@remit/ui 0.0.37 → 0.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.37",
+  "version": "0.0.39",
   "type": "module",
   "files": [
     "src"
@@ -12,7 +12,7 @@
   "scripts": {
     "test": "npm run test:typecheck && npm run test:run",
     "test:typecheck": "tsgo --noEmit",
-    "test:run": "node --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=75 --test 'src/**/*.test.ts'"
+    "test:run": "node --import tsx --experimental-test-coverage --test-coverage-include='src/**' --test-coverage-exclude='src/**/*.test.ts' --test-coverage-exclude='src/**/*.test.tsx' --test-coverage-lines=90 --test 'src/**/*.test.ts'"
   },
   "dependencies": {
     "@fontsource-variable/geist": "^5",

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

@@ -40,6 +40,7 @@ export function MessageListPane({
 	isDesktop,
 	initialTouchState,
 	selectionBar,
+	selectionSheet,
 	listBody,
 	hideHeader = false,
 }: Pick<
@@ -72,6 +73,13 @@ export function MessageListPane({
 	 * When omitted the pane's built-in touch-triage selection bar is used.
 	 */
 	selectionBar?: ReactNode;
+	/**
+	 * The mobile multi-select surface: a peeking bottom sheet overlaid on the
+	 * list, distinct from `selectionBar` (which replaces the header at the top).
+	 * Rendered as the last child so it sits above the rows; the caller pads the
+	 * list's own bottom so no row hides behind the teaser.
+	 */
+	selectionSheet?: ReactNode;
 	/**
 	 * Overrides the row-rendering section of the non-brief list — the whole
 	 * scrollable body including virtualization, swipe-triage and any load-more
@@ -142,7 +150,7 @@ export function MessageListPane({
 		!selectionBar && touchTriage && selectionMode && checkedIds.size > 0;
 
 	return (
-		<section className="flex h-full w-full flex-col bg-surface">
+		<section className="relative flex h-full w-full flex-col bg-surface">
 			{selectionBar ??
 				(inBuiltinSelection ? (
 					<SelectionTopBar
@@ -249,6 +257,7 @@ export function MessageListPane({
 			)}
 
 			{isDesktop && <KeyboardHintBar />}
+			{selectionSheet}
 		</section>
 	);
 }

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

@@ -0,0 +1,139 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToString } from "react-dom/server";
+import { SelectionSheet, type SelectionSheetProps } from "./selection-sheet.js";
+
+const noop = () => {};
+
+const base: SelectionSheetProps = {
+	count: 3,
+	onCancel: noop,
+	onDelete: noop,
+};
+
+describe("SelectionSheet", () => {
+	it("teases collapsed with the count and the swipe hint", () => {
+		const html = renderToString(createElement(SelectionSheet, base));
+		assert.match(html, /3 messages selected/);
+		assert.match(html, /Swipe up for actions/);
+		assert.match(html, /role="slider"/);
+		// Collapsed: no cancel/mark-read in the header yet.
+		assert.doesNotMatch(html, /aria-label="Cancel selection"/);
+		// The clipped body is inert while collapsed, so its offscreen verbs stay
+		// out of the tab order and the a11y tree.
+		assert.match(html, /inert=""/);
+	});
+
+	it("expanded shows the quick actions, cancel, and the smart-flow rows", () => {
+		const html = renderToString(
+			createElement(SelectionSheet, {
+				...base,
+				startExpanded: true,
+				onMarkRead: noop,
+				onJunk: noop,
+				onSelectSimilar: noop,
+				onSomethingElse: noop,
+				moveSlot: createElement("span", null, "move-here"),
+			}),
+		);
+		assert.match(html, /aria-label="Move selected messages to Trash"/);
+		assert.match(html, /aria-label="Move selected messages to Junk"/);
+		assert.match(html, /aria-label="Mark as read"/);
+		assert.match(html, /aria-label="Cancel selection"/);
+		assert.match(html, /move-here/);
+		assert.match(html, /Select similar messages/);
+		assert.match(html, /Something else/);
+		// Expanded: the body is live, not inert.
+		assert.doesNotMatch(html, /inert=""/);
+	});
+
+	it("names the loaded scope and renders the select-all control", () => {
+		const html = renderToString(
+			createElement(SelectionSheet, {
+				...base,
+				count: 47,
+				startExpanded: true,
+				selectAll: { checked: true, indeterminate: false, onChange: noop },
+			}),
+		);
+		assert.match(html, /All 47 loaded selected/);
+		assert.match(html, /aria-label="Select all"/);
+	});
+
+	it("counting replaces the quick actions with the status and a Stop", () => {
+		const html = renderToString(
+			createElement(SelectionSheet, {
+				...base,
+				count: 0,
+				mode: "counting",
+				statusLabel: "Counting… 1,900 so far",
+				notice: {
+					tone: "info",
+					text: "",
+					action: { label: "Stop", onClick: noop },
+				},
+			}),
+		);
+		assert.match(html, /Counting… 1,900 so far/);
+		assert.match(html, /Stop/);
+		// No quick actions while counting.
+		assert.doesNotMatch(html, /aria-label="Move selected messages to Trash"/);
+	});
+
+	it("running shows a progress bar and no quick actions", () => {
+		const html = renderToString(
+			createElement(SelectionSheet, {
+				...base,
+				count: 3412,
+				mode: "running",
+				isBusy: true,
+				statusLabel: "Deleting 1,200 of 3,412…",
+				progress: { value: 1200, max: 3412 },
+			}),
+		);
+		assert.match(html, /Deleting 1,200 of 3,412…/);
+		assert.match(html, /role="progressbar"/);
+		assert.doesNotMatch(html, /Select similar messages/);
+	});
+
+	it("escalated keeps the verbs and a clear-selection notice", () => {
+		const html = renderToString(
+			createElement(SelectionSheet, {
+				...base,
+				count: 3412,
+				mode: "escalated",
+				startExpanded: true,
+				statusLabel: 'All 3,412 matching "npm" selected',
+				moveSlot: createElement("span", null, "move-here"),
+				notice: {
+					tone: "info",
+					text: "",
+					action: { label: "Clear selection", onClick: noop },
+				},
+			}),
+		);
+		assert.match(html, /All 3,412 matching/);
+		assert.match(html, /aria-label="Move selected messages to Trash"/);
+		assert.match(html, /Clear selection/);
+		// Not a bounded selection, so no select-similar entry.
+		assert.doesNotMatch(html, /Select similar messages/);
+	});
+
+	it("renders a partial-failure notice with a Retry action", () => {
+		const html = renderToString(
+			createElement(SelectionSheet, {
+				...base,
+				count: 340,
+				startExpanded: true,
+				notice: {
+					tone: "danger",
+					text: "3,072 moved to Trash. 340 couldn't be deleted.",
+					action: { label: "Retry 340", onClick: noop },
+				},
+			}),
+		);
+		assert.match(html, /3,072 moved to Trash/);
+		assert.match(html, /Retry 340/);
+	});
+});

package/src/components/selection-sheet.stories.tsx

@@ -0,0 +1,158 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { FolderInput } from "lucide-react";
+import { SelectionSheet } from "./selection-sheet.js";
+
+const meta: Meta<typeof SelectionSheet> = {
+	title: "Screens/Kit/SelectionSheet",
+	component: SelectionSheet,
+	parameters: { layout: "fullscreen" },
+	args: {
+		count: 3,
+		onCancel: () => undefined,
+		onDelete: () => undefined,
+		onMarkRead: () => undefined,
+		onJunk: () => undefined,
+		onSelectSimilar: () => undefined,
+		onSomethingElse: () => undefined,
+	},
+	decorators: [
+		(Story) => (
+			<div className="relative mx-auto h-dvh w-full shrink-0 overflow-hidden bg-surface sm:my-6 sm:h-[720px] sm:w-[390px] sm:rounded-[2rem] sm:border sm:border-line sm:shadow-sm">
+				{/* Inbox backdrop, so the peeking sheet reads against a list. */}
+				<div className="divide-y divide-line opacity-50">
+					{Array.from({ length: 11 }).map((_, i) => (
+						<div
+							// biome-ignore lint/suspicious/noArrayIndexKey: static skeleton rows
+							key={i}
+							className="flex items-start gap-3 px-row-inset py-2.5"
+						>
+							<div className="mt-0.5 size-7 shrink-0 rounded-full bg-surface-sunken" />
+							<div className="min-w-0 flex-1 space-y-1">
+								<div className="h-2.5 w-1/3 rounded bg-surface-sunken" />
+								<div className="h-2 w-2/3 rounded bg-surface-sunken" />
+							</div>
+						</div>
+					))}
+				</div>
+				<Story />
+			</div>
+		),
+	],
+};
+export default meta;
+
+type Story = StoryObj<typeof SelectionSheet>;
+
+/** Stand-in for the caller's move-to-folder trigger (an icon button that opens
+ *  a folder picker). The sheet only reserves the slot. */
+const MoveSlot = () => (
+	<button
+		type="button"
+		aria-label="Move selected messages"
+		className="inline-flex size-11 shrink-0 items-center justify-center rounded text-fg-muted hover:bg-surface-raised"
+	>
+		<FolderInput className="size-4" />
+	</button>
+);
+
+/** Collapsed — the slim ~56px teaser that rises at 2+ selected. */
+export const Teaser: Story = {
+	args: { moveSlot: <MoveSlot /> },
+};
+
+/** Expanded — quick actions (Delete / Move / Junk) plus the select-similar and
+ *  "Something else" entries. */
+export const Expanded: Story = {
+	args: { startExpanded: true, moveSlot: <MoveSlot /> },
+};
+
+/** While a search result set pages to its total: the count isn't known, the
+ *  quick actions are replaced by the running total and an explicit Stop. */
+export const Counting: Story = {
+	args: {
+		count: 0,
+		mode: "counting",
+		startExpanded: true,
+		statusLabel: "Counting… 1,900 so far",
+		selectAll: {
+			checked: true,
+			indeterminate: false,
+			onChange: () => undefined,
+		},
+		notice: {
+			tone: "info",
+			text: "",
+			action: { label: "Stop", onClick: () => undefined },
+		},
+	},
+};
+
+/** A bulk delete in progress — a running total and a determinate progress bar,
+ *  the delete busy, no quick actions to act mid-run. */
+export const RunningProgress: Story = {
+	args: {
+		count: 3412,
+		mode: "running",
+		startExpanded: true,
+		isBusy: true,
+		statusLabel: "Deleting 1,200 of 3,412…",
+		progress: { value: 1200, max: 3412 },
+	},
+};
+
+/**
+ * Every loaded row checked and the search has more matches: the sheet offers to
+ * escalate the selection to the whole result set.
+ */
+export const EscalationAvailable: Story = {
+	args: {
+		count: 47,
+		startExpanded: true,
+		moveSlot: <MoveSlot />,
+		selectAll: {
+			checked: true,
+			indeterminate: false,
+			onChange: () => undefined,
+		},
+		notice: {
+			tone: "info",
+			text: "",
+			action: {
+				label: 'Select all matching "npm"',
+				onClick: () => undefined,
+			},
+		},
+	},
+};
+
+/** Selection escalated to the search predicate: the count names the query's
+ *  total, every verb still acts, and the notice offers a way back. */
+export const Escalated: Story = {
+	args: {
+		count: 3412,
+		mode: "escalated",
+		startExpanded: true,
+		moveSlot: <MoveSlot />,
+		statusLabel: 'All 3,412 matching "npm" selected',
+		notice: {
+			tone: "info",
+			text: "",
+			action: { label: "Clear selection", onClick: () => undefined },
+		},
+	},
+};
+
+/** After a bulk delete with some batches failed: the count reflects only what
+ *  is still selected — the failures — and Retry names how many. */
+export const PartialFailure: Story = {
+	args: {
+		count: 340,
+		startExpanded: true,
+		moveSlot: <MoveSlot />,
+		notice: {
+			tone: "danger",
+			text: "3,072 moved to Trash. 340 couldn't be deleted.",
+			action: { label: "Retry 340", onClick: () => undefined },
+		},
+	},
+};

package/src/components/selection-sheet.test.ts

@@ -0,0 +1,88 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { resolveSheetSnap } from "./selection-sheet.js";
+
+const base = {
+	expandedHeight: 320,
+	teaserHeight: 56,
+	flickVelocity: 0.5,
+};
+
+describe("resolveSheetSnap", () => {
+	it("flicks up expand regardless of how far the drag travelled", () => {
+		assert.equal(
+			resolveSheetSnap({ ...base, expanded: false, delta: -4, velocity: -1.2 }),
+			true,
+		);
+	});
+
+	it("flicks down collapse regardless of how far the drag travelled", () => {
+		assert.equal(
+			resolveSheetSnap({ ...base, expanded: true, delta: 4, velocity: 1.2 }),
+			false,
+		);
+	});
+
+	it("a slow upward drag past the midpoint expands from the teaser", () => {
+		// midpoint = (320 - 56) / 2 = 132; -140 crosses it going up.
+		assert.equal(
+			resolveSheetSnap({
+				...base,
+				expanded: false,
+				delta: -140,
+				velocity: 0.1,
+			}),
+			true,
+		);
+	});
+
+	it("a slow upward drag short of the midpoint settles back to the teaser", () => {
+		assert.equal(
+			resolveSheetSnap({
+				...base,
+				expanded: false,
+				delta: -100,
+				velocity: 0.1,
+			}),
+			false,
+		);
+	});
+
+	it("a slow downward drag past the midpoint collapses from expanded", () => {
+		assert.equal(
+			resolveSheetSnap({ ...base, expanded: true, delta: 140, velocity: 0.1 }),
+			false,
+		);
+	});
+
+	it("a slow downward drag short of the midpoint stays expanded", () => {
+		assert.equal(
+			resolveSheetSnap({ ...base, expanded: true, delta: 100, velocity: 0.1 }),
+			true,
+		);
+	});
+
+	it("a barely-moved release keeps the current snap state", () => {
+		assert.equal(
+			resolveSheetSnap({ ...base, expanded: true, delta: 0, velocity: 0 }),
+			true,
+		);
+		assert.equal(
+			resolveSheetSnap({ ...base, expanded: false, delta: 0, velocity: 0 }),
+			false,
+		);
+	});
+
+	it("defaults the flick threshold when omitted", () => {
+		assert.equal(
+			resolveSheetSnap({
+				expanded: false,
+				delta: -4,
+				velocity: -1,
+				expandedHeight: 320,
+				teaserHeight: 56,
+			}),
+			true,
+		);
+	});
+});

package/src/components/selection-sheet.tsx

@@ -0,0 +1,483 @@
+import {
+	ChevronUp,
+	Loader2,
+	MailOpen,
+	ShieldAlert,
+	Trash2,
+	X,
+} from "lucide-react";
+import type { ReactNode } from "react";
+import {
+	useCallback,
+	useEffect,
+	useLayoutEffect,
+	useRef,
+	useState,
+} from "react";
+import { cn } from "../lib/cn.js";
+import { Banner, type BannerTone } from "./banner.js";
+import { Button } from "./button.js";
+import { Checkbox } from "./checkbox.js";
+import { ProgressBar } from "./progress-bar.js";
+
+const formatCount = (n: number): string => n.toLocaleString();
+
+/** The peek height of the collapsed teaser row (px). */
+export const SELECTION_SHEET_TEASER_HEIGHT = 56;
+/** Ceiling on the expanded sheet height (px); CSS clamps to a third of the
+ *  viewport below this. */
+const EXPANDED_MAX = 320;
+
+const SNAP_MS = 320;
+const SNAP_EASE = "cubic-bezier(0.32, 0.9, 0.3, 1)";
+const FLICK_VELOCITY = 0.5; // px/ms
+
+function rubberBand(overshoot: number): number {
+	return Math.sign(overshoot) * Math.sqrt(Math.abs(overshoot)) * 4;
+}
+
+export interface SheetSnapInput {
+	/** The snap state the drag started from. */
+	expanded: boolean;
+	/** Net vertical travel over the drag (px); positive is downward. */
+	delta: number;
+	/** Terminal pointer velocity (px/ms); positive is downward. */
+	velocity: number;
+	/** Measured full height of the expanded sheet (px). */
+	expandedHeight: number;
+	/** Peek height of the collapsed teaser (px). */
+	teaserHeight: number;
+	/** Speed past which a drag is a flick, snapping in its direction. */
+	flickVelocity?: number;
+}
+
+/**
+ * The two-snap decision the sheet makes when a drag ends: a flick snaps in its
+ * own direction; otherwise the sheet settles to whichever snap point the drag
+ * crossed the midpoint toward. Pure so the snap behaviour is testable without a
+ * pointer or a DOM.
+ */
+export function resolveSheetSnap({
+	expanded,
+	delta,
+	velocity,
+	expandedHeight,
+	teaserHeight,
+	flickVelocity = FLICK_VELOCITY,
+}: SheetSnapInput): boolean {
+	if (Math.abs(velocity) > flickVelocity) return velocity < 0;
+	const midpoint = (expandedHeight - teaserHeight) / 2;
+	return expanded ? delta < midpoint : delta < -midpoint;
+}
+
+export type SelectionSheetMode = "idle" | "counting" | "running" | "escalated";
+
+export interface SelectionSheetNoticeAction {
+	label: string;
+	onClick: () => void;
+}
+
+export interface SelectionSheetNotice {
+	tone: BannerTone;
+	text: string;
+	action?: SelectionSheetNoticeAction;
+}
+
+export interface SelectionSheetProps {
+	count: number;
+	/**
+	 * Which content the sheet routes to. `idle` shows the quick actions and the
+	 * smart-flow rows; `counting`/`running` replace them with the paging status,
+	 * progress and notice; `escalated` keeps the quick actions over the whole
+	 * predicate. Defaults to `idle`.
+	 */
+	mode?: SelectionSheetMode;
+	/** The X / stop control — exits selection, or stops a run in progress. */
+	onCancel: () => void;
+	onDelete: () => void;
+	/** Move to the Junk mailbox. Omitted (hidden) in the Junk folder itself, or
+	 *  when no Junk folder is appointed. */
+	onJunk?: () => void;
+	/** Optional — hidden while a run is in flight or the total is still counting. */
+	onMarkRead?: () => void;
+	/** Widen the selection to similar mail, then open Organize. */
+	onSelectSimilar?: () => void;
+	/** Open Organize with the current selection to choose an action. */
+	onSomethingElse?: () => void;
+	/**
+	 * Move-to-folder trigger, rendered as the middle quick action. Kept as a
+	 * render prop so the caller owns the folder-picker data and API deps.
+	 */
+	moveSlot?: ReactNode;
+	/** True while a delete or move mutation is in flight. */
+	isBusy?: boolean;
+	/** Select-all-loaded control, rendered above the quick actions when present. */
+	selectAll?: {
+		checked: boolean;
+		indeterminate?: boolean;
+		onChange: () => void;
+	};
+	/** Overrides the default "{count} messages selected" status text. */
+	statusLabel?: string;
+	/** Determinate progress for a bulk run in flight. */
+	progress?: { value: number; max: number; tone?: BannerTone };
+	/** At-most-one toned status line: an escalation offer, a Stop, a Retry, or a
+	 *  cross-account move restriction. */
+	notice?: SelectionSheetNotice;
+	/** Start expanded rather than at the teaser — for stories and the counting /
+	 *  running states, which need their status visible. */
+	startExpanded?: boolean;
+}
+
+/**
+ * The mobile multi-select surface: a peeking bottom sheet that teases at ~56px
+ * with the selection count, and expands by drag or tap to a third-height sheet
+ * carrying the bulk verbs (Delete / Move / Junk), the select-similar → organize
+ * entries, and every escalation state (counting, running progress,
+ * partial-failure) the selection can be in. Drag or tap the grabber to collapse
+ * back to the teaser; the selection is untouched.
+ *
+ * Sits absolutely against the bottom of the nearest positioned ancestor, so the
+ * list it belongs to must be a `relative` container and pad its own bottom by
+ * {@link SELECTION_SHEET_TEASER_HEIGHT} so no row hides behind the teaser.
+ */
+export function SelectionSheet({
+	count,
+	mode = "idle",
+	onCancel,
+	onDelete,
+	onJunk,
+	onMarkRead,
+	onSelectSimilar,
+	onSomethingElse,
+	moveSlot,
+	isBusy = false,
+	selectAll,
+	statusLabel,
+	progress,
+	notice,
+	startExpanded = false,
+}: SelectionSheetProps) {
+	const [expanded, setExpanded] = useState(startExpanded);
+	const containerRef = useRef<HTMLDivElement>(null);
+	const [expandedHeight, setExpandedHeight] = useState(EXPANDED_MAX);
+
+	// A run or a live count owns the sheet: it stays open so the progress and
+	// status can't be dragged out of sight mid-operation.
+	const locked = mode === "counting" || mode === "running";
+	useEffect(() => {
+		if (locked) setExpanded(true);
+	}, [locked]);
+
+	useLayoutEffect(() => {
+		const el = containerRef.current;
+		if (!el) return;
+		const measure = () => setExpandedHeight(el.offsetHeight);
+		measure();
+		const ro = new ResizeObserver(measure);
+		ro.observe(el);
+		return () => ro.disconnect();
+	}, []);
+
+	// Offset from the current snap position (positive = dragged down).
+	const [dragOffset, setDragOffset] = useState<number | null>(null);
+	const pointer = useRef<{
+		startY: number;
+		lastY: number;
+		lastT: number;
+		velocity: number;
+	} | null>(null);
+	// True once a pointer-down has actually moved, so the click the browser fires
+	// on pointer-up after a drag doesn't also toggle the snap state and undo it.
+	const movedRef = useRef(false);
+
+	const onPointerDown = useCallback(
+		(e: React.PointerEvent) => {
+			if (locked) return;
+			(e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+			pointer.current = {
+				startY: e.clientY,
+				lastY: e.clientY,
+				lastT: e.timeStamp,
+				velocity: 0,
+			};
+			movedRef.current = false;
+			setDragOffset(0);
+		},
+		[locked],
+	);
+
+	const onPointerMove = useCallback(
+		(e: React.PointerEvent) => {
+			const p = pointer.current;
+			if (!p) return;
+			const dt = e.timeStamp - p.lastT;
+			if (dt > 0) p.velocity = (e.clientY - p.lastY) / dt;
+			p.lastY = e.clientY;
+			p.lastT = e.timeStamp;
+			const delta = e.clientY - p.startY;
+			if (Math.abs(delta) > 4) movedRef.current = true;
+			const range = expandedHeight - SELECTION_SHEET_TEASER_HEIGHT;
+			const clamped = expanded
+				? delta < 0
+					? rubberBand(delta)
+					: Math.min(delta, range + rubberBand(Math.max(0, delta - range)))
+				: delta > 0
+					? rubberBand(delta)
+					: Math.max(delta, -range + rubberBand(Math.min(0, delta + range)));
+			setDragOffset(clamped);
+		},
+		[expanded, expandedHeight],
+	);
+
+	const finishDrag = useCallback(() => {
+		const p = pointer.current;
+		pointer.current = null;
+		if (!p) return;
+		setDragOffset(null);
+		setExpanded(
+			resolveSheetSnap({
+				expanded,
+				delta: p.lastY - p.startY,
+				velocity: p.velocity,
+				expandedHeight,
+				teaserHeight: SELECTION_SHEET_TEASER_HEIGHT,
+			}),
+		);
+	}, [expanded, expandedHeight]);
+
+	const collapsedTranslate = expandedHeight - SELECTION_SHEET_TEASER_HEIGHT;
+	const baseTranslate = expanded ? 0 : collapsedTranslate;
+	const dragging = dragOffset !== null;
+	const translate = baseTranslate + (dragOffset ?? 0);
+	const transition = dragging ? "none" : `transform ${SNAP_MS}ms ${SNAP_EASE}`;
+
+	const defaultLabel = selectAll?.checked
+		? `All ${formatCount(count)} loaded selected`
+		: `${formatCount(count)} ${count === 1 ? "message" : "messages"} selected`;
+
+	const showQuickActions = mode === "idle" || mode === "escalated";
+	const showSmartRows = mode === "idle";
+
+	return (
+		<div
+			ref={containerRef}
+			data-selection-sheet=""
+			className="absolute inset-x-0 bottom-0 z-30 flex select-none flex-col rounded-t-2xl border-t border-line bg-surface shadow-2xl shadow-black/40"
+			style={{
+				maxHeight: `min(${EXPANDED_MAX}px, 38dvh)`,
+				minHeight: `${SELECTION_SHEET_TEASER_HEIGHT}px`,
+				transform: `translateY(${translate}px)`,
+				transition,
+			}}
+		>
+			{/* Grabber / teaser — always visible at the peek. Tapping toggles the
+			    snap state; dragging snaps between the two heights. */}
+			{/* biome-ignore lint/a11y/useKeyWithClickEvents: keyboard users reach every action via the buttons below; the grabber is a pointer-drag affordance */}
+			<div
+				role="slider"
+				aria-label={
+					expanded ? "Collapse selection actions" : "Expand selection actions"
+				}
+				aria-valuemin={0}
+				aria-valuemax={1}
+				aria-valuenow={expanded ? 1 : 0}
+				tabIndex={0}
+				onPointerDown={onPointerDown}
+				onPointerMove={onPointerMove}
+				onPointerUp={finishDrag}
+				onPointerCancel={finishDrag}
+				onClick={() => {
+					// A drag already settled the snap in finishDrag; swallow the click
+					// the browser fires after it so it doesn't toggle straight back.
+					if (movedRef.current) {
+						movedRef.current = false;
+						return;
+					}
+					if (!dragging && !locked) setExpanded((v) => !v);
+				}}
+				className={cn(
+					"flex touch-none flex-col items-center pt-2",
+					locked ? "" : "cursor-grab active:cursor-grabbing",
+				)}
+			>
+				<div className="mb-1.5 h-1 w-10 rounded-full bg-fg-subtle/40" />
+				<div className="flex w-full items-center gap-2 px-4 pb-3">
+					<span
+						className="min-w-0 flex-1 truncate text-sm font-semibold text-fg"
+						role="status"
+						aria-live="polite"
+					>
+						{statusLabel ?? defaultLabel}
+					</span>
+					{expanded ? (
+						<>
+							{onMarkRead && !isBusy && mode !== "counting" && (
+								<Button
+									variant="ghost"
+									size="touch"
+									icon={<MailOpen className="size-4" />}
+									// These buttons sit inside the grabber's drag surface. Its
+									// pointer-down capture would otherwise swallow the button's
+									// own click (the grabber ends up the click target and just
+									// toggles the snap), so stop the pointer-down here — the tap
+									// then lands on the button and runs its action.
+									onPointerDown={(e) => e.stopPropagation()}
+									onClick={(e) => {
+										e.stopPropagation();
+										onMarkRead();
+									}}
+									aria-label="Mark as read"
+									className="-my-2 shrink-0"
+								/>
+							)}
+							<Button
+								variant="ghost"
+								size="touch"
+								icon={<X className="size-4" />}
+								onPointerDown={(e) => e.stopPropagation()}
+								onClick={(e) => {
+									e.stopPropagation();
+									onCancel();
+								}}
+								aria-label="Cancel selection"
+								className="-my-2 -mr-2 shrink-0"
+							/>
+						</>
+					) : (
+						<span className="flex shrink-0 items-center gap-1 text-xs text-fg-subtle">
+							<span>Swipe up for actions</span>
+							<ChevronUp className="size-4" />
+						</span>
+					)}
+				</div>
+			</div>
+
+			{/* Expanded content — clipped by the translate when collapsed. It stays
+			    in the DOM at the teaser, so `inert` when collapsed keeps its offscreen
+			    verbs out of the tab order and the a11y tree until the sheet opens. */}
+			<div
+				inert={!expanded ? true : undefined}
+				className="flex min-h-0 flex-1 flex-col overflow-hidden px-4 pb-4"
+			>
+				{progress && (
+					<div className="mb-3">
+						<ProgressBar
+							value={progress.value}
+							max={progress.max}
+							tone={progress.tone}
+						/>
+					</div>
+				)}
+
+				{selectAll && mode !== "running" && (
+					// biome-ignore lint/a11y/noLabelWithoutControl: the label wraps Checkbox's own input, giving the 20px control a 44px hit area
+					<label className="mb-3 flex min-h-11 cursor-pointer items-center gap-3 text-sm font-medium text-fg-muted">
+						<Checkbox
+							aria-label="Select all"
+							checked={selectAll.checked}
+							indeterminate={selectAll.indeterminate}
+							onChange={selectAll.onChange}
+						/>
+						Select all loaded
+					</label>
+				)}
+
+				{showQuickActions && (
+					<div className="mb-3 flex items-stretch justify-around gap-1 border-b border-line pb-3">
+						<Button
+							variant="ghost"
+							onClick={onDelete}
+							icon={
+								isBusy ? (
+									<Loader2 className="size-5 animate-spin" />
+								) : (
+									<Trash2 className="size-5 text-danger" />
+								)
+							}
+							aria-label="Move selected messages to Trash"
+							aria-busy={isBusy || undefined}
+							className="h-auto flex-1 flex-col gap-1 px-0 py-1.5 text-[11px]"
+						>
+							Delete
+						</Button>
+						{moveSlot && (
+							<div className="flex flex-1 flex-col items-center gap-1">
+								{moveSlot}
+								<span aria-hidden="true" className="text-[11px] text-fg-muted">
+									Move
+								</span>
+							</div>
+						)}
+						{onJunk && (
+							<Button
+								variant="ghost"
+								onClick={onJunk}
+								icon={<ShieldAlert className="size-5" />}
+								aria-label="Move selected messages to Junk"
+								className="h-auto flex-1 flex-col gap-1 px-0 py-1.5 text-[11px]"
+							>
+								Junk
+							</Button>
+						)}
+					</div>
+				)}
+
+				{showSmartRows && (onSelectSimilar || onSomethingElse) && (
+					<div className="flex flex-col gap-2">
+						{onSelectSimilar && (
+							<Button
+								variant="primary"
+								onClick={onSelectSimilar}
+								className="h-auto flex-col items-start gap-0 px-4 py-2.5 text-left"
+							>
+								<span className="text-sm font-semibold leading-tight">
+									Select similar messages
+								</span>
+								<span className="text-xs opacity-80">find more like these</span>
+							</Button>
+						)}
+						{onSomethingElse && (
+							<Button
+								variant="secondary"
+								onClick={onSomethingElse}
+								className="h-auto flex-col items-start gap-0 px-4 py-2.5 text-left"
+							>
+								<span className="text-sm font-medium leading-tight">
+									Something else
+								</span>
+								<span className="text-xs text-fg-subtle">
+									just deal with these
+								</span>
+							</Button>
+						)}
+					</div>
+				)}
+
+				{notice && (
+					<Banner
+						tone={notice.tone}
+						variant="soft"
+						role="status"
+						aria-live="polite"
+						className={cn(showQuickActions || progress ? "mt-1" : "mt-0")}
+					>
+						<div className="flex items-center justify-between gap-2">
+							{notice.text && <span>{notice.text}</span>}
+							{notice.action && (
+								<Button
+									variant="ghost"
+									size="md"
+									onClick={notice.action.onClick}
+									className="-my-1 min-h-11 shrink-0"
+								>
+									{notice.action.label}
+								</Button>
+							)}
+						</div>
+					</Banner>
+				)}
+			</div>
+		</div>
+	);
+}

package/src/index.ts

@@ -376,6 +376,16 @@ export {
 	type SegmentedOption,
 } from "./components/segmented-control.js";
 export { Select, type SelectProps } from "./components/select.js";
+export {
+	resolveSheetSnap,
+	SELECTION_SHEET_TEASER_HEIGHT,
+	SelectionSheet,
+	type SelectionSheetMode,
+	type SelectionSheetNotice,
+	type SelectionSheetNoticeAction,
+	type SelectionSheetProps,
+	type SheetSnapInput,
+} from "./components/selection-sheet.js";
 export {
 	SelectionTopBar,
 	type SelectionTopBarNotice,