@rivinia/modal 0.5.2 → 0.5.3

package/README.md

@@ -5,7 +5,7 @@ policies, async guards, and optional ready-made UI. The core package owns
 modal state and lifecycle but does not render or style dialogs.
 
 - Install: `npm install @rivinia/modal`
-- Prepared patch: **0.5.2** (latest published: **0.5.1**)
+- 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.
@@ -37,8 +37,9 @@ described below. You can also configure the provider manually as above.
 
 ## Open a typed modal
 
-This standalone component uses a typed template, mounts one shared modal host,
-and waits for the result before changing application state:
+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
 import { Component, TemplateRef, ViewChild, signal } from '@angular/core';
@@ -59,19 +60,7 @@ interface DeleteData {
 @Component({
   standalone: true,
   imports: [RiviniaModalHost],
-  template: `
-    @for (user of users(); track user.id) {
-      <button type="button" (click)="askToDelete(user)">Delete {{ user.name }}</button>
-    }
-
-    <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>
-
-    <rv-modal-host [modal]="modals" size="sm" />
-  `,
+  templateUrl: './users-page.component.html',
 })
 export class UsersPage {
   private readonly manager = injectRiviniaModal();
@@ -115,11 +104,90 @@ export class UsersPage {
 }
 ```
 
+```html
+<!-- src/app/users-page.component.html -->
+@for (user of users(); track user.id) {
+<button type="button" (click)="askToDelete(user)">Delete {{ user.name }}</button>
+}
+
+<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>
+
+<rv-modal-host [modal]="modals" size="sm" />
+```
+
+### Signal-based view query
+
+For new code, Angular 22 also supports the `viewChild` signal query. Keep the
+same HTML; call the query signal to get its `TemplateRef`:
+
+```ts
+// 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);
+  }
+
+  cancelDelete(): void {
+    this.pendingDelete?.cancel('user-cancelled');
+  }
+}
+```
+
 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. For an NgModule-based app, import this
-standalone component in the module's `imports` array, not `declarations`.
-Mount a single host for the manager you pass to it.
+standalone component that renders it. All examples in this guide target
+standalone Angular 22 applications.
 
 `openModal<TData, TResult>()` accepts a `TemplateRef`, a component type, or a
 `ModalContent<TData>` descriptor. Template content receives `data` as
@@ -129,6 +197,128 @@ 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.
 
+### Component content, modal context, and `NgComponentOutlet`
+
+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
+// 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);
+  }
+
+  cancel(): void {
+    this.modal.dismiss('user-cancelled');
+  }
+}
+```
+
+```html
+<!-- 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);
+}
+```
+
+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' },
+    });
+  }
+
+  showPaymentSaved(): void {
+    this.toast.show({ message: 'Payment saved', kind: 'success' });
+  }
+}
+```
+
+```html
+<!-- 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" />
+```
+
+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.
+
 The result is a discriminated `ModalResult<TResult>`:
 
 - `confirmed` carries the typed `value`.
@@ -211,20 +401,23 @@ import { RiviniaModalDialog } from '@rivinia/modal/ui';
 @Component({
   standalone: true,
   imports: [RiviniaModalDialog],
-  template: `
-    <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>
-  `,
+  templateUrl: './preview-dialog.component.html',
 })
 export class PreviewDialog {
   open = false;
 }
 ```
 
+```html
+<!-- 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>
+```
+
 `RiviniaModalDialog` accepts `open`, `title`, `description`, `ariaLabel`,
 `size`, `position`, `animation`, `closeOnEscape`, `backdrop`, and
 `showCloseButton`; its `open` model supports `[(open)]`. In UI-only mode it

package/package.json

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