panelui-native 0.5.3 → 0.7.0

package/src/components/switch/index.tsx

@@ -7,6 +7,7 @@ import Animated, {
   withSpring,
 } from 'react-native-reanimated';
 import { tv, type VariantProps } from 'tailwind-variants';
+import { getNativeUI } from '../../native';
 
 const SPRING = { damping: 18, stiffness: 250, mass: 0.5 } as const;
 
@@ -37,6 +38,16 @@ export interface SwitchProps extends VariantProps<typeof switchVariants> {
   value: boolean;
   onValueChange?: (value: boolean) => void;
   disabled?: boolean;
+  /**
+   * Render the platform's own switch instead of this one. Requires the
+   * optional `@expo/ui` package; without it this prop does nothing.
+   *
+   * **Theme tokens do not apply** — the platform draws the control, so
+   * `className` and `size` are ignored.
+   */
+  native?: boolean;
+  /** Text label drawn beside the control. Native mode only. */
+  label?: string;
 }
 
 /**
@@ -44,8 +55,9 @@ export interface SwitchProps extends VariantProps<typeof switchVariants> {
  * UI thread; toggling never re-renders beyond the value change itself.
  */
 export const Switch = forwardRef<View, SwitchProps>(
-  ({ className, value, onValueChange, disabled, size = 'md' }, ref) => {
+  ({ className, value, onValueChange, disabled, size = 'md', native, label }, ref) => {
     const progress = useSharedValue(value ? 1 : 0);
+    const nativeUI = native ? getNativeUI() : null;
     const slots = switchVariants({ size, disabled: !!disabled });
 
     useEffect(() => {
@@ -62,6 +74,20 @@ export const Switch = forwardRef<View, SwitchProps>(
       opacity: progress.value,
     }));
 
+    if (nativeUI) {
+      const { Host, Switch: NativeSwitch } = nativeUI;
+      return (
+        <Host matchContents>
+          <NativeSwitch
+            value={value}
+            onValueChange={(next: boolean) => onValueChange?.(next)}
+            label={label}
+            disabled={disabled}
+          />
+        </Host>
+      );
+    }
+
     return (
       <Pressable
         ref={ref}

package/src/components/toast/index.tsx

@@ -1,10 +1,10 @@
 /**
  * Toast — transient notification.
  *
- * Adapted from: heroui-inc/heroui-native src/components/toast/
- * (the three usage patterns — string, config object, custom component — the
- * Title / Description / Action / Close anatomy, placement, and swipe-to-
- * dismiss). Styled with Coss UI tokens and PanelUI's Alert status palette.
+ * Three ways to raise one, because the right amount of ceremony differs: a
+ * bare string, a config object with a title, description and action, or a
+ * custom component when none of that fits. The anatomy underneath is the same
+ * in all three.
  *
  * The viewport is mounted for you by PanelUIProvider; `useToast()` works
  * anywhere below it.
@@ -71,8 +71,7 @@ const STACK_SCALE_STEP = 0.97;
 const EDGE_INSET = 16;
 
 /*
- * Entering/exiting animations, from heroui-inc/heroui-native
- * src/components/toast/toast.animation.ts.
+ * Entering and exiting animations.
  *
  * `mass(3)` is doing the important work: a heavy spring settles without the
  * visible overshoot a default-mass one gives. `withInitialValues` keeps
@@ -285,7 +284,7 @@ export const Toast = Object.assign(ToastRoot, {
  *
  * Swiping is vertical and direction-aware: dragging toward the screen edge the
  * toast came from dismisses it, dragging the other way rubber-bands against a
- * hard limit. Matches heroui-native's toast.animation.ts.
+ * hard limit.
  */
 function ToastSlot({
   item,
@@ -376,7 +375,7 @@ function ToastSlot({
    * Stack position plus the gesture transform.
    *
    * The whole deck takes the *newest* toast's height so the cards behind read
-   * as a uniform stack rather than a ragged pile — matching heroui-native.
+   * as a uniform stack rather than a ragged pile.
    */
   const stackStyle = useAnimatedStyle(() => {
     // Fall back to this toast's own height until the front one is measured.

package/src/components/typography/index.tsx

@@ -1,9 +1,9 @@
 /**
  * Typography — semantic text presets.
  *
- * Adapted from: heroui-inc/heroui-native (Typography `type` scale and the
- * Heading / Paragraph / Code compound parts), built on PanelUI's Text
- * primitive so every preset keeps `className` passthrough and theme colours.
+ * The type scale in one place, so headings stay consistent instead of being
+ * rebuilt out of size and weight classes at each call site. Built on the Text
+ * primitive, so every preset keeps `className` passthrough and theme colours.
  */
 import { forwardRef } from 'react';
 import { View, type Text as RNText, type ViewProps } from 'react-native';

package/src/hooks/index.ts

@@ -0,0 +1,24 @@
+export {
+  useCopyToClipboard,
+  type UseCopyToClipboardOptions,
+  type UseCopyToClipboardResult,
+} from './use-copy-to-clipboard';
+export {
+  useDisclosure,
+  type UseDisclosureOptions,
+  type UseDisclosureResult,
+} from './use-disclosure';
+export {
+  useBreakpoint,
+  BREAKPOINTS,
+  type Breakpoint,
+  type UseBreakpointResult,
+} from './use-breakpoint';
+export { useKeyboard, type UseKeyboardResult } from './use-keyboard';
+export {
+  useKeyboardAvoidance,
+  type UseKeyboardAvoidanceOptions,
+  type UseKeyboardAvoidanceResult,
+} from './use-keyboard-avoidance';
+export { useDebouncedValue } from './use-debounced-value';
+export { usePrevious } from './use-previous';

package/src/hooks/use-breakpoint.ts

@@ -0,0 +1,52 @@
+import { useWindowDimensions } from 'react-native';
+
+/** Tailwind's breakpoints, minus the ones no phone or tablet reaches. */
+export const BREAKPOINTS = { sm: 640, md: 768, lg: 1024, xl: 1280 } as const;
+
+export type Breakpoint = keyof typeof BREAKPOINTS;
+
+export interface UseBreakpointResult {
+  /** Largest breakpoint the window currently satisfies, or `base`. */
+  current: Breakpoint | 'base';
+  /** True when the window is at least this wide. */
+  isAtLeast: (breakpoint: Breakpoint) => boolean;
+  width: number;
+  height: number;
+  isLandscape: boolean;
+}
+
+/**
+ * Responsive state from the window size — the React Native answer to a media
+ * query, which has no equivalent here.
+ *
+ * For styling, prefer Uniwind's responsive class prefixes (`md:flex-row`).
+ * Reach for this when the *behaviour* changes, not just the look — rendering
+ * a sheet on a phone and a dialog on a tablet, say.
+ *
+ * ```tsx
+ * const { isAtLeast } = useBreakpoint();
+ * return isAtLeast('md') ? <Dialog …/> : <BottomSheet …/>;
+ * ```
+ */
+export function useBreakpoint(): UseBreakpointResult {
+  const { width, height } = useWindowDimensions();
+
+  const current: Breakpoint | 'base' =
+    width >= BREAKPOINTS.xl
+      ? 'xl'
+      : width >= BREAKPOINTS.lg
+        ? 'lg'
+        : width >= BREAKPOINTS.md
+          ? 'md'
+          : width >= BREAKPOINTS.sm
+            ? 'sm'
+            : 'base';
+
+  return {
+    current,
+    isAtLeast: (breakpoint) => width >= BREAKPOINTS[breakpoint],
+    width,
+    height,
+    isLandscape: width > height,
+  };
+}

package/src/hooks/use-copy-to-clipboard.ts

@@ -0,0 +1,79 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+export interface UseCopyToClipboardOptions {
+  /** Milliseconds before `copied` flips back. */
+  timeout?: number;
+  onCopy?: () => void;
+}
+
+export interface UseCopyToClipboardResult {
+  /** Writes `value` to the clipboard and sets `copied`. */
+  copy: (value: string) => Promise<void>;
+  copied: boolean;
+}
+
+/**
+ * Copy text to the clipboard, with a temporary "copied" state.
+ *
+ * Requires `expo-clipboard`, which is an optional peer dependency — React
+ * Native removed `Clipboard` from core, and pulling in a required native
+ * module for one hook would cost every consumer who never calls it:
+ *
+ * ```sh
+ * npx expo install expo-clipboard
+ * ```
+ *
+ * ```tsx
+ * const { copy, copied } = useCopyToClipboard();
+ * <Button onPress={() => copy(url)}>{copied ? 'Copied' : 'Copy link'}</Button>
+ * ```
+ */
+export function useCopyToClipboard({
+  timeout = 2000,
+  onCopy,
+}: UseCopyToClipboardOptions = {}): UseCopyToClipboardResult {
+  const [copied, setCopied] = useState(false);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Never leave a timer running against an unmounted component.
+  useEffect(
+    () => () => {
+      if (timer.current) clearTimeout(timer.current);
+    },
+    []
+  );
+
+  const copy = useCallback(
+    async (value: string) => {
+      const setString = await loadClipboard();
+      await setString(value);
+
+      setCopied(true);
+      onCopy?.();
+
+      if (timer.current) clearTimeout(timer.current);
+      if (timeout > 0) {
+        timer.current = setTimeout(() => setCopied(false), timeout);
+      }
+    },
+    [timeout, onCopy]
+  );
+
+  return { copy, copied };
+}
+
+/**
+ * Resolves expo-clipboard lazily, so apps that never call this hook are not
+ * asked to install it. The import is awaited rather than top-level for the
+ * same reason.
+ */
+async function loadClipboard(): Promise<(value: string) => Promise<unknown>> {
+  try {
+    const clipboard = await import('expo-clipboard');
+    return clipboard.setStringAsync;
+  } catch {
+    throw new Error(
+      'useCopyToClipboard requires expo-clipboard. Install it with: npx expo install expo-clipboard'
+    );
+  }
+}

package/src/hooks/use-debounced-value.ts

@@ -0,0 +1,23 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * A copy of `value` that only updates once it has stopped changing for
+ * `delay` ms — for search fields, where you want the typed value on screen
+ * immediately but the query fired once.
+ *
+ * ```tsx
+ * const [query, setQuery] = useState('');
+ * const debounced = useDebouncedValue(query, 300);
+ * useEffect(() => { search(debounced); }, [debounced]);
+ * ```
+ */
+export function useDebouncedValue<T>(value: T, delay = 300): T {
+  const [debounced, setDebounced] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debounced;
+}

package/src/hooks/use-disclosure.ts

@@ -0,0 +1,57 @@
+import { useCallback, useMemo, useState } from 'react';
+
+export interface UseDisclosureOptions {
+  defaultOpen?: boolean;
+  /** Controlled open state. Pass this to drive it from outside. */
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export interface UseDisclosureResult {
+  isOpen: boolean;
+  open: () => void;
+  close: () => void;
+  toggle: () => void;
+  /** Spread onto Dialog, BottomSheet or Select. */
+  props: { open: boolean; onOpenChange: (open: boolean) => void };
+}
+
+/**
+ * Open/closed state for an overlay.
+ *
+ * The same controlled-or-uncontrolled pattern Dialog, BottomSheet and Select
+ * implement internally, lifted out for when you need to drive one from
+ * elsewhere — closing a sheet after a request settles, say.
+ *
+ * ```tsx
+ * const sheet = useDisclosure();
+ * <Button onPress={sheet.open}>Share</Button>
+ * <BottomSheet {...sheet.props}>…</BottomSheet>
+ * ```
+ */
+export function useDisclosure({
+  defaultOpen = false,
+  open: controlledOpen,
+  onOpenChange,
+}: UseDisclosureOptions = {}): UseDisclosureResult {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+  const isControlled = controlledOpen !== undefined;
+  const isOpen = isControlled ? controlledOpen : uncontrolledOpen;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!isControlled) setUncontrolledOpen(next);
+      onOpenChange?.(next);
+    },
+    [isControlled, onOpenChange]
+  );
+
+  const open = useCallback(() => setOpen(true), [setOpen]);
+  const close = useCallback(() => setOpen(false), [setOpen]);
+  const toggle = useCallback(() => setOpen(!isOpen), [setOpen, isOpen]);
+
+  return useMemo(
+    () => ({ isOpen, open, close, toggle, props: { open: isOpen, onOpenChange: setOpen } }),
+    [isOpen, open, close, toggle, setOpen]
+  );
+}

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/hooks/use-keyboard.ts

@@ -0,0 +1,43 @@
+import { useEffect, useState } from 'react';
+import { Keyboard, Platform } from 'react-native';
+
+export interface UseKeyboardResult {
+  /** Height of the keyboard in px, or 0 when hidden. */
+  height: number;
+  isVisible: boolean;
+}
+
+/**
+ * Keyboard height and visibility, on the JS thread.
+ *
+ * Use this when the value drives rendering — showing a hint, swapping a
+ * layout. For *animating* against the keyboard, use Reanimated's
+ * `useAnimatedKeyboard` instead: it runs on the UI thread and tracks the
+ * keyboard frame-for-frame, where this fires once per show/hide.
+ *
+ * ```tsx
+ * const { isVisible } = useKeyboard();
+ * {isVisible ? null : <Footer />}
+ * ```
+ */
+export function useKeyboard(): UseKeyboardResult {
+  const [height, setHeight] = useState(0);
+
+  useEffect(() => {
+    // iOS reports the frame before it animates; Android only on completion.
+    const showEvent = Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow';
+    const hideEvent = Platform.OS === 'ios' ? 'keyboardWillHide' : 'keyboardDidHide';
+
+    const show = Keyboard.addListener(showEvent, (event) =>
+      setHeight(event.endCoordinates.height)
+    );
+    const hide = Keyboard.addListener(hideEvent, () => setHeight(0));
+
+    return () => {
+      show.remove();
+      hide.remove();
+    };
+  }, []);
+
+  return { height, isVisible: height > 0 };
+}

package/src/hooks/use-previous.ts

@@ -0,0 +1,24 @@
+import { useEffect, useRef } from 'react';
+
+/**
+ * The value from the previous render, or `undefined` on the first.
+ *
+ * Useful for reacting to a transition rather than a state — firing only when
+ * something *became* true.
+ *
+ * ```tsx
+ * const wasOpen = usePrevious(isOpen);
+ * useEffect(() => {
+ *   if (isOpen && !wasOpen) track('sheet_opened');
+ * }, [isOpen, wasOpen]);
+ * ```
+ */
+export function usePrevious<T>(value: T): T | undefined {
+  const ref = useRef<T | undefined>(undefined);
+
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+
+  return ref.current;
+}

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

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,
@@ -83,13 +90,43 @@ 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 {
+  Message,
+  type MessageProps,
+  type MessageGroupProps,
+  type MessageAvatarProps,
+  type MessageContentProps,
+  type MessageHeaderProps,
+  type MessageBubbleProps,
+  type MessageBubbleContentProps,
+  type MessageFooterProps,
+  type MessageActionsProps,
+} from './components/message';
 export { Progress, type ProgressProps } from './components/progress';
 export {
   RadioGroup,
   type RadioGroupProps,
   type RadioGroupItemProps,
 } from './components/radio-group';
+export {
+  ScrollFade,
+  type ScrollFadeProps,
+} from './components/scroll-fade';
+export { Shimmer, type ShimmerProps } from './components/shimmer';
 export { Skeleton, type SkeletonProps } from './components/skeleton';
 export { Spinner, type SpinnerProps } from './components/spinner';
 export {
@@ -102,6 +139,7 @@ export {
   type StepState,
   type StepsOrientation,
 } from './components/steps';
+export { Surface, type SurfaceProps } from './components/surface';
 export { Switch, type SwitchProps } from './components/switch';
 export {
   Timeline,
@@ -166,5 +204,8 @@ export {
   type IconProps,
 } from './icons';
 
+// Hooks
+export * from './hooks';
+
 // Utils
 export { cn } from './utils/cn';