From 439315de029f60406598202eb225f2369ec19f22 Mon Sep 17 00:00:00 2001
From: joostdecock <joost@joost.at>
Date: Sat, 24 May 2025 13:11:06 +0200
Subject: [PATCH] [react] feat: Added docs for components/Layout

---
 packages/react/components/Layout/index.mjs    | 62 ++++++++++++-------
 packages/react/mkdocs.sh                      |  1 +
 .../react/components/keyval/readme.mdx        |  2 +-
 .../react/components/layout/_examples.js      | 38 ++++++++++++
 .../react/components/layout/readme.mdx        | 51 ++++++++++++++-
 5 files changed, 126 insertions(+), 28 deletions(-)
 create mode 100644 sites/dev/docs/reference/packages/react/components/layout/_examples.js

diff --git a/packages/react/components/Layout/index.mjs b/packages/react/components/Layout/index.mjs
index 155e41597a6..56ceb69159e 100644
--- a/packages/react/components/Layout/index.mjs
+++ b/packages/react/components/Layout/index.mjs
@@ -2,15 +2,17 @@ import React from 'react'
 import { Breadcrumbs } from '@freesewing/react/components/Breadcrumbs'
 import { Link as DefaultLink } from '@freesewing/react/components/Link'
 
-/*
+/**
  * This is the default layout, including title and breadcrumbs
  *
- * @param {object} props - All React props
- * @param {array} props.children - The content to go in the layout
- * @param {array} props.crumbs - Data for the breadcrumbs
+ * @component
+ * @param {object} props - All component props
+ * @param {function} [props.Link = false] - An optional framework specific Link component
+ * @param {JSX.Element} [props.children = []] - The component children to render inside the layout
+ * @param {array} [props.crumbs = []] - Data for the breadcrumbs, see Breadcrumbs
  * @param {string} props.description - The page description
- * @param {function} props.Link - An optional framework specific Link component
  * @param {string} props.title - The page title
+ * @returns {JSX.Element}
  */
 export const Layout = ({ children = [], crumbs = [], description, Link = false, title }) => {
   if (!Link) Link = DefaultLink
@@ -26,11 +28,13 @@ export const Layout = ({ children = [], crumbs = [], description, Link = false,
   )
 }
 
-/*
+/**
  * This is the base layout
  *
- * @param {object} props - All React props
- * @param {array} props.children - The content to go in the layout
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} [props.children = []] - The component children to render inside the layout
+ * @returns {JSX.Element}
  */
 export const BaseLayout = ({ children }) => (
   <div className="tw:flex tw:flex-row tw:items-start tw:w-full tw:justify-between tw:2xl:px-36 tw:xl:px-12 tw:px-4 tw:gap-0 tw:lg:gap-4 tw:xl:gap-8 3xl:tw:gap-12">
@@ -38,11 +42,13 @@ export const BaseLayout = ({ children }) => (
   </div>
 )
 
-/*
+/**
  * The left column of the base layout
  *
- * @param {object} props - All React props
- * @param {array} props.children - The content to go in the layout
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} [props.children = []] - The component children to render inside the layout
+ * @returns {JSX.Element}
  */
 export const BaseLayoutLeft = ({ children = [] }) => (
   <div className="tw:max-w-96 tw:w-1/4 tw:hidden tw:lg:block tw:shrink-0 tw:my-8 tw:sticky tw:top-4 tw:max-h-screen tw:overflow-scroll">
@@ -50,11 +56,13 @@ export const BaseLayoutLeft = ({ children = [] }) => (
   </div>
 )
 
-/*
+/**
  * The right column of the base layout
  *
- * @param {object} props - All React props
- * @param {array} props.children - The content to go in the layout
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} [props.children = []] - The component children to render inside the layout
+ * @returns {JSX.Element}
  */
 export const BaseLayoutRight = ({ children = [] }) => (
   <div className="tw:max-w-96 tw:w-1/4 tw:hidden tw:xl:block tw:my-8 tw:sticky tw:top-2">
@@ -62,12 +70,14 @@ export const BaseLayoutRight = ({ children = [] }) => (
   </div>
 )
 
-/*
+/**
  * The main column for prose (text like docs and so on)
  *
- * @param {object} props - All React props
- * @param {array} props.children - The content to go in the layout
- * @param {array} props.wide - Whether or not to use the wide view
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} [props.children = []] - The component children to render inside the layout
+ * @param {boolean} [props.wide  false] - Set this to true to render a full-width prose layout
+ * @returns {JSX.Element}
  */
 export const BaseLayoutProse = ({ children = [], wide = false }) => (
   <div className={`tw:grow tw:w-full tw:m-auto tw:max-w-${wide ? 'full' : 'prose'} tw:my-8`}>
@@ -75,21 +85,25 @@ export const BaseLayoutProse = ({ children = [], wide = false }) => (
   </div>
 )
 
-/*
+/**
  * The central column for wide content (no max-width)
  *
- * @param {object} props - All React props
- * @param {array} props.children - The content to go in the layout
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} [props.children = []] - The component children to render inside the layout
+ * @returns {JSX.Element}
  */
 export const BaseLayoutWide = ({ children = [] }) => (
   <div className="tw:grow tw:w-full tw:m-auto tw:my-8 tw:grow">{children}</div>
 )
 
-/*
+/**
  * A layout for pages that do their own title/layout, like the sign in page
  *
- * @param {object} props - All React props
- * @param {array} props.children - The content to go in the layout
+ * @component
+ * @param {object} props - All component props
+ * @param {JSX.Element} [props.children = []] - The component children to render inside the layout
+ * @returns {JSX.Element}
  */
 export const NoTitleLayout = ({ children }) => {
   return (
diff --git a/packages/react/mkdocs.sh b/packages/react/mkdocs.sh
index 0ce2104fef3..0f7e7c37376 100755
--- a/packages/react/mkdocs.sh
+++ b/packages/react/mkdocs.sh
@@ -17,3 +17,4 @@ jsdoc -c jsdoc.json components/Icon/* > ../../sites/dev/prebuild/jsdoc/react/com
 jsdoc -c jsdoc.json components/Input/* > ../../sites/dev/prebuild/jsdoc/react/components/input.json
 jsdoc -c jsdoc.json components/Json/* > ../../sites/dev/prebuild/jsdoc/react/components/json.json
 jsdoc -c jsdoc.json components/KeyVal/* > ../../sites/dev/prebuild/jsdoc/react/components/keyval.json
+jsdoc -c jsdoc.json components/Layout/* > ../../sites/dev/prebuild/jsdoc/react/components/layout.json
diff --git a/sites/dev/docs/reference/packages/react/components/keyval/readme.mdx b/sites/dev/docs/reference/packages/react/components/keyval/readme.mdx
index 207c02c4705..e3af22766f8 100644
--- a/sites/dev/docs/reference/packages/react/components/keyval/readme.mdx
+++ b/sites/dev/docs/reference/packages/react/components/keyval/readme.mdx
@@ -9,7 +9,7 @@ import { KeyValExample } from './_examples.js'
 
 <DocusaurusDoc>
 
-The __KeyVal component family provides the following components:
+The __KeyVal__ component family provides the following components:
 
 - [KeyVal](#keyval)
 
diff --git a/sites/dev/docs/reference/packages/react/components/layout/_examples.js b/sites/dev/docs/reference/packages/react/components/layout/_examples.js
new file mode 100644
index 00000000000..b24bb148705
--- /dev/null
+++ b/sites/dev/docs/reference/packages/react/components/layout/_examples.js
@@ -0,0 +1,38 @@
+import React from 'react'
+import { Markdown } from '@freesewing/react/components/Markdown'
+import {
+  Layout,
+  BaseLayout,
+  BaseLayoutLeft,
+  BaseLayoutRight,
+  BaseLayoutProse,
+  BaseLayoutWide,
+  NoTitleLayout
+} from '@freesewing/react/components/Layout'
+
+export const LayoutExample = () => (
+  <Layout description="This is the description" title="This is the title">
+    <Content />
+  </Layout>
+)
+
+export const BaseLayoutExample = () => <BaseLayout><Content /></BaseLayout>
+export const BaseLayoutLeftExample = () => <BaseLayoutLeft><Content /></BaseLayoutLeft>
+export const BaseLayoutRightExample = () => <BaseLayoutRight><Content /></BaseLayoutRight>
+export const BaseLayoutProseExample = () => <BaseLayoutProse><Content /></BaseLayoutProse>
+export const BaseLayoutWideExample = () => <BaseLayoutWide><Content /></BaseLayoutWide>
+export const NoTitleLayoutExample = () => <NoTitleLayout><Content /></NoTitleLayout>
+
+
+
+const Content = () => <Markdown>{md}</Markdown>
+
+const md = `
+This is \`props.children\`.
+
+## Some more content
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+`
diff --git a/sites/dev/docs/reference/packages/react/components/layout/readme.mdx b/sites/dev/docs/reference/packages/react/components/layout/readme.mdx
index b1bc8f46f29..5b58a2dd0ba 100644
--- a/sites/dev/docs/reference/packages/react/components/layout/readme.mdx
+++ b/sites/dev/docs/reference/packages/react/components/layout/readme.mdx
@@ -2,6 +2,51 @@
 title: Layout
 ---
 
-:::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.layout.mjs'
+import {
+  BaseLayoutExample,
+  BaseLayoutLeftExample,
+  BaseLayoutProseExample,
+  BaseLayoutRightExample,
+  BaseLayoutWideExample,
+  LayoutExample,
+  NoTitleLayoutExample,
+} from './_examples.js'
+
+
+<DocusaurusDoc>
+
+The __Layout__ component family provides the following components:
+
+- [BaseLayout](#baselayout)
+- [BaseLayoutLeft](#baselayoutleft)
+- [BaseLayoutProse](#baselayoutprose)
+- [BaseLayoutRight](#baselayoutright)
+- [BaseLayoutWide](#baselayoutwide)
+- [Layout](#layout)
+- [NoTitleLayout](#notitlelayout)
+
+## BaseLayout
+<ComponentDocs docs={jsdoc.jsdocBaseLayout} example={BaseLayoutExample} />
+
+## BaseLayoutLeft
+<ComponentDocs docs={jsdoc.jsdocBaseLayoutLeft} example={BaseLayoutLeftExample} />
+
+## BaseLayoutProse
+<ComponentDocs docs={jsdoc.jsdocBaseLayoutProse} example={BaseLayoutProseExample} />
+
+## BaseLayoutRight
+<ComponentDocs docs={jsdoc.jsdocBaseLayoutRight} example={BaseLayoutRightExample} />
+
+## BaseLayoutWide
+<ComponentDocs docs={jsdoc.jsdocBaseLayoutWide} example={BaseLayoutWideExample} />
+
+## Layout
+<ComponentDocs docs={jsdoc.jsdocLayout} example={LayoutExample} />
+
+## NoTitleLayout
+<ComponentDocs docs={jsdoc.jsdocNoTitleLayout} example={NoTitleLayoutExample} />
+
+</DocusaurusDoc>