maplibre-gl-raster 0.1.0

package/dist/types/react.d.ts

@@ -0,0 +1,477 @@
+import { Dispatch } from 'react';
+import { IControl } from 'maplibre-gl';
+import { Map as Map_2 } from 'maplibre-gl';
+import { SetStateAction } from 'react';
+
+/**
+ * Options for {@link AddRasterOptions} consumers (RasterControl.addRaster).
+ */
+export declare interface AddRasterOptions {
+    /** Layer id; auto-generated when omitted. */
+    id?: string;
+    /** Display name; derived from the URL / file name when omitted. */
+    name?: string;
+    /** Initial visualization state overrides (mode/bands default from the
+     * loaded band count). */
+    state?: Partial<RasterLayerState>;
+    /** Fit the map to the raster's bounds once loaded. @default true */
+    zoomTo?: boolean;
+    /** Id of an existing map style layer to insert the raster beneath (e.g. a
+     * symbol layer so labels stay readable). Drawn on top when omitted or when
+     * the layer does not exist. */
+    beforeId?: string;
+}
+
+/**
+ * A MapLibre GL control for visualizing local and remote raster datasets
+ * (GeoTIFF / Cloud Optimized GeoTIFF). A collapsible button expands into a
+ * panel with an "Add data" section (URL or local file), a layer list, and
+ * per-layer rendering settings (bands, rescale histograms, colormaps,
+ * nodata, stretch, gamma, opacity). Rendering uses a deck.gl COGLayer
+ * pipeline on a shared MapboxOverlay.
+ *
+ * @example
+ * ```typescript
+ * const control = new RasterControl({ collapsed: false });
+ * map.addControl(control, 'top-right');
+ * await control.addRaster('https://example.com/data/cog.tif');
+ * ```
+ */
+export declare class RasterControl implements IControl {
+    private _map?;
+    private _mapContainer?;
+    private _container?;
+    private _panel?;
+    private _options;
+    private _state;
+    private _eventHandlers;
+    private _layerManager?;
+    private _panelUI?;
+    private _onReady;
+    private _resizeHandler;
+    private _mapResizeHandler;
+    private _clickOutsideHandler;
+    /**
+     * Creates a new RasterControl instance.
+     *
+     * @param options - Configuration options for the control
+     */
+    constructor(options?: Partial<RasterControlOptions>);
+    /**
+     * Called when the control is added to the map.
+     * Implements the IControl interface.
+     *
+     * @param map - The MapLibre GL map instance
+     * @returns The control's container element
+     */
+    onAdd(map: Map_2): HTMLElement;
+    /**
+     * Called when the control is removed from the map.
+     * Implements the IControl interface.
+     */
+    onRemove(): void;
+    /**
+     * Gets the current state of the control.
+     *
+     * @returns The current plugin state
+     */
+    getState(): RasterControlState;
+    /**
+     * Updates the control state.
+     *
+     * @param newState - Partial state to merge with current state
+     */
+    setState(newState: Partial<RasterControlState>): void;
+    /**
+     * Toggles the collapsed state of the control panel.
+     */
+    toggle(): void;
+    /**
+     * Expands the control panel.
+     */
+    expand(): void;
+    /**
+     * Collapses the control panel.
+     */
+    collapse(): void;
+    /**
+     * Registers an event handler.
+     *
+     * @param event - The event type to listen for
+     * @param handler - The callback function
+     */
+    on(event: RasterControlEvent, handler: RasterControlEventHandler): void;
+    /**
+     * Removes an event handler.
+     *
+     * @param event - The event type
+     * @param handler - The callback function to remove
+     */
+    off(event: RasterControlEvent, handler: RasterControlEventHandler): void;
+    /**
+     * Gets the map instance.
+     *
+     * @returns The MapLibre GL map instance or undefined if not added to a map
+     */
+    getMap(): Map_2 | undefined;
+    /**
+     * Gets the control container element.
+     *
+     * @returns The container element or undefined if not added to a map
+     */
+    getContainer(): HTMLElement | undefined;
+    /**
+     * Adds a raster layer from a remote COG URL or a local GeoTIFF File.
+     *
+     * The returned promise resolves with the layer id once the GeoTIFF header
+     * loads (waiting for the control to be added to a map first, if needed)
+     * and rejects when loading fails.
+     *
+     * @param source - COG URL or a local GeoTIFF File
+     * @param options - Id/name/state overrides and zoom behavior
+     * @returns The new layer's id
+     */
+    addRaster(source: string | File, options?: AddRasterOptions): Promise<string>;
+    /**
+     * Removes a raster layer.
+     *
+     * @param id - The layer id
+     */
+    removeRaster(id: string): void;
+    /**
+     * Gets a snapshot of one raster layer.
+     *
+     * @param id - The layer id
+     * @returns Layer info, or undefined when unknown
+     */
+    getRaster(id: string): RasterLayerInfo | undefined;
+    /**
+     * Gets snapshots of all raster layers in draw order (first = bottom).
+     *
+     * @returns Layer info array
+     */
+    getRasters(): RasterLayerInfo[];
+    /**
+     * Merges a partial visualization state into a layer (bands, rescale,
+     * colormap, nodata, opacity, gamma, stretch, visible).
+     *
+     * @param id - The layer id
+     * @param patch - State fields to update
+     */
+    setRasterState(id: string, patch: Partial<RasterLayerState>): void;
+    /**
+     * Shows or hides a raster layer.
+     *
+     * @param id - The layer id
+     * @param visible - Whether the layer should render
+     */
+    setVisible(id: string, visible: boolean): void;
+    /**
+     * Selects the layer whose settings the panel edits.
+     *
+     * @param id - The layer id, or null to clear the selection
+     */
+    selectRaster(id: string | null): void;
+    /**
+     * Fits the map view to a layer's bounds.
+     *
+     * @param id - The layer id
+     */
+    zoomToRaster(id: string): void;
+    /**
+     * Moves a layer to a new position in the draw order.
+     *
+     * @param id - The layer id
+     * @param toIndex - Target index (0 = bottom)
+     */
+    reorderRaster(id: string, toIndex: number): void;
+    /** Re-emits LayerManager events through the control's event system. */
+    private _forwardLayerManagerEvents;
+    /**
+     * Emits an event to all registered handlers.
+     *
+     * @param event - The event type to emit
+     * @param extra - Optional layerId/error payload for raster events
+     */
+    private _emit;
+    /**
+     * Creates the main container element for the control.
+     * Contains a toggle button (29x29) matching navigation control size.
+     *
+     * @returns The container element
+     */
+    private _createContainer;
+    /**
+     * Creates the panel element with header and content areas.
+     * Panel is positioned as a dropdown below the toggle button.
+     *
+     * @returns The panel element
+     */
+    private _createPanel;
+    /**
+     * Setup event listeners for panel positioning and click-outside behavior.
+     */
+    private _setupEventListeners;
+    /**
+     * 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;
+}
+
+/**
+ * Event types emitted by the raster control
+ */
+export declare type RasterControlEvent = 'collapse' | 'expand' | 'statechange' | 'rasteradd' | 'rasterremove' | 'rasterchange' | 'rasterselect' | 'error';
+
+/**
+ * Event payload passed to registered handlers.
+ */
+export declare interface RasterControlEventData {
+    type: RasterControlEvent;
+    state: RasterControlState;
+    /** Affected layer id for raster* events. */
+    layerId?: string;
+    /** Error detail for 'error' events. */
+    error?: Error;
+}
+
+/**
+ * Event handler function type
+ */
+export declare type RasterControlEventHandler = (event: RasterControlEventData) => void;
+
+/**
+ * Options for configuring the RasterControl
+ */
+export declare interface RasterControlOptions {
+    /**
+     * Whether the control panel should start collapsed (showing only the toggle button)
+     * @default true
+     */
+    collapsed?: boolean;
+    /**
+     * Position of the control on the map
+     * @default 'top-right'
+     */
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    /**
+     * Title displayed in the control header
+     * @default 'Raster'
+     */
+    title?: string;
+    /**
+     * Width of the control panel in pixels
+     * @default 360
+     */
+    panelWidth?: number;
+    /**
+     * Custom CSS class name for the control container
+     */
+    className?: string;
+    /**
+     * Render the deck.gl overlay interleaved with the basemap's layers.
+     * @default true
+     */
+    interleaved?: boolean;
+    /**
+     * Prefills the "Add data" URL input with this COG URL. The raster is only
+     * loaded automatically when {@link autoLoad} is true; otherwise the user
+     * still clicks Load.
+     * @default ''
+     */
+    defaultUrl?: string;
+    /**
+     * When true and {@link defaultUrl} is set, the raster is loaded as soon as
+     * the control is added to the map (instead of prefilling the URL input).
+     * @default false
+     */
+    autoLoad?: boolean;
+}
+
+/**
+ * React wrapper component for RasterControl.
+ *
+ * This component manages the lifecycle of a RasterControl instance,
+ * adding it to the map on mount and removing it on unmount.
+ *
+ * @example
+ * ```tsx
+ * import { RasterControlReact } from 'maplibre-gl-raster/react';
+ *
+ * function MyMap() {
+ *   const [map, setMap] = useState<Map | null>(null);
+ *
+ *   return (
+ *     <>
+ *       <div ref={mapContainer} />
+ *       {map && (
+ *         <RasterControlReact
+ *           map={map}
+ *           collapsed={false}
+ *           onReady={(control) => control.addRaster('https://example.com/cog.tif')}
+ *         />
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @param props - Component props including map instance and control options
+ * @returns null - This component renders nothing directly
+ */
+export declare function RasterControlReact({ map, onStateChange, onReady, ...options }: RasterControlReactProps): null;
+
+/**
+ * Props for the React wrapper component
+ */
+export declare interface RasterControlReactProps extends RasterControlOptions {
+    /**
+     * MapLibre GL map instance
+     */
+    map: Map_2;
+    /**
+     * Callback fired when the control state changes
+     */
+    onStateChange?: (state: RasterControlState) => void;
+    /**
+     * Callback fired once the control is added to the map, with the control
+     * instance — use it to call imperative methods like addRaster().
+     */
+    onReady?: (control: RasterControl) => void;
+}
+
+/**
+ * Internal state of the plugin control
+ */
+export declare interface RasterControlState {
+    /**
+     * Whether the control panel is currently collapsed
+     */
+    collapsed: boolean;
+    /**
+     * Current panel width in pixels
+     */
+    panelWidth: number;
+    /**
+     * Any custom state data
+     */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Public, read-only snapshot of a raster layer.
+ */
+export declare interface RasterLayerInfo {
+    /** Stable layer id. */
+    id: string;
+    /** Display name shown in the layer list. */
+    name: string;
+    /** Data source. */
+    source: RasterLayerSource;
+    /** Band count, known once the GeoTIFF header loads. */
+    bandCount: number | null;
+    /** 1-indexed band names parsed from GDAL_METADATA, when present. */
+    bandNames: globalThis.Map<number, string> | null;
+    /** Map style layer id the raster is inserted beneath, when set. */
+    beforeId: string | null;
+    /** Current visualization state. */
+    state: RasterLayerState;
+}
+
+/** Where a raster layer's data came from. */
+export declare type RasterLayerSource = {
+    kind: 'url';
+    url: string;
+} | {
+    kind: 'file';
+    fileName: string;
+    objectUrl: string;
+};
+
+/**
+ * Per-layer visualization state.
+ */
+export declare interface RasterLayerState {
+    /** Rendering mode. */
+    mode: RasterMode;
+    /** 1-indexed band selection: [r, g, b] in RGB mode, [band] in single mode. */
+    bands: number[];
+    /** Per-channel [min, max] rescale windows; null = auto (2-98% percentile
+     * from computed stats). */
+    rescale: [number, number][] | null;
+    /** Colormap name (single-band mode only). 'palette' uses the image's
+     * embedded color table; defaults to 'gray'. */
+    colormap: string;
+    /** Nodata handling. */
+    nodata: RasterNodata;
+    /** Layer transparency, 0 (invisible) to 1 (fully opaque). */
+    opacity: number;
+    /** Power-law gamma correction (1.0 = off). */
+    gamma: number;
+    /** Curve applied to rescaled values. */
+    stretch: RasterStretch;
+    /** Whether the layer is drawn on the map. */
+    visible: boolean;
+}
+
+/** Rendering mode: RGB composite (one band per channel) or single band
+ * through a colormap. */
+export declare type RasterMode = 'rgb' | 'single';
+
+/** Nodata handling: 'auto' reads the value declared by the COG (and treats
+ * NaN as nodata for float data), a number overrides it in source units, and
+ * 'off' renders every pixel. */
+export declare type RasterNodata = number | 'off' | 'auto';
+
+/** Curve applied to the rescaled [0, 1] value before gamma / colormap.
+ * "log" expands the low-value range (useful for skewed data with most
+ * variation near zero); "sqrt" is a gentler version. */
+export declare type RasterStretch = 'linear' | 'log' | 'sqrt';
+
+/**
+ * Custom hook for managing plugin state in React applications.
+ *
+ * This hook provides a simple way to track and update the state
+ * of a RasterControl from React components.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { state, setCollapsed, setData, reset } = useRasterState();
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={() => setCollapsed(!state.collapsed)}>
+ *         {state.collapsed ? 'Expand' : 'Collapse'}
+ *       </button>
+ *       <RasterControlReact
+ *         map={map}
+ *         collapsed={state.collapsed}
+ *         onStateChange={(newState) => setState(newState)}
+ *       />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @param initialState - Optional initial state values
+ * @returns Object containing state and update functions
+ */
+export declare function useRasterState(initialState?: Partial<RasterControlState>): {
+    state: RasterControlState;
+    setState: Dispatch<SetStateAction<RasterControlState>>;
+    setCollapsed: (collapsed: boolean) => void;
+    setPanelWidth: (panelWidth: number) => void;
+    setData: (data: Record<string, unknown>) => void;
+    reset: () => void;
+    toggle: () => void;
+};
+
+export { }