@rivinia/toast 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @rivinia/toast
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@rivinia/toast.svg)](https://www.npmjs.com/package/@rivinia/toast)
+[![license](https://img.shields.io/npm/l/@rivinia/toast.svg)](https://www.npmjs.com/package/@rivinia/toast)
+
+Headless toast queue for Angular 22+. Signals, pause-on-hover timers, actions,
+dedupe, overflow policies — zero DOM, zero styles, zero router dependency.
+A future `@rivinia/toast/ui` entry point will render this state; Core never
+imports UI.
+
+- Version: **0.2.0**
+- Requires: **Angular `^22.0.0`**, `tslib`
+
+## Install
+
+```bash
+npm install @rivinia/toast
+ng add @rivinia/toast   # wires provideRiviniaToast() into app.config.ts
+```
+
+```ts
+// app.config.ts
+import { provideRiviniaToast } from '@rivinia/toast';
+
+providers: [provideRiviniaToast({ duration: 5000, maxVisible: 5 })];
+```
+
+## Quick start
+
+```ts
+export class Checkout {
+  private toast = injectRiviniaToast();
+
+  pay() {
+    const id = this.toast.show({ message: 'Payment sent', kind: 'success' });
+    // id: number | null (null = rejected by the 'reject' overflow policy)
+  }
+
+  saving() {
+    // Same key updates in place instead of stacking duplicates:
+    this.toast.show({ message: 'Saving…', dedupeKey: 'save' });
+    this.toast.show({ message: 'Saved', kind: 'success', dedupeKey: 'save' });
+  }
+}
+```
+
+```html
+<!-- your outlet (or the future @rivinia/toast/ui): -->
+@for (t of toast.active(); track t.id) {
+  <div [attr.data-kind]="t.kind">{{ resolveToastText(t.message) }}</div>
+}
+```
+
+## API
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `provideRiviniaToast(config?)` | provider | `{ duration?=5000, durations?, maxVisible?=5, maxQueue?=∞, overflow?='dismiss-oldest' }` |
+| `RiviniaToast` | `@Service()` | `show/dismiss/dismissAll/update/pause/resume/runAction`, `active` + `queue` signals |
+| `injectRiviniaToast()` | function | shorthand for `inject(RiviniaToast)` |
+| `resolveToastText(msg)` | util | reads `string \| Signal<string>` (reactive re-translation without i18n coupling) |
+| `clampDuration(v, fallback)` | util | normalizes durations (`0`/negative/`NaN`/infinite = persistent) |
+| types | types | `Toast`, `ToastKind`, `ToastMessage`, `ToastAction`, `ToastOptions`, `ToastChanges`, `ToastOverflowPolicy`, `RiviniaToastConfig` |
+
+`show()` returns the stable id, or `null` under `'reject'` (or a full finite
+queue). `dismiss/update/pause/resume/runAction` return `false` for unknown ids
+(and repeated dismissal) instead of throwing. `duration: 0` = persistent.
+Timers start at queue **promotion**, never while queued. Per-toast options
+always beat globals.
+
+## Recipes (app-owned, deliberately not in the library)
+
+```ts
+import { filter } from 'rxjs';
+import { NavigationStart } from '@angular/router';
+
+// Clear timed toasts on navigation (BRT behavior, 3 lines, no library peer needed):
+router.events.pipe(filter((e) => e instanceof NavigationStart))
+  .subscribe(() => toast.active().forEach((t) => t.duration > 0 && toast.dismiss(t.id)));
+
+// Backend-shaped errors stay in your error mapper, then:
+toast.show({ message: 'Order failed', kind: 'error', action: {
+  label: 'Retry', onPress: () => retry(),
+} }); // dismisses after press unless dismissAfterPress: false
+```
+
+Future UI must render inside `role="region" aria-live="polite"`, pause on
+hover **and** keyboard focus (WCAG 2.2.1 timing control), and offer a labelled
+dismiss button — the Core API (`pause/resume/dismiss`) already supports all of it.
+
+## Testing your app code
+
+```ts
+vi.useFakeTimers();
+toast.show({ message: 'x' });
+vi.advanceTimersByTime(5000);
+expect(toast.active()).toEqual([]);
+```
+
+## License
+
+MIT.

package/fesm2022/rivinia-toast.mjs

@@ -0,0 +1,267 @@
+import * as i0 from "@angular/core";
+import { DestroyRef, InjectionToken, Service, inject, makeEnvironmentProviders, signal } from "@angular/core";
+function resolveToastText(message) {
+	return typeof message === "string" ? message : message();
+}
+function clampDuration(value, fallback) {
+	const candidate = value === void 0 ? fallback : value;
+	if (typeof candidate !== "number" || !Number.isFinite(candidate) || candidate <= 0) return 0;
+	return Math.floor(candidate);
+}
+const RIVINIA_TOAST_CONFIG = new InjectionToken("RIVINIA_TOAST_CONFIG");
+const DEFAULT_DURATION = 5e3;
+var RiviniaToast = class RiviniaToast {
+	config = inject(RIVINIA_TOAST_CONFIG, { optional: true });
+	_active = signal([], ...ngDevMode ? [{ debugName: "_active" }] : /* istanbul ignore next */ []);
+	_queue = signal([], ...ngDevMode ? [{ debugName: "_queue" }] : /* istanbul ignore next */ []);
+	active = this._active.asReadonly();
+	queue = this._queue.asReadonly();
+	_timers = /* @__PURE__ */ new Map();
+	_generations = /* @__PURE__ */ new Map();
+	_dedupeByKey = /* @__PURE__ */ new Map();
+	_dedupeKeyById = /* @__PURE__ */ new Map();
+	_nextId = 0;
+	constructor() {
+		inject(DestroyRef).onDestroy(() => this.clearTimers());
+	}
+	show(options) {
+		if (options.dedupeKey !== void 0) {
+			const existing = this.findByDedupeKey(options.dedupeKey);
+			if (existing !== null) {
+				this.update(existing, {
+					message: options.message,
+					kind: options.kind,
+					duration: options.duration,
+					action: options.action ?? null
+				});
+				return existing;
+			}
+		}
+		const id = ++this._nextId;
+		const kind = options.kind ?? "info";
+		const duration = this.resolveDuration(kind, options.duration);
+		const toast = {
+			id,
+			kind,
+			message: options.message,
+			duration,
+			remaining: duration,
+			action: options.action ?? null
+		};
+		if (options.dedupeKey !== void 0) {
+			this._dedupeByKey.set(options.dedupeKey, id);
+			this._dedupeKeyById.set(id, options.dedupeKey);
+		}
+		if (this._active().length < this.maxVisible()) {
+			this._active.update((list) => [...list, toast]);
+			this.arm(id, duration);
+			return id;
+		}
+		switch (this.config?.overflow ?? "dismiss-oldest") {
+			case "queue":
+				if (this._queue().length >= this.maxQueue()) {
+					this.forgetDedupe(id);
+					return null;
+				}
+				this._queue.update((list) => [...list, toast]);
+				return id;
+			case "reject":
+				this.forgetDedupe(id);
+				return null;
+			default: {
+				const oldest = this._active()[0];
+				if (oldest) this.dismiss(oldest.id);
+				this._active.update((list) => [...list, toast]);
+				this.arm(id, duration);
+				return id;
+			}
+		}
+	}
+	update(id, changes) {
+		const inActive = this._active().some((t) => t.id === id);
+		const apply = (t) => ({
+			...t,
+			message: changes.message ?? t.message,
+			kind: changes.kind ?? t.kind,
+			duration: changes.duration !== void 0 ? clampDuration(changes.duration, t.duration) : t.duration,
+			remaining: changes.duration !== void 0 ? clampDuration(changes.duration, t.duration) : t.duration,
+			action: changes.action !== void 0 ? changes.action : t.action
+		});
+		if (inActive) {
+			this.disarm(id);
+			let next;
+			this._active.update((list) => list.map((t) => {
+				if (t.id !== id) return t;
+				next = apply(t);
+				return next;
+			}));
+			if (next) this.arm(id, next.duration);
+			return true;
+		}
+		let found = false;
+		this._queue.update((list) => list.map((t) => {
+			if (t.id !== id) return t;
+			found = true;
+			return apply(t);
+		}));
+		return found;
+	}
+	dismiss(id) {
+		this.disarm(id);
+		let removed = false;
+		this._active.update((list) => {
+			const next = list.filter((t) => t.id !== id);
+			removed = next.length !== list.length;
+			return next;
+		});
+		if (!removed) this._queue.update((list) => {
+			const next = list.filter((t) => t.id !== id);
+			removed = next.length !== list.length;
+			return next;
+		});
+		if (removed) {
+			this.forgetDedupe(id);
+			this.promote();
+		}
+		return removed;
+	}
+	dismissAll() {
+		this.clearTimers();
+		this._active.set([]);
+		this._queue.set([]);
+		this._dedupeByKey.clear();
+		this._dedupeKeyById.clear();
+	}
+	pause(id) {
+		const record = this._timers.get(id);
+		if (!record) return false;
+		clearTimeout(record.handle);
+		this._timers.delete(id);
+		const elapsed = Date.now() - record.startedAt;
+		this._active.update((list) => list.map((t) => t.id === id ? {
+			...t,
+			remaining: Math.max(0, t.remaining - elapsed)
+		} : t));
+		return true;
+	}
+	resume(id) {
+		if (this._timers.has(id)) return false;
+		const toast = this._active().find((t) => t.id === id);
+		if (!toast) return false;
+		if (toast.remaining <= 0) {
+			this.dismiss(id);
+			return true;
+		}
+		this.arm(id, toast.remaining);
+		return true;
+	}
+	runAction(id) {
+		const toast = this._active().find((t) => t.id === id) ?? this._queue().find((t) => t.id === id);
+		if (!toast?.action) return false;
+		toast.action.onPress();
+		if (toast.action.dismissAfterPress ?? true) this.dismiss(id);
+		return true;
+	}
+	maxVisible() {
+		const value = this.config?.maxVisible ?? 5;
+		return Math.max(1, Math.floor(value));
+	}
+	maxQueue() {
+		const value = this.config?.maxQueue ?? Number.POSITIVE_INFINITY;
+		return value < 0 ? 0 : value;
+	}
+	resolveDuration(kind, override) {
+		if (override !== void 0) return clampDuration(override, this.fallbackDuration(kind));
+		return this.fallbackDuration(kind);
+	}
+	fallbackDuration(kind) {
+		const perKind = this.config?.durations?.[kind];
+		if (perKind !== void 0) return clampDuration(perKind, DEFAULT_DURATION);
+		return clampDuration(this.config?.duration, DEFAULT_DURATION);
+	}
+	arm(id, delay) {
+		if (delay <= 0) return;
+		const generation = (this._generations.get(id) ?? 0) + 1;
+		this._generations.set(id, generation);
+		this._timers.set(id, {
+			handle: setTimeout(() => {
+				if (this._timers.get(id)?.generation === generation) this.dismiss(id);
+			}, delay),
+			startedAt: Date.now(),
+			generation
+		});
+	}
+	disarm(id) {
+		const record = this._timers.get(id);
+		if (record) {
+			clearTimeout(record.handle);
+			this._timers.delete(id);
+		}
+	}
+	clearTimers() {
+		for (const record of this._timers.values()) clearTimeout(record.handle);
+		this._timers.clear();
+	}
+	promote() {
+		while (this._active().length < this.maxVisible() && this._queue().length > 0) {
+			const head = this._queue()[0];
+			this._queue.update((list) => list.slice(1));
+			const fresh = {
+				...head,
+				remaining: head.duration
+			};
+			this._active.update((list) => [...list, fresh]);
+			this.arm(fresh.id, fresh.duration);
+		}
+	}
+	findByDedupeKey(key) {
+		const id = this._dedupeByKey.get(key);
+		if (id === void 0) return null;
+		if (!(this._active().some((t) => t.id === id) || this._queue().some((t) => t.id === id))) {
+			this.forgetDedupe(id);
+			return null;
+		}
+		return id;
+	}
+	forgetDedupe(id) {
+		const key = this._dedupeKeyById.get(id);
+		if (key !== void 0) {
+			this._dedupeKeyById.delete(id);
+			if (this._dedupeByKey.get(key) === id) this._dedupeByKey.delete(key);
+		}
+	}
+	static ɵfac = i0.ɵɵngDeclareFactory({
+		minVersion: "12.0.0",
+		version: "22.2.2",
+		ngImport: i0,
+		type: RiviniaToast,
+		deps: [],
+		target: i0.ɵɵFactoryTarget.Service
+	});
+	static ɵprov = i0.ɵɵngDeclareService({
+		minVersion: "22.0.0",
+		version: "22.2.2",
+		ngImport: i0,
+		type: RiviniaToast
+	});
+};
+i0.ɵɵngDeclareClassMetadata({
+	minVersion: "12.0.0",
+	version: "22.2.2",
+	ngImport: i0,
+	type: RiviniaToast,
+	decorators: [{ type: Service }],
+	ctorParameters: () => []
+});
+function provideRiviniaToast(config = {}) {
+	return makeEnvironmentProviders([{
+		provide: RIVINIA_TOAST_CONFIG,
+		useValue: config
+	}]);
+}
+function injectRiviniaToast() {
+	return inject(RiviniaToast);
+}
+export { RiviniaToast, clampDuration, injectRiviniaToast, provideRiviniaToast, resolveToastText };
+
+//# sourceMappingURL=rivinia-toast.mjs.map

package/fesm2022/rivinia-toast.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"rivinia-toast.mjs","names":[],"sources":["../../../projects/toast/src/lib/toast-utils.ts","../../../projects/toast/src/lib/toast-config.ts","../../../projects/toast/src/lib/rivinia-toast.ts","../../../projects/toast/src/lib/provide-toast.ts"],"sourcesContent":["import type { Signal } from '@angular/core';\nimport type { ToastMessage } from './toast-types';\n\n/**\n * Reads a toast message regardless of shape. Future UI entry points call this\n * in templates — one place to support `string | Signal<string>`.\n */\nexport function resolveToastText(message: ToastMessage): string {\n  return typeof message === 'string' ? message : (message as Signal<string>)();\n}\n\n/**\n * Normalizes a duration into a safe non-negative integer.\n * `0`, negatives, `NaN` and non-finite values all mean persistent (no timer).\n * Rationale: a `setTimeout(Infinity)` silently overflows to ~1ms in browsers —\n * converting to persistent is the only non-surprising mapping.\n */\nexport function clampDuration(value: number | undefined, fallback: number): number {\n  const candidate = value === undefined ? fallback : value;\n  if (typeof candidate !== 'number' || !Number.isFinite(candidate) || candidate <= 0) {\n    return 0;\n  }\n  return Math.floor(candidate);\n}\n","import { InjectionToken } from '@angular/core';\nimport type { ToastKind, ToastOverflowPolicy } from './toast-types';\n\n/**\n * Global configuration for `@rivinia/toast`.\n *\n * Every field is optional. Per-toast options always win over globals.\n * URLs, icons, positions, styles: intentionally absent — presentation is\n * app-owned (a future `@rivinia/toast/ui` entry point will consume this Core).\n */\nexport interface RiviniaToastConfig {\n  /**\n   * Default auto-dismiss delay in milliseconds.\n   * @default 5000\n   */\n  duration?: number;\n  /**\n   * Per-kind default delays. A per-toast `duration` beats both levels.\n   * @default {} (every kind falls back to `duration`)\n   */\n  durations?: Partial<Record<ToastKind, number>>;\n  /**\n   * Maximum simultaneously visible (active) toasts. Clamped to ≥ 1.\n   * @default 5 (industry standard: shadcn `TOAST_LIMIT = 3`, BRT `MAX_VISIBLE = 5`)\n   */\n  maxVisible?: number;\n  /**\n   * Maximum queued toasts when `overflow: 'queue'`. Further shows are rejected.\n   * @default Infinity (bounded only if you bound it — an unbounded queue is a\n   * documented leak risk for hot paths; prefer `'dismiss-oldest'` there)\n   */\n  maxQueue?: number;\n  /**\n   * What happens when a new toast arrives while `maxVisible` are active.\n   * - `'dismiss-oldest'`: dismiss the oldest active toast, show the new one.\n   * - `'queue'`: hold the new toast (no timer runs) until room frees up.\n   * - `'reject'`: `show()` returns `null`; nothing changes.\n   * @default 'dismiss-oldest'\n   */\n  overflow?: ToastOverflowPolicy;\n}\n\n/**\n * Internal configuration token. Consumers must use `provideRiviniaToast()`.\n * @internal\n */\nexport const RIVINIA_TOAST_CONFIG = new InjectionToken<RiviniaToastConfig>(\n  'RIVINIA_TOAST_CONFIG',\n);\n\nexport const DEFAULT_DURATION = 5000;\nexport const DEFAULT_MAX_VISIBLE = 5;\n","import { DestroyRef, inject, Service, signal } from '@angular/core';\nimport {\n  DEFAULT_DURATION,\n  DEFAULT_MAX_VISIBLE,\n  RIVINIA_TOAST_CONFIG,\n  type RiviniaToastConfig,\n} from './toast-config';\nimport type {\n  Toast,\n  ToastChanges,\n  ToastKind,\n  ToastOptions,\n} from './toast-types';\nimport { clampDuration } from './toast-utils';\n\ninterface TimerRecord {\n  handle: ReturnType<typeof setTimeout>;\n  startedAt: number;\n  generation: number;\n}\n\n/**\n * Headless toast queue owner.\n *\n * State: two readonly signals — `active` (visible, capped) and `queue`\n * (overflow waiting, timerless). Who changes it: only the methods below.\n * Timers: one `setTimeout` per active timed toast, guarded by a per-toast\n * generation so a stale fire can never dismiss an updated toast. No DOM,\n * no styles, no router — presentation and navigation policy are app-owned\n * (see README recipes).\n */\n@Service()\nexport class RiviniaToast {\n  private readonly config = inject<RiviniaToastConfig>(RIVINIA_TOAST_CONFIG, {\n    optional: true,\n  });\n\n  private readonly _active = signal<Toast[]>([]);\n  private readonly _queue = signal<Toast[]>([]);\n\n  /** Visible toasts, oldest first. Never exceeds effective `maxVisible`. */\n  readonly active = this._active.asReadonly();\n  /** Overflow waiting for room. No timers run while queued. */\n  readonly queue = this._queue.asReadonly();\n\n  private readonly _timers = new Map<number, TimerRecord>();\n  private readonly _generations = new Map<number, number>();\n  private readonly _dedupeByKey = new Map<string, number>();\n  private readonly _dedupeKeyById = new Map<number, string>();\n  private _nextId = 0;\n\n  constructor() {\n    inject(DestroyRef).onDestroy(() => this.clearTimers());\n  }\n\n  /**\n   * Shows a toast. Returns its stable id, or `null` when rejected by the\n   * `'reject'` overflow policy (or a full finite queue).\n   */\n  show(options: ToastOptions): number | null {\n    if (options.dedupeKey !== undefined) {\n      const existing = this.findByDedupeKey(options.dedupeKey);\n      if (existing !== null) {\n        this.update(existing, {\n          message: options.message,\n          kind: options.kind,\n          duration: options.duration,\n          action: options.action ?? null,\n        });\n        return existing;\n      }\n    }\n\n    const id = ++this._nextId;\n    const kind = options.kind ?? 'info';\n    const duration = this.resolveDuration(kind, options.duration);\n    const toast: Toast = {\n      id,\n      kind,\n      message: options.message,\n      duration,\n      remaining: duration,\n      action: options.action ?? null,\n    };\n    if (options.dedupeKey !== undefined) {\n      this._dedupeByKey.set(options.dedupeKey, id);\n      this._dedupeKeyById.set(id, options.dedupeKey);\n    }\n\n    if (this._active().length < this.maxVisible()) {\n      this._active.update((list) => [...list, toast]);\n      this.arm(id, duration);\n      return id;\n    }\n\n    switch (this.config?.overflow ?? 'dismiss-oldest') {\n      case 'queue': {\n        if (this._queue().length >= this.maxQueue()) {\n          this.forgetDedupe(id);\n          return null;\n        }\n        this._queue.update((list) => [...list, toast]);\n        return id;\n      }\n      case 'reject':\n        this.forgetDedupe(id);\n        return null;\n      case 'dismiss-oldest':\n      default: {\n        const oldest = this._active()[0];\n        if (oldest) this.dismiss(oldest.id);\n        this._active.update((list) => [...list, toast]);\n        this.arm(id, duration);\n        return id;\n      }\n    }\n  }\n\n  /**\n   * Merges changes into an active or queued toast and restarts its timer\n   * with the new duration (unchanged when `changes.duration` is absent).\n   * Unknown ids (never shown or already dismissed): no-op, returns `false`.\n   */\n  update(id: number, changes: ToastChanges): boolean {\n    const inActive = this._active().some((t) => t.id === id);\n    const apply = (t: Toast): Toast => ({\n      ...t,\n      message: changes.message ?? t.message,\n      kind: changes.kind ?? t.kind,\n      duration: changes.duration !== undefined ? clampDuration(changes.duration, t.duration) : t.duration,\n      remaining:\n        changes.duration !== undefined ? clampDuration(changes.duration, t.duration) : t.duration,\n      action: changes.action !== undefined ? changes.action : t.action,\n    });\n    if (inActive) {\n      this.disarm(id);\n      let next: Toast | undefined;\n      this._active.update((list) =>\n        list.map((t) => {\n          if (t.id !== id) return t;\n          next = apply(t);\n          return next;\n        }),\n      );\n      if (next) this.arm(id, next.duration);\n      return true;\n    }\n    let found = false;\n    this._queue.update((list) =>\n      list.map((t) => {\n        if (t.id !== id) return t;\n        found = true;\n        return apply(t);\n      }),\n    );\n    return found;\n  }\n\n  /**\n   * Removes a toast wherever it lives, clearing its timer. Unknown ids and\n   * repeated calls: no-op, returns `false`. Removing an active toast promotes\n   * the queue head (if any), whose timer starts at promotion.\n   */\n  dismiss(id: number): boolean {\n    this.disarm(id);\n    let removed = false;\n    this._active.update((list) => {\n      const next = list.filter((t) => t.id !== id);\n      removed = next.length !== list.length;\n      return next;\n    });\n    if (!removed) {\n      this._queue.update((list) => {\n        const next = list.filter((t) => t.id !== id);\n        removed = next.length !== list.length;\n        return next;\n      });\n    }\n    if (removed) {\n      this.forgetDedupe(id);\n      this.promote();\n    }\n    return removed;\n  }\n\n  /** Clears timers, active and queue. Ids keep incrementing (never reused). */\n  dismissAll(): void {\n    this.clearTimers();\n    this._active.set([]);\n    this._queue.set([]);\n    this._dedupeByKey.clear();\n    this._dedupeKeyById.clear();\n  }\n\n  /**\n   * Suspends the active timer, preserving `remaining`. UI binds this to\n   * hover/focus (WCAG 2.2.1 timing control). Returns `false` for unknown ids,\n   * queued/persistent toasts, or already-paused timers.\n   */\n  pause(id: number): boolean {\n    const record = this._timers.get(id);\n    if (!record) return false;\n    clearTimeout(record.handle);\n    this._timers.delete(id);\n    const elapsed = Date.now() - record.startedAt;\n    this._active.update((list) =>\n      list.map((t) =>\n        t.id === id ? { ...t, remaining: Math.max(0, t.remaining - elapsed) } : t,\n      ),\n    );\n    return true;\n  }\n\n  /**\n   * Restarts a paused timer with the preserved `remaining`. A toast paused at\n   * zero remaining is dismissed instead (it logically already expired).\n   */\n  resume(id: number): boolean {\n    if (this._timers.has(id)) return false;\n    const toast = this._active().find((t) => t.id === id);\n    if (!toast) return false;\n    if (toast.remaining <= 0) {\n      this.dismiss(id);\n      return true;\n    }\n    this.arm(id, toast.remaining);\n    return true;\n  }\n\n  /**\n   * Runs the toast action callback, then dismisses unless the action opts out\n   * via `dismissAfterPress: false`. Callback exceptions propagate to the caller.\n   * Returns `false` when the toast or its action is missing.\n   */\n  runAction(id: number): boolean {\n    const toast =\n      this._active().find((t) => t.id === id) ?? this._queue().find((t) => t.id === id);\n    if (!toast?.action) return false;\n    toast.action.onPress();\n    if (toast.action.dismissAfterPress ?? true) this.dismiss(id);\n    return true;\n  }\n\n  private maxVisible(): number {\n    const value = this.config?.maxVisible ?? DEFAULT_MAX_VISIBLE;\n    return Math.max(1, Math.floor(value));\n  }\n\n  private maxQueue(): number {\n    const value = this.config?.maxQueue ?? Number.POSITIVE_INFINITY;\n    return value < 0 ? 0 : value;\n  }\n\n  private resolveDuration(kind: ToastKind, override?: number): number {\n    if (override !== undefined) return clampDuration(override, this.fallbackDuration(kind));\n    return this.fallbackDuration(kind);\n  }\n\n  private fallbackDuration(kind: ToastKind): number {\n    const perKind = this.config?.durations?.[kind];\n    if (perKind !== undefined) return clampDuration(perKind, DEFAULT_DURATION);\n    return clampDuration(this.config?.duration, DEFAULT_DURATION);\n  }\n\n  private arm(id: number, delay: number): void {\n    if (delay <= 0) return;\n    const generation = (this._generations.get(id) ?? 0) + 1;\n    this._generations.set(id, generation);\n    this._timers.set(id, {\n      handle: setTimeout(() => {\n        // Stale-guard: only the latest generation may dismiss.\n        if (this._timers.get(id)?.generation === generation) this.dismiss(id);\n      }, delay),\n      startedAt: Date.now(),\n      generation,\n    });\n  }\n\n  private disarm(id: number): void {\n    const record = this._timers.get(id);\n    if (record) {\n      clearTimeout(record.handle);\n      this._timers.delete(id);\n    }\n  }\n\n  private clearTimers(): void {\n    for (const record of this._timers.values()) clearTimeout(record.handle);\n    this._timers.clear();\n  }\n\n  private promote(): void {\n    while (this._active().length < this.maxVisible() && this._queue().length > 0) {\n      const head = this._queue()[0];\n      this._queue.update((list) => list.slice(1));\n      const fresh: Toast = { ...head, remaining: head.duration };\n      this._active.update((list) => [...list, fresh]);\n      this.arm(fresh.id, fresh.duration);\n    }\n  }\n\n  private findByDedupeKey(key: string): number | null {\n    const id = this._dedupeByKey.get(key);\n    if (id === undefined) return null;\n    const present =\n      this._active().some((t) => t.id === id) || this._queue().some((t) => t.id === id);\n    if (!present) {\n      this.forgetDedupe(id);\n      return null;\n    }\n    return id;\n  }\n\n  private forgetDedupe(id: number): void {\n    const key = this._dedupeKeyById.get(id);\n    if (key !== undefined) {\n      this._dedupeKeyById.delete(id);\n      if (this._dedupeByKey.get(key) === id) this._dedupeByKey.delete(key);\n    }\n  }\n}\n","import { EnvironmentProviders, inject, makeEnvironmentProviders } from '@angular/core';\nimport { RIVINIA_TOAST_CONFIG, type RiviniaToastConfig } from './toast-config';\nimport { RiviniaToast } from './rivinia-toast';\n\n/**\n * Configures `@rivinia/toast`. The queue is a root singleton; call once at\n * bootstrap. Presentation (outlet component, position, styles, icons,\n * translations) stays app-owned — a future `@rivinia/toast/ui` entry point\n * will consume the same `RiviniaToast` state.\n *\n * @example\n * ```ts\n * provideRiviniaToast({ duration: 5000, maxVisible: 5 })\n * ```\n */\nexport function provideRiviniaToast(config: RiviniaToastConfig = {}): EnvironmentProviders {\n  return makeEnvironmentProviders([{ provide: RIVINIA_TOAST_CONFIG, useValue: config }]);\n}\n\n/** Shorthand for `inject(RiviniaToast)`. */\nexport function injectRiviniaToast(): RiviniaToast {\n  return inject(RiviniaToast);\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@rivinia/toast",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Headless toast queue for Angular with optional UI outlet: signals, pause-on-hover timers, actions.",
+  "keywords": [
+    "angular",
+    "toast",
+    "notification",
+    "signals",
+    "typescript"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@angular/core": "^22.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "schematics": "./schematics/collection.json",
+  "module": "fesm2022/rivinia-toast.mjs",
+  "typings": "types/rivinia-toast.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/rivinia-toast.d.ts",
+      "default": "./fesm2022/rivinia-toast.mjs"
+    }
+  },
+  "type": "module"
 }

package/schematics/collection.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
+  "schematics": {
+    "ng-add": {
+      "description": "Add provideRiviniaToast() to the application config.",
+      "factory": "./ng-add/index.cjs#ngAdd",
+      "schema": "./ng-add/schema.json"
+    }
+  }
+}

package/schematics/ng-add/index.cjs

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ngAdd = ngAdd;
+const schematics_1 = require("@angular-devkit/schematics");
+const PROVIDE_IMPORT = `import { provideRiviniaToast } from '@rivinia/toast';`;
+/**
+ * `ng add @rivinia/toast` — wires the library into a standalone app config.
+ *
+ * - Never overwrites user files; only inserts one import + one provider.
+ * - Idempotent: safe to run twice (existing entries are detected and skipped).
+ * - No prompts by design: duration/maxVisible are one-line edits, and every
+ *   extra question is a papercut. Pass `--duration` / `--max-visible` flags
+ *   or edit the emitted call afterwards.
+ */
+function ngAdd(options) {
+    return (tree, context) => {
+        let configPath;
+        try {
+            configPath = findAppConfig(tree, options.project);
+        }
+        catch (error) {
+            context.logger.warn(`[rivinia/toast] workspace lookup failed (${error instanceof Error ? error.message : error}) — skipping. ` +
+                `Add provideRiviniaToast() manually (see README).`);
+            return tree;
+        }
+        if (!configPath || !tree.exists(configPath)) {
+            context.logger.warn(`[rivinia/toast] app.config.ts not found — skipping. ` +
+                `Add provideRiviniaToast() manually (see README).`);
+            return tree;
+        }
+        let content = tree.read(configPath)?.toString('utf-8') ?? '';
+        if (!content) {
+            throw new schematics_1.SchematicsException(`[rivinia/toast] ${configPath} is empty.`);
+        }
+        const parts = [];
+        if (options.duration !== undefined)
+            parts.push(`duration: ${options.duration}`);
+        if (options.maxVisible !== undefined)
+            parts.push(`maxVisible: ${options.maxVisible}`);
+        const provideCall = `provideRiviniaToast(${parts.length > 0 ? `{ ${parts.join(', ')} }` : ''})`;
+        let changed = false;
+        if (!content.includes(PROVIDE_IMPORT)) {
+            content = insertAfterLastImport(content, PROVIDE_IMPORT);
+            changed = true;
+        }
+        if (!content.includes('provideRiviniaToast(')) {
+            content = insertProvider(content, provideCall);
+            changed = true;
+        }
+        else {
+            context.logger.info('[rivinia/toast] provideRiviniaToast() already present — skipped.');
+        }
+        if (changed) {
+            tree.overwrite(configPath, content);
+            context.logger.info(`[rivinia/toast] wired into ${configPath}.`);
+        }
+        return tree;
+    };
+}
+function defaultProjectName(tree, requested) {
+    if (requested)
+        return requested;
+    const angularJson = tree.read('/angular.json')?.toString('utf-8');
+    if (!angularJson) {
+        throw new schematics_1.SchematicsException('[rivinia/toast] angular.json not found.');
+    }
+    const workspace = JSON.parse(angularJson);
+    if (workspace.defaultProject && typeof workspace.defaultProject === 'string') {
+        return workspace.defaultProject;
+    }
+    const names = Object.keys(workspace.projects ?? {});
+    if (names.length === 0) {
+        throw new schematics_1.SchematicsException('[rivinia/toast] no projects in angular.json.');
+    }
+    return names[0];
+}
+function findAppConfig(tree, requestedProject) {
+    const angularJson = tree.read('/angular.json')?.toString('utf-8');
+    if (!angularJson)
+        return null;
+    const workspace = JSON.parse(angularJson);
+    const name = defaultProjectName(tree, requestedProject);
+    const project = workspace.projects?.[name];
+    if (!project)
+        return null;
+    const sourceRoot = project.sourceRoot ?? (project.root ? `${project.root}/src` : 'src');
+    return `/${sourceRoot}/app/app.config.ts`;
+}
+function insertAfterLastImport(content, line) {
+    const lines = content.split('\n');
+    let idx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/^\s*import\s/.test(lines[i]))
+            idx = i;
+    }
+    lines.splice(idx + 1, 0, line);
+    return lines.join('\n');
+}
+function insertProvider(content, call) {
+    const match = /providers\s*:\s*\[/.exec(content);
+    if (!match) {
+        throw new schematics_1.SchematicsException('[rivinia/toast] no `providers: [` array found in app.config.ts — add providers manually.');
+    }
+    const at = match.index + match[0].length;
+    return `${content.slice(0, at)}\n    ${call},${content.slice(at)}`;
+}

package/schematics/ng-add/schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/schema",
+  "$id": "rivinia-toast-ng-add",
+  "title": "Rivinia Toast ng-add options",
+  "type": "object",
+  "properties": {
+    "duration": {
+      "type": "number",
+      "description": "Global default auto-dismiss delay in milliseconds for provideRiviniaToast({ duration }). Omit to keep the 5000 default."
+    },
+    "maxVisible": {
+      "type": "number",
+      "description": "Maximum simultaneously visible toasts for provideRiviniaToast({ maxVisible }). Omit to keep the 5 default."
+    },
+    "project": {
+      "type": "string",
+      "description": "Angular CLI project name — only for multi-app workspaces. Defaults to the workspace default project.",
+      "default": ""
+    }
+  },
+  "required": []
+}

package/types/rivinia-toast.d.ts

@@ -0,0 +1,213 @@
+import * as i0 from "@angular/core";
+import { EnvironmentProviders, InjectionToken, Signal } from "@angular/core";
+/**
+ * Semantic severity. Core treats this as data only (default durations,
+ * UI icon/role mapping) — never as styling.
+ */
+type ToastKind = 'success' | 'error' | 'info' | 'warning';
+/**
+ * Toast text without i18n coupling: pass a plain string, or a `Signal<string>`
+ * (e.g. a `computed` over your language service) for reactive re-translation.
+ * The future UI reads it via `resolveToastText()`.
+ */
+type ToastMessage = string | Signal<string>;
+/**
+ * Optional call-to-action. DOM wiring (click handlers) lives in UI code,
+ * which calls `runAction(id)` — Core only owns the metadata + callback.
+ */
+interface ToastAction {
+  /** Button label: plain string or reactive signal. */
+  readonly label: ToastMessage;
+  /** Runs when the UI triggers the action. Exceptions propagate to the caller. */
+  readonly onPress: () => void;
+  /**
+   * Dismiss the toast after `onPress` runs.
+   * @default true
+   */
+  readonly dismissAfterPress?: boolean;
+}
+/** A live notification. All fields readonly — mutate via service methods. */
+interface Toast {
+  /** Stable monotonic identifier. Never reused, even after dismissal. */
+  readonly id: number;
+  readonly kind: ToastKind;
+  readonly message: ToastMessage;
+  /** Resolved auto-dismiss delay in ms. `0` = persistent (no timer). */
+  readonly duration: number;
+  /** Milliseconds left on the active timer. Equals `duration` when fresh/queued. */
+  readonly remaining: number;
+  readonly action: ToastAction | null;
+}
+/** Arguments to `show()`. */
+interface ToastOptions {
+  readonly message: ToastMessage;
+  readonly kind?: ToastKind;
+  /** Overrides every configured default. `0` (or negative/NaN) = persistent. */
+  readonly duration?: number;
+  readonly action?: ToastAction;
+  /**
+   * Opt-in deduplication scope. A second `show()` with an equal key updates the
+   * existing active-or-queued toast in place (content replaced, timer restarted)
+   * and returns its id — instead of opening a duplicate. No key = no dedupe.
+   */
+  readonly dedupeKey?: string;
+}
+/** Partial changes for `update()`. Re-keying is not supported. */
+interface ToastChanges {
+  readonly message?: ToastMessage;
+  readonly kind?: ToastKind;
+  /** When provided, the timer restarts with the new duration. */
+  readonly duration?: number;
+  /** `null` removes an existing action. */
+  readonly action?: ToastAction | null;
+}
+/**
+ * Overflow behavior when showing past `maxVisible` active toasts.
+ * See `RiviniaToastConfig.overflow` for semantics.
+ */
+type ToastOverflowPolicy = 'dismiss-oldest' | 'queue' | 'reject';
+/**
+ * Global configuration for `@rivinia/toast`.
+ *
+ * Every field is optional. Per-toast options always win over globals.
+ * URLs, icons, positions, styles: intentionally absent — presentation is
+ * app-owned (a future `@rivinia/toast/ui` entry point will consume this Core).
+ */
+interface RiviniaToastConfig {
+  /**
+   * Default auto-dismiss delay in milliseconds.
+   * @default 5000
+   */
+  duration?: number;
+  /**
+   * Per-kind default delays. A per-toast `duration` beats both levels.
+   * @default {} (every kind falls back to `duration`)
+   */
+  durations?: Partial<Record<ToastKind, number>>;
+  /**
+   * Maximum simultaneously visible (active) toasts. Clamped to ≥ 1.
+   * @default 5 (industry standard: shadcn `TOAST_LIMIT = 3`, BRT `MAX_VISIBLE = 5`)
+   */
+  maxVisible?: number;
+  /**
+   * Maximum queued toasts when `overflow: 'queue'`. Further shows are rejected.
+   * @default Infinity (bounded only if you bound it — an unbounded queue is a
+   * documented leak risk for hot paths; prefer `'dismiss-oldest'` there)
+   */
+  maxQueue?: number;
+  /**
+   * What happens when a new toast arrives while `maxVisible` are active.
+   * - `'dismiss-oldest'`: dismiss the oldest active toast, show the new one.
+   * - `'queue'`: hold the new toast (no timer runs) until room frees up.
+   * - `'reject'`: `show()` returns `null`; nothing changes.
+   * @default 'dismiss-oldest'
+   */
+  overflow?: ToastOverflowPolicy;
+}
+/**
+ * Internal configuration token. Consumers must use `provideRiviniaToast()`.
+ * @internal
+ */
+declare const RIVINIA_TOAST_CONFIG: InjectionToken<RiviniaToastConfig>;
+declare const DEFAULT_DURATION = 5000;
+declare const DEFAULT_MAX_VISIBLE = 5;
+/**
+ * Reads a toast message regardless of shape. Future UI entry points call this
+ * in templates — one place to support `string | Signal<string>`.
+ */
+export declare function resolveToastText(message: ToastMessage): string;
+/**
+ * Normalizes a duration into a safe non-negative integer.
+ * `0`, negatives, `NaN` and non-finite values all mean persistent (no timer).
+ * Rationale: a `setTimeout(Infinity)` silently overflows to ~1ms in browsers —
+ * converting to persistent is the only non-surprising mapping.
+ */
+export declare function clampDuration(value: number | undefined, fallback: number): number;
+/**
+ * Headless toast queue owner.
+ *
+ * State: two readonly signals — `active` (visible, capped) and `queue`
+ * (overflow waiting, timerless). Who changes it: only the methods below.
+ * Timers: one `setTimeout` per active timed toast, guarded by a per-toast
+ * generation so a stale fire can never dismiss an updated toast. No DOM,
+ * no styles, no router — presentation and navigation policy are app-owned
+ * (see README recipes).
+ */
+export declare class RiviniaToast {
+  private readonly config;
+  private readonly _active;
+  private readonly _queue;
+  /** Visible toasts, oldest first. Never exceeds effective `maxVisible`. */
+  readonly active: import("@angular/core").Signal<Toast[]>;
+  /** Overflow waiting for room. No timers run while queued. */
+  readonly queue: import("@angular/core").Signal<Toast[]>;
+  private readonly _timers;
+  private readonly _generations;
+  private readonly _dedupeByKey;
+  private readonly _dedupeKeyById;
+  private _nextId;
+  constructor();
+  /**
+   * Shows a toast. Returns its stable id, or `null` when rejected by the
+   * `'reject'` overflow policy (or a full finite queue).
+   */
+  show(options: ToastOptions): number | null;
+  /**
+   * Merges changes into an active or queued toast and restarts its timer
+   * with the new duration (unchanged when `changes.duration` is absent).
+   * Unknown ids (never shown or already dismissed): no-op, returns `false`.
+   */
+  update(id: number, changes: ToastChanges): boolean;
+  /**
+   * Removes a toast wherever it lives, clearing its timer. Unknown ids and
+   * repeated calls: no-op, returns `false`. Removing an active toast promotes
+   * the queue head (if any), whose timer starts at promotion.
+   */
+  dismiss(id: number): boolean;
+  /** Clears timers, active and queue. Ids keep incrementing (never reused). */
+  dismissAll(): void;
+  /**
+   * Suspends the active timer, preserving `remaining`. UI binds this to
+   * hover/focus (WCAG 2.2.1 timing control). Returns `false` for unknown ids,
+   * queued/persistent toasts, or already-paused timers.
+   */
+  pause(id: number): boolean;
+  /**
+   * Restarts a paused timer with the preserved `remaining`. A toast paused at
+   * zero remaining is dismissed instead (it logically already expired).
+   */
+  resume(id: number): boolean;
+  /**
+   * Runs the toast action callback, then dismisses unless the action opts out
+   * via `dismissAfterPress: false`. Callback exceptions propagate to the caller.
+   * Returns `false` when the toast or its action is missing.
+   */
+  runAction(id: number): boolean;
+  private maxVisible;
+  private maxQueue;
+  private resolveDuration;
+  private fallbackDuration;
+  private arm;
+  private disarm;
+  private clearTimers;
+  private promote;
+  private findByDedupeKey;
+  private forgetDedupe;
+  static ɵfac: i0.ɵɵFactoryDeclaration<RiviniaToast, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+/**
+ * Configures `@rivinia/toast`. The queue is a root singleton; call once at
+ * bootstrap. Presentation (outlet component, position, styles, icons,
+ * translations) stays app-owned — a future `@rivinia/toast/ui` entry point
+ * will consume the same `RiviniaToast` state.
+ *
+ * @example
+ * ```ts
+ * provideRiviniaToast({ duration: 5000, maxVisible: 5 })
+ * ```
+ */
+export declare function provideRiviniaToast(config?: RiviniaToastConfig): EnvironmentProviders;
+/** Shorthand for `inject(RiviniaToast)`. */
+export declare function injectRiviniaToast(): RiviniaToast;
+export type { RiviniaToastConfig, Toast, ToastAction, ToastChanges, ToastKind, ToastMessage, ToastOptions, ToastOverflowPolicy };