@remit/ui 0.0.74 → 0.0.76

package/package.json

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

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

@@ -6,6 +6,7 @@ import {
 	useRef,
 	useState,
 } from "react";
+import type { SelectionModifiers } from "../lib/use-selection.js";
 import type {
 	IntelligenceData,
 	SenderTrustLevel,
@@ -58,9 +59,30 @@ export function resolvePaneLayout(
 
 export type NarrowView = "list" | "message";
 
-/** Seeds the narrow touch list's interaction state for stories / SSR, so it can
- *  render selection mode or a swipe-peeked row without a live gesture. */
-export type TouchSeed = "selection" | "peek-trailing" | "peek-leading";
+/** Seeds the narrow touch list with a swipe-peeked row for stories / SSR, so it
+ *  can render that state without a live gesture. */
+export type TouchSeed = "peek-trailing" | "peek-leading";
+
+/**
+ * The list's selection, owned by whoever renders the list. The kit holds none
+ * of it: a surface that offers multi-select already has the selected set, the
+ * range anchor and the verbs the bar runs, and one set of rows can only ever
+ * answer to one of them.
+ *
+ * `useSelection` is the model both the app and the kit's own stories drive this
+ * from.
+ */
+export interface MessageListSelection {
+	/** The ticked rows. */
+	selectedIds: ReadonlySet<string>;
+	/** Ticks or unticks one row — its checkbox, and a long press on touch. */
+	onToggle: (id: string) => void;
+	/**
+	 * A row click and the modifiers it carried. True when selection took the
+	 * click, in which case the row does not open.
+	 */
+	onRowSelect?: (id: string, modifiers: SelectionModifiers) => boolean;
+}
 
 /**
  * Measures an element's OWN width via ResizeObserver — a container query, not a
@@ -317,19 +339,21 @@ export interface AppShellProps {
 	 */
 	initialNarrowView?: NarrowView;
 	/**
-	 * Seed the narrow touch list directly in selection mode or with a
-	 * swipe-peeked row, so a story / SSR can show those triage states statically.
-	 * Only meaningful below the reading boundary; ignored once the reading pane
-	 * fits or when the message view is showing.
+	 * Seed the narrow touch list with a swipe-peeked row, so a story / SSR can
+	 * show that triage state statically. Only meaningful below the reading
+	 * boundary; ignored once the reading pane fits or when the message view is
+	 * showing.
 	 */
 	initialTouchState?: TouchSeed;
 	/**
-	 * Replaces the narrow-width list pane header when a selection is active —
-	 * forwarded to `MessageListPane`'s `selectionBar` slot. The caller owns
-	 * selection state and toolbar actions; when omitted, `initialTouchState`
-	 * still drives the pane's own built-in touch-triage bar.
+	 * The list header, forwarded to `MessageListPane`'s `selectionBar` slot. The
+	 * caller mounts it for every state of the list: it names the view while
+	 * nothing is ticked and carries the count and the verbs from the first
+	 * ticked row.
 	 */
 	selectionBar?: ReactNode;
+	/** The list's selection, forwarded to `MessageListPane`. */
+	selection?: MessageListSelection;
 	intelligence?: IntelligenceData;
 	/** Pane 4 visible. Defaults to true when intelligence is present. */
 	intelligenceOpen?: boolean;

package/src/components/app-shell.render.test.ts

@@ -294,14 +294,19 @@ describe("AppShell touch-state seeds (story/SSR affordance)", () => {
 		);
 	});
 
-	it("selection seed shows the selection bar replacing the header", () => {
-		const html = render({ ...touchBase, initialTouchState: "selection" });
-		assert.match(
-			html,
-			/aria-label="Cancel selection"/,
-			"the selection bar is shown",
+	it("draws the consumer's selection on the touch rows", () => {
+		const html = render({
+			...touchBase,
+			selection: {
+				selectedIds: new Set(["r1", "r2"]),
+				onToggle: () => undefined,
+			},
+		});
+		assert.equal(
+			count(html, /aria-checked="true"/g),
+			2,
+			"both ticked rows show a checked box",
 		);
-		assert.match(html, /2 messages selected/, "selection wording shown");
 		// Selection mode is not a swipe — no action zones revealed.
 		assert.equal(
 			count(html, trailingAction),
@@ -344,33 +349,38 @@ describe("AppShell touch-state seeds (story/SSR affordance)", () => {
 		);
 	});
 
-	it("selectionBar overrides the built-in bar and forwards to the list pane", () => {
+	it("the selection bar is the list pane's header", () => {
 		const html = render({
 			...touchBase,
+			listTitle: "Inbox",
 			selectionBar: createElement(
 				"div",
 				{ "data-testid": "custom-bar" },
 				"Deleting 1,200 of 3,412…",
 			),
 		});
-		assert.match(html, /Deleting 1,200 of 3,412…/, "the override renders");
+		assert.match(html, /Deleting 1,200 of 3,412…/, "the bar renders");
 		assert.doesNotMatch(
 			html,
-			/aria-label="Cancel selection"/,
-			"the built-in bar is not also rendered",
+			/<h1[^>]*>Inbox<\/h1>/,
+			"the pane's own title header stands down",
 		);
 	});
 
-	it("ignores the touch seed at/above 1024 (desktop list)", () => {
+	it("leaves the always-visible checkbox to the touch tier", () => {
 		const html = render({
 			...touchBase,
 			initialWidth: 1100,
-			initialTouchState: "selection",
+			selection: {
+				selectedIds: new Set(["r1"]),
+				onToggle: () => undefined,
+			},
 		});
+		assert.match(html, /aria-label="Deselect message"/, "the row is ticked");
 		assert.doesNotMatch(
 			html,
-			/aria-label="Cancel selection"/,
-			"no selection bar on the desktop list",
+			/translateX/,
+			"desktop rows carry no swipe-triage layer",
 		);
 	});
 });

package/src/components/app-shell.tsx

@@ -70,6 +70,7 @@ export function AppShell({
 	thread,
 	initialNarrowView = "list",
 	initialTouchState,
+	selection,
 	selectionBar,
 	intelligence,
 	intelligenceOpen = true,
@@ -127,6 +128,7 @@ export function AppShell({
 			}}
 			onSelectBriefCategory={selectCategory}
 			initialTouchState={initialTouchState}
+			selection={selection}
 			selectionBar={selectionBar}
 		/>
 	);
@@ -187,6 +189,7 @@ function AppShellList({
 	onSelectThread,
 	onSelectBriefCategory,
 	initialTouchState,
+	selection,
 	selectionBar,
 }: Pick<
 	AppShellProps,
@@ -205,6 +208,7 @@ function AppShellList({
 	| "density"
 	| "onSelectThread"
 	| "initialTouchState"
+	| "selection"
 	| "selectionBar"
 > & {
 	narrowView: NarrowView;
@@ -248,6 +252,7 @@ function AppShellList({
 			onOpenNav={showNavPane ? undefined : layout?.openNav}
 			isDesktop={showReadingPane}
 			initialTouchState={initialTouchState}
+			selection={selection}
 			selectionBar={selectionBar}
 		/>
 	);

package/src/components/brief-sections.tsx

@@ -16,7 +16,7 @@ import {
 import type { BriefRowComponent } from "./message-row.js";
 
 /* Composable brief filters — each is an additive predicate over a thread row. */
-type BriefFilterId = "unread" | "attachment" | "contacts" | "today";
+export type BriefFilterId = "unread" | "attachment" | "contacts" | "today";
 
 /* "Today" prefers the real `sentDate` timestamp; it falls back to the fixture
    convention that same-day rows render a HH:MM timeLabel (fixtures carry no
@@ -56,7 +56,40 @@ export const briefFilterChips: FilterSheetFilter[] = briefFilterDefs.map(
 	({ id, label }) => ({ id, label }),
 );
 
-export interface BriefSectionsProps {
+/**
+ * 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
+ * surface — the phone search takeover — reads one definition of what "Unread" or
+ * "Today" means.
+ */
+export function matchesBriefFilters(
+	thread: ThreadRowData,
+	activeFilters: ReadonlySet<BriefFilterId>,
+): boolean {
+	return briefFilterDefs.every(
+		(f) => !activeFilters.has(f.id) || f.match(thread),
+	);
+}
+
+/**
+ * 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.
+ */
+type BriefFilterControl =
+	| {
+			activeFilters: ReadonlySet<BriefFilterId>;
+			onToggleFilter: (id: BriefFilterId) => void;
+			onClearFilters: () => void;
+	  }
+	| {
+			activeFilters?: never;
+			onToggleFilter?: never;
+			onClearFilters?: never;
+	  };
+
+interface BriefSectionsBaseProps {
 	sections: ThreadSection[];
 	briefCategory?: BriefCategoryFilter;
 	selectedThreadId?: string;
@@ -73,10 +106,17 @@ export interface BriefSectionsProps {
 	sourcesNote?: string;
 	/** Called when the user selects a source/account pill. */
 	onSelectSource?: (id: string) => void;
+	/**
+	 * Drop the filter row and its panel, keeping the rows where they are. See
+	 * `FilterSheetProps`.
+	 */
+	hideChrome?: boolean;
 	/** Seeds the filter panel open on first render (stories / deep links). */
 	defaultExpanded?: boolean;
 }
 
+export type BriefSectionsProps = BriefSectionsBaseProps & BriefFilterControl;
+
 /**
  * The daily-brief list body: category pills (single-select) + attribute chips
  * (additive) + one capped section per category (see {@link BriefSection}). Owns
@@ -95,9 +135,15 @@ export function BriefSections({
 	sources,
 	sourcesNote,
 	onSelectSource,
+	activeFilters,
+	onToggleFilter,
+	onClearFilters,
+	hideChrome,
 	defaultExpanded = false,
 }: BriefSectionsProps) {
-	const [active, setActive] = useState<ReadonlySet<BriefFilterId>>(new Set());
+	const [ownFilters, setOwnFilters] = useState<ReadonlySet<BriefFilterId>>(
+		new Set(),
+	);
 	const [sheetExpanded, setSheetExpanded] = useState(defaultExpanded);
 	const listRef = useRef<HTMLDivElement>(null);
 	useRovingFocus({
@@ -105,8 +151,14 @@ export function BriefSections({
 		itemSelector: LIST_ROW_SELECTOR,
 	});
 
+	const active = activeFilters ?? ownFilters;
+
 	const toggleFilter = (id: BriefFilterId) => {
-		setActive((prev) => {
+		if (onToggleFilter) {
+			onToggleFilter(id);
+			return;
+		}
+		setOwnFilters((prev) => {
 			const next = new Set(prev);
 			if (next.has(id)) next.delete(id);
 			else next.add(id);
@@ -114,10 +166,9 @@ export function BriefSections({
 		});
 	};
 
-	const predicates = briefFilterDefs.filter((f) => active.has(f.id));
 	const matches = (t: ThreadRowData) =>
 		(briefCategory === "all" || t.category === briefCategory) &&
-		predicates.every((f) => f.match(t));
+		matchesBriefFilters(t, active);
 
 	// One section per category only earns its keep at the "all" scope. Narrow to
 	// a single category and the headers are redundant: render a plain flat list.
@@ -142,7 +193,11 @@ export function BriefSections({
 
 	const clearFilters = () => {
 		onSelectBriefCategory?.("all");
-		setActive(new Set());
+		if (onClearFilters) {
+			onClearFilters();
+			return;
+		}
+		setOwnFilters(new Set());
 	};
 
 	const empty = showSections ? filtered.length === 0 : flatRows.length === 0;
@@ -200,6 +255,7 @@ export function BriefSections({
 			onSelectSource={onSelectSource}
 			onToggleFilter={(id) => toggleFilter(id as BriefFilterId)}
 			onClear={clearFilters}
+			hideChrome={hideChrome}
 		>
 			{listBody}
 		</FilterSheet>

package/src/components/filter-sheet.render.test.ts

@@ -85,7 +85,7 @@ describe("FilterSheet under a FilterPanelProvider", () => {
 		renderToString(
 			createElement(
 				FilterPanelProvider,
-				null,
+				{ hasSheet: true },
 				createElement(FilterToggle),
 				createElement(FilterSheet, {
 					categories,
@@ -120,4 +120,15 @@ describe("FilterSheet under a FilterPanelProvider", () => {
 	it("renders nothing for a toggle with no panel above it", () => {
 		assert.equal(renderToString(createElement(FilterToggle)), "");
 	});
+
+	it("renders nothing while the provider reports no sheet", () => {
+		const html = renderToString(
+			createElement(
+				FilterPanelProvider,
+				{ hasSheet: false },
+				createElement(FilterToggle),
+			),
+		);
+		assert.equal(html, "");
+	});
 });

package/src/components/filter-sheet.tsx

@@ -121,6 +121,8 @@ interface FilterPanelState {
 	/** Whether the sheet under this provider is narrowing the list right now. */
 	active: boolean;
 	setActive: (active: boolean) => void;
+	/** Whether a sheet is mounted for the caret to open. */
+	hasSheet: boolean;
 }
 
 const FilterPanelCtx = createContext<FilterPanelState | null>(null);
@@ -130,29 +132,54 @@ const FilterPanelCtx = createContext<FilterPanelState | null>(null);
  * under it, which are siblings in the tree. Wrap both: the header renders a
  * `FilterToggle`, the sheet drops its own trigger row, and the sheet keeps its
  * filter state exactly where it already lives.
+ *
+ * `hasSheet` states whether a sheet is mounted right now, and the caret stands
+ * down for as long as there is no panel behind it. It is required: a view whose
+ * 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.
  */
-export function FilterPanelProvider({ children }: { children: ReactNode }) {
+export function FilterPanelProvider({
+	children,
+	hasSheet,
+}: {
+	children?: ReactNode;
+	hasSheet: boolean;
+}) {
 	const [open, setOpen] = useState(false);
 	const [active, setActive] = useState(false);
 	const value = useMemo(
-		() => ({ open, setOpen, active, setActive }),
-		[open, active],
+		() => ({ open, setOpen, active, setActive, hasSheet }),
+		[open, active, hasSheet],
 	);
 	return (
 		<FilterPanelCtx.Provider value={value}>{children}</FilterPanelCtx.Provider>
 	);
 }
 
+/**
+ * Detaches whatever it wraps from an enclosing `FilterPanelProvider`. A
+ * full-screen surface that covers the list — the phone search takeover — carries
+ * its own filter chrome, and the caret it would otherwise borrow belongs to a
+ * header that is not on screen.
+ */
+export function FilterPanelBoundary({ children }: { children: ReactNode }) {
+	return (
+		<FilterPanelCtx.Provider value={null}>{children}</FilterPanelCtx.Provider>
+	);
+}
+
 /**
  * The filter caret, for a list header to render beside its unread count. It is
  * the view's whole filter affordance; the panel it opens still belongs to the
  * sheet, inline above the rows.
  *
- * Renders nothing outside a `FilterPanelProvider` — there is no panel to open.
+ * Renders nothing outside a `FilterPanelProvider`, and nothing while that
+ * provider reports no sheet — there is no panel to open.
  */
 export function FilterToggle() {
 	const panel = useContext(FilterPanelCtx);
-	if (!panel) return null;
+	if (!panel?.hasSheet) return null;
 	const { open, active, setOpen } = panel;
 	return (
 		<button
@@ -225,7 +252,9 @@ export function FilterSheet({
 
 	const setPanelActive = panel?.setActive;
 	useEffect(() => {
-		setPanelActive?.(hasActive);
+		if (!setPanelActive) return;
+		setPanelActive(hasActive);
+		return () => setPanelActive(false);
 	}, [hasActive, setPanelActive]);
 
 	const clearSource = useCallback(() => {

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

@@ -152,6 +152,28 @@ describe("MessageListPane", () => {
 		assert.doesNotMatch(html, /Every message in this folder was checked\./);
 	});
 
+	it("ticks the rows the consumer says are selected, and nothing else", () => {
+		const html = renderToString(
+			createElement(MessageListPane, {
+				...baseProps,
+				isDesktop: true,
+				selection: {
+					selectedIds: new Set(["t1"]),
+					onToggle: () => undefined,
+				},
+			}),
+		);
+		assert.match(html, /aria-label="Deselect message"/);
+		assert.match(html, /aria-label="Select message"/);
+	});
+
+	it("offers no checkbox at all when the consumer holds no selection", () => {
+		const html = renderToString(
+			createElement(MessageListPane, { ...baseProps, isDesktop: true }),
+		);
+		assert.doesNotMatch(html, /aria-label="Select message"/);
+	});
+
 	it("renders the selectionBar slot instead of the pane header when provided", () => {
 		const html = renderToString(
 			createElement(MessageListPane, {

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

@@ -1,6 +1,11 @@
 import type { Decorator, Meta, StoryObj } from "@storybook/react";
 import { useState } from "react";
 import { inboxFilterConfig } from "../filter-presets.js";
+import {
+	rowSelectIntent,
+	type SelectionModifiers,
+	useSelection,
+} from "../lib/use-selection.js";
 import type { ThreadSection } from "./app-shell-types.js";
 import { FilterSheet } from "./filter-sheet.js";
 import { MailHeader } from "./mail-header.js";
@@ -212,60 +217,109 @@ export const CustomListBody: Story = {
 	decorators: [desktopFrame],
 };
 
+function SelectableList({ isDesktop }: { isDesktop: boolean }) {
+	const selection = useSelection();
+	const [trashedIds, setTrashedIds] = useState<ReadonlySet<string>>(new Set());
+	const [readIds, setReadIds] = useState<ReadonlySet<string>>(new Set());
+
+	const visible = sections.map((section) => ({
+		...section,
+		threads: section.threads
+			.filter((thread) => !trashedIds.has(thread.id))
+			.map((thread) =>
+				readIds.has(thread.id) ? { ...thread, isRead: true } : thread,
+			),
+	}));
+	const orderedIds = visible.flatMap((s) => s.threads).map((t) => t.id);
+	const allSelected =
+		orderedIds.length > 0 &&
+		orderedIds.every((id) => selection.selectedIds.has(id));
+
+	const runVerb = (record: (ids: ReadonlySet<string>) => void) => {
+		record(selection.selectedIds);
+		selection.clearSelection();
+	};
+
+	// Shift and cmd/ctrl come off a mouse, which the touch list has no path for.
+	const onRowSelect = isDesktop
+		? (id: string, modifiers: SelectionModifiers) => {
+				const intent = rowSelectIntent(modifiers);
+				if (intent === "range") {
+					selection.selectRange(orderedIds, id);
+					return true;
+				}
+				if (intent === "toggle") {
+					selection.toggle(id);
+					return true;
+				}
+				selection.clearSelection();
+				selection.setAnchor(id);
+				return false;
+			}
+		: undefined;
+
+	return (
+		<MessageListPane
+			listTitle="Inbox"
+			listMeta="3 conversations"
+			sections={visible}
+			flatList
+			isDesktop={isDesktop}
+			onSelectThread={() => undefined}
+			selection={{
+				selectedIds: selection.selectedIds,
+				onToggle: selection.toggle,
+				onRowSelect,
+			}}
+			selectionBar={
+				<SelectionTopBar
+					title="Inbox"
+					count={selection.selectedCount}
+					onCancel={selection.clearSelection}
+					onDelete={() =>
+						runVerb((ids) =>
+							setTrashedIds((prev) => new Set([...prev, ...ids])),
+						)
+					}
+					onMarkRead={() =>
+						runVerb((ids) => setReadIds((prev) => new Set([...prev, ...ids])))
+					}
+					selectAll={{
+						checked: allSelected,
+						indeterminate: selection.hasSelection && !allSelected,
+						onChange: () => selection.toggleAll(orderedIds),
+					}}
+				/>
+			}
+		/>
+	);
+}
+
 /**
- * The `selectionBar` slot at desktop width, holding the same
- * `SelectionTopBar` the narrow story below holds. One surface at every
- * width: from 768px up the labelled select-all sits inline in the bar.
+ * The pane under a selection its consumer owns — it draws the checkboxes and
+ * holds none of the state. Click a checkbox to tick one row, cmd/ctrl-click a
+ * row to tick it without opening it, shift-click to range from the last row
+ * touched, and select-all covers the rows on screen. From 768px up the labelled
+ * select-all sits inline in the bar.
+ *
+ * The bar is the header for every state of the list: it names the mailbox with
+ * nothing ticked and carries the count and the verbs from the first ticked row.
+ * Delete and Mark read act on the rows — trashed rows leave the list, marked
+ * ones lose their unread dot.
  */
-export const ExternalSelectionBar: Story = {
-	args: {
-		isDesktop: true,
-		flatList: true,
-		selectionBar: (
-			<SelectionTopBar
-				title="Inbox"
-				count={2}
-				onCancel={() => undefined}
-				onMarkRead={() => undefined}
-				onJunk={() => undefined}
-				onOrganize={() => undefined}
-				onDelete={() => undefined}
-				selectAll={{
-					checked: false,
-					indeterminate: true,
-					onChange: () => undefined,
-				}}
-			/>
-		),
-	},
+export const ConsumerSelection: Story = {
+	render: () => <SelectableList isDesktop />,
 	decorators: [desktopFrame],
 };
 
 /**
- * The same bar at phone width: select-all moves to a second row so row one
- * stays a count and the verbs, with a back arrow out of selection.
+ * The same list at phone width, where selection is a long press and a tap on
+ * the checkbox: no modifier comes off a touch, so there is no range and no
+ * cmd-toggle here. Checkboxes stay put once a row is ticked, and select-all
+ * moves to a second row so row one stays a count and the verbs.
  */
-export const NarrowExternalSelectionBar: Story = {
-	args: {
-		isDesktop: false,
-		flatList: true,
-		selectionBar: (
-			<SelectionTopBar
-				title="Inbox"
-				count={2}
-				onCancel={() => undefined}
-				onMarkRead={() => undefined}
-				onJunk={() => undefined}
-				onOrganize={() => undefined}
-				onDelete={() => undefined}
-				selectAll={{
-					checked: false,
-					indeterminate: true,
-					onChange: () => undefined,
-				}}
-			/>
-		),
-	},
+export const NarrowConsumerSelection: Story = {
+	render: () => <SelectableList isDesktop={false} />,
 	decorators: [narrowFrame],
 };