panelui-native 0.83.0 → 0.85.0

package/src/components/popover/index.tsx

@@ -30,6 +30,7 @@
  * and jump into place.
  */
 import {
+  Children,
   cloneElement,
   createContext,
   isValidElement,
@@ -62,6 +63,7 @@ import { useSafeAreaInsets } from 'react-native-safe-area-context';
 import { FocusRestorePortal } from '../../primitives/portal';
 import { Scrim } from '../../primitives/scrim';
 import { useBackHandler } from '../../hooks/use-back-handler';
+import { NativeHost, getSwiftUI } from '../../native';
 import { BottomSheet } from '../bottom-sheet';
 import { Text, type TextProps, textChildren } from '../../primitives/text';
 import { cn } from '../../utils/cn';
@@ -116,6 +118,8 @@ interface PopoverContextValue {
   setArrowOffset: (offset: number) => void;
   /** Whether Content is presenting as a bottom sheet — Arrow is null then. */
   presentation: PopoverPresentation;
+  /** Whether the platform is drawing the panel. Trigger and Content both read it. */
+  native: boolean;
 }
 
 export type PopoverPresentation = 'popover' | 'bottom-sheet';
@@ -176,6 +180,30 @@ export interface PopoverProps {
    * sheet.
    */
   presentation?: PopoverPresentation;
+  /**
+   * Present the platform's own popover instead of this one. Requires the
+   * optional `@expo/ui`.
+   *
+   * **iOS only.** SwiftUI has a popover that anchors to a view and keeps its
+   * anchored shape on a phone rather than becoming a sheet; Compose's nearest
+   * relative is a dropdown menu, which is a different control with different
+   * rules. Android and web keep the styled panel, as does an iOS device
+   * without `@expo/ui` installed.
+   *
+   * **The platform draws the container, so theme tokens do not reach it.** The
+   * panel's surface, its corner radius, its shadow and its arrow are the
+   * system's; `className` on `Popover.Content` styles what is *inside* it.
+   * `align`, `offset`, `alignOffset`, `scrim` and `blur` have no native
+   * equivalent and are ignored; `placement` becomes the edge the arrow is
+   * asked for.
+   *
+   * **Give the content a `width`.** The platform sizes its popover to what is
+   * hosted in it, and a React Native subtree with no width of its own has
+   * nothing to report — the same rule that governs every hosted view.
+   * `Popover.Content` defaults to a sensible one under `native`, but a panel
+   * whose rows need more room should say so.
+   */
+  native?: boolean;
 }
 
 function PopoverRoot({
@@ -184,6 +212,7 @@ function PopoverRoot({
   onOpenChange,
   defaultOpen = false,
   presentation = 'popover',
+  native = false,
 }: PopoverProps) {
   const [internalOpen, setInternalOpen] = useState(defaultOpen);
   const [trigger, setTrigger] = useState<TriggerRect | null>(null);
@@ -201,6 +230,16 @@ function PopoverRoot({
     [isControlled, onOpenChange]
   );
 
+  /*
+   * The platform's popover, where it is reachable and the caller asked for it.
+   *
+   * A sheet presentation is left alone: `native` names which popover to draw,
+   * and asking for both a sheet and a popover is a contradiction rather than a
+   * combination.
+   */
+  const swiftUI = native && presentation === 'popover' ? getSwiftUI() : null;
+  const nativeActive = swiftUI !== null;
+
   const context = useMemo(
     () => ({
       open: resolvedOpen,
@@ -212,11 +251,95 @@ function PopoverRoot({
       arrowOffset,
       setArrowOffset,
       presentation,
+      native: nativeActive,
     }),
-    [resolvedOpen, setOpen, trigger, placement, arrowOffset, presentation]
+    [resolvedOpen, setOpen, trigger, placement, arrowOffset, presentation, nativeActive]
   );
 
-  return <PopoverContext.Provider value={context}>{children}</PopoverContext.Provider>;
+  return (
+    <PopoverContext.Provider value={context}>
+      {swiftUI ? <NativePopover swiftUI={swiftUI}>{children}</NativePopover> : children}
+    </PopoverContext.Provider>
+  );
+}
+
+/** Default width for a hosted panel, in points. Room for a short menu row. */
+const NATIVE_PANEL_WIDTH = 240;
+
+/** `placement` in the platform's vocabulary. */
+const ARROW_EDGE = {
+  top: 'top',
+  bottom: 'bottom',
+  left: 'leading',
+  right: 'trailing',
+} as const;
+
+/**
+ * The platform's popover, with our trigger and our content hosted inside it.
+ *
+ * SwiftUI attaches a popover to a view, so the two halves this component keeps
+ * as siblings have to become parent and child: the trigger is what the panel
+ * points at, and the platform will not anchor to something it cannot see. So
+ * the children are read here and placed into the two slots the platform
+ * expects, rather than the caller having to write a different tree under
+ * `native` than without it.
+ *
+ * Both halves are React Native, so both are wrapped in the host view that lets
+ * the platform measure them. The trigger is given no press handling of its
+ * own — `Popover.Trigger` already toggles the state this reads, and the
+ * platform presents from that.
+ */
+function NativePopover({
+  swiftUI,
+  children,
+}: {
+  swiftUI: NonNullable<ReturnType<typeof getSwiftUI>>;
+  children: ReactNode;
+}) {
+  const { open, setOpen } = usePopover('Popover');
+  const { Host, RNHostView, Popover: PlatformPopover } = swiftUI;
+
+  let trigger: ReactNode = null;
+  let content: ReactElement<PopoverContentProps> | null = null;
+
+  for (const child of Children.toArray(children)) {
+    if (!isValidElement(child)) continue;
+    if (child.type === PopoverTrigger) trigger = child;
+    else if (child.type === PopoverContent) {
+      content = child as ReactElement<PopoverContentProps>;
+    }
+  }
+
+  const contentProps = content?.props;
+  const width =
+    typeof contentProps?.width === 'number' ? contentProps.width : NATIVE_PANEL_WIDTH;
+
+  return (
+    <NativeHost host={Host} matchContents ignoreSafeArea="keyboard">
+      <PlatformPopover
+        isPresented={open}
+        onIsPresentedChange={setOpen}
+        arrowEdge={ARROW_EDGE[contentProps?.placement ?? 'bottom']}
+      >
+        <PlatformPopover.Trigger>
+          <RNHostView matchContents>{trigger}</RNHostView>
+        </PlatformPopover.Trigger>
+        <PlatformPopover.Content>
+          <RNHostView matchContents>
+            {/*
+              An explicit width, not a class. Inside the host there is no
+              parent for a percentage or a flex basis to resolve against, so a
+              panel that does not state its width reports none and the platform
+              sizes its popover to nothing.
+            */}
+            <View style={{ width }} className={cn('gap-1 p-2', contentProps?.className)}>
+              {textChildren(contentProps?.children)}
+            </View>
+          </RNHostView>
+        </PlatformPopover.Content>
+      </PlatformPopover>
+    </NativeHost>
+  );
 }
 
 export interface PopoverTriggerProps {
@@ -231,7 +354,7 @@ export interface PopoverTriggerProps {
  * and only a wrapper we own is guaranteed to be measurable.
  */
 function PopoverTrigger({ children }: PopoverTriggerProps) {
-  const { open, setOpen, setTrigger } = usePopover('Popover.Trigger');
+  const { open, setOpen, setTrigger, native } = usePopover('Popover.Trigger');
   const ref = useRef<View>(null);
 
   const measureThenToggle = (...args: unknown[]) => {
@@ -242,6 +365,17 @@ function PopoverTrigger({ children }: PopoverTriggerProps) {
       return;
     }
 
+    /*
+     * Nothing to measure when the platform is drawing the panel: it anchors to
+     * this trigger itself, and asking a view hosted inside the native tree for
+     * its window coordinates is a callback that may never come back — which
+     * would leave the press doing nothing at all.
+     */
+    if (native) {
+      setOpen(true);
+      return;
+    }
+
     // Measured on every open rather than on layout: the trigger may have
     // scrolled since it was laid out, and a stale rect anchors the panel to
     // where the trigger used to be.
@@ -363,7 +497,8 @@ function PopoverContent({
   ...props
 }: PopoverContentProps) {
   const context = usePopover('Popover.Content');
-  const { open, setOpen, trigger, setPlacement, setArrowOffset, presentation } = context;
+  const { open, setOpen, trigger, setPlacement, setArrowOffset, presentation, native } =
+    context;
 
   // The anchored panel owns the Android back button while it is up. The sheet
   // presentation is left alone — BottomSheet installs its own handler.
@@ -509,6 +644,13 @@ function PopoverContent({
    * the surface it is merged into the sheet's own padding classes and replaces
    * them, so a panel asking for `p-3` silently strips the sheet's `px-5 pt-2`.
    */
+  /*
+   * Already drawn. Under `native` the root reads this element's props and
+   * hosts its children inside the platform's own popover, so rendering the
+   * styled panel here as well would put a second one on the screen.
+   */
+  if (native) return null;
+
   if (presentation === 'bottom-sheet') {
     return (
       <BottomSheet open={open} onOpenChange={setOpen}>

package/src/components/select/index.tsx

@@ -63,7 +63,7 @@ import Animated, {
 import { tv } from 'tailwind-variants';
 import { useCSSVariable } from 'uniwind';
 import { CheckIcon, ChevronDownIcon, SearchIcon } from '../../icons';
-import { getNativeUI } from '../../native';
+import { NativeHost, getNativeUI } from '../../native';
 import { Portal } from '../../primitives/portal';
 import { Text, textChildren } from '../../primitives/text';
 import { useBackHandler } from '../../hooks/use-back-handler';
@@ -568,7 +568,7 @@ function SelectRoot({
       // A picker fills the width of the row it sits in and reports its own
       // height — a menu is a compact button, a wheel a full rotor, and the
       // platform is the only thing that knows which by how much.
-      <Host matchContents={{ vertical: true }} ignoreSafeArea="keyboard">
+      <NativeHost host={Host} matchContents={{ vertical: true }} ignoreSafeArea="keyboard">
         <Picker
           selectedValue={value ?? firstEnabled?.value ?? ''}
           onValueChange={(next: string) => onValueChange(next)}
@@ -579,7 +579,7 @@ function SelectRoot({
             <Picker.Item key={option.value} label={option.label} value={option.value} />
           ))}
         </Picker>
-      </Host>
+      </NativeHost>
     );
   }
 

package/src/components/slider/index.tsx

@@ -42,7 +42,7 @@ import Animated, {
 } from 'react-native-reanimated';
 import { tv, type VariantProps } from 'tailwind-variants';
 import { useDirectionSign } from '../../hooks/use-direction';
-import { getNativeUI } from '../../native';
+import { NativeHost, getNativeUI } from '../../native';
 import { Text } from '../../primitives/text';
 import { selectionTick } from '../../utils/haptics';
 
@@ -102,6 +102,15 @@ const sliderVariants = tv({
 /** Thumb width per size. Wider than it is tall, so the pill reads as a grip. */
 const THUMB_WIDTH: Record<'sm' | 'md' | 'lg', number> = { sm: 24, md: 28, lg: 32 };
 
+/**
+ * The box the platform slider is given, in points.
+ *
+ * Both platforms draw a slider shorter than this and centre it, so the number
+ * is the row's height rather than the control's — and at 44 it is also the
+ * smallest a thing you drag is allowed to be.
+ */
+const NATIVE_SLIDER_HEIGHT = 44;
+
 type SliderVariantProps = VariantProps<typeof sliderVariants>;
 
 export interface SliderProps extends Omit<SliderVariantProps, 'disabled'> {
@@ -564,10 +573,23 @@ export const Slider = forwardRef<View, SliderProps>(
       return (
         <View ref={ref} className={slots.root({ className })}>
           {header}
-          {/* A slider has no intrinsic width — it fills whatever it is given —
-              so the width comes from ordinary layout and only the height is
-              matched to the platform's content. */}
-          <Host matchContents={{ vertical: true }} ignoreSafeArea="keyboard">
+          {/*
+            Neither axis is left to the platform.
+
+            A slider has no intrinsic width — it fills whatever it is given —
+            so ordinary layout was always going to decide that. The height was
+            being matched, and matching is not a one-off: the host writes the
+            platform's measured size back into the layout on every geometry
+            change, so the row's height moved whenever the control was touched
+            and everything below it moved with it. The height is stated
+            instead.
+          */}
+          <NativeHost
+            host={Host}
+            matchContents={false}
+            ignoreSafeArea="keyboard"
+            style={{ height: NATIVE_SLIDER_HEIGHT }}
+          >
             <NativeSlider
               value={value}
               onValueChange={(next: number) => {
@@ -578,7 +600,7 @@ export const Slider = forwardRef<View, SliderProps>(
               step={step}
               disabled={disabled}
             />
-          </Host>
+          </NativeHost>
         </View>
       );
     }

package/src/components/switch/index.tsx

@@ -8,7 +8,7 @@ import Animated, {
 } from 'react-native-reanimated';
 import { tv, type VariantProps } from 'tailwind-variants';
 import { useDirectionSign } from '../../hooks/use-direction';
-import { getNativeUI } from '../../native';
+import { NativeHost, getNativeUI } from '../../native';
 import { selectionTick } from '../../utils/haptics';
 import { useFieldLabelledBy } from '../field';
 
@@ -79,6 +79,15 @@ export interface SwitchProps
  * Animated switch. Thumb position and active-track opacity are driven on the
  * UI thread; toggling never re-renders beyond the value change itself.
  */
+/**
+ * The box the platform toggle is given, in points.
+ *
+ * Taller than either platform's switch — 31 on iOS, 32 on Android — so the
+ * control is never clipped by the box it is centred in, and short enough that
+ * a row built around it is still a row.
+ */
+const NATIVE_TOGGLE_HEIGHT = 32;
+
 export const Switch = forwardRef<View, SwitchProps>(
   (
     {
@@ -124,18 +133,30 @@ export const Switch = forwardRef<View, SwitchProps>(
     if (nativeUI) {
       const { Host, Switch: NativeSwitch } = nativeUI;
       return (
-        // A platform toggle has a definite intrinsic size on both platforms,
-        // so the host is left to follow it. Pinning the host to a number
-        // instead is what leaves the control laid out against a box it never
-        // agreed to, and settling into it a frame later.
-        <Host matchContents ignoreSafeArea="keyboard">
+        /*
+         * The height is stated; only the width is matched.
+         *
+         * `matchContents` hands an axis to the platform for good — the host
+         * writes the measured size back into the layout every time the
+         * platform's geometry changes, not once on mount — and the vertical
+         * axis is the one that moves everything below it when it does. A
+         * toggle's height is the one number here that does not vary, so it is
+         * given rather than asked for; its width is the platform's and stays
+         * the platform's.
+         */
+        <NativeHost
+          host={Host}
+          matchContents={{ horizontal: true }}
+          ignoreSafeArea="keyboard"
+          style={{ height: NATIVE_TOGGLE_HEIGHT }}
+        >
           <NativeSwitch
             value={value}
             onValueChange={(next: boolean) => onValueChange?.(next)}
             label={label ?? accessibilityLabel}
             disabled={disabled}
           />
-        </Host>
+        </NativeHost>
       );
     }
 

package/src/icons/index.tsx

@@ -50,6 +50,7 @@
  * outline could only ignore. All four are drawn here rather than mapped.
  */
 import { createContext, useContext, type ReactNode } from 'react';
+import { View } from 'react-native';
 import { HugeiconsIcon, type IconSvgElement } from '@hugeicons/react-native';
 import Svg, { G, Path, type SvgProps } from 'react-native-svg';
 import { useDirection } from '../hooks/use-direction';
@@ -208,17 +209,37 @@ function icon(glyph: IconSvgElement, defaults: IconDefaults) {
   }: ToggleIconProps) {
     const resolved = useResolvedColor(color, defaults.color);
     const rtl = useDirection() === 'rtl';
-    return (
+
+    const drawing = (
       <HugeiconsIcon
         icon={glyph}
         size={size}
         color={resolved}
         strokeWidth={strokeWidth ?? defaults.strokeWidth ?? STROKE}
         fill={defaults.fillable && filled ? resolved : 'none'}
-        style={defaults.flip ? [{ transform: [{ scaleX: rtl ? -1 : 1 }] }, style] : style}
+        style={defaults.flip ? undefined : style}
         {...props}
       />
     );
+
+    if (!defaults.flip) return drawing;
+
+    /*
+     * The mirror goes on a view around the glyph, not on the glyph.
+     *
+     * The drawing component takes a `style` prop and drops it: it destructures
+     * `style` out of its props and never puts it back, and the interop layer
+     * that would otherwise have carried it is a package this library does not
+     * use. A transform handed to it is silently discarded, which is a chevron
+     * that keeps pointing right in a right-to-left row — and a failure with
+     * nothing to see, since every other prop on the same element does arrive.
+     *
+     * A plain view cannot lose it. It also puts the caller's own `style` back
+     * on the outside, where it is applied rather than thrown away.
+     */
+    return (
+      <View style={[{ transform: [{ scaleX: rtl ? -1 : 1 }] }, style]}>{drawing}</View>
+    );
   }
 
   return Icon;

package/src/index.ts

@@ -222,6 +222,15 @@ export {
   type FlowRect,
   type FlowPoint,
 } from './components/flow';
+export {
+  FlipCard,
+  useFlipCard,
+  type FlipCardProps,
+  type FlipCardFaceProps,
+  type FlipCardDirection,
+  type FlipCardRotation,
+  type FlipCardTrigger,
+} from './components/flip-card';
 export {
   FunnelChart,
   useFunnelChart,
@@ -421,6 +430,7 @@ export {
   type ChipVariant,
   type ChipSize,
 } from './components/chip';
+export { CircularText, type CircularTextProps } from './components/circular-text';
 export {
   Collapsible,
   type CollapsibleProps,
@@ -557,12 +567,6 @@ export {
   type PanelsidePageProps,
   type PanelsideTriggerProps,
   type PanelsideSearchTriggerProps,
-  type PanelsideSearchSheetProps,
-  type PanelsideSearchTabsProps,
-  type PanelsideSearchTabProps,
-  type PanelsideSearchResultsProps,
-  type PanelsideSearchResultProps,
-  type PanelsideSearchFieldProps,
   type PanelsideMode,
   type PanelsideSwipeFrom,
   type PanelsideItemSize,

package/src/native/index.ts

@@ -18,25 +18,40 @@
  * **Theme tokens do not apply in native mode.** The platform draws the control
  * with its own colours, metrics and typography — that is the entire point, and
  * it means `className` and the variant props are ignored on those components.
+ *
+ * The one exception is which appearance it draws: `colorScheme` is the single
+ * theme signal the toolkit accepts, and `NativeHost` is what passes it. Mount
+ * every host through that rather than reaching for `Host` directly, or the
+ * control resolves its own appearance from the system and stops tracking the
+ * app's theme.
  */
 import { Platform } from 'react-native';
 import type { ComponentType, ReactNode } from 'react';
 
+export { NativeHost, type NativeHostProps } from './native-host';
+
 interface NativeUIModule {
   Host: ComponentType<{
     children?: ReactNode;
     /**
-     * Whether the host resizes itself to the platform content.
+     * Which axes the platform is allowed to size.
      *
-     * This is on for every control here, and it is the whole answer to the
-     * jump. Sizing the *host* and leaving the control unsized inside it hands
-     * the platform a box it never agreed to: it lays out against its own
-     * intrinsic size, and settles into the box on the first thing that forces
-     * a second pass — which for a button is the first press.
+     * **It is not a one-off measurement.** An axis given to `matchContents` is
+     * given for good: the host writes the platform's measured size straight
+     * into the layout every time the platform's geometry changes, and dirties
+     * the layout when it does. So a control that lays itself out again under a
+     * press drags its box with it, and everything below it moves — which is
+     * the defect this spent three attempts on, twice reasoning about the first
+     * measurement when the problem was every one after it.
      *
-     * The per-axis form is for a control with no intrinsic width, like a
-     * slider or a picker: the width comes from ordinary layout and only the
-     * height is reported back.
+     * The rule that comes out of that: **never hand over an axis whose size
+     * you already know.** State it in `style` instead and match only what is
+     * genuinely the platform's — a labelled button's width, a toggle's width.
+     * An axis left out is never written to, so an explicit size on it is safe.
+     *
+     * Where nothing can be stated the axis has to stay matched. A picker is
+     * the honest example: a menu is a compact button and a wheel is a rotor,
+     * and only the platform knows which it drew.
      */
     matchContents?: boolean | { vertical?: boolean; horizontal?: boolean };
     /**
@@ -56,6 +71,14 @@ interface NativeUIModule {
      * platform's business and stay its business.
      */
     ignoreSafeArea?: 'all' | 'container' | 'keyboard';
+    /**
+     * The appearance the platform draws the hosted control in.
+     *
+     * Passed by `NativeHost` from the app's own theme, because the host would
+     * otherwise resolve it from the system — which is a different question,
+     * and one whose answer does not change when the theme does.
+     */
+    colorScheme?: 'light' | 'dark';
     style?: unknown;
     [key: string]: unknown;
   }>;
@@ -161,6 +184,63 @@ interface SwiftUIModifiers {
   presentationBackground: (color: string) => unknown;
 }
 
+/**
+ * The SwiftUI-only components, for the ones the universal set does not carry.
+ *
+ * `@expo/ui` exports a portable component for everything both toolkits agree
+ * on, and that is what `getNativeUI` reaches. A popover is not on that list:
+ * SwiftUI has one that anchors to a view and adapts itself on a compact
+ * screen, and Compose's nearest relative is a dropdown menu, which is a
+ * different control with different rules. Rather than pretend the two are one
+ * thing, the iOS one is reached here and Android keeps the styled panel.
+ */
+interface SwiftUIComponents {
+  Host: ComponentType<{
+    children?: ReactNode;
+    matchContents?: boolean | { vertical?: boolean; horizontal?: boolean };
+    ignoreSafeArea?: 'all' | 'container' | 'keyboard';
+    /** As on the portable host above — see `NativeHost`. */
+    colorScheme?: 'light' | 'dark';
+    style?: unknown;
+  }>;
+  RNHostView: ComponentType<{ children?: ReactNode; matchContents?: boolean }>;
+  Popover: ComponentType<{
+    children?: ReactNode;
+    isPresented?: boolean;
+    onIsPresentedChange?: (isPresented: boolean) => void;
+    attachmentAnchor?: 'leading' | 'trailing' | 'center' | 'top' | 'bottom';
+    arrowEdge?: 'leading' | 'trailing' | 'top' | 'bottom' | 'none';
+  }> & {
+    Trigger: ComponentType<{ children?: ReactNode }>;
+    Content: ComponentType<{ children?: ReactNode }>;
+  };
+}
+
+let swiftUIResolved = false;
+let swiftUI: SwiftUIComponents | null = null;
+
+export function getSwiftUI(): SwiftUIComponents | null {
+  if (swiftUIResolved) return swiftUI;
+  swiftUIResolved = true;
+
+  if (Platform.OS !== 'ios') return null;
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const module = require('@expo/ui/swift-ui') as Partial<SwiftUIComponents>;
+    // A version without the popover is not an error; it is a fallback to the
+    // styled panel, which is what every missing native path here does.
+    swiftUI =
+      module.Host && module.RNHostView && module.Popover
+        ? (module as SwiftUIComponents)
+        : null;
+  } catch {
+    swiftUI = null;
+  }
+
+  return swiftUI;
+}
+
 let modifiersResolved = false;
 let modifiers: SwiftUIModifiers | null = null;
 

package/src/native/native-host.tsx

@@ -0,0 +1,75 @@
+/**
+ * The host every native control is mounted in, told which appearance to draw.
+ *
+ * A hosting controller resolves its colour scheme from the trait environment
+ * it is placed in, which is the system appearance — not the theme the app is
+ * running. Those are the same thing only by coincidence: an app in a dark
+ * theme on a phone set to light gets a light platform control beside dark
+ * content, and a theme changed at runtime leaves the control where it was,
+ * because nothing in the trait environment moved.
+ *
+ * So the appearance is passed rather than inferred. `colorScheme` is the one
+ * theme signal the platform toolkit accepts, and this is the single place it
+ * is given.
+ *
+ * ```tsx
+ * const { Host, Switch: NativeSwitch } = nativeUI;
+ * <NativeHost host={Host} matchContents ignoreSafeArea="keyboard">
+ *   <NativeSwitch value={on} onValueChange={setOn} />
+ * </NativeHost>
+ * ```
+ *
+ * ## Why the host arrives as a prop
+ *
+ * There are two of them. The universal `Host` comes from `getNativeUI()` and
+ * the SwiftUI-only one from `getSwiftUI()`, and a caller has already resolved
+ * whichever it needs before it renders. Taking the component rather than
+ * resolving it again keeps this file free of the module bridge, which is what
+ * lets the bridge re-export it without the two importing each other.
+ *
+ * ## Why this is a component rather than a hook at each call site
+ *
+ * `useThemeMode` subscribes to theme changes, and a hook cannot be called
+ * conditionally — so reading it inside `Button` would put a subscription on
+ * every button in a list for a branch almost none of them take. Here the
+ * subscription exists only where a native host is actually mounted.
+ */
+import type { ComponentType, ReactNode } from 'react';
+import { useThemeMode } from '../theme/use-theme';
+
+/**
+ * What this renders the host with. A type alias rather than an interface, and
+ * that is load-bearing: only an alias gets an implicit index signature, which
+ * is what makes it assignable to the bridge's own `Host` prop type.
+ */
+type NativeHostRenderProps = {
+  children?: ReactNode;
+  colorScheme?: 'light' | 'dark';
+  matchContents?: boolean | { vertical?: boolean; horizontal?: boolean };
+  ignoreSafeArea?: 'all' | 'container' | 'keyboard';
+  style?: unknown;
+};
+
+export interface NativeHostProps {
+  /**
+   * The host component to render — `Host` from `getNativeUI()` for a portable
+   * control, or from `getSwiftUI()` for an iOS-only one.
+   */
+  host: ComponentType<NativeHostRenderProps>;
+  children?: ReactNode;
+  /** Whether the host resizes itself to the platform content. */
+  matchContents?: boolean | { vertical?: boolean; horizontal?: boolean };
+  /** Which safe areas the host lets the platform inset its content for. */
+  ignoreSafeArea?: 'all' | 'container' | 'keyboard';
+  style?: unknown;
+}
+
+export function NativeHost({ host: Host, children, ...props }: NativeHostProps) {
+  const { mode } = useThemeMode();
+
+  return (
+    <Host colorScheme={mode} {...props}>
+      {children}
+    </Host>
+  );
+}