@nice2dev/icons 1.0.0

package/dist/esm/animationControls.js

@@ -0,0 +1,680 @@
+import { jsx } from 'react/jsx-runtime';
+import React, { forwardRef, useState, useRef, useEffect, useImperativeHandle, useMemo, useCallback } from 'react';
+
+/* ────────────────────────────────────────────────────────────────────────────
+   2. HELPER FUNCTIONS
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Build CSS class for animation
+ */
+function getAnimationClass(animation) {
+    return `ntd-anim-${animation}`;
+}
+/**
+ * Build inline animation style
+ */
+function getAnimationStyle(animation, duration = 1000, easing = "ease-in-out", iterations = 1, delay = 0) {
+    const iterationValue = iterations < 0 ? "infinite" : iterations;
+    return {
+        animationName: `ntd-${animation}`,
+        animationDuration: `${duration}ms`,
+        animationTimingFunction: easing,
+        animationIterationCount: iterationValue,
+        animationDelay: `${delay}ms`,
+        animationFillMode: "forwards",
+    };
+}
+/**
+ * Check if config is a sequence
+ */
+function isSequenceConfig(config) {
+    return typeof config === "object" && "steps" in config;
+}
+/* ────────────────────────────────────────────────────────────────────────────
+   3. ANIMATION SEQUENCE HOOK
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Hook to manage animation sequences
+ */
+function useAnimationSequence(config) {
+    const [currentStepIndex, setCurrentStepIndex] = useState(0);
+    const [loopIteration, setLoopIteration] = useState(0);
+    const [state, setState] = useState("idle");
+    const [direction, setDirection] = useState("forward");
+    const timeoutRef = useRef(null);
+    const startTimeRef = useRef(0);
+    const elapsedRef = useRef(0);
+    const steps = useMemo(() => {
+        if (config.direction === "reverse") {
+            return [...config.steps].reverse();
+        }
+        return config.steps;
+    }, [config.steps, config.direction]);
+    const currentStep = steps[currentStepIndex];
+    const clearTimer = useCallback(() => {
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+            timeoutRef.current = null;
+        }
+    }, []);
+    const play = useCallback(() => {
+        if (state === "finished") {
+            // Reset if finished
+            setCurrentStepIndex(0);
+            setLoopIteration(0);
+            elapsedRef.current = 0;
+        }
+        setState("playing");
+        startTimeRef.current = Date.now();
+    }, [state]);
+    const pause = useCallback(() => {
+        if (state === "playing") {
+            clearTimer();
+            elapsedRef.current += Date.now() - startTimeRef.current;
+            setState("paused");
+        }
+    }, [state, clearTimer]);
+    const reset = useCallback(() => {
+        clearTimer();
+        setCurrentStepIndex(0);
+        setLoopIteration(0);
+        setDirection("forward");
+        elapsedRef.current = 0;
+        setState("idle");
+    }, [clearTimer]);
+    const goToStep = useCallback((index) => {
+        if (index >= 0 && index < steps.length) {
+            clearTimer();
+            setCurrentStepIndex(index);
+            elapsedRef.current = 0;
+            if (state === "playing") {
+                startTimeRef.current = Date.now();
+            }
+        }
+    }, [steps.length, clearTimer, state]);
+    const getProgress = useCallback(() => {
+        if (state === "idle")
+            return 0;
+        if (state === "finished")
+            return 1;
+        const stepProgress = currentStepIndex / steps.length;
+        return stepProgress;
+    }, [state, currentStepIndex, steps.length]);
+    // Handle step progression
+    useEffect(() => {
+        if (state !== "playing" || !currentStep)
+            return;
+        const stepDuration = (currentStep.duration || 1000) * (currentStep.iterations || 1);
+        const remainingTime = stepDuration - elapsedRef.current;
+        timeoutRef.current = setTimeout(() => {
+            elapsedRef.current = 0;
+            // Determine next step
+            let nextStepIndex;
+            if (config.direction === "alternate") {
+                if (direction === "forward") {
+                    if (currentStepIndex >= steps.length - 1) {
+                        setDirection("backward");
+                        nextStepIndex = currentStepIndex - 1;
+                    }
+                    else {
+                        nextStepIndex = currentStepIndex + 1;
+                    }
+                }
+                else {
+                    if (currentStepIndex <= 0) {
+                        setDirection("forward");
+                        nextStepIndex = currentStepIndex + 1;
+                    }
+                    else {
+                        nextStepIndex = currentStepIndex - 1;
+                    }
+                }
+            }
+            else {
+                nextStepIndex = currentStepIndex + 1;
+            }
+            // Check if sequence complete
+            if (nextStepIndex >= steps.length && config.direction !== "alternate") {
+                if (config.loop) {
+                    const newIteraton = loopIteration + 1;
+                    if (config.loopCount && newIteraton >= config.loopCount) {
+                        setState("finished");
+                    }
+                    else {
+                        setLoopIteration(newIteraton);
+                        setCurrentStepIndex(0);
+                        // Apply loop delay
+                        if (config.loopDelay) {
+                            setState("paused");
+                            timeoutRef.current = setTimeout(() => {
+                                setState("playing");
+                                startTimeRef.current = Date.now();
+                            }, config.loopDelay);
+                        }
+                        else {
+                            startTimeRef.current = Date.now();
+                        }
+                    }
+                }
+                else {
+                    setState("finished");
+                }
+            }
+            else if (nextStepIndex >= 0 && nextStepIndex < steps.length) {
+                setCurrentStepIndex(nextStepIndex);
+                startTimeRef.current = Date.now();
+            }
+        }, remainingTime + (currentStep.delay || 0));
+        return clearTimer;
+    }, [
+        state,
+        currentStep,
+        currentStepIndex,
+        steps.length,
+        direction,
+        config.loop,
+        config.loopCount,
+        config.loopDelay,
+        config.direction,
+        loopIteration,
+        clearTimer,
+    ]);
+    return {
+        currentStep,
+        currentStepIndex,
+        state,
+        loopIteration,
+        play,
+        pause,
+        reset,
+        goToStep,
+        getProgress,
+    };
+}
+/* ────────────────────────────────────────────────────────────────────────────
+   4. ANIMATION CONTROLLER COMPONENT
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Animation Controller component
+ *
+ * Wraps an icon and provides play/pause/reset controls.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<AnimationControllerHandle>(null);
+ *
+ * <AnimationController
+ *   ref={ref}
+ *   animation="spin"
+ *   autoPlay={false}
+ * >
+ *   <NiceIcon name="loading" />
+ * </AnimationController>
+ *
+ * <button onClick={() => ref.current?.play()}>Play</button>
+ * <button onClick={() => ref.current?.pause()}>Pause</button>
+ * <button onClick={() => ref.current?.reset()}>Reset</button>
+ * ```
+ *
+ * @example Sequence
+ * ```tsx
+ * <AnimationController
+ *   animation={{
+ *     steps: [
+ *       { animation: 'bounce', duration: 500 },
+ *       { animation: 'spin', duration: 1000 },
+ *       { animation: 'pulse', duration: 800 },
+ *     ],
+ *     loop: true,
+ *     loopCount: 3
+ *   }}
+ *   autoPlay
+ * >
+ *   <NiceIcon name="star" />
+ * </AnimationController>
+ * ```
+ */
+const AnimationController = forwardRef(function AnimationController(props, ref) {
+    const { children, animation, autoPlay = false, playState: externalPlayState, onStart, onEnd, onStepChange, onPause, onResume, className, style, } = props;
+    // Determine if sequence or single animation
+    const isSequence = isSequenceConfig(animation);
+    // For single animations
+    const [singleState, setSingleState] = useState(autoPlay ? "playing" : "idle");
+    const singleIterationRef = useRef(0);
+    // For sequences
+    const sequenceConfig = isSequence
+        ? animation
+        : { steps: [{ animation, duration: 1000 }] };
+    const sequence = useAnimationSequence(sequenceConfig);
+    // Unified state
+    const state = isSequence ? sequence.state : singleState;
+    const currentStepIndex = isSequence ? sequence.currentStepIndex : 0;
+    // Handle external playState control
+    useEffect(() => {
+        if (externalPlayState !== undefined) {
+            if (isSequence) {
+                if (externalPlayState === "playing")
+                    sequence.play();
+                else if (externalPlayState === "paused")
+                    sequence.pause();
+                else if (externalPlayState === "idle")
+                    sequence.reset();
+            }
+            else {
+                setSingleState(externalPlayState);
+            }
+        }
+    }, [externalPlayState, isSequence, sequence]);
+    // Auto-play
+    useEffect(() => {
+        if (autoPlay) {
+            if (isSequence) {
+                sequence.play();
+            }
+            else {
+                setSingleState("playing");
+            }
+            onStart === null || onStart === void 0 ? void 0 : onStart();
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Step change callback
+    const prevStepRef = useRef(currentStepIndex);
+    useEffect(() => {
+        if (prevStepRef.current !== currentStepIndex && isSequence) {
+            const step = sequenceConfig.steps[currentStepIndex];
+            onStepChange === null || onStepChange === void 0 ? void 0 : onStepChange(currentStepIndex, step);
+        }
+        prevStepRef.current = currentStepIndex;
+    }, [currentStepIndex, isSequence, sequenceConfig.steps, onStepChange]);
+    // State change callbacks
+    const prevStateRef = useRef(state);
+    useEffect(() => {
+        if (prevStateRef.current !== state) {
+            if (state === "playing" && prevStateRef.current === "paused") {
+                onResume === null || onResume === void 0 ? void 0 : onResume();
+            }
+            else if (state === "paused" && prevStateRef.current === "playing") {
+                onPause === null || onPause === void 0 ? void 0 : onPause();
+            }
+            else if (state === "finished") {
+                onEnd === null || onEnd === void 0 ? void 0 : onEnd();
+            }
+            else if (state === "playing" && prevStateRef.current === "idle") {
+                onStart === null || onStart === void 0 ? void 0 : onStart();
+            }
+        }
+        prevStateRef.current = state;
+    }, [state, onStart, onEnd, onPause, onResume]);
+    // Imperative handle
+    useImperativeHandle(ref, () => ({
+        play: () => {
+            if (isSequence) {
+                sequence.play();
+            }
+            else {
+                setSingleState("playing");
+                singleIterationRef.current++;
+            }
+            onStart === null || onStart === void 0 ? void 0 : onStart();
+        },
+        pause: () => {
+            if (isSequence) {
+                sequence.pause();
+            }
+            else {
+                setSingleState("paused");
+            }
+            onPause === null || onPause === void 0 ? void 0 : onPause();
+        },
+        reset: () => {
+            if (isSequence) {
+                sequence.reset();
+            }
+            else {
+                setSingleState("idle");
+                singleIterationRef.current++;
+            }
+        },
+        goToStep: (index) => {
+            if (isSequence) {
+                sequence.goToStep(index);
+            }
+        },
+        getState: () => state,
+        getCurrentStep: () => currentStepIndex,
+        getProgress: () => {
+            if (isSequence) {
+                return sequence.getProgress();
+            }
+            return state === "playing" ? 0.5 : state === "finished" ? 1 : 0;
+        },
+    }));
+    // Build animation styles
+    const animationStyles = useMemo(() => {
+        if (state === "idle") {
+            return {};
+        }
+        if (state === "paused") {
+            return { animationPlayState: "paused" };
+        }
+        if (isSequence && sequence.currentStep) {
+            const step = sequence.currentStep;
+            return getAnimationStyle(step.animation, step.duration, step.easing, step.iterations, step.delay);
+        }
+        if (!isSequence) {
+            return getAnimationStyle(animation, 1000, "ease-in-out", -1);
+        }
+        return {};
+    }, [state, isSequence, sequence.currentStep, animation]);
+    // Animation class
+    const animationClass = state === "playing" || state === "paused"
+        ? isSequence && sequence.currentStep
+            ? getAnimationClass(sequence.currentStep.animation)
+            : getAnimationClass(animation)
+        : "";
+    // Clone child with animation props
+    const animatedChild = React.cloneElement(children, {
+        className: `${children.props.className || ""} ${animationClass}`.trim(),
+        style: {
+            ...children.props.style,
+            ...animationStyles,
+        },
+        key: isSequence
+            ? `seq-${currentStepIndex}-${sequence.loopIteration}`
+            : `single-${singleIterationRef.current}`,
+    });
+    return (jsx("span", { className: `ntd-animation-controller ntd-animation-${state} ${className || ""}`.trim(), style: style, children: animatedChild }));
+});
+/* ────────────────────────────────────────────────────────────────────────────
+   5. INTERACTIVE ICON COMPONENT
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Interactive icon wrapper with hover/click/focus triggers
+ *
+ * @example
+ * ```tsx
+ * <InteractiveIcon
+ *   config={{
+ *     trigger: 'hover',
+ *     enterAnimation: 'bounce',
+ *     leaveAnimation: 'fadeOut',
+ *   }}
+ * >
+ *   <NiceIcon name="heart" />
+ * </InteractiveIcon>
+ * ```
+ *
+ * @example Click
+ * ```tsx
+ * <InteractiveIcon
+ *   config={{
+ *     trigger: 'click',
+ *     enterAnimation: 'pulse',
+ *     once: true,
+ *   }}
+ * >
+ *   <NiceIcon name="notification" />
+ * </InteractiveIcon>
+ * ```
+ */
+const InteractiveIcon = forwardRef(function InteractiveIcon(props, ref) {
+    const { children, config, disabled = false, onInteractionStart, onInteractionEnd, className, style, } = props;
+    const [isActive, setIsActive] = useState(false);
+    const [isLeaving, setIsLeaving] = useState(false);
+    const [hasPlayed, setHasPlayed] = useState(false);
+    const wrapperRef = useRef(null);
+    const timeoutRef = useRef(null);
+    // Merge refs
+    const setRefs = useCallback((node) => {
+        wrapperRef.current =
+            node;
+        if (typeof ref === "function") {
+            ref(node);
+        }
+        else if (ref) {
+            ref.current = node;
+        }
+    }, [ref]);
+    // Clear any pending timeouts
+    const clearTimer = useCallback(() => {
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+            timeoutRef.current = null;
+        }
+    }, []);
+    useEffect(() => clearTimer, [clearTimer]);
+    // Handle activation
+    const activate = useCallback(() => {
+        if (disabled)
+            return;
+        if (config.once && hasPlayed)
+            return;
+        clearTimer();
+        setIsLeaving(false);
+        if (config.delay) {
+            timeoutRef.current = setTimeout(() => {
+                setIsActive(true);
+                setHasPlayed(true);
+                onInteractionStart === null || onInteractionStart === void 0 ? void 0 : onInteractionStart();
+            }, config.delay);
+        }
+        else {
+            setIsActive(true);
+            setHasPlayed(true);
+            onInteractionStart === null || onInteractionStart === void 0 ? void 0 : onInteractionStart();
+        }
+    }, [disabled, config.once, config.delay, hasPlayed, clearTimer, onInteractionStart]);
+    // Handle deactivation
+    const deactivate = useCallback(() => {
+        if (!isActive)
+            return;
+        clearTimer();
+        if (config.leaveAnimation) {
+            setIsLeaving(true);
+            setIsActive(false);
+            timeoutRef.current = setTimeout(() => {
+                setIsLeaving(false);
+                onInteractionEnd === null || onInteractionEnd === void 0 ? void 0 : onInteractionEnd();
+            }, config.leaveDuration || 300);
+        }
+        else {
+            setIsActive(false);
+            onInteractionEnd === null || onInteractionEnd === void 0 ? void 0 : onInteractionEnd();
+        }
+    }, [isActive, config.leaveAnimation, config.leaveDuration, clearTimer, onInteractionEnd]);
+    // Visibility observer
+    useEffect(() => {
+        var _a;
+        if (config.trigger !== "visible" || !wrapperRef.current)
+            return;
+        const threshold = (_a = config.visibilityThreshold) !== null && _a !== void 0 ? _a : 0.5;
+        const observer = new IntersectionObserver(([entry]) => {
+            if (entry.isIntersecting) {
+                activate();
+            }
+            else if (!config.once) {
+                deactivate();
+            }
+        }, { threshold });
+        observer.observe(wrapperRef.current);
+        return () => observer.disconnect();
+    }, [config.trigger, config.visibilityThreshold, config.once, activate, deactivate]);
+    // Event handlers
+    const handleMouseEnter = config.trigger === "hover" ? activate : undefined;
+    const handleMouseLeave = config.trigger === "hover" ? deactivate : undefined;
+    const handleClick = config.trigger === "click" ? activate : undefined;
+    const handleFocus = config.trigger === "focus" ? activate : undefined;
+    const handleBlur = config.trigger === "focus" ? deactivate : undefined;
+    // Build animation props
+    const currentAnimation = isActive
+        ? config.enterAnimation
+        : isLeaving
+            ? config.leaveAnimation
+            : undefined;
+    const animationDuration = isActive
+        ? config.enterDuration
+        : config.leaveDuration;
+    const animationStyles = currentAnimation
+        ? getAnimationStyle(currentAnimation, animationDuration || 300)
+        : {};
+    const animationClass = currentAnimation
+        ? getAnimationClass(currentAnimation)
+        : "";
+    // Clone with animation
+    const animatedChild = React.cloneElement(children, {
+        className: `${children.props.className || ""} ${animationClass}`.trim(),
+        style: {
+            ...children.props.style,
+            ...animationStyles,
+        },
+    });
+    return (jsx("span", { ref: setRefs, className: `ntd-interactive-icon ${isActive ? "ntd-active" : ""} ${isLeaving ? "ntd-leaving" : ""} ${disabled ? "ntd-disabled" : ""} ${className || ""}`.trim(), style: {
+            display: "inline-flex",
+            cursor: disabled ? "default" : config.trigger === "click" ? "pointer" : undefined,
+            ...style,
+        }, onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, onClick: handleClick, onFocus: handleFocus, onBlur: handleBlur, tabIndex: config.trigger === "focus" ? 0 : undefined, role: config.trigger === "click" ? "button" : undefined, children: animatedChild }));
+});
+/* ────────────────────────────────────────────────────────────────────────────
+   6. UTILITY FUNCTIONS
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Create an animation sequence configuration
+ *
+ * @example
+ * ```tsx
+ * const seq = createAnimationSequence([
+ *   { animation: 'shake', duration: 300 },
+ *   { animation: 'pulse', duration: 500 },
+ *   { animation: 'bounce', duration: 400 },
+ * ], { loop: true, loopCount: 2 });
+ * ```
+ */
+function createAnimationSequence(steps, options) {
+    var _a, _b;
+    return {
+        steps,
+        loop: (_a = options === null || options === void 0 ? void 0 : options.loop) !== null && _a !== void 0 ? _a : false,
+        loopCount: options === null || options === void 0 ? void 0 : options.loopCount,
+        loopDelay: options === null || options === void 0 ? void 0 : options.loopDelay,
+        direction: (_b = options === null || options === void 0 ? void 0 : options.direction) !== null && _b !== void 0 ? _b : "normal",
+    };
+}
+/**
+ * Create an interactive config for hover effect
+ */
+function createHoverAnimation(enterAnimation, leaveAnimation, options) {
+    var _a, _b;
+    return {
+        trigger: "hover",
+        enterAnimation,
+        leaveAnimation,
+        enterDuration: (_a = options === null || options === void 0 ? void 0 : options.enterDuration) !== null && _a !== void 0 ? _a : 300,
+        leaveDuration: (_b = options === null || options === void 0 ? void 0 : options.leaveDuration) !== null && _b !== void 0 ? _b : 200,
+        delay: options === null || options === void 0 ? void 0 : options.delay,
+    };
+}
+/**
+ * Create an interactive config for click effect
+ */
+function createClickAnimation(animation, options) {
+    var _a, _b;
+    return {
+        trigger: "click",
+        enterAnimation: animation,
+        enterDuration: (_a = options === null || options === void 0 ? void 0 : options.duration) !== null && _a !== void 0 ? _a : 500,
+        once: (_b = options === null || options === void 0 ? void 0 : options.once) !== null && _b !== void 0 ? _b : false,
+        delay: options === null || options === void 0 ? void 0 : options.delay,
+    };
+}
+/**
+ * Create an interactive config for visibility trigger
+ */
+function createVisibilityAnimation(animation, options) {
+    var _a, _b, _c;
+    return {
+        trigger: "visible",
+        enterAnimation: animation,
+        enterDuration: (_a = options === null || options === void 0 ? void 0 : options.duration) !== null && _a !== void 0 ? _a : 600,
+        once: (_b = options === null || options === void 0 ? void 0 : options.once) !== null && _b !== void 0 ? _b : true,
+        visibilityThreshold: (_c = options === null || options === void 0 ? void 0 : options.threshold) !== null && _c !== void 0 ? _c : 0.5,
+    };
+}
+/* ────────────────────────────────────────────────────────────────────────────
+   7. PRESET SEQUENCES
+───────────────────────────────────────────────────────────────────────────── */
+/**
+ * Preset animation sequences for common use cases
+ */
+const PRESET_SEQUENCES = {
+    /** Attention grabber: bounce → shake → pulse */
+    attention: createAnimationSequence([
+        { animation: "bounce", duration: 400 },
+        { animation: "shake", duration: 300 },
+        { animation: "pulse", duration: 500 },
+    ]),
+    /** Success animation: pop → bounce */
+    success: createAnimationSequence([
+        { animation: "pop", duration: 200 },
+        { animation: "bounce", duration: 500 },
+    ]),
+    /** Error animation: shake → pulse */
+    error: createAnimationSequence([
+        { animation: "shake", duration: 500, iterations: 2 },
+        { animation: "pulse", duration: 300 },
+    ]),
+    /** Loading sequence: spin → pulse (looping) */
+    loading: createAnimationSequence([
+        { animation: "spin", duration: 1000 },
+        { animation: "pulse", duration: 500 },
+    ], { loop: true }),
+    /** Celebration: bounce → tada → heartbeat */
+    celebrate: createAnimationSequence([
+        { animation: "bounce", duration: 500 },
+        { animation: "tada", duration: 800 },
+        { animation: "heartbeat", duration: 600 },
+    ]),
+    /** Notification: swing → bounce */
+    notification: createAnimationSequence([
+        { animation: "swing", duration: 600 },
+        { animation: "bounce", duration: 400 },
+    ]),
+    /** Gentle: pulse → breathe */
+    gentle: createAnimationSequence([
+        { animation: "pulse", duration: 800 },
+        { animation: "breathe", duration: 1500 },
+    ], { loop: true }),
+    /** Reveal: fade-in → pop */
+    reveal: createAnimationSequence([
+        { animation: "fade-in", duration: 300 },
+        { animation: "pop", duration: 200 },
+    ]),
+};
+/**
+ * Preset interactive configs
+ */
+const PRESET_INTERACTIONS = {
+    /** Bounce on hover */
+    hoverBounce: createHoverAnimation("bounce"),
+    /** Pulse on hover */
+    hoverPulse: createHoverAnimation("pulse"),
+    /** Spin on hover */
+    hoverSpin: createHoverAnimation("spin"),
+    /** Shake on hover */
+    hoverShake: createHoverAnimation("shake"),
+    /** Pop on click */
+    clickPop: createClickAnimation("pop", { once: true }),
+    /** Bounce on click */
+    clickBounce: createClickAnimation("bounce"),
+    /** Tada on click */
+    clickTada: createClickAnimation("tada"),
+    /** FadeIn on visible */
+    visibleFadeIn: createVisibilityAnimation("fade-in", { once: true }),
+    /** Bounce on visible */
+    visibleBounce: createVisibilityAnimation("bounce", { once: true }),
+    /** Scale in on visible */
+    visibleScaleIn: createVisibilityAnimation("scale-in", { once: true }),
+};
+
+export { AnimationController, InteractiveIcon, PRESET_INTERACTIONS, PRESET_SEQUENCES, createAnimationSequence, createClickAnimation, createHoverAnimation, createVisibilityAnimation, useAnimationSequence };
+//# sourceMappingURL=animationControls.js.map