npm - @maplibre-yaml/core - Versions diffs - 0.2.2 → 0.3.0 - Mend

@maplibre-yaml/core 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

package/LICENSE.md +21 -0
package/README.md +44 -16
package/dist/components/index.d.ts +1 -1
package/dist/components/index.js +197 -73
package/dist/components/index.js.map +1 -1
package/dist/index.d.ts +1 -9
package/dist/index.js +207 -94
package/dist/index.js.map +1 -1
package/dist/{map-renderer-SjO3KQmx.d.ts → map-renderer-4FF3EmBO.d.ts} +130 -3
package/dist/register.browser.js +6029 -7035
package/dist/register.browser.js.map +1 -1
package/dist/register.d.ts +1 -1
package/dist/register.js +197 -73
package/dist/register.js.map +1 -1
package/dist/schemas/index.js +24 -2
package/dist/schemas/index.js.map +1 -1
package/package.json +17 -12
package/register.js +8 -0

package/LICENSE.md ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2025 mariogiampieri
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md CHANGED Viewed

@@ -25,23 +25,32 @@ The simplest way to use maplibre-yaml is with the `<ml-map>` web component:
   <style>
     ml-map { display: block; height: 400px; }
   </style>
+  <!-- Tell the browser where to find maplibre-gl (kept external, not bundled) -->
+  <script type="importmap">
+    { "imports": { "maplibre-gl": "https://esm.sh/maplibre-gl@^4" } }
+  </script>
+  <!-- Register the <ml-map> web component -->
+  <script
+    type="module"
+    src="https://unpkg.com/@maplibre-yaml/core/register.js"
+  ></script>
 </head>
 <body>
   <ml-map src="/map.yaml"></ml-map>
-  <script type="module">
-    import '@maplibre-yaml/core/register';
-  </script>
 </body>
 </html>
 ```
+With a bundler (Vite, Webpack, etc.) skip the import map and CDN script — `import '@maplibre-yaml/core/register'` in your entry point instead.
 ### JavaScript API
 ```typescript
-import { parseYAMLConfig, MapRenderer } from '@maplibre-yaml/core';
+import { YAMLParser, MapRenderer } from '@maplibre-yaml/core';
 const yaml = `
 type: map
+id: my-map
 config:
   center: [-122.4, 37.8]
   zoom: 12
@@ -57,11 +66,22 @@ layers:
       circle-color: "#3b82f6"
 `;
-const config = parseYAMLConfig(yaml);
+const mapBlock = YAMLParser.parseMapBlock(yaml);
 const container = document.getElementById('map');
-const renderer = new MapRenderer(container, config);
+const renderer = new MapRenderer(
+  container,
+  mapBlock.config,
+  mapBlock.layers,
+  {
+    onLoad: () => console.log('Map loaded'),
+    onError: (error) => console.error(error),
+  },
+  mapBlock.sources
+);
 ```
+Use `YAMLParser.parseMapBlock` for single `type: map` documents. `parseYAMLConfig` parses full root documents (a `pages:` array of pages and blocks) and will reject a bare map block.
 ## Entry Points
 The package provides multiple entry points for different use cases:
@@ -197,6 +217,8 @@ layers:
 ### Interactive Popups
+Popup content is a list of HTML elements, where each element maps a tag name to an array of static (`str`) or dynamic (`property`) content items:
 ```yaml
 layers:
   - id: locations
@@ -206,12 +228,16 @@ layers:
       url: https://example.com/locations.geojson
     layout:
       icon-image: marker
-    interactions:
-      - type: click
+    interactive:
+      hover:
+        cursor: pointer
+      click:
         popup:
-          content: |
-            <h3>{{name}}</h3>
-            <p>{{description}}</p>
+          - h3:
+              - property: name
+                else: "Unknown"
+          - p:
+              - property: description
 ```
 ## API Reference
@@ -229,12 +255,13 @@ const result = safeParseYAMLConfig(yamlString);
 if (result.success) {
   console.log(result.data);
 } else {
-  console.error(result.error);
+  console.error(result.errors);
 }
-// Using the class
-const parser = new YAMLParser();
-const config = parser.parse(yamlString);
+// Single-block documents (all methods are static)
+const mapBlock = YAMLParser.parseMapBlock(mapYaml);
+const story = YAMLParser.parseScrollytellingBlock(storyYaml);
+const safe = YAMLParser.safeParseMapBlock(mapYaml);
 ```
 ### Renderer
@@ -242,7 +269,8 @@ const config = parser.parse(yamlString);
 ```typescript
 import { MapRenderer } from '@maplibre-yaml/core';
-const renderer = new MapRenderer(container, config, {
+// new MapRenderer(container, config, layers?, options?, sources?)
+const renderer = new MapRenderer(container, config, layers, {
   onLoad: () => console.log('Map loaded'),
   onError: (error) => console.error(error),
 });

package/dist/components/index.d.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 export { MLMap, registerMLMap } from '../register.js';
 import 'maplibre-gl';
-import '../map-renderer-SjO3KQmx.js';
+import '../map-renderer-4FF3EmBO.js';
 import '../page.schema-Cad2FFqh.js';
 import 'zod';

package/dist/components/index.js CHANGED Viewed

@@ -1,6 +1,6 @@
 import { parse } from 'yaml';
 import { z, ZodError } from 'zod';
-import maplibregl2 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();
   }
 };
@@ -4037,7 +4105,7 @@ var EventHandler = class {
   showPopup(content, feature, lngLat) {
     this.activePopup?.remove();
     const html = this.popupBuilder.build(content, feature.properties);
-    this.activePopup = new maplibregl2.Popup().setLngLat(lngLat).setHTML(html).addTo(this.map);
+    this.activePopup = new Popup().setLngLat(lngLat).setHTML(html).addTo(this.map);
   }
   /**
    * Detach events for a layer
@@ -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;
@@ -4142,14 +4212,14 @@ var ControlsManager = class {
     if (config.navigation) {
       const options = typeof config.navigation === "object" ? config.navigation : {};
       const position = options.position || "top-right";
-      const control = new maplibregl2.NavigationControl();
+      const control = new NavigationControl();
       this.map.addControl(control, position);
       this.addedControls.push(control);
     }
     if (config.geolocate) {
       const options = typeof config.geolocate === "object" ? config.geolocate : {};
       const position = options.position || "top-right";
-      const control = new maplibregl2.GeolocateControl({
+      const control = new GeolocateControl({
         positionOptions: { enableHighAccuracy: true },
         trackUserLocation: true
       });
@@ -4159,14 +4229,14 @@ var ControlsManager = class {
     if (config.scale) {
       const options = typeof config.scale === "object" ? config.scale : {};
       const position = options.position || "bottom-left";
-      const control = new maplibregl2.ScaleControl();
+      const control = new ScaleControl();
       this.map.addControl(control, position);
       this.addedControls.push(control);
     }
     if (config.fullscreen) {
       const options = typeof config.fullscreen === "object" ? config.fullscreen : {};
       const position = options.position || "top-right";
-      const control = new maplibregl2.FullscreenControl();
+      const control = new FullscreenControl();
       this.map.addControl(control, position);
       this.addedControls.push(control);
     }
@@ -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 maplibregl2.Map({
+    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) => {