@pnx-mixtape/mxds 0.1.0-rc.4 → 0.1.0-rc.6

package/src/Component/Navigation/_navigation-dropdown.css

@@ -20,6 +20,10 @@
       &:is(.mx-nav__has-subnav, :has(> ul)) {
         position: relative;
 
+        /* Each sub-menu anchors to its own parent item. */
+        anchor-scope: --mx-nav-item;
+        anchor-name: --mx-nav-item;
+
         & > a {
           --toggle-gap: var(--spacing-l);
         }
@@ -90,7 +94,11 @@
       margin: 0;
 
       @media (--global-nav-up) {
-        position: absolute;
+        /* Fixed so fallbacks flip against the viewport, not the parent item. */
+        position: fixed;
+        position-anchor: --mx-nav-item;
+        position-area: block-end span-inline-end;
+        position-try-fallbacks: flip-inline;
         inline-size: var(--dropdown-width, 270px);
         border-radius: var(--border-radius);
         background-color: var(
@@ -113,16 +121,6 @@
       }
     }
 
-    & .mx-nav--reverse .nav__level-2 {
-      @media (--global-nav-up) {
-        inset-inline: auto 0;
-
-        & .mx-nav__toggle::before {
-          transform: rotate(90deg);
-        }
-      }
-    }
-
     & .mx-nav__separator {
       border-block-start: var(--line-width, 1px) solid var(--line-colour, var(--colour-border));
     }

package/src/Component/Navigation/_navigation-mega.css

@@ -17,11 +17,12 @@
       inline-size: 100%;
 
       @media (--global-nav-up) {
-        position: absolute;
-        inset-inline-start: var(--dropdown-width, 270px);
-        inset-block-start: 0;
+        position: fixed;
+        position-anchor: --mx-nav-item;
+        position-area: span-block-end inline-end;
+        position-try-fallbacks: flip-inline;
         inline-size: var(--dropdown-width, 270px);
-        min-block-size: 100%;
+        min-block-size: anchor-size(block);
         padding-inline-start: 0;
         border-block-start: 0;
         border-radius: 0 var(--border-radius) var(--border-radius) 0;
@@ -37,12 +38,5 @@
         }
       }
     }
-
-    & .mx-nav--reverse .mx-nav__level-2 ul {
-      @media (--global-nav-up) {
-        inset-inline-start: calc(var(--dropdown-width, 270px) * -1);
-        border-radius: var(--border-radius) 0 0 var(--border-radius);
-      }
-    }
   }
 }

package/src/Component/Navigation/_navigation.css

@@ -45,11 +45,13 @@
     inset-block-start: var(--toggle-top, 12px);
     inset-inline-end: 0;
     cursor: pointer;
-  }
 
-  .mx-nav--open {
-    & > .mx-nav__toggle::before {
+    &[aria-expanded="true"]::before {
       transform: rotate(180deg);
     }
   }
+
+  mx-nav:not(:defined) .mx-nav__toggle {
+    display: none;
+  }
 }

package/src/Component/Navigation/menu.twig

@@ -23,7 +23,7 @@
           {{ item.link.title }}
         {% endif %}
         {% if item.items is not empty %}
-          <button class="mx-nav__toggle mx-icon mx-icon--chevron-down mx-icon--only">Sub-navigation</button>
+          <button class="mx-nav__toggle mx-icon mx-icon--chevron-down mx-icon--only" type="button">Sub-navigation</button>
           {{ nav.menutree(item.items, level + 1, setInert, baseClass) }}
         {% endif %}
       </li>

package/src/Component/Navigation/navigation.twig

@@ -14,7 +14,6 @@
 {% if type == "mega" %}
   {# Horizontal menu with 3 levels deep, no hover flyout. #}
   {% set needsJs = true %}
-  {% set componentAttributes = componentAttributes.addAttribute("edgeCheck") %}
   {% set modifiers = ['dropdown', 'mega-nav'] %}
 {% endif %}
 {% if type == "footer" %}

package/src/Component/Pagination/Pagination.stories.ts

@@ -136,35 +136,65 @@ export const Pagination: Story = {
 
 /**
  * Steps a virtual screen reader through the page and asserts on what it announces.
+ *
+ * Pagination's narrow/wide layouts are driven by a CSS container query (not
+ * `matchMedia`) that swaps the numbered link list for a "Page X of Y" label -
+ * see `pagination.css`. Chromatic exercises both `chromatic.modes` (mobile and
+ * desktop), so this branches on the container's own rendered state (which of
+ * the two is actually visible) rather than hardcoding one shape. Whichever
+ * mode a local run happens to render at, only one branch runs meaningfully for
+ * that run - the other is exercised by Chromatic's other mode in CI. See
+ * "Testing Mobile / matchMedia-Driven Behavior in Play Functions" in
+ * docs/Testing.md.
  */
 export const ScreenReaderAnnouncements: Story = {
-  play: async () => {
+  play: async ({ canvasElement }) => {
+    const label = canvasElement.querySelector(".mx-pagination__label")
+    const isNarrow = label !== null && getComputedStyle(label).display !== "none"
     const log = await runScreenReaderWalkthrough()
-    await expect(log).toEqual([
-      "document",
-      "navigation, Pagination",
-      "link, Previous",
-      "Previous",
-      "end of link, Previous",
-      "list",
-      "listitem, level 1, position 1, set size 4",
-      "link, 1",
-      "end of listitem, level 1, position 1, set size 4",
-      "listitem, level 1, position 2, set size 4",
-      "link, 2, current page",
-      "end of listitem, level 1, position 2, set size 4",
-      "listitem, level 1, position 3, set size 4",
-      "link, 3",
-      "end of listitem, level 1, position 3, set size 4",
-      "listitem, level 1, position 4, set size 4",
-      "link, 10",
-      "end of listitem, level 1, position 4, set size 4",
-      "end of list",
-      "link, Next",
-      "Next",
-      "end of link, Next",
-      "end of navigation, Pagination",
-      "end of document",
-    ])
+
+    if (isNarrow) {
+      await expect(log).toEqual([
+        "document",
+        "navigation, Pagination",
+        "link, Previous",
+        "Previous",
+        "end of link, Previous",
+        "Page 2 of 10",
+        "list",
+        "link, Next",
+        "Next",
+        "end of link, Next",
+        "end of navigation, Pagination",
+        "end of document",
+      ])
+    } else {
+      await expect(log).toEqual([
+        "document",
+        "navigation, Pagination",
+        "link, Previous",
+        "Previous",
+        "end of link, Previous",
+        "list",
+        "listitem, level 1, position 1, set size 4",
+        "link, 1",
+        "end of listitem, level 1, position 1, set size 4",
+        "listitem, level 1, position 2, set size 4",
+        "link, 2, current page",
+        "end of listitem, level 1, position 2, set size 4",
+        "listitem, level 1, position 3, set size 4",
+        "link, 3",
+        "end of listitem, level 1, position 3, set size 4",
+        "listitem, level 1, position 4, set size 4",
+        "link, 10",
+        "end of listitem, level 1, position 4, set size 4",
+        "end of list",
+        "link, Next",
+        "Next",
+        "end of link, Next",
+        "end of navigation, Pagination",
+        "end of document",
+      ])
+    }
   },
 }

package/src/Component/Pagination/pagination.css

@@ -2,8 +2,6 @@
  * Pagination
  */
 
-@import "../../Utility/_mixins.css";
-
 @layer design-system.components {
   .mx-pagination {
     margin-inline: 0;
@@ -102,11 +100,22 @@
     & :is(.mx-pagination__previous, .mx-pagination__next) {
       text-transform: capitalize;
 
-      & span:where(:not(.mx-icon)) {
-        @add-mixin sr-only;
-
-        @container pagination (min-width: 25ch) {
-          @add-mixin sr-undo;
+      & :is(a, button) {
+        @container pagination (max-width: 32ch) {
+          inline-size: var(--button-min-height, var(--spacing-xl));
+          block-size: var(--button-min-height, var(--spacing-xl));
+          flex-wrap: wrap;
+          position: relative;
+          padding: 0;
+          overflow: hidden;
+
+          & .mx-icon {
+            inline-size: var(--button-min-height, var(--spacing-xl));
+            block-size: var(--button-min-height, var(--spacing-xl));
+            place-content: center;
+            display: flex;
+            order: -1;
+          }
         }
       }
     }

package/src/Component/Popover/__snapshots__/Popover.stories.tsx.snap

@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Content Only 1`] = `"<button class="mx-button mx-icon--end" type="button" id="story-popover-minimal-trigger" popovertarget="story-popover-minimal" style="anchor-name: --story-popover-minimal;">Popover trigger<span class="mx-icon mx-icon--question"></span></button><div class="mx-popover" id="story-popover-minimal" aria-describedby="story-popover-minimal-trigger" data-placement="bottom" popover="" style="position-anchor: --story-popover-minimal;"><div class="mx-rich-text mx-vertical-flow"><p>A simple hint with no heading or action link.</p></div></div>"`;
+exports[`Content Only 1`] = `"<button class="mx-button mx-icon--end" type="button" id="story-popover-minimal-trigger" popovertarget="story-popover-minimal" style="anchor-name: --story-popover-minimal;"><span>Popover trigger</span><span class="mx-icon mx-icon--question"></span></button><div class="mx-popover" id="story-popover-minimal" aria-describedby="story-popover-minimal-trigger" data-placement="bottom" popover="" style="position-anchor: --story-popover-minimal;"><div class="mx-rich-text mx-vertical-flow"><p>A simple hint with no heading or action link.</p></div></div>"`;
 
-exports[`Default 1`] = `"<button class="mx-button mx-icon--end" type="button" id="story-popover-trigger" popovertarget="story-popover" style="anchor-name: --story-popover;">Popover trigger<span class="mx-icon mx-icon--question"></span></button><div class="mx-popover" id="story-popover" aria-describedby="story-popover-trigger" data-placement="bottom" popover="" style="position-anchor: --story-popover;"><div class="mx-rich-text mx-vertical-flow"><h2>Popover heading</h2><p>Short supplementary content. Use Popover for non-interactive hints; for menus use DropMenu, for modal content use Dialog.</p><a href="#" class="mx-link mx-link--more">Learn more</a></div></div>"`;
+exports[`Default 1`] = `"<button class="mx-button mx-icon--end" type="button" id="story-popover-trigger" popovertarget="story-popover" style="anchor-name: --story-popover;"><span>Popover trigger</span><span class="mx-icon mx-icon--question"></span></button><div class="mx-popover" id="story-popover" aria-describedby="story-popover-trigger" data-placement="bottom" popover="" style="position-anchor: --story-popover;"><div class="mx-rich-text mx-vertical-flow"><h2>Popover heading</h2><p>Short supplementary content. Use Popover for non-interactive hints; for menus use DropMenu, for modal content use Dialog.</p><a href="#" class="mx-link mx-link--more">Learn more</a></div></div>"`;
 
-exports[`Placement 1`] = `"<button class="mx-button mx-icon--end" type="button" id="story-popover-placement-trigger" popovertarget="story-popover-placement" style="anchor-name: --story-popover-placement;">Popover trigger<span class="mx-icon mx-icon--question"></span></button><div class="mx-popover" id="story-popover-placement" aria-describedby="story-popover-placement-trigger" data-placement="top" popover="" style="position-anchor: --story-popover-placement;"><div class="mx-rich-text mx-vertical-flow"><h2>Popover heading</h2><p>Short supplementary content. Use Popover for non-interactive hints; for menus use DropMenu, for modal content use Dialog.</p><a href="#" class="mx-link mx-link--more">Learn more</a></div></div>"`;
+exports[`Placement 1`] = `"<button class="mx-button mx-icon--end" type="button" id="story-popover-placement-trigger" popovertarget="story-popover-placement" style="anchor-name: --story-popover-placement;"><span>Popover trigger</span><span class="mx-icon mx-icon--question"></span></button><div class="mx-popover" id="story-popover-placement" aria-describedby="story-popover-placement-trigger" data-placement="top" popover="" style="position-anchor: --story-popover-placement;"><div class="mx-rich-text mx-vertical-flow"><h2>Popover heading</h2><p>Short supplementary content. Use Popover for non-interactive hints; for menus use DropMenu, for modal content use Dialog.</p><a href="#" class="mx-link mx-link--more">Learn more</a></div></div>"`;

package/src/Component/SideNavigation/Components/SideNavigationTree.tsx

@@ -1,37 +1,81 @@
-import { JSX } from "react"
+import { JSX, ComponentPropsWithoutRef, useContext, useId } from "react"
+import { useDisclosureState } from "react-stately"
 import { MenuTree } from "@pnx-mixtape/ids-shape"
 import Link from "../../../Atom/Link/Link"
+import { SideNavigationContext } from "../SideNavigation"
 
-type SideNavigationTreeProps = {
+type SideNavigationTreeProps = ComponentPropsWithoutRef<"ul"> & {
   items: MenuTree[]
   level?: number
 }
 
-const SideNavigationTree = ({ items, level = 0 }: SideNavigationTreeProps): JSX.Element => (
-  <ul className={`mx-nav__level-${level + 1}`}>
+type SideNavigationItemProps = {
+  item: MenuTree
+  level: number
+}
+
+// True when this item, or any descendant, is the current page.
+const hasCurrent = ({ link, items }: MenuTree): boolean =>
+  Boolean(link.current) || Boolean(items?.some(hasCurrent))
+
+const SideNavigationItem = ({ item, level }: SideNavigationItemProps): JSX.Element => {
+  const collapsible = useContext(SideNavigationContext)
+  const { isExpanded, toggle } = useDisclosureState({ defaultExpanded: hasCurrent(item) })
+  const listId = useId()
+  const labelId = useId()
+  const hasItems = item.items && item.items.length > 0
+
+  return (
+    <li className={hasItems ? "mx-nav__has-subnav" : undefined}>
+      {item.link.href ? (
+        <Link
+          to={item.link.href}
+          id={hasItems && collapsible ? labelId : undefined}
+          aria-current={item.link.current ? "page" : undefined}
+        >
+          {item.link.title}
+        </Link>
+      ) : (
+        item.link.title
+      )}
+      {hasItems && (
+        <>
+          <button
+            className="mx-nav__toggle mx-icon mx-icon--chevron-down mx-icon--only"
+            type="button"
+            {...(collapsible && {
+              "aria-expanded": isExpanded,
+              "aria-controls": listId,
+              onClick: toggle,
+            })}
+          >
+            Sub-navigation
+          </button>
+          <SideNavigationTree
+            items={item.items}
+            level={level + 1}
+            {...(collapsible && {
+              id: listId,
+              "aria-labelledby": item.link.href ? labelId : undefined,
+              inert: !isExpanded,
+            })}
+          />
+        </>
+      )}
+    </li>
+  )
+}
+
+const SideNavigationTree = ({
+  items,
+  level = 0,
+  ...props
+}: SideNavigationTreeProps): JSX.Element => (
+  <ul className={`mx-nav__level-${level + 1}`} {...props}>
     {items.map((item, i) => (
       // Menu items have no stable id; index is the only available key.
       // oxlint-disable-next-line react/no-array-index-key
-      <li key={i} className={item.items?.length ? "mx-nav__has-subnav" : undefined}>
-        {item.link.href ? (
-          <Link to={item.link.href} aria-current={item.link.current ? "page" : undefined}>
-            {item.link.title}
-          </Link>
-        ) : (
-          item.link.title
-        )}
-        {item.items && item.items.length > 0 && (
-          <>
-            <button
-              className="mx-nav__toggle mx-icon mx-icon--chevron-down mx-icon--only"
-              type="button"
-            >
-              Sub-navigation
-            </button>
-            <SideNavigationTree items={item.items} level={level + 1} />
-          </>
-        )}
-      </li>
+      <SideNavigationItem key={i} item={item} level={level} />
     ))}
   </ul>
 )

package/src/Component/SideNavigation/README.md

@@ -2,18 +2,26 @@
 
 A vertical, multi-level navigation rendered as a `<nav>` landmark with a parent page link at the top and a nested list of sibling/child pages below. Designed to live in the aside of content layouts to expose a section's local page tree. Extends the base `.mx-nav` styles from the Navigation component.
 
+By default every level is rendered open. Set `collapsible` to wrap the nav in `<mx-nav openActive>`, which turns each sub-list into a click-to-expand disclosure and opens the branch containing the current page.
+
 ## CSS Import
 
 ```css
 @import "@pnx-mixtape/mxds/src/Component/SideNavigation/side-navigation.css";
 ```
 
-Depends on the Navigation component's base styles (for `.mx-nav` and sub-list level classes):
+Depends on the Navigation component's base styles (for `.mx-nav`, sub-list level classes and, when collapsible, the `.mx-nav--collapsible` toggle/transition styles):
 
 ```css
 @import "@pnx-mixtape/mxds/src/Component/Navigation/navigation.css";
 ```
 
+## JS Import (collapsible only)
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Navigation/Elements/Navigation"
+```
+
 ---
 
 ## Twig
@@ -24,6 +32,7 @@ Depends on the Navigation component's base styles (for `.mx-nav` and sub-list le
   title: 'Section navigation',
   parent: parent_link,
   items: menu_tree,
+  collapsible: true,
 } %}
 ```
 
@@ -31,13 +40,14 @@ Depends on the Navigation component's base styles (for `.mx-nav` and sub-list le
 
 **side-navigation.twig props** (`SideNavigation` type from `ids-shape`):
 
-| Prop         | Type         | Description                                                                                                                              |
-| ------------ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`         | `string`     | Written to `.mx-side-nav__parent` and used as the `<nav>`'s `aria-labelledby` fallback when `title` is empty                             |
-| `title`      | `string`     | `aria-label` for the `<nav>` landmark. Provide a meaningful value so assistive tech can distinguish this nav from the site's primary nav |
-| `parent`     | `Link`       | Pre-rendered Link atom representing the current section's parent page, shown above the list                                              |
-| `items`      | `MenuTree[]` | Recursive menu tree — see shape below                                                                                                    |
-| `attributes` | `Attribute`  | Optional Drupal-style attributes object; the template merges `mx-nav mx-side-nav` onto its classes                                       |
+| Prop          | Type         | Description                                                                                                                                                                              |
+| ------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`          | `string`     | Written to `.mx-side-nav__parent` and used as the `<nav>`'s `aria-labelledby` fallback when `title` is empty                                                                             |
+| `title`       | `string`     | `aria-label` for the `<nav>` landmark. Provide a meaningful value so assistive tech can distinguish this nav from the site's primary nav                                                 |
+| `parent`      | `Link`       | Pre-rendered Link atom representing the current section's parent page, shown above the list                                                                                              |
+| `items`       | `MenuTree[]` | Recursive menu tree — see shape below                                                                                                                                                    |
+| `collapsible` | `boolean`    | Optional. Wraps the `<nav>` in `<mx-nav openActive>` and adds `mx-nav--collapsible` so sub-lists collapse behind their toggle buttons. Not part of the `ids-shape` `SideNavigation` type |
+| `attributes`  | `Attribute`  | Optional Drupal-style attributes object; the template merges `mx-nav mx-side-nav` onto its classes                                                                                       |
 
 **`MenuTree` shape** (from `@pnx-mixtape/ids-shape`):
 
@@ -98,13 +108,43 @@ Rules for the markup:
 - The top list is `mx-nav__level-1`, children are `mx-nav__level-2`, grandchildren are `mx-nav__level-3`. Each level adds more inline-start indent.
 - Any `<li>` that contains a nested `<ul>` must carry `mx-nav__has-subnav`.
 - The current page's `<a>` carries `aria-current="page"` — CSS uses this to bold the label and apply the active background.
-- Sub-lists are **not** collapsed or inert — unlike the dropdown/collapsible navigation, every level is rendered open.
+- Sub-lists are **not** collapsed or inert by default — every level is rendered open.
+
+### Collapsible
+
+```html
+<mx-nav openActive>
+  <nav class="mx-nav mx-side-nav mx-nav--collapsible" aria-label="Section navigation">
+    <div class="mx-side-nav__parent" id="section-nav">
+      <a href="/about">About</a>
+    </div>
+    <ul class="mx-nav__level-1">
+      <li class="mx-nav__has-subnav">
+        <a href="/about/what-we-do">What we do</a>
+        <button class="mx-nav__toggle mx-icon mx-icon--chevron-down mx-icon--only" type="button">
+          Sub-navigation
+        </button>
+        <ul class="mx-nav__level-2">
+          <li>
+            <a href="/about/what-we-do/events" aria-current="page">Events</a>
+          </li>
+        </ul>
+      </li>
+    </ul>
+  </nav>
+</mx-nav>
+```
+
+- Sub-lists are rendered open in the markup (no `inert`), so the full tree is available without JS.
+- On connect, `<mx-nav>` wires each `.mx-nav__toggle` to its sibling `<ul>` (`aria-controls`, `aria-expanded`, `inert`), labels each sub-list by its parent link, then (because of `openActive`) re-opens any sub-list whose parent link or descendants carry `aria-current="page"` or `.is-active`.
+- Sub-lists not on the current page's trail start collapsed.
+- Toggles are hidden until `<mx-nav>` is defined (`mx-nav:not(:defined) .mx-nav__toggle`).
 
 ---
 
 ## React
 
-Uses a composition pattern — always use `SideNavigationTree` inside `SideNavigation`.
+Uses a composition pattern — always use `SideNavigationTree` inside `SideNavigation`. `SideNavigationTree` reads `collapsible` from `SideNavigation` via context, so it is only set once.
 
 ```tsx
 import { SideNavigation, SideNavigationTree, Link } from "@pnx-mixtape/mxds/react"
@@ -126,6 +166,7 @@ const items: MenuTree[] = [
   id="section-nav"
   title="Section navigation"
   parent={<Link to="/about">About</Link>}
+  collapsible
 >
   <SideNavigationTree items={items} />
 </SideNavigation>
@@ -133,18 +174,20 @@ const items: MenuTree[] = [
 
 **`SideNavigation` Props:**
 
-| Prop        | Type        | Required | Description                                                                                                                  |
-| ----------- | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `parent`    | `ReactNode` | No       | Link/element shown above the list inside `.mx-side-nav__parent`                                                              |
-| `title`     | `string`    | No       | `aria-label` for the `<nav>` landmark. When omitted, falls back to `aria-labelledby` pointing at the parent wrapper          |
-| `id`        | `string`    | No       | `id` on `.mx-side-nav__parent`, also used as the `aria-labelledby` target when `title` is not set. Auto-generated if omitted |
-| `className` | `string`    | No       | Extra class on the `<nav>`                                                                                                   |
+| Prop          | Type        | Required | Description                                                                                                                                                                                                                         |
+| ------------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `parent`      | `ReactNode` | No       | Link/element shown above the list inside `.mx-side-nav__parent`                                                                                                                                                                     |
+| `title`       | `string`    | No       | `aria-label` for the `<nav>` landmark. When omitted, falls back to `aria-labelledby` pointing at the parent wrapper                                                                                                                 |
+| `id`          | `string`    | No       | `id` on `.mx-side-nav__parent`, also used as the `aria-labelledby` target when `title` is not set. Auto-generated if omitted                                                                                                        |
+| `collapsible` | `boolean`   | No       | Adds `mx-nav--collapsible` and makes every nested `SideNavigationTree` sub-list a disclosure (`aria-expanded`/`aria-controls` on the toggle, `inert` when closed). Branches containing the current item start open. Default `false` |
+| `className`   | `string`    | No       | Extra class on the `<nav>`                                                                                                                                                                                                          |
 
 **`SideNavigationTree` Props:**
 
-| Prop    | Type         | Required | Description                                                                   |
-| ------- | ------------ | -------- | ----------------------------------------------------------------------------- |
-| `items` | `MenuTree[]` | Yes      | Recursive menu tree — rendered as nested `<ul class="mx-nav__level-N">` lists |
+| Prop       | Type            | Required | Description                                                                   |
+| ---------- | --------------- | -------- | ----------------------------------------------------------------------------- |
+| `items`    | `MenuTree[]`    | Yes      | Recursive menu tree — rendered as nested `<ul class="mx-nav__level-N">` lists |
+| `...props` | `ul` attributes | No       | Spread onto the `<ul>`                                                        |
 
 **`MenuTree` shape** (from `@pnx-mixtape/ids-shape`):
 
@@ -159,17 +202,18 @@ const items: MenuTree[] = [
 
 ## Modifiers
 
-SideNavigation uses the base `.mx-nav` class for list reset and the component-specific classes below. There are no variant modifiers — the single layout covers all cases.
+SideNavigation uses the base `.mx-nav` class for list reset and the component-specific classes below. The only variant is `mx-nav--collapsible`.
 
-| Class                                                     | Applied by                             | Visual intent                                                                                                                        |
-| --------------------------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `mx-nav`                                                  | Always (shared with Navigation)        | Base list reset — no bullets, vertical layout                                                                                        |
-| `mx-side-nav`                                             | Always                                 | Side-nav specific styling: per-item dividers, indent ramp across levels, current-page background                                     |
-| `mx-side-nav__parent`                                     | Always                                 | Parent-page wrapper above the list — bold label, thicker bottom border                                                               |
-| `mx-nav__level-1` / `mx-nav__level-2` / `mx-nav__level-3` | Structural                             | Sub-list nesting level — each level increases `--indent`                                                                             |
-| `mx-nav__has-subnav`                                      | Structural                             | Applied to any `<li>` that contains a child `<ul>`                                                                                   |
-| `mx-nav__toggle`                                          | Structural (inherited from Navigation) | Hidden in side-nav (`display: none`) — the template emits it for markup parity with dropdown nav, but every level is always expanded |
-| `is-active`                                               | Authoring                              | Alternative to `aria-current="page"` for marking the current item — styled identically                                               |
+| Class                                                     | Applied by                             | Visual intent                                                                                                    |
+| --------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `mx-nav`                                                  | Always (shared with Navigation)        | Base list reset — no bullets, vertical layout                                                                    |
+| `mx-side-nav`                                             | Always                                 | Side-nav specific styling: per-item dividers, indent ramp across levels, current-page background                 |
+| `mx-side-nav__parent`                                     | Always                                 | Parent-page wrapper above the list — bold label, thicker bottom border                                           |
+| `mx-nav--collapsible`                                     | Twig `collapsible: true`               | Shows the sub-list toggles and applies the collapsible nav's `inert`/transition styles                           |
+| `mx-nav__level-1` / `mx-nav__level-2` / `mx-nav__level-3` | Structural                             | Sub-list nesting level — each level increases `--indent`                                                         |
+| `mx-nav__has-subnav`                                      | Structural                             | Applied to any `<li>` that contains a child `<ul>`                                                               |
+| `mx-nav__toggle`                                          | Structural (inherited from Navigation) | Hidden (`display: none`) unless the nav is `mx-nav--collapsible`, where it opens and closes its sibling sub-list |
+| `is-active`                                               | Authoring                              | Alternative to `aria-current="page"` for marking the current item — styled identically                           |
 
 ---
 
@@ -180,8 +224,10 @@ SideNavigation uses the base `.mx-nav` class for list reset and the component-sp
 - Uses semantic nested `<ul>` / `<li>` lists, so assistive tech announces list depth and item count at each level.
 - The current page is marked with `aria-current="page"` on the `<a>`. Style-only bolding is a visual reinforcement — the ARIA attribute is what assistive tech announces. Avoid relying on the background/weight alone.
 - Active-trail ancestors (parent items on the path to the current page) are not given `aria-current` — only the exact current page. Apply the `is-active` class if you want to visually mark ancestors with the same active styling.
-- Keyboard navigation: every item is a native `<a>`, so tab order follows source order and no custom key handling is needed. Sub-lists are always visible, so there is no expand/collapse interaction to manage.
-- The `.mx-nav__toggle` button is emitted in the Twig markup for structural parity with the dropdown nav but is hidden via CSS — do not rely on it for any interactive behaviour in this component at this time (future iterations may enable it).
+- Keyboard navigation: every item is a native `<a>`, so tab order follows source order. In the default variant sub-lists are always visible, so there is no expand/collapse interaction to manage.
+- The `.mx-nav__toggle` button is hidden via CSS in the default variant.
+- Collapsible (Twig and React): each toggle is a native `<button>` with `aria-expanded` and `aria-controls`; collapsed sub-lists are `inert`, so they drop out of the tab order and the accessibility tree. In Twig, `<mx-nav>` also adds the shared `Keyboard` arrow-key handling between links; React has no equivalent. `Escape` does not close sub-lists in either — that is only wired up for `flyout` navs.
+- Collapsible: every toggle's accessible name is "Sub-navigation". Screen-reader users get the context from the preceding link, but the name alone doesn't say which section it opens.
 
 ---
 
@@ -205,7 +251,7 @@ SideNavigation uses the base `.mx-nav` class for list reset and the component-sp
 }
 ```
 
-Level 2 and level 3 sub-lists override `--indent` to step the text further in — at narrow widths with `--spacing-s` / `--spacing-m`, and at the `--global-nav-up` breakpoint with `--spacing-m` / `--spacing-l`.
+Level 2 and level 3 sub-lists override `--indent` to step the text further in — at narrow widths with `--spacing-s` / `--spacing-m`, and at the `--sidebar-up` breakpoint with `--spacing-m` / `--spacing-l`.
 
 ---
 

package/src/Component/SideNavigation/SideNavigation.stories.ts

@@ -1,11 +1,17 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
+import { expect } from "storybook/test"
 import Component from "./side-navigation.twig"
 import Link from "../../Atom/Link/link.twig"
 import "../Navigation/navigation.css"
 import "./side-navigation.css"
+import "../Navigation/Elements/Navigation"
 import { SideNavigation as NavigationType } from "@pnx-mixtape/ids-shape"
 
-const meta: Meta<NavigationType> = {
+type SideNavigationType = NavigationType & {
+  collapsible?: boolean
+}
+
+const meta: Meta<SideNavigationType> = {
   tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
@@ -128,10 +134,43 @@ const meta: Meta<NavigationType> = {
         required: true,
       },
     },
+    collapsible: {
+      type: "boolean",
+    },
   },
 }
 
 export default meta
-type Story = StoryObj<NavigationType>
+type Story = StoryObj<SideNavigationType>
 
 export const SideNavigation: Story = {}
+
+export const Collapsible: Story = {
+  args: {
+    collapsible: true,
+  },
+  play: async ({ canvas, userEvent, step }) => {
+    const item = canvas.getByRole("link", { name: "What we do" }).closest("li")
+    const trigger = item.querySelector(":scope > .mx-nav__toggle")
+    const list = item.querySelector(":scope > ul")
+
+    await step("Opens the active trail", async () => {
+      await expect(trigger).toHaveAttribute("aria-expanded", "true")
+      await expect(trigger).toHaveAttribute("aria-controls", list.id)
+      await expect(list).not.toHaveAttribute("inert")
+    })
+
+    await step("Closes on click", async () => {
+      await userEvent.click(trigger)
+      await expect(trigger).toHaveAttribute("aria-expanded", "false")
+      await expect(list).toHaveAttribute("inert")
+    })
+
+    await step("Reopens on click", async () => {
+      await userEvent.click(trigger)
+      await expect(trigger).toHaveAttribute("aria-expanded", "true")
+      await expect(list).not.toHaveAttribute("inert")
+      ;(trigger as HTMLElement).blur()
+    })
+  },
+}