@malva-ui/core 0.1.12

package/docs/ai/card.md

@@ -0,0 +1,196 @@
+# Library: card
+
+## Overview
+
+The Card library (`@malva-ui/core/card`) provides a flexible, composable container for displaying grouped content. Supports multiple sizes, elevation levels, and named content sections (header, subheader, actions, footer) via structural directives. Background images are also supported.
+
+## Public API
+
+Exported from `@malva-ui/core/card`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvCard` | Component | Main card container — selector `mlv-card` |
+| `MlvCardSize` | Type | `'s' \| 'm' \| 'l'` |
+| `MlvCardBodyLayout` | Type | `'none' \| 'stack'` — layout applied to `.mlv-card__body` |
+| `MlvCardHeaderDef` | Directive | Slot for header content — `[mlvCardHeader]` |
+| `MlvCardSubheaderDef` | Directive | Slot for subheader — `[mlvCardSubheader]` |
+| `MlvCardActionsDef` | Directive | Slot for action buttons — `[mlvCardActions]` |
+| `MlvCardFooterDef` | Directive | Slot for footer — `[mlvCardFooter]` |
+
+---
+
+## Components
+
+### `MlvCard`
+
+- **Selector:** `mlv-card`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+- 
+- 
+- **Imports:** `NgTemplateOutlet`
+
+#### Inputs
+
+| Name              | Type                | Default  | Description                                                                                                                |
+| ----------------- | ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `size`            | `MlvCardSize`       | `'m'`    | Size preset controlling padding, radius, typography                                                                        |
+| `elevated`        | `BooleanInput`      | `false`  | Larger shadow + hover lift effect                                                                                          |
+| `backgroundImage` | `string \| null`    | `null`   | URL for a background image; sets the `--mlv-card-bg-image` CSS variable                                                    |
+| `bodyLayout`      | `MlvCardBodyLayout` | `'none'` | `'stack'` turns `.mlv-card__body` into a vertical flex stack separated by `--mlv-card-body-gap`; `'none'` is a plain block |
+
+#### Content Children (protected)
+
+| Name           | Directive             | Description                |
+| -------------- | --------------------- | -------------------------- |
+| `headerRef`    | `MlvCardHeaderDef`    | Header section template    |
+| `subheaderRef` | `MlvCardSubheaderDef` | Subheader section template |
+| `actionsRef`   | `MlvCardActionsDef`   | Actions section template   |
+| `footerRef`    | `MlvCardFooterDef`    | Footer section template    |
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-card',
+  '[class]': '"mlv-card--size-" + size()',
+  '[class.mlv-card--elevated]': 'elevated()',
+  '[class.mlv-card--has-bg-image]': '!!backgroundImage()',
+  '[style.--mlv-card-bg-image]': 'backgroundImage() ? "url(" + backgroundImage() + ")" : null',
+}
+```
+
+`bodyLayout` is **not** a host binding — it toggles `mlv-card__body--stack` on the body element inside the template, so only the body is affected and the card block keeps its own layout.
+
+#### Template Structure (`card.html`)
+
+```html
+@if (headerRef() || actionsRef()) {
+<div class="mlv-card__header-row">
+  @if (headerRef()) { <ng-container [ngTemplateOutlet]="headerRef()!.templateRef" /> } @if (actionsRef()) {
+  <div class="mlv-card__actions"><ng-container [ngTemplateOutlet]="..." /></div>
+  }
+</div>
+} @if (subheaderRef()) { <ng-container [ngTemplateOutlet]="subheaderRef()!.templateRef" /> }
+<div class="mlv-card__body" [class.mlv-card__body--stack]="bodyLayout() === 'stack'"><ng-content /></div>
+@if (footerRef()) {
+<div class="mlv-card__footer"><ng-container [ngTemplateOutlet]="footerRef()!.templateRef" /></div>
+}
+```
+
+#### Size Presets
+
+| Size | Padding     | Radius       | Heading font    | Subheading     | Gap       |
+| ---- | ----------- | ------------ | --------------- | -------------- | --------- |
+| `s`  | `spacing-3` | `radius-xl`  | `font-size-xl`  | `font-size-s`  | Inherited |
+| `m`  | `spacing-5` | `radius-2xl` | `font-size-3xl` | `font-size-l`  | Inherited |
+| `l`  | `spacing-8` | `radius-3xl` | `font-size-4xl` | `font-size-xl` | Inherited |
+
+#### Styles Summary (`card.scss`)
+
+- Base: `display: flex; flex-direction: column; overflow: hidden`
+- Background: `var(--mlv-background-elevation-1)`; Shadow: `var(--mlv-shadow-small)`
+- Smooth transitions on shadow, background, transform
+- Elevated variant: larger shadow, hover → `translateY(-0.125rem)` lift
+- Background image variant: `background-size: cover; background-position: center`
+- CSS class helpers:
+  - `.mlv-card__header-row` — `display: flex; justify-content: space-between`
+  - `.mlv-card__heading` — `flex: 1; overflow: hidden; text-overflow: ellipsis`
+  - `.mlv-card__actions` — `display: flex; align-items: center; gap: 0.25rem; flex-shrink: 0`
+  - `.mlv-card__subheading` — secondary text color, `line-height: 1.5`
+  - `.mlv-card__body` — `flex: 1; min-height: 0` (untouched by `bodyLayout="none"`)
+  - `.mlv-card__body--stack` — `display: flex; flex-direction: column; gap: var(--mlv-card-body-gap)`; `--mlv-card-body-gap` defaults to `--mlv-spacing-3` and scales with the size preset (`s` → `--mlv-spacing-2`, `m` → `--mlv-spacing-3`, `l` → `--mlv-spacing-4`). Override it per card (`style="--mlv-card-body-gap: 1.5rem"`).
+  - `.mlv-card__footer` — `display: flex; align-items: center; border-top; margin-top: auto; gap: 0.5rem`
+  - `.mlv-card__footer--full-width > *` — `flex: 1` (equal-width footer items)
+
+---
+
+## Directives
+
+All defined in their own files under *(internal)*.
+
+### `MlvCardHeaderDef`
+
+ | **Selector:** `[mlvCardHeader]`
+
+Provides `templateRef = inject(TemplateRef)`. Used with `<ng-template mlvCardHeader>`.
+
+### `MlvCardSubheaderDef`
+
+ | **Selector:** `[mlvCardSubheader]`
+
+Provides `templateRef = inject(TemplateRef)`. Used with `<ng-template mlvCardSubheader>`.
+
+### `MlvCardActionsDef`
+
+ | **Selector:** `[mlvCardActions]`
+
+Provides `templateRef = inject(TemplateRef)`. Renders in the header row, right-aligned.
+
+### `MlvCardFooterDef`
+
+ | **Selector:** `[mlvCardFooter]`
+
+Provides `templateRef = inject(TemplateRef)`. Renders at the bottom with a top border separator.
+
+---
+
+## Services
+
+None.
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic card -->
+<mlv-card>
+  <p>Content here</p>
+</mlv-card>
+
+<!-- Card with header, subheader, actions, and footer -->
+<mlv-card size="l" [elevated]="true">
+  <ng-template mlvCardHeader>
+    <h2 class="mlv-card__heading">Card Title</h2>
+  </ng-template>
+  <ng-template mlvCardActions>
+    <button mlvButton shape="square" variant="transparent" size="small">⋯</button>
+  </ng-template>
+  <ng-template mlvCardSubheader>
+    <p class="mlv-card__subheading">A supporting subtitle</p>
+  </ng-template>
+
+  <div>Main body content</div>
+
+  <ng-template mlvCardFooter>
+    <button mlvButton>Save</button>
+    <button mlvButton variant="outlined">Cancel</button>
+  </ng-template>
+</mlv-card>
+
+<!-- Card with background image -->
+<mlv-card backgroundImage="/assets/banner.jpg">
+  <p>Text over image</p>
+</mlv-card>
+
+<!-- Stacked body — no hand-rolled wrapper needed for vertical rhythm -->
+<mlv-card bodyLayout="stack">
+  <p>Summary line</p>
+  <div><mlv-badge tone="success" muted>Healthy</mlv-badge></div>
+  <p>Last deployed 12 minutes ago.</p>
+</mlv-card>
+
+<!-- Per-card gap override -->
+<mlv-card bodyLayout="stack" style="--mlv-card-body-gap: 1.5rem">…</mlv-card>
+```
+
+---
+
+## Dependencies
+
+- `@angular/core` ^22.0.0 — signals, `contentChild()`
+- `@angular/common` — `NgTemplateOutlet`
+- `@angular/cdk/coercion` — `BooleanInput`
+- Malva UI CSS design tokens (`--mlv-*`)

package/docs/ai/chat.md

@@ -0,0 +1,145 @@
+# @malva-ui/core/chat
+
+**Import path:** `@malva-ui/core/chat` (also re-exported from `@malva-ui/core`)
+**Nx project:** `core-chat` — `lint` + `test` targets
+
+Data-driven chat surface. `mlv-chat` renders an oldest→newest `messages` array as author groups with date separators, delivery ticks, embedded reply quotes, an image/gif/video grid, audio playback, a typing indicator, loading skeletons, appear/removal animations, and reverse infinite pagination. Grouping and date insertion are computed internally — consumers only supply flat data.
+
+**Naming:** the bubble component is `MlvChatMessage`; the message *data* interface is **`MlvChatMessageData`**. The `mlv-message` selector and `.mlv-message` BEM block are already owned by `MlvMessage` in `@malva-ui/core/form-utils`, which is why the lib is `chat` (not `message`) and every selector is `mlv-chat-*`.
+
+---
+
+## Public API
+
+| Export                                             | Kind                  | Description                                                          |
+| -------------------------------------------------- | --------------------- | -------------------------------------------------------------------- |
+| `MlvChat`                                          | Component             | `mlv-chat` — scroll container and renderer                           |
+| `MlvChatMessage`                                   | Component             | `mlv-chat-message` — one bubble; rendered internally, usable alone   |
+| `MlvChatMessageDef`                                | Structural directive  | `[mlvChatMessageDef]` — custom bubble body per message `type`        |
+| `MlvChatAuthorDef`                                 | Structural directive  | `[mlvChatAuthorDef]` — custom author slot above other-authored groups |
+| `MlvChatDateDef`                                   | Structural directive  | `[mlvChatDateDef]` — custom date separator                           |
+| `MlvChatMessageData<TData>`                        | Interface             | One message                                                          |
+| `MlvChatUser`, `MlvChatAttachment`                 | Interfaces            | Participant / attachment                                             |
+| `MlvChatMessageStatus`, `MlvChatGroupPosition`     | Types                 | `'sending' \| 'sent' \| 'delivered' \| 'read' \| 'failed'`; `'single' \| 'first' \| 'middle' \| 'last'` |
+| `MlvChatRenderItem`, `MlvChatRenderMessage`        | Types                 | Output of `buildChatRenderList`                                      |
+| `MlvChatMessageDefContext`, `MlvChatMessageDefRef` | Interfaces            | Template context / registered def                                    |
+| `MlvChatAuthorDefContext`, `MlvChatDateDefContext` | Interfaces            | Template contexts                                                    |
+| `MLV_CHAT_USERS`, `MLV_CHAT_MESSAGE_DEFS`          | Injection tokens      | Container→bubble wiring                                              |
+| `buildChatRenderList`, `toChatDate`, `isSameChatDay`, `formatChatDuration` | Functions | Pure helpers (also used by the internals)                  |
+
+**Internal, deliberately not exported:** `MlvChatMediaGrid`, `MlvChatAudio`, `MlvChatAudioService`, `MLV_CHAT_AUDIO_FACTORY`, `MlvChatDate`, `MlvChatTyping`.
+
+---
+
+## `MlvChat`
+
+**Files:** *(internal)*
+**Selector:** `mlv-chat` · `ViewEncapsulation.None` · OnPush
+
+### Inputs
+
+| Input            | Type                    | Default  | Description                                                        |
+| ---------------- | ----------------------- | -------- | ------------------------------------------------------------------ |
+| `messages`       | `MlvChatMessageData[]`  | required | Ordered oldest → newest                                            |
+| `selfId`         | `string`                | required | Messages with this `authorId` render as own                        |
+| `users`          | `MlvChatUser[]`         | `[]`     | Avatars, author names, typing names                                |
+| `loading`        | `BooleanInput`          | `false`  | Skeleton bubbles instead of content                                |
+| `loadingOlder`   | `BooleanInput`          | `false`  | Top spinner; also suppresses further `loadOlder`                   |
+| `hasOlder`       | `BooleanInput`          | `false`  | Gates `loadOlder`                                                  |
+| `typingUsers`    | `string[]`              | `[]`     | Ids resolved against `users`; unknown ids are dropped              |
+| `groupWindow`    | `number`                | `5`      | Max gap in minutes inside one author group                         |
+| `showAuthors`    | `'auto' \| boolean`     | `'auto'` | `'auto'` shows the author slot once `users.length > 2`             |
+| `dateSeparators` | `BooleanInput`          | `true`   | Calendar-day separators                                            |
+| `windowSize`     | `number`                | `150`    | Newest messages kept in the DOM                                    |
+| `mlvDensity`     | `MlvDensity`            | ambient  | Via `MlvDensityDirective` host directive                           |
+
+### Outputs
+
+| Output       | Payload                                                       | When                                          |
+| ------------ | ------------------------------------------------------------- | --------------------------------------------- |
+| `loadOlder`  | `void`                                                        | Near the top, window exhausted, `hasOlder` set |
+| `retry`      | `MlvChatMessageData`                                          | Retry on a failed own message                 |
+| `mediaClick` | `{ message, attachment }`                                     | A media cell was activated                    |
+| `replyClick` | `{ message, replyTo }`                                        | A reply quote was activated                   |
+
+### Providers / host directives
+
+`MlvChatAudioService` (per-chat playback exclusivity), `MLV_DENSITY_ELEMENT: 'chat'`, `MLV_CHAT_USERS`, `MLV_CHAT_MESSAGE_DEFS`; host directive `MlvDensityDirective` (input `mlvDensity`).
+
+---
+
+## `MlvChatMessage`
+
+**Files:** *(internal)*
+
+| Input           | Type                    | Default    | Description                                             |
+| --------------- | ----------------------- | ---------- | ------------------------------------------------------- |
+| `message`       | `MlvChatMessageData`    | required   | The message                                             |
+| `own`           | `BooleanInput`          | `false`    | Right-aligned accent bubble; ticks render only when true |
+| `groupPosition` | `MlvChatGroupPosition`  | `'single'` | Corner-tail radii                                       |
+| `quote`         | `BooleanInput`          | `false`    | Condensed reply-quote rendering                         |
+
+Outputs: `retry: void`, `mediaClick: MlvChatAttachment`, `replyClick: MlvChatMessageData`.
+
+Content order inside the bubble: reply quote → media grid → audio players → text → meta row (time + ticks; retry button when `failed`).
+
+---
+
+## Behavior
+
+### Grouping (`buildChatRenderList`)
+
+Pure function in `chat-render-list.ts`. Breaks a group on author change, on a gap larger than `groupWindow` minutes, and always at a calendar-day boundary. Emits `{ kind: 'date' }` items (ids `date-YYYY-M-D`) and `{ kind: 'group' }` items (ids `group-<first message id>`) with each message's `position`.
+
+### Scroll engine
+
+Native scroll plus `content-visibility: auto` on group rows (no view recycling, so animations and reading order stay intact).
+
+- Pinned when within 48px of the bottom. Appending while pinned smooth-scrolls down; while unpinned it increments the "N new messages" pill.
+- Pinning is re-applied from a `MlvResizeObserverService` subscription on the inner `.mlv-chat__content` wrapper, not from renders alone — media loading late and `content-visibility` revealing height both change the scroll height without a change-detection pass.
+- Within 150px of the top the render window grows by 50 messages; once the window covers the whole array and `hasOlder` is set (and `loadingOlder` is not), `loadOlder` fires.
+- Prepending compensates the scroll position by the height delta (captured before render, applied in an `afterRenderEffect`).
+- Re-pinning trims the window back to `windowSize` and clears the pill.
+- `_evaluateScroll(scrollTop, scrollHeight, clientHeight)` holds the logic separately from DOM measurement so it is testable without layout.
+
+### Replies
+
+`replyTo` carries a **full** `MlvChatMessageData`, not an id — so a quote renders correctly even when the original sits outside the loaded pages. The quote is the same bubble in `quote` mode (clamped text, thumbnail, audio chip, no meta). Recursion is one level deep: a quoted message with its own `replyTo` shows a `↩` marker instead of nesting.
+
+### Media
+
+1 item large (aspect ratio reserved from `width`/`height`), 2–4 in a 2-column grid, >4 collapses to four cells with a `+N` overlay. Skeleton per image until `load`. `video` renders poster + play badge + duration chip (no inline player); `gif` autoplays muted on a loop. `uploadProgress` dims the cell and overlays `mlv-progress`.
+
+### Audio
+
+Native `HTMLAudioElement` created lazily through `MLV_CHAT_AUDIO_FACTORY` (overridable in tests). `MlvChatAudioService` is provided by `mlv-chat`, so only one audio message plays per chat; a standalone bubble injects it optionally and plays without coordination.
+
+### Animations
+
+Only live-appended messages animate in — ids are recorded in `_liveIds` when the array's last id changes, so initial load, window growth, and prepended history render instantly. Enter: grid-rows collapse + fade + translateY (`--mlv-duration-slow`, `--mlv-ease-out-strong`). Leave via `animate.leave="mlv-chat__item--leave"`. `@include mixins.reduced-motion` on `mlv-chat`, `mlv-chat-message`, and `mlv-chat-typing`.
+
+---
+
+## Accessibility
+
+- Viewport: `role="log"` (polite by default), i18n `aria-label`, `tabindex="0"`.
+- Each message is an `<article>` labelled `"{author}, {time}, {status}"`; status icons are `aria-hidden`.
+- Retry and media cells are real buttons with accessible names; images always carry `alt` (i18n fallback).
+
+---
+
+## i18n
+
+Token `MLV_CHAT_I18N` (*(internal)*). Keys: `chatLabel`, `today`, `yesterday`, `statusSending`, `statusSent`, `statusDelivered`, `statusRead`, `statusFailed`, `retry`, `newMessages` (ICU `{count}`), `typing` (ICU `{count}`), `playAudio`, `pauseAudio`, `imageFallbackAlt`, `moreMedia` (ICU `{count}`), `loadingOlder`. Shipped in all fourteen locale packs (de, en, es, fr, id, it, ja, nl, pl, pt, ro, tr, uk, zh-Hans).
+
+---
+
+## Styling
+
+BEM blocks `.mlv-chat`, `.mlv-chat-message`, `.mlv-chat-media-grid`, `.mlv-chat-audio`, `.mlv-chat-date`, `.mlv-chat-typing`. The group avatar is `position: sticky; inset-block-end: 0`, so a tall run keeps its avatar in view. Because the global `[class*='mlv']` reset drops inherited colour, `__text`, `__meta`, `__time`, and `__status` each restate `--mlv-chat-message-color`; the read tick is the full-strength bubble colour (ticks only render on the accent own-bubble, where an info hue would sit blue-on-blue). State-driven custom properties only: `--mlv-chat-gap`, `--mlv-chat-padding`, `--mlv-chat-bubble-gap` (density), `--mlv-chat-message-bg/-color/-radius/-tail-radius` (own/other/failed). Density levels tight → airy via `density.scss` mixins, comfortable being the base.
+
+---
+
+## Dependencies
+
+`@angular/{core,common,cdk}`, `@lucide/angular`, `@malva-ui/cdk/density`, `@malva-ui/i18n`, and the `@malva-ui/core` leaves `avatar`, `button`, `loader`, `progress`, `skeleton`, `slider`.

package/docs/ai/checkbox.md

@@ -0,0 +1,193 @@
+# Library: checkbox
+
+## Overview
+
+The checkbox library (`@malva-ui/core/checkbox`) provides accessible, stateful checkbox components. Includes a standalone checkbox component supporting indeterminate states and a checkbox group for managing multiple checkboxes together with keyboard navigation (arrow keys).
+
+> **Accessible naming (`aria-label` / `aria-labelledby`)** — the host element is
+> role-less, so ARIA prohibits naming attributes on it (axe
+> `aria-prohibited-attr`); the real accessible-name target is the inner
+> `<input type="checkbox">`. Two supported forms, both landing on the inner input:
+>
+> 1. **`ariaLabel` / `ariaLabelledBy` inputs** — for dynamic labels
+>    (`<mlv-checkbox [ariaLabel]="'Select row ' + i" />`). Never bind
+>    `[attr.aria-label]` on the host — Angular writes it straight onto the host
+>    element where it cannot be intercepted.
+> 2. **Static host attribute** (`<mlv-checkbox aria-label="Select row" />`) —
+>    captured via `HostAttributeToken` in the constructor, imperatively removed
+>    from the host (`Renderer2.removeAttribute`), and forwarded to the input.
+>
+> The inputs win over a captured static attribute
+> (`_resolvedAriaLabel`/`_resolvedAriaLabelledBy` computeds); when neither is
+> supplied no attribute is emitted. `input({ alias: 'aria-label' })` was tried
+> first and reverted: Angular does not consume a static `aria-label` attribute
+> into an aliased input when it is also a real DOM attribute. `mlv-radio` and
+> `mlv-switch` implement the identical pattern.
+
+## Public API
+
+Exported from `@malva-ui/core/checkbox`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvCheckbox` | Component | Standalone checkbox — `mlv-checkbox` |
+| `MlvCheckboxState` | Type | `'default' \| 'success' \| 'info' \| 'warning' \| 'error'` (alias of `MlvFormState`) |
+| `MlvCheckboxGroup` | Component | Group container — `mlv-checkbox-group` |
+| `MlvCheckboxGroupState` | Type | Same values as `MlvCheckboxState` (alias of `MlvFormState`) |
+
+---
+
+## Components
+
+### `MlvCheckbox`
+
+- **Selector:** `mlv-checkbox`
+- **Change Detection:** `OnPush`
+- **Extends:** `MlvSignalCheckboxControlBase` from `@malva-ui/core/form-utils` (signal forms — no `ControlValueAccessor`)
+- **Focus management:** `MlvCheckboxGroup` adapts checkbox instances to `FocusKeyManager` and uses `computedDisabled()` as the skip predicate, preserving `[disabled]` as a signal input.
+
+#### Inputs
+
+| Name             | Type                  | Default     | Description                                                                                                                                                                                                                                                                                                                              |
+| ---------------- | --------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `indeterminate`  | `boolean`             | `false`     | Shows minus icon (mixed state)                                                                                                                                                                                                                                                                                                           |
+| `disabled`       | `boolean`             | `false`     | Disables the checkbox                                                                                                                                                                                                                                                                                                                    |
+| `tabbable`       | `boolean` (coerced)   | `true`      | When `false`, forces the native input to `tabindex="-1"` regardless of group roving state. Composite parents (`mlv-tree` multi-select rows, `mlv-data-table` rows) set `[tabbable]="false"` to keep a single tab stop while the checkbox stays operable via the row (Space) and the mouse.                                               |
+| `label`          | `string`              | `''`        | **Visible** label text, rendered inside the `<label>` when nothing is projected into `<mlv-checkbox>`. Projected content always wins: the fallback stays in the DOM but is `display: none`-d by `.mlv-checkbox__content:not(:empty) + .mlv-checkbox__label-text`, so it never joins the accessible name. Inherited from the signal base. |
+| `required`       | `boolean` (coerced)   | `false`     | Sets `aria-required` on the native input. Also a signal-forms field binding. Inherited from the signal base.                                                                                                                                                                                                                             |
+| `ariaLabel`      | `string \| null`      | `null`      | Accessible name applied to the inner native input. Use for dynamic labels; wins over a captured static host `aria-label` (see the naming note above). Inherited from the signal base since 2026-08 (was a checkbox-local input).                                                                                                         |
+| `ariaLabelledBy` | `string \| undefined` | `undefined` | Id reference(s) naming the inner native input. Same rationale/precedence as `ariaLabel`.                                                                                                                                                                                                                                                 |
+| `state`          | `MlvCheckboxState`    | `'default'` | Visual state                                                                                                                                                                                                                                                                                                                             |
+
+#### Inputs (inherited from `MlvSignalFormUiControlBase`)
+
+| Name          | Type                                               | Default                    | Description                                                                      |
+| ------------- | -------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------- |
+| `readonly`    | `boolean`                                          | `false`                    | Read-only control; also a signal-forms field binding.                            |
+| `loading`     | `boolean`                                          | `false`                    | Shows the loading affordance.                                                    |
+| `clearable`   | `boolean`                                          | `false`                    | Renders the clear (X) affordance while the control has a value.                  |
+| `pill`        | `boolean`                                          | `false`                    | Fully rounded (stadium) control container.                                       |
+| `errors`      | `readonly ValidationError.WithOptionalFieldTree[]` | `[]`                       | Signal-forms field binding: current validation errors.                           |
+| `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`                                           | `mlvNextId('mlv-control')` | HTML id applied to the control's focus target.                                   |
+| `hint`        | `string`                                           | `''`                       | Hint text rendered inside the label.                                             |
+| `description` | `string`                                           | `''`                       | Persistent help text rendered below the control (`<mlv-description>` slot wins). |
+| `message`     | `string`                                           | `''`                       | Validation/status message rendered below the control.                            |
+
+#### Model (two-way binding)
+
+| Name      | Type      | Default |
+| --------- | --------- | ------- |
+| `checked` | `boolean` | `false` |
+
+#### Outputs
+
+| Name            | Type      | Description                                                                                 |
+| --------------- | --------- | ------------------------------------------------------------------------------------------- |
+| `checkedChange` | `boolean` | The `checked` model's change output.                                                        |
+| `touch`         | `void`    | Inherited. Emitted on blur — the signal-forms replacement for the CVA `onTouched` callback. |
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-checkbox',
+  '[class.mlv-checkbox--disabled]': 'computedDisabled()',
+  '[class.mlv-checkbox--checked]': 'checked()',
+  '[class.mlv-checkbox--indeterminate]': 'indeterminate()',
+}
+```
+
+The host is **not** focusable. The single focus target is the visually-hidden
+native `<input type="checkbox">` (clip-path pattern, kept in the a11y tree). Its
+`tabindex` is `_resolvedTabIndex()` — the roving tabindex (`tabIndex` signal,
+managed by `MlvCheckboxGroup` and updated as focus moves) gated by the
+`tabbable` input.
+
+#### Key Methods
+
+- `focus()` — Focuses the native input (not the host); adapts to CDK `FocusKeyManager`.
+- `toggle(event)` — Toggle checked state (bound to the input's Enter keydown)
+- `onInputChange(event)` — Reflects native `change` (Space / click)
+- `setFocused(focused)` — Inherited from the signal base; updates the focus signal driving the wrapper state.
+
+There is no `writeValue`/`setDisabledState` pair any more: the control is a
+signal-forms field, not a `ControlValueAccessor` (see the 2026-07 cutover note).
+
+#### Keyboard & Focus
+
+- **Single tab stop:** the native input carries the roving tabindex; the host is not tabbable (no more double tab stop).
+- **Space** toggles natively (fires `change`); **Enter** toggles via the input's `(keydown.enter)`.
+- **`:focus-visible`** ring is promoted from the hidden input onto `.mlv-checkbox__visual` using `--mlv-border-focus`.
+
+#### Template Summary
+
+Label wrapping the visually-hidden native checkbox (`#nativeInput`, `[attr.tabindex]="_resolvedTabIndex()"`) + visual element with dynamic icon (check or minus for indeterminate) + `.mlv-checkbox__text`, which holds `.mlv-checkbox__content` (`ng-content`) followed by the `.mlv-checkbox__label-text` fallback rendered from the `label` input. ARIA attributes on the native input: `aria-checked`, `aria-required`, plus `aria-label` / `aria-labelledby` forwarded from the host (see the forwarding note above).
+
+A dev-mode `console.warn` fires once per instance when a checkbox has no projected text, no `label`, and no `ariaLabel`/`ariaLabelledBy` — i.e. no accessible name at all.
+
+---
+
+### `MlvCheckboxGroup`
+
+- **Selector:** `mlv-checkbox-group`
+- **Change Detection:** `OnPush`
+- **Extends:** `MlvFocusableGroupBase<MlvCheckbox>` from `@malva-ui/core/form-utils` — the shared roving-tabindex `FocusKeyManager` lifecycle (arrow nav, `change`→tabindex sync, teardown) lives in the base; the group only supplies `_items` (projected checkboxes) + `_isDisabled` (`computedDisabled()`).
+- **Template:** Inline — `div[role="group"]` with optional label + `<ng-content>`
+
+#### Inputs
+
+| Name    | Type                    | Default     |
+| ------- | ----------------------- | ----------- |
+| `label` | `string`                | `''`        |
+| `state` | `MlvCheckboxGroupState` | `'default'` |
+
+#### Methods (inherited from `MlvFocusableGroupBase`)
+
+| Method                            | Description                                                                        |
+| --------------------------------- | ---------------------------------------------------------------------------------- |
+| `onChildFocus(child)`             | Marks the focused child active in the `FocusKeyManager` (roving tabindex).         |
+| `onKeydown(event: KeyboardEvent)` | Forwards arrow/Home/End keys to the `FocusKeyManager`, skipping disabled children. |
+
+#### Keyboard Navigation
+
+`FocusKeyManager` (from `MlvFocusableGroupBase`) — arrow up/down navigates between child checkboxes, skips disabled via `computedDisabled()`, and the base's `change`-sub keeps the roving `tabindex=0` on the focused checkbox.
+
+#### Internal Token
+
+`CHECKBOX_GROUP: InjectionToken<MlvCheckboxGroupAccessor>` — injected by children to notify parent of focus events.
+
+---
+
+## Usage Examples
+
+```html
+<!-- Standalone -->
+<mlv-checkbox [(checked)]="isChecked">Accept terms</mlv-checkbox>
+
+<!-- Indeterminate -->
+<mlv-checkbox [indeterminate]="true">Select all</mlv-checkbox>
+
+<!-- Grouped -->
+<mlv-checkbox-group label="Preferences">
+  <mlv-checkbox [(checked)]="opt1">Option 1</mlv-checkbox>
+  <mlv-checkbox [(checked)]="opt2">Option 2</mlv-checkbox>
+</mlv-checkbox-group>
+
+<!-- Reactive forms -->
+<mlv-checkbox [formControl]="ctrl">Subscribe</mlv-checkbox>
+```
+
+---
+
+## Testing
+
+---
+
+## Dependencies
+
+- `@angular/core`, `@angular/forms` — CVA, form integration
+- `@angular/cdk/a11y` — `FocusableOption`, `FocusKeyManager`
+- `@lucide/angular` — `LucideCheck`, `LucideMinus` icons
+- `@malva-ui/core/form-utils` — `MlvLabel`