@pnx-mixtape/mxds 0.1.0-rc.3 → 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/Atom/_generic.css

@@ -9,16 +9,6 @@
     box-sizing: border-box;
     background-repeat: no-repeat;
     margin: 0;
-    opacity: 1;
-    transition-property:
-      opacity, color, background-color, border-color, transform, rotate, display, overlay;
-    transition-duration: 0.5s;
-    transition-timing-function: var(--ease);
-    transition-behavior: allow-discrete;
-
-    @starting-style {
-      opacity: 0;
-    }
   }
 
   :focus {

package/src/Component/Accordion/accordion.css

@@ -1,6 +1,7 @@
 /**
  * Accordion
  */
+@import "../../Utility/_mixins.css";
 
 @layer design-system.defaults {
   details {
@@ -59,8 +60,9 @@
     }
 
     & > .mx-accordion__content {
+      @add-mixin transition;
+
       display: none;
-      opacity: 0;
       overflow: hidden;
     }
 

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
+  }
+}