@remit/ui 0.0.137 → 0.0.139

package/src/components/role-appointment-list.tsx

@@ -1,5 +1,6 @@
 import { Check, Folder } from "lucide-react";
-import { useState } from "react";
+import { useId, useRef, useState } from "react";
+import { Banner } from "./banner.js";
 import { Button } from "./button.js";
 import {
 	canonicalRoleLabel,
@@ -38,20 +39,56 @@ export interface CandidateFolder {
 	messageCount: number;
 }
 
+/** Where a role's answer came from (#887). */
+export type RoleAppointmentSource =
+	| "Appointed"
+	| "Flagged"
+	| "Reserved"
+	| "Proposed"
+	| "Stale"
+	| "None";
+
+export interface RoleAppointment {
+	/** The mailbox the role resolves to, or null when it resolves to none. */
+	mailboxId: string | null;
+	source: RoleAppointmentSource;
+	/** `Stale` only: the path the folder the user chose last had. */
+	staleFolderPath?: string;
+}
+
 /** Empty <option> value standing for "no folder appointed". */
 const NONE = "";
 
+const UNRESOLVED: RoleAppointment = { mailboxId: null, source: "None" };
+
 /** Picker option text: `Concepten · 340 msgs`. */
 function folderOptionLabel(folder: CandidateFolder): string {
 	const noun = folder.messageCount === 1 ? "msg" : "msgs";
 	return `${providerLeaf(folder.providerPath)} · ${folder.messageCount} ${noun}`;
 }
 
+const messages = (count: number): string =>
+	`${count} ${count === 1 ? "message" : "messages"}`;
+
+/**
+ * The provenance clause in front of the path and count. Read the source rather
+ * than inferring it from the shape of the row: only `Appointed` means a person
+ * decided, and `Proposed` is a name match nobody confirmed.
+ */
+const provenanceClause = (
+	source: RoleAppointmentSource,
+	roleLabel: string,
+): string => {
+	if (source === "Appointed") return "Chosen by you";
+	if (source === "Flagged") return `The mail server marks it as ${roleLabel}`;
+	if (source === "Reserved") return "The account's own INBOX";
+	return "Matched by name, not confirmed";
+};
+
 interface RoleAppointmentRowProps {
 	role: FolderRole;
 	folders: readonly CandidateFolder[];
-	/** The mailbox appointed to this role, or null when the role is unfilled. */
-	appointedId: string | null;
+	appointment: RoleAppointment;
 	/** Committed display-name override for the appointed folder. */
 	displayName: string;
 	onAppoint: (role: FolderRole, mailboxId: string | null) => void;
@@ -64,21 +101,62 @@ interface RoleAppointmentRowProps {
  * folder that actually holds mail), and — once a folder is appointed — a rename
  * field for its sidebar label. Selecting a folder here clears it from any other
  * role on write; the picker can never produce a duplicate.
+ *
+ * The line under the control says where the row's answer came from, and is
+ * pointed at by the Select's `aria-describedby` so the provenance is announced
+ * with the control that changes it.
  */
 function RoleAppointmentRow({
 	role,
 	folders,
-	appointedId,
+	appointment,
 	displayName,
 	onAppoint,
 	onRename,
 }: RoleAppointmentRowProps) {
 	const [draftName, setDraftName] = useState(displayName);
-	const appointed = folders.find((f) => f.mailboxId === appointedId) ?? null;
+	const selectRef = useRef<HTMLSelectElement>(null);
+	const subtitleId = useId();
+	const { mailboxId, source, staleFolderPath } = appointment;
+	const appointed = folders.find((f) => f.mailboxId === mailboxId) ?? null;
 	const label = canonicalRoleLabel(role);
 	const renameDirty =
 		appointed != null && draftName.trim() !== displayName.trim();
 
+	const subtitle = (() => {
+		if (source === "None") {
+			const needsOne = role === "trash" ? " Deleting mail needs one." : "";
+			return (
+				<span id={subtitleId} className="pl-[7.5rem] text-xs text-fg-muted">
+					{`Not set — pick the folder this account uses for ${label}.${needsOne}`}
+				</span>
+			);
+		}
+		if (source === "Stale" || !appointed) return null;
+		return (
+			<span
+				id={subtitleId}
+				className="truncate pl-[7.5rem] text-2xs text-fg-subtle"
+				title={appointed.providerPath}
+			>
+				{`${provenanceClause(source, label)} · ${appointed.providerPath} · ${messages(appointed.messageCount)}`}
+			</span>
+		);
+	})();
+
+	// Trash is the one role where a broken appointment stops a verb; the others
+	// fall back to a live folder. With no fallback to name, the sentence stops
+	// rather than inventing one.
+	const staleFallback =
+		role === "trash"
+			? " Deleting mail is stopped until you pick another one."
+			: appointed
+				? ` reader is using ${providerLeaf(appointed.providerPath)} instead.`
+				: "";
+	const staleNotice = `The folder you chose for ${label}${
+		staleFolderPath ? ` — ${staleFolderPath} —` : ""
+	} is gone from the mail server.${staleFallback}`;
+
 	return (
 		<div className="flex flex-col gap-1 border-b border-line px-row-inset py-2.5 last:border-b-0">
 			<div className="flex items-center gap-2">
@@ -87,9 +165,15 @@ function RoleAppointmentRow({
 					{label}
 				</span>
 				<Select
+					ref={selectRef}
 					className="w-56 shrink-0"
-					value={appointedId ?? NONE}
+					value={mailboxId ?? NONE}
 					aria-label={`Folder for ${label}`}
+					// Whichever line the row renders — the provenance subtitle or the
+					// stale callout — is the one that explains this control.
+					aria-describedby={
+						subtitle || source === "Stale" ? subtitleId : undefined
+					}
 					onChange={(event) =>
 						onAppoint(
 							role,
@@ -126,14 +210,23 @@ function RoleAppointmentRow({
 					</>
 				)}
 			</div>
-			{appointed && (
-				<span
-					className="truncate pl-[7.5rem] text-2xs text-fg-subtle"
-					title={appointed.providerPath}
-				>
-					{appointed.providerPath} · {appointed.messageCount}{" "}
-					{appointed.messageCount === 1 ? "message" : "messages"}
-				</span>
+			{subtitle}
+			{source === "Stale" && (
+				<Banner tone="warning" variant="soft" className="ml-[7.5rem]">
+					<span className="flex flex-wrap items-center gap-2">
+						<span id={subtitleId} className="flex-1">
+							{staleNotice}
+						</span>
+						<Button
+							variant="secondary"
+							size="sm"
+							className="shrink-0"
+							onClick={() => selectRef.current?.focus()}
+						>
+							Pick a folder
+						</Button>
+					</span>
+				</Banner>
 			)}
 		</div>
 	);
@@ -143,8 +236,8 @@ export interface RoleAppointmentListProps {
 	accountEmail: string;
 	/** Every folder the account exposes (candidates for any role). */
 	folders: readonly CandidateFolder[];
-	/** role → appointed mailboxId. A missing role means "None". */
-	appointments: Readonly<Record<string, string | null>>;
+	/** role → what fills it and where that answer came from. */
+	appointments: Readonly<Record<string, RoleAppointment>>;
 	/** mailboxId → committed display-name override. */
 	displayNames?: Readonly<Record<string, string>>;
 	onAppoint: (role: FolderRole, mailboxId: string | null) => void;
@@ -167,7 +260,9 @@ export function RoleAppointmentList({
 	onRename,
 }: RoleAppointmentListProps) {
 	const appointedIds = new Set(
-		Object.values(appointments).filter((id): id is string => id != null),
+		Object.values(appointments)
+			.map((appointment) => appointment.mailboxId)
+			.filter((id): id is string => id != null),
 	);
 	const leftovers = folders.filter((f) => !appointedIds.has(f.mailboxId));
 
@@ -180,19 +275,25 @@ export function RoleAppointmentList({
 				<p className="text-xs text-fg-muted">
 					Each role points to one folder. Pick the folder that holds the mail —
 					the counts help you tell real folders from empty look-alikes.
-					Appointing a folder here removes it from any other role.
+					Appointing a folder here removes it from any other role. Each row says
+					where its answer came from — your choice, the mail server's own flag,
+					or a name reader matched.
 				</p>
 			</header>
 			<div className="rounded-sm border border-line bg-surface">
 				{APPOINTABLE_ROLES.map((role) => {
-					const appointedId = appointments[role] ?? null;
+					const appointment = appointments[role] ?? UNRESOLVED;
 					return (
 						<RoleAppointmentRow
 							key={role}
 							role={role}
 							folders={folders}
-							appointedId={appointedId}
-							displayName={appointedId ? (displayNames[appointedId] ?? "") : ""}
+							appointment={appointment}
+							displayName={
+								appointment.mailboxId
+									? (displayNames[appointment.mailboxId] ?? "")
+									: ""
+							}
 							onAppoint={onAppoint}
 							onRename={onRename}
 						/>
@@ -214,8 +315,7 @@ export function RoleAppointmentList({
 									{providerLeaf(folder.providerPath)}
 								</span>
 								<span className="ml-auto shrink-0 text-2xs text-fg-subtle">
-									{folder.messageCount}{" "}
-									{folder.messageCount === 1 ? "message" : "messages"}
+									{messages(folder.messageCount)}
 								</span>
 							</li>
 						))}

package/src/components/role-appointment-prompt.render.test.ts

@@ -0,0 +1,240 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import type { FolderTreeNode } from "../lib/folder-tree.js";
+import {
+	RoleAppointmentPrompt,
+	type RoleAppointmentPromptProps,
+	roleAppointmentPromptCopy,
+} from "./role-appointment-prompt.js";
+
+const folders: FolderTreeNode[] = [
+	{ id: "mb-inbox", label: "INBOX", path: "INBOX", messageCount: 4821 },
+	{
+		id: "mb-deleted",
+		label: "Deleted Messages",
+		path: "Deleted Messages",
+		messageCount: 512,
+	},
+	{
+		id: "mb-prullenbak",
+		label: "Prullenbak",
+		path: "Prullenbak",
+		messageCount: 0,
+	},
+];
+
+const noop = () => {};
+
+const render = (props: Partial<RoleAppointmentPromptProps>) =>
+	renderToString(
+		createElement(RoleAppointmentPrompt, {
+			open: true,
+			reason: "none",
+			action: { kind: "delete", count: 12 },
+			folders,
+			delimiter: "/",
+			phase: { kind: "choosing" },
+			onSelect: noop,
+			onConfirm: noop,
+			onCancel: noop,
+			...props,
+		}),
+	);
+
+describe("roleAppointmentPromptCopy", () => {
+	it("says nothing was deleted, and what reader files deletes in", () => {
+		const copy = roleAppointmentPromptCopy("none", {
+			kind: "delete",
+			count: 12,
+		});
+		assert.equal(copy.title, "No folder is set as Trash");
+		assert.equal(
+			copy.description,
+			"Nothing has been deleted. reader files deleted mail in the folder you set as Trash, and this account has none.",
+		);
+		assert.equal(
+			copy.pickerPrompt,
+			"Which folder does this account use for deleted mail?",
+		);
+		assert.equal(copy.confirmLabel, "Set as Trash and delete 12 messages");
+	});
+
+	it("counts one message as one message", () => {
+		const copy = roleAppointmentPromptCopy("none", {
+			kind: "delete",
+			count: 1,
+		});
+		assert.equal(copy.confirmLabel, "Set as Trash and delete 1 message");
+	});
+
+	it("changes the verb, never the folder clause, for Empty Trash", () => {
+		const copy = roleAppointmentPromptCopy("none", { kind: "emptyTrash" });
+		assert.match(copy.description, /^Nothing has been emptied\./);
+		assert.match(copy.description, /and this account has none\.$/);
+		assert.equal(copy.confirmLabel, "Set as Trash and empty it");
+	});
+
+	it("names the folder that vanished", () => {
+		const copy = roleAppointmentPromptCopy(
+			"stale",
+			{ kind: "delete", count: 3 },
+			{ staleFolderLabel: "Prullenbak" },
+		);
+		assert.equal(copy.title, "The Trash folder you chose is gone");
+		assert.equal(
+			copy.description,
+			"Nothing has been deleted. You set Prullenbak as this account's Trash and it is no longer on the mail server — another mail app may have renamed or removed it.",
+		);
+		assert.equal(copy.pickerPrompt, "Which folder should reader use instead?");
+	});
+
+	it("degrades the stale wording when no path was ever recorded", () => {
+		const copy = roleAppointmentPromptCopy("stale", {
+			kind: "delete",
+			count: 3,
+		});
+		assert.equal(
+			copy.description,
+			"Nothing has been deleted. The folder you set as this account's Trash is no longer on the mail server — another mail app may have renamed or removed it.",
+		);
+	});
+
+	it("names the guess and the irreversibility when confirming a guess", () => {
+		const copy = roleAppointmentPromptCopy(
+			"unconfirmed",
+			{ kind: "emptyTrash" },
+			{ trashFolderLabel: "Deleted Messages", selectedCount: 512 },
+		);
+		assert.equal(copy.title, "Confirm this account's Trash folder");
+		assert.equal(
+			copy.description,
+			"Nothing has been emptied. reader files this account's deleted mail in Deleted Messages because of its name — you never chose it, and the mail server doesn't mark it as Trash. Emptying a folder erases everything in it from the mail server, and that cannot be restored.",
+		);
+		assert.equal(
+			copy.pickerPrompt,
+			"Confirm Deleted Messages, or pick the folder this account really uses.",
+		);
+		assert.equal(copy.confirmLabel, "Set as Trash and empty 512 messages");
+	});
+
+	it("falls back to an uncounted confirm when the count is unknown", () => {
+		const copy = roleAppointmentPromptCopy(
+			"unconfirmed",
+			{ kind: "emptyTrash" },
+			{ trashFolderLabel: "Deleted Messages" },
+		);
+		assert.equal(copy.confirmLabel, "Set as Trash and empty it");
+	});
+});
+
+describe("RoleAppointmentPrompt", () => {
+	it("renders nothing while closed", () => {
+		assert.equal(render({ open: false }), "");
+	});
+
+	it("offers a way out that changes nothing, and no confirm until one is picked", () => {
+		const html = render({});
+		assert.match(html, />Cancel</);
+		assert.doesNotMatch(html, /Set as Trash and delete/);
+		assert.doesNotMatch(html, /disabled=/);
+	});
+
+	it("mounts the confirm once a folder is chosen", () => {
+		const html = render({ selectedId: "mb-prullenbak" });
+		assert.match(html, /Set as Trash and delete 12 messages/);
+	});
+
+	it("announces each folder's count as part of the row's own name", () => {
+		const html = render({});
+		assert.match(
+			html,
+			/aria-label="Set Deleted Messages, 512 messages, as Trash"/,
+		);
+		assert.match(html, /aria-label="Folders on this account"/);
+	});
+
+	it("names the account only where there is more than one", () => {
+		assert.match(
+			render({ accountEmail: "you@example.com" }),
+			/you@example.com/,
+		);
+		assert.doesNotMatch(render({}), /you@example\.com/);
+	});
+
+	it("offers a new folder only where the account has no Trash at all", () => {
+		const create = async (): Promise<FolderTreeNode> => ({
+			id: "mb-new",
+			label: "Trash",
+			path: "INBOX/Trash",
+		});
+		assert.match(render({ onCreateFolder: create }), />New folder</);
+		assert.doesNotMatch(
+			render({ reason: "stale", onCreateFolder: create }),
+			/New folder/,
+		);
+		assert.doesNotMatch(
+			render({ reason: "unconfirmed", onCreateFolder: create }),
+			/New folder/,
+		);
+	});
+
+	it("warns in the tone of the pending action, not of the reason", () => {
+		assert.match(render({ reason: "none" }), /text-warning/);
+		assert.match(
+			render({ reason: "unconfirmed", action: { kind: "emptyTrash" } }),
+			/text-danger/,
+		);
+	});
+
+	it("replaces the body with the in-flight write, and takes the way out away", () => {
+		const html = render({
+			selectedId: "mb-prullenbak",
+			phase: { kind: "appointing" },
+		});
+		assert.match(html, /Setting the Trash folder…/);
+		assert.match(html, /data-escape-owner/);
+		assert.match(html, /aria-live="polite"/);
+		assert.doesNotMatch(html, />Cancel</);
+	});
+
+	it("says what the re-issued action is doing, per verb", () => {
+		assert.match(
+			render({ selectedId: "mb-prullenbak", phase: { kind: "acting" } }),
+			/Deleting 12 messages…/,
+		);
+		assert.match(
+			render({
+				selectedId: "mb-prullenbak",
+				action: { kind: "emptyTrash" },
+				phase: { kind: "acting" },
+			}),
+			/Emptying Prullenbak…/,
+		);
+	});
+
+	it("keeps the picker and the selection through a failed appointment", () => {
+		const html = render({
+			selectedId: "mb-prullenbak",
+			phase: { kind: "appoint-failed", cause: "generic" },
+		});
+		assert.match(
+			html,
+			/Couldn&#x27;t set that folder as Trash\. Nothing has been deleted\. Please try again\./,
+		);
+		assert.match(html, /Set as Trash and delete 12 messages/);
+		assert.match(html, /role="alert"/);
+	});
+
+	it("words an unsettled mailbox as a wait, not a failure to retry blindly", () => {
+		const html = render({
+			selectedId: "mb-prullenbak",
+			phase: { kind: "appoint-failed", cause: "mailbox-pending" },
+		});
+		assert.match(
+			html,
+			/Prullenbak is still being created on the mail server\. Wait for it to finish, then try again\./,
+		);
+	});
+});

package/src/components/role-appointment-prompt.stories.tsx

@@ -0,0 +1,172 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useEffect, useState } from "react";
+import type { FolderTreeNode } from "../lib/folder-tree.js";
+import {
+	type PromptPhase,
+	RoleAppointmentPrompt,
+	type RoleAppointmentPromptProps,
+} from "./role-appointment-prompt.js";
+
+/**
+ * An account with two folders that could both be Trash by name: the one holding
+ * 512 messages, and the empty look-alike beside it. Telling those apart is the
+ * whole reason the prompt shows counts.
+ */
+const FOLDERS: readonly FolderTreeNode[] = [
+	{ id: "mb-inbox", label: "INBOX", path: "INBOX", messageCount: 4821 },
+	{
+		id: "mb-archive",
+		label: "Archive",
+		path: "Archive",
+		messageCount: 19243,
+	},
+	{
+		id: "mb-deleted",
+		label: "Deleted Messages",
+		path: "Deleted Messages",
+		messageCount: 512,
+	},
+	{
+		id: "mb-prullenbak",
+		label: "Prullenbak",
+		path: "Prullenbak",
+		messageCount: 0,
+	},
+	{ id: "mb-spam", label: "Spam", path: "Spam", messageCount: 88 },
+];
+
+type HarnessProps = Omit<
+	RoleAppointmentPromptProps,
+	| "open"
+	| "selectedId"
+	| "onSelect"
+	| "onConfirm"
+	| "onCancel"
+	| "folders"
+	| "delimiter"
+> & {
+	initialSelectedId?: string;
+	/** Phases the story steps through, so one story can show a sequence. */
+	phaseCycle?: readonly PromptPhase[];
+};
+
+function Harness({ initialSelectedId, phaseCycle, ...props }: HarnessProps) {
+	const [selectedId, setSelectedId] = useState(initialSelectedId);
+	const [step, setStep] = useState(0);
+
+	useEffect(() => {
+		if (!phaseCycle || phaseCycle.length < 2) return;
+		const timer = setInterval(
+			() => setStep((current) => (current + 1) % phaseCycle.length),
+			2200,
+		);
+		return () => clearInterval(timer);
+	}, [phaseCycle]);
+
+	return (
+		<RoleAppointmentPrompt
+			{...props}
+			open
+			folders={FOLDERS}
+			delimiter="/"
+			phase={phaseCycle?.[step] ?? props.phase}
+			selectedId={selectedId}
+			onSelect={setSelectedId}
+			onConfirm={() => {}}
+			onCancel={() => {}}
+		/>
+	);
+}
+
+const meta: Meta<typeof Harness> = {
+	title: "Mail/RoleAppointmentPrompt",
+	component: Harness,
+};
+export default meta;
+
+type Story = StoryObj<typeof Harness>;
+
+const choosing: PromptPhase = { kind: "choosing" };
+
+/** A delete refused because the account has no Trash at all. A first choice. */
+export const None: Story = {
+	name: "none",
+	args: {
+		reason: "none",
+		action: { kind: "delete", count: 12 },
+		phase: choosing,
+		accountEmail: "440737+mvhenten@users.noreply.github.com",
+	},
+};
+
+/**
+ * A delete refused because the folder the user chose is gone. The description
+ * names it, so a rename (pick the renamed one) is told from a deletion.
+ */
+export const Stale: Story = {
+	name: "stale",
+	args: {
+		reason: "stale",
+		action: { kind: "delete", count: 12 },
+		staleFolderLabel: "Prullenbak",
+		phase: choosing,
+	},
+};
+
+/**
+ * Empty Trash on a folder reader only matched by name. The guess starts
+ * selected, so the common case is one tap, and the confirm is the danger
+ * variant — this is the only framing whose confirm expunges.
+ */
+export const Unconfirmed: Story = {
+	name: "unconfirmed",
+	args: {
+		reason: "unconfirmed",
+		action: { kind: "emptyTrash" },
+		trashFolderLabel: "Deleted Messages",
+		initialSelectedId: "mb-deleted",
+		phase: choosing,
+	},
+};
+
+/**
+ * Two writes behind one press, and the story steps through both: the
+ * appointment, then the delete it unblocks. Neither has a way out — the write
+ * has left, and cancelling a half-applied ceremony is worse than waiting.
+ */
+export const Pending: Story = {
+	name: "pending",
+	args: {
+		reason: "none",
+		action: { kind: "delete", count: 12 },
+		initialSelectedId: "mb-prullenbak",
+		phase: { kind: "appointing" },
+		phaseCycle: [{ kind: "appointing" }, { kind: "acting" }],
+	},
+};
+
+/** The write failed. The picker stays, the selection stays, the confirm stays pressable. */
+export const AppointFailed: Story = {
+	name: "appoint-failed",
+	args: {
+		reason: "none",
+		action: { kind: "delete", count: 12 },
+		initialSelectedId: "mb-prullenbak",
+		phase: { kind: "appoint-failed", cause: "generic" },
+	},
+};
+
+/**
+ * The folder was made in the picker and the mail server has not confirmed it
+ * yet. A different sentence with a different remedy from a network failure —
+ * waiting fixes this one, retrying does not.
+ */
+export const AppointRefusedPendingMailbox: Story = {
+	name: "appoint-refused-pending-mailbox",
+	args: {
+		reason: "none",
+		action: { kind: "delete", count: 12 },
+		initialSelectedId: "mb-prullenbak",
+		phase: { kind: "appoint-failed", cause: "mailbox-pending" },
+	},
+};