@remit/ui 0.0.75 → 0.0.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.75",
+  "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/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

@@ -133,16 +133,18 @@ const FilterPanelCtx = createContext<FilterPanelState | null>(null);
  * `FilterToggle`, the sheet drops its own trigger row, and the sheet keeps its
  * filter state exactly where it already lives.
  *
- * A view whose body is sometimes something other than the filtered list — a
- * skeleton, an empty state, an error — says so with `hasSheet`, and the caret
- * stands down for as long as there is no panel behind it.
+ * `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,
-	hasSheet = true,
+	hasSheet,
 }: {
-	children: ReactNode;
-	hasSheet?: boolean;
+	children?: ReactNode;
+	hasSheet: boolean;
 }) {
 	const [open, setOpen] = useState(false);
 	const [active, setActive] = useState(false);

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],
 };