srcdev-nuxt-components 9.1.0 → 9.1.1

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/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

@@ -50,7 +50,7 @@ Each skill is a single markdown file named `<area>-<task>.md`.
     ├── 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