@remit/ui 0.0.153 → 0.0.155

package/src/components/self-update-progress-overlay.tsx

@@ -1,6 +1,7 @@
 import { AlertOctagon, Check, Loader2 } from "lucide-react";
 import { type RefObject, useEffect, useRef } from "react";
 import { cn } from "../lib/cn.js";
+import { useOverlayScope } from "../lib/overlay-scope.js";
 import { Button } from "./button.js";
 import {
 	type UpdatePhase,
@@ -76,6 +77,9 @@ export function SelfUpdateProgressOverlay({
 }: SelfUpdateProgressOverlayProps) {
 	const ref = useRef<HTMLDivElement>(null);
 	useBlockingFocus(ref);
+	// Nothing to answer: the update is running and there is no way out of it, so
+	// every shortcut is contained rather than acting on a mailbox that is gone.
+	useOverlayScope({ id: "self-update", open: true });
 	const activeIndex = phaseOrder.indexOf(phase);
 
 	return (

package/src/components/slide-panel.tsx

@@ -1,6 +1,7 @@
 import { X } from "lucide-react";
-import { type ReactNode, useEffect } from "react";
+import type { ReactNode } from "react";
 import { cn } from "../lib/cn.js";
+import { useOverlayScope } from "../lib/overlay-scope.js";
 
 /* ------------------------------------------------------------------ */
 /* SlidePanel: right-edge slide-over for a focused sub-task (editing   */
@@ -28,15 +29,13 @@ export function SlidePanel({
 	footer,
 }: SlidePanelProps) {
 	// Escape closes the panel from anywhere inside it, which is what a dialog
-	// owes the keyboard. The scrim is a pointer affordance only.
-	useEffect(() => {
-		if (!isOpen) return;
-		const onKeyDown = (event: KeyboardEvent) => {
-			if (event.key === "Escape") onClose();
-		};
-		document.addEventListener("keydown", onKeyDown);
-		return () => document.removeEventListener("keydown", onKeyDown);
-	}, [isOpen, onClose]);
+	// owes the keyboard, and nothing behind it sees the press. The scrim is a
+	// pointer affordance only.
+	useOverlayScope({
+		id: "slide-panel",
+		open: isOpen,
+		answers: { back: onClose },
+	});
 
 	return (
 		<>

package/src/index.ts

@@ -354,7 +354,6 @@ export {
 	type FolderRole,
 	isVirtualFolderRole,
 	provenanceFolderLabel,
-	providerLeaf,
 	type ResultFolder,
 	roleIcon,
 } from "./components/folder-role.js";
@@ -908,6 +907,13 @@ export {
 	DESKTOP_MEDIA_QUERY,
 	DESKTOP_MIN_WIDTH,
 } from "./lib/layout-breakpoints.js";
+export {
+	type OverlayAnswers,
+	type OverlayScopeOptions,
+	overlayStack,
+	resolveAgainstOverlays,
+	useOverlayScope,
+} from "./lib/overlay-scope.js";
 export {
 	derivePropertyClauses,
 	normalizeSubject,

package/src/lib/overlay-scope.test.ts

@@ -0,0 +1,314 @@
+/**
+ * The overlay stack, from the outside: what a window-level listener under an
+ * open overlay is allowed to see (#958), and what a triage layer under one is
+ * allowed to run (#959).
+ */
+import "@remit/test-dom";
+import assert from "node:assert/strict";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { act, createElement, type ReactNode } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import {
+	type OverlayAnswers,
+	overlayStack,
+	resolveAgainstOverlays,
+	useOverlayScope,
+} from "./overlay-scope.js";
+import { useTriageKeyboard } from "./use-triage-keyboard.js";
+
+let root: Root;
+let seen: string[];
+let listener: (event: KeyboardEvent) => void;
+
+beforeEach(() => {
+	const container = document.getElementById("root") as unknown as HTMLElement;
+	container.innerHTML = "";
+	root = createRoot(container);
+	seen = [];
+	listener = (event) => seen.push(event.key);
+	window.addEventListener("keydown", listener);
+});
+
+afterEach(() => {
+	window.removeEventListener("keydown", listener);
+	act(() => root.unmount());
+});
+
+const press = (key: string, from: EventTarget = document.body) => {
+	act(() => {
+		from.dispatchEvent(
+			new window.KeyboardEvent("keydown", { key, bubbles: true }),
+		);
+	});
+};
+
+const field = (id: string): HTMLInputElement =>
+	document.getElementById(id) as HTMLInputElement;
+
+function Scope({
+	id,
+	open,
+	answers,
+	children,
+}: {
+	id: string;
+	open: boolean;
+	answers?: OverlayAnswers;
+	children?: ReactNode;
+}) {
+	useOverlayScope({ id, open, answers });
+	return children ?? null;
+}
+
+const render = (element: ReactNode) => {
+	act(() => root.render(element));
+};
+
+describe("an overlay on the stack", () => {
+	it("answers Escape itself and leaves nothing for the window to see", () => {
+		const dismissed: string[] = [];
+		render(
+			createElement(Scope, {
+				id: "sheet",
+				open: true,
+				answers: { back: () => dismissed.push("sheet") },
+			}),
+		);
+
+		press("Escape");
+
+		assert.deepEqual(dismissed, ["sheet"]);
+		assert.deepEqual(
+			seen,
+			[],
+			"the layer behind the overlay saw the same press",
+		);
+	});
+
+	it("hands the key back once it closes", () => {
+		render(createElement(Scope, { id: "sheet", open: true, answers: {} }));
+		render(createElement(Scope, { id: "sheet", open: false, answers: {} }));
+
+		press("Escape");
+
+		assert.deepEqual(seen, ["Escape"]);
+	});
+
+	// Both open in one render, which is the case mount order gets wrong: React
+	// runs the inner overlay's effects first, so registration order would put the
+	// drawer on top of the confirmation it contains.
+	it("is answered by the innermost overlay, however the two came to be open", () => {
+		const dismissed: string[] = [];
+		const stack = () =>
+			createElement(Scope, {
+				id: "drawer",
+				open: true,
+				answers: { back: () => dismissed.push("drawer") },
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test
+				children: createElement(Scope, {
+					id: "confirm",
+					open: true,
+					answers: { back: () => dismissed.push("confirm") },
+				}),
+			});
+
+		render(stack());
+		press("Escape");
+		assert.deepEqual(
+			dismissed,
+			["confirm"],
+			"the drawer under the confirmation answered for it",
+		);
+
+		assert.deepEqual(
+			overlayStack().map((frame) => frame.id),
+			["drawer", "confirm"],
+			"the stack is not ordered outside-in",
+		);
+	});
+
+	it("says what it answers without leaving the stack to say it", () => {
+		const rung: string[] = [];
+		const scope = (serving: boolean) =>
+			createElement(Scope, {
+				id: "drawer",
+				open: true,
+				answers: serving
+					? {
+							back: () => rung.push("back"),
+							toggleIntelligence: () => rung.push("toggleIntelligence"),
+						}
+					: { back: () => rung.push("back") },
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test
+				children: createElement(Scope, {
+					id: "confirm",
+					open: true,
+					answers: { back: () => rung.push("confirm") },
+				}),
+			});
+
+		render(scope(false));
+		render(scope(true));
+
+		press("Escape");
+
+		assert.deepEqual(
+			rung,
+			["confirm"],
+			"changing what the drawer answers moved it above the confirmation",
+		);
+	});
+
+	it("keeps serving the key that opened it, and nothing else", () => {
+		const rung: string[] = [];
+		render(
+			createElement(Scope, {
+				id: "drawer",
+				open: true,
+				answers: {
+					back: () => rung.push("back"),
+					toggleIntelligence: () => rung.push("toggleIntelligence"),
+				},
+			}),
+		);
+
+		press("i");
+		press("j");
+
+		assert.deepEqual(rung, ["toggleIntelligence"]);
+		// Only what the drawer answered is swallowed. A key it does not serve is
+		// left to travel; what stops it is the triage layer declining to run it.
+		assert.deepEqual(seen, ["j"], "the drawer ate a key it never answered");
+	});
+
+	it("is not answered by a key typed into a field inside it", () => {
+		const rung: string[] = [];
+		render(
+			createElement(Scope, {
+				id: "drawer",
+				open: true,
+				answers: {
+					back: () => rung.push("back"),
+					toggleIntelligence: () => rung.push("toggleIntelligence"),
+				},
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test
+				children: createElement("input", { id: "typing" }),
+			}),
+		);
+
+		press("i", field("typing"));
+
+		assert.deepEqual(
+			rung,
+			[],
+			"a letter typed into the field closed the drawer",
+		);
+	});
+
+	it("yields Escape to a control inside it that owns one", () => {
+		const dismissed: string[] = [];
+		render(
+			createElement(Scope, {
+				id: "sheet",
+				open: true,
+				answers: { back: () => dismissed.push("sheet") },
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test
+				children: createElement("input", {
+					"data-escape-owner": "",
+					id: "suggesting",
+				}),
+			}),
+		);
+		(document.getElementById("suggesting") as HTMLInputElement).focus();
+
+		press("Escape");
+
+		assert.deepEqual(dismissed, [], "the overlay took Escape from the field");
+	});
+});
+
+describe("what the surfaces under an overlay may act on", () => {
+	it("contains an action the overlay does not serve", () => {
+		render(createElement(Scope, { id: "sheet", open: true, answers: {} }));
+
+		assert.equal(resolveAgainstOverlays("compose")?.outcome, "contained");
+	});
+
+	it("resolves to nothing at all with no overlay up", () => {
+		assert.equal(resolveAgainstOverlays("compose"), null);
+	});
+
+	it("leaves c and i typed into a field under an overlay inert (#959)", () => {
+		const ran: string[] = [];
+		function Layer() {
+			useTriageKeyboard({
+				handlers: {
+					compose: () => ran.push("compose"),
+					toggleIntelligence: () => ran.push("toggleIntelligence"),
+				},
+			});
+			return createElement(Scope, {
+				id: "sheet",
+				open: true,
+				answers: { back: () => undefined },
+				// biome-ignore lint/correctness/noChildrenProp: no JSX in a `.ts` test
+				children: createElement("input", { id: "typing" }),
+			});
+		}
+
+		render(createElement(Layer));
+
+		press("c", field("typing"));
+		press("i", field("typing"));
+
+		assert.deepEqual(
+			ran,
+			[],
+			"typing under an overlay reached the layer below",
+		);
+	});
+
+	it("drops a g prefix rather than arming one behind the overlay", () => {
+		const went: string[] = [];
+		function Layer({ modal }: { modal: boolean }) {
+			useTriageKeyboard({ handlers: { goBrief: () => went.push("goBrief") } });
+			return createElement(Scope, {
+				id: "sheet",
+				open: modal,
+				answers: { back: () => undefined },
+			});
+		}
+
+		// `g` over the modal must not leave a prefix behind for the `b` that
+		// follows it, which lands after the overlay has gone.
+		render(createElement(Layer, { modal: true }));
+		press("g");
+		render(createElement(Layer, { modal: false }));
+		press("b");
+		assert.deepEqual(went, [], "a sequence completed across the modal");
+
+		press("g");
+		press("b");
+		assert.deepEqual(went, ["goBrief"], "g stayed dead after the modal closed");
+	});
+
+	it("leaves a triage layer's compose inert under a modal (#959)", () => {
+		const composed: string[] = [];
+		function Layer({ modal }: { modal: boolean }) {
+			useTriageKeyboard({ handlers: { compose: () => composed.push("c") } });
+			return createElement(Scope, {
+				id: "confirm",
+				open: modal,
+				answers: { back: () => undefined },
+			});
+		}
+
+		render(createElement(Layer, { modal: true }));
+		press("c");
+		assert.deepEqual(composed, [], "c opened compose from under the modal");
+
+		render(createElement(Layer, { modal: false }));
+		press("c");
+		assert.deepEqual(composed, ["c"], "c stayed dead after the modal closed");
+	});
+});

package/src/lib/overlay-scope.ts

@@ -0,0 +1,205 @@
+/**
+ * The live overlay stack — the runtime half of the shortcut tree's leaf.
+ *
+ * `shortcut-tree` already states the rule: the top overlay frame either answers
+ * an action or contains it, and a key pressed over an overlay never reaches the
+ * surface behind it. Nothing enforced that at runtime, so every overlay grew its
+ * own answer — a capture-phase window listener here, a document-phase
+ * `stopPropagation` there, a `blocksKeyboard` flag threaded up through a pane —
+ * and the surfaces that grew none let Escape close the conversation underneath
+ * (#958) while `c` opened compose out from under a modal (#959).
+ *
+ * A mounted overlay declares itself here for as long as it is on screen, with
+ * what it answers for, and the rest follows from that one declaration:
+ *
+ * - What the top frame answers is run by one listener, shared by every overlay.
+ *   It sits on `window` in the capture phase, ahead of the triage layers and of
+ *   every other window listener the app binds, and swallows the key it ran —
+ *   Escape for a dismissal, and `i` for the drawer that key opened. A control
+ *   inside an overlay with something of its own to close marks itself
+ *   `[data-escape-owner]` and keeps Escape while it holds focus.
+ * - Everything else is contained rather than swallowed: `useTriageKeyboard`
+ *   resolves through {@link resolveAgainstOverlays} and declines to run a handler
+ *   the top frame does not serve, so the key is inert instead of racing.
+ *
+ * An overlay that answers nothing — the selection wizard, which has its own Back
+ * and Close and wants Escape to do neither — declares no answers and still
+ * contains the keyboard while it is up.
+ *
+ * The stack is ordered by where each overlay sits in the React tree, taken once
+ * at its first render: an overlay is above every overlay it renders inside. That
+ * is the invariant a nested pair needs — a confirmation raised from inside a
+ * drawer is the one Escape reaches — and it holds however the two came to be
+ * open, including a remount that mounts both in one commit. Registration order
+ * cannot state it: React runs a child's effects before its parent's, so
+ * registering on mount puts the inner overlay underneath the one containing it.
+ *
+ * The stack is module state rather than a React context on purpose: a window
+ * listener is global, so the register it answers from is too, and an overlay
+ * rendered through a portal or mounted in a Storybook story needs no provider
+ * above it to be seen.
+ */
+import { useEffect, useRef, useState } from "react";
+import type { TriageAction } from "./keymap.js";
+import {
+	dispatchKey,
+	isControlTarget,
+	isEditableTarget,
+} from "./keymap-dispatch.js";
+import {
+	type OverlayFrame,
+	type Resolution,
+	resolveOverlays,
+} from "./shortcut-tree.js";
+
+/** What an overlay answers, keyed by the action it answers. */
+export type OverlayAnswers = Partial<Record<TriageAction, () => void>>;
+
+interface ScopeEntry {
+	id: string;
+	/** Position in the React tree, ascending outward-in. See the module note. */
+	depth: number;
+	run: () => OverlayAnswers;
+}
+
+const ESCAPE_OWNER_SELECTOR = "[data-escape-owner]";
+
+let entries: ScopeEntry[] = [];
+
+/** Handed out by `useState` during render, so parents are numbered before children. */
+let renderedOverlays = 0;
+const nextDepth = (): number => ++renderedOverlays;
+
+const byDepth = (a: ScopeEntry, b: ScopeEntry): number => a.depth - b.depth;
+
+/**
+ * The frames on screen, root first — the tree's `overlays`.
+ *
+ * Built on demand rather than stored, so an overlay that gains or loses an
+ * answer while it is open says so without leaving the stack and rejoining it at
+ * the top.
+ */
+export function overlayStack(): readonly OverlayFrame[] {
+	return [...entries].sort(byDepth).map((entry) => ({
+		id: entry.id,
+		handles: Object.entries(entry.run())
+			.filter(([, answer]) => answer)
+			.map(([action]) => action as TriageAction),
+	}));
+}
+
+/** The innermost overlay on screen — the leaf that answers first. */
+function topEntry(): ScopeEntry | undefined {
+	let top: ScopeEntry | undefined;
+	for (const entry of entries) {
+		if (!top || entry.depth > top.depth) top = entry;
+	}
+	return top;
+}
+
+/**
+ * How the open overlays answer this action, or null when none is up. A layer
+ * with a window-level keyboard consults this before running a handler of its
+ * own: any answer at all means the action belongs to the overlay.
+ */
+export function resolveAgainstOverlays(
+	action: TriageAction,
+): Resolution | null {
+	return resolveOverlays(action, overlayStack());
+}
+
+/**
+ * What this keystroke means to an overlay. Escape reaches one from anywhere
+ * inside it, a focused field included — unless a control in there has its own
+ * thing to close, which takes the press and leaves the next one for the overlay.
+ * Every other key goes through the ordinary dispatch, so `i` typed into a field
+ * inside a drawer is a letter and not a dismissal. A `g …` sequence is never an
+ * overlay's to answer, so the prefix state is not carried here.
+ */
+function overlayAction(event: KeyboardEvent): TriageAction | null {
+	if (event.key === "Escape") {
+		const focused = document.activeElement;
+		if (focused instanceof Element && focused.closest(ESCAPE_OWNER_SELECTOR)) {
+			return null;
+		}
+		return "back";
+	}
+	return dispatchKey(
+		{
+			key: event.key,
+			shiftKey: event.shiftKey,
+			metaKey: event.metaKey,
+			ctrlKey: event.ctrlKey,
+			altKey: event.altKey,
+			inEditable: isEditableTarget(event.target),
+			onControl: isControlTarget(event.target),
+		},
+		null,
+	).action;
+}
+
+function onOverlayKey(event: KeyboardEvent): void {
+	const top = topEntry();
+	if (!top) return;
+	const action = overlayAction(event);
+	if (!action) return;
+	const answer = top.run()[action];
+	if (!answer) return;
+	event.preventDefault();
+	event.stopImmediatePropagation();
+	answer();
+}
+
+function setEntries(next: ScopeEntry[]): void {
+	const wasEmpty = entries.length === 0;
+	entries = next;
+	if (wasEmpty === (next.length === 0)) return;
+	if (next.length > 0) {
+		window.addEventListener("keydown", onOverlayKey, true);
+		return;
+	}
+	window.removeEventListener("keydown", onOverlayKey, true);
+}
+
+export interface OverlayScopeOptions {
+	/** Names the frame in the stack; only has to tell it from its neighbours. */
+	id: string;
+	/** On screen. A closed overlay leaves the stack and contains nothing. */
+	open: boolean;
+	/**
+	 * What this overlay answers, run by the shared listener before any layer
+	 * underneath sees the key. `back` is Escape, and dismissing is what a modal,
+	 * a drawer and a menu all want it to mean. Every action outside the table is
+	 * contained: inert for the surfaces underneath, never forwarded.
+	 */
+	answers?: OverlayAnswers;
+}
+
+/**
+ * Put this overlay on the stack while it is open. One call replaces a
+ * hand-rolled Escape listener, and hands the rest of the keyboard back to the
+ * surfaces underneath only once the overlay is gone.
+ */
+export function useOverlayScope({
+	id,
+	open,
+	answers = {},
+}: OverlayScopeOptions): void {
+	// Read at keystroke time, so neither a re-rendered answer nor a changed set
+	// of them re-registers the frame.
+	const answersRef = useRef(answers);
+	answersRef.current = answers;
+
+	// Numbered during the first render, where React is still going parent before
+	// child — the one moment nesting is legible from inside a hook.
+	const [depth] = useState(nextDepth);
+
+	useEffect(() => {
+		if (!open) return;
+		const entry: ScopeEntry = { id, depth, run: () => answersRef.current };
+		setEntries([...entries, entry]);
+		return () => {
+			setEntries(entries.filter((candidate) => candidate !== entry));
+		};
+	}, [id, open, depth]);
+}

package/src/lib/shortcut-tree.ts

@@ -315,6 +315,27 @@ function isRegistered(
 	return registered[level]?.includes(action) === true;
 }
 
+/**
+ * The overlay stack's own verdict, independent of everything below it: the top
+ * frame answers the action or contains it, and null means no overlay is up.
+ *
+ * Exported because the runtime stack (`overlay-scope`) needs the same rule from
+ * a keydown listener, where the rest of the tree is not built. One rule, one
+ * place: an overlay that contains a key for the resolver contains it for the
+ * live keyboard too.
+ */
+export function resolveOverlays(
+	action: TriageAction,
+	overlays: readonly OverlayFrame[],
+): Resolution | null {
+	const frame = overlays.at(-1);
+	if (!frame) return null;
+	if (!frame.handles.includes(action)) {
+		return { outcome: "contained", by: { kind: "overlay", frame } };
+	}
+	return { outcome: "act", target: { kind: "overlay", frame } };
+}
+
 /**
  * Resolve an action against the tree. Pure: no DOM, no router, no side effects.
  *
@@ -334,13 +355,8 @@ export function resolveShortcut(
 	tree: ShortcutTree,
 	registered: RegisteredActions,
 ): Resolution {
-	const frame = tree.overlays.at(-1);
-	if (frame) {
-		if (!frame.handles.includes(action)) {
-			return { outcome: "contained", by: { kind: "overlay", frame } };
-		}
-		return { outcome: "act", target: { kind: "overlay", frame } };
-	}
+	const overlaid = resolveOverlays(action, tree.overlays);
+	if (overlaid) return overlaid;
 
 	const field = tree.editing;
 	if (field) {

package/src/lib/use-triage-keyboard.ts

@@ -6,6 +6,7 @@ import {
 	isEditableTarget,
 	type SequencePrefix,
 } from "./keymap-dispatch.js";
+import { overlayStack, resolveAgainstOverlays } from "./overlay-scope.js";
 
 interface UseTriageKeyboardOptions {
 	handlers: TriageHandlers;
@@ -47,6 +48,11 @@ interface UseTriageKeyboardOptions {
  * conversation views. They bind disjoint keys; only the list's competing
  * listener was removed.
  *
+ * An open overlay pre-empts the whole layer. Every mounted modal, drawer and
+ * menu declares itself through `overlay-scope`, and each action is resolved
+ * against that stack before a handler runs, so no layer acts through a surface
+ * the reader has on top of it.
+ *
  * Per-action targeting (focused row vs selection) and the actual mutations live
  * in the handlers the caller passes in — this hook only dispatches.
  */
@@ -87,6 +93,17 @@ export function useTriageKeyboard({
 				prefixRef.current,
 			);
 
+			// An overlay is the leaf of the shortcut tree: while one is on screen it
+			// answers what it serves — through `overlay-scope`'s own listener, which
+			// has already run and swallowed the key — and contains the rest. The
+			// pending prefix is contained with it: a `g` pressed over a modal must
+			// not arm a sequence whose second key lands on the surface behind it.
+			if (overlayStack().length > 0) {
+				clearPrefixTimer();
+				prefixRef.current = null;
+				return;
+			}
+
 			// Update the pending prefix and (re)arm / clear its reset timer.
 			clearPrefixTimer();
 			prefixRef.current = result.nextPrefix;
@@ -99,6 +116,10 @@ export function useTriageKeyboard({
 
 			if (result.action === null) return;
 
+			// The same rule, per action: a contained key is left undefaulted, because
+			// it was never ours to consume.
+			if (resolveAgainstOverlays(result.action) !== null) return;
+
 			const handler = handlersRef.current[result.action];
 			if (!handler) return;