@malva-ui/core 0.1.12 → 0.1.14

package/docs/ai/page.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-`@malva-ui/core/page` provides composable application-page primitives. `mlv-page-shell` owns the reusable geometry that joins existing action bars, one or two sidebars, and the rounded Page canvas; the projected navigation components retain their own behavior. The remaining primitives own page scrolling, structured headers, a collapsible key-facts summary strip, responsive main/aside content, and a bottom workflow action dock.
+`@malva-ui/core/page` provides composable application-page primitives. `mlv-page-shell` owns the reusable geometry that joins an existing action bar, zero to two start sidebars, one optional static or responsive end pane, and the rounded Page canvas; the projected navigation components retain their own behavior. The remaining primitives own page scrolling, structured headers, a collapsible key-facts summary strip, responsive main/aside content, and a bottom workflow action dock.
 
 Record-editor experiences (draft/live switches, version history, diff views, suggestions, delayed publish) are built by **composition**: this library ships the structure, slots, and scroll-linked behaviour; the host owns the domain state. See docs page example 3 for the full pattern.
 
@@ -10,54 +10,76 @@ Record-editor experiences (draft/live switches, version history, diff views, sug
 
 Exported from `@malva-ui/core/page`:
 
-| Export                     | Kind          | Selector / values             |
-| -------------------------- | ------------- | ----------------------------- |
-| `MlvPageShell`             | Component     | `mlv-page-shell`              |
-| `MlvPageTopbar`            | Shell slot    | `[mlvPageTopbar]`             |
-| `MlvPageSidebar`           | Shell slot    | `[mlvPageSidebar]`            |
-| `MlvPageEndSidebar`        | Shell slot    | `[mlvPageEndSidebar]`         |
-| `MlvPage`                  | Component     | `main[mlvPage]`               |
-| `MlvPageHeader`            | Component     | `mlv-page-header`             |
-| `MlvPageContent`           | Component     | `mlv-page-content`            |
-| `MlvPageBreadcrumb`        | Template slot | `[mlvPageBreadcrumb]`         |
-| `MlvPageHeaderIcon`        | Template slot | `[mlvPageHeaderIcon]`         |
-| `MlvPageTitle`             | Template slot | `[mlvPageTitle]`              |
-| `MlvPageHeaderStatus`      | Template slot | `[mlvPageHeaderStatus]`       |
-| `MlvPageHeaderActions`     | Template slot | `[mlvPageHeaderActions]`      |
-| `MlvPageHeaderDescription` | Template slot | `[mlvPageHeaderDescription]`  |
-| `MlvPageHeaderMeta`        | Template slot | `[mlvPageHeaderMeta]`         |
-| `MlvPageHeaderTabs`        | Template slot | `[mlvPageHeaderTabs]`         |
-| `MlvPageHeaderTabsActions` | Template slot | `[mlvPageHeaderTabsActions]`  |
-| `MlvPageAside`             | Template slot | `[mlvPageAside]`              |
-| `MlvPageSummary`           | Component     | `mlv-page-summary`            |
-| `MlvPageSummaryItem`       | Component     | `mlv-page-summary-item`       |
-| `MlvPageDock`              | Component     | `mlv-page-dock`               |
-| `MlvPageDockStart`         | Dock slot     | `[mlvPageDockStart]`          |
-| `MlvPageDockCenter`        | Dock slot     | `[mlvPageDockCenter]`         |
-| `MlvPageDockEnd`           | Dock slot     | `[mlvPageDockEnd]`            |
-| `MLV_PAGE_SCROLL`          | Token         | `MlvPageScrollState`          |
-| `MlvPageScrollState`       | Interface     | `{ scrollTop; scrolled }`     |
-| `MlvPageSnapController`    | Service       | provided by `MlvPage`         |
-| `MlvPageSnap`              | Directive     | `[mlvPageSnap]`               |
-| `MlvPageSnapMode`          | Type          | `'hide' \| 'fade' \| 'keep'`  |
-| `MlvPageDockAppearance`    | Type          | `'bar' \| 'floating'`         |
-| `MlvPageScroll`            | Type          | `'auto' \| 'none'`            |
-| `MlvPagePadding`           | Type          | `'none' \| 's' \| 'm' \| 'l'` |
-| `MlvPageSurface`           | Type          | `'anchored' \| 'flat'`        |
-| `MlvPageHeaderSize`        | Type          | `'m' \| 's'`                  |
-| `MlvPageHeaderTabsAlign`   | Type          | `'start' \| 'center'`         |
-| `MlvPageAsidePlacement`    | Type          | `'start' \| 'end'`            |
-| `MlvPageContentGap`        | Type          | `'s' \| 'm' \| 'l'`           |
+| Export                     | Kind             | Selector / values                    |
+| -------------------------- | ---------------- | ------------------------------------ |
+| `MlvPageShell`             | Component        | `mlv-page-shell`                     |
+| `MlvPageTopbar`            | Shell slot       | `[mlvPageTopbar]`                    |
+| `MlvPageSidebar`           | Shell slot       | `[mlvPageSidebar]`                   |
+| `MlvPageEndSidebar`        | Shell slot       | `[mlvPageEndSidebar]`                |
+| `MlvPageEndPane`           | Component        | `mlv-page-end-pane`                  |
+| `MlvPageEndPaneContent`    | Template slot    | `ng-template[mlvPageEndPaneContent]` |
+| `MlvPageEndPaneTrigger`    | Button directive | `button[mlvPageEndPaneTrigger]`      |
+| `MlvPage`                  | Component        | `main[mlvPage]`                      |
+| `MlvPageHeader`            | Component        | `mlv-page-header`                    |
+| `MlvPageContent`           | Component        | `mlv-page-content`                   |
+| `MlvPageBreadcrumb`        | Template slot    | `[mlvPageBreadcrumb]`                |
+| `MlvPageHeaderIcon`        | Template slot    | `[mlvPageHeaderIcon]`                |
+| `MlvPageTitle`             | Template slot    | `[mlvPageTitle]`                     |
+| `MlvPageHeaderStatus`      | Template slot    | `[mlvPageHeaderStatus]`              |
+| `MlvPageHeaderActions`     | Template slot    | `[mlvPageHeaderActions]`             |
+| `MlvPageHeaderDescription` | Template slot    | `[mlvPageHeaderDescription]`         |
+| `MlvPageHeaderMeta`        | Template slot    | `[mlvPageHeaderMeta]`                |
+| `MlvPageHeaderTabs`        | Template slot    | `[mlvPageHeaderTabs]`                |
+| `MlvPageHeaderTabsActions` | Template slot    | `[mlvPageHeaderTabsActions]`         |
+| `MlvPageAside`             | Template slot    | `[mlvPageAside]`                     |
+| `MlvPageSummary`           | Component        | `mlv-page-summary`                   |
+| `MlvPageSummaryItem`       | Component        | `mlv-page-summary-item`              |
+| `MlvPageDock`              | Component        | `mlv-page-dock`                      |
+| `MlvPageDockStart`         | Dock slot        | `[mlvPageDockStart]`                 |
+| `MlvPageDockCenter`        | Dock slot        | `[mlvPageDockCenter]`                |
+| `MlvPageDockEnd`           | Dock slot        | `[mlvPageDockEnd]`                   |
+| `MLV_PAGE_SCROLL`          | Token            | `MlvPageScrollState`                 |
+| `MlvPageScrollState`       | Interface        | `{ scrollTop; scrolled }`            |
+| `MlvPageSnapController`    | Service          | provided by `MlvPage`                |
+| `MlvPageSnap`              | Directive        | `[mlvPageSnap]`                      |
+| `MlvPageSnapRegionBase`    | Abstract base    | focus contract for snap regions      |
+| `MlvPageSnapRegion`        | Interface        | `{ reveal; syncHiddenState }`        |
+| `MlvPageSnapMode`          | Type             | `'hide' \| 'fade' \| 'keep'`         |
+| `MlvPageDockAppearance`    | Type             | `'bar' \| 'floating'`                |
+| `MlvPageScroll`            | Type             | `'auto' \| 'none'`                   |
+| `MlvPagePadding`           | Type             | `'none' \| 's' \| 'm' \| 'l'`        |
+| `MlvPageSurface`           | Type             | `'anchored' \| 'flat'`               |
+| `MlvPageHeaderSize`        | Type             | `'m' \| 's'`                         |
+| `MlvPageHeaderTabsAlign`   | Type             | `'start' \| 'center'`                |
+| `MlvPageAsidePlacement`    | Type             | `'start' \| 'end'`                   |
+| `MlvPageContentGap`        | Type             | `'s' \| 'm' \| 'l'`                  |
 
 ## `MlvPageShell`
 
 `MlvPageShell` is the application-page composition boundary. It supplies stable topbar/body/content tracks, continuous dark chrome, and the integration styling that turns a collapsed `mlv-sidebar` into a rail beside an attached Page canvas. Consumers project existing navigation components through marker directives; Page does not duplicate their interaction logic.
 
 - `[mlvPageTopbar]` spans the shell above every column.
-- `[mlvPageSidebar]` marks the primary start sidebar.
-- `[mlvPageEndSidebar]` optionally adds a second shell-level sidebar after the canvas.
+- `[mlvPageSidebar]` marks zero to two start sidebars. Repeated hosts project in their author DOM order.
+- `[mlvPageEndSidebar]` optionally adds one static shell-level end sidebar after the canvas.
+- `mlv-page-end-pane` adds a responsive trailing pane that becomes a modal Drawer below its configured breakpoint.
 - Unmarked content occupies the central canvas track and should normally be one `main[mlvPage]`.
 
+### Multi-sidebar projection contract
+
+`mlv-page-shell` accepts zero, one, or two repeated `[mlvPageSidebar]` hosts.
+Their DOM order is their visual and reading order, so an icon rail followed by an
+expanded navigation panel stays a rail followed by navigation for every user.
+The shell accepts at most one `[mlvPageEndSidebar]`, projected after the central
+content track for a labelled inspector or complementary navigation region.
+The same end projection also accepts one `mlv-page-end-pane`; existing static
+end-sidebar markup remains compatible and unchanged.
+
+The shell deliberately has no numbered sidebar selectors and no column-count
+input. Each projected host owns its own `width`, collapsed state, and
+`offcanvas` mode. The shell only preserves the tracks around it: the central
+content track remains `flex: 1 1 auto` with `min-width: 0`, allowing it to
+shrink instead of overflowing when sidebars are present.
+
 A projected sidebar in `mode="offcanvas"` renders as an overlay drawer while its
 host element stays in the shell's body row. `mlv-sidebar--offcanvas` is
 `width: 100%` so a standalone sidebar can fill its container, which inside the
@@ -97,10 +119,12 @@ Everything projected into `[mlvPageTopbar]` / `[mlvPageSidebar]` /
 `[mlvPageEndSidebar]` sits on the chrome background, not on a page surface, so
 the theme tokens those components resolve read wrong against it. The shell
 remaps them scoped to the chrome slots only — a control inside `main[mlvPage]`
-keeps the normal tokens. All values derive from
-`--mlv-page-shell-effective-foreground`, the same contrast-derived value the
-topbar already uses, so one set of rules covers a light brand colour, a dark
-brand colour, and the default `neutral-900` chrome in both themes.
+keeps the normal tokens. Every remap mixes
+`--mlv-page-shell-effective-foreground` **against
+`--mlv-page-shell-effective-background`** — never against `transparent` — so
+one formula is correct on a light chrome, a dark chrome, and a brand chrome,
+and the result is opaque (a portalled flyout no longer picks up whatever is
+behind it) (SF-R2).
 
 On `&__sidebar.mlv-sidebar`:
 
@@ -109,22 +133,82 @@ On `&__sidebar.mlv-sidebar`:
 | `--mlv-sidebar-border-width`        | `0rem`               | The rail has no wall of its own inside the shell.                                     |
 | `--mlv-text-primary`                | effective foreground | Row labels.                                                                           |
 | `--mlv-text-secondary`              | foreground 78 %      | Idle row labels.                                                                      |
-| `--mlv-text-action`                 | effective foreground | Active row text (the pill, not colour, carries the active state — see below).         |
-| `--mlv-background-neutral-1`        | foreground 15 %      | Neutral interactive fill.                                                             |
-| `--mlv-background-neutral-1-hover`  | foreground 15 %      | Transparent-variant `mlvButton`s and other projected chrome resolve this pair direct. |
-| `--mlv-background-neutral-1-active` | foreground 24 %      | Same — e.g. the workspace switcher's open state.                                      |
-| `--mlv-sidebar-hover-bg`            | foreground 15 %      | Row hover / focus-visible fill (see `libs-sidebar.md` → **State surfaces**).          |
-| `--mlv-sidebar-active-bg`           | foreground 24 %      | Active row pill.                                                                      |
-| `--mlv-sidebar-rail-color`          | foreground 30 %      | Expanded group tree line.                                                             |
+| `--mlv-text-action`                 | effective foreground | Link/action foreground inside the rail.                                               |
+| `--mlv-background-neutral-1`        | foreground 8 %       | Neutral interactive fill.                                                             |
+| `--mlv-background-neutral-1-hover`  | foreground 8 %       | Transparent-variant `mlvButton`s and other projected chrome resolve this pair direct. |
+| `--mlv-background-neutral-1-active` | foreground 12 %      | Same — e.g. the workspace switcher's open state.                                      |
+| `--mlv-sidebar-hover-bg`            | foreground 8 %       | Row hover / focus-visible fill (see `libs-sidebar.md` → **State surfaces**).          |
+| `--mlv-sidebar-active-bg`           | foreground 12 %      | Active row pill.                                                                      |
+| `--mlv-sidebar-rail-color`          | foreground 24 %      | Expanded group tree line.                                                             |
+| `--mlv-text-on-selected`            | effective foreground | Active row label — see below.                                                         |
+| `--mlv-background-selected`         | foreground 12 %      | Selected fill for anything resolving it directly (workspace switcher row).            |
+| `--mlv-background-selected-hover`   | foreground 8 %       | Same, hovered.                                                                        |
 | `--mlv-border-focus`                | effective foreground | Focus ring.                                                                           |
 
-Measured on a `rgb(65, 99, 169)` brand colour (white foreground): active pill =
-white 24 % → white icon at 3.53:1; hover = white 15 % → 4.26:1. Both clear the
-WCAG AA 3:1 minimum for UI components.
+The six row-state fills above (`--mlv-background-neutral-1*`,
+`--mlv-sidebar-hover-bg/-active-bg/-rail-color`) sit lower than the
+field-fill/border/foreground mixes elsewhere in this remap — SF-R2/SL-R5's "no
+state fill darker than the darkest resting surface." Resolved on three
+chromes: light (`#ffffff` bg, near-black fg) hover `rgb(236,236,236)` / active
+`rgb(227,227,227)`; dark default (`#171717` bg, `#fafafa` fg) hover
+`rgb(41,41,41)` / active `rgb(50,50,50)`; brand blue `rgb(65,99,169)` with
+white foreground — hover `rgb(80,111,176)` / active `rgb(88,118,179)`. One
+formula, three correct answers.
+
+`--mlv-text-on-selected` has to be remapped **in its own right**, not through
+`--mlv-text-action`. It is declared once per theme block as
+`var(--mlv-text-action)`, so it resolves in the scope it is declared in — the
+document root — and remapping `--mlv-text-action` on the sidebar never reaches
+it. Without the direct remap an active row keeps the theme accent: a lavender
+label on the chrome-derived 12 % pill, unreadable on a coloured chrome and deaf
+to a `color`/`foreground` override.
+
+The seam between two adjacent start sidebars
+(`.mlv-page-shell__body > [mlvPageSidebar] + [mlvPageSidebar]`) is derived the
+same way — `border-inline-start: var(--mlv-stroke-width) solid` foreground
+**16 %**, between the 8/12 % row-state fills and the 24 % rail line.
+`--mlv-border-subtle` resolves against the page surface and painted a near-white
+hairline across a dark or brand chrome.
 
 `&__topbar .mlv-form-control-wrapper` / `&__sidebar .mlv-form-control-wrapper`
 carry the matching remap for projected form controls (container background,
-border ramp, text and focus tokens).
+border ramp, text and focus tokens) — same chrome-background mix, unchanged
+percentages (10 / 30 / 40 / 50 for the field fill/border ramp; 78 / 78 / 60 for
+the action/text-secondary/text-tertiary foregrounds).
+
+## `MlvPageEndPane`
+
+`MlvPageEndPane` owns one trailing region across two renderers. It projects the
+single required `ng-template[mlvPageEndPaneContent]` into a labelled inline
+`aside` above `collapseBelow` and into a right-side modal `MlvDrawer` below it.
+Only one branch exists at a time, so consumers never create duplicate forms,
+subscriptions, ids, or tab stops while the viewport crosses the breakpoint.
+
+| Input / model          | Type                     | Default   | Description                                                     |
+| ---------------------- | ------------------------ | --------- | --------------------------------------------------------------- |
+| `opened`               | `boolean` model          | `false`   | One logical open state shared by inline and Drawer renderers.   |
+| `width`                | `string`                 | `'20rem'` | Inline track width and compact Drawer size.                     |
+| `collapseBelow`        | `MlvBreakpoint \| null`  | `null`    | Breakpoint below which the pane uses the modal Drawer renderer. |
+| `ariaLabel`            | `string`                 | required  | Accessible name of the active aside or dialog.                  |
+| `closeOnBackdropClick` | `boolean`                | `true`    | Allows backdrop dismissal in compact mode.                      |
+| `closeOnEscape`        | `boolean`                | `true`    | Allows Escape dismissal in compact mode.                        |
+| `initialFocus`         | `MlvOverlayInitialFocus` | `'auto'`  | Compact Drawer initial-focus strategy.                          |
+
+| Output         | Description                                                                                              |
+| -------------- | -------------------------------------------------------------------------------------------------------- |
+| `openedChange` | Model output emitted when the logical `opened` state changes.                                            |
+| `afterOpened`  | Emits once for each logical false-to-true transition. Breakpoint migration does not emit.                |
+| `afterClosed`  | Emits once after a real close and after the active renderer is gone. Breakpoint migration does not emit. |
+
+Public methods `open()`, `close()`, and `toggle()` update the same logical
+model. `button[mlvPageEndPaneTrigger]` requires a pane instance, toggles it,
+and mirrors `aria-expanded` plus `aria-controls`. The pane host owns a stable
+`panelId`, so that relationship resolves while open, closed, inline, or modal.
+
+The pane captures the pre-open active element only on a logical false-to-true
+transition. Its internal Drawer disables its own focus restoration; the pane
+restores focus once after a real close. Moving an already-open pane across the
+breakpoint neither restores focus nor emits a false close event.
 
 ## `MlvPage`
 
@@ -140,8 +224,29 @@ border ramp, text and focus tokens).
 | `stickyHeader` | `boolean`        | `true`       | Makes a projected `mlv-page-header` sticky within the page scroll area. |
 | `snapRange`    | `number`         | `96`         | Scroll distance in px mapped onto the full 0..1 snap timeline.          |
 
+`MlvPage` also exposes its snap controller as a `snap` getter, so a component
+that only _hosts_ the page (and therefore cannot inject the controller) can
+reach it with `viewChild(MlvPage).snap` — see `expand()` below.
+
 The anchored surface rounds only the top corners. This makes the page read as one continuous canvas rather than a detached card floating inside the application shell.
 
+The host rounds its border box and publishes the matching _padding_-box curve as
+`--mlv-page-surface-radius` (`calc(var(--mlv-radius-xl) - 0.0625rem)` when
+anchored, `0rem` when flat). A **first-child** `mlv-page-header` /
+`mlv-page-summary` consumes it for its own top corners; full-bleed chrome
+further down the page stays square.
+
+That radius cannot be left to the host's `overflow: clip`. The header and the
+summary strip paint a glass surface with `backdrop-filter`, and a filtered
+backdrop is composited into a backdrop root that an ancestor's _rounded_
+overflow clip never reaches — verified in Chromium: forcing
+`backdrop-filter: none` on the header rounds the corners, restoring the blur
+squares them off again. Clipping on `.mlv-page__inner` is **not** the
+alternative: `overflow` there makes `__inner` the nearest scroll container for
+the sticky header, and `__inner` scrolls with the content, so the header would
+stop sticking — and every inline-rendered overlay would be cut off at the canvas
+edge.
+
 ### Chrome surface (glass)
 
 Header, summary strip, and dock share the `mlv-action-bar` glass recipe:
@@ -199,11 +304,32 @@ manually (skipped under `prefers-reduced-motion`).
 Controller API: `progress`/`pinned`/`snapped`/`spacerScale` signals,
 `toggle()` (snap fully open/closed — a manual pin, otherwise the next scroll
 event would undo it; collapsing also tweens `spacerScale` to 0 so the
-compensation spacer is reclaimed), `setPinned(boolean)` (freeze at the
+compensation spacer is reclaimed), `expand()` / `collapse()` (the same manual
+pin, driven imperatively), `setPinned(boolean)` (freeze at the
 current progress / release back to scroll-following). Pin origin matters: a
 manual (chevron) pin survives everywhere with the spacer reclaimed; a
 scroll-origin (pin button) pin auto-releases at the top of the page.
 
+**`expand()` also reveals collapsed chrome for a programmatic focus.** A
+collapsed snap region is `visibility: hidden`, so a consumer's `focus()` on a
+control inside it is silently refused. `expand()` therefore reveals every
+registered region **synchronously**, before its own tween runs, so the naive
+sequence works:
+
+```ts
+// A component that hosts the page reaches the controller through the page.
+private readonly page = viewChild.required(MlvPage);
+
+onEscapeToTop(): void {
+  this.page().snap.expand();
+  this.activeHeaderTab()?.focus();
+}
+```
+
+A component _inside_ `main[mlvPage]` injects `MlvPageSnapController` directly
+instead. `revealing` (`@internal`) is the bridge flag the regions read between
+the call and the tween leaving their window.
+
 ### `MlvPageSnap` (`[mlvPageSnap]`)
 
 Every element can define its own state on the snap timeline: the directive
@@ -217,9 +343,30 @@ behaviour — `hide` (height + opacity collapse, default), `fade`, or `keep`.
 | `snapSize`            | `'3rem'`  | Nominal expanded size for the `hide` height scrub.     |
 
 Fully elapsed `hide`/`fade` elements get `visibility: hidden` so they leave
-the accessibility tree and tab order. The behaviour CSS lives in `page.scss`
+the accessibility tree and tab order — a control nobody can see must not be an
+invisible tab stop. The behaviour CSS lives in `page.scss`
 (`.mlv-page-snap--hide/--fade`), so it is only active inside a page.
 
+**Focus contract (`MlvPageSnapRegionBase`).** The collapse is driven by
+_scrolling_, not by a user action, so hiding it unconditionally would let a
+scroll blur whatever the user had focused — the browser drops that focus to
+`<body>` and the next Tab restarts at the top of the page. A region therefore
+**never hides while it holds focus**: `focusin`/`focusout` (with a
+`relatedTarget` containment test, so moving between two controls inside the
+region does not count as leaving) drive a `mlv-page-snap--revealed` /
+`mlv-page-summary--revealed` class that zeroes the region's local
+`--mlv-snap-progress`, taking it off the timeline until focus leaves. Nothing
+relocates focus, and the mouse-only scrub — nothing focused — is unchanged.
+`MlvPageSnap` and `MlvPageSummary` share the contract through
+`MlvPageSnapRegionBase`; a subclass supplies its own end-of-window test and
+binds `_hidden()` / `_revealed()` plus the two focus listeners in its `host`.
+
+The base also implements the `MlvPageSnapRegion` methods the controller calls —
+`reveal()` lifts the hide immediately (ahead of change detection, so a
+same-task `focus()` lands) and `syncHiddenState()` re-applies it when the
+reveal window closes without a render in between. Both are controller
+plumbing; consumers call `expand()`, never these.
+
 ## `MlvPageHeader`
 
 The header renders a predictable hierarchy for breadcrumb/back navigation, one semantic page title, inline status, actions, supporting description, metadata, and a tabs row. All content areas are optional structural template slots.
@@ -275,8 +422,12 @@ collapse/expand and pinning are driven by the header's snap controls through
 `MlvPageSnapController` — the strip itself just scrubs its height (against a
 `ResizeObserver`-measured natural row height) and opacity from
 `--mlv-page-snap` over its stagger window, and turns `visibility: hidden`
-once fully collapsed. Breaking change: the former `collapsed`/`pinned`
-models, `collapseOnScroll`, and the strip-owned controls were removed.
+once fully collapsed — unless it holds focus, in which case it reveals itself
+(`mlv-page-summary--revealed`) rather than let a scroll blur a projected
+interactive fact into `<body>`; see the snap focus contract above. Breaking
+change: the former `collapsed`/`pinned` models, `collapseOnScroll`, and the
+strip-owned controls were removed. As a `MlvPageSnapRegionBase` subclass it
+also carries the controller-facing `reveal()` / `syncHiddenState()` pair.
 
 | Input          | Type     | Default          | Description                              |
 | -------------- | -------- | ---------------- | ---------------------------------------- |
@@ -348,6 +499,12 @@ sticky dock is destroyed or `sticky` goes false.
 | `stackBelow`     | `number`                | `1024`              | Container width in CSS pixels below which the columns stack. |
 | `asideLabel`     | `string`                | `'Related content'` | Accessible name for the aside landmark.                      |
 
+### Aside track reservation
+
+- The complementary grid track exists **only while an `[mlvPageAside]` template is actually projected**. The component sets `mlv-page-content--has-aside` on the host from the same `contentChild(MlvPageAside)` query that renders the `<aside>`, and the SCSS keys the two-track definition (and the stacked two-row definition) on that class.
+- Without an aside the host is a single `minmax(0, 1fr)` track / `'main'` area, so a consumer that projects no aside keeps the full inline size instead of losing `asideWidth` to an empty track. No opt-in input; no `:has()`; consumer-side overrides that collapsed the track are no longer needed.
+- Inline geometry is scoped `--has-aside:not(--stacked)` so the compound `--has-aside.--aside-start` selector cannot out-specify the stacked single-column rules.
+
 ## Usage
 
 ```html
@@ -406,11 +563,14 @@ Record-editor composition (compact header, summary strip, dock):
 - `@angular/cdk/coercion`
 - `@lucide/angular`
 - `@malva-ui/cdk` (`MlvStructural`, `MlvResizeObserverService`)
+- `@malva-ui/cdk/overlay` (`MlvOverlayInitialFocus`)
+- `@malva-ui/cdk/utils` (`MlvBreakpointService`, `MlvBreakpoint`, `mlvNextId`)
 - `@malva-ui/cdk/floating-container` — **SCSS only**: `page-dock.scss` `@use`s
   `floating-container.mixins.scss` for the floating appearance. The mixins are
   inlined at compile time, so this is not a runtime or package dependency (and
   the Nx graph does not model it — see the same arrangement with *(internal)*).
 - `@malva-ui/core/button` (summary chevron/pin controls)
+- `@malva-ui/core/drawer` (compact end-pane renderer)
 - `@malva-ui/core/expand` (summary collapse animation)
 - `@malva-ui/core/link`
 - `@malva-ui/core/scrollbar` (page scroll owner; `viewportElement` feeds the scroll context)

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.