maplibre-gl-layers 0.2.0 → 0.4.0

package/dist/interpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.4.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: 366a9e1190bfe770b4002a06284ff627188b5c76
  */
 
 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.4.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: 366a9e1190bfe770b4002a06284ff627188b5c76
  */
 
 import { SpriteLocation } from './types';

package/dist/math.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.4.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: 366a9e1190bfe770b4002a06284ff627188b5c76
  */
 
 import { SpriteAnchor, SpriteImageOffset, SpriteLocation, SpriteScalingOptions } from './types';
@@ -30,11 +30,6 @@ export declare const RAD2DEG: number;
  * @constant
  */
 export declare const TILE_SIZE = 512;
-/**
- * Default values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
- * @constant
- */
-export declare const DEFAULT_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
 /**
  * Structure holding resolved sprite scaling options.
  * @property {number} metersPerPixel - Effective number of meters represented by each rendered pixel.
@@ -45,7 +40,7 @@ export declare const DEFAULT_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
  * @property {number} spriteMinPixel - Lower clamp for sprite size in pixels.
  * @property {number} spriteMaxPixel - Upper clamp for sprite size in pixels.
  */
-export type ResolvedSpriteScalingOptions = {
+export interface ResolvedSpriteScalingOptions {
     metersPerPixel: number;
     zoomMin: number;
     zoomMax: number;
@@ -53,7 +48,7 @@ export type ResolvedSpriteScalingOptions = {
     scaleMax: number;
     spriteMinPixel: number;
     spriteMaxPixel: number;
-};
+}
 /**
  * Fills missing {@link SpriteScalingOptions} values with defaults so downstream math can assume a complete object.
  * @param options Optional scaling configuration from the caller.
@@ -140,7 +135,11 @@ export declare const calculateBillboardAnchorShiftPixels: (halfWidth: number, ha
  * @param {number} zoomScaleFactor - Zoom-dependent scale multiplier.
  * @returns {{ width: number; height: number }} Dimensions expressed as world-space meters.
  */
-export declare const calculateSurfaceWorldDimensions: (imageWidth: number | undefined, imageHeight: number | undefined, baseMetersPerPixel: number, imageScale: number, zoomScaleFactor: number) => {
+export declare const calculateSurfaceWorldDimensions: (imageWidth: number | undefined, imageHeight: number | undefined, baseMetersPerPixel: number, imageScale: number, zoomScaleFactor: number, options?: {
+    effectivePixelsPerMeter?: number;
+    spriteMinPixel?: number;
+    spriteMaxPixel?: number;
+}) => {
     width: number;
     height: number;
 };
@@ -160,9 +159,10 @@ export declare const calculateSurfaceAnchorShiftMeters: (halfWidthMeters: number
  * Calculates surface image offsets in meters.
  * @param {SpriteImageOffset | undefined} offset - Offset configuration for the surface sprite.
  * @param {number} imageScale - User-provided scale multiplier applied to the offset distance.
+ * @param {number} zoomScaleFactor - Zoom-dependent scale multiplier.
  * @returns {{ east: number; north: number }} Offset vector in meters.
  */
-export declare const calculateSurfaceOffsetMeters: (offset: SpriteImageOffset | undefined, imageScale: number) => {
+export declare const calculateSurfaceOffsetMeters: (offset: SpriteImageOffset | undefined, imageScale: number, zoomScaleFactor: number) => {
     east: number;
     north: number;
 };
@@ -399,6 +399,9 @@ export declare const calculateBillboardCornerScreenPositions: (params: Billboard
  * @property {number} totalRotateDeg - Rotation applied to the sprite in degrees.
  * @property {SpriteAnchor} [anchor] - Anchor definition normalized between -1 and 1.
  * @property {SpriteImageOffset} [offset] - Offset definition applied in meters/deg.
+ * @property {number} [effectivePixelsPerMeter] - Conversion rate from meters to on-screen pixels.
+ * @property {number} [spriteMinPixel] - Lower clamp for the sprite's largest pixel dimension.
+ * @property {number} [spriteMaxPixel] - Upper clamp for the sprite's largest pixel dimension.
  * @property {ProjectLngLatFn} [project] - Projection function mapping longitude/latitude to screen space.
  * @property {ProjectToClipSpaceFn} [projectToClipSpace] - Projection into clip space when available.
  * @property {number} [drawingBufferWidth] - WebGL drawing buffer width in device pixels.
@@ -417,6 +420,9 @@ export type SurfaceCenterParams = {
     totalRotateDeg: number;
     anchor?: SpriteAnchor;
     offset?: SpriteImageOffset;
+    effectivePixelsPerMeter?: number;
+    spriteMinPixel?: number;
+    spriteMaxPixel?: number;
     project?: ProjectLngLatFn;
     projectToClipSpace?: ProjectToClipSpaceFn;
     drawingBufferWidth?: number;

package/dist/numericInterpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.4.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: 366a9e1190bfe770b4002a06284ff627188b5c76
  */
 
 import { EasingFunction, SpriteNumericInterpolationOptions } from './types';

package/dist/rotationInterpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.4.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: 366a9e1190bfe770b4002a06284ff627188b5c76
  */
 
 import { SpriteNumericInterpolationOptions } from './types';

package/dist/types.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.2.0
+ * version: 0.4.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: 366a9e1190bfe770b4002a06284ff627188b5c76
  */
 
 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.
  *
@@ -416,11 +449,14 @@ export type SpriteLayerEventListener<T, K extends keyof SpriteLayerEventMap<T>>
  * @property {number | undefined} zoomMax - Maximum zoom level before scaling adjustments apply.
  * @property {number | undefined} scaleMin - Lower limit for scale clamping.
  * @property {number | undefined} scaleMax - Upper limit for scale clamping.
- * @property {number | undefined} spriteMinPixel - Minimum on-screen pixel size for sprites.
- * @property {number | undefined} spriteMaxPixel - Maximum on-screen pixel size for sprites.
+ * @property {number | undefined} spriteMinPixel - Minimum on-screen pixel size for sprites (0 disables the lower clamp).
+ * @property {number | undefined} spriteMaxPixel - Maximum on-screen pixel size for sprites (0 disables the upper clamp).
  */
 export interface SpriteScalingOptions {
-    /** Overrides the baseline meters-per-pixel ratio. */
+    /**
+     * Overrides the baseline meters-per-pixel ratio.
+     * We strongly recommend specifying the default value of 1, as this value affects all calculations.
+     */
     metersPerPixel?: number;
     /** Minimum zoom level before scaling adjustments apply. */
     zoomMin?: number;
@@ -430,16 +466,26 @@ export interface SpriteScalingOptions {
     scaleMin?: number;
     /** Upper limit for scale clamping. */
     scaleMax?: number;
-    /** Minimum on-screen pixel size for sprites. */
+    /** Minimum on-screen pixel size for sprites (0 disables the lower clamp). */
     spriteMinPixel?: number;
-    /** Maximum on-screen pixel size for sprites. */
+    /** Maximum on-screen pixel size for sprites (0 disables the upper clamp). */
     spriteMaxPixel?: number;
 }
+/**
+ * Unlimited (default) values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
+ * metersPerPixel is 1.
+ */
+export declare const UNLIMITED_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
+/**
+ * Standard values that fill in missing {@link SpriteScalingOptions} fields supplied by callers.
+ * metersPerPixel is 1.
+ */
+export declare const STANDARD_SPRITE_SCALING_OPTIONS: SpriteScalingOptions;
 /**
  * Options accepted when creating a SpriteLayer.
  *
  * @property {string | undefined} id - Optional layer identifier supplied to MapLibre.
- * @property {SpriteScalingOptions | undefined} spriteScaling - Optional scaling controls.
+ * @property {SpriteScalingOptions | undefined} spriteScaling - Optional scaling controls. Default is UNLIMITED_SPRITE_SCALING_OPTIONS.
  */
 export interface SpriteLayerOptions {
     /** Optional layer identifier supplied to MapLibre. */
@@ -456,6 +502,8 @@ export type SpriteTextGlyphPaddingPixel = number | {
     bottom?: number;
     left?: number;
 };
+/** Border sides that can be rendered for a text glyph outline. */
+export type SpriteTextGlyphBorderSide = 'top' | 'right' | 'bottom' | 'left';
 /** Additional size options accepted by registerTextGlyph. */
 export type SpriteTextGlyphDimensions = {
     readonly lineHeightPixel: number;
@@ -468,7 +516,6 @@ export type SpriteTextGlyphDimensions = {
  * Text glyph appearance options.
  *
  * @property {string | undefined} fontFamily - Font family name.
- * @property {number | undefined} fontSizePixel - Font size in pixels.
  * @property {string | undefined} fontWeight - CSS font-weight value.
  * @property {'normal' | 'italic' | undefined} fontStyle - CSS font-style value.
  * @property {string | undefined} color - Text fill color.
@@ -477,15 +524,15 @@ export type SpriteTextGlyphDimensions = {
  * @property {SpriteTextGlyphPaddingPixel | undefined} paddingPixel - Padding around the glyph.
  * @property {string | undefined} borderColor - Outline color.
  * @property {number | undefined} borderWidthPixel - Outline width in pixels.
+ * @property {SpriteTextGlyphBorderSide[] | undefined} borderSides - Border sides to draw (defaults to all four).
  * @property {number | undefined} borderRadiusPixel - Border radius in pixels.
  * @property {SpriteTextGlyphHorizontalAlign | undefined} textAlign - Horizontal alignment of multiline text.
- * @property {number | undefined} renderPixelRatio - Pixel ratio used when rendering the glyph.
+ * @property {number | undefined} fontSizePixelHint - It is not specified normally. Preferred font size in pixels before dimension constraints are enforced.
+ * @property {number | undefined} renderPixelRatio - Canvas pixel ratio multiplier (defaults to 1) applied before the glyph is resampled to its logical size.
  */
 export interface SpriteTextGlyphOptions {
     /** Font family name. */
     fontFamily?: string;
-    /** Font size in pixels. */
-    fontSizePixel?: number;
     /** CSS font-weight value. */
     fontWeight?: string;
     /** CSS font-style value. */
@@ -502,11 +549,15 @@ export interface SpriteTextGlyphOptions {
     borderColor?: string;
     /** Outline width in pixels. */
     borderWidthPixel?: number;
+    /** Border sides to draw; defaults to all four sides when omitted. */
+    borderSides?: readonly SpriteTextGlyphBorderSide[];
     /** Border radius in pixels. */
     borderRadiusPixel?: number;
     /** Horizontal alignment of multiline text. */
     textAlign?: SpriteTextGlyphHorizontalAlign;
-    /** Pixel ratio used when rendering the glyph. */
+    /** It is not specified normally. Preferred font size in pixels; may shrink automatically to satisfy provided dimensions. */
+    fontSizePixelHint?: number;
+    /** Pixel ratio used when rendering the glyph; defaults to 1 and values > 1 render at higher resolution before downscaling. */
     renderPixelRatio?: number;
 }
 /**
@@ -640,12 +691,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.4.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: 366a9e1190bfe770b4002a06284ff627188b5c76
  */
 
 /**

package/package.json

@@ -1,20 +1,20 @@
 {
   "git": {
     "tags": [
-      "0.2.0"
+      "0.4.0"
     ],
     "branches": [
       "main"
     ],
-    "version": "0.2.0",
+    "version": "0.4.0",
     "commit": {
-      "hash": "4fe3389ad068a5950d4f01e01ec9d3b34c049fb2",
-      "shortHash": "4fe3389",
-      "date": "2025-10-28T17:25:52+09:00Z",
+      "hash": "366a9e1190bfe770b4002a06284ff627188b5c76",
+      "shortHash": "366a9e1",
+      "date": "2025-10-29T22:23:19+09:00Z",
       "message": "Merge branch 'develop'"
     }
   },
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -54,7 +54,7 @@
   ],
   "scripts": {
     "build": "vite build",
-    "dev": "echo \"maplibre-gl-layers does not have dev rule.\"",
+    "dev": "npm run build",
     "test": "npm run build && vitest run",
     "test:e2e": "npm run build && playwright test",
     "pack": "npm run build && screw-up pack --pack-destination ../artifacts"