@blotch/dolan 22.2.3 → 22.2.4

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

@@ -1,97 +1,121 @@
-import { Component } from '@angular/core';
-import { render, waitForUpdate } from '@blotch/angular-lynx-testing-library';
+import { Component, signal } from '@angular/core';
+import {
+  fireEvent,
+  render,
+  waitForUpdate,
+} from '@blotch/angular-lynx-testing-library';
 import { LYNX_ELEMENTS } from '@blotch/angular-lynx';
 import { describe, expect, it, vi } from 'vitest';
-import { setInputSignal } from '../../../test-utils/set-input-signal';
+import { lynxMainThread } from '../../../test-utils/lynx-main-thread';
 import { UiList } from './list';
 
 @Component({
   imports: [UiList, LYNX_ELEMENTS],
-  template: `<ui-list><text>Item</text></ui-list>`,
+  template: `
+    <ui-list
+      [height]="height()"
+      [mainAxisGap]="mainAxisGap()"
+      [crossAxisGap]="crossAxisGap()"
+      [bounces]="bounces()"
+      [scrollBar]="scrollBar()"
+      [nestedScroll]="nestedScroll()"
+      [sticky]="sticky()"
+      class="bg-card"
+      (scrolledToStart)="reached.push('start')"
+      (scrolledToEnd)="reached.push('end')"
+    >
+      <text>Item</text>
+    </ui-list>
+  `,
 })
-class ListHost {}
+class ListHost {
+  readonly height = signal('');
+  readonly mainAxisGap = signal('');
+  readonly crossAxisGap = signal('');
+  readonly bounces = signal(true);
+  readonly scrollBar = signal(true);
+  readonly nestedScroll = signal(false);
+  readonly sticky = signal(false);
+  readonly reached: string[] = [];
+}
+
+const renderList = async () => {
+  const result = await render(ListHost);
+  return {
+    ...result,
+    host: result.componentRef.instance as ListHost,
+    list: () => result.container.querySelector('list')!,
+  };
+};
 
 /**
  * The values each boolean reached Lynx with, through `__SetAttribute`.
  */
 const watchAttributes = () => {
-  const mainThread = (
-    globalThis as unknown as {
-      lynxTestingEnv: { mainThread: { globalThis: Record<string, unknown> } };
-    }
-  ).lynxTestingEnv.mainThread.globalThis;
-  const setAttribute = vi.spyOn(mainThread, '__SetAttribute' as never);
+  const setAttribute = vi.spyOn(lynxMainThread(), '__SetAttribute');
   return {
     last: (name: string): unknown =>
-      (setAttribute.mock.calls as unknown[][])
-        .filter((call) => call[1] === name)
-        .at(-1)?.[2],
+      setAttribute.mock.calls.filter((call) => call[1] === name).at(-1)?.[2],
     restore: () => setAttribute.mockRestore(),
   };
 };
 
 describe('UiList', () => {
-  it('renders projected content', async () => {
-    // Lynx `<list>` is virtualized — items are only added to the native tree by
-    // the componentAtIndex callback, which isn't driven from a unit test. Just
-    // assert the wrapper mounts (its own template bindings + host bindings are
-    // covered) without asserting on the item's text.
-    const { container } = await render(ListHost);
-    expect(container).toBeTruthy();
+  it('renders a single-column vertical list with the given class', async () => {
+    // Lynx `<list>` is virtualized: items join the native tree only through
+    // its componentAtIndex callback, which a unit test doesn't drive. So this
+    // checks the list itself rather than the projected item.
+    const { list } = await renderList();
+    expect(list().getAttribute('list-type')).toBe('single');
+    expect(list().getAttribute('span-count')).toBe('1');
+    expect(list().getAttribute('scroll-orientation')).toBe('vertical');
+    expect(list().classList).toContain('w-full');
+    expect(list().classList).toContain('bg-card');
   });
 
-  it('emits an explicit height style when the height input is set', async () => {
-    // JIT template bindings don't propagate through input(); flip the signal
-    // directly so listStyle exercises its truthy branch.
-    const { container, componentRef } = await render(UiList);
-    setInputSignal((componentRef.instance as UiList).height, '400px');
-    await waitForUpdate();
+  it('gives the list an explicit height, which it needs to scroll', async () => {
+    const { host, list } = await renderList();
+    expect(list().getAttribute('style') ?? '').not.toContain('height');
 
-    const list = container.querySelector('list');
-    expect(list?.getAttribute('style')).toContain('height: 400px');
+    host.height.set('400px');
+    await waitForUpdate();
+    expect(list().getAttribute('style')).toContain('height: 400px');
   });
 
   it('sets the gaps as list styles, which Lynx reads, not attributes', async () => {
     // jsdom drops style properties it doesn't know, so the gaps never show in
     // the style attribute: watch what reaches Lynx's inline style API instead.
-    const mainThread = (
-      globalThis as unknown as {
-        lynxTestingEnv: { mainThread: { globalThis: Record<string, unknown> } };
-      }
-    ).lynxTestingEnv.mainThread.globalThis;
-    const addInlineStyle = vi.spyOn(mainThread, '__AddInlineStyle' as never);
-    const { container, componentRef } = await render(UiList);
-    const list = componentRef.instance as UiList;
-    setInputSignal(list.mainAxisGap, '8px');
-    setInputSignal(list.crossAxisGap, '12px');
+    const addInlineStyle = vi.spyOn(lynxMainThread(), '__AddInlineStyle');
+    const { host, list } = await renderList();
+    host.mainAxisGap.set('8px');
+    host.crossAxisGap.set('12px');
     await waitForUpdate();
 
-    const element = container.querySelector('list');
     expect(addInlineStyle).toHaveBeenCalledWith(
-      element,
+      list(),
       'list-main-axis-gap',
       '8px',
     );
     expect(addInlineStyle).toHaveBeenCalledWith(
-      element,
+      list(),
       'list-cross-axis-gap',
       '12px',
     );
-    expect(element?.getAttribute('list-main-axis-gap')).toBeNull();
+    expect(list().getAttribute('list-main-axis-gap')).toBeNull();
     addInlineStyle.mockRestore();
   });
 
   it('hands Lynx real booleans, so the defaults that are on can be turned off', async () => {
     // A false used to remove the attribute, which leaves Lynx's default: on.
     const attributes = watchAttributes();
-    const { componentRef } = await render(UiList);
-    const inst = componentRef.instance as UiList;
+    const { host } = await renderList();
     expect(attributes.last('bounces')).toBe(true);
     expect(attributes.last('scroll-bar-enable')).toBe(true);
-    setInputSignal(inst.bounces, false);
-    setInputSignal(inst.scrollBar, false);
-    setInputSignal(inst.nestedScroll, true);
-    setInputSignal(inst.sticky, true);
+
+    host.bounces.set(false);
+    host.scrollBar.set(false);
+    host.nestedScroll.set(true);
+    host.sticky.set(true);
     await waitForUpdate();
     expect(attributes.last('bounces')).toBe(false);
     expect(attributes.last('scroll-bar-enable')).toBe(false);
@@ -99,4 +123,11 @@ describe('UiList', () => {
     expect(attributes.last('sticky')).toBe(true);
     attributes.restore();
   });
+
+  it('emits when scrolled to the start or the end', async () => {
+    const { host, list } = await renderList();
+    fireEvent.scrolltolower(list());
+    fireEvent.scrolltoupper(list());
+    expect(host.reached).toEqual(['end', 'start']);
+  });
 });

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

@@ -0,0 +1,25 @@
+export {
+  UI_MENU,
+  UiMenu,
+  UiMenuItem,
+  UiMenuSection,
+  UiMenuSeparator,
+  UiMenuTrigger,
+  type UiMenuHost,
+} from './menu';
+export {
+  UiMenuPopup,
+  measureMenuElement,
+  type MenuElement,
+  type MenuKind,
+  type MenuPhase,
+} from './menu-popup';
+export {
+  menuStartFrame,
+  placeMenu,
+  type MenuPlacement,
+  type MenuPlacementMode,
+  type MenuPlacementOptions,
+  type MenuRect,
+  type MenuSize,
+} from './menu-placement';

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

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest';
+import {
+  type MenuPlacementOptions,
+  type MenuRect,
+  menuStartFrame,
+  placeMenu,
+} from './menu-placement';
+
+/** A phone's screen inside its safe area, in points. */
+const AREA = { width: 402, height: 778 };
+const MENU = { width: 250, height: 200 };
+
+const rect = (
+  left: number,
+  top: number,
+  width: number,
+  height: number,
+): MenuRect => ({ left, top, width, height });
+
+const place = (options: Partial<MenuPlacementOptions> & { anchor: MenuRect }) =>
+  placeMenu({ area: AREA, menu: MENU, mode: 'beside', ...options });
+
+describe('placeMenu', () => {
+  it('opens below an anchor with room below, lined up with its left edge', () => {
+    const placement = place({ anchor: rect(16, 100, 370, 96) });
+
+    expect(placement).toEqual({
+      frame: rect(16, 204, 250, 200),
+      anchor: rect(16, 100, 370, 96),
+      vertical: 'top',
+      horizontal: 'left',
+    });
+  });
+
+  it('lines up with the right edge of an anchor in the right half', () => {
+    const placement = place({ anchor: rect(340, 10, 44, 44) });
+
+    expect(placement.horizontal).toBe('right');
+    expect(placement.frame.left).toBe(384 - 250);
+  });
+
+  it('keeps the menu inside the area horizontally', () => {
+    expect(place({ anchor: rect(380, 10, 60, 44) }).frame.left).toBe(
+      402 - 8 - 250,
+    );
+    expect(place({ anchor: rect(-40, 10, 44, 44) }).frame.left).toBe(8);
+  });
+
+  it('opens above an anchor near the bottom', () => {
+    const placement = place({ anchor: rect(16, 700, 100, 44) });
+
+    expect(placement.vertical).toBe('bottom');
+    expect(placement.frame.top).toBe(700 - 8 - 200);
+  });
+
+  it('moves a lifted anchor up when the menu fits on neither side', () => {
+    const anchor = rect(16, 150, 370, 450);
+    const placement = place({ anchor, movableAnchor: true });
+
+    // The anchor moves up until the menu fits below it, inside the margin.
+    const anchorTop = 778 - 8 - 200 - 8 - 450;
+    expect(placement.anchor).toEqual({ ...anchor, top: anchorTop });
+    expect(placement.frame.top).toBe(anchorTop + 450 + 8);
+    expect(placement.vertical).toBe('top');
+  });
+
+  it('covers an anchor it can neither open beside nor move', () => {
+    const anchor = rect(16, 100, 370, 600);
+
+    // Too tall to move out of the way, or not movable: the menu sits at the
+    // bottom of the area, over the anchor.
+    for (const movableAnchor of [true, false]) {
+      const placement = place({ anchor, movableAnchor });
+      expect(placement.anchor).toEqual(anchor);
+      expect(placement.frame.top).toBe(778 - 8 - 200);
+    }
+  });
+
+  it('shrinks a menu taller or wider than the area to fit', () => {
+    const placement = place({
+      anchor: rect(16, 100, 44, 44),
+      menu: { width: 500, height: 1000 },
+    });
+
+    expect(placement.frame).toEqual(rect(8, 8, 402 - 16, 778 - 16));
+  });
+
+  it('grows a pull-down menu over its anchor, from its top edge', () => {
+    const placement = place({ anchor: rect(16, 100, 80, 44), mode: 'grow' });
+
+    expect(placement.frame).toEqual(rect(16, 100, 250, 200));
+    expect(placement.vertical).toBe('top');
+  });
+
+  it('grows a pull-down menu from the bottom edge of an anchor near the bottom', () => {
+    const placement = place({ anchor: rect(16, 720, 80, 44), mode: 'grow' });
+
+    expect(placement.frame.top).toBe(764 - 200);
+    expect(placement.vertical).toBe('bottom');
+  });
+
+  it('takes its own gap and margin', () => {
+    const placement = place({
+      anchor: rect(0, 100, 80, 40),
+      gap: 0,
+      margin: 0,
+    });
+
+    expect(placement.frame).toEqual(rect(0, 140, 250, 200));
+  });
+});
+
+describe('menuStartFrame', () => {
+  const below = placeMenu({
+    anchor: rect(16, 100, 80, 44),
+    area: AREA,
+    menu: MENU,
+    mode: 'beside',
+  });
+  const aboveRight = placeMenu({
+    anchor: rect(300, 700, 80, 44),
+    area: AREA,
+    menu: MENU,
+    mode: 'beside',
+  });
+
+  it('starts a pull-down menu as its anchor', () => {
+    expect(menuStartFrame(below, 'anchor')).toEqual(below.anchor);
+  });
+
+  it('starts a context menu small, in the corner nearest its anchor', () => {
+    expect(menuStartFrame(below, 'corner')).toEqual(
+      rect(16, 152, 250 * 0.3, 200 * 0.3),
+    );
+    const { frame } = aboveRight;
+    expect(menuStartFrame(aboveRight, 'corner')).toEqual(
+      rect(
+        frame.left + frame.width - 250 * 0.3,
+        frame.top + frame.height - 200 * 0.3,
+        250 * 0.3,
+        200 * 0.3,
+      ),
+    );
+  });
+
+  it('starts a Material menu as a sliver along the edge nearest its anchor', () => {
+    expect(menuStartFrame(below, 'edge')).toEqual(rect(16, 152, 250, 0));
+    const { frame } = aboveRight;
+    expect(menuStartFrame(aboveRight, 'edge')).toEqual(
+      rect(frame.left, frame.top + frame.height, 250, 0),
+    );
+  });
+});

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

@@ -0,0 +1,159 @@
+/** A box on screen, in px. */
+export type MenuRect = {
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+  readonly height: number;
+};
+
+/** A size, in px. */
+export type MenuSize = { readonly width: number; readonly height: number };
+
+/**
+ * How a menu sits against the element that opened it.
+ *
+ * - `'grow'`: over it, from its top edge (or its bottom edge, near the bottom
+ *   of the screen), as Apple's pull-down menus grow out of their button.
+ * - `'beside'`: below it, or above it near the bottom of the screen, a gap
+ *   away. Context menus open beside the pressed element, and Material menus
+ *   beside their anchor.
+ */
+export type MenuPlacementMode = 'grow' | 'beside';
+
+export type MenuPlacementOptions = {
+  /** The element that opened the menu, in the area's coordinates. */
+  readonly anchor: MenuRect;
+  /** The area the menu has to stay in: the screen inside its safe area. */
+  readonly area: MenuSize;
+  /** The menu's size at rest. */
+  readonly menu: MenuSize;
+  readonly mode: MenuPlacementMode;
+  /**
+   * Whether the anchor may move to make room, as the lifted element of a
+   * context menu does when the menu fits neither below nor above it.
+   */
+  readonly movableAnchor?: boolean;
+  /** The space between the menu and a `'beside'` anchor. */
+  readonly gap?: number;
+  /** The space the menu keeps from the area's edges. */
+  readonly margin?: number;
+};
+
+export type MenuPlacement = {
+  /** The menu's box at rest. */
+  readonly frame: MenuRect;
+  /**
+   * Where the anchor sits while the menu is open: where it was, unless
+   * `movableAnchor` let it move to make room.
+   */
+  readonly anchor: MenuRect;
+  /**
+   * The menu edge nearest the anchor, which the menu grows from and its
+   * content is pinned to: it hangs from its `'top'` below or over the anchor,
+   * and stands on its `'bottom'` above it.
+   */
+  readonly vertical: 'top' | 'bottom';
+  /**
+   * The anchor edge the menu lines up with: its `'right'` edge for an anchor
+   * entirely in the right half of the area, such as a button in a corner,
+   * so the menu opens toward the middle of the screen, and its `'left'` edge
+   * otherwise, which includes a row as wide as the screen.
+   */
+  readonly horizontal: 'left' | 'right';
+};
+
+const clamp = (value: number, min: number, max: number): number =>
+  Math.min(Math.max(value, min), Math.max(min, max));
+
+/**
+ * Where a menu goes on screen, beside or over the element that opened it,
+ * kept inside the area (the screen within its safe area): below the element,
+ * or above it when there's no room below, lined up with whichever of its
+ * edges is nearer the middle of the screen.
+ */
+export const placeMenu = ({
+  anchor,
+  area,
+  menu,
+  mode,
+  movableAnchor = false,
+  gap = 8,
+  margin = 8,
+}: MenuPlacementOptions): MenuPlacement => {
+  const width = clamp(menu.width, 0, area.width - 2 * margin);
+  const height = clamp(menu.height, 0, area.height - 2 * margin);
+  const horizontal = anchor.left < area.width / 2 ? 'left' : 'right';
+  const left = clamp(
+    horizontal === 'left' ? anchor.left : anchor.left + anchor.width - width,
+    margin,
+    area.width - margin - width,
+  );
+  const bottomLimit = area.height - margin;
+  const anchorBottom = anchor.top + anchor.height;
+
+  const place = (
+    top: number,
+    vertical: 'top' | 'bottom',
+    anchorTop = anchor.top,
+  ): MenuPlacement => ({
+    frame: {
+      left,
+      top: clamp(top, margin, bottomLimit - height),
+      width,
+      height,
+    },
+    anchor: { ...anchor, top: anchorTop },
+    vertical,
+    horizontal,
+  });
+
+  if (mode === 'grow') {
+    // Over the anchor, from its top edge, or else from its bottom edge.
+    return anchor.top + height <= bottomLimit
+      ? place(anchor.top, 'top')
+      : place(anchorBottom - height, 'bottom');
+  }
+
+  if (anchorBottom + gap + height <= bottomLimit) {
+    return place(anchorBottom + gap, 'top');
+  }
+  if (anchor.top - gap - height >= margin) {
+    return place(anchor.top - gap - height, 'bottom');
+  }
+  // Room on neither side. A lifted element moves up until the menu fits
+  // below it, as iOS moves a context menu's preview; if even that can't
+  // make room, or the anchor can't move, the menu covers the anchor.
+  const anchorTop = bottomLimit - height - gap - anchor.height;
+  if (movableAnchor && anchorTop >= margin) {
+    return place(anchorTop + anchor.height + gap, 'top', anchorTop);
+  }
+  return place(bottomLimit - height, 'top');
+};
+
+/**
+ * Where a menu starts growing from, and shrinks back to, as it opens and
+ * closes.
+ *
+ * - From the anchor itself for a `'grow'` menu: one shape whose frame grows,
+ *   which Liquid Glass follows frame by frame (its glass can't morph one
+ *   shape into another).
+ * - From a small box in the corner nearest the anchor for a context menu.
+ * - From a sliver along the edge nearest the anchor for Material, whose
+ *   menus unfold from their anchor.
+ */
+export const menuStartFrame = (
+  placement: MenuPlacement,
+  from: 'anchor' | 'corner' | 'edge',
+): MenuRect => {
+  const { frame, anchor, vertical, horizontal } = placement;
+  if (from === 'anchor') return anchor;
+  const scale = from === 'corner' ? 0.3 : 1;
+  const width = frame.width * scale;
+  const height = from === 'corner' ? frame.height * scale : 0;
+  return {
+    left: horizontal === 'left' ? frame.left : frame.left + frame.width - width,
+    top: vertical === 'top' ? frame.top : frame.top + frame.height - height,
+    width,
+    height,
+  };
+};