maplibre-gl-layers 0.6.0 → 0.11.0

package/dist/types.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.6.0
+ * version: 0.11.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: 481f544de02fd3e71a2ba6c28bbb7eeb98b49eff
+ * git.commit.hash: 371efb126f281333d59ec75cfe788d45f3b1482e
  */
 
 import { CustomLayerInterface } from 'maplibre-gl';
@@ -71,6 +71,28 @@ export interface SpriteImageOriginLocation {
      */
     useResolvedAnchor?: boolean;
 }
+/** Defines movement interpolation modes. */
+export type SpriteInterpolationMode = 'feedback' | 'feedforward';
+/** Easing function signature used to map interpolation progress. */
+export type EasingFunction = (progress: number) => number;
+/** Options for interpolating values. */
+export interface SpriteInterpolationOptions {
+    /** Interpolation mode; defaults to feedback. */
+    mode?: SpriteInterpolationMode;
+    /** Duration in milliseconds. */
+    durationMs: number;
+    /** Easing function mapping interpolation progress. Defaults to linear. */
+    easing?: EasingFunction;
+}
+/** Interpolation configuration for rotateDeg and offsetDeg. */
+export interface SpriteImageInterpolationOptions {
+    /** Interpolation settings for rotateDeg; null disables interpolation. */
+    rotateDeg?: SpriteInterpolationOptions | null;
+    /** Interpolation settings for offset.offsetDeg; null disables interpolation. */
+    offsetDeg?: SpriteInterpolationOptions | null;
+    /** Interpolation settings for offset.offsetMeters; null disables interpolation. */
+    offsetMeters?: SpriteInterpolationOptions | null;
+}
 /**
  * Initial attributes that define a sprite image.
  */
@@ -108,9 +130,9 @@ export interface SpriteImageDefinitionInit {
      */
     autoRotationMinDistanceMeters?: number;
     /**
-     * Optional interpolation settings for rotateDeg and offsetDeg.
+     * Optional interpolation settings.
      */
-    rotationInterpolation?: SpriteImageRotationInterpolationOptions;
+    interpolation?: SpriteImageInterpolationOptions;
 }
 /**
  * Update payload for a sprite image. Properties left undefined are ignored.
@@ -134,8 +156,8 @@ export interface SpriteImageDefinitionUpdate {
     autoRotation?: boolean;
     /** Minimum distance in meters before auto-rotation updates. */
     autoRotationMinDistanceMeters?: number;
-    /** Optional interpolation settings applied to rotateDeg and offsetDeg. */
-    rotationInterpolation?: SpriteImageRotationInterpolationOptions;
+    /** Optional interpolation settings. */
+    interpolation?: SpriteImageInterpolationOptions;
 }
 /**
  * Helper for bulk initializing sprite images.
@@ -255,40 +277,13 @@ export interface SpriteCurrentState<TTag> {
     /** Optional tag value; null indicates no tag. */
     readonly tag: TTag | null;
 }
-/** Defines movement interpolation modes. */
-export type SpriteInterpolationMode = 'feedback' | 'feedforward';
-/** Easing function signature used to map interpolation progress. */
-export type EasingFunction = (progress: number) => number;
-/** Options controlling position interpolation. */
-export interface SpriteInterpolationOptions {
-    /** Interpolation mode; defaults to feedback. */
-    mode?: SpriteInterpolationMode;
-    /** Duration in milliseconds. */
-    durationMs: number;
-    /** Easing function mapping interpolation progress. Defaults to linear. */
-    easing?: EasingFunction;
-}
-/** Options for interpolating numeric values such as angles. */
-export interface SpriteNumericInterpolationOptions {
-    /** Duration in milliseconds. */
-    durationMs: number;
-    /** Easing function mapping interpolation progress. Defaults to linear. */
-    easing?: EasingFunction;
-}
-/** Interpolation configuration for rotateDeg and offsetDeg. */
-export interface SpriteImageRotationInterpolationOptions {
-    /** Interpolation settings for rotateDeg; null disables interpolation. */
-    rotateDeg?: SpriteNumericInterpolationOptions | null;
-    /** Interpolation settings for offset.offsetDeg; null disables interpolation. */
-    offsetDeg?: SpriteNumericInterpolationOptions | null;
-}
 /**
  * Base structure for sprite updates.
  *
  * @template TTag Tag type stored on the sprite.
  * @property {boolean | undefined} isEnabled - Optional toggle to enable or disable the sprite.
  * @property {SpriteLocation | undefined} location - Optional target location for the sprite.
- * @property {SpriteInterpolationOptions | null | undefined} interpolation - Optional interpolation settings; `null` disables interpolation.
+ * @property {SpriteLocationInterpolationOptions | null | undefined} interpolation - Optional location interpolation settings; `null` disables interpolation.
  * @property {TTag | null | undefined} tag - Optional tag value to replace the current one; `null` clears the tag.
  */
 export interface SpriteUpdateEntryBase<TTag> {
@@ -326,11 +321,6 @@ export interface SpriteUpdateEntry<TTag> extends SpriteUpdateEntryBase<TTag> {
     /** Optional set of image updates. */
     images?: SpriteImageDefinitionUpdateEntry[];
 }
-/** @deprecated Scheduled for removal in a future release. Use {@link SpriteLayerInterface.mutateSprites} instead. */
-export interface SpriteUpdateBulkEntry<T> extends SpriteUpdateEntry<T> {
-    /** @deprecated Scheduled for removal in a future release. Use {@link SpriteLayerInterface.mutateSprites} instead. */
-    spriteId: string;
-}
 /**
  * Callback-based helper for mutating sprite state.
  *
@@ -374,7 +364,7 @@ export interface SpriteMutateCallbacks<TTag, TSourceItem extends SpriteMutateSou
      * (or `null`) to skip creation.
      *
      * @param sourceItem Source item that produced the sprite ID.
-     * @returns Sprite initialiser to insert, or `undefined`/`null` to skip.
+     * @returns Sprite initializer to insert, or `undefined`/`null` to skip.
      */
     add: (sourceItem: TSourceItem) => SpriteInit<TTag> | null | undefined;
     /**
@@ -413,24 +403,49 @@ export interface SpriteScreenPoint {
 export interface SpriteLayerClickEvent<T> {
     /** Discriminated event type. */
     readonly type: 'spriteclick';
-    /** Snapshot of the sprite that was hit. */
-    readonly sprite: SpriteCurrentState<T>;
-    /** Sprite image that received the interaction. */
-    readonly image: SpriteImageState;
+    /** Snapshot of the sprite that was hit, or `undefined` when it no longer exists. */
+    readonly sprite: SpriteCurrentState<T> | undefined;
+    /** Sprite image that received the interaction, or `undefined` when missing. */
+    readonly image: SpriteImageState | undefined;
     /** Screen position of the interaction. */
     readonly screenPoint: SpriteScreenPoint;
     /** Original DOM event. */
     readonly originalEvent: MouseEvent | PointerEvent | TouchEvent;
 }
+/**
+ * Event dispatched when a sprite is hovered by a pointing device.
+ *
+ * @template T Tag type stored on sprites.
+ * @property {'spritehover'} type - Discriminated event type.
+ * @property {SpriteCurrentState<T>} sprite - Snapshot of the sprite that was hit.
+ * @property {SpriteImageState} image - Sprite image that received the interaction.
+ * @property {SpriteScreenPoint} screenPoint - Screen position of the interaction.
+ * @property {MouseEvent | PointerEvent} originalEvent - Original hover-capable DOM event.
+ */
+export interface SpriteLayerHoverEvent<T> {
+    /** Discriminated event type. */
+    readonly type: 'spritehover';
+    /** Snapshot of the sprite that was hit, or `undefined` when it no longer exists. */
+    readonly sprite: SpriteCurrentState<T> | undefined;
+    /** Sprite image that received the interaction, or `undefined` when missing. */
+    readonly image: SpriteImageState | undefined;
+    /** Screen position of the interaction. */
+    readonly screenPoint: SpriteScreenPoint;
+    /** Original hover-capable DOM event. */
+    readonly originalEvent: MouseEvent | PointerEvent;
+}
 /**
  * Map of events emitted by SpriteLayer.
  *
  * @template T Tag type stored on sprites.
  * @property {SpriteLayerClickEvent<T>} spriteclick - Event fired when a sprite image is clicked.
+ * @property {SpriteLayerHoverEvent<T>} spritehover - Event fired when a sprite image is hovered.
  */
 export interface SpriteLayerEventMap<T> {
     /** Event fired when a sprite image is clicked. */
     readonly spriteclick: SpriteLayerClickEvent<T>;
+    /** Event fired when a sprite image is hovered. */
+    readonly spritehover: SpriteLayerHoverEvent<T>;
 }
 /**
  * Event listener callback.
@@ -471,16 +486,6 @@ export interface SpriteScalingOptions {
     /** 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;
 /**
  * Allowed minification filters for sprite textures.
  */
@@ -503,14 +508,6 @@ export interface SpriteTextureFilteringOptions {
     generateMipmaps?: boolean;
     maxAnisotropy?: number;
 }
-/**
- * Defaulted text filtering options.
- */
-export declare const DEFAULT_TEXTURE_FILTERING_OPTIONS: SpriteTextureFilteringOptions;
-/**
- * Better text filtering options than default options.
- */
-export declare const BETTER_TEXTURE_FILTERING_OPTIONS: SpriteTextureFilteringOptions;
 /**
  * Options accepted when creating a SpriteLayer.
  *
@@ -525,6 +522,38 @@ export interface SpriteLayerOptions {
     spriteScaling?: SpriteScalingOptions;
     /** Optional texture filtering configuration. */
     textureFiltering?: SpriteTextureFilteringOptions;
+    /**
+     * When true, renders red outlines around sprite hit-test regions to aid debugging.
+     * Defaults to false.
+     */
+    showDebugBounds?: boolean;
+}
+/**
+ * Options used when registering SVG images.
+ */
+export interface SpriteImageSvgOptions {
+    /** Treat the resource as SVG even when the MIME type is missing or incorrect. */
+    readonly assumeSvg?: boolean;
+    /** Enables parsing of the SVG markup to detect intrinsic sizing. Defaults to true for SVG images. */
+    readonly inspectSize?: boolean;
+    /**
+     * Uses the SVG viewBox dimensions as the raster size when width/height attributes are missing.
+     * When disabled (default), such SVGs fail to load instead of inferring a size.
+     */
+    readonly useViewBoxDimensions?: boolean;
+}
+/**
+ * Options accepted by {@link SpriteLayerInterface.registerImage}.
+ */
+export interface SpriteImageRegisterOptions {
+    /** Target width in CSS pixels. When only one dimension is supplied, the aspect ratio is preserved if known. */
+    readonly width?: number;
+    /** Target height in CSS pixels. When only one dimension is supplied, the aspect ratio is preserved if known. */
+    readonly height?: number;
+    /** Resampling quality used during rasterization. */
+    readonly resizeQuality?: ResizeQuality;
+    /** SVG-specific configuration. */
+    readonly svg?: SpriteImageSvgOptions;
 }
 /** Horizontal alignment options for text glyphs. */
 export type SpriteTextGlyphHorizontalAlign = 'left' | 'center' | 'right';
@@ -605,9 +634,10 @@ export interface SpriteLayerInterface<TTag = any> extends CustomLayerInterface {
      *
      * @param {string} imageId - Unique image identifier.
      * @param {string | ImageBitmap} image - Image source (URL or ImageBitmap) to upload.
+     * @param {SpriteImageRegisterOptions | undefined} options - Optional SVG handling controls.
      * @returns {Promise<boolean>} Resolves to `true` when the image was registered; `false` if the ID already existed.
      */
-    readonly registerImage: (imageId: string, image: string | ImageBitmap) => Promise<boolean>;
+    readonly registerImage: (imageId: string, image: string | ImageBitmap, options?: SpriteImageRegisterOptions) => Promise<boolean>;
     /**
      * Registers a text glyph texture for later use.
      *
@@ -679,6 +709,12 @@ export interface SpriteLayerInterface<TTag = any> extends CustomLayerInterface {
      * @returns {SpriteCurrentState<TTag> | undefined} Current state or `undefined` when not found.
      */
     readonly getSpriteState: (spriteId: string) => SpriteCurrentState<TTag> | undefined;
+    /**
+     * Enables or disables hit-test maintenance (quad-tree updates).
+     *
+     * @param {boolean} enabled - When false, hit testing is skipped and the internal data structure is cleared.
+     */
+    readonly setHitTestEnabled: (enabled: boolean) => void;
     /**
      * Attaches an image definition to a sprite.
      *
@@ -723,17 +759,13 @@ export interface SpriteLayerInterface<TTag = any> extends CustomLayerInterface {
      * @returns {boolean} `true` when the sprite was found and updated.
      */
     readonly updateSprite: (spriteId: string, update: SpriteUpdateEntry<TTag>) => boolean;
-    /**
-     * @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'`.
+     * initializer 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;
     /**

package/dist/utils.d.ts

@@ -1,16 +1,32 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.6.0
+ * version: 0.11.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: 481f544de02fd3e71a2ba6c28bbb7eeb98b49eff
+ * git.commit.hash: 371efb126f281333d59ec75cfe788d45f3b1482e
  */
 
+import { SpriteImageRegisterOptions } from './types';
+export type SvgSizeResolutionErrorCode = 'size-missing' | 'viewbox-disabled' | 'invalid-dimensions';
+export declare class SvgSizeResolutionError extends Error implements Error {
+    readonly code: SvgSizeResolutionErrorCode;
+    constructor(message: string, code: SvgSizeResolutionErrorCode);
+}
+/**
+ * Helper that read an ImageBitmap from a blob.
+ * @param blob Target blob.
+ * @param options Optional reading options.
+ * @returns Promise resolving to the ImageBitmap.
+ * @remarks This function helps reading SVG with better manner.
+ */
+export declare const readImageBitmap: (blob: Blob, options?: SpriteImageRegisterOptions) => Promise<ImageBitmap>;
 /**
  * Helper that loads an ImageBitmap from a URL.
  * @param url Target image URL.
+ * @param options Optional loading options.
  * @returns Promise resolving to the ImageBitmap.
+ * @remarks This function helps loading SVG with better manner.
  */
-export declare const loadImageBitmap: (url: string) => Promise<ImageBitmap>;
+export declare const loadImageBitmap: (url: string, options?: SpriteImageRegisterOptions) => Promise<ImageBitmap>;

package/package.json

@@ -1,20 +1,20 @@
 {
   "git": {
     "tags": [
-      "0.6.0"
+      "0.11.0"
     ],
     "branches": [
       "main"
     ],
-    "version": "0.6.0",
+    "version": "0.11.0",
     "commit": {
-      "hash": "481f544de02fd3e71a2ba6c28bbb7eeb98b49eff",
-      "shortHash": "481f544",
-      "date": "2025-10-30T14:50:01+09:00Z",
+      "hash": "371efb126f281333d59ec75cfe788d45f3b1482e",
+      "shortHash": "371efb1",
+      "date": "2025-11-01T23:41:18+09:00Z",
       "message": "Merge branch 'develop'"
     }
   },
-  "version": "0.6.0",
+  "version": "0.11.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",

package/dist/numericInterpolation.d.ts

@@ -1,80 +0,0 @@
-/*!
- * name: maplibre-gl-layers
- * version: 0.6.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: 481f544de02fd3e71a2ba6c28bbb7eeb98b49eff
- */
-
-import { EasingFunction, SpriteNumericInterpolationOptions } from './types';
-/**
- * Runtime state tracked for numeric interpolations.
- * @property {number} durationMs - Total duration of the interpolation in milliseconds.
- * @property {EasingFunction} easing - Easing function applied to progress samples.
- * @property {number} from - Start value used for interpolation.
- * @property {number} to - Adjusted target along the shortest rotation path.
- * @property {number} finalValue - Caller-requested final value (used once interpolation completes).
- * @property {number} startTimestamp - Timestamp when interpolation began, `-1` until evaluation starts.
- */
-export interface NumericInterpolationState {
-    readonly durationMs: number;
-    readonly easing: EasingFunction;
-    readonly from: number;
-    readonly to: number;
-    readonly finalValue: number;
-    startTimestamp: number;
-}
-/**
- * Parameters required to construct a {@link NumericInterpolationState}.
- * @property {number} currentValue - Current numeric value rendered on screen.
- * @property {number} targetValue - Desired value after interpolation completes.
- * @property {SpriteNumericInterpolationOptions} options - Timing and easing configuration.
- */
-export interface CreateNumericInterpolationStateParams {
-    currentValue: number;
-    targetValue: number;
-    options: SpriteNumericInterpolationOptions;
-}
-/**
- * Result returned by {@link createNumericInterpolationState} containing state and a flag for activation.
- * @property {NumericInterpolationState} state - Resolved state object.
- * @property {boolean} requiresInterpolation - Indicates whether the caller should animate or snap.
- */
-export interface CreateNumericInterpolationStateResult {
-    readonly state: NumericInterpolationState;
-    readonly requiresInterpolation: boolean;
-}
-/**
- * Creates interpolation state describing how to move from the current value to the target value.
- * @param {CreateNumericInterpolationStateParams} params - Inputs describing the current, target, and options.
- * @returns {CreateNumericInterpolationStateResult} State data plus a flag indicating if animation is needed.
- */
-export declare const createNumericInterpolationState: (params: CreateNumericInterpolationStateParams) => CreateNumericInterpolationStateResult;
-/**
- * Parameters describing interpolation evaluation state.
- * @property {NumericInterpolationState} state - State generated via {@link createNumericInterpolationState}.
- * @property {number} timestamp - Timestamp in milliseconds used to sample the interpolation curve.
- */
-export interface EvaluateNumericInterpolationParams {
-    state: NumericInterpolationState;
-    timestamp: number;
-}
-/**
- * Result of evaluating a numeric interpolation at a specific timestamp.
- * @property {number} value - Current interpolated value (or final value after completion).
- * @property {boolean} completed - Indicates whether interpolation reached the end.
- * @property {number} effectiveStartTimestamp - Start timestamp applied during evaluation.
- */
-export interface EvaluateNumericInterpolationResult {
-    readonly value: number;
-    readonly completed: boolean;
-    readonly effectiveStartTimestamp: number;
-}
-/**
- * Evaluates a numeric interpolation against the provided timestamp.
- * @param {EvaluateNumericInterpolationParams} params - Inputs containing interpolation state and sample timestamp.
- * @returns {EvaluateNumericInterpolationResult} Current value, completion flag, and effective start time.
- */
-export declare const evaluateNumericInterpolation: (params: EvaluateNumericInterpolationParams) => EvaluateNumericInterpolationResult;