panelui-native 0.86.1 → 0.88.0

package/src/components/search-bar/index.tsx

@@ -1,13 +1,80 @@
 /**
  * SearchBar — a text field for querying a list, with the two controls a search
- * needs and an ordinary field does not.
+ * needs and an ordinary field does not, and a panel of results that opens out
+ * of the field itself.
  *
  * ```tsx
  * <SearchBar placeholder="Search orders" onSubmit={run} />
  * <SearchBar variant="filled" shape="pill" cancel="focus" />
- * <SearchBar debounce={250} onDebouncedChange={filter} loading={pending} />
+ * <SearchBar avoidKeyboard value={query} onChangeText={setQuery}>
+ *   <SearchBar.Section label="Suggested">
+ *     <SearchBar.Item trailing={<AddButton />} onPress={add}>Claude</SearchBar.Item>
+ *   </SearchBar.Section>
+ * </SearchBar>
  * ```
  *
+ * ## The results are above the field, and the field is above the keyboard
+ *
+ * A search that is being typed into has a keyboard under it, and a list drawn
+ * below the field is a list drawn behind the keyboard. So `avoidKeyboard`
+ * lifts the field until it sits `keyboardOffset` points clear of the keyboard's
+ * top edge, and the panel opens *upward* out of it into the space that is
+ * actually free.
+ *
+ * That puts the first result nearest the field and the last one furthest away,
+ * which is the order a reader walking away from the caret expects. Pass
+ * `panelPlacement="bottom"` for a search bar in a header, where the space is
+ * the other way round.
+ *
+ * The panel is positioned absolutely rather than laid out in the flow, so
+ * opening it never moves the page underneath — a list that pushes the field it
+ * belongs to is a field that walks away from the finger typing into it.
+ *
+ * ## Touches inside the panel must not close the keyboard
+ *
+ * The panel scrolls with `keyboardShouldPersistTaps="always"`, and every press
+ * inside it holds the field's focus open for a moment afterwards. Both are
+ * needed, because a search closes the instant the field blurs and there are
+ * two separate ways for a touch in the panel to blur it.
+ *
+ * `"handled"` only spares presses a child takes responsibility for, which
+ * leaves the panel's own padding, the gaps between rows, a section heading and
+ * the whole of `SearchBar.Status` as live dismiss surfaces — tapping the word
+ * "Searching …" would end the search. `"always"` gives the panel back.
+ *
+ * The focus guard covers the other way: a control inside a row — an add
+ * button, a remove ✕ — takes focus with the press on Android, and returning it
+ * a frame later is not enough on its own, because the blur has already closed
+ * the panel the control was drawn in. So a press in the panel marks the field
+ * as still being used, and a blur arriving under that mark is answered by
+ * asking for focus back rather than by ending the search.
+ *
+ * That guard only knows about presses that go through this component's own
+ * parts, and a caller's `Pressable` in a row's `trailing` slot takes the touch
+ * itself. So the panel also waits before believing any blur, and asks the
+ * keyboard: it is still up, because nothing in the panel dismisses it, and a
+ * search whose keyboard is still up has not ended. Focus goes back instead.
+ *
+ * ## The space kept for the field is not a target
+ *
+ * The card is one box around the results *and* the field, so it carries a
+ * spacer where the field sits. That spacer is a plain view drawn over a
+ * focused field, and a touch on a plain view is the platform's cue to dismiss
+ * the keyboard — so winning one blurred the field and closed the panel drawn
+ * out of that focus. Tapping the search box shut the results, which is exactly
+ * backwards. The card and its spacer take no touches at all now.
+ *
+ * ## What has already been picked goes in the field
+ *
+ * `tokens` puts the choices made so far inside the field, before the caret, so
+ * the query and what it has produced are one control rather than a control and
+ * a list somewhere above it. `SearchBar.Token` is the chip; backspace on an
+ * empty field fires `onRemoveLastToken`, which is what a token field does
+ * everywhere else.
+ *
+ * They scroll rather than wrap: the field is one line tall, and a row of chips
+ * that grew it would move the caret every time something was picked.
+ *
  * ## The clear button, and why it is not the platform's
  *
  * A ✕ appears inside the field as soon as there is something to clear, and
@@ -44,29 +111,47 @@
  * a return key is somebody saying they are done waiting.
  */
 import {
+  Children,
+  createContext,
   forwardRef,
+  isValidElement,
+  useContext,
   useCallback,
   useEffect,
   useImperativeHandle,
+  useMemo,
   useRef,
   useState,
   type ReactNode,
 } from 'react';
 import {
+  ScrollView,
+  StyleSheet,
   View,
+  useWindowDimensions,
   type LayoutChangeEvent,
   type NativeSyntheticEvent,
   type TextInput,
+  type TextInputKeyPressEventData,
   type TextInputSubmitEditingEventData,
+  type ViewProps,
+  type ViewStyle,
 } from 'react-native';
 import Animated, {
+  FadeIn,
+  FadeOut,
   useAnimatedStyle,
   useSharedValue,
   withTiming,
 } from 'react-native-reanimated';
 import { tv, type VariantProps } from 'tailwind-variants';
+import { useKeyboard } from '../../hooks/use-keyboard';
 import { SearchIcon, XIcon } from '../../icons';
-import { AnimatedPressable } from '../../primitives/animated-pressable';
+import {
+  AnimatedPressable,
+  type AnimatedPressableProps,
+} from '../../primitives/animated-pressable';
+import { KeyboardAvoider } from '../../primitives/keyboard-avoider';
 import { Text } from '../../primitives/text';
 import { Input, type InputProps } from '../input';
 import { Spinner } from '../spinner';
@@ -89,10 +174,123 @@ const CANCEL_GAP = 8;
  */
 const CLEAR_HIT_SLOP = 12;
 
+/** The panel's crossfade, matching every other anchored list in the library. */
+const PANEL_IN = 140;
+const PANEL_OUT = 120;
+
+/** Gap left between the panel's far edge and the edge of the screen. */
+const PANEL_EDGE_GAP = 24;
+
+/** Floor for the derived height — below this a list is not worth opening. */
+const PANEL_MIN_HEIGHT = 160;
+
+/**
+ * Ceiling for the derived height, in points. About six rows and a heading.
+ *
+ * The room above a lifted field is most of the screen, and a panel that takes
+ * all of it is a full-screen list that happens to have a search box under it —
+ * the page it was opened over stops being visible, so the search stops reading
+ * as something laid over the app. Past this the results scroll, which is what
+ * a long list should do anyway.
+ *
+ * `panelMaxHeight` overrides it for a screen that really is nothing but the
+ * search.
+ */
+const PANEL_MAX_HEIGHT = 320;
+
+/**
+ * The field's height per size, matching `Input`'s own `h-10 / h-12 / h-14`.
+ *
+ * It is the fallback for the slot the panel keeps for the field, which is
+ * otherwise the measured height and therefore zero on the frame the panel
+ * first opens. A zero slot puts the card's bottom edge at the field's, so the
+ * last row is drawn underneath the field — which is painted after the card and
+ * takes the touch. The press then reads as a tap on the input.
+ */
+const FIELD_HEIGHT = { sm: 40, md: 48, lg: 56 } as const;
+
+/**
+ * How long a press inside the panel keeps the field's focus. Long enough to
+ * cover the blur Android sends with the press and the re-render that follows
+ * it, short enough that a real dismissal is never held open.
+ */
+const FOCUS_GUARD = 400;
+
+/**
+ * How long the panel waits after a blur before believing the search is over.
+ *
+ * The guard above only covers presses that go through this component's own
+ * parts. A caller's own `Pressable` in a row's `trailing` slot takes the touch
+ * itself and this component never hears about it — so the catch-all is the
+ * keyboard: it is still up, because nothing in the panel dismisses it, and a
+ * search whose keyboard is still up has not ended. The pause is long enough
+ * for focus to come back on its own and short enough that a real dismissal
+ * does not leave the panel hanging.
+ */
+const BLUR_GRACE = 220;
+
+/** Share of the field a row of tokens may take before it starts scrolling. */
+const TOKEN_MAX_SHARE = 0.6;
+
+/*
+ * The card is pinned to the edge of the field's own slot and grows away from
+ * it, so the field's box is the one thing that never moves.
+ */
+const CARD_ABOVE: ViewStyle = { position: 'absolute', bottom: 0, left: 0, right: 0 };
+const CARD_BELOW: ViewStyle = { position: 'absolute', top: 0, left: 0, right: 0 };
+
+/*
+ * `zIndex` *and* `elevation`, on the field's own box rather than on the card:
+ * Android draws siblings in tree order and takes its stacking from elevation,
+ * so a card overlapping the content above the field would otherwise be painted
+ * under it — and putting it here keeps the field painting over the card, which
+ * is what lets the two be one surface.
+ *
+ * Applied always, and never toggled. React Native implements `zIndex` on iOS
+ * by reordering the parent's subviews, which takes the view out of the
+ * hierarchy and puts it back — and a `UITextField` removed from the window
+ * resigns first responder. Setting this at the moment the panel opens
+ * therefore blurred the field that had just been focused, which closed the
+ * panel again: the keyboard came up and went straight back down, and the only
+ * way to get a search open was to be quicker than the render.
+ *
+ * A constant stacking order costs nothing while the panel is shut — there is
+ * nothing to stack against — and the elevation draws no shadow, because the
+ * box has no background for Android to cast one from.
+ */
+const RAISED: ViewStyle = { zIndex: 20, elevation: 20 };
+
 const searchBarVariants = tv({
   slots: {
     row: 'w-full flex-row items-center',
+    /*
+     * The box the panel is positioned against — the field alone, so the panel
+     * is the field's width rather than the row's and does not run out under a
+     * Cancel button that is only sometimes there.
+     */
+    anchor: 'relative',
     field: '',
+    /*
+     * One card around the results *and* the field, with the field drawn over
+     * the space kept for it at the bottom.
+     *
+     * It has to be one box because the outline is one outline. Drawn as two —
+     * a bordered panel above a bordered field — the field's edge is the focus
+     * ring, since a field with a panel open is a field being typed into, and
+     * the card ends up with a brighter box welded to a dimmer one.
+     *
+     * `bg-popover`, not `bg-card`: this floats over the page rather than
+     * sitting in it, and a card is one step from the background — close enough
+     * that in dark mode the whole thing dissolves into the screen behind it.
+     */
+    panel: 'overflow-hidden rounded-2xl border border-border bg-popover shadow-lg',
+    panelList: 'p-1.5',
+    /** The hairline between the results and the field. */
+    panelDivider: 'w-full bg-border',
+    sectionLabel: 'px-3 pb-1 pt-2 text-sm text-muted-foreground',
+    item: 'flex-row items-center gap-3 rounded-lg px-3 py-2.5',
+    itemLabel: 'flex-1 text-base text-foreground',
+    status: 'flex-row items-center justify-center gap-2 px-3 py-8',
     // Clipped, because this is what the Cancel button is revealed out of: the
     // button keeps its measured width and the container's grows past it.
     //
@@ -103,12 +301,39 @@ const searchBarVariants = tv({
     cancelButton: 'absolute bottom-0 end-0 top-0 items-center justify-center ps-2',
     cancelLabel: 'font-medium text-primary',
     clear: 'items-center justify-center rounded-full',
+    /*
+     * The chips sit in the field's start content, which `Input` measures and
+     * turns into padding on the text — so the caret starts after them however
+     * many there are, and nothing typed ever runs underneath them.
+     */
+    tokenRow: 'flex-row items-center gap-1.5',
+    token: 'flex-row items-center gap-1 rounded-full bg-accent ps-2 pe-1',
+    tokenLabel: 'text-accent-foreground',
+    tokenRemove: 'items-center justify-center rounded-full',
   },
   variants: {
     size: {
-      sm: { cancelLabel: 'text-[14px]', clear: 'h-6 w-6' },
-      md: { cancelLabel: 'text-[16px]', clear: 'h-6 w-6' },
-      lg: { cancelLabel: 'text-[16px]', clear: 'h-7 w-7' },
+      sm: {
+        cancelLabel: 'text-[14px]',
+        clear: 'h-6 w-6',
+        token: 'h-6',
+        tokenLabel: 'text-[13px]',
+        tokenRemove: 'h-4 w-4',
+      },
+      md: {
+        cancelLabel: 'text-[16px]',
+        clear: 'h-6 w-6',
+        token: 'h-7',
+        tokenLabel: 'text-[14px]',
+        tokenRemove: 'h-5 w-5',
+      },
+      lg: {
+        cancelLabel: 'text-[16px]',
+        clear: 'h-7 w-7',
+        token: 'h-8',
+        tokenLabel: 'text-[15px]',
+        tokenRemove: 'h-5 w-5',
+      },
     },
     /**
      * The field's corner. `pill` is the shape a search field takes when it is
@@ -119,10 +344,24 @@ const searchBarVariants = tv({
       rounded: { field: '' },
       pill: { field: 'rounded-full' },
     },
+    /**
+     * Which edge of the field the card grows out of. The field's corners on
+     * that edge go square and its border comes off entirely — the card around
+     * both of them is what draws the edge.
+     */
+    attached: {
+      none: {},
+      top: { field: 'rounded-t-none rounded-b-2xl border-0' },
+      bottom: { field: 'rounded-b-none rounded-t-2xl border-0' },
+    },
+    selected: {
+      true: { item: 'bg-accent' },
+    },
   },
   defaultVariants: {
     size: 'md',
     shape: 'rounded',
+    attached: 'none',
   },
 });
 
@@ -131,21 +370,47 @@ type SearchBarVariantProps = VariantProps<typeof searchBarVariants>;
 /** Glyph sizes per field size — the icon tracks the text, not the box. */
 const ICON_SIZE = { sm: 16, md: 18, lg: 20 } as const;
 
+interface SearchBarContextValue {
+  /** The field's size, so a chip drawn in it matches the text beside it. */
+  size: NonNullable<SearchBarVariantProps['size']>;
+  /**
+   * Marks the field as still in use and asks for focus back. Called by
+   * anything pressable the panel or the field contains, before the press has
+   * had a chance to blur the field and close the search around it.
+   */
+  retainFocus: () => void;
+}
+
+const SearchBarContext = createContext<SearchBarContextValue | null>(null);
+
+/** Where the results open. */
+export type SearchBarPanelPlacement = 'top' | 'bottom';
+
+/** When the results are shown. */
+export type SearchBarPanelMode = 'never' | 'focus' | 'always';
+
 /**
  * What SearchBar takes from Input, minus everything it owns itself. The form
  * furniture is dropped along with it: a label and an error line stack above
  * and below the field, and Cancel sits beside the whole stack rather than
  * beside the field it belongs to. Use `Field` for a search that is one answer
  * in a form.
+ *
+ * The keyboard props go too. Input's would move the field and leave the Cancel
+ * button and the panel where they were; SearchBar lifts all three together.
  */
 type InheritedInputProps = Omit<
   InputProps,
+  | 'avoidKeyboard'
   | 'defaultValue'
   | 'description'
   | 'endContent'
   | 'errorMessage'
   | 'interactiveContent'
   | 'isRequired'
+  | 'keyboardBottomInset'
+  | 'keyboardMode'
+  | 'keyboardOffset'
   | 'label'
   | 'multiline'
   | 'onChangeText'
@@ -154,7 +419,9 @@ type InheritedInputProps = Omit<
   | 'value'
 >;
 
-export interface SearchBarProps extends InheritedInputProps, SearchBarVariantProps {
+export interface SearchBarProps
+  extends InheritedInputProps,
+    Omit<SearchBarVariantProps, 'attached' | 'selected'> {
   /**
    * The field's background, from `Input`. `outline` draws its own edge, for a
    * search bar sitting on the page; `filled` drops it, for one inside a card
@@ -202,9 +469,58 @@ export interface SearchBarProps extends InheritedInputProps, SearchBarVariantPro
   loading?: boolean;
   /** The leading glyph, for a search over something with a symbol of its own. */
   icon?: ReactNode;
+  /**
+   * Lift the whole search — field, Cancel button and panel — until it sits
+   * clear of the software keyboard, and put it back on blur. Without it the
+   * field stays where the page left it, which on most screens is behind the
+   * keyboard it just opened.
+   *
+   * Install `react-native-keyboard-controller` for this to behave on Android.
+   *
+   * Do not toggle it at runtime: it changes which component wraps the row, so
+   * the field would remount and lose focus.
+   */
+  avoidKeyboard?: boolean;
+  /** Gap kept between the field's bottom edge and the keyboard. */
+  keyboardOffset?: number;
+  /**
+   * When the results panel is shown. `focus` opens it while the field is being
+   * typed into, `always` keeps it out for a screen that is nothing but the
+   * search, `never` ignores the children entirely.
+   */
+  panel?: SearchBarPanelMode;
+  /**
+   * Which side of the field the panel opens out of. `top` is the default,
+   * because the space under a focused field belongs to the keyboard.
+   */
+  panelPlacement?: SearchBarPanelPlacement;
+  /**
+   * Cap on the panel's height, in points.
+   *
+   * The panel takes the smaller of this and the room between the field and the
+   * edge of the screen, so it never runs off the top of the display. Unset, it
+   * is capped at about six rows: the space above a lifted field is most of the
+   * screen, and a panel that takes all of it stops reading as something laid
+   * over the app. Longer lists scroll.
+   */
+  panelMaxHeight?: number;
+  /**
+   * What has been picked so far, drawn inside the field before the caret.
+   * `SearchBar.Token` is the chip; anything else that fits on one line works
+   * too. Tokens scroll rather than wrap, so the field stays one line tall.
+   */
+  tokens?: ReactNode;
+  /**
+   * Fires when backspace is pressed in an empty field. Remove the last token
+   * here — it is the gesture every token field answers, and without it the
+   * only way back out of a choice is its own ✕.
+   */
+  onRemoveLastToken?: () => void;
+  /** The panel's contents — `SearchBar.Section`, `.Item` and `.Status`. */
+  children?: ReactNode;
 }
 
-export const SearchBar = forwardRef<TextInput, SearchBarProps>(
+const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
   (
     {
       value: valueProp,
@@ -226,8 +542,17 @@ export const SearchBar = forwardRef<TextInput, SearchBarProps>(
       className,
       containerClassName,
       disabled,
+      avoidKeyboard = false,
+      keyboardOffset = 12,
+      panel = 'focus',
+      panelPlacement = 'top',
+      panelMaxHeight,
+      tokens,
+      onRemoveLastToken,
+      children,
       onFocus,
       onBlur,
+      onKeyPress,
       onSubmitEditing,
       ...props
     },
@@ -241,7 +566,27 @@ export const SearchBar = forwardRef<TextInput, SearchBarProps>(
     const inputRef = useRef<TextInput | null>(null);
     useImperativeHandle(ref, () => inputRef.current as TextInput, []);
 
-    const slots = searchBarVariants({ size, shape });
+    /*
+     * Counted rather than tested for truthiness: `{results.map(…)}` over an
+     * empty array is a child, and a panel that opens on nothing is a card of
+     * padding.
+     */
+    const hasPanel = useMemo(() => {
+      let found = false;
+      Children.forEach(children, (child) => {
+        if (isValidElement(child)) found = true;
+      });
+      return found;
+    }, [children]);
+
+    const panelOpen =
+      !disabled &&
+      panel !== 'never' &&
+      hasPanel &&
+      (panel === 'always' || focused);
+
+    const attached = panelOpen ? panelPlacement : 'none';
+    const slots = searchBarVariants({ size, shape, attached });
 
     const setText = useCallback(
       (next: string) => {
@@ -276,20 +621,96 @@ export const SearchBar = forwardRef<TextInput, SearchBarProps>(
       };
     }, [text, debounce]);
 
+    /*
+     * Set while a press inside the panel or the field is being served. A blur
+     * arriving under it is the press taking focus rather than the search
+     * ending, so it is answered by asking for focus back — the panel is drawn
+     * out of `focused`, and letting it through would close the panel the
+     * pressed control is standing in.
+     */
+    const guarded = useRef(false);
+    const guardTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+    useEffect(
+      () => () => {
+        if (guardTimer.current) clearTimeout(guardTimer.current);
+      },
+      []
+    );
+
+    const retainFocus = useCallback(() => {
+      if (disabled) return;
+      guarded.current = true;
+      if (guardTimer.current) clearTimeout(guardTimer.current);
+      guardTimer.current = setTimeout(() => {
+        guarded.current = false;
+      }, FOCUS_GUARD);
+      inputRef.current?.focus();
+    }, [disabled]);
+
+    /*
+     * Set while the search is being ended deliberately — Cancel, or a caller
+     * calling `blur()`. Without it the recovery below would fight the very
+     * thing that is trying to close the search.
+     */
+    const ending = useRef(false);
+    const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const clearCloseTimer = useCallback(() => {
+      if (closeTimer.current) clearTimeout(closeTimer.current);
+      closeTimer.current = null;
+    }, []);
+
+    useEffect(() => clearCloseTimer, [clearCloseTimer]);
+
+    // Read inside a timer, so it has to be a ref rather than the render value.
+    const keyboardUp = useRef(false);
+
     const handleFocus = useCallback<NonNullable<InputProps['onFocus']>>(
       (event) => {
+        clearCloseTimer();
+        ending.current = false;
         setFocused(true);
         onFocus?.(event);
       },
-      [onFocus]
+      [clearCloseTimer, onFocus]
     );
 
     const handleBlur = useCallback<NonNullable<InputProps['onBlur']>>(
       (event) => {
-        setFocused(false);
+        // The caller asked for the event, so it goes out now rather than at
+        // the end of the pause — this is about what the *panel* believes.
         onBlur?.(event);
+
+        if (guarded.current) {
+          inputRef.current?.focus();
+          return;
+        }
+
+        clearCloseTimer();
+        closeTimer.current = setTimeout(() => {
+          closeTimer.current = null;
+          if (!ending.current && keyboardUp.current) {
+            // The keyboard never went down, so the search is still on screen
+            // and something inside it has taken the focus. Give it back.
+            inputRef.current?.focus();
+            return;
+          }
+          setFocused(false);
+        }, BLUR_GRACE);
+      },
+      [clearCloseTimer, onBlur]
+    );
+
+    const handleKeyPress = useCallback(
+      (event: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
+        // Only on an empty field: while there is a query, backspace is editing
+        // it, and eating a token instead would delete something nobody aimed at.
+        if (event.nativeEvent.key === 'Backspace' && text.length === 0) {
+          onRemoveLastToken?.();
+        }
+        onKeyPress?.(event);
       },
-      [onBlur]
+      [onKeyPress, onRemoveLastToken, text.length]
     );
 
     const handleSubmit = useCallback(
@@ -315,7 +736,12 @@ export const SearchBar = forwardRef<TextInput, SearchBarProps>(
 
     const handleCancel = useCallback(() => {
       if (disabled) return;
+      // Deliberate: the recovery above must not answer this blur by handing
+      // the focus straight back.
+      ending.current = true;
+      guarded.current = false;
       setText('');
+      setFocused(false);
       inputRef.current?.blur();
       onCancel?.();
     }, [disabled, onCancel, setText]);
@@ -349,7 +775,77 @@ export const SearchBar = forwardRef<TextInput, SearchBarProps>(
       [cancelWidth]
     );
 
-    const startContent = (
+    /*
+     * How much room the panel has, in the direction it opens. Measured on the
+     * JS side because it decides a layout constraint rather than a frame of an
+     * animation: a `maxHeight` that changed every frame would re-lay out the
+     * list under the finger scrolling it.
+     */
+    const { height: windowHeight } = useWindowDimensions();
+    const { height: keyboardHeight } = useKeyboard();
+    useEffect(() => {
+      keyboardUp.current = keyboardHeight > 0;
+    }, [keyboardHeight]);
+    const anchorRef = useRef<View | null>(null);
+    const [anchorBox, setAnchorBox] = useState<{
+      top: number;
+      height: number;
+      width: number;
+    } | null>(null);
+
+    const measureAnchor = useCallback(() => {
+      anchorRef.current?.measureInWindow((_x, y, width, height) => {
+        setAnchorBox((current) =>
+          current &&
+          current.top === y &&
+          current.height === height &&
+          current.width === width
+            ? current
+            : { top: y, height, width }
+        );
+      });
+    }, []);
+
+    useEffect(() => {
+      if (!panelOpen) return;
+      measureAnchor();
+    }, [panelOpen, keyboardHeight, measureAnchor]);
+
+    const resolvedMaxHeight = useMemo(() => {
+      const fieldHeight = anchorBox?.height ?? 0;
+      /*
+       * While the field is riding the keyboard, where it has come to rest is
+       * computed rather than measured: the lift is a transform applied on the
+       * UI thread, so a measurement taken from JavaScript is a frame behind it
+       * for the whole of the animation.
+       */
+      const fieldTop =
+        avoidKeyboard && keyboardHeight > 0
+          ? windowHeight - keyboardHeight - keyboardOffset - fieldHeight
+          : (anchorBox?.top ?? 0);
+      const room =
+        panelPlacement === 'top'
+          ? fieldTop - PANEL_EDGE_GAP
+          : windowHeight - keyboardHeight - fieldTop - fieldHeight - PANEL_EDGE_GAP;
+      /*
+       * The smaller of what it is allowed and what it actually has, floored so
+       * a cramped screen still opens something worth reading. A caller's cap
+       * is clamped to the room too — a cap taller than the space available is
+       * a panel running off the top of the display.
+       */
+      const cap = panelMaxHeight ?? PANEL_MAX_HEIGHT;
+      return Math.max(Math.min(cap, room), PANEL_MIN_HEIGHT);
+    }, [
+      anchorBox,
+      avoidKeyboard,
+      keyboardHeight,
+      keyboardOffset,
+      panelMaxHeight,
+      panelPlacement,
+      windowHeight,
+    ]);
+
+    const glyph = (
       /*
        * Decorative, and said so here rather than through Input's
        * `interactiveContent` — that flag covers both ends of the field, and
@@ -357,6 +853,7 @@ export const SearchBar = forwardRef<TextInput, SearchBarProps>(
        * touches with it.
        */
       <View
+        key="glyph"
         pointerEvents="none"
         accessibilityElementsHidden
         importantForAccessibility="no-hide-descendants"
@@ -365,6 +862,36 @@ export const SearchBar = forwardRef<TextInput, SearchBarProps>(
       </View>
     );
 
+    /*
+     * Capped and scrolling rather than wrapping. The field is one line tall, so
+     * a row of chips allowed to grow would move the caret every time something
+     * was picked; and left uncapped it would take the whole field and leave
+     * nowhere to type the next query.
+     */
+    const tokenRow = tokens ? (
+      <ScrollView
+        key="tokens"
+        horizontal
+        keyboardShouldPersistTaps="always"
+        showsHorizontalScrollIndicator={false}
+        style={{
+          maxWidth: anchorBox ? anchorBox.width * TOKEN_MAX_SHARE : undefined,
+        }}
+        contentContainerClassName={slots.tokenRow()}
+      >
+        {tokens}
+      </ScrollView>
+    ) : null;
+
+    const startContent = tokenRow ? (
+      <>
+        {glyph}
+        {tokenRow}
+      </>
+    ) : (
+      glyph
+    );
+
     const endContent = loading ? (
       <Spinner size="sm" />
     ) : isClearable && text.length > 0 ? (
@@ -386,13 +913,14 @@ export const SearchBar = forwardRef<TextInput, SearchBarProps>(
         size={size}
         disabled={disabled}
         className={slots.field({ className })}
-        containerClassName={cancel === 'never' ? containerClassName : 'flex-1'}
+        containerClassName="w-full"
         startContent={startContent}
         endContent={endContent}
         value={text}
         onChangeText={setText}
         onFocus={handleFocus}
         onBlur={handleBlur}
+        onKeyPress={handleKeyPress}
         onSubmitEditing={handleSubmit}
         accessibilityRole="search"
         returnKeyType="search"
@@ -407,41 +935,401 @@ export const SearchBar = forwardRef<TextInput, SearchBarProps>(
       />
     );
 
-    if (cancel === 'never') return field;
+    const context = useMemo<SearchBarContextValue>(
+      () => ({ size, retainFocus }),
+      [retainFocus, size]
+    );
 
-    return (
-      <View className={slots.row({ className: containerClassName })}>
-        {field}
-        <Animated.View
-          style={cancelStyle}
-          className={slots.cancelClip()}
-          pointerEvents={cancelOut ? 'auto' : 'none'}
-          accessibilityElementsHidden={!cancelOut}
-          importantForAccessibility={cancelOut ? 'auto' : 'no-hide-descendants'}
-        >
-          {/*
-           * Absolute, and pinned to the end edge: it keeps its natural width
-           * inside a container whose width is animating, so the clip reveals
-           * it from the edge instead of squeezing the word as it arrives. It
-           * is also what makes the measurement possible at all — a child laid
-           * out against a container of width 0 would otherwise report 0.
-           */}
-          <AnimatedPressable
-            onLayout={handleCancelLayout}
-            onPress={handleCancel}
-            disabled={disabled}
-            focusable={!disabled}
-            hitSlop={8}
-            accessibilityRole="button"
-            accessibilityState={{ disabled: !!disabled }}
-            className={slots.cancelButton()}
+    // Nothing beside it and nothing under it: the field is the whole component,
+    // and a wrapper around it would only be a box for the caller's layout to
+    // fight.
+    if (cancel === 'never' && !avoidKeyboard && !hasPanel) {
+      return (
+        <SearchBarContext.Provider value={context}>
+          <View ref={anchorRef} onLayout={measureAnchor} className={containerClassName}>
+            {field}
+          </View>
+        </SearchBarContext.Provider>
+      );
+    }
+
+    /*
+     * The results, the hairline and the room the field occupies, in the order
+     * they are stacked. The field itself is drawn over that last piece rather
+     * than inside the card: it has to keep its own place in the layout, and a
+     * text field that moved into an absolutely positioned box on focus would
+     * remount and lose the keyboard it just opened.
+     */
+    const list = (
+      <ScrollView
+        key="list"
+        style={{ maxHeight: resolvedMaxHeight }}
+        /*
+         * `always`, not `handled`: everything in the panel that is not itself
+         * a button — the padding, the gaps between rows, a section heading,
+         * the whole of `SearchBar.Status` — would otherwise spend the first
+         * tap dismissing the keyboard, which ends the search.
+         */
+        keyboardShouldPersistTaps="always"
+        keyboardDismissMode="none"
+        showsVerticalScrollIndicator={false}
+        bounces={false}
+        className={slots.panelList()}
+      >
+        {children}
+      </ScrollView>
+    );
+    const divider = (
+      <View
+        key="divider"
+        pointerEvents="none"
+        style={{ height: StyleSheet.hairlineWidth }}
+        className={slots.panelDivider()}
+      />
+    );
+    /*
+     * The room the card keeps for the field, and the reason it is inert.
+     *
+     * It is a spacer drawn at exactly the field's position, inside the card and
+     * therefore outside the list's `keyboardShouldPersistTaps`. Any touch it
+     * wins is a touch on a plain view while a field is focused, which is the
+     * platform's cue to dismiss the keyboard — so the field blurs, and the
+     * panel drawn out of that focus closes. From the outside that is "tapping
+     * the search box closes the results", which is exactly backwards.
+     *
+     * It has nothing to be pressed for. `none` puts the touch through to the
+     * field underneath it, where it was aimed.
+     */
+    const fieldSlot = (
+      <View
+        key="slot"
+        pointerEvents="none"
+        style={{ height: anchorBox?.height ?? FIELD_HEIGHT[size] }}
+      />
+    );
+
+    const anchor = (
+      <View
+        ref={anchorRef}
+        onLayout={measureAnchor}
+        style={RAISED}
+        className={slots.anchor({ className: cancel === 'never' ? 'w-full' : 'flex-1' })}
+      >
+        {panelOpen ? (
+          <Animated.View
+            entering={FadeIn.duration(PANEL_IN)}
+            exiting={FadeOut.duration(PANEL_OUT)}
+            // `box-none`: the card is a surface, not a target. Only the rows
+            // inside it answer a touch, and the space kept for the field lets
+            // one through to the field.
+            pointerEvents="box-none"
+            style={panelPlacement === 'top' ? CARD_ABOVE : CARD_BELOW}
+            className={slots.panel()}
           >
-            <Text className={slots.cancelLabel()}>{cancelLabel}</Text>
-          </AnimatedPressable>
-        </Animated.View>
+            {panelPlacement === 'top'
+              ? [list, divider, fieldSlot]
+              : [fieldSlot, divider, list]}
+          </Animated.View>
+        ) : null}
+        {field}
       </View>
     );
+
+    const body =
+      cancel === 'never' ? (
+        anchor
+      ) : (
+        <>
+          {anchor}
+          <Animated.View
+            style={cancelStyle}
+            className={slots.cancelClip()}
+            pointerEvents={cancelOut ? 'auto' : 'none'}
+            accessibilityElementsHidden={!cancelOut}
+            importantForAccessibility={cancelOut ? 'auto' : 'no-hide-descendants'}
+          >
+            {/*
+             * Absolute, and pinned to the end edge: it keeps its natural width
+             * inside a container whose width is animating, so the clip reveals
+             * it from the edge instead of squeezing the word as it arrives. It
+             * is also what makes the measurement possible at all — a child laid
+             * out against a container of width 0 would otherwise report 0.
+             */}
+            <AnimatedPressable
+              onLayout={handleCancelLayout}
+              onPress={handleCancel}
+              disabled={disabled}
+              focusable={!disabled}
+              hitSlop={8}
+              accessibilityRole="button"
+              accessibilityState={{ disabled: !!disabled }}
+              className={slots.cancelButton()}
+            >
+              <Text className={slots.cancelLabel()}>{cancelLabel}</Text>
+            </AnimatedPressable>
+          </Animated.View>
+        </>
+      );
+
+    /*
+     * The keyboard hook is behind a component boundary rather than a flag.
+     * Calling it at all has global consequences — without the keyboard
+     * controller installed it falls back to Reanimated's useAnimatedKeyboard,
+     * which switches Android out of adjustResize for the whole app. A search
+     * bar that never asked to avoid the keyboard must not do that to every
+     * other screen.
+     */
+    if (avoidKeyboard) {
+      return (
+        <SearchBarContext.Provider value={context}>
+          <KeyboardAvoider
+            // Only while *this* field is the one being typed into. Without it
+            // every avoiding field on the screen lifts the moment any field
+            // anywhere is tapped, and since they all aim at the same gap above
+            // the keyboard, they arrive stacked on top of one another.
+            active={focused}
+            mode="lift"
+            offset={keyboardOffset}
+            className={slots.row({ className: containerClassName })}
+          >
+            {body}
+          </KeyboardAvoider>
+        </SearchBarContext.Provider>
+      );
+    }
+
+    return (
+      <SearchBarContext.Provider value={context}>
+        <View className={slots.row({ className: containerClassName })}>{body}</View>
+      </SearchBarContext.Provider>
+    );
   }
 );
 
-SearchBar.displayName = 'SearchBar';
+SearchBarRoot.displayName = 'SearchBar';
+
+export interface SearchBarSectionProps extends ViewProps {
+  className?: string;
+  /**
+   * The heading over the run of rows — "Suggested", "Results". Announced as a
+   * header, so a screen reader reaching the group is told what it is before
+   * walking into it.
+   */
+  label?: string;
+  children?: ReactNode;
+}
+
+/** A labelled run of rows inside the panel. */
+function SearchBarSection({ className, label, children, ...props }: SearchBarSectionProps) {
+  const { sectionLabel } = searchBarVariants();
+  return (
+    <View {...props} className={className}>
+      {label ? (
+        <Text accessibilityRole="header" className={sectionLabel()}>
+          {label}
+        </Text>
+      ) : null}
+      {children}
+    </View>
+  );
+}
+
+SearchBarSection.displayName = 'SearchBar.Section';
+
+export interface SearchBarItemProps extends Omit<AnimatedPressableProps, 'children'> {
+  className?: string;
+  /** Anything before the label — an avatar, a logo, a status dot. */
+  leading?: ReactNode;
+  /**
+   * Anything after it. A slot rather than a built-in button, because what a
+   * result row offers differs per search: an add, a pin, a count, nothing.
+   */
+  trailing?: ReactNode;
+  /** A second line under the label, for what the label alone cannot say. */
+  description?: string;
+  /** Draws the row as the one the search has settled on. */
+  selected?: boolean;
+  /** The row's label. */
+  children?: ReactNode;
+}
+
+/** One result. */
+function SearchBarItem({
+  className,
+  leading,
+  trailing,
+  description,
+  selected,
+  children,
+  onPressIn,
+  ...props
+}: SearchBarItemProps) {
+  const { item, itemLabel } = searchBarVariants({ selected: !!selected });
+  const search = useContext(SearchBarContext);
+  return (
+    <AnimatedPressable
+      accessibilityRole="button"
+      accessibilityState={{ selected: !!selected, disabled: !!props.disabled }}
+      /*
+       * Before the press, not after it: the blur it may cause is what closes
+       * the panel this row is drawn in, and by the time `onPress` runs the row
+       * can already be gone.
+       */
+      onPressIn={(event) => {
+        search?.retainFocus();
+        onPressIn?.(event);
+      }}
+      // A row is a wide target, and a target that shrinks when pressed reads as
+      // a card rather than a line in a list. The dim is the whole feedback.
+      pressScale={1}
+      pressOpacity={0.6}
+      // The rows sit flush against each other, so the points either side of the
+      // gap between two of them would otherwise belong to neither.
+      hitSlop={{ top: 2, bottom: 2 }}
+      {...props}
+      className={item({ className })}
+    >
+      {leading}
+      <View className="flex-1">
+        <Text numberOfLines={1} className={itemLabel()}>
+          {children}
+        </Text>
+        {description ? (
+          <Text size="sm" muted numberOfLines={1}>
+            {description}
+          </Text>
+        ) : null}
+      </View>
+      {trailing}
+    </AnimatedPressable>
+  );
+}
+
+SearchBarItem.displayName = 'SearchBar.Item';
+
+export interface SearchBarStatusProps extends ViewProps {
+  className?: string;
+  /** A spinner beside the line, for a search that is still running. */
+  loading?: boolean;
+  children?: ReactNode;
+}
+
+/**
+ * The one line a panel shows instead of rows — nothing typed yet, a search in
+ * flight, or a query that matched nothing. It is a sentence rather than an
+ * empty box because those three states look identical when they are blank, and
+ * which one it is decides what the person does next.
+ */
+function SearchBarStatus({
+  className,
+  loading = false,
+  children,
+  ...props
+}: SearchBarStatusProps) {
+  const { status } = searchBarVariants();
+  return (
+    <View accessibilityRole="text" {...props} className={status({ className })}>
+      {loading ? <Spinner size="sm" /> : null}
+      <Text size="sm" muted>
+        {children}
+      </Text>
+    </View>
+  );
+}
+
+SearchBarStatus.displayName = 'SearchBar.Status';
+
+export interface SearchBarActionProps extends AnimatedPressableProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * A button inside a row — an add, a pin, a remove — for the `trailing` slot.
+ *
+ * It exists rather than being left to a plain `Pressable` because a control
+ * nested inside a row takes the touch itself, so the row above it never sees
+ * the press and cannot hold the field's focus on its behalf. Pressed, this one
+ * ends up blurring the field, and a blurred field closes the panel the button
+ * was standing in — the press lands and the search disappears under it.
+ */
+function SearchBarAction({ className, children, onPressIn, ...props }: SearchBarActionProps) {
+  const search = useContext(SearchBarContext);
+  return (
+    <AnimatedPressable
+      accessibilityRole="button"
+      hitSlop={12}
+      pressScale={1}
+      pressOpacity={0.5}
+      onPressIn={(event) => {
+        search?.retainFocus();
+        onPressIn?.(event);
+      }}
+      {...props}
+      className={className}
+    >
+      {children}
+    </AnimatedPressable>
+  );
+}
+
+SearchBarAction.displayName = 'SearchBar.Action';
+
+export interface SearchBarTokenProps extends ViewProps {
+  className?: string;
+  /** Anything before the label — an avatar, a logo, a status dot. */
+  leading?: ReactNode;
+  /** Fires when the chip's ✕ is pressed. Without it no ✕ is drawn. */
+  onRemove?: () => void;
+  /** How the ✕ announces itself. Defaults to `Remove <label>`. */
+  removeLabel?: string;
+  /** The chip's label. */
+  children?: ReactNode;
+}
+
+/**
+ * One choice already made, drawn inside the field before the caret.
+ *
+ * It sits in the field rather than in a list above it so that the query and
+ * what the query has produced are one control. A search that files its results
+ * somewhere else asks the reader to look in two places to know where they are.
+ */
+function SearchBarToken({
+  className,
+  leading,
+  onRemove,
+  removeLabel,
+  children,
+  ...props
+}: SearchBarTokenProps) {
+  const search = useContext(SearchBarContext);
+  const slots = searchBarVariants({ size: search?.size ?? 'md' });
+  const label = typeof children === 'string' ? children : undefined;
+  return (
+    <View {...props} className={slots.token({ className })}>
+      {leading}
+      <Text numberOfLines={1} className={slots.tokenLabel()}>
+        {children}
+      </Text>
+      {onRemove ? (
+        <SearchBarAction
+          accessibilityLabel={removeLabel ?? (label ? `Remove ${label}` : 'Remove')}
+          onPress={onRemove}
+          className={slots.tokenRemove()}
+        >
+          <XIcon size={12} />
+        </SearchBarAction>
+      ) : null}
+    </View>
+  );
+}
+
+SearchBarToken.displayName = 'SearchBar.Token';
+
+export const SearchBar = Object.assign(SearchBarRoot, {
+  Section: SearchBarSection,
+  Item: SearchBarItem,
+  Action: SearchBarAction,
+  Token: SearchBarToken,
+  Status: SearchBarStatus,
+});