@maplibre-yaml/core 0.1.3-beta.1 → 0.2.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-export { ColorOrExpressionSchema, ColorSchema, ContentBlockSchema, ContentElementSchema, ContentItemSchema, ExpressionSchema, GeoJSONSourceSchema, ImageSourceSchema, LatitudeSchema, LayerSourceSchema, LngLatBoundsSchema, LngLatSchema, LoadingConfigSchema, LongitudeSchema, NumberOrExpressionSchema, RasterSourceSchema, StreamConfigSchema, ValidTagNames, VectorSourceSchema, VideoSourceSchema, ZoomLevelSchema } from './schemas/index.js';
-import { L as LayerSchema, P as PopupContentSchema, C as ControlsConfigSchema } from './page.schema-VBytF9l5.js';
-export { k as BackgroundLayerSchema, B as BaseLayerPropertiesSchema, O as Block, G as BlockSchema, y as Chapter, z as ChapterAction, v as ChapterActionSchema, A as ChapterLayers, w as ChapterLayersSchema, x as ChapterSchema, e as CircleLayerSchema, p as ControlPosition, n as ControlPositionSchema, q as ControlsConfig, i as FillExtrusionLayerSchema, F as FillLayerSchema, T as GlobalConfig, K as GlobalConfigSchema, H as HeatmapLayerSchema, j as HillshadeLayerSchema, I as InteractiveConfigSchema, m as LayerOrReferenceSchema, l as LayerReferenceSchema, r as LegendConfig, a as LegendConfigSchema, d as LegendItemSchema, f as LineLayerSchema, t as MapBlock, M as MapBlockSchema, s as MapConfig, b as MapConfigSchema, u as MapFullPageBlock, o as MapFullPageBlockSchema, N as MixedBlock, E as MixedBlockSchema, Q as Page, J as PageSchema, c as PopupContentItemSchema, h as RasterLayerSchema, U as RootConfig, R as RootSchema, D as ScrollytellingBlock, S as ScrollytellingBlockSchema, g as SymbolLayerSchema } from './page.schema-VBytF9l5.js';
-export { L as LegendBuilder, M as MapRenderer, c as MapRendererEvents, b as MapRendererOptions, P as ParseError, a as ParseResult, Y as YAMLParser, p as parseYAMLConfig, s as safeParseYAMLConfig } from './map-renderer-IvxniEQy.js';
+export { ColorOrExpressionSchema, ColorSchema, ContentBlockSchema, ContentElementSchema, ContentItemSchema, ExpressionSchema, LatitudeSchema, LngLatBoundsSchema, LngLatSchema, LongitudeSchema, NumberOrExpressionSchema, ValidTagNames, ZoomLevelSchema } from './schemas/index.js';
+import { L as LayerSchema, P as PopupContentSchema, C as ControlsConfigSchema, d as MapConfig, G as GlobalConfig, e as MapBlock } from './page.schema-Cad2FFqh.js';
+export { t as BackgroundLayerSchema, B as BaseLayerPropertiesSchema, _ as Block, W as BlockSchema, N as Chapter, O as ChapterAction, E as ChapterActionSchema, Q as ChapterLayers, J as ChapterLayersSchema, K as ChapterSchema, n as CircleLayerSchema, y as ControlPosition, w as ControlPositionSchema, z as ControlsConfig, r as FillExtrusionLayerSchema, F as FillLayerSchema, h as GeoJSONSourceSchema, Y as GlobalConfigSchema, H as HeatmapLayerSchema, s as HillshadeLayerSchema, I as ImageSourceSchema, l as InteractiveConfigSchema, v as LayerOrReferenceSchema, u as LayerReferenceSchema, c as LayerSourceSchema, A as LegendConfig, a as LegendConfigSchema, m as LegendItemSchema, o as LineLayerSchema, g as LoadingConfigSchema, M as MapBlockSchema, b as MapConfigSchema, D as MapFullPageBlock, x as MapFullPageBlockSchema, Z as MixedBlock, U as MixedBlockSchema, $ as Page, X as PageSchema, k as PopupContentItemSchema, q as RasterLayerSchema, i as RasterSourceSchema, a0 as RootConfig, R as RootSchema, T as ScrollytellingBlock, S as ScrollytellingBlockSchema, f as StreamConfigSchema, p as SymbolLayerSchema, V as VectorSourceSchema, j as VideoSourceSchema } from './page.schema-Cad2FFqh.js';
+export { L as LegendBuilder, M as MapRenderer, c as MapRendererEvents, b as MapRendererOptions, P as ParseError, a as ParseResult, Y as YAMLParser, p as parseYAMLConfig, s as safeParseYAMLConfig } from './map-renderer-8-c51Ww7.js';
 import { Map, LngLat } from 'maplibre-gl';
 import { z } from 'zod';
 import { FeatureCollection } from 'geojson';
@@ -2405,4 +2405,171 @@ 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 PollingConfig, PollingManager, type PollingState, PopupBuilder, PopupContentSchema, type RetryCallbacks, type RetryConfig, RetryManager, type SSEConfig, SSEConnection, type StreamConfig, StreamManager, type StreamState, type WebSocketConfig, WebSocketConnection, injectLoadingStyles, loadingStyles };
+/**
+ * @file Configuration resolution utilities for maplibre-yaml
+ * @module @maplibre-yaml/core/utils/config-resolver
+ *
+ * @description
+ * Utilities for resolving map configurations with global config inheritance.
+ * Enables maps to inherit default values from global configuration while
+ * allowing per-map overrides.
+ *
+ * @example
+ * ```typescript
+ * import { resolveMapConfig, resolveMapBlock } from '@maplibre-yaml/core/utils';
+ *
+ * const globalConfig = {
+ *   defaultMapStyle: 'https://demotiles.maplibre.org/style.json',
+ *   theme: 'dark'
+ * };
+ *
+ * const mapConfig = {
+ *   center: [-74.006, 40.7128],
+ *   zoom: 12
+ *   // mapStyle will be inherited from globalConfig.defaultMapStyle
+ * };
+ *
+ * const resolved = resolveMapConfig(mapConfig, globalConfig);
+ * // resolved.mapStyle === 'https://demotiles.maplibre.org/style.json'
+ * ```
+ */
+
+/**
+ * Error thrown when map configuration is invalid after resolution.
+ */
+declare class ConfigResolutionError extends Error {
+    readonly missingFields: string[];
+    constructor(message: string, missingFields: string[]);
+}
+/**
+ * Resolves a map configuration by applying global defaults.
+ *
+ * @param mapConfig - The map-specific configuration (may have optional fields)
+ * @param globalConfig - Global configuration with defaults
+ * @returns Resolved map configuration with all required fields
+ * @throws {ConfigResolutionError} If required fields are missing after resolution
+ *
+ * @remarks
+ * Resolution order (highest to lowest priority):
+ * 1. Values explicitly set in mapConfig
+ * 2. Values from globalConfig defaults
+ * 3. Error (no silent fallbacks for center, zoom, or mapStyle)
+ *
+ * **Inherited Properties:**
+ * - `mapStyle` ← `globalConfig.defaultMapStyle`
+ * - `center` ← `globalConfig.defaultCenter`
+ * - `zoom` ← `globalConfig.defaultZoom`
+ *
+ * @example Basic Resolution
+ * ```typescript
+ * const resolved = resolveMapConfig(
+ *   { center: [0, 0], zoom: 5 },
+ *   { defaultMapStyle: 'https://example.com/style.json' }
+ * );
+ * // resolved.mapStyle === 'https://example.com/style.json'
+ * ```
+ *
+ * @example Inherit zoom/center from global
+ * ```typescript
+ * const resolved = resolveMapConfig(
+ *   { mapStyle: 'https://example.com/style.json' },
+ *   { defaultCenter: [-74.006, 40.7128], defaultZoom: 10 }
+ * );
+ * // resolved.center === [-74.006, 40.7128]
+ * // resolved.zoom === 10
+ * ```
+ */
+declare function resolveMapConfig(mapConfig: Partial<MapConfig>, globalConfig: GlobalConfig): MapConfig;
+declare function resolveMapConfig(mapConfig: Partial<MapConfig> & {
+    center: [number, number];
+    zoom: number;
+}, globalConfig?: GlobalConfig): MapConfig;
+/**
+ * Resolves a complete MapBlock by applying global defaults to its config.
+ *
+ * @param mapBlock - The map block with potentially incomplete config
+ * @param globalConfig - Global configuration with defaults
+ * @returns Resolved map block with complete configuration
+ * @throws {ConfigResolutionError} If required fields are missing after resolution
+ *
+ * @remarks
+ * This function resolves the `config` property of a MapBlock while preserving
+ * all other block properties (layers, controls, legend, etc.).
+ *
+ * @example
+ * ```typescript
+ * const mapBlock = {
+ *   type: 'map',
+ *   id: 'my-map',
+ *   config: { center: [0, 0], zoom: 5 },
+ *   layers: [...]
+ * };
+ *
+ * const resolved = resolveMapBlock(mapBlock, {
+ *   defaultMapStyle: 'https://example.com/style.json'
+ * });
+ * // resolved.config.mapStyle === 'https://example.com/style.json'
+ * ```
+ */
+declare function resolveMapBlock(mapBlock: MapBlock, globalConfig?: GlobalConfig): MapBlock;
+/**
+ * Checks if a map configuration has all required fields.
+ *
+ * @param mapConfig - Map configuration to validate
+ * @returns True if all required fields are present
+ *
+ * @remarks
+ * Use this to check if a config needs resolution before rendering.
+ *
+ * @example
+ * ```typescript
+ * if (!isMapConfigComplete(config)) {
+ *   config = resolveMapConfig(config, globalConfig);
+ * }
+ * ```
+ */
+declare function isMapConfigComplete(mapConfig: Partial<MapConfig>): mapConfig is MapConfig;
+/**
+ * Creates a map configuration with sensible defaults for simple use cases.
+ *
+ * @param options - Minimal configuration options
+ * @param globalConfig - Optional global configuration for defaults
+ * @returns Complete map configuration
+ *
+ * @remarks
+ * This is a convenience function for creating simple map configurations
+ * without needing to specify every field. Useful for collection items and
+ * content-focused applications.
+ *
+ * **Default Values:**
+ * - `zoom`: 12
+ * - `pitch`: 0
+ * - `bearing`: 0
+ * - `interactive`: true
+ *
+ * @example Simple Location Map
+ * ```typescript
+ * const config = createSimpleMapConfig({
+ *   center: [-74.006, 40.7128],
+ *   mapStyle: 'https://example.com/style.json'
+ * });
+ * ```
+ *
+ * @example With Global Style
+ * ```typescript
+ * const config = createSimpleMapConfig(
+ *   { center: [-74.006, 40.7128] },
+ *   { defaultMapStyle: 'https://example.com/style.json' }
+ * );
+ * ```
+ */
+declare function createSimpleMapConfig(options: {
+    center: [number, number];
+    zoom?: number;
+    mapStyle?: string;
+    pitch?: number;
+    bearing?: number;
+    interactive?: boolean;
+}, globalConfig?: GlobalConfig): MapConfig;
+
+export { BaseConnection, type CacheConfig, type CacheEntry, type CacheStats, ConfigResolutionError, type ConnectionConfig, type ConnectionEvents, type ConnectionState, ControlsConfigSchema, ControlsManager, DataFetcher, DataMerger, EventEmitter, type EventHandler, type EventHandlerCallbacks, type FetchOptions, type FetchResult, type FetcherConfig, GlobalConfig, LayerManager, type LayerManagerCallbacks, LayerSchema, type LoadingConfig, type LoadingEvents, LoadingManager, type LoadingState, MapBlock, MapConfig, 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, createSimpleMapConfig, injectLoadingStyles, isMapConfigComplete, loadingStyles, resolveMapBlock, resolveMapConfig };

package/dist/index.js

@@ -585,6 +585,7 @@ var MapBlockSchema = z.object({
   className: z.string().optional().describe("CSS class name for container"),
   style: z.string().optional().describe("Inline CSS styles for container"),
   config: MapConfigSchema.describe("Map configuration"),
+  sources: z.record(z.string(), LayerSourceSchema).optional().describe("Map sources"),
   layers: z.array(LayerOrReferenceSchema).default([]).describe("Map layers"),
   controls: ControlsConfigSchema.optional().describe("Map controls"),
   legend: LegendConfigSchema.optional().describe("Legend configuration")
@@ -595,6 +596,7 @@ var MapFullPageBlockSchema = z.object({
   className: z.string().optional().describe("CSS class name for container"),
   style: z.string().optional().describe("Inline CSS styles for container"),
   config: MapConfigSchema.describe("Map configuration"),
+  sources: z.record(z.string(), LayerSourceSchema).optional().describe("Map sources"),
   layers: z.array(LayerOrReferenceSchema).default([]).describe("Map layers"),
   controls: ControlsConfigSchema.optional().describe("Map controls"),
   legend: LegendConfigSchema.optional().describe("Legend configuration")
@@ -698,6 +700,10 @@ var GlobalConfigSchema = z.object({
   description: z.string().optional().describe("Application description"),
   defaultMapStyle: z.string().url().optional().describe("Default map style URL"),
   theme: z.enum(["light", "dark"]).default("light").describe("Default theme"),
+  defaultZoom: z.number().min(0).max(24).optional().describe("Default zoom level for all maps"),
+  defaultCenter: LngLatSchema.optional().describe(
+    "Default center [lng, lat] for all maps"
+  ),
   dataFetching: z.object({
     defaultStrategy: z.enum(["runtime", "build", "hybrid"]).default("runtime").describe("Default fetch strategy"),
     timeout: z.number().min(1e3).default(3e4).describe("Default timeout in milliseconds"),
@@ -3556,9 +3562,16 @@ var LayerManager = class {
     this.abortControllers = /* @__PURE__ */ new Map();
   }
   async addLayer(layer) {
-    const sourceId = `${layer.id}-source`;
+    const isSourceRef = typeof layer.source === "string";
+    const sourceId = isSourceRef ? layer.source : `${layer.id}-source`;
     this.layerToSource.set(layer.id, sourceId);
-    await this.addSource(sourceId, layer);
+    if (!isSourceRef) {
+      await this.addSource(sourceId, layer);
+    } else if (!this.map.getSource(sourceId)) {
+      throw new Error(
+        `Source '${sourceId}' referenced by layer '${layer.id}' not found. Ensure it is defined in the block-level 'sources' map.`
+      );
+    }
     const layerSpec = {
       id: layer.id,
       type: layer.type,
@@ -3586,12 +3599,6 @@ var LayerManager = class {
     }
   }
   async addSource(sourceId, layer) {
-    if (typeof layer.source === "string") {
-      if (!this.map.getSource(layer.source)) {
-        throw new Error(`Source reference '${layer.source}' not found`);
-      }
-      return;
-    }
     const source = layer.source;
     if (source.type === "geojson") {
       const geojsonSource = source;
@@ -3811,7 +3818,10 @@ var LayerManager = class {
     }
     if (this.map.getLayer(layerId)) this.map.removeLayer(layerId);
     const sourceId = this.layerToSource.get(layerId) || `${layerId}-source`;
-    if (this.map.getSource(sourceId)) this.map.removeSource(sourceId);
+    const isInlineSource = sourceId === `${layerId}-source`;
+    if (isInlineSource && this.map.getSource(sourceId)) {
+      this.map.removeSource(sourceId);
+    }
     this.sourceData.delete(sourceId);
     this.layerToSource.delete(layerId);
   }
@@ -4173,7 +4183,7 @@ var MapRenderer = class {
   controlsManager;
   eventListeners;
   isLoaded;
-  constructor(container, config, layers = [], options = {}) {
+  constructor(container, config, layers = [], options = {}, sources) {
     this.eventListeners = /* @__PURE__ */ new Map();
     this.isLoaded = false;
     this.map = new maplibregl2.Map({
@@ -4201,6 +4211,13 @@ var MapRenderer = class {
     this.controlsManager = new ControlsManager(this.map);
     this.map.on("load", () => {
       this.isLoaded = true;
+      if (sources) {
+        for (const [id, sourceSpec] of Object.entries(sources)) {
+          if (!this.map.getSource(id)) {
+            this.map.addSource(id, sourceSpec);
+          }
+        }
+      }
       Promise.all(layers.map((layer) => this.addLayer(layer))).then(() => {
         this.emit("load", void 0);
         options.onLoad?.();
@@ -4497,6 +4514,67 @@ function injectLoadingStyles() {
   document.head.appendChild(style);
 }
 
-export { BackgroundLayerSchema, BaseConnection, BaseLayerPropertiesSchema, BlockSchema, ChapterActionSchema, ChapterLayersSchema, ChapterSchema, CircleLayerSchema, ColorOrExpressionSchema, ColorSchema, ContentBlockSchema, ContentElementSchema, ContentItemSchema, ControlPositionSchema, ControlsConfigSchema, ControlsManager, DataFetcher, DataMerger, EventEmitter, EventHandler, ExpressionSchema, FillExtrusionLayerSchema, FillLayerSchema, GeoJSONSourceSchema, GlobalConfigSchema, HeatmapLayerSchema, HillshadeLayerSchema, ImageSourceSchema, InteractiveConfigSchema, LatitudeSchema, LayerManager, LayerOrReferenceSchema, LayerReferenceSchema, LayerSchema, LayerSourceSchema, LegendBuilder, LegendConfigSchema, LegendItemSchema, LineLayerSchema, LngLatBoundsSchema, LngLatSchema, LoadingConfigSchema, LoadingManager, LongitudeSchema, MapBlockSchema, MapConfigSchema, MapFullPageBlockSchema, MapRenderer, MaxRetriesExceededError, MemoryCache, MixedBlockSchema, NumberOrExpressionSchema, PageSchema, PollingManager, PopupBuilder, PopupContentItemSchema, PopupContentSchema, RasterLayerSchema, RasterSourceSchema, RetryManager, RootSchema, SSEConnection, ScrollytellingBlockSchema, StreamConfigSchema, StreamManager, SymbolLayerSchema, ValidTagNames, VectorSourceSchema, VideoSourceSchema, WebSocketConnection, YAMLParser, ZoomLevelSchema, injectLoadingStyles, loadingStyles, parseYAMLConfig, safeParseYAMLConfig };
+// src/utils/config-resolver.ts
+var ConfigResolutionError = class extends Error {
+  constructor(message, missingFields) {
+    super(message);
+    this.missingFields = missingFields;
+    this.name = "ConfigResolutionError";
+  }
+};
+function resolveMapConfig(mapConfig, globalConfig) {
+  const center = mapConfig.center ?? globalConfig?.defaultCenter;
+  const zoom = mapConfig.zoom ?? globalConfig?.defaultZoom;
+  const resolved = {
+    ...mapConfig,
+    center,
+    zoom,
+    mapStyle: mapConfig.mapStyle ?? globalConfig?.defaultMapStyle,
+    interactive: mapConfig.interactive ?? true,
+    pitch: mapConfig.pitch ?? 0,
+    bearing: mapConfig.bearing ?? 0
+  };
+  const missingFields = [];
+  if (!resolved.mapStyle) {
+    missingFields.push("mapStyle");
+  }
+  if (resolved.center === void 0) {
+    missingFields.push("center");
+  }
+  if (resolved.zoom === void 0) {
+    missingFields.push("zoom");
+  }
+  if (missingFields.length > 0) {
+    throw new ConfigResolutionError(
+      `Map configuration is missing required fields: ${missingFields.join(
+        ", "
+      )}. Either provide these fields in the map config or set defaults in global config (e.g., config.defaultMapStyle, config.defaultCenter, config.defaultZoom).`,
+      missingFields
+    );
+  }
+  return resolved;
+}
+function resolveMapBlock(mapBlock, globalConfig) {
+  return {
+    ...mapBlock,
+    config: resolveMapConfig(mapBlock.config, globalConfig)
+  };
+}
+function isMapConfigComplete(mapConfig) {
+  return mapConfig.center !== void 0 && mapConfig.zoom !== void 0 && mapConfig.mapStyle !== void 0;
+}
+function createSimpleMapConfig(options, globalConfig) {
+  const config = {
+    center: options.center,
+    zoom: options.zoom ?? 12,
+    mapStyle: options.mapStyle,
+    pitch: options.pitch ?? 0,
+    bearing: options.bearing ?? 0,
+    interactive: options.interactive ?? true
+  };
+  return resolveMapConfig(config, globalConfig);
+}
+
+export { BackgroundLayerSchema, BaseConnection, BaseLayerPropertiesSchema, BlockSchema, ChapterActionSchema, ChapterLayersSchema, ChapterSchema, CircleLayerSchema, ColorOrExpressionSchema, ColorSchema, ConfigResolutionError, ContentBlockSchema, ContentElementSchema, ContentItemSchema, ControlPositionSchema, ControlsConfigSchema, ControlsManager, DataFetcher, DataMerger, EventEmitter, EventHandler, ExpressionSchema, FillExtrusionLayerSchema, FillLayerSchema, GeoJSONSourceSchema, GlobalConfigSchema, HeatmapLayerSchema, HillshadeLayerSchema, ImageSourceSchema, InteractiveConfigSchema, LatitudeSchema, LayerManager, LayerOrReferenceSchema, LayerReferenceSchema, LayerSchema, LayerSourceSchema, LegendBuilder, LegendConfigSchema, LegendItemSchema, LineLayerSchema, LngLatBoundsSchema, LngLatSchema, LoadingConfigSchema, LoadingManager, LongitudeSchema, MapBlockSchema, MapConfigSchema, MapFullPageBlockSchema, MapRenderer, MaxRetriesExceededError, MemoryCache, MixedBlockSchema, NumberOrExpressionSchema, PageSchema, PollingManager, PopupBuilder, PopupContentItemSchema, PopupContentSchema, RasterLayerSchema, RasterSourceSchema, RetryManager, RootSchema, SSEConnection, ScrollytellingBlockSchema, StreamConfigSchema, StreamManager, SymbolLayerSchema, ValidTagNames, VectorSourceSchema, VideoSourceSchema, WebSocketConnection, YAMLParser, ZoomLevelSchema, createSimpleMapConfig, injectLoadingStyles, isMapConfigComplete, loadingStyles, parseYAMLConfig, resolveMapBlock, resolveMapConfig, safeParseYAMLConfig };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map