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

package/src/Component/LinkList/README.md

@@ -1,19 +1,180 @@
-# Link List
+# LinkList
 
-### How to use
+A simple vertical list of navigation links, each with a trailing icon and a divider between items. Commonly used as an aside inside `HeroBanner`, `HeroSearch`, `Card`, and `ContentBlock` to surface popular or related links.
 
-**CSS**
+## CSS Import
 
-`@import '@pnx-mixtape/mxds/src/Component/LinkList/link-list.css';`
+```css
+@import "@pnx-mixtape/mxds/src/Component/LinkList/link-list.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/LinkList/link-list.twig' %}`
+```twig
+{% include '@mixtape/Component/LinkList/link-list.twig' with {
+  title: heading_component,
+  items: [
+    link_component_1,
+    link_component_2,
+    link_component_3,
+  ]
+} %}
+```
 
-Alternatively copy/paste the file for more control.
+Each item is expected to be a rendered `Link` component that includes an `iconEnd` — typically `chevron-right`:
 
-**JSX Components**
+```twig
+{% include '@mixtape/Atom/Link/link.twig' with {
+  title: 'Music',
+  href: '/music',
+  iconEnd: include('@mixtape/Atom/Icon/icon.twig', { icon: 'chevron-right' }),
+} %}
+```
 
-- JSX import: `import { LinkList, LinkListItem } from '@pnx-mixtape/mxds/src/react';`
+**link-list.twig props:**
+
+| Prop         | Type        | Required | Description                                                                                              |
+| ------------ | ----------- | -------- | -------------------------------------------------------------------------------------------------------- |
+| `title`      | `Heading`   | no       | Optional rendered `Heading` component shown above the list                                               |
+| `items`      | `Link[]`    | yes      | Array of rendered `Link` components — each should include a trailing `iconEnd` (usually `chevron-right`) |
+| `attributes` | `Attribute` | no       | Drupal-style attribute object; `mx-link-list` is appended automatically                                  |
+
+---
+
+## HTML
+
+Minimal working markup — an unordered list with `mx-link-list`, each item containing a link with a trailing `mx-icon` span.
+
+```html
+<ul class="mx-link-list">
+  <li>
+    <a class="mx-link" href="/music">
+      Music
+      <span class="mx-icon mx-icon--chevron-right"></span>
+    </a>
+  </li>
+  <li>
+    <a class="mx-link" href="/performances">
+      Performances
+      <span class="mx-icon mx-icon--chevron-right"></span>
+    </a>
+  </li>
+  <li>
+    <a class="mx-link" href="/get-involved">
+      Get involved
+      <span class="mx-icon mx-icon--chevron-right"></span>
+    </a>
+  </li>
+</ul>
+```
+
+With an optional heading above the list:
+
+```html
+<h2 class="mx-heading--m">Popular links</h2>
+<ul class="mx-link-list">
+  <!-- items -->
+</ul>
+```
+
+---
+
+## React
+
+`LinkList` renders a `<ul class="mx-link-list">`. Each `LinkListItem` renders a `<li>` containing a `<Link>` with the item label and a trailing icon.
+
+```tsx
+import { LinkList, LinkListItem } from "@pnx-mixtape/mxds/react"
+import { Icons } from "@pnx-mixtape/mxds/src/enums"
+
+// Default — chevron-right icon
+<LinkList>
+  <LinkListItem to="/music">Music</LinkListItem>
+  <LinkListItem to="/performances">Performances</LinkListItem>
+  <LinkListItem to="/get-involved">Get involved</LinkListItem>
+</LinkList>
+
+// With a custom trailing icon
+<LinkList>
+  <LinkListItem to="/brochure.pdf" icon={Icons.DOWNLOAD}>Download brochure</LinkListItem>
+  <LinkListItem to="https://example.com" icon={Icons.EXTERNAL}>Visit partner site</LinkListItem>
+</LinkList>
+
+// With a preceding heading (heading is a sibling, not a child)
+<>
+  <h2 className="mx-heading--m">Popular links</h2>
+  <LinkList>
+    <LinkListItem to="#1">Page link #1</LinkListItem>
+    <LinkListItem to="#2">Page link #2</LinkListItem>
+    <LinkListItem to="#3">Page link #3</LinkListItem>
+  </LinkList>
+</>
+```
+
+**`LinkList` props:**
+
+| Prop       | Type        | Default | Description                           |
+| ---------- | ----------- | ------- | ------------------------------------- |
+| `children` | `ReactNode` | —       | One or more `LinkListItem` components |
+
+**`LinkListItem` props:**
+
+| Prop        | Type        | Default               | Description                                     |
+| ----------- | ----------- | --------------------- | ----------------------------------------------- |
+| `to`        | `string`    | — (required)          | Destination URL passed to the underlying `Link` |
+| `icon`      | `Icons`     | `Icons.CHEVRON_RIGHT` | Trailing icon rendered after the label          |
+| `className` | `string`    | —                     | Extra class on the `<li>` wrapper               |
+| `children`  | `ReactNode` | —                     | Link label content                              |
+
+---
+
+## Modifiers
+
+LinkList has no modifier enum and no variant classes. The only visual lever is the per-item `icon` (React) / `iconEnd` (Twig). Valid icon values come from the `Icons` enum in `@pnx-mixtape/mxds/src/enums` — commonly used in this component:
+
+| React `Icons` value   | String            | Visual intent                                  |
+| --------------------- | ----------------- | ---------------------------------------------- |
+| `Icons.CHEVRON_RIGHT` | `"chevron-right"` | Default — indicates navigation to another page |
+| `Icons.EXTERNAL`      | `"external-link"` | Link leaves the site                           |
+| `Icons.DOWNLOAD`      | `"download"`      | Link downloads a file                          |
+
+Any other `Icons` enum value is accepted — these are the conventional choices for a link list.
+
+---
+
+## Usage inside other components
+
+`LinkList` is a recognised aside option for:
+
+- `HeroBanner` — pass as the `linkList` Twig prop (takes precedence over `image`).
+- `HeroSearch` — pass as the `linkList` Twig prop.
+- `Card` — pass as the `linkList` Twig prop.
+- `ContentBlock` — pass as the `linkList` Twig prop (often used here for related-links patterns).
+
+When used as an aside, pair the list with a short heading (typically an `<h2>` or `<h3>`) as a sibling element so the list has a clear label in the document outline.
+
+---
+
+## Accessibility
+
+- The component renders a native `<ul>` of `<li>`s — screen readers announce it as a list with an item count.
+- Each `<a>` has `text-decoration-line: none` by default and gains an underline on `:hover`. Keyboard focus styling comes from the `Link` atom.
+- The trailing icon is rendered as a decorative `<span>` with no text — it is not announced to assistive tech. Never rely on the icon alone to convey meaning (e.g. "download" or "external link"); include that context in the link text or via `allyText` on the React `Link` when necessary.
+- When used as a navigational aside, provide a sibling heading above the list so assistive-tech users can identify its purpose.
+- The last item has its bottom border removed — purely decorative, no accessibility impact.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-link-list {
+  --min-height: var(--spacing-xl); /* min-block-size of each <li> */
+  --line-width: 1px; /* thickness of the divider between items */
+  --line-colour: var(--colour-border); /* colour of the divider */
+  --vertical-padding: var(--spacing-xxxs); /* padding-block on each link */
+  --justify: space-between; /* justify-content inside the link — puts icon at end */
+}
+```

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

@@ -4,8 +4,8 @@ exports[`Link List 1`] = `
 "
 
 <ul class="mx-link-list">
-      <li>
-<a href="#">
+  
+<li><a href="#">
   
   <span>Music</span>
     
@@ -13,8 +13,7 @@ exports[`Link List 1`] = `
 
 </a>
 </li>
-      <li>
-<a href="#">
+<li><a href="#">
   
   <span>Performances</span>
     
@@ -22,8 +21,7 @@ exports[`Link List 1`] = `
 
 </a>
 </li>
-      <li>
-<a href="#">
+<li><a href="#">
   
   <span>Get involved</span>
     
@@ -31,7 +29,7 @@ exports[`Link List 1`] = `
 
 </a>
 </li>
-  </ul>
+</ul>
 "
 `;
 
@@ -41,8 +39,8 @@ exports[`With Title 1`] = `
 <h2 class="mx-heading--m">Popular links</h2>
 
 <ul class="mx-link-list">
-      <li>
-<a href="#">
+  
+<li><a href="#">
   
   <span>Music</span>
     
@@ -50,8 +48,7 @@ exports[`With Title 1`] = `
 
 </a>
 </li>
-      <li>
-<a href="#">
+<li><a href="#">
   
   <span>Performances</span>
     
@@ -59,8 +56,7 @@ exports[`With Title 1`] = `
 
 </a>
 </li>
-      <li>
-<a href="#">
+<li><a href="#">
   
   <span>Get involved</span>
     
@@ -68,6 +64,6 @@ exports[`With Title 1`] = `
 
 </a>
 </li>
-  </ul>
+</ul>
 "
 `;

package/src/Component/LinkList/link-list.twig

@@ -3,7 +3,5 @@
 
 {{ title }}
 <ul{{ attributes }}>
-  {% for item in items %}
-    <li>{{ item }}</li>
-  {% endfor %}
+  {{ items }}
 </ul>

package/src/Component/ListItem/Components/ListItemContent.figma.ts

@@ -0,0 +1,28 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=51-198
+// source=src/Component/ListItem/Components/ListItemContent.tsx
+// component=ListItemContent
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const headingHandle = instance.findText("Heading")
+const heading = headingHandle.type === "TEXT" ? headingHandle.textContent : ""
+
+// "Content" replaced the old fixed "Body" text layer — a real SLOT now, same pattern
+// as CardContent/ContentBlockContent.
+const content = instance.getSlot("Content")
+
+export default {
+  example: figma.code`<ListItemContent>
+  <Heading as={HeadingTypes.THREE}>${heading}</Heading>
+  ${content}
+</ListItemContent>`,
+  imports: [
+    'import { ListItemContent, Heading } from "@pnx-mixtape/mxds/react"',
+    'import { HeadingTypes } from "@pnx-mixtape/ids-shape"',
+  ],
+  id: "list-item-content",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/ListItem/Components/ListItemMedia.figma.ts

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

package/src/Component/ListItem/ListItem.figma.ts

@@ -0,0 +1,20 @@
+// url=https://www.figma.com/design/aGH90DVE6lrFVdLfDCHnFK/mxds---Design-System?node-id=51-201
+// source=src/Component/ListItem/ListItem.tsx
+// component=ListItem
+import figma from "figma"
+
+const instance = figma.selectedInstance
+
+const content = instance.getSlot("Content")
+
+// `as` (wrapper tag, default ARTICLE) has no visual effect, not modelled. The
+// `mx-card--block` className modifier documented in the README is behavioural/
+// focus-outline only — not modelled either.
+export default {
+  example: figma.code`<ListItem>${content}</ListItem>`,
+  imports: ['import { ListItem } from "@pnx-mixtape/mxds/react"'],
+  id: "list-item",
+  metadata: {
+    nestable: true,
+  },
+}

package/src/Component/ListItem/ListItem.stories.ts

@@ -3,15 +3,12 @@ import Component from "./list-item.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 "../Card/card.css"
 import "./list-item.css"
 import "../Tag/tag.css"
-import {
-  HeadingTypes,
-  ListItem as ListItemType,
-  ListItemModifiers,
-  TagTypes,
-} from "@pnx-mixtape/ids-shape"
+import { ListItem as ListItemType, ListItemModifiers, TagTypes } from "@pnx-mixtape/ids-shape"
+import { modes } from "../../../.storybook/modes"
 
 /**
  * List Item extends the Card to create a search result type component.
@@ -102,6 +99,14 @@ const meta: Meta<ListItemType> = {
       },
     },
   },
+  parameters: {
+    chromatic: {
+      modes: {
+        mobile: modes["xs"],
+        desktop: modes["xl"],
+      },
+    },
+  },
 }
 
 export default meta
@@ -145,8 +150,7 @@ export const WithTags: Story = {
   args: {
     label: "Resource",
     tags: Tags({
-      items: ["Music", "News"],
-      type: TagTypes.TEXT,
+      items: ["Music", "News"].map(item => TagItem({ type: TagTypes.TEXT, item })).join(""),
     }),
   },
 }

package/src/Component/ListItem/ListItem.stories.tsx

@@ -7,12 +7,13 @@ import { TextStyles, TextTags } from "../../enums"
 import { Page } from "../../../.storybook-react/decorators"
 
 const meta: Meta<typeof Component> = {
+  tags: ["autodocs"],
   decorators: [Page],
   component: Component,
   args: {
     children: (
       <ListItemContent>
-        <Text modifier={TextStyles.S} tag={TextTags.STRONG}>
+        <Text modifier={TextStyles.S} as={TextTags.STRONG}>
           label
         </Text>
         <div className="mx-heading--m">

package/src/Component/ListItem/README.md

@@ -0,0 +1,233 @@
+# ListItem
+
+A horizontal search-result style list entry that extends the Card component. Supports an optional thumbnail, label, date or URL info line, tag list, and a "block link" interaction where the whole row is clickable. Designed to stack in vertical lists (search results, publication lists, resource listings) with a dividing border between items.
+
+## CSS Import
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/ListItem/list-item.css";
+```
+
+ListItem reuses Card styles, so both stylesheets are needed:
+
+```css
+@import "@pnx-mixtape/mxds/src/Component/Card/card.css";
+@import "@pnx-mixtape/mxds/src/Component/ListItem/list-item.css";
+```
+
+---
+
+## Twig
+
+```twig
+{% include '@mixtape/Component/ListItem/list-item.twig' with {
+  link: link_component,
+  content: '<p>Short summary of the item.</p>',
+  label: 'Publication',
+  info: '25 May 2025',
+  infoBefore: true,
+  image: image_component,
+  tags: tags_component,
+  modifiers: ['block'],
+} %}
+```
+
+**list-item.twig props** (`ListItem` type from `ids-shape`):
+
+| Prop         | Type                  | Description                                                                     |
+| ------------ | --------------------- | ------------------------------------------------------------------------------- |
+| `link`       | `Link`                | Required — rendered as the heading / title link                                 |
+| `content`    | `WysiwygText`         | Required — body copy (HTML string)                                              |
+| `label`      | `string`              | Optional label displayed above the title (`<strong class="mx-text--s">`)        |
+| `info`       | `string`              | Optional secondary line — date, URL, metadata                                   |
+| `infoBefore` | `boolean`             | If `true`, render `info` above the title; otherwise below. Default `false`      |
+| `image`      | `Image`               | Optional thumbnail. Presence of an image automatically adds `mx-card--collapse` |
+| `tags`       | `Tags`                | Optional trailing [Tags](../Tag) component                                      |
+| `modifiers`  | `ListItemModifiers[]` | Array of modifier enum values — see below                                       |
+
+---
+
+## HTML
+
+Minimal markup — ListItem reuses the Card class names (`mx-card`, `mx-card__content`, `mx-card__media`) with an added `mx-list-item` class. When an image is present the item automatically gets `mx-card--collapse`.
+
+```html
+<article class="mx-card mx-list-item">
+  <div class="mx-card__content mx-vertical-flow">
+    <strong class="mx-text--s">Publication</strong>
+    <div class="mx-heading--l">
+      <a href="/article">List item title</a>
+    </div>
+    <div class="mx-text--s">25 May 2025</div>
+    <p>Short summary of the item.</p>
+  </div>
+</article>
+```
+
+### With image (horizontal at wider containers)
+
+```html
+<article class="mx-card mx-list-item mx-card--collapse">
+  <div class="mx-card__content mx-vertical-flow">
+    <div class="mx-heading--l">
+      <a href="/article">List item title</a>
+    </div>
+    <p>Short summary.</p>
+  </div>
+  <figure class="mx-card__media">
+    <img src="/thumb.jpg" alt="" />
+  </figure>
+</article>
+```
+
+### Block link
+
+```html
+<article class="mx-card mx-list-item mx-card--block">
+  <div class="mx-card__content mx-vertical-flow">
+    <div class="mx-heading--l">
+      <a href="/article">List item title <span class="sr-only">– read more</span></a>
+    </div>
+    <p>Entire row is clickable.</p>
+  </div>
+</article>
+```
+
+---
+
+## React
+
+Uses a composition pattern — use `ListItemContent` and `ListItemMedia` as named slots inside `ListItem`.
+
+```tsx
+import { ListItem, ListItemContent, ListItemMedia, Text, Link, Media } from "@pnx-mixtape/mxds/react"
+import { TextStyles, TextTags } from "@pnx-mixtape/mxds/src/enums"
+import { AsTypes } from "@pnx-mixtape/ids-shape"
+
+// Default — label, title, date and body copy
+<ListItem>
+  <ListItemContent>
+    <Text modifier={TextStyles.S} as={TextTags.STRONG}>Publication</Text>
+    <div className="mx-heading--l">
+      <Link to="/article">List item title</Link>
+    </div>
+    <Text modifier={TextStyles.S}>25 May 2025</Text>
+    <p>Short summary of the item.</p>
+  </ListItemContent>
+</ListItem>
+
+// With image (switches to horizontal layout at wide containers)
+<ListItem>
+  <ListItemContent>
+    <div className="mx-heading--l">
+      <Link to="/article">List item title</Link>
+    </div>
+    <p>Short summary of the item.</p>
+  </ListItemContent>
+  <ListItemMedia>
+    <Media src="/thumb.jpg" alt="" />
+  </ListItemMedia>
+</ListItem>
+
+// Block link — apply mx-card--block via className, place <Link> inside the heading
+<ListItem className="mx-card--block">
+  <ListItemContent>
+    <div className="mx-heading--l">
+      <Link to="/article">
+        List item title <span className="sr-only">– read more</span>
+      </Link>
+    </div>
+    <p>The entire row is now a single click target.</p>
+  </ListItemContent>
+</ListItem>
+
+// Reversed layout — image on the right at wide containers
+<ListItem className="mx-card--reversed">
+  <ListItemContent>
+    <div className="mx-heading--l">
+      <Link to="/article">List item title</Link>
+    </div>
+  </ListItemContent>
+  <ListItemMedia>
+    <Media src="/thumb.jpg" alt="" />
+  </ListItemMedia>
+</ListItem>
+
+// Rendered as <li> inside a semantic list
+<ListItem as={AsTypes.LI}>
+  <ListItemContent>
+    <div className="mx-heading--l">
+      <Link to="/article">List item title</Link>
+    </div>
+  </ListItemContent>
+</ListItem>
+```
+
+**`ListItem` props:**
+
+| Prop        | Type      | Default   | Description                                                                                               |
+| ----------- | --------- | --------- | --------------------------------------------------------------------------------------------------------- |
+| `as`        | `AsTypes` | `article` | Semantic element for the outer wrapper: `article`, `div`, `li`, `aside`, `section`                        |
+| `className` | `string`  | —         | Extra class on the wrapper — use `mx-card--block` or `mx-card--reversed` to apply the `ListItemModifiers` |
+
+**`ListItemMedia` props:** `skeleton?: boolean` — renders a loading skeleton placeholder behind the image.
+
+**`ListItemContent`** has no props — it wraps children in `.mx-list-item__content.mx-vertical-flow`.
+
+---
+
+## Modifiers
+
+The `modifiers` prop accepts an array of `ListItemModifiers` enum values from `@pnx-mixtape/ids-shape`. Each value is converted to a class `mx-card--{value}` by the twig template.
+
+| `ListItemModifiers` | Value        | Class applied       | Visual intent                                                                                                                                                                                                             |
+| ------------------- | ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BLOCK`             | `"block"`    | `mx-card--block`    | Makes the entire row a single clickable target. The heading link colour changes on wrapper hover; the focus ring appears on the row itself. Place a visually hidden phrase inside the `<Link>` for screen-reader context. |
+| `REVERSE`           | `"reversed"` | `mx-card--reversed` | At wide container widths the thumbnail sits on the right, content on the left (default is thumbnail left, content right).                                                                                                 |
+
+These are the only two members of the `ListItemModifiers` enum. There is no `collapse` modifier — `mx-card--collapse` is added automatically whenever an image is present.
+
+### React equivalent
+
+React's `ListItem` has no dedicated `modifiers` prop — pass the corresponding class via `className`:
+
+```tsx
+<ListItem className="mx-card--block">...</ListItem>
+<ListItem className="mx-card--reversed">...</ListItem>
+<ListItem className="mx-card--block mx-card--reversed">...</ListItem>
+```
+
+---
+
+## Accessibility
+
+- The outer element defaults to `<article>`, giving each entry an implicit landmark in a search-results context. Use `as={AsTypes.LI}` when nesting inside a semantic `<ul>`/`<ol>`.
+- The heading level is not enforced — wrap the `<Link>` in an appropriate `<h2>`/`<h3>` element in your own markup for correct document outline. The `.mx-heading--l` class only provides the visual style.
+- When using `mx-card--block`, include visually-hidden context inside the link so screen-reader users know what they are activating:
+  ```tsx
+  <Link to="/article">
+    List item title <span className="sr-only">– read more about this topic</span>
+  </Link>
+  ```
+- Decorative thumbnails should have `alt=""`. Meaningful thumbnails need descriptive alt text.
+- The dividing border between items is purely decorative and needs no ARIA handling.
+
+---
+
+## Customisation via CSS custom properties
+
+```css
+.mx-list-item {
+  --media-col: 200px; /* thumbnail column width (image-width) */
+  --ratio: 1; /* aspect ratio of the thumbnail figure */
+  --large-card-gap: var(--gap-l); /* gap between media and content */
+  --card-alignment: start; /* vertical alignment of media vs content */
+  --line-width: 1px; /* divider between list items */
+  --line-colour: var(--colour-border); /* divider colour */
+  --gap: var(--gap-m); /* divider spacing above each item */
+}
+```
+
+---
+
+→ Used in context: `mockups/ArticleListingPage.stories.ts:10`