@remit/ui 0.0.67 → 0.0.69

package/package.json

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

package/src/components/folder-manage-actions.render.test.ts

@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import {
+	FolderManageActions,
+	type FolderManageActionsProps,
+} from "./folder-manage-actions.js";
+
+const render = (props: Partial<FolderManageActionsProps>) =>
+	renderToString(
+		createElement(FolderManageActions, {
+			label: "Travel",
+			onRename: () => undefined,
+			onDelete: () => undefined,
+			...props,
+		}),
+	);
+
+describe("FolderManageActions", () => {
+	it("names both controls after the folder they act on", () => {
+		const html = render({});
+		assert.match(html, /aria-label="Rename Travel"/);
+		assert.match(html, /aria-label="Delete Travel"/);
+	});
+
+	it("leaves a deletable folder's delete pressable", () => {
+		assert.doesNotMatch(render({}), /disabled=""/);
+	});
+
+	it("states why a folder stays, in the control's own name", () => {
+		const html = render({
+			deleteBlockedReason: "The inbox can't be deleted.",
+		});
+		assert.match(
+			html,
+			/aria-label="Delete Travel — The inbox can&#x27;t be deleted."/,
+		);
+		assert.match(html, /disabled=""/);
+		assert.match(html, /title="The inbox can&#x27;t be deleted."/);
+	});
+
+	it("takes the surface's own wording for each control", () => {
+		const html = render({
+			renameLabel: (label) => `Hernoem ${label}`,
+			deleteLabel: (label) => `Verwijder ${label}`,
+		});
+		assert.match(html, /aria-label="Hernoem Travel"/);
+		assert.match(html, /aria-label="Verwijder Travel"/);
+	});
+});

package/src/components/folder-manage-actions.stories.tsx

@@ -0,0 +1,94 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import type { ReactNode } from "react";
+import { FolderManageActions } from "./folder-manage-actions.js";
+import { FolderRow } from "./folder-row.js";
+
+const meta: Meta<typeof FolderManageActions> = {
+	title: "Mail/FolderManageActions",
+	component: FolderManageActions,
+	parameters: { layout: "centered" },
+};
+export default meta;
+
+type Story = StoryObj<typeof FolderManageActions>;
+
+function List({ children }: { children: ReactNode }) {
+	return (
+		<div className="w-[360px] overflow-hidden rounded-lg border border-line bg-surface font-sans text-fg">
+			{children}
+		</div>
+	);
+}
+
+export const OnARow: Story = {
+	name: "Beside the folder it acts on",
+	render: () => (
+		<List>
+			<FolderRow
+				label="Travel"
+				depth={0}
+				expanded={false}
+				ariaLabel="Travel"
+				separated
+				actions={
+					<FolderManageActions
+						label="Travel"
+						onRename={() => {}}
+						onDelete={() => {}}
+					/>
+				}
+			/>
+			<FolderRow
+				label="Hotels"
+				depth={1}
+				expanded={false}
+				ariaLabel="Hotels"
+				actions={
+					<FolderManageActions
+						label="Hotels"
+						onRename={() => {}}
+						onDelete={() => {}}
+					/>
+				}
+			/>
+		</List>
+	),
+};
+
+/** A folder the account depends on keeps rename and states why it stays. */
+export const Blocked: Story = {
+	name: "A folder that can't be deleted",
+	render: () => (
+		<List>
+			<FolderRow
+				label="Inbox"
+				depth={0}
+				expanded={false}
+				ariaLabel="Inbox"
+				separated
+				actions={
+					<FolderManageActions
+						label="Inbox"
+						deleteBlockedReason="The inbox can't be deleted."
+						onRename={() => {}}
+						onDelete={() => {}}
+					/>
+				}
+			/>
+			<FolderRow
+				label="Trash"
+				depth={0}
+				expanded={false}
+				ariaLabel="Trash"
+				actions={
+					<FolderManageActions
+						label="Trash"
+						deleteBlockedReason="This folder is your Trash folder. Reassign that role before deleting it."
+						onRename={() => {}}
+						onDelete={() => {}}
+					/>
+				}
+			/>
+		</List>
+	),
+};

package/src/components/folder-manage-actions.tsx

@@ -0,0 +1,54 @@
+import { Pencil, Trash2 } from "lucide-react";
+import { Button } from "./button.js";
+
+export interface FolderManageActionsProps {
+	/** The folder as it reads on the row, so each control names its own target. */
+	label: string;
+	onRename: () => void;
+	onDelete: () => void;
+	/** Why this folder can't be deleted; absent means it can. */
+	deleteBlockedReason?: string;
+	renameLabel?: (label: string) => string;
+	deleteLabel?: (label: string) => string;
+}
+
+/**
+ * What a folder row offers beyond opening: rename it, or delete it. A folder
+ * the account depends on states why it stays — as the control's own name, so
+ * the reason is announced rather than only hovered.
+ */
+export const FolderManageActions = ({
+	label,
+	onRename,
+	onDelete,
+	deleteBlockedReason,
+	renameLabel = (name) => `Rename ${name}`,
+	deleteLabel = (name) => `Delete ${name}`,
+}: FolderManageActionsProps) => {
+	const deleteName = deleteBlockedReason
+		? `${deleteLabel(label)} — ${deleteBlockedReason}`
+		: deleteLabel(label);
+	return (
+		<span className="flex shrink-0 items-center gap-0.5 pr-2">
+			<Button
+				variant="ghost"
+				size="sm"
+				icon={<Pencil className="size-3.5" />}
+				aria-label={renameLabel(label)}
+				onClick={onRename}
+			/>
+			{/* The title sits on the wrapper: a disabled button takes no pointer
+			    events, so a tooltip on it never shows. */}
+			<span title={deleteBlockedReason}>
+				<Button
+					variant="ghost"
+					size="sm"
+					icon={<Trash2 className="size-3.5" />}
+					aria-label={deleteName}
+					disabled={deleteBlockedReason !== undefined}
+					onClick={onDelete}
+				/>
+			</span>
+		</span>
+	);
+};

package/src/components/folder-manager.render.test.ts

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { FolderManager, type ManagedFolder } from "./folder-manager.js";
+
+const folders: ManagedFolder[] = [
+	{
+		id: "inbox",
+		label: "Inbox",
+		path: "INBOX",
+		deleteBlockedReason: "The inbox can't be deleted.",
+	},
+	{ id: "travel", label: "Travel", path: "Travel" },
+	{ id: "hotels", label: "Hotels", path: "Travel/Hotels" },
+	{ id: "trash", label: "Trash", path: "Deleted Messages" },
+];
+
+const render = (props: Partial<Parameters<typeof FolderManager>[0]> = {}) =>
+	renderToString(
+		createElement(FolderManager, {
+			folders,
+			onRename: () => undefined,
+			onDelete: () => undefined,
+			...props,
+		}),
+	);
+
+describe("FolderManager", () => {
+	it("browses the folders as a tree that starts at its top level", () => {
+		const html = render();
+		assert.match(html, /role="tree"/);
+		assert.equal(html.match(/role="treeitem"/g)?.length, 3);
+		assert.doesNotMatch(html, /aria-label="Hotels"/);
+	});
+
+	it("reads a row as the folder itself, not as a destination", () => {
+		const html = render();
+		assert.match(html, /aria-label="Travel"/);
+		assert.doesNotMatch(html, /Move to/);
+	});
+
+	it("labels a folder by its role while nesting it by its real path", () => {
+		const html = render();
+		assert.match(html, /aria-label="Trash"/);
+		assert.doesNotMatch(html, />Deleted Messages</);
+	});
+
+	it("offers rename and delete on every row", () => {
+		const html = render();
+		assert.match(html, /aria-label="Rename Travel"/);
+		assert.match(html, /aria-label="Delete Travel"/);
+	});
+
+	it("carries a folder's reason for staying onto its delete control", () => {
+		assert.match(
+			render(),
+			/aria-label="Delete Inbox — The inbox can&#x27;t be deleted."/,
+		);
+	});
+
+	it("offers no create affordance without onCreateFolder", () => {
+		assert.doesNotMatch(render(), /New folder/);
+	});
+
+	it("makes a folder where the user is looking once creating is wired", () => {
+		const html = render({
+			onCreateFolder: () =>
+				Promise.resolve({ id: "made", label: "Made", path: "Made" }),
+		});
+		assert.match(html, /aria-label="New folder"/);
+	});
+
+	it("takes the surface's own tree name", () => {
+		assert.match(
+			render({ labels: { treeAriaLabel: "All folders for a@b.example" } }),
+			/aria-label="All folders for a@b.example"/,
+		);
+	});
+});

package/src/components/folder-manager.stories.tsx

@@ -0,0 +1,184 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { type ReactNode, useState } from "react";
+import type { FolderTreeNode } from "../lib/folder-tree.js";
+import { FolderManager, type ManagedFolder } from "./folder-manager.js";
+import { FolderRenameDialog } from "./folder-rename-dialog.js";
+
+const folders: ManagedFolder[] = [
+	{
+		id: "mbx-inbox",
+		label: "Inbox",
+		path: "INBOX",
+		deleteBlockedReason: "The inbox can't be deleted.",
+	},
+	{
+		id: "mbx-archive",
+		label: "Archive",
+		path: "Archive",
+		deleteBlockedReason:
+			"This folder is your Archive folder. Reassign that role before deleting it.",
+	},
+	{
+		id: "mbx-trash",
+		label: "Trash",
+		path: "Deleted Messages",
+		deleteBlockedReason:
+			"This folder is your Trash folder. Reassign that role before deleting it.",
+	},
+	{
+		id: "mbx-travel",
+		label: "Travel",
+		path: "Travel",
+		deleteBlockedReason: "This folder has subfolders. Delete them first.",
+	},
+	{ id: "mbx-travel-flights", label: "Flights", path: "Travel/Flights" },
+	{ id: "mbx-travel-hotels", label: "Hotels", path: "Travel/Hotels" },
+	{
+		id: "mbx-travel-hotels-receipts",
+		label: "Receipts",
+		path: "Travel/Hotels/Receipts",
+	},
+	{
+		id: "mbx-finance",
+		label: "Finance",
+		path: "Finance",
+		deleteBlockedReason: "This folder has subfolders. Delete them first.",
+	},
+	{ id: "mbx-finance-invoices", label: "Invoices", path: "Finance/Invoices" },
+	{ id: "mbx-finance-tax", label: "Tax", path: "Finance/Tax" },
+	{ id: "mbx-family", label: "Family", path: "Family" },
+	{ id: "mbx-news", label: "Newsletters", path: "Newsletters" },
+	{ id: "mbx-news-tech", label: "Tech", path: "Newsletters/Tech" },
+];
+
+const meta: Meta<typeof FolderManager> = {
+	title: "Mail/FolderManager",
+	component: FolderManager,
+	parameters: { layout: "centered" },
+};
+export default meta;
+
+type Story = StoryObj<typeof FolderManager>;
+
+function Frame({
+	children,
+	className = "h-[520px] w-[420px] rounded-lg border border-line shadow-lg",
+}: {
+	children: ReactNode;
+	className?: string;
+}) {
+	return (
+		<div
+			className={`flex flex-col overflow-hidden bg-surface font-sans text-fg ${className}`}
+		>
+			{children}
+		</div>
+	);
+}
+
+let createdSeq = 0;
+const createFolder = (
+	name: string,
+	parentPath: string,
+): Promise<FolderTreeNode> =>
+	new Promise((resolve) => {
+		createdSeq += 1;
+		setTimeout(
+			() =>
+				resolve({
+					id: `mbx-created-${createdSeq}`,
+					label: name,
+					path: parentPath ? `${parentPath}/${name}` : name,
+				}),
+			400,
+		);
+	});
+
+function Manager({
+	renaming = false,
+	className,
+}: {
+	renaming?: boolean;
+	className?: string;
+}) {
+	const [known, setKnown] = useState<ManagedFolder[]>(folders);
+	const [renamed, setRenamed] = useState<ManagedFolder | null>(
+		renaming ? (folders[2] as ManagedFolder) : null,
+	);
+	const [draft, setDraft] = useState("Trash");
+	return (
+		<>
+			<Frame className={className}>
+				<FolderManager
+					folders={known}
+					onCreateFolder={(name, parentPath) =>
+						createFolder(name, parentPath).then((created) => {
+							setKnown((current) => [...current, created]);
+							return created;
+						})
+					}
+					onRename={(folder) => {
+						setRenamed(folder);
+						setDraft(folder.label);
+					}}
+					onDelete={(folder) =>
+						setKnown((current) =>
+							current.filter((entry) => entry.id !== folder.id),
+						)
+					}
+					labels={{ treeAriaLabel: "All folders for alice@northwind.example" }}
+				/>
+			</Frame>
+			{renamed && (
+				<FolderRenameDialog
+					open
+					folderLabel={renamed.label}
+					defaultLabel="Deleted Messages"
+					name={draft}
+					onNameChange={setDraft}
+					onSubmit={() => setRenamed(null)}
+					onClose={() => setRenamed(null)}
+				/>
+			)}
+		</>
+	);
+}
+
+/**
+ * The account's folders as they really nest, closed to the top level. Every row
+ * opens where you tap it and carries rename and delete; a folder the account
+ * depends on keeps rename and states why it stays.
+ */
+export const Default: Story = {
+	name: "Default (collapsed to top level)",
+	render: () => <Manager />,
+};
+
+/** Renaming a folder: the name is Remit's own, and clearing it restores the server's. */
+export const Renaming: Story = {
+	name: "Renaming a folder",
+	render: () => <Manager renaming />,
+};
+
+/** A first-run account with nothing but its inbox. */
+export const JustTheInbox: Story = {
+	name: "A single folder",
+	render: () => (
+		<Frame>
+			<FolderManager
+				folders={[folders[0] as ManagedFolder]}
+				onCreateFolder={createFolder}
+				onRename={() => {}}
+				onDelete={() => {}}
+			/>
+		</Frame>
+	),
+};
+
+/** The surface as it sits on a phone: full width, one branch open at a time. */
+export const Phone: Story = {
+	name: "Phone",
+	globals: { viewport: { value: "mobile" } },
+	parameters: { layout: "fullscreen" },
+	render: () => <Manager className="h-screen w-full" />,
+};

package/src/components/folder-manager.tsx

@@ -0,0 +1,77 @@
+import type { FolderTreeNode } from "../lib/folder-tree.js";
+import { FolderManageActions } from "./folder-manage-actions.js";
+import {
+	FolderTreePicker,
+	type FolderTreePickerLabels,
+} from "./folder-tree-picker.js";
+
+export interface ManagedFolder extends FolderTreeNode {
+	/** Why this folder can't be deleted; absent means it can. */
+	deleteBlockedReason?: string;
+}
+
+export interface FolderManagerLabels extends FolderTreePickerLabels {
+	rename?: (label: string) => string;
+	remove?: (label: string) => string;
+}
+
+export interface FolderManagerProps {
+	folders: readonly ManagedFolder[];
+	onRename: (folder: ManagedFolder) => void;
+	onDelete: (folder: ManagedFolder) => void;
+	/**
+	 * Creating a folder is an IMAP mutation, so this resolves only once the mail
+	 * server confirms it. Absent means no create affordance renders.
+	 */
+	onCreateFolder?: (
+		name: string,
+		parentPath: string,
+		signal?: AbortSignal,
+	) => Promise<FolderTreeNode>;
+	/** The provider's hierarchy separator. */
+	delimiter?: string;
+	labels?: FolderManagerLabels;
+}
+
+/**
+ * The folders as the account holds them, browsed the same way a destination is
+ * picked — open a folder to see what is inside it, filter to narrow, make a new
+ * one where you are looking — with rename and delete on each row. Nothing is
+ * chosen here, so a row opens and closes and nothing else.
+ */
+export const FolderManager = ({
+	folders,
+	onRename,
+	onDelete,
+	onCreateFolder,
+	delimiter,
+	labels,
+}: FolderManagerProps) => {
+	const byId = new Map(folders.map((folder) => [folder.id, folder]));
+	return (
+		<FolderTreePicker
+			folders={folders}
+			onCreateFolder={onCreateFolder}
+			delimiter={delimiter}
+			labels={{
+				treeAriaLabel: "Your folders",
+				optionLabel: (label) => label,
+				...labels,
+			}}
+			rowActions={(folder) => {
+				const managed = byId.get(folder.id);
+				if (!managed) return null;
+				return (
+					<FolderManageActions
+						label={managed.label}
+						deleteBlockedReason={managed.deleteBlockedReason}
+						renameLabel={labels?.rename}
+						deleteLabel={labels?.remove}
+						onRename={() => onRename(managed)}
+						onDelete={() => onDelete(managed)}
+					/>
+				);
+			}}
+		/>
+	);
+};

package/src/components/folder-rename-dialog.render.test.ts

@@ -0,0 +1,51 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import {
+	FolderRenameDialog,
+	type FolderRenameDialogProps,
+} from "./folder-rename-dialog.js";
+
+const render = (props: Partial<FolderRenameDialogProps>) =>
+	renderToString(
+		createElement(FolderRenameDialog, {
+			open: true,
+			folderLabel: "Trash",
+			defaultLabel: "Deleted Messages",
+			name: "Trash",
+			onNameChange: () => undefined,
+			onSubmit: () => undefined,
+			onClose: () => undefined,
+			...props,
+		}),
+	);
+
+describe("FolderRenameDialog", () => {
+	it("renders nothing when closed", () => {
+		assert.equal(render({ open: false }), "");
+	});
+
+	it("names the folder it is renaming", () => {
+		assert.match(render({}), /Rename Trash/);
+	});
+
+	it("states what clearing the name falls back to", () => {
+		const html = render({});
+		assert.match(html, /Leave it blank to use/);
+		assert.match(html, />Deleted Messages</);
+	});
+
+	it("holds the wait while the name is saved", () => {
+		const html = render({ pending: true });
+		assert.match(html, /Saving…/);
+		assert.match(html, /disabled/);
+	});
+
+	it("states a failure where it happened", () => {
+		assert.match(
+			render({ error: "Couldn't save that name." }),
+			/role="alert"[^>]*>Couldn&#x27;t save that name./,
+		);
+	});
+});

package/src/components/folder-rename-dialog.stories.tsx

@@ -0,0 +1,66 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { FolderRenameDialog } from "./folder-rename-dialog.js";
+
+const meta: Meta<typeof FolderRenameDialog> = {
+	title: "Mail/FolderRenameDialog",
+	component: FolderRenameDialog,
+	parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+type Story = StoryObj<typeof FolderRenameDialog>;
+
+function Live({
+	initialName = "Trash",
+	pending,
+	error,
+}: {
+	initialName?: string;
+	pending?: boolean;
+	error?: string;
+}) {
+	const [name, setName] = useState(initialName);
+	return (
+		<div className="h-screen bg-canvas font-sans">
+			<FolderRenameDialog
+				open
+				folderLabel="Trash"
+				defaultLabel="Deleted Messages"
+				name={name}
+				onNameChange={setName}
+				onSubmit={() => {}}
+				onClose={() => {}}
+				pending={pending}
+				error={error}
+			/>
+		</div>
+	);
+}
+
+export const Default: Story = {
+	name: "Renaming an appointed folder",
+	render: () => <Live />,
+};
+
+/** Cleared: the folder goes back to what the mail server calls it. */
+export const Cleared: Story = {
+	name: "Name cleared",
+	render: () => <Live initialName="" />,
+};
+
+export const Saving: Story = {
+	name: "Saving",
+	render: () => <Live pending />,
+};
+
+export const Failed: Story = {
+	name: "The save failed",
+	render: () => <Live error="Couldn't save that name. Please try again." />,
+};
+
+export const Phone: Story = {
+	name: "Phone",
+	globals: { viewport: { value: "mobile" } },
+	render: () => <Live />,
+};