@xweather/mapsgl 1.8.3 → 1.8.4

package/dist/mapsgl.css

@@ -1,7 +1,7 @@
 /*!
  * 
- * 	@xweather/mapsgl - 1.8.3
- * 	(c) 2025 Vaisala Xweather
+ * 	@xweather/mapsgl - 1.8.4
+ * 	(c) 2026 Vaisala Xweather
  * 	License: BSD
  * 	https://www.xweather.com
  *

package/dist/mapsgl.d.ts

@@ -1589,6 +1589,13 @@ export declare interface BarLegendOptions {
      * Whether the edges of the color scale bar should be rounded.
      */
     rounded: boolean;
+    /**
+     * Whether the color scale bar should have equal widths for each color stop. Default is `false`.
+     *
+     * When `false`, each cell will have a variable width that is proportional to its value and the next cell's value
+     * relative to the value range of the bar.
+     */
+    equalWidth: boolean;
     /**
      * Defines the base measurement type and units for the legend which corresponds to the color scale's value range.
      */
@@ -1648,6 +1655,11 @@ export declare interface BarLegendOptions {
          * The placement of the labels relative to the color scale bar.
          */
         placement: 'top' | 'middle' | 'bottom';
+        /**
+         * Whether the labels should be centered on their corresponding color scale bar cell. Default is `false`,
+         * which means the labels will be aligned to the left (beginning) of the corresponding color scale bar cell.
+         */
+        centered: boolean;
         /**
          * The marks to display at the label positions along the color scale bar.
          */
@@ -1657,6 +1669,10 @@ export declare interface BarLegendOptions {
          */
         margin: number | [number, number];
         normalized: boolean;
+        /**
+         * Whether the labels should be allowed to overlap each other. Default is `false`.
+         */
+        allowOverlap: boolean;
     }>;
 }
 
@@ -2065,20 +2081,243 @@ declare const dbzToMMRate: (dbz: number, perSecond?: boolean) => number;
 
 declare const defaultUnits: Record<Exclude<UnitSystem, 'custom'>, MapUnits>;
 
+export declare class Deferred<T> {
+    promise: Promise<T>;
+    resolve: (value: T | PromiseLike<T>) => void;
+    reject: (reason?: any) => void;
+    constructor();
+}
+
 declare const degToDir: (d: number) => string;
 
 export declare interface Disposable {
     dispose(): void;
 }
 
+/**
+ * Manages download tasks with queuing, concurrency control, retry logic, and caching.
+ * Supports per-host concurrency limits and priority-based task ordering.
+ *
+ * @template Task - The download task type that extends DownloadTask
+ */
+export declare class DownloadManager<Task extends DownloadTask<any>> extends EventDispatcher {
+
+/**
+     * Gets the progress tracker for download operations.
+     * @returns The Progress instance tracking download statistics.
+     */
+    get progress(): Progress;
+    /**
+     * Creates a new DownloadManager instance.
+     * @param options - Configuration options for the download manager.
+     * @param options.fetcher - Function that performs the fetch operation for tasks.
+     * @param options.taskRunner - Optional custom task runner function. Defaults to runDownloadTask.
+     * @param options.maxRetries - Maximum number of retry attempts for failed tasks.
+     * @param options.defaultConcurrency - Default maximum concurrent downloads. Defaults to 16.
+     * @param options.perHostConcurrency - Per-host concurrency limits, keyed by host name.
+     */
+    constructor(options?: Partial<DownloadManagerOptions<TaskData<Task>>>);
+    /**
+     * Checks if a task result exists in the cache.
+     * @param key - The unique identifier for the task.
+     * @returns True if the task result is cached, false otherwise.
+     */
+    has(key: string): boolean;
+    /**
+     * Retrieves a cached task result.
+     * @param key - The unique identifier for the task.
+     * @returns The cached task data, or undefined if not found.
+     */
+    get(key: string): TaskData<Task> | undefined;
+    /**
+     * Sets the tile fetcher function to use for requests.
+     * The fetcher function should return a Promise that resolves with a Response object.
+     * @param fetcher -
+     */
+    setFetcher(fetcher: Fetcher<Task>): void;
+    /**
+     * Sets the task runner function used to execute download tasks.
+     * @param runner - The task runner function that handles task execution with retry logic.
+     */
+    setTaskRunner(runner: TaskRunner<Task>): void;
+    /**
+     * Sets the task transformer function that modifies tasks before execution.
+     * @param transformer - Function that receives a task and returns a (possibly modified) task.
+     */
+    setTaskTransformer(transformer: (task: Task) => Task): void;
+    /**
+     * Finds all tasks that match the provided predicate function.
+     * @param predicate - A callback that receives a task and returns true if it should be included.
+     */
+    find(predicate: (task: Task) => boolean): Task[];
+    /**
+     * Finds the first task that matches the provided predicate function.
+     * @param predicate - A callback that receives a task and returns true for a match.
+     */
+    findOne(predicate: (task: Task) => boolean): Task | undefined;
+    /**
+     * Returns true if any task matches the provided predicate function.
+     * @param predicate - A callback that receives a task and returns true for a match.
+     */
+    hasTask(predicate: (task: Task) => boolean): boolean;
+    /**
+     * Adds a task to the download queue and optionally starts processing.
+     * Tasks are organized by host for per-host concurrency control and sorted by priority.
+     * @param task - The download task to enqueue.
+     * @param start - If true, immediately starts processing the queue. Defaults to true.
+     */
+    enqueue(task: Task, start?: boolean): void;
+    /**
+     * Aborts a specific download task.
+     * If the task is in-flight, the request is aborted. If pending, it's removed from the queue.
+     * Updates progress tracking accordingly.
+     * @param task - The task to abort.
+     */
+    abort(task: Task): void;
+    /**
+     * Aborts all tasks that match the provided predicate function.
+     * @param predicate - A callback that receives a task and returns true if it should be aborted.
+     */
+    abortWhere(predicate: (task: Task) => boolean): void;
+    abortAll(): void;
+
+}
+
+/**
+ * Configuration options for creating a DownloadManager instance.
+ * @template Task - The download task type that extends DownloadTask
+ */
+export declare interface DownloadManagerOptions<Task extends DownloadTask<any>> {
+    /** Function that performs the fetch operation for tasks. */
+    fetcher: Fetcher<Task>;
+    /** Optional custom task runner function. Defaults to runDownloadTask if not provided. */
+    taskRunner?: TaskRunner<Task>;
+    /** Maximum number of retry attempts for failed tasks. */
+    maxRetries?: number;
+    /** Default maximum concurrent downloads across all hosts. Defaults to 16 if not provided. */
+    defaultConcurrency?: number;
+    /** Per-host concurrency limits, keyed by host name. */
+    perHostConcurrency?: Record<string, number>;
+}
+
+/**
+ * Priority levels for download tasks. Lower numbers indicate higher priority.
+ * Tasks with lower priority values are processed before tasks with higher values.
+ */
 declare const DownloadPriority: {
+    /** Critical priority (0) - highest priority, processed first. */
     readonly critical: 0;
+    /** High priority (1) - processed after critical tasks. */
     readonly high: 1;
+    /** Warm priority (2) - lowest priority, processed last. */
     readonly warm: 2;
 };
 
+/**
+ * Type representing a download priority value.
+ */
 export declare type DownloadPriority = ObjectValue<typeof DownloadPriority>;
 
+/**
+ * Status values for download tasks throughout their lifecycle.
+ */
+declare const DownloadStatus: {
+    /** Task is queued and waiting to be processed. */
+    readonly pending: "pending";
+    /** Task is currently being executed (fetch in progress). */
+    readonly inFlight: "in-flight";
+    /** Task completed successfully. */
+    readonly success: "success";
+    /** Task failed after all retry attempts. */
+    readonly failed: "failed";
+    /** Task was cancelled before completion. */
+    readonly cancelled: "cancelled";
+};
+
+/**
+ * Type representing a download status value.
+ */
+export declare type DownloadStatus = ObjectValue<typeof DownloadStatus>;
+
+/**
+ * Represents a single download task with its configuration, state, and result handling.
+ * @template ResultType - The type of data that will be returned when the task completes.
+ */
+export declare class DownloadTask<ResultType> {
+    /** Unique identifier for this task. */
+    readonly key: string;
+    /** URL to fetch data from. */
+    readonly url: string;
+    /** Request options for the download task. */
+    readonly options: Partial<DownloadTaskRequestOptions>;
+    /** AbortController for cancelling the request. */
+    readonly controller: AbortController;
+    /** Expected result type for the response ('blob', 'json', 'arrayBuffer', or 'text'). */
+    resultType: 'blob' | 'json' | 'arrayBuffer' | 'text';
+    /** Priority level for this task. Lower numbers indicate higher priority. */
+    priority: DownloadPriority;
+    /** Current status of the download task. */
+    status: DownloadStatus;
+    /** Number of retry attempts made for this task. */
+    retries: number;
+    /** The Response object from the fetch operation, if available. */
+    response: Response | undefined;
+    /** Optional custom parser function to transform the Response into ResultType. */
+    parse: ((response: Response) => Promise<ResultType>) | undefined;
+    /** Deferred promise that resolves when the task completes. Set externally by the download scheduler. */
+    readonly deferred: Deferred<ResultType>;
+    /**
+     * Gets the promise that resolves when the task completes.
+     * @returns A Promise that resolves with the task result.
+     */
+    get promise(): Promise<ResultType>;
+    /** Optional host name for per-host concurrency control. */
+    host?: string;
+    /**
+     * Creates a new DownloadTask instance.
+     * @param key - Unique identifier for the task.
+     * @param url - URL to fetch data from.
+     * @param options - Request options for the download task.
+     * @param priority - Priority level for the task. Defaults to DownloadPriority.warm if not provided.
+     */
+    constructor(key: string, url: string, options: Partial<DownloadTaskRequestOptions>, priority?: DownloadPriority);
+    getResponseResult(response: Response | Record<string, any>): Promise<any>;
+}
+
+/**
+ * Options for configuring a download task request.
+ */
+export declare type DownloadTaskRequestOptions = {
+    /**
+     * The HTTP method to use for the request.
+     */
+    method: 'GET' | 'POST';
+    /**
+     * The authenticator to use for the request, if any.
+     */
+    authenticator?: AnyAuthenticator;
+    /**
+     * The request body to send, if any.
+     */
+    body?: any;
+    /**
+     * The request headers to send, if any.
+     */
+    headers?: Record<string, string>;
+    /**
+     * The request parameters to send, if any.
+     */
+    params: Record<string, any>;
+    /**
+     * The {@link AbortSignal} to use for the request.
+     */
+    signal: AbortSignal;
+    /**
+     * The download priority of the request.
+     */
+    priority: DownloadPriority;
+};
+
 /**
  * Set of common easing functions.
  */
@@ -2335,6 +2574,14 @@ export declare type FeatureQueryResult = {
     nodata: boolean;
 };
 
+/**
+ * Function type that performs the actual fetch operation for a download task.
+ * @template Task - The download task type that extends DownloadTask
+ * @param task - The download task to fetch data for.
+ * @returns A Promise that resolves with a Response object.
+ */
+export declare type Fetcher<Task extends DownloadTask<any>> = (task: Task) => Promise<Response>;
+
 export declare type FillPattern = string | RemoteSymbolImage;
 
 /**
@@ -2839,6 +3086,7 @@ export declare type LabelItem = {
     value: number;
     label: string;
     position?: number;
+    span?: number;
 };
 
 /**
@@ -2960,8 +3208,43 @@ export declare type LayerGroups = {
  * Layer mask configuration.
  */
 export declare type LayerMask = {
-    layer: WebGLLayer;
+    layers: Array<WebGLLayer>;
     inverted?: boolean;
+    mode?: 'all' | 'any';
+};
+
+export declare type LayerMaskConfiguration = Partial<LayerMaskSpecification> & {
+    /**
+     * The type of mask to apply to the layer. This is an alternative to using the `layers` property. If both
+     * are provided, the `layers` property will take precedence.
+     */
+    type?: 'water' | 'land';
+};
+
+/**
+ * Layer mask specification.
+ */
+export declare type LayerMaskSpecification = {
+    /**
+     * An array of layer identifiers and optional overrides to use for masking this layer's output. If the `id` is a
+     * weather layer identifier, use the `overrides` property to provide additional options for the layer and the mask
+     * layer will be created automatically. Use this in combination with the `mode` property to control how the masks
+     * are applied to the layer's final output.
+     */
+    layers: Array<{
+        id: string;
+        overrides?: Partial<WeatherLayerOptions>;
+    }>;
+    /**
+     * Whether to invert the mask, meaning the layer will be visible outside of the mask area.
+     */
+    invert?: boolean;
+    /**
+     * The mode to use applying the masks, either 'all' (default) or 'any'.
+     * - 'all': The layer will be visible only if all the masks are visible (intersection of all masks).
+     * - 'any': The layer will be visible if any of the masks are visible (union of all masks).
+     */
+    mode?: 'all' | 'any';
 };
 
 export declare type LayerMetadata = {
@@ -3104,10 +3387,10 @@ export declare interface LayerSpecification {
      */
     queryType?: ObjectValueFromKeys<typeof LayerType, 'text' | 'symbol' | 'circle'>;
     /**
-     * Layer identifier of the layer to use for masking this layer's output as a string, or an object containing the
-     * mask layer's id and an optional flag to invert the mask. The layer must have already been added to the map.
+     * Layer mask configuration to use when rendering the the layer, if any. The layer(s) used for masking must have
+     * already been added to the map.
      */
-    mask?: string | MaskLayerSpecification;
+    mask?: LayerMaskSpecification;
     /**
      * Filter expression to use for filtering features from the data source. This is only used for vector tile data
      * sources whose tiles are in the Mapbox Vector Tile (MVT) format.
@@ -4367,18 +4650,6 @@ export declare interface MapViewState {
     projectionMatrix?: Matrix4;
 }
 
-export declare type MaskConfiguration = {
-    id?: string;
-    layerId: string;
-    invert?: boolean;
-    overrides?: Record<string, any>;
-};
-
-export declare type MaskLayerSpecification = {
-    id: string;
-    invert?: boolean;
-};
-
 declare const mbToHg: (mb: number) => number;
 
 declare const mbToPa: (mb: number) => number;
@@ -4901,8 +5172,18 @@ export declare type QueryLayerConfiguration = {
     overrides?: Record<string, any>;
 };
 
+/**
+ * Query layer specification.
+ */
 export declare type QueryLayerSpecification = {
+    /**
+     * Layer identifier of the layer to use for querying/sampling data from.
+     */
     id: string;
+    /**
+     * Whether to hide the query layer. Default value is `false` which means the query layer will be visible. If you
+     * set this to `true`, then the query layer will be hidden while still being available for querying/sampling data.
+     */
     hidden?: boolean;
 };
 
@@ -5120,6 +5401,7 @@ export declare class SourceMetadata extends EventDispatcher {
     private _transformer;
     private _hasLoaded;
     private _lastRequestOptions;
+    
     /**
      * Creates an instance of SourceMetadata
      * @param url - URL to request metadata from if needed.
@@ -5167,6 +5449,7 @@ export declare class SourceMetadata extends EventDispatcher {
      * @readonly
      */
     get hasValidTimes(): boolean;
+    get validTimeRange(): TimeRange;
     getAllValidTimes(): Array<Date>;
     /**
      * Returns an array of valid times for the source. If the source has multiple datasets, the valid times
@@ -5748,6 +6031,39 @@ export declare interface SymbolStyleSpec {
     factor: StyleValue<number>;
 }
 
+/**
+ * Extracts the result type from a DownloadTask type.
+ * @template Task - The download task type that extends DownloadTask
+ * @example
+ * type MyTask = DownloadTask<string>;
+ * type MyResult = TaskData<MyTask>; // MyResult is 'string'
+ */
+export declare type TaskData<Task extends DownloadTask<any>> = Task extends DownloadTask<infer T> ? T : never;
+
+/**
+ * Function type that executes a download task with retry logic and error handling.
+ * @template Task - The download task type that extends DownloadTask
+ * @param task - The download task to execute.
+ * @param config - Configuration for the task runner.
+ * @returns A Promise that resolves when the task completes (successfully or after all retries fail).
+ */
+export declare type TaskRunner<Task extends DownloadTask<any>> = (task: Task, config: TaskRunnerConfig<Task>) => Promise<Response>;
+
+/**
+ * Configuration object for task runner execution.
+ * @template Task - The download task type that extends DownloadTask
+ */
+export declare interface TaskRunnerConfig<Task extends DownloadTask<any>> {
+    /** Function that performs the fetch operation. */
+    fetcher: Fetcher<Task>;
+    /** Maximum number of retry attempts for failed tasks. */
+    maxRetries: number;
+    /** HTTP status code range [min, max] that triggers retry attempts. */
+    retryStatusRange: [number, number];
+    /** Optional function to transform tasks before execution. */
+    taskTransformer?: (task: Task) => Task;
+}
+
 /**
  * Text style properties control how text gets rendered on a map from vector features. Use these properties on
  * conjunction with `symbol` to define the style for a text layer.
@@ -6058,14 +6374,14 @@ export declare type TileCoordinateBounds = {
     se: TileCoordinate;
 };
 
-/**
- * A function that fetches a tile from the given URL and options.
- * @param coord - The tile coordinate to load.
- * @param url - The tile URL to load.
- * @param options - The tile request options.
- * @returns A promise that resolves with the response.
- */
-export declare type TileFetcher = (coord: TileCoord, url: string, options: Partial<TileRequestOptions>) => Promise<Response>;
+export declare class TileDownloadTask extends DownloadTask<{
+    data: Blob;
+    headers: Headers;
+}> {
+    readonly coord: TileCoord;
+    readonly intervals: Array<number>;
+    constructor(key: string, coord: TileCoord, intervals: Array<number>, url: string, options: Partial<TileRequestOptions>, priority?: DownloadPriority);
+}
 
 export declare interface TileInfo {
     x: number;
@@ -6074,7 +6390,7 @@ export declare interface TileInfo {
 }
 
 export declare type TileQuadrant = 'tl' | 'tc' | 'tr' | 'ml' | 'mc' | 'mr' | 'bl' | 'bc' | 'br';
-
+
 /**
  * Options for a tile request.
  */
@@ -6121,16 +6437,6 @@ export declare type TileRequestOptions = {
     intervals: Array<Date>;
 };
 
-/**
- * A response from a tile request.
- * @property data The response data.
- * @property headers The response headers.
- */
-export declare type TileResponse = {
-    data: any;
-    headers: any;
-};
-
 /**
  * `TileSource` is an abstract class that provides the primary implementation of a tile-based data source object that
  * loads tiles from a remote source. This class is not intended to be used directly, but rather extended by a concrete
@@ -6174,20 +6480,14 @@ declare abstract class TileSource<Data = any, Source extends TileSourceSpecifica
         width: number;
         height: number;
     };
-
-/**
+    
+    /**
      * Returns the coordinate bounds for the source if provided by the source configuration.
      * When defined, data and/or tiles will not be requested outside of these bounds. This is useful for limiting the
      * amount of data requested from a source when the data is only needed for a specific region.
      * @readonly
      */
     get bounds(): CoordinateBounds;
-    get isReady(): boolean;
-    /**
-     * Returns whether or not the source is currently loading tiles.
-     * @readonly
-     */
-    get isLoading(): boolean;
 
 constructor(id: string, spec: Partial<Source>);
     /**
@@ -6255,7 +6555,10 @@ constructor(id: string, spec: Partial<Source>);
      * @returns The tile instance.
      */
     protected getOrCreateTile(coord: TileCoord): Tile<Data>;
-    protected loadTile(tile: Tile<Data>, options?: Partial<TileRequestOptions>): Promise<Data>;
+    protected loadTile(tile: Tile<Data>, options?: Partial<TileRequestOptions>): Promise<{
+        data: Blob;
+        headers: Headers;
+    }>;
     getMetadata(options?: Partial<UrlRequestOptions>): Promise<unknown>;
     removeConsumer(consumer: DataSourceConsumer): void;
     /**
@@ -6458,6 +6761,7 @@ export declare class TimeAnimation extends Animation {
     clampDateRange(min: Date, max: Date): void;
     protected eventPayload(): Record<string, any>;
     protected advanceToStopPosition(): void;
+    private _debouncedRangeChangeEvent;
 }
 
 export declare type TimeAnimationInfo = {
@@ -7009,7 +7313,7 @@ export declare interface WeatherLayerConfiguration extends Identifiable {
     /**
      * The layer mask configuration to use when rendering the the layer, if any.
      */
-    mask?: MaskConfiguration;
+    mask?: LayerMaskConfiguration;
     /**
      * The operation to perform on the data within the time series. Defaults to `none`.
      */
@@ -7147,24 +7451,7 @@ export declare type WeatherLayerOptions = {
     /**
      * Options for configuring a mask to apply to the layer.
      */
-    mask: {
-        /**
-         * The unique identifier for the mask layer. If not provided, then the value of `layerId` will be used.
-         */
-        id?: string;
-        /**
-         * Layer identifier of the layer to use for masking this layer's output.
-         */
-        layerId: string;
-        /**
-         * Whether to invert the mask, meaning the layer will be visible outside of the mask area.
-         */
-        invert?: boolean;
-        /**
-         * Additional configuration overrides for the mask layer.
-         */
-        overrides?: Record<string, any>;
-    };
+    mask: LayerMaskConfiguration;
     childLayers?: {
         [id: string]: Partial<WeatherLayerOptions>;
     };