Merge pull request #3 from imjulianeral/docs/update&add-RBAC

fix(docs): docs added for RBAC and userRole props

README.md

@@ -1,6 +1,6 @@
 # NextShield
 
-😉 Component designed to protect the routes of your app. You must use this component as a wrapper in your `_app.tsx` file.
+😉 The shield that every Next.js project needs.
 
 ```tsx
 import { Loading } from '@components/routes/loading'
@@ -21,7 +21,7 @@ const MyApp: NextPage<AppProps> = ({ Component, pageProps }) => {
       privateRoutes={privateRoutes}
       publicRoutes={publicRoutes}
       hybridRoutes={hybridRoutes}
-      LoadingComponent={Loading}
+      LoadingComponent={<Loading />}
     >
       <Component {...pageProps} />
     </NextShield>
@@ -117,7 +117,7 @@ return (
 
 ### accessRoute
 
-🚧 Private route where your user is going to access after login.
+🚧 Route where your user is going to access after login, must be a private route.
 
 ```tsx
 ...
@@ -160,7 +160,7 @@ const hybridRoutes = ['/support', '/pricing', '/products/[slug]']
 
 ### LoadingComponent
 
-Functional Component which is going to appear when `isLoading` equals to `true`
+🌀 React Component which is going to appear when `isLoading` equals to `true`.
 
 `Loading.tsx`:
 
@@ -181,11 +181,57 @@ const MyApp: NextPage<AppProps> = ({ Component, pageProps }) => {
   return (
     <NextShield
       ...
-      LoadingComponent={Loading}
+      LoadingComponent={<Loading />}
       ...
     >
       <Component {...pageProps} />
     </NextShield>
   )
 }
 ```
+
+### RBAC
+
+🔏 🔐 🔒 Role Based Access Control.
+
+You can define an object literal to specify which roles are supported and which routes the role have access.
+
+You must define the accessRoute on each Role.
+
+```tsx
+return (
+  <NextShield
+    ...
+    accessRoute="/profile"
+    RBAC={{
+      ADMIN: ['/profile', '/control-panel'],
+      EMPLOYEE: ['/profile', '/dashboard'],
+    }}
+    ...
+  >
+    <Component {...pageProps} />
+  </NextShield>
+)
+```
+
+### userRole
+
+🎭 The auth user role.
+
+- This value must be provided when using RBAC.
+- Should by provided by the session or state of the application.
+- Must match with the roles defined on RBAC
+
+```tsx
+const { user } = useAuth()
+
+return (
+  <NextShield
+    ...
+    userRole={user.role} // "ADMIN"
+    ...
+  >
+    <Component {...pageProps} />
+  </NextShield>
+)
+```

package.json

@@ -30,6 +30,7 @@
     }
   },
   "name": "next-shield",
+  "description": "The shield that every Next.js project needs.",
   "author": "Jorge Acero",
   "module": "dist/next-shield.esm.js",
   "size-limit": [

src/components/NextShield.tsx

@@ -4,7 +4,7 @@ import { NextShieldProps } from '../types/props'
 import { verifyPath } from '../libs/routes'
 
 /**
- * 😉 The router that every Next.js project needs
+ * 😉 The shield that every Next.js project needs
  *
  * @typeParam NextShieldProps - {@link NextShieldProps | see here}
  * @returns NextShield Component
@@ -29,7 +29,7 @@ import { verifyPath } from '../libs/routes'
  *      privateRoutes={privateRoutes}
  *      publicRoutes={publicRoutes}
  *      hybridRoutes={hybridRoutes}
- *      LoadingComponent={Loading}
+ *      LoadingComponent={<Loading />}
  *    >
  *      <Component {...pageProps} />
  *    </NextShield>

src/types/props.ts

@@ -1,7 +1,6 @@
 import type { ReactNode } from "react";
 import type { NextRouter } from 'next/router'
 
-
 export interface NextShieldProps<
   PrivateRoutesList extends string[],
   PublicRoutesList extends string[]
@@ -93,7 +92,7 @@ export interface NextShieldProps<
    */
   loginRoute: PublicRoutesList[number]
   /**
-   * 🚧 Private route where your user is going to access after login.
+   * 🚧 Route where your user is going to access after login, must be a private route.
    *
    * @example
    * ```tsx
@@ -138,7 +137,7 @@ export interface NextShieldProps<
    */
   hybridRoutes?: string[]
   /**
-   * Functional Component which is going to appear when `isLoading` equals to `true`
+   * 🌀 React Component which is going to appear when `isLoading` equals to `true`.
    *
    * @example
    * ```tsx
@@ -156,7 +155,7 @@ export interface NextShieldProps<
    *   return (
    *     <NextShield
    *       ...
-   *       LoadingComponent={Loading}
+   *       LoadingComponent={<Loading />}
    *       ...
    *     >
    *       <Component {...pageProps} />
@@ -166,8 +165,57 @@ export interface NextShieldProps<
    * ```
    */
   LoadingComponent: ReactNode
+
+  /**
+   * 🔏 🔐 🔒 Role Based Access Control.
+   * 
+   * @remarks
+   * You can define an object literal to specify which roles are supported and which routes the role have access.
+   * 
+   * You must define the accessRoute on each Role
+   * 
+   * @example
+   * ```tsx
+   *   return (
+   *     <NextShield
+   *       ...
+   *       accessRoute="/profile"
+   *       RBAC={{
+   *          ADMIN: ['/profile', '/control-panel'],
+   *          EMPLOYEE: ['/profile', '/dashboard'], 
+   *       }}
+   *       ...
+   *     >
+   *       <Component {...pageProps} />
+   *     </NextShield>
+   *   )
+   * ```
+   */
   RBAC?: {
     [index: string]: PrivateRoutesList[number][]
   }
+  /**
+   * 🎭 The auth user role.
+   * 
+   * @remarks
+   * - This value must be provided when using RBAC.
+   * - Should by provided by the session or state of the application.
+   * - Must match with the roles defined on RBAC
+   * 
+   * @example
+   * ```tsx
+   *   const { user } = useAuth()
+   * 
+   *   return (
+   *     <NextShield
+   *       ...
+   *       userRole={user.role} // "ADMIN"
+   *       ...
+   *     >
+   *       <Component {...pageProps} />
+   *     </NextShield>
+   *   )
+   * ```
+   */
   userRole?: string
 }