@malva-ui/core 0.1.12

package/docs/ai/tabs.md

@@ -0,0 +1,564 @@
+# Library: tabs
+
+The overflow trigger explicitly uses `type="button"` to remain form-safe.
+
+## Overview
+
+`@malva-ui/core/tabs` provides a full-featured, accessible tab group component for the Malva UI design system. It supports horizontal and vertical orientations, animated content transitions, overflow handling (tabs that don't fit in the header move to a popup "More" menu), keyboard navigation, and two-way binding for the active tab.
+
+The library is built entirely with Angular signals, uses `ChangeDetectionStrategy.OnPush`, and is compliant with ARIA tab panel patterns (`role="tablist"`, `role="tab"`, `role="tabpanel"`).
+
+### `@angular/aria` integration (Phase 2 · Task 2.3)
+
+The tablist's roving focus, arrow-key navigation, selection and ARIA wiring are delegated to `@angular/aria`'s headless tabs pattern (migrated from a hand-rolled `FocusKeyManager`):
+
+- `MlvTabGroup` host-applies aria `Tabs` (`hostDirectives: [Tabs]`).
+- The header (`.mlv-tab-group__header`) is `ngTabList`; each visible `mlv-tab-item` carries `ngTab [value]`.
+- The active panel (`mlv-tab-content`) is `ngTabPanel` and wraps `[mlvTabContent]` 1:1 in an `ngTabContent` structural directive; inert stub `ngTabPanel`s (`.mlv-tab-group__panel-stub`, `display:none`) are rendered for the other visible tabs so every `ngTab`'s `aria-controls` resolves (aria's dev validator requires a matching panel; the overflow architecture renders only the active panel's real content).
+
+aria now owns `role="tab"/"tablist"/"tabpanel"`, `aria-selected`, `aria-disabled`, `aria-orientation`, the roving `tabindex`, and auto-wires `aria-controls` ↔ `aria-labelledby` by matching `value` (no more manual id computation). Pins on `ngTabList`: `selectionMode="follow"` (auto-select on arrow, as before), `[softDisabled]="false"` (skip/never-select disabled tabs, as before), `[wrap]="false"` (no wrap, as before). RTL is now correct via CDK `Directionality` (the old `FocusKeyManager` hard-coded `'ltr'`). `mlv-tab-item` keeps its own click/Enter/Space→`activate` handlers; Enter/Space `stopPropagation()` so aria's tablist keydown does not additionally activate the roving-focused tab, preserving the historical "keyboard activation targets the event's tab" contract. The former "Arrow past the last visible tab opens the overflow popup" shortcut was dropped — the "More" button stays mouse/Tab/Enter reachable.
+
+---
+
+## Public API
+
+Exported from `@malva-ui/core/tabs`:
+
+| Export                | Kind            | Description                                                                                                                    |
+| --------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------- |
+| `MlvTabGroup`         | Component       | Root container. Renders the tab header (list + indicator) and active content panel.                                            |
+| `MlvTab`              | Component       | Invisible definition node. Declares a single tab's value, disabled state, and its label/content templates.                     |
+| `MlvTabDef`           | Directive       | Structural directive applied to an `<ng-template>` inside `<mlv-tab>` to define the tab label.                                 |
+| `MlvTabDefContext`    | Type            | Template context for `mlvTabDef` — `{ $implicit: boolean }` where `$implicit` is `true` when the tab is in the overflow popup. |
+| `MlvTabContentDef`    | Directive       | Structural directive applied to an `<ng-template>` inside `<mlv-tab>` to define the panel content.                             |
+| `MlvTabItem`          | Component       | Low-level clickable tab button rendered inside the header. Receives `active`/`disabled` inputs and emits `activate`.           |
+| `MlvTabContent`       | Component       | Wrapper for the active panel; applies CSS entry/leave animation classes.                                                       |
+| `TAB_GROUP`           | Injection Token | `InjectionToken<MlvTabGroupAccessor>` — lets child components access the parent `MlvTabGroup` without a direct import.         |
+| `MlvTabGroupAccessor` | Interface       | Contract exposed via `TAB_GROUP`: `activeTab`, `orientation`, `selectTab()`, `isActive()`.                                     |
+| `MlvTabOrientation`   | Type            | `'horizontal'                                                                                                                  | 'vertical'` |
+| `MlvTabAppearance`    | Type            | `'underline' \| 'boxed'` — header visual style (Phase A). Orthogonal to `orientation`; composes with horizontal & vertical.    |
+| `MlvTabsService`      | Service         | Scoped service (provided by `MlvTabGroup`) that manages tab registration, visible/overflow split, and forced-visible logic.    |
+
+---
+
+## Components
+
+### `MlvTabGroup`
+
+**Selector:** `mlv-tab-group`
+
+**Purpose:** The root shell. Renders the header (`role="tablist"`), the animated active indicator bar, the overflow "More" popup, and the active tab's content panel.
+
+#### Inputs (models / signals)
+
+| Name          | Type                                                           | Default        | Description                                                                                                                                                                                                                                                                                                                           |
+| ------------- | -------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `orientation` | `model<MlvTabOrientation>`                                     | `'horizontal'` | Layout direction. `'horizontal'` stacks tabs in a row; `'vertical'` stacks them in a column. Two-way bindable.                                                                                                                                                                                                                        |
+| `activeTab`   | `model<string>`                                                | `''`           | Value of the currently selected tab. Two-way bindable. Auto-selects the first tab if the value is empty or does not match any registered tab. **Suppressed in routed mode** — the URL owns the active tab.                                                                                                                            |
+| `appearance`  | `input<MlvTabAppearance>`                                      | `'underline'`  | Header visual style. `'underline'` shows the sliding indicator bar (non-active tabs get a grey hover line at the indicator position); `'boxed'` is a segmented control — grey content-width track with a white pill that slides behind the active tab. **Orthogonal to `orientation`** — a boxed group can be horizontal or vertical. |
+| `mlvDensity`  | `input<MlvDensity>` (via `MlvDensityDirective` host directive) | inherited      | Content density for the group. Adds `mlv-tab-group--<density>` on the host; `tab-item.scss` scales padding/font-size per level (tight/compact/comfortable/spacious/airy). Inherits from the nearest density ancestor when unset.                                                                                                      |
+
+#### Internal signals / computed
+
+| Name                    | Description                                                                                                           |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `selectedTab`           | `computed<string \| undefined>` — bridges `activeTab` to the aria `ngTabList` `selectedTab` model (`'' → undefined`). |
+| `visibleTabs`           | `computed` — tabs that fit in the header (delegates to `MlvTabsService.visibleTabs`).                                 |
+| `overflowTabs`          | `computed` — tabs hidden from the header (delegates to `MlvTabsService.overflowTabs`).                                |
+| `activeContentTemplate` | `computed<TemplateRef<unknown> \| null>` — the `mlvTabContent` template for the active tab.                           |
+
+`_onSelectedTabChange(value)` bridges the aria `selectedTabChange` output back to `activeTab` (ignoring `undefined`).
+
+#### Outputs
+
+| Name                | Type                         | Description                              |
+| ------------------- | ---------------------------- | ---------------------------------------- |
+| `activeTabChange`   | `output<string>`             | The `activeTab` model's change output.   |
+| `orientationChange` | `output<MlvTabsOrientation>` | The `orientation` model's change output. |
+
+Both are the `model()` change outputs — there are no separate `output()` declarations.
+
+#### Host directives
+
+- `Tabs` (`ngTabs`) from `@angular/aria/tabs` — the container the aria tab list/panels register against (no inputs).
+- `MlvDensityDirective` from `@malva-ui/cdk/density` (exposes `mlvDensity`; `MLV_DENSITY_ELEMENT` is provided as `'tab-group'`, which the directive prefixes to produce `mlv-tab-group--<density>`).
+
+#### Host bindings
+
+```
+class: 'mlv-tab-group'
+[class.mlv-tab-group--horizontal]:        orientation() === 'horizontal'
+[class.mlv-tab-group--vertical]:          orientation() === 'vertical'
+[class.mlv-tab-group--appearance-boxed]:  appearance() === 'boxed'
+```
+
+#### Public methods
+
+| Method              | Signature                  | Description                                                                                                                                                                                                                                   |
+| ------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `selectTab`         | `(value: string): void`    | Activates a tab by value. No-op if the tab is disabled. **For a routed tab (one with a `[routerLink]`) it calls `router.navigateByUrl(urlTree)` instead of setting `activeTab` directly** — the resulting `NavigationEnd` drives `activeTab`. |
+| `selectOverflowTab` | `(value: string): void`    | Promotes an overflow tab to visible area, then activates it.                                                                                                                                                                                  |
+| `isActive`          | `(value: string): boolean` | Returns `true` if the given value matches `activeTab()`.                                                                                                                                                                                      |
+
+#### Overflow popup methods (template-facing, public)
+
+| Method                   | Signature                      | Description                                                                     |
+| ------------------------ | ------------------------------ | ------------------------------------------------------------------------------- |
+| `openOverflowPopup`      | `(): void`                     | Opens the "More" popup and resets the overflow roving index to the first entry. |
+| `onMorePopupAfterOpened` | `(): void`                     | Moves focus into the popup once it finishes opening.                            |
+| `onMorePopupAfterClosed` | `(): void`                     | Restores focus to the "More" trigger after the popup closes.                    |
+| `onOverflowKeydown`      | `(event: KeyboardEvent): void` | Arrow/Home/End/Escape roving navigation inside the overflow popup.              |
+
+#### Providers
+
+- `MlvTabsService` — scoped to the component tree.
+- `TAB_GROUP` → `useExisting: MlvTabGroup` — exposes `MlvTabGroupAccessor` to descendants.
+
+#### Template structure summary
+
+```
+.mlv-tab-group__header  ngTabList [orientation] [wrap]=false [softDisabled]=false selectionMode=follow [(selectedTab)]
+  @for visibleTabs
+    <mlv-tab-item ngTab [value]> with ng-template mlvTabDef (context: { $implicit: false })
+      label rendered directly inside the role="tab" — routed and non-routed are identical
+      (no nested <a>: an anchor inside role="tab" trips axe nested-interactive)
+  @if overflowTabs.length > 0
+    <button .mlv-tab-group__more-trigger [mlvPopupTrigger]>
+    <mlv-popup>
+      <ng-template mlvPopupContent>
+        <mlv-list>
+          @for overflowTabs → <mlv-list-item> with ng-template mlvTabDef (context: { $implicit: true })
+  <div .mlv-tab-group__indicator #indicatorRef>
+.mlv-tab-group__body
+  @if activeContentTemplate
+    <mlv-tab-content ngTabPanel [value]=activeTab>
+      <ng-template ngTabContent><ng-container [ngTemplateOutlet]=activeContentTemplate></ng-template>
+  @for visibleTabs where !isActive → <div .mlv-tab-group__panel-stub ngTabPanel [value]><ng-template ngTabContent></div>
+```
+
+#### CSS
+
+Key classes:
+
+- `.mlv-tab-group` — `display:flex; flex-direction:column` (row when `--vertical`); **`min-width: 0`**.
+- `.mlv-tab-group__header` — `display:flex; overflow:hidden`; **`min-width: 0`**. Horizontal: bottom border shadow. Vertical: right border shadow.
+- `.mlv-tab-group__indicator` — absolutely-positioned bar animated via CSS custom properties `--mlv-tab-indicator-left`, `--mlv-tab-indicator-width` (horizontal) or `--mlv-tab-indicator-top`, `--mlv-tab-indicator-height` (vertical). Duration controlled via `--mlv-tab-indicator-duration` (default `220ms`).
+- `.mlv-tab-group__more-trigger` — the "More (N)" overflow button.
+- `.mlv-tab-group__body` — `flex:1; min-width:0; min-height:0`.
+
+**`min-width: 0` on the block and header is load-bearing, not tidiness.** The
+overflow split is computed from `headerEl.clientWidth`, so it only engages when
+the group can actually be narrower than its tab row. A flex or grid item
+defaults to `min-width: auto`, whose content-based minimum here is the full
+width of the tab row — `overflow: hidden` on the header suppresses the
+_automatic minimum size_ of a flex item, not the min-content contribution the
+parent track sizes against. Without it, a tab group placed in a grid or flex
+child refuses to shrink, `clientWidth` never drops, "More (N)" never appears,
+declarations (the stylesheet is asserted directly — component styles are not
+injected under jsdom, so `getComputedStyle` cannot see them).
+
+CSS variables used:
+
+- `--mlv-border-subtle` — header bottom/right separator box-shadow.
+- `--mlv-border-normal` — non-active hover line (underline appearance).
+- `--mlv-background-accent-1` — indicator bar fill.
+- `--mlv-palette-neutral-400` — more-trigger colour (no hover colour shift — see Hover policy under Appearance).
+- `--mlv-border-focus` / `--mlv-radius-s` — more-trigger focus ring.
+- `--mlv-duration-normal` — more-trigger colour transition.
+- `--mlv-ease-in-out-strong` — indicator slide easing.
+- `--mlv-background-sunken` / `--mlv-background-raised` / `--mlv-background-neutral-1-hover` / `--mlv-radius-xl` / `--mlv-shadow-1` / `--mlv-text-primary` — boxed appearance (track, pill, hover tint, concentric radius).
+
+#### Appearance (Phase A)
+
+`appearance` (`'underline' | 'boxed'`, default `'underline'`) is **orthogonal to `orientation`** — two independent inputs that compose, not a single union.
+
+**Hover policy (both appearances):** tabs never shift text colour on hover — only the **active** state recolours. The hover affordance is positional instead: underline shows a grey line, boxed tints the item background.
+
+`'underline'` — the classic sliding indicator bar. A non-active, non-disabled tab (and the overflow "More" trigger, which gets `position: relative` for this) shows a **grey hover line** (`::after`, `var(--mlv-border-normal)`) at the exact indicator position — bottom edge for horizontal, inline-end for vertical. Scoped via `.mlv-tab-group:not(.mlv-tab-group--appearance-boxed)`.
+
+`'boxed'` — a **segmented control**. Under `mlv-tab-group--appearance-boxed`:
+
+- the `__header` becomes the grey **track**: `width: fit-content` (content-width, so it can be aligned horizontally; `height: fit-content` for vertical), `background: var(--mlv-background-sunken)`, `border-radius: var(--mlv-radius-xl)`, `padding: 0.1875rem`, `gap: 0.125rem`, separator box-shadow dropped;
+- the `__indicator` is repurposed as the **white pill that SLIDES behind the active tab** (reusing the same `left/width | top/height` animation as the underline bar) — `background: var(--mlv-background-raised)`, `box-shadow: var(--mlv-shadow-1)`, `z-index: 0`, inset inside the track padding (`top/bottom: 0.1875rem` horizontal, `left/right: 0.1875rem` vertical), **concentric radius** `calc(var(--mlv-radius-xl) - 0.1875rem)` (track radius minus track padding);
+- each `.mlv-tab-item` gets the concentric `border-radius` + `z-index: 1` (label above the pill); **non-active hover** tints `var(--mlv-background-neutral-1-hover)` (NOT `neutral-1` — that token equals the sunken track colour, making the hover invisible); the **active** item only changes `color` to `var(--mlv-text-primary)` (the sliding pill provides its background — it is _not_ given its own `background`);
+- the `__more-trigger` mirrors the non-active item treatment (radius, `z-index: 1`, hover tint) — it never carries the pill.
+
+**Every boxed selector uses the child combinator (`>`)** — `.mlv-tab-group--appearance-boxed > .mlv-tab-group__header > .mlv-tab-item` etc. — so a boxed group **never** restyles the tab-items/indicator of a tab-group **nested inside its panels** (e.g. demo tab-groups inside a boxed docs Examples panel). The earlier descendant-combinator version leaked boxed styling into nested underline groups; the child combinator is load-bearing, not cosmetic. Boxed composes with `--horizontal` and `--vertical` (a vertical boxed group slides the pill top/height).
+
+#### Routed mode (Phase A2)
+
+When **any** registered tab carries a `[routerLink]` (its `urlTree()` is non-null), the group enters **routed mode** (`_isRouted` computed). In routed mode the URL is the source of truth for the active tab:
+
+- The group injects `Router` (`{ optional: true }` — non-routed groups work with no router provided) and subscribes to `Router.events` filtered to `NavigationEnd` (`takeUntilDestroyed`). On each event — and once on init via an effect, because the router may already be settled — `_syncActiveFromRoute()` sets `activeTab` to the value of the first tab whose `urlTree` satisfies `router.isActive(urlTree, options)`. `linkActiveOptions` is honoured: the `{ exact }` shorthand is mapped through `Router.isActive`'s boolean overload (exact ↔ subset), a full `IsActiveMatchOptions` is passed straight through.
+- The **auto-select-first** effect and **`_onSelectedTabChange`** (aria's optimistic selection) both early-return while routed, so nothing sets `activeTab` behind the route's back.
+- `selectTab()` navigates (`router.navigateByUrl(urlTree)`) rather than setting `activeTab`; the resulting `NavigationEnd` updates it. This covers both click and keyboard (Enter/Space) activation.
+- **No header anchor.** The label renders directly inside the `role="tab"` (`<mlv-tab-item>`), for both routed and non-routed tabs. A routed tab does **not** wrap its label in an `<a href>`: an anchor is inherently interactive, and nesting it inside `role="tab"` fails the axe **`nested-interactive`** rule (a hard requirement). The trade-off is that routed tabs lose native middle-click / open-in-new-tab; the URL is still fully deep-linkable and back/forward works. (An earlier version wrapped the label in an `<a tabindex="-1" role="presentation">`, but `role="presentation"` cannot suppress a focusable anchor, so axe still flagged it — hence the removal.)
+- `role="tab"` / `aria-selected` continue to come from `ngTab`; because `activeTab` is updated from the route, aria stays in sync.
+
+**Subtlety (documented in code):** `routerLink` on `<mlv-tab>` is a URL _carrier_ on the `display:none` def node; `routerLinkActive` cannot style the separately-rendered header, so active state is owned explicitly via `Router.isActive` — intentional, not a workaround to remove later.
+
+> `Router.isActive(url, options)` is marked `@deprecated 21.1` (superseded by the standalone `isActive()` signal function) but remains functional, long-stable public API and is not flagged by the repo's ESLint config (no type-checked/`no-deprecated` ruleset).
+
+Overflow-menu focus restoration uses this tab group's own queried item refs;
+it never performs a document-wide selector, so multiple tab groups remain
+independent.
+
+#### Active-tab pinning (content survival)
+
+`MlvTabGroup` keeps the **active tab pinned into the visible row** via an
+`effect` that mirrors `activeTab` into `MlvTabsService.forcedVisibleValue`. When
+overflow is active this swaps the active tab into the last visible slot (the same
+mechanism as picking a tab from the overflow popup), guaranteeing the active tab
+always keeps a rendered `ngTab`.
+
+This is load-bearing for correctness, not cosmetics: `@angular/aria` derives the
+active `ngTabPanel`'s visibility from its controlling `ngTab`'s `expanded` state.
+If the active tab's `ngTab` is torn down (e.g. a resize repartition pushes it into
+overflow, or the old code cleared `forcedVisibleValue` on every resize), aria
+desyncs its `selectedTab` model, marks the active panel `inert`, and the deferred
+`ngTabContent` **destroys the panel body permanently** — the content vanishes and
+never re-renders. Pinning the active tab prevents that teardown, so active content
+survives any resize/repartition. (The `activeContentTemplate` panel additionally
+survives even if the active tab is driven fully into overflow, because aria treats
+a panel with no matching `ngTab` as visible.)
+
+#### Overflow / resize behaviour
+
+`MlvTabGroup` uses a native `ResizeObserver` on the header element after
+view init. The recalculation is **damped** to eliminate the flickering
+("dizzy") repartition that a naive per-frame recalc produces:
+
+1. **Debounce** — ResizeObserver callbacks are coalesced with a trailing
+   `setTimeout` (`_RESIZE_DEBOUNCE_MS = 64`), so a drag triggers one
+   recalculation after the width settles rather than one per frame.
+2. **Width caching (no measure→mutate loop)** — each tab's natural header width
+   is cached by value (`_tabWidths`) the first time all tabs render. Subsequent
+   recalculations compute the split purely from the cache and the container
+   width — they never reset the rendered set to "show all" to re-measure, which
+   was the source of the flicker and the observer feedback loop. The DOM is only
+   expanded-to-measure when the cache is cold or a new tab was added.
+3. **Hysteresis** — `_computeFittingCount(widths, containerWidth, moreButtonWidth,
+currentMax)` is a pure function returning how many leading tabs fit (`-1` when
+   all fit). A tab currently in overflow must clear the boundary by an extra
+   `_HYSTERESIS_PX = 24` before it returns to the visible row, while a visible
+   tab leaves as soon as it no longer fits. This asymmetric threshold makes the
+   split a fixed point at boundary widths, so it cannot oscillate.
+
+`MlvTabsService.visibleTabs` / `overflowTabs` guard the `maxVisibleCount === 0` case
+(all tabs overflow): the active/forced tab becomes the sole visible tab instead of
+duplicating the last natural tab (which previously produced an `NG0955`
+duplicate-track-key warning).
+
+---
+
+### `MlvTab`
+
+**Selector:** `mlv-tab`
+
+**Purpose:** Invisible definition node (`display:none`). Wraps a tab's value, disabled state, and two optional `<ng-template>` slots: one for the header label (`mlvTabDef`) and one for the panel body (`mlvTabContent`). Registers itself with `MlvTabsService` on init and unregisters on destroy.
+
+#### Inputs
+
+| Name                | Type                                                  | Default            | Description                                                                                                                                                                                |
+| ------------------- | ----------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `value`             | `input.required<string>()`                            | —                  | Unique identifier for the tab. Used to match against `MlvTabGroup.activeTab`.                                                                                                              |
+| `disabled`          | `input(false)`                                        | `false`            | When `true`, prevents the tab from being activated.                                                                                                                                        |
+| `linkActiveOptions` | `input<{ exact: boolean } \| IsActiveMatchOptions>()` | `{ exact: false }` | (Phase A2) Match options controlling when this **routed** tab is considered active, mirroring `RouterLinkActive.routerLinkActiveOptions`. Only consulted when a `[routerLink]` is present. |
+
+#### Routable tabs (Phase A2)
+
+A consumer may put Angular's native `[routerLink]` (plus `queryParams` / `fragment` / `relativeTo` / …) directly on `<mlv-tab>`. `MlvTab` optionally self-injects the `RouterLink` directive and exposes:
+
+| Member      | Signature             | Description                                                                                                                                               |
+| ----------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `urlTree()` | `(): UrlTree \| null` | The `UrlTree` this tab links to, or `null` when no `[routerLink]` is applied. A non-null value on **any** tab switches the parent group into routed mode. |
+
+The `routerLink` sits on the `display:none` `<mlv-tab>` def node purely as a **URL carrier** — because the header tab is rendered separately by `mlv-tab-group`, `routerLinkActive` cannot style it, so active state is derived explicitly from `Router.isActive` (see the routed-mode notes on `MlvTabGroup`). This is intentional, not a workaround.
+
+#### Content queries
+
+| Name              | Type                             | Description                                      |
+| ----------------- | -------------------------------- | ------------------------------------------------ |
+| `defTemplate`     | `contentChild(MlvTabDef)`        | The `mlvTabDef` template for the tab label.      |
+| `contentTemplate` | `contentChild(MlvTabContentDef)` | The `mlvTabContent` template for the panel body. |
+
+#### Host bindings
+
+```
+style: 'display: none'
+```
+
+---
+
+### `MlvTabItem`
+
+**Selector:** `mlv-tab-item`
+
+**Purpose:** The rendered, focusable tab button in the header. Projects its content via `<ng-content />`. Handles click and keyboard (Enter / Space) activation. The parent `mlv-tab-group` applies `@angular/aria`'s `ngTab` directive on this element, which owns `role="tab"`, `aria-selected`, `aria-disabled`, the DOM `id`, the roving `tabindex`, and `aria-controls`; this component only owns the active/disabled **styling** and the `activate` output.
+
+#### Inputs
+
+| Name       | Type           | Default | Description                                                                                               |
+| ---------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------- |
+| `active`   | `input(false)` | `false` | Whether this tab is currently selected. Drives the `--active` style class only (ARIA comes from `ngTab`). |
+| `disabled` | `input(false)` | `false` | Whether this tab is disabled. Drives the `--disabled` style class only.                                   |
+
+> The former `controls` input was removed — `aria-controls` is auto-wired by `ngTab` from the matching `ngTabPanel` value.
+
+#### Outputs
+
+| Name       | Type             | Description                                        |
+| ---------- | ---------------- | -------------------------------------------------- |
+| `activate` | `output<void>()` | Emitted on click or Enter/Space when not disabled. |
+
+#### Public methods
+
+| Method    | Signature  | Description                                                                       |
+| --------- | ---------- | --------------------------------------------------------------------------------- |
+| `focus()` | `(): void` | Moves DOM focus to the tab button — used by the group's overflow/roving handling. |
+
+#### Host bindings
+
+```
+class: 'mlv-tab-item'
+[class.mlv-tab-item--active]:    active()
+[class.mlv-tab-item--disabled]:  disabled()
+(click):                        !disabled() && activate.emit()
+(keydown.enter):                !disabled() && activate.emit(); $event.stopPropagation()
+(keydown.space):                !disabled() && activate.emit(); $event.stopPropagation(); $event.preventDefault()
+```
+
+`role="tab"`, `aria-selected`, `aria-disabled`, `aria-controls`, `id`, and the roving `tabindex` are contributed by the `ngTab` directive applied on the element by `mlv-tab-group`. Enter/Space `stopPropagation()` so aria's `ngTabList` keydown does not additionally activate the roving-focused tab.
+
+#### CSS
+
+- `.mlv-tab-item` — `inline-flex; gap:0.5rem; padding:0.75rem 1rem` (comfortable). No hover colour shift.
+- Density mixins (`density.density-*`) scale padding/font-size per group `mlvDensity`: tight `0.375rem 0.625rem`, compact `0.5rem 0.75rem`, spacious `1rem 1.25rem`, airy `1.25rem 1.5rem`.
+- `--active` — `color: var(--mlv-text-action)` (boxed overrides to `text-primary`).
+- `--disabled` — `opacity:0.5; cursor:not-allowed`.
+
+Boxed overrides for `.mlv-tab-item` (radius, `z-index:1`, hover tint, active colour) live in `tabs.scss` under `--appearance-boxed` via child combinators.
+
+---
+
+### `MlvTabContent`
+
+**Selector:** `mlv-tab-content`
+
+**Purpose:** Presentational wrapper for the active panel content. It has no inputs — `role="tabpanel"`, the panel `id` and `aria-labelledby` are contributed by the `@angular/aria` `ngTabPanel` directive applied on the element by `mlv-tab-group` (which wires them to the controlling tab by matching `value`).
+
+#### Inputs
+
+None.
+
+#### Host bindings
+
+```
+class: 'mlv-tab-content'
+```
+
+`role="tabpanel"`, `id`, `aria-labelledby`, and the `inert` toggle come from the `ngTabPanel` directive.
+
+#### CSS
+
+- `.mlv-tab-content--enter` — keyframe `tab-content-enter`: fade in + slide from `-0.25rem` Y. Duration: `--mlv-tab-content-enter-duration` (default `200ms`).
+- `.mlv-tab-content--leave` — keyframe `tab-content-leave`: fade out + slide to `-0.25rem` Y. Duration: `--mlv-tab-content-leave-duration` (default `150ms`).
+
+---
+
+## Directives
+
+### `MlvTabDef`
+
+**Selector:** `[mlvTabDef]`
+
+**Purpose:** Applied to an `<ng-template>` inside `<mlv-tab>` to define the tab header label. The template is rendered inside `<mlv-tab-item>` in both the visible header and the overflow popup.
+
+**Template context:** `MlvTabDefContext`
+
+```ts
+interface MlvTabDefContext {
+  $implicit: boolean; // true when rendered in the overflow popup, false in the header
+}
+```
+
+Includes an `ngTemplateContextGuard` static method for proper type narrowing.
+
+---
+
+### `MlvTabContentDef`
+
+**Selector:** `[mlvTabContent]`
+
+**Purpose:** Applied to an `<ng-template>` inside `<mlv-tab>` to define the panel body that is rendered inside `<mlv-tab-content>` when the tab is active.
+
+No inputs or outputs. Exposes `templateRef: TemplateRef`.
+
+---
+
+## Services
+
+### `MlvTabsService`
+
+**Scope:** Provided by `MlvTabGroup` (NOT `providedIn: 'root'`). Each `MlvTabGroup` instance gets its own `MlvTabsService`.
+
+**Purpose:** Tracks all registered `MlvTab` instances; computes which tabs are visible vs. in the overflow; manages the "forced visible" state when a user selects a tab from the overflow popup.
+
+#### Signals
+
+| Signal               | Type                 | Description                                                                                                                                                        |
+| -------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `tabs`               | `signal<MlvTab[]>`   | All registered tab components in DOM order.                                                                                                                        |
+| `maxVisibleCount`    | `signal<number>`     | `-1` means no overflow (all tabs fit). A positive number limits the visible set.                                                                                   |
+| `forcedVisibleValue` | `signal<string       | null>`                                                                                                                                                             | When a user picks an overflow tab, its value is stored here to swap it into the visible slot. |
+| `visibleTabs`        | `computed<MlvTab[]>` | Subset of `tabs` that are displayed in the header. Implements swap logic: if a forced tab is beyond `maxVisibleCount`, it replaces the last naturally-visible tab. |
+| `overflowTabs`       | `computed<MlvTab[]>` | Tabs not shown in the header. Complement of `visibleTabs`.                                                                                                         |
+
+#### Methods
+
+| Method         | Signature               | Description                                                                                               |
+| -------------- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
+| `register`     | `(tab: MlvTab): void`   | Appends the tab to the `tabs` signal. Called by `MlvTab.ngOnInit`.                                        |
+| `unregister`   | `(tab: MlvTab): void`   | Removes the tab and clears `forcedVisibleValue` if it matched the removed tab's value. Called on destroy. |
+| `forceVisible` | `(value: string): void` | Sets `forcedVisibleValue` to the given value (swaps it into visible area).                                |
+
+---
+
+## Injection Token
+
+### `TAB_GROUP`
+
+```ts
+const TAB_GROUP = new InjectionToken<MlvTabGroupAccessor>('TAB_GROUP');
+```
+
+Provided via `useExisting: MlvTabGroup` inside `MlvTabGroup.providers`. Allows deeply nested components to access the parent tab group without importing `MlvTabGroup` directly.
+
+**`MlvTabGroupAccessor` interface:**
+
+```ts
+interface MlvTabGroupAccessor {
+  readonly activeTab: Signal<string>;
+  readonly orientation: Signal<MlvTabOrientation>;
+  selectTab(value: string): void;
+  isActive(value: string): boolean;
+}
+```
+
+---
+
+## Usage Examples
+
+### Basic horizontal tabs
+
+```html
+<mlv-tab-group [(activeTab)]="selectedTab">
+  <mlv-tab value="overview">
+    <ng-template mlvTabDef>Overview</ng-template>
+    <ng-template mlvTabContent>
+      <p>Overview content</p>
+    </ng-template>
+  </mlv-tab>
+
+  <mlv-tab value="details">
+    <ng-template mlvTabDef>Details</ng-template>
+    <ng-template mlvTabContent>
+      <p>Details content</p>
+    </ng-template>
+  </mlv-tab>
+
+  <mlv-tab value="history" [disabled]="true">
+    <ng-template mlvTabDef>History</ng-template>
+    <ng-template mlvTabContent>
+      <p>History content</p>
+    </ng-template>
+  </mlv-tab>
+</mlv-tab-group>
+```
+
+### Vertical tabs
+
+```html
+<mlv-tab-group orientation="vertical" [(activeTab)]="selectedTab">
+  <!-- ... mlv-tab children ... -->
+</mlv-tab-group>
+```
+
+### Boxed appearance (Phase A)
+
+`appearance` is orthogonal to `orientation` — combine freely:
+
+```html
+<mlv-tab-group appearance="boxed" [(activeTab)]="selectedTab">
+  <!-- ... mlv-tab children ... -->
+</mlv-tab-group>
+
+<!-- boxed + vertical -->
+<mlv-tab-group appearance="boxed" orientation="vertical" [(activeTab)]="selectedTab">
+  <!-- ... -->
+</mlv-tab-group>
+```
+
+### Content density
+
+```html
+<mlv-tab-group mlvDensity="compact" [(activeTab)]="selectedTab">
+  <!-- ... -->
+</mlv-tab-group>
+```
+
+### Routable tabs (Phase A2)
+
+Put Angular's native `[routerLink]` on `<mlv-tab>`; the active tab is derived from the URL. Import `RouterLink` in the consuming component. `linkActiveOptions` mirrors `RouterLinkActive.routerLinkActiveOptions`:
+
+```html
+<mlv-tab-group appearance="boxed">
+  <mlv-tab value="examples" routerLink="/button" [linkActiveOptions]="{ exact: true }">
+    <ng-template mlvTabDef>Examples</ng-template>
+    <ng-template mlvTabContent>…</ng-template>
+  </mlv-tab>
+  <mlv-tab value="api" routerLink="/button/api">
+    <ng-template mlvTabDef>API</ng-template>
+    <ng-template mlvTabContent>…</ng-template>
+  </mlv-tab>
+</mlv-tab-group>
+```
+
+Tabs with **no** `routerLink` keep today's click-driven `activeTab` behaviour (this is the default — every existing consumer is unaffected).
+
+### Detecting overflow context in tab label
+
+The `$implicit` variable in `mlvTabDef` is `true` when the tab is rendered inside the overflow popup:
+
+```html
+<mlv-tab value="reports">
+  <ng-template mlvTabDef let-hidden> @if (hidden) { Rep. } @else { Reports } </ng-template>
+  <ng-template mlvTabContent>...</ng-template>
+</mlv-tab>
+```
+
+### Importing in a standalone component
+
+```ts
+import { MlvTabGroup, MlvTab, MlvTabDef, MlvTabContentDef } from '@malva-ui/core/tabs';
+
+@Component({
+  imports: [MlvTabGroup, MlvTab, MlvTabDef, MlvTabContentDef],
+  // ...
+})
+export class MyComponent {}
+```
+
+---
+
+## Dependencies
+
+| Dependency              | Usage                                                                                                                                                                                |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `@angular/core`         | Signals, DI, component lifecycle                                                                                                                                                     |
+| `@angular/common`       | `NgTemplateOutlet`                                                                                                                                                                   |
+| `@malva-ui/cdk/density` | `MlvDensityDirective` (host directive) + `MLV_DENSITY_ELEMENT` — `mlvDensity` input on `mlv-tab-group`                                                                               |
+| `@angular/router`       | (Phase A2) `Router` / `NavigationEnd` (routed-mode active detection + navigation) in `mlv-tab-group`; `RouterLink` optionally self-injected by `mlv-tab` as a URL carrier            |
+| `@angular/aria/tabs`    | `Tabs` / `TabList` / `Tab` / `TabPanel` / `TabContent` (`ngTabs`/`ngTabList`/`ngTab`/`ngTabPanel`/`ngTabContent`) — headless roving focus, selection and ARIA wiring for the tablist |
+| `@malva-ui/core/popup`  | `MlvPopup`, `MlvPopupContent`, `MlvPopupTrigger` — used for the overflow "More" popup                                                                                                |
+| `@malva-ui/core/list`   | `MlvList`, `MlvListItem` — used to render items in the overflow popup                                                                                                                |