@maplibre-yaml/core 0.2.1 → 0.3.0-alpha.0

package/dist/register.d.ts

@@ -1,5 +1,5 @@
 import { Map } from 'maplibre-gl';
-import { d as MapBlock, M as MapRenderer } from './map-renderer-SjO3KQmx.js';
+import { e as MapBlock, M as MapRenderer } from './map-renderer-4FF3EmBO.js';
 import './page.schema-Cad2FFqh.js';
 import 'zod';
 

package/dist/register.js

@@ -1,6 +1,6 @@
 import { parse } from 'yaml';
 import { z, ZodError } from 'zod';
-import { Map as Map$1, Popup, NavigationControl, GeolocateControl, ScaleControl, FullscreenControl } from 'maplibre-gl';
+import * as maplibre from 'maplibre-gl';
 
 // @maplibre-yaml/core - Declarative web maps with YAML
 
@@ -154,8 +154,30 @@ var GeoJSONSourceSchema = z.object({
   generateId: z.boolean().optional(),
   promoteId: z.union([z.string(), z.record(z.string())]).optional(),
   attribution: z.string().optional()
-}).passthrough().refine((data) => data.url || data.data || data.prefetchedData, {
-  message: 'GeoJSON source requires at least one of: url, data, or prefetchedData. Use "url" to fetch from an endpoint, "data" for inline GeoJSON, or "prefetchedData" for build-time fetched data.'
+}).passthrough().superRefine((d, ctx) => {
+  if (!d.url && !d.data && !d.prefetchedData) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'GeoJSON source requires at least one of: url, data, or prefetchedData. Use "url" to fetch from an endpoint, "data" for inline GeoJSON, or "prefetchedData" for build-time fetched data.'
+    });
+    return;
+  }
+  if (typeof d.data === "string" && /^(\.\.?|\/?src)\//.test(d.data)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["data"],
+      // Recommends `data: "/data/..."` rather than `url:` because the
+      // `url:` field is schema-validated with z.string().url(), which
+      // requires a fully-qualified URL (`https://...`) and rejects
+      // root-relative paths. MapLibre treats a string in `data:` as a
+      // URL and fetches it correctly. Until url: relaxes to accept
+      // root-relative paths (see follow-up), `data: "/path"` is the
+      // working pattern for files served from public/.
+      message: `GeoJSON source.data must be an inline GeoJSON object or a URL. "${d.data}" is a local source-directory path that won't resolve at runtime. Move the file to public/ and reference the public-served URL:
+  data: "/data/<filename>.geojson"
+(\`url:\` requires a fully-qualified https:// URL and won't accept root-relative paths; use \`data:\` for runtime URLs to public assets.)`
+    });
+  }
 });
 var VectorSourceSchema = z.object({
   type: z.literal("vector").describe("Source type"),
@@ -1022,6 +1044,95 @@ var YAMLParser = class {
       };
     }
   }
+  /**
+   * Detect the document type of a YAML string and validate it against the
+   * matching schema
+   *
+   * @param yaml - YAML string to parse (a map block, a scrollytelling block, or a root document)
+   * @returns Discriminated result with the detected block type and the corresponding safeParse result
+   *
+   * @remarks
+   * Dispatches on the document's top-level `type:` field:
+   *
+   * - `type: map` → {@link safeParseMapBlock}
+   * - `type: scrollytelling` → {@link safeParseScrollytellingBlock}
+   * - no `type:` but a `pages:` key → {@link safeParse} (root document)
+   *
+   * Any other `type:` value produces a failure result listing the valid
+   * values, as does a document that has neither `type:` nor `pages:`.
+   * This method never throws.
+   *
+   * @example
+   * ```typescript
+   * const { blockType, result } = YAMLParser.safeParseAny(yamlString);
+   * if (!result.success) {
+   *   result.errors.forEach(err => console.error(`${err.path}: ${err.message}`));
+   * } else if (blockType === 'map') {
+   *   renderMap(result.data);
+   * }
+   * ```
+   */
+  static safeParseAny(yaml) {
+    let parsed;
+    try {
+      parsed = parse(yaml);
+    } catch (error) {
+      return {
+        blockType: "unknown",
+        result: {
+          success: false,
+          errors: [
+            {
+              path: "",
+              message: `YAML syntax error: ${error instanceof Error ? error.message : String(error)}`
+            }
+          ]
+        }
+      };
+    }
+    const doc = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    const type = doc?.type;
+    if (type === "map") {
+      return { blockType: "map", result: this.safeParseMapBlock(yaml) };
+    }
+    if (type === "scrollytelling") {
+      return {
+        blockType: "scrollytelling",
+        result: this.safeParseScrollytellingBlock(yaml)
+      };
+    }
+    if (type !== void 0) {
+      return {
+        blockType: "unknown",
+        result: {
+          success: false,
+          errors: [
+            {
+              path: "type",
+              message: `Unknown block type: ${JSON.stringify(
+                type
+              )}. Expected one of: map, scrollytelling. Root documents omit "type" and use a top-level "pages:" array instead.`
+            }
+          ]
+        }
+      };
+    }
+    if (doc !== null && "pages" in doc) {
+      return { blockType: "root", result: this.safeParse(yaml) };
+    }
+    return {
+      blockType: "unknown",
+      result: {
+        success: false,
+        errors: [
+          {
+            path: "",
+            message: 'Unable to determine document type. Expected a block with "type: map" or "type: scrollytelling", or a root document with a top-level "pages:" array.'
+          }
+        ]
+      }
+    };
+  }
   /**
    * Resolve $ref references to global layers and sources
    *
@@ -1187,6 +1298,14 @@ var YAMLParser = class {
 };
 YAMLParser.parse.bind(YAMLParser);
 YAMLParser.safeParse.bind(YAMLParser);
+YAMLParser.safeParseAny.bind(YAMLParser);
+var gl = maplibre.default ?? maplibre;
+var Map2 = gl.Map;
+var Popup = gl.Popup;
+var NavigationControl = gl.NavigationControl;
+var GeolocateControl = gl.GeolocateControl;
+var ScaleControl = gl.ScaleControl;
+var FullscreenControl = gl.FullscreenControl;
 
 // src/data/memory-cache.ts
 var MemoryCache = class _MemoryCache {
@@ -1712,9 +1831,17 @@ var DataFetcher = class _DataFetcher {
    * Perform the actual HTTP fetch
    */
   async performFetch(url, options) {
-    const controller = options.signal ? new AbortController() : new AbortController();
-    if (options.signal) {
-      options.signal.addEventListener("abort", () => controller.abort());
+    const controller = new AbortController();
+    const externalSignal = options.signal;
+    const onExternalAbort = () => controller.abort(externalSignal?.reason);
+    if (externalSignal) {
+      if (externalSignal.aborted) {
+        controller.abort(externalSignal.reason);
+      } else {
+        externalSignal.addEventListener("abort", onExternalAbort, {
+          once: true
+        });
+      }
     }
     const timeoutId = setTimeout(() => {
       controller.abort();
@@ -1772,6 +1899,7 @@ var DataFetcher = class _DataFetcher {
       return data;
     } finally {
       clearTimeout(timeoutId);
+      externalSignal?.removeEventListener("abort", onExternalAbort);
       this.activeRequests.delete(url);
     }
   }
@@ -3553,9 +3681,6 @@ var LayerManager = class {
   loadingManager;
   sourceData;
   layerToSource;
-  // Legacy support (deprecated)
-  refreshIntervals;
-  abortControllers;
   constructor(map, callbacks) {
     this.map = map;
     this.callbacks = callbacks || {};
@@ -3566,8 +3691,6 @@ var LayerManager = class {
     this.loadingManager = new LoadingManager({ showUI: false });
     this.sourceData = /* @__PURE__ */ new Map();
     this.layerToSource = /* @__PURE__ */ new Map();
-    this.refreshIntervals = /* @__PURE__ */ new Map();
-    this.abortControllers = /* @__PURE__ */ new Map();
   }
   async addLayer(layer) {
     const isSourceRef = typeof layer.source === "string";
@@ -3818,12 +3941,6 @@ var LayerManager = class {
     this.pollingManager.stop(layerId);
     this.streamManager.disconnect(layerId);
     this.loadingManager.hideLoading(layerId);
-    this.stopRefreshInterval(layerId);
-    const controller = this.abortControllers.get(layerId);
-    if (controller) {
-      controller.abort();
-      this.abortControllers.delete(layerId);
-    }
     if (this.map.getLayer(layerId)) this.map.removeLayer(layerId);
     const sourceId = this.layerToSource.get(layerId) || `${layerId}-source`;
     const isInlineSource = sourceId === `${layerId}-source`;
@@ -3846,61 +3963,12 @@ var LayerManager = class {
     const source = this.map.getSource(sourceId);
     if (source && source.setData) source.setData(data);
   }
-  /**
-   * @deprecated Legacy refresh method - use PollingManager instead
-   */
-  startRefreshInterval(layer) {
-    if (typeof layer.source !== "object" || layer.source === null) {
-      return;
-    }
-    const sourceObj = layer.source;
-    if (sourceObj.type !== "geojson" || !sourceObj.url || !sourceObj.refreshInterval) {
-      return;
-    }
-    const geojsonSource = layer.source;
-    const interval = setInterval(async () => {
-      const sourceId = `${layer.id}-source`;
-      try {
-        const cacheEnabled = geojsonSource.cache?.enabled ?? true;
-        const cacheTTL = geojsonSource.cache?.ttl;
-        const result = await this.dataFetcher.fetch(geojsonSource.url, {
-          skipCache: !cacheEnabled,
-          ttl: cacheTTL
-        });
-        const data = result.data;
-        this.sourceData.set(sourceId, data);
-        const source = this.map.getSource(sourceId);
-        if (source?.setData) {
-          source.setData(data);
-        }
-        this.callbacks.onDataLoaded?.(layer.id, data.features.length);
-      } catch (error) {
-        this.callbacks.onDataError?.(layer.id, error);
-      }
-    }, geojsonSource.refreshInterval);
-    this.refreshIntervals.set(layer.id, interval);
-  }
-  stopRefreshInterval(layerId) {
-    const interval = this.refreshIntervals.get(layerId);
-    if (interval) {
-      clearInterval(interval);
-      this.refreshIntervals.delete(layerId);
-    }
-  }
-  clearAllIntervals() {
-    for (const interval of this.refreshIntervals.values())
-      clearInterval(interval);
-    this.refreshIntervals.clear();
-  }
   destroy() {
     this.pollingManager.destroy();
     this.streamManager.destroy();
     this.loadingManager.destroy();
     this.sourceData.clear();
     this.layerToSource.clear();
-    this.clearAllIntervals();
-    for (const controller of this.abortControllers.values()) controller.abort();
-    this.abortControllers.clear();
   }
 };
 
@@ -4127,6 +4195,8 @@ var LegendBuilder = class {
     return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
   }
 };
+
+// src/renderer/controls-manager.ts
 var ControlsManager = class {
   map;
   addedControls;
@@ -4191,10 +4261,18 @@ var MapRenderer = class {
   controlsManager;
   eventListeners;
   isLoaded;
+  containerEl;
+  controlsAdded;
+  legendBuilt;
+  autoLegendContainer;
   constructor(container, config, layers = [], options = {}, sources) {
     this.eventListeners = /* @__PURE__ */ new Map();
     this.isLoaded = false;
-    this.map = new Map$1({
+    this.containerEl = typeof container === "string" ? document.getElementById(container) : container;
+    this.controlsAdded = false;
+    this.legendBuilt = false;
+    this.autoLegendContainer = null;
+    this.map = new Map2({
       ...config,
       container: typeof container === "string" ? container : container,
       style: config.mapStyle,
@@ -4226,6 +4304,12 @@ var MapRenderer = class {
           }
         }
       }
+      if (options.controls && !this.controlsAdded) {
+        this.addControls(options.controls);
+      }
+      if (options.legend && !this.legendBuilt) {
+        this.buildLegend(this.createLegendContainer(options.legend), layers, options.legend);
+      }
       Promise.all(layers.map((layer) => this.addLayer(layer))).then(() => {
         this.emit("load", void 0);
         options.onLoad?.();
@@ -4279,16 +4363,43 @@ var MapRenderer = class {
   }
   /**
    * Add controls to the map
+   *
+   * @remarks
+   * Called automatically on map load when a `controls:` config was passed via
+   * {@link MapRendererOptions}. Calling it manually marks controls as added so
+   * the automatic invocation is skipped (no double-add).
    */
   addControls(config) {
+    this.controlsAdded = true;
     this.controlsManager.addControls(config);
   }
   /**
    * Build legend in container
+   *
+   * @remarks
+   * Called automatically on map load when a `legend:` config was passed via
+   * {@link MapRendererOptions}. Calling it manually marks the legend as built
+   * so the automatic invocation is skipped (no double-build).
    */
   buildLegend(container, layers, config) {
+    this.legendBuilt = true;
     this.legendBuilder.build(container, layers, config);
   }
+  /**
+   * Create a positioned container inside the map element for the auto legend
+   */
+  createLegendContainer(config) {
+    const el = document.createElement("div");
+    el.className = "ml-map-legend";
+    const position = config.position ?? "top-left";
+    el.style.position = "absolute";
+    el.style.zIndex = "1";
+    el.style[position.includes("top") ? "top" : "bottom"] = "10px";
+    el.style[position.includes("left") ? "left" : "right"] = "10px";
+    (this.containerEl ?? this.map.getContainer()).appendChild(el);
+    this.autoLegendContainer = el;
+    return el;
+  }
   /**
    * Get the legend builder instance
    */
@@ -4331,6 +4442,8 @@ var MapRenderer = class {
     this.eventHandler.destroy();
     this.layerManager.destroy();
     this.controlsManager.removeAllControls();
+    this.autoLegendContainer?.remove();
+    this.autoLegendContainer = null;
     this.eventListeners.clear();
     this.map.remove();
   }
@@ -4514,6 +4627,15 @@ var MLMap = class extends HTMLElement {
    * Render the map with the given configuration
    */
   renderMap(mapBlock) {
+    if (!mapBlock.config?.mapStyle) {
+      this.handleError([
+        {
+          path: "config.mapStyle",
+          message: 'mapStyle is required for standalone maps. Add it to your config, for example: mapStyle: "https://demotiles.maplibre.org/style.json" (inheriting a defaultMapStyle is a feature of the Astro builders, not the standalone <ml-map> element).'
+        }
+      ]);
+      return;
+    }
     if (this.renderer) {
       this.renderer.destroy();
       this.renderer = null;
@@ -4525,8 +4647,10 @@ var MLMap = class extends HTMLElement {
     }
     this.appendChild(this.mapContainer);
     try {
-      const { config, sources, layers = [] } = mapBlock;
+      const { config, sources, layers = [], controls, legend } = mapBlock;
       this.renderer = new MapRenderer(this.mapContainer, config, layers, {
+        controls,
+        legend,
         onLoad: () => {
         },
         onError: (error) => {