@remit/web-client 0.0.307 → 0.0.308

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/web-client",
-  "version": "0.0.307",
+  "version": "0.0.308",
   "type": "module",
   "description": "Remit web client, published as composable primitives — the app shell, auth shells, and runtime config. A distributor imports what it composes and bundles it.",
   "exports": {

package/src/components/config-import/steps.tsx

@@ -621,10 +621,10 @@ export function StepPendingFolders({
 		<WizardShell
 			steps={IMPORT_STEPS}
 			activeStep={3}
-			title={folders.length > 0 ? "Waiting on folders" : "Import finished"}
+			title={folders.length > 0 ? "Creating folders" : "Import finished"}
 			subtitle={
 				folders.length > 0
-					? "The config names folders this server has not shown us yet."
+					? "The config names folders this account does not have yet. Reader creates them on the mail server."
 					: "Everything in the file landed, and every folder it named resolved."
 			}
 			footer={
@@ -642,10 +642,11 @@ export function StepPendingFolders({
 				{folders.length > 0 ? (
 					<>
 						<Banner tone="warning">
-							{folders.length} settings are imported but switched off. Each
-							turns itself on the moment its folder appears — nothing was
-							dropped. If a folder never appears, create it in your mail client,
-							or edit the setting in Settings → Senders & Rules.
+							{folders.length} settings are imported but switched off. Reader
+							creates each missing folder on the mail server the next time the
+							account syncs, and turns the setting on once the server confirms
+							it. A rule whose folder cannot be created stays off, and Settings
+							→ Filters says why.
 						</Banner>
 						<div className="flex items-center gap-2 text-xs text-fg-muted">
 							<FolderClock className="size-4" />

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

@@ -47,6 +47,7 @@ const filterFixture = (
 	name: "Receipts",
 	scope: "Standing",
 	state: "Active",
+	disabledReason: "None",
 	hasAnchor: false,
 	ruleChangedAt: 100,
 	actionChangedAt: 100,

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

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import React, { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { ApiError } from "@/lib/api";
+import { FilterToggleError } from "./FilterToggleError";
+
+(globalThis as { React?: typeof React }).React = React;
+
+const render = (error: unknown) =>
+	renderToString(
+		createElement(FilterToggleError, {
+			enabling: true,
+			error,
+			onRetry: () => undefined,
+			reportHref: (message: string) =>
+				`https://example.test/new?body=${encodeURIComponent(message)}`,
+		}) as never,
+	);
+
+describe("FilterToggleError (#1103)", () => {
+	it("shows a refusal with its fix and a report link, and no Retry", () => {
+		const html = render(new ApiError("Pick a folder in the rule.", 400));
+		assert.match(html, /Couldn('|')t turn the filter on/);
+		assert.match(html, /Pick a folder in the rule\./);
+		assert.match(html, /Report an issue/);
+		assert.match(html, /example\.test\/new\?body=Pick/);
+		assert.doesNotMatch(html, />Retry</);
+	});
+
+	it("offers Retry when the server did not answer", () => {
+		const html = render(new ApiError("Unavailable", 503));
+		assert.match(html, />Retry</);
+		assert.match(html, /Report an issue/);
+	});
+});

package/src/components/settings/FilterToggleError.stories.tsx

@@ -0,0 +1,40 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { ApiError } from "@/lib/api";
+import { FilterToggleError } from "./FilterToggleError";
+
+const meta: Meta<typeof FilterToggleError> = {
+	title: "Playground/Shipped/Settings/Filters/FilterToggleError",
+	component: FilterToggleError,
+	parameters: { layout: "padded" },
+	decorators: [
+		(Story) => (
+			<div className="mx-auto max-w-md">
+				<Story />
+			</div>
+		),
+	],
+	args: {
+		onRetry: () => undefined,
+		reportHref: () => "https://github.com/remit-mail/reader/issues/new",
+	},
+};
+export default meta;
+
+type Story = StoryObj<typeof FilterToggleError>;
+
+export const RefusedWithoutFolder: Story = {
+	args: {
+		enabling: true,
+		error: new ApiError(
+			"This filter has no folder to move mail into yet. Wait for its folder to be created on the mail server, or pick a folder in the rule, then turn it on.",
+			400,
+		),
+	},
+};
+
+export const ServerUnavailable: Story = {
+	args: {
+		enabling: false,
+		error: new ApiError("The server did not answer.", 503),
+	},
+};

package/src/components/settings/FilterToggleError.tsx

@@ -0,0 +1,44 @@
+import { ErrorState, formatErrorMessage } from "@/components/ui/ErrorState";
+import { getErrorStatus } from "@/lib/error-classifier";
+
+interface FilterToggleErrorProps {
+	enabling: boolean;
+	error: unknown;
+	onRetry: () => void;
+	reportHref: (message: string) => string;
+}
+
+const isRefusal = (error: unknown): boolean => {
+	const status = getErrorStatus(error);
+	return status !== undefined && status >= 400 && status < 500;
+};
+
+export function FilterToggleError({
+	enabling,
+	error,
+	onRetry,
+	reportHref,
+}: FilterToggleErrorProps) {
+	return (
+		<div className="space-y-1">
+			<ErrorState
+				variant="inline"
+				title={
+					enabling
+						? "Couldn't turn the filter on"
+						: "Couldn't turn the filter off"
+				}
+				error={error}
+				onRetry={isRefusal(error) ? undefined : onRetry}
+			/>
+			<a
+				href={reportHref(formatErrorMessage(error))}
+				target="_blank"
+				rel="noreferrer"
+				className="text-xs text-accent hover:underline"
+			>
+				Report an issue
+			</a>
+		</div>
+	);
+}

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

@@ -21,6 +21,7 @@ const filter = (
 	name: "Travel",
 	scope: "Standing",
 	state: "Active",
+	disabledReason: "None",
 	hasAnchor: true,
 	ruleChangedAt: 0,
 	actionChangedAt: 0,
@@ -45,6 +46,7 @@ const render = (
 			labelById,
 			onEdit: () => undefined,
 			onDelete: () => undefined,
+			onToggle: () => undefined,
 			semanticUnavailable,
 			now: NOW,
 		}) as never,
@@ -111,4 +113,44 @@ describe("FiltersList", () => {
 		assert.match(html, /Expired/);
 		assert.match(html, /expired/);
 	});
+
+	it("offers to turn a running filter off", () => {
+		const html = render([filter({})]);
+		assert.match(html, /Turn off filter Travel/);
+		assert.doesNotMatch(html, /Disabled/);
+	});
+
+	const reasons = [
+		["UserDisabled", /Turned off\./],
+		["AwaitingFolder", /Off until its folder exists on the mail server/],
+		["FolderCreateFailed", /refused to create its folder/],
+		["FolderMissing", /no longer exists/],
+	] as const;
+
+	it("drops the turns-on-by-itself copy once the user picked a folder", () => {
+		const html = render([
+			filter({
+				state: "Disabled",
+				disabledReason: "AwaitingFolder",
+				actionMailboxId: "mbx-travel",
+			}),
+		]);
+		assert.doesNotMatch(html, /turns on by itself/);
+		assert.match(html, /Turned off\./);
+	});
+
+	for (const [reason, copy] of reasons) {
+		it(`marks a filter disabled for ${reason} with its reason and a way back on (#1103)`, () => {
+			const html = render([
+				filter({
+					state: "Disabled",
+					disabledReason: reason,
+					actionMailboxId: "None",
+				}),
+			]);
+			assert.match(html, /Disabled/);
+			assert.match(html, copy);
+			assert.match(html, /Turn on filter Travel/);
+		});
+	}
 });

package/src/components/settings/FiltersList.stories.tsx

@@ -0,0 +1,89 @@
+import type { RemitImapFilterResponse } from "@remit/api-http-client/types.gen.ts";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { FiltersList } from "./FiltersList";
+
+const NOW = Date.parse("2026-09-25T12:00:00Z");
+
+const meta: Meta<typeof FiltersList> = {
+	title: "Playground/Shipped/Settings/Filters/FiltersList",
+	component: FiltersList,
+	parameters: { layout: "padded" },
+	decorators: [
+		(Story) => (
+			<div className="mx-auto max-w-md">
+				<Story />
+			</div>
+		),
+	],
+	args: {
+		mailboxName: (mailboxId: string) =>
+			mailboxId === "mbx-invoices" ? "Invoices" : undefined,
+		labelById: new Map(),
+		onEdit: () => undefined,
+		onDelete: () => undefined,
+		onToggle: () => undefined,
+		now: NOW,
+	},
+};
+export default meta;
+
+type Story = StoryObj<typeof FiltersList>;
+
+const makeFilter = (
+	overrides: Partial<RemitImapFilterResponse>,
+): RemitImapFilterResponse => ({
+	filterId: "flt-1",
+	accountConfigId: "acc-1",
+	name: "Invoices",
+	scope: "Standing",
+	state: "Active",
+	disabledReason: "None",
+	hasAnchor: false,
+	ruleChangedAt: 0,
+	actionChangedAt: 0,
+	matchOperator: "And",
+	literalClauses: [{ field: "From", value: "billing@example.com" }],
+	actionLabelId: "None",
+	actionMailboxId: "mbx-invoices",
+	createdAt: 0,
+	updatedAt: 0,
+	...overrides,
+});
+
+const disabled = (
+	reason: RemitImapFilterResponse["disabledReason"],
+	overrides: Partial<RemitImapFilterResponse> = {},
+): RemitImapFilterResponse[] => [
+	makeFilter({ state: "Disabled", disabledReason: reason, ...overrides }),
+];
+
+export const Active: Story = {
+	args: { filters: [makeFilter({})] },
+};
+
+export const TurnedOffByUser: Story = {
+	args: { filters: disabled("UserDisabled") },
+};
+
+export const AwaitingFolder: Story = {
+	args: { filters: disabled("AwaitingFolder", { actionMailboxId: "None" }) },
+};
+
+export const FolderCreateFailed: Story = {
+	args: {
+		filters: disabled("FolderCreateFailed", { actionMailboxId: "None" }),
+	},
+};
+
+export const FolderMissing: Story = {
+	args: {
+		filters: disabled("FolderMissing", { actionMailboxId: "mbx-deleted" }),
+	},
+};
+
+export const Toggling: Story = {
+	args: {
+		filters: disabled("UserDisabled"),
+		togglingFilterId: "flt-1",
+	},
+};

package/src/components/settings/FiltersList.tsx

@@ -8,6 +8,7 @@ import {
 } from "@remit/ui";
 import { Trash2 } from "lucide-react";
 import {
+	disabledReasonCopy,
 	filterDisplayStatus,
 	formatExpiresAt,
 } from "@/lib/organize/filter-status";
@@ -23,6 +24,8 @@ interface FiltersListProps {
 	onEdit: (filterId: string) => void;
 	onDelete: (filterId: string) => void;
 	deletingFilterId?: string;
+	onToggle: (filterId: string, enabled: boolean) => void;
+	togglingFilterId?: 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
@@ -47,6 +50,8 @@ export function FiltersList({
 	onEdit,
 	onDelete,
 	deletingFilterId,
+	onToggle,
+	togglingFilterId,
 	semanticUnavailable = false,
 	now = Date.now(),
 }: FiltersListProps) {
@@ -64,6 +69,8 @@ export function FiltersList({
 			{filters.map((filter) => {
 				const status = filterDisplayStatus(filter, now);
 				const expired = status === "Expired";
+				const disabled = status === "Disabled";
+				const reason = disabled ? disabledReasonCopy(filter) : undefined;
 				const folder =
 					filter.actionMailboxId !== NO_ACTION
 						? mailboxName(filter.actionMailboxId)
@@ -88,12 +95,15 @@ export function FiltersList({
 							<div className="flex items-center gap-2">
 								<span
 									className={`truncate text-sm font-medium ${
-										expired ? "text-fg-muted" : "text-fg"
+										expired || disabled ? "text-fg-muted" : "text-fg"
 									}`}
 								>
 									{filter.name}
 								</span>
-								<Badge tone={expired ? "neutral" : "positive"} dot>
+								<Badge
+									tone={expired ? "neutral" : disabled ? "warning" : "positive"}
+									dot
+								>
 									{status}
 								</Badge>
 							</div>
@@ -107,6 +117,9 @@ export function FiltersList({
 										? " · always"
 										: ""}
 							</p>
+							{reason && (
+								<p className="mt-0.5 text-xs text-warning">{reason}</p>
+							)}
 							{(filter.hasAnchor || label) && (
 								<div className="mt-1.5 flex flex-wrap gap-1.5">
 									{filter.hasAnchor && (
@@ -129,6 +142,17 @@ export function FiltersList({
 								</div>
 							)}
 						</button>
+						{!expired && (
+							<Button
+								variant="ghost"
+								size="sm"
+								onClick={() => onToggle(filter.filterId, disabled)}
+								disabled={togglingFilterId === filter.filterId}
+								aria-label={`${disabled ? "Turn on" : "Turn off"} filter ${filter.name}`}
+							>
+								{disabled ? "Turn on" : "Turn off"}
+							</Button>
+						)}
 						<Button
 							variant="ghost"
 							size="sm"

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

@@ -46,6 +46,7 @@ const makeFilter = (
 	name: "Receipts",
 	scope: "Standing",
 	state: "Active",
+	disabledReason: "None",
 	hasAnchor: false,
 	ruleChangedAt: 0,
 	actionChangedAt: 0,

package/src/hooks/useFilters.ts

@@ -1,5 +1,6 @@
 import {
 	filterDetailOperationsDeleteFilterMutation,
+	filterDetailOperationsUpdateFilterMutation,
 	filterOperationsCreateFilterMutation,
 	filterOperationsListFiltersOptions,
 	filterOperationsListFiltersQueryKey,
@@ -145,3 +146,41 @@ export const useDeleteFilter = (accountId: string | undefined) => {
 			: undefined,
 	};
 };
+
+export const useToggleFilter = (accountId: string | undefined) => {
+	const queryClient = useQueryClient();
+	const mutation = useMutation({
+		...filterDetailOperationsUpdateFilterMutation(),
+		onSuccess: () => {
+			if (!accountId) return;
+			queryClient.invalidateQueries({
+				queryKey: buildFilterListKey(accountId),
+			});
+		},
+	});
+	const { mutate, variables } = mutation;
+
+	const toggleFilter = useCallback(
+		(filterId: string, enabled: boolean) => {
+			if (!accountId) return;
+			mutate({
+				path: { accountId, filterId },
+				body: { state: enabled ? "Active" : "Disabled" },
+			});
+		},
+		[accountId, mutate],
+	);
+
+	const retry = useCallback(() => {
+		if (variables) mutate(variables);
+	}, [mutate, variables]);
+
+	return {
+		toggleFilter,
+		retry,
+		togglingFilterId: mutation.isPending ? variables?.path.filterId : undefined,
+		isError: mutation.isError,
+		error: mutation.error,
+		enabling: variables?.body?.state === "Active",
+	};
+};

package/src/lib/filter-report.ts

@@ -0,0 +1,10 @@
+import { buildBugReportContext, buildGitHubIssueUrl } from "./bug-report";
+
+export function filterToggleReportHref(message: string): string {
+	return buildGitHubIssueUrl(
+		buildBugReportContext({
+			title: `Filter toggle: ${message}`,
+			errorMessage: message,
+		}),
+	);
+}

package/src/lib/organize/filter-edit-model.test.ts

@@ -18,6 +18,7 @@ const filter = (
 	name: "Receipts",
 	scope: "Standing",
 	state: "Active",
+	disabledReason: "None",
 	hasAnchor: false,
 	ruleChangedAt: 0,
 	actionChangedAt: 0,

package/src/lib/organize/filter-status.test.ts

@@ -9,6 +9,27 @@ import {
 const NOW = Date.parse("2026-07-12T12:00:00Z");
 
 describe("filterDisplayStatus", () => {
+	it("marks a disabled filter Disabled (#1103)", () => {
+		assert.equal(
+			filterDisplayStatus({ scope: "Standing", state: "Disabled" }, NOW),
+			"Disabled",
+		);
+	});
+
+	it("marks a disabled temporary filter past its date Expired", () => {
+		assert.equal(
+			filterDisplayStatus(
+				{
+					scope: "Temporary",
+					state: "Disabled",
+					expiresAt: "2020-01-01T00:00:00Z",
+				},
+				NOW,
+			),
+			"Expired",
+		);
+	});
+
 	it("treats a Standing filter as always Active", () => {
 		assert.equal(
 			filterDisplayStatus({ scope: "Standing", state: "Active" }, NOW),

package/src/lib/organize/filter-status.ts

@@ -1,6 +1,8 @@
 import type { RemitImapFilterResponse } from "@remit/api-http-client/types.gen.ts";
 
-export type FilterDisplayStatus = "Active" | "Expired";
+export type FilterDisplayStatus = "Active" | "Expired" | "Disabled";
+
+export type FilterDisabledReason = RemitImapFilterResponse["disabledReason"];
 
 /**
  * The displayed Active/Expired status of a filter.
@@ -19,12 +21,39 @@ export const filterDisplayStatus = (
 	now: number,
 ): FilterDisplayStatus => {
 	if (filter.state === "Expired") return "Expired";
-	if (filter.scope !== "Temporary") return "Active";
-	if (!filter.expiresAt) return "Active";
+	const running = filter.state === "Disabled" ? "Disabled" : "Active";
+	if (filter.scope !== "Temporary") return running;
+	if (!filter.expiresAt) return running;
 
 	const expiresAtMs = Date.parse(filter.expiresAt);
-	if (Number.isNaN(expiresAtMs)) return "Active";
-	return expiresAtMs <= now ? "Expired" : "Active";
+	if (Number.isNaN(expiresAtMs)) return running;
+	return expiresAtMs <= now ? "Expired" : running;
+};
+
+const DISABLED_REASON_COPY: Record<
+	Exclude<FilterDisabledReason, "None">,
+	string
+> = {
+	UserDisabled: "Turned off. Turn it on to run it on new mail again.",
+	AwaitingFolder:
+		"Off until its folder exists on the mail server. It turns on by itself once the folder is created.",
+	FolderCreateFailed:
+		"Off: the mail server refused to create its folder. Pick another folder in the rule, then turn it on.",
+	FolderMissing:
+		"Off: the folder it moves mail into no longer exists. Pick another folder in the rule, then turn it on.",
+};
+
+export const disabledReasonCopy = (
+	filter: Pick<RemitImapFilterResponse, "disabledReason" | "actionMailboxId">,
+): string | undefined => {
+	if (filter.disabledReason === "None") return undefined;
+	const folderless =
+		filter.disabledReason === "AwaitingFolder" ||
+		filter.disabledReason === "FolderCreateFailed";
+	if (folderless && filter.actionMailboxId !== "None") {
+		return DISABLED_REASON_COPY.UserDisabled;
+	}
+	return DISABLED_REASON_COPY[filter.disabledReason];
 };
 
 /**

package/src/routes/settings/-filters.test.ts

@@ -64,6 +64,7 @@ const filter: RemitImapFilterResponse = {
 	name: "Receipts",
 	scope: "Standing",
 	state: "Active",
+	disabledReason: "None",
 	hasAnchor: false,
 	ruleChangedAt: 0,
 	actionChangedAt: 0,

package/src/routes/settings/filters.tsx

@@ -9,10 +9,16 @@ import { createFileRoute, useNavigate } from "@tanstack/react-router";
 import { useCallback, useMemo, useState } from "react";
 import { FilterEditorSurface } from "@/components/settings/FilterEditorSurface";
 import { FiltersList } from "@/components/settings/FiltersList";
+import { FilterToggleError } from "@/components/settings/FilterToggleError";
 import { ErrorState } from "@/components/ui/ErrorState";
-import { useDeleteFilter, useFilterList } from "@/hooks/useFilters";
+import {
+	useDeleteFilter,
+	useFilterList,
+	useToggleFilter,
+} from "@/hooks/useFilters";
 import { useFolderLabelTranslator } from "@/hooks/useFolderLabelTranslator";
 import { useLabelList } from "@/hooks/useLabels";
+import { filterToggleReportHref } from "@/lib/filter-report";
 import { buildMailboxRoleMap, labelForMailbox } from "@/lib/folder-roles";
 import { buildMoveOptions, folderDelimiter } from "@/lib/move-options";
 import { SETTINGS_ID_TO_PATH, SETTINGS_NAV_ITEMS } from "@/routes/settings";
@@ -32,6 +38,10 @@ const filtersHelp = (
 			An expired filter isn't deleted the instant it lapses — it stays here,
 			marked Expired, so you can see what it did and when it stopped.
 		</p>
+		<p>
+			A filter that can't do its job turns itself off and says why, for example
+			when its folder no longer exists. Turn it back on once that is fixed.
+		</p>
 	</div>
 );
 
@@ -44,6 +54,7 @@ export function AccountFilters({
 	const { filters, isPending, isError, error, refetch } =
 		useFilterList(accountId);
 	const { deleteFilter, deletingFilterId } = useDeleteFilter(accountId);
+	const toggle = useToggleFilter(accountId);
 	const [editingFilterId, setEditingFilterId] = useState<string | undefined>();
 
 	const { data: mailboxesData } = useQuery({
@@ -128,14 +139,26 @@ export function AccountFilters({
 					}}
 				/>
 			) : (
-				<FiltersList
-					filters={filters}
-					mailboxName={mailboxName}
-					labelById={labelById}
-					onEdit={setEditingFilterId}
-					onDelete={deleteFilter}
-					deletingFilterId={deletingFilterId}
-				/>
+				<>
+					{toggle.isError && (
+						<FilterToggleError
+							enabling={toggle.enabling}
+							error={toggle.error}
+							onRetry={toggle.retry}
+							reportHref={filterToggleReportHref}
+						/>
+					)}
+					<FiltersList
+						filters={filters}
+						mailboxName={mailboxName}
+						labelById={labelById}
+						onEdit={setEditingFilterId}
+						onDelete={deleteFilter}
+						deletingFilterId={deletingFilterId}
+						onToggle={toggle.toggleFilter}
+						togglingFilterId={toggle.togglingFilterId}
+					/>
+				</>
 			)}
 		</section>
 	);