srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/01.atoms/navigation/breadcrumb/CONSUMER-STYLING.md

@@ -19,10 +19,24 @@
 }
 ```
 
+---
+
 ## Text content — props, not CSS
 
 `items` and `separator` are props. There is no hardcoded copy to override in CSS.
 
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+---
+
 ## Notes
 
 - An item renders as a `NuxtLink` when it has a `to`, otherwise as `<span aria-current="page">` —
@@ -30,3 +44,4 @@
 - The separator (`aria-hidden="true"`) is only rendered between items, never after the last one.
 - `--breadcrumb-colour` is what `ServiceDetail` overrides internally (to `white` by default) so
   the breadcrumb reads over its hero image — see `ServiceDetail`'s `CONSUMER-STYLING.md`.
+

package/app/components/01.atoms/navigation/skip-links/CONSUMER-STYLING.md

@@ -25,7 +25,20 @@
 }
 ```
 
+---
+
 ## Links are prop-driven
 
 The set of skip links is provided via the `links` prop (`{ href, label }[]`), not slots — see the
 skill doc for the default value and localisation notes.
+
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+

package/app/components/01.atoms/navigation/tabs/CONSUMER-STYLING.md

@@ -35,6 +35,8 @@
 }
 ```
 
+---
+
 ## Colour tokens are flat values, not light-dark() pairs
 
 Every colour token above defaults to a single flat `--slate-*` value rather than a
@@ -48,6 +50,8 @@ own override in `light-dark()`:
 }
 ```
 
+---
+
 ## Tab-label text colour tracks the indicator behind it
 
 Hover and active can have different background colours (`--tabs-hover-indicator-colour` vs.
@@ -65,6 +69,8 @@ either indicator background, override its matching text-colour token to keep con
 }
 ```
 
+---
+
 ## Tabs spanned by a jump keep their normal styling
 
 When the active tab (or hover) jumps across several tabs at once (e.g. clicking tab 5 while tab 1
@@ -85,15 +91,30 @@ literally the same colour as the indicator sliding beneath it (invisible). If yo
 `--tabs-active-indicator-colour`, check it still differs enough from `--tabs-list-item-colour` (or
 override that too) to avoid the same collision recurring.
 
+---
+
 ## Indicator visibility is prop-driven, not tokens
 
 Whether the hover highlight, active highlight, and underline indicator render at all is controlled
 by the `trackHover`/`trackActive`/`trackIndicator` boolean props (all default `true`), since they
 also gate whether the underlying DOM nodes are created — not just their styling.
 
+---
+
 ## Movement/position values are private
 
 `--_x-active`, `--_x-hovered`, `--_width-active`, `--_width-hovered`, `--_y-active`, `--_y-hovered`,
 `--_y-height`, `--_y-width`, and `--_transition-duration` are computed at runtime from the tab
 elements' measured layout (`offsetLeft`/`offsetWidth`/etc. in `useTabs`) and aren't meaningful to
 override directly — use `transitionDuration` (a prop, in ms) to control indicator movement speed.
+
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+

package/app/components/01.atoms/page-row/CONSUMER-STYLING.md

@@ -12,9 +12,30 @@ or instance) without touching the component itself.
 | `--page-row-content-max-width` | `1064px` | Maximum width of the `content` column track |
 | `--page-row-inset-content-max-width` | `840px` | Maximum width of the `inset-content` column track |
 
+Private (not public API): `--_minimum-content-padding`,
+`--_content-max-width`, `--_inset-content-max-width` (resolved copies of the tokens above) and the
+computed tracks `--_full-track-min`, `--_full-track`, `--_popout-track`, `--_content-track`,
+`--_inset-content-track`.
+
+> Changed 2026-09-27: the computed tracks used to be unprefixed `--full`, `--popout`, `--content`
+> and `--inset-content`. Declared on every `.page-row`, they overwrote any consumer variable with
+> the same (very generic) name inside a page row. They are internal and now carry the `--_` prefix.
+
+---
+
+## State hooks
+
+| Hook | When |
+|---|---|
+| `.page-row.full`, `.popout`, `.content`, `.inset-content` | The `variant` prop (default `content`). Sets the row's own track when nested, and the default track for its direct non-PageRow children |
+| `[data-align="start"]`, `[data-align="end"]` | The `align` prop on a nested row: bleeds to the left or right edge instead of centring |
+
+Direct children of a `.page-row` are grid items placed on a named track (`full`, `popout`,
+`content`, `inset-content`). Place your own child elsewhere with e.g. `grid-column: popout`.
+
 ---
 
-## Global theming — app-level CSS file
+## Global theming
 
 Create `assets/styles/setup/07.components/page-row.css` in the consuming app and set tokens on
 `:root`. These values apply to every `PageRow` instance across the site.
@@ -31,7 +52,20 @@ Create `assets/styles/setup/07.components/page-row.css` in the consuming app and
 
 ---
 
-## Page-scoped overrides
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+**Caveat:** a nested `.page-row` re-declares `--_minimum-content-padding` as
+`var(--page-row-minimum-content-padding, 0px)`, so nested rows get no gutter by default. If you set
+`--page-row-minimum-content-padding` on an ancestor, nested rows inherit that value and pick up the
+gutter too. Reset it to `0px` on nested rows if that's not what you want.
+
+### Page or section
 
 Override track widths for a specific page by scoping tokens under the page wrapper. No `:deep()`
 is required (component styles are unscoped).
@@ -46,9 +80,7 @@ is required (component styles are unscoped).
 }
 ```
 
----
-
-## Per-instance overrides via inline style
+### One instance: inline style
 
 ```vue
 <PageRow
@@ -59,9 +91,7 @@ is required (component styles are unscoped).
 </PageRow>
 ```
 
----
-
-## Per-instance overrides via styleClassPassthrough
+### One instance: style-class-passthrough
 
 ```vue
 <PageRow variant="content" :style-class-passthrough="['narrow']">
@@ -80,6 +110,13 @@ is required (component styles are unscoped).
 
 ---
 
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `.page-row` element, alongside the variant
+class. Tokens set on a passthrough class land for that row and any rows nested in it.
+
+---
+
 ## Notes
 
 - Track widths are derived from the four tokens using `calc()` — changing one token shifts all
@@ -88,3 +125,4 @@ is required (component styles are unscoped).
   narrow screens; it also sets the outer `full` gutter minimum.
 - The component applies no padding, margin, or background — those are always set by the consuming
   app on the PageRow element or its children.
+

package/app/components/01.atoms/page-row/PageRow.vue

@@ -28,8 +28,13 @@ const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
 });
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 const { headingId, ariaLabelledby } = useAriaLabelledById(props.tag);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 </script>
 
 <style lang="css">
@@ -42,7 +47,6 @@ const { headingId, ariaLabelledby } = useAriaLabelledById(props.tag);
    */
   .page-row {
     --_minimum-content-padding: var(--page-row-minimum-content-padding, 1rem);
-    --_popout-max-width: var(--page-row-popout-max-width, 1400px);
     --_content-max-width: var(--page-row-content-max-width, 1064px);
     --_inset-content-max-width: var(--page-row-inset-content-max-width, 840px);
 
@@ -54,31 +58,31 @@ const { headingId, ariaLabelledby } = useAriaLabelledById(props.tag);
       max(0px, calc((var(--_content-max-width) + var(--_minimum-content-padding) * 2 - 100%) / 2))
     );
 
-    --full: minmax(var(--_full-track-min), 1fr);
-    --popout: minmax(0, calc((var(--_popout-max-width) - var(--_content-max-width)) * 0.5));
-    --content: clamp(
+    --_full-track: minmax(var(--_full-track-min), 1fr);
+    --_popout-track: minmax(0, calc((var(--page-row-popout-max-width, 1400px) - var(--_content-max-width)) * 0.5));
+    --_content-track: clamp(
       0px,
       calc((100% - var(--_minimum-content-padding) * 2 - var(--_inset-content-max-width)) * 0.5),
       calc((var(--_content-max-width) - var(--_inset-content-max-width)) * 0.5)
     );
-    --inset-content: min(var(--_inset-content-max-width), 100% - var(--_minimum-content-padding) * 2);
+    --_inset-content-track: min(var(--_inset-content-max-width), 100% - var(--_minimum-content-padding) * 2);
 
     display: grid;
     grid-template-columns:
       [full-start]
-      var(--full)
+      var(--_full-track)
       [popout-start]
-      var(--popout)
+      var(--_popout-track)
       [content-start]
-      var(--content)
+      var(--_content-track)
       [inset-content-start]
-      var(--inset-content)
+      var(--_inset-content-track)
       [inset-content-end]
-      var(--content)
+      var(--_content-track)
       [content-end]
-      var(--popout)
+      var(--_popout-track)
       [popout-end]
-      var(--full)
+      var(--_full-track)
       [full-end];
 
     container-type: inline-size;

package/app/components/01.atoms/page-row/stories/PageRow.stories.ts

@@ -147,6 +147,8 @@ const NestingTemplate: StoryFn = () => ({
 
 export const NestingPattern = NestingTemplate.bind({});
 NestingPattern.parameters = {
+  // Fixed showcase: hardcoded values, so Controls would do nothing here.
+  controls: { disable: true },
   docs: {
     description: {
       story:
@@ -199,6 +201,8 @@ const ComparisonTemplate: StoryFn = () => ({
 
 export const WidthComparison = ComparisonTemplate.bind({});
 WidthComparison.parameters = {
+  // Fixed showcase: hardcoded values, so Controls would do nothing here.
+  controls: { disable: true },
   docs: {
     description: {
       story: "Side-by-side comparison of all four main track widths.",
@@ -260,6 +264,8 @@ const AlignTemplate: StoryFn = () => ({
 
 export const Alignment = AlignTemplate.bind({});
 Alignment.parameters = {
+  // Fixed showcase: hardcoded values, so Controls would do nothing here.
+  controls: { disable: true },
   docs: {
     description: {
       story:
@@ -302,6 +308,8 @@ const A11yTemplate: StoryFn = () => ({
 
 export const AriaLabelledBy = A11yTemplate.bind({});
 AriaLabelledBy.parameters = {
+  // Fixed showcase: hardcoded values, so Controls would do nothing here.
+  controls: { disable: true },
   docs: {
     description: {
       story:

package/app/components/01.atoms/page-row/tests/PageRow.spec.ts

@@ -3,15 +3,6 @@ import { h } from "vue";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import PageRow from "../PageRow.vue";
 
-const mockElementClasses = { value: "" };
-const mockUseStyleClassPassthrough = vi.fn(() => ({
-  elementClasses: mockElementClasses,
-}));
-
-vi.mock("#imports", () => ({
-  useStyleClassPassthrough: mockUseStyleClassPassthrough,
-}));
-
 describe("PageRow", () => {
   let wrapper: Awaited<ReturnType<typeof mountSuspended>>;
 
@@ -28,7 +19,6 @@ describe("PageRow", () => {
 
   beforeEach(() => {
     vi.clearAllMocks();
-    mockElementClasses.value = "";
   });
 
   afterEach(() => {
@@ -95,7 +85,6 @@ describe("PageRow", () => {
 
   describe("Props — styleClassPassthrough", () => {
     it("forwards string class via elementClasses", async () => {
-      mockElementClasses.value = "custom-class";
       await createWrapper({ styleClassPassthrough: "custom-class" });
       expect(wrapper.classes()).toContain("custom-class");
     });
@@ -105,6 +94,13 @@ describe("PageRow", () => {
       expect(wrapper.classes()).toContain("class-a");
       expect(wrapper.classes()).toContain("class-b");
     });
+
+    it("updates classes when styleClassPassthrough changes after mount", async () => {
+      await createWrapper({ styleClassPassthrough: ["original"] });
+      await wrapper.setProps({ styleClassPassthrough: ["updated"] });
+      expect(wrapper.classes()).not.toContain("original");
+      expect(wrapper.classes()).toContain("updated");
+    });
   });
 
   describe("Props — align", () => {

package/app/components/01.atoms/pop-over/CONSUMER-STYLING.md

@@ -40,6 +40,18 @@ Or scope to a single instance via `styleClassPassthrough`:
 <PopOver style-class-passthrough="promo-pop-over">...</PopOver>
 ```
 
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+---
+
 ## Notes
 
 - Built on the native Popover API (`popover`/`popovertarget`) and CSS anchor-positioning
@@ -52,3 +64,4 @@ Or scope to a single instance via `styleClassPassthrough`:
   semantics with arrow-key navigation), `PopOver` is a generic disclosure: both `trigger` and
   `content` slots are entirely consumer-supplied, and it always renders its own visible close
   button rather than relying on click-outside/Escape alone.
+

package/app/components/01.atoms/qr-code/CONSUMER-STYLING.md

@@ -0,0 +1,48 @@
+# DisplayQrCode — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--display-qr-code-size` | the `size` prop (`256px`) | Width of the code; height follows via `aspect-ratio: 1 / 1` |
+
+Module colours are props, not tokens: `black-color` (default `currentColor`) and `white-color`
+(default `transparent`). They're written into the SVG by `nuxt-qrcode`. Because the dark modules
+default to `currentColor`, setting `color` on the element or an ancestor recolours them.
+
+> Changed 2026-09-27: `--display-qr-code-size` is new. When set, it takes precedence over the
+> `size` prop, so a layout can resize codes without touching every instance.
+
+No private `--_` tokens.
+
+---
+
+## State hooks
+
+The root is the `nuxt-qrcode` SVG with class `.display-qr-code`, `role="img"` and an
+`aria-label` (the `aria-label` prop, default `"QR code"`). There are no state classes.
+
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+### Page or section
+
+```css
+.my-page {
+  --display-qr-code-size: 18rem;
+  color: var(--brand-primary); /* dark modules, when black-color is left at currentColor */
+}
+```
+
+---
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root SVG. Reactive after mount.

package/app/components/01.atoms/qr-code/DisplayQrCode.vue

@@ -6,6 +6,8 @@
     :radius
     :black-color
     :white-color
+    role="img"
+    :aria-label="ariaLabel"
     :class="[elementClasses]"
   />
 </template>
@@ -20,6 +22,7 @@ interface Props {
   blackColor?: string;
   whiteColor?: string;
   size?: string;
+  ariaLabel?: string;
   styleClassPassthrough?: string | string[];
 }
 
@@ -29,6 +32,7 @@ const props = withDefaults(defineProps<Props>(), {
   blackColor: "currentColor",
   whiteColor: "transparent",
   size: "256px",
+  ariaLabel: "QR code",
   styleClassPassthrough: () => [],
 });
 
@@ -44,7 +48,7 @@ watch(
 @layer components {
   .display-qr-code {
     aspect-ratio: 1 / 1;
-    width: v-bind(size);
+    width: var(--display-qr-code-size, v-bind(size));
   }
 }
 </style>

package/app/components/01.atoms/qr-code/stories/DisplayQrCode.stories.ts

@@ -31,6 +31,11 @@ const meta: Meta<typeof DisplayQrCodeComponent> = {
       description: "Color of the QR code background",
       table: { category: "Appearance" },
     },
+    ariaLabel: {
+      control: { type: "text" },
+      description: "Accessible name for the QR image (override for a more specific or translated label)",
+      table: { category: "Accessibility" },
+    },
     variant: { table: { disable: true } },
     styleClassPassthrough: { table: { disable: true } },
   },
@@ -40,6 +45,7 @@ const meta: Meta<typeof DisplayQrCodeComponent> = {
     radius: 0,
     blackColor: "#000000",
     whiteColor: "transparent",
+    ariaLabel: "QR code",
     styleClassPassthrough: [],
   },
 };
@@ -52,6 +58,7 @@ interface QrStoryArgs {
   radius: number;
   blackColor: string;
   whiteColor: string;
+  ariaLabel: string;
   styleClassPassthrough: string[];
 }
 
@@ -68,12 +75,13 @@ const DisplayTemplate: StoryFn<QrStoryArgs> = (args, { parameters }) => ({
   template: `
     <div style="padding: 40px; display: flex; align-items: center; justify-content: center; background: #f5f5f5; border-radius: 8px;">
       <DisplayQrCodeComponent
-        :qrValue="args.qrValue"
+        :qr-value="args.qrValue"
         :variant="variant"
         :radius="args.radius"
-        :blackColor="args.blackColor"
-        :whiteColor="args.whiteColor"
+        :black-color="args.blackColor"
+        :white-color="args.whiteColor"
         :size="args.size"
+        :aria-label="args.ariaLabel"
         :style-class-passthrough="args.styleClassPassthrough"
       />
     </div>

package/app/components/01.atoms/qr-code/tests/DisplayQrCode.spec.ts

@@ -137,3 +137,18 @@ describe("DisplayQrCode", () => {
     expect(wrapper.classes()).toContain("updated");
   });
 });
+
+describe("DisplayQrCode accessibility", () => {
+  it("exposes the QR code as an image with a default accessible name", async () => {
+    const wrapper = await mountSuspended(DisplayQrCode, { props: { qrValue: "https://example.com" } });
+    expect(wrapper.attributes("role")).toBe("img");
+    expect(wrapper.attributes("aria-label")).toBe("QR code");
+  });
+
+  it("uses the ariaLabel prop as the accessible name", async () => {
+    const wrapper = await mountSuspended(DisplayQrCode, {
+      props: { qrValue: "https://example.com", ariaLabel: "Scan to open our booking page" },
+    });
+    expect(wrapper.attributes("aria-label")).toBe("Scan to open our booking page");
+  });
+});

package/app/components/01.atoms/text-block/CONSUMER-STYLING.md

@@ -0,0 +1,49 @@
+# TextBlock — Consumer Styling Guide
+
+`TextBlock` is a plain wrapper whose only styling is vertical padding. Both edges default to the
+global fluid spacing token `--fluid-space-48-96` (`clamp(3rem, …, 6rem)`, i.e. 30px–60px).
+
+## Tokens
+
+| Token | Default | Controls |
+|-------|---------|----------|
+| `--text-block-padding-block-start` | `var(--fluid-space-48-96)` | `padding-block-start` |
+| `--text-block-padding-block-end` | `var(--fluid-space-48-96)` | `padding-block-end` |
+
+```css
+/* Tighter lead block on one page */
+.price-list-page {
+  --text-block-padding-block-start: var(--fluid-space-24-48);
+  --text-block-padding-block-end: 0;
+}
+```
+
+You don't need to redeclare the default padding in your own CSS to get it; the component ships it.
+
+---
+
+## Local overrides
+
+Set the tokens above on an element you own (a page or section class, or a class added with
+`:style-class-passthrough`): they inherit down into the component. Keep the block **unlayered** (no
+`@layer` wrapper) so it beats the library's `@layer components`. If your own file uses
+`<style scoped>`, tokens set on your element still work, but selectors that reach inside the component need
+`:deep()`. Patterns and examples: `.claude/skills/component-local-style-override.md`.
+
+### One instance
+
+Add your own class through `styleClassPassthrough` and set the tokens on it:
+
+```vue
+<TextBlock :style-class-passthrough="['page-lead']">…</TextBlock>
+```
+
+```css
+.page-lead {
+  --text-block-padding-block-end: 0;
+}
+```
+
+`.text-block` is declared inside `@layer components`, so any unlayered consumer rule on the class
+itself also wins, but prefer the tokens so the fallback chain stays intact.
+

package/app/components/01.atoms/text-block/TextBlock.vue

@@ -1,6 +1,6 @@
 <template>
-  <component :is="tag" class="text-block" :class="[elementClasses]">
-    <slot name="default"></slot>
+  <component :is="tag" class="text-block" :class="[elementClasses]" :aria-labelledby="ariaLabelledby">
+    <slot name="default" :heading-id="headingId"></slot>
   </component>
 </template>
 
@@ -14,14 +14,22 @@ const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
 });
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+const { headingId, ariaLabelledby } = useAriaLabelledById(() => props.tag);
+
+watch(
+  () => props.styleClassPassthrough,
+  (newVal) => {
+    resetElementClasses(newVal ?? []);
+  }
+);
 </script>
 
 <style lang="css">
 @layer components {
   .text-block {
-    padding-block-start: var(--fluid-space-48-96);
-    padding-block-end: var(--fluid-space-48-96);
+    padding-block-start: var(--text-block-padding-block-start, var(--fluid-space-48-96));
+    padding-block-end: var(--text-block-padding-block-end, var(--fluid-space-48-96));
   }
 }
 </style>