@remit/web-client 0.0.66 → 0.0.68

package/src/components/settings/FiltersList.render.test.ts

@@ -31,12 +31,17 @@ const filter = (
 	...overrides,
 });
 
-const render = (filters: RemitImapFilterResponse[]) =>
+const render = (
+	filters: RemitImapFilterResponse[],
+	semanticUnavailable = false,
+) =>
 	renderToString(
 		createElement(FiltersList, {
 			filters,
 			mailboxName: (id: string) => (id === "mbx-travel" ? "Travel" : undefined),
+			onEdit: () => undefined,
 			onDelete: () => undefined,
+			semanticUnavailable,
 			now: NOW,
 		}) as never,
 	);
@@ -54,6 +59,27 @@ describe("FiltersList", () => {
 		assert.match(html, /always/);
 	});
 
+	it("opens the row's rule in the editor", () => {
+		const html = render([filter({})]);
+		assert.match(html, /Edit filter Travel/);
+	});
+
+	it("shows the widen chip for an anchored filter where the deployment can serve it", () => {
+		const html = render([filter({ hasAnchor: true })]);
+		assert.match(html, /and anything similar/i);
+	});
+
+	it("lists the widen chip inactive on a deployment that cannot evaluate it (D4)", () => {
+		const html = render([filter({ hasAnchor: true })], true);
+		assert.match(html, /not available here/i);
+		assert.doesNotMatch(html, /and anything similar/i);
+	});
+
+	it("shows no widen chip for a purely literal filter", () => {
+		const html = render([filter({ hasAnchor: false })]);
+		assert.doesNotMatch(html, /similar/i);
+	});
+
 	it("keeps an expired temporary filter visible and marks it Expired (RFC 034 Decision 1.2)", () => {
 		const html = render([
 			filter({

package/src/components/settings/FiltersList.tsx

@@ -1,5 +1,5 @@
 import type { RemitImapFilterResponse } from "@remit/api-http-client/types.gen.ts";
-import { Badge, Button } from "@remit/ui";
+import { Badge, Button, WidenChip } from "@remit/ui";
 import { Trash2 } from "lucide-react";
 import {
 	filterDisplayStatus,
@@ -11,21 +11,34 @@ interface FiltersListProps {
 	filters: RemitImapFilterResponse[];
 	/** Resolve a destination mailbox id to a folder name for display. */
 	mailboxName: (mailboxId: string) => string | undefined;
+	/** Open the row's rule in the editor (RFC 038 D6). */
+	onEdit: (filterId: string) => void;
 	onDelete: (filterId: string) => void;
 	deletingFilterId?: string;
+	/**
+	 * This deployment ships no vector pipeline (RFC 038 D4). A filter carrying a
+	 * semantic anchor lists with its widen chip inactive — it matches by its
+	 * literal clauses only.
+	 */
+	semanticUnavailable?: boolean;
 	/** Injected for deterministic status in tests; defaults to now. */
 	now?: number;
 }
 
 /**
- * The account's standing filters. Expired temporary filters stay listed and
- * are marked Expired distinctly rather than hidden (RFC 034 Decision 1.2).
+ * The account's standing filters, each opening its rule in the editor (RFC 038
+ * D6). Expired temporary filters stay listed and are marked Expired distinctly
+ * rather than hidden (RFC 034 Decision 1.2). A filter with a semantic anchor
+ * shows the widen chip — inactive where this deployment cannot evaluate it
+ * (D4), so the list says honestly that it matches by literal clauses only.
  */
 export function FiltersList({
 	filters,
 	mailboxName,
+	onEdit,
 	onDelete,
 	deletingFilterId,
+	semanticUnavailable = false,
 	now = Date.now(),
 }: FiltersListProps) {
 	if (filters.length === 0) {
@@ -53,7 +66,12 @@ export function FiltersList({
 						key={filter.filterId}
 						className="flex items-start gap-3 px-3 py-2.5"
 					>
-						<div className="min-w-0 flex-1">
+						<button
+							type="button"
+							onClick={() => onEdit(filter.filterId)}
+							aria-label={`Edit filter ${filter.name}`}
+							className="min-w-0 flex-1 rounded-sm text-left hover:opacity-80"
+						>
 							<div className="flex items-center gap-2">
 								<span
 									className={`truncate text-sm font-medium ${
@@ -76,7 +94,17 @@ export function FiltersList({
 										? " · always"
 										: ""}
 							</p>
-						</div>
+							{filter.hasAnchor && (
+								<div className="mt-1.5 flex flex-wrap gap-1.5">
+									<WidenChip
+										widen={{
+											anchorCount: 1,
+											...(semanticUnavailable ? { inactive: true } : {}),
+										}}
+									/>
+								</div>
+							)}
+						</button>
 						<Button
 							variant="ghost"
 							size="sm"

package/src/components/settings/settings-filter.stories.tsx

@@ -0,0 +1,165 @@
+import type { RemitImapFilterResponse } from "@remit/api-http-client/types.gen.ts";
+import { BottomSheet, type FolderOption } from "@remit/ui";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+import { ErrorBannerProvider } from "@/components/ui/ErrorBannerProvider";
+import { FilterEditor } from "./FilterEditor";
+
+/**
+ * `Flows/Settings Filters` — editing a standing filter in the same chip editor
+ * the Organize surface uses (RFC 038 D6), rendered from the real web-client
+ * component the settings page mounts. Each story opens a persisted filter into
+ * the editor: a literal rule, an anchored rule with its widen chip, an
+ * until-a-date rule, and the degraded case where the deployment cannot evaluate
+ * the anchor and the widen lists inactive (D4).
+ */
+
+const ACCOUNT_ID = "acc-1";
+
+const FOLDERS: FolderOption[] = [
+	{ id: "mbx-inbox", label: "Inbox" },
+	{ id: "mbx-archive", label: "Archive" },
+	{ id: "mbx-receipts", label: "Receipts" },
+	{ id: "mbx-travel", label: "Travel" },
+];
+
+const makeFilter = (
+	overrides: Partial<RemitImapFilterResponse> = {},
+): RemitImapFilterResponse => ({
+	filterId: "f-1",
+	accountConfigId: ACCOUNT_ID,
+	name: "Receipts",
+	scope: "Standing",
+	state: "Active",
+	hasAnchor: false,
+	ruleChangedAt: 0,
+	matchOperator: "And",
+	literalClauses: [
+		{ field: "From", value: "receipts@stripe.com" },
+		{ field: "Subject", value: "invoice" },
+	],
+	actionLabelId: "None",
+	actionMailboxId: "mbx-receipts",
+	createdAt: 0,
+	updatedAt: 0,
+	...overrides,
+});
+
+/**
+ * A bare client with no backend. The editor opens on `loading` and its preview
+ * settles to the count region's error state — these stories exercise the editor
+ * chrome (chips, read-only lifecycle, the widen chip), not the live count.
+ */
+function seededClient(): QueryClient {
+	return new QueryClient({
+		defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+	});
+}
+
+/** Phone frame + a bottom sheet holding the editor, mirroring the mobile home. */
+function SheetStage({ children }: { children: ReactNode }) {
+	return (
+		<QueryClientProvider client={seededClient()}>
+			<ErrorBannerProvider>
+				<div className="relative mx-auto h-dvh w-full shrink-0 overflow-hidden bg-surface sm:my-6 sm:h-[760px] sm:w-[390px] sm:rounded-[2rem] sm:border sm:border-line sm:shadow-sm">
+					<div className="divide-y divide-line opacity-50">
+						{Array.from({ length: 8 }).map((_, index) => (
+							<div
+								// biome-ignore lint/suspicious/noArrayIndexKey: static backdrop skeleton, no ids
+								key={index}
+								className="flex items-start gap-3 px-row-inset py-2.5"
+							>
+								<div className="mt-0.5 size-7 shrink-0 rounded-full bg-surface-sunken" />
+								<div className="min-w-0 flex-1 space-y-1">
+									<div className="h-2.5 w-1/3 rounded bg-surface-sunken" />
+									<div className="h-2 w-2/3 rounded bg-surface-sunken" />
+								</div>
+							</div>
+						))}
+					</div>
+					<BottomSheet open onClose={() => undefined}>
+						{children}
+					</BottomSheet>
+				</div>
+			</ErrorBannerProvider>
+		</QueryClientProvider>
+	);
+}
+
+const meta: Meta = {
+	title: "Flows/Settings Filters",
+	parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+type Story = StoryObj;
+
+/** A standing literal filter opened for editing. */
+export const EditStandingRule: Story = {
+	name: "Edit Standing Rule",
+	render: () => (
+		<SheetStage>
+			<FilterEditor
+				accountId={ACCOUNT_ID}
+				filter={makeFilter()}
+				folders={FOLDERS}
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/** A filter with a semantic anchor — the widen lists as an active chip. */
+export const EditAnchoredRule: Story = {
+	name: "Edit Anchored Rule",
+	render: () => (
+		<SheetStage>
+			<FilterEditor
+				accountId={ACCOUNT_ID}
+				filter={makeFilter({ hasAnchor: true, name: "GitHub" })}
+				folders={FOLDERS}
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/** A temporary filter — the scope loads as until-a-date with the stored date. */
+export const EditUntilADate: Story = {
+	name: "Edit Until A Date",
+	render: () => (
+		<SheetStage>
+			<FilterEditor
+				accountId={ACCOUNT_ID}
+				filter={makeFilter({
+					name: "Conference",
+					scope: "Temporary",
+					expiresAt: "2027-09-01T23:59:59+00:00",
+				})}
+				folders={FOLDERS}
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};
+
+/**
+ * The deployment cannot evaluate the filter's anchor (RFC 038 D4): the widen
+ * chip lists inactive, the rule matches by its literal clauses only, and the
+ * dead anchor is removable.
+ */
+export const DegradedAnchor: Story = {
+	name: "Degraded Anchor",
+	render: () => (
+		<SheetStage>
+			<FilterEditor
+				accountId={ACCOUNT_ID}
+				filter={makeFilter({ hasAnchor: true, name: "Newsletters" })}
+				folders={FOLDERS}
+				semanticUnavailable
+				onClose={() => undefined}
+			/>
+		</SheetStage>
+	),
+};

package/src/hooks/useRuleEditorState.ts

@@ -0,0 +1,174 @@
+import type {
+	ClauseEditState,
+	ClauseField,
+	FilterRule,
+	MatchOperator,
+	RuleScope,
+} from "@remit/ui";
+import { useRef, useState } from "react";
+import {
+	normalizeClauseValue,
+	SUPPORTED_CLAUSE_FIELDS,
+} from "@/lib/organize/rule-model";
+
+export interface RuleEditorState {
+	rule: FilterRule;
+	setRule: (updater: (current: FilterRule) => FilterRule) => void;
+	/** The clause-editing and rule-mutation handlers a {@link FilterRuleEditor} binds. */
+	handlers: {
+		clauseEdit: ClauseEditState | undefined;
+		onStartAddClause: () => void;
+		onStartEditClause: (clauseId: string) => void;
+		onRemoveClause: (clauseId: string) => void;
+		onChangeDraftField: (field: ClauseField) => void;
+		onChangeDraftValue: (value: string) => void;
+		onSubmitClause: () => void;
+		onCancelClause: () => void;
+		onAddWiden: () => void;
+		onRemoveWiden: () => void;
+		onChangeMatchOperator: (matchOperator: MatchOperator) => void;
+		onChangeMove: (mailboxId: string) => void;
+		onChangeScope: (scope: RuleScope) => void;
+		onChangeName: (name: string) => void;
+		onChangeUntil: (until: string) => void;
+	};
+}
+
+interface RuleEditorStateInput {
+	/** The rule the editor opens on. */
+	initialRule: FilterRule;
+	/**
+	 * How many anchors a widen the user adds inline should carry. A search-seeded
+	 * rule has no message anchor, so its editor never offers the widen and this is
+	 * unused; the Organize editor passes its selection size.
+	 */
+	widenAnchorCount?: number;
+}
+
+/**
+ * The clause-editing and rule-mutation state a filter-rule editor owns, shared by
+ * every entry point onto the chip editor (RFC 038 D1) so the Organize and
+ * search-derived surfaces edit the rule identically. Preview and commit stay with
+ * the caller — they differ by entry point (an anchored widen count and back-apply
+ * job for Organize, a literal count for a search-derived rule).
+ */
+export const useRuleEditorState = ({
+	initialRule,
+	widenAnchorCount = 1,
+}: RuleEditorStateInput): RuleEditorState => {
+	const [rule, setRuleState] = useState<FilterRule>(initialRule);
+	const [clauseEdit, setClauseEdit] = useState<ClauseEditState | undefined>();
+	const nextClauseId = useRef(0);
+
+	const setRule = (updater: (current: FilterRule) => FilterRule) =>
+		setRuleState(updater);
+
+	const startAddClause = () =>
+		setClauseEdit({
+			mode: "add",
+			draft: { field: SUPPORTED_CLAUSE_FIELDS[0], value: "" },
+		});
+
+	const startEditClause = (clauseId: string) => {
+		const clause = rule.clauses.find((entry) => entry.id === clauseId);
+		if (!clause) return;
+		setClauseEdit({
+			mode: "edit",
+			clauseId,
+			draft: { field: clause.field, value: clause.value },
+		});
+	};
+
+	const changeDraftField = (field: ClauseField) =>
+		setClauseEdit((edit) =>
+			edit ? { ...edit, draft: { ...edit.draft, field } } : edit,
+		);
+
+	const changeDraftValue = (value: string) =>
+		setClauseEdit((edit) =>
+			edit ? { ...edit, draft: { ...edit.draft, value } } : edit,
+		);
+
+	const submitClause = () => {
+		if (!clauseEdit) return;
+		const field = clauseEdit.draft.field;
+		const value = normalizeClauseValue(field, clauseEdit.draft.value);
+		if (value === "") return;
+		setRuleState((current) => {
+			if (clauseEdit.mode === "edit" && clauseEdit.clauseId) {
+				return {
+					...current,
+					clauses: current.clauses.map((clause) =>
+						clause.id === clauseEdit.clauseId
+							? { id: clause.id, field, value }
+							: clause,
+					),
+				};
+			}
+			nextClauseId.current += 1;
+			return {
+				...current,
+				clauses: [
+					...current.clauses,
+					{ id: `clause-${nextClauseId.current}`, field, value },
+				],
+			};
+		});
+		setClauseEdit(undefined);
+	};
+
+	const removeClause = (clauseId: string) =>
+		setRuleState((current) => ({
+			...current,
+			clauses: current.clauses.filter((clause) => clause.id !== clauseId),
+		}));
+
+	const addWiden = () =>
+		setRuleState((current) => ({
+			...current,
+			widen: { anchorCount: Math.max(widenAnchorCount, 1) },
+		}));
+
+	const removeWiden = () =>
+		setRuleState((current) => ({ ...current, widen: undefined }));
+
+	const changeMatchOperator = (matchOperator: MatchOperator) =>
+		setRuleState((current) => ({ ...current, matchOperator }));
+
+	const changeMove = (mailboxId: string) =>
+		setRuleState((current) => ({
+			...current,
+			moveMailboxId: mailboxId || undefined,
+		}));
+
+	const changeScope = (scope: RuleScope) =>
+		setRuleState((current) => ({ ...current, scope }));
+
+	const changeName = (name: string) =>
+		setRuleState((current) => ({ ...current, name }));
+
+	const changeUntil = (until: string) =>
+		setRuleState((current) => ({ ...current, until }));
+
+	return {
+		rule,
+		setRule,
+		handlers: {
+			clauseEdit,
+			onStartAddClause: startAddClause,
+			onStartEditClause: startEditClause,
+			onRemoveClause: removeClause,
+			onChangeDraftField: changeDraftField,
+			onChangeDraftValue: changeDraftValue,
+			onSubmitClause: submitClause,
+			onCancelClause: () => setClauseEdit(undefined),
+			onAddWiden: addWiden,
+			onRemoveWiden: removeWiden,
+			onChangeMatchOperator: changeMatchOperator,
+			onChangeMove: changeMove,
+			onChangeScope: changeScope,
+			onChangeName: changeName,
+			onChangeUntil: changeUntil,
+		},
+	};
+};

package/src/hooks/useRulePreview.ts

@@ -22,20 +22,25 @@ import type { OrganizeMatchPredicate } from "@/lib/organize/sender-fallback";
  * 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.
+ *
+ * `seedCount` is the opening count a widen probe already knows; omit it (as the
+ * settings editor does, having no probe) to open on `loading` and preview the
+ * loaded predicate immediately.
  */
 export const useRulePreview = (
 	accountId: string | undefined,
 	predicate: OrganizeMatchPredicate,
-	seedCount: number,
+	seedCount?: number,
 ): PreviewCount => {
 	const mutation = useMutation(organizeOperationsPreviewOrganizeMutation());
 	const { mutateAsync } = mutation;
 	const currentSignature = predicateSignature(predicate);
 
-	const [state, setState] = useState<PreviewState>(() => ({
-		count: seedCount,
-		previewedSignature: currentSignature,
-	}));
+	const [state, setState] = useState<PreviewState>(() =>
+		seedCount === undefined
+			? {}
+			: { count: seedCount, previewedSignature: currentSignature },
+	);
 
 	const predicateRef = useRef(predicate);
 	predicateRef.current = predicate;

package/src/hooks/useSearchFilterSeed.render.test.ts

@@ -0,0 +1,83 @@
+/**
+ * Opening the filter-from-search editor: the seed count comes from the converted
+ * literal predicate in one request, under the account the filter targets. No
+ * capability probe — the deployment's semantic reach is read from the search's
+ * own results on the surface, so a seed success is never blocked by a probe.
+ */
+
+import assert from "node:assert/strict";
+import { afterEach, describe, it } from "node:test";
+import { createElement } from "react";
+import type { OrganizeMatchPredicate } from "@/lib/organize/sender-fallback";
+import { createDomHarness, type DomHarness } from "../test-support/dom";
+import {
+	type HttpCall,
+	type HttpMock,
+	httpError,
+	mockFetch,
+} from "../test-support/http";
+import { useSearchFilterSeed } from "./useSearchFilterSeed";
+
+let harness: DomHarness | undefined;
+let http: HttpMock | undefined;
+
+afterEach(() => {
+	harness?.close();
+	harness = undefined;
+	http?.restore();
+	http = undefined;
+});
+
+const PREDICATE: OrganizeMatchPredicate = {
+	matchOperator: "And",
+	literalClauses: [{ field: "HasWords", value: "receipts" }],
+};
+
+function Probe() {
+	const seed = useSearchFilterSeed("acc-1", PREDICATE);
+	return createElement(
+		"div",
+		null,
+		JSON.stringify({
+			seedCount: seed.seedCount ?? null,
+			isPending: seed.isPending,
+			isError: seed.isError,
+		}),
+	);
+}
+
+const mount = (responder: (call: HttpCall) => unknown): DomHarness => {
+	http = mockFetch(responder);
+	harness = createDomHarness();
+	harness.renderApp(createElement(Probe));
+	return harness;
+};
+
+const state = (dom: DomHarness) => JSON.parse(dom.text());
+
+describe("useSearchFilterSeed", () => {
+	it("seeds the count from the literal predicate in a single preview", async () => {
+		const dom = mount((call) =>
+			call.path.endsWith("/organize/preview")
+				? { matchedCount: 12, messageIds: [] }
+				: {},
+		);
+		await dom.flush();
+		await dom.flush();
+		assert.equal(state(dom).seedCount, 12);
+		// One preview, carrying the literal clauses and no anchor.
+		const previews = http?.to("/organize/preview") ?? [];
+		assert.equal(previews.length, 1);
+		assert.equal(previews[0].body?.anchorMessageId, undefined);
+		assert.deepEqual(previews[0].body?.literalClauses, [
+			{ field: "HasWords", value: "receipts" },
+		]);
+	});
+
+	it("surfaces the seed error so the caller can offer a retry", async () => {
+		const dom = mount(() => httpError(500));
+		await dom.flush();
+		await dom.flush();
+		assert.equal(state(dom).isError, true);
+	});
+});

package/src/hooks/useSearchFilterSeed.ts

@@ -0,0 +1,61 @@
+import { organizeOperationsPreviewOrganizeMutation } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation } from "@tanstack/react-query";
+import { useCallback, useEffect } from "react";
+import { buildOrganizeInput } from "@/lib/organize/organize-model";
+import type { OrganizeMatchPredicate } from "@/lib/organize/sender-fallback";
+
+interface SearchFilterSeed {
+	/** The live count for the converted literal predicate, seeding the editor. */
+	seedCount?: number;
+	isPending: boolean;
+	isError: boolean;
+	error: unknown;
+	retry: () => void;
+}
+
+/**
+ * Open the filter-from-search editor: seed the live count from the converted
+ * literal predicate. One `POST /organize/preview` under the account the filter
+ * targets — the count on screen is the set a literal-only filter applies to.
+ *
+ * The deployment's semantic reach is not probed here; it is read from the
+ * search's own "Related" results on the surface that opens the editor (RFC 038
+ * D5), a direct signal that needs no request and cannot hit the wrong account.
+ */
+export const useSearchFilterSeed = (
+	accountId: string | undefined,
+	literalPredicate: OrganizeMatchPredicate,
+): SearchFilterSeed => {
+	const seed = useMutation(organizeOperationsPreviewOrganizeMutation());
+	const { mutate, reset } = seed;
+
+	const run = useCallback(() => {
+		if (!accountId) return;
+		reset();
+		mutate({
+			path: { accountId },
+			body: buildOrganizeInput({
+				matchOperator: literalPredicate.matchOperator,
+				literalClauses: literalPredicate.literalClauses,
+			}),
+		});
+	}, [
+		accountId,
+		literalPredicate.matchOperator,
+		literalPredicate.literalClauses,
+		mutate,
+		reset,
+	]);
+
+	useEffect(() => {
+		run();
+	}, [run]);
+
+	return {
+		seedCount: seed.data?.matchedCount,
+		isPending: seed.isPending || seed.data === undefined,
+		isError: seed.isError,
+		error: seed.error,
+		retry: run,
+	};
+};

package/src/hooks/useUpdateFilter.ts

@@ -0,0 +1,56 @@
+import {
+	filterDetailOperationsGetFilterQueryKey,
+	filterDetailOperationsUpdateFilterMutation,
+} from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import type { RemitImapUpdateFilterInput } from "@remit/api-http-client/types.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback } from "react";
+import { buildFilterListKey } from "./useFilters";
+
+/**
+ * Patch an existing filter (RFC 038 D6). The server bumps `ruleChangedAt` only
+ * when the body touches a predicate or action field, never on a name-only
+ * rename (RFC 034 Decision 3.2) — the caller decides which fields to send. On
+ * success both the account's filter list and this filter's detail are
+ * invalidated so the settings page and any open editor read the saved rule.
+ */
+export const useUpdateFilter = (
+	accountId: string | undefined,
+	filterId: string | undefined,
+) => {
+	const queryClient = useQueryClient();
+	const mutation = useMutation({
+		...filterDetailOperationsUpdateFilterMutation(),
+		onSuccess: () => {
+			if (!accountId) return;
+			queryClient.invalidateQueries({
+				queryKey: buildFilterListKey(accountId),
+			});
+			if (filterId) {
+				queryClient.invalidateQueries({
+					queryKey: filterDetailOperationsGetFilterQueryKey({
+						path: { accountId, filterId },
+					}),
+				});
+			}
+		},
+	});
+	const { mutate } = mutation;
+
+	const updateFilter = useCallback(
+		(body: RemitImapUpdateFilterInput) => {
+			if (!accountId || !filterId) return;
+			mutate({ path: { accountId, filterId }, body });
+		},
+		[accountId, filterId, mutate],
+	);
+
+	return {
+		updateFilter,
+		isPending: mutation.isPending,
+		isSuccess: mutation.isSuccess,
+		isError: mutation.isError,
+		error: mutation.error,
+		reset: mutation.reset,
+	};
+};