srcdev-nuxt-components 9.1.0 → 9.1.2

package/.claude/settings.json

@@ -20,7 +20,8 @@
     ],
     "additionalDirectories": [
       "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/content-wrappers/content-width",
-      "/Users/simoncornforth/websites/nuxt-components/.claude/skills"
+      "/Users/simoncornforth/websites/nuxt-components/.claude/skills",
+      "/Users/simoncornforth/websites/nuxt-components/app/components/02.molecules/navigation/site-navigation/tests"
     ]
   }
 }

package/.claude/skills/components/page-hero-highlights.md

@@ -19,6 +19,8 @@ The layout uses a 4-row CSS Grid with `subgrid` — no `translate`, negative mar
 | `highlightsJustify`     | `"start" \| "center" \| "end" \| "space-between" \| "space-around"` | `"start"`   | Alignment of highlight items along the main axis                                                                                |
 | `maxWidth`              | `string`                                                            | `undefined` | Cap the central content column (e.g. `"1064px"`). Gutters grow to enforce the constraint; below this width they hold at `16px`. |
 | `contentAlign`          | `"start" \| "center"`                                               | `"center"`  | When `maxWidth` is set: `"center"` grows gutters equally; `"start"` pins content to the left with a fixed `16px` left gutter.   |
+| `contentPanel`          | `boolean`                                                           | `true`      | When `true`, renders a decorative panel behind the content slot and offsets the highlights strip. Set to `false` for a flat layout with no backdrop. |
+| `highlightTitleBaseline`| `boolean`                                                           | `false`     | When `true`, fixes the highlight title row to a set height so titles align at a common baseline. Override `--highlight-title-height` to tune. |
 | `styleClassPassthrough` | `string \| string[]`                                                | `[]`        | Extra classes on the root element                                                                                               |
 
 ## Slots
@@ -83,6 +85,64 @@ Example with `HeroText` in the header slot:
 </PageHeroHighlights>
 ```
 
+## PageHeroHighlightsHeader companion component
+
+A co-located companion component for laying out the `#header` slot. Provides a responsive two-area layout: `#start` (title/description) and `#end` (action buttons), stacking vertically on mobile and sitting side-by-side on wider viewports.
+
+Located at: `app/components/04.templates/page-hero-highlights/PageHeroHighlightsHeader.vue`
+
+### PageHeroHighlightsHeader props
+
+| Prop                    | Type                 | Default | Description                       |
+| ----------------------- | -------------------- | ------- | --------------------------------- |
+| `styleClassPassthrough` | `string \| string[]` | `[]`    | Extra classes on the root element |
+
+### PageHeroHighlightsHeader slots
+
+| Slot    | Purpose                                                   |
+| ------- | --------------------------------------------------------- |
+| `start` | Title and description — always rendered, fills full width when `#end` is absent |
+| `end`   | Action buttons — `.phh-end` is only mounted when this slot is provided |
+
+### CSS tokens
+
+| Token              | Default  | Description                              |
+| ------------------ | -------- | ---------------------------------------- |
+| `--phh-padding-block` | `1.6rem` | Block padding on the header              |
+| `--phh-gap`        | `1.6rem` | Gap between `#start` and `#end` areas    |
+| `--phh-end-gap`    | `0.8rem` | Gap between items within `#end`          |
+
+### Usage
+
+```vue
+<PageHeroHighlights tag="section">
+  <template #header="{ headingId }">
+    <PageHeroHighlightsHeader>
+      <template #start>
+        <h1 :id="headingId" class="page-heading-1">Surplus needs</h1>
+        <p class="page-body-normal">Let us know what you need help with.</p>
+      </template>
+      <template #end>
+        <HelpButton />
+        <Button>Create new need</Button>
+      </template>
+    </PageHeroHighlightsHeader>
+  </template>
+  ...
+</PageHeroHighlights>
+```
+
+Omit `#end` for a single-element header — `#start` fills full width with no layout change needed:
+
+```vue
+<PageHeroHighlightsHeader>
+  <template #start>
+    <h1 :id="headingId">Dashboard</h1>
+    <p>Overview of your account activity.</p>
+  </template>
+</PageHeroHighlightsHeader>
+```
+
 ## With aria-labelledby (section tag)
 
 When `tag="section"`, `aria-labelledby` is set automatically. Wire the heading id via the scoped slot prop:

package/.claude/skills/components/services-card-grid.md

@@ -0,0 +1,110 @@
+# ServicesCardGrid Component
+
+## Overview
+
+`ServicesCardGrid` renders a responsive auto-fit CSS grid of `ServicesCard` components from a `Service[]` array. It owns the grid layout; card-level presentation (eyebrow/hero typography) and slot content are configured via pass-through props and a scoped `#actions` slot.
+
+## Props
+
+| Prop                    | Type                              | Default  | Required |
+| ----------------------- | --------------------------------- | -------- | -------- |
+| `servicesData`          | `Service[]`                       | —        | **yes**  |
+| `tag`                   | `"div" \| "section" \| "main"`    | `"div"`  | no       |
+| `eyebrowConfig`         | `EyebrowConfig`                   | `{}`     | no       |
+| `heroConfig`            | `HeroConfig`                      | `{}`     | no       |
+| `styleClassPassthrough` | `string \| string[]`              | `[]`     | no       |
+
+Both config props are passed through to every `ServicesCard` in the grid unchanged. See [services-card.md](./services-card.md) for the full `EyebrowConfig` / `HeroConfig` key reference.
+
+## Slots
+
+| Slot      | Slot props                 | Purpose                                          |
+| --------- | -------------------------- | ------------------------------------------------ |
+| `actions` | `{ serviceData: Service }` | CTA rendered inside each card below description  |
+
+## CSS custom properties
+
+Set on `.services-card-grid` (or scoped to a page class):
+
+| Token                  | Default   | Controls                              |
+| ---------------------- | --------- | ------------------------------------- |
+| `--_gap`               | `4rem`    | Gap between grid cells                |
+| `--_column-min-width`  | `250px`   | Minimum column width before wrapping  |
+
+## Consumer page boilerplate
+
+```vue
+<template>
+  <div>
+    <NuxtLayout name="default">
+      <template #layout-content>
+        <LayoutRow tag="div" variant="content" :style-class-passthrough="['mbe-20']">
+          <h1 class="page-heading-1">Services</h1>
+        </LayoutRow>
+
+        <LayoutRow tag="div" variant="content" :style-class-passthrough="['mbe-20']">
+          <ServicesCardGrid
+            :services-data="servicesData ?? []"
+            :eyebrow-config="{ fontSize: 'large' }"
+            :hero-config="{ tag: 'h2', fontSize: 'heading' }"
+          >
+            <template #actions="{ serviceData }">
+              <InputButtonCore
+                variant="secondary"
+                :button-text="`Enquire about ${serviceData.title}`"
+                :href="`/services/${serviceData.slug}`"
+                :style-class-passthrough="['mbs-24']"
+              >
+                <template #right>
+                  <Icon name="mdi:arrow-right" class="icon" />
+                </template>
+              </InputButtonCore>
+            </template>
+          </ServicesCardGrid>
+        </LayoutRow>
+      </template>
+    </NuxtLayout>
+  </div>
+</template>
+
+<script setup lang="ts">
+definePageMeta({ layout: false });
+
+useHead({
+  title: "Services",
+  meta: [{ name: "description", content: "Our services" }],
+  bodyAttrs: { class: "page-services" },
+});
+
+const store = useServicesStore();
+const { servicesData } = storeToRefs(store);
+
+if (servicesData.value.length === 0) {
+  await store.fetchServicesData();
+}
+</script>
+
+<style lang="css">
+.page-services {
+  /* Page-level CSS token overrides — delete any you don't need */
+  .services-card-grid {
+    --_gap: 4rem;
+    --_column-min-width: 250px;
+
+    .services-card {
+      --_eyebrow-text-margin-block: 0.8rem 0;
+      --_hero-text-margin-block: 2rem 1rem;
+      --_description-text-colour: var(--colour-text-secondary);
+    }
+  }
+}
+</style>
+```
+
+## Notes
+
+- Component is auto-imported in Nuxt — no import needed.
+- The `Service` type is imported from `~/types/types.services`.
+- Uses `repeat(auto-fit, minmax(var(--_column-min-width), 1fr))` — columns grow to fill available space and wrap when below the minimum width.
+- The `#actions` slot template is passed down into each `ServicesCard`; `serviceData` is the scoped prop for the current iteration item.
+- Data fetching is the page's responsibility — pass an empty array as fallback while loading (`servicesData ?? []`).

package/.claude/skills/components/services-card.md

@@ -10,8 +10,26 @@
 | ----------------------- | --------------------------------- | ------- | -------- |
 | `serviceData`           | `Service`                         | —       | **yes**  |
 | `tag`                   | `"div" \| "section" \| "article"` | `"div"` | no       |
+| `eyebrowConfig`         | `EyebrowConfig`                   | `{}`    | no       |
+| `heroConfig`            | `HeroConfig`                      | `{}`    | no       |
 | `styleClassPassthrough` | `string \| string[]`              | `[]`    | no       |
 
+### EyebrowConfig
+
+| Key        | Type                              | Default    |
+| ---------- | --------------------------------- | ---------- |
+| `tag`      | `"p" \| "div" \| "span"`         | `"div"`    |
+| `fontSize` | `"large" \| "medium" \| "small"` | `"large"`  |
+
+### HeroConfig
+
+| Key        | Type                                                           | Default     |
+| ---------- | -------------------------------------------------------------- | ----------- |
+| `tag`      | `"h1" \| "h2" \| "h3" \| "h4" \| "h5" \| "h6"`              | `"h2"`      |
+| `fontSize` | `"display" \| "title" \| "heading" \| "subheading" \| "label"` | `"heading"` |
+
+Config objects are partial — only specify the keys you want to override. Unset keys fall back to the defaults shown above.
+
 ## Slots
 
 | Slot      | Slot props                 | Purpose                                                                |
@@ -20,6 +38,16 @@
 
 The `actions` slot receives `serviceData` as a scoped prop so the consumer can construct routes or labels from the service data without additional props.
 
+## CSS custom properties
+
+Set on `.services-card` (or scoped to a page class):
+
+| Token                          | Default                       | Controls                        |
+| ------------------------------ | ----------------------------- | ------------------------------- |
+| `--_eyebrow-text-margin-block` | `0.8rem 0`                    | Space above/below the eyebrow   |
+| `--_hero-text-margin-block`    | `2rem 1rem`                   | Space above/below the title     |
+| `--_description-text-colour`   | `var(--colour-text-secondary)` | Description paragraph colour    |
+
 ## Basic usage
 
 ```vue
@@ -38,44 +66,50 @@ The `actions` slot receives `serviceData` as a scoped prop so the consumer can c
 </ServicesCard>
 ```
 
-## Multiple actions
+## With config overrides
 
 ```vue
-<ServicesCard :service-data="service">
+<ServicesCard
+  :service-data="service"
+  :eyebrow-config="{ fontSize: 'small' }"
+  :hero-config="{ tag: 'h3', fontSize: 'title' }"
+>
   <template #actions="{ serviceData }">
-    <InputButtonCore
-      variant="secondary"
-      :button-text="`More about ${serviceData.title}`"
-      :href="`/services/${serviceData.slug}`"
-    />
-    <NuxtLink :to="`/services/${serviceData.slug}/contact`">Get in touch</NuxtLink>
+    <InputButtonCore variant="secondary" :button-text="`Enquire`" :href="`/services/${serviceData.slug}`" />
   </template>
 </ServicesCard>
 ```
 
-## Local style override scaffold
-
-When consuming this component, scaffold a style block using `styleClassPassthrough`. Delete the block if unused.
-
-See [component-local-style-override.md](../component-local-style-override.md) for the full pattern.
+## Consumer page boilerplate
 
 ```vue
-<ServicesCard :style-class-passthrough="['my-card']" :service-data="service">
-  ...
-</ServicesCard>
-
-<style>
-/* ─── ServicesCard local overrides ─────────────────────────────────
-   Colours, borders, geometry only — do not override behaviour.
-   Delete this block if no overrides are needed.
-   ─────────────────────────────────────────────────────────────────── */
-.services-card {
-  &.my-card {
-    /* Geometry — image */
-    /* .image-wrapper { border-radius: 1.2rem; } */
-
-    /* Colours */
-    /* .description { color: var(--brand-text-secondary); } */
+<template>
+  <ServicesCard
+    :service-data="service"
+    :eyebrow-config="{ fontSize: 'large' }"
+    :hero-config="{ tag: 'h2', fontSize: 'heading' }"
+  >
+    <template #actions="{ serviceData }">
+      <InputButtonCore
+        variant="secondary"
+        :button-text="`Enquire about ${serviceData.title}`"
+        :href="`/services/${serviceData.slug}`"
+        :style-class-passthrough="['mbs-24']"
+      >
+        <template #right>
+          <Icon name="mdi:arrow-right" class="icon" />
+        </template>
+      </InputButtonCore>
+    </template>
+  </ServicesCard>
+</template>
+
+<style lang="css">
+.page-my-page {
+  .services-card {
+    --_eyebrow-text-margin-block: 0.8rem 0;
+    --_hero-text-margin-block: 2rem 1rem;
+    --_description-text-colour: var(--colour-text-secondary);
   }
 }
 </style>
@@ -85,5 +119,6 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 
 - Component is auto-imported in Nuxt — no import needed.
 - The `Service` type is imported from `~/types/types.services`.
-- Grid rows are sized `auto 2ch auto 5lh auto` — the last row (`auto`) accommodates the `actions` slot at any height.
+- Grid rows are sized `auto auto auto 5lh auto` — the `5lh` row locks description height so actions align across cards.
 - Image has a `3/4` aspect ratio with a subtle scale-on-hover effect.
+- Usually consumed via `ServicesCardGrid` rather than directly.

package/.claude/skills/components/site-navigation.md

@@ -0,0 +1,120 @@
+# SiteNavigation
+
+## Overview
+
+`SiteNavigation` is a responsive site-wide navigation component. It renders a horizontal link list on wide viewports and automatically collapses to a burger-menu + slide-down panel on narrow viewports. Collapse is driven by a `ResizeObserver` that compares the list's natural `scrollWidth` against the nav container's `clientWidth` — no breakpoint prop needed.
+
+Both the horizontal list and the panel include animated active/hover indicator decorators (underline indicator + background highlight) that snap into position using CSS custom properties set via JavaScript.
+
+## Component location
+
+`app/components/02.molecules/navigation/site-navigation/SiteNavigation.vue`
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `navItemData` | `NavItemData` | — (required) | Navigation items — see type below |
+| `navAlign` | `"left" \| "center" \| "right"` | `"left"` | Alignment of the horizontal nav list |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root `<nav>` |
+
+## NavItemData type
+
+```ts
+import type { NavItemData } from "~/types/components/navigation-horizontal.d";
+
+const navItemData: NavItemData = {
+  main: [
+    { text: "Home",     href: "/" },
+    { text: "About",    href: "/about" },
+    { text: "Services", href: "/services", cssName: "is-featured" },
+    { text: "Contact",  href: "/contact", iconName: "heroicons:envelope", isExternal: false },
+  ],
+};
+```
+
+`NavItem` fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `text` | `string` | Link label |
+| `href` | `string` | Link destination |
+| `isExternal` | `boolean?` | Passed to NuxtLink `:external` — opens in new tab |
+| `iconName` | `string?` | Iconify icon name rendered before the label |
+| `cssName` | `string?` | CSS class applied to the `<li>` element |
+
+## Basic usage
+
+```vue
+<SiteNavigation :nav-item-data="navItemData" nav-align="left" />
+```
+
+Always use hyphenated prop names in templates (ESLint enforces this).
+
+## CSS token API
+
+Set these tokens on a parent element (e.g. your `<header>`) to theme the navigation.
+
+```css
+.your-header {
+  /* ── Decorators ────────────────────────────────────── */
+  --site-nav-decorator-indicator-color: var(--rose-05);  /* underline bar */
+
+  /* ── Horizontal nav links ──────────────────────────── */
+  --site-nav-link-color:        var(--warm-01);
+  --site-nav-link-hover-color:  var(--rose-04);
+  --site-nav-link-active-color: var(--rose-05);
+  --site-nav-link-size:         1.6rem;
+  --site-nav-link-weight:       400;
+  --site-nav-link-tracking:     0.06em;
+  --site-nav-gap:               2.2rem;
+  --site-nav-transition:        250ms ease;
+
+  /* ── Mobile panel ──────────────────────────────────── */
+  --site-nav-panel-bg:                  var(--page-bg, #1a1614);
+  --site-nav-panel-border-color:        color-mix(in oklch, var(--rose-05) 35%, transparent);
+  --site-nav-panel-link-color:          var(--warm-01);
+  --site-nav-panel-link-hover-color:    var(--rose-04);
+  --site-nav-panel-link-active-color:   var(--rose-05);
+  --site-nav-panel-padding-block:       1.4rem;
+  --site-nav-panel-padding-inline:      1.5rem;
+  --site-nav-panel-slide-duration:      350ms;
+  --site-nav-panel-slide-easing:        cubic-bezier(0.4, 0, 0.2, 1);
+  --site-nav-panel-decorator-indicator-color: var(--rose-05);
+  --site-nav-panel-indicator-left:      0;      /* position the panel indicator bar */
+  --site-nav-panel-indicator-right:     auto;
+
+  /* ── Burger button ─────────────────────────────────── */
+  --site-nav-burger-color:      var(--warm-01);
+  --site-nav-burger-width:      22px;
+  --site-nav-burger-height:     1.5px;
+  --site-nav-burger-gap:        5px;
+  --site-nav-burger-transition: 300ms ease;
+
+  /* ── Backdrop (teleported to <body>) ───────────────── */
+  --site-nav-backdrop-bg:       oklch(0% 0 0 / 55%);
+  --site-nav-backdrop-blur:     3px;
+  --site-nav-backdrop-duration: 350ms;
+}
+```
+
+## Behaviour notes
+
+- **Collapse detection**: `ResizeObserver` fires on every container resize. The list's `scrollWidth` is cached whenever the list is in the DOM; that cached value is compared against the container's `clientWidth` to set `isCollapsed`.
+- **isLoaded state**: The component uses `useState("site-nav-loaded")` — a Nuxt shared state — to gate visibility until the first measurement is complete, preventing a flash of the wrong nav state on load. The nav renders `opacity: 0` until `is-loaded` is applied.
+- **Teleport**: The backdrop overlay is teleported to `<body>` via `<Teleport>` and is only mounted when `isCollapsed && isLoaded`.
+- **Panel inert**: The `#site-nav-panel` div receives `:inert="!isMenuOpen ? true : undefined"` — it is inert (keyboard/pointer-inaccessible) when closed.
+- **Decorator init**: `initNavDecorators()` and `initPanelDecorators()` inject `<li>` elements with CSS-driven indicator `<div>`s. They query `[data-nav-item]` / `[data-panel-nav-item]` to find links, and look for `router-link-active` to set the initial active position.
+
+## Accessibility
+
+- Root `<nav>` has `aria-label="Site navigation"`.
+- Burger button uses `aria-expanded` (string `"true"/"false"`) and `aria-controls="site-nav-panel"`.
+- Backdrop and indicator `<li>` elements are `aria-hidden="true"`.
+- Panel div is `inert` when closed.
+
+## Related files
+
+- Type: `app/types/components/navigation-horizontal.d.ts`
+- Tests: `app/components/02.molecules/navigation/site-navigation/tests/SiteNavigation.spec.ts`
+- Story: `app/components/02.molecules/navigation/site-navigation/stories/SiteNavigation.stories.ts`

package/.claude/skills/index.md

@@ -43,14 +43,15 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── layout-row.md           — LayoutRow variant guide, width/margin decisions, usage patterns
     ├── link-text.md            — LinkText props, slots, usage patterns, styling
     ├── page-hero-highlights.md — PageHeroHighlights template: hero + highlights strip grid, CSS custom property theming
-    ├── services-card.md        — ServicesCard props, actions slot, usage patterns
+    ├── services-card.md        — ServicesCard props (incl. eyebrowConfig/heroConfig), actions slot, CSS tokens, page boilerplate
+    ├── services-card-grid.md   — ServicesCardGrid props, config pass-through, CSS tokens, full page boilerplate
     ├── services-section.md     — ServicesSection props, summary-link/cta slots, summary vs full mode
     ├── contact-section.md      — ContactSection props (stepperIndicatorSize pass-through), 3-item info+form layout, slot API
     ├── stepper-list.md         — StepperList dynamic slots (item-{n}/indicator-{n}), props, connector behaviour
     ├── expanding-panel.md      — ExpandingPanel v-model, forceOpened, slots (summary/icon/content), ARIA wiring
     ├── navigation-horizontal.md — NavigationHorizontal props, NavItemData type, CSS token API, import path gotcha
     ├── input-copy-core.md      — InputCopyCore: readonly copy-to-clipboard input; props, emits, slots, CSS classes, usage
-    └── treatment-consultant.md — TreatmentConsultant 5-step wizard: props, step flow, treatment exclusion logic, recommendation matrix, image paths
+    └── site-navigation.md      — SiteNavigation: responsive nav with auto-collapse, burger menu, decorator indicators, CSS token API
 ```
 
 ## Skill file template