@malva-ui/core 0.1.12

package/docs/ai/menu.md

@@ -0,0 +1,335 @@
+# Library: menu
+
+## Overview
+
+The Menu library (`@malva-ui/core/menu`) provides a dropdown action menu system with keyboard navigation, grouped items, separators, and nested submenu support. Submenus include triangle pointer tracking to prevent accidental closure when the user moves the cursor diagonally toward a submenu panel. The library also provides `mlv-menubar` — a horizontal File / Edit / View application menu bar that composes a row of `mlv-menu` dropdowns per the WAI-ARIA Menubar pattern.
+
+The menu panel is rendered inside a `mlv-popup` overlay using `[mlvPopupContent]` — no DOM manipulation is needed. `MlvMenuTrigger` uses `MlvPopupService.open()` with the popup's template, which naturally includes the `mlv-list` panel and projected `mlv-menu-item` children.
+
+## Public API
+
+Exported from `@malva-ui/core/menu`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvMenu` | Component | Menu panel — `mlv-menu` |
+| `MlvMenuItem` | Directive | Menu action item — `mlv-list-item[mlvMenuItem]` |
+| `MlvMenuSeparator` | Component | Visual separator — `mlv-menu-separator` |
+| `MlvMenuGroup` | Component | Group container — `mlv-menu-group` |
+| `MlvMenuGroupLabel` | Directive | Group label slot — `[mlvMenuGroupLabel]` |
+| `MlvMenuTrigger` | Directive | Opens a menu on click/hover — `[mlvMenuTrigger]` |
+| `MlvMenubar` | Component | Horizontal application menu bar — `mlv-menubar` |
+| `MlvMenuAccessor` | Interface | Parent menu accessor interface (via `MENU_TOKEN`) |
+| `MENU_TOKEN` | Token | `InjectionToken<MlvMenuAccessor>` |
+| `MlvMenubarItem` | Interface | Subset of `MlvMenuTrigger` a menubar coordinates (roving/open) |
+| `MlvMenubarAccessor` | Interface | Parent menubar accessor interface (via `MENUBAR_TOKEN`) |
+| `MlvMenubarMenuController` | Interface | Controller a menubar dropdown uses to cross to sibling menus |
+| `MENUBAR_TOKEN` | Token | `InjectionToken<MlvMenubarAccessor>` |
+
+---
+
+## Components
+
+### `MlvMenu`
+
+- **Selector:** `mlv-menu`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+
+#### Inputs
+
+| Name         | Type                      | Default     | Description                                                                                                                                                                                                                                                                                                                                                                                                         |
+| ------------ | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`      | `string`                  | `''`        | `aria-label` for the menu panel                                                                                                                                                                                                                                                                                                                                                                                     |
+| `mlvDensity` | `MlvDensity \| undefined` | `undefined` | Density for the panel's item rows. The panel is portaled to the CDK overlay container, outside the trigger's density cascade — forwarded to the inner `mlv-popup`, which stamps `mlv--{density}` on the detached panel; row padding responds via the `mlv-list-item` density ladder. Omitted → global `MlvDensityService`. Submenus are separate `mlv-menu` instances — set per menu when overriding a nested tree. |
+
+#### Outputs
+
+| Name     | Description                                                                                                                                                                                                                                                                                                                                                                    |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `closed` | Emits when the menu requests to be closed. **Intentionally a bare `closed` output with no `opened` model** — the menu is trigger-driven (opened imperatively via `MlvMenuTrigger`), so it is deliberately excluded from the `opened` two-way-model normalization applied to `mlv-drawer`/`mlv-popup` (the dialog's equivalent is `[(mlvDialog)]` on `ng-template[mlvDialog]`). |
+
+#### Public methods
+
+| Method                           | Description                                                                                                                                                     |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `focusFirstItem()`               | Focuses the first non-disabled item (keyboard open ArrowDown)                                                                                                   |
+| `focusLastItem()`                | Focuses the last non-disabled item (keyboard open ArrowUp)                                                                                                      |
+| `close()`                        | Closes the menu and emits `closed`                                                                                                                              |
+| `closeAll()`                     | Closes this menu and any ancestor menus                                                                                                                         |
+| `registerParentMenu(parentMenu)` | Internal API used by submenu triggers to connect a submenu to its opener                                                                                        |
+| `registerMenubarController(ctl)` | Internal API used by menubar-child triggers so the panel's top-level ArrowRight/ArrowLeft cross to sibling menubar menus (`null` for standalone menus/submenus) |
+
+#### Internal signals
+
+- `_isOpen: WritableSignal<boolean>` — managed by `MlvMenuTrigger`
+- `_popup: Signal<MlvPopup>` — accessed by `MlvMenuTrigger` for overlay management
+
+---
+
+### `MlvMenuItem`
+
+**Selector:** `mlv-list-item[mlvMenuItem]`
+
+Applied to `mlv-list-item` to give it menu-item semantics. Overrides `role="listitem"` → `role="menuitem"`, wires into the parent `FocusKeyManager`, and closes the parent menu stack on activation.
+
+Users must import both `MlvListItem` (from `@malva-ui/core/list`) and `MlvMenuItem` (from `@malva-ui/core/menu`).
+
+#### Inputs
+
+| Name       | Type           | Default | Description                                  |
+| ---------- | -------------- | ------- | -------------------------------------------- |
+| `disabled` | `BooleanInput` | `false` | Disables the item; supports attribute syntax |
+
+#### Outputs
+
+| Name        | Description                                                                                     |
+| ----------- | ----------------------------------------------------------------------------------------------- |
+| `itemClick` | Emits when the item is activated (click or Enter/Space); parent menu stack closes automatically |
+
+#### Public methods
+
+| Method       | Description                                                                                                                      |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| `focus()`    | Focuses the host element (CDK `FocusableOption`)                                                                                 |
+| `getLabel()` | Returns the item's trimmed visible text; used by the parent `FocusKeyManager` type-ahead (`withTypeAhead()`) to match keystrokes |
+
+---
+
+### `MlvMenuSeparator`
+
+**Selector:** `mlv-menu-separator`
+
+Renders a horizontal `<hr role="separator" />` between item groups.
+
+---
+
+### `MlvMenuGroup`
+
+**Selector:** `mlv-menu-group`
+
+Groups related menu items with `role="group"`. Use `[mlvMenuGroupLabel]` on a child element for an accessible label.
+
+---
+
+### `MlvMenubar`
+
+- **Selector:** `mlv-menubar`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+
+A horizontal File / Edit / View style application menu bar implementing the [WAI-ARIA Menubar pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menubar/). Wrap a row of `[mlvMenuTrigger]` elements; each opens a standard `mlv-menu` dropdown and the bar coordinates roving focus and open state across them. It discovers its top-level items via `contentChildren(MlvMenuTrigger)` and provides itself through `MENUBAR_TOKEN` so those triggers switch into menubar-child mode.
+
+> **Declare the `mlv-menu` panels as siblings of the menubar** (outside its projected content). That way the bar's `contentChildren` query only sees the top-level triggers — never the items or submenu triggers inside the (sibling, overlay-rendered) dropdown panels.
+
+#### Inputs
+
+| Name    | Type     | Default | Description                                |
+| ------- | -------- | ------- | ------------------------------------------ |
+| `label` | `string` | `''`    | `aria-label` for the `role="menubar"` host |
+
+#### Host bindings
+
+- `role="menubar"`, `aria-orientation="horizontal"`, `[attr.aria-label]`
+- `(keydown)` — horizontal `FocusKeyManager` navigation (ArrowLeft/Right, Home/End, type-ahead) across top-level items; opening keys (Enter/Space/ArrowDown/ArrowUp) are left to the focused trigger.
+
+#### Behavior (APG menubar)
+
+- **Roving tabindex** — only the active top-level item has `tabindex="0"` (`FocusKeyManager` horizontal, wrap, Home/End, type-ahead; disabled items skipped).
+- **Open** — `ArrowDown` / `Enter` / `Space` opens the focused item's menu with focus on its first item; `ArrowUp` opens with focus on the last item (handled by `MlvMenuTrigger`).
+- **Open-follow** — while any dropdown is open, arrowing or **hovering** to another top-level item closes the current menu and opens the sibling. Hover-follow is only active _while a menu is already open_ (a cold hover does nothing).
+- **In-menu crossing** — `ArrowRight` / `ArrowLeft` at the top level of an open dropdown crosses to the adjacent menubar menu (focusing its first item); a focused submenu-trigger item's own `ArrowRight` opens the submenu instead — **submenu wins** (it stops propagation before the panel's handler runs).
+- **Escape** — closes the menu and restores focus to its top-level item (via `MlvMenuTrigger`'s focus-restore).
+
+#### `MlvMenubarAccessor` methods (used by child triggers via `MENUBAR_TOKEN`)
+
+| Method                            | Description                                                                      |
+| --------------------------------- | -------------------------------------------------------------------------------- |
+| `hostElement`                     | Menubar host element — passed as the backdrop-less click-outside exclusion       |
+| `notifyItemOpened(item)`          | Records the open item; closes any previously-open sibling; syncs roving tabindex |
+| `notifyItemClosed(item)`          | Clears the open-item record                                                      |
+| `onItemPointerEnter(item)`        | Hover-follow (opens the hovered item only while another menu is already open)    |
+| `hasOpenMenu()`                   | Whether any dropdown in the bar is open                                          |
+| `openAdjacentItemMenu(from, dir)` | Crosses to the next/previous item's menu with focus on its first item            |
+
+---
+
+## Directives
+
+### `MlvMenuTrigger`
+
+**Selector:** `[mlvMenuTrigger]`
+
+#### Inputs
+
+| Name                  | Type                 | Default | Description                                        |
+| --------------------- | -------------------- | ------- | -------------------------------------------------- |
+| `mlvMenuTrigger`      | `MlvMenu` (required) | —       | The menu panel to open                             |
+| `isSubmenuTrigger`    | `BooleanInput`       | `false` | Activates submenu mode (hover + triangle tracking) |
+| `menuTriggerDisabled` | `BooleanInput`       | `false` | Disables the trigger                               |
+
+#### Outputs
+
+| Name         | Description                      |
+| ------------ | -------------------------------- |
+| `menuOpened` | Emits when the menu panel opens  |
+| `menuClosed` | Emits when the menu panel closes |
+
+#### Host bindings
+
+- `aria-haspopup="menu"`
+- `[attr.aria-expanded]` — bound to `_isOpen()`
+- `[attr.aria-controls]` — panel id while open
+- `[attr.role]` — `"menuitem"` when the trigger is a **menubar child**, otherwise `null` (standalone/submenu triggers keep their native/`MlvMenuItem` role)
+- `[attr.tabindex]` — roving tabindex (`_tabIndex()`) when a menubar child, otherwise `null`
+- `(click)` — toggles the menu (non-submenu mode)
+- `(mouseenter)` — menubar child: delegates to the bar's hover-follow; submenu trigger: opens the menu
+- `(mouseleave)` — schedules close with triangle check (submenu mode only)
+- `(keydown)` — Enter/Space, ArrowDown/Up, ArrowRight (submenu), Escape keyboard support
+
+#### Methods
+
+| Method     | Description      |
+| ---------- | ---------------- |
+| `open()`   | Opens the menu   |
+| `close()`  | Closes the menu  |
+| `toggle()` | Toggles the menu |
+
+#### Menubar-child mode
+
+When a `[mlvMenuTrigger]` is a **direct child of a `mlv-menubar`** it can inject `MENUBAR_TOKEN` and switches into menubar-child mode: it exposes `role="menuitem"` + a roving tabindex, opens its dropdown **without a backdrop** (so sibling top-level items stay hoverable/clickable — the menubar host is passed as `dismissExcludeElements`), reports open/close via `MlvMenubarAccessor.notifyItemOpened/Closed`, and registers a `MlvMenubarMenuController` on the menu so the panel's top-level ArrowRight/ArrowLeft cross to sibling menus. It additionally implements the `MlvMenubarItem` shape (`disabledBoolean`, `_tabIndex`, `focus()`, `getLabel()`, `isMenuOpen()`, `openMenu()`, `closeMenu()`, `openMenuWithFirstItemFocused()`, `openMenuWithLastItemFocused()`). **Standalone and submenu triggers are completely unaffected** — they never inject the token, so role/tabindex stay `null` and backdrop/behavior are unchanged.
+
+---
+
+## Submenu Hover Intent
+
+When `isSubmenuTrigger="true"`, the directive installs a document-level `mousemove`
+listener. Intent is resolved by **what the pointer is over**, with geometry used
+only for the ambiguous space between the item and its panel:
+
+| Pointer is over                  | Result                                                                                                                                               |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The trigger item itself          | Stays open, whatever the trajectory. Resting the cursor makes no horizontal progress, so a cone-only rule would close it.                            |
+| A different row of the same menu | Closes. Unambiguous intent that no cone can express — the panel is tall, so from the far edge of the item the safe area covers most downward travel. |
+| Anything in between              | The safe cone decides, backed by a 150 ms grace timer.                                                                                               |
+
+The cone requires at least `MIN_HORIZONTAL_PROGRESS` (2px) of travel **toward**
+the panel. Without it, `deltaX === 0` is not movement "away", so sliding straight
+down the item column registered as aiming at the submenu and held it open over a
+sibling row.
+
+The grace timer — not the cone — is what tolerates a 1px wobble and the 8px
+`SUBMENU_POSITIONS` gap between item and panel. Both re-entry points (the panel's
+`mouseenter` and the trigger's) cancel it, so crossing that gap in either
+direction is safe; the panel's `mouseleave` schedules rather than forces a close,
+because on the way back to the parent item the cursor traverses the gap where
+`relatedTarget` is the overlay container, never the trigger.
+
+This prevents the submenu from closing when the user moves the cursor diagonally from the parent item toward the submenu — a common UX problem in nested menus.
+
+The geometry calculation lives in the pure internal `submenu-aim.ts` module;
+the trigger directive owns event subscription and timer orchestration only.
+
+---
+
+## CSS Classes
+
+| Class                              | Description                                                                                          |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `.mlv-menu`                        | Host block                                                                                           |
+| `.mlv-menu__panel`                 | Floating panel with `role="menu"`                                                                    |
+| `.mlv-list-item` (in menu context) | Menu item — styled with compact padding and a small rounded hover/focus surface inside popup padding |
+| `.mlv-menu-separator`              | Host block for separator                                                                             |
+| `.mlv-menu-separator__line`        | The `<hr>` element                                                                                   |
+| `.mlv-menu-group`                  | Host block for group                                                                                 |
+| `.mlv-menu-group__label`           | Applied by `[mlvMenuGroupLabel]`                                                                     |
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic menu -->
+<button [mlvMenuTrigger]="menu">Open</button>
+<mlv-menu #menu>
+  <mlv-list-item mlvMenuItem (itemClick)="onEdit()">Edit</mlv-list-item>
+  <mlv-menu-separator />
+  <mlv-list-item mlvMenuItem (itemClick)="onDelete()">Delete</mlv-list-item>
+</mlv-menu>
+
+<!-- With icon prefix -->
+<mlv-list-item mlvMenuItem (itemClick)="onEdit()">
+  <svg mlvListItemPrefix lucideEdit [size]="14" />
+  Edit
+</mlv-list-item>
+
+<!-- With chevron suffix (submenu indicator) -->
+<mlv-list-item mlvMenuItem [mlvMenuTrigger]="subMenu" [isSubmenuTrigger]="true">
+  More options
+  <svg mlvListItemSuffix lucideChevronRight [size]="12" />
+</mlv-list-item>
+
+<!-- Grouped menu -->
+<mlv-menu #menu>
+  <mlv-menu-group>
+    <span mlvMenuGroupLabel>File</span>
+    <mlv-list-item mlvMenuItem>New</mlv-list-item>
+    <mlv-list-item mlvMenuItem>Open</mlv-list-item>
+  </mlv-menu-group>
+</mlv-menu>
+```
+
+**Required imports** (consumer component):
+
+```ts
+import { MlvMenu, MlvMenuItem, MlvMenuTrigger } from '@malva-ui/core/menu';
+import { MlvListItem } from '@malva-ui/core/list'; // always needed for mlv-list-item
+```
+
+---
+
+## File Structure
+
+---
+
+## Dependencies
+
+| Package                 | Version   | Role                                     |
+| ----------------------- | --------- | ---------------------------------------- |
+| `@angular/core`         | `^22.0.0` | Signals, DI, component                   |
+| `@angular/cdk/a11y`     | `^22.0.0` | `FocusKeyManager`, `FocusableOption`     |
+| `@angular/cdk/overlay`  | `^22.0.0` | CDK overlay positioning                  |
+| `@angular/cdk/portal`   | `^22.0.0` | `TemplatePortal` (via `MlvPopupService`) |
+| `@angular/cdk/coercion` | `^22.0.0` | `BooleanInput`, `coerceBooleanProperty`  |
+
+---
+
+## Accessibility notes (updated)
+
+- The menu panel is wrapped by `mlv-popup` which no longer applies `role="dialog"`/`aria-modal`/focus-trap; the `mlv-list` inside owns `role="menu"`.
+- `MlvMenu.panelId` — stable id on the panel (now `mlvNextId('mlv-menu-panel')` from `@malva-ui/cdk/utils`, replacing a hand-rolled module counter); `MlvMenuTrigger` wires `aria-controls` (trigger → panel) while open, alongside `aria-haspopup="menu"`.
+- `MlvMenuItem._tabIndex` is now a `signal` (OnPush-safe roving tabindex).
+- Focus is returned to the trigger on **all** close reasons (item activation, in-panel Escape, Tab, ArrowLeft on a submenu, backdrop) via `MlvMenuTrigger`; Tab-close calls `preventDefault()`.
+- Submenu keyboard: `ArrowRight` on a submenu trigger opens the submenu and focuses its first item; `ArrowLeft` inside a submenu closes it and returns focus to the parent item.
+- `MlvMenuGroup` names its `role="group"` via `aria-labelledby` pointing at the generated id of the projected `[mlvMenuGroupLabel]` (that id is now `mlvNextId('mlv-menu-group-label')` from `@malva-ui/cdk/utils`, replacing a hand-rolled counter).
+- **Type-ahead** (added with `@angular/aria` migration Task 2.6): typing a printable letter while the menu is open moves focus to the first item whose visible text starts with the typed string (200 ms debounce, wraps). Implemented via CDK `FocusKeyManager.withTypeAhead()`; `MlvMenuItem.getLabel()` returns the item's trimmed `textContent`. Disabled items are skipped. The key manager's `change` stream keeps the roving tabindex in sync when type-ahead moves the active item asynchronously.
+
+## `@angular/aria` migration status (Task 2.6) — deviation
+
+**The `@angular/aria` `Menu`/`MenuItem`/`MenuTrigger`/`MenuContent` (`ngMenu*`) primitives were evaluated and NOT adopted; `mlv-menu` keeps its custom `FocusKeyManager` + CDK-overlay implementation.** The aria `Menu` pattern is architecturally incompatible with this component's design and adopting it would break the public API. Precise reason:
+
+- The aria `Menu` directive requires **one single element** to simultaneously (a) be the DI parent that provides `MENU_COMPONENT` to its items — `ngMenuItem` resolves its parent via `inject(MENU_COMPONENT)`; (b) be the rendered, focusable DOM element that receives the `keydown`/`focusin`/`focusout`/`mouseover` host listeners aria binds; and (c) observe its own DOM children for item ordering (`_collection.startObserving(this.element)`).
+- `mlv-menu` deliberately splits these: menu items are **consumer-content-projected** into `<mlv-menu>` (so their DI parent is the `<mlv-menu>` host, where `MENU_TOKEN` lives), while the rendered panel is a **detached CDK-overlay `TemplatePortal`** (`mlv-list`) at document root (where focus, keyboard and item DOM live), and the `<mlv-menu>` host element itself stays empty/detached.
+- Placing `ngMenu` on the `<mlv-menu>` host satisfies DI but its keyboard/focus/order handling lands on the empty detached host — dead. Placing `ngMenu` on the internal overlay `mlv-list` satisfies keyboard/focus/DOM but projected items cannot `inject(MENU_COMPONENT)` across the `<ng-content>` boundary — DI dead. No single element satisfies all three without either abandoning CDK-overlay positioning (the plan requires keeping it) or replacing consumer content-projection with a data-driven `items` input (a public API break).
+- Contrast with the completed list migration (Task 2.1): there `Listbox`/`Option` sit on the consumer's own `<mlv-list>`/`<mlv-list-item>` elements in the same lexical scope, rendered in place — DI, DOM and keyboard all coincide.
+
+Per the plan's fallback clause and risk register ("if a pattern doesn't fit, keep the manual implementation"), only the aria-parity **type-ahead** behavior was added (via CDK `FocusKeyManager`, since aria's own type-ahead cannot be used here). Roving focus, roles, submenu hover/triangle tracking, ArrowLeft/ArrowRight submenu handling, and focus-restore-to-trigger all remain the existing custom implementation.
+
+## `mlv-menubar` — `@angular/aria` `ngMenuBar` evaluation (NOT adopted)
+
+`@angular/aria` exports `MenuBar` (`[ngMenuBar]`) alongside `Menu`/`MenuItem`/`MenuTrigger`. It was evaluated for `mlv-menubar` and **not adopted**, for the same architectural reason `ngMenu` was rejected, propagated through the top-level dropdowns:
+
+- `ngMenuBar` is a `List`-based pattern whose top-level items must be `ngMenuItem` (required `value`), and each item's `submenu` input must reference an **`ngMenu`** that the menubar pattern opens/closes/focuses. `mlv-menubar`'s dropdowns are existing `mlv-menu` panels — **detached CDK-overlay `TemplatePortal`s with consumer-content-projected items** — not `ngMenu` directives. Wiring `ngMenuBar`'s item→submenu coordination to a `mlv-menu` overlay is exactly the DI-parent + focus-host + DOM-order-observer mismatch documented above for `ngMenu`, so the whole open/close/focus chain would land on empty detached hosts.
+- Adopting `ngMenuBar` would therefore force either (a) replacing every `mlv-menu` panel with an `ngMenu` (dropping CDK-overlay positioning + the content-projection public API — a breaking change), or (b) keeping `mlv-menu` panels and re-implementing the coordination anyway, at which point `ngMenuBar` adds nothing.
+
+So `mlv-menubar` keeps a custom implementation consistent with `mlv-menu`: a CDK `FocusKeyManager` (horizontal, wrap, Home/End, type-ahead) for the roving tabindex over the top-level `MlvMenuTrigger` children, and explicit open-follow / in-menu-crossing coordination via the small `MlvMenubarAccessor` / `MlvMenubarMenuController` contracts. This reuses `mlv-menu` + `MlvMenuTrigger` unchanged for the dropdown panels — the sanctioned "keep the manual implementation" fallback.

package/docs/ai/notification.md

@@ -0,0 +1,281 @@
+# Library: notification
+
+## Overview
+
+`@malva-ui/core/notification` provides richer programmatic notification cards with semantic icons, supporting text, and optional actions. It has two creation APIs:
+
+1. `show(config)` and the `success`/`error`/`warning`/`info`/`tone` shorthands render the standard title/description/actions notification.
+2. `open(content, config)` renders an escaped string, a typed `TemplateRef`, or an Angular component while retaining the standard icon, tone, description, actions, timer, position, and dismiss affordance.
+
+Every creation method returns a `MlvNotificationRef<TData>`, which extends the toast library's ref contract. Caller close, dynamic-content close, auto-dismiss, action close, and the built-in dismiss button all route through the shared service-owned lifecycle.
+
+Notification reuses `MlvToastContainer` and `MlvAbstractToastService` from `@malva-ui/core/toast`. Active cards are rendered as a normal linear list; there is no notification-specific container, `maxShownItems` option, or stacked-card layout mode.
+
+---
+
+## Public API
+
+Exported from `@malva-ui/core/notification`:
+
+| Export                                  | Kind            | Description                                                                 |
+| --------------------------------------- | --------------- | --------------------------------------------------------------------------- |
+| `MlvNotificationService`                | Service         | `show()`, `open()`, tone shorthands, and `close()`; provided in `root`      |
+| `MlvNotificationRef<TData>`             | Class           | Data-aware, injectable per-item close/lifecycle handle                      |
+| `MlvNotificationContent<TData>`         | Type alias      | Escaped string, typed `TemplateRef`, or component type accepted by `open()` |
+| `MlvNotificationOpenConfig<TData>`      | Interface       | Options for content-polymorphic `open()`                                    |
+| `MlvNotificationTemplateContext<TData>` | Interface       | `$implicit`, `ref`, `data`, and `config` exposed to template content        |
+| `NOTIFICATION_DATA`                     | Injection token | Data available to component content                                         |
+| `NOTIFICATION_CONFIG`                   | Injection token | Readonly per-open config available to component content                     |
+| `MlvNotificationConfig<TData>`          | Interface       | Standard `show()` config with required `title`                              |
+| `MlvNotificationTone`                   | Type alias      | Malva semantic tones plus `'default'`                                       |
+| `MlvNotificationAction`                 | Interface       | Label, callback, and optional button variant                                |
+| `MlvInternalNotification`               | Interface       | Fully resolved internal item state                                          |
+| `MlvNotificationItem`                   | Component       | Notification card rendered inside the shared toast container                |
+
+---
+
+## Service
+
+### `MlvNotificationService`
+
+**Provided in:** `root`
+
+Extends:
+
+```ts
+export class MlvNotificationService extends MlvAbstractToastService<MlvNotificationConfig, MlvInternalNotification, MlvIAbstractToastComponent<MlvInternalNotification>, MlvNotificationRef> {}
+```
+
+It reuses `MlvToastContainer` and supplies `MlvNotificationItem` as the item renderer.
+
+#### Creation methods
+
+| Method    | Signature                                                                                                                         | Description                                       |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `show`    | `(config: MlvNotificationConfig): MlvNotificationRef`                                                                             | Renders the standard notification card            |
+| `open`    | `<TData = unknown>(content: MlvNotificationContent<TData>, config?: MlvNotificationOpenConfig<TData>): MlvNotificationRef<TData>` | Renders string, template, or component content    |
+| `success` | `(title: string, config?: Omit<MlvNotificationConfig, 'title' \| 'tone'>): MlvNotificationRef`                                    | Standard card with `success` tone                 |
+| `error`   | `(title: string, config?: Omit<MlvNotificationConfig, 'title' \| 'tone'>): MlvNotificationRef`                                    | Standard card with `danger` tone                  |
+| `warning` | `(title: string, config?: Omit<MlvNotificationConfig, 'title' \| 'tone'>): MlvNotificationRef`                                    | Standard card with `warning` tone                 |
+| `info`    | `(title: string, config?: Omit<MlvNotificationConfig, 'title' \| 'tone'>): MlvNotificationRef`                                    | Standard card with `info` tone                    |
+| `tone`    | `(tone: MlvNotificationTone, title: string, config?: Omit<MlvNotificationConfig, 'title' \| 'tone'>): MlvNotificationRef`         | Generic tone shorthand                            |
+| `close`   | `(id: string, position?: MlvToastPosition): void`                                                                                 | Closes an item through the shared toast lifecycle |
+
+`show()` and every shorthand remain supported. `open()` adds content polymorphism without replacing the standard API.
+
+#### `open()` content branches
+
+- **String:** normalized to the standard title and rendered through Angular interpolation. HTML-looking input is displayed literally and never inserted as trusted HTML.
+- **TemplateRef:** rendered through `NgTemplateOutlet` with `MlvNotificationTemplateContext<TData>`.
+- **Component:** rendered through `NgComponentOutlet` with an injector providing `MlvNotificationRef`, its base `MlvToastRef`, `NOTIFICATION_DATA`, and `NOTIFICATION_CONFIG`.
+
+Template/component content replaces the standard title. `description`, tone icon/accent, actions, close button, position, and lifecycle options remain available through `MlvNotificationOpenConfig`.
+
+#### Resolved defaults
+
+| Field          | Default                        |
+| -------------- | ------------------------------ |
+| `position`     | `'top-right'`                  |
+| `tone`         | `'default'`                    |
+| `description`  | `''`                           |
+| `displayTime`  | `6000` ms                      |
+| `pauseOnHover` | `true`                         |
+| `closable`     | `true`                         |
+| `actions`      | `[]`                           |
+| `showIcon`     | `true`                         |
+| `politeness`   | `resolveToastPoliteness(tone)` |
+
+#### Close lifecycle
+
+All close sources delegate to `MlvAbstractToastService.close()`. The shared container removes the item, the service completes the matching `MlvNotificationRef`, and an empty position overlay is disposed after the shared `200ms` leave interval. Calling `MlvNotificationRef.close()` repeatedly is safe.
+
+Action callbacks run first and then automatically request close.
+
+#### Announcement
+
+The announcement includes the title, the description, **and every action label** — a
+notification never takes focus, so a screen-reader user has to be told that an action
+exists at all. Politeness follows `config.politeness`, defaulting to
+`resolveToastPoliteness(tone)`. Template and component content is not announced; it owns
+its own text.
+
+`LiveAnnouncer` requires the `.cdk-visually-hidden` rules shipped in
+`styles/malva-ui.css` — without that stylesheet the announcement renders visibly.
+
+---
+
+## Content, config, and context types
+
+### `MlvNotificationContent<TData = unknown>`
+
+```ts
+export type MlvNotificationContent<TData = unknown> = string | TemplateRef<MlvNotificationTemplateContext<TData>> | Type<unknown>;
+```
+
+### `MlvNotificationTemplateContext<TData = unknown>`
+
+```ts
+export interface MlvNotificationTemplateContext<TData = unknown> {
+  $implicit: MlvNotificationRef<TData>;
+  ref: MlvNotificationRef<TData>;
+  data: TData;
+  config: Readonly<MlvNotificationOpenConfig<TData>>;
+}
+```
+
+`$implicit` and `ref` are the same handle. Templates can use `let-ref`, `let-ref="ref"`, `let-data="data"`, and `let-config="config"`.
+
+### `MlvNotificationAction`
+
+```ts
+export interface MlvNotificationAction {
+  label: string;
+  action: () => void;
+  variant?: 'primary' | 'secondary';
+}
+```
+
+### `MlvNotificationConfig<TData = unknown>`
+
+Extends `MlvBaseToastConfig<TData>`:
+
+| Field         | Type                      | Required | Description                                     |
+| ------------- | ------------------------- | -------- | ----------------------------------------------- |
+| `title`       | `string`                  | yes      | Standard escaped title                          |
+| `description` | `string`                  | no       | Supporting text                                 |
+| `tone`        | `MlvNotificationTone`     | no       | Semantic icon, border, and announcement urgency |
+| `actions`     | `MlvNotificationAction[]` | no       | Buttons rendered below the main row             |
+| `showIcon`    | `boolean`                 | no       | Whether the tone icon is shown                  |
+
+It also inherits `position`, typed `data`, `injector`, `displayTime`, `pauseOnHover`, and `closable`.
+
+### `MlvNotificationOpenConfig<TData = unknown>`
+
+Extends `MlvBaseToastConfig<TData>` with optional `description`, `tone`, `actions`, and `showIcon`. It intentionally has no `title`; content is passed separately to `open()`.
+
+---
+
+## Injection tokens
+
+### `NOTIFICATION_DATA`
+
+`InjectionToken<unknown>` containing `MlvNotificationOpenConfig.data` for component content. Templates read the typed value from their `data` context property.
+
+### `NOTIFICATION_CONFIG`
+
+`InjectionToken<Readonly<MlvNotificationOpenConfig>>` containing the complete per-open configuration for component content. Templates receive the same object as `config`.
+
+The dynamic component injector also aliases the same ref instance as `MlvToastRef`, allowing infrastructure shared with toast to inject the base ref contract.
+
+---
+
+## `MlvNotificationRef<TData = unknown>`
+
+Extends `MlvToastRef<TData>` without changing its lifecycle:
+
+| Member          | Type               | Description                                      |
+| --------------- | ------------------ | ------------------------------------------------ |
+| `id`            | `string`           | Unique generated item id                         |
+| `data`          | `TData`            | Readonly value from the matching config          |
+| `closed`        | `Signal<boolean>`  | Becomes `true` when the service removes the card |
+| `close()`       | `void`             | Requests dismissal; idempotent                   |
+| `afterClosed()` | `Observable<void>` | Emits once after removal, then completes         |
+
+The same instance is returned to the caller, injected into component content, and exposed to template content.
+
+---
+
+## `MlvNotificationItem`
+
+**Files:** *(internal)*
+
+- Selector: `mlv-notification-item`.
+- Extends `MlvAbstractToastItem<MlvInternalNotification>`.
+- Host class is `mlv-notification-item mlv-notification-item--{tone}`.
+- Carries **no** `role`/`aria-live`. `MlvNotificationService` announces through the CDK `LiveAnnouncer` instead, so the card is not itself a live region (see `libs-toast.md` → Screen-reader announcement).
+- Selects success, danger, warning, or information Lucide icons from the resolved tone.
+- Renders template content with `NgTemplateOutlet`, component content with `NgComponentOutlet`, or the standard escaped title.
+- Renders optional description, form-safe `type="button"` close control, and configured action buttons around any dynamic content.
+- `.mlv-notification-item__dynamic-content` provides safe wrapping and primary text color.
+
+The item is mounted by the generic `MlvToastContainer`; there is no `NotificationContainerComponent`.
+
+---
+
+## Usage
+
+### Standard API and shorthands
+
+```ts
+const ref = this.notifications.show({
+  title: 'Release ready',
+  description: 'Version 4.2.0 passed all checks.',
+  tone: 'success',
+  actions: [
+    {
+      label: 'Open release',
+      variant: 'primary',
+      action: () => this.openRelease(),
+    },
+  ],
+});
+
+ref.afterClosed().subscribe(() => {
+  // The notification has been removed.
+});
+
+this.notifications.error('Deployment failed', { displayTime: 0 });
+```
+
+### String, template, and component content
+
+```ts
+this.notifications.open('Deployment completed successfully.', {
+  tone: 'success',
+});
+
+const ref = this.notifications.open<ReleaseData>(template, {
+  displayTime: 0,
+  data: { version: '4.2.0' },
+});
+
+this.notifications.open<ReleaseData>(ReleaseContentComponent, {
+  displayTime: 0,
+  data: { version: '4.2.0' },
+});
+```
+
+```html
+<ng-template #template let-ref let-data="data" let-config="config">
+  <strong>Release {{ data.version }}</strong>
+  <button mlvButton (click)="ref.close()">Dismiss</button>
+</ng-template>
+```
+
+```ts
+export class ReleaseContentComponent {
+  readonly ref = inject<MlvNotificationRef<ReleaseData>>(MlvNotificationRef);
+  readonly data = inject(NOTIFICATION_DATA) as ReleaseData;
+  readonly config = inject(NOTIFICATION_CONFIG) as Readonly<MlvNotificationOpenConfig<ReleaseData>>;
+}
+```
+
+---
+
+## Dependencies
+
+| Package                       | Usage                                                                                    |
+| ----------------------------- | ---------------------------------------------------------------------------------------- |
+| `@malva-ui/core/toast`        | Abstract service/item, shared container, `MlvToastRef`, config and positioning contracts |
+| `@malva-ui/core/button`       | Dismiss and action buttons                                                               |
+| `@malva-ui/core/chip`         | Tone icon badge                                                                          |
+| `@malva-ui/cdk/accessibility` | Accessible click handling                                                                |
+| `@malva-ui/cdk/utils`         | Shared tone type                                                                         |
+| `@malva-ui/i18n`              | Dismiss label                                                                            |
+| `@angular/core`               | Component, signals, templates, tokens, and injectors                                     |
+| `@angular/common`             | `NgTemplateOutlet`, `NgComponentOutlet`                                                  |
+| `@lucide/angular`             | Tone and dismiss icons                                                                   |
+
+## Testing
+
+Component tests cover creation, the absence of live-region roles on the card, and focus-safe timer pausing. Service tests cover string/template/component content, data context/token, typed refs, duplicate-close safety, and shared overlay cleanup.