panelui-native 0.6.0 → 0.9.0

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

@@ -0,0 +1,140 @@
+/**
+ * useKeyboardAvoidance — lift an element just clear of the software keyboard.
+ *
+ * `KeyboardAvoidingView` shifts or pads an entire subtree by the full keyboard
+ * height regardless of where the element actually sits, which over-scrolls
+ * short forms and does nothing useful for an element already above the fold.
+ * This measures the element and moves it by exactly the overlap — and not at
+ * all when there is none.
+ *
+ * ## Install the keyboard controller
+ *
+ * ```sh
+ * npx expo install react-native-keyboard-controller
+ * ```
+ *
+ * It is an optional peer, but on Android it is close to required. Reanimated's
+ * own `useAnimatedKeyboard` — the fallback used when the controller is absent —
+ * is deprecated in Reanimated 4, and merely *calling* it switches Android out
+ * of `adjustResize` into manual inset handling for the whole app. That is a
+ * global side effect from a local hook, and it is why keyboard avoidance built
+ * on it tends to work on iOS and break on Android.
+ *
+ * With the controller installed, wrap your app in its `KeyboardProvider` —
+ * `PanelUIProvider` does this for you when the package is present.
+ *
+ * ```tsx
+ * const { ref, onLayout, animatedStyle } = useKeyboardAvoidance();
+ *
+ * <Animated.View ref={ref} onLayout={onLayout} style={animatedStyle}>
+ *   <TextInput />
+ * </Animated.View>
+ * ```
+ */
+import { useCallback } from 'react';
+import { useWindowDimensions, type LayoutChangeEvent, type View } from 'react-native';
+import {
+  useAnimatedKeyboard,
+  useAnimatedRef,
+  useAnimatedStyle,
+  useSharedValue,
+  type AnimatedRef,
+  type SharedValue,
+} from 'react-native-reanimated';
+
+export interface UseKeyboardAvoidanceOptions {
+  /** Set false to leave the element where it is. */
+  enabled?: boolean;
+  /** Gap to keep between the element's bottom edge and the keyboard. */
+  offset?: number;
+}
+
+export interface UseKeyboardAvoidanceResult {
+  /** Attach to the element that should stay visible. */
+  ref: AnimatedRef<View>;
+  /** Attach to the same element — it is how the resting position is measured. */
+  onLayout: (event: LayoutChangeEvent) => void;
+  /** Apply to the same element. */
+  animatedStyle: ReturnType<typeof useAnimatedStyle>;
+}
+
+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.
+ */
+const useKeyboardHeight: KeyboardHeightHook = (() => {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const controller = require('react-native-keyboard-controller');
+    if (typeof controller?.useReanimatedKeyboardAnimation === 'function') {
+      return () => {
+        // The controller reports height as a negative offset, matching the
+        // translation you would apply. Normalise it to a positive height so
+        // the arithmetic below reads the same either way.
+        const { height } = controller.useReanimatedKeyboardAnimation();
+        return height as SharedValue<number>;
+      };
+    }
+  } catch {
+    // Not installed — fall through.
+  }
+
+  return () => useAnimatedKeyboard().height;
+})();
+
+/** True when the keyboard controller is driving this, rather than the fallback. */
+export function hasKeyboardController(): boolean {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    return typeof require('react-native-keyboard-controller')
+      ?.useReanimatedKeyboardAnimation === 'function';
+  } catch {
+    return false;
+  }
+}
+
+export function useKeyboardAvoidance({
+  enabled = true,
+  offset = 16,
+}: UseKeyboardAvoidanceOptions = {}): UseKeyboardAvoidanceResult {
+  const ref = useAnimatedRef<View>();
+  const rawHeight = useKeyboardHeight();
+  const { height: screenHeight } = useWindowDimensions();
+
+  /** Window-space bottom edge of the element with no translation applied. */
+  const restingBottom = useSharedValue(0);
+
+  const measure = useCallback(() => {
+    ref.current?.measureInWindow((_x, y, _width, height) => {
+      if (height > 0) restingBottom.value = y + height;
+    });
+  }, [ref, restingBottom]);
+
+  const onLayout = useCallback(
+    (_event: LayoutChangeEvent) => {
+      // measureInWindow is only meaningful once the view is attached and
+      // positioned, which is a frame later than onLayout on both platforms.
+      requestAnimationFrame(measure);
+    },
+    [measure]
+  );
+
+  const animatedStyle = useAnimatedStyle(() => {
+    // Both sources are normalised to a positive height here.
+    const keyboardHeight = Math.abs(rawHeight.value);
+
+    if (!enabled || keyboardHeight === 0 || restingBottom.value === 0) {
+      return { transform: [{ translateY: 0 }] };
+    }
+
+    const keyboardTop = screenHeight - keyboardHeight;
+    const overlap = restingBottom.value + offset - keyboardTop;
+
+    return { transform: [{ translateY: overlap > 0 ? -overlap : 0 }] };
+  });
+
+  return { ref, onLayout, animatedStyle };
+}

package/src/icons/index.tsx

@@ -2,10 +2,10 @@
  * Icon set.
  *
  * Two families live here:
- * - Stroked 24×24 icons (Lucide geometry, as used by shadcn-ui/ui) for chrome
- *   such as chevrons and the close button.
- * - Filled 16×16 status icons for Alert and Toast indicators.
- *   Adapted from: heroui-inc/heroui-native src/components/alert/{default,success,warning}-icon.tsx
+ * - Stroked 24×24 icons on Lucide geometry, for chrome such as chevrons and
+ *   the close button.
+ * - Filled 16×16 status icons for Alert and Toast indicators, which read
+ *   better small than a stroked equivalent would.
  *
  * Every icon resolves its colour in the same order: an explicit `color` prop,
  * then the colour inherited from an enclosing `IconColorProvider`, then its
@@ -462,3 +462,51 @@ export function SendIcon({ size = 16, color, ...props }: IconProps) {
     </Svg>
   );
 }
+
+/** Document with a folded corner — a file attachment. */
+export function FileIcon({ size = 16, color, ...props }: IconProps) {
+  const resolved = useResolvedColor(color, '#737373');
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24" fill="none" {...props}>
+      <Path
+        d="M14 3H7a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V8zM14 3v5h5"
+        stroke={resolved}
+        strokeWidth={2}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </Svg>
+  );
+}
+
+/** Framed picture with a sun and a corner peak — an image attachment. */
+export function ImageIcon({ size = 16, color, ...props }: IconProps) {
+  const resolved = useResolvedColor(color, '#737373');
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24" fill="none" {...props}>
+      <Path
+        d="M4 4h16v16H4z M8.5 10a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3zM20 15l-4.5-4.5L6 20"
+        stroke={resolved}
+        strokeWidth={2}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </Svg>
+  );
+}
+
+/** A paperclip — attaching a file to a composer. */
+export function PaperclipIcon({ size = 16, color, ...props }: IconProps) {
+  const resolved = useResolvedColor(color, '#737373');
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24" fill="none" {...props}>
+      <Path
+        d="M21 8.5 11.3 18.2a4 4 0 0 1-5.6-5.6l9-9a2.5 2.5 0 0 1 3.6 3.6l-9 9a1 1 0 0 1-1.5-1.5l8.3-8.3"
+        stroke={resolved}
+        strokeWidth={2}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </Svg>
+  );
+}

package/src/index.ts

@@ -17,11 +17,18 @@ export {
 // Primitives
 export { Portal, PortalHost, PortalProvider } from './primitives/portal';
 export { Text, type TextProps } from './primitives/text';
+export {
+  KeyboardAvoider,
+  type KeyboardAvoiderProps,
+} from './primitives/keyboard-avoider';
 export {
   AnimatedPressable,
   type AnimatedPressableProps,
 } from './primitives/animated-pressable';
 
+// Native UI bridge
+export { hasNativeUI } from './native';
+
 // Components
 export {
   Accordion,
@@ -43,6 +50,18 @@ export {
   type AvatarProps,
   type AvatarBadgeProps,
 } from './components/avatar';
+export {
+  Attachment,
+  type AttachmentProps,
+  type AttachmentGroupProps,
+  type AttachmentMediaProps,
+  type AttachmentContentProps,
+  type AttachmentTitleProps,
+  type AttachmentDescriptionProps,
+  type AttachmentActionsProps,
+  type AttachmentActionProps,
+  type AttachmentState,
+} from './components/attachment';
 export { Badge, type BadgeProps } from './components/badge';
 export {
   BottomSheet,
@@ -83,7 +102,76 @@ export {
   type InputGroupInputProps,
   type InputGroupDecoratorProps,
 } from './components/input-group';
+export {
+  Item,
+  type ItemProps,
+  type ItemGroupProps,
+  type ItemSeparatorProps,
+  type ItemMediaProps,
+  type ItemContentProps,
+  type ItemTitleProps,
+  type ItemDescriptionProps,
+  type ItemActionsProps,
+  type ItemHeaderProps,
+  type ItemFooterProps,
+} from './components/item';
 export { Label, type LabelProps, type LabelTextProps } from './components/label';
+export {
+  LineChart,
+  useLineChart,
+  type LineChartProps,
+  type LineChartHandle,
+  type LineChartGridProps,
+  type LineChartLineProps,
+  type LineChartAreaProps,
+  type LineChartSkeletonProps,
+  type LineChartXAxisProps,
+  type LineChartTooltipProps,
+  type LineChartLegendProps,
+  type LineChartDatum,
+  type LineChartStatus,
+  type LineChartCurve,
+} from './components/line-chart';
+export {
+  Marker,
+  type MarkerProps,
+  type MarkerIconProps,
+  type MarkerContentProps,
+} from './components/marker';
+export {
+  MessageScroller,
+  useMessageScroller,
+  useMessageScrollerVisibility,
+  type MessageScrollerProps,
+  type MessageScrollerViewportProps,
+  type MessageScrollerContentProps,
+  type MessageScrollerItemProps,
+  type MessageScrollerButtonProps,
+  type MessageScrollerPosition,
+} from './components/message-scroller';
+export {
+  Message,
+  type MessageProps,
+  type MessageGroupProps,
+  type MessageAvatarProps,
+  type MessageContentProps,
+  type MessageHeaderProps,
+  type MessageBubbleProps,
+  type MessageBubbleContentProps,
+  type MessageFooterProps,
+  type MessageActionsProps,
+} from './components/message';
+export {
+  Popover,
+  type PopoverProps,
+  type PopoverTriggerProps,
+  type PopoverContentProps,
+  type PopoverArrowProps,
+  type PopoverCloseProps,
+  type PopoverPlacement,
+  type PopoverAlign,
+  type PopoverPresentation,
+} from './components/popover';
 export { Progress, type ProgressProps } from './components/progress';
 export {
   RadioGroup,
@@ -94,6 +182,7 @@ export {
   ScrollFade,
   type ScrollFadeProps,
 } from './components/scroll-fade';
+export { Separator, type SeparatorProps } from './components/separator';
 export { Shimmer, type ShimmerProps } from './components/shimmer';
 export { Skeleton, type SkeletonProps } from './components/skeleton';
 export { Spinner, type SpinnerProps } from './components/spinner';
@@ -154,11 +243,14 @@ export {
   ChevronLeftIcon,
   ChevronRightIcon,
   FacebookIcon,
+  FileIcon,
   GoogleIcon,
   IconColorProvider,
   InfoIcon,
+  ImageIcon,
   MoonIcon,
   PackageIcon,
+  PaperclipIcon,
   PlusSquareIcon,
   ReceiptIcon,
   SearchIcon,

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/primitives/scrim.tsx

@@ -0,0 +1,95 @@
+/**
+ * Scrim — the layer behind an overlay.
+ *
+ * An overlay needs the screen behind it to recede. There are two honest ways to
+ * do that: dim it, or blur it. Dimming is free and always works; blurring reads
+ * as more physical — the content behind stays legible as shape and colour while
+ * losing its detail — but it needs a native view to do it.
+ *
+ * `expo-blur` is resolved lazily and only when `blur` is asked for, so a project
+ * that never blurs anything installs nothing. When it is asked for and the
+ * package is missing, this falls back to a dim rather than failing: a blur you
+ * cannot draw is better shown as a darkened screen than as a crash.
+ *
+ * It fills its parent and does not intercept touches itself — the overlay layers
+ * its own dismiss `Pressable` over it — so it is purely the visual backdrop.
+ */
+import { type ComponentType } from 'react';
+import { StyleSheet, View, type ViewProps } from 'react-native';
+import Animated, { FadeIn, FadeOut } from 'react-native-reanimated';
+
+interface BlurViewProps {
+  intensity?: number;
+  tint?: 'light' | 'dark' | 'default' | 'systemMaterial';
+  style?: unknown;
+  children?: React.ReactNode;
+}
+
+/**
+ * `expo-blur`'s BlurView, or null when it is not installed. Resolved once at
+ * module load — the require is cheap and caching it avoids a try/catch on every
+ * render.
+ */
+const BlurView: ComponentType<BlurViewProps> | null = (() => {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const mod = require('expo-blur');
+    return (mod?.BlurView as ComponentType<BlurViewProps>) ?? null;
+  } catch {
+    return null;
+  }
+})();
+
+/** True when a real blur can be drawn — for a caller that wants to know. */
+export const hasBlur = BlurView !== null;
+
+export interface ScrimProps extends Omit<ViewProps, 'children'> {
+  /** Frost the backdrop instead of dimming it. Falls back to a dim if it can't. */
+  blur?: boolean;
+  /** Blur strength, 0–100. */
+  intensity?: number;
+  /** Which way the blur tints. */
+  tint?: 'light' | 'dark' | 'default' | 'systemMaterial';
+  /**
+   * The dim used when not blurring — and when blurring is asked for but
+   * unavailable. A popover passes a lighter one than a dialog.
+   */
+  dimClassName?: string;
+}
+
+export function Scrim({
+  blur = false,
+  intensity = 24,
+  tint = 'default',
+  dimClassName = 'bg-black/50',
+  style,
+  ...props
+}: ScrimProps) {
+  if (blur && BlurView) {
+    return (
+      <Animated.View
+        entering={FadeIn.duration(180)}
+        exiting={FadeOut.duration(150)}
+        style={[StyleSheet.absoluteFill, style]}
+        {...props}
+      >
+        {/* A faint dim under the blur so the frost has something to sit on —
+            a pure blur over a dark scene is nearly invisible. */}
+        <BlurView intensity={intensity} tint={tint} style={StyleSheet.absoluteFill} />
+        <View className="absolute inset-0 bg-black/10" />
+      </Animated.View>
+    );
+  }
+
+  return (
+    <Animated.View
+      entering={FadeIn.duration(150)}
+      exiting={FadeOut.duration(150)}
+      style={[StyleSheet.absoluteFill, style]}
+      className={dimClassName}
+      {...props}
+    />
+  );
+}
+
+Scrim.displayName = 'Scrim';

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