@lordicon/web 1.0.0

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+    "singleQuote": true,
+    "trailingComma": "all",
+    "tabWidth": 4,
+    "useTabs": false
+}

package/LICENSE

@@ -0,0 +1,30 @@
+The MIT License
+
+Copyright (c) 2025 Lordicon
+
+====
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+====
+
+Files located in the node_modules directories are externally
+maintained libraries used by this software which have their own
+licenses; we recommend you read them, as their terms may differ from the
+terms above.

package/README.md

@@ -0,0 +1,148 @@
+# Lordicon Web Player
+
+A lightweight and flexible player for seamlessly embedding, controlling, and customizing animated [Lordicon](https://lordicon.com/) icons in any web application.
+
+## Features
+
+- ✨ Simple API for controlling Lottie-based icon animations
+- 📦 Supports Lordicon icon files
+- 🎨 Easy customization of colors, stroke, and animation state
+- 🔔 Event system for reacting to animation lifecycle 
+- 🛡️ TypeScript support
+
+## Installation
+
+```sh
+npm install @lordicon/web
+```
+
+## Usage
+
+> **Note:**  
+> This repository contains an `examples` directory with a rich collection of usage examples and integration scenarios.  
+> Feel free to explore it for more advanced use cases and inspiration!
+
+### Basic Example
+
+```js
+import { Player } from '@lordicon/web';
+
+const container = document.getElementById('icon');
+const data = /* Lottie JSON data */;
+
+const player = new Player(container, data, {
+    colors: {
+        primary: '#ff0000',
+        secondary: '#0000ff',
+    },
+    stroke: 2,
+    state: 'in-reveal',
+});
+
+player.play();
+```
+
+### Customizing Properties
+
+You can update properties at any time:
+
+```js
+player.colors.primary = '#00ff00';
+player.stroke = 3;
+player.state = 'hover-jump';
+```
+
+Or set multiple at once (all unspecified properties will be reset to their default values):
+
+```js
+player.properties = {
+    colors: { primary: '#123456' },
+    stroke: 1,
+    state: 'hover-jump',
+};
+```
+
+### Events
+
+Register event listeners:
+
+```js
+player.addEventListener('complete', () => {
+    console.log('Animation completed!');
+});
+```
+
+Supported events: 
+
+- `ready` – Fired when the player is initialized and ready to use.
+- `complete` – Fired when the animation finishes playing.
+- `frame` – Fired on each frame update.
+- `refresh` –  Fired when the player is refreshed, for example, after icon customization.
+
+## API
+
+Player
+
+__Constructor__
+
+```ts
+new Player(container, data, properties, options)
+```
+
+- `container` - The DOM element where the player will be rendered.
+- `data` - The animation data in Lottie JSON format. You can download it from [Lordicon](https://lordicon.com/).
+- `properties` - *(Optional)* Initial icon properties such as colors, stroke width, animation state, etc.  
+
+    Example:  
+    ```js
+    {
+        colors: { primary: '#ff0000' },
+        stroke: 2,
+        state: 'in-reveal'
+    }
+    ```
+- `options` - *(Optional)* Additional options. By default, the player is automatically initialized and ready to use immediately.
+
+    Example: 
+    ```js
+    {
+        autoInit: true
+    }
+    ```
+
+__Methods__
+
+- `init()`: Initialize the player (called automatically by default).
+- `destroy()`: Destroy the player and release resources.
+- `play()`: Play animation.
+- `playFromStart()`: Play from the beginning of the current state.
+- `pause()`: Pause animation.
+- `stop()`: Stop animation.
+- `seek(frame)`: Go to specific frame.
+- `seekToStart()`: Move to the first frame and stop.
+- `seekToEnd()`: Move to the last frame and stop.
+- `switchSegment(segment)`: Sets the animation segment to play.
+
+__Properties__
+
+- `colors`: Proxy for color manipulation (e.g., player.colors.primary = '#fff').
+- `stroke`: Stroke width (number or preset).
+- `state`: Current animation state (string).
+- `speed`: Playback speed.
+- `direction`: Playback direction (1 or -1).
+- `loop`: Looping (boolean).
+- `frame`: Current frame (number).
+- `playing`: Whether animation is playing (boolean).
+- `ready`: Whether player is ready (boolean).
+- `availableStates`: List of available states.
+- `frameCount`: Total number of frames in the animation (number).
+- `duration`: Duration of the animation in seconds (number).
+- `properties`: Get or set multiple properties at once. Setter: Any property not provided will be reset to its default value (overwrites all properties). Getter: Returns the current properties object.
+- `segment`: Gets the current segment of the animation as [start, end] frame numbers.
+- `lottieInstance`: Access to the underlying internal Lottie player instance.
+- `lottieProperties`: Array of customizable properties for the icon.
+
+__Events__
+
+- `addEventListener(name, handler)`: Register event handler. Supported event names: `'ready'`, `'complete'`, `'frame'`, `'refresh'`.
+- `removeEventListener(name, handler?)`: Remove event handler(s).

package/dist/index.d.ts

@@ -0,0 +1,388 @@
+/**
+ * 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 { }