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

package/dist/register.d.ts

@@ -0,0 +1,205 @@
+import { Map } from 'maplibre-gl';
+import { M as MapBlock, b as MapRenderer } from './map-renderer-DOLO9y-3.js';
+import './page.schema-CzdCyPFI.js';
+import 'zod';
+
+/**
+ * @file Unified MLMap web component for maplibre-yaml
+ * @module @maplibre-yaml/core/components/ml-map
+ *
+ * @description
+ * The `<ml-map>` component is the primary way to embed MapLibre maps configured
+ * with YAML. It supports multiple configuration methods to fit any use case.
+ *
+ * ## Configuration Methods (in priority order)
+ *
+ * ### 1. External YAML File (Recommended)
+ * ```html
+ * <ml-map src="/configs/my-map.yaml"></ml-map>
+ * ```
+ *
+ * ### 2. Inline YAML via Script Tag
+ * ```html
+ * <ml-map>
+ *   <script type="text/yaml">
+ * type: map
+ * id: my-map
+ * config:
+ *   center: [-74.006, 40.7128]
+ *   zoom: 12
+ *   mapStyle: "https://demotiles.maplibre.org/style.json"
+ * layers: []
+ *   </script>
+ * </ml-map>
+ * ```
+ *
+ * ### 3. JSON Config Attribute (Programmatic)
+ * ```html
+ * <ml-map config='{"type":"map",...}'></ml-map>
+ * ```
+ */
+
+/**
+ * MLMap custom element for rendering MapLibre maps from YAML/JSON configuration.
+ *
+ * @fires ml-map:load - Map loaded and ready for interaction
+ * @fires ml-map:error - Error during initialization or runtime
+ * @fires ml-map:loading - Loading configuration from URL
+ * @fires ml-map:layer-added - Layer was added to the map
+ * @fires ml-map:layer-removed - Layer was removed from the map
+ * @fires ml-map:layer-data-loading - Layer data is being fetched
+ * @fires ml-map:layer-data-loaded - Layer data loaded successfully
+ * @fires ml-map:layer-data-error - Layer data failed to load
+ * @fires ml-map:layer-click - User clicked on a layer feature
+ * @fires ml-map:layer-hover - User hovered over a layer feature
+ */
+declare class MLMap extends HTMLElement {
+    /** Internal MapRenderer instance */
+    private renderer;
+    /** Whether the component has been initialized */
+    private initialized;
+    /** Container element for the map */
+    private mapContainer;
+    /** Parsed and validated configuration */
+    private _config;
+    /**
+     * Observed attributes that trigger attributeChangedCallback
+     */
+    static get observedAttributes(): string[];
+    /**
+     * Get the current map configuration
+     */
+    get config(): MapBlock | null;
+    /**
+     * Set the map configuration programmatically
+     */
+    set config(value: MapBlock | string | null);
+    /**
+     * Called when the element is added to the DOM
+     */
+    connectedCallback(): void;
+    /**
+     * Called when the element is removed from the DOM
+     */
+    disconnectedCallback(): void;
+    /**
+     * Called when an observed attribute changes
+     */
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * Initialize the component by detecting and loading configuration
+     */
+    private initialize;
+    /**
+     * Load and parse YAML from a script tag's text content
+     */
+    private loadFromScriptTag;
+    /**
+     * Load and parse YAML from an external URL
+     */
+    private loadFromURL;
+    /**
+     * Parse and validate JSON from the config attribute
+     */
+    private loadFromJSONAttribute;
+    /**
+     * Render the map with the given configuration
+     */
+    private renderMap;
+    /**
+     * Forward MapRenderer events to custom element events
+     */
+    private setupEventForwarding;
+    /**
+     * Handle and display errors
+     */
+    private handleError;
+    /**
+     * Escape HTML special characters for safe innerHTML usage
+     */
+    private escapeHtml;
+    /**
+     * Clean up resources when component is removed
+     */
+    private destroy;
+    /**
+     * Get the underlying MapLibre GL map instance
+     *
+     * @returns The MapLibre GL map instance, or null if not initialized
+     *
+     * @example
+     * ```javascript
+     * const mapEl = document.querySelector('ml-map');
+     *
+     * mapEl.addEventListener('ml-map:load', () => {
+     *   const map = mapEl.getMap();
+     *   map.flyTo({ center: [-122.4, 37.8], zoom: 14 });
+     * });
+     * ```
+     */
+    getMap(): Map | null;
+    /**
+     * Get the MapRenderer instance
+     *
+     * @returns The MapRenderer instance, or null if not initialized
+     */
+    getRenderer(): MapRenderer | null;
+    /**
+     * Check if the map is loaded
+     *
+     * @returns True if the map has finished loading
+     */
+    isLoaded(): boolean;
+    /**
+     * Add a layer to the map
+     *
+     * @param layer - Layer configuration object
+     * @returns Promise that resolves when the layer is added
+     *
+     * @example
+     * ```javascript
+     * await mapEl.addLayer({
+     *   id: 'new-layer',
+     *   type: 'circle',
+     *   source: {
+     *     type: 'geojson',
+     *     data: { type: 'FeatureCollection', features: [] }
+     *   },
+     *   paint: { 'circle-radius': 6, 'circle-color': '#ff0000' }
+     * });
+     * ```
+     */
+    addLayer(layer: any): Promise<void>;
+    /**
+     * Remove a layer from the map
+     *
+     * @param layerId - ID of the layer to remove
+     */
+    removeLayer(layerId: string): void;
+    /**
+     * Set layer visibility
+     *
+     * @param layerId - ID of the layer
+     * @param visible - Whether the layer should be visible
+     */
+    setLayerVisibility(layerId: string, visible: boolean): void;
+    /**
+     * Update layer data
+     *
+     * @param layerId - ID of the layer
+     * @param data - New GeoJSON data
+     */
+    updateLayerData(layerId: string, data: GeoJSON.GeoJSON): void;
+    /**
+     * Reload configuration from the current source
+     *
+     * @returns Promise that resolves when reload is complete
+     */
+    reload(): Promise<void>;
+}
+/**
+ * Register the ml-map custom element
+ */
+declare function registerMLMap(): void;
+
+export { MLMap, registerMLMap };