@remit/ui 0.0.142 → 0.0.143

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.142",
+  "version": "0.0.143",
   "type": "module",
   "files": [
     "src"

package/src/components/compose-address-field.stories.tsx

@@ -1,9 +1,11 @@
 import type { Meta, StoryObj } from "@storybook/react";
-import { useState } from "react";
+import { useRef, useState } from "react";
 import { expect, userEvent, waitFor, within } from "storybook/test";
 import {
 	type AddressEntry,
 	ComposeAddressField,
+	type ComposeAddressFieldHandle,
+	type ParsedAddressInput,
 } from "./compose-address-field.js";
 
 const KNOWN: AddressEntry[] = [
@@ -114,6 +116,198 @@ export const IncompleteAddressIsNotTaken: Story = {
 	},
 };
 
+const NO_RECIPIENT_REFUSAL = "Add a To address before sending.";
+
+const notAnAddress = (text: string) =>
+	`To holds "${text}", which is not an address.`;
+
+/**
+ * A press elsewhere is what an address typed and left in the field has to
+ * survive, and this is the shape the composer holds the field in for it.
+ *
+ * The press reads the field through `commitPending`, in the same tick, rather
+ * than the list the field has got round to committing — the blur timer is still
+ * 150 ms away from that. What the button says before it is pressed comes from
+ * `onPendingChange`, so neither refusal ever stands while an address is on
+ * screen, and text that is not an address stops the send instead of leaving
+ * with it.
+ */
+const SendHarness = ({ initial = [] }: { initial?: AddressEntry[] }) => {
+	const [addresses, setAddresses] = useState<AddressEntry[]>(initial);
+	const [pending, setPending] = useState<ParsedAddressInput>({
+		entries: [],
+		unparsed: "",
+	});
+	const [sentTo, setSentTo] = useState<string[] | undefined>(undefined);
+	const [refusal, setRefusal] = useState<string | undefined>(undefined);
+	const field = useRef<ComposeAddressFieldHandle>(null);
+
+	const refuse = (committed: ParsedAddressInput["unparsed"], count: number) => {
+		if (committed.trim()) return notAnAddress(committed.trim());
+		if (count === 0) return NO_RECIPIENT_REFUSAL;
+		return undefined;
+	};
+
+	return (
+		<div className="w-[520px]">
+			<ComposeAddressField
+				label="To"
+				addresses={addresses}
+				onChange={setAddresses}
+				placeholder="Recipients"
+				onPendingChange={setPending}
+				ref={field}
+			/>
+			<button
+				type="button"
+				onClick={() => {
+					const beforePress = refuse(
+						pending.unparsed,
+						addresses.length + pending.entries.length,
+					);
+					if (beforePress !== undefined) {
+						setRefusal(beforePress);
+						return;
+					}
+					const committed = field.current?.commitPending();
+					const recipients = committed?.addresses ?? addresses;
+					const onPress = refuse(committed?.unparsed ?? "", recipients.length);
+					if (onPress !== undefined) {
+						setRefusal(onPress);
+						return;
+					}
+					setSentTo(recipients.map((recipient) => recipient.email));
+				}}
+			>
+				Send
+			</button>
+			{sentTo !== undefined && <p data-testid="sent-to">{sentTo.join(", ")}</p>}
+			{refusal !== undefined && <p data-testid="refusal">{refusal}</p>}
+		</div>
+	);
+};
+
+export const SendTakesTheAddressStillInTheField: Story = {
+	render: () => <SendHarness />,
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await userEvent.type(
+			canvas.getByLabelText("To:"),
+			"typed@northwind.example",
+		);
+		await userEvent.click(canvas.getByRole("button", { name: "Send" }));
+		await expect(canvas.getByTestId("sent-to")).toHaveTextContent(
+			"typed@northwind.example",
+		);
+		await expect(canvas.queryByTestId("refusal")).not.toBeInTheDocument();
+	},
+};
+
+/** With nothing typed and no chip there is nothing to send to, and it says so. */
+export const SendRefusesAnEmptyField: Story = {
+	render: () => <SendHarness />,
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await userEvent.click(canvas.getByRole("button", { name: "Send" }));
+		await expect(canvas.getByTestId("refusal")).toHaveTextContent(
+			NO_RECIPIENT_REFUSAL,
+		);
+	},
+};
+
+export const SendTakesTheAddressAfterAChip: Story = {
+	render: () => (
+		<SendHarness initial={[{ email: "chipped@northwind.example" }]} />
+	),
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await userEvent.type(
+			canvas.getByLabelText("To:"),
+			"typed@northwind.example",
+		);
+		await userEvent.click(canvas.getByRole("button", { name: "Send" }));
+		await expect(canvas.getByTestId("sent-to")).toHaveTextContent(
+			"chipped@northwind.example, typed@northwind.example",
+		);
+	},
+};
+
+/** A pasted list arrives in one onChange and never sees the comma keydown. */
+export const SendTakesAPastedList: Story = {
+	render: () => <SendHarness />,
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await userEvent.click(canvas.getByLabelText("To:"));
+		await userEvent.paste("alice@northwind.example, bob@northwind.example");
+		await userEvent.click(canvas.getByRole("button", { name: "Send" }));
+		await expect(canvas.getByTestId("sent-to")).toHaveTextContent(
+			"alice@northwind.example, bob@northwind.example",
+		);
+	},
+};
+
+/**
+ * Text that is not an address stops the send and is quoted back. Going ahead
+ * would deliver the message to everyone but the person that text was for, and
+ * the composer closing on it would take the text away unread.
+ */
+export const SendRefusesTextThatIsNotAnAddress: Story = {
+	render: () => (
+		<SendHarness initial={[{ email: "chipped@northwind.example" }]} />
+	),
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		const input = canvas.getByLabelText<HTMLInputElement>("To:");
+		await userEvent.type(input, "alice@northwind");
+		await userEvent.click(canvas.getByRole("button", { name: "Send" }));
+
+		await expect(canvas.getByTestId("refusal")).toHaveTextContent(
+			notAnAddress("alice@northwind"),
+		);
+		await expect(canvas.queryByTestId("sent-to")).not.toBeInTheDocument();
+		await expect(input).toHaveValue("alice@northwind");
+	},
+};
+
+/**
+ * Candidates a complete address is a substring of, so the typed text is itself
+ * committable and the suggestion picked is somebody else. That is what makes
+ * the story below a claim about the blur timer rather than about deduplication.
+ */
+const NEARBY: AddressEntry[] = [
+	{ email: "beta@northwind.example", displayName: "Beta Team" },
+	{ email: "a@northwind.example.org", displayName: "Alpha Team" },
+];
+
+/**
+ * The other press the field has to survive, and the reason the blur commit is
+ * still on a timer: a click travelling towards a suggestion must not be answered
+ * by the typed text becoming a chip and the list going with it.
+ */
+export const SuggestionSurvivesTheBlurItCauses: Story = {
+	render: () => <Harness candidates={NEARBY} />,
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		const input = canvas.getByLabelText<HTMLInputElement>("To:");
+		await userEvent.type(input, "a@northwind.example");
+		const list = await canvas.findByRole("listbox");
+		await userEvent.click(within(list).getByText("Beta Team"));
+
+		await expect(canvas.getByText("Beta Team")).toBeVisible();
+		await expect(input).toHaveValue("");
+
+		// Past the blur timer, not merely past the click: the commit it scheduled
+		// is cancelled, so the address that was typed never becomes a second chip.
+		await new Promise((resolve) => setTimeout(resolve, 400));
+		await expect(
+			canvas.getAllByRole("button", { name: /^Remove / }),
+		).toHaveLength(1);
+		await expect(
+			canvas.queryByText("a@northwind.example"),
+		).not.toBeInTheDocument();
+	},
+};
+
 export const BackspaceRemovesTheLastChip: Story = {
 	render: () => (
 		<Harness

package/src/components/compose-address-field.tsx

@@ -1,11 +1,50 @@
-import { useCallback, useMemo, useRef, useState } from "react";
+import type { Ref } from "react";
+import {
+	useCallback,
+	useEffect,
+	useImperativeHandle,
+	useMemo,
+	useRef,
+	useState,
+} from "react";
+import {
+	type AddressEntry,
+	type ParsedAddressInput,
+	parseAddressInput,
+} from "../lib/parse-address-input.js";
 import { useSuggestList } from "../lib/use-suggest-list.js";
 import { AddressTag } from "./address-tag.js";
 import { type Suggestion, SuggestList } from "./suggest-list.js";
 
-export interface AddressEntry {
-	email: string;
-	displayName?: string;
+export type { AddressEntry, ParsedAddressInput };
+
+/** What the field holds, after a commit. */
+export interface ComposeAddressCommit {
+	/** Every address the field now has, the ones just taken included. */
+	addresses: AddressEntry[];
+	/** What was left in the field because it is not an address. */
+	unparsed: string;
+}
+
+/**
+ * What a caller acting on the field's contents holds it by.
+ *
+ * The field commits on blur behind a timer, so that a click travelling towards a
+ * suggestion is not answered by the list disappearing under it. Anything that
+ * acts on the recipients — sending — is a press that blurs the field, and so
+ * lands inside that window and reads the list as it stood before the last
+ * address was typed. `commitPending` closes it: it takes what is in the field
+ * and hands back the list including it, in the same tick as the press.
+ */
+export interface ComposeAddressFieldHandle {
+	/**
+	 * Take the addresses the field is holding and report what it holds after.
+	 * Anything that is not an address stays in the field and is named in
+	 * `unparsed`, for the caller to refuse on rather than send without.
+	 */
+	commitPending: () => ComposeAddressCommit;
+	/** Drop what is typed and not committed — the field's share of a new document. */
+	clearPending: () => void;
 }
 
 export interface ComposeAddressFieldProps {
@@ -17,28 +56,19 @@ export interface ComposeAddressFieldProps {
 	suggestions?: readonly AddressEntry[];
 	/** The current text, reported so the caller can look candidates up. */
 	onQueryChange?: (query: string) => void;
+	/**
+	 * What the field is holding but has not committed, so a caller whose own
+	 * state turns on having a recipient counts what is on screen.
+	 */
+	onPendingChange?: (pending: ParsedAddressInput) => void;
+	ref?: Ref<ComposeAddressFieldHandle>;
 }
 
 /** Beyond Enter, the keys that take the highlighted suggestion in a chips field. */
 const ACCEPT_KEYS = ["Tab", ","] as const;
 
-const isValidEmail = (value: string): boolean =>
-	/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim());
-
-const parseEmailInput = (value: string): AddressEntry | undefined => {
-	const trimmed = value.trim();
-	if (!trimmed) return undefined;
-
-	const angleMatch = trimmed.match(/^(.+?)\s*<([^>]+)>$/);
-	if (angleMatch) {
-		const displayName = angleMatch[1].trim();
-		const email = angleMatch[2].trim();
-		if (isValidEmail(email)) return { email, displayName };
-	}
-
-	if (isValidEmail(trimmed)) return { email: trimmed };
-	return undefined;
-};
+/** How long a click has to reach a suggestion before the blur commits the field. */
+const BLUR_COMMIT_MS = 150;
 
 export const ComposeAddressField = ({
 	label,
@@ -47,24 +77,49 @@ export const ComposeAddressField = ({
 	placeholder,
 	suggestions = [],
 	onQueryChange,
+	onPendingChange,
+	ref,
 }: ComposeAddressFieldProps) => {
 	const [inputValue, setInputValue] = useState("");
 	const inputRef = useRef<HTMLInputElement>(null);
 
+	const pending = useMemo(() => parseAddressInput(inputValue), [inputValue]);
+	useEffect(() => {
+		onPendingChange?.(pending);
+	}, [pending, onPendingChange]);
+
+	const blurCommitRef = useRef<ReturnType<typeof setTimeout> | undefined>(
+		undefined,
+	);
+	const cancelBlurCommit = useCallback(() => {
+		if (blurCommitRef.current === undefined) return;
+		clearTimeout(blurCommitRef.current);
+		blurCommitRef.current = undefined;
+	}, []);
+	useEffect(() => cancelBlurCommit, [cancelBlurCommit]);
+
 	const existingEmails = new Set(addresses.map((a) => a.email.toLowerCase()));
 	const filteredSuggestions =
 		inputValue.length >= 2
 			? suggestions.filter((s) => !existingEmails.has(s.email.toLowerCase()))
 			: [];
 
+	const setInput = useCallback(
+		(next: string) => {
+			setInputValue(next);
+			onQueryChange?.(next);
+		},
+		[onQueryChange],
+	);
+
 	const addAddress = useCallback(
 		(entry: AddressEntry) => {
+			cancelBlurCommit();
 			if (existingEmails.has(entry.email.toLowerCase())) return;
 			onChange([...addresses, entry]);
-			setInputValue("");
-			onQueryChange?.("");
+			setInput("");
 		},
-		[addresses, existingEmails, onChange, onQueryChange],
+		[addresses, existingEmails, onChange, setInput, cancelBlurCommit],
 	);
 
 	const removeAddress = useCallback(
@@ -82,12 +137,49 @@ export const ComposeAddressField = ({
 		[addAddress],
 	);
 
-	const commitInput = useCallback(() => {
-		const entry = parseEmailInput(inputValue);
-		if (entry) {
-			addAddress(entry);
+	const commitPending = useCallback((): ComposeAddressCommit => {
+		cancelBlurCommit();
+		if (pending.entries.length === 0) {
+			return { addresses, unparsed: pending.unparsed };
+		}
+
+		const taken = new Set(existingEmails);
+		const next = [...addresses];
+		for (const entry of pending.entries) {
+			const key = entry.email.toLowerCase();
+			if (taken.has(key)) continue;
+			taken.add(key);
+			next.push(entry);
 		}
-	}, [inputValue, addAddress]);
+
+		onChange(next);
+		setInput(pending.unparsed);
+		return { addresses: next, unparsed: pending.unparsed };
+	}, [
+		pending,
+		addresses,
+		existingEmails,
+		onChange,
+		setInput,
+		cancelBlurCommit,
+	]);
+
+	const clearPending = useCallback(() => {
+		cancelBlurCommit();
+		setInput("");
+	}, [setInput, cancelBlurCommit]);
+
+	useImperativeHandle(ref, () => ({ commitPending, clearPending }), [
+		commitPending,
+		clearPending,
+	]);
+
+	// A blur that has already been answered — by a send committing the field in
+	// the same press — must not commit again off the value it saw on the way out.
+	const latestCommitRef = useRef(commitPending);
+	useEffect(() => {
+		latestCommitRef.current = commitPending;
+	}, [commitPending]);
 
 	// The open state, the highlight, and the arrow/Enter/Escape handling are the
 	// app's one typeahead behaviour, shared with the filter-rule value field.
@@ -119,7 +211,7 @@ export const ComposeAddressField = ({
 			if (e.key === "Enter" || e.key === "Tab" || e.key === ",") {
 				if (inputValue.trim()) {
 					e.preventDefault();
-					commitInput();
+					commitPending();
 				}
 			}
 		},
@@ -128,16 +220,21 @@ export const ComposeAddressField = ({
 			addresses.length,
 			removeAddress,
 			suggest.handleKeyDown,
-			commitInput,
+			commitPending,
 		],
 	);
 
+	// The delay is what keeps a click on a suggestion alive: the press blurs the
+	// input before it lands, and committing straight away would take the list out
+	// from under the pointer.
 	const handleBlur = useCallback(() => {
-		setTimeout(() => {
-			commitInput();
+		cancelBlurCommit();
+		blurCommitRef.current = setTimeout(() => {
+			blurCommitRef.current = undefined;
+			latestCommitRef.current();
 			suggest.dismiss();
-		}, 150);
-	}, [commitInput, suggest.dismiss]);
+		}, BLUR_COMMIT_MS);
+	}, [cancelBlurCommit, suggest.dismiss]);
 
 	return (
 		<div className="relative" data-address-field={label}>
@@ -171,8 +268,7 @@ export const ComposeAddressField = ({
 						value={inputValue}
 						onChange={(e) => {
 							suggest.reopen();
-							setInputValue(e.target.value);
-							onQueryChange?.(e.target.value);
+							setInput(e.target.value);
 						}}
 						onKeyDown={handleKeyDown}
 						onBlur={handleBlur}

package/src/index.ts

@@ -171,8 +171,11 @@ export {
 } from "./components/compose-action-bar.js";
 export {
 	type AddressEntry,
+	type ComposeAddressCommit,
 	ComposeAddressField,
+	type ComposeAddressFieldHandle,
 	type ComposeAddressFieldProps,
+	type ParsedAddressInput,
 } from "./components/compose-address-field.js";
 export { ComposeBodySkeleton } from "./components/compose-body-skeleton.js";
 export {

package/src/lib/parse-address-input.test.ts

@@ -0,0 +1,79 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { parseAddressInput } from "./parse-address-input.js";
+
+describe("parseAddressInput", () => {
+	it("reads a bare address", () => {
+		assert.deepEqual(parseAddressInput("ada@example.com"), {
+			entries: [{ email: "ada@example.com" }],
+			unparsed: "",
+		});
+	});
+
+	it("reads a display name and the address it wraps", () => {
+		assert.deepEqual(parseAddressInput("Ada Lovelace <ada@example.com>"), {
+			entries: [{ email: "ada@example.com", displayName: "Ada Lovelace" }],
+			unparsed: "",
+		});
+	});
+
+	it("reads a pasted list", () => {
+		assert.deepEqual(
+			parseAddressInput("alice@example.com, bob@example.com").entries,
+			[{ email: "alice@example.com" }, { email: "bob@example.com" }],
+		);
+	});
+
+	it("takes a semicolon as a separator too", () => {
+		assert.equal(
+			parseAddressInput("alice@example.com; bob@example.com").entries.length,
+			2,
+		);
+	});
+
+	it("keeps a quoted display name whole", () => {
+		assert.deepEqual(parseAddressInput('"Hopper, Grace" <grace@example.com>'), {
+			entries: [{ email: "grace@example.com", displayName: "Hopper, Grace" }],
+			unparsed: "",
+		});
+	});
+
+	it("keeps what is not an address rather than dropping it", () => {
+		assert.deepEqual(parseAddressInput("not-an-address"), {
+			entries: [],
+			unparsed: "not-an-address",
+		});
+	});
+
+	it("separates the addresses in a list from what is not one", () => {
+		assert.deepEqual(parseAddressInput("bob@example.com, alice@example"), {
+			entries: [{ email: "bob@example.com" }],
+			unparsed: "alice@example",
+		});
+	});
+
+	it("reports every leftover, not only the first", () => {
+		assert.equal(
+			parseAddressInput("one, bob@example.com, two").unparsed,
+			"one, two",
+		);
+	});
+
+	it("reads empty text as holding nothing", () => {
+		assert.deepEqual(parseAddressInput("   "), { entries: [], unparsed: "" });
+	});
+
+	it("ignores the separators an empty slot leaves behind", () => {
+		assert.deepEqual(parseAddressInput("ada@example.com,,"), {
+			entries: [{ email: "ada@example.com" }],
+			unparsed: "",
+		});
+	});
+
+	it("rejects an address with no top-level domain", () => {
+		assert.deepEqual(parseAddressInput("ada@example"), {
+			entries: [],
+			unparsed: "ada@example",
+		});
+	});
+});

package/src/lib/parse-address-input.ts

@@ -0,0 +1,81 @@
+/**
+ * What a recipient field is holding in its text input, read as addresses.
+ *
+ * A field takes one address at a time when it is typed, and a whole list when
+ * one is pasted, so what is in it is a list either way. Anything in that list
+ * that is not an address is kept rather than dropped: it is what the reader
+ * typed, and losing it silently is how a message goes out to fewer people than
+ * it was addressed to.
+ */
+
+export interface AddressEntry {
+	email: string;
+	displayName?: string;
+}
+
+export interface ParsedAddressInput {
+	/** The addresses the text names, in the order it names them. */
+	entries: AddressEntry[];
+	/** The parts that are not addresses, rejoined. Empty when there are none. */
+	unparsed: string;
+}
+
+const isValidEmail = (value: string): boolean =>
+	/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value.trim());
+
+const parseOne = (value: string): AddressEntry | undefined => {
+	const trimmed = value.trim();
+	if (!trimmed) return undefined;
+
+	const angleMatch = trimmed.match(/^(.+?)\s*<([^>]+)>$/);
+	if (angleMatch) {
+		const displayName = angleMatch[1].trim().replace(/^"(.*)"$/, "$1");
+		const email = angleMatch[2].trim();
+		if (isValidEmail(email)) return { email, displayName };
+	}
+
+	if (isValidEmail(trimmed)) return { email: trimmed };
+	return undefined;
+};
+
+/**
+ * Split on the separators a mail client writes between addresses, ignoring the
+ * ones inside a quoted display name or an angle-bracketed address — `"Hopper,
+ * Grace" <grace@example.com>` is one address, not two.
+ */
+const splitAddresses = (value: string): string[] => {
+	const parts: string[] = [];
+	let current = "";
+	let quoted = false;
+	let angled = false;
+
+	for (const char of value) {
+		if (char === '"') quoted = !quoted;
+		if (char === "<") angled = true;
+		if (char === ">") angled = false;
+		if ((char === "," || char === ";") && !quoted && !angled) {
+			parts.push(current);
+			current = "";
+			continue;
+		}
+		current += char;
+	}
+	parts.push(current);
+	return parts;
+};
+
+export const parseAddressInput = (value: string): ParsedAddressInput => {
+	const entries: AddressEntry[] = [];
+	const leftovers: string[] = [];
+
+	for (const part of splitAddresses(value)) {
+		const entry = parseOne(part);
+		if (entry) {
+			entries.push(entry);
+			continue;
+		}
+		if (part.trim()) leftovers.push(part.trim());
+	}
+
+	return { entries, unparsed: leftovers.join(", ") };
+};