srcdev-nuxt-components 9.0.15 → 9.0.17

package/.claude/settings.json

@@ -0,0 +1,25 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx vitest run app/components/01.atoms/content-wrappers/layout-grid/tests/LayoutGrid.spec.ts)",
+      "Bash(npx vitest run app/components/01.atoms/content-wrappers/layout-grid/tests/LayoutGrid.spec.ts --update-snapshots)",
+      "Bash(npx vitest run app/components/01.atoms/content-wrappers/layout-grid/tests/LayoutGrid.spec.ts -u)",
+      "Bash(npx vitest run app/components/01.atoms/content-wrappers/content-width/tests/ContentWidth.spec.ts)",
+      "Bash(node -e \":*)",
+      "Bash(git add app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-cols/LayoutGridByCols.vue app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-cols/tests/LayoutGridByCols.spec.ts app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-cols/tests/__snapshots__/LayoutGridByCols.spec.ts.snap app/pages/forms/examples/buttons/index.vue app/pages/forms/examples/material/checkbox-radio-panels.vue app/pages/forms/examples/material/text-fields.vue)",
+      "Bash(git commit:*)",
+      "Bash(npx vitest run app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-width/tests/LayoutGridByWidth.spec.ts)",
+      "Bash(npx vitest run app/components/01.atoms/card/tests/CardCore.spec.ts)",
+      "Bash(npx vitest run app/components/image-galleries/slider-gallery/tests/SliderGallery.spec.ts)",
+      "Bash(npx vitest run)",
+      "Bash(git mv:*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx vitest:*)",
+      "Bash(git show:*)"
+    ],
+    "additionalDirectories": [
+      "/Users/simoncornforth/websites/nuxt-components/app/components/01.atoms/content-wrappers/content-width",
+      "/Users/simoncornforth/websites/nuxt-components/.claude/skills"
+    ]
+  }
+}

package/.claude/skills/component-aria-landmark.md

@@ -0,0 +1,68 @@
+# Aria Landmark Labelling
+
+## Overview
+
+Components that accept a `tag` prop may render as a semantic landmark element (`section`, `main`, `article`, `aside`). Landmarks benefit from an accessible name via `aria-labelledby` pointing to a heading inside them. The `useAriaLabelledById` composable handles this automatically.
+
+## The composable
+
+`app/composables/useAriaLabelledById.ts`
+
+Returns `{ headingId, ariaLabelledby }`:
+
+- `headingId` — a stable ID (via `useId()`) to place on the heading element inside the slot
+- `ariaLabelledby` — computed: set to `headingId` when `tag` is a landmark, `undefined` otherwise (which removes the attribute entirely)
+
+Labelled tags: `section`, `main`, `article`, `aside`.
+
+## Usage in a component
+
+```vue
+<template>
+  <component
+    :is="tag"
+    :aria-labelledby="ariaLabelledby"
+  >
+    <slot name="header" :heading-id="headingId"></slot>
+  </component>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  tag?: "div" | "section" | "main";
+}
+const props = withDefaults(defineProps<Props>(), { tag: "div" });
+
+const { headingId, ariaLabelledby } = useAriaLabelledById(() => props.tag);
+</script>
+```
+
+The composable is auto-imported — no explicit import needed in `.vue` files.
+
+## Consumer usage
+
+When using `tag="section"` (or another landmark), the heading element inside the slot must consume `headingId`:
+
+```vue
+<MyComponent tag="section">
+  <template #header="{ headingId }">
+    <h1 :id="headingId">Page Title</h1>
+  </template>
+</MyComponent>
+```
+
+When `tag="div"` (default), the `aria-labelledby` attribute is absent and `headingId` may be ignored.
+
+## Components already using this pattern
+
+- `PageHeroHighlights` (04.templates)
+- `ProfileSection` (02.molecules)
+- `ServicesSection` (03.organisms)
+- `LayoutGridByCols` (01.atoms)
+- `LayoutGridByWidth` (01.atoms)
+
+## Notes
+
+- If a component does not expose a named slot with `:heading-id`, the `headingId` is still generated — the consumer simply places their own heading inside the slot without binding the id.
+- `headingId` is stable across renders (SSR-safe via `useId()`).
+- Do not replicate the old manual pattern (`const needsLabel = computed(() => props.tag === "section")`) — use this composable instead.

package/.claude/skills/component-dynamic-slots.md

@@ -0,0 +1,150 @@
+# Dynamic Slot Patterns
+
+## Overview
+
+Two distinct patterns exist for dynamic slots in this project. Choose based on who controls
+the slot structure — the **consumer** (named dynamic slots) or the **component** (indexed dynamic slots).
+
+**Default to named dynamic slots.** Only use indexed dynamic slots when there is a specific
+reason the component must know the count in advance (see decision guide below).
+
+---
+
+## Pattern 1 — Named Dynamic Slots
+
+The component renders whatever slots the consumer passes. Slot names are not known in advance.
+Best for container/card/layout components.
+
+### When to use
+
+- The component is a wrapper/shell (card, panel, grid, dialog)
+- Slot names are consumer-defined (semantic or indexed — doesn't matter)
+- `itemCount` would only be used to drive the slot loop and nothing else
+
+### Implementation
+
+```vue
+<template>
+  <component :is="tag" class="my-component">
+    <template v-for="(_, name) in $slots" :key="name">
+      <div>
+        <slot :name="name"></slot>
+      </div>
+    </template>
+  </component>
+</template>
+```
+
+No `useSlots()` call needed — `$slots` is available directly in the template.
+
+### Slot name as CSS class
+
+Since `name` is already available in the loop, it can be applied as a class on the wrapper element. This gives each slot section a targetable class derived automatically from the slot name — no extra props needed:
+
+```vue
+<template v-for="(_, name) in $slots" :key="name">
+  <div class="card-row" :class="`card-row-${name}`">
+    <slot :name="name"></slot>
+  </div>
+</template>
+```
+
+A consumer passing `#header` gets `<div class="card-row card-row-header">`, `#footer` gets `<div class="card-row card-row-footer">`, etc. The component's CSS can then target `.card-row-header`, `.card-row-footer` etc. for per-section styling.
+
+### Consumer usage
+
+Any slot names work — semantic or indexed:
+
+```vue
+<!-- Semantic names (card) -->
+<CardCore variant="solid">
+  <template #header>...</template>
+  <template #body>...</template>
+  <template #footer>...</template>
+</CardCore>
+
+<!-- Indexed names (grid) — consumer still uses v-for with dynamic slot names -->
+<LayoutGridByCols :column-count="3">
+  <template v-for="(item, i) in items" #[`item-${i}`] :key="i">
+    {{ item }}
+  </template>
+</LayoutGridByCols>
+```
+
+Slots are rendered in document order.
+
+### Reference components (named dynamic slots)
+
+- `app/components/01.atoms/card/CardCore.vue`
+- `app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-cols/LayoutGridByCols.vue`
+- `app/components/01.atoms/content-wrappers/layout-grid/layout-grid-by-width/LayoutGridByWidth.vue`
+- `app/components/container-glow/ContainerGlowCore.vue`
+
+---
+
+## Pattern 2 — Indexed Dynamic Slots
+
+The component declares how many slots exist via an `itemCount` prop. Slot names follow a
+predictable pattern (`item-0`, `item-1`, …).
+
+### When to use — only when itemCount is needed for logic beyond slot iteration
+
+| Reason to keep `itemCount` | Example |
+
+|---|---|
+| Multiple slot types per item must be grouped into one rendered element | `AccordianCore` — `summary`/`icon`/`content` per `<ExpandingPanel>` |
+| Two parallel loops must stay in sync for aria linking | `TabsCore` — nav `<li>` loop + content `<div>` loop linked by id |
+| `itemCount` drives non-slot logic (z-index, CSS scope, counters) | `WipeAwayVertical` — `z-index: itemCount - key`, `timelineScope` computed |
+| `$slots` inspection per iteration is needed to conditionally render | `StepperList` — checks `$slots[indicator-N]` to toggle class per `<li>` |
+
+If none of these apply and `itemCount` is **only** used to generate the slot loop — convert to named dynamic slots.
+
+### Implementation
+
+```vue
+<template>
+  <div class="my-grid">
+    <template v-for="index in itemCount" :key="index">
+      <slot :name="`item-${index - 1}`"></slot>
+    </template>
+  </div>
+</template>
+
+<script setup lang="ts">
+interface Props {
+  itemCount: number;
+}
+const props = defineProps<Props>();
+</script>
+```
+
+### Multi-type indexed slots
+
+Some components pair multiple slot types per index (e.g. TabsCore):
+
+```vue
+<template v-for="index in itemCount" :key="index">
+  <slot :name="`tab-${index}-trigger`"></slot>
+  <slot :name="`tab-${index}-content`"></slot>
+</template>
+```
+
+### Reference components (indexed dynamic slots)
+
+- `app/components/tabs/TabsCore.vue`
+- `app/components/accordian/AccordianCore.vue`
+- `app/components/02.molecules/stepper-list/StepperList.vue`
+- `app/components/view-timeline/WipeAwayVertical.vue`
+
+---
+
+## Comparison
+
+| | Named dynamic slots | Indexed dynamic slots |
+|---|---|---|
+| Slot names defined by | Consumer | Component |
+| Number of slots | Open-ended | Fixed by `itemCount` prop |
+| Template mechanism | `v-for="(_, name) in $slots"` | `v-for="index in itemCount"` |
+| Typical use case | Card, grid, panel, layout wrapper | Tabs, accordion, stepper, timeline |
+| Slot naming convention | Any (semantic or indexed) | Enforced (`item-0`, `tab-0-trigger`) |
+| Default choice? | ✅ Yes | Only when count is needed for logic |

package/.claude/skills/component-export-types.md

@@ -0,0 +1,61 @@
+# Export Component Types for Consumers
+
+## Overview
+
+Types defined inline in a `.vue` component file are not easily importable by consuming apps. This skill moves them into `app/types/components/` and re-exports via the barrel, so consumers can import from the package root.
+
+## Steps
+
+### 1. Create a types file
+
+Create `app/types/components/<component-name>.d.ts` with the exported interfaces:
+
+```ts
+// app/types/components/navigation-horizontal.d.ts
+export interface NavItem {
+  text: string;
+  href?: string;
+  isExternal?: boolean;
+  iconName?: string;
+  cssName?: string;
+}
+
+export interface NavItemData {
+  [key: string]: NavItem[];
+}
+```
+
+### 2. Add to the barrel
+
+In `app/types/components/index.ts`, add an export line:
+
+```ts
+export * from "./navigation-horizontal.d"
+```
+
+### 3. Update the component
+
+Replace the inline `export interface` blocks in the `.vue` file with an import from the shared types file:
+
+```ts
+// Before
+export interface NavItem { ... }
+export interface NavItemData { ... }
+
+// After
+import type { NavItem, NavItemData } from "~/types/components/navigation-horizontal.d";
+```
+
+## Consuming app usage
+
+Once published, consumers import from the package barrel:
+
+```ts
+import type { NavItem, NavItemData } from "nuxt-components/app/types/components";
+```
+
+## Notes
+
+- The `.d.ts` extension is conventional for type-only files but is not required — plain `.ts` works too (see `hero-text.ts`).
+- Keep the type file minimal: only types, no runtime code.
+- If a type is already used by multiple components, consider a shared location like `app/types/components/shared.d.ts` rather than naming it after one component.

package/.claude/skills/component-local-style-override.md

@@ -0,0 +1,126 @@
+# Component Local Style Override
+
+## Overview
+
+When including a component in a page or consuming component, visual customisation can be applied
+locally using `styleClassPassthrough` combined with a scoped style block in the consuming file.
+This avoids adding one-off props to the component and keeps customisation co-located with the usage.
+
+No changes to the component are required.
+
+---
+
+## Pattern
+
+### 1. Pass a modifier class via styleClassPassthrough
+
+```vue
+<CardCore :style-class-passthrough="['featured-card']">
+  ...
+</CardCore>
+```
+
+### 2. Add a style block in the consuming file
+
+Scaffold this block when adding the component. Include a comment so future developers know it
+is safe to delete if no overrides are needed.
+
+```vue
+<style>
+/* ─── CardCore local overrides ─────────────────────────────────────
+   Customise the appearance of this instance via CSS custom properties or
+   direct overrides. Delete this block if no overrides are needed.
+   Colours, borders, geometry only — do not override behaviour (display, pointer-events, etc.)
+   ─────────────────────────────────────────────────────────────────────────── */
+.card-core {
+  &.featured-card {
+    /* Colours */
+    /* --_background-color: var(--brand-primary); */
+    /* --_border-color: var(--brand-secondary); */
+
+    /* Geometry */
+    /* border-radius: 1.6rem; */
+
+    /* Border / outline */
+    /* --_border-width: 0.3rem; */
+  }
+}
+</style>
+```
+
+---
+
+## What to override
+
+| Category | Examples | Approach |
+|---|---|---|
+| Colours | backgrounds, borders, text | CSS custom properties if the component exposes them, otherwise direct values |
+| Geometry | border-radius, padding, gap | Direct property or `--_` private variable |
+| Border / outline | width, style, colour | Direct property or `--_` private variable |
+
+**Do not override behaviour** — `display`, `visibility`, `pointer-events`, `z-index`, animations.
+Those belong in the component or a structural parent, not a style modifier.
+
+---
+
+## CSS custom property targeting
+
+Components use `--_` prefixed private custom properties internally. These can be targeted via
+a modifier class at higher specificity:
+
+```css
+/* Component internally defines: */
+.my-component {
+  --_background-color: white;
+  background-color: var(--_background-color);
+}
+
+/* Consumer overrides via modifier: */
+.my-component {
+  &.my-modifier {
+    --_background-color: var(--brand-surface); /* CSS token */
+    /* or */
+    --_background-color: #f5f0eb;              /* direct value */
+  }
+}
+```
+
+Note: `--_` properties are component-internal. If the component is updated and renames them,
+the override will silently stop working. For shared/themeable overrides, prefer components that
+expose `--theme-*` public variables instead.
+
+---
+
+## When to use this vs other approaches
+
+| Situation | Approach |
+|---|---|
+| One-off visual tweak for a specific page/context | Local style override (this skill) |
+| Consistent appearance across all instances site-wide | Default theme (`theming-override-default.md`) |
+| Variant that belongs in the component itself | Add a `variant` prop value to the component |
+| Structural layout change | Wrapper element or parent component |
+
+### Component type guide
+
+**Local overrides are appropriate for:**
+
+- Display/content components — cards, panels, hero sections, media blocks
+- Layout wrappers used in a specific visual context (e.g. a grid section with a tinted background)
+- Any component whose appearance legitimately varies per page or usage context
+
+**Keep styling global (theme/config) for:**
+
+- Form elements and interactive controls — inputs, buttons, toggles, checkboxes
+- Typography components used for consistency across the site
+- Anything where visual inconsistency between instances would be a bug
+
+The test: *should all instances of this component look the same?* If yes → theme. If instances are expected to look different → local override.
+
+---
+
+## Notes
+
+- `styleClassPassthrough` accepts a string or array — pass an array when combining multiple modifiers.
+- The modifier class lands on the component's root element, so nested element overrides need the
+  full selector path: `.card-core.featured-card .card-row-header { ... }`.
+- Keep the style block close to the component usage in the template — don't put it in a global stylesheet.

package/.claude/skills/component-prop-driven-container-layout.md

@@ -0,0 +1,42 @@
+# Prop-Driven Layout Variation via data-* + CSS @container
+
+## Overview
+
+How to vary CSS grid layout inside a `@container` query based on a component prop, using a `data-*` attribute as the CSS hook. Used in `ContentContainer` for the `justifyContent` prop.
+
+## Pattern
+
+### 1. Bind the prop as a class in the template
+
+```vue
+<div class="content-container" :class="justifyContent">
+```
+
+### 2. Use `&.class` selectors inside the `@container` query
+
+```css
+@container content-container (width >= 1092px) {
+  /* default (center) */
+  --gutter: 0;
+  --content-max-width: 1064px;
+  --justify-content: center;
+
+  &.start {
+    --gutter: 16px;
+    --justify-content: start;
+  }
+
+  &.end {
+    --gutter: 16px;
+    --justify-content: end;
+  }
+}
+```
+
+The `&` selector inside a `@container` rule refers to the element that carries the class.
+
+## Notes
+
+- **Why not `v-bind()` in `<style>`?** `v-bind()` injects a CSS custom property at the root element — it can't be targeted with a selector. A bound class gives you selector-level control, which is necessary when different values need different combinations of CSS property overrides. Prefer `:class="propName"` over `data-*` attributes for this — it's simpler.
+- **`grid-column: gutter` vs `grid-column: content` when gutter is 0**: When named grid column tracks are 0px wide, `gutter-start`/`gutter-end` and `content-start`/`content-end` resolve to the same positions. A child spanning `gutter` and one spanning `content` are visually identical. You can safely use `grid-column: content` uniformly and remove conditional `grid-column` overrides.
+- This pattern works with standard CSS nesting — no preprocessor required.

package/.claude/skills/components/accordian-core.md

@@ -0,0 +1,159 @@
+# AccordianCore Component
+
+## Overview
+
+`AccordianCore` renders a group of `ExpandingPanel` components. When a shared `name` prop is supplied, the native `<details>` behaviour ensures only one panel can be open at a time. Content is filled via **indexed dynamic slots** — one set per panel, driven by `itemCount`.
+
+---
+
+## Dynamic slot pattern
+
+For `itemCount="3"` the following slots exist:
+
+| Slot | Purpose |
+|------|---------|
+| `#accordian-0-summary` | Clickable label for panel 0 |
+| `#accordian-0-icon` | Custom toggle icon for panel 0 (optional) |
+| `#accordian-0-content` | Expandable content for panel 0 |
+| `#accordian-1-summary` | Clickable label for panel 1 |
+| `#accordian-1-icon` | Custom toggle icon for panel 1 (optional) |
+| `#accordian-1-content` | Expandable content for panel 1 |
+| … | … |
+
+**Rules:**
+- Slots are **zero-indexed**: first panel = `accordian-0-*`, last = `accordian-{itemCount - 1}-*`.
+- `accordian-{n}-summary` and `accordian-{n}-content` are the primary slots — always provide these.
+- `accordian-{n}-icon` is optional. When omitted, the default `ExpandingPanel` caret icon is used.
+- Always keep `itemCount` in sync with the number of slot sets you provide.
+
+---
+
+## Props reference
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| `name` | `string` | `undefined` | Shared `name` passed to every `ExpandingPanel`. When set, native `<details>` grouping means only one panel can be open at a time. Omit for independent panels. |
+| `itemCount` | `number` | `0` | Number of `ExpandingPanel` components to render. |
+| `animationDuration` | `number` | `300` | Expand/collapse animation duration in ms, forwarded to every panel. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `.display-accordian` element. |
+
+---
+
+## Usage examples
+
+### Basic accordion (exclusive open)
+
+```vue
+<AccordianCore name="faq" :item-count="3" :animation-duration="300">
+  <template #accordian-0-summary><span>What is your returns policy?</span></template>
+  <template #accordian-0-content>
+    <p>You can return any item within 30 days of purchase.</p>
+  </template>
+
+  <template #accordian-1-summary><span>How long does delivery take?</span></template>
+  <template #accordian-1-content>
+    <p>Standard delivery takes 3–5 working days.</p>
+  </template>
+
+  <template #accordian-2-summary><span>Do you ship internationally?</span></template>
+  <template #accordian-2-content>
+    <p>Yes — we ship to over 40 countries.</p>
+  </template>
+</AccordianCore>
+```
+
+Passing `name="faq"` groups all panels so only one can be open at a time.
+
+### Independent panels (no name — each opens freely)
+
+```vue
+<AccordianCore :item-count="2">
+  <template #accordian-0-summary><span>Panel A</span></template>
+  <template #accordian-0-content><p>Content A</p></template>
+
+  <template #accordian-1-summary><span>Panel B</span></template>
+  <template #accordian-1-content><p>Content B</p></template>
+</AccordianCore>
+```
+
+### Custom icons per panel
+
+```vue
+<AccordianCore :item-count="2">
+  <template #accordian-0-summary><span>Section one</span></template>
+  <template #accordian-0-icon><span>＋</span></template>
+  <template #accordian-0-content><p>Content one</p></template>
+
+  <template #accordian-1-summary><span>Section two</span></template>
+  <template #accordian-1-icon><span>＋</span></template>
+  <template #accordian-1-content><p>Content two</p></template>
+</AccordianCore>
+```
+
+### Programmatic slot rendering (many items)
+
+```vue
+<AccordianCore :item-count="items.length">
+  <template v-for="(item, i) in items" #[`accordian-${i}-summary`] :key="i">
+    <span>{{ item.title }}</span>
+  </template>
+  <template v-for="(item, i) in items" #[`accordian-${i}-content`] :key="i">
+    <p>{{ item.body }}</p>
+  </template>
+</AccordianCore>
+```
+
+---
+
+## CSS custom properties
+
+Override in a consuming component or theme block:
+
+| Property | Effect |
+|----------|--------|
+| Applied via `accordian-item` class on each `ExpandingPanel` | Panels animate `margin-block-end` and `border-radius` alongside the expand transition — duration follows `animationDuration`. |
+
+---
+
+## 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.
+
+```vue
+<AccordianCore :style-class-passthrough="['my-accordian']" :item-count="3">
+  ...
+</AccordianCore>
+
+<style>
+/* ─── AccordianCore local overrides ────────────────────────────────
+   Colours, borders, geometry only — do not override behaviour.
+   Delete this block if no overrides are needed.
+   ─────────────────────────────────────────────────────────────────── */
+.display-accordian {
+  &.my-accordian {
+    /* Geometry */
+    /* max-width: none; */ /* default is 600px — remove the width cap */
+
+    /* Panel-level overrides via the .accordian-item hook */
+    .accordian-item.expanding-panel {
+      /* Border */
+      /* border-block-end: 1px solid currentColor; */
+
+      /* Geometry */
+      /* border-radius: 0.8rem; */
+    }
+  }
+}
+</style>
+```
+
+---
+
+## Notes
+
+- `AccordianCore` always passes `style-class-passthrough="['accordian-item']"` to every inner `ExpandingPanel` — use `.accordian-item` as the hook for per-panel styling overrides.
+- For a single standalone expand/collapse panel, use `ExpandingPanel` directly instead.
+- Auto-imported in Nuxt — no manual import needed.
+- File: `app/components/02.molecules/expandable/accordian/AccordianCore.vue`