panelui-native 0.5.3 → 0.6.0

package/src/components/shimmer/index.tsx

@@ -0,0 +1,135 @@
+/**
+ * Shimmer — an animated highlight sweeping across content.
+ *
+ * The React Native equivalent of shadcn-ui/ui's `shimmer` utility
+ * (https://ui.shadcn.com/docs/utils/shimmer). That one is CSS:
+ * `background-clip: text` with a `color-mix()` highlight. React Native has
+ * neither, so the highlight is drawn as an SVG gradient band swept across an
+ * overlay by Reanimated, on the UI thread.
+ *
+ * The visible difference: the band passes *over* the content rather than
+ * being clipped to glyph shapes. On body-sized text the two read the same; on
+ * very large text the web version is crisper.
+ *
+ * ```tsx
+ * <Shimmer>
+ *   <Text muted>Generating response…</Text>
+ * </Shimmer>
+ * ```
+ */
+import { useEffect, useState, type ReactNode } from 'react';
+import { View, type LayoutChangeEvent, type ViewProps } from 'react-native';
+import Animated, {
+  cancelAnimation,
+  Easing,
+  useAnimatedStyle,
+  useReducedMotion,
+  useSharedValue,
+  withRepeat,
+  withTiming,
+} from 'react-native-reanimated';
+import Svg, { Defs, LinearGradient, Rect, Stop } from 'react-native-svg';
+import { useCSSVariable } from 'uniwind';
+import { cn } from '../../utils/cn';
+
+export interface ShimmerProps extends ViewProps {
+  className?: string;
+  /** Milliseconds for one sweep. */
+  duration?: number;
+  /** Sweep once instead of looping. */
+  once?: boolean;
+  /** Sweep right-to-left. */
+  reverse?: boolean;
+  /** Width of the highlight band, as a fraction of the content width. */
+  spread?: number;
+  /** Highlight colour. Defaults to the theme's foreground. */
+  color?: string;
+  /** Peak opacity of the highlight. */
+  intensity?: number;
+  children?: ReactNode;
+}
+
+export function Shimmer({
+  className,
+  duration = 2000,
+  once = false,
+  reverse = false,
+  spread = 0.4,
+  color,
+  intensity = 0.45,
+  children,
+  ...props
+}: ShimmerProps) {
+  const [width, setWidth] = useState(0);
+  const progress = useSharedValue(0);
+  const reducedMotion = useReducedMotion();
+
+  const themeForeground = useCSSVariable('--color-foreground');
+  const highlight =
+    color ?? (typeof themeForeground === 'string' ? themeForeground : '#ffffff');
+
+  useEffect(() => {
+    // Respect the OS setting rather than animating regardless — the same
+    // thing shadcn's utility does with prefers-reduced-motion.
+    if (reducedMotion || width === 0) return;
+
+    progress.value = 0;
+    progress.value = withRepeat(
+      withTiming(1, { duration, easing: Easing.linear }),
+      once ? 1 : -1,
+      false
+    );
+
+    return () => cancelAnimation(progress);
+  }, [duration, once, reducedMotion, width, progress]);
+
+  const bandWidth = Math.max(width * spread, 1);
+
+  const bandStyle = useAnimatedStyle(() => {
+    // Travel from fully off one edge to fully off the other.
+    const from = -bandWidth;
+    const to = width;
+    const x = reverse
+      ? to - progress.value * (to - from)
+      : from + progress.value * (to - from);
+    return { transform: [{ translateX: x }] };
+  });
+
+  const onLayout = (event: LayoutChangeEvent) => {
+    setWidth(event.nativeEvent.layout.width);
+    props.onLayout?.(event);
+  };
+
+  return (
+    <View
+      {...props}
+      onLayout={onLayout}
+      className={cn('overflow-hidden', className)}
+    >
+      {children}
+
+      {reducedMotion || width === 0 ? null : (
+        <Animated.View
+          pointerEvents="none"
+          style={[
+            { position: 'absolute', top: 0, bottom: 0, width: bandWidth },
+            bandStyle,
+          ]}
+        >
+          <Svg width="100%" height="100%">
+            <Defs>
+              <LinearGradient id="shimmer" x1="0" y1="0" x2="1" y2="0">
+                <Stop offset="0" stopColor={highlight} stopOpacity={0} />
+                <Stop offset="0.5" stopColor={highlight} stopOpacity={intensity} />
+                <Stop offset="1" stopColor={highlight} stopOpacity={0} />
+              </LinearGradient>
+            </Defs>
+            <Rect x="0" y="0" width="100%" height="100%" fill="url(#shimmer)" />
+          </Svg>
+        </Animated.View>
+      )}
+    </View>
+  );
+}
+
+Shimmer.displayName = 'Shimmer';

package/src/components/surface/index.tsx

@@ -0,0 +1,63 @@
+/**
+ * Surface — an elevated container.
+ *
+ * Adapted from: heroui-inc/heroui-native src/components/surface/
+ * (the variant ladder and the nesting model for building hierarchy).
+ *
+ * Both the fill and the corner radius follow the active theme: the variants
+ * resolve to themed `--color-surface-*` tokens, and `rounded-3xl` resolves
+ * through the per-theme radius scale — so Moon's surfaces are tight and
+ * Grass's are soft, without the component knowing anything about either.
+ *
+ * ```tsx
+ * <Surface>
+ *   <Surface variant="secondary">
+ *     <Surface variant="tertiary">…</Surface>
+ *   </Surface>
+ * </Surface>
+ * ```
+ */
+import { forwardRef } from 'react';
+import { StyleSheet, View, type ViewProps } from 'react-native';
+import { tv, type VariantProps } from 'tailwind-variants';
+
+const surfaceVariants = tv({
+  base: 'overflow-hidden rounded-3xl p-4',
+  variants: {
+    variant: {
+      default: 'bg-surface',
+      secondary: 'bg-surface-secondary',
+      tertiary: 'bg-surface-tertiary',
+      transparent: 'bg-transparent',
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+  },
+});
+
+export interface SurfaceProps
+  extends ViewProps,
+    VariantProps<typeof surfaceVariants> {
+  className?: string;
+}
+
+export const Surface = forwardRef<View, SurfaceProps>(
+  ({ className, variant, style, ...props }, ref) => (
+    <View
+      ref={ref}
+      // `borderCurve` has no Tailwind equivalent. On iOS it gives the
+      // continuous (squircle) corner Apple uses, which is visibly smoother
+      // than a circular arc at this radius; Android ignores it.
+      style={[styles.root, style]}
+      className={surfaceVariants({ variant, className })}
+      {...props}
+    />
+  )
+);
+
+Surface.displayName = 'Surface';
+
+const styles = StyleSheet.create({
+  root: { borderCurve: 'continuous' },
+});

package/src/hooks/index.ts

@@ -0,0 +1,19 @@
+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 { 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
+ * coss.com/ui's `useMediaQuery`, 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,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);