leaflet-city-mapper 0.0.9 → 0.1.0

package/src/vector-style/visibleStyle.js

@@ -1,5 +1,14 @@
 import { evaluateStyle } from './evaluateStyle.js';
 
+/**
+ * Check a style layer's zoom range, visibility and feature filter.
+ *
+ * @param {Object} layer Vector style layer.
+ * @param {Object} properties Feature properties.
+ * @param {number} zoom Current zoom.
+ *
+ * @returns {boolean} Whether the layer is visible for the feature.
+ */
 export function visibleStyle(layer, properties, zoom) {
   return zoom >= (layer.minzoom ?? 0) && zoom < (layer.maxzoom ?? Infinity) &&
     layer.layout?.visibility !== 'none' &&

package/src/vector-tiles/README.md

@@ -0,0 +1,30 @@
+# Vector tiles
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Configures vector tile layers, loads and prepares tiles, and manages their
+paint, labels and lifecycle as the view changes.
+
+## Tile and label lifecycle
+
+```mermaid
+flowchart LR
+  Config["Vector source + style / sprite"] --> Needed["Select tiles for view"]
+  Needed --> Fetch["Fetch tile"]
+  Fetch --> Worker["Worker: decode + style + prepare"]
+  Worker --> Check{"Session current and not aborted?"}
+  Check -->|yes| Batches["Attach batches"]
+  Check -->|no| Drop["Discard"]
+  Batches --> Labels["Place labels using occupied cells"]
+  Labels --> Revision["Check session + revision after yielding"]
+```
+
+The public layer remains a `vector` source. Stale sessions must neither attach
+results nor decrement a new session's in-flight count. Label revisions prevent
+older placement work from replacing a newer view.
+
+- [configureVectorTileLayer.js](./configureVectorTileLayer.js): configure layer lifecycle.
+- [loadVectorTile.js](./loadVectorTile.js): fetch and attach a tile.
+- [updateVectorTileLabels.js](./updateVectorTileLabels.js): update visible labels.
+
+Related: [mvt](../mvt/README.md), [vector-style](../vector-style/README.md), [workers](../workers/README.md).

package/src/vector-tiles/appendVectorBatch.js

@@ -1,5 +1,17 @@
 import { vectorFeaturePaths } from './vectorFeaturePaths.js';
 
+/**
+ * Group feature paths by paint and style dependencies, splitting large batches.
+ *
+ * @param {Object} job Vector tile preparation job.
+ * @param {Object} layer Decoded source layer.
+ * @param {Object} entry Style layer entry.
+ * @param {Object} feature Decoded feature.
+ * @param {number} order Style layer order.
+ * @param {Map} batches Batches indexed by paint and property values.
+ * @param {Iterable<string>} dependencies Feature properties used by the style.
+ * @param {Object} paint Evaluated paint.
+ */
 export function appendVectorBatch(job, layer, entry, feature, order, batches, dependencies, paint) {
   const values = /* alloc */ [];
   let key, batch, path, count;

package/src/vector-tiles/attachVectorTileBatch.js

@@ -4,6 +4,14 @@ import { vectorStyleZoom } from './vectorStyleZoom.js';
 import { vectorTilePaint } from './vectorTilePaint.js';
 import { forwardVectorTileError } from './forwardVectorTileError.js';
 
+/**
+ * Create and attach a rendered Leaflet layer for a prepared vector batch.
+ *
+ * @param {Object} owner Vector tile layer.
+ * @param {Object} tile Tile receiving the rendered batch.
+ * @param {Object} group Leaflet group receiving the layer.
+ * @param {Object} batch Prepared vector batch.
+ */
 export function attachVectorTileBatch(owner, tile, group, batch) {
   const { pane } = vectorTileOptionsByLayer.get(owner);
   const paint = vectorTilePaint(batch, vectorStyleZoom(owner));

package/src/vector-tiles/attachVectorTileBatches.js

@@ -2,6 +2,17 @@ import { attachVectorTileBatch } from './attachVectorTileBatch.js';
 import { vectorTilesIdle } from './vectorTilesIdle.js';
 import { yieldTask } from '../utils/yieldTask.js';
 
+/**
+ * Attach vector batches incrementally while the tile session remains current.
+ *
+ * @param {Object} owner Vector tile layer.
+ * @param {Object} tile Tile receiving the batches.
+ * @param {Object} group Leaflet group receiving the layers.
+ * @param {Array} batches Prepared vector batches.
+ * @param {Object} session Session identity.
+ *
+ * @returns {Promise<boolean>} Whether every batch was attached.
+ */
 export async function attachVectorTileBatches(owner, tile, group, batches, session) {
   let batch, start = performance.now();
   for (batch of batches) {

package/src/vector-tiles/compareVectorLabelPriority.js

@@ -1,3 +1,11 @@
+/**
+ * Order vector labels by ascending priority value.
+ *
+ * @param {Object} a First label.
+ * @param {Object} b Second label.
+ *
+ * @returns {number} Relative order of the labels.
+ */
 export function compareVectorLabelPriority(a, b) {
   return a.priority - b.priority;
 }

package/src/vector-tiles/compareVectorTileDistance.js

@@ -1,3 +1,11 @@
+/**
+ * Order vector tiles by ascending distance.
+ *
+ * @param {Object} a First tile.
+ * @param {Object} b Second tile.
+ *
+ * @returns {number} Relative order of the tiles.
+ */
 export function compareVectorTileDistance(a, b) {
   return a.distance - b.distance;
 }

package/src/vector-tiles/configureVectorTileLayer.js

@@ -12,6 +12,14 @@ import { retireVectorTileGroup } from './retireVectorTileGroup.js';
 import { pumpVectorTiles } from './pumpVectorTiles.js';
 import { loadVectorTile } from './loadVectorTile.js';
 
+/**
+ * Resolve vector tile settings and install the layer's lifecycle methods.
+ *
+ * @param {Object} layer Leaflet layer to configure.
+ * @param {Object} options Vector tile source options.
+ *
+ * @returns {Promise<Object>} The configured layer.
+ */
 export async function configureVectorTileLayer(layer, options) {
   const settings = await vectorTileSettings(options);
   if (typeof settings.sprite === 'string') settings.spriteSheet = await loadVectorSprite(settings.sprite);

package/src/vector-tiles/createVectorLabel.js

@@ -2,6 +2,21 @@ import { evaluateStyle } from '../vector-style/evaluateStyle.js';
 import { projectVectorPoint } from './projectVectorPoint.js';
 import { vectorStyleValue } from './vectorStyleValue.js';
 
+/**
+ * Construct a projected vector label candidate with evaluated style properties.
+ *
+ * @param {Object} job Vector tile preparation job.
+ * @param {Object} layer Decoded source layer.
+ * @param {Object} entry Style layer entry.
+ * @param {Object} properties Feature properties.
+ * @param {number} order Style layer order.
+ * @param {string} text Label text.
+ * @param {Object} icon Sprite icon.
+ * @param {Object} anchor Label anchor and optional line endpoints.
+ * @param {number} size Text size.
+ *
+ * @returns {Object} Label candidate.
+ */
 export function createVectorLabel(job, layer, entry, properties, order, text, icon, anchor, size) {
   return /* alloc */ {
     text, latlng: projectVectorPoint(anchor.point, job.coords, layer.extent),

package/src/vector-tiles/forwardVectorTileError.js

@@ -1,5 +1,10 @@
 import { reportError } from '../scene/reportLayerError.js';
 
+/**
+ * Report a rendered vector batch error on its owning layer.
+ *
+ * @param {Object} event Error event.
+ */
 export function forwardVectorTileError({ error }) {
   reportError(this, error);
 }

package/src/vector-tiles/loadVectorSprite.js

@@ -1,3 +1,12 @@
+/**
+ * Load the sprite index and derive the corresponding image URL.
+ *
+ * @param {string} url Sprite URL without extension.
+ *
+ * @returns {Promise<Object>} Sprite image URL and index.
+ *
+ * @throws {Error} If the sprite index request returns an unsuccessful status.
+ */
 export async function loadVectorSprite(url) {
   const response = await fetch(`${url}.json`);
   if (!response.ok) throw /* alloc */ new Error(`Sprite ${url}.json: HTTP ${response.status}`);

package/src/vector-tiles/loadVectorTile.js

@@ -3,6 +3,15 @@ import { vectorTileOptionsByLayer } from '../weakmaps/vectorTileOptionsByLayer.j
 import { vectorStyleZoom } from './vectorStyleZoom.js';
 import { attachVectorTileBatches } from './attachVectorTileBatches.js';
 
+/**
+ * Fetch, prepare and attach a vector tile while its session remains current.
+ *
+ * @param {Object} tile Tile state and abort controller.
+ *
+ * @returns {Promise<void>} Completion of the load or error reporting.
+ *
+ * @throws {Error} HTTP errors are caught internally and emitted on the owning layer.
+ */
 export async function loadVectorTile(tile) {
   const { coords, controller } = tile, session = this.session;
   const { url, style, sourceId, maxZoom, maxNativeZoom } = vectorTileOptionsByLayer.get(this);

package/src/vector-tiles/onVectorTileAdd.js

@@ -10,6 +10,11 @@ import { onVectorTileWorkerError } from './onVectorTileWorkerError.js';
 import { createGeometryWorker } from '../workers/createGeometryWorker.js';
 import { vectorWorkerByLayer } from '../weakmaps/vectorWorkerByLayer.js';
 
+/**
+ * Initialize vector tile panes, worker and map listeners when the layer is added.
+ *
+ * @param {Object} map Leaflet map.
+ */
 export function onVectorTileAdd(map) {
   const { style, pane } = vectorTileOptionsByLayer.get(this);
   let index, entry;

package/src/vector-tiles/onVectorTileMessage.js

@@ -1,5 +1,10 @@
 import { revokeVectorWorkerUrl } from './revokeVectorWorkerUrl.js';
 
+/**
+ * Resolve or reject the pending vector tile job for a worker response.
+ *
+ * @param {MessageEvent} event Worker message.
+ */
 export function onVectorTileMessage({ data }) {
   revokeVectorWorkerUrl(this);
   const pending = this.waiting.get(data.id);

package/src/vector-tiles/onVectorTileRemove.js

@@ -2,6 +2,11 @@ import { vectorTileEvents } from '../globals/vectorTileEvents.js';
 import { vectorWorkerByLayer } from '../weakmaps/vectorWorkerByLayer.js';
 import { revokeVectorWorkerUrl } from './revokeVectorWorkerUrl.js';
 
+/**
+ * Remove listeners, cancel pending work and dispose rendered vector tiles and labels.
+ *
+ * @param {Object} map Leaflet map.
+ */
 export function onVectorTileRemove(map) {
   map.off(vectorTileEvents, this.refresh);
   map.off('move rotate pitch', this.rotateLabels);

package/src/vector-tiles/onVectorTileWorkerError.js

@@ -1,6 +1,11 @@
 import { reportError } from '../scene/reportLayerError.js';
 import { revokeVectorWorkerUrl } from './revokeVectorWorkerUrl.js';
 
+/**
+ * Reject pending vector jobs and report a worker error to the layer.
+ *
+ * @param {ErrorEvent} event Worker error event.
+ */
 export function onVectorTileWorkerError(event) {
   revokeVectorWorkerUrl(this);
   const error = /* alloc */ new Error(`Worker MVT: ${event.message}`);

package/src/vector-tiles/paintVectorTileBatch.js

@@ -1,5 +1,11 @@
 import { vectorTilePaint } from './vectorTilePaint.js';
 
+/**
+ * Update a rendered vector batch's paint at the given zoom.
+ *
+ * @param {Object} batch Rendered batch and its style entry.
+ * @param {number} zoom Style zoom.
+ */
 export function paintVectorTileBatch(batch, zoom) {
   const paint = vectorTilePaint(batch, zoom), { layer } = batch;
   if (batch.kind === 'line') {

package/src/vector-tiles/prepareVectorLabel.js

@@ -4,6 +4,15 @@ import { vectorLabelAnchors } from './vectorLabelAnchors.js';
 import { vectorLabelText } from './vectorLabelText.js';
 import { createVectorLabel } from './createVectorLabel.js';
 
+/**
+ * Add in-tile label candidates for a styled vector feature.
+ *
+ * @param {Object} job Vector tile preparation job.
+ * @param {Object} layer Decoded source layer.
+ * @param {Object} entry Style layer entry.
+ * @param {Object} feature Decoded feature.
+ * @param {number} order Style layer order.
+ */
 export function prepareVectorLabel(job, layer, entry, feature, order) {
   const { properties } = feature, { zoom } = job;
   const text = vectorLabelText(entry, properties, zoom);

package/src/vector-tiles/prepareVectorStyleLayer.js

@@ -5,6 +5,14 @@ import { vectorFeaturePaint } from './vectorFeaturePaint.js';
 import { vectorPaint } from '../vector-style/vectorPaint.js';
 import { appendVectorBatch } from './appendVectorBatch.js';
 
+/**
+ * Prepare labels or painted geometry batches for a vector style layer.
+ *
+ * @param {Object} job Vector tile preparation job.
+ * @param {Object} layer Decoded source layer.
+ * @param {Object} entry Style layer entry.
+ * @param {number} order Style layer order.
+ */
 export function prepareVectorStyleLayer(job, layer, entry, order) {
   const batches = /* alloc */ new Map(), dependencies = vectorStyleDependencies(entry);
   const outlineColor = entry.type === 'fill' ? entry.paint?.['fill-outline-color'] : null;

package/src/vector-tiles/prepareVectorTile.js

@@ -1,6 +1,19 @@
 import { decodeVectorTile } from '../mvt/decodeVectorTile.js';
 import { prepareVectorStyleLayer } from './prepareVectorStyleLayer.js';
 
+/**
+ * Decode a vector tile and prepare its styled geometry and label candidates.
+ *
+ * @param {ArrayBuffer} buffer Encoded vector tile.
+ * @param {Object} coords Tile coordinates.
+ * @param {Array} style Style layer entries.
+ * @param {number} zoom Style zoom.
+ * @param {string} source Optional source identifier.
+ * @param {number} maxZoom Maximum map zoom for style evaluation.
+ * @param {number} mapZoom Current map zoom.
+ *
+ * @returns {Object} Prepared batches and labels.
+ */
 export function prepareVectorTile(buffer, coords, style, zoom, source, maxZoom = 19, mapZoom = zoom) {
   const layers = decodeVectorTile(buffer), byName = /* alloc */ new Map();
   const job = /* alloc */ { coords, zoom, mapZoom, maxZoom, output: /* alloc */ [], labels: /* alloc */ [],

package/src/vector-tiles/projectVectorPaths.js

@@ -1,6 +1,16 @@
 import { projectVectorPoint } from './projectVectorPoint.js';
 import { simplifyVectorPath } from './simplifyVectorPath.js';
 
+/**
+ * Simplify and project tile geometry paths to geographic coordinates.
+ *
+ * @param {Array} geometry Tile coordinate paths.
+ * @param {Object} coords Tile coordinates.
+ * @param {number} extent Tile coordinate extent.
+ * @param {number} tolerance Simplification tolerance.
+ *
+ * @returns {Array} Projected paths.
+ */
 export function projectVectorPaths(geometry, coords, extent, tolerance) {
   const paths = /* alloc */ [];
   let path, simplified, projected, point;

package/src/vector-tiles/projectVectorPoint.js

@@ -1,3 +1,12 @@
+/**
+ * Project a vector tile point into latitude and longitude.
+ *
+ * @param {Array<number>} point Tile-local coordinates.
+ * @param {Object} coords Tile coordinates.
+ * @param {number} extent Tile coordinate extent.
+ *
+ * @returns {Array<number>} Latitude and longitude.
+ */
 export function projectVectorPoint(point, coords, extent) {
   const size = 2 ** coords.z;
   const x = (coords.x + point[0] / extent) / size;

package/src/vector-tiles/projectVectorTriangles.js

@@ -2,6 +2,16 @@ import { triangulateVectorRings } from '../mvt/triangulateVectorRings.js';
 import { projectVectorPoint } from './projectVectorPoint.js';
 import { simplifyVectorPath } from './simplifyVectorPath.js';
 
+/**
+ * Simplify polygon rings, triangulate them and project their vertices.
+ *
+ * @param {Array} geometry Tile coordinate rings.
+ * @param {Object} coords Tile coordinates.
+ * @param {number} extent Tile coordinate extent.
+ * @param {number} tolerance Simplification tolerance.
+ *
+ * @returns {Array} Projected triangle paths.
+ */
 export function projectVectorTriangles(geometry, coords, extent, tolerance) {
   const paths = /* alloc */ [], rings = /* alloc */ [];
   let triangle, projected, point, ring;

package/src/vector-tiles/pruneVectorTiles.js

@@ -1,6 +1,9 @@
 import { reportError } from '../scene/reportLayerError.js';
 import { vectorTileAwaited } from './vectorTileAwaited.js';
 
+/**
+ * Cancel unneeded vector tiles and retire groups no longer needed as fallbacks.
+ */
 export function pruneVectorTiles() {
   let tile, key;
   for ([key, tile] of this.tiles) {

package/src/vector-tiles/pumpVectorTiles.js

@@ -1,5 +1,8 @@
 import { compareVectorTileDistance } from './compareVectorTileDistance.js';
 
+/**
+ * Start pending needed tiles nearest the map center, up to the concurrency limit.
+ */
 export function pumpVectorTiles() {
   if (!this.session) return;
   const center = this._map.getCenter(), pending = /* alloc */ [];

package/src/vector-tiles/readTileJSON.js

@@ -1,3 +1,13 @@
+/**
+ * Fetch TileJSON metadata and merge its tile URL and defaults into source options.
+ *
+ * @param {Object} options Source options including the TileJSON URL.
+ *
+ * @returns {Promise<Object>} Options with resolved tile URL and metadata.
+ *
+ * @throws {Error} If the metadata request returns an unsuccessful status.
+ * @throws {Error} If the metadata lacks a tile URL template.
+ */
 export async function readTileJSON(options) {
   const url = /* alloc */ new URL(options.tileJSON, document.baseURI).href;
   const response = await fetch(url);

package/src/vector-tiles/readVectorStyle.js

@@ -1,5 +1,16 @@
 import { parseVectorStyle } from '../vector-style/parseVectorStyle.js';
 
+/**
+ * Load or extract vector style layers and validate their identifiers and types.
+ *
+ * @param {string|Object|Array} style Style URL, document or layer array.
+ *
+ * @returns {Promise<Array>} Validated style layers.
+ *
+ * @throws {Error} If the style request returns an unsuccessful status.
+ * @throws {Error} If the style does not contain a layer array.
+ * @throws {Error} If a style layer lacks a string identifier or type.
+ */
 export async function readVectorStyle(style) {
   if (typeof style === 'string') {
     const response = await fetch(style);

package/src/vector-tiles/refreshVectorTiles.js

@@ -1,3 +1,6 @@
+/**
+ * Debounce vector tile updates after map changes.
+ */
 export function refreshVectorTiles() {
   clearTimeout(this.timer);
   this.changedAt = performance.now();

package/src/vector-tiles/reserveVectorLabelCells.js

@@ -1,3 +1,11 @@
+/**
+ * Reserve label cells only if none are already occupied.
+ *
+ * @param {Iterable<string>} cells Cells required by the label.
+ * @param {Set<string>} occupied Previously occupied cells.
+ *
+ * @returns {boolean} Whether the cells were reserved.
+ */
 export function reserveVectorLabelCells(cells, occupied) {
   let cell;
   for (cell of cells) if (occupied.has(cell)) return false;

package/src/vector-tiles/retireVectorTileGroup.js

@@ -1,5 +1,12 @@
 import { yieldTask } from '../utils/yieldTask.js';
 
+/**
+ * Remove a tile group's layers incrementally while its session remains current.
+ *
+ * @param {Object} group Leaflet layer group to retire.
+ *
+ * @returns {Promise<void>} Completion of retirement.
+ */
 export async function retireVectorTileGroup(group) {
   const session = this.session;
   this.retiring.add(group);

package/src/vector-tiles/revokeVectorWorkerUrl.js

@@ -1,5 +1,10 @@
 import { vectorWorkerByLayer } from '../weakmaps/vectorWorkerByLayer.js';
 
+/**
+ * Revoke a vector worker's temporary blob URL once it is no longer needed.
+ *
+ * @param {Object} layer Owning vector tile layer.
+ */
 export function revokeVectorWorkerUrl(layer) {
   const entry = vectorWorkerByLayer.get(layer);
   if (entry?.blobUrl) {

package/src/vector-tiles/rotateVectorLabel.js

@@ -1,6 +1,13 @@
 import { radians } from '../globals/radians.js';
 import { markerSetRotation } from '../core/markerSetRotation.js';
 
+/**
+ * Rotate a line label to follow its projected segment while keeping text upright.
+ *
+ * @param {Object} map Leaflet map.
+ * @param {Object} marker Label marker.
+ * @param {Object} label Label candidate with optional line endpoints.
+ */
 export function rotateVectorLabel(map, marker, label) {
   if (!label.along) return;
   const a = map.latLngToContainerPoint(label.along[0]), b = map.latLngToContainerPoint(label.along[1]);

package/src/vector-tiles/rotateVectorLabels.js

@@ -1,5 +1,8 @@
 import { rotateVectorLabel } from './rotateVectorLabel.js';
 
+/**
+ * Update the rotation of the bound layer's line labels.
+ */
 export function rotateVectorLabels() {
   let marker;
   for (marker of this.labels.values()) if (marker._mvtLabel) rotateVectorLabel(this._map, marker, marker._mvtLabel);

package/src/vector-tiles/simplifyVectorPath.js

@@ -1,3 +1,11 @@
+/**
+ * Simplify a path with a distance tolerance while retaining its endpoints.
+ *
+ * @param {Array} path Tile-coordinate points.
+ * @param {number} tolerance Maximum retained deviation.
+ *
+ * @returns {Array} Simplified path.
+ */
 export function simplifyVectorPath(path, tolerance) {
   if (path.length < 3) return path;
   const keep = /* alloc */ new Uint8Array(path.length);

package/src/vector-tiles/updateVectorLabelMarker.js

@@ -4,6 +4,15 @@ import { vectorLabelIcon } from './vectorLabelIcon.js';
 import { rotateVectorLabel } from './rotateVectorLabel.js';
 import { forwardVectorTileError } from './forwardVectorTileError.js';
 
+/**
+ * Create or update a marker for a vector label candidate.
+ *
+ * @param {Object} owner Vector tile layer.
+ * @param {Object} label Label candidate.
+ * @param {string} key Label identity key.
+ *
+ * @returns {boolean} Whether the marker was created or its appearance changed.
+ */
 export function updateVectorLabelMarker(owner, label, key) {
   const appearance = JSON.stringify(/* alloc */ [label.size, label.color, label.halo, label.haloWidth, label.icon]);
   const sheet = vectorTileOptionsByLayer.get(owner).spriteSheet;

package/src/vector-tiles/updateVectorLabelStyle.js

@@ -1,5 +1,11 @@
 import { evaluateStyle } from '../vector-style/evaluateStyle.js';
 
+/**
+ * Evaluate the text appearance of a label at the given zoom.
+ *
+ * @param {Object} label Label candidate.
+ * @param {number} zoom Style zoom.
+ */
 export function updateVectorLabelStyle(label, zoom) {
   label.size = evaluateStyle(label.entry.layout?.['text-size'] ?? 12, label.properties, zoom);
   label.color = evaluateStyle(label.entry.paint?.['text-color'] ?? '#000', label.properties, zoom);

package/src/vector-tiles/updateVectorTileLabels.js

@@ -5,6 +5,11 @@ import { updateVectorLabelMarker } from './updateVectorLabelMarker.js';
 import { vectorTilesIdle } from './vectorTilesIdle.js';
 import { yieldTask } from '../utils/yieldTask.js';
 
+/**
+ * Place visible vector labels without overlapping occupied cells and remove stale markers.
+ *
+ * @returns {Promise<void>} Completion of the current placement revision.
+ */
 export async function updateVectorTileLabels() {
   const session = this.session, revision = this.labelRevision = (this.labelRevision || 0) + 1;
   this.labelsReady = false;

package/src/vector-tiles/updateVectorTilePaint.js

@@ -3,6 +3,11 @@ import { vectorStyleZoom } from './vectorStyleZoom.js';
 import { vectorTilesIdle } from './vectorTilesIdle.js';
 import { yieldTask } from '../utils/yieldTask.js';
 
+/**
+ * Update rendered tile paint incrementally while the zoom and session remain current.
+ *
+ * @returns {Promise<void>} Completion of the current paint revision.
+ */
 export async function updateVectorTilePaint() {
   const zoom = vectorStyleZoom(this), session = this.session;
   if (this.paintZoom === zoom) return;

package/src/vector-tiles/updateVectorTiles.js

@@ -2,6 +2,9 @@ import { vectorTileOptionsByLayer } from '../weakmaps/vectorTileOptionsByLayer.j
 import { vectorStyleZoom } from './vectorStyleZoom.js';
 import { reportError } from '../scene/reportLayerError.js';
 
+/**
+ * Update needed tiles for the map bounds, then schedule loading, paint and labels.
+ */
 export function updateVectorTiles() {
   if (!this.session) return;
   const { minNativeZoom, maxNativeZoom } = vectorTileOptionsByLayer.get(this);

package/src/vector-tiles/validateVectorTileZooms.js

@@ -1,3 +1,12 @@
+/**
+ * Validate the native and map zoom limits for a vector tile source.
+ *
+ * @param {number} minNativeZoom Minimum native zoom.
+ * @param {number} maxNativeZoom Maximum native zoom.
+ * @param {number} maxZoom Maximum map zoom.
+ *
+ * @throws {Error} If the zoom limits are noninteger, unordered or outside the supported range.
+ */
 export function validateVectorTileZooms(minNativeZoom, maxNativeZoom, maxZoom) {
   if (!Number.isInteger(minNativeZoom) || !Number.isInteger(maxNativeZoom) || !Number.isInteger(maxZoom) ||
       minNativeZoom < 0 || maxNativeZoom < minNativeZoom || maxZoom < maxNativeZoom || maxZoom > 24) {

package/src/vector-tiles/vectorFeaturePaint.js

@@ -1,6 +1,16 @@
 import { vectorPaint } from '../vector-style/vectorPaint.js';
 import { visibleStyle } from '../vector-style/visibleStyle.js';
 
+/**
+ * Find usable fill or line paint for a compatible vector feature.
+ *
+ * @param {Object} entry Style layer entry.
+ * @param {Object} feature Decoded feature.
+ * @param {number} sampleZoom Initial style zoom.
+ * @param {number} maxZoom Maximum zoom to search for visible line paint.
+ *
+ * @returns {Object|null} Paint, or null if no compatible visible paint exists.
+ */
 export function vectorFeaturePaint(entry, feature, sampleZoom, maxZoom) {
   if (entry.type === 'fill') return feature.type === 3 ? vectorPaint(entry, feature.properties, sampleZoom) : null;
   if (entry.type !== 'line' || feature.type !== 2) return null;

package/src/vector-tiles/vectorFeaturePaths.js

@@ -2,6 +2,16 @@ import { projectVectorTriangles } from './projectVectorTriangles.js';
 import { projectVectorPaths } from './projectVectorPaths.js';
 import { vectorTolerance } from './vectorTolerance.js';
 
+/**
+ * Project and cache a feature's paths or fill triangles for the tile job.
+ *
+ * @param {Object} job Vector tile preparation job.
+ * @param {Object} layer Decoded source layer.
+ * @param {Object} entry Style layer entry.
+ * @param {Object} feature Decoded feature.
+ *
+ * @returns {Array} Projected feature paths.
+ */
 export function vectorFeaturePaths(job, layer, entry, feature) {
   const cache = entry.type === 'fill' ? job.triangles : job.projected;
   let paths = cache.get(feature);

package/src/vector-tiles/vectorFeatureZoom.js

@@ -1,5 +1,15 @@
 import { visibleStyle } from '../vector-style/visibleStyle.js';
 
+/**
+ * Find a zoom at which the style is visible for a feature.
+ *
+ * @param {Object} entry Style layer entry.
+ * @param {Object} properties Feature properties.
+ * @param {number} zoom Current style zoom.
+ * @param {number} maxZoom Maximum fallback zoom.
+ *
+ * @returns {number} Visible zoom, or -1 if none is found.
+ */
 export function vectorFeatureZoom(entry, properties, zoom, maxZoom) {
   if (visibleStyle(entry, properties, zoom)) return zoom;
   zoom = maxZoom;