@malva-ui/core 0.1.12

package/docs/ai/textarea.md

@@ -0,0 +1,249 @@
+# Library: textarea
+
+## Overview
+
+`@malva-ui/core/textarea` provides a multi-line text input form control (`mlv-textarea`). It extends `MlvSignalFormControlBase<string>` (from `@malva-ui/core/form-utils`) and is a signal-forms `FormValueControl<string>` — reactive (`[formControl]`/`formControlName`), template-driven (`ngModel`), and signal (`[formField]`) bindings all bind the `value` model directly (migrated 2026-07-22, slice 2 of docs/plans/signal-forms-migration.md). It supports optional auto-resize behaviour (textarea grows with content), a character counter with warning/error states, and a custom `mlv-scrollbar` overlay for a consistent cross-browser scrollbar appearance.
+
+The component wraps the native `<textarea>` inside `mlv-form-control-wrapper`, giving it the same label/hint/message/clear infrastructure as `mlv-input`.
+
+---
+
+## Public API
+
+| Export        | Kind      | Description                            |
+| ------------- | --------- | -------------------------------------- |
+| `MlvTextarea` | Component | Multi-line text input — `mlv-textarea` |
+
+---
+
+## Components
+
+### `MlvTextarea`
+
+**Selector:** `mlv-textarea`
+**Change Detection:** `OnPush`
+**Encapsulation:** `ViewEncapsulation.None`
+**Extends:** `MlvSignalFormControlBase<string>` (signal-forms `FormValueControl<string>`)
+**Implements:** `MlvFormControl`
+
+#### Providers
+
+| Token              | Value         |
+| ------------------ | ------------- |
+| `MLV_FORM_CONTROL` | `MlvTextarea` |
+
+> `NG_VALUE_ACCESSOR` is intentionally **not** provided — a signal-forms `FormValueControl` must not also implement `ControlValueAccessor`. Angular's reactive/ngModel compat binds the `value` model directly.
+
+#### Host Bindings
+
+| Binding                             | Value                                                 |
+| ----------------------------------- | ----------------------------------------------------- |
+| `class`                             | `'mlv-textarea'` (static)                             |
+| `[class]`                           | State modifier classes derived from `resolvedState()` |
+| `[class.mlv-textarea--disabled]`    | `computedDisabled()`                                  |
+| `[class.mlv-textarea--focused]`     | `focused()`                                           |
+| `[class.mlv-textarea--auto-resize]` | `autoResize()`                                        |
+
+#### Inputs (own)
+
+| Name          | Type                     | Default     | Description                                                                                |
+| ------------- | ------------------------ | ----------- | ------------------------------------------------------------------------------------------ |
+| `placeholder` | `string`                 | `''`        | Placeholder text shown when the textarea is empty.                                         |
+| `rows`        | `number`                 | `3`         | Number of visible text rows; sets the default height.                                      |
+| `minRows`     | `number \| undefined`    | `undefined` | Minimum row count when `autoResize` is active.                                             |
+| `maxRows`     | `number \| undefined`    | `undefined` | Maximum row count when `autoResize` is active.                                             |
+| `autoResize`  | `BooleanInput → boolean` | `false`     | When true, the textarea grows vertically to fit its content. Respects `minRows`/`maxRows`. |
+| `maxLength`   | `number \| undefined`    | `undefined` | Maximum number of characters allowed. When set, a character counter is displayed.          |
+
+#### Model
+
+| Name    | Type                  | Default | Description                                                                                                                                                                                 |
+| ------- | --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value` | `ModelSignal<string>` | `''`    | The `FormValueControl` value model — replaces the former `internalValue` signal + CVA transport. Bound directly by `[formControl]`/`ngModel`/`[formField]`. Two-way bindable (`[(value)]`). |
+
+#### Inputs (inherited from `MlvSignalFormControlBase<string>`)
+
+| Name          | Type                         | Default                | Description                                                                                                                                                      |
+| ------------- | ---------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `state`       | `MlvFormState`               | `'default'`            | Explicit visual state: `'default'` \| `'success'` \| `'info'` \| `'warning'` \| `'error'`. A non-default value takes precedence over automatic validation state. |
+| `readonly`    | `boolean`                    | `false`                | Makes the textarea read-only. Also a signal-forms field binding (`[formField]` sets it).                                                                         |
+| `disabled`    | `boolean`                    | `false`                | Disables the control. Signal-forms field binding — the bound field's disabled state drives it.                                                                   |
+| `loading`     | `BooleanInput → boolean`     | `false`                | Shows a loading indicator (handled by form wrapper).                                                                                                             |
+| `clearable`   | `BooleanInput → boolean`     | `false`                | Shows a clear (×) button that calls `clearValue()`.                                                                                                              |
+| `errors`      | `readonly ValidationError[]` | `[]`                   | Signal-forms field binding — current validation errors of the bound field.                                                                                       |
+| `touched`     | `boolean`                    | `false`                | Signal-forms field binding — whether the bound field is touched.                                                                                                 |
+| `dirty`       | `boolean`                    | `false`                | Signal-forms field binding — whether the bound field is dirty.                                                                                                   |
+| `id`          | `string`                     | auto (`mlv-control-N`) | ID applied to the native `<textarea>` element.                                                                                                                   |
+| `label`       | `string`                     | `''`                   | Label text rendered in `mlv-label`.                                                                                                                              |
+| `hint`        | `string`                     | `''`                   | Hint text rendered inside `mlv-hint` (nested in label).                                                                                                          |
+| `description` | `string`                     | `''`                   | Persistent help text rendered in `mlv-description` below the control, in front of `message`. Referenced by `aria-describedby`.                                   |
+| `message`     | `string`                     | `''`                   | Validation message rendered in `mlv-message`.                                                                                                                    |
+| `required`    | `boolean` (coerced)          | `false`                | Renders the required marker in `mlv-label` and sets `aria-required` on the native `<textarea>`. Also a signal-forms field binding.                               |
+| `ariaLabel`   | `string \| null`             | `null`                 | `aria-label` on the native `<textarea>` — use when no visible `mlv-label` is rendered.                                                                           |
+| `pill`        | `boolean` (coerced)          | `false`                | Fully rounded (stadium) control container. Shared by every control extending the signal base.                                                                    |
+
+> `maxLength` (`number | undefined`) doubles as the signal-forms `FormUiControl.maxLength` constraint member — its read/write type already matches the contract (`InputSignal<number | undefined>`), so no widening was needed (unlike `mlv-input`).
+
+#### Outputs
+
+| Name          | Type             | Description                                                                                                                                                                   |
+| ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `touch`       | `output<void>`   | Inherited from the base — emitted on blur (via `_markTouched`), the signal-forms replacement for CVA `onTouched`. `[formField]` subscribes and marks the bound field touched. |
+| `valueChange` | `output<string>` | The `value` model's change output.                                                                                                                                            |
+
+#### Signals & Computed Properties
+
+| Name               | Kind              | Description                                                                                                         |
+| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `focused`          | `signal(boolean)` | Whether the textarea currently has focus.                                                                           |
+| `charCount`        | `computed`        | Current character count (`(value() ?? '').length`).                                                                 |
+| `isCountWarning`   | `computed`        | `true` when char count is ≥ 90 % of `maxLength`.                                                                    |
+| `isCountError`     | `computed`        | `true` when char count has reached `maxLength`.                                                                     |
+| `hasValue`         | `computed`        | `(value() ?? '').length > 0` — drives the wrapper's clear-button visibility.                                        |
+| `minHeightStyle`   | `computed`        | CSS string for `min-height` of the scrollbar wrapper (derived from `rows`/`minRows`).                               |
+| `maxHeightStyle`   | `computed`        | CSS string for `max-height` of the scrollbar wrapper (derived from `maxRows`), or `undefined`.                      |
+| `computedDisabled` | `computed`        | `disabled()` — effective disabled state (no CVA `setDisabledState` side channel in the signal base).                |
+| `resolvedState`    | `computed`        | Explicit non-default `state()`; otherwise `'error'` when the bound field has errors and is touched, or `'default'`. |
+
+#### View Children
+
+| Name           | Type                                                       | Description                                                               |
+| -------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `_textareaRef` | `viewChild<ElementRef<HTMLTextAreaElement>>('textareaEl')` | Reference to the native `<textarea>` element, used by `_runAutoResize()`. |
+
+#### Content Slots
+
+| Selector               | Description                                          |
+| ---------------------- | ---------------------------------------------------- |
+| `[mlvTextareaPrepend]` | Arbitrary content projected before the form wrapper. |
+| `[mlvTextareaAppend]`  | Arbitrary content projected after the form wrapper.  |
+
+#### Public Methods
+
+| Method       | Signature                  | Description                                                                                |
+| ------------ | -------------------------- | ------------------------------------------------------------------------------------------ |
+| `onInput`    | `(event: Event): void`     | Handles the native `input` event; sets the `value` model (propagates to the bound field).  |
+| `onBlur`     | `(): void`                 | Clears focused state and emits `touch` (via `_markTouched`).                               |
+| `clearValue` | `(): void`                 | Resets the `value` model to `''` and marks the field touched (`_markTouched`).             |
+| `setFocused` | `(focused: boolean): void` | Inherited from the base; updates the focus signal that drives the wrapper's focused state. |
+
+#### Template Summary
+
+1. Optional `[mlvTextareaPrepend]` slot.
+2. `mlv-form-control-wrapper` (clearable, state, focused, disabled wired via inherited signals):
+   - `mlv-label` (rendered when `label()` or `hint()` is set), with optional nested `mlv-hint`.
+   - `mlv-scrollbar` wrapper whose `min-height`/`max-height` are bound inline; disabled when `autoResize` is true.
+   - Native `<textarea #textareaEl>` with `aria-invalid`, `aria-label`, `aria-required`, `aria-describedby` (`_textareaDescribedBy()` — the base's description/message ids plus the counter id, `null` when none apply), and standard form bindings.
+   - `mlv-description` (shown when `description()` is non-empty), carrying `_descriptionId()`.
+   - `mlv-message` (shown when `message()` is non-empty), carrying `_messageId()`.
+   - Character counter `<div mlvFormControlWrapperAside>` (shown when `maxLength` is set) with `aria-live="polite"` and `--warning` / `--error` class modifiers. **The `mlvFormControlWrapperAside` marker is required** — before 2026-08 the counter was a plain child of `mlv-form-control-wrapper`, matched no projection slot, and never reached the DOM (leaving `aria-describedby` pointing at a missing id).
+3. Optional `[mlvTextareaAppend]` slot.
+
+#### SCSS
+
+BEM block: `.mlv-textarea`
+
+| Class                           | Description                                                     |
+| ------------------------------- | --------------------------------------------------------------- |
+| `.mlv-textarea`                 | Block root                                                      |
+| `.mlv-textarea__scrollbar`      | `mlv-scrollbar` wrapper; `flex: 1 1 auto`                       |
+| `.mlv-textarea__field`          | Native `<textarea>`; no border/outline; hides native scrollbar  |
+| `.mlv-textarea__count`          | Character counter; `text-align: right`; `--mlv-typography-ui-s` |
+| `.mlv-textarea__count--warning` | Color: `--mlv-text-warning`                                     |
+| `.mlv-textarea__count--error`   | Color: `--mlv-text-negative`                                    |
+| `.mlv-textarea--auto-resize`    | Applied when `autoResize()` is true; allows free height growth  |
+| `.mlv-textarea--disabled`       | Applied when `computedDisabled()` is true                       |
+| `.mlv-textarea--focused`        | Applied when `focused()` is true                                |
+| `.mlv-textarea--{state}`        | Applied for `resolvedState()` (e.g., `--error`, `--success`)    |
+
+Key style decisions:
+
+- Overrides `.mlv-form-control-wrapper__control-container` to `height: auto` so the textarea can grow.
+- The clear button is repositioned with `margin-top`/`margin-inline-end` to align with the first text row.
+- When `mlv-scrollbar` is disabled (auto-resize mode), its overflow is `visible`.
+
+---
+
+## Interfaces & Types
+
+`MlvTextarea` relies on types from `@malva-ui/core/form-utils`:
+
+| Type           | Values                                                     | Description             |
+| -------------- | ---------------------------------------------------------- | ----------------------- |
+| `MlvFormState` | `'default' \| 'success' \| 'info' \| 'warning' \| 'error'` | Visual validation state |
+
+---
+
+## Usage Examples
+
+### Basic textarea with label
+
+```html
+<mlv-textarea label="Description" placeholder="Enter a description…" />
+```
+
+### Reactive form with validation message
+
+```typescript
+// component.ts
+readonly descCtrl = new FormControl('', Validators.required);
+```
+
+```html
+<mlv-textarea label="Description" hint="Maximum 500 characters" [maxLength]="500" [formControl]="descCtrl" [message]="descCtrl.invalid && descCtrl.touched ? 'Description is required' : ''" [state]="descCtrl.invalid && descCtrl.touched ? 'error' : 'default'" />
+```
+
+### Auto-resize with row constraints
+
+```html
+<mlv-textarea label="Notes" autoResize [minRows]="2" [maxRows]="8" placeholder="Type your notes…" />
+```
+
+### Clearable textarea in a reactive form
+
+```html
+<mlv-textarea label="Bio" clearable [rows]="5" [formControl]="bioCtrl" />
+```
+
+### Read-only textarea
+
+```html
+<mlv-textarea label="Summary" readonly [value]="summary()" />
+```
+
+### With prepend and append content slots
+
+```html
+<mlv-textarea label="Message">
+  <div mlvTextareaPrepend>Prefix content</div>
+  <div mlvTextareaAppend>Append content</div>
+</mlv-textarea>
+```
+
+---
+
+## Dependencies
+
+### Angular / third-party
+
+| Package                 | Usage                                                                                                            |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `@angular/core`         | `Component`, `model`, `computed`, `effect`, `viewChild`, `input`, `ViewEncapsulation`, `ChangeDetectionStrategy` |
+| `@angular/cdk/coercion` | `BooleanInput`, `coerceBooleanProperty`                                                                          |
+
+### Internal (`@malva-ui/*`)
+
+| Package                     | Exports used                                                                                                                                                   |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@malva-ui/core/form-utils` | `MlvSignalFormControlBase`, `MlvFormControlWrapper`, `MlvFormControlWrapperControl`, `MlvLabel`, `MlvHint`, `MlvMessage`, `MLV_FORM_CONTROL`, `MlvFormControl` |
+| `@malva-ui/core/scrollbar`  | `MlvScrollbar`                                                                                                                                                 |
+| `@malva-ui/styles`          | CSS custom properties (`--mlv-*` tokens), `mixins.base()`                                                                                                      |
+
+---
+
+## Signal-forms cutover (2026-07-22, slice 2)
+
+- **Base swap:** `FormControlBase<string>` → `MlvSignalFormControlBase<string>`; dropped `implements ControlValueAccessor` and the `NG_VALUE_ACCESSOR` provider (kept `MLV_FORM_CONTROL`). A control may not implement both CVA and `FormValueControl`.
+- **`value = model<string>('')`** replaces the former `internalValue` signal + CVA plumbing (`writeValue` removed; there is no `onChange`/`registerOn*`/`setDisabledState`). `charCount`/`isCountWarning`/`isCountError`/`hasValue` and the auto-resize effect all read `value()`; template renders `[value]="value() ?? ''"` defensively.
+- **Touch:** blur emits the base `touch` output via `_markTouched()` (was CVA `onTouched`). `clearValue()` now does `value.set('')` + `_markTouched()` (preserves the old clear-marks-touched behaviour).
+- **No constraint collisions:** the only `FormUiControl` same-named input is `maxLength` (`number | undefined`), whose type already matches the contract — no widening needed.

package/docs/ai/tile.md

@@ -0,0 +1,150 @@
+# Library: tile
+
+## Overview
+
+The Tile library (`@malva-ui/core/tile`) provides a card-like container component (`mlv-tile`) for displaying information in a structured, elevated panel. Tiles support five sizes, five semantic tones (info/success/warning/danger), closable mode with a dismiss button, and drag-and-drop integration via a drag handle. An optional `[mlvTileHeader]` template directive projects a custom header section.
+
+## Public API
+
+Exported from `@malva-ui/core/tile`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvTile` | Component | Elevated container panel — `mlv-tile` |
+| `MlvTileHeader` | Directive | Template slot for tile header content — `[mlvTileHeader]` |
+| `MlvTileSize` | Type | `'xs' | 's' | 'm' | 'l' | 'xl'` |
+| `MlvTileTone` | Type | `MlvTone | 'default'` (`'info' | 'success' | 'warning' | 'danger' | 'default'`) |
+
+---
+
+## Components
+
+### `MlvTile`
+
+**Selector:** `mlv-tile` | **Change Detection:** `OnPush` | **Encapsulation:** `None`
+
+#### Inputs
+
+| Name           | Type           | Default     | Description                                                                                      |
+| -------------- | -------------- | ----------- | ------------------------------------------------------------------------------------------------ |
+| `size`         | `MlvTileSize`  | `'m'`       | Controls padding, border-radius, and gap: `xs`, `s`, `m`, `l`, `xl`                              |
+| `tone`         | `MlvTileTone`  | `'default'` | Semantic tone: `default`, `info`, `success`, `warning`, `danger` — applies a colored left border |
+| `closable`     | `BooleanInput` | `false`     | Renders a dismiss button in the header row; emits `closed` when clicked                          |
+| `draggable`    | `BooleanInput` | `false`     | Renders a drag handle icon (for SortableJS integration)                                          |
+| `dragDisabled` | `BooleanInput` | `false`     | Shows the tile as disabled-draggable (reduced opacity, not-allowed cursor)                       |
+
+#### Outputs
+
+| Name     | Type   | Description                                                                                                                                                                                                                                                                                                                                                                             |
+| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `closed` | `void` | Emits when the close button is clicked. **Intentionally a bare `closed` output with no `opened` model** — a tile is a persistent container dismissed by the consumer, not a toggled overlay, so it is deliberately excluded from the `opened` two-way-model normalization applied to `mlv-drawer`/`mlv-popup` (the dialog's equivalent is `[(mlvDialog)]` on `ng-template[mlvDialog]`). |
+
+#### Host Bindings
+
+```ts
+host: {
+  class: 'mlv-tile',
+  '[class]': '"mlv-tile--size-" + size()',
+  '[class.mlv-tile--tone-info]': 'tone() === "info"',
+  '[class.mlv-tile--tone-success]': 'tone() === "success"',
+  '[class.mlv-tile--tone-warning]': 'tone() === "warning"',
+  '[class.mlv-tile--tone-danger]': 'tone() === "danger"',
+  '[class.mlv-tile--draggable]': 'draggable()',
+  '[class.mlv-tile--drag-disabled]': 'dragDisabled()',
+}
+```
+
+#### Content Children
+
+| Query       | Type            | Description                                                    |
+| ----------- | --------------- | -------------------------------------------------------------- |
+| `headerRef` | `MlvTileHeader` | Optional header template — renders above the body when present |
+
+#### Template Summary
+
+When `headerRef`, `closable`, or `draggable` is truthy, a `.mlv-tile__header` row is rendered containing:
+
+- A drag handle icon (`lucideGripVertical`) if `draggable()`
+- The projected header template via `[ngTemplateOutlet]` if `headerRef()` exists
+- A close button (`mlvButton`, variant `transparent`, size `xs`) if `closable()`
+
+The body is always rendered as `.mlv-tile__body` with `<ng-content />`.
+
+---
+
+## Directives
+
+### `MlvTileHeader`
+
+**Selector:** `[mlvTileHeader]`
+
+Extends `MlvStructural` from `@malva-ui/cdk`. Marks an `<ng-template>` as the tile header slot. The parent `MlvTile` queries it via `contentChild(MlvTileHeader)` and renders its `templateRef` inside `.mlv-tile__header`.
+
+---
+
+## BEM Class Reference
+
+| Class                                         | Description                                                      |
+| --------------------------------------------- | ---------------------------------------------------------------- |
+| `.mlv-tile`                                   | Root block                                                       |
+| `.mlv-tile--size-xs/s/m/l/xl`                 | Size variants                                                    |
+| `.mlv-tile--tone-info/success/warning/danger` | Semantic tone left-border color                                  |
+| `.mlv-tile--draggable`                        | Shows drag handle                                                |
+| `.mlv-tile--drag-disabled`                    | Reduced opacity, not-allowed cursor                              |
+| `.mlv-tile--leaving`                          | Applied externally before DOM removal to trigger leave animation |
+| `.mlv-tile__header`                           | Header row (drag handle + header slot + close button)            |
+| `.mlv-tile__drag-handle`                      | Drag handle icon wrapper                                         |
+| `.mlv-tile__close`                            | Close button                                                     |
+| `.mlv-tile__body`                             | Main content area                                                |
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic tile -->
+<mlv-tile>
+  <p>Content here</p>
+</mlv-tile>
+
+<!-- With header template -->
+<mlv-tile>
+  <ng-template mlvTileHeader>
+    <strong>Tile Title</strong>
+  </ng-template>
+  <p>Body content</p>
+</mlv-tile>
+
+<!-- Closable tile -->
+<mlv-tile closable (closed)="onClose()">
+  <p>This tile can be dismissed.</p>
+</mlv-tile>
+
+<!-- Semantic tone -->
+<mlv-tile tone="warning">
+  <p>Warning: something needs attention.</p>
+</mlv-tile>
+
+<!-- Draggable + closable + sized -->
+<mlv-tile size="l" tone="info" closable draggable (closed)="remove(tile)">
+  <ng-template mlvTileHeader>Dashboard Widget</ng-template>
+  <p>Widget content goes here.</p>
+</mlv-tile>
+```
+
+---
+
+## Dependencies
+
+| Package                 | Role                                  |
+| ----------------------- | ------------------------------------- |
+| `@angular/core`         | Signals, component, directive, DI     |
+| `@angular/common`       | `NgTemplateOutlet`                    |
+| `@angular/cdk/coercion` | Boolean coercion                      |
+| `@malva-ui/core/button` | Close button (`mlvButton`)            |
+| `@malva-ui/cdk`         | `MlvStructural` base class            |
+| `@lucide/angular`       | `LucideX`, `LucideGripVertical` icons |
+
+---
+
+## File Structure

package/docs/ai/time-picker.md

@@ -0,0 +1,214 @@
+# Library: time-picker
+
+Nx project name: `core-time-picker`. Internal scroll controls explicitly use
+`type="button"` so embedding the picker in a form cannot submit that form.
+
+## Overview
+
+The Time Picker library (`@malva-ui/core/time-picker`) provides a popup-based drum-roll style time selection component. A compact trigger displays the current time with a clock icon; clicking it opens a floating popup panel with scrollable columns. Supports 24h and 12h (AM/PM) modes, optional seconds, and signal/reactive/template-driven forms.
+
+The component follows the same trigger → popup pattern as `mlv-day-picker`, `mlv-select`, and `mlv-combobox`, using `mlv-form-control-wrapper` for consistent form control styling (border, background, states, focus, density).
+
+The component is composed of two Angular components:
+- `MlvTimePicker` — the main form-control component with trigger + popup panel, label/hint/message support
+- `MlvTimePickerColumn` — an internal scrollable column using CSS scroll-snap
+
+---
+
+## Public API
+
+Exported from `@malva-ui/core/time-picker`:
+
+| Export               | Kind      | Description                                                                          |
+| -------------------- | --------- | ------------------------------------------------------------------------------------ |
+| `MlvTimePicker`      | Component | The primary time picker form control — `mlv-time-picker`                             |
+| `MlvTimeMode`        | Type      | `'24h' \| '12h'`                                                                     |
+| `MlvTimePickerState` | Type      | `'default' \| 'success' \| 'info' \| 'warning' \| 'error'` (alias of `MlvFormState`) |
+
+`MlvTimePickerColumn` is an internal renderer and is intentionally not
+exported from the package barrel.
+
+---
+
+## Components
+
+### `MlvTimePicker`
+
+- **Selector:** `mlv-time-picker`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+- **Extends:** `MlvSignalFormControlBase<string>` from `@malva-ui/core/form-utils`
+- **Implements:** `FormValueControl<string>`, `MlvFormControl`
+
+#### Inputs from `MlvSignalFormControlBase`
+
+| Input      | Type                 | Default        | Description                         |
+| ---------- | -------------------- | -------------- | ----------------------------------- |
+| `id`       | `string`             | auto-generated | HTML id for the inner group element |
+| `label`    | `string`             | `''`           | Label text                          |
+| `hint`     | `string`             | `''`           | Hint text inside label              |
+| `message`  | `string`             | `''`           | Validation/status message           |
+| `state`    | `MlvTimePickerState` | `'default'`    | Visual state                        |
+| `disabled` | `BooleanInput`       | `false`        | Disables all columns                |
+| `readonly` | `boolean`            | `false`        | Read-only mode                      |
+
+#### Own Inputs
+
+| Input         | Type           | Default         | Description                           |
+| ------------- | -------------- | --------------- | ------------------------------------- |
+| `mode`        | `MlvTimeMode`  | `'24h'`         | Clock mode — 24-hour or 12-hour AM/PM |
+| `showSeconds` | `BooleanInput` | `false`         | Shows a seconds column                |
+| `ariaLabel`   | `string`       | `'Time picker'` | ARIA label for the group element      |
+
+#### Forms value format
+
+Emits and accepts time strings in `HH:mm` (or `HH:mm:ss` when `showSeconds` is true). Always in 24-hour notation.
+
+#### Host Bindings
+
+```ts
+host: {
+  class: 'mlv-time-picker',
+  '[class]': '"mlv-time-picker--" + state()',
+  '[class.mlv-time-picker--disabled]': 'computedDisabled()',
+  '[class.mlv-time-picker--open]': 'isOpen()',
+  '[class.mlv-time-picker--12h]': 'mode() === "12h"',
+  '[class.mlv-time-picker--with-seconds]': 'showSeconds()',
+}
+```
+
+#### Density
+
+Uses `MlvDensityDirective` as a `hostDirective`. Provides `MLV_DENSITY_ELEMENT = 'time-picker'`.
+
+Since popup content renders in a detached CDK overlay, the effective density is read from the directive and bound as a BEM modifier class on the panel element (`mlv-time-picker__panel--compact`, etc.). The density SCSS mixins on `&__panel` respond to this class, setting the `--mlv-tp-*` CSS custom properties which cascade to columns, dividers, and AM/PM buttons inside the overlay.
+
+#### Architecture
+
+The trigger element has `role="combobox"` with `aria-expanded`, `aria-haspopup="dialog"`, and conditional `tabindex`. Clicking or pressing Enter/Space opens the popup. The popup contains drum-roll columns rendered by `MlvTimePickerColumn`. On popup open, the first column (hours) listbox receives focus automatically. The `mlv-popup` opts into modal-dialog semantics via `panelRole="dialog"` + `[modal]="true"` + `[ariaLabel]` (the popup no longer hard-codes these) — this emits `role="dialog"`/`aria-modal="true"` on the panel and enables the CDK focus trap. ArrowLeft/ArrowRight keyboard navigation moves focus between column listboxes. On popup close, focus is restored to the trigger element via `_onPopupClosed()`.
+
+The popup also opts into `mobileMode="auto"` (`[mobileTitle]="label() || _resolvedAriaLabel()"`), so below the `md` breakpoint (< 768px) the drum-roll columns open in a full-screen sheet with a header + close button and scroll-locked page; above it the panel stays anchored (unchanged). The drum-roll scroll-snap columns and `_onPopupOpened()` (focus first column) / `_onPopupClosed()` (focus restore) compose with the full-screen focus trap. See `libs-popup.md` → _Mobile fullscreen inputs_.
+
+---
+
+### `MlvTimePickerColumn`
+
+- **Selector:** `mlv-time-picker-column`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+
+#### Inputs
+
+| Input           | Type                  | Description                                            |
+| --------------- | --------------------- | ------------------------------------------------------ |
+| `label`         | `string` (required)   | Accessible label — `"Hours"`, `"Minutes"`, `"Seconds"` |
+| `items`         | `number[]` (required) | Values to display                                      |
+| `selectedValue` | `number` (required)   | Currently selected value                               |
+| `disabled`      | `boolean`             | Disables the column                                    |
+
+#### Outputs
+
+| Output        | Type     | Description                       |
+| ------------- | -------- | --------------------------------- |
+| `valueChange` | `number` | Emitted when user selects a value |
+
+#### Methods
+
+| Method        | Description                                                                                                                                                    |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `focusList()` | Focuses the column's `<ul>` listbox. Used by parent for inter-column keyboard navigation.                                                                      |
+| `listElement` | Getter — the column's `<ul>` listbox element, or `null` before view init. Lets the parent identify which column holds focus when moving focus between columns. |
+
+#### `@angular/aria` backing (Phase 3 migration)
+
+The column's `<ul>` is a headless **`ngListbox`** and each `<li>` an **`ngOption`** (`@angular/aria/listbox`), applied in the template (not as `hostDirectives`) so their inputs bind freely. aria owns the roles (`listbox`/`option`), `aria-selected`, `aria-activedescendant`, roving tabindex, keyboard navigation, and selection. Pinned configuration:
+
+| aria input      | Value              | Why                                                                                                                                                                               |
+| --------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `focusMode`     | `activedescendant` | Focus stays on the `<ul>` (parent inter-column ArrowLeft/Right + `focusList()` rely on it). aria moves neither DOM focus nor scroll in this mode, so it cannot fight scroll-snap. |
+| `selectionMode` | `follow`           | Drum-roll semantic = "centered is selected" → arrow moves **and** selects (unlike list/select/tree, which pin `explicit`).                                                        |
+| `wrap`          | `true`             | Preserves the historical wrapping navigation.                                                                                                                                     |
+| `disabled`      | `disabled()`       | A disabled column blocks aria keydown/click.                                                                                                                                      |
+| `tabindex`      | `-1` when disabled | Preserves the contract that a disabled listbox leaves the tab order (aria would keep it focusable at `0`).                                                                        |
+
+**Value bridging:** the public scalar `selectedValue` input / `valueChange` output are preserved. Internally `[value]="[selectedValue()]"` bridges the scalar into aria's array (`V[]`) single-select model, and `(valueChange)` collapses `V[]` → scalar (guarding no-op echoes).
+
+**Active-item sync (the scroll-snap coexistence gotcha):** aria's `setDefaultState` auto-activates the selected option only until first interaction — but the popup's open handler focuses the list (`focusin`), defeating it. So the column seeds aria's active item to the selected value via `Listbox.gotoIndex()` in `ngAfterViewInit` (options are registered synchronously by `ngOption.ngOnInit`), re-syncs it from the scroll handler, and re-syncs from the `selectedValue` effect on external writes. Without this seed, the first Arrow key would navigate from a stale/`undefined` active item.
+
+#### Keyboard Navigation (owned by aria)
+
+- ArrowUp/ArrowDown: navigate + select items within the column (wrapping)
+- ArrowLeft/ArrowRight: move focus between columns (handled by parent panel)
+- Home/End: jump to first/last item
+- Enter/Space: select the active item
+- **Type-ahead (aria addition):** typing digits seeks to the matching zero-padded option `label`
+
+#### Scroll Behavior
+
+Uses CSS `scroll-snap-type: y mandatory` for item snapping — retained on top of aria (aria attaches no scroll listener and never calls its opt-in `scrollActiveItemIntoView()`). The scroll handler is debounced (150 ms) to avoid fighting with scroll-snap during large swipes; on a scroll-driven change the aria active item is re-aligned via `gotoIndex` so a following Arrow key moves from the centered value. Programmatic smooth scrolling is used only for keyboard/click/external-value interactions.
+
+---
+
+## Styling
+
+### CSS Custom Properties
+
+| Variable                | Default                 | Purpose                            |
+| ----------------------- | ----------------------- | ---------------------------------- |
+| `--mlv-tp-item-height`  | `2.25rem`               | Item height (density-aware)        |
+| `--mlv-tp-column-width` | `3.5rem`                | Column width (density-aware)       |
+| `--mlv-tp-ampm-width`   | `3rem`                  | AM/PM column width (density-aware) |
+| `--mlv-tp-track-height` | `calc(item-height * 5)` | Viewport height (shows 5 items)    |
+
+Border, background, and focus styling are handled by `mlv-form-control-wrapper` — no component-scoped border variables needed.
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic 24h -->
+<mlv-time-picker label="Start time" [formControl]="timeCtrl" />
+
+<!-- 12h AM/PM mode -->
+<mlv-time-picker label="Meeting time" mode="12h" [formControl]="timeCtrl" />
+
+<!-- With seconds -->
+<mlv-time-picker label="Precise time" [showSeconds]="true" [formControl]="timeCtrl" />
+
+<!-- Disabled -->
+<mlv-time-picker label="Fixed time" disabled [formControl]="timeCtrl" />
+
+<!-- Error state -->
+<mlv-time-picker label="Time" state="error" message="Required" [formControl]="timeCtrl" />
+```
+
+---
+
+## Dependencies
+
+### Internal
+
+- `@malva-ui/core/form-utils` — `MlvSignalFormControlBase`, `MlvFormControlWrapper`, `MlvFormControlWrapperControl`, `MlvHint`, `MlvLabel`, `MLV_FORM_CONTROL`, `MlvMessage`
+- `@malva-ui/core/popup` — `MlvPopup`, `MlvPopupContent`, `MlvPopupContainer`
+- `@malva-ui/core/button` — `MlvButton` (AM/PM toggle buttons)
+- `@malva-ui/cdk/density` — `MlvDensityDirective`, `MLV_DENSITY_ELEMENT`
+- `@lucide/angular` — `LucideClock` (trigger icon)
+
+### Angular
+
+- `@angular/core`, `@angular/forms`, `@angular/cdk/coercion`
+- `@angular/aria/listbox` — `Listbox` (`ngListbox`), `Option` (`ngOption`) backing the drum-roll column (see the aria backing section above)
+
+### Styles
+
+- `@malva-ui/styles` — `mixins.base()`, `density.*` mixins, `--mlv-*` tokens
+
+---
+
+## Field surface (2026-08)
+
+- `ariaLabel` moved to `MlvSignalFormUiControlBase`; `MlvTimePicker` no longer declares its own. `_resolvedAriaLabel()` still falls back to the i18n `timePicker` string, so the rendered name is unchanged when the input is unset.
+- Inherited `required` renders the `mlv-label` marker and sets `aria-required` on the `role="combobox"` trigger.
+- Inherited `description` renders `<mlv-description>` below the control; `aria-describedby` is the base's `_describedBy()`.
+- The public `messageId` computed is gone — `<mlv-message>` carries the base's `_messageId()`.