srcdev-nuxt-components 9.4.5 → 9.4.7

package/.claude/component-ledger/template.html

@@ -389,6 +389,7 @@ footer.note code{
           <th data-key="snippet" data-type="bool">Snippet</th>
           <th data-key="variants" data-type="bool" title="Uses a variants/ subfolder">Variants folder</th>
           <th data-key="legacy_props" data-type="bool" title="Still options-style defineProps({...}), not defineProps&lt;Props&gt;()">Legacy props</th>
+          <th data-key="story_args_bug" data-type="bool" title="A story destructures/refs Storybook's reactive args at setup-time, so most Controls-panel changes silently stop updating the rendered story after first render">Story args bug</th>
           <th data-key="score" data-type="num">Score</th>
         </tr>
       </thead>
@@ -398,6 +399,7 @@ footer.note code{
 
   <footer class="note">
     <p><strong>Methodology:</strong> "Styling doc", "Tests", "Story" and "Variants folder" are filesystem checks (<code>CONSUMER-STYLING.md</code>, a <code>tests/</code> dir, a <code>stories/</code> dir or <code>*.stories.ts</code> file, a <code>variants/</code> subfolder). "Skill doc" and "Snippet" match the component's kebab-case name against <code>.claude/skills/components/*.md</code> and <code>.vscode/*.code-snippets</code> &mdash; a small number of near-miss names may read as false negatives and are worth a manual glance before acting. "Score" is the count of the five doc/test/story/skill/snippet checks passed, out of 5, and is what "reference-quality" and "only incomplete" are based on. "Legacy props" is a source check for options-style <code>defineProps({...})</code> rather than <code>defineProps&lt;Props&gt;()</code> &mdash; like "Variants folder" it is <em>not</em> counted in the 5-point score (deliberately, so it stays visible instead of vanishing into an already-high score), but it does factor into "reference-quality" and "only incomplete", same as "Variants folder".</p>
+    <p style="margin-top:0.8rem;"><strong>"Story args bug"</strong> flags a story whose <code>setup()</code> destructures or spreads Storybook's <code>args</code> into local variables/refs at mount time (e.g. <code>const { modelValue, ...otherArgs } = args;</code> then <code>ref(modelValue)</code>). @storybook/vue3 mounts the story component once and mutates the same <code>args</code> object in place on every Controls change &mdash; it does not re-run <code>setup()</code> &mdash; so a destructured copy freezes at its initial value and most Controls silently stop updating the rendered story after first render. The fix is to bind the template straight to <code>args.x</code> (optionally through a <code>computed()</code> that strips non-prop extra args), never to a value copied out in <code>setup()</code>. Also not counted in the 5-point score, for the same reason as "Legacy props".</p>
     <p style="margin-top:0.8rem;"><strong>On <code>--_</code> vars:</strong> the public/private split is decided by consumer relevance, not reuse count &mdash; a private var is correct even used once, as long as the value has no plausible consumer override. This column is a raw count of <code>--_</code>-prefixed CSS custom properties per group; it is <em>not</em> scored and doesn't factor into "reference-quality" or "score." A high count is only a prompt to check each one by hand for a value that should have been public (a colour, size, or per-state variant with no override token) &mdash; the bug class the <code>ServicesCard</code> fix (CLAUDE.md pitfall #20) caught, not the presence of the prefix itself.</p>
     <p style="margin-top:0.8rem;"><strong>This page regenerates from <code>.claude/component-ledger/build.mjs</code></strong>, triggered whenever a staged commit touches <code>app/components/</code> (see the <code>create-commit-message</code> skill's hook). All numbers on this page, including the narrative above, are computed live from the latest scan &mdash; nothing here is hand-written prose that can drift out of date.</p>
   </footer>
@@ -437,10 +439,11 @@ statDefs.forEach(sd => {
 });
 
 // ---- dynamic narrative (every number computed from DATA, nothing hand-written) ----
-const fullyCompliant = DATA.filter(d => d.score === 5 && d.tier !== "NONE" && !d.variants && !d.legacy_props);
+const fullyCompliant = DATA.filter(d => d.score === 5 && d.tier !== "NONE" && !d.variants && !d.legacy_props && !d.story_args_bug);
 const unplaced = DATA.filter(d => d.tier === "NONE");
 const forkedVariants = DATA.filter(d => d.variants);
 const legacyProps = DATA.filter(d => d.legacy_props);
+const storyArgsBug = DATA.filter(d => d.story_args_bug);
 const noSkillAndUnplaced = unplaced.filter(d => !d.skill).length;
 const topPrivate = DATA.filter(d => d.priv_tokens > 0).sort((a,b) => b.priv_tokens - a.priv_tokens).slice(0, 3);
 
@@ -451,6 +454,7 @@ narrativeEl.innerHTML = `
   <p><strong>${unplaced.length} groups</strong> still sit loose at <code class="mono">app/components/</code> top level rather than inside a numbered tier. ${noSkillAndUnplaced} of those ${unplaced.length} also have no skill doc &mdash; an unplaced component tends to also be an undocumented one.</p>
   <p>${forkedVariants.length ? `<strong>${forkedVariants.length} group${forkedVariants.length===1?"":"s"}</strong> still fork${forkedVariants.length===1?"s":""} variants into a <code class="mono">variants/</code> subfolder &mdash; deprecated in favour of documenting the variation in the parent skill.md.` : `No component groups currently fork variants into a <code class="mono">variants/</code> subfolder.`}</p>
   <p>${legacyProps.length ? `<strong>${legacyProps.length} group${legacyProps.length===1?"":"s"}</strong> still use${legacyProps.length===1?"s":""} options-style <code class="mono">defineProps({...})</code> instead of <code class="mono">defineProps&lt;Props&gt;()</code> &mdash; this doesn't move the 5-point score, so it can hide behind an otherwise-complete-looking group.` : `No component groups currently use options-style defineProps.`}</p>
+  <p>${storyArgsBug.length ? `<strong>${storyArgsBug.length} group${storyArgsBug.length===1?"":"s"}</strong> ha${storyArgsBug.length===1?"s":"ve"} a story that destructures/refs Storybook's <code class="mono">args</code> at setup-time (${storyArgsBug.map(d => `<code class="mono">${d.compdir.split("/").pop()}</code>`).join(", ")}) &mdash; the Controls panel silently stops updating most props on that story after first render. This doesn't move the 5-point score either, for the same reason as "Legacy props".` : `No component groups currently have this Storybook Controls reactivity bug.`}</p>
   <p><strong>${topPrivate.length ? "On --_ vars:" : ""}</strong> ${topPrivate.length
     ? `the largest private-token surfaces right now are ${topPrivate.map(d => `<code class="mono">${d.compdir.split("/").pop()}</code> (${d.priv_tokens})`).join(", ")} &mdash; worth a manual look for a value that should have been public, per the corrected rule in the footer below. A high count on its own isn't a defect.`
     : ""}</p>
@@ -517,7 +521,7 @@ function tierLabel(t){ return t === "NONE" ? "unplaced" : t; }
 function render(){
   let rows = DATA.slice();
   if (activeTier !== "all") rows = rows.filter(d => d.tier === activeTier);
-  if (onlyIncomplete) rows = rows.filter(d => d.score < 5 || d.tier === "NONE" || d.variants || d.legacy_props);
+  if (onlyIncomplete) rows = rows.filter(d => d.score < 5 || d.tier === "NONE" || d.variants || d.legacy_props || d.story_args_bug);
   const q = searchEl.value.trim().toLowerCase();
   if (q) rows = rows.filter(d => d.compdir.toLowerCase().includes(q));
 
@@ -546,6 +550,7 @@ function render(){
       <td class="check">${check(d.snippet)}</td>
       <td class="check">${d.variants ? '<span class="no" style="opacity:1;color:var(--warn);">●</span>' : '<span class="no">–</span>'}</td>
       <td class="check">${d.legacy_props ? '<span class="no" style="opacity:1;color:var(--warn);">●</span>' : '<span class="no">–</span>'}</td>
+      <td class="check">${d.story_args_bug ? '<span class="no" style="opacity:1;color:var(--warn);">●</span>' : '<span class="no">–</span>'}</td>
       <td><span class="score-bar">${dots}</span></td>
     </tr>`;
   }).join("");

package/.claude/skills/components/breadcrumb.md

@@ -13,6 +13,7 @@ current page).
 |------|------|---------|----------|
 | `items` | `BreadcrumbItem[]` | — | **yes** |
 | `separator` | `string` | `"/"` | no |
+| `ariaLabel` | `string` | `"Breadcrumb"` | no — override for localisation |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | no |
 
 `BreadcrumbItem` is exported from `~/types/components/breadcrumb` (and re-exported from

package/.claude/skills/components/column-flow-grid.md

@@ -0,0 +1,93 @@
+---
+name: ColumnFlowGrid
+description: ColumnFlowGrid CSS multi-column (columns) text-flow layout — named dynamic slots (no count/data prop), itemMinWidth/gap/unit sizing, CSS token API. Not a true masonry — see MasonryGrid for that.
+type: reference
+---
+
+# ColumnFlowGrid
+
+## Overview
+
+`ColumnFlowGrid` lays out slot content using CSS `columns` (the "multi-column" text-flow module —
+the same mechanism newspaper-style text layouts use). Every slot is wrapped in a
+`.column-flow-grid-item` div with `break-inside: avoid` so an item never splits across columns.
+
+**Renamed from `MasonryGrid`** during this compliance pass — despite the old name, this component
+doesn't do anything masonry-specific: it's CSS `columns` and nothing else, with items simply
+flowing into whichever column is currently shortest **in DOM order**, not reordered for reading.
+See **Which one do I want?** below.
+
+## Which one do I want? (`ColumnFlowGrid` vs `MasonryGrid`)
+
+| | Technique | DOM/reading order | Column heights | Resize behaviour |
+|---|---|---|---|---|
+| `ColumnFlowGrid` | CSS `columns` | Column-major (as authored) | Uneven, CSS-native column-fill | Instant, native — no JS |
+| `MasonryGrid` | JS-measured, greedy shortest-column packing | Natural (as authored — no reorder needed) | Uneven, genuinely bin-packed | Animated (items slide into new positions) |
+
+Use **`ColumnFlowGrid`** when you just want cheap CSS-only column flow and don't need real
+masonry packing or a resize animation — nothing here is measured or JS-driven at all, so it's the
+lighter option. Use **`MasonryGrid`** (`.claude/skills/components/masonry-grid.md`) for genuine
+Pinterest-style packing (each item placed into whichever column is currently shortest) with
+animated reflow on resize.
+
+`MasonryGridOrdered` (a third, JS-measured sibling that predated this pair) has been retired — its
+implementation was absorbed into `MasonryGrid` directly. See `masonry-grid.md`'s migration history
+note for details.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tag` | `"div" \| "section" \| "article" \| "main"` | `"div"` | HTML element rendered as the root. |
+| `itemMinWidth` | `number` | `300` | Minimum column width in pixels — drives `columns: auto <value>px`. |
+| `gap` | `number` | `1.2` | Gap between columns/items, in `unit`. |
+| `unit` | `string` | `"rem"` | CSS unit applied to `gap`. |
+| `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
+
+## Slot API
+
+Any named slot is accepted — there are no declared slot names, and **no count/data prop to keep
+in sync**. The component iterates `$slots` and wraps each in a `.column-flow-grid-item`:
+
+```vue
+<ColumnFlowGrid>
+  <template #item-1>...</template>
+  <template #item-2>...</template>
+  <template #item-3>...</template>
+</ColumnFlowGrid>
+```
+
+Slot names can be anything (`item-1`/`item-2` is just a convention, matching `AutoGrid`).
+
+## Basic usage
+
+```vue
+<ColumnFlowGrid :item-min-width="280" :gap="1.6">
+  <template v-for="(photo, i) in photos" :key="photo.id" #[`item-${i}`]>
+    <img :src="photo.src" :alt="photo.alt" />
+  </template>
+</ColumnFlowGrid>
+```
+
+## CSS Token Customization
+
+| Token | Falls back to | Controls |
+|---|---|---|
+| `--column-flow-grid-item-border-colour` | `var(--theme-border)` | Outline colour around each item |
+| `--column-flow-grid-item-padding` | `1.2rem` | Inner padding of each item |
+
+Column width and gap are controlled via the `itemMinWidth`/`gap`/`unit` props, not CSS custom
+properties, since they need JS-computed values rather than being purely CSS-driven. See
+`CONSUMER-STYLING.md` in the component folder.
+
+## Notes
+
+- **Renamed from `MasonryGrid`** (2026-09-13) — see **Which one do I want?** above for why. If you
+  have consumer code importing this as `MasonryGrid`, it needs updating to `ColumnFlowGrid`; the
+  props and behaviour are otherwise unchanged. CSS classes/tokens were renamed to match
+  (`masonry-grid-*` → `column-flow-grid-*`).
+- **Column count is not fixed**: `columns: auto <itemMinWidth>` lets the browser decide how many
+  columns fit — there's no `columnCount` prop. Use `itemMinWidth` to influence it.
+- Item ordering is left-to-right by column-fill in `columns` layout (an item goes into the current
+  shortest column), not top-to-bottom reading order — be aware of this if visual order matters for
+  the specific content being laid out. This is the exact distinction `MasonryGrid` exists to solve.

package/.claude/skills/components/content-docs.md

@@ -18,6 +18,8 @@
 | `docsNavLabel` | `string` | `"Navigation"` | Heading text for the `docsNav` panel's `#summary`. |
 | `docsPageNavLabel` | `string` | `"On this page"` | Heading text for the `docsPageNav` panel's `#summary`. |
 | `panelVariant` | `"modern" \| "classic"` | `"classic"` | Which panel component renders `docsNav`/`docsPageNav`: `ExpandingPanel` (`"modern"`) or `ExpandingPanelClassic` (`"classic"`, default). `"modern"` is known not to work correctly on WebKit — the mobile nav (which relies on `contentIsOnTop`) becomes unreachable there. See CLAUDE.md pitfall #19. |
+| `docsNavAriaLabel` | `string` | `"Docs navigation"` | aria-label on the `docsNav` `<nav>` landmark — override for localisation. |
+| `docsPageNavAriaLabel` | `string` | `"On this page"` | aria-label on the `docsPageNav` `<nav>` landmark — override for localisation. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the root `.content-docs` element. |
 
 `DocsNavItem` (from `~/types/components`):

package/.claude/skills/components/display-tooltip-defined.md

@@ -20,6 +20,9 @@ directly when you need full control over the popover's content.
 |------|------|---------|-------------|
 | `tooltipId` | `string` | `""` | Base id for the popover. Prefixed with `nuxt-tooltip-` when provided; auto-generated via `useId()` (also prefixed) when omitted. |
 | `contentText` | `TooltipContentText` | `{}` | Title/body/action content. Each field is optional — omitted fields render nothing. |
+| `triggerAriaLabel` | `string` | `"Toggle the popover"` | Forwarded to the underlying `DisplayTooltip`'s `triggerAriaLabel` — override for localisation. |
+| `closeButtonText` | `string` | `"Close"` | Visible text on the close button — override for localisation. |
+| `closeButtonAriaLabel` | `string` | `"Close tool tip"` | aria-label on the close button — override for localisation. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the underlying `DisplayTooltip` root element. |
 
 `TooltipContentText` is exported from `~/types/components`:

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

@@ -24,6 +24,7 @@ requirement, same caution as `DeepExpandingMenu`'s equivalent gap.
 |------|------|---------|-------------|
 | `tooltipId` | `string` | `""` | Id linking the trigger button (`popovertarget`) to the popover panel (`id`). Auto-generated via `useId()` when omitted. |
 | `hideTrigger` | `boolean` | `false` | Visually hides the trigger button (kept in the DOM, not removed) — e.g. when an equivalent trigger is supplied via the `triggerContent` slot. |
+| `triggerAriaLabel` | `string` | `"Toggle the popover"` | aria-label on the trigger button — override for localisation. |
 | `styleClassPassthrough` | `string \| string[]` | `[]` | Extra classes applied to the root element. |
 
 ## Slots

package/.claude/skills/components/entry-animation.md

@@ -0,0 +1,88 @@
+# EntryAnimation Component
+
+## Overview
+
+`EntryAnimation` wraps slot content in a configurable tag and applies one of three CSS
+scroll-driven entry-animation utility classes (`entry-slide-in`, `entry-zoom-reveal`,
+`entry-exit-blur` — see `.claude/skills/css-animation-utilities.md`). It has no styling of its
+own beyond applying the class; the animation keyframes/timeline live in the shared
+`06.utility-classes/animations` stylesheet.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:animation-type`, `:skip-animation`.
+
+| Prop (template form)       | Type                                                    | Default          | Notes                                                                 |
+| --------------------------- | -------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------- |
+| `:tag`                      | `"div" \| "section" \| "article" \| "aside"`             | `"div"`           | Root element tag.                                                     |
+| `:animation-type`           | `"entry-slide-in" \| "entry-zoom-reveal" \| "entry-exit-blur"` | `"entry-slide-in"` | Which utility animation class to apply.                              |
+| `:skip-animation`           | `boolean`                                                 | `false`           | Renders with no animation class at all — see **Skipping the animation** below. |
+| `:style-class-passthrough`  | `string \| string[]`                                      | `[]`              | Extra CSS classes applied to the root element; always applied regardless of `skipAnimation`. |
+
+---
+
+## Slots
+
+| Slot      | Notes                                  |
+| --------- | ---------------------------------------- |
+| `default` | The content to animate in.               |
+
+---
+
+## Skipping the animation
+
+The common case in a `v-for` loop over a list of cards/sections is that the **first** item is
+already above the fold — animating it in only delays content the visitor can already see when the
+page loads. Before `skipAnimation` existed, the only way to handle this was swapping the whole
+component out for a plain tag per-item:
+
+```vue
+<!-- ❌ Old workaround — loses tag/styleClassPassthrough consistency for item 0 -->
+<component :is="index === 0 ? 'div' : EntryAnimation">
+  ...
+</component>
+```
+
+Use `skip-animation` instead — it keeps the same component, tag, and `styleClassPassthrough` for
+every item, it just omits the animation class for the ones that don't need it:
+
+```vue
+<EntryAnimation
+  v-for="(item, index) in items"
+  :key="item.id"
+  :skip-animation="index === 0"
+  animation-type="entry-slide-in"
+>
+  <template #default>
+    <!-- item content -->
+  </template>
+</EntryAnimation>
+```
+
+---
+
+## CSS Token Customization
+
+None — this component has no `--entry-animation-*` tokens or CSS of its own. The animation
+keyframes, timing, and `prefers-reduced-motion` guard live in the shared utility class
+(`entry-slide-in`/`entry-zoom-reveal`/`entry-exit-blur`), not in this component.
+
+---
+
+## Accessibility
+
+- All three animation utility classes are already scoped inside `@media (prefers-reduced-motion:
+  no-preference)` at the CSS level — a visitor with reduced motion enabled sees the content with no
+  animation, same as `skip-animation`. `skip-animation` is for a layout/UX decision (already
+  visible above the fold), not a substitute for the reduced-motion guard.
+
+---
+
+## Notes
+
+- **No animation reactivity**: `animationType`/`skipAnimation` are read once at mount to toggle the
+  utility class — changing either prop after mount does not currently re-toggle the class. This
+  matches the component's existing usage pattern (animation type is always set once per instance,
+  never swapped at runtime); flag it if a future consumer needs runtime toggling.

package/.claude/skills/components/input-copy.md

@@ -13,6 +13,8 @@
 | Prop (template form)       | Type                   | Default          | Notes                                                        |
 | -------------------------- | ---------------------- | ---------------- | ------------------------------------------------------------ |
 | `:value`                   | `string`               | (required)       | The text to copy to clipboard (e.g., license key, API token).|
+| `:id`                      | `string`               | auto-generated   | Id applied to the input. Only pass one if something needs to target this input directly. |
+| `:name`                    | `string`               | falls back to `id` | Name applied to the input. Falls back to the resolved `id` (auto-generated or explicit) when not provided. |
 | `:label`                   | `string`               | (optional)       | Short label for the field; used in aria-label if ariaLabel not set. |
 | `:aria-label`              | `string`               | (optional)       | Custom aria-label for the input; overrides label.           |
 | `:description`             | `string`               | (optional)       | Helper text displayed below the input.                       |

package/.claude/skills/components/input-text-core.md

@@ -0,0 +1,186 @@
+# InputTextCore Component
+
+## Overview
+
+`InputTextCore` is the low-level native `<input>` primitive for the `05.forms` text-input family.
+It renders a single styled text-like input with left/right icon slots, focus/dirty state models,
+and numeric-pattern validation for `inputmode="numeric"`. It has no label, description, or error
+message rendering of its own — those are composed by the wrapper variants below.
+
+Most consumers should reach for one of the **Variants** rather than `InputTextCore` directly.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:input-variant`, `:aria-describedby`.
+
+| Prop (template form)       | Type                                                         | Default     | Notes                                                                 |
+| --------------------------- | ------------------------------------------------------------ | ----------- | ---------------------------------------------------------------------- |
+| `:type`                     | `"text" \| "email" \| "password" \| "number" \| "tel" \| "url" \| "date"` | `"text"`    | Native input type.                                                     |
+| `:inputmode`                | `"text" \| "email" \| "tel" \| "url" \| "search" \| "numeric" \| "none" \| "decimal"` | `"text"`    | Sets virtual keyboard hint; `"numeric"` also enables pattern validation. |
+| `:maxlength`                | `number`                                                      | `255`       | Native `maxlength`.                                                   |
+| `:min`                      | `string \| number`                                            | (optional)  | Passed straight through to the native input — e.g. earliest allowed date for `type="date"`, or lowest number for `type="number"`. Use an ISO date string (`"2026-01-01"`) for `type="date"`. |
+| `:max`                      | `string \| number`                                            | (optional)  | Same as `min`, for the upper bound.                                   |
+| `:id`                       | `string`                                                      | (required)  | Applied to the native input.                                          |
+| `:name`                     | `string`                                                      | (required)  | Applied to the native input.                                          |
+| `:required`                 | `boolean`                                                     | `false`     | Native `required`.                                                    |
+| `:placeholder`              | `string`                                                      | `""`        | Native placeholder.                                                   |
+| `:field-has-error`          | `boolean`                                                     | `false`     | Drives `.error` class, `aria-invalid`, and forces `theme` to `"error"`. |
+| `:style-class-passthrough`  | `string \| string[]`                                          | `[]`        | Extra CSS classes applied to the wrapper.                             |
+| `:theme`                    | `FormUiTheme`                                                 | `"default"` | Overridden to `"error"` internally when `fieldHasError` is true.       |
+| `:aria-describedby`         | `string`                                                      | `""`        | Forwarded to the native input.                                        |
+| `:input-variant`            | `"normal" \| "outlined" \| "underlined"`                      | `"normal"`  | Visual style — border box vs. underline.                              |
+
+### v-models
+
+| Model             | Type      | Notes                                                     |
+| ----------------- | --------- | ---------------------------------------------------------- |
+| `v-model`          | `string`  | The input value.                                            |
+| `v-model:is-dirty` | `boolean` | Set to `true` once the wrapper variant detects a non-empty value at mount or on change. |
+| `v-model:is-active`| `boolean` | Tracks focus state (`focusin`/`focusout`).                   |
+
+---
+
+## Slots
+
+| Slot    | Notes                                                                 |
+| ------- | ---------------------------------------------------------------------- |
+| `left`  | Rendered before the input, inside the bordered wrapper (e.g. an icon or `InputButtonCore variant="inline"`). |
+| `right` | Rendered after the input, inside the bordered wrapper.                 |
+
+---
+
+## CSS Token Customization
+
+All `--input-text-*` tokens can be overridden at global, page, or instance scope, each falling back
+to the shared `--theme-*`/`--theme-input-*` tokens every other themed form component also uses. See
+`CONSUMER-STYLING.md` in the component directory for the full token table.
+
+**Common tokens:**
+- `--input-text-surface` — wrapper background
+- `--input-text-border` / `--input-text-border-hover` / `--input-text-border-focus` — border/outline colour
+- `--input-text-color` — input text colour
+- `--input-text-placeholder-color` — placeholder colour
+
+---
+
+## Using `min`/`max` for a native date picker
+
+`type="date"` plus `min`/`max` is the standard way to stop the browser's native date picker from
+offering dates outside an allowed range — e.g. preventing a booking date in the past:
+
+```vue
+<InputTextCore
+  id="appointment-date"
+  name="appointmentDate"
+  type="date"
+  v-model="appointmentDate"
+  :min="new Date().toISOString().split('T')[0]"
+  max="2027-12-31"
+/>
+```
+
+`min`/`max` are passed straight through with no validation of their own — the browser enforces the
+range in its native picker/typed-entry UI. Pair with server-side validation; a native `min`/`max`
+constraint is a UX affordance, not a substitute for validating the submitted value.
+
+---
+
+## Variants
+
+The `variants/` folder composes `InputTextCore` with `InputLabel`, `InputDescription`, and
+`InputError` for the common "labelled field" case. Each forwards `min`/`max` straight through if
+you pass them.
+
+### InputTextWithLabel
+
+The general-purpose labelled text field — supports every `InputTypesText` value including
+`"date"`.
+
+```vue
+<InputTextWithLabel
+  v-model="appointmentDate"
+  id="appointment-date"
+  name="appointmentDate"
+  type="date"
+  label="Appointment date"
+  :min="new Date().toISOString().split('T')[0]"
+  max="2027-12-31"
+  :error-message="errors.appointmentDate"
+  :field-has-error="!!errors.appointmentDate"
+/>
+```
+
+Props: same `type`/`inputmode`/`maxlength`/`min`/`max`/`name`/`placeholder`/`label`/`errorMessage`/
+`fieldHasError`/`required`/`styleClassPassthrough`/`theme`/`inputVariant` as `InputTextCore`, plus
+`label: string` (required) and `errorMessage: object | string` (required — pass `""` if unused).
+Slots: `left`, `right`, `descriptionHtml`, `descriptionText`.
+
+### InputPasswordWithLabel
+
+Adds a show/hide toggle button (`InputButtonCore variant="inline"` in the `right` slot) that swaps
+`type` between `"password"` and `"text"`.
+
+```vue
+<InputPasswordWithLabel
+  v-model="password"
+  name="password"
+  label="Password"
+  :error-message="errors.password"
+  :field-has-error="!!errors.password"
+  show-password-text="Show password"
+  hide-password-text="Hide password"
+/>
+```
+
+Extra props: `showPasswordText` (default `"Show password"`) and `hidePasswordText` (default
+`"Hide password"`) — the toggle button's accessible name in each state. Pass translated strings
+here for a non-English consumer app; there is no built-in i18n framework dependency.
+
+### InputTextAsNumberWithLabel
+
+A numeric stepper: left/right `InputButtonCore variant="inline"` buttons decrement/increment the
+value by `step`, disabled once `min`/`max` is reached.
+
+```vue
+<InputTextAsNumberWithLabel
+  v-model="quantity"
+  name="quantity"
+  label="Quantity"
+  :min="1"
+  :max="99"
+  :step="1"
+  step-down-text="Decrease quantity"
+  step-up-text="Increase quantity"
+>
+  <template #left>−</template>
+  <template #right>+</template>
+</InputTextAsNumberWithLabel>
+```
+
+Extra props: `min: number` (required), `max: number` (required), `step?: number` (default `1`),
+`stepDownText`/`stepUpText` (default `"Step down"`/`"Step up"`) — the decrement/increment buttons'
+accessible names. Requires `left`/`right` slot content for the step icons (no default icon).
+
+---
+
+## Accessibility
+
+- `field-has-error` sets `aria-invalid="true"` and forces the error theme, independent of what
+  `theme` was passed.
+- `inputmode="numeric"` adds a `pattern="[0-9]+"` and blocks non-numeric `beforeinput` edits that
+  would fail it.
+- Focus is tracked via native `focusin`/`focusout`, not a custom keyboard handler — `:focus-visible`
+  styling is preserved.
+- The password/number variants give their icon-only toggle/step buttons a real accessible name via
+  `InputButtonCore`'s `buttonText` (visually hidden via `.sr-only` when an icon-only slot is used).
+
+---
+
+## Notes
+
+- **No built-in label/error rendering**: `InputTextCore` alone renders no `<label>` or error text —
+  use a variant, or compose your own wrapper the same way they do.
+- **`min`/`max` need matching `type`**: they're inert on `type="text"`/`"email"`/etc. — only
+  `"date"` and `"number"` (native range-constrained types) act on them.

package/.claude/skills/components/marquee-scroller.md

@@ -0,0 +1,130 @@
+---
+name: MarqueeScroller
+description: MarqueeScroller infinite horizontal logo/badge scroller — props, dynamic per-item slots, accessibility controls, CSS tokens, consumer styling
+type: reference
+---
+
+# MarqueeScroller
+
+## Overview
+
+`MarqueeScroller` renders an infinite horizontal scroller for small repeating items — client
+logos, badges, testimonial avatars. The track is duplicated once so the loop is seamless
+(`marquee-group` renders twice: once real, once `aria-hidden="true"`), and the whole thing pauses
+automatically on hover, on keyboard focus, and when the user has `prefers-reduced-motion` set.
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `animationRuntime` | `string` | `"40s"` | CSS `animation-duration` for one full loop of the track. |
+| `reverse` | `boolean` | `false` | Reverses the scroll direction. |
+| `marqueeData` | `MarqueeItem[]` (`{ id: number; content: string }[]`) | `[]` | The items to render. Each item's `id` names the slot that renders its markup. `content` is not rendered by the component itself — it's a convenience field for the consumer to key off inside the slot. |
+| `itemConfig` | `MarqueeItemConfig` (`{ width?, height?, gap? }`) | `{ width: "50px", height: "50px", gap: "16px" }` | Item box size and the gap between items. Also sets the track height. |
+| `ariaLabel` | `string` | `"Scrolling content"` | `aria-label` on the root region — override for localisation. |
+| `ariaDescription` | `string` | `"Use spacebar to pause or play the animation."` | Screen-reader-only instructions rendered inside the region — override for localisation. |
+| `showControls` | `boolean` | `false` | Shows a visible pause/play button. Recommended (WCAG 2.2.2, Pause/Stop/Hide) whenever content scrolls automatically and indefinitely. |
+| `respectReducedMotion` | `boolean` | `true` | Auto-pauses and disables the animation for users with `prefers-reduced-motion: reduce`, and pauses on keyboard focus. |
+| `playIcon` | `string` | `"mdi:play"` | Iconify icon name shown on the control button while paused. Ignored if the `toggle-icon` slot is used. |
+| `pauseIcon` | `string` | `"mdi:pause"` | Iconify icon name shown on the control button while playing. Ignored if the `toggle-icon` slot is used. |
+| `playLabel` | `string` | `"Play animation"` | Control button `aria-label` while paused — override for localisation. |
+| `pauseLabel` | `string` | `"Pause animation"` | Control button `aria-label` while playing — override for localisation. |
+
+Import the item types from the library's type exports when building `marqueeData`/`itemConfig`
+outside the component:
+
+```ts
+import type { MarqueeItem, MarqueeItemConfig } from "srcdev-nuxt-components";
+```
+
+## Slots
+
+One dynamically-named slot per `marqueeData` entry, named after that item's `id`:
+
+```vue
+<MarqueeScroller :marquee-data="[{ id: 1, content: 'logo-a' }, { id: 2, content: 'logo-b' }]">
+  <template #1>
+    <img src="/logos/a.svg" alt="Logo A" />
+  </template>
+  <template #2>
+    <img src="/logos/b.svg" alt="Logo B" />
+  </template>
+</MarqueeScroller>
+```
+
+Each slot is rendered twice (once in the visible group, once in the `aria-hidden` duplicate group)
+so the loop wraps seamlessly — don't put anything with side effects or unique ids inside a slot.
+
+`toggle-icon` (scoped with `{ isPaused: boolean }`) replaces the control button's icon entirely —
+use this instead of `playIcon`/`pauseIcon` when an Iconify name isn't enough (custom SVG, a
+different icon set):
+
+```vue
+<MarqueeScroller show-controls>
+  <template #toggle-icon="{ isPaused }">
+    <Icon :name="isPaused ? 'lucide:play' : 'lucide:pause'" />
+  </template>
+</MarqueeScroller>
+```
+
+## Accessibility behaviour
+
+- The root is `role="region"` with `tabindex="0"` so it's independently focusable.
+- Spacebar toggles pause/play while the region is focused. Arrow keys do nothing — there is no
+  manual-stepping behaviour, so the default `ariaDescription` doesn't claim one (fixed 2026-09-08;
+  it previously announced "arrow keys ... for manual control" with no implementation behind it).
+- Focusing the region pauses the animation when `respectReducedMotion` is `true` (the default);
+  blurring resumes it unless the user prefers reduced motion.
+- Hovering anywhere over the scroller pauses the track and applies
+  `--marquee-scroller-group-hover-filter` (default `grayscale(1)`) to every item; hovering an
+  individual item restores it via `--marquee-scroller-item-hover-filter` (default `grayscale(0)`).
+- `aria-live` switches to `"polite"` while paused so screen readers announce the paused content.
+- The duplicate track group is always `aria-hidden="true"`.
+- All user-visible copy (`ariaLabel`, `ariaDescription`, `playLabel`, `pauseLabel`) is a plain
+  string prop with an English default — there's no i18n framework dependency in this library, so
+  pass translated strings from the consumer's own i18n solution.
+
+## Basic usage
+
+```vue
+<MarqueeScroller
+  :marquee-data="[
+    { id: 1, content: 'acme' },
+    { id: 2, content: 'globex' },
+  ]"
+  :item-config="{ width: '120px', height: '60px', gap: '24px' }"
+  show-controls
+>
+  <template #1><img src="/logos/acme.svg" alt="Acme" /></template>
+  <template #2><img src="/logos/globex.svg" alt="Globex" /></template>
+</MarqueeScroller>
+```
+
+## CSS custom properties
+
+See `CONSUMER-STYLING.md` in this component's folder for the full public token table. Item size,
+gap, and animation duration are prop-driven (`itemConfig`, `animationRuntime`), not tokens, since
+they also drive the component's own layout math. The `prefers-contrast: high` override's
+`ButtonFace`/`ButtonText` colours are deliberately not tokens (they track the OS high-contrast
+theme); only its border width is (`--marquee-scroller-control-border-width`).
+
+## Seamless loop math
+
+The track duplicates `marqueeData` into two `.marquee-group` children so the loop can wrap without
+a visible cut. The animation must shift the track by exactly one group's width plus its connecting
+gap — not `translateX(-50%)`, which overshoots short of the seam once the track's own `gap`
+between the two groups is added to its total width. This is computed as a private
+`--_track-shift: calc(itemCount * (itemWidth + gap))` token and used in the `marqueeMove`
+keyframe. Fixed 2026-09-08 — the original `-50%` version produced a small but visible gap/overlap
+at the loop point once more than a couple of items were in `marqueeData`.
+
+## Auto-repeating marqueeData in a wide container
+
+If a single pass of `marqueeData` is narrower than the container (few items, or a full-bleed
+section on a wide viewport), the loop briefly shows empty space before snapping back into view —
+the visible track only spans as wide as the content, not the container. On mount (and on
+container resize, via `ResizeObserver`), the component measures one rendered group's `scrollWidth`
+against the root element's `offsetWidth` and repeats `marqueeData` internally (`repeatCount`)
+enough times per `.marquee-group` so a single group's width always covers the container. This is
+transparent to consumers — it doesn't change `marqueeData` or any prop, only how many times each
+item's slot is rendered internally. Fixed 2026-09-08.