@blotch/dolan 22.2.2 → 22.2.4

package/dist/ui/components/dialog/dialog.test.ts

@@ -1,8 +1,24 @@
-import { Component, signal } from '@angular/core';
-import { render, waitForUpdate } from '@blotch/angular-lynx-testing-library';
+import { Component, signal, viewChild } from '@angular/core';
+import {
+  fireEvent,
+  render,
+  waitForUpdate,
+} from '@blotch/angular-lynx-testing-library';
 import { LYNX_ELEMENTS } from '@blotch/angular-lynx';
-import { describe, expect, it } from 'vitest';
-import { setInputSignal } from '../../../test-utils/set-input-signal';
+import {
+  type MockInstance,
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest';
+import { DURATION } from '../../utils/animate';
+import {
+  type LynxMainThread,
+  lynxMainThread,
+} from '../../../test-utils/lynx-main-thread';
 import {
   UiDialog,
   UiDialogDescription,
@@ -12,7 +28,6 @@ import {
 } from './dialog';
 
 @Component({
-  standalone: true,
   imports: [
     UiDialog,
     UiDialogHeader,
@@ -22,136 +37,226 @@ import {
     LYNX_ELEMENTS,
   ],
   template: `
-    <ui-dialog [(open)]="open">
-      <ui-dialog-header>
-        <ui-dialog-title>Title</ui-dialog-title>
-        <ui-dialog-description>Description</ui-dialog-description>
-      </ui-dialog-header>
-      <ui-dialog-footer><text>Actions</text></ui-dialog-footer>
-    </ui-dialog>
+    @if (shown()) {
+      <ui-dialog
+        [(open)]="open"
+        class="max-w-sm"
+        (closed)="closes.set(closes() + 1)"
+      >
+        <ui-dialog-header class="gap-2">
+          <ui-dialog-title class="text-xl">Title</ui-dialog-title>
+          <ui-dialog-description class="italic">
+            Description
+          </ui-dialog-description>
+        </ui-dialog-header>
+        <ui-dialog-footer class="justify-start">
+          <text>Actions</text>
+        </ui-dialog-footer>
+      </ui-dialog>
+    }
   `,
 })
 class DialogHost {
-  open = true;
+  readonly open = signal(false);
+  // Takes the dialog out of the tree, as an `@if` or a route change would.
+  readonly shown = signal(true);
+  readonly closes = signal(0);
+  readonly dialog = viewChild.required(UiDialog);
 }
 
+const renderDialog = async () => {
+  const result = await render(DialogHost);
+  const panel = () =>
+    result.container.querySelector('[accessibility-exclusive-focus]')!;
+  return {
+    ...result,
+    host: result.componentRef.instance as DialogHost,
+    overlay: () => result.container.querySelector('overlay')!,
+    panel,
+    backdrop: () => panel().parentElement!,
+  };
+};
+
+/**
+ * Waits for the dialog's open or close sequence, which runs on timers, then
+ * renders what it changed.
+ */
+const after = async (ms: number) => {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+  await waitForUpdate();
+};
+
+/**
+ * Long enough for the open sequence, including the panel's 30ms stagger. The
+ * sequence is chained timers, and on Windows each can fire up to a clock
+ * tick (about 16ms) late, so 50ms was too short on CI's Windows runner.
+ */
+const OPENED = 150;
+/** Long enough for the close animation and the hide after it, as above. */
+const CLOSED = DURATION.normal + 150;
+
+/** `__ElementAnimate`'s first argument for starting an animation. */
+const START = 0;
+/** `__ElementAnimate`'s first argument for canceling an animation. */
+const CANCEL = 3;
+
 describe('UiDialog', () => {
-  it('renders header, title, description, and footer', async () => {
-    const { getByText } = await render(DialogHost);
+  // Watched per test: the testing library resets the main thread after each.
+  let animate: MockInstance<LynxMainThread['__ElementAnimate']>;
+  beforeEach(() => {
+    animate = vi.spyOn(lynxMainThread(), '__ElementAnimate');
+  });
+  afterEach(() => animate.mockRestore());
+
+  it('renders each part with its projected content', async () => {
+    const { getByText } = await renderDialog();
     expect(getByText('Title')).toBeTruthy();
     expect(getByText('Description')).toBeTruthy();
     expect(getByText('Actions')).toBeTruthy();
   });
 
-  it('backdrop tap closes the dialog', async () => {
-    const { componentRef } = await render(UiDialog);
-    const inst = componentRef.instance as UiDialog;
-    inst.open.set(true);
-    await waitForUpdate();
-    (inst as unknown as { onBackdropTap: () => void }).onBackdropTap();
-    expect(inst.open()).toBe(false);
+  it("merges each part's class with its own, the given class winning", async () => {
+    const { container, getByText, panel } = await renderDialog();
+    expect(panel().classList).toContain('bg-background');
+    expect(panel().classList).toContain('max-w-sm');
+    expect(getByText('Title').classList).toContain('font-semibold');
+    expect(getByText('Title').classList).toContain('text-xl');
+    expect(getByText('Description').classList).toContain('text-sm');
+    expect(getByText('Description').classList).toContain('italic');
+    // Each part's own view, not its host element, which keeps the bare class.
+    const header = container.querySelector('.flex-col.gap-2');
+    expect(header?.classList).not.toContain('gap-1.5');
+    const footer = container.querySelector('.pt-4');
+    expect(footer?.classList).toContain('justify-start');
+    expect(footer?.classList).not.toContain('justify-end');
   });
 
-  it('panel tap is a no-op (catchtap stops bubbling)', async () => {
-    const { componentRef } = await render(UiDialog);
-    const inst = componentRef.instance as UiDialog;
-    expect(() =>
-      (inst as unknown as { onPanelTap: () => void }).onPanelTap(),
-    ).not.toThrow();
+  it('stays hidden until it is opened', async () => {
+    const { host, overlay, panel } = await renderDialog();
+    await after(CLOSED);
+    expect(overlay().getAttribute('style')).toContain('display: none');
+    expect(panel().getAttribute('accessibility-exclusive-focus')).toBe('false');
+    expect(animate).not.toHaveBeenCalled();
+    // Starting closed isn't closing: `closed` waits for a real close.
+    expect(host.closes()).toBe(0);
   });
 
-  it('open effect: showing then hiding runs the animate-in and animate-out lifecycles', async () => {
-    // Monkey-patch backdrop/panel refs so #animateIn / #animateOut execute in
-    // full instead of bailing on !backdrop || !panel.
-    const { componentRef, container } = await render(UiDialog);
-    const inst = componentRef.instance as UiDialog;
-    const view = container.querySelector('view') as Element;
-    (inst as unknown as { backdropRef: unknown }).backdropRef = signal({
-      nativeElement: view,
-    });
-    (inst as unknown as { panelRef: unknown }).panelRef = signal({
-      nativeElement: view,
-    });
-
-    inst.open.set(true);
-    await waitForUpdate();
-    // Wait for setTimeout chains to flush (nested setTimeouts inside #doOpen).
-    await waitForUpdate();
-    await waitForUpdate();
-
-    // Now close it — exercises #doClose + #animateOut. The nested setTimeout
-    // inside #doClose runs DURATION.normal (250ms) + 20ms later; wait real time.
-    inst.open.set(false);
-    await new Promise((r) => setTimeout(r, 320));
-    await waitForUpdate();
-    expect(inst.open()).toBe(false);
+  it('shows the overlay and animates the backdrop, then the panel, in', async () => {
+    const { host, overlay, backdrop, panel } = await renderDialog();
+    host.open.set(true);
+    await after(OPENED);
+    expect(overlay().getAttribute('style')).not.toContain('display: none');
+    expect(animate).toHaveBeenCalledWith(backdrop(), [
+      START,
+      expect.any(String),
+      [{ opacity: 0 }, { opacity: 1 }],
+      expect.objectContaining({ duration: DURATION.normal }),
+    ]);
+    expect(animate).toHaveBeenCalledWith(panel(), [
+      START,
+      expect.any(String),
+      [
+        { transform: 'scale(0.9) translateY(10px)', opacity: 0 },
+        { transform: 'scale(1) translateY(0px)', opacity: 1 },
+      ],
+      expect.objectContaining({ duration: DURATION.slow }),
+    ]);
   });
 
-  it('open effect bails when backdrop/panel refs are undefined', async () => {
-    // Covers the early-return branches in #animateIn / #animateOut.
-    const { componentRef } = await render(UiDialog);
-    const inst = componentRef.instance as UiDialog;
-    inst.open.set(true);
-    await waitForUpdate();
-    await waitForUpdate();
-    inst.open.set(false);
-    await waitForUpdate();
-    expect(inst.open()).toBe(false);
+  it('moves a screen reader into the panel and keeps it there while open', async () => {
+    const { host, panel } = await renderDialog();
+    const invoke = vi.spyOn(host.dialog().panelRef().nativeElement, 'invoke');
+    host.open.set(true);
+    await after(OPENED);
+    expect(invoke).toHaveBeenCalledWith('requestAccessibilityFocus');
+    expect(panel().getAttribute('accessibility-exclusive-focus')).toBe('true');
   });
 
-  it('overlayStyle switches between visible and hidden variants', async () => {
-    const { componentRef, container } = await render(UiDialog);
-    const inst = componentRef.instance as UiDialog;
-    // Default hidden — overlay carries display:none.
-    let overlay = container.querySelector('overlay');
-    expect(overlay?.getAttribute('style')).toContain('display: none');
-
-    // Open + advance so overlayVisible flips true.
-    const view = container.querySelector('view') as Element;
-    (inst as unknown as { backdropRef: unknown }).backdropRef = signal({
-      nativeElement: view,
-    });
-    (inst as unknown as { panelRef: unknown }).panelRef = signal({
-      nativeElement: view,
-    });
-    inst.open.set(true);
-    for (let i = 0; i < 10; i++) await waitForUpdate();
-    overlay = container.querySelector('overlay');
-    expect(overlay?.getAttribute('style')).not.toContain('display: none');
-  });
+  it('animates out, then hides and emits closed', async () => {
+    const { host, overlay, backdrop, panel } = await renderDialog();
+    host.open.set(true);
+    await after(OPENED);
+    animate.mockClear();
 
-  it('accepts a user class on the panel', async () => {
-    const { componentRef, container } = await render(UiDialog);
-    const inst = componentRef.instance as UiDialog;
-    setInputSignal(inst.userClass, 'custom-panel');
-    await waitForUpdate();
-    const panelCandidates = Array.from(container.querySelectorAll('view'));
-    expect(
-      panelCandidates.some((el) =>
-        el.getAttribute('class')?.includes('custom-panel'),
-      ),
-    ).toBe(true);
+    host.open.set(false);
+    await after(CLOSED);
+    expect(animate).toHaveBeenCalledWith(backdrop(), [
+      START,
+      expect.any(String),
+      [{ opacity: 1 }, { opacity: 0 }],
+      expect.any(Object),
+    ]);
+    expect(animate).toHaveBeenCalledWith(panel(), [
+      START,
+      expect.any(String),
+      [
+        { transform: 'scale(1) translateY(0px)', opacity: 1 },
+        { transform: 'scale(0.95) translateY(10px)', opacity: 0 },
+      ],
+      expect.any(Object),
+    ]);
+    expect(overlay().getAttribute('style')).toContain('display: none');
+    expect(panel().getAttribute('accessibility-exclusive-focus')).toBe('false');
+    expect(host.closes()).toBe(1);
   });
-});
 
-describe('Dialog sub-components', () => {
-  it('UiDialogHeader renders projected content', async () => {
-    const { container } = await render(UiDialogHeader);
-    expect(container.querySelector('view')).toBeTruthy();
+  it('cancels the previous animations when it opens again', async () => {
+    const { host, backdrop, panel } = await renderDialog();
+    host.open.set(true);
+    await after(OPENED);
+    host.open.set(false);
+    await after(CLOSED);
+    animate.mockClear();
+
+    host.open.set(true);
+    await after(OPENED);
+    // The close animations hold their last frame (fill: forwards) until
+    // they're canceled, which would hide the panel being opened.
+    expect(animate).toHaveBeenCalledWith(backdrop(), [
+      CANCEL,
+      expect.any(String),
+    ]);
+    expect(animate).toHaveBeenCalledWith(panel(), [CANCEL, expect.any(String)]);
   });
 
-  it('UiDialogTitle renders projected content', async () => {
-    const { container } = await render(UiDialogTitle);
-    expect(container.querySelector('text')).toBeTruthy();
+  it('closes when the backdrop is tapped', async () => {
+    const { host, backdrop } = await renderDialog();
+    host.open.set(true);
+    await after(OPENED);
+    fireEvent.tap(backdrop());
+    expect(host.open()).toBe(false);
+    await after(CLOSED);
+    expect(host.closes()).toBe(1);
   });
 
-  it('UiDialogDescription renders projected content', async () => {
-    const { container } = await render(UiDialogDescription);
-    expect(container.querySelector('text')).toBeTruthy();
+  it('stays open when the panel is tapped', async () => {
+    const { host, panel } = await renderDialog();
+    host.open.set(true);
+    await after(OPENED);
+    // The panel catches its taps, so they don't reach the backdrop.
+    fireEvent.tap(panel(), { eventType: 'catchEvent' });
+    await waitForUpdate();
+    expect(host.open()).toBe(true);
   });
 
-  it('UiDialogFooter renders projected content', async () => {
-    const { container } = await render(UiDialogFooter);
-    expect(container.querySelector('view')).toBeTruthy();
+  it('stops its close sequence when it is destroyed while closing', async () => {
+    const warn = vi.spyOn(console, 'warn');
+    const { host } = await renderDialog();
+    host.open.set(true);
+    await after(OPENED);
+    host.open.set(false);
+    await after(0);
+    // Destroyed during the close animation. Its close timer
+    // (DURATION.normal + 20) used to fire anyway and emit `closed` from the
+    // destroyed output, which Angular warns about in dev builds.
+    host.shown.set(false);
+    await waitForUpdate();
+    await after(CLOSED);
+    const warnings = warn.mock.calls.map(([message]) => String(message));
+    warn.mockRestore();
+    expect(warnings.filter((message) => message.includes('NG0953'))).toEqual(
+      [],
+    );
+    expect(host.closes()).toBe(0);
   });
 });

package/dist/ui/components/dialog/dialog.ts

@@ -1,5 +1,6 @@
 import {
   type ElementRef,
+  type OnDestroy,
   Component,
   ViewEncapsulation,
   computed,
@@ -26,20 +27,24 @@ import { cn } from '../../utils/cn';
 
 @Component({
   selector: 'ui-dialog',
-  standalone: true,
   imports: [LYNX_ELEMENTS],
   encapsulation: ViewEncapsulation.None,
   template: `
     <overlay [attr.visible]="overlayVisible()" [style]="overlayStyle()">
       <view #backdrop [class]="backdropClass()" (bindtap)="onBackdropTap()">
-        <view #panel [class]="panelClass()" (catchtap)="onPanelTap()">
+        <view
+          #panel
+          [class]="panelClass()"
+          [accessibility-exclusive-focus]="overlayVisible()"
+          (catchtap)="onPanelTap()"
+        >
           <ng-content />
         </view>
       </view>
     </overlay>
   `,
 })
-export class UiDialog {
+export class UiDialog implements OnDestroy {
   readonly open = model(false);
   readonly userClass = input<string>('', { alias: 'class' });
 
@@ -47,27 +52,38 @@ export class UiDialog {
 
   protected readonly overlayVisible = signal(false);
 
-  readonly backdropRef = viewChild<ElementRef>('backdrop');
-  readonly panelRef = viewChild<ElementRef>('panel');
+  // Required: both are always in the template (the overlay hides with
+  // display:none rather than leaving the tree), and the sequences only read
+  // them from timers that start after the first render.
+  readonly backdropRef = viewChild.required<ElementRef>('backdrop');
+  readonly panelRef = viewChild.required<ElementRef>('panel');
   #backdropAnim?: AnimationHandle;
   #panelAnim?: AnimationHandle;
   #hasBeenOpen = false;
+  // The open and close sequences' pending timers, so ngOnDestroy can stop
+  // them.
+  readonly #timers = new Set<ReturnType<typeof setTimeout>>();
 
-  constructor() {
-    // `#hasBeenOpen` prevents the close animation from running on the initial
-    // effect evaluation when `open` starts as false. Without this guard, the
-    // very first run would call #doClose() immediately, resulting in a no-op
-    // animation that still hides the overlay and emits `closed` unexpectedly.
-    effect(() => {
-      const isOpen = this.open();
-      if (isOpen) {
-        this.#hasBeenOpen = true;
-        this.#doOpen();
-      } else if (this.#hasBeenOpen) {
-        this.#doClose();
-      }
-    });
-  }
+  /**
+   * Plays the open or close sequence whenever `open` changes. A field rather
+   * than a constructor: Angular's test build keeps a function for a
+   * constructor that nothing calls, which an app's coverage report would show
+   * as uncovered.
+   *
+   * `#hasBeenOpen` prevents the close animation from running on the initial
+   * effect evaluation when `open` starts as false. Without this guard, the
+   * very first run would call #doClose() immediately, resulting in a no-op
+   * animation that still hides the overlay and emits `closed` unexpectedly.
+   */
+  protected readonly openAndClose = effect(() => {
+    const isOpen = this.open();
+    if (isOpen) {
+      this.#hasBeenOpen = true;
+      this.#doOpen();
+    } else if (this.#hasBeenOpen) {
+      this.#doClose();
+    }
+  });
 
   /**
    * Hide the overlay with `display:none` on web where `visible` attr has no
@@ -110,15 +126,37 @@ export class UiDialog {
    */
   protected onPanelTap(): void {}
 
+  /**
+   * The dialog can be destroyed while its open or close sequence is still
+   * running, for example by an `@if` around it or a route change right after
+   * closing it. The rest of the sequence then ran on the destroyed component:
+   * it animated detached elements and emitted `closed` from a destroyed
+   * output, which Angular warns about in dev builds (NG0953).
+   */
+  ngOnDestroy(): void {
+    for (const timer of this.#timers) clearTimeout(timer);
+  }
+
+  /**
+   * `setTimeout`, tracked so that ngOnDestroy can cancel it.
+   */
+  #later(callback: () => void, ms: number): void {
+    const timer = setTimeout(() => {
+      this.#timers.delete(timer);
+      callback();
+    }, ms);
+    this.#timers.add(timer);
+  }
+
   /**
    * Two-phase open: make overlay visible first (so native elements exist in
    * the tree), then animate on the next frame. See nav-drawer for the same
    * pattern — Lynx animate() requires elements to be mounted before use.
    */
   #doOpen(): void {
-    setTimeout(() => {
+    this.#later(() => {
       this.overlayVisible.set(true);
-      setTimeout(() => this.#animateIn(), 0);
+      this.#later(() => this.#animateIn(), 0);
     }, 0);
   }
 
@@ -127,9 +165,9 @@ export class UiDialog {
    * causing elements to disappear before the animation finishes.
    */
   #doClose(): void {
-    setTimeout(() => {
+    this.#later(() => {
       this.#animateOut();
-      setTimeout(() => {
+      this.#later(() => {
         this.overlayVisible.set(false);
         this.closed.emit();
       }, DURATION.normal + 20);
@@ -137,18 +175,22 @@ export class UiDialog {
   }
 
   #animateIn(): void {
-    const backdrop = this.backdropRef()?.nativeElement;
-    const panel = this.panelRef()?.nativeElement;
-    if (!backdrop || !panel) return;
+    const backdrop = this.backdropRef().nativeElement;
+    const panel = this.panelRef().nativeElement;
 
     this.#backdropAnim?.cancel();
     this.#panelAnim?.cancel();
 
     // Backdrop fades in first
     this.#backdropAnim = fadeIn(backdrop, { duration: DURATION.normal });
+    // Move a screen reader into the panel. It would otherwise stay on whatever
+    // opened it, which is now behind the overlay. With the panel's
+    // accessibility-exclusive-focus (see the template), it then can't leave
+    // the panel until it closes.
+    panel.invoke?.('requestAccessibilityFocus');
 
     // Panel scales in with gentle spring (staggered 30ms after backdrop)
-    setTimeout(() => {
+    this.#later(() => {
       this.#panelAnim = scaleIn(panel, {
         duration: DURATION.slow,
         easing: EASING.springSubtle,
@@ -159,9 +201,8 @@ export class UiDialog {
   }
 
   #animateOut(): void {
-    const backdrop = this.backdropRef()?.nativeElement;
-    const panel = this.panelRef()?.nativeElement;
-    if (!backdrop || !panel) return;
+    const backdrop = this.backdropRef().nativeElement;
+    const panel = this.panelRef().nativeElement;
 
     this.#backdropAnim?.cancel();
     this.#panelAnim?.cancel();
@@ -181,7 +222,6 @@ export class UiDialog {
 
 @Component({
   selector: 'ui-dialog-header',
-  standalone: true,
   imports: [LYNX_ELEMENTS],
   encapsulation: ViewEncapsulation.None,
   template: `
@@ -200,7 +240,6 @@ export class UiDialogHeader {
 
 @Component({
   selector: 'ui-dialog-title',
-  standalone: true,
   imports: [LYNX_ELEMENTS],
   encapsulation: ViewEncapsulation.None,
   template: `<text [class]="textClass()"><ng-content /></text>`,
@@ -215,7 +254,6 @@ export class UiDialogTitle {
 
 @Component({
   selector: 'ui-dialog-description',
-  standalone: true,
   imports: [LYNX_ELEMENTS],
   encapsulation: ViewEncapsulation.None,
   template: `<text [class]="textClass()"><ng-content /></text>`,
@@ -230,7 +268,6 @@ export class UiDialogDescription {
 
 @Component({
   selector: 'ui-dialog-footer',
-  standalone: true,
   imports: [LYNX_ELEMENTS],
   encapsulation: ViewEncapsulation.None,
   template: `