leaflet-city-mapper 0.0.9 → 0.1.1

package/src/triangulation/on.js

@@ -1,4 +1,13 @@
-export function on(p, q, r) {
-  return Math.min(p.x, q.x) <= r.x && r.x <= Math.max(p.x, q.x) &&
-    Math.min(p.y, q.y) <= r.y && r.y <= Math.max(p.y, q.y);
-}
+/**
+ * Check whether a point lies within a segment's axis-aligned bounding box.
+ *
+ * @param {Object} p First segment endpoint.
+ * @param {Object} q Second segment endpoint.
+ * @param {Object} r Point to test.
+ *
+ * @returns {boolean} Whether the point lies within the bounds.
+ */
+export function on(p, q, r) {
+  return Math.min(p.x, q.x) <= r.x && r.x <= Math.max(p.x, q.x) &&
+    Math.min(p.y, q.y) <= r.y && r.y <= Math.max(p.y, q.y);
+}

package/src/triangulation/polygonRings.js

@@ -1,14 +1,22 @@
-import { clean } from './clean.js';
-import { isClockWise } from './isClockWise.js';
-
-export function polygonRings(paths, vertices) {
-  const rings = /* alloc */ [];
-  let offset = 0, index, path, ring;
-  for (index = 0; index < paths.length; index++) {
-    path = paths[index];
-    ring = clean(vertices.slice(offset, offset += path.length));
-    if (isClockWise(ring) !== Boolean(index)) ring.reverse();
-    rings.push(ring);
-  }
-  return rings;
-}
+import { clean } from './clean.js';
+import { isClockWise } from './isClockWise.js';
+
+/**
+ * Split indexed vertices into cleaned rings and normalize outer and hole winding.
+ *
+ * @param {Object[][]} paths Original polygon paths defining ring lengths.
+ * @param {Object[]} vertices Indexed vertices corresponding to the paths.
+ *
+ * @returns {Object[][]} Cleaned rings with normalized winding.
+ */
+export function polygonRings(paths, vertices) {
+  const rings = /* alloc */ [];
+  let offset = 0, index, path, ring;
+  for (index = 0; index < paths.length; index++) {
+    path = paths[index];
+    ring = clean(vertices.slice(offset, offset += path.length));
+    if (isClockWise(ring) !== Boolean(index)) ring.reverse();
+    rings.push(ring);
+  }
+  return rings;
+}

package/src/triangulation/sortHoles.js

@@ -1,6 +1,13 @@
 import { minimumX } from './minimumX.js';
 import { mergeHoles } from './mergeHoles.js';
 
+/**
+ * Stably sort hole rings in place by their minimum x coordinate.
+ *
+ * @param {Object[][]} holes Hole rings.
+ *
+ * @returns {Object[][]} The supplied array of sorted holes.
+ */
 export function sortHoles(holes) {
   if (holes.length < 2) return holes;
   const buffer = /* alloc */ new Array(holes.length);

package/src/triangulation/triangulate.js

@@ -5,18 +5,19 @@ import { connectHole } from './connectHole.js';
 import { clipEars } from './clipEars.js';
 import { validateArea } from './validateArea.js';
 
-
 /**
  * Triangulates a polygon given as `{x, y}` points.
  * Rings omit the repeated closing point; winding is normalized internally.
  * Vertex indices remain relative to the original inputs after duplicate/collinear
  * cleanup. Hole bridges duplicate endpoints, not source vertices.
+ *
  * @param {Object[]} contour Outer boundary.
  * @param {Object[][]} [holes] Interior boundaries.
  *
  * @returns {number[][]} Triangles as indices in `[...contour, ...holes.flat()]`.
+ *
+ * @throws {Error} If a polygon coordinate is not finite.
  */
-
 export function triangulate(contour, holes = geometryEmpty) {
   const paths = /* alloc */ [contour, ...holes];
   const points = paths.flat();

package/src/triangulation/validateArea.js

@@ -1,10 +1,19 @@
-import { area } from './area.js';
-import { cross } from './cross.js';
-
-export function validateArea(rings, vertices, result) {
-  let holeArea = 0, actual = 0, i, triangle;
-  for (i = 1; i < rings.length; i++) holeArea += area(rings[i]);
-  const expected = area(rings[0]) - holeArea;
-  for (triangle of result) actual += cross(vertices[triangle[0]], vertices[triangle[1]], vertices[triangle[2]]) / 2;
-  if (expected <= 0 || Math.abs(actual - expected) > Math.max(1e-7, expected * 1e-8)) throw /* alloc */ new Error('Polygon triangulation area mismatch');
-}
+import { area } from './area.js';
+import { cross } from './cross.js';
+
+/**
+ * Check that triangle area matches the outer ring area minus its holes.
+ *
+ * @param {Object[][]} rings Outer ring followed by hole rings.
+ * @param {Object[]} vertices Indexed planar vertices.
+ * @param {number[][]} result Triangles of vertex indices.
+ *
+ * @throws {Error} If the expected area is nonpositive or the triangle area differs.
+ */
+export function validateArea(rings, vertices, result) {
+  let holeArea = 0, actual = 0, i, triangle;
+  for (i = 1; i < rings.length; i++) holeArea += area(rings[i]);
+  const expected = area(rings[0]) - holeArea;
+  for (triangle of result) actual += cross(vertices[triangle[0]], vertices[triangle[1]], vertices[triangle[2]]) / 2;
+  if (expected <= 0 || Math.abs(actual - expected) > Math.max(1e-7, expected * 1e-8)) throw /* alloc */ new Error('Polygon triangulation area mismatch');
+}

package/src/utils/README.md

@@ -0,0 +1,16 @@
+# Utilities
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Small shared helpers for ordering, wrapping values and yielding asynchronous work.
+
+## When to use these helpers
+
+`wrap` is specific to angles in radians, not arbitrary ranges. After
+`yieldTask`, callers must recheck cancellation or revisions.
+
+- [compareDistance.js](./compareDistance.js): compare items by distance.
+- [wrap.js](./wrap.js): wrap an angle between negative and positive pi.
+- [yieldTask.js](./yieldTask.js): yield to a timer.
+
+Related: [globals](../globals/README.md), [sources](../sources/README.md).

package/src/utils/compareDistance.js

@@ -1,3 +1,11 @@
-export function compareDistance(a, b) {
-  return a.distance - b.distance;
-}
+/**
+ * Compare objects by ascending distance.
+ *
+ * @param {Object} a First object with a distance.
+ * @param {Object} b Second object with a distance.
+ *
+ * @returns {number} Signed distance difference.
+ */
+export function compareDistance(a, b) {
+  return a.distance - b.distance;
+}

package/src/utils/noOperation.js

@@ -1 +1,2 @@
+/** Do nothing when a callback is required. */
 export function noOperation() {}

package/src/utils/wrap.js

@@ -1,3 +1,10 @@
+/**
+ * Wrap an angle to the range from negative pi to pi.
+ *
+ * @param {number} angle Angle in radians.
+ *
+ * @returns {number} Wrapped angle in radians.
+ */
 export function wrap(angle) {
   return Math.atan2(Math.sin(angle), Math.cos(angle));
 }

package/src/utils/yieldTask.js

@@ -1,5 +1,12 @@
-export function yieldTask(delay = 0) {
-  const task = Promise.withResolvers();
-  setTimeout(task.resolve, delay);
-  return task.promise;
-}
+/**
+ * Yield to a timer before continuing asynchronous work.
+ *
+ * @param {number} [delay=0] Timer delay in milliseconds.
+ *
+ * @returns {Promise<void>} Resolves when the timer fires.
+ */
+export function yieldTask(delay = 0) {
+  const task = Promise.withResolvers();
+  setTimeout(task.resolve, delay);
+  return task.promise;
+}

package/src/vector-style/README.md

@@ -0,0 +1,27 @@
+# Vector styles
+
+[Source guide](../README.md) | [Project README](../../README.md)
+
+Parses and validates vector style layers, evaluates supported expressions and
+translates paint values for vector tile rendering.
+
+## Style input and evaluation
+
+```mermaid
+flowchart LR
+  Text["JSON / otm_layers text"] --> Clean["Remove comments + trailing commas"]
+  Clean --> Parse["JSON parse + validate layers"]
+  Parse --> Match["Match style and source layers"]
+  Match --> Evaluate["Evaluate expressions: properties + zoom"]
+  Evaluate --> Paint["Resolve fill / line paint"]
+  Paint --> Tile["Vector tile presentation"]
+```
+
+Parsing does not execute arbitrary JavaScript. Only supported expression
+operators are evaluated; non-array values pass through unchanged.
+
+- [parseVectorStyle.js](./parseVectorStyle.js): parse and validate style source.
+- [evaluateStyle.js](./evaluateStyle.js): evaluate style expressions.
+- [vectorPaint.js](./vectorPaint.js): derive paint values.
+
+Related: [vector-tiles](../vector-tiles/README.md), [colors](../colors/README.md), [mvt](../mvt/README.md).

package/src/vector-style/appendQuotedStyleCharacter.js

@@ -1,22 +1,30 @@
-export function appendQuotedStyleCharacter(char, state) {
-  if (state.quoted) {
-    if (state.escaped) {
-      state.escaped = false;
-      return char === "'" ? char : '\\' + char;
-    }
-    if (char === '\\') {
-      state.escaped = true;
-      return '';
-    }
-    if (char === state.quoted) {
-      state.quoted = '';
-      return '"';
-    }
-    return char === '"' ? '\\"' : char;
-  }
-  if (char === '"' || char === "'") {
-    state.quoted = char;
-    return '"';
-  }
-  return undefined;
-}
+/**
+ * Convert one quoted style character to JSON form while updating quote and escape state.
+ *
+ * @param {string} char Current character.
+ * @param {Object} state Mutable quoted and escaped state.
+ *
+ * @returns {string|undefined} Converted text, or undefined outside a quoted string.
+ */
+export function appendQuotedStyleCharacter(char, state) {
+  if (state.quoted) {
+    if (state.escaped) {
+      state.escaped = false;
+      return char === "'" ? char : '\\' + char;
+    }
+    if (char === '\\') {
+      state.escaped = true;
+      return '';
+    }
+    if (char === state.quoted) {
+      state.quoted = '';
+      return '"';
+    }
+    return char === '"' ? '\\"' : char;
+  }
+  if (char === '"' || char === "'") {
+    state.quoted = char;
+    return '"';
+  }
+  return undefined;
+}

package/src/vector-style/arrayContainsRange.js

@@ -1,8 +1,18 @@
-export function arrayContainsRange(values, start, end, target) {
-  let i = 0, value = null;
-  for (i = start; i < end; i++) {
-    value = values[i];
-    if (value === target || (value !== value && target !== target)) return true;
-  }
-  return false;
-}
+/**
+ * Check a slice for a value, treating NaN as equal to NaN.
+ *
+ * @param {Array} values Input values.
+ * @param {number} start Inclusive start index.
+ * @param {number} end Exclusive end index.
+ * @param {*} target Value to find.
+ *
+ * @returns {boolean} Whether the value occurs in the slice.
+ */
+export function arrayContainsRange(values, start, end, target) {
+  let i = 0, value = null;
+  for (i = start; i < end; i++) {
+    value = values[i];
+    if (value === target || (value !== value && target !== target)) return true;
+  }
+  return false;
+}

package/src/vector-style/evaluateBoolean.js

@@ -1,18 +1,31 @@
-import { evaluateStyle } from './evaluateStyle.js';
-
-export function evaluateBoolean(op, args, properties, zoom, legacy) {
-  let i = 0;
-  if (op === 'all') {
-    for (i = 0; i < args.length; i++) {
-      if (!evaluateStyle(args[i], properties, zoom, legacy)) return false;
-    }
-    return true;
-  }
-  if (op === 'any') {
-    for (i = 0; i < args.length; i++) {
-      if (evaluateStyle(args[i], properties, zoom, legacy)) return true;
-    }
-    return false;
-  }
-  throw /* alloc */ new Error(`Unsupported vector style expression: ${op}`);
-}
+import { evaluateStyle } from './evaluateStyle.js';
+
+/**
+ * Evaluate a short-circuiting all or any style expression.
+ *
+ * @param {string} op Expression operator.
+ * @param {Array} args Expression operands.
+ * @param {Object} properties Feature properties.
+ * @param {number} zoom Current zoom.
+ * @param {boolean} legacy Whether to use legacy filter evaluation.
+ *
+ * @returns {boolean} Expression result.
+ *
+ * @throws {Error} If the operator is unsupported.
+ */
+export function evaluateBoolean(op, args, properties, zoom, legacy) {
+  let i = 0;
+  if (op === 'all') {
+    for (i = 0; i < args.length; i++) {
+      if (!evaluateStyle(args[i], properties, zoom, legacy)) return false;
+    }
+    return true;
+  }
+  if (op === 'any') {
+    for (i = 0; i < args.length; i++) {
+      if (evaluateStyle(args[i], properties, zoom, legacy)) return true;
+    }
+    return false;
+  }
+  throw /* alloc */ new Error(`Unsupported vector style expression: ${op}`);
+}

package/src/vector-style/evaluateCoalesceOrCase.js

@@ -1,21 +1,34 @@
-import { evaluateStyle } from './evaluateStyle.js';
-
-export function evaluateCoalesceOrCase(op, args, properties, zoom, legacy) {
-  let i = 0, result = null;
-  if (op === 'coalesce') {
-    for (i = 0; i < args.length; i++) {
-      result = evaluateStyle(args[i], properties, zoom);
-      if (result !== null && result !== undefined) return result;
-    }
-    return null;
-  }
-  if (op === 'case') {
-    for (i = 0; i < args.length - 1; i += 2) {
-      if (evaluateStyle(args[i], properties, zoom)) {
-        return evaluateStyle(args[i + 1], properties, zoom);
-      }
-    }
-    return evaluateStyle(args[args.length - 1], properties, zoom);
-  }
-  throw /* alloc */ new Error(`Unsupported vector style expression: ${op}`);
-}
+import { evaluateStyle } from './evaluateStyle.js';
+
+/**
+ * Evaluate a coalesce or case style expression.
+ *
+ * @param {string} op Expression operator.
+ * @param {Array} args Expression operands.
+ * @param {Object} properties Feature properties.
+ * @param {number} zoom Current zoom.
+ * @param {boolean} legacy Legacy filter flag.
+ *
+ * @returns {*} Selected expression result.
+ *
+ * @throws {Error} If the operator is unsupported.
+ */
+export function evaluateCoalesceOrCase(op, args, properties, zoom, legacy) {
+  let i = 0, result = null;
+  if (op === 'coalesce') {
+    for (i = 0; i < args.length; i++) {
+      result = evaluateStyle(args[i], properties, zoom);
+      if (result !== null && result !== undefined) return result;
+    }
+    return null;
+  }
+  if (op === 'case') {
+    for (i = 0; i < args.length - 1; i += 2) {
+      if (evaluateStyle(args[i], properties, zoom)) {
+        return evaluateStyle(args[i + 1], properties, zoom);
+      }
+    }
+    return evaluateStyle(args[args.length - 1], properties, zoom);
+  }
+  throw /* alloc */ new Error(`Unsupported vector style expression: ${op}`);
+}

package/src/vector-style/evaluateComparison.js

@@ -1,16 +1,29 @@
-import { evaluateInput } from './evaluateInput.js';
-import { evaluateStyle } from './evaluateStyle.js';
-
-export function evaluateComparison(op, args, properties, zoom, legacy) {
-  const left = evaluateInput(args[0], properties, zoom, legacy);
-  const right = evaluateStyle(args[1], properties, zoom);
-  switch (op) {
-    case '==': return left === right;
-    case '!=': return left !== right;
-    case '<=': return left <= right;
-    case '>=': return left >= right;
-    case '<': return left < right;
-    case '>': return left > right;
-      default: throw /* alloc */ new Error(`Unsupported vector style expression: ${op}`);
-  }
-}
+import { evaluateInput } from './evaluateInput.js';
+import { evaluateStyle } from './evaluateStyle.js';
+
+/**
+ * Evaluate a comparison between style expression operands.
+ *
+ * @param {string} op Comparison operator.
+ * @param {Array} args Expression operands.
+ * @param {Object} properties Feature properties.
+ * @param {number} zoom Current zoom.
+ * @param {boolean} legacy Whether the left operand is a legacy property name.
+ *
+ * @returns {boolean} Comparison result.
+ *
+ * @throws {Error} If the operator is unsupported.
+ */
+export function evaluateComparison(op, args, properties, zoom, legacy) {
+  const left = evaluateInput(args[0], properties, zoom, legacy);
+  const right = evaluateStyle(args[1], properties, zoom);
+  switch (op) {
+    case '==': return left === right;
+    case '!=': return left !== right;
+    case '<=': return left <= right;
+    case '>=': return left >= right;
+    case '<': return left < right;
+    case '>': return left > right;
+      default: throw /* alloc */ new Error(`Unsupported vector style expression: ${op}`);
+  }
+}

package/src/vector-style/evaluateIExpression.js

@@ -1,8 +1,21 @@
-import { evaluateInterpolate } from './evaluateInterpolate.js';
-import { evaluateMembership } from './evaluateMembership.js';
-
-export function evaluateIExpression(op, args, properties, zoom, legacy) {
-  if (op === 'in') return evaluateMembership(op, args, properties, zoom, legacy);
-  if (op === 'interpolate') return evaluateInterpolate(args, properties, zoom);
-  throw /* alloc */ new Error(`Unsupported vector style expression: ${op}`);
-}
+import { evaluateInterpolate } from './evaluateInterpolate.js';
+import { evaluateMembership } from './evaluateMembership.js';
+
+/**
+ * Dispatch an in or interpolate style expression.
+ *
+ * @param {string} op Expression operator.
+ * @param {Array} args Expression operands.
+ * @param {Object} properties Feature properties.
+ * @param {number} zoom Current zoom.
+ * @param {boolean} legacy Whether to use legacy membership semantics.
+ *
+ * @returns {*} Expression result.
+ *
+ * @throws {Error} If the operator is unsupported.
+ */
+export function evaluateIExpression(op, args, properties, zoom, legacy) {
+  if (op === 'in') return evaluateMembership(op, args, properties, zoom, legacy);
+  if (op === 'interpolate') return evaluateInterpolate(args, properties, zoom);
+  throw /* alloc */ new Error(`Unsupported vector style expression: ${op}`);
+}

package/src/vector-style/evaluateInput.js

@@ -1,6 +1,16 @@
-import { evaluateStyle } from './evaluateStyle.js';
-
-export function evaluateInput(value, properties, zoom, legacy) {
-  if (legacy && typeof value === 'string') return properties[value];
-  return evaluateStyle(value, properties, zoom);
-}
+import { evaluateStyle } from './evaluateStyle.js';
+
+/**
+ * Evaluate an input or resolve a legacy string operand as a property name.
+ *
+ * @param {*} value Input value or expression.
+ * @param {Object} properties Feature properties.
+ * @param {number} zoom Current zoom.
+ * @param {boolean} legacy Whether string values name properties.
+ *
+ * @returns {*} Evaluated input.
+ */
+export function evaluateInput(value, properties, zoom, legacy) {
+  if (legacy && typeof value === 'string') return properties[value];
+  return evaluateStyle(value, properties, zoom);
+}

package/src/vector-style/evaluateInterpolate.js

@@ -1,27 +1,36 @@
-import { styleColor } from './styleColor.js';
-import { evaluateStyle } from './evaluateStyle.js';
-
-export function evaluateInterpolate(args, properties, zoom) {
-  const result = evaluateStyle(args[1], properties, zoom);
-  const base = args[0][0] === 'exponential' ? args[0][1] : 1;
-  let i = 0, lower = 0, upper = 0, ratio = 0, left = null, right = null, j = 0, color = '';
-  if (result <= args[2]) return evaluateStyle(args[3], properties, zoom);
-  for (i = 4; i < args.length; i += 2) {
-    if (result > args[i]) continue;
-    lower = args[i - 2];
-    upper = args[i];
-    ratio = base === 1 ? (result - lower) / (upper - lower)
-      : (base ** (result - lower) - 1) / (base ** (upper - lower) - 1);
-    left = evaluateStyle(args[i - 1], properties, zoom);
-    right = evaluateStyle(args[i + 1], properties, zoom);
-    if (typeof left === 'number' && typeof right === 'number') return left + (right - left) * ratio;
-    left = styleColor(left);
-    right = styleColor(right);
-    for (j = 0; j < 3; j++) {
-      if (j) color += ',';
-      color += Math.round(left[j] + (right[j] - left[j]) * ratio);
-    }
-    return `rgba(${color},${left[3] + (right[3] - left[3]) * ratio})`;
-  }
-  return evaluateStyle(args.at(-1), properties, zoom);
-}
+import { styleColor } from './styleColor.js';
+import { evaluateStyle } from './evaluateStyle.js';
+
+/**
+ * Interpolate numeric or color style outputs between expression stops.
+ *
+ * @param {Array} args Interpolation mode, input and stops.
+ * @param {Object} properties Feature properties.
+ * @param {number} zoom Current zoom.
+ *
+ * @returns {*} Interpolated or endpoint value.
+ */
+export function evaluateInterpolate(args, properties, zoom) {
+  const result = evaluateStyle(args[1], properties, zoom);
+  const base = args[0][0] === 'exponential' ? args[0][1] : 1;
+  let i = 0, lower = 0, upper = 0, ratio = 0, left = null, right = null, j = 0, color = '';
+  if (result <= args[2]) return evaluateStyle(args[3], properties, zoom);
+  for (i = 4; i < args.length; i += 2) {
+    if (result > args[i]) continue;
+    lower = args[i - 2];
+    upper = args[i];
+    ratio = base === 1 ? (result - lower) / (upper - lower)
+      : (base ** (result - lower) - 1) / (base ** (upper - lower) - 1);
+    left = evaluateStyle(args[i - 1], properties, zoom);
+    right = evaluateStyle(args[i + 1], properties, zoom);
+    if (typeof left === 'number' && typeof right === 'number') return left + (right - left) * ratio;
+    left = styleColor(left);
+    right = styleColor(right);
+    for (j = 0; j < 3; j++) {
+      if (j) color += ',';
+      color += Math.round(left[j] + (right[j] - left[j]) * ratio);
+    }
+    return `rgba(${color},${left[3] + (right[3] - left[3]) * ratio})`;
+  }
+  return evaluateStyle(args.at(-1), properties, zoom);
+}

package/src/vector-style/evaluateMatch.js

@@ -1,12 +1,21 @@
-import { evaluateStyle } from './evaluateStyle.js';
-
-export function evaluateMatch(args, properties, zoom) {
-  const result = evaluateStyle(args[0], properties, zoom);
-  let i = 0, matched = false;
-  for (i = 1; i < args.length - 1; i += 2) {
-    if (Array.isArray(args[i])) matched = args[i].includes(result);
-    else matched = args[i] === result;
-    if (matched) return evaluateStyle(args[i + 1], properties, zoom);
-  }
-  return evaluateStyle(args[args.length - 1], properties, zoom);
-}
+import { evaluateStyle } from './evaluateStyle.js';
+
+/**
+ * Evaluate a match expression against scalar or array labels.
+ *
+ * @param {Array} args Input, labels, outputs and fallback.
+ * @param {Object} properties Feature properties.
+ * @param {number} zoom Current zoom.
+ *
+ * @returns {*} Matched output or fallback.
+ */
+export function evaluateMatch(args, properties, zoom) {
+  const result = evaluateStyle(args[0], properties, zoom);
+  let i = 0, matched = false;
+  for (i = 1; i < args.length - 1; i += 2) {
+    if (Array.isArray(args[i])) matched = args[i].includes(result);
+    else matched = args[i] === result;
+    if (matched) return evaluateStyle(args[i + 1], properties, zoom);
+  }
+  return evaluateStyle(args[args.length - 1], properties, zoom);
+}