[react] feat: Added docs for components/Role

packages/react/components/Role/index.mjs

@@ -161,10 +161,22 @@ const ConsentLacking = ({ banner, refresh }) => {
   )
 }
 
-export const RoleBlock = ({ children, user = false, Link = false }) => {
+/**
+ * A component to block access based on a FreeSewing role.
+ *
+ * Note that in an SPA, blocking access to the user is merely a matter of providing a
+ * more intuitive UI. That actual access control is implemented on the backend.
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {React.FC} [props.Link = false] - An optional framework-specific Link component
+ * @param {string} [props.role = admin] - The role required to access the content. Typically admin or user.
+ * @param {JSX.Element} props.children - The component children, will be rendered if props.js is not set
+ * @returns {JSX.Element}
+ */
+export const RoleBlock = ({ children, role = "admin", Link = false }) => {
   if (!Link) Link = DefaultLink
-  let requiredRole = 'admin'
-  if (user) requiredRole = user
+  const requiredRole = role
 
   const { account, setAccount, token, admin, stopImpersonating, signOut } = useAccount()
   const backend = useBackend()
@@ -198,7 +210,6 @@ export const RoleBlock = ({ children, user = false, Link = false }) => {
           })
         } else if (status === 451) setError('consentLacking')
         else {
-          console.log({ status, data })
           if (data?.error?.error) setError(data.error.error)
           else signOut()
         }
@@ -246,6 +257,18 @@ export const RoleBlock = ({ children, user = false, Link = false }) => {
   return children
 }
 
+/**
+ * A component to display different content to users or visitors.
+ *
+ * This is a convenience component to not have to check
+ * for a user account is many different places.
+ *
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} userContent - The content to show to users
+ * @param {JSX.Element} visitorContent - The content to show to visitors (not-logged in)
+ * @returns {JSX.Element}
+ */
 export const UserVisitorContent = ({ userContent = null, visitorContent = null }) => {
   const { account, setAccount, token } = useAccount()
   const backend = useBackend()

packages/react/mkdocs.sh

@@ -31,3 +31,4 @@ jsdoc -c jsdoc.json components/Patrons/* > ../../sites/dev/prebuild/jsdoc/react/
 jsdoc -c jsdoc.json components/Pattern/* > ../../sites/dev/prebuild/jsdoc/react/components/pattern.json
 jsdoc -c jsdoc.json components/Popout/* > ../../sites/dev/prebuild/jsdoc/react/components/popout.json
 jsdoc -c jsdoc.json components/Profile/* > ../../sites/dev/prebuild/jsdoc/react/components/profile.json
+jsdoc -c jsdoc.json components/Role/* > ../../sites/dev/prebuild/jsdoc/react/components/role.json

sites/dev/docs/reference/packages/react/components/profile/readme.mdx

@@ -13,7 +13,7 @@ import { AvatarExample, OwnProfileExample, UserProfileExample } from './_example
 
 ## Components
 
-The **Json** component family provides the following components:
+The **Profile** component family provides the following components:
 
 - [Avatar](#avatar)
 - [OwnProfile](#ownprofile)

sites/dev/docs/reference/packages/react/components/role/_examples.js

@@ -0,0 +1,15 @@
+import React from 'react'
+import { RoleBlock, UserVisitorContent } from '@freesewing/react/components/Role'
+
+export const RoleBlockExample = () => (
+  <RoleBlock role="admin">
+    <p>Wow, you are an admin! This content is admin-only.</p>
+  </RoleBlock>
+)
+
+export const UserVisitorContentExample = () => (
+  <UserVisitorContent
+    userContent={<p>You are a user. This content is only for users.</p>}
+    visitorContent={<p>You are a visitor. This content is only for visitors.</p>}
+  />
+)

sites/dev/docs/reference/packages/react/components/role/readme.mdx

@@ -2,6 +2,28 @@
 title: Role
 ---
 
-:::note
-This page is yet to be created
-:::
+import { DocusaurusDoc } from '@freesewing/react/components/Docusaurus'
+import { ComponentDocs } from '@site/src/components/component-docs.js'
+import * as jsdoc from '@site/prebuild/jsdoc/components.role.mjs'
+import { RoleBlockExample, UserVisitorContentExample } from './_examples.js'
+
+<DocusaurusDoc>
+
+- [Components](#components)
+
+## Components
+
+The **Role** component family provides the following components:
+
+- [RoleBlock](#roleblock)
+- [UserVisitorContent](#uservisitorcontent)
+
+### RoleBlock
+
+<ComponentDocs docs={jsdoc.jsdocRoleBlock} example={RoleBlockExample} />
+
+### UserVisitorContent
+
+<ComponentDocs docs={jsdoc.jsdocUserVisitorContent} example={UserVisitorContentExample} />
+
+</DocusaurusDoc>