@remit/ui 0.0.3 → 0.0.5

package/src/components/search-chip-keys.ts

@@ -0,0 +1,154 @@
+/**
+ * The keyboard contract for the chips-plus-text search expression, as pure
+ * decisions over the field's state. Kept apart from the component so the rules
+ * are testable without a DOM — the component only maps a result onto focus and
+ * callbacks.
+ *
+ * Focus is roving: the whole field is one Tab stop, and focus sits either on
+ * the text input or on exactly one chip. Which one it sits on is what makes a
+ * keystroke mean "edit the query" or "act on a chip", so the two surfaces get
+ * one resolver each.
+ *
+ * Grounded in Material Design 3's chip accessibility guidance and Angular
+ * Material's `mat-chip-grid`, the closest documented chips-inside-a-field
+ * precedent. There is no W3C ARIA pattern for chips, so this is an adaptation
+ * rather than an implementation of a standard — it is settled by screen-reader
+ * testing, not by role names alone.
+ */
+
+/** Where focus should land. `null` means the text input. */
+export type ChipFocusTarget = number | null;
+
+export type ChipInputAction =
+	/** Move focus off the text and onto a chip. */
+	| { type: "focusChip"; index: number }
+	/** Clear the typed text, leaving the chips and any open thread alone. */
+	| { type: "clearQuery" }
+	| { type: "blur" }
+	| { type: "none" };
+
+export type ChipAction =
+	| { type: "removeChip"; index: number }
+	| { type: "focusChip"; index: number }
+	/** Return focus to the text input. */
+	| { type: "focusInput" }
+	/** Open the chip's own editor, where the host provides one. */
+	| { type: "activateChip"; index: number }
+	| { type: "none" };
+
+export interface ChipInputKeyState {
+	key: string;
+	shiftKey?: boolean;
+	/**
+	 * The keystroke came from the keyboard's auto-repeat, not a fresh press.
+	 * Holding Backspace to clear the text must stop at the chips instead of
+	 * running on into them, which would collapse the two-press rule into one
+	 * held key.
+	 */
+	repeat?: boolean;
+	/** Caret sits before all typed text, with nothing selected in the input. */
+	caretAtStart: boolean;
+	/** The field has typed text. */
+	hasValue: boolean;
+	chipCount: number;
+}
+
+export interface ChipKeyState {
+	key: string;
+	/** See `ChipInputKeyState.repeat`. */
+	repeat?: boolean;
+	/** Index of the chip that currently holds focus. */
+	index: number;
+	chipCount: number;
+}
+
+/**
+ * Keystrokes while the caret is in the text.
+ *
+ * Backspace at the very start of the text moves focus onto the preceding chip
+ * rather than removing it — the press that removes it is the next one, handled
+ * by `resolveChipKey`. Two presses, so a compound term is never destroyed by a
+ * stray keystroke.
+ */
+export function resolveChipInputKey({
+	key,
+	shiftKey = false,
+	repeat = false,
+	caretAtStart,
+	hasValue,
+	chipCount,
+}: ChipInputKeyState): ChipInputAction {
+	const lastChip = chipCount - 1;
+
+	if (key === "Escape") {
+		if (hasValue) return { type: "clearQuery" };
+		return { type: "blur" };
+	}
+
+	// Shift+Tab walks back into the chips instead of leaving the field, so the
+	// chips are reachable without a pointer.
+	if (key === "Tab" && shiftKey) {
+		if (chipCount === 0) return { type: "none" };
+		return { type: "focusChip", index: lastChip };
+	}
+
+	if (key === "Backspace" || key === "ArrowLeft") {
+		if (!caretAtStart || chipCount === 0) return { type: "none" };
+		// A held key that has just eaten the last character stops here: crossing
+		// into the chips has to be a deliberate press.
+		if (repeat) return { type: "none" };
+		return { type: "focusChip", index: lastChip };
+	}
+
+	return { type: "none" };
+}
+
+/** Keystrokes while a chip holds focus. */
+export function resolveChipKey({
+	key,
+	repeat = false,
+	index,
+	chipCount,
+}: ChipKeyState): ChipAction {
+	if (key === "Backspace" || key === "Delete") {
+		// One press, one chip. Holding the key must not walk the whole strip.
+		if (repeat) return { type: "none" };
+		return { type: "removeChip", index };
+	}
+
+	if (key === "ArrowLeft") {
+		if (index === 0) return { type: "none" };
+		return { type: "focusChip", index: index - 1 };
+	}
+
+	if (key === "ArrowRight") {
+		// Past the last chip is the text, caret at the start.
+		if (index >= chipCount - 1) return { type: "focusInput" };
+		return { type: "focusChip", index: index + 1 };
+	}
+
+	if (key === "Enter" || key === " ") {
+		return { type: "activateChip", index };
+	}
+
+	if (key === "Escape") {
+		return { type: "focusInput" };
+	}
+
+	return { type: "none" };
+}
+
+/**
+ * Where focus lands after the chip at `removedIndex` is removed: the chip that
+ * takes its place, else the one before it, else the text input. Never nowhere —
+ * a removal that drops focus to the document body strands keyboard users.
+ */
+export function focusAfterRemoval(
+	removedIndex: number,
+	countBeforeRemoval: number,
+): ChipFocusTarget {
+	const remaining = countBeforeRemoval - 1;
+	if (remaining <= 0) return null;
+	if (removedIndex < remaining) return removedIndex;
+	return remaining - 1;
+}

package/src/components/search-token-chip.tsx

@@ -1,26 +1,44 @@
 import { X } from "lucide-react";
+import { forwardRef } from "react";
 import { cn } from "../lib/cn.js";
 
+/**
+ * What the chip represents. A `scope` chip is the view the user is already in
+ * (the folder they navigated to) rather than a filter they typed, so it is
+ * visually differentiated — same removability, different provenance.
+ */
+export type SearchChipTone = "filter" | "scope";
+
 export interface SearchTokenChipProps {
 	label: string;
 	onRemove: () => void;
+	tone?: SearchChipTone;
 	className?: string;
 }
 
+const toneClass: Record<SearchChipTone, string> = {
+	filter: "border-line bg-surface-sunken text-fg-muted",
+	scope: "border-accent-2/40 bg-accent-2-soft text-accent-2",
+};
+
 /**
- * One removable filter-token chip (`from:`, `has:attachment`, …) shown under
- * the search field once the field's typed text parses a recognized token.
- * Same dismissible-pill treatment as `AddressTag`, generalized to a plain
+ * One removable filter-token chip (`from:`, `has:attachment`, …) as a static
+ * pill. Same dismissible treatment as `AddressTag`, generalized to a plain
  * label since a token chip carries no email identity.
+ *
+ * For chips inside the search field — where they are focusable and the
+ * keyboard can remove them — use `SearchChipRow` instead.
  */
 export const SearchTokenChip = ({
 	label,
 	onRemove,
+	tone = "filter",
 	className,
 }: SearchTokenChipProps) => (
 	<span
 		className={cn(
-			"inline-flex items-center gap-1 rounded-full border border-line bg-surface-sunken px-2 py-0.5 text-2xs text-fg-muted",
+			"inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-2xs",
+			toneClass[tone],
 			className,
 		)}
 	>
@@ -36,6 +54,95 @@ export const SearchTokenChip = ({
 	</span>
 );
 
+export interface SearchChipRowProps {
+	label: string;
+	onRemove: () => void;
+	/** Opens the chip's own editor, where the host offers one. */
+	onActivate?: () => void;
+	tone?: SearchChipTone;
+	/** True for the one chip in the roving tab order (see `SearchChipInput`). */
+	focused?: boolean;
+	onKeyDown?: (event: React.KeyboardEvent) => void;
+	onFocusLabel?: () => void;
+	className?: string;
+}
+
+/**
+ * One chip inside the search field, as a `row` of the enclosing `grid`.
+ *
+ * The label and the remove button are separate `gridcell`s so a screen reader
+ * announces the chip and its removal as two distinct actions — M3's
+ * requirement for a chip that carries a remove affordance. Only the label cell
+ * takes part in the roving tab order; the remove button stays reachable by
+ * pointer and by the Backspace/Delete route on the focused chip, which keeps
+ * the field a single Tab stop.
+ */
+export const SearchChipRow = forwardRef<HTMLButtonElement, SearchChipRowProps>(
+	(
+		{
+			label,
+			onRemove,
+			onActivate,
+			tone = "filter",
+			focused = false,
+			onKeyDown,
+			onFocusLabel,
+			className,
+		},
+		ref,
+	) => (
+		// biome-ignore lint/a11y/useSemanticElements: grid pattern, not tabular data
+		<span
+			role="row"
+			// Not a tab stop itself — the cells inside it are. Present so the row is
+			// programmatically focusable, as its role implies.
+			tabIndex={-1}
+			className={cn(
+				"inline-flex max-w-48 items-center gap-1 rounded-full border px-2 py-0.5 text-2xs transition-colors",
+				toneClass[tone],
+				focused && "ring-2 ring-ring",
+				className,
+			)}
+		>
+			{/* biome-ignore lint/a11y/useSemanticElements: see the row */}
+			<button
+				ref={ref}
+				type="button"
+				role="gridcell"
+				// Roving tabindex: exactly one chip (or the text input) is in the tab
+				// order at a time, so the whole field is one Tab stop.
+				tabIndex={focused ? 0 : -1}
+				onClick={onActivate}
+				onFocus={onFocusLabel}
+				onKeyDown={onKeyDown}
+				className={cn(
+					"block min-w-0 max-w-full truncate rounded-full outline-none",
+					onActivate ? "cursor-pointer" : "cursor-default",
+				)}
+			>
+				{label}
+			</button>
+			{/* biome-ignore lint/a11y/useSemanticElements: see the row */}
+			<button
+				type="button"
+				role="gridcell"
+				tabIndex={-1}
+				onClick={onRemove}
+				// Deliberately not wired to the roving handler. Should this button take
+				// focus — a click, or assistive tech moving to it — that handler would
+				// read Enter/Space as "activate the chip" and preventDefault them,
+				// swallowing the button's own click. Its native activation is the
+				// remove action already.
+				className="block shrink-0 rounded-full p-0.5 transition-colors hover:bg-fg-muted/20"
+				aria-label={`Remove filter: ${label}`}
+			>
+				<X className="size-3" />
+			</button>
+		</span>
+	),
+);
+SearchChipRow.displayName = "SearchChipRow";
+
 export interface SearchTokenChipsProps {
 	tokens: { label: string; onRemove: () => void }[];
 	className?: string;

package/src/components/slide-panel.render.test.ts

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { createElement } from "react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { SlidePanel, type SlidePanelProps } from "./slide-panel.js";
+
+const render = (isOpen: boolean) =>
+	renderToStaticMarkup(
+		createElement(
+			SlidePanel,
+			// createElement never folds the children argument into the props type,
+			// so a component with required children needs the props cast.
+			{
+				isOpen,
+				onClose: () => undefined,
+				title: "Add Account",
+			} as SlidePanelProps,
+			"panel body",
+		),
+	);
+
+/** The panel element itself, as distinct from the scrim behind it. */
+const dialog = (html: string): string => {
+	const match = html.match(/<div[^>]*role="dialog"[^>]*>/);
+	assert.ok(match, "no dialog element rendered");
+	return match[0];
+};
+
+/** The click-to-dismiss scrim: the first element, before the dialog. */
+const scrim = (html: string): string => {
+	const match = html.match(/^<div[^>]*>/);
+	assert.ok(match, "no scrim element rendered");
+	return match[0];
+};
+
+describe("SlidePanel (#57)", () => {
+	it("is a fixed right-edge column, never a full-viewport takeover above sm", () => {
+		const html = render(true);
+		assert.match(html, /fixed top-0 right-0/);
+		assert.match(html, /sm:w-\[400px\]/);
+		assert.match(html, /translate-x-0/);
+	});
+
+	it("a closed panel is off-canvas and takes no pointer events", () => {
+		const html = render(false);
+		assert.match(html, /translate-x-full/);
+		assert.match(html, /pointer-events-none/);
+	});
+
+	it("a closed panel is inert and hidden from assistive tech", () => {
+		const tag = dialog(render(false));
+		assert.match(tag, /inert=""/);
+		assert.match(tag, /aria-hidden="true"/);
+	});
+
+	it("an open panel is reachable", () => {
+		const tag = dialog(render(true));
+		assert.doesNotMatch(tag, /inert=""/);
+		assert.match(tag, /aria-hidden="false"/);
+		assert.match(tag, /role="dialog"/);
+	});
+
+	it("scrolls its body rather than the page", () => {
+		const html = render(true);
+		assert.match(html, /overflow-auto/);
+	});
+
+	/**
+	 * The scrim is a pointer shortcut for the header's Close button, not a
+	 * control of its own: posing as a focusable button while answering only
+	 * Escape strands a keyboard user on a thing that looks activatable.
+	 */
+	it("the scrim never poses as a focusable control", () => {
+		for (const html of [render(true), render(false)]) {
+			const tag = scrim(html);
+			assert.doesNotMatch(tag, /role="button"/);
+			assert.doesNotMatch(tag, /tabindex=/);
+			assert.match(tag, /aria-hidden="true"/);
+		}
+	});
+
+	it("always offers a labelled close control in the header", () => {
+		assert.match(render(true), /aria-label="Close"/);
+	});
+});

package/src/components/slide-panel.stories.tsx

@@ -0,0 +1,129 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { Button } from "./button.js";
+import { FieldLabel } from "./field-label.js";
+import { Input } from "./input.js";
+import { SlidePanel } from "./slide-panel.js";
+
+const meta: Meta<typeof SlidePanel> = {
+	title: "Components/SlidePanel",
+	component: SlidePanel,
+	parameters: { layout: "fullscreen" },
+};
+export default meta;
+
+type Story = StoryObj<typeof SlidePanel>;
+
+const backdropRows = Array.from({ length: 12 }, (_, i) => `Row ${i + 1}`);
+
+const Backdrop = () => (
+	<div className="h-dvh space-y-3 bg-canvas p-6">
+		<h1 className="text-md font-semibold text-fg">Screen behind the panel</h1>
+		{backdropRows.map((row) => (
+			<div
+				key={row}
+				className="rounded-sm border border-line bg-surface px-4 py-3 text-sm text-fg-muted"
+			>
+				{row}
+			</div>
+		))}
+	</div>
+);
+
+const Body = () => (
+	<div className="space-y-4">
+		<div>
+			<FieldLabel htmlFor="slide-panel-email">Email address</FieldLabel>
+			<Input id="slide-panel-email" placeholder="alice@example.com" />
+		</div>
+		<div>
+			<FieldLabel htmlFor="slide-panel-name">Display name</FieldLabel>
+			<Input id="slide-panel-name" placeholder="Alice" />
+		</div>
+	</div>
+);
+
+const Footer = ({ onClose }: { onClose: () => void }) => (
+	<>
+		<Button variant="secondary" size="sm" onClick={onClose}>
+			Cancel
+		</Button>
+		<Button variant="primary" size="sm">
+			Save
+		</Button>
+	</>
+);
+
+/** Open: a fixed-width column at the right edge, the screen behind it dimmed. */
+export const Open: Story = {
+	globals: { viewport: { value: "desktop" } },
+	render: () => (
+		<>
+			<Backdrop />
+			<SlidePanel isOpen onClose={() => {}} title="Add Account" footer={null}>
+				<Body />
+			</SlidePanel>
+		</>
+	),
+};
+
+/**
+ * Closed. The panel stays mounted so it can animate, so this is the state that
+ * has to be provably invisible: a closed panel that is not pushed off-canvas
+ * takes over the whole screen (#57).
+ */
+export const Closed: Story = {
+	globals: { viewport: { value: "desktop" } },
+	render: () => (
+		<>
+			<Backdrop />
+			<SlidePanel
+				isOpen={false}
+				onClose={() => {}}
+				title="Add Account"
+				footer={null}
+			>
+				<Body />
+			</SlidePanel>
+		</>
+	),
+};
+
+/** On a phone the panel owns the full width. */
+export const Phone: Story = {
+	globals: { viewport: { value: "mobile" } },
+	render: () => (
+		<>
+			<Backdrop />
+			<SlidePanel isOpen onClose={() => {}} title="Add Account" footer={null}>
+				<Body />
+			</SlidePanel>
+		</>
+	),
+};
+
+/** Opening and closing from the screen behind it. */
+export const Interactive: Story = {
+	globals: { viewport: { value: "desktop" } },
+	render: function Render() {
+		const [open, setOpen] = useState(false);
+		return (
+			<>
+				<div className="h-dvh space-y-3 bg-canvas p-6">
+					<Button variant="primary" size="sm" onClick={() => setOpen(true)}>
+						Add account
+					</Button>
+					<Backdrop />
+				</div>
+				<SlidePanel
+					isOpen={open}
+					onClose={() => setOpen(false)}
+					title="Add Account"
+					footer={<Footer onClose={() => setOpen(false)} />}
+				>
+					<Body />
+				</SlidePanel>
+			</>
+		);
+	},
+};

package/src/components/slide-panel.tsx

@@ -0,0 +1,92 @@
+import { X } from "lucide-react";
+import { type ReactNode, useEffect } from "react";
+import { cn } from "../lib/cn.js";
+
+/* ------------------------------------------------------------------ */
+/* SlidePanel: right-edge slide-over for a focused sub-task (editing   */
+/* an account) without leaving the screen behind it. Full width on     */
+/* phones, a fixed-width column from `sm` up.                          */
+/*                                                                     */
+/* A closed panel stays mounted so it can animate, so it must be inert */
+/* in every sense that is not visual: no pointer events, out of the    */
+/* tab order, hidden from assistive technology.                        */
+/* ------------------------------------------------------------------ */
+
+export interface SlidePanelProps {
+	isOpen: boolean;
+	onClose: () => void;
+	title: string;
+	children: ReactNode;
+	footer?: ReactNode;
+}
+
+export function SlidePanel({
+	isOpen,
+	onClose,
+	title,
+	children,
+	footer,
+}: SlidePanelProps) {
+	// Escape closes the panel from anywhere inside it, which is what a dialog
+	// owes the keyboard. The scrim is a pointer affordance only.
+	useEffect(() => {
+		if (!isOpen) return;
+		const onKeyDown = (event: KeyboardEvent) => {
+			if (event.key === "Escape") onClose();
+		};
+		document.addEventListener("keydown", onKeyDown);
+		return () => document.removeEventListener("keydown", onKeyDown);
+	}, [isOpen, onClose]);
+
+	return (
+		<>
+			{/* Click-to-dismiss scrim: a pointer shortcut for the header's Close
+			    button, never the only way out, so it stays out of the tab order and
+			    the a11y tree rather than posing as a control. */}
+			<div
+				className={cn(
+					"fixed inset-0 z-40 bg-black/30 transition-opacity",
+					isOpen ? "opacity-100" : "pointer-events-none opacity-0",
+				)}
+				onClick={onClose}
+				aria-hidden="true"
+			/>
+
+			<div
+				className={cn(
+					"fixed top-0 right-0 z-50 h-full w-full border-l border-line bg-canvas shadow-xl sm:w-[400px] sm:max-w-[90vw]",
+					"transform transition-transform duration-200 ease-out",
+					isOpen ? "translate-x-0" : "pointer-events-none translate-x-full",
+				)}
+				role="dialog"
+				aria-modal="true"
+				aria-hidden={!isOpen}
+				inert={!isOpen}
+				aria-labelledby="slide-panel-title"
+			>
+				<div className="flex h-14 items-center justify-between border-b border-line px-4">
+					<h2 id="slide-panel-title" className="font-semibold">
+						{title}
+					</h2>
+					<button
+						type="button"
+						onClick={onClose}
+						className="rounded-md p-1.5 transition-colors hover:bg-surface-raised"
+						aria-label="Close"
+					>
+						<X className="size-5" />
+					</button>
+				</div>
+
+				<div className="flex h-[calc(100%-3.5rem)] flex-col">
+					<div className="flex-1 overflow-auto p-4">{children}</div>
+					{footer && (
+						<div className="flex justify-end gap-3 border-t border-line bg-canvas p-4">
+							{footer}
+						</div>
+					)}
+				</div>
+			</div>
+		</>
+	);
+}

package/src/index.ts

@@ -42,6 +42,7 @@ export {
 	type TouchSeed,
 	useContainerWidth,
 } from "./components/app-shell-types.js";
+export { AppTopBar, type AppTopBarProps } from "./components/app-top-bar.js";
 export { AuthCard, type AuthCardProps } from "./components/auth-card.js";
 export {
 	AuthFooter,
@@ -279,6 +280,11 @@ export {
 	type RowDestructiveAction,
 } from "./components/row-actions.js";
 export { SearchBar, type SearchBarProps } from "./components/search-bar.js";
+export {
+	type SearchChip,
+	SearchChipInput,
+	type SearchChipInputProps,
+} from "./components/search-chip-input.js";
 export {
 	type SearchResult,
 	SearchResultRow,
@@ -291,6 +297,9 @@ export {
 	type SearchResultsProps,
 } from "./components/search-results.js";
 export {
+	SearchChipRow,
+	type SearchChipRowProps,
+	type SearchChipTone,
 	SearchTokenChip,
 	type SearchTokenChipProps,
 	SearchTokenChips,
@@ -333,6 +342,10 @@ export {
 	SettingsShell,
 	type SettingsShellProps,
 } from "./components/settings-screen.js";
+export {
+	SlidePanel,
+	type SlidePanelProps,
+} from "./components/slide-panel.js";
 export {
 	commitPeek,
 	SwipeableRow,