@pnx-mixtape/mxds 0.0.30 → 0.1.0-rc.1

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

@@ -1,169 +1,155 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`Accent 1`] = `
-"  <div class="mx-steps mx-steps--supplementary mx-steps--counters">
-      <div class="mx-steps__panel mx-steps--fill">
+"  <ol class="mx-steps mx-steps--supplementary mx-steps--counters">
+  <li class="mx-steps__panel mx-steps--fill">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
   </div>
-</div>
-
-      <div class="mx-steps__panel mx-steps--fill">
+</li>
+<li class="mx-steps__panel mx-steps--fill">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Soul music ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem.
   </div>
-</div>
-
-      <div class="mx-steps__panel">
+</li>
+<li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Motown lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
   </div>
-</div>
+</li>
 
-  </div>
+</ol>
 "
 `;
 
 exports[`Counters 1`] = `
-"  <div class="mx-steps mx-steps--light mx-steps--counters">
-      <div class="mx-steps__panel">
+"  <ol class="mx-steps mx-steps--light mx-steps--counters">
+  <li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   <h2>Funk</h2><p>Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.</p>
   </div>
-</div>
-
-      <div class="mx-steps__panel">
+</li>
+<li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   <h3>Soul</h3><p>Soul music ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem.</p>
   </div>
-</div>
-
-      <div class="mx-steps__panel">
+</li>
+<li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   <h4>Motown</h4><p>Motown lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.</p>
   </div>
-</div>
+</li>
 
-  </div>
+</ol>
 "
 `;
 
 exports[`Filled 1`] = `
-"  <div class="mx-steps mx-steps--light mx-steps--fill">
-      <div class="mx-steps__panel">
+"  <ol class="mx-steps mx-steps--light mx-steps--fill">
+  <li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   <h2>Funk</h2><p>Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.</p>
   </div>
-</div>
-
-      <div class="mx-steps__panel">
+</li>
+<li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   <h3>Soul</h3><p>Soul music ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem.</p>
   </div>
-</div>
-
-      <div class="mx-steps__panel">
+</li>
+<li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   <h4>Motown</h4><p>Motown lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.</p>
   </div>
-</div>
+</li>
 
-  </div>
+</ol>
 "
 `;
 
 exports[`Highlighted 1`] = `
-"  <div class="mx-steps mx-steps--light">
-      <div class="mx-steps__panel">
+"  <ol class="mx-steps mx-steps--light">
+  <li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
   </div>
-</div>
-
-      <div class="mx-steps__panel mx-steps--fill">
+</li>
+<li class="mx-steps__panel mx-steps--fill">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Soul music ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem.
   </div>
-</div>
-
-      <div class="mx-steps__panel">
+</li>
+<li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Motown lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
   </div>
-</div>
+</li>
 
-  </div>
+</ol>
 "
 `;
 
 exports[`Primary 1`] = `
-"  <div class="mx-steps mx-steps--dark mx-steps--counters">
-      <div class="mx-steps__panel mx-steps--fill">
+"  <ol class="mx-steps mx-steps--dark mx-steps--counters">
+  <li class="mx-steps__panel mx-steps--fill">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
   </div>
-</div>
-
-      <div class="mx-steps__panel mx-steps--fill">
+</li>
+<li class="mx-steps__panel mx-steps--fill">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Soul music ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem.
   </div>
-</div>
-
-      <div class="mx-steps__panel">
+</li>
+<li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Motown lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
   </div>
-</div>
+</li>
 
-  </div>
+</ol>
 "
 `;
 
 exports[`Progress 1`] = `
-"  <div class="mx-steps mx-steps--light mx-steps--counters">
-      <div class="mx-steps__panel mx-steps--fill">
+"  <ol class="mx-steps mx-steps--light mx-steps--counters">
+  <li class="mx-steps__panel mx-steps--fill">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
   </div>
-</div>
-
-      <div class="mx-steps__panel mx-steps--fill">
+</li>
+<li class="mx-steps__panel mx-steps--fill">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Soul music ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem.
   </div>
-</div>
-
-      <div class="mx-steps__panel">
+</li>
+<li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   Motown lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.
   </div>
-</div>
+</li>
 
-  </div>
+</ol>
 "
 `;
 
 exports[`Steps 1`] = `
-"  <div class="mx-steps mx-steps--light">
-      <div class="mx-steps__panel">
+"  <ol class="mx-steps mx-steps--light">
+  <li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   <h2>Funk</h2><p>Funk is the ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.</p>
   </div>
-</div>
-
-      <div class="mx-steps__panel">
+</li>
+<li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   <h3>Soul</h3><p>Soul music ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem.</p>
   </div>
-</div>
-
-      <div class="mx-steps__panel">
+</li>
+<li class="mx-steps__panel">
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   <h4>Motown</h4><p>Motown lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin at finibus velit. Curabitur consequat, dolor venenatis ullamcorper commodo, quam mi iaculis sem, non varius massa risus et enim. Interdum et malesuada fames ac ante ipsum primis in faucibus. Phasellus non mi lorem. Morbi semper sagittis euismod. Vestibulum non ornare orci.</p>
   </div>
-</div>
+</li>
 
-  </div>
+</ol>
 "
 `;

package/src/Component/Steps/step-item.twig

@@ -4,8 +4,9 @@
   status ? 'mx-steps--fill' : null
 ] %}
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
-<div{{ attributes }}>
+{% if current %}{% set attributes = attributes.setAttribute('aria-current', 'step') %}{% endif %}
+<li{{ attributes }}>
   <div class="mx-steps__panel-content mx-container mx-vertical-flow mx-rich-text">
   {{ content }}
   </div>
-</div>
+</li>

package/src/Component/Steps/steps.css

@@ -5,6 +5,11 @@
 @layer design-system.components {
   .mx-steps {
     counter-reset: step;
+
+    &:is(ol, ul) {
+      list-style: none;
+      padding-inline-start: 0;
+    }
   }
 
   .mx-steps__panel {

package/src/Component/Steps/steps.twig

@@ -11,8 +11,6 @@
   fill ? baseClass~"--fill" : null,
 ] %}
 {% set attributes = (attributes ?? create_attribute()).addClass(classes) %}
-<div{{ attributes }}>
-  {% for item in items %}
-    {{ item }}
-  {% endfor %}
-</div>
+<ol{{ attributes }}>
+  {{ items }}
+</ol>

package/src/Component/Sticky/Elements/Sticky.ts

@@ -65,14 +65,14 @@ export default class Sticky extends HTMLElement {
   }
 
   disconnectedCallback(): void {
-    this.iO.unobserve(this.trigger)
-    this.rO.disconnect()
+    this.iO.disconnect()
+    this.rO?.disconnect()
   }
 
   get trigger(): HTMLDivElement {
-    let trigger: HTMLDivElement | null = this.querySelector(".sticky__trigger")
+    let trigger: HTMLDivElement | null = this.querySelector(".mx-sticky__trigger")
     if (!trigger) {
-      trigger = createElement('<div class="sticky__trigger"></div>') as HTMLDivElement
+      trigger = createElement('<div class="mx-sticky__trigger"></div>') as HTMLDivElement
       this.insertAdjacentElement("beforebegin", trigger)
     }
     return trigger

package/src/Component/Sticky/README.md

@@ -1,30 +1,212 @@
 # Sticky
 
-### How to use
+A layout helper that makes its children stick to the top of their nearest scrolling ancestor using `position: sticky`. Supports a configurable top offset, `z-index`, breakpoint-gated stickiness, and an optional Web Component that exposes an `is-stuck` state and a `sticky-toggle` event.
 
-**CSS**
+## CSS Import
 
-`@import '@pnx-mixtape/mxds/src/Component/Sticky/sticky.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Component/Sticky/sticky.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/Sticky/twig/sticky.twig' %}`
+```twig
+{% include '@mixtape/Component/Sticky/sticky.twig' with {
+  content: rendered_content,
+  offset: 0,
+  className: 'mx-sticky'
+} %}
+```
 
-Alternatively copy/paste the file for more control.
+**sticky.twig props:**
 
-**JSX Components**
+| Prop        | Type          | Default     | Description                                                                            |
+| ----------- | ------------- | ----------- | -------------------------------------------------------------------------------------- |
+| `content`   | `WysiwygText` | —           | Content that should be sticky on scroll (required)                                     |
+| `offset`    | `number`      | `0`         | Inline value applied to `--sticky-offset`                                              |
+| `className` | `string`      | `mx-sticky` | Class on the `<mx-sticky>` wrapper. One of `mx-sticky`, `mx-sticky--m`, `mx-sticky--l` |
 
-`import { Sticky } from '@pnx-mixtape/mxds/src/react';`
+---
 
-**JS Custom Element**
+## HTML + Web Component
 
-Custom Elements are self defined, simply import the desired feature.
-These do not use the Shadow DOM and are not typical Web Components.
-External CSS applies.
-No Polyfills or frameworks are required.
+The `<mx-sticky>` custom element wraps the stuck element, observes when it crosses the top of the viewport via `IntersectionObserver`, and toggles an `is-stuck` class on itself. It dispatches a bubbling `sticky-toggle` `CustomEvent` with `{ isSticky, options, target }` in `detail` on every transition.
 
-- Sticky import: `import '@pnx-mixtape/mxds/src/Component/Sticky/Elements/Sticky';` and be sure to include `<mx-sticky>` around the content.
+```html
+<mx-sticky style="--sticky-offset: 0" offsetPropName="--sticky-offset" class="mx-sticky">
+  I am sticky.
+</mx-sticky>
+```
 
-See twig files for all HTML examples.
+Apply the sticky positioning by adding one of the CSS classes below to the wrapping element, or style `mx-sticky` in your own CSS — the bundled `sticky.css` only defines `.sticky`, `.sticky--m`, `.sticky--l`, not `.mx-sticky` (see "Source inconsistencies" below).
+
+**Import the JS:**
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Sticky/Elements/Sticky"
+```
+
+**`<mx-sticky>` attributes:**
+
+| Attribute        | Description                                                                                                                                                                                                      |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `offsetpropname` | Name of a CSS custom property to set on `document.body` equal to the sticky element's current rendered height. Useful for offsetting other sticky elements below it (e.g. a sticky subnav under a sticky header) |
+
+**Generated markup:** On `connectedCallback`, if a sibling `.sticky__trigger` element doesn't already exist, one is inserted directly before `<mx-sticky>`. That trigger is the element observed by the `IntersectionObserver` — when its top edge leaves the viewport, `is-stuck` is added to `<mx-sticky>`.
+
+**Event:**
+
+```js
+document.querySelector("mx-sticky").addEventListener("sticky-toggle", e => {
+  console.log(e.detail.isSticky) // true when stuck, false when released
+})
+```
+
+---
+
+## React
+
+`Sticky` is a wrapper — it renders a single element with `position: sticky` applied and passes children through unchanged. There is no composition pattern and no stuck-state detection in the React version.
+
+```tsx
+import { Sticky } from "@pnx-mixtape/mxds/react"
+import { AsTags } from "@pnx-mixtape/mxds/src/enums"
+
+// Basic — sticks to the top of the scroll container
+<Sticky as={AsTags.DIV}>
+  <p>Element is sticky</p>
+</Sticky>
+
+// With a top offset (pixels)
+<Sticky as={AsTags.DIV} offset={150}>
+  <nav>...</nav>
+</Sticky>
+
+// Only stick at medium breakpoints and up
+<Sticky as={AsTags.ASIDE} breakpoint="m">
+  <aside>Sidebar content</aside>
+</Sticky>
+
+// Only stick at large breakpoints and up, with raised stacking context
+<Sticky as={AsTags.DIV} breakpoint="l" zIndex={10}>
+  ...
+</Sticky>
+```
+
+**`Sticky` props:**
+
+| Prop         | Type         | Default | Description                                                                  |
+| ------------ | ------------ | ------- | ---------------------------------------------------------------------------- |
+| `as`         | `AsTags`     | `div`   | Semantic element for the wrapper: `div`, `li`, `article`, `aside`, `section` |
+| `offset`     | `number`     | —       | Top offset in pixels. Sets `--sticky-offset: {offset}px` inline              |
+| `zIndex`     | `number`     | —       | Stacking context value. Sets `--z-index` inline                              |
+| `breakpoint` | `"l" \| "m"` | —       | Only apply stickiness from this breakpoint up. Omit for all viewports        |
+| `className`  | `string`     | —       | Extra class on the wrapper                                                   |
+
+The rendered class is `mx-sticky` by default, or `mx-sticky--m` / `mx-sticky--l` when `breakpoint` is set.
+
+---
+
+## HTML + Web Component
+
+The `<mx-sticky>` custom element wraps the stuck element, observes when it crosses the top of the viewport via `IntersectionObserver`, and toggles an `is-stuck` class on itself. It dispatches a bubbling `sticky-toggle` `CustomEvent` with `{ isSticky, options, target }` in `detail` on every transition.
+
+```html
+<mx-sticky style="--sticky-offset: 0" offsetPropName="--sticky-offset" class="mx-sticky">
+  I am sticky.
+</mx-sticky>
+```
+
+Apply the sticky positioning by adding one of the `.mx-sticky` classes below to the wrapping element.
+
+**Import the JS:**
+
+```js
+import "@pnx-mixtape/mxds/src/Component/Sticky/Elements/Sticky"
+```
+
+**`<mx-sticky>` attributes:**
+
+| Attribute        | Description                                                                                                                                                                                                      |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `offsetpropname` | Name of a CSS custom property to set on `document.body` equal to the sticky element's current rendered height. Useful for offsetting other sticky elements below it (e.g. a sticky subnav under a sticky header) |
+
+**Generated markup:** On `connectedCallback`, if a sibling `.sticky__trigger` element doesn't already exist, one is inserted directly before `<mx-sticky>`. That trigger is the element observed by the `IntersectionObserver` — when its top edge leaves the viewport, `is-stuck` is added to `<mx-sticky>`.
+
+**Event:**
+
+```js
+document.querySelector("mx-sticky").addEventListener("sticky-toggle", e => {
+  console.log(e.detail.isSticky) // true when stuck, false when released
+})
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/Sticky/sticky.twig' with {
+  content: rendered_content,
+  offset: 0,
+  className: 'mx-sticky'
+} %}
+```
+
+**sticky.twig props:**
+
+| Prop        | Type          | Default     | Description                                                                            |
+| ----------- | ------------- | ----------- | -------------------------------------------------------------------------------------- |
+| `content`   | `WysiwygText` | —           | Content that should be sticky on scroll (required)                                     |
+| `offset`    | `number`      | `0`         | Inline value applied to `--sticky-offset`                                              |
+| `className` | `string`      | `mx-sticky` | Class on the `<mx-sticky>` wrapper. One of `mx-sticky`, `mx-sticky--m`, `mx-sticky--l` |
+
+---
+
+## Modifiers
+
+Sticky has no `ids-shape` enum. Breakpoint-gated variants are controlled by classes (HTML/Twig) or the `breakpoint` prop (React):
+
+| CSS class      | React `breakpoint` | Behaviour                               |
+| -------------- | ------------------ | --------------------------------------- |
+| `mx-sticky`    | `undefined`        | Sticky at all viewports                 |
+| `mx-sticky--m` | `"m"`              | Sticky only at medium breakpoint and up |
+| `mx-sticky--l` | `"l"`              | Sticky only at large breakpoint and up  |
+
+---
+
+## Accessibility
+
+No special accessibility concerns. `Sticky` is a purely presentational wrapper — it does not add ARIA attributes, focus management, or announcements, and does not change the document outline (use `as` to choose a semantic element that matches the surrounding content).
+
+When using the Web Component, the `sticky-toggle` event and `is-stuck` class are for styling/behavioural hooks only and do not affect assistive technology.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-sticky {
+  --sticky-offset: 0; /* distance from the top of the scroll container */
+  --z-index: 1; /* stacking context while stuck */
+}
+```
+
+The React component writes `--sticky-offset` and `--z-index` as inline styles from the `offset` and `zIndex` props. In HTML/Twig, set them as inline `style` values on `<mx-sticky>` or override them in your own CSS.
+
+When using `<mx-sticky>` with the `offsetpropname` attribute, the element's current height is written to that custom property on `document.body` and can be consumed by downstream sticky elements:
+
+```html
+<mx-sticky offsetpropname="--header-height" class="mx-sticky">...</mx-sticky>
+
+<!-- Later element offsets itself by the header's height -->
+<mx-sticky style="--sticky-offset: var(--header-height, 0)" class="mx-sticky">...</mx-sticky>
+```
+
+---
+
+## Source inconsistencies
+
+- The `is-stuck` class and `sticky-toggle` event only fire when the `<mx-sticky>` Web Component is in use — the React `Sticky` component has no stuck-state detection.

package/src/Component/Sticky/Sticky.figma.ts

@@ -0,0 +1,20 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=65-221
+// source=src/Component/Sticky/Sticky.tsx
+// component=Sticky
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+// Real children — a proper Content SLOT (not a fixed text layer).
+const content = instance.getSlot("Content")
+
+// `as` is required with no default in code and has no visual effect — a plain div
+// is used in the example since something must be supplied.
+export default {
+  example: figma.code`<Sticky as={AsTags.DIV}>${content}</Sticky>`,
+  imports: ['import { Sticky, AsTags } from "@pnx-mixtape/mxds/react"'],
+  id: "sticky",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Sticky/Sticky.tsx

@@ -1,4 +1,4 @@
-import { JSX, PropsWithChildren } from "react"
+import { JSX, PropsWithChildren, useEffect, useMemo, useRef, useState } from "react"
 import classNames from "classnames"
 import { AsTags } from "../../enums"
 
@@ -8,6 +8,11 @@ type StickyProps = PropsWithChildren & {
   className?: string
   breakpoint?: "l" | "m"
   as: AsTags
+  /**
+   * Called whenever the stuck state changes. React analogue of the Web
+   * Component's `sticky-toggle` event.
+   */
+  onStuckChange?: (isStuck: boolean) => void
 }
 
 const Sticky = ({
@@ -17,17 +22,43 @@ const Sticky = ({
   className,
   as = AsTags.DIV,
   breakpoint,
+  onStuckChange,
 }: StickyProps): JSX.Element => {
   const Tag: JSX.ElementType = `${as}` as unknown as JSX.ElementType
-  const stickyClass: string = breakpoint ? `sticky--${breakpoint}` : "sticky"
-  const style = {}
-  if (offset) style["--sticky-offset"] = `${offset}px`
-  if (zIndex) style["--z-index"] = zIndex
+  const stickyClass: string = breakpoint ? `mx-sticky--${breakpoint}` : "mx-sticky"
+  const triggerRef = useRef<HTMLDivElement>(null)
+  const [isStuck, setIsStuck] = useState(false)
+
+  const style = useMemo<Record<string, string | number>>(() => {
+    const next: Record<string, string | number> = {}
+    if (offset) next["--sticky-offset"] = `${offset}px`
+    if (zIndex) next["--z-index"] = zIndex
+    return next
+  }, [offset, zIndex])
+
+  useEffect(() => {
+    const trigger = triggerRef.current
+    if (!trigger) return
+
+    const iO = new IntersectionObserver(([{ boundingClientRect }]) => {
+      const stuck = boundingClientRect.y < 0
+      setIsStuck(prev => {
+        if (prev !== stuck) onStuckChange?.(stuck)
+        return stuck
+      })
+    })
+    iO.observe(trigger)
+
+    return () => iO.disconnect()
+  }, [onStuckChange])
 
   return (
-    <Tag className={classNames(stickyClass, className)} style={style}>
-      {children}
-    </Tag>
+    <>
+      <div ref={triggerRef} className="mx-sticky__trigger" aria-hidden="true" />
+      <Tag className={classNames(stickyClass, className, { "is-stuck": isStuck })} style={style}>
+        {children}
+      </Tag>
+    </>
   )
 }
 

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

@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`Sticky 1`] = `
-"<div class="sticky__trigger"></div><mx-sticky style="--sticky-offset: 0" offsetpropname="--sticky-offset" class="mx-sticky">
+"<div class="mx-sticky__trigger"></div><mx-sticky style="--sticky-offset: 0" offsetpropname="--sticky-offset" class="mx-sticky">
   I am sticky.
 </mx-sticky>
 "

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

@@ -1,3 +1,3 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Sticky 1`] = `"<div class="sticky" style="--sticky-offset: 150px;"><p>Element is sticky</p></div>"`;
+exports[`Sticky 1`] = `"<div class="mx-sticky__trigger" aria-hidden="true"></div><div class="mx-sticky" style="--sticky-offset: 150px;"><p>Element is sticky</p></div>"`;

package/src/Component/Sticky/sticky.css

@@ -15,23 +15,23 @@
 }
 
 @layer design-system.components {
-  .sticky {
+  .mx-sticky {
     @mixin sticky;
   }
 
-  .sticky--m {
+  .mx-sticky--m {
     @media (--medium-up) {
       @mixin sticky;
     }
   }
 
-  .sticky--l {
+  .mx-sticky--l {
     @media (--large-up) {
       @mixin sticky;
     }
   }
 
-  .sticky__trigger {
+  .mx-sticky__trigger {
     position: absolute;
     inline-size: 1px;
     block-size: 1px;