panelui-native 0.84.0 → 0.86.0

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/components/tabs/index.tsx

@@ -225,8 +225,6 @@ interface TabsContextValue {
   registerLayout: (value: string, layout: TabLayout) => void;
   layouts: Record<string, TabLayout>;
   variant: TabsVariant;
-  scrollable: boolean;
-  setScrollable: (scrollable: boolean) => void;
   keepMounted: TabsKeepMounted;
   /**
    * Whether the panels are in a strip rather than stacked in place.
@@ -241,6 +239,23 @@ interface TabsContextValue {
 
 const TabsContext = createContext<TabsContextValue | null>(null);
 
+/**
+ * Whether the row the trigger is in scrolls, published by that row.
+ *
+ * It is a `Tabs.List` prop and it decides a trigger's width — intrinsic in a
+ * scroller, an equal share in a fixed row — so the two have to agree in the
+ * commit they are laid out in. Routed through the root it arrived one commit
+ * late: every trigger was measured once at its equal-share position, the
+ * indicator snapped to that geometry because it was the first measurement it
+ * had, and the second pass moved everything. With enough tabs to need a
+ * scroller in the first place, the gap between the two geometries is most of
+ * the row.
+ *
+ * Separate from the root's context so it can be provided by the list, and
+ * defaulted so a trigger outside one still resolves.
+ */
+const TabsListContext = createContext(false);
+
 function useTabs(component: string): TabsContextValue {
   const context = useContext(TabsContext);
   if (!context) {
@@ -371,9 +386,6 @@ function TabsRoot({
 }: TabsProps) {
   const [internalValue, setInternalValue] = useState(defaultValue);
   const [layouts, setLayouts] = useState<Record<string, TabLayout>>({});
-  // Published by the List rather than the root, because it is the List that
-  // decides whether it scrolls — but the Triggers below it need to know.
-  const [scrollable, setScrollable] = useState(false);
   const isControlled = value !== undefined;
   const resolvedValue = isControlled ? value : internalValue;
   const animationDisabled = animation === 'disable-all';
@@ -415,8 +427,6 @@ function TabsRoot({
       registerLayout,
       layouts,
       variant,
-      scrollable,
-      setScrollable,
       keepMounted,
       pager: paged,
       animationDisabled,
@@ -427,7 +437,6 @@ function TabsRoot({
       registerLayout,
       layouts,
       variant,
-      scrollable,
       keepMounted,
       paged,
       animationDisabled,
@@ -481,9 +490,23 @@ function TabsPager({
 
   const order = useMemo(() => panels.map((panel) => panel.props.value), [panels]);
   const count = panels.length;
-  // An unknown value shows the first panel rather than none of them: a tab set
-  // with nothing in it is a harder thing to debug than one showing the wrong tab.
-  const active = Math.max(0, order.indexOf(value));
+  /*
+   * The index of the value, or the last one that resolved.
+   *
+   * A value that is not among the panels is a moment rather than a state: a
+   * controlled parent part-way through an update, panels rebuilt from a `map`
+   * whose keys changed. Falling back to zero for that moment springs the strip
+   * to the first panel and back, which is a visible flicker for something that
+   * was never wrong. Holding the last index shows the panel that was already
+   * there until the new one arrives.
+   *
+   * Zero remains the answer when nothing has ever resolved — a tab set with
+   * nothing in it is a harder thing to debug than one showing the wrong tab.
+   */
+  const resolved = order.indexOf(value);
+  const lastResolved = useRef(0);
+  if (resolved >= 0) lastResolved.current = resolved;
+  const active = resolved >= 0 ? resolved : Math.min(lastResolved.current, count - 1);
 
   const [width, setWidth] = useState(0);
   const position = useSharedValue(active);
@@ -640,9 +663,22 @@ function TabsPager({
     [sign, commit, position, start, dragging, widthValue, countValue]
   );
 
-  const strip = useAnimatedStyle(() => ({
-    transform: [{ translateX: -position.value * widthValue.value * sign }],
-  }));
+  /*
+   * The width comes in as the React value, not through `widthValue`.
+   *
+   * `widthValue` is mirrored from state in an effect, so it is a commit behind
+   * — and the commit it is behind by is the one where the strip first appears.
+   * For that frame the transform evaluated to `-position × 0`, which is panel
+   * zero on screen whichever tab is active: the tab set opened on the first
+   * panel and jumped to the right one. Reading `width` here re-creates the
+   * style when it changes, so the first frame of the strip is already in the
+   * right place. `widthValue` is still what the gesture reads, because a
+   * worklet cannot see React state.
+   */
+  const strip = useAnimatedStyle(
+    () => ({ transform: [{ translateX: -position.value * width * sign }] }),
+    [width, sign]
+  );
 
   const onLayout = useCallback((event: LayoutChangeEvent) => {
     const measured = event.nativeEvent.layout;
@@ -755,27 +791,54 @@ export interface TabsListProps extends ViewProps {
   children: ReactNode;
 }
 
+/**
+ * Where the active tab should sit in the scroller, or null when it cannot be
+ * known yet.
+ *
+ * A little in from the edge rather than flush against it, so the tab does not
+ * read as the last one in the row.
+ */
+function scrollTarget(layout: TabLayout | undefined): number | null {
+  if (!layout) return null;
+  return Math.max(layout.x - 24, 0);
+}
+
 function TabsList({ className, scrollable = false, children, ...props }: TabsListProps) {
-  const { variant, setScrollable, value, layouts } = useTabs('Tabs.List');
+  const { variant, value, layouts } = useTabs('Tabs.List');
   const { list } = tabsVariants({ variant });
   const scroller = useRef<ScrollView>(null);
 
-  useEffect(() => {
-    setScrollable(scrollable);
-  }, [scrollable, setScrollable]);
+  /*
+   * Where the row should be, kept as a ref rather than only applied once.
+   *
+   * A horizontal scroller does not always keep its offset when its content is
+   * laid out again, and the row is laid out again on every switch — so the
+   * scroller can be left at zero, showing the first tab, with nothing in this
+   * component's state disagreeing. Re-applying the target from
+   * `onContentSizeChange` puts it back where the selection says it should be.
+   */
+  const target = scrollTarget(layouts[value]);
+  const targetRef = useRef<number | null>(target);
+  targetRef.current = target;
+  const settled = useRef(false);
 
-  // Bring the active tab into view when it changes from elsewhere — a
+  // Bring the active tab into view when the selection changes — a press, a
   // controlled switch, or a swipe on the panel below.
-  const activeLayout = layouts[value];
   useEffect(() => {
-    if (!scrollable || !activeLayout) return;
+    if (!scrollable || target === null) return;
     scroller.current?.scrollTo({
-      // Land the tab a little in from the edge rather than flush against it,
-      // so it does not read as the last one in the row.
-      x: Math.max(activeLayout.x - 24, 0),
-      animated: true,
+      x: target,
+      // The first measurement has nowhere to travel from: animating it is a
+      // row that visibly slides into place as the screen appears.
+      animated: settled.current,
     });
-  }, [scrollable, activeLayout?.x, activeLayout]);
+    settled.current = true;
+  }, [scrollable, value, target]);
+
+  const restore = useCallback(() => {
+    if (!scrollable || targetRef.current === null) return;
+    scroller.current?.scrollTo({ x: targetRef.current, animated: false });
+  }, [scrollable]);
 
   const row = (
     <View {...props} accessibilityRole="tablist" className={cn(list(), className)}>
@@ -786,7 +849,14 @@ function TabsList({ className, scrollable = false, children, ...props }: TabsLis
     </View>
   );
 
-  if (!scrollable) return row;
+  /*
+   * The triggers are told whether they are in a scroller here rather than
+   * through the root, so their width and the row they are measured in belong to
+   * one commit. See {@link TabsListContext}.
+   */
+  const scoped = <TabsListContext.Provider value={scrollable}>{row}</TabsListContext.Provider>;
+
+  if (!scrollable) return scoped;
 
   return (
     <ScrollView
@@ -796,8 +866,9 @@ function TabsList({ className, scrollable = false, children, ...props }: TabsLis
       // The row measures itself, and the indicator is positioned against it,
       // so the scroller must not stretch it to the viewport width.
       contentContainerStyle={{ flexGrow: 0 }}
+      onContentSizeChange={restore}
     >
-      {row}
+      {scoped}
     </ScrollView>
   );
 }
@@ -826,20 +897,30 @@ function TabsTrigger({
   children,
 }: TabsTriggerProps) {
   const context = useTabs('Tabs.Trigger');
+  const scrollable = useContext(TabsListContext);
   const active = context.value === value;
   const slots = tabsVariants({
     variant: context.variant,
     active,
     disabled,
-    scrollable: context.scrollable,
+    scrollable,
   });
 
+  /*
+   * Bound to `registerLayout` alone, which is stable for the life of the tab
+   * set — not to the whole context, which is rebuilt every time any trigger
+   * registers. Depending on the context made this a new function on every
+   * measurement, so a layout burst handed every trigger a new `onLayout` for
+   * every *other* trigger's measurement: quadratic prop updates in exactly the
+   * case that has enough tabs to be slow.
+   */
+  const { registerLayout } = context;
   const handleLayout = useCallback(
     (event: LayoutChangeEvent) => {
       const { x, width } = event.nativeEvent.layout;
-      context.registerLayout(value, { x, width });
+      registerLayout(value, { x, width });
     },
-    [context, value]
+    [registerLayout, value]
   );
 
   if (context.variant === 'expanding') {

package/src/hooks/use-keyboard-avoidance.ts

@@ -46,6 +46,7 @@
  */
 import { useCallback, useEffect, useState } from 'react';
 import {
+  TurboModuleRegistry,
   useWindowDimensions,
   type LayoutChangeEvent,
   type View,
@@ -117,12 +118,44 @@ export interface UseKeyboardAvoidanceResult {
 type KeyboardHeightHook = () => SharedValue<number>;
 
 /**
- * Resolved once, at module load, so the hook below always calls the same
- * underlying hook — swapping between them per render would break the rules of
- * hooks.
+ * Whether the controller's native module is actually in this client.
+ *
+ * Resolving the package is not the same as being able to use it: in Expo Go the
+ * JavaScript is in `node_modules` and requires cleanly, and every call into it
+ * throws from a proxy that reports the package as unlinked. A `try`/`catch`
+ * around the require never sees that, because it happens later.
+ */
+function nativeControllerPresent(): boolean {
+  try {
+    return TurboModuleRegistry.get('KeyboardController') !== null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolved on the first render rather than at module load, and then never
+ * again.
+ *
+ * The resolution asks the native module registry a question, and this module is
+ * reachable from the package's root entry — so at module scope that question
+ * was being asked while a consuming app was still evaluating its imports,
+ * before the runtime had finished standing up. By the first render it is up.
+ *
+ * Caching it is what keeps the rules of hooks: `useKeyboardHeight` always calls
+ * the same underlying hook, because the implementation is chosen once and
+ * cannot change afterwards.
  */
-const useKeyboardHeight: KeyboardHeightHook = (() => {
+let keyboardHeightImpl: KeyboardHeightHook | undefined;
+
+function useKeyboardHeight(): SharedValue<number> {
+  if (!keyboardHeightImpl) keyboardHeightImpl = resolveKeyboardHeight();
+  return keyboardHeightImpl();
+}
+
+const resolveKeyboardHeight = (): KeyboardHeightHook => {
   try {
+    if (!nativeControllerPresent()) return () => useAnimatedKeyboard().height;
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const controller = require('react-native-keyboard-controller');
     if (typeof controller?.useReanimatedKeyboardAnimation === 'function') {
@@ -139,11 +172,12 @@ const useKeyboardHeight: KeyboardHeightHook = (() => {
   }
 
   return () => useAnimatedKeyboard().height;
-})();
+};
 
 /** True when the keyboard controller is driving this, rather than the fallback. */
 export function hasKeyboardController(): boolean {
   try {
+    if (!nativeControllerPresent()) return false;
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     return typeof require('react-native-keyboard-controller')
       ?.useReanimatedKeyboardAnimation === 'function';

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,

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;
   }>;
@@ -175,7 +198,9 @@ interface SwiftUIComponents {
   Host: ComponentType<{
     children?: ReactNode;
     matchContents?: boolean | { vertical?: boolean; horizontal?: boolean };
-    ignoreSafeArea?: unknown;
+    ignoreSafeArea?: 'all' | 'container' | 'keyboard';
+    /** As on the portable host above — see `NativeHost`. */
+    colorScheme?: 'light' | 'dark';
     style?: unknown;
   }>;
   RNHostView: ComponentType<{ children?: ReactNode; matchContents?: boolean }>;

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>
+  );
+}

package/src/primitives/glass.tsx

@@ -44,6 +44,7 @@
  */
 import type { ComponentType, ReactNode } from 'react';
 import { Platform, StyleSheet, View, type StyleProp, type ViewProps, type ViewStyle } from 'react-native';
+import { useThemeMode } from '../theme/use-theme';
 import { cn } from '../utils/cn';
 import { useReduceTransparency } from './scrim';
 
@@ -144,6 +145,16 @@ export function Glass({
   ...props
 }: GlassProps) {
   const reduceTransparency = useReduceTransparency();
+  /*
+   * Which appearance the material is drawn in, from the app's theme rather
+   * than the phone's.
+   *
+   * The material's own default follows the system, so an app running a dark
+   * theme on a phone set to light draws light glass over dark content — and a
+   * theme changed at runtime leaves it where it was, because the system
+   * appearance never moved.
+   */
+  const { mode } = useThemeMode();
   // Not knowing yet counts as "do not draw it": the material arriving a frame
   // late is invisible, and one flashing at somebody who opted out is not.
   const material = GlassView !== null && reduceTransparency === false;
@@ -159,6 +170,7 @@ export function Glass({
         <GlassView
           glassEffectStyle={variant}
           tintColor={tint}
+          colorScheme={mode}
           pointerEvents="none"
           style={[StyleSheet.absoluteFill, shape]}
         />

package/src/providers/panel-ui-provider.tsx

@@ -1,5 +1,5 @@
 import { Fragment, type ComponentType, type ReactNode } from 'react';
-import { Platform, StyleSheet, View } from 'react-native';
+import { Platform, StyleSheet, TurboModuleRegistry, View } from 'react-native';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import {
   PortalHost,
@@ -15,16 +15,44 @@ import { cn } from '../utils/cn';
  * avoidance simply does nothing. Mount it here when the package is installed
  * so `avoidKeyboard` works without any extra setup, and fall back to a
  * pass-through when it is not.
+ *
+ * Installed is not the same question as usable, and the difference is what a
+ * `try`/`catch` around the `require` cannot see. In a client that loads no
+ * native modules of its own — Expo Go — the JavaScript is in `node_modules`
+ * and resolves, so the require succeeds and hands back a provider whose native
+ * side is absent. The throw then lands when that provider mounts, outside the
+ * `try`, and takes the app down before anything has painted.
+ *
+ * `TurboModuleRegistry.get` answers the real question and returns null rather
+ * than throwing, so the pass-through is reached instead.
+ *
+ * Resolved on the first render rather than when this module is evaluated. This
+ * file is the first thing a consuming app imports, and asking the native module
+ * registry a question before the runtime has finished standing up is a question
+ * asked too early — by the first render it is up, and the answer cannot change
+ * afterwards. The result is cached so the component type is stable: swapping it
+ * between renders would unmount and rebuild everything below it.
  */
-const KeyboardProvider: ComponentType<{ children?: ReactNode }> = (() => {
+let keyboardProvider: ComponentType<{ children?: ReactNode }> | undefined;
+
+function resolveKeyboardProvider(): ComponentType<{ children?: ReactNode }> {
+  if (keyboardProvider) return keyboardProvider;
+
+  let resolved: ComponentType<{ children?: ReactNode }> = Fragment;
   try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const controller = require('react-native-keyboard-controller');
-    return controller?.KeyboardProvider ?? Fragment;
+    if (TurboModuleRegistry.get('KeyboardController') !== null) {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const controller = require('react-native-keyboard-controller');
+      resolved = controller?.KeyboardProvider ?? Fragment;
+    }
   } catch {
-    return Fragment;
+    // Not installed, or installed without its native half. Either way the
+    // pass-through is the answer.
   }
-})();
+
+  keyboardProvider = resolved;
+  return resolved;
+}
 
 export interface PanelUIProviderProps {
   children: ReactNode;
@@ -57,6 +85,10 @@ export function PanelUIProvider({
   className,
   background = true,
 }: PanelUIProviderProps) {
+  // Resolved once, on the first render of the first provider in the app, and
+  // cached from there. See {@link resolveKeyboardProvider}.
+  const KeyboardProvider = resolveKeyboardProvider();
+
   return (
     <GestureHandlerRootView style={styles.root}>
       {/* Outermost of ours, so every field below it can avoid the keyboard.