Component API

/**
 * Main Lottie React component for declarative animation rendering
 * @param props - Component props including animation data and options
 * @returns React element with Lottie animation
 */
export default function Lottie(props: LottieComponentProps): ReactElement;

interface LottieComponentProps extends LottieOptions {
  /** Optional interactivity configuration for scroll/cursor interactions */
  interactivity?: Omit<InteractivityProps, "lottieObj">;
}

import React from "react";
import Lottie from "lottie-react";
import animationData from "./animation.json";

// Basic usage
const BasicAnimation = () => (
  <Lottie 
    animationData={animationData}
    loop={true}
    autoplay={true}
  />
);

// With styling and HTML props
const StyledAnimation = () => (
  <Lottie
    animationData={animationData}
    loop={false}
    autoplay={true}
    style={{ width: 400, height: 400 }}
    className="my-animation"
    data-testid="lottie-animation"
  />
);

// With ref for imperative access
import { useRef } from "react";

const AnimationWithRef = () => {
  const lottieRef = useRef(null);

  const handlePlay = () => {
    lottieRef.current?.play();
  };

  return (
    <div>
      <Lottie
        lottieRef={lottieRef}
        animationData={animationData}
        loop={true}
        autoplay={false}
      />
      <button onClick={handlePlay}>Play Animation</button>
    </div>
  );
};

// With event handlers
const AnimationWithEvents = () => (
  <Lottie
    animationData={animationData}
    loop={true}
    onComplete={() => console.log("Animation completed")}
    onLoopComplete={() => console.log("Loop completed")}
    onDataReady={() => console.log("Data ready")}
  />
);

// With interactivity
const InteractiveAnimation = () => (
  <Lottie
    animationData={animationData}
    loop={false}
    autoplay={false}
    interactivity={{
      mode: "scroll",
      actions: [
        {
          type: "seek",
          frames: [0, 100],
          visibility: [0, 1.0]
        }
      ]
    }}
  />
);

interface LottieComponentProps extends LottieOptions {
  /** Optional interactivity configuration for scroll/cursor interactions */
  interactivity?: {
    /** Interaction mode: scroll-based or cursor-based */
    mode: "scroll" | "cursor";
    /** Array of actions to perform based on interactions */
    actions: Action[];
  };
}

interface LottieOptions<T extends RendererType = "svg"> extends 
  Omit<AnimationConfigWithData<T>, "container" | "animationData">, 
  Omit<React.HTMLProps<HTMLDivElement>, "loop"> {
  /** Animation data object (required) */
  animationData: unknown;
  /** Optional ref for imperative access to animation controls */
  lottieRef?: LottieRef;
  /** Whether to loop the animation */
  loop?: boolean;
  /** Whether to autoplay the animation */
  autoplay?: boolean;
  /** Animation renderer type */
  renderer?: T;
  /** Animation name for debugging */
  name?: string;
  /** Path to animation assets */
  assetsPath?: string;
  /** Initial segment to play */
  initialSegment?: AnimationSegment;
  /** Renderer-specific settings */
  rendererSettings?: any;
  
  // Event handlers
  /** Called when animation completes */
  onComplete?: AnimationEventCallback | null;
  /** Called when animation loop completes */
  onLoopComplete?: AnimationEventCallback | null;
  /** Called on each frame */
  onEnterFrame?: AnimationEventCallback | null;
  /** Called when animation segment starts */
  onSegmentStart?: AnimationEventCallback | null;
  /** Called when config is ready */
  onConfigReady?: AnimationEventCallback | null;
  /** Called when data is ready */
  onDataReady?: AnimationEventCallback | null;
  /** Called when data loading fails */
  onDataFailed?: AnimationEventCallback | null;
  /** Called when images are loaded */
  onLoadedImages?: AnimationEventCallback | null;
  /** Called when DOM is loaded */
  onDOMLoaded?: AnimationEventCallback | null;
  /** Called when animation is destroyed */
  onDestroy?: AnimationEventCallback | null;
}

interface LottieRefCurrentProps {
  /** Start/resume animation playback */
  play: () => void;
  /** Stop animation and reset to beginning */
  stop: () => void;
  /** Pause animation at current frame */
  pause: () => void;
  /** Set animation playback speed */
  setSpeed: (speed: number) => void;
  /** Go to specific frame/time and stop */
  goToAndStop: (value: number, isFrame?: boolean) => void;
  /** Go to specific frame/time and play */
  goToAndPlay: (value: number, isFrame?: boolean) => void;
  /** Set animation direction (1 = forward, -1 = reverse) */
  setDirection: (direction: AnimationDirection) => void;
  /** Play specific segments of the animation */
  playSegments: (segments: AnimationSegment | AnimationSegment[], forceFlag?: boolean) => void;
  /** Enable/disable subframe rendering */
  setSubframe: (useSubFrames: boolean) => void;
  /** Get animation duration in seconds or frames */
  getDuration: (inFrames?: boolean) => number | undefined;
  /** Destroy animation instance and clean up */
  destroy: () => void;
  /** Ref to the animation container DOM element */
  animationContainerRef: RefObject<HTMLDivElement>;
  /** Whether animation data has been loaded */
  animationLoaded: boolean;
  /** Direct access to lottie-web AnimationItem instance */
  animationItem: AnimationItem | undefined;
}

type LottieRef = MutableRefObject<LottieRefCurrentProps | null>;

// Re-exported from lottie-web
type RendererType = "svg" | "canvas" | "html";
type AnimationDirection = 1 | -1;
type AnimationSegment = [number, number];
type AnimationEventCallback<T = any> = (event: T) => void;

interface AnimationConfigWithData<T extends RendererType> {
  renderer?: T;
  loop?: boolean;
  autoplay?: boolean;
  name?: string;
  assetsPath?: string;
  rendererSettings?: any;
  // ... other lottie-web config options
}

interface AnimationItem {
  play(): void;
  stop(): void;
  pause(): void;
  setSpeed(speed: number): void;
  goToAndStop(value: number, isFrame?: boolean): void;
  goToAndPlay(value: number, isFrame?: boolean): void;
  setDirection(direction: AnimationDirection): void;
  playSegments(segments: AnimationSegment | AnimationSegment[], forceFlag?: boolean): void;
  setSubframe(useSubFrames: boolean): void;
  getDuration(inFrames?: boolean): number;
  destroy(): void;
  // ... other lottie-web AnimationItem properties
}