@malva-ui/core 0.1.12

package/docs/ai/popup.md

@@ -0,0 +1,347 @@
+# Library: popup
+
+## Overview
+
+The Popup library (`@malva-ui/core/popup`) provides a flexible overlay/popover system built on Angular CDK. Supports click/hover/focus trigger types, automatic positioning with fallbacks, optional arrows, animations, focus trapping, and backdrop click.
+
+## Public API
+
+Exported from `@malva-ui/core/popup`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvPopup` | Component | Popup panel — `mlv-popup` |
+| `MlvPopupContent` | Directive | Content slot — `[mlvPopupContent]` |
+| `MlvPopupHeaderContent` | Directive | Full-screen header extension slot — `[mlvPopupHeaderContent]` |
+| `MlvPopupPinnedContent` | Directive | Chrome pinned above the scroll region in every mode — `[mlvPopupPinnedContent]` |
+| `MlvPopupArrowEdge` | Type | `'top' \| 'bottom' \| 'left' \| 'right'` |
+| `MlvPopupArrowAlign` | Type | `'start' \| 'center' \| 'end'` |
+| `MlvPopupTrigger` | Directive | Trigger element — `[mlvPopupTrigger]` |
+| `MlvPopupTriggerType` | Type | `'click' \| 'hover' \| 'focus'` |
+| `MlvPopupContainer` | Component | Programmatic container — `mlv-popup-container` |
+| `MlvPopupService` | Service | Low-level overlay API |
+| `MlvPopupOpenConfig` | Interface | Config for `MlvPopupService.open()` |
+| `MlvPopupHandle` | Interface | `{ overlayRef, close }` |
+| `MlvPopupSizeConfig` | Interface | Size options |
+| `MlvPopupScrollStrategy` | Type | `'reposition' \| 'close' \| 'block' \| 'noop'` |
+| `MlvPopupPositionName` | Type | Union of 12 named positions (`'bottom-end'`, `'top'`, etc.) |
+| `POPUP_POSITIONS` | Token | `InjectionToken<ReadonlyMap<MlvPopupPositionName, ConnectedPosition>>` |
+| `POPUP_POSITION_MAP` | Const | Default map of all 12 named positions |
+| `MlvPopupPositionResolver` | Class | Static helper — `resolve()`, `allPositions()` |
+| `providePopupPositions` | Function | Provider factory to override the position map |
+| `MENU_POSITIONS` | Const | `ConnectedPosition[]` — dropdown-menu placement sequence (`bottom-start`→`top-start`→`bottom-end`→`top-end`), derived from `POPUP_POSITION_MAP`. Consumed by `@malva-ui/core/menu`'s `MlvMenuTrigger`. |
+| `SUBMENU_POSITIONS` | Const | `ConnectedPosition[]` — submenu placement sequence (`right-start`→`left-start`), derived from `POPUP_POSITION_MAP`. Consumed by `MlvMenuTrigger`. |
+
+---
+
+## Components
+
+### `MlvPopup`
+
+- **Selector:** `mlv-popup`
+- **Change Detection:** `OnPush`
+- **Encapsulation:** `None`
+
+#### Model (two-way binding)
+
+| Name     | Type      | Default |
+| -------- | --------- | ------- |
+| `opened` | `boolean` | `false` |
+
+> **Open/close API consistency:** `mlv-popup` already exposes the normalized surface — an `opened` two-way model plus `afterOpened`/`afterClosed` outputs — matching `mlv-drawer`. The dialog no longer shares it: its open state moved to `ng-template[mlvDialog]` / `MlvDialogService` on `@angular/cdk/dialog`, and `mlv-dialog` is now only the presentational surface. No change was needed here during the open/close naming normalization (`mlv-expand` was the outlier and was renamed `open` → `opened`). `mlv-popup` keeps its own trigger/positioning architecture and does **not** extend `@malva-ui/cdk/overlay`'s `MlvOverlayHostBase` (which targets centred/edge modal surfaces).
+
+#### Inputs
+
+| Name                     | Type                                                          | Default     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------ | ------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `position`               | `MlvPopupPositionName \| MlvPopupPositionName[] \| undefined` | `undefined` | Named position(s) — resolved from `POPUP_POSITIONS` map. Array = ordered fallbacks. Takes precedence over `positions`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `positions`              | `ConnectedPosition[] \| undefined`                            | `undefined` | Raw CDK positions for advanced use. Used when `position` is not set.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `width`                  | `number \| string \| undefined`                               | —           | CSS width of the popup panel                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `height`                 | `number \| string \| undefined`                               | —           | CSS height                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `minWidth`               | `number \| string \| undefined`                               | —           | Minimum CSS width                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `minHeight`              | `number \| string \| undefined`                               | —           | Minimum CSS height                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `maxWidth`               | `number \| string \| undefined`                               | —           | Maximum CSS width                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `maxHeight`              | `number \| string \| undefined`                               | —           | Maximum CSS height                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `hasArrow`               | `boolean`                                                     | `false`     | Show arrow pointing to trigger                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `hasShadow`              | `boolean`                                                     | `true`      | Drop shadow                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `class`                  | `string`                                                      | —           | Additional CSS classes on the panel                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `mlvDensity`             | `MlvDensity \| undefined`                                     | `undefined` | Density for the popup content. The panel is portaled to the CDK overlay container on `<body>`, outside any `mlvDensityRoot`/ancestor density cascade — this input restores it: the resolved density (explicit input, else the nearest ancestor `MLV_DENSITY_CONTEXT`, else `MlvDensityService`) is stamped as a `mlv--{density}` class on the panel (`_panelClasses` computed merges it with `class`), so density-aware descendants (e.g. `mlv-list-item` rows) respond via the standard CSS cascade. Consumers with embedded popups (select, combobox, pagination, menu, breadcrumb) forward their own `mlvDensity` input here. |
+| `flexibleDimensions`     | `boolean`                                                     | `false`     | Allow panel to grow to fill viewport                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `panelRole`              | `string \| null`                                              | `null`      | ARIA `role` for the panel. Default `null` — the panel is a neutral chrome/positioning container and the semantic role comes from the projected content (`role="menu"`, `role="listbox"`, `role="tooltip"`). Set to `'dialog'` (with `modal`) for a genuine modal surface.                                                                                                                                                                                                                                                                                                                                                        |
+| `modal`                  | `BooleanInput`                                                | `false`     | When `true`, emits `aria-modal="true"` and enables the CDK focus trap (Tab cycles within the panel). When `false` (default), no `aria-modal` and focus is free to leave — correct for menus/listboxes/tooltips whose focus is managed by their trigger / roving tabindex. When `panelRole === 'dialog'` and `modal` is `true`, provide an accessible name via `ariaLabel`.                                                                                                                                                                                                                                                       |
+| `ariaLabel`              | `string \| undefined`                                         | `undefined` | Accessible name applied as `aria-label` on the panel.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `dismissExcludeElements` | `readonly HTMLElement[]`                                      | `[]`        | Elements treated as "inside" the popup for **click-outside dismissal** in backdrop-less mode (`[hasBackdrop]="false"`). A click within any of these — in addition to the floating panel — does not close the popup. The trigger/anchor lives in normal document flow (outside the panel), so pass it here to stop a click on it dismissing the popup; e.g. `mlv-combobox` passes its input row so caret repositioning keeps the open list open. No effect when a backdrop is used. Forwarded through `MlvPopupContainer` into `MlvPopupService.open`'s `dismissExcludeElements`.                                                 |
+
+> **Breaking change (a11y):** The panel no longer hard-codes `role="dialog" aria-modal="true" cdkTrapFocus`. Panels default to no role, non-modal, no focus trap. Modal-dialog consumers (e.g. `mlv-day-picker`) must opt in via `panelRole="dialog"` + `[modal]="true"`.
+
+#### Mobile fullscreen inputs
+
+Opt-in mechanism that renders the popup as a full-screen mobile sheet (header bar + close button) instead of a trigger-anchored panel. Off by default so existing consumers are byte-identical; the three date/time pickers opt into `mobileMode="auto"`.
+
+| Name               | Type                                 | Default     | Description                                                                                                                                                              |
+| ------------------ | ------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `mobileMode`       | `'auto' \| 'fullscreen' \| 'off'`    | `'off'`     | `'off'` — always anchored (unchanged). `'auto'` — full-screen below `mobileBreakpoint`, anchored above. `'fullscreen'` — always full-screen (useful for demos).          |
+| `mobileBreakpoint` | `MlvBreakpoint` (`'sm'\|'md'\|'lg'`) | `'md'`      | Breakpoint below which `mobileMode="auto"` switches to full-screen. Reads `MlvBreakpointService` (SSR-safe CDK `BreakpointObserver`). Default `'md'` = viewport < 768px. |
+| `mobileTitle`      | `string \| undefined`                | `undefined` | Optional visible heading rendered in the full-screen header bar. When omitted the header shows only the close button.                                                    |
+| `mobileCloseLabel` | `string \| undefined`                | `undefined` | Override for the full-screen close-button accessible name. Falls back to the `MLV_POPUP_I18N` `close` string (`'Close'`).                                                |
+
+Popup content is always rendered inside `.mlv-popup__scrollbar`, a shared `mlv-scrollbar` instance that owns overflow for both anchored popovers and full-screen sheets. In full-screen mode: a global (viewport-filling) CDK position strategy replaces the connected one; a solid backdrop (`.mlv-popup-fullscreen-backdrop`, always on) plus a **block** scroll strategy lock the page behind the sheet without layout shift; the panel gets `.mlv-popup--fullscreen` with safe-area-inset padding, a header (`.mlv-popup__header` with a `.mlv-popup__header-row` for `__title` / `__close`, plus an optional `.mlv-popup__header-content` extension — see below), a scrolling body, and a bottom slide-up animation (fade under `prefers-reduced-motion`). Focus is trapped (`cdkTrapFocus` when `modal() || isFullscreen()`); the close button, backdrop click, and `Escape` all close via the `opened` model so consumer `afterClosed`/focus-restore runs. The overlay decides fullscreen at open time (`MlvPopupService.open`'s `fullscreen` flag, sourced from `isFullscreen()`); the panel chrome tracks the signal reactively.
+
+**Header-content slot (`[mlvPopupHeaderContent]`).** An optional `<ng-template mlvPopupHeaderContent>` is rendered inside the full-screen header, directly beneath the title/close row, via `contentChild(MlvPopupHeaderContent)`. It is **only** stamped while `isFullscreen()` is `true` (and no-ops when the slot is absent), so trigger-anchored popups are byte-identical whether or not the slot is supplied. It exists because the full-screen sheet's solid backdrop + focus trap occlude/block any control that lives outside the overlay panel (in normal document flow): a consumer can move such a control into the sheet by projecting it here. `mlv-combobox` uses it to render an in-sheet search input (and multi-select chips) so type-to-filter keeps working full-screen — see `libs-combobox.md` → _Mobile fullscreen_. The slot sits inside the trapped panel, so projected focusable controls compose with the trap.
+
+**Pinned-content slot (`[mlvPopupPinnedContent]`).** Mode-independent, unlike the header slot: an optional `<ng-template mlvPopupPinnedContent>` is stamped as `.mlv-popup__pinned` directly **above** `.mlv-popup__scrollbar` in both anchored and full-screen panels (in full-screen it lands between `.mlv-popup__header` and the scroll region, still inside the trap). The panel is a flex column and the scrollbar is `flex: 1 1 auto; min-height: 0`, so the pinned block keeps its own height and the scroll region shrinks around it — content can never push it out of view. It carries no padding; the projected block owns its spacing. `mlv-select` uses it for the searchable dropdown's search row (`position: sticky` inside the viewport was fragile — see `libs-select.md` → _Searchable dropdown_).
+
+`isFullscreen: Signal<boolean>` is **public** so consumers with their own inner focus trap (e.g. `mlv-date-range-picker`, whose inner panel carries `cdkTrapFocus`) can disable it via `[cdkTrapFocus]="!popup.isFullscreen()"` and avoid nesting two traps.
+
+#### Outputs
+
+| Name          | Description                    |
+| ------------- | ------------------------------ |
+| `afterOpened` | Emitted when popup enters view |
+| `afterClosed` | Emitted when popup leaves view |
+
+#### Content Children (content slots)
+
+| Query              | Directive               | Stamped where                                                                 |
+| ------------------ | ----------------------- | ----------------------------------------------------------------------------- |
+| `contentRef`       | `MlvPopupContent`       | `.mlv-popup__inner`, inside the scroll region — every mode                    |
+| `headerContentRef` | `MlvPopupHeaderContent` | `.mlv-popup__header-content`, under the title/close row — **fullscreen only** |
+| `pinnedContentRef` | `MlvPopupPinnedContent` | `.mlv-popup__pinned`, directly above the scroll region — **every mode**       |
+
+Each is a `contentChild(...)`; an absent slot stamps nothing, so a popup that
+declares none is byte-identical to one before the slots existed.
+
+#### Internal Signals
+
+- `animationState: signal<'enter' \| 'leave' \| 'idle'>`
+- `arrowEdge: signal<MlvPopupArrowEdge>`
+- `arrowAlign: signal<MlvPopupArrowAlign>`
+- `isFullscreen: computed<boolean>` — **public**; whether the popup is rendering as a full-screen mobile sheet (see Mobile fullscreen inputs)
+
+#### Leave-animation fallback
+
+Overlay disposal is driven by the panel's `(animationend)` → `leaveAnimationDone$`. Because `prefers-reduced-motion` strips the `.mlv-popup--leave` animation entirely (it is gated in `animations.scss`) and hidden/background tabs throttle CSS animations indefinitely, `animationend` may never fire. `MlvPopup` therefore arms a fallback timer (`POPUP_LEAVE_FALLBACK_MS`, 250 ms — matches the dialog's module-level `LEAVE_FALLBACK_MS` in `dialog-ref.ts`) whenever `animationState` becomes `'leave'`; if the real `animationend` hasn't completed the leave by then, the timer invokes `onAnimationEnd()` so the overlay always disposes. The timer is disarmed on any state change and on destroy. Without it, every popup-based overlay (menu, menubar, select, combobox, pickers) would hang open for reduced-motion users.
+
+#### Enter promotion — `beginEnterAnimation()`
+
+- Overlay owners (`MlvPopupContainer`, `MlvPopupTrigger` standalone mode, `MlvMenuTrigger`) set `animationState` to `'idle'` on attach, then promote to `'enter'` from a `queueMicrotask` so the panel is in the DOM before the keyframes start.
+- **Never write `animationState.set('enter')` from that microtask directly** — call `popup.beginEnterAnimation()`, which promotes only while the state is still `'idle'`.
+- Why: a close requested in the same tick as the attach (outside-pointer dismissal, immediate option pick) already moved the state to `'leave'`. Overwriting it wedges the overlay permanently — the leave keyframes never play so no `animationend` arrives, the `'enter'` write itself clears the leave fallback timer without re-arming, and the owner's `_closing` latch blocks both the retry path and any re-open (`open()` returns early while a handle exists). The trigger keeps toggling `aria-expanded` while the panel stays on screen — that mismatch is the tell.
+
+#### Detach watchdog
+
+`POPUP_DETACH_WATCHDOG_MS` (350 ms = leave fallback + 100 ms). `MlvPopupContainer` and `MlvPopupTrigger` arm it when a leave starts and clear it on detach/`onClose`/destroy; if the overlay is still attached and still `_closing` when it fires, they force `_detachOverlay()`. Detaching is what resets `_closing`/`_handle`, so a leave that never completes must still end in a detach — otherwise the owner latches with no path back.
+
+---
+
+### `MlvPopupContainer`
+
+**Selector:** `mlv-popup-container`
+
+Wrapper for programmatic popup management. Required content child: `MlvPopup`.
+
+#### Methods
+
+- `open()` — Open the popup
+- `close()` — Close the popup
+- `toggle()` — Toggle state
+
+---
+
+## Directives
+
+### `MlvPopupTrigger`
+
+**Selector:** `[mlvPopupTrigger]`
+
+#### Inputs
+
+| Name              | Type                                           | Default    |
+| ----------------- | ---------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `mlvPopupTrigger` | `MlvPopup` (required)                          | —          |
+| `triggerOn`       | `MlvPopupTriggerType \| MlvPopupTriggerType[]` | `'click'`  |
+| `ariaHasPopup`    | `string \| null`                               | `'dialog'` | Value for the trigger's `aria-haspopup`. Set to `'menu'`, `'listbox'`, etc. to match the popup content's role, or `null` to omit. |
+
+#### Host Events → Methods
+
+- `(click)` → `onClick()` (toggles if `'click'` trigger)
+- `(mouseenter)` → `onMouseEnter()` (opens if `'hover'`)
+- `(mouseleave)` → `onMouseLeave()` (delayed close if `'hover'`)
+- `(focus)` → `onFocus()` (opens if `'focus'`)
+- `(blur)` → `onBlur()` (closes if `'focus'`)
+
+---
+
+### `MlvPopupContent`
+
+**Selector:** `[mlvPopupContent]` | Provides `templateRef: TemplateRef` for content rendering.
+
+---
+
+### `MlvPopupHeaderContent`
+
+**Selector:** `[mlvPopupHeaderContent]` | 
+
+Marks an `<ng-template>` as a header extension rendered inside the **full-screen** header, beneath the title/close row (`contentChild(MlvPopupHeaderContent)`). Generic and reusable; only stamped while `isFullscreen()` is `true` and a no-op when absent, so anchored popups are unaffected. Used by `mlv-combobox` for its in-sheet search input. Extends `MlvStructural` (provides `templateRef`).
+
+---
+
+### `MlvPopupPinnedContent`
+
+**Selector:** `[mlvPopupPinnedContent]` | 
+
+Marks an `<ng-template>` as chrome pinned above the popup's scroll region (`contentChild(MlvPopupPinnedContent)`), stamped as `.mlv-popup__pinned` directly before `.mlv-popup__scrollbar` in **every** mode — anchored and full-screen alike (in full-screen it sits below `.mlv-popup__header`, inside the sheet's focus trap). Generic and reusable; a no-op when absent. Unlike `[mlvPopupHeaderContent]` — which exists to move outside-the-overlay controls into the full-screen sheet — this slot is about **scroll behaviour**: the projected block keeps its own height while the scroll region shrinks around it, so it can never scroll out of view. Used by `mlv-select` for the searchable dropdown's search row. Extends `MlvStructural` (provides `templateRef`).
+
+---
+
+## Services
+
+### `MlvPopupService`
+
+ | **Provided in:** `root`
+
+#### `resolvePositions(names: MlvPopupPositionName | MlvPopupPositionName[]): ConnectedPosition[]`
+
+Looks up one or more named positions in the active `POPUP_POSITIONS` map and returns the corresponding `ConnectedPosition[]`. CDK uses the first position in the array that fits in the viewport. Unrecognised names are skipped and a `console.warn` is emitted in dev mode.
+
+```ts
+// Single preferred position
+positions: this.popupService.resolvePositions('bottom-end');
+// Preferred + fallback
+positions: this.popupService.resolvePositions(['bottom-end', 'top-end']);
+```
+
+#### `open(config: MlvPopupOpenConfig): MlvPopupHandle`
+
+Creates CDK overlay at origin, attaches template portal, subscribes to position changes, backdrop clicks, and Escape key.
+
+```ts
+interface MlvPopupOpenConfig {
+  origin: ElementRef;
+  template: TemplateRef<unknown>;
+  vcr: ViewContainerRef;
+  positions: ConnectedPosition[];
+  size?: MlvPopupSizeConfig;
+  fullscreen?: boolean; // full-screen mobile sheet: global position strategy, forced solid backdrop, block scroll-lock; ignores positions/size
+  hasBackdrop?: boolean;
+  backdropClass?: string;
+  scrollStrategy?: MlvPopupScrollStrategy;
+  flexibleDimensions?: boolean;
+  dismissExcludeElements?: readonly HTMLElement[]; // trigger/anchor elements treated as "inside" for backdrop-less click-outside detection
+  onClose: () => void;
+  onRequestClose?: () => void;
+  onPositionChange?: (change: ConnectedOverlayPositionChange) => void;
+}
+
+interface MlvPopupHandle {
+  overlayRef: OverlayRef;
+  close: () => void;
+}
+```
+
+`backdropClass` lets consumers replace the default transparent CDK backdrop when they need a styled overlay treatment while keeping the same close behavior.
+
+---
+
+## Named Positions
+
+12 named positions are registered in `POPUP_POSITION_MAP` and resolved via the `POPUP_POSITIONS` token:
+
+| Name           | Side  | Alignment      |
+| -------------- | ----- | -------------- |
+| `top-start`    | Above | Left-aligned   |
+| `top`          | Above | Centered       |
+| `top-end`      | Above | Right-aligned  |
+| `bottom-start` | Below | Left-aligned   |
+| `bottom`       | Below | Centered       |
+| `bottom-end`   | Below | Right-aligned  |
+| `left-start`   | Left  | Top-aligned    |
+| `left`         | Left  | Centered       |
+| `left-end`     | Left  | Bottom-aligned |
+| `right-start`  | Right | Top-aligned    |
+| `right`        | Right | Centered       |
+| `right-end`    | Right | Bottom-aligned |
+
+All positions include an 8 px gap between trigger and panel.
+
+**Resolution order** when `resolvedPositions()` is called on `MlvPopup`:
+
+1. `position` input (named, looked up in map)
+2. `positions` input (raw CDK)
+3. All 12 defaults (CDK auto-picks the first that fits)
+
+**Override globally:**
+
+```ts
+// app.config.ts
+providers: [providePopupPositions(new Map([...POPUP_POSITION_MAP, ['bottom', { originX: 'center', originY: 'bottom', overlayX: 'center', overlayY: 'top', offsetY: 4 }]]))];
+```
+
+---
+
+## CSS Classes
+
+- `.mlv-popup` — background, border, radius, padding, flex column
+- `.mlv-popup--shadow` — `filter: drop-shadow(0 4px 30px rgba(0,0,0,0.16))`
+- `.mlv-popup--arrow` + `.mlv-popup--arrow-{edge}` + `.mlv-popup--arrow-{align}` — positioned arrow via `::before` pseudo-element
+- `.mlv-popup--enter` / `.mlv-popup--leave` — animation state classes
+- `.mlv-popup--fullscreen` — full-screen mobile sheet: fills the pane, no border/radius, safe-area padding, slide-up animation (overrides the `--mlv-popup-*-translate-y` keyframe vars)
+- `.mlv-popup__header` (column) / `.mlv-popup__header-row` (title + close flex row) / `.mlv-popup__title` / `.mlv-popup__close` — full-screen header bar
+- `.mlv-popup__header-content` — optional header extension stamped beneath the title row when `[mlvPopupHeaderContent]` is supplied
+- `.mlv-popup__pinned` — optional non-scrolling block stamped above `.mlv-popup__scrollbar` when `[mlvPopupPinnedContent]` is supplied (`flex: 0 0 auto`, `z-index: 3` so scrolled sticky content passes underneath; no padding of its own)
+- `.mlv-popup-fullscreen-pane` (global) — CDK overlay panel class stretching the pane to the viewport (`100dvh`)
+- `.mlv-popup-fullscreen-backdrop` (global) — solid scrim (`--mlv-background-overlay`) shown behind the sheet
+
+---
+
+## Usage Examples
+
+```html
+<!-- Named position (preferred) -->
+<button [mlvPopupTrigger]="popup">Open</button>
+<mlv-popup #popup position="bottom-end" [hasArrow]="true">
+  <ng-template mlvPopupContent><p>Popup content</p></ng-template>
+</mlv-popup>
+
+<!-- Named position with fallback -->
+<button [mlvPopupTrigger]="popup2">Open</button>
+<mlv-popup #popup2 [position]="['bottom-end', 'top-end']">
+  <ng-template mlvPopupContent><p>Flips to top when no bottom space</p></ng-template>
+</mlv-popup>
+
+<!-- Hover tooltip -->
+<span [mlvPopupTrigger]="tip" triggerOn="hover">Hover me</span>
+<mlv-popup #tip position="top" [hasShadow]="false" [hasArrow]="true">
+  <ng-template mlvPopupContent>Help text</ng-template>
+</mlv-popup>
+
+<!-- Multi-trigger -->
+<input [mlvPopupTrigger]="help" [triggerOn]="['focus', 'hover']" />
+<mlv-popup #help position="bottom-start">
+  <ng-template mlvPopupContent>Field info</ng-template>
+</mlv-popup>
+
+<!-- Programmatic container -->
+<mlv-popup-container #container>
+  <mlv-popup position="right">
+    <ng-template mlvPopupContent>Menu items</ng-template>
+  </mlv-popup>
+</mlv-popup-container>
+<button (click)="container.toggle()">Toggle</button>
+
+<!-- Programmatic service usage -->
+<!-- In component: -->
+<!-- positions: this.popupService.resolvePositions(['bottom', 'top']) -->
+```
+
+---
+
+## Dependencies
+
+- `@angular/cdk/overlay` — overlay, positioning, global/block strategies (full-screen)
+- `@angular/cdk/portal` — `TemplatePortal`
+- `@angular/cdk/a11y` — `cdkTrapFocus`
+- `@lucide/angular` — `LucideX` (full-screen close-button icon)
+- `@malva-ui/cdk/utils` — `MlvBreakpointService` (SSR-safe viewport detection for `mobileMode="auto"`)
+- `@malva-ui/core/scrollbar` — themed overflow for anchored and full-screen popup content
+- `@malva-ui/i18n` — `MLV_POPUP_I18N` (optional; full-screen close-button label, falls back to `'Close'`)

package/docs/ai/progress.md

@@ -0,0 +1,84 @@
+name: libs-progress
+description: Documentation for the @malva-ui/core/progress library — determinate linear and circular progress bar
+type: project
+---
+
+# Library: progress
+
+## Overview
+
+The Progress library (`@malva-ui/core/progress`) provides a standalone determinate progress indicator component — distinct from `mlv-loader` (which handles indeterminate/loading states).
+
+**Features:**
+
+- Linear `bar` and circular `circle` shape variants
+- Determinate only — requires a `value` (0–100)
+- Size variants: `s`, `m` (default), `l`
+- Semantic tone variants: `default`, `success`, `warning`, `danger`, `info`
+- Optional percentage display centered inside circle or beside bar
+- Label slot via `ng-content`
+- SVG `stroke-dashoffset` animation for the circle variant
+- Fully accessible: `role="progressbar"`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-label`
+
+## Public API
+
+Exported from `@malva-ui/core/progress`:
+
+| Export             | Kind      | Description                                                                          |
+| ------------------ | --------- | ------------------------------------------------------------------------------------ |
+| `MlvProgress`      | Component | `mlv-progress` — the main component                                                  |
+| `MlvProgressShape` | Type      | `'bar' \| 'circle'`                                                                  |
+| `MlvProgressSize`  | Type      | `'s' \| 'm' \| 'l'`                                                                  |
+| `MlvProgressTone`  | Type      | `MlvTone \| 'default'` (`'info' \| 'success' \| 'warning' \| 'danger' \| 'default'`) |
+
+## Component: `MlvProgress` (`mlv-progress`)
+
+### Inputs
+
+| Input            | Type               | Default      | Description                            |
+| ---------------- | ------------------ | ------------ | -------------------------------------- |
+| `value`          | `number`           | — (required) | Progress value, clamped to 0–100       |
+| `shape`          | `MlvProgressShape` | `'bar'`      | Linear bar or circular ring            |
+| `size`           | `MlvProgressSize`  | `'m'`        | Size variant                           |
+| `tone`           | `MlvProgressTone`  | `'default'`  | Semantic tone                          |
+| `showPercentage` | `BooleanInput`     | `false`      | Whether to show the numeric percentage |
+| `ariaLabel`      | `string`           | `'Progress'` | Accessible label for the progressbar   |
+
+### Host
+
+- `role="progressbar"`
+- `[attr.aria-valuenow]="value()"`
+- `[attr.aria-valuemin]="0"`, `[attr.aria-valuemax]="100"`
+- `[attr.aria-label]="ariaLabel()"`
+- BEM classes: `mlv-progress`, `mlv-progress--bar/circle`, `mlv-progress--s/m/l`, `mlv-progress--default/success/warning/danger/info`
+
+## SCSS / BEM
+
+Block: `mlv-progress`
+
+| Class                                   | Description                                      |
+| --------------------------------------- | ------------------------------------------------ |
+| `.mlv-progress`                         | Host element                                     |
+| `.mlv-progress__track`                  | Bar: outer track div                             |
+| `.mlv-progress__fill`                   | Bar: inner fill div, `width` driven by `value()` |
+| `.mlv-progress__svg`                    | Circle: SVG element                              |
+| `.mlv-progress__circle-bg`              | Circle: background stroke                        |
+| `.mlv-progress__circle-fill`            | Circle: animated foreground stroke               |
+| `.mlv-progress__percentage`             | Percentage text (inside circle or beside bar)    |
+| `.mlv-progress__label`                  | `ng-content` label slot                          |
+| `--bar` modifier                        | Linear bar layout                                |
+| `--circle` modifier                     | Circular SVG ring                                |
+| `--s/m/l`                               | Size variants                                    |
+| `--default/success/warning/danger/info` | Tone color variants                              |
+
+Tone colors map to `--mlv-palette-success-500`, `--mlv-background-danger-1`, `--mlv-background-warning-1`, `--mlv-palette-info-500` tokens.
+
+## Dependencies
+
+- `@malva-ui/styles` — all `--mlv-*` CSS custom properties
+
+## Notes
+
+- **Not** a replacement for `mlv-loader` — use `mlv-loader` for indeterminate loading spinners/bars.
+- The circle SVG uses `stroke-dasharray` = circumference, `stroke-dashoffset` = circumference × (1 - value/100).
+- Percentage display for circle is centered as an absolutely-positioned span over the SVG.

package/docs/ai/radio.md

@@ -0,0 +1,201 @@
+# Library: radio
+
+## Overview
+
+The Radio library (`@malva-ui/core/radio`) provides accessible radio button components following WAI-ARIA patterns. Includes individual radio buttons and a group component that manages selection state, keyboard navigation (arrow keys), and reactive forms integration.
+
+> **Host `aria-label` / `aria-labelledby` forwarding** — a consumer writing
+> `<mlv-radio aria-label="Select row" />` (e.g. a radio with no projected text)
+> would otherwise leave the attribute on the role-less host element, which ARIA
+> prohibits (axe `aria-prohibited-attr`). `MlvRadio` captures a **static**
+> host `aria-label`/`aria-labelledby` via `HostAttributeToken` in its constructor,
+> imperatively removes it from the host (`Renderer2.removeAttribute`), and forwards
+> it onto the inner `<input type="radio">` — the real accessible-name target —
+> through the `[attr.aria-label]` / `[attr.aria-labelledby]` template bindings
+> (`_ariaLabel` / `_ariaLabelledBy` signals). When no host ARIA attribute is
+> supplied the signals stay `null`, so no empty `aria-label` is emitted on the
+> input and any group-provided labelling mechanism is left untouched. For
+> **dynamic** labels use the `ariaLabel` / `ariaLabelledBy` **inputs** (they win
+> over a captured static attribute via the
+> `_resolvedAriaLabel`/`_resolvedAriaLabelledBy` computeds) — never bind
+> `[attr.aria-label]` on the host, which Angular writes straight onto the host
+> element where it cannot be intercepted. Same pattern as `mlv-checkbox` and
+> `mlv-switch`.
+
+## Public API
+
+Exported from `@malva-ui/core/radio`:
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `MlvRadio` | Component | Radio button — `mlv-radio` |
+| `MlvRadioGroup` | Component | Group container — `mlv-radio-group` |
+| `MlvRadioGroupState` | Type | `'default' \| 'success' \| 'info' \| 'warning' \| 'error'` |
+
+---
+
+## Components
+
+### `MlvRadio`
+
+- **Selector:** `mlv-radio`
+- **Change Detection:** `OnPush`
+- **Focus management:** `MlvRadioGroup` adapts radio instances to `FocusKeyManager` and uses `disabled()` as the skip predicate, preserving `[disabled]` as a signal input.
+
+#### Inputs
+
+| Name             | Type                  | Default     |
+| ---------------- | --------------------- | ----------- |
+| `value`          | `unknown`             | `undefined` |
+| `ariaLabel`      | `string \| undefined` | `undefined` |
+| `ariaLabelledBy` | `string \| undefined` | `undefined` |
+| `disabled`       | `boolean`             | `false`     |
+
+#### Internal Signals
+
+- `checked: signal(false)` — managed by parent group
+- `name: signal('')` — set by parent group
+
+#### Host Bindings
+
+```ts
+host: {
+  'class': 'mlv-radio',
+  '[class.mlv-radio--checked]': 'checked()',
+  '[class.mlv-radio--disabled]': 'disabled()',
+}
+```
+
+The host is **not** focusable. The single focus target is the visually-hidden
+native `<input type="radio">` (kept in the a11y tree via the clip-path pattern,
+which restores native radio grouping and Space selection). Its `tabindex` is the
+roving tabindex (`tabIndex` signal) managed by `MlvRadioGroup`.
+
+#### Key Methods
+
+- `focus()` — CDK `FocusableOption`; focuses the native input (not the host)
+
+#### Internal methods (`@internal`, template-facing)
+
+- `onFocus()` — Notifies parent group
+- `onSelect()` — Native selection (click, Space, arrow keys); calls `group.selectRadio(this)` if not disabled
+
+#### Keyboard & Focus
+
+- **Single tab stop:** the native input carries the roving tabindex; the host is not tabbable.
+- **Space** selects natively; **ArrowUp/ArrowLeft** and **ArrowDown/ArrowRight** move+select within the group (via `FocusKeyManager`, skipping disabled radios, wrapping).
+- **`:focus-visible`** ring is promoted from the hidden input onto `.mlv-radio__visual` using `--mlv-border-focus`.
+
+#### Template Summary
+
+Visually-hidden (clip-path) native `<input #nativeInput type="radio" [attr.tabindex]="tabIndex()">` with `aria-checked` + visual circle indicator (`.mlv-radio__visual::before` for inner dot with CSS transition) + `<ng-content>` for label.
+
+---
+
+### `MlvRadioGroup`
+
+- **Selector:** `mlv-radio-group`
+- **Change Detection:** `OnPush`
+- **Extends:** `MlvSignalFormControlBase<unknown>` from `@malva-ui/core/form-utils`
+- **Implements:** `FormValueControl<unknown>`, `MlvRadioGroupAccessor`
+- **Provides:** `RADIO_GROUP`, `MLV_FORM_CONTROL` tokens
+
+#### Model (two-way binding)
+
+| Name    | Type      |
+| ------- | --------- |
+| `value` | `unknown` |
+
+#### Inputs
+
+| Name       | Type                                    | Default            | Description                                                                                                        |
+| ---------- | --------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `name`     | `string`                                | auto-generated     | Group name for native radios                                                                                       |
+| `disabled` | `boolean`                               | `false`            | _(inherited)_ Disable all radios; also settable via `FormControl.disable()` (merged into `computedDisabled()`)     |
+| `readonly` | `boolean`                               | `false`            | _(inherited)_ Locks selection while keeping the group legible/focusable; reflected as `mlv-radio-group--readonly`  |
+| `state`    | `MlvRadioGroupState` (`= MlvFormState`) | `'default'`        | _(inherited)_ Validation state; reflected as `mlv-radio-group--state-*` with an inline-start accent on the content |
+| `label`    | `string`                                | `''`               | _(inherited)_ Group label (rendered via `mlv-label`)                                                               |
+| `id`       | `string`                                | auto (`mlvNextId`) | _(inherited)_ Bound to the host `id` attribute                                                                     |
+
+> `MlvRadioGroupState` remains exported as a public type alias for backwards compatibility; it is now defined as `MlvFormState` from `@malva-ui/core/form-utils`.
+
+#### Keyboard Navigation
+
+`FocusKeyManager` (vertical, wrapping) — Arrow Up/Down moves focus, skips disabled radios via `disabled()`, and auto-selects the focused radio.
+
+#### Tab Management
+
+Only the checked radio (or first radio if none checked) has `tabIndex=0`. All others are `-1`.
+
+> **Does not use `MlvFocusableGroupBase`** (deliberate). That base is _focus-driven_ roving, whereas radio's tab stop is _selection-driven_ and its arrows couple selection, radio names, and the forms value in the same effect. Adopting the focus-only base would change behavior, so radio keeps its own manager.
+
+#### Template Summary
+
+`div[role="radiogroup"][aria-label]` + optional `mlv-label` + `<ng-content>` + `(keydown)` handler.
+
+#### ARIA
+
+- `role="radiogroup"` on container
+- `[attr.aria-checked]` on native inputs
+- Only active radio is tabbable (`tabIndex=0`)
+
+---
+
+## Internal Token
+
+```ts
+export const RADIO_GROUP = new InjectionToken<MlvRadioGroupAccessor>('RADIO_GROUP');
+
+interface MlvRadioGroupAccessor {
+  selectRadio(radio: MlvRadio): void;
+  onChildFocus(radio: MlvRadio): void;
+}
+```
+
+---
+
+## Usage Examples
+
+```html
+<!-- Basic group -->
+<mlv-radio-group [(value)]="selected">
+  <mlv-radio [value]="'a'">Option A</mlv-radio>
+  <mlv-radio [value]="'b'">Option B</mlv-radio>
+</mlv-radio-group>
+
+<!-- With label -->
+<mlv-radio-group label="Choose size" [(value)]="size">
+  <mlv-radio [value]="'s'">Small</mlv-radio>
+  <mlv-radio [value]="'m'">Medium</mlv-radio>
+  <mlv-radio [value]="'l'">Large</mlv-radio>
+</mlv-radio-group>
+
+<!-- Disabled radio -->
+<mlv-radio-group [(value)]="val">
+  <mlv-radio [value]="1">One</mlv-radio>
+  <mlv-radio [value]="2" [disabled]="true">Two (disabled)</mlv-radio>
+</mlv-radio-group>
+
+<!-- Reactive forms -->
+<mlv-radio-group formControlName="option">
+  <mlv-radio [value]="'yes'">Yes</mlv-radio>
+  <mlv-radio [value]="'no'">No</mlv-radio>
+</mlv-radio-group>
+```
+
+---
+
+## Dependencies
+
+- `@angular/forms/signals` — `FormValueControl` contract
+- `@angular/cdk/a11y` — `FocusKeyManager`, `FocusableOption`
+- `@malva-ui/core/form-utils` — `MlvSignalFormControlBase`, `MLV_FORM_CONTROL`, `MlvFormState`, `MlvLabel`
+- `@malva-ui/cdk/utils` — `mlvNextId` (group `name` default)
+
+---
+
+## Field surface (2026-08)
+
+- `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()`.