panelui-native 0.6.0 → 0.7.0

package/src/native/index.ts

@@ -0,0 +1,79 @@
+/**
+ * Optional bridge to the platform's own UI toolkit.
+ *
+ * A handful of controls are better served by the real thing than by a faithful
+ * re-implementation: a switch, a picker, a sheet and a button are muscle
+ * memory, and users notice when the animation curve or the haptic is a
+ * near-miss. Passing `native` to those components hands rendering to SwiftUI
+ * on iOS and Jetpack Compose on Android.
+ *
+ * It is optional on purpose. The package is resolved lazily and every caller
+ * falls back to the styled implementation when it is missing, so nobody who
+ * never writes `native` has to install anything.
+ *
+ * ```sh
+ * npx expo install @expo/ui
+ * ```
+ *
+ * **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.
+ */
+import { Platform } from 'react-native';
+import type { ComponentType, ReactNode } from 'react';
+
+interface NativeUIModule {
+  Host: ComponentType<{
+    children?: ReactNode;
+    matchContents?: boolean;
+    style?: unknown;
+    [key: string]: unknown;
+  }>;
+  /**
+   * Hosts React Native views inside the native tree. Anything of ours that
+   * goes inside a native container has to be wrapped in this or the native
+   * layout does not measure it — children spill outside their container.
+   */
+  RNHostView: ComponentType<{
+    children?: ReactNode;
+    matchContents?: boolean;
+    style?: unknown;
+  }>;
+  Button: ComponentType<Record<string, unknown>>;
+  Switch: ComponentType<Record<string, unknown>>;
+  Picker: ComponentType<Record<string, unknown>> & {
+    Item: ComponentType<Record<string, unknown>>;
+  };
+  BottomSheet: ComponentType<Record<string, unknown>>;
+}
+
+let resolved = false;
+let module: NativeUIModule | null = null;
+
+/**
+ * The native UI module, or null when it is not installed or the platform has
+ * no toolkit behind it. Resolved once and cached — a failed require is not
+ * retried on every render.
+ */
+export function getNativeUI(): NativeUIModule | null {
+  if (resolved) return module;
+  resolved = true;
+
+  // Web has no SwiftUI and no Compose; @expo/ui renders plain views there,
+  // which loses the styling without gaining anything.
+  if (Platform.OS === 'web') return null;
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    module = require('@expo/ui') as NativeUIModule;
+  } catch {
+    module = null;
+  }
+
+  return module;
+}
+
+/** Whether `native` will actually render a platform control. */
+export function hasNativeUI(): boolean {
+  return getNativeUI() !== null;
+}

package/src/primitives/keyboard-avoider.tsx

@@ -0,0 +1,49 @@
+/**
+ * KeyboardAvoider — a view that lifts itself just clear of the keyboard.
+ *
+ * A thin wrapper over `useKeyboardAvoidance` for the common case of "keep this
+ * box visible", so a form does not have to wire the ref, layout handler and
+ * animated style by hand.
+ */
+import type { ReactNode } from 'react';
+import type { ViewProps } from 'react-native';
+import Animated from 'react-native-reanimated';
+import { useKeyboardAvoidance } from '../hooks/use-keyboard-avoidance';
+
+export interface KeyboardAvoiderProps extends ViewProps {
+  className?: string;
+  /** Set false to leave the content where it is. */
+  enabled?: boolean;
+  /** Gap to keep between the content's bottom edge and the keyboard. */
+  offset?: number;
+  children?: ReactNode;
+}
+
+export function KeyboardAvoider({
+  className,
+  enabled = true,
+  offset = 16,
+  children,
+  style,
+  onLayout,
+  ...props
+}: KeyboardAvoiderProps) {
+  const avoidance = useKeyboardAvoidance({ enabled, offset });
+
+  return (
+    <Animated.View
+      {...props}
+      ref={avoidance.ref}
+      onLayout={(event) => {
+        avoidance.onLayout(event);
+        onLayout?.(event);
+      }}
+      className={className}
+      style={[style, avoidance.animatedStyle]}
+    >
+      {children}
+    </Animated.View>
+  );
+}
+
+KeyboardAvoider.displayName = 'KeyboardAvoider';

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

@@ -1,10 +1,27 @@
-import type { ReactNode } from 'react';
+import { Fragment, type ComponentType, type ReactNode } from 'react';
 import { StyleSheet, View } from 'react-native';
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
 import { PortalHost, PortalProvider } from '../primitives/portal';
 import { ToastViewport } from '../components/toast';
 import { cn } from '../utils/cn';
 
+/**
+ * `react-native-keyboard-controller` needs its provider at the root, and
+ * forgetting it is a silent failure — the hooks return zeroes and keyboard
+ * 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.
+ */
+const KeyboardProvider: ComponentType<{ children?: ReactNode }> = (() => {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const controller = require('react-native-keyboard-controller');
+    return controller?.KeyboardProvider ?? Fragment;
+  } catch {
+    return Fragment;
+  }
+})();
+
 export interface PanelUIProviderProps {
   children: ReactNode;
   /**
@@ -38,14 +55,18 @@ export function PanelUIProvider({
 }: PanelUIProviderProps) {
   return (
     <GestureHandlerRootView style={styles.root}>
-      <View className={cn('flex-1', background && 'bg-background', className)}>
-        <PortalProvider>
-          {children}
-          {/* Sits before PortalHost so it can portal into it. */}
-          <ToastViewport />
-          <PortalHost />
-        </PortalProvider>
-      </View>
+      {/* Outermost of ours, so every field below it can avoid the keyboard.
+          A no-op Fragment when the controller is not installed. */}
+      <KeyboardProvider>
+        <View className={cn('flex-1', background && 'bg-background', className)}>
+          <PortalProvider>
+            {children}
+            {/* Sits before PortalHost so it can portal into it. */}
+            <ToastViewport />
+            <PortalHost />
+          </PortalProvider>
+        </View>
+      </KeyboardProvider>
     </GestureHandlerRootView>
   );
 }

package/src/theme/use-theme.ts

@@ -29,7 +29,7 @@ export interface PanelThemeFamily {
 /**
  * The theme families PanelUI ships. Each sets its own palette *and* its own
  * radius scale, so switching family changes the shape of the UI as well as
- * its colour — Panel is the Coss default, Moon is sharp and monochrome,
+ * its colour — Panel is the default, Moon is sharp and monochrome,
  * Grass is soft and green.
  *
  * Everything beyond `panel` must be registered in your metro config, or

package/theme.css

@@ -1,7 +1,9 @@
 /*
- * PanelUI theme — Coss UI design tokens, translated for React Native.
- * Source of truth: cosscom/coss packages/ui/src/styles/globals.css
- * (color-mix()/--alpha() expressions precomputed to static values.)
+ * PanelUI theme — the semantic design tokens, translated for React Native.
+ *
+ * Every colour is a static rgba/hex value: native cannot evaluate
+ * color-mix() or --alpha() at runtime, so those expressions are precomputed
+ * here rather than shipped as-is.
  *
  * Structured the way Uniwind expects themed tokens (see uniwind's own
  * test.css / expo-example): utility names declared in @theme, per-theme