@malva-ui/core 0.1.12

package/docs/ai/alert.md

@@ -0,0 +1,190 @@
+# Library: alert
+
+## Overview
+
+`@malva-ui/core/alert` provides an inline feedback banner component (`mlv-alert`) for displaying contextual messages with four semantic tones. Supports a dismissible mode with an animated close button, a custom icon slot, and separate content-projection slots for title and description.
+
+---
+
+## Public API
+
+Exported from `@malva-ui/core/alert`:
+
+| Export          | Kind      | Description                          |
+| --------------- | --------- | ------------------------------------ |
+| `MlvAlert`      | Component | `mlv-alert` — inline feedback banner |
+| `MlvAlertIcon`  | Directive | `[mlvAlertIcon]` — custom icon slot  |
+| `MlvAlertTitle` | Directive | `[mlvAlertTitle]` — title slot       |
+
+The `tone` input is typed with the shared `MlvTone` type from `@malva-ui/cdk/utils` (`'info' \| 'success' \| 'warning' \| 'danger'`) — alert no longer declares its own tone type.
+
+---
+
+## Components
+
+### `MlvAlert`
+
+**Selector:** `mlv-alert` | **Change Detection:** `OnPush` | **Encapsulation:** `None`
+
+#### Inputs
+
+| Name          | Type           | Default  | Description                                                                   |
+| ------------- | -------------- | -------- | ----------------------------------------------------------------------------- |
+| `tone`        | `MlvTone`      | `'info'` | Semantic tone controlling color scheme and default icon                       |
+| `dismissible` | `BooleanInput` | `false`  | Renders a dismiss button; supports attribute syntax `<mlv-alert dismissible>` |
+
+#### Outputs
+
+| Name        | Type   | Description                                   |
+| ----------- | ------ | --------------------------------------------- |
+| `dismissed` | `void` | Emits when the user clicks the dismiss button |
+
+#### Host Bindings
+
+```ts
+host: {
+  class: 'mlv-alert',
+  '[class]': '"mlv-alert--tone-" + tone()',
+  '[class.mlv-alert--dismissed]': '_dismissed()',
+  'role': 'alert',
+  '[attr.aria-live]': '"polite"',
+  '[attr.hidden]': '_dismissed() || null',
+}
+```
+
+#### Content Projection
+
+| Slot        | Directive         | Description                                                                |
+| ----------- | ----------------- | -------------------------------------------------------------------------- |
+| Icon        | `[mlvAlertIcon]`  | Custom icon inside `<ng-template>`; overrides the default Lucide tone icon |
+| Title       | `[mlvAlertTitle]` | Title text inside `<ng-template>`; rendered above the description          |
+| Description | (default)         | Main message content projected via `<ng-content />`                        |
+
+---
+
+## Directives
+
+### `MlvAlertIcon`
+
+**Selector:** `[mlvAlertIcon]`
+
+Marks an `<ng-template>` slot for a custom icon. The parent `MlvAlert` queries this via `contentChild(MlvAlertIcon)`.
+
+### `MlvAlertTitle`
+
+**Selector:** `[mlvAlertTitle]`
+
+Marks an `<ng-template>` slot for a title heading rendered above the description content.
+
+---
+
+## Types
+
+The `tone` input uses the shared `MlvTone` type re-exported from `@malva-ui/cdk/utils`:
+
+```ts
+export type MlvTone = 'info' | 'success' | 'warning' | 'danger';
+```
+
+Alert's tone vocabulary matches `MlvTone` exactly, so it does not declare a component-local type.
+
+---
+
+## CSS Classes
+
+| Class                     | Description                                                  |
+| ------------------------- | ------------------------------------------------------------ |
+| `.mlv-alert`              | Root block — flex row, border, background                    |
+| `.mlv-alert__icon`        | Icon container (aria-hidden)                                 |
+| `.mlv-alert__body`        | Column container for title + description                     |
+| `.mlv-alert__title`       | Title text (semibold)                                        |
+| `.mlv-alert__description` | Description content                                          |
+| `.mlv-alert__dismiss`     | Dismiss button                                               |
+| `.mlv-alert--tone-{name}` | Tone color modifier (`info`, `success`, `warning`, `danger`) |
+| `.mlv-alert--dismissed`   | Added after dismiss; hides the alert via `display: none`     |
+
+## CSS Custom Properties
+
+| Property                 | Default                        | Description                            |
+| ------------------------ | ------------------------------ | -------------------------------------- |
+| `--mlv-alert-bg`         | `var(--mlv-background-info-2)` | Alert background; overridden by tone   |
+| `--mlv-alert-color`      | `var(--mlv-text-on-info)`      | Alert text color; overridden by tone   |
+| `--mlv-alert-border`     | `var(--mlv-border-info)`       | Alert border color; overridden by tone |
+| `--mlv-alert-icon-color` | `var(--mlv-text-on-info)`      | Icon color; overridden by tone         |
+
+---
+
+## Tone Color Mapping
+
+| `tone`    | Background token             | Text token              | Border token           |
+| --------- | ---------------------------- | ----------------------- | ---------------------- |
+| `info`    | `--mlv-background-info-2`    | `--mlv-text-on-info`    | `--mlv-border-info`    |
+| `success` | `--mlv-background-success-2` | `--mlv-text-on-success` | `--mlv-border-success` |
+| `warning` | `--mlv-background-warning-2` | `--mlv-text-on-warning` | `--mlv-border-warning` |
+| `danger`  | `--mlv-background-danger-2`  | `--mlv-text-on-danger`  | `--mlv-border-danger`  |
+
+---
+
+## Default Icons Per Tone
+
+| `tone`    | Lucide icon           |
+| --------- | --------------------- |
+| `info`    | `LucideInfo`          |
+| `success` | `LucideCheckCircle`   |
+| `warning` | `LucideTriangleAlert` |
+| `danger`  | `LucideCircleX`       |
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic info alert -->
+<mlv-alert tone="info">Your session will expire in 5 minutes.</mlv-alert>
+
+<!-- Success with title -->
+<mlv-alert tone="success">
+  <ng-template mlvAlertTitle>Upload complete</ng-template>
+  Your file has been uploaded and is ready to use.
+</mlv-alert>
+
+<!-- Warning, dismissible -->
+<mlv-alert tone="warning" dismissible (dismissed)="onDismissed()"> You are running low on storage. </mlv-alert>
+
+<!-- Danger with title and dismiss -->
+<mlv-alert tone="danger" dismissible>
+  <ng-template mlvAlertTitle>Payment failed</ng-template>
+  Your card was declined. Please update your payment method.
+</mlv-alert>
+
+<!-- Custom icon -->
+<mlv-alert tone="info">
+  <ng-template mlvAlertIcon><svg lucideRocket [size]="18" /></ng-template>
+  A new version is available.
+</mlv-alert>
+```
+
+---
+
+## Accessibility
+
+- Host has `role="alert"` and `aria-live="polite"` for live-region announcement.
+- Icon area is `aria-hidden="true"` — purely decorative.
+- Dismiss button has `aria-label="Dismiss alert"`.
+- `[attr.hidden]` is set on the host after dismiss so the element is removed from the accessibility tree.
+- Dismiss button has `:focus-visible` ring using `--mlv-border-focus`.
+
+---
+
+## Dependencies
+
+| Package                 | Version   | Role                                                                                 |
+| ----------------------- | --------- | ------------------------------------------------------------------------------------ |
+| `@angular/core`         | `^22.0.0` | Signals, DI, component, directives                                                   |
+| `@angular/common`       | `^22.0.0` | `NgTemplateOutlet`                                                                   |
+| `@angular/cdk/coercion` | `^22.0.0` | `BooleanInput`, `coerceBooleanProperty`                                              |
+| `@lucide/angular`       | `*`       | `LucideInfo`, `LucideCheckCircle`, `LucideTriangleAlert`, `LucideCircleX`, `LucideX` |
+
+---
+
+## File Structure

package/docs/ai/autocomplete.md

@@ -0,0 +1,111 @@
+# Library: autocomplete
+
+## Overview
+
+`@malva-ui/core/autocomplete` provides a single reusable attribute directive, **`[mlvAutocomplete]`**, that adds autocomplete / typeahead behaviour to **any** text input — a native `<input>` or a `<mlv-input>` — without turning the field into a form control. It reuses the same building blocks as `mlv-combobox`: the shared substring **matcher** (`filterOptions` / `defaultOptionMatcher` from `@malva-ui/core/dropdown`), the **`mlv-dropdown-panel`** suggestion list, and the shared **`MlvOptionsAdapter`** source engine.
+
+The directive is the new surface for arbitrary inputs; `mlv-combobox` remains the full `FormControlBase` combobox. Both now share one matching implementation.
+
+## Public API
+
+Exported from `@malva-ui/core/autocomplete`:
+
+| Export                       | Kind      | Description                                                                                                     |
+| ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- |
+| `MlvAutocomplete<T>`         | Directive | `[mlvAutocomplete]` / `[mlvAutocompleteSearch]` — the autocomplete behaviour                                    |
+| `MlvAutocompleteSearchFn<T>` | Type      | Alias of `MlvOptionsSearchFn<T>` (`@malva-ui/core/dropdown`), kept for backwards compatibility — same signature |
+
+## `MlvAutocomplete<T>`
+
+**Selector:** `[mlvAutocomplete], [mlvAutocompleteSearch]`
+**exportAs:** `mlvAutocomplete`
+
+Attribute directive — no template. It renders the suggestion popup via a CDK **overlay hosting a `mlv-dropdown-panel` component portal** (a headless attribute directive cannot host `mlv-popup`'s declarative `ng-template mlvPopupContent`; the overlay is the same CDK primitive `mlv-popup` itself wraps). The panel is reused unchanged for list rendering, option groups, aria listbox semantics, and the activedescendant highlight.
+
+### Inputs
+
+| Input (alias)                                                        | Type                                 | Default                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| -------------------------------------------------------------------- | ------------------------------------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options` (`mlvAutocomplete`)                                        | `MlvOptionsInput<T>`                 | `[]`                     | Suggestion source: `readonly T[]` / `Observable<readonly T[]>` (**local** — filtered with `matcher`), or a `MlvDataSource<T>` (**remote** — it filters via `setSearch({ query, keys: [] })` and pages). Ignored when `search` is set.                                                                                                                                                                                                          |
+| `search` (`mlvAutocompleteSearch`)                                   | `MlvAutocompleteSearchFn<T> \| null` | `null`                   | Async source; supersedes `options`. Array / Promise / Observable. A newer query supersedes an in-flight one (its result is discarded) while the previous results stay visible.                                                                                                                                                                                                                                                                 |
+| `toOption` (`mlvAutocompleteToOption`)                               | `MlvSelectOptionTransform<T>`        | `defaultOptionTransform` | Maps a raw item to `{ label, value, group? }`.                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `matcher` (`mlvAutocompleteMatcher`)                                 | `MlvOptionMatcher<T>`                | `defaultOptionMatcher`   | Predicate for local filtering (case- + diacritic-insensitive substring by default).                                                                                                                                                                                                                                                                                                                                                            |
+| `debounce` (`mlvAutocompleteDebounce`)                               | `number`                             | `200`                    | Debounce (ms) before filtering / searching.                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `minLength` (`mlvAutocompleteMinLength`)                             | `number`                             | `0`                      | Min query length before opening. `0` opens on focus (cheap local); use `2+` for async.                                                                                                                                                                                                                                                                                                                                                         |
+| `highlight` (`mlvAutocompleteHighlight`)                             | `boolean`                            | `true`                   | Emphasise the matched substring in each suggestion.                                                                                                                                                                                                                                                                                                                                                                                            |
+| `inline` (`mlvAutocompleteInline`)                                   | `boolean`                            | `true`                   | Inline completion: append the top **prefix** match's remainder after the caret, left selected. `false` = list-only. Drives `aria-autocomplete` `both`/`list`.                                                                                                                                                                                                                                                                                  |
+| `openOnFocus` (`mlvAutocompleteOpenOnFocus`)                         | `boolean`                            | `true`                   | Open suggestions on focus (subject to `minLength`).                                                                                                                                                                                                                                                                                                                                                                                            |
+| `disabled` (`mlvAutocompleteDisabled`)                               | `boolean`                            | `false`                  | Disables the behaviour entirely.                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `loadingText` (`mlvAutocompleteLoadingText`)                         | `string`                             | `'Loading…'`             | Text in both panel loading affordances — the top row (remote search in flight) and the bottom next-page row (localise by binding).                                                                                                                                                                                                                                                                                                             |
+| `infiniteScrollThreshold` (`mlvAutocompleteInfiniteScrollThreshold`) | `number`                             | `150`                    | Distance (px) from the end of the suggestion list at which the next `MlvDataSource` page is requested. Forwarded to the panel's paging sentinel; only a data-source `options` pages.                                                                                                                                                                                                                                                           |
+| `density` (`mlvAutocompleteDensity`)                                 | `MlvDensity \| undefined`            | `undefined`              | Density for the suggestion rows. The panel lives in a bare CDK overlay outside the page's density cascade — the resolved density (input, else the nearest ancestor `MLV_DENSITY_CONTEXT`, else global `MlvDensityService`) is stamped as a `mlv--{density}` class on the panel host via a constructor `effect` (the applied-class memo resets each open, since the overlay is recreated). Rows respond via the `mlv-list-item` density ladder. |
+| `selectedValue` (`mlvAutocompleteValue`, two-way)                    | `T \| null`                          | `null`                   | The last selected value. `[(mlvAutocompleteValue)]`.                                                                                                                                                                                                                                                                                                                                                                                           |
+
+### Outputs
+
+| Output           | Type                         | Description                                             |
+| ---------------- | ---------------------------- | ------------------------------------------------------- |
+| `optionSelected` | `output<MlvSelectOption<T>>` | Emits the full option each time a suggestion is chosen. |
+| `openedChange`   | `output<boolean>`            | Emits `true`/`false` as the popup opens / closes.       |
+
+Plus the read-only `isOpen` signal.
+
+### Behaviour / accessibility
+
+- **Input resolution:** the directive resolves the real focusable `<input>` — the host itself when it is an `<input>`, otherwise the inner `<input>` of a projected `mlv-input` (`querySelector('input')`) — and wires ARIA + listeners onto it via `Renderer2`.
+- **WAI-ARIA combobox:** `role="combobox"`, `aria-expanded`, `aria-controls` (the panel's listbox id), `aria-activedescendant` (the active option id), and `aria-autocomplete` — `both` while inline completion is on (default), `list` when opted out (`[mlvAutocompleteInline]="false"`).
+- **Inline completion (`inline`, default on):** on each user **insertion** (input event where text grew — never Backspace/Delete/cut/paste-shrink), when the caret is a plain cursor at the end of the field and the **top visible result's label is a genuine case-insensitive prefix** of the typed text, the directive inserts that suggestion's remainder after the caret and leaves it **selected** (typed prefix keeps the user's casing; remainder uses the suggestion's). Continuing to type replaces the selection (browser default); `Enter`/click commits the full value (caret to end); `Escape` strips the completion back to the typed text (then the existing close-then-clear semantics). Backspace/Delete do not re-complete until the next insertion. Non-prefix (fuzzy/substring-only) top matches are skipped silently — list-only. The completed top item (index 0) becomes the activedescendant-active row. Insertion-vs-deletion is detected via `beforeinput` `inputType` when available, else a value-length comparison (jsdom/programmatic). Remote sources: the completion is **armed** for the query and applied by the adapter-mirroring effect once items arrive and the source is no longer loading, then disarmed — so it fires once, from the current query's results, never from a stale in-flight one. The completed value is propagated through the same synthetic-`input` dispatch a commit uses, so `mlv-input` / `ngModel` / a form control observe it (the directive suppresses re-filtering that one event).
+- **Activedescendant keyboard model:** DOM focus stays in the input. ArrowDown/ArrowUp open then move the highlighted option (wrap-around); Home/End jump to first/last; Enter selects the highlighted option; Escape closes, then (already closed) clears the input. The active-index state + wrap navigation is the shared `MlvActiveDescendant` class from `@malva-ui/core/dropdown` (`new MlvActiveDescendant(() => this._results().length)`) — the identical engine `mlv-combobox` uses (both previously carried a byte-identical private `_moveActive`). The `aria-activedescendant` id comes from the shared `optionId(this._listboxId, index)` helper, matching the id the panel stamps.
+- **Selection:** committing writes the option label into the input and dispatches a synthetic `input` event (so `mlv-input` / `ngModel` stay in sync — the directive suppresses re-filtering that one event), emits `optionSelected`, sets `selectedValue`, and closes. Pointer selection needs **no aria reconciliation guard** because the panel is never seeded with a committed selection (`selectedValues` is always `[]`), so any non-empty `valueChange` is a genuine pick.
+- **Source engine (`MlvOptionsAdapter`):** every `options` shape plus the `search` fn is normalised by the shared adapter from `@malva-ui/core/dropdown` (`new MlvOptionsAdapter({ source: this.options, searchFn: this.search, debounce: signal(0), eager: signal(false) })` — `debounce` is `0` because the directive already debounces keystrokes before `_runQuery`). Its `mode()` picks the query path:
+  - **local** (`T[]` / `Observable<T[]>`) — `_runQuery` resolves + filters `adapter.items()` synchronously with `matcher`, exactly as before, and opens the panel.
+  - **remote** (`MlvDataSource<T>` / `search` fn) — `_runQuery` first **seeds** the results from whatever `adapter.items()` already holds, opens the panel, then runs `adapter.search(query)`. A data source receives the query as `setSearch({ query, keys: [] })` (natural-field search — the directive knows option shapes, not column keys) and owns its own filtering; the directive never re-filters remote items with `matcher`.
+  - One constructor `effect` mirrors `adapter.items()` into the rendered results for **both** modes: remote items render as-is, local ones are re-filtered against the current query (with the activedescendant reset if the highlighted row no longer exists). The local arm is what repaints an already-open panel when an `Observable` source emits late — nothing else would, until the next keystroke — and it is skipped while the panel is closed, since `_runQuery` fills it on open. Because the effect only fires on an item-set **change**, it is also why the remote arm of `_runQuery` seeds: a `search` fn that memoises and returns the identical array for a repeated query would otherwise leave the panel empty after the `minLength` gate cleared the results. Binding a stable `search` function reference is still recommended (an inline arrow is a fresh reference on every change-detection run) — the adapter tolerates re-binding without cancelling an in-flight call, but a stable reference keeps the bookkeeping trivial.
+- **Debounce + stale results:** keystrokes are debounced (`debounce`); a remote source shows the panel's loading affordance (`--loading` recede + `role="status"` row) while the **previous results stay rendered and interactive** rather than blanking to an empty list, and the adapter's monotonic token discards a superseded in-flight result. Local sources never report loading.
+- **Lazy paging (data source only):** `hasMore`, `loadingMore` and `infiniteScrollThreshold` are pushed into the panel, whose scroll sentinel emits `loadMore`; the directive forwards that to `adapter.loadMore()`, which appends the next page slice (and is a no-op until the requested page has landed, so a repeatedly firing sentinel cannot skip a page).
+- **Result normalization:** array, Promise, and Observable search results are
+  normalized by the pure `toOptionsResult()` helper from
+  `@malva-ui/core/dropdown` (it started out directive-private and moved so every
+  option control shares one async boundary) — the adapter now owns that call, so
+  the directive no longer imports it and stays focused on interaction state.
+- **Dismissal:** backdrop-less overlay; a `mousedown` on the panel is `preventDefault`ed so option clicks don't blur the input, and `outsidePointerEvents` closes on genuine outside clicks (the host is treated as inside).
+
+### i18n
+
+The directive is intentionally **not** wired to `@malva-ui/i18n` — a headless behaviour applicable to arbitrary inputs should not force a component i18n token/provider. User-facing strings are plain inputs (`loadingText`; the no-results copy is projected by the consumer if desired). Localise by binding translated strings.
+
+## Usage
+
+```html
+<!-- Static options on a plain mlv-input -->
+<mlv-input label="Fruit" [mlvAutocomplete]="fruits" (optionSelected)="pick($event)" />
+
+<!-- Async search (min length 2) with loading + highlighting -->
+<mlv-input label="User" [mlvAutocompleteSearch]="searchUsers" [mlvAutocompleteMinLength]="2" [mlvAutocompleteToOption]="userToOption" />
+
+<!-- Data source: it filters (setSearch) and pages itself; the panel shows a
+     spinner over the previous results and appends the next page on scroll -->
+<mlv-input label="Assignee" [mlvAutocomplete]="usersDataSource" [mlvAutocompleteMinLength]="2" [mlvAutocompleteToOption]="userToOption" />
+
+<!-- Custom matcher (prefix match) -->
+<mlv-input [mlvAutocomplete]="cities" [mlvAutocompleteMatcher]="startsWith" />
+
+<!-- Opt out of inline completion (list-only, aria-autocomplete="list") -->
+<mlv-input [mlvAutocomplete]="fruits" [mlvAutocompleteInline]="false" />
+
+<!-- Native input also works -->
+<input mlvAutocomplete [mlvAutocomplete]="fruits" />
+```
+
+## Dependencies
+
+- `@angular/cdk/overlay`, `@angular/cdk/portal` — imperative suggestion overlay
+- `@angular/cdk/coercion` — `coerceBooleanProperty`
+- `@malva-ui/core/dropdown` — `MlvDropdownPanel`, `MlvOptionsAdapter`, `filterOptions`, `defaultOptionMatcher`, `defaultOptionTransform`, `resolveOptions`, `MlvActiveDescendant`, `optionId`, `MlvOptionsInput`, `MlvOptionsSearchFn`, `MlvSelectOption`, `MlvSelectOptionTransform`, `MlvOptionMatcher` (`toOptionsResult` is no longer imported here — the adapter owns it)
+- `@malva-ui/cdk/data-source` — indirect: `MlvDataSource<T>` is one arm of `MlvOptionsInput<T>`, connected and paged by the adapter
+- `@malva-ui/cdk/utils` — `mlvNextId` (stable listbox id)
+- `rxjs` — keystroke debounce (`Subject` + `debounce`/`timer`)
+
+## Testing
+
+- Nx project: **`core-autocomplete`** — `yarn nx test core-autocomplete` (Vitest).

package/docs/ai/avatar-group.md

@@ -0,0 +1,184 @@
+# Library: avatar-group
+
+## Overview
+
+The Avatar Group library (`@malva-ui/core/avatar-group`) renders a horizontal stack of overlapping `mlv-avatar` instances representing a list of members (team, collaborators, reviewers). The visible count is calculated automatically from the host width via `MlvResizeObserverService` — there is **no** `max` input. When members overflow, an avatar-styled `+N` counter is appended; hovering or focusing the counter opens a popup listing every hidden member.
+
+## Public API
+
+Exported from `@malva-ui/core/avatar-group`:
+
+| Export                 | Kind      | Description                                                            |
+| ---------------------- | --------- | ---------------------------------------------------------------------- |
+| `MlvAvatarGroup` | Component | Overlapping avatar stack — `mlv-avatar-group`                         |
+| `MlvAvatarGroupMember`    | Interface | Per-member shape: `name`, optional `src`, `initials`, `color`          |
+
+---
+
+## Components
+
+### `MlvAvatarGroup`
+
+- **Selector:** `mlv-avatar-group`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+- **Imports:** `MlvAvatar`, `MlvColorFromTextPipe` (from `@malva-ui/core/avatar`); `MlvPopup`, `MlvPopupTrigger`, `MlvPopupContent` (from `@malva-ui/core/popup`)
+
+#### Inputs
+
+| Name          | Type                     | Default    | Description                                                                              |
+| ------------- | ------------------------ | ---------- | ---------------------------------------------------------------------------------------- |
+| `members`     | `MlvAvatarGroupMember[]` | `[]`       | The full member list. Visible count is auto-calculated from container width.             |
+| `size`        | `MlvAvatarSize`          | `'m'`      | Size variant applied to all avatars (incl. overflow counter). Forwarded to `mlv-avatar`. |
+| `shape`       | `MlvAvatarShape`         | `'circle'` | Shape applied to all avatars in the group. Forwarded to `mlv-avatar`.                    |
+| `interactive` | `BooleanInput`           | `false`    | When true, exposes the host as a tabbable button with Enter/Space activation.            |
+
+> The `max` input mentioned in older docs does not exist. Constrain visible count by sizing the host (`max-width`, `width`).
+
+#### Outputs
+
+| Name            | Payload                  | Fires when                                                                                                                                                         |
+| --------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `groupClick`    | `MlvAvatarGroupMember[]` | User clicks anywhere on the host. Emits the full member array. Suppressed when `members().length === 0`.                                                           |
+| `overflowClick` | `MlvAvatarGroupMember[]` | User clicks (or activates via Enter/Space on) the `+N` counter. Emits the **hidden** member subset. Stops propagation so the host `groupClick` does not also fire. |
+
+#### Host Bindings
+
+```ts
+host: {
+  class: 'mlv-avatar-group',
+  '[class]': '"mlv-avatar-group--size-" + size()',
+  '[class.mlv-avatar-group--interactive]': 'interactive()',
+  '[attr.role]': 'interactive() ? "button" : "group"',
+  '[attr.tabindex]': 'interactive() && members().length > 0 ? 0 : null',
+  '[attr.aria-label]': '_hostAriaLabel()',
+  '(click)': '_onHostClick()',
+  '(keydown)': '_onHostKeydown($event)',
+}
+```
+
+`_hostAriaLabel()` produces:
+
+- `'No members'` when `members().length === 0`
+- `'N member'` / `'N members'` when no overflow
+- `'N members, V shown'` when overflowing (`V` = visible count)
+
+#### Auto-fit Algorithm
+
+`_maxFit` computed signal returns the maximum **total** avatars (visible + overflow) that fit:
+
+- Returns `Infinity` until the first `MlvResizeObserverService` measurement (so the initial render shows everything before width is known).
+- Otherwise: `Math.max(1, Math.floor((width - avatarPx) / (avatarPx - overlapPx)) + 1)`.
+- When `members.length > _maxFit`, reserves 1 slot for the `+N` counter (`_visibleMembers().length === Math.max(1, maxFit - 1)`).
+
+Avatar pixel sizes (matches `mlv-avatar` SCSS tokens):
+
+| Size  | Avatar px | Overlap px |
+| ----- | --------: | ---------: |
+| `xs`  |        24 |          4 |
+| `s`   |        32 |          6 |
+| `m`   |        40 |          8 |
+| `l`   |        56 |         10 |
+| `xl`  |        80 |         12 |
+| `xxl` |        96 |         14 |
+
+#### Computed (protected)
+
+| Name              | Returns                                                                                                 |
+| ----------------- | ------------------------------------------------------------------------------------------------------- |
+| `_visibleMembers` | `MlvAvatarGroupMember[]` — `members.slice(0, max(1, maxFit - 1))` when overflowing, else the full list. |
+| `_hiddenMembers`  | `MlvAvatarGroupMember[]` — `members.slice(_visibleMembers.length)`.                                     |
+| `_overflowCount`  | `number` — `_hiddenMembers.length`.                                                                     |
+| `_hasOverflow`    | `boolean` — `_overflowCount > 0`.                                                                       |
+| `_overflowLabel`  | `string` — `'+' + _overflowCount` (e.g. `'+5'`).                                                        |
+
+---
+
+## Interfaces
+
+### `MlvAvatarGroupMember`
+
+```ts
+interface MlvAvatarGroupMember {
+  /** Full display name — used for initials derivation, popup label, and aria-label. */
+  name: string;
+  /** Optional image URL. Falls back to initials or color on error. */
+  src?: string | null;
+  /** Explicit initials string; overrides name-derived initials. */
+  initials?: string;
+  /** CSS color for the avatar background. Defaults to a deterministic color from name. */
+  color?: string;
+}
+```
+
+---
+
+## CSS Custom Properties
+
+Declared in `avatar-group.scss`:
+
+| Variable              | Default                              | Purpose                                                               |
+| --------------------- | ------------------------------------ | --------------------------------------------------------------------- |
+| `--mlv-ag-overlap`    | `-0.5rem` (size `m`); see size table | Negative `margin-left` applied to stacked items (per-size override).  |
+| `--mlv-ag-ring-width` | `0.125rem`                           | Outline width of each avatar's ring (used to separate stacked tiles). |
+| `--mlv-ag-ring-color` | `var(--mlv-background-base)`         | Outline color of the ring.                                            |
+
+Per-size `--mlv-ag-overlap` defaults applied via `&--size-{xs,s,m,l,xl,xxl}` modifiers:
+
+| Modifier     | Overlap     |
+| ------------ | ----------- |
+| `--size-xs`  | `-0.25rem`  |
+| `--size-s`   | `-0.375rem` |
+| `--size-m`   | `-0.5rem`   |
+| `--size-l`   | `-0.625rem` |
+| `--size-xl`  | `-0.75rem`  |
+| `--size-xxl` | `-0.875rem` |
+
+---
+
+## CSS Classes (BEM)
+
+| Class                                       | Purpose                                                                       |
+| ------------------------------------------- | ----------------------------------------------------------------------------- |
+| `.mlv-avatar-group`                         | Block — flex container that fills the parent.                                 |
+| `.mlv-avatar-group--size-{xs,s,m,l,xl,xxl}` | Size modifier (per-size overlap override).                                    |
+| `.mlv-avatar-group--interactive`            | Modifier — applies `cursor: pointer` to the host.                             |
+| `.mlv-avatar-group__list`                   | Element — flex row holding visible avatars.                                   |
+| `.mlv-avatar-group__item`                   | Element — wraps each visible avatar; carries z-index stacking + ring outline. |
+| `.mlv-avatar-group__overflow`               | Element — wraps the `+N` overflow counter (interactive trigger).              |
+| `.mlv-avatar-group__overflow-avatar`        | Element — the avatar visual for the overflow counter.                         |
+| `.mlv-avatar-group__popup-list`             | Element — popup body listing hidden members.                                  |
+| `.mlv-avatar-group__popup-row`              | Element — row inside the popup (avatar + name).                               |
+| `.mlv-avatar-group__popup-name`             | Element — name label inside a popup row.                                      |
+
+---
+
+## Dependencies
+
+### Internal package dependencies
+
+- `@malva-ui/core/avatar` — `MlvAvatar`, `MlvColorFromTextPipe`, `MlvAvatarSize`, `MlvAvatarShape`
+- `@malva-ui/core/popup` — `MlvPopup`, `MlvPopupTrigger`, `MlvPopupContent`
+- `@malva-ui/cdk` — `MlvResizeObserverService`
+
+### Angular peers
+
+- `@angular/cdk` (`coerceBooleanProperty`, `BooleanInput`)
+- `@angular/core` (signals, `takeUntilDestroyed`)
+
+---
+
+## Accessibility
+
+- The passive host carries `role="group"`; interactive groups use `role="button"`, a conditional tab stop, and Enter/Space activation.
+- Overflow counter is keyboard-activatable: `Enter` and `Space` both trigger `overflowClick`.
+- Stop-propagation on the overflow counter prevents host `groupClick` from also firing.
+- The overflow counter is the `mlvPopupTrigger` for the members popover. It sets `[ariaHasPopup]="null"` because the popover is a purely **informational** member list (`role="list"`) — not a menu/listbox/dialog — so no `aria-haspopup` type is advertised; the directive's `aria-expanded` still communicates open/closed state. The wrapping `mlv-popup` stays roleless; the `role="list"` lives on the projected content.
+
+---
+
+## Testing
+
+*(internal)*. Member-count,
+overflow, and list labels resolve through `MLV_AVATAR_GROUP_I18N`; specs provide
+`provideMlvI18nTesting()`.

package/docs/ai/avatar.md

@@ -0,0 +1,150 @@
+# Library: avatar
+
+## Overview
+
+The Avatar library (`@malva-ui/core/avatar`) provides a versatile component for representing users or entities. Supports three content modes: image (with shimmer skeleton + fade-in), initials (explicit or derived from a name), and arbitrary projected content (icons, etc.). Includes a `MlvColorFromTextPipe` for deriving deterministic background colors from name strings.
+
+## Public API
+
+Exported from `@malva-ui/core/avatar`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvAvatar` | Component | User/entity avatar — `mlv-avatar` |
+| `MlvAvatarSize` | Type | `'xs' \| 's' \| 'm' \| 'l' \| 'xl' \| 'xxl'` |
+| `MlvAvatarShape` | Type | `'circle' \| 'square'` |
+| `deriveInitials` | Function | Derives up-to-2-character initials from a name string |
+| `MlvColorFromTextPipe` | Pipe | `mlvColorFromText` — deterministic HSL color from a string |
+
+---
+
+## Components
+
+### `MlvAvatar`
+
+- **Selector:** `mlv-avatar`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+
+#### Content Priority
+
+1. `src` image (with skeleton + fade-in; falls back to initials on error)
+2. `initials` / `name` derived initials
+3. Projected `ng-content` (icons, custom elements)
+
+#### Inputs
+
+| Name       | Type             | Default    | Description                                                          |
+| ---------- | ---------------- | ---------- | -------------------------------------------------------------------- |
+| `size`     | `MlvAvatarSize`  | `'m'`      | Size variant (maps to fixed width/height/font-size)                  |
+| `shape`    | `MlvAvatarShape` | `'circle'` | Shape — `circle` (50% radius) or `square` (8px radius)               |
+| `src`      | `string \| null` | `null`     | Image URL; shows shimmer skeleton while loading; falls back on error |
+| `name`     | `string`         | `''`       | Display name; first letter of each word (max 2) used as initials     |
+| `initials` | `string`         | `''`       | Explicit initials; overrides `name`-derived initials                 |
+| `color`    | `string`         | `''`       | CSS color for background; defaults to `var(--mlv-text-secondary)`    |
+| `label`    | `string`         | `''`       | Optional text label displayed below the avatar visual                |
+
+#### Host Bindings
+
+```ts
+host: {
+  class: 'mlv-avatar',
+  '[class]': '"mlv-avatar--" + size()',
+  '[class.mlv-avatar--circle]': 'shape() === "circle"',
+  '[class.mlv-avatar--square]': 'shape() === "square"',
+  // Present the avatar as one labelled image to assistive tech when it names
+  // an entity; omit the role when there is no name so no nameless role=img.
+  '[attr.role]': '_accessibleName() ? "img" : null',
+  '[attr.aria-label]': '_accessibleName()',
+}
+```
+
+> **Accessible name (`_accessibleName`)** — computed as `name() || label() || null`.
+> When present, the host gains `role="img"` with that name so an `aria-label`
+> is valid on the otherwise role-less host (this is what mlv-avatar-group
+> relies on — it passes `[name]` and no longer sets a redundant `aria-label`).
+> When absent (icon-only / initials-only avatar), the role is omitted so axe
+> does not flag a nameless `role="img"`.
+
+#### Size Reference
+
+| Size  | Width/Height  | Font size |
+| ----- | ------------- | --------- |
+| `xs`  | 1.5rem (24px) | 0.625rem  |
+| `s`   | 2rem (32px)   | 0.75rem   |
+| `m`   | 2.5rem (40px) | 0.875rem  |
+| `l`   | 3.5rem (56px) | 1rem      |
+| `xl`  | 5rem (80px)   | 1.25rem   |
+| `xxl` | 6rem (96px)   | 1.5rem    |
+
+#### Template Structure
+
+```
+.mlv-avatar
+  .mlv-avatar__visual        ← colored container
+    .mlv-avatar__skeleton    ← shimmer (while image loads)
+    img.mlv-avatar__image    ← image (fades in on load)
+    span.mlv-avatar__initials ← initials text
+    span.mlv-avatar__content  ← ng-content slot
+  .mlv-avatar__label         ← optional label below
+    span.mlv-avatar__label-word (× n words, each wrapped in MlvFade)
+```
+
+---
+
+## Pipes
+
+### `MlvColorFromTextPipe`
+
+**Pipe name:** `mlvColorFromText`
+
+Converts a string to a deterministic `hsl(...)` CSS color by hashing the characters into a hue value (0–360). Saturation ~60% and lightness ~80% are fixed for pleasant, accessible results.
+
+```html
+<mlv-avatar [name]="user.name" [color]="user.name | mlvColorFromText" />
+```
+
+---
+
+## Utilities
+
+### `deriveInitials(name: string): string`
+
+Takes the first character of each space-separated word (up to 2 characters), uppercased. Returns `''` for empty/blank strings.
+
+```ts
+deriveInitials('John Doe'); // 'JD'
+deriveInitials('Alice'); // 'A'
+deriveInitials('John Michael Doe'); // 'JD'
+deriveInitials(''); // ''
+```
+
+---
+
+## Usage Examples
+
+```html
+<!-- Auto initials from name + deterministic color -->
+<mlv-avatar name="John Doe" [color]="'John Doe' | mlvColorFromText" />
+
+<!-- Image with fallback to initials on error -->
+<mlv-avatar src="https://example.com/avatar.jpg" name="John Doe" label="John Doe" />
+
+<!-- Explicit initials + custom color -->
+<mlv-avatar initials="JD" color="hsl(217, 60%, 75%)" size="l" label="John Doe" />
+
+<!-- Icon content (no name/initials) -->
+<mlv-avatar size="m" color="hsl(253, 60%, 80%)" label="Bot">
+  <svg lucideBot [size]="20" />
+</mlv-avatar>
+
+<!-- Square shape -->
+<mlv-avatar name="Alice" shape="square" size="xl" [color]="'Alice' | mlvColorFromText" />
+```
+
+---
+
+## Dependencies
+
+- `@angular/core`
+- `@malva-ui/cdk` — `MlvFade` (used for label word overflow)