@remit/ui 0.0.114 → 0.0.116

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.114",
+  "version": "0.0.116",
   "type": "module",
   "files": [
     "src"
@@ -13,7 +13,7 @@
   "scripts": {
     "test": "npm run test:typecheck && npm run test:run",
     "test:typecheck": "tsgo --noEmit",
-    "test:run": "node --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=90 --test 'src/**/*.test.ts'"
+    "test:run": "node $NODE_TEST_FLAGS --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=90 --test 'src/**/*.test.ts'"
   },
   "dependencies": {
     "@fontsource-variable/geist": "^5",
@@ -44,12 +44,12 @@
   "peerDependencies": {
     "react": "^19",
     "react-dom": "^19",
-    "@types/react": "^19"
+    "@types/react": "^19",
+    "@types/react-dom": "^19"
   },
   "devDependencies": {
     "@storybook/react": "^9",
     "@types/jsdom": "^28.0.3",
-    "@types/react-dom": "^19",
     "jsdom": "^29.1.1",
     "react": "^19",
     "react-dom": "^19",

package/src/components/isolated-email-frame.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useMemo, useRef, useState } from "react";
+import { useMatchMedia } from "../lib/use-match-media.js";
 import { buildEmailSrcDoc, type EmailFrameVariant } from "./email-frame-css.js";
 
 export interface IsolatedEmailFrameProps {
@@ -86,24 +87,6 @@ export const computeFitScale = (
 	return Math.max(MIN_SCALE, containerWidth / contentWidth);
 };
 
-const useMatchMedia = (query: string): boolean => {
-	const [matches, setMatches] = useState(() => {
-		if (typeof window === "undefined" || !window.matchMedia) return false;
-		return window.matchMedia(query).matches;
-	});
-
-	useEffect(() => {
-		if (typeof window === "undefined" || !window.matchMedia) return;
-		const mql = window.matchMedia(query);
-		setMatches(mql.matches);
-		const handler = (event: MediaQueryListEvent) => setMatches(event.matches);
-		mql.addEventListener("change", handler);
-		return () => mql.removeEventListener("change", handler);
-	}, [query]);
-
-	return matches;
-};
-
 /** Named (non-character) keys worth replaying: moving around and closing. */
 const FORWARDED_NAMED_KEYS = new Set([
 	"Enter",

package/src/components/popover-menu.tsx

@@ -1,8 +1,139 @@
 import { EllipsisVertical } from "lucide-react";
-import { type ReactNode, useEffect, useRef, useState } from "react";
+import type { CSSProperties, Ref, RefObject } from "react";
+import {
+	type ReactNode,
+	useEffect,
+	useLayoutEffect,
+	useRef,
+	useState,
+} from "react";
+import { createPortal } from "react-dom";
 import { cn } from "../lib/cn.js";
 import { Button } from "./button.js";
 
+/** Viewport-relative bounding box of whatever a menu opens against. */
+export interface PopoverMenuAnchor {
+	readonly left: number;
+	readonly right: number;
+	readonly top: number;
+	readonly bottom: number;
+}
+
+const ANCHOR_GAP_PX = 4;
+const VIEWPORT_MARGIN_PX = 8;
+
+/**
+ * Where the panel lands: below the anchor and aligned to whichever edge
+ * `align` names, pulled back onto the screen on every side it would
+ * otherwise cross. A panel too tall for the space below flips above the
+ * anchor instead of running past the bottom edge.
+ */
+function clampToViewport(
+	anchor: PopoverMenuAnchor,
+	panel: { width: number; height: number },
+	align: "start" | "end",
+): { left: number; top: number } {
+	const maxLeft = Math.max(
+		VIEWPORT_MARGIN_PX,
+		window.innerWidth - panel.width - VIEWPORT_MARGIN_PX,
+	);
+	const preferredLeft =
+		align === "end" ? anchor.right - panel.width : anchor.left;
+	const left = Math.min(Math.max(preferredLeft, VIEWPORT_MARGIN_PX), maxLeft);
+
+	const below = anchor.bottom + ANCHOR_GAP_PX;
+	const above = anchor.top - ANCHOR_GAP_PX - panel.height;
+	const fitsBelow =
+		below + panel.height <= window.innerHeight - VIEWPORT_MARGIN_PX;
+	const top = fitsBelow || above < VIEWPORT_MARGIN_PX ? below : above;
+
+	return { left, top };
+}
+
+/**
+ * Measures the anchor and the panel's own size, then keeps the panel's fixed
+ * position clamped to the viewport for as long as it is open — reset on every
+ * resize and on scroll anywhere in the ancestor chain, since a fixed position
+ * does not follow a scrolled anchor on its own.
+ */
+function useAnchoredPlacement(
+	panelRef: RefObject<HTMLElement | null>,
+	open: boolean,
+	align: "start" | "end",
+	getAnchor: () => PopoverMenuAnchor | null,
+): CSSProperties | null {
+	const [style, setStyle] = useState<CSSProperties | null>(null);
+	const getAnchorRef = useRef(getAnchor);
+	getAnchorRef.current = getAnchor;
+
+	useLayoutEffect(() => {
+		if (!open) {
+			setStyle(null);
+			return;
+		}
+		const place = () => {
+			const panel = panelRef.current;
+			const anchor = getAnchorRef.current();
+			if (!panel || !anchor) return;
+			// `.width`/`.height` over the rect's own edges: a `getBoundingClientRect`
+			// stand-in in a test carries the edges without the derived pair.
+			const rect = panel.getBoundingClientRect();
+			const size = {
+				width: rect.right - rect.left,
+				height: rect.bottom - rect.top,
+			};
+			const placement = clampToViewport(anchor, size, align);
+			setStyle((previous) =>
+				previous?.left === placement.left && previous.top === placement.top
+					? previous
+					: { position: "fixed", left: placement.left, top: placement.top },
+			);
+		};
+		place();
+		window.addEventListener("resize", place);
+		window.addEventListener("scroll", place, true);
+		return () => {
+			window.removeEventListener("resize", place);
+			window.removeEventListener("scroll", place, true);
+		};
+	}, [open, align, panelRef]);
+
+	return style;
+}
+
+export interface PopoverMenuPortalProps {
+	open: boolean;
+	align?: "start" | "end";
+	getAnchor: () => PopoverMenuAnchor | null;
+	panelRef: RefObject<HTMLElement | null>;
+	children: ReactNode;
+}
+
+/**
+ * Carries a menu panel out of the DOM subtree it opened from and into the
+ * document body, positioned at a fixed, viewport-clamped point. A panel left
+ * in place is clipped by the first scrolling ancestor between it and the
+ * page — the compose body, a card, anything with its own `overflow` — no
+ * matter how high its `z-index` climbs; escaping that ancestor takes leaving
+ * its DOM subtree, which only a portal does.
+ */
+export function PopoverMenuPortal({
+	open,
+	align = "start",
+	getAnchor,
+	panelRef,
+	children,
+}: PopoverMenuPortalProps) {
+	const style = useAnchoredPlacement(panelRef, open, align, getAnchor);
+	if (!open) return null;
+	return createPortal(
+		<div style={style ?? { position: "fixed", visibility: "hidden" }}>
+			{children}
+		</div>,
+		document.body,
+	);
+}
+
 export interface PopoverMenuItem {
 	/** Stable key, also the accessible text of the row. */
 	key: string;
@@ -11,6 +142,83 @@ export interface PopoverMenuItem {
 	onSelect: () => void;
 }
 
+export interface PopoverMenuPanelProps {
+	label?: string;
+	children: ReactNode;
+	className?: string;
+	ref?: Ref<HTMLDivElement>;
+	onKeyDown?: (event: React.KeyboardEvent<HTMLDivElement>) => void;
+	"data-testid"?: string;
+}
+
+/**
+ * The menu itself, without a trigger: the surface, the scrolling and the
+ * rounding every dropdown in the kit shares. A menu that hangs off a button
+ * gets it through {@link PopoverMenu}; one anchored to something else — the
+ * misspelt word under the pointer — positions this and keeps the same chrome.
+ */
+export function PopoverMenuPanel({
+	label,
+	children,
+	className,
+	ref,
+	onKeyDown,
+	"data-testid": testId,
+}: PopoverMenuPanelProps) {
+	return (
+		<div
+			ref={ref}
+			role="menu"
+			aria-label={label}
+			tabIndex={-1}
+			onKeyDown={onKeyDown}
+			data-testid={testId}
+			className={cn(
+				"z-50 flex max-h-[60dvh] min-w-44 flex-col overflow-y-auto overscroll-contain rounded-md border border-line bg-surface py-1 shadow-lg outline-none",
+				className,
+			)}
+		>
+			{children}
+		</div>
+	);
+}
+
+export interface PopoverMenuRowProps {
+	label: string;
+	icon?: ReactNode;
+	onSelect: () => void;
+	className?: string;
+	lang?: string;
+	"data-testid"?: string;
+}
+
+/** One selectable row of a menu panel, at the kit's touch height. */
+export function PopoverMenuRow({
+	label,
+	icon,
+	onSelect,
+	className,
+	lang,
+	"data-testid": testId,
+}: PopoverMenuRowProps) {
+	return (
+		<button
+			type="button"
+			role="menuitem"
+			lang={lang}
+			onClick={onSelect}
+			data-testid={testId}
+			className={cn(
+				"flex min-h-11 items-center gap-3 px-4 py-2.5 text-left text-sm text-fg transition-colors hover:bg-surface-sunken",
+				className,
+			)}
+		>
+			{icon && <span className="shrink-0 text-fg-subtle">{icon}</span>}
+			{label}
+		</button>
+	);
+}
+
 export interface PopoverMenuProps {
 	/** Accessible label for the trigger button. */
 	triggerLabel: string;
@@ -65,16 +273,18 @@ export function PopoverMenu({
 }: PopoverMenuProps) {
 	const [open, setOpen] = useState(false);
 	const containerRef = useRef<HTMLDivElement>(null);
+	const panelRef = useRef<HTMLDivElement>(null);
 
 	useEffect(() => {
 		if (!open) return;
 		const onPointer = (event: MouseEvent) => {
+			const target = event.target as Node;
 			if (
-				containerRef.current &&
-				!containerRef.current.contains(event.target as Node)
-			) {
-				setOpen(false);
-			}
+				containerRef.current?.contains(target) ||
+				panelRef.current?.contains(target)
+			)
+				return;
+			setOpen(false);
 		};
 		const onKey = (event: KeyboardEvent) => {
 			if (event.key === "Escape") setOpen(false);
@@ -108,34 +318,27 @@ export function PopoverMenu({
 			>
 				{triggerText}
 			</Button>
-			{open && (
-				<div
-					role="menu"
-					className={cn(
-						"absolute top-full z-50 mt-1 flex max-h-[60dvh] min-w-44 flex-col overflow-y-auto overscroll-contain rounded-md border border-line bg-surface py-1 shadow-lg",
-						align === "end" ? "right-0" : "left-0",
-					)}
-				>
+			<PopoverMenuPortal
+				open={open}
+				align={align}
+				panelRef={panelRef}
+				getAnchor={() => containerRef.current?.getBoundingClientRect() ?? null}
+			>
+				<PopoverMenuPanel ref={panelRef}>
 					{items.map((item) => (
-						<button
+						<PopoverMenuRow
 							key={item.key}
-							type="button"
-							role="menuitem"
-							onClick={() => {
+							label={item.label}
+							icon={item.icon}
+							onSelect={() => {
 								setOpen(false);
 								item.onSelect();
 							}}
-							className="flex min-h-11 items-center gap-3 px-4 py-2.5 text-left text-sm text-fg transition-colors hover:bg-surface-sunken"
-						>
-							{item.icon && (
-								<span className="shrink-0 text-fg-subtle">{item.icon}</span>
-							)}
-							{item.label}
-						</button>
+						/>
 					))}
 					{children}
-				</div>
-			)}
+				</PopoverMenuPanel>
+			</PopoverMenuPortal>
 		</div>
 	);
 }

package/src/components/pull-to-refresh.tsx

@@ -1,7 +1,7 @@
 import type { ReactElement } from "react";
-import { useEffect, useState } from "react";
 import ReactPullToRefresh from "react-simple-pull-to-refresh";
 import { DESKTOP_MEDIA_QUERY } from "../lib/layout-breakpoints.js";
+import { useMatchMedia } from "../lib/use-match-media.js";
 
 export interface PullToRefreshProps {
 	children: ReactElement;
@@ -9,24 +9,6 @@ export interface PullToRefreshProps {
 	isRefreshing?: boolean;
 }
 
-const useMatchMedia = (query: string): boolean => {
-	const [matches, setMatches] = useState(() => {
-		if (typeof window === "undefined" || !window.matchMedia) return false;
-		return window.matchMedia(query).matches;
-	});
-
-	useEffect(() => {
-		if (typeof window === "undefined" || !window.matchMedia) return;
-		const mql = window.matchMedia(query);
-		setMatches(mql.matches);
-		const handler = (event: MediaQueryListEvent) => setMatches(event.matches);
-		mql.addEventListener("change", handler);
-		return () => mql.removeEventListener("change", handler);
-	}, [query]);
-
-	return matches;
-};
-
 /**
  * Wraps a scrollable list with a pull-to-refresh gesture on mobile. Below the
  * desktop breakpoint (Tailwind `lg`) a downward pull at the top of the list

package/src/components/rich-text-correction-menu.tsx

@@ -0,0 +1,220 @@
+import { BookPlus, EyeOff } from "lucide-react";
+import { useEffect, useRef } from "react";
+import { DESKTOP_MEDIA_QUERY } from "../lib/layout-breakpoints.js";
+import { useRovingFocus } from "../lib/roving-focus.js";
+import { useMatchMedia } from "../lib/use-match-media.js";
+import { BottomSheet } from "./bottom-sheet.js";
+import {
+	type PopoverMenuAnchor,
+	PopoverMenuPanel,
+	PopoverMenuPortal,
+	PopoverMenuRow,
+} from "./popover-menu.js";
+
+const SKELETON_WIDTHS = ["w-28", "w-20", "w-24"];
+
+export type CorrectionMenuAnchor = PopoverMenuAnchor;
+
+export interface RichTextCorrectionMenuProps {
+	word: string;
+	/** Null while the checker is still answering. */
+	suggestions: readonly string[] | null;
+	/** What the checker said when it could not answer. */
+	failure: string | null;
+	anchor: CorrectionMenuAnchor;
+	language: string;
+	onReplace: (suggestion: string) => void;
+	onIgnore: () => void;
+	/** Rendered only when the mount carries somewhere to put the word. */
+	onAddWord?: () => void;
+	/**
+	 * `returnFocus` is false when the writer's own click is already on its way
+	 * somewhere else, and taking the caret back would fight it.
+	 */
+	onDismiss: (returnFocus: boolean) => void;
+}
+
+const CorrectionRows = ({
+	word,
+	suggestions,
+	failure,
+	language,
+	onReplace,
+	onIgnore,
+	onAddWord,
+}: Omit<RichTextCorrectionMenuProps, "anchor" | "onDismiss">) => (
+	<>
+		<p
+			lang={language}
+			data-testid="spell-word"
+			className="px-4 pb-1 pt-1.5 text-xs font-medium text-fg-subtle"
+		>
+			{word}
+		</p>
+		{suggestions === null && failure === null
+			? SKELETON_WIDTHS.map((width) => (
+					<div
+						key={width}
+						aria-hidden="true"
+						data-testid="spell-suggestion-skeleton"
+						className="flex min-h-11 items-center px-4 py-2.5"
+					>
+						<span
+							className={`h-3 animate-pulse rounded bg-surface-sunken ${width}`}
+						/>
+					</div>
+				))
+			: null}
+		{failure !== null && (
+			<p
+				role="alert"
+				data-testid="spell-suggestions-failed"
+				className="px-4 py-2 text-sm text-danger"
+			>
+				No suggestions came back: {failure}
+			</p>
+		)}
+		{suggestions?.length === 0 && (
+			<p
+				data-testid="spell-no-suggestions"
+				className="px-4 py-2 text-sm text-fg-muted"
+			>
+				No suggestions for this word.
+			</p>
+		)}
+		{suggestions?.map((suggestion) => (
+			<PopoverMenuRow
+				key={suggestion}
+				label={suggestion}
+				lang={language}
+				data-testid="spell-suggestion"
+				className="font-medium"
+				onSelect={() => onReplace(suggestion)}
+			/>
+		))}
+		<hr className="my-1 border-line" />
+		<PopoverMenuRow
+			label="Ignore for now"
+			icon={<EyeOff className="size-4" />}
+			data-testid="spell-ignore"
+			onSelect={onIgnore}
+		/>
+		{onAddWord && (
+			<PopoverMenuRow
+				label="Add to dictionary"
+				icon={<BookPlus className="size-4" />}
+				data-testid="spell-add-word"
+				onSelect={onAddWord}
+			/>
+		)}
+	</>
+);
+
+/**
+ * The corrections offered for one misspelt word. The menu is up before the
+ * checker has answered — skeleton rows stand where the suggestions will be —
+ * and it never goes quiet: a request that failed says so where the suggestions
+ * would have been, and ignoring the word stays reachable either way.
+ *
+ * Below the desktop gate the same rows are a sheet, because a popover anchored
+ * to a word sits under the thumb that opened it.
+ */
+export const RichTextCorrectionMenu = ({
+	anchor,
+	onDismiss,
+	...rows
+}: RichTextCorrectionMenuProps) => {
+	const desktop = useMatchMedia(DESKTOP_MEDIA_QUERY);
+	const panelRef = useRef<HTMLDivElement>(null);
+
+	useRovingFocus({ containerRef: panelRef, itemSelector: '[role="menuitem"]' });
+
+	// The menu takes focus as it opens, so Escape and the arrow keys have
+	// somewhere to land rather than staying behind in the message.
+	useEffect(() => {
+		panelRef.current?.focus();
+	}, []);
+
+	// A press rather than a click, and a pointer press rather than a mouse one:
+	// the tap that opened this menu is followed by the browser's compatibility
+	// mouse events, which a `mousedown` listener reads as a press somewhere else
+	// and closes the menu on the way up.
+	//
+	// Escape is caught here too, at the document rather than the panel: the
+	// panel takes focus on mount so the panel's own `onKeyDown` ordinarily
+	// gets there first and this one never fires (its `stopPropagation` keeps
+	// the keydown from reaching here), but a focus call that lands a beat
+	// later than the browser is ready for is not something to depend on —
+	// this is what actually closes the menu when that happens.
+	useEffect(() => {
+		if (!desktop) return;
+		const onPointer = (event: Event) => {
+			if (panelRef.current?.contains(event.target as Node)) return;
+			onDismiss(false);
+		};
+		const onDocumentKeyDown = (event: KeyboardEvent) => {
+			if (event.key !== "Escape") return;
+			onDismiss(true);
+		};
+		document.addEventListener("pointerdown", onPointer);
+		document.addEventListener("keydown", onDocumentKeyDown);
+		return () => {
+			document.removeEventListener("pointerdown", onPointer);
+			document.removeEventListener("keydown", onDocumentKeyDown);
+		};
+	}, [desktop, onDismiss]);
+
+	/**
+	 * Escape closes it, and so does Tab: a menu is not a dialog, and the repo
+	 * traps focus nowhere. Letting Tab walk on would put the caret behind an
+	 * open sheet, so the menu goes first and the message has the focus back
+	 * before the next stop.
+	 */
+	const onKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+		if (event.key !== "Escape" && event.key !== "Tab") return;
+		event.preventDefault();
+		event.stopPropagation();
+		onDismiss(true);
+	};
+
+	if (!desktop) {
+		return (
+			<BottomSheet
+				open
+				onClose={() => onDismiss(true)}
+				dismissLabel="Close corrections"
+			>
+				<div
+					ref={panelRef}
+					role="menu"
+					aria-label={`Corrections for ${rows.word}`}
+					tabIndex={-1}
+					onKeyDown={onKeyDown}
+					data-testid="spell-menu"
+					className="flex flex-col overflow-y-auto pb-4 outline-none"
+				>
+					<CorrectionRows {...rows} />
+				</div>
+			</BottomSheet>
+		);
+	}
+
+	return (
+		<PopoverMenuPortal
+			open
+			align="start"
+			panelRef={panelRef}
+			getAnchor={() => anchor}
+		>
+			<PopoverMenuPanel
+				ref={panelRef}
+				label={`Corrections for ${rows.word}`}
+				onKeyDown={onKeyDown}
+				data-testid="spell-menu"
+				className="max-w-64"
+			>
+				<CorrectionRows {...rows} />
+			</PopoverMenuPanel>
+		</PopoverMenuPortal>
+	);
+};