From 7093dd3d36778ead1722cbd9f7b96ef3336bdf50 Mon Sep 17 00:00:00 2001 From: joostdecock Date: Thu, 29 May 2025 11:49:04 +0200 Subject: [PATCH] [react] feat: Added docs for components/Role --- packages/react/components/Role/index.mjs | 31 ++++++++++++++++--- packages/react/mkdocs.sh | 1 + .../react/components/profile/readme.mdx | 2 +- .../react/components/role/_examples.js | 15 +++++++++ .../packages/react/components/role/readme.mdx | 28 +++++++++++++++-- 5 files changed, 69 insertions(+), 8 deletions(-) create mode 100644 sites/dev/docs/reference/packages/react/components/role/_examples.js diff --git a/packages/react/components/Role/index.mjs b/packages/react/components/Role/index.mjs index 25dc3e17967..e6d0689b8e6 100644 --- a/packages/react/components/Role/index.mjs +++ b/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() diff --git a/packages/react/mkdocs.sh b/packages/react/mkdocs.sh index 6c672bf2289..3a5b81b06d8 100755 --- a/packages/react/mkdocs.sh +++ b/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 diff --git a/sites/dev/docs/reference/packages/react/components/profile/readme.mdx b/sites/dev/docs/reference/packages/react/components/profile/readme.mdx index 1c7f6c8b362..fa7105a1bf8 100644 --- a/sites/dev/docs/reference/packages/react/components/profile/readme.mdx +++ b/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) diff --git a/sites/dev/docs/reference/packages/react/components/role/_examples.js b/sites/dev/docs/reference/packages/react/components/role/_examples.js new file mode 100644 index 00000000000..4cc6c532eff --- /dev/null +++ b/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 = () => ( + +

Wow, you are an admin! This content is admin-only.

+ +) + +export const UserVisitorContentExample = () => ( + You are a user. This content is only for users.

} + visitorContent={

You are a visitor. This content is only for visitors.

} + /> +) diff --git a/sites/dev/docs/reference/packages/react/components/role/readme.mdx b/sites/dev/docs/reference/packages/react/components/role/readme.mdx index 1f3bd87907d..33ae10fc382 100644 --- a/sites/dev/docs/reference/packages/react/components/role/readme.mdx +++ b/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' + + + +- [Components](#components) + +## Components + +The **Role** component family provides the following components: + +- [RoleBlock](#roleblock) +- [UserVisitorContent](#uservisitorcontent) + +### RoleBlock + + + +### UserVisitorContent + + + +