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

package/src/Component/InPageNavigation/InPageNavigation.stories.tsx

@@ -1,10 +1,9 @@
 import { Meta, StoryObj } from "@storybook/react-vite"
+import { HeadingTypes } from "@pnx-mixtape/ids-shape"
 import Heading from "../../Atom/Heading/Heading"
 import Text from "../../Atom/Text/Text"
 import Component from "./InPageNavigation"
-import Sidebar from "../../Layout/Sidebar/Sidebar"
 import "./in-page-navigation.css"
-import { HeadingLevels } from "../../enums"
 import { Page } from "../../../.storybook-react/decorators"
 
 const meta: Meta<typeof Component> = {
@@ -12,68 +11,67 @@ const meta: Meta<typeof Component> = {
   component: Component,
   decorators: [Page],
   render: () => (
-    <Sidebar before sidebar={<Component />}>
-      <div className="mx-vertical-flow">
-        <Heading level={HeadingLevels.TWO}>Section 1</Heading>
+    <div className="mx-vertical-flow">
+      <Component />
+      <section className="mx-vertical-flow mx-rich-text">
+        <Heading>Section 1</Heading>
         <Text>
           In publishing and graphic design, lorem ipsum is a placeholder text commonly used to
           demonstrate the visual form of a document without relying on meaningful content. Replacing
           the actual content with placeholder text allows designers to design the form of the
           content before the content itself has been produced.
         </Text>
-        <Heading level={HeadingLevels.TWO} id="anchor-test">
-          Section 2
-        </Heading>
+        <Heading id="anchor-test">Section 2</Heading>
         <Text>
           In publishing and graphic design, lorem ipsum is a placeholder text commonly used to
           demonstrate the visual form of a document without relying on meaningful content. Replacing
           the actual content with placeholder text allows designers to design the form of the
           content before the content itself has been produced.
         </Text>
-        <Heading level={HeadingLevels.THREE}>Test level 3</Heading>
+        <Heading as={HeadingTypes.THREE}>Test level 3</Heading>
         <Text>
           In publishing and graphic design, lorem ipsum is a placeholder text commonly used to
           demonstrate the visual form of a document without relying on meaningful content. Replacing
           the actual content with placeholder text allows designers to design the form of the
           content before the content itself has been produced.
         </Text>
-        <Heading level={HeadingLevels.TWO}>Section 3</Heading>
+        <Heading>Section 3</Heading>
         <Text>
           In publishing and graphic design, lorem ipsum is a placeholder text commonly used to
           demonstrate the visual form of a document without relying on meaningful content. Replacing
           the actual content with placeholder text allows designers to design the form of the
           content before the content itself has been produced.
         </Text>
-        <Heading level={HeadingLevels.TWO}>Section 4</Heading>
+        <Heading>Section 4</Heading>
         <Text>
           In publishing and graphic design, lorem ipsum is a placeholder text commonly used to
           demonstrate the visual form of a document without relying on meaningful content. Replacing
           the actual content with placeholder text allows designers to design the form of the
           content before the content itself has been produced.
         </Text>
-        <Heading level={HeadingLevels.TWO}>Section 5</Heading>
+        <Heading>Section 5</Heading>
         <Text>
           In publishing and graphic design, lorem ipsum is a placeholder text commonly used to
           demonstrate the visual form of a document without relying on meaningful content. Replacing
           the actual content with placeholder text allows designers to design the form of the
           content before the content itself has been produced.
         </Text>
-        <Heading level={HeadingLevels.THREE}>Test level 6</Heading>
+        <Heading as={HeadingTypes.THREE}>Test level 6</Heading>
         <Text>
           In publishing and graphic design, lorem ipsum is a placeholder text commonly used to
           demonstrate the visual form of a document without relying on meaningful content. Replacing
           the actual content with placeholder text allows designers to design the form of the
           content before the content itself has been produced.
         </Text>
-        <Heading level={HeadingLevels.TWO}>Section 7</Heading>
+        <Heading>Section 7</Heading>
         <Text>
           In publishing and graphic design, lorem ipsum is a placeholder text commonly used to
           demonstrate the visual form of a document without relying on meaningful content. Replacing
           the actual content with placeholder text allows designers to design the form of the
           content before the content itself has been produced.
         </Text>
-      </div>
-    </Sidebar>
+      </section>
+    </div>
   ),
 }
 export default meta

package/src/Component/InPageNavigation/InPageNavigation.tsx

@@ -1,9 +1,8 @@
 import { JSX, RefObject } from "react"
+import { HeadingTypes } from "@pnx-mixtape/ids-shape"
 import Link from "../../Atom/Link/Link"
 import Heading from "../../Atom/Heading/Heading"
 import useInPageNavigation from "./Hooks/useInPageNavigation"
-import { HeadingStyles } from "../../enums"
-import { HeadingTypes } from "@pnx-mixtape/ids-shape"
 
 type InPageNavigationProps = {
   title?: string
@@ -11,6 +10,8 @@ type InPageNavigationProps = {
   levels?: string
 }
 
+const TITLE_MODIFIERS = [HeadingTypes.FOUR]
+
 // @todo: make composable
 const InPageNavigation = ({
   title = "On this page",
@@ -19,8 +20,8 @@ const InPageNavigation = ({
 }: InPageNavigationProps): JSX.Element => {
   const { headings } = useInPageNavigation({ ref: containerRef, levels })
   return (
-    <nav className={"mx-in-page-navigation mx-nav mx-nav--list"}>
-      <Heading as={HeadingTypes.TWO} modifier={HeadingStyles.EMBELLISHED}>
+    <nav className={"mx-in-page-navigation mx-nav mx-nav--list mx-vertical-flow"}>
+      <Heading as={HeadingTypes.TWO} modifiers={TITLE_MODIFIERS}>
         {title}
       </Heading>
       <ul>

package/src/Component/InPageNavigation/README.md

@@ -1,25 +1,180 @@
-# In Page Navigation
+# InPageNavigation
 
-### How to use
+A "table of contents" navigation block that links to headings within the current page. Can be provided with explicit items, or auto-built from headings in a target content region via the `<mx-in-page-navigation>` Web Component.
 
-**CSS**
+## CSS Import
 
-`@import '@pnx-mixtape/mxds/src/Component/InPageNavigation/in-page-navigation.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Component/InPageNavigation/in-page-navigation.css";
+```
 
-**Twig**
+---
 
-You can setup a twig namespace in your project if you wish to use the twig files directly.
+## Twig
 
-- Eg: `{% extends '@mixtape/Component/InPageNavigation/in-page-navigation.twig' %}`
+```twig
+{# Auto-built — leave items empty so the JS picks up headings inside .js-content #}
+{% include '@mixtape/Component/InPageNavigation/in-page-navigation.twig' with {
+  title: heading_component,
+  levels: ['h2', 'h3'],
+} %}
 
-Alternatively copy/paste the file for more control.
+{# Or pass pre-rendered link items #}
+{% include '@mixtape/Component/InPageNavigation/in-page-navigation.twig' with {
+  title: heading_component,
+  levels: ['h2', 'h3'],
+  items: [
+    link_to_section_1,
+    link_to_section_2,
+  ],
+} %}
+```
 
-**Web Components**
+**in-page-navigation.twig props** (`InPageNavigation` type from `ids-shape`):
 
-Web Components are self defined, simply import the desired feature. These do not use the Shadow DOM. External CSS applies.
+| Prop         | Type                   | Required | Description                                                                                                                    |
+| ------------ | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `title`      | `string \| Heading`    | No       | Rendered heading markup. Joined into the `data-title` attribute (HTML stripped) for the JS-generated default heading           |
+| `levels`     | `HeadingTypes[]`       | No       | Heading levels for the JS to index, e.g. `['h2', 'h3']`. Joined with commas onto `data-levels`                                 |
+| `items`      | `Link[] \| Collection` | No       | Pre-rendered Link markup for each menu item. If empty, the JS auto-builds the list from headings inside `.js-content`          |
+| `attributes` | `Attribute`            | No       | Optional Drupal-style attributes object — `mx-nav mx-nav--list mx-in-page-navigation mx-vertical-flow` is always merged on top |
 
-- InPageNavigationBase import: `import '@pnx-mixtape/mxds/src/Component/InPageNavigation/Element/InPageNavigation';` and be sure to include `<mx-in-page-navigation>` around the `<nav />` tag.
-- Use the `[data-content]` attribute to specify where to look for headings (required).
-- Use the `[data-headings]` attribute to customise the heading levels. Default is h2.
+The Twig template always wraps the `<nav>` in `<mx-in-page-navigation>` and hard-codes `data-content=".js-content"` — your page content must use that class (or fork the template with a different selector). The `<ul>` is only rendered when `items` is non-empty; otherwise the web component populates the list at connect time.
 
-See twig files for all HTML examples.
+---
+
+## HTML + Web Component
+
+The `<mx-in-page-navigation>` custom element enhances a `<nav>` list with:
+
+- Auto-generating list items from headings found inside a container selector (`data-content`)
+- Auto-assigning `id` attributes to headings that don't have one (slugified from their text)
+- Auto-generating a `<h2>` title inside the `<nav>` when no items are provided
+- Marking the clicked link with `is-active` on click (no scroll-spy — see note below)
+
+```html
+<mx-in-page-navigation data-content=".js-content" data-levels="h2,h3" data-title="On this page">
+  <nav class="mx-nav mx-nav--list mx-in-page-navigation mx-vertical-flow">
+    <!-- Items populated by JS from headings found in .js-content.
+         Or provide your own items explicitly: -->
+  </nav>
+</mx-in-page-navigation>
+
+<div class="js-content mx-rich-text mx-vertical-flow">
+  <h2 id="section-1">Section 1</h2>
+  <p>...</p>
+  <h2 id="section-2">Section 2</h2>
+  <p>...</p>
+  <h3 id="test-level-3">Test level 3</h3>
+  <p>...</p>
+</div>
+```
+
+**Import the JS:**
+
+```js
+import "@pnx-mixtape/mxds/src/Component/InPageNavigation/Elements/InPageNavigation"
+```
+
+**`<mx-in-page-navigation>` data attributes:**
+
+| Attribute      | Required | Default        | Description                                                                                                                                                                       |
+| -------------- | -------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-content` | yes      | —              | CSS selector for the container whose headings should be indexed. The element uses `.closest()`, then `parentElement.querySelector()`, then `document.querySelector()` to find it. |
+| `data-levels`  | no       | `h2`           | Comma-separated list of heading tags to include, e.g. `h2,h3`.                                                                                                                    |
+| `data-title`   | no       | `On this page` | Text used to generate the `<h2>` title when one is not present.                                                                                                                   |
+
+**Web Component behaviour notes:**
+
+- If the `<nav>` already contains `<a>` links, the JS leaves the list alone and only binds the click handler — it still resolves each link's `hash` against the container so clicking sets `is-active`.
+- If the `<nav>` is empty, the JS generates a heading (`<h2 class="is-excluded mx-heading--m">`) and one `<li class="mx-in-page-navigation__level--h{n}">` per matched heading.
+- Headings with the class `is-excluded` are skipped.
+- A heading can override its link label via a `data-in-page-navigation-title` attribute on the heading element.
+- The `is-active` class is toggled **on click only**. There is no IntersectionObserver / scroll-spy — active state does not follow scroll position.
+- If `data-content` resolves to a container with zero matching headings, the `<nav>` renders empty and CSS hides the whole element (`mx-in-page-navigation:has(.mx-nav:empty) { display: none }`).
+
+## React
+
+```tsx
+import { useRef } from "react"
+import { InPageNavigation, Sidebar } from "@pnx-mixtape/mxds/react"
+
+const Page = () => {
+  const contentRef = useRef<HTMLElement>(null)
+  return (
+    <Sidebar before sidebar={<InPageNavigation containerRef={contentRef} />}>
+      <section ref={contentRef} className="mx-vertical-flow">
+        <h2>Section 1</h2>
+        <p>...</p>
+        <h2>Section 2</h2>
+        <p>...</p>
+        <h3>Test level 3</h3>
+        <p>...</p>
+      </section>
+    </Sidebar>
+  )
+}
+```
+
+**`InPageNavigation` props:**
+
+| Prop           | Type                     | Default          | Description                                                                                                                       |
+| -------------- | ------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `title`        | `string`                 | `"On this page"` | Text for the heading rendered above the list.                                                                                     |
+| `containerRef` | `RefObject<HTMLElement>` | —                | Ref to the content container whose headings should be indexed. Falls back to `document.querySelector("section")` if not provided. |
+| `levels`       | `string`                 | `"h2, h3"`       | CSS selector string of heading levels to include.                                                                                 |
+
+**Behaviour:** The `useInPageNavigation` hook queries the ref (or the first `<section>`) for headings matching `levels`, assigns an `id` (slugified from text) to any heading without one, and returns the list. The component renders a `<nav class="mx-in-page-navigation mx-nav mx-nav--list">` with an embellished `<h2>` title and a `<ul>` of anchor links, each with a chevron-right icon.
+
+> **Note:** The React version does not compose with a Web Component and does not apply scroll-spy. Active-link styling is not applied on click either — it is CSS link-state based only.
+
+---
+
+## Modifiers
+
+### Level classes (applied automatically)
+
+Each generated `<li>` is tagged with its source heading level so nested levels can be indented:
+
+| Class                                     | Source heading | Visual intent                                                                                     |
+| ----------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------- |
+| `mx-in-page-navigation__level--h2`        | `<h2>`         | Top level, no indent                                                                              |
+| `mx-in-page-navigation__level--h3`        | `<h3>`         | Indented by `var(--indent, var(--spacing-s))`                                                     |
+| `mx-in-page-navigation__level--h4`…`--h6` | `<h4>`–`<h6>`  | Generated if requested via `data-levels`, but only `--h3` has a styled indent in the shipped CSS. |
+
+### State class
+
+| Class       | Trigger                                 | Meaning                                                                   |
+| ----------- | --------------------------------------- | ------------------------------------------------------------------------- |
+| `is-active` | Added to `<a>` on click inside the list | Currently-selected section link. Removed from all siblings on each click. |
+
+There are no size / colour modifier enums for this component.
+
+---
+
+## Accessibility
+
+- The outer element is a `<nav>` — give it a label if multiple `<nav>` blocks exist on the page. The shipped templates rely on the `<h2>` inside the `<nav>` for its accessible name; if you remove the title, add `aria-label="On this page"` (or `aria-labelledby`) yourself.
+- The title heading uses the `is-excluded` class so the Web Component will not re-index it as a section link.
+- Each item is a standard anchor (`<a href="#id">`) — keyboard-navigable by default. Activating a link performs a native in-page jump, which moves focus to the target heading when the browser supports it (Safari and Firefox require `tabindex="-1"` on the target for focus to land; add this if you need robust focus management).
+- `aria-current="location"` is **not** currently set by the component on the active link — if you are building a prototype that needs true scroll-spy with `aria-current="location"`, you will need to layer an IntersectionObserver on top.
+- The chevron-right glyph is rendered via the `mx-icon mx-icon--chevron-right` class on a decorative `<span>`; it is not announced as content.
+- If the container has no matching headings, the nav hides itself via CSS (`:has(.mx-nav:empty)`) — screen readers will not encounter an empty landmark.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-in-page-navigation {
+  --link-colour: var(--colour-link); /* anchor colour */
+  --nav-underline: underline; /* anchor text-decoration */
+  --indent: var(--spacing-s); /* indent applied to h3 items */
+}
+```
+
+The component also inherits `--flow-gap` / `--gap` for its block-end margin when it is not the only child of its parent.
+
+---
+
+→ Used in context: `mockups/ArticlePage.stories.ts:19`

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

@@ -1,3 +1,3 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`In Page Navigation 1`] = `"<div class="mx-grid--sidebar"><aside><nav class="mx-in-page-navigation mx-nav mx-nav--list"><h2 class="mx-text--embellished-headline" id="on-this-page">On this page</h2><ul><li class="mx-in-page-navigation__level--h2"><a href="#section-1" class="mx-icon mx-icon--chevron-right">Section 1</a></li><li class="mx-in-page-navigation__level--h2"><a href="#anchor-test" class="mx-icon mx-icon--chevron-right">Section 2</a></li><li class="mx-in-page-navigation__level--h2"><a href="#test-level-3" class="mx-icon mx-icon--chevron-right">Test level 3</a></li><li class="mx-in-page-navigation__level--h2"><a href="#section-3" class="mx-icon mx-icon--chevron-right">Section 3</a></li><li class="mx-in-page-navigation__level--h2"><a href="#section-4" class="mx-icon mx-icon--chevron-right">Section 4</a></li><li class="mx-in-page-navigation__level--h2"><a href="#section-5" class="mx-icon mx-icon--chevron-right">Section 5</a></li><li class="mx-in-page-navigation__level--h2"><a href="#test-level-6" class="mx-icon mx-icon--chevron-right">Test level 6</a></li><li class="mx-in-page-navigation__level--h2"><a href="#section-7" class="mx-icon mx-icon--chevron-right">Section 7</a></li></ul></nav></aside><section><div class="mx-vertical-flow"><h2 class="" level="h2" id="section-1">Section 1</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" id="anchor-test" level="h2">Section 2</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" level="h3" id="test-level-3">Test level 3</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" level="h2" id="section-3">Section 3</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" level="h2" id="section-4">Section 4</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" level="h2" id="section-5">Section 5</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" level="h3" id="test-level-6">Test level 6</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" level="h2" id="section-7">Section 7</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p></div></section></div>"`;
+exports[`In Page Navigation 1`] = `"<div class="mx-vertical-flow"><nav class="mx-in-page-navigation mx-nav mx-nav--list mx-vertical-flow"><h2 class="mx-heading--m" id="on-this-page">On this page</h2><ul><li class="mx-in-page-navigation__level--h2"><a href="#section-1" class="mx-icon mx-icon--chevron-right">Section 1</a></li><li class="mx-in-page-navigation__level--h2"><a href="#anchor-test" class="mx-icon mx-icon--chevron-right">Section 2</a></li><li class="mx-in-page-navigation__level--h3"><a href="#test-level-3" class="mx-icon mx-icon--chevron-right">Test level 3</a></li><li class="mx-in-page-navigation__level--h2"><a href="#section-3" class="mx-icon mx-icon--chevron-right">Section 3</a></li><li class="mx-in-page-navigation__level--h2"><a href="#section-4" class="mx-icon mx-icon--chevron-right">Section 4</a></li><li class="mx-in-page-navigation__level--h2"><a href="#section-5" class="mx-icon mx-icon--chevron-right">Section 5</a></li><li class="mx-in-page-navigation__level--h3"><a href="#test-level-6" class="mx-icon mx-icon--chevron-right">Test level 6</a></li><li class="mx-in-page-navigation__level--h2"><a href="#section-7" class="mx-icon mx-icon--chevron-right">Section 7</a></li></ul></nav><section class="mx-vertical-flow mx-rich-text"><h2 class="" id="section-1">Section 1</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" id="anchor-test">Section 2</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h3 class="" id="test-level-3">Test level 3</h3><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" id="section-3">Section 3</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" id="section-4">Section 4</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" id="section-5">Section 5</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h3 class="" id="test-level-6">Test level 6</h3><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p><h2 class="" id="section-7">Section 7</h2><p class="">In publishing and graphic design, lorem ipsum is a placeholder text commonly used to demonstrate the visual form of a document without relying on meaningful content. Replacing the actual content with placeholder text allows designers to design the form of the content before the content itself has been produced.</p></section></div>"`;

package/src/Component/InPageNavigation/in-page-navigation.css

@@ -24,5 +24,17 @@
     & .mx-in-page-navigation__level--h3 {
       padding-inline-start: var(--indent, var(--spacing-s));
     }
+
+    & .mx-in-page-navigation__level--h4 {
+      padding-inline-start: calc(var(--indent, var(--spacing-s)) * 2);
+    }
+
+    & .mx-in-page-navigation__level--h5 {
+      padding-inline-start: calc(var(--indent, var(--spacing-s)) * 3);
+    }
+
+    & .mx-in-page-navigation__level--h6 {
+      padding-inline-start: calc(var(--indent, var(--spacing-s)) * 4);
+    }
   }
 }

package/src/Component/InPageNavigation/in-page-navigation.twig

@@ -5,17 +5,15 @@
   'mx-vertical-flow'
 ] %}
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
-<mx-in-page-navigation data-content=".js-content" data-levels="{{ levels|join(",") }}" data-title="{{ title|striptags|trim }}">
-  {% spaceless %}
+<mx-in-page-navigation data-content="{{ contentSelector|default('.js-content') }}" data-levels="{{ levels|join(",") }}" data-title="{{ title|striptags|trim }}">
+  {% apply spaceless %}
   <nav{{ attributes }}>
     {% if items %}
       {{ title }}
       <ul>
-        {% for item in items %}
-          <li>{{ item }}</li>
-        {% endfor %}
+        {{ items }}
       </ul>
     {% endif %}
   </nav>
-  {% endspaceless %}
+  {% endapply %}
 </mx-in-page-navigation>

package/src/Component/LinkList/LinkList.figma.ts

@@ -0,0 +1,17 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=83-305
+// source=src/Component/LinkList/LinkList.tsx
+// component=LinkList
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const content = instance.getSlot("Content")
+
+export default {
+  example: figma.code`<LinkList>${content}</LinkList>`,
+  imports: ['import { LinkList } from "@pnx-mixtape/mxds/react"'],
+  id: "link-list",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/LinkList/LinkList.stories.ts

@@ -17,6 +17,7 @@ const meta: Meta<typeof Component> = {
       Link({
         title: "Music",
         href: "#",
+        listItem: true,
         iconEnd: Icon({
           icon: Icons.CHEVRON_RIGHT,
         }),
@@ -24,6 +25,7 @@ const meta: Meta<typeof Component> = {
       Link({
         title: "Performances",
         href: "#",
+        listItem: true,
         iconEnd: Icon({
           icon: Icons.CHEVRON_RIGHT,
         }),
@@ -31,11 +33,12 @@ const meta: Meta<typeof Component> = {
       Link({
         title: "Get involved",
         href: "#",
+        listItem: true,
         iconEnd: Icon({
           icon: Icons.CHEVRON_RIGHT,
         }),
       }),
-    ],
+    ].join(""),
   },
   argTypes: {
     title: {
@@ -46,14 +49,14 @@ const meta: Meta<typeof Component> = {
       },
     },
     items: {
-      description: `A list of [Link](/?path=/docs/atom-link--docs) objects to use for the menu. These should include the \`${Icons.CHEVRON_RIGHT}\` [Icon](/?path=/docs/atom-icon--docs)`,
+      description: `A concatenated string of [Link](/?path=/docs/atom-link--docs) markup (with \`listItem: true\`) to use for the menu. These should include the \`${Icons.CHEVRON_RIGHT}\` [Icon](/?path=/docs/atom-icon--docs)`,
       type: {
         name: "other",
         required: true,
-        value: "array",
+        value: "string",
       },
       table: {
-        type: { summary: "Link[]" },
+        type: { summary: "string" },
       },
     },
   },

package/src/Component/LinkList/LinkListItem.figma.ts

@@ -0,0 +1,20 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=83-300
+// source=src/Component/LinkList/LinkList.tsx
+// component=LinkListItem
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const content = instance.getSlot("Content")
+
+// `icon` (Icons, defaults to CHEVRON_RIGHT) not modelled as a swappable property —
+// only one directional chevron vector traced so far (see Icon component's own scope
+// note); the default is the honest, always-correct case.
+export default {
+  example: figma.code`<LinkListItem to="#">${content}</LinkListItem>`,
+  imports: ['import { LinkListItem } from "@pnx-mixtape/mxds/react"'],
+  id: "link-list-item",
+  metadata: {
+    nestable: true,
+  },
+}