srcdev-nuxt-components 9.4.11 → 9.5.0

package/app/components/01.atoms/text-block/stories/TextBlock.stories.ts

@@ -0,0 +1,84 @@
+import TextBlock from "../TextBlock.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof TextBlock> = {
+  title: "Atoms/Text Block",
+  component: TextBlock,
+  argTypes: {
+    tag: {
+      control: { type: "select" },
+      options: ["div", "section", "article", "main"],
+      description: "Root element. section/article get aria-labelledby pointing at the heading-id slot prop",
+    },
+    styleClassPassthrough: {
+      control: "object",
+      description: "Additional classes applied to the root element",
+    },
+  },
+  args: {
+    tag: "div",
+    styleClassPassthrough: [],
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Vertical-rhythm wrapper for a block of text (typically a page lead: eyebrow, hero heading, intro copy). Its only styling is fluid block padding, overridable via --text-block-padding-block-start/-end. The dashed outline in these stories shows the padding and is not part of the component.",
+      },
+    },
+  },
+  decorators: [
+    () => ({
+      template: `<div style="outline: 1px dashed currentColor; outline-offset: -1px;"><story /></div>`,
+    }),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof TextBlock>;
+
+export const Default: Story = {
+  render: (args) => ({
+    components: { TextBlock },
+    setup() {
+      return { args };
+    },
+    template: `
+      <TextBlock v-bind="args" v-slot="{ headingId }">
+        <h2 :id="headingId" class="page-heading-2">Our services</h2>
+        <p>Everything we offer, with prices and appointment lengths.</p>
+      </TextBlock>
+    `,
+  }),
+};
+
+export const AsLabelledSection: Story = {
+  name: "As a labelled section",
+  args: { tag: "section" },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "With tag=section the root gets aria-labelledby. Bind the heading-id slot prop to the heading's id so the landmark has an accessible name; a dev-mode console warning fires if you forget.",
+      },
+    },
+  },
+  render: Default.render,
+};
+
+export const CustomPadding: Story = {
+  name: "Custom padding tokens",
+  render: (args) => ({
+    components: { TextBlock },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div style="--text-block-padding-block-start: var(--fluid-space-8-16); --text-block-padding-block-end: 0;">
+        <TextBlock v-bind="args">
+          <p>Tight top padding, none at the bottom, set via the public tokens on a parent.</p>
+        </TextBlock>
+      </div>
+    `,
+  }),
+};

package/app/components/01.atoms/text-block/tests/TextBlock.spec.ts

@@ -0,0 +1,78 @@
+import { describe, it, expect, vi } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import { nextTick } from "vue";
+import TextBlock from "../TextBlock.vue";
+
+describe("TextBlock", () => {
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(TextBlock, { slots: { default: "Content" } });
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders correct HTML structure with default props", async () => {
+    const wrapper = await mountSuspended(TextBlock, { slots: { default: "<p>Lead copy</p>" } });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  it("defaults to a div with the text-block class", async () => {
+    const wrapper = await mountSuspended(TextBlock);
+    expect(wrapper.element.tagName).toBe("DIV");
+    expect(wrapper.classes()).toContain("text-block");
+  });
+
+  it.each(["section", "article", "main"] as const)("renders a <%s> when tag is set", async (tag) => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const wrapper = await mountSuspended(TextBlock, { props: { tag } });
+    expect(wrapper.element.tagName).toBe(tag.toUpperCase());
+    warn.mockRestore();
+  });
+
+  it("renders slot content", async () => {
+    const wrapper = await mountSuspended(TextBlock, { slots: { default: "<p class='lead'>Hello</p>" } });
+    expect(wrapper.find(".lead").text()).toBe("Hello");
+  });
+
+  describe("aria-labelledby", () => {
+    it("is not set on a div", async () => {
+      const wrapper = await mountSuspended(TextBlock);
+      expect(wrapper.attributes("aria-labelledby")).toBeUndefined();
+    });
+
+    it("is not set on main (a single main landmark needs no name)", async () => {
+      const wrapper = await mountSuspended(TextBlock, { props: { tag: "main" } });
+      expect(wrapper.attributes("aria-labelledby")).toBeUndefined();
+    });
+
+    it.each(["section", "article"] as const)("points a <%s> at the heading bound via the heading-id slot prop", async (tag) => {
+      const wrapper = await mountSuspended(TextBlock, {
+        props: { tag },
+        slots: {
+          default: `<template #default="{ headingId }"><h2 :id="headingId">Title</h2></template>`,
+        },
+      });
+      const labelledby = wrapper.attributes("aria-labelledby");
+      expect(labelledby).toBeTruthy();
+      expect(wrapper.find("h2").attributes("id")).toBe(labelledby);
+    });
+  });
+
+  describe("styleClassPassthrough", () => {
+    it("applies passthrough classes", async () => {
+      const wrapper = await mountSuspended(TextBlock, { props: { styleClassPassthrough: ["page-lead", "mbe-20"] } });
+      expect(wrapper.classes()).toEqual(expect.arrayContaining(["text-block", "page-lead", "mbe-20"]));
+    });
+
+    it("accepts a single string", async () => {
+      const wrapper = await mountSuspended(TextBlock, { props: { styleClassPassthrough: "page-lead" } });
+      expect(wrapper.classes()).toContain("page-lead");
+    });
+
+    it("updates classes when the prop changes", async () => {
+      const wrapper = await mountSuspended(TextBlock, { props: { styleClassPassthrough: ["first"] } });
+      await wrapper.setProps({ styleClassPassthrough: ["second"] });
+      await nextTick();
+      expect(wrapper.classes()).toContain("second");
+      expect(wrapper.classes()).not.toContain("first");
+    });
+  });
+});

package/app/components/01.atoms/text-block/tests/__snapshots__/TextBlock.spec.ts.snap

@@ -0,0 +1,7 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`TextBlock > renders correct HTML structure with default props 1`] = `
+"<div class="text-block">
+  <p>Lead copy</p>
+</div>"
+`;

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

@@ -0,0 +1,56 @@
+# EyebrowText — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--eyebrow-text-bg-img` | `linear-gradient(135deg, #c2a770, #b4747e, #d1bd94)` | Fill of the text (`background-clip: text` over `color: transparent`) |
+| `--eyebrow-text-large` | `1.4rem` | Font size for `font-size="large"` |
+| `--eyebrow-text-medium` | `1.2rem` | Font size for `font-size="medium"` (default) |
+| `--eyebrow-text-small` | `1rem` | Font size for `font-size="small"` |
+
+The library theme also sets all four on `:root` (`03.theming/_default.css` and
+`05.typography/01.tokens/_reponsive-font-sizes.css`) with the same values.
+
+> Changed 2026-09-27: the component now carries those values as fallbacks too. Before, an app that
+> replaced the library theme files without defining `--eyebrow-text-bg-img` got invisible text,
+> since the colour is `transparent`.
+
+No private `--_` tokens.
+
+---
+
+## State hooks
+
+| Class | When |
+|---|---|
+| `.eyebrow-text.large`, `.medium`, `.small` | The `font-size` prop |
+
+---
+
+## Global theming
+
+```css
+:where(html) {
+  --eyebrow-text-bg-img: linear-gradient(135deg, var(--brand-primary), var(--brand-accent));
+}
+```
+
+For a plain solid colour, use a single-colour gradient:
+`linear-gradient(var(--brand-primary), var(--brand-primary))`.
+
+---
+
+## 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`.
+
+---
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root `.eyebrow-text` element. Reactive after mount.

package/app/components/01.atoms/text-blocks/eyebrow-text/EyebrowText.vue

@@ -17,7 +17,12 @@ const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
 });
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 </script>
 
 <style lang="css">
@@ -25,20 +30,20 @@ const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough)
   .eyebrow-text {
     text-transform: uppercase;
     background-clip: text;
-    background-image: var(--eyebrow-text-bg-img);
+    background-image: var(--eyebrow-text-bg-img, linear-gradient(135deg, #c2a770, #b4747e, #d1bd94));
     font-style: italic;
     color: transparent;
 
     &.large {
-      font-size: var(--eyebrow-text-large);
+      font-size: var(--eyebrow-text-large, 1.4rem);
     }
 
     &.medium {
-      font-size: var(--eyebrow-text-medium);
+      font-size: var(--eyebrow-text-medium, 1.2rem);
     }
 
     &.small {
-      font-size: var(--eyebrow-text-small);
+      font-size: var(--eyebrow-text-small, 1rem);
     }
   }
 }

package/app/components/01.atoms/text-blocks/eyebrow-text/tests/EyebrowText.spec.ts

@@ -194,3 +194,14 @@ describe("EyebrowText", () => {
     expect(wrapper.text()).toBe("Limited Edition");
   });
 });
+
+describe("EyebrowText styleClassPassthrough reactivity", () => {
+  it("updates classes when styleClassPassthrough changes after mount", async () => {
+    const wrapper = await mountSuspended(EyebrowText, {
+      props: { textContent: "Eyebrow", styleClassPassthrough: ["original"] },
+    });
+    await wrapper.setProps({ styleClassPassthrough: ["updated"] });
+    expect(wrapper.classes()).not.toContain("original");
+    expect(wrapper.classes()).toContain("updated");
+  });
+});

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

@@ -27,7 +27,21 @@ own CSS rather than expecting a level to come with baked-in margin:
 }
 ```
 
-## Overriding one instance
+---
+
+## Local overrides
+
+There are no public tokens, so override the classes above with direct properties, scoped to an
+element you own (a page or section class, or a class added with `:style-class-passthrough`). Keep
+the block **unlayered** (no `@layer` wrapper) so it beats the library's `@layer components`. If your
+own file uses `<style scoped>`, selectors that reach inside the component need `:deep()`. Patterns
+and examples: `.claude/skills/component-local-style-override.md`.
+
+**Caveat:** size comes from the global `--step-*` type-scale tokens behind `.page-heading-*`.
+Overriding a `--step-*` token on your own element changes every `page-heading-*` inside it, not just
+this component's.
+
+### One instance
 
 Use `styleClassPassthrough` to add your own class and override `font-size`/`font-weight`/etc. for
 a single `HeaderBlock` instance without touching the shared `.page-heading-*` utility classes:
@@ -41,3 +55,4 @@ a single `HeaderBlock` instance without touching the shared `.page-heading-*` ut
   font-size: 6rem;
 }
 ```
+

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

@@ -0,0 +1,74 @@
+# HeroText — Consumer Styling Guide
+
+## Public token API
+
+### Type scale
+
+| Token | Default | Used when |
+|---|---|---|
+| `--hero-text-display` | `clamp(4.8rem, 4vw + 2rem, 9.6rem)` | `font-size="display"` |
+| `--hero-text-title` | `clamp(3.6rem, 4vw + 2rem, 4.8rem)` | `font-size="title"` (default) |
+| `--hero-text-heading` | `clamp(2.8rem, 4vw + 2rem, 3rem)` | `font-size="heading"` |
+| `--hero-text-subheading` | `2.4rem` | `font-size="subheading"` |
+| `--hero-text-label` | `1.75rem` | `font-size="label"` |
+
+### Appearance
+
+| Token | Default | Controls |
+|---|---|---|
+| `--hero-text-font-family` | `"Playfair Display"` | Font family of the whole heading |
+| `--hero-text-margin` | `0` | Margin on the root |
+| `--hero-text-horizontal-gap` | `0.5ch` | Gap between segments, `axis="horizontal"` |
+| `--hero-text-vertical-gap` | `0.4em` | Gap between segments, `axis="vertical"` |
+| `--hero-text-bg-img` | `linear-gradient(135deg, #c2a770, #b4747e, #d1bd94)` | Fill of `accent` segments (`background-clip: text`) |
+| `--hero-text-accent-offset` | `0.2em` | Extra bottom padding (and matching negative margin) on `accent` segments so descenders aren't clipped |
+| `--hero-text-icon-colour` | `var(--colour-text-accent)` | Icon colour |
+
+The library theme sets the type scale and `--hero-text-bg-img` on `:root` with the same values.
+
+> Changed 2026-09-27: the component now carries those values as fallbacks (an app replacing the
+> theme files got invisible accent text). `--hero-text-icon-colour` is new. The subheading icon is
+> now sized with `font-size: 0.75em`; it used `width ... !important`, which fought
+> `@nuxt/icon`'s own sizing.
+
+Private (not public API): `--_hero-text-accent-offset`.
+
+---
+
+## State hooks
+
+| Hook | When |
+|---|---|
+| `.hero-text.display`, `.title`, `.heading`, `.subheading`, `.label` | The `font-size` prop |
+| `.axis-horizontal`, `.axis-vertical` | The `axis` prop (vertical is a flex column) |
+| `.accent` | A segment with `styleClass: "accent"` |
+
+Inner elements: `.hero-text__icon`, and one `<span class="text-block-{n}">` per segment (plus its
+own `styleClass`).
+
+---
+
+## Global theming
+
+```css
+:where(html) {
+  --hero-text-font-family: var(--font-family-display);
+  --hero-text-bg-img: linear-gradient(135deg, var(--brand-primary), var(--brand-accent));
+}
+```
+
+---
+
+## 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`.
+
+---
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root heading element. Reactive after mount.

package/app/components/01.atoms/text-blocks/hero-text/HeroText.vue

@@ -31,7 +31,12 @@ const componentClasses = computed(() => {
   return [props.fontSize, `axis-${props.axis}`];
 });
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 
 const normalisedContent = computed(() =>
   props.textContent.map((item, index) => ({
@@ -65,38 +70,38 @@ const normalisedContent = computed(() =>
 
     .hero-text__icon {
       aspect-ratio: 1;
-      color: var(--colour-text-accent);
+      color: var(--hero-text-icon-colour, var(--colour-text-accent));
     }
 
     &.display {
-      font-size: var(--hero-text-display);
+      font-size: var(--hero-text-display, clamp(4.8rem, 4vw + 2rem, 9.6rem));
     }
 
     &.title {
-      font-size: var(--hero-text-title);
+      font-size: var(--hero-text-title, clamp(3.6rem, 4vw + 2rem, 4.8rem));
     }
 
     &.heading {
-      font-size: var(--hero-text-heading);
+      font-size: var(--hero-text-heading, clamp(2.8rem, 4vw + 2rem, 3rem));
     }
 
     &.subheading {
-      font-size: var(--hero-text-subheading);
+      font-size: var(--hero-text-subheading, 2.4rem);
 
       .hero-text__icon {
-        width: calc(var(--hero-text-subheading) * 0.75) !important;
+        font-size: 0.75em;
       }
     }
 
     &.label {
-      font-size: var(--hero-text-label);
+      font-size: var(--hero-text-label, 1.75rem);
     }
 
     .accent {
       --_hero-text-accent-offset: var(--hero-text-accent-offset, 0.2em);
 
       background-clip: text;
-      background-image: var(--hero-text-bg-img);
+      background-image: var(--hero-text-bg-img, linear-gradient(135deg, #c2a770, #b4747e, #d1bd94));
       font-style: italic;
       color: transparent;
       padding-bottom: var(--_hero-text-accent-offset);

package/app/components/01.atoms/text-blocks/hero-text/tests/HeroText.spec.ts

@@ -146,3 +146,14 @@ describe("HeroText", () => {
     expect(wrapper.find(".hero-text__icon").exists()).toBe(false);
   });
 });
+
+describe("HeroText styleClassPassthrough reactivity", () => {
+  it("updates classes when styleClassPassthrough changes after mount", async () => {
+    const wrapper = await mountSuspended(HeroText, {
+      props: { tag: "h2", textContent: [{ text: "Hero" }], styleClassPassthrough: ["original"] },
+    });
+    await wrapper.setProps({ styleClassPassthrough: ["updated"] });
+    expect(wrapper.classes()).not.toContain("original");
+    expect(wrapper.classes()).toContain("updated");
+  });
+});

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

@@ -0,0 +1,45 @@
+# LinkText — Consumer Styling Guide
+
+## Public token API
+
+| Token | Default | Controls |
+|---|---|---|
+| `--link-text-colour` | `currentColor` | Text and icon colour; also the focus outline colour |
+| `--link-text-colour-hover` | `--link-text-colour` | Colour on hover/focus |
+| `--link-text-decoration` | `underline` | Text decoration at rest |
+| `--link-text-decoration-hover` | `none` | Text decoration on hover/focus |
+| `--link-text-underline-offset` | `0.2em` | Underline offset |
+| `--link-text-font-size` | `inherit` | Font size |
+| `--link-text-gap` | `0.4em` | Gap between icon slots and label |
+
+Transitions read the library-wide `--control-transition-duration` (`200ms`) and
+`--control-transition-ease` (`ease`).
+
+> Changed 2026-09-27: `--link-text-colour-hover` now falls back to `--link-text-colour`. It fell
+> back to `currentColor`, which in a `color` declaration means the parent's colour, so a link with
+> a custom colour switched to the surrounding text colour on hover.
+
+Private (not public API): `--_colour` (the resolved resting colour).
+
+---
+
+## State hooks
+
+Inner classes: `.link-text__label`, `.link-text__icon` with `.link-text__icon--left` /
+`.link-text__icon--right` (only rendered when the `left`/`right` slot is used).
+
+---
+
+## 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`.
+
+---
+
+## Class passthrough
+
+`style-class-passthrough` adds classes to the root link element. Reactive after mount.

package/app/components/01.atoms/text-blocks/link-text/LinkText.vue

@@ -1,10 +1,10 @@
 <template>
   <NuxtLink class="link-text" :class="elementClasses" :to="to" :external="external" :target="target">
-    <span v-if="hasLeftSlot" class="link-text__icon link-text__icon--left">
+    <span v-if="hasLeftSlot()" class="link-text__icon link-text__icon--left">
       <slot name="left"></slot>
     </span>
     <span class="link-text__label">{{ linkText }}</span>
-    <span v-if="hasRightSlot" class="link-text__icon link-text__icon--right">
+    <span v-if="hasRightSlot()" class="link-text__icon link-text__icon--right">
       <slot name="right"></slot>
     </span>
   </NuxtLink>
@@ -26,10 +26,15 @@ const props = withDefaults(defineProps<Props>(), {
 });
 
 const slots = useSlots();
-const hasLeftSlot = computed(() => Boolean(slots.left));
-const hasRightSlot = computed(() => Boolean(slots.right));
+const hasLeftSlot = () => Boolean(slots.left);
+const hasRightSlot = () => Boolean(slots.right);
 
-const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  () => resetElementClasses(props.styleClassPassthrough)
+);
 </script>
 
 <style lang="css">
@@ -38,8 +43,10 @@ const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough)
     display: inline-grid;
     grid-auto-flow: column;
     align-items: center;
+    --_colour: var(--link-text-colour, currentColor);
+
     gap: var(--link-text-gap, 0.4em);
-    color: var(--link-text-colour, currentColor);
+    color: var(--_colour);
     font-size: var(--link-text-font-size, inherit);
     text-decoration: var(--link-text-decoration, underline);
     text-underline-offset: var(--link-text-underline-offset, 0.2em);
@@ -47,12 +54,12 @@ const { elementClasses } = useStyleClassPassthrough(props.styleClassPassthrough)
 
     &:hover,
     &:focus-visible {
-      color: var(--link-text-colour-hover, currentColor);
+      color: var(--link-text-colour-hover, var(--_colour));
       text-decoration: var(--link-text-decoration-hover, none);
     }
 
     &:focus-visible {
-      outline: 2px solid var(--link-text-colour, currentColor);
+      outline: 2px solid var(--_colour);
       outline-offset: 3px;
       border-radius: 2px;
     }

package/app/components/01.atoms/text-blocks/link-text/tests/LinkText.spec.ts

@@ -166,3 +166,14 @@ describe("LinkText", () => {
     expect(children[2].classList.contains("link-text__icon--right")).toBe(true);
   });
 });
+
+describe("LinkText styleClassPassthrough reactivity", () => {
+  it("updates classes when styleClassPassthrough changes after mount", async () => {
+    const wrapper = await mountSuspended(LinkText, {
+      props: { to: "/about", linkText: "About", styleClassPassthrough: ["original"] },
+    });
+    await wrapper.setProps({ styleClassPassthrough: ["updated"] });
+    expect(wrapper.classes()).not.toContain("original");
+    expect(wrapper.classes()).toContain("updated");
+  });
+});

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

@@ -32,8 +32,21 @@ Or scope to a single instance via `styleClassPassthrough`:
 }
 ```
 
+---
+
 ## Strength props apply at most one class each
 
 `borderStrength`, `shadowStrength` and `innerShadowStrength` are independent — a value of `0`
 (the default) applies no class for that decoration. All three can be combined on the same
 instance (e.g. a border and a shadow together).
+
+---
+
+## 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`.
+