@tileflow/core 0.1.0-alpha.47 → 0.1.0-alpha.48

package/dist/runtime.js

@@ -488,6 +488,18 @@ function planTileflowThemeBlend(styles, options = {}) {
     }
   }
 }
+function mixTileflowColours(from, to, t) {
+  const a = oklab(from);
+  const b = oklab(to);
+  if (!a || !b) return void 0;
+  const alpha = a[3] + (b[3] - a[3]) * t;
+  if (alpha <= 0) return "rgba(0, 0, 0, 0)";
+  const channels = a.slice(0, 3).map((value, channel) => {
+    const from2 = value * a[3];
+    return (from2 + (b[channel] * b[3] - from2) * t) / alpha;
+  });
+  return colourFromOklab([...channels, alpha]);
+}
 function fillLayer(layer, position, dominant, layerSwitches) {
   const filled = { ...layer };
   for (const group of ["layout", "paint"]) {
@@ -531,10 +543,7 @@ function mixLeaf(values, position) {
   if (t <= 0 || from === to) return from;
   if (t >= 1) return to;
   if (typeof from === "number" && typeof to === "number") return from + (to - from) * t;
-  const a = oklab(String(from));
-  const b = oklab(String(to));
-  if (!a || !b) return t < 0.5 ? from : to;
-  return colourFromOklab(a.map((value, channel) => value + (b[channel] - value) * t));
+  return mixTileflowColours(String(from), String(to), t) ?? (t < 0.5 ? from : to);
 }
 function clampPosition(position, themes) {
   if (!Number.isFinite(position)) return 0;
@@ -3253,49 +3262,6 @@ function fail(message) {
   throw new TypeError(`Tileflow style family: ${message}`);
 }
 
-// src/style-family-loader.ts
-async function loadTileflowStyleFamily(url, options = {}) {
-  const request = options.fetch ?? globalThis.fetch.bind(globalThis);
-  const response = await request(url, { credentials: "same-origin", signal: options.signal });
-  if (!response.ok) throw new Error(`Tileflow style family request failed: ${response.status}`);
-  const maximum = tileflowStyleFamilyLimits.documentBytes;
-  const length = response.headers.get("content-length");
-  if (length && Number(length) > maximum) {
-    await response.body?.cancel();
-    throw new TypeError("Tileflow style family is too large.");
-  }
-  const reader = response.body?.getReader();
-  if (!reader) throw new TypeError("Tileflow style family response has no body.");
-  const chunks = [];
-  let total = 0;
-  try {
-    for (; ; ) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      total += value.byteLength;
-      if (total > maximum) {
-        await reader.cancel();
-        throw new TypeError("Tileflow style family is too large.");
-      }
-      chunks.push(value);
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  const bytes2 = new Uint8Array(total);
-  let offset = 0;
-  for (const chunk of chunks) {
-    bytes2.set(chunk, offset);
-    offset += chunk.length;
-  }
-  return parseTileflowStyleFamily(
-    JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes2))
-  );
-}
-
-// src/color-program-runtime.ts
-init_color_program();
-
 // src/themes/index.ts
 init_color_program();
 init_model();
@@ -3362,7 +3328,271 @@ function rgbToHex(r, g, b) {
   return `#${[r, g, b].map((value) => value.toString(16).padStart(2, "0")).join("")}`;
 }
 
+// src/overlays.ts
+init_portable_identity_rules();
+var tileflowOverlayPlacements = [
+  "above-water",
+  "below-roads",
+  "above-roads",
+  "above-buildings",
+  "below-labels",
+  "above-labels"
+];
+var tileflowClusterMetadataKey = "tileflow:cluster";
+function geojsonSource(options = {}) {
+  const data = options.data ?? { features: [], type: "FeatureCollection" };
+  if (typeof data === "string") {
+    if (!isHttpsUrl(data)) {
+      throw new Error("Tileflow GeoJSON source URLs must be absolute https:// URLs.");
+    }
+  } else if (!isPlainRecord3(data) || data.type !== "FeatureCollection" || !Array.isArray(data.features)) {
+    throw new Error("Tileflow GeoJSON source data must be a FeatureCollection or an https:// URL.");
+  }
+  assertClusterOptions(options);
+  const attribution = options.attribution?.trim();
+  return Object.freeze({
+    ...attribution ? { attribution } : {},
+    ...pickClusterOptions(options),
+    data: typeof data === "string" ? data : Object.freeze(cloneJson2(data)),
+    kind: "geojson"
+  });
+}
+function maplibreOverlay(options) {
+  if (!isTileflowPortableId(options.source)) {
+    throw new Error(`Invalid Tileflow overlay source ID: ${options.source}.`);
+  }
+  if (!tileflowOverlayPlacements.includes(options.placement)) {
+    throw new Error(`Invalid Tileflow overlay placement: ${String(options.placement)}.`);
+  }
+  if (!Array.isArray(options.layers) || options.layers.length < 1) {
+    throw new Error("Tileflow MapLibre overlays require at least one layer.");
+  }
+  const layers = options.layers.map((layer, index) => {
+    if (!isPlainRecord3(layer)) {
+      throw new Error(`Tileflow overlay layer ${index} must be a plain object.`);
+    }
+    if (!isTileflowPortableId(layer.id)) {
+      throw new Error(`Invalid Tileflow overlay layer ID: ${String(layer.id)}.`);
+    }
+    if (layer.id === "tileflow" || layer.id.startsWith("tileflow-")) {
+      throw new Error(`Tileflow overlay layer ID is reserved: ${layer.id}.`);
+    }
+    if (typeof layer.type !== "string" || !layer.type) {
+      throw new Error(`Tileflow overlay layer ${layer.id} requires a MapLibre type.`);
+    }
+    if (Object.hasOwn(layer, "source")) {
+      throw new Error(
+        `Tileflow overlay layer ${layer.id} inherits its source from the overlay and must not declare source.`
+      );
+    }
+    return Object.freeze(cloneJson2(layer));
+  });
+  return Object.freeze({
+    kind: "maplibre-overlay",
+    layers: Object.freeze(layers),
+    placement: options.placement,
+    source: options.source
+  });
+}
+function clusterOverlay(options) {
+  const colors = options.colors ?? ["#2563eb", "#7c3aed", "#db2777"];
+  const radii = options.radii ?? [16, 22, 30];
+  const [low, high] = options.steps ?? [100, 750];
+  if (!(low > 0 && high > low) || !radii.every((radius) => radius > 0)) {
+    throw new Error("Tileflow cluster steps must increase and radii must be positive.");
+  }
+  const metadata = (role) => ({
+    [tileflowClusterMetadataKey]: {
+      expandOnClick: options.expandOnClick ?? true,
+      role
+    }
+  });
+  const step = (values) => [
+    "step",
+    ["get", "point_count"],
+    values[0],
+    low,
+    values[1],
+    high,
+    values[2]
+  ];
+  return maplibreOverlay({
+    layers: [
+      {
+        filter: ["has", "point_count"],
+        id: `${options.id}-clusters`,
+        metadata: metadata("cluster"),
+        paint: {
+          "circle-color": step(colors),
+          "circle-radius": step(radii),
+          "circle-stroke-color": "#ffffff",
+          "circle-stroke-width": 2
+        },
+        type: "circle"
+      },
+      {
+        filter: ["has", "point_count"],
+        id: `${options.id}-cluster-count`,
+        layout: {
+          "text-allow-overlap": true,
+          "text-field": ["get", "point_count_abbreviated"],
+          ...options.font ? { "text-font": [...options.font] } : {},
+          "text-ignore-placement": true,
+          "text-size": 13
+        },
+        metadata: metadata("count"),
+        paint: { "text-color": options.textColor ?? "#ffffff" },
+        type: "symbol"
+      },
+      {
+        filter: ["!", ["has", "point_count"]],
+        id: `${options.id}-points`,
+        metadata: metadata("point"),
+        paint: {
+          "circle-color": options.pointColor ?? colors[0],
+          "circle-radius": 6,
+          "circle-stroke-color": "#ffffff",
+          "circle-stroke-width": 1.5
+        },
+        type: "circle"
+      }
+    ],
+    placement: options.placement,
+    source: options.source
+  });
+}
+function heatmapOverlay(options) {
+  const colors = options.colors ?? [
+    [0, "rgba(33, 102, 172, 0)"],
+    [0.2, "#67a9cf"],
+    [0.4, "#d1e5f0"],
+    [0.6, "#fddbc7"],
+    [0.8, "#ef8a62"],
+    [1, "#b2182b"]
+  ];
+  if (colors.length < 2 || colors.some(([density], index) => {
+    const previous = colors[index - 1]?.[0] ?? -1;
+    return !(density >= 0 && density <= 1 && density > previous);
+  })) {
+    throw new Error("Tileflow heatmap colors need at least two increasing densities from 0 to 1.");
+  }
+  const paint = {
+    "heatmap-color": ["interpolate", ["linear"], ["heatmap-density"], ...colors.flat()],
+    "heatmap-intensity": options.intensity ?? 1,
+    "heatmap-opacity": options.opacity ?? 0.8,
+    "heatmap-radius": options.radius ?? 30,
+    "heatmap-weight": options.weight ?? 1
+  };
+  return maplibreOverlay({
+    layers: [
+      {
+        id: options.id,
+        ...options.maxZoom === void 0 ? {} : { maxzoom: options.maxZoom },
+        paint,
+        ...options.sourceLayer === void 0 ? {} : { "source-layer": options.sourceLayer },
+        type: "heatmap"
+      }
+    ],
+    placement: options.placement,
+    source: options.source
+  });
+}
+function pickClusterOptions(source) {
+  return {
+    ...source.cluster === void 0 ? {} : { cluster: source.cluster },
+    ...source.clusterMaxZoom === void 0 ? {} : { clusterMaxZoom: source.clusterMaxZoom },
+    ...source.clusterMinPoints === void 0 ? {} : { clusterMinPoints: source.clusterMinPoints },
+    ...source.clusterProperties === void 0 ? {} : { clusterProperties: cloneJson2(source.clusterProperties) },
+    ...source.clusterRadius === void 0 ? {} : { clusterRadius: source.clusterRadius }
+  };
+}
+function assertClusterOptions(options) {
+  const { cluster, clusterMaxZoom, clusterMinPoints, clusterProperties, clusterRadius } = options;
+  if (cluster !== void 0 && typeof cluster !== "boolean") {
+    throw new Error("Tileflow GeoJSON cluster must be a boolean.");
+  }
+  if (clusterRadius !== void 0 && !(Number.isFinite(clusterRadius) && clusterRadius > 0)) {
+    throw new Error("Tileflow clusterRadius must be a positive number of pixels.");
+  }
+  if (clusterMaxZoom !== void 0 && !(Number.isFinite(clusterMaxZoom) && clusterMaxZoom >= 0 && clusterMaxZoom <= 24)) {
+    throw new Error("Tileflow clusterMaxZoom must be a zoom from 0 to 24.");
+  }
+  if (clusterMinPoints !== void 0 && !(Number.isInteger(clusterMinPoints) && clusterMinPoints >= 2)) {
+    throw new Error("Tileflow clusterMinPoints must be an integer of at least 2.");
+  }
+  if (!cluster && [clusterMaxZoom, clusterMinPoints, clusterProperties, clusterRadius].some(
+    (value) => value !== void 0
+  )) {
+    throw new Error("Tileflow cluster options require cluster: true.");
+  }
+  for (const [name, value] of Object.entries(clusterProperties ?? {})) {
+    if (!Array.isArray(value) || value.length !== 2) {
+      throw new Error(`Tileflow clusterProperties.${name} must be [operator, mapExpression].`);
+    }
+  }
+}
+function isHttpsUrl(value) {
+  try {
+    return new URL(value).protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+function cloneJson2(value) {
+  if (Array.isArray(value)) return value.map(cloneJson2);
+  if (!isPlainRecord3(value)) return value;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [key, cloneJson2(child)])
+  );
+}
+function isPlainRecord3(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+// src/style-family-loader.ts
+async function loadTileflowStyleFamily(url, options = {}) {
+  const request = options.fetch ?? globalThis.fetch.bind(globalThis);
+  const response = await request(url, { credentials: "same-origin", signal: options.signal });
+  if (!response.ok) throw new Error(`Tileflow style family request failed: ${response.status}`);
+  const maximum = tileflowStyleFamilyLimits.documentBytes;
+  const length = response.headers.get("content-length");
+  if (length && Number(length) > maximum) {
+    await response.body?.cancel();
+    throw new TypeError("Tileflow style family is too large.");
+  }
+  const reader = response.body?.getReader();
+  if (!reader) throw new TypeError("Tileflow style family response has no body.");
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      total += value.byteLength;
+      if (total > maximum) {
+        await reader.cancel();
+        throw new TypeError("Tileflow style family is too large.");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const bytes2 = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes2.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return parseTileflowStyleFamily(
+    JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes2))
+  );
+}
+
 // src/color-program-runtime.ts
+init_color_program();
 init_model();
 function applyTileflowColorOverrides(style, overrides) {
   const keys = Object.keys(overrides);
@@ -4452,18 +4682,22 @@ export {
   applyTileflowColorOverrides,
   assertValidTileflowRuntimeSource,
   clearTileflowManifestCache,
+  clusterOverlay,
   createTileflowSessionController,
   createTileflowSessionId,
   defaultTileflowManifestUrl,
   defaultTileflowRuntimeView,
   expandTileflowFamilyTemplate,
+  geojsonSource,
   getTileflowAnalyticsApiUrl,
   getTileflowStyleFontFaces,
+  heatmapOverlay,
   inferTileflowAnalyticsFromStyleUrl,
   isTileflowTimeOfDay,
   loadTileflowManifest,
   loadTileflowRuntimeAppearance,
   loadTileflowStyleFamily,
+  maplibreOverlay,
   materializeTileflowStyleFamily,
   mergeTileflowAnalytics,
   nearestTileflowBlendTheme,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tileflow/core",
-  "version": "0.1.0-alpha.47",
+  "version": "0.1.0-alpha.48",
   "license": "Apache-2.0",
   "description": "Typed Tileflow config and MapLibre style compiler.",
   "type": "module",
@@ -25,6 +25,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "REFERENCE.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES.md"
   ],