panelui-native 0.5.1 → 0.6.0

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

@@ -0,0 +1,81 @@
+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.
+ *
+ * Mirrors coss.com/ui's `useCopyToClipboard`.
+ *
+ * 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.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/index.ts

@@ -90,6 +90,11 @@ export {
   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 +107,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 +172,8 @@ export {
   type IconProps,
 } from './icons';
 
+// Hooks
+export * from './hooks';
+
 // Utils
 export { cn } from './utils/cn';

package/theme.css

@@ -40,7 +40,13 @@
   --color-border: unset;
   --color-input: unset;
   --color-ring: unset;
+  /*
+   * Elevation ladder. Each step sits one notch further from the page
+   * background than the last, so nesting Surfaces reads as hierarchy.
+   */
   --color-surface: unset;
+  --color-surface-secondary: unset;
+  --color-surface-tertiary: unset;
   --color-skeleton: unset;
 
   /*
@@ -122,6 +128,8 @@
 
       /* grouping surface (Frame) and skeleton fill */
       --color-surface: #f7f7f7;
+      --color-surface-secondary: #f1f1f1;
+      --color-surface-tertiary: #eaeaea;
       --color-skeleton: rgba(0, 0, 0, 0.1);
 
       /* status fills: -soft = Alert (10%), -subtle = Badge (8%) */
@@ -193,6 +201,8 @@
 
       /* grouping surface (Frame) and skeleton fill */
       --color-surface: #1c1c1c;
+      --color-surface-secondary: #222222;
+      --color-surface-tertiary: #282828;
       --color-skeleton: rgba(255, 255, 255, 0.13);
 
       /* status fills: -soft = Alert (6%), -subtle = Badge (16%) */
@@ -274,6 +284,8 @@
       --color-ring: #171717;
 
       --color-surface: #fafafa;
+      --color-surface-secondary: #f4f4f4;
+      --color-surface-tertiary: #ededed;
       --color-skeleton: rgba(0, 0, 0, 0.08);
 
       --color-info-soft: rgba(0, 112, 243, 0.08);
@@ -334,6 +346,8 @@
       --color-ring: #ededed;
 
       --color-surface: #0f0f0f;
+      --color-surface-secondary: #161616;
+      --color-surface-tertiary: #1d1d1d;
       --color-skeleton: rgba(255, 255, 255, 0.11);
 
       --color-info-soft: rgba(0, 112, 243, 0.12);
@@ -397,6 +411,8 @@
       --color-ring: #3ecf8e;
 
       --color-surface: #f8f9fa;
+      --color-surface-secondary: #f1f3f5;
+      --color-surface-tertiary: #e9ecef;
       --color-skeleton: rgba(0, 0, 0, 0.08);
 
       --color-info-soft: rgba(59, 130, 246, 0.1);
@@ -457,6 +473,8 @@
       --color-ring: #3ecf8e;
 
       --color-surface: #242424;
+      --color-surface-secondary: #2a2a2a;
+      --color-surface-tertiary: #303030;
       --color-skeleton: rgba(255, 255, 255, 0.11);
 
       --color-info-soft: rgba(59, 130, 246, 0.08);