@remit/ui 0.0.78 → 0.0.79

package/package.json

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

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/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

@@ -582,6 +582,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,