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

package/src/Atom/Icon/README.md

@@ -66,7 +66,7 @@ import { IconColourModifier, IconSizeModifier, IconRotateModifier } from "@pnx-m
 
 ## Available icons (`Icons` enum)
 
-`arrow-down`, `arrow-left`, `arrow-up`, `arrow-right`, `chevron-down`, `chevron-left`, `chevron-right`, `chevron-up`, `close`, `collapse`, `download`, `drupal`, `error`, `expand`, `external-link`, `facebook`, `google`, `info`, `instagram`, `linkedin`, `mastodon`, `bluesky`, `menu`, `search`, `success`, `twitter`, `warning`, `youtube`, `email`, `file`, `heart-selected`, `heart-unselected`, `link`, `lock`, `login`, `more`, `pencil`, `phone`, `pin`, `print`, `question`, `restart`, `share`, `star-selected`, `star-unselected`, `tick`, `trash`, `user`
+`arrow-down`, `arrow-left`, `arrow-up`, `arrow-right`, `chevron-down`, `chevron-left`, `chevron-right`, `chevron-up`, `close`, `collapse`, `download`, `drupal`, `error`, `expand`, `external-link`, `facebook`, `globe`, `google`, `info`, `instagram`, `linkedin`, `mastodon`, `bluesky`, `menu`, `search`, `success`, `twitter`, `warning`, `youtube`, `email`, `file`, `heart-selected`, `heart-unselected`, `link`, `lock`, `login`, `more`, `pencil`, `phone`, `pin`, `print`, `question`, `restart`, `share`, `star-selected`, `star-unselected`, `thumb`, `tick`, `trash`, `user`
 
 ## Colour modifiers
 

package/src/Atom/Icon/_icon.css

@@ -77,6 +77,7 @@
   @add-mixin icon print;
   @add-mixin icon question;
   @add-mixin icon share;
+  @add-mixin icon thumb;
 
   .mx-icon--status::before {
     mask-image: url("./images/info.svg");

package/src/Atom/Icon/images/thumb.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-thumbs-up preview-icon"><path d="M15 5.88 14 10h5.83a2 2 0 0 1 1.92 2.56l-2.33 8A2 2 0 0 1 17.5 22H4a2 2 0 0 1-2-2v-8a2 2 0 0 1 2-2h2.76a2 2 0 0 0 1.79-1.11L12 2a3.13 3.13 0 0 1 3 3.88Z"/><path d="M7 10v12"/></svg>

package/src/Atom/Media/__snapshots__/Media.stories.ts.snap

@@ -6,9 +6,7 @@ exports[`Attribution 1`] = `
 <figure class="mx-media mx-media--image">  <picture>
     <img src="https://picsum.photos/id/56/558/418?grayscale" alt="Some blurry bubble image">
 </picture>
-
-    <figcaption><b>Figure 1.</b> A picsum image
-     -     Jane Doe  </figcaption>
+  <figcaption><b>Figure 1.</b> A picsum image - Jane Doe</figcaption>
   </figure>"
 `;
 
@@ -18,8 +16,7 @@ exports[`Media 1`] = `
 <figure class="mx-media mx-media--image">  <picture>
     <img src="https://picsum.photos/id/56/558/418?grayscale" alt="Some blurry bubble image">
 </picture>
-
-    <figcaption><b>Figure 1.</b> A picsum image  </figcaption>
+  <figcaption><b>Figure 1.</b> A picsum image</figcaption>
   </figure>"
 `;
 
@@ -29,8 +26,7 @@ exports[`No Figure 1`] = `
   <picture>
     <img src="https://picsum.photos/id/56/558/418?grayscale" alt="Some blurry bubble image">
 </picture>
-
-  "
+"
 `;
 
 exports[`Remote Video 1`] = `
@@ -39,7 +35,6 @@ exports[`Remote Video 1`] = `
 <figure class="mx-media mx-media--video">  <figure class="mx-video" data-src="https://www.youtube.com/embed/NpEaa2P7qZI" data-title="Something from youtube">
   <iframe src="https://www.youtube.com/embed/NpEaa2P7qZI" title="Something from youtube" allow="fullscreen; picture-in-picture; encrypted-media; clipboard-write" allowfullscreen=""></iframe>
 </figure>
-
-    <figcaption>A remote video  </figcaption>
+  <figcaption>A remote video</figcaption>
   </figure>"
 `;

package/src/Atom/Media/media.twig

@@ -11,11 +11,10 @@
 {% if wrap %}<figure{{ attributes }}>{% endif %}
   {{ item }}
   {% if caption is not empty or attribution is not empty %}
-  <figcaption>{% apply spaceless %}
-    {{ caption }}
-    {% if caption is not empty and attribution is not empty %} - {% endif %}
-    {{ attribution }}
-    {% endapply %}
+  <figcaption>
+    {{- caption -}}
+    {%- if caption is not empty and attribution is not empty %} - {% endif -%}
+    {{- attribution -}}
   </figcaption>
   {% endif %}
 {% if wrap %}</figure>{% endif %}

package/src/Component/BackToTop/BackToTop.stories.ts

@@ -0,0 +1,127 @@
+import { Meta, StoryObj } from "@storybook/html-vite"
+import { expect, waitFor } from "storybook/test"
+import Component from "./back-to-top.twig"
+import "./back-to-top.css"
+import "./Elements/BackToTop"
+
+/**
+ * A trigger that appears once the reader has scrolled past a threshold and jumps back to a
+ * target element on the page, with focus management and reduced-motion support.
+ * It requires the `BackToTop` custom element javascript.
+ *
+ * By default it watches how far the reader has scrolled (`visibleAfter`, `100vh`) — pass
+ * `target` to watch a specific element (e.g. a page's `<h1>`) leaving the viewport instead.
+ */
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  component: Component,
+  args: {
+    title: "Back to top",
+    href: "#main",
+    visibleAfter: "1vh",
+  },
+  argTypes: {
+    target: {
+      description:
+        "CSS selector of an element to observe — visible once it scrolls above the viewport top. Omit to use `visibleAfter` instead.",
+      control: "text",
+      type: "string",
+    },
+    visibleAfter: {
+      description:
+        "Distance down the page before the trigger appears. Only used when `target` is unset.",
+      control: "text",
+      type: "string",
+      table: {
+        defaultValue: { summary: "100vh" },
+      },
+    },
+    href: {
+      description: "Scroll destination — a same-page hash.",
+      control: "text",
+      type: {
+        name: "string",
+        required: true,
+      },
+      table: {
+        defaultValue: { summary: "#main" },
+      },
+    },
+    offset: {
+      description:
+        "Pixel offset to avoid overlapping another fixed element (e.g. a sticky CTA bar).",
+      control: "number",
+      type: "number",
+    },
+    title: {
+      description: "Trigger label.",
+      control: "text",
+      type: {
+        name: "string",
+        required: true,
+      },
+      table: {
+        defaultValue: { summary: "Back to top" },
+      },
+    },
+    breakpoint: {
+      description: "Restrict display to a breakpoint and up. Omit to show at all viewport sizes.",
+      control: "select",
+      options: ["", "l"],
+      type: "string",
+    },
+  },
+  render: args => `
+    <div style="block-size: 100px; padding-block-start: 2rem;">
+      <p>Scroll down to reveal the "Back to top" trigger.</p>
+    </div>
+    <div id="main">
+      <h2>Main content</h2>
+      <p>This is the scroll destination.</p>
+    </div>
+    ${Component(args)}
+  `,
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * Visibility is driven by real window scroll position (see the component's `setVisible`), which
+ * isn't reliably simulated via `window.scrollTo` in this test canvas — so this play function
+ * exercises the same toggle the scroll listener would call, directly, along with the click
+ * behaviour, rather than simulating a real scroll.
+ */
+export const BackToTop: Story = {
+  play: async ({ canvasElement, userEvent, step }) => {
+    const wrapper = canvasElement.querySelector("mx-back-to-top") as InstanceType<
+      typeof HTMLElement
+    > & { setVisible: (isVisible: boolean) => void }
+    const trigger = canvasElement.querySelector("a") as HTMLAnchorElement
+    const main = canvasElement.querySelector("#main") as HTMLElement
+
+    await step("Starts hidden", async () => {
+      await expect(wrapper.classList.contains("is-visible")).toBe(false)
+    })
+
+    await step("Becomes visible once toggled", async () => {
+      let detail: { isVisible: boolean } | undefined
+      wrapper.addEventListener("back-to-top-toggle", (event: Event) => {
+        detail = (event as CustomEvent<{ isVisible: boolean }>).detail
+      })
+      wrapper.setVisible(true)
+      await expect(wrapper.classList.contains("is-visible")).toBe(true)
+      await expect(detail?.isVisible).toBe(true)
+    })
+
+    await step("Activating it moves focus to the destination", async () => {
+      await userEvent.click(trigger)
+      await waitFor(() => expect(document.activeElement).toBe(main))
+    })
+
+    await step("Restores toggled state", async () => {
+      wrapper.setVisible(false)
+      await expect(wrapper.classList.contains("is-visible")).toBe(false)
+    })
+  },
+}

package/src/Component/BackToTop/BackToTop.stories.tsx

@@ -0,0 +1,53 @@
+import { Meta, StoryObj } from "@storybook/react-vite"
+import { expect, waitFor } from "storybook/test"
+import Component from "./BackToTop"
+import "./back-to-top.css"
+import { Page } from "../../../.storybook-react/decorators"
+
+const fillerStyle = { blockSize: "50vh", paddingBlockStart: "2rem" }
+
+const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
+  component: Component,
+  decorators: [Page],
+  args: {
+    title: "Back to top",
+    to: "#main",
+  },
+  render: args => (
+    <>
+      <div style={fillerStyle}>
+        <p>Scroll down to reveal the &quot;Back to top&quot; trigger.</p>
+      </div>
+      <div id="main">
+        <h2>Main content</h2>
+        <p>This is the scroll destination.</p>
+      </div>
+      <Component {...args} />
+    </>
+  ),
+}
+
+export default meta
+
+/**
+ * Visibility is driven by real window scroll position, which isn't reliably simulated via
+ * `window.scrollTo` in this test canvas — see the Twig/Web Component story, which exercises the
+ * toggle directly instead. This story covers the click behaviour, which doesn't depend on it.
+ */
+export const BackToTop: StoryObj<typeof meta> = {
+  play: async ({ canvasElement, userEvent, step }) => {
+    const wrapper = canvasElement.querySelector(".mx-back-to-top") as HTMLElement
+    const trigger = canvasElement.querySelector("a") as HTMLAnchorElement
+    const main = canvasElement.querySelector("#main") as HTMLElement
+
+    await step("Starts hidden", async () => {
+      await expect(wrapper.classList.contains("is-visible")).toBe(false)
+    })
+
+    await step("Activating it moves focus to the destination", async () => {
+      await userEvent.click(trigger)
+      await waitFor(() => expect(document.activeElement).toBe(main))
+    })
+  },
+}

package/src/Component/BackToTop/BackToTop.tsx

@@ -0,0 +1,120 @@
+import { JSX, MouseEventHandler, useEffect, useMemo, useState } from "react"
+import classNames from "classnames"
+import { ButtonModifiers } from "@pnx-mixtape/ids-shape"
+import { ButtonLink } from "../../Atom/Button/Button"
+import { Icons } from "../../enums"
+
+const TRIGGER_MODIFIERS = [ButtonModifiers.LIGHT]
+
+/** Resolves a CSS length (`px` or `vh`) to a pixel value. */
+const resolveThreshold = (value: string): number => {
+  const amount = Number.parseFloat(value)
+  if (Number.isNaN(amount)) return window.innerHeight
+  if (value.endsWith("vh")) return (amount / 100) * window.innerHeight
+  return amount
+}
+
+type BackToTopProps = {
+  /** CSS selector of an element to observe — visible once it scrolls above the viewport top. */
+  target?: string
+  /** When `target` is unset, distance down the page before the trigger appears. */
+  visibleAfter?: string
+  /** Scroll destination. Must be a same-page hash (`#id`). */
+  to?: string
+  /** Pixel offset to avoid overlapping another fixed element (e.g. a sticky CTA bar). */
+  offset?: number
+  title?: string
+  /** Restricts display to a breakpoint and up. Omit to show at all viewport sizes. */
+  breakpoint?: "l"
+  className?: string
+  /** Called whenever the visible state changes. React analogue of the Web Component's `back-to-top-toggle` event. */
+  onVisibleChange?: (isVisible: boolean) => void
+}
+
+const BackToTop = ({
+  target,
+  visibleAfter = "100vh",
+  to = "#main",
+  offset,
+  title = "Back to top",
+  breakpoint,
+  className,
+  onVisibleChange,
+}: BackToTopProps): JSX.Element => {
+  const [isVisible, setIsVisible] = useState(false)
+
+  useEffect(() => {
+    const setNext = (next: boolean): void => {
+      setIsVisible(prev => {
+        if (prev !== next) onVisibleChange?.(next)
+        return next
+      })
+    }
+
+    const observed = target ? document.querySelector(target) : null
+
+    if (observed) {
+      const io = new IntersectionObserver(([{ boundingClientRect }]) => {
+        setNext(boundingClientRect.y < 0)
+      })
+      io.observe(observed)
+      return () => io.disconnect()
+    }
+
+    const threshold = resolveThreshold(visibleAfter)
+    const handleScroll = (): void => setNext(window.scrollY > threshold)
+    handleScroll()
+    window.addEventListener("scroll", handleScroll, { passive: true })
+    return () => window.removeEventListener("scroll", handleScroll)
+  }, [target, visibleAfter, onVisibleChange])
+
+  const handleClick: MouseEventHandler<HTMLAnchorElement> = event => {
+    if (!to.startsWith("#")) return
+    const dest = document.querySelector<HTMLElement>(to)
+    if (!dest) return
+
+    event.preventDefault()
+
+    const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches
+    dest.scrollIntoView({ behavior: reduceMotion ? "auto" : "smooth", block: "start" })
+
+    const hadTabindex = dest.hasAttribute("tabindex")
+    if (!hadTabindex) dest.setAttribute("tabindex", "-1")
+    dest.focus({ preventScroll: true })
+    if (!hadTabindex) {
+      dest.addEventListener("blur", () => dest.removeAttribute("tabindex"), { once: true })
+    }
+
+    window.history?.pushState?.(null, "", to)
+  }
+
+  const style = useMemo<Record<string, string | number>>(() => {
+    const next: Record<string, string | number> = {}
+    if (offset) next["--back-to-top-offset"] = `${offset}px`
+    return next
+  }, [offset])
+
+  return (
+    <div
+      className={classNames(
+        breakpoint ? `mx-back-to-top--${breakpoint}` : "mx-back-to-top",
+        className,
+        // Always "enhanced" — React has already confirmed JS is running.
+        { "is-enhanced": true, "is-visible": isVisible },
+      )}
+      style={style}
+    >
+      <ButtonLink
+        to={to}
+        onClick={handleClick}
+        modifiers={TRIGGER_MODIFIERS}
+        className="mx-back-to-top__trigger mx-button--small"
+        iconStart={Icons.ARROW_UP}
+      >
+        {title}
+      </ButtonLink>
+    </div>
+  )
+}
+
+export default BackToTop

package/src/Component/BackToTop/Elements/BackToTop.ts

@@ -0,0 +1,119 @@
+/**
+ * BackToTop — shows/hides a "jump to top" trigger based on scroll position,
+ * and manages focus/scroll when it's activated.
+ */
+
+type ToggleDetail = {
+  isVisible: boolean
+  target: BackToTop
+}
+
+/** Resolves a CSS length (`px` or `vh`) to a pixel value. */
+const resolveThreshold = (value: string): number => {
+  const amount = Number.parseFloat(value)
+  if (Number.isNaN(amount)) return window.innerHeight
+  if (value.endsWith("vh")) return (amount / 100) * window.innerHeight
+  return amount
+}
+
+export default class BackToTop extends HTMLElement {
+  internals_: ElementInternals
+  controller: AbortController
+  io?: IntersectionObserver
+
+  constructor() {
+    super()
+    this.internals_ = this.attachInternals()
+    this.controller = new AbortController()
+  }
+
+  connectedCallback(): void {
+    const { signal } = this.controller
+
+    // Only hide-until-scrolled once JS is confirmed running — see back-to-top.css.
+    this.classList.add("is-enhanced")
+
+    this.trigger?.addEventListener("click", this.handleClick, { signal })
+
+    const selector = this.getAttribute("target")
+    const target = selector ? document.querySelector(selector) : null
+
+    if (target) {
+      this.io = new IntersectionObserver(([{ boundingClientRect }]) => {
+        this.setVisible(boundingClientRect.y < 0)
+      })
+      this.io.observe(target)
+      return
+    }
+
+    const threshold = resolveThreshold(this.getAttribute("visibleafter") || "100vh")
+    this.setVisible(window.scrollY > threshold)
+    window.addEventListener("scroll", () => this.setVisible(window.scrollY > threshold), {
+      signal,
+      passive: true,
+    })
+  }
+
+  disconnectedCallback(): void {
+    this.controller.abort()
+    this.io?.disconnect()
+  }
+
+  get trigger(): HTMLAnchorElement | null {
+    return this.querySelector("a")
+  }
+
+  setVisible(isVisible: boolean): void {
+    if (this.classList.contains("is-visible") === isVisible) return
+    this.classList.toggle("is-visible", isVisible)
+    this.dispatchEvent(
+      new CustomEvent<ToggleDetail>("back-to-top-toggle", {
+        bubbles: true,
+        cancelable: true,
+        detail: { isVisible, target: this },
+      }),
+    )
+  }
+
+  /**
+   * Prevents the native anchor jump so we can scroll smoothly (honouring
+   * reduced-motion), then moves focus to the destination — a plain anchor
+   * jump scrolls the page but does not reliably move accessible focus
+   * unless the destination is already focusable.
+   */
+  handleClick = (event: MouseEvent): void => {
+    const link = event.currentTarget as HTMLAnchorElement
+    const hash = link.getAttribute("href")
+    if (!hash?.startsWith("#")) return
+
+    const dest = document.querySelector<HTMLElement>(hash)
+    if (!dest) return
+
+    event.preventDefault()
+
+    const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches
+    dest.scrollIntoView({ behavior: reduceMotion ? "auto" : "smooth", block: "start" })
+
+    const hadTabindex = dest.hasAttribute("tabindex")
+    if (!hadTabindex) dest.setAttribute("tabindex", "-1")
+    dest.focus({ preventScroll: true })
+    if (!hadTabindex) {
+      dest.addEventListener("blur", () => dest.removeAttribute("tabindex"), {
+        once: true,
+        signal: this.controller.signal,
+      })
+    }
+
+    window.history?.pushState?.(null, "", hash)
+  }
+}
+
+if (!customElements.get("mx-back-to-top")) {
+  customElements.define("mx-back-to-top", BackToTop)
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "mx-back-to-top": BackToTop
+  }
+}

package/src/Component/BackToTop/README.md

@@ -0,0 +1,164 @@
+# BackToTop
+
+A trigger that appears once the reader has scrolled past a threshold and jumps back to a target
+element on the page. Shows/hides itself via `IntersectionObserver`, and manages focus and
+reduced-motion-aware smooth scrolling when activated.
+
+---
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/BackToTop/back-to-top.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/BackToTop/back-to-top.twig' with {
+  href: '#main',
+  title: 'Back to top',
+} %}
+
+{# Watch a specific element (e.g. the page's <h1>) instead of a scroll distance #}
+{% include '@mixtape/Component/BackToTop/back-to-top.twig' with {
+  target: '#page-title',
+  href: '#main',
+} %}
+```
+
+**back-to-top.twig props:**
+
+| Prop           | Type        | Default       | Description                                                                                                  |
+| -------------- | ----------- | ------------- | ------------------------------------------------------------------------------------------------------------ |
+| `href`         | `string`    | `#main`       | Scroll destination — a same-page hash                                                                        |
+| `title`        | `string`    | `Back to top` | Trigger label                                                                                                |
+| `target`       | `string`    | —             | CSS selector of an element to observe — visible once it scrolls above the viewport top                       |
+| `visibleAfter` | `string`    | `100vh`       | Distance down the page before the trigger appears. Only used when `target` is unset                          |
+| `offset`       | `number`    | —             | Pixel offset to avoid overlapping another fixed element (e.g. a sticky CTA bar). Sets `--back-to-top-offset` |
+| `breakpoint`   | `string`    | —             | `l` restricts display to the large breakpoint and up. Omit to show at all viewport sizes                     |
+| `attributes`   | `Attribute` | —             | Optional Drupal-style attributes object — modifier classes are merged on top                                 |
+
+---
+
+## HTML + Web Component
+
+```html
+<mx-back-to-top class="mx-back-to-top" target="#page-title">
+  <a class="mx-button mx-button--light mx-button--small mx-back-to-top__trigger" href="#main">
+    <span class="mx-icon mx-icon--arrow-up"></span>
+    <span>Back to top</span>
+  </a>
+</mx-back-to-top>
+```
+
+Registers as `<mx-back-to-top>`. Import the element to activate its behaviour:
+
+```js
+import "@pnx-mixtape/mxds/src/Component/BackToTop/Elements/BackToTop"
+```
+
+**`<mx-back-to-top>` attributes:**
+
+| Attribute      | Description                                                                                           |
+| -------------- | ----------------------------------------------------------------------------------------------------- |
+| `target`       | CSS selector of an element to observe — visible once it scrolls above the viewport top                |
+| `visibleafter` | Distance down the page before the trigger appears (default `100vh`). Used only when `target` is unset |
+
+If no `target` is set, visibility is driven by a plain scroll-position check instead (`window.scrollY` compared against `visibleafter`, resolved from a `px` or `vh` value) rather than an `IntersectionObserver` — this avoids depending on the host page's containing-block/positioning context, which a synthetic absolutely-positioned sentinel would be sensitive to.
+
+**Behaviour on click:** the Web Component intercepts the click, scrolls the destination into view
+(`behavior: smooth`, or `auto` when `prefers-reduced-motion: reduce`), temporarily makes the
+destination focusable if it isn't already (`tabindex="-1"`, removed again on blur), moves focus
+to it, and updates the URL hash via `history.pushState` — all without a full native anchor jump,
+so the smooth scroll and reduced-motion behaviour are never a race against the browser's own
+default jump.
+
+**Event:**
+
+```js
+document.querySelector("mx-back-to-top").addEventListener("back-to-top-toggle", e => {
+  console.log(e.detail.isVisible) // true when the trigger becomes visible, false when it hides
+})
+```
+
+---
+
+## React
+
+```tsx
+import { BackToTop } from "@pnx-mixtape/mxds/react"
+
+<BackToTop />
+
+// Watch a specific element instead of a scroll distance
+<BackToTop target="#page-title" href="#main" />
+
+// Desktop-only, offset to avoid overlapping a sticky CTA bar
+<BackToTop breakpoint="l" offset={56} />
+```
+
+**`BackToTop` props:**
+
+| Prop              | Type                           | Default       | Description                                                                            |
+| ----------------- | ------------------------------ | ------------- | -------------------------------------------------------------------------------------- |
+| `to`              | `string`                       | `#main`       | Scroll destination — a same-page hash                                                  |
+| `title`           | `string`                       | `Back to top` | Trigger label                                                                          |
+| `target`          | `string`                       | —             | CSS selector of an element to observe — visible once it scrolls above the viewport top |
+| `visibleAfter`    | `string`                       | `100vh`       | Distance down the page before the trigger appears. Only used when `target` is unset    |
+| `offset`          | `number`                       | —             | Pixel offset to avoid overlapping another fixed element. Sets `--back-to-top-offset`   |
+| `breakpoint`      | `"l"`                          | —             | Restrict display to the large breakpoint and up. Omit to show at all viewport sizes    |
+| `className`       | `string`                       | —             | Extra class on the root                                                                |
+| `onVisibleChange` | `(isVisible: boolean) => void` | —             | Called whenever the visible state changes. React analogue of `back-to-top-toggle`      |
+
+---
+
+## Modifiers
+
+| CSS class           | React `breakpoint` | Behaviour                                                   |
+| ------------------- | ------------------ | ----------------------------------------------------------- |
+| `mx-back-to-top`    | `undefined`        | Visible (once scrolled) at all viewport sizes               |
+| `mx-back-to-top--l` | `"l"`              | Visible (once scrolled) only at the large breakpoint and up |
+
+---
+
+### React ⇄ Twig parity
+
+`onVisibleChange` has no Twig equivalent — Twig/HTML has no concept of a function prop. The
+`<mx-back-to-top>` Web Component dispatches a `back-to-top-toggle` `CustomEvent` instead; listen
+for it if you need the same notification outside React.
+
+---
+
+## Accessibility
+
+- The trigger is a real `<a href>` (via the `Button` atom, `as: 'link'`) and is always visible,
+  in the tab order, and keyboard-activatable **without JavaScript**. The scroll-gated show/hide
+  behaviour is only switched on once JS has confirmed it can drive it — the Web Component adds
+  an `is-enhanced` class in `connectedCallback`, and React (which always has JS) adds it
+  unconditionally — so a blocked or failed script load can never leave the trigger permanently
+  hidden or unreachable.
+- On activation, focus is moved to the scroll destination. If the destination isn't natively
+  focusable, a temporary `tabindex="-1"` is added and removed again once it loses focus — this
+  fixes a common gap where a plain anchor jump scrolls the page but leaves screen reader focus
+  behind.
+- Smooth scrolling respects `prefers-reduced-motion: reduce` (falls back to an instant jump).
+- Hidden from print via `@media print`.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-back-to-top {
+  --back-to-top-gap: 64px; /* distance from the bottom of the viewport */
+  --back-to-top-offset: 0; /* additional offset, e.g. to clear a sticky CTA bar */
+  --back-to-top-inline-end: var(--spacing-m); /* distance from the side of the viewport */
+  --back-to-top-z-index: 10;
+}
+```
+
+The React component writes `--back-to-top-offset` as an inline style from the `offset` prop. In
+HTML/Twig, pass `offset` (which sets it inline) or override any of these in your own CSS.