@remit/ui 0.0.2 → 0.0.4

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/filter-presets.test.ts

@@ -60,13 +60,20 @@ describe("inboxFilterConfig", () => {
 		);
 	});
 
-	it("adds Has attachment to Unread and Flagged", () => {
+	it("adds Has attachment to Unread and Starred", () => {
 		assert.deepEqual(
 			inboxFilterConfig().filters.map((f) => f.id),
 			["unread", "flagged", "attachment"],
 		);
 	});
 
+	it("labels the IMAP \\Flagged filter 'Starred'", () => {
+		assert.deepEqual(
+			inboxFilterConfig().filters.map((f) => f.label),
+			["Unread", "Starred", "Has attachment"],
+		);
+	});
+
 	it("never offers an accounts source group", () => {
 		assert.equal(inboxFilterConfig().sources, undefined);
 	});

package/src/filter-presets.ts

@@ -43,7 +43,8 @@ const MESSAGE_CATEGORIES: FilterSheetCategory[] = [
 ];
 
 const UNREAD: FilterSheetFilter = { id: "unread", label: "Unread" };
-const FLAGGED: FilterSheetFilter = { id: "flagged", label: "Flagged" };
+// `flagged` is the wire name (IMAP \Flagged); the user-facing label is "Starred".
+const FLAGGED: FilterSheetFilter = { id: "flagged", label: "Starred" };
 const HAS_ATTACHMENT: FilterSheetFilter = {
 	id: "attachment",
 	label: "Has attachment",

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,