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

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

@@ -0,0 +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[`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[`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>"`;

package/src/Component/Popover/polyfills.js

@@ -3,27 +3,62 @@
  * @see https://drafts.csswg.org/css-anchor-position-1/
  * @see https://developer.mozilla.org/en-US/docs/Web/API/Popover_API#browser_compatibility
  */
-import { computePosition } from "@floating-ui/dom"
+let popoverPolyfillPromise
 
 export default class Polyfills {
   constructor(popover) {
     this.popover = popover
-    this.trigger = document.querySelector(`[popovertarget="${popover.getAttribute("id")}"`)
-    this.positionPopover = this.positionPopover.bind(this)
-    this.popover.addEventListener("toggle", this.positionPopover)
+    this.trigger = document.querySelector(`[popovertarget="${popover.getAttribute("id")}"]`)
+    this.init()
   }
 
-  positionPopover = ({ newState }) => {
+  init = async () => {
+    if (!this.trigger || !this.popover) return
+    if (!this.supportsPopover()) {
+      await this.ensurePopoverPolyfill()
+    }
+    if (!this.supportsAnchor()) {
+      this.controller = new AbortController()
+      this.popover.addEventListener("toggle", this.positionPopover, {
+        signal: this.controller.signal,
+      })
+    }
+  }
+
+  supportsAnchor = () => {
+    return "anchorName" in document.documentElement.style
+  }
+
+  supportsPopover = () => {
+    return "popover" in HTMLElement.prototype
+  }
+
+  ensurePopoverPolyfill = () => {
+    if (!popoverPolyfillPromise) {
+      popoverPolyfillPromise = import("@oddbird/popover-polyfill")
+    }
+    return popoverPolyfillPromise
+  }
+
+  positionPopover = async ({ newState }) => {
     if (newState === "open") {
-      computePosition(this.trigger, this.popover, {
-        placement: this.placement || "bottom-start",
-      }).then(({ x, y }) => {
-        this.popover.style.insetInlineStart = `${x}px`
-        this.popover.style.insetBlockStart = `${y}px`
+      const { computePosition, flip, shift } = await import("@floating-ui/dom")
+      requestAnimationFrame(() => {
+        computePosition(this.trigger, this.popover, {
+          placement: this.placement || "top",
+          middleware: [flip({ padding: 10 }), shift({ padding: 10 })],
+        }).then(({ x, y }) => {
+          this.popover.style.insetInlineStart = `${x}px`
+          this.popover.style.insetBlockStart = `${y}px`
+        })
       })
     }
   }
 
+  destroy() {
+    this.controller.abort()
+  }
+
   get placement() {
     return this.popover.getAttribute("data-placement")
   }

package/src/Component/Popover/popover.css

@@ -18,6 +18,7 @@
     }
   }
 
+  /* @public --popover-padding --popover-background --popover-foreground --popover-radius --popover-width */
   :where(.mx-popover) {
     display: none;
     opacity: 0;

package/src/Component/Popover/popover.twig

@@ -15,7 +15,6 @@
       aria-describedby="{{ name }}"
       style="position-anchor: --{{ id }}"
       data-placement="{{ placement }}"
-      role="tooltip"
       popover
   >
     <div class="mx-rich-text mx-vertical-flow">

package/src/Component/ResultsBar/Components/ResultsBarInfo.figma.ts

@@ -0,0 +1,21 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=95-367
+// source=src/Component/ResultsBar/Components/ResultsBarInfo.tsx
+// component=ResultsBarInfo
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const hasResults = instance.getEnum("HasResults", { Off: false, On: true })
+
+// number/pageCount/total are real numeric props that directly control which message
+// renders (no-results vs the count message) — fixed representative numbers per state.
+export default {
+  example: hasResults
+    ? figma.code`<ResultsBarInfo number={1} pageCount={10} total={42} />`
+    : figma.code`<ResultsBarInfo number={1} pageCount={0} total={0} />`,
+  imports: ['import { ResultsBarInfo } from "@pnx-mixtape/mxds/react"'],
+  id: "results-bar-info",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/ResultsBar/Components/ResultsBarSort.figma.ts

@@ -0,0 +1,15 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=95-368
+// source=src/Component/ResultsBar/Components/ResultsBarSort.tsx
+// component=ResultsBarSort
+import figma from "figma"
+
+// `options: string[]` (each string used as both value and label) is a data array,
+// not JSX — fixed representative options, same reasoning as Breadcrumb's `items`.
+export default {
+  example: figma.code`<ResultsBarSort id="sort" options={["Newest", "Oldest", "Most relevant"]} />`,
+  imports: ['import { ResultsBarSort } from "@pnx-mixtape/mxds/react"'],
+  id: "results-bar-sort",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/ResultsBar/Components/ResultsBarSort.tsx

@@ -1,12 +1,31 @@
-import { JSX } from "react"
-import FormSelect, { FormSelectProps } from "../../../Form/Select/FormSelect"
+import { JSX, ComponentPropsWithoutRef, useMemo } from "react"
+import FormSelect from "../../../Form/Select/FormSelect"
 import FormLabel from "../../../Form/Label/FormLabel"
 
-const ResultsBarSort = ({ id, name, options, ...props }: FormSelectProps): JSX.Element => (
-  <div className="mx-results-bar__sort">
-    <FormLabel id={id} text="Sort by" />
-    <FormSelect name={name} options={options} id={id} {...props} />
-  </div>
-)
+type ResultsBarSortProps = Omit<ComponentPropsWithoutRef<"select">, "options"> & {
+  /**
+   * Sort options. Each entry is used as both the option `value` and the
+   * visible label — matching the `sort: string[]` shape in `results-bar.twig`.
+   */
+  options: string[]
+  label?: string
+}
+
+const ResultsBarSort = ({
+  id,
+  name,
+  options,
+  label = "Sort by",
+  ...props
+}: ResultsBarSortProps): JSX.Element => {
+  const selectOptions = useMemo(() => options.map(value => ({ value, label: value })), [options])
+
+  return (
+    <div className="mx-results-bar__sort">
+      <FormLabel id={id} text={label} />
+      <FormSelect name={name} options={selectOptions} id={id} {...props} />
+    </div>
+  )
+}
 
 export default ResultsBarSort

package/src/Component/ResultsBar/README.md

@@ -0,0 +1,158 @@
+# ResultsBar
+
+A bar displaying the number of results available (e.g. "Showing results 1 - 10 of 250 results") and an optional sort dropdown. Typically placed above a list of search or listing results.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/ResultsBar/results-bar.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/ResultsBar/results-bar.twig' with {
+  number: 1,
+  pageCount: 10,
+  total: 250,
+  sort: ['Most recent', 'A-Z', 'Z-A'],
+} %}
+```
+
+**results-bar.twig props** (`ResultsBar` type from `ids-shape`):
+
+| Prop        | Type       | Description                                                                                                                                                  |
+| ----------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `number`    | `number`   | Index of the first result on the current page                                                                                                                |
+| `pageCount` | `number`   | Index of the last result on the current page (clamped to `total`)                                                                                            |
+| `total`     | `number`   | Total number of results                                                                                                                                      |
+| `sort`      | `string[]` | Optional list of sort option labels. Each string is used as both the `value` and display text of an `<option>`. When present, renders the `Sort by` dropdown |
+| `empty`     | `boolean`  | Shows the empty-state message and applies `mx-results-bar--empty`                                                                                            |
+
+---
+
+## HTML
+
+Minimal working markup:
+
+```html
+<div class="mx-results-bar">
+  <span aria-live="polite">Showing results 1 - 10 of 250 results</span>
+</div>
+```
+
+With sort dropdown:
+
+```html
+<div class="mx-results-bar">
+  <span aria-live="polite">Showing results 1 - 10 of 250 results</span>
+  <div class="mx-results-bar__sort">
+    <label class="mx-label" for="results-sort">Sort by</label>
+    <select class="mx-input__select" id="results-sort" name="results-sort">
+      <option value="recent">Most recent</option>
+      <option value="az">A-Z</option>
+      <option value="za">Z-A</option>
+    </select>
+  </div>
+</div>
+```
+
+Empty state:
+
+```html
+<div class="mx-results-bar mx-results-bar--empty">
+  <span aria-live="assertive" aria-atomic="true">Sorry, no results were found for your search</span>
+</div>
+```
+
+---
+
+## React
+
+Uses a composition pattern — `ResultsBar` is a wrapper, and `ResultsBarInfo` / `ResultsBarSort` are the content slots placed inside it.
+
+```tsx
+import { ResultsBar, ResultsBarInfo, ResultsBarSort } from "@pnx-mixtape/mxds/react"
+
+// Info only
+<ResultsBar>
+  <ResultsBarInfo number={1} pageCount={10} total={250} />
+</ResultsBar>
+
+// Empty state (no results found)
+<ResultsBar>
+  <ResultsBarInfo number={1} pageCount={10} total={0} />
+</ResultsBar>
+
+// With sort dropdown
+<ResultsBar>
+  <ResultsBarInfo number={1} pageCount={10} total={250} />
+  <ResultsBarSort
+    id="results-sort"
+    name="results-sort"
+    options={["Most recent", "A-Z", "Z-A"]}
+  />
+</ResultsBar>
+```
+
+**`ResultsBar` props:** accepts `children` only.
+
+**`ResultsBarInfo` props:**
+
+| Prop        | Type     | Description                                                                                 |
+| ----------- | -------- | ------------------------------------------------------------------------------------------- |
+| `number`    | `number` | The index of the first result on the current page (e.g. `1`, `11`, `21`…)                   |
+| `pageCount` | `number` | The index of the last result on the current page. Clamped to `total` if it exceeds it       |
+| `total`     | `number` | The total number of results across all pages. When `0`, the empty-state message is rendered |
+
+**`ResultsBarSort` props:**
+
+| Prop      | Type                                 | Description                                                                                                                 |
+| --------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
+| `id`      | `string`                             | Used by the associated `<label>` and the `<select>`                                                                         |
+| `name`    | `string`                             | Select element name                                                                                                         |
+| `options` | `string[]`                           | Sort options. Each entry is used as both the `<option>` `value` and visible text — matching the Twig `sort: string[]` shape |
+| `label`   | `string`                             | Visible label. Defaults to `"Sort by"`                                                                                      |
+| …rest     | `ComponentPropsWithoutRef<"select">` | Any native `<select>` attribute                                                                                             |
+
+---
+
+## Modifiers
+
+| Class                   | `ResultsBar.empty` value | Visual intent                                                    |
+| ----------------------- | ------------------------ | ---------------------------------------------------------------- |
+| `mx-results-bar`        | —                        | Default: flex row, results info aligned left, sort aligned right |
+| `mx-results-bar--empty` | `empty: true`            | Empty-state styling applied when no results are found            |
+
+---
+
+## Accessibility
+
+- The results count is wrapped in a `aria-live="polite"` region, so screen readers announce updates when pagination or filters change the count without refreshing the page.
+- The empty-state message uses `aria-live="assertive"` with `aria-atomic="true"` so "no results" is announced immediately and as a whole.
+- The sort control (`ResultsBarSort` / Twig) is a standard `<label>` + `<select>` pair — the `id` on the label's `for` attribute matches the select's `id`. This gives native keyboard and screen reader support.
+- The label text "Sort by" is a visible, persistent label — do not hide it or replace it with placeholder-only labelling.
+- When wiring this up in a real listing, make sure the live region (`ResultsBarInfo`) remains mounted across filter/sort/pagination updates so the text change is announced rather than the whole region being replaced.
+
+---
+
+## Customisation via CSS custom properties
+
+`ResultsBar` does not expose component-local CSS custom properties. Layout relies on design-system tokens — override these at a higher scope to adjust spacing:
+
+```css
+.mx-results-bar {
+  gap: var(--spacing-s); /* gap between info and sort */
+  margin-block-end: var(--spacing-m); /* spacing before the results list */
+}
+
+.mx-results-bar__sort {
+  gap: var(--spacing-s); /* gap between "Sort by" label and select */
+}
+```
+
+---
+
+→ Used in context: `mockups/ArticleListingPage.stories.ts:11`

package/src/Component/ResultsBar/ResultsBar.figma.ts

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

package/src/Component/ResultsBar/ResultsBar.stories.ts

@@ -2,6 +2,7 @@ import { Meta, StoryObj } from "@storybook/html-vite"
 import Component from "./results-bar.twig"
 import "./results-bar.css"
 import { ResultsBar as ResultsBarType } from "@pnx-mixtape/ids-shape"
+import { modes } from "../../../.storybook/modes"
 
 /**
  * A bar displaying the number of results available, and an optional sort dropdown.
@@ -41,6 +42,14 @@ const meta: Meta<ResultsBarType> = {
       },
     },
   },
+  parameters: {
+    chromatic: {
+      modes: {
+        mobile: modes["xs"],
+        desktop: modes["xl"],
+      },
+    },
+  },
 }
 
 export default meta

package/src/Component/ResultsBar/ResultsBar.stories.tsx

@@ -29,20 +29,7 @@ export const Sort: StoryObj<typeof Component> = {
       <>
         <ResultsBarInfo number={1} pageCount={10} total={250} />
         <ResultsBarSort
-          options={[
-            {
-              value: "1",
-              label: "Option 1",
-            },
-            {
-              value: "2",
-              label: "Option 2",
-            },
-            {
-              value: "3",
-              label: "Option 3",
-            },
-          ]}
+          options={["Newest", "Oldest", "Most popular"]}
           id="results-sort"
           name="results-sort"
         />

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

@@ -23,6 +23,9 @@ exports[`Sort 1`] = `
         <div class="mx-results-bar__sort">
       <label class="mx-label" for="results-sort">Sort by</label>
       <select class="mx-input__select" id="results-sort" name="results-sort">
+        <button>
+          <selectedcontent>Most recent</selectedcontent>
+        </button>
                   <option value="Most recent">Most recent</option>
                   <option value="A-Z">A-Z</option>
                   <option value="Z-A">Z-A</option>

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

@@ -4,4 +4,4 @@ exports[`Empty 1`] = `"<div class="mx-results-bar"><span aria-live="assertive" a
 
 exports[`Results Bar 1`] = `"<div class="mx-results-bar"><span aria-live="polite">Showing results 1 - 10 of 250 results</span></div>"`;
 
-exports[`Sort 1`] = `"<div class="mx-results-bar"><span aria-live="polite">Showing results 1 - 10 of 250 results</span><div class="mx-results-bar__sort"><label class="mx-label" for="results-sort">Sort by</label><select id="results-sort" class="mx-input__select" aria-describedby="results-sort-help" aria-invalid="false" name="results-sort"><option value="">Select one</option><option value="1">Option 1</option><option value="2">Option 2</option><option value="3">Option 3</option></select></div></div>"`;
+exports[`Sort 1`] = `"<div class="mx-results-bar"><span aria-live="polite">Showing results 1 - 10 of 250 results</span><div class="mx-results-bar__sort"><label class="mx-label" for="results-sort">Sort by</label><select id="results-sort" class="mx-input__select" aria-describedby="help-results-sort" aria-invalid="false" name="results-sort"><button><selectedcontent>Select one</selectedcontent></button><option value="">Select one</option><option value="Newest">Newest</option><option value="Oldest">Oldest</option><option value="Most popular">Most popular</option></select></div></div>"`;

package/src/Component/ResultsBar/results-bar.twig

@@ -15,6 +15,9 @@
     <div class="mx-results-bar__sort">
       <label class="mx-label" for="results-sort">Sort by</label>
       <select class="mx-input__select" id="results-sort" name="results-sort">
+        <button>
+          <selectedcontent></selectedcontent>
+        </button>
         {% for option in sort %}
           <option value="{{ option }}">{{ option }}</option>
         {% endfor %}

package/src/Component/SideNavigation/Components/SideNavigationTree.figma.ts

@@ -0,0 +1,26 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=83-358
+// source=src/Component/SideNavigation/Components/SideNavigationTree.tsx
+// component=SideNavigationTree
+import figma from "figma"
+
+// `items` (MenuTree[]) is a data-object array, not JSX children — fixed
+// representative example (one item with a nested sub-list), same reasoning as
+// Breadcrumb/Navigation.
+export default {
+  example: figma.code`<SideNavigationTree items={[
+  { link: { href: "/one", title: "Section one" } },
+  {
+    link: { href: "/two", title: "Section two" },
+    items: [
+      { link: { href: "/two/a", title: "Sub-section A" } },
+      { link: { href: "/two/b", title: "Sub-section B" } },
+    ],
+  },
+  { link: { href: "/three", title: "Section three" } },
+]} />`,
+  imports: ['import { SideNavigationTree } from "@pnx-mixtape/mxds/react"'],
+  id: "side-navigation-tree",
+  metadata: {
+    nestable: true,
+  },
+}

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

@@ -0,0 +1,38 @@
+import { JSX } from "react"
+import { MenuTree } from "@pnx-mixtape/ids-shape"
+import Link from "../../../Atom/Link/Link"
+
+type SideNavigationTreeProps = {
+  items: MenuTree[]
+  level?: number
+}
+
+const SideNavigationTree = ({ items, level = 0 }: SideNavigationTreeProps): JSX.Element => (
+  <ul className={`mx-nav__level-${level + 1}`}>
+    {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>
+    ))}
+  </ul>
+)
+export default SideNavigationTree