react-native-quick-preview 1.0.5 → 2.0.0

package/src/internal/components/PopoverContainer.tsx

@@ -0,0 +1,58 @@
+import React from 'react'
+import { View, StyleSheet } from 'react-native'
+import Animated, { Easing, useAnimatedStyle, useSharedValue, withTiming } from 'react-native-reanimated'
+import type { QuickPreviewOptions } from '../../types'
+import { resolveSizeStyle } from '../resolveSize'
+
+export function PopoverContainer({
+  children,
+  options,
+  insets: _insets,
+  onRequestClose: _onRequestClose, // kept for API parity with SheetContainer
+}: {
+  children: React.ReactNode
+  options?: QuickPreviewOptions
+  insets: { top: number; bottom: number }
+  onRequestClose: () => void
+}) {
+  const scale = useSharedValue(0.96)
+  const opacity = useSharedValue(0)
+
+  React.useEffect(() => {
+    // Smooth ease-out, no spring overshoot — a clean, quick "pop" in.
+    scale.value = withTiming(1, { duration: 200, easing: Easing.out(Easing.cubic) })
+    opacity.value = withTiming(1, { duration: 160, easing: Easing.out(Easing.quad) })
+  }, [scale, opacity])
+
+  const container = useAnimatedStyle(() => ({
+    opacity: opacity.value,
+    transform: [{ scale: scale.value }],
+  }))
+
+  const sizeStyle = resolveSizeStyle(options?.size)
+
+  return (
+    <View style={[StyleSheet.absoluteFill, styles.center]} pointerEvents="box-none">
+      <Animated.View
+        style={[styles.card, sizeStyle, container]}
+        accessibilityRole={options?.accessibilityRole}
+        accessibilityLabel={options?.accessibilityLabel ?? 'Quick preview'}
+      >
+        {children}
+      </Animated.View>
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  center: { justifyContent: 'center', alignItems: 'center' },
+  card: {
+    maxWidth: 520,
+    width: '92%',
+    maxHeight: '86%',
+    borderRadius: 16,
+    backgroundColor: 'white',
+    overflow: 'hidden',
+    elevation: 3,
+  },
+})

package/src/internal/components/QuickPreviewScrollView.tsx

@@ -0,0 +1,21 @@
+import React from 'react'
+import { ScrollView, ScrollViewProps } from 'react-native'
+
+/**
+ * A gesture-aware `ScrollView` for use inside preview content. Use it instead of
+ * a plain `ScrollView` so that scrolling the content and the swipe-to-dismiss
+ * gesture don't fight each other. Accepts all `ScrollViewProps`.
+ *
+ * @example
+ * ```tsx
+ * present(
+ *   <QuickPreviewScrollView>
+ *     <LongArticle />
+ *   </QuickPreviewScrollView>,
+ *   { variant: 'sheet', size: { maxHeight: 520 } }
+ * )
+ * ```
+ */
+export function QuickPreviewScrollView(props: ScrollViewProps) {
+  return <ScrollView nestedScrollEnabled {...props} />
+}

package/src/internal/components/SheetContainer.tsx

@@ -0,0 +1,84 @@
+import React from 'react'
+import { View, StyleSheet } from 'react-native'
+import Animated, { Easing, useAnimatedStyle, useSharedValue, withTiming, runOnJS } from 'react-native-reanimated'
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import type { QuickPreviewOptions } from '../../types'
+import { resolveSizeStyle } from '../resolveSize'
+
+export function SheetContainer({
+  children,
+  options,
+  insets,
+  onRequestClose,
+}: {
+  children: React.ReactNode
+  options?: QuickPreviewOptions
+  insets: { top: number; bottom: number }
+  onRequestClose: () => void
+}) {
+  const translateY = useSharedValue(1000)
+  const dismissOnPanDown = options?.dismissOnPanDown ?? true
+
+  React.useEffect(() => {
+    // Smooth slide up, no spring bounce.
+    translateY.value = withTiming(0, { duration: 300, easing: Easing.out(Easing.cubic) })
+  }, [translateY])
+
+  const pan = Gesture.Pan()
+    .onUpdate((e) => {
+      if (!dismissOnPanDown) return
+      translateY.value = Math.max(0, e.translationY)
+    })
+    .onEnd((e) => {
+      const shouldClose = e.velocityY > 1000 || translateY.value > 140
+      if (shouldClose) {
+        translateY.value = withTiming(800, { duration: 200 }, (finished) => {
+          if (finished) runOnJS(onRequestClose)()
+        })
+      } else {
+        translateY.value = withTiming(0, { duration: 240, easing: Easing.out(Easing.cubic) })
+      }
+    })
+
+  const style = useAnimatedStyle(() => ({
+    transform: [{ translateY: translateY.value }],
+  }))
+
+  const sizeStyle = resolveSizeStyle(options?.size)
+
+  return (
+    <GestureDetector gesture={pan}>
+      <Animated.View
+        style={[styles.sheet, sizeStyle, style, { paddingBottom: Math.max(insets.bottom, 12) }]}
+        accessibilityRole={options?.accessibilityRole}
+        accessibilityLabel={options?.accessibilityLabel ?? 'Quick preview'}
+      >
+        <View style={styles.grabber} />
+        {children}
+      </Animated.View>
+    </GestureDetector>
+  )
+}
+
+const styles = StyleSheet.create({
+  sheet: {
+    position: 'absolute',
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderTopLeftRadius: 16,
+    borderTopRightRadius: 16,
+    paddingTop: 8,
+    backgroundColor: 'white',
+    overflow: 'hidden',
+    elevation: 3,
+  },
+  grabber: {
+    alignSelf: 'center',
+    width: 40,
+    height: 4,
+    borderRadius: 2,
+    backgroundColor: 'rgba(0,0,0,0.2)',
+    marginBottom: 8,
+  },
+})

package/src/internal/resolveSize.ts

@@ -0,0 +1,17 @@
+import type { QuickPreviewSize } from '../types'
+
+/**
+ * Turn the public `size` option into container style constraints.
+ * 'auto' (or undefined) applies nothing; a number caps the height;
+ * an object caps height and/or width.
+ */
+export function resolveSizeStyle(
+  size?: QuickPreviewSize
+): { maxHeight?: number; maxWidth?: number } {
+  if (size == null || size === 'auto') return {}
+  if (typeof size === 'number') return { maxHeight: size }
+  const out: { maxHeight?: number; maxWidth?: number } = {}
+  if (typeof size.maxHeight === 'number') out.maxHeight = size.maxHeight
+  if (typeof size.maxWidth === 'number') out.maxWidth = size.maxWidth
+  return out
+}

package/src/types.ts

@@ -0,0 +1,93 @@
+import type React from 'react'
+import type { AccessibilityRole } from 'react-native'
+
+/**
+ * How the preview is presented.
+ * - `'popover'` — a centered card that scales in.
+ * - `'sheet'` — a panel that slides up from the bottom and can be swiped down to dismiss.
+ *
+ * @defaultValue `'popover'`
+ */
+export type QuickPreviewVariant = 'popover' | 'sheet'
+
+/**
+ * Constrains the preview container's size.
+ * - `'auto'` — size to the content (default).
+ * - `number` — a maximum height in points.
+ * - `{ maxHeight, maxWidth }` — explicit maximum dimensions in points.
+ *
+ * @defaultValue `'auto'`
+ */
+export type QuickPreviewSize =
+  | 'auto'
+  | number
+  | { maxHeight?: number; maxWidth?: number }
+
+/**
+ * Options for a single presentation, passed to {@link QuickPreviewController.present}
+ * (or `QuickPreview.present`, or as `previewOptions` on `QuickPreviewPressable`).
+ *
+ * @example
+ * ```tsx
+ * present(<Card />, {
+ *   variant: 'sheet',
+ *   size: { maxHeight: 480 },
+ *   dismissOnPanDown: true,
+ * })
+ * ```
+ */
+export type QuickPreviewOptions = {
+  /**
+   * Centered `'popover'` or bottom `'sheet'`.
+   * @defaultValue `'popover'`
+   */
+  variant?: QuickPreviewVariant
+  /**
+   * Constrain the container size. A number caps the height; an object caps
+   * `maxHeight`/`maxWidth`; `'auto'` sizes to the content.
+   * @defaultValue `'auto'`
+   */
+  size?: QuickPreviewSize
+  /**
+   * Close the preview when the backdrop (the area outside it) is tapped.
+   * @defaultValue `true`
+   */
+  dismissOnBackdropPress?: boolean
+  /**
+   * Close the preview when it is swiped down. Applies to the `'sheet'` variant only.
+   * @defaultValue `true`
+   */
+  dismissOnPanDown?: boolean
+  /** Accessibility label announced for the preview container. */
+  accessibilityLabel?: string
+  /** Accessibility role for the preview container. */
+  accessibilityRole?: AccessibilityRole
+  /** Called on the JS thread when the open animation starts. */
+  onOpenStart?: () => void
+  /** Called when the open animation finishes. */
+  onOpenEnd?: () => void
+  /** Called when the close animation starts. */
+  onCloseStart?: () => void
+  /** Called when the close animation finishes and the preview is unmounted. */
+  onCloseEnd?: () => void
+}
+
+/**
+ * The imperative controller returned by {@link useQuickPreview} and exposed as the
+ * static `QuickPreview` handle. Use it to open, update, and close previews.
+ */
+export type QuickPreviewController = {
+  /**
+   * Present `node` as the preview. Calling this while a preview is already open
+   * replaces its content and options.
+   * @param node - the React element to show inside the preview.
+   * @param opts - presentation options ({@link QuickPreviewOptions}).
+   */
+  present: (node: React.ReactNode, opts?: Partial<QuickPreviewOptions>) => void
+  /** Dismiss the current preview. No-op if nothing is open. */
+  close: () => void
+  /** Merge new options into the currently open preview (e.g. switch `variant`). */
+  update: (opts: Partial<QuickPreviewOptions>) => void
+  /** Whether a preview is currently open. */
+  isOpen: () => boolean
+}

package/src/useQuickPreview.ts

@@ -0,0 +1,28 @@
+import React from 'react'
+import { QuickPreviewContext } from './context'
+import type { QuickPreviewController } from './types'
+
+/**
+ * Access the {@link QuickPreviewController} to open, update, and close previews
+ * from inside a React component. Must be called under a mounted `<PreviewProvider>`.
+ *
+ * @throws if used outside of a `<PreviewProvider>`.
+ * @returns the controller: `{ present, close, update, isOpen }`.
+ *
+ * @example
+ * ```tsx
+ * function ProductCard({ product }) {
+ *   const { present } = useQuickPreview()
+ *   return (
+ *     <Pressable onLongPress={() => present(<ProductPreview product={product} />, { variant: 'sheet' })}>
+ *       <Thumbnail source={product.image} />
+ *     </Pressable>
+ *   )
+ * }
+ * ```
+ */
+export function useQuickPreview(): QuickPreviewController {
+  const ctx = React.useContext(QuickPreviewContext)
+  if (!ctx) throw new Error('useQuickPreview must be used within <PreviewProvider>')
+  return ctx
+}

package/src/QuickPreview.tsx

@@ -1,222 +0,0 @@
-// src/QuickPreview.tsx
-import React, { useEffect, useMemo, useRef, useState } from 'react';
-import {
-  View,
-  StyleSheet,
-  Modal,
-  Dimensions,
-  Animated,
-  Platform,
-  Pressable,
-  PanResponder,
-  Keyboard,
-} from 'react-native';
-import type { AccessibilityRole } from 'react-native';
-import type { CloseReason, QuickPreviewProps, ThemeMode } from './QuickPreviewProperties';
-
-const { width: screenWidth, height: screenHeight } = Dimensions.get('window');
-
-// TS-safe across RN versions where "dialog" may not exist in AccessibilityRole
-const dialogA11yRole = 'dialog' as unknown as AccessibilityRole;
-
-const overlayColor = (theme: ThemeMode, custom?: number) =>
-  `rgba(0,0,0,${custom ?? (theme === 'dark' ? 0.8 : 0.5)})`;
-
-export const QuickPreview: React.FC<QuickPreviewProps> = ({
-  visible,
-  onClose,
-  onOpen,
-  onClosed,
-  theme = 'light',
-  backdropOpacity,
-  animationDuration = 220,
-  closeOnBackdropPress = true,
-  closeOnBackButton = true,
-  enableSwipeToClose = true,
-  swipeThreshold = 80,
-  unmountOnExit = true,
-  avoidKeyboard = false,
-  children,
-  renderBackdrop,
-  onBackdropPress,
-  testID = 'quickpreview',
-  accessibilityLabel = 'Quick preview',
-  stylesOverride = {},
-}) => {
-  const [mounted, setMounted] = useState(false);
-  const [kb, setKb] = useState(0); // keyboard height
-
-  const fade = useRef(new Animated.Value(0)).current;
-  const scale = useRef(new Animated.Value(0.96)).current;
-  const translateY = useRef(new Animated.Value(0)).current;
-
-  const baseOverlay = useMemo(() => overlayColor(theme, backdropOpacity), [theme, backdropOpacity]);
-
-  // Track why we closed so we can report it to onClosed
-  const closeReasonRef = useRef<CloseReason>('programmatic');
-
-  // Mount/unmount with animation
-  useEffect(() => {
-    if (visible && !mounted) {
-      setMounted(true);
-      onOpen?.(); // great place to trigger optional haptics in-app
-
-      requestAnimationFrame(() => {
-        Animated.parallel([
-          Animated.timing(fade, { toValue: 1, duration: animationDuration, useNativeDriver: true }),
-          Animated.spring(scale, { toValue: 1, useNativeDriver: true, friction: 7, tension: 80 }),
-        ]).start();
-      });
-    } else if (!visible && mounted) {
-      Animated.parallel([
-        Animated.timing(fade, { toValue: 0, duration: animationDuration, useNativeDriver: true }),
-        Animated.timing(scale, { toValue: 0.96, duration: animationDuration, useNativeDriver: true }),
-      ]).start(() => {
-        translateY.setValue(0);
-        onClosed?.(closeReasonRef.current);
-        closeReasonRef.current = 'programmatic';
-        if (unmountOnExit) setMounted(false);
-      });
-    }
-  }, [visible, mounted, animationDuration, fade, scale, translateY, unmountOnExit, onOpen, onClosed]);
-
-  // Keyboard avoidance (optional)
-  useEffect(() => {
-    if (!avoidKeyboard) return;
-    const show = Keyboard.addListener('keyboardDidShow', (e) => setKb(e.endCoordinates?.height ?? 0));
-    const hide = Keyboard.addListener('keyboardDidHide', () => setKb(0));
-    return () => {
-      show.remove();
-      hide.remove();
-    };
-  }, [avoidKeyboard]);
-
-  // Swipe to close
-  const panResponder = useRef(
-    PanResponder.create({
-      onMoveShouldSetPanResponder: (_evt, g) =>
-        enableSwipeToClose && Math.abs(g.dy) > Math.abs(g.dx) && Math.abs(g.dy) > 5,
-      onPanResponderMove: (_evt, g) => {
-        if (!enableSwipeToClose) return;
-        if (g.dy > 0) {
-          translateY.setValue(g.dy);
-          const p = Math.min(1, g.dy / (swipeThreshold * 2));
-          fade.setValue(1 - p * 0.25);
-          scale.setValue(1 - p * 0.03);
-        }
-      },
-      onPanResponderRelease: (_evt, g) => {
-        if (!enableSwipeToClose) return;
-        if (g.dy > swipeThreshold) {
-          closeReasonRef.current = 'swipe';
-          Animated.parallel([
-            Animated.timing(translateY, { toValue: screenHeight * 0.35, duration: 180, useNativeDriver: true }),
-            Animated.timing(fade, { toValue: 0, duration: 180, useNativeDriver: true }),
-          ]).start(() => onClose?.());
-        } else {
-          Animated.parallel([
-            Animated.spring(translateY, { toValue: 0, useNativeDriver: true }),
-            Animated.spring(fade, { toValue: 1, useNativeDriver: true }),
-            Animated.spring(scale, { toValue: 1, useNativeDriver: true }),
-          ]).start();
-        }
-      },
-    })
-  ).current;
-
-  if (!mounted && !visible) return null;
-
-  return (
-    <Modal
-      transparent
-      visible={mounted || visible}
-      animationType="none"
-      onRequestClose={() => {
-        if (closeOnBackButton) {
-          closeReasonRef.current = 'backButton';
-          onClose?.();
-        }
-      }}
-      presentationStyle="overFullScreen"
-      statusBarTranslucent={Platform.OS === 'android'}
-    >
-      {/* Backdrop */}
-      <Animated.View
-        style={[
-          styles.overlay,
-          { backgroundColor: baseOverlay, opacity: fade },
-          stylesOverride.overlay,
-        ]}
-        accessibilityViewIsModal
-      >
-        {renderBackdrop ? (
-          // If you provide a custom backdrop, you control its hit area/closing
-          renderBackdrop(fade as unknown as Animated.AnimatedInterpolation<number>)
-        ) : (
-          <Pressable
-            onPress={() => {
-              onBackdropPress?.();
-              if (closeOnBackdropPress) {
-                closeReasonRef.current = 'backdrop';
-                onClose?.();
-              }
-            }}
-            style={StyleSheet.absoluteFill}
-            android_disableSound
-            accessibilityRole="button"
-            accessibilityLabel="Close quick preview"
-            testID="qp-backdrop"
-          />
-        )}
-
-        {/* Centered card */}
-        <View
-          style={[
-            styles.centerWrap,
-            { paddingBottom: Math.max(16, avoidKeyboard ? kb : 16) },
-            stylesOverride.centerWrap,
-          ]}
-          pointerEvents="box-none"
-        >
-          <Animated.View
-            {...(enableSwipeToClose ? panResponder.panHandlers : {})}
-            style={[
-              styles.container,
-              { transform: [{ scale }, { translateY }] },
-              stylesOverride.container,
-            ]}
-            testID={testID}
-            accessibilityRole={dialogA11yRole}
-            accessibilityViewIsModal
-            accessibilityLabel={accessibilityLabel}
-          >
-            {children}
-          </Animated.View>
-        </View>
-      </Animated.View>
-    </Modal>
-  );
-};
-
-const styles = StyleSheet.create({
-  overlay: { flex: 1, justifyContent: 'center', alignItems: 'center' },
-  centerWrap: {
-    flex: 1,
-    width: '100%',
-    justifyContent: 'center',
-    alignItems: 'center',
-    paddingHorizontal: 16,
-  },
-  container: {
-    width: Math.min(screenWidth * 0.92, 560),
-    maxHeight: screenHeight * 0.82,
-    borderRadius: 16,
-    overflow: 'hidden',
-    elevation: 8,
-    shadowColor: '#000',
-    shadowOpacity: 0.2,
-    shadowRadius: 12,
-    shadowOffset: { width: 0, height: 6 },
-    backgroundColor: '#fff',
-  },
-});

package/src/QuickPreviewProperties.ts

@@ -1,46 +0,0 @@
-import type { ReactNode } from 'react';
-import type { Animated } from 'react-native';
-
-export type ThemeMode = 'light' | 'dark';
-export type CloseReason = 'programmatic' | 'backdrop' | 'backButton' | 'swipe';
-
-
-export interface QuickPreviewProps {
-  visible: boolean;
-  onClose: () => void;
-
-   /** Lifecycle hooks (great for haptics/analytics) */
-   onOpen?: () => void;                     // fires when animating in
-   onClosed?: (reason: CloseReason) => void; // fires after fully closed
- 
-
-  theme?: ThemeMode;
-  backdropOpacity?: number;    // default 0.5 light / 0.8 dark
-  animationDuration?: number;  // default 220
-
-  /** Behavior toggles */
-  closeOnBackdropPress?: boolean; // default true
-  closeOnBackButton?: boolean;    // default true
-  enableSwipeToClose?: boolean;   // default true
-  swipeThreshold?: number;        // default 80
-  unmountOnExit?: boolean;        // default true
-  avoidKeyboard?: boolean;        // default false
-
-  /** Headless content */
-  children?: ReactNode;
-
-  /** Backdrop customization */
-  renderBackdrop?: (opacity: Animated.AnimatedInterpolation<number>) => ReactNode;
-  onBackdropPress?: () => void;
-
-  /** Testing & a11y */
-  testID?: string;
-  accessibilityLabel?: string;
-
-  /** Outer wrapper style overrides */
-  stylesOverride?: {
-    overlay?: any;
-    container?: any;
-    centerWrap?: any;
-  };
-}