@pnx-mixtape/mxds 0.0.29 → 0.1.0-rc.0

package/src/Layout/Header/Header.tsx

@@ -1,34 +1,39 @@
-import { JSX, PropsWithChildren, ReactNode, useId } from "react"
+import { JSX, PropsWithChildren, ReactNode, useId, Fragment } from "react"
+import { FocusScope } from "react-aria"
+import { useDisclosureState } from "react-stately"
 import classNames from "classnames"
 import Section from "../Section/Section"
 import GlobalToggle from "./Components/GlobalToggle"
 import NavigationDropdown from "../../Component/Navigation/Dropdown"
-import useToggle from "../../Utility/Hooks/useToggle"
 import useMediaQuery from "../../Utility/Hooks/useMediaQuery"
-import { Icons, SectionStyles } from "../../enums.js"
-import { SectionTypes } from "@pnx-mixtape/ids-shape"
+import { Icons } from "../../enums.js"
+import { SectionTypes, SectionModifiers } from "@pnx-mixtape/ids-shape"
 import { NavigationItem } from "../../Component/Navigation/Navigation"
 
 type PrimaryHeaderProps = PropsWithChildren & {
   logo?: ReactNode
   navigationItems?: NavigationItem[]
   mediaQuery?: string
-  size?: SectionStyles | SectionStyles[]
+  size?: SectionModifiers | SectionModifiers[]
   className?: string
+  backgroundClass?: string
 }
 
 const Header = ({
   logo,
   navigationItems,
   mediaQuery = "(max-width: 720px)",
-  size = SectionStyles.S,
+  size = SectionModifiers.S,
   children,
   className,
+  backgroundClass = "mx-background--primary",
 }: PrimaryHeaderProps): JSX.Element => {
   const id: string = useId()
-  const [on, toggle] = useToggle(false)
+  const { isExpanded, toggle } = useDisclosureState({ defaultExpanded: false })
   const isMobile: boolean = useMediaQuery(mediaQuery)
 
+  const Wrapper = isExpanded && isMobile ? FocusScope : Fragment
+
   return (
     <Section
       as={SectionTypes.HEADER}
@@ -45,7 +50,7 @@ const Header = ({
               toggleId={id}
               icon={Icons.MENU}
               name="menu"
-              open={on}
+              open={isExpanded}
               onClick={() => toggle()}
             />
           </div>
@@ -54,16 +59,20 @@ const Header = ({
         <div className="mx-header__main">
           <div
             id={id}
-            className="mx-header__nav"
-            // @ts-expect-error inert is allowed.
-            inert={!on && isMobile ? "" : null}
+            className={classNames("mx-header__nav mx-header__collapse-toggle", {
+              [backgroundClass]: isExpanded && isMobile,
+            })}
+            inert={!isExpanded && isMobile}
           >
-            <NavigationDropdown
-              title="Primary Navigation"
-              items={navigationItems}
-              mediaQuery={mediaQuery}
-              id={id}
-            ></NavigationDropdown>
+            {/* oxlint-disable-next-line jsx-a11y/no-autofocus */}
+            <Wrapper contain restoreFocus autoFocus>
+              <NavigationDropdown
+                title="Primary Navigation"
+                items={navigationItems}
+                mediaQuery={mediaQuery}
+                id={id}
+              ></NavigationDropdown>
+            </Wrapper>
           </div>
 
           {children}

package/src/Layout/Header/README.md

@@ -0,0 +1,141 @@
+# Header
+
+The primary site header. Contains the logo/brand, main navigation (with mobile hamburger toggle), search, and optional extra controls (e.g. login button). Collapses navigation into a toggle menu below a configurable breakpoint.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Layout/Header/header.css";
+```
+
+## Twig
+
+```twig
+{% include '@mixtape/Layout/Header/header.twig' with {
+  logo: logo_component,
+  title: 'Site Name',
+  description: 'Tagline or short description',
+  navigation: navigation_component,
+  search: search_form_component,
+  controls: [
+    login_button_component,
+  ],
+} %}
+
+{# Stacked layout — navigation row sits below the brand bar at full width #}
+{% include '@mixtape/Layout/Header/header.twig' with {
+  logo: logo_component,
+  navigation: navigation_component,
+  controls: [
+    login_button_component,
+  ],
+  stacked: true,
+} %}
+```
+
+**header.twig props** (`Header` type from `ids-shape`, plus `stacked`):
+
+| Prop          | Type             | Required | Description                                                                                         |
+| ------------- | ---------------- | -------- | --------------------------------------------------------------------------------------------------- |
+| `logo`        | `Logo \| Logo[]` | No       | Rendered Logo markup placed in the brand area                                                       |
+| `title`       | `string`         | No       | Bold site name rendered alongside the logo                                                          |
+| `description` | `string`         | No       | Tagline / short description rendered under the title                                                |
+| `navigation`  | `Navigation`     | No       | Rendered Navigation component placed in the primary nav region                                      |
+| `search`      | `SearchForm`     | No       | Rendered SearchForm component placed in the primary search region                                   |
+| `controls`    | `Button[]`       | No       | Rendered Button atoms (e.g. login/account) — placed in the right-aligned controls area              |
+| `stacked`     | `boolean`        | No       | Moves `navigation` (and `controls`) into a separate full-width row below the brand bar              |
+| `attributes`  | `Attribute`      | No       | Optional Drupal-style attributes object — `mx-header mx-page mx-section--s` is always merged on top |
+
+When `stacked: true` the navigation and controls are excluded from the inner brand row and re-rendered in a sibling `<div id="primary-nav" class="mx-header__nav mx-page">` below the `<header>`. The mobile toggle buttons (`<mx-global-toggle>`) are always rendered when `navigation` or `search` is present, regardless of the stacked flag.
+
+## HTML
+
+```html
+<header class="mx-header mx-section mx-section--s mx-page">
+  <div class="mx-header__inner">
+    <div class="mx-header__brand">
+      <!-- logo -->
+    </div>
+    <!-- mobile toggle (mobile only) -->
+    <div class="mx-header__main">
+      <div class="mx-header__nav">
+        <!-- navigation -->
+      </div>
+      <!-- extra controls -->
+    </div>
+  </div>
+</header>
+```
+
+## Web Component (HTML/Twig)
+
+For a Twig/HTML implementation, the header uses the `NavigationDropdown` component for desktop dropdown menus.
+
+## React
+
+```tsx
+import { Header } from "@pnx-mixtape/mxds/react"
+;<Header
+  logo={
+    <a href="/">
+      <img src="/logo.svg" alt="Site name" />
+    </a>
+  }
+  navigationItems={[
+    { id: "about", title: "About", to: "/about" },
+    {
+      id: "services",
+      title: "Services",
+      to: "/services",
+      items: [{ id: "services-design", title: "Design", to: "/services/design" }],
+    },
+  ]}
+>
+  {/* Optional extra content (e.g. login button) */}
+  <Button modifiers={[ButtonModifiers.DARK]}>Login</Button>
+</Header>
+```
+
+**Props:**
+
+| Prop              | Type                                     | Default                | Description                                                                                                                                       |
+| ----------------- | ---------------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `logo`            | `ReactNode`                              | —                      | Brand logo/link                                                                                                                                   |
+| `navigationItems` | `NavigationItem[]`                       | —                      | Primary nav items. `NavigationItem` is `{ id, title, to, items? }`. Nested items are rendered as dropdowns by the underlying `NavigationDropdown` |
+| `mediaQuery`      | `string`                                 | `"(max-width: 720px)"` | Breakpoint at which nav collapses to mobile toggle                                                                                                |
+| `size`            | `SectionModifiers \| SectionModifiers[]` | `SectionModifiers.S`   | Vertical padding (see `Section`)                                                                                                                  |
+| `className`       | `string`                                 | —                      | Extra class on the header element                                                                                                                 |
+| `children`        | `ReactNode`                              | —                      | Extra controls rendered in the header right area                                                                                                  |
+
+### React ⇄ Twig parity
+
+| Feature              | React | Twig                    | Notes                                                                                                |
+| -------------------- | ----- | ----------------------- | ---------------------------------------------------------------------------------------------------- |
+| `stacked` layout     | ❌    | ✅ (`stacked: boolean`) | Twig template can render the navigation in a separate row below the brand bar. Not exposed in React  |
+| Twig `search` slot   | ❌    | ✅ (`search`)           | Twig adds a search-toggle button + search panel. Compose your own in React via `children`            |
+| Twig `controls` slot | ❌    | ✅ (`controls`)         | Twig renders an array of right-aligned controls. React accepts a single `children` block — wrap them |
+| Hamburger toggle     | ✅    | ✅                      | Both stacks collapse the nav to a hamburger below `mediaQuery`                                       |
+
+## Mobile behaviour
+
+Below `mediaQuery`, the navigation is hidden via `inert` and a hamburger button appears (`mx-icon--menu`). Toggling reveals the nav panel. The navigation and toggle share an `id` for ARIA association.
+
+## Accessibility
+
+- The outer `<header>` element is the page banner landmark — there should be only one per page.
+- The primary nav inside the header is labelled `"Primary Navigation"` (React: passed to `NavigationDropdown` via `title`; Twig: `aria-label="Primary navigation"` on the nav wrapper).
+- The optional search wrapper is labelled `"Search"` (Twig).
+- If you place additional `<nav>` regions inside the Header (e.g. utility links via `children` or `controls`), give each a distinct `aria-label`. The labelling convention used elsewhere in the design system is title case ("Primary Navigation", "Utility Navigation", "Language Switcher", "Skip to links").
+
+## Customisation via CSS custom properties
+
+```css
+.mx-header {
+  --brand-gap: var(--gap-s); /* gap between logo and site name */
+  --main-gap: var(--gap); /* gap between nav items and controls */
+}
+```
+
+---
+
+→ Used in context: `mockups/HomePage.stories.ts:3`

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

@@ -11,7 +11,7 @@ exports[`Controls 1`] = `
                     <mx-global-toggle><button aria-controls="unique-0" class="mx-button mx-button--icon-only mx-icon mx-icon--menu">Open Menu</button></mx-global-toggle>
           </div>
         <div class="mx-header__main">
-              <div id="unique-0" class="mx-header__nav mx-header__collapse-toggle" aria-label="Primary navigation" role="region">
+              <div id="unique-0" class="mx-header__nav mx-header__collapse-toggle">
             
 
 <mx-nav flyout="">
@@ -43,7 +43,7 @@ exports[`Controls 1`] = `
   </mx-nav>
 
         </div>
-                                    
+                          
   <button class="mx-button" type="button">
     
     <span>Translate</span>
@@ -52,7 +52,7 @@ exports[`Controls 1`] = `
 
   </button>
 
-                  </div>
+          </div>
   </div>
 </header>
 "
@@ -69,7 +69,7 @@ exports[`Header 1`] = `
                     <mx-global-toggle><button aria-controls="unique-0" class="mx-button mx-button--icon-only mx-icon mx-icon--menu">Open Menu</button></mx-global-toggle>
           </div>
         <div class="mx-header__main">
-              <div id="unique-0" class="mx-header__nav mx-header__collapse-toggle" aria-label="Primary navigation" role="region">
+              <div id="unique-0" class="mx-header__nav mx-header__collapse-toggle">
             
 
 <mx-nav flyout="">
@@ -101,7 +101,8 @@ exports[`Header 1`] = `
   </mx-nav>
 
         </div>
-                                    </div>
+                          
+          </div>
   </div>
 </header>
 "
@@ -119,7 +120,7 @@ exports[`Search 1`] = `
                     <mx-global-toggle><button aria-controls="unique-1" class="mx-button mx-button--icon-only mx-icon mx-icon--menu">Open Menu</button></mx-global-toggle>
           </div>
         <div class="mx-header__main">
-              <div id="unique-1" class="mx-header__nav mx-header__collapse-toggle" aria-label="Primary navigation" role="region">
+              <div id="unique-1" class="mx-header__nav mx-header__collapse-toggle">
             
 
 <mx-nav flyout="">
@@ -151,7 +152,7 @@ exports[`Search 1`] = `
   </mx-nav>
 
         </div>
-                    <div id="unique-0" class="mx-header__search mx-header__collapse-toggle" aria-label="Search" role="region">
+                    <div id="unique-0" class="mx-header__search mx-header__collapse-toggle">
           
 <form class="mx-form mx-form--inline-button" role="search" action="#search">
   <input class="mx-input__text " id="search-keyword" name="search-form" type="search" value="" aria-label="Search by keywords" placeholder="Keywords...">
@@ -162,7 +163,8 @@ exports[`Search 1`] = `
 </form>
 
         </div>
-                              </div>
+                    
+          </div>
   </div>
 </header>
 "
@@ -180,7 +182,7 @@ exports[`Stacked 1`] = `
                     <mx-global-toggle><button aria-controls="unique-1" class="mx-button mx-button--icon-only mx-icon mx-icon--menu">Open Menu</button></mx-global-toggle>
           </div>
         <div class="mx-header__main">
-                    <div id="unique-0" class="mx-header__search mx-header__collapse-toggle" aria-label="Search" role="region">
+                    <div id="unique-0" class="mx-header__search mx-header__collapse-toggle">
           
 <form class="mx-form mx-form--inline-button" role="search" action="#search">
   <input class="mx-input__text " id="search-keyword" name="search-form" type="search" value="" aria-label="Search by keywords" placeholder="Keywords...">
@@ -194,7 +196,7 @@ exports[`Stacked 1`] = `
                 </div>
   </div>
 </header>
-  <div id="unique-1" class="mx-header__nav mx-page mx-header__collapse-toggle" aria-label="Primary navigation" role="region">
+  <div id="unique-1" class="mx-header__nav mx-page mx-header__collapse-toggle">
     <div class="mx-header__nav-inner">
           
 
@@ -284,7 +286,7 @@ exports[`Stacked 1`] = `
   </mx-nav>
 
               <div class="mx-header__nav-right">
-                      
+          
   <button class="mx-button" type="button">
     
     <span>Translate</span>
@@ -293,7 +295,7 @@ exports[`Stacked 1`] = `
 
   </button>
 
-                  </div>
+        </div>
           </div>
   </div>
 "
@@ -313,7 +315,7 @@ exports[`With Title 1`] = `
                     <mx-global-toggle><button aria-controls="unique-0" class="mx-button mx-button--icon-only mx-icon mx-icon--menu">Open Menu</button></mx-global-toggle>
           </div>
         <div class="mx-header__main">
-              <div id="unique-0" class="mx-header__nav mx-header__collapse-toggle" aria-label="Primary navigation" role="region">
+              <div id="unique-0" class="mx-header__nav mx-header__collapse-toggle">
             
 
 <mx-nav flyout="">
@@ -345,7 +347,8 @@ exports[`With Title 1`] = `
   </mx-nav>
 
         </div>
-                                    </div>
+                          
+          </div>
   </div>
 </header>
 "

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

@@ -1,3 +1,3 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Primary Header 1`] = `"<header class="mx-page mx-header mx-section--s"><div class="mx-header__inner"><div class="mx-header__brand"><a href="https://mxds.pnx.io/" class="mx-logo"><img alt="Mixtape" loading="eager" src="https://mxds.pnx.io/images/mixtape-logo.png"></a></div><div class="mx-header__main"><div id="_r_0_" class="mx-header__nav"><nav class="mx-nav mx-nav--dropdown" aria-label="Primary Navigation" id="_r_0_"><ul class="mx-nav__level-1"><li class="mx-nav__has-subnav"><a href="http://example.com/#1" class="">Home</a><button aria-controls="_r_1_" aria-expanded="false" class="mx-nav__toggle mx-icon mx-icon--only mx-icon--chevron-down" type="button">Sub-navigation</button></li><li class=""><a href="http://example.com/#2" class="">About</a></li><li class=""><a href="http://example.com/#3" class="">Contact</a></li></ul></nav></div></div></div></header>"`;
+exports[`Primary Header 1`] = `"<header class="mx-page mx-header mx-section--s"><div class="mx-header__inner"><div class="mx-header__brand"><img alt="Mixtape" src="mixtape-logo.png"></div><div class="mx-header__main"><div id="_r_0_" class="mx-header__nav mx-header__collapse-toggle"><nav class="mx-nav mx-nav--dropdown" aria-label="Primary Navigation" id="_r_0_"><ul class="mx-nav__level-1"><li class="mx-nav__has-subnav"><a href="http://example.com/#1" class="">Home</a><button aria-controls="_r_1_" aria-expanded="false" class="mx-nav__toggle mx-icon mx-icon--only mx-icon--chevron-down" type="button">Sub-navigation</button></li><li class=""><a href="http://example.com/#2" class="">About</a></li><li class=""><a href="http://example.com/#3" class="">Contact</a></li></ul></nav></div></div></div></header>"`;

package/src/Layout/Header/_header.css

@@ -57,9 +57,3 @@
     }
   }
 }
-
-@media print {
-  .mx-header .mx-header__nav {
-    display: none;
-  }
-}

package/src/Layout/Header/_toggles.css

@@ -58,10 +58,10 @@
       transition-duration: 0.4s;
     }
   }
-}
 
-.global-nav-up-only {
-  @media (--global-nav-down) {
-    display: none;
+  .global-nav-up-only {
+    @media (--global-nav-down) {
+      display: none;
+    }
   }
 }

package/src/Layout/Header/header.twig

@@ -30,32 +30,28 @@
     {% endif %}
     <div class="mx-header__main">
       {% if navigation is not empty and not stacked %}
-        <div id="primary-nav" class="mx-header__nav mx-header__collapse-toggle global-nav-up-only" aria-label="Primary navigation">
+        <div id="primary-nav" class="mx-header__nav mx-header__collapse-toggle global-nav-up-only">
           {{ navigation }}
         </div>
       {% endif %}
       {% if search is not empty %}
-        <div id="primary-search" class="mx-header__search mx-header__collapse-toggle global-nav-up-only" aria-label="Search">
+        <div id="primary-search" class="mx-header__search mx-header__collapse-toggle global-nav-up-only">
           {{ search }}
         </div>
       {% endif %}
       {% if not stacked %}
-        {% for control in controls %}
-          {{ control }}
-        {% endfor %}
+        {{ controls }}
       {% endif %}
     </div>
   </div>
 </header>
 {% if stacked and (navigation is not empty or controls is not empty) %}
-  <div id="primary-nav" class="mx-header__nav mx-page mx-header__collapse-toggle global-nav-up-only" aria-label="Primary navigation">
+  <div id="primary-nav" class="mx-header__nav mx-page mx-header__collapse-toggle global-nav-up-only">
     <div class="mx-header__nav-inner">
       {{ navigation }}
       {% if controls is not empty %}
         <div class="mx-header__nav-right">
-          {% for control in controls %}
-            {{ control }}
-          {% endfor %}
+          {{ controls }}
         </div>
       {% endif %}
     </div>

package/src/Layout/Masthead/Masthead.figma.ts

@@ -0,0 +1,27 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=79-272
+// source=src/Layout/Masthead/Masthead.tsx
+// component=Masthead
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const background = instance.getEnum("Background", {
+  Dark: "MastheadModifier.DARK",
+  Light: "MastheadModifier.LIGHT",
+})
+
+const content = instance.getSlot("Content")
+
+// `links`/`skipLinks` are ReactNode[] ARRAY props (same shape issue as Carousel's
+// `items`) — not modelled.
+export default {
+  example: figma.code`<Masthead background={${background}}>${content}</Masthead>`,
+  imports: [
+    'import { Masthead } from "@pnx-mixtape/mxds/react"',
+    'import { MastheadModifier } from "@pnx-mixtape/ids-shape"',
+  ],
+  id: "masthead",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Layout/Masthead/Masthead.stories.ts

@@ -6,7 +6,11 @@ import "./masthead.css"
 import { Masthead as MastheadType, MastheadModifier } from "@pnx-mixtape/ids-shape"
 import { Icons } from "../../enums"
 
-const meta: Meta<MastheadType> = {
+type MxMastheadType = Omit<MastheadType, "skipLinks"> & {
+  skipLinks?: string
+}
+
+const meta: Meta<MxMastheadType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
@@ -20,7 +24,17 @@ const meta: Meta<MastheadType> = {
         href: "#nav",
         title: "Skip to navigation",
       }),
-    ],
+    ].join(""),
+  },
+  argTypes: {
+    background: {
+      description: "Change the background colour",
+      options: Object.values(MastheadModifier),
+      control: "radio",
+      table: {
+        type: { summary: "enum" },
+      },
+    },
   },
 }
 
@@ -52,6 +66,6 @@ export const WithLinks: Story = {
           icon: Icons.LOGIN,
         }),
       }),
-    ],
+    ].join(""),
   },
 }

package/src/Layout/Masthead/Masthead.stories.tsx

@@ -0,0 +1,55 @@
+import { Meta, StoryObj } from "@storybook/react-vite"
+import Component from "./Masthead"
+import { MastheadModifier } from "@pnx-mixtape/ids-shape"
+import "./masthead.css"
+import { Page } from "../../../.storybook-react/decorators"
+
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  decorators: [Page],
+  component: Component,
+  args: {
+    skipLinks: [
+      <a key="content" href="#content">
+        Skip to content
+      </a>,
+      <a key="nav" href="#nav">
+        Skip to navigation
+      </a>,
+    ],
+    children: "A PreviousNext product",
+  },
+  argTypes: {
+    background: {
+      description: "Change the background colour",
+      options: Object.values(MastheadModifier),
+      control: "radio",
+      table: {
+        type: { summary: "enum" },
+      },
+    },
+  },
+}
+
+export default meta
+
+export const Masthead: StoryObj<typeof meta> = {}
+
+export const Light: StoryObj<typeof meta> = {
+  args: {
+    background: MastheadModifier.LIGHT,
+  },
+}
+
+export const WithLinks: StoryObj<typeof meta> = {
+  args: {
+    links: [
+      <a key="account" className="mx-link" href="#">
+        Create account
+      </a>,
+      <a key="login" className="mx-link" href="#">
+        Log in
+      </a>,
+    ],
+  },
+}

package/src/Layout/Masthead/Masthead.tsx

@@ -0,0 +1,59 @@
+import { Fragment, JSX, PropsWithChildren, ReactNode } from "react"
+import classNames from "classnames"
+import { MastheadModifier } from "@pnx-mixtape/ids-shape"
+
+type MastheadProps = PropsWithChildren & {
+  background?: MastheadModifier
+  skipLinks?: ReactNode[]
+  links?: ReactNode[]
+  className?: string
+}
+
+const Masthead = ({
+  background = MastheadModifier.DARK,
+  skipLinks,
+  links,
+  children,
+  className,
+}: MastheadProps): JSX.Element => {
+  const hasContent = children || (links && links.length > 0)
+
+  return (
+    <>
+      {skipLinks && skipLinks.length > 0 && (
+        <nav className="mx-skip-links" aria-label="Skip to links">
+          {skipLinks.map((link, i) => (
+            // Opaque ReactNode with no stable id; index is the only available key.
+            // oxlint-disable-next-line react/no-array-index-key
+            <Fragment key={i}>{link}</Fragment>
+          ))}
+        </nav>
+      )}
+      {hasContent && (
+        <div
+          className={classNames(
+            "mx-masthead",
+            "mx-spacing--top-xxs mx-spacing--bottom-xxs",
+            background === MastheadModifier.LIGHT ? "mx-background--alt" : "mx-background--reverse",
+            className,
+          )}
+        >
+          <div className="flex">
+            {children && <div>{children}</div>}
+            {links && links.length > 0 && (
+              <nav className="mx-masthead__nav" aria-label="Additional links">
+                {links.map((link, i) => (
+                  // Opaque ReactNode with no stable id; index is the only available key.
+                  // oxlint-disable-next-line react/no-array-index-key
+                  <Fragment key={i}>{link}</Fragment>
+                ))}
+              </nav>
+            )}
+          </div>
+        </div>
+      )}
+    </>
+  )
+}
+
+export default Masthead