@blotch/dolan 22.2.2 → 22.2.4

package/dist/ui/components/nav-drawer/nav-drawer.ts

@@ -1,5 +1,6 @@
 import {
   type ElementRef,
+  type OnDestroy,
   Component,
   ViewEncapsulation,
   computed,
@@ -28,10 +29,10 @@ import {
 } from '../../utils/animate';
 import { cn } from '../../utils/cn';
 import { UiIcon } from '../icon';
+import { UI_ICON_COLOR } from '../icon/icon-theme';
 
 @Component({
   selector: 'ui-nav-drawer',
-  standalone: true,
   imports: [LYNX_ELEMENTS],
   encapsulation: ViewEncapsulation.None,
   template: `
@@ -39,10 +40,10 @@ import { UiIcon } from '../icon';
       <!-- bg-black/50 dims the content behind the drawer. The fadeIn/fadeOut in
            #animateIn/#animateOut already tween this element's opacity over
            DURATION.normal, so the dim animates in lockstep with the panel slide —
-           matching the dialog/action-sheet/bottom-sheet backdrop. A named color
-           with an opacity modifier is required here: bg-black/50 compiles to
-           rgb(0 0 0 / 0.5), which Lynx accepts, whereas opacity modifiers on
-           semantic tokens don't. -->
+           matching the dialog/action-sheet/bottom-sheet backdrop. It's a named
+           color, not a theme one, because the dim is black in light and dark
+           mode alike; bg-black/50 compiles to rgb(0 0 0 / 0.5), which Lynx
+           accepts. -->
       <view
         #backdrop
         class="h-full w-full bg-black/50"
@@ -52,6 +53,7 @@ import { UiIcon } from '../icon';
           #panel
           [class]="panelClass()"
           [style]="panelPositionStyle()"
+          [accessibility-exclusive-focus]="overlayVisible()"
           (catchtap)="onPanelTap()"
         >
           <ng-content />
@@ -60,7 +62,7 @@ import { UiIcon } from '../icon';
     </overlay>
   `,
 })
-export class UiNavDrawer {
+export class UiNavDrawer implements OnDestroy {
   readonly open = model(false);
   readonly side = input<'left' | 'right'>('left');
   readonly userClass = input<string>('', { alias: 'class' });
@@ -80,27 +82,38 @@ export class UiNavDrawer {
       : 'position: fixed; overflow: visible; width: 100vw; height: 100vh; top: 0; left: 0; z-index: 999; display: none;',
   );
 
-  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
-    // first run would call #doClose() and emit `closed` before the drawer
-    // has ever been opened.
-    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
+   * first run would call #doClose() and emit `closed` before the drawer
+   * has ever been opened.
+   */
+  protected readonly openAndClose = effect(() => {
+    const isOpen = this.open();
+    if (isOpen) {
+      this.#hasBeenOpen = true;
+      this.#doOpen();
+    } else if (this.#hasBeenOpen) {
+      this.#doClose();
+    }
+  });
 
   protected readonly panelClass = computed(() =>
     cn(
@@ -135,6 +148,28 @@ export class UiNavDrawer {
     this.open.set(false);
   }
 
+  /**
+   * The drawer 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: first make the overlay visible (so native elements exist),
    * then animate in on the next frame. Without the nested setTimeout, the
@@ -142,9 +177,9 @@ export class UiNavDrawer {
    * yet — Lynx element.animate() requires the element to be in the tree.
    */
   #doOpen(): void {
-    setTimeout(() => {
+    this.#later(() => {
       this.overlayVisible.set(true);
-      setTimeout(() => this.#animateIn(), 0);
+      this.#later(() => this.#animateIn(), 0);
     }, 0);
   }
 
@@ -155,9 +190,9 @@ export class UiNavDrawer {
    * cause a visual glitch (elements disappear before fade completes).
    */
   #doClose(): void {
-    setTimeout(() => {
+    this.#later(() => {
       this.#animateOut();
-      setTimeout(() => {
+      this.#later(() => {
         this.overlayVisible.set(false);
         this.closed.emit();
       }, DURATION.normal + 20);
@@ -165,9 +200,8 @@ export class UiNavDrawer {
   }
 
   #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();
@@ -178,12 +212,16 @@ export class UiNavDrawer {
       duration: DURATION.slow,
       easing: EASING.sheet,
     });
+    // 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');
   }
 
   #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();
@@ -199,7 +237,6 @@ export class UiNavDrawer {
 
 @Component({
   selector: 'ui-nav-drawer-header',
-  standalone: true,
   imports: [LYNX_ELEMENTS],
   encapsulation: ViewEncapsulation.None,
   template: `
@@ -227,9 +264,15 @@ export class UiNavDrawerHeader {
   );
 }
 
+/**
+ * `UiNavDrawerItem`, for `contentChildren()`. A call rather than the class
+ * itself: for a class, Angular's test build keeps an arrow function that
+ * nothing calls, which an app's coverage report would show as uncovered.
+ */
+const navDrawerItem = () => UiNavDrawerItem;
+
 @Component({
   selector: 'ui-nav-drawer-content',
-  standalone: true,
   imports: [LYNX_ELEMENTS],
   encapsulation: ViewEncapsulation.None,
   // Fixes: a long item list scrolled nowhere and spilled over the header and
@@ -284,27 +327,29 @@ export class UiNavDrawerContent {
   // Every nav item projected into this section (Home + each group item). Used to
   // find the active one when the drawer opens. `descendants: true` reaches items
   // nested inside the @for group wrappers, not just the direct content children.
-  readonly items = contentChildren(UiNavDrawerItem, { descendants: true });
+  readonly items = contentChildren(navDrawerItem(), { descendants: true });
 
   protected readonly contentClass = computed(() =>
     cn('h-full w-full', this.userClass()),
   );
 
-  constructor() {
-    // When the drawer opens, land the user on their current route instead of the
-    // top of a potentially long nav list. The <overlay> is display:none until
-    // open, so the scroll-view has no laid-out child frames until it's shown —
-    // defer a tick so the just-shown content is measured before we read it.
-    //
-    // This open-driven path is the fallback: it covers the web preview (where
-    // contentsizechanged isn't emitted) and re-opens that don't trigger a
-    // relayout. On device, onContentLayout() below is the precise trigger. Both
-    // call the same instant scroll, so firing twice is a harmless no-op.
-    effect(() => {
-      if (!this.#drawer.open()) return;
-      setTimeout(() => this.#scrollActiveIntoView(), 0);
-    });
-  }
+  /**
+   * When the drawer opens, land the user on their current route instead of the
+   * top of a potentially long nav list.
+   *
+   * The <overlay> is display:none until open, so the scroll-view has no
+   * laid-out child frames until it's shown — defer a tick so the just-shown
+   * content is measured before we read it.
+   *
+   * This open-driven path is the fallback: it covers the web preview (where
+   * contentsizechanged isn't emitted) and re-opens that don't trigger a
+   * relayout. On device, onContentLayout() below is the precise trigger. Both
+   * call the same instant scroll, so firing twice is a harmless no-op.
+   */
+  protected readonly revealActiveOnOpen = effect(() => {
+    if (!this.#drawer.open()) return;
+    setTimeout(() => this.#scrollActiveIntoView(), 0);
+  });
 
   /**
    * Fired by the scroll-view once its content finishes layout. Gated on the
@@ -317,18 +362,31 @@ export class UiNavDrawerContent {
 
   #scrollActiveIntoView(): void {
     this.items()
-      /* v8 ignore start -- .find predicate unreachable when no content-projected items */
       .find((item) => item.active())
-      /* v8 ignore stop */
       ?.scrollIntoView();
   }
 }
 
+/**
+ * The color icons inside an item draw with: the destructive color in a
+ * destructive item. A function of its own rather than written inline in
+ * `providers`: Angular's test build keeps a second copy of an inline factory
+ * that nothing calls, which an app's coverage report would show as uncovered.
+ */
+const itemIconColor = () => {
+  const item = inject(UiNavDrawerItem);
+  return computed(() =>
+    item.variant() === 'destructive' ? 'var(--destructive)' : undefined,
+  );
+};
+
 @Component({
   selector: 'ui-nav-drawer-item',
-  standalone: true,
   imports: [LYNX_ELEMENTS],
   encapsulation: ViewEncapsulation.None,
+  // Icons projected into the item (see the variant below) inject this through
+  // the item's element injector, which content projection keeps them under.
+  providers: [{ provide: UI_ICON_COLOR, useFactory: itemIconColor }],
   template: `
     <view
       #container
@@ -358,10 +416,18 @@ export class UiNavDrawerItem {
   readonly containerRef = viewChild<ElementRef>('container');
   #pressAnim?: AnimationHandle;
 
+  // `destructive` recolors the item's content, which the item doesn't render
+  // itself: the label and icon are projected. Lynx doesn't inherit `color`, so
+  // a text class here wouldn't reach the label. CSS variables do inherit, so
+  // the item points `--foreground` at `--destructive` for everything inside
+  // it: a label styled `text-foreground` (as items are) turns destructive.
+  // Icons draw with SVG, which can't read CSS, so they get the same color
+  // through UI_ICON_COLOR (see providers above).
   protected readonly containerClass = computed(() =>
     cn(
       'flex-row items-center gap-3 px-4 py-3 flex',
       this.active() ? 'bg-accent' : 'bg-transparent',
+      this.variant() === 'destructive' && '[--foreground:var(--destructive)]',
       this.userClass(),
     ),
   );
@@ -421,7 +487,6 @@ export class UiNavDrawerItem {
 
 @Component({
   selector: 'ui-nav-drawer-footer',
-  standalone: true,
   imports: [LYNX_ELEMENTS],
   encapsulation: ViewEncapsulation.None,
   template: `
@@ -449,13 +514,17 @@ export class UiNavDrawerFooter {
 
 @Component({
   selector: 'ui-nav-drawer-trigger',
-  standalone: true,
   imports: [LYNX_ELEMENTS, UiIcon],
   encapsulation: ViewEncapsulation.None,
   template: `
+    <!-- The trigger is only an icon, so it carries the words a screen reader
+         says for it. -->
     <view
       #container
       [class]="containerClass()"
+      [accessibility-element]="true"
+      accessibility-traits="button"
+      [accessibility-label]="label()"
       (bindtouchstart)="onPressStart()"
       (bindtouchend)="onPressEnd()"
       (bindtouchcancel)="onPressCancel()"
@@ -469,6 +538,8 @@ export class UiNavDrawerFooter {
   `,
 })
 export class UiNavDrawerTrigger {
+  /** What a screen reader says for the trigger. */
+  readonly label = input('Open navigation menu');
   readonly userClass = input<string>('', { alias: 'class' });
 
   readonly pressed = output<void>();

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

@@ -1,96 +1,208 @@
-import { render, waitForUpdate } from '@blotch/angular-lynx-testing-library';
+import { Component, signal } from '@angular/core';
+import {
+  fireEvent,
+  render,
+  waitForUpdate,
+  within,
+} from '@blotch/angular-lynx-testing-library';
 import { describe, expect, it } from 'vitest';
-import { setInputSignal } from '../../../test-utils/set-input-signal';
+import { ICON_LIGHT_COLORS } from '../icon/icon-theme';
 import { UiPagination } from './pagination';
 
-describe('UiPagination', () => {
-  const setup = async (totalPages: number, page = 1, siblingCount = 1) => {
-    const { componentRef, container } = await render(UiPagination);
-    const inst = componentRef.instance as UiPagination;
-    setInputSignal(inst.totalPages, totalPages);
-    setInputSignal(inst.siblingCount, siblingCount);
-    inst.page.set(page);
-    await waitForUpdate();
-    return { inst, container };
+@Component({
+  imports: [UiPagination],
+  template: `
+    <ui-pagination
+      [(page)]="page"
+      [totalPages]="totalPages()"
+      [siblingCount]="siblingCount()"
+      class="mt-4"
+    />
+  `,
+})
+class PaginationHost {
+  readonly page = signal(1);
+  readonly totalPages = signal(5);
+  readonly siblingCount = signal(1);
+}
+
+@Component({
+  imports: [UiPagination],
+  template: `
+    <ui-pagination
+      [totalPages]="2"
+      previousLabel="Back"
+      nextLabel="Forward"
+      [pageLabel]="resultsLabel"
+    />
+  `,
+})
+class LabeledPaginationHost {
+  readonly resultsLabel = (page: number, current: boolean): string =>
+    current ? `Results ${page}, showing` : `Results ${page}`;
+}
+
+/**
+ * Renders the row at a page of a total, with `siblingCount` pages on each
+ * side of the current one.
+ */
+const renderPagination = async (
+  totalPages: number,
+  page = 1,
+  siblingCount = 1,
+) => {
+  const result = await render(PaginationHost);
+  const host = result.componentRef.instance as PaginationHost;
+  host.totalPages.set(totalPages);
+  host.siblingCount.set(siblingCount);
+  host.page.set(page);
+  await waitForUpdate();
+  return {
+    ...result,
+    host,
+    /** The button a screen reader reads as `label`. */
+    button: (label: string) => result.getByRole('button', { name: label }),
   };
+};
+
+/**
+ * What the row shows between its arrows, in order: page numbers and gaps.
+ */
+const shown = (container: Element): (string | null)[] =>
+  Array.from(container.querySelectorAll('text')).map(
+    (el) => el.textContent?.trim() ?? null,
+  );
 
-  it('renders the pagination controls', async () => {
-    const { container } = await setup(5, 2);
-    expect(container).toBeTruthy();
+/**
+ * The screen reader labels of the row's buttons, in order. getAllByRole()
+ * finds only what a screen reader reaches as a button, so this also checks
+ * each one's traits and accessibility-element.
+ */
+const labels = (container: Element): (string | null)[] =>
+  within(container as HTMLElement)
+    .getAllByRole('button')
+    .map((button) => button.getAttribute('accessibility-label'));
+
+describe('UiPagination', () => {
+  it('lists every page when they all fit, with the given class', async () => {
+    // With one sibling, up to 5 + 1 * 2 = 7 pages fit without gaps.
+    const { container } = await renderPagination(7, 3);
+    expect(shown(container)).toEqual(['1', '2', '3', '4', '5', '6', '7']);
+    expect(container.querySelector('.gap-1')?.classList).toContain('mt-4');
   });
 
-  it('lists every page when total fits the un-truncated window', async () => {
-    // With siblings=1 the threshold is 5+2 = 7, so a total of 5 stays inline.
-    const { container } = await setup(5, 3);
-    // Each page should render its numeric label.
-    const text = container.textContent ?? '';
-    expect(text).toContain('1');
-    expect(text).toContain('5');
-    expect(text).not.toContain('...');
+  it('leaves a gap before the last page near the start', async () => {
+    const { container } = await renderPagination(10, 2);
+    expect(shown(container)).toEqual(['1', '2', '3', '...', '10']);
   });
 
-  it('inserts a trailing ellipsis when the window is near the start', async () => {
-    // total=10, page=2, siblings=1 → rangeStart=2, rangeEnd=3; gap on right only.
-    const { container } = await setup(10, 2);
-    expect(container.textContent ?? '').toContain('...');
+  it('leaves a gap after the first page near the end', async () => {
+    const { container } = await renderPagination(10, 9);
+    expect(shown(container)).toEqual(['1', '...', '8', '9', '10']);
   });
 
-  it('inserts a leading ellipsis when the window is near the end', async () => {
-    // total=10, page=9, siblings=1 → rangeStart=8, rangeEnd=9; gap on left only.
-    const { container } = await setup(10, 9);
-    expect(container.textContent ?? '').toContain('...');
+  it('leaves gaps on both sides in the middle', async () => {
+    const { container } = await renderPagination(10, 5);
+    expect(shown(container)).toEqual(['1', '...', '4', '5', '6', '...', '10']);
   });
 
-  it('inserts leading and trailing ellipses when the window sits in the middle', async () => {
-    // total=10, page=5, siblings=1 → rangeStart=4, rangeEnd=6; gaps on both sides.
-    const { container } = await setup(10, 5);
-    // Two ellipses in the DOM as separate <text> nodes.
-    expect(
-      container.textContent?.match(/\.\.\./g)?.length,
-    ).toBeGreaterThanOrEqual(1);
+  it('widens the window around the current page with more siblings', async () => {
+    const { container } = await renderPagination(12, 6, 2);
+    expect(shown(container)).toEqual([
+      '1',
+      '...',
+      '4',
+      '5',
+      '6',
+      '7',
+      '8',
+      '...',
+      '12',
+    ]);
   });
 
-  it('prev() decrements page when > 1', async () => {
-    const { inst } = await setup(5, 3);
-    (inst as unknown as { prev: () => void }).prev();
-    await waitForUpdate();
-    expect(inst.page()).toBe(2);
+  it('highlights the current page', async () => {
+    const { button } = await renderPagination(3, 2);
+    expect(button('Page 2, current page').classList).toContain('bg-primary');
+    expect(button('Page 1').classList).toContain('bg-transparent');
+    expect(button('Page 2, current page').textContent?.trim()).toBe('2');
   });
 
-  it('prev() is a no-op at page 1', async () => {
-    const { inst } = await setup(5, 1);
-    (inst as unknown as { prev: () => void }).prev();
+  it('goes to a tapped page', async () => {
+    const { host, button } = await renderPagination(5, 1);
+    fireEvent.tap(button('Page 4'));
     await waitForUpdate();
-    expect(inst.page()).toBe(1);
+    expect(host.page()).toBe(4);
+    expect(button('Page 4, current page').classList).toContain('bg-primary');
   });
 
-  it('next() increments page when < totalPages', async () => {
-    const { inst } = await setup(5, 3);
-    (inst as unknown as { next: () => void }).next();
+  it('steps back and forward with the arrows', async () => {
+    const { host, button } = await renderPagination(5, 3);
+    fireEvent.tap(button('Previous page'));
     await waitForUpdate();
-    expect(inst.page()).toBe(4);
-  });
+    expect(host.page()).toBe(2);
 
-  it('next() is a no-op at the last page', async () => {
-    const { inst } = await setup(5, 5);
-    (inst as unknown as { next: () => void }).next();
+    fireEvent.tap(button('Next page'));
+    fireEvent.tap(button('Next page'));
     await waitForUpdate();
-    expect(inst.page()).toBe(5);
+    expect(host.page()).toBe(4);
   });
 
-  it('goTo() jumps the page directly', async () => {
-    const { inst } = await setup(5, 1);
-    (inst as unknown as { goTo: (n: number) => void }).goTo(4);
+  it("dims the arrow that can't go further, and ignores its taps", async () => {
+    const first = await renderPagination(5, 1);
+    expect(first.button('Previous page').classList).toContain('opacity-50');
+    expect(first.button('Next page').classList).not.toContain('opacity-50');
+    fireEvent.tap(first.button('Previous page'));
     await waitForUpdate();
-    expect(inst.page()).toBe(4);
+    expect(first.host.page()).toBe(1);
+
+    const last = await renderPagination(5, 5);
+    expect(last.button('Next page').classList).toContain('opacity-50');
+    fireEvent.tap(last.button('Next page'));
+    await waitForUpdate();
+    expect(last.host.page()).toBe(5);
+  });
+
+  it('labels every button for screen readers', async () => {
+    const { container } = await renderPagination(3, 2);
+    expect(labels(container)).toEqual([
+      'Previous page',
+      'Page 1',
+      'Page 2, current page',
+      'Page 3',
+      'Next page',
+    ]);
+  });
+
+  it('takes its own labels', async () => {
+    const { container } = await render(LabeledPaginationHost);
+    expect(labels(container)).toEqual([
+      'Back',
+      'Results 1, showing',
+      'Results 2',
+      'Forward',
+    ]);
+  });
+
+  it('hides the gaps from screen readers', async () => {
+    const { container } = await renderPagination(10, 5);
+    const gaps = Array.from(container.querySelectorAll('text'))
+      .filter((el) => el.textContent === '...')
+      .map((el) =>
+        el.parentElement?.getAttribute('accessibility-elements-hidden'),
+      );
+    expect(gaps).toEqual(['true', 'true']);
   });
 
-  it('active page carries the primary variant class', async () => {
-    const { container } = await setup(3, 2);
-    // The active page's tile background is bg-primary; the others are transparent.
-    const primary = Array.from(container.querySelectorAll('view')).find((el) =>
-      el.getAttribute('class')?.includes('bg-primary'),
+  it("draws the arrows in the theme's foreground", async () => {
+    const { container } = await renderPagination(3, 2);
+    const arrows = Array.from(container.querySelectorAll('svg')).map((el) =>
+      el.getAttribute('content'),
     );
-    expect(primary).toBeTruthy();
+    expect(arrows).toHaveLength(2);
+    for (const arrow of arrows) {
+      expect(arrow).toContain(ICON_LIGHT_COLORS['foreground']);
+      expect(arrow).not.toContain('currentColor');
+    }
   });
 });