srcdev-nuxt-components 9.4.7 → 9.4.9

package/app/components/01.atoms/navigation/tabs/tests/TabsCore.spec.ts

@@ -0,0 +1,274 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import TabsCore from "../TabsCore.vue";
+
+class MockResizeObserver {
+  observe = vi.fn();
+  unobserve = vi.fn();
+  disconnect = vi.fn();
+}
+
+const slots = {
+  "tab-0-trigger": "Tab One",
+  "tab-0-content": "<p class='panel-0'>Content one</p>",
+  "tab-1-trigger": "Tab Two",
+  "tab-1-content": "<p class='panel-1'>Content two</p>",
+  "tab-2-trigger": "Tab Three",
+  "tab-2-content": "<p class='panel-2'>Content three</p>",
+};
+
+const fiveSlots = {
+  ...slots,
+  "tab-3-trigger": "Tab Four",
+  "tab-3-content": "<p class='panel-3'>Content four</p>",
+  "tab-4-trigger": "Tab Five",
+  "tab-4-content": "<p class='panel-4'>Content five</p>",
+};
+
+describe("TabsCore", () => {
+  beforeEach(() => {
+    vi.stubGlobal("ResizeObserver", MockResizeObserver);
+  });
+
+  // ─── Mount ───────────────────────────────────────────────────────────────
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    expect(wrapper.vm).toBeTruthy();
+  });
+
+  it("renders one trigger and one panel per itemCount", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    expect(wrapper.findAll(".tabs-list-item")).toHaveLength(3);
+    expect(wrapper.findAll(".tab-content")).toHaveLength(3);
+  });
+
+  // ─── Accessibility structure ─────────────────────────────────────────────
+
+  it("renders a tablist with the default aria-label", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const tablist = wrapper.find("[role='tablist']");
+    expect(tablist.exists()).toBe(true);
+    expect(tablist.attributes("aria-label")).toBe("Tabs");
+  });
+
+  it("uses a custom ariaLabel when provided", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3, ariaLabel: "Settings" }, slots });
+    expect(wrapper.find("[role='tablist']").attributes("aria-label")).toBe("Settings");
+  });
+
+  it("renders each trigger as a type=button with role=tab", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+    triggers.forEach((trigger) => {
+      expect(trigger.attributes("type")).toBe("button");
+      expect(trigger.attributes("role")).toBe("tab");
+    });
+  });
+
+  it("renders each panel as role=tabpanel labelled by its trigger", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const panels = wrapper.findAll(".tab-content");
+    panels.forEach((panel, index) => {
+      expect(panel.attributes("role")).toBe("tabpanel");
+      expect(panel.attributes("aria-labelledby")).toBe(`tab-${index}-trigger`);
+    });
+  });
+
+  // ─── Active tab state ────────────────────────────────────────────────────
+
+  it("marks the first tab active and its panel visible/unhidden on mount", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+    const panels = wrapper.findAll(".tab-content");
+
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+    expect(triggers[0]!.attributes("tabindex")).toBe("0");
+    expect(triggers[1]!.attributes("aria-selected")).toBe("false");
+    expect(triggers[1]!.attributes("tabindex")).toBe("-1");
+
+    expect(panels[0]!.attributes("aria-hidden")).toBe("false");
+    expect((panels[0]!.element as HTMLElement).style.display).toBe("block");
+    expect(panels[1]!.attributes("aria-hidden")).toBe("true");
+    expect((panels[1]!.element as HTMLElement).style.display).toBe("none");
+  });
+
+  it("activates a tab on click and updates aria-selected, tabindex, and panel visibility", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+    const panels = wrapper.findAll(".tab-content");
+
+    await triggers[1]!.trigger("click");
+
+    expect(triggers[0]!.attributes("aria-selected")).toBe("false");
+    expect(triggers[0]!.attributes("tabindex")).toBe("-1");
+    expect(triggers[1]!.attributes("aria-selected")).toBe("true");
+    expect(triggers[1]!.attributes("tabindex")).toBe("0");
+
+    expect(panels[0]!.attributes("aria-hidden")).toBe("true");
+    expect(panels[1]!.attributes("aria-hidden")).toBe("false");
+    expect((panels[1]!.element as HTMLElement).style.display).toBe("block");
+  });
+
+  // ─── Keyboard navigation ─────────────────────────────────────────────────
+
+  it("moves focus and activates the next tab on ArrowRight (axis x)", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[0]!.trigger("keydown", { key: "ArrowRight" });
+
+    expect(triggers[1]!.attributes("aria-selected")).toBe("true");
+    expect(triggers[1]!.attributes("tabindex")).toBe("0");
+  });
+
+  it("wraps to the first tab on ArrowRight from the last tab", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[2]!.trigger("click");
+    await triggers[2]!.trigger("keydown", { key: "ArrowRight" });
+
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+  });
+
+  it("moves focus to the previous tab on ArrowLeft (axis x)", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[1]!.trigger("click");
+    await triggers[1]!.trigger("keydown", { key: "ArrowLeft" });
+
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+  });
+
+  it("uses ArrowUp/ArrowDown instead of ArrowLeft/ArrowRight when axis is y", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3, axis: "y" }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[0]!.trigger("keydown", { key: "ArrowRight" });
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+
+    await triggers[0]!.trigger("keydown", { key: "ArrowDown" });
+    expect(triggers[1]!.attributes("aria-selected")).toBe("true");
+  });
+
+  it("jumps to the last tab on End and the first tab on Home", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[0]!.trigger("keydown", { key: "End" });
+    expect(triggers[2]!.attributes("aria-selected")).toBe("true");
+
+    await triggers[2]!.trigger("keydown", { key: "Home" });
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+  });
+
+  // ─── trackHover / trackActive / trackIndicator ──────────────────────────
+
+  it("renders all three indicator decorators by default", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    expect(wrapper.find(".nav__hovered").exists()).toBe(true);
+    expect(wrapper.find(".nav__active").exists()).toBe(true);
+    expect(wrapper.find(".nav__active-indicator").exists()).toBe(true);
+  });
+
+  it("omits the hover decorator when trackHover is false", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3, trackHover: false }, slots });
+    expect(wrapper.find(".nav__hovered").exists()).toBe(false);
+  });
+
+  it("omits the active decorator when trackActive is false", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3, trackActive: false }, slots });
+    expect(wrapper.find(".nav__active").exists()).toBe(false);
+  });
+
+  it("omits the underline indicator when trackIndicator is false", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3, trackIndicator: false }, slots });
+    expect(wrapper.find(".nav__active-indicator").exists()).toBe(false);
+  });
+
+  // ─── Hover indicator movement ────────────────────────────────────────────
+
+  it("moves the hover indicator position on mouseenter", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const tabsList = wrapper.find(".tabs-list").element as HTMLElement;
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    expect(tabsList.style.getPropertyValue("--_width-hovered")).toBe("");
+
+    await triggers[1]!.trigger("mouseenter");
+
+    expect(tabsList.style.getPropertyValue("--_width-hovered")).not.toBe("");
+  });
+
+  it("resets the hover indicator to the active tab on mouseleave", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const tabsList = wrapper.find(".tabs-list");
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[1]!.trigger("mouseenter");
+    await tabsList.trigger("mouseleave");
+
+    // Should not throw, and the hover indicator settles back onto the active (first) tab.
+    expect((tabsList.element as HTMLElement).style.getPropertyValue("--_x-hovered")).toBe("0px");
+  });
+
+  it("clears a pending settle timeout when hovering a second tab before the first settles", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 3 }, slots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+    const clearTimeoutSpy = vi.spyOn(global, "clearTimeout");
+
+    await triggers[1]!.trigger("mouseenter");
+    await triggers[2]!.trigger("mouseenter");
+
+    expect(clearTimeoutSpy).toHaveBeenCalled();
+  });
+
+  // ─── Regression: more than 3 tabs ────────────────────────────────────────
+  // The original hand-rolled version of this component had an indicator-positioning issue
+  // that only showed up with itemCount > 3 — these lock in correct behaviour at 5.
+
+  it("activates a distant tab (index 0 -> index 4) directly via click", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 5 }, slots: fiveSlots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[4]!.trigger("click");
+
+    expect(triggers[0]!.attributes("aria-selected")).toBe("false");
+    expect(triggers[4]!.attributes("aria-selected")).toBe("true");
+    expect(triggers[4]!.attributes("tabindex")).toBe("0");
+    expect(wrapper.findAll(".tab-content")[4]!.attributes("aria-hidden")).toBe("false");
+  });
+
+  it("does not recolour tabs spanned by a distant activation jump (regression: intermediate labels going invisible)", async () => {
+    // The old implementation force-applied a "transitioning" class to every tab spanned by a
+    // jump, forcing it to the active-indicator's text colour for the whole transition — even
+    // though the sliding indicator only visually reaches each spanned tab partway through, and
+    // for a forward jump doesn't reach the middle tabs until late in the transition. That made
+    // intermediate labels flash a colour matching neither their own background nor (yet) the
+    // indicator's, going invisible. Spanned tabs should only ever carry aria-selected/hover
+    // state of their own — never a class forcing them to look active.
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 5 }, slots: fiveSlots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    // Active tab starts at index 0, so activating index 4 spans every tab in between.
+    await triggers[4]!.trigger("click");
+
+    [1, 2, 3].forEach((index) => {
+      expect(triggers[index]!.attributes("aria-selected")).toBe("false");
+      expect(triggers[index]!.classes()).not.toContain("transitioning");
+    });
+  });
+
+  it("wraps correctly with End then ArrowRight across 5 tabs", async () => {
+    const wrapper = await mountSuspended(TabsCore, { props: { itemCount: 5 }, slots: fiveSlots });
+    const triggers = wrapper.findAll(".tabs-list-item");
+
+    await triggers[0]!.trigger("keydown", { key: "End" });
+    expect(triggers[4]!.attributes("aria-selected")).toBe("true");
+
+    await triggers[4]!.trigger("keydown", { key: "ArrowRight" });
+    expect(triggers[0]!.attributes("aria-selected")).toBe("true");
+  });
+});

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

@@ -0,0 +1,43 @@
+# HeaderBlock — Consumer Styling Guide
+
+## No component-owned CSS tokens
+
+`HeaderBlock` has no `<style>` block of its own. Visual size comes from applying one of six global
+`.page-heading-1`–`.page-heading-6` utility classes (`classLevel` prop), defined in
+`app/assets/styles/setup/05.typography/02.utility-classes/_font-classes-page-heading.css`:
+
+```css
+.page-heading-1 { font-size: var(--step-8); }
+.page-heading-2 { font-size: var(--step-7); }
+/* … down to .page-heading-6 { font-size: var(--step-3); } */
+```
+
+Each size is a fluid type-scale token (`--step-3` through `--step-8`, defined globally, not by
+this component) — override those tokens at a page/section scope to change every `page-heading-*`
+element's size at once, not just this component's.
+
+All six levels also reset `margin-block: 0rem` and `padding-block: 0rem` (instead of relying on the
+browser's own per-level heading margins, which vary by `<h1>`–`<h6>` and would otherwise fight
+`classLevel`/`tagLevel` being independent). This is a deliberate blank slate — add spacing in your
+own CSS rather than expecting a level to come with baked-in margin:
+
+```css
+.my-page .page-heading-1 {
+  margin-block: 2.4rem 1.6rem;
+}
+```
+
+## Overriding 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:
+
+```vue
+<HeaderBlock :tag-level="2" :class-level="1" style-class-passthrough="hero-title">Big idea</HeaderBlock>
+```
+
+```css
+.hero-title {
+  font-size: 6rem;
+}
+```

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

@@ -0,0 +1,50 @@
+<template>
+  <component :is="tag" :id :class="[classLevelClass, elementClasses]">
+    <slot></slot>
+  </component>
+</template>
+
+<script setup lang="ts">
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+interface Props {
+  /** Semantic heading level — controls which <h1>-<h6> tag is rendered. */
+  tagLevel?: HeadingLevel | `${HeadingLevel}`;
+  /** Visual size level — controls which `.page-heading-N` utility class is applied. Independent of tagLevel, so a component can be, e.g., a semantic h2 styled at the page-heading-1 size. */
+  classLevel?: HeadingLevel | `${HeadingLevel}`;
+  /** Bind to a wrapping section's aria-labelledby target (e.g. the heading-id slot prop from PageRow/useAriaLabelledById). */
+  id?: string | null;
+  styleClassPassthrough?: string | string[];
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  tagLevel: 1,
+  classLevel: 1,
+  id: null,
+  styleClassPassthrough: () => [],
+});
+
+const validLevels = [1, 2, 3, 4, 5, 6];
+
+const tagLevel = computed(() => {
+  const n = Number(props.tagLevel);
+  return validLevels.includes(n) ? n : 1;
+});
+
+const classLevel = computed(() => {
+  const n = Number(props.classLevel);
+  return validLevels.includes(n) ? n : 1;
+});
+
+const tag = computed(() => `h${tagLevel.value}`);
+const classLevelClass = computed(() => `page-heading-${classLevel.value}`);
+
+const { elementClasses, resetElementClasses } = useStyleClassPassthrough(props.styleClassPassthrough);
+
+watch(
+  () => props.styleClassPassthrough,
+  (newVal) => {
+    resetElementClasses(newVal ?? []);
+  }
+);
+</script>

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

@@ -0,0 +1,111 @@
+import HeaderBlock from "../HeaderBlock.vue";
+import type { Meta, StoryObj } from "@nuxtjs/storybook";
+
+const meta: Meta<typeof HeaderBlock> = {
+  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",
+    },
+    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",
+    },
+    id: {
+      control: "text",
+      description: "Bind to a wrapping section's aria-labelledby target (e.g. PageRow's heading-id slot prop)",
+    },
+    styleClassPassthrough: {
+      control: "object",
+      description: "Additional classes applied to the root element",
+    },
+  },
+  args: {
+    tagLevel: 1,
+    classLevel: 1,
+    styleClassPassthrough: [],
+  },
+  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.",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof HeaderBlock>;
+
+export const Default: Story = {
+  render: (args) => ({
+    components: { HeaderBlock },
+    setup() {
+      return { args };
+    },
+    template: `<HeaderBlock v-bind="args">Page title</HeaderBlock>`,
+  }),
+};
+
+export const DecoupledLevels: Story = {
+  name: "Semantic vs Visual Level Decoupled",
+  args: { tagLevel: 2, classLevel: 1 },
+  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.",
+      },
+    },
+  },
+  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: {
+    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).",
+      },
+    },
+  },
+  render: () => ({
+    components: { HeaderBlock },
+    template: `
+      <section aria-labelledby="story-section-heading">
+        <HeaderBlock id="story-section-heading" :tag-level="2" :class-level="2">Section title</HeaderBlock>
+        <p>Section content…</p>
+      </section>
+    `,
+  }),
+};
+
+export const AllSizes: Story = {
+  name: "All classLevel Sizes",
+  render: () => ({
+    components: { HeaderBlock },
+    template: `
+      <div>
+        <HeaderBlock :tag-level="1" :class-level="1">page-heading-1</HeaderBlock>
+        <HeaderBlock :tag-level="2" :class-level="2">page-heading-2</HeaderBlock>
+        <HeaderBlock :tag-level="3" :class-level="3">page-heading-3</HeaderBlock>
+        <HeaderBlock :tag-level="4" :class-level="4">page-heading-4</HeaderBlock>
+        <HeaderBlock :tag-level="5" :class-level="5">page-heading-5</HeaderBlock>
+        <HeaderBlock :tag-level="6" :class-level="6">page-heading-6</HeaderBlock>
+      </div>
+    `,
+  }),
+};

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

@@ -0,0 +1,119 @@
+import { describe, it, expect } from "vitest";
+import { mountSuspended } from "@nuxt/test-utils/runtime";
+import HeaderBlock from "../HeaderBlock.vue";
+
+describe("HeaderBlock", () => {
+  // ─── Mount ───────────────────────────────────────────────────────────────
+
+  it("mounts without error", async () => {
+    const wrapper = await mountSuspended(HeaderBlock, {
+      slots: { default: "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" },
+    });
+    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" },
+    });
+    expect(wrapper.html()).toMatchSnapshot();
+  });
+
+  // ─── tagLevel / classLevel ───────────────────────────────────────────────
+
+  it("defaults to an h1 with the page-heading-1 class", async () => {
+    const wrapper = await mountSuspended(HeaderBlock, { slots: { default: "Title" } });
+    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" },
+    });
+    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" },
+    });
+    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" },
+    });
+    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" },
+    });
+    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" },
+    });
+    expect(wrapper.classes()).toContain("page-heading-1");
+  });
+
+  // ─── Slot content ────────────────────────────────────────────────────────
+
+  it("renders slot content", async () => {
+    const wrapper = await mountSuspended(HeaderBlock, {
+      slots: { default: "<span class='highlight'>Big</span> idea" },
+    });
+    expect(wrapper.find(".highlight").exists()).toBe(true);
+    expect(wrapper.text()).toContain("idea");
+  });
+
+  // ─── id ──────────────────────────────────────────────────────────────────
+
+  it("does not render an id attribute by default", async () => {
+    const wrapper = await mountSuspended(HeaderBlock, { slots: { default: "Title" } });
+    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" },
+    });
+    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" },
+    });
+    expect(wrapper.classes()).toContain("hero-title");
+  });
+});

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

@@ -0,0 +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 default props 1`] = `"<h1 class="page-heading-1">Default heading</h1>"`;

package/app/components/03.organisms/site-header/SiteHeader.vue

@@ -33,7 +33,7 @@
 <script setup lang="ts">
 import type { ResponsiveHeaderProp } from "../../../types/components";
 import PageRow from "../../01.atoms/page-row/PageRow.vue";
-import SkipLinks from "../../skip-links/SkipLinks.vue";
+import SkipLinks from "../../01.atoms/navigation/skip-links/SkipLinks.vue";
 import ResponsiveHeader from "../responsive-header/ResponsiveHeader.vue";
 
 interface Props {

package/app/components/03.organisms/site-header/tests/SiteHeader.spec.ts

@@ -34,7 +34,7 @@ describe("SiteHeader", () => {
       slots: { branding: "<a href='/' class='brand-link'>Brand</a>" },
       global: { stubs: { ResponsiveHeader: responsiveHeaderStub } },
     });
-    expect(wrapper.find(".home-link .brand-link").exists()).toBe(true);
+    expect(wrapper.find(".skip-links__home .brand-link").exists()).toBe(true);
   });
 
   it("does not render the secondaryNavigation slot when not provided", async () => {

package/app/components/03.organisms/site-header/tests/__snapshots__/SiteHeader.spec.ts.snap

@@ -4,9 +4,9 @@ exports[`SiteHeader > renders correct HTML structure with default props 1`] = `
 "<div class="page-row content">
   <header class="site-header">
     <nav class="home-navigation" aria-label="Home Navigation">
-      <div class="home-link-navigation">
-        <div class="home-link"></div>
-        <nav class="skip-links-nav" aria-label="Skip navigation"><a href="#main-content" class="skip-link">Skip to main content</a><a href="#footer-content" class="skip-link">Skip to footer</a></nav>
+      <div class="skip-links">
+        <div class="skip-links__home"></div>
+        <nav class="skip-links__nav" aria-label="Skip navigation"><a href="#main-content" class="skip-links__link">Skip to main content</a><a href="#footer-content" class="skip-links__link">Skip to footer</a></nav>
       </div>
     </nav>
     <div class="responsive-header-stub" main-nav-aria-label="Main navigation" secondary-nav-aria-label="Secondary navigation" overflow-menu-aria-label="Overflow navigation menu"></div>