maplibre-gl 6.3.0 → 6.4.0

package/dist/maplibre-gl.d.ts

@@ -3,7 +3,6 @@ import { GeoJSONVTOptions } from "@maplibre/geojson-vt";
 import { AllLayoutProperties, AllPaintProperties, Color, ColorArray, CompositeExpression, DiffCommand, DiffOperations, Feature, FeatureFilter, FeatureState, FilterSpecification, Formatted, FormattedSection, GeoJSONSourceSpecification, GlobalProperties, ICanonicalTileID, IMercatorCoordinate, ImageSourceSpecification, InterpolationType, LayerSpecification, LightSpecification, NumberArray, Padding, ProjectionSpecification, PromoteIdSpecification, PropertyValueSpecification, RasterDEMSourceSpecification, RasterSourceSpecification, ResolvedImage, SkySpecification, SourceExpression, SourceSpecification, SpriteSpecification, StateSpecification, StylePropertyExpression, StylePropertySpecification, StyleSpecification, TerrainSpecification, TransitionSpecification, ValidationError, VariableAnchorOffsetCollection, VectorSourceSpecification, VideoSourceSpecification, VisibilityExpression, VisibilitySpecification } from "@maplibre/maplibre-gl-style-spec";
 import { VectorTileFeatureLike, VectorTileLayerLike } from "@maplibre/vt-pbf";
 import { mat2, mat4, vec3, vec4 } from "gl-matrix";
-import { PotpackBox } from "potpack";
 import KDBush from "kdbush";
 import TinySDF from "@mapbox/tiny-sdf";
 export type * from "@maplibre/maplibre-gl-style-spec";
@@ -2313,6 +2312,117 @@ interface StyleImageInterface {
   onRemove?: () => void;
 }
 //#endregion
+//#region src/render/image_manager.d.ts
+type MissingImageRequestHandler = (id: string) => void | Promise<void>;
+type ImageManagerEventType = {
+  error: ErrorEvent;
+  styleimagemissing: MapStyleImageMissingEvent;
+};
+/**
+ * Owns every image of the style - the ones the sprites bring in as well as the ones added at
+ * runtime - and tracks requests for them from the tile workers, sending responses when the
+ * requests are fulfilled.
+ */
+declare class ImageManager extends Evented<ImageManagerEventType> {
+  images: Record<string, StyleImage>;
+  /**
+   * Incremented on every {@link ImageManager.updateImage} call. {@link ImageAtlas} instances
+   * compare it against the value they last patched against, so that a tile whose atlas is up to
+   * date can skip its patching work entirely.
+   */
+  updateVersion: number;
+  loaded: boolean;
+  /**
+   * This is used to track requests for images that are not yet available. When the image is loaded,
+   * the requestors will be notified.
+   */
+  requestors: Array<{
+    ids: string[];
+    promiseResolve: (value: GetImagesResponse | PromiseLike<GetImagesResponse>) => void;
+  }>;
+  missingImageResolver: MissingImageRequestHandler | null;
+  /**
+   * The images whose `render` callback already ran in the current frame. A given image usually
+   * sits in the atlas of several tiles, so it would otherwise be asked to re-render once per
+   * tile that holds it.
+   */
+  private _renderCallbacksDispatchedThisFrame;
+  /**
+   * The ids of the images each sprite has brought in, keyed by sprite id, so that they can be
+   * removed again when that sprite is reloaded or removed.
+   */
+  private _spriteImagesIds;
+  /** Cached result of {@link ImageManager.listImages}, invalidated whenever an image is added or removed */
+  private _imagesIds;
+  constructor();
+  destroy(): void;
+  isLoaded(): boolean;
+  setLoaded(loaded: boolean): void;
+  getImage(id: string): StyleImage;
+  addImage(id: string, image: StyleImage): void;
+  _validate(id: string, image: StyleImage): boolean;
+  _validateStretch(stretch: Array<[number, number]>, size: number): boolean;
+  _validateContent(content: [number, number, number, number], image: StyleImage): boolean;
+  /**
+   * Replaces an image that is already known under this id, bumping its version so that the
+   * atlases holding it notice.
+   *
+   * The old record is read directly rather than through {@link ImageManager.getImage}, which
+   * would force a synchronous decode of the sprite data of the very image being replaced. Its
+   * size therefore comes from whichever of the two the pixels are still in, since an image that
+   * came from a sprite and was never rendered has not been decoded yet, and its version is
+   * defaulted, since images start out without one.
+   *
+   * @param validate - whether to reject an image of a different size than the one it replaces
+   */
+  updateImage(id: string, image: StyleImage, validate?: boolean): void;
+  removeImage(id: string): void;
+  /**
+   * @returns the ids of every image currently held, sprite images and runtime ones alike. The
+   * returned array is shared between callers and must not be modified.
+   */
+  listImages(): string[];
+  /**
+   * Images of the `default` sprite keep their plain id, the ones of any other sprite are
+   * namespaced by their sprite's id.
+   */
+  private _getSpriteImageId;
+  /**
+   * Takes over the images of a single sprite: adds the new ones, updates the ones that are
+   * already known, and removes the ones that a previous load of this same sprite had brought in
+   * but that are not part of it anymore.
+   *
+   * @param spriteId - the id of the sprite the images belong to
+   * @param images - the sprite's images, keyed by their id within the sprite
+   * @returns the ids of the images that this sprite now provides, and the ids of the ones that
+   * were removed because they are no longer part of it
+   */
+  setSpriteImages(spriteId: string, images: Record<string, StyleImage>): {
+    loaded: string[];
+    removed: string[];
+  };
+  /**
+   * Removes all the images a single sprite has brought in.
+   * @returns the ids of the removed images
+   */
+  removeSpriteImages(spriteId: string): string[];
+  /**
+   * Removes the images of every sprite, leaving the images added at runtime alone.
+   * @returns the ids of the removed images
+   */
+  removeAllSpriteImages(): string[];
+  setMissingImageResolver(resolver: MissingImageRequestHandler | null): void;
+  getImages(ids: string[]): Promise<GetImagesResponse>;
+  _getImagesForIds(ids: string[]): Promise<GetImagesResponse>;
+  beginFrame(): void;
+  /**
+   * Re-renders the images among `ids` that were added with a `render` callback (see
+   * `StyleImageInterface`), at most once per frame each.
+   */
+  dispatchRenderCallbacks(ids: string[]): void;
+  cloneImages(): Record<string, StyleImage>;
+}
+//#endregion
 //#region src/webgl/texture.d.ts
 type TextureFormat = WebGLRenderingContextBase["RGBA"] | WebGLRenderingContextBase["ALPHA"];
 type TextureFilter = WebGLRenderingContextBase["LINEAR"] | WebGLRenderingContextBase["LINEAR_MIPMAP_NEAREST"] | WebGLRenderingContextBase["NEAREST"];
@@ -2357,80 +2467,6 @@ declare class Texture {
   destroy(): void;
 }
 //#endregion
-//#region src/render/image_manager.d.ts
-type MissingImageRequestHandler = (id: string) => void | Promise<void>;
-type Pattern = {
-  bin: PotpackBox;
-  position: ImagePosition;
-};
-type ImageManagerEventType = {
-  error: ErrorEvent;
-  styleimagemissing: MapStyleImageMissingEvent;
-};
-/**
- * ImageManager does three things:
- *
- * 1. Tracks requests for icon images from tile workers and sends responses when the requests are fulfilled.
- * 2. Builds a texture atlas for pattern images.
- * 3. Rerenders renderable images once per frame
- *
- * These are disparate responsibilities and should eventually be handled by different classes. When we implement
- * data-driven support for `*-pattern`, we'll likely use per-bucket pattern atlases, and that would be a good time
- * to refactor this.
- */
-declare class ImageManager extends Evented<ImageManagerEventType> {
-  images: {
-    [_: string]: StyleImage;
-  };
-  updatedImages: {
-    [_: string]: boolean;
-  };
-  callbackDispatchedThisFrame: {
-    [_: string]: boolean;
-  };
-  loaded: boolean;
-  /**
-   * This is used to track requests for images that are not yet available. When the image is loaded,
-   * the requestors will be notified.
-   */
-  requestors: Array<{
-    ids: string[];
-    promiseResolve: (value: GetImagesResponse | PromiseLike<GetImagesResponse>) => void;
-  }>;
-  missingImageResolver: MissingImageRequestHandler | null;
-  patterns: {
-    [_: string]: Pattern;
-  };
-  atlasImage: RGBAImage;
-  atlasTexture: Texture;
-  dirty: boolean;
-  constructor();
-  destroy(): void;
-  isLoaded(): boolean;
-  setLoaded(loaded: boolean): void;
-  getImage(id: string): StyleImage;
-  addImage(id: string, image: StyleImage): void;
-  _validate(id: string, image: StyleImage): boolean;
-  _validateStretch(stretch: Array<[number, number]>, size: number): boolean;
-  _validateContent(content: [number, number, number, number], image: StyleImage): boolean;
-  updateImage(id: string, image: StyleImage, validate?: boolean): void;
-  removeImage(id: string): void;
-  listImages(): string[];
-  setMissingImageResolver(resolver: MissingImageRequestHandler | null): void;
-  getImages(ids: string[]): Promise<GetImagesResponse>;
-  _getImagesForIds(ids: string[]): Promise<GetImagesResponse>;
-  getPixelSize(): {
-    width: number;
-    height: number;
-  };
-  getPattern(id: string): ImagePosition;
-  bind(context: Context): void;
-  _updatePatternAtlas(): void;
-  beginFrame(): void;
-  dispatchRenderCallbacks(ids: string[]): void;
-  cloneImages(): Record<string, StyleImage>;
-}
-//#endregion
 //#region src/style/style_glyph.d.ts
 /**
  * Some metices related to a glyph
@@ -2499,24 +2535,44 @@ declare class ImagePosition {
   get displaySize(): [number, number];
 }
 /**
- * A class holding all the images
+ * A single tile's packed copy of the icons and patterns its features reference, built in the
+ * worker so that the symbol layout can bake the positions within it straight into the vertex
+ * buffers. Each tile owns one, along with the texture it is uploaded to - as opposed to
+ * {@link ImageManager}, which owns the images of the whole style.
+ * @internal
  */
 declare class ImageAtlas {
   image: RGBAImage;
-  iconPositions: {
-    [_: string]: ImagePosition;
-  };
-  patternPositions: {
-    [_: string]: ImagePosition;
-  };
+  iconPositions: Record<string, ImagePosition>;
+  patternPositions: Record<string, ImagePosition>;
   haveRenderCallbacks: string[];
   uploaded: boolean;
+  /**
+   * The {@link ImageManager.updateVersion} this atlas' texture was last patched against.
+   * Starts out at `-1` so that a freshly transferred atlas always patches once: images may have
+   * been updated between the moment the worker snapshotted them and the moment the atlas arrives.
+   */
+  patchedUpdateVersion: number;
   constructor(icons: GetImagesResponse, patterns: GetImagesResponse);
   addImages(images: {
     [_: string]: StyleImage;
   }, positions: {
     [_: string]: ImagePosition;
   }, bins: Rect[]): void;
+  /**
+   * Brings this atlas' texture back in sync with the images it was built from, re-uploading the
+   * ones that were replaced in the meantime.
+   *
+   * This runs for every in-view tile on every frame, so the common case of nothing having
+   * changed has to cost nothing: a single comparison against {@link ImageManager.updateVersion}
+   * ends the call. When something did change, only the images this atlas actually holds are
+   * looked at - a handful per tile - and {@link ImageAtlas.patchUpdatedImage} then skips the
+   * ones whose version still matches, leaving just the genuinely stale ones to upload.
+   *
+   * The render callbacks are dispatched first because they may update images themselves, and
+   * those updates have to be part of the version this call catches up with - otherwise an
+   * animated image would always be uploaded a frame late.
+   */
   patchUpdatedImages(imageManager: ImageManager, texture: Texture): void;
   patchUpdatedImage(position: ImagePosition, image: StyleImage, texture: Texture): void;
 }
@@ -5241,7 +5297,7 @@ declare class ImageSource extends Evented<SourceEventType> implements Source {
   perspectiveTransform: RasterPerspectiveTransform;
   flippedWindingOrder: boolean;
   _loaded: boolean;
-  _request: AbortController;
+  _abortController: AbortController;
   private _imageDirty;
   /** @internal */
   constructor(id: string, options: ImageSourceSpecification | VideoSourceSpecification | CanvasSourceSpecification, dispatcher: Dispatcher, eventedParent: Evented);
@@ -6157,7 +6213,7 @@ declare class TileManager extends Evented<SourceEventType> {
   getState(): SourceFeatureState;
   pause(): void;
   resume(): void;
-  _loadTile(tile: Tile, id: string, state: TileState): Promise<void>;
+  _loadTile(tile: Tile, id: string, state: TileState, hadData: boolean): Promise<void>;
   _unloadTile(tile: Tile): void;
   _abortTile(tile: Tile): void;
   serialize(): any;
@@ -6175,7 +6231,7 @@ declare class TileManager extends Evented<SourceEventType> {
    */
   reload(sourceDataChanged?: boolean, shouldReloadTileOptions?: any): void;
   _reloadTile(id: string, state: TileState): Promise<void>;
-  _tileLoaded(tile: Tile, id: string, previousState: TileState, result: LoadTileResult): void;
+  _tileLoaded(tile: Tile, id: string, previousState: TileState, hadData: boolean, result: LoadTileResult): void;
   /**
    * Get a specific tile by TileID
    */
@@ -6343,6 +6399,34 @@ declare class TileLayerIndex {
   findMatches(symbolInstances: SymbolInstanceArray, newTileID: OverscaledTileID, zoomCrossTileIDs: {
     [crossTileID: number]: boolean;
   }): void;
+  /**
+   * Matches a symbol instance against an entry backed by a KDBush spatial index
+   * (used for keys with more than {@link KDBUSH_THRESHHOLD} symbols).
+   *
+   * Matches any symbol with the same key whose coordinates are within one grid
+   * unit (with a 4px grid, this covers a 12px by 12px area). The lowest-index
+   * unclaimed candidate is claimed in a single pass rather than sorting the
+   * whole result set on every query: `range()` can return many candidates where
+   * symbols are coincident (e.g. stacked point markers), so a per-query sort
+   * would dominate placement cost on dense layers.
+   *
+   * Once a symbol is marked duplicate against a parent symbol, no other symbol
+   * at the same zoom level may duplicate against the same parent (see issue #5993).
+   */
+  private findMatchesForIndexedEntry;
+  /**
+   * Matches a symbol instance against an entry that stores its positions as a
+   * plain array (used for keys with at most {@link KDBUSH_THRESHHOLD} symbols).
+   *
+   * Matches any symbol with the same key whose coordinates are within one grid
+   * unit (with a 4px grid, this covers a 12px by 12px area). Positions are
+   * stored in symbol-instance order, so the first unclaimed match is also the
+   * lowest-index one.
+   *
+   * Once a symbol is marked duplicate against a parent symbol, no other symbol
+   * at the same zoom level may duplicate against the same parent (see issue #5993).
+   */
+  private findMatchesForNonIndexedEntry;
   getCrossTileIDsLists(): number[][];
 }
 declare class CrossTileIDs {
@@ -7066,6 +7150,32 @@ type DrawFunctions = {
   terrainCoords: typeof drawCoords;
 };
 //#endregion
+//#region src/render/pattern_atlas.d.ts
+/**
+ * A texture atlas of the pattern images that are drawn without a tile's own {@link ImageAtlas},
+ * i.e. `background-pattern`. Entries are packed on demand and re-packed whenever one of them is
+ * added or changes, which is rare enough for the repacking cost not to matter.
+ */
+declare class PatternAtlas {
+  private _imageManager;
+  private _entries;
+  private _image;
+  private _texture;
+  private _dirty;
+  constructor(imageManager: ImageManager);
+  destroy(): void;
+  getPixelSize(): {
+    width: number;
+    height: number;
+  };
+  /**
+   * @returns the position of the pattern within the atlas, or `null` if there is no such image
+   */
+  getPattern(id: string): ImagePosition;
+  bind(context: Context): void;
+  private _update;
+}
+//#endregion
 //#region src/util/request_manager.d.ts
 /**
  * A type of MapLibre resource.
@@ -7257,6 +7367,7 @@ declare class Painter {
   options: PainterOptions;
   lineAtlas: LineAtlas;
   imageManager: ImageManager;
+  patternAtlas: PatternAtlas;
   glyphManager: GlyphManager;
   depthRangeFor3D: DepthRangeType;
   opaquePassCutoff: number;
@@ -9224,6 +9335,7 @@ declare class Style extends Evented<MapEventType> {
   stylesheet: StyleSpecification;
   dispatcher: Dispatcher;
   imageManager: ImageManager;
+  patternAtlas: PatternAtlas;
   glyphManager: GlyphManager;
   lineAtlas: LineAtlas;
   light: Light;
@@ -9263,10 +9375,6 @@ declare class Style extends Evented<MapEventType> {
     [layer: string]: true;
   };
   _layerOrderChanged: boolean;
-  _spritesImagesIds: {
-    [spriteId: string]: string[];
-  };
-  _availableImages: string[];
   _globalState: Record<string, any>;
   crossTileSymbolIndex: CrossTileSymbolIndex;
   pauseablePlacement: PauseablePlacement;
@@ -9290,7 +9398,7 @@ declare class Style extends Evented<MapEventType> {
   loadEmpty(): void;
   _load(json: StyleSpecification, options: StyleSwapOptions & StyleSetterOptions, previousStyle?: StyleSpecification): void;
   private _createLayers;
-  _loadSprite(sprite: SpriteSpecification, isUpdate?: boolean, completion?: (err: Error) => void): void;
+  _loadSprite(sprite: SpriteSpecification, isUpdate?: boolean, completion?: (err: Error) => void): Promise<void>;
   _unloadSprite(): void;
   _validateLayer(layer: StyleLayer): void;
   loaded(): boolean;
@@ -9338,6 +9446,11 @@ declare class Style extends Evented<MapEventType> {
   getImage(id: string): StyleImage;
   setMissingImageResolver(resolver: MissingImageRequestHandler | null): void;
   removeImage(id: string): void;
+  /**
+   * Queues the tiles that depend on these images to be reloaded on the next update, which is
+   * needed whenever an image appears, disappears or changes size.
+   */
+  _markImagesChanged(ids: string[]): void;
   _afterImageUpdated(id: string): void;
   listImages(): string[];
   addSource(id: string, source: SourceSpecification | CanvasSourceSpecification, options?: StyleSetterOptions): void;
@@ -10814,16 +10927,36 @@ declare class Camera extends Evented<MapEventType> {
 }
 //#endregion
 //#region src/ui/handler_inertia.d.ts
+type InertiaBufferEntry = {
+  time: number;
+  settings: HandlerResult;
+};
 declare class HandlerInertia {
   _map: Map$1;
-  _inertiaBuffer: Array<{
-    time: number;
-    settings: any;
-  }>;
+  _inertiaBuffer: InertiaBufferEntry[];
   constructor(map: Map$1);
   clear(): void;
-  record(settings: any): void;
+  record(settings: HandlerResult): void;
   _drainInertiaBuffer(): void;
+  /**
+   * Returns the entries the velocity is measured from: everything recorded within
+   * {@link VELOCITY_WINDOW} before now, but never fewer than the last two, so that
+   * inertia also works below two recorded updates per window.
+   */
+  _getVelocityEntries(): InertiaBufferEntry[];
+  /**
+   * Returns the ease which continues the gesture that has just ended.
+   *
+   * The velocity is measured over the time up to the release and not up to the last
+   * recorded movement, so that a gesture held still before being released has a lower
+   * velocity, down to no inertia at all. The delta of an entry happened before it was
+   * recorded, so the first entry only marks the start of the measured interval; anchors
+   * are the exception, as they describe the state at the moment of their entry.
+   *
+   * @param panInertiaOptions - overrides for the pan inertia defaults
+   * @returns the ease options, or `undefined` when the measured interval holds no
+   * movement, which terrain gestures produce by recording updates without any delta
+   */
   _onMoveEnd(panInertiaOptions?: DragPanOptions | boolean): EaseToOptions;
 }
 //#endregion
@@ -15317,6 +15450,10 @@ type MarkerOptions = {
   scale?: number;
   /**
    * A boolean indicating whether or not a marker is able to be dragged to a new position on the map.
+   * A draggable default marker also becomes keyboard focusable and, while focused, moves by
+   * 1 screen pixel per arrow-key press (10 with Shift), firing the same `dragstart`/`drag`/`dragend`
+   * events as pointer dragging. Markers with a custom `element` keep their focusability and
+   * keyboard behavior application-owned.
    * @defaultValue false
    */
   draggable?: boolean;
@@ -15483,12 +15620,13 @@ declare class Marker extends Evented<MarkerEventType> {
   _rotation: number;
   _pitchAlignment: Alignment;
   _rotationAlignment: Alignment;
-  _originalTabIndex: string;
   _opacity: string;
   _opacityWhenCovered: string;
   _opacityTimeout: ReturnType<typeof setTimeout>;
   _subpixelPositioning: boolean;
   _roleManaged: boolean;
+  _tabIndexManaged: boolean;
+  _keyboardDragActive: boolean;
   /**
    * @param options - the options
    */
@@ -15578,6 +15716,18 @@ declare class Marker extends Evented<MarkerEventType> {
   setSubpixelPositioning(value: boolean): this;
   _onClick: (e: MouseEvent) => void;
   _onKeyPress: (e: KeyboardEvent) => void;
+  /**
+   * Move a focused draggable default marker with the arrow keys
+   * (1 screen pixel per keydown; 10 with Shift).
+   * Mirrors the pointer drag gesture: the position updates before `dragstart`
+   * fires on the first movement, every movement fires `drag`, and releasing
+   * the arrow key (or losing focus) fires `dragend`. Holding a key down
+   * produces repeated `drag` events within a single gesture.
+   */
+  _onKeyDown: (e: KeyboardEvent) => void;
+  _onKeyUp: (e: KeyboardEvent) => void;
+  _onBlur: () => void;
+  _endKeyboardDrag(): void;
   _onMapClick: (e: MapMouseEvent) => void;
   /**
    * Returns the {@link Popup} instance that is bound to the {@link Marker}.
@@ -15662,7 +15812,10 @@ declare class Marker extends Evented<MarkerEventType> {
   _onUp: () => void;
   _addDragHandler: (e: MapMouseEvent | MapTouchEvent) => void;
   /**
-   * Sets the `draggable` property and functionality of the marker
+   * Sets the `draggable` property and functionality of the marker.
+   * A draggable default marker is also keyboard focusable and movable with the
+   * arrow keys (see {@link MarkerOptions.draggable}); custom marker elements keep
+   * their focusability and keyboard behavior application-owned.
    * @param shouldBeDraggable - Turns drag functionality on/off
    */
   setDraggable(shouldBeDraggable?: boolean): this;
@@ -15671,6 +15824,14 @@ declare class Marker extends Evented<MarkerEventType> {
    * @returns True if the marker is draggable.
    */
   isDraggable(): boolean;
+  /**
+   * Keep the marker element focusable while it has built-in keyboard behavior.
+   * A popup makes any marker element interactive; dragging only manages
+   * focusability for the default marker so custom elements stay
+   * application-owned (#7790). A tabindex supplied by the application is
+   * never added, changed, or removed here.
+   */
+  _updateTabIndex(): void;
   /**
    * Keep the default marker role aligned with interactivity.
    * Default markers need a role because `aria-label` is set in {@link Marker.addTo}.