react-native-quick-preview 1.0.4 → 2.0.0

package/package.json

@@ -1,81 +1,103 @@
-{
-  "name": "react-native-quick-preview",
-  "version": "1.0.4",   
-  "description": "A beautiful, customizable quick preview modal component for React Native",
-  "author": "Oliver Lindblad",
-  "license": "MIT",
-
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "react-native": "dist/index.js",
-
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "react-native": "./dist/index.js",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.js",
-      "default": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-
-  "sideEffects": false,
-  "files": ["dist", "src", "README.md", "LICENSE"],
-
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "type-check": "tsc --noEmit",
-    "lint": "eslint src --ext .ts,.tsx",
-    "clean": "rimraf dist",
-    "prepublishOnly": "rimraf dist && tsup"
-  },
-
-  "keywords": [
-    "react-native",
-    "modal",
-    "preview",
-    "quicklook",
-    "expo",
-    "typescript",
-    "ui",
-    "component"
-  ],
-
-  "peerDependencies": {
-    "react": ">=18.2.0 <21",
-    "react-native": ">=0.64.0 <1"
-  },
-
-  "devDependencies": {
-    "@types/react": "^19.0.0",
-    "@typescript-eslint/eslint-plugin": "^7.18.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    "eslint": "^8.57.0",
-    "rimraf": "^6.0.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.0.0",
-
-    "react": "19.0.0",
-    "react-native": "0.79.5"
-  },
-
-  "overrides": {
-    "eslint": "^8.57.0",
-    "@typescript-eslint/parser": "^7.18.0",
-    "@typescript-eslint/eslint-plugin": "^7.18.0"
-  },
-
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Hashtagsmile/react-native-quicklook.git"
-  },
-  "bugs": {
-    "url": "https://github.com/Hashtagsmile/react-native-quicklook/issues"
-  },
-  "homepage": "https://github.com/Hashtagsmile/react-native-quicklook#readme",
-  "publishConfig": { "access": "public" },
-  "engines": { "node": ">=16" }
-}
+{
+  "name": "react-native-quick-preview",
+  "version": "2.0.0",
+  "description": "Headless long-press quick preview for React Native. Peek at any content in a popover or sheet, swipe down to dismiss.",
+  "author": "Oliver Lindblad",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "react-native": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "react-native": "./src/index.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "!src/**/__tests__/**",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "clean": "rimraf dist",
+    "prepublishOnly": "rimraf dist && tsup",
+    "test": "jest"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "modal",
+    "preview",
+    "quick-preview",
+    "quick-view",
+    "peek",
+    "long-press",
+    "bottom-sheet",
+    "popover",
+    "headless",
+    "typescript",
+    "ui",
+    "component"
+  ],
+  "peerDependencies": {
+    "react": ">=18.2.0 <21",
+    "react-native": ">=0.64.0 <1",
+    "react-native-gesture-handler": ">=2.0.0",
+    "react-native-portalize": ">=1.0.0",
+    "react-native-reanimated": ">=3.0.0",
+    "react-native-safe-area-context": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@react-native/babel-preset": "0.81.5",
+    "@testing-library/react-native": "^13.3.3",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "jest": "^29.7.0",
+    "react": "19.1.0",
+    "react-native": "0.81.5",
+    "react-native-gesture-handler": "~2.28.0",
+    "react-native-portalize": "^1.0.0",
+    "react-native-reanimated": "~4.1.1",
+    "react-native-safe-area-context": "~5.6.0",
+    "react-test-renderer": "19.1.0",
+    "rimraf": "^6.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "react-native-worklets": "~0.5.1"
+  },
+  "overrides": {
+    "eslint": "^8.57.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "@typescript-eslint/eslint-plugin": "^7.18.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hashtagsmile/react-native-quick-preview.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Hashtagsmile/react-native-quick-preview/issues"
+  },
+  "homepage": "https://github.com/Hashtagsmile/react-native-quick-preview#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "source": "src/index.ts"
+}

package/src/QuickPreviewAPI.ts

@@ -0,0 +1,70 @@
+// src/QuickPreviewAPI.ts
+import type { QuickPreviewController, QuickPreviewOptions } from './types'
+import type React from 'react'
+
+// Persist across Fast Refresh / HMR
+const STORE = Symbol.for('rnqp.controller')
+type Store = { controller: QuickPreviewController | null }
+const g = globalThis as Record<symbol, Store | undefined>
+const store: Store = g[STORE] ?? (g[STORE] = { controller: null })
+
+function warn() {
+  // __DEV__ is provided by RN/Metro; if TS complains, declare it in a globals.d.ts
+  if (typeof __DEV__ !== 'undefined' && __DEV__) {
+    // eslint-disable-next-line no-console
+    console.warn('[react-native-quick-preview] PreviewProvider not mounted yet.')
+  }
+}
+
+/**
+ * A static handle to the same controller as {@link useQuickPreview} — callable
+ * from anywhere, including outside React (services, store actions, event handlers).
+ * Before `<PreviewProvider>` mounts it is a safe no-op (with a dev warning).
+ *
+ * @example
+ * ```ts
+ * import { QuickPreview } from 'react-native-quick-preview'
+ *
+ * QuickPreview.present(<Card />, { variant: 'sheet' })
+ * QuickPreview.update({ size: { maxHeight: 480 } })
+ * QuickPreview.close()
+ * ```
+ */
+export const QuickPreview = {
+  /** @internal Registered by `<PreviewProvider />`. Not part of the public API. */
+  _set(c: QuickPreviewController | null) {
+    store.controller = c
+  },
+
+  /**
+   * Present `node` as the preview. Replaces the content if one is already open.
+   * @param node - the React element to show inside the preview.
+   * @param opts - presentation options ({@link QuickPreviewOptions}).
+   */
+  present(node: React.ReactNode, opts?: Partial<QuickPreviewOptions>) {
+    const c = store.controller
+    c ? c.present(node, opts) : warn()
+  },
+
+  /** Dismiss the current preview. No-op if nothing is open. */
+  close() {
+    const c = store.controller
+    c ? c.close() : warn()
+  },
+
+  /** Merge new options into the currently open preview. */
+  update(opts: Partial<QuickPreviewOptions>) {
+    const c = store.controller
+    c ? c.update(opts) : warn()
+  },
+
+  /** Whether a preview is currently open. */
+  isOpen() {
+    return !!store.controller?.isOpen()
+  },
+
+  /** @internal Dev/test convenience — don't use in app code. */
+  __unsafe_getController(): QuickPreviewController | null {
+    return store.controller
+  },
+} as const

package/src/addons/QuickPreviewPressable.tsx

@@ -0,0 +1,115 @@
+import React from 'react'
+import type { StyleProp, ViewStyle } from 'react-native'
+import { Gesture, GestureDetector } from 'react-native-gesture-handler'
+import Animated, {
+  runOnJS,
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated'
+import { QuickPreview } from '../QuickPreviewAPI'
+import type { QuickPreviewOptions } from '../types'
+
+export type QuickPreviewPressableProps = {
+  children: React.ReactNode
+  /** Called for a normal tap (e.g., navigate) */
+  onPress?: () => void
+  /** Return the preview node to present */
+  renderPreview: () => React.ReactNode
+  /** Options forwarded to QuickPreview.present */
+  previewOptions?: Partial<QuickPreviewOptions>
+  /** Long-press delay (ms). Default 350 */
+  delay?: number
+  /** Press-down scale. Default 0.98 */
+  scale?: number
+  /**
+   * Called on the JS thread when the long press activates, right before the
+   * preview opens. Wire up haptics here, e.g.:
+   *   onLongPressStart={() => Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Medium)}
+   * The library deliberately does not import expo-haptics itself: an optional
+   * require would break Metro bundling for apps that don't have it installed.
+   */
+  onLongPressStart?: () => void
+  /** Disable all interactions */
+  disabled?: boolean
+  /** Style applied to the animated wrapper (the thing that scales) */
+  style?: StyleProp<ViewStyle>
+  /** Accessibility */
+  accessible?: boolean
+  accessibilityLabel?: string
+  testID?: string
+}
+
+export function QuickPreviewPressable({
+  children,
+  onPress,
+  renderPreview,
+  previewOptions,
+  delay = 350,
+  scale = 0.98,
+  onLongPressStart,
+  disabled = false,
+  style,
+  accessible,
+  accessibilityLabel,
+  testID,
+}: QuickPreviewPressableProps) {
+  const s = useSharedValue(1)
+
+  // Runs on the JS thread: renderPreview() creates React elements, which must
+  // never happen on the UI thread inside a worklet.
+  const openPreview = () => {
+    onLongPressStart?.()
+    QuickPreview.present(renderPreview(), {
+      variant: 'popover',
+      dismissOnBackdropPress: true,
+      ...previewOptions,
+    })
+  }
+
+  const longPress = Gesture.LongPress()
+    .enabled(!disabled)
+    .minDuration(delay)
+    .onTouchesDown(() => {
+      s.value = withTiming(scale, { duration: 90 })
+    })
+    .onFinalize(() => {
+      s.value = withTiming(1, { duration: 120 })
+    })
+    .onStart(() => {
+      runOnJS(openPreview)()
+    })
+
+  const tap = Gesture.Tap()
+    .enabled(!disabled)
+    .maxDuration(220)
+    .onTouchesDown(() => {
+      s.value = withTiming(scale, { duration: 90 })
+    })
+    .onFinalize(() => {
+      s.value = withTiming(1, { duration: 120 })
+    })
+    .onEnd(() => {
+      if (onPress) runOnJS(onPress)()
+    })
+
+  const gesture = Gesture.Exclusive(longPress, tap)
+
+  const animated = useAnimatedStyle(() => ({
+    transform: [{ scale: s.value }],
+  }))
+
+  return (
+    <GestureDetector gesture={gesture}>
+      <Animated.View
+        style={[animated, style]}
+        accessible={accessible}
+        accessibilityRole="button"
+        accessibilityLabel={accessibilityLabel}
+        testID={testID}
+      >
+        {children}
+      </Animated.View>
+    </GestureDetector>
+  )
+}

package/src/context.tsx

@@ -0,0 +1,91 @@
+import React from 'react'
+import { BackHandler, AccessibilityInfo } from 'react-native'
+import { Host, Portal } from 'react-native-portalize'
+import { QuickPreviewOptions, QuickPreviewController } from './types'
+import { QuickPreviewRoot } from './internal/QuickPreviewRoot'
+import { QuickPreview as QuickPreviewStatic } from './QuickPreviewAPI'
+
+export const QuickPreviewContext = React.createContext<QuickPreviewController | null>(null)
+
+/**
+ * Hosts the preview layer and registers the controller. Mount this once, near the
+ * root of your app, inside a `<GestureHandlerRootView>`. After it's mounted you can
+ * present previews via {@link useQuickPreview} or the static `QuickPreview` handle.
+ *
+ * @example
+ * ```tsx
+ * <GestureHandlerRootView style={{ flex: 1 }}>
+ *   <PreviewProvider>
+ *     <YourApp />
+ *   </PreviewProvider>
+ * </GestureHandlerRootView>
+ * ```
+ */
+export function PreviewProvider({ children }: { children: React.ReactNode }) {
+  const [content, setContent] = React.useState<React.ReactNode | null>(null)
+  const [options, setOptions] = React.useState<QuickPreviewOptions | undefined>(undefined)
+  const openRef = React.useRef(false)
+
+  const announce = React.useCallback((msg: string) => {
+    // eslint-disable-next-line no-empty
+    try { AccessibilityInfo.announceForAccessibility?.(msg) } catch {}
+  }, [])
+
+  const close = React.useCallback(() => {
+    if (!openRef.current) return
+    openRef.current = false
+    setContent(null)
+    setOptions(undefined)
+    announce('Quick preview closed')
+  }, [announce])
+
+  const present = React.useCallback(
+    (node: React.ReactNode, opts?: Partial<QuickPreviewOptions>) => {
+      // Replace, don't merge: options from a previous presentation must not
+      // leak into the next one. Merging is what update() is for.
+      setOptions(opts)
+      openRef.current = true
+      setContent(() => node)
+      announce('Quick preview opened')
+    },
+    [announce]
+  )
+
+  const update = React.useCallback((opts: Partial<QuickPreviewOptions>) => {
+    setOptions(prev => ({ ...prev, ...opts }))
+  }, [])
+
+  React.useEffect(() => {
+    const sub = BackHandler.addEventListener('hardwareBackPress', () => {
+      if (openRef.current) { close(); return true }
+      return false
+    })
+    return () => sub.remove()
+  }, [close])
+
+  const value = React.useMemo<QuickPreviewController>(
+    () => ({ present, close, update, isOpen: () => openRef.current }),
+    [present, close, update]
+  )
+
+  // Register the static API (layout effect = available ASAP)
+  React.useLayoutEffect(() => {
+    QuickPreviewStatic._set(value)
+    return () => QuickPreviewStatic._set(null)
+  }, [value])
+
+  return (
+    <QuickPreviewContext.Provider value={value}>
+      <Host>
+        {children}
+        {content ? (
+          <Portal>
+            <QuickPreviewRoot options={options} onRequestClose={close}>
+              {content}
+            </QuickPreviewRoot>
+          </Portal>
+        ) : null}
+      </Host>
+    </QuickPreviewContext.Provider>
+  )
+}

package/src/headless/QuickPreview.tsx

@@ -0,0 +1,56 @@
+import React from 'react'
+import { Portal } from 'react-native-portalize'
+import { QuickPreviewOptions } from '../types'
+import { QuickPreviewRoot } from '../internal/QuickPreviewRoot'
+
+/**
+ * Props for the controlled, headless `QuickPreviewComponent`. Extends
+ * {@link QuickPreviewOptions} (so `variant`, `size`, `dismissOn*`, and the
+ * lifecycle callbacks are all accepted).
+ */
+export type HeadlessQuickPreviewProps = {
+  /** Whether the preview is shown. You own this state. */
+  visible: boolean
+  /** Called when the preview requests to close (backdrop press, swipe, back button). */
+  onClose: () => void
+  /**
+   * Render into a portal above the app. Disable only if you're providing your
+   * own host/overlay.
+   * @defaultValue `true`
+   */
+  portal?: boolean
+} & Partial<QuickPreviewOptions> & {
+  /** The preview content. */
+  children: React.ReactNode
+}
+
+/**
+ * A controlled, headless preview component — you own the `visible` state. Useful
+ * when you prefer a declarative component over the imperative
+ * {@link useQuickPreview} hook or the static `QuickPreview` handle.
+ *
+ * Exported as `QuickPreviewComponent`.
+ *
+ * @example
+ * ```tsx
+ * const [visible, setVisible] = useState(false)
+ * <QuickPreviewComponent visible={visible} onClose={() => setVisible(false)} variant="sheet">
+ *   <Card />
+ * </QuickPreviewComponent>
+ * ```
+ */
+export function QuickPreview({
+  visible,
+  onClose,
+  portal = true,
+  children,
+  ...opts
+}: HeadlessQuickPreviewProps) {
+  if (!visible) return null
+  const node = (
+    <QuickPreviewRoot options={opts} onRequestClose={onClose}>
+      {children}
+    </QuickPreviewRoot>
+  )
+  return portal ? <Portal>{node}</Portal> : node
+}

package/src/index.ts

@@ -1,2 +1,24 @@
-export { QuickLook } from './QuickLook';
-export type { QuickLookProps, ThemeMode, CloseReason  } from './QuickLookProperties';
+// src/index.ts
+
+// core
+export { PreviewProvider } from './context'
+export { useQuickPreview } from './useQuickPreview'
+
+// static API (Gorhom-style)
+export { QuickPreview } from './QuickPreviewAPI'
+
+// headless component exported under a different name
+export { QuickPreview as QuickPreviewComponent } from './headless/QuickPreview'
+
+// types / helpers
+export type {
+  QuickPreviewOptions,
+  QuickPreviewVariant,
+  QuickPreviewSize,
+  QuickPreviewController,
+} from './types'
+export { QuickPreviewScrollView } from './internal/components/QuickPreviewScrollView'
+
+
+// Addons
+export { QuickPreviewPressable } from './addons/QuickPreviewPressable'

package/src/internal/QuickPreviewRoot.tsx

@@ -0,0 +1,73 @@
+import React from 'react'
+import { StyleSheet, View } from 'react-native'
+import Animated, { useAnimatedStyle, useSharedValue, withTiming } from 'react-native-reanimated'
+import { useSafeAreaInsets } from 'react-native-safe-area-context'
+import { QuickPreviewOptions } from '../types'
+import { Backdrop } from './components/Backdrop'
+import { SheetContainer } from './components/SheetContainer'
+import { PopoverContainer } from './components/PopoverContainer'
+
+export function QuickPreviewRoot({
+  options,
+  onRequestClose,
+  children,
+}: {
+  options?: QuickPreviewOptions
+  onRequestClose: () => void
+  children: React.ReactNode
+}) {
+  const { top, bottom } = useSafeAreaInsets()
+  const variant = options?.variant ?? 'popover'
+  const dismissOnBackdropPress = options?.dismissOnBackdropPress ?? true
+
+  const opacity = useSharedValue(0)
+
+  const cbs = React.useRef({
+    onOpenStart: options?.onOpenStart,
+    onOpenEnd: options?.onOpenEnd,
+    onCloseStart: options?.onCloseStart,
+    onCloseEnd: options?.onCloseEnd,
+  })
+  React.useEffect(() => {
+    cbs.current = {
+      onOpenStart: options?.onOpenStart,
+      onOpenEnd: options?.onOpenEnd,
+      onCloseStart: options?.onCloseStart,
+      onCloseEnd: options?.onCloseEnd,
+    }
+  }, [options?.onOpenStart, options?.onOpenEnd, options?.onCloseStart, options?.onCloseEnd])
+
+  React.useEffect(() => {
+    cbs.current.onOpenStart?.()
+    opacity.value = withTiming(1, { duration: 180 }, finished => {
+      if (finished) cbs.current.onOpenEnd?.()
+    })
+    return () => {
+      cbs.current.onCloseStart?.()
+      cbs.current.onCloseEnd?.()
+    }
+    // run once (mount-only effect)
+  }, [])
+
+  const containerStyle = useAnimatedStyle(() => ({ opacity: opacity.value }))
+
+  return (
+    <View style={StyleSheet.absoluteFill} pointerEvents="box-none" accessibilityViewIsModal>
+      <Animated.View style={[StyleSheet.absoluteFill, containerStyle]} pointerEvents="box-none">
+        <Backdrop
+          onPress={dismissOnBackdropPress ? onRequestClose : undefined}
+          dismissOnBackdropPress={dismissOnBackdropPress}
+        />
+        {variant === 'sheet' ? (
+          <SheetContainer insets={{ top, bottom }} options={options} onRequestClose={onRequestClose}>
+            {children}
+          </SheetContainer>
+        ) : (
+          <PopoverContainer insets={{ top, bottom }} options={options} onRequestClose={onRequestClose}>
+            {children}
+          </PopoverContainer>
+        )}
+      </Animated.View>
+    </View>
+  )
+}

package/src/internal/components/Backdrop.tsx

@@ -0,0 +1,36 @@
+import React from 'react'
+import { Pressable, StyleSheet } from 'react-native'
+import Animated, { useAnimatedStyle, useSharedValue, withTiming } from 'react-native-reanimated'
+
+export function Backdrop({
+  onPress,
+  dismissOnBackdropPress = true,
+}: {
+  onPress?: () => void
+  dismissOnBackdropPress?: boolean
+}) {
+  const opacity = useSharedValue(0)
+  React.useEffect(() => {
+    opacity.value = withTiming(1, { duration: 160 })
+    return () => { opacity.value = 0 }
+  }, [opacity])
+
+  const style = useAnimatedStyle(() => ({
+    backgroundColor: 'rgba(0,0,0,0.5)',
+    ...StyleSheet.absoluteFillObject,
+    opacity: opacity.value,
+  }))
+
+  return (
+    <Animated.View style={style} pointerEvents={dismissOnBackdropPress && onPress ? 'auto' : 'none'}>
+      {dismissOnBackdropPress && onPress ? (
+        <Pressable
+          style={StyleSheet.absoluteFill}
+          onPress={onPress}
+          accessibilityRole="button"
+          accessibilityLabel="Close preview"
+        />
+      ) : null}
+    </Animated.View>
+  )
+}