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

package/dist/{map-renderer-SjO3KQmx.d.ts → map-renderer-4FF3EmBO.d.ts}

@@ -1,6 +1,7 @@
-import { R as RootSchema, M as MapBlockSchema, S as ScrollytellingBlockSchema, L as LayerSchema, a as LegendConfigSchema, b as MapConfigSchema, c as LayerSourceSchema, C as ControlsConfigSchema } from './page.schema-Cad2FFqh.js';
+import { R as RootSchema, M as MapBlockSchema, S as ScrollytellingBlockSchema, L as LayerSchema, a as LegendConfigSchema, b as MapConfigSchema, C as ControlsConfigSchema, c as LayerSourceSchema } from './page.schema-Cad2FFqh.js';
 import { z } from 'zod';
-import { Map, LngLat } from 'maplibre-gl';
+import * as maplibre from 'maplibre-gl';
+import { LngLat } from 'maplibre-gl';
 
 /**
  * @file YAML parser for MapLibre configuration files
@@ -122,6 +123,33 @@ interface ParseResult<T = RootConfig> {
     data?: T;
     errors: ParseError[];
 }
+/**
+ * Discriminated result returned by {@link YAMLParser.safeParseAny}
+ *
+ * @remarks
+ * The `blockType` field identifies which schema the document was validated
+ * against, and `result` carries the corresponding safeParse result:
+ *
+ * - `'map'` — document had `type: map`, validated with {@link YAMLParser.safeParseMapBlock}
+ * - `'scrollytelling'` — document had `type: scrollytelling`, validated with {@link YAMLParser.safeParseScrollytellingBlock}
+ * - `'root'` — document had no `type:` but a `pages:` array, validated with {@link YAMLParser.safeParse}
+ * - `'unknown'` — the document type could not be determined (unrecognized
+ *   `type:` value, YAML syntax error, or a document that is neither a block
+ *   nor a root config); `result` is always a failure with a descriptive error
+ */
+type SafeParseAnyResult = {
+    blockType: "map";
+    result: ParseResult<MapBlock>;
+} | {
+    blockType: "scrollytelling";
+    result: ParseResult<ScrollytellingBlock>;
+} | {
+    blockType: "root";
+    result: ParseResult<RootConfig>;
+} | {
+    blockType: "unknown";
+    result: ParseResult<never>;
+};
 /**
  * YAML parser with schema validation and reference resolution
  *
@@ -334,6 +362,35 @@ declare class YAMLParser {
      * ```
      */
     static safeParseScrollytellingBlock(yaml: string): ParseResult<ScrollytellingBlock>;
+    /**
+     * 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: string): SafeParseAnyResult;
     /**
      * Resolve $ref references to global layers and sources
      *
@@ -444,6 +501,54 @@ declare const parseYAMLConfig: typeof YAMLParser.parse;
  * ```
  */
 declare const safeParseYAMLConfig: typeof YAMLParser.safeParse;
+/**
+ * Convenience function to detect and validate any supported document type
+ *
+ * @param yaml - YAML string to parse (map block, scrollytelling block, or root document)
+ * @returns Discriminated result with the detected block type and safeParse result
+ *
+ * @remarks
+ * This is an alias for {@link YAMLParser.safeParseAny} for convenient imports.
+ *
+ * @example
+ * ```typescript
+ * import { safeParseAny } from '@maplibre-yaml/core/parser';
+ * const { blockType, result } = safeParseAny(yamlString);
+ * ```
+ */
+declare const safeParseAny: typeof YAMLParser.safeParseAny;
+
+/**
+ * @file maplibre-gl named-export interop
+ * @module @maplibre-yaml/core/renderer
+ *
+ * @description
+ * Single place where maplibre-gl runtime values enter this package.
+ *
+ * maplibre-gl (v3–v5) ships a CJS bundle with no `exports` map, which makes
+ * its bindings environment-dependent:
+ *
+ * - **Node ESM**: cjs-module-lexer cannot statically detect the bundle's
+ *   named exports, so `import { Map } from "maplibre-gl"` throws at import
+ *   time ("Named export not found") — only the `default` binding
+ *   (`module.exports`) is populated. This is why a straight named-import
+ *   conversion was reverted once before: it broke every Node consumer of
+ *   this package (the CLI's `validate`, Astro's content loader).
+ * - **Bundlers** (Vite/esbuild/webpack): CJS interop populates both named
+ *   and default bindings.
+ * - **Real ESM builds** (esm.sh via the documented CDN import map, or a
+ *   future ESM-only maplibre-gl): named exports exist; `default` may not.
+ *   maplibre-gl v5's type declarations already dropped the default export.
+ *
+ * Importing the namespace and preferring `default` when present yields
+ * working constructors in every environment, while the exported types stay
+ * the named ones that v5 declares. Do not import maplibre-gl runtime values
+ * directly anywhere else in src/ — route them through this module.
+ * (Type-only imports from "maplibre-gl" are fine; they're erased.)
+ */
+
+declare const Map: typeof maplibre.Map;
+type Map = maplibre.Map;
 
 /**
  * @file Legend builder for map layers
@@ -490,6 +595,10 @@ type LegendConfig = z.infer<typeof LegendConfigSchema>;
 interface MapRendererOptions {
     onLoad?: () => void;
     onError?: (error: Error) => void;
+    /** Controls declared in the YAML `controls:` block — added automatically on map load */
+    controls?: ControlsConfig;
+    /** Legend declared in the YAML `legend:` block — built automatically on map load */
+    legend?: LegendConfig;
 }
 /**
  * Events emitted by MapRenderer
@@ -535,6 +644,10 @@ declare class MapRenderer {
     private controlsManager;
     private eventListeners;
     private isLoaded;
+    private containerEl;
+    private controlsAdded;
+    private legendBuilt;
+    private autoLegendContainer;
     constructor(container: string | HTMLElement, config: MapConfig, layers?: Layer[], options?: MapRendererOptions, sources?: Record<string, LayerSource>);
     /**
      * Get the underlying MapLibre map instance
@@ -562,12 +675,26 @@ declare class MapRenderer {
     updateLayerData(layerId: string, data: GeoJSON.GeoJSON): void;
     /**
      * 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: ControlsConfig): void;
     /**
      * 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: string | HTMLElement, layers: Layer[], config?: LegendConfig): void;
+    /**
+     * Create a positioned container inside the map element for the auto legend
+     */
+    private createLegendContainer;
     /**
      * Get the legend builder instance
      */
@@ -590,4 +717,4 @@ declare class MapRenderer {
     destroy(): void;
 }
 
-export { LegendBuilder as L, MapRenderer as M, type ParseError as P, YAMLParser as Y, type ParseResult as a, type MapRendererOptions as b, type MapRendererEvents as c, type MapBlock as d, parseYAMLConfig as p, safeParseYAMLConfig as s };
+export { LegendBuilder as L, MapRenderer as M, type ParseError as P, type SafeParseAnyResult as S, YAMLParser as Y, safeParseAny as a, type ParseResult as b, type MapRendererOptions as c, type MapRendererEvents as d, type MapBlock as e, parseYAMLConfig as p, safeParseYAMLConfig as s };