srcdev-nuxt-components 9.6.13 → 9.6.14

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

@@ -1,5 +1,6 @@
 import HeroText from "../HeroText.vue";
 import type { Meta, StoryObj } from "@nuxtjs/storybook";
+import type { TextConfig } from "~/types/components";
 
 const meta: Meta<typeof HeroText> = {
   title: "Atoms/Text Blocks/Hero Text",
@@ -8,46 +9,40 @@ const meta: Meta<typeof HeroText> = {
     tag: {
       control: { type: "select" },
       options: ["h1", "h2", "h3", "h4", "h5", "h6"],
-      description: "HTML tag for the element",
-      defaultValue: "h1",
+      description: "Heading element to render.",
+      table: { category: "Basic" },
     },
     axis: {
       control: { type: "select" },
       options: ["horizontal", "vertical"],
-      description: "Layout axis",
-      defaultValue: "horizontal",
+      description: "`horizontal` flows the segments as one line of text; `vertical` stacks them in a column. Set as `data-axis`.",
+      table: { category: "Basic" },
     },
     fontSize: {
       control: { type: "select" },
       options: ["display", "title", "heading", "subheading", "label"],
-      description: "Semantic font size",
-      defaultValue: "title",
+      description: "Size step, set as `data-font-size` and sized by `--hero-text-{size}`.",
+      table: { category: "Basic" },
     },
     textContent: {
       control: "object",
-      description: "Array of text segments with styleClass",
-      defaultValue: [
-        { text: "Designing", styleClass: "normal" },
-        { text: "Artistry", styleClass: "accent" },
-        { text: "at Home", styleClass: "normal" },
-      ],
+      description:
+        "Segments: `{ text, styleClass?: \"normal\" | \"accent\" }`. Text is trimmed, a space joins segments, and blank segments are dropped.",
+      table: { category: "Content" },
     },
     icon: {
       control: { type: "select" },
       options: [undefined, "lucide:sparkles"],
-      description: "Icon name",
+      description: "Iconify name for a decorative icon before the text.",
+      table: { category: "Basic" },
     },
-    styleClassPassthrough: {
-      control: "object",
-      description: "Additional classes",
-      defaultValue: [],
+    id: {
+      control: "text",
+      description: "Rendered as `id`, for a section's `aria-labelledby`.",
+      table: { category: "Accessibility" },
     },
+    styleClassPassthrough: { table: { disable: true } },
   },
-};
-
-export default meta;
-type Story = StoryObj<typeof HeroText>;
-export const Default: Story = {
   args: {
     tag: "h1",
     axis: "horizontal",
@@ -58,8 +53,75 @@ export const Default: Story = {
       { text: "at Home", styleClass: "normal" },
     ],
     icon: "lucide:sparkles",
-    styleClassPassthrough: [],
   },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "A heading built from text segments (`textContent`), each `normal` or `accent` (italic, filled with the `--hero-text-bg-img` gradient). `fontSize` picks one of five size steps, `axis` flows the segments inline or stacks them, and `icon` adds a decorative icon. Rendered as the title in `ServicesCard`, `ServiceSummary`, `ServiceDetail` and as `PriceList`'s group headings.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof HeroText>;
+
+// Links in the canvas open in the Storybook manager (target="_top"), not inside the preview iframe.
+const storyNoteStyle = "margin: 0 0 1.6rem; font-size: 1.4rem;";
+const parentNote = `
+  <p style="${storyNoteStyle}">
+    In use: the title in
+    <a href="/?path=/story/organisms-services-services-card--config-overrides" target="_top">ServicesCard</a>
+    (size and tag set through <code>heroConfig</code>),
+    <a href="/?path=/story/organisms-services-service-summary--default" target="_top">ServiceSummary</a>,
+    <a href="/?path=/story/organisms-services-service-detail--default" target="_top">ServiceDetail</a>, and the group headings in
+    <a href="/?path=/story/molecules-pricelist--default" target="_top">PriceList</a>.
+  </p>
+`;
+const parentDocs =
+  "In use: the title in [ServicesCard](?path=/story/organisms-services-services-card--config-overrides) (sized through `heroConfig`), [ServiceSummary](?path=/story/organisms-services-service-summary--default), [ServiceDetail](?path=/story/organisms-services-service-detail--default) and the group headings in [PriceList](?path=/story/molecules-pricelist--default).";
+
+export const Default: Story = {
+  render: (args) => ({
+    components: { HeroText },
+    setup() {
+      return { args };
+    },
+    template: `<div>${parentNote}<HeroText v-bind="args" /></div>`,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: `Three segments with the middle one accented. Use the Controls panel to change the tag, axis, size, icon and segments. ${parentDocs}`,
+      },
+    },
+  },
+};
+
+export const Sizes: Story = {
+  render: (args) => ({
+    components: { HeroText },
+    setup() {
+      return { args, sizes: ["display", "title", "heading", "subheading", "label"] };
+    },
+    template: `
+      <div style="display: grid; gap: 2.4rem;">
+        <HeroText v-for="size in sizes" :key="size" v-bind="args" :font-size="size" />
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: "Every `fontSize` step, largest first. The icon shrinks to `0.75em` at `subheading`.",
+      },
+    },
+  },
+};
+
+export const Vertical: Story = {
+  args: { axis: "vertical", fontSize: "display", icon: undefined },
   render: (args) => ({
     components: { HeroText },
     setup() {
@@ -67,4 +129,95 @@ export const Default: Story = {
     },
     template: `<HeroText v-bind="args" />`,
   }),
+  parameters: {
+    docs: {
+      description: {
+        story: "`axis=\"vertical\"` stacks each segment on its own line, spaced by `--hero-text-vertical-gap`.",
+      },
+    },
+  },
+};
+
+const longGerman = "Freihändige Balayage-Farbtechnik für natürlich wirkende Übergänge";
+
+const stressCases: { note: string; textContent: TextConfig[]; fontSize?: string }[] = [
+  {
+    note: "Unbroken word and long URL at display size",
+    fontSize: "display",
+    textContent: [
+      { text: "Kostenloselieferungfürallebestellungen", styleClass: "normal" },
+      { text: "https://example.invalid/a/very/long/url", styleClass: "accent" },
+    ],
+  },
+  {
+    note: "Long German copy across an accent segment",
+    textContent: [
+      { text: longGerman, styleClass: "normal" },
+      { text: longGerman, styleClass: "accent" },
+    ],
+  },
+  {
+    note: "Emoji first and HTML-like text (shown as text)",
+    textContent: [
+      { text: "😀 Neue", styleClass: "normal" },
+      { text: "<b>not bold</b>", styleClass: "accent" },
+    ],
+  },
+  {
+    note: "Blank and missing segments are dropped: only “Kept” and “Too” render, one space apart",
+    textContent: [
+      { text: "Kept", styleClass: "normal" },
+      { text: "", styleClass: "accent" },
+      { text: "   ", styleClass: "normal" },
+      { text: undefined, styleClass: "accent" } as unknown as TextConfig,
+      { text: "Too", styleClass: "accent" },
+    ],
+  },
+  {
+    note: "A single character",
+    textContent: [{ text: "A", styleClass: "accent" }],
+  },
+];
+
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  render: () => ({
+    components: { HeroText },
+    setup() {
+      return { stressCases };
+    },
+    template: `
+      <div style="display: grid; gap: 2.4rem; padding: 2.4rem;">
+        <template v-for="(item, index) in stressCases" :key="index">
+          <p style="margin: 0; font-size: 1.4rem;">{{ item.note }}, in a 24rem column.</p>
+          <div style="inline-size: 24rem; outline: 0.1rem dashed currentColor;">
+            <HeroText tag="h2" :font-size="item.fontSize ?? 'title'" :text-content="item.textContent" icon="lucide:sparkles" />
+          </div>
+        </template>
+
+        <p style="margin: 0; font-size: 1.4rem;">Right-to-left text, vertical axis.</p>
+        <HeroText
+          tag="h2"
+          axis="vertical"
+          dir="rtl"
+          :text-content="[{ text: 'تسريحات شعر', styleClass: 'normal' }, { text: 'لموسم الخريف', styleClass: 'accent' }]"
+        />
+
+        <p style="margin: 0; font-size: 1.4rem;">Empty <code>textContent</code>: an empty heading, no stray space.</p>
+        <div style="outline: 0.1rem dashed currentColor;">
+          <HeroText tag="h2" :text-content="[]" />
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      story: { inline: false, height: "1300px" },
+      description: {
+        story:
+          "Worst-case segments. Check: unbroken words and URLs wrap inside each dashed 24rem column, including at `display` size; long copy wraps across the accent segment with its gradient intact and its descenders unclipped; emoji and HTML-like text render as text; blank or missing segments leave no double spaces; right-to-left text stacks correctly on the vertical axis; an empty `textContent` renders an empty heading.",
+      },
+    },
+  },
 };

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

@@ -1,157 +1,163 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, afterEach, vi } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import HeroText from "../HeroText.vue";
+import type { TextConfig } from "~/types/components";
+
+type HeroTextProps = InstanceType<typeof HeroText>["$props"];
+
+const mounted: Awaited<ReturnType<typeof mountSuspended>>[] = [];
+
+const mountHero = async (props: Partial<HeroTextProps> = {}) => {
+  const wrapper = await mountSuspended(HeroText, {
+    props: { tag: "h1", textContent: [{ text: "Hello", styleClass: "normal" }], ...props } as HeroTextProps,
+  });
+  mounted.push(wrapper);
+  return wrapper;
+};
+
+const segmentTexts = (wrapper: Awaited<ReturnType<typeof mountHero>>) =>
+  wrapper.findAll(".hero-text-segment").map((span) => span.element.textContent);
+
+afterEach(() => {
+  mounted.splice(0).forEach((wrapper) => wrapper.unmount());
+  vi.restoreAllMocks();
+});
 
 describe("HeroText", () => {
   it("mounts without error", async () => {
-    const wrapper = await mountSuspended(HeroText, {
-      props: {
-        tag: "h1",
-        axis: "horizontal",
-        fontSize: "title",
-        textContent: [
-          { text: "Designing", styleClass: "normal" },
-          { text: "Artistry", styleClass: "accent" },
-          { text: "at Home", styleClass: "normal" },
-        ],
-        styleClassPassthrough: [],
-      },
-    });
+    const wrapper = await mountHero();
     expect(wrapper.vm).toBeTruthy();
   });
 
   it("renders correct HTML structure", async () => {
-    const wrapper = await mountSuspended(HeroText, {
-      props: {
-        tag: "h2",
-        axis: "vertical",
-        fontSize: "display",
-        textContent: [
-          { text: "Hello", styleClass: "normal" },
-          { text: "World", styleClass: "accent" },
-        ],
-        styleClassPassthrough: ["custom-class"],
-      },
+    const wrapper = await mountHero({
+      tag: "h2",
+      axis: "vertical",
+      fontSize: "display",
+      textContent: [
+        { text: "Hello", styleClass: "normal" },
+        { text: "World", styleClass: "accent" },
+      ],
+      styleClassPassthrough: ["custom-class"],
     });
     expect(wrapper.html()).toMatchSnapshot();
   });
 
-  it("applies axis and fontSize classes", async () => {
-    const wrapper = await mountSuspended(HeroText, {
-      props: {
-        tag: "h3",
-        axis: "vertical",
-        fontSize: "heading",
-        textContent: [{ text: "A", styleClass: "normal" }],
-        styleClassPassthrough: [],
-      },
-    });
-    const el = wrapper.find(".hero-text");
-    expect(el.classes()).toContain("axis-vertical");
-    expect(el.classes()).toContain("heading");
-  });
-
-  it("renders all textContent items as spans", async () => {
-    const wrapper = await mountSuspended(HeroText, {
-      props: {
-        tag: "h4",
-        textContent: [
-          { text: "One", styleClass: "normal" },
-          { text: "Two", styleClass: "accent" },
-          { text: "Three", styleClass: "normal" },
-        ],
-      },
-    });
-    const spans = wrapper.findAll("span");
-    expect(spans.length).toBe(3);
-    expect(spans[0]?.text()).toBe("One");
-    expect(spans[1]?.text()).toBe("Two");
-    expect(spans[2]?.text()).toBe("Three");
+  // ─── Size and axis ───────────────────────────────────────────────────────
+
+  it("defaults to data-font-size='title' and data-axis='horizontal'", async () => {
+    const wrapper = await mountHero();
+    expect(wrapper.attributes("data-font-size")).toBe("title");
+    expect(wrapper.attributes("data-axis")).toBe("horizontal");
   });
 
-  it("applies styleClassPassthrough classes", async () => {
-    const wrapper = await mountSuspended(HeroText, {
-      props: {
-        tag: "h5",
-        textContent: [{ text: "Styled", styleClass: "accent" }],
-        styleClassPassthrough: ["extra-class", "another-class"],
-      },
+  it("sets data-axis and data-font-size from the props", async () => {
+    const wrapper = await mountHero({ tag: "h3", axis: "vertical", fontSize: "heading" });
+    expect(wrapper.attributes("data-axis")).toBe("vertical");
+    expect(wrapper.attributes("data-font-size")).toBe("heading");
+  });
+
+  it("puts no bare size or axis class on the root", async () => {
+    const wrapper = await mountHero({ axis: "vertical", fontSize: "label" });
+    expect(wrapper.classes()).toEqual(["hero-text"]);
+  });
+
+  it("updates the attributes when the props change after mount", async () => {
+    const wrapper = await mountHero({ fontSize: "label" });
+    await wrapper.setProps({ fontSize: "display", axis: "vertical" });
+    expect(wrapper.attributes("data-font-size")).toBe("display");
+    expect(wrapper.attributes("data-axis")).toBe("vertical");
+  });
+
+  it("renders the tag from the tag prop", async () => {
+    const wrapper = await mountHero({ tag: "h4" });
+    expect(wrapper.element.tagName).toBe("H4");
+  });
+
+  it("renders the id when given", async () => {
+    const wrapper = await mountHero({ id: "hero-heading" });
+    expect(wrapper.attributes("id")).toBe("hero-heading");
+  });
+
+  // ─── Segments ────────────────────────────────────────────────────────────
+
+  it("renders every textContent item as a hero-text-segment span with its styleClass", async () => {
+    const wrapper = await mountHero({
+      tag: "h4",
+      textContent: [
+        { text: "One", styleClass: "normal" },
+        { text: "Two", styleClass: "accent" },
+        { text: "Three" },
+      ],
     });
-    const el = wrapper.find(".hero-text");
-    expect(el.classes()).toContain("extra-class");
-    expect(el.classes()).toContain("another-class");
+    const spans = wrapper.findAll(".hero-text-segment");
+    expect(spans).toHaveLength(3);
+    expect(spans[0]?.classes()).toContain("normal");
+    expect(spans[1]?.classes()).toContain("accent");
+    expect(spans[2]?.classes()).toEqual(["hero-text-segment"]);
   });
 
-  // -------------------------
-  // normalisedContent
-  // -------------------------
   it("trims leading and trailing whitespace from text segments", async () => {
-    const wrapper = await mountSuspended(HeroText, {
-      props: {
-        tag: "h1",
-        textContent: [{ text: "  Hello  ", styleClass: "normal" }],
-      },
-    });
-    expect(wrapper.find("span").element.textContent).toBe("Hello");
+    const wrapper = await mountHero({ textContent: [{ text: "  Hello  ", styleClass: "normal" }] });
+    expect(segmentTexts(wrapper)).toEqual(["Hello"]);
   });
 
   it("adds a trailing space to all segments except the last", async () => {
-    const wrapper = await mountSuspended(HeroText, {
-      props: {
-        tag: "h1",
-        textContent: [
-          { text: "One", styleClass: "normal" },
-          { text: "Two", styleClass: "normal" },
-          { text: "Three", styleClass: "normal" },
-        ],
-      },
+    const wrapper = await mountHero({
+      textContent: [{ text: "One" }, { text: "Two" }, { text: "Three" }],
     });
-    const spans = wrapper.findAll("span");
-    expect(spans[0]!.element.textContent).toBe("One ");
-    expect(spans[1]!.element.textContent).toBe("Two ");
-    expect(spans[2]!.element.textContent).toBe("Three");
-  });
-
-  it("does not add a trailing space when there is only one segment", async () => {
-    const wrapper = await mountSuspended(HeroText, {
-      props: {
-        tag: "h1",
-        textContent: [{ text: "Solo", styleClass: "normal" }],
-      },
-    });
-    expect(wrapper.find("span").element.textContent).toBe("Solo");
-  });
-
-  // -------------------------
-  // Icon
-  // -------------------------
-  it("renders an icon when the icon prop is provided", async () => {
-    const wrapper = await mountSuspended(HeroText, {
-      props: {
-        tag: "h1",
-        textContent: [{ text: "Hello", styleClass: "normal" }],
-        icon: "lucide:sparkles",
-      },
+    expect(segmentTexts(wrapper)).toEqual(["One ", "Two ", "Three"]);
+  });
+
+  it("drops segments with empty, blank or missing text, and spaces only the remaining ones", async () => {
+    const wrapper = await mountHero({
+      textContent: [
+        { text: "One" },
+        { text: "" },
+        { text: "   " },
+        { text: undefined } as unknown as TextConfig,
+        null as unknown as TextConfig,
+        { text: "Two" },
+      ],
     });
-    expect(wrapper.find(".hero-text__icon").exists()).toBe(true);
+    expect(segmentTexts(wrapper)).toEqual(["One ", "Two"]);
+  });
+
+  it("renders nothing but the heading for an empty textContent", async () => {
+    const wrapper = await mountHero({ textContent: [] });
+    expect(wrapper.findAll(".hero-text-segment")).toHaveLength(0);
+  });
+
+  it("renders HTML-like text as text", async () => {
+    const wrapper = await mountHero({ textContent: [{ text: "<b>not bold</b>" }] });
+    expect(wrapper.find("b").exists()).toBe(false);
+    expect(wrapper.text()).toBe("<b>not bold</b>");
+  });
+
+  // ─── Icon ────────────────────────────────────────────────────────────────
+
+  it("renders a decorative icon when the icon prop is provided", async () => {
+    const wrapper = await mountHero({ icon: "lucide:sparkles" });
+    const icon = wrapper.find(".hero-text__icon");
+    expect(icon.exists()).toBe(true);
+    expect(icon.attributes("aria-hidden")).toBe("true");
   });
 
   it("does not render an icon when the icon prop is omitted", async () => {
-    const wrapper = await mountSuspended(HeroText, {
-      props: {
-        tag: "h1",
-        textContent: [{ text: "Hello", styleClass: "normal" }],
-      },
-    });
+    const wrapper = await mountHero();
     expect(wrapper.find(".hero-text__icon").exists()).toBe(false);
   });
-});
 
-describe("HeroText styleClassPassthrough reactivity", () => {
+  // ─── styleClassPassthrough ───────────────────────────────────────────────
+
+  it("applies styleClassPassthrough classes", async () => {
+    const wrapper = await mountHero({ styleClassPassthrough: ["extra-class", "another-class"] });
+    expect(wrapper.classes()).toContain("extra-class");
+    expect(wrapper.classes()).toContain("another-class");
+  });
+
   it("updates classes when styleClassPassthrough changes after mount", async () => {
-    const wrapper = await mountSuspended(HeroText, {
-      props: { tag: "h2", textContent: [{ text: "Hero" }], styleClassPassthrough: ["original"] },
-    });
+    const wrapper = await mountHero({ 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/hero-text/tests/__snapshots__/HeroText.spec.ts.snap

@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`HeroText > renders correct HTML structure 1`] = `
-"<h2 class="hero-text custom-class display axis-vertical">
-  <!--v-if--><span class="text-block-0 normal">Hello </span><span class="text-block-1 accent">World</span>
+"<h2 class="hero-text custom-class" data-font-size="display" data-axis="vertical">
+  <!--v-if--><span class="hero-text-segment normal">Hello </span><span class="hero-text-segment accent">World</span>
 </h2>"
 `;

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

@@ -25,6 +25,9 @@ Private (not public API): `--_colour` (the resolved resting colour).
 
 ## State hooks
 
+`:hover` and `:focus-visible` switch to the `-hover` tokens. `:focus-visible` also draws a
+`0.2rem` outline in the resting colour, `0.3rem` out.
+
 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).
 
@@ -43,3 +46,17 @@ Set the tokens above on an element you own (a page or section class, or a class
 ## Class passthrough
 
 `style-class-passthrough` adds classes to the root link element. Reactive after mount.
+
+---
+
+## Notes
+
+- The root is an `inline-grid` capped at `max-inline-size: 100%`, and the label wraps
+  (`overflow-wrap: anywhere`), so a long or unbroken label or URL stays inside its column with the
+  icons centred on the wrapped text. Being a grid, it wraps as a block rather than flowing across
+  lines like a plain inline link.
+- No line-clamp token: link text names its destination and must stay readable.
+
+> Changed 2026-10-19: the label wraps (it used to overflow its column when unbroken) and the
+> focus ring is sized in rem (`2px`/`3px` became `0.2rem`/`0.3rem`, the same at the library's
+> 10px rem).

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

@@ -43,6 +43,7 @@ watch(
     display: inline-grid;
     grid-auto-flow: column;
     align-items: center;
+    max-inline-size: 100%;
     --_colour: var(--link-text-colour, currentColor);
 
     gap: var(--link-text-gap, 0.4em);
@@ -59,9 +60,14 @@ watch(
     }
 
     &:focus-visible {
-      outline: 2px solid var(--_colour);
-      outline-offset: 3px;
-      border-radius: 2px;
+      outline: 0.2rem solid var(--_colour);
+      outline-offset: 0.3rem;
+      border-radius: 0.2rem;
+    }
+
+    .link-text__label {
+      min-inline-size: 0;
+      overflow-wrap: anywhere;
     }
 
     .link-text__icon {