@malva-ui/core 0.1.13 → 0.1.14

package/docs/ai/dropdown.md

@@ -14,7 +14,7 @@ Exported from `@malva-ui/core/dropdown`:
 | Export | Kind | Description |
 |--------|------|-------------|
 | `MlvDropdownPanel<T>` | Component | Dropdown list panel — `mlv-dropdown-panel` |
-| `MlvSelectOption<T>` | Interface | `{ label: string; value: T; group?: string }` |
+| `MlvSelectOption<T>` | Interface | `{ label: string; value: T; group?: string; disabled?: boolean }` |
 | `MlvSelectOptionTransform<T>` | Type | `(item: T) => MlvSelectOption<T>` |
 | `defaultOptionTransform<T>` | Function | Converts item using `String(item)` as label |
 | `isSelectOption<T>` | Function | Type-guard: value is `MlvSelectOption`-shaped (`label` + `value`) |
@@ -52,24 +52,25 @@ Exported from `@malva-ui/core/dropdown`:
 
 #### Inputs
 
-| Name                      | Type                                                     | Default      | Description                                                                                                                                                                                                                                                                                                                                                                                                       |
-| ------------------------- | -------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `options`                 | `MlvSelectOption<T>[]`                                   | `[]`         | Options to display                                                                                                                                                                                                                                                                                                                                                                                                |
-| `multiple`                | `boolean`                                                | `false`      | Multi-select mode                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `selectedValues`          | `T[]`                                                    | `[]`         | Currently selected values                                                                                                                                                                                                                                                                                                                                                                                         |
-| `minHeight`               | `number`                                                 | `0`          | Minimum height in px                                                                                                                                                                                                                                                                                                                                                                                              |
-| `maxHeight`               | `number`                                                 | `0`          | Max height in px; `0` = 40% of viewport                                                                                                                                                                                                                                                                                                                                                                           |
-| `itemTemplate`            | `TemplateRef<{ $implicit: MlvSelectOption<T> }> \| null` | `null`       | Custom item renderer                                                                                                                                                                                                                                                                                                                                                                                              |
-| `listboxId`               | `string \| null`                                         | `null`       | HTML `id` set on the inner `<mlv-list>` so a parent select/combobox can reference the listbox via `aria-controls`                                                                                                                                                                                                                                                                                                 |
-| `focusMode`               | `'roving' \| 'activedescendant'`                         | `'roving'`   | Forwarded to the inner aria listbox. `'activedescendant'` keeps DOM focus on the owning trigger/input (used by `mlv-combobox`); `'roving'` moves focus onto the active option (used by `mlv-select`).                                                                                                                                                                                                             |
-| `activeIndex`             | `number`                                                 | `-1`         | Index of the activedescendant-active (highlighted) option; `-1` = none. Renders `.mlv-dropdown-panel__item--active` on that row and drives a deterministic option `id`.                                                                                                                                                                                                                                           |
-| `highlightQuery`          | `string`                                                 | `''`         | When non-empty, the default option row emphasises the matched substring of this query in each label (via `MlvHighlightMatchPipe` → `<mark class="mlv-dropdown-panel__match">`). Ignored for custom `itemTemplate` rows. Empty = plain label (unchanged). Used by `mlv-combobox` and `[mlvAutocomplete]`.                                                                                                          |
-| `loading`                 | `boolean`                                                | `false`      | Renders a loading affordance (spinner + `loadingText`, `role="status"`) above the list and suppresses the empty `<ng-content>` projection. Also sets the `--loading` host modifier and `aria-busy` on the listbox — previous options stay mounted, readable and interactive; the default row renders in the secondary text colour while loading (custom `itemTemplate` rows own their colours and are untouched). |
-| `loadingText`             | `string`                                                 | `'Loading…'` | Text announced inside both loading affordances (top row and `loadingMore` bottom row).                                                                                                                                                                                                                                                                                                                            |
-| `loadingMore`             | `boolean`                                                | `false`      | A page **beyond the first** is in flight: renders a polite `role="status"` row (`.mlv-dropdown-panel__loading-more`) after the last option and sets `aria-busy` on the listbox. Options stay interactive and are not dimmed.                                                                                                                                                                                      |
-| `hasMore`                 | `boolean`                                                | `false`      | Whether more pages exist. Arms the paging sentinel — see **Lazy-loading pagination** below.                                                                                                                                                                                                                                                                                                                       |
-| `infiniteScrollThreshold` | `number`                                                 | `150`        | Distance (px) from the end of the scroll owner at which `loadMore` fires.                                                                                                                                                                                                                                                                                                                                         |
-| `scrollMode`              | `'self' \| 'parent'`                                     | `'self'`     | Selects the single scroll owner. Standalone panels render their own `mlv-scrollbar`; panels inside `mlv-popup` delegate scrolling to the popup to avoid nested scroll regions.                                                                                                                                                                                                                                    |
+| Name                      | Type                                                     | Default      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------------- | -------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`                 | `MlvSelectOption<T>[]`                                   | `[]`         | Options to display                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `multiple`                | `boolean`                                                | `false`      | Multi-select mode                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `selectedValues`          | `T[]`                                                    | `[]`         | Currently selected values                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `minHeight`               | `number`                                                 | `0`          | Minimum height in px                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `maxHeight`               | `number`                                                 | `0`          | Max height in px; `0` = 40% of viewport                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `itemTemplate`            | `TemplateRef<{ $implicit: MlvSelectOption<T> }> \| null` | `null`       | Custom item renderer                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `listboxId`               | `string \| null`                                         | `null`       | HTML `id` set on the inner `<mlv-list>` so a parent select/combobox can reference the listbox via `aria-controls`                                                                                                                                                                                                                                                                                                                                                                             |
+| `ariaLabel`               | `string \| null`                                         | `null`       | Accessible name rendered as `aria-label` on the inner listbox. `role="listbox"` is an ARIA input field (axe `aria-input-field-name`, WCAG 4.1.2), so a panel not already named through an owning control needs one — `mlv-filter` passes its field label, and `mlv-select` / `mlv-combobox` each pass their own resolved trigger name (`_panelAriaLabel`: the visible `label`, else the explicit `ariaLabel` input). `null` renders no attribute — an unlabelled consumer's DOM is unchanged. |
+| `focusMode`               | `'roving' \| 'activedescendant'`                         | `'roving'`   | Forwarded to the inner aria listbox. `'activedescendant'` keeps DOM focus on the owning trigger/input (used by `mlv-combobox`); `'roving'` moves focus onto the active option (used by `mlv-select`).                                                                                                                                                                                                                                                                                         |
+| `activeIndex`             | `number`                                                 | `-1`         | Index of the activedescendant-active (highlighted) option; `-1` = none. Renders `.mlv-dropdown-panel__item--active` on that row and drives a deterministic option `id`.                                                                                                                                                                                                                                                                                                                       |
+| `highlightQuery`          | `string`                                                 | `''`         | When non-empty, the default option row emphasises the matched substring of this query in each label (via `MlvHighlightMatchPipe` → `<mark class="mlv-dropdown-panel__match">`). Ignored for custom `itemTemplate` rows. Empty = plain label (unchanged). Used by `mlv-combobox` and `[mlvAutocomplete]`.                                                                                                                                                                                      |
+| `loading`                 | `boolean`                                                | `false`      | Renders a loading affordance (spinner + `loadingText`, `role="status"`) above the list and suppresses the empty `<ng-content>` projection. Also sets the `--loading` host modifier and `aria-busy` on the listbox — previous options stay mounted, readable and interactive; the default row renders in the secondary text colour while loading (custom `itemTemplate` rows own their colours and are untouched).                                                                             |
+| `loadingText`             | `string`                                                 | `'Loading…'` | Text announced inside both loading affordances (top row and `loadingMore` bottom row).                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `loadingMore`             | `boolean`                                                | `false`      | A page **beyond the first** is in flight: renders a polite `role="status"` row (`.mlv-dropdown-panel__loading-more`) after the last option and sets `aria-busy` on the listbox. Options stay interactive and are not dimmed.                                                                                                                                                                                                                                                                  |
+| `hasMore`                 | `boolean`                                                | `false`      | Whether more pages exist. Arms the paging sentinel — see **Lazy-loading pagination** below.                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `infiniteScrollThreshold` | `number`                                                 | `150`        | Distance (px) from the end of the scroll owner at which `loadMore` fires.                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `scrollMode`              | `'self' \| 'parent'`                                     | `'self'`     | Selects the single scroll owner. Standalone panels render their own `mlv-scrollbar`; panels inside `mlv-popup` delegate scrolling to the popup to avoid nested scroll regions.                                                                                                                                                                                                                                                                                                                |
 
 #### Outputs
 
@@ -129,6 +130,8 @@ The panel always has exactly one themed scroll owner. Standalone/autocomplete pa
 - `listRole="listbox"` on the `<mlv-list>` and `itemRole="option"` on each `<mlv-list-item>` — required so aria's pointer selection can resolve options via `closest('[role="option"]')`.
 - `selectionMode="explicit"` + `[softDisabled]="false"` — arrow keys move focus without committing the value and skip disabled options.
 - `[label]="option.label"` on each item — feeds aria's type-ahead search.
+- `[disabled]="option.disabled ?? false"` on each item — forwarded to aria's `Option`, which renders `aria-disabled`; disabled options are skipped by keyboard navigation (see `[softDisabled]="false"` above) and cannot be selected.
+- `[attr.aria-label]="ariaLabel()"` on the `<mlv-list>` — the accessible name for the listbox, absent unless a consumer sets `ariaLabel`.
 - `[listboxId]="_resolvedListboxId()"` on the `<mlv-list>` — forwards the id into aria's `Listbox.id` input (re-exposed as `listboxId` by `MlvListSelectable`). aria renders it via `[attr.id]="id()"`, so the DOM id equals the value the parent select/combobox `aria-controls` points to. Binding the native `[id]` instead does **not** work — aria's own `[attr.id]` overrides it, minting a `ng-listbox-*` id and dangling `aria-controls`. `_resolvedListboxId()` is `listboxId()` when set, else a stable `mlvNextId('mlv-dropdown-listbox')` fallback so the listbox always carries a valid unique id.
 
 The listbox sets `--mlv-list-padding-block` and `--mlv-list-padding-inline` so option rows keep x-axis breathing room inside select/combobox popups.
@@ -163,6 +166,8 @@ export interface MlvSelectOption<T = unknown> {
   value: T;
   /** Optional group label — clusters options under a sticky, non-selectable header. */
   group?: string;
+  /** Whether the option is unavailable for selection. Skipped by keyboard navigation. */
+  disabled?: boolean;
 }
 
 export type MlvSelectOptionTransform<T> = (item: T) => MlvSelectOption<T>;

package/docs/ai/empty-state.md

@@ -82,7 +82,7 @@ Each slot wrapper hides itself with `display: none` when empty, so unused slots
   &__icon                      — flex center; color: --mlv-text-tertiary; :empty → display:none
   &__body                      — flex column, center, gap 0.5rem; :empty → display:none
   &__title                     — h4-sized heading, font-weight 600, color --mlv-text-secondary; :empty → display:none
-  &__description               — body text, color --mlv-text-tertiary, max-width 28rem; :empty → display:none
+  &__description               — body text, color --mlv-text-secondary, max-width 28rem; :empty → display:none
   &__actions                   — flex wrap, centered, gap 0.5rem; :empty → display:none
 ```
 
@@ -90,8 +90,8 @@ Each slot wrapper hides itself with `display: none` when empty, so unused slots
 
 | Token                          | Where used                        |
 | ------------------------------ | --------------------------------- |
-| `--mlv-text-tertiary`          | Icon color, description color     |
-| `--mlv-text-secondary`         | Title color                       |
+| `--mlv-text-tertiary`          | Icon color (decorative only)      |
+| `--mlv-text-secondary`         | Title and description color       |
 | `--mlv-typography-family-text` | Title and description font family |
 | `--mlv-typography-heading-h4`  | Title font size                   |
 | `--mlv-font-size-m`            | Description font size             |

package/docs/ai/filter.md

@@ -8,32 +8,51 @@
 
 ### `MlvFilter` (`mlv-filter`)
 
-- Inputs: `label`, `key`, `options`, `editor`, `multiple`, `allowMultipleConditions`, `operators`, `operatorLabels`, `defaultOperator`, `placeholder`, `applyMode`, `disabled`, `loading`, `invalid`, and `ariaDescribedBy`.
+- Inputs: `label`, `key`, `appearance`, `options`, `editor`, `multiple`, `allowMultipleConditions`, `operators`, `operatorLabels`, `defaultOperator`, `placeholder`, `applyMode`, `disabled`, `loading`, `invalid`, `ariaDescribedBy`, and `valueEditor`. `appearance` defaults to `field`; `query` presents a natural-language sentence chip with a labelled remove action.
 - Models: `conditions`, `conditionStrategy`, and `opened`.
 - Outputs: `applied` and `cleared`.
 - Option editors support one or many values. Text/number editors support operator selection, optional multiple conditions, OR-by-default composition (overridable with `conditionStrategy`), and either live or explicit Apply/Cancel behavior.
+- The bounded options editor renders the shared `mlv-dropdown-panel` (`@malva-ui/core/dropdown`) inside the popover — the same primitive `mlv-select` / `mlv-combobox` use — so option rows, per-option `disabled`, selection tokens and listbox keyboard behavior come from `@angular/aria` instead of a hand-rolled roving-tabindex list. `mlv-filter` provides `MlvSelectionService` for the panel and names the listbox with `[ariaLabel]="label()"`; a disabled or loading filter marks every row disabled so a panel already open when loading starts stops offering picks it would reject, and `maxHeight` keeps the option slab at the previous 20rem budget rather than the panel's taller viewport-derived default. The panel keeps its default `scrollMode="self"` here rather than the `scrollMode="parent"` that `mlv-select` / `mlv-combobox` bind inside their own `mlv-popup` (see `libs-dropdown.md`) — the popover's pinned title/Clear header and (explicit-mode) Cancel/Apply footer must stay outside the scroll region, so the option list needs its own self-owned, bounded (320px / 20rem) scroll area rather than scrolling the whole popup content underneath them. Selection round-trips to conditions: single-select commits `equals` and closes the popover (clicking the selected row again deselects it, aria's toggle semantics), multi-select accumulates one `in` condition and keeps it open.
+- aria's listbox owns a `value` model that it reconciles against the options actually _registered_ in the DOM, re-emitting `valueChange` from that reconciliation and not only from user picks. `mlv-filter` filters both shapes of noise before anything rewrites the draft: an emit that restates the selection unchanged (compared as a multiset via `fast-equals`, so duplicates and structured values are handled) and an emit that drops committed values with no rendered option (`isReconciliationEmit` from `@malva-ui/core/dropdown`, compared with `Object.is` to mirror aria's own matching). A committed value whose option has not arrived yet — async options, a saved view restored ahead of its choices, a removed choice — therefore survives opening the popover, and `filteredOutCommitted` re-adds it to a genuine multi-select pick instead of letting one extra pick discard the rest. Closing on a restated single-select emit is live-mode only: an explicit draft is resolved by Apply/Cancel alone.
+- **Clear reseed.** The panel's Clear action always empties the _committed_ conditions (`[]`, live mode commits immediately; explicit mode stages it for Apply/Cancel). For a free-form (non-options) editor the _draft_ reseeds to one empty condition instead of zero, so the popover never dead-ends with no condition row to fill back in; a bounded options editor's draft clears to `[]` outright since its rows come from `options`, not a user-typed condition. Applying the reseeded draft unchanged still commits `[]` and emits `cleared`.
+
+### Custom value editor
+
+- `MlvFilterValueEditorDef` (`ng-template[mlvFilterValueEditor]`) replaces the built-in value input of a free-form condition with any consumer control (date picker, tokenizer, remote picker). Project it into `mlv-filter`, or pass a `TemplateRef` to the `valueEditor` input — the input wins over the projected content child.
+- The directive's own `mlvFilterValueEditor` key input (default `''`) targets one smart-filter-bar definition key; an empty key is the fallback for every free-form field. `mlv-smart-filter-bar` collects every `MlvFilterValueEditorDef` projected as its content children and resolves the template for each definition itself: an exact `mlvFilterValueEditor` key match on that definition's `key` wins; otherwise the key-less (`''`) fallback template applies if one is projected; otherwise the built-in editor renders. At most one exact-key and one fallback template are consulted — a second template for the same key or a second key-less template is never disambiguated further (first match by content-child order).
+- Template context (`MlvFilterValueEditorContext`): `$implicit` (current value, or the `between` range array), `condition`, `index`, `operator`, `disabled`, `placeholder`, `setValue(value)`, and `commit()`. `setValue` writes the draft and commits immediately in live mode; `commit()` applies the draft in explicit mode and is a no-op in live mode.
+- The slot replaces both the single-value input and the `between` range pair, is not rendered for valueless operators (`empty` / `not-empty`), and never replaces the lib-owned operator select. Opening the editor focuses the first focusable control inside the rendered value cell.
 
 ### `MlvSmartFilterBar` (`mlv-smart-filter-bar`)
 
 - `definitions` is the required metadata source for available fields, editor types, operators, defaults, required fields, and initial visibility.
 - Models: `filters`, `visibleKeys`, `searchValue`, and `filtersVisible`.
-- Execution inputs: `searchTrigger`, `searchDebounce`, `filterApplyMode`, `autoExecute`, `showSearch`, `loading`, and `disabled`.
+- Execution inputs: `appearance`, `searchTrigger`, `searchDebounce`, `filterApplyMode`, `autoExecute`, `showSearch`, `loading`, and `disabled`. `appearance` defaults to `classic`; `query` adds searchable filter discovery, sentence chips, Clear all, and an Apply action only for explicit field mode.
 - Outputs: `execute`, `refresh`, and `resetCompleted`.
 - Public actions: `executeQuery()`, `refreshQuery()`, `clear()`, and `resetToDefaults()`.
 - Required definitions remain visible and block `execute` and `refresh` while empty. A blocked query exposes localized summary and field errors, expands the filter row, and focuses the first incomplete field.
 - Active filters remain visible and cannot be hidden in the manager until their conditions are cleared; removed metadata keys are pruned and surviving state/visibility is normalized to metadata order.
+- The `query`-appearance **Add filter** trigger (`.mlv-smart-filter-bar__add`) is a dashed, secondary-text-toned chip — `border: dashed var(--mlv-border-normal)` with a leading `lucidePlus` glyph — that darkens to `--mlv-text-primary` on hover; it inherits `mlvButton`'s default `--mlv-btn-radius` (`--mlv-radius-button` = `--mlv-radius-l`, 8px) rather than overriding it, matching the dominant corner radius of the sibling `--query` filter-trigger sentence chips.
 - Asynchronous and changing definition sets initialize new defaults without re-adding previously hidden defaults.
 - The available-filters manager is a focus-trapped modal, stages visibility edits, and commits or discards the draft through Apply/Cancel.
 - Loading disables query, toolbar, filter, and manager controls consistently.
 
 ### Neutral model
 
-The entry point exports `MlvFilterOperator`, `MlvFilterCondition`, `MlvFilterConditionStrategy`, `MlvFilterApplyMode`, `MlvFilterOption`, `MlvFilterDefinition`, `MlvFilterFieldState`, and `MlvFilterExecutionPayload`. Definitions may override built-in translated operator labels with domain-specific `operatorLabels`. Execution payloads deeply clone supported nested option values so consumers cannot mutate internal state through an emitted snapshot.
+The entry point exports `MlvFilterOperator`, `MlvFilterCondition`, `MlvFilterConditionStrategy`, `MlvFilterApplyMode`, `MlvSmartFilterBarAppearance`, `MlvFilterOption`, `MlvFilterDefinition`, `MlvFilterFieldState`, and `MlvFilterExecutionPayload`. Definitions may override built-in translated operator labels with domain-specific `operatorLabels`. Execution payloads deeply clone supported nested option values so consumers cannot mutate internal state through an emitted snapshot, retain the flat `filters` model, and include its equivalent grouped `expression`.
+
+### Grouped expressions
+
+`MlvFilterExpression` is a recursive, readonly condition/group tree. Use `mlvFilterFieldsToExpression()` to adapt the existing flat field state without changing its public contract: fields compose in a top-level `and`; multi-condition fields become an ordered group using their `strategy`; empty fields are omitted as no-ops.
+
+`mlvFilterExpressionToFields()` is intentionally conservative. It normalizes boolean identities before flattening: empty `and` is true and maps to `[]`; empty `or` is false and maps to `null` when it is the whole expression or an AND child, but is ignored inside a larger OR; a true AND child dominates an OR and maps to `[]`. It then flattens nested `and` groups and same-field `or` groups, but returns `null` for cross-field `or` and mixed same-field compositions that cannot be represented by one field strategy without changing their meaning. Direct condition leaves and singleton groups normalize to the semantically-neutral `and` strategy; a one-condition flat field therefore cannot round-trip its irrelevant strategy marker.
+
+`mlvMatchesFilterExpression(value, expression, readValue)` evaluates a tree against any domain model through the supplied `(value, key) => unknown` reader. Empty groups follow boolean identities: `and` is true and `or` is false. `contains`, `not-contains`, `starts-with`, and `ends-with` stringify nullish values as empty strings and compare case/diacritic-insensitively. `equals`/`not-equals` and `in`/`not-in` use strict identity; membership requires an array operand and does not expand an array-valued field. Numeric comparisons accept finite numbers or nonblank numeric strings; `between` is inclusive, requires exactly two ordered finite bounds, and invalid numeric/range inputs do not match. `empty`/`not-empty` ignore their operands and recognize nullish values, `''`, and empty arrays.
 
 ## Accessibility and i18n
 
-- Native buttons plus dialog/listbox semantics provide keyboard activation; bounded options use roving focus with Arrow, Home, and End navigation.
-- Popovers focus their editor on open and restore the invoking control on close; the available-filter manager traps focus while open.
+- Native buttons plus dialog/listbox semantics provide keyboard activation; bounded options inherit the `mlv-dropdown-panel` listbox — `@angular/aria` owns Arrow/Home/End navigation, type-ahead, and skipping disabled options.
+- Popovers focus their editor on open and restore the invoking control on close; a bounded editor lands on the listbox's roving tab stop, which aria parks on the committed option (first focusable otherwise). The available-filter manager traps focus while open.
 - Required validation uses `aria-invalid`, field descriptions, and a localized alert summary.
 - Every built-in label, operator, strategy, action, summary, and accessible name resolves through `MLV_FILTER_I18N`; definitions and inputs supply domain copy.
 - English and Spanish language packs cover the full operator set.

package/docs/ai/form-utils.md

@@ -16,7 +16,7 @@ Exported from `@malva-ui/core/form-utils`:
 > **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` |
+| `MlvHint` | Component | Label hint — `mlv-hint`; renders a question-mark icon + tooltip |
 | `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 |
@@ -99,7 +99,8 @@ When the selected strategy makes an error visible, `resolvedState()` becomes `er
 | `for`      | `string`             | `''`    |
 | `required` | `boolean` (`coerce`) | `false` |
 
-Renders `<label [attr.for]="for">`. Supports nested `<mlv-hint>`.
+Renders `<label [attr.for]="for">`. Supports nested `<mlv-hint>`, projected into
+`.mlv-label__hint` — which renders as an icon + tooltip, not inline text (see `MlvHint`).
 
 `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
@@ -111,10 +112,70 @@ usage can set it directly.
 
 ### `MlvHint`
 
-**Selector:** `mlv-hint`
+**Selector:** `mlv-hint` | **Change Detection:** `OnPush`
 
-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).
+Secondary hint for the control named by the enclosing `mlv-label`. Authored as **projected
+content** (`<mlv-hint>Sent to your phone</mlv-hint>`) — that is the whole public API, there are
+no inputs — but it **renders as a small `circle-question-mark` icon button** (`LucideCircleQuestionMark`,
+`[size]="14"`) that reveals the text in an `[mlvTooltip]` on hover **and** on keyboard focus.
+Use `mlv-description` for sentence-length help text that should stay permanently visible below
+the control.
+
+**Why an icon and not inline text.** The hint used to render as text directly inside the
+label's `display: inline-flex` row, so a long hint became a flex sibling of the label text and
+forced the label to wrap mid-phrase. An icon is a fixed-size sibling, so the label row stays on
+one line at any hint length.
+
+#### DOM
+
+```html
+<mlv-hint class="mlv-hint">
+  <!-- rendered only while the projected text is non-empty -->
+  <button type="button" class="mlv-hint__trigger" aria-label="<hint text>" [mlvTooltip]="<hint text>">
+    <svg lucideCircleQuestionMark aria-hidden="true" />
+  </button>
+  <span class="mlv-hint__source" aria-hidden="true"><!-- projected content --></span>
+</mlv-hint>
+```
+
+#### How the tooltip string is obtained
+
+`mlvTooltip` needs a `string`, but the public API is content projection. The projected content
+is rendered into `.mlv-hint__source`, which is `display: none` (`textContent` still resolves on
+a non-displayed element) and read into a private `_text` signal:
+
+- The first read happens in `afterNextRender`, so it never runs during SSR.
+- A `MutationObserver` (`childList` + `characterData` + `subtree`) keeps `_text` in sync, which
+  is what makes the interpolated form every control uses — `<mlv-hint>{{ hint() }}</mlv-hint>` —
+  update at runtime. An `effect()` would **not** work here: `textContent` is not a reactive read,
+  and the mutated text node belongs to the _parent_ view. The observer is disconnected via
+  `DestroyRef.onDestroy`. Re-setting the signal to an identical string is a no-op, so there is no
+  render loop.
+
+#### Accessibility
+
+- `.mlv-hint__source` is `aria-hidden`. Previously the hint text sat inside the `<label>` and
+  leaked into the labelled control's accessible name (`"Full name Shown on every comment"`).
+  Hiding it yields a clean control name; the same string is placed on the trigger's `aria-label`,
+  so the hint stays reachable to assistive tech via the icon.
+- The trigger is a real `<button type="button">`, so it is in the tab order, activates on
+  Enter/Space, and gets a `:focus-visible` ring (`--mlv-border-focus`). `MlvTooltip` opens on
+  `focusin` as well as `mouseenter`, so keyboard users get the hint, and closes on `Escape`.
+- **No trigger is rendered while the projected text is empty.** An empty `<mlv-hint>` would
+  otherwise leave a nameless icon button behind — an AXE `button-name` violation. (This is why
+  the component uses an `@if` rather than `MlvTooltip`'s `tooltipDisabled`.)
+- The click handler calls **both** `preventDefault()` and `stopPropagation()`. The trigger is a
+  `<button>` nested inside a `<label>`: `preventDefault()` stops the label's native
+  "focus the labelled control" behaviour, and `stopPropagation()` stops click handlers bound on
+  `mlv-label` itself — `mlv-select` binds one there to open its dropdown — from firing when the
+  user only wanted to read the hint.
+
+#### Styling
+
+`hint.css` is a plain global stylesheet (`ViewEncapsulation.None`), so it selects the BEM block
+class `.mlv-hint` bound from `host`, not `:host` (which never matches outside a shadow tree).
+`mlv-label` styles `.mlv-label__hint` as `display: inline-flex; align-self: center` so the icon
+sits on the row's centre line instead of the text baseline the label row is built on.
 
 ---
 
@@ -177,6 +238,96 @@ host: {
 }
 ```
 
+> **One validation ring (SF-R6).** Only `state="error"` colours the container
+> border (`--container-border-color: var(--mlv-border-error)`). `success`,
+> `info` and `warning` deliberately paint no ring — their meaning lives
+> entirely in the adjacent `mlv-message` text, so a form with mixed states
+> reads as one alarm rather than four coloured perimeters. `disabled` and
+> `readonly` stay fully achromatic, differentiated by fill and text colour
+> only. The default-state hover border also moved off the raw palette stop
+> (`neutral-300`) onto `--mlv-border-strong`, which is the same pixel in
+> light but fixes a dark-mode bug where a hovered field drew a near-white
+> border. The focused-state ring width is `var(--mlv-stroke-width)` (not a
+> literal `1px`).
+
+#### Control-text type & padding ramp (2026-08-26)
+
+`.mlv-form-control-wrapper` declares the **one** density-scaled type/padding
+ramp every text-style control obeys — `--form-ctrl-font-size` (block) /
+`--form-ctrl-h-padding` (inline, combined into `--mlv-control-padding` with
+the constant `--mlv-spacing-1` block half):
+
+| density     | `--form-ctrl-font-size`   | `--form-ctrl-h-padding` |
+| ----------- | ------------------------- | ----------------------- |
+| tight       | `--mlv-font-size-s` (12)  | `--mlv-spacing-2`       |
+| compact     | `--mlv-font-size-m` (14)  | `--mlv-spacing-2-5`     |
+| comfortable | `--mlv-font-size-m` (14)  | `--mlv-spacing-3`       |
+| spacious    | `--mlv-font-size-l` (16)  | `--mlv-spacing-4`       |
+| airy        | `--mlv-font-size-xl` (18) | `--mlv-spacing-5`       |
+
+Matches CH-R3 in `docs/superpowers/specs/2026-08-24-visual-language-spec.md`.
+Both custom properties are declared once here and **inherited** by every
+descendant of the wrapper — `mlv-input`, `mlv-textarea`, `mlv-number-input`,
+the `mlv-select` / `mlv-combobox` / `mlv-day-picker` / `mlv-time-picker`
+trigger text, and (via projection) `mlv-label`, `mlv-description` and
+`mlv-message` all render inside the wrapper's DOM. A control's own SCSS must
+read `var(--form-ctrl-font-size, var(--mlv-font-size-m))` /
+`var(--mlv-control-padding)` rather than a literal or a different token —
+see `mlv-input__native` and `mlv-number-input__native` for the reference
+pattern.
+
+`mlv-label` is the one exception: it is a **sibling** of the wrapper (both
+are projected children of the owning control), not a descendant, so it
+cannot inherit `--form-ctrl-font-size` through the DOM. `label.scss` instead
+carries its own copy of the same five values via the `density.*` mixins, so
+a label still reads at the size of the field it names at every density.
+
+**2026-08-26 fix.** Before this pass, `mlv-input__native` declared a flat,
+non-ramped `padding: var(--mlv-spacing-1)` on top of the wrapper's own
+(already ramped) container padding — a doubled, non-scaling inline padding
+found on no other control. It now follows the same pattern as
+`mlv-select`/`mlv-combobox`/`mlv-time-picker`/`mlv-number-input`: the
+wrapper's `__control-container` padding is zeroed and `mlv-input__native`
+owns the full `var(--mlv-control-padding)` itself. Several controls also
+carried a hardcoded `--mlv-font-size-l` instead of the ramp (`mlv-input`,
+`mlv-number-input`, `mlv-tokenizer`'s overflow badge, `mlv-combobox`'s empty
+row) or diverged from the ramp's exact steps (`mlv-switch`'s `compact` /
+`airy` label size). `mlv-checkbox` and `mlv-radio` had no label type ramp at
+all. All are now on the shared ramp; see
+`docs/superpowers/specs/2026-08-24-visual-language-spec.md` CH-R3 and the
+form-density-standardization report
+(`.superpowers/sdd/form-density-standardization-report.md`) for the full
+before/after inventory. `mlv-pin-input`'s cell text and `mlv-rating` (no
+visible text) are documented exceptions and stay off the ramp.
+
+**Superseded (2026-08-26, round 2 of the same day).** The "zero the
+container, `mlv-input__native` owns the full padding" fix above turned out to
+be correct only for controls whose entire row lives inside one element they
+own outright (`mlv-select`/`mlv-combobox`/`mlv-time-picker`/`mlv-number-input`).
+`mlv-input`'s prefix/suffix (`*mlvFormControlPrepend`/`*mlvFormControlAppend`)
+are separate siblings rendered by the wrapper's own generic slots — zeroing
+the container stripped their only inset while the native input's now-full
+padding pushed text in from the other side, breaking every prefix/suffix
+consumer (`mlv-search-field`, currency-style `mlv-input` prefix/suffix
+examples). `mlv-input__native` now declares **no** padding of its own in
+either mode; the row's one shared inset comes from whichever ancestor already
+supplies it — the wrapper's own un-zeroed default for `mlv-input`'s default
+mode, or the embedding composite's own trigger row in `bare` mode. See the
+report's Round 3 §1 for the full before/after.
+
+**Affordance-glyph size ramp (2026-08-26, round 3).** A second shared token,
+`--form-ctrl-icon-size: calc(var(--form-ctrl-height) * var(--mlv-icon-in-container-ratio))`,
+declared alongside the type/padding ramp above — reuses CH-R4's
+`--mlv-icon-in-container-ratio` (0.45) anchored to the field's own height.
+Every form-control affordance glyph (leading/trailing icons, chevrons, the
+generic clear button) now reads this instead of a fixed `1.25rem`, a
+row-text-relative `em`, or a button-local ratio pinned to a fixed density.
+Resolves to 12.6 / 16.2 / 19.8 / 23.4 / 27px across tight → airy. See the
+report's Round 3 §3–4 for the full consumer table, the two "direct
+declaration beats inherited value" gotchas it surfaced, and the matching
+`--mlv-text-tertiary` → `--mlv-text-primary` colour ramp (mirroring
+`.mlv-select__arrow`).
+
 ---
 
 ## Directives
@@ -245,6 +396,7 @@ Implements `ControlValueAccessor`. Extend to create custom form controls.
 <mlv-form-field displayStrategy="touched">
   <mlv-label for="email">
     Email
+    <!-- renders as a question-mark icon; the text shows in a tooltip -->
     <mlv-hint>We'll contact you here</mlv-hint>
   </mlv-label>
   <input id="email" type="email" [formControl]="emailCtrl" />
@@ -266,6 +418,9 @@ Implements `ControlValueAccessor`. Extend to create custom form controls.
 
 - `@angular/core`, `@angular/forms` — CVA, reactive forms
 - `@angular/cdk/coercion` — boolean coercion
+- `@lucide/angular` — `LucideCircleQuestionMark` for the `mlv-hint` trigger
+- `@malva-ui/core/tooltip` — `MlvTooltip`, which reveals the `mlv-hint` text
+- `@malva-ui/core/button` — `MlvClearMlvButton` chrome
 
 ## Clearable value-gating (2026-07)
 

package/docs/ai/icon-toggle.md

@@ -0,0 +1,160 @@
+# Library: icon-toggle
+
+## Overview
+
+`@malva-ui/core/icon-toggle` provides a **chromeless, glyph-only** WAI-ARIA
+toggle button (`button[mlvIconToggle]`) — visual-language spec **AB-R7**. It
+wraps exactly one projected Lucide `<svg>` and expresses `pressed` purely
+through the glyph itself: an outlined icon at rest, a "tiny fill" on hover,
+and a full `fill: currentColor` when pressed. There is **no background in any
+state** — the defining constraint. An optional `tone` recolours only the
+pressed glyph to a matching semantic text token (e.g. a favourite star).
+
+Built to replace ad hoc "tinted circle behind a glyph" treatments — see the
+support-inbox star (exhibit B), which adopts this component in the showcase
+sweep, not here.
+
+- **Leaf project (Nx):** `core-icon-toggle` at *(internal)*
+- **Secondary entry point:** `@malva-ui/core/icon-toggle` (also re-exported from the grouped `@malva-ui/core` barrel)
+- **Package tag:** `scope:ui`
+
+## Public API
+
+Exported from `@malva-ui/core/icon-toggle`:
+
+| Symbol          | Kind      | Selector                | Description                          |
+| --------------- | --------- | ----------------------- | ------------------------------------ |
+| `MlvIconToggle` | Component | `button[mlvIconToggle]` | Chromeless glyph-only toggle button. |
+
+`MlvTone` (the `tone` input's type) is not re-exported here — import it from `@malva-ui/cdk/utils`.
+
+## Component
+
+### `MlvIconToggle` — `button[mlvIconToggle]`
+
+- **Change detection:** `OnPush` · **Encapsulation:** `None`
+- **Template:** `<ng-content />` — the host **is** the native `<button>`;
+  the consumer projects exactly one Lucide `<svg>` and nothing else. Follows
+  the repo's `button[mlvButton]` attribute-selector-on-native-element pattern
+  (`.claude/rules/angular-component.md` § Selectors): native `disabled`,
+  `type`, and click/keyboard activation semantics all work unmodified — no
+  custom keydown handling is added, so Enter/Space activate through the
+  browser's native button semantics exactly like a plain `<button>`.
+
+#### Inputs / Model
+
+| Name       | Type                   | Default     | Description                                                                                                                                                                                                                                               |
+| ---------- | ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pressed`  | `model<boolean>`       | `false`     | Two-way bindable pressed state, reflected as `aria-pressed`. Bind one-way (`[pressed]` + `(pressedChange)`) when a caller owns the source of truth — same convention as `mlv-button-toggle`.                                                              |
+| `tone`     | `MlvTone \| undefined` | `undefined` | Recolours only the **pressed** glyph to the matching semantic text token (`info` → `--mlv-text-info`, `success` → `--mlv-text-positive`, `warning` → `--mlv-text-warning`, `danger` → `--mlv-text-negative`). Rest/hover stay neutral regardless of tone. |
+| `disabled` | `boolean` (coerced)    | `false`     | Native `disabled` + `aria-disabled`.                                                                                                                                                                                                                      |
+
+#### Host bindings
+
+```ts
+host: {
+  class: 'mlv-icon-toggle',
+  '[class.mlv-icon-toggle--pressed]': 'pressed()',
+  '[class]': '_toneClass()',                 // "mlv-icon-toggle--tone-<tone>" or ''
+  '[attr.aria-pressed]': 'pressed()',
+  '[attr.disabled]': 'disabled() || null',
+  '[attr.aria-disabled]': 'disabled() || null',
+  '(click)': '_handleClick()',
+}
+```
+
+`hostDirectives: [MlvDensityDirective]` (exposing `mlvDensity`) with
+`MLV_DENSITY_ELEMENT: 'icon-toggle'` — same pattern as `MlvButton`. Emits
+`mlv-icon-toggle--{tight,compact,comfortable,spacious,airy}` directly on the
+host.
+
+## Accessibility
+
+WAI-ARIA toggle button pattern. `aria-pressed` always reflects `pressed()`
+regardless of `disabled`. Every consumer must supply an accessible name —
+`aria-label` on the button (the projected `<svg>` should carry
+`aria-hidden="true"`), matching every other icon-only control in the library
+(`.claude/rules/accessibility.md` § Icon Buttons and Ambiguous Controls).
+
+The pointer target is held at a minimum of `1.5rem` (24px — WCAG 2.2 SC
+2.5.8) via `min-inline-size`/`min-block-size` plus density-aware padding,
+**never** by inflating the glyph — "chromeless does not mean
+tap-target-less" (AB-R7). Focus ring is Form A (SF-R3): `outline:
+var(--mlv-stroke-width-medium) solid var(--mlv-border-focus)` with
+`outline-offset: var(--mlv-focus-ring-offset)` on `:focus-visible`.
+
+## Styling
+
+- BEM block `.mlv-icon-toggle`. **No background in any state** — this is the
+  component's defining constraint; a design that needs a filled/tinted
+  toggle affordance should reach for `mlv-button-toggle` instead.
+- **Fill-state mechanism** (Lucide ships no separate filled icon set, so
+  "pressed" is a CSS `fill` on the _same_ outlined glyph — correct only for
+  icons with an enclosed shape such as a star, heart, bookmark, or pin, not
+  for open-stroke glyphs):
+  - rest: `color: var(--mlv-text-secondary)`; `svg { fill: transparent; }`
+  - hover (not pressed): `color: var(--mlv-text-primary)`; `svg { fill: color-mix(in srgb, currentColor 15%, transparent); }`
+  - pressed: `color: var(--mlv-text-primary)`; `svg { fill: currentColor; }`
+  - pressed + `tone`: `color` overridden to the matching semantic text token; fill stays `currentColor`, so the glyph itself carries the tone
+  - the hover rule is scoped `:not(.mlv-icon-toggle--pressed):hover` so it can never fight the tone-pressed color rule for the same element
+  - focus-visible: Form A (SF-R3)
+  - disabled: native `:disabled` — `opacity: var(--mlv-disabled-opacity)`, `cursor: not-allowed`, `pointer-events: none` (no dedicated `--disabled` class needed; the host is always a real `<button>`)
+- **Sizing** — `min-inline-size`/`min-block-size: 1.5rem` unconditionally
+  (WCAG 2.5.8 floor), plus density-aware `padding` from `--mlv-spacing-*`:
+  tight `-1` (4px), compact `-1-5` (6px), comfortable `-2` (8px, default),
+  spacious `-2-5` (10px), airy `-3` (12px). The projected `<svg>`'s own size
+  is entirely author-controlled via its `[size]` attribute — the component
+  never resizes it.
+- **Motion** — `fill` transitions at `var(--mlv-duration-fast)` `var(--mlv-ease-default)`; `@include mixins.reduced-motion($block);` collapses it to `var(--mlv-duration-instant)` under `prefers-reduced-motion: reduce` (MO-R1/MO-R4).
+
+## Usage
+
+```html
+<!-- Neutral toggle, no tone -->
+<button mlvIconToggle type="button" [(pressed)]="bookmarked" aria-label="Bookmark">
+  <svg lucideBookmark [size]="16" aria-hidden="true" />
+</button>
+
+<!-- `tone` recolours only the pressed glyph — the exhibit-B star pattern -->
+<button mlvIconToggle type="button" tone="warning" [pressed]="ticket.starred" aria-label="Star conversation" (pressedChange)="toggleStar()">
+  <svg lucideStar [size]="16" aria-hidden="true" />
+</button>
+
+<!-- Disabled -->
+<button mlvIconToggle type="button" disabled [pressed]="true" aria-label="Star (disabled)">
+  <svg lucideStar [size]="16" aria-hidden="true" />
+</button>
+```
+
+```ts
+import { MlvIconToggle } from '@malva-ui/core/icon-toggle';
+
+@Component({
+  imports: [MlvIconToggle],
+})
+```
+
+## Dependencies
+
+- `@angular/cdk/coercion` — `BooleanInput`, `coerceBooleanProperty`
+- `@malva-ui/cdk/density` — `MlvDensityDirective`, `MLV_DENSITY_ELEMENT`
+- `@malva-ui/cdk/utils` — `MlvTone` (type-only import)
+- Malva UI CSS design tokens (`--mlv-*`)
+
+## Tests
+
+no pressed class); click toggles `pressed`/`aria-pressed`/the pressed class;
+a documented native-`<button>`-semantics test proving no custom keydown
+handling intercepts activation (real Enter/Space coverage lives in Playwright
+e2e, following the *(internal)* precedent); disabled gates the
+toggle and reflects native `disabled` + `aria-disabled`; tone modifier class
+reflection across all four `MlvTone` values, independent of pressed state;
+disabled+pressed+tone renders together (the host keeps `--pressed` and
+`--tone-*` alongside `disabled`/`aria-disabled`, so a disabled toggle still
+shows its dimmed pressed styling rather than losing state); two-way
+`[(pressed)]` binding through a host component (writes back on click,
+reflects an externally-set value); and a Sass-compiled fill-state assertion
+(rest `transparent`, hover-not-pressed `color-mix(...)`, pressed
+`currentColor`, and that no rule ever declares a `background`/`background-color`
+other than `transparent`) — the same source-text-assertion technique
+jsdom cannot resolve.

package/docs/ai/input.md

@@ -173,3 +173,33 @@ Marks a consumer-projected native `<input>` that `mlv-input` should adopt as its
 - 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]`.
+
+## Type & padding ramp fix (2026-08-26)
+
+`.mlv-input__native` previously declared a flat, non-ramped
+`padding: var(--mlv-spacing-1)` on top of the wrapper's own (already ramped)
+container padding — a doubled inline padding no other control carried, and
+one that grew disproportionately at `tight`. It now matches
+`mlv-select`/`mlv-combobox`/`mlv-time-picker`/`mlv-number-input`: the
+wrapper's `.mlv-form-control-wrapper__control-container` padding is zeroed
+in `input.scss` and `.mlv-input__native` owns the full ramped
+`var(--mlv-control-padding)` itself. Its font-size also moved off a
+hardcoded `--mlv-font-size-l` onto `var(--form-ctrl-font-size, var(--mlv-font-size-m))`
+— the same density-ramped chain `mlv-number-input`/`mlv-textarea` already
+used. See `.claude/projects/libs-form-utils.md` → _Control-text type &
+padding ramp_.
+
+**Padding ownership in `bare` mode.** The fix above applies unconditionally
+in `mlv-input`'s default (non-`bare`) mode, where it owns its own wrapper.
+`bare` mode (`projectControl`'s sibling flag — "used by composite controls
+that own their own surrounding container", per the `bare` input's own
+doc comment) is different: `mlv-combobox`, `mlv-tokenizer`, and
+`mlv-select`'s in-dropdown search field all project a bare `<mlv-input>`
+inside a trigger/row that **already** applies the full ramped padding
+itself. `bare()` is now reflected as a host class,
+`[class.mlv-input--bare]`, and `input.scss` adds
+`&--bare &__native { padding: 0; }` so the bare native element contributes
+no inset of its own — one padded box per control, owned by whichever
+element (the wrapper, or the composite's own trigger row) actually draws
+the field's boundary. Font-size is unaffected by `bare` — it still reads
+`var(--form-ctrl-font-size, var(--mlv-font-size-m))` regardless.