@remit/ui 0.0.58 → 0.0.60

package/package.json

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

package/src/components/filter-rule.ts

@@ -241,15 +241,47 @@ export function commitLabel(scope: RuleScope): string {
 	return "Save until then";
 }
 
+/**
+ * Why a rule cannot be committed yet, one message per unmet condition. Any
+ * surface that asks for a rule — the editor in one pass, the wizard one step at
+ * a time — says the same thing about the same gap, because there is one string
+ * for it.
+ */
+export const ruleBlockedCopy = {
+	noMatch: "Add a clause so the rule has something to match.",
+	// A one-time apply runs the vector-free matcher, which cannot read message
+	// bodies. Saved as a rule the same clause works, so say that rather than
+	// refusing the clause outright.
+	bodyTextOnce:
+		"Applying once can't read message bodies. Save this as a rule instead, or drop the “has the words” clause.",
+	noAction: "Pick a folder to move into, or a label to apply.",
+	unnamed: "Name this rule so you can find it later.",
+	noUntilDate: "Pick the date this rule should stop on.",
+	counting: "Counting matches — save once the count settles.",
+	recounting: "Recounting matches — save once the count settles.",
+} as const;
+
+/**
+ * Why the count on screen is not yet the count that will be applied, or
+ * `undefined` once it has settled. This is what makes RFC 038's
+ * previewed-set-equals-applied-set contract structural rather than a promise:
+ * no surface can commit a rule whose match count is still moving.
+ */
+export function previewSettledReason(
+	preview: PreviewCount,
+): string | undefined {
+	if (preview.status === "loading") return ruleBlockedCopy.counting;
+	if (preview.status === "ready" && preview.stale)
+		return ruleBlockedCopy.recounting;
+	return undefined;
+}
+
 /**
  * Why the rule cannot be saved yet, or `undefined` when it is ready. A rule
  * needs at least one live way to match, at least one action — move and/or
  * label, either satisfies this (issue #26) — and, for the two persisted
- * scopes, a name and, for `until`, a date. It also needs a settled preview:
- * the rule is committable only when the count on screen is the count that
- * will be applied. That makes RFC 038's previewed-set-equals-applied-set
- * contract structural — a consumer cannot save a rule whose match count is
- * still moving. Never disable a control without saying why (ux.md).
+ * scopes, a name and, for `until`, a date. It also needs a settled preview.
+ * Never disable a control without saying why (ux.md).
  */
 export function commitBlockedReason(
 	rule: FilterRule,
@@ -258,26 +290,17 @@ export function commitBlockedReason(
 	const hasMatch =
 		rule.clauses.length > 0 ||
 		(rule.widen !== undefined && !rule.widen.inactive);
-	if (!hasMatch) return "Add a clause so the rule has something to match.";
-	// A one-time apply runs the vector-free matcher, which cannot read message
-	// bodies. Saved as a rule the same clause works, so say that rather than
-	// refusing the clause outright.
+	if (!hasMatch) return ruleBlockedCopy.noMatch;
 	if (rule.scope === "once" && unreadableBodyClauses(rule).length > 0)
-		return "Applying once can't read message bodies. Save this as a rule instead, or drop the “has the words” clause.";
-	if (!rule.moveMailboxId && !rule.labelId)
-		return "Pick a folder to move into, or a label to apply.";
+		return ruleBlockedCopy.bodyTextOnce;
+	if (!rule.moveMailboxId && !rule.labelId) return ruleBlockedCopy.noAction;
 	if (
 		(rule.scope === "standing" || rule.scope === "until") &&
 		(rule.name ?? "").trim() === ""
 	)
-		return "Name this rule so you can find it later.";
-	if (rule.scope === "until" && !rule.until)
-		return "Pick the date this rule should stop on.";
-	if (preview.status === "loading")
-		return "Counting matches — save once the count settles.";
-	if (preview.status === "ready" && preview.stale)
-		return "Recounting matches — save once the count settles.";
-	return undefined;
+		return ruleBlockedCopy.unnamed;
+	if (rule.scope === "until" && !rule.until) return ruleBlockedCopy.noUntilDate;
+	return previewSettledReason(preview);
 }
 
 export const demoFolders: FolderOption[] = [

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

@@ -62,10 +62,12 @@ function ControlledShell({
 	withSources = true,
 	singleAccount = false,
 	sourcesNote,
+	hideChrome = false,
 }: {
 	initialCategory?: string;
 	initialFilters?: Set<string>;
 	initialExpanded?: boolean;
+	hideChrome?: boolean;
 	initialSource?: string;
 	withSources?: boolean;
 	singleAccount?: boolean;
@@ -85,6 +87,7 @@ function ControlledShell({
 	return (
 		<div className="h-[600px] w-[390px]">
 			<FilterSheet
+				hideChrome={hideChrome}
 				categories={CATEGORIES}
 				filters={FILTERS}
 				sources={sources}
@@ -156,3 +159,14 @@ export const CollapsedWithSourceSelected: Story = {
 export const SingleAccount: Story = {
 	render: () => <ControlledShell singleAccount />,
 };
+
+/**
+ * The same shell with the filter row dropped, which is what a live search does:
+ * a query narrows the same list by the same intent, so the two never share the
+ * row. The children stay exactly where they were — swapping their parent for a
+ * plain container instead would remount everything under it, including a search
+ * field being typed into.
+ */
+export const ChromeHidden: Story = {
+	render: () => <ControlledShell hideChrome />,
+};

package/src/components/filter-sheet.tsx

@@ -62,6 +62,14 @@ export interface FilterSheetProps {
 	 * Required when `expanded` is a controlled prop.
 	 */
 	onExpandedChange?: (expanded: boolean) => void;
+	/**
+	 * Drop the filter row and its panel, keeping the shell and the children
+	 * exactly where they are. A search narrows the same list by the same intent
+	 * and takes the filter's place, and swapping the children's parent for a
+	 * plain container instead would remount everything under it — including a
+	 * search field being typed into.
+	 */
+	hideChrome?: boolean;
 	/**
 	 * The list rendered below the filter. The expanded panel is inline: it pushes
 	 * this content down (the list reflows), it does not overlay it.
@@ -112,6 +120,7 @@ export function FilterSheet({
 	onToggleFilter,
 	onClear,
 	onExpandedChange,
+	hideChrome = false,
 	children,
 }: FilterSheetProps) {
 	const isControlled = expandedProp !== undefined;
@@ -268,42 +277,44 @@ export function FilterSheet({
 			{/* The toggle is a div-button (not a real <button>) so the Clear
 			    control can be a real nested <button> without invalid
 			    button-in-button nesting. */}
-			{/* biome-ignore lint/a11y/useSemanticElements: nested <button> inside would be invalid button-in-button */}
-			<div
-				role="button"
-				tabIndex={0}
-				aria-expanded={open}
-				aria-label={open ? "Collapse filters" : "Expand filters"}
-				onClick={() => setOpen(!open)}
-				onKeyDown={(e) => {
-					if (!isSelfRowActivation(e)) return;
-					e.preventDefault();
-					setOpen(!open);
-				}}
-				className="flex h-section-row w-full shrink-0 cursor-pointer items-center gap-1.5 overflow-x-hidden border-b border-line bg-surface-sunken px-row-inset text-left hover:bg-surface"
-			>
-				{summaryChips}
-				{hasActive && (
-					<button
-						type="button"
-						aria-label="Clear filters"
-						onClick={(e) => {
-							e.stopPropagation();
-							clearAll();
-						}}
-						className="flex size-6 items-center justify-center text-fg-subtle hover:text-fg-muted"
-					>
-						<Close className="size-3" />
-					</button>
-				)}
-				<ChevronDown
-					className={cn(
-						"ml-auto size-3 shrink-0 text-fg-subtle transition-transform duration-200",
-						open ? "rotate-180" : "rotate-0",
+			{!hideChrome && (
+				// biome-ignore lint/a11y/useSemanticElements: nested <button> inside would be invalid button-in-button
+				<div
+					role="button"
+					tabIndex={0}
+					aria-expanded={open}
+					aria-label={open ? "Collapse filters" : "Expand filters"}
+					onClick={() => setOpen(!open)}
+					onKeyDown={(e) => {
+						if (!isSelfRowActivation(e)) return;
+						e.preventDefault();
+						setOpen(!open);
+					}}
+					className="flex h-section-row w-full shrink-0 cursor-pointer items-center gap-1.5 overflow-x-hidden border-b border-line bg-surface-sunken px-row-inset text-left hover:bg-surface"
+				>
+					{summaryChips}
+					{hasActive && (
+						<button
+							type="button"
+							aria-label="Clear filters"
+							onClick={(e) => {
+								e.stopPropagation();
+								clearAll();
+							}}
+							className="flex size-6 items-center justify-center text-fg-subtle hover:text-fg-muted"
+						>
+							<Close className="size-3" />
+						</button>
 					)}
-				/>
-			</div>
-			{open && (
+					<ChevronDown
+						className={cn(
+							"ml-auto size-3 shrink-0 text-fg-subtle transition-transform duration-200",
+							open ? "rotate-180" : "rotate-0",
+						)}
+					/>
+				</div>
+			)}
+			{open && !hideChrome && (
 				<div className="shrink-0">
 					{sourceRow}
 					{categoryRow}

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

@@ -213,13 +213,9 @@ export const CustomListBody: Story = {
 };
 
 /**
- * External `selectionBar` slot mechanism, exercised at desktop width with
- * `SelectionTopBar` as a convenient stand-in node — any slot content works
- * here, the point is that the pane header is replaced. This is NOT a
- * production composition: the live desktop toolbar is `SelectionToolbar`
- * (web-client only, not in this kit); `MessageList.tsx` only ever puts
- * `SelectionTopBar` in this slot when `!isDesktop` — see `NarrowExternalSelectionBar`
- * below for that production-accurate case.
+ * 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.
  */
 export const ExternalSelectionBar: Story = {
 	args: {
@@ -227,10 +223,18 @@ export const ExternalSelectionBar: Story = {
 		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,
+				}}
 			/>
 		),
 	},
@@ -238,9 +242,8 @@ export const ExternalSelectionBar: Story = {
 };
 
 /**
- * The production composition (`MessageList.tsx:798` gates on `!isDesktop`):
- * `SelectionTopBar` in the `selectionBar` slot at narrow width. Desktop never
- * renders this component in the slot — only `NarrowTouchList`'s width does.
+ * 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.
  */
 export const NarrowExternalSelectionBar: Story = {
 	args: {
@@ -248,10 +251,18 @@ export const NarrowExternalSelectionBar: Story = {
 		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,
+				}}
 			/>
 		),
 	},

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

@@ -43,7 +43,7 @@ export function MessageListPane({
 	isDesktop,
 	initialTouchState,
 	selectionBar,
-	selectionSheet,
+	paneOverlay,
 	listBody,
 	hideHeader = false,
 }: Pick<
@@ -86,12 +86,11 @@ export function MessageListPane({
 	 */
 	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.
+	 * An overlay covering the pane, above the rows — the guided organize flow.
+	 * The pane is the positioned ancestor it measures against, and it is
+	 * rendered last so it sits over everything the pane draws.
 	 */
-	selectionSheet?: ReactNode;
+	paneOverlay?: ReactNode;
 	/**
 	 * Overrides the row-rendering section of the non-brief list — the whole
 	 * scrollable body including virtualization, swipe-triage and any load-more
@@ -166,6 +165,7 @@ export function MessageListPane({
 			{selectionBar ??
 				(inBuiltinSelection ? (
 					<SelectionTopBar
+						title={listTitle}
 						count={checkedIds.size}
 						onCancel={cancelSelection}
 						onMarkRead={cancelSelection}
@@ -273,7 +273,7 @@ export function MessageListPane({
 			)}
 
 			{isDesktop && <KeyboardHintBar />}
-			{selectionSheet}
+			{paneOverlay}
 		</section>
 	);
 }

package/src/components/popover-menu.render.test.ts

@@ -29,4 +29,38 @@ describe("PopoverMenu", () => {
 		);
 		assert.equal(html, "");
 	});
+
+	it("stays alive for children alone, so a nested picker is reachable", () => {
+		const html = renderToString(
+			createElement(
+				PopoverMenu,
+				{ triggerLabel: "More actions", items: [] },
+				createElement("span", null, "Apply label"),
+			),
+		);
+		assert.match(html, /aria-label="More actions"/);
+	});
+
+	it("makes a nested menu a menuitem of the menu it sits in", () => {
+		const html = renderToString(
+			createElement(PopoverMenu, {
+				triggerLabel: "Apply label to selected messages",
+				items: [item],
+				nested: true,
+			}),
+		);
+		assert.match(html, /aria-label="Apply label[^>]*role="menuitem"/);
+		assert.match(html, /role="none"/);
+	});
+
+	it("renders the trigger text beside its glyph", () => {
+		const html = renderToString(
+			createElement(PopoverMenu, {
+				triggerLabel: "Apply label to selected messages",
+				triggerText: "Apply label",
+				items: [item],
+			}),
+		);
+		assert.match(html, /Apply label</);
+	});
 });

package/src/components/popover-menu.stories.tsx

@@ -55,3 +55,62 @@ export const SingleItem: Story = {
 export const Empty: Story = {
 	args: { triggerLabel: "More actions", items: [] },
 };
+
+/**
+ * A nested picker at the foot of the menu, for a list that belongs to the
+ * account rather than to the bar — the selection bar's apply-label trigger.
+ * Its own trigger is a worded row, so it reads as one of the menu's actions
+ * rather than a stray glyph.
+ */
+/**
+ * A list longer than the viewport. The panel scrolls within its own bounds, so
+ * the last row is reachable on a phone instead of running off the bottom.
+ */
+export const ManyItems: Story = {
+	args: {
+		triggerLabel: "More actions",
+		items: Array.from({ length: 24 }, (_, i) => ({
+			key: `label-${i}`,
+			label: `Label ${i + 1}`,
+			icon: <Tag className="size-4" />,
+			onSelect: () => undefined,
+		})),
+	},
+};
+
+export const WithNestedPicker: Story = {
+	args: {
+		triggerLabel: "More actions",
+		items: [
+			{
+				key: "read",
+				label: "Mark read",
+				icon: <MailOpen className="size-4" />,
+				onSelect: () => undefined,
+			},
+		],
+		children: (
+			<PopoverMenu
+				triggerLabel="Apply label to selected messages"
+				triggerIcon={<Tag className="size-4 text-fg-subtle" />}
+				triggerText="Apply label"
+				align="start"
+				nested
+				touch={false}
+				triggerClassName="min-h-11 w-full justify-start gap-3 px-4 py-2.5 text-sm font-normal text-fg"
+				items={[
+					{
+						key: "work",
+						label: "Work",
+						onSelect: () => undefined,
+					},
+					{
+						key: "receipts",
+						label: "Receipts",
+						onSelect: () => undefined,
+					},
+				]}
+			/>
+		),
+	},
+};

package/src/components/popover-menu.tsx

@@ -16,12 +16,27 @@ export interface PopoverMenuProps {
 	triggerLabel: string;
 	/** Trigger glyph. Defaults to the vertical ellipsis (kebab). */
 	triggerIcon?: ReactNode;
+	/** Visible trigger text. Without it the trigger is the glyph alone. */
+	triggerText?: string;
 	items: PopoverMenuItem[];
 	/** Which edge the menu aligns to. Defaults to "end" (right). */
 	align?: "start" | "end";
 	/** Touch-sizes the trigger to ≥44px. Defaults to true. */
 	touch?: boolean;
 	className?: string;
+	triggerClassName?: string;
+	/**
+	 * This menu is itself a row of an enclosing menu: the trigger becomes a
+	 * `menuitem` and its wrapper drops out of the accessibility tree, so the
+	 * enclosing `menu` holds only menu children.
+	 */
+	nested?: boolean;
+	/**
+	 * Extra rows below the items — a nested trigger whose own list is too long
+	 * or too dynamic to flatten into `items`, e.g. the label picker. Present
+	 * children keep the menu alive even with no items of its own.
+	 */
+	children?: ReactNode;
 }
 
 /**
@@ -29,16 +44,24 @@ export interface PopoverMenuProps {
  * dismissed on outside-click or Escape. Built on the kit `Button` for the
  * trigger; rows are ≥44px for touch ergonomics. The home for the secondary
  * actions an overflow menu collects (mark read/unread, …) so the live client
- * stops hand-rolling the same popover. Renders nothing when `items` is empty —
- * an empty kebab is dead weight, not a disabled control.
+ * stops hand-rolling the same popover. Renders nothing when there are no items
+ * and no children — an empty kebab is dead weight, not a disabled control, so
+ * a caller passing `children` owes it something to show.
+ *
+ * The panel scrolls within the viewport: a list as long as an account's labels
+ * would otherwise run off the bottom of a phone with no way to reach its end.
  */
 export function PopoverMenu({
 	triggerLabel,
 	triggerIcon,
+	triggerText,
 	items,
 	align = "end",
 	touch = true,
 	className,
+	triggerClassName,
+	nested = false,
+	children,
 }: PopoverMenuProps) {
 	const [open, setOpen] = useState(false);
 	const containerRef = useRef<HTMLDivElement>(null);
@@ -64,10 +87,14 @@ export function PopoverMenu({
 		};
 	}, [open]);
 
-	if (items.length === 0) return null;
+	if (items.length === 0 && !children) return null;
 
 	return (
-		<div ref={containerRef} className={cn("relative", className)}>
+		<div
+			ref={containerRef}
+			className={cn("relative", className)}
+			{...(nested ? { role: "none" } : {})}
+		>
 			<Button
 				variant="ghost"
 				size="sm"
@@ -76,13 +103,16 @@ export function PopoverMenu({
 				aria-label={triggerLabel}
 				aria-haspopup="menu"
 				aria-expanded={open}
-				className={cn(touch && "min-h-11 min-w-11 px-0")}
-			/>
+				{...(nested ? { role: "menuitem" } : {})}
+				className={cn(touch && "min-h-11 min-w-11 px-0", triggerClassName)}
+			>
+				{triggerText}
+			</Button>
 			{open && (
 				<div
 					role="menu"
 					className={cn(
-						"absolute top-full z-50 mt-1 flex min-w-44 flex-col rounded-md border border-line bg-surface py-1 shadow-lg",
+						"absolute top-full z-50 mt-1 flex max-h-[60dvh] min-w-44 flex-col overflow-y-auto overscroll-contain rounded-md border border-line bg-surface py-1 shadow-lg",
 						align === "end" ? "right-0" : "left-0",
 					)}
 				>
@@ -103,6 +133,7 @@ export function PopoverMenu({
 							{item.label}
 						</button>
 					))}
+					{children}
 				</div>
 			)}
 		</div>