@blotch/dolan 22.2.3 → 22.2.4

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

@@ -1,8 +1,23 @@
 import { Component, signal } from '@angular/core';
-import { render, waitForUpdate } from '@blotch/angular-lynx-testing-library';
+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 {
+  type LynxMainThread,
+  lynxMainThread,
+} from '../../../test-utils/lynx-main-thread';
 import {
   UiCollapsible,
   UiCollapsibleContent,
@@ -10,103 +25,165 @@ import {
 } from './collapsible';
 
 @Component({
-  standalone: true,
-  imports: [UiCollapsible, LYNX_ELEMENTS],
-  template: `<ui-collapsible><text>Content</text></ui-collapsible>`,
+  imports: [
+    UiCollapsible,
+    UiCollapsibleTrigger,
+    UiCollapsibleContent,
+    LYNX_ELEMENTS,
+  ],
+  template: `
+    <ui-collapsible [(open)]="open" [disabled]="disabled()" class="gap-2">
+      <ui-collapsible-trigger class="px-2">
+        <text>Toggle</text>
+      </ui-collapsible-trigger>
+      <ui-collapsible-content class="pt-1">
+        <text>Details</text>
+      </ui-collapsible-content>
+    </ui-collapsible>
+  `,
 })
-class CollapsibleHost {}
+class CollapsibleHost {
+  readonly open = signal(false);
+  readonly disabled = signal(false);
+}
+
+const renderCollapsible = async () => {
+  const result = await render(CollapsibleHost);
+  return {
+    ...result,
+    host: result.componentRef.instance as CollapsibleHost,
+    // The trigger's own view holds the tap listener; the projected text is
+    // inside it.
+    trigger: () => result.getByText('Toggle').parentElement!,
+    // The content's own view wraps the projected text while it's open.
+    content: () => result.queryByText('Details')?.parentElement ?? null,
+  };
+};
+
+/** `__ElementAnimate`'s first argument for starting an animation. */
+const START = 0;
+/** `__ElementAnimate`'s first argument for canceling an animation. */
+const CANCEL = 3;
 
 describe('UiCollapsible', () => {
-  it('renders projected content', async () => {
-    const { getByText } = await render(CollapsibleHost);
-    expect(getByText('Content')).toBeTruthy();
-  });
+  it("merges each part's class with its own", async () => {
+    const { container, host, trigger, content } = await renderCollapsible();
+    // The host element carries the class too, so look for the view that has
+    // both its own and the given class.
+    expect(container.querySelector('.flex-col.gap-2')).not.toBeNull();
+    expect(trigger().classList).toContain('flex-row');
+    expect(trigger().classList).toContain('px-2');
 
-  it('toggle() flips the open state', async () => {
-    const { componentRef } = await render(UiCollapsible);
-    const inst = componentRef.instance as UiCollapsible;
-    expect(inst.open()).toBe(false);
-    inst.toggle();
-    expect(inst.open()).toBe(true);
-    inst.toggle();
-    expect(inst.open()).toBe(false);
+    host.open.set(true);
+    await waitForUpdate();
+    expect(content()!.classList).toContain('flex-col');
+    expect(content()!.classList).toContain('pt-1');
   });
 
-  it('toggle() is a no-op when disabled', async () => {
-    const { componentRef } = await render(UiCollapsible);
-    const inst = componentRef.instance as UiCollapsible;
-    setInputSignal(inst.disabled, true);
-    inst.toggle();
-    expect(inst.open()).toBe(false);
-  });
-});
+  it('opens and closes when the trigger is tapped', async () => {
+    const { host, trigger, content } = await renderCollapsible();
+    // Closed, the content isn't mounted at all.
+    expect(content()).toBeNull();
 
-describe('UiCollapsibleTrigger', () => {
-  it('onTap delegates to the parent collapsible.toggle()', async () => {
-    const parentResult = await render(UiCollapsible);
-    const parent = parentResult.componentRef.instance as UiCollapsible;
+    fireEvent.tap(trigger());
+    await waitForUpdate();
+    expect(content()).not.toBeNull();
+    expect(host.open()).toBe(true);
 
-    const triggerResult = await render(UiCollapsibleTrigger, {
-      providers: [{ provide: UiCollapsible, useValue: parent }],
-    });
-    const trigger = triggerResult.componentRef.instance as UiCollapsibleTrigger;
-    (trigger as unknown as { onTap: () => void }).onTap();
-    expect(parent.open()).toBe(true);
+    fireEvent.tap(trigger());
+    await waitForUpdate();
+    expect(content()).toBeNull();
+    expect(host.open()).toBe(false);
   });
 
-  it('applies disabled dim class when parent is disabled', async () => {
-    const parentResult = await render(UiCollapsible);
-    const parent = parentResult.componentRef.instance as UiCollapsible;
-    setInputSignal(parent.disabled, true);
-
-    const triggerResult = await render(UiCollapsibleTrigger, {
-      providers: [{ provide: UiCollapsible, useValue: parent }],
-    });
+  it('opens when its `open` is set', async () => {
+    const { host, content } = await renderCollapsible();
+    host.open.set(true);
     await waitForUpdate();
-    const view = triggerResult.container.querySelector('view');
-    expect(view?.getAttribute('class')).toContain('opacity-50');
+    expect(content()).not.toBeNull();
   });
-});
 
-describe('UiCollapsibleContent', () => {
-  it('runs the reveal animation on open via setTimeout', async () => {
-    const parentResult = await render(UiCollapsible);
-    const parent = parentResult.componentRef.instance as UiCollapsible;
+  it('dims its trigger and ignores taps while disabled', async () => {
+    const { host, trigger, content } = await renderCollapsible();
+    expect(trigger().classList).not.toContain('opacity-50');
 
-    const contentResult = await render(UiCollapsibleContent, {
-      providers: [{ provide: UiCollapsible, useValue: parent }],
-    });
-    const content = contentResult.componentRef.instance as UiCollapsibleContent;
-    // JIT + jsdom doesn't populate the `#content` viewChild — patch it with a
-    // signal returning the outer view so the setTimeout body's `el` check
-    // passes and revealIn actually runs.
-    const view = contentResult.container.querySelector('view') as Element;
-    (content as unknown as { contentRef: unknown }).contentRef = signal({
-      nativeElement: view,
-    });
-
-    parent.open.set(true);
+    host.disabled.set(true);
     await waitForUpdate();
-    await waitForUpdate(); // wait for the effect's setTimeout(_, 0) to fire
+    expect(trigger().classList).toContain('opacity-50');
 
-    // Toggle off then on again to hit the cancel path with `#anim` already set.
-    parent.open.set(false);
-    await waitForUpdate();
-    parent.open.set(true);
-    await waitForUpdate();
+    fireEvent.tap(trigger());
     await waitForUpdate();
-    expect(parent.open()).toBe(true);
+    expect(content()).toBeNull();
+    expect(host.open()).toBe(false);
   });
 
-  it('bails out inside setTimeout when contentRef is undefined', async () => {
-    const parentResult = await render(UiCollapsible);
-    const parent = parentResult.componentRef.instance as UiCollapsible;
-    await render(UiCollapsibleContent, {
-      providers: [{ provide: UiCollapsible, useValue: parent }],
+  describe('reveal animation', () => {
+    // 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());
+
+    /**
+     * The keys of the animations started on an element.
+     */
+    const startedOn = (element: Element | null) =>
+      animate.mock.calls
+        .filter(
+          ([target, [operation]]) => target === element && operation === START,
+        )
+        .map(([, [, key]]) => key);
+
+    it('slides the content down into place each time it opens', async () => {
+      const { trigger, content } = await renderCollapsible();
+
+      fireEvent.tap(trigger());
+      // The first update runs the effect, which waits a macrotask so the
+      // content is committed to Lynx's tree; the second lets that run.
+      await waitForUpdate();
+      await waitForUpdate();
+      expect(animate).toHaveBeenCalledWith(content(), [
+        START,
+        expect.any(String),
+        [
+          { transform: 'translateY(-8px)', opacity: 0 },
+          { transform: 'translateY(0)', opacity: 1 },
+        ],
+        // No fill: once it ends, the content's inline resting style applies.
+        expect.objectContaining({ fill: 'none' }),
+      ]);
+      const [firstKey] = startedOn(content());
+
+      fireEvent.tap(trigger());
+      await waitForUpdate();
+      fireEvent.tap(trigger());
+      await waitForUpdate();
+      await waitForUpdate();
+      // Reopening stops the previous reveal before it plays a new one on the
+      // content's new view.
+      expect(animate).toHaveBeenCalledWith(expect.anything(), [
+        CANCEL,
+        firstKey,
+      ]);
+      expect(startedOn(content())).toHaveLength(1);
+    });
+
+    it("doesn't animate content that closed before its reveal began", async () => {
+      const { componentRef, trigger, content } = await renderCollapsible();
+
+      fireEvent.tap(trigger());
+      // The effect has scheduled the reveal for the next macrotask.
+      await waitForUpdate();
+      // Close it before then, and render that straight away.
+      fireEvent.tap(trigger());
+      componentRef.changeDetectorRef.detectChanges();
+      expect(content()).toBeNull();
+
+      await waitForUpdate();
+      expect(
+        animate.mock.calls.filter(([, [operation]]) => operation === START),
+      ).toEqual([]);
     });
-    parent.open.set(true);
-    await waitForUpdate();
-    await waitForUpdate();
-    expect(parent.open()).toBe(true);
   });
 });

package/dist/ui/components/collapsible/collapsible.ts

@@ -101,20 +101,25 @@ export class UiCollapsibleContent {
   readonly contentRef = viewChild<ElementRef>('content');
   #anim?: AnimationHandle;
 
-  constructor() {
-    // Animate the reveal whenever the panel opens. contentRef only resolves while
-    // the `@if` content is mounted; defer one macrotask so the freshly (re)created
-    // element is committed to the native tree before we animate it.
-    effect(() => {
-      if (!this.collapsible.open()) return;
-      setTimeout(() => {
-        const el = this.contentRef()?.nativeElement;
-        if (!el) return;
-        this.#anim?.cancel();
-        this.#anim = revealIn(el, { fromY: -8, fill: 'none' });
-      }, 0);
-    });
-  }
+  /**
+   * Animates the reveal whenever the panel opens. 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.
+   *
+   * contentRef only resolves while the `@if` content is mounted; defer one
+   * macrotask so the freshly (re)created element is committed to the native
+   * tree before we animate it. By then the panel may have closed again, which
+   * leaves nothing to animate.
+   */
+  protected readonly revealing = effect(() => {
+    if (!this.collapsible.open()) return;
+    setTimeout(() => {
+      const el = this.contentRef()?.nativeElement;
+      if (!el) return;
+      this.#anim?.cancel();
+      this.#anim = revealIn(el, { fromY: -8, fill: 'none' });
+    }, 0);
+  });
 
   protected readonly contentClass = computed(() =>
     cn('flex-col flex', this.userClass()),

package/dist/ui/components/context-menu/context-menu.test.ts

@@ -0,0 +1,224 @@
+import { Component, signal } from '@angular/core';
+import {
+  fireEvent,
+  render,
+  waitForUpdate,
+  within,
+} from '@blotch/angular-lynx-testing-library';
+import { LYNX_ELEMENTS, LynxAccessibilitySettings } from '@blotch/angular-lynx';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { UiMenuItem, UiMenuSeparator } from '../menu/menu';
+import { UiContextMenu } from './context-menu';
+
+@Component({
+  imports: [LYNX_ELEMENTS, UiContextMenu, UiMenuItem, UiMenuSeparator],
+  template: `
+    <ui-context-menu
+      [open]="open()"
+      (openChange)="open.set($event)"
+      [disabled]="disabled()"
+      (closed)="closed()"
+    >
+      <view class="card" (bindtap)="opened()">
+        <text>Kyoto</text>
+      </view>
+      <ui-menu-item label="Share" icon="upload" (pressed)="shared()" />
+      <ui-menu-separator />
+      <ui-menu-item
+        label="Delete"
+        icon="trash"
+        variant="destructive"
+        (pressed)="deleted()"
+      />
+    </ui-context-menu>
+  `,
+})
+class ContextMenuHost {
+  readonly open = signal(false);
+  readonly disabled = signal(false);
+  readonly closed = vi.fn();
+  readonly opened = vi.fn();
+  readonly shared = vi.fn();
+  readonly deleted = vi.fn();
+}
+
+/**
+ * The Lynx function that runs an element's UI methods, such as measuring it
+ * (`boundingClientRect`). The testing library defines it on the global
+ * object.
+ */
+type InvokeUIMethod = {
+  __InvokeUIMethod: (
+    element: Element,
+    method: string,
+    params: Record<string, unknown>,
+    callback: (result: { code: number; data?: unknown }) => void,
+  ) => void;
+};
+
+/** Accessibility settings a test can change, as the host app would. */
+const settings = {
+  reduceMotion: signal(false),
+  reduceTransparency: signal(false),
+  increaseContrast: signal(false),
+};
+
+const IOS_26 = { platform: 'iOS', osVersion: '26.0' };
+
+/**
+ * Renders the context menu on a platform (none for Material), measuring
+ * elements as `boundingClientRect` would on a phone: the safe area (the
+ * element that holds the menu) a phone's screen, the menu's content 120pt
+ * tall, and anything else, the pressed element, a card near the top.
+ */
+const renderContextMenu = async (
+  platform: { platform: string; osVersion: string } | null = IOS_26,
+) => {
+  vi.stubGlobal('SystemInfo', platform ?? undefined);
+  vi.spyOn(
+    globalThis as unknown as InvokeUIMethod,
+    '__InvokeUIMethod',
+  ).mockImplementation((element, method, _params, callback) => {
+    if (method !== 'boundingClientRect') {
+      callback({ code: 0 });
+      return;
+    }
+    const data = element.querySelector(':scope > blur-view[ui-glass]')
+      ? { left: 0, top: 62, width: 402, height: 778 }
+      : element.parentElement?.tagName.toLowerCase() === 'scroll-view'
+        ? { left: 0, top: 0, width: 250, height: 120 }
+        : { left: 16, top: 162, width: 370, height: 96 };
+    callback({ code: 0, data });
+  });
+  const result = await render(ContextMenuHost, {
+    providers: [{ provide: LynxAccessibilitySettings, useValue: settings }],
+  });
+  const host = result.componentRef.instance as ContextMenuHost;
+  const overlay = result.container.querySelector('overlay')!;
+  return {
+    ...result,
+    host,
+    overlay,
+    menu: within(overlay as HTMLElement),
+    card: () => result.getByText('Kyoto').parentElement!,
+    /** The element the card is in: its home, or the overlay's slot. */
+    holder: () =>
+      result.getByText('Kyoto').parentElement!.parentElement!.parentElement!,
+    panel: () => overlay.querySelector('blur-view[ui-glass]')!,
+  };
+};
+
+type Rendered = Awaited<ReturnType<typeof renderContextMenu>>;
+
+/**
+ * Waits until the menu has opened.
+ */
+const waitForOpen = (rendered: Rendered) =>
+  vi.waitFor(() =>
+    expect(rendered.panel().getAttribute('accessibility-exclusive-focus')).toBe(
+      'true',
+    ),
+  );
+
+/**
+ * Waits until the menu has closed and its animation has finished.
+ */
+const waitForClose = async (rendered: Rendered) => {
+  await vi.waitFor(() => expect(rendered.host.closed).toHaveBeenCalled());
+  await waitForUpdate();
+};
+
+/**
+ * Long-presses an element. The press bubbles, as Lynx's touch events do, to
+ * the context menu around the element.
+ */
+const longPress = (element: Element) =>
+  fireEvent.longpress(element, { bubbles: true });
+
+const style = (element: Element, name: string) =>
+  (element as HTMLElement).style.getPropertyValue(name);
+
+// The renderer warns that the components' selectors aren't Lynx elements.
+beforeEach(() => {
+  vi.spyOn(console, 'warn').mockImplementation(() => {});
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe('UiContextMenu', () => {
+  it('opens on a long press, lifting the element above the dimmed screen', async () => {
+    const rendered = await renderContextMenu();
+    const home = rendered.holder();
+
+    longPress(rendered.card());
+    await waitForOpen(rendered);
+
+    expect(rendered.host.open()).toBe(true);
+    // The element itself is in the menu's overlay now, lifted, and the spot
+    // it left keeps its size.
+    expect(rendered.overlay.contains(rendered.card())).toBe(true);
+    expect(style(rendered.holder(), 'transform')).toBe('scale(1.03)');
+    expect(style(home, 'width')).toBe('370px');
+    expect(style(home, 'height')).toBe('96px');
+    expect(rendered.overlay.querySelector('.bg-glass-dim')).not.toBeNull();
+    // The menu opens below it.
+    expect(style(rendered.panel(), 'top')).toBe(`${100 + 96 + 8}px`);
+  });
+
+  it('runs the chosen item and closes, putting the element back', async () => {
+    const rendered = await renderContextMenu();
+    longPress(rendered.card());
+    await waitForOpen(rendered);
+
+    fireEvent.tap(
+      rendered.menu.getByRole('button', { name: 'Delete, destructive' }),
+    );
+
+    expect(rendered.host.deleted).toHaveBeenCalledTimes(1);
+    expect(rendered.host.open()).toBe(false);
+    await waitForClose(rendered);
+    expect(rendered.overlay.contains(rendered.card())).toBe(false);
+    expect(style(rendered.holder(), 'height')).toBe('');
+    // A tap on the element still reaches it.
+    fireEvent.tap(rendered.card());
+    expect(rendered.host.opened).toHaveBeenCalledTimes(1);
+  });
+
+  it('closes on a tap outside the menu', async () => {
+    const rendered = await renderContextMenu();
+    rendered.host.open.set(true);
+    await waitForOpen(rendered);
+
+    fireEvent.tap(rendered.overlay.firstElementChild!);
+
+    expect(rendered.host.open()).toBe(false);
+    await waitForClose(rendered);
+  });
+
+  it("doesn't open on a long press when disabled", async () => {
+    const rendered = await renderContextMenu();
+    rendered.host.disabled.set(true);
+    await waitForUpdate();
+
+    longPress(rendered.card());
+    await waitForUpdate();
+
+    expect(rendered.host.open()).toBe(false);
+  });
+
+  it('opens a Material menu beside the element on Android, leaving it in place', async () => {
+    const rendered = await renderContextMenu(null);
+    const home = rendered.holder();
+
+    longPress(rendered.card());
+    await waitForOpen(rendered);
+
+    expect(home.contains(rendered.card())).toBe(true);
+    expect(style(home, 'height')).toBe('');
+    expect(rendered.overlay.querySelector('.bg-glass-dim')).toBeNull();
+    expect(rendered.menu.getByRole('button', { name: 'Share' })).toBeTruthy();
+  });
+});

package/dist/ui/components/context-menu/context-menu.ts

@@ -0,0 +1,110 @@
+import {
+  Component,
+  type ElementRef,
+  ViewEncapsulation,
+  booleanAttribute,
+  inject,
+  input,
+  model,
+  output,
+  viewChild,
+} from '@angular/core';
+import { LYNX_ELEMENTS } from '@blotch/angular-lynx';
+
+import { type MenuElement, UiMenuPopup } from '../menu/menu-popup';
+import { UI_MENU, type UiMenuHost } from '../menu/menu';
+
+/**
+ * The `ui-context-menu` an item is in, for `UI_MENU`. A named function rather
+ * than an inline factory: the component's metadata keeps its own copy of an
+ * inline one, which nothing calls, so an app's coverage report would show it
+ * as uncovered.
+ */
+const contextMenu = (): UiMenuHost => inject(UiContextMenu);
+
+/**
+ * A context menu: a long press on an element lifts it and opens a menu of
+ * actions beside it, while the rest of the screen dims.
+ *
+ * ```html
+ * <ui-context-menu>
+ *   <view class="rounded-xl bg-card p-4">
+ *     <text class="text-foreground">Trip to Kyoto</text>
+ *   </view>
+ *   <ui-menu-item label="Share" icon="upload" (pressed)="share()" />
+ *   <ui-menu-item label="Favorite" icon="heart" (pressed)="favorite()" />
+ *   <ui-menu-separator />
+ *   <ui-menu-item label="Delete" icon="trash" variant="destructive" (pressed)="remove()" />
+ * </ui-context-menu>
+ * ```
+ *
+ * The items (`ui-menu-item`, `ui-menu-section`, `ui-menu-separator`) are the
+ * menu, and everything else is the element it opens from. Taps on the
+ * element still reach it: Lynx tells a tap from a long press. A tap outside
+ * the menu, choosing an item, or Android's back button closes it, and
+ * `[(open)]` opens and closes it from code.
+ *
+ * On iOS the element lifts above a dimming layer (a blur before iOS 26) and
+ * the menu, Liquid Glass from iOS 26, opens below it, or above it near the
+ * bottom of the screen; when it fits on neither side, the element moves up
+ * to make room. The element itself moves into the menu's overlay, so it
+ * stays live and looks exactly as it did. On Android it's a Material 3 menu
+ * beside the element, without the lift or the dimming, unless the app opts
+ * into glass with `provideGlass({ android: 'glass' })`.
+ *
+ * Apple asks for a context menu's first actions to match the swipe actions
+ * of the row it's on, when there are any, so the two ways to reach an
+ * action agree.
+ */
+@Component({
+  selector: 'ui-context-menu',
+  imports: [LYNX_ELEMENTS, UiMenuPopup],
+  encapsulation: ViewEncapsulation.None,
+  providers: [{ provide: UI_MENU, useFactory: contextMenu }],
+  template: `
+    <!-- Keeps the element's size while it's lifted into the overlay, so the
+         page doesn't move under the menu. -->
+    <view
+      #home
+      class="flex-col flex"
+      [style.width.px]="popup.placeholder()?.width"
+      [style.height.px]="popup.placeholder()?.height"
+    >
+      <view #element class="flex-col flex" (bindlongpress)="onLongPress()">
+        <ng-content />
+      </view>
+    </view>
+    <ui-menu-popup
+      #popup
+      kind="context"
+      [open]="open()"
+      [anchor]="elementView().nativeElement"
+      [anchorHome]="homeView().nativeElement"
+      (dismissed)="close()"
+      (closed)="closed.emit()"
+    >
+      <ng-content select="ui-menu-item, ui-menu-section, ui-menu-separator" />
+    </ui-menu-popup>
+  `,
+})
+export class UiContextMenu implements UiMenuHost {
+  /** Whether the menu is open. */
+  readonly open = model(false);
+  /** Turns the long press off. */
+  readonly disabled = input(false, { transform: booleanAttribute });
+
+  /** The menu has closed and its close animation has finished. */
+  readonly closed = output<void>();
+
+  // Required: both are always in the template.
+  readonly elementView = viewChild.required<ElementRef<MenuElement>>('element');
+  readonly homeView = viewChild.required<ElementRef<MenuElement>>('home');
+
+  protected onLongPress(): void {
+    if (!this.disabled()) this.open.set(true);
+  }
+
+  close(): void {
+    this.open.set(false);
+  }
+}

package/dist/ui/components/context-menu/index.ts

@@ -0,0 +1 @@
+export { UiContextMenu } from './context-menu';