@remit/ui 0.0.55 → 0.0.57

package/src/lib/use-long-press.ts

@@ -1,7 +1,59 @@
 import type { DOMAttributes } from "@react-types/shared";
-import { type PointerEvent, useCallback, useRef } from "react";
+import { type PointerEvent, useCallback } from "react";
 import { mergeProps, useLongPress as useAriaLongPress } from "react-aria";
 
+/**
+ * Suppression lives on the document, not on the row.
+ *
+ * There is one pointer, and the element under it does not survive the press: a
+ * long press on a mailbox row enters selection mode, which swaps the swipeable
+ * row for the plain one *while the finger is still down*. A handler on the row
+ * that armed the press is torn down with it, and Android Chrome then raises its
+ * link menu over the selection the press just made. A capture-phase listener on
+ * the document sees the menu whichever node ends up under the finger.
+ *
+ * Set while a touch or pen press is down. A press that never delivers its
+ * `pointerup` — the browser took the gesture, the tab went to the background —
+ * would leave suppression armed forever, so arming is bounded by this timer as
+ * well as by the release.
+ */
+let armedTimer: ReturnType<typeof setTimeout> | undefined;
+
+/** Longer than any press a human holds before the browser ends the gesture. */
+const MAX_ARMED_MS = 5_000;
+
+/**
+ * One press raises at most one menu, so suppression is spent on use. The
+ * release disarms too, which is what keeps a keyboard-invoked menu
+ * (Context-Menu key / Shift+F10) raised later from inheriting a press that is
+ * long over. Deliberately keyed to `pointerup` and not to `pointercancel`: on
+ * Android the browser — and react-aria's own long-press timer — can cancel the
+ * pointer before the `contextmenu` it raised arrives, which would race the
+ * suppression away.
+ */
+function suppressContextMenu(event: Event): void {
+	event.preventDefault();
+	disarm();
+}
+
+function disarm(): void {
+	if (armedTimer === undefined) return;
+	clearTimeout(armedTimer);
+	armedTimer = undefined;
+	document.removeEventListener("contextmenu", suppressContextMenu, true);
+	document.removeEventListener("pointerup", disarm, true);
+}
+
+function arm(): void {
+	if (armedTimer === undefined) {
+		document.addEventListener("contextmenu", suppressContextMenu, true);
+		document.addEventListener("pointerup", disarm, true);
+	} else {
+		clearTimeout(armedTimer);
+	}
+	armedTimer = setTimeout(disarm, MAX_ARMED_MS);
+}
+
 export interface UseLongPressOptions {
 	/** Called once the threshold elapses while the press stays over the target. */
 	onLongPress: () => void;
@@ -32,14 +84,17 @@ export interface UseLongPressResult {
  * `-webkit-touch-callout: none` in CSS at the call site, since iOS fires no
  * cancelable event for it.
  *
- * The `contextmenu` suppression is keyed to the active pointer's type, tracked
- * off `pointerdown` on the same element: a touch or pen press suppresses the
- * menu Android Chrome and iOS Safari raise on a long press over a link, while a
- * mouse right-click is left alone so the desktop context menu keeps working. It
- * does not delegate this to react-aria's own suppression — that listener is
- * transient (added on press start, scoped to the touched node, and torn down
- * shortly after pointerup), so a press ended early by the swipe gesture's axis
- * arbitration, or a menu raised over a descendant node, slips past it.
+ * The `contextmenu` suppression is armed by a touch or pen `pointerdown` and
+ * runs on the document in the capture phase: a touch press suppresses the menu
+ * Android Chrome and iOS Safari raise on a long press over a link, while a mouse
+ * right-click is left alone so the desktop context menu keeps working. Two
+ * reasons it is neither react-aria's own suppression nor a handler on the row.
+ * react-aria's listener is transient — added on press start, scoped to the
+ * touched node, torn down shortly after pointerup — so a press ended early by
+ * the swipe gesture's axis arbitration slips past it. And the row itself does
+ * not survive the press: the long press enters selection mode, which replaces
+ * the swipeable row with the plain one while the finger is still down, so a
+ * handler bound to the pressed node is gone by the time the menu arrives.
  *
  * Single source of truth for the app's long-press threshold — both mobile
  * row consumers (the plain row and the swipeable row) go through this hook
@@ -58,37 +113,15 @@ export function useLongPress({
 		onLongPress,
 	});
 
-	const pointerTypeRef = useRef<string>("");
-
+	// Only a touch or pen press arms it: a mouse right-click, and a keyboard menu
+	// (Context-Menu key / Shift+F10) that is preceded by no press at all, keep
+	// the native menu.
 	const onPointerDown = useCallback((event: PointerEvent) => {
-		pointerTypeRef.current = event.pointerType;
-	}, []);
-
-	// A press that lifts without raising a menu disarms suppression, so a later
-	// keyboard-invoked menu can't inherit its pointer type. Not cleared on
-	// pointercancel: on Android the browser (and react-aria's own long-press
-	// timer) can fire pointercancel before the long-press contextmenu, which
-	// would race the suppression away.
-	const onPointerUp = useCallback(() => {
-		pointerTypeRef.current = "";
-	}, []);
-
-	const onContextMenu = useCallback((event: { preventDefault: () => void }) => {
-		// Consume the armed pointer type. A keyboard-invoked menu (Context-Menu
-		// key / Shift+F10) fires no pointerdown, so without spending the type on
-		// use it would inherit the last touch press's and be wrongly suppressed.
-		const pointerType = pointerTypeRef.current;
-		pointerTypeRef.current = "";
-		if (pointerType === "touch" || pointerType === "pen") {
-			event.preventDefault();
-		}
+		if (event.pointerType !== "touch" && event.pointerType !== "pen") return;
+		arm();
 	}, []);
 
 	return {
-		longPressProps: mergeProps(longPressProps, {
-			onPointerDown,
-			onPointerUp,
-			onContextMenu,
-		}),
+		longPressProps: mergeProps(longPressProps, { onPointerDown }),
 	};
 }

package/src/lib/use-suggest-list.test.ts

@@ -0,0 +1,169 @@
+/**
+ * use-suggest-list — drives the real hook on a jsdom-mounted input, because what
+ * matters is the interaction between its state and the keystrokes the field
+ * receives: an accepted suggestion, a dismissal that leaves the typed value
+ * alone, a result set that changes under a stale highlight. The key rules
+ * themselves are pure and tested in `suggest-keys.test.ts`.
+ */
+
+import assert from "node:assert/strict";
+import { after, afterEach, before, beforeEach, describe, it } from "node:test";
+import type { JSDOM } from "jsdom";
+import { act, createElement, useState } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { useSuggestList } from "./use-suggest-list.js";
+
+let dom: JSDOM;
+let container: HTMLElement;
+let root: Root;
+
+const accepted: string[] = [];
+
+function Field(props: { options: string[] }) {
+	const [value, setValue] = useState("typed");
+	const suggest = useSuggestList({
+		count: props.options.length,
+		onAccept: (index) => accepted.push(props.options[index]),
+	});
+	return createElement("input", {
+		id: "field",
+		value,
+		onChange: (event: { target: { value: string } }) => {
+			suggest.reopen();
+			setValue(event.target.value);
+		},
+		onKeyDown: suggest.handleKeyDown,
+		"data-open": String(suggest.open),
+		"data-active": String(suggest.activeIndex),
+		...suggest.comboboxProps,
+	});
+}
+
+function mount(options: string[]) {
+	act(() => {
+		root.render(createElement(Field, { options }));
+	});
+	const field = dom.window.document.getElementById("field");
+	assert.ok(field, "field did not mount");
+	// React's change-event polyfill tracks the focused input across keystrokes;
+	// keys arriving at an unfocused field are not a state this ever sees.
+	act(() => {
+		(field as HTMLInputElement).focus();
+	});
+	return field;
+}
+
+function press(field: Element, key: string) {
+	const event = new dom.window.KeyboardEvent("keydown", {
+		key,
+		bubbles: true,
+		cancelable: true,
+	});
+	act(() => {
+		field.dispatchEvent(event);
+	});
+	return event;
+}
+
+before(async () => {
+	const { JSDOM: JSDOMCtor } = await import("jsdom");
+	dom = new JSDOMCtor(
+		"<!doctype html><html><body><div id=root></div></body></html>",
+		{ url: "http://localhost/", pretendToBeVisual: true },
+	);
+	globalThis.window = dom.window as unknown as typeof globalThis.window;
+	globalThis.document = dom.window.document;
+	globalThis.HTMLElement = dom.window.HTMLElement;
+	globalThis.Element = dom.window.Element;
+	globalThis.SVGElement = dom.window.SVGElement;
+	globalThis.KeyboardEvent = dom.window.KeyboardEvent;
+	(
+		globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+	).IS_REACT_ACT_ENVIRONMENT = true;
+});
+
+after(() => {
+	dom.window.close();
+});
+
+beforeEach(() => {
+	accepted.length = 0;
+	container = dom.window.document.getElementById(
+		"root",
+	) as unknown as HTMLElement;
+	container.innerHTML = "";
+	root = createRoot(container);
+});
+
+afterEach(() => {
+	act(() => {
+		root.unmount();
+	});
+});
+
+const OPTIONS = ["one", "two", "three"];
+
+describe("useSuggestList", () => {
+	it("opens only when there is something to suggest", () => {
+		assert.equal(mount([]).getAttribute("data-open"), "false");
+		assert.equal(mount(OPTIONS).getAttribute("data-open"), "true");
+	});
+
+	it("wires the combobox for a screen reader", () => {
+		const field = mount(OPTIONS);
+		assert.equal(field.getAttribute("role"), "combobox");
+		assert.equal(field.getAttribute("aria-expanded"), "true");
+		assert.equal(field.getAttribute("aria-autocomplete"), "list");
+		assert.ok(field.getAttribute("aria-controls"));
+		assert.equal(field.getAttribute("aria-activedescendant"), null);
+	});
+
+	it("points at the highlighted option once one is highlighted", () => {
+		const field = mount(OPTIONS);
+		press(field, "ArrowDown");
+		assert.equal(field.getAttribute("data-active"), "0");
+		assert.equal(
+			field.getAttribute("aria-activedescendant"),
+			`${field.getAttribute("aria-controls")}-option-0`,
+		);
+	});
+
+	it("takes the highlighted suggestion on Enter and leaves Enter alone otherwise", () => {
+		const field = mount(OPTIONS);
+		const bare = press(field, "Enter");
+		assert.deepEqual(accepted, []);
+		assert.equal(bare.defaultPrevented, false, "the field's own Enter stands");
+
+		press(field, "ArrowDown");
+		press(field, "ArrowDown");
+		press(field, "Enter");
+		assert.deepEqual(accepted, ["two"]);
+	});
+
+	it("closes on Escape without touching what was typed, and owns the key while open", () => {
+		const field = mount(OPTIONS);
+		assert.equal(field.getAttribute("data-escape-owner"), "");
+		press(field, "Escape");
+		assert.equal(field.getAttribute("data-open"), "false");
+		assert.equal(field.getAttribute("data-escape-owner"), null);
+		assert.equal((field as HTMLInputElement).value, "typed");
+	});
+
+	it("leaves Escape to the surrounding surface once the list is closed", () => {
+		const field = mount(OPTIONS);
+		press(field, "Escape");
+		const second = press(field, "Escape");
+		assert.equal(second.defaultPrevented, false);
+	});
+
+	it("offers the list again for a changed result set, with no highlight carried over", () => {
+		const field = mount(OPTIONS);
+		press(field, "ArrowDown");
+		press(field, "Escape");
+		act(() => {
+			root.render(createElement(Field, { options: ["only"] }));
+		});
+		assert.equal(field.getAttribute("data-open"), "true");
+		assert.equal(field.getAttribute("data-active"), "-1");
+	});
+});

package/src/lib/use-suggest-list.ts

@@ -0,0 +1,124 @@
+import {
+	type KeyboardEvent,
+	useCallback,
+	useEffect,
+	useId,
+	useState,
+} from "react";
+import { suggestKeyAction } from "./suggest-keys.js";
+
+export interface UseSuggestListInput {
+	/** How many suggestions are on offer right now. */
+	count: number;
+	/** Take the suggestion at this index. */
+	onAccept: (index: number) => void;
+	/** Extra keys that take the highlighted suggestion — see `suggestKeyAction`. */
+	acceptKeys?: readonly string[];
+}
+
+/** The ARIA wiring a combobox input spreads onto itself. */
+export interface ComboboxProps {
+	role: "combobox";
+	"aria-expanded": boolean;
+	"aria-controls": string;
+	"aria-autocomplete": "list";
+	"aria-activedescendant"?: string;
+	/**
+	 * Marks the field as owning Escape while its list is open, so a surrounding
+	 * dialog closes on Escape only when the list is not the thing to close.
+	 */
+	"data-escape-owner"?: "";
+}
+
+export interface SuggestListState {
+	/** Whether the list should render. */
+	open: boolean;
+	/** The highlighted option, `-1` when the typed value is what stands. */
+	activeIndex: number;
+	setActiveIndex: (index: number) => void;
+	/** Close the list, keeping whatever is typed. */
+	dismiss: () => void;
+	/** Offer the list again — what a fresh keystroke does after a dismissal. */
+	reopen: () => void;
+	/** Returns true when the list consumed the key and the caller should stop. */
+	handleKeyDown: (event: KeyboardEvent) => boolean;
+	listId: string;
+	optionId: (index: number) => string;
+	comboboxProps: ComboboxProps;
+}
+
+/**
+ * The open/highlight state, ARIA wiring, and keyboard handling behind a
+ * suggestion list, so every typeahead in the app behaves the same way and there
+ * is one place the behaviour is defined. The caller owns the data, the markup,
+ * and what a picked suggestion means; this owns only which option is highlighted
+ * and whether the list is showing.
+ *
+ * Nothing here writes the field's value — a dismissal, a re-render, or an empty
+ * result leaves what the user typed exactly as it is.
+ */
+export function useSuggestList({
+	count,
+	onAccept,
+	acceptKeys,
+}: UseSuggestListInput): SuggestListState {
+	const [dismissed, setDismissed] = useState(false);
+	const [activeIndex, setActiveIndex] = useState(-1);
+	const base = useId().replace(/[^a-zA-Z0-9_-]/g, "");
+	const listId = `suggest-${base}`;
+	const optionId = useCallback(
+		(index: number) => `suggest-${base}-option-${index}`,
+		[base],
+	);
+
+	// A changed result set is a new list: no highlight carries over onto an option
+	// the user never saw, and a list dismissed for the previous query is offered
+	// again for this one.
+	// biome-ignore lint/correctness/useExhaustiveDependencies: `count` is the trigger, not a value the effect reads — a different result set is what resets the list
+	useEffect(() => {
+		setActiveIndex(-1);
+		setDismissed(false);
+	}, [count]);
+
+	const open = count > 0 && !dismissed;
+
+	const handleKeyDown = useCallback(
+		(event: KeyboardEvent): boolean => {
+			const action = suggestKeyAction({
+				key: event.key,
+				open,
+				count,
+				activeIndex,
+				acceptKeys,
+			});
+			if (action.type === "none") return false;
+			event.preventDefault();
+			if (action.type === "move") setActiveIndex(action.index);
+			if (action.type === "dismiss") setDismissed(true);
+			if (action.type === "accept") onAccept(action.index);
+			return true;
+		},
+		[open, count, activeIndex, acceptKeys, onAccept],
+	);
+
+	return {
+		open,
+		activeIndex,
+		setActiveIndex,
+		dismiss: useCallback(() => setDismissed(true), []),
+		reopen: useCallback(() => setDismissed(false), []),
+		handleKeyDown,
+		listId,
+		optionId,
+		comboboxProps: {
+			role: "combobox",
+			"aria-expanded": open,
+			"aria-controls": listId,
+			"aria-autocomplete": "list",
+			...(activeIndex >= 0
+				? { "aria-activedescendant": optionId(activeIndex) }
+				: {}),
+			...(open ? { "data-escape-owner": "" as const } : {}),
+		},
+	};
+}