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

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

@@ -18,7 +18,7 @@ exports[`Breadcrumb 1`] = `
     
 </a>
 </li>
-          <li>
+          <li>  
 <a href="#" aria-current="page">
   
   <span>Join the team</span>

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

@@ -1,5 +1,5 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`Breadcrumb 1`] = `"<nav class="mx-nav mx-nav--breadcrumb mx-nav--inline" aria-label="You are here"><ul><li><a href="#" class="mx-link">Home</a></li><li><a href="#" class="mx-link">About</a></li><li><a href="#" class="mx-link">Contact</a></li><li>Current page title</li></ul></nav>"`;
+exports[`Breadcrumb 1`] = `"<nav class="mx-nav mx-nav--breadcrumbs mx-nav--inline" aria-label="You are here"><ul><li><a href="#" class="mx-link">Home</a></li><li><a href="#" class="mx-link">About</a></li><li><a href="#" class="mx-link">Contact</a></li><li><span aria-current="page">Current page title</span></li></ul></nav>"`;
 
-exports[`No Current Page 1`] = `"<nav class="mx-nav mx-nav--breadcrumb mx-nav--inline" aria-label="You are here"><ul><li><a href="#" class="mx-link">Home</a></li><li><a href="#" class="mx-link">About</a></li><li><a href="#" class="mx-link">Contact</a></li></ul></nav>"`;
+exports[`No Current Page 1`] = `"<nav class="mx-nav mx-nav--breadcrumbs mx-nav--inline" aria-label="You are here"><ul><li><a href="#" class="mx-link">Home</a></li><li><a href="#" class="mx-link">About</a></li><li><a href="#" class="mx-link" aria-current="page">Contact</a></li></ul></nav>"`;

package/src/Component/Breadcrumb/breadcrumb.css

@@ -10,17 +10,18 @@
     z-index: 1;
     overflow: auto;
     white-space: nowrap;
-    padding-inline: var(--outline-size);
-    padding-block: var(--outline-size);
-    margin-inline: calc(var(--outline-size) * -1);
-    margin-block: calc(var(--outline-size) * -1);
+    scroll-padding-inline: calc(var(--outline-size) * 2);
+    padding-inline: calc(var(--outline-size) * 2);
+    padding-block: calc(var(--outline-size) * 2);
+    margin-inline: calc(var(--outline-size) * -2);
+    margin-block: calc(var(--outline-size) * -2);
 
     & > ul {
       gap: var(--breadcrumb-gap, var(--spacing-xxxxs));
     }
 
     & > ul > li {
-      color: var(--breadcrumb-foreground, var(--foreground, var(--colour-foreground-alt)));
+      color: var(--breadcrumb-foreground, var(--foreground-alt, var(--colour-foreground-alt)));
       display: flex;
       align-items: center;
 
@@ -28,7 +29,7 @@
         content: "";
         display: block;
         vertical-align: middle;
-        mask-image: svg-load("../../Atom/Icon/images/chevron-right.svg");
+        mask-image: url("../../Atom/Icon/images/chevron-right.svg");
         mask-position: center;
         mask-repeat: no-repeat;
         block-size: var(--spacing-m);

package/src/Component/Callout/README.md

@@ -0,0 +1,100 @@
+# Callout
+
+A simple content block with a coloured vertical line on the inline-start edge, used to draw attention to supporting text, quotes, or short announcements. Accepts an optional heading and body content.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/Callout/callout.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/Callout/callout.twig' with {
+  title: heading_component,
+  content: '<p>Some callout content.</p>',
+} %}
+```
+
+**callout.twig props** (`Callout` type from `ids-shape`):
+
+| Prop      | Type          | Required | Description                    |
+| --------- | ------------- | -------- | ------------------------------ |
+| `title`   | `Heading`     | No       | Optional rendered Heading atom |
+| `content` | `WysiwygText` | Yes      | Body content (HTML string)     |
+
+The Twig template also merges any Drupal-style `attributes` passed in, so callers can add ids, data attributes, or extra classes.
+
+---
+
+## HTML
+
+```html
+<div class="mx-callout mx-vertical-flow">
+  <h2>Callout heading</h2>
+  <p>Some callout content.</p>
+</div>
+```
+
+The `mx-vertical-flow` utility adds consistent vertical spacing between the heading and the body content. Omit it if the callout contains a single element.
+
+### Content-only (no heading)
+
+```html
+<div class="mx-callout mx-vertical-flow">
+  <p>Some callout content.</p>
+</div>
+```
+
+---
+
+## React
+
+There is **no React implementation** for Callout. Use the Twig template or HTML markup above. For a React project, render the same class structure directly in JSX:
+
+```tsx
+<div className="mx-callout mx-vertical-flow">
+  <h2>Callout heading</h2>
+  <p>Some callout content.</p>
+</div>
+```
+
+---
+
+## Modifiers
+
+Callout ships with **no modifier classes or enum variants**. It is a single-variant component — the outer `.mx-callout` class is the only component-level hook.
+
+For background-coloured variants, compose with the global background utilities (e.g. `mx-background--alt`) if required, though this is not a documented pattern.
+
+---
+
+## Accessibility
+
+- Callout is a plain `<div>` — it carries no implicit ARIA role or landmark semantics
+- Use a real heading element (`<h2>`–`<h6>`) inside when a `title` is supplied so the callout participates in the document outline correctly
+- The coloured left border is decorative only; all meaning must be conveyed through the text content
+- If the callout represents a quotation, wrap the content in a `<blockquote>` instead of relying on the visual treatment alone
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-callout {
+  --line-gap: var(--gap); /* space between the border and content */
+  --line-width: 6px; /* thickness of the left border */
+  --line-colour: var(--colour-primary); /* border colour */
+}
+```
+
+Override these on a scoped selector to recolour or resize the callout — for example, a warning variant:
+
+```css
+.mx-callout--warning {
+  --line-colour: var(--colour-warning);
+}
+```

package/src/Component/Card/Card.figma.ts

@@ -0,0 +1,59 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=51-178
+// source=src/Component/Card/Card.tsx
+// component=Card
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const reversed = instance.getEnum("Reversed", { Off: false, On: true })
+// RESET excluded — no dedicated CSS rule exists for it (relies on inheriting the
+// ambient background reset, visually identical to None in isolation).
+const background = instance.getEnum("Background", {
+  None: null,
+  Alt: "BackgroundStyles.ALT",
+  Primary: "BackgroundStyles.PRIMARY",
+  Accent: "BackgroundStyles.ACCENT",
+  Reverse: "BackgroundStyles.REVERSE",
+  Box: "BackgroundStyles.BOX",
+})
+
+// "Layout" (Horizontal/Stacked) is deliberately NOT read as a prop — there is no
+// prop for it in code. It mirrors a real CSS state (card.css's media+content grid
+// stacks by default and only goes side-by-side inside a container query at
+// breakpoint.contentCard) but that state is driven entirely by the card's own
+// rendered width, not by anything settable. Both Layout values produce identical
+// code — it's a Figma-only preview of "narrow" vs "wide" container width, added so
+// designers can show cards stacked in a grid without implying a prop exists.
+
+// Media is a real INSTANCE_SWAP — can resolve to either CardMedia (default) or a
+// bare Video. Real gap: swapping to Video only participates correctly in the card's
+// grid if it's given className="mx-card__media" (Video.tsx does forward className),
+// but Code Connect can't inject a prop into another component's own executed
+// template — so a Video swap renders Video's normal standalone example, and the
+// className would need to be added by hand. Documented here, not silently guessed.
+const mediaInstance = instance.getInstanceSwap("Media")
+const mediaCode =
+  mediaInstance && mediaInstance.type === "INSTANCE"
+    ? mediaInstance.executeTemplate().example
+    : figma.code`<CardMedia><Media src="..." alt="" /></CardMedia>`
+
+const contentCode = instance.getSlot("Content")
+
+const reversedProp = reversed ? " reversed" : ""
+const backgroundProp = background ? ` background={${background}}` : ""
+
+// `block` (full-card clickable link overlay) and `as` (wrapper tag) have no visual
+// effect and aren't modelled. Media/Content are always authored in the same JSX
+// order — `reversed` only reorders them visually via CSS grid-area, it does NOT
+// reorder the actual children in code.
+export default {
+  example: figma.code`<Card${reversedProp}${backgroundProp}>
+  ${mediaCode}
+  ${contentCode}
+</Card>`,
+  imports: ['import { Card, BackgroundStyles } from "@pnx-mixtape/mxds/react"'],
+  id: "card",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Card/Card.stories.ts

@@ -1,13 +1,7 @@
 import { Meta, StoryObj } from "@storybook/html-vite"
 import Component from "./card.twig"
 import "./card.css"
-import {
-  Card as CardType,
-  HeadingTypes,
-  ListItemModifiers,
-  PopoverPlacementModifier,
-  TagTypes,
-} from "@pnx-mixtape/ids-shape"
+import { Card as CardType, HeadingTypes, ListItemModifiers, TagTypes } from "@pnx-mixtape/ids-shape"
 import { Icons, BackgroundStyles } from "../../enums"
 
 // Deps.
@@ -15,11 +9,13 @@ import Heading from "../../Atom/Heading/heading.twig"
 import Link from "../../Atom/Link/link.twig"
 import Image from "../../Atom/Image/image.twig"
 import Tags from "../Tag/tags.twig"
+import TagItem from "../Tag/tag-item.twig"
 import LinkList from "../LinkList/link-list.twig"
 import Icon from "../../Atom/Icon/icon.twig"
 // css
 import "../Tag/tag.css"
 import "../LinkList/link-list.css"
+import { modes } from "../../../.storybook/modes"
 
 export type MxCardType = Omit<CardType, "modifiers"> & {
   modifiers?: ListItemModifiers[]
@@ -148,6 +144,14 @@ const meta: Meta<MxCardType> = {
       },
     },
   },
+  parameters: {
+    chromatic: {
+      modes: {
+        mobile: modes["xs"],
+        desktop: modes["xl"],
+      },
+    },
+  },
 }
 
 export default meta
@@ -198,8 +202,7 @@ export const Date: Story = {
 export const WithTags: Story = {
   args: {
     tags: Tags({
-      items: ["Music", "News"],
-      type: TagTypes.TEXT,
+      items: ["Music", "News"].map(item => TagItem({ type: TagTypes.TEXT, item })).join(""),
     }),
   },
 }
@@ -215,6 +218,7 @@ export const WithLinkList: Story = {
         Link({
           title: "Link one",
           href: "#",
+          listItem: true,
           iconEnd: Icon({
             icon: Icons.CHEVRON_RIGHT,
           }),
@@ -222,6 +226,7 @@ export const WithLinkList: Story = {
         Link({
           title: "Link two",
           href: "#",
+          listItem: true,
           iconEnd: Icon({
             icon: Icons.CHEVRON_RIGHT,
           }),
@@ -229,11 +234,12 @@ export const WithLinkList: Story = {
         Link({
           title: "Link three",
           href: "#",
+          listItem: true,
           iconEnd: Icon({
             icon: Icons.CHEVRON_RIGHT,
           }),
         }),
-      ],
+      ].join(""),
     }),
   },
 }

package/src/Component/Card/Components/CardContent.figma.ts

@@ -0,0 +1,28 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=51-7
+// source=src/Component/Card/Components/CardContent.tsx
+// component=CardContent
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const headingHandle = instance.findText("Heading")
+const heading = headingHandle.type === "TEXT" ? headingHandle.textContent : ""
+
+// "Content" holds the flexible body content (currently just a Text layer, but
+// designers can put anything there — a link, multiple paragraphs, etc.).
+const content = instance.getSlot("Content")
+
+export default {
+  example: figma.code`<CardContent>
+  <Heading as={HeadingTypes.THREE}>${heading}</Heading>
+  ${content}
+</CardContent>`,
+  imports: [
+    'import { CardContent, Heading } from "@pnx-mixtape/mxds/react"',
+    'import { HeadingTypes } from "@pnx-mixtape/ids-shape"',
+  ],
+  id: "card-content",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Card/Components/CardContent.tsx

@@ -2,7 +2,7 @@ import { JSX, PropsWithChildren } from "react"
 import classNames from "classnames"
 
 const CardContent = ({ children }: PropsWithChildren): JSX.Element => {
-  return <div className={classNames("mx-card__content", "mx-vertical-flow")}>{children}</div>
+  return <div className={classNames("mx-card__content", "mx-vertical-flow-flex")}>{children}</div>
 }
 
 export default CardContent

package/src/Component/Card/Components/CardMedia.figma.ts

@@ -0,0 +1,15 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=51-5
+// source=src/Component/Card/Components/CardMedia.tsx
+// component=CardMedia
+import figma from "figma"
+
+// `skeleton` (boolean, loading-state placeholder) not modelled — a loading-state
+// visual, not a design variant.
+export default {
+  example: figma.code`<CardMedia><Media src="..." alt="" /></CardMedia>`,
+  imports: ['import { CardMedia, Media } from "@pnx-mixtape/mxds/react"'],
+  id: "card-media",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/Card/README.md

@@ -1,15 +1,270 @@
 # Card
 
-### How to use
+A flexible content card displaying a combination of media, icon, title, body text, tags, date, and links. Stacks vertically on mobile, switches to a side-by-side layout at wider containers using CSS container queries.
 
-**CSS**
+## CSS Import
 
-`@import @pnx-mixtape/mxds/src/Component/Card/card.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Component/Card/card.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/Card/card.twig' %}`
+```twig
+{# Standard card with media, heading, content and a "more" link #}
+{% include '@mixtape/Component/Card/card.twig' with {
+  title: heading_component,
+  content: '<p>A short description.</p>',
+  image: image_component,
+  link: more_link_component,
+} %}
 
-Alternatively copy/paste the file for more control.
+{# Dark background card via modifiers — the template maps dark/light/supplementary
+   to background classes instead of treating them as card modifiers #}
+{% include '@mixtape/Component/Card/card.twig' with {
+  title: heading_component,
+  content: '<p>Description text.</p>',
+  modifiers: ['dark'],
+  icon: icon_component,
+} %}
+
+{# Block-link card (entire card is clickable — wrap the title in a Link) #}
+{% include '@mixtape/Component/Card/card.twig' with {
+  title: heading_with_link_component,
+  content: '<p>Description text.</p>',
+  modifiers: ['block'],
+  image: image_component,
+} %}
+
+{# Compact horizontal layout on narrow screens #}
+{% include '@mixtape/Component/Card/card.twig' with {
+  title: heading_component,
+  content: '<p>Article description.</p>',
+  image: image_component,
+  collapse: true,
+} %}
+```
+
+**card.twig props** (`Card` type from `ids-shape`, extends `WayfindingBlock`):
+
+| Prop         | Type             | Required | Description                                                                                                     |
+| ------------ | ---------------- | -------- | --------------------------------------------------------------------------------------------------------------- |
+| `title`      | `Heading`        | No       | Rendered Heading atom — placed inside `mx-card__content`                                                        |
+| `content`    | `WysiwygText`    | No       | Body text — wrapped in `<div class="mx-text--lede">`                                                            |
+| `image`      | `Image`          | No       | Rendered Image atom — placed inside `<figure class="mx-card__media">`                                           |
+| `icon`       | `Icon`           | No       | Rendered Icon atom — placed inside `<div class="mx-card__icon">` above the content                              |
+| `tags`       | `Tags \| string` | No       | Pre-rendered Tags markup placed at the top of the content area                                                  |
+| `date`       | `string`         | No       | Date string rendered as `<div class="mx-text--s">` above the title                                              |
+| `link`       | `Link \| Button` | No       | Optional rendered Link or Button at the end of the content area                                                 |
+| `linkList`   | `LinkList`       | No       | Optional rendered LinkList placed before `link`                                                                 |
+| `background` | `string`         | No       | Adds `mx-background--{background}` directly                                                                     |
+| `collapse`   | `boolean`        | No       | Adds `mx-card--collapse` (compact horizontal layout on narrow screens)                                          |
+| `modifiers`  | `CardModifier[]` | No       | See below — `dark`/`light`/`supplementary` map to background classes; other values become `mx-card--{modifier}` |
+| `attributes` | `Attribute`      | No       | Optional Drupal-style attributes object — modifier classes are merged on top                                    |
+
+The `modifiers` array has special handling. The values `dark`, `light`, and `supplementary` are translated to `mx-background--reverse`, `mx-background--alt`, and `mx-background--primary` respectively (overriding any explicit `background` prop). Any other value is appended as `mx-card--{modifier}` — for example `block` produces `mx-card--block` for a block-link card.
+
+---
+
+## HTML
+
+```html
+<div class="mx-container">
+  <article class="mx-card">
+    <figure class="mx-card__media">
+      <img src="/photo.jpg" alt="Description" />
+    </figure>
+    <div class="mx-card__content mx-vertical-flow">
+      <h3>Card title</h3>
+      <p class="mx-text--lede">A short description.</p>
+      <a class="mx-link mx-link--more" href="/read-more">Learn more</a>
+    </div>
+  </article>
+</div>
+```
+
+### With background & icon
+
+```html
+<div class="mx-container">
+  <article class="mx-card mx-background--primary">
+    <div class="mx-card__icon">
+      <!-- Icon atom -->
+    </div>
+    <div class="mx-card__content mx-vertical-flow-flex">
+      <h3>Feature card</h3>
+      <p>Description text.</p>
+    </div>
+  </article>
+</div>
+```
+
+---
+
+## React
+
+Uses a composition pattern — always use `CardContent` and `CardMedia` as named slots inside `Card`.
+
+```tsx
+import { Card, CardContent, CardMedia, Heading, Text, Link, Media } from "@pnx-mixtape/mxds/react"
+import { BackgroundStyles } from "../../enums"
+import { AsTypes } from "@pnx-mixtape/ids-shape"
+
+// Standard card with image
+<Card>
+  <CardMedia>
+    <Media src="/photo.jpg" alt="Description" />
+  </CardMedia>
+  <CardContent>
+    <Heading>Card title</Heading>
+    <Text>A short description of the content.</Text>
+    <Link more to="/read-more">Learn more</Link>
+  </CardContent>
+</Card>
+
+// Reversed layout (image on right at wide containers)
+<Card reversed>
+  <CardMedia>
+    <Media src="/photo.jpg" alt="" />
+  </CardMedia>
+  <CardContent>
+    <Heading>Reversed card</Heading>
+    <Text>Image appears on the right at wider breakpoints.</Text>
+  </CardContent>
+</Card>
+
+// Block link (entire card is clickable)
+<Card block>
+  <CardMedia>
+    <Media src="/photo.jpg" alt="" />
+  </CardMedia>
+  <CardContent>
+    <Heading>
+      <Link to="/article">Article title <span className="sr-only">– read more</span></Link>
+    </Heading>
+    <Text>Description text.</Text>
+  </CardContent>
+</Card>
+
+// With background colour
+<Card background={BackgroundStyles.REVERSE}>
+  <CardContent>
+    <Heading>Dark card</Heading>
+    <Text>Content on a dark background.</Text>
+  </CardContent>
+</Card>
+
+// Rendered as <li> inside a grid list
+<Card as={AsTypes.LI}>
+  <CardContent>
+    <Heading>List item card</Heading>
+  </CardContent>
+</Card>
+```
+
+**`Card` props:**
+
+| Prop         | Type               | Default | Description                                                                        |
+| ------------ | ------------------ | ------- | ---------------------------------------------------------------------------------- |
+| `reversed`   | `boolean`          | `false` | Image appears on the right side at wide containers                                 |
+| `block`      | `boolean`          | `false` | Makes the entire card a clickable block link — place `<Link>` inside the heading   |
+| `as`         | `AsTypes`          | `div`   | Semantic element for the outer wrapper: `div`, `li`, `article`, `aside`, `section` |
+| `background` | `BackgroundStyles` | —       | Applies a background colour variant                                                |
+| `className`  | `string`           | —       | Extra class on the `<article>`                                                     |
+
+**`CardMedia` props:** `skeleton?: boolean` — shows a loading skeleton placeholder behind the image (useful while images load)
+
+---
+
+## Background / colour modifiers (`CardModifier` enum from `ids-shape`)
+
+In Twig, pass `modifiers` to map to background classes:
+
+| `CardModifier` value | Maps to                  | Appearance                  |
+| -------------------- | ------------------------ | --------------------------- |
+| `dark`               | `mx-background--reverse` | Dark background, light text |
+| `light`              | `mx-background--alt`     | Subtle off-white background |
+| `supplementary`      | `mx-background--primary` | Brand primary background    |
+
+In React, pass a `BackgroundStyles` value directly to `background`:
+
+```tsx
+<Card background={BackgroundStyles.PRIMARY}>...</Card>
+<Card background={BackgroundStyles.REVERSE}>...</Card>
+<Card background={BackgroundStyles.ALT}>...</Card>
+```
+
+---
+
+## Layout behaviour
+
+The card uses **CSS container queries** (`mx-container`) — not viewport breakpoints — so its two-column layout triggers based on the card's own available width, not the page width. This means cards in a 3-column grid switch layout at a different point than cards in a full-width section.
+
+| Container width | Layout                                       |
+| --------------- | -------------------------------------------- |
+| Below `720px`   | Stacked (media above content)                |
+| 720px+          | Side by side (media left, content right)     |
+| 946px+          | Wider gap (`6rem`) between media and content |
+
+---
+
+## Block link card
+
+When `block={true}` (React) or `mx-card--block` (HTML), the entire card becomes a single click target. The focus outline appears on the card itself.
+
+Best practice: place a visually-hidden `<span className="sr-only">` inside the `<Link>` to give screen readers meaningful context:
+
+```tsx
+<Link to="/article">
+  Article title <span className="sr-only">– read more about this topic</span>
+</Link>
+```
+
+---
+
+## Collapse variant
+
+`mx-card--collapse` hides paragraph text on mobile, and switches the card to a compact horizontal layout with a small square thumbnail on narrow screens.
+
+```html
+<article class="mx-card mx-card--collapse">...</article>
+```
+
+---
+
+## Card grids
+
+When exactly two cards are in an `mx-grid`, each card is capped at `37ch` wide and centred — preventing two cards from stretching uncomfortably across a wide grid.
+
+Use `SectionGrid` (React) or `mx-grid mx-grid--cols-md-3` (HTML) to create multi-column card layouts:
+
+```tsx
+import { SectionGrid } from "@pnx-mixtape/mxds/react"
+import { GridModifiers, SectionModifiers } from "@pnx-mixtape/ids-shape"
+;<SectionGrid sizes={SectionModifiers.L} cols={GridModifiers.MD_3}>
+  <Card as={AsTypes.LI}>...</Card>
+  <Card as={AsTypes.LI}>...</Card>
+  <Card as={AsTypes.LI}>...</Card>
+</SectionGrid>
+```
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-card {
+  --card-gap: var(--gap-l); /* gap between media and content */
+  --large-card-gap: 4rem; /* gap at large container widths */
+  --media-col: 1fr; /* media column width */
+  --content-col: 1fr; /* content column width */
+  --content-min-spacing: var(--spacing-m); /* padding inside background cards */
+  --max-card-width: 40ch; /* max width when only 2 cards in a grid */
+}
+```
+
+---
+
+→ Used in context: `mockups/ArticlePage.stories.ts:12`