@remit/web-client 0.0.65 → 0.0.66

package/src/hooks/useRulePreview.ts

@@ -0,0 +1,86 @@
+import { organizeOperationsPreviewOrganizeMutation } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { PreviewCount } from "@remit/ui";
+import { useMutation } from "@tanstack/react-query";
+import { useEffect, useRef, useState } from "react";
+import { buildOrganizeInput } from "@/lib/organize/organize-model";
+import {
+	derivePreview,
+	PREVIEW_DEBOUNCE_MS,
+	type PreviewState,
+	predicateSignature,
+} from "@/lib/organize/rule-model";
+import type { OrganizeMatchPredicate } from "@/lib/organize/sender-fallback";
+
+/**
+ * The live match count for the edited rule (RFC 038 D1). Every predicate change
+ * schedules a debounced `POST /organize/preview` and, until it lands, reports
+ * the last count as stale so the count never blanks and the commit gate can
+ * hold apply. Seeded with the widen probe's count, so opening the editor shows a
+ * settled number without an immediate re-fetch.
+ *
+ * Out-of-order responses are dropped: only the reply to the most recent request
+ * updates the count, so a slow early preview never overwrites a newer one. The
+ * server bounds the match, so a broad predicate over a large mailbox stays a
+ * single cheap request; the debounce is what keeps rapid edits from spamming it.
+ */
+export const useRulePreview = (
+	accountId: string | undefined,
+	predicate: OrganizeMatchPredicate,
+	seedCount: number,
+): PreviewCount => {
+	const mutation = useMutation(organizeOperationsPreviewOrganizeMutation());
+	const { mutateAsync } = mutation;
+	const currentSignature = predicateSignature(predicate);
+
+	const [state, setState] = useState<PreviewState>(() => ({
+		count: seedCount,
+		previewedSignature: currentSignature,
+	}));
+
+	const predicateRef = useRef(predicate);
+	predicateRef.current = predicate;
+	const latestRequested = useRef(currentSignature);
+
+	useEffect(() => {
+		if (!accountId) return;
+		if (currentSignature === state.previewedSignature) return;
+		if (currentSignature === state.errorSignature) return;
+
+		const handle = setTimeout(() => {
+			const signature = currentSignature;
+			latestRequested.current = signature;
+			mutateAsync({
+				path: { accountId },
+				body: buildOrganizeInput({ ...predicateRef.current }),
+			})
+				.then((response) => {
+					if (latestRequested.current !== signature) return;
+					setState({
+						count: response.matchedCount,
+						previewedSignature: signature,
+					});
+				})
+				.catch((error: unknown) => {
+					if (latestRequested.current !== signature) return;
+					setState((previous) => ({
+						...previous,
+						error:
+							error instanceof Error
+								? error.message
+								: "Couldn't count matches.",
+						errorSignature: signature,
+					}));
+				});
+		}, PREVIEW_DEBOUNCE_MS);
+
+		return () => clearTimeout(handle);
+	}, [
+		accountId,
+		currentSignature,
+		state.previewedSignature,
+		state.errorSignature,
+		mutateAsync,
+	]);
+
+	return derivePreview(state, currentSignature);
+};

package/src/lib/organize/rule-model.test.ts

@@ -0,0 +1,297 @@
+/**
+ * The rule ↔ predicate wiring behind the Organize chip editor (RFC 038 D1). The
+ * load-bearing contract lives here: the predicate the editor previews is exactly
+ * the predicate a commit applies, so the count on screen is the set that moves.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { FilterRule } from "@remit/ui";
+import { buildOrganizeInput } from "./organize-model";
+import {
+	buildInitialRule,
+	derivePreview,
+	normalizeClauseValue,
+	normalizeListId,
+	predicateSignature,
+	rulePredicate,
+	ruleToDraft,
+	SUPPORTED_CLAUSE_FIELDS,
+} from "./rule-model";
+
+describe("SUPPORTED_CLAUSE_FIELDS", () => {
+	it("offers every field the backend matcher now evaluates, ListId and FromDomain included (#262)", () => {
+		assert.deepEqual(SUPPORTED_CLAUSE_FIELDS, [
+			"From",
+			"Subject",
+			"HasWords",
+			"ListId",
+			"FromDomain",
+		]);
+	});
+});
+
+describe("normalizeListId", () => {
+	it("strips the bracketed identifier, trims, and case-folds — matching the backend", () => {
+		assert.equal(
+			normalizeListId("<Weekly.News.Example.com>"),
+			"weekly.news.example.com",
+		);
+		assert.equal(normalizeListId("  Weekly.News  "), "weekly.news");
+		assert.equal(normalizeListId(""), "");
+	});
+
+	it("only normalizes the ListId field, trimming the rest", () => {
+		assert.equal(
+			normalizeClauseValue("ListId", "<List.Example.COM>"),
+			"list.example.com",
+		);
+		assert.equal(normalizeClauseValue("From", "  a@x.com  "), "a@x.com");
+		assert.equal(
+			normalizeClauseValue("FromDomain", " github.com "),
+			"github.com",
+		);
+	});
+});
+
+describe("buildInitialRule", () => {
+	it("opens a semantic-capable rule on the widen anchor with no literal clauses", () => {
+		const rule = buildInitialRule({
+			anchorMessageId: "msg-1",
+			semanticUnavailable: false,
+			senders: [],
+			selectionCount: 3,
+		});
+		assert.equal(rule.clauses.length, 0);
+		assert.deepEqual(rule.widen, { anchorCount: 3 });
+		assert.equal(rule.matchOperator, "all");
+		assert.equal(rule.scope, "once");
+	});
+
+	it("opens the sender fallback on visible, editable derived From chips (#251)", () => {
+		const rule = buildInitialRule({
+			anchorMessageId: "msg-1",
+			semanticUnavailable: true,
+			senders: ["a@x.com", "b@y.com"],
+			selectionCount: 2,
+		});
+		assert.equal(rule.widen, undefined);
+		assert.equal(rule.matchOperator, "any");
+		assert.deepEqual(
+			rule.clauses.map((clause) => ({
+				field: clause.field,
+				value: clause.value,
+				derived: clause.derived,
+			})),
+			[
+				{ field: "From", value: "a@x.com", derived: true },
+				{ field: "From", value: "b@y.com", derived: true },
+			],
+		);
+	});
+
+	it("collapses senders sharing a registrable domain to one derived FromDomain chip (#262)", () => {
+		const rule = buildInitialRule({
+			semanticUnavailable: true,
+			senders: ["npm@github.com", "ci@sub.github.com"],
+			selectionCount: 2,
+		});
+		assert.equal(rule.matchOperator, "any");
+		assert.deepEqual(
+			rule.clauses.map((clause) => ({
+				field: clause.field,
+				value: clause.value,
+				derived: clause.derived,
+			})),
+			[{ field: "FromDomain", value: "github.com", derived: true }],
+		);
+	});
+
+	it("carries a Something-else seed's folder and scope", () => {
+		const rule = buildInitialRule({
+			anchorMessageId: "msg-1",
+			semanticUnavailable: false,
+			senders: [],
+			selectionCount: 1,
+			seedMailboxId: "mbx-archive",
+			seedScope: "standing",
+		});
+		assert.equal(rule.moveMailboxId, "mbx-archive");
+		assert.equal(rule.scope, "standing");
+	});
+
+	it("offers no widen when there is no anchor to ride on", () => {
+		const rule = buildInitialRule({
+			semanticUnavailable: false,
+			senders: [],
+			selectionCount: 0,
+		});
+		assert.equal(rule.widen, undefined);
+	});
+});
+
+const semanticRule: FilterRule = {
+	clauses: [{ id: "c1", field: "Subject", value: "receipt" }],
+	matchOperator: "all",
+	widen: { anchorCount: 2 },
+	moveMailboxId: "mbx-archive",
+	scope: "once",
+};
+
+describe("rulePredicate", () => {
+	it("includes the anchor while the widen is present and active", () => {
+		const predicate = rulePredicate(semanticRule, "msg-1");
+		assert.equal(predicate.anchorMessageId, "msg-1");
+		assert.equal(predicate.matchOperator, "And");
+		assert.deepEqual(predicate.literalClauses, [
+			{ field: "Subject", value: "receipt" },
+		]);
+	});
+
+	it("drops the anchor once the widen is removed", () => {
+		const predicate = rulePredicate(
+			{ ...semanticRule, widen: undefined },
+			"msg-1",
+		);
+		assert.equal(predicate.anchorMessageId, undefined);
+	});
+
+	it("drops the anchor for a widen the deployment cannot evaluate (D4 inactive)", () => {
+		const predicate = rulePredicate(
+			{ ...semanticRule, widen: { anchorCount: 2, inactive: true } },
+			"msg-1",
+		);
+		assert.equal(predicate.anchorMessageId, undefined);
+	});
+
+	it("maps the any operator to Or", () => {
+		const predicate = rulePredicate(
+			{ ...semanticRule, matchOperator: "any" },
+			"msg-1",
+		);
+		assert.equal(predicate.matchOperator, "Or");
+	});
+});
+
+describe("predicateSignature", () => {
+	it("is stable across identical predicates", () => {
+		assert.equal(
+			predicateSignature(rulePredicate(semanticRule, "msg-1")),
+			predicateSignature(rulePredicate(semanticRule, "msg-1")),
+		);
+	});
+
+	it("changes when a clause value changes", () => {
+		const changed: FilterRule = {
+			...semanticRule,
+			clauses: [{ id: "c1", field: "Subject", value: "invoice" }],
+		};
+		assert.notEqual(
+			predicateSignature(rulePredicate(semanticRule, "msg-1")),
+			predicateSignature(rulePredicate(changed, "msg-1")),
+		);
+	});
+
+	it("changes when the widen is removed", () => {
+		assert.notEqual(
+			predicateSignature(rulePredicate(semanticRule, "msg-1")),
+			predicateSignature(
+				rulePredicate({ ...semanticRule, widen: undefined }, "msg-1"),
+			),
+		);
+	});
+});
+
+describe("the previewed set equals the applied set", () => {
+	it("carries exactly the previewed predicate into the commit draft", () => {
+		const preview = buildOrganizeInput({
+			...rulePredicate(semanticRule, "msg-1"),
+			matchOperator: rulePredicate(semanticRule, "msg-1").matchOperator,
+			literalClauses: rulePredicate(semanticRule, "msg-1").literalClauses,
+		});
+		const apply = buildOrganizeInput(ruleToDraft(semanticRule, "msg-1"));
+		assert.equal(apply.anchorMessageId, preview.anchorMessageId);
+		assert.equal(apply.matchOperator, preview.matchOperator);
+		assert.deepEqual(apply.literalClauses, preview.literalClauses);
+	});
+
+	it("keeps them equal for the sender fallback (no anchor, Or)", () => {
+		const rule = buildInitialRule({
+			semanticUnavailable: true,
+			senders: ["a@x.com", "b@y.com"],
+			selectionCount: 2,
+		});
+		const predicate = rulePredicate(rule);
+		const apply = buildOrganizeInput(ruleToDraft(rule));
+		assert.equal(apply.anchorMessageId, undefined);
+		assert.equal(apply.matchOperator, "Or");
+		assert.deepEqual(apply.literalClauses, predicate.literalClauses);
+	});
+
+	it("adds the expiry only for the until scope, never touching the match set", () => {
+		const once = ruleToDraft(semanticRule, "msg-1");
+		assert.equal(once.expiresAt, undefined);
+
+		const until = ruleToDraft(
+			{ ...semanticRule, scope: "until", until: "2999-01-02" },
+			"msg-1",
+		);
+		assert.ok(until.expiresAt?.startsWith("2999-01-02"));
+		assert.deepEqual(until.literalClauses, once.literalClauses);
+		assert.equal(until.anchorMessageId, once.anchorMessageId);
+	});
+
+	it("carries the move destination into the draft", () => {
+		assert.equal(
+			ruleToDraft(semanticRule, "msg-1").moveMailboxId,
+			"mbx-archive",
+		);
+	});
+});
+
+describe("derivePreview", () => {
+	const signature = "sig-current";
+
+	it("is loading before the first count lands", () => {
+		assert.deepEqual(derivePreview({}, signature), { status: "loading" });
+	});
+
+	it("is ready when the count was counted for the current predicate", () => {
+		assert.deepEqual(
+			derivePreview({ count: 42, previewedSignature: signature }, signature),
+			{ status: "ready", count: 42 },
+		);
+	});
+
+	it("goes stale — never blank — when the predicate has moved past the count", () => {
+		assert.deepEqual(
+			derivePreview({ count: 42, previewedSignature: "sig-old" }, signature),
+			{ status: "ready", count: 42, stale: true },
+		);
+	});
+
+	it("surfaces an error raised for the current predicate", () => {
+		assert.deepEqual(
+			derivePreview(
+				{ count: 1, error: "boom", errorSignature: signature },
+				signature,
+			),
+			{ status: "error", reason: "boom" },
+		);
+	});
+
+	it("ignores an error raised for a predicate already moved past", () => {
+		assert.deepEqual(
+			derivePreview(
+				{
+					count: 5,
+					previewedSignature: signature,
+					error: "boom",
+					errorSignature: "sig-old",
+				},
+				signature,
+			),
+			{ status: "ready", count: 5 },
+		);
+	});
+});

package/src/lib/organize/rule-model.ts

@@ -0,0 +1,205 @@
+import type {
+	ClauseField,
+	FilterRule,
+	MatchOperator,
+	PreviewCount,
+	RuleClause,
+	RuleScope,
+} from "@remit/ui";
+import { pickedDateToExpiresAt } from "./filter-status";
+import type { OrganizeDraft } from "./organize-model";
+import {
+	deriveSenderClauses,
+	type OrganizeMatchPredicate,
+} from "./sender-fallback";
+
+/**
+ * The clause fields the Organize editor may offer (RFC 038 D2). Gated on what
+ * the backend matcher evaluates, not on what the generated enum carries: every
+ * one of these is honored by the literal matcher and the back-apply corpus
+ * projection (match.ts), so a chip never previews a set the apply can't
+ * reproduce. `ListId` and `FromDomain` joined once their matcher shipped (#262).
+ */
+export const SUPPORTED_CLAUSE_FIELDS: ClauseField[] = [
+	"From",
+	"Subject",
+	"HasWords",
+	"ListId",
+	"FromDomain",
+];
+
+/**
+ * Canonical form of a `ListId` clause value, matching the backend's
+ * `normalizeListId` (list-id.ts): the bracketed identifier when present,
+ * otherwise the whole value, trimmed and case-folded. Normalizing at input keeps
+ * the chip the user sees identical to the value the matcher compares, so
+ * `<weekly.news.example.com>` and `Weekly.News.Example.com` are one list.
+ */
+export const normalizeListId = (value: string): string => {
+	const trimmed = value.trim();
+	const bracketed = trimmed.match(/<([^>]+)>/);
+	return (bracketed ? bracketed[1] : trimmed).trim().toLowerCase();
+};
+
+/** Canonicalize a clause value for its field before it becomes a chip. */
+export const normalizeClauseValue = (
+	field: ClauseField,
+	value: string,
+): string => (field === "ListId" ? normalizeListId(value) : value.trim());
+
+const toApiOperator = (operator: MatchOperator): "And" | "Or" =>
+	operator === "all" ? "And" : "Or";
+
+export interface InitialRuleInput {
+	/** The semantic anchor — the first selected message. */
+	anchorMessageId?: string;
+	/**
+	 * The deployment ships no vector pipeline, so the widen cannot run. The rule
+	 * opens on the sender-derived literal clauses instead of an anchor.
+	 */
+	semanticUnavailable: boolean;
+	/** Distinct sender addresses of the selection, for the fallback clauses. */
+	senders: readonly string[];
+	/** How many messages the selection holds — the widen's anchor count. */
+	selectionCount: number;
+	/** A folder a "Something else" shortcut pre-picked. */
+	seedMailboxId?: string;
+	/** A scope a "Something else" shortcut pre-picked. */
+	seedScope?: RuleScope;
+}
+
+/**
+ * The rule the editor opens on, built from the widen probe. A semantic-capable
+ * deployment opens on the widen chip (the anchor, no literal clauses); one
+ * without the vector pipeline opens on the sender-fallback `From` chips (#251),
+ * visible and editable, matched with `Or`. Either way the move destination and
+ * scope come from any "Something else" seed.
+ */
+export const buildInitialRule = (input: InitialRuleInput): FilterRule => {
+	const scope = input.seedScope ?? "once";
+	if (input.semanticUnavailable) {
+		// The same derivation the widen fallback runs (#251, #262): one `From`
+		// clause per sender, or a single `FromDomain` clause when they share a
+		// registrable domain. Surfaced as ordinary editable chips.
+		const clauses: RuleClause[] = deriveSenderClauses(input.senders).map(
+			(clause, index) => ({
+				id: `derived-${index}`,
+				field: clause.field,
+				value: clause.value,
+				derived: true,
+			}),
+		);
+		return {
+			clauses,
+			matchOperator: "any",
+			moveMailboxId: input.seedMailboxId,
+			scope,
+			name: "",
+		};
+	}
+	return {
+		clauses: [],
+		matchOperator: "all",
+		widen: input.anchorMessageId
+			? { anchorCount: Math.max(input.selectionCount, 1) }
+			: undefined,
+		moveMailboxId: input.seedMailboxId,
+		scope,
+		name: "",
+	};
+};
+
+/**
+ * The match-relevant projection of a rule — the anchor (only while the widen is
+ * present and active), the operator, and the literal clauses. Preview and apply
+ * both derive from this, so the set the editor counts is the set a commit acts
+ * on. Fields that do not change the match set (folder, scope, name, date) are
+ * deliberately absent.
+ */
+export const rulePredicate = (
+	rule: FilterRule,
+	anchorMessageId?: string,
+): OrganizeMatchPredicate => {
+	const widenActive = rule.widen !== undefined && !rule.widen.inactive;
+	const literalClauses = rule.clauses.map((clause) => ({
+		field: clause.field,
+		value: clause.value,
+	}));
+	return {
+		...(widenActive && anchorMessageId ? { anchorMessageId } : {}),
+		matchOperator: toApiOperator(rule.matchOperator),
+		literalClauses,
+	};
+};
+
+/**
+ * A stable key for a predicate's match set. Two predicates with the same key
+ * match the same messages; a change to the key is what marks the live count
+ * stale and schedules the next preview.
+ */
+export const predicateSignature = (predicate: OrganizeMatchPredicate): string =>
+	JSON.stringify({
+		anchor: predicate.anchorMessageId ?? null,
+		operator: predicate.matchOperator,
+		clauses: predicate.literalClauses.map(
+			(clause) => `${clause.field} ${clause.value}`,
+		),
+	});
+
+/**
+ * The commit draft for a rule. The match fields are exactly
+ * {@link rulePredicate}'s — the previewed predicate — with the folder action
+ * and, for the `until` scope, the derived expiry added. The expiry never enters
+ * the match set, so preview and apply still count and act on the same messages.
+ */
+export const ruleToDraft = (
+	rule: FilterRule,
+	anchorMessageId?: string,
+): OrganizeDraft => {
+	const predicate = rulePredicate(rule, anchorMessageId);
+	return {
+		...(predicate.anchorMessageId
+			? { anchorMessageId: predicate.anchorMessageId }
+			: {}),
+		matchOperator: predicate.matchOperator,
+		literalClauses: predicate.literalClauses,
+		moveMailboxId: rule.moveMailboxId,
+		expiresAt:
+			rule.scope === "until"
+				? pickedDateToExpiresAt(rule.until ?? "")
+				: undefined,
+	};
+};
+
+export interface PreviewState {
+	/** The last count that came back, `undefined` before the first lands. */
+	count?: number;
+	/** The signature the {@link count} was counted for. */
+	previewedSignature?: string;
+	/** The signature the last error was raised for. */
+	errorSignature?: string;
+	error?: string;
+}
+
+/**
+ * The live count for the rule on screen. The count is `ready` only when it was
+ * counted for the current predicate; a predicate change since then reads
+ * `stale` (recounting, never blank) so the commit gate can hold apply until it
+ * settles.
+ */
+export const derivePreview = (
+	state: PreviewState,
+	currentSignature: string,
+): PreviewCount => {
+	if (state.error !== undefined && state.errorSignature === currentSignature) {
+		return { status: "error", reason: state.error };
+	}
+	if (state.count === undefined) return { status: "loading" };
+	if (state.previewedSignature === currentSignature) {
+		return { status: "ready", count: state.count };
+	}
+	return { status: "ready", count: state.count, stale: true };
+};
+
+/** How long a rule change settles before the next preview fires. */
+export const PREVIEW_DEBOUNCE_MS = 350;

package/src/components/mail/organize/OrganizePanel.progress.test.ts

@@ -1,113 +0,0 @@
-/**
- * The back-apply progress copy. On a deployment without the vector pipeline the
- * "all like these" job moves the sender-matched set, so the in-progress line must
- * state the sender semantics — never "similar mail" (#250's honesty
- * requirement). The semantic path keeps the "similar mail" wording.
- */
-
-import assert from "node:assert/strict";
-import { afterEach, describe, it } from "node:test";
-import { mailboxOperationsListMailboxesQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
-import { createElement } from "react";
-import type { OrganizeMatchPredicate } from "../../../lib/organize/sender-fallback";
-import { createDomHarness, type DomHarness } from "../../../test-support/dom";
-import { makeMailbox } from "../../../test-support/fixtures";
-import { type HttpMock, mockFetch } from "../../../test-support/http";
-import { OrganizePanel } from "./OrganizePanel";
-
-let harness: DomHarness | undefined;
-let http: HttpMock | undefined;
-
-afterEach(() => {
-	harness?.close();
-	harness = undefined;
-	http?.restore();
-	http = undefined;
-});
-
-const ACCOUNT_ID = "acc-1";
-
-const MAILBOXES = [
-	makeMailbox({ mailboxId: "mbx-inbox", fullPath: "INBOX" }),
-	makeMailbox({ mailboxId: "mbx-archive", fullPath: "Archive" }),
-];
-
-const SEMANTIC_PREDICATE: OrganizeMatchPredicate = {
-	anchorMessageId: "msg-1",
-	matchOperator: "And",
-	literalClauses: [],
-};
-
-const SENDER_PREDICATE: OrganizeMatchPredicate = {
-	matchOperator: "Or",
-	literalClauses: [{ field: "From", value: "npm@github.com" }],
-};
-
-const mount = (
-	props: Partial<Parameters<typeof OrganizePanel>[0]>,
-): DomHarness => {
-	http = mockFetch((call) => {
-		if (call.path.endsWith("/organize") && call.method === "POST") {
-			return { organizeJobId: "job-1", state: "Processing" };
-		}
-		if (call.path.endsWith("/organize/job-1") && call.method === "GET") {
-			return {
-				organizeJobId: "job-1",
-				state: "Processing",
-				matchedCount: 128,
-				appliedCount: 0,
-				failedCount: 0,
-			};
-		}
-		return {};
-	});
-	harness = createDomHarness();
-	harness.queryClient.setQueryData(
-		mailboxOperationsListMailboxesQueryKey({ path: { accountId: ACCOUNT_ID } }),
-		{ items: MAILBOXES },
-	);
-	harness.renderApp(
-		createElement(OrganizePanel, {
-			accountId: ACCOUNT_ID,
-			mailboxId: "mbx-inbox",
-			selectedMessageIds: ["msg-1", "msg-2"],
-			matchPredicate: SEMANTIC_PREDICATE,
-			matchedCount: 128,
-			seedMailboxId: "mbx-archive",
-			onClose: () => undefined,
-			...props,
-		}),
-	);
-	return harness;
-};
-
-async function startJob(dom: DomHarness): Promise<void> {
-	dom.click(dom.byText("button", "Organize"));
-	for (let attempt = 0; attempt < 20; attempt += 1) {
-		await dom.flush();
-		if (/Organizing/.test(dom.text())) return;
-		await dom.wait(1);
-	}
-}
-
-describe("OrganizePanel back-apply progress copy", () => {
-	it("states the sender semantics while organizing in the sender fallback", async () => {
-		const dom = mount({
-			matchPredicate: SENDER_PREDICATE,
-			semanticUnavailable: true,
-			senders: ["npm@github.com"],
-		});
-		await startJob(dom);
-
-		assert.match(dom.text(), /Organizing mail from these senders/);
-		assert.doesNotMatch(dom.text(), /Organizing similar mail/);
-	});
-
-	it("keeps the similar-mail wording on the semantic path", async () => {
-		const dom = mount({});
-		await startJob(dom);
-
-		assert.match(dom.text(), /Organizing similar mail/);
-		assert.doesNotMatch(dom.text(), /from these senders/);
-	});
-});