leaflet-city-mapper 0.0.9 → 0.1.1

package/src/gpu/initializeRendererResources.js

@@ -1,34 +1,39 @@
-import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
-import { sceneSunlightUniforms } from '../globals/sceneSunlightUniforms.js';
-import { resizeSunlight } from '../shadows/resizeSunlight.js';
-
-export function initializeRendererResources(layer, device) {
-  const renderer = rendererByLayer.get(layer);
-  const layout = device.createBindGroupLayout(/* alloc */ {
-    entries: /* alloc */ [
-      /* alloc */ { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: /* alloc */ { type: 'uniform' } },
-      /* alloc */ { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: /* alloc */ { sampleType: 'depth' } },
-      /* alloc */ { binding: 2, visibility: GPUShaderStage.FRAGMENT, sampler: /* alloc */ { type: 'comparison' } },
-      /* alloc */ { binding: 3, visibility: GPUShaderStage.FRAGMENT, buffer: /* alloc */ { type: 'read-only-storage' } },
-    ]
-  });
-  const buffer = device.createBuffer(/* alloc */ { size: 80, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
-  const sampler = device.createSampler(/* alloc */ { compare: 'less-equal', minFilter: 'linear', magFilter: 'linear' });
-  const lights = device.createBuffer(/* alloc */ { size: 32, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
-  renderer.sunlight = /* alloc */ { layout, buffer, sampler, lights, size: 0 };
-  device.queue.writeBuffer(buffer, 0, sceneSunlightUniforms);
-  resizeSunlight(layer, 1);
-  renderer.roofFallbackTexture = /* alloc */ {
-    device,
-    texture: device.createTexture(/* alloc */ {
-      size: /* alloc */ [1, 1],
-      format: 'rgba8unorm',
-      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
-    }),
-    sampler: device.createSampler(/* alloc */ {
-      addressModeU: 'clamp-to-edge', addressModeV: 'clamp-to-edge',
-    }),
-    image: null, format: 'rgba8unorm', srgb: false, uploaded: null,
-  };
-}
+import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
+import { sceneSunlightUniforms } from '../globals/sceneSunlightUniforms.js';
+import { resizeSunlight } from '../shadows/resizeSunlight.js';
+
+/**
+ * Create sunlight bindings and a fallback roof texture for the layer's renderer.
+ *
+ * @param {L.Layer} layer Layer owning the renderer.
+ * @param {GPUDevice} device Device used to create the resources.
+ */
+export function initializeRendererResources(layer, device) {
+  const renderer = rendererByLayer.get(layer);
+  const layout = device.createBindGroupLayout(/* alloc */ {
+    entries: /* alloc */ [
+      /* alloc */ { binding: 0, visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT, buffer: /* alloc */ { type: 'uniform' } },
+      /* alloc */ { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: /* alloc */ { sampleType: 'depth' } },
+      /* alloc */ { binding: 2, visibility: GPUShaderStage.FRAGMENT, sampler: /* alloc */ { type: 'comparison' } },
+      /* alloc */ { binding: 3, visibility: GPUShaderStage.FRAGMENT, buffer: /* alloc */ { type: 'read-only-storage' } },
+    ]
+  });
+  const buffer = device.createBuffer(/* alloc */ { size: 80, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST });
+  const sampler = device.createSampler(/* alloc */ { compare: 'less-equal', minFilter: 'linear', magFilter: 'linear' });
+  const lights = device.createBuffer(/* alloc */ { size: 32, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+  renderer.sunlight = /* alloc */ { layout, buffer, sampler, lights, size: 0 };
+  device.queue.writeBuffer(buffer, 0, sceneSunlightUniforms);
+  resizeSunlight(layer, 1);
+  renderer.roofFallbackTexture = /* alloc */ {
+    device,
+    texture: device.createTexture(/* alloc */ {
+      size: /* alloc */ [1, 1],
+      format: 'rgba8unorm',
+      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST | GPUTextureUsage.RENDER_ATTACHMENT,
+    }),
+    sampler: device.createSampler(/* alloc */ {
+      addressModeU: 'clamp-to-edge', addressModeV: 'clamp-to-edge',
+    }),
+    image: null, format: 'rgba8unorm', srgb: false, uploaded: null,
+  };
+}

package/src/gpu/initializeSharedRenderer.js

@@ -5,48 +5,55 @@ import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
 import { sceneByLayer } from '../weakmaps/sceneByLayer.js';
 import { sceneOriginByLayer } from '../weakmaps/sceneOriginByLayer.js';
 import { sharedByLayer } from '../weakmaps/sharedByLayer.js';
+import { rendererDevices } from '../weakmaps/rendererDevices.js';
+import { emptyNode } from '../scene/createSceneNode.js';
+import { failAttachment } from '../scene/failAttachment.js';
+import { requestAdapter } from './requestAdapter.js';
+import { requestDevice } from './requestDevice.js';
+import { rendererDeviceError } from './rendererDeviceError.js';
+import { rendererDeviceLost } from './rendererDeviceLost.js';
+import { createSceneCamera } from '../camera/createSceneCamera.js';
+import { initializeRendererResources } from './initializeRendererResources.js';
+import { mountRenderer } from './mountRenderer.js';
 
-import { rendererDevices } from '../weakmaps/rendererDevices.js';
-import { emptyNode } from '../scene/createSceneNode.js';
-import { failAttachment } from '../scene/failAttachment.js';
-import { requestAdapter } from './requestAdapter.js';
-import { requestDevice } from './requestDevice.js';
-import { rendererDeviceError } from './rendererDeviceError.js';
-import { rendererDeviceLost } from './rendererDeviceLost.js';
-import { createSceneCamera } from '../camera/createSceneCamera.js';
-import { initializeRendererResources } from './initializeRendererResources.js';
-import { mountRenderer } from './mountRenderer.js';
-
-export async function initializeSharedRenderer(layer, map) {
-  const canvas = document.createElement('canvas');
-  if (!navigator.gpu) {
-    failAttachment(/* alloc */ new Error('Layer3D requires WebGPU'), layer, map);
-  }
-  const adapter = await requestAdapter(layer, map);
-  const device = await requestDevice(adapter, layer, map);
-  rendererDevices.set(device, map);
-  device.addEventListener('uncapturederror', rendererDeviceError);
-  Promise.all(/* alloc */ [device.lost, Promise.resolve(device)]).then(rendererDeviceLost);
-  const context = canvas.getContext('webgpu');
-  if (!context) {
-    device.destroy();
-    failAttachment(/* alloc */ new Error('Unable to create a WebGPU canvas context'), layer, map);
-  }
-  const format = navigator.gpu.getPreferredCanvasFormat();
-  context.configure(/* alloc */ { device, format, alphaMode: 'premultiplied' });
-  map.getContainer().querySelector('.leaflet-webgpu-warning')?.remove();
-  sharedByLayer.set(layer, layer);
-  layersByLayer.set(layer, /* alloc */ new Set());
-  sceneOriginByLayer.set(layer, locationByLayer.get(layer));
-  sceneByLayer.set(layer, emptyNode());
-  cameraByLayer.set(layer, createSceneCamera());
-  rendererByLayer.set(layer, /* alloc */ {
-    device,
-    context,
-    format,
-    canvas,
-    dpr: Math.min(window.devicePixelRatio, 2)
-  });
-  initializeRendererResources(layer, device);
-  mountRenderer(layer, map, canvas);
-}
+/**
+ * Acquire a WebGPU device and initialize the shared scene, renderer and canvas.
+ *
+ * @param {L.Layer} layer Layer that owns the shared renderer.
+ * @param {L.Map} map Map receiving the renderer.
+ *
+ * @returns {Promise<void>} Resolves after the renderer is mounted.
+ */
+export async function initializeSharedRenderer(layer, map) {
+  const canvas = document.createElement('canvas');
+  if (!navigator.gpu) {
+    failAttachment(/* alloc */ new Error('Layer3D requires WebGPU'), layer, map);
+  }
+  const adapter = await requestAdapter(layer, map);
+  const device = await requestDevice(adapter, layer, map);
+  rendererDevices.set(device, map);
+  device.addEventListener('uncapturederror', rendererDeviceError);
+  Promise.all(/* alloc */ [device.lost, Promise.resolve(device)]).then(rendererDeviceLost);
+  const context = canvas.getContext('webgpu');
+  if (!context) {
+    device.destroy();
+    failAttachment(/* alloc */ new Error('Unable to create a WebGPU canvas context'), layer, map);
+  }
+  const format = navigator.gpu.getPreferredCanvasFormat();
+  context.configure(/* alloc */ { device, format, alphaMode: 'premultiplied' });
+  map.getContainer().querySelector('.leaflet-webgpu-warning')?.remove();
+  sharedByLayer.set(layer, layer);
+  layersByLayer.set(layer, /* alloc */ new Set());
+  sceneOriginByLayer.set(layer, locationByLayer.get(layer));
+  sceneByLayer.set(layer, emptyNode());
+  cameraByLayer.set(layer, createSceneCamera());
+  rendererByLayer.set(layer, /* alloc */ {
+    device,
+    context,
+    format,
+    canvas,
+    dpr: Math.min(window.devicePixelRatio, 2)
+  });
+  initializeRendererResources(layer, device);
+  mountRenderer(layer, map, canvas);
+}

package/src/gpu/mountRenderer.js

@@ -1,19 +1,25 @@
-import { sizeByLayer } from '../weakmaps/sizeByLayer.js';
-
-import { onMapChange } from '../scene/onMapChange.js';
-import { startZoom } from '../animations/startZoom.js';
-import { onZoomAnim } from '../animations/onZoomAnim.js';
-import { endZoom } from '../animations/endZoom.js';
-
-export function mountRenderer(layer, map, canvas) {
-  sizeByLayer.set(layer, null);
-  canvas.className = 'leaflet-3d';
-  canvas.style.cssText = 'position:absolute;top:0;left:0;z-index:1;pointer-events:none';
-  canvas.setAttribute('role', 'img');
-  canvas.setAttribute('aria-label', layer.options.ariaLabel ?? '3D scene');
-  map.getPane('mapPane').before(canvas);
-  map.on('move zoom rotate pitch resize viewreset layeradd layerremove', onMapChange, layer);
-  map.on('zoomstart', startZoom, layer);
-  map.on('zoomanim', onZoomAnim, layer);
-  map.on('zoomend', endZoom, layer);
-}
+import { sizeByLayer } from '../weakmaps/sizeByLayer.js';
+import { onMapChange } from '../scene/onMapChange.js';
+import { startZoom } from '../animations/startZoom.js';
+import { onZoomAnim } from '../animations/onZoomAnim.js';
+import { endZoom } from '../animations/endZoom.js';
+
+/**
+ * Insert the rendering canvas and subscribe the layer to map and zoom events.
+ *
+ * @param {L.Layer} layer Layer receiving map events.
+ * @param {L.Map} map Map receiving the canvas.
+ * @param {HTMLCanvasElement} canvas WebGPU rendering canvas.
+ */
+export function mountRenderer(layer, map, canvas) {
+  sizeByLayer.set(layer, null);
+  canvas.className = 'leaflet-3d';
+  canvas.style.cssText = 'position:absolute;top:0;left:0;z-index:1;pointer-events:none';
+  canvas.setAttribute('role', 'img');
+  canvas.setAttribute('aria-label', layer.options.ariaLabel ?? '3D scene');
+  map.getPane('mapPane').before(canvas);
+  map.on('move zoom rotate pitch resize viewreset layeradd layerremove', onMapChange, layer);
+  map.on('zoomstart', startZoom, layer);
+  map.on('zoomanim', onZoomAnim, layer);
+  map.on('zoomend', endZoom, layer);
+}

package/src/gpu/releaseRenderer.js

@@ -1,3 +1,11 @@
+/**
+ * Wait for submitted GPU work, release renderer resources and destroy the device.
+ *
+ * @param {Object} renderer Renderer whose resources are released.
+ * @param {L.Layer} layer Layer notified if resource cleanup fails.
+ *
+ * @returns {Promise<void>} Resolves after device destruction.
+ */
 export async function releaseRenderer(renderer, layer) {
   try {
     await renderer.device.queue.onSubmittedWorkDone();

package/src/gpu/rendererDeviceError.js

@@ -1,11 +1,13 @@
 import { layersByLayer } from '../weakmaps/layersByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { rendererDevices } from '../weakmaps/rendererDevices.js';
 import { renderers } from '../weakmaps/renderers.js';
 
-
-
+/**
+ * Forward an uncaptured GPU error to layers using the current renderer.
+ *
+ * @param {GPUUncapturedErrorEvent} event Device error event.
+ */
 export function rendererDeviceError(event) {
   const map = rendererDevices.get(event.currentTarget);
   const owner = renderers.get(map);

package/src/gpu/rendererDeviceLost.js

@@ -1,11 +1,13 @@
 import { layersByLayer } from '../weakmaps/layersByLayer.js';
 import { rendererByLayer } from '../weakmaps/rendererByLayer.js';
-
 import { rendererDevices } from '../weakmaps/rendererDevices.js';
 import { renderers } from '../weakmaps/renderers.js';
 
-
-
+/**
+ * Report device loss to layers using the affected current renderer.
+ *
+ * @param {Array} result Device-lost information followed by the device.
+ */
 export function rendererDeviceLost([info, device]) {
   const map = rendererDevices.get(device);
   const owner = renderers.get(map);

package/src/gpu/reportShaderCompilation.js

@@ -1,3 +1,11 @@
+/**
+ * Report shader compilation errors or rejected compilation-info requests to the layer.
+ *
+ * @param {L.Layer} layer Layer receiving error events.
+ * @param {Promise[]} pending Compilation-info promises.
+ *
+ * @returns {Promise<void>} Resolves after reporting the results.
+ */
 export async function reportCompilation(layer, pending) {
   let info, message;
   try {

package/src/gpu/requestAdapter.js

@@ -1,5 +1,13 @@
 import { failAttachment } from '../scene/failAttachment.js';
 
+/**
+ * Request a WebGPU adapter and fail the layer attachment if it is unavailable.
+ *
+ * @param {L.Layer} layer Layer being attached.
+ * @param {L.Map} map Map receiving the layer.
+ *
+ * @returns {Promise<GPUAdapter>} The acquired adapter.
+ */
 export async function requestAdapter(layer, map) {
   let adapter;
   try {

package/src/gpu/requestDevice.js

@@ -1,5 +1,14 @@
 import { failAttachment } from '../scene/failAttachment.js';
 
+/**
+ * Request a device from an adapter and fail the layer attachment on rejection.
+ *
+ * @param {GPUAdapter} adapter Adapter providing the device.
+ * @param {L.Layer} layer Layer being attached.
+ * @param {L.Map} map Map receiving the layer.
+ *
+ * @returns {Promise<GPUDevice>} The acquired device.
+ */
 export async function requestDevice(adapter, layer, map) {
   try {
     return await adapter.requestDevice();

package/src/gpu/showWebGPUWarning.js

@@ -1,3 +1,8 @@
+/**
+ * Show a single accessible WebGPU-unavailable warning in the map container.
+ *
+ * @param {L.Map} map Map receiving the warning.
+ */
 export function showWebGPUWarning(map) {
   const container = map.getContainer();
   if (container.querySelector('.leaflet-webgpu-warning')) return;

package/src/index.js

@@ -1,11 +1,9 @@
 import { L } from './globals/L.js';
 import { layerProto } from './globals/layerProto.js';
 import { removeLayer as sharedRemoveLayer } from './globals/removeLayer.js';
-
 import './camera/mapCamera.js';
 import './sunlight/initSunlight.js';
 import './walk/initWalk.js';
-
 import { layerLayerAdd } from './scene/addRegisteredLayer.js';
 import { layerInitialize } from './scene/layerInitialize.js';
 import { removeLayer } from './core/removeLayer.js';

package/src/layer-controls/README.md

@@ -0,0 +1,25 @@
+# Layer controls
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Manages layer control entry placement and loading or feature-count status.
+
+## Status follows the layer
+
+```mermaid
+flowchart LR
+  Progress["Progress event / source areas"] --> Count["Loaded + pending + errors"]
+  Count --> Status["Render layer status"]
+  Layer["Layer added"] --> Entry["Place status under control entry"]
+  Entry --> Changes["Reposition on layer changes"]
+  Changes --> Remove["Remove listener when layer leaves"]
+```
+
+Status reflects source progress, not GPU frame completion. Placement may fail
+when no layers control lists the layer; loading must remain independent of it.
+
+- [placeEntry.js](./placeEntry.js): place a layer entry.
+- [updateLayerCount.js](./updateLayerCount.js): update its status.
+- [renderLayerCount.js](./renderLayerCount.js): render loading and count information.
+
+Related: [scene](../scene/README.md), [sources](../sources/README.md).

package/src/layer-controls/layerControlInputId.js

@@ -1,11 +1,18 @@
-import { L } from '../globals/L.js';
-import { layerControlAddItem } from '../globals/layerControlAddItem.js';
-
-// Leaflet 2 stores layer associations on its control, not on the input.
-if (layerControlAddItem && !L.Control.Layers) L.LayersControl.prototype._addItem = addLayerControlInputId;
-
-export function addLayerControlInputId(entry) {
-  const label = layerControlAddItem.call(this, entry);
-  label.querySelector('.leaflet-control-layers-selector').layerId = L.Util.stamp(entry.layer);
-  return label;
-}
+import { L } from '../globals/L.js';
+import { layerControlAddItem } from '../globals/layerControlAddItem.js';
+
+// Leaflet 2 stores layer associations on its control, not on the input.
+if (layerControlAddItem && !L.Control.Layers) L.LayersControl.prototype._addItem = addLayerControlInputId;
+
+/**
+ * Add a layer-control item and attach its layer identifier to the selector.
+ *
+ * @param {Object} entry Layer-control entry.
+ *
+ * @returns {HTMLElement} The created label.
+ */
+export function addLayerControlInputId(entry) {
+  const label = layerControlAddItem.call(this, entry);
+  label.querySelector('.leaflet-control-layers-selector').layerId = L.Util.stamp(entry.layer);
+  return label;
+}

package/src/layer-controls/layerCountTitle.js

@@ -1,6 +1,16 @@
-import { modelUrlByLayer } from '../weakmaps/modelUrlByLayer.js';
-
-export function layerCountTitle(layer, formatted, pending, error) {
-  return error ? `Unable to load: ${typeof error === 'string' ? error : error.message}` :
-    `${formatted} loaded ${modelUrlByLayer.get(layer) ? 'models' : 'elements'} in the current area${pending ? `; ${pending} blocks loading` : ''}`;
-}
+import { modelUrlByLayer } from '../weakmaps/modelUrlByLayer.js';
+
+/**
+ * Format a loading error or a count description for a layer-control status.
+ *
+ * @param {L.Layer} layer Layer whose status is described.
+ * @param {string} formatted Formatted loaded count.
+ * @param {number} pending Number of blocks still loading.
+ * @param {Error|string} [error] Loading error, if any.
+ *
+ * @returns {string} Status title.
+ */
+export function layerCountTitle(layer, formatted, pending, error) {
+  return error ? `Unable to load: ${typeof error === 'string' ? error : error.message}` :
+    `${formatted} loaded ${modelUrlByLayer.get(layer) ? 'models' : 'elements'} in the current area${pending ? `; ${pending} blocks loading` : ''}`;
+}

package/src/layer-controls/placeEntry.js

@@ -2,6 +2,15 @@ import { L } from '../globals/L.js';
 import { placeEntryElement } from './placeEntryElement.js';
 import './layerControlInputId.js';
 
+/**
+ * Find a layers-control entry containing the layer and place an element beside it.
+ *
+ * @param {L.Map} map Map containing the layers control.
+ * @param {L.Layer} layer Layer to locate.
+ * @param {HTMLElement} element Element to place.
+ *
+ * @returns {boolean} Whether a matching entry was found.
+ */
 export function placeEntry(map, layer, element) {
   let input, entry;
   for (input of map.getContainer().querySelectorAll('.leaflet-control-layers-selector')) {

package/src/layer-controls/placeEntryElement.js

@@ -1,22 +1,29 @@
-import { L } from '../globals/L.js';
-
-export function placeEntryElement(input, layer, element) {
-  const label = input.closest('label');
-  if (element.classList.contains('layer-count')) {
-    if (!input.hasAttribute('aria-label')) input.setAttribute('aria-label', label.textContent.trim());
-    element.id = `leaflet-layer-count-${L.Util.stamp(layer)}`;
-    input.setAttribute('aria-describedby', element.id);
-    label.append(element);
-  }
-  else if (element.classList.contains('traffic-status')) {
-    let group = label.nextElementSibling;
-    if (!group?.classList.contains('traffic-status-group')) {
-      group = L.DomUtil.create('div', 'traffic-status-group');
-      group.style.cssText = 'display:flex;flex-wrap:wrap;gap:4px 8px;max-width:200px;margin:2px 0 6px 20px;';
-      group.setAttribute('role', 'group');
-      group.setAttribute('aria-label', 'Traffic counts');
-      label.after(group);
-    }
-    group.append(element);
-  } else label.after(element);
-}
+import { L } from '../globals/L.js';
+
+/**
+ * Place a count, traffic status or other element next to a layer selector.
+ *
+ * @param {HTMLInputElement} input Layers-control selector.
+ * @param {L.Layer} layer Layer associated with the selector.
+ * @param {HTMLElement} element Element to place.
+ */
+export function placeEntryElement(input, layer, element) {
+  const label = input.closest('label');
+  if (element.classList.contains('layer-count')) {
+    if (!input.hasAttribute('aria-label')) input.setAttribute('aria-label', label.textContent.trim());
+    element.id = `leaflet-layer-count-${L.Util.stamp(layer)}`;
+    input.setAttribute('aria-describedby', element.id);
+    label.append(element);
+  }
+  else if (element.classList.contains('traffic-status')) {
+    let group = label.nextElementSibling;
+    if (!group?.classList.contains('traffic-status-group')) {
+      group = L.DomUtil.create('div', 'traffic-status-group');
+      group.style.cssText = 'display:flex;flex-wrap:wrap;gap:4px 8px;max-width:200px;margin:2px 0 6px 20px;';
+      group.setAttribute('role', 'group');
+      group.setAttribute('aria-label', 'Traffic counts');
+      label.after(group);
+    }
+    group.append(element);
+  } else label.after(element);
+}

package/src/layer-controls/placeUnderEntry.js

@@ -1,5 +1,12 @@
 import { placeEntry } from './placeEntry.js';
 
+/**
+ * Place a tracked element under its layer entry and notify its placement callback.
+ *
+ * @param {Object} state Placement state.
+ *
+ * @returns {boolean} Whether a matching entry was found.
+ */
 export function placeUnderEntry(state) {
   const nested = placeEntry(state.map, state.layer, state.element);
   const onPlace = state.onPlace;

package/src/layer-controls/removeEntry.js

@@ -1,5 +1,6 @@
 import { replaceEntry } from './replaceEntry.js';
 
+/** Remove the tracked element, its map listener and any empty traffic status group. */
 export function removeEntry() {
   this.map.off('layeradd layerremove', replaceEntry, this);
   const group = this.element.parentElement;

package/src/layer-controls/renderLayerCount.js

@@ -1,20 +1,28 @@
-import { countStatusByLayer } from '../weakmaps/countStatusByLayer.js';
-import { modelUrlByLayer } from '../weakmaps/modelUrlByLayer.js';
-import { modelByLayer } from '../weakmaps/modelByLayer.js';
-import { headerByLayer } from '../weakmaps/headerByLayer.js';
-import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
-
-export function renderLayerCount(layer, count, pending, error) {
-  const status = countStatusByLayer.get(layer);
-  const modelUrl = modelUrlByLayer.get(layer), model = modelByLayer.get(layer);
-  if (modelUrl) count = model ? 1 : 0;
-  const loading = pending || (modelUrl ? !model : !headerByLayer.get(layer) && !geojsonByLayer.get(layer));
-  const formatted = count.toLocaleString('en-US');
-  const text = error ? 'Error' : `${formatted}${loading ? '…' : ''}`;
-  const title = layerCountTitle(layer, formatted, pending, error);
-  if (status.textContent !== text) status.textContent = text;
-  if (status.title !== title) status.title = title;
-  if (error && status.getAttribute('role') !== 'alert') status.setAttribute('role', 'alert');
-  else if (!error && status.hasAttribute('role')) status.removeAttribute('role');
-}
-import { layerCountTitle } from './layerCountTitle.js';
+import { countStatusByLayer } from '../weakmaps/countStatusByLayer.js';
+import { modelUrlByLayer } from '../weakmaps/modelUrlByLayer.js';
+import { modelByLayer } from '../weakmaps/modelByLayer.js';
+import { headerByLayer } from '../weakmaps/headerByLayer.js';
+import { geojsonByLayer } from '../weakmaps/geojsonByLayer.js';
+import { layerCountTitle } from './layerCountTitle.js';
+
+/**
+ * Update a layer count's text, title and error accessibility state.
+ *
+ * @param {L.Layer} layer Layer whose count is displayed.
+ * @param {number} count Number of loaded elements.
+ * @param {number} pending Number of blocks still loading.
+ * @param {Error|string} [error] Loading error, if any.
+ */
+export function renderLayerCount(layer, count, pending, error) {
+  const status = countStatusByLayer.get(layer);
+  const modelUrl = modelUrlByLayer.get(layer), model = modelByLayer.get(layer);
+  if (modelUrl) count = model ? 1 : 0;
+  const loading = pending || (modelUrl ? !model : !headerByLayer.get(layer) && !geojsonByLayer.get(layer));
+  const formatted = count.toLocaleString('en-US');
+  const text = error ? 'Error' : `${formatted}${loading ? '…' : ''}`;
+  const title = layerCountTitle(layer, formatted, pending, error);
+  if (status.textContent !== text) status.textContent = text;
+  if (status.title !== title) status.title = title;
+  if (error && status.getAttribute('role') !== 'alert') status.setAttribute('role', 'alert');
+  else if (!error && status.hasAttribute('role')) status.removeAttribute('role');
+}

package/src/layer-controls/replaceEntry.js

@@ -1,8 +1,7 @@
 import { pendingPlacements } from '../globals/pendingPlacements.js';
-
-
 import { runPlacements } from './runPlacements.js';
 
+/** Queue this tracked layer-control element for placement in a microtask. */
 export function replaceEntry() {
   pendingPlacements.push(this);
   queueMicrotask(runPlacements);

package/src/layer-controls/runPlacements.js

@@ -1,8 +1,7 @@
 import { pendingPlacements } from '../globals/pendingPlacements.js';
-
-
 import { placeUnderEntry } from './placeUnderEntry.js';
 
+/** Place the next queued element if its layer is still on the map. */
 export function runPlacements() {
   const state = pendingPlacements.shift();
   if (state?.map.hasLayer(state.layer)) placeUnderEntry(state);

package/src/layer-controls/underEntry.js

@@ -5,9 +5,13 @@ import { removeEntry } from './removeEntry.js';
 
 /**
  * Keeps `element` right under `layer`'s entry in the map's layers control while the layer is on the map.
- * Returns false when no layers control lists the layer.
+ *
+ * @param {L.Layer} layer Layer whose entry should contain the element.
+ * @param {HTMLElement} element Element to place.
+ * @param {Function} [onPlace] Callback receiving whether placement succeeded.
+ *
+ * @returns {boolean} False when no layers control lists the layer.
  */
-
 export function underEntry(layer, element, onPlace) {
   const state = /* alloc */ { map: layer._map, layer, element, onPlace };
   state.map.on('layeradd layerremove', replaceEntry, state);

package/src/layer-controls/updateLayerCount.js

@@ -1,9 +1,13 @@
 import { areasByLayer } from '../weakmaps/areasByLayer.js';
 import { countStatusByLayer } from '../weakmaps/countStatusByLayer.js';
-
 import { underEntry } from './underEntry.js';
 import { renderLayerCount } from './renderLayerCount.js';
 
+/**
+ * Collect loaded and pending counts from an event or layer areas and refresh the status.
+ *
+ * @param {Object} event Layer event containing the target and optional loading counts.
+ */
 export function updateLayerCount(event) {
   const layer = event.target, status = countStatusByLayer.get(layer)
   if (!layer._map) return;