srcdev-nuxt-components 9.4.10 → 9.4.12

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

@@ -0,0 +1,214 @@
+# InputNumberCore Component
+
+## Overview
+
+`InputNumberCore` is the low-level native `<input type="number">` primitive for the `05.forms`
+number-input family. It renders a single native number input with left/right button slots (for
+step-down/step-up controls). It has no label, description, or error-message rendering of its
+own — that's composed by the `InputNumberDefault` variant below.
+
+Most consumers should reach for **InputNumberDefault** rather than `InputNumberCore` 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 input. |
+| `:name` | `string` | (required) | Applied to the native input. |
+| `:min` | `number` | (required) | Native `min`. |
+| `:max` | `number` | (required) | Native `max`. |
+| `:step` | `number` | `1` | Native `step`. |
+| `:placeholder` | `string` | `""` | Native `placeholder`. |
+| `: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 `InputRangeCore`'s `weight` prop. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | Adds the variant name as a class on the wrapper — `"normal"` (bordered box) and `"underlined"` (bottom-border only) have CSS; `"outlined"` doesn't (see CONSUMER-STYLING.md). Same prop/behaviour as `InputTextCore`. |
+| `:field-has-error` | `boolean` | `false` | Drives `data-invalid` on the wrapper. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the input element. |
+| `:aria-describedby` | `string` | `""` | Forwarded to the native input. |
+
+### v-model
+
+`v-model` — `number | readonly number[]`, **required** (`defineModel({ required: true })`). Bound
+directly to the native number input. Required rather than defaulted deliberately — same reasoning
+as `InputRangeCore`'s `v-model` (see that skill doc) — this also satisfies `vue/require-default-prop`.
+
+---
+
+## Slots
+
+| Slot | Notes |
+|------|-------|
+| `left` | Rendered before the input (e.g. a step-down button). Adds `has-left-slot` to the wrapper. |
+| `right` | Rendered after the input (e.g. a step-up button). Adds `has-right-slot` to the wrapper. |
+
+Any `.input-button-core` inside `.slot` gets its own border/outline stripped and is sized to
+match the input (`aspect-ratio: 1`, `width: var(--input-min-height)`) regardless of which slot
+it's in. The divider border is then added directly to that button element specifically when its
+slot is present — `&.has-left-slot .left-slot .input-button-core { border-right: ... }` and the
+right-hand mirror — so it sits flush against the button's own edge rather than around the
+containing `.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`.
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/05.forms/input-number/CONSUMER-STYLING.md) for the
+full table with defaults.
+
+**Common tokens:**
+- `--input-number-surface` / `-surface-hover` — wrapper/input/embedded-button background, resting and hover, falls back to `--theme-input-surface`/`-surface-hover`
+- `--input-number-border` / `-border-hover` / `-border-focus` — border colour resting, mouse-hover outline, and `:focus-visible` outline (also the divider colour and the embedded button's own focus outline), falls back to `--theme-border`/`--theme-border-focus`
+- `--input-number-text-color` — input text colour, falls back to `--theme-input-text-color-normal`
+- `--input-number-placeholder-color` — placeholder text colour, falls back to `--theme-input-placeholder`
+
+---
+
+## Fixed 2026-09-22: dead CSS from a missing base class and mismatched selectors
+
+`InputNumberCore` migrated to full compliance from a `variants:true`, `eslint_issues:true`,
+score-1/5 state. Several latent bugs were fixed alongside the standard checklist:
+
+- The native `<input>` had no static `input-number-core` class — only the dynamic
+  `elementClasses` passthrough — so the entire `.input-number-core { ... }` style block (font,
+  padding, colour, focus box-shadow) never matched anything. Fixed by adding the class directly.
+- `placeholder` was declared as a prop but never bound on the `<input>` — unlike `InputRangeCore`
+  (where a range input genuinely has no placeholder concept and the no-op is intentional and
+  documented), a number input *does* support `placeholder` meaningfully, so this was a real gap,
+  not a deliberate no-op. Fixed by binding `:placeholder`.
+- The left/right slot divs rendered with classes `slot left`/`slot right`, but the CSS targeted
+  `.left-slot`/`.right-slot` and `.has-left-slot`/`.has-right-slot` — neither the slot divs nor
+  the wrapper ever carried those exact class names, so the divider-border and flex-alignment
+  rules for embedded step buttons never applied. Fixed by renaming the slot divs to
+  `slot left-slot`/`slot right-slot` and adding `has-left-slot`/`has-right-slot` to the wrapper
+  directly from `slots.left`/`slots.right` (Vue's own `useSlots()`), rather than a fragile,
+  cross-component class-toggling relay.
+- Relatedly, `InputNumberDefault` called `updateElementClasses(["has-left-button",
+  "has-right-button"])` unconditionally on mount, which permanently added those two classes to
+  its own outer `.input-number-with-label` wrapper — a different element than
+  `InputNumberCore`'s `.input-number-wrapper`, so the `:has()` selector that was meant to key off
+  those classes could never match (the class lived on an ancestor, not a descendant). Replaced
+  entirely: `InputNumberCore` now detects an embedded button directly via
+  `:has(.left-slot .input-button-core)` / `:has(.right-slot .input-button-core)`, so no
+  JS-driven class relay is needed at all.
+- `theme` was typed as an inline `"default" | "success" | "error" | "warning"` union in both
+  `InputNumberCore` and `InputNumberDefault` instead of importing the shared `FormUiTheme` type —
+  aligned with the rest of `05.forms`.
+- `weight` was passed from `InputNumberDefault` to `InputNumberCore` but `InputNumberCore` had no
+  matching prop, so it fell through as a raw, meaningless `weight="normal"` HTML attribute on the
+  wrapper `<div>`. Fixed by declaring the prop on `InputNumberCore` too, matching `InputRangeCore`.
+- `defineModel()` had no default, tripping `vue/require-default-prop` — fixed the same way as
+  `InputRangeCore`: `defineModel({ required: true })`, not a rule disable or an artificial default.
+- A single-use private token, `--_border`, was inlined to the public
+  `var(--input-number-border, var(--theme-border))` directly at its point of use — it had no
+  composition or state-swap behind it, just a bare pass-through (see pitfall #20). `--_surface`
+  (used twice) and `--_min-width` (composed from a `v-bind()` value) correctly stayed private.
+
+---
+
+## Fixed 2026-09-22 (follow-up): rewritten to visually mirror InputTextCore
+
+The first migration pass above only made `InputNumberCore`'s *own* (pre-existing, previously dead)
+CSS active — it didn't reconsider whether that CSS was actually the right design. Once live, it
+was visually inconsistent with the rest of `05.forms`: no border-radius, no hover/focus outline
+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. `InputNumberCore` 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:
+
+- Added `:input-variant` (`"normal"` / `"outlined"` / `"underlined"`), matching `InputTextCore`'s
+  prop and wrapper-class shape (`InputNumberDefault` 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`
+  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`).
+- 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.
+- The embedded step button now gets a hover background (`--input-number-surface-hover`, new
+  public token) and a visible `:focus-visible` outline (reusing `--input-number-border-focus`) —
+  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
+  *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
+  (`var(--input-number-border-hover, var(--theme-border-focus))` /
+  `var(--input-number-surface-hover, var(--theme-input-surface-hover))`) rather than kept as
+  private wrappers. `--_border-focus` stayed private since it's now genuinely reused (the
+  wrapper's own focus outline *and* the embedded button's focus outline both read it).
+
+**Separately found in the same investigation** (not an `InputNumberCore` 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.
+
+**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-core` itself, unlike
+`InputTextCore`'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-core` directly
+(`&.has-left-slot .left-slot .input-button-core { border-right: ... }`, matching
+`InputTextAsNumberWithLabel`'s `.left-slot .input-button-core { 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
+result that's easy to miss without a side-by-side screenshot comparison.
+
+---
+
+## Variants
+
+### InputNumberDefault
+
+`InputNumberDefault` (`variants/InputNumberDefault.vue`) composes `InputNumberCore` with
+`InputLabel`, `InputDescription`, and `InputError`, plus optional step-down/step-up buttons
+(`InputButtonCore`) wired into the `left`/`right` slots.
+
+**Additional props over InputNumberCore:**
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:label` | `string` | (required) | Rendered via `InputLabel`. |
+| `:error-message` | `object \| string` | (required) | Rendered via `InputError` when `field-has-error` is true. |
+| `:step-down-label` | `string` | `"Step down"` | `button-text` on the step-down `InputButtonCore` — override for localisation. |
+| `:step-up-label` | `string` | `"Step up"` | `button-text` on the step-up `InputButtonCore` — override for localisation. |
+
+**Slots**: `descriptionHtml`, `descriptionText` (both forwarded to `InputDescription`), plus
+`left`/`right` (forwarded straight through to the underlying `InputNumberCore` — the
+step-down/step-up buttons only render when you use the `left`/`right` slots yourself, since the
+button icon content itself is consumer-supplied).
+
+```vue
+<InputNumberDefault
+  name="quantity"
+  label="Quantity"
+  v-model="quantity"
+  :min="1"
+  :max="10"
+  error-message="Please choose a value between 1 and 10"
+  :field-has-error="hasError"
+>
+  <template #left><Icon name="mdi:minus" /></template>
+  <template #right><Icon name="mdi:plus" /></template>
+</InputNumberDefault>
+```
+
+`v-model` is `number | readonly number[]`, **required** — same as `InputNumberCore` above.
+
+Step-down is disabled (`readonly` on its `InputButtonCore`) once the value reaches `min`, and
+step-up once it reaches `max`; clicking either button while at that boundary is a no-op.

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

@@ -0,0 +1,151 @@
+# InputSelectCore Component
+
+## Overview
+
+`InputSelectCore` 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 `InputSelectWithLabel` variant below.
+
+Most consumers should reach for **InputSelectWithLabel** rather than `InputSelectCore` 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 when `modelValue` is empty). No option rendered at all when unset. |
+| `:title` | `string` | `"Please select an option"` | Native `title` attribute (tooltip). |
+| `:required` | `boolean` | `false` | Native `required`. |
+| `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the wrapper. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | Adds the variant name as a class on the wrapper — `"normal"` (bordered box) and `"underlined"` (bottom-border only) have CSS; `"outlined"` doesn't (see CONSUMER-STYLING.md). Same prop/behaviour as `InputTextCore`. |
+| `:field-has-error` | `boolean` | `false` | Drives `data-invalid` on the wrapper and `aria-invalid` on the select. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the select element. |
+| `:aria-describedby` | `string` | `""` | Forwarded to the native select. |
+
+### 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. The template dereferences `fieldData.data` unconditionally, so a consumer that doesn't bind `v-model:field-data` will crash on render — `required: true` documents that constraint (it's a dev-time warning only, not a runtime guard).
+- `v-model:is-dirty` — `boolean`. Set to `true` on the native `change` event (never reset to `false` by this component).
+- `v-model:is-active` — `boolean`. Tracks native focus/blur (`focusin`/`focusout`), toggling `.active` on the wrapper.
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/05.forms/input-select/CONSUMER-STYLING.md) for the
+full table with defaults.
+
+**Common tokens:**
+- `--input-select-surface` / `-surface-hover` — wrapper/select background and option-row hover background, fall back to `--theme-input-surface`/`-surface-hover`
+- `--input-select-border` / `-border-hover` / `-border-focus` — border colour resting, mouse-hover outline, and `:focus-visible` outline (also the open-picker's own border/outline), fall back to `--theme-border`/`--theme-border-focus`
+
+---
+
+## 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.
+The component degrades gracefully in non-supporting browsers rather than breaking: `appearance:
+none` is set first (unconditionally), then overridden by `appearance: base-select` only where the
+browser recognizes that value — an unsupported value is simply ignored by the CSS parser, so the
+select falls back to the browser's native (unstyled) dropdown instead of losing functionality.
+Per pitfall #19's general lesson (checking WebKit support specifically for load-bearing use of a
+very new CSS feature, since Chrome's device-emulation mode can't catch a WebKit-only gap): this
+fallback is CSS-only degradation, not a functional break like `ExpandingPanel`'s `::details-content`
+case was, so it's lower risk — but the open-picker's custom border/outline/transition styling
+should still be spot-checked on a real Safari session before treating it as visually final.
+
+---
+
+## Fixed 2026-09-22: dead functionality and prop-shape bugs
+
+`InputSelectCore` migrated to full compliance from a `variants:true`, `eslint_issues:true`,
+score-2/5 state (no tests, no skill doc, no snippet).
+
+- **`required` prop was declared but never bound to the native `<select>`** — native HTML
+  `required` validation was completely inert regardless of the prop's value. Fixed by adding
+  `:required` to the select.
+- **`styleClassPassthrough` prop was declared but never consumed** — no `useStyleClassPassthrough`
+  call existed anywhere in the script, and the select's `class` was a hardcoded static string.
+  The prop was entirely dead; a consumer passing it had no effect. Fixed by wiring up
+  `useStyleClassPassthrough` and binding `elementClasses` alongside the static class.
+- **`isDirty`/`isActive` models were declared and read in the wrapper's CSS class bindings
+  (`{ dirty: isDirty }`, `{ active: isActive }`), but nothing ever set them** — no `focusin`/
+  `focusout`/`change` handlers existed at all, unlike `InputTextareaCore`'s `updateFocus`
+  pattern. The `.dirty`/`.active` CSS states could never trigger. Fixed by adding
+  `@focusin`/`@focusout` (toggling `isActive`) and `@change` (setting `isDirty = true`) directly
+  on the select.
+- **The placeholder `<option>` used `readonly`**, which is not a valid/supported HTML attribute
+  on `<option>` — a silent no-op, leaving the placeholder fully selectable as a real answer
+  (defeating its purpose). Fixed by switching to `disabled`, the correct native pattern for a
+  non-selectable placeholder option.
+- **`theme`/`inputVariant` were typed as inline unions** (`"default" | "success" | "error" |
+  "warning"` / `"normal" | "outlined" | "underlined"`) instead of importing the shared
+  `FormUiTheme`/`InputUiVariant` types — aligned with the rest of `05.forms`.
+- **`fieldData`'s `defineModel` used an untyped `defineModel("fieldData") as Ref<T>` cast**
+  instead of the proper generic `defineModel<T>("fieldData")` call, and had no default — the
+  `as` cast also hid the prop from ESLint's `vue/require-default-prop` detection entirely (it
+  didn't fire on `InputSelectCore.vue`, only on `InputSelectWithLabel.vue`'s correctly-typed
+  equivalent). Fixed by using the proper generic form with `{ required: true }` on both files —
+  see the `v-model:field-data` note above for why `required` is the meaningful fix here (the
+  template would otherwise crash on `fieldData.data` with no data bound).
+- **Dead commented-out CSS** (~8 lines, a "legacy support - eg, Safari" `::after` arrow
+  fallback that was never active) and a **redundant duplicate declaration**
+  (`&.underlined { background-color: var(--_surface); }`, re-setting a value the unscoped base
+  rule already applied unconditionally) were removed.
+- **CSS token cleanup**: `--_surface`, `--_surface-hover`, `--_border-hover`, and
+  `--_outline-color` were each used at exactly one point with no composition or state-swap
+  behind them (`--_outline-color` was a bare alias for `--_border-focus`, per pitfall #20) — all
+  four inlined directly to their public `var(--input-select-*, {default})` form at their point of
+  use. `--_border` (reused across `.normal`/`.underlined`/open-picker) and `--_border-focus`
+  (used directly once, plus now the open-picker's outline too) correctly stayed private.
+
+---
+
+## Variants
+
+### InputSelectWithLabel
+
+`InputSelectWithLabel` (`variants/InputSelectWithLabel.vue`) composes `InputSelectCore` with
+`InputLabel`, `InputDescription` (positioned before or after the field depending on
+`inputVariant === "outlined"`, matching `InputTextWithLabel`'s exact placement rule), and
+`InputError`.
+
+**Additional props over InputSelectCore:**
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:data-testid` | `string` | `"input-select-with-label"` | Sets `data-testid` on the wrapper — used for the wrapper element specifically (`:data-testid` shorthand resolves to the camelCase `dataTestid` prop, same convention as `:aria-describedby`). |
+| `:label` | `string` | (required) | Rendered via `InputLabel`. |
+| `:error-message` | `object \| string` | (required) | Rendered via `InputError` when `field-has-error` is true. |
+
+**Slots**: `descriptionHtml`, `descriptionText` (both forwarded to `InputDescription`).
+
+```vue
+<InputSelectWithLabel
+  name="colour"
+  label="Favourite colour"
+  v-model="colour"
+  v-model:field-data="colourOptions"
+  placeholder="Choose a colour"
+  :error-message="errors.colour"
+  :field-has-error="!!errors.colour"
+>
+  <template #descriptionText>Pick the colour you like best</template>
+</InputSelectWithLabel>
+```
+
+`v-model` and `v-model:field-data` are both **required** — same as `InputSelectCore` above. Note
+this wrapper passes `:theme="FormUiTheme"` (a local `computed`, not the raw `theme` prop) down to
+`InputSelectCore`, so the theme automatically switches to `"error"` whenever `fieldHasError` is
+true, regardless of the `theme` prop's own value.

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

@@ -163,6 +163,22 @@ Extra props: `min: number` (required), `max: number` (required), `step?: number`
 `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).
 
+**Fixed 2026-09-22**: `updateElementClasses(["input-text-as-number", "has-left-button",
+"has-right-button"])` computes marker classes onto this component's own `elementClasses`, which is
+bound to the outer `.input-text-with-label` wrapper — but the nested `<InputTextCore>` was passed
+`:style-class-passthrough` as a bare shorthand, which resolves to the raw incoming
+`styleClassPassthrough` **prop**, not the local `elementClasses`. So the marker classes never
+reached the actual `<input>`, the scoped `.input-text-core.input-text-as-number { width:
+fit-content; text-align: center; ... }` CSS never matched anything, and the input silently fell
+back to `InputTextCore`'s default full-width, left-aligned styling instead of the intended
+compact, centered numeric stepper box. Fixed by changing that binding to
+`:style-class-passthrough="elementClasses"` — `elementClasses` still carries any consumer-supplied
+`styleClassPassthrough` too, since the composable seeds it from the prop before the marker classes
+are toggled on top. When a component computes its own marker/state classes via
+`updateElementClasses()` and needs them on a *child* component rather than its own root element,
+always pass the computed `elementClasses` explicitly — the `:x` shorthand only ever resolves to
+the prop of that exact name, never a same-named local composable output.
+
 ---
 
 ## Accessibility

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

@@ -0,0 +1,154 @@
+# InputTextareaCore Component
+
+## Overview
+
+`InputTextareaCore` is the low-level native `<textarea>` primitive for the `05.forms` multi-line
+text family. It renders a single native textarea with left/right decorative slots. It has no
+label, description, or error-message rendering of its own — that's composed by the
+`InputTextareaWithLabel` variant below.
+
+Most consumers should reach for **InputTextareaWithLabel** rather than `InputTextareaCore`
+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 textarea. |
+| `:name` | `string` | (required) | Applied to the native textarea. |
+| `:maxlength` | `number` | `255` | Native `maxlength`. |
+| `:placeholder` | `string` | `""` | Native `placeholder`. |
+| `:required` | `boolean` | `false` | Native `required`. |
+| `:theme` | `FormUiTheme` | `"default"` | Sets `data-theme` on the wrapper. |
+| `:input-variant` | `InputUiVariant` | `"normal"` | Adds the variant name as a class on the wrapper — `"normal"` (bordered box) and `"underlined"` (bottom-border only) have CSS; `"outlined"` doesn't (see CONSUMER-STYLING.md). Same prop/behaviour as `InputTextCore`. |
+| `:field-has-error` | `boolean` | `false` | Drives `data-invalid` on the wrapper and `aria-invalid` on the textarea. |
+| `:style-class-passthrough` | `string \| string[]` | `[]` | Extra CSS classes applied to the textarea element. |
+| `:aria-describedby` | `string` | `""` | Forwarded to the native textarea. |
+
+### v-models
+
+- `v-model` — `string | number | readonly string[] | null | undefined`, **required**
+  (`defineModel({ required: true })`, satisfying `vue/require-default-prop` the same way as
+  `InputRangeCore`/`InputNumberCore` — see `project_ledger_eslint_issues_column` in memory).
+  "Required" here means a consumer must bind `v-model`, not that the value can't be an empty
+  string — `""` is a perfectly valid textarea value.
+- `v-model:is-dirty` — `boolean`. Set once by `InputTextareaWithLabel` the first time the value
+  becomes non-empty (never reset back to `false` by this component).
+- `v-model:is-active` — `boolean`. Tracks native focus/blur (`focusin`/`focusout`), toggling
+  `.active` on the wrapper and textarea.
+
+---
+
+## Slots
+
+| Slot | Notes |
+|------|-------|
+| `left` | Rendered before the textarea (decorative — e.g. an icon). Adds `has-left-slot` to the wrapper. |
+| `right` | Rendered after the textarea (decorative). Adds `has-right-slot` to the wrapper. |
+
+Unlike `InputNumberCore`/`InputRangeCore`, these slots have no built-in `InputButtonCore`
+divider/embedded-button styling — they're plain decorative content (see the Storybook stories,
+which use emoji), not a stepper control.
+
+---
+
+## CSS token API
+
+See [CONSUMER-STYLING.md](../../app/components/05.forms/input-textarea/CONSUMER-STYLING.md) for
+the full table with defaults.
+
+**Common tokens:**
+- `--input-textarea-surface` — wrapper background, falls back to `--theme-input-surface`
+- `--input-textarea-border` / `-border-hover` / `-border-focus` — border colour resting, mouse-hover outline, and `:focus-visible` outline, fall back to `--theme-border`/`--theme-border-focus`
+- `--input-textarea-text-color` — textarea text colour, falls back to `--theme-input-text-color-normal`
+- `--input-textarea-placeholder-color` — placeholder text colour, falls back to `--theme-input-placeholder`
+
+---
+
+## Fixed 2026-09-22: undefined tokens and dead code
+
+`InputTextareaCore` migrated to full compliance from a `variants:true`, `eslint_issues:true`,
+score-1/5 state (no public tokens, no CONSUMER-STYLING.md, no tests, no skill doc, no snippet).
+
+- **Silently broken styling from undefined CSS custom properties** (same bug class as pitfall #21
+  and `InputRangeCore`'s dead `--theme-form-range-accent-color`): the wrapper's `padding-inline`
+  read `--element-decorator-padding-inline`, and the placeholder's `font-size`/`font-style`/
+  `line-height`/`font-weight` read `--input-placeholder-font-size`/`-font-style`/`-line-height`/
+  `-font-weight` — **none of these five custom properties were declared anywhere in the
+  codebase**. Per the CSS spec, an undefined `var()` with no fallback makes the whole declaration
+  invalid, so all five silently fell back to the browser/inherited default instead of the intended
+  design. Fixed by switching to the tokens `InputTextCore` actually uses for the same purpose:
+  `--input-padding-inline` for the wrapper padding, and `--theme-input-placeholder-font-size` +
+  hardcoded `italic`/`1`/`normal` for the placeholder (matching `InputTextCore`'s placeholder rule
+  exactly — those three placeholder sub-properties aren't tokenized there either).
+- **Zero public `--input-textarea-*` tokens existed at all** — every colour value read a
+  `--theme-*` global directly, with no component-level override point (the exact gap pitfall #14
+  describes for early `05.forms` components). Added the full set matching `InputTextCore`'s shape:
+  `--input-textarea-surface`, `-border`, `-border-hover`, `-border-focus`, `-text-color`,
+  `-placeholder-color`.
+- **Dead code**: both `InputTextareaCore` and `InputTextareaWithLabel` declared
+  `const FormUiTheme = computed(() => props.fieldHasError ? "error" : props.theme);` — a value
+  binding that shadows the imported `FormUiTheme` *type* import of the same name, and is never
+  referenced anywhere in either file (the template's `:theme` shorthand resolves straight from
+  `defineProps`). Removed both. `InputTextareaWithLabel` also had ~5 lines of commented-out dead
+  code (an old, hand-rolled `id`/`errorId`/`ariaDescribedby` implementation, superseded by
+  `useAriaDescribedById` right below it) — removed. (The identical dead `FormUiTheme` computed
+  still exists in `InputTextCore`/`InputTextWithLabel` themselves — out of scope for this pass
+  since those weren't being touched, but worth cleaning up next time either is migrated.)
+- **`InputTextareaWithLabel` passed `:label` down to `InputTextareaCore`**, which has no `label`
+  prop (matching `InputTextCore`, which doesn't have one either) — it fell through as a
+  meaningless raw `label="..."` HTML attribute on the wrapper `<div>`. Removed the pass-through;
+  `InputLabel` (which does have a real `label` concept) already renders it correctly. Covered by
+  a regression test.
+- **`defineModel()` had no default**, tripping `vue/require-default-prop` in both files — fixed
+  with `{ required: true }`, same pattern as `InputRangeCore`/`InputNumberCore` (see the v-model
+  note above for why this is still correct even though an empty string is a valid value here).
+- **`InputTextareaWithLabel.stories.ts` used `reactive()` in two render functions
+  (`AllVariants`/`FormExamples`) without importing it** — only `computed` was imported from
+  `"vue"`. This library's `.ts` Storybook files need Vue reactivity APIs imported explicitly (no
+  Nuxt auto-import outside `.vue` files) — a real runtime `ReferenceError` waiting to happen the
+  first time either story rendered. Fixed by adding `reactive` to the existing `computed` import.
+
+---
+
+## Variants
+
+### InputTextareaWithLabel
+
+`InputTextareaWithLabel` (`variants/InputTextareaWithLabel.vue`) composes `InputTextareaCore` with
+`InputLabel`, `InputDescription` (positioned before or after the field depending on
+`inputVariant === "outlined"`, matching `InputTextWithLabel`'s exact placement rule), and
+`InputError`.
+
+**Additional props over InputTextareaCore:**
+
+| Prop (template form) | Type | Default | Notes |
+|------|------|---------|-------|
+| `:label` | `string` | (required) | Rendered via `InputLabel`. |
+| `:error-message` | `object \| string` | (required) | Rendered via `InputError` when `field-has-error` is true. |
+
+**Slots**: `descriptionHtml`, `descriptionText` (both forwarded to `InputDescription`), plus
+`left`/`right` (forwarded straight through to the underlying `InputTextareaCore`).
+
+```vue
+<InputTextareaWithLabel
+  name="message"
+  label="Message"
+  v-model="message"
+  placeholder="How can we help you?"
+  :maxlength="500"
+  :error-message="errors.message"
+  :field-has-error="!!errors.message"
+>
+  <template #descriptionText>Please describe your inquiry in detail</template>
+</InputTextareaWithLabel>
+```
+
+`v-model` is `string | number | readonly string[] | null | undefined`, **required** — same as
+`InputTextareaCore` above. `isDirty`/`isActive` are managed internally (not exposed as props) —
+`isDirty` flips to `true` the first time the value becomes a non-empty string (checked on mount
+and on every change), and never resets.