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

package/src/Component/InPageNavigation/Elements/InPageNavigation.ts

@@ -32,9 +32,10 @@ export default class InPageNavigation extends HTMLElement {
       ) as HTMLHeadingElement
       this.nav.insertBefore(headingElement, this.menu)
       // Build links if not provided.
+      const counts: Record<string, number> = {}
       this.headings.forEach((heading: HTMLHeadingElement) => {
         const listItem: HTMLLIElement = this.generateListItem(heading)
-        const link: HTMLAnchorElement = this.generateAnchor(heading)
+        const link: HTMLAnchorElement = this.generateAnchor(heading, counts)
         this.items.push({ link, heading })
         listItem.appendChild(link)
         this.menu?.appendChild(listItem)
@@ -119,16 +120,20 @@ export default class InPageNavigation extends HTMLElement {
     return this.menu?.querySelectorAll("a")
   }
 
-  generatedId(heading: HTMLHeadingElement): string {
+  generatedId(heading: HTMLHeadingElement, counts: Record<string, number>): string {
     const string: string | undefined = heading?.textContent?.trim()
-    return !string ? "" : makeAnchor(string)
+    if (!string) return ""
+    const base: string = makeAnchor(string)
+    const index: number = counts[base] ?? 0
+    counts[base] = index + 1
+    return index > 0 ? `${base}-${index}` : base
   }
 
-  generateAnchor(heading: HTMLHeadingElement): HTMLAnchorElement {
+  generateAnchor(heading: HTMLHeadingElement, counts: Record<string, number>): HTMLAnchorElement {
     const { textContent, id } = heading
     const linkText: string | null =
       heading.getAttribute("data-in-page-navigation-title") || textContent
-    const targetID: string = id || this.generatedId(heading)
+    const targetID: string = id || this.generatedId(heading, counts)
     if (!id) heading.id = targetID
     const item: Element = createElement(
       `<a href="#${targetID}"><span class="mx-icon mx-icon--chevron-right"></span><span>${linkText}</span></a>`,

package/src/Component/InPageNavigation/Hooks/useInPageNavigation.ts

@@ -23,17 +23,22 @@ const useInPageNavigation = ({
     const context = ref?.current || document.querySelector("section")
     const headingElements: Element[] = [...context.querySelectorAll(levels)]
 
+    const counts: Record<string, number> = {}
     const values: HeadingType[] = headingElements.map(
-      ({ textContent: text, id, localName }: Element) =>
-        ({
-          id: id || makeAnchor(text),
+      ({ textContent: text, id, localName }: Element) => {
+        const base: string = makeAnchor(text)
+        const index: number = counts[base] ?? 0
+        counts[base] = index + 1
+        return {
+          id: id || (index > 0 ? `${base}-${index}` : base),
           text: text,
           level: localName,
-        }) as HeadingType,
+        } as HeadingType
+      },
     )
     setHeadings([...new Set(values)])
     headingElements.forEach((heading: HTMLHeadingElement, index: number): void => {
-      if (!heading.id) heading.id = values[index].id
+      heading.id = values[index].id
     })
   }, [ref, levels])
 

package/src/Component/InPageNavigation/InPageNavigation.stories.ts

@@ -1,5 +1,7 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
+import { expect } from "storybook/test"
 import Component from "./twig/in-page-navigation-story.twig"
+import Default from "./twig/in-page-navigation-story-duplicate-headings.twig"
 import Other from "./twig/in-page-navigation-selector.twig"
 import "./in-page-navigation.css"
 import "./Elements/InPageNavigation"
@@ -119,6 +121,37 @@ export const NoHeadings: Story = {
   },
 }
 
+/**
+ * Duplicate heading text: the javascript ensures generated ids stay unique.
+ */
+export const IdenticalHeadings: Story = {
+  args: {
+    items: "",
+    levels: [HeadingTypes.TWO, HeadingTypes.THREE],
+  },
+  render: args => Default(args),
+  play: async ({ canvasElement, step }) => {
+    const links: HTMLAnchorElement[] = [
+      ...canvasElement.querySelectorAll<HTMLAnchorElement>(".mx-in-page-navigation a"),
+    ]
+    const ids: string[] = links.map(({ hash }: HTMLAnchorElement) => hash.slice(1))
+
+    await step("Repeated heading text is suffixed, the first stays unsuffixed", async () => {
+      await expect(ids.filter((id: string) => id.startsWith("identical-heading"))).toEqual([
+        "identical-heading",
+        "identical-heading-1",
+        "identical-heading-2",
+      ])
+    })
+
+    await step("Every link targets a heading that exists", async () => {
+      const missing: string[] = ids.filter((id: string) => !canvasElement.querySelector(`#${id}`))
+      await expect(missing).toEqual([])
+      await expect(new Set(ids).size).toBe(ids.length)
+    })
+  },
+}
+
 /**
  * Generated items from anywhere in the page: page content contains headings, but not within the container element.
  */

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

@@ -5,6 +5,7 @@ import Text from "../../Atom/Text/Text"
 import Component from "./InPageNavigation"
 import "./in-page-navigation.css"
 import { Page } from "../../../.storybook-react/decorators"
+import { expect } from "storybook/test"
 
 const meta: Meta<typeof Component> = {
   tags: ["autodocs"],
@@ -76,3 +77,54 @@ const meta: Meta<typeof Component> = {
 }
 export default meta
 export const InPageNavigation: StoryObj<typeof Component> = {}
+
+export const IdenticalHeadings: StoryObj<typeof Component> = {
+  render: () => (
+    <div className="mx-vertical-flow">
+      <Component />
+      <section className="mx-vertical-flow mx-rich-text">
+        <Heading>Identical heading</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>Identical heading</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>Identical heading</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>
+      </section>
+    </div>
+  ),
+  play: async ({ canvasElement, step }) => {
+    const links: HTMLAnchorElement[] = [
+      ...canvasElement.querySelectorAll<HTMLAnchorElement>(".mx-in-page-navigation a"),
+    ]
+    const ids: string[] = links.map(({ hash }: HTMLAnchorElement) => hash.slice(1))
+
+    await step("Repeated heading text is suffixed, the first stays unsuffixed", async () => {
+      await expect(ids.filter((id: string) => id.startsWith("identical-heading"))).toEqual([
+        "identical-heading",
+        "identical-heading-1",
+        "identical-heading-2",
+      ])
+    })
+
+    await step("Every link targets a heading that exists", async () => {
+      const missing: string[] = ids.filter((id: string) => !canvasElement.querySelector(`#${id}`))
+      await expect(missing).toEqual([])
+      await expect(new Set(ids).size).toBe(ids.length)
+    })
+  },
+}

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

@@ -16,6 +16,32 @@ exports[`Generated Items 1`] = `
 "
 `;
 
+exports[`Identical Headings 1`] = `
+"<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"><h2 class="is-excluded mx-heading--m">On this page</h2><ul><li class="mx-in-page-navigation__level--h2"><a href="#section-1"><span class="mx-icon mx-icon--chevron-right"></span><span>Section 1</span></a></li><li class="mx-in-page-navigation__level--h2"><a href="#section-2"><span class="mx-icon mx-icon--chevron-right"></span><span>Section 2</span></a></li><li class="mx-in-page-navigation__level--h3"><a href="#test-level-3"><span class="mx-icon mx-icon--chevron-right"></span><span>Test level 3</span></a></li><li class="mx-in-page-navigation__level--h2"><a href="#section-3"><span class="mx-icon mx-icon--chevron-right"></span><span>Section 3</span></a></li><li class="mx-in-page-navigation__level--h2"><a href="#identical-heading"><span class="mx-icon mx-icon--chevron-right"></span><span>Identical heading</span></a></li><li class="mx-in-page-navigation__level--h3"><a href="#identical-subheading"><span class="mx-icon mx-icon--chevron-right"></span><span>Identical subheading</span></a></li><li class="mx-in-page-navigation__level--h3"><a href="#identical-heading-1"><span class="mx-icon mx-icon--chevron-right"></span><span>Identical heading</span></a></li><li class="mx-in-page-navigation__level--h3"><a href="#identical-subheading-1"><span class="mx-icon mx-icon--chevron-right"></span><span>Identical subheading</span></a></li><li class="mx-in-page-navigation__level--h2"><a href="#identical-heading-2"><span class="mx-icon mx-icon--chevron-right"></span><span>Identical heading</span></a></li></ul></nav></mx-in-page-navigation>
+<div class="js-content mx-rich-text mx-vertical-flow">
+<h2 id="section-1">Section 1</h2>
+<p>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 id="section-2">Section 2</h2>
+<p>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 id="test-level-3">Test level 3</h3>
+<p>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 id="section-3">Section 3</h2>
+<p>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 id="identical-heading">Identical heading</h2>
+<p>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 id="identical-subheading">Identical subheading</h3>
+<p>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 id="identical-heading-1">Identical heading</h3>
+<p>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 id="identical-subheading-1">Identical subheading</h3>
+<p>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 id="identical-heading-2">Identical heading</h2>
+<p>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>
+"
+`;
+
 exports[`In Page Navigation 1`] = `
 "<mx-in-page-navigation data-content=".js-content" data-levels="" data-title="On this page">
   <nav class="mx-nav mx-nav--list mx-in-page-navigation mx-vertical-flow"><h2 class="is-excluded mx-heading--m">On this page</h2><ul><li><a href="#section-1"><span class="mx-icon mx-icon--chevron-right"></span><span>Section 1</span></a></li><li><a href="#section-2"><span class="mx-icon mx-icon--chevron-right"></span><span>Section 2</span></a></li><li><a href="#section-3"><span class="mx-icon mx-icon--chevron-right"></span><span>Section 3</span></a></li></ul></nav></mx-in-page-navigation>

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

@@ -1,3 +1,5 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`Identical Headings 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="#identical-heading" class="mx-icon mx-icon--chevron-right">Identical heading</a></li><li class="mx-in-page-navigation__level--h2"><a href="#identical-heading-1" class="mx-icon mx-icon--chevron-right">Identical heading</a></li><li class="mx-in-page-navigation__level--h2"><a href="#identical-heading-2" class="mx-icon mx-icon--chevron-right">Identical heading</a></li></ul></nav><section class="mx-vertical-flow mx-rich-text"><h2 class="" id="identical-heading">Identical heading</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="identical-heading-1">Identical heading</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="identical-heading-2">Identical heading</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>"`;
+
 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/twig/content-example-duplicate-headings.twig

@@ -0,0 +1,20 @@
+<div class="js-content mx-rich-text mx-vertical-flow">
+<h2 id="section-1">Section 1</h2>
+<p>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 id="section-2">Section 2</h2>
+<p>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 id="test-level-3">Test level 3</h3>
+<p>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 id="section-3">Section 3</h2>
+<p>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>Identical heading</h2>
+<p>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>Identical subheading</h3>
+<p>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>Identical heading</h3>
+<p>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>Identical subheading</h3>
+<p>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>Identical heading</h2>
+<p>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>

package/src/Component/InPageNavigation/twig/in-page-navigation-story-duplicate-headings.twig

@@ -0,0 +1,2 @@
+{% include "../in-page-navigation.twig" with { title: title, levels: levels } %}
+{% include "./content-example-duplicate-headings.twig" %}

package/src/Component/ListItem/__snapshots__/ListItem.stories.ts.snap

@@ -25,7 +25,7 @@ exports[`Image Reverse 1`] = `
 <article class="mx-card mx-list-item mx-card--collapse mx-card--reversed">
   <div class="mx-card__content mx-vertical-flow">
           <strong class="mx-text--s">Publication</strong>
-              <div class="mx-text--s">25 May 2025</div>
+              <div class="mx-text--meta">25 May 2025</div>
         <div class="mx-heading--l">
       
 <a href="#">
@@ -73,7 +73,7 @@ exports[`With Image 1`] = `
 <article class="mx-card mx-list-item mx-card--collapse">
   <div class="mx-card__content mx-vertical-flow">
           <strong class="mx-text--s">Publication</strong>
-              <div class="mx-text--s">25 May 2025</div>
+              <div class="mx-text--meta">25 May 2025</div>
         <div class="mx-heading--l">
       
 <a href="#">
@@ -101,7 +101,7 @@ exports[`With Info 1`] = `
 <article class="mx-card mx-list-item">
   <div class="mx-card__content mx-vertical-flow">
           <strong class="mx-text--s">Publication</strong>
-              <div class="mx-text--s">25 May 2025</div>
+              <div class="mx-text--meta">25 May 2025</div>
         <div class="mx-heading--l">
       
 <a href="#">
@@ -166,7 +166,7 @@ exports[`With Url 1`] = `
 </a>
 
     </div>
-          <div class="mx-text--s">https://example.com/some-thing</div>
+          <div class="mx-text--meta">https://example.com/some-thing</div>
         <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</p>
     
   </div>

package/src/Component/ListItem/list-item.twig

@@ -15,13 +15,13 @@
       <strong class="mx-text--s">{{ label }}</strong>
     {% endif %}
     {% if info is not empty and infoBefore %}
-      <div class="mx-text--s">{{ info }}</div>
+      <div class="mx-text--meta">{{ info }}</div>
     {% endif %}
     <div class="mx-heading--l">
       {{ link }}
     </div>
     {% if info is not empty and not infoBefore %}
-      <div class="mx-text--s">{{ info }}</div>
+      <div class="mx-text--meta">{{ info }}</div>
     {% endif %}
     {{ content }}
     {{ tags }}

package/src/Component/Navigation/_navigation.css

@@ -4,7 +4,7 @@
 
 @layer design-system.atoms {
   .mx-nav {
-    --colour-link: var(--link-colour, currentcolor);
+    --link-colour: currentcolor;
 
     &:where(:not(:has(ul))),
     ul {

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

@@ -117,14 +117,18 @@ type Story = StoryObj<PaginationType>
 // click/keyboard interaction to test here, just the ARIA structure.
 export const Pagination: Story = {
   play: async ({ canvas, step }) => {
+    const prev = canvas.getByRole("link", { name: /Previous/ })
+    const next = canvas.getByRole("link", { name: /Next/ })
+    const link1 = canvas.getByRole("link", { name: "1", hidden: true })
+    const link2 = canvas.getByRole("link", { name: "2", hidden: true })
     await step("Current page is marked with aria-current", async () => {
-      await expect(canvas.getByRole("link", { name: "2" })).toHaveAttribute("aria-current", "page")
-      await expect(canvas.getByRole("link", { name: "1" })).not.toHaveAttribute("aria-current")
+      await expect(link2).toHaveAttribute("aria-current", "page")
+      await expect(link1).not.toHaveAttribute("aria-current")
     })
 
     await step("Previous/next links are present", async () => {
-      await expect(canvas.getByRole("link", { name: /Previous/ })).toBeInTheDocument()
-      await expect(canvas.getByRole("link", { name: /Next/ })).toBeInTheDocument()
+      await expect(prev).toBeInTheDocument()
+      await expect(next).toBeInTheDocument()
     })
   },
 }

package/src/Component/Pagination/pagination.css

@@ -2,7 +2,7 @@
  * Pagination
  */
 
-@import "@pnx-mixtape/mxds/Utility/_mixins.css";
+@import "../../Utility/_mixins.css";
 
 @layer design-system.components {
   .mx-pagination {
@@ -103,10 +103,10 @@
       text-transform: capitalize;
 
       & span:where(:not(.mx-icon)) {
-        @mixin sr-only;
+        @add-mixin sr-only;
 
         @container pagination (min-width: 25ch) {
-          @mixin sr-undo;
+          @add-mixin sr-undo;
         }
       }
     }

package/src/Component/ProgressIndicator/ProgressIndicator.stories.ts

@@ -0,0 +1,36 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import Component from "./progress-indicator.twig"
+import "./progress-indicator.css"
+
+type ProgressIndicatorProps = {
+  steps: string[]
+  current: number
+}
+
+const steps = ["Your card", "Your details", "Your income", "Evidence", "Review and submit"]
+
+const meta: Meta<ProgressIndicatorProps> = {
+  tags: ["autodocs"],
+  component: Component,
+  args: {
+    steps,
+    current: 1,
+  },
+}
+
+export default meta
+type Story = StoryObj<ProgressIndicatorProps>
+
+export const ProgressIndicator: Story = {}
+
+export const MiddleStep: Story = {
+  args: {
+    current: 3,
+  },
+}
+
+export const LastStep: Story = {
+  args: {
+    current: 5,
+  },
+}

package/src/Component/ProgressIndicator/ProgressIndicator.stories.tsx

@@ -0,0 +1,30 @@
+import { Meta, StoryObj } from "@storybook/react-vite"
+import Component from "./ProgressIndicator"
+import "./progress-indicator.css"
+import { Page } from "../../../.storybook-react/decorators"
+
+const steps = ["Your card", "Your details", "Your income", "Evidence", "Review and submit"]
+
+const meta: Meta<typeof Component> = {
+  component: Component,
+  decorators: [Page],
+  args: {
+    steps,
+    current: 1,
+  },
+}
+
+export default meta
+export const ProgressIndicator: StoryObj<typeof meta> = {}
+
+export const MiddleStep: StoryObj<typeof meta> = {
+  args: {
+    current: 3,
+  },
+}
+
+export const LastStep: StoryObj<typeof meta> = {
+  args: {
+    current: 5,
+  },
+}

package/src/Component/ProgressIndicator/ProgressIndicator.tsx

@@ -0,0 +1,60 @@
+import { JSX } from "react"
+import classNames from "classnames"
+import { validators } from "../../Utility/utilities"
+
+type ProgressIndicatorProps = {
+  steps: string[]
+  current: number
+  className?: string
+}
+
+const ProgressIndicator = ({
+  steps,
+  current,
+  className = null,
+}: ProgressIndicatorProps): JSX.Element => {
+  const total = steps.length
+  const currentStep = validators.integer(current, 1, total) ? current : 1
+
+  return (
+    <div className={classNames("mx-progress-indicator", className)}>
+      <p className="mx-progress-indicator__count">
+        Step {currentStep} of {total} — {steps[currentStep - 1]}
+      </p>
+      <div className="mx-progress-indicator__track" aria-hidden="true">
+        {steps.map((step, index) => {
+          const position = index + 1
+
+          return (
+            <i
+              key={`${step}-${position}`}
+              className={classNames("mx-progress-indicator__marker", {
+                "mx-progress-indicator__marker--done": position < currentStep,
+                "mx-progress-indicator__marker--now": position === currentStep,
+              })}
+            />
+          )
+        })}
+      </div>
+      <ol className="mx-progress-indicator__steps">
+        {steps.map((step, index) => {
+          const position = index + 1
+
+          return (
+            <li
+              key={`${step}-${position}`}
+              className={classNames("mx-progress-indicator__step", {
+                "mx-progress-indicator__step--done": position < currentStep,
+              })}
+              aria-current={position === currentStep ? "step" : undefined}
+            >
+              {step}
+            </li>
+          )
+        })}
+      </ol>
+    </div>
+  )
+}
+
+export default ProgressIndicator

package/src/Component/ProgressIndicator/README.md

@@ -0,0 +1,111 @@
+# ProgressIndicator
+
+A horizontal step-progress tracker for multi-step forms and wizards — a status sentence, a segmented bar, and a list of step names, with the current step highlighted. Presentational only: the parent application owns the step-switching logic and re-renders with an updated `current` prop/value.
+
+---
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/ProgressIndicator/progress-indicator.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/ProgressIndicator/progress-indicator.twig' with {
+  steps: ['Your card', 'Your details', 'Your income', 'Evidence', 'Review and submit'],
+  current: 2,
+} %}
+```
+
+**progress-indicator.twig props:**
+
+| Prop         | Type        | Required | Description                                         |
+| ------------ | ----------- | -------- | --------------------------------------------------- |
+| `steps`      | `string[]`  | Yes      | Ordered list of step labels                         |
+| `current`    | `int`       | Yes      | 1-indexed position of the active step               |
+| `attributes` | `Attribute` | No       | Optional Drupal-style attributes object on the root |
+
+`steps` is treated as plain data (fixed step names for one form), not editorial content — each label renders as a bare list item, so it's looped directly rather than passed as a pre-joined string.
+
+---
+
+## HTML
+
+```html
+<div class="mx-progress-indicator">
+  <p class="mx-progress-indicator__count">Step 2 of 5 — Your details</p>
+  <div class="mx-progress-indicator__track" aria-hidden="true">
+    <i class="mx-progress-indicator__marker mx-progress-indicator__marker--done"></i>
+    <i class="mx-progress-indicator__marker mx-progress-indicator__marker--now"></i>
+    <i class="mx-progress-indicator__marker"></i>
+    <i class="mx-progress-indicator__marker"></i>
+    <i class="mx-progress-indicator__marker"></i>
+  </div>
+  <ol class="mx-progress-indicator__steps">
+    <li class="mx-progress-indicator__step mx-progress-indicator__step--done">Your card</li>
+    <li class="mx-progress-indicator__step" aria-current="step">Your details</li>
+    <li class="mx-progress-indicator__step">Your income</li>
+    <li class="mx-progress-indicator__step">Evidence</li>
+    <li class="mx-progress-indicator__step">Review and submit</li>
+  </ol>
+</div>
+```
+
+---
+
+## React
+
+```tsx
+import { ProgressIndicator } from "@pnx-mixtape/mxds/react"
+
+;<ProgressIndicator
+  steps={["Your card", "Your details", "Your income", "Evidence", "Review and submit"]}
+  current={2}
+/>
+```
+
+**`ProgressIndicator` props:**
+
+| Prop        | Type       | Default | Description                           |
+| ----------- | ---------- | ------- | ------------------------------------- |
+| `steps`     | `string[]` | —       | Ordered list of step labels           |
+| `current`   | `number`   | —       | 1-indexed position of the active step |
+| `className` | `string`   | —       | Extra class on the root               |
+
+---
+
+## Modifiers
+
+There are no BEM modifier classes to apply by hand — the per-step `--done`/`--now` states on the track markers and step list are derived automatically from comparing each step's position against `current`.
+
+---
+
+## Accessibility
+
+- The segmented track (`mx-progress-indicator__track`) is `aria-hidden` — it's a decorative echo of progress, not the source of truth.
+- The real status is the `mx-progress-indicator__count` sentence ("Step 2 of 5 — Your details") and the `<ol>` of step names, with `aria-current="step"` on the active one — both are read by screen readers as ordinary text/list content.
+- The `::before` checkmark on completed steps (`mx-progress-indicator__step--done`) is a visual-only enhancement; completion is already conveyed by list order relative to `aria-current`, so its absence from some assistive tech's generated-content support doesn't lose information.
+- On navigation, the consuming application is responsible for moving focus to the new step's heading (or an error summary, if validation fails) — this component doesn't manage focus itself, same as it doesn't manage step-switching.
+
+---
+
+## Customisation
+
+| Custom property            | Applies to                                                               | Default                 |
+| -------------------------- | ------------------------------------------------------------------------ | ----------------------- |
+| `--gap`                    | `.mx-progress-indicator`                                                 | `var(--spacing-xs)`     |
+| `--track-gap`              | `.mx-progress-indicator__track`                                          | `var(--spacing-xxxs)`   |
+| `--marker-size`            | `.mx-progress-indicator__track`                                          | `var(--spacing-xxxs)`   |
+| `--marker-colour`          | `.mx-progress-indicator__track`                                          | `var(--colour-border)`  |
+| `--marker-colour-complete` | `.mx-progress-indicator__track`                                          | `var(--colour-primary)` |
+| `--marker-colour-active`   | `.mx-progress-indicator__track` and active `mx-progress-indicator__step` | `var(--colour-primary)` |
+
+```css
+.theme--health-services .mx-progress-indicator {
+  font-family: var(--font-family-display);
+}
+```