@kouji-ui/core 0.0.4 → 0.1.1

package/src/toast/toast.service.ts

@@ -1,8 +1,18 @@
-import { Injectable, TemplateRef, inject, signal } from '@angular/core';
+import { EnvironmentInjector, Injectable, TemplateRef, Type, effect, inject, runInInjectionContext, signal } from '@angular/core';
+import { KjOverlayBuilder } from '../primitives/overlay/builder';
+import { inPlace } from '../primitives/overlay/strategies/mount/in-place';
+import { corner, type KjCornerPosition } from '../primitives/overlay/strategies/position/corner';
+import { polite } from '../primitives/overlay/strategies/live-announcer/polite';
+import { assertive } from '../primitives/overlay/strategies/live-announcer/assertive';
+import { programmatic } from '../primitives/overlay/strategies/trigger-event/programmatic';
 import { KJ_TOAST_STRATEGY } from './toast.strategy';
+import { KjToastRef } from './toast.ref';
 
 export type KjToastVariant = 'default' | 'success' | 'destructive' | 'warning';
 
+/** Variant tag accepted by the variant-sugar methods (`success`/`info`/`warn`/`error`). */
+export type KjToastSugarVariant = 'success' | 'info' | 'warn' | 'error';
+
 /**
  * Shape `[kjToastDefaultTemplate]` and per-call templates receive via `ngTemplateOutlet`.
  * Inherits every `KjToastContext` field for `let-id="id"`-style bindings, plus `$implicit`
@@ -34,12 +44,20 @@ export interface KjToastOptions<TData = unknown> {
   id?: string;
   /** Optional title rendered above the message. */
   title?: string;
+  /** Plain text message — set when not using a custom template. */
+  message?: string;
   /** Visual / semantic variant. Defaults to `'default'`. */
   variant?: KjToastVariant;
   /** Auto-dismiss delay in ms. `0` = persistent. Defaults to `5000`. */
   duration?: number;
   /** Arbitrary payload exposed to the template via `ctx.data`. */
   data?: TData;
+  /** Override the corner position used for the overlay. Defaults to `'bottom-right'`. */
+  position?: KjCornerPosition;
+  /** Optional component to mount as the toast body. */
+  component?: Type<unknown>;
+  /** Optional template for queue-based rendering through `<kj-toast-viewport>`. */
+  template?: TemplateRef<KjToastTemplateContext<TData>>;
 }
 
 /** Internal queue item — tracked by the service, consumed by `KjToastViewport`. */
@@ -54,90 +72,258 @@ export interface KjToastItem<TData = unknown> {
   readonly template?: TemplateRef<KjToastTemplateContext<TData>>;
 }
 
+/** Reasons that can hold the auto-dismiss timers in the paused state. Ref-counted. */
+export type KjToastPauseReason = 'hover' | 'focus' | 'manual';
+
+/** Internal timer tracking for an in-flight toast — supports pause / resume. */
+interface KjToastTimer {
+  /** The active `setTimeout` handle, or `null` while paused. */
+  handle: ReturnType<typeof setTimeout> | null;
+  /** Original duration (ms) used to compute remaining on pause. */
+  duration: number;
+  /** When the current `setTimeout` was started. Used to compute remaining on pause. */
+  startedAt: number;
+  /** Time left to fire when paused. */
+  remaining: number;
+}
+
+const VARIANT_FROM_SUGAR: Record<KjToastSugarVariant, KjToastVariant> = {
+  success: 'success',
+  info: 'default',
+  warn: 'warning',
+  error: 'destructive',
+};
+
 /**
  * Programmatic API for toast notifications.
  *
- * Two ways to show a toast:
- * - `show(template, options)` — full template control. Markup, layout, icons, action buttons all owned by the client.
- * - `show(message, options)` — string shorthand. Uses the viewport's `[kjToastDefaultTemplate]`.
- *
- * @example
- * ```ts
- * private readonly toast = inject(KjToastService);
+ * Two ways to dispatch a toast:
+ * - `show(opts)` (and the `success`/`info`/`warn`/`error` sugar) — overlay-based.
+ *   Each call creates an overlay via `KjOverlayBuilder`, anchored at the chosen
+ *   corner, returning a `KjToastRef` for programmatic dismissal.
+ * - The legacy queue API (`show(message|template, options)` returning a string id)
+ *   is preserved so consumers using `<kj-toast-viewport>` to render their own
+ *   queue continue to work. Auto-dismiss + pause/resume + max-visible logic
+ *   lives on this service regardless of which entry-point a caller uses.
  *
- * save()    { this.toast.success('Saved!'); }
- * undoable() {
- *   this.toast.show(this.undoTpl, { duration: 8000, data: { entityId: 42 } });
- * }
- * ```
- * @category Core/Overlays
+ * @doc-category Core/Overlay
  */
 @Injectable({ providedIn: 'root' })
 export class KjToastService {
   private readonly strategy = inject(KJ_TOAST_STRATEGY);
+  private readonly builder = inject(KjOverlayBuilder);
+  private readonly env = inject(EnvironmentInjector);
   private readonly _toasts = signal<KjToastItem[]>([]);
   /** Live list of active toasts. Read by `[kjToastViewport]`. */
   readonly toasts = this._toasts.asReadonly();
 
-  private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();
+  private readonly timers = new Map<string, KjToastTimer>();
 
-  /** Show a toast with a custom template. Returns the toast id. */
-  show<T = unknown>(template: TemplateRef<KjToastTemplateContext<T>>, options?: KjToastOptions<T>): string;
+  /** Holds active overlay controllers keyed by toast id so dismiss can close them. */
+  private readonly overlays = new Map<string, { close: () => void }>();
+
+  /**
+   * Ref-counted pause depth, keyed by reason. A timer is considered paused
+   * while any reason holds a non-zero count.
+   */
+  private readonly pauseDepth = new Map<KjToastPauseReason, number>();
+
+  /**
+   * Overlay-based entry point. Builds an overlay via `KjOverlayBuilder` with
+   * `bodyPortal` mount, `corner` positioning and a polite/assertive live
+   * announcer based on the variant. Returns a `KjToastRef` whose `close()`
+   * dismisses the toast and unwinds the overlay.
+   */
+  show<TData = unknown>(opts: KjToastOptions<TData>): KjToastRef;
   /** Show a toast with a plain text message. The viewport's default template renders it. */
   show(message: string, options?: KjToastOptions): string;
-  show(content: TemplateRef<KjToastTemplateContext> | string, options: KjToastOptions = {}): string {
+  /** Show a toast with a custom template. Returns the toast id. */
+  show<TData = unknown>(template: TemplateRef<KjToastTemplateContext<TData>>, options?: KjToastOptions<TData>): string;
+  show(
+    arg: KjToastOptions | string | TemplateRef<KjToastTemplateContext>,
+    options: KjToastOptions = {},
+  ): KjToastRef | string {
+    if (typeof arg === 'string') {
+      return this.enqueue({ ...options, message: arg });
+    }
+    if (arg instanceof TemplateRef) {
+      return this.enqueue({ ...options, template: arg });
+    }
+    return this.openOverlay(arg);
+  }
+
+  private openOverlay(opts: KjToastOptions): KjToastRef {
+    const id = opts.id ?? crypto.randomUUID();
+    const variant = opts.variant ?? 'default';
+    const handle = this.builder.create({
+      mount: inPlace(),
+      position: corner({ position: opts.position ?? 'bottom-right' }),
+      backdrop: null,
+      focusTrap: null,
+      scrollLock: null,
+      liveAnnouncer: variant === 'destructive' ? assertive() : polite(),
+      trigger: programmatic(),
+      panelRole: variant === 'destructive' ? 'alert' : 'status',
+    });
+
+    if (opts.component) {
+      this.builder.attachComponent(handle, opts.component, { data: opts.data });
+    }
+
+    runInInjectionContext(this.env, () => {
+      let wasOpen = false;
+      const eff = effect(() => {
+        const s = handle.controller.state();
+        if (s === 'open' || s === 'opening') wasOpen = true;
+        if (s === 'closed' && wasOpen) {
+          eff.destroy();
+          queueMicrotask(() => handle.destroy());
+        }
+      });
+    });
+
+    this._toasts.update((ts) => [...ts, {
+      id,
+      variant,
+      duration: opts.duration ?? this.strategy.duration,
+      title: opts.title,
+      message: opts.message,
+      data: opts.data,
+      template: opts.template,
+    }]);
+
+    const dismiss = (toastId: string) => this.dismiss(toastId);
+    const ref = new KjToastRef(id, handle.controller, dismiss);
+    this.overlays.set(id, { close: () => handle.controller.close('programmatic') });
+
+    const duration = opts.duration ?? this.strategy.duration;
+    if (duration > 0) this.startTimer(id, duration);
+    handle.controller.open();
+    return ref;
+  }
+
+  private enqueue(options: KjToastOptions): string {
     const id = options.id ?? crypto.randomUUID();
-    const isTemplate = content instanceof TemplateRef;
     const toast: KjToastItem = {
       id,
       variant: options.variant ?? 'default',
       duration: options.duration ?? this.strategy.duration,
       title: options.title,
       data: options.data,
-      message: isTemplate ? undefined : content,
-      template: isTemplate ? content : undefined,
+      message: options.message,
+      template: options.template,
     };
-    this._toasts.update(ts => [...ts, toast]);
-    if (toast.duration > 0) {
-      this.timers.set(id, setTimeout(() => this.dismiss(id), toast.duration));
-    }
+    this._toasts.update((ts) => [...ts, toast]);
+    if (toast.duration > 0) this.startTimer(id, toast.duration);
     return id;
   }
 
-  /** Show a success toast (string shorthand). */
-  success(message: string, options?: Omit<KjToastOptions, 'variant'>): string {
-    return this.show(message, { ...options, variant: 'success' });
+  /** Show a success toast via the overlay-based API. */
+  success<TData = unknown>(opts: Omit<KjToastOptions<TData>, 'variant'> = {}): KjToastRef {
+    return this.openOverlay({ ...opts, variant: VARIANT_FROM_SUGAR.success });
+  }
+  /** Show an informational toast via the overlay-based API. */
+  info<TData = unknown>(opts: Omit<KjToastOptions<TData>, 'variant'> = {}): KjToastRef {
+    return this.openOverlay({ ...opts, variant: VARIANT_FROM_SUGAR.info });
+  }
+  /** Show a warning toast via the overlay-based API. */
+  warn<TData = unknown>(opts: Omit<KjToastOptions<TData>, 'variant'> = {}): KjToastRef {
+    return this.openOverlay({ ...opts, variant: VARIANT_FROM_SUGAR.warn });
+  }
+  /** Show an error toast via the overlay-based API. Uses `role="alert"` + assertive announcement. */
+  error<TData = unknown>(opts: Omit<KjToastOptions<TData>, 'variant'> = {}): KjToastRef {
+    return this.openOverlay({ ...opts, variant: VARIANT_FROM_SUGAR.error });
+  }
+
+  /**
+   * Pause every in-flight auto-dismiss timer, ref-counted by `reason`.
+   * Required by WCAG 2.2.1 (Timing Adjustable, AAA) and 1.4.13.
+   */
+  pause(reason: KjToastPauseReason): void {
+    const next = (this.pauseDepth.get(reason) ?? 0) + 1;
+    this.pauseDepth.set(reason, next);
+    if (next === 1 && this.totalPauseDepth() === 1) this.pauseAllTimers();
+  }
+
+  /** Decrement the ref-count for `reason`; re-arms timers when the total reaches zero. */
+  resume(reason: KjToastPauseReason): void {
+    const cur = this.pauseDepth.get(reason) ?? 0;
+    if (cur === 0) return;
+    const next = cur - 1;
+    if (next === 0) this.pauseDepth.delete(reason);
+    else this.pauseDepth.set(reason, next);
+    if (this.totalPauseDepth() === 0) this.resumeAllTimers();
   }
-  /** Show an error toast (string shorthand). */
-  error(message: string, options?: Omit<KjToastOptions, 'variant'>): string {
-    return this.show(message, { ...options, variant: 'destructive' });
+
+  /** True while any pause reason is held. */
+  isPaused(): boolean {
+    return this.totalPauseDepth() > 0;
+  }
+
+  private totalPauseDepth(): number {
+    let sum = 0;
+    for (const v of this.pauseDepth.values()) sum += v;
+    return sum;
+  }
+
+  private startTimer(id: string, duration: number): void {
+    if (this.isPaused()) {
+      this.timers.set(id, { handle: null, duration, startedAt: 0, remaining: duration });
+      return;
+    }
+    const handle = setTimeout(() => this.dismiss(id), duration);
+    this.timers.set(id, { handle, duration, startedAt: Date.now(), remaining: duration });
   }
-  /** Show a warning toast (string shorthand). */
-  warning(message: string, options?: Omit<KjToastOptions, 'variant'>): string {
-    return this.show(message, { ...options, variant: 'warning' });
+
+  private pauseAllTimers(): void {
+    for (const [id, t] of this.timers) {
+      if (t.handle == null) continue;
+      clearTimeout(t.handle);
+      const elapsed = Date.now() - t.startedAt;
+      const remaining = Math.max(0, t.duration - elapsed);
+      this.timers.set(id, { handle: null, duration: t.duration, startedAt: 0, remaining });
+    }
   }
-  /** Show an informational toast (string shorthand). */
-  info(message: string, options?: Omit<KjToastOptions, 'variant'>): string {
-    return this.show(message, { ...options, variant: 'default' });
+
+  private resumeAllTimers(): void {
+    for (const [id, t] of this.timers) {
+      if (t.handle != null) continue;
+      const remaining = t.remaining;
+      if (remaining <= 0) {
+        queueMicrotask(() => this.dismiss(id));
+        continue;
+      }
+      const handle = setTimeout(() => this.dismiss(id), remaining);
+      this.timers.set(id, { handle, duration: remaining, startedAt: Date.now(), remaining });
+    }
   }
 
   /** Manually dismiss a toast by id. */
   dismiss(id: string): void {
-    clearTimeout(this.timers.get(id));
+    const t = this.timers.get(id);
+    if (t?.handle != null) clearTimeout(t.handle);
     this.timers.delete(id);
-    this._toasts.update(ts => ts.filter(t => t.id !== id));
+    this._toasts.update((ts) => ts.filter((t) => t.id !== id));
+    const ov = this.overlays.get(id);
+    if (ov) {
+      this.overlays.delete(id);
+      ov.close();
+    }
   }
 
   /** Dismiss every active toast. */
   dismissAll(): void {
-    this.timers.forEach(t => clearTimeout(t));
+    for (const t of this.timers.values()) {
+      if (t.handle != null) clearTimeout(t.handle);
+    }
     this.timers.clear();
     this._toasts.set([]);
+    for (const ov of this.overlays.values()) ov.close();
+    this.overlays.clear();
   }
 
   /**
    * Builds a template context for a queued toast — used by `[kjToastViewport]` when rendering.
-   * `ctx.dismiss` is bound to this service.
    */
   contextFor<T>(toast: KjToastItem<T>): KjToastTemplateContext<T> {
     const ctx: KjToastContext<T> = {

package/src/toast/toast.spec.ts

@@ -1,12 +1,15 @@
-import { TestBed } from '@angular/core/testing';
+import { Component, TemplateRef, ViewChild } from '@angular/core';
+import { NgTemplateOutlet } from '@angular/common';
+import { TestBed } from '@angular/core/testing';
 import { render } from '@testing-library/angular';
 import { axe, toHaveNoViolations } from 'jest-axe';
 import { KjToast, KjToastViewport } from './toast';
-import { KjToastService } from './toast.service';
+import { KjToastService, type KjToastTemplateContext } from './toast.service';
+import { KjToastRef } from './toast.ref';
 
 expect.extend(toHaveNoViolations);
 
-describe('KjToast', () => {
+describe('KjToast directive', () => {
   it('sets role=status by default', async () => {
     const { container } = await render(`<div kjToast>Saved</div>`, { imports: [KjToast] });
     expect(container.querySelector('[kjToast]')).toHaveAttribute('role', 'status');
@@ -46,7 +49,45 @@ describe('KjToastViewport', () => {
   });
 });
 
-describe('KjToastService', () => {
+describe('KjToastService overlay API', () => {
+  let svc: KjToastService;
+
+  beforeEach(() => {
+    TestBed.configureTestingModule({});
+    svc = TestBed.inject(KjToastService);
+  });
+
+  afterEach(() => {
+    svc.dismissAll();
+  });
+
+  it('success() returns a KjToastRef', () => {
+    const ref = svc.success({ message: 'Saved' });
+    expect(ref).toBeInstanceOf(KjToastRef);
+    expect(typeof ref.close).toBe('function');
+    expect(typeof ref.id).toBe('string');
+  });
+
+  it('info() / warn() / error() each return a KjToastRef', () => {
+    expect(svc.info({ message: 'i' })).toBeInstanceOf(KjToastRef);
+    expect(svc.warn({ message: 'w' })).toBeInstanceOf(KjToastRef);
+    expect(svc.error({ message: 'e' })).toBeInstanceOf(KjToastRef);
+  });
+
+  it('error() builds an overlay whose controller exists', () => {
+    const ref = svc.error({ message: 'Boom' });
+    expect(ref.controller).toBeTruthy();
+  });
+
+  it('ref.close() removes the toast from the queue', () => {
+    const ref = svc.success({ message: 'Saved', duration: 0 });
+    expect(svc.toasts().some((t) => t.id === ref.id)).toBe(true);
+    ref.close();
+    expect(svc.toasts().some((t) => t.id === ref.id)).toBe(false);
+  });
+});
+
+describe('KjToastService queue API', () => {
   let svc: KjToastService;
 
   beforeEach(() => {
@@ -67,16 +108,6 @@ describe('KjToastService', () => {
     expect(svc.toasts().length).toBe(0);
   });
 
-  it('success() sets variant=success', () => {
-    svc.success('Done', { duration: 0 });
-    expect(svc.toasts()[0].variant).toBe('success');
-  });
-
-  it('error() sets variant=destructive', () => {
-    svc.error('Fail', { duration: 0 });
-    expect(svc.toasts()[0].variant).toBe('destructive');
-  });
-
   it('dismissAll() clears all toasts', () => {
     svc.show('A', { duration: 0 });
     svc.show('B', { duration: 0 });
@@ -93,3 +124,124 @@ describe('KjToastService', () => {
     expect(svc.toasts().length).toBe(0);
   });
 });
+
+describe('KjToastService pause / resume', () => {
+  let svc: KjToastService;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    TestBed.configureTestingModule({});
+    svc = TestBed.inject(KjToastService);
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('pauses the auto-dismiss timer while a reason is held', () => {
+    const id = svc.show('Pause me', { duration: 1000 });
+    vi.advanceTimersByTime(400);
+    svc.pause('hover');
+    vi.advanceTimersByTime(5000);
+    expect(svc.toasts().find((t) => t.id === id)).toBeDefined();
+  });
+
+  it('resume() re-arms with the remaining duration', () => {
+    svc.show('Resume me', { duration: 1000 });
+    vi.advanceTimersByTime(400);
+    svc.pause('hover');
+    vi.advanceTimersByTime(5000);
+    svc.resume('hover');
+    vi.advanceTimersByTime(599);
+    expect(svc.toasts().length).toBe(1);
+    vi.advanceTimersByTime(2);
+    expect(svc.toasts().length).toBe(0);
+  });
+
+  it('ref-counts pause/resume per reason', () => {
+    svc.show('Ref count', { duration: 1000 });
+    svc.pause('hover');
+    svc.pause('focus');
+    expect(svc.isPaused()).toBe(true);
+    svc.resume('hover');
+    expect(svc.isPaused()).toBe(true);
+    svc.resume('focus');
+    expect(svc.isPaused()).toBe(false);
+  });
+
+  it('an extra resume() never goes negative', () => {
+    svc.show('Extra resume', { duration: 1000 });
+    svc.resume('hover');
+    svc.resume('hover');
+    expect(svc.isPaused()).toBe(false);
+    svc.pause('hover');
+    expect(svc.isPaused()).toBe(true);
+    svc.resume('hover');
+    expect(svc.isPaused()).toBe(false);
+  });
+
+  it('dismiss() clears the active timer regardless of pause state', () => {
+    const id = svc.show('Dismiss while paused', { duration: 1000 });
+    svc.pause('hover');
+    svc.dismiss(id);
+    svc.resume('hover');
+    expect(svc.toasts().length).toBe(0);
+    vi.advanceTimersByTime(2000);
+    expect(svc.toasts().length).toBe(0);
+  });
+});
+
+describe('KjToastViewport interactions', () => {
+  @Component({
+    standalone: true,
+    imports: [KjToastViewport, KjToast, NgTemplateOutlet],
+    template: `
+      <button id="outside-btn">Outside</button>
+      <ol kjToastViewport [kjToastDefaultTemplate]="tpl" aria-label="Notifications" #vp="kjToastViewport">
+        @for (r of vp.renderable(); track r.id) {
+          <li>
+            <ng-container [ngTemplateOutlet]="r.template" [ngTemplateOutletContext]="r.context"></ng-container>
+          </li>
+        }
+      </ol>
+      <ng-template #tpl let-ctx>
+        <div kjToast [kjToastId]="ctx.id">
+          <span>{{ ctx.message }}</span>
+          <button class="action" (click)="ctx.dismiss()">Undo</button>
+        </div>
+      </ng-template>
+    `,
+  })
+  class _Host {
+    @ViewChild('tpl') tpl!: TemplateRef<KjToastTemplateContext>;
+  }
+
+  beforeEach(() => {
+    TestBed.resetTestingModule();
+    TestBed.configureTestingModule({});
+  });
+
+  it('host exposes tabindex="-1" so F6 can target it as a fallback', async () => {
+    const { container } = await render(`<div kjToastViewport></div>`, { imports: [KjToastViewport] });
+    expect(container.querySelector('[kjToastViewport]')).toHaveAttribute('tabindex', '-1');
+  });
+
+  it('pauses + resumes the service on pointer enter / leave', () => {
+    const svc = TestBed.inject(KjToastService);
+    svc.show('Hi', { duration: 0 });
+    @Component({
+      standalone: true,
+      imports: [KjToastViewport],
+      template: `<ol kjToastViewport></ol>`,
+    })
+    class Bare {}
+    const fixture = TestBed.createComponent(Bare);
+    fixture.detectChanges();
+    const vp = fixture.nativeElement.querySelector('[kjToastViewport]') as HTMLElement;
+    vp.dispatchEvent(new MouseEvent('mouseenter'));
+    expect(svc.isPaused()).toBe(true);
+    vp.dispatchEvent(new MouseEvent('mouseleave'));
+    expect(svc.isPaused()).toBe(false);
+    svc.dismissAll();
+  });
+});

package/src/toast/toast.strategy.ts

@@ -21,6 +21,14 @@ export interface KjToastStrategy {
   duration: number;
   /** When `true`, the viewport flips `data-expanded` on `mouseenter` / `mouseleave`. */
   expandOnHover: boolean;
+  /**
+   * When `true`, the viewport pauses every in-flight auto-dismiss timer while
+   * the pointer hovers it or focus is inside it. Required for WCAG 2.2.1 (AAA)
+   * and 1.4.13 — without it, a user reaching for the toast's action button
+   * may have it disappear underneath them. Distinct from `expandOnHover`,
+   * which controls visual stacking only.
+   */
+  pauseOnHover: boolean;
 }
 
 /**
@@ -36,6 +44,7 @@ export const KJ_TOAST_SONNER_STRATEGY: KjToastStrategy = Object.freeze({
   positionY: 'bottom',
   duration: 4000,
   expandOnHover: true,
+  pauseOnHover: true,
 });
 
 /**
@@ -50,6 +59,7 @@ export const KJ_TOAST_LIST_STRATEGY: KjToastStrategy = Object.freeze({
   positionY: 'bottom',
   duration: 5000,
   expandOnHover: false,
+  pauseOnHover: true,
 });
 
 /** DI token holding the active toast strategy. Defaults to `KJ_TOAST_SONNER_STRATEGY`. */