@lordicon/web 1.0.1 → 1.2.0

package/dist/interfaces.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Icon animation data in Lottie JSON format.
+ * This player is optimized for icons from [Lordicon](https://lordicon.com/).
+ */
+export type LottieData = any;
+/**
+ * Represents a single Lottie animation instance from `@lordicon/internal`.
+ * Contains the current state and methods for controlling playback.
+ */
+export 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): 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;
+};
+/**
+ * Supported property types for Lottie animations.
+ */
+export type LottiePropertyType = 'color' | 'slider' | 'point' | 'checkbox' | 'feature';
+/**
+ * Describes a property found in the animation.
+ */
+export interface LottieProperty {
+    name: string;
+    path: string;
+    type: LottiePropertyType;
+    value: any;
+}
+/**
+ * Supported stroke weights for icons.
+ */
+export type Stroke = 1 | 2 | 3 | 'light' | 'regular' | 'bold';
+/**
+ * RGB color tuple in Lottie format: [r, g, b].
+ */
+export type RgbTuple = [number, number, number];
+/**
+ * RGB color as an object.
+ */
+export interface RgbColor {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Object storing multiple named colors.
+ *
+ * Example:
+ * {
+ *     primary: 'red',
+ *     secondary: '#ff0000',
+ * }
+ */
+export interface ColorMap {
+    [key: string]: string;
+}
+/**
+ * Animation segment as a tuple: [startFrame, endFrame].
+ */
+export type FrameSegment = [number, number];
+/**
+ * Animation playback direction: 1 (forward) or -1 (backward).
+ */
+export type PlaybackDirection = 1 | -1;
+/**
+ * Supported player event names.
+ */
+export type EventName = 'ready' | 'complete' | 'frame' | 'refresh';
+/**
+ * Player event callback type.
+ */
+export type EventHandler = () => void;
+/**
+ * Properties for legacy icons.
+ */
+export interface LegacyIconProperties {
+    /**
+     * Scale for legacy icons.
+     */
+    scale?: number;
+    /**
+     * Axis x for legacy icons.
+     */
+    axisX?: number;
+    /**
+     * Axis y for legacy icons.
+     */
+    axisY?: number;
+}
+/**
+ * Properties for customizing icons.
+ *
+ * Example:
+ * {
+ *     stroke: 'bold',
+ *     colors: {
+ *         primary: 'red',
+ *     },
+ * }
+ */
+export 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 interface IconState {
+    name: string;
+    time: number;
+    duration: number;
+    params: string[];
+    default?: boolean;
+}

package/dist/lottie.d.ts

@@ -0,0 +1,48 @@
+import { LottieAnimationInstance, LottieData, LottieProperty, RgbColor, RgbTuple } from './interfaces';
+/**
+ * Converts an RGB color object to a hexadecimal color string.
+ * @param value Color object with r, g, b properties.
+ * @returns Hexadecimal color string (e.g., "#ff0000").
+ */
+export declare function rgbToHex(value: RgbColor): string;
+/**
+ * Converts a hexadecimal color string to an RGB color object.
+ * @param hex Hexadecimal color string (with or without "#").
+ * @returns RgbColor object with r, g, b properties.
+ */
+export declare function hexToRgb(hex: string): RgbColor;
+/**
+ * Converts a hexadecimal color string to an RGB tuple in the 0-1 range.
+ * @param hex Hexadecimal color string.
+ * @returns RgbTuple with values normalized to 0-1.
+ */
+export declare function hexToTupleColor(hex: string): RgbTuple;
+/**
+ * Converts an RGB tuple (0-1 range) to a hexadecimal color string.
+ * @param value RgbTuple with values in the 0-1 range.
+ * @returns Hexadecimal color string.
+ */
+export declare function tupleColorToHex(value: RgbTuple): string;
+/**
+ * Extracts all supported customizable properties from Lottie data.
+ * @param data Lottie animation data.
+ * @param options Extraction options (e.g., lottieInstance: boolean).
+ * @returns Array of LottieProperty objects describing customizable properties.
+ */
+export declare function extractLottieProperties(data: LottieData, { lottieInstance }?: {
+    lottieInstance?: boolean;
+}): LottieProperty[];
+/**
+ * Resets Lottie data or animation instance to default values for the given properties.
+ * @param data Lottie data or animation instance to reset.
+ * @param properties Array of properties to reset.
+ */
+export declare function resetLottieProperties(data: LottieData | LottieAnimationInstance, properties: LottieProperty[]): void;
+/**
+ * Updates Lottie data or animation instance with a new value for the given properties.
+ * Handles color, point, and other property types accordingly.
+ * @param data Lottie data or animation instance to update.
+ * @param properties Array of properties to update.
+ * @param value New value to set for each property.
+ */
+export declare function updateLottieProperties(data: LottieData | LottieAnimationInstance, properties: LottieProperty[], value: any): void;

package/dist/parsers.d.ts

@@ -0,0 +1,40 @@
+import { ColorMap } from './interfaces';
+/**
+ * Returns a hexadecimal color string for a given color name or hex code.
+ *
+ * Example:
+ * ```js
+ * parseColor('red'); // "#ff0000"
+ * parseColor('#0f0'); // "#00ff00"
+ * ```
+ *
+ * @param colorName Color name (e.g., "red") or hex string (e.g., "#ff0000" or "#0f0").
+ * @returns Hexadecimal color string in the format "#rrggbb".
+ */
+export declare function parseColor(colorName: string): string;
+/**
+ * Parses a colors attribute string into a ColorMap object.
+ *
+ * Example:
+ * ```js
+ * parseColors('primary:red,secondary:#00ff00');
+ * // Returns: { primary: '#ff0000', secondary: '#00ff00' }
+ * ```
+ *
+ * @param colors Colors defined as a comma-separated string (e.g., "primary:red,secondary:#00ff00").
+ * @returns Object mapping color names to hex strings, or undefined if input is invalid.
+ */
+export declare function parseColors(colors: any): ColorMap | undefined;
+/**
+ * Parses a stroke attribute value to a supported numeric range.
+ *
+ * @param value Stroke value as a string or number ("light", 1, "1", "regular", 2, "2", "bold", 3, "3").
+ * @returns Stroke value as 1, 2, or 3, or undefined if not valid.
+ */
+export declare function parseStroke(value: any): (1 | 2 | 3 | undefined);
+/**
+ * Parse state attribute.
+ * @param value State value.
+ * @returns Returns the state as a string if valid, otherwise undefined.
+ */
+export declare function parseState(value: any): (string | undefined);

package/dist/player.d.ts

@@ -0,0 +1,233 @@
+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/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;

package/examples/03-states.html

@@ -14,7 +14,9 @@
 
     <div>
         <label for="state-select">Choose state:</label>
-        <select id="state-select"></select>
+        <select id="state-select">
+            <option value="*">*</option>
+        </select>
     </div>
 </body>
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lordicon/web",
-    "version": "1.0.1",
+    "version": "1.2.0",
     "description": "A lightweight and flexible player for seamlessly embedding, controlling, and customizing animated Lordicon icons in any web application.",
     "repository": "https://github.com/lordicondev/player-web",
     "homepage": "https://lordicon.com/",
@@ -24,15 +24,15 @@
     },
     "devDependencies": {
         "@lordicon/internal": "^0.5.0",
-        "vite": "^6.2.3",
-        "vite-plugin-dts": "^4.5.4",
-        "concurrently": "^9.1.2",
-        "eslint-config-prettier": "^9.1.0",
-        "eslint": "^8.54.0",
-        "prettier": "^3.2.5",
-        "typescript": "^5.3.2",
-        "@typescript-eslint/eslint-plugin": "^6.12.0",
-        "@typescript-eslint/parser": "^6.12.0",
+        "vite": "^8.0.16",
+        "vite-plugin-dts": "^5.0.2",
+        "concurrently": "^10.0.3",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint": "^10.5.0",
+        "prettier": "^3.8.4",
+        "typescript": "^6.0.3",
+        "@typescript-eslint/eslint-plugin": "^8.61.1",
+        "@typescript-eslint/parser": "^8.61.1",
         "@types/node": "^22.13.13"
     }
 }

package/src/player.ts

@@ -184,7 +184,7 @@ export class Player {
             }
 
             // Fallback to default state if initial is invalid.
-            if (this._initialProperties.state && !this._state) {
+            if (this._initialProperties.state && !this._state && this._initialProperties.state !== '*') {
                 this._state = this._availableStates.filter(c => c.default)[0];
             }
         }
@@ -624,6 +624,8 @@ export class Player {
 
         if (isNil(state)) {
             this._state = this._availableStates.filter(c => c.default)[0];
+        } else if (state === '*') {
+            this._state = undefined;
         } else if (state) {
             this._state = this._availableStates.filter(c => c.name === state)[0];
 

package/vite.config.ts

@@ -1,11 +1,17 @@
-import { resolve } from 'path';
+import { resolve, sep } from 'path';
 import { defineConfig } from 'vite';
 import dts from 'vite-plugin-dts';
 
 export default defineConfig({
     plugins: [
         dts({
-            rollupTypes: true,
+            insertTypesEntry: true,
+            beforeWriteFile: (filePath, content) => {
+                return {
+                    filePath: filePath.replace(`${sep}dist${sep}src${sep}`, `${sep}dist${sep}`),
+                    content,
+                };
+            },
         }),
     ],
     build: {