@lordicon/web 1.0.0 → 1.1.0

package/dist/{index.d.ts → src/player.d.ts}

@@ -1,388 +1,233 @@
-/**
- * Object storing multiple named colors.
- *
- * Example:
- * {
- *     primary: 'red',
- *     secondary: '#ff0000',
- * }
- */
-export declare interface ColorMap {
-    [key: string]: string;
-}
-
-/**
- * Player event callback type.
- */
-export declare type EventHandler = () => void;
-
-/**
- * Supported player event names.
- */
-export declare type EventName = 'ready' | 'complete' | 'frame' | 'refresh';
-
-/**
- * Animation segment as a tuple: [startFrame, endFrame].
- */
-declare type FrameSegment = [number, number];
-
-/**
- * Properties for customizing icons.
- *
- * Example:
- * {
- *     stroke: 'bold',
- *     colors: {
- *         primary: 'red',
- *     },
- * }
- */
-export declare interface IconProperties {
-    /**
-     * State (motion type) of the icon. States allow switching between multiple animations built into a single icon file.
-     */
-    state?: string;
-    /**
-     * Colors.
-     */
-    colors?: ColorMap;
-    /**
-     * Stroke.
-     */
-    stroke?: Stroke;
-}
-
-/**
- * Details of a single animation state.
- */
-export declare interface IconState {
-    name: string;
-    time: number;
-    duration: number;
-    params: string[];
-    default?: boolean;
-}
-
-/**
- * Properties for legacy icons.
- */
-export declare interface LegacyIconProperties {
-    /**
-     * Scale for legacy icons.
-     */
-    scale?: number;
-    /**
-     * Axis x for legacy icons.
-     */
-    axisX?: number;
-    /**
-     * Axis y for legacy icons.
-     */
-    axisY?: number;
-}
-
-/**
- * Represents a single Lottie animation instance from `@lordicon/internal`.
- * Contains the current state and methods for controlling playback.
- */
-declare type LottieAnimationInstance = {
-    name: string;
-    isLoaded: boolean;
-    currentFrame: number;
-    currentRawFrame: number;
-    firstFrame: number;
-    totalFrames: number;
-    frameRate: number;
-    frameMult: number;
-    playSpeed: number;
-    playDirection: number;
-    playCount: number;
-    isPaused: boolean;
-    autoplay: boolean;
-    loop: boolean | number;
-    renderer: any;
-    animationID: string;
-    assetsPath: string;
-    timeCompleted: number;
-    segmentPos: number;
-    isSubframeEnabled: boolean;
-    segments: FrameSegment | FrameSegment[];
-    play(name?: string): void;
-    stop(name?: string): void;
-    togglePause(name?: string): void;
-    destroy(name?: string): void;
-    pause(name?: string): void;
-    goToAndStop(value: number | string, isFrame?: boolean, name?: string): void;
-    goToAndPlay(value: number | string, isFrame?: boolean, name?: string): void;
-    includeLayers(data: any): void;
-    setSegment(init: number, end: number): void;
-    resetSegments(forceFlag: boolean): void;
-    hide(): void;
-    show(): void;
-    resize(): void;
-    setSpeed(speed: number): void;
-    setDirection(direction: PlaybackDirection_2): void;
-    setLoop(isLooping: boolean): void;
-    playSegments(segments: FrameSegment | FrameSegment[], forceFlag?: boolean): void;
-    setSubframe(useSubFrames: boolean): void;
-    getDuration(inFrames?: boolean): number;
-    triggerEvent(name: string, args: any): void;
-    addEventListener(name: string, callback: any): () => void;
-    removeEventListener(name: string, callback?: any): void;
-};
-
-/**
- * Icon animation data in Lottie JSON format.
- * This player is optimized for icons from [Lordicon](https://lordicon.com/).
- */
-declare type LottieData = any;
-
-/**
- * Describes a property found in the animation.
- */
-declare interface LottieProperty {
-    name: string;
-    path: string;
-    type: LottiePropertyType;
-    value: any;
-}
-
-/**
- * Supported property types for Lottie animations.
- */
-declare type LottiePropertyType = 'color' | 'slider' | 'point' | 'checkbox' | 'feature';
-
-/**
- * Animation playback direction: 1 (forward) or -1 (backward).
- */
-declare type PlaybackDirection_2 = 1 | -1;
-export { PlaybackDirection_2 as PlaybackDirection }
-
-/**
- * Player class for controlling and customizing Lottie-based icons.
- */
-export declare class Player {
-    protected _container: HTMLElement;
-    protected _iconData: any;
-    protected _initialProperties: IconProperties & LegacyIconProperties;
-    protected _lottieInstance?: LottieAnimationInstance;
-    protected _ready: boolean;
-    protected _colorsProxy?: any;
-    protected _direction: PlaybackDirection_2;
-    protected _speed: number;
-    protected _lottieProperties?: LottieProperty[];
-    protected _eventHandlers: any;
-    protected _state?: IconState;
-    protected _availableStates: IconState[];
-    /**
-     * Creates a new Player instance.
-     * @param container The DOM element where the animation will be rendered.
-     * @param data Lottie animation data.
-     * @param properties Initial icon properties (colors, stroke, state, etc.).
-     * @param options Additional options (e.g., autoInit).
-     */
-    constructor(container: HTMLElement, data: LottieData, properties?: IconProperties & LegacyIconProperties, options?: {
-        autoInit?: boolean;
-    });
-    /**
-     * Initializes the player and connects it to the DOM element.
-     * Throws an error if already initialized.
-     */
-    init(): void;
-    /**
-     * Destroys the player and releases all resources.
-     * Throws an error if not initialized.
-     */
-    destroy(): void;
-    /**
-     * Registers an event listener for a player event.
-     * @param name Event name (e.g., 'complete', 'frame', 'ready').
-     * @param handler Handler function to call when the event is triggered.
-     * @returns Function to remove the listener.
-     */
-    addEventListener(name: EventName, handler: EventHandler): () => void;
-    /**
-     * Removes an event listener for a player event.
-     * @param name Event name.
-     * @param handler Handler function to remove. If not provided, removes all handlers for the event.
-     */
-    removeEventListener(name: EventName, handler?: EventHandler): void;
-    /**
-     * Triggers a player event and invokes all registered callbacks.
-     * @param name Event name.
-     * @param args Optional arguments to pass to the callbacks.
-     */
-    protected triggerEvent(name: EventName, args?: any): void;
-    /**
-     * Forces a re-render of the animation.
-     */
-    protected refresh(): void;
-    /**
-     * Starts playing the animation from the current frame.
-     * Note: If the animation is finished, it cannot be played again from the last frame.
-     */
-    play(): void;
-    /**
-     * Plays the animation from the beginning of the current state or from the start if no state is set.
-     */
-    playFromStart(): void;
-    /**
-     * Pauses the animation at the current frame.
-     */
-    pause(): void;
-    /**
-     * Stop the animation.
-     */
-    stop(): void;
-    /**
-     * Moves the animation to a specific frame and stops.
-     * @param frame Frame number to seek to.
-     */
-    seek(frame: number): void;
-    /**
-     * Moves the animation to the first frame and stops.
-     */
-    seekToStart(): void;
-    /**
-     * Moves the animation to the last frame and stops.
-     */
-    seekToEnd(): void;
-    /**
-     * Sets the animation segment to play.
-     * If no segment is provided, resets to the default segment.
-     * @param segment Optional segment as [start, end] frame numbers.
-     */
-    switchSegment(segment?: [number, number]): void;
-    /**
-     * Sets multiple icon properties at once.
-     * Any property not provided will be reset to its default value.
-     * @param properties Properties to assign.
-     */
-    set properties(properties: IconProperties);
-    /**
-     * Gets the current icon properties (colors, stroke, state).
-     * @returns The current properties.
-     */
-    get properties(): IconProperties;
-    /**
-     * Sets all customizable colors at once.
-     * Pass null to reset all colors to default.
-     * @param colors Color map or null.
-     */
-    set colors(colors: ColorMap | null);
-    /**
-     * Provides a proxy for reading or updating individual colors by name.
-     *
-     * Example:
-     *   player.colors.primary = '#ff0000';
-     *   delete player.colors.secondary;
-     */
-    get colors(): ColorMap;
-    /**
-     * Sets the stroke width for the icon.
-     * Pass null to reset to default.
-     * @param stroke Stroke value or null.
-     */
-    set stroke(stroke: Stroke | null);
-    /**
-     * Gets the current stroke width of the icon.
-     * @returns Stroke value or null if not set.
-     */
-    get stroke(): Stroke | null;
-    /**
-     * Sets the current state (animation segment) of the icon.
-     * If the state does not exist, falls back to the default state.
-     * @param state State name or null for default.
-     */
-    set state(state: string | null);
-    /**
-     * Gets the current state (animation segment) of the icon.
-     * @returns State name or null if not set.
-     */
-    get state(): string | null;
-    /**
-     * Sets the playback speed of the animation.
-     * @param speed Playback speed (1 = normal).
-     */
-    set speed(speed: number);
-    /**
-     * Gets the current playback speed.
-     * @returns Playback speed.
-     */
-    get speed(): number;
-    /**
-     * Sets the playback direction.
-     * @param direction 1 for forward, -1 for reverse.
-     */
-    set direction(direction: PlaybackDirection_2);
-    /**
-     * Gets the current playback direction.
-     * @returns Playback direction.
-     */
-    get direction(): PlaybackDirection_2;
-    /**
-     * Enables or disables looping of the animation.
-     * @param loop True to loop, false otherwise.
-     */
-    set loop(loop: boolean);
-    /**
-     * Gets whether the animation is set to loop.
-     * @returns True if looping, false otherwise.
-     */
-    get loop(): boolean;
-    /**
-     * Sets the current frame of the animation.
-     * @param frame Frame number.
-     */
-    set frame(frame: number);
-    /**
-     * Gets the current frame of the animation.
-     * @returns Current frame number.
-     */
-    get frame(): number;
-    /**
-     * Gets the list of available states for the icon.
-     * @returns Array of available states.
-     */
-    get availableStates(): IconState[];
-    /**
-     * Returns true if the animation is currently playing.
-     */
-    get playing(): boolean;
-    /**
-     * Returns true if the player is ready for interaction.
-     */
-    get ready(): boolean;
-    /**
-     * Gets the total number of frames in the animation.
-     * @returns Frame count.
-     */
-    get frameCount(): number;
-    /**
-     * Gets the current segment of the animation as [start, end] frame numbers.
-     * @returns Segment as [start, end].
-     */
-    get segment(): [number, number];
-    /**
-     * Gets the duration of the animation in seconds.
-     * @returns Duration in seconds.
-     */
-    get duration(): number;
-    /**
-     * Provides access to the underlying Lottie player instance.
-     * @returns LottieAnimationInstance.
-     */
-    get lottieInstance(): LottieAnimationInstance | undefined;
-    /**
-     * Gets all customizable properties for the icon.
-     * @returns Array of LottieProperty.
-     */
-    get lottieProperties(): LottieProperty[];
-}
-
-/**
- * Supported stroke weights for icons.
- */
-export declare type Stroke = 1 | 2 | 3 | 'light' | 'regular' | 'bold';
-
-export { }
+import { AnimationConfig } from '@lordicon/internal';
+import { ColorMap, EventHandler, EventName, IconProperties, IconState, LegacyIconProperties, LottieAnimationInstance, LottieData, LottieProperty, PlaybackDirection, Stroke } from './interfaces';
+/**
+ * LottieOptions type represents the configuration options for the Lottie player.
+ */
+export type LottieOptions = Omit<AnimationConfig, 'container'>;
+/**
+ * Player class for controlling and customizing Lottie-based icons.
+ */
+export declare class Player {
+    protected _container: HTMLElement;
+    protected _iconData: any;
+    protected _initialProperties: IconProperties & LegacyIconProperties;
+    protected _lottieInstance?: LottieAnimationInstance;
+    protected _ready: boolean;
+    protected _colorsProxy?: any;
+    protected _direction: PlaybackDirection;
+    protected _speed: number;
+    protected _lottieProperties?: LottieProperty[];
+    protected _eventHandlers: any;
+    protected _state?: IconState;
+    protected _availableStates: IconState[];
+    protected _animationFrameRate: number;
+    /**
+     * Creates a new Player instance.
+     * @param container The DOM element where the animation will be rendered.
+     * @param data Lottie animation data.
+     * @param properties Initial icon properties (colors, stroke, state, etc.).
+     * @param options Additional options (e.g., autoInit).
+     */
+    constructor(container: HTMLElement, data: LottieData, properties?: IconProperties & LegacyIconProperties, options?: {
+        autoInit?: boolean;
+    });
+    /**
+     * Initializes the player and connects it to the DOM element.
+     * Throws an error if already initialized.
+     */
+    init(): void;
+    /**
+     * Destroys the player and releases all resources.
+     * Throws an error if not initialized.
+     */
+    destroy(): void;
+    /**
+     * Registers an event listener for a player event.
+     * @param name Event name (e.g., 'complete', 'frame', 'ready').
+     * @param handler Handler function to call when the event is triggered.
+     * @returns Function to remove the listener.
+     */
+    addEventListener(name: EventName, handler: EventHandler): () => void;
+    /**
+     * Removes an event listener for a player event.
+     * @param name Event name.
+     * @param handler Handler function to remove. If not provided, removes all handlers for the event.
+     */
+    removeEventListener(name: EventName, handler?: EventHandler): void;
+    /**
+     * Triggers a player event and invokes all registered callbacks.
+     * @param name Event name.
+     * @param args Optional arguments to pass to the callbacks.
+     */
+    protected triggerEvent(name: EventName, args?: any): void;
+    /**
+     * Forces a re-render of the animation.
+     */
+    protected refresh(): void;
+    /**
+     * Starts playing the animation from the current frame.
+     * Note: If the animation is finished, it cannot be played again from the last frame.
+     */
+    play(): void;
+    /**
+     * Plays the animation from the beginning of the current state or from the start if no state is set.
+     */
+    playFromStart(): void;
+    /**
+     * Pauses the animation at the current frame.
+     */
+    pause(): void;
+    /**
+     * Stop the animation.
+     */
+    stop(): void;
+    /**
+     * Moves the animation to a specific frame and stops.
+     * @param frame Frame number to seek to.
+     */
+    seek(frame: number): void;
+    /**
+     * Moves the animation to the first frame and stops.
+     */
+    seekToStart(): void;
+    /**
+     * Moves the animation to the last frame and stops.
+     */
+    seekToEnd(): void;
+    /**
+     * Sets the animation segment to play.
+     * If no segment is provided, resets to the default segment.
+     * @param segment Optional segment as [start, end] frame numbers.
+     */
+    switchSegment(segment?: [number, number]): void;
+    /**
+     * Sets multiple icon properties at once.
+     * Any property not provided will be reset to its default value.
+     * @param properties Properties to assign.
+     */
+    set properties(properties: IconProperties);
+    /**
+     * Gets the current icon properties (colors, stroke, state).
+     * @returns The current properties.
+     */
+    get properties(): IconProperties;
+    /**
+     * Sets all customizable colors at once.
+     * Pass null to reset all colors to default.
+     * @param colors Color map or null.
+     */
+    set colors(colors: ColorMap | null);
+    /**
+     * Provides a proxy for reading or updating individual colors by name.
+     *
+     * Example:
+     *   player.colors.primary = '#ff0000';
+     *   delete player.colors.secondary;
+     */
+    get colors(): ColorMap;
+    /**
+     * Sets the stroke width for the icon.
+     * Pass null to reset to default.
+     * @param stroke Stroke value or null.
+     */
+    set stroke(stroke: Stroke | null);
+    /**
+     * Gets the current stroke width of the icon.
+     * @returns Stroke value or null if not set.
+     */
+    get stroke(): Stroke | null;
+    /**
+     * Sets the current state (animation segment) of the icon.
+     * If the state does not exist, falls back to the default state.
+     * @param state State name or null for default.
+     */
+    set state(state: string | null);
+    /**
+     * Gets the current state (animation segment) of the icon.
+     * @returns State name or null if not set.
+     */
+    get state(): string | null;
+    /**
+     * Sets the playback speed of the animation.
+     * @param speed Playback speed (1 = normal).
+     */
+    set speed(speed: number);
+    /**
+     * Gets the current playback speed.
+     * @returns Playback speed.
+     */
+    get speed(): number;
+    /**
+     * Sets the playback direction.
+     * @param direction 1 for forward, -1 for reverse.
+     */
+    set direction(direction: PlaybackDirection);
+    /**
+     * Gets the current playback direction.
+     * @returns Playback direction.
+     */
+    get direction(): PlaybackDirection;
+    /**
+     * Enables or disables looping of the animation.
+     * @param loop True to loop, false otherwise.
+     */
+    set loop(loop: boolean);
+    /**
+     * Gets whether the animation is set to loop.
+     * @returns True if looping, false otherwise.
+     */
+    get loop(): boolean;
+    /**
+     * Sets the current frame of the animation.
+     * @param frame Frame number.
+     */
+    set frame(frame: number);
+    /**
+     * Gets the current frame of the animation.
+     * @returns Current frame number.
+     */
+    get frame(): number;
+    /**
+     * Gets the list of available states for the icon.
+     * @returns Array of available states.
+     */
+    get availableStates(): IconState[];
+    /**
+     * Gets the frame rate of the animation.
+     * @returns Frame rate in frames per second.
+     */
+    get frameRate(): number;
+    /**
+     * Returns true if the animation is currently playing.
+     */
+    get playing(): boolean;
+    /**
+     * Returns true if the player is ready for interaction.
+     */
+    get ready(): boolean;
+    /**
+     * Gets the total number of frames in the animation.
+     * @returns Frame count.
+     */
+    get frameCount(): number;
+    /**
+     * Gets the current segment of the animation as [start, end] frame numbers.
+     * @returns Segment as [start, end].
+     */
+    get segment(): [number, number];
+    /**
+     * Gets the duration of the animation in seconds.
+     * @returns Duration in seconds.
+     */
+    get duration(): number;
+    /**
+     * Provides access to the underlying Lottie player instance.
+     * @returns LottieAnimationInstance.
+     */
+    get lottieInstance(): LottieAnimationInstance | undefined;
+    /**
+     * Gets all customizable properties for the icon.
+     * @returns Array of LottieProperty.
+     */
+    get lottieProperties(): LottieProperty[];
+}

package/dist/src/utils.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Deep clone value.
+ * @param value Value to clone.
+ */
+export declare function deepClone<T = any>(value: T): T;
+/**
+ * Checks if value is null or undefined.
+ * @param value Value to check.
+ * @returns True if value is null or undefined, false otherwise.
+ */
+export declare function isNil(value: any): boolean;
+/**
+ * Checks if value is object like.
+ * @param value Value to check.
+ * @returns True if value is object like, false otherwise.
+ */
+export declare function isObjectLike(value: any): value is object;
+/**
+ * Checks if path is a direct property of object.
+ * @param object Object to check.
+ * @param path Path to check.
+ */
+export declare function has<T>(object: T, path: string | string[]): boolean;
+/**
+ * Retrieves the value at the given path from the object.
+ * Returns defaultValue if the path does not exist.
+ * @param object Object to get value from.
+ * @param path Property path as a dot-separated string or array of keys.
+ * @param defaultValue Value to return if the path does not exist.
+ * @returns Value at the given path or defaultValue.
+ */
+export declare function get<T>(object: T, path: string | string[], defaultValue?: any): any;
+/**
+ * Update object value on path.
+ * @param object Object to update.
+ * @param path Path to the value.
+ * @param value New value to set.
+ */
+export declare function set(object: any, path: string | string[], value: any): void;