maplibre-gl-layers 0.2.0 → 0.3.0

package/dist/interpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.3.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
+ * git.commit.hash: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
  */
 
 import { EasingFunction, SpriteInterpolationMode, SpriteInterpolationOptions, SpriteLocation } from './types';

package/dist/location.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.3.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
+ * git.commit.hash: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
  */
 
 import { SpriteLocation } from './types';

package/dist/math.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.3.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
+ * git.commit.hash: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
  */
 
 import { SpriteAnchor, SpriteImageOffset, SpriteLocation, SpriteScalingOptions } from './types';

package/dist/numericInterpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.3.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
+ * git.commit.hash: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
  */
 
 import { EasingFunction, SpriteNumericInterpolationOptions } from './types';

package/dist/rotationInterpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.3.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
+ * git.commit.hash: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
  */
 
 import { SpriteNumericInterpolationOptions } from './types';

package/dist/types.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.3.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
+ * git.commit.hash: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
  */
 
 import { CustomLayerInterface } from 'maplibre-gl';
@@ -326,14 +326,9 @@ export interface SpriteUpdateEntry<TTag> extends SpriteUpdateEntryBase<TTag> {
     /** Optional set of image updates. */
     images?: SpriteImageDefinitionUpdateEntry[];
 }
-/**
- * Entry consumed by updateBulk to target a specific sprite.
- *
- * @template T Tag type stored on the sprite.
- * @property {string} spriteId - Identifier of the sprite to update.
- */
+/** @deprecated Scheduled for removal in a future release. Use {@link SpriteLayerInterface.mutateSprites} instead. */
 export interface SpriteUpdateBulkEntry<T> extends SpriteUpdateEntry<T> {
-    /** Identifier of the sprite to update. */
+    /** @deprecated Scheduled for removal in a future release. Use {@link SpriteLayerInterface.mutateSprites} instead. */
     spriteId: string;
 }
 /**
@@ -355,6 +350,44 @@ export interface SpriteUpdaterEntry<TTag> extends SpriteUpdateEntryBase<TTag> {
     /** Removes an image slot. */
     readonly removeImage: (subLayer: number, order: number) => boolean;
 }
+/**
+ * Result flags returned by `mutateSprites` callbacks.
+ * - `'notremove'`: Keep the sprite after applying any modifications.
+ * - `'remove'`: Remove the sprite from the layer.
+ */
+export type SpriteModifierResult = 'notremove' | 'remove';
+/** Source items supplied to `mutateSprites` must expose the target sprite ID. */
+export interface SpriteMutateSourceItem {
+    /** Identifier of the sprite targeted by the source item. */
+    readonly spriteId: string;
+}
+/**
+ * Callbacks invoked by `mutateSprites` for each source item.
+ *
+ * @template TTag Sprite tag type stored by the layer.
+ * @template TSourceItem Source item type that satisfies {@link SpriteMutateSourceItem}.
+ */
+export interface SpriteMutateCallbacks<TTag, TSourceItem extends SpriteMutateSourceItem> {
+    /**
+     * Invoked when the sprite ID from the source item does not yet exist.
+     * Return a populated {@link SpriteInit} when the sprite should be added; return `undefined`
+     * (or `null`) to skip creation.
+     *
+     * @param sourceItem Source item that produced the sprite ID.
+     * @returns Sprite initialiser to insert, or `undefined`/`null` to skip.
+     */
+    add: (sourceItem: TSourceItem) => SpriteInit<TTag> | null | undefined;
+    /**
+     * Invoked when the sprite ID already exists on the layer.
+     * Use `update` to mutate sprite properties or images; return `'remove'` to delete the sprite instead.
+     *
+     * @param sourceItem Source item that produced the sprite ID.
+     * @param sprite Current sprite state snapshot.
+     * @param update Helper exposing the same operations as {@link SpriteUpdaterEntry}.
+     * @returns `'remove'` to delete the sprite; otherwise `'notremove'`.
+     */
+    modify: (sourceItem: TSourceItem, sprite: SpriteCurrentState<TTag>, update: SpriteUpdaterEntry<TTag>) => SpriteModifierResult;
+}
 /**
  * Represents a point in screen space.
  *
@@ -640,12 +673,18 @@ export interface SpriteLayerInterface<TTag = any> extends CustomLayerInterface {
      */
     readonly updateSprite: (spriteId: string, update: SpriteUpdateEntry<TTag>) => boolean;
     /**
-     * Applies a batch of sprite updates.
-     *
-     * @param {SpriteUpdateBulkEntry<TTag>[]} updateBulkList - List of sprite updates.
-     * @returns {number} Number of sprites that were updated.
+     * @deprecated Use {@link SpriteLayerInterface.mutateSprites} instead for clearer mutation flows.
      */
     readonly updateBulk: (updateBulkList: SpriteUpdateBulkEntry<TTag>[]) => number;
+    /**
+     * Adds, updates, or removes sprites based on an arbitrary collection of source items.
+     *
+     * @param {readonly TSourceItem[]} sourceItems - Source items that describe desired sprite state.
+     * @param {SpriteMutateCallbacks<TTag, TSourceItem>} mutator - Callbacks responsible for creation and modification.
+     * @returns {number} Number of sprites that changed. Counts each `add` that returns a non-null
+     * initialiser and each `modify` that either invoked the updater helper or returned `'remove'`.
+     */
+    readonly mutateSprites: <TSourceItem extends SpriteMutateSourceItem>(sourceItems: readonly TSourceItem[], mutator: SpriteMutateCallbacks<TTag, TSourceItem>) => number;
     /**
      * Iterates over each sprite and allows modifications through a callback.
      *

package/dist/utils.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.3.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 4fe3389ad068a5950d4f01e01ec9d3b34c049fb2
+ * git.commit.hash: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
  */
 
 /**

package/package.json

@@ -1,20 +1,20 @@
 {
   "git": {
     "tags": [
-      "0.2.0"
+      "0.3.0"
     ],
     "branches": [
       "main"
     ],
-    "version": "0.2.0",
+    "version": "0.3.0",
     "commit": {
-      "hash": "4fe3389ad068a5950d4f01e01ec9d3b34c049fb2",
-      "shortHash": "4fe3389",
-      "date": "2025-10-28T17:25:52+09:00Z",
+      "hash": "fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06",
+      "shortHash": "fd90d1f",
+      "date": "2025-10-29T13:58:42+09:00Z",
       "message": "Merge branch 'develop'"
     }
   },
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images",
   "author": "Kouji Matsui (@kekyo@mi.kekyo.net)",
   "license": "MIT",