@blotch/dolan 22.2.3 → 22.2.5

package/dist/ui/components/scroll-area/scroll-area.test.ts

@@ -1,75 +1,111 @@
-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 { UiScrollArea } from './scroll-area';
 
 @Component({
   imports: [UiScrollArea, LYNX_ELEMENTS],
-  template: `<ui-scroll-area><text>Body</text></ui-scroll-area>`,
+  template: `
+    <ui-scroll-area
+      [orientation]="orientation()"
+      [height]="height()"
+      [bounces]="bounces()"
+      [scrollBar]="scrollBar()"
+      [nestedScroll]="nestedScroll()"
+      class="bg-card"
+      contentClass="gap-2"
+      (scrolledToStart)="reached.push('start')"
+      (scrolledToEnd)="reached.push('end')"
+    >
+      <text>Body</text>
+    </ui-scroll-area>
+  `,
 })
-class ScrollAreaHost {}
+class ScrollAreaHost {
+  readonly orientation = signal<'vertical' | 'horizontal'>('vertical');
+  readonly height = signal('');
+  readonly bounces = signal(true);
+  readonly scrollBar = signal(true);
+  readonly nestedScroll = signal(false);
+  readonly reached: string[] = [];
+}
+
+const renderScrollArea = async () => {
+  const result = await render(ScrollAreaHost);
+  return {
+    ...result,
+    host: result.componentRef.instance as ScrollAreaHost,
+    scrollView: () => result.container.querySelector('scroll-view')!,
+    /** The view inside the scroll view that lays out the content. */
+    content: () => result.getByText('Body').parentElement!,
+  };
+};
 
 /**
  * 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('UiScrollArea', () => {
-  it('renders projected content in the scroll view', async () => {
-    const { getByText } = await render(ScrollAreaHost);
-    expect(getByText('Body')).toBeTruthy();
+  it('renders projected content in a vertical scroll view', async () => {
+    const { scrollView, content } = await renderScrollArea();
+    expect(scrollView().getAttribute('scroll-orientation')).toBe('vertical');
+    expect(scrollView().classList).toContain('bg-card');
+    expect(content().classList).toContain('flex-col');
+    expect(content().classList).toContain('gap-2');
   });
 
-  it('emits an explicit height when the height input is set', async () => {
-    const { componentRef, container } = await render(UiScrollArea);
-    setInputSignal((componentRef.instance as UiScrollArea).height, '250px');
+  it('gives the scroll view an explicit height, which it needs to scroll', async () => {
+    const { host, scrollView } = await renderScrollArea();
+    expect(scrollView().getAttribute('style') ?? '').not.toContain('height');
+
+    host.height.set('250px');
     await waitForUpdate();
-    const scroll = container.querySelector('scroll-view');
-    expect(scroll?.getAttribute('style')).toContain('height: 250px');
+    expect(scrollView().getAttribute('style')).toContain('height: 250px');
   });
 
-  it('flips the content layout for horizontal orientation', async () => {
-    const { componentRef, container } = await render(UiScrollArea);
-    setInputSignal(
-      (componentRef.instance as UiScrollArea).orientation,
-      'horizontal',
-    );
+  it('lays the content out in a row when horizontal', async () => {
+    const { host, scrollView, content } = await renderScrollArea();
+    host.orientation.set('horizontal');
     await waitForUpdate();
-    // The inner content wrapper picks up flex-row for the horizontal branch.
-    const rowEl = container.querySelector('.flex-row');
-    expect(rowEl).toBeTruthy();
+    expect(scrollView().getAttribute('scroll-orientation')).toBe('horizontal');
+    expect(content().classList).toContain('flex-row');
   });
 
   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(UiScrollArea);
-    const inst = componentRef.instance as UiScrollArea;
+    const { host } = await renderScrollArea();
     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);
+
+    host.bounces.set(false);
+    host.scrollBar.set(false);
+    host.nestedScroll.set(true);
     await waitForUpdate();
     expect(attributes.last('bounces')).toBe(false);
     expect(attributes.last('scroll-bar-enable')).toBe(false);
     expect(attributes.last('enable-nested-scroll')).toBe(true);
     attributes.restore();
   });
+
+  it('emits when scrolled to the start or the end', async () => {
+    const { host, scrollView } = await renderScrollArea();
+    fireEvent.scrolltolower(scrollView());
+    fireEvent.scrolltoupper(scrollView());
+    expect(host.reached).toEqual(['end', 'start']);
+  });
 });

package/dist/ui/components/scroll-area/scroll-area.ts

@@ -1,6 +1,7 @@
 import {
   Component,
   ViewEncapsulation,
+  booleanAttribute,
   computed,
   input,
   output,
@@ -40,9 +41,9 @@ import { cn } from '../../utils/cn';
 export class UiScrollArea {
   readonly orientation = input<'vertical' | 'horizontal'>('vertical');
   readonly height = input<string>('');
-  readonly bounces = input(true);
-  readonly scrollBar = input(true);
-  readonly nestedScroll = input(false);
+  readonly bounces = input(true, { transform: booleanAttribute });
+  readonly scrollBar = input(true, { transform: booleanAttribute });
+  readonly nestedScroll = input(false, { transform: booleanAttribute });
   readonly upperThreshold = input(0);
   readonly lowerThreshold = input(0);
   readonly userClass = input<string>('', { alias: 'class' });

package/dist/ui/components/search-field/index.ts

@@ -0,0 +1,15 @@
+export {
+  UI_SEARCH_FIELD_CONTAINER,
+  UiSearchField,
+  type SearchFieldContainer,
+} from './search-field';
+export {
+  KEYBOARD_GAP,
+  keyboardHeightOf,
+  keyboardLift,
+  keyboardScreen,
+  measureForKeyboard,
+  type KeyboardHeightEvent,
+  type KeyboardRect,
+  type KeyboardScreen,
+} from './keyboard';

package/dist/ui/components/search-field/keyboard.test.ts

@@ -0,0 +1,147 @@
+import { Injector, type Renderer2 } from '@angular/core';
+import { LynxSystemInfo } from '@blotch/angular-lynx';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import {
+  type KeyboardScreen,
+  keyboardHeightOf,
+  keyboardLift,
+  keyboardScreen,
+  measureForKeyboard,
+} from './keyboard';
+
+const IPHONE: KeyboardScreen = {
+  platform: 'iOS',
+  pixelRatio: 3,
+  screenHeight: 874,
+};
+const PIXEL: KeyboardScreen = {
+  platform: 'Android',
+  pixelRatio: 2.625,
+  screenHeight: 914,
+};
+
+/**
+ * The Lynx function that runs an element's UI methods, which the testing
+ * library defines on the global object.
+ */
+type InvokeUIMethod = {
+  __InvokeUIMethod: (
+    element: unknown,
+    method: string,
+    params: Record<string, unknown>,
+    callback: (result: { code: number; data?: unknown }) => void,
+  ) => void;
+};
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('keyboardHeightOf', () => {
+  it('takes iOS’s points as they are', () => {
+    expect(keyboardHeightOf({ detail: { height: 336 } }, IPHONE)).toBe(336);
+  });
+
+  it('turns Android’s physical pixels into px', () => {
+    expect(keyboardHeightOf({ detail: { height: 819 } }, PIXEL)).toBe(312);
+  });
+});
+
+describe('keyboardLift', () => {
+  it('measures iOS’s keyboard up from the bottom of the screen', () => {
+    // The keyboard's top is at 874 - 336 = 538; the field's bottom clears it
+    // by the gap.
+    expect(keyboardLift({ bottom: 820 }, { bottom: 840 }, 336, IPHONE, 8)).toBe(
+      290,
+    );
+  });
+
+  it('measures Android’s up from the bottom of the Lynx view', () => {
+    // The keyboard's top is at 890 - 312 = 578.
+    expect(keyboardLift({ bottom: 855 }, { bottom: 890 }, 312, PIXEL, 8)).toBe(
+      285,
+    );
+  });
+
+  it('is 0 when the keyboard doesn’t reach the element, or is down', () => {
+    expect(keyboardLift({ bottom: 300 }, { bottom: 874 }, 336, IPHONE, 8)).toBe(
+      0,
+    );
+    expect(keyboardLift({ bottom: 820 }, { bottom: 874 }, 0, IPHONE, 8)).toBe(
+      0,
+    );
+  });
+});
+
+describe('keyboardScreen', () => {
+  it('is LynxSystemInfo where there is one', () => {
+    const info = { platform: 'iOS', pixelRatio: 3, screenHeight: 874 };
+    const injector = Injector.create({
+      providers: [{ provide: LynxSystemInfo, useValue: info }],
+    });
+    expect(keyboardScreen(injector)).toBe(info);
+  });
+
+  it('is null where LynxSystemInfo has no SystemInfo to read, and throws', () => {
+    const injector = Injector.create({
+      providers: [
+        {
+          provide: LynxSystemInfo,
+          useFactory: () => {
+            throw new Error('SystemInfo is not available in this environment');
+          },
+        },
+      ],
+    });
+    expect(keyboardScreen(injector)).toBeNull();
+  });
+});
+
+describe('measureForKeyboard', () => {
+  /** A page holding a column holding the field, as Lynx elements. */
+  const page = { element: 'page', tagName: 'page' };
+  const column = { element: 'column' };
+  const field = { element: 'field' };
+  // The page has a parent of its own in the testing library, which the
+  // walk stops short of.
+  const parents = new Map<unknown, unknown>([
+    [field, column],
+    [column, page],
+    [page, { element: 'document' }],
+  ]);
+  const renderer = {
+    parentNode: (node: unknown) => parents.get(node) ?? null,
+  } as unknown as Renderer2;
+
+  it('measures the element and the page it’s in, on screen', async () => {
+    const invoke = vi
+      .spyOn(globalThis as unknown as InvokeUIMethod, '__InvokeUIMethod')
+      .mockImplementation((element, _method, _params, callback) =>
+        callback({
+          code: 0,
+          data: { bottom: element === 'page' ? 874 : 820 },
+        }),
+      );
+
+    await expect(measureForKeyboard(renderer, field)).resolves.toEqual({
+      element: expect.objectContaining({ bottom: 820 }),
+      page: expect.objectContaining({ bottom: 874 }),
+    });
+    expect(invoke).toHaveBeenCalledWith(
+      'field',
+      'boundingClientRect',
+      { relativeTo: 'screen' },
+      expect.any(Function),
+    );
+  });
+
+  it('is null where an element can’t be measured', async () => {
+    vi.spyOn(
+      globalThis as unknown as InvokeUIMethod,
+      '__InvokeUIMethod',
+    ).mockImplementation((_element, _method, _params, callback) =>
+      callback({ code: 1 }),
+    );
+    await expect(measureForKeyboard(renderer, field)).resolves.toBeNull();
+  });
+});

package/dist/ui/components/search-field/keyboard.ts

@@ -0,0 +1,123 @@
+import { type Injector, type Renderer2 } from '@angular/core';
+import { LynxSystemInfo, MainThreadElement } from '@blotch/angular-lynx';
+
+/**
+ * How far above the keyboard a field that rises clear of it sits, in px: the
+ * gap the dock keeps from the home indicator.
+ */
+export const KEYBOARD_GAP = 8;
+
+/** What a field's `<input>` sends with its `keyboardheightchange` event. */
+export type KeyboardHeightEvent = { detail: { height: number } };
+
+/** The platform, as far as the keyboard's geometry needs it. */
+export type KeyboardScreen = {
+  readonly platform: string;
+  readonly pixelRatio: number;
+  /** The screen's height in px. */
+  readonly screenHeight: number;
+};
+
+/**
+ * The platform from LynxSystemInfo, or null where there's no SystemInfo to
+ * read: LynxSystemInfo throws in unit tests without one. Looked up when the
+ * keyboard shows, which is when it's needed.
+ */
+export const keyboardScreen = (injector: Injector): KeyboardScreen | null => {
+  try {
+    return injector.get(LynxSystemInfo);
+  } catch {
+    return null;
+  }
+};
+
+/** A box on screen, as far as the keyboard's geometry needs it, in px. */
+export type KeyboardRect = { readonly bottom: number };
+
+/**
+ * The keyboard's height in px, from an `<input>`'s `keyboardheightchange`
+ * event, which arrives on the main thread while the input is focused: as the
+ * keyboard shows, when it changes size (the emoji keyboard, the predictive
+ * bar), and with 0 as it hides.
+ *
+ * Lynx measures it differently on each platform. iOS sends points, measured
+ * up from the bottom of the window. Android sends physical pixels, measured
+ * up from the bottom of the Lynx view: an app whose window shrinks above the
+ * keyboard, as the Android app `ng build --platform android` makes does,
+ * gets 0 once it has.
+ */
+export const keyboardHeightOf = (
+  event: KeyboardHeightEvent,
+  screen: KeyboardScreen,
+): number =>
+  screen.platform === 'Android'
+    ? event.detail.height / screen.pixelRatio
+    : event.detail.height;
+
+/**
+ * How far an element has to rise for its bottom edge to clear the keyboard
+ * by `gap`, in px: 0 when the keyboard doesn't reach it. `element` and
+ * `page` are their boxes on screen, `page` the Lynx page's, whose bottom is
+ * the Lynx view's: iOS measures the keyboard from the window's bottom edge,
+ * and Android from the Lynx view's (see keyboardHeightOf()).
+ */
+export const keyboardLift = (
+  element: KeyboardRect,
+  page: KeyboardRect,
+  keyboard: number,
+  screen: KeyboardScreen,
+  gap: number,
+): number => {
+  if (keyboard <= 0) return 0;
+  const keyboardTop =
+    screen.platform === 'iOS'
+      ? screen.screenHeight - keyboard
+      : page.bottom - keyboard;
+  return Math.max(0, Math.round(element.bottom + gap - keyboardTop));
+};
+
+/** AngularLynx's wrapper of a Lynx element, around the element itself. */
+type LynxElementRef = { readonly element: unknown; readonly tagName?: string };
+
+/**
+ * An element's box on screen, or null where it can't be measured (the web
+ * preview measures from the `<lynx-view>`, which has no keyboard to clear).
+ * Lynx gives a script an element's position only through its
+ * `boundingClientRect` UI method, which answers later.
+ */
+const measureOnScreen = async (
+  element: LynxElementRef,
+): Promise<KeyboardRect | null> => {
+  try {
+    return await new MainThreadElement(
+      element.element as ConstructorParameters<typeof MainThreadElement>[0],
+    ).getBoundingClientRect({ relativeTo: 'screen' });
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Measures `element` and the page it's in, the `<page>` above it, for
+ * keyboardLift(). Null when either can't be measured.
+ */
+export const measureForKeyboard = async (
+  renderer: Renderer2,
+  element: LynxElementRef,
+): Promise<{ element: KeyboardRect; page: KeyboardRect } | null> => {
+  let page = element;
+  for (
+    let parent = renderer.parentNode(page) as LynxElementRef | null;
+    parent && page.tagName !== 'page';
+    parent = renderer.parentNode(parent) as LynxElementRef | null
+  ) {
+    page = parent;
+  }
+  const [elementRect, pageRect] = await Promise.all([
+    measureOnScreen(element),
+    measureOnScreen(page),
+  ]);
+  return elementRect && pageRect
+    ? { element: elementRect, page: pageRect }
+    : null;
+};