@lordicon/utils-lottie 1.3.0 → 1.4.0

package/dist/interfaces.d.ts

@@ -1,5 +1,6 @@
 /**
- * Icon data in JSON format.
+ * Any Lottie JSON, untyped. The older functions take it; `IconData` describes the file for
+ * new code.
  */
 export type LottieData = any;
 /**

package/dist/lottie.d.ts

@@ -1,3 +1,4 @@
+import { IconData } from './icon-data';
 import { ColorMap, LottieAnimationInstance, LottieData, LottieProperty, RgbColor, RgbTuple } from './interfaces';
 /**
  * Converts an RGB color object to a hexadecimal color string.
@@ -47,12 +48,27 @@ export declare function resetLottieProperties(data: LottieData | LottieAnimation
  */
 export declare function updateLottieProperties(data: LottieData | LottieAnimationInstance, properties: LottieProperty[], value: any): void;
 /**
- * Remaps colors in Lottie data according to the provided color map.
- * @param data Lottie data to remap colors in.
- * @param colors Color map where keys are original colors in hex format and values are new colors in hex format.
- * @returns Lottie data with colors remapped according to the provided color map.
+ * The icon's own colors, by name: `{ primary: '#121331', secondary: '#08a88a' }`.
+ * @param data Lottie data.
+ */
+export declare function defaultColors(data: LottieData): ColorMap;
+/**
+ * Replaces colours in Lottie data, matched by the icon's own colours: `{ '#121331': 'red' }`.
+ * Keys and values may be any hex value or CSS colour name; ones that are not colours are
+ * skipped.
+ *
+ * Changes `data` in place and returns the same object, not a copy. To keep the original,
+ * pass a copy: `remapColors(structuredClone(data), colors)`.
  */
 export declare function remapColors(data: LottieData, colors: ColorMap): LottieData;
+/**
+ * The icon's colours to change, by name, from a map keyed by the icon's own colours:
+ * `{ '#121331': 'red' }` gives `{ primary: '#ff0000' }` for an icon whose primary is `#121331`.
+ * For the player's `colors` or the `colors` attribute.
+ */
+export declare function colorsByName(data: IconData, colors: ColorMap): ColorMap;
+/** True when the icon's stroke width can be changed: it has a `stroke` or `stroke-layers` effect. */
+export declare function hasStroke(data: IconData): boolean;
 /**
  * Recursively removes expressions from Lottie data by deleting "x" properties that contain expressions.
  * @param data Lottie data to remove expressions from.

package/dist/parsers.d.ts

@@ -1,40 +1,43 @@
 import { ColorMap } from './interfaces.js';
 /**
- * Returns a hexadecimal color string for a given color name or hex code.
+ * A `#rrggbb` colour for a hex value or a CSS colour name, and black for anything else.
+ * @deprecated Use `resolveColor()`, which says when a value is not a colour.
+ */
+export declare function parseColor(colorName: string): string;
+/**
+ * A `#rrggbb` color for a hex value (`#0f0` or `#00ff00`) or a CSS color name. Null when the
+ * value is neither, where `parseColor()` would give black.
+ */
+export declare function resolveColor(value: string): string | null;
+/**
+ * Parses a `colors` attribute into a colour map. Names are lower-cased, colours come out as
+ * `#rrggbb`, and a pair whose colour is not a colour is left out.
  *
- * Example:
  * ```js
- * parseColor('red'); // "#ff0000"
- * parseColor('#0f0'); // "#00ff00"
+ * parseColors('primary:red, secondary:#0f0'); // { primary: '#ff0000', secondary: '#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;
+export declare function parseColors(colors: string): ColorMap | undefined;
 /**
- * Parses a colors attribute string into a ColorMap object.
+ * Writes a colour map the way `parseColors()` reads it, with every colour as `#rrggbb`.
+ * Colours that are not colours are left out.
  *
- * Example:
  * ```js
- * parseColors('primary:red,secondary:#00ff00');
- * // Returns: { primary: '#ff0000', secondary: '#00ff00' }
+ * formatColors({ primary: 'red', secondary: '#0f0' }); // '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: string): ColorMap | undefined;
+export declare function formatColors(colors: ColorMap): string;
 /**
  * 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: string | number): (1 | 2 | 3 | undefined);
+export declare function parseStroke(value: string | number): 1 | 2 | 3 | undefined;
 /**
- * Parse state attribute.
- * @param value State value.
- * @returns Returns the state as a string if valid, otherwise undefined.
+ * The name of a stroke width: 1, `'1'` and `'light'` give `'light'`. Null when the value is
+ * not a stroke width.
  */
-export declare function parseState(value: any): (string | undefined);
+export declare function strokeName(value: string | number): 'light' | 'regular' | 'bold' | null;
+/** @deprecated Returns a string as it is; nothing to parse. */
+export declare function parseState(value: any): string | undefined;

package/dist/states.d.ts

@@ -5,3 +5,34 @@ import { IconState, LottieData } from './interfaces.js';
  * @returns Array of icon states extracted from the data.
  */
 export declare function readStates(data: LottieData): IconState[];
+/** A frame range `[start, end)`. The end is exclusive, as `setSegment()` takes it. */
+export type Segment = [number, number];
+/** The frames of a state. `+ 1` keeps the state's last frame in the segment. */
+export declare function stateSegment(state: IconState): Segment;
+/**
+ * The split ratio a morph marker carries: `morph-close:0.5` gives 0.5. Null without one, or
+ * when it is not between 0 and 1 (both excluded).
+ */
+export declare function stateRatio(state: IconState): number | null;
+/**
+ * Splits a state in two at a ratio: the way to the second look, and the way back. `ratio`
+ * overrides the one in the marker. Null when neither gives one between 0 and 1, or the state
+ * is a single frame. Each half keeps at least one frame.
+ */
+export declare function splitSegment(state: IconState, ratio?: number): [Segment, Segment] | null;
+/** The state with this exact name, or the first one whose name starts with it. */
+export declare function findState(states: IconState[], name: string): IconState | null;
+/** What kind of animation a state is, from its name: `morph-select` is a `morph`. */
+export type StateType = 'in' | 'hover' | 'morph' | 'loop';
+/**
+ * The kind of a state, from the prefix of its name: `in`, `hover`, `morph` or `loop`. Takes a
+ * state or a name, with or without a `default:` flag. Null for any other prefix.
+ */
+export declare function stateType(state: IconState | string): StateType | null;
+/**
+ * The frame a state ends on: its last frame, or for a morph with a ratio the last frame of
+ * the first half, where the icon holds its second look. `ratio` overrides the marker's.
+ */
+export declare function stateEndFrame(state: IconState, ratio?: number): number;
+/** The state marked `default:`, or null. */
+export declare function defaultState(states: IconState[]): IconState | null;

package/dist/utils.d.ts

@@ -31,7 +31,7 @@ export declare function has<T>(object: T, path: string | string[]): boolean;
  */
 export declare function get<T>(object: T, path: string | string[], defaultValue?: any): any;
 /**
- * Update object value on path.
+ * Sets the value at a path. Does nothing when a step on the way is missing or not an object.
  * @param object Object to update.
  * @param path Path to the value.
  * @param value New value to set.

package/package.json

@@ -1,39 +1,58 @@
 {
     "name": "@lordicon/utils-lottie",
-    "version": "1.3.0",
+    "version": "1.4.0",
+    "description": "Utilities for Lordicon Lottie files: states, colours, stroke and customised copies of an icon.",
     "author": "Lordicon <dev@lordicon.com>",
     "homepage": "https://lordicon.com/",
     "repository": "https://github.com/lordicondev/utils-lottie",
     "license": "MIT",
     "private": false,
-    "sideEffects": false,
     "type": "module",
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
+    "sideEffects": false,
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
     "files": [
-        "dist/**/*",
-        "README.md"
+        "dist",
+        "README.md",
+        "LICENSE.md",
+        "CHANGELOG.md"
     ],
     "keywords": [
         "lordicon",
         "lottie"
     ],
+    "engines": {
+        "node": ">=20"
+    },
     "scripts": {
         "start": "vite --config vite-examples.config.ts",
         "build": "vite build",
-        "prepack": "npm run build",
-        "test": "vitest"
+        "test": "vitest run",
+        "lint": "eslint .",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "check:types": "tsc --noEmit",
+        "check": "npm run check:types && npm run lint && npm run format:check",
+        "prepack": "npm run build"
     },
-    "dependencies": {},
     "devDependencies": {
+        "@eslint/js": "^10.0.1",
         "@lordicon/internal": "^0.5.0",
-        "@types/node": "^22.9.0",
-        "typescript": "~5.6.2",
-        "vite": "^6.2.3",
-        "vite-plugin-dts": "^4.5.4",
-        "vitest": "^3.2.3"
-    },
-    "engines": {
-        "node": ">=20.0.0"
+        "@types/node": "^26.6.2",
+        "eslint": "^10.11.0",
+        "globals": "^17.12.0",
+        "prettier": "^3.9.9",
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.70.1",
+        "vite": "^8.3.0",
+        "vite-plugin-dts": "^5.1.1",
+        "vitest": "^5.0.1"
     }
-}
+}