@lotics/ui 6.4.0 → 7.0.0

package/AGENTS.md

@@ -7,7 +7,7 @@ open the file.** If the closest component lacks a capability, **extend it** (a p
 every app inherits), never inline a one-off `View`/`Text` rebuild — that forfeits the
 typeahead, async search, virtualization, and a11y the primitive already ships.
 
-- Import per module: `import { Combobox } from "@lotics/ui/combobox"`.
+- Import per module: `import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox"`.
 - Floating content (`Dialog` · `Popover` · `Tooltip` · `Alert` · `OptionList`) needs a
   `PortalHost` at the app root.
 - RN-Web only: `View`/`ScrollView` from `react-native`, the `Text` primitive (no raw
@@ -45,8 +45,9 @@ Pick by capability, not by name. (→ the source file for the API.)
   or `Select` (the rich one — custom-rendered options, single/multi, select-all). Search-as-you-type
   / async / create-new → `Combobox`. A selectable card row → `CardSelectItem`. For a SELECT-FIELD
   picker, render each option as its colored chip on `Select`
-  (`renderOptionContent={(o) => <OptionBadge value={o} />}`). `Select`/`Combobox` all open
-  the one shared `OptionList` body; `Picker` is the only one that's a native dropdown.
+  (`renderOptionContent={(o) => <OptionBadge value={o} />}`). `Select` opens the shared
+  `OptionList` body; `Combobox` is COMPOUND (`ComboboxInput` + `ComboboxContent`) over the same
+  `useOptionList` engine; `Picker` is the only one that's a native dropdown.
 - **Pick member(s)** — `MemberSelect` (a `Select` that renders each option as a `MemberChip`,
   single or multi) — the ready member picker; pass it the roster (`members={useMembers().members}`).
   Don't re-wire `Select` + `renderOptionContent` + a directory by hand. To edit a `select_member`
@@ -195,20 +196,38 @@ Past two columns the label→field link breaks — MANY inputs means GROUPING in
 wrap their OWN `FormField` (and omit `style`) — for a grid cell use a bare `FormField style={half}`
 wrapping `DatePicker`/`Picker`.
 
-### Find-or-create — `Combobox` IS the control
-`Combobox` is a SELECT by default (no leading icon, a trailing chevron); opt INTO the search-box
-look with `icon="search"` only when typing-to-search is primary (a large/remote set).
-`allowCustom` appends a "Create …" row (`customOptionLabel`) when the query matches no option,
-emitting the typed text as the value — so a value not in the known set means CREATE. Wire that
-branch to a create overlay (a modal `Dialog` for 4+ fields, an anchored popover for 1–3) that
-builds the new record and attaches it; existing matches attach directly. The create row sits
-BELOW matches by default (the keyboard highlight lands on the first MATCH, so Enter on a partial
-picks it, never a duplicate); pass `customOptionPlacement="top"` to pin it above. Use
+### Find-or-create — the `Combobox` family IS the control
+`Combobox` is COMPOUND: a root holds the DATA + behaviour (the shared `useOptionList` engine —
+`options`, `value`, `onValueChange`, `onSearchChange`, `allowCustom`, the per-row
+`getOptionDescription`/`renderOptionContent` so they're typed against the option `data`), and the
+parts render the CHROME, composed as children — never a render-prop pile:
+
+```tsx
+<Combobox options={hits} value={sel} onSearchChange={setQ} onValueChange={pick} allowCustom
+          customOptionLabel={(q) => `Create "${q}"`} getOptionDescription={(o) => o.data?.code}>
+  <ComboboxInput icon="search" clearable onClear={deselect} placeholder="Find or create…" />
+  <ComboboxContent recentsLabel="Recent">
+    <ComboboxEmpty>No match — type a name to create one</ComboboxEmpty>
+    <ComboboxFooter>{validity}</ComboboxFooter>
+  </ComboboxContent>
+</Combobox>
+```
+
+It's a SELECT by default (`ComboboxInput` with NO `icon` → a trailing chevron); opt INTO the
+search-box look with `ComboboxInput icon="search"` only when typing-to-search is primary (a
+large/remote set). `allowCustom` appends a "Create …" row (`customOptionLabel`) when the query
+matches no option, emitting the typed text as the value — so a value not in the known set means
+CREATE. Wire that branch to a create overlay (a modal `Dialog` for 4+ fields, an anchored popover
+for 1–3) that builds the new record and attaches it; existing matches attach directly. The create
+row sits BELOW matches by default (the keyboard highlight lands on the first MATCH, so Enter on a
+partial picks it, never a duplicate); pass `customOptionPlacement="top"` to pin it above. Use
 `reflectSelection={false}` and render the attached record below as a card with a Change action.
 For input-level status that must stay visible while results scroll (validity feedback on the typed
-value, a result count, a secondary "create" affordance), pass `footer={({ close }) => …}` — a pinned
-row below the listbox, OUTSIDE keyboard option-nav; call `close()` from a footer action that hands
-off elsewhere (so the popover dismisses cleanly instead of floating over what you navigated to).
+value, a result count, a secondary "create" affordance), drop a `ComboboxFooter` into the content —
+a pinned row below the listbox, OUTSIDE keyboard option-nav; call `useCombobox().close()` from a
+footer action that hands off elsewhere (so the popover dismisses cleanly instead of floating over
+what you navigated to). A `ComboboxEmpty` child gives the no-match state richer content than the
+`ComboboxContent emptyText` string.
 
 ### Line items — create → preview → edit (a composition, not a primitive)
 For a list of records you build then revise (invoice rows, repair lines, config entries), each
@@ -751,7 +770,7 @@ option_badge (OptionBadge — a select value as its configured colored badge) ·
 member_chip (MemberChip — avatar + name; the universal person render) ·
 member_select (MemberSelect — a Picker of MemberChip options; the member picker) ·
 status_badge · button · icon_button · link · text_link (TextLink — underlined text that's optionally an `onPress` action or an `href` link, or plain underlined text to wrap in your own pressable; the neutral counterpart to the fixed-blue `Link`) · chip · tabs · segmented_control ·
-picker (native `<select>`, plain label-only single) · select (Select — rich/custom-rendered, single/multi, select-all, chips via `renderSelected` + `searchable` + `allowCustom` — the tag field is just a multi Select; opens `OptionList`) · option_list (OptionList — the ONE shared searchable listbox body every selector opens: single/multi, optional internal search, create row, keyboard + native-`<select>` typeahead; host it directly in a `Popover`/`Dialog` for a command palette) · combobox (single-select editable search input; browses on focus; no `multi` — multi-value chips → `Select multi`) ·
+picker (native `<select>`, plain label-only single) · select (Select — rich/custom-rendered, single/multi, select-all, chips via `renderSelected` + `searchable` + `allowCustom` — the tag field is just a multi Select; opens `OptionList`) · option_list (OptionList — the ONE shared searchable listbox body every selector opens: single/multi, optional internal search, create row, keyboard + native-`<select>` typeahead; host it directly in a `Popover`/`Dialog` for a command palette) · combobox (COMPOUND single-select editable search: `Combobox` root + `ComboboxInput` + `ComboboxContent`, optional `ComboboxEmpty`/`ComboboxFooter`, `useCombobox()`; over the shared `useOptionList` engine; browses on focus; no `multi` — multi-value chips → `Select multi`) ·
 text_input_field · number_input · search_input · form_field · checkbox · checkbox_input · switch ·
 radio_picker · counter · range_slider · date_picker · date_range_filter_field · time_picker ·
 inline_text_input · inline_number_input · inline_select · inline_member_select · inline_date_picker ·

package/examples/tpl_dossier.tsx

@@ -23,7 +23,7 @@ import { ChipGroup } from "@lotics/ui/chip_group";
 import { FilterChip, selectSummary } from "@lotics/ui/filter_chip";
 import { OptionList } from "@lotics/ui/option_list";
 import { cycleSort, sortBy, type SortState } from "@lotics/ui/sort_header";
-import { Combobox } from "@lotics/ui/combobox";
+import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox";
 import type { PickerOption } from "@lotics/ui/picker";
 import { formatMoney } from "@lotics/ui/format_money";
 
@@ -222,15 +222,15 @@ function TaoHoSoForm() {
           </View>
           <FormField label="Customer">
             <Combobox
-              icon="search"
               options={CUSTOMER_OPTIONS}
               onValueChange={(opt) => setKhach(opt.label ?? opt.value)}
               allowCustom
               customOptionPlacement="top"
               customOptionLabel={(q) => `Create new customer “${q}”`}
-              placeholder="Search customers, or add a new one…"
-              accessibilityLabel="Customer"
-            />
+            >
+              <ComboboxInput icon="search" placeholder="Search customers, or add a new one…" accessibilityLabel="Customer" />
+              <ComboboxContent />
+            </Combobox>
           </FormField>
           <FormField label="Case fee">
             <NumberInput value={phi} onValueChange={setPhi} min={0} accessibilityLabel="Case fee" />

package/examples/tpl_order.tsx

@@ -10,7 +10,7 @@ import { Icon } from "@lotics/ui/icon";
 import { FormField } from "@lotics/ui/form_field";
 import { TextInputField } from "@lotics/ui/text_input_field";
 import { Picker } from "@lotics/ui/picker";
-import { Combobox } from "@lotics/ui/combobox";
+import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox";
 import type { PickerOption } from "@lotics/ui/picker";
 import { DatePicker } from "@lotics/ui/date_picker";
 import { NumberInput } from "@lotics/ui/number_input";
@@ -288,7 +288,6 @@ export function TplOrder() {
                   </View>
                 ) : null}
                 <Combobox
-                  icon="search"
                   options={customerOptions}
                   onValueChange={onPickCustomer}
                   getOptionDescription={(o) => (o.data ? `${o.data.code} · ${o.data.city}` : undefined)}
@@ -296,11 +295,11 @@ export function TplOrder() {
                   allowCustom
                   customOptionPlacement="top"
                   customOptionLabel={(q) => `Create new customer “${q}”`}
-                  placeholder="Search customers by name…"
-                  emptyText="No customer matches — type a name to create one"
-                  accessibilityLabel="Attach customer"
                   autoFocus={changing}
-                />
+                >
+                  <ComboboxInput icon="search" placeholder="Search customers by name…" accessibilityLabel="Attach customer" />
+                  <ComboboxContent emptyText="No customer matches — type a name to create one" />
+                </Combobox>
                 {!customer ? (
                   <Text size="xs" color="muted">
                     No match? Pick “Create new customer …” to add it without leaving this order.

package/examples/tpl_quick.tsx

@@ -9,7 +9,7 @@ import { Divider } from "@lotics/ui/divider";
 import { Icon, type IconName } from "@lotics/ui/icon";
 import { FormField } from "@lotics/ui/form_field";
 import { TextInputField } from "@lotics/ui/text_input_field";
-import { Combobox } from "@lotics/ui/combobox";
+import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox";
 import type { PickerOption } from "@lotics/ui/picker";
 import { SegmentedControl } from "@lotics/ui/segmented_control";
 import { Counter } from "@lotics/ui/counter";
@@ -122,9 +122,10 @@ export function TplQuick() {
                   value={contact}
                   onValueChange={setContact}
                   getOptionDescription={(o) => o.data?.company}
-                  placeholder="Select a contact"
-                  accessibilityLabel="Contact"
-                />
+                >
+                  <ComboboxInput placeholder="Select a contact" accessibilityLabel="Contact" />
+                  <ComboboxContent />
+                </Combobox>
               </FormField>
               <FormField label="Duration" style={{ flexGrow: 0, flexBasis: 180 }}>
                 <View style={{ minHeight: 40, justifyContent: "center" }}>

package/examples/tpl_ratedesk.tsx

@@ -6,7 +6,7 @@ import { Button } from "@lotics/ui/button";
 import { Badge } from "@lotics/ui/badge";
 import { Icon } from "@lotics/ui/icon";
 import { EmptyState } from "@lotics/ui/empty_state";
-import { Combobox } from "@lotics/ui/combobox";
+import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox";
 import { type PickerOption } from "@lotics/ui/picker";
 import { ColumnFilter, type FilterableColumn, type ColumnFilterValue } from "@lotics/ui/column_filter";
 import { FileDropzone } from "@lotics/ui/file_dropzone";
@@ -193,11 +193,17 @@ export function TplRatedesk() {
         <View style={{ flexDirection: "row", alignItems: "center", flexWrap: "wrap", gap: 8 }}>
           <View style={{ flexDirection: "row", alignItems: "center", gap: 6, flexGrow: 1, flexBasis: 360, minWidth: 280 }}>
             <View style={{ flex: 1, minWidth: 120 }}>
-              <Combobox icon="map-pin" options={originOpts} recentOptions={originOpts} recentsLabel="Origin" value={fromV} onValueChange={setFromV} clearable onClear={() => setFromV(null)} placeholder="From" accessibilityLabel="Origin port" />
+              <Combobox options={originOpts} recentOptions={originOpts} value={fromV} onValueChange={setFromV}>
+                <ComboboxInput icon="map-pin" clearable onClear={() => setFromV(null)} placeholder="From" accessibilityLabel="Origin port" />
+                <ComboboxContent recentsLabel="Origin" />
+              </Combobox>
             </View>
             <Icon name="arrow-right" size={14} color={colors.zinc[400]} />
             <View style={{ flex: 1, minWidth: 120 }}>
-              <Combobox icon="map-pin" options={destOpts} recentOptions={destOpts} recentsLabel="Destination" value={toV} onValueChange={setToV} clearable onClear={() => setToV(null)} placeholder="To" accessibilityLabel="Destination port" />
+              <Combobox options={destOpts} recentOptions={destOpts} value={toV} onValueChange={setToV}>
+                <ComboboxInput icon="map-pin" clearable onClear={() => setToV(null)} placeholder="To" accessibilityLabel="Destination port" />
+                <ComboboxContent recentsLabel="Destination" />
+              </Combobox>
             </View>
           </View>
           <ColumnFilter column={carrierCol} value={carrierF} onChange={setCarrierF} clearLabel="Clear carrier" />

package/examples/tpl_report.tsx

@@ -6,7 +6,7 @@ import { Badge } from "@lotics/ui/badge";
 import { Breakdown } from "@lotics/ui/breakdown";
 import { Button } from "@lotics/ui/button";
 import { Card, CardFooter, CardHeader, CardHeaderTitle } from "@lotics/ui/card";
-import { Combobox } from "@lotics/ui/combobox";
+import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox";
 import { type PickerOption } from "@lotics/ui/picker";
 import { DateRangeFilterField } from "@lotics/ui/date_range_filter_field";
 import { type DateFilterValue } from "@lotics/ui/date_filter";
@@ -400,14 +400,11 @@ function NamePicker(props: {
     <Combobox<string>
       options={options}
       value={selected ? { value: selected, label: selected } : null}
-      clearable
-      clearLabel={`Clear ${label}`}
-      onClear={() => onSelect(null)}
       onSearchChange={setQ}
       onValueChange={(opt) => onSelect(opt.value)}
-      placeholder={placeholder}
-      emptyText={`No ${label} matches`}
-      accessibilityLabel={`Search ${label}`}
-    />
+    >
+      <ComboboxInput clearable clearLabel={`Clear ${label}`} onClear={() => onSelect(null)} placeholder={placeholder} accessibilityLabel={`Search ${label}`} />
+      <ComboboxContent emptyText={`No ${label} matches`} />
+    </Combobox>
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "6.4.0",
+  "version": "7.0.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",

package/src/combobox.tsx

@@ -6,7 +6,17 @@ import {
   type ViewStyle,
   type TextInput as RNTextInput,
 } from "react-native";
-import { useCallback, useRef, useState, type ReactNode } from "react";
+import {
+  Children,
+  createContext,
+  isValidElement,
+  useCallback,
+  useContext,
+  useRef,
+  useState,
+  type ReactNode,
+  type RefObject,
+} from "react";
 import { colors } from "./colors";
 import { FOCUS_RING } from "./control_surface";
 import { useLoticsLocale } from "./locale";
@@ -18,7 +28,65 @@ import { ActivityIndicator } from "./activity_indicator";
 import { Popover, PopoverContent } from "./popover";
 import type { PickerOption } from "./picker";
 import { useDebouncedCallback } from "./use_debounced_callback";
-import { useOptionList } from "./use_option_list";
+import { useOptionList, type UseOptionList } from "./use_option_list";
+
+type KeyEvent = { nativeEvent: { key: string }; preventDefault: () => void };
+
+interface ComboboxContextValue {
+  /** The shared engine instance — the input drives its keyboard, the content
+   *  renders its rows, so both halves stay one source of truth. Typed loosely
+   *  here (React context can't be per-instance generic); `ComboboxContent` casts
+   *  it back to its own `<T, D>` at the rendering boundary. */
+  list: UseOptionList<string, unknown>;
+  /** The text shown in the input (a reflected selection or the live query). */
+  query: string;
+  open: boolean;
+  /** A dropdown is actually up (open AND it has something to show). The input's
+   *  focus ring and the popover both gate on this, never on `open` alone. */
+  showList: boolean;
+  loading: boolean;
+  disabled: boolean;
+  autoFocus: boolean;
+  /** `recentOptions` were supplied — so the idle list is recents (gets a heading),
+   *  not a plain browse of `options`. */
+  hasRecents: boolean;
+  /** Per-row renderers — typed against the root's `<T, D>`, widened to the loose
+   *  context shape; `ComboboxContent` invokes them on its (equally loose) rows. */
+  renderOptionContent?: (option: PickerOption<string, unknown>) => ReactNode;
+  getOptionDescription?: (option: PickerOption<string, unknown>) => string | undefined;
+  triggerRef: RefObject<View | null>;
+  inputRef: RefObject<RNTextInput | null>;
+  handleChangeText: (text: string) => void;
+  handleKeyPress: (e: KeyEvent) => void;
+  onInputFocus: () => void;
+  onInputBlur: () => void;
+  setOpen: (open: boolean) => void;
+  close: () => void;
+}
+
+const ComboboxContext = createContext<ComboboxContextValue | null>(null);
+
+/** Read the surrounding `Combobox`'s state from a part or its children — `close()`
+ *  to dismiss the popover (e.g. from a `ComboboxFooter` action that navigates
+ *  elsewhere), plus the live `query` / `open` / `searching` flags. Throws outside a
+ *  `Combobox`. */
+export function useCombobox(): {
+  close: () => void;
+  setOpen: (open: boolean) => void;
+  query: string;
+  open: boolean;
+  searching: boolean;
+} {
+  const ctx = useContext(ComboboxContext);
+  if (!ctx) throw new Error("useCombobox must be used inside a <Combobox>");
+  return {
+    close: ctx.close,
+    setOpen: ctx.setOpen,
+    query: ctx.query,
+    open: ctx.open,
+    searching: ctx.list.searching,
+  };
+}
 
 export interface ComboboxProps<T extends string = string, D = unknown> {
   /** Result options for the current query. With `onSearchChange` the consumer
@@ -33,16 +101,8 @@ export interface ComboboxProps<T extends string = string, D = unknown> {
   value?: PickerOption<T, D> | null;
   /** Reflect the picked label in the input (classic autocomplete). Default true.
    *  Set false to keep the input a pure search and render the selection yourself
-   *  (e.g. in a list below). For a multi-value CHIP field use `Select multi`
-   *  (its `renderSelected` returns a removable `Chip`). */
+   *  (e.g. in a list below). For a multi-value CHIP field use `Select multi`. */
   reflectSelection?: boolean;
-  /** Custom rendering of an option row in the dropdown. The input itself is a
-   *  plain text field (it can only show the label string) — to display a
-   *  selection with custom rendering, use `reflectSelection={false}` and render
-   *  the picked option yourself below. */
-  renderOptionContent?: (option: PickerOption<T, D>) => ReactNode;
-  /** Row subtitle pulled from the option (single-line, under the title). */
-  getOptionDescription?: (option: PickerOption<T, D>) => string | undefined;
   /** Accept free text: when the query matches no option, offer it as a custom
    *  value — `onValueChange` receives `{ value: query, label: query }`. */
   allowCustom?: boolean;
@@ -57,49 +117,46 @@ export interface ComboboxProps<T extends string = string, D = unknown> {
   customOptionPlacement?: "top" | "bottom";
   /** Shown — under a heading — when the input is focused but empty. */
   recentOptions?: PickerOption<T, D>[];
+  /** Rich row content (a colour-dot badge, a member chip). Falls back to the label.
+   *  Lives on the root so its `option` is typed against the inferred `<T, D>`. */
+  renderOptionContent?: (option: PickerOption<T, D>) => ReactNode;
+  /** A single-line subtitle under the label (e.g. a code or company). */
+  getOptionDescription?: (option: PickerOption<T, D>) => string | undefined;
   loading?: boolean;
   searchDebounceMs?: number;
-  /** Leading icon inside the input. OMIT (the default) for a SELECT — no leading
-   *  glyph, a trailing chevron — so a "pick a code/record" combobox reads as a
-   *  picker, not a free-text search box. Opt IN to the search-box look explicitly
-   *  with `icon="search"` (leading glyph, no chevron). */
-  icon?: IconName;
-  placeholder?: string;
-  recentsLabel?: string;
-  emptyText?: string;
-  /** A pinned row rendered at the bottom of the popover (below the results, outside
-   *  the scroll area) whenever the popover is open. For input-level status that must
-   *  stay visible while results scroll — validity feedback, a result count, a "create"
-   *  affordance. It sits OUTSIDE the listbox, so its content is auxiliary (not an
-   *  option) and never enters keyboard option-nav. Receives `close` to dismiss the
-   *  popover — call it from an action that navigates elsewhere. */
-  footer?: (api: { close: () => void }) => ReactNode;
-  accessibilityLabel?: string;
   disabled?: boolean;
-  /** Show an in-input clear ✕ whenever the input has text (a reflected selection
-   *  or a typed query). Pressing it empties the input, resets the search, and
-   *  fires `onClear` so the consumer can deselect. */
-  clearable?: boolean;
-  /** Fired when the clear ✕ is pressed (the input + search are reset first). */
-  onClear?: () => void;
-  /** Accessible label for the clear ✕ (default "Clear"). */
-  clearLabel?: string;
+  /** Focus the input (and open) on mount. */
   autoFocus?: boolean;
-  testID?: string;
+  /** The container View around the input + popover. */
   style?: StyleProp<ViewStyle>;
+  /** `ComboboxInput` then `ComboboxContent` (with optional `ComboboxEmpty` /
+   *  `ComboboxFooter` inside it). */
+  children: ReactNode;
 }
 
 /**
- * The ARIA combobox: an editable input whose typing drives a (debounced) search,
- * with results in a Popover listbox below. The input owns the keyboard (↑/↓ move
- * the active row, Enter selects, Esc closes) — not a button trigger; on an empty
- * field it browses the full set (or `recentOptions`). Shares the `useOptionList`
- * row model + nav with the rest of the kit's selectors.
+ * The ARIA combobox, composed: an editable `ComboboxInput` whose typing drives a
+ * (debounced) search, with results in a `ComboboxContent` popover listbox below.
+ * The input owns the keyboard (↑/↓ move the active row, Enter selects, Esc closes);
+ * on an empty field it browses the full set (or `recentOptions`).
  *
- * Selection display: the picked label reflects into the input (`reflectSelection`),
- * or set `reflectSelection={false}` to keep the input a pure search and render the
- * selection below yourself. For a "pick from a known list" control use `Picker`
- * (native, plain) or `Select` (rich/multi, or a chip box via `renderSelected`).
+ * The root holds the data + behaviour (the shared `useOptionList` engine, the
+ * selection, the open/query state) and provides it via context; the parts render
+ * the chrome — so per-row content, the empty state, recents and a footer are
+ * COMPOSED as children, not passed as a pile of render-props:
+ *
+ * ```tsx
+ * <Combobox options={hits} value={sel} onSearchChange={setQ} onValueChange={pick} allowCustom>
+ *   <ComboboxInput icon="search" clearable placeholder="Search…" />
+ *   <ComboboxContent recentsLabel="Recent" getOptionDescription={(o) => o.data?.code}>
+ *     <ComboboxEmpty>No matches — type a name to create one</ComboboxEmpty>
+ *     <ComboboxFooter>{validity}</ComboboxFooter>
+ *   </ComboboxContent>
+ * </Combobox>
+ * ```
+ *
+ * For a "pick from a known list" control use `Picker` (native, plain) or `Select`
+ * (rich/multi, or a chip box via `renderSelected`).
  */
 export function Combobox<T extends string = string, D = unknown>(props: ComboboxProps<T, D>) {
   const {
@@ -108,29 +165,19 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
     onSearchChange,
     value,
     reflectSelection = true,
-    renderOptionContent,
-    getOptionDescription,
     allowCustom = false,
     customOptionLabel,
     customOptionPlacement = "bottom",
     recentOptions,
+    renderOptionContent,
+    getOptionDescription,
     loading = false,
     searchDebounceMs = 200,
-    icon,
-    placeholder,
-    footer,
-    accessibilityLabel = "Results",
     disabled = false,
-    clearable = false,
-    onClear,
-    clearLabel,
     autoFocus = false,
-    testID,
     style,
+    children,
   } = props;
-  const loc = useLoticsLocale().optionList;
-  const emptyText = props.emptyText ?? loc.noResults;
-  const recentsLabel = props.recentsLabel ?? loc.recent;
 
   const single = value ?? null;
   const reflectedText = single ? (single.label ?? single.value) : "";
@@ -177,9 +224,9 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
     [onValueChange, isServer, debouncedSearch, onSearchChange, reflectSelection],
   );
 
-  // Dismiss the popover from the footer — drop focus too, mirroring the popover's
-  // own self-close (so the input's keyboard focus ring doesn't linger after a
-  // footer action hands off elsewhere).
+  // Dismiss the popover from a footer action — drop focus too, mirroring the
+  // popover's own self-close (so the input's keyboard focus ring doesn't linger
+  // after the action hands off elsewhere).
   const close = useCallback(() => {
     setOpen(false);
     inputRef.current?.blur();
@@ -208,7 +255,7 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
   );
 
   const handleKeyPress = useCallback(
-    (e: { nativeEvent: { key: string }; preventDefault: () => void }) => {
+    (e: KeyEvent) => {
       const key = e.nativeEvent.key;
       if (!open && (key === "ArrowDown" || key === "ArrowUp")) setOpen(true);
       if (list.handleKey(key)) e.preventDefault();
@@ -216,161 +263,292 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
     [open, list],
   );
 
+  const onInputFocus = useCallback(() => {
+    // A programmatic refocus right after a commit must not reopen the menu;
+    // consume the one-shot flag instead of opening.
+    if (suppressFocusOpenRef.current) {
+      suppressFocusOpenRef.current = false;
+      return;
+    }
+    if (!disabled) setOpen(true);
+  }, [disabled]);
+
+  const onInputBlur = useCallback(() => {
+    // Clear a flag the keyboard path left set (its refocus was a no-op, so
+    // onFocus never consumed it) — the next real focus opens normally.
+    suppressFocusOpenRef.current = false;
+  }, []);
+
   const showList = open && !disabled && (list.searching || list.rows.length > 0);
-  const showRecentsHeader = !list.searching && (recentOptions?.length ?? 0) > 0;
-  // Select mode (no leading icon): show a trailing chevron so the field reads as
-  // a picker, not a free-text search. The clear ✕ owns the right slot when
-  // present, so suppress the chevron then.
+
+  const ctx: ComboboxContextValue = {
+    // Boundary cast: the engine is generic per-instance, the context type is not.
+    // `ComboboxContent` casts back to its own `<T, D>` before touching rows.
+    list: list as unknown as UseOptionList<string, unknown>,
+    query,
+    open,
+    showList,
+    loading,
+    disabled,
+    autoFocus,
+    hasRecents: (recentOptions?.length ?? 0) > 0,
+    // Boundary casts: the renderers were type-checked against `<T, D>` on the root;
+    // the loose context invokes them on its loose rows.
+    renderOptionContent: renderOptionContent as
+      | ((o: PickerOption<string, unknown>) => ReactNode)
+      | undefined,
+    getOptionDescription: getOptionDescription as
+      | ((o: PickerOption<string, unknown>) => string | undefined)
+      | undefined,
+    triggerRef,
+    inputRef,
+    handleChangeText,
+    handleKeyPress,
+    onInputFocus,
+    onInputBlur,
+    setOpen,
+    close,
+  };
+
+  return (
+    <ComboboxContext.Provider value={ctx}>
+      <View style={style}>{children}</View>
+    </ComboboxContext.Provider>
+  );
+}
+
+function useComboboxContext(part: string): ComboboxContextValue {
+  const ctx = useContext(ComboboxContext);
+  if (!ctx) throw new Error(`<${part}> must be used inside a <Combobox>`);
+  return ctx;
+}
+
+export interface ComboboxInputProps {
+  /** Leading icon inside the input. OMIT (the default) for a SELECT — no leading
+   *  glyph, a trailing chevron — so a "pick a code/record" combobox reads as a
+   *  picker, not a free-text search box. Opt IN to the search-box look explicitly
+   *  with `icon="search"` (leading glyph, no chevron). */
+  icon?: IconName;
+  placeholder?: string;
+  /** Show an in-input clear ✕ whenever the input has text (a reflected selection
+   *  or a typed query). Pressing it empties the input, resets the search, and
+   *  fires `onClear` so the consumer can deselect. */
+  clearable?: boolean;
+  /** Fired when the clear ✕ is pressed (the input + search are reset first). */
+  onClear?: () => void;
+  /** Accessible label for the clear ✕ (default "Clear"). */
+  clearLabel?: string;
+  /** Accessible name for the combobox input (the `role="combobox"` control). */
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+/** The editable text field that drives the search and owns the keyboard. Keeps DOM
+ *  focus while the listbox is open (the ARIA combobox pattern — the active row is
+ *  wired via `aria-activedescendant`, never real focus). */
+export function ComboboxInput(props: ComboboxInputProps) {
+  const { icon, placeholder, clearable = false, onClear, clearLabel, accessibilityLabel, testID } = props;
+  const ctx = useComboboxContext("ComboboxInput");
+  // Select mode (no leading icon): a trailing chevron so the field reads as a
+  // picker, not a free-text search. The clear ✕ owns the right slot when present.
   const showChevron = !icon && !clearable;
 
   return (
-    <View style={style}>
-      <View ref={triggerRef}>
-        <TextInputField
-          ref={inputRef}
-          testID={testID}
-          icon={icon}
-          value={query}
-          clearable={clearable}
-          clearLabel={clearLabel}
-          onClear={onClear}
-          onChangeText={handleChangeText}
-          onFocus={() => {
-            // A programmatic refocus right after a commit must not reopen the
-            // menu; consume the one-shot flag instead of opening.
-            if (suppressFocusOpenRef.current) {
-              suppressFocusOpenRef.current = false;
-              return;
-            }
-            if (!disabled) setOpen(true);
-          }}
-          onBlur={() => {
-            // Clear a flag the keyboard path left set (its refocus was a no-op,
-            // so onFocus never consumed it) — the next real focus opens normally.
-            suppressFocusOpenRef.current = false;
-          }}
-          onKeyPress={handleKeyPress}
-          placeholder={placeholder}
-          placeholderTextColor={colors.zinc["400"]}
-          editable={!disabled}
-          autoFocus={autoFocus}
-          autoCapitalize="none"
-          autoCorrect={false}
-          style={[
-            showChevron ? styles.selectInput : undefined,
-            // Gate on `showList`, not `open`: an empty query with no options has
-            // `open=true` but renders NO dropdown, so a ring tied to `open` would
-            // show with nothing below it AND linger after blur (no popover fires a
-            // close). The ring must mean "a dropdown is up".
-            showList ? styles.openRing : undefined,
-          ]}
-          role="combobox"
-          aria-expanded={showList}
-          aria-controls={list.listboxId}
-          aria-activedescendant={showList ? list.activeId : undefined}
-          aria-autocomplete="list"
-        />
-        {showChevron ? (
-          <View style={styles.chevron}>
-            <Icon name="chevrons-up-down" size={16} color={colors.zinc["400"]} />
-          </View>
-        ) : null}
-      </View>
-      <Popover
-        open={showList}
-        onOpenChange={(next) => {
-          setOpen(next);
-          // An outside dismiss closes the menu but leaves the textbox focused, so
-          // the input's keyboard focus ring would linger. Drop focus when the
-          // popover closes ITSELF — a commit refocuses through its own path
-          // (`commit` sets `open` directly), never through `onOpenChange`.
-          if (!next) inputRef.current?.blur();
-        }}
-        triggerRef={triggerRef}
-        side="bottom"
-        align="start"
-        offset={4}
-        inheritTriggerWidth
-      >
-        <PopoverContent manageFocus={false} disableBodyScroll testID={testID ? `${testID}-popover` : undefined}>
-          <View style={styles.menu}>
-            {showRecentsHeader ? (
-              <View style={styles.sectionHeader}>
-                <Text size="xs" weight="medium" color="zinc-500">
-                  {recentsLabel}
-                </Text>
+    <View ref={ctx.triggerRef}>
+      <TextInputField
+        ref={ctx.inputRef}
+        testID={testID}
+        icon={icon}
+        value={ctx.query}
+        clearable={clearable}
+        clearLabel={clearLabel}
+        onClear={onClear}
+        onChangeText={ctx.handleChangeText}
+        onFocus={ctx.onInputFocus}
+        onBlur={ctx.onInputBlur}
+        onKeyPress={ctx.handleKeyPress}
+        placeholder={placeholder}
+        placeholderTextColor={colors.zinc["400"]}
+        editable={!ctx.disabled}
+        autoFocus={ctx.autoFocus}
+        autoCapitalize="none"
+        autoCorrect={false}
+        accessibilityLabel={accessibilityLabel}
+        style={[
+          showChevron ? styles.selectInput : undefined,
+          // Gate on `showList`, not `open`: an empty query with no options has
+          // `open=true` but renders NO dropdown, so a ring tied to `open` would
+          // show with nothing below it AND linger after blur (no popover fires a
+          // close). The ring must mean "a dropdown is up".
+          ctx.showList ? styles.openRing : undefined,
+        ]}
+        role="combobox"
+        aria-expanded={ctx.showList}
+        aria-controls={ctx.list.listboxId}
+        aria-activedescendant={ctx.showList ? ctx.list.activeId : undefined}
+        aria-autocomplete="list"
+      />
+      {showChevron ? (
+        <View style={styles.chevron}>
+          <Icon name="chevrons-up-down" size={16} color={colors.zinc["400"]} />
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+export interface ComboboxContentProps {
+  /** Heading over the idle list when `recentOptions` were supplied. */
+  recentsLabel?: string;
+  /** Shown when a non-empty query matches nothing. A `<ComboboxEmpty>` child wins
+   *  over this string. */
+  emptyText?: string;
+  /** Accessible name for the listbox. */
+  accessibilityLabel?: string;
+  testID?: string;
+  /** Optional `ComboboxEmpty` / `ComboboxFooter`. */
+  children?: ReactNode;
+}
+
+/** The popover body: an optional recents heading, the keyboard-navigable row list
+ *  (from the root's `options`, rendered via the root's `renderOptionContent` /
+ *  `getOptionDescription`), then any `ComboboxFooter`. A `ComboboxEmpty` child
+ *  replaces the default empty text. */
+export function ComboboxContent(props: ComboboxContentProps) {
+  const { accessibilityLabel, testID, children } = props;
+  const ctx = useComboboxContext("ComboboxContent");
+  const loc = useLoticsLocale().optionList;
+  const emptyText = props.emptyText ?? loc.noResults;
+  const recentsLabel = props.recentsLabel ?? loc.recent;
+  const { list, renderOptionContent, getOptionDescription } = ctx;
+
+  // Pull the optional slots out of children — `ComboboxEmpty` replaces the default
+  // empty state, `ComboboxFooter` pins below the scroll.
+  let emptyEl: ReactNode = null;
+  let footerEl: ReactNode = null;
+  Children.forEach(children, (child) => {
+    if (!isValidElement(child)) return;
+    if (child.type === ComboboxEmpty) emptyEl = child;
+    else if (child.type === ComboboxFooter) footerEl = child;
+  });
+
+  const showRecentsHeader = !list.searching && ctx.hasRecents;
+  const isEmpty = !ctx.loading && list.rows.length === 0;
+
+  return (
+    <Popover
+      open={ctx.showList}
+      onOpenChange={(next) => {
+        ctx.setOpen(next);
+        // An outside dismiss closes the menu but leaves the textbox focused, so
+        // the input's keyboard focus ring would linger. Drop focus when the
+        // popover closes ITSELF — a commit refocuses through its own path (the
+        // root sets `open` directly), never through `onOpenChange`.
+        if (!next) ctx.inputRef.current?.blur();
+      }}
+      triggerRef={ctx.triggerRef}
+      side="bottom"
+      align="start"
+      offset={4}
+      inheritTriggerWidth
+    >
+      <PopoverContent manageFocus={false} disableBodyScroll testID={testID}>
+        <View style={styles.menu}>
+          {showRecentsHeader ? (
+            <View style={styles.sectionHeader}>
+              <Text size="xs" weight="medium" color="zinc-500">
+                {recentsLabel}
+              </Text>
+            </View>
+          ) : null}
+          <ScrollView
+            ref={list.scrollRef}
+            style={styles.scroll}
+            nativeID={list.listboxId}
+            accessibilityLabel={accessibilityLabel ?? (list.searching ? undefined : recentsLabel)}
+            keyboardShouldPersistTaps="handled"
+            role={"listbox" as "list"}
+          >
+            {ctx.loading ? (
+              <View style={styles.statusRow}>
+                <ActivityIndicator />
               </View>
-            ) : null}
-            <ScrollView
-              ref={list.scrollRef}
-              style={styles.scroll}
-              nativeID={list.listboxId}
-              accessibilityLabel={list.searching ? accessibilityLabel : recentsLabel}
-              keyboardShouldPersistTaps="handled"
-              role={"listbox" as "list"}
-            >
-              {loading ? (
-                <View style={styles.statusRow}>
-                  <ActivityIndicator />
-                </View>
-              ) : list.rows.length === 0 ? (
-                list.searching ? (
+            ) : isEmpty ? (
+              // Idle with nothing to show renders no empty row (an empty SELECT
+              // browse); only a non-matching SEARCH gets the empty state.
+              list.searching ? (
+                emptyEl ?? (
                   <View style={styles.statusRow}>
                     <Text size="sm" color="zinc-500">
                       {emptyText}
                     </Text>
                   </View>
-                ) : null
-              ) : (
-                list.rows.map((row) => {
-                  const isCustom = row.kind === "custom";
-                  const opt = row.option;
-                  const desc = !isCustom ? getOptionDescription?.(opt) : undefined;
-                  const label = opt.label ?? opt.value;
-                  const title =
-                    !isCustom && renderOptionContent ? (
-                      renderOptionContent(opt)
-                    ) : desc ? (
-                      <View>
-                        <Text userSelect="none" numberOfLines={1}>
-                          {label}
-                        </Text>
-                        <Text size="xs" color="zinc-500" numberOfLines={1}>
-                          {desc}
-                        </Text>
-                      </View>
-                    ) : (
-                      <Text userSelect="none" numberOfLines={1} weight={isCustom ? "medium" : undefined}>
+                )
+              ) : null
+            ) : (
+              list.rows.map((row) => {
+                const isCustom = row.kind === "custom";
+                const opt = row.option;
+                const desc = !isCustom ? getOptionDescription?.(opt) : undefined;
+                const label = opt.label ?? opt.value;
+                const title =
+                  !isCustom && renderOptionContent ? (
+                    renderOptionContent(opt)
+                  ) : desc ? (
+                    <View>
+                      <Text userSelect="none" numberOfLines={1}>
                         {label}
                       </Text>
-                    );
-                  return (
-                    <MenuButton
-                      key={`${row.kind}-${opt.value}`}
-                      nativeID={row.nativeID}
-                      testID={isCustom ? "combobox-custom-option" : `combobox-option-${opt.value}`}
-                      role="option"
-                      accessibilityLabel={label}
-                      icon={isCustom ? <Icon name="plus" size={16} color={colors.zinc["600"]} /> : undefined}
-                      title={title}
-                      focused={row.index === list.activeIndex}
-                      selected={row.selected}
-                      disabled={opt.disabled}
-                      onPress={() => list.pickRow(row.index)}
-                      onHoverIn={() => list.setActiveIndex(row.index, false)}
-                    />
+                      <Text size="xs" color="zinc-500" numberOfLines={1}>
+                        {desc}
+                      </Text>
+                    </View>
+                  ) : (
+                    <Text userSelect="none" numberOfLines={1} weight={isCustom ? "medium" : undefined}>
+                      {label}
+                    </Text>
                   );
-                })
-              )}
-            </ScrollView>
-            {footer ? <View style={styles.footer}>{footer({ close })}</View> : null}
-          </View>
-        </PopoverContent>
-      </Popover>
-    </View>
+                return (
+                  <MenuButton
+                    key={`${row.kind}-${opt.value}`}
+                    nativeID={row.nativeID}
+                    testID={isCustom ? "combobox-custom-option" : `combobox-option-${opt.value}`}
+                    role="option"
+                    accessibilityLabel={label}
+                    icon={isCustom ? <Icon name="plus" size={16} color={colors.zinc["600"]} /> : undefined}
+                    title={title}
+                    focused={row.index === list.activeIndex}
+                    selected={row.selected}
+                    disabled={opt.disabled}
+                    onPress={() => list.pickRow(row.index)}
+                    onHoverIn={() => list.setActiveIndex(row.index, false)}
+                  />
+                );
+              })
+            )}
+          </ScrollView>
+          {footerEl}
+        </View>
+      </PopoverContent>
+    </Popover>
   );
 }
 
+/** A richer empty state for `ComboboxContent` — used INSTEAD of its `emptyText`
+ *  string. Renders only when a non-empty query matches nothing. */
+export function ComboboxEmpty(props: { children: ReactNode }) {
+  return <View style={styles.statusRow}>{props.children}</View>;
+}
+
+/** A pinned row at the bottom of the popover (below the results, outside the
+ *  scroll) — input-level status that stays visible while results scroll: validity
+ *  feedback, a result count, a create affordance. It sits OUTSIDE the listbox, so
+ *  its content is auxiliary (never an option, never in keyboard option-nav). Call
+ *  `useCombobox().close()` from an action that hands off elsewhere. */
+export function ComboboxFooter(props: { children: ReactNode }) {
+  return <View style={styles.footer}>{props.children}</View>;
+}
+
 const styles = StyleSheet.create({
   openRing: {
     boxShadow: FOCUS_RING,