leaflet-city-mapper 0.0.9 → 0.1.0

package/src/archives/getDirectoryEntries.js

@@ -1,7 +1,18 @@
-import { directoriesByLayer } from '../weakmaps/directoriesByLayer.js';
-
+import { directoriesByLayer } from '../weakmaps/directoriesByLayer.js';
 import { loadDirectory } from './loadDirectory.js';
 
+/**
+ * Load and cache decoded archive directories, evicting failed requests.
+ *
+ * @param {L.Layer} layer Archive layer owning the directory cache.
+ * @param {number} offset Directory byte offset.
+ * @param {number} length Directory byte length.
+ * @param {number} compression PMTiles compression code.
+ *
+ * @returns {Promise<Object[]>} Decoded directory entries.
+ *
+ * @throws {*} If loading the cached directory fails.
+ */
 export async function getDirectoryEntries(layer, offset, length, compression) {
   const directories = directoriesByLayer.get(layer);
   const key = `${offset}:${length}`;

package/src/archives/getHeader.js

@@ -3,8 +3,13 @@ import { sceneLayers } from '../weakmaps/sceneLayers.js';
 import { decodeHeader } from './decodeHeader.js';
 import { read } from './readArchiveRange.js';
 
-/** Cache header initialization; failures remain visible to all callers. */
-
+/**
+ * Cache header initialization; failures remain visible to all callers.
+ *
+ * @param {L.Layer|Object} layer Archive layer or external archive provider.
+ *
+ * @returns {Promise<Object>} Decoded archive header.
+ */
 export function getHeader(layer) {
   if (!sceneLayers.has(layer)) return layer.getHeader();
   if (layer.options.archive && layer.options.archive !== layer) return getHeader(layer.options.archive);

package/src/archives/getTileData.js

@@ -1,6 +1,19 @@
 import { decompress } from './decompress.js';
 import { read } from './readArchiveRange.js';
 
+/**
+ * Read and decompress tile data if the requested ID falls within the entry's run.
+ *
+ * @param {L.Layer} layer Archive layer.
+ * @param {Object} header Decoded archive header.
+ * @param {Object} entry Directory entry.
+ * @param {number} id Requested tile ID.
+ * @param {AbortSignal} [signal] Request cancellation signal.
+ *
+ * @returns {Promise<Object|undefined>} Object containing tile data, or undefined on a miss.
+ *
+ * @throws {Error} If the tile range extends outside the tile data section.
+ */
 export async function getTileData(layer, header, entry, id, signal) {
   if (id - entry.tileId >= entry.runLength) return;
   if (entry.offset + entry.length > header.tileDataLength) {

package/src/archives/getZxy.js

@@ -1,11 +1,19 @@
 import { sceneLayers } from '../weakmaps/sceneLayers.js';
-
 import { tileId } from './tileId.js';
 import { getHeader } from './getHeader.js';
 import { findTile } from './findTile.js';
 
-/** Nearest directory entry at/before the Hilbert ID, then follow leaf pointers. */
-
+/**
+ * Retrieve an archive tile by XYZ coordinates, following leaf pointers when necessary.
+ *
+ * @param {L.Layer|Object} layer Archive layer or external archive provider.
+ * @param {number} z Tile zoom level.
+ * @param {number} x Tile column.
+ * @param {number} y Tile row.
+ * @param {AbortSignal} [signal] Request cancellation signal.
+ *
+ * @returns {Promise<Object|undefined>} Tile data, or undefined when unavailable.
+ */
 export async function getZxy(layer, z, x, y, signal) {
   if (!sceneLayers.has(layer)) return layer.getZxy(z, x, y, signal);
   if (layer.options.archive && layer.options.archive !== layer) {

package/src/archives/loadDirectory.js

@@ -2,6 +2,16 @@ import { decodeDirectory } from "./decodeDirectory.js";
 import { decompress } from "./decompress.js";
 import { read } from "./readArchiveRange.js";
 
+/**
+ * Read, decompress and decode an archive directory.
+ *
+ * @param {L.Layer} layer Archive layer.
+ * @param {number} offset Directory byte offset.
+ * @param {number} length Directory byte length.
+ * @param {number} compression PMTiles compression code.
+ *
+ * @returns {Promise<Object[]>} Decoded directory entries.
+ */
 export async function loadDirectory(layer, offset, length, compression) {
   return decodeDirectory(await decompress(await read(layer, offset, length), compression));
 }

package/src/archives/loadSource.js

@@ -1,10 +1,19 @@
 import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
-
 import { archiveDecoder } from '../globals/archiveDecoder.js';
-
 import { getZxy } from './getZxy.js';
 
-
+/**
+ * Load GeoJSON from inline data, a URL or the requested archive tile.
+ *
+ * @param {L.Layer} layer Source layer.
+ * @param {Object} area Area coordinates and request controller.
+ *
+ * @returns {Promise<Object>} GeoJSON data, or an empty collection on an archive miss.
+ *
+ * @throws {Error} If both inline data and a URL are supplied.
+ * @throws {Error} If neither inline data nor a URL is supplied for a GeoJSON source.
+ * @throws {Error} If the GeoJSON request returns a non-success status.
+ */
 export async function loadSource(layer, area) {
   if (geojsonByLayer.get(layer)) {
     const { data, url } = layer.options;

package/src/archives/readArchiveRange.js

@@ -1,8 +1,22 @@
-import { etagByLayer } from '../weakmaps/etagByLayer.js';
-import { urlByLayer } from '../weakmaps/urlByLayer.js';
-
-
+import { etagByLayer } from '../weakmaps/etagByLayer.js';
+import { urlByLayer } from '../weakmaps/urlByLayer.js';
 
+/**
+ * Read and validate a byte range from a PMTiles archive.
+ *
+ * @param {L.Layer} layer Archive layer containing the URL and cached ETag.
+ * @param {number} offset Starting byte offset.
+ * @param {number} length Number of bytes to read.
+ * @param {AbortSignal} [signal] Request cancellation signal.
+ *
+ * @returns {Promise<ArrayBuffer>} Requested archive bytes.
+ *
+ * @throws {Error} If the requested byte range is invalid.
+ * @throws {Error} If the HTTP request fails.
+ * @throws {Error} If the archive ETag changes.
+ * @throws {Error} If the range response headers or status are invalid.
+ * @throws {Error} If the response length differs from the requested range.
+ */
 export async function read(layer, offset, length, signal) {
   signal?.throwIfAborted();
   if (!Number.isSafeInteger(offset) || !Number.isSafeInteger(length) ||

package/src/archives/readVarint.js

@@ -1,5 +1,14 @@
-
-
+/**
+ * Read one unsigned PMTiles varint and advance the reader cursor.
+ *
+ * @param {Object} reader Reader containing the bytes and cursor.
+ *
+ * @returns {number} Decoded safe integer.
+ *
+ * @throws {Error} If the directory ends before the varint.
+ * @throws {Error} If the decoded value exceeds the safe integer range.
+ * @throws {Error} If the varint does not terminate within the supported length.
+ */
 export function varint(reader) {
   const { bytes } = reader;
   let value = 0;

package/src/archives/tileId.js

@@ -1,5 +1,14 @@
-/** Cumulative Hilbert ID for an archive tile. */
-
+/**
+ * Compute the cumulative Hilbert ID for an archive tile.
+ *
+ * @param {number} z Tile zoom level.
+ * @param {number} x Tile column.
+ * @param {number} y Tile row.
+ *
+ * @returns {number} Cumulative tile ID.
+ *
+ * @throws {Error} If the tile coordinates are outside the supported zoom grid.
+ */
 export function tileId(z, x, y) {
   if (!Number.isInteger(z) || !Number.isInteger(x) || !Number.isInteger(y) || z < 0 || z > 26 ||
     x < 0 || y < 0 || x >= 2 ** z || y >= 2 ** z) {

package/src/astronomy/README.md

@@ -0,0 +1,25 @@
+# Astronomy
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Calculates celestial positions and solar time for a date and observer.
+
+## From observer to direction
+
+```mermaid
+flowchart LR
+  Observer["Time + latitude / longitude"] --> Positions["Solar / lunar coordinates"]
+  Positions --> Horizontal["Observer-relative position"]
+  Horizontal --> Output["Altitude + azimuth + world direction"]
+  Output --> Sunlight["Sunlight / sky"]
+```
+
+Output angles are degrees; internal trigonometry uses radians. Solar position
+does not include atmospheric refraction. The clock belongs to
+[sunlight](../sunlight/README.md), not these calculations.
+
+- [solarPosition.js](./solarPosition.js) and [moonPosition.js](./moonPosition.js): celestial coordinates.
+- [horizontalPosition.js](./horizontalPosition.js): observer-relative position.
+- [solarTime.js](./solarTime.js): solar time calculation.
+
+Related: [sunlight](../sunlight/README.md).

package/src/astronomy/horizontalPosition.js

@@ -1,5 +1,16 @@
 import { radians } from '../globals/radians.js';
 
+/**
+ * Convert equatorial coordinates to observer-relative altitude, azimuth and direction.
+ *
+ * @param {number} d Days since the J2000 epoch.
+ * @param {number} lat Observer latitude in degrees.
+ * @param {number} lng Observer longitude in degrees.
+ * @param {number} ascension Right ascension in radians.
+ * @param {number} declination Declination in radians.
+ *
+ * @returns {Object} Altitude and azimuth in degrees and a world-space direction vector.
+ */
 export function horizontalPosition(d, lat, lng, ascension, declination) {
   const hourAngle = (280.16 + 360.9856235 * d + lng) * radians - ascension;
   const latitude = lat * radians;

package/src/astronomy/moonPosition.js

@@ -4,8 +4,15 @@ import { radians } from '../globals/radians.js';
 import { sinObliquity } from '../globals/sinObliquity.js';
 import { cosObliquity } from '../globals/cosObliquity.js';
 
-// Low-precision geocentric lunar orbit; no parallax or atmospheric refraction.
-
+/**
+ * Approximate the geocentric lunar position without parallax or atmospheric refraction.
+ *
+ * @param {Date|string|number} date Observation date.
+ * @param {number} lat Observer latitude in degrees.
+ * @param {number} lng Observer longitude in degrees.
+ *
+ * @returns {Object} Altitude, azimuth and world-space direction.
+ */
 export function moonPosition(date, lat, lng) {
   const d = solarTime(date, lat, lng) / 86400000 - 10957.5;
   const anomaly = (134.963 + 13.064993 * d) * radians;

package/src/astronomy/solarPosition.js

@@ -4,8 +4,15 @@ import { radians } from '../globals/radians.js';
 import { sinObliquity } from '../globals/sinObliquity.js';
 import { cosObliquity } from '../globals/cosObliquity.js';
 
-// Solar centre, without atmospheric refraction.
-
+/**
+ * Calculate the solar center position without atmospheric refraction.
+ *
+ * @param {Date|string|number} date Observation date.
+ * @param {number} lat Observer latitude in degrees.
+ * @param {number} lng Observer longitude in degrees.
+ *
+ * @returns {Object} Altitude, azimuth and world-space direction.
+ */
 export function solarPosition(date, lat, lng) {
   const time = solarTime(date, lat, lng);
   const d = time / 86400000 - 10957.5;

package/src/astronomy/solarTime.js

@@ -1,4 +1,14 @@
-/** Normalize dates and validate the observer without calculating a celestial position. */
+/**
+ * Normalize dates and validate the observer without calculating a celestial position.
+ *
+ * @param {Date|string|number} date Observation date.
+ * @param {number} lat Observer latitude in degrees.
+ * @param {number} lng Observer longitude in degrees.
+ *
+ * @returns {number} Timestamp in milliseconds since the Unix epoch.
+ *
+ * @throws {Error} If the date or observer coordinates are invalid.
+ */
 export function solarTime(date, lat, lng) {
   const time = date instanceof Date ? Date.prototype.getTime.call(date)
     : typeof date === 'string' ? Date.parse(date)

package/src/camera/README.md

@@ -0,0 +1,30 @@
+# Camera
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Extends map behavior for pitch and bearing and updates the scene camera to match
+the Leaflet view. Camera-aware bounds and pan operations live here as well.
+
+## Map state versus scene camera
+
+```mermaid
+flowchart LR
+  Input["Controls / map API"] --> Set["Validate angles"]
+  Set --> State["Per-map pitch + bearing"]
+  State --> Events["pitch / rotate events"]
+  State --> Camera["updateMapCamera"]
+  View["Viewport + zoom + origin"] --> Camera
+  Height["Terrain + walker height"] --> Camera
+  Camera --> Render["Scene perspective"]
+```
+
+Pitch is clamped and bearing normalized. The rendering camera is derived from
+map state, including intermediate zoom views; elevated geometry uses the GPU
+camera, not a CSS transform. Ground conversion lives in
+[projections](../projections/README.md).
+
+- [mapCamera.js](./mapCamera.js): install camera-related map integration.
+- [mapSetPitchAndBearing.js](./mapSetPitchAndBearing.js): validate and update camera angles.
+- [updateMapCamera.js](./updateMapCamera.js): synchronize the rendering camera.
+
+Related: [controls](../controls/README.md), [projections](../projections/README.md), [animations](../animations/README.md).

package/src/camera/cameraMapReady.js

@@ -1,9 +1,7 @@
-import { cameraDraggableByMap } from '../weakmaps/cameraDraggableByMap.js';
-
-
-
-import { adjustCameraDrag } from '../controls/adjustCameraDrag.js';
-
+import { cameraDraggableByMap } from '../weakmaps/cameraDraggableByMap.js';
+import { adjustCameraDrag } from '../controls/adjustCameraDrag.js';
+
+/** Attach the camera drag adjustment once this map's draggable is ready. */
 export function cameraMapReady() {
   const draggable = this.dragging?._draggable;
   if (!draggable) return;

package/src/camera/cleanupCameraMap.js

@@ -1,11 +1,9 @@
-import { cameraDraggableByMap } from '../weakmaps/cameraDraggableByMap.js';
-import { pitchSkyByMap } from '../weakmaps/pitchSkyByMap.js';
-
-
-
-import { cancelCameraAnimation } from '../animations/cancelCameraAnimation.js';
-import { adjustCameraDrag } from '../controls/adjustCameraDrag.js';
-
+import { cameraDraggableByMap } from '../weakmaps/cameraDraggableByMap.js';
+import { pitchSkyByMap } from '../weakmaps/pitchSkyByMap.js';
+import { cancelCameraAnimation } from '../animations/cancelCameraAnimation.js';
+import { adjustCameraDrag } from '../controls/adjustCameraDrag.js';
+
+/** Cancel this map's camera animation and remove its sky and drag listener. */
 export function cleanupCameraMap() {
   cancelCameraAnimation(this);
   pitchSkyByMap.get(this)?.remove();

package/src/camera/constrainCameraToBounds.js

@@ -1,3 +1,4 @@
+/** Pan this map inside its maximum bounds when bounds are configured. */
 export function constrainCameraToBounds() {
   if (this.options.maxBounds) this._panInsideMaxBounds();
 }

package/src/camera/createSceneCamera.js

@@ -1,4 +1,8 @@
-/** Perspective camera state: fov in degrees, near/far in scene metres. */
+/**
+ * Create perspective camera state with identity matrices and default projection parameters.
+ *
+ * @returns {Object} Camera state; fov is in degrees and near/far are in scene metres.
+ */
 export function createSceneCamera() {
   return /* alloc */ {
     position: /* alloc */ [0, 0, 0],

package/src/camera/fitCameraBounds.js

@@ -6,7 +6,15 @@ import { pointOf } from '../projections/toPoint.js';
 import { angles } from '../projections/cameraAngles.js';
 import { verticalGroundY } from '../projections/verticalGroundY.js';
 
-
+/**
+ * Fit geographic bounds in the camera's rotated, perspective ground viewport.
+ *
+ * @param {L.Map} map Map providing camera and zoom settings.
+ * @param {L.LatLngBounds|Array|Object} bounds Geographic bounds or an object providing them.
+ * @param {Object} [options] Padding and maximum zoom options.
+ *
+ * @returns {Object} Fitted center and zoom.
+ */
 export function fitCameraBounds(map, bounds, options = cameraEmptyOptions) {
   bounds = bounds.getBounds ? bounds.getBounds() : bounds instanceof L.LatLngBounds ? bounds
     : /* alloc */ new L.LatLngBounds(bounds);

package/src/camera/getBearing.js

@@ -1,5 +1,10 @@
 import { mapGetBearing } from './mapGetBearing.js';
 
+/**
+ * Get this map's camera bearing.
+ *
+ * @returns {number} Bearing in degrees.
+ */
 export function getBearing() {
   return mapGetBearing(this);
 }

package/src/camera/getPitch.js

@@ -1,5 +1,10 @@
 import { mapGetPitch } from './mapGetPitch.js';
 
+/**
+ * Get this map's camera pitch.
+ *
+ * @returns {number} Pitch in degrees.
+ */
 export function getPitch() {
   return mapGetPitch(this);
 }

package/src/camera/initializeCameraMap.js

@@ -1,9 +1,6 @@
 import { cameraMaps } from '../weakmaps/cameraMaps.js';
 import { cameraReadyByMap } from '../weakmaps/cameraReadyByMap.js';
-
-
 import { mapSetPitchAndBearing } from './mapSetPitchAndBearing.js';
-
 import { updateSky } from './updateSky.js';
 import { constrainCameraToBounds } from './constrainCameraToBounds.js';
 import { cleanupCameraMap } from './cleanupCameraMap.js';
@@ -11,6 +8,7 @@ import { cameraMapReady } from './cameraMapReady.js';
 import { loadCameraControls } from '../controls/loadCameraControls.js';
 import { noOperation } from '../utils/noOperation.js';
 
+/** Initialize this map's camera, lifecycle listeners and optional camera controls. */
 export function initializeCameraMap() {
   cameraMaps.add(this);
   if (!document.getElementById('leaflet-camera-zoom-style')) {

package/src/camera/mapCamera.js

@@ -8,9 +8,7 @@ import { popupPan } from '../globals/popupPan.js';
 import { tooltipPosition } from '../globals/tooltipPosition.js';
 import { tiledBounds } from '../globals/tiledBounds.js';
 import { gridEvents } from '../globals/gridEvents.js';
-
 import { initNativeGPU } from '../native/initNativeGPU.js';
-
 import { mapLayerPointToContainerPoint } from './mapLayerPointToContainerPoint.js';
 import { mapContainerPointToLayerPoint } from './mapContainerPointToLayerPoint.js';
 import { mapGetCenterLayerPoint } from './mapGetCenterLayerPoint.js';

package/src/camera/mapContainerPointToLayerPoint.js

@@ -1,9 +1,14 @@
 import { mapMethods } from '../globals/mapMethods.js';
-
-
 import { animationPoint } from '../projections/transformZoomAnimationPoint.js';
 import { project } from '../projections/projectCameraPoint.js';
 
+/**
+ * Convert a screen point to a layer point through the inverse camera projection.
+ *
+ * @param {L.Point|Array} point Container point.
+ *
+ * @returns {L.Point} Corresponding layer point.
+ */
 export function mapContainerPointToLayerPoint(point) {
   return mapMethods.value.containerPointToLayerPoint.call(this, animationPoint(this, project(this, point, true), true));
 }

package/src/camera/mapGetBearing.js

@@ -1,5 +1,10 @@
 import { cameraBearingByMap } from '../weakmaps/cameraBearingByMap.js';
 
-
-
+/**
+ * Read a map's stored bearing, defaulting to north.
+ *
+ * @param {L.Map} map Map to inspect.
+ *
+ * @returns {number} Bearing in degrees.
+ */
 export function mapGetBearing(map) { return cameraBearingByMap.get(map) ?? 0; }

package/src/camera/mapGetBounds.js

@@ -1,12 +1,15 @@
 import { L } from '../globals/L.js';
 import { mapMethods } from '../globals/mapMethods.js';
-
 import { mapGetPitch } from './mapGetPitch.js';
 import { mapGetBearing } from './mapGetBearing.js';
-
 import { groundBounds } from '../projections/groundBounds.js';
 import { animationPoint } from '../projections/transformZoomAnimationPoint.js';
 
+/**
+ * Get geographic bounds of this map's camera ground footprint.
+ *
+ * @returns {L.LatLngBounds} Visible ground bounds.
+ */
 export function mapGetBounds() {
   if (!mapGetPitch(this) && !mapGetBearing(this)) return mapMethods.value.getBounds.call(this);
   const footprint = groundBounds(this), bounds = /* alloc */ new L.LatLngBounds();

package/src/camera/mapGetBoundsCenterZoom.js

@@ -1,9 +1,16 @@
-import { mapMethods } from '../globals/mapMethods.js';
-
-import { mapGetPitch } from './mapGetPitch.js';
-import { mapGetBearing } from './mapGetBearing.js';
-import { fitCameraBounds } from './fitCameraBounds.js';
-
+import { mapMethods } from '../globals/mapMethods.js';
+import { mapGetPitch } from './mapGetPitch.js';
+import { mapGetBearing } from './mapGetBearing.js';
+import { fitCameraBounds } from './fitCameraBounds.js';
+
+/**
+ * Compute a bounds center and zoom using the camera-aware fit when needed.
+ *
+ * @param {L.LatLngBounds|Array} bounds Geographic bounds.
+ * @param {Object} options Fit options.
+ *
+ * @returns {Object} Fitted center and zoom.
+ */
 export function mapGetBoundsCenterZoom(bounds, options) {
   return mapGetPitch(this) || mapGetBearing(this) ? fitCameraBounds(this, bounds, options) :
     mapMethods.value._getBoundsCenterZoom.call(this, bounds, options);

package/src/camera/mapGetBoundsZoom.js

@@ -1,14 +1,21 @@
 import { L } from '../globals/L.js';
 import { mapMethods } from '../globals/mapMethods.js';
 import { cameraZeroPadding } from '../globals/cameraZeroPadding.js';
-
 import { mapGetPitch } from './mapGetPitch.js';
 import { mapGetBearing } from './mapGetBearing.js';
-
 import { fitCameraBounds } from './fitCameraBounds.js';
 import { pointOf } from '../projections/toPoint.js';
 import { groundBounds } from '../projections/groundBounds.js';
 
+/**
+ * Compute a bounds zoom using the camera ground footprint when rotated or pitched.
+ *
+ * @param {L.LatLngBounds|Array} bounds Geographic bounds.
+ * @param {boolean} inside Whether the viewport must fit inside the bounds.
+ * @param {L.Point|Array} padding Viewport padding.
+ *
+ * @returns {number} Fitted zoom level.
+ */
 export function mapGetBoundsZoom(bounds, inside, padding) {
   if (!mapGetPitch(this) && !mapGetBearing(this)) return mapMethods.value.getBoundsZoom.call(this, bounds, inside, padding);
   if (!inside) return fitCameraBounds(this, bounds,

package/src/camera/mapGetCenterLayerPoint.js

@@ -1,6 +1,10 @@
 import { mapMethods } from '../globals/mapMethods.js';
 
-
+/**
+ * Convert the center of this map's container to a layer point.
+ *
+ * @returns {L.Point} Center layer point.
+ */
 export function mapGetCenterLayerPoint() {
   return mapMethods.value.containerPointToLayerPoint.call(this, this.getSize().divideBy(2));
 }

package/src/camera/mapGetPitch.js

@@ -1,5 +1,10 @@
 import { cameraPitchByMap } from '../weakmaps/cameraPitchByMap.js';
 
-
-
+/**
+ * Read a map's stored pitch, defaulting to zero.
+ *
+ * @param {L.Map} map Map to inspect.
+ *
+ * @returns {number} Pitch in degrees.
+ */
 export function mapGetPitch(map) { return cameraPitchByMap.get(map) ?? 0; }

package/src/camera/mapLayerPointToContainerPoint.js

@@ -1,8 +1,14 @@
 import { mapMethods } from '../globals/mapMethods.js';
-
 import { project } from '../projections/projectCameraPoint.js';
 import { animationPoint } from '../projections/transformZoomAnimationPoint.js';
 
+/**
+ * Convert a layer point to a screen point through the camera projection.
+ *
+ * @param {L.Point|Array} point Layer point.
+ *
+ * @returns {L.Point} Corresponding container point.
+ */
 export function mapLayerPointToContainerPoint(point) {
   return project(this, animationPoint(this, mapMethods.value.layerPointToContainerPoint.call(this, point)));
 }

package/src/camera/mapLimitCenter.js

@@ -1,11 +1,18 @@
 import { L } from '../globals/L.js';
 import { mapMethods } from '../globals/mapMethods.js';
-
 import { mapGetPitch } from './mapGetPitch.js';
 import { mapGetBearing } from './mapGetBearing.js';
-
 import { groundBounds } from '../projections/groundBounds.js';
 
+/**
+ * Limit a proposed center to bounds using the projected camera footprint.
+ *
+ * @param {L.LatLng} center Proposed map center.
+ * @param {number} zoom Zoom level for the bounds calculation.
+ * @param {L.LatLngBounds} bounds Maximum geographic bounds.
+ *
+ * @returns {L.LatLng} Limited center.
+ */
 export function mapLimitCenter(center, zoom, bounds) {
   if (!bounds || !this._loaded || !mapGetPitch(this) && !mapGetBearing(this)) {
     return mapMethods.value._limitCenter.call(this, center, zoom, bounds);

package/src/camera/mapLimitOffset.js

@@ -1,10 +1,16 @@
-import { mapMethods } from '../globals/mapMethods.js';
-
-import { mapGetPitch } from './mapGetPitch.js';
-import { mapGetBearing } from './mapGetBearing.js';
-
-import { project } from '../projections/projectCameraPoint.js';
-
+import { mapMethods } from '../globals/mapMethods.js';
+import { mapGetPitch } from './mapGetPitch.js';
+import { mapGetBearing } from './mapGetBearing.js';
+import { project } from '../projections/projectCameraPoint.js';
+
+/**
+ * Limit a screen pan offset to geographic bounds under the camera projection.
+ *
+ * @param {L.Point} offset Proposed screen offset.
+ * @param {L.LatLngBounds} bounds Maximum geographic bounds.
+ *
+ * @returns {L.Point} Limited screen offset.
+ */
 export function mapLimitOffset(offset, bounds) {
   if (!bounds || !mapGetPitch(this) && !mapGetBearing(this)) return mapMethods.value._limitOffset.call(this, offset, bounds);
   const half = this.getSize().divideBy(2), ground = half.subtract(project(this, half.subtract(offset), true));