@malva-ui/core 0.1.13 → 0.1.14

package/docs/ai/data-table.md

@@ -9,44 +9,46 @@ Feature-rich data table component for Angular. Accepts a plain `T[]` array or a
 
 ## Public API
 
-| Export                        | Kind           | Description                                                                                                                   |
-| ----------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `MlvDataTable`                | Component      | Main table component (`mlv-data-table`)                                                                                       |
-| `MlvDataTableCell`            | Directive      | `mlvDataTableCell` structural directive for custom cell templates                                                             |
-| `MlvDataTableEditCell`        | Directive      | `mlvDataTableEditCell` structural directive for custom edit-mode cell templates                                               |
-| `MlvDataTableNoData`          | Directive      | `mlvDataTableNoData` structural directive for custom empty-state template                                                     |
-| `MlvDataTableError`           | Directive      | `mlvDataTableError` structural directive for custom failed-request template                                                   |
-| `MlvDataTableErrorContext`    | Interface      | Error template context (`{ $implicit: message, retry }`)                                                                      |
-| `MlvDataTableFooter`          | Directive      | `mlvDataTableFooter` structural directive for custom footer summary row templates                                             |
-| `MlvDataSource<T>`            | Abstract class | Base class for custom data sources — re-exported from `@malva-ui/cdk/data-source`                                             |
-| `MlvArrayDataSource<T>`       | Class          | In-memory data source — handles filtering, sorting, pagination. Re-exported from `@malva-ui/cdk/data-source`                  |
-| `MlvDataSourceState`          | Interface      | Serialisable source snapshot — re-exported from `@malva-ui/cdk/data-source`                                                   |
-| `MlvDataTableColumn<T>`       | Interface      | Column definition type                                                                                                        |
-| `MlvDataTableColumnGroup`     | Interface      | Column group definition for multi-row headers                                                                                 |
-| `MlvFilterState`              | Interface      | Active filter state (`{ key, operator, value }`)                                                                              |
-| `MlvDataSourceFilterOperator` | Type           | `'contains' \| 'not-contains' \| 'equals' \| 'not-equals' \| 'in' \| 'not-in'` — re-exported from `@malva-ui/cdk/data-source` |
-| `MlvDataTableFilterOperator`  | Type           | **Deprecated** alias of `MlvDataSourceFilterOperator`                                                                         |
-| `MlvSearchState`              | Interface      | Global query plus the explicit column keys it may inspect                                                                     |
-| `MlvSearchFieldTrigger`       | Type           | `'live' \| 'submit'` search commit strategy                                                                                   |
-| `MlvFilterDisplay`            | Type           | `'toolbar' \| 'column' \| 'none'` filter-control placement                                                                    |
-| `MlvSortState`                | Interface      | Active sort state (`{ key, direction }`)                                                                                      |
-| `MlvSortDirection`            | Type           | `'asc' \| 'desc'`                                                                                                             |
-| `MlvEditMode`                 | Type           | `'row' \| 'cell'`                                                                                                             |
-| `MlvEditEvent<T>`             | Interface      | Row edit start/cancel event (`{ row, index }`)                                                                                |
-| `MlvEditSaveEvent<T>`         | Interface      | Row edit save event (`{ row, index, originalRow }`)                                                                           |
-| `MlvRowClickEvent<T>`         | Interface      | Row click event (`{ row, index, event }`)                                                                                     |
-| `MlvSelectableMode`           | Type           | `'single' \| 'multi' \| false`                                                                                                |
-| `MlvSelectionChangeEvent<T>`  | Interface      | Selection change event (`{ selectedRows, row? }`)                                                                             |
-| `MlvPaginationMode`           | Type           | `'paged' \| 'infinite'` — pagination strategy                                                                                 |
-| `MlvLoadMoreEvent`            | Interface      | Infinite-scroll load-more payload (`{ page, perPage, distance }`)                                                             |
-| `MlvColumnFilterConfig`       | Interface      | Per-column filter options and allowed operators                                                                               |
-| `MlvColumnValueLabels`        | Type           | Raw-value → label map for a column's default cell renderer                                                                    |
-| `MlvColumnToneFn<T>`          | Type           | `(row: T) => MlvTone \| null \| undefined` per-row tone resolver                                                              |
-| `MlvColumnResponsive`         | Type           | Responsive breakpoint map (`Record<string \| number, 'hidden' \| 'visible'>`)                                                 |
-| `MlvColumnAlign`              | Type           | `'left' \| 'center' \| 'right'`                                                                                               |
-| `MlvPinSide`                  | Type           | `'left' \| 'right'` — the side a column can be pinned to                                                                      |
-| `MlvColumnResizeSource`       | Type           | `'pointer' \| 'keyboard' \| 'reset'` resize commit source                                                                     |
-| `MlvColumnResizeEvent`        | Interface      | Committed column key, pixel width or reset, and interaction source                                                            |
+| Export                          | Kind           | Description                                                                                                                   |
+| ------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `MlvDataTable`                  | Component      | Main table component (`mlv-data-table`)                                                                                       |
+| `MlvDataTableCell`              | Directive      | `mlvDataTableCell` structural directive for custom cell templates                                                             |
+| `MlvDataTableEditCell`          | Directive      | `mlvDataTableEditCell` structural directive for custom edit-mode cell templates                                               |
+| `MlvDataTableNoData`            | Directive      | `mlvDataTableNoData` structural directive for custom empty-state template                                                     |
+| `MlvDataTableError`             | Directive      | `mlvDataTableError` structural directive for custom failed-request template                                                   |
+| `MlvDataTableErrorContext`      | Interface      | Error template context (`{ $implicit: message, retry }`)                                                                      |
+| `MlvDataTableFooter`            | Directive      | `mlvDataTableFooter` structural directive for custom footer summary row templates                                             |
+| `MlvDataTableToolbarActions`    | Directive      | `mlvDataTableToolbarActions` optional host-action template rendered last in the Data Table toolbar                            |
+| `MlvDataSource<T>`              | Abstract class | Base class for custom data sources — re-exported from `@malva-ui/cdk/data-source`                                             |
+| `MlvArrayDataSource<T>`         | Class          | In-memory data source — handles filtering, sorting, pagination. Re-exported from `@malva-ui/cdk/data-source`                  |
+| `MlvDataSourceState`            | Interface      | Serialisable source snapshot — re-exported from `@malva-ui/cdk/data-source`                                                   |
+| `MlvDataTableColumn<T>`         | Interface      | Column definition type                                                                                                        |
+| `MlvDataTableColumnGroup`       | Interface      | Column group definition for multi-row headers                                                                                 |
+| `MlvFilterState`                | Interface      | Active filter state (`{ key, operator, value }`)                                                                              |
+| `MlvDataSourceFilterOperator`   | Type           | `'contains' \| 'not-contains' \| 'equals' \| 'not-equals' \| 'in' \| 'not-in'` — re-exported from `@malva-ui/cdk/data-source` |
+| `MlvDataTableFilterOperator`    | Type           | **Deprecated** alias of `MlvDataSourceFilterOperator`                                                                         |
+| `MlvSearchState`                | Interface      | Global query plus the explicit column keys it may inspect                                                                     |
+| `MlvSearchFieldTrigger`         | Type           | `'live' \| 'submit'` search commit strategy                                                                                   |
+| `MlvFilterDisplay`              | Type           | `'toolbar' \| 'column' \| 'none'` filter-control placement                                                                    |
+| `MlvSortState`                  | Interface      | Active sort state (`{ key, direction }`)                                                                                      |
+| `MlvSortDirection`              | Type           | `'asc' \| 'desc'`                                                                                                             |
+| `MlvEditMode`                   | Type           | `'row' \| 'cell'`                                                                                                             |
+| `MlvEditEvent<T>`               | Interface      | Row edit start/cancel event (`{ row, index }`)                                                                                |
+| `MlvEditSaveEvent<T>`           | Interface      | Row edit save event (`{ row, index, originalRow }`)                                                                           |
+| `MlvRowClickEvent<T>`           | Interface      | Row click event (`{ row, index, event }`)                                                                                     |
+| `MlvSelectableMode`             | Type           | `'single' \| 'multi' \| false`                                                                                                |
+| `MlvSelectionChangeEvent<T>`    | Interface      | Selection change event (`{ selectedRows, row? }`)                                                                             |
+| `MlvPaginationMode`             | Type           | `'paged' \| 'infinite'` — pagination strategy                                                                                 |
+| `MlvLoadMoreEvent`              | Interface      | Infinite-scroll load-more payload (`{ page, perPage, distance }`)                                                             |
+| `MlvColumnFilterConfig`         | Interface      | Per-column filter options and allowed operators                                                                               |
+| `MlvColumnValueLabels`          | Type           | Raw-value → label map for a column's default cell renderer                                                                    |
+| `MlvColumnToneFn<T>`            | Type           | `(row: T) => MlvTone \| null \| undefined` per-row tone resolver                                                              |
+| `MlvColumnResponsive`           | Type           | Responsive breakpoint map (`Record<string \| number, 'hidden' \| 'visible'>`)                                                 |
+| `MlvColumnAlign`                | Type           | `'left' \| 'center' \| 'right'`                                                                                               |
+| `MlvPinSide`                    | Type           | `'left' \| 'right'` — the side a column can be pinned to                                                                      |
+| `MlvColumnResizeSource`         | Type           | `'pointer' \| 'keyboard' \| 'reset'` resize commit source                                                                     |
+| `MlvColumnResizeEvent`          | Interface      | Committed column key, pixel width or reset, and interaction source                                                            |
+| `MlvDataTablePresentationState` | Interface      | Durable sort, visible/pinned columns, committed width overrides, and items-per-page snapshot                                  |
 
 ---
 
@@ -79,6 +81,7 @@ Feature-rich data table component for Angular. Accepts a plain `T[]` array or a
 | `loading`                 | `BooleanInput`                         | `false`     | Show a centered loading overlay (spinner) on top of the table body                                                                                                                                                       |
 | `error`                   | `boolean \| string`                    | `false`     | Failed-request state. `true` uses the localized default message, a non-empty string is used verbatim. Replaces the table body while set and not loading. See "Error State" below.                                        |
 | `showSearch`              | `BooleanInput`                         | `true`      | Render the built-in toolbar search field when searchable columns exist. Set to `false` when an external control owns search; `searchQuery` and searchable-column behavior remain active.                                 |
+| `showSortMenu`            | `BooleanInput`                         | `false`     | Render the localized generic Sort menu when at least one column is sortable. Menu actions share header-sort state and presentation-state emissions.                                                                      |
 | `searchTrigger`           | `MlvSearchFieldTrigger`                | `'live'`    | Commit the built-in search field live after its debounce or only on explicit submit                                                                                                                                      |
 | `searchDebounce`          | `number`                               | `200`       | Trailing delay in milliseconds for live search; values below zero are clamped to zero                                                                                                                                    |
 | `searchQuery`             | `string` (model)                       | `''`        | Applied global query. It searches only columns marked `searchable` and can be controlled externally even when `showSearch` is false                                                                                      |
@@ -94,17 +97,18 @@ Feature-rich data table component for Angular. Accepts a plain `T[]` array or a
 
 #### Outputs
 
-| Output            | Type                      | Description                                                                                                                 |
-| ----------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `rowEditStart`    | `MlvEditEvent`            | Emits when a row enters edit mode                                                                                           |
-| `rowEditSave`     | `MlvEditSaveEvent`        | Emits when the user confirms edits on a row                                                                                 |
-| `rowEditCancel`   | `MlvEditEvent`            | Emits when the user cancels editing a row                                                                                   |
-| `rowAdd`          | `void`                    | Emits when the user clicks "Add row"                                                                                        |
-| `rowClick`        | `MlvRowClickEvent`        | Emits when the user clicks any data row (not including selection checkbox clicks)                                           |
-| `selectionChange` | `MlvSelectionChangeEvent` | Emits whenever the row selection changes                                                                                    |
-| `retry`           | `void`                    | Emits when the error block's retry control is activated. The consumer refetches and clears `error`                          |
-| `columnResize`    | `MlvColumnResizeEvent`    | Emits committed pointer/keyboard widths and resets so consumers can persist column state                                    |
-| `loadMore`        | `MlvLoadMoreEvent`        | Emits in infinite mode when the user scrolls within `infiniteScrollThreshold` of the bottom (`{ page, perPage, distance }`) |
+| Output                    | Type                            | Description                                                                                                                        |
+| ------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `rowEditStart`            | `MlvEditEvent`                  | Emits when a row enters edit mode                                                                                                  |
+| `rowEditSave`             | `MlvEditSaveEvent`              | Emits when the user confirms edits on a row                                                                                        |
+| `rowEditCancel`           | `MlvEditEvent`                  | Emits when the user cancels editing a row                                                                                          |
+| `rowAdd`                  | `void`                          | Emits when the user clicks "Add row"                                                                                               |
+| `rowClick`                | `MlvRowClickEvent`              | Emits when the user clicks any data row (not including selection checkbox clicks)                                                  |
+| `selectionChange`         | `MlvSelectionChangeEvent`       | Emits whenever the row selection changes                                                                                           |
+| `retry`                   | `void`                          | Emits when the error block's retry control is activated. The consumer refetches and clears `error`                                 |
+| `columnResize`            | `MlvColumnResizeEvent`          | Emits committed pointer/keyboard widths and resets so consumers can persist column state                                           |
+| `presentationStateChange` | `MlvDataTablePresentationState` | Emits one normalized durable-presentation snapshot after a user sort, visibility, pin, committed resize/reset, or page-size action |
+| `loadMore`                | `MlvLoadMoreEvent`              | Emits in infinite mode when the user scrolls within `infiniteScrollThreshold` of the bottom (`{ page, perPage, distance }`)        |
 
 `selectedRows`, `searchQuery`, and `activeFilters` are `model()`s, so they also
 emit `selectedRowsChange`, `searchQueryChange`, and `activeFiltersChange`.
@@ -117,7 +121,7 @@ Density-aware CSS custom properties set on the host cascade through the entire t
 
 | Variable                    | Tight         | Compact       | Comfortable   | Spacious      | Airy          |
 | --------------------------- | ------------- | ------------- | ------------- | ------------- | ------------- |
-| `--mlv-dt-row-height`       | `2.5rem`      | `3rem`        | `3.5rem`      | `4.25rem`     | `5rem`        |
+| `--mlv-dt-row-height`       | `2.75rem`     | `3.25rem`     | `3.75rem`     | `4.25rem`     | `4.75rem`     |
 | `--mlv-dt-cell-padding-x`   | `0.75rem`     | `1rem`        | `1.25rem`     | `1.5rem`      | `1.75rem`     |
 | `--mlv-dt-header-height`    | `2.25rem`     | `2.5rem`      | `3rem`        | `3.25rem`     | `3.75rem`     |
 | `--mlv-dt-font-size`        | `font-size-s` | `font-size-s` | `font-size-m` | `font-size-l` | `font-size-l` |
@@ -131,6 +135,7 @@ Density-aware CSS custom properties set on the host cascade through the entire t
 - `mlvDataTableNoData` — custom empty-state template shown when filtered data is empty
 - `mlvDataTableError` — custom failed-request template; context: `{ $implicit: message, retry: () => void }`
 - `mlvDataTableFooter` — custom footer summary row template rendered inside `<tfoot>`; context: `{ $implicit: visibleColumns }`
+- `mlvDataTableToolbarActions` — optional host-owned action template rendered after table-owned Search, Sort, Columns, and Filter controls in the single toolbar
 
 #### Internal state (signals on the component instance)
 
@@ -162,6 +167,7 @@ inputs/outputs above instead.
 | Tree rows         | `isRowExpanded`, `hasChildren`, `getDepth`, `toggleExpand`                                                                                                                           |
 | Sorting           | `onSortClick`, `getSortDirection`, `getSortLabel`                                                                                                                                    |
 | Column resizing   | `onResizeStart`, `onColumnResizeKeydown`, `getColumnResizeLabel`, `getColumnResizeValue`, `getColumnResizeMin`, `getColumnResizeMax`, `getColumnResizeValueText`, `resetColumnWidth` |
+| Presentation      | `getPresentationState`, `applyPresentationState`                                                                                                                                     |
 
 ---
 
@@ -394,7 +400,7 @@ All three tables share the same `<colgroup>` (rendered via the internal `#colgro
 
 CDK virtual scroll requires a fixed item height so it can compute the positions of non-rendered rows. The `rowHeight` input is passed to `[itemSize]` on the viewport, and each rendered `<tr>` has its height forced via `[style.height.px]="rowHeight()"`.
 
-**`rowHeight` MUST match the actual rendered row height for the active density**, otherwise the viewport will mis-position rows and the table will appear jumpy. See the density table above for the default `--mlv-dt-row-height` per density step (e.g. `56` for comfortable at 3.5rem = 56px).
+**`rowHeight` MUST match the actual rendered row height for the active density**, otherwise the viewport will mis-position rows and the table will appear jumpy. See the density table above for the default `--mlv-dt-row-height` per density step (e.g. `60` for comfortable at 3.75rem = 60px).
 
 ### Viewport height
 
@@ -429,7 +435,7 @@ readonly columns: MlvDataTableColumn[] = [
 ```
 
 ```html
-<mlv-data-table [data]="rows()" [columns]="columns" [virtualScroll]="true" [rowHeight]="56" maxHeight="32rem" />
+<mlv-data-table [data]="rows()" [columns]="columns" [virtualScroll]="true" [rowHeight]="60" maxHeight="32rem" />
 ```
 
 ---
@@ -510,6 +516,35 @@ Internally tracked via the `_hiddenColumns` signal; hidden columns are filtered
 
 ---
 
+## Durable presentation snapshots
+
+`getPresentationState()` returns the durable presentation settings that a host
+may persist with a saved view:
+
+```ts
+interface MlvDataTablePresentationState {
+  readonly sort: MlvSortState | null;
+  readonly visibleColumnKeys: readonly string[];
+  readonly pinnedStartColumnKeys: readonly string[];
+  readonly pinnedEndColumnKeys: readonly string[];
+  readonly columnWidths: Readonly<Record<string, number>>;
+  readonly perPage: number;
+}
+```
+
+Keys are returned in declared-column order. The snapshot intentionally excludes
+the current page, row selection, search, filters, loading/error state, and
+overlays. `applyPresentationState(partial)` changes only supplied fields,
+ignores stale column keys, clamps widths and page size, resets the transient
+page to one, and does not emit an echo. Hosts receive exactly one full,
+normalized `(presentationStateChange)` snapshot after a user sort, column
+visibility action, pin/unpin, committed resize/reset, or items-per-page change;
+page-only movement remains transient. Non-hideable declared columns are always
+restored to the visible list during application, and `Infinity` is preserved as
+the paginator's all-items page-size sentinel.
+
+---
+
 ## Footer Summary Row
 
 Project a `<ng-template mlvDataTableFooter>` into the table to render a summary row inside a `<tfoot>` element. The template receives the current visible columns as its implicit context. Emit semantic `<th>`/`<td>` elements directly; the component owns their density padding, height, vertical alignment, top divider, opaque sticky surface, and bordered-cell separators without requiring consumers to apply private BEM classes.
@@ -810,7 +845,7 @@ Per-cell template helpers are memoized so they no longer allocate a fresh object
 
 ## Styling
 
-**Design philosophy:** Completely flat and borderless — no wrapper chrome, no shadow, no radius on the container. The table sits directly on the page. Visual hierarchy comes from typography and spacing alone. Headers use normal-case text in a muted accent color (`color-mix` of `--mlv-text-action` and `--mlv-text-secondary`), `font-weight-medium`. Row separators are barely visible (`--mlv-border-subtle`), with a slightly heavier `--mlv-border-normal` line between header and body. Summary footers reuse density geometry with a strong top divider and opaque sticky surface. Resize separators remain subtly visible at rest and become explicit on hover, press, or keyboard focus. Sort icons on unsorted columns are completely hidden until hover. Row hover uses `--mlv-background-sunken`. Row heights are generous (3.5rem comfortable, up to 5rem airy) to support rich multi-line cell content.
+**Design philosophy:** Completely flat and borderless — no wrapper chrome, no shadow, no radius on the container. The table sits directly on the page. Visual hierarchy comes from typography and spacing alone. Headers use normal-case text in a muted accent color (`color-mix` of `--mlv-text-action` and `--mlv-text-secondary`), `font-weight-medium`. Row separators are barely visible (`--mlv-border-subtle`), with a slightly heavier `--mlv-border-normal` line between header and body. Summary footers reuse density geometry with a strong top divider and opaque sticky surface. Resize separators remain subtly visible at rest and become explicit on hover, press, or keyboard focus. Sort icons on unsorted columns are completely hidden until hover. Row hover uses `--mlv-background-neutral-1-hover` — the gentle neutral interactive hover step, not `--mlv-background-sunken` (a static recessed-tray surface token; using it for hover made the row read as pressed rather than hovered). Row heights are generous (3.75rem comfortable, up to 4.75rem airy) to support rich multi-line cell content.
 
 **BEM block:** `.mlv-data-table`
 
@@ -913,5 +948,5 @@ readonly rows = signal<Transaction[]>(generateLargeDataset(10_000));
 ```
 
 ```html
-<mlv-data-table [data]="rows()" [columns]="columns" [virtualScroll]="true" [rowHeight]="56" maxHeight="32rem" />
+<mlv-data-table [data]="rows()" [columns]="columns" [virtualScroll]="true" [rowHeight]="60" maxHeight="32rem" />
 ```

package/docs/ai/dialog.md

@@ -31,32 +31,35 @@ Migration from the previous API: [docs/migrations/2026-08-dialog-composition.md]
 
 Exported from `@malva-ui/core/dialog`:
 
-| Export                             | Kind                                        | Description                                                                                                         |
-| ---------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
-| `MlvDialog`                        | Component                                   | The dialog surface — `mlv-dialog`. Root of every dialog's content.                                                  |
-| `MlvDialogHeader`                  | Component                                   | Header row (title + close button) — `mlv-dialog-header, [mlvDialogHeader]`.                                         |
-| `MlvDialogBody`                    | Component                                   | Scrollable body backed by `mlv-scrollbar` — `mlv-dialog-body, [mlvDialogBody]`.                                     |
-| `MlvDialogFooter`                  | Component                                   | Action row — `mlv-dialog-footer, [mlvDialogFooter]`.                                                                |
-| `MlvDialogFooterAlign`             | Type alias                                  | `'start' \| 'end' \| 'center' \| 'between'`.                                                                        |
-| `MlvDialogClose`                   | Directive                                   | Closes the enclosing dialog on click, with an optional result — `[mlvDialogClose]`.                                 |
-| `MlvDialogTemplate`                | Directive                                   | Declarative two-way sugar over the service — `ng-template[mlvDialog]`, `exportAs: 'mlvDialog'`.                     |
-| `MlvDialogService`                 | Service (`providedIn: 'root'`)              | `open()` / `confirm()` / `closeAll()` / `openDialogs`.                                                              |
-| `MlvDialogRef<R, D>`               | Class                                       | Handle for one open dialog: close, results, config, animation state.                                                |
-| `MlvDialogAnimationState`          | Type alias                                  | `'enter' \| 'idle' \| 'leave'`.                                                                                     |
-| `MlvDialogConfig<D>`               | Interface                                   | Per-open configuration, shared by `open()` and `mlvDialogOptions`.                                                  |
-| `MlvDialogContent<R, D>`           | Type alias                                  | `string \| TemplateRef<MlvDialogTemplateContext<R, D>> \| Type<unknown>`.                                           |
-| `MlvDialogTemplateContext<R, D>`   | Interface                                   | `$implicit`, `ref`, `data`, `config` exposed to `TemplateRef` content.                                              |
-| `MlvDialogSize`                    | Type alias                                  | `MlvDialogSizePreset \| (string & {}) \| MlvDialogSizeConfig`.                                                      |
-| `MlvDialogSizePreset`              | Type alias                                  | `'s' \| 'm' \| 'l' \| 'fullscreen'`.                                                                                |
-| `MlvDialogSizeConfig`              | Interface                                   | Explicit `width`/`height`/`min*`/`max*` dimensions.                                                                 |
-| `MlvDialogSizePresets`             | Type alias                                  | `Record<string, MlvDialogSizeConfig>`.                                                                              |
-| `MlvDialogAppearance`              | Type alias                                  | `'default' \| 'confirm'`.                                                                                           |
-| `MlvDialogRole`                    | Type alias                                  | `'dialog' \| 'alertdialog'`.                                                                                        |
-| `DIALOG_DATA`                      | `InjectionToken<unknown>`                   | Angular CDK's `DIALOG_DATA`, re-exported under the same name. Same token identity, so either import injects `data`. |
-| `DIALOG_CONFIG`                    | `InjectionToken<Readonly<MlvDialogConfig>>` | The consumer's config for the current dialog, injectable by content and parts.                                      |
-| `DIALOG_SIZE_PRESETS`              | `InjectionToken<MlvDialogSizePresets>`      | Registered size presets; override to change or add presets app-wide.                                                |
-| `MlvConfirmDialogOptions`          | Interface                                   | Options for `MlvDialogService.confirm()`.                                                                           |
-| `mlvGenerateRoutableDialogRoute()` | Function                                    | Builds a `Route` that opens a component inside a dialog when activated.                                             |
+| Export                             | Kind                                        | Description                                                                                                             |
+| ---------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `MlvDialog`                        | Component                                   | The dialog surface — `mlv-dialog`. Root of every dialog's content.                                                      |
+| `MlvDialogHeader`                  | Component                                   | Header row (title + close button) — `mlv-dialog-header, [mlvDialogHeader]`.                                             |
+| `MlvDialogBody`                    | Component                                   | Scrollable body backed by `mlv-scrollbar` — `mlv-dialog-body, [mlvDialogBody]`.                                         |
+| `MlvDialogFooter`                  | Component                                   | Action row — `mlv-dialog-footer, [mlvDialogFooter]`.                                                                    |
+| `MlvDialogFooterAlign`             | Type alias                                  | `'start' \| 'end' \| 'center' \| 'between'`.                                                                            |
+| `MlvDialogClose`                   | Directive                                   | Closes the enclosing dialog on click, with an optional result — `[mlvDialogClose]`.                                     |
+| `MlvDialogTemplate`                | Directive                                   | Declarative two-way sugar over the service — `ng-template[mlvDialog]`, `exportAs: 'mlvDialog'`.                         |
+| `MlvDialogService`                 | Service (`providedIn: 'root'`)              | `open()` / `confirm()` / `closeAll()` / `openDialogs`.                                                                  |
+| `MlvDialogRef<R, D>`               | Class                                       | Handle for one open dialog: close, results, config, animation state.                                                    |
+| `MlvDialogAnimationState`          | Type alias                                  | `'enter' \| 'idle' \| 'leave'`.                                                                                         |
+| `MlvDialogConfig<D>`               | Interface                                   | Per-open configuration, shared by `open()` and `mlvDialogOptions`.                                                      |
+| `MlvDialogContent<R, D>`           | Type alias                                  | `string \| TemplateRef<MlvDialogTemplateContext<R, D>> \| Type<unknown>`.                                               |
+| `MlvDialogTemplateContext<R, D>`   | Interface                                   | `$implicit`, `ref`, `data`, `config` exposed to `TemplateRef` content.                                                  |
+| `MlvDialogSize`                    | Type alias                                  | `MlvDialogSizePreset \| (string & {}) \| MlvDialogSizeConfig`.                                                          |
+| `MlvDialogSizePreset`              | Type alias                                  | `'s' \| 'm' \| 'l' \| 'fullscreen'`.                                                                                    |
+| `MlvDialogSizeConfig`              | Interface                                   | Explicit `width`/`height`/`min*`/`max*` dimensions.                                                                     |
+| `MlvDialogSizePresets`             | Type alias                                  | `Record<string, MlvDialogSizeConfig>`.                                                                                  |
+| `MlvDialogAppearance`              | Type alias                                  | `'default' \| 'confirm'`.                                                                                               |
+| `MlvDialogRole`                    | Type alias                                  | `'dialog' \| 'alertdialog'`.                                                                                            |
+| `MlvDialogRestoreFocusTarget`      | Type alias                                  | Static CDK-compatible target: `boolean \| string \| HTMLElement`.                                                       |
+| `MlvDialogRestoreFocusResolver`    | Type alias                                  | `() => MlvDialogRestoreFocusTarget`; evaluated immediately before disposal.                                             |
+| `MlvDialogRestoreFocus`            | Type alias                                  | Static target or late resolver; preserves the default captured-opener behavior while supporting responsive composition. |
+| `DIALOG_DATA`                      | `InjectionToken<unknown>`                   | Angular CDK's `DIALOG_DATA`, re-exported under the same name. Same token identity, so either import injects `data`.     |
+| `DIALOG_CONFIG`                    | `InjectionToken<Readonly<MlvDialogConfig>>` | The consumer's config for the current dialog, injectable by content and parts.                                          |
+| `DIALOG_SIZE_PRESETS`              | `InjectionToken<MlvDialogSizePresets>`      | Registered size presets; override to change or add presets app-wide.                                                    |
+| `MlvConfirmDialogOptions`          | Interface                                   | Options for `MlvDialogService.confirm()`.                                                                               |
+| `mlvGenerateRoutableDialogRoute()` | Function                                    | Builds a `Route` that opens a component inside a dialog when activated.                                                 |
 
 Deliberately **not** exported (implementation details): `MlvDialogContainer`,
 `MlvDialogTextContent` + `MLV_DIALOG_TEXT`, `MlvConfirmDialog` +
@@ -164,6 +167,7 @@ and never instantiated by consumers.
 - Host: `class="mlv-dialog-container"`, `tabindex="-1"`, `[attr.id]`, `[attr.role]`, `[attr.aria-modal]`, `[attr.aria-labelledby]` (suppressed when `ariaLabel` is set), `[attr.aria-label]`, `[attr.aria-describedby]` — restated from the CDK base so the contract sits next to the styles that depend on it.
 - `changeDetection: ChangeDetectionStrategy.Eager` — a **documented exception** to the repo's OnPush rule, matching `CdkDialogContainer` / `MatDialogContainer`. This view is the change-detection parent of arbitrary consumer content (the portal outlet's `ViewContainerRef` lives in it), so an OnPush, non-dirty container would skip refreshing zone-driven content.
 - `_captureInitialFocus()` override: the CDK first focuses the container (`autoFocus: 'dialog'`, which emits `_focusTrapped` so the CDK aria-hides the rest of the page), then — from `afterNextRender`, guarded against a destroyed view — `MlvOverlayInitialFocusResolver` moves focus to the resolved `initialFocus` target.
+- `ngOnDestroy()` evaluates a dynamic `restoreFocus` resolver before delegating to the inherited CDK hook. A consumer resolver exception degrades to `restoreFocus: false`, so focus restoration is skipped while container destruction, overlay disposal, `closed` emission, and registry cleanup continue. The inherited CDK teardown runs outside that consumer-error boundary, so its own exceptions are not hidden.
 
 Its stylesheet is selected as `mlv-dialog-container.mlv-dialog-container`
 (element **and** class): Ivy merges the inherited `cdk-dialog-container`
@@ -287,25 +291,28 @@ granular Escape/backdrop opt-outs. It **never renders chrome**.
 
 `open()` translates `MlvDialogConfig` into the CDK `DialogConfig`:
 
-| `MlvDialogConfig`                                    | CDK `DialogConfig`                                                                                                                                                                                                     |
-| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `size` (preset name or `MlvDialogSizeConfig`)        | `width`/`height`/`minWidth`/`minHeight`/`maxWidth`/`maxHeight` resolved through `DIALOG_SIZE_PRESETS` (an unknown name falls back to `'m'`), each run through `coerceCssPixelValue`.                                   |
-| `panelClass`                                         | `['mlv-dialog-pane', …('mlv-dialog-pane--fullscreen' when the size is the `fullscreen` preset name), ...panelClass]`                                                                                                   |
-| `backdropClass`                                      | `['mlv-dialog-backdrop', ...backdropClass]`                                                                                                                                                                            |
-| `hasBackdrop` (default `true`)                       | `hasBackdrop`                                                                                                                                                                                                          |
-| `closeOnBackdrop` / `closeOnEscape` (default `true`) | `disableClose: true` **always**; the service subscribes to `cdkRef.backdropClick` / `cdkRef.keydownEvents` (Escape without modifiers) itself, so each can be opted out separately and the leave animation still plays. |
-| `initialFocus` (default `'auto'`)                    | `autoFocus: 'dialog'` — the CDK focuses the container, then `MlvDialogContainer` applies the Malva strategy.                                                                                                           |
-| `restoreFocus` (default `true`)                      | `restoreFocus`                                                                                                                                                                                                         |
-| `role` (default `'dialog'`)                          | `role`                                                                                                                                                                                                                 |
-| `ariaLabel` / `ariaLabelledBy` / `ariaDescribedBy`   | passthrough (`null` when unset). For string content with no `title`, `ariaLabel` defaults to the text itself.                                                                                                          |
-| `closeOnNavigation` (default `true`)                 | `closeOnNavigation`                                                                                                                                                                                                    |
-| `data`, `injector`, `id`                             | passthrough (`viewContainerRef` is not exposed)                                                                                                                                                                        |
-| `title`, `closable`, `appearance`                    | not CDK — handed to the content through `DIALOG_CONFIG` and read by `mlv-dialog` / `mlv-dialog-header`.                                                                                                                |
-| —                                                    | `container: MlvDialogContainer` (+ `DIALOG_CONFIG` provider); `templateContext: { $implicit: ref, ref, data, config }`; `providers: (cdkRef) => [MlvDialogRef, DIALOG_CONFIG, (string content: MLV_DIALOG_TEXT)]`      |
+| `MlvDialogConfig`                                    | CDK `DialogConfig`                                                                                                                                                                                                                                                                         |
+| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `size` (preset name or `MlvDialogSizeConfig`)        | `width`/`height`/`minWidth`/`minHeight`/`maxWidth`/`maxHeight` resolved through `DIALOG_SIZE_PRESETS` (an unknown name falls back to `'m'`), each run through `coerceCssPixelValue`.                                                                                                       |
+| `panelClass`                                         | `['mlv-dialog-pane', …('mlv-dialog-pane--fullscreen' when the size is the `fullscreen` preset name), ...panelClass]`                                                                                                                                                                       |
+| `backdropClass`                                      | `['mlv-dialog-backdrop', ...backdropClass]`                                                                                                                                                                                                                                                |
+| `hasBackdrop` (default `true`)                       | `hasBackdrop`                                                                                                                                                                                                                                                                              |
+| `closeOnBackdrop` / `closeOnEscape` (default `true`) | `disableClose: true` **always**; the service subscribes to `cdkRef.backdropClick` / `cdkRef.keydownEvents` (Escape without modifiers) itself, so each can be opted out separately and the leave animation still plays.                                                                     |
+| `initialFocus` (default `'auto'`)                    | `autoFocus: 'dialog'` — the CDK focuses the container, then `MlvDialogContainer` applies the Malva strategy.                                                                                                                                                                               |
+| `restoreFocus` (default `true`)                      | Static targets pass through unchanged. A resolver is held by `MlvDialogContainer`, evaluated immediately before disposal, checked for a connected element/captured opener, then handed to the inherited CDK restore hook. A throwing resolver becomes `false` so disposal still completes. |
+| `role` (default `'dialog'`)                          | `role`                                                                                                                                                                                                                                                                                     |
+| `ariaLabel` / `ariaLabelledBy` / `ariaDescribedBy`   | passthrough (`null` when unset). For string content with no `title`, `ariaLabel` defaults to the text itself.                                                                                                                                                                              |
+| `closeOnNavigation` (default `true`)                 | `closeOnNavigation`                                                                                                                                                                                                                                                                        |
+| `data`, `injector`, `id`                             | passthrough (`viewContainerRef` is not exposed)                                                                                                                                                                                                                                            |
+| `title`, `closable`, `appearance`                    | not CDK — handed to the content through `DIALOG_CONFIG` and read by `mlv-dialog` / `mlv-dialog-header`.                                                                                                                                                                                    |
+| —                                                    | `container: MlvDialogContainer` (+ `DIALOG_CONFIG` provider); `templateContext: { $implicit: ref, ref, data, config }`; `providers: (cdkRef) => [MlvDialogRef, DIALOG_CONFIG, (string content: MLV_DIALOG_TEXT)]`                                                                          |
 
 The config object is frozen by copy at open time, so later mutation of the
-caller's object never changes a live dialog. Content can inject `MlvDialogRef`,
-`DIALOG_CONFIG`, `DIALOG_DATA`, and the CDK's own `DialogRef`.
+caller's object never changes a live dialog. A `restoreFocus` resolver is the
+deliberate exception in behavior: its function identity is frozen, but its
+return value is sampled at actual disposal so responsive state can change while
+the dialog remains open. Content can inject `MlvDialogRef`, `DIALOG_CONFIG`,
+`DIALOG_DATA`, and the CDK's own `DialogRef`.
 
 #### String content
 
@@ -391,27 +398,28 @@ public contract.
 The single configuration object, used by `MlvDialogService.open()`,
 `mlvDialogOptions`, and `mlvGenerateRoutableDialogRoute()`.
 
-| Field               | Type                     | Default       | Description                                                                                  |
-| ------------------- | ------------------------ | ------------- | -------------------------------------------------------------------------------------------- |
-| `size`              | `MlvDialogSize`          | `'m'`         | Preset name or explicit dimensions.                                                          |
-| `appearance`        | `MlvDialogAppearance`    | `'default'`   | `'confirm'` drops the header/footer borders and hides the close button.                      |
-| `title`             | `string`                 | `undefined`   | Plain-text title: string content, the `mlv-dialog-header` fallback, and the accessible name. |
-| `closable`          | `boolean`                | `true`        | Default for `mlv-dialog-header`'s close button.                                              |
-| `panelClass`        | `string \| string[]`     | `undefined`   | Extra class(es) on the overlay pane (`.mlv-dialog-pane`).                                    |
-| `backdropClass`     | `string \| string[]`     | `undefined`   | Extra class(es) on the backdrop (`.mlv-dialog-backdrop`).                                    |
-| `hasBackdrop`       | `boolean`                | `true`        | Whether a backdrop is rendered.                                                              |
-| `closeOnBackdrop`   | `boolean`                | `true`        | Whether a backdrop click closes the dialog.                                                  |
-| `closeOnEscape`     | `boolean`                | `true`        | Whether Escape closes the dialog.                                                            |
-| `closeOnNavigation` | `boolean`                | `true`        | Whether browser history navigation closes the dialog.                                        |
-| `initialFocus`      | `MlvOverlayInitialFocus` | `'auto'`      | Where focus lands once open — see [libs-overlay.md](libs-overlay.md).                        |
-| `restoreFocus`      | `boolean`                | `true`        | Whether focus returns to the previously focused element on close.                            |
-| `role`              | `MlvDialogRole`          | `'dialog'`    | ARIA role of the container.                                                                  |
-| `ariaLabel`         | `string`                 | `undefined`   | Accessible name when no visible title labels the dialog.                                     |
-| `ariaLabelledBy`    | `string`                 | `undefined`   | Id of a labelling element. Wins over `ariaLabel` and the header title.                       |
-| `ariaDescribedBy`   | `string`                 | `undefined`   | Id of a describing element.                                                                  |
-| `data`              | `D`                      | `undefined`   | Payload for `MlvDialogRef.data`, `DIALOG_DATA`, and the template context's `data`.           |
-| `injector`          | `Injector`               | root injector | Parent injector for the content.                                                             |
-| `id`                | `string`                 | CDK-generated | Id of the dialog container.                                                                  |
+| Field               | Type                     | Default       | Description                                                                                    |
+| ------------------- | ------------------------ | ------------- | ---------------------------------------------------------------------------------------------- |
+| `size`              | `MlvDialogSize`          | `'m'`         | Preset name or explicit dimensions.                                                            |
+| `appearance`        | `MlvDialogAppearance`    | `'default'`   | `'confirm'` drops the header/footer borders and hides the close button.                        |
+| `title`             | `string`                 | `undefined`   | Plain-text title: string content, the `mlv-dialog-header` fallback, and the accessible name.   |
+| `closable`          | `boolean`                | `true`        | Default for `mlv-dialog-header`'s close button.                                                |
+| `panelClass`        | `string \| string[]`     | `undefined`   | Extra class(es) on the overlay pane (`.mlv-dialog-pane`).                                      |
+| `backdropClass`     | `string \| string[]`     | `undefined`   | Extra class(es) on the backdrop (`.mlv-dialog-backdrop`).                                      |
+| `hasBackdrop`       | `boolean`                | `true`        | Whether a backdrop is rendered.                                                                |
+| `closeOnBackdrop`   | `boolean`                | `true`        | Whether a backdrop click closes the dialog.                                                    |
+| `closeOnEscape`     | `boolean`                | `true`        | Whether Escape closes the dialog.                                                              |
+| `closeOnNavigation` | `boolean`                | `true`        | Whether browser history navigation closes the dialog.                                          |
+| `direction`         | `MlvDirection`           | resolved      | Text direction for the pane. The pane is portaled to `<body>`, so it never inherits a `[dir]` scope the opener sits in; defaults to the direction resolved from the focused element at open time, then the global direction. |
+| `initialFocus`      | `MlvOverlayInitialFocus` | `'auto'`      | Where focus lands once open — see [libs-overlay.md](libs-overlay.md).                          |
+| `restoreFocus`      | `MlvDialogRestoreFocus`  | `true`        | Captured opener, disabled, selector, explicit element, or a late resolver sampled at disposal. |
+| `role`              | `MlvDialogRole`          | `'dialog'`    | ARIA role of the container.                                                                    |
+| `ariaLabel`         | `string`                 | `undefined`   | Accessible name when no visible title labels the dialog.                                       |
+| `ariaLabelledBy`    | `string`                 | `undefined`   | Id of a labelling element. Wins over `ariaLabel` and the header title.                         |
+| `ariaDescribedBy`   | `string`                 | `undefined`   | Id of a describing element.                                                                    |
+| `data`              | `D`                      | `undefined`   | Payload for `MlvDialogRef.data`, `DIALOG_DATA`, and the template context's `data`.             |
+| `injector`          | `Injector`               | root injector | Parent injector for the content.                                                               |
+| `id`                | `string`                 | CDK-generated | Id of the dialog container.                                                                    |
 
 ### `MlvDialogTemplateContext<R, D>`
 
@@ -748,7 +756,7 @@ export default class UserEditDialog {
 - **Role:** `config.role`, `'dialog'` by default; `'alertdialog'` for interruptions that need an immediate answer — `confirm()` picks it automatically for a destructive/`'danger'` confirmation. Applied to `mlv-dialog-container`, not to the surface.
 - **`aria-modal="false"`** on the container is CDK parity and deliberate: with `aria-modal="true"` assistive tech treats every node outside the container as inert, which would swallow select/menu popups the CDK renders as siblings of the dialog. The CDK `aria-hidden`s the rest of the page instead, which achieves modality without that side effect.
 - **Focus in:** the CDK focuses the container first (so the page is hidden from AT), then `initialFocus` is applied. `'auto'` prefers a projected `[mlvAutofocus]`, then the first tabbable element that is **not** the close button or the body's scroll viewport, then the container.
-- **Focus out:** `restoreFocus` (default `true`) returns focus to the element that was focused before the dialog opened.
+- **Focus out:** `restoreFocus` defaults to `true`, returning focus to the element that was focused before the dialog opened. A CSS selector is resolved at close time; an explicit `HTMLElement` selects a fixed target; `false` disables restoration. A `MlvDialogRestoreFocusResolver` is sampled at actual disposal for responsive composition. When it returns `true`, Malva uses the captured opener only if it is still connected; when it returns an element, that element must be connected. If the resolver throws, restoration is skipped and the complete close/disposal lifecycle still finishes. Existing static boolean/string/element consumers retain their CDK semantics.
 - **Escape / backdrop:** both close by default and are independently opt-out-able (`closeOnEscape`, `closeOnBackdrop`); Escape with a modifier key is ignored. Either way the leave animation plays before disposal.
 - **Keyboard:** focus is trapped by the CDK container; `[mlvDialogClose]` on a `<button>` inherits native Enter/Space activation.
 - **Motion:** the enter/leave keyframes are gated behind `prefers-reduced-motion`, and the ref's 250 ms fallback timer guarantees disposal when no `animationend` ever arrives.
@@ -827,8 +835,8 @@ second exit attempt while the confirmation is already up.
 
 ## Testing
 
-| Spec                                          | Tests | Covers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| --------------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Spec                                          | Tests | Covers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| --------------------------------------------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 
 The routable dialog has no lib spec — it is covered by docs example 6 on
 `/dialog` and by the docs build.
@@ -841,6 +849,7 @@ The routable dialog has no lib spec — it is covered by docs example 6 on
 | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `@angular/cdk/dialog`      | `Dialog` (engine), `DialogRef`, `DialogConfig`, `CdkDialogContainer` (base of `MlvDialogContainer`), `DIALOG_DATA`.                                            |
 | `@angular/cdk/portal`      | `CdkPortalOutlet` in the container template, `ComponentType` in the service signature.                                                                         |
+| `@angular/cdk/platform`    | Shadow-DOM-aware capture of the opener used when a late restore resolver returns `true`.                                                                       |
 | `@angular/cdk/coercion`    | `coerceBooleanProperty` (`closable`), `coerceArray` (panel/backdrop classes), `coerceCssPixelValue` (sizes).                                                   |
 | `@angular/cdk/keycodes`    | `hasModifierKey` — Escape with a modifier does not close.                                                                                                      |
 | `@angular/router`          | `Router`, `ActivatedRoute` in the routable-dialog shell.                                                                                                       |

package/docs/ai/drawer.md

@@ -51,7 +51,7 @@ absent from the public barrel. Drawer-section DOM lookup is scoped to the owning
 
 **Purpose:** Inline template-based drawer. Renders its content inside an Angular CDK Overlay when opened. Handles enter/leave CSS animations, focus trapping, backdrop click / Escape key dismissal.
 
-**Extends:** `MlvOverlayHostBase` from `@malva-ui/cdk/overlay`. The `opened` model, `hasBackdrop`/`closeOnBackdropClick`/`closeOnEscape` inputs, `afterOpened`/`afterClosed` outputs, `animationState` signal, `open()`/`close()`/`onAnimationEnd()` methods, focus-restore, and overlay create/destroy lifecycle are inherited from the shared base. `MlvDrawer` adds only the drawer-specific position/size/resize surface and supplies the backdrop class + edge position strategy. The `opened` + `afterOpened`/`afterClosed` shape is intentionally consistent with `mlv-popup`. 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 `opened` model, no `afterOpened`/`afterClosed`.
+**Extends:** `MlvOverlayHostBase` from `@malva-ui/cdk/overlay`. The `opened` model, `hasBackdrop`/`closeOnBackdropClick`/`closeOnEscape`/`restoreFocus` inputs, `afterOpened`/`afterClosed` outputs, `animationState` signal, `open()`/`close()`/`onAnimationEnd()` methods, optional focus restoration, and overlay create/destroy lifecycle are inherited from the shared base. `MlvDrawer` adds only the drawer-specific position/size/resize surface and supplies the backdrop class + edge position strategy. The `opened` + `afterOpened`/`afterClosed` shape is intentionally consistent with `mlv-popup`. 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 `opened` model, no `afterOpened`/`afterClosed`.
 
 **Inputs (`input()` / `model()`):**
 
@@ -63,6 +63,7 @@ absent from the public barrel. Drawer-section DOM lookup is scoped to the owning
 | `hasBackdrop`          | `input<boolean>`           | `true`    | Whether a dim backdrop is shown behind the drawer                                                                                                                 |
 | `closeOnBackdropClick` | `input<boolean>`           | `true`    | Whether clicking the backdrop closes the drawer                                                                                                                   |
 | `closeOnEscape`        | `input<boolean>`           | `true`    | Whether pressing Escape closes the drawer                                                                                                                         |
+| `restoreFocus`         | `input<boolean>`           | `true`    | Inherited coerced boolean. Restores the connected pre-open focus target after disposal; composed owners can disable it.                                           |
 | `resizable`            | `input<boolean>`           | `false`   | When true, renders a drag handle; enables drag-to-resize and swipe-to-dismiss                                                                                     |
 | `snapPoints`           | `input<number[]>`          | `[]`      | Sorted viewport-percentage snap points (0–100); panel snaps to nearest after drag. Empty = free resize                                                            |
 | `defaultSnap`          | `input<number>`            | `100`     | Initial snap point percentage applied when the drawer opens (only when `resizable=true`)                                                                          |
@@ -111,8 +112,10 @@ absent from the public barrel. Drawer-section DOM lookup is scoped to the owning
 The focus trap keeps Tab inside the panel but **does not auto-capture**: taking
 the first tabbable node landed on the leftmost `mlv-button-close`, popping its
 "Close" tooltip on every open. `MlvOverlayHostBase` applies the `initialFocus`
-strategy instead. Focus is returned to the trigger on close via the component's
-`_triggerElement` restore in `destroyOverlay()`.
+strategy instead. With the inherited `restoreFocus=true` default, focus returns
+to the connected pre-open target on close. Set `restoreFocus=false` when a
+composed parent owns the logical focus lifecycle; disposal then leaves focus
+untouched. Reopening during leave cancels disposal and keeps the Drawer rendered.
 
 **Viewport clamping:** `drawerDimensions` emits `maxWidth`/`maxHeight` alongside
 `width`/`height`. The sizing axis resolves to `min(<maxSize>, 100dvw|100dvh)`
@@ -142,15 +145,15 @@ The `<ng-template>` is projected into a CDK `TemplatePortal` when opened.
 
 **CSS variables:**
 
-| Variable                      | Default                             | Description                                            |
-| ----------------------------- | ----------------------------------- | ------------------------------------------------------ |
-| `--mlv-drawer-enter-duration` | `300ms`                             | Duration of backdrop fade-in                           |
-| `--mlv-drawer-enter-easing`   | `ease-in-out`                       | Easing of backdrop fade-in                             |
-| `--mlv-drawer-leave-duration` | `300ms`                             | Duration of backdrop fade-out                          |
-| `--mlv-drawer-leave-easing`   | `ease-in-out`                       | Easing of backdrop fade-out                            |
-| `--mlv-drawer-current-size`   | _(unset)_                           | Live height/width set by `MlvDrawerResize` during drag |
-| `--mlv-drawer-snap-duration`  | `350ms`                             | Duration of the post-drag spring snap animation        |
-| `--mlv-drawer-snap-easing`    | `cubic-bezier(0.34, 1.56, 0.64, 1)` | Easing of the spring snap animation                    |
+| Variable                      | Default                                                        | Description                                            |
+| ----------------------------- | -------------------------------------------------------------- | ------------------------------------------------------ |
+| `--mlv-drawer-enter-duration` | `300ms`                                                        | Duration of backdrop fade-in                           |
+| `--mlv-drawer-enter-easing`   | `ease-in-out`                                                  | Easing of backdrop fade-in                             |
+| `--mlv-drawer-leave-duration` | `300ms`                                                        | Duration of backdrop fade-out                          |
+| `--mlv-drawer-leave-easing`   | `ease-in-out`                                                  | Easing of backdrop fade-out                            |
+| `--mlv-drawer-current-size`   | _(unset)_                                                      | Live height/width set by `MlvDrawerResize` during drag |
+| `--mlv-drawer-snap-duration`  | `var(--mlv-duration-slow)` (300ms)                             | Duration of the post-drag spring snap animation        |
+| `--mlv-drawer-snap-easing`    | `var(--mlv-ease-spring)` (`cubic-bezier(0.34, 1.56, 0.64, 1)`) | Easing of the spring snap animation                    |
 
 **CSS classes (panel element `mlv-drawer`):**