@malva-ui/core 0.1.13 → 0.1.14

package/docs/ai/radio.md

@@ -199,3 +199,12 @@ interface MlvRadioGroupAccessor {
 - `MlvRadioGroup` now renders `<mlv-description>` (from the inherited `description` input) and `<mlv-message>` (from the inherited `message` input) below the projected radios. **`message` was previously accepted but never rendered** — setting it now produces a visible status line.
 - Inherited `required` renders the `mlv-label` marker and sets `aria-required` on the `role="radiogroup"` host.
 - The host `aria-label` is now `ariaLabel() ?? label()`, and `aria-describedby` is the base's `_describedBy()`.
+
+## Label type scale (2026-08-26)
+
+`.mlv-radio` now carries the shared control-text ramp (CH-R3) via
+`density.density-*` mixins, mirroring `mlv-checkbox` — `--mlv-font-size-s`
+(tight) / `-m` (compact, comfortable) / `-l` (spacious) / `-xl` (airy). It
+previously had no type ramp at all. `&__label`'s `gap` also moved from the
+raw literal `0.25rem` to `var(--mlv-spacing-1)` (same value, tokenized). See
+`.claude/projects/libs-form-utils.md` → _Control-text type & padding ramp_.

package/docs/ai/scrollbar.md

@@ -29,13 +29,13 @@ Exported from `@malva-ui/core/scrollbar`:
 
 #### Inputs
 
-| Name               | Type                      | Default      | Description                                                            |
-| ------------------ | ------------------------- | ------------ | ---------------------------------------------------------------------- |
-| `orientation`      | `MlvScrollbarOrientation` | `'vertical'` | Which axes to show the custom scrollbar on                             |
-| `scrollbarSize`    | `string`                  | `'0.75rem'`  | CSS length for track width/height; maps to `--mlv-sb-size`             |
-| `disabled`         | `BooleanInput`            | `false`      | Hides custom tracks and restores native scrollbar                      |
-| `ariaLabel`        | `string \| undefined`     | `undefined`  | Accessible viewport label; falls back to i18n/default text             |
-| `viewportTabIndex` | `number`                  | `0`          | **`0` means auto** (see below); any non-zero value is applied verbatim |
+| Name               | Type                      | Default      | Description                                                                                                                      |
+| ------------------ | ------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| `orientation`      | `MlvScrollbarOrientation` | `'vertical'` | Which axes to show the custom scrollbar on                                                                                       |
+| `scrollbarSize`    | `string`                  | `'0.75rem'`  | CSS length for track width/height; maps to `--mlv-sb-size`                                                                       |
+| `disabled`         | `BooleanInput`            | `false`      | Hides custom tracks and restores native scrollbar                                                                                |
+| `ariaLabel`        | `string \| undefined`     | `undefined`  | Accessible viewport label; falls back to i18n/default text. Written to the DOM only while the viewport is a tab stop — see below |
+| `viewportTabIndex` | `number`                  | `0`          | **`0` means auto** (see below); any non-zero value is applied verbatim                                                           |
 
 #### Viewport tab stop (WCAG 2.1.1)
 
@@ -54,6 +54,28 @@ CDK's `InteractivityChecker` under `{ ignoreVisibility: true }` (the geometric
 visibility test never passes before first paint, nor under jsdom). The resolved
 value lives in the protected `_effectiveViewportTabIndex` computed.
 
+#### Viewport role and name (WCAG 4.1.2)
+
+The name follows the tab stop — both are driven by `_effectiveViewportTabIndex`:
+
+| Viewport tab stop | `role`  | `aria-label`              |
+| ----------------- | ------- | ------------------------- |
+| yes (`>= 0`)      | `group` | resolved `ariaLabel`/i18n |
+| no (`-1`)         | absent  | absent                    |
+
+- `aria-label` is **prohibited** on an element with no role (implicit
+  `generic`), so a bare labelled `<div>` had its name discarded by AT and
+  tripped axe `aria-prohibited-attr`. The label is now only emitted alongside a
+  role that permits it.
+- `group`, not the landmark `region`: wrapping content in `mlv-scrollbar` must
+  never inject a landmark — nor repeat one generic "Scrollable region" landmark
+  name — into the host page's landmark navigation.
+- A viewport that is not a tab stop is not a control the user can land on, so
+  it stays a plain container and the projected content owns its own semantics.
+
+Resolved by the protected `_isViewportFocusable`, `_viewportRole` and
+`_viewportAriaLabel` computeds.
+
 #### Public properties
 
 | Property          | Type          | Description                                                                                                        |
@@ -75,7 +97,7 @@ host: {
 #### Template Structure
 
 ```html
-<div class="mlv-scrollbar__viewport" #viewport [attr.tabindex]="_effectiveViewportTabIndex()" (scroll)="_onScroll()">
+<div class="mlv-scrollbar__viewport" #viewport [attr.tabindex]="_effectiveViewportTabIndex()" [attr.role]="_viewportRole()" [attr.aria-label]="_viewportAriaLabel()" (scroll)="_onScroll()">
   <div class="mlv-scrollbar__content" #content>
     <ng-content />
   </div>

package/docs/ai/segmented.md

@@ -46,28 +46,28 @@ Exported from `@malva-ui/core/segmented`:
 
 #### Inputs
 
-| Name          | Type                                               | Default        | Description                                                                                                                                                                |
-| ------------- | -------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tone`        | `MlvSegmentedTone`                                 | `'neutral'`    | Active pill colour: `neutral` (raised surface) or a **pale** semantic tone (`accent`/`info`/`success`/`warning`/`danger`).                                                 |
-| `orientation` | `MlvSegmentedOrientation`                          | `'horizontal'` | Track axis. Reflected as `mlv-segmented--horizontal` / `mlv-segmented--vertical` and as `aria-orientation` on the radiogroup.                                              |
-| `equalWidth`  | `boolean` (coerced)                                | `false`        | Track fills its container and every item becomes `flex: 1 1 0`.                                                                                                            |
-| `mlvDensity`  | `MlvDensity`                                       | inherited      | _(host directive)_ Density override for this group; scales item padding and font size.                                                                                     |
-| `disabled`    | `boolean` (coerced)                                | `false`        | _(inherited)_ Disables every segment. Also the signal-forms field binding — `[formField]` writes this very input, which is the single source read by `computedDisabled()`. |
-| `readonly`    | `boolean` (coerced)                                | `false`        | _(inherited)_ Segments stay focusable and arrow keys still move focus, but selection is blocked.                                                                           |
-| `required`    | `boolean` (coerced)                                | `false`        | _(inherited)_ Renders the `mlv-label` marker and sets `aria-required` on the radiogroup.                                                                                   |
-| `state`       | `MlvFormState`                                     | `'default'`    | _(inherited)_ Explicit validation state. The effective `resolvedState()` is reflected as `mlv-segmented--state-*`.                                                         |
-| `label`       | `string`                                           | `''`           | _(inherited)_ Rendered as `<mlv-label>` above the track; also the radiogroup's `aria-label` fallback.                                                                      |
-| `description` | `string`                                           | `''`           | _(inherited)_ Rendered as `<mlv-description>` below the track and referenced by `aria-describedby`.                                                                        |
-| `message`     | `string`                                           | `''`           | _(inherited)_ Rendered as `<mlv-message>` below the description, coloured by `resolvedState()`, and referenced by `aria-describedby`.                                      |
-| `ariaLabel`   | `string \| null`                                   | `null`         | _(inherited)_ Accessible name of the radiogroup. Falls back to `label`; `null` in link mode (the track carries no role there).                                             |
-| `id`          | `string`                                           | auto           | _(inherited)_ Host `id`; also the prefix of the generated description/message element ids.                                                                                 |
-| `hint`        | `string`                                           | `''`           | _(inherited)_ **Not rendered** — the segmented label has no `mlv-hint` slot. Use `description`.                                                                            |
-| `loading`     | `boolean` (coerced)                                | `false`        | _(inherited)_ **Inert** — the control renders no loading affordance.                                                                                                       |
-| `clearable`   | `boolean` (coerced)                                | `false`        | _(inherited)_ **Inert** — the control renders no clear button (there is no `mlv-form-control-wrapper`).                                                                    |
-| `pill`        | `boolean` (coerced)                                | `false`        | _(inherited)_ **Inert** — the track has no wrapper. Round the track with `--mlv-segmented-radius` instead.                                                                 |
-| `errors`      | `readonly ValidationError.WithOptionalFieldTree[]` | `[]`           | _(inherited)_ Signal-forms field binding; `[formField]` supplies it. Feeds `resolvedState()`.                                                                              |
-| `touched`     | `boolean` (coerced)                                | `false`        | _(inherited)_ Signal-forms field binding. A non-empty `errors` becomes a visible `error` state only once this is true.                                                     |
-| `dirty`       | `boolean` (coerced)                                | `false`        | _(inherited)_ Signal-forms field binding.                                                                                                                                  |
+| Name          | Type                                               | Default        | Description                                                                                                                                                                                                                                                                                      |
+| ------------- | -------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `tone`        | `MlvSegmentedTone`                                 | `'neutral'`    | Active pill colour: `neutral` or a semantic tone (`accent`/`info`/`success`/`warning`/`danger`) — every tone, including `neutral`, converges on the `--mlv-background-selected` / `--mlv-text-on-selected` token pair (AB-R8, SF-R1); a segmented choice never renders as a filled accent block. |
+| `orientation` | `MlvSegmentedOrientation`                          | `'horizontal'` | Track axis. Reflected as `mlv-segmented--horizontal` / `mlv-segmented--vertical` and as `aria-orientation` on the radiogroup.                                                                                                                                                                    |
+| `equalWidth`  | `boolean` (coerced)                                | `false`        | Track fills its container and every item becomes `flex: 1 1 0`.                                                                                                                                                                                                                                  |
+| `mlvDensity`  | `MlvDensity`                                       | inherited      | _(host directive)_ Density override for this group; scales item padding and font size.                                                                                                                                                                                                           |
+| `disabled`    | `boolean` (coerced)                                | `false`        | _(inherited)_ Disables every segment. Also the signal-forms field binding — `[formField]` writes this very input, which is the single source read by `computedDisabled()`.                                                                                                                       |
+| `readonly`    | `boolean` (coerced)                                | `false`        | _(inherited)_ Segments stay focusable and arrow keys still move focus, but selection is blocked.                                                                                                                                                                                                 |
+| `required`    | `boolean` (coerced)                                | `false`        | _(inherited)_ Renders the `mlv-label` marker and sets `aria-required` on the radiogroup.                                                                                                                                                                                                         |
+| `state`       | `MlvFormState`                                     | `'default'`    | _(inherited)_ Explicit validation state. The effective `resolvedState()` is reflected as `mlv-segmented--state-*`.                                                                                                                                                                               |
+| `label`       | `string`                                           | `''`           | _(inherited)_ Rendered as `<mlv-label>` above the track; also the radiogroup's `aria-label` fallback.                                                                                                                                                                                            |
+| `description` | `string`                                           | `''`           | _(inherited)_ Rendered as `<mlv-description>` below the track and referenced by `aria-describedby`.                                                                                                                                                                                              |
+| `message`     | `string`                                           | `''`           | _(inherited)_ Rendered as `<mlv-message>` below the description, coloured by `resolvedState()`, and referenced by `aria-describedby`.                                                                                                                                                            |
+| `ariaLabel`   | `string \| null`                                   | `null`         | _(inherited)_ Accessible name of the radiogroup. Falls back to `label`; `null` in link mode (the track carries no role there).                                                                                                                                                                   |
+| `id`          | `string`                                           | auto           | _(inherited)_ Host `id`; also the prefix of the generated description/message element ids.                                                                                                                                                                                                       |
+| `hint`        | `string`                                           | `''`           | _(inherited)_ **Not rendered** — the segmented label has no `mlv-hint` slot. Use `description`.                                                                                                                                                                                                  |
+| `loading`     | `boolean` (coerced)                                | `false`        | _(inherited)_ **Inert** — the control renders no loading affordance.                                                                                                                                                                                                                             |
+| `clearable`   | `boolean` (coerced)                                | `false`        | _(inherited)_ **Inert** — the control renders no clear button (there is no `mlv-form-control-wrapper`).                                                                                                                                                                                          |
+| `pill`        | `boolean` (coerced)                                | `false`        | _(inherited)_ **Inert** — the track has no wrapper. Round the track with `--mlv-segmented-radius` instead.                                                                                                                                                                                       |
+| `errors`      | `readonly ValidationError.WithOptionalFieldTree[]` | `[]`           | _(inherited)_ Signal-forms field binding; `[formField]` supplies it. Feeds `resolvedState()`.                                                                                                                                                                                                    |
+| `touched`     | `boolean` (coerced)                                | `false`        | _(inherited)_ Signal-forms field binding. A non-empty `errors` becomes a visible `error` state only once this is true.                                                                                                                                                                           |
+| `dirty`       | `boolean` (coerced)                                | `false`        | _(inherited)_ Signal-forms field binding.                                                                                                                                                                                                                                                        |
 
 #### Outputs
 
@@ -245,23 +245,23 @@ Two BEM blocks:
 - `.mlv-segmented` — elements `__track`, `__indicator`; modifiers `--tone-{neutral|accent|info|success|warning|danger}`, `--horizontal` / `--vertical`, `--equal-width`, `--disabled`, `--measured`, `--state-{default|info|success|warning|error}`, plus `--readonly` and `--link` which carry **no styles** (state hooks for consumers).
 - `.mlv-segmented-item` — modifiers `--active`, `--disabled`, plus `--link` which carries **no styles** (hook only).
 
-Visuals: sunken track (`--mlv-background-sunken`, radius `xl`, `0.1875rem` inset padding, `0.125rem` gap, `overflow: hidden`), raised pill (`--mlv-shadow-1`, concentric `--mlv-segmented-inner-radius`, `220ms` `--mlv-ease-in-out-strong` slide), items in `--mlv-text-secondary` that transition `color` and `background-color` to the tone's active colour, `--mlv-background-neutral-1-hover` on idle hover, pressed (`:active`) idle segments one shade deeper on `--mlv-background-neutral-1-active`, and a `0.0625rem` hairline separator centred in the gap between two adjacent idle items.
+Visuals: sunken track (`--mlv-background-sunken`, radius `button`, `0.1875rem` inset padding, `0.125rem` gap, `overflow: hidden`), raised pill (`--mlv-shadow-raised`, concentric `--mlv-segmented-inner-radius`, `var(--mlv-duration-normal)` (200ms) `--mlv-ease-in-out-strong` slide), items in `--mlv-text-secondary` that transition `color` and `background-color` to the tone's active colour, `--mlv-background-neutral-1-hover` on idle hover, pressed (`:active`) idle segments one shade deeper on `--mlv-background-neutral-1-active`, and a `0.0625rem` hairline separator centred in the gap between two adjacent idle items.
 
-Separator rules: the hairline is hidden on **both** sides of the active, hovered, pressed (`:active`) and `:focus-visible` item, including the active item's own leading hairline. In `orientation="vertical"` the same hairline becomes a horizontal rule on the item's **top** edge (50% width, centred) instead of a vertical rule on its inline-start edge. Sizing is entirely density-driven (`0.375rem 0.625rem` tight → `1.25rem 1.5rem` airy, with `--mlv-font-size-s` / `-l` steps — identical to `mlv-tab-item`); there is **no** `size` input. `--state-error` / `--state-warning` / `--state-success` paint an inset tinted stroke on the track; `--state-info` and `--state-default` have no styling. `.mlv-segmented--disabled` dims the track with `--mlv-disabled-opacity`. Reduced motion via `@include mixins.reduced-motion('mlv-segmented')`. Dark theme (`[mlvTheme='dark']`): the track becomes `--mlv-background-neutral-1` and the neutral pill `--mlv-palette-neutral-700` (lifted surface + lighter pill); semantic tones keep their pale pills.
+Separator rules: the hairline is hidden on **both** sides of the active, hovered, pressed (`:active`) and `:focus-visible` item, including the active item's own leading hairline. In `orientation="vertical"` the same hairline becomes a horizontal rule on the item's **top** edge (50% width, centred) instead of a vertical rule on its inline-start edge. Sizing is entirely density-driven (`0.375rem 0.625rem` tight → `1.25rem 1.5rem` airy, with `--mlv-font-size-s` / `-l` steps — identical to `mlv-tab-item`); there is **no** `size` input. `--state-error` / `--state-warning` / `--state-success` paint an inset tinted stroke on the track; `--state-info` and `--state-default` have no styling. `.mlv-segmented--disabled` dims the track with `--mlv-disabled-opacity`. Reduced motion via `@include mixins.reduced-motion('mlv-segmented')`. Dark theme (`[mlvTheme='dark']`): the track becomes `--mlv-background-neutral-1` (lifted surface). Owner override 2026-08-25: the `neutral` tone's pill briefly converged on `--mlv-background-selected`/`--mlv-text-on-selected` (AB-R8, SF-R1) and needed no dark override of its own, but the owner asked for the previous raised-white pill back (`--mlv-background-raised` / `--mlv-text-primary`) — `--mlv-background-raised` resolves darker than the dark track (`#1e1e1e` vs `#262626`) and would sink instead of lift, so `[mlvTheme='dark'] .mlv-segmented--tone-neutral` repaints the pill one step lighter, `--mlv-palette-neutral-700`. Semantic tones (`accent`/`info`/`success`/`warning`/`danger`) still use their pale pills, which are theme-aware without a component-level repaint.
 
 Consumer-overridable custom properties:
 
-| Variable                             | Declared on                                 | Default                                       |
-| ------------------------------------ | ------------------------------------------- | --------------------------------------------- |
-| `--mlv-segmented-radius`             | `.mlv-segmented`                            | `var(--mlv-radius-xl)`                        |
-| `--mlv-segmented-track-padding`      | `.mlv-segmented`                            | `0.1875rem`                                   |
-| `--mlv-segmented-track-bg`           | `.mlv-segmented`                            | `var(--mlv-background-sunken)`                |
-| `--mlv-segmented-separator-color`    | `.mlv-segmented`                            | `var(--mlv-border-normal)`                    |
-| `--mlv-segmented-indicator-duration` | `.mlv-segmented`                            | `220ms`                                       |
-| `--mlv-segmented-pill-bg`            | `.mlv-segmented`, overridden per `--tone-*` | `var(--mlv-background-raised)`, then per tone |
-| `--mlv-segmented-active-color`       | `.mlv-segmented`, overridden per `--tone-*` | `var(--mlv-text-primary)`, then per tone      |
-
-The two pill variables carry their **neutral** defaults on `.mlv-segmented` itself, so a consumer who replaces the host `[class]` (and with it the `--tone-*` modifier) still gets the boxed-tabs pill instead of a transparent one; the `&--tone-*` rules are emitted after the block at equal specificity, so a tone still wins.
+| Variable                             | Declared on                                 | Default                                         |
+| ------------------------------------ | ------------------------------------------- | ----------------------------------------------- |
+| `--mlv-segmented-radius`             | `.mlv-segmented`                            | `var(--mlv-radius-button)`                      |
+| `--mlv-segmented-track-padding`      | `.mlv-segmented`                            | `0.1875rem`                                     |
+| `--mlv-segmented-track-bg`           | `.mlv-segmented`                            | `var(--mlv-background-sunken)`                  |
+| `--mlv-segmented-separator-color`    | `.mlv-segmented`                            | `var(--mlv-border-normal)`                      |
+| `--mlv-segmented-indicator-duration` | `.mlv-segmented`                            | `var(--mlv-duration-normal)` (200ms)            |
+| `--mlv-segmented-pill-bg`            | `.mlv-segmented`, overridden per `--tone-*` | `var(--mlv-background-selected)`, then per tone |
+| `--mlv-segmented-active-color`       | `.mlv-segmented`, overridden per `--tone-*` | `var(--mlv-text-on-selected)`, then per tone    |
+
+The two pill variables carry their **neutral** defaults on `.mlv-segmented` itself, so a consumer who replaces the host `[class]` (and with it the `--tone-*` modifier) still gets the selected-token pill instead of a transparent one; the `&--tone-*` rules are emitted after the block at equal specificity, so a tone still wins. AB-R8/SF-R1: `neutral` converges on the same `--mlv-background-selected` pill every other persistent-selection surface uses — never a filled accent block.
 
 `--mlv-segmented-inner-radius` (`max(0rem, radius − track-padding)`, shared by the pill and the items) and `--mlv-segmented-indicator-left|top|width|height` (written by the component in `px`) are internal — read them, do not set them.
 

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`.