@malva-ui/core 0.1.12 → 0.1.14

package/docs/ai/drawer.md

@@ -51,7 +51,7 @@ absent from the public barrel. Drawer-section DOM lookup is scoped to the owning
 
 **Purpose:** Inline template-based drawer. Renders its content inside an Angular CDK Overlay when opened. Handles enter/leave CSS animations, focus trapping, backdrop click / Escape key dismissal.
 
-**Extends:** `MlvOverlayHostBase` from `@malva-ui/cdk/overlay`. The `opened` model, `hasBackdrop`/`closeOnBackdropClick`/`closeOnEscape` inputs, `afterOpened`/`afterClosed` outputs, `animationState` signal, `open()`/`close()`/`onAnimationEnd()` methods, focus-restore, and overlay create/destroy lifecycle are inherited from the shared base. `MlvDrawer` adds only the drawer-specific position/size/resize surface and supplies the backdrop class + edge position strategy. The `opened` + `afterOpened`/`afterClosed` shape is intentionally consistent with `mlv-popup`. The dialog no longer shares it: its open state moved to `ng-template[mlvDialog]` / `MlvDialogService` on `@angular/cdk/dialog`, and `mlv-dialog` is now only the presentational surface — no `opened` model, no `afterOpened`/`afterClosed`.
+**Extends:** `MlvOverlayHostBase` from `@malva-ui/cdk/overlay`. The `opened` model, `hasBackdrop`/`closeOnBackdropClick`/`closeOnEscape`/`restoreFocus` inputs, `afterOpened`/`afterClosed` outputs, `animationState` signal, `open()`/`close()`/`onAnimationEnd()` methods, optional focus restoration, and overlay create/destroy lifecycle are inherited from the shared base. `MlvDrawer` adds only the drawer-specific position/size/resize surface and supplies the backdrop class + edge position strategy. The `opened` + `afterOpened`/`afterClosed` shape is intentionally consistent with `mlv-popup`. The dialog no longer shares it: its open state moved to `ng-template[mlvDialog]` / `MlvDialogService` on `@angular/cdk/dialog`, and `mlv-dialog` is now only the presentational surface — no `opened` model, no `afterOpened`/`afterClosed`.
 
 **Inputs (`input()` / `model()`):**
 
@@ -63,6 +63,7 @@ absent from the public barrel. Drawer-section DOM lookup is scoped to the owning
 | `hasBackdrop`          | `input<boolean>`           | `true`    | Whether a dim backdrop is shown behind the drawer                                                                                                                 |
 | `closeOnBackdropClick` | `input<boolean>`           | `true`    | Whether clicking the backdrop closes the drawer                                                                                                                   |
 | `closeOnEscape`        | `input<boolean>`           | `true`    | Whether pressing Escape closes the drawer                                                                                                                         |
+| `restoreFocus`         | `input<boolean>`           | `true`    | Inherited coerced boolean. Restores the connected pre-open focus target after disposal; composed owners can disable it.                                           |
 | `resizable`            | `input<boolean>`           | `false`   | When true, renders a drag handle; enables drag-to-resize and swipe-to-dismiss                                                                                     |
 | `snapPoints`           | `input<number[]>`          | `[]`      | Sorted viewport-percentage snap points (0–100); panel snaps to nearest after drag. Empty = free resize                                                            |
 | `defaultSnap`          | `input<number>`            | `100`     | Initial snap point percentage applied when the drawer opens (only when `resizable=true`)                                                                          |
@@ -111,8 +112,10 @@ absent from the public barrel. Drawer-section DOM lookup is scoped to the owning
 The focus trap keeps Tab inside the panel but **does not auto-capture**: taking
 the first tabbable node landed on the leftmost `mlv-button-close`, popping its
 "Close" tooltip on every open. `MlvOverlayHostBase` applies the `initialFocus`
-strategy instead. Focus is returned to the trigger on close via the component's
-`_triggerElement` restore in `destroyOverlay()`.
+strategy instead. With the inherited `restoreFocus=true` default, focus returns
+to the connected pre-open target on close. Set `restoreFocus=false` when a
+composed parent owns the logical focus lifecycle; disposal then leaves focus
+untouched. Reopening during leave cancels disposal and keeps the Drawer rendered.
 
 **Viewport clamping:** `drawerDimensions` emits `maxWidth`/`maxHeight` alongside
 `width`/`height`. The sizing axis resolves to `min(<maxSize>, 100dvw|100dvh)`
@@ -142,15 +145,15 @@ The `<ng-template>` is projected into a CDK `TemplatePortal` when opened.
 
 **CSS variables:**
 
-| Variable                      | Default                             | Description                                            |
-| ----------------------------- | ----------------------------------- | ------------------------------------------------------ |
-| `--mlv-drawer-enter-duration` | `300ms`                             | Duration of backdrop fade-in                           |
-| `--mlv-drawer-enter-easing`   | `ease-in-out`                       | Easing of backdrop fade-in                             |
-| `--mlv-drawer-leave-duration` | `300ms`                             | Duration of backdrop fade-out                          |
-| `--mlv-drawer-leave-easing`   | `ease-in-out`                       | Easing of backdrop fade-out                            |
-| `--mlv-drawer-current-size`   | _(unset)_                           | Live height/width set by `MlvDrawerResize` during drag |
-| `--mlv-drawer-snap-duration`  | `350ms`                             | Duration of the post-drag spring snap animation        |
-| `--mlv-drawer-snap-easing`    | `cubic-bezier(0.34, 1.56, 0.64, 1)` | Easing of the spring snap animation                    |
+| Variable                      | Default                                                        | Description                                            |
+| ----------------------------- | -------------------------------------------------------------- | ------------------------------------------------------ |
+| `--mlv-drawer-enter-duration` | `300ms`                                                        | Duration of backdrop fade-in                           |
+| `--mlv-drawer-enter-easing`   | `ease-in-out`                                                  | Easing of backdrop fade-in                             |
+| `--mlv-drawer-leave-duration` | `300ms`                                                        | Duration of backdrop fade-out                          |
+| `--mlv-drawer-leave-easing`   | `ease-in-out`                                                  | Easing of backdrop fade-out                            |
+| `--mlv-drawer-current-size`   | _(unset)_                                                      | Live height/width set by `MlvDrawerResize` during drag |
+| `--mlv-drawer-snap-duration`  | `var(--mlv-duration-slow)` (300ms)                             | Duration of the post-drag spring snap animation        |
+| `--mlv-drawer-snap-easing`    | `var(--mlv-ease-spring)` (`cubic-bezier(0.34, 1.56, 0.64, 1)`) | Easing of the spring snap animation                    |
 
 **CSS classes (panel element `mlv-drawer`):**
 

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)