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

package/src/Atom/DefinitionList/DefinitionList.tsx

@@ -1,4 +1,4 @@
-import { JSX, ComponentPropsWithoutRef, PropsWithChildren } from "react"
+import { JSX, ComponentPropsWithoutRef, PropsWithChildren, ReactNode } from "react"
 
 type DefinitionListProps = ComponentPropsWithoutRef<"dl"> & PropsWithChildren
 
@@ -9,16 +9,19 @@ const DefinitionList = ({ children, ...props }: DefinitionListProps): JSX.Elemen
 type DefinitionListItemProps = ComponentPropsWithoutRef<"div"> &
   PropsWithChildren & {
     title: string
+    action?: ReactNode
   }
 
 const DefinitionListItem = ({
   title,
+  action = null,
   children,
   ...props
 }: DefinitionListItemProps): JSX.Element => (
   <div {...props}>
     <dt>{title}</dt>
     <dd>{children}</dd>
+    {action && <dd className="mx-list__action">{action}</dd>}
   </div>
 )
 

package/src/Atom/DefinitionList/DefinitionListItem.stories.ts

@@ -7,7 +7,7 @@ import { DefinitionListItem as DefinitionListItemType } from "@pnx-mixtape/ids-s
  * A single title/content pair used by [DefinitionList](/?path=/docs/atom-definitionlist--docs).
  */
 const meta: Meta<DefinitionListItemType> = {
-  tags: ["autodocs", "ids-mvp", "no-snapshot"],
+  tags: ["autodocs", "ids-mvp"],
   component: Component,
   args: {
     title: "Some title",

package/src/Atom/DefinitionList/README.md

@@ -37,6 +37,8 @@ No dedicated CSS file — base styles come from the global reset. Import `base.c
 
 The template is consumed by `ids-shape`'s `DefinitionList` type but does not currently render the optional `title` heading the type declares — pass a heading separately above the include if required.
 
+**definition-list-item.twig** also accepts an optional `action` var — see [Summary modifier](#summary-modifier).
+
 ## HTML
 
 ```html
@@ -61,3 +63,44 @@ import DefinitionList, { DefinitionListItem } from "@pnx-mixtape/mxds/react"
   <DefinitionListItem title="Author">Jane Smith</DefinitionListItem>
 </DefinitionList>
 ```
+
+`DefinitionListItem` also accepts an optional `action?: ReactNode` prop — see [Summary modifier](#summary-modifier).
+
+---
+
+## Summary modifier
+
+`ListStyles.SUMMARY` (`mx-list--summary`, from `src/Atom/List`) turns a `DefinitionList` into a "review your answers" block: a term/value/action row layout with dividers between rows, matching the GOV.UK-style summary-list pattern used on a review-and-submit step. Each row's optional third element (`action`) is typically a "Change" link back to the step that set that answer.
+
+```twig
+{% include '@mixtape/Atom/DefinitionList/definition-list.twig' with {
+  summary: true,
+  items: [
+    { title: 'Concession card', content: 'Yes, I hold a card', action: '<a href="#step-1">Change<span class="sr-only"> concession card</span></a>' },
+    { title: 'Full name', content: 'Jane Smith', action: '<a href="#step-2">Change<span class="sr-only"> full name</span></a>' },
+  ],
+} %}
+```
+
+```tsx
+import DefinitionList, { DefinitionListItem } from "@pnx-mixtape/mxds/react"
+import { ListStyles } from "../../enums"
+;<DefinitionList className={ListStyles.SUMMARY}>
+  <DefinitionListItem
+    title="Concession card"
+    action={
+      <a href="#step-1">
+        Change<span className="sr-only"> concession card</span>
+      </a>
+    }
+  >
+    Yes, I hold a card
+  </DefinitionListItem>
+</DefinitionList>
+```
+
+Note the asymmetry: Twig's `definition-list.twig` has a dedicated `summary: true` boolean (mirroring its existing `columns: true`), since Twig always needs an explicit class-selection var. React's `DefinitionList` is a thin `<dl {...props}>` wrapper with no such boolean — pass the modifier class directly via `className` (or `classNames(...)` if combining with other classes), same as any other `ComponentPropsWithoutRef<"dl">` usage.
+
+### React ⇄ Twig parity
+
+`pnpm audit-parity` reports `title`/`action` as Twig-only for this component — that's a tooling artefact, not a real gap: it merges every `.twig` file in this directory (`definition-list.twig` **and** `definition-list-item.twig`) and diffs the combined field list against only the default-exported React component (`DefinitionList`, the `<dl>` wrapper). `title`/`content`/`action` are actually `DefinitionListItem`'s props (the named export), which do have full parity with `definition-list-item.twig` — there's just no single React component the tool can compare `definition-list-item.twig` against directly, the same limitation that gives `Checkbox`/`Radio` an `N/A` rather than a real result.

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

@@ -1,19 +1,53 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`Columns 1`] = `
+"  <dl class="mx-list--columns">
+  <div>
+  <dt>Some title</dt>
+  <dd>Some content</dd>
+  </div>
+<div>
+  <dt>Another title</dt>
+  <dd>More content</dd>
+  </div>
+<div>
+  <dt>Yet another title</dt>
+  <dd>And even more content</dd>
+  </div>
+
+</dl>
+"
+`;
+
 exports[`Definition List 1`] = `
 "<dl>
   <div>
   <dt>Some title</dt>
   <dd>Some content</dd>
-</div>
+  </div>
 <div>
   <dt>Another title</dt>
   <dd>More content</dd>
-</div>
+  </div>
 <div>
   <dt>Yet another title</dt>
   <dd>And even more content</dd>
-</div>
+  </div>
+
+</dl>
+"
+`;
+
+exports[`Summary 1`] = `
+"  <dl class="mx-list--summary">
+  <div>
+  <dt>Concession card</dt>
+  <dd>Yes, I hold a card</dd>
+  <dd class="mx-list__action"><a href="#step-1">Change<span class="sr-only"> concession card</span></a></dd></div>
+<div>
+  <dt>Full name</dt>
+  <dd>Jane Smith</dd>
+  <dd class="mx-list__action"><a href="#step-2">Change<span class="sr-only"> full name</span></a></dd></div>
 
 </dl>
 "

package/src/Atom/DefinitionList/__snapshots__/DefinitionList.stories.tsx.snap

@@ -1,3 +1,5 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`Definition List 1`] = `"<dl><div><dt>Item #1</dt><dd>Data for item #1</dd></div><div><dt>Item #2</dt><dd>Data for item #2</dd></div><div><dt>Item #3</dt><dd>Data for item #3</dd></div></dl>"`;
+
+exports[`Summary 1`] = `"<dl class="mx-list--summary"><div><dt>Concession card</dt><dd>Yes, I hold a card</dd><dd class="mx-list__action"><a href="#step-1">Change<span class="sr-only"> concession card</span></a></dd></div><div><dt>Full name</dt><dd>Jane Smith</dd><dd class="mx-list__action"><a href="#step-2">Change<span class="sr-only"> full name</span></a></dd></div></dl>"`;

package/src/Atom/DefinitionList/__snapshots__/DefinitionListItem.stories.ts.snap

@@ -1,9 +1,9 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`Definition List Item 1`] = `
-"<div>
+"<dl><div>
   <dt>Some title</dt>
   <dd>Some content</dd>
-</div>
-"
+  </div>
+</dl>"
 `;

package/src/Atom/DefinitionList/definition-list-item.twig

@@ -1,4 +1,5 @@
 <div>
   <dt>{{ title }}</dt>
   <dd>{{ content }}</dd>
+  {% if action %}<dd class="mx-list__action">{{ action }}</dd>{% endif %}
 </div>

package/src/Atom/DefinitionList/definition-list.twig

@@ -1,4 +1,9 @@
+{% if columns %}
+  {% set class = "mx-list--columns" %}
+{% elseif summary %}
+  {% set class = "mx-list--summary" %}
+{% endif %}
 {% set attributes = attributes ?? create_attribute() %}
-<dl{{ attributes }}>
+<dl{{ attributes.addClass(class) }}>
   {{ items }}
 </dl>

package/src/Atom/Heading/Heading.tsx

@@ -42,6 +42,12 @@ const Heading = ({
 
   useEffect(() => {
     if (anchor || !ref.current) return
+    if (ref.current.id) {
+      // Adopt an id already set externally (e.g. by InPageNavigation's dedup logic)
+      // eslint-disable-next-line @eslint-react/hooks-extra/no-direct-set-state-in-use-effect
+      setAnchor(ref.current.id)
+      return
+    }
     // eslint-disable-next-line @eslint-react/hooks-extra/no-direct-set-state-in-use-effect
     setAnchor(makeAnchor(ref.current?.textContent))
   }, [anchor, ref])

package/src/Atom/Heading/_headings.css

@@ -14,10 +14,11 @@
     h6,
     .mx-heading--xs
   ) {
-    font-family: var(--heading-font-family, var(--font-family));
+    font-family: var(--heading-font-family, var(--font-family-display, var(--font-family)));
     line-height: var(--line-height-h);
     font-size: var(--heading-font-size, var(--font-size));
     font-weight: var(--heading-font-weight, var(--font-weight-bold));
+    letter-spacing: var(--heading-letter-spacing, 0);
     text-wrap: balance;
 
     &[class*="mx-background--"] {

package/src/Atom/Icon/_extended-set.css

@@ -4,34 +4,34 @@
  * Icon - Extended
  */
 @layer design-system.atoms {
-  @mixin icon attachment;
-  @mixin icon blockquote;
-  @mixin icon building;
-  @mixin icon calendar;
-  @mixin icon clock;
-  @mixin icon globe;
-  @mixin icon heart-selected;
-  @mixin icon heart-unselected;
-  @mixin icon image;
-  @mixin icon home;
-  @mixin icon lock;
-  @mixin icon login;
-  @mixin icon media-play;
-  @mixin icon media-pause;
-  @mixin icon media-stop;
-  @mixin icon media-next;
-  @mixin icon media-previous;
-  @mixin icon media-rewind;
-  @mixin icon media-skip;
-  @mixin icon more;
-  @mixin icon notification;
-  @mixin icon pencil;
-  @mixin icon restart;
-  @mixin icon settings;
-  @mixin icon star-selected;
-  @mixin icon star-unselected;
-  @mixin icon tick;
-  @mixin icon trash;
-  @mixin icon user;
-  @mixin icon video;
+  @add-mixin icon attachment;
+  @add-mixin icon blockquote;
+  @add-mixin icon building;
+  @add-mixin icon calendar;
+  @add-mixin icon clock;
+  @add-mixin icon globe;
+  @add-mixin icon heart-selected;
+  @add-mixin icon heart-unselected;
+  @add-mixin icon image;
+  @add-mixin icon home;
+  @add-mixin icon lock;
+  @add-mixin icon login;
+  @add-mixin icon media-play;
+  @add-mixin icon media-pause;
+  @add-mixin icon media-stop;
+  @add-mixin icon media-next;
+  @add-mixin icon media-previous;
+  @add-mixin icon media-rewind;
+  @add-mixin icon media-skip;
+  @add-mixin icon more;
+  @add-mixin icon notification;
+  @add-mixin icon pencil;
+  @add-mixin icon restart;
+  @add-mixin icon settings;
+  @add-mixin icon star-selected;
+  @add-mixin icon star-unselected;
+  @add-mixin icon tick;
+  @add-mixin icon trash;
+  @add-mixin icon user;
+  @add-mixin icon video;
 }

package/src/Atom/Icon/_icon.css

@@ -1,4 +1,5 @@
 @import "_mixin-icon.css";
+@import "../../Utility/_mixins.css";
 
 /**
  * Icon
@@ -21,6 +22,8 @@
       mask-repeat: no-repeat;
       background-color: currentcolor;
       color: var(--icon-colour, inherit);
+
+      @add-mixin forced-colors-paint;
     }
   }
 
@@ -38,42 +41,42 @@
     }
   }
 
-  @mixin icon arrow-down;
-  @mixin icon arrow-left;
-  @mixin icon arrow-up;
-  @mixin icon arrow-right;
-  @mixin icon chevron-down;
-  @mixin icon chevron-left;
-  @mixin icon chevron-right;
-  @mixin icon chevron-up;
-  @mixin icon close;
-  @mixin icon collapse;
-  @mixin icon download;
-  @mixin icon drupal;
-  @mixin icon error;
-  @mixin icon expand;
-  @mixin icon external-link;
-  @mixin icon facebook;
-  @mixin icon google;
-  @mixin icon info;
-  @mixin icon instagram;
-  @mixin icon linkedin;
-  @mixin icon mastodon;
-  @mixin icon bluesky;
-  @mixin icon menu;
-  @mixin icon search;
-  @mixin icon success;
-  @mixin icon twitter;
-  @mixin icon warning;
-  @mixin icon youtube;
-  @mixin icon email;
-  @mixin icon file;
-  @mixin icon link;
-  @mixin icon phone;
-  @mixin icon pin;
-  @mixin icon print;
-  @mixin icon question;
-  @mixin icon share;
+  @add-mixin icon arrow-down;
+  @add-mixin icon arrow-left;
+  @add-mixin icon arrow-up;
+  @add-mixin icon arrow-right;
+  @add-mixin icon chevron-down;
+  @add-mixin icon chevron-left;
+  @add-mixin icon chevron-right;
+  @add-mixin icon chevron-up;
+  @add-mixin icon close;
+  @add-mixin icon collapse;
+  @add-mixin icon download;
+  @add-mixin icon drupal;
+  @add-mixin icon error;
+  @add-mixin icon expand;
+  @add-mixin icon external-link;
+  @add-mixin icon facebook;
+  @add-mixin icon google;
+  @add-mixin icon info;
+  @add-mixin icon instagram;
+  @add-mixin icon linkedin;
+  @add-mixin icon mastodon;
+  @add-mixin icon bluesky;
+  @add-mixin icon menu;
+  @add-mixin icon search;
+  @add-mixin icon success;
+  @add-mixin icon twitter;
+  @add-mixin icon warning;
+  @add-mixin icon youtube;
+  @add-mixin icon email;
+  @add-mixin icon file;
+  @add-mixin icon link;
+  @add-mixin icon phone;
+  @add-mixin icon pin;
+  @add-mixin icon print;
+  @add-mixin icon question;
+  @add-mixin icon share;
 
   .mx-icon--status::before {
     mask-image: url("./images/info.svg");

package/src/Atom/Image/README.md

@@ -76,8 +76,8 @@ The template always wraps the image in a `<picture>` element so multiple `source
 
 ```css
 figcaption {
-  --caption-font-size: var(--font-size-s);
-  --caption-line-height: var(--line-height);
+  --font-size-ui: var(--font-size-s);
+  --line-height-ui: var(--line-height);
 }
 ```
 

package/src/Atom/Image/_image.css

@@ -1,16 +1,22 @@
 @layer design-system.defaults {
   figure {
     margin: 0;
-    display: table;
-    inline-size: fit-content;
+    display: block;
+    inline-size: var(--width, 100%);
+
+    & :is(picture, img, iframe, video) {
+      inline-size: 100%;
+    }
   }
 
   figcaption {
+    margin-block-start: var(--spacing-xs);
     padding: var(--spacing-xxs);
-    font-size: var(--caption-font-size, var(--font-size-xs));
-    line-height: var(--caption-line-height, var(--line-height-h));
-    caption-side: bottom;
-    display: table-caption;
+    font-family: var(--font-family-ui, var(--font-family));
+    font-size: var(--font-size-ui, var(--font-size-xs));
+    line-height: var(--line-height-ui, var(--line-height-h));
+    color: var(--colour-foreground-alt);
+    display: block;
   }
 
   img {

package/src/Atom/Link/Link.tsx

@@ -1,4 +1,4 @@
-import { JSX, ComponentPropsWithoutRef, PropsWithChildren } from "react"
+import { JSX, ComponentPropsWithoutRef, PropsWithChildren, useId } from "react"
 import classNames from "classnames"
 import { useLinkComponent } from "../../react"
 
@@ -28,6 +28,15 @@ const Link = ({
 
   const externalAttrs = external ? { target: "_blank", rel: "noopener noreferrer" } : {}
 
+  // `children` can be arbitrary JSX, so this can't fold into a single
+  // `aria-label` the way the Twig Link atom does. Instead, the supplemental
+  // text is `aria-describedby`'d and `aria-hidden` - kept out of the normal
+  // accessibility tree walk (so it isn't announced twice) while still
+  // resolving as the link's description, since `aria-hidden` elements remain
+  // valid `aria-describedby` targets.
+  const descriptionId = useId()
+  const hasDescription = external || Boolean(allyText)
+
   return (
     // oxlint-disable-next-line react/static-components -- LinkComponent is a stable reference from context, not created during render
     <LinkComponent
@@ -38,12 +47,16 @@ const Link = ({
         "mx-link--download": download,
       })}
       {...(current ? { "aria-current": "page" as const } : {})}
+      {...(hasDescription ? { "aria-describedby": descriptionId } : {})}
       {...externalAttrs}
       {...props}
     >
       {children}
-      {external && <span className="sr-only">(opens in a new window)</span>}
-      {allyText && <span className="sr-only">{allyText}</span>}
+      {hasDescription && (
+        <span id={descriptionId} className="sr-only" aria-hidden="true">
+          {[external && "(opens in a new window)", allyText].filter(Boolean).join(" ")}
+        </span>
+      )}
     </LinkComponent>
   )
 }

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

@@ -6,18 +6,16 @@ exports[`Download 1`] = `
   
 <span class="mx-icon mx-icon--download"></span>
 
-  <span>Download (PDF 12kb)</span>
-    
+  Download (PDF 12kb)  
 </a>
 "
 `;
 
 exports[`External 1`] = `
-"      
-<a href="#" class="mx-link--external" target="_blank" rel="noopener noreferrer">
+"                  
+<a href="#" class="mx-link--external" target="_blank" rel="noopener noreferrer" aria-label="Hyperlink (opens in a new window)">
   
-  <span>Hyperlink</span>
-  <span class="sr-only">(opens in a new window)</span>  
+  Hyperlink  
 </a>
 "
 `;
@@ -28,8 +26,7 @@ exports[`Icon Link 1`] = `
   
 <span class="mx-icon mx-icon--link"></span>
 
-  <span>Hyperlink</span>
-    
+  Hyperlink  
 </a>
 "
 `;
@@ -38,8 +35,7 @@ exports[`Link 1`] = `
 "
 <a href="#">
   
-  <span>Hyperlink</span>
-    
+  Hyperlink  
 </a>
 "
 `;
@@ -48,8 +44,7 @@ exports[`More 1`] = `
 "  
 <a href="#" class="mx-link--more">
   
-  <span>Hyperlink</span>
-    
+  Hyperlink  
 <span class="mx-icon mx-icon--arrow-right"></span>
 
 </a>

package/src/Atom/Link/__snapshots__/Link.stories.tsx.snap

@@ -1,6 +1,6 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`External 1`] = `"<a href="http://example.com" class="mx-link mx-link--external" target="_blank" rel="noopener noreferrer">Link<span class="sr-only">(opens in a new window)</span></a>"`;
+exports[`External 1`] = `"<a href="http://example.com" class="mx-link mx-link--external" aria-describedby="_r_1_" target="_blank" rel="noopener noreferrer">Link<span id="_r_1_" class="sr-only" aria-hidden="true">(opens in a new window)</span></a>"`;
 
 exports[`Link 1`] = `"<a href="http://example.com" class="mx-link">Link</a>"`;
 

package/src/Atom/Link/_links.css

@@ -1,3 +1,5 @@
+@import "../../Utility/_mixins.css";
+
 @layer design-system.defaults {
   a[href] {
     color: var(--link-colour, var(--colour-link));
@@ -10,6 +12,11 @@
       text-underline-offset: 0.2em;
       text-decoration-thickness: max(0.09em, 2px);
     }
+
+    /* system colour for any glyph painted inside a link */
+    @media (--forced-colors) {
+      --forced-colour: LinkText;
+    }
   }
 
   .mx-link--external {
@@ -27,6 +34,8 @@
       block-size: var(--spacing-s);
       inline-size: var(--spacing-s);
       background-color: currentcolor;
+
+      @add-mixin forced-colors-paint;
     }
   }
 

package/src/Atom/Link/link.twig

@@ -18,12 +18,18 @@
 {% if download %}
   {% set attributes = attributes.setAttribute('download', '') %}
 {% endif %}
+{% if iconOnly or external %}
+  {% set accessibleLabel = title %}
+  {% if external %}
+    {% set accessibleLabel = accessibleLabel ~ ' (opens in a new window)' %}
+  {% endif %}
+  {% set attributes = attributes.setAttribute('aria-label', accessibleLabel) %}
+{% endif %}
 
 {% if listItem %}<li>{% endif %}
 <a{{ attributes }}>
   {{ iconStart }}
-  <span{% if iconOnly %} class="sr-only"{% endif %}>{{ title }}</span>
-  {% if external %}<span class="sr-only">(opens in a new window)</span>{% endif %}
+  {% if not iconOnly %}{{ title }}{% endif %}
   {{ iconEnd }}
 </a>
 {% if listItem %}</li>{% endif %}

package/src/Atom/LinkedImage/linked-image.twig

@@ -1,9 +1,8 @@
-{% set attributes = attributes ?? create_attribute() %}
+{% set attributes = (attributes ?? create_attribute()).setAttribute('aria-label', title) %}
 <a href="{{ href }}" {{ attributes }}>
   {% if image.src is defined %}
     {% include '@mixtape/Atom/Image/image.twig' with image only %}
   {% else %}
     {{ image }}
   {% endif %}
-  <span class="sr-only">{{ title }}</span>
 </a>