@malva-ui/core 0.1.12

package/docs/ai/pagination.md

@@ -0,0 +1,237 @@
+# @malva-ui/pagination
+
+All page navigation controls explicitly use `type="button"` to remain
+form-safe.
+
+**Import path:** `@malva-ui/core/pagination`
+**Selector:** `mlv-pagination`
+
+Pagination control with an item-count line plus items-per-page selector on one side, and a page-navigation strip (prev/next arrows, numbered page buttons, ellipsis page-jump fields) on the other. It owns no data — only the position within it.
+
+---
+
+## Public API
+
+| Export                     | Kind      | Description                                                                                          |
+| -------------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
+| `MlvPagination`            | Component | The pagination component (`mlv-pagination`).                                                         |
+| `MlvPaginationCount`       | Directive | `[mlvPaginationCount]` — replaces the item-count text with a projected template.                     |
+| `MlvPaginationPerPageItem` | Directive | `[mlvPaginationPerPageItem]` — replaces the whole items-per-page selector.                           |
+| `MlvPaginationService`     | Service   | Component-scoped page-range calculation. Provided by `MlvPagination`; not `providedIn: 'root'`.      |
+| `MlvPaginationObject`      | Interface | Input shape the component pushes into the service (`totalItems`, `currentPage`, per-page + options). |
+
+---
+
+## Components
+
+### `MlvPagination`
+
+- **Selector:** `mlv-pagination`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+- **Providers:** `MlvPaginationService`, `MlvSelectionService`
+
+#### Inputs
+
+| Name                | Type                      | Required | Default                        | Description                                                                                                                                                                                                                                                              |
+| ------------------- | ------------------------- | -------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `totalItems`        | `number`                  | ✅       | —                              | Total items across all pages. Drives the page count, the "X–Y of Z" range text, and how far `perPageOptions` is trimmed.                                                                                                                                                 |
+| `perPageOptions`    | `number[]`                |          | `[10, 30, 60, 100, Infinity]`  | Choices offered by the items-per-page selector. The list is cut after the first option that covers `totalItems`; include `Infinity` for "All (Z)".                                                                                                                       |
+| `mlvDensity`        | `MlvDensity \| undefined` |          | `undefined`                    | Density for the items-per-page dropdown list. Forwarded to the `mlv-popup`, which stamps `mlv--{density}` on the detached overlay panel (outside the page's density cascade); rows respond via the `mlv-list-item` density ladder. Omitted → global `MlvDensityService`. |
+| `mobile`            | `BooleanInput`            |          | `false`                        | Adds `mlv-pagination--mobile` to the host. **The library ships no rules for that class** — a styling hook for the consumer, not a built-in responsive mode.                                                                                                              |
+| `id`                | `string`                  |          | generated (`mlv-pagination-N`) | **Currently inert** — nothing reads it. The per-page trigger and its listbox pair through their own generated id.                                                                                                                                                        |
+| `displayTotalItems` | `BooleanInput`            |          | `true`                         | **Currently inert** — nothing reads it. The count is always rendered; project `[mlvPaginationCount]` to change or suppress the text.                                                                                                                                     |
+
+#### Models (two-way bindable)
+
+| Name           | Type     | Default | Description                                                                                      |
+| -------------- | -------- | ------- | ------------------------------------------------------------------------------------------------ |
+| `currentPage`  | `number` | `1`     | Currently active page, 1-based. Also set by the arrows, page buttons and page-jump fields.       |
+| `itemsPerPage` | `number` | `10`    | Items shown per page; also set by the per-page selector. `Infinity` puts every item on one page. |
+
+Their change outputs are `currentPageChange` and `itemsPerPageChange` (the `model()` outputs — there are no separate `output()` declarations).
+
+#### Coercion
+
+`mobile` and `displayTotalItems` use `coerceBooleanProperty`, so both accept attribute syntax (`<mlv-pagination mobile>`). **`totalItems` and `currentPage` are not coerced** — bind numbers, not route-param strings.
+
+#### Public methods
+
+| Method                           | Description                                                                                                                        |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `goToPage(page: number)`         | Sets `currentPage`. No clamping — internal callers only reach it from enabled controls.                                            |
+| `setItemsPerPage(n: number)`     | Sets `itemsPerPage`. `Infinity` puts every item on one page.                                                                       |
+| `setPageFromInput(event: Event)` | Jumps to the page typed into an ellipsis field (Enter keydown). Out-of-range values are ignored.                                   |
+| `getCellContext()`               | Template context for the projected slots: `$implicit` (current page), `total`, `start`, `end` (1-based, `end` clamped), `options`. |
+
+---
+
+## Layout Structure
+
+The host is a plain flex row of two wrappers, both sized by `flex-basis`:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│  50 items   [10 – 30 of 50 ▾]        [←] [1] [2] […] [50] [→]    │
+│  .mlv-pagination__items-count-wrapper  .mlv-pagination__items-wrapper │
+│  (flex-basis: 400%)                    (flex-basis: 60%, shrink 0)   │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+- `__items-count-wrapper` holds the count text and the per-page selector, `white-space: nowrap`.
+- `__items-wrapper` is a `role="navigation"` landmark and is **not rendered at all while `totalPages() <= 1`**.
+- The per-page selector is **not rendered** while `normalizedItemsPerPageOptions()` is empty — i.e. when `totalItems` is at or below the smallest `perPageOptions` entry.
+
+There is no absolute positioning and no three-column grid.
+
+---
+
+## Page collapsing
+
+Collapsing is driven by **page count**, not container width — the component
+observes no resize. `MlvPaginationService.pages()` returns the page numbers to
+render, inserting `moreElementValue` (`-1`) markers where a run is elided:
+
+- Window size is fixed at `CORNER_DISPLAY_PAGES * 2 + SIDE_CURRENT_DISPLAY_PAGES * 2 + 1 + 2` = **9** entries (1 corner page each side, 2 pages either side of current, the current page, and 2 ellipsis slots).
+- At or below 9 pages every page is rendered.
+- Near the start or the end, a single ellipsis appears on the far side; in the middle, one on each side.
+
+```
+ 9 pages,  page 1:  [<] [1] [2] [3] [4] [5] [6] [7] [8] [9] [>]
+50 pages,  page 1:  [<] [1] [2] [3] [4] [5] [6] [7] […] [50] [>]
+50 pages, page 25:  [<] [1] […] [23] [24] [25] [26] [27] […] [50] [>]
+50 pages, page 50:  [<] [1] […] [44] [45] [46] [47] [48] [49] [50] [>]
+```
+
+Each `…` slot renders as an `mlv-input[type=number]` (`.mlv-pagination__item--input`,
+sized to `--mlv-height-s`); pressing Enter calls `setPageFromInput()`, which
+ignores values outside `1…totalPages`.
+
+---
+
+## Items-per-Page Selector
+
+A transparent trigger button showing the current range (or the localized "All (Z)"
+label when the active value is `Infinity`) opens an `mlv-popup` containing a
+shared **`mlv-dropdown-panel`** — the same panel `mlv-select` and `mlv-combobox`
+use, rather than a hand-rolled option list.
+
+The panel owns the listbox pattern: it pins `listRole="listbox"`,
+`itemRole="option"`, `selectionMode="explicit"` and `[softDisabled]="false"`,
+renders the selected state, and supplies keyboard navigation and type-ahead.
+Pagination supplies only data and receives the choice:
+
+- `[options]` — `MlvSelectOption<number>[]` built from
+  `normalizedItemsPerPageOptions()`, labelled through the same i18n resolver, so
+  the `Infinity` entry reads "All (Z)" instead of a number.
+- `[selectedValues]` — the active value as a single-element array; the panel's
+  selection model is array-shaped even for single select.
+- `(valueChange)` — unwrapped to one number, applied, and the popup closed.
+
+`MlvSelectionService` must be provided by the component that hosts the panel —
+it injects it non-optionally, as a focus-first channel only. `mlv-pagination`
+provides it alongside `MlvPaginationService`; `selectedValues` remains the single
+source of truth for selection.
+
+---
+
+## CSS Classes (BEM)
+
+| Class                                          | Description                                                                      |
+| ---------------------------------------------- | -------------------------------------------------------------------------------- |
+| `.mlv-pagination`                              | Host element                                                                     |
+| `.mlv-pagination--mobile`                      | Applied by the `mobile` input. **No rules ship for it** — consumer styling hook. |
+| `.mlv-pagination__items-count-wrapper`         | Count text + per-page selector                                                   |
+| `.mlv-pagination__items-count`                 | The count text itself                                                            |
+| `.mlv-pagination__items-per-page`              | Items-per-page trigger + popup wrapper                                           |
+| `.mlv-pagination__items-per-page__description` | Width/opacity-animated label revealed on the active option                       |
+| `.mlv-pagination__items-per-page--active`      | Sets the two custom properties that reveal that label                            |
+| `.mlv-pagination__items-wrapper`               | `role="navigation"` landmark around the page strip                               |
+| `.mlv-pagination__items`                       | Arrow + page-button row                                                          |
+| `.mlv-pagination__items__container`            | The page buttons and ellipsis fields                                             |
+| `.mlv-pagination__item`                        | Any arrow button, page button, or ellipsis field                                 |
+| `.mlv-pagination__item--input`                 | The ellipsis page-jump `mlv-input`                                               |
+
+Active/disabled page-button appearance is **not** styled here — the buttons are
+`mlvButton` with `[variant]` swapped between `primary` and `transparent` and
+`shape="square"`, so `button.scss` owns their look.
+
+Component-scoped custom properties: `--mlv-pagination-item-width` and
+`--mlv-pagination-item-opacity` (both default to `0`, set by
+`__items-per-page--active`).
+
+---
+
+## Design Tokens Used
+
+| Token                  | Usage                                                 |
+| ---------------------- | ----------------------------------------------------- |
+| `--mlv-font-size-s`    | Count text and the ellipsis field's inner input       |
+| `--mlv-text-secondary` | Count text colour                                     |
+| `--mlv-height-s`       | Ellipsis page-jump field box (width = height)         |
+| `--mlv-spacing-2`      | Gaps between count/selector and between page controls |
+
+Everything else the component looks like comes from `mlv-button`, `mlv-input`,
+`mlv-popup` and `mlv-dropdown-panel`.
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic -->
+<mlv-pagination [totalItems]="500" [(currentPage)]="page" />
+
+<!-- Custom per-page choices with an "all items" option -->
+<mlv-pagination [totalItems]="total" [(currentPage)]="page" [(itemsPerPage)]="perPage" [perPageOptions]="[10, 25, 50, 100, Infinity]" />
+
+<!-- Custom count text -->
+<mlv-pagination [totalItems]="total" [(currentPage)]="page">
+  <ng-template mlvPaginationCount let-page let-start="start" let-end="end"> Showing {{ start }}–{{ end }} on page {{ page }} </ng-template>
+</mlv-pagination>
+```
+
+`totalItems` is not coerced — `totalItems="200"` binds the **string** `"200"`.
+Convert route params before binding.
+
+---
+
+## Accessibility
+
+- The page-navigation section (`.mlv-pagination__items-wrapper`) is a `role="navigation"` landmark, labelled via `[attr.aria-label]="_i18n().navigationLabel"` (English: "Pagination").
+- Prev/next arrow buttons use `[attr.aria-label]` from `_i18n().previousPage` / `_i18n().nextPage`.
+- Page number buttons set `[attr.aria-current]="'page'"` on the current page and take their `aria-label` from the ICU `page` key (English: "Page {page}") via `_pageAriaLabel()`, not from a hardcoded string.
+- The ellipsis "jump to page" field is a `mlv-input` (`type="number"`) with `[ariaLabel]="_i18n().goToPage"` (English: "Go to page") so it has an accessible name despite only showing a `...` placeholder.
+- i18n keys consumed: `navigationLabel`, `previousPage`, `nextPage`, `page`, `goToPage`, plus the ICU display keys `itemRange`, `itemCount`, `itemsPerPage` and `allItems` — see `MLV_PAGINATION_I18N`. (`items` is declared on `MlvPaginationI18n` but this component does not read it.)
+- Items-per-page selector: the trigger declares `aria-haspopup="listbox"` (via `MlvPopupTrigger`'s `ariaHasPopup` input) plus `aria-controls` pointing at the panel's `listboxId`, and `MlvPopupTrigger` reflects `aria-expanded`. The listbox semantics — roles, `aria-selected`, roving focus and type-ahead — come from `mlv-dropdown-panel` rather than being wired here, which also closes the roving-tabindex gap the hand-rolled list had.
+
+---
+
+## Services
+
+### `MlvPaginationService`
+
+Component-scoped (provided by `MlvPagination`, **not** `providedIn: 'root'`). Derives the page model from one `MlvPaginationObject` signal that the component keeps in sync via an `effect`.
+
+| Member                          | Kind                 | Description                                                                                                                                       |
+| ------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pagination`                    | `signal`             | The `MlvPaginationObject` input state.                                                                                                            |
+| `totalPages`                    | `computed<number>`   | `ceil(totalItems / itemsPerPage)`; `0` when `itemsPerPage` is falsy.                                                                              |
+| `pages`                         | `computed<number[]>` | Page numbers to render, with `moreElementValue` markers where a run is elided.                                                                    |
+| `normalizedItemsPerPageOptions` | `computed<number[]>` | `perPageOptions` trimmed against `totalItems` — **empty** when `totalItems` is at or below the smallest option, which is what hides the selector. |
+| `moreElementValue`              | `-1`                 | The ellipsis marker inside `pages()`.                                                                                                             |
+| `validate()`                    | method               | Dev-mode-only `console.warn` when `totalItems` or `itemsPerPage` is not a positive number. Called from `pages()`.                                 |
+
+---
+
+## Dependencies
+
+- `@angular/core` ^22.0.0
+- `@angular/cdk/coercion` — `BooleanInput`, `coerceBooleanProperty`
+- `@malva-ui/cdk/accessibility` — `MlvClick`
+- `@malva-ui/cdk/density` — `MlvDensity` type
+- `@malva-ui/cdk/utils` — `mlvNextId`, `range`, `MlvStructural`
+- `@malva-ui/core/button`, `/input`, `/popup`, `/dropdown`, `/form-utils` (`MlvSelectionService`)
+- `@lucide/angular` — `LucideChevronLeft`, `LucideChevronRight`
+- `@malva-ui/i18n` — `MLV_PAGINATION_I18N`, `MlvI18nResolverService`
+- Malva UI CSS design tokens (`--mlv-*`)

package/docs/ai/pin-input.md

@@ -0,0 +1,173 @@
+# Library: pin-input
+
+## Overview
+
+The `pin-input` library (`@malva-ui/core/pin-input`) provides `mlv-pin-input`: a row of single-character input cells that behave as one logical Signal Forms control. Intended for OTP codes, numeric PINs, and short verification sequences.
+
+## Public API
+
+Exported from `@malva-ui/core/pin-input`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvPinInput` | Component | OTP / PIN entry — `mlv-pin-input` |
+| `MlvPinInputSeparator` | Structural directive | Custom separator template — `*mlvPinInputSeparator` |
+
+---
+
+## Components
+
+### `MlvPinInput`
+
+**Selector:** `mlv-pin-input` | **Extends:** `MlvSignalFormControlBase<string>` | **Implements:** `FormValueControl<string>`, `MlvFormControl` | **Change Detection:** `OnPush`
+
+Each cell is rendered as a nested `mlv-input` instance bound to plain positional signal state. The component exposes one `value = model<string>('')` to Angular forms; no nested `FormControl`s or CVA transport remain. Cell keyboard / paste / focus events are wired through to coordinate auto-advance, value distribution, and focus management.
+
+#### Inputs (own)
+
+| Name          | Type                               | Default  | Description                                                                                                                                                                                                                                       |
+| ------------- | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `length`      | `number`                           | `6`      | Number of cells rendered                                                                                                                                                                                                                          |
+| `type`        | `'text' \| 'password' \| 'number'` | `'text'` | Input type applied to each cell                                                                                                                                                                                                                   |
+| `placeholder` | `string`                           | `'·'`    | Placeholder character shown in empty cells                                                                                                                                                                                                        |
+| `separator`   | `string`                           | `''`     | Separator placement: `''` disables, `'each'` inserts one between every pair of cells, comma-separated indices (e.g. `'1,3'`) insert a separator before each listed cell index, a single index (e.g. `'3'`) inserts one separator at that position |
+
+#### Inputs (from `FormControlBase`)
+
+`state`, `readonly`, `disabled`, `loading`, `clearable`, `id` (auto-generated), `label`, `hint`, `message`
+
+Setting `label` renders a `<mlv-label>` whose `for` attribute points at the first cell's id. `hint` is rendered as a `<mlv-hint>` inside that label. `message` is rendered as a `<mlv-message>` below the cell row and picks up the current `state` for theming. `disabled` (via `computedDisabled()`) is propagated to every per-cell `FormControl`.
+
+#### Outputs
+
+| Name        | Type                       | Description                                           |
+| ----------- | -------------------------- | ----------------------------------------------------- |
+| `completed` | `OutputEmitterRef<string>` | Fires the full joined value when every cell is filled |
+
+#### Host bindings
+
+| Binding                           | Value                               |
+| --------------------------------- | ----------------------------------- |
+| `class`                           | `mlv-pin-input`                     |
+| `[class]`                         | `"mlv-pin-input--state-" + state()` |
+| `[class.mlv-pin-input--disabled]` | `computedDisabled()`                |
+| `[class.mlv-pin-input--focused]`  | `focused()`                         |
+| `[attr.role]`                     | `"group"`                           |
+| `[attr.aria-label]`               | `label() \|\| "PIN entry"`          |
+| `[attr.aria-disabled]`            | `computedDisabled() \|\| null`      |
+
+#### Keyboard Interaction
+
+| Key                     | Action                                                 |
+| ----------------------- | ------------------------------------------------------ |
+| Any printable character | Fill current cell, advance to next                     |
+| `Backspace`             | Clear current cell; if already empty, move to previous |
+| `Delete`                | Clear current cell without moving                      |
+| `ArrowLeft`             | Move focus to previous cell                            |
+| `ArrowRight`            | Move focus to next cell                                |
+| `Home`                  | Move focus to first cell                               |
+| `End`                   | Move focus to last cell                                |
+
+#### Paste Behaviour
+
+Pasting any string distributes characters across cells starting from the **first cell** (index 0), regardless of which cell has focus. Whitespace is stripped before distribution.
+
+#### Separators
+
+Separators render as a span with class `mlv-pin-input__separator` and `aria-hidden="true"` between cells. By default each slot contains a `LucideDot` icon. To provide a custom separator template:
+
+```html
+<mlv-pin-input [length]="6" separator="each">
+  <ng-template mlvPinInputSeparator>
+    <span class="dash">—</span>
+  </ng-template>
+</mlv-pin-input>
+```
+
+Separator position strings are interpreted as follows:
+
+| Value          | Result for `length=6`                |
+| -------------- | ------------------------------------ |
+| `''` (default) | `[ ][ ][ ][ ][ ][ ]` — no separators |
+| `'each'`       | `[ ]·[ ]·[ ]·[ ]·[ ]·[ ]`            |
+| `'3'`          | `[ ][ ][ ]·[ ][ ][ ]`                |
+| `'1,3'`        | `[ ]·[ ][ ]·[ ][ ][ ]`               |
+
+Out-of-range values (≤0 or ≥`length`) are ignored. A single separator position means "a separator before the cell at that index".
+
+#### Forms Integration
+
+- `value: ModelSignal<string>` — splits external writes into positional cell state and emits the joined value after edits
+- `touch` — emitted from cell blur via `_markTouched()`
+- `disabled` — the field-bound signal is propagated directly to every nested `mlv-input`
+- Binding-matrix coverage verifies `[formControl]`, `ngModel`, and `[formField]` value/touched/disabled round trips
+
+---
+
+## ARIA
+
+Each cell is a `<mlv-input>` instance whose underlying native `<input>` receives:
+
+```html
+<input aria-label="Digit N of L" autocomplete="one-time-code" inputmode="numeric" [id]="<pinInputId>-cell-<index>" />
+```
+
+The host element carries `role="group"` and `aria-label` equal to the configured `label` (falling back to `"PIN entry"`). When a `label` input is set, the `<mlv-label>` renders with `for="<pinInputId>-cell-0"` so clicking the label focuses the first cell.
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic OTP -->
+<mlv-pin-input [(ngModel)]="otp" />
+
+<!-- Custom length -->
+<mlv-pin-input [length]="4" [(ngModel)]="pin" />
+
+<!-- Masked mode -->
+<mlv-pin-input type="password" [length]="4" [(ngModel)]="pin" />
+
+<!-- Reactive Forms -->
+<mlv-pin-input [length]="6" [formControl]="otpCtrl" />
+
+<!-- With label, hint, and error message -->
+<mlv-pin-input [length]="6" [formControl]="otpCtrl" label="One-time code" hint="Sent to +1 ••• 1234" [state]="otpCtrl.invalid && otpCtrl.touched ? 'error' : 'default'" [message]="otpCtrl.invalid && otpCtrl.touched ? 'Code is invalid' : ''" />
+
+<!-- completed event -->
+<mlv-pin-input [length]="6" (completed)="onOtpComplete($event)" />
+
+<!-- Separator every cell -->
+<mlv-pin-input [length]="6" separator="each" [(ngModel)]="code" />
+
+<!-- Grouped in halves -->
+<mlv-pin-input [length]="6" separator="3" [(ngModel)]="code" />
+
+<!-- Custom separator template -->
+<mlv-pin-input [length]="6" separator="each">
+  <ng-template mlvPinInputSeparator>
+    <span class="dash">—</span>
+  </ng-template>
+</mlv-pin-input>
+```
+
+---
+
+## Internationalization (i18n)
+
+Strings resolve through `MLV_PIN_INPUT_I18N` (`@malva-ui/i18n`): `digit` — an ICU string (`"Digit {position} of {length}"`) resolved per cell via `MlvI18nResolverService` — and `pinEntry`, the group `aria-label` fallback when no `label` input is set. Provide `provideMlvI18nTesting()` in specs.
+
+## Dependencies
+
+- `@angular/core` `[@angular/core_VERSION_PLACEHOLDER]` — Signals, DI, `viewChildren`, `effect`, `ChangeDetectionStrategy`, `ViewEncapsulation`
+- `@angular/forms/signals` `[@angular/forms_VERSION_PLACEHOLDER]` — custom-control contract supplied by the shared signal base
+- `@malva-ui/core/form-utils` — `MlvSignalFormControlBase`, `MLV_FORM_CONTROL`, `MlvFormControl`, `MlvLabel`, `MlvHint`, `MlvMessage`
+- `@malva-ui/core/input` — `MlvInput` rendered once per cell
+
+---
+
+## Field surface (2026-08)
+
+- Inherited `required` renders the `mlv-label` marker and is forwarded to every cell, so each cell input carries `aria-required`.
+- Inherited `description` renders `<mlv-description>` below the cells. Every cell receives `[ariaDescribedBy]="_describedBy()"` (the new `MlvInput` override input), so the description and message are announced from any cell.
+- `<mlv-message>` now carries the base's `_messageId()`; previously it had no id and nothing referenced it.