@remit/ui 0.0.104 → 0.0.106

package/package.json

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

package/src/components/attachment-list.stories.tsx

@@ -1,4 +1,5 @@
 import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
 import { type AttachmentItem, AttachmentList } from "./attachment-list.js";
 
 /**
@@ -25,57 +26,95 @@ const report: AttachmentItem = {
 	download: { status: "idle" },
 };
 
+const sitePlan: AttachmentItem = {
+	attachmentId: "part-3",
+	filename: "site-plan.png",
+	typeLabel: "PNG",
+	sizeOctets: 486_120,
+	download: { status: "idle" },
+};
+
+/** How long the app's own fetch takes on a small attachment, near enough. */
+const DOWNLOAD_MS = 900;
+
+/**
+ * The app owns the fetch and hands per-row state back. The harness plays that
+ * part: a press puts the row on the spinner, and the row returns to rest when
+ * the file has been handed to the browser. A row is only pressable once at a
+ * time, which is the state the component reads to disable it.
+ */
+const Harness = ({
+	attachments,
+	hasUnlistedAttachment,
+}: {
+	attachments: readonly AttachmentItem[];
+	hasUnlistedAttachment?: boolean;
+}) => {
+	const [rows, setRows] = useState<readonly AttachmentItem[]>(attachments);
+
+	const setDownload = (attachmentId: string, item: AttachmentItem) =>
+		setRows((current) =>
+			current.map((row) => (row.attachmentId === attachmentId ? item : row)),
+		);
+
+	const download = (attachmentId: string) => {
+		const row = rows.find((item) => item.attachmentId === attachmentId);
+		if (!row || row.download.status === "downloading") return;
+		setDownload(attachmentId, { ...row, download: { status: "downloading" } });
+		setTimeout(
+			() => setDownload(attachmentId, { ...row, download: { status: "idle" } }),
+			DOWNLOAD_MS,
+		);
+	};
+
+	return (
+		<AttachmentList
+			attachments={rows}
+			onDownload={download}
+			hasUnlistedAttachment={hasUnlistedAttachment}
+		/>
+	);
+};
+
 export const OneAttachment: Story = {
-	args: {
-		attachments: [report],
-		onDownload: (id) => alert(`Download ${id}`),
-	},
+	render: () => <Harness attachments={[report]} />,
 };
 
 export const SeveralAttachments: Story = {
-	args: {
-		attachments: [
-			report,
-			{
-				attachmentId: "part-3",
-				filename: "site-plan.png",
-				typeLabel: "PNG",
-				sizeOctets: 486_120,
-				download: { status: "idle" },
-			},
-			{
-				attachmentId: "part-4",
-				filename: "notes.txt",
-				typeLabel: "PLAIN",
-				sizeOctets: 812,
-				download: { status: "idle" },
-			},
-			{
-				attachmentId: "part-5",
-				filename: "archive",
-				typeLabel: "FILE",
-				sizeOctets: 1024 ** 3 + 1024 ** 2 * 200,
-				download: { status: "idle" },
-			},
-		],
-		onDownload: (id) => alert(`Download ${id}`),
-	},
+	render: () => (
+		<Harness
+			attachments={[
+				report,
+				sitePlan,
+				{
+					attachmentId: "part-4",
+					filename: "notes.txt",
+					typeLabel: "PLAIN",
+					sizeOctets: 812,
+					download: { status: "idle" },
+				},
+				{
+					attachmentId: "part-5",
+					filename: "archive",
+					typeLabel: "FILE",
+					sizeOctets: 1024 ** 3 + 1024 ** 2 * 200,
+					download: { status: "idle" },
+				},
+			]}
+		/>
+	),
 };
 
+/** One row mid-fetch. The rows beside it are still pressable. */
 export const Downloading: Story = {
-	args: {
-		attachments: [
-			{ ...report, download: { status: "downloading" } },
-			{
-				attachmentId: "part-3",
-				filename: "site-plan.png",
-				typeLabel: "PNG",
-				sizeOctets: 486_120,
-				download: { status: "idle" },
-			},
-		],
-		onDownload: (id) => alert(`Download ${id}`),
-	},
+	render: () => (
+		<Harness
+			attachments={[
+				{ ...report, download: { status: "downloading" } },
+				sitePlan,
+			]}
+		/>
+	),
 };
 
 /**
@@ -85,28 +124,23 @@ export const Downloading: Story = {
  * outcome this list exists to make impossible.
  */
 export const DownloadFailed: Story = {
-	args: {
-		attachments: [
-			{
-				...report,
-				download: {
-					status: "failed",
-					title: "This attachment is missing from storage",
-					detail:
-						"Remit has the message but not the file. Re-sync the account from Settings, then try again.",
-					reportUrl: "https://github.com/remit-mail/reader/issues/new",
+	render: () => (
+		<Harness
+			attachments={[
+				{
+					...report,
+					download: {
+						status: "failed",
+						title: "This attachment is missing from storage",
+						detail:
+							"Remit has the message but not the file. Re-sync the account from Settings, then try again.",
+						reportUrl: "https://github.com/remit-mail/reader/issues/new",
+					},
 				},
-			},
-			{
-				attachmentId: "part-3",
-				filename: "site-plan.png",
-				typeLabel: "PNG",
-				sizeOctets: 486_120,
-				download: { status: "idle" },
-			},
-		],
-		onDownload: (id) => alert(`Download ${id}`),
-	},
+				sitePlan,
+			]}
+		/>
+	),
 };
 
 /**
@@ -117,32 +151,33 @@ export const DownloadFailed: Story = {
  * what lands.
  */
 export const HostileFilename: Story = {
-	args: {
-		attachments: [
-			{
-				attachmentId: "part-6",
-				filename: "passwd",
-				typeLabel: "FILE",
-				sizeOctets: 3_120,
-				download: { status: "idle" },
-			},
-			{
-				attachmentId: "part-7",
-				filename: "invoicegnp.exe",
-				typeLabel: "FILE",
-				sizeOctets: 118_400,
-				download: { status: "idle" },
-			},
-			{
-				attachmentId: "part-8",
-				filename: `${"long-name-".repeat(11)}report.pdf`,
-				typeLabel: "PDF",
-				sizeOctets: 44_000,
-				download: { status: "idle" },
-			},
-		],
-		onDownload: (id) => alert(`Download ${id}`),
-	},
+	render: () => (
+		<Harness
+			attachments={[
+				{
+					attachmentId: "part-6",
+					filename: "passwd",
+					typeLabel: "FILE",
+					sizeOctets: 3_120,
+					download: { status: "idle" },
+				},
+				{
+					attachmentId: "part-7",
+					filename: "invoicegnp.exe",
+					typeLabel: "FILE",
+					sizeOctets: 118_400,
+					download: { status: "idle" },
+				},
+				{
+					attachmentId: "part-8",
+					filename: `${"long-name-".repeat(11)}report.pdf`,
+					typeLabel: "PDF",
+					sizeOctets: 44_000,
+					download: { status: "idle" },
+				},
+			]}
+		/>
+	),
 };
 
 /**
@@ -151,9 +186,5 @@ export const HostileFilename: Story = {
  * read as broken.
  */
 export const UnlistedAttachment: Story = {
-	args: {
-		attachments: [],
-		onDownload: () => undefined,
-		hasUnlistedAttachment: true,
-	},
+	render: () => <Harness attachments={[]} hasUnlistedAttachment />,
 };

package/src/components/brief-sections.tsx

@@ -90,7 +90,9 @@ export function matchesBriefFilters(
  * The attribute chips are either this component's own or entirely the
  * consumer's. A consumer narrowing the same rows on a second surface (the phone
  * search takeover) holds the set so both surfaces answer to one selection, and
- * takes every control over it with the set.
+ * takes every control over it with the set. `onClearFilters` is then the whole
+ * of Clear, category scope included — one handler reading one state, rather
+ * than two reading the same one and racing to write it.
  */
 export type BriefFilterControl =
 	| {
@@ -236,11 +238,11 @@ export function BriefSections({
 	const sheetFilters = briefFilterChips;
 
 	const clearFilters = () => {
-		onSelectBriefCategory?.("all");
 		if (onClearFilters) {
 			onClearFilters();
 			return;
 		}
+		onSelectBriefCategory?.("all");
 		setOwnFilters(new Set());
 	};
 

package/src/components/compose-action-bar.stories.tsx

@@ -1,4 +1,6 @@
 import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { expect, userEvent, within } from "storybook/test";
 import { ComposeActionBar } from "./compose-action-bar.js";
 
 const meta: Meta<typeof ComposeActionBar> = {
@@ -30,11 +32,43 @@ export const Sending: Story = {
 	args: { sending: true },
 };
 
+/**
+ * Send is never greyed out. Pressing it with nothing to send on reports the
+ * reason where the app would raise its banner — a control that swallowed the
+ * press would be the dead button this bar exists to avoid.
+ */
 export const CannotSend: Story = {
 	name: "Cannot send — stays pressable",
-	args: {
-		canSend: false,
-		unavailableReason: "SMTP not configured",
-		onUnavailable: () => undefined,
+	render: () => {
+		const [reason, setReason] = useState<string>();
+		return (
+			<div className="space-y-2">
+				{reason && (
+					<div
+						role="alert"
+						data-testid="compose-unavailable"
+						className="rounded-md bg-danger-soft px-3 py-2 text-sm text-danger"
+					>
+						{reason}
+					</div>
+				)}
+				<ComposeActionBar
+					onSend={() => undefined}
+					onDiscard={() => undefined}
+					sending={false}
+					canSend={false}
+					saveStatus="idle"
+					unavailableReason="SMTP not configured"
+					onUnavailable={setReason}
+				/>
+			</div>
+		);
+	},
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		await userEvent.click(canvas.getByRole("button", { name: "Send" }));
+		await expect(canvas.getByTestId("compose-unavailable")).toHaveTextContent(
+			"SMTP not configured",
+		);
 	},
 };

package/src/components/compose-body.stories.tsx

@@ -39,7 +39,7 @@ const Harness = ({
 	initialHtml = "",
 	initialText = "",
 	startIn = "rich",
-	onConversionError = () => undefined,
+	onConversionError,
 	conversions,
 	languages = LANGUAGES,
 	quoted,
@@ -56,15 +56,29 @@ const Harness = ({
 	quoted?: string;
 }) => {
 	const [mode, setMode] = useState<"rich" | "plain">(startIn);
+	const [failure, setFailure] = useState<ConversionFailure>();
 	return (
 		<div className="flex h-[460px] w-[680px] flex-col overflow-auto rounded-md border border-line bg-canvas">
+			{failure && (
+				<div
+					role="alert"
+					data-testid="compose-conversion-error"
+					className="border-b border-danger/30 bg-danger-soft px-3 py-2 text-xs"
+				>
+					<p className="font-medium text-danger">{failure.title}</p>
+					<p className="text-fg-muted">{failure.detail}</p>
+				</div>
+			)}
 			<ComposeBody
 				mode={mode}
 				onModeChange={setMode}
 				initialHtml={initialHtml}
 				initialText={initialText}
-				onChange={() => undefined}
-				onConversionError={onConversionError}
+				onChange={noop}
+				onConversionError={(reported) => {
+					setFailure(reported);
+					onConversionError?.(reported);
+				}}
 				conversions={conversions}
 				languages={languages}
 				onLanguageChange={noop}
@@ -278,6 +292,9 @@ export const ConversionCameBackEmpty: Story = {
 			title: "Couldn't switch to rich text",
 			detail: "The conversion came back empty, so your message is unchanged.",
 		});
+		await expect(
+			within(canvasElement).getByTestId("compose-conversion-error"),
+		).toHaveTextContent("Couldn't switch to rich text");
 		const textarea = plainSurface(canvasElement);
 		if (!textarea) throw new Error("the plain surface left");
 		await expect(textarea.value).toBe("Everything I wrote this morning.");

package/src/components/compose-mode-toggle.stories.tsx

@@ -15,22 +15,11 @@ const meta: Meta<typeof ComposeModeToggle> = {
 	title: "Mail/ComposeModeToggle",
 	component: ComposeModeToggle,
 	parameters: { layout: "centered" },
-	args: { onToggle: () => undefined },
 };
 export default meta;
 
 type Story = StoryObj<typeof ComposeModeToggle>;
 
-export const RichText: Story = {
-	name: "Rich text — plain text on offer",
-	args: { mode: "rich" },
-};
-
-export const PlainText: Story = {
-	name: "Plain text — the mode is on",
-	args: { mode: "plain" },
-};
-
 const Harness = ({ start }: { start: ComposeBodyMode }) => {
 	const [mode, setMode] = useState<ComposeBodyMode>(start);
 	return (
@@ -41,6 +30,16 @@ const Harness = ({ start }: { start: ComposeBodyMode }) => {
 	);
 };
 
+export const RichText: Story = {
+	name: "Rich text — plain text on offer",
+	render: () => <Harness start="rich" />,
+};
+
+export const PlainText: Story = {
+	name: "Plain text — the mode is on",
+	render: () => <Harness start="plain" />,
+};
+
 export const PressedStateFollowsTheMode: Story = {
 	render: () => <Harness start="rich" />,
 	play: async ({ canvasElement }) => {

package/src/components/compose-smtp-missing-banner.stories.tsx

@@ -11,7 +11,7 @@ const meta: Meta<typeof ComposeSmtpMissingBanner> = {
 	title: "Mail/ComposeSmtpMissingBanner",
 	component: ComposeSmtpMissingBanner,
 	parameters: { layout: "padded" },
-	args: { onConfigure: () => undefined },
+	args: { onConfigure: fn().mockName("onConfigure") },
 };
 export default meta;
 

package/src/components/mobile-search-view.stories.tsx

@@ -353,7 +353,7 @@ export const NothingToConvert: Story = {
 			initialValue="has:attachment"
 			sections={resultSections}
 			preset="inbox"
-			makeFilterBlockedReason="Add a sender or words to filter on"
+			makeFilterBlockedReason="Has attachment isn't a filter condition — add a sender or words to filter on"
 		/>
 	),
 };

package/src/components/reading-pane.stories.tsx

@@ -1,7 +1,12 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { Paperclip, Star } from "lucide-react";
+import { useState } from "react";
 import type { ThreadData, ThreadMessageData } from "./app-shell-types.js";
-import { AttachmentList } from "./attachment-list.js";
+import {
+	type AttachmentDownloadState,
+	type AttachmentItem,
+	AttachmentList,
+} from "./attachment-list.js";
 import { MessageBodyView } from "./message-body-view.js";
 import {
 	CollapsedMessage,
@@ -198,6 +203,44 @@ export const ExpandedRowComposed: StoryObj<typeof ExpandedMessage> = {
 	),
 };
 
+/** The app owns the fetch and hands the row its state back; so does this. */
+const ThreadAttachments = () => {
+	const [rows, setRows] = useState<AttachmentItem[]>([
+		{
+			attachmentId: "part-2",
+			filename: "Q3 board pack.pdf",
+			typeLabel: "PDF",
+			sizeOctets: 2_411_724,
+			download: { status: "idle" },
+		},
+		{
+			attachmentId: "part-3",
+			filename: "headcount.csv",
+			typeLabel: "CSV",
+			sizeOctets: 4_180,
+			download: { status: "idle" },
+		},
+	]);
+
+	const setStatus = (attachmentId: string, download: AttachmentDownloadState) =>
+		setRows((current) =>
+			current.map((row) =>
+				row.attachmentId === attachmentId ? { ...row, download } : row,
+			),
+		);
+
+	return (
+		<AttachmentList
+			className="mt-4 px-2 lg:px-0"
+			attachments={rows}
+			onDownload={(attachmentId) => {
+				setStatus(attachmentId, { status: "downloading" });
+				setTimeout(() => setStatus(attachmentId, { status: "idle" }), 900);
+			}}
+		/>
+	);
+};
+
 /**
  * The expanded row as `MessageCard` composes it when the message carries files
  * (#683): body first, attachment list under it. The indicators row holds no
@@ -222,26 +265,7 @@ export const ExpandedRowWithAttachments: StoryObj<typeof ExpandedMessage> = {
 							category="personal"
 							allowImages
 						/>
-						<AttachmentList
-							className="mt-4 px-2 lg:px-0"
-							attachments={[
-								{
-									attachmentId: "part-2",
-									filename: "Q3 board pack.pdf",
-									typeLabel: "PDF",
-									sizeOctets: 2_411_724,
-									download: { status: "idle" },
-								},
-								{
-									attachmentId: "part-3",
-									filename: "headcount.csv",
-									typeLabel: "CSV",
-									sizeOctets: 4_180,
-									download: { status: "idle" },
-								},
-							]}
-							onDownload={(id) => alert(`Download ${id}`)}
-						/>
+						<ThreadAttachments />
 					</div>
 				}
 			/>

package/src/components/rich-text-editor.stories.tsx

@@ -1,8 +1,12 @@
 import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
 import { expect, userEvent } from "storybook/test";
 import { sanitizeAdoptedHtml } from "../lib/adopted-html.js";
 import { ComposeLanguageChip } from "./compose-language-chip.js";
-import { ComposeModeToggle } from "./compose-mode-toggle.js";
+import {
+	type ComposeBodyMode,
+	ComposeModeToggle,
+} from "./compose-mode-toggle.js";
 import { RichTextEditor } from "./rich-text-editor.js";
 
 /**
@@ -108,18 +112,29 @@ export const ClickBelowTheText: Story = {
 /**
  * The two pinned controls, in the order compose ships them: the chip first, so
  * one Shift+Tab out of the body still reaches the mode toggle and two reach the
- * chip.
+ * chip. Both hold their own state here — the editor knows nothing about either,
+ * and a pinned control that did not answer a press would read as a broken
+ * toolbar rather than a layout story.
  */
-const pinnedControls = (
-	<>
-		<ComposeLanguageChip
-			language="nl"
-			languages={["nl", "en", "de"]}
-			onSelect={() => undefined}
-		/>
-		<ComposeModeToggle mode="rich" onToggle={() => undefined} />
-	</>
-);
+const PinnedControls = () => {
+	const [language, setLanguage] = useState("nl");
+	const [mode, setMode] = useState<ComposeBodyMode>("rich");
+	return (
+		<>
+			<ComposeLanguageChip
+				language={language}
+				languages={["nl", "en", "de"]}
+				onSelect={setLanguage}
+			/>
+			<ComposeModeToggle
+				mode={mode}
+				onToggle={() => setMode(mode === "plain" ? "rich" : "plain")}
+			/>
+		</>
+	);
+};
+
+const pinnedControls = <PinnedControls />;
 
 /** The toolbar as compose ships it: the formatting cluster, then the two pinned controls. */
 export const ToolbarInRich: Story = {

package/src/components/search-conversion.render.test.ts

@@ -6,6 +6,7 @@ import {
 	DROPPED_SEMANTIC_COPY,
 	droppedFacetsCopy,
 	hasConversionNotice,
+	makeFilterBlockedCopy,
 	scopedOutCopy,
 } from "./search-conversion.js";
 import { SearchConversionNoticeView } from "./search-conversion-notice.js";
@@ -48,6 +49,29 @@ describe("search-conversion copy", () => {
 		assert.equal(hasConversionNotice({ droppedFacets: ["Unread"] }), true);
 		assert.equal(hasConversionNotice({ droppedSemantic: true }), true);
 	});
+
+	it("names the facets a chip-composed query is made of, not just the gap", () => {
+		const copy = makeFilterBlockedCopy(["Unread", "Category: Newsletter"]);
+		assert.match(
+			copy,
+			/Unread and Category: Newsletter aren't filter conditions/,
+		);
+		assert.match(copy, /add a sender or words to filter on/);
+	});
+
+	it("reads singular for one facet", () => {
+		assert.match(
+			makeFilterBlockedCopy(["Unread"]),
+			/^Unread isn't a filter condition — /,
+		);
+	});
+
+	it("asks for what is missing when no facet is what is in the way", () => {
+		assert.equal(
+			makeFilterBlockedCopy([]),
+			"Add a sender or words to filter on",
+		);
+	});
 });
 
 describe("SearchConversionNoticeView", () => {

package/src/components/search-conversion.ts

@@ -50,6 +50,24 @@ export function droppedFacetsCopy(facets: string[]): string {
 	} left out — the filter still matches everything else you searched for.`;
 }
 
+/** What a query needs before there is a rule to open on. */
+const NEEDS_A_CLAUSE = "add a sender or words to filter on";
+
+/**
+ * Why the current query has no filter in it. A query narrowed only by chips —
+ * ticked in the brief's filter panel, which writes them into the query as terms
+ * — is all attribute facets and no clause, so the reason names the facets that
+ * cannot be one instead of asking for something the user just supplied.
+ */
+export function makeFilterBlockedCopy(droppedFacets: string[]): string {
+	if (droppedFacets.length === 0)
+		return `${NEEDS_A_CLAUSE[0].toUpperCase()}${NEEDS_A_CLAUSE.slice(1)}`;
+	const verb = droppedFacets.length === 1 ? "isn't" : "aren't";
+	const noun =
+		droppedFacets.length === 1 ? "a filter condition" : "filter conditions";
+	return `${joinFacets(droppedFacets)} ${verb} ${noun} — ${NEEDS_A_CLAUSE}`;
+}
+
 /**
  * States the filter is literal-only, so the search's similar-mail reach is not
  * carried (RFC 038 D5). Shown only where that reach existed — a capable search

package/src/components/search-results.stories.tsx

@@ -1,5 +1,6 @@
 import type { Decorator, Meta, StoryObj } from "@storybook/react";
 import { useState } from "react";
+import { makeFilterBlockedCopy } from "./search-conversion.js";
 import type { SearchResult } from "./search-result-row.js";
 import { type SearchResultSection, SearchResults } from "./search-results.js";
 
@@ -201,7 +202,7 @@ export const MakeFilterBlocked: Story = {
 			sections={resultSections}
 			makeFilter={{
 				onClick: () => {},
-				blockedReason: "Add a sender or words to filter on",
+				blockedReason: makeFilterBlockedCopy(["Has attachment"]),
 			}}
 		/>
 	),

package/src/index.ts

@@ -502,6 +502,7 @@ export {
 	DROPPED_SEMANTIC_COPY,
 	droppedFacetsCopy,
 	hasConversionNotice,
+	makeFilterBlockedCopy,
 	type SearchConversionNotice,
 	scopedOutCopy,
 } from "./components/search-conversion.js";
@@ -678,6 +679,17 @@ export {
 	formatByteSize,
 	sanitizeAttachmentFilename,
 } from "./lib/attachment-file.js";
+export {
+	briefChipCategory,
+	briefChipFilters,
+	briefFilterHasTerm,
+	briefQueryCategory,
+	briefQueryFilters,
+	briefQueryIsActive,
+	clearBriefFiltersInQuery,
+	setBriefCategoryInQuery,
+	toggleBriefFilterInQuery,
+} from "./lib/brief-filter-query.js";
 export {
 	buildCidResolver,
 	type CidResolvableBodyPart,
@@ -775,6 +787,14 @@ export {
 	useRovingFocus,
 } from "./lib/roving-focus.js";
 export { type RuleNameParts, suggestRuleName } from "./lib/rule-name.js";
+export {
+	quoteSearchTokenValue,
+	type SearchQueryWord,
+	type SearchTermParts,
+	searchTokenTerm,
+	splitSearchTerm,
+	splitSearchWords,
+} from "./lib/search-query-words.js";
 export {
 	type DroppedFacet,
 	type DroppedFacetType,

package/src/lib/brief-filter-query.test.ts

@@ -0,0 +1,200 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import type { BriefFilterId } from "../components/brief-sections.js";
+import {
+	briefChipCategory,
+	briefChipFilters,
+	briefFilterHasTerm,
+	briefQueryCategory,
+	briefQueryFilters,
+	clearBriefFiltersInQuery,
+	setBriefCategoryInQuery,
+	toggleBriefFilterInQuery,
+} from "./brief-filter-query.js";
+
+const ids = (filters: ReadonlySet<BriefFilterId>): BriefFilterId[] =>
+	[...filters].sort();
+
+describe("ticking a chip while a search is on", () => {
+	it("writes its term into the query, where it can be read", () => {
+		assert.equal(
+			toggleBriefFilterInQuery("Odido", "unread"),
+			"Odido is:unread",
+		);
+	});
+
+	it("writes the attachment term the same way", () => {
+		assert.equal(
+			toggleBriefFilterInQuery("Odido", "attachment"),
+			"Odido has:attachment",
+		);
+	});
+
+	it("takes the term back out when the chip is unticked", () => {
+		assert.equal(
+			toggleBriefFilterInQuery("Odido is:unread", "unread"),
+			"Odido",
+		);
+	});
+
+	it("leaves a chips-only query behind once the words are deleted", () => {
+		assert.equal(toggleBriefFilterInQuery("", "unread"), "is:unread");
+	});
+
+	it("says a chip has no term rather than writing one that means nothing", () => {
+		assert.equal(toggleBriefFilterInQuery("Odido", "contacts"), undefined);
+		assert.equal(toggleBriefFilterInQuery("Odido", "today"), undefined);
+		assert.equal(briefFilterHasTerm("contacts"), false);
+		assert.equal(briefFilterHasTerm("today"), false);
+	});
+});
+
+describe("scoping to a category while a search is on", () => {
+	it("writes the category term", () => {
+		assert.equal(
+			setBriefCategoryInQuery("Odido", "newsletter"),
+			"Odido category:newsletter",
+		);
+	});
+
+	it("swaps one category for another rather than stacking them", () => {
+		assert.equal(
+			setBriefCategoryInQuery("Odido category:newsletter", "marketing"),
+			"Odido category:marketing",
+		);
+	});
+
+	it("takes the term out again when the scope goes back to all", () => {
+		assert.equal(
+			setBriefCategoryInQuery("Odido category:newsletter", "all"),
+			"Odido",
+		);
+	});
+});
+
+describe("a term edited or deleted by hand", () => {
+	it("ticks the chip it names", () => {
+		assert.deepEqual(ids(briefQueryFilters("Odido is:unread")), ["unread"]);
+	});
+
+	it("reads the same whatever case it is typed in", () => {
+		assert.deepEqual(ids(briefQueryFilters("Odido IS:Unread")), ["unread"]);
+	});
+
+	it("unticks the chip once it is deleted", () => {
+		assert.deepEqual(ids(briefQueryFilters("Odido")), []);
+	});
+
+	it("scopes the category the term names, alias included", () => {
+		assert.equal(briefQueryCategory("Odido category:newsletter"), "newsletter");
+		assert.equal(
+			briefQueryCategory("Odido category:unclassified"),
+			"uncategorized",
+		);
+	});
+
+	it("leaves the scope alone for a category nobody has", () => {
+		assert.equal(briefQueryCategory("Odido category:nonsense"), "all");
+	});
+
+	it("never reads its own word as a category", () => {
+		assert.equal(briefQueryCategory("category:all"), "all");
+	});
+
+	it("keeps the words the query is otherwise made of", () => {
+		assert.equal(
+			clearBriefFiltersInQuery(
+				"Odido is:unread category:newsletter from:a@b.c",
+			),
+			"Odido from:a@b.c",
+		);
+	});
+});
+
+/**
+ * Terms are cut the way the parser cuts them. A splitter that broke on
+ * whitespace alone read a facet inside a quoted value as a facet of its own,
+ * and missed a quoted one that the parser applies — so the chip row disagreed
+ * with the rows on screen, and editing reached inside what the user typed.
+ */
+describe("a quoted value", () => {
+	it("keeps a facet spelled inside it out of the chips", () => {
+		assert.deepEqual(ids(briefQueryFilters('subject:"a is:unread b"')), []);
+	});
+
+	it("is left whole when a chip is ticked beside it", () => {
+		assert.equal(
+			toggleBriefFilterInQuery('subject:"a is:unread b"', "unread"),
+			'subject:"a is:unread b" is:unread',
+		);
+	});
+
+	it("ticks the chip when it is the facet's own value", () => {
+		assert.deepEqual(ids(briefQueryFilters('is:"unread"')), ["unread"]);
+	});
+
+	it("is removed by unticking rather than joined by a second term", () => {
+		assert.equal(toggleBriefFilterInQuery('is:"unread"', "unread"), "");
+	});
+
+	it("scopes the category it names", () => {
+		assert.equal(briefQueryCategory('category:"Newsletter"'), "newsletter");
+	});
+
+	// Two category terms AND to nothing (`matchesSearchTokens`), so a category
+	// pill that left the old one behind emptied the list on a click.
+	it("leaves one category term behind when another is picked", () => {
+		assert.equal(
+			setBriefCategoryInQuery('category:"Newsletter"', "marketing"),
+			"category:marketing",
+		);
+	});
+
+	it("is cleared with the rest of the chip terms", () => {
+		assert.equal(
+			clearBriefFiltersInQuery('Odido is:"unread" category:"Newsletter"'),
+			"Odido",
+		);
+	});
+});
+
+describe("the chips the panel shows ticked", () => {
+	it("are the panel's own while nothing is being searched", () => {
+		assert.deepEqual(
+			ids(briefChipFilters({ query: "", ownFilters: new Set(["unread"]) })),
+			["unread"],
+		);
+		assert.equal(
+			briefChipCategory({ query: "", ownCategory: "newsletter" }),
+			"newsletter",
+		);
+	});
+
+	it("are the query's terms while a search is on", () => {
+		assert.deepEqual(
+			ids(
+				briefChipFilters({
+					query: "Odido has:attachment",
+					ownFilters: new Set(["unread"]),
+				}),
+			),
+			["attachment"],
+		);
+		assert.equal(
+			briefChipCategory({ query: "Odido", ownCategory: "newsletter" }),
+			"all",
+		);
+	});
+
+	it("carry the chips the vocabulary cannot spell across a search", () => {
+		assert.deepEqual(
+			ids(
+				briefChipFilters({
+					query: "Odido is:unread",
+					ownFilters: new Set(["today", "contacts"]),
+				}),
+			),
+			["contacts", "today", "unread"],
+		);
+	});
+});

package/src/lib/brief-filter-query.ts

@@ -0,0 +1,173 @@
+/**
+ * The brief's chips as terms of the search query (#460).
+ *
+ * While something is being searched, a chip and a typed term are the same
+ * thing: ticking "Unread" over `Odido` leaves `Odido is:unread` in the field,
+ * which the user can read, edit and delete, and deleting it unticks the chip.
+ * The vocabulary is the one the search field already parses — `is:unread`,
+ * `has:attachment`, `category:<id>` — so a chip writes a term the engines
+ * already honour rather than a second, invisible filter stack over the same
+ * rows.
+ *
+ * Two of the brief's chips have no term in that vocabulary: "From contacts"
+ * matches on sender trust, which no facet names, and "Today" is a relative
+ * window where the vocabulary carries only absolute `before:`/`after:` dates.
+ * Those two keep narrowing from the panel's own state, which is why
+ * {@link briefChipFilters} carries them across a search rather than dropping
+ * them.
+ *
+ * Terms are cut and read with `search-query-words.ts`, the splitter the token
+ * parser itself uses, so a chip ticks for exactly what the parser applies:
+ * `is:"unread"` is the unread facet, and an `is:unread` inside a quoted value
+ * belongs to that value.
+ */
+
+import {
+	type BriefCategoryFilter,
+	isBriefCategory,
+} from "../components/app-shell-types.js";
+import type { BriefFilterId } from "../components/brief-sections.js";
+import {
+	searchTokenTerm,
+	splitSearchTerm,
+	splitSearchWords,
+} from "./search-query-words.js";
+
+interface FilterTerm {
+	id: BriefFilterId;
+	name: string;
+	value: string;
+}
+
+const FILTER_TERMS: readonly FilterTerm[] = [
+	{ id: "unread", name: "is", value: "unread" },
+	{ id: "attachment", name: "has", value: "attachment" },
+];
+
+const CATEGORY_TERM_NAME = "category";
+
+/** Category spellings beyond the ids themselves, as the token parser reads them. */
+const CATEGORY_ALIASES: Record<string, BriefCategoryFilter> = {
+	unclassified: "uncategorized",
+};
+
+const words = (query: string): string[] =>
+	splitSearchWords(query).map((word) => word.raw);
+
+const rejoin = (kept: string[]): string => kept.join(" ");
+
+/**
+ * The chip a term names, read the way the parser reads it: `is:"unread"` is the
+ * unread facet, and an `is:unread` sitting inside a quoted value is not a term
+ * at all.
+ */
+const filterOfWord = (word: string): BriefFilterId | undefined => {
+	const parts = splitSearchTerm(word);
+	if (!parts) return undefined;
+	return FILTER_TERMS.find(
+		(term) =>
+			term.name === parts.name && term.value === parts.value.toLowerCase(),
+	)?.id;
+};
+
+const categoryOfWord = (word: string): BriefCategoryFilter | undefined => {
+	const parts = splitSearchTerm(word);
+	if (!parts || parts.name !== CATEGORY_TERM_NAME) return undefined;
+	const value = parts.value.toLowerCase();
+	const alias = CATEGORY_ALIASES[value];
+	if (alias) return alias;
+	if (!isBriefCategory(value) || value === "all") return undefined;
+	return value;
+};
+
+const termFor = (id: BriefFilterId): FilterTerm | undefined =>
+	FILTER_TERMS.find((term) => term.id === id);
+
+/** Whether a chip is one the search vocabulary can express. */
+export const briefFilterHasTerm = (id: BriefFilterId): boolean =>
+	termFor(id) !== undefined;
+
+/** The chips a query's own terms tick. */
+export const briefQueryFilters = (
+	query: string,
+): ReadonlySet<BriefFilterId> => {
+	const ticked = new Set<BriefFilterId>();
+	for (const word of words(query)) {
+		const id = filterOfWord(word);
+		if (id) ticked.add(id);
+	}
+	return ticked;
+};
+
+/** The category a query is scoped to by its own terms, `"all"` when none is. */
+export const briefQueryCategory = (query: string): BriefCategoryFilter => {
+	let category: BriefCategoryFilter = "all";
+	for (const word of words(query)) {
+		const named = categoryOfWord(word);
+		if (named) category = named;
+	}
+	return category;
+};
+
+/**
+ * The query with a chip's term written in or taken out, or `undefined` when the
+ * chip has no term — the caller narrows the same rows from the panel's own
+ * state instead, rather than pressing a control that writes nothing.
+ */
+export const toggleBriefFilterInQuery = (
+	query: string,
+	id: BriefFilterId,
+): string | undefined => {
+	const term = termFor(id);
+	if (!term) return undefined;
+	const typed = words(query);
+	const kept = typed.filter((word) => filterOfWord(word) !== id);
+	if (kept.length < typed.length) return rejoin(kept);
+	return rejoin([...typed, searchTokenTerm(term.name, term.value)]);
+};
+
+/** The query scoped to one category, or with its category term taken out for `"all"`. */
+export const setBriefCategoryInQuery = (
+	query: string,
+	category: BriefCategoryFilter,
+): string => {
+	const kept = words(query).filter((word) => !categoryOfWord(word));
+	if (category === "all") return rejoin(kept);
+	return rejoin([...kept, searchTokenTerm(CATEGORY_TERM_NAME, category)]);
+};
+
+/** The query with every chip term taken out, leaving what was typed. */
+export const clearBriefFiltersInQuery = (query: string): string =>
+	rejoin(
+		words(query).filter((word) => !filterOfWord(word) && !categoryOfWord(word)),
+	);
+
+/** Whether a query is narrowing the list — the state in which chips are terms. */
+export const briefQueryIsActive = (query: string): boolean =>
+	query.trim().length > 0;
+
+/**
+ * The chips shown ticked. Under a query the terms are the whole answer for
+ * every chip that has one; the two that have none keep answering to the panel's
+ * own state, so a search never silently stops them narrowing.
+ */
+export const briefChipFilters = (input: {
+	query: string;
+	ownFilters: ReadonlySet<BriefFilterId>;
+}): ReadonlySet<BriefFilterId> => {
+	if (!briefQueryIsActive(input.query)) return input.ownFilters;
+	const ticked = new Set(briefQueryFilters(input.query));
+	for (const id of input.ownFilters) {
+		if (!briefFilterHasTerm(id)) ticked.add(id);
+	}
+	return ticked;
+};
+
+/** The category scope shown selected — the query's under a query, else the panel's. */
+export const briefChipCategory = (input: {
+	query: string;
+	ownCategory: BriefCategoryFilter;
+}): BriefCategoryFilter =>
+	briefQueryIsActive(input.query)
+		? briefQueryCategory(input.query)
+		: input.ownCategory;

package/src/lib/search-query-words.ts

@@ -0,0 +1,93 @@
+/**
+ * How a search query is cut into terms.
+ *
+ * One implementation, because two would disagree: the token parser
+ * (`web-client/src/lib/search-tokens.ts`) reads `in:"Sent Items"` as one term
+ * and the brief's chips write and remove terms of the same query
+ * (`brief-filter-query.ts`). A splitter that broke on whitespace alone would
+ * read `is:unread` inside a quoted value as a term of its own, and editing it
+ * would reach inside what the user typed between quotes.
+ *
+ * A value carrying whitespace is written in double quotes; an unterminated
+ * quote runs to the end of the input, so a value stays one term while it is
+ * still being typed.
+ */
+
+/** One whitespace-separated term of a query, with where it sits in the input. */
+export interface SearchQueryWord {
+	/** The term exactly as typed, quotes included. */
+	raw: string;
+	/** Index of the term's first character in the query. */
+	start: number;
+	/** Index just past the term's last character. */
+	end: number;
+}
+
+/** Split a query into terms on whitespace, except inside double quotes. */
+export function splitSearchWords(query: string): SearchQueryWord[] {
+	const words: SearchQueryWord[] = [];
+	let start = -1;
+	let quoted = false;
+	for (let i = 0; i < query.length; i++) {
+		const char = query[i] as string;
+		if (char === '"') {
+			quoted = !quoted;
+			if (start < 0) start = i;
+			continue;
+		}
+		if (!quoted && /\s/.test(char)) {
+			if (start >= 0) words.push({ raw: query.slice(start, i), start, end: i });
+			start = -1;
+			continue;
+		}
+		if (start < 0) start = i;
+	}
+	if (start >= 0) {
+		words.push({ raw: query.slice(start), start, end: query.length });
+	}
+	return words;
+}
+
+/** A term split at its first colon: the token name and the value as typed. */
+export interface SearchTermParts {
+	name: string;
+	/** The value with its quotes removed. */
+	value: string;
+	/** The value exactly as typed, quotes included. */
+	rawValue: string;
+}
+
+const unquote = (value: string): string => {
+	if (!value.startsWith('"')) return value;
+	const inner = value.slice(1);
+	return inner.endsWith('"') ? inner.slice(0, -1) : inner;
+};
+
+/**
+ * Split `name:value` at the first colon. A term with no colon, or one starting
+ * with a colon, is not a token attempt and returns `undefined`.
+ */
+export function splitSearchTerm(word: string): SearchTermParts | undefined {
+	const colon = word.indexOf(":");
+	if (colon <= 0) return undefined;
+	const rawValue = word.slice(colon + 1);
+	return {
+		name: word.slice(0, colon).toLowerCase(),
+		value: unquote(rawValue),
+		rawValue,
+	};
+}
+
+const needsQuotes = (value: string): boolean => /[\s"]/.test(value);
+
+/**
+ * A value as it is written in a query: quoted when it carries whitespace, bare
+ * otherwise. The inverse of the unquoting above, so a suggestion the user picks
+ * parses back to the value it was built from.
+ */
+export const quoteSearchTokenValue = (value: string): string =>
+	needsQuotes(value) ? `"${value.replace(/"/g, "")}"` : value;
+
+/** `name:value`, quoted as needed — the text a query carries for one token. */
+export const searchTokenTerm = (name: string, value: string): string =>
+	`${name}:${quoteSearchTokenValue(value)}`;