@12-apps/ui 6.63.1 → 6.64.0

package/src/components/form/PickerSheet/PickerSheet.styles.ts

@@ -0,0 +1,249 @@
+import { alpha, type CSSObject, type Theme } from '@mui/material/styles/index.js';
+
+import { fieldBorder, fieldHeight } from '../../../tokens/field-height';
+import { fieldRadiusPx } from '../../../tokens/field-radius';
+import { fieldWell, uiInk } from '../../../tokens/ink';
+import { rem, rems } from '../../../tokens/relative';
+
+/**
+ * The prototype's measurements, verbatim, in the design's px.
+ *
+ * Each is drawn through `rem()` where it is read, so the sheet follows a
+ * density mode the way every other surface in the package does. Colours come
+ * from the palette (a white-labelled tenant and dark mode carry through).
+ */
+const METRICS = {
+  dialogWidthPx: 520,
+  dialogMaxHeightPx: 780,
+  dialogRadiusPx: 14,
+  /** The gap a centred dialog keeps from the viewport edge. */
+  dialogMarginPx: 32,
+  sheetRadiusPx: 16,
+  headGapPx: 10,
+  closeButtonPx: 36,
+  controlRadiusPx: 8,
+  bodyPaddingPx: 16,
+  bodyGapPx: 12,
+  listMaxHeightPx: 380,
+  listGapPx: 2,
+  rowPaddingPx: 10,
+  rowMinHeightPx: 44,
+  /** Left padding per level of `indent` (`.pitem.ind{padding-left:28px}` at depth 1). */
+  rowIndentStepPx: 28,
+  checkGlyphPx: 16,
+  closeGlyphPx: 18,
+  searchGlyphPx: 16,
+  /** The magnifier's inset from the field's inner edge, and the gap before the text. */
+  searchGlyphInsetPx: 10,
+  searchGlyphGapPx: 6,
+  /** The prototype's body line-height; the sheet sets it rather than inheriting a host's. */
+  lineHeight: 1.4,
+} as const;
+
+/** The panel's shadow: `0 16px 48px` of ink at 0.28. */
+const panelShadow = (theme: Theme): string =>
+  `${rems(theme, 0, 16, 48)} ${alpha(uiInk(theme).panelShadowInk, 0.28)}`;
+
+/** The centred dialog's paper, on a pointer. */
+export const dialogPaperSx = (theme: Theme): CSSObject => ({
+  width: rem(theme, METRICS.dialogWidthPx),
+  maxWidth: `calc(100% - ${rem(theme, METRICS.dialogMarginPx)})`,
+  maxHeight: `min(${rem(theme, METRICS.dialogMaxHeightPx)}, calc(100% - ${rem(theme, METRICS.dialogMarginPx * 2)}))`,
+  margin: 0,
+  borderRadius: rem(theme, METRICS.dialogRadiusPx),
+  boxShadow: panelShadow(theme),
+  background: theme.palette.background.paper,
+  backgroundImage: 'none',
+  display: 'flex',
+  flexDirection: 'column',
+  overflow: 'hidden',
+});
+
+/** The bottom sheet's paper, on a phone: full width, no grab handle. */
+export const sheetPaperSx = (theme: Theme): CSSObject => ({
+  width: '100%',
+  maxHeight: '88%',
+  borderRadius: rems(theme, METRICS.sheetRadiusPx, METRICS.sheetRadiusPx, 0, 0),
+  boxShadow: panelShadow(theme),
+  background: theme.palette.background.paper,
+  backgroundImage: 'none',
+  display: 'flex',
+  flexDirection: 'column',
+  overflow: 'hidden',
+});
+
+/** `.sh` — kicker and title on the left, the close button on the right. */
+export const headSx = (theme: Theme): CSSObject => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: rem(theme, METRICS.headGapPx),
+  padding: rems(theme, 14, 16),
+  // A shade under the controls' own border: the rule separates, it does not frame.
+  borderBottom: `1px solid ${alpha(theme.palette.divider, 0.6)}`,
+  flex: '0 0 auto',
+});
+
+export const kickerSx = (theme: Theme): CSSObject => ({
+  fontSize: rem(theme, 11.5),
+  color: theme.palette.text.secondary,
+  lineHeight: METRICS.lineHeight,
+});
+
+export const titleSx = (theme: Theme): CSSObject => ({
+  margin: 0,
+  fontSize: rem(theme, 14),
+  fontWeight: 700,
+  lineHeight: METRICS.lineHeight,
+  color: theme.palette.text.primary,
+});
+
+export const closeButtonSx = (theme: Theme): CSSObject => ({
+  flex: '0 0 auto',
+  width: rem(theme, METRICS.closeButtonPx),
+  height: rem(theme, METRICS.closeButtonPx),
+  display: 'grid',
+  placeItems: 'center',
+  padding: 0,
+  border: `1px solid ${theme.palette.divider}`,
+  borderRadius: rem(theme, METRICS.controlRadiusPx),
+  background: 'transparent',
+  color: theme.palette.text.primary,
+  cursor: 'pointer',
+  '& svg': { width: rem(theme, METRICS.closeGlyphPx), height: rem(theme, METRICS.closeGlyphPx) },
+  '&:hover': { background: theme.palette.action.hover },
+  '&:focus-visible': { outline: `${rem(theme, 2)} solid ${theme.palette.primary.main}`, outlineOffset: rem(theme, 1) },
+});
+
+/** `.sb` — the scrolling body: search, list, foot. */
+export const bodySx = (theme: Theme): CSSObject => ({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: rem(theme, METRICS.bodyGapPx),
+  padding: rem(theme, METRICS.bodyPaddingPx),
+  overflow: 'auto',
+  minHeight: 0,
+  flex: '1 1 auto',
+});
+
+/**
+ * The search field: the library's field height, border and corner, with a
+ * leading magnifier. White on the light sheet, so the field reads as a field
+ * against the paper behind it.
+ */
+export const searchFieldSx = (theme: Theme): CSSObject => ({
+  position: 'relative',
+  display: 'flex',
+  alignItems: 'center',
+  flex: '0 0 auto',
+  '& > svg': {
+    position: 'absolute',
+    // + 1 for the input's own border, which the glyph sits inside of.
+    left: rem(theme, METRICS.searchGlyphInsetPx + 1),
+    width: rem(theme, METRICS.searchGlyphPx),
+    height: rem(theme, METRICS.searchGlyphPx),
+    color: theme.palette.text.secondary,
+    pointerEvents: 'none',
+    zIndex: 1,
+  },
+  '& input': {
+    width: '100%',
+    height: fieldHeight(theme),
+    boxSizing: 'border-box',
+    padding: rems(theme, 0, 10, 0, METRICS.searchGlyphInsetPx + METRICS.searchGlyphPx + METRICS.searchGlyphGapPx),
+    fontSize: rem(theme, 14),
+    border: fieldBorder(theme),
+    borderRadius: fieldRadiusPx(theme),
+    background: fieldWell(theme),
+    color: theme.palette.text.primary,
+    '&:focus': {
+      outline: 'none',
+      borderColor: theme.palette.primary.main,
+      boxShadow: `0 0 0 ${rem(theme, 3)} ${alpha(theme.palette.primary.main, 0.15)}`,
+    },
+  },
+});
+
+/** The list: a column, scrolling on its own past 380px. */
+export const listSx = (theme: Theme): CSSObject => ({
+  display: 'flex',
+  flexDirection: 'column',
+  gap: rem(theme, METRICS.listGapPx),
+  maxHeight: rem(theme, METRICS.listMaxHeightPx),
+  overflow: 'auto',
+  overscrollBehavior: 'contain',
+  margin: 0,
+  padding: 0,
+  listStyle: 'none',
+  flex: '0 1 auto',
+});
+
+/** Left padding for a row at `depth` — the row's own 10px at depth 0, 28px per level below it. */
+export const rowPaddingLeft = (theme: Theme, depth: number): string =>
+  rem(theme, depth > 0 ? METRICS.rowIndentStepPx * depth : METRICS.rowPaddingPx);
+
+/** Background of a row: selected wins over the keyboard cursor, which wins over rest. */
+function rowBackground(theme: Theme, selected: boolean, active: boolean): string {
+  if (selected) return alpha(theme.palette.primary.main, 0.1);
+  return active ? theme.palette.action.hover : 'transparent';
+}
+
+/** `.pitem` — a row. `active` is the keyboard cursor, drawn as a ring so it reads apart from `selected`. */
+export const rowSx = (theme: Theme, selected: boolean, active: boolean): CSSObject => ({
+  display: 'flex',
+  alignItems: 'center',
+  gap: rem(theme, 10),
+  padding: rem(theme, METRICS.rowPaddingPx),
+  minHeight: rem(theme, METRICS.rowMinHeightPx),
+  boxSizing: 'border-box',
+  borderRadius: rem(theme, METRICS.controlRadiusPx),
+  textAlign: 'left',
+  cursor: 'pointer',
+  userSelect: 'none',
+  color: theme.palette.text.primary,
+  background: rowBackground(theme, selected, active),
+  boxShadow: active ? `inset 0 0 0 ${rem(theme, 1)} ${alpha(theme.palette.primary.main, 0.3)}` : 'none',
+  '&:hover': { background: selected ? alpha(theme.palette.primary.main, 0.1) : theme.palette.action.hover },
+});
+
+export const rowTextSx: CSSObject = { flex: '1 1 auto', minWidth: 0 };
+
+export const rowLabelSx = (theme: Theme): CSSObject => ({
+  display: 'block',
+  fontSize: rem(theme, 14),
+  lineHeight: METRICS.lineHeight,
+});
+
+export const rowMetaSx = (theme: Theme): CSSObject => ({
+  display: 'block',
+  fontSize: rem(theme, 12),
+  lineHeight: METRICS.lineHeight,
+  color: theme.palette.text.secondary,
+});
+
+export const checkSx = (theme: Theme): CSSObject => ({
+  flex: '0 0 auto',
+  display: 'grid',
+  color: theme.palette.primary.main,
+  '& svg': { width: rem(theme, METRICS.checkGlyphPx), height: rem(theme, METRICS.checkGlyphPx) },
+});
+
+/** The create row's text: the accent, at 600. */
+export const createLabelSx = (theme: Theme): CSSObject => ({
+  ...rowLabelSx(theme),
+  color: theme.palette.primary.main,
+  fontWeight: 600,
+});
+
+export const emptySx = (theme: Theme): CSSObject => ({
+  fontSize: rem(theme, 12),
+  lineHeight: METRICS.lineHeight,
+  color: theme.palette.text.secondary,
+  padding: rem(theme, 10),
+});
+
+export const footSx = (theme: Theme): CSSObject => ({
+  margin: 0,
+  fontSize: rem(theme, 12),
+  lineHeight: METRICS.lineHeight,
+  color: theme.palette.text.secondary,
+});

package/src/components/form/PickerSheet/PickerSheet.tsx

@@ -0,0 +1,132 @@
+'use client';
+
+import { useId } from 'react';
+import Box from '@mui/material/Box/index.js';
+import Dialog from '@mui/material/Dialog/index.js';
+import Drawer from '@mui/material/Drawer/index.js';
+import { useTheme } from '@mui/material/styles/index.js';
+import useMediaQuery from '@mui/material/useMediaQuery/index.js';
+
+import { METRICS as CATEGORY_SELECT_METRICS } from '../CategorySelect/CategorySelect.styles';
+import { stackedOverlayZIndex } from '../../../tokens/layers';
+import { PickerSheetHead, PickerSheetList, PickerSheetSearch } from './PickerSheet.parts';
+import { bodySx, dialogPaperSx, footSx, sheetPaperSx } from './PickerSheet.styles';
+import type { PickerSheetProps } from './PickerSheet.types';
+import { usePickerSheet } from './usePickerSheet';
+
+/**
+ * Both surfaces clear the sheet ladder rather than taking MUI's default — the
+ * same rule as `CategoryPanelSurface`. A `Dialog` sits at `zIndex.modal` and a
+ * temporary `Drawer` a step lower, while `StackedModal` puts its second panel
+ * at 1310: a picker opened from a stacked editor painted UNDER it (FUT-806).
+ * See `tokens/layers`.
+ */
+const ABOVE_SHEETS = { zIndex: stackedOverlayZIndex } as const;
+
+interface SurfaceProps {
+  open: boolean;
+  /** True below the sheet breakpoint — a bottom sheet instead of a centred dialog. */
+  sheet: boolean;
+  onClose: () => void;
+  titleId: string;
+  dataTestId: string;
+  children: React.ReactNode;
+}
+
+/**
+ * Where the sheet lives. Both surfaces are modal, which gives Esc, the
+ * tap-outside dismissal and focus containment for free.
+ */
+function PickerSheetSurface({ open, sheet, onClose, titleId, dataTestId, children }: SurfaceProps): React.JSX.Element {
+  const close = (): void => onClose();
+  if (sheet) {
+    // A Drawer's paper carries no dialog semantics of its own, so it is given them.
+    const paper = {
+      sx: sheetPaperSx,
+      role: 'dialog',
+      'aria-modal': true,
+      'aria-labelledby': titleId,
+      'data-testid': dataTestId,
+    };
+    return (
+      <Drawer anchor="bottom" open={open} onClose={close} sx={ABOVE_SHEETS} slotProps={{ paper }}>
+        {children}
+      </Drawer>
+    );
+  }
+  const paper = { sx: dialogPaperSx, 'data-testid': dataTestId };
+  return (
+    <Dialog open={open} onClose={close} aria-labelledby={titleId} sx={ABOVE_SHEETS} slotProps={{ paper }}>
+      {children}
+    </Dialog>
+  );
+}
+
+/**
+ * A searchable pick-or-create sheet: a title, a search box, a list of rows
+ * (optionally a tree), and a create row when the query names nothing yet.
+ *
+ * A centred dialog on a pointer and a bottom sheet under `CategorySelect`'s
+ * sheet breakpoint. Typing filters (case-insensitive substring over each
+ * item's label and `searchText`, accents aside) and flattens the tree; ↑↓ move
+ * the cursor, Enter picks,
+ * Esc or a tap outside closes. Picking calls `onPick` and nothing else — the
+ * caller decides when to close. All copy comes from the caller.
+ */
+export function PickerSheet(props: PickerSheetProps): React.JSX.Element {
+  const { open, onClose, kicker, title, searchPlaceholder, searchLabel, closeLabel, createLabel, createMeta, emptyText, foot } =
+    props;
+  const dataTestId = props.dataTestId ?? 'picker-sheet';
+  const theme = useTheme();
+  const sheet = useMediaQuery(theme.breakpoints.down(CATEGORY_SELECT_METRICS.sheetBreakpoint));
+  const baseId = useId();
+  const titleId = `${baseId}-title`;
+  const listId = `${baseId}-list`;
+  const rowId = (index: number): string => `${baseId}-row-${index}`;
+  const state = usePickerSheet(props);
+
+  return (
+    <PickerSheetSurface open={open} sheet={sheet} onClose={onClose} titleId={titleId} dataTestId={dataTestId}>
+      <PickerSheetHead
+        kicker={kicker}
+        title={title}
+        titleId={titleId}
+        closeLabel={closeLabel}
+        onClose={onClose}
+        dataTestId={dataTestId}
+      />
+      <Box sx={bodySx}>
+        <PickerSheetSearch
+          query={state.query}
+          placeholder={searchPlaceholder}
+          label={searchLabel}
+          listId={listId}
+          activeId={state.activeIndex >= 0 ? rowId(state.activeIndex) : undefined}
+          expanded={state.view.rowCount > 0}
+          inputRef={state.searchInputRef}
+          onQueryChange={state.setQuery}
+          onKeyDown={state.onSearchKeyDown}
+          dataTestId={dataTestId}
+        />
+        <PickerSheetList
+          view={state.view}
+          activeIndex={state.activeIndex}
+          cursorShown={state.cursorShown}
+          listId={listId}
+          rowId={rowId}
+          listRef={state.listRef}
+          createLabel={createLabel}
+          createMeta={createMeta}
+          emptyText={emptyText}
+          onChoose={state.choose}
+          dataTestId={dataTestId}
+        />
+        {foot ? (
+          <Box component="p" sx={footSx} data-testid={`${dataTestId}-foot`}>
+            {foot}
+          </Box>
+        ) : null}
+      </Box>
+    </PickerSheetSurface>
+  );
+}

package/src/components/form/PickerSheet/PickerSheet.types.ts

@@ -0,0 +1,64 @@
+/** One row of a {@link PickerSheetProps} list. */
+export interface PickerSheetItem {
+  /** Stable identity; what `onPick` receives. */
+  id: string;
+  /** The row's first line. */
+  label: string;
+  /** Second line, muted — a category's path, a price, a unit. */
+  meta?: string;
+  /**
+   * Tree depth, 0..n, drawn as left padding steps. Applies only while the query
+   * is empty: a search flattens the tree, and `meta` carries the path instead.
+   */
+  indent?: number;
+  /** The current value: a tinted row with a check mark at the right. */
+  selected?: boolean;
+  /**
+   * More text the query matches, beside the label (which always matches) —
+   * a path, synonyms. Defaults to `meta`.
+   */
+  searchText?: string;
+  /** A row that is not a thing to find ("None"): shown with an empty query only. */
+  hideWhileSearching?: boolean;
+}
+
+/**
+ * A searchable pick-or-create sheet. Every word it shows comes from the caller —
+ * the component ships no copy of its own.
+ */
+export interface PickerSheetProps {
+  open: boolean;
+  /** Esc, a tap outside and the close button. Picking does NOT call it; the caller closes. */
+  onClose: () => void;
+  /** Small muted line above the title. */
+  kicker?: string;
+  /** The dialog's name (`aria-labelledby`). */
+  title: string;
+  searchPlaceholder: string;
+  /** The search input's accessible name. */
+  searchLabel: string;
+  /** The close button's accessible name. */
+  closeLabel: string;
+  items: PickerSheetItem[];
+  /** Called with the picked item's id, and nothing else happens. */
+  onPick: (id: string) => void;
+  /**
+   * The create row's text. The row is offered last when the trimmed query
+   * matches no item LABEL exactly (case and accents aside), and only when `onCreate`
+   * is given too.
+   */
+  createLabel?: (query: string) => string;
+  /** A muted second line under the create row — what creating does ("Opens the quick form"). */
+  createMeta?: (query: string) => string;
+  /** Called with the trimmed query when the create row is chosen. */
+  onCreate?: (query: string) => void;
+  /** Shown instead of the list when nothing matches and there is no create row. */
+  emptyText?: (query: string) => string;
+  /** The note under the list. */
+  foot?: string;
+  /**
+   * Base test id (default `picker-sheet`). Sub-elements get `${id}-search`,
+   * `${id}-item-${item.id}`, `${id}-create`, `${id}-close`.
+   */
+  dataTestId?: string;
+}

package/src/components/form/PickerSheet/index.ts

@@ -0,0 +1,2 @@
+export { PickerSheet } from './PickerSheet';
+export type { PickerSheetItem, PickerSheetProps } from './PickerSheet.types';

package/src/components/form/PickerSheet/picker-sheet-model.ts

@@ -0,0 +1,63 @@
+import { foldText } from '../CategorySelect/category-tree';
+import type { PickerSheetItem } from './PickerSheet.types';
+
+/** What the list shows for a query: the matching items, and whether a create row follows them. */
+export interface PickerSheetView {
+  /** The trimmed query. */
+  query: string;
+  items: PickerSheetItem[];
+  /** True when the create row is offered as the last row. */
+  canCreate: boolean;
+  /** Rows the keyboard cursor walks: every matching item, plus the create row. */
+  rowCount: number;
+}
+
+/**
+ * The text an item is matched on, folded: its label always, then its
+ * `searchText` (or its meta line). The label is never left out, so a row whose
+ * label IS the query is always on screen — the create row it suppresses would
+ * otherwise leave the list empty.
+ */
+function haystack(item: PickerSheetItem): string {
+  return foldText(`${item.label} ${item.searchText ?? item.meta ?? ''}`);
+}
+
+/**
+ * Substring match, case and accents aside: "acai" finds "Açaí", as it does in
+ * `CategorySelect` — a hurried phone keyboard drops the accent, and a search
+ * that then finds nothing offers to create a duplicate. An empty query keeps
+ * everything but nothing hides.
+ */
+function filterPickerItems(items: PickerSheetItem[], query: string): PickerSheetItem[] {
+  const needle = foldText(query.trim());
+  if (!needle) return items;
+  return items.filter((item) => !item.hideWhileSearching && haystack(item).includes(needle));
+}
+
+/** True when some item's LABEL is the query, case and accents aside — creating it would duplicate it. */
+function hasExactLabel(items: PickerSheetItem[], query: string): boolean {
+  const needle = foldText(query.trim());
+  return items.some((item) => foldText(item.label.trim()) === needle);
+}
+
+/** The list for a query, and whether it ends in a create row. */
+export function pickerSheetView(
+  items: PickerSheetItem[],
+  rawQuery: string,
+  creatable: boolean,
+): PickerSheetView {
+  const query = rawQuery.trim();
+  const matches = filterPickerItems(items, query);
+  const canCreate = creatable && query.length > 0 && !hasExactLabel(items, query);
+  return { query, items: matches, canCreate, rowCount: matches.length + (canCreate ? 1 : 0) };
+}
+
+/**
+ * The keyboard cursor after an arrow key — the `Command` model: it wraps at
+ * both ends, and from "no row" Down lands on the first row and Up on the last.
+ */
+export function stepActiveIndex(current: number, delta: 1 | -1, rowCount: number): number {
+  if (rowCount === 0) return -1;
+  if (current < 0) return delta > 0 ? 0 : rowCount - 1;
+  return (current + delta + rowCount) % rowCount;
+}

package/src/components/form/PickerSheet/usePickerSheet.ts

@@ -0,0 +1,122 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { pickerSheetView, stepActiveIndex, type PickerSheetView } from './picker-sheet-model';
+import type { PickerSheetProps } from './PickerSheet.types';
+
+/** Everything the sheet's parts read: the query, the derived list, the cursor and the handlers. */
+interface PickerSheetState {
+  query: string;
+  view: PickerSheetView;
+  /** The keyboard cursor, an index into `view` (items, then the create row); -1 for none. Always a row that exists. */
+  activeIndex: number;
+  /** Draw the cursor: only once an arrow key has moved it, never from typing alone. */
+  cursorShown: boolean;
+  searchInputRef: React.RefObject<HTMLInputElement | null>;
+  listRef: React.RefObject<HTMLUListElement | null>;
+  setQuery: (next: string) => void;
+  /** Pick the row at `index` — an item, or the create row when it is the last one. */
+  choose: (index: number) => void;
+  onSearchKeyDown: (event: React.KeyboardEvent) => void;
+}
+
+type HookProps = Pick<PickerSheetProps, 'open' | 'items' | 'onPick' | 'onCreate' | 'createLabel'>;
+
+/**
+ * Bring the selected row into view on open, and keep the keyboard cursor in view.
+ *
+ * Nothing inside is focused on open — the modal focuses its own paper. Focusing
+ * the search box raised a phone's keyboard over the list it was opened to show.
+ * Deferred a frame: the surface mounts its content in the same commit as this
+ * effect.
+ */
+function useSheetScroll(
+  open: boolean,
+  activeIndex: number,
+  listRef: React.RefObject<HTMLUListElement | null>,
+): void {
+  useEffect(() => {
+    if (!open) return undefined;
+    const frame = requestAnimationFrame(() => {
+      listRef.current?.querySelector('[aria-selected="true"]')?.scrollIntoView?.({ block: 'nearest' });
+    });
+    return () => cancelAnimationFrame(frame);
+  }, [open, listRef]);
+
+  useEffect(() => {
+    if (activeIndex < 0) return;
+    const rows = listRef.current?.querySelectorAll('[role="option"]');
+    rows?.[activeIndex]?.scrollIntoView?.({ block: 'nearest' });
+  }, [activeIndex, listRef]);
+}
+
+/**
+ * The sheet's state. The query resets every time the sheet opens; typing puts
+ * the cursor on the first match, so "type, then Enter" picks it (or creates,
+ * when the create row is all there is).
+ */
+export function usePickerSheet({ open, items, onPick, onCreate, createLabel }: HookProps): PickerSheetState {
+  const [query, setRawQuery] = useState('');
+  const [rawActiveIndex, setActiveIndex] = useState(-1);
+  const [cursorShown, setCursorShown] = useState(false);
+  const searchInputRef = useRef<HTMLInputElement | null>(null);
+  const listRef = useRef<HTMLUListElement | null>(null);
+
+  // Reset while rendering the frame that opens the sheet, not in an effect
+  // after it — an effect would paint the last session's query for one frame.
+  const [wasOpen, setWasOpen] = useState(open);
+  if (open !== wasOpen) {
+    setWasOpen(open);
+    if (open) {
+      setRawQuery('');
+      setActiveIndex(-1);
+      setCursorShown(false);
+    }
+  }
+
+  const creatable = Boolean(onCreate && createLabel);
+  const view = useMemo(() => pickerSheetView(items, query, creatable), [items, query, creatable]);
+  // Clamped on read: the rows can shrink under the cursor (a query, new items),
+  // and `aria-activedescendant` must never name a row that is not there.
+  const activeIndex = rawActiveIndex < view.rowCount ? rawActiveIndex : -1;
+
+  useSheetScroll(open, activeIndex, listRef);
+
+  const setQuery = useCallback((next: string) => {
+    setRawQuery(next);
+    setActiveIndex(next.trim() ? 0 : -1);
+  }, []);
+
+  const choose = useCallback(
+    (index: number) => {
+      const item = view.items[index];
+      if (item) {
+        onPick(item.id);
+        return;
+      }
+      if (view.canCreate && index === view.items.length) onCreate?.(view.query);
+    },
+    [view, onPick, onCreate],
+  );
+
+  const onSearchKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+        event.preventDefault();
+        const delta = event.key === 'ArrowDown' ? 1 : -1;
+        setActiveIndex(stepActiveIndex(activeIndex, delta, view.rowCount));
+        setCursorShown(true);
+        return;
+      }
+      if (event.key === 'Enter' && activeIndex >= 0) {
+        event.preventDefault();
+        choose(activeIndex);
+      }
+      // Escape is the modal's: it closes through `onClose`, once.
+    },
+    [view.rowCount, activeIndex, choose],
+  );
+
+  return { query, view, activeIndex, cursorShown, searchInputRef, listRef, setQuery, choose, onSearchKeyDown };
+}

package/src/tokens/ink.ts

@@ -114,6 +114,14 @@ export const absoluteInk = (theme: Theme): { black: string; white: string } => (
 export const modeInk = (theme: Theme): string =>
   theme.palette.mode === 'dark' ? theme.palette.common.white : theme.palette.common.black;
 
+/**
+ * The well of a field that sits on a tinted panel: white in light mode, so the
+ * field reads as a field against the paper around it; the paper itself in dark
+ * mode, where white would glare.
+ */
+export const fieldWell = (theme: Theme): string =>
+  theme.palette.mode === 'dark' ? theme.palette.background.paper : theme.palette.common.white;
+
 /* ── Neutral tones over the grey ramp ─────────────────────────────────────── */
 
 const step = (theme: Theme, n: keyof typeof NEUTRAL_RAMP): string => theme.palette.grey[n] ?? NEUTRAL_RAMP[n];