@rivinia/modal 0.5.1 → 0.5.3

package/README.md

@@ -1,213 +1,470 @@
 # @rivinia/modal
 
-[![npm version](https://img.shields.io/npm/v/@rivinia/modal.svg)](https://www.npmjs.com/package/@rivinia/modal)
-[![license](https://img.shields.io/npm/l/@rivinia/modal.svg)](https://www.npmjs.com/package/@rivinia/modal)
+An Angular modal manager with typed results, stack/queue admission, dismissal
+policies, async guards, and optional ready-made UI. The core package owns
+modal state and lifecycle but does not render or style dialogs.
 
-Headless modal manager for Angular 22+. Stack/Queue strategies, typed
-`Promise` results, dismissal policies, async guards, ownership — zero DOM,
-zero styles, zero router dependency. A future `@rivinia/modal/ui` entry point
-will render this state; Core never imports UI.
+- Install: `npm install @rivinia/modal`
+- Package version: **0.5.3**
+- Peer dependencies: `@angular/core ^22.0.0` and `@angular/common ^22.0.0`
+- `@rivinia/modal` is the headless manager.
+- `@rivinia/modal/ui` contains standalone dialog and host components.
 
-- Version: **0.5.0**
-- Requires: **Angular `^22.0.0`**, `tslib`
+## Configure the manager
 
-## Install
-
-```bash
-npm install @rivinia/modal
-ng add @rivinia/modal   # wires provideRiviniaModal() into app.config.ts
-```
+Register the provider once in the application's root environment providers.
+The defaults use a stack with up to five visible modals and queue overflow:
 
 ```ts
 // app.config.ts
+import type { ApplicationConfig } from '@angular/core';
 import { provideRiviniaModal } from '@rivinia/modal';
 
-providers: [provideRiviniaModal({ strategy: 'stack', maxVisible: 3 })];
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRiviniaModal({
+      strategy: 'stack',
+      maxVisible: 3,
+      closingTimeout: 300,
+    }),
+  ],
+};
 ```
 
-## Quick start
+`ng add @rivinia/modal` can insert `provideRiviniaModal()` into a detected
+standalone app configuration. It does not add a rendering host; add one as
+described below. You can also configure the provider manually as above.
+
+## Open a typed modal
+
+The examples use standalone components and separate `.ts`/`.html` files. Mount
+one shared `RiviniaModalHost` for the manager. This first version uses the
+classic `@ViewChild` query, which is still supported in Angular 22:
 
 ```ts
-export class Users {
-  private modals = injectRiviniaModal();
+import { Component, TemplateRef, ViewChild, signal } from '@angular/core';
+import type { ModalHandle, ModalTemplateContext } from '@rivinia/modal';
+import { injectRiviniaModal } from '@rivinia/modal';
+import { RiviniaModalHost } from '@rivinia/modal/ui';
+
+interface User {
+  readonly id: string;
+  readonly name: string;
+}
+
+interface DeleteData {
+  readonly id: string;
+  readonly name: string;
+}
+
+@Component({
+  standalone: true,
+  imports: [RiviniaModalHost],
+  templateUrl: './users-page.component.html',
+})
+export class UsersPage {
+  private readonly manager = injectRiviniaModal();
+  protected readonly modals = this.manager;
+  readonly users = signal<User[]>([{ id: '42', name: 'Ada Lovelace' }]);
 
-  async remove(user: User) {
-    const handle = this.modals.openModal<DeleteData, boolean>(confirmTemplate, {
-      data: { name: user.name },
+  @ViewChild('deleteConfirmation', { static: true })
+  private deleteTemplate!: TemplateRef<ModalTemplateContext<DeleteData>>;
+
+  private pendingDelete: ModalHandle<boolean> | null = null;
+
+  async askToDelete(user: User): Promise<void> {
+    if (this.pendingDelete) return;
+
+    const handle = this.manager.openModal<DeleteData, boolean>(this.deleteTemplate, {
+      data: { id: user.id, name: user.name },
       ref: 'confirm-delete',
+      metadata: { title: 'Delete user' },
+      dismiss: { backdrop: 'static' },
     });
-    const result = await handle.result;
-    if (result.status === 'confirmed' && result.value) {
-      this.delete(user);
+    this.pendingDelete = handle;
+
+    try {
+      const result = await handle.result;
+      if (result.status === 'confirmed' && result.value) {
+        this.users.update((users) => users.filter((entry) => entry.id !== user.id));
+      }
+    } finally {
+      if (this.pendingDelete === handle) this.pendingDelete = null;
     }
-    // 'cancelled' | 'dismissed' | 'queued-cancelled' | 'owner-destroyed' | 'rejected'
+  }
+
+  confirmDelete(): void {
+    // ModalHandle<boolean> checks that the confirmed value is a boolean.
+    this.pendingDelete?.close(true);
+  }
+
+  cancelDelete(): void {
+    this.pendingDelete?.cancel('user-cancelled');
   }
 }
 ```
 
-## API
+```html
+<!-- src/app/users-page.component.html -->
+@for (user of users(); track user.id) {
+<button type="button" (click)="askToDelete(user)">Delete {{ user.name }}</button>
+}
 
-| Export                            | Kind         | Purpose                                                                                                                                                        |
-| --------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `provideRiviniaModal(config?)`    | provider     | `{ strategy?, dismiss?, maxVisible?, maxQueue?, overflow?, descendants?, presets?, closingTimeout?, diagnostics? }`                                            |
-| `RiviniaModal`                    | `@Service()` | `openModal/close/dismiss/cancel/requestDismiss/update/confirmClosed/dismissAll/findByRef/useStrategy/debugState` + `active/queued/closing/visible/top` signals |
-| `injectRiviniaModal()`            | function     | shorthand for `inject(RiviniaModal)`                                                                                                                           |
-| `RIVINIA_MODAL_CONTEXT`           | token        | per-instance context for dynamic components                                                                                                                    |
-| `StackStrategy` / `QueueStrategy` | classes      | built-in ordering policies (`ModalStrategy` for custom)                                                                                                        |
-| types                             | types        | `ModalHandle`, `ModalResult`, `ModalContent`, `ModalOpenOptions`, `ModalDismissPolicy`, `ModalGuard`, …                                                        |
+<ng-template #deleteConfirmation let-data>
+  <p>Delete {{ data.name }}?</p>
+  <button type="button" (click)="confirmDelete()">Delete user</button>
+  <button type="button" (click)="cancelDelete()">Cancel</button>
+</ng-template>
 
-Results settle exactly once, at dismissal initiation — exit animations never
-delay callers. `close/dismiss/cancel` are guard-free primitives (booleans);
-`requestDismiss(id, origin)` runs async guards for user intents. Forced paths
-(owner destroy, overflow eviction, `dismissAll`) bypass guards. Render failures
-reject the promise instead of becoming variants.
+<rv-modal-host [modal]="modals" size="sm" />
+```
 
-`openModal` accepts a raw `TemplateRef`, a component `Type`, or a full
-`ModalContent` descriptor (component inputs via `options.inputs`). Dismissal
-policy merges field-by-field: built-in defaults < global `dismiss` < named
-preset < per-call options — absent keys never clobber.
+### Signal-based view query
 
-## Ownership (who cleans up)
+For new code, Angular 22 also supports the `viewChild` signal query. Keep the
+same HTML; call the query signal to get its `TemplateRef`:
 
 ```ts
-// Owned by a short-lived component: dies with it (active → owner-destroyed)
-this.modals.openModal(tpl, { owner: this.destroyRef });
+// src/app/users-page.component.ts
+import { Component, TemplateRef, signal, viewChild } from '@angular/core';
+import type { ModalHandle, ModalTemplateContext } from '@rivinia/modal';
+import { injectRiviniaModal } from '@rivinia/modal';
+import { RiviniaModalHost } from '@rivinia/modal/ui';
+
+interface User {
+  readonly id: string;
+  readonly name: string;
+}
+
+interface DeleteData {
+  readonly id: string;
+  readonly name: string;
+}
+
+@Component({
+  standalone: true,
+  imports: [RiviniaModalHost],
+  templateUrl: './users-page.component.html',
+})
+export class UsersPage {
+  private readonly manager = injectRiviniaModal();
+  protected readonly modals = this.manager;
+  readonly users = signal<User[]>([{ id: '42', name: 'Ada Lovelace' }]);
+  private readonly deleteTemplate =
+    viewChild.required<TemplateRef<ModalTemplateContext<DeleteData>>>('deleteConfirmation');
+  private pendingDelete: ModalHandle<boolean> | null = null;
+
+  async askToDelete(user: User): Promise<void> {
+    if (this.pendingDelete) return;
+
+    const handle = this.manager.openModal<DeleteData, boolean>(this.deleteTemplate(), {
+      data: { id: user.id, name: user.name },
+      ref: 'confirm-delete',
+      metadata: { title: 'Delete user' },
+      dismiss: { backdrop: 'static' },
+    });
+    this.pendingDelete = handle;
+    try {
+      const result = await handle.result;
+      if (result.status === 'confirmed' && result.value) {
+        this.users.update((users) => users.filter((entry) => entry.id !== user.id));
+      }
+    } finally {
+      if (this.pendingDelete === handle) this.pendingDelete = null;
+    }
+  }
+
+  confirmDelete(): void {
+    this.pendingDelete?.close(true);
+  }
 
-// Independent (default): lives until closed — for services and app flows
-this.modals.openModal(tpl);
+  cancelDelete(): void {
+    this.pendingDelete?.cancel('user-cancelled');
+  }
+}
 ```
 
-Owner teardown frees capacity like any other removal: queued requests promote
-normally (a queued request sharing the dead owner is still torn down by its own
-callback, settling `owner-destroyed`). Opening with an already-destroyed owner
-settles `owner-destroyed` immediately without adding anything.
+The UI host uses `metadata.title` by default, so the example renders
+“Delete user” without custom title logic. Import `RiviniaModalHost` into the
+standalone component that renders it. All examples in this guide target
+standalone Angular 22 applications.
 
-Closing a parent cascades to descendants (`dismissed: parent-closed`) unless
-`descendants: 'prevent-parent-close'` blocks it. Swapping strategies with live
-modals throws — close everything first.
+`openModal<TData, TResult>()` accepts a `TemplateRef`, a component type, or a
+`ModalContent<TData>` descriptor. Template content receives `data` as
+`let-data` and the per-modal operations as `let-modal="modal"`. For component
+content, pass `inputs` in the options; those keys are `Record<string, unknown>`
+and are not checked against the component's inputs at compile time. The
+optional `RIVINIA_MODAL_CONTEXT` injection token supplies the same per-modal
+context to a dynamically created component.
 
-## Ready-made UI (`@rivinia/modal/ui`)
+### Component content, modal context, and `NgComponentOutlet`
 
-Optional secondary entry point. Zero new runtime dependencies (platform
-`<dialog>` + Angular only), no design system, no CSS framework. Headless
-consumers never load it (proven: core FESM contains zero UI markers).
+When the content is a component type, the host renders it with Angular's
+`NgComponentOutlet` and creates an injector scoped to that modal instance.
+Inject `RIVINIA_MODAL_CONTEXT` for that instance's `id`, `data`, `close()`, and
+`dismiss()`; ordinary app services still resolve from the surrounding
+injectors. The host supplies this context, so do not build a separate
+`Injector` just to pass modal data or lifecycle operations.
 
 ```ts
-import { RiviniaModalDialog } from '@rivinia/modal/ui'; // UI-only
-import { RiviniaModalHost } from '@rivinia/modal/ui'; // managed adapter
-```
+// src/app/delete-confirmation.component.ts
+import { Component, inject } from '@angular/core';
+import { RIVINIA_MODAL_CONTEXT } from '@rivinia/modal';
+
+@Component({
+  standalone: true,
+  templateUrl: './delete-confirmation.component.html',
+})
+export class DeleteConfirmationComponent {
+  readonly modal = inject(RIVINIA_MODAL_CONTEXT);
+
+  confirm(): void {
+    this.modal.close(true);
+  }
 
-**Mode A — UI-only** (no controller; owns its `open` state):
+  cancel(): void {
+    this.modal.dismiss('user-cancelled');
+  }
+}
+```
 
 ```html
-<rv-modal-dialog [(open)]="open" [title]="'Delete?'" [size]="'sm'" (confirmed)="remove()">
-  <p>Delete {{ user.name }}?</p>
-</rv-modal-dialog>
+<!-- src/app/delete-confirmation.component.html -->
+<h2>Delete this user?</h2>
+<button type="button" (click)="confirm()">Delete</button>
+<button type="button" (click)="cancel()">Cancel</button>
+```
+
+Open the component type through the same manager and host used for template
+content:
+
+```ts
+const handle = this.manager.openModal<DeleteConfirmationComponent, DeleteData, boolean>(
+  DeleteConfirmationComponent,
+  {
+    data: { id: user.id, name: user.name },
+    metadata: { title: 'Delete user' },
+  },
+);
+const result = await handle.result;
+if (result.status === 'confirmed' && result.value) {
+  this.removeUser(user.id);
+}
 ```
 
-**Mode B — headless + custom UI:** keep using `@rivinia/modal` alone.
-Nothing here loads, no styles leak.
+The injection token is typed as `ModalContext<unknown>` because content may
+come from different callers. Narrow or validate `modal.data` before reading
+application-specific fields. The opener's `ModalHandle<boolean>` remains
+typed, so `handle.close()` checks the result type. Component `inputs` can also
+be supplied in `openModal` options, but their keys are not type-checked.
+
+### Showing a toast inside an open modal
+
+The toast list is fixed-position UI, not a popover. A native `<dialog>` is in
+the browser's top layer, so a toast list rendered outside it can appear behind
+the dialog regardless of its `z-index`. When a notification belongs to the
+open modal, put its `RiviniaToastList` inside the modal template so it is
+rendered inside the dialog:
+
+```ts
+// src/app/payment-page.component.ts
+import { Component, TemplateRef, inject, viewChild } from '@angular/core';
+import type { ModalTemplateContext } from '@rivinia/modal';
+import { RiviniaModal } from '@rivinia/modal';
+import { RiviniaModalHost } from '@rivinia/modal/ui';
+import { RiviniaToast } from '@rivinia/toast';
+import { RiviniaToastList } from '@rivinia/toast/ui';
+
+@Component({
+  standalone: true,
+  imports: [RiviniaModalHost, RiviniaToastList],
+  templateUrl: './payment-page.component.html',
+})
+export class PaymentPageComponent {
+  readonly modal = inject(RiviniaModal);
+  readonly toast = inject(RiviniaToast);
+  private readonly paymentTemplate =
+    viewChild.required<TemplateRef<ModalTemplateContext<void>>>('paymentConfirmation');
+
+  openPayment(): void {
+    this.modal.openModal<void, void>(this.paymentTemplate(), {
+      data: undefined,
+      metadata: { title: 'Confirm payment' },
+    });
+  }
 
-**Mode C — headless + ready-made UI** (single source of truth stays Core):
+  showPaymentSaved(): void {
+    this.toast.show({ message: 'Payment saved', kind: 'success' });
+  }
+}
+```
 
 ```html
-<rv-modal-host [modal]="injectRiviniaModal()" />
+<!-- src/app/payment-page.component.html -->
+<button type="button" (click)="openPayment()">Pay invoice</button>
+
+<ng-template #paymentConfirmation let-modal="modal">
+  <p>Submit payment for invoice INV-2048?</p>
+  <button type="button" (click)="showPaymentSaved()">Show saved notice</button>
+  <button type="button" (click)="modal.close()">Done</button>
+  <rv-toast-list [manager]="toast" position="top-end" />
+</ng-template>
+
+<rv-modal-host [modal]="modal" size="sm" />
 ```
 
-Intents (X, Escape, backdrop) route through `requestDismiss` (guards run);
-exits play, then the host calls `confirmClosed()` (match `closingTimeout`
-to the animation duration; default 300 ms covers the 150 ms default).
+Register `provideRiviniaToast()` as well as `provideRiviniaModal()` in the
+application's root providers. Use one `RiviniaToastList` per toast manager at a
+time: if the app already renders that same manager globally, move or gate that
+list while this modal is open rather than mounting a second list and showing
+every notification twice.
 
-Custom chrome (no X button, custom header/footer, own actions in content):
+The result is a discriminated `ModalResult<TResult>`:
 
-```html
-<rv-modal-dialog [(open)]="open">
-  <div rv-modal-header rvModalHeader>My header, no X</div>
-  <p>Body.</p>
-  <div rv-modal-footer rvModalFooter><button (click)="save()">Save</button></div>
-</rv-modal-dialog>
+- `confirmed` carries the typed `value`.
+- `cancelled` and `dismissed` may carry a `reason`.
+- `owner-destroyed` and `queued-cancelled` identify lifecycle cleanup.
+- `rejected` identifies a request refused by the configured admission or
+  overflow policy.
+
+Narrow on `result.status` before reading `result.value`. Results settle once
+when closing starts; callers do not wait for the exit animation. A component
+that owns a handle may use `close(value)`, `cancel(reason)`, or
+`dismiss(reason)`. `ModalHandle.close()` enforces `TResult`; the `close()`
+method on template/component context accepts `unknown`, so prefer the handle
+when the result type matters.
+
+## Dismissal, guards, and lifecycle
+
+The default dismissal policy allows Escape and backdrop click. Configure
+global defaults, named presets, or per-modal overrides:
+
+```ts
+provideRiviniaModal({
+  dismiss: { closeOnEscape: true, backdrop: 'static' },
+  presets: {
+    critical: { dismiss: { closeOnEscape: false, backdrop: 'static' } },
+  },
+});
 ```
 
-No header at all: omit the title (no custom header either). Header rules:
-title + optional `description` (wired as `aria-describedby`), top-aligned
-with a shrink-proof X; an empty heading collapses (no dead space); a custom
-header renders inside the same padded row. Focus goes to the title when
-there is no close button, to the dialog otherwise. No footer:
-omit the footer slot (renders nothing). Positions: `center` (default),
-`top/bottom`, `-start/-end` variants (RTL-aware), `side-start/side-end`
-full-height panels, `fullscreen`. Under 640px viewports, center/top/bottom
-shapes become bottom sheets automatically (top-only radius, slide-up
-entrance); panels and fullscreen keep their shape.
-Sizes `sm/md/lg/xl/full/auto` are ceilings via `--rv-modal-width-*` vars.
-
-Theming (no theme service; consumer owns it):
-
-```css
-:root {
-  --rv-modal-bg: #1c1c1e;
-  --rv-modal-fg: #f5f5f7;
-}
-@media (prefers-color-scheme: dark) {
-  .rv-modal {
-    /* built-in dark defaults already apply; override vars to brand it */
-  }
+Dismissal policy fields merge independently in this order: built-in defaults,
+global config, named preset, and per-open options. A missing key at a later
+layer does not erase an earlier setting. `backdrop` may be `close`, `static`,
+or `disabled`.
+
+`RiviniaModalHost` routes Escape, backdrop, and close-button intents through
+`requestDismiss()`, which runs any async `guards` supplied when opening. A
+guard that returns `false` or throws keeps the modal open. The direct
+`close()`, `dismiss()`, and `cancel()` methods on a handle are guard-free;
+use `requestDismiss(id, origin)` when programmatic code should also be checked.
+Forced cleanup such as owner destruction and `dismissAll()` bypasses guards.
+
+The manager supports `strategy: 'stack' | 'queue'` (or a custom
+`ModalStrategy`). Stack allows up to `maxVisible` active modals, with the
+latest on top; queue activates one at a time in FIFO order. A modal in its
+exit animation normally occupies a visible slot until the host confirms
+teardown or the timeout finalizes it; `dismiss-oldest` preempts an active
+instance to make room while its exit runs. When capacity is full, `overflow`
+may queue (default), dismiss the oldest active modal, or reject the new request.
+`maxQueue` bounds queued requests when queue overflow is enabled.
+
+An optional `owner: DestroyRef` ties a modal to a component/service lifetime.
+Destroying the owner settles an active request as `owner-destroyed`; a queued
+request settles as `queued-cancelled`. Without an owner, the modal is
+independent of the caller's lifetime. Set `parentId` to associate a child
+modal with a parent; by default, closing a parent closes its descendants.
+`descendants: 'prevent-parent-close'` instead blocks parent closure while a
+descendant remains open.
+
+When a modal enters `closing`, its result has already settled but it remains
+visible while the UI exits. The UI host calls `confirmClosed()` after its exit
+animation. The default `closingTimeout` is 300 ms; set it to cover the
+renderer’s exit duration, or set it to `0` when a custom renderer will always
+acknowledge closure manually. Changing strategy with active, queued, or
+closing modals throws; close them first.
+
+## Ready-made UI
+
+`@rivinia/modal/ui` is optional. It provides a native `<dialog>` component
+(`RiviniaModalDialog`) for UI-only use and `RiviniaModalHost` to render
+manager-owned modals. The host passes dismissal intents to the manager before
+closing, so guards and promise results remain coordinated.
+
+For a UI-only dialog, import the standalone component and bind its `open`
+model. This mode has no manager, guards, or `ModalHandle` promise:
+
+```ts
+import { Component } from '@angular/core';
+import { RiviniaModalDialog } from '@rivinia/modal/ui';
+
+@Component({
+  standalone: true,
+  imports: [RiviniaModalDialog],
+  templateUrl: './preview-dialog.component.html',
+})
+export class PreviewDialog {
+  open = false;
 }
 ```
 
-Plus: `prefers-reduced-motion` disables animation; `animation: 'none'`
-opt-out; `backdrop: 'close' | 'static' | 'disabled'`; Escape/backdrop/X
-policies stay independent (no `disableClose` bundle); long content scrolls
-inside (`rv-modal-body`); `scrollbar-gutter: stable` while open;
-reference-counted scroll lock restores previous styles; focus trap + focus
-restore + `aria-labelledby`/`aria-label`; `dir=rtl` works via logical
-properties; SSR renders closed and opens after hydration; lazy-load the
-entry (`loadComponent`) to split it into its own chunk (~16.7 kB raw,
-~4.9 kB transfer, measured).
-
-## Toasts above an open modal (measured pattern)
-
-A toast host outside the dialog can never paint above it — neither a high
-`z-index` nor `popover="manual"` escapes the modal top layer (verified in
-Chrome via `elementFromPoint`). When an error toast must appear over an open
-modal (e.g. a data error inside the form), host the list **inside** the
-dialog content instead: as a descendant of the top-layer element it paints
-above the dialog background with zero extra code and zero coupling:
-
 ```html
-<rv-modal-dialog [(open)]="open" [title]="'Edit user'">
-  <!-- paints above this dialog; positions are still viewport-anchored -->
-  <rv-toast-list [manager]="injectRiviniaToast()" [position]="'top-end'" />
-  <form>…</form>
+<!-- src/app/preview-dialog.component.html -->
+<button type="button" (click)="open = true">Preview</button>
+<rv-modal-dialog #dialog [(open)]="open" title="Preview">
+  <p>Dialog content.</p>
+  <button type="button" (click)="dialog.confirm(true)">Continue</button>
+  <button type="button" (click)="dialog.cancel('cancelled')">Cancel</button>
 </rv-modal-dialog>
 ```
 
-Notes: positions stay viewport-anchored (`fixed`), so `top-end` means the
-viewport corner in both LTR and RTL (logical properties). Toasts fired
-while no dialog is open still need a page-level list — the two lists share
-the same manager, so nothing is lost or duplicated. Toasts: MEASURED (Chrome, `elementFromPoint`) —
-neither a high `z-index` nor `popover="manual"` paints above an open modal
-dialog; toasts queue behind it. No modal→toast dependency by design.
-
-## Type holes (honest, by design)
-
-Core checks `ModalHandle<TResult>.close(result?: TResult)` and
-`ModalResult`/`ModalContext.data` typing (see `modal-type-safety.spec.ts`
-`@ts-expect-error` tests). It does NOT check:
-
-- `ModalContext.close(result?: unknown)` — any payload compiles; the mismatch
-  reaches the opener's awaited `ModalResult` unchecked.
-- `inputs?: Record<string, unknown>` (options + component content) — any shape
-  compiles; misspelled keys fail silently at render. The UI owns binding.
-- The internal deferred-promise cast to `Promise<ModalResult<TResult>>` —
-  `close()` settles whatever it receives, never validated.
-
-## Browser back button (non-goal)
-
-Native `<dialog>.showModal()` does not integrate with history: the back
-button neither closes the dialog nor is blocked by it (platform behavior,
-not a Rivinia choice). If your app needs back-to-dismiss, wire it at the
-app layer (router guard / `popstate` → `dismiss()`); the manager's
-`dismissRequested` + guards flow stays the single teardown path.
+`RiviniaModalDialog` accepts `open`, `title`, `description`, `ariaLabel`,
+`size`, `position`, `animation`, `closeOnEscape`, `backdrop`, and
+`showCloseButton`; its `open` model supports `[(open)]`. In UI-only mode it
+emits `confirmed`, `dismissed`, and `cancelled`. In managed use, the host
+accepts the required `modal` manager input plus `size`, `showCloseButton`,
+and `titleOf` overrides; observe the manager's `ModalHandle.result` instead
+of the dialog outputs.
+`RvModalHeader` and `RvModalFooter` are marker directives for custom header
+and footer projection; import the marker used by the template and apply it
+alongside `rv-modal-header` or `rv-modal-footer`. A custom header replaces the
+default title and close button. Without a footer slot, no footer region is
+rendered.
+
+The native dialog provides focus containment and restores focus to its
+invoker. The UI includes scroll locking, reduced-motion support, RTL-aware
+logical positions, and responsive bottom-sheet styling below 640px for
+center/top/bottom placements. The UI exposes size, position, animation,
+backdrop, Escape, and close-button inputs. During server rendering it remains
+closed and opens on the client after hydration. Theme it with CSS custom
+properties such as `--rv-modal-bg`, `--rv-modal-fg`, `--rv-modal-border`,
+`--rv-modal-radius`, and `--rv-modal-width-md`.
+
+## Public core exports
+
+The core entry point exports:
+
+- `provideRiviniaModal()` and `injectRiviniaModal()` for configuration and
+  injection, plus `RiviniaModal` for direct manager APIs.
+- `StackStrategy`, `QueueStrategy`, and the `ModalStrategy` contract.
+- `RiviniaModalConfig`, `ModalPreset`, `ModalHandle`, `ModalResult`,
+  `ModalContent`, `ModalOpenOptions`, `ModalUpdate`, `ModalInstance`,
+  `ModalTemplateContext`, `ModalContext`, `ModalGuard`,
+  `ModalDismissPolicy`, `ModalDismissOrigin`, `ModalOverflowPolicy`,
+  `ModalStatus`, `ModalDiagnostic`, and `DescendantPolicy`.
+- `RIVINIA_MODAL_CONTEXT` for dynamic modal components.
+
+`RiviniaModal` exposes readonly `active`, `queued`, `closing`, `visible`, and
+`top` signals, along with `openModal`, `close`, `dismiss`, `cancel`,
+`requestDismiss`, `update`, `confirmClosed`, `dismissAll`, `findByRef`,
+`useStrategy`, and diagnostics helpers. Inspect the signal values by calling
+them, for example `manager.top()`.
+
+The `@rivinia/modal/ui` entry point exports `RiviniaModalDialog`,
+`RiviniaModalHost`, `RiviniaModalHostManager`, `RiviniaModalScrollLock`,
+`RvModalHeader`, and `RvModalFooter`, plus the `RiviniaModalAnimation`,
+`RiviniaModalBackdrop`, `RiviniaModalPosition`, `RiviniaModalSize`, and
+`RiviniaModalUiOptions` types.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivinia/modal",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Headless modal manager for Angular: stack/queue strategies, typed results, guards, ownership.",
   "keywords": [
     "angular",