srcdev-nuxt-components 9.1.42 → 9.1.44

package/.claude/settings.json

@@ -26,7 +26,9 @@
       "Bash(node -e ':*)",
       "Bash(git ls-tree *)",
       "Bash(node -p \"require\\('./package.json'\\).version\")",
-      "Bash(git status *)"
+      "Bash(git status *)",
+      "Bash(cp /Users/simoncornforth/websites/nuxt-components/.claude/skills/components/data-grid.md /Users/simoncornforth/websites/nuxt-components/.claude/skills/components/auto-grid.md)",
+      "Bash(rm /Users/simoncornforth/websites/nuxt-components/.claude/skills/components/data-grid.md)"
     ],
     "additionalDirectories": []
   }

package/.claude/skills/components/{data-grid.md → auto-grid.md}

@@ -1,8 +1,8 @@
-# DataGrid Component
+# AutoGrid Component
 
 ## Overview
 
-`DataGrid` is a responsive auto-fit CSS grid wrapper. It renders whatever named slots the consumer provides, auto-fitting columns to a minimum of `250px` each. Column count and gap are controlled via CSS custom properties, making layout adjustments a single-line style override rather than a prop change.
+`AutoGrid` is a responsive auto-fit CSS grid wrapper. It renders whatever named slots the consumer provides, auto-fitting columns to a minimum of `250px` each. Column count and gap are controlled via CSS custom properties, making layout adjustments a single-line style override rather than a prop change.
 
 ---
 
@@ -11,21 +11,21 @@
 Pass any number of named slots — the component renders each one in document order inside the grid.
 
 ```vue
-<DataGrid>
+<AutoGrid>
   <template #item-1><StatCard label="Revenue" value="£24,500" /></template>
   <template #item-2><StatCard label="Clients" value="142" /></template>
   <template #item-3><StatCard label="Bookings" value="38" /></template>
-</DataGrid>
+</AutoGrid>
 ```
 
 When filling from a data array, use a dynamic slot name in a `v-for`:
 
 ```vue
-<DataGrid>
+<AutoGrid>
   <template v-for="(item, i) in stats" #[`item-${i}`] :key="i">
     <StatCard :label="item.label" :value="item.value" />
   </template>
-</DataGrid>
+</AutoGrid>
 ```
 
 ---
@@ -34,10 +34,10 @@ When filling from a data array, use a dynamic slot name in a `v-for`:
 
 > **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:style-class-passthrough`.
 
-| Prop (template form) | Type | Default | Notes |
-|---|---|---|---|
-| `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | Use a semantic tag for page landmark regions. |
-| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes on the root element. |
+| Prop (template form)       | Type                                        | Default | Notes                                         |
+| -------------------------- | ------------------------------------------- | ------- | --------------------------------------------- |
+| `tag`                      | `"div" \| "section" \| "article" \| "main"` | `"div"` | Use a semantic tag for page landmark regions. |
+| `:style-class-passthrough` | `string \| string[]`                        | `[]`    | Extra CSS classes on the root element.        |
 
 ---
 
@@ -45,25 +45,27 @@ When filling from a data array, use a dynamic slot name in a `v-for`:
 
 Override these via `style` attribute or a `styleClassPassthrough` class in a consuming `<style>` block.
 
-| Property | Default | Notes |
-|---|---|---|
-| `--data-grid-columns` | `repeat(auto-fit, minmax(250px, 1fr))` | Full `grid-template-columns` value. Override to fix column count or change min width. |
-| `--data-grid-gap` | `1rem` | Grid gap between items. |
+| Property                  | Default  | Notes                                                                                    |
+| ------------------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `--auto-grid-min-col-size` | `250px` | Minimum column width; browser auto-fits as many columns as will fit.                    |
+| `--auto-grid-gap`          | `1rem`  | Grid gap between items.                                                                  |
 
 ### Fixed column count
 
+Override `grid-template-columns` directly — there is no single token for this:
+
 ```vue
-<DataGrid style="--data-grid-columns: repeat(3, 1fr); --data-grid-gap: 2.4rem;">
+<AutoGrid style="grid-template-columns: repeat(3, 1fr); --auto-grid-gap: 2.4rem;">
   ...
-</DataGrid>
+</AutoGrid>
 ```
 
 ### Narrower minimum item width
 
 ```vue
-<DataGrid style="--data-grid-columns: repeat(auto-fit, minmax(180px, 1fr));">
+<AutoGrid style="--auto-grid-min-col-size: 180px;">
   ...
-</DataGrid>
+</AutoGrid>
 ```
 
 ---
@@ -73,7 +75,7 @@ Override these via `style` attribute or a `styleClassPassthrough` class in a con
 ### Stat cards (default auto-fit)
 
 ```vue
-<DataGrid>
+<AutoGrid>
   <template #revenue>
     <div class="stat-card">
       <span class="stat-card-label">Revenue</span>
@@ -86,17 +88,17 @@ Override these via `style` attribute or a `styleClassPassthrough` class in a con
       <span class="stat-card-value">142</span>
     </div>
   </template>
-</DataGrid>
+</AutoGrid>
 ```
 
 ### Semantic section with auto aria-labelledby
 
 ```vue
-<DataGrid tag="section">
+<AutoGrid tag="section">
   <!-- aria-labelledby is wired automatically via useAriaLabelledById -->
   <template #item-1><div>Item 1</div></template>
   <template #item-2><div>Item 2</div></template>
-</DataGrid>
+</AutoGrid>
 ```
 
 ### Data-driven grid
@@ -105,20 +107,20 @@ Override these via `style` attribute or a `styleClassPassthrough` class in a con
 <script setup lang="ts">
 const stats = [
   { id: "revenue", label: "Revenue", value: "£24,500" },
-  { id: "clients", label: "Clients",  value: "142" },
+  { id: "clients", label: "Clients", value: "142" },
   { id: "bookings", label: "Bookings", value: "38" },
 ];
 </script>
 
 <template>
-  <DataGrid>
+  <AutoGrid>
     <template v-for="stat in stats" #[stat.id] :key="stat.id">
       <div class="stat-card">
         <span class="stat-card-label">{{ stat.label }}</span>
         <span class="stat-card-value">{{ stat.value }}</span>
       </div>
     </template>
-  </DataGrid>
+  </AutoGrid>
 </template>
 ```
 
@@ -137,19 +139,19 @@ See [component-aria-landmark.md](../component-aria-landmark.md) for the full lan
 ## Local style override scaffold
 
 ```vue
-<DataGrid :style-class-passthrough="['my-data-grid']">
+<AutoGrid :style-class-passthrough="['my-auto-grid']">
   ...
-</DataGrid>
+</AutoGrid>
 
 <style>
-/* ─── DataGrid local overrides ──────────────────────────────────────
+/* ─── AutoGrid local overrides ──────────────────────────────────────
    Use CSS custom properties for layout, not utility classes.
    Delete this block if no overrides are needed.
    ─────────────────────────────────────────────────────────────────── */
-.data-grid {
-  &.my-data-grid {
-    --data-grid-columns: repeat(auto-fit, minmax(200px, 1fr));
-    --data-grid-gap: 2rem;
+.auto-grid {
+  &.my-auto-grid {
+    --auto-grid-min-col-size: 200px;
+    --auto-grid-gap: 2rem;
   }
 }
 </style>
@@ -163,5 +165,5 @@ See [component-local-style-override.md](../component-local-style-override.md) fo
 
 - Auto-imported in Nuxt — no manual import needed.
 - Slot names can be anything — semantic (`#revenue`) or indexed (`#item-0`). Document order determines render order.
-- `--data-grid-columns` accepts any valid `grid-template-columns` value, including named tracks and `subgrid`.
-- The component does not impose a column count — `auto-fit` with `minmax` means the browser decides. Use `repeat(N, 1fr)` in `--data-grid-columns` to fix the count.
+- `--auto-grid-min-col-size` controls the minimum column width; `auto-fit` fills as many columns as will fit.
+- To fix the column count, override `grid-template-columns` directly (e.g. `style="grid-template-columns: repeat(3, 1fr)"`) — there is no single token for this.

package/.claude/skills/components/display-avatar.md

@@ -0,0 +1,187 @@
+# DisplayAvatar Component
+
+## Overview
+
+`DisplayAvatar` renders a circular avatar — either an image (via `NuxtImg`) or a text fallback showing initials derived from the `alt` prop. Optionally wraps in a `DisplayChip` to show a status indicator badge.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:style-class-passthrough`.
+
+| Prop (template form)       | Type                                      | Default  | Notes                                                              |
+| -------------------------- | ----------------------------------------- | -------- | ------------------------------------------------------------------ |
+| `as`                       | `string \| object`                        | `"span"` | Root element tag. Ignored when `chip` is set.                      |
+| `src`                       | `string`                                  | —        | Image URL. Renders `NuxtImg` when set; fallback text otherwise.   |
+| `alt`                       | `string`                                  | —        | Alt text for the image; also used to derive initials.             |
+| `text`                      | `string`                                  | —        | Override the auto-derived initials with an explicit string.       |
+| `size`                      | `"xs" \| "s" \| "md" \| "lg" \| "xl"`   | `"md"`   | Controls width, height, and font-size.                            |
+| `chip`                      | `boolean \| DisplayChipConfig`           | —        | Add a status chip. `true` uses defaults; pass a config object to customise. |
+| `:style-class-passthrough`  | `string \| string[]`                      | `[]`     | Extra CSS classes on the root element.                            |
+
+### Size dimensions
+
+| Size | Diameter | Font size |
+| ---- | -------- | --------- |
+| `xs` | 24px     | 0.75rem   |
+| `s`  | 32px     | 0.875rem  |
+| `md` | 40px     | 1rem      |
+| `lg` | 48px     | 1.125rem  |
+| `xl` | 56px     | 1.25rem   |
+
+---
+
+## Slots
+
+| Slot      | Purpose                                                              |
+| --------- | -------------------------------------------------------------------- |
+| `default` | Replaces the auto image/fallback content entirely.                  |
+| `icon`    | Appended inside the avatar (e.g. an icon overlay over the image). |
+
+---
+
+## Fallback text logic
+
+When `src` is not set, a `<span>` renders the fallback value:
+
+1. `text` prop — used as-is if provided.
+2. `alt` initials — first character of each word, capped at two characters.
+3. Empty string — if neither is set.
+
+```
+alt="John Doe"     → "JD"
+alt="Alice"        → "A"
+alt="Alice Bob C"  → "AB"
+text="?"           → "?"
+```
+
+---
+
+## Usage examples
+
+### Image avatar
+
+```vue
+<DisplayAvatar
+  src="/images/profile.jpg"
+  alt="Jane Smith"
+  size="lg"
+/>
+```
+
+### Initials fallback
+
+```vue
+<DisplayAvatar alt="Jane Smith" size="md" />
+<!-- renders: "JS" -->
+```
+
+### Custom text fallback
+
+```vue
+<DisplayAvatar text="?" size="xs" />
+```
+
+### Custom root element
+
+```vue
+<DisplayAvatar as="div" alt="Jane Smith" />
+```
+
+### With a status chip (default config)
+
+```vue
+<DisplayAvatar
+  src="/images/profile.jpg"
+  alt="Jane Smith"
+  :chip="true"
+/>
+```
+
+Default chip config: `{ size: "12px", maskWidth: "4px", offset: "0px", angle: "90deg" }`.
+
+### With a custom chip
+
+```vue
+<DisplayAvatar
+  src="/images/profile.jpg"
+  alt="Jane Smith"
+  :chip="{
+    size: '16px',
+    maskWidth: '2px',
+    offset: '4px',
+    angle: '45deg'
+  }"
+/>
+```
+
+Full `DisplayChipConfig` shape (pass directly as the `chip` value):
+
+```ts
+interface DisplayChipConfig {
+  size: string       // chip diameter, e.g. "12px"
+  maskWidth: string  // cutout ring width, e.g. "4px"
+  offset: string     // distance from avatar edge, e.g. "0px"
+  angle: string      // position around avatar (0–360deg), e.g. "45deg"
+  icon?: string      // Iconify icon name
+  label?: string     // short text (max 3 characters)
+}
+```
+
+### Default slot override
+
+```vue
+<DisplayAvatar size="xl">
+  <template #default>
+    <img src="/images/profile.jpg" alt="Jane Smith" class="avatar-image" />
+  </template>
+</DisplayAvatar>
+```
+
+### Icon slot
+
+```vue
+<DisplayAvatar alt="Jane Smith">
+  <template #icon>
+    <Icon name="bi:check-circle-fill" class="avatar-icon" />
+  </template>
+</DisplayAvatar>
+```
+
+---
+
+## Local style override scaffold
+
+```vue
+<DisplayAvatar
+  alt="Jane Smith"
+  :style-class-passthrough="['profile-avatar']"
+/>
+
+<style>
+/* ─── DisplayAvatar local overrides ────────────────────────────────
+   Scope by your wrapper class, then nest .display-avatar directly.
+   No :deep() needed (component styles are unscoped).
+   Delete this block if no overrides are needed.
+   ─────────────────────────────────────────────────────────────────── */
+.my-page-section {
+  .display-avatar {
+    &.profile-avatar {
+      /* custom overrides */
+    }
+  }
+}
+</style>
+```
+
+See [component-local-style-override.md](../component-local-style-override.md) for the full pattern.
+
+---
+
+## Notes
+
+- Auto-imported in Nuxt — no manual import needed.
+- When `chip` is set, the root element becomes `DisplayChip` and the `as` prop is ignored.
+- `class` and `style` are **not** declared as explicit props — they fall through to the root element automatically via Vue's attribute inheritance (`inheritAttrs: true`). Do not re-add them as props; doing so pulls them out of `$attrs` and breaks automatic inheritance.
+- `NuxtImg` is used for the image, so `@nuxt/image` must be installed in the consuming app.

package/.claude/skills/components/display-chip.md

@@ -0,0 +1,213 @@
+# DisplayChip Component
+
+## Overview
+
+`DisplayChip` renders a small status indicator dot (or icon/label badge) that is absolutely positioned on a parent element using CSS trigonometric functions. It works by applying a radial-gradient mask to the parent's content, creating a clean cutout behind the chip. Supports circle and square parent shapes.
+
+Used directly for standalone chip overlays, and internally by `DisplayAvatar` when its `chip` prop is set.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:style-class-passthrough`.
+
+| Prop (template form)       | Type                       | Default    | Notes                                              |
+| -------------------------- | -------------------------- | ---------- | -------------------------------------------------- |
+| `tag`                      | `"div" \| "span"`          | `"span"`   | Root element tag.                                  |
+| `shape`                    | `"circle" \| "square"`     | `"circle"` | Affects position maths — must match the parent shape. |
+| `:config`                  | `DisplayChipConfig`        | see below  | Controls chip geometry and optional content.       |
+| `:style-class-passthrough` | `string \| string[]`       | `[]`       | Extra CSS classes — use for status colour variants. |
+
+### DisplayChipConfig
+
+```ts
+interface DisplayChipConfig {
+  size: string       // chip dot diameter, e.g. "12px"
+  maskWidth: string  // cutout ring width around the chip, e.g. "4px"
+  offset: string     // extra distance from the parent edge, e.g. "0px"
+  angle: string      // position around the parent (0–360deg), e.g. "45deg"
+  icon?: string      // Iconify icon name rendered inside the chip
+  label?: string     // short text rendered inside the chip (max 3 characters)
+}
+```
+
+Default config: `{ size: "12px", maskWidth: "4px", offset: "0px", angle: "90deg" }`.
+
+### Angle reference
+
+| Angle    | Position     |
+| -------- | ------------ |
+| `0deg`   | Top          |
+| `45deg`  | Top-right    |
+| `90deg`  | Right        |
+| `135deg` | Bottom-right |
+| `180deg` | Bottom       |
+| `225deg` | Bottom-left  |
+| `270deg` | Left         |
+| `315deg` | Top-left     |
+
+---
+
+## Status colours
+
+Apply status via `styleClassPassthrough` — the component has built-in colour variants:
+
+| Class      | Colour                  |
+| ---------- | ----------------------- |
+| (none)     | `slategrey` (offline)   |
+| `online`   | `rgb(0, 255, 135)`      |
+| `idle`     | `rgb(255, 185, 51)`     |
+| `dnd`      | `rgb(255, 40, 80)`      |
+
+```vue
+<DisplayChip :style-class-passthrough="['online']">...</DisplayChip>
+```
+
+---
+
+## Label constraints
+
+- Max 3 characters. Longer values are silently truncated with a `console.warn`.
+- Font-size scales automatically with chip size via `--_font-size-adjust`:
+  - 1 char → `0.7 × size`
+  - 2 chars → `0.6 × size`
+  - 3 chars → `0.5 × size`
+
+---
+
+## Slots
+
+| Slot      | Purpose                                    |
+| --------- | ------------------------------------------ |
+| `default` | The host element the chip is positioned on. Must be a single block element. |
+
+---
+
+## Usage examples
+
+### Simple status dot on a circular avatar
+
+```vue
+<DisplayChip
+  shape="circle"
+  :config="{ size: '12px', maskWidth: '4px', offset: '0px', angle: '45deg' }"
+  :style-class-passthrough="['online']"
+>
+  <div class="avatar">SRC</div>
+</DisplayChip>
+```
+
+### Status dot on a square card thumbnail
+
+```vue
+<DisplayChip
+  shape="square"
+  :config="{ size: '10px', maskWidth: '3px', offset: '2px', angle: '135deg' }"
+  :style-class-passthrough="['idle']"
+>
+  <img src="/thumbnail.jpg" alt="Card thumbnail" />
+</DisplayChip>
+```
+
+### With an icon inside the chip
+
+```vue
+<DisplayChip
+  :config="{ size: '16px', maskWidth: '4px', offset: '0px', angle: '45deg', icon: 'bi:check-circle-fill' }"
+  :style-class-passthrough="['online']"
+>
+  <div class="avatar">SRC</div>
+</DisplayChip>
+```
+
+### With a label inside the chip
+
+```vue
+<!-- 1–3 characters only; longer values are truncated with a warning -->
+<DisplayChip
+  :config="{ size: '16px', maskWidth: '4px', offset: '0px', angle: '45deg', label: '+2' }"
+  :style-class-passthrough="['dnd']"
+>
+  <div class="avatar">SRC</div>
+</DisplayChip>
+```
+
+### Reactive config (QA panel / form pattern)
+
+```vue
+<script setup lang="ts">
+import type { DisplayChipConfig } from 'srcdev-nuxt-components/types/components'
+
+const size = ref(12)
+const angle = ref(45)
+
+const chipConfig = computed((): DisplayChipConfig => ({
+  size: `${size.value}px`,
+  maskWidth: '4px',
+  offset: '0px',
+  angle: `${angle.value}deg`,
+}))
+</script>
+
+<template>
+  <DisplayChip shape="circle" :config="chipConfig" :style-class-passthrough="['online']">
+    <div class="avatar">SRC</div>
+  </DisplayChip>
+</template>
+```
+
+### Via DisplayAvatar (recommended for avatar use cases)
+
+Prefer `DisplayAvatar` with its `chip` prop over wiring `DisplayChip` directly:
+
+```vue
+<DisplayAvatar
+  src="/images/profile.jpg"
+  alt="Jane Smith"
+  :chip="{ size: '12px', maskWidth: '4px', offset: '0px', angle: '45deg' }"
+  :style-class-passthrough="['online']"
+/>
+```
+
+See [display-avatar.md](./display-avatar.md) for the full API.
+
+---
+
+## Local style override scaffold
+
+```vue
+<DisplayChip
+  :config="chipConfig"
+  :style-class-passthrough="['my-chip']"
+>
+  <div class="avatar">SRC</div>
+</DisplayChip>
+
+<style>
+/* ─── DisplayChip local overrides ──────────────────────────────────
+   Scope by your wrapper class, then nest .display-chip-core directly.
+   No :deep() needed (component styles are unscoped).
+   Delete this block if no overrides are needed.
+   ─────────────────────────────────────────────────────────────────── */
+.my-page-section {
+  .display-chip-core {
+    &.my-chip {
+      /* override colour vars, e.g. */
+      --color-online: hotpink;
+    }
+  }
+}
+</style>
+```
+
+---
+
+## Notes
+
+- Auto-imported in Nuxt — no manual import needed.
+- `shape` must match the actual shape of the slot content — the position maths differs between `circle` (radius-based) and `square` (clamped corner-aware).
+- `config` values are geometric inputs to CSS `calc(cos())` / `calc(sin())` expressions. Pass them as strings with units (`"12px"`, `"45deg"`), not plain numbers.
+- The chip dot is rendered via `::after` pseudo-element; icon and label sit above it at `z-index: 2`.
+- The mask cutout is applied to all direct children of `.display-chip-core` except `.chip-icon` and `.chip-label` — ensure the host element is a direct child.
+- `DisplayChipConfig` and `DisplayChipProps` are both exported from the layer types. Use `DisplayChipConfig` when passing geometry values (the `config` prop). Use `DisplayChipProps` only if you need to pass the full component prop set (e.g. when building a wrapper component).

package/.claude/skills/css-animation-utilities.md

@@ -0,0 +1,87 @@
+# CSS Animation Utilities
+
+## Overview
+
+Scroll-driven animation utility classes bundled with the layer. Apply a class to any element to get a CSS-only, scroll-linked animation — no JavaScript required. All utilities use the [CSS Scroll-Driven Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline) spec (`animation-timeline: view()`).
+
+**Browser support**: Chrome 115+, Firefox 110+, Safari 18+. No polyfill exists — use `@supports` for graceful degradation where needed.
+
+All utilities are wrapped in `@media (prefers-reduced-motion: no-preference)` — animations are automatically disabled for users who prefer reduced motion.
+
+## Available classes
+
+### `.animation-scroller-x`
+
+Scales and fades items relative to their position in a **horizontal scroll container** (carousel, horizontal list). Items at the edges are small and faint; items at the centre are full size and opaque.
+
+```css
+animation-timeline: view(x);
+```
+
+| Position | `opacity` | `scale` |
+|---|---|---|
+| Edges (0 %, 100 %) | 0.25 | 0.5 |
+| Centre (35 %–65 %) | 1 | 1 |
+
+#### Usage
+
+```html
+<!-- Scrollable container — overflow-x must be auto or scroll -->
+<div class="carousel-track" style="overflow-x: auto; display: flex;">
+  <div class="animation-scroller-x">Item 1</div>
+  <div class="animation-scroller-x">Item 2</div>
+  <div class="animation-scroller-x">Item 3</div>
+</div>
+```
+
+The animation is driven by the element's position inside its nearest scrollport on the x-axis. Add `.animation-scroller-x` to each **child** — not the container.
+
+---
+
+### `.entry-zoom-reveal`
+
+Fades and zooms an element in as it scrolls into the vertical viewport (bottom 30 % inset to top 5 %).
+
+```html
+<div class="entry-zoom-reveal">Content revealed on scroll</div>
+```
+
+- `fill: both` — element stays hidden before entry, visible after exit
+
+---
+
+### `.entry-slide-in`
+
+Slides an element up from 200 px below as it scrolls into view.
+
+```html
+<div class="entry-slide-in">Slides up on scroll</div>
+```
+
+---
+
+### `.entry-exit-blur`
+
+Blurs an element as it enters and exits the vertical viewport; sharp in the centre (45 %–55 %).
+
+```html
+<div class="entry-exit-blur">Sharp in view, blurred at edges</div>
+```
+
+---
+
+### `.auto-rotate`
+
+Rotates an element 0 → 360 ° as it scrolls through the vertical viewport.
+
+```html
+<div class="auto-rotate">
+  <img src="/logo.svg" alt="" />
+</div>
+```
+
+## Notes
+
+- All classes use `animation-timeline: view()` (vertical) **except** `.animation-scroller-x` which uses `view(x)`.
+- The `scroller` keyframe name used by `.animation-scroller-x` is global — avoid re-declaring `@keyframes scroller` in your own CSS.
+- Utility classes are included automatically when you extend the layer — no explicit import needed in your app.