react-native-tuto-showcase 1.0.0

package/dist/components/ContentSection.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+export default function ContentSection({ title, description, buttonText, buttonTextStyle, buttonContainerStyle, coords, onPress, }: {
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    buttonText?: string;
+    buttonTextStyle?: any;
+    buttonContainerStyle?: any;
+    coords: {
+        top?: number;
+        bottom?: number;
+    };
+    onPress: () => void;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/ContentSection.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { View, Text, Pressable, StyleSheet } from 'react-native';
+export default function ContentSection({ title, description, buttonText, buttonTextStyle, buttonContainerStyle, coords, onPress, }) {
+    return (_jsxs(View, { style: [
+            styles.contentBase,
+            coords,
+        ], children: [title ? _jsx(View, { style: styles.titleContainer, children: title }) : null, description ? (_jsx(View, { style: styles.description, children: description })) : null, _jsx(Pressable, { style: [styles.cta, buttonContainerStyle], onPress: onPress, children: _jsx(Text, { style: [styles.ctaText, buttonTextStyle], children: buttonText || 'GOT IT' }) })] }));
+}
+const styles = StyleSheet.create({
+    contentBase: {
+        position: 'absolute',
+        left: 24,
+        right: 24,
+        alignItems: 'flex-end',
+    },
+    titleContainer: {
+        marginBottom: 8,
+        alignItems: 'flex-end',
+    },
+    description: {
+        color: '#FFFFFF',
+        fontSize: 16,
+        textAlign: 'right',
+        opacity: 0.9,
+        marginBottom: 24,
+    },
+    cta: {
+        backgroundColor: '#E8E8E8',
+        paddingHorizontal: 20,
+        paddingVertical: 10,
+        borderRadius: 6,
+        elevation: 2,
+    },
+    ctaText: { color: '#333', fontSize: 14, fontWeight: '700' },
+});

package/dist/components/GestureHints.d.ts

@@ -0,0 +1,12 @@
+export type GestureHint = {
+    kind: 'left' | 'right';
+    x: number;
+    y: number;
+} | {
+    kind: 'scroll';
+    x: number;
+    y: number;
+};
+export default function GestureHints({ hints }: {
+    hints: GestureHint[];
+}): import("react/jsx-runtime").JSX.Element;

package/dist/components/GestureHints.js

@@ -0,0 +1,19 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { View, StyleSheet } from 'react-native';
+export default function GestureHints({ hints }) {
+    return (_jsx(_Fragment, { children: hints.map((h, i) => (_jsx(View, { style: [styles.hintDot, { left: h.x - 12, top: h.y - 12 }] }, i))) }));
+}
+const styles = StyleSheet.create({
+    hintDot: {
+        position: 'absolute',
+        width: 24,
+        height: 24,
+        borderRadius: 12,
+        backgroundColor: '#FFF',
+        elevation: 4,
+        shadowColor: '#000',
+        shadowOpacity: 0.25,
+        shadowRadius: 4,
+        shadowOffset: { width: 0, height: 2 },
+    },
+});

package/dist/components/LottieAboveTarget.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import { AnyShape } from '../types/shapes';
+export default function LottieAboveTarget({ shapes, lottie, }: {
+    shapes: AnyShape[];
+    lottie: React.ReactElement<any>;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/components/LottieAboveTarget.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+export default function LottieAboveTarget({ shapes, lottie, }) {
+    if (!lottie || shapes.length === 0)
+        return null;
+    const focus = shapes[shapes.length - 1];
+    const layout = StyleSheet.flatten(lottie.props?.style) || {};
+    const lw = layout.width ?? 100;
+    const lh = layout.height ?? 100;
+    const cx = focus.cx;
+    const topOfHole = focus.type === 'circle' ? focus.cy - focus.r : focus.y;
+    const top = topOfHole - lh + 50;
+    const left = cx - lw / 2;
+    return (_jsx(View, { pointerEvents: "none", style: [
+            styles.container,
+            { top, left, width: lw, height: lh },
+        ], children: React.cloneElement(lottie, {
+            autoPlay: true,
+            loop: true,
+            style: [{ width: lw, height: lh }],
+        }) }));
+}
+const styles = StyleSheet.create({
+    container: {
+        position: 'absolute',
+        justifyContent: 'center',
+        alignItems: 'center',
+    },
+});

package/dist/components/Overlay.d.ts

@@ -0,0 +1,12 @@
+import { Animated } from 'react-native';
+import { AnyShape } from '../types/shapes';
+type Props = {
+    width: number;
+    height: number;
+    shapes: AnyShape[];
+    bgColor: string;
+    spotScale: Animated.Value;
+    spotOpacity: Animated.Value;
+};
+export default function Overlay({ width, height, shapes, bgColor, spotScale, spotOpacity, }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Overlay.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import Svg, { Rect, Circle, Defs, Mask, G } from 'react-native-svg';
+import { Animated } from 'react-native';
+const AnimatedCircle = Animated.createAnimatedComponent(Circle);
+export default function Overlay({ width, height, shapes, bgColor, spotScale, spotOpacity, }) {
+    const maskId = 'tutoMask';
+    const baseR = 7; // SPOT_BASE_SIZE/2
+    const animatedR = Animated.multiply(baseR, spotScale);
+    const getAlphaColor = (color) => color.replace(/rgba?\(([^)]+)\)/, (m, inner) => {
+        const p = inner.split(',').map((s) => s.trim());
+        if (p.length >= 4) {
+            p[3] = '0.3';
+            return `rgba(${p.join(',')})`;
+        }
+        return `rgba(${p.join(',')},0.3)`;
+    });
+    return (_jsxs(Svg, { width: width, height: height, children: [_jsx(Defs, { children: _jsxs(Mask, { id: maskId, children: [_jsx(Rect, { x: 0, y: 0, width: width, height: height, fill: "white" }), shapes.map((s, i) => s.type === 'circle' ? (_jsx(Circle, { cx: s.cx, cy: s.cy, r: s.r, fill: "black" }, i)) : (_jsx(Rect, { x: s.x, y: s.y, width: s.w, height: s.h, rx: s.radius ?? s.h / 2, ry: s.radius ?? s.h / 2, fill: "black" }, i)))] }) }), _jsx(Rect, { x: 0, y: 0, width: width, height: height, fill: bgColor, mask: `url(#${maskId})` }), shapes.map((s, i) => {
+                const alpha = getAlphaColor(bgColor);
+                return (_jsx(AnimatedCircle, { cx: s.cx, cy: s.cy, r: animatedR, fill: alpha, opacity: spotOpacity }, 'spot-' + i));
+            }), _jsx(G, { children: shapes.map((s, i) => {
+                    if (!s.border)
+                        return null;
+                    const color = s.borderColor ?? '#AA999999';
+                    if (s.type === 'circle') {
+                        return (_jsx(Circle, { cx: s.cx, cy: s.cy, r: s.r * 1.2, stroke: color, strokeWidth: 2, fill: "transparent" }, 'border-' + i));
+                    }
+                    const pad = 30;
+                    return (_jsx(Rect, { x: s.x - pad, y: s.y - pad, width: s.w + pad * 2, height: s.h + pad * 2, rx: (s.h + pad * 2) / 2, ry: (s.h + pad * 2) / 2, stroke: color, strokeWidth: 2, fill: "transparent" }, 'border-' + i));
+                }) })] }));
+}

package/dist/helpers/buildActions.d.ts

@@ -0,0 +1,13 @@
+import { AnyShape } from '../types/shapes';
+import { ViewActions } from '../types/viewActions';
+import React from 'react';
+export declare function buildActionsFactory(setVisible: (b: boolean) => void, measureOverlayOrigin: () => void, setShapes: React.Dispatch<React.SetStateAction<AnyShape[]>>, setHints: React.Dispatch<React.SetStateAction<any[]>>, setClickZones: React.Dispatch<React.SetStateAction<Array<{
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    onClick?: () => void;
+}>>>, overlayOrigin: {
+    x: number;
+    y: number;
+}, expose: any): (refOrTag: React.RefObject<any> | number | null) => ViewActions;

package/dist/helpers/buildActions.js

@@ -0,0 +1,184 @@
+import { Dimensions, findNodeHandle, Platform } from 'react-native';
+import { measureInWindowAsync } from './measureInWindowAsync';
+import { toLocalRect } from './geometry';
+const DEFAULT_ADDITIONAL_RADIUS_RATIO = 1;
+const BORDER_PAD = 30;
+class ViewActionsSettings {
+    animated = true;
+    withBorder = false;
+    onClick;
+    delay = 0;
+    duration = 300;
+}
+export function buildActionsFactory(setVisible, measureOverlayOrigin, setShapes, setHints, setClickZones, overlayOrigin, expose) {
+    return function buildActions(refOrTag) {
+        const settings = new ViewActionsSettings();
+        const resolveRect = async () => {
+            if (!refOrTag)
+                return null;
+            const getTag = () => typeof refOrTag === 'number'
+                ? refOrTag
+                : findNodeHandle(refOrTag.current);
+            const tryMeasure = async (attempt = 0) => {
+                const tag = getTag();
+                if (!tag)
+                    return null;
+                const rect = await measureInWindowAsync(tag).catch(() => null);
+                if (!rect)
+                    return null;
+                const screenH = Dimensions.get('window').height;
+                const isVisible = rect.height > 0 && rect.y < screenH && rect.y + rect.height > 0;
+                if (!isVisible && attempt < 10) {
+                    await new Promise(r => setTimeout(r, 100));
+                    return tryMeasure(attempt + 1);
+                }
+                return rect;
+            };
+            return await tryMeasure();
+        };
+        const editor = (api) => api;
+        const actionEditor = (api) => api;
+        const api = {
+            on: next => buildActions(next),
+            show: () => {
+                setVisible(true);
+                requestAnimationFrame(() => measureOverlayOrigin());
+                return expose;
+            },
+            showOnce: key => {
+                expose.showOnce(key);
+                return expose;
+            },
+            onClickContentView: (_idOrRef, onClick) => {
+                resolveRect().then(r => {
+                    if (!r)
+                        return;
+                    const lr = toLocalRect(r, overlayOrigin);
+                    setClickZones(p => [
+                        ...p,
+                        { x: lr.x, y: lr.y, w: lr.width, h: lr.height, onClick }
+                    ]);
+                });
+                return expose;
+            },
+            addCircle: (ratio = DEFAULT_ADDITIONAL_RADIUS_RATIO) => {
+                resolveRect().then(r => {
+                    if (!r)
+                        return;
+                    const lr = toLocalRect(r, overlayOrigin);
+                    const cx = lr.x + lr.width / 2;
+                    const cy = lr.y + lr.height / 2;
+                    const radius = (Math.max(lr.width, lr.height) / 2) * ratio;
+                    setShapes(p => [...p, { type: 'circle', cx, cy, r: radius }]);
+                    const w = lr.width * ratio;
+                    const h = lr.height * ratio;
+                    const x = lr.x - (w - lr.width) / 2;
+                    const y = lr.y - (h - lr.height) / 2;
+                    setClickZones(p => [...p, { x, y, w, h, onClick: settings.onClick }]);
+                });
+                return editor(api);
+            },
+            addRoundRect: (ratio = DEFAULT_ADDITIONAL_RADIUS_RATIO, radius, opts) => {
+                resolveRect().then(r => {
+                    if (!r)
+                        return;
+                    const lr = toLocalRect(r, overlayOrigin);
+                    const defaultPad = Platform.OS === 'android' ? 24 : 40;
+                    const pad = opts?.pad ?? defaultPad;
+                    const baseCx = lr.x + lr.width / 2;
+                    const baseCy = lr.y + lr.height / 2;
+                    let w = lr.width + 2 * pad;
+                    let h = lr.height + 2 * pad;
+                    if (typeof opts?.w === 'number')
+                        w = opts.w;
+                    if (typeof opts?.h === 'number')
+                        h = opts.h;
+                    if (typeof opts?.dw === 'number')
+                        w = w + opts.dw;
+                    if (typeof opts?.dh === 'number')
+                        h = h + opts.dh;
+                    w = Math.max(1, w);
+                    h = Math.max(1, h);
+                    let x = baseCx - w / 2;
+                    let y = baseCy - h / 2;
+                    if (typeof opts?.dx === 'number')
+                        x += opts.dx;
+                    if (typeof opts?.dy === 'number')
+                        y += opts.dy;
+                    const cx = x + w / 2;
+                    const cy = y + h / 2;
+                    setShapes(p => [
+                        ...p,
+                        { type: 'roundrect', x, y, w, h, cx, cy, radius }
+                    ]);
+                    setClickZones(p => [...p, { x, y, w, h, onClick: settings.onClick }]);
+                });
+                return editor(api);
+            },
+            displaySwipableLeft: () => {
+                resolveRect().then(r => {
+                    if (!r)
+                        return;
+                    const lr = toLocalRect(r, overlayOrigin);
+                    setHints(p => [
+                        ...p,
+                        { kind: 'left', x: lr.x + lr.width * 0.7, y: lr.y + lr.height / 2 }
+                    ]);
+                });
+                return actionEditor(api);
+            },
+            displaySwipableRight: () => {
+                resolveRect().then(r => {
+                    if (!r)
+                        return;
+                    const lr = toLocalRect(r, overlayOrigin);
+                    setHints(p => [
+                        ...p,
+                        { kind: 'right', x: lr.x, y: lr.y + lr.height / 2 }
+                    ]);
+                });
+                return actionEditor(api);
+            },
+            displayScrollable: () => {
+                resolveRect().then(r => {
+                    if (!r)
+                        return;
+                    const lr = toLocalRect(r, overlayOrigin);
+                    setHints(p => [
+                        ...p,
+                        { kind: 'scroll', x: lr.x + lr.width / 2, y: lr.y + lr.height * 0.1 }
+                    ]);
+                });
+                return actionEditor(api);
+            },
+            withBorder: () => {
+                setShapes(prev => {
+                    if (prev.length === 0)
+                        return prev;
+                    const last = { ...prev[prev.length - 1], border: true };
+                    const arr = [...prev];
+                    arr[arr.length - 1] = last;
+                    return arr;
+                });
+                return editor(api);
+            },
+            onClick: cb => {
+                settings.onClick = cb;
+                return editor(api);
+            },
+            delayed: ms => {
+                settings.delay = ms;
+                return actionEditor(api);
+            },
+            duration: ms => {
+                settings.duration = ms;
+                return actionEditor(api);
+            },
+            animated: a => {
+                settings.animated = a;
+                return actionEditor(api);
+            }
+        };
+        return api;
+    };
+}

package/dist/helpers/geometry.d.ts

@@ -0,0 +1,10 @@
+import { LayoutRectangle } from 'react-native';
+export declare function toLocalRect(r: LayoutRectangle, overlayOrigin: {
+    x: number;
+    y: number;
+}): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};

package/dist/helpers/geometry.js

@@ -0,0 +1,10 @@
+import { Platform, StatusBar } from 'react-native';
+export function toLocalRect(r, overlayOrigin) {
+    let x = r.x - overlayOrigin.x;
+    let y = r.y - overlayOrigin.y;
+    if (Platform.OS === 'android') {
+        const sb = StatusBar.currentHeight ?? 0;
+        y = y + sb;
+    }
+    return { x, y, width: r.width, height: r.height };
+}

package/dist/helpers/measureInWindowAsync.d.ts

@@ -0,0 +1,2 @@
+import { LayoutRectangle } from 'react-native';
+export declare function measureInWindowAsync(nativeTag: number): Promise<LayoutRectangle>;

package/dist/helpers/measureInWindowAsync.js

@@ -0,0 +1,15 @@
+import { UIManager } from 'react-native';
+export function measureInWindowAsync(nativeTag) {
+    return new Promise((resolve, reject) => {
+        if (!nativeTag)
+            return reject(new Error('Invalid native tag'));
+        UIManager.measureInWindow(nativeTag, (x, y, w, h) => {
+            if (typeof x === 'number') {
+                resolve({ x, y, width: w, height: h });
+            }
+            else {
+                reject(new Error('measureInWindow failed'));
+            }
+        });
+    });
+}

package/dist/hooks/useContentPosition.d.ts

@@ -0,0 +1,5 @@
+import { AnyShape } from '../types/shapes';
+export declare function useContentPosition(visible: boolean, shapes: AnyShape[], height: number): {
+    top?: number;
+    bottom?: number;
+};

package/dist/hooks/useContentPosition.js

@@ -0,0 +1,23 @@
+import { useEffect, useState } from 'react';
+export function useContentPosition(visible, shapes, height) {
+    const [coords, setCoords] = useState({});
+    useEffect(() => {
+        if (!visible || shapes.length === 0) {
+            setCoords({ bottom: 32 });
+            return;
+        }
+        const s = shapes[shapes.length - 1];
+        const centerY = s.cy;
+        const shapeHalf = s.type === 'circle' ? s.r : s.h / 2;
+        const margin = 50; // المسافة بين الهول والمحتوى
+        if (centerY < height / 2) {
+            const top = centerY + shapeHalf + margin;
+            setCoords({ top });
+        }
+        else {
+            const bottom = height - (centerY - shapeHalf) + margin;
+            setCoords({ bottom });
+        }
+    }, [visible, shapes, height]);
+    return coords;
+}

package/dist/hooks/useOverlayMeasurements.d.ts

@@ -0,0 +1,14 @@
+import { LayoutChangeEvent } from 'react-native';
+export declare function useOverlayMeasurements(): {
+    rootRef: import("react").RefObject<any>;
+    overlayOrigin: {
+        x: number;
+        y: number;
+    };
+    overlaySize: {
+        width: number;
+        height: number;
+    };
+    onLayout: (e: LayoutChangeEvent) => void;
+    measureOverlayOrigin: () => Promise<void>;
+};

package/dist/hooks/useOverlayMeasurements.js

@@ -0,0 +1,24 @@
+import { useCallback, useRef, useState } from 'react';
+import { findNodeHandle } from 'react-native';
+import { measureInWindowAsync } from '../helpers/measureInWindowAsync';
+export function useOverlayMeasurements() {
+    const rootRef = useRef(null);
+    const [overlayOrigin, setOverlayOrigin] = useState({ x: 0, y: 0 });
+    const [overlaySize, setOverlaySize] = useState({ width: 0, height: 0 });
+    const measureOverlayOrigin = useCallback(async () => {
+        const tag = findNodeHandle(rootRef.current);
+        if (!tag)
+            return;
+        try {
+            const rect = await measureInWindowAsync(tag);
+            setOverlayOrigin({ x: rect.x, y: rect.y });
+        }
+        catch { }
+    }, []);
+    const onLayout = useCallback((e) => {
+        const { width, height } = e.nativeEvent.layout;
+        setOverlaySize({ width, height });
+        measureOverlayOrigin();
+    }, [measureOverlayOrigin]);
+    return { rootRef, overlayOrigin, overlaySize, onLayout, measureOverlayOrigin };
+}

package/dist/hooks/usePulseAnimation.d.ts

@@ -0,0 +1,5 @@
+import { Animated } from 'react-native';
+export declare function usePulseAnimation(visible: boolean): {
+    scale: Animated.Value;
+    opacity: Animated.Value;
+};

package/dist/hooks/usePulseAnimation.js

@@ -0,0 +1,46 @@
+import { useEffect, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+const SPOT_PULSE_MS = 900;
+const SPOT_SCALE_MIN = 0.85;
+const SPOT_SCALE_MAX = 1.25;
+export function usePulseAnimation(visible) {
+    const scale = useRef(new Animated.Value(1)).current;
+    const opacity = useRef(new Animated.Value(1)).current;
+    useEffect(() => {
+        if (!visible)
+            return;
+        const loop = Animated.loop(Animated.sequence([
+            Animated.parallel([
+                Animated.timing(scale, {
+                    toValue: SPOT_SCALE_MAX,
+                    duration: SPOT_PULSE_MS,
+                    easing: Easing.out(Easing.quad),
+                    useNativeDriver: true
+                }),
+                Animated.timing(opacity, {
+                    toValue: 0.85,
+                    duration: SPOT_PULSE_MS,
+                    easing: Easing.out(Easing.quad),
+                    useNativeDriver: true
+                })
+            ]),
+            Animated.parallel([
+                Animated.timing(scale, {
+                    toValue: SPOT_SCALE_MIN,
+                    duration: SPOT_PULSE_MS,
+                    easing: Easing.in(Easing.quad),
+                    useNativeDriver: true
+                }),
+                Animated.timing(opacity, {
+                    toValue: 1,
+                    duration: SPOT_PULSE_MS,
+                    easing: Easing.in(Easing.quad),
+                    useNativeDriver: true
+                })
+            ])
+        ]));
+        loop.start();
+        return () => loop.stop();
+    }, [visible]);
+    return { scale, opacity };
+}

package/dist/hooks/useShowOnce.d.ts

@@ -0,0 +1,7 @@
+export declare function useShowOnce(): {
+    shownKeys: Set<string>;
+    loaded: boolean;
+    markShown: (key: string) => void;
+    reset: (key: string) => void;
+    isShown: (key: string) => boolean;
+};

package/dist/hooks/useShowOnce.js

@@ -0,0 +1,43 @@
+import { useEffect, useState } from 'react';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+const STORAGE_KEY = '@tuto_showcase_shown_keys';
+export function useShowOnce() {
+    const [shownKeys, setShownKeys] = useState(new Set());
+    const [loaded, setLoaded] = useState(false);
+    useEffect(() => {
+        (async () => {
+            try {
+                const stored = await AsyncStorage.getItem(STORAGE_KEY);
+                if (stored) {
+                    setShownKeys(new Set(JSON.parse(stored)));
+                }
+            }
+            catch { }
+            setLoaded(true);
+        })();
+    }, []);
+    const persist = async (keys) => {
+        try {
+            await AsyncStorage.setItem(STORAGE_KEY, JSON.stringify(Array.from(keys)));
+        }
+        catch { }
+    };
+    const markShown = (key) => {
+        setShownKeys(prev => {
+            const set = new Set(prev);
+            set.add(key);
+            persist(set);
+            return set;
+        });
+    };
+    const reset = (key) => {
+        setShownKeys(prev => {
+            const set = new Set(prev);
+            set.delete(key);
+            persist(set);
+            return set;
+        });
+    };
+    const isShown = (key) => shownKeys.has(key);
+    return { shownKeys, loaded, markShown, reset, isShown };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+export type TutoShowcaseHandle = {
+    on: (r: any) => any;
+    show: () => void;
+    dismiss: () => void;
+    showOnce: (key: string) => void;
+    isShowOnce: (key: string) => boolean;
+    resetShowOnce: (key: string) => void;
+};
+declare const TutoShowcase: React.ForwardRefExoticComponent<Omit<any, "ref"> & React.RefAttributes<TutoShowcaseHandle>>;
+export default TutoShowcase;

package/dist/index.js

@@ -0,0 +1,92 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useState, useCallback, useImperativeHandle, useEffect, } from 'react';
+import { Modal, TouchableWithoutFeedback, View, StyleSheet, Dimensions, } from 'react-native';
+import Overlay from './components/Overlay';
+import GestureHints from './components/GestureHints';
+import ContentSection from './components/ContentSection';
+import LottieAboveTarget from './components/LottieAboveTarget';
+import { useShowOnce } from './hooks/useShowOnce';
+import { useOverlayMeasurements } from './hooks/useOverlayMeasurements';
+import { usePulseAnimation } from './hooks/usePulseAnimation';
+import { buildActionsFactory } from './helpers/buildActions';
+import { useContentPosition } from './hooks/useContentPosition';
+const DEFAULT_BG = 'rgba(0,0,0,0.78)';
+const TutoShowcase = forwardRef(function Tuto({ title, description, buttonText = 'GOT IT', buttonTextStyle, buttonContainerStyle, overlayBackgroundColor, onGotIt, lottie, }, ref) {
+    // -------- Hooks يجب أن تكون في الأعلى وبنفس الترتيب دائماً --------
+    const [visible, setVisible] = useState(false);
+    const [bgColor, setBgColor] = useState(overlayBackgroundColor || DEFAULT_BG);
+    const [shapes, setShapes] = useState([]);
+    const [hints, setHints] = useState([]);
+    const [clickZones, setClickZones] = useState([]);
+    const { rootRef, overlayOrigin, overlaySize, onLayout, measureOverlayOrigin, } = useOverlayMeasurements();
+    const { scale: spotScale, opacity: spotOpacity } = usePulseAnimation(visible);
+    const dims = Dimensions.get('window');
+    const width = overlaySize.width || dims.width;
+    const height = overlaySize.height || dims.height;
+    const coords = useContentPosition(visible, shapes, height);
+    const { shownKeys, loaded, markShown, reset: resetShowOnce, isShown, } = useShowOnce();
+    // لو اتغير الـ prop من برّه نحدث الـ state
+    useEffect(() => {
+        if (overlayBackgroundColor) {
+            setBgColor(overlayBackgroundColor);
+        }
+    }, [overlayBackgroundColor]);
+    const dismiss = useCallback(() => {
+        setVisible(false);
+        setShapes([]);
+        setHints([]);
+        setClickZones([]);
+    }, []);
+    const expose = {
+        on: () => { },
+        show: () => {
+            setVisible(true);
+            return;
+        },
+        dismiss,
+        showOnce: key => {
+            if (!loaded) {
+                setVisible(true);
+                markShown(key);
+                return;
+            }
+            if (shownKeys.has(key))
+                return;
+            setVisible(true);
+            markShown(key);
+        },
+        isShowOnce: key => shownKeys.has(key),
+        resetShowOnce,
+    };
+    const buildActions = buildActionsFactory(setVisible, measureOverlayOrigin, setShapes, setHints, setClickZones, overlayOrigin, expose);
+    // نربط on بالـ factory
+    expose.on = refOrTag => buildActions(refOrTag);
+    useImperativeHandle(ref, () => expose, [
+        visible,
+        shapes,
+        hints,
+        clickZones,
+        bgColor,
+        overlayOrigin,
+        shownKeys,
+        loaded,
+    ]);
+    const onOverlayPress = useCallback((evt) => {
+        const x = evt.nativeEvent.locationX;
+        const y = evt.nativeEvent.locationY;
+        for (const z of clickZones) {
+            if (x >= z.x && x <= z.x + z.w && y >= z.y && y <= z.y + z.h) {
+                z.onClick?.();
+                return;
+            }
+        }
+    }, [clickZones]);
+    // ✅ الشرط هنا بعد كل الـ hooks
+    if (!visible)
+        return null;
+    return (_jsx(Modal, { visible: true, transparent: true, animationType: "fade", children: _jsx(TouchableWithoutFeedback, { onPress: onOverlayPress, children: _jsxs(View, { ref: rootRef, onLayout: onLayout, style: [StyleSheet.absoluteFill, { direction: 'ltr' }], children: [_jsx(Overlay, { width: width, height: height, shapes: shapes, bgColor: bgColor, spotScale: spotScale, spotOpacity: spotOpacity }), lottie && _jsx(LottieAboveTarget, { shapes: shapes, lottie: lottie }), (title || description) && (_jsx(ContentSection, { title: title, description: description, buttonText: buttonText, buttonTextStyle: buttonTextStyle, buttonContainerStyle: buttonContainerStyle, coords: coords, onPress: () => {
+                            onGotIt?.();
+                            dismiss();
+                        } })), _jsx(GestureHints, { hints: hints })] }) }) }));
+});
+export default TutoShowcase;

package/dist/types/RRSizeOpts.d.ts

@@ -0,0 +1,9 @@
+export type RRSizeOpts = {
+    w?: number;
+    h?: number;
+    dw?: number;
+    dh?: number;
+    pad?: number;
+    dx?: number;
+    dy?: number;
+};

package/dist/types/RRSizeOpts.js

@@ -0,0 +1 @@
+export {};

package/dist/types/shapes.d.ts

@@ -0,0 +1,19 @@
+export type ShapeBase = {
+    border?: boolean;
+    borderColor?: string;
+    cx: number;
+    cy: number;
+};
+export type CircleShape = ShapeBase & {
+    type: 'circle';
+    r: number;
+};
+export type RoundRectShape = ShapeBase & {
+    type: 'roundrect';
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    radius?: number;
+};
+export type AnyShape = CircleShape | RoundRectShape;

package/dist/types/shapes.js

@@ -0,0 +1 @@
+export {};

package/dist/types/viewActions.d.ts

@@ -0,0 +1,19 @@
+import { RRSizeOpts } from './RRSizeOpts';
+export type ViewActions = {
+    on: (refOrTag: any) => ViewActions;
+    show: () => any;
+    showOnce: (key: string) => any;
+    onClickContentView: (idOrRef: any, onClick: () => void) => any;
+    addCircle: (ratio?: number) => ViewActionsEditor;
+    addRoundRect: (ratio?: number, radius?: number, opts?: RRSizeOpts) => ViewActionsEditor;
+    displaySwipableLeft: () => ActionViewActionsEditor;
+    displaySwipableRight: () => ActionViewActionsEditor;
+    displayScrollable: () => ActionViewActionsEditor;
+    withBorder: () => ViewActionsEditor;
+    onClick: (cb: () => void) => ViewActionsEditor;
+    delayed: (ms: number) => ActionViewActionsEditor;
+    duration: (ms: number) => ActionViewActionsEditor;
+    animated: (a: boolean) => ActionViewActionsEditor;
+};
+export type ViewActionsEditor = Pick<ViewActions, 'withBorder' | 'onClick' | 'on' | 'show' | 'showOnce' | 'onClickContentView'>;
+export type ActionViewActionsEditor = Pick<ViewActions, 'delayed' | 'duration' | 'animated' | 'on' | 'show' | 'showOnce' | 'onClickContentView'>;

package/dist/types/viewActions.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "react-native-tuto-showcase",
+  "version": "1.0.0",
+  "description": "Customizable tutorial / spotlight overlay for React Native (onboarding, feature tours, coachmarks).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "source": "src/index.tsx",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "react-native",
+    "tutorial",
+    "onboarding",
+    "spotlight",
+    "showcase",
+    "coachmark",
+    "overlay"
+  ],
+  "author": "Ahmed Mohamed Ali Ali Hegazy",
+  "license": "MIT",
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0"
+  },
+  "dependencies": {
+    "@react-native-async-storage/async-storage": "^1.23.0",
+    "react-native-svg": "^13.14.0"
+  },
+  "packageManager": "yarn@3.6.4+sha512.e70835d4d6d62c07be76b3c1529cb640c7443f0fe434ef4b6478a5a399218cbaf1511b396b3c56eb03bc86424cff2320f6167ad2fde273aa0df6e60b7754029f",
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-native": "^0.72.8",
+    "typescript": "^5.9.3"
+  }
+  
+}