@malva-ui/core 0.1.12 → 0.1.14

package/docs/ai/icon-toggle.md

@@ -0,0 +1,160 @@
+# Library: icon-toggle
+
+## Overview
+
+`@malva-ui/core/icon-toggle` provides a **chromeless, glyph-only** WAI-ARIA
+toggle button (`button[mlvIconToggle]`) — visual-language spec **AB-R7**. It
+wraps exactly one projected Lucide `<svg>` and expresses `pressed` purely
+through the glyph itself: an outlined icon at rest, a "tiny fill" on hover,
+and a full `fill: currentColor` when pressed. There is **no background in any
+state** — the defining constraint. An optional `tone` recolours only the
+pressed glyph to a matching semantic text token (e.g. a favourite star).
+
+Built to replace ad hoc "tinted circle behind a glyph" treatments — see the
+support-inbox star (exhibit B), which adopts this component in the showcase
+sweep, not here.
+
+- **Leaf project (Nx):** `core-icon-toggle` at *(internal)*
+- **Secondary entry point:** `@malva-ui/core/icon-toggle` (also re-exported from the grouped `@malva-ui/core` barrel)
+- **Package tag:** `scope:ui`
+
+## Public API
+
+Exported from `@malva-ui/core/icon-toggle`:
+
+| Symbol          | Kind      | Selector                | Description                          |
+| --------------- | --------- | ----------------------- | ------------------------------------ |
+| `MlvIconToggle` | Component | `button[mlvIconToggle]` | Chromeless glyph-only toggle button. |
+
+`MlvTone` (the `tone` input's type) is not re-exported here — import it from `@malva-ui/cdk/utils`.
+
+## Component
+
+### `MlvIconToggle` — `button[mlvIconToggle]`
+
+- **Change detection:** `OnPush` · **Encapsulation:** `None`
+- **Template:** `<ng-content />` — the host **is** the native `<button>`;
+  the consumer projects exactly one Lucide `<svg>` and nothing else. Follows
+  the repo's `button[mlvButton]` attribute-selector-on-native-element pattern
+  (`.claude/rules/angular-component.md` § Selectors): native `disabled`,
+  `type`, and click/keyboard activation semantics all work unmodified — no
+  custom keydown handling is added, so Enter/Space activate through the
+  browser's native button semantics exactly like a plain `<button>`.
+
+#### Inputs / Model
+
+| Name       | Type                   | Default     | Description                                                                                                                                                                                                                                               |
+| ---------- | ---------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pressed`  | `model<boolean>`       | `false`     | Two-way bindable pressed state, reflected as `aria-pressed`. Bind one-way (`[pressed]` + `(pressedChange)`) when a caller owns the source of truth — same convention as `mlv-button-toggle`.                                                              |
+| `tone`     | `MlvTone \| undefined` | `undefined` | Recolours only the **pressed** glyph to the matching semantic text token (`info` → `--mlv-text-info`, `success` → `--mlv-text-positive`, `warning` → `--mlv-text-warning`, `danger` → `--mlv-text-negative`). Rest/hover stay neutral regardless of tone. |
+| `disabled` | `boolean` (coerced)    | `false`     | Native `disabled` + `aria-disabled`.                                                                                                                                                                                                                      |
+
+#### Host bindings
+
+```ts
+host: {
+  class: 'mlv-icon-toggle',
+  '[class.mlv-icon-toggle--pressed]': 'pressed()',
+  '[class]': '_toneClass()',                 // "mlv-icon-toggle--tone-<tone>" or ''
+  '[attr.aria-pressed]': 'pressed()',
+  '[attr.disabled]': 'disabled() || null',
+  '[attr.aria-disabled]': 'disabled() || null',
+  '(click)': '_handleClick()',
+}
+```
+
+`hostDirectives: [MlvDensityDirective]` (exposing `mlvDensity`) with
+`MLV_DENSITY_ELEMENT: 'icon-toggle'` — same pattern as `MlvButton`. Emits
+`mlv-icon-toggle--{tight,compact,comfortable,spacious,airy}` directly on the
+host.
+
+## Accessibility
+
+WAI-ARIA toggle button pattern. `aria-pressed` always reflects `pressed()`
+regardless of `disabled`. Every consumer must supply an accessible name —
+`aria-label` on the button (the projected `<svg>` should carry
+`aria-hidden="true"`), matching every other icon-only control in the library
+(`.claude/rules/accessibility.md` § Icon Buttons and Ambiguous Controls).
+
+The pointer target is held at a minimum of `1.5rem` (24px — WCAG 2.2 SC
+2.5.8) via `min-inline-size`/`min-block-size` plus density-aware padding,
+**never** by inflating the glyph — "chromeless does not mean
+tap-target-less" (AB-R7). Focus ring is Form A (SF-R3): `outline:
+var(--mlv-stroke-width-medium) solid var(--mlv-border-focus)` with
+`outline-offset: var(--mlv-focus-ring-offset)` on `:focus-visible`.
+
+## Styling
+
+- BEM block `.mlv-icon-toggle`. **No background in any state** — this is the
+  component's defining constraint; a design that needs a filled/tinted
+  toggle affordance should reach for `mlv-button-toggle` instead.
+- **Fill-state mechanism** (Lucide ships no separate filled icon set, so
+  "pressed" is a CSS `fill` on the _same_ outlined glyph — correct only for
+  icons with an enclosed shape such as a star, heart, bookmark, or pin, not
+  for open-stroke glyphs):
+  - rest: `color: var(--mlv-text-secondary)`; `svg { fill: transparent; }`
+  - hover (not pressed): `color: var(--mlv-text-primary)`; `svg { fill: color-mix(in srgb, currentColor 15%, transparent); }`
+  - pressed: `color: var(--mlv-text-primary)`; `svg { fill: currentColor; }`
+  - pressed + `tone`: `color` overridden to the matching semantic text token; fill stays `currentColor`, so the glyph itself carries the tone
+  - the hover rule is scoped `:not(.mlv-icon-toggle--pressed):hover` so it can never fight the tone-pressed color rule for the same element
+  - focus-visible: Form A (SF-R3)
+  - disabled: native `:disabled` — `opacity: var(--mlv-disabled-opacity)`, `cursor: not-allowed`, `pointer-events: none` (no dedicated `--disabled` class needed; the host is always a real `<button>`)
+- **Sizing** — `min-inline-size`/`min-block-size: 1.5rem` unconditionally
+  (WCAG 2.5.8 floor), plus density-aware `padding` from `--mlv-spacing-*`:
+  tight `-1` (4px), compact `-1-5` (6px), comfortable `-2` (8px, default),
+  spacious `-2-5` (10px), airy `-3` (12px). The projected `<svg>`'s own size
+  is entirely author-controlled via its `[size]` attribute — the component
+  never resizes it.
+- **Motion** — `fill` transitions at `var(--mlv-duration-fast)` `var(--mlv-ease-default)`; `@include mixins.reduced-motion($block);` collapses it to `var(--mlv-duration-instant)` under `prefers-reduced-motion: reduce` (MO-R1/MO-R4).
+
+## Usage
+
+```html
+<!-- Neutral toggle, no tone -->
+<button mlvIconToggle type="button" [(pressed)]="bookmarked" aria-label="Bookmark">
+  <svg lucideBookmark [size]="16" aria-hidden="true" />
+</button>
+
+<!-- `tone` recolours only the pressed glyph — the exhibit-B star pattern -->
+<button mlvIconToggle type="button" tone="warning" [pressed]="ticket.starred" aria-label="Star conversation" (pressedChange)="toggleStar()">
+  <svg lucideStar [size]="16" aria-hidden="true" />
+</button>
+
+<!-- Disabled -->
+<button mlvIconToggle type="button" disabled [pressed]="true" aria-label="Star (disabled)">
+  <svg lucideStar [size]="16" aria-hidden="true" />
+</button>
+```
+
+```ts
+import { MlvIconToggle } from '@malva-ui/core/icon-toggle';
+
+@Component({
+  imports: [MlvIconToggle],
+})
+```
+
+## Dependencies
+
+- `@angular/cdk/coercion` — `BooleanInput`, `coerceBooleanProperty`
+- `@malva-ui/cdk/density` — `MlvDensityDirective`, `MLV_DENSITY_ELEMENT`
+- `@malva-ui/cdk/utils` — `MlvTone` (type-only import)
+- Malva UI CSS design tokens (`--mlv-*`)
+
+## Tests
+
+no pressed class); click toggles `pressed`/`aria-pressed`/the pressed class;
+a documented native-`<button>`-semantics test proving no custom keydown
+handling intercepts activation (real Enter/Space coverage lives in Playwright
+e2e, following the *(internal)* precedent); disabled gates the
+toggle and reflects native `disabled` + `aria-disabled`; tone modifier class
+reflection across all four `MlvTone` values, independent of pressed state;
+disabled+pressed+tone renders together (the host keeps `--pressed` and
+`--tone-*` alongside `disabled`/`aria-disabled`, so a disabled toggle still
+shows its dimmed pressed styling rather than losing state); two-way
+`[(pressed)]` binding through a host component (writes back on click,
+reflects an externally-set value); and a Sass-compiled fill-state assertion
+(rest `transparent`, hover-not-pressed `color-mix(...)`, pressed
+`currentColor`, and that no rule ever declares a `background`/`background-color`
+other than `transparent`) — the same source-text-assertion technique
+jsdom cannot resolve.

package/docs/ai/input.md

@@ -173,3 +173,33 @@ Marks a consumer-projected native `<input>` that `mlv-input` should adopt as its
 - Inherited `required` renders the `mlv-label` marker and sets `aria-required` on the native `<input>`.
 - Inherited `description` renders `<mlv-description>` below the control (wrapped mode only — `bare` renders no chrome).
 - The non-reactive `messageId` string field is gone; `<mlv-message>` now carries the base's `_messageId()` so `aria-describedby` resolves even when a consumer sets `[id]`.
+
+## Type & padding ramp fix (2026-08-26)
+
+`.mlv-input__native` previously declared a flat, non-ramped
+`padding: var(--mlv-spacing-1)` on top of the wrapper's own (already ramped)
+container padding — a doubled inline padding no other control carried, and
+one that grew disproportionately at `tight`. It now matches
+`mlv-select`/`mlv-combobox`/`mlv-time-picker`/`mlv-number-input`: the
+wrapper's `.mlv-form-control-wrapper__control-container` padding is zeroed
+in `input.scss` and `.mlv-input__native` owns the full ramped
+`var(--mlv-control-padding)` itself. Its font-size also moved off a
+hardcoded `--mlv-font-size-l` onto `var(--form-ctrl-font-size, var(--mlv-font-size-m))`
+— the same density-ramped chain `mlv-number-input`/`mlv-textarea` already
+used. See `.claude/projects/libs-form-utils.md` → _Control-text type &
+padding ramp_.
+
+**Padding ownership in `bare` mode.** The fix above applies unconditionally
+in `mlv-input`'s default (non-`bare`) mode, where it owns its own wrapper.
+`bare` mode (`projectControl`'s sibling flag — "used by composite controls
+that own their own surrounding container", per the `bare` input's own
+doc comment) is different: `mlv-combobox`, `mlv-tokenizer`, and
+`mlv-select`'s in-dropdown search field all project a bare `<mlv-input>`
+inside a trigger/row that **already** applies the full ramped padding
+itself. `bare()` is now reflected as a host class,
+`[class.mlv-input--bare]`, and `input.scss` adds
+`&--bare &__native { padding: 0; }` so the bare native element contributes
+no inset of its own — one padded box per control, owned by whichever
+element (the wrapper, or the composite's own trigger row) actually draws
+the field's boundary. Font-size is unaffected by `bare` — it still reads
+`var(--form-ctrl-font-size, var(--mlv-font-size-m))` regardless.

package/docs/ai/layout.md

@@ -56,6 +56,12 @@ host: {
 }
 ```
 
+The host binding scopes the theme to this subtree. Publishing the theme on the
+**document element** is `MlvThemeService`'s job, not the layout's — see below.
+`mlv-layout` used to own that write, which meant an application (or a single
+route) that renders no layout got a theme switcher that flipped a signal nobody
+read.
+
 #### Content Children
 
 | Name      | Directive       | Description                        |
@@ -118,6 +124,23 @@ Marks template for sidebar. Provides `templateRef: TemplateRef`.
 - `setTheme(mode: MlvThemeMode): void` — set a selected mode, persist it, and
   synchronize the resolved theme
 
+#### Root Theme Attribute
+
+The service writes the resolved theme to `document.documentElement` as
+`mlvTheme="light|dark"` from a constructor `effect`, browser-only. `theme.scss`
+keys its dark token map off a plain `[mlvTheme='dark']` attribute selector, so
+nothing changes colour until that attribute exists above the content.
+
+- It lives here, not on `mlv-layout`, so the theme applies regardless of which
+  components are on screen. Any route that renders no layout still themes.
+- The service is `providedIn: 'root'`, so the write happens as soon as anything
+  injects it — which any theme control already does.
+- A scoped `mlvTheme` attribute further down the tree still wins locally: it is
+  a plain attribute selector and custom properties inherit, so the nearest
+  matching ancestor decides. That is how a permanently-dark rail inside an
+  otherwise light page works.
+- Server rendering never touches `documentElement`.
+
 #### Storage Behavior
 
 1. Attempts `localStorage` first

package/docs/ai/list.md

@@ -18,6 +18,7 @@ Exported from `@malva-ui/core/list`:
 |--------|------|-------------|
 | `MlvList` | Component | List container — `mlv-list` |
 | `MlvListVariant` | Type alias | `'plain' \| 'inset'` |
+| `MlvListAppearance` | Type alias | `'default' \| 'menu'` — context-specific row styling (standalone vs. overlay panel) |
 | `MlvListItem` | Component | List row — `mlv-list-item` |
 | `MlvListItemAccent` | Type alias | Semantic accent key or raw CSS color for the leading bar |
 | `MlvListItemMedia` | Directive | Leading rich-media slot — `[mlvListItemMedia]` |
@@ -48,10 +49,11 @@ Template: `<ng-content />`
 
 #### Inputs
 
-| Name       | Type             | Default   | Description                                                                                                                                                                                                                                                                         |
-| ---------- | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `listRole` | `string`         | `'list'`  | WAI-ARIA role for the host element. Override to `'menu'` when used as a menu container.                                                                                                                                                                                             |
-| `variant`  | `MlvListVariant` | `'plain'` | Visual variant. `'plain'` — spaced rows with no container styling. `'inset'` — iOS Settings-style grouped look: rows sit on a raised surface inside a sunken, rounded card; consecutive rows are joined by inset dividers and group headers become sticky uppercase section labels. |
+| Name         | Type                | Default     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------ | ------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `listRole`   | `string`            | `'list'`    | WAI-ARIA role for the host element. Override to `'menu'` when used as a menu container.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `variant`    | `MlvListVariant`    | `'plain'`   | Visual variant. `'plain'` — hairline-separated rows, no per-row card: the container has zero gap and paints a single `border-top` (`--mlv-border-subtle`) between consecutive `mlv-list-item` rows (never on the row itself), each row's own `--mlv-list-item-radius` is `0`, and `--mlv-list-item-bg` is `transparent` at rest — a row gets a fill only on hover, selection, or focus (SL-R5). `'inset'` — iOS Settings-style grouped look: rows sit on a raised surface inside a sunken, rounded card; consecutive rows are joined by inset dividers (not the plain variant's container hairline — `:not(.mlv-list--inset)` scopes it out) and group headers become sticky uppercase section labels.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `appearance` | `MlvListAppearance` | `'default'` | Context-specific row styling, orthogonal to `variant`. `mlv-list` is a shared primitive used both as a standalone content list and as the panel container inside overlays (select/combobox/autocomplete dropdown, `mlv-menu`, popover menus like the tabs overflow / breadcrumb overflow / drawer-sections menu). `'default'` emits no modifier class — the airy SL-R5 standalone look above. `'menu'` adds `.mlv-list--appearance-menu`, which (a) suppresses the `'plain'`-variant hairline separator (`list.css` — `:not(.mlv-list--appearance-menu)` scopes it out) and (b) restores the pre-harmonization compact overlay rhythm on every descendant `mlv-list-item` via an ancestor-selector override in `list-item.scss`: `--mlv-list-item-padding-block: var(--mlv-spacing-2)` (was `--mlv-spacing-3`) and `--mlv-list-item-radius: var(--mlv-radius-m)` (was `0`), so the row has rounded corners for the hover/selection pill instead of being clipped by the container. Every internal overlay consumer (`mlv-dropdown-panel`, `mlv-menu`, tabs overflow popup, breadcrumb overflow popup, `mlv-drawer-sections`) sets this; standalone/docs list examples stay on the `'default'` appearance. |
 
 ---
 
@@ -89,14 +91,16 @@ The component automatically switches to the rich layout when any of the rich slo
 The row exposes a consistent state hierarchy styled via component-scoped CSS variables:
 
 - `:hover` — subtle tinted background
-- `:focus-visible` — accent focus ring via `--mlv-border-focus`
+- `:focus-visible` — Form A focus ring, `var(--mlv-stroke-width-medium)` `var(--mlv-border-focus)` at `var(--mlv-focus-ring-offset)` (SF-R3)
 - `:active` — pressed scale (0.985)
-- `--active` / `[aria-selected='true']` — tinted accent background and revealed leading accent bar
+- `--active` / `[aria-selected='true']` / `[aria-current]:not([aria-current='false'])` — `--mlv-background-selected` / `-hover` fill, `--mlv-text-on-selected` label, and revealed leading accent bar. Selection is its own token (SF-R1) — it never resolves the pressed `-active` fill. `aria-current` covers rows that name the state their context is already in (active heading level / list type / alignment in an editor menu, current saved view); presence minus the one negative value, so navigational `page`/`step` rows match too.
 - `--unread` — semibold title + leading unread dot
 - `--has-accent` — explicit accent bar always rendered
 
 Rendered row content is wrapped in `.mlv-list-item__surface`; the host owns focus/selection state, while pressed `:active` scaling is applied only to that inner surface.
 
+**Content projection (template invariant):** `list-item.html` follows the conditional-projection pattern — every `ng-content` slot (each selector and the wildcard default) appears exactly **once**, wrapped in an `ng-template`, and the rich/legacy layout branches stamp those templates through `ngTemplateOutlet`. Never duplicate a selector (or the bare `<ng-content />`) across the `@if` branches: slot assignment is static, so projected nodes bind to the first matching slot even when that branch never renders, and the content silently vanishes (this is exactly how legacy `[mlvListItemPrefix]` rows inside menus used to lose their icons). ng-content `select` attribute names are camelCase, matching the authored directive attributes.
+
 #### Density
 
 `list-item.scss` carries a density ladder driven by the shared cascade mixins (`@malva-ui/styles` `density.scss`): an ancestor `mlv--{density}` class (from `mlvDensityRoot`, or the class `mlv-popup` stamps on its detached overlay panel) scales the `--mlv-list-item-padding-block` / `--mlv-list-item-padding-inline` vars — tight `--mlv-spacing-1`, compact `--mlv-spacing-1-5`, comfortable `--mlv-spacing-2` (baseline default), spacious `--mlv-spacing-2-5`, airy `--mlv-spacing-3`. Consumers that override row padding must route it through those vars (not a direct `padding:`), or the ladder cannot apply — see the menu-panel row rule in `menu.scss` for the pattern.

package/docs/ai/menu.md

@@ -18,6 +18,13 @@ Exported from `@malva-ui/core/menu`:
 | `MlvMenuGroup` | Component | Group container — `mlv-menu-group` |
 | `MlvMenuGroupLabel` | Directive | Group label slot — `[mlvMenuGroupLabel]` |
 | `MlvMenuTrigger` | Directive | Opens a menu on click/hover — `[mlvMenuTrigger]` |
+| `MlvMenuItemData` | Interface | Typed reactive menu item data with optional lazy `children` |
+| `MlvMenuDataSource` | Type | Array or `MlvDataSource` accepted by reactive menus |
+| `MlvMenuItemDef` | Directive | Typed projected row template — `[mlvMenuItemDef]` |
+| `MlvMenuItemDefContext` | Interface | `$implicit`, `index`, `hasChildren`, and `loading` template context |
+| `MlvMenubarDividerData` | Interface | Root-level data divider discriminator and stable id |
+| `MlvMenubarEntry` | Type | Menubar item-or-divider entry type |
+| `MlvMenubarDataSource` | Type | Array or `MlvDataSource` accepted by reactive menubars |
 | `MlvMenubar` | Component | Horizontal application menu bar — `mlv-menubar` |
 | `MlvMenuAccessor` | Interface | Parent menu accessor interface (via `MENU_TOKEN`) |
 | `MENU_TOKEN` | Token | `InjectionToken<MlvMenuAccessor>` |
@@ -42,6 +49,7 @@ Exported from `@malva-ui/core/menu`:
 | ------------ | ------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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. |
+| `dataSource`  | `MlvMenuDataSource<TItem> \| undefined` | `undefined` | Reactive item collection. Accepts an array or `MlvDataSource<TItem>`; when set, the menu renders the projected `[mlvMenuItemDef]` row template instead of projected menu rows. |
 
 #### Outputs
 
@@ -65,13 +73,51 @@ Exported from `@malva-ui/core/menu`:
 - `_isOpen: WritableSignal<boolean>` — managed by `MlvMenuTrigger`
 - `_popup: Signal<MlvPopup>` — accessed by `MlvMenuTrigger` for overlay management
 
+#### Reactive data mode
+
+`dataSource` accepts either `MlvMenuItemData<T>[]` or an `MlvDataSource`
+instance. Project one typed row definition with `[mlvMenuItemDef]`; the
+template receives the item as `$implicit` plus `index`, `hasChildren`, and
+`loading`:
+
+```html
+<mlv-menu [dataSource]="items">
+  <mlv-list-item
+    mlvMenuItem
+    *mlvMenuItemDef="let item; let hasChildren = hasChildren"
+  >
+    {{ item.label }}
+    @if (hasChildren) {
+      <mlv-spacer />
+      <svg mlvListItemSuffix lucideChevronRight [size]="16" />
+    }
+  </mlv-list-item>
+</mlv-menu>
+```
+
+An item with `children: Observable<MlvMenuItemData<T>[]>` becomes a submenu
+trigger automatically. The child stream is subscribed to on first open and
+the submenu displays the localized loader while it is pending. A generated
+submenu arrow is supplied by menu styling; an explicit suffix in a custom row
+template takes precedence.
+
+#### Key-manager lifecycle (roving tabindex)
+
+The `FocusKeyManager` is reconciled from a constructor `effect()` reading `_items()`, and the reconciliation is deliberately **`untracked`**:
+
+- `_syncTabIndices()` reads `FocusKeyManager.activeItem`, which CDK backs with a **signal** (`ListKeyManager._activeItem`). Reading it inside the effect's reactive context made the effect depend on the active item, so **every** arrow key re-ran the effect → new manager → `activeItemIndex` reset to `-1`. Symptoms: ArrowDown always returned to the first item, ArrowUp to the last, and no `role="menuitem"` ever held `tabindex="0"`. Home/End/type-ahead hid the bug because they are absolute moves. **`_items()` must stay the effect's only dependency.**
+- `_syncKeyManager(items)` bails when the item set is member-identical to `_managedItems` (a snapshot), so a change-detection pass that re-runs the content query never rebuilds the manager.
+- A real item change rebuilds and carries the active item over with `updateActiveItem()` (no focus steal). If the active item was removed/disabled, `mlvNearestEnabledItem()` picks the closest enabled item to its old index — the tab stop never falls back to "nothing".
+- `_teardownKeyManager()` unsubscribes the `change` stream and calls `FocusKeyManager.destroy()`; also wired to `DestroyRef.onDestroy`.
+- `_syncTabIndices()` invariant: **exactly one enabled item carries `tabindex="0"` while the panel is open.** That is the active item once navigation started; before then (pointer-opened panel, focus on the `role="menu"` list) the first enabled item is the tab stop. The key manager's index stays `-1` in that state, so the first ArrowDown still lands on the **first** item.
+
 ---
 
 ### `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.
+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 leaf activation. When the same row is an enabled `[mlvMenuTrigger]` with `[isSubmenuTrigger]="true"`, the trigger owns click/Enter/Space activation so opening the child menu does not select the row or dismiss its ancestor. A disabled submenu trigger falls back to the item's leaf `itemClick` and close-all behavior.
 
 Users must import both `MlvListItem` (from `@malva-ui/core/list`) and `MlvMenuItem` (from `@malva-ui/core/menu`).
 
@@ -127,6 +173,7 @@ A horizontal File / Edit / View style application menu bar implementing the [WAI
 | Name    | Type     | Default | Description                                |
 | ------- | -------- | ------- | ------------------------------------------ |
 | `label` | `string` | `''`    | `aria-label` for the `role="menubar"` host |
+| `dataSource` | `MlvMenubarEntry<TItem>[] \| MlvDataSource<MlvMenubarEntry<TItem>> \| undefined` | `undefined` | Reactive top-level items. Entries may be item data or `MlvMenubarDividerData`; dividers are visual root separators and are excluded from keyboard navigation. |
 
 #### Host bindings
 
@@ -141,6 +188,15 @@ A horizontal File / Edit / View style application menu bar implementing the [WAI
 - **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).
 
+#### Reactive data mode
+
+Menubars accept the same typed item definition as menus. Set `dataSource` to an
+array or `MlvDataSource` and use `MlvMenubarDividerData` entries for root-level
+vertical separators. Dividers render with `role="separator"` and
+`aria-orientation="vertical"`; they never receive a tabindex or participate in
+roving navigation. Lazy `children` streams create generated dropdown menus and
+use the localized pending loader.
+
 #### `MlvMenubarAccessor` methods (used by child triggers via `MENUBAR_TOKEN`)
 
 | Method                            | Description                                                                      |
@@ -201,6 +257,23 @@ When a `[mlvMenuTrigger]` is a **direct child of a `mlv-menubar`** it can inject
 
 ---
 
+## Generated submenu overlay origin
+
+`MlvMenuDataItem` anchors a generated submenu to the row that `ngTemplateOutlet`
+stamps, which does not exist yet when the overlay controller is constructed. The
+origin is therefore a real `ElementRef` instance whose `nativeElement` is
+redefined as a lazy getter, **not** a plain object with the same shape.
+
+The instance matters: CDK's `FlexibleConnectedPositionStrategy._getOriginRect()`
+only calls `getBoundingClientRect()` when the origin passes
+`instanceof ElementRef` (or `instanceof Element`). Anything else is read as an
+`{x, y}` point — `undefined` coordinates propagate to `NaN`, the pane's `top`
+and `left` are dropped as invalid, and every generated submenu renders at the
+viewport's top-left corner instead of beside its row. Covered by
+"anchors a generated submenu to the rendered row through a real ElementRef
+
+---
+
 ## Submenu Hover Intent
 
 When `isSubmenuTrigger="true"`, the directive installs a document-level `mousemove`
@@ -313,6 +386,7 @@ import { MlvListItem } from '@malva-ui/core/list'; // always needed for mlv-list
 - 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.
+- **Roving tabindex** — exactly one enabled `role="menuitem"` holds `tabindex="0"` while the panel is open, and it follows ArrowUp/ArrowDown/Home/End/type-ahead. See "Key-manager lifecycle" under `MlvMenu` for the rebuild rules that keep this true (a rebuilt `FocusKeyManager` would otherwise reset the active index to `-1`).
 
 ## `@angular/aria` migration status (Task 2.6) — deviation