@pnx-mixtape/mxds 0.0.21 → 0.0.23

package/src/Layout/Section/Background.stories.ts

@@ -1,14 +1,9 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
 import Component from "./twig/section-background.twig"
 import "./section.css"
-import {
-  HeadingTypes,
-  Section as SectionType,
-  SectionModifiers,
-  SectionTypes,
-  Image as ImageType,
-} from "@pnx-mixtape/ids-shape"
-import { BackgroundStyles, Icons } from "../../enums"
+import { Section as SectionType, Image as ImageType } from "@pnx-mixtape/ids-shape"
+import { BackgroundStyles } from "../../enums"
+import Section from "./Section.stories"
 
 // Deps.
 import Heading from "../../Atom/Heading/heading.twig"
@@ -20,48 +15,28 @@ type MxSectionType = SectionType & {
   image?: ImageType
 }
 
+/**
+ * Section can have a background image.
+ */
 const meta: Meta<MxSectionType> = {
   tags: ["autodocs"],
   component: Component,
   args: {
+    ...Section.args,
     image: Image({
       src: "https://picsum.photos/id/56/1642/560?grayscale",
       alt: "Blurry bubbles",
     }),
-    modifiers: [SectionModifiers.XL],
-    as: SectionTypes.DIV,
-    container: true,
-    title: Heading({
-      title: "Section name",
-      as: HeadingTypes.TWO,
-    }),
-    content:
-      '<p class="mx-text--lede">A short description to help explain enough about the subject matter to encourage visitors to learn more.</p>',
-    link: Link({
-      href: "#",
-      title: "See more content",
-      more: true,
-      iconEnd: Icon({
-        icon: Icons.ARROW_RIGHT,
-      }),
-    }),
   },
   argTypes: {
-    modifiers: {
-      options: Object.values(SectionModifiers),
-      control: "multi-select",
-    },
-    background: {
-      options: Object.values(BackgroundStyles),
-      control: "select",
+    ...Section.argTypes,
+    image: {
+      description: "[Image](/?path=/docs/atom-image--docs) component.",
+      control: "text",
+      table: {
+        type: { summary: "Image" },
+      },
     },
-    as: { options: Object.values(SectionTypes), control: "select" },
-    container: { control: "boolean" },
-    // @ts-expect-error The controls follow the shape
-    "title.title": { control: "text" },
-    "title.as": { options: Object.values(HeadingTypes), control: "select" },
-    "link.href": { control: "text" },
-    "link.title": { control: "text" },
   },
 }
 

package/src/Layout/Section/Breakouts.stories.ts

@@ -3,6 +3,9 @@ import Component from "./twig/sections-breakout.twig"
 import "./section.css"
 import { Section as SectionType } from "@pnx-mixtape/ids-shape"
 
+/**
+ * Example of section breakouts (to be added to main section)
+ */
 const meta: Meta<SectionType> = {
   tags: ["autodocs"],
   component: Component,

package/src/Layout/Section/Flow.stories.ts

@@ -3,6 +3,9 @@ import Component from "./twig/sections-flow.twig"
 import "./section.css"
 import { Section as SectionType } from "@pnx-mixtape/ids-shape"
 
+/**
+ * Example of section flow (to be added to main section)
+ */
 const meta: Meta<SectionType> = {
   tags: ["autodocs"],
   component: Component,

package/src/Layout/Section/Section.stories.ts

@@ -19,13 +19,12 @@ const meta: Meta<SectionType> = {
     modifiers: [SectionModifiers.XL],
     as: SectionTypes.DIV,
     container: true,
+    content:
+      '<p class="mx-text--lede">A short description to help explain enough about the subject matter to encourage visitors to learn more.</p>',
     title: Heading({
       title: "Section name",
       as: HeadingTypes.TWO,
     }),
-    content: [
-      '<p class="mx-text--lede">A short description to help explain enough about the subject matter to encourage visitors to learn more.</p>',
-    ],
     link: Link({
       href: "#",
       title: "See more content",
@@ -37,24 +36,107 @@ const meta: Meta<SectionType> = {
   },
   argTypes: {
     modifiers: {
+      description: "Set the vertical spacing.",
       options: Object.values(SectionModifiers),
       control: "multi-select",
+      table: {
+        defaultValue: { summary: SectionModifiers.XL },
+        type: { summary: "enum" },
+      },
     },
     background: {
+      description: "Change the background colour.",
       options: Object.values(BackgroundStyles),
       control: "select",
+      table: {
+        type: { summary: "enum" },
+      },
+    },
+    as: {
+      description: "Change the wrapper html element.",
+      options: Object.values(SectionTypes),
+      control: "select",
+      table: {
+        type: { summary: "enum" },
+        defaultValue: { summary: SectionTypes.DIV },
+      },
+    },
+    container: {
+      description: "Create a container context inside the section.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    title: {
+      description: "An optional [Heading](/?path=/docs/atom-heading--docs) component.",
+      control: "text",
+      table: {
+        type: { summary: "Heading" },
+        subcategory: "Section content",
+      },
+    },
+    content: {
+      description: "Content (can be anything).",
+      control: "text",
+      type: {
+        name: "string",
+        required: true,
+      },
+      table: {
+        type: { summary: "WysiwygText | HTMLElement" },
+        subcategory: "Section content",
+      },
+    },
+    link: {
+      description: "Optional content [Link](/?path=/docs/atom-link--docs).",
+      control: "text",
+      table: {
+        type: { summary: "Link" },
+        subcategory: "Section content",
+      },
     },
-    as: { options: Object.values(SectionTypes), control: "select" },
-    container: { control: "boolean" },
-    // @ts-expect-error The controls follow the shape
-    "title.title": { control: "text" },
-    "title.as": { options: Object.values(HeadingTypes), control: "select" },
-    "link.href": { control: "text" },
-    "link.title": { control: "text" },
   },
 }
 
 export default meta
-type Story = StoryObj<typeof meta>
+type Story = StoryObj<SectionType>
 
 export const Section: Story = {}
+
+/**
+ * Sections can have different top/bottom modifiers.
+ */
+export const Modifiers: Story = {
+  args: {
+    modifiers: [SectionModifiers.TOP_S, SectionModifiers.BOTTOM_XL],
+  },
+}
+
+/**
+ * Heading and link are optional.
+ */
+export const Header: Story = {
+  args: {
+    title: null,
+    link: null,
+  },
+}
+
+/**
+ * Background colours span the full width.
+ */
+export const Background: Story = {
+  args: {
+    background: BackgroundStyles.PRIMARY,
+  },
+}
+
+/**
+ * With the exception of the box.
+ */
+export const Box: Story = {
+  args: {
+    background: BackgroundStyles.BOX,
+  },
+}

package/src/Layout/Section/Section.tsx

@@ -1,9 +1,4 @@
-import {
-  JSX,
-  ComponentPropsWithoutRef,
-  PropsWithChildren,
-  useMemo,
-} from "react"
+import { JSX, ComponentPropsWithoutRef, PropsWithChildren, useMemo } from "react"
 import classNames from "classnames"
 import { PageWidths, SectionFlow, SectionStyles } from "../../enums"
 import { SectionTypes } from "@pnx-mixtape/ids-shape"
@@ -13,11 +8,7 @@ type InnerTagProps = ComponentPropsWithoutRef<"div"> &
     condition: boolean
   }
 
-const InnerTag = ({
-  condition,
-  children,
-  ...props
-}: InnerTagProps): JSX.Element =>
+const InnerTag = ({ condition, children, ...props }: InnerTagProps): JSX.Element =>
   condition ? <div {...props}>{children}</div> : <>{children}</>
 
 type SectionProps = PropsWithChildren & {
@@ -46,8 +37,7 @@ const Section = ({
   const Tag: JSX.ElementType = `${as}` as unknown as JSX.ElementType
   const sizeClasses = useMemo<string[]>(() => {
     if (!sizes) return []
-    if (Array.isArray(sizes))
-      return sizes.map((size: SectionStyles) => `mx-section--${size}`)
+    if (Array.isArray(sizes)) return sizes.map((size: SectionStyles) => `mx-section--${size}`)
     return [`mx-section--${sizes}`]
   }, [sizes])
 

package/src/Layout/Section/SectionGrid.tsx

@@ -34,8 +34,7 @@ const SectionGrid = ({
 
   const sizeClasses = useMemo<string[]>(() => {
     if (!sizes) return []
-    if (Array.isArray(sizes))
-      return sizes.map((size: SectionStyles) => `mx-section--${size}`)
+    if (Array.isArray(sizes)) return sizes.map((size: SectionStyles) => `mx-section--${size}`)
     return [`mx-section--${sizes}`]
   }, [sizes])
 
@@ -50,13 +49,7 @@ const SectionGrid = ({
       })}
       {...props}
     >
-      <Grid
-        wrapper
-        container={container}
-        as={gridAs}
-        cols={cols}
-        className={innerClassName}
-      >
+      <Grid wrapper container={container} as={gridAs} cols={cols} className={innerClassName}>
         {children}
       </Grid>
     </Tag>

package/src/Layout/Section/__snapshots__/Background.stories.ts.snap

@@ -1,8 +1,8 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Layout/Section/Background Background smoke-test 1`] = `
 <div class="mx-page default">
-  <div class="mx-section mx-page ">
+  <div class="mx-section mx-page">
     <figure class="mx-background--image mx-section--full"
             aria-hidden="true"
     >
@@ -23,7 +23,7 @@ exports[`Layout/Section/Background Background smoke-test 1`] = `
           <span>
             See more content
           </span>
-          <span class="mx-icon mx-icon--arrow-right ">
+          <span class="mx-icon mx-icon--arrow-right">
           </span>
         </a>
       </div>
@@ -58,7 +58,7 @@ exports[`Layout/Section/Background Dark smoke-test 1`] = `
           <span>
             See more content
           </span>
-          <span class="mx-icon mx-icon--arrow-right ">
+          <span class="mx-icon mx-icon--arrow-right">
           </span>
         </a>
       </div>

package/src/Layout/Section/__snapshots__/Breakouts.stories.ts.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Layout/Section/Breakouts Breakouts smoke-test 1`] = `
 <div class="mx-page default">

package/src/Layout/Section/__snapshots__/Flow.stories.ts.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Layout/Section/Flow Flow smoke-test 1`] = `
 <div class="mx-page default">

package/src/Layout/Section/__snapshots__/Section.stories.ts.snap

@@ -1,8 +1,98 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`Layout/Section Background smoke-test 1`] = `
+<div class="mx-page default">
+  <div class="mx-background--primary mx-section--xl">
+    <div class="mx-container">
+      <div class="mx-section__header">
+        <h2>
+          Section name
+        </h2>
+        <a class="mx-link--more"
+           href="#"
+        >
+          <span>
+            See more content
+          </span>
+          <span class="mx-icon mx-icon--arrow-right">
+          </span>
+        </a>
+      </div>
+      <p class="mx-text--lede">
+        A short description to help explain enough about the subject matter to encourage visitors to learn more.
+      </p>
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Layout/Section Box smoke-test 1`] = `
+<div class="mx-page default">
+  <div class="mx-background--box mx-section--xl">
+    <div class="mx-container">
+      <div class="mx-section__header">
+        <h2>
+          Section name
+        </h2>
+        <a class="mx-link--more"
+           href="#"
+        >
+          <span>
+            See more content
+          </span>
+          <span class="mx-icon mx-icon--arrow-right">
+          </span>
+        </a>
+      </div>
+      <p class="mx-text--lede">
+        A short description to help explain enough about the subject matter to encourage visitors to learn more.
+      </p>
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Layout/Section Header smoke-test 1`] = `
+<div class="mx-page default">
+  <div class="mx-section--xl">
+    <div class="mx-container">
+      <p class="mx-text--lede">
+        A short description to help explain enough about the subject matter to encourage visitors to learn more.
+      </p>
+    </div>
+  </div>
+</div>
+`;
+
+exports[`Layout/Section Modifiers smoke-test 1`] = `
+<div class="mx-page default">
+  <div class="mx-section--top-s mx-section--bottom-xl">
+    <div class="mx-container">
+      <div class="mx-section__header">
+        <h2>
+          Section name
+        </h2>
+        <a class="mx-link--more"
+           href="#"
+        >
+          <span>
+            See more content
+          </span>
+          <span class="mx-icon mx-icon--arrow-right">
+          </span>
+        </a>
+      </div>
+      <p class="mx-text--lede">
+        A short description to help explain enough about the subject matter to encourage visitors to learn more.
+      </p>
+    </div>
+  </div>
+</div>
+`;
 
 exports[`Layout/Section Section smoke-test 1`] = `
 <div class="mx-page default">
-  <div class=" mx-section--xl">
+  <div class="mx-section--xl">
     <div class="mx-container">
       <div class="mx-section__header">
         <h2>
@@ -14,7 +104,7 @@ exports[`Layout/Section Section smoke-test 1`] = `
           <span>
             See more content
           </span>
-          <span class="mx-icon mx-icon--arrow-right ">
+          <span class="mx-icon mx-icon--arrow-right">
           </span>
         </a>
       </div>

package/src/Layout/Section/__snapshots__/Section.stories.tsx.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Layout/Section Default smoke-test 1`] = `
 <div class="mx-page undefined">

package/src/Layout/Section/__snapshots__/SectionGrid.stories.tsx.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Layout/Section/SectionGrid List smoke-test 1`] = `
 <div class="mx-page undefined">

package/src/Layout/Section/section.css

@@ -99,8 +99,7 @@
     /* :first-in-island-of-class */
 
     &:is(
-      :not([class*="mx-background"])
-        + .mx-section--group[class*="mx-background"],
+      :not([class*="mx-background"]) + .mx-section--group[class*="mx-background"],
       :not(.mx-section--group + .mx-section--group)
     ) {
       padding-block-start: var(--group-spacing);
@@ -109,9 +108,7 @@
     /* :last-in-island-of-class */
 
     &:is(
-      :not([class*="mx-background"]):has(
-        + .mx-section--group[class*="mx-background"]
-      ),
+      :not([class*="mx-background"]):has(+ .mx-section--group[class*="mx-background"]),
       :not(:has(+ .mx-section--group))
     ) {
       padding-block-end: var(--group-spacing);

package/src/Layout/Section/section.twig

@@ -17,9 +17,7 @@
       {{ link }}
       </div>
     {% endif %}
-    {% for item in content %}
-      {{ item }}
-    {% endfor %}
+    {{ content }}
   {% if container %}
     </div>
   {% endif %}

package/src/Layout/Sidebar/Sidebar.stories.ts

@@ -10,17 +10,47 @@ type SidebarArgs = {
   sidebarContent?: string | HTMLElement
 }
 
+/**
+ * A CSS Grid sidebar layout.
+ */
 const meta: Meta<SidebarArgs> = {
   tags: ["autodocs"],
   component: Component,
-  argTypes: {
-    order: { options: Object.values(SidebarOrder), control: "select" },
-    before: { control: "boolean" },
-  },
   args: {
     content: "Main content",
     sidebarContent: "Sidebar content",
   },
+  argTypes: {
+    order: {
+      description: "Change the visual position of the sidebar.",
+      options: Object.values(SidebarOrder),
+      control: "radio",
+      table: {
+        type: { summary: "enum" },
+      },
+    },
+    before: {
+      description: "Change the semantic (html) position of the sidebar.",
+      type: "boolean",
+      table: {
+        defaultValue: { summary: "false" },
+      },
+    },
+    content: {
+      description: "The main column content",
+      table: {
+        type: { summary: "String | WysiwygText | HTMLElement" },
+        subcategory: "Content",
+      },
+    },
+    sidebarContent: {
+      description: "The side column content",
+      table: {
+        type: { summary: "String | WysiwygText | HTMLElement" },
+        subcategory: "Content",
+      },
+    },
+  },
 }
 
 export default meta
@@ -28,24 +58,36 @@ type Story = StoryObj<SidebarArgs>
 
 export const Sidebar: Story = {}
 
+/**
+ * Move the sidebar first in the HTML.
+ */
 export const SidebarFirst: Story = {
   args: {
     before: true,
   },
 }
 
+/**
+ * Reverse at the medium breakpoint.
+ */
 export const RevserseMedium: Story = {
   args: {
     order: SidebarOrder.REVERSE,
   },
 }
 
+/**
+ * Only reverse for larger breakpoints.
+ */
 export const ReverseLarge: Story = {
   args: {
     order: SidebarOrder.REVERSE_L,
   },
 }
 
+/**
+ * The sidebar is optional.
+ */
 export const NoSidebar: Story = {
   args: {
     sidebarContent: null,

package/src/Layout/Sidebar/Sidebar.tsx

@@ -25,9 +25,7 @@ const Sidebar = ({
   >
     {before && sidebar && <aside className={sidebarClassName}>{sidebar}</aside>}
     <section className={contentClassName}>{children}</section>
-    {!before && sidebar && (
-      <aside className={sidebarClassName}>{sidebar}</aside>
-    )}
+    {!before && sidebar && <aside className={sidebarClassName}>{sidebar}</aside>}
   </div>
 )
 

package/src/Layout/Sidebar/__snapshots__/Sidebar.stories.ts.snap

@@ -1,8 +1,8 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Layout/Sidebar NoSidebar smoke-test 1`] = `
 <div class="mx-page default">
-  <div class="mx-grid--sidebar ">
+  <div class="mx-grid--sidebar">
     <section>
       Main content
     </section>
@@ -38,7 +38,7 @@ exports[`Layout/Sidebar RevserseMedium smoke-test 1`] = `
 
 exports[`Layout/Sidebar Sidebar smoke-test 1`] = `
 <div class="mx-page default">
-  <div class="mx-grid--sidebar ">
+  <div class="mx-grid--sidebar">
     <section>
       Main content
     </section>
@@ -51,7 +51,7 @@ exports[`Layout/Sidebar Sidebar smoke-test 1`] = `
 
 exports[`Layout/Sidebar SidebarFirst smoke-test 1`] = `
 <div class="mx-page default">
-  <div class="mx-grid--sidebar ">
+  <div class="mx-grid--sidebar">
     <aside>
       Sidebar content
     </aside>

package/src/Layout/Sidebar/__snapshots__/Sidebar.stories.tsx.snap

@@ -1,4 +1,4 @@
-// Jest Snapshot v1, https://goo.gl/fbAQLP
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
 exports[`Layout/Sidebar NoSidebar smoke-test 1`] = `
 <div class="mx-page undefined">

package/src/Utility/Context/ImageComponent.tsx

@@ -23,10 +23,9 @@ import {
 type ImageComponentProps = ComponentPropsWithoutRef<"img">
 type ImageComponentContextValue = (ImageComponentProps) => JSX.Element
 
-const DefaultImageComponent = ({
-  alt,
-  ...props
-}: ImageComponentProps): JSX.Element => <img alt={alt} {...props} />
+const DefaultImageComponent = ({ alt, ...props }: ImageComponentProps): JSX.Element => (
+  <img alt={alt} {...props} />
+)
 
 const ImageComponentContext: Context<ImageComponentContextValue> =
   createContext<ImageComponentContextValue>(DefaultImageComponent)
@@ -36,10 +35,7 @@ type ImageComponentProviderProps = PropsWithChildren & {
   component?: (ImageComponentProps) => JSX.Element
 }
 
-const ImageComponentProvider = ({
-  children,
-  component = null,
-}: ImageComponentProviderProps) => (
+const ImageComponentProvider = ({ children, component = null }: ImageComponentProviderProps) => (
   <ImageComponentContext value={component}>{children}</ImageComponentContext>
 )
 

package/src/Utility/Context/LinkComponent.tsx

@@ -26,11 +26,7 @@ type LinkComponentProps = ComponentPropsWithoutRef<"a"> &
   }
 type LinkComponentValue = (LinkComponentProps) => JSX.Element
 
-const DefaultLinkComponent = ({
-  to,
-  children,
-  ...props
-}: LinkComponentProps): JSX.Element => (
+const DefaultLinkComponent = ({ to, children, ...props }: LinkComponentProps): JSX.Element => (
   <a href={to} {...props}>
     {children}
   </a>