@rivinia/modal 0.3.0 → 0.5.0

package/types/rivinia-modal-ui.d.ts

@@ -0,0 +1,332 @@
+import * as i0 from "@angular/core";
+import { Injector, Signal } from "@angular/core";
+import { ModalDismissOrigin, ModalInstance, ModalTemplateContext } from "@rivinia/modal";
+/**
+ * Responsive size presets. Dimensions are ceilings, not mandates: every
+ * preset is a CSS custom property (`--rv-modal-width-*`) the consumer can
+ * override without touching library source. `auto` sizes to content.
+ */
+type RiviniaModalSize = 'sm' | 'md' | 'lg' | 'xl' | 'full' | 'auto';
+/**
+ * Placement in the viewport. `start`/`end` are logical (RTL-aware).
+ * `fullscreen` covers the viewport (safe-area aware). `side-start` /
+ * `side-end` dock a full-height panel to the inline edge. Implemented with
+ * plain CSS on the native `<dialog>` — no positioning engine.
+ *
+ * Responsive sheet mapping (built in, no input needed): viewports narrower
+ * than 640px render `center`, `top`, `bottom` and the bottom corners as a
+ * bottom sheet (anchored, top-only radius, slide-from-bottom entrance).
+ * `fullscreen` and the side panels keep their shape on small screens.
+ */
+type RiviniaModalPosition = 'center' | 'top' | 'bottom' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'center-start' | 'center-end' | 'side-start' | 'side-end' | 'fullscreen';
+/** Entrance/exit animation preset. `none` disables motion entirely. */
+type RiviniaModalAnimation = 'fade' | 'scale' | 'slide-top' | 'slide-bottom' | 'slide-start' | 'slide-end' | 'none';
+/** Backdrop click policy (mirrors the headless `ModalDismissPolicy`). */
+type RiviniaModalBackdrop = 'close' | 'static' | 'disabled';
+/**
+ * Visual + interaction options for {@link RiviniaModalDialog}. Independent
+ * knobs only — no `disableClose` bundle (Escape, backdrop and the close
+ * button stay separately configurable, like the headless policy).
+ */
+interface RiviniaModalUiOptions {
+  /** @default 'md' */
+  readonly size?: RiviniaModalSize;
+  /** @default 'center' */
+  readonly position?: RiviniaModalPosition;
+  /** @default 'scale' */
+  readonly animation?: RiviniaModalAnimation;
+  /** Escape requests dismissal via the configured path. @default true */
+  readonly closeOnEscape?: boolean;
+  /** Backdrop click behavior. @default 'close' */
+  readonly backdrop?: RiviniaModalBackdrop;
+  /** Render the header close button. @default true */
+  readonly showCloseButton?: boolean;
+}
+/**
+ * Marker for custom header content. Put it on the element carrying
+ * `rv-modal-header` — its presence (not just the attribute) tells the
+ * dialog to hide the default title + close button:
+ *
+ * ```html
+ * <div rv-modal-header rvModalHeader>My header</div>
+ * ```
+ */
+export declare class RvModalHeader {
+  static ɵfac: i0.ɵɵFactoryDeclaration<RvModalHeader, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<RvModalHeader, "[rvModalHeader]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Marker for custom footer content. Put it on the element carrying
+ * `rv-modal-footer`. Without it the footer region never renders.
+ */
+export declare class RvModalFooter {
+  static ɵfac: i0.ɵɵFactoryDeclaration<RvModalFooter, never>;
+  static ɵdir: i0.ɵɵDirectiveDeclaration<RvModalFooter, "[rvModalFooter]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Ready-made modal dialog on the native `<dialog>` element (top layer,
+ * `::backdrop`, inert background, Escape `cancel` event — all platform
+ * behavior, zero overlay dependencies).
+ *
+ * UI-only by design: it owns its own `open` state and never imports the
+ * headless controller. Pair it with `@rivinia/modal` through
+ * {@link RiviniaModalHost} (or your own adapter) when you want managed
+ * lifecycle, guards and typed results.
+ *
+ * Projection: `[rv-modal-header]` replaces the default header (title +
+ * close button); default `<ng-content>` is the body; `[rv-modal-footer]`
+ * is optional and renders nothing when absent.
+ */
+export declare class RiviniaModalDialog {
+  /** Two-way open state. UI-only mode owns this; the host drives it in managed mode. */
+  readonly open: import("@angular/core").ModelSignal<boolean>;
+  readonly title: import("@angular/core").InputSignal<string>;
+  /**
+   * Supporting text under the title (shadcn-style description). Rendered in
+   * the default header only, and wired as the dialog's `aria-describedby`
+   * for free accessible naming. Empty = no description element at all.
+   */
+  readonly description: import("@angular/core").InputSignal<string>;
+  /** Explicit accessible name. When set, `aria-label` wins over the title reference. */
+  readonly ariaLabel: import("@angular/core").InputSignal<string>;
+  readonly size: import("@angular/core").InputSignal<RiviniaModalSize>;
+  readonly position: import("@angular/core").InputSignal<RiviniaModalPosition>;
+  readonly animation: import("@angular/core").InputSignal<RiviniaModalAnimation>;
+  readonly closeOnEscape: import("@angular/core").InputSignal<boolean>;
+  readonly backdrop: import("@angular/core").InputSignal<RiviniaModalBackdrop>;
+  readonly showCloseButton: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Managed mode (for {@link RiviniaModalHost}): UI intents (X button,
+   * Escape, backdrop) emit `dismissRequested` INSTEAD of dismissing, so the
+   * manager runs guards first and settles results. Drive the exit with the
+   * `closing` input; acknowledge teardown with `exitDone`.
+   * UI-only mode (`false`, default) dismisses locally.
+   */
+  readonly managed: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Managed-mode exit trigger. Set `true` when the manager reports this
+   * instance `closing`: the dialog plays its exit animation, then emits
+   * `exitDone` (call `confirmClosed()` there). Ignored in UI-only mode.
+   */
+  readonly closing: import("@angular/core").InputSignal<boolean>;
+  /** Settled with a value (primary/confirm actions call `close(value)`). */
+  readonly confirmed: import("@angular/core").OutputEmitterRef<unknown>;
+  /** Settled without a value (X button, backdrop, Escape, `dismiss()`). */
+  readonly dismissed: import("@angular/core").OutputEmitterRef<string | undefined>;
+  /** Explicit cancellation (`cancel()`). Kept distinct from dismissal. */
+  readonly cancelled: import("@angular/core").OutputEmitterRef<string | undefined>;
+  /**
+   * Managed-mode intent (X button / Escape / backdrop). Emitted INSTEAD of
+   * dismissing — the host routes it to the manager first. Never emitted in
+   * UI-only mode.
+   */
+  readonly dismissRequested: import("@angular/core").OutputEmitterRef<"button" | "escape" | "backdrop">;
+  /** Managed-mode exit completion. Acknowledge with `confirmClosed()`. */
+  readonly exitDone: import("@angular/core").OutputEmitterRef<void>;
+  private readonly dialog;
+  private readonly headerSlot;
+  private readonly footerSlot;
+  private readonly doc;
+  private readonly scrollLock;
+  private readonly titleId;
+  private readonly descriptionId;
+  private readonly phase;
+  private readonly invoker;
+  private exitTimer;
+  /** Template state for animation styling. Never rendered open on the server. */
+  readonly state: import("@angular/core").Signal<"closed" | "open" | "closing">;
+  readonly hasCustomHeader: import("@angular/core").Signal<boolean>;
+  readonly hasCustomFooter: import("@angular/core").Signal<boolean>;
+  readonly computedLabel: import("@angular/core").Signal<string | null>;
+  constructor();
+  /** Confirm with a value. No-op while closing/closed. */
+  confirm(value?: unknown): boolean;
+  /** Backwards-compatible close: confirms when given a value, dismisses otherwise. */
+  close(value?: unknown): boolean;
+  /** Dismiss without a value (X button, backdrop, Escape route here). */
+  dismiss(reason?: string): boolean;
+  /** Explicit cancellation. */
+  cancel(reason?: string): boolean;
+  protected onCloseButton(): void;
+  protected onCancel(event: Event): void;
+  protected onBackdropClick(event: MouseEvent): void;
+  protected onKeydown(event: KeyboardEvent): void;
+  private get live();
+  private show;
+  private hide;
+  private finish;
+  private teardown;
+  /** Plays the exit animation (when warranted), then runs `done`. Idempotent. */
+  private playExit;
+  private exitDurationMs;
+  private finalize;
+  private prefersMotion;
+  static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaModalDialog, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<RiviniaModalDialog, "rv-modal-dialog", never, {
+    "open": {
+      "alias": "open";
+      "required": false;
+      "isSignal": true;
+    };
+    "title": {
+      "alias": "title";
+      "required": false;
+      "isSignal": true;
+    };
+    "description": {
+      "alias": "description";
+      "required": false;
+      "isSignal": true;
+    };
+    "ariaLabel": {
+      "alias": "ariaLabel";
+      "required": false;
+      "isSignal": true;
+    };
+    "size": {
+      "alias": "size";
+      "required": false;
+      "isSignal": true;
+    };
+    "position": {
+      "alias": "position";
+      "required": false;
+      "isSignal": true;
+    };
+    "animation": {
+      "alias": "animation";
+      "required": false;
+      "isSignal": true;
+    };
+    "closeOnEscape": {
+      "alias": "closeOnEscape";
+      "required": false;
+      "isSignal": true;
+    };
+    "backdrop": {
+      "alias": "backdrop";
+      "required": false;
+      "isSignal": true;
+    };
+    "showCloseButton": {
+      "alias": "showCloseButton";
+      "required": false;
+      "isSignal": true;
+    };
+    "managed": {
+      "alias": "managed";
+      "required": false;
+      "isSignal": true;
+    };
+    "closing": {
+      "alias": "closing";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "open": "openChange";
+    "confirmed": "confirmed";
+    "dismissed": "dismissed";
+    "cancelled": "cancelled";
+    "dismissRequested": "dismissRequested";
+    "exitDone": "exitDone";
+  }, ["headerSlot", "footerSlot"], ["[rv-modal-header]", "*", "[rv-modal-footer]"], true, never>;
+}
+/**
+ * Managed adapter: renders every `visible()` instance of the headless
+ * `RiviniaModal` inside a {@link RiviniaModalDialog} and routes all UI
+ * intents through the manager first (guards run; results settle in Core —
+ * the single source of truth). The dialog never settles anything itself in
+ * this mode; listen to `ModalHandle.result`, not dialog outputs.
+ *
+ * Exit coordination: when Core reports an instance `closing`, the dialog
+ * plays its exit animation and the host acknowledges with `confirmClosed()`
+ * (idempotent — safe if `closingTimeout` auto-finalized first). Match
+ * `closingTimeout` to the animation duration so exits stay visible.
+ *
+ * Title resolution: `titleOf` per instance (default: `metadata.title` →
+ * `ref` → `''`). Content descriptors render as-is: templates via
+ * `ngTemplateOutlet` with `{$implicit: data, modal}`, components via
+ * `NgComponentOutlet` with `inputs` + a per-instance
+ * `RIVINIA_MODAL_CONTEXT` injector (the lab-proven pattern).
+ *
+ * The manager arrives via `[modal]` input (D06 input-composition: the UI
+ * entry never instantiates Core itself, so UI-only consumers pay nothing).
+ * The input is typed as {@link RiviniaModalHostManager} — the structural
+ * slice the host actually drives — so the full manager (or a test double)
+ * satisfies it from any module realm:
+ *
+ * ```html
+ * <rv-modal-host [modal]="injectRiviniaModal()" />
+ * ```
+ */
+interface RiviniaModalHostManager {
+  readonly visible: Signal<readonly ModalInstance<unknown>[]>;
+  requestDismiss(id: string, origin: ModalDismissOrigin): Promise<boolean>;
+  confirmClosed(id: string): boolean;
+  close(id: string, value?: unknown): boolean;
+  dismiss(id: string, reason?: string): boolean;
+}
+export declare class RiviniaModalHost {
+  /**
+   * The headless manager to render. Typed as {@link RiviniaModalHostManager}
+   * (structural) — pass `injectRiviniaModal()` from your app code.
+   */
+  readonly modal: import("@angular/core").InputSignal<RiviniaModalHostManager>;
+  /** Dialog size for every managed instance. @default 'md' */
+  readonly size: import("@angular/core").InputSignal<RiviniaModalSize>;
+  /** Render the header close button on every managed instance. @default true */
+  readonly showCloseButton: import("@angular/core").InputSignal<boolean>;
+  /** Resolve a title per instance. Default: `metadata.title` → `ref` → `''`. */
+  readonly titleOf: import("@angular/core").InputSignal<((instance: ModalInstance<unknown>) => string | undefined) | undefined>;
+  protected readonly visible: Signal<readonly ModalInstance<unknown>[]>;
+  protected titleOfInstance(instance: ModalInstance<unknown>): string;
+  protected templateContext(instance: ModalInstance<unknown>): ModalTemplateContext<unknown>;
+  protected contextInjector(instance: ModalInstance<unknown>): Injector;
+  protected onIntent(id: string, origin: 'button' | 'escape' | 'backdrop'): Promise<void>;
+  protected onExitDone(id: string): void;
+  private modalContext;
+  static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaModalHost, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<RiviniaModalHost, "rv-modal-host", never, {
+    "modal": {
+      "alias": "modal";
+      "required": true;
+      "isSignal": true;
+    };
+    "size": {
+      "alias": "size";
+      "required": false;
+      "isSignal": true;
+    };
+    "showCloseButton": {
+      "alias": "showCloseButton";
+      "required": false;
+      "isSignal": true;
+    };
+    "titleOf": {
+      "alias": "titleOf";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {}, never, never, true, never>;
+}
+/**
+ * Reference-counted background scroll lock. Multiple overlays share one lock:
+ * closing one modal never unlocks the page while another still needs it.
+ * Restores the exact previous `overflow` value (never blanks app-owned
+ * styles). All DOM access happens inside methods — never at module
+ * evaluation — and every method is a no-op without a document (SSR).
+ */
+export declare class RiviniaModalScrollLock {
+  private readonly _doc;
+  private _locks;
+  private _previousOverflow;
+  /** Number of active locks (diagnostics/tests). */
+  get active(): number;
+  acquire(): void;
+  release(): void;
+  private get document();
+  static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaModalScrollLock, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+export type { RiviniaModalAnimation, RiviniaModalBackdrop, RiviniaModalHostManager, RiviniaModalPosition, RiviniaModalSize, RiviniaModalUiOptions };

package/types/rivinia-modal.d.ts

@@ -69,6 +69,13 @@ type ModalContent<TData> = {
 } | {
   readonly kind: 'component';
   readonly component: Type<unknown>;
+  /**
+   * Component inputs bound by the UI via `NgComponentOutlet`.
+   *
+   * Type hole (by design, not checked): `Record<string, unknown>` accepts
+   * any shape — a misspelled input key compiles and fails silently at
+   * render. The UI layer, not Core, owns binding.
+   */
   readonly inputs?: Record<string, unknown>;
 };
 /** Template context for `TemplateRef` content. */
@@ -86,6 +93,12 @@ interface ModalContext<TData> {
   readonly id: string;
   readonly data: TData;
   readonly parentId: string | null;
+  /**
+   * Type hole (by design): `result` is `unknown`, so passing the wrong payload
+   * type compiles — the mismatch surfaces only in the `ModalResult` value the
+   * opener awaits. Prefer the typed `ModalHandle<TResult>.close()` at the
+   * call site, which IS checked (see type tests).
+   */
   close(result?: unknown): boolean;
   dismiss(reason?: string): boolean;
 }
@@ -150,7 +163,11 @@ interface ModalOpenOptions<TData = unknown> {
   readonly dismiss?: Partial<ModalDismissPolicy>;
   readonly guards?: readonly ModalGuard[];
   readonly metadata?: Record<string, unknown>;
-  /** Inputs for component content (bound by the UI via `NgComponentOutlet`). */
+  /** Inputs for component content (bound by the UI via `NgComponentOutlet`).
+   *
+   * Type hole (by design, not checked): any shape compiles; misspelled keys
+   * fail silently at render. See `ModalContent` inputs.
+   */
   readonly inputs?: Record<string, unknown>;
 }
 /** Partial changes for `update()` (content shape itself is immutable). */
@@ -254,6 +271,10 @@ export declare class RiviniaModal {
   readonly active: import("@angular/core").Signal<readonly ModalInstance<unknown>[]>;
   /** Queued instances, FIFO admission order. */
   readonly queued: import("@angular/core").Signal<readonly ModalInstance<unknown>[]>;
+  /** Closing instances (exit animations), in strategy display order. */
+  readonly closing: import("@angular/core").Signal<readonly ModalInstance<unknown>[]>;
+  /** Everything rendered (active + closing), in strategy display order. */
+  readonly visible: import("@angular/core").Signal<readonly ModalInstance<unknown>[]>;
   /** Topmost active instance (the only Escape-eligible one), if any. */
   readonly top: import("@angular/core").Signal<ModalInstance<unknown> | null>;
   constructor();