@remit/ui 0.0.78 → 0.0.80

package/package.json

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

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

@@ -213,6 +213,15 @@ export const briefCategories: ReadonlyArray<{
 	{ id: "social", label: "Social" },
 ];
 
+/**
+ * Whether an id names one of the brief's category scopes. A host holding one
+ * category across views whose sheets speak plain strings narrows it with this
+ * rather than asserting it.
+ */
+export function isBriefCategory(id: string): id is BriefCategoryFilter {
+	return briefCategories.some((c) => c.id === id);
+}
+
 export interface ThreadRowLabel {
 	labelId: string;
 	name: string;

package/src/components/app-shell.tsx

@@ -244,11 +244,10 @@ function AppShellList({
 			searchQuery={searchQuery}
 			onRetry={onRetry}
 			onReportError={onReportError}
-			briefCategory={briefCategory}
+			briefFilter={{ briefCategory, onSelectBriefCategory }}
 			selectedThreadId={selectedThreadId}
 			density={density}
 			onSelectThread={onSelectThread}
-			onSelectBriefCategory={onSelectBriefCategory}
 			onOpenNav={showNavPane ? undefined : layout?.openNav}
 			isDesktop={showReadingPane}
 			initialTouchState={initialTouchState}

package/src/components/app-top-bar.stories.tsx

@@ -1,11 +1,13 @@
 import type { Meta, StoryObj } from "@storybook/react";
-import { Bug, SquarePen } from "lucide-react";
 import { useState } from "react";
 import { AppTopBar } from "./app-top-bar.js";
-import { Avatar } from "./avatar.js";
-import { Button } from "./button.js";
-import { type SearchChip, SearchChipInput } from "./search-chip-input.js";
+import { SearchChipInput } from "./search-chip-input.js";
 
+/**
+ * The bar's geometry. What fills it — which actions, in what order, with what
+ * wording — is `ShellTopBar`, which is what the app and the shell prototype
+ * both mount; these stories show only the row the slots sit in.
+ */
 const meta: Meta<typeof AppTopBar> = {
 	title: "Mail/AppTopBar",
 	component: AppTopBar,
@@ -15,169 +17,64 @@ export default meta;
 
 type Story = StoryObj<typeof AppTopBar>;
 
-const Actions = () => (
-	<>
-		<Button
-			variant="ghost"
-			size="sm"
-			icon={<SquarePen className="size-4" />}
-			title="Compose"
-			aria-label="Compose"
-		/>
-		<Button
-			variant="ghost"
-			size="sm"
-			icon={<Bug className="size-4" />}
-			title="Report a bug"
-			aria-label="Report a bug"
-		/>
-		<Avatar name="Matthijs van Henten" email="mvh@example.com" size="sm" />
-	</>
+const Slot = ({ label }: { label: string }) => (
+	<div className="rounded border border-dashed border-line px-2 py-1 text-2xs text-fg-subtle">
+		{label}
+	</div>
 );
 
-const SCOPE: SearchChip = { id: "in:spam", label: "in:spam", tone: "scope" };
-
-/**
- * The placeholders the app pairs with each scope state. Only the unscoped brief
- * may claim to search all mail; a scoped view says so, and a mailbox route
- * whose name has not loaded yet gets neutral wording rather than a placeholder
- * asserting the wrong scope.
- */
-const PLACEHOLDER = {
-	global: "Search all mail",
-	pending: "Search mail",
-	scoped: "Search this folder",
-} as const;
-
-const Bar = ({
-	initialChips = [],
-	placeholder = PLACEHOLDER.global,
-}: {
-	initialChips?: SearchChip[];
-	placeholder?: string;
-}) => {
-	const [chips, setChips] = useState<SearchChip[]>(initialChips);
+const Field = () => {
 	const [value, setValue] = useState("");
 	return (
-		<AppTopBar
-			actions={<Actions />}
-			search={
-				<SearchChipInput
-					size="lg"
-					chips={chips}
-					onRemoveChip={(id) => setChips((cs) => cs.filter((c) => c.id !== id))}
-					value={value}
-					onChange={setValue}
-					onClear={() => {
-						setValue("");
-						setChips([]);
-					}}
-					onClearQuery={() => setValue("")}
-					globalFocusKey={false}
-					placeholder={placeholder}
-				/>
-			}
+		<SearchChipInput
+			size="lg"
+			value={value}
+			onChange={setValue}
+			onClear={() => setValue("")}
+			onClearQuery={() => setValue("")}
+			globalFocusKey={false}
+			placeholder="Search all mail"
 		/>
 	);
 };
 
-/** Over the panes it spans, so the arrangement reads the way it will in the app. */
-const WithPanes = ({ children }: { children: React.ReactNode }) => (
-	<div className="flex h-96 flex-col bg-canvas">
-		{children}
-		<div className="flex min-h-0 flex-1">
-			<div className="w-56 shrink-0 border-r border-line bg-surface p-3 text-xs text-fg-muted">
-				Nav — under the bar, like every other pane
-			</div>
-			<div className="w-72 shrink-0 border-r border-line bg-surface p-3 text-xs text-fg-muted">
-				Message list
-			</div>
-			<div className="min-w-0 flex-1 p-3 text-xs text-fg-muted">
-				Message pane — its own toolbar lives here, under the bar
-			</div>
-		</div>
-	</div>
-);
-
-/**
- * The daily brief's state: search unscoped, nothing narrowing it. No chip, and
- * the only placeholder allowed to claim it searches all mail — which it now
- * genuinely does, across every folder of every account.
- */
-export const Unscoped: Story = {
-	render: () => <Bar />,
-};
-
-/**
- * A narrowing scope in the bar, tinted to mark it as the view the user is in
- * rather than a filter they typed. Removing it widens the search again — a
- * navigation back to the brief, not an edit of the text, because the chip
- * mirrors the route.
- *
- * The placeholder narrows with the chip. A scoped bar reading "Search all mail"
- * is a state the app never produces.
- */
-export const Scoped: Story = {
-	render: () => <Bar initialChips={[SCOPE]} placeholder={PLACEHOLDER.scoped} />,
-};
-
-/**
- * The third scope state: a mailbox route whose name has not resolved yet. The
- * list underneath is already narrowed, so the bar must not claim to search
- * everything — but a chip reading a raw uuid is worse than no chip, so it shows
- * none and falls back to neutral wording until the name arrives.
- */
-export const ScopePending: Story = {
-	render: () => <Bar placeholder={PLACEHOLDER.pending} />,
-};
-
-/**
- * The virtual collections scope the bar too, and their chips read as whatever
- * describes the collection. Flagged is a marker on the mail rather than a
- * place, so it chips `is:starred`; the outbox is a place mail sits in and keeps
- * the `in:` form.
- */
-export const ScopedToFlagged: Story = {
+/** Leading · search · actions. The field is the only slot that grows. */
+export const Slots: Story = {
 	render: () => (
-		<Bar
-			initialChips={[{ id: "is:starred", label: "is:starred", tone: "scope" }]}
-			placeholder={PLACEHOLDER.scoped}
+		<AppTopBar
+			leading={<Slot label="leading" />}
+			search={<Field />}
+			actions={<Slot label="actions" />}
 		/>
 	),
 };
 
-export const ScopedToOutbox: Story = {
-	render: () => (
-		<Bar
-			initialChips={[{ id: "in:outbox", label: "in:outbox", tone: "scope" }]}
-			placeholder={PLACEHOLDER.scoped}
-		/>
-	),
+/** With nothing but the field, the bar is still the page's one search surface. */
+export const SearchOnly: Story = {
+	render: () => <AppTopBar search={<Field />} />,
 };
 
-/** The arrangement: one bar across the top of the shell, over the nav, the list
- *  and the message pane alike. */
+/** One row across the top of the shell, over the nav, the list and the message
+ *  pane alike. */
 export const OverTheLayout: Story = {
 	render: () => (
-		<WithPanes>
-			<Bar initialChips={[SCOPE]} placeholder={PLACEHOLDER.scoped} />
-		</WithPanes>
-	),
-};
-
-export const SearchOnly: Story = {
-	render: () => (
-		<AppTopBar
-			search={
-				<SearchChipInput
-					size="lg"
-					value=""
-					onChange={() => undefined}
-					onClear={() => undefined}
-					globalFocusKey={false}
-					placeholder="Search all mail"
-				/>
-			}
-		/>
+		<div className="flex h-96 flex-col bg-canvas">
+			<AppTopBar
+				leading={<Slot label="leading" />}
+				search={<Field />}
+				actions={<Slot label="actions" />}
+			/>
+			<div className="flex min-h-0 flex-1">
+				<div className="w-56 shrink-0 border-r border-line bg-surface p-3 text-xs text-fg-muted">
+					Nav — under the bar, like every other pane
+				</div>
+				<div className="w-72 shrink-0 border-r border-line bg-surface p-3 text-xs text-fg-muted">
+					Message list
+				</div>
+				<div className="min-w-0 flex-1 p-3 text-xs text-fg-muted">
+					Message pane — its own toolbar lives here, under the bar
+				</div>
+			</div>
+		</div>
 	),
 };

package/src/components/brief-sections.tsx

@@ -56,6 +56,16 @@ export const briefFilterChips: FilterSheetFilter[] = briefFilterDefs.map(
 	({ id, label }) => ({ id, label }),
 );
 
+/**
+ * Whether an id names one of the brief's attribute chips. A consumer holding
+ * one filter set across several views — the workbench shell, whose mailbox
+ * sheet offers chips of its own — narrows that set to the brief's own with
+ * this rather than asserting it.
+ */
+export function isBriefFilterId(id: string): id is BriefFilterId {
+	return briefFilterDefs.some((f) => f.id === id);
+}
+
 /**
  * Whether a thread survives a set of attribute chips, as the brief's own list
  * applies them. Exported so a consumer narrowing the same rows on another
@@ -77,7 +87,7 @@ export function matchesBriefFilters(
  * search takeover) holds the set so both surfaces answer to one selection, and
  * takes every control over it with the set.
  */
-type BriefFilterControl =
+export type BriefFilterControl =
 	| {
 			activeFilters: ReadonlySet<BriefFilterId>;
 			onToggleFilter: (id: BriefFilterId) => void;
@@ -89,13 +99,8 @@ type BriefFilterControl =
 			onClearFilters?: never;
 	  };
 
-interface BriefSectionsBaseProps {
-	sections: ThreadSection[];
-	briefCategory?: BriefCategoryFilter;
-	selectedThreadId?: string;
-	Row: BriefRowComponent;
-	onSelectThread?: (id: string) => void;
-	onSelectBriefCategory?: (category: BriefCategoryFilter) => void;
+/** The accounts the aggregate is segmented by, as the FilterSheet draws them. */
+export interface BriefSourceControl {
 	/**
 	 * Account/source pills, passed straight through to the FilterSheet. Selection
 	 * is encoded per source via `active`; the row only renders when more than one
@@ -106,6 +111,31 @@ interface BriefSectionsBaseProps {
 	sourcesNote?: string;
 	/** Called when the user selects a source/account pill. */
 	onSelectSource?: (id: string) => void;
+}
+
+/** The single category the sections are scoped to. */
+export interface BriefCategoryControl {
+	briefCategory?: BriefCategoryFilter;
+	onSelectBriefCategory?: (category: BriefCategoryFilter) => void;
+}
+
+/**
+ * The brief's whole filter surface as a host holds it: the category scope, the
+ * account pills and the attribute chips. A host with a second surface over the
+ * same rows — the phone search takeover — holds this one set and hands it to
+ * both, so a filter set on either is set on both.
+ */
+export type BriefFilterSurface = BriefCategoryControl &
+	BriefSourceControl &
+	BriefFilterControl;
+
+interface BriefSectionsBaseProps
+	extends BriefCategoryControl,
+		BriefSourceControl {
+	sections: ThreadSection[];
+	selectedThreadId?: string;
+	Row: BriefRowComponent;
+	onSelectThread?: (id: string) => void;
 	/**
 	 * Drop the filter row and its panel, keeping the rows where they are. See
 	 * `FilterSheetProps`.

package/src/components/filter-sheet.tsx

@@ -138,19 +138,35 @@ const FilterPanelCtx = createContext<FilterPanelState | null>(null);
  * body is sometimes something else — a skeleton, an empty state, an error —
  * would otherwise inherit a caret over nothing by saying nothing. Compute it
  * from what the body renders, in the same pass that renders it.
+ *
+ * `open`/`onOpenChange` hand the panel's state to the host, for a view whose
+ * second surface — the phone search takeover — replaces this provider while it
+ * is up. Omit both and the provider keeps the state itself.
  */
 export function FilterPanelProvider({
 	children,
 	hasSheet,
+	open: openProp,
+	onOpenChange,
 }: {
 	children?: ReactNode;
 	hasSheet: boolean;
+	open?: boolean;
+	onOpenChange?: (open: boolean) => void;
 }) {
-	const [open, setOpen] = useState(false);
+	const [internalOpen, setInternalOpen] = useState(false);
 	const [active, setActive] = useState(false);
+	const open = openProp ?? internalOpen;
+	const setOpen = useCallback(
+		(next: boolean) => {
+			if (openProp === undefined) setInternalOpen(next);
+			onOpenChange?.(next);
+		},
+		[openProp, onOpenChange],
+	);
 	const value = useMemo(
 		() => ({ open, setOpen, active, setActive, hasSheet }),
-		[open, active, hasSheet],
+		[open, setOpen, active, hasSheet],
 	);
 	return (
 		<FilterPanelCtx.Provider value={value}>{children}</FilterPanelCtx.Provider>
@@ -296,11 +312,15 @@ export function FilterSheet({
 	);
 
 	const sourceRow = sources && sources.length > 1 && (
-		<div className="flex flex-wrap items-center gap-1.5 border-b border-line px-row-inset pb-2 pt-2">
+		<fieldset
+			aria-label="Accounts"
+			className="min-w-0 flex flex-wrap items-center gap-1.5 border-b border-line px-row-inset pb-2 pt-2"
+		>
 			{sources.map((source) => (
 				<button
 					key={source.id}
 					type="button"
+					aria-pressed={Boolean(source.active)}
 					onClick={() => onSelectSource?.(source.id)}
 					className={cn(
 						"flex items-center gap-1 rounded-full border px-2.5 py-0.5 text-2xs transition-colors",
@@ -320,17 +340,21 @@ export function FilterSheet({
 					{sourcesNote}
 				</span>
 			)}
-		</div>
+		</fieldset>
 	);
 
 	const categoryRow = (
-		<div className="flex flex-wrap items-center gap-1.5 border-b border-line px-row-inset pb-1.5 pt-1.5">
+		<fieldset
+			aria-label="Categories"
+			className="min-w-0 flex flex-wrap items-center gap-1.5 border-b border-line px-row-inset pb-1.5 pt-1.5"
+		>
 			{categories.map((cat) => {
 				const selected = selectedCategory === cat.id;
 				return (
 					<button
 						key={cat.id}
 						type="button"
+						aria-pressed={selected}
 						onClick={() => onSelectCategory(cat.id)}
 						className={cn(
 							"shrink-0 rounded-full transition-opacity",
@@ -343,17 +367,21 @@ export function FilterSheet({
 					</button>
 				);
 			})}
-		</div>
+		</fieldset>
 	);
 
 	const filterRow = (
-		<div className="flex flex-wrap items-center gap-1.5 border-b border-line px-row-inset pb-2 pt-1.5">
+		<fieldset
+			aria-label="Attributes"
+			className="min-w-0 flex flex-wrap items-center gap-1.5 border-b border-line px-row-inset pb-2 pt-1.5"
+		>
 			{filters.map((f) => {
 				const on = activeFilters.has(f.id);
 				return (
 					<button
 						key={f.id}
 						type="button"
+						aria-pressed={on}
 						onClick={() => onToggleFilter(f.id)}
 						className={cn(
 							"shrink-0 rounded-full border px-2.5 py-0.5 text-2xs transition-colors",
@@ -376,7 +404,7 @@ export function FilterSheet({
 					Clear
 				</button>
 			)}
-		</div>
+		</fieldset>
 	);
 
 	return (

package/src/components/message-list-pane.brief-filter.test.ts

@@ -0,0 +1,185 @@
+/**
+ * The cross-account brief's account pills reach the panel through the pane that
+ * renders the brief, not only through `BriefSections` mounted on its own. The
+ * caret has to be pressed for the panel to be up, so this mounts against jsdom
+ * rather than `renderToString`.
+ */
+import assert from "node:assert/strict";
+import { after, afterEach, before, beforeEach, describe, it } from "node:test";
+import type { JSDOM } from "jsdom";
+import { act, createElement } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import type { ThreadSection } from "./app-shell-types.js";
+import type { BriefFilterSurface } from "./brief-sections.js";
+import { MessageListPane } from "./message-list-pane.js";
+
+const sections: ThreadSection[] = [
+	{
+		id: "personal",
+		label: "Personal",
+		threads: [
+			{
+				id: "t1",
+				accountId: "acc_personal",
+				fromName: "Priya Nair",
+				fromEmail: "priya@example.com",
+				subject: "Design review tomorrow",
+				snippet: "Can we move it to 2pm?",
+				timeLabel: "8:15",
+				isRead: false,
+				category: "personal",
+			},
+		],
+	},
+];
+
+const sources = [
+	{ id: "all", label: "All", active: true },
+	{ id: "acc_personal", label: "Personal", count: 4 },
+	{ id: "acc_work", label: "Work", count: 7 },
+];
+
+let dom: JSDOM;
+let container: HTMLElement;
+let root: Root;
+
+before(async () => {
+	const { JSDOM: JSDOMCtor } = await import("jsdom");
+	dom = new JSDOMCtor(
+		"<!doctype html><html><body><div id=root></div></body></html>",
+		{ url: "http://localhost/", pretendToBeVisual: true },
+	);
+	globalThis.window = dom.window as unknown as typeof globalThis.window;
+	globalThis.document = dom.window.document;
+	globalThis.HTMLElement = dom.window.HTMLElement;
+	globalThis.Element = dom.window.Element;
+	globalThis.MouseEvent = dom.window.MouseEvent;
+	Object.defineProperty(globalThis, "navigator", {
+		value: dom.window.navigator,
+		configurable: true,
+	});
+	(
+		globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+	).IS_REACT_ACT_ENVIRONMENT = true;
+});
+
+after(() => {
+	dom.window.close();
+});
+
+beforeEach(() => {
+	container = dom.window.document.getElementById(
+		"root",
+	) as unknown as HTMLElement;
+	container.innerHTML = "";
+	root = createRoot(container);
+});
+
+afterEach(() => {
+	act(() => {
+		root.unmount();
+	});
+});
+
+function mount(briefFilter?: BriefFilterSurface) {
+	act(() => {
+		root.render(
+			createElement(MessageListPane, {
+				listTitle: "Daily brief",
+				sections,
+				briefFilters: true,
+				isDesktop: true,
+				briefFilter,
+			}),
+		);
+	});
+}
+
+function click(element: Element) {
+	act(() => {
+		element.dispatchEvent(
+			new dom.window.MouseEvent("click", { bubbles: true, cancelable: true }),
+		);
+	});
+}
+
+function openPanel() {
+	const caret = container.querySelector('[aria-label="Expand filters"]');
+	assert.ok(caret, "the pane offers a way to open the filter panel");
+	click(caret);
+}
+
+function labels(selector: string): string[] {
+	return Array.from(container.querySelectorAll(selector)).map((node) =>
+		(node.textContent ?? "").trim(),
+	);
+}
+
+describe("the brief's filter panel inside the message list pane", () => {
+	it("carries the account pills and the muted note it is given", () => {
+		mount({
+			sources,
+			sourcesNote: "+1 muted",
+			onSelectSource: () => undefined,
+		});
+		openPanel();
+		const pills = labels("button");
+		assert.ok(
+			pills.includes("Personal4"),
+			"a pill per account, with its count",
+		);
+		assert.ok(pills.includes("Work7"));
+		assert.match(container.textContent ?? "", /\+1 muted/);
+	});
+
+	it("reports the pill the user picks", () => {
+		let picked: string | undefined;
+		mount({
+			sources,
+			onSelectSource: (id) => {
+				picked = id;
+			},
+		});
+		openPanel();
+		const work = Array.from(container.querySelectorAll("button")).find(
+			(node) => (node.textContent ?? "").trim() === "Work7",
+		);
+		assert.ok(work);
+		click(work);
+		assert.equal(picked, "acc_work");
+	});
+
+	it("offers no source row without pills", () => {
+		mount();
+		openPanel();
+		assert.doesNotMatch(container.textContent ?? "", /Work/);
+	});
+
+	it("draws the chips the caller holds and reports a toggle", () => {
+		let toggled: string | undefined;
+		mount({
+			sources,
+			activeFilters: new Set(["unread"]),
+			onToggleFilter: (id) => {
+				toggled = id;
+			},
+			onClearFilters: () => undefined,
+		});
+		openPanel();
+		const unread = Array.from(container.querySelectorAll("button")).find(
+			(node) => (node.textContent ?? "").trim() === "Unread",
+		);
+		assert.ok(unread);
+		assert.equal(
+			unread.getAttribute("aria-pressed"),
+			"true",
+			"the held chip reads as active",
+		);
+		const attachment = Array.from(container.querySelectorAll("button")).find(
+			(node) => (node.textContent ?? "").trim() === "Has attachment",
+		);
+		assert.ok(attachment);
+		click(attachment);
+		assert.equal(toggled, "attachment");
+	});
+});

package/src/components/message-list-pane.render.test.ts

@@ -37,7 +37,6 @@ const baseProps = {
 	sections,
 	flatList: true,
 	onSelectThread: () => undefined,
-	onSelectBriefCategory: () => undefined,
 };
 
 describe("MessageListPane", () => {

package/src/components/message-list-pane.stories.tsx

@@ -68,7 +68,6 @@ const meta: Meta<typeof MessageListPane> = {
 		listMeta: "3 conversations",
 		sections,
 		onSelectThread: () => undefined,
-		onSelectBriefCategory: () => undefined,
 	},
 };
 export default meta;

package/src/components/message-list-pane.tsx

@@ -8,7 +8,7 @@ import type {
 	MessageListSelection,
 	TouchSeed,
 } from "./app-shell-types.js";
-import { BriefSections } from "./brief-sections.js";
+import { type BriefFilterSurface, BriefSections } from "./brief-sections.js";
 import { Button } from "./button.js";
 import { KeyboardHintBar } from "./keyboard-hint-bar.js";
 import {
@@ -46,11 +46,10 @@ export function MessageListPane({
 	errorMessage,
 	onRetry,
 	onReportError,
-	briefCategory,
+	briefFilter,
 	selectedThreadId,
 	density = "comfortable",
 	onSelectThread,
-	onSelectBriefCategory,
 	onOpenNav,
 	isDesktop,
 	initialTouchState,
@@ -71,11 +70,9 @@ export function MessageListPane({
 	| "errorMessage"
 	| "onRetry"
 	| "onReportError"
-	| "briefCategory"
 	| "selectedThreadId"
 	| "density"
 	| "onSelectThread"
-	| "onSelectBriefCategory"
 > & {
 	/**
 	 * The active category filter, when the caller has one. Without it the empty
@@ -84,6 +81,14 @@ export function MessageListPane({
 	 * unfiltered, so a surface that filters must pass this.
 	 */
 	listFilter?: MessageListFilter;
+	/**
+	 * The brief's category scope, account pills and attribute chips, held by the
+	 * caller. The cross-account brief is segmented from this panel, and a caller
+	 * narrowing the same rows on a second surface hands both the one set it
+	 * holds. Absent, the chips are the brief's own, no source row is offered and
+	 * every category is in scope.
+	 */
+	briefFilter?: BriefFilterSurface;
 	/** Name of the collection, e.g. "Inbox". Passed to the empty state. */
 	listScopeLabel?: string;
 	/** When set, the list header shows a folders/menu button that opens the nav
@@ -250,12 +255,11 @@ export function MessageListPane({
 				/>
 			) : briefFilters ? (
 				<BriefSections
+					{...(briefFilter ?? {})}
 					sections={sections}
-					briefCategory={briefCategory}
 					selectedThreadId={selectedThreadId}
 					Row={BriefRow}
 					onSelectThread={onSelectThread}
-					onSelectBriefCategory={onSelectBriefCategory}
 				/>
 			) : listBody != null ? (
 				/* Consumer-provided body wins on every width — it owns the rows

package/src/components/shell-top-bar.render.test.ts

@@ -0,0 +1,95 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import {
+	ShellTopBar,
+	type ShellTopBarProps,
+	type ShellTopBarSearch,
+} from "./shell-top-bar.js";
+
+const search = (
+	overrides: Partial<ShellTopBarSearch> = {},
+): ShellTopBarSearch => ({
+	value: "",
+	scope: "global",
+	onChange: () => undefined,
+	onClear: () => undefined,
+	onClearQuery: () => undefined,
+	...overrides,
+});
+
+const render = (overrides: Partial<ShellTopBarProps> = {}): string =>
+	renderToString(
+		createElement(ShellTopBar, {
+			search: search(),
+			onCompose: () => undefined,
+			onReportBug: () => undefined,
+			onOpenSettings: () => undefined,
+			account: createElement("div", { "data-testid": "account" }, "account"),
+			...overrides,
+		}),
+	);
+
+describe("ShellTopBar", () => {
+	it("carries compose, bug report, settings and the account, in that order", () => {
+		const html = render();
+		const compose = html.indexOf('aria-label="Compose"');
+		const bug = html.indexOf('aria-label="Report a bug"');
+		const settings = html.indexOf('aria-label="Settings"');
+		const account = html.indexOf('data-testid="account"');
+		assert.ok(compose > -1 && bug > -1 && settings > -1 && account > -1);
+		assert.ok(
+			compose < bug && bug < settings && settings < account,
+			"actions render in reading order",
+		);
+	});
+
+	it("carries exactly the four actions and nothing else", () => {
+		const labels = [...render().matchAll(/aria-label="([^"]+)"/g)].map(
+			(match) => match[1],
+		);
+		assert.deepEqual(labels, [
+			"Search mail",
+			"Compose",
+			"Report a bug",
+			"Settings",
+		]);
+	});
+
+	it("words the compose tooltip around the host's bare key", () => {
+		assert.match(render({ composeShortcut: "c" }), /title="Compose \(c\)"/);
+	});
+
+	it("names the action alone when the host binds no key to it", () => {
+		assert.match(render(), /title="Compose"/);
+	});
+
+	it("only claims to search all mail when nothing narrows it", () => {
+		assert.match(render(), /placeholder="Search all mail"/);
+	});
+
+	it("says which folder a scoped view searches", () => {
+		assert.match(
+			render({ search: search({ scope: "scoped" }) }),
+			/placeholder="Search this folder"/,
+		);
+	});
+
+	it("carries the route's scope as a chip and drops the claim to search all mail", () => {
+		const html = render({
+			search: search({
+				scope: "scoped",
+				chips: [{ id: "in:spam", label: "in:spam", tone: "scope" }],
+			}),
+		});
+		assert.match(html, /in:spam/);
+		assert.doesNotMatch(html, /Search all mail/);
+	});
+
+	it("falls back to neutral wording while a mailbox name is still loading", () => {
+		const html = render({ search: search({ scope: "pending" }) });
+		assert.match(html, /placeholder="Search mail"/);
+		assert.doesNotMatch(html, /Search all mail/);
+	});
+});

package/src/components/shell-top-bar.stories.tsx

@@ -0,0 +1,132 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { useState } from "react";
+import { Avatar } from "./avatar.js";
+import type { SearchChip } from "./search-chip-input.js";
+import { type ShellSearchScope, ShellTopBar } from "./shell-top-bar.js";
+
+const meta: Meta<typeof ShellTopBar> = {
+	title: "Mail/ShellTopBar",
+	component: ShellTopBar,
+	parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+type Story = StoryObj<typeof ShellTopBar>;
+
+const SCOPE: SearchChip = { id: "in:spam", label: "in:spam", tone: "scope" };
+
+const Account = () => (
+	<button type="button" aria-label="Account">
+		<Avatar name="Matthijs van Henten" email="mvh@example.com" size="sm" />
+	</button>
+);
+
+const Bar = ({
+	initialChips,
+	scope = "global",
+}: {
+	initialChips?: SearchChip[];
+	scope?: ShellSearchScope;
+}) => {
+	const [chips, setChips] = useState<SearchChip[] | undefined>(initialChips);
+	const [value, setValue] = useState("");
+	return (
+		<ShellTopBar
+			search={{
+				value,
+				scope: chips?.length ? scope : "global",
+				chips,
+				onChange: setValue,
+				onClear: () => {
+					setValue("");
+					setChips(undefined);
+				},
+				onClearQuery: () => setValue(""),
+				onRemoveChip: () => setChips(undefined),
+			}}
+			onCompose={() => undefined}
+			onReportBug={() => undefined}
+			onOpenSettings={() => undefined}
+			composeShortcut="c"
+			account={<Account />}
+		/>
+	);
+};
+
+/**
+ * The daily brief's state: search unscoped, nothing narrowing it, and the only
+ * placeholder allowed to claim it searches all mail — which it genuinely does,
+ * across every folder of every account.
+ */
+export const Unscoped: Story = {
+	render: () => <Bar />,
+};
+
+/**
+ * A narrowing scope in the bar, tinted to mark it as the view the user is in
+ * rather than a filter they typed. Removing it widens the search again — a
+ * navigation back to the brief, not an edit of the text, because the chip
+ * mirrors the route. The placeholder narrows with the chip.
+ */
+export const Scoped: Story = {
+	render: () => <Bar initialChips={[SCOPE]} scope="scoped" />,
+};
+
+/**
+ * A mailbox route whose name has not resolved yet. The list underneath is
+ * already narrowed, so the bar must not claim to search everything — and a chip
+ * reading a raw uuid is worse than no chip, so it shows none and falls back to
+ * neutral wording until the name arrives.
+ */
+export const ScopePending: Story = {
+	render: () => (
+		<ShellTopBar
+			search={{
+				value: "",
+				scope: "pending",
+				onChange: () => undefined,
+				onClear: () => undefined,
+				onClearQuery: () => undefined,
+			}}
+			onCompose={() => undefined}
+			onReportBug={() => undefined}
+			onOpenSettings={() => undefined}
+			composeShortcut="c"
+			account={<Account />}
+		/>
+	),
+};
+
+/**
+ * The virtual collections scope the bar too, and their chips read as whatever
+ * describes the collection. Flagged is a marker on the mail rather than a
+ * place, so it chips `is:starred`.
+ */
+export const ScopedToFlagged: Story = {
+	render: () => (
+		<Bar
+			initialChips={[{ id: "is:starred", label: "is:starred", tone: "scope" }]}
+			scope="scoped"
+		/>
+	),
+};
+
+/** The arrangement: one bar across the top of the shell, over every pane. */
+export const OverTheLayout: Story = {
+	render: () => (
+		<div className="flex h-96 flex-col bg-canvas">
+			<Bar initialChips={[SCOPE]} scope="scoped" />
+			<div className="flex min-h-0 flex-1">
+				<div className="w-56 shrink-0 border-r border-line bg-surface p-3 text-xs text-fg-muted">
+					Nav — under the bar, like every other pane
+				</div>
+				<div className="w-72 shrink-0 border-r border-line bg-surface p-3 text-xs text-fg-muted">
+					Message list
+				</div>
+				<div className="min-w-0 flex-1 p-3 text-xs text-fg-muted">
+					Message pane — its own toolbar lives here, under the bar
+				</div>
+			</div>
+		</div>
+	),
+};

package/src/components/shell-top-bar.tsx

@@ -0,0 +1,127 @@
+/**
+ * ShellTopBar — the app's one search surface and its global actions, composed.
+ *
+ * `AppTopBar` is geometry; this is what fills it. It spans the whole layout —
+ * the nav column, the list, the reading pane and the intelligence rail — and
+ * carries the actions that belong to the app rather than to whatever is
+ * currently listed or open: the nav toggle, compose, bug report, settings,
+ * account. Reply, delete, move and the rest stay on the reading pane's own
+ * toolbar, under this bar.
+ *
+ * It is the app's search, not the list's: the list header drops its own field
+ * wherever this bar is mounted, so exactly one search input exists on the page
+ * and the "/" shortcut has one target.
+ *
+ * The field carries one chip: the scope of the view the user navigated into
+ * (`in:spam` in Spam, nothing on the brief). Removing it goes to the brief and
+ * searches everything. Typed `in:`/`from:` terms are not chipped here — they
+ * are already visible as the text the user typed, and chipping them would show
+ * the same term twice in one field; they render as chips over the result
+ * sections instead, where the text is not repeated.
+ *
+ * Which actions, in what order, with what wording lives here and only here, so
+ * the bar the prototype shows is the bar the app shows.
+ */
+import { Bug, Settings, SquarePen } from "lucide-react";
+import type { ReactNode } from "react";
+import { AppTopBar } from "./app-top-bar.js";
+import { Button } from "./button.js";
+import { NavToggleButton } from "./nav-toggle-button.js";
+import { SearchBar } from "./search-bar.js";
+import type { SearchChip } from "./search-chip-input.js";
+
+/**
+ * How narrowed the search already is. Only the unscoped brief may claim to
+ * search all mail; a mailbox route whose name has not loaded yet is already
+ * narrowed but has no chip to show, so it gets neutral wording rather than a
+ * placeholder that asserts the wrong scope.
+ */
+export type ShellSearchScope = "global" | "pending" | "scoped";
+
+const SEARCH_PLACEHOLDER: Record<ShellSearchScope, string> = {
+	global: "Search all mail",
+	pending: "Search mail",
+	scoped: "Search this folder",
+};
+
+export interface ShellTopBarSearch {
+	value: string;
+	scope: ShellSearchScope;
+	chips?: readonly SearchChip[];
+	onChange: (value: string) => void;
+	onClear: () => void;
+	onClearQuery: () => void;
+	onRemoveChip?: (id: string) => void;
+}
+
+export interface ShellTopBarProps {
+	search: ShellTopBarSearch;
+	onCompose: () => void;
+	onReportBug: () => void;
+	onOpenSettings: () => void;
+	/**
+	 * The key that composes, as the host's keymap reads it — `c`, `⌘N`,
+	 * `g then b`. The tooltip's wording around it is this component's.
+	 */
+	composeShortcut?: string;
+	/**
+	 * The account control at the bar's trailing edge. An element rather than
+	 * data: the app hangs a signed-in session and its sign-out off it.
+	 */
+	account: ReactNode;
+}
+
+export function ShellTopBar({
+	search,
+	onCompose,
+	onReportBug,
+	onOpenSettings,
+	composeShortcut,
+	account,
+}: ShellTopBarProps) {
+	return (
+		<AppTopBar
+			leading={<NavToggleButton />}
+			search={
+				<SearchBar
+					value={search.value}
+					onChange={search.onChange}
+					onClear={search.onClear}
+					onClearQuery={search.onClearQuery}
+					chips={search.chips}
+					onRemoveChip={search.onRemoveChip}
+					placeholder={SEARCH_PLACEHOLDER[search.scope]}
+				/>
+			}
+			actions={
+				<>
+					<Button
+						variant="ghost"
+						size="sm"
+						icon={<SquarePen className="size-4" />}
+						title={composeShortcut ? `Compose (${composeShortcut})` : "Compose"}
+						aria-label="Compose"
+						onClick={onCompose}
+					/>
+					<Button
+						variant="ghost"
+						size="sm"
+						icon={<Bug className="size-4" />}
+						title="Report a bug"
+						aria-label="Report a bug"
+						onClick={onReportBug}
+					/>
+					<Button
+						variant="ghost"
+						size="sm"
+						icon={<Settings className="size-4" />}
+						title="Settings"
+						aria-label="Settings"
+						onClick={onOpenSettings}
+					/>
+					{account}
+				</>
+			}
+		/>
+	);
+}

package/src/index.ts

@@ -29,6 +29,7 @@ export {
 	categoryTone,
 	type Density,
 	INTELLIGENCE_MIN_WIDTH,
+	isBriefCategory,
 	type MessageListSelection,
 	type NarrowView,
 	type NavAccount,
@@ -87,9 +88,14 @@ export {
 	SECTION_ROW_CAP,
 } from "./components/brief-section.js";
 export {
+	type BriefCategoryControl,
+	type BriefFilterControl,
 	type BriefFilterId,
+	type BriefFilterSurface,
 	BriefSections,
 	type BriefSectionsProps,
+	type BriefSourceControl,
+	isBriefFilterId,
 	matchesBriefFilters,
 } from "./components/brief-sections.js";
 export {
@@ -582,6 +588,12 @@ export {
 	SettingsShell,
 	type SettingsShellProps,
 } from "./components/settings-screen.js";
+export {
+	type ShellSearchScope,
+	ShellTopBar,
+	type ShellTopBarProps,
+	type ShellTopBarSearch,
+} from "./components/shell-top-bar.js";
 export {
 	SlidePanel,
 	type SlidePanelProps,