@malva-ui/core 0.1.12 → 0.1.14

package/docs/ai/select.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-`@malva-ui/core/select` provides a fully-featured, accessible dropdown select component for Angular forms. It wraps the popup and dropdown infrastructure to deliver single/multiple selection, custom option rendering, automatic positioning, and signal/reactive/template-driven forms integration.
+`@malva-ui/core/select` provides a fully-featured, accessible dropdown select component for Angular forms. It wraps the popup and dropdown infrastructure to deliver single/multiple selection, custom option rendering, optional native select behavior, automatic positioning, and signal/reactive/template-driven forms integration.
 
 The library is generic (`MlvSelect<T>`) so it can work with any data type and accepts a transform function to convert raw values into displayable options.
 
@@ -19,7 +19,7 @@ Exported from `@malva-ui/core/select`:
 | `MlvSelectListTemplate`       | Directive class                                      | Marks an `<ng-template>` as the full list template (selector-only marker)                                           |
 | `MlvSelectItemTemplate`       | Directive class                                      | Marks an `<ng-template>` as the per-item template inside the dropdown                                               |
 | `MlvSelectSelectedTemplate`   | Directive class                                      | Marks an `<ng-template>` as the selected-value display template in the trigger                                      |
-| `MlvSelectOption<T>`          | Interface (re-export from `@malva-ui/core/dropdown`) | `{ label: string; value: T; group?: string }` (`group` clusters options under sticky headers)                       |
+| `MlvSelectOption<T>`          | Interface (re-export from `@malva-ui/core/dropdown`) | `{ label: string; value: T; group?: string; disabled?: boolean }` (`group` clusters options under sticky headers) |
 | `MlvSelectOptionTransform<T>` | Type (re-export from `@malva-ui/core/dropdown`)      | `(item: T) => MlvSelectOption<T>`                                                                                   |
 | `defaultOptionTransform`      | Function (re-export from `@malva-ui/core/dropdown`)  | Default transform: `String(item)` → label                                                                           |
 | `resolveOptions`              | Function (re-export from `@malva-ui/core/dropdown`)  | Maps a raw array through a transform function                                                                       |
@@ -58,8 +58,9 @@ Exported from `@malva-ui/core/select`:
 | `searchable`        | `BooleanInput`                                                                                             | `false`                  | Renders a search field as the first row of the open dropdown — pinned above the option list, so it never scrolls away — moves the combobox semantics onto it while open, and switches navigation to the activedescendant model. See _Searchable dropdown_.                |
 | `searchPlaceholder` | `string \| undefined`                                                                                      | `undefined`              | Placeholder of the in-dropdown search field. Falls back to `MLV_SELECT_I18N.searchPlaceholder` (`'Search...'`).                                                                                                                                                           |
 | `matcher`           | `MlvOptionMatcher<T> \| undefined`                                                                         | shared substring matcher | Custom local-filter predicate (fuzzy / secondary-field). Threaded into the shared `filterOptions`; results are always ranked prefix-matches-first. **Ignored for remote sources**, which own their filtering. Mirrors `mlv-combobox`'s / `[mlvAutocompleteMatcher]`.      |
-| `ariaLabel`         | `string \| undefined`                                                                                      | `undefined`              | Accessible name for the combobox trigger when no visible `label` is rendered                                                                                                                                                                                              |
+| `ariaLabel`         | `string \| undefined`                                                                                      | `undefined`              | Accessible name for the combobox trigger when no visible `label` is rendered. Also (via `_panelAriaLabel`) names the dropdown panel's `role="listbox"` — see _Dropdown panel accessible name_.                                                                            |
 | `multiple`          | `boolean`                                                                                                  | `false`                  | Enables multi-selection mode                                                                                                                                                                                                                                              |
+| `native`            | `boolean \| 'auto'`                                                                                       | `false`                  | Renders a transparent, interactive native `<select>` over the visual trigger. `true` always uses it; `'auto'` uses it below the `md` breakpoint; a bare `native` attribute means `true`. Native choices come from `[options]`; custom item and selected-value templates are ignored, and only native `<option>` / `<optgroup>` content is rendered. |
 | `placeholder`       | `string`                                                                                                   | `'Select...'`            | Placeholder text shown when no value is selected                                                                                                                                                                                                                          |
 | `toOption`          | `MlvSelectOptionTransform<T>`                                                                              | `defaultOptionTransform` | Function mapping a raw item to `{ label, value }`                                                                                                                                                                                                                         |
 | `compareWith`       | `(a: T, b: T) => boolean`                                                                                  | reference equality       | Equality used to match option values against the selection and against externally written values. Threaded into `MlvSelectionService.compareWith` and used by the reconciliation guard. See _Value ↔ options normalisation_.                                             |
@@ -76,6 +77,8 @@ Exported from `@malva-ui/core/select`:
 | Member                                   | Kind                   | Description                                                                                                                                                                |
 | ---------------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `resolvedOptions`                        | `computed`             | `_adapter.items()` mapped through `toOption()`                                                                                                                             |
+| `_nativeActive` (protected)              | `computed`             | Whether the transparent native select is active: always for `native=true`, below `md` for `native='auto'`, never for `false`                                               |
+| `_nativeOptionGroups` (protected)        | `computed`             | Normalized `[options]` values grouped into native `<optgroup>` / `<option>` structures                                                                                       |
 | `filteredOptions`                        | `computed`             | The options actually rendered in the panel: `resolvedOptions` filtered by `searchQuery` while **searchable + local**, `resolvedOptions` as-is otherwise                    |
 | `searchQuery`                            | `signal<string>`       | Text of the in-dropdown search field; always `''` while closed (the close resets it)                                                                                       |
 | `isOpen`                                 | `signal<boolean>`      | Tracks whether the dropdown popup is visible                                                                                                                               |
@@ -119,7 +122,7 @@ class="mlv-select"
 2. `<mlv-label>` — rendered when `label()` or `hint()` is set; clicking focuses the trigger.
 3. `<ng-template mlvFormControlWrapperControl>` — projects the control itself:
    - `<mlv-popup-container>` — CDK overlay anchor.
-   - `.mlv-select__trigger` — `div[role="combobox"]` with:
+   - `.mlv-select__trigger` — visual trigger (`div[role="combobox"]` in custom mode) with:
      - `[hostRole]="_outerIsCombobox() ? 'combobox' : 'button'"` — the role steps down to `button` while the **searchable** dropdown is open (the search input is the combobox then). `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`, `aria-disabled`, `aria-labelledby`/`aria-label` and `aria-describedby` are unconditional (all valid on either role); only `aria-required` is gated on `_outerIsCombobox()` — the search `mlv-input` takes it over via `[required]="required()"` while it owns the role.
      - `mlvResizeObserver` — tracks trigger width.
      - `mlvClick` — handles click-to-toggle.
@@ -127,6 +130,7 @@ class="mlv-select"
      - `aria-busy` while `_awaitingValueLabel()`.
      - Shows the i18n `loading` text while `_awaitingValueLabel()`, otherwise `selectedTemplate` / plain text when a value is selected, otherwise the placeholder.
      - A chevron arrow SVG (rotates 180° when open) — replaced by an `mlv-loader` spinner while `_awaitingValueLabel()`.
+   - `.mlv-select__native` — real native `<select>` rendered when `_nativeActive()` is true. It is positioned over the visual trigger with `opacity: 0`, so it remains the focusable/clickable interaction surface while the styled trigger stays visible. It renders normalized `[options]` as `<option>` / `<optgroup>` and does not render custom templates.
    - `<mlv-popup>` — the popup overlay bound to `isOpen`, with `(afterOpened)="_onPopupOpened()"` (focus handoff to the search field) and `(afterClosed)="_onPopupClosed()"` (focus restore + search reset).
      - `<ng-template mlvPopupPinnedContent>` — stamped only when `searchable()` — carries `.mlv-select__search` (a `lucideSearch` icon + a `bare` `mlv-input`). The popup renders it as `.mlv-popup__pinned`, **above** its scroll region, so the search row is the dropdown's first row and stays put however far the options scroll.
      - `<ng-template mlvPopupContent>` stamps `.mlv-select__panel` — a `(mousedown)="_onPanelMousedown($event)"` wrapper — around `<mlv-dropdown-panel scrollMode="parent">`, so the option list delegates to the popup's themed scrollbar instead of creating a nested scroll region. The panel receives `[options]="filteredOptions()"`, `[focusMode]="searchable() ? 'activedescendant' : 'roving'"`, `[activeIndex]="_activeIndex()"`, `[highlightQuery]="_highlightQuery()"`, `[loading]="_panelLoading()"`, `[loadingText]="_i18n().loading"`, `[hasMore]="_adapter.hasMore()"`, `[loadingMore]="_adapter.loadingMore()"` and `(loadMore)="_adapter.loadMore()"`; when `searchable()` it also projects the `.mlv-select__empty` no-results row.
@@ -338,7 +342,7 @@ Internal `@malva-ui/*` libraries:
 - `@malva-ui/core/loader` — `MlvLoader` (the loading variant's circular spinner in place of the chevron)
 - `@malva-ui/i18n` — `MLV_SELECT_I18N` (`placeholder`, `searchPlaceholder`, `noResults`, `loading`, `resultsAvailable`), `MLV_FORM_UTILS_I18N` (`clear`), `MlvI18nResolverService` (the ICU `resultsAvailable`)
 - `@malva-ui/cdk/accessibility` — `MlvClick`
-- `@malva-ui/cdk/utils` — `MlvResizeObserver`
+- `@malva-ui/cdk/utils` — `MlvResizeObserver`, `MlvBreakpointService` (responsive `native='auto'` mode)
 - `@malva-ui/styles` — SCSS mixins (`mixins.base()`)
 
 Angular / third-party:
@@ -357,6 +361,7 @@ Angular / third-party:
 - Closed-trigger keyboard: ArrowUp / ArrowDown / Home / End open the dropdown (shared `_openFromKey`; no-op while inert). The focus-first request runs in roving mode only — a searchable dropdown hands focus to its search field instead.
 - A polite `aria-live` status region (`.mlv-select__sr-status`) announces the filtered result count / "No results" while the searchable dropdown is open — both resolved from `MLV_SELECT_I18N` (`resultsAvailable` is an ICU plural). It is empty while closed or non-searchable, so no stale count is read out.
 - The loading variant sets `aria-busy` on the trigger and gives the `mlv-loader` an `ariaLabel` from `MLV_SELECT_I18N.loading`. The trigger is **not** disabled — it keeps `tabindex="0"` and stays reachable and readable to AT while its value resolves; only the open paths are suppressed.
+- Native mode keeps the real `<select>` as the only exposed focus target. The styled trigger is `aria-hidden`, disabled, and removed from the tab order while the transparent native control carries the field's label, description, and value interaction. Native controls are intentionally opacity-hidden rather than `visibility: hidden`, because they must remain focusable and clickable.
 
 ---
 
@@ -481,6 +486,20 @@ Tab prevents its default deliberately: the search field lives in a **detached ov
 
 > **A non-searchable select is untouched.** No search row, no `__empty` projection, roving focus (`activeIndex` pinned to `-1`, `highlightQuery` empty), the trigger keeps its combobox role at all times, and `filteredOptions` is `resolvedOptions`.
 
+## Native select mode
+
+Set `native` to `true` when the browser's native options picker is preferred (particularly on mobile), or to `'auto'` to use it below the shared `md` breakpoint. A bare `native` attribute is shorthand for `native="true"`; the default is `false`.
+
+Native mode uses the component's normalized `[options]` data. A `group` becomes an `<optgroup>`, and `disabled` becomes a disabled `<option>`. `MlvSelectItemTemplate` and `MlvSelectSelectedTemplate` are ignored in this mode because native controls only render their native option content.
+
+```html
+<!-- Native picker on every viewport -->
+<mlv-select native label="Country" [options]="countries" [(value)]="country" />
+
+<!-- Native picker below md; custom dropdown above md -->
+<mlv-select native="auto" label="Country" [options]="countries" [(value)]="country" />
+```
+
 ---
 
 ## Testing
@@ -510,3 +529,9 @@ The dropdown `mlv-popup` is wired to `[mobileMode]="mobileMode()"` (default `'au
 - Inherited `required` renders the `mlv-label` marker and sets `aria-required` on the trigger — and, while a **searchable** dropdown is open, on the in-dropdown search input instead (the element that owns `role="combobox"` then).
 - Inherited `description` renders `<mlv-description>` below the control; the trigger's `aria-describedby` is the base's `_describedBy()`.
 - `<mlv-message>` now carries `_messageId()`, so the describedby reference resolves.
+
+---
+
+## Dropdown panel accessible name (2026-08)
+
+`mlv-dropdown-panel`'s inner `role="listbox"` is an ARIA input field (axe `aria-input-field-name`, WCAG 4.1.2) and needs its own accessible name — it is not implicitly named by the trigger it belongs to. `mlv-select` binds `[ariaLabel]="_panelAriaLabel()"` on its `<mlv-dropdown-panel>`, where `_panelAriaLabel` mirrors the trigger's own resolution: the visible `label` when set, else the explicit `ariaLabel` input — `null` when neither is set (same as an unlabelled trigger, an existing condition outside this fix's scope). Mirrors `mlv-combobox` and `mlv-filter` (which passes its field `label` directly).

package/docs/ai/sidebar.md

@@ -17,7 +17,7 @@ Exported from `@malva-ui/core/sidebar`:
 | `MlvSidebarGroup` | Component | Collapsible group with `mlv-expand` accordion + `mlv-popup` flyout — `mlv-sidebar-group` |
 | `MlvSidebarItem` | Component | Individual navigation item — `mlv-sidebar-item` |
 | `MlvSidebarRail` | Component | Drag-to-resize rail with snap-to-collapse — `mlv-sidebar-rail` |
-| `MlvSidebarTrigger` | Component | Toggle button for collapsing/expanding the sidebar — `mlv-sidebar-trigger` |
+| `MlvSidebarTrigger` | Component | Toggle button for collapsing/expanding the sidebar, exposing `focusTarget()`, `offcanvasFocusTarget()`, and a disposal-time `restoreFocusResolver` — `mlv-sidebar-trigger` |
 | `MlvSidebarWorkspace` | Component | Styled active-workspace row and multi-workspace menu — `mlv-sidebar-workspace` |
 | `MlvSidebarWorkspaceLogo` | Structural directive | Custom logo template reused by the trigger and menu options — `[mlvSidebarWorkspaceLogo]` |
 | `MlvSidebarWorkspaceText` | Structural directive | Custom text template reused by the trigger and menu options — `[mlvSidebarWorkspaceText]` |
@@ -31,6 +31,7 @@ Exported from `@malva-ui/core/sidebar`:
 | `MlvSidebarContent` | Component | Scrollable main content region backed by `mlv-scrollbar` — `[mlvSidebarContent]` |
 | `SidebarContentDirective` | Compatibility alias | Backwards-compatible export alias for `MlvSidebarContent` |
 | `MlvSidebarMode` | Type | `'icon' \| 'offcanvas' \| 'floating' \| 'fixed'` |
+| `MlvSidebarAppearance` | Type | `'raised' \| 'flat'` outer surface treatment for an inline Sidebar |
 | `MlvSidebarContextValue` | Interface | Shape of the value provided via `SIDEBAR_CONTEXT` |
 | `SIDEBAR_CONTEXT` | Injection Token | `InjectionToken<MlvSidebarContextValue>` — carries collapsed/mode/toggle/setWidth to descendants |
 
@@ -47,17 +48,19 @@ Exported from `@malva-ui/core/sidebar`:
 
 #### Inputs / Models
 
-| Name             | Kind      | Type                    | Default     | Description                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ---------------- | --------- | ----------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `collapsed`      | `model()` | `boolean`               | `false`     | Two-way bindable collapsed state. In `fixed` mode this is always treated as false. **Intentionally named `collapsed`, not `opened`** — it models rail collapse/expand (a persistent layout state), a distinct concept from the transient open/close of overlay surfaces (`mlv-drawer`/`mlv-popup`/`mlv-expand`, and the dialog's `[(mlvDialog)]`). It is deliberately excluded from the `opened` naming normalization. |
-| `width`          | `model()` | `string`                | `'260px'`   | Total expanded host width, including border and padding. Two-way bindable and updated by `setWidth()` during rail drag.                                                                                                                                                                                                                                                                                                |
-| `collapsedWidth` | `input()` | `string`                | `'56px'`    | Total collapsed host width, including border and padding.                                                                                                                                                                                                                                                                                                                                                              |
-| `mode`           | `input()` | `MlvSidebarMode`        | `'icon'`    | Layout mode requested by the author: `'icon'`, `'offcanvas'`, `'floating'`, or `'fixed'`. Read `effectiveMode()` for the mode actually in effect.                                                                                                                                                                                                                                                                      |
-| `collapseBelow`  | `input()` | `MlvBreakpoint \| null` | `null`      | Viewport breakpoint below which the sidebar behaves as an offcanvas drawer regardless of `mode`. See **Responsive usage**.                                                                                                                                                                                                                                                                                             |
-| `ariaLabel`      | `input()` | `string \| undefined`   | `undefined` | Accessible name for the `navigation` landmark. Falls back to `MLV_SIDEBAR_I18N.navigation`. A plain `aria-label` **attribute** on `<mlv-sidebar>` does not work — the host binding owns that attribute — so use this input when a page has more than one sidebar.                                                                                                                                                      |
-| `fullHeight`     | `input()` | `BooleanInput`          | `false`     | When true, sidebar uses `position: sticky` at full viewport height.                                                                                                                                                                                                                                                                                                                                                    |
-| `minWidth`       | `input()` | `number`                | `200`       | Minimum width in px during drag resize.                                                                                                                                                                                                                                                                                                                                                                                |
-| `maxWidth`       | `input()` | `number`                | `480`       | Maximum width in px during drag resize.                                                                                                                                                                                                                                                                                                                                                                                |
+| Name                | Kind      | Type                    | Default     | Description                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ------------------- | --------- | ----------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `collapsed`         | `model()` | `boolean`               | `false`     | Two-way bindable collapsed state. In `fixed` mode this is always treated as false. **Intentionally named `collapsed`, not `opened`** — it models rail collapse/expand (a persistent layout state), a distinct concept from the transient open/close of overlay surfaces (`mlv-drawer`/`mlv-popup`/`mlv-expand`, and the dialog's `[(mlvDialog)]`). It is deliberately excluded from the `opened` naming normalization. |
+| `width`             | `model()` | `string`                | `'260px'`   | Total expanded host width, including border and padding. Two-way bindable and updated by `setWidth()` during rail drag.                                                                                                                                                                                                                                                                                                |
+| `collapsedWidth`    | `input()` | `string`                | `'56px'`    | Total collapsed host width, including border and padding.                                                                                                                                                                                                                                                                                                                                                              |
+| `mode`              | `input()` | `MlvSidebarMode`        | `'icon'`    | Layout mode requested by the author: `'icon'`, `'offcanvas'`, `'floating'`, or `'fixed'`. Read `effectiveMode()` for the mode actually in effect.                                                                                                                                                                                                                                                                      |
+| `appearance`        | `input()` | `MlvSidebarAppearance`  | `'raised'`  | Outer surface treatment for an inline Sidebar. `'flat'` removes only the outer radius and shadow; the border and background remain.                                                                                                                                                                                                                                                                                    |
+| `collapseBelow`     | `input()` | `MlvBreakpoint \| null` | `null`      | Viewport breakpoint below which the sidebar behaves as an offcanvas drawer regardless of `mode`. See **Responsive usage**.                                                                                                                                                                                                                                                                                             |
+| `closeOnActivation` | `input()` | `BooleanInput`          | `false`     | When opted in, activating an enabled projected button, link, `role="button"`, or menu item closes an open offcanvas Sidebar. Inline modes and non-interactive projected content are unaffected.                                                                                                                                                                                                                        |
+| `ariaLabel`         | `input()` | `string \| undefined`   | `undefined` | Accessible name for the `navigation` landmark. Falls back to `MLV_SIDEBAR_I18N.navigation`. A plain `aria-label` **attribute** on `<mlv-sidebar>` does not work — the host binding owns that attribute — so use this input when a page has more than one sidebar.                                                                                                                                                      |
+| `fullHeight`        | `input()` | `BooleanInput`          | `false`     | When true, sidebar uses `position: sticky` at full viewport height.                                                                                                                                                                                                                                                                                                                                                    |
+| `minWidth`          | `input()` | `number`                | `200`       | Minimum width in px during drag resize.                                                                                                                                                                                                                                                                                                                                                                                |
+| `maxWidth`          | `input()` | `number`                | `480`       | Maximum width in px during drag resize.                                                                                                                                                                                                                                                                                                                                                                                |
 
 The two models emit `collapsedChange` and `widthChange` (the `model()` change outputs — there are no separate `output()` declarations).
 
@@ -74,6 +77,8 @@ host: {
   class: 'mlv-sidebar',
   '[class.mlv-sidebar--collapsed]': '_effectiveCollapsed()',
   '[class]': '"mlv-sidebar--" + effectiveMode()',
+  '[class.mlv-sidebar--raised]': 'appearance() === "raised"',
+  '[class.mlv-sidebar--flat]': 'appearance() === "flat"',
   '[class.mlv-sidebar--full-height]': 'fullHeight()',
   '[style.--mlv-sidebar-expanded-width]': 'width()',
   '[style.--mlv-sidebar-collapsed-width]': 'collapsedWidth()',
@@ -99,10 +104,13 @@ Provides itself as `SIDEBAR_CONTEXT` so all descendant groups and items can inje
 
 #### Protected handlers (template-facing, not public API)
 
-| Method                  | Signature                 | Description                                                                                                                                                                                                                                               |
-| ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `onContainerKeydown`    | `(event: Event): void`    | Handles `ArrowDown`/`ArrowUp` on the container to move focus between `mlv-sidebar-item`, `.mlv-sidebar-group__header`, `.mlv-sidebar-group__icon-btn`, and `button` elements in DOM order (wraps around). Skips elements inside `.cdk-overlay-container`. |
-| `_onDrawerOpenedChange` | `(opened: boolean): void` | Syncs the drawer's open/close state back to the `collapsed` model (offcanvas mode).                                                                                                                                                                       |
+| Method                      | Signature                   | Description                                                                                                                                                                                                                                               |
+| --------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `onContainerKeydown`        | `(event: Event): void`      | Handles `ArrowDown`/`ArrowUp` on the container to move focus between `mlv-sidebar-item`, `.mlv-sidebar-group__header`, `.mlv-sidebar-group__icon-btn`, and `button` elements in DOM order (wraps around). Skips elements inside `.cdk-overlay-container`. |
+| `_onContainerClick`         | `(event: MouseEvent): void` | With `closeOnActivation`, closes an open offcanvas Sidebar after a real enabled projected action bubbles through the shared container.                                                                                                                    |
+| `_onDrawerOpenedChange`     | `(opened: boolean): void`   | Syncs the drawer's open/close state back to the `collapsed` model (offcanvas mode).                                                                                                                                                                       |
+| `_shouldRestoreDrawerFocus` | `(): boolean`               | Restores the external trigger for normal activation, but lets a newly opened `dialog` or `alertdialog` retain focus.                                                                                                                                      |
+| `_onDrawerAfterClosed`      | `(): void`                  | Clears activation-specific state and reasserts focus inside a still-open modal after Drawer disposal removes the projected opener.                                                                                                                        |
 
 #### Internal Computed Signals
 
@@ -120,7 +128,7 @@ A constructor `effect` watches `_isBelowCollapseBreakpoint`: entering the respon
 Uses `@if (effectiveMode() === 'offcanvas')` to branch between two layouts:
 
 - **Shared body template:** The `.mlv-sidebar__container` (with the single `<ng-content />` projection slot) is declared once in a `#body` `<ng-template>` and rendered via `[ngTemplateOutlet]` in both branches. This avoids two default `<ng-content>` slots (Angular projects into only the last), which previously left the offcanvas drawer empty. The host owns width; the inner container remains `width: 100%` and clips trailing content during animation.
-- **Offcanvas branch:** Wraps the shared body outlet in `<mlv-drawer>`'s **`<ng-template mlvDrawerContent>`** (required — `MlvDrawer` only renders content projected through `MlvDrawerContent`). Drawer is bound `[opened]="!_effectiveCollapsed()"`, `position="left"`, `[size]="width()"`, `[hasBackdrop]="true"`. The drawer's `openedChange` syncs back to `collapsed` via `_onDrawerOpenedChange`; its `cdkTrapFocusAutoCapture` moves focus into the panel on open and Escape/backdrop close it.
+- **Offcanvas branch:** Wraps the shared body outlet in `<mlv-drawer>`'s **`<ng-template mlvDrawerContent>`** (required — `MlvDrawer` only renders content projected through `MlvDrawerContent`). Drawer is bound `[opened]="!_effectiveCollapsed()"`, `position="left"`, `[size]="width()"`, `[hasBackdrop]="true"`. The drawer's `openedChange` syncs back to `collapsed` via `_onDrawerOpenedChange`; its `cdkTrapFocusAutoCapture` moves focus into the panel on open and Escape/backdrop close it. With `closeOnActivation`, an enabled projected action also closes it; the external trigger regains focus unless that activation opened a `dialog` or `alertdialog`. In that composed case Drawer restoration is suppressed and focus is reasserted in the connected modal after the projected opener is disposed.
 - **Default branch:** Renders the shared body directly. The host toggles between the expanded and collapsed width custom properties.
 
 Both branches project `<ng-content />` and handle `(keydown)="onContainerKeydown($event)"` for arrow-key focus management.
@@ -128,14 +136,15 @@ Both branches project `<ng-content />` and handle `(keydown)="onContainerKeydown
 #### Inline Style Summary
 
 - **Block `.mlv-sidebar`:** owns the animated total width and exposes `--mlv-sidebar-expanded-width`, `--mlv-sidebar-collapsed-width`, `--mlv-sidebar-gutter`, `--mlv-sidebar-border-width`, derived `--mlv-sidebar-icon-column-width`, `--mlv-sidebar-row-height`, and the three state-surface variables (`--mlv-sidebar-hover-bg`, `--mlv-sidebar-active-bg`, `--mlv-sidebar-rail-color` — see **State surfaces**). The icon column is `collapsedWidth - (2 × gutter) - (2 × border)` and is shared by item, group, project-selector, header, and footer icon containers.
-- **`--mlv-sidebar-row-height`** (default `2.25rem`) is the single source of truth for the height of every navigable row — `mlv-sidebar-item`, `.mlv-sidebar-group__header`, `.mlv-sidebar-group__icon-btn`, and `.mlv-sidebar-trigger__btn` all resolve `min-height: var(--mlv-sidebar-row-height, 2.25rem)`, so a mixed list keeps one rhythm. It is density-aware on the sidebar block: tight `1.875rem`, compact `--mlv-height-xs`, comfortable (default) `2.25rem`, spacious `--mlv-height-s`, airy `--mlv-height-m`. The icon column deliberately does **not** scale with density — it stays derived from `collapsedWidth`.
+- **`--mlv-sidebar-row-height`** (default `2.25rem`) is the single source of truth for the height of every navigable row — `mlv-sidebar-item`, `.mlv-sidebar-group__header`, `.mlv-sidebar-group__icon-btn`, and `.mlv-sidebar-trigger__btn` all resolve `min-height: var(--mlv-sidebar-row-height, 2.25rem)`, so a mixed list keeps one rhythm. It is density-aware on the sidebar block: tight `var(--mlv-spacing-6)` (1.5rem/24px — off the height ramp by design, one step under compact so the order holds now that `--mlv-height-xs` is 28px), compact `--mlv-height-xs`, comfortable (default) `2.25rem`, spacious `--mlv-height-s`, airy `--mlv-height-m`. The icon column deliberately does **not** scale with density — it stays derived from `collapsedWidth`.
 - **Element `.mlv-sidebar__container`:** flex column, `height: 100%`, `width: 100%`, `gap: 1px`, and `overflow: hidden`; it clips fading labels while the host's trailing edge contracts.
 - **Element `.mlv-sidebar__header`:** `flex-shrink: 0` — stays pinned at top.
 - **Element `.mlv-sidebar__content`:** `flex: 1 1 0`, `overflow: hidden`, `min-height: 0` — middle-region host whose internal `.mlv-sidebar__content-scrollbar` owns scrolling. Unslotted legacy content is wrapped by `.mlv-sidebar__scrollbar` at the sidebar level.
 - **Element `.mlv-sidebar__footer`:** `flex-shrink: 0` — stays pinned at bottom.
 - **Modifier `.mlv-sidebar--collapsed`:** switches only the host width. Descendant icon tracks remain start-anchored at the same derived width while labels fade and become `visibility: hidden` after the transition.
+- **Modifier `.mlv-sidebar--flat`:** removes only the inline sidebar's outer radius and shadow (`--mlv-shadow-flat`); its border and raised background remain. Page Shell continues to own its chrome seam.
 - **Modifier `.mlv-sidebar--offcanvas`:** removes border, shadow, and padding, and collapses the host to `width: 0` (`flex: 0 0 auto`, `overflow: hidden`). The panel lives in a CDK overlay, so the host is only an anchor in the page flow — it previously claimed `width: 100%` and squeezed the content beside it, which also broke the layout the moment `collapseBelow` crossed its breakpoint.
-- **Modifier `.mlv-sidebar--floating`:** `position: absolute`, `z-index: 100`, elevated shadow (`--mlv-shadow-3`), `translateX(-100%)` when collapsed.
+- **Modifier `.mlv-sidebar--floating`:** `position: absolute`, `z-index: 100`, elevated shadow (`--mlv-shadow-overlay` — a side overlay per SL-R3), `translateX(-100%)` when collapsed.
 - **Modifier `.mlv-sidebar--full-height`:** `position: sticky`, full viewport height via `100dvh`, respects `--mlv-sidebar-offset-top` and `--mlv-sidebar-offset-bottom` CSS custom properties.
 - **Drawer context** (`.mlv-drawer .mlv-sidebar`): fills drawer width, forces labels visible.
 - **Reduced motion:** host, floating transform, label, badge, group heading, and trigger transitions use the instant duration when `prefers-reduced-motion: reduce` is active.
@@ -388,7 +397,7 @@ count is not folded in — prefer the input-based path for full a11y of the coun
 - **Element `__badge`:** trailing badge with the same opacity/delayed-visibility behavior.
 - **Element `__status`:** `position: absolute`, top-right (`0.1875rem`), `pointer-events: none` — collapsed-rail status dot overlaying the icon.
 - **Element `__tooltip`:** absolute, right of item, hidden (`opacity: 0`), shown on hover/focus-visible in collapsed mode.
-- **Modifier `--active`:** action text color + `font-weight: 600` on the modifier, plus the active pill (`--mlv-sidebar-active-bg`, default `--mlv-background-accent-1-pale`) written against the block class so it survives `:hover`. See **State surfaces**.
+- **Modifier `--active`:** `--mlv-text-on-selected` + `font-weight: 600` on the modifier, plus the active pill (`--mlv-sidebar-active-bg`, default `--mlv-background-selected`) written against the block class so it survives `:hover`. Selection is its own token (SF-R1) — never the pressed `-active` fill. See **State surfaces**.
 - **Modifier `--collapsed`:** leaves the icon track unchanged; disables interaction on the label and fades trailing content while the sidebar container clips it.
 
 ---
@@ -468,6 +477,14 @@ Toggle button that collapses/expands the sidebar. Renders a plain transparent ic
 | --------- | ------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `sidebar` | `MlvSidebarContextValue \| undefined` | `undefined` | The sidebar to control when the trigger is rendered **outside** `<mlv-sidebar>` — pass the sidebar's template reference (`<mlv-sidebar #nav />` → `[sidebar]="nav"`). Required for any sidebar that can become an offcanvas drawer: a closed drawer renders none of its projected content, so a nested trigger disappears with it. Falls back to the ancestor `SIDEBAR_CONTEXT`. |
 
+#### Public focus helpers
+
+| Member                   | Type                                | Description                                                                                                                                                                                             |
+| ------------------------ | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `focusTarget`            | `Signal<HTMLButtonElement \| null>` | The connected native trigger button, or `null` before its view exists. Pass it to an overlay's explicit restore-focus option when the activating offcanvas control disappears.                          |
+| `offcanvasFocusTarget()` | `HTMLButtonElement \| null`         | Point-in-time connected native trigger only while the sidebar's effective mode is `offcanvas`; otherwise `null`. Connectivity and effective mode are checked on every call.                             |
+| `restoreFocusResolver`   | `() => true \| HTMLButtonElement`   | Stable function for a dynamic Dialog restore option. At disposal it returns the connected external trigger in offcanvas mode, or `true` so Dialog uses its connected captured opener in an inline mode. |
+
 #### Host Bindings
 
 ```ts
@@ -665,7 +682,7 @@ export interface MlvSidebarContextValue {
 - `MlvSidebarGroup` — reads `parentCtx?.collapsed()` to switch between accordion and icon-button layouts.
 - `MlvSidebarItem` — reads `ctx?.collapsed()` and `ctx?.inFlyout?.()` to compute `isCollapsed`.
 - `MlvSidebarRail` — reads `collapsed()`, calls `toggle()` and `setWidth()` during drag/keyboard interactions.
-- `MlvSidebarTrigger` — reads `collapsed()` and `effectiveMode?.() ?? mode()`, calls `toggle()` on click. Injects the token **optionally** so it can be pointed at a sidebar with its `sidebar` input from outside the sidebar tree.
+- `MlvSidebarTrigger` — reads `collapsed()` and `effectiveMode?.() ?? mode()`, calls `toggle()` on click, and exposes its native button through `focusTarget()`, the point-in-time `offcanvasFocusTarget()`, and the stable disposal-time `restoreFocusResolver`. Injects the token **optionally** so it can be pointed at a sidebar with its `sidebar` input from outside the sidebar tree.
 
 ---
 
@@ -679,11 +696,11 @@ Three component-scoped variables declared on `.mlv-sidebar` (`sidebar.scss`)
 carry every state fill in the sidebar. They are the **only** supported seam for
 a host that paints the sidebar on its own chrome.
 
-| Variable                   | Default                               | Consumed by                                                                                                                                                                                                                 |
-| -------------------------- | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `--mlv-sidebar-hover-bg`   | `var(--mlv-background-neutral-1)`     | `mlv-sidebar-item:hover/:focus-visible`, `.mlv-sidebar-group__header:hover/:focus-visible`, `.mlv-sidebar-group__icon-btn:hover/:focus-visible`, `.mlv-sidebar-trigger__btn:hover`, `.mlv-sidebar-workspace__trigger:hover` |
-| `--mlv-sidebar-active-bg`  | `var(--mlv-background-accent-1-pale)` | `.mlv-sidebar-item--active` and `.mlv-sidebar-group__icon-btn--active` (both including their `:hover`/`:focus-visible` states)                                                                                              |
-| `--mlv-sidebar-rail-color` | `var(--mlv-border-normal)`            | `.mlv-sidebar-group__content.mlv-expand--open` tree line                                                                                                                                                                    |
+| Variable                   | Default                           | Consumed by                                                                                                                                                                                                                 |
+| -------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--mlv-sidebar-hover-bg`   | `var(--mlv-background-neutral-1)` | `mlv-sidebar-item:hover/:focus-visible`, `.mlv-sidebar-group__header:hover/:focus-visible`, `.mlv-sidebar-group__icon-btn:hover/:focus-visible`, `.mlv-sidebar-trigger__btn:hover`, `.mlv-sidebar-workspace__trigger:hover` |
+| `--mlv-sidebar-active-bg`  | `var(--mlv-background-selected)`  | `.mlv-sidebar-item--active` and `.mlv-sidebar-group__icon-btn--active` (both including their `:hover`/`:focus-visible` states)                                                                                              |
+| `--mlv-sidebar-rail-color` | `var(--mlv-border-normal)`        | `.mlv-sidebar-group__content.mlv-expand--open` tree line                                                                                                                                                                    |
 
 **Why they exist.** The three globals resolve against the _page_ surface. A host
 that renders the sidebar on an arbitrary background — `mlv-page-shell` puts the
@@ -972,7 +989,7 @@ The `mlv-sidebar` landmark `aria-label` resolves through `MLV_SIDEBAR_I18N` (`@m
 Set **`collapseBelow`** (`MlvBreakpoint` = `'sm' | 'md' | 'lg'`, default `null` = off) and the sidebar owns the breakpoint itself — no `matchMedia` wiring, and the consumer never touches `mode`:
 
 ```html
-<mlv-sidebar #nav collapseBelow="md" [(collapsed)]="collapsed" ariaLabel="Product navigation">
+<mlv-sidebar #nav collapseBelow="md" closeOnActivation [(collapsed)]="collapsed" ariaLabel="Product navigation">
   <div mlvSidebarContent>…</div>
 </mlv-sidebar>
 
@@ -986,6 +1003,7 @@ Below the breakpoint:
 - The sidebar **closes itself** on entry (the previous `collapsed()` value is stored and restored when the viewport grows back past the breakpoint).
 - `mlv-sidebar-trigger` becomes a hamburger (`lucideMenu`) / close (`lucideX`) menu button, is no longer hidden by `mode="fixed"`, and is named `openNavigation`/`closeNavigation`.
 - Dismissal is the normal offcanvas behaviour inherited from `mlv-drawer`: Escape, backdrop click, or the trigger. The drawer captures focus on open and only mounts its content while open.
+- `closeOnActivation` is optional and defaults to `false`. When enabled, a projected navigation or action activation also dismisses the compact drawer; desktop/inline behavior is unchanged. Focus returns to the external trigger for ordinary navigation. An activation-opened `dialog` or `alertdialog` retains focus through Drawer disposal; configure that modal with `restoreFocus: externalTrigger.restoreFocusResolver` (pass the function, do not invoke it). Because Dialog samples it at disposal, a dialog that survives either breakpoint direction restores to the connected external trigger in offcanvas mode or its reconnected projected opener in inline mode. Detached and hidden stale targets are never selected.
 
 Thresholds come from `MLV_BREAKPOINT_CONFIG` (override with `provideMlvBreakpoints({ md, lg })`) so they stay in sync with the SCSS `breakpoint-*` mixins. Detection goes through `MlvBreakpointService` → CDK `BreakpointObserver`, which is SSR-safe: on the server it resolves to the initial `'sm'` tier instead of touching `matchMedia`.
 

package/docs/ai/switch.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-The Switch library (`@malva-ui/core/switch`) provides accessible toggle switch components implementing the WAI-ARIA switch pattern. Supports grouped switches with keyboard navigation and reactive forms integration via `ControlValueAccessor`.
+The Switch library (`@malva-ui/core/switch`) provides accessible toggle switch components implementing the WAI-ARIA switch pattern. Supports grouped switches with keyboard navigation, signal-forms integration, and the shared five-level density system (`tight` / `compact` / `comfortable` / `spacious` / `airy`) from `@malva-ui/cdk/density`.
 
 > **Host `aria-label` / `aria-labelledby` forwarding** — a consumer writing
 > `<mlv-switch aria-label="Enable feature" />` (a switch with no projected text)
@@ -52,14 +52,15 @@ Exported from `@malva-ui/core/switch`:
 
 #### Inputs
 
-| Name             | Type                  | Default     | Description                                                                                                                                                                                                                                      |
-| ---------------- | --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `disabled`       | `boolean`             | `false`     | Component-level disabled                                                                                                                                                                                                                         |
-| `state`          | `MlvSwitchState`      | `'default'` | Semantic state for track color                                                                                                                                                                                                                   |
-| `label`          | `string`              | `''`        | **Visible** label text, rendered inside the `<label>` when nothing is projected into `<mlv-switch>`. Projected content always wins (CSS `display: none`-s the fallback), so the accessible name never duplicates. Inherited from the signal base |
-| `required`       | `boolean` (coerced)   | `false`     | Sets `aria-required` on the native input; also a signal-forms field binding. Inherited from the signal base                                                                                                                                      |
-| `ariaLabel`      | `string \| null`      | `null`      | Accessible name applied to the inner native input; wins over a captured static host `aria-label`. Inherited from the signal base since 2026-08 (was a switch-local input)                                                                        |
-| `ariaLabelledBy` | `string \| undefined` | `undefined` | Id reference(s) naming the inner native input; same precedence as `ariaLabel`                                                                                                                                                                    |
+| Name             | Type                  | Default                     | Description                                                                                                                                                                                                                                                                                                                  |
+| ---------------- | --------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mlvDensity`     | `MlvDensity`          | inherited / `'comfortable'` | Density override for this switch (via the `MlvDensityDirective` host directive). All five levels scale track size, thumb size, thumb travel, label gap and label typography. Falls back to the nearest ancestor `MLV_DENSITY_CONTEXT` (e.g. an enclosing `mlv-switch-group` or `form[mlvForm]`), then to `MlvDensityService` |
+| `disabled`       | `boolean`             | `false`                     | Component-level disabled                                                                                                                                                                                                                                                                                                     |
+| `state`          | `MlvSwitchState`      | `'default'`                 | Semantic state for track color                                                                                                                                                                                                                                                                                               |
+| `label`          | `string`              | `''`                        | **Visible** label text, rendered inside the `<label>` when nothing is projected into `<mlv-switch>`. Projected content always wins (CSS `display: none`-s the fallback), so the accessible name never duplicates. Inherited from the signal base                                                                             |
+| `required`       | `boolean` (coerced)   | `false`                     | Sets `aria-required` on the native input; also a signal-forms field binding. Inherited from the signal base                                                                                                                                                                                                                  |
+| `ariaLabel`      | `string \| null`      | `null`                      | Accessible name applied to the inner native input; wins over a captured static host `aria-label`. Inherited from the signal base since 2026-08 (was a switch-local input)                                                                                                                                                    |
+| `ariaLabelledBy` | `string \| undefined` | `undefined`                 | Id reference(s) naming the inner native input; same precedence as `ariaLabel`                                                                                                                                                                                                                                                |
 
 #### Inputs (inherited from `MlvSignalFormUiControlBase`)
 
@@ -87,6 +88,8 @@ Exported from `@malva-ui/core/switch`:
 #### Host Bindings
 
 ```ts
+hostDirectives: [{ directive: MlvDensityDirective, inputs: ['mlvDensity'] }],
+providers: [{ provide: MLV_DENSITY_ELEMENT, useValue: 'switch' }, /* … */],
 host: {
   'class': 'mlv-switch',
   '[class.mlv-switch--disabled]': 'computedDisabled()',
@@ -94,6 +97,10 @@ host: {
 }
 ```
 
+`MlvDensityDirective` additionally stamps exactly one of
+`mlv-switch--tight | --compact | --comfortable | --spacious | --airy` on the host
+(from `MLV_DENSITY_ELEMENT: 'switch'`). Consumers set `mlvDensity`, never the class.
+
 The host is **not** focusable. The single focus target is the visually-hidden
 native `<input type="checkbox" role="switch">` (kept in the a11y tree via the
 clip-path pattern). Its `tabindex` is the roving tabindex managed by
@@ -133,10 +140,61 @@ A dev-mode `console.warn` fires once per instance when a switch has no projected
 
 #### Styles
 
-- Track: `40px × 24px`, `border-radius: 12px`
-- Thumb: `20px × 20px`, animates `translateX(16px)` when checked
-- Transition: `0.2s ease-in-out`
-- Uses `--mlv-border-normal`, `--mlv-background-accent-1`, `--mlv-background-base`
+Track is a stadium (`--mlv-radius-full`) at every step; the thumb is a circle
+inset by `--mlv-switch-thumb-inset` (`0.125rem`, constant). Colors:
+`--mlv-background-neutral-1` (off) → `--mlv-background-accent-1` (on),
+thumb `--mlv-elevation-bg-5` + `--mlv-shadow-1`, focus ring `--mlv-border-focus`
+promoted from the hidden input onto `.mlv-switch__track`.
+
+**2026-08-26:** in dark theme `--mlv-elevation-bg-5` follows the general
+elevation ladder (lightened grey, `color-mix` toward white off
+`--mlv-palette-neutral-700`, ≈`#707070`) — muddy against the off-track
+(≈`#262626`) and near-unreadable (≈1.07:1) against the accent-1 on-track
+(`#5770cb`). `switch.scss` shadows the token locally under
+`[mlvTheme='dark'] .mlv-switch` to `--mlv-palette-neutral-50` (≈`#fafafa`,
+same invariant near-white in every theme) so the thumb reads as a crisp knob
+in both states (14.5:1 off-track, 4.45:1 on-track). Light is untouched — it
+already resolved `--mlv-elevation-bg-5` → `--mlv-background-raised` →
+`#ffffff`. No other `--mlv-elevation-bg-5` consumer exists, so the shadowed
+override is switch-local by construction.
+
+##### Density geometry ladder
+
+Every level satisfies `thumb = track-height − 2 × inset` and
+`travel = track-width − thumb − 2 × inset`, so the thumb never clips the track.
+`comfortable` reproduces the pre-density rendering exactly.
+
+| Level         | Track (w × h)       | Thumb      | Travel     | Label gap           | Label type                                         |
+| ------------- | ------------------- | ---------- | ---------- | ------------------- | -------------------------------------------------- |
+| `tight`       | `2rem × 1.125rem`   | `0.875rem` | `0.875rem` | `--mlv-spacing-1`   | `body-s` / `--mlv-line-height-tight`               |
+| `compact`     | `2.25rem × 1.25rem` | `1rem`     | `1rem`     | `--mlv-spacing-1-5` | `body-m` / `--mlv-line-height-normal`              |
+| `comfortable` | `2.5rem × 1.5rem`   | `1.25rem`  | `1rem`     | `--mlv-spacing-2`   | `body-m` / `--mlv-line-height-normal`              |
+| `spacious`    | `3rem × 1.75rem`    | `1.5rem`   | `1.25rem`  | `--mlv-spacing-2-5` | `body-l` / `--mlv-line-height-normal`              |
+| `airy`        | `3.5rem × 2rem`     | `1.75rem`  | `1.5rem`   | `--mlv-spacing-3`   | `--mlv-font-size-xl` / `--mlv-line-height-relaxed` |
+
+The values live in component-scoped custom properties on `.mlv-switch`
+(`--mlv-switch-track-width`, `--mlv-switch-track-height`, `--mlv-switch-thumb-size`,
+`--mlv-switch-thumb-inset`, `--mlv-switch-thumb-travel`, `--mlv-switch-gap`,
+`--mlv-switch-font-size`, `--mlv-switch-line-height`), redeclared inside the five
+`density.density-*` mixin blocks.
+
+**2026-08-26:** `compact` and `airy` previously read `body-s` / `body-l` —
+one step below the shared control-text ramp (CH-R3), which put a switch
+label at a different size than an input's text at those two densities.
+Retuned to `body-m` (compact) and the primitive `--mlv-font-size-xl` (airy —
+there is no `--mlv-typography-body-xl-size` alias) to match
+`--form-ctrl-font-size`'s ramp in `mlv-form-control-wrapper`. `tight` /
+`comfortable` / `spacious` were already correct. See
+`.claude/projects/libs-form-utils.md` → _Control-text type & padding ramp_.
+
+##### Accessibility floor
+
+The pointer target is the wrapping `<label>`, not the track. `.mlv-switch__label`
+carries an unconditional `min-block-size: 1.5rem; min-inline-size: 1.5rem`, so the
+hit area never falls below **24 × 24 CSS px** (WCAG 2.2 SC 2.5.8, level AA) even
+at `tight` / `compact`, where the _visible_ track is only 18px / 20px tall.
+Label text uses `--mlv-text-primary` at every step, so contrast stays AA including
+at the 12px `body-s` used by `tight` and `compact`.
 
 ---
 
@@ -150,10 +208,11 @@ A dev-mode `console.warn` fires once per instance when a switch has no projected
 
 #### Inputs
 
-| Name    | Type                  | Default     |
-| ------- | --------------------- | ----------- |
-| `label` | `string`              | `''`        |
-| `state` | `MlvSwitchGroupState` | `'default'` |
+| Name         | Type                  | Default                     | Description                                                                                                                                                                      |
+| ------------ | --------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`      | `string`              | `''`                        | Accessible name + visible group label.                                                                                                                                           |
+| `state`      | `MlvSwitchGroupState` | `'default'`                 | Visual/validation state applied to the group.                                                                                                                                    |
+| `mlvDensity` | `MlvDensity`          | inherited / `'comfortable'` | Density for the group **and** every projected switch — see _Density projection_ below. Scales the group's inter-switch gap and is provided as `MLV_DENSITY_CONTEXT` to children. |
 
 #### Methods (inherited from `MlvFocusableGroupBase`)
 
@@ -164,9 +223,35 @@ A dev-mode `console.warn` fires once per instance when a switch has no projected
 
 #### Keyboard Navigation
 
+#### Density projection
+
+```ts
+hostDirectives: [{ directive: MlvDensityDirective, inputs: ['mlvDensity'] }],
+providers: [
+  { provide: MLV_DENSITY_ELEMENT, useValue: 'switch-group' },
+  provideMlvDensityContext(MlvDensityDirective),
+],
+```
+
+- The host is stamped `mlv-switch-group--{density}`, which scales
+  `--mlv-switch-group-gap` (`tight` `--mlv-spacing-1` → `airy` `--mlv-spacing-4`;
+  `comfortable` keeps the historical `0.5rem`).
+- `provideMlvDensityContext` publishes the group's resolved density as
+  `MLV_DENSITY_CONTEXT`. Projected `<mlv-switch>` children resolve it through
+  their declaration-site element injector (the same path `SWITCH_GROUP` uses), so
+  they stamp the matching `mlv-switch--{density}` themselves — the density reaches
+  them through DI, not only the CSS cascade.
+- Resolution order in each child: its own `mlvDensity` input → the group's
+  `MLV_DENSITY_CONTEXT` → `MlvDensityService`. An explicit `mlvDensity` on a
+  single switch therefore overrides the group.
+
 #### Template Summary
 
-`div[role="group"][aria-label]` + optional `mlv-label` + `<ng-content>` + `(keydown)` handler.
+The **host** `<mlv-switch-group>` _is_ the group container: `class="mlv-switch-group"`,
+`role="group"`, `[attr.aria-label]="label() || null"` and the `(keydown)` handler are
+host bindings (the former inner wrapper `<div>` was removed so the BEM block and its
+density modifier live on the same element). Template: optional `mlv-label` +
+`<ng-content>`.
 
 ---
 
@@ -203,6 +288,15 @@ interface MlvSwitchGroupAccessor {
 
 <!-- Disabled -->
 <mlv-switch [disabled]="true">Locked</mlv-switch>
+
+<!-- Per-switch density -->
+<mlv-switch mlvDensity="compact">Compact toggle</mlv-switch>
+
+<!-- Group density, projected to every child; one child opts out -->
+<mlv-switch-group mlvDensity="spacious" label="Notifications">
+  <mlv-switch [(checked)]="email">Email</mlv-switch>
+  <mlv-switch [(checked)]="sms" mlvDensity="tight">SMS</mlv-switch>
+</mlv-switch-group>
 ```
 
 ---
@@ -212,5 +306,6 @@ interface MlvSwitchGroupAccessor {
 - `@angular/forms` — CVA
 - `@angular/cdk/a11y` — `FocusKeyManager`, `FocusableOption`
 - `@malva-ui/cdk/accessibility` — `MlvClick`
+- `@malva-ui/cdk/density` — `MlvDensityDirective`, `MLV_DENSITY_ELEMENT`, `provideMlvDensityContext`
 - `@malva-ui/core/form-utils` — `MlvLabel`
-- `@malva-ui/styles` — design tokens, `_mixins.scss`
+- `@malva-ui/styles` — design tokens, `_mixins.scss`, `_density.scss`

package/docs/ai/table.md

@@ -0,0 +1,69 @@
+# @malva-ui/core/table
+
+> directives, styles, tests, or public API change.
+
+  
+**Import path:** `@malva-ui/core/table`  
+**Selector:** `table[mlvTable]`
+
+Native table presentation primitives for common tables. The package enhances a
+real HTML `<table>` rather than rendering rows or owning a data source. Use
+`@malva-ui/core/data-table` for sorting, filtering, pagination, selection,
+editing, virtual scroll, and other data-grid behavior.
+
+## Public API
+
+| Export              | Kind      | Description                                                                               |
+| ------------------- | --------- | ----------------------------------------------------------------------------------------- |
+| `MlvTable`          | Component | Adds Malva table appearance, responsive modes, and density support to `<table mlvTable>`. |
+| `MlvTableRow`       | Directive | Marks a `<tr mlvTableRow>` as `main` or `secondary` for Pop In mode.                      |
+| `MlvTableCell`      | Directive | Adds shared Malva cell styling to cells carrying `mlvTableCell`.                          |
+| `MlvTableHoverable` | Type      | `false`, `'row'`, or `'cell'`.                                                            |
+
+## `MlvTable`
+
+### Inputs
+
+| Input        | Type                | Default   | Description                                                                              |
+| ------------ | ------------------- | --------- | ---------------------------------------------------------------------------------------- |
+| `bordered`   | `BooleanInput`      | `false`   | Adds an outer boundary and cell separators.                                              |
+| `responsive` | `BooleanInput`      | `false`   | Enables horizontal overflow styling for narrow viewports. Required for Pop In mode.      |
+| `popIn`      | `BooleanInput`      | `false`   | Enables the paired main/secondary row presentation at the mobile breakpoint.             |
+| `hoverable`  | `MlvTableHoverable` | `false`   | Applies pointer feedback to a whole row or individual data cells.                        |
+| `mlvDensity` | `MlvDensity`        | inherited | Applies `tight`, `compact`, `comfortable`, `spacious`, or `airy` spacing and type scale. |
+
+### Appearance classes
+
+The component adds the BEM block `mlv-table` and state modifiers for the
+selected inputs. It preserves native table roles and does not add a grid role.
+
+## Pop In markup
+
+Pop In is opt-in and requires both `[responsive]="true"` and `[popIn]="true"`.
+Each data item is represented by a pair of native rows:
+
+```html
+<tr mlvTableRow main>
+  <td mlvTableCell data-label="Name">...</td>
+</tr>
+<tr mlvTableRow secondary>
+  <td mlvTableCell colspan="2">...</td>
+</tr>
+```
+
+The main row should contain the minimum set of important or interactive cells.
+The secondary row is for supporting display-only information. On narrow
+viewports the table header is visually collapsed while remaining available to
+assistive technology, main cells show their `data-label`, and the secondary
+row becomes a quiet supporting surface. Set `colspan` to the number of cells in
+the paired main row; it is a numeric HTML attribute and does not accept a
+percentage.
+
+## Styling
+
+Styles use the `mlv-table` BEM block, shared Malva design tokens, rem units,
+and a reduced-motion fallback. `MlvTable` integrates the shared
+`MlvDensityDirective`; density changes cell padding and type scale while
+preserving the native table structure. Unmarked native rows and cells remain
+valid and retain the base table styling; the row/cell directives only provide
+styling hooks and do not change native semantics.