@malva-ui/core 0.1.12

package/docs/ai/rating.md

@@ -0,0 +1,76 @@
+# Library: rating
+
+---
+
+## Overview
+
+**Package:** `@malva-ui/core/rating`
+**Selector:** `mlv-rating`
+
+A signal-forms-native star rating component with hover preview, half-star precision via clip-path, read-only display mode, keyboard navigation, and compatibility across all Angular forms APIs.
+
+---
+
+## Public API
+
+### `MlvRating`
+
+Extends `MlvSignalFormControlBase<number>` from `@malva-ui/core/form-utils`. Its `value = model(0)` implements `FormValueControl<number>`; the inherited `touch` output and field-state inputs complete the signal-forms contract. Provides `MLV_FORM_CONTROL` for Malva form-field composition and deliberately does not provide `NG_VALUE_ACCESSOR`.
+
+| Member                       | Type                  | Default            | Description                                                                                                                                                                                                        |
+| ---------------------------- | --------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `max`                        | `number`              | `5`                | Total number of stars rendered                                                                                                                                                                                     |
+| `step`                       | `1 or 0.5`            | `1`                | Step increment — `0.5` enables half-star precision                                                                                                                                                                 |
+| `value`                      | `ModelSignal<number>` | `0`                | Two-way value model used by signal, reactive, and template-driven forms                                                                                                                                            |
+| `readonly`                   | `BooleanInput`        | `false`            | _(inherited)_ Disables interaction; shows a static value display                                                                                                                                                   |
+| `disabled`                   | `BooleanInput`        | `false`            | _(inherited)_ Disables interaction; also settable via `FormControl.disable()` (merged into `computedDisabled()`)                                                                                                   |
+| `state`                      | `MlvFormState`        | `'default'`        | _(inherited)_ Explicit validation state. A non-default value wins; otherwise bound errors resolve to `error` after the field is touched. The effective state is reflected as the `mlv-rating--state-*` host class. |
+| `id`                         | `string`              | auto (`mlvNextId`) | _(inherited)_ Bound to the host `id` attribute                                                                                                                                                                     |
+| `label` / `hint` / `message` | `string`              | `''`               | _(inherited)_ Available from the base; no text-field chrome is rendered (rating does not adopt `MlvFormControlWrapper`)                                                                                            |
+
+Implements the signal-forms `FormValueControl<number>` contract. Angular's compatibility bridge keeps `ngModel`, `[formControl]`, and `formControlName` working without CVA plumbing. The reusable binding-matrix spec verifies value, touched, and disabled round-trips through all three forms transports.
+
+The inherited `resolvedState` computed signal keeps visual validation consistent with other migrated controls: explicit non-default states take precedence, while an invalid Signal Forms field becomes visually `error` only after it is touched.
+
+### Keyboard Navigation
+
+| Key                   | Action            |
+| --------------------- | ----------------- |
+| ArrowRight / ArrowUp  | Increment by step |
+| ArrowLeft / ArrowDown | Decrement by step |
+| Home                  | Set to 0          |
+| End                   | Set to max        |
+
+### Focus / tab order
+
+- **Single tab stop (roving tabindex):** only the star covering the current value is tabbable (`tabindex="0"`); all other stars are `-1` (and all `-1` when read-only or disabled). Arrow keys change the value; the host (`role="group"`) handles the key events. Previously every star was `tabindex="0"`, producing up to `max` tab stops.
+- Star buttons keep toggle-button semantics (`aria-pressed`) rather than `role="radio"`, because half-star precision (`step="0.5"`) does not map cleanly onto a discrete radio group.
+
+---
+
+## Usage
+
+Import: `import { MlvRating } from '@malva-ui/core/rating';`
+
+Selector: `mlv-rating`
+
+Inputs: max, step, readonly, disabled
+
+---
+
+## Internationalization (i18n)
+
+Strings resolve through `MLV_RATING_I18N` (`@malva-ui/i18n`): `rating` (the `role="group"` host label) and `rateValue` — an ICU string (`"Rate {value} out of {max}"`) resolved per star via `MlvI18nResolverService`. Provide `provideMlvI18nTesting()` in specs.
+
+## Dependencies
+
+- @angular/core
+- @angular/forms/signals
+- @malva-ui/core/form-utils (`MlvSignalFormControlBase`, `MLV_FORM_CONTROL`, `MlvFormState`)
+- @lucide/angular (LucideStar)
+
+---
+
+## Field surface (2026-08)
+
+- No `aria-required` / `aria-label` forwarding: every star is a `<button>` that already carries its own `aria-label` (the i18n `rateValue` template), and ARIA does not allow `aria-required` on `role="button"`. The inherited `required` and `ariaLabel` inputs therefore have no ARIA effect on `mlv-rating` — express the requirement through the surrounding `mlv-form-field` / label copy.

package/docs/ai/scrollbar.md

@@ -0,0 +1,170 @@
+# Library: scrollbar
+
+## Overview
+
+The `scrollbar` library (`@malva-ui/core/scrollbar`) provides a minimalistic custom scrollbar component (`mlv-scrollbar`) that hides the native browser scrollbar and renders a themed overlay track and thumb. Native scroll behaviour is never intercepted — the viewport scrolls exactly as if the component were not present.
+
+The host element must have a defined height (set via a CSS class, inline style, or flex/grid sizing from a parent container).
+
+---
+
+## Public API
+
+Exported from `@malva-ui/core/scrollbar`:
+
+| Export                    | Kind      | Description                                    |
+| ------------------------- | --------- | ---------------------------------------------- |
+| `MlvScrollbar`            | Component | `mlv-scrollbar` — the custom scrollbar wrapper |
+| `MlvScrollbarOrientation` | Type      | `'vertical' \| 'horizontal' \| 'both'`         |
+
+---
+
+## Components
+
+### `MlvScrollbar`
+
+- **Selector:** `mlv-scrollbar`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+
+#### Inputs
+
+| Name               | Type                      | Default      | Description                                                            |
+| ------------------ | ------------------------- | ------------ | ---------------------------------------------------------------------- |
+| `orientation`      | `MlvScrollbarOrientation` | `'vertical'` | Which axes to show the custom scrollbar on                             |
+| `scrollbarSize`    | `string`                  | `'0.75rem'`  | CSS length for track width/height; maps to `--mlv-sb-size`             |
+| `disabled`         | `BooleanInput`            | `false`      | Hides custom tracks and restores native scrollbar                      |
+| `ariaLabel`        | `string \| undefined`     | `undefined`  | Accessible viewport label; falls back to i18n/default text             |
+| `viewportTabIndex` | `number`                  | `0`          | **`0` means auto** (see below); any non-zero value is applied verbatim |
+
+#### Viewport tab stop (WCAG 2.1.1)
+
+The default `0` is an _auto_ mode, not a literal tabindex: the viewport is a tab
+stop only while the scrolled content holds nothing tabbable.
+
+- Text-only region → `tabindex="0"`, so keyboard users can still scroll it.
+- Region containing controls → `tabindex="-1"`, so the region does not add a
+  redundant stop (and a focus ring around the whole body) in front of them. This
+  is what made a service-opened dialog capture focus onto its entire body.
+
+Tabbability is re-read after first render and on every content mutation
+(`MutationObserver` over the content wrapper: `childList`, `subtree`, and the
+`tabindex`/`disabled`/`hidden`/`href`/`type` attributes), confirmed with the
+CDK's `InteractivityChecker` under `{ ignoreVisibility: true }` (the geometric
+visibility test never passes before first paint, nor under jsdom). The resolved
+value lives in the protected `_effectiveViewportTabIndex` computed.
+
+#### Public properties
+
+| Property          | Type          | Description                                                                                                        |
+| ----------------- | ------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `viewportElement` | `HTMLElement` | The native scrollable viewport. Lets wrapping components (e.g. `main[mlvPage]`) attach their own scroll observers. |
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-scrollbar',
+  '[class.mlv-scrollbar--disabled]': 'disabled()',
+  '[class.mlv-scrollbar--dragging]': '_isDragging()',
+  '[class.mlv-scrollbar--scrolling]': '_isScrolling()',
+  '[style.--mlv-sb-size]': 'scrollbarSize()',
+}
+```
+
+#### Template Structure
+
+```html
+<div class="mlv-scrollbar__viewport" #viewport [attr.tabindex]="_effectiveViewportTabIndex()" (scroll)="_onScroll()">
+  <div class="mlv-scrollbar__content" #content>
+    <ng-content />
+  </div>
+</div>
+<div class="mlv-scrollbar__track mlv-scrollbar__track--vertical" #trackV>
+  <div class="mlv-scrollbar__thumb" [style.top.px]="_thumbTop()" [style.height.px]="_thumbHeight()" (pointerdown)="_onThumbPointerDown($event, 'vertical')"></div>
+</div>
+<div class="mlv-scrollbar__track mlv-scrollbar__track--horizontal" #trackH>
+  <div class="mlv-scrollbar__thumb" [style.left.px]="_thumbLeft()" [style.width.px]="_thumbWidth()" (pointerdown)="_onThumbPointerDown($event, 'horizontal')"></div>
+</div>
+```
+
+#### BEM Structure
+
+| Class                               | Role                                                                       |
+| ----------------------------------- | -------------------------------------------------------------------------- |
+| `.mlv-scrollbar`                    | Host — relative grid sizing context for the viewport and overlay tracks    |
+| `.mlv-scrollbar__viewport`          | Scrollable inner container — `overflow: auto; scrollbar-width: none`       |
+| `.mlv-scrollbar__content`           | Content wrapper observed by `ResizeObserver`                               |
+| `.mlv-scrollbar__track`             | Base track styles                                                          |
+| `.mlv-scrollbar__track--vertical`   | Right-edge vertical track                                                  |
+| `.mlv-scrollbar__track--horizontal` | Bottom-edge horizontal track                                               |
+| `.mlv-scrollbar__track--hidden`     | Applied when no overflow on that axis                                      |
+| `.mlv-scrollbar__thumb`             | The scroll position indicator; `top`/`height` or `left`/`width` set inline |
+
+#### Modifiers
+
+| Modifier                   | Applied when                                            |
+| -------------------------- | ------------------------------------------------------- |
+| `mlv-scrollbar--disabled`  | `disabled()` is `true`                                  |
+| `mlv-scrollbar--dragging`  | User is actively dragging a thumb                       |
+| `mlv-scrollbar--scrolling` | Scroll events are in-flight (cleared after 150 ms idle) |
+
+#### CSS Custom Properties
+
+| Variable                  | Default                    | Description                                  |
+| ------------------------- | -------------------------- | -------------------------------------------- |
+| `--mlv-sb-size`           | `0.75rem`                  | Track width/height                           |
+| `--mlv-sb-inset`          | `0.25rem`                  | Cross-axis padding inside track around thumb |
+| `--mlv-sb-edge-padding`   | `0.1875rem`                | Padding from track start/end edges           |
+| `--mlv-sb-thumb-bg`       | `var(--mlv-border-strong)` | Thumb background color                       |
+| `--mlv-sb-thumb-opacity`  | `0.5`                      | Thumb opacity at rest                        |
+| `--mlv-sb-track-bg`       | `transparent`              | Track background                             |
+| `--mlv-sb-radius`         | `var(--mlv-radius-full)`   | Thumb and track border-radius                |
+| `--mlv-sb-min-thumb-size` | `1.75rem`                  | Minimum thumb length                         |
+
+#### Drag Scroll
+
+Thumb drag is supported. On `pointerdown`, the thumb captures the pointer via `setPointerCapture`, then translates `pointermove` deltas into viewport `scrollTop`/`scrollLeft` updates. Released on `pointerup` or `pointercancel`.
+
+#### ResizeObserver
+
+A native `ResizeObserver` watches both the viewport element (host resize) and the content wrapper (content size changes). When either resizes, overflow state and thumb geometry are recalculated. In SSR/test environments without `ResizeObserver`, initial rendering and native scrolling remain available while geometry observation is skipped. The i18n token is optional, with `"Scrollable region"` as the accessible-label fallback.
+
+---
+
+## Usage Examples
+
+```html
+<!-- Vertical (default) -->
+<mlv-scrollbar style="height: 12rem">
+  <p>Long content…</p>
+</mlv-scrollbar>
+
+<!-- Horizontal -->
+<mlv-scrollbar orientation="horizontal" style="width: 20rem">
+  <div style="width: 60rem">Wide content…</div>
+</mlv-scrollbar>
+
+<!-- Both axes -->
+<mlv-scrollbar orientation="both" style="height: 12rem; width: 20rem">
+  <div style="height: 30rem; width: 60rem">…</div>
+</mlv-scrollbar>
+
+<!-- Disabled -->
+<mlv-scrollbar [disabled]="true" style="height: 8rem">
+  <!-- native scrollbar shown -->
+</mlv-scrollbar>
+
+<!-- Custom size -->
+<mlv-scrollbar scrollbarSize="0.5rem" style="height: 10rem"> … </mlv-scrollbar>
+```
+
+---
+
+## Dependencies
+
+| Dependency              | Version   | Notes                                                             |
+| ----------------------- | --------- | ----------------------------------------------------------------- |
+| `@angular/core`         | `^22.0.0` | Signals, DI, `afterNextRender`, `viewChild`                       |
+| `@angular/cdk/coercion` | `^22.0.0` | `BooleanInput`, `coerceBooleanProperty`                           |
+| `@angular/cdk/a11y`     | `^22.0.0` | `InteractivityChecker` — confirms projected content is a tab stop |

package/docs/ai/search-field.md

@@ -0,0 +1,85 @@
+# Library: search-field
+
+## Overview
+
+`@malva-ui/core/search-field` provides `MlvSearchField` (`mlv-search-field`), a search-specific composite control built from Malva input, button, and loader primitives. It supports debounced live queries and explicit submit queries without submitting a surrounding native form.
+
+## Public API
+
+### Types
+
+- `MlvSearchFieldTrigger = 'live' | 'submit'`
+- `MlvSearchFieldPresentation = 'field' | 'icon'`
+- `MlvSearchFieldRole = 'searchbox' | 'combobox'`
+- `MlvSearchFieldAriaAutocomplete = 'none' | 'list' | 'both'`
+- `MlvSearchFieldNavigateDirection = 'up' | 'down' | 'home' | 'end' | 'pageUp' | 'pageDown'`
+- `MlvSearchFieldNavigateEvent { direction: MlvSearchFieldNavigateDirection; event: KeyboardEvent }`
+- `MlvSearchFieldCommitEvent { value: string; event: KeyboardEvent | MouseEvent }`
+- `MlvSearchOverlayContentDef` (`[mlvSearchOverlayContent]`) + `MlvSearchOverlayContentContext`
+
+### Inputs
+
+| Input                  | Type                                     | Default       | Notes                                                                                                                                                                   |
+| ---------------------- | ---------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`                | `model<string>`                          | `''`          | Two-way draft query                                                                                                                                                     |
+| `trigger`              | `MlvSearchFieldTrigger`                  | `'live'`      | Commit strategy                                                                                                                                                         |
+| `debounce`             | `number`                                 | `200`         | Live-mode trailing delay in ms; negatives clamp to zero                                                                                                                 |
+| `placeholder`          | `string \| undefined`                    | i18n          | Override for the language-pack default                                                                                                                                  |
+| `ariaLabel`            | `string \| undefined`                    | i18n          | Override for the language-pack default                                                                                                                                  |
+| `disabled`             | `boolean`                                | `false`       | —                                                                                                                                                                       |
+| `loading`              | `boolean`                                | `false`       | —                                                                                                                                                                       |
+| `clearable`            | `boolean`                                | `true`        | —                                                                                                                                                                       |
+| `showSubmit`           | `boolean`                                | `true`        | Whether submit mode renders the trailing submit action. Off ⇒ commits from Enter alone and the search glyph moves to the leading edge — exactly one glyph either way    |
+| `commitOnClear`        | `boolean`                                | `true`        | Whether clearing commits `''` through `search`. `false` in a composite control that owns commit orchestration independently of the two-way `value` model                |
+| `presentation`         | `MlvSearchFieldPresentation`             | `'field'`     | `'icon'` renders a circular search button only and implies `overlay`                                                                                                    |
+| `overlay`              | `boolean`                                | `false`       | Opens a full-screen search overlay instead of accepting input inline                                                                                                    |
+| `role`                 | `MlvSearchFieldRole`                     | `'searchbox'` | `'combobox'` stamps `role="combobox"` on the input and turns on the `navigate` hooks. `'searchbox'` renders **no** `role` attribute (it is implicit on `type="search"`) |
+| `ariaControls`         | `string \| null`                         | `null`        | → `aria-controls` on the input: the popup listbox's DOM id                                                                                                              |
+| `ariaActiveDescendant` | `string \| null`                         | `null`        | → `aria-activedescendant`: the highlighted option's DOM id                                                                                                              |
+| `ariaAutocomplete`     | `MlvSearchFieldAriaAutocomplete \| null` | `null`        | → `aria-autocomplete`                                                                                                                                                   |
+| `ariaExpanded`         | `boolean \| null`                        | `null`        | → `aria-expanded`. Ignored while `overlay` is on, where the input reports the overlay's own state                                                                       |
+
+### Outputs
+
+| Output     | Payload                       | Notes                                                                              |
+| ---------- | ----------------------------- | ---------------------------------------------------------------------------------- |
+| `search`   | `string`                      | Committed query, per the selected `trigger`                                        |
+| `navigate` | `MlvSearchFieldNavigateEvent` | Option-navigation key, only while `role="combobox"`                                |
+| `commit`   | `MlvSearchFieldCommitEvent`   | Enter or the submit action, in every `trigger` mode, before the field's own commit |
+
+Live mode deduplicates emitted values. Submit mode emits only from a non-composing Enter key or the trailing submit action. Clearing always cancels a pending live event and updates `value` to `''`; by default it also commits `''` immediately, unless `commitOnClear` is disabled. Loading keeps live input editable so a newer query can replace an in-flight request, while blocking duplicate explicit submissions. Submit mode surfaces loading on the submit button itself; without a submit action a standalone circular loader takes its place.
+
+## Combobox hooks
+
+The field never owns a suggestion popup — it exposes the WAI-ARIA combobox wiring and reports keys, and the consumer owns the listbox, the option list, and the highlight.
+
+- `role="combobox"` is the single opt-in switch. It stamps `role="combobox"` on the underlying `<input>` and starts emitting `navigate`. The default `'searchbox'` renders no `role` attribute and never emits — a plain search field is byte-identical to before.
+- `ariaControls` / `ariaActiveDescendant` / `ariaAutocomplete` / `ariaExpanded` forward straight through `mlv-input`'s existing aria pass-through inputs, so they land on the focusable `<input>`. `aria-haspopup` stays unset for a combobox (`listbox` is its ARIA default); with `overlay` on it is `dialog` and `aria-expanded` reports the overlay instead.
+- Meaningful only with `presentation="field"`, and mutually exclusive with `overlay` — an icon trigger has no input, and an overlay trigger is a read-only dialog opener.
+- **`navigate` preventDefault policy:** `up`/`down`/`pageUp`/`pageDown` are consumed by the field before the event is handed over — inside a text input they jump the caret to the ends of the query or scroll the page, which is never what a combobox wants. `home`/`end` are reported **un**consumed, because an editable combobox keeps them as caret keys per WAI-ARIA; a consumer that wants "jump to first/last option" calls `preventDefault()` on the supplied event itself.
+- **`commit` / `search` interplay:** `commit` fires on a non-composing Enter and on the submit action, in _every_ `trigger` mode, always before the field's own commit. Calling `preventDefault()` on the supplied event takes the commit over — the field skips its `search` emission and leaves the key consumed, so Enter resolves the highlighted option and never submits a surrounding form. Left alone, existing behaviour is unchanged: `submit` mode emits `search`, `live` mode has already emitted through the debounce and Enter still bubbles. `commit` is never offered for an interaction the field would ignore anyway — while `disabled`, while `loading`, or while `overlay` is enabled (Enter opens the dialog there).
+- Escape keeps its existing meaning: it clears the field. Closing the popup is consumer state, driven from the same signal that feeds `ariaExpanded`.
+- Pair with `@malva-ui/core/dropdown`: `MlvActiveDescendant` holds the index, `optionId(listboxId, index)` builds the id `mlv-dropdown-panel` renders, and the panel takes `focusMode="activedescendant"` + `[activeIndex]`. A panel used outside `mlv-select`/`mlv-combobox` must provide `MlvSelectionService` itself. See docs example 5.
+
+## Overlay search
+
+`MlvSearchField` extends `MlvOverlayHostBase` (`@malva-ui/cdk/overlay`), so `overlay`/`presentation="icon"` reuses the shared modal-overlay lifecycle: `opened` model, animation state, backdrop, Escape/backdrop dismissal, and focus restore to the trigger.
+
+- The overlay is attached with a global position strategy at `100%`/`100%`, panel class `mlv-search-field__overlay-pane`. The panel carries `role="dialog"`, `aria-modal="true"`, and `cdkTrapFocus` with `cdkTrapFocusAutoCapture` — the same trap `mlv-drawer` uses (the dialog now relies on the CDK container's own trap). `autoCapture` also supplies the initial focus, so the overlay body needs no `mlvAutofocus` of its own.
+- **The trigger activates on click and Enter/Space, never on focus.** WAI-ARIA treats a control that opens a dialog as a button. Opening on `focusin` drops a keyboard user who is merely tabbing past into a modal, and it fights `MlvOverlayHostBase`'s focus restore — the base returns focus to the trigger on close, which under a focus-opener reopens the overlay immediately. Space is `preventDefault`ed so it cannot scroll the page; Enter is consumed so it cannot submit a surrounding form.
+- With `presentation="field"` the inline input becomes the trigger: it is rendered `readonly`, carries `aria-haspopup="dialog"` and `aria-expanded`, and cannot compete with the overlay's own input for typing. `presentation="icon"` renders a circular `<button>` instead.
+- **Default overlay body:** a nested `mlv-search-field` — not a second hand-rolled input — configured as a pure input surface (`trigger="submit"`, `[showSubmit]="false"`, `[commitOnClear]="false"`). It relays `valueChange` to the host, which owns the debounce, dedupe and commit; the host handles Enter (`_onOverlayEnter`), committing per its own `trigger` and then closing.
+- **Custom overlay body:** project `<ng-template mlvSearchOverlayContent>`. It replaces the default field and receives `MlvSearchOverlayContentContext` — `$implicit`/`query`, `loading`, `placeholder`, `ariaLabel`, `setQuery`, `submit`, `clear`, `close` — with an `ngTemplateContextGuard` for `let-` inference. The host keeps owning the overlay lifecycle and the `value`/`search` contract.
+- The overlay surface remaps `.mlv-form-control-wrapper` custom properties for a light-on-dark translucent field (10% white fill, 30/40/50% white border ramp), matching the treatment `mlv-page-shell` uses for chrome-hosted fields.
+
+## Accessibility and i18n
+
+- Uses the native search input mode and a labelled trailing submit action. The implicit `searchbox` role is left implicit; `role="combobox"` is the only case that stamps an explicit role, and it comes with the `aria-controls`/`aria-expanded`/`aria-activedescendant` inputs the pattern requires.
+- Prevents a handled Enter key from submitting a parent form.
+- Clear and submit actions are keyboard reachable and localized.
+- Defaults come from `MLV_SEARCH_FIELD_I18N`; explicit component inputs win. The overlay's close action uses the `closeOverlay` key.
+- Density is inherited by its Malva primitives and motion respects reduced-motion preferences (`mixins.reduced-motion`), including the backdrop and panel enter/leave animations.
+
+## Verification
+
+Run `npx nx test core-search-field`, `npx nx typecheck core-search-field`, and `npx nx lint core-search-field`.