react-native-quick-preview 1.0.4 → 2.0.0

package/dist/index.d.mts

@@ -1,42 +1,249 @@
-import React, { ReactNode } from 'react';
-import { Animated } from 'react-native';
+import React from 'react';
+import { AccessibilityRole, ScrollViewProps, StyleProp, ViewStyle } from 'react-native';
 
-type ThemeMode = 'light' | 'dark';
-type CloseReason = 'programmatic' | 'backdrop' | 'backButton' | 'swipe';
-interface QuickLookProps {
+/**
+ * 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'`
+ */
+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'`
+ */
+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,
+ * })
+ * ```
+ */
+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.
+ */
+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;
+};
+
+/**
+ * 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>
+ * ```
+ */
+declare function PreviewProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+
+/**
+ * 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>
+ *   )
+ * }
+ * ```
+ */
+declare function useQuickPreview(): QuickPreviewController;
+
+/**
+ * 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()
+ * ```
+ */
+declare const QuickPreview$1: {
+    /** @internal Registered by `<PreviewProvider />`. Not part of the public API. */
+    readonly _set: (c: QuickPreviewController | null) => void;
+    /**
+     * 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}).
+     */
+    readonly present: (node: React.ReactNode, opts?: Partial<QuickPreviewOptions>) => void;
+    /** Dismiss the current preview. No-op if nothing is open. */
+    readonly close: () => void;
+    /** Merge new options into the currently open preview. */
+    readonly update: (opts: Partial<QuickPreviewOptions>) => void;
+    /** Whether a preview is currently open. */
+    readonly isOpen: () => boolean;
+    /** @internal Dev/test convenience — don't use in app code. */
+    readonly __unsafe_getController: () => QuickPreviewController | null;
+};
+
+/**
+ * Props for the controlled, headless `QuickPreviewComponent`. Extends
+ * {@link QuickPreviewOptions} (so `variant`, `size`, `dismissOn*`, and the
+ * lifecycle callbacks are all accepted).
+ */
+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;
-    /** Lifecycle hooks (great for haptics/analytics) */
-    onOpen?: () => void;
-    onClosed?: (reason: CloseReason) => void;
-    /** Optional: press whole card (prefer explicit CTAs as well) */
-    onPressCard?: () => void;
-    theme?: ThemeMode;
-    backdropOpacity?: number;
-    animationDuration?: number;
-    /** Behavior toggles */
-    closeOnBackdropPress?: boolean;
-    closeOnBackButton?: boolean;
-    enableSwipeToClose?: boolean;
-    swipeThreshold?: number;
-    unmountOnExit?: boolean;
-    avoidKeyboard?: boolean;
-    /** 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;
-    };
-}
+    /**
+     * 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>
+ * ```
+ */
+declare function QuickPreview({ visible, onClose, portal, children, ...opts }: HeadlessQuickPreviewProps): React.JSX.Element | null;
+
+/**
+ * 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 } }
+ * )
+ * ```
+ */
+declare function QuickPreviewScrollView(props: ScrollViewProps): React.JSX.Element;
 
-declare const QuickLook: React.FC<QuickLookProps>;
+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;
+};
+declare function QuickPreviewPressable({ children, onPress, renderPreview, previewOptions, delay, scale, onLongPressStart, disabled, style, accessible, accessibilityLabel, testID, }: QuickPreviewPressableProps): React.JSX.Element;
 
-export { type CloseReason, QuickLook, type QuickLookProps, type ThemeMode };
+export { PreviewProvider, QuickPreview$1 as QuickPreview, QuickPreview as QuickPreviewComponent, type QuickPreviewController, type QuickPreviewOptions, QuickPreviewPressable, QuickPreviewScrollView, type QuickPreviewSize, type QuickPreviewVariant, useQuickPreview };

package/dist/index.d.ts

@@ -1,42 +1,249 @@
-import React, { ReactNode } from 'react';
-import { Animated } from 'react-native';
+import React from 'react';
+import { AccessibilityRole, ScrollViewProps, StyleProp, ViewStyle } from 'react-native';
 
-type ThemeMode = 'light' | 'dark';
-type CloseReason = 'programmatic' | 'backdrop' | 'backButton' | 'swipe';
-interface QuickLookProps {
+/**
+ * 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'`
+ */
+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'`
+ */
+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,
+ * })
+ * ```
+ */
+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.
+ */
+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;
+};
+
+/**
+ * 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>
+ * ```
+ */
+declare function PreviewProvider({ children }: {
+    children: React.ReactNode;
+}): React.JSX.Element;
+
+/**
+ * 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>
+ *   )
+ * }
+ * ```
+ */
+declare function useQuickPreview(): QuickPreviewController;
+
+/**
+ * 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()
+ * ```
+ */
+declare const QuickPreview$1: {
+    /** @internal Registered by `<PreviewProvider />`. Not part of the public API. */
+    readonly _set: (c: QuickPreviewController | null) => void;
+    /**
+     * 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}).
+     */
+    readonly present: (node: React.ReactNode, opts?: Partial<QuickPreviewOptions>) => void;
+    /** Dismiss the current preview. No-op if nothing is open. */
+    readonly close: () => void;
+    /** Merge new options into the currently open preview. */
+    readonly update: (opts: Partial<QuickPreviewOptions>) => void;
+    /** Whether a preview is currently open. */
+    readonly isOpen: () => boolean;
+    /** @internal Dev/test convenience — don't use in app code. */
+    readonly __unsafe_getController: () => QuickPreviewController | null;
+};
+
+/**
+ * Props for the controlled, headless `QuickPreviewComponent`. Extends
+ * {@link QuickPreviewOptions} (so `variant`, `size`, `dismissOn*`, and the
+ * lifecycle callbacks are all accepted).
+ */
+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;
-    /** Lifecycle hooks (great for haptics/analytics) */
-    onOpen?: () => void;
-    onClosed?: (reason: CloseReason) => void;
-    /** Optional: press whole card (prefer explicit CTAs as well) */
-    onPressCard?: () => void;
-    theme?: ThemeMode;
-    backdropOpacity?: number;
-    animationDuration?: number;
-    /** Behavior toggles */
-    closeOnBackdropPress?: boolean;
-    closeOnBackButton?: boolean;
-    enableSwipeToClose?: boolean;
-    swipeThreshold?: number;
-    unmountOnExit?: boolean;
-    avoidKeyboard?: boolean;
-    /** 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;
-    };
-}
+    /**
+     * 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>
+ * ```
+ */
+declare function QuickPreview({ visible, onClose, portal, children, ...opts }: HeadlessQuickPreviewProps): React.JSX.Element | null;
+
+/**
+ * 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 } }
+ * )
+ * ```
+ */
+declare function QuickPreviewScrollView(props: ScrollViewProps): React.JSX.Element;
 
-declare const QuickLook: React.FC<QuickLookProps>;
+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;
+};
+declare function QuickPreviewPressable({ children, onPress, renderPreview, previewOptions, delay, scale, onLongPressStart, disabled, style, accessible, accessibilityLabel, testID, }: QuickPreviewPressableProps): React.JSX.Element;
 
-export { type CloseReason, QuickLook, type QuickLookProps, type ThemeMode };
+export { PreviewProvider, QuickPreview$1 as QuickPreview, QuickPreview as QuickPreviewComponent, type QuickPreviewController, type QuickPreviewOptions, QuickPreviewPressable, QuickPreviewScrollView, type QuickPreviewSize, type QuickPreviewVariant, useQuickPreview };