panelui-native 0.80.0 → 0.82.0

package/src/components/panelside/index.tsx

@@ -77,6 +77,7 @@
  * rather than travelling.
  */
 import {
+  Children,
   cloneElement,
   createContext,
   isValidElement,
@@ -90,6 +91,7 @@ import {
   type ReactNode,
 } from 'react';
 import {
+  Keyboard,
   Platform,
   Pressable,
   ScrollView,
@@ -117,7 +119,12 @@ 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, XIcon } from '../../icons';
+import { HugeiconsIcon, type IconSvgElement } from '@hugeicons/react-native';
+import Cancel01Icon from '@hugeicons/core-free-icons/Cancel01Icon';
+import Menu01Icon from '@hugeicons/core-free-icons/Menu01Icon';
+import MoreHorizontalIcon from '@hugeicons/core-free-icons/MoreHorizontalIcon';
+import Search01Icon from '@hugeicons/core-free-icons/Search01Icon';
+import { IconColorProvider, useIconColor } from '../../icons';
 import {
   BottomSheet,
   bottomSheetDetentHeight,
@@ -125,6 +132,7 @@ import {
   type BottomSheetProps,
 } from '../bottom-sheet';
 import { Button } from '../button';
+import { Menu, type MenuContentProps } from '../menu';
 import { Tabs } from '../tabs';
 import { getNativeUI } from '../../native';
 import { AnimatedPressable } from '../../primitives/animated-pressable';
@@ -268,10 +276,64 @@ const clamp = (value: number, min: number, max: number) => {
   return Math.min(Math.max(value, min), max);
 };
 
+/**
+ * The stroke weight the panel's glyphs are drawn at.
+ *
+ * A shade heavier than the icon set's own default. The panel sits over a
+ * dimmed screen and its rows are quiet by design, so a hairline glyph goes
+ * soft against them at the sizes used here.
+ */
+const GLYPH_STROKE = 1.8;
+
+/**
+ * What a glyph is drawn in when nothing has said. The same neutral the rest of
+ * the chrome falls back to — visible against either theme, and never the thing
+ * that decides how a panel looks, since every surface here provides a colour.
+ */
+const GLYPH_FALLBACK = '#737373';
+
+/**
+ * Floor for a row's action menu.
+ *
+ * Wide enough for a verb and its glyph with the label doing the growing. Left
+ * to size itself, a menu takes its width from the one thing in each row that
+ * is not flexible — the glyph — and comes up as a column of icons.
+ */
+const ACTIONS_MIN_WIDTH = 220;
+
+/**
+ * One of the panel's own glyphs.
+ *
+ * It exists to keep the colour contract the rest of the library has: an icon
+ * takes an explicit colour, then the one an enclosing surface is providing,
+ * and only then falls back. The drawing component underneath knows nothing
+ * about that inheritance and needs the resolved value handed to it.
+ */
+function Glyph({
+  icon,
+  size = 20,
+  color,
+}: {
+  icon: IconSvgElement;
+  size?: number;
+  color?: string;
+}) {
+  const inherited = useIconColor();
+
+  return (
+    <HugeiconsIcon
+      icon={icon}
+      size={size}
+      color={color ?? inherited ?? GLYPH_FALLBACK}
+      strokeWidth={GLYPH_STROKE}
+    />
+  );
+}
+
 export type PanelsideMode = 'push' | 'overlay';
 export type PanelsideSwipeFrom = 'anywhere' | 'edge';
 export type PanelsideItemSize = 'default' | 'sm';
-export type PanelsideCtaSize = 'default' | 'lg';
+export type PanelsideCtaSize = 'default' | 'lg' | 'xl';
 /**
  * What a header or a footer paints behind itself.
  *
@@ -281,6 +343,8 @@ export type PanelsideCtaSize = 'default' | 'lg';
  * that is a row of the layout rather than something floating over one.
  */
 export type PanelsideSurface = 'transparent' | 'fade' | 'solid';
+/** How the panel's small round controls are drawn: a fill, or a ring. */
+export type PanelsideControlVariant = 'filled' | 'outline';
 
 const itemVariants = tv({
   // No width: in a group it stretches on its own, and pinning it to full width
@@ -322,6 +386,7 @@ const ctaVariants = tv({
     size: {
       default: 'h-11 gap-2 px-6',
       lg: 'h-13 gap-2.5 px-7',
+      xl: 'h-14 gap-3 px-8',
     },
   },
   defaultVariants: {
@@ -356,6 +421,15 @@ interface PanelsideContextValue {
    */
   searchOpen: boolean;
   setSearchOpen: (open: boolean) => void;
+  /**
+   * The page the scene is showing.
+   *
+   * On the root for the same reason `searchOpen` is: the rows that navigate
+   * are in the panel and the pages are in the scene, which are different
+   * subtrees. Anything else is one `useState` every app threads through both.
+   */
+  route: string;
+  navigate: (route: string) => void;
 }
 
 const PanelsideContext = createContext<PanelsideContextValue | null>(null);
@@ -383,6 +457,10 @@ export interface UsePanelsideResult {
   /** Whether the search surface is up. `Panelside.SearchTrigger` sets it. */
   searchOpen: boolean;
   setSearchOpen: (open: boolean) => void;
+  /** The page the scene is showing — a `Panelside.Page`'s `value`. */
+  route: string;
+  /** Go to a page, closing the panel on the way. */
+  navigate: (route: string) => void;
 }
 
 /**
@@ -391,9 +469,20 @@ export interface UsePanelsideResult {
  * lives.
  */
 export function usePanelside(): UsePanelsideResult {
-  const { open, setOpen, toggle, progress, docked, searchOpen, setSearchOpen } =
+  const { open, setOpen, toggle, progress, docked, searchOpen, setSearchOpen, route, navigate } =
     usePanelsideContext('usePanelside');
-  return { open, setOpen, toggle, progress, docked, searchOpen, setSearchOpen };
+
+  // `navigate` closes the panel. The root cannot do it there without making
+  // its own `setOpen` a dependency of the callback every row holds.
+  const go = useCallback(
+    (next: string) => {
+      navigate(next);
+      setOpen(false);
+    },
+    [navigate, setOpen]
+  );
+
+  return { open, setOpen, toggle, progress, docked, searchOpen, setSearchOpen, route, navigate: go };
 }
 
 /**
@@ -489,6 +578,19 @@ export interface PanelsideProps {
   radius?: number;
   /** How far the scene is dimmed at full open, 0 to 1. */
   dim?: number;
+  /**
+   * Which page the scene is showing. Controlled; pair it with `onRouteChange`.
+   *
+   * A route is any string you choose. It is matched against
+   * `Panelside.Page`'s `value` and against `Panelside.Item`'s `to`, so a row
+   * marks itself as the current destination and the scene swaps to the page
+   * without either being wired to the other.
+   */
+  route?: string;
+  /** Which page the scene starts on, when the panel is not controlling `route`. */
+  defaultRoute?: string;
+  /** Called with the route a row navigated to. */
+  onRouteChange?: (route: string) => void;
   className?: string;
 }
 
@@ -508,6 +610,9 @@ function PanelsideRoot({
   scale,
   radius,
   dim,
+  route: controlledRoute,
+  defaultRoute = '',
+  onRouteChange,
   className,
 }: PanelsideProps) {
   const { width: windowWidth } = useWindowDimensions();
@@ -518,6 +623,23 @@ function PanelsideRoot({
   const open = controlled ? controlledOpen : uncontrolledOpen;
   const [searchOpen, setSearchOpen] = useState(false);
 
+  const [uncontrolledRoute, setUncontrolledRoute] = useState(defaultRoute);
+  const route = controlledRoute ?? uncontrolledRoute;
+
+  /*
+   * Navigating closes the panel, and does so here rather than at each call
+   * site. The thing you just moved to would otherwise be behind the thing you
+   * moved from, which is the one arrangement no app wants — and a row that has
+   * to be told to close is a row every app writes the same three lines for.
+   */
+  const navigate = useCallback(
+    (next: string) => {
+      if (controlledRoute === undefined) setUncontrolledRoute(next);
+      onRouteChange?.(next);
+    },
+    [controlledRoute, onRouteChange]
+  );
+
   /*
    * Measured rather than taken from the window, because Panelside does not
    * have to be the whole screen — it can be one tab of a larger layout, and
@@ -695,15 +817,19 @@ function PanelsideRoot({
       dim,
       searchOpen,
       setSearchOpen,
+      route,
+      navigate,
     }),
     [
       dim,
       dismissible,
       docked,
       mode,
+      navigate,
       open,
       progress,
       radius,
+      route,
       scale,
       searchOpen,
       setOpen,
@@ -908,7 +1034,7 @@ function PanelsideSearch({
         containerClassName
       )}
     >
-      <SearchIcon size={16} color={muted} />
+      <Glyph icon={Search01Icon} size={16} color={muted} />
       <TextInput
         placeholder={placeholder}
         placeholderTextColor={muted}
@@ -1032,7 +1158,20 @@ export interface PanelsideItemProps extends Omit<PressableProps, 'children'> {
    * shorthand for `Panelside.ItemLabel`.
    */
   label?: string;
-  /** Marks the row as the current destination. */
+  /**
+   * The page this row goes to — a `Panelside.Page`'s `value`.
+   *
+   * Pressing it sets the panel's route, and the row marks itself active while
+   * that route is the current one. It also closes the panel, since the thing
+   * you just moved to would otherwise be behind the thing you moved from.
+   *
+   * `active` and `onPress` still win where they are passed, so a row can
+   * navigate and do something else as well.
+   */
+  to?: string;
+  /** Leave the panel open after navigating. Off by default. */
+  closeOnNavigate?: boolean;
+  /** Marks the row as the current destination. Derived from `to` when given. */
   active?: boolean;
   /**
    * Trailing count or status. A number or string renders as a pill; anything
@@ -1081,16 +1220,34 @@ function PanelsideItem({
   className,
   icon,
   label,
-  active = false,
+  to,
+  closeOnNavigate = true,
+  active: activeProp,
   badge,
   disabled = false,
   size = 'default',
+  onPress,
   children,
   ...props
 }: PanelsideItemProps) {
+  const panel = useContext(PanelsideContext);
   const restTint = useCSSVariable('--color-muted-foreground');
   const activeTint = useCSSVariable('--color-foreground');
 
+  // A row outside a `<Panelside>` still works — the parts are usable on their
+  // own — it simply has no route to match against.
+  const active = activeProp ?? (to !== undefined && panel?.route === to);
+
+  const press = useCallback(
+    (event: Parameters<NonNullable<PressableProps['onPress']>>[0]) => {
+      onPress?.(event);
+      if (to === undefined || !panel) return;
+      panel.navigate(to);
+      if (closeOnNavigate) panel.setOpen(false);
+    },
+    [closeOnNavigate, onPress, panel, to]
+  );
+
   const tint = active
     ? typeof activeTint === 'string'
       ? activeTint
@@ -1110,8 +1267,16 @@ function PanelsideItem({
    * that, and a written-out `Panelside.ItemLabel` supplies it too — so the
    * spacer is only for the row that has neither, which is a row of nothing but
    * an icon and a badge.
+   *
+   * And only where there is something to push. A row of nothing but an icon
+   * has no trailing content, and a spacer in it is not inert: laid out against
+   * the width available rather than against the row's own contents, it expands,
+   * takes the space with it, and squeezes whatever shares the line — which is
+   * how an icon-only row in a footer beside a compose button cropped that
+   * button's label and left its own icon short of the trailing edge.
    */
   const filled = label !== undefined || children !== undefined;
+  const trailing = badge !== undefined && badge !== null;
 
   return (
     <PanelsideItemContext.Provider value={context}>
@@ -1122,13 +1287,14 @@ function PanelsideItem({
         accessibilityState={{ selected: active, disabled }}
         accessibilityLabel={label}
         pressScale={0.985}
+        onPress={to !== undefined || onPress ? press : undefined}
         {...props}
       >
         {icon ? <PanelsideItemIcon>{icon}</PanelsideItemIcon> : null}
 
         {label !== undefined ? <PanelsideItemLabel>{label}</PanelsideItemLabel> : null}
 
-        {filled ? null : <View className="flex-1" />}
+        {filled || !trailing ? null : <View className="flex-1" />}
 
         {badge !== undefined && badge !== null ? (
           <PanelsideItemBadge>{badge}</PanelsideItemBadge>
@@ -1233,6 +1399,7 @@ function PanelsideAction({
   className,
   label = 'More options',
   children,
+  onPress,
   ...props
 }: PanelsideActionProps) {
   const tint = useCSSVariable('--color-muted-foreground');
@@ -1246,13 +1413,97 @@ function PanelsideAction({
       // The glyph is small and sits next to a row-sized target, so it takes
       // the difference back as slop rather than as layout.
       hitSlop={8}
+      // The row underneath is pressable and usually navigates. A press that
+      // reached both would open the menu and leave the thing it is about.
+      onPress={(event) => {
+        event.stopPropagation();
+        onPress?.(event);
+      }}
       {...props}
     >
-      {children ?? <EllipsisIcon size={18} color={color} />}
+      {children ?? <Glyph icon={MoreHorizontalIcon} size={18} color={color} />}
     </AnimatedPressable>
   );
 }
 
+export interface PanelsideItemActionsProps {
+  className?: string;
+  /**
+   * What a screen reader announces for the button. The control is an
+   * unlabelled glyph, so this is the only description it has.
+   */
+  label?: string;
+  /** Replaces the default overflow glyph. */
+  icon?: ReactNode;
+  /** Where the panel opens relative to the button. Defaults to below it. */
+  placement?: MenuContentProps['placement'];
+  /** How it lines up on that edge. Defaults to the button's trailing edge. */
+  align?: MenuContentProps['align'];
+  /**
+   * Floor for the menu's width. A panel sized to its contents takes its width
+   * from whatever inside it is not flexible — in a row of a flexible label and
+   * a fixed glyph, that is the glyph, and the menu comes up as a column of
+   * icons with the words squeezed out of it.
+   */
+  minWidth?: number;
+  /** Passed through to the panel — `width`, `maxHeight`, `offset` and the rest. */
+  contentProps?: Omit<MenuContentProps, 'children' | 'placement' | 'align' | 'minWidth'>;
+  /** The rows: `Menu.Item`, `Menu.Separator`, `Menu.Label`. */
+  children?: ReactNode;
+}
+
+/**
+ * A row's actions, behind an overflow button at the end of it.
+ *
+ * ```tsx
+ * <Panelside.Item label={chat.title} to={chat.id}>
+ *   <Panelside.ItemActions>
+ *     <Menu.Item onSelect={rename}>Rename</Menu.Item>
+ *     <Menu.Separator />
+ *     <Menu.Item variant="destructive" onSelect={remove}>Delete</Menu.Item>
+ *   </Panelside.ItemActions>
+ * </Panelside.Item>
+ * ```
+ *
+ * The panel is anchored to the button rather than presented from the bottom of
+ * the screen, so it lines up with the row it belongs to and the list it came
+ * from stays readable behind it. It is also narrow: the panel it opens in is a
+ * fraction of the screen, and a sheet covering that to offer four verbs costs
+ * more than it says.
+ *
+ * Pressing the button does not press the row. A row that navigates would
+ * otherwise navigate away from the thing the menu is about.
+ */
+function PanelsideItemActions({
+  className,
+  label = 'More options',
+  icon,
+  placement = 'bottom',
+  align = 'end',
+  minWidth = ACTIONS_MIN_WIDTH,
+  contentProps,
+  children,
+}: PanelsideItemActionsProps) {
+  return (
+    <Menu>
+      <Menu.Trigger>
+        <PanelsideAction className={className} label={label}>
+          {icon}
+        </PanelsideAction>
+      </Menu.Trigger>
+      <Menu.Content
+        placement={placement}
+        align={align}
+        width="content-fit"
+        minWidth={minWidth}
+        {...contentProps}
+      >
+        {children}
+      </Menu.Content>
+    </Menu>
+  );
+}
+
 export interface PanelsideFooterProps extends ViewProps {
   className?: string;
   /**
@@ -1364,6 +1615,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 },
+  hidden: { display: 'none' },
 });
 
 export interface PanelsideCtaProps extends Omit<PressableProps, 'children'> {
@@ -1378,10 +1630,11 @@ export interface PanelsideCtaProps extends Omit<PressableProps, 'children'> {
    * 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.
+   * in the row, and `xl` is 56pt.
    *
    * Ignored under `native` — the platform sizes its own button, and asks for a
-   * control size rather than a height.
+   * control size rather than a height. The three steps reach the platform's
+   * regular, large and extra-large controls.
    */
   size?: PanelsideCtaSize;
   /**
@@ -1430,7 +1683,7 @@ function PanelsideCta({
         glass={glass}
         // The platform sizes a native button from its label, so a height means
         // nothing here — the step is asked for as a control size instead.
-        size={size === 'lg' ? 'lg' : 'md'}
+        size={size === 'default' ? 'md' : size}
         variant={variant}
         accessibilityLabel={label}
         // Pressable allows `null` for disabled; Button does not.
@@ -1448,7 +1701,7 @@ function PanelsideCta({
           React view in it to pad, and hosting one to get a view leaves a width
           nothing knows in advance.
 
-          So this one is sized rather than padded — `size="lg"` reaches the
+          So this one is sized rather than padded — the size reaches the
           platform as a control size, which scales the room the style leaves
           around the label and the label with it.
         */}
@@ -1661,6 +1914,115 @@ function PanelsideScene({
   );
 }
 
+export interface PanelsidePagesProps extends ViewProps {
+  className?: string;
+  /** `Panelside.Page` elements. Anything else is rendered as given. */
+  children?: ReactNode;
+}
+
+/**
+ * The pages the panel navigates between.
+ *
+ * Put it inside `Panelside.Scene` and give each page a `value` that a row's
+ * `to` matches. Nothing is wired between the two: the row sets the panel's
+ * route, and the page whose value equals it is the one shown.
+ *
+ * ```tsx
+ * <Panelside.Scene>
+ *   <Panelside.Pages>
+ *     <Panelside.Page value="inbox"><Inbox /></Panelside.Page>
+ *     <Panelside.Page value="drafts"><Drafts /></Panelside.Page>
+ *   </Panelside.Pages>
+ * </Panelside.Scene>
+ * ```
+ *
+ * A page is mounted the first time it is visited and stays mounted after
+ * that, hidden rather than removed. Going back to one is then a style change
+ * rather than a mount: its list does not rebuild, its scroll position is where
+ * you left it, and whatever it was fetching is already there. A page whose
+ * contents go stale — or whose data is large enough that keeping it is worse
+ * than fetching it again — takes `keepAlive={false}`.
+ */
+function PanelsidePages({ className, children, ...props }: PanelsidePagesProps) {
+  const { route } = usePanelsideContext('Panelside.Pages');
+
+  /*
+   * Which pages have ever been the route.
+   *
+   * A `Set` in state rather than a ref: mounting a page for the first time has
+   * to be a render, and the ref would not cause one. It only ever grows, and
+   * only by one entry per page, so the identity change per first visit costs
+   * nothing after the pages have all been seen once.
+   */
+  const [visited, setVisited] = useState<readonly string[]>(() => [route]);
+
+  useEffect(() => {
+    setVisited((current) => (current.includes(route) ? current : [...current, route]));
+  }, [route]);
+
+  return (
+    <View className={cn('flex-1', className)} {...props}>
+      {Children.map(children, (child) => {
+        if (!isValidElement<PanelsidePageProps>(child) || child.type !== PanelsidePage) {
+          return child;
+        }
+
+        const { value, keepAlive = true } = child.props;
+        const current = value === route;
+        if (!current && (!keepAlive || !visited.includes(value))) return null;
+
+        return cloneElement(child, { hidden: !current });
+      })}
+    </View>
+  );
+}
+
+export interface PanelsidePageProps extends ViewProps {
+  className?: string;
+  /** What a row's `to` has to equal for this page to be the one shown. */
+  value: string;
+  /**
+   * Keep the page mounted once it has been visited. Default true, which is
+   * what makes going back to it instant. Off, it is torn down on the way out
+   * and rebuilt on the way in.
+   */
+  keepAlive?: boolean;
+  /**
+   * Set by `Panelside.Pages`. A hidden page is laid out by nobody, is not in
+   * the accessibility tree, and takes no touches — but it is still mounted,
+   * which is the whole point of it.
+   */
+  hidden?: boolean;
+  children?: ReactNode;
+}
+
+/** One page. Only meaningful inside `Panelside.Pages`. */
+function PanelsidePage({
+  className,
+  value,
+  keepAlive,
+  hidden = false,
+  children,
+  style,
+  ...props
+}: PanelsidePageProps) {
+  // `display: none` rather than unmounting, and rather than opacity: it takes
+  // the page out of layout entirely, so a hidden page costs no measurement,
+  // while its component tree — and everything it is holding — stays.
+  return (
+    <View
+      accessibilityElementsHidden={hidden}
+      importantForAccessibility={hidden ? 'no-hide-descendants' : 'auto'}
+      pointerEvents={hidden ? 'none' : 'auto'}
+      style={[hidden ? styles.hidden : null, style]}
+      className={cn('flex-1', className)}
+      {...props}
+    >
+      {textChildren(children)}
+    </View>
+  );
+}
+
 export interface PanelsideTriggerProps extends Omit<PressableProps, 'children'> {
   className?: string;
   /** What a screen reader announces. */
@@ -1708,7 +2070,7 @@ function PanelsideTrigger({
       accessibilityRole="button"
       accessibilityLabel={label}
     >
-      <MenuIcon size={20} color={color} />
+      <Glyph icon={Menu01Icon} size={20} color={color} />
     </AnimatedPressable>
   );
 }
@@ -1738,6 +2100,17 @@ export interface PanelsideSearchTriggerProps extends Omit<PressableProps, 'child
   className?: string;
   /** What a screen reader announces. */
   label?: string;
+  /**
+   * `filled` is the default: a circle in the secondary surface, which is what
+   * a control sitting alone on the panel's own surface needs to read as one.
+   *
+   * `outline` is a ring and no fill, for a panel whose other controls are
+   * outlined too — a filled circle among them is the only thing on the screen
+   * claiming to be a second primary.
+   *
+   * Ignored under `native`, where the platform owns the button's chrome.
+   */
+  variant?: PanelsideControlVariant;
   /** Replaces the default magnifier. */
   children?: ReactNode;
   /**
@@ -1762,6 +2135,7 @@ export interface PanelsideSearchTriggerProps extends Omit<PressableProps, 'child
 function PanelsideSearchTrigger({
   className,
   label = 'Search',
+  variant = 'filled',
   children,
   native = false,
   glass = false,
@@ -1780,7 +2154,7 @@ function PanelsideSearchTrigger({
     [onPress, setSearchOpen]
   );
 
-  const glyph = children ?? <SearchIcon size={18} color={native ? color : undefined} />;
+  const glyph = children ?? <Glyph icon={Search01Icon} size={18} color={native ? color : undefined} />;
 
   if (native) {
     return (
@@ -1802,10 +2176,12 @@ function PanelsideSearchTrigger({
       {...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',
+        'h-10 w-10 items-center justify-center rounded-full',
+        // Filled by default. 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 — which stops being true the
+        // moment the rest of the screen's controls are outlined as well.
+        variant === 'outline' ? 'border border-border' : 'bg-secondary',
         className
       )}
       accessibilityRole="button"
@@ -1885,6 +2261,22 @@ export interface PanelsideSearchSheetProps {
   showClose?: boolean;
   /** What a screen reader announces for that button. */
   closeLabel?: string;
+  /**
+   * How that button is drawn. Matches `Panelside.SearchTrigger`'s `variant`,
+   * so the control that opens the surface and the one that closes it are the
+   * same shape.
+   */
+  closeVariant?: PanelsideControlVariant;
+  /**
+   * Draw that button as the platform's own, the way `Panelside.SearchTrigger`
+   * does. Independent of `native` on the sheet itself: the surface can be ours
+   * while the two controls on either end of it are the platform's, which is
+   * the arrangement a native screen wants when the sheet's own presentation
+   * cannot hold this content.
+   */
+  closeNative?: boolean;
+  /** Draw that native button in the platform's Liquid Glass material. */
+  closeGlass?: boolean;
   children?: ReactNode;
 }
 
@@ -1930,6 +2322,9 @@ function PanelsideSearchSheet({
   keyboardGap = 10,
   showClose = true,
   closeLabel = 'Close search',
+  closeVariant = 'filled',
+  closeNative = false,
+  closeGlass = false,
   children,
 }: PanelsideSearchSheetProps) {
   const { searchOpen, setSearchOpen } = usePanelsideContext('Panelside.SearchSheet');
@@ -1945,8 +2340,20 @@ function PanelsideSearchSheet({
   const query = value ?? uncontrolledQuery;
   const activeTab = tab ?? uncontrolledTab;
 
+  /*
+   * Closing takes the keyboard with it, wherever the close came from — the
+   * button, a drag on the sheet, or the system back gesture.
+   *
+   * Leaving it to the field's own blur is too late. The field blurs when
+   * `open` goes false, but the sheet is already on its way out by then: the
+   * styled one unmounts its portal after the exit animation, and the platform
+   * one keeps its content mounted and only stops presenting it. Either way the
+   * blur lands on a field nothing can see, and the keyboard stays up until the
+   * system notices for itself, some seconds later, that nothing is focused.
+   */
   const setOpen = useCallback(
     (next: boolean) => {
+      if (!next) Keyboard.dismiss();
       if (openProp === undefined) setSearchOpen(next);
       onOpenChange?.(next);
     },
@@ -2039,14 +2446,30 @@ function PanelsideSearchSheet({
           >
             {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>
+                {closeNative ? (
+                  <Button
+                    native
+                    glass={closeGlass}
+                    size="icon"
+                    variant="ghost"
+                    accessibilityLabel={closeLabel}
+                    onPress={close}
+                  >
+                    <Glyph icon={Cancel01Icon} size={17} color={glyph} />
+                  </Button>
+                ) : (
+                  <AnimatedPressable
+                    onPress={close}
+                    accessibilityRole="button"
+                    accessibilityLabel={closeLabel}
+                    className={cn(
+                      'h-9 w-9 items-center justify-center rounded-full',
+                      closeVariant === 'outline' ? 'border border-border' : 'bg-secondary'
+                    )}
+                  >
+                    <Glyph icon={Cancel01Icon} size={17} color={glyph} />
+                  </AnimatedPressable>
+                )}
               </View>
             ) : null}
             {children}
@@ -2059,6 +2482,20 @@ function PanelsideSearchSheet({
 
 export interface PanelsideSearchTabsProps {
   className?: string;
+  /**
+   * Where the row sits across the sheet. Default `center`.
+   *
+   * Centred because only the selected tab is open and the rest are their
+   * icons, so the row's width changes as you move through it — anchored to the
+   * leading edge that change reads as the row growing and shrinking, and
+   * centred it reads as the selection moving.
+   *
+   * `start` anchors it to the leading edge, for a sheet whose tabs are wide
+   * enough to fill the row anyway.
+   */
+  align?: 'start' | 'center';
+  /** Applied to the row itself rather than to the box around it. */
+  listClassName?: string;
   children?: ReactNode;
 }
 
@@ -2072,7 +2509,12 @@ export interface PanelsideSearchTabsProps {
  * Every `Panelside.SearchTab` therefore needs an `icon` — a closed tab has
  * nothing else to be.
  */
-function PanelsideSearchTabs({ className, children }: PanelsideSearchTabsProps) {
+function PanelsideSearchTabs({
+  className,
+  align = 'center',
+  listClassName,
+  children,
+}: PanelsideSearchTabsProps) {
   const { tab, setTab } = usePanelsideSearchSheet('Panelside.SearchTabs');
 
   return (
@@ -2083,7 +2525,9 @@ function PanelsideSearchTabs({ className, children }: PanelsideSearchTabsProps)
       defaultValue={tab}
       className={cn('px-4 pt-1', className)}
     >
-      <Tabs.List>{children}</Tabs.List>
+      <Tabs.List className={cn(align === 'center' && 'justify-center', listClassName)}>
+        {children}
+      </Tabs.List>
     </Tabs>
   );
 }
@@ -2099,7 +2543,11 @@ export interface PanelsideSearchTabProps {
 
 function PanelsideSearchTab({ className, value, icon, children }: PanelsideSearchTabProps) {
   return (
-    <Tabs.Trigger value={value} icon={icon} className={className}>
+    // A step of padding above the tab row's own. This row is the only control
+    // on a surface that is otherwise a list and a field, and a closed tab here
+    // is a glyph with nothing else to be aimed at by — so it is sized to be
+    // hit rather than to the density a row of labelled tabs can afford.
+    <Tabs.Trigger value={value} icon={icon} className={cn('px-4 py-3', className)}>
       {children}
     </Tabs.Trigger>
   );
@@ -2253,13 +2701,24 @@ function PanelsideSearchField({
       bottomInset={bottomInset}
       className="w-full px-4 pb-1"
     >
+      {/*
+        An opaque surface with a ring, not the secondary tint the rest of the
+        panel's controls use.
+
+        The field rides the keyboard by translating rather than by taking a row
+        of the layout, so once it is up the results are directly behind it —
+        and the secondary token is a few percent of a colour, which the list
+        then reads straight through, taking the placeholder with it. The ring
+        is what a floating pill needs to have an edge once its fill is the same
+        colour as most of the sheet.
+      */}
       <View
         className={cn(
-          'h-12 w-full flex-row items-center gap-2 rounded-full bg-secondary px-4',
+          'h-12 w-full flex-row items-center gap-2 rounded-full border border-border bg-surface px-4 shadow-lg',
           containerClassName
         )}
       >
-        <SearchIcon size={17} color={muted} />
+        <Glyph icon={Search01Icon} size={17} color={muted} />
         <TextInput
           ref={field}
           value={text}
@@ -2281,7 +2740,7 @@ function PanelsideSearchField({
             accessibilityLabel="Clear search"
             className="h-5 w-5 items-center justify-center rounded-full bg-muted"
           >
-            <XIcon size={12} color={muted} />
+            <Glyph icon={Cancel01Icon} size={12} color={muted} />
           </AnimatedPressable>
         ) : null}
       </View>
@@ -2301,9 +2760,12 @@ PanelsideItemIcon.displayName = 'Panelside.ItemIcon';
 PanelsideItemLabel.displayName = 'Panelside.ItemLabel';
 PanelsideItemBadge.displayName = 'Panelside.ItemBadge';
 PanelsideAction.displayName = 'Panelside.Action';
+PanelsideItemActions.displayName = 'Panelside.ItemActions';
 PanelsideFooter.displayName = 'Panelside.Footer';
 PanelsideCta.displayName = 'Panelside.Cta';
 PanelsideScene.displayName = 'Panelside.Scene';
+PanelsidePages.displayName = 'Panelside.Pages';
+PanelsidePage.displayName = 'Panelside.Page';
 PanelsideTrigger.displayName = 'Panelside.Trigger';
 PanelsideSearchTrigger.displayName = 'Panelside.SearchTrigger';
 PanelsideSearchSheet.displayName = 'Panelside.SearchSheet';
@@ -2325,9 +2787,12 @@ export const Panelside = Object.assign(PanelsideRoot, {
   ItemLabel: PanelsideItemLabel,
   ItemBadge: PanelsideItemBadge,
   Action: PanelsideAction,
+  ItemActions: PanelsideItemActions,
   Footer: PanelsideFooter,
   Cta: PanelsideCta,
   Scene: PanelsideScene,
+  Pages: PanelsidePages,
+  Page: PanelsidePage,
   Trigger: PanelsideTrigger,
   SearchTrigger: PanelsideSearchTrigger,
   SearchSheet: PanelsideSearchSheet,