@malva-ui/core 0.1.12

package/docs/ai/form-utils.md

@@ -0,0 +1,319 @@
+# Library: form-utils
+
+## Overview
+
+The Form Utils library (`@malva-ui/core/form-utils`) provides foundational building blocks for accessible, state-aware forms. Includes form field wrappers, label/hint/message components, a `ControlValueAccessor` base class, and a `MlvSelectionService` for dropdown/select components.
+
+## Public API
+
+Exported from `@malva-ui/core/form-utils`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvFormState` | Type | `'default' \| 'success' \| 'info' \| 'warning' \| 'error'` |
+| `MlvErrorDisplayStrategy` | Type | `'touched' \| 'dirty' \| 'submit' \| 'immediate'` |
+
+> **Tone-unification exclusion (intentional).** `MlvFormState` deliberately keeps the input name **`state`** and the **`'error'`** member. It expresses *form-validation* semantics (used by `mlv-input`, `mlv-textarea`, `mlv-select`, `mlv-checkbox`/`mlv-checkbox-group`, `mlv-switch`/`mlv-switch-group`, `mlv-radio-group`, `mlv-day-picker`, `mlv-time-picker`, `mlv-date-range-picker`, `mlv-form-field`, `mlv-message`, and the CVA base `FormControlBase` — inherited by `mlv-rating`, `mlv-radio-group`, `mlv-color-picker-popup`), **not** the display-surface visual `tone` unified via `MlvTone` in `@malva-ui/cdk/utils`. Its only change in the API-unification refactor was renaming the old long-form info member → **`'info'`** so the token vocabulary matches everything else (`--state-info` / `--info` BEM modifiers, `state() === "info"` host bindings).
+| `MlvFormField` | Component | Auto-validation wrapper — `mlv-form-field` |
+| `MlvLabel` | Component | Form label — `mlv-label` |
+| `MlvHint` | Component | Label hint — `mlv-hint` |
+| `MlvDescription` | Component | Persistent help text below the control — `mlv-description` |
+| `MlvMessage` | Component | Validation message — `mlv-message` |
+| `FormControlBase<T>` | Abstract Directive | Base for custom form controls |
+| `MlvFormControlWrapper` | Component | Control wrapper with prefix/suffix — `mlv-form-control-wrapper` |
+| `MlvFormControlWrapperControl` | Directive | Control template slot — `[mlvFormControlWrapperControl]` |
+| `FormControlWrapperControlAppend` | Directive | Suffix slot — `[mlvFormControlWrapperControlAppend]` |
+| `FormControlWrapperControlPrepend` | Directive | Prefix slot — `[mlvFormControlWrapperControlPrepend]` |
+| `MlvSelectionService<T>` | Service | Selection state management for dropdowns |
+| `toAriaValues<V>` | Function | Normalises a CVA value (`T` / `T[]` / `null`) into the `V[]` array `@angular/aria` selection patterns require |
+| `fromAriaValues<V>` | Function | Collapses an aria `V[]` selection array back to the CVA shape (`V \| null` single, `V[]` multi) |
+| `MlvFocusableGroupBase<T>` | Abstract Directive | Roving-tabindex focus scaffold for composite groups; extended by `mlv-checkbox-group` / `mlv-switch-group` |
+| `MlvClearMlvButton` | Component | Shared clear-X button (`mlv-clear-button`) used by the wrapper and inlined by select/combobox |
+| `MlvFocusableGroupItem` | Interface | Per-item contract for the base: `FocusableOption` + `tabIndex: WritableSignal<number>` |
+
+---
+
+## Focusable group base
+
+`@Directive()` abstract base owning **only** the focus / roving-tabindex concern shared by composite groups whose single tab stop follows focus.
+
+- `MlvFocusableGroupBase<T extends MlvFocusableGroupItem>` — subclass supplies `_items: Signal<readonly T[]>` (live children, e.g. `contentChildren`) and `_isDisabled(item): boolean` (arrow-nav skip predicate); base wires a vertical + wrapping `FocusKeyManager`, the `change`→tabindex sync (only the active child is `tabindex=0`), public `onKeydown` (ArrowUp/Down + `preventDefault`), public `onChildFocus` (`setActiveItem`), initial tab stop on the first child, and `DestroyRef` teardown (unsubscribe + destroy, including before every rebuild).
+- `MlvFocusableGroupItem` — `FocusableOption` whose `tabIndex` is a `WritableSignal<number>` the group flips `0`/`-1`; satisfied by `mlv-checkbox` / `mlv-switch`.
+- Adopted by `MlvCheckboxGroup` + `MlvSwitchGroup` (deduped their identical manager lifecycle; the `change`-sub was previously missing on switch — see libs-switch.md).
+- **Not adopted by `mlv-radio-group`** (deliberate): radio's tab stop follows the _checked_ radio (selection-driven, not focus-driven), its arrows move selection across all four keys, and its effect couples radio-name + CVA selection — a focus-only base cannot express that without behavior change, so radio keeps its own `FocusKeyManager`.
+
+---
+
+## `@angular/aria` CVA value bridge
+
+Pure helpers that translate between the CVA single/multi value shape used by `FormControlBase<T>` and the array-only selection model (`value: ModelSignal<V[]>`) that `@angular/aria` selection patterns (`ngListbox`, `ngMenu`, `ngTree`, …) expose — single-select is a 1-element array in aria. Used by components that keep their `T`/`T[]` CVA contract while driving an aria pattern underneath.
+
+```ts
+toAriaValues<V>(value: V | readonly V[] | null | undefined): V[];
+//  null | undefined        -> []          (cleared)
+//  array                   -> [...array]  (multi-select, shallow copy)
+//  any other value         -> [value]     (single-select)
+
+fromAriaValues<V>(values: readonly V[] | null | undefined, multiple: boolean): V | V[] | null;
+//  multiple === true       -> [...values] (empty stays [])
+//  multiple === false      -> values[0] ?? null
+```
+
+---
+
+## Components
+
+### `MlvFormField`
+
+**Selector:** `mlv-form-field` | **Change Detection:** `OnPush`
+
+#### Inputs
+
+| Name              | Type                                          | Default     | Description                     |
+| ----------------- | --------------------------------------------- | ----------- | ------------------------------- |
+| `state`           | `MlvFormState`                                | `'default'` | Visual state                    |
+| `errorMessages`   | `Record<string, string \| ((err) => string)>` | `{}`        | Custom validator error messages |
+| `displayStrategy` | `MlvErrorDisplayStrategy`                     | `'touched'` | When to show errors             |
+
+**Built-in error messages:** `required`, `email`, `min`, `max`, `minlength`, `maxlength`, `pattern`
+
+**`MlvErrorDisplayStrategy`:**
+
+- `'touched'` — show after blur
+- `'dirty'` — show after first change
+- `'submit'` — show after form submission
+- `'immediate'` — always show
+
+When the selected strategy makes an error visible, `resolvedState()` becomes `error` and the field applies the error border token to the projected control wrapper as well as rendering the error message. The direct-child CSS scope prevents an outer field from recoloring controls owned by a nested field.
+
+---
+
+### `MlvLabel`
+
+**Selector:** `mlv-label`
+
+#### Inputs
+
+| Name       | Type                 | Default |
+| ---------- | -------------------- | ------- |
+| `for`      | `string`             | `''`    |
+| `required` | `boolean` (`coerce`) | `false` |
+
+Renders `<label [attr.for]="for">`. Supports nested `<mlv-hint>`.
+
+`required` renders `<span class="mlv-label__required" aria-hidden="true">*</span>` plus a
+`.cdk-visually-hidden` node carrying the translated `formUtils.required` word (falls back to
+`'required'` when `provideMlvI18n()` was never called). Controls extending
+`MlvSignalFormUiControlBase` forward their own `required` input here; standalone `mlv-label`
+usage can set it directly.
+
+---
+
+### `MlvHint`
+
+**Selector:** `mlv-hint`
+
+Pass-through component rendered inside `mlv-label` for secondary hint text — a short inline
+aside, not a sentence-length description (use `mlv-description` for that).
+
+---
+
+### `MlvDescription`
+
+**Selector:** `mlv-description`
+
+Persistent help text rendered **below** the control, in front of `mlv-message`, through the
+wrapper's `mlv-description` projection slot. Stays visible while a validation message shows.
+Controls extending the signal base render it from their `description` input and point
+`aria-describedby` at it via `_describedBy()`.
+
+---
+
+### `MlvMessage`
+
+**Selector:** `mlv-message`
+
+#### Inputs
+
+| Name    | Type           | Default     |
+| ------- | -------------- | ----------- |
+| `state` | `MlvFormState` | `'default'` |
+
+Animated enter/leave (fade + slide). Sets `aria-live` / `role` based on state.
+
+---
+
+### `MlvFormControlWrapper`
+
+**Selector:** `mlv-form-control-wrapper`
+
+Visual shell for form controls. Projects label, control, prefix/suffix, and message via directive slots.
+
+#### Inputs
+
+**None.** The wrapper takes no inputs — every state modifier is read from the
+optional `MLV_FORM_CONTROL` connector injected from the host control
+(`focused()`, `disabled()`, `readonly()`, `loading()`, `pill?.()`, and
+`resolvedState?.() ?? state()`). A wrapper used outside a control renders in the
+default state.
+
+#### Outputs
+
+| Name    | Type           | Description                                                 |
+| ------- | -------------- | ----------------------------------------------------------- |
+| `clear` | `output<void>` | Emitted when the user activates the wrapper's clear button. |
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-form-control-wrapper',
+  '[class]': '_stateClass()',
+  '[class.mlv-form-control-wrapper--focused]': 'formControl?.focused()',
+  '[class.mlv-form-control-wrapper--disabled]': 'formControl?.disabled()',
+  '[class.mlv-form-control-wrapper--readonly]': 'formControl?.readonly()',
+  '[class.mlv-form-control-wrapper--loading]': 'formControl?.loading()',
+  '[class.mlv-form-control-wrapper--pill]': 'formControl?.pill?.() ?? false',
+}
+```
+
+---
+
+## Directives
+
+| Directive                          | Selector                                | Purpose                            |
+| ---------------------------------- | --------------------------------------- | ---------------------------------- |
+| `MlvFormControlWrapperControl`     | `[mlvFormControlWrapperControl]`        | Marks template as the main control |
+| `FormControlWrapperControlPrepend` | `[mlvFormControlWrapperControlPrepend]` | Left-side prefix content           |
+| `FormControlWrapperControlAppend`  | `[mlvFormControlWrapperControlAppend]`  | Right-side suffix content          |
+
+---
+
+## Abstract Base Class: `FormControlBase<T>`
+
+Implements `ControlValueAccessor`. Extend to create custom form controls.
+
+#### Inputs
+
+`state`, `readonly`, `disabled` (coerced), `id` (auto-generated), `label`, `hint`, `message`
+
+#### Protected Members
+
+- `onChange: (v: unknown) => void`
+- `onTouched: () => void`
+- `internalDisabled: signal(boolean)`
+- `focused: signal(boolean)`
+
+#### CVA Methods
+
+`writeValue`, `registerOnChange`, `registerOnTouched`, `setDisabledState`
+
+---
+
+## Services
+
+### `MlvSelectionService<T>`
+
+ | **Provided:** component-level (inject per component)
+
+#### Signals
+
+| Signal           | Type               | Description            |
+| ---------------- | ------------------ | ---------------------- |
+| `multiple`       | `signal(boolean)`  | Single vs multi-select |
+| `selectedValues` | `signal<T[]>([])`  | Current selections     |
+| `displayValue`   | `computed<string>` | Human-readable label   |
+
+#### Methods
+
+| Method                          | Description                                |
+| ------------------------------- | ------------------------------------------ |
+| `select(value: T)`              | Add to selection (replaces in single mode) |
+| `deselect(value: T)`            | Remove from selection                      |
+| `isSelected(value: T): boolean` | Check if selected                          |
+| `clear()`                       | Clear all                                  |
+| `setValues(values: T[])`        | Replace all                                |
+| `toggle(value: T)`              | Add or remove                              |
+| `requestFocusFirst()`           | Emit to focus first list item              |
+
+---
+
+## Usage Examples
+
+```html
+<!-- Form field with auto error display -->
+<mlv-form-field displayStrategy="touched">
+  <mlv-label for="email">
+    Email
+    <mlv-hint>We'll contact you here</mlv-hint>
+  </mlv-label>
+  <input id="email" type="email" [formControl]="emailCtrl" />
+</mlv-form-field>
+
+<!-- Control wrapper with prefix/suffix -->
+<mlv-form-control-wrapper [focused]="isFocused()" state="default">
+  <ng-template mlvFormControlWrapperControlPrepend>$</ng-template>
+  <ng-template mlvFormControlWrapperControl>
+    <input type="number" />
+  </ng-template>
+  <ng-template mlvFormControlWrapperControlAppend>USD</ng-template>
+</mlv-form-control-wrapper>
+```
+
+---
+
+## Dependencies
+
+- `@angular/core`, `@angular/forms` — CVA, reactive forms
+- `@angular/cdk/coercion` — boolean coercion
+
+## Clearable value-gating (2026-07)
+
+- `MlvFormControl` connector: new required `hasValue: Signal<boolean>` + optional `ownsClearButton?: Signal<boolean>`.
+- `FormControlBase` declares `hasValue` **abstract** — every control derives it from its own store (text length, selection count, nullable value, token/file count; always-valued controls like slider/color-picker/time-picker return `true`).
+- Wrapper clear condition: `clearable() && hasValue() && !ownsClearButton?.()` — no dangling X on empty controls; controls flagging `ownsClearButton` (select, combobox) render `mlv-clear-button` inline before their chevron instead.
+- `MlvClearMlvButton` (`mlv-clear-button`): compact transparent circular X, i18n `clear` aria-label, `(clear)` output.
+
+## Pill controls (2026-08)
+
+- `MlvSignalFormUiControlBase` gained the shared `pill` input (`BooleanInput`) —
+  the **single place** that makes every wrapped control (input, select,
+  textarea, day-picker, tokenizer, search-field, …) fully rounded.
+- `MlvFormControl` connector: optional `pill?: Signal<boolean>`; the wrapper
+  binds `mlv-form-control-wrapper--pill`, which sets the container
+  `border-radius: var(--mlv-radius-full)` directly (wins at every density) and
+  widens inline padding (`* 1.35`) so content clears the round caps.
+- Mirrors `shape="pill"` on `mlvButton` and `shape="pill"` on `[mlvActionBar]`.
+
+## Testing entry: `@malva-ui/core/form-utils/testing`
+
+- `UiFormControl` / `UI_FORM_CONTROL` deleted (dead — nothing consumed them; form-field uses `contentChild(NgControl)`).
+
+## Signal forms Phase 1 (2026-07)
+
+- `MlvSignalFormUiControlBase` / `MlvSignalFormControlBase<T>` / `MlvSignalCheckboxControlBase` — the `FormValueControl` / `FormCheckboxControl` era counterparts of `FormControlBase`. Base owns the Malva field surface + connector, signal-forms field bindings (`errors`/`disabled`/`readonly`/`touched`/`dirty` inputs bound automatically by `[formField]`; field-bound booleans use `WriteT = unknown` transforms to satisfy the contract) and the `touch` output (replaces `onTouched`). Subclass supplies `value = model<T>(...)` (or `checked`) + `hasValue`. No CVA members — dual implementation is prohibited by the contract, controls swap bases atomically.
+- Signal controls expose `resolvedState()`: the explicit `[state]` input wins when non-default; otherwise a non-empty bound `errors` collection becomes `error` after `touched` is true. `MlvFormControlWrapper` prefers this optional connector signal (falling back to legacy `state()`), and migrated hosts/messages/`aria-invalid` consume it so signal-form validation needs no consumer-authored state plumbing.
+
+## Field surface additions (2026-08)
+
+- `MlvSignalFormUiControlBase` gained three shared inputs, so every control extending it inherits them:
+  - `required` (`InputSignalWithTransform<boolean, unknown>`, `coerceBooleanProperty`) — also a
+    signal-forms field binding, so a `required()` schema rule drives it automatically. Controls forward
+    it to `<mlv-label [required]>` and set `aria-required` on their focus target.
+  - `description` (`string`, `''`) — persistent help text rendered below the control as
+    `<mlv-description>`, in front of the validation `message`. Both stay visible together.
+  - `ariaLabel` (`string | null`, `null`) — accessible name for the focus target when no visible label
+    exists. Previously duplicated per control (`mlv-input`, `mlv-select`, `mlv-checkbox`, …); those
+    duplicates were removed so `[ariaLabel]` now works on every base-extending control.
+- Protected helpers on the base: `_descriptionId()` / `_messageId()` (`<id>-description` / `<id>-message`)
+  and `_describedBy()` — the space-separated `aria-describedby` value, `null` when neither element is
+  rendered so no dangling IDREF is emitted. Controls render `<mlv-description [id]="_descriptionId()">`
+  and `<mlv-message [id]="_messageId()">` to match.
+- `MlvFormControlWrapper` gained two below-control projection slots next to `mlv-message`:
+  `mlv-description` and `[mlvFormControlWrapperAside]` (control-owned auxiliary readout, e.g. the
+  `mlv-textarea` character counter, which previously matched no slot and never reached the DOM).
+- `MlvFormField.autoErrorMessage` no longer falls back to the literal `Validation error: <key>`; unknown
+  validator keys resolve to the translated `formUtils.invalidValue` and a dev-mode `console.warn` names
+  the key once per application run.
+
+- `MlvFormField` dual source: `contentChild(FormField)` (signal path — reads `FieldState.errors()/touched()/dirty()` reactively, prefers rule-supplied `message`, maps `kind.toLowerCase()` onto the legacy error keys) with the `NgControl`+events path kept for reactive/template-driven. The legacy effect early-returns for `[formField]` children (the signals interop exposes a shim NgControl without `.events`). `submit` strategy proxies to touched under the signal path.

package/docs/ai/form.md

@@ -0,0 +1,129 @@
+# Library: form
+
+## Overview
+
+`@malva-ui/core/form` is the **layout** layer for forms (the control infrastructure lives in `@malva-ui/core/form-utils`). It enhances native `<form>` / `<fieldset>` / `<legend>` with Malva rhythm and grid, and makes a form the single density source for every control inside it. Design: `docs/superpowers/specs/2026-08-16-form-layout-design.md`.
+
+## Public API
+
+Exported from `@malva-ui/core/form`:
+
+| Export                 | Kind      | Description                                                            |
+| ---------------------- | --------- | ---------------------------------------------------------------------- |
+| `MlvForm`              | Component | `form[mlvForm]` — vertical stack, density-scaled gap, density context  |
+| `MlvFieldset`          | Component | `fieldset[mlvFieldset]` — legend/description + auto-fit or capped grid |
+| `MlvFormHeader`        | Directive | `[mlvFormHeader]` — title row (flex, wrap, space-between)              |
+| `MlvFormActions`       | Directive | `[mlvFormActions]` — actions row; `align` input                        |
+| `MlvFieldsetSpan`      | Directive | `[mlvFieldsetSpan]` — `grid-column` span for a fieldset grid child     |
+| `MlvFormGap`           | Type      | `'xs' \| 's' \| 'm' \| 'l' \| 'xl'` (spacing-2/3/4/5/6)                |
+| `MlvFieldsetColumns`   | Type      | `'auto' \| number`                                                     |
+| `MlvFormActionsAlign`  | Type      | `'start' \| 'end' \| 'center' \| 'between'`                            |
+| `MlvFieldsetSpanValue` | Type      | `number \| 'full'`                                                     |
+
+---
+
+## Components
+
+### `MlvForm`
+
+ | **Selector:** `form[mlvForm]` | **Change detection:** `OnPush` | **Encapsulation:** `None`
+
+Attribute component on the native `<form>` (reactive forms, signal forms, `ngSubmit`, `type="submit"` all stay native). Template is `<ng-content />`.
+
+#### Inputs
+
+| Name         | Type                      | Default     | Description                                                                                                                                            |
+| ------------ | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mlvDensity` | `MlvDensity \| undefined` | `undefined` | Forwarded from the `MlvDensityDirective` host directive (`MLV_DENSITY_ELEMENT: 'form'`). Stamps `mlv-form--<density>` and is projected to descendants. |
+| `gap`        | `MlvFormGap \| undefined` | `undefined` | Inline `--mlv-form-gap` override; unset = density default.                                                                                             |
+| `maxWidth`   | `string \| undefined`     | `undefined` | Bound to `max-inline-size`.                                                                                                                            |
+
+#### Density projection
+
+The form both stamps `mlv-form--<density>` (cascade-only components such as `mlv-form-control-wrapper` follow the ancestor class) **and** provides `MLV_DENSITY_CONTEXT` via `provideMlvDensityContext(MlvDensityDirective)` (directive-bearing components such as `mlvButton`, and `mlv-popup`/`[mlvAutocomplete]` panels, resolve it before the service). Resolution everywhere: explicit input → nearest context → `MlvDensityService`. See `libs-density.md`.
+
+**Caveat — the form always stamps its own modifier.** `mlv-form--<density>` is written on every form from its resolved density (explicit input → context → service), so it _shadows_ an enclosing CSS-only density region for everything inside it. A region declared as a bare class (an ancestor `mlv--tight` / `*--tight` with no directive and no context) is not readable from JS, so the form resolves to the service value and cascade-only descendants follow `mlv-form--<service density>`, not the region. Pass `mlvDensity` on the form (or provide a context above it) instead of relying on a CSS-only region.
+
+#### Host bindings
+
+```ts
+host: {
+  class: 'mlv-form',
+  '[style.--mlv-form-gap]': '_gapValue()',       // null when gap is unset
+  '[style.max-inline-size]': 'maxWidth() ?? null',
+}
+```
+
+#### Styles (`form.scss`, block `mlv-form`)
+
+- `display:flex; flex-direction:column; align-items:stretch; min-inline-size:0; gap: var(--mlv-form-gap)`.
+- `--mlv-form-gap` density scale (`_form-mixins.scss` `gap-scale`): tight `--mlv-spacing-2`, compact `-3`, comfortable `-4` (default), spacious `-5`, airy `-6`. Override anywhere with `--mlv-form-gap`.
+- `> .mlv-button { align-self: flex-start }`.
+
+### `MlvFieldset`
+
+ | **Selector:** `fieldset[mlvFieldset]` | **Template:** `fieldset.html` | **Styles:** `fieldset.scss`
+
+Template: `@if (legend()) <legend class="mlv-fieldset__legend">` else `<ng-content select="legend" />` → optional `<p class="mlv-fieldset__description" [id]>` → `<div class="mlv-fieldset__body"><ng-content /></div>`. The grid sits on `__body` (legend never becomes a grid item; avoids the WebKit fieldset+grid bug). A projected `<legend>` is used only when the `legend` input is unset.
+
+#### Inputs
+
+| Name             | Type                                                                         | Default                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------- | ---------------------------------------------------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`             | `string`                                                                     | `mlvNextId('mlv-fieldset')` | Host id; the description id is `<id>-description`.                                                                                                                                                                                                                                                                                                                                                                                 |
+| `legend`         | `string \| undefined`                                                        | `undefined`                 | Renders `<legend class="mlv-fieldset__legend">`.                                                                                                                                                                                                                                                                                                                                                                                   |
+| `description`    | `string \| undefined`                                                        | `undefined`                 | Renders `<p class="mlv-fieldset__description">`; host `aria-describedby` points at it (removed when absent). A **static** `aria-describedby` authored on the `<fieldset>` is read once at construction and preserved: with a description the attribute becomes `"<id>-description <authored>"`, without one it stays `"<authored>"`. A **bound** `[attr.aria-describedby]` is not supported — the host binding owns the attribute. |
+| `columns`        | `MlvFieldsetColumns` (transform accepts numeric strings; invalid → `'auto'`) | `'auto'`                    | `'auto'` = auto-fit; number = **max** columns → `mlv-fieldset--capped` + `--mlv-fieldset-columns`.                                                                                                                                                                                                                                                                                                                                 |
+| `minColumnWidth` | `string`                                                                     | `'10rem'`                   | `--mlv-fieldset-min-column-width`.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `gap`            | `MlvFormGap \| undefined`                                                    | `undefined`                 | Inline `--mlv-form-gap` on the fieldset (shadows the form's for it and nested fieldsets).                                                                                                                                                                                                                                                                                                                                          |
+
+#### Host bindings
+
+`class: 'mlv-fieldset'`, `[attr.id]`, `[class.mlv-fieldset--capped]`, `[style.--mlv-fieldset-columns]`, `[style.--mlv-fieldset-min-column-width]`, `[style.--mlv-form-gap]`, `[attr.aria-describedby]` (`_describedBy()` — the description id merged with a static consumer-authored value, `null` when neither is present).
+
+#### Styles (`fieldset.scss`, block `mlv-fieldset`)
+
+- Host: `fieldset-reset`, `display:block`, `--mlv-fieldset-default-gap` density-scaled (standalone rhythm), `--mlv-fieldset-min-column-width: 10rem`.
+- `__legend` and `> legend`: `legend` mixin — `padding: 0 0 spacing-2`, body-l / semibold, `--mlv-text-primary`, `inline-size:100%`, `float:none`; plus `legend-dense` (body-m) under `density-tight` / `density-compact`.
+- `__description`: body-s, `--mlv-text-secondary`, `margin: 0 0 spacing-3`.
+- `__body`: `display:grid; min-inline-size:0; gap: var(--mlv-form-gap, var(--mlv-fieldset-default-gap)); grid-template-columns: repeat(auto-fit, minmax(min(var(--mlv-fieldset-min-column-width), 100%), 1fr))`.
+- `--capped > __body`: `repeat(auto-fit, minmax(max(min(min-col, 100%), calc((100% - (n - 1) * gap) / n)), 1fr))` — the inner `min(…, 100%)` clamp keeps the track from overflowing a container narrower than `minColumnWidth`.
+
+#### Bare `<fieldset>` fallback (in `form.scss`)
+
+`.mlv-form fieldset:not(.mlv-fieldset)`: `fieldset-reset` + `display:flex; flex-direction:column; gap: var(--mlv-form-gap)`; `> legend` gets the `legend` mixin. No grid — use `mlvFieldset` for columns.
+
+#### Caveat
+
+Native `fieldset[disabled]` disables the inner native inputs of Malva controls without updating their `disabled` signal (wrapper not styled disabled). Not synced yet — drive `disabled` on the controls / form group instead.
+
+## Directives
+
+### `MlvFormHeader` — `[mlvFormHeader]`
+
+. Host class `mlv-form__header`: `display:flex; flex-wrap:wrap; align-items:center; justify-content:space-between; gap: var(--mlv-spacing-3)`. Direct-child headings (`> :is(h1…h6)`) get `margin: 0` so consumer heading rules don't break the row (the `[class*='mlv']` reset is layered and loses to them). Put `h*[mlvTitle]` + accessories inside. No inputs. Styled by `form.scss` (use inside `form[mlvForm]`).
+
+### `MlvFormActions` — `[mlvFormActions]`
+
+. Host class `mlv-form__actions`: `display:flex; flex-wrap:wrap; align-items:center; gap: var(--mlv-spacing-3); justify-content:flex-start`.
+
+| Input   | Type                  | Default   | Description                                                                                                |
+| ------- | --------------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
+| `align` | `MlvFormActionsAlign` | `'start'` | `end` / `center` / `between` add `mlv-form__actions--align-<x>` (`flex-end` / `center` / `space-between`). |
+
+### `MlvFieldsetSpan` — `[mlvFieldsetSpan]`
+
+. Host `[style.grid-column]`.
+
+| Input             | Type                                                                            | Description                                                                                                                            |
+| ----------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `mlvFieldsetSpan` | `MlvFieldsetSpanValue` (required; numeric strings accepted, invalid → `'full'`) | `'full'` → `1 / -1`; `n` → `span n`. Numeric spans overflow an auto-fit grid that collapsed below `n` columns — prefer `'full'` there. |
+
+## Internal helpers
+
+- *(internal)* — `mlvFormGapValue(gap)` maps a step to its `var(--mlv-spacing-*)` (not exported).
+- *(internal)* — `gap-scale($var)`, `fieldset-reset`, `legend` (base declarations, no density blocks), `legend-dense` (body-m type scale for tight/compact).
+
+## Dependencies
+
+- `@angular/core`; `@malva-ui/cdk/density` (`MlvDensityDirective`, `MLV_DENSITY_ELEMENT`, `provideMlvDensityContext`); `@malva-ui/cdk/utils` (`mlvNextId`); `@malva-ui/styles` (SCSS mixins/tokens).

package/docs/ai/input.md

@@ -0,0 +1,175 @@
+# Library: input
+
+## Overview
+
+The Input library (`@malva-ui/core/input`) provides a fully accessible, state-aware text input component that integrates with Angular signal, reactive, and template-driven forms. Supports multiple input types, validation states, and optional prefix/suffix content.
+
+## Public API
+
+Exported from `@malva-ui/core/input`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvInput` | Component | Text input form control — `mlv-input` |
+| `MlvInputType` | Type | `'text' \| 'password' \| 'email' \| 'number' \| 'tel' \| 'search' \| 'url'` |
+| `MlvInputState` | Type | `'default' \| 'success' \| 'info' \| 'warning' \| 'error'` (alias of `MlvFormState`) |
+| `MlvInputInputMode` | Type | `'none' \| 'text' \| 'decimal' \| 'numeric' \| 'tel' \| 'search' \| 'email' \| 'url'` |
+| `InputPrefixDirective` | Directive | Left-side slot — `[mlvInputPrefix]` |
+| `InputSuffixDirective` | Directive | Right-side slot — `[mlvInputSuffix]` |
+| `MlvInputNative` | Directive | Marks a consumer-projected native `<input>` for adoption — `input[mlvInputNative]` |
+
+---
+
+## Components
+
+### `MlvInput`
+
+- **Selector:** `mlv-input`
+- **Change Detection:** `OnPush`
+- **Extends:** `MlvSignalFormControlBase<string>` (signal-forms `FormValueControl` — migrated 2026-07-22, slice 1 of docs/plans/signal-forms-migration.md)
+
+#### Inputs (own)
+
+| Name               | Type                        | Default  | Description                                                                                                                                                                            |
+| ------------------ | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `type`             | `MlvInputType`              | `'text'` | Native input type                                                                                                                                                                      |
+| `placeholder`      | `string`                    | `''`     | Placeholder text                                                                                                                                                                       |
+| `autocomplete`     | `string`                    | `''`     | Native `autocomplete` hint forwarded to the underlying `<input>`. Empty string suppresses the attribute                                                                                |
+| `inputMode`        | `MlvInputInputMode \| null` | `null`   | Native `inputmode` attribute forwarded to the underlying `<input>`; controls the virtual keyboard on mobile                                                                            |
+| `ariaLabel`        | `string \| null`            | `null`   | Rendered as `aria-label` on the underlying `<input>`; use when no visible `<mlv-label>` is present                                                                                     |
+| `ariaAutocomplete` | `string \| null`            | `null`   | Forwarded to `aria-autocomplete` (typically `'list'`); use with `role="combobox"` (e.g. `mlv-combobox`)                                                                                |
+| `projectControl`   | `boolean`                   | `false`  | Opt-in: adopt a consumer-projected `<input mlvInputNative>` as the control element instead of rendering the internal `<input>`. See "Native-input projection (aria forwarding)" below. |
+
+> The `min`, `max`, `step`, `maxLength`, `minLength`, `pattern`, `name`, `autocomplete`, `autofocus`, `role`, `ariaExpanded`, `ariaHasPopup`, `ariaControls`, `ariaActiveDescendant`, `value`, and `bare` inputs are also forwarded to / control the underlying `<input>`; see `input.ts` for the full list.
+
+#### Inputs (from MlvSignalFormControlBase)
+
+`state`, `readonly`, `disabled`, `id` (auto-generated), `label`, `hint`, `message`
+
+#### Computed
+
+- `messageId: computed()` — `id()` + `'-message'` for `aria-describedby`
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-input',
+  '[class]': '"mlv-input--" + state()',
+  '[class.mlv-input--disabled]': 'disabled()',
+  '[class.mlv-input--focused]': 'focused()',
+}
+```
+
+#### Outputs
+
+| Name         | Type                 | Description                                                                                                                                                                                                                        |
+| ------------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `inputFocus` | `output<FocusEvent>` | Re-emitted from the native input's `focus` handler. The native `focus` event does not bubble to the `mlv-input` host, so composite controls (e.g. `mlv-combobox`) subscribe to this instead of binding `(focus)` on `<mlv-input>`. |
+| `inputBlur`  | `output<FocusEvent>` | Re-emitted from the native input's `blur` handler (after `onTouched()`), so composite controls can run blur-driven logic (close dropdowns, revert text).                                                                           |
+
+#### Key Methods
+
+- `onInput(event: Event)` — Updates value signal + notifies form control
+- `onFocus(event: FocusEvent)` — Sets focused state + emits `inputFocus`
+- `onBlur(event: FocusEvent)` — Clears focus flag, emits the signal-form `touch` output, and emits `inputBlur`
+- `focus()` — Imperatively focuses the underlying native `<input>`
+- `select()` — Imperatively selects the current text inside the native `<input>`
+- `setFocused(focused)` — Inherited from the signal base; updates the focus signal driving the wrapper state.
+
+`computedDisabled` is a computed **property**, not a method — the effective
+component/form disabled state.
+
+#### Template Summary
+
+`MlvFormControlWrapper` → optional `MlvLabel` with hint → optional `InputPrefixDirective` slot → native `<input>` with full ARIA attributes (`aria-invalid`, `aria-describedby`) → optional `InputSuffixDirective` slot → `MlvMessage`
+
+---
+
+## Directives
+
+### `InputPrefixDirective`
+
+ | **Selector:** `[mlvInputPrefix]`
+
+Provides `templateRef` for left-side content (icons, currency symbols).
+
+### `InputSuffixDirective`
+
+ | **Selector:** `[mlvInputSuffix]`
+
+Provides `templateRef` for right-side content (toggle buttons, units).
+
+### `MlvInputNative`
+
+ | **Selector:** `input[mlvInputNative]` | **exportAs:** `mlvInputNative`
+
+Marks a consumer-projected native `<input>` that `mlv-input` should adopt as its control element when `projectControl` is set. Applies the shared `mlv-input__native` styling hook and exposes `nativeElement` so the host `mlv-input`'s `focus()` / `select()` / `nativeElement` resolve to the projected input.
+
+---
+
+## Native-input projection (aria forwarding)
+
+`@angular/aria`'s combobox trigger directive (`[ngCombobox]`, formerly `input[ngComboboxInput]`) must sit **directly on the interactive `<input>`**. Because Angular cannot attach an external directive to a component's internal template element, `mlv-input` exposes an opt-in projection slot:
+
+- Set `projectControl` on `<mlv-input>` and project an `<input mlvInputNative …>` carrying whatever attribute directives you need.
+- In this mode `mlv-input` does **not** render its own `<input>`; it provides the wrapper chrome, the `mlv-input__native` styling hook, and forwards `focus()` / `select()` / `nativeElement` to the projected input. The projected input owns its own value/keyboard wiring (e.g. aria's `[(value)]`/`[(expanded)]`), so CVA on the inner `mlv-input` is not used in this mode.
+
+```html
+<mlv-input bare projectControl>
+  <input mlvInputNative ngCombobox [(value)]="query" [(expanded)]="open" />
+</mlv-input>
+```
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic -->
+<mlv-input [formControl]="nameCtrl" label="Full Name" placeholder="Your name" />
+
+<!-- Signal form with automatic touched-error state -->
+<mlv-input [formField]="profileForm.email" type="email" label="Email" hint="We'll send updates here" />
+
+<!-- Password with show/hide toggle -->
+<mlv-input [formControl]="pwCtrl" [type]="show() ? 'text' : 'password'" label="Password">
+  <ng-template mlvInputSuffix>
+    <button type="button" (click)="show.update(v => !v)">{{ show() ? 'Hide' : 'Show' }}</button>
+  </ng-template>
+</mlv-input>
+
+<!-- Currency input -->
+<mlv-input [formControl]="amountCtrl" type="number" label="Amount">
+  <ng-template mlvInputPrefix>$</ng-template>
+  <ng-template mlvInputSuffix>USD</ng-template>
+</mlv-input>
+```
+
+---
+
+## Dependencies
+
+- `@malva-ui/core/form-utils` — `MlvSignalFormControlBase`, `MlvFormControlWrapper`, all wrapper directives, `MlvLabel`, `MlvHint`, `MlvMessage`
+- `@angular/forms/signals` — signal-form field binding (consumer side); reactive forms and `ngModel` remain compatible
+
+## Signal-forms constraint alignment (2026-07)
+
+- `maxLength`/`minLength`/`step` write-accept `undefined` (→ `null`); `min`/`max` write-accept `number|string|null|undefined` (contract binds `NonNullable<TValue>|undefined` = `string`); `name` write-accepts `undefined`; `pattern` write-accepts `string | RegExp | readonly RegExp[]` (normalised to a single OR-combined source for the native attribute). Reason: `[formField]` auto-binds same-named `FormUiControl` members; strict AOT failed on the old narrower types (caught only by `docs:build`).
+
+## Signal-forms cutover (2026-07, slice 1)
+
+- `value = model<string>('')` — the `FormValueControl` model; replaces the old one-way `value` input + `internalValue` signal + CVA plumbing (`writeValue`/`registerOn*`/`setDisabledState` gone; `NG_VALUE_ACCESSOR` provider removed). `clearValue()` stays (`value.set('')`).
+- Blur reports `touch` output (base `_markTouched`) instead of CVA `onTouched`.
+- Bound validation `errors` make `resolvedState()` return `error` after `touched`; an explicit non-default `[state]` still wins. The same resolved state drives the input host, internal `MlvFormControlWrapper`, and native `aria-invalid`.
+- Composite one-way binders (`[value]="searchQuery()"` in combobox etc.) keep working — a model accepts one-way binding; template renders `value() ?? ''` defensively.
+
+---
+
+## Field surface (2026-08)
+
+- `ariaLabel` moved to `MlvSignalFormUiControlBase`; `MlvInput` no longer declares it (same name, same `string | null` type, same `aria-label` binding).
+- New `ariaDescribedBy` (`string | null`, `null`) — an explicit `aria-describedby` override for the native `<input>`, taking precedence over the ids derived from `description`/`message`. Composite controls that render their own chrome (`mlv-combobox`, `mlv-tokenizer`, `mlv-pin-input`) point the inner bare input at their own description/message ids through it.
+- Inherited `required` renders the `mlv-label` marker and sets `aria-required` on the native `<input>`.
+- Inherited `description` renders `<mlv-description>` below the control (wrapped mode only — `bare` renders no chrome).
+- The non-reactive `messageId` string field is gone; `<mlv-message>` now carries the base's `_messageId()` so `aria-describedby` resolves even when a consumer sets `[id]`.