@idealyst/lottie 1.2.29

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@idealyst/lottie",
+  "version": "1.2.29",
+  "description": "Cross-platform Lottie animation component for React and React Native",
+  "readme": "README.md",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.native.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IdealystIO/idealyst-framework.git",
+    "directory": "packages/lottie"
+  },
+  "author": "Idealyst <contact@idealyst.io>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "react-native": "./src/index.native.ts",
+      "import": "./src/index.ts",
+      "require": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "prepublishOnly": "echo 'Publishing TypeScript source directly'",
+    "publish:npm": "npm publish"
+  },
+  "peerDependencies": {
+    "lottie-react-native": ">=6.0.0",
+    "lottie-web": ">=5.0.0",
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0"
+  },
+  "peerDependenciesMeta": {
+    "lottie-react-native": {
+      "optional": true
+    },
+    "lottie-web": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "lottie-react-native": "^7.2.2",
+    "lottie-web": "^5.12.2",
+    "react": "^19.1.0",
+    "react-native": "^0.80.1",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "react",
+    "react-native",
+    "lottie",
+    "animation",
+    "cross-platform",
+    "after-effects"
+  ]
+}

package/src/Lottie.native.tsx

@@ -0,0 +1,191 @@
+/**
+ * Lottie - Native implementation
+ *
+ * Uses lottie-react-native for rendering Lottie animations on React Native.
+ */
+
+import React, { forwardRef, useImperativeHandle, useRef, useCallback } from 'react';
+import LottieView from 'lottie-react-native';
+import type { LottieProps, LottieRef, LottieJSON, LottieSource } from './types';
+
+/**
+ * Lottie animation component for React Native.
+ *
+ * @example
+ * ```tsx
+ * import { Lottie } from '@idealyst/lottie';
+ *
+ * // With require (recommended for native)
+ * <Lottie source={require('./animation.json')} autoPlay loop />
+ *
+ * // With imported JSON
+ * import animationData from './animation.json';
+ * <Lottie source={animationData} autoPlay />
+ *
+ * // With URL
+ * <Lottie source={{ uri: 'https://example.com/animation.json' }} autoPlay />
+ *
+ * // With ref for control
+ * const lottieRef = useRef<LottieRef>(null);
+ * <Lottie ref={lottieRef} source={require('./animation.json')} />
+ * lottieRef.current?.play();
+ * ```
+ */
+export const Lottie = forwardRef<LottieRef, LottieProps>((props, ref) => {
+  const {
+    source,
+    autoPlay = true,
+    loop = false,
+    speed = 1,
+    style,
+    resizeMode = 'contain',
+    progress,
+    onComplete,
+    onLoad,
+    onError,
+    onAnimationUpdate,
+    visible = true,
+    testID,
+  } = props;
+
+  const lottieRef = useRef<LottieView>(null);
+  const isPlayingRef = useRef(autoPlay);
+  const totalFramesRef = useRef(0);
+  const frameRateRef = useRef(30);
+
+  // Convert source to lottie-react-native format
+  const getSource = (): any => {
+    if (typeof source === 'string') {
+      // URL string - wrap in uri object
+      return { uri: source };
+    }
+    if (typeof source === 'object' && 'uri' in source) {
+      // Already in { uri: string } format
+      return source;
+    }
+    // Direct JSON object or require()
+    return source;
+  };
+
+  // Handle animation load
+  const handleLoad = useCallback(() => {
+    // Try to get animation info from the ref
+    // Note: lottie-react-native doesn't expose these directly in all cases
+    onLoad?.();
+  }, [onLoad]);
+
+  // Handle animation finish
+  const handleFinish = useCallback(
+    (isCancelled: boolean) => {
+      if (!isCancelled) {
+        isPlayingRef.current = false;
+        onComplete?.();
+      }
+    },
+    [onComplete]
+  );
+
+  // Handle animation failure
+  const handleFailure = useCallback(
+    (error: any) => {
+      onError?.(new Error(error?.message || 'Failed to load animation'));
+    },
+    [onError]
+  );
+
+  // Imperative handle for ref methods
+  useImperativeHandle(
+    ref,
+    () => ({
+      play: () => {
+        isPlayingRef.current = true;
+        lottieRef.current?.play();
+      },
+      pause: () => {
+        isPlayingRef.current = false;
+        lottieRef.current?.pause();
+      },
+      stop: () => {
+        isPlayingRef.current = false;
+        lottieRef.current?.reset();
+      },
+      reset: () => {
+        lottieRef.current?.reset();
+      },
+      setProgress: (value: number) => {
+        // lottie-react-native uses progress prop for this
+        // For imperative control, we need to use play with segments
+        if (lottieRef.current && totalFramesRef.current > 0) {
+          const frame = Math.floor(value * totalFramesRef.current);
+          lottieRef.current.play(frame, frame);
+        }
+      },
+      goToAndStop: (frame: number, isFrame = true) => {
+        isPlayingRef.current = false;
+        if (lottieRef.current) {
+          // Play to the frame and immediately pause
+          lottieRef.current.play(frame, frame);
+        }
+      },
+      goToAndPlay: (frame: number, isFrame = true) => {
+        isPlayingRef.current = true;
+        if (lottieRef.current) {
+          lottieRef.current.play(frame, undefined);
+        }
+      },
+      setSpeed: (value: number) => {
+        // Speed is controlled via prop, not imperatively in lottie-react-native
+        console.warn('setSpeed: Use the speed prop instead for native');
+      },
+      setDirection: (direction: 1 | -1) => {
+        // Direction is controlled via speed sign
+        console.warn('setDirection: Use negative speed for reverse playback');
+      },
+      playSegments: (startFrame: number, endFrame: number, forceFlag = false) => {
+        isPlayingRef.current = true;
+        lottieRef.current?.play(startFrame, endFrame);
+      },
+      getCurrentFrame: () => {
+        // Not directly available in lottie-react-native
+        return 0;
+      },
+      getTotalFrames: () => {
+        return totalFramesRef.current;
+      },
+      getDuration: () => {
+        return totalFramesRef.current / frameRateRef.current;
+      },
+      isPlaying: () => {
+        return isPlayingRef.current;
+      },
+      destroy: () => {
+        // React Native handles cleanup automatically
+        lottieRef.current?.reset();
+      },
+    }),
+    []
+  );
+
+  if (!visible) {
+    return null;
+  }
+
+  return (
+    <LottieView
+      ref={lottieRef}
+      source={getSource()}
+      autoPlay={autoPlay}
+      loop={typeof loop === 'boolean' ? loop : true}
+      speed={speed}
+      style={style}
+      resizeMode={resizeMode}
+      progress={progress}
+      onAnimationLoaded={handleLoad}
+      onAnimationFinish={handleFinish}
+      onAnimationFailure={handleFailure}
+      testID={testID}
+    />
+  );
+});
+
+Lottie.displayName = 'Lottie';

package/src/Lottie.tsx

@@ -0,0 +1,250 @@
+/**
+ * Lottie - Web implementation
+ *
+ * Uses lottie-web for rendering Lottie animations on the web.
+ */
+
+import React, {
+  forwardRef,
+  useImperativeHandle,
+  useRef,
+  useEffect,
+  useCallback,
+  useState,
+} from 'react';
+import lottie, { AnimationItem } from 'lottie-web';
+import type { LottieProps, LottieRef, LottieJSON } from './types';
+
+/**
+ * Lottie animation component for web.
+ *
+ * @example
+ * ```tsx
+ * import { Lottie } from '@idealyst/lottie';
+ *
+ * // With imported JSON
+ * import animationData from './animation.json';
+ * <Lottie source={animationData} autoPlay loop />
+ *
+ * // With URL
+ * <Lottie source="https://example.com/animation.json" autoPlay />
+ *
+ * // With ref for control
+ * const lottieRef = useRef<LottieRef>(null);
+ * <Lottie ref={lottieRef} source={animationData} />
+ * lottieRef.current?.play();
+ * ```
+ */
+export const Lottie = forwardRef<LottieRef, LottieProps>((props, ref) => {
+  const {
+    source,
+    autoPlay = true,
+    loop = false,
+    speed = 1,
+    style,
+    resizeMode = 'contain',
+    progress,
+    onComplete,
+    onLoad,
+    onError,
+    onAnimationUpdate,
+    visible = true,
+    testID,
+  } = props;
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const animationRef = useRef<AnimationItem | null>(null);
+  const [isLoaded, setIsLoaded] = useState(false);
+
+  // Convert loop prop to lottie-web format
+  const loopValue = typeof loop === 'number' ? loop : loop;
+
+  // Load animation
+  useEffect(() => {
+    if (!containerRef.current || !visible) return;
+
+    const loadAnimation = async () => {
+      try {
+        // Determine animation data
+        let animationData: LottieJSON | undefined;
+        let path: string | undefined;
+
+        if (typeof source === 'string') {
+          // URL string
+          path = source;
+        } else if (typeof source === 'object' && 'uri' in source) {
+          // { uri: string } format
+          path = source.uri;
+        } else {
+          // Direct JSON object
+          animationData = source as LottieJSON;
+        }
+
+        // Destroy previous animation if exists
+        if (animationRef.current) {
+          animationRef.current.destroy();
+        }
+
+        // Create new animation
+        const anim = lottie.loadAnimation({
+          container: containerRef.current!,
+          renderer: 'svg',
+          loop: loopValue,
+          autoplay: autoPlay,
+          animationData,
+          path,
+          rendererSettings: {
+            preserveAspectRatio:
+              resizeMode === 'cover'
+                ? 'xMidYMid slice'
+                : resizeMode === 'contain'
+                  ? 'xMidYMid meet'
+                  : 'xMidYMid meet',
+          },
+        });
+
+        animationRef.current = anim;
+
+        // Set speed
+        anim.setSpeed(speed);
+
+        // Set initial progress if provided
+        if (progress !== undefined) {
+          const frame = progress * anim.totalFrames;
+          anim.goToAndStop(frame, true);
+        }
+
+        // Event handlers
+        anim.addEventListener('DOMLoaded', () => {
+          setIsLoaded(true);
+          onLoad?.();
+        });
+
+        anim.addEventListener('complete', () => {
+          onComplete?.();
+        });
+
+        anim.addEventListener('loopComplete', () => {
+          // For loop counts, onComplete is called when all loops finish
+          if (typeof loop === 'number') {
+            // lottie-web handles loop count internally
+          }
+        });
+
+        anim.addEventListener('enterFrame', (e: any) => {
+          onAnimationUpdate?.(e.currentTime);
+        });
+
+        anim.addEventListener('data_failed', () => {
+          onError?.(new Error('Failed to load animation data'));
+        });
+      } catch (error) {
+        onError?.(error instanceof Error ? error : new Error(String(error)));
+      }
+    };
+
+    loadAnimation();
+
+    return () => {
+      if (animationRef.current) {
+        animationRef.current.destroy();
+        animationRef.current = null;
+      }
+    };
+  }, [source, visible]);
+
+  // Update loop when it changes
+  useEffect(() => {
+    if (animationRef.current) {
+      animationRef.current.loop = loopValue;
+    }
+  }, [loopValue]);
+
+  // Update speed when it changes
+  useEffect(() => {
+    if (animationRef.current) {
+      animationRef.current.setSpeed(speed);
+    }
+  }, [speed]);
+
+  // Update progress when it changes
+  useEffect(() => {
+    if (animationRef.current && progress !== undefined && isLoaded) {
+      const frame = progress * animationRef.current.totalFrames;
+      animationRef.current.goToAndStop(frame, true);
+    }
+  }, [progress, isLoaded]);
+
+  // Imperative handle for ref methods
+  useImperativeHandle(
+    ref,
+    () => ({
+      play: () => {
+        animationRef.current?.play();
+      },
+      pause: () => {
+        animationRef.current?.pause();
+      },
+      stop: () => {
+        animationRef.current?.stop();
+      },
+      reset: () => {
+        animationRef.current?.goToAndStop(0, true);
+      },
+      setProgress: (value: number) => {
+        if (animationRef.current) {
+          const frame = value * animationRef.current.totalFrames;
+          animationRef.current.goToAndStop(frame, true);
+        }
+      },
+      goToAndStop: (frame: number, isFrame = true) => {
+        animationRef.current?.goToAndStop(frame, isFrame);
+      },
+      goToAndPlay: (frame: number, isFrame = true) => {
+        animationRef.current?.goToAndPlay(frame, isFrame);
+      },
+      setSpeed: (value: number) => {
+        animationRef.current?.setSpeed(value);
+      },
+      setDirection: (direction: 1 | -1) => {
+        animationRef.current?.setDirection(direction);
+      },
+      playSegments: (startFrame: number, endFrame: number, forceFlag = false) => {
+        animationRef.current?.playSegments([startFrame, endFrame], forceFlag);
+      },
+      getCurrentFrame: () => {
+        return animationRef.current?.currentFrame ?? 0;
+      },
+      getTotalFrames: () => {
+        return animationRef.current?.totalFrames ?? 0;
+      },
+      getDuration: () => {
+        if (!animationRef.current) return 0;
+        return animationRef.current.totalFrames / animationRef.current.frameRate;
+      },
+      isPlaying: () => {
+        return animationRef.current ? !animationRef.current.isPaused : false;
+      },
+      destroy: () => {
+        animationRef.current?.destroy();
+        animationRef.current = null;
+      },
+    }),
+    []
+  );
+
+  if (!visible) {
+    return null;
+  }
+
+  // Convert ViewStyle to CSSProperties for web
+  const containerStyle: React.CSSProperties = {
+    width: '100%',
+    height: '100%',
+    ...(style as React.CSSProperties),
+  };
+
+  return <div ref={containerRef} style={containerStyle} data-testid={testID} />;
+});
+
+Lottie.displayName = 'Lottie';

package/src/index.native.ts

@@ -0,0 +1,48 @@
+/**
+ * @idealyst/lottie - Native exports
+ *
+ * Cross-platform Lottie animation component for React and React Native.
+ *
+ * @example
+ * ```tsx
+ * import { Lottie, LottieRef } from '@idealyst/lottie';
+ *
+ * // With require (recommended for native)
+ * <Lottie source={require('./animation.json')} autoPlay loop />
+ *
+ * // With imported JSON
+ * import animationData from './animation.json';
+ * <Lottie source={animationData} autoPlay />
+ *
+ * // With URL
+ * <Lottie source={{ uri: 'https://example.com/animation.json' }} autoPlay />
+ *
+ * // With ref for imperative control
+ * const lottieRef = useRef<LottieRef>(null);
+ *
+ * <Lottie
+ *   ref={lottieRef}
+ *   source={require('./animation.json')}
+ *   onComplete={() => console.log('done')}
+ * />
+ *
+ * // Control playback
+ * lottieRef.current?.play();
+ * lottieRef.current?.pause();
+ * ```
+ */
+
+// Type exports
+export type {
+  LottieProps,
+  LottieRef,
+  LottieJSON,
+  LottieSource,
+  AnimationSpeed,
+  LoopConfig,
+  ResizeMode,
+  AnimationDirection,
+} from './types';
+
+// Component export
+export { Lottie } from './Lottie.native';

package/src/index.ts

@@ -0,0 +1,46 @@
+/**
+ * @idealyst/lottie - Web exports
+ *
+ * Cross-platform Lottie animation component for React and React Native.
+ *
+ * @example
+ * ```tsx
+ * import { Lottie, LottieRef } from '@idealyst/lottie';
+ *
+ * // Basic usage
+ * <Lottie source="https://example.com/animation.json" autoPlay loop />
+ *
+ * // With imported JSON
+ * import animationData from './animation.json';
+ * <Lottie source={animationData} autoPlay />
+ *
+ * // With ref for imperative control
+ * const lottieRef = useRef<LottieRef>(null);
+ *
+ * <Lottie
+ *   ref={lottieRef}
+ *   source={animationData}
+ *   onComplete={() => console.log('done')}
+ * />
+ *
+ * // Control playback
+ * lottieRef.current?.play();
+ * lottieRef.current?.pause();
+ * lottieRef.current?.setProgress(0.5);
+ * ```
+ */
+
+// Type exports
+export type {
+  LottieProps,
+  LottieRef,
+  LottieJSON,
+  LottieSource,
+  AnimationSpeed,
+  LoopConfig,
+  ResizeMode,
+  AnimationDirection,
+} from './types';
+
+// Component export
+export { Lottie } from './Lottie';

package/src/types.ts

@@ -0,0 +1,226 @@
+/**
+ * Type definitions for @idealyst/lottie
+ */
+
+import type { ViewStyle } from 'react-native';
+
+/**
+ * Lottie animation JSON structure (simplified type)
+ */
+export interface LottieJSON {
+  v: string; // version
+  fr: number; // frame rate
+  ip: number; // in point
+  op: number; // out point
+  w: number; // width
+  h: number; // height
+  nm?: string; // name
+  ddd?: number; // 3D
+  assets?: any[];
+  layers: any[];
+  markers?: any[];
+}
+
+/**
+ * Animation source - can be a URL, imported JSON, or require()
+ */
+export type LottieSource = string | LottieJSON | { uri: string };
+
+/**
+ * Animation speed multiplier
+ */
+export type AnimationSpeed = number;
+
+/**
+ * Loop configuration
+ */
+export type LoopConfig = boolean | number;
+
+/**
+ * Resize mode for the animation
+ */
+export type ResizeMode = 'cover' | 'contain' | 'center';
+
+/**
+ * Direction of animation playback
+ */
+export type AnimationDirection = 1 | -1;
+
+/**
+ * Props for the Lottie component
+ */
+export interface LottieProps {
+  /**
+   * The animation source. Can be:
+   * - A URL string to a .json file
+   * - An imported JSON object
+   * - A require() statement (native only)
+   * - An object with { uri: string }
+   */
+  source: LottieSource;
+
+  /**
+   * Whether to start playing immediately on mount.
+   * @default true
+   */
+  autoPlay?: boolean;
+
+  /**
+   * Whether to loop the animation.
+   * - true: loop infinitely
+   * - false: play once
+   * - number: loop that many times
+   * @default false
+   */
+  loop?: LoopConfig;
+
+  /**
+   * Playback speed multiplier.
+   * - 1 = normal speed
+   * - 2 = double speed
+   * - 0.5 = half speed
+   * - negative values play in reverse
+   * @default 1
+   */
+  speed?: AnimationSpeed;
+
+  /**
+   * Style to apply to the container view.
+   */
+  style?: ViewStyle;
+
+  /**
+   * How the animation should be resized to fit its container.
+   * @default 'contain'
+   */
+  resizeMode?: ResizeMode;
+
+  /**
+   * Initial progress value (0-1).
+   * Useful for showing a specific frame on mount.
+   */
+  progress?: number;
+
+  /**
+   * Callback when the animation completes a loop or finishes.
+   */
+  onComplete?: () => void;
+
+  /**
+   * Callback when the animation is loaded and ready to play.
+   */
+  onLoad?: () => void;
+
+  /**
+   * Callback when there's an error loading the animation.
+   */
+  onError?: (error: Error) => void;
+
+  /**
+   * Callback for animation frame updates.
+   * Called with the current frame number.
+   */
+  onAnimationUpdate?: (frame: number) => void;
+
+  /**
+   * Whether the component should render.
+   * Useful for conditional rendering without unmounting.
+   * @default true
+   */
+  visible?: boolean;
+
+  /**
+   * Test ID for testing frameworks.
+   */
+  testID?: string;
+}
+
+/**
+ * Ref methods available on the Lottie component
+ */
+export interface LottieRef {
+  /**
+   * Start playing the animation from the current position.
+   */
+  play: () => void;
+
+  /**
+   * Pause the animation at the current position.
+   */
+  pause: () => void;
+
+  /**
+   * Stop the animation and reset to the beginning.
+   */
+  stop: () => void;
+
+  /**
+   * Reset the animation to the beginning without stopping.
+   */
+  reset: () => void;
+
+  /**
+   * Set the animation progress (0-1).
+   * @param progress - Value between 0 and 1
+   */
+  setProgress: (progress: number) => void;
+
+  /**
+   * Go to a specific frame.
+   * @param frame - Frame number
+   * @param isFrame - Whether the value is a frame number (true) or time in seconds (false)
+   */
+  goToAndStop: (frame: number, isFrame?: boolean) => void;
+
+  /**
+   * Go to a specific frame and start playing.
+   * @param frame - Frame number
+   * @param isFrame - Whether the value is a frame number (true) or time in seconds (false)
+   */
+  goToAndPlay: (frame: number, isFrame?: boolean) => void;
+
+  /**
+   * Set the playback speed.
+   * @param speed - Speed multiplier
+   */
+  setSpeed: (speed: number) => void;
+
+  /**
+   * Set the playback direction.
+   * @param direction - 1 for forward, -1 for reverse
+   */
+  setDirection: (direction: AnimationDirection) => void;
+
+  /**
+   * Play a specific segment of the animation.
+   * @param startFrame - Start frame
+   * @param endFrame - End frame
+   * @param forceFlag - Whether to force the segment (native only)
+   */
+  playSegments: (startFrame: number, endFrame: number, forceFlag?: boolean) => void;
+
+  /**
+   * Get the current frame number.
+   */
+  getCurrentFrame: () => number;
+
+  /**
+   * Get the total number of frames.
+   */
+  getTotalFrames: () => number;
+
+  /**
+   * Get the animation duration in seconds.
+   */
+  getDuration: () => number;
+
+  /**
+   * Check if the animation is currently playing.
+   */
+  isPlaying: () => boolean;
+
+  /**
+   * Destroy the animation instance and clean up resources.
+   */
+  destroy: () => void;
+}