@maplibre-yaml/core 0.1.0-alpha.0 → 0.1.1

package/dist/index.d.ts

@@ -1,320 +1,11 @@
-import { RootSchema } from './schemas/index.js';
-export { BlockSchema, ChapterActionSchema, ChapterLayersSchema, ChapterSchema, ColorOrExpressionSchema, ColorSchema, ContentBlockSchema, ContentElementSchema, ContentItemSchema, ExpressionSchema, GeoJSONSourceSchema, GlobalConfigSchema, ImageSourceSchema, LatitudeSchema, LayerSourceSchema, LngLatBoundsSchema, LngLatSchema, LoadingConfigSchema, LongitudeSchema, MixedBlockSchema, NumberOrExpressionSchema, PageSchema, RasterSourceSchema, ScrollytellingBlockSchema, StreamConfigSchema, ValidTagNames, VectorSourceSchema, VideoSourceSchema, ZoomLevelSchema } from './schemas/index.js';
-import { L as LayerSchema, P as PopupContentSchema, C as ControlsConfigSchema } from './map.schema-EnZRrtIh.js';
-export { h as BackgroundLayerSchema, B as BaseLayerPropertiesSchema, d as CircleLayerSchema, k as ControlPositionSchema, f as FillExtrusionLayerSchema, F as FillLayerSchema, H as HeatmapLayerSchema, g as HillshadeLayerSchema, I as InteractiveConfigSchema, j as LayerOrReferenceSchema, i as LayerReferenceSchema, a as LegendConfigSchema, c as LegendItemSchema, e as LineLayerSchema, l as MapBlockSchema, M as MapConfigSchema, m as MapFullPageBlockSchema, b as PopupContentItemSchema, R as RasterLayerSchema, S as SymbolLayerSchema } from './map.schema-EnZRrtIh.js';
-import { z } from 'zod';
-export { L as LegendBuilder, M as MapRenderer, b as MapRendererEvents, a as MapRendererOptions } from './map-renderer-RQc5_bdo.js';
+export { ChapterActionSchema, ChapterLayersSchema, ChapterSchema, ColorOrExpressionSchema, ColorSchema, ContentBlockSchema, ContentElementSchema, ContentItemSchema, ExpressionSchema, GeoJSONSourceSchema, ImageSourceSchema, LatitudeSchema, LayerSourceSchema, LngLatBoundsSchema, LngLatSchema, LoadingConfigSchema, LongitudeSchema, NumberOrExpressionSchema, RasterSourceSchema, ScrollytellingBlockSchema, StreamConfigSchema, ValidTagNames, VectorSourceSchema, VideoSourceSchema, ZoomLevelSchema } from './schemas/index.js';
+import { L as LayerSchema, P as PopupContentSchema, C as ControlsConfigSchema } from './page.schema-CzdCyPFI.js';
+export { j as BackgroundLayerSchema, B as BaseLayerPropertiesSchema, p as BlockSchema, e as CircleLayerSchema, m as ControlPositionSchema, h as FillExtrusionLayerSchema, F as FillLayerSchema, G as GlobalConfigSchema, H as HeatmapLayerSchema, i as HillshadeLayerSchema, I as InteractiveConfigSchema, l as LayerOrReferenceSchema, k as LayerReferenceSchema, a as LegendConfigSchema, d as LegendItemSchema, f as LineLayerSchema, M as MapBlockSchema, b as MapConfigSchema, n as MapFullPageBlockSchema, o as MixedBlockSchema, q as PageSchema, c as PopupContentItemSchema, g as RasterLayerSchema, R as RootSchema, S as SymbolLayerSchema } from './page.schema-CzdCyPFI.js';
+export { L as LegendBuilder, M as MapBlock, b as MapRenderer, d as MapRendererEvents, c as MapRendererOptions, P as ParseError, a as ParseResult, R as RootConfig, Y as YAMLParser, p as parseYAMLConfig, s as safeParseYAMLConfig } from './map-renderer-DOLO9y-3.js';
 import { Map, LngLat } from 'maplibre-gl';
+import { z } from 'zod';
 import { FeatureCollection } from 'geojson';
 
-/**
- * @file YAML parser for MapLibre configuration files
- * @module @maplibre-yaml/core/parser
- *
- * @description
- * This module provides YAML parsing, schema validation, and reference resolution
- * for MapLibre YAML configuration files. It converts YAML strings into validated
- * TypeScript objects ready for rendering.
- *
- * ## Features
- *
- * - **YAML Parsing**: Converts YAML strings to JavaScript objects
- * - **Schema Validation**: Validates against Zod schemas with detailed error messages
- * - **Reference Resolution**: Resolves `$ref` pointers to global layers and sources
- * - **Error Formatting**: Transforms Zod errors into user-friendly messages with paths
- *
- * @example
- * Basic parsing
- * ```typescript
- * import { YAMLParser } from '@maplibre-yaml/core/parser';
- *
- * const yaml = `
- * pages:
- *   - path: "/"
- *     title: "My Map"
- *     blocks:
- *       - type: map
- *         id: main
- *         config:
- *           center: [0, 0]
- *           zoom: 2
- *           mapStyle: "https://example.com/style.json"
- * `;
- *
- * const config = YAMLParser.parse(yaml);
- * ```
- *
- * @example
- * Safe parsing with error handling
- * ```typescript
- * const result = YAMLParser.safeParse(yaml);
- * if (result.success) {
- *   console.log('Valid config:', result.data);
- * } else {
- *   result.errors.forEach(err => {
- *     console.error(`${err.path}: ${err.message}`);
- *   });
- * }
- * ```
- *
- * @example
- * Reference resolution
- * ```typescript
- * const yaml = `
- * layers:
- *   myLayer:
- *     id: shared
- *     type: circle
- *     source: { type: geojson, data: {...} }
- *
- * pages:
- *   - path: "/"
- *     blocks:
- *       - type: map
- *         layers:
- *           - $ref: "#/layers/myLayer"
- * `;
- *
- * const config = YAMLParser.parse(yaml);
- * // References are automatically resolved
- * ```
- */
-
-/**
- * Type alias for the root configuration object
- *
- * @remarks
- * Inferred from the RootSchema Zod schema
- */
-type RootConfig = z.infer<typeof RootSchema>;
-/**
- * Error information for a single validation or parsing error
- *
- * @property path - JSON path to the error location (e.g., "pages[0].blocks[1].config.center")
- * @property message - Human-readable error description
- * @property line - Optional line number in the YAML file where error occurred
- * @property column - Optional column number in the YAML file where error occurred
- */
-interface ParseError {
-    path: string;
-    message: string;
-    line?: number;
-    column?: number;
-}
-/**
- * Result object returned by safeParse operations
- *
- * @property success - Whether parsing and validation succeeded
- * @property data - Validated configuration object (only present if success is true)
- * @property errors - Array of errors (only present if success is false)
- */
-interface ParseResult {
-    success: boolean;
-    data?: RootConfig;
-    errors: ParseError[];
-}
-/**
- * YAML parser with schema validation and reference resolution
- *
- * @remarks
- * This class provides static methods for parsing YAML configuration files,
- * validating them against schemas, and resolving references between configuration
- * sections. All methods are static as the parser maintains no internal state.
- *
- * @example
- * Parse and validate YAML (throws on error)
- * ```typescript
- * const config = YAMLParser.parse(yamlString);
- * ```
- *
- * @example
- * Safe parse (returns result object)
- * ```typescript
- * const result = YAMLParser.safeParse(yamlString);
- * if (!result.success) {
- *   console.error('Validation errors:', result.errors);
- * }
- * ```
- */
-declare class YAMLParser {
-    /**
-     * Parse YAML string and validate against schema
-     *
-     * @param yaml - YAML string to parse
-     * @returns Validated configuration object
-     * @throws {Error} If YAML syntax is invalid
-     * @throws {ZodError} If validation fails
-     *
-     * @remarks
-     * This method parses the YAML, validates it against the RootSchema,
-     * resolves all references, and returns the validated config. If any
-     * step fails, it throws an error.
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   const config = YAMLParser.parse(yamlString);
-     *   console.log('Valid config:', config);
-     * } catch (error) {
-     *   console.error('Parse error:', error.message);
-     * }
-     * ```
-     */
-    static parse(yaml: string): RootConfig;
-    /**
-     * Parse YAML string and validate, returning a result object
-     *
-     * @param yaml - YAML string to parse
-     * @returns Result object with success flag and either data or errors
-     *
-     * @remarks
-     * This is the non-throwing version of {@link parse}. Instead of throwing
-     * errors, it returns a result object that indicates success or failure.
-     * Use this when you want to handle errors gracefully without try/catch.
-     *
-     * @example
-     * ```typescript
-     * const result = YAMLParser.safeParse(yamlString);
-     * if (result.success) {
-     *   console.log('Config:', result.data);
-     * } else {
-     *   result.errors.forEach(err => {
-     *     console.error(`Error at ${err.path}: ${err.message}`);
-     *   });
-     * }
-     * ```
-     */
-    static safeParse(yaml: string): ParseResult;
-    /**
-     * Validate a JavaScript object against the schema
-     *
-     * @param config - JavaScript object to validate
-     * @returns Validated configuration object
-     * @throws {ZodError} If validation fails
-     *
-     * @remarks
-     * This method bypasses YAML parsing and directly validates a JavaScript object.
-     * Useful when you already have a parsed object (e.g., from JSON.parse) and just
-     * want to validate and resolve references.
-     *
-     * @example
-     * ```typescript
-     * const jsConfig = JSON.parse(jsonString);
-     * const validated = YAMLParser.validate(jsConfig);
-     * ```
-     */
-    static validate(config: unknown): RootConfig;
-    /**
-     * Resolve $ref references to global layers and sources
-     *
-     * @param config - Configuration object with potential references
-     * @returns Configuration with all references resolved
-     * @throws {Error} If a reference cannot be resolved
-     *
-     * @remarks
-     * References use JSON Pointer-like syntax: `#/layers/layerName` or `#/sources/sourceName`.
-     * This method walks the configuration tree, finds all objects with a `$ref` property,
-     * looks up the referenced item in `config.layers` or `config.sources`, and replaces
-     * the reference object with the actual item.
-     *
-     * ## Reference Syntax
-     *
-     * - `#/layers/myLayer` - Reference to a layer in the global `layers` section
-     * - `#/sources/mySource` - Reference to a source in the global `sources` section
-     *
-     * @example
-     * ```typescript
-     * const config = {
-     *   layers: {
-     *     myLayer: { id: 'layer1', type: 'circle', ... }
-     *   },
-     *   pages: [{
-     *     blocks: [{
-     *       type: 'map',
-     *       layers: [{ $ref: '#/layers/myLayer' }]
-     *     }]
-     *   }]
-     * };
-     *
-     * const resolved = YAMLParser.resolveReferences(config);
-     * // resolved.pages[0].blocks[0].layers[0] now contains the full layer object
-     * ```
-     */
-    static resolveReferences(config: RootConfig): RootConfig;
-    /**
-     * Format Zod validation errors into user-friendly messages
-     *
-     * @param error - Zod validation error
-     * @returns Array of formatted error objects
-     *
-     * @remarks
-     * This method transforms Zod's internal error format into human-readable
-     * messages with clear paths and descriptions. It handles various Zod error
-     * types and provides appropriate messages for each.
-     *
-     * ## Error Type Handling
-     *
-     * - `invalid_type`: Type mismatch (e.g., expected number, got string)
-     * - `invalid_union_discriminator`: Invalid discriminator for union types
-     * - `invalid_union`: None of the union options matched
-     * - `too_small`: Value below minimum (arrays, strings, numbers)
-     * - `too_big`: Value above maximum
-     * - `invalid_string`: String format validation failed
-     * - `custom`: Custom validation refinement failed
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   RootSchema.parse(invalidConfig);
-     * } catch (error) {
-     *   if (error instanceof ZodError) {
-     *     const formatted = YAMLParser.formatZodErrors(error);
-     *     formatted.forEach(err => {
-     *       console.error(`${err.path}: ${err.message}`);
-     *     });
-     *   }
-     * }
-     * ```
-     */
-    private static formatZodErrors;
-}
-/**
- * Convenience function to parse YAML config
- *
- * @param yaml - YAML string to parse
- * @returns Validated configuration object
- * @throws {Error} If parsing or validation fails
- *
- * @remarks
- * This is an alias for {@link YAMLParser.parse} for convenient imports.
- *
- * @example
- * ```typescript
- * import { parseYAMLConfig } from '@maplibre-yaml/core/parser';
- * const config = parseYAMLConfig(yamlString);
- * ```
- */
-declare const parseYAMLConfig: typeof YAMLParser.parse;
-/**
- * Convenience function to safely parse YAML config
- *
- * @param yaml - YAML string to parse
- * @returns Result object with success flag and data or errors
- *
- * @remarks
- * This is an alias for {@link YAMLParser.safeParse} for convenient imports.
- *
- * @example
- * ```typescript
- * import { safeParseYAMLConfig } from '@maplibre-yaml/core/parser';
- * const result = safeParseYAMLConfig(yamlString);
- * if (result.success) {
- *   console.log(result.data);
- * }
- * ```
- */
-declare const safeParseYAMLConfig: typeof YAMLParser.safeParse;
-
 /**
  * @file Layer manager for MapLibre map layers
  * @module @maplibre-yaml/core/renderer
@@ -2714,4 +2405,4 @@ declare const loadingStyles = "\n/* Loading Overlay */\n.mly-loading-overlay {\n
  */
 declare function injectLoadingStyles(): void;
 
-export { BaseConnection, type CacheConfig, type CacheEntry, type CacheStats, type ConnectionConfig, type ConnectionEvents, type ConnectionState, ControlsConfigSchema, ControlsManager, DataFetcher, DataMerger, EventEmitter, type EventHandler, type EventHandlerCallbacks, type FetchOptions, type FetchResult, type FetcherConfig, LayerManager, type LayerManagerCallbacks, LayerSchema, type LoadingConfig, type LoadingEvents, LoadingManager, type LoadingState, MaxRetriesExceededError, MemoryCache, type MergeOptions, type MergeResult, type MergeStrategy, type ParseError, type ParseResult, type PollingConfig, PollingManager, type PollingState, PopupBuilder, PopupContentSchema, type RetryCallbacks, type RetryConfig, RetryManager, type RootConfig, RootSchema, type SSEConfig, SSEConnection, type StreamConfig, StreamManager, type StreamState, type WebSocketConfig, WebSocketConnection, YAMLParser, injectLoadingStyles, loadingStyles, parseYAMLConfig, safeParseYAMLConfig };
+export { BaseConnection, type CacheConfig, type CacheEntry, type CacheStats, type ConnectionConfig, type ConnectionEvents, type ConnectionState, ControlsConfigSchema, ControlsManager, DataFetcher, DataMerger, EventEmitter, type EventHandler, type EventHandlerCallbacks, type FetchOptions, type FetchResult, type FetcherConfig, LayerManager, type LayerManagerCallbacks, LayerSchema, type LoadingConfig, type LoadingEvents, LoadingManager, type LoadingState, MaxRetriesExceededError, MemoryCache, type MergeOptions, type MergeResult, type MergeStrategy, type PollingConfig, PollingManager, type PollingState, PopupBuilder, PopupContentSchema, type RetryCallbacks, type RetryConfig, RetryManager, type SSEConfig, SSEConnection, type StreamConfig, StreamManager, type StreamState, type WebSocketConfig, WebSocketConnection, injectLoadingStyles, loadingStyles };

package/dist/index.js

@@ -82,7 +82,9 @@ var GeoJSONSourceSchema = z.object({
     "Polling refresh configuration"
   ),
   // Legacy support for direct refresh properties
-  refreshInterval: z.number().min(1e3).optional().describe("Polling interval in milliseconds (legacy, use refresh.refreshInterval)"),
+  refreshInterval: z.number().min(1e3).optional().describe(
+    "Polling interval in milliseconds (legacy, use refresh.refreshInterval)"
+  ),
   updateStrategy: z.enum(["replace", "merge", "append-window"]).optional().describe("Update strategy (legacy, use refresh.updateStrategy)"),
   updateKey: z.string().optional().describe("Update key (legacy, use refresh.updateKey)"),
   loading: LoadingConfigSchema.optional().describe(
@@ -91,7 +93,7 @@ var GeoJSONSourceSchema = z.object({
   cache: CacheConfigSchema.optional().describe("Cache configuration"),
   // MapLibre clustering options
   cluster: z.boolean().optional().describe("Enable point clustering"),
-  clusterRadius: z.number().int().min(0).default(50).describe("Cluster radius in pixels"),
+  clusterRadius: z.number().int().min(0).optional().describe("Cluster radius in pixels (default: 50)"),
   clusterMaxZoom: z.number().min(0).max(24).optional().describe("Maximum zoom level to cluster points"),
   clusterMinPoints: z.number().int().min(2).optional().describe("Minimum points to form a cluster"),
   clusterProperties: z.record(z.any()).optional().describe("Aggregate cluster properties"),
@@ -813,6 +815,99 @@ var YAMLParser = class {
     const validated = RootSchema.parse(config);
     return this.resolveReferences(validated);
   }
+  /**
+   * Parse YAML string for a single map block and validate against MapBlockSchema
+   *
+   * @param yaml - YAML string to parse (should be a map block, not a full document)
+   * @returns Validated map block object
+   * @throws {Error} If YAML syntax is invalid
+   * @throws {ZodError} If validation fails
+   *
+   * @remarks
+   * This method is specifically for parsing individual map blocks (e.g., in documentation
+   * or component usage). Unlike {@link parse}, it validates against MapBlockSchema rather
+   * than RootSchema, so it expects a single map configuration without the pages array wrapper.
+   *
+   * @example
+   * ```typescript
+   * const yaml = `
+   * type: map
+   * id: example
+   * config:
+   *   center: [0, 0]
+   *   zoom: 2
+   *   mapStyle: "https://example.com/style.json"
+   * layers:
+   *   - id: points
+   *     type: circle
+   *     source:
+   *       type: geojson
+   *       data: { type: "FeatureCollection", features: [] }
+   * `;
+   *
+   * const mapBlock = YAMLParser.parseMapBlock(yaml);
+   * ```
+   */
+  static parseMapBlock(yaml) {
+    let parsed;
+    try {
+      parsed = parse(yaml);
+    } catch (error) {
+      throw new Error(
+        `YAML syntax error: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+    return MapBlockSchema.parse(parsed);
+  }
+  /**
+   * Parse YAML string for a single map block, returning a result object
+   *
+   * @param yaml - YAML string to parse (should be a map block, not a full document)
+   * @returns Result object with success flag and either data or errors
+   *
+   * @remarks
+   * This is the non-throwing version of {@link parseMapBlock}. Instead of throwing
+   * errors, it returns a result object that indicates success or failure.
+   * Use this when you want to handle errors gracefully without try/catch.
+   *
+   * @example
+   * ```typescript
+   * const result = YAMLParser.safeParseMapBlock(yamlString);
+   * if (result.success) {
+   *   console.log('Map config:', result.data);
+   * } else {
+   *   result.errors.forEach(err => {
+   *     console.error(`Error at ${err.path}: ${err.message}`);
+   *   });
+   * }
+   * ```
+   */
+  static safeParseMapBlock(yaml) {
+    try {
+      const data = this.parseMapBlock(yaml);
+      return {
+        success: true,
+        data,
+        errors: []
+      };
+    } catch (error) {
+      if (error instanceof ZodError) {
+        return {
+          success: false,
+          errors: this.formatZodErrors(error)
+        };
+      }
+      return {
+        success: false,
+        errors: [
+          {
+            path: "",
+            message: error instanceof Error ? error.message : String(error)
+          }
+        ]
+      };
+    }
+  }
   /**
    * Resolve $ref references to global layers and sources
    *
@@ -3403,15 +3498,16 @@ var LayerManager = class {
       if (geojsonSource.url) {
         await this.addGeoJSONSourceFromURL(sourceId, layer.id, geojsonSource);
       } else if (geojsonSource.data) {
-        this.map.addSource(sourceId, {
+        const sourceSpec = {
           type: "geojson",
-          data: geojsonSource.data,
-          cluster: geojsonSource.cluster,
-          clusterRadius: geojsonSource.clusterRadius,
-          clusterMaxZoom: geojsonSource.clusterMaxZoom,
-          clusterMinPoints: geojsonSource.clusterMinPoints,
-          clusterProperties: geojsonSource.clusterProperties
-        });
+          data: geojsonSource.data
+        };
+        if (geojsonSource.cluster !== void 0) sourceSpec.cluster = geojsonSource.cluster;
+        if (geojsonSource.clusterRadius !== void 0) sourceSpec.clusterRadius = geojsonSource.clusterRadius;
+        if (geojsonSource.clusterMaxZoom !== void 0) sourceSpec.clusterMaxZoom = geojsonSource.clusterMaxZoom;
+        if (geojsonSource.clusterMinPoints !== void 0) sourceSpec.clusterMinPoints = geojsonSource.clusterMinPoints;
+        if (geojsonSource.clusterProperties !== void 0) sourceSpec.clusterProperties = geojsonSource.clusterProperties;
+        this.map.addSource(sourceId, sourceSpec);
       } else if (geojsonSource.stream) {
         this.map.addSource(sourceId, {
           type: "geojson",
@@ -3472,15 +3568,16 @@ var LayerManager = class {
     } else if (config.data) {
       initialData = config.data;
     }
-    this.map.addSource(sourceId, {
+    const sourceSpec = {
       type: "geojson",
-      data: initialData,
-      cluster: config.cluster,
-      clusterRadius: config.clusterRadius,
-      clusterMaxZoom: config.clusterMaxZoom,
-      clusterMinPoints: config.clusterMinPoints,
-      clusterProperties: config.clusterProperties
-    });
+      data: initialData
+    };
+    if (config.cluster !== void 0) sourceSpec.cluster = config.cluster;
+    if (config.clusterRadius !== void 0) sourceSpec.clusterRadius = config.clusterRadius;
+    if (config.clusterMaxZoom !== void 0) sourceSpec.clusterMaxZoom = config.clusterMaxZoom;
+    if (config.clusterMinPoints !== void 0) sourceSpec.clusterMinPoints = config.clusterMinPoints;
+    if (config.clusterProperties !== void 0) sourceSpec.clusterProperties = config.clusterProperties;
+    this.map.addSource(sourceId, sourceSpec);
     this.sourceData.set(sourceId, initialData);
     if (config.url && !config.prefetchedData) {
       this.callbacks.onDataLoading?.(layerId);