srcdev-nuxt-components 9.6.8 → 9.6.9

package/.claude/skills/component-compliance-checklist.md

@@ -25,7 +25,10 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
    **Existing component:** if it lives outside a tier, move it with `git mv`.
 2. **Props pattern** — `interface Props` + `withDefaults(defineProps<Props>(), {...})`, never
    options-style `defineProps({...})`. Include `styleClassPassthrough` and wire it through
-   `useStyleClassPassthrough()`. Consumer-facing data-shape types go in
+   `useStyleClassPassthrough()`, with a `watch` that calls `resetElementClasses` so it reacts to prop
+   changes. A Field wrapper applies its passthrough to its own root only: forwarding the same prop
+   to the inner control as well puts one consumer class on two elements (`InputNumberField`,
+   `InputRangeField`, fixed 2026-10-16). Consumer-facing data-shape types go in
    `app/types/components/<component-name>.d.ts` and are exported from `app/types/components/index.ts`
    (see `component-export-types.md`), not left inline in the `.vue` file.
 3. **CSS tokens** — audit every custom property in the component's `<style>` block against the
@@ -196,6 +199,10 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
    - Live-updating or auto-advancing content (carousels, marquees, auto-dismissing toasts) has a
      way to pause it, per WCAG 2.2.2 — a visible control, or pause-on-hover/focus at minimum.
    - `prefers-reduced-motion` is respected for any animation that isn't purely decorative.
+   - A mode that hides a native control's own indicator (a range thumb, a checkbox box, a caret)
+     draws its own visible state for the current value, and its interactive area isn't shrunk to a
+     sliver. `InputRange`'s markers mode hid the thumb with nothing in its place and left only a
+     2px line clickable, from its first commit until 2026-10-16; its 5/5 score didn't show it.
    - A component with a `tag` prop that can render a landmark uses `useAriaLabelledById`
      (`component-aria-landmark.md`), unless it falls back to `aria-label` when no heading is
      given: the composable can't do that and warns whenever a landmark has no heading. Then label
@@ -268,6 +275,10 @@ The ledger can't see items 6c, 9, 10, 11 and 14, so check those by hand.
       defaults to its min-content width and overflows a narrow column (`MultipleCheckboxes`,
       2026-10-16).
     - Element ids come from `useId()`, never from data values (rule `consumer/ids-from-useid.md`).
+    - Step buttons and any other script that changes a number round to the step's precision
+      (`toFixed`), clamp to `min`/`max`, and compare limits with `<=`/`>=`, never `===` (0.1 steps
+      drift to 0.30000000000000004, and an overshoot past an `===` check never disables the button).
+      Reference: `stepBy()` in `InputNumberField`.
     - Layout measured in script (connector lines, indicators) re-measures when any measured item
       resizes or changes class, not only when the container resizes (`measured-layout-observers.md`,
       pitfall #28).

package/.claude/skills/component-inline-action-button.md

@@ -105,6 +105,6 @@ changed visible label ("Copied!") isn't announced, because the aria-label wins;
 
 ## Real examples
 
-- `InputPasswordWithLabel`: `app/components/05.forms/input-text/InputPasswordWithLabel.vue` (show/hide toggle attached to the input)
+- `InputPasswordField`: `app/components/05.forms/input-text/InputPasswordField.vue` (show/hide toggle attached to the input)
 - `CookieConsentBanner`: `app/components/02.molecules/cookie-consent-banner/CookieConsentBanner.vue`
   (standalone Accept/Reject actions, not attached to an input)

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

@@ -165,7 +165,7 @@ Use when the same component appears multiple times on a page and you need to tar
 instance.
 
 If the component you're rendering is a **wrapper** that doesn't forward `styleClassPassthrough` to
-the inner component you want to style (e.g. `InputDescription` inside `InputTextWithLabel`), put a
+the inner component you want to style (e.g. `InputDescription` inside `InputTextField`), put a
 plain `class` on the wrapper instead. Vue falls it through to the wrapper's root element, which is
 an ancestor of the inner component, so tokens set there inherit down. This needs the wrapper to
 have a single root element and not set `inheritAttrs: false`.

package/.claude/skills/component-naming.md

@@ -79,19 +79,19 @@ external consumer, free to rename. Run `/check-component-usage` for the current
 |---------|----------|-----------|
 | ~~InputNumberCore~~ | ✅ `InputNumber` (2026-09-25) | - |
 | ~~InputNumberDefault~~ | ✅ `InputNumberField` (2026-09-25) | - |
-| InputTextCore | `InputText` | yes |
-| InputTextWithLabel | `InputTextField` | yes |
-| InputPasswordWithLabel | `InputPasswordField` | yes |
-| InputTextAsNumberWithLabel | `InputTextAsNumberField` | - |
+| ~~InputTextCore~~ | ✅ `InputText` (2026-10-16) | yes |
+| ~~InputTextWithLabel~~ | ✅ `InputTextField` (2026-10-16) | yes |
+| ~~InputPasswordWithLabel~~ | ✅ `InputPasswordField` (2026-10-16) | yes |
+| ~~InputTextAsNumberWithLabel~~ | ✅ `InputTextAsNumberField` (2026-10-16) | - |
 | ~~InputRangeCore~~ | ✅ `InputRange` (2026-10-16) | - |
 | ~~InputRangeDefault~~ | ✅ `InputRangeField` (2026-10-16) | - |
-| InputTextareaCore | `InputTextarea` | - |
-| InputTextareaWithLabel | `InputTextareaField` | yes |
-| InputSelectCore | `InputSelect` | yes |
-| InputSelectWithLabel | `InputSelectField` | yes |
-| ToggleSwitchCore | `ToggleSwitch` | yes |
-| ToggleSwitchWithLabel | `ToggleSwitchField` | yes |
-| ToggleSwitchWithLabelInline | `layout` prop on `ToggleSwitchField`, or `ToggleSwitchFieldInline` | - |
+| ~~InputTextareaCore~~ | ✅ `InputTextarea` (2026-10-16) | - |
+| ~~InputTextareaWithLabel~~ | ✅ `InputTextareaField` (2026-10-16) | yes |
+| ~~InputSelectCore~~ | ✅ `InputSelect` (2026-10-16) | yes |
+| ~~InputSelectWithLabel~~ | ✅ `InputSelectField` (2026-10-16) | yes |
+| ~~ToggleSwitchCore~~ | ✅ `ToggleSwitch` (2026-10-16) | yes |
+| ~~ToggleSwitchWithLabel~~ | ✅ `ToggleSwitchField` (2026-10-16) | yes |
+| ~~ToggleSwitchWithLabelInline~~ | ✅ `layout="inline"` on `ToggleSwitchField` (2026-10-16) | - |
 | ~~TripleToggleSwitchCore~~ | ✅ `TripleToggleSwitch` (2026-09-27) | - |
 | ~~InputButtonCore~~ | ✅ `InputButton` (2026-09-28) | yes |
 | ~~InputCheckboxRadioCore~~ | ✅ `InputCheckboxRadio` (2026-09-27) | - |

package/.claude/skills/components/container-glow.md

@@ -96,8 +96,8 @@ apply instantly instead of fading).
 ## Notes
 
 - 2026-09-20 migration: renamed from `ContainerGlowCore` to `ContainerGlow` — the `Core` suffix in
-  this library denotes a primitive with a non-Core wrapper built on top of it (`InputTextCore` →
-  `InputTextWithLabel`, `AlertMaskCore` → `AlertMaskedContent`), and this component has no such
+  this library denotes a primitive with a non-Core wrapper built on top of it (`InputTextCore` → `InputTextWithLabel`, since renamed;
+  `AlertMaskCore` → `AlertMaskedContent`), and this component has no such
   sibling. Checked all consumer repos first; found one real usage in a defunct
   demo app, left as a follow-up for that repo rather than edited here.
 - Moved from `app/components/container-glow/` (unplaced) into

package/.claude/skills/components/form-field.md

@@ -6,7 +6,7 @@
 field's width (`narrow`/`medium`/`wide`), centres it with `margin-inline: auto`, optionally insets
 it from its container edges with a gutter, and applies the shared vertical field spacing
 (`--field-margin-block`). It renders no label, input or error text itself: put an `*Field`
-component (`InputTextWithLabel`, `InputNumberField`, `InputSelectWithLabel`, ...) in its default
+component (`InputTextField`, `InputNumberField`, `InputSelectField`, ...) in its default
 slot.
 
 Typical use inside `FormWrapper` / a pattern form: `<FormField width="wide" :has-gutter="false">`
@@ -37,7 +37,7 @@ around each control, so the form's own container controls the width.
 
 ```vue
 <FormField width="wide" :has-gutter="false" :field-has-error="!!errors.email">
-  <InputTextWithLabel
+  <InputTextField
     v-model="state.email"
     name="email"
     label="Email"

package/.claude/skills/components/form-wrapper.md

@@ -36,7 +36,7 @@ centre it.
 <FormWrapper width="medium">
   <form @submit.prevent="submitForm">
     <FormField width="wide" :has-gutter="false">
-      <InputTextWithLabel ... />
+      <InputTextField ... />
     </FormField>
   </form>
 </FormWrapper>

package/.claude/skills/components/glowing-border.md

@@ -50,7 +50,7 @@ stops are public CSS custom properties — see `CONSUMER-STYLING.md` for the ful
 
 ## Highlighting a single control
 
-Wrap just an `InputButton` or `InputTextCore` so the glow becomes the control's border (a design
+Wrap just an `InputButton` or `InputText` so the glow becomes the control's border (a design
 call-out for something "special"). Set `--glowing-border-radius` to the control's radius plus the
 glow width, `--glowing-border-surface: transparent`, `--glowing-border-overflow: visible` (or the
 control's focus ring is clipped), shrink-to-fit display, and `--input-text-border: transparent` for

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

@@ -3,15 +3,15 @@
 ## Overview
 
 `InputDescription` renders a form field's help text. Every `*Field` wrapper in `05.forms`
-(`InputTextWithLabel`, `InputNumberField`, `InputSelectWithLabel`, `InputTextareaWithLabel`,
-`InputRangeField`, `InputTextAsNumberWithLabel`, `SingleCheckbox`, `MultipleCheckboxes`,
+(`InputTextField`, `InputNumberField`, `InputSelectField`, `InputTextareaField`,
+`InputRangeField`, `InputTextAsNumberField`, `SingleCheckbox`, `MultipleCheckboxes`,
 `MultipleRadiobuttons`) already renders one and forwards its own `descriptionText` /
 `descriptionHtml` slots into it, so consumers normally just pass those slots to the wrapper:
 
 ```vue
-<InputTextWithLabel v-model="email" name="email" label="Email" :field-has-error :error-message>
+<InputTextField v-model="email" name="email" label="Email" :field-has-error :error-message>
   <template #descriptionText>We'll only use this for your booking confirmation</template>
-</InputTextWithLabel>
+</InputTextField>
 ```
 
 Use `InputDescription` directly only when building a custom field wrapper.
@@ -54,7 +54,7 @@ otherwise `InputDescription` sees an (empty) slot and renders an empty element:
 
 - It's a plain description, not a live region: link it with `aria-describedby` on the control
   (`useAriaDescribedById` does this in every wrapper).
-- `InputTextWithLabel`, `InputSelectWithLabel` and `InputTextareaWithLabel` render it **after**
+- `InputTextField`, `InputSelectField` and `InputTextareaField` render it **after**
   the control for the `outlined` variant and before it otherwise; both positions carry the same id.
 
 ---
@@ -81,9 +81,9 @@ look, zero the slot margins and space it with the root margins (example in CONSU
 - Wrappers forwarded both description slots unconditionally, so every field rendered an empty
   description element (with its id) even when no description was given. Each wrapper now forwards
   a slot only when its own consumer supplied it.
-- `InputTextWithLabel` and `InputSelectWithLabel` rendered the description **twice** for the
+- `InputTextField` and `InputSelectField` rendered the description **twice** for the
   `outlined` variant (before and after the control); the first copy now has
-  `v-if="inputVariant !== 'outlined'"`, matching `InputTextareaWithLabel`.
+  `v-if="inputVariant !== 'outlined'"`, matching `InputTextareaField`.
 - The outlined-variant copies had no `description-id`, so the control's `aria-describedby`
   pointed at an id that didn't exist. They now pass it.
 - Removed props that were never read: `id` (a leftover from a commented-out id computation) and

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

@@ -3,9 +3,9 @@
 ## Overview
 
 `InputError` renders the red error message strip under a form control. Every `*Field` wrapper in
-`05.forms` (`InputTextWithLabel`, `InputNumberField`, `InputSelectWithLabel`, `InputTextareaWithLabel`,
-`InputRangeField`, `ToggleSwitchWithLabel`, `SingleCheckbox`, `MultipleCheckboxes`,
-`MultipleRadiobuttons`, `InputTextAsNumberWithLabel`) already renders one, so consumers rarely use
+`05.forms` (`InputTextField`, `InputNumberField`, `InputSelectField`, `InputTextareaField`,
+`InputRangeField`, `ToggleSwitchField`, `SingleCheckbox`, `MultipleCheckboxes`,
+`MultipleRadiobuttons`, `InputTextAsNumberField`) already renders one, so consumers rarely use
 it directly. Use it yourself only when building a custom field wrapper.
 
 It is designed to sit in **grid row 2** of the wrapper, directly under the control in row 1: it is

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

@@ -3,9 +3,8 @@
 ## Overview
 
 `InputLabel` renders a form field's `<label>`. Every labelled wrapper in `05.forms`
-(`InputTextWithLabel`, `InputTextAsNumberWithLabel`, `InputNumberField`, `InputSelectWithLabel`,
-`InputTextareaWithLabel`, `InputRangeField`, `ToggleSwitchWithLabel`,
-`ToggleSwitchWithLabelInline`) already renders one from its `label` prop, so consumers normally
+(`InputTextField`, `InputTextAsNumberField`, `InputNumberField`, `InputSelectField`,
+`InputTextareaField`, `InputRangeField`, `ToggleSwitchField`) already renders one from its `label` prop, so consumers normally
 never use it directly.
 
 Use `InputLabel` directly only when building a custom field wrapper:
@@ -24,7 +23,7 @@ Use `InputLabel` directly only when building a custom field wrapper:
 
 | Prop (template form) | Type | Default | Notes |
 |------|------|---------|-------|
-| `:id` | `string` | required | The **control's** id, rendered as the label's `for`. The label itself gets no id. Must match the id actually on the `<input>`/`<select>`/`<textarea>` (e.g. `ToggleSwitchCore` prefixes its input id with `toggle-switch-`, so its wrappers pass `toggleSwitchId`). |
+| `:id` | `string` | required | The **control's** id, rendered as the label's `for`. The label itself gets no id. Must match the id actually on the `<input>`/`<select>`/`<textarea>` (e.g. `ToggleSwitch` prefixes its input id with `toggle-switch-`, so its wrappers pass `toggleSwitchId`). |
 | `:required` | `boolean` | `false` | Whether the field is required. Only decides which fields the indicator marks; it doesn't set `required` on the control. Wrappers forward their own `required`. |
 | `:indicator` | `"none" \| "required" \| "optional"` | `undefined` → app.config → `"none"` | Which fields get a marker. |
 | `:required-text` | `string` | `undefined` → app.config → `"*"` | Required marker text. |
@@ -61,9 +60,9 @@ export default defineAppConfig({
 
 - `"required"` mode: a marker on fields with `required`; `"optional"` mode: a marker on fields
   without it; `"none"`: nothing (default, so existing sites are unchanged).
-- `InputTextWithLabel`, `InputTextAsNumberWithLabel`, `InputNumberField`, `InputSelectWithLabel`,
-  `InputTextareaWithLabel` and `InputRangeField` forward `:required`.
-  `ToggleSwitchWithLabel`/`ToggleSwitchWithLabelInline` pass `indicator="none"`: a switch always
+- `InputTextField`, `InputTextAsNumberField`, `InputNumberField`, `InputSelectField`,
+  `InputTextareaField` and `InputRangeField` forward `:required`.
+  `ToggleSwitchField` pass `indicator="none"`: a switch always
   has a value, so neither marker means anything there.
 - The wrappers don't expose the indicator props per field; use `app.config`.
 - Text props are the i18n hook: pass translated `optionalText`/`requiredText` (or set them in
@@ -101,7 +100,7 @@ Hooks: `data-input-variant`, `data-invalid`, `.input-label-indicator[data-indica
 - Removed props that were never read: `name` and `theme`. Wrappers stopped passing them.
 - Wrappers also passed a non-prop `:for`, which fell through and overrode the `for` built from
   `id`. For the text/number/select/textarea/range wrappers it was the same value (dropped). For
-  `ToggleSwitchWithLabel`/`ToggleSwitchWithLabelInline` it was the only thing pointing the label
+  `ToggleSwitchField` it was the only thing pointing the label
   at the real input (`toggle-switch-<id>`); they now pass `:id="toggleSwitchId"` explicitly.
 - `inputVariant` moved from a bare class (`.normal`/`.underlined`, whose rules were duplicates of
   the base rule) to `data-input-variant`. `fieldHasError` (accepted but unused) now renders

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

@@ -30,7 +30,7 @@ Most consumers should reach for **InputNumberField** rather than `InputNumber` d
 | `:required` | `boolean` | `false` | Native `required`. |
 | `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the wrapper. |
 | `:weight` | `FormWeight` | `"normal"` | Adds an `input-number--{weight}` class to the input, for prop-shape consistency with sibling `05.forms` components. **No CSS in the library currently styles this class — it's a no-op today**, same convention as `InputRange`'s `weight` prop. |
-| `:input-variant` | `InputUiVariant` | `"normal"` | Rendered as `data-input-variant` on the wrapper (a bare class until 2026-10-16) — `"normal"` (bordered box) and `"underlined"` (bottom-border only) have CSS; `"outlined"` doesn't (see CONSUMER-STYLING.md). Same prop/behaviour as `InputTextCore`. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | Rendered as `data-input-variant` on the wrapper (a bare class until 2026-10-16) — `"normal"` (bordered box) and `"underlined"` (bottom-border only) have CSS; `"outlined"` doesn't (see CONSUMER-STYLING.md). Same prop/behaviour as `InputText`. |
 | `:field-has-error` | `boolean` | `false` | Drives `data-invalid` on the wrapper. |
 | `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the input element. Reacts to changes. |
 | `:aria-describedby` | `string` | `""` | Forwarded to the native input. |
@@ -57,7 +57,7 @@ slot is present (`.input-number-slot-left .input-button { border-right: ... }` a
 right-hand mirror), so it sits flush against the button's own edge rather than around the
 containing `.input-number-slot` div. This makes step buttons read as embedded segments of the same control
 rather than separate floating buttons. The divider reuses the wrapper's own border colour token
-(no separate divider token), same as `InputTextCore`/`InputTextAsNumberWithLabel`.
+(no separate divider token), same as `InputText`/`InputTextAsNumberField`.
 
 ---
 
@@ -117,7 +117,7 @@ score-1/5 state. Several latent bugs were fixed alongside the standard checklist
 
 ---
 
-## Fixed 2026-09-22 (follow-up): rewritten to visually mirror InputTextCore
+## Fixed 2026-09-22 (follow-up): rewritten to visually mirror InputText
 
 The first migration pass above only made `InputNumber`'s *own* (pre-existing, previously dead)
 CSS active — it didn't reconsider whether that CSS was actually the right design. Once live, it
@@ -125,21 +125,21 @@ was visually inconsistent with the rest of `05.forms`: no border-radius, no hove
 state, wrong padding-token family (`--form-textarea-padding-*` instead of the shared input
 padding tokens), and a box-shadow-toggle focus mechanism instead of the `:has()`-based outline
 approach every other input in this library uses. `InputNumber` is meant to be a native
-`<input type="number">` sibling to the text-based `InputTextAsNumberWithLabel` variant (see
-`input-text-core.md`'s Variants section) — both should look and behave the same. The CSS was rewritten
-to mirror `InputTextCore` directly:
+`<input type="number">` sibling to the text-based `InputTextAsNumberField` variant (see
+`input-text.md`'s Variants section) — both should look and behave the same. The CSS was rewritten
+to mirror `InputText` directly:
 
-- Added `:input-variant` (`"normal"` / `"outlined"` / `"underlined"`), matching `InputTextCore`'s
+- Added `:input-variant` (`"normal"` / `"outlined"` / `"underlined"`), matching `InputText`'s
   prop and wrapper-class shape (`InputNumberField` forwards it the same way
-  `InputTextWithLabel` forwards it to `InputTextCore`, including to `InputLabel`).
-- Replaced the flat, unconditional border/radius/box-shadow with `InputTextCore`'s `.normal`
+  `InputTextField` forwards it to `InputText`, including to `InputLabel`).
+- Replaced the flat, unconditional border/radius/box-shadow with `InputText`'s `.normal`
   variant shape: border + `border-radius: var(--form-input-border-radius)` (previously this read
   `var(--form-element-border-width)` — a pre-existing bug that used the *border-width* token as
   the *radius*, coincidentally invisible while the block was dead), plus `:has(input:hover)` /
   `:has(input:focus-visible)` outline states instead of the old `--_focus-box-shadow` custom
   property toggle.
   - `--input-number-border-hover` and `--input-number-border-focus` are new public tokens for
-    these two states (both fall back to `--theme-border-focus`, same as `InputTextCore`).
+    these two states (both fall back to `--theme-border-focus`, same as `InputText`).
 - Padding moved from `--form-textarea-padding-*` (the wrong token family — textarea, not input)
   to the shared `--input-padding-block`/`--input-padding-inline`/`--input-min-height` tokens every
   other `05.forms` text-like input uses.
@@ -148,7 +148,7 @@ to mirror `InputTextCore` directly:
   previously it had neither, an accessibility gap beyond the visual mismatch (checklist item 9).
 - The divider between the input and an embedded button now reuses the border colour
   (`--_border`) directly instead of a separate `--input-number-divider-color` token — removed,
-  since `InputTextCore` doesn't have an equivalent separate token either (the border colour
+  since `InputText` doesn't have an equivalent separate token either (the border colour
   *is* the divider colour there too).
 - `--_border-hover` and `--_surface-hover` were each used only once with no composition or
   state-swap, so per the public-token rule they were inlined directly
@@ -158,21 +158,21 @@ to mirror `InputTextCore` directly:
   wrapper's own focus outline *and* the embedded button's focus outline both read it).
 - Fixed 2026-10-04: the wrapper's hover and focus outlines only matched `input:hover` /
   `input:focus-visible`, so hovering or tabbing to a step button showed no outer ring, unlike
-  `InputTextCore` (and so `InputTextAsNumberWithLabel`), which matches `button` too. Both
-  selectors are now `:has(input:…, button:…)`, mirroring `InputTextCore`.
+  `InputText` (and so `InputTextAsNumberField`), which matches `button` too. Both
+  selectors are now `:has(input:…, button:…)`, mirroring `InputText`.
 
 **Separately found in the same investigation** (not an `InputNumber` bug, but what the visual
-comparison was originally checking against): `InputTextAsNumberWithLabel.vue` had its own,
-unrelated pre-existing bug — see `input-text-core.md`'s Variants section for the fix.
+comparison was originally checking against): `InputTextAsNumberField.vue` had its own,
+unrelated pre-existing bug — see `input-text.md`'s Variants section for the fix.
 
 **Correction, same day**: the first version of this rewrite still didn't visually match — the
 divider border and button sizing (`aspect-ratio: 1`, `width: var(--input-min-height)`) had been
 put on the `.left-slot`/`.right-slot` *wrapper divs*, not on `.input-button` itself, unlike
-`InputTextCore`'s equivalent block. That left an unstyled gap between the button and the border
+`InputText`'s equivalent block. That left an unstyled gap between the button and the border
 line instead of a flush edge, and the buttons weren't sized to match the input's height. Fixed by
 moving the divider border and all button sizing/colour rules onto `.input-button` directly
 (`&.has-left-slot .left-slot .input-button { border-right: ... }`, matching
-`InputTextAsNumberWithLabel`'s `.left-slot .input-button { border-right: ... }` exactly)
+`InputTextAsNumberField`'s `.left-slot .input-button { border-right: ... }` exactly)
 rather than the containing `.slot` div. When mirroring another component's CSS structure, check
 *which element* a rule targets, not just that an equivalent rule exists somewhere in the block —
 a border/sizing rule one level off in the DOM tree produces a visually-close-but-not-matching

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

@@ -0,0 +1,153 @@
+# InputSelect Component
+
+> **Renamed 2026-10-16**: `InputSelectCore` → `InputSelect`, `InputSelectWithLabel` →
+> `InputSelectField` (DOM classes `.input-select-core` → `.input-select`,
+> `.input-select-with-label` → `.input-select-field`; full class list in CONSUMER-STYLING.md).
+> Skill doc renamed from `input-select-core.md`. A consumer app uses both old names; list its edits
+> privately and apply them when it upgrades.
+
+## Overview
+
+`InputSelect` is the low-level native `<select>` primitive for the `05.forms` select family.
+It renders a native select with a data-driven list of `<option>`s (each optionally decorated with
+an icon), an optional placeholder option, and adopts the modern CSS Customizable Select API
+(`appearance: base-select`) for a fully styleable open-picker state where supported, with a
+graceful CSS fallback (see "Browser support" below). It has no label, description, or
+error-message rendering of its own — that's composed by the `InputSelectField` variant below.
+
+Most consumers should reach for **InputSelectField** rather than `InputSelect` directly.
+
+---
+
+## Props reference
+
+> **Hyphenation rule**: Vue's ESLint config enforces `vue/attribute-hyphenation`. Always write camelCase prop names hyphenated in templates: `:field-has-error`, `:style-class-passthrough`, `:aria-describedby`.
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:id` | `string` | (required) | Applied to the native select. |
+| `:name` | `string` | (required) | Applied to the native select. |
+| `:placeholder` | `string` | `""` | Renders a disabled placeholder `<option>`, selected while `modelValue` is `""`, `null` or `undefined` (not `0`). No option rendered at all when unset. |
+| `:title` | `string` | `"Please select an option"` | Native `title` attribute (tooltip). Visitor-facing copy: pass a translated string. |
+| `:required` | `boolean` | `false` | Native `required`. |
+| `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the wrapper. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | Sets `data-input-variant` on the wrapper. `"normal"` (bordered box) and `"underlined"` (bottom border only) have CSS; `"outlined"` doesn't. |
+| `:field-has-error` | `boolean` | `false` | `data-invalid` on the wrapper and `aria-invalid="true"` on the select. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the select element. Reacts to changes. |
+| `:aria-describedby` | `string` | `""` | Forwarded to the native select; omitted when empty. |
+
+### v-models
+
+- `v-model` — `string | number | readonly number[]`, **required** (`defineModel({ required: true })`, satisfying `vue/require-default-prop` — see `project_ledger_eslint_issues_column` in memory).
+- `v-model:field-data` — `IFormMultipleOptions` (`{ data: IOptionsConfig[]; total; skip; limit }`), **required**. The `data` array drives the rendered `<option>`s; only `data` is read. The template dereferences `fieldData.data` unconditionally, so a consumer that doesn't bind it crashes on render. A one-way `:field-data` works too: the component never writes it.
+- `v-model:is-dirty` — `boolean`. Set to `true` on the native `change` event (never reset to `false` by this component). Reflected as `data-dirty` on the wrapper.
+- `v-model:is-active` — `boolean`. Tracks native focus/blur (`focusin`/`focusout`). Reflected as `data-active` on the wrapper.
+
+### Option icons
+
+An `IOptionsConfig` item with `icon` renders an `<Icon class="input-select-option-icon">`
+(`aria-hidden`) before its label. It only shows where `appearance: base-select` is supported; a
+native dropdown renders option text only. Labels render as text, never as markup.
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/05.forms/input-select/CONSUMER-STYLING.md) for the
+full table with defaults and the state hooks.
+
+**Common tokens:**
+
+- `--input-select-surface` / `-surface-hover` — wrapper/select background and option-row hover background
+- `--input-select-text-color` — select text colour
+- `--input-select-border` / `-border-hover` / `-border-focus` — border colour resting, mouse-hover outline, and `:focus-visible` outline (also the open picker's border/outline)
+- `--input-select-option-gap` / `-option-icon-size` — option icon spacing and size
+
+**State hooks** (on `.input-select-wrapper`): `data-input-variant`, `data-theme`, `data-invalid`,
+`data-dirty`, `data-active`.
+
+---
+
+## Browser support: `appearance: base-select`
+
+The open-picker styling (`&::picker(select)`, `:open`/`:not(:open)` states, the transition/opacity
+`@starting-style` reveal) relies on the CSS Customizable Select API
+(`appearance: base-select`/`::picker(select)`), a very new feature not yet supported everywhere.
+`appearance: none` is set first, then overridden by `appearance: base-select` only where the
+browser recognises that value, so elsewhere (including Safari 16) the select falls back to the
+browser's native dropdown with full functionality. This is decorative degradation, not a
+functional break like `ExpandingPanel`'s `::details-content` case (pitfall #19), but the
+open-picker styling should still be spot-checked on a real Safari session before treating it as
+visually final.
+
+---
+
+## Changed 2026-10-16: rename, state hooks, stress fixes
+
+- Renamed to the Control/Field convention (see the note at the top).
+- State classes (`.normal`/`.underlined`/`.outlined`, `.dirty`, `.active`, `.error`) became data
+  attributes, so a consumer's unlayered `.error` rule can't restyle the field.
+- The placeholder option used `:selected="!modelValue"`, so a model value of `0` also marked the
+  placeholder selected. It now checks for an empty value only.
+- `aria-describedby=""` was rendered when no description id was passed; it's now omitted.
+- `styleClassPassthrough` now reacts to prop changes (it was read once at setup).
+- `InputSelectField` applied its passthrough to the inner select; it now applies it to its own
+  root only. It also gained a `title` prop (forwarded), and its root is `.input-select-field`
+  itself rather than an unclassed outer `<div>` around it.
+- New public tokens: `--input-select-text-color`, `--input-select-option-gap`,
+  `--input-select-option-icon-size`.
+- Long option labels wrap in the open picker, and the Field wraps long label, description and
+  error copy. `StressTest` stories on both components.
+
+## Fixed 2026-09-22: dead functionality and prop-shape bugs
+
+Migrated from a `variants:true`, `eslint_issues:true`, score-2/5 state.
+
+- `required` and `styleClassPassthrough` were declared but never bound.
+- `isDirty`/`isActive` were read but nothing set them; `@focusin`/`@focusout`/`@change` added.
+- The placeholder option used `readonly` (not valid on `<option>`); switched to `disabled`.
+- `theme`/`inputVariant` moved to the shared `FormUiTheme`/`InputUiVariant` types; `fieldData`
+  moved from an `as Ref<T>` cast to `defineModel<T>("fieldData", { required: true })`.
+- Dead commented-out CSS and single-use private tokens removed (pitfall #20).
+
+---
+
+## Variants
+
+### InputSelectField
+
+`InputSelectField` (`InputSelectField.vue`) composes `InputSelect` with `InputLabel`,
+`InputDescription` (before the control, or after the control and error when
+`inputVariant === "outlined"`, matching `InputTextField`'s placement rule), and `InputError`.
+Ids for the label, description and error come from `useAriaDescribedById`.
+
+**Additional props over InputSelect** (it takes no `id`; the id is generated):
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:data-testid` | `string` | `"input-select-field"` | Sets `data-testid` on the root. (Was `"input-select-with-label"` until 2026-10-16.) |
+| `:label` | `string` | (required) | Rendered via `InputLabel`. |
+| `:error-message` | `object \| string` | (required) | Rendered via `InputError` when `field-has-error` is true. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Applied to the `.input-select-field` root only, not the inner select. |
+
+`name`, `placeholder`, `title`, `required`, `field-has-error`, `theme` and `input-variant` are
+forwarded. While `field-has-error` is set, the inner `InputSelect` gets `theme="error"` whatever
+the `theme` prop says; the Field root's own `data-theme` keeps the prop value.
+
+**Slots**: `descriptionHtml`, `descriptionText` (both forwarded to `InputDescription`).
+
+```vue
+<InputSelectField
+  v-model="colour"
+  v-model:field-data="colourOptions"
+  name="colour"
+  label="Favourite colour"
+  placeholder="Choose a colour"
+  :error-message="errors.colour"
+  :field-has-error="!!errors.colour"
+>
+  <template #descriptionText>Pick the colour you like best</template>
+</InputSelectField>
+```
+
+`v-model` and `v-model:field-data` are both **required**, same as `InputSelect` above.