panelui-native 0.87.0 → 0.88.0

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

@@ -32,9 +32,48 @@
  *
  * ## Touches inside the panel must not close the keyboard
  *
- * The panel scrolls with `keyboardShouldPersistTaps="handled"`. Without it the
- * first tap on a row is spent dismissing the keyboard and the press never
- * arrives, which reads as a row that ignores every other tap.
+ * 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
  *
@@ -73,8 +112,10 @@
  */
 import {
   Children,
+  createContext,
   forwardRef,
   isValidElement,
+  useContext,
   useCallback,
   useEffect,
   useImperativeHandle,
@@ -91,6 +132,7 @@ import {
   type LayoutChangeEvent,
   type NativeSyntheticEvent,
   type TextInput,
+  type TextInputKeyPressEventData,
   type TextInputSubmitEditingEventData,
   type ViewProps,
   type ViewStyle,
@@ -142,6 +184,54 @@ 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.
@@ -155,6 +245,18 @@ const CARD_BELOW: ViewStyle = { position: 'absolute', top: 0, left: 0, right: 0
  * 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 };
 
@@ -199,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
@@ -241,6 +370,19 @@ 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';
 
@@ -353,11 +495,27 @@ export interface SearchBarProps
    */
   panelPlacement?: SearchBarPanelPlacement;
   /**
-   * Cap on the panel's height, in points. Derived from the room between the
-   * field and the edge of the screen when it is not given, so a panel never
-   * runs off the top of the display.
+   * 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;
 }
@@ -389,9 +547,12 @@ const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
       panel = 'focus',
       panelPlacement = 'top',
       panelMaxHeight,
+      tokens,
+      onRemoveLastToken,
       children,
       onFocus,
       onBlur,
+      onKeyPress,
       onSubmitEditing,
       ...props
     },
@@ -460,20 +621,96 @@ const SearchBarRoot = 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);
       },
-      [onBlur]
+      [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);
+      },
+      [onKeyPress, onRemoveLastToken, text.length]
     );
 
     const handleSubmit = useCallback(
@@ -499,7 +736,12 @@ const SearchBarRoot = 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]);
@@ -541,17 +783,25 @@ const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
      */
     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 } | null>(
-      null
-    );
+    const [anchorBox, setAnchorBox] = useState<{
+      top: number;
+      height: number;
+      width: number;
+    } | null>(null);
 
     const measureAnchor = useCallback(() => {
-      anchorRef.current?.measureInWindow((_x, y, _width, height) => {
+      anchorRef.current?.measureInWindow((_x, y, width, height) => {
         setAnchorBox((current) =>
-          current && current.top === y && current.height === height
+          current &&
+          current.top === y &&
+          current.height === height &&
+          current.width === width
             ? current
-            : { top: y, height }
+            : { top: y, height, width }
         );
       });
     }, []);
@@ -562,7 +812,6 @@ const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
     }, [panelOpen, keyboardHeight, measureAnchor]);
 
     const resolvedMaxHeight = useMemo(() => {
-      if (panelMaxHeight !== undefined) return panelMaxHeight;
       const fieldHeight = anchorBox?.height ?? 0;
       /*
        * While the field is riding the keyboard, where it has come to rest is
@@ -578,7 +827,14 @@ const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
         panelPlacement === 'top'
           ? fieldTop - PANEL_EDGE_GAP
           : windowHeight - keyboardHeight - fieldTop - fieldHeight - PANEL_EDGE_GAP;
-      return Math.max(room, PANEL_MIN_HEIGHT);
+      /*
+       * 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,
@@ -589,7 +845,7 @@ const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
       windowHeight,
     ]);
 
-    const startContent = (
+    const glyph = (
       /*
        * Decorative, and said so here rather than through Input's
        * `interactiveContent` — that flag covers both ends of the field, and
@@ -597,6 +853,7 @@ const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
        * touches with it.
        */
       <View
+        key="glyph"
         pointerEvents="none"
         accessibilityElementsHidden
         importantForAccessibility="no-hide-descendants"
@@ -605,6 +862,36 @@ const SearchBarRoot = 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 ? (
@@ -633,6 +920,7 @@ const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
         onChangeText={setText}
         onFocus={handleFocus}
         onBlur={handleBlur}
+        onKeyPress={handleKeyPress}
         onSubmitEditing={handleSubmit}
         accessibilityRole="search"
         returnKeyType="search"
@@ -647,11 +935,22 @@ const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
       />
     );
 
+    const context = useMemo<SearchBarContextValue>(
+      () => ({ size, retainFocus }),
+      [retainFocus, size]
+    );
+
     // 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 <View className={containerClassName}>{field}</View>;
+      return (
+        <SearchBarContext.Provider value={context}>
+          <View ref={anchorRef} onLayout={measureAnchor} className={containerClassName}>
+            {field}
+          </View>
+        </SearchBarContext.Provider>
+      );
     }
 
     /*
@@ -666,11 +965,12 @@ const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
         key="list"
         style={{ maxHeight: resolvedMaxHeight }}
         /*
-         * Without this the first tap on a row is spent dismissing the keyboard
-         * and the press never lands, which reads as a list that ignores every
-         * other touch.
+         * `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="handled"
+        keyboardShouldPersistTaps="always"
         keyboardDismissMode="none"
         showsVerticalScrollIndicator={false}
         bounces={false}
@@ -682,23 +982,47 @@ const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
     const divider = (
       <View
         key="divider"
+        pointerEvents="none"
         style={{ height: StyleSheet.hairlineWidth }}
         className={slots.panelDivider()}
       />
     );
-    const fieldSlot = <View key="slot" style={{ height: anchorBox?.height ?? 0 }} />;
+    /*
+     * 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={panelOpen ? RAISED : undefined}
+        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()}
           >
@@ -757,22 +1081,28 @@ const SearchBarRoot = forwardRef<TextInput, SearchBarProps>(
      */
     if (avoidKeyboard) {
       return (
-        <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 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 <View className={slots.row({ className: containerClassName })}>{body}</View>;
+    return (
+      <SearchBarContext.Provider value={context}>
+        <View className={slots.row({ className: containerClassName })}>{body}</View>
+      </SearchBarContext.Provider>
+    );
   }
 );
 
@@ -831,13 +1161,24 @@ function SearchBarItem({
   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}
@@ -898,8 +1239,97 @@ function SearchBarStatus({
 
 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,
 });