maplibre-gl-layers 0.3.0 → 0.5.0

package/dist/interpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.3.0
+ * version: 0.5.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: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
+ * git.commit.hash: ce37eea48b788c36b4bf98cdfce83b95a85833ee
  */
 
 import { EasingFunction, SpriteInterpolationMode, SpriteInterpolationOptions, SpriteLocation } from './types';

package/dist/location.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.3.0
+ * version: 0.5.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: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
+ * git.commit.hash: ce37eea48b788c36b4bf98cdfce83b95a85833ee
  */
 
 import { SpriteLocation } from './types';

package/dist/math.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.3.0
+ * version: 0.5.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: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
+ * git.commit.hash: ce37eea48b788c36b4bf98cdfce83b95a85833ee
  */
 
 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.
@@ -101,11 +96,12 @@ export declare const calculateDistanceAndBearingMeters: (from: SpriteLocation, t
  * @param {number} effectivePixelsPerMeter - Conversion between world meters and screen pixels.
  * @param {number} spriteMinPixel - Lower pixel clamp for the sprite's largest side.
  * @param {number} spriteMaxPixel - Upper pixel clamp for the sprite's largest side.
- * @returns {{ width: number; height: number }} Pixel dimensions after scaling and clamping.
+ * @returns {{ width: number; height: number; scaleAdjustment: number }} Pixel dimensions alongside the scale factor applied during clamping.
  */
 export declare const calculateBillboardPixelDimensions: (imageWidth: number | undefined, imageHeight: number | undefined, baseMetersPerPixel: number, imageScale: number, zoomScaleFactor: number, effectivePixelsPerMeter: number, spriteMinPixel: number, spriteMaxPixel: number) => {
     width: number;
     height: number;
+    scaleAdjustment: number;
 };
 /**
  * Computes the billboard offset in screen-space pixels.
@@ -113,9 +109,10 @@ export declare const calculateBillboardPixelDimensions: (imageWidth: number | un
  * @param {number} imageScale - User-provided scale multiplier applied to the offset distance.
  * @param {number} zoomScaleFactor - Zoom-dependent scale multiplier.
  * @param {number} effectivePixelsPerMeter - Conversion factor from meters to pixels.
+ * @param {number} [sizeScaleAdjustment=1] - Additional scale factor applied when sprite size is clamped.
  * @returns {{ x: number; y: number }} Screen-space offset relative to the billboard center.
  */
-export declare const calculateBillboardOffsetPixels: (offset: SpriteImageOffset | undefined, imageScale: number, zoomScaleFactor: number, effectivePixelsPerMeter: number) => {
+export declare const calculateBillboardOffsetPixels: (offset: SpriteImageOffset | undefined, imageScale: number, zoomScaleFactor: number, effectivePixelsPerMeter: number, sizeScaleAdjustment?: number) => {
     x: number;
     y: number;
 };
@@ -138,11 +135,16 @@ export declare const calculateBillboardAnchorShiftPixels: (halfWidth: number, ha
  * @param {number} baseMetersPerPixel - World meters represented by a pixel at the current zoom.
  * @param {number} imageScale - User-provided scale multiplier.
  * @param {number} zoomScaleFactor - Zoom-dependent scale multiplier.
- * @returns {{ width: number; height: number }} Dimensions expressed as world-space meters.
+ * @returns {{ width: number; height: number; scaleAdjustment: number }} World dimensions in meters and the applied clamp scale factor.
  */
-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;
+    scaleAdjustment: number;
 };
 /**
  * Computes east/north shifts from anchor rotation on surface images.
@@ -160,9 +162,11 @@ 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.
+ * @param {number} [sizeScaleAdjustment=1] - Additional scale factor applied when sprite size is clamped.
  * @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, sizeScaleAdjustment?: number) => {
     east: number;
     north: number;
 };
@@ -399,6 +403,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 +424,9 @@ export type SurfaceCenterParams = {
     totalRotateDeg: number;
     anchor?: SpriteAnchor;
     offset?: SpriteImageOffset;
+    effectivePixelsPerMeter?: number;
+    spriteMinPixel?: number;
+    spriteMaxPixel?: number;
     project?: ProjectLngLatFn;
     projectToClipSpace?: ProjectToClipSpaceFn;
     drawingBufferWidth?: number;
@@ -429,7 +439,7 @@ export type SurfaceCenterParams = {
  * Output describing the resolved surface center and displacement details.
  * @typedef SurfaceCenterResult
  * @property {{ x: number; y: number } | null} center - Projected screen coordinates or `null` when projection fails.
- * @property {{ width: number; height: number }} worldDimensions - Sprite dimensions in world meters.
+ * @property {{ width: number; height: number; scaleAdjustment: number }} worldDimensions - Sprite dimensions in world meters.
  * @property {{ east: number; north: number }} totalDisplacement - Combined anchor and offset displacement in meters.
  * @property {SpriteLocation} displacedLngLat - Geographic coordinates after applying displacement.
  * @property {{ x: number; y: number } | null | undefined} [anchorlessCenter] - Anchorless screen coordinates when requested.
@@ -444,6 +454,7 @@ export type SurfaceCenterResult = {
     worldDimensions: {
         width: number;
         height: number;
+        scaleAdjustment: number;
     };
     totalDisplacement: {
         east: number;

package/dist/numericInterpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.3.0
+ * version: 0.5.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: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
+ * git.commit.hash: ce37eea48b788c36b4bf98cdfce83b95a85833ee
  */
 
 import { EasingFunction, SpriteNumericInterpolationOptions } from './types';

package/dist/rotationInterpolation.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.3.0
+ * version: 0.5.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: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
+ * git.commit.hash: ce37eea48b788c36b4bf98cdfce83b95a85833ee
  */
 
 import { SpriteNumericInterpolationOptions } from './types';

package/dist/types.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.3.0
+ * version: 0.5.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: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
+ * git.commit.hash: ce37eea48b788c36b4bf98cdfce83b95a85833ee
  */
 
 import { CustomLayerInterface } from 'maplibre-gl';
@@ -449,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;
@@ -463,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. */
@@ -489,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;
@@ -501,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.
@@ -510,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. */
@@ -535,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;
 }
 /**

package/dist/utils.d.ts

@@ -1,11 +1,11 @@
 /*!
  * name: maplibre-gl-layers
- * version: 0.3.0
+ * version: 0.5.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: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
+ * git.commit.hash: ce37eea48b788c36b4bf98cdfce83b95a85833ee
  */
 
 /**

package/package.json

@@ -1,20 +1,20 @@
 {
   "git": {
     "tags": [
-      "0.3.0"
+      "0.5.0"
     ],
     "branches": [
       "main"
     ],
-    "version": "0.3.0",
+    "version": "0.5.0",
     "commit": {
-      "hash": "fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06",
-      "shortHash": "fd90d1f",
-      "date": "2025-10-29T13:58:42+09:00Z",
+      "hash": "ce37eea48b788c36b4bf98cdfce83b95a85833ee",
+      "shortHash": "ce37eea",
+      "date": "2025-10-30T12:28:02+09:00Z",
       "message": "Merge branch 'develop'"
     }
   },
-  "version": "0.3.0",
+  "version": "0.5.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"