@remit/ui 0.0.49 → 0.0.51

package/package.json

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

package/src/components/app-shell-types.ts

@@ -191,6 +191,12 @@ export const briefCategories: ReadonlyArray<{
 	{ id: "social", label: "Social" },
 ];
 
+export interface ThreadRowLabel {
+	labelId: string;
+	name: string;
+	color: string;
+}
+
 export interface ThreadRowData {
 	id: string;
 	accountId: string;
@@ -212,6 +218,8 @@ export interface ThreadRowData {
 	messageCount?: number;
 	/** Authenticity heuristics flagged this row (DKIM/From mismatch). */
 	suspicious?: boolean;
+	/** Labels applied to this message (issue #26) — filter-, organize-, and manually-applied alike. */
+	labels?: ThreadRowLabel[];
 }
 
 export interface ThreadSection {

package/src/components/filter-rule-editor.stories.tsx

@@ -6,11 +6,13 @@ import {
 	type ClauseField,
 	clauseFieldLabel,
 	demoFolders,
+	demoLabels,
 	demoRule,
 	demoSenderFallbackRule,
 	demoVocabularyRule,
 	type FilterRule,
 	type FolderOption,
+	type LabelOption,
 	type PreviewCount,
 	type RuleClause,
 } from "./filter-rule.js";
@@ -51,11 +53,18 @@ const READY = (count: number, stale?: boolean): PreviewCount => ({
 function LiveEditor({
 	initialRule,
 	semanticAvailable = true,
+	labels = demoLabels,
 	onCreateFolder,
+	onCreateLabel,
 }: {
 	initialRule: FilterRule;
 	semanticAvailable?: boolean;
-	onCreateFolder?: (name: string) => Promise<FolderOption>;
+	labels?: LabelOption[];
+	onCreateFolder?: (
+		name: string,
+		signal?: AbortSignal,
+	) => Promise<FolderOption>;
+	onCreateLabel?: (name: string) => Promise<LabelOption>;
 }) {
 	const [rule, setRule] = useState<FilterRule>(initialRule);
 	const [clauseEdit, setClauseEdit] = useState<ClauseEditState | undefined>();
@@ -123,6 +132,8 @@ function LiveEditor({
 		},
 		onChangeMove: (moveMailboxId) =>
 			setRule((r) => ({ ...r, moveMailboxId: moveMailboxId || undefined })),
+		onChangeLabel: (labelId) =>
+			setRule((r) => ({ ...r, labelId: labelId || undefined })),
 		onChangeScope: (scope) => setRule((r) => ({ ...r, scope })),
 		onChangeName: (name) => setRule((r) => ({ ...r, name })),
 		onChangeUntil: (until) => setRule((r) => ({ ...r, until })),
@@ -132,10 +143,12 @@ function LiveEditor({
 		<FilterRuleEditor
 			rule={rule}
 			folders={demoFolders}
+			labels={labels}
 			preview={preview}
 			semanticAvailable={semanticAvailable}
 			clauseEdit={clauseEdit}
 			onCreateFolder={onCreateFolder}
+			onCreateLabel={onCreateLabel}
 			onCommit={() => {}}
 			onCancel={() => {}}
 			{...handlers}
@@ -170,6 +183,259 @@ export const WithNewFolderOption: Story = {
 	),
 };
 
+/**
+ * Drive the destination field into its create sub-form: pick "＋ New folder…",
+ * type a name, and press "Create folder". Used by the pending and error stories
+ * below so each lands in the state it documents without a manual click-through.
+ */
+async function openCreateAndSubmit(
+	canvasElement: HTMLElement,
+	folderName: string,
+) {
+	const setSelectValue = Object.getOwnPropertyDescriptor(
+		HTMLSelectElement.prototype,
+		"value",
+	)?.set;
+	const setInputValue = Object.getOwnPropertyDescriptor(
+		HTMLInputElement.prototype,
+		"value",
+	)?.set;
+	const select = canvasElement.querySelector<HTMLSelectElement>(
+		'select[aria-label="Destination folder"]',
+	);
+	if (!select) return;
+	setSelectValue?.call(select, CREATE_FOLDER_STORY_VALUE);
+	select.dispatchEvent(new Event("change", { bubbles: true }));
+	const input = canvasElement.querySelector<HTMLInputElement>(
+		'input[aria-label="New folder name"]',
+	);
+	if (!input) return;
+	setInputValue?.call(input, folderName);
+	input.dispatchEvent(new Event("input", { bubbles: true }));
+	const createButton = Array.from(
+		canvasElement.querySelectorAll<HTMLButtonElement>("button"),
+	).find((button) => button.textContent?.trim() === "Create folder");
+	createButton?.click();
+}
+
+/** Matches the internal CREATE_FOLDER_VALUE option in the destination select. */
+const CREATE_FOLDER_STORY_VALUE = "__filter_create_folder__";
+
+/** Mirrors the web-client wait's honest timeout copy. */
+const TIMEOUT_MESSAGE =
+	"The folder was created but the mail server hasn't confirmed it yet, so nothing was attached to it. It's in your folder list — try again in a moment.";
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 60));
+
+const neverResolvesCreateFolder = (): Promise<FolderOption> =>
+	new Promise<FolderOption>(() => undefined);
+
+const rejectingCreateFolder = (message: string) => (): Promise<FolderOption> =>
+	Promise.reject(new Error(message));
+
+/** Rejects the first attempt, resolves the retry — the resume the hook performs. */
+const failThenSucceedCreateFolder = () => {
+	let attempts = 0;
+	return (name: string): Promise<FolderOption> => {
+		attempts += 1;
+		return attempts === 1
+			? Promise.reject(new Error(TIMEOUT_MESSAGE))
+			: Promise.resolve({ id: "mbx-created", label: name });
+	};
+};
+
+/** Never resolves on its own; rejects with an AbortError when the signal aborts. */
+const abortAwareCreateFolder = (
+	_name: string,
+	signal?: AbortSignal,
+): Promise<FolderOption> =>
+	new Promise<FolderOption>((_resolve, reject) => {
+		signal?.addEventListener("abort", () =>
+			reject(new DOMException("Aborted", "AbortError")),
+		);
+	});
+
+/**
+ * The folder is a dependent write for the filter, so creating it waits for the
+ * mail server to confirm the folder before it can be picked as the destination.
+ * The wait shows as "Creating folder…" — held for the whole confirmation, not
+ * just a fast optimistic round-trip.
+ */
+export const NewFolderCreating: Story = {
+	name: "New folder — creating (waiting for the server)",
+	render: () => (
+		<LiveEditor
+			initialRule={demoRule}
+			onCreateFolder={neverResolvesCreateFolder}
+		/>
+	),
+	play: async ({ canvasElement }) => {
+		await openCreateAndSubmit(canvasElement, "Receipts");
+	},
+};
+
+/**
+ * The folder create failed on the mail server. The rule is not committed against
+ * a folder that does not exist: the error is surfaced inline with the create form
+ * still open, so the create can be retried or cancelled.
+ */
+export const NewFolderCreateFailed: Story = {
+	name: "New folder — create failed (retry / cancel)",
+	render: () => (
+		<LiveEditor
+			initialRule={demoRule}
+			onCreateFolder={rejectingCreateFolder(
+				"The folder couldn't be created on the mail server. Please try again.",
+			)}
+		/>
+	),
+	play: async ({ canvasElement }) => {
+		await openCreateAndSubmit(canvasElement, "Receipts");
+	},
+};
+
+/**
+ * The folder create was never confirmed within the wait bound. Distinct from a
+ * hard failure — the message names the timeout — and, like a failure, leaves no
+ * folder selected, so no filter is written against it.
+ */
+export const NewFolderCreateTimedOut: Story = {
+	name: "New folder — create timed out (retry / cancel)",
+	render: () => (
+		<LiveEditor
+			initialRule={demoRule}
+			onCreateFolder={rejectingCreateFolder(TIMEOUT_MESSAGE)}
+		/>
+	),
+	play: async ({ canvasElement }) => {
+		await openCreateAndSubmit(canvasElement, "Receipts");
+	},
+};
+
+/**
+ * Retry is a resume: the first attempt times out (the folder was made but not yet
+ * confirmed), and pressing "Create folder" again with the same name resolves —
+ * the hook re-waits on the folder it already made rather than re-creating it, so
+ * the retry the failure message points at actually works.
+ */
+export const NewFolderCreateRetrySucceeds: Story = {
+	name: "New folder — retry resumes and succeeds",
+	render: () => (
+		<LiveEditor
+			initialRule={demoRule}
+			onCreateFolder={failThenSucceedCreateFolder()}
+		/>
+	),
+	play: async ({ canvasElement }) => {
+		await openCreateAndSubmit(canvasElement, "Receipts");
+		await tick();
+		const retry = Array.from(
+			canvasElement.querySelectorAll<HTMLButtonElement>("button"),
+		).find((button) => button.textContent?.trim() === "Create folder");
+		retry?.click();
+	},
+};
+
+/**
+ * Cancelling while "Creating folder…" is in flight aborts the wait: the create
+ * promise rejects with an AbortError the field swallows, so no destination binds
+ * after the user backed out — the sub-form just closes.
+ */
+export const NewFolderCreateCancelledMidWait: Story = {
+	name: "New folder — cancel aborts the wait",
+	render: () => (
+		<LiveEditor
+			initialRule={demoRule}
+			onCreateFolder={abortAwareCreateFolder}
+		/>
+	),
+	play: async ({ canvasElement }) => {
+		await openCreateAndSubmit(canvasElement, "Receipts");
+		await tick();
+		const cancel = Array.from(
+			canvasElement.querySelectorAll<HTMLButtonElement>("button"),
+		).find((button) => button.textContent?.trim() === "Cancel");
+		cancel?.click();
+	},
+};
+
+/** No labels exist yet in the account — the select offers only "No label". */
+export const NoLabels: Story = {
+	render: () => <LiveEditor initialRule={demoRule} labels={[]} />,
+};
+
+/** A rule that already applies a label — the chip renders next to the select. */
+export const WithLabelSelected: Story = {
+	render: () => (
+		<LiveEditor initialRule={{ ...demoRule, labelId: "lbl-receipts" }} />
+	),
+};
+
+/** Many labels in the account — the select scrolls rather than the layout growing. */
+export const ManyLabels: Story = {
+	render: () => (
+		<LiveEditor
+			initialRule={demoRule}
+			labels={Array.from({ length: 20 }, (_, i) => ({
+				id: `lbl-${i}`,
+				name: `Label ${i + 1}`,
+				color: demoLabels[i % demoLabels.length].color,
+			}))}
+		/>
+	),
+};
+
+/** A long label name truncates in the chip rather than overflowing the row. */
+export const LongLabelNames: Story = {
+	render: () => (
+		<LiveEditor
+			initialRule={{ ...demoRule, labelId: "lbl-long" }}
+			labels={[
+				{
+					id: "lbl-long",
+					name: "Quarterly compliance filings that need a second look",
+					color: "Purple",
+				},
+				...demoLabels,
+			]}
+		/>
+	),
+};
+
+let newLabelSeq = 0;
+const mockCreateLabel = (name: string): Promise<LabelOption> =>
+	new Promise((resolve) => {
+		newLabelSeq += 1;
+		setTimeout(
+			() => resolve({ id: `lbl-new-${newLabelSeq}`, name, color: "Default" }),
+			400,
+		);
+	});
+
+/**
+ * The label select offers a "＋ New label…" option because `onCreateLabel` is
+ * wired (issue #26). Choosing it reveals a name field; on resolve the label is
+ * added to the select and picked as the action. Without the prop the option
+ * never shows — the editor stays data-agnostic.
+ */
+export const WithNewLabelOption: Story = {
+	render: () => (
+		<LiveEditor initialRule={demoRule} onCreateLabel={mockCreateLabel} />
+	),
+};
+
+const mockCreateLabelFailure = (): Promise<LabelOption> =>
+	new Promise((_resolve, reject) => {
+		setTimeout(() => reject(new Error("That name is already taken.")), 400);
+	});
+
+/** Creating a label from the picker can fail — the field stays open with the reason. */
+export const LabelCreateError: Story = {
+	render: () => (
+		<LiveEditor initialRule={demoRule} onCreateLabel={mockCreateLabelFailure} />
+	),
+};
+
 /** Literal clauses joined with "or", including the ticket-B ListId and FromDomain fields. */
 export const AnyOfTheseClauses: Story = {
 	render: () => <LiveEditor initialRule={demoVocabularyRule} />,

package/src/components/filter-rule-editor.tsx

@@ -1,4 +1,12 @@
-import { Fragment, type ReactNode, useMemo, useState } from "react";
+import {
+	Fragment,
+	type ReactNode,
+	useEffect,
+	useMemo,
+	useRef,
+	useState,
+} from "react";
+import { isAbortError } from "../lib/abort.js";
 import { BottomSheet } from "./bottom-sheet.js";
 import { Button } from "./button.js";
 import { Dialog } from "./dialog.js";
@@ -16,6 +24,7 @@ import {
 	commitLabel,
 	type FilterRule,
 	type FolderOption,
+	type LabelOption,
 	type MatchOperator,
 	matchJoinWord,
 	matchOperatorLabel,
@@ -23,6 +32,7 @@ import {
 	type RuleScope,
 } from "./filter-rule.js";
 import { Input } from "./input.js";
+import { LabelChip } from "./label-chip.js";
 import { SegmentedControl } from "./segmented-control.js";
 import { Select } from "./select.js";
 
@@ -36,6 +46,8 @@ export interface ClauseEditState {
 export interface FilterRuleEditorProps {
 	rule: FilterRule;
 	folders: FolderOption[];
+	/** The account's labels the apply-label action can target (issue #26). */
+	labels?: LabelOption[];
 	preview: PreviewCount;
 	/**
 	 * Content rendered above the clause chips — the filter-from-search conversion
@@ -84,12 +96,23 @@ export interface FilterRuleEditorProps {
 	onChangeMatchOperator?: (operator: MatchOperator) => void;
 	onChangeMove?: (mailboxId: string) => void;
 	/**
-	 * Create a new destination folder from within the editor. Given a folder
-	 * name, resolves to the created folder once the backend has queued it. When
-	 * absent, the "New folder…" option is not offered — the editor stays
-	 * data-agnostic, so stories and consumers without wiring render unchanged.
+	 * Create a new destination folder from within the editor. Given a folder name
+	 * and an abort signal, resolves to the created folder once the mail server
+	 * confirms it. The editor aborts the signal on unmount or cancel. When absent,
+	 * the "New folder…" option is not offered — the editor stays data-agnostic, so
+	 * stories and consumers without wiring render unchanged.
+	 */
+	onCreateFolder?: (
+		name: string,
+		signal?: AbortSignal,
+	) => Promise<FolderOption>;
+	onChangeLabel?: (labelId: string) => void;
+	/**
+	 * Create a new label from within the editor (issue #26). Given a label
+	 * name, resolves to the created label once the backend has saved it. When
+	 * absent, the "New label…" option is not offered.
 	 */
-	onCreateFolder?: (name: string) => Promise<FolderOption>;
+	onCreateLabel?: (name: string) => Promise<LabelOption>;
 	onChangeScope?: (scope: RuleScope) => void;
 	onChangeName?: (name: string) => void;
 	onChangeUntil?: (date: string) => void;
@@ -109,6 +132,7 @@ const scopeOptions: { value: RuleScope; label: string }[] = [
 ];
 
 const CREATE_FOLDER_VALUE = "__filter_create_folder__";
+const CREATE_LABEL_VALUE = "__filter_create_label__";
 
 /**
  * The move-to destination select, plus an inline "New folder…" affordance when
@@ -116,6 +140,13 @@ const CREATE_FOLDER_VALUE = "__filter_create_folder__";
  * name field; on resolve the new folder is added to the local option set (so it
  * is selectable even before the caller's folder list refetches) and picked as
  * the destination. Without `onCreateFolder` this is the bare select.
+ *
+ * The destination is a dependent write: the filter this editor commits binds to
+ * the folder, so `onCreateFolder` resolves only once the folder is confirmed on
+ * the mail server, not when the create is merely queued. The pending state holds
+ * "Creating folder…" for that whole wait, and a create that fails or never
+ * confirms rejects with its own message here — the folder is never selected, so
+ * the caller cannot commit a filter against a folder that does not exist.
  */
 function MoveDestinationField({
 	folders,
@@ -126,13 +157,21 @@ function MoveDestinationField({
 	folders: FolderOption[];
 	value: string;
 	onChangeMove?: (mailboxId: string) => void;
-	onCreateFolder?: (name: string) => Promise<FolderOption>;
+	onCreateFolder?: (
+		name: string,
+		signal?: AbortSignal,
+	) => Promise<FolderOption>;
 }) {
 	const [creating, setCreating] = useState(false);
 	const [name, setName] = useState("");
 	const [pending, setPending] = useState(false);
 	const [error, setError] = useState<string>();
 	const [createdFolders, setCreatedFolders] = useState<FolderOption[]>([]);
+	// The create waits for the mail server to confirm the folder; abort it on
+	// unmount or cancel so a late confirmation never binds the destination after
+	// the editor is gone or the sub-form dismissed.
+	const createAbort = useRef<AbortController | null>(null);
+	useEffect(() => () => createAbort.current?.abort(), []);
 
 	const options = useMemo(() => {
 		const known = new Set(folders.map((folder) => folder.id));
@@ -157,7 +196,10 @@ function MoveDestinationField({
 		if (trimmed === "") return;
 		setPending(true);
 		setError(undefined);
-		onCreateFolder(trimmed)
+		createAbort.current?.abort();
+		const controller = new AbortController();
+		createAbort.current = controller;
+		onCreateFolder(trimmed, controller.signal)
 			.then((folder) => {
 				setCreatedFolders((prev) =>
 					prev.some((entry) => entry.id === folder.id)
@@ -170,6 +212,7 @@ function MoveDestinationField({
 				setPending(false);
 			})
 			.catch((error: unknown) => {
+				if (isAbortError(error)) return;
 				setError(
 					error instanceof Error
 						? error.message
@@ -180,9 +223,11 @@ function MoveDestinationField({
 	};
 
 	const cancel = () => {
+		createAbort.current?.abort();
 		setCreating(false);
 		setName("");
 		setError(undefined);
+		setPending(false);
 	};
 
 	return (
@@ -234,7 +279,154 @@ function MoveDestinationField({
 							onClick={submit}
 							disabled={pending || name.trim() === ""}
 						>
-							{pending ? "Creating…" : "Create folder"}
+							{pending ? "Creating folder…" : "Create folder"}
+						</Button>
+						<Button
+							variant="ghost"
+							size="sm"
+							onClick={cancel}
+							disabled={pending}
+						>
+							Cancel
+						</Button>
+					</div>
+				</div>
+			)}
+		</div>
+	);
+}
+
+/**
+ * The apply-label select, plus an inline "New label…" affordance when the
+ * consumer wires `onCreateLabel` (issue #26). Mirrors `MoveDestinationField`:
+ * selecting the create option reveals a name field, and the created label is
+ * added to the local option set and picked immediately, before the caller's
+ * label list refetches.
+ */
+function LabelDestinationField({
+	labels,
+	value,
+	onChangeLabel,
+	onCreateLabel,
+}: {
+	labels: LabelOption[];
+	value: string;
+	onChangeLabel?: (labelId: string) => void;
+	onCreateLabel?: (name: string) => Promise<LabelOption>;
+}) {
+	const [creating, setCreating] = useState(false);
+	const [name, setName] = useState("");
+	const [pending, setPending] = useState(false);
+	const [error, setError] = useState<string>();
+	const [createdLabels, setCreatedLabels] = useState<LabelOption[]>([]);
+
+	const options = useMemo(() => {
+		const known = new Set(labels.map((label) => label.id));
+		return [
+			...labels,
+			...createdLabels.filter((label) => !known.has(label.id)),
+		];
+	}, [labels, createdLabels]);
+
+	const selected = options.find((label) => label.id === value);
+
+	const handleSelectChange = (next: string) => {
+		if (next === CREATE_LABEL_VALUE) {
+			setError(undefined);
+			setCreating(true);
+			return;
+		}
+		onChangeLabel?.(next);
+	};
+
+	const submit = () => {
+		if (!onCreateLabel) return;
+		const trimmed = name.trim();
+		if (trimmed === "") return;
+		setPending(true);
+		setError(undefined);
+		onCreateLabel(trimmed)
+			.then((label) => {
+				setCreatedLabels((prev) =>
+					prev.some((entry) => entry.id === label.id) ? prev : [...prev, label],
+				);
+				onChangeLabel?.(label.id);
+				setCreating(false);
+				setName("");
+				setPending(false);
+			})
+			.catch((error: unknown) => {
+				setError(
+					error instanceof Error
+						? error.message
+						: "Couldn't create that label. Please try again.",
+				);
+				setPending(false);
+			});
+	};
+
+	const cancel = () => {
+		setCreating(false);
+		setName("");
+		setError(undefined);
+	};
+
+	return (
+		<div className="space-y-2">
+			<div className="flex items-center gap-2">
+				<Select
+					aria-label="Label to apply"
+					value={value}
+					onChange={(event) => handleSelectChange(event.target.value)}
+					className="flex-1"
+				>
+					<option value="">No label</option>
+					{options.map((label) => (
+						<option key={label.id} value={label.id}>
+							{label.name}
+						</option>
+					))}
+					{onCreateLabel && (
+						<option value={CREATE_LABEL_VALUE}>＋ New label…</option>
+					)}
+				</Select>
+				{selected && (
+					<LabelChip label={{ ...selected, labelId: selected.id }} />
+				)}
+			</div>
+			{creating && (
+				<div className="space-y-2 rounded-md border border-line bg-surface-sunken p-2">
+					<Input
+						value={name}
+						onChange={(event) => setName(event.target.value)}
+						placeholder="Label name"
+						aria-label="New label name"
+						disabled={pending}
+						autoFocus
+						onKeyDown={(event) => {
+							if (event.key === "Enter") {
+								event.preventDefault();
+								submit();
+							}
+							if (event.key === "Escape") {
+								event.preventDefault();
+								cancel();
+							}
+						}}
+					/>
+					{error && (
+						<p className="text-2xs text-danger" role="alert">
+							{error}
+						</p>
+					)}
+					<div className="flex gap-2">
+						<Button
+							variant="primary"
+							size="sm"
+							onClick={submit}
+							disabled={pending || name.trim() === ""}
+						>
+							{pending ? "Creating…" : "Create label"}
 						</Button>
 						<Button
 							variant="ghost"
@@ -254,6 +446,7 @@ function MoveDestinationField({
 export function FilterRuleEditor({
 	rule,
 	folders,
+	labels = [],
 	preview,
 	notice,
 	semanticAvailable = false,
@@ -272,6 +465,8 @@ export function FilterRuleEditor({
 	onChangeMatchOperator,
 	onChangeMove,
 	onCreateFolder,
+	onChangeLabel,
+	onCreateLabel,
 	onChangeScope,
 	onChangeName,
 	onChangeUntil,
@@ -386,15 +581,16 @@ export function FilterRuleEditor({
 						onChangeMove={onChangeMove}
 						onCreateFolder={onCreateFolder}
 					/>
-					<div className="flex items-center gap-2 pt-0.5">
-						<span className="inline-flex items-center gap-1.5 rounded-full bg-surface-sunken px-2 py-0.5 text-2xs font-medium text-fg-muted">
-							label them…
-						</span>
-						<span className="text-2xs text-fg-subtle">
-							Labeling isn't available yet — arrives with mail-labeling (RFC
-							031).
-						</span>
-					</div>
+				</section>
+
+				<section className="space-y-2">
+					<p className="text-xs font-medium text-fg-muted">Apply a label</p>
+					<LabelDestinationField
+						labels={labels}
+						value={rule.labelId ?? ""}
+						onChangeLabel={onChangeLabel}
+						onCreateLabel={onCreateLabel}
+					/>
 				</section>
 
 				<section className="space-y-2">

package/src/components/filter-rule.render.test.ts

@@ -21,6 +21,7 @@ import {
 	demoVocabularyRule,
 	type FilterRule,
 	type FolderOption,
+	type LabelOption,
 	matchJoinWord,
 	matchOperatorLabel,
 	type PreviewCount,
@@ -45,6 +46,11 @@ const FOLDERS: FolderOption[] = [
 	{ id: "mbx-archive", label: "Archive" },
 ];
 
+const LABELS: LabelOption[] = [
+	{ id: "lbl-receipts", name: "Receipts", color: "Blue" },
+	{ id: "lbl-travel", name: "Travel", color: "Green" },
+];
+
 const READY: PreviewCount = { status: "ready", count: 47 };
 
 const editor = (overrides: Partial<FilterRuleEditorProps> = {}) =>
@@ -161,10 +167,20 @@ describe("commitBlockedReason", () => {
 		);
 	});
 
-	it("asks for a folder when none is chosen", () => {
+	it("asks for a folder or a label when neither action is chosen", () => {
 		assert.match(
 			commitBlockedReason({ ...base, moveMailboxId: undefined }, fresh) ?? "",
-			/Pick a folder/,
+			/Pick a folder to move into, or a label to apply/,
+		);
+	});
+
+	it("a label alone is a sufficient action, no folder needed", () => {
+		assert.equal(
+			commitBlockedReason(
+				{ ...base, moveMailboxId: undefined, labelId: "lbl-1" },
+				fresh,
+			),
+			undefined,
 		);
 	});
 
@@ -505,10 +521,33 @@ describe("FilterRuleEditor", () => {
 		assert.match(html, /from sender/);
 	});
 
-	it("reserves a disabled label slot next to the move action", () => {
-		const html = editor();
-		assert.match(html, /label them…/);
-		assert.match(html, /Labeling isn.+available yet/);
+	it("offers the account's labels as the apply-label action", () => {
+		const html = editor({ labels: LABELS });
+		assert.match(html, /aria-label="Label to apply"/);
+		assert.match(html, /Receipts/);
+		assert.match(html, /Travel/);
+	});
+
+	it("renders a chip for the selected label", () => {
+		const html = editor({
+			labels: LABELS,
+			rule: { ...demoRule, labelId: "lbl-receipts" },
+		});
+		assert.match(html, /Receipts/);
+	});
+
+	it("offers no create option without onCreateLabel", () => {
+		const html = editor({ labels: LABELS });
+		assert.doesNotMatch(html, /New label…/);
+	});
+
+	it("offers the create option when onCreateLabel is wired", () => {
+		const html = editor({
+			labels: LABELS,
+			onCreateLabel: () =>
+				Promise.resolve({ id: "lbl-new", name: "New", color: "Default" }),
+		});
+		assert.match(html, /New label…/);
 	});
 
 	it("shows the scope toggle and names a standing rule", () => {

package/src/components/filter-rule.ts

@@ -62,6 +62,11 @@ export interface FilterRule {
 	widen?: RuleWiden;
 	/** The move-to-folder action's destination. Absent leaves mail in place. */
 	moveMailboxId?: string;
+	/**
+	 * The apply-label action's target (issue #26) — additive, so it can be set
+	 * alongside `moveMailboxId`. Absent applies no label.
+	 */
+	labelId?: string;
 	scope: RuleScope;
 	/** ISO 8601 civil date (`YYYY-MM-DD`) for the `until` scope. */
 	until?: string;
@@ -74,6 +79,12 @@ export interface FolderOption {
 	label: string;
 }
 
+export interface LabelOption {
+	id: string;
+	name: string;
+	color: string;
+}
+
 /**
  * The live match count (RFC 038 D1). `stale` marks a count the editor already
  * moved past — a clause changed after it was counted, so the number on screen
@@ -171,13 +182,13 @@ export function commitLabel(scope: RuleScope): string {
 
 /**
  * Why the rule cannot be saved yet, or `undefined` when it is ready. A rule
- * needs at least one live way to match, a folder to move into (the only wired
- * action), and — for the two persisted scopes — a name and, for `until`, a
- * date. It also needs a settled preview: the rule is committable only when the
- * count on screen is the count that will be applied. That makes RFC 038's
- * previewed-set-equals-applied-set contract structural — a consumer cannot save
- * a rule whose match count is still moving. Never disable a control without
- * saying why (ux.md).
+ * needs at least one live way to match, at least one action — move and/or
+ * label, either satisfies this (issue #26) — and, for the two persisted
+ * scopes, a name and, for `until`, a date. It also needs a settled preview:
+ * the rule is committable only when the count on screen is the count that
+ * will be applied. That makes RFC 038's previewed-set-equals-applied-set
+ * contract structural — a consumer cannot save a rule whose match count is
+ * still moving. Never disable a control without saying why (ux.md).
  */
 export function commitBlockedReason(
 	rule: FilterRule,
@@ -187,8 +198,8 @@ export function commitBlockedReason(
 		rule.clauses.length > 0 ||
 		(rule.widen !== undefined && !rule.widen.inactive);
 	if (!hasMatch) return "Add a clause so the rule has something to match.";
-	if (!rule.moveMailboxId)
-		return "Pick a folder to move matches into — labeling isn't available yet.";
+	if (!rule.moveMailboxId && !rule.labelId)
+		return "Pick a folder to move into, or a label to apply.";
 	if (
 		(rule.scope === "standing" || rule.scope === "until") &&
 		(rule.name ?? "").trim() === ""
@@ -211,6 +222,12 @@ export const demoFolders: FolderOption[] = [
 	{ id: "mbx-junk", label: "Junk" },
 ];
 
+export const demoLabels: LabelOption[] = [
+	{ id: "lbl-receipts", name: "Receipts", color: "Blue" },
+	{ id: "lbl-travel", name: "Travel", color: "Green" },
+	{ id: "lbl-urgent", name: "Urgent", color: "Red" },
+];
+
 export const demoRule: FilterRule = {
 	clauses: [
 		{ id: "c1", field: "From", value: "notifications@github.com" },

package/src/components/label-chip.render.test.ts

@@ -0,0 +1,45 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { LabelChip } from "./label-chip.js";
+
+describe("LabelChip", () => {
+	it("renders the label's name and a dot in its color", () => {
+		const html = renderToString(
+			createElement(LabelChip, {
+				label: { labelId: "l1", name: "Receipts", color: "Blue" },
+			}),
+		);
+		assert.match(html, /Receipts/);
+		assert.match(html, /bg-blue-500/);
+	});
+
+	it("falls back to the neutral dot for an unrecognized color", () => {
+		const html = renderToString(
+			createElement(LabelChip, {
+				label: { labelId: "l1", name: "Mystery", color: "Chartreuse" },
+			}),
+		);
+		assert.match(html, /bg-fg-subtle/);
+	});
+
+	it("renders no remove affordance without onRemove", () => {
+		const html = renderToString(
+			createElement(LabelChip, {
+				label: { labelId: "l1", name: "Receipts", color: "Blue" },
+			}),
+		);
+		assert.doesNotMatch(html, /Remove label/);
+	});
+
+	it("renders a remove button naming the label when onRemove is wired", () => {
+		const html = renderToString(
+			createElement(LabelChip, {
+				label: { labelId: "l1", name: "Receipts", color: "Blue" },
+				onRemove: () => undefined,
+			}),
+		);
+		assert.match(html, /aria-label="Remove label Receipts"/);
+	});
+});

package/src/components/label-chip.tsx

@@ -0,0 +1,49 @@
+import { cn } from "../lib/cn.js";
+import { isLabelColorValue, labelDotClass } from "../lib/label-color.js";
+
+export interface LabelChipData {
+	labelId: string;
+	name: string;
+	color: string;
+}
+
+export interface LabelChipProps {
+	label: LabelChipData;
+	/** Renders a remove affordance — the manual "just these" unlabel action. */
+	onRemove?: (labelId: string) => void;
+	className?: string;
+}
+
+/**
+ * A label applied to a message (issue #26) — a colored dot plus its name, the
+ * same shape a category badge or the widen chip takes. `color` renders from
+ * the literal palette (never a semantic tone): a label's color is a user
+ * choice, not a status the design system assigns meaning to.
+ */
+export function LabelChip({ label, onRemove, className }: LabelChipProps) {
+	const dotClass = isLabelColorValue(label.color)
+		? labelDotClass[label.color]
+		: labelDotClass.Default;
+
+	return (
+		<span
+			className={cn(
+				"inline-flex items-center gap-1 rounded-full bg-surface-sunken px-2 py-0.5 text-2xs font-medium text-fg-muted shrink-0",
+				className,
+			)}
+		>
+			<span className={cn("size-1.5 shrink-0 rounded-full", dotClass)} />
+			<span className="truncate">{label.name}</span>
+			{onRemove && (
+				<button
+					type="button"
+					onClick={() => onRemove(label.labelId)}
+					aria-label={`Remove label ${label.name}`}
+					className="ml-0.5 rounded-full text-fg-subtle hover:text-fg"
+				>
+					×
+				</button>
+			)}
+		</span>
+	);
+}

package/src/components/message-row.render.test.ts

@@ -35,6 +35,30 @@ describe("ComfortableRow", () => {
 		assert.notEqual(unread, read);
 		assert.match(unread, /font-semibold/);
 	});
+
+	it("renders a chip for every label applied to the message (issue #26)", () => {
+		const html = renderToString(
+			createElement(ComfortableRow, {
+				thread: {
+					...base,
+					isRead: true,
+					labels: [
+						{ labelId: "l1", name: "Receipts", color: "Blue" },
+						{ labelId: "l2", name: "Travel", color: "Green" },
+					],
+				},
+			}),
+		);
+		assert.match(html, /Receipts/);
+		assert.match(html, /Travel/);
+	});
+
+	it("renders no label chip when the message carries none", () => {
+		const html = renderToString(
+			createElement(ComfortableRow, { thread: { ...base, isRead: true } }),
+		);
+		assert.doesNotMatch(html, /Remove label/);
+	});
 });
 
 describe("ComfortableRow selection slot", () => {

package/src/components/message-row.tsx

@@ -5,6 +5,7 @@ import { LIST_ROW_ATTRIBUTE } from "../lib/roving-focus.js";
 import { categoryTone, type ThreadRowData } from "./app-shell-types.js";
 import { Avatar } from "./avatar.js";
 import { Badge } from "./badge.js";
+import { LabelChip } from "./label-chip.js";
 
 /** Visible keyboard-focus ring for a row reached by the list's arrow-key cursor. */
 const ROW_FOCUS_RING =
@@ -166,6 +167,9 @@ export function ComfortableRowTextContent({
 						{thread.category}
 					</Badge>
 				)}
+				{thread.labels?.map((label) => (
+					<LabelChip key={label.labelId} label={label} className="max-w-20" />
+				))}
 				{badge}
 			</span>
 		</span>

package/src/components/move-mailbox-picker.stories.tsx

@@ -112,3 +112,202 @@ export const CreateAndMove: Story = {
 	name: "Create folder from search",
 	render: () => <CreatePicker />,
 };
+
+/**
+ * Type a folder name into the search box and press the create-and-move row —
+ * used by the pending and error stories so each lands in its state without a
+ * manual click-through.
+ */
+async function typeAndCreate(canvasElement: HTMLElement, folderName: string) {
+	const setInputValue = Object.getOwnPropertyDescriptor(
+		HTMLInputElement.prototype,
+		"value",
+	)?.set;
+	const input = canvasElement.querySelector<HTMLInputElement>(
+		'input[type="search"]',
+	);
+	if (!input) return;
+	setInputValue?.call(input, folderName);
+	input.dispatchEvent(new Event("input", { bubbles: true }));
+	const createButton = Array.from(
+		canvasElement.querySelectorAll<HTMLButtonElement>("button"),
+	).find((button) => button.textContent?.includes(`Create "${folderName}"`));
+	createButton?.click();
+}
+
+/** Mirrors the web-client wait's honest timeout copy. */
+const TIMEOUT_MESSAGE =
+	"The folder was created but the mail server hasn't confirmed it yet, so nothing was attached to it. It's in your folder list — try again in a moment.";
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 60));
+
+const neverResolvesCreateFolder = (): Promise<MoveMailboxOption> =>
+	new Promise<MoveMailboxOption>(() => undefined);
+
+const rejectingCreateFolder =
+	(message: string) => (): Promise<MoveMailboxOption> =>
+		Promise.reject(new Error(message));
+
+/** Rejects the first attempt, resolves the retry — the resume the hook performs. */
+const failThenSucceedCreateFolder = () => {
+	let attempts = 0;
+	return (name: string): Promise<MoveMailboxOption> => {
+		attempts += 1;
+		return attempts === 1
+			? Promise.reject(new Error(TIMEOUT_MESSAGE))
+			: Promise.resolve({ id: "mbx-created", label: name });
+	};
+};
+
+/** Never resolves on its own; rejects with an AbortError when the signal aborts. */
+const abortAwareCreateFolder = (
+	_name: string,
+	signal?: AbortSignal,
+): Promise<MoveMailboxOption> =>
+	new Promise<MoveMailboxOption>((_resolve, reject) => {
+		signal?.addEventListener("abort", () =>
+			reject(new DOMException("Aborted", "AbortError")),
+		);
+	});
+
+/**
+ * The move is a dependent write on the folder: the create-and-move row does not
+ * resolve until the mail server confirms the folder, so the move never races the
+ * folder into existence. The wait shows as "Creating folder…".
+ */
+export const CreateFolderInFlight: Story = {
+	name: "Create folder — waiting for the server",
+	render: () => (
+		<MoveMailboxPicker
+			mailboxes={mailboxes}
+			onSelect={() => undefined}
+			onCreateFolder={neverResolvesCreateFolder}
+		/>
+	),
+	play: async ({ canvasElement }) => {
+		await typeAndCreate(canvasElement, "Taxes");
+	},
+};
+
+/**
+ * The folder create failed on the mail server. No move runs; the error is shown
+ * inline and the create row can be pressed again to retry.
+ */
+export const CreateFolderFailed: Story = {
+	name: "Create folder — failed (retry)",
+	render: () => (
+		<MoveMailboxPicker
+			mailboxes={mailboxes}
+			onSelect={() => undefined}
+			onCreateFolder={rejectingCreateFolder(
+				"The folder couldn't be created on the mail server. Please try again.",
+			)}
+		/>
+	),
+	play: async ({ canvasElement }) => {
+		await typeAndCreate(canvasElement, "Taxes");
+	},
+};
+
+/**
+ * The folder create was never confirmed within the wait bound — the timeout is
+ * named distinctly, and no move runs.
+ */
+export const CreateFolderTimedOut: Story = {
+	name: "Create folder — timed out (retry)",
+	render: () => (
+		<MoveMailboxPicker
+			mailboxes={mailboxes}
+			onSelect={() => undefined}
+			onCreateFolder={rejectingCreateFolder(TIMEOUT_MESSAGE)}
+		/>
+	),
+	play: async ({ canvasElement }) => {
+		await typeAndCreate(canvasElement, "Taxes");
+	},
+};
+
+/**
+ * Retry is a resume: the first create times out, and pressing the create row
+ * again with the same name resolves and moves — the hook re-waits on the folder
+ * it already made rather than re-creating it.
+ */
+export const CreateFolderRetrySucceeds: Story = {
+	name: "Create folder — retry resumes and moves",
+	render: () => {
+		const RetryStage = () => {
+			const [moved, setMoved] = useState<string | null>(null);
+			return (
+				<div className="flex flex-col">
+					<MoveMailboxPicker
+						mailboxes={mailboxes}
+						onSelect={setMoved}
+						onCreateFolder={failThenSucceedCreateFolder()}
+					/>
+					{moved && (
+						<p className="border-t border-line px-3 py-2 text-xs text-fg-muted">
+							Moved to {moved}
+						</p>
+					)}
+				</div>
+			);
+		};
+		return <RetryStage />;
+	},
+	play: async ({ canvasElement }) => {
+		await typeAndCreate(canvasElement, "Taxes");
+		await tick();
+		const retry = Array.from(
+			canvasElement.querySelectorAll<HTMLButtonElement>("button"),
+		).find((button) => button.textContent?.includes('Create "Taxes"'));
+		retry?.click();
+	},
+};
+
+/**
+ * Closing the picker while "Creating folder…" is in flight aborts the wait: the
+ * create promise rejects with an AbortError, so a folder that would confirm later
+ * never fires the move after the picker is gone. Here "Close picker" unmounts it
+ * mid-wait; no "Moved to" line appears.
+ */
+export const CreateFolderClosedMidWait: Story = {
+	name: "Create folder — closing aborts the move",
+	render: () => {
+		const AbortStage = () => {
+			const [open, setOpen] = useState(true);
+			const [moved, setMoved] = useState<string | null>(null);
+			return (
+				<div className="flex flex-col">
+					<button
+						type="button"
+						onClick={() => setOpen(false)}
+						className="border-b border-line px-3 py-2 text-left text-xs text-fg-muted"
+					>
+						Close picker
+					</button>
+					{open && (
+						<MoveMailboxPicker
+							mailboxes={mailboxes}
+							onSelect={setMoved}
+							onCreateFolder={abortAwareCreateFolder}
+						/>
+					)}
+					{moved && (
+						<p className="border-t border-line px-3 py-2 text-xs text-fg-muted">
+							Moved to {moved}
+						</p>
+					)}
+				</div>
+			);
+		};
+		return <AbortStage />;
+	},
+	play: async ({ canvasElement }) => {
+		await typeAndCreate(canvasElement, "Taxes");
+		await tick();
+		const close = Array.from(
+			canvasElement.querySelectorAll<HTMLButtonElement>("button"),
+		).find((button) => button.textContent?.trim() === "Close picker");
+		close?.click();
+	},
+};

package/src/components/move-mailbox-picker.tsx

@@ -7,6 +7,7 @@ import {
 	useRef,
 	useState,
 } from "react";
+import { isAbortError } from "../lib/abort.js";
 import { cn } from "../lib/cn.js";
 import { Input } from "./input.js";
 
@@ -60,10 +61,15 @@ export interface MoveMailboxPickerProps {
 	/**
 	 * Create a folder named by the current search query. When provided and the
 	 * query names no existing folder, a create-and-move row is offered at the
-	 * bottom of the list; resolving it yields the new folder, which is selected
-	 * (moved into) immediately. Absent means no create affordance renders.
+	 * bottom of the list; resolving it — once the mail server confirms the folder
+	 * — yields the new folder, which is selected (moved into). The picker aborts
+	 * the passed signal on unmount, so a folder that confirms after the picker is
+	 * closed never fires the move. Absent means no create affordance renders.
 	 */
-	onCreateFolder?: (name: string) => Promise<MoveMailboxOption>;
+	onCreateFolder?: (
+		name: string,
+		signal?: AbortSignal,
+	) => Promise<MoveMailboxOption>;
 	/**
 	 * Called when the user dismisses the picker via Escape. Trigger consumers
 	 * use this to close their popover/drawer; the picker never owns
@@ -153,6 +159,11 @@ export const MoveMailboxPicker = ({
 	);
 	const inputRef = useRef<HTMLInputElement>(null);
 	const optionRefs = useRef<Array<HTMLButtonElement | null>>([]);
+	// The create waits for the mail server to confirm the folder; abort it when
+	// the picker unmounts (its popover/drawer closes) so a late confirmation never
+	// fires the move after the picker is gone.
+	const createAbort = useRef<AbortController | null>(null);
+	useEffect(() => () => createAbort.current?.abort(), []);
 
 	useEffect(() => {
 		if (autoFocus) inputRef.current?.focus();
@@ -206,12 +217,16 @@ export const MoveMailboxPicker = ({
 		if (name === "") return;
 		setCreating(true);
 		setCreateError(undefined);
-		onCreateFolder(name)
+		createAbort.current?.abort();
+		const controller = new AbortController();
+		createAbort.current = controller;
+		onCreateFolder(name, controller.signal)
 			.then((folder) => {
 				onSelect(folder.id);
 				setCreating(false);
 			})
 			.catch((error: unknown) => {
+				if (isAbortError(error)) return;
 				setCreateError(
 					error instanceof Error ? error.message : text.createError,
 				);

package/src/index.ts

@@ -144,11 +144,13 @@ export {
 	commitBlockedReason,
 	commitLabel,
 	demoFolders,
+	demoLabels,
 	demoRule,
 	demoSenderFallbackRule,
 	demoVocabularyRule,
 	type FilterRule,
 	type FolderOption,
+	type LabelOption,
 	type MatchOperator,
 	matchJoinWord,
 	matchOperatorLabel,
@@ -221,6 +223,11 @@ export {
 	KeyboardHintBar,
 	type KeyboardHintBarProps,
 } from "./components/keyboard-hint-bar.js";
+export {
+	LabelChip,
+	type LabelChipData,
+	type LabelChipProps,
+} from "./components/label-chip.js";
 export { ListItem, type ListItemProps } from "./components/list-item.js";
 export {
 	type MailAction,
@@ -555,6 +562,12 @@ export {
 	sanitizeInlineStyle,
 	sanitizeStyleElementCss,
 } from "./lib/email-sanitizer.js";
+export {
+	isLabelColorValue,
+	type LabelColorValue,
+	labelColorOptions,
+	labelDotClass,
+} from "./lib/label-color.js";
 export {
 	LIST_ROW_ATTRIBUTE,
 	LIST_ROW_SELECTOR,

package/src/lib/abort.ts

@@ -0,0 +1,11 @@
+/**
+ * True for the rejection an aborted `AbortSignal` produces (a `DOMException`
+ * named `AbortError`, or any error carrying that name). A create affordance that
+ * is unmounted or cancelled aborts its in-flight folder create; the rejection is
+ * expected, not a failure to show — the surface is already gone.
+ */
+export const isAbortError = (error: unknown): boolean =>
+	typeof error === "object" &&
+	error !== null &&
+	"name" in error &&
+	(error as { name?: unknown }).name === "AbortError";

package/src/lib/label-color.test.ts

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	isLabelColorValue,
+	labelColorOptions,
+	labelDotClass,
+} from "./label-color.js";
+
+describe("label-color", () => {
+	it("every listed option resolves to a dot class", () => {
+		for (const color of labelColorOptions) {
+			assert.ok(labelDotClass[color]);
+		}
+	});
+
+	it("recognizes every named color value", () => {
+		for (const color of labelColorOptions) {
+			assert.ok(isLabelColorValue(color));
+		}
+	});
+
+	it("rejects a value outside the named set", () => {
+		assert.equal(isLabelColorValue("Chartreuse"), false);
+	});
+});

package/src/lib/label-color.ts

@@ -0,0 +1,46 @@
+/**
+ * A user-picked label color (RFC 030, issue #26). Unlike the app's status
+ * tones (positive/warning/danger/…), a label's color carries no meaning the
+ * design system assigns — the user picked it to tell their own labels apart —
+ * so it renders from the literal Tailwind palette rather than a semantic
+ * token.
+ */
+export type LabelColorValue =
+	| "Default"
+	| "Red"
+	| "Orange"
+	| "Yellow"
+	| "Green"
+	| "Teal"
+	| "Blue"
+	| "Purple"
+	| "Gray";
+
+/** Solid dot color for a label swatch or chip. */
+export const labelDotClass: Record<LabelColorValue, string> = {
+	Default: "bg-fg-subtle",
+	Red: "bg-red-500",
+	Orange: "bg-orange-500",
+	Yellow: "bg-yellow-500",
+	Green: "bg-green-500",
+	Teal: "bg-teal-500",
+	Blue: "bg-blue-500",
+	Purple: "bg-purple-500",
+	Gray: "bg-gray-500",
+};
+
+/** Every color a label can be assigned, in picker order. */
+export const labelColorOptions: LabelColorValue[] = [
+	"Default",
+	"Red",
+	"Orange",
+	"Yellow",
+	"Green",
+	"Teal",
+	"Blue",
+	"Purple",
+	"Gray",
+];
+
+export const isLabelColorValue = (value: string): value is LabelColorValue =>
+	Object.hasOwn(labelDotClass, value);