srcdev-nuxt-components 9.6.13 → 9.6.14

package/app/components/01.atoms/text-blocks/header-block/stories/HeaderBlock.stories.ts

@@ -1,84 +1,108 @@
+import { computed } from "vue";
 import HeaderBlock from "../HeaderBlock.vue";
 import type { Meta, StoryObj } from "@nuxtjs/storybook";
 
-const meta: Meta<typeof HeaderBlock> = {
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+interface StoryArgs {
+  tagLevel: HeadingLevel;
+  classLevel: HeadingLevel;
+  id?: string;
+  headingText: string;
+  styleClassPassthrough?: string | string[];
+}
+
+const meta: Meta<StoryArgs> = {
   title: "Atoms/Text Blocks/Header Block",
   component: HeaderBlock,
   argTypes: {
     tagLevel: {
       control: { type: "select" },
       options: [1, 2, 3, 4, 5, 6],
-      description: "Semantic heading level — which <h1>-<h6> tag is rendered",
+      description: "Semantic heading level: which `<h1>`-`<h6>` tag is rendered.",
+      table: { category: "Basic" },
     },
     classLevel: {
       control: { type: "select" },
       options: [1, 2, 3, 4, 5, 6],
-      description: "Visual size level — which .page-heading-N utility class is applied, independent of tagLevel",
+      description: "Visual size level: which `.page-heading-N` utility class is applied, independent of `tagLevel`.",
+      table: { category: "Basic" },
     },
     id: {
       control: "text",
-      description: "Bind to a wrapping section's aria-labelledby target (e.g. PageRow's heading-id slot prop)",
+      description: "Rendered as `id`, for a wrapping section's `aria-labelledby` (e.g. PageRow's `heading-id` slot prop).",
+      table: { category: "Accessibility" },
     },
-    styleClassPassthrough: {
-      control: "object",
-      description: "Additional classes applied to the root element",
+    headingText: {
+      control: "text",
+      description: "Story-only: text placed in the default slot.",
+      table: { category: "Slots (story-only)" },
     },
+    styleClassPassthrough: { table: { disable: true } },
   },
   args: {
     tagLevel: 1,
     classLevel: 1,
-    styleClassPassthrough: [],
+    headingText: "Page title",
   },
   parameters: {
     docs: {
       description: {
         component:
-          "Renders an <h1>-<h6> tag chosen by tagLevel (document structure/accessibility), styled by the global .page-heading-{classLevel} utility class (visual size) — the two are independent, so a component can be a semantic h2 styled at the page-heading-1 size.",
+          "Renders an `<h1>`-`<h6>` chosen by `tagLevel` (document structure), sized by the global `.page-heading-{classLevel}` utility class (visual size). The two are independent, so a heading can be a semantic `h2` styled at the `page-heading-1` size. The default slot is the heading content; `id` pairs it with a section's `aria-labelledby`.",
       },
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof HeaderBlock>;
+type Story = StoryObj<StoryArgs>;
+
+const render: Story["render"] = (args) => ({
+  components: { HeaderBlock },
+  setup() {
+    const componentArgs = computed(() => {
+      const { headingText: _headingText, ...rest } = args;
+      return rest;
+    });
+    return { args, componentArgs };
+  },
+  template: `<HeaderBlock v-bind="componentArgs">{{ args.headingText }}</HeaderBlock>`,
+});
 
 export const Default: Story = {
-  render: (args) => ({
-    components: { HeaderBlock },
-    setup() {
-      return { args };
+  render,
+  parameters: {
+    docs: {
+      description: {
+        story: "An `h1` at the `page-heading-1` size. Use the Controls panel to change either level or the text.",
+      },
     },
-    template: `<HeaderBlock v-bind="args">Page title</HeaderBlock>`,
-  }),
+  },
 };
 
 export const DecoupledLevels: Story = {
   name: "Semantic vs Visual Level Decoupled",
-  args: { tagLevel: 2, classLevel: 1 },
+  render,
+  args: { tagLevel: 2, classLevel: 1, headingText: "Section heading, styled big" },
   parameters: {
     docs: {
       description: {
         story:
-          "tagLevel=2 (renders an <h2>, correct for document structure below the page's real <h1>) but classLevel=1 (styled at the largest page-heading size) — inspect the DOM to confirm the tag is <h2> while it visually reads as the biggest heading on the page.",
+          "`tagLevel` 2 renders an `<h2>`, correct for document structure below the page's real `<h1>`, while `classLevel` 1 styles it at the largest size. Inspect the DOM to confirm the tag is `<h2>`.",
       },
     },
   },
-  render: (args) => ({
-    components: { HeaderBlock },
-    setup() {
-      return { args };
-    },
-    template: `<HeaderBlock v-bind="args">Section heading, styled big</HeaderBlock>`,
-  }),
 };
 
 export const SectionAriaLabelledby: Story = {
   name: "Paired with a Section's aria-labelledby",
   parameters: {
+    controls: { disable: true },
     docs: {
       description: {
         story:
-          "The id prop lets HeaderBlock be the target of a wrapping landmark's aria-labelledby — pass the same id both places (or, inside this library, the heading-id slot prop that PageRow/other section wrappers expose via useAriaLabelledById).",
+          "The `id` prop lets HeaderBlock be the target of a wrapping landmark's `aria-labelledby`. Pass the same id both places, or inside `PageRow`, `ProfileSection` (`heroText` slot) or `PageHeroHighlights` (`header` slot) bind the `heading-id` slot prop they expose. See the [PageRow](?path=/story/atoms-layouts-pagerow--aria-labelled-by) story, which wires the slot prop to a heading.",
       },
     },
   },
@@ -95,6 +119,14 @@ export const SectionAriaLabelledby: Story = {
 
 export const AllSizes: Story = {
   name: "All classLevel Sizes",
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story: "Every `classLevel`, from `page-heading-1` (`--step-8`) down to `page-heading-6` (`--step-3`).",
+      },
+    },
+  },
   render: () => ({
     components: { HeaderBlock },
     template: `
@@ -109,3 +141,41 @@ export const AllSizes: Story = {
     `,
   }),
 };
+
+export const StressTest: Story = {
+  name: "Stress Test (Worst-Case Data)",
+  parameters: {
+    controls: { disable: true },
+    docs: {
+      description: {
+        story:
+          "Worst-case headings. Check: an unbroken word and a long URL at `page-heading-1` wrap inside the dashed 24rem column instead of overflowing; long German copy wraps on spaces; emoji, right-to-left text and HTML-like text (shown as text) render normally; a single character still gets the full size; out-of-range levels (9 and 0) fall back to `h1` at `page-heading-1`.",
+      },
+    },
+  },
+  render: () => ({
+    components: { HeaderBlock },
+    setup() {
+      return { htmlLike: "<b>not bold</b>" };
+    },
+    template: `
+      <div style="display: grid; gap: 2.4rem; padding: 2.4rem;">
+        <p style="margin: 0; font-size: 1.4rem;">Unbroken word, long URL and long German copy in a 24rem column at the largest size.</p>
+        <div style="display: grid; gap: 1.6rem; inline-size: 24rem; outline: 0.1rem dashed currentColor;">
+          <HeaderBlock :tag-level="2" :class-level="1">Kostenloselieferungfürallebestellungen</HeaderBlock>
+          <HeaderBlock :tag-level="2" :class-level="2">https://example.invalid/a/very/long/unbroken/url</HeaderBlock>
+          <HeaderBlock :tag-level="2" :class-level="3">Kostenlose Lieferung für alle Bestellungen über einem Mindestbestellwert</HeaderBlock>
+        </div>
+
+        <p style="margin: 0; font-size: 1.4rem;">Emoji first, right-to-left, HTML-like text and a single character.</p>
+        <HeaderBlock :tag-level="2" :class-level="3">😀 Emoji at the start</HeaderBlock>
+        <HeaderBlock :tag-level="2" :class-level="3" dir="rtl">تسريحات شعر جديدة لموسم الخريف</HeaderBlock>
+        <HeaderBlock :tag-level="2" :class-level="3">{{ htmlLike }}</HeaderBlock>
+        <HeaderBlock :tag-level="2" :class-level="3">A</HeaderBlock>
+
+        <p style="margin: 0; font-size: 1.4rem;">Out-of-range levels (tag 9, class 0): both fall back to 1.</p>
+        <HeaderBlock :tag-level="9" :class-level="0">Fallback heading</HeaderBlock>
+      </div>
+    `,
+  }),
+};

package/app/components/01.atoms/text-blocks/header-block/tests/HeaderBlock.spec.ts

@@ -1,93 +1,107 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, afterEach, vi } from "vitest";
 import { mountSuspended } from "@nuxt/test-utils/runtime";
 import HeaderBlock from "../HeaderBlock.vue";
 
-describe("HeaderBlock", () => {
-  // ─── Mount ───────────────────────────────────────────────────────────────
+type HeaderBlockProps = InstanceType<typeof HeaderBlock>["$props"];
+
+const mounted: Awaited<ReturnType<typeof mountSuspended>>[] = [];
+
+const mountHeader = async (props: HeaderBlockProps = {}, content = "Title") => {
+  const wrapper = await mountSuspended(HeaderBlock, { props, slots: { default: content } });
+  mounted.push(wrapper);
+  return wrapper;
+};
+
+afterEach(() => {
+  mounted.splice(0).forEach((wrapper) => wrapper.unmount());
+  vi.restoreAllMocks();
+});
 
+describe("HeaderBlock", () => {
   it("mounts without error", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, {
-      slots: { default: "Hello World" },
-    });
+    const wrapper = await mountHeader({}, "Hello World");
     expect(wrapper.vm).toBeTruthy();
   });
 
   // ─── Snapshots ───────────────────────────────────────────────────────────
 
   it("renders correct HTML structure with default props", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, {
-      slots: { default: "Default heading" },
-    });
+    const wrapper = await mountHeader({}, "Default heading");
     expect(wrapper.html()).toMatchSnapshot();
   });
 
   it("renders correct HTML structure with all props set", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, {
-      props: { tagLevel: 3, classLevel: 5, id: "section-heading", styleClassPassthrough: ["custom-class"] },
-      slots: { default: "Custom heading" },
-    });
+    const wrapper = await mountHeader(
+      { tagLevel: 3, classLevel: 5, id: "section-heading", styleClassPassthrough: ["custom-class"] },
+      "Custom heading"
+    );
     expect(wrapper.html()).toMatchSnapshot();
   });
 
+  // ─── Root class ──────────────────────────────────────────────────────────
+
+  it("always has the header-block class", async () => {
+    const wrapper = await mountHeader({ tagLevel: 4, classLevel: 2, styleClassPassthrough: "extra" });
+    expect(wrapper.classes()).toContain("header-block");
+  });
+
   // ─── tagLevel / classLevel ───────────────────────────────────────────────
 
   it("defaults to an h1 with the page-heading-1 class", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, { slots: { default: "Title" } });
+    const wrapper = await mountHeader();
     expect(wrapper.element.tagName).toBe("H1");
     expect(wrapper.classes()).toContain("page-heading-1");
   });
 
   it("renders the tag matching tagLevel", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, {
-      props: { tagLevel: 4 },
-      slots: { default: "Title" },
-    });
+    const wrapper = await mountHeader({ tagLevel: 4 });
     expect(wrapper.element.tagName).toBe("H4");
   });
 
   it("applies the page-heading class matching classLevel, independent of tagLevel", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, {
-      props: { tagLevel: 2, classLevel: 6 },
-      slots: { default: "Title" },
-    });
+    const wrapper = await mountHeader({ tagLevel: 2, classLevel: 6 });
     expect(wrapper.element.tagName).toBe("H2");
     expect(wrapper.classes()).toContain("page-heading-6");
     expect(wrapper.classes()).not.toContain("page-heading-2");
   });
 
   it("accepts tagLevel/classLevel as numeric strings", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, {
-      props: { tagLevel: "5", classLevel: "2" },
-      slots: { default: "Title" },
-    });
+    const wrapper = await mountHeader({ tagLevel: "5", classLevel: "2" });
     expect(wrapper.element.tagName).toBe("H5");
     expect(wrapper.classes()).toContain("page-heading-2");
   });
 
   it("clamps an out-of-range tagLevel to 1", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, {
-      // @ts-expect-error deliberately invalid at the type level to test the runtime clamp
-      props: { tagLevel: 9 },
-      slots: { default: "Title" },
-    });
+    // @ts-expect-error deliberately invalid at the type level to test the runtime clamp
+    const wrapper = await mountHeader({ tagLevel: 9 });
     expect(wrapper.element.tagName).toBe("H1");
   });
 
   it("clamps an out-of-range classLevel to 1", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, {
-      // @ts-expect-error deliberately invalid at the type level to test the runtime clamp
-      props: { classLevel: 0 },
-      slots: { default: "Title" },
-    });
+    // @ts-expect-error deliberately invalid at the type level to test the runtime clamp
+    const wrapper = await mountHeader({ classLevel: 0 });
     expect(wrapper.classes()).toContain("page-heading-1");
   });
 
+  it("falls back to level 1 for fractional and negative levels", async () => {
+    // @ts-expect-error deliberately invalid at the type level to test the runtime clamp
+    const wrapper = await mountHeader({ tagLevel: 2.5, classLevel: -3 });
+    expect(wrapper.element.tagName).toBe("H1");
+    expect(wrapper.classes()).toContain("page-heading-1");
+  });
+
+  it("updates the tag and class when the levels change after mount", async () => {
+    const wrapper = await mountHeader({ tagLevel: 2, classLevel: 2 });
+    await wrapper.setProps({ tagLevel: 3, classLevel: 4 });
+    expect(wrapper.element.tagName).toBe("H3");
+    expect(wrapper.classes()).toContain("page-heading-4");
+    expect(wrapper.classes()).not.toContain("page-heading-2");
+  });
+
   // ─── Slot content ────────────────────────────────────────────────────────
 
   it("renders slot content", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, {
-      slots: { default: "<span class='highlight'>Big</span> idea" },
-    });
+    const wrapper = await mountHeader({}, "<span class='highlight'>Big</span> idea");
     expect(wrapper.find(".highlight").exists()).toBe(true);
     expect(wrapper.text()).toContain("idea");
   });
@@ -95,25 +109,27 @@ describe("HeaderBlock", () => {
   // ─── id ──────────────────────────────────────────────────────────────────
 
   it("does not render an id attribute by default", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, { slots: { default: "Title" } });
+    const wrapper = await mountHeader();
     expect(wrapper.attributes("id")).toBeUndefined();
   });
 
   it("renders a given id, for pairing with a wrapping section's aria-labelledby", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, {
-      props: { id: "section-heading" },
-      slots: { default: "Title" },
-    });
+    const wrapper = await mountHeader({ id: "section-heading" });
     expect(wrapper.attributes("id")).toBe("section-heading");
   });
 
   // ─── styleClassPassthrough ───────────────────────────────────────────────
 
   it("applies styleClassPassthrough classes", async () => {
-    const wrapper = await mountSuspended(HeaderBlock, {
-      props: { styleClassPassthrough: "hero-title" },
-      slots: { default: "Title" },
-    });
+    const wrapper = await mountHeader({ styleClassPassthrough: "hero-title" });
     expect(wrapper.classes()).toContain("hero-title");
   });
+
+  it("updates classes when styleClassPassthrough changes after mount", async () => {
+    const wrapper = await mountHeader({ styleClassPassthrough: ["original"] });
+    await wrapper.setProps({ styleClassPassthrough: ["updated"] });
+    expect(wrapper.classes()).not.toContain("original");
+    expect(wrapper.classes()).toContain("updated");
+    expect(wrapper.classes()).toContain("header-block");
+  });
 });

package/app/components/01.atoms/text-blocks/header-block/tests/__snapshots__/HeaderBlock.spec.ts.snap

@@ -1,5 +1,5 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
-exports[`HeaderBlock > renders correct HTML structure with all props set 1`] = `"<h3 id="section-heading" class="page-heading-5 custom-class">Custom heading</h3>"`;
+exports[`HeaderBlock > renders correct HTML structure with all props set 1`] = `"<h3 id="section-heading" class="header-block page-heading-5 custom-class">Custom heading</h3>"`;
 
-exports[`HeaderBlock > renders correct HTML structure with default props 1`] = `"<h1 class="page-heading-1">Default heading</h1>"`;
+exports[`HeaderBlock > renders correct HTML structure with default props 1`] = `"<h1 class="header-block page-heading-1">Default heading</h1>"`;

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

@@ -18,7 +18,6 @@
 |---|---|---|
 | `--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 |
@@ -39,12 +38,20 @@ Private (not public API): `--_hero-text-accent-offset`.
 
 | 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"` |
+| `[data-font-size="display" \| "title" \| "heading" \| "subheading" \| "label"]` | The `font-size` prop |
+| `[data-axis="horizontal" \| "vertical"]` | The `axis` prop (vertical is a flex column) |
+| `.hero-text-segment.accent` | A segment with `styleClass: "accent"` |
 
-Inner elements: `.hero-text__icon`, and one `<span class="text-block-{n}">` per segment (plus its
-own `styleClass`).
+Inner elements: `.hero-text__icon` (decorative, `aria-hidden`), and one
+`<span class="hero-text-segment">` per segment, plus its own `styleClass`. Segments with blank or
+missing `text` are dropped. Target one segment with `.hero-text-segment:nth-of-type(n)`.
+
+> Changed 2026-10-19: size and axis were bare classes on the root (`.title`, `.label`,
+> `.axis-vertical`, ...) and segments were `.text-block-{n}`, names a consumer's own CSS could
+> collide with. Replace `.hero-text.title` with `.hero-text[data-font-size="title"]`,
+> `.hero-text.axis-vertical` with `.hero-text[data-axis="vertical"]`, and `.text-block-1` with
+> `.hero-text-segment:nth-of-type(2)`. `--hero-text-horizontal-gap` is gone: it never applied (the
+> horizontal axis isn't a flex container; segments are joined by a space).
 
 ---
 
@@ -72,3 +79,12 @@ 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 heading element. Reactive after mount.
+
+---
+
+## Notes
+
+- Every segment wraps (`overflow-wrap: anywhere`), so an unbroken word or URL stays inside its
+  column. There is no line-clamp token: clamping needs `overflow: hidden`, which clips the accent
+  descender offset and italic overhang. `ServiceDetail` clamps its title itself, with an allowance
+  for both.

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

@@ -1,7 +1,19 @@
 <template>
-  <component :is="tag" :id="id" class="hero-text" :class="[elementClasses, ...componentClasses]">
-    <Icon v-if="props.icon" :name="props.icon" class="hero-text__icon" />
-    <span v-for="(item, index) in normalisedContent" :key="index" :class="['text-block-' + index, item.styleClass]">
+  <component
+    :is="tag"
+    :id="id"
+    class="hero-text"
+    :class="[elementClasses]"
+    :data-font-size="fontSize"
+    :data-axis="axis"
+  >
+    <Icon v-if="icon" :name="icon" class="hero-text__icon" aria-hidden="true" />
+    <span
+      v-for="(item, index) in normalisedContent"
+      :key="index"
+      class="hero-text-segment"
+      :class="item.styleClass"
+    >
       {{ item.text }}
     </span>
   </component>
@@ -27,10 +39,6 @@ const props = withDefaults(defineProps<Props>(), {
   styleClassPassthrough: () => [],
 });
 
-const componentClasses = computed(() => {
-  return [props.fontSize, `axis-${props.axis}`];
-});
-
 const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
 
 watch(
@@ -38,12 +46,16 @@ watch(
   () => resetElementClasses(props.styleClassPassthrough)
 );
 
-const normalisedContent = computed(() =>
-  props.textContent.map((item, index) => ({
+// CMS data can hold segments with missing or blank text; drop them so no stray spaces render.
+const normalisedContent = computed(() => {
+  const segments = (props.textContent ?? [])
+    .map((item) => ({ ...item, text: String(item?.text ?? "").trim() }))
+    .filter((item) => item.text !== "");
+  return segments.map((item, index) => ({
     ...item,
-    text: item.text.trim() + (index < props.textContent.length - 1 ? " " : ""),
-  }))
-);
+    text: item.text + (index < segments.length - 1 ? " " : ""),
+  }));
+});
 </script>
 
 <style lang="css">
@@ -55,14 +67,11 @@ const normalisedContent = computed(() =>
       "wght" 400,
       "ital" 1;
     line-height: 1;
+    overflow-wrap: anywhere;
 
     margin: var(--hero-text-margin, 0);
 
-    &.axis-horizontal {
-      flex-direction: row;
-      gap: var(--hero-text-horizontal-gap, 0.5ch);
-    }
-    &.axis-vertical {
+    &[data-axis="vertical"] {
       display: flex;
       gap: var(--hero-text-vertical-gap, 0.4em);
       flex-direction: column;
@@ -73,19 +82,19 @@ const normalisedContent = computed(() =>
       color: var(--hero-text-icon-colour, var(--colour-text-accent));
     }
 
-    &.display {
+    &[data-font-size="display"] {
       font-size: var(--hero-text-display, clamp(4.8rem, 4vw + 2rem, 9.6rem));
     }
 
-    &.title {
+    &[data-font-size="title"] {
       font-size: var(--hero-text-title, clamp(3.6rem, 4vw + 2rem, 4.8rem));
     }
 
-    &.heading {
+    &[data-font-size="heading"] {
       font-size: var(--hero-text-heading, clamp(2.8rem, 4vw + 2rem, 3rem));
     }
 
-    &.subheading {
+    &[data-font-size="subheading"] {
       font-size: var(--hero-text-subheading, 2.4rem);
 
       .hero-text__icon {
@@ -93,11 +102,11 @@ const normalisedContent = computed(() =>
       }
     }
 
-    &.label {
+    &[data-font-size="label"] {
       font-size: var(--hero-text-label, 1.75rem);
     }
 
-    .accent {
+    .hero-text-segment.accent {
       --_hero-text-accent-offset: var(--hero-text-accent-offset, 0.2em);
 
       background-clip: text;

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

@@ -2,7 +2,7 @@ import { test, expect, type Page, type Locator } from "@playwright/test";
 
 // --- Config ---
 const STORYBOOK_URL = "http://127.0.0.1:6006";
-const STORY_BASE = "atoms-text-blocks-herotext";
+const STORY_BASE = "atoms-text-blocks-hero-text";
 const HEADING_TIMEOUT = 20_000;
 
 // --- Types ---