@malva-ui/core 0.1.12

package/docs/ai/tokenizer.md

@@ -0,0 +1,236 @@
+# Library: tokenizer
+
+## Overview
+
+The Tokenizer library (`@malva-ui/core/tokenizer`) provides a tag/token input component for managing a collection of labelled items. Users type text, press Enter (or a configurable split key) to create tokens, and can remove them. Supports overflow limiting, custom token templates, duplicate control, and all three Angular forms modes.
+
+## Public API
+
+Exported from `@malva-ui/core/tokenizer`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvTokenizer<T>` | Component | Token input — `mlv-tokenizer` |
+| `MlvToken` | Component | Individual token — `mlv-token` |
+| `MlvTokenTemplate` | Directive | Custom token template — `[mlvTokenTemplate]` |
+| `MlvTokenTemplateContext<T>` | Interface | `{ $implicit: MlvSelectOption<T> }` |
+| `MlvSelectOption<T>` | Interface | `{ label: string; value: T }` |
+
+---
+
+## Components
+
+### `MlvTokenizer<T>`
+
+- **Selector:** `mlv-tokenizer`
+- **Change Detection:** `OnPush`
+- **Extends:** `MlvSignalFormControlBase<MlvSelectOption<T>[]>`
+
+#### Model (two-way binding)
+
+| Name     | Type                   | Default |
+| -------- | ---------------------- | ------- |
+| `tokens` | `MlvSelectOption<T>[]` | `[]`    |
+
+#### Inputs (own)
+
+| Name              | Type                                        | Default                         | Description                                       |
+| ----------------- | ------------------------------------------- | ------------------------------- | ------------------------------------------------- |
+| `placeholder`     | `string`                                    | `''`                            | Input placeholder                                 |
+| `showOverflow`    | `boolean`                                   | `true`                          | Show `+N more` overflow indicator                 |
+| `maxVisible`      | `number \| null`                            | `null`                          | Max tokens shown (`null` = unlimited)             |
+| `allowDuplicates` | `boolean`                                   | `false`                         | Allow identical token values                      |
+| `createToken`     | `(v: string) => MlvSelectOption<T>`         | `v => ({ label: v, value: v })` | Transform input string → token                    |
+| `splitFn`         | `((v: string) => string[] \| null) \| null` | `null`                          | Split input into multiple tokens (e.g., by comma) |
+
+#### Inputs (from MlvSignalFormControlBase)
+
+`disabled`, `label`, `hint`, `message`, `state`, `id`
+
+#### Computed Signals
+
+| Signal          | Description                              |
+| --------------- | ---------------------------------------- |
+| `visibleTokens` | Subset of tokens limited by `maxVisible` |
+| `overflowCount` | Number of hidden tokens                  |
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-tokenizer',
+  '[class.mlv-tokenizer--disabled]': 'disabled()',
+  '[class.mlv-tokenizer--focused]': 'focused()',
+}
+```
+
+#### Content Children
+
+- `tokenTemplate: contentChild(MlvTokenTemplate)` — optional custom token rendering
+
+#### Key Methods
+
+| Method                    | Description                                                                                                                                            |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `focusInput()`            | Focus the text input (also disarms any Backspace chip-selection)                                                                                       |
+| `onInputEnter(event)`     | Disarm, then parse input with `createToken` + optional `splitFn`; add tokens (deduplication); clear input                                              |
+| `onInputBackspace(event)` | Empty-input Backspace: arm the last chip (first press), then remove-and-re-arm from the end (subsequent presses). See _Backspace chip-selection flow_. |
+| `onInputDelete(event)`    | Delete parity: removes the armed chip and re-arms the new last one; no-op when nothing armed                                                           |
+| `removeToken(token)`      | Remove a specific token                                                                                                                                |
+| `onTokenKeydown(event)`   | Delegate to `FocusKeyManager` for token-to-token navigation                                                                                            |
+
+#### Backspace chip-selection flow
+
+Pressing **Backspace** in the text input **while the input is empty** does not immediately delete. Instead it follows a Gmail-style two-stage model, tracked by the `_armed` signal (visual-only selection — DOM focus stays in the input):
+
+1. **First Backspace** → _arms_ the **last** token. The armed token renders its inner `mlv-chip` with `tone="primary"` and gets a `.mlv-token--armed` ring; **no deletion** occurs.
+2. **Second (and each further) Backspace** → removes the armed (last) token and arms the new last one, walking deletion from the end **one token per press**.
+3. Removing the final token leaves the input focused and **disarmed**.
+
+**Delete** (`onInputDelete`) mirrors the second-Backspace behavior but only acts on an already-armed token.
+
+**Disarm triggers** (any clears the selection): typing a character (`input` event), caret movement (`ArrowLeft`/`ArrowRight`/`Home`/`End`), `Enter`, blur, pointer interaction (`focusInput`), an external forms value write, and any **external** `[(tokens)]` change. Internal arm-driven deletions are distinguished via `_internalTokensRef`, so re-arming survives its own mutation.
+
+This flow is **independent of** the token roving-focus model: `ArrowLeft`/`ArrowRight` on a DOM-focused token still navigate via `FocusKeyManager`, and **Backspace/Delete on a DOM-focused token** still removes that token directly (`MlvToken._onKeyRemove`).
+
+**Screen-reader communication.** The armed token is announced through a **visually-hidden `aria-live="polite"` / `role="status"` region** (`.mlv-tokenizer__sr`, bound to the `_srMessage` signal) inside the tokens container. This live-region approach was chosen over `aria-activedescendant` deliberately: the token structure is a `role="list"` of `role="listitem"` (not a `listbox`/`option` combobox), so per `.claude/rules/accessibility.md` `aria-activedescendant` is not the appropriate pattern, and arming is a visual highlight while real focus never leaves the input. The region announces the armed token's label and clears on disarm.
+
+#### Template Summary
+
+Form control wrapper → label → `div[role="list"]` wrapping each token as `mlv-token[role="listitem"]` (with optional custom template via `tokenTemplate`) → overflow indicator (`+N more`) → text input → a visually-hidden `span.mlv-tokenizer__sr[aria-live="polite"][role="status"]` (Backspace-selection announcements). The `mlv-input` is a **sibling of** the list, never inside `role="list"`. `MlvTokenizer` wires a `FocusKeyManager` over the rendered tokens (Arrow keys navigate; roving tabindex keeps a single token in the tab order).
+
+The `role="list"` container's `aria-label` falls back to the localized `MLV_TOKENIZER_I18N` **`selectedItems`** string (`"Selected items"` in the `en` pack) when the consumer provides no `label` input — it is no longer a hard-coded English literal. The `_i18n` signal (`inject(MLV_TOKENIZER_I18N)`) supplies both `addToken` (input aria-label) and `selectedItems` (list aria-label).
+
+---
+
+### `MlvToken`
+
+**Selector:** `mlv-token` | **Change Detection:** `OnPush` | **Encapsulation:** `None`
+
+Driven by the parent `MlvTokenizer`'s `FocusKeyManager` (roving tabindex).
+The token host is the single keyboard focus target; the inner `mlv-chip`
+provides the visual chrome and mouse close affordance but is kept out of the tab
+order (`[chipTabIndex]="-1"`).
+
+#### Inputs
+
+| Name        | Type                       | Default | Description                                                                                                                                                                                              |
+| ----------- | -------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`     | `MlvSelectOption<unknown>` | —       | The option this token represents                                                                                                                                                                         |
+| `removable` | `boolean`                  | `true`  | Whether the token shows a remove affordance                                                                                                                                                              |
+| `disabled`  | `boolean`                  | `false` | Disables the token (renamed from `isDisabled`)                                                                                                                                                           |
+| `armed`     | `boolean`                  | `false` | Visual-only "selected" state — renders the inner chip with `tone="primary"` and a `.mlv-token--armed` ring. Driven by the tokenizer's empty-input Backspace flow; does not change tabindex/role/removal. |
+
+#### Outputs
+
+| Name      | Type                               |
+| --------- | ---------------------------------- |
+| `removed` | `output<MlvSelectOption<unknown>>` |
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-token',
+  'role': 'listitem',
+  '[attr.aria-label]': '_ariaLabel()',            // the option label
+  '[class.mlv-token--disabled]': 'disabled()',
+  '[class.mlv-token--armed]': 'armed()',              // visual Backspace-selection
+  '[attr.tabindex]': 'disabled() ? -1 : tabIndex()',  // roving tabindex signal
+  '(keydown.backspace)': '_onKeyRemove($event)',
+  '(keydown.delete)': '_onKeyRemove($event)',
+}
+```
+
+- `role="listitem"` (the previous `role="option"` + unconditional `aria-selected="true"` were invalid outside a listbox and have been removed).
+- Keyboard removal: **Backspace/Delete** on a focused token emits `removed`. Mouse removal is the chip's close (×) button.
+- **`.mlv-token:focus-visible`** ring uses `--mlv-border-focus`.
+
+#### Template (inline)
+
+```html
+<mlv-chip mlvDensity="compact" [chipTabIndex]="-1" [tone]="armed() ? 'primary' : 'default'" [closable]="removable() && !disabled()" [closeAriaLabel]="_closeAriaLabel()" [muted]="disabled()" (chipClose)="onRemove()">
+  <ng-content />
+</mlv-chip>
+```
+
+`_closeAriaLabel()` composes a descriptive accessible name for the inner chip's
+close button as `"<Remove>: <label>"` (e.g. `"Remove: Angular"`), reusing the
+localized "Remove" verb from `MLV_CHIP_I18N` so screen-reader users know which
+token the close button removes. Falls back to the bare verb when the token has
+no label.
+
+---
+
+## Directives
+
+### `MlvTokenTemplate`
+
+**Selector:** `[mlvTokenTemplate]`
+
+Provides `templateRef: TemplateRef<MlvTokenTemplateContext<T>>`. Use as `contentChild(MlvTokenTemplate)` in the tokenizer.
+
+---
+
+## Interfaces
+
+```ts
+export interface MlvSelectOption<T = unknown> {
+  label: string;
+  value: T;
+}
+
+export interface MlvTokenTemplateContext<T = unknown> {
+  $implicit: MlvSelectOption<T>;
+}
+```
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic tokenizer -->
+<mlv-tokenizer [(tokens)]="tags" placeholder="Add tags..." />
+
+<!-- With max visible + overflow -->
+<mlv-tokenizer [(tokens)]="tags" [maxVisible]="3" [showOverflow]="true" />
+
+<!-- Comma-split input -->
+<mlv-tokenizer [(tokens)]="emails" [splitFn]="splitByComma" placeholder="email1, email2, ..." />
+
+<!-- Custom token template -->
+<mlv-tokenizer [(tokens)]="users">
+  <ng-template mlvTokenTemplate let-option>
+    <strong>{{ option.label }}</strong>
+  </ng-template>
+</mlv-tokenizer>
+
+<!-- Reactive forms -->
+<mlv-tokenizer [formControl]="tagsCtrl" placeholder="Add tags" />
+```
+
+```ts
+splitByComma = (v: string) =>
+  v
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+```
+
+---
+
+## Dependencies
+
+- `@angular/forms/signals` — signal-control contract; reactive/ngModel compatibility is built into Angular
+- `@angular/cdk/a11y` — `FocusKeyManager`, `FocusableOption`
+- `@malva-ui/core/form-utils` — `MlvSignalFormControlBase`, `MlvFormControlWrapper`, `MlvLabel`, `MlvHint`, `MlvMessage`
+
+---
+
+## Field surface (2026-08)
+
+- Inherited `required` renders the `mlv-label` marker and is forwarded to the inner `mlv-input`.
+- Inherited `ariaLabel` overrides the i18n `addToken` label on the inner input when supplied.
+- Inherited `description` renders `<mlv-description>` below the control; the inner bare input receives `[ariaDescribedBy]="_describedBy()"`.
+- The non-reactive public `messageId` string field is gone; `<mlv-message>` carries the base's `_messageId()`.

package/docs/ai/toolbar.md

@@ -0,0 +1,155 @@
+# Library: toolbar
+
+## Overview
+
+The Toolbar library (`@malva-ui/core/toolbar`) provides simple, composable components for building horizontal toolbars and action bars. Minimal layout-focused components for application headers and control panels.
+
+## Public API
+
+Exported from `@malva-ui/core/toolbar`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvToolbar` | Component | Horizontal container — `mlv-toolbar` |
+| `MlvToolbarSpacer` | Component | Flex spacer — `mlv-toolbar-spacer` |
+| `MlvToolbarRoving<V>` | Directive | **Opt-in** roving-focus container — `mlv-toolbar[mlvToolbarRoving]` |
+| `MlvToolbarWidget<V>` | Directive | **Opt-in** toolbar widget marker — `[mlvToolbarWidget]` |
+
+---
+
+## Keyboard roving focus (opt-in · `@angular/aria` · Task 2.4)
+
+> **Behavioral note (added capability):** by default `mlv-toolbar` is a pure layout container — every child is its own Tab stop, exactly as before. Adding `mlvToolbarRoving` to the toolbar and `mlvToolbarWidget` to each interactive child turns the toolbar into a **single Tab stop** whose widgets are traversed with the arrow keys / `Home` / `End`, following the WAI-ARIA toolbar pattern. This is a **new capability**, applied only when opted in — existing toolbars are unaffected.
+
+**Why opt-in, not automatic:** `mlv-toolbar` projects arbitrary content, so aria widgets cannot be auto-attached to consumer children. Empirically, applying aria `ngToolbar` to a _widget-less_ container renders `role="toolbar"` + `tabindex="0"` + `aria-disabled="true"` on it (aria treats "no focusable items" as a disabled list) — a regression for every existing plain-button toolbar. The two opt-in markers avoid both problems.
+
+### `MlvToolbarRoving` — `mlv-toolbar[mlvToolbarRoving]`
+
+Host-applies `@angular/aria`'s `Toolbar` (`ngToolbar`). Re-exposes its knobs so they can be pinned where the element is used (a host directive's inputs cannot be set from the wrapper's own `host` metadata):
+
+| Input                   | Default        | Description                                                                                          |
+| ----------------------- | -------------- | ---------------------------------------------------------------------------------------------------- |
+| `orientation`           | `'horizontal'` | Arrow-key navigation axis.                                                                           |
+| `wrap`                  | `true`         | Whether arrow navigation wraps at the ends.                                                          |
+| `softDisabled`          | `true`         | Keep disabled widgets focusable-but-inert (`false` skips them during navigation).                    |
+| `disabled`              | `false`        | Disable the whole toolbar.                                                                           |
+| `value` / `valueChange` | `[]`           | Selection model (array of selected widget values) for toggle/radio-style toolbars. Two-way bindable. |
+
+### `MlvToolbarWidget` — `[mlvToolbarWidget]`
+
+Host-applies `@angular/aria`'s `ToolbarWidget` (`ngToolbarWidget`) to each interactive child.
+
+| Input      | Alias              | Default | Description                                                                                                                                                                        |
+| ---------- | ------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`    | `mlvToolbarWidget` | `''`    | Widget identity, supplied through the selector attribute: `<button mlvToolbarWidget>` → `''` (action button), `<button mlvToolbarWidget="left">` → identity for a selection group. |
+| `disabled` | `disabled`         | `false` | Disables this widget.                                                                                                                                                              |
+
+**Deviation from the migration plan (`mlvNextId` synthesis):** aria `ngToolbarWidget.value` is a _required_ input, and in aria 22.0.5 a wrapper directive **cannot** feed its own host directive's input from the wrapper's `host` metadata (verified — raises `NG0950`). The value therefore can't be synthesized internally; it is exposed through the selector alias instead, which stays ergonomic (omitted → `''`) for value-less action buttons while letting selection groups supply distinct identities inline.
+
+```html
+<!-- Action toolbar: roving focus, no per-widget value needed -->
+<mlv-toolbar mlvToolbarRoving>
+  <button mlvButton mlvToolbarWidget>Cut</button>
+  <button mlvButton variant="outlined" mlvToolbarWidget>Copy</button>
+  <button mlvButton variant="outlined" mlvToolbarWidget>Paste</button>
+</mlv-toolbar>
+
+<!-- Selection group (toggle/radio-style) -->
+<mlv-toolbar mlvToolbarRoving [(value)]="alignment">
+  <button mlvButton mlvToolbarWidget="left">Left</button>
+  <button mlvButton mlvToolbarWidget="center">Center</button>
+  <button mlvButton mlvToolbarWidget="right">Right</button>
+</mlv-toolbar>
+```
+
+---
+
+## Components
+
+### `MlvToolbar`
+
+- **Selector:** `mlv-toolbar`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+- **Template:** Inline — `<ng-content />`
+
+#### Inputs
+
+| Name        | Type      | Default | Description                       |
+| ----------- | --------- | ------- | --------------------------------- |
+| `gap`       | `number`  | `0.25`  | Gap between items in rem          |
+| `equalSize` | `boolean` | `false` | Equal flex width for all children |
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-toolbar',
+  '[style.gap.rem]': 'gap()',
+  '[class.mlv-toolbar--equal]': 'equalSize()',
+}
+```
+
+#### Styles
+
+- `.mlv-toolbar` — `display: flex; flex-direction: row; align-items: center`
+- `.mlv-toolbar--equal > *:not(.mlv-toolbar-spacer)` — `flex: 1 1 0`
+
+---
+
+### `MlvToolbarSpacer`
+
+- **Selector:** `mlv-toolbar-spacer`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+- **Template:** Empty
+- **Styles (inline):** `.mlv-toolbar-spacer { flex: 1 1 auto; }`
+
+#### Host Bindings
+
+```ts
+host: { 'class': 'mlv-toolbar-spacer' }
+```
+
+Grows to fill all available horizontal space, pushing adjacent items to the right.
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic toolbar -->
+<mlv-toolbar>
+  <button mlvButton>Home</button>
+  <button mlvButton>About</button>
+</mlv-toolbar>
+
+<!-- With spacer (items pushed to edges) -->
+<mlv-toolbar>
+  <button mlvButton>Menu</button>
+  <mlv-toolbar-spacer />
+  <button mlvButton>Profile</button>
+  <button mlvButton>Logout</button>
+</mlv-toolbar>
+
+<!-- Custom gap -->
+<mlv-toolbar [gap]="0.5">
+  <button mlvButton>Save</button>
+  <button mlvButton>Cancel</button>
+</mlv-toolbar>
+
+<!-- Equal-width items -->
+<mlv-toolbar [equalSize]="true">
+  <button mlvButton>Option 1</button>
+  <button mlvButton>Option 2</button>
+  <button mlvButton>Option 3</button>
+</mlv-toolbar>
+```
+
+---
+
+## Dependencies
+
+- `@angular/core`
+- `@angular/cdk/coercion` — `coerceBooleanProperty` for `equalSize`
+- `@angular/aria/toolbar` — `Toolbar` / `ToolbarWidget` (`ngToolbar` / `ngToolbarWidget`) behind the opt-in `mlvToolbarRoving` / `mlvToolbarWidget` directives

package/docs/ai/tooltip.md

@@ -0,0 +1,154 @@
+# Library: tooltip
+
+## Overview
+
+The Tooltip library (`@malva-ui/core/tooltip`) provides a lightweight, accessible tooltip that appears on hover and focus. It uses Angular CDK overlay positioning and supports configurable placement, color variants, delay, and an optional directional arrow.
+
+Tooltip is self-contained — it creates a CDK overlay and a `MlvTooltipPanel` dynamically via `MlvTooltip`. It intentionally does not reuse `MlvPopupService` (which is click/template-based) since tooltip trigger behavior (hover + focus + delay) diverges significantly from popup click semantics.
+
+## Public API
+
+Exported from `@malva-ui/core/tooltip`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvTooltip` | Directive | `[mlvTooltip]` — main public API; attach to any element |
+| `MlvTooltipPanel` | Component | `mlv-tooltip-panel` — internal floating panel (not for direct use) |
+| `MlvTooltipTone` | Type | `MlvTone \| 'dark' \| 'light' \| 'primary'` |
+| `MlvTooltipPlacement` | Type | `'top' \| 'bottom' \| 'left' \| 'right'` |
+
+---
+
+## Directives
+
+### `MlvTooltip`
+
+**Selector:** `[mlvTooltip]`
+
+The primary consumer API. Attach to any element — button, icon, input, etc.
+
+#### Inputs
+
+| Name               | Type                  | Default  | Description                                                     |
+| ------------------ | --------------------- | -------- | --------------------------------------------------------------- |
+| `mlvTooltip`       | `string` (required)   | —        | Tooltip text content                                            |
+| `tooltipPlacement` | `MlvTooltipPlacement` | `'top'`  | Preferred placement; CDK flips to opposite if no viewport space |
+| `tooltipTone`      | `MlvTooltipTone`      | `'dark'` | Tone variant of the tooltip panel                               |
+| `tooltipDelay`     | `number`              | `300`    | Milliseconds before tooltip appears after hover/focus           |
+| `tooltipDisabled`  | `BooleanInput`        | `false`  | Suppresses the tooltip entirely                                 |
+| `tooltipArrow`     | `BooleanInput`        | `true`   | Shows/hides the directional arrow                               |
+
+#### Behavior
+
+- **Show:** `mouseenter` or `focusin` → schedule after `tooltipDelay` ms
+- **Hide:** `focusout` or `Escape` key → immediate. `mouseleave` → hides after a ~150 ms grace period so the pointer can travel onto the tooltip panel.
+- **Hoverable (WCAG 1.4.13):** while visible, `mouseenter` on the tooltip panel cancels the pending hide and `mouseleave` on the panel re-schedules it, so the tooltip stays open while the pointer is over it. Panel hover listeners are attached with `Renderer2.listen` in `_show()` and torn down in `_hide()`.
+- **Accessibility:** sets `aria-describedby` on the host pointing to the tooltip panel `id` while visible; removes it on hide
+- **CDK overlay:** `flexibleConnectedTo` strategy with `reposition` scroll strategy
+
+---
+
+## Components
+
+### `MlvTooltipPanel` (internal)
+
+**Selector:** `mlv-tooltip-panel`
+**Change Detection:** `OnPush` | **Encapsulation:** `None`
+
+Created programmatically by `MlvTooltip`. Not intended for direct consumer use.
+
+#### Inputs
+
+| Name        | Type                  | Description                        |
+| ----------- | --------------------- | ---------------------------------- |
+| `content`   | `string` (required)   | Tooltip text                       |
+| `tone`      | `MlvTooltipTone`      | Tone variant (default `'dark'`)    |
+| `showArrow` | `boolean`             | Whether the arrow is visible       |
+| `placement` | `MlvTooltipPlacement` | Drives arrow direction CSS class   |
+| `tooltipId` | `string` (required)   | Unique `id` for `aria-describedby` |
+
+#### Accessibility
+
+- Host `div` has `role="tooltip"` and a unique `id`
+- Arrow `span` has `aria-hidden="true"`
+- Tooltip is not focusable (no interactive elements)
+
+---
+
+## CSS Classes
+
+| Class                            | Description                                             |
+| -------------------------------- | ------------------------------------------------------- |
+| `.mlv-tooltip`                   | Root block — background, color, radius, padding, shadow |
+| `.mlv-tooltip__content`          | Text content wrapper                                    |
+| `.mlv-tooltip__arrow`            | CSS border-trick arrow element                          |
+| `.mlv-tooltip--tone-{name}`      | Tone variant modifier                                   |
+| `.mlv-tooltip--no-arrow`         | Hides the arrow element                                 |
+| `.mlv-tooltip--placement-{side}` | Drives arrow position (top/bottom/left/right)           |
+
+## CSS Custom Properties
+
+| Property              | Default                          | Description                                     |
+| --------------------- | -------------------------------- | ----------------------------------------------- |
+| `--mlv-tt-bg`         | `var(--mlv-palette-neutral-900)` | Tooltip background (overridden by tone variant) |
+| `--mlv-tt-color`      | `var(--mlv-text-inverse)`        | Tooltip text color (overridden by tone variant) |
+| `--mlv-tt-arrow-size` | `0.375rem`                       | Arrow triangle size                             |
+
+---
+
+## Tone Variants
+
+| `tooltipTone`    | Background                   | Text                             |
+| ---------------- | ---------------------------- | -------------------------------- |
+| `dark` (default) | `--mlv-palette-neutral-900`  | `--mlv-text-inverse`             |
+| `light`          | `--mlv-background-base`      | `--mlv-text-primary`             |
+| `primary`        | `--mlv-background-accent-1`  | `--mlv-text-primary-on-accent-1` |
+| `success`        | `--mlv-background-success-1` | `--mlv-text-on-success`          |
+| `warning`        | `--mlv-background-warning-1` | `--mlv-text-on-warning`          |
+| `danger`         | `--mlv-background-danger-1`  | `--mlv-text-on-danger`           |
+| `info`           | `--mlv-background-info-1`    | `--mlv-text-on-info`             |
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic -->
+<button [mlvTooltip]="'Save changes'">Save</button>
+
+<!-- Placement -->
+<button [mlvTooltip]="'Bottom tooltip'" tooltipPlacement="bottom">Open</button>
+
+<!-- Tone -->
+<button [mlvTooltip]="'Danger action'" tooltipTone="danger">Delete</button>
+
+<!-- Delay -->
+<button [mlvTooltip]="'Appears after 500ms'" [tooltipDelay]="500">Hover me</button>
+
+<!-- No arrow -->
+<button [mlvTooltip]="'No arrow'" [tooltipArrow]="false">Button</button>
+
+<!-- Disabled -->
+<button [mlvTooltip]="'Hidden'" [tooltipDisabled]="isDisabled">Button</button>
+
+<!-- Icon-only button (accessibility) -->
+<button mlvButton shape="circle" aria-label="Delete" [mlvTooltip]="'Delete item'" tooltipTone="danger">
+  <svg lucideTrash2 [size]="16" />
+</button>
+```
+
+---
+
+## Dependencies
+
+| Package                 | Version   | Role                                    |
+| ----------------------- | --------- | --------------------------------------- |
+| `@angular/core`         | `^22.0.0` | Signals, DI, directive                  |
+| `@angular/cdk/overlay`  | `^22.0.0` | CDK overlay positioning                 |
+| `@angular/cdk/portal`   | `^22.0.0` | `ComponentPortal`                       |
+| `@angular/cdk/coercion` | `^22.0.0` | `BooleanInput`, `coerceBooleanProperty` |
+| `uuid`                  | `^13.0.0` | Unique tooltip ID generation            |
+
+---
+
+## File Structure