panelui-native 0.79.0 → 0.80.0

package/src/components/panelside/index.tsx

@@ -84,6 +84,7 @@ import {
   useContext,
   useEffect,
   useMemo,
+  useRef,
   useState,
   type ReactElement,
   type ReactNode,
@@ -116,9 +117,18 @@ import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { tv } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
 import { LinearGradient } from 'expo-linear-gradient';
-import { EllipsisIcon, IconColorProvider, MenuIcon, SearchIcon } from '../../icons';
+import { EllipsisIcon, IconColorProvider, MenuIcon, SearchIcon, XIcon } from '../../icons';
+import {
+  BottomSheet,
+  bottomSheetDetentHeight,
+  type BottomSheetBodyProps,
+  type BottomSheetProps,
+} from '../bottom-sheet';
 import { Button } from '../button';
+import { Tabs } from '../tabs';
+import { getNativeUI } from '../../native';
 import { AnimatedPressable } from '../../primitives/animated-pressable';
+import { KeyboardAvoider } from '../../primitives/keyboard-avoider';
 import { Text, textChildren, type TextProps } from '../../primitives/text';
 import { useBackHandler } from '../../hooks/use-back-handler';
 import { useDirectionSign } from '../../hooks/use-direction';
@@ -236,6 +246,20 @@ const DOCK_WIDTH_MAX = 320;
 /** How far above the floating footer the list starts dissolving into it. */
 const FOOTER_FADE = 28;
 
+/**
+ * What `BottomSheet.Content` leaves below its last child, maxed against the
+ * home indicator. Mirrored here so the search field can subtract the strip it
+ * already sits above before it travels with the keyboard.
+ */
+const SHEET_BOTTOM_PADDING = 16;
+
+/**
+ * The top padding the search surface asks `BottomSheet.Content` for, and takes
+ * back off the column's height. Smaller than the sheet's own default, because
+ * this surface leads with a round button rather than with a title.
+ */
+const SHEET_TOP_PADDING = 12;
+
 /** Progress past which a layer is treated as fully hidden for accessibility. */
 const HIDDEN_EPSILON = 0.05;
 
@@ -248,6 +272,15 @@ export type PanelsideMode = 'push' | 'overlay';
 export type PanelsideSwipeFrom = 'anywhere' | 'edge';
 export type PanelsideItemSize = 'default' | 'sm';
 export type PanelsideCtaSize = 'default' | 'lg';
+/**
+ * What a header or a footer paints behind itself.
+ *
+ * `transparent` paints nothing, and the list runs the full height of the panel
+ * underneath it. `fade` dissolves the list into the panel background over the
+ * strip above the controls. `solid` is a band with an edge on it, for a footer
+ * that is a row of the layout rather than something floating over one.
+ */
+export type PanelsideSurface = 'transparent' | 'fade' | 'solid';
 
 const itemVariants = tv({
   // No width: in a group it stretches on its own, and pinning it to full width
@@ -272,9 +305,14 @@ const itemVariants = tv({
 const ctaVariants = tv({
   // Taller and wider than a list row's control. It is the one thing in the
   // panel you are meant to reach for without reading, so it should not be the
-  // same size as the eight chat titles above it — but it shares its footer row
-  // with an account button, and a pill that stands a whole step above that row
-  // makes the footer taller than anything in the panel needs it to be.
+  // same size as the eight chat titles above it.
+  //
+  // It used to be 40pt, chosen to sit level with the account button beside it.
+  // That is the wrong thing to size it against: the account button is a target
+  // you find once, and the compose pill is the one pressed every session — at
+  // matching heights the two read as a pair of equals and the pill stopped
+  // being the thing the footer is for. Four points is enough to separate them
+  // without making the footer taller than the panel needs.
   base: 'shrink flex-row items-center justify-center rounded-full',
   variants: {
     variant: {
@@ -282,8 +320,8 @@ const ctaVariants = tv({
       secondary: 'bg-secondary',
     },
     size: {
-      default: 'h-10 gap-2 px-5',
-      lg: 'h-12 gap-2 px-6',
+      default: 'h-11 gap-2 px-6',
+      lg: 'h-13 gap-2.5 px-7',
     },
   },
   defaultVariants: {
@@ -308,6 +346,16 @@ interface PanelsideContextValue {
   scale?: number;
   radius?: number;
   dim?: number;
+  /**
+   * Whether the search surface is up.
+   *
+   * It lives on the root rather than on the sheet because the two halves of
+   * search are in different subtrees: the button is in the header and the
+   * sheet is a sibling of the panel. Anything else means every app wiring one
+   * `useState` through both.
+   */
+  searchOpen: boolean;
+  setSearchOpen: (open: boolean) => void;
 }
 
 const PanelsideContext = createContext<PanelsideContextValue | null>(null);
@@ -332,6 +380,9 @@ export interface UsePanelsideResult {
   progress: SharedValue<number>;
   /** True while the panel is docked open beside the scene. */
   docked: boolean;
+  /** Whether the search surface is up. `Panelside.SearchTrigger` sets it. */
+  searchOpen: boolean;
+  setSearchOpen: (open: boolean) => void;
 }
 
 /**
@@ -340,8 +391,9 @@ export interface UsePanelsideResult {
  * lives.
  */
 export function usePanelside(): UsePanelsideResult {
-  const { open, setOpen, toggle, progress, docked } = usePanelsideContext('usePanelside');
-  return { open, setOpen, toggle, progress, docked };
+  const { open, setOpen, toggle, progress, docked, searchOpen, setSearchOpen } =
+    usePanelsideContext('usePanelside');
+  return { open, setOpen, toggle, progress, docked, searchOpen, setSearchOpen };
 }
 
 /**
@@ -464,6 +516,7 @@ function PanelsideRoot({
   const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
   const controlled = controlledOpen !== undefined;
   const open = controlled ? controlledOpen : uncontrolledOpen;
+  const [searchOpen, setSearchOpen] = useState(false);
 
   /*
    * Measured rather than taken from the window, because Panelside does not
@@ -640,8 +693,23 @@ function PanelsideRoot({
       scale,
       radius,
       dim,
+      searchOpen,
+      setSearchOpen,
     }),
-    [dim, dismissible, docked, mode, open, progress, radius, scale, setOpen, toggle, width]
+    [
+      dim,
+      dismissible,
+      docked,
+      mode,
+      open,
+      progress,
+      radius,
+      scale,
+      searchOpen,
+      setOpen,
+      toggle,
+      width,
+    ]
   );
 
   return (
@@ -726,6 +794,20 @@ export interface PanelsideHeaderProps extends ViewProps {
   title?: string;
   /** A single element pinned to the trailing end of the title row. */
   action?: ReactNode;
+  /**
+   * What the header paints behind itself.
+   *
+   * `transparent` is the default and paints nothing, so the header is the
+   * panel's own surface with a title on it rather than a bar sitting on top of
+   * one. In the panel's normal stacking that is the whole story — the header
+   * takes a row and the list starts below it.
+   *
+   * `fade` and `solid` are for a header the caller has lifted out of that
+   * stack — `className="absolute start-0 end-0 top-0"` — so the list runs
+   * underneath it. They are the two shapes `Panelside.Footer` offers, drawn
+   * the other way up.
+   */
+  surface?: PanelsideSurface;
   /** Anything below the title row — a search field, a workspace switcher. */
   children?: ReactNode;
 }
@@ -734,11 +816,14 @@ function PanelsideHeader({
   className,
   title,
   action,
+  surface = 'transparent',
   children,
   style,
   ...props
 }: PanelsideHeaderProps) {
   const insets = useSafeAreaInsets();
+  const background = useCSSVariable('--color-background');
+  const solid = typeof background === 'string' ? background : '#000000';
 
   return (
     <View
@@ -750,9 +835,32 @@ function PanelsideHeader({
       // `px-3` matches the scroller below it, so the search field and the rows
       // share one edge. A header inset further would leave the field floating
       // a few points inside the list it filters.
-      className={cn('gap-3 px-3 pb-3', className)}
+      className={cn(
+        'gap-3 px-3 pb-3',
+        surface === 'solid' && 'border-b border-border bg-background',
+        className
+      )}
       {...props}
     >
+      {/* The footer's fade, upside down: opaque under the title and clearing to
+          nothing at the bottom edge, so a row scrolled up into the header
+          dissolves rather than sliding out from under a line. */}
+      {surface === 'fade' ? (
+        <>
+          <View
+            pointerEvents="none"
+            className="absolute end-0 start-0 top-0 bg-background"
+            style={{ bottom: FOOTER_FADE }}
+          />
+          <LinearGradient
+            colors={[solid, `${solid}00`]}
+            start={{ x: 0, y: 0 }}
+            end={{ x: 0, y: 1 }}
+            pointerEvents="none"
+            style={[styles.rise, { height: FOOTER_FADE }]}
+          />
+        </>
+      ) : null}
       {(title || action) && (
         <View className="h-9 flex-row items-center justify-between gap-2">
           {title ? (
@@ -1153,22 +1261,43 @@ export interface PanelsideFooterProps extends ViewProps {
    * leaves exactly this footer's height of room at the end.
    */
   floating?: boolean;
+  /**
+   * What the footer paints behind its controls.
+   *
+   * `transparent` is the default and paints nothing: the list runs under the
+   * controls, which is how the panel reads as one surface with two things
+   * floating on it rather than as a list with a bar bolted to the bottom.
+   *
+   * `fade` dissolves the list into the panel background over the strip above
+   * the controls. It costs a band of the panel, and buys a compose button that
+   * never has a chat title running through its label — worth turning on for a
+   * panel whose history is long enough that something is always underneath.
+   *
+   * `solid` is a band with a hairline over it, for a footer that is a row of
+   * the layout. Implied by `floating={false}`, which has no list to float over.
+   */
+  surface?: PanelsideSurface;
   children?: ReactNode;
 }
 
 function PanelsideFooter({
   className,
   floating = true,
+  surface = 'transparent',
   children,
   style,
   ...props
 }: PanelsideFooterProps) {
   const insets = useSafeAreaInsets();
-  const surface = useContext(PanelsideSurfaceContext);
-  const setFooterHeight = surface?.setFooterHeight;
+  const panel = useContext(PanelsideSurfaceContext);
+  const setFooterHeight = panel?.setFooterHeight;
   const background = useCSSVariable('--color-background');
   const solid = typeof background === 'string' ? background : '#000000';
 
+  // A footer in the flow has nothing to float over, so the only thing it can
+  // be is the band — whatever was asked for.
+  const paint = floating ? surface : 'solid';
+
   const onLayout = useCallback(
     (event: LayoutChangeEvent) => {
       setFooterHeight?.(event.nativeEvent.layout.height);
@@ -1181,7 +1310,7 @@ function PanelsideFooter({
       onLayout={floating ? onLayout : undefined}
       style={[
         { paddingBottom: Math.max(insets.bottom, 12) },
-        floating ? { paddingTop: FOOTER_FADE } : null,
+        floating ? { paddingTop: paint === 'fade' ? FOOTER_FADE : 12 } : null,
         style,
       ]}
       className={cn(
@@ -1196,22 +1325,16 @@ function PanelsideFooter({
       {...props}
     >
       {/*
-        A floating footer has no edge and no bar. A solid one cuts a strip out
-        of the bottom of the list; a transparent one lets rows slide under the
-        controls and show through the labels. So it is neither: the top
-        `FOOTER_FADE` points are a gradient the list dissolves into, and
-        everything below that — the band the controls actually sit in — is
-        plain background.
-
-        The fade has to finish *above* the first control, not run through it.
-        Two layers rather than one gradient across the whole box, because a
-        gradient sized to the box puts its midpoint wherever the box happens to
-        be tall, which is exactly where the labels are.
+        The fade is two layers rather than one gradient across the whole box.
+        A gradient sized to the box puts its midpoint wherever the box happens
+        to be tall, which is exactly where the labels are — so the top
+        `FOOTER_FADE` points are the gradient and everything below it, the band
+        the controls actually sit in, is plain background.
 
         Both are inside the footer's own bounds, so neither depends on a parent
         that does not clip its children.
       */}
-      {floating ? (
+      {paint === 'fade' ? (
         <>
           <LinearGradient
             colors={[`${solid}00`, solid]}
@@ -1227,6 +1350,12 @@ function PanelsideFooter({
           />
         </>
       ) : null}
+      {paint === 'solid' && floating ? (
+        <View
+          pointerEvents="none"
+          className="absolute bottom-0 end-0 start-0 top-0 border-t border-border bg-background"
+        />
+      ) : null}
       {textChildren(children)}
     </View>
   );
@@ -1234,6 +1363,7 @@ function PanelsideFooter({
 
 const styles = StyleSheet.create({
   fade: { position: 'absolute', top: 0, left: 0, right: 0 },
+  rise: { position: 'absolute', bottom: 0, left: 0, right: 0 },
 });
 
 export interface PanelsideCtaProps extends Omit<PressableProps, 'children'> {
@@ -1245,9 +1375,10 @@ export interface PanelsideCtaProps extends Omit<PressableProps, 'children'> {
   /** `primary` is the filled accent pill; `secondary` is the quiet one. */
   variant?: 'primary' | 'secondary';
   /**
-   * How tall the pill is. `default` is 40pt, which sits level with the account
-   * button beside it in the footer; `lg` is the 48pt pill, for a panel where
-   * the call to action is the only thing in the row.
+   * How tall the pill is. `default` is 44pt — a step above the account button
+   * beside it, so the footer reads as one primary control and one secondary
+   * one. `lg` is 52pt, for a panel where the call to action is the only thing
+   * in the row.
    *
    * Ignored under `native` — the platform sizes its own button, and asks for a
    * control size rather than a height.
@@ -1582,6 +1713,583 @@ function PanelsideTrigger({
   );
 }
 
+/* ------------------------------------------------------------------ *
+ * Search.
+ *
+ * A field in the header is the obvious way to put search in a navigation
+ * panel, and it is the wrong one on a phone. The panel is 80% of the screen
+ * and the field is 40 points of it, so a search that returns anything has to
+ * push the history down the screen it is already filling — and the field is at
+ * the top, which is the far end of the screen from the keyboard that has just
+ * opened under it.
+ *
+ * So search is a surface rather than a row. A round button in the header opens
+ * a sheet that is the whole screen; the tabs across the top narrow what is
+ * being searched; the results fill the middle; and the field is at the bottom,
+ * where the thumb already is, riding the keyboard rather than hiding behind
+ * it.
+ *
+ * `Panelside.Search` — the inline field — is still exported, and is still
+ * right for a docked panel on a tablet, where there is width for a field and
+ * no keyboard covering half the screen.
+ * ------------------------------------------------------------------ */
+
+export interface PanelsideSearchTriggerProps extends Omit<PressableProps, 'children'> {
+  className?: string;
+  /** What a screen reader announces. */
+  label?: string;
+  /** Replaces the default magnifier. */
+  children?: ReactNode;
+  /**
+   * Render the platform's own button instead of the circle. Requires the
+   * optional `@expo/ui` package; without it this prop does nothing.
+   */
+  native?: boolean;
+  /**
+   * Draw the native button in the platform's Liquid Glass material. Requires
+   * `native`, and iOS 26 or later; ignored anywhere else.
+   */
+  glass?: boolean;
+}
+
+/**
+ * The button that opens the search surface. Goes in `Panelside.Header`'s
+ * `action` slot.
+ *
+ * It toggles the root's `searchOpen`, which `Panelside.SearchSheet` reads —
+ * so the two need nothing wired between them.
+ */
+function PanelsideSearchTrigger({
+  className,
+  label = 'Search',
+  children,
+  native = false,
+  glass = false,
+  onPress,
+  ...props
+}: PanelsideSearchTriggerProps) {
+  const { setSearchOpen } = usePanelsideContext('Panelside.SearchTrigger');
+  const tint = useCSSVariable('--color-foreground');
+  const color = typeof tint === 'string' ? tint : undefined;
+
+  const open = useCallback(
+    (event: Parameters<NonNullable<PressableProps['onPress']>>[0]) => {
+      onPress?.(event);
+      setSearchOpen(true);
+    },
+    [onPress, setSearchOpen]
+  );
+
+  const glyph = children ?? <SearchIcon size={18} color={native ? color : undefined} />;
+
+  if (native) {
+    return (
+      <Button
+        native
+        glass={glass}
+        size="icon"
+        variant="ghost"
+        accessibilityLabel={label}
+        onPress={open}
+      >
+        {glyph}
+      </Button>
+    );
+  }
+
+  return (
+    <AnimatedPressable
+      {...props}
+      onPress={open}
+      className={cn(
+        // Filled rather than outlined. It sits on the panel's own surface with
+        // nothing else on that row, so an outline at this size reads as an
+        // empty circle before it reads as a control.
+        'h-10 w-10 items-center justify-center rounded-full bg-secondary',
+        className
+      )}
+      accessibilityRole="button"
+      accessibilityLabel={label}
+    >
+      <IconColorProvider color={color}>{glyph}</IconColorProvider>
+    </AnimatedPressable>
+  );
+}
+
+interface PanelsideSearchSheetContextValue {
+  /**
+   * Whether the sheet is up.
+   *
+   * The field needs it, and cannot read it from being mounted: under `native`
+   * the platform owns presentation, so the content stays mounted for the life
+   * of the screen and only `isPresented` changes. An `autoFocus` on a field
+   * inside it would fire at app start, opening the keyboard over a sheet
+   * nobody has asked for.
+   */
+  open: boolean;
+  query: string;
+  setQuery: (query: string) => void;
+  tab: string;
+  setTab: (tab: string) => void;
+  close: () => void;
+  /** The inset the field already sits above, so docking does not travel it twice. */
+  bottomInset: number;
+}
+
+const PanelsideSearchSheetContext = createContext<PanelsideSearchSheetContextValue | null>(
+  null
+);
+
+function usePanelsideSearchSheet(part: string): PanelsideSearchSheetContextValue {
+  const value = useContext(PanelsideSearchSheetContext);
+  if (!value) throw new Error(`${part} must be used inside a <Panelside.SearchSheet>.`);
+  return value;
+}
+
+export interface PanelsideSearchSheetProps {
+  className?: string;
+  /** Controlled. Omit it and the sheet follows the root's `searchOpen`. */
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** The query. Controlled; pair it with `onValueChange`. */
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  /** Which tab is selected — the `value` of a `Panelside.SearchTab`. */
+  tab?: string;
+  /**
+   * Which tab starts selected, when the sheet is not controlling `tab`. Set it
+   * to the first tab's `value`: the expanding row shows the selected tab open
+   * and the rest as their icons, so with nothing selected every tab is closed
+   * and the row is a line of unlabelled glyphs.
+   */
+  defaultTab?: string;
+  onTabChange?: (tab: string) => void;
+  /**
+   * Present the platform's own sheet. Default true, because this one is the
+   * whole screen and the system's presentation, detents and dismiss gesture
+   * are the ones people already know. Requires the optional `@expo/ui`
+   * package; without it the styled sheet renders instead.
+   */
+  native?: boolean;
+  /** Heights the sheet can rest at. Defaults to the tall one. */
+  snapPoints?: BottomSheetProps['snapPoints'];
+  /** Gap between the field and the top of the keyboard. */
+  keyboardGap?: number;
+  /**
+   * Draw the round dismiss button at the leading edge of the top row. On by
+   * default — it is the way out of a surface that covers the screen, and it
+   * belongs where a thumb reaching across arrives rather than in the corner
+   * furthest from one.
+   */
+  showClose?: boolean;
+  /** What a screen reader announces for that button. */
+  closeLabel?: string;
+  children?: ReactNode;
+}
+
+/**
+ * The search surface: tabs, results, and a field at the bottom.
+ *
+ * ```tsx
+ * <Panelside.SearchSheet value={query} onValueChange={setQuery} tab={tab} onTabChange={setTab}>
+ *   <Panelside.SearchTabs>
+ *     <Panelside.SearchTab value="all" icon={<SparklesIcon size={16} />}>All</Panelside.SearchTab>
+ *     <Panelside.SearchTab value="chats" icon={<MessageCircleIcon size={16} />}>Chats</Panelside.SearchTab>
+ *   </Panelside.SearchTabs>
+ *
+ *   <Panelside.SearchResults>
+ *     {hits.map((hit) => (
+ *       <Panelside.SearchResult key={hit.id} title={hit.title} description={hit.kind} />
+ *     ))}
+ *   </Panelside.SearchResults>
+ *
+ *   <Panelside.SearchField placeholder="Search chats" />
+ * </Panelside.SearchSheet>
+ * ```
+ *
+ * Put it under `<Panelside>` and outside `Panelside.Panel` — a sheet is
+ * presented over the whole app, and the panel is a layer that slides.
+ *
+ * It reports what was typed and which tab is selected. What counts as a match,
+ * and what a result is, are yours: a search that only read chat titles would
+ * be wrong for the first app that indexes message bodies.
+ */
+function PanelsideSearchSheet({
+  className,
+  open: openProp,
+  onOpenChange,
+  value,
+  defaultValue = '',
+  onValueChange,
+  tab,
+  defaultTab = '',
+  onTabChange,
+  native = true,
+  snapPoints,
+  keyboardGap = 10,
+  showClose = true,
+  closeLabel = 'Close search',
+  children,
+}: PanelsideSearchSheetProps) {
+  const { searchOpen, setSearchOpen } = usePanelsideContext('Panelside.SearchSheet');
+  const insets = useSafeAreaInsets();
+  const { height: screenHeight } = useWindowDimensions();
+  const tint = useCSSVariable('--color-foreground');
+  const glyph = typeof tint === 'string' ? tint : undefined;
+
+  const [uncontrolledQuery, setUncontrolledQuery] = useState(defaultValue);
+  const [uncontrolledTab, setUncontrolledTab] = useState(defaultTab);
+
+  const open = openProp ?? searchOpen;
+  const query = value ?? uncontrolledQuery;
+  const activeTab = tab ?? uncontrolledTab;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (openProp === undefined) setSearchOpen(next);
+      onOpenChange?.(next);
+    },
+    [onOpenChange, openProp, setSearchOpen]
+  );
+
+  const setQuery = useCallback(
+    (next: string) => {
+      if (value === undefined) setUncontrolledQuery(next);
+      onValueChange?.(next);
+    },
+    [onValueChange, value]
+  );
+
+  const setTab = useCallback(
+    (next: string) => {
+      if (tab === undefined) setUncontrolledTab(next);
+      onTabChange?.(next);
+    },
+    [onTabChange, tab]
+  );
+
+  const close = useCallback(() => setOpen(false), [setOpen]);
+
+  const detents = snapPoints ?? (['full'] as const satisfies BottomSheetProps['snapPoints']);
+
+  /*
+   * What `BottomSheet.Content` pads the bottom of the sheet by. The field
+   * already sits that far above the screen edge, and docking travels by the
+   * keyboard's height less whatever the element has already cleared — so
+   * getting this wrong is a gap under the field, or the field over the
+   * keyboard's top row.
+   */
+  const bottomInset = Math.max(insets.bottom, SHEET_BOTTOM_PADDING) - keyboardGap;
+
+  /*
+   * A definite height for the column, not `flex-1` against the sheet's own.
+   *
+   * The platform sheet gives its hosted content a *minimum* height, and a
+   * minimum is not something `flex-1` can divide: the results list sizes to
+   * its own rows instead, grows past the sheet, and pushes the field off the
+   * bottom — which is a search surface with no way to type in it. So the
+   * column is told exactly how tall it is, and the list gets the room left
+   * between the tabs and the field.
+   *
+   * Only under the platform sheet. The styled one is laid out by us and has a
+   * real height already, so `flex-1` resolves there and a second opinion about
+   * how tall the sheet is would only be a chance to disagree with it.
+   */
+  const hosted = native && getNativeUI() !== null;
+  const columnHeight = hosted
+    ? (bottomSheetDetentHeight(detents as BottomSheetProps['snapPoints'], screenHeight) ??
+        screenHeight * 0.9) -
+      SHEET_TOP_PADDING -
+      Math.max(insets.bottom, SHEET_BOTTOM_PADDING)
+    : undefined;
+
+  const context = useMemo<PanelsideSearchSheetContextValue>(
+    () => ({ open, query, setQuery, tab: activeTab, setTab, close, bottomInset }),
+    [activeTab, bottomInset, close, open, query, setQuery, setTab]
+  );
+
+  return (
+    <BottomSheet
+      native={native}
+      open={open}
+      onOpenChange={setOpen}
+      snapPoints={detents as BottomSheetProps['snapPoints']}
+    >
+      {/*
+        `showClose` off on the sheet itself: this surface draws its own, at the
+        leading edge of the top row, where the reference for this pattern puts
+        it and where a thumb reaching across the screen arrives.
+      */}
+      <BottomSheet.Content size="full" showClose={false} className="gap-0 px-0 pt-3">
+        {/*
+          The provider is *inside* Content, not around the sheet.
+
+          The styled sheet mounts its content through a portal, under the
+          portal host and outside this component's subtree — so a provider
+          wrapped around the sheet is a provider the children never see, and
+          every part below throws about not being inside a `SearchSheet`. Only
+          the native path happened to work, because the platform hosts the
+          content in place.
+        */}
+        <PanelsideSearchSheetContext.Provider value={context}>
+          <View
+            className={cn('gap-2', columnHeight === undefined && 'flex-1', className)}
+            style={columnHeight === undefined ? undefined : { height: columnHeight }}
+          >
+            {showClose ? (
+              <View className="flex-row px-4 pb-1">
+                <AnimatedPressable
+                  onPress={close}
+                  accessibilityRole="button"
+                  accessibilityLabel={closeLabel}
+                  className="h-9 w-9 items-center justify-center rounded-full bg-secondary"
+                >
+                  <XIcon size={17} color={glyph} />
+                </AnimatedPressable>
+              </View>
+            ) : null}
+            {children}
+          </View>
+        </PanelsideSearchSheetContext.Provider>
+      </BottomSheet.Content>
+    </BottomSheet>
+  );
+}
+
+export interface PanelsideSearchTabsProps {
+  className?: string;
+  children?: ReactNode;
+}
+
+/**
+ * The row across the top of the search sheet, narrowing what is searched.
+ *
+ * The expanding variant: only the selected tab is open, and the rest are their
+ * icons. A row of four full labels takes the whole width to say four words
+ * nobody rereads, and this row has to leave the results the screen.
+ *
+ * Every `Panelside.SearchTab` therefore needs an `icon` — a closed tab has
+ * nothing else to be.
+ */
+function PanelsideSearchTabs({ className, children }: PanelsideSearchTabsProps) {
+  const { tab, setTab } = usePanelsideSearchSheet('Panelside.SearchTabs');
+
+  return (
+    <Tabs
+      variant="expanding"
+      value={tab}
+      onValueChange={setTab}
+      defaultValue={tab}
+      className={cn('px-4 pt-1', className)}
+    >
+      <Tabs.List>{children}</Tabs.List>
+    </Tabs>
+  );
+}
+
+export interface PanelsideSearchTabProps {
+  className?: string;
+  /** What selecting this tab reports as the sheet's `tab`. */
+  value: string;
+  /** Required: a closed tab is its icon and nothing else. */
+  icon: ReactNode;
+  children?: ReactNode;
+}
+
+function PanelsideSearchTab({ className, value, icon, children }: PanelsideSearchTabProps) {
+  return (
+    <Tabs.Trigger value={value} icon={icon} className={className}>
+      {children}
+    </Tabs.Trigger>
+  );
+}
+
+export interface PanelsideSearchResultsProps extends BottomSheetBodyProps {
+  className?: string;
+  contentContainerClassName?: string;
+  children?: ReactNode;
+}
+
+/**
+ * The scrolling middle of the search sheet.
+ *
+ * `BottomSheet.Body` rather than a `ScrollView`, so the list's scroll and the
+ * sheet's dismiss drag agree on which of them a downward pull belongs to.
+ */
+function PanelsideSearchResults({
+  className,
+  contentContainerClassName,
+  children,
+  ...props
+}: PanelsideSearchResultsProps) {
+  usePanelsideSearchSheet('Panelside.SearchResults');
+
+  return (
+    <BottomSheet.Body
+      className={cn('flex-1', className)}
+      contentContainerClassName={cn('gap-1 px-4 pb-4 pt-1', contentContainerClassName)}
+      keyboardShouldPersistTaps="handled"
+      keyboardDismissMode="interactive"
+      {...props}
+    >
+      {textChildren(children)}
+    </BottomSheet.Body>
+  );
+}
+
+export interface PanelsideSearchResultProps extends Omit<PressableProps, 'children'> {
+  className?: string;
+  /** Leading element — a thumbnail, an icon, an avatar. */
+  media?: ReactNode;
+  /** The result's name, truncated to one line. */
+  title?: string;
+  /** What kind of thing it is, or where it was found. */
+  description?: string;
+  children?: ReactNode;
+}
+
+/**
+ * One hit. A leading thumbnail, a title, and a line saying what it is.
+ *
+ * Taller than a `Panelside.Item`, and deliberately: a navigation row is a
+ * place you already know the name of, and a result is a thing you are deciding
+ * about — the second line is what the decision is made on.
+ */
+function PanelsideSearchResult({
+  className,
+  media,
+  title,
+  description,
+  children,
+  ...props
+}: PanelsideSearchResultProps) {
+  const tint = useCSSVariable('--color-muted-foreground');
+  const color = typeof tint === 'string' ? tint : undefined;
+
+  return (
+    <AnimatedPressable
+      className={cn('flex-row items-center gap-3 rounded-xl px-2 py-2', className)}
+      accessibilityRole="button"
+      accessibilityLabel={title}
+      pressScale={0.985}
+      {...props}
+    >
+      {media ? (
+        <View className="h-11 w-11 items-center justify-center overflow-hidden rounded-xl bg-secondary">
+          <IconColorProvider color={color}>{media}</IconColorProvider>
+        </View>
+      ) : null}
+      {title !== undefined || description !== undefined ? (
+        <View className="flex-1 gap-0.5">
+          {title !== undefined ? (
+            <Text size="base" weight="medium" numberOfLines={1}>
+              {title}
+            </Text>
+          ) : null}
+          {description !== undefined ? (
+            <Text size="sm" muted numberOfLines={1}>
+              {description}
+            </Text>
+          ) : null}
+        </View>
+      ) : null}
+      {children}
+    </AnimatedPressable>
+  );
+}
+
+export interface PanelsideSearchFieldProps extends TextInputProps {
+  className?: string;
+  containerClassName?: string;
+}
+
+/**
+ * The field, at the bottom of the sheet, riding the keyboard.
+ *
+ * At the bottom because that is where the thumb is and where the keyboard
+ * comes up: a field at the top of a full-height sheet is at the far end of the
+ * screen from both, and every character typed into it is read at the other
+ * end of a list that is moving.
+ *
+ * The way out of the surface is not here — `Panelside.SearchSheet` draws it at
+ * the leading edge of the top row, so the dismiss control does not move with
+ * the keyboard and is not one mis-tap away from the field.
+ */
+function PanelsideSearchField({
+  className,
+  containerClassName,
+  placeholder = 'Search',
+  value,
+  onChangeText,
+  ...props
+}: PanelsideSearchFieldProps) {
+  const { open, query, setQuery, bottomInset } = usePanelsideSearchSheet(
+    'Panelside.SearchField'
+  );
+  const placeholderTint = useCSSVariable('--color-muted-foreground');
+  const textTint = useCSSVariable('--color-foreground');
+  const muted = typeof placeholderTint === 'string' ? placeholderTint : undefined;
+  const field = useRef<TextInput>(null);
+
+  const text = value ?? query;
+  const change = onChangeText ?? setQuery;
+
+  /*
+   * Focus on the transition rather than with `autoFocus`. Under `native` the
+   * sheet's content is mounted for the life of the screen and only
+   * `isPresented` changes, so `autoFocus` fires once — at startup, on a sheet
+   * that is not up — and the keyboard opens over whatever is.
+   */
+  useEffect(() => {
+    if (open) field.current?.focus();
+    else field.current?.blur();
+  }, [open]);
+
+  return (
+    <KeyboardAvoider
+      mode="dock"
+      active={open}
+      bottomInset={bottomInset}
+      className="w-full px-4 pb-1"
+    >
+      <View
+        className={cn(
+          'h-12 w-full flex-row items-center gap-2 rounded-full bg-secondary px-4',
+          containerClassName
+        )}
+      >
+        <SearchIcon size={17} color={muted} />
+        <TextInput
+          ref={field}
+          value={text}
+          onChangeText={change}
+          placeholder={placeholder}
+          placeholderTextColor={muted}
+          /* `text-[16px]` rather than a `text-*` step — see Panelside.Search. */
+          className={cn('h-full flex-1 font-normal text-[16px] text-foreground', className)}
+          style={typeof textTint === 'string' ? { color: textTint } : undefined}
+          accessibilityRole="search"
+          returnKeyType="search"
+          {...props}
+        />
+        {text.length > 0 ? (
+          <AnimatedPressable
+            onPress={() => change('')}
+            hitSlop={8}
+            accessibilityRole="button"
+            accessibilityLabel="Clear search"
+            className="h-5 w-5 items-center justify-center rounded-full bg-muted"
+          >
+            <XIcon size={12} color={muted} />
+          </AnimatedPressable>
+        ) : null}
+      </View>
+
+    </KeyboardAvoider>
+  );
+}
+
 PanelsidePanel.displayName = 'Panelside.Panel';
 PanelsideHeader.displayName = 'Panelside.Header';
 PanelsideSearch.displayName = 'Panelside.Search';
@@ -1597,6 +2305,13 @@ PanelsideFooter.displayName = 'Panelside.Footer';
 PanelsideCta.displayName = 'Panelside.Cta';
 PanelsideScene.displayName = 'Panelside.Scene';
 PanelsideTrigger.displayName = 'Panelside.Trigger';
+PanelsideSearchTrigger.displayName = 'Panelside.SearchTrigger';
+PanelsideSearchSheet.displayName = 'Panelside.SearchSheet';
+PanelsideSearchTabs.displayName = 'Panelside.SearchTabs';
+PanelsideSearchTab.displayName = 'Panelside.SearchTab';
+PanelsideSearchResults.displayName = 'Panelside.SearchResults';
+PanelsideSearchResult.displayName = 'Panelside.SearchResult';
+PanelsideSearchField.displayName = 'Panelside.SearchField';
 
 export const Panelside = Object.assign(PanelsideRoot, {
   Panel: PanelsidePanel,
@@ -1614,4 +2329,11 @@ export const Panelside = Object.assign(PanelsideRoot, {
   Cta: PanelsideCta,
   Scene: PanelsideScene,
   Trigger: PanelsideTrigger,
+  SearchTrigger: PanelsideSearchTrigger,
+  SearchSheet: PanelsideSearchSheet,
+  SearchTabs: PanelsideSearchTabs,
+  SearchTab: PanelsideSearchTab,
+  SearchResults: PanelsideSearchResults,
+  SearchResult: PanelsideSearchResult,
+  SearchField: PanelsideSearchField,
 });