@rivinia/modal 0.4.0 → 0.5.1

package/README.md

@@ -8,7 +8,7 @@ Headless modal manager for Angular 22+. Stack/Queue strategies, typed
 zero styles, zero router dependency. A future `@rivinia/modal/ui` entry point
 will render this state; Core never imports UI.
 
-- Version: **0.4.0**
+- Version: **0.5.0**
 - Requires: **Angular `^22.0.0`**, `tslib`
 
 ## Install
@@ -86,6 +86,108 @@ 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.
 
+## Ready-made UI (`@rivinia/modal/ui`)
+
+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).
+
+```ts
+import { RiviniaModalDialog } from '@rivinia/modal/ui'; // UI-only
+import { RiviniaModalHost } from '@rivinia/modal/ui'; // managed adapter
+```
+
+**Mode A — UI-only** (no controller; owns its `open` state):
+
+```html
+<rv-modal-dialog [(open)]="open" [title]="'Delete?'" [size]="'sm'" (confirmed)="remove()">
+  <p>Delete {{ user.name }}?</p>
+</rv-modal-dialog>
+```
+
+**Mode B — headless + custom UI:** keep using `@rivinia/modal` alone.
+Nothing here loads, no styles leak.
+
+**Mode C — headless + ready-made UI** (single source of truth stays Core):
+
+```html
+<rv-modal-host [modal]="injectRiviniaModal()" />
+```
+
+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).
+
+Custom chrome (no X button, custom header/footer, own actions in content):
+
+```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>
+```
+
+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 */
+  }
+}
+```
+
+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>
+</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
@@ -99,6 +201,14 @@ Core checks `ModalHandle<TResult>.close(result?: TResult)` and
 - 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.
+
 ## License
 
 MIT.