@pnx-mixtape/mxds 0.0.30 → 0.1.0-rc.1

package/src/Layout/Grid/Grid.stories.ts

@@ -3,6 +3,7 @@ import Component from "./grid.twig"
 import GridItem from "./grid-item.twig"
 import "./grid.css"
 import { AsTypes, Grid as GridType, GridModifiers, SectionTypes } from "@pnx-mixtape/ids-shape"
+import { modes } from "../../../.storybook/modes"
 
 /**
  * A CSS grid that is dynamic by default.
@@ -18,7 +19,7 @@ const meta: Meta<GridType> = {
       GridItem({ item: "<span>item 4</span>" }),
       GridItem({ item: "<span>item 5</span>" }),
       GridItem({ item: "<span>item 6</span>" }),
-    ],
+    ].join(""),
     as: SectionTypes.DIV,
   },
   argTypes: {
@@ -37,14 +38,23 @@ const meta: Meta<GridType> = {
       },
     },
     items: {
-      description: "A list of [GridItem](/?path=/docs/layout-grid-griditem--docs) objects.",
+      description:
+        "A concatenated string of [GridItem](/?path=/docs/layout-grid-griditem--docs) markup.",
       type: {
         name: "other",
         required: true,
-        value: "array",
+        value: "string",
       },
       table: {
-        type: { summary: "GridItem" },
+        type: { summary: "string" },
+      },
+    },
+  },
+  parameters: {
+    chromatic: {
+      modes: {
+        mobile: modes["xs"],
+        desktop: modes["xl"],
       },
     },
   },
@@ -80,7 +90,7 @@ export const List: Story = {
         item: ["list item 2"],
         as: AsTypes.LI,
       }),
-    ],
+    ].join(""),
   },
 }
 
@@ -96,6 +106,6 @@ export const Span: Story = {
         item: ["item 2, span 2"],
         modifiers: [GridModifiers.MD_2],
       }),
-    ],
+    ].join(""),
   },
 }

package/src/Layout/Grid/README.md

@@ -0,0 +1,162 @@
+# Grid
+
+A responsive CSS grid layout using `auto-fit` and `minmax`. Columns automatically reflow — no breakpoint classes needed for basic usage. Column count modifiers pin the grid to a specific number of columns at a given breakpoint.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Layout/Grid/grid.css";
+```
+
+## Twig
+
+```twig
+{# Auto-reflow grid #}
+{% include '@mixtape/Layout/Grid/grid.twig' with {
+  items: [
+    item_1,
+    item_2,
+    item_3,
+  ],
+} %}
+
+{# 3 columns from medium up, rendered as <ul> with <li> items #}
+{% include '@mixtape/Layout/Grid/grid.twig' with {
+  as: 'ul',
+  modifiers: ['md-3'],
+  items: [
+    include('@mixtape/Layout/Grid/grid-item.twig', { as: 'li', item: card_1 }),
+    include('@mixtape/Layout/Grid/grid-item.twig', { as: 'li', item: card_2 }),
+    include('@mixtape/Layout/Grid/grid-item.twig', { as: 'li', item: card_3 }),
+  ],
+} %}
+
+{# Grid item spanning 2 columns at medium+ #}
+{% include '@mixtape/Layout/Grid/grid-item.twig' with {
+  modifiers: ['md-2'],
+  item: wide_content,
+} %}
+```
+
+**grid.twig props** (`Grid` type from `ids-shape`):
+
+| Prop         | Type                       | Required | Description                                                                        |
+| ------------ | -------------------------- | -------- | ---------------------------------------------------------------------------------- |
+| `items`      | `GridItem[] \| Collection` | Yes      | Rendered grid-item strings (or any Collection markup) — looped into the wrapper    |
+| `modifiers`  | `GridModifiers[]`          | No       | Each value is appended as `mx-grid--cols-{modifier}` (e.g. `md-3`, `lg-4`)         |
+| `as`         | `SectionTypes`             | No       | Semantic element. Defaults to `div` — pass `ul`/`section`/`aside` etc. as required |
+| `attributes` | `Attribute`                | No       | Optional Drupal-style attributes object — `mx-grid` is always merged on top        |
+
+**grid-item.twig props** (`GridItem` type from `ids-shape`):
+
+| Prop         | Type              | Required | Description                                                                               |
+| ------------ | ----------------- | -------- | ----------------------------------------------------------------------------------------- |
+| `item`       | `Collection`      | Yes      | Rendered child markup placed inside the item wrapper                                      |
+| `modifiers`  | `GridModifiers[]` | No       | Each value is appended as `mx-grid-item__span-{modifier}` (e.g. `md-2` to span 2 columns) |
+| `container`  | `boolean`         | No       | Adds `mx-container` to enable a CSS container query context on this item                  |
+| `as`         | `AsTypes`         | No       | Semantic element. Defaults to `div`                                                       |
+| `attributes` | `Attribute`       | No       | Optional Drupal-style attributes object — span/container classes are merged on top        |
+
+The grid-item template short-circuits when there are no modifiers, no container, and `as` is the default `div` — it just prints the `item` directly with no wrapper. This keeps the auto-reflow grid example above clean: pass plain rendered children to `items` and only wrap them in `grid-item.twig` when you need the per-item span / element / container.
+
+## HTML
+
+```html
+<!-- Auto-reflow -->
+<div class="mx-grid">
+  <div>Item</div>
+  <div>Item</div>
+  <div>Item</div>
+</div>
+
+<!-- 3 columns from medium up -->
+<ul class="mx-grid mx-grid--cols-md-3">
+  <li>Item</li>
+  <li>Item</li>
+  <li>Item</li>
+</ul>
+
+<!-- Item spanning 2 columns from medium up -->
+<div class="mx-grid-item__span-md-2">Wide item</div>
+```
+
+## React
+
+```tsx
+import { Grid } from "@pnx-mixtape/mxds/react"
+import { GridModifiers, AsTypes } from "@pnx-mixtape/ids-shape"
+
+// Auto-reflow grid (default behaviour)
+<Grid wrapper>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</Grid>
+
+// 3-column from medium breakpoint, as a <ul>
+<Grid wrapper cols={GridModifiers.MD_3} as={AsTypes.UL}>
+  <li>Card</li>
+  <li>Card</li>
+  <li>Card</li>
+</Grid>
+
+// Multiple column breakpoints
+<Grid wrapper cols={[GridModifiers.SM_2, GridModifiers.LG_4]}>
+  ...
+</Grid>
+
+// Grid item spanning columns
+<Grid width={GridModifiers.MD_2}>
+  Wide item
+</Grid>
+```
+
+**`Grid` props:**
+
+| Prop        | Type                               | Default | Description                                              |
+| ----------- | ---------------------------------- | ------- | -------------------------------------------------------- |
+| `wrapper`   | `boolean`                          | `false` | Applies `mx-grid` — must be `true` on the grid container |
+| `container` | `boolean`                          | `false` | Adds `mx-container` CSS container query context          |
+| `cols`      | `GridModifiers \| GridModifiers[]` | —       | Column count modifier(s)                                 |
+| `width`     | `GridModifiers`                    | —       | Makes this item span columns (`mx-grid-item__span-*`)    |
+| `as`        | `AsTypes \| SectionTypes`          | `div`   | Semantic element                                         |
+
+## Column modifiers (`GridModifiers` enum)
+
+All modifiers set a fixed column count at the named breakpoint and above. Below the breakpoint, the grid collapses to 1 column.
+
+| Class                | `GridModifiers` enum | Columns at breakpoint |
+| -------------------- | -------------------- | --------------------- |
+| `mx-grid--cols-xs-2` | `GridModifiers.XS_2` | 2 from 420px          |
+| `mx-grid--cols-sm-2` | `GridModifiers.SM_2` | 2 from 540px          |
+| `mx-grid--cols-md-2` | `GridModifiers.MD_2` | 2 from 720px          |
+| `mx-grid--cols-lg-2` | `GridModifiers.LG_2` | 2 from 946px          |
+| `mx-grid--cols-xl-2` | `GridModifiers.XL_2` | 2 from 1100px         |
+| `mx-grid--cols-md-3` | `GridModifiers.MD_3` | 3 from 720px          |
+| `mx-grid--cols-lg-3` | `GridModifiers.LG_3` | 3 from 946px          |
+| `mx-grid--cols-xl-3` | `GridModifiers.XL_3` | 3 from 1100px         |
+| `mx-grid--cols-md-4` | `GridModifiers.MD_4` | 4 from 720px          |
+| `mx-grid--cols-lg-4` | `GridModifiers.LG_4` | 4 from 946px          |
+| `mx-grid--cols-xl-4` | `GridModifiers.XL_4` | 4 from 1100px         |
+
+## Gap modifiers
+
+| Class                    | Effect                   |
+| ------------------------ | ------------------------ |
+| `mx-grid--collapse`      | Removes all gaps         |
+| `mx-grid--collapse-cols` | Removes column gaps only |
+| `mx-grid--collapse-rows` | Removes row gaps only    |
+
+## Customisation via CSS custom properties
+
+```css
+.mx-grid {
+  --grid-min: 30ch; /* minimum column width before reflow (default: 20ch) */
+  --grid-gap: 2rem; /* gap override */
+  --large-grid-gap: 3rem; /* gap at large breakpoint+ (default: --gap-l) */
+}
+```
+
+---
+
+→ Used in context: `mockups/ArticlePage.stories.ts:10`

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

@@ -3,22 +3,17 @@
 exports[`Breakpoints 1`] = `
 "    
 <div class="mx-grid mx-grid--cols-sm-2 mx-grid--cols-lg-4">
-  
+
   <span>item 1</span>
 
-  
   <span>item 2</span>
 
-  
   <span>item 3</span>
 
-  
   <span>item 4</span>
 
-  
   <span>item 5</span>
 
-  
   <span>item 6</span>
 
 </div>
@@ -28,22 +23,17 @@ exports[`Breakpoints 1`] = `
 exports[`Grid 1`] = `
 "
 <div class="mx-grid">
-  
+
   <span>item 1</span>
 
-  
   <span>item 2</span>
 
-  
   <span>item 3</span>
 
-  
   <span>item 4</span>
 
-  
   <span>item 5</span>
 
-  
   <span>item 6</span>
 
 </div>
@@ -53,12 +43,11 @@ exports[`Grid 1`] = `
 exports[`List 1`] = `
 "  
 <ul class="mx-grid mx-grid--cols-sm-2">
-  
+
   <li>
     list item 1
   </li>
 
-  
   <li>
     list item 2
   </li>
@@ -70,10 +59,9 @@ exports[`List 1`] = `
 exports[`Span 1`] = `
 "    
 <div class="mx-grid mx-grid--cols-sm-2 mx-grid--cols-md-3">
-  
-  <span>item 1</span>
 
-    
+  <span>item 1</span>
+  
   <div class="mx-grid-item__span-md-2">
     item 2, span 2
   </div>

package/src/Layout/Grid/grid.css

@@ -179,9 +179,3 @@
     }
   }
 }
-
-@media print {
-  .mx-grid {
-    display: block;
-  }
-}

package/src/Layout/Grid/grid.twig

@@ -7,7 +7,5 @@
 {% set as = as|default("div") %}
 
 <{{ as }}{{ attributes }}>
-{% for item in items %}
-  {{ item }}
-{% endfor %}
+{{ items }}
 </{{ as }}>

package/src/Layout/Header/Components/GlobalToggle.tsx

@@ -8,6 +8,7 @@ type GlobalToggleProps = ButtonType & {
   name: string
   toggleId: string
   open?: boolean
+  modifiers?: ButtonModifiers
 }
 
 const GlobalToggle = ({
@@ -15,13 +16,14 @@ const GlobalToggle = ({
   icon,
   name,
   toggleId,
+  modifiers,
   ...props
 }: GlobalToggleProps): JSX.Element => {
   return (
     <Button
       iconOnly={true}
-      icon={open ? Icons.CLOSE : icon}
-      modifiers={[ButtonModifiers.DARK]}
+      iconStart={open ? Icons.CLOSE : icon}
+      modifiers={modifiers}
       aria-expanded={open}
       aria-controls={toggleId}
       {...props}

package/src/Layout/Header/Elements/GlobalToggle.ts

@@ -23,6 +23,8 @@ export default class GlobalToggle extends HTMLElement {
   isSearch?: boolean
   hideOther?: boolean = true
   otherTrigger?: HTMLButtonElement | null
+  rafId?: number | null
+  focusTrapTimeout?: ReturnType<typeof setTimeout> | null
 
   constructor() {
     super()
@@ -33,9 +35,6 @@ export default class GlobalToggle extends HTMLElement {
 
   connectedCallback(): void {
     if (!this.trigger || !this.target) return
-
-    this.target?.setAttribute("role", "region")
-
     const hideOther = this.trigger.getAttribute("hideOther")
     if (hideOther === "false") this.hideOther = false
     this.isSearch = this.controls.includes("search")
@@ -53,12 +52,33 @@ export default class GlobalToggle extends HTMLElement {
       onDeactivate: () => document.body.classList.remove(this.scrollLockClass),
       checkCanFocusTrap: ([trapContainer]) =>
         new Promise<void>(resolve => {
-          const interval = setInterval(() => {
+          // Safety timeout: resolve after 2 seconds if visibility never changes
+          this.focusTrapTimeout = setTimeout(() => {
+            if (this.rafId) {
+              cancelAnimationFrame(this.rafId)
+              this.rafId = null
+            }
+            if (process.env.NODE_ENV !== "production") {
+              // oxlint-disable-next-line no-console
+              console.warn("Focus trap visibility check timed out - proceeding anyway")
+            }
+            resolve()
+          }, 2000)
+
+          // Check visibility using requestAnimationFrame for better performance
+          const checkVisibility = () => {
             if (getComputedStyle(trapContainer).visibility !== "hidden") {
+              if (this.focusTrapTimeout) {
+                clearTimeout(this.focusTrapTimeout)
+                this.focusTrapTimeout = null
+              }
+              this.rafId = null
               resolve()
-              clearInterval(interval)
+            } else {
+              this.rafId = requestAnimationFrame(checkVisibility)
             }
-          }, 5)
+          }
+          this.rafId = requestAnimationFrame(checkVisibility)
         }),
     })
 
@@ -73,6 +93,18 @@ export default class GlobalToggle extends HTMLElement {
   disconnectedCallback(): void {
     this.widget.detach()
     this.controller.abort()
+
+    // Clean up focus trap timers
+    if (this.rafId) {
+      cancelAnimationFrame(this.rafId)
+      this.rafId = null
+    }
+    if (this.focusTrapTimeout) {
+      clearTimeout(this.focusTrapTimeout)
+      this.focusTrapTimeout = null
+    }
+    this.focusTrap.deactivate()
+    document.body.classList.remove(this.scrollLockClass)
   }
 
   handleBreakpoint = ({ matches }: MediaQueryList | MediaQueryListEvent): void => {
@@ -85,20 +117,32 @@ export default class GlobalToggle extends HTMLElement {
     } else {
       this.widget.detach()
       this.target.removeAttribute("inert")
-      this.target.classList.remove(this.scrollLockClass)
+      document.body.classList.remove(this.scrollLockClass)
       this.trigger.removeEventListener("disclosure-toggle", this.handleDisclosure)
       this.focusTrap.deactivate()
     }
   }
 
-  handleDisclosure = ({ detail }: CustomEvent<DisclosureWidgetEvent>): void => {
+  handleDisclosure = async ({ detail }: CustomEvent<DisclosureWidgetEvent>): Promise<void> => {
     const { isOpen } = detail
     // Toggle toggle text.
     const origText = !isOpen ? "Close" : "Open"
     const replaceText = !isOpen ? "Open" : "Close"
     this.trigger.textContent = this.triggerText.replace(origText, replaceText)
 
-    isOpen ? this.focusTrap.activate() : this.focusTrap.deactivate()
+    if (isOpen) {
+      // Handle focus trap activation errors gracefully
+      try {
+        await this.focusTrap.activate()
+      } catch (error) {
+        if (process.env.NODE_ENV !== "production") {
+          // oxlint-disable-next-line no-console
+          console.warn("Failed to activate focus trap:", error)
+        }
+      }
+    } else {
+      this.focusTrap.deactivate()
+    }
 
     // Close other trigger if it's open.
     if (isOpen && this.hideOther && this.otherTrigger) {

package/src/Layout/Header/Header.figma.ts

@@ -0,0 +1,40 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=117-531
+// source=src/Layout/Header/Header.tsx
+// component=Header
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const logo = instance.getSlot("Logo")
+const content = instance.getSlot("Content")
+
+// `navigationItems` is always rendered internally via a real `NavigationDropdown`
+// (Header.tsx imports and renders it unconditionally, not just on mobile — only the
+// surrounding toggle's visibility is conditional) — a consumer of Header never writes
+// <NavigationDropdown> by hand. NavigationDropdown itself isn't a mapped Code Connect
+// component yet (flagged in Chunk 6 as a real scope gap, still pending its own
+// follow-up chunk), so this fixes `navigationItems` as a literal array matching the
+// real example data in mockups/constants.tsx — including a nested sub-item, since
+// that's a real supported shape NavigationDropdown renders (DropdownLevel). The nav
+// row shown in the Figma composition (real Link instances) is visual-only preview,
+// same relationship as Footer's Navigation instance to its `links` prop.
+export default {
+  example: figma.code`<Header logo={${logo}} navigationItems={[
+  {
+    id: "1",
+    title: "Home",
+    to: "http://example.com/#1",
+    items: [
+      { id: "1.1", title: "Child link 1", to: "http://example.com/#1.1" },
+      { id: "1.2", title: "Child link 2", to: "http://example.com/#1.2" },
+    ],
+  },
+  { id: "2", title: "About", to: "http://example.com/#2" },
+  { id: "3", title: "Contact", to: "http://example.com/#3" },
+]}>${content}</Header>`,
+  imports: ['import { Header } from "@pnx-mixtape/mxds/react"'],
+  id: "header",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Layout/Header/Header.stories.ts

@@ -1,4 +1,5 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
+import { expect } from "storybook/test"
 import Component from "./header.twig"
 import "./_header.css"
 import "./_toggles.css"
@@ -16,9 +17,11 @@ import SearchForm from "../../Form/Search/search-form.twig"
 import "../../Component/Navigation/Elements/Navigation"
 // css.
 import "../../Component/Navigation/navigation.css"
+import { modes } from "../../../.storybook/modes"
 
-type MxHeaderType = HeaderType & {
+type MxHeaderType = Omit<HeaderType, "controls"> & {
   stacked: boolean
+  controls?: string
 }
 
 const meta: Meta<MxHeaderType> = {
@@ -71,12 +74,48 @@ const meta: Meta<MxHeaderType> = {
     "logo.image.src": { control: "text" },
     "logo.image.alt": { control: "text" },
   },
+  parameters: {
+    chromatic: {
+      modes: {
+        mobile: modes["xs"],
+        desktop: modes["xl"],
+      },
+    },
+  },
 }
 
 export default meta
 type Story = StoryObj<MxHeaderType>
 
-export const Header: Story = {}
+export const Header: Story = {
+  play: async ({ canvas, canvasElement, userEvent, step }) => {
+    // The toggle only attaches its click/keyboard handlers below the mobile breakpoint.
+    const isMobile = matchMedia("(max-width: 720px)").matches
+    if (!isMobile) return
+
+    const trigger = canvas.getByRole("button", { name: "Open Menu" })
+    const nav = canvasElement.querySelector("#primary-nav") as HTMLElement
+
+    await step("Starts closed", async () => {
+      await expect(trigger).toHaveAttribute("aria-expanded", "false")
+      await expect(nav).toHaveAttribute("inert")
+    })
+
+    await step("Opens on click", async () => {
+      await userEvent.click(trigger)
+      await expect(trigger).toHaveAttribute("aria-expanded", "true")
+      await expect(nav).not.toHaveAttribute("inert")
+    })
+
+    await step("Closes on escape", async () => {
+      await userEvent.keyboard("{Escape}")
+      await expect(trigger).toHaveAttribute("aria-expanded", "false")
+      await expect(nav).toHaveAttribute("inert")
+      // Remove focus
+      await userEvent.click(canvasElement)
+    })
+  },
+}
 
 export const WithTitle: Story = {
   args: {
@@ -104,7 +143,7 @@ export const Controls: Story = {
           icon: Icons.CHEVRON_DOWN,
         }),
       }),
-    ],
+    ].join(""),
   },
 }
 
@@ -123,7 +162,7 @@ export const Stacked: Story = {
           icon: Icons.CHEVRON_DOWN,
         }),
       }),
-    ],
+    ].join(""),
     navigation: Navigation({
       id: "header-stacked-story",
       type: "mega",

package/src/Layout/Header/Header.stories.tsx

@@ -1,4 +1,5 @@
 import { Meta, StoryObj } from "@storybook/react-vite"
+import { expect } from "storybook/test"
 import Component from "./Header"
 import { mixtapeLogo, navigationItems } from "../../../mockups/constants"
 import "./header.css"
@@ -15,4 +16,32 @@ const meta: Meta<typeof Component> = {
 
 export default meta
 
-export const PrimaryHeader: StoryObj<typeof meta> = {}
+export const PrimaryHeader: StoryObj<typeof meta> = {
+  play: async ({ canvas, canvasElement, userEvent, step }) => {
+    // The mobile toggle only renders below the header's mobile breakpoint.
+    const isMobile = matchMedia("(max-width: 720px)").matches
+    if (!isMobile) return
+
+    const trigger = canvas.getByRole("button", { name: "Open menu" })
+    const nav = canvasElement.querySelector(".mx-header__nav") as HTMLElement
+
+    await step("Starts closed", async () => {
+      await expect(trigger).toHaveAttribute("aria-expanded", "false")
+      await expect(nav).toHaveAttribute("inert")
+    })
+
+    await step("Opens on click", async () => {
+      await userEvent.click(trigger)
+      await expect(trigger).toHaveAttribute("aria-expanded", "true")
+      await expect(nav).not.toHaveAttribute("inert")
+    })
+
+    await step("Closes on click", async () => {
+      await userEvent.click(trigger)
+      await expect(trigger).toHaveAttribute("aria-expanded", "false")
+      await expect(nav).toHaveAttribute("inert")
+      // Remove focus
+      await userEvent.click(canvasElement)
+    })
+  },
+}