maplibre-gl-layer-control-tidop 0.0.1

package/dist/types/index.d.ts

@@ -0,0 +1,796 @@
+import { IControl } from 'maplibre-gl';
+import { LayerSpecification } from 'maplibre-gl';
+import { Map as Map_2 } from 'maplibre-gl';
+
+/**
+ * Clamp a numeric value between min and max
+ * @param value Value to clamp
+ * @param min Minimum value
+ * @param max Maximum value
+ * @returns Clamped value
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+
+/**
+ * Create an SVG symbol for the Background layer group
+ * @param size Symbol size in pixels (default: 16)
+ * @returns SVG markup string
+ */
+export declare function createBackgroundGroupSymbolSVG(size?: number): string;
+
+/**
+ * Create an SVG symbol for a layer type
+ * @param layerType The MapLibre layer type
+ * @param color The primary color (hex format), or null for default
+ * @param options Optional configuration
+ * @returns SVG markup string
+ */
+export declare function createLayerSymbolSVG(layerType: string, color: string | null, options?: SymbolOptions): string;
+
+/**
+ * Adapter interface for custom (non-MapLibre) layers.
+ * Implement this interface to integrate custom layer types (e.g., deck.gl layers)
+ * with the layer control.
+ */
+export declare interface CustomLayerAdapter {
+    /** Unique type identifier for this adapter (e.g., 'cog', 'zarr', 'deck') */
+    type: string;
+    /** Get all layer IDs managed by this adapter */
+    getLayerIds(): string[];
+    /** Get the current state of a layer */
+    getLayerState(layerId: string): LayerState | null;
+    /** Set layer visibility */
+    setVisibility(layerId: string, visible: boolean): void;
+    /** Set layer opacity (0-1) */
+    setOpacity(layerId: string, opacity: number): void;
+    /** Get display name for a layer */
+    getName(layerId: string): string;
+    /** Get layer symbol type for UI display (optional) */
+    getSymbolType?(layerId: string): string;
+    /**
+     * Subscribe to layer changes (add/remove).
+     * Returns an unsubscribe function.
+     */
+    onLayerChange?(callback: (event: 'add' | 'remove', layerId: string) => void): () => void;
+    /**
+     * Get the bounds of a layer (optional).
+     * Returns [west, south, east, north] or null if not available.
+     */
+    getBounds?(layerId: string): [number, number, number, number] | null;
+    /**
+     * Remove a layer (optional).
+     * Called when user removes a layer via context menu.
+     */
+    removeLayer?(layerId: string): void;
+    /**
+     * Get native MapLibre layer IDs for a custom layer (optional).
+     * When provided, the style editor will show paint property controls
+     * for these native layers instead of the generic "custom layer" message.
+     */
+    getNativeLayerIds?(layerId: string): string[];
+}
+
+/**
+ * Registry for managing custom layer adapters.
+ * Routes layer operations to the appropriate adapter based on layer ID.
+ */
+export declare class CustomLayerRegistry {
+    private adapters;
+    private changeListeners;
+    private unsubscribers;
+    /**
+     * Register a custom layer adapter.
+     * @param adapter The adapter to register
+     */
+    register(adapter: CustomLayerAdapter): void;
+    /**
+     * Unregister an adapter by type.
+     * @param type The adapter type to unregister
+     */
+    unregister(type: string): void;
+    /**
+     * Get all custom layer IDs across all adapters.
+     * @returns Array of layer IDs
+     */
+    getAllLayerIds(): string[];
+    /**
+     * Check if a layer ID is managed by any adapter.
+     * @param layerId The layer ID to check
+     * @returns true if the layer is managed by an adapter
+     */
+    hasLayer(layerId: string): boolean;
+    /**
+     * Get the adapter responsible for a specific layer.
+     * @param layerId The layer ID
+     * @returns The adapter or null if not found
+     */
+    getAdapterForLayer(layerId: string): CustomLayerAdapter | null;
+    /**
+     * Get the state of a custom layer.
+     * @param layerId The layer ID
+     * @returns The layer state or null if not found
+     */
+    getLayerState(layerId: string): LayerState | null;
+    /**
+     * Set visibility of a custom layer.
+     * @param layerId The layer ID
+     * @param visible Whether the layer should be visible
+     * @returns true if the operation was handled by an adapter
+     */
+    setVisibility(layerId: string, visible: boolean): boolean;
+    /**
+     * Set opacity of a custom layer.
+     * @param layerId The layer ID
+     * @param opacity The opacity value (0-1)
+     * @returns true if the operation was handled by an adapter
+     */
+    setOpacity(layerId: string, opacity: number): boolean;
+    /**
+     * Get the symbol type for a custom layer (for UI display).
+     * @param layerId The layer ID
+     * @returns The symbol type or null if not available
+     */
+    getSymbolType(layerId: string): string | null;
+    /**
+     * Get the bounds of a custom layer (for zoom-to-layer).
+     * @param layerId The layer ID
+     * @returns The bounds [west, south, east, north] or null if not available
+     */
+    getBounds(layerId: string): [number, number, number, number] | null;
+    /**
+     * Get native MapLibre layer IDs for a custom layer.
+     * @param layerId The custom layer ID
+     * @returns Array of native layer IDs, or null if not available
+     */
+    getNativeLayerIds(layerId: string): string[] | null;
+    /**
+     * Remove a custom layer through its adapter.
+     * @param layerId The layer ID to remove
+     * @returns true if the operation was handled by an adapter
+     */
+    removeLayer(layerId: string): boolean;
+    /**
+     * Subscribe to layer changes across all adapters.
+     * @param callback Function called when layers are added or removed
+     * @returns Unsubscribe function
+     */
+    onChange(callback: (event: 'add' | 'remove', layerId: string) => void): () => void;
+    private notifyChange;
+    /**
+     * Clean up all subscriptions and adapters.
+     */
+    destroy(): void;
+}
+
+/**
+ * Darken a hex color by a given amount
+ * @param hexColor The hex color to darken (e.g., '#ff0000')
+ * @param amount Amount to darken (0-1, where 1 is fully black)
+ * @returns The darkened hex color
+ */
+export declare function darkenColor(hexColor: string, amount: number): string;
+
+/**
+ * Format a numeric value based on the step size
+ * @param value Numeric value to format
+ * @param step Step size (determines decimal places)
+ * @returns Formatted string
+ */
+export declare function formatNumericValue(value: number, step: number): string;
+
+/**
+ * Get the primary color from a layer's paint properties
+ * @param map The MapLibre map instance
+ * @param layerId The layer ID
+ * @param layerType The layer type
+ * @returns The normalized hex color, or null if not found
+ */
+export declare function getLayerColor(map: Map_2, layerId: string, layerType: string): string | null;
+
+/**
+ * Get the primary color directly from a layer specification
+ * @param layer The layer specification
+ * @returns The normalized hex color, or null if not found
+ */
+export declare function getLayerColorFromSpec(layer: LayerSpecification): string | null;
+
+/**
+ * Get the current opacity value for a layer
+ * @param map MapLibre map instance
+ * @param layerId Layer ID
+ * @param layerType Layer type
+ * @returns Current opacity value (0-1), or 1.0 if the layer type doesn't support opacity
+ */
+export declare function getLayerOpacity(map: Map_2, layerId: string, layerType: string): number;
+
+/**
+ * Get layer type from map
+ * @param map MapLibre map instance
+ * @param layerId Layer ID
+ * @returns Layer type or null if layer not found
+ */
+export declare function getLayerType(map: Map_2, layerId: string): string | null;
+
+/**
+ * Check if a layer type supports style editing
+ * @param layerType Layer type
+ * @returns True if the layer type supports style editing
+ */
+export declare function isStyleableLayerType(layerType: string): layerType is StyleableLayerType;
+
+/**
+ * LayerControl - A comprehensive layer control for MapLibre GL
+ * Provides visibility toggle, opacity control, and advanced style editing
+ */
+export declare class LayerControl implements IControl {
+    private map;
+    private mapContainer;
+    private container;
+    private button;
+    private panel;
+    private resizeHandler;
+    private mapResizeHandler;
+    private state;
+    private targetLayers;
+    private styleEditors;
+    private initialSourceIds;
+    private initialLayerIds;
+    private minPanelWidth;
+    private maxPanelWidth;
+    private maxPanelHeight;
+    private showStyleEditor;
+    private showOpacitySlider;
+    private showLayerSymbol;
+    private excludeDrawnLayers;
+    private excludeLayerPatterns;
+    private customLayerRegistry;
+    private customLayerUnsubscribe;
+    private removedCustomLayerIds;
+    private nativeLayerGroups;
+    private basemapStyleUrl;
+    private basemapLayerIds;
+    private widthSliderEl;
+    private widthThumbEl;
+    private widthValueEl;
+    private isWidthSliderActive;
+    private widthDragRectWidth;
+    private widthDragStartX;
+    private widthDragStartWidth;
+    private widthFrame;
+    private contextMenuEl;
+    private enableContextMenu;
+    private enableDragAndDrop;
+    private onLayerRename?;
+    private onLayerReorder?;
+    private onLayerRemove?;
+    constructor(options?: LayerControlOptions);
+    /**
+     * Called when the control is added to the map
+     */
+    onAdd(map: Map_2): HTMLElement;
+    /**
+     * Fetch the basemap style JSON and extract layer IDs.
+     * This provides reliable distinction between basemap and user-added layers.
+     */
+    private fetchBasemapStyle;
+    /**
+     * Called when the control is removed from the map
+     */
+    onRemove(): void;
+    /**
+     * Auto-detect layers from the map and populate layerStates
+     */
+    private autoDetectLayers;
+    /**
+     * Detect which sources are user-added (not from the basemap style)
+     * User-added sources are identified by:
+     * - Sources that were NOT present when the control was first added
+     * - Additionally for sources added later:
+     *   - GeoJSON sources with inline data objects (not URL strings)
+     *   - Image, video, canvas sources
+     *   - Raster, raster-dem, vector sources from non-basemap tile providers
+     */
+    private detectUserAddedSources;
+    /**
+     * Generate a friendly display name from a layer ID
+     */
+    private generateFriendlyName;
+    /**
+     * Check if a layer ID belongs to a drawing library (Geoman, Mapbox GL Draw, etc.)
+     * @param layerId The layer ID to check
+     * @returns true if the layer is from a drawing library
+     */
+    private isDrawnLayer;
+    /**
+     * Convert wildcard patterns (e.g., '*-temp-*', 'debug-*') to RegExp objects
+     */
+    private wildcardPatternsToRegex;
+    /**
+     * Check if a layer matches any of the user-defined exclusion patterns
+     */
+    private isExcludedByPattern;
+    /**
+     * Create the main container element
+     */
+    private createContainer;
+    /**
+     * Create the toggle button
+     */
+    private createToggleButton;
+    /**
+     * Create the panel element
+     */
+    private createPanel;
+    /**
+     * Detect which corner the control is positioned in
+     * @returns The position: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+     */
+    private getControlPosition;
+    /**
+     * Update the panel position based on button location and control corner
+     * Positions the panel next to the button, expanding in the appropriate direction
+     */
+    private updatePanelPosition;
+    /**
+     * Create action buttons for Show All / Hide All
+     */
+    private createActionButtons;
+    /**
+     * Set visibility of all layers
+     */
+    private setAllLayersVisibility;
+    /**
+     * Create the panel header with title and width control
+     */
+    private createPanelHeader;
+    /**
+     * Create the width control slider
+     */
+    private createWidthControl;
+    /**
+     * Setup event listeners for width slider
+     */
+    private setupWidthSliderEvents;
+    /**
+     * Update panel width from pointer event
+     */
+    private updateWidthFromPointer;
+    /**
+     * Apply panel width (clamped to min/max)
+     */
+    private applyPanelWidth;
+    /**
+     * Update width display (value label and thumb position)
+     */
+    private updateWidthDisplay;
+    /**
+     * Setup main event listeners
+     */
+    private setupEventListeners;
+    /**
+     * Setup listeners for map layer changes
+     */
+    private setupLayerChangeListeners;
+    /**
+     * Toggle panel expanded/collapsed state
+     */
+    private toggle;
+    /**
+     * Expand the panel
+     */
+    private expand;
+    /**
+     * Collapse the panel
+     */
+    private collapse;
+    /**
+     * Build layer items (called initially and when layers change)
+     */
+    private buildLayerItems;
+    /**
+     * Add a single layer item to the panel
+     */
+    private addLayerItem;
+    /**
+     * Create a symbol element for a layer
+     * @param layerId The layer ID
+     * @returns The symbol HTML element, or null if layer not found
+     */
+    private createLayerSymbol;
+    /**
+     * Create a symbol element for a background layer
+     * @param layer The layer specification
+     * @returns The symbol HTML element
+     */
+    private createBackgroundLayerSymbol;
+    /**
+     * Create a symbol element for the Background layer group
+     * Shows a stacked layers icon to represent multiple background layers
+     * @returns The symbol HTML element
+     */
+    private createBackgroundGroupSymbol;
+    /**
+     * Toggle layer visibility
+     */
+    private toggleLayerVisibility;
+    /**
+     * Change layer opacity
+     */
+    private changeLayerOpacity;
+    /**
+     * Check if a layer is a user-added layer (vs basemap layer)
+     * Used primarily for the background legend to determine which layers are background
+     */
+    private isUserAddedLayer;
+    /**
+     * Toggle visibility for all background layers (basemap layers)
+     */
+    private toggleBackgroundVisibility;
+    /**
+     * Change opacity for all background layers (basemap layers)
+     */
+    private changeBackgroundOpacity;
+    /**
+     * Create legend button for Background layer
+     */
+    private createBackgroundLegendButton;
+    /**
+     * Toggle background legend panel visibility
+     */
+    private toggleBackgroundLegend;
+    /**
+     * Open background legend panel
+     */
+    private openBackgroundLegend;
+    /**
+     * Close background legend panel
+     */
+    private closeBackgroundLegend;
+    /**
+     * Create the background legend panel with individual layer controls
+     */
+    private createBackgroundLegendPanel;
+    /**
+     * Check if a layer is currently rendered in the map viewport
+     */
+    private isLayerRendered;
+    /**
+     * Populate the background layer list with individual layers
+     */
+    private populateBackgroundLayerList;
+    /**
+     * Toggle visibility of an individual background layer
+     */
+    private toggleIndividualBackgroundLayer;
+    /**
+     * Set visibility for all background layers
+     */
+    private setAllBackgroundLayersVisibility;
+    /**
+     * Update the main Background checkbox based on individual layer states
+     */
+    private updateBackgroundCheckboxState;
+    /**
+     * Create style button for a layer
+     */
+    private createStyleButton;
+    /**
+     * Toggle style editor for a layer
+     */
+    private toggleStyleEditor;
+    /**
+     * Open style editor for a layer
+     */
+    private openStyleEditor;
+    /**
+     * Create info panel for custom layers (style editing not supported)
+     */
+    private createCustomLayerInfoPanel;
+    /**
+     * Create a combined style editor for custom layers with native MapLibre sublayers.
+     * Groups controls by sublayer type (fill, line, circle, etc.).
+     */
+    private createNativeSubLayerStyleEditor;
+    /**
+     * Add style controls for a group of native layers of the same type.
+     * Changes to any control are applied to all layers in the group.
+     */
+    private addStyleControlsForNativeGroup;
+    /**
+     * Close style editor for a layer
+     */
+    private closeStyleEditor;
+    /**
+     * Create style editor UI
+     */
+    private createStyleEditor;
+    /**
+     * Add style controls based on layer type
+     */
+    private addStyleControlsForLayerType;
+    /**
+     * Add controls for fill layers
+     */
+    private addFillControls;
+    /**
+     * Add controls for line layers
+     */
+    private addLineControls;
+    /**
+     * Add controls for circle layers
+     */
+    private addCircleControls;
+    /**
+     * Add controls for raster layers
+     */
+    private addRasterControls;
+    /**
+     * Add controls for symbol layers
+     */
+    private addSymbolControls;
+    /**
+     * Create a color control
+     */
+    private createColorControl;
+    /**
+     * Create a slider control
+     */
+    private createSliderControl;
+    /**
+     * Reset layer style to original
+     */
+    private resetLayerStyle;
+    /**
+     * Update layer states from map (sync UI with map)
+     */
+    private updateLayerStatesFromMap;
+    /**
+     * Update UI elements for a specific layer
+     */
+    private updateUIForLayer;
+    /**
+     * Check for new layers and add them to the control, remove deleted layers
+     */
+    private checkForNewLayers;
+    /**
+     * Register a custom layer adapter dynamically.
+     * This allows adding adapters after the LayerControl has been initialized.
+     * @param adapter The custom layer adapter to register
+     */
+    registerCustomAdapter(adapter: CustomLayerAdapter): void;
+    /**
+     * Create context menu element
+     */
+    private createContextMenu;
+    /**
+     * Create a context menu item
+     */
+    private createContextMenuItem;
+    /**
+     * Show context menu at position
+     */
+    private showContextMenu;
+    /**
+     * Hide context menu
+     */
+    private hideContextMenu;
+    /**
+     * Start renaming a layer
+     */
+    private startRenaming;
+    /**
+     * Zoom to a layer's bounds
+     */
+    private zoomToLayer;
+    /**
+     * Get user layer IDs in current map order (top to bottom in UI = high z-index to low)
+     * Includes both MapLibre layers and custom layers managed by adapters.
+     */
+    private getUserLayerIdsInMapOrder;
+    /**
+     * Check if a layer is a MapLibre layer (not a custom layer)
+     */
+    private isMapLibreLayer;
+    /**
+     * Find the next MapLibre layer ID in a direction from a given index
+     * @param layerIds Array of layer IDs
+     * @param startIndex Index to start searching from
+     * @param direction 1 for forward (toward bottom), -1 for backward (toward top)
+     * @returns MapLibre layer ID or undefined if not found
+     */
+    private findNextMapLibreLayer;
+    /**
+     * Move a layer up in UI (higher rendering order = move to higher z-index)
+     */
+    private moveLayerUp;
+    /**
+     * Move a layer to the top (highest rendering order)
+     */
+    private moveLayerToTop;
+    /**
+     * Move a layer down in UI (lower rendering order = move to lower z-index)
+     */
+    private moveLayerDown;
+    /**
+     * Move a layer to the bottom (lowest rendering order among user layers)
+     */
+    private moveLayerToBottom;
+    /**
+     * Remove a layer from the map
+     */
+    private removeLayer;
+    /**
+     * Create drag handle element
+     */
+    private createDragHandle;
+    /**
+     * Create a disabled drag handle for alignment (used for Background layer)
+     */
+    private createDisabledDragHandle;
+    /**
+     * Start dragging a layer
+     */
+    private startDrag;
+    /**
+     * Handle drag move
+     */
+    private onDragMove;
+    /**
+     * End dragging
+     */
+    private endDrag;
+    /**
+     * Clean up drag state
+     */
+    private cleanupDragState;
+    /**
+     * Apply UI order to map layers
+     */
+    private applyUIOrderToMap;
+}
+
+/**
+ * Options for LayerControl constructor
+ */
+export declare interface LayerControlOptions {
+    /** Whether the control starts collapsed (default: true) */
+    collapsed?: boolean;
+    /** Initial layer states (keyed by layer ID) */
+    layerStates?: LayerStates;
+    /** Array of layer IDs to control (if not specified, controls all layers) */
+    layers?: string[];
+    /** Initial panel width in pixels (default: 320) */
+    panelWidth?: number;
+    /** Minimum panel width in pixels (default: 240) */
+    panelMinWidth?: number;
+    /** Maximum panel width in pixels (default: 420) */
+    panelMaxWidth?: number;
+    /** Whether to show the style editor button (gear icon) for layers (default: true) */
+    showStyleEditor?: boolean;
+    /** Whether to show the opacity slider for layers (default: true) */
+    showOpacitySlider?: boolean;
+    /** Whether to show layer type symbols/icons next to layer names (default: true) */
+    showLayerSymbol?: boolean;
+    /** Maximum panel height in pixels (default: 600). When content exceeds this height, the panel becomes scrollable. */
+    panelMaxHeight?: number;
+    /** Whether to exclude drawn layers from drawing libraries like Geoman, Mapbox GL Draw, etc. (default: true) */
+    excludeDrawnLayers?: boolean;
+    /** Array of wildcard patterns to exclude layers by name (e.g., ['*-temp-*', 'debug-*']) */
+    excludeLayers?: string[];
+    /** Custom layer adapters for non-MapLibre layers (e.g., deck.gl COG layers, Zarr layers) */
+    customLayerAdapters?: CustomLayerAdapter[];
+    /**
+     * URL of the basemap style JSON. If provided, all layers defined in this style
+     * will be grouped under "Background", and all other layers will be shown individually
+     * in the layer control. This provides reliable distinction between basemap layers
+     * and user-added layers.
+     */
+    basemapStyleUrl?: string;
+    /** Whether to enable context menu (right-click) on layers (default: true) */
+    enableContextMenu?: boolean;
+    /** Whether to enable drag-and-drop reordering of layers (default: true) */
+    enableDragAndDrop?: boolean;
+    /** Callback when a layer is renamed via context menu */
+    onLayerRename?: (layerId: string, oldName: string, newName: string) => void;
+    /** Callback when layers are reordered via drag-and-drop */
+    onLayerReorder?: (layerOrder: string[]) => void;
+    /** Callback when a layer is removed via context menu */
+    onLayerRemove?: (layerId: string) => void;
+}
+
+/**
+ * State for a single layer
+ */
+export declare interface LayerState {
+    /** Whether the layer is visible */
+    visible: boolean;
+    /** Layer opacity (0-1) */
+    opacity: number;
+    /** Display name for the layer */
+    name: string;
+    /** Whether this is a custom (non-MapLibre) layer */
+    isCustomLayer?: boolean;
+    /** Custom layer type identifier (e.g., 'cog', 'zarr') */
+    customLayerType?: string;
+}
+
+/**
+ * Collection of layer states keyed by layer ID
+ */
+export declare interface LayerStates {
+    [layerId: string]: LayerState;
+}
+
+/**
+ * Normalize a color value to hex format
+ * Handles hex strings, RGB strings, and RGB arrays
+ * @param value Color value in various formats
+ * @returns Normalized hex color string (always 6 digits)
+ */
+export declare function normalizeColor(value: any): string;
+
+/**
+ * Paint properties for different layer types
+ */
+export declare interface PaintProperty {
+    /** Property name (e.g., 'fill-color') */
+    name: string;
+    /** Current value */
+    value: any;
+}
+
+/**
+ * Convert RGB values to hex color string
+ * @param r Red component (0-255)
+ * @param g Green component (0-255)
+ * @param b Blue component (0-255)
+ * @returns Hex color string (e.g., '#ff0000')
+ */
+export declare function rgbToHex(r: number, g: number, b: number): string;
+
+/**
+ * Set the opacity for a layer
+ * @param map MapLibre map instance
+ * @param layerId Layer ID
+ * @param layerType Layer type
+ * @param opacity Opacity value (0-1)
+ */
+export declare function setLayerOpacity(map: Map_2, layerId: string, layerType: string, opacity: number): void;
+
+/**
+ * MapLibre layer types that support styling
+ * Includes all standard MapLibre layer types
+ */
+export declare type StyleableLayerType = 'fill' | 'line' | 'circle' | 'symbol' | 'raster' | 'heatmap' | 'fill-extrusion' | 'hillshade' | 'background';
+
+/**
+ * Control for a paint property (color picker or slider)
+ */
+export declare interface StyleControlConfig {
+    /** Label to display */
+    label: string;
+    /** Paint property name */
+    property: string;
+    /** Control type */
+    type: 'color' | 'slider';
+    /** For sliders: minimum value */
+    min?: number;
+    /** For sliders: maximum value */
+    max?: number;
+    /** For sliders: step increment */
+    step?: number;
+    /** Default value if property is not set */
+    defaultValue?: any;
+}
+
+/**
+ * Symbol generation options
+ */
+export declare interface SymbolOptions {
+    /** Symbol size in pixels (default: 16) */
+    size?: number;
+    /** Stroke width for line symbols (default: 2) */
+    strokeWidth?: number;
+}
+
+export { }