maplibre-gl-raster 0.2.4 → 0.3.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { _ as colormaps_default, a as debounce, c as throttle, d as percentileFromHistogram, f as readBandNames, g as COLORMAP_ROW_COUNT, h as COLORMAP_OPTIONS, i as classNames, l as MAX_SAMPLE_TILES, m as COLORMAP_NAMES, n as PALETTE_COLORMAP, o as formatNumericValue, p as loadGeoTIFF, r as clamp, s as generateId, t as RasterControl, u as computeAutoStats, v as createResilientEpsgResolver } from "./RasterControl-BAv4x6Eg.js";
+import { C as computeAutoStats, E as createResilientEpsgResolver, S as MAX_SAMPLE_TILES, T as readBandNames, _ as COLORMAP_ROW_COUNT, a as loadColormapSprite, b as autoRangeFor, c as classNames, d as generateId, f as throttle, g as COLORMAP_OPTIONS, h as COLORMAP_NAMES, i as isKnownColormap, l as debounce, m as COLORMAP_DISPLAY_NAMES, n as Colorbar, o as sampleColormapStops, p as loadGeoTIFF, r as PALETTE_COLORMAP, s as clamp, t as RasterControl, u as formatNumericValue, v as colormapDisplayName, w as percentileFromHistogram, x as statsForBand, y as colormaps_default } from "./RasterControl-CV8yzpiz.js";
 import { a as Photometric, d as TiffTag, i as Compression, l as SampleFormat, o as PlanarConfiguration, s as Predictor } from "./decode-BL-qbDOV.js";
 //#region src/lib/raster/metadata.ts
 var SAMPLE_FORMAT_LABELS = {
@@ -218,6 +218,6 @@ function summarizeGeoTIFF(tiff) {
 	};
 }
 //#endregion
-export { COLORMAP_NAMES, COLORMAP_OPTIONS, COLORMAP_ROW_COUNT, MAX_SAMPLE_TILES, PALETTE_COLORMAP, RasterControl, clamp, classNames, colormaps_default as colormapsPngUrl, computeAutoStats, createResilientEpsgResolver, debounce, formatNumericValue, generateId, loadGeoTIFF, percentileFromHistogram, readBandNames, summarizeGeoTIFF, throttle };
+export { COLORMAP_DISPLAY_NAMES, COLORMAP_NAMES, COLORMAP_OPTIONS, COLORMAP_ROW_COUNT, Colorbar, MAX_SAMPLE_TILES, PALETTE_COLORMAP, RasterControl, autoRangeFor, clamp, classNames, colormapDisplayName, colormaps_default as colormapsPngUrl, computeAutoStats, createResilientEpsgResolver, debounce, formatNumericValue, generateId, isKnownColormap, loadColormapSprite, loadGeoTIFF, percentileFromHistogram, readBandNames, sampleColormapStops, statsForBand, summarizeGeoTIFF, throttle };
 
 //# sourceMappingURL=index.mjs.map

package/dist/maplibre-gl-raster.css

@@ -8,7 +8,8 @@
 
 .mlr-control,
 .mlr-control-panel,
-.mlr-inspect-popup {
+.mlr-inspect-popup,
+.mlr-colorbar {
   --mlr-bg: #fff;
   --mlr-surface-muted: #f1f3f5;
   --mlr-surface-soft: #f7f8f9;
@@ -39,7 +40,8 @@
 @media (prefers-color-scheme: dark) {
   .mlr-control,
   .mlr-control-panel,
-  .mlr-inspect-popup {
+  .mlr-inspect-popup,
+  .mlr-colorbar {
     --mlr-bg: #23282e;
     --mlr-surface-muted: #2e343b;
     --mlr-surface-soft: #2a3036;
@@ -68,6 +70,40 @@
   }
 }
 
+/* Host-controlled dark theme: an app that toggles a `.dark` class (e.g.
+   GeoLibre, which sets it on <html>) themes the controls and colorbar to
+   match, overriding the OS prefers-color-scheme default above. */
+.dark .mlr-control,
+.dark .mlr-control-panel,
+.dark .mlr-inspect-popup,
+.dark .mlr-colorbar {
+  --mlr-bg: #23282e;
+  --mlr-surface-muted: #2e343b;
+  --mlr-surface-soft: #2a3036;
+  --mlr-text: #e3e6e9;
+  --mlr-text-strong: #f0f2f4;
+  --mlr-text-soft: #c4cad0;
+  --mlr-text-muted: #9aa3ab;
+  --mlr-text-faint: #828b93;
+  --mlr-border: #454d55;
+  --mlr-border-soft: #3a4148;
+  --mlr-border-faint: #343b42;
+  --mlr-border-strong: #525a63;
+  --mlr-accent: #5b9ce0;
+  --mlr-accent-strong: #6faae6;
+  --mlr-accent-soft: rgba(91, 156, 224, 0.2);
+  --mlr-hover: rgba(255, 255, 255, 0.08);
+  --mlr-error: #e07b6e;
+  --mlr-disabled-bg: #4a5158;
+  --mlr-disabled-text: #5f666d;
+  --mlr-scrollbar: #4a5158;
+  --mlr-scrollbar-hover: #5f666d;
+  --mlr-shadow: rgba(0, 0, 0, 0.35);
+  --mlr-histogram-neutral: #cfd6dd;
+
+  color-scheme: dark;
+}
+
 /* Container - matches maplibregl-ctrl styling. The doubled selector
    outranks maplibre-gl's `.maplibregl-ctrl-group { background: #fff }`
    regardless of stylesheet order, so the button follows the theme (a white
@@ -127,7 +163,10 @@
   min-width: 240px;
   max-width: 420px;
   max-height: min(80vh, 720px);
-  overflow-y: auto;
+  /* The content area is the scroller; the panel clips so the resize handle
+     (an absolutely-positioned child) stays pinned to the corner and never
+     scrolls away with the content. */
+  overflow: hidden;
   z-index: 1000;
   padding: 8px;
   font-size: 12px;
@@ -135,8 +174,33 @@
   display: none;
 }
 
+/* Flex column so the header keeps its height and the content flexes to fill
+   the panel (whether the panel auto-sizes to content up to max-height, or the
+   user has set an explicit size via the resize handle). */
 .mlr-control-panel.expanded {
-  display: block;
+  display: flex;
+  flex-direction: column;
+}
+
+/* Engine-independent resize affordance (CSS `resize` is unreliable in
+   WebKitGTK). Placed at the panel's inward corner by _addResizeHandle(). */
+.mlr-control-resize {
+  position: absolute;
+  width: 16px;
+  height: 16px;
+  z-index: 5;
+  color: var(--mlr-text-faint);
+  opacity: 0.55;
+  touch-action: none;
+  background-image: repeating-linear-gradient(
+    135deg,
+    currentcolor 0 1px,
+    transparent 1px 3px
+  );
+}
+
+.mlr-control-resize:hover {
+  opacity: 0.9;
 }
 
 /* Panel header */
@@ -179,7 +243,11 @@
 
 /* Content */
 .mlr-control-content {
-  max-height: min(72vh, 660px);
+  /* Flex child of the panel column: fill the remaining height and scroll.
+     min-height: 0 lets it shrink below its content so the scrollbar engages
+     instead of overflowing the panel. */
+  flex: 1 1 auto;
+  min-height: 0;
   overflow-y: auto;
   /* Histogram drag handles are centered on the chart edges and poke a few
      pixels past the content box; clip them instead of growing a horizontal
@@ -361,6 +429,22 @@
   color: var(--mlr-text-soft);
 }
 
+/* Inline checkbox row (e.g. Reverse colormap): box and label on one line. */
+.mlr-check {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  font-size: 11px;
+  font-weight: 500;
+  color: var(--mlr-text-soft);
+  cursor: pointer;
+}
+
+.mlr-check input[type='checkbox'] {
+  margin: 0;
+  cursor: pointer;
+}
+
 /* Collapsible field (e.g. Rescale) */
 .mlr-collapsible > summary {
   cursor: pointer;
@@ -670,6 +754,69 @@
   image-rendering: auto;
 }
 
+/* Colorbar legend (a standalone IControl docked in a map corner). It shares
+   the --mlr-* theme variables defined above, so it follows both the OS
+   prefers-color-scheme and a host `.dark` class. */
+.mlr-colorbar {
+  box-sizing: border-box;
+  padding: 8px 10px;
+  background: var(--mlr-bg);
+  color: var(--mlr-text);
+  border: 1px solid var(--mlr-border-faint);
+  border-radius: 4px;
+  box-shadow: 0 1px 4px var(--mlr-shadow);
+  font: 11px/1.3 system-ui, sans-serif;
+  user-select: none;
+}
+
+.mlr-colorbar-title {
+  margin-bottom: 6px;
+  font-weight: 600;
+  color: var(--mlr-text);
+}
+
+.mlr-colorbar-track {
+  display: flex;
+  gap: 6px;
+}
+
+.mlr-colorbar-horizontal .mlr-colorbar-track {
+  flex-direction: column;
+}
+
+.mlr-colorbar-vertical .mlr-colorbar-track {
+  flex-direction: row;
+}
+
+.mlr-colorbar-bar {
+  border: 1px solid var(--mlr-border);
+  border-radius: 2px;
+}
+
+.mlr-colorbar-ticks {
+  display: flex;
+  justify-content: space-between;
+  color: var(--mlr-text-soft);
+  white-space: nowrap;
+}
+
+.mlr-colorbar-horizontal .mlr-colorbar-ticks {
+  flex-direction: row;
+}
+
+/* Pull the first/last labels inward so they don't overflow the bar ends. */
+.mlr-colorbar-horizontal .mlr-colorbar-tick:first-child {
+  margin-left: -2px;
+}
+
+.mlr-colorbar-horizontal .mlr-colorbar-tick:last-child {
+  margin-right: -2px;
+}
+
+.mlr-colorbar-vertical .mlr-colorbar-ticks {
+  flex-direction: column;
+}
+
 /* Settings header + inspect toggle */
 .mlr-settings-header {
   display: flex;

package/dist/react.mjs

@@ -1,4 +1,4 @@
-import { t as RasterControl } from "./RasterControl-BAv4x6Eg.js";
+import { t as RasterControl } from "./RasterControl-CV8yzpiz.js";
 import { useCallback, useEffect, useRef, useState } from "react";
 //#region src/lib/core/RasterControlReact.tsx
 /**

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 import { default as colormapsPngUrl } from '@developmentseed/deck.gl-raster/gpu-modules/colormaps.png';
+import { ControlPosition } from 'maplibre-gl';
 import { EpsgResolver } from '@developmentseed/proj';
 import { GeoTIFF } from '@developmentseed/geotiff';
 import { IControl } from 'maplibre-gl';
@@ -23,6 +24,11 @@ export declare interface AddRasterOptions {
     beforeId?: string;
 }
 
+/** 2–98% percentile range from a band's histogram. Falls back to [min, max]
+ * if the histogram is empty (e.g. GDAL_METADATA-only stats with no overview
+ * sample). Mirrors the displayed default in the settings UI. */
+export declare function autoRangeFor(stats: BandStats): Range_2;
+
 export declare type AutoStats = {
     /** 1-indexed band → stats map. Null when stats are unknown. */
     perBand: Map<number, BandStats> | null;
@@ -92,16 +98,138 @@ export declare function clamp(value: number, min: number, max: number): number;
  */
 export declare function classNames(classes: Record<string, boolean>): string;
 
+/**
+ * A standalone colorbar legend rendered on the map as a MapLibre `IControl`.
+ *
+ * The ramp is sampled from the library's own colormap sprite (so named
+ * colormaps and the `reversed` flag match the rendered raster exactly), or
+ * built from a custom list of colors. Add it with
+ * `map.addControl(new Colorbar({ colormap, min, max, ... }))` and reconfigure
+ * live with {@link update} (e.g. from a `rasterchange` handler).
+ */
+export declare class Colorbar implements IControl {
+    private _opts;
+    private _root;
+    private _bar;
+    private _colorToken;
+    /**
+     * @param options - Initial colorbar configuration.
+     */
+    constructor(options?: ColorbarOptions);
+    /** @returns The configured map corner. */
+    getDefaultPosition(): ControlPosition;
+    /**
+     * MapLibre `IControl` hook: builds and returns the legend element.
+     *
+     * @returns The root element MapLibre docks into its corner container.
+     */
+    onAdd(): HTMLElement;
+    /** MapLibre `IControl` hook: detaches the legend. */
+    onRemove(): void;
+    /**
+     * Merges a partial configuration and re-renders. `position` changes only
+     * take effect on the next add (MapLibre fixes a control's corner at
+     * `addControl` time).
+     *
+     * @param options - Fields to change.
+     */
+    update(options: Partial<ColorbarOptions>): void;
+    /** @returns A copy of the resolved options. */
+    getOptions(): ColorbarOptions;
+    /** Resolves the tick values shown along the bar. */
+    private _tickValues;
+    /** Formats a tick value (fixed decimals when configured, else compact auto)
+     * with the configured units suffix. */
+    private _formatTick;
+    private _render;
+    /** Sets the bar gradient, sampling the sprite for named colormaps. */
+    private _applyColors;
+}
+
+/**
+ * Configuration for a {@link Colorbar} legend. All fields are optional; the
+ * resolved defaults are listed per field.
+ */
+export declare interface ColorbarOptions {
+    /** Named colormap to sample (case-insensitive), e.g. 'viridis'. Sampled
+     * from the same sprite the renderer uses, so it matches the map exactly.
+     * Ignored when {@link colors} supplies a custom ramp. @default 'viridis' */
+    colormap?: string;
+    /** Custom anchor colors (any CSS color). When two or more are given they
+     * define the ramp directly and {@link colormap} is ignored. */
+    colors?: string[];
+    /** Sample the ramp back-to-front (matches a reversed raster render).
+     * @default false */
+    reversed?: boolean;
+    /** Value at the start of the ramp. @default 0 */
+    min?: number;
+    /** Value at the end of the ramp. @default 1 */
+    max?: number;
+    /** Title shown above the bar. @default '' */
+    title?: string;
+    /** Horizontal alignment of the title. @default 'left' */
+    titleAlign?: 'left' | 'center' | 'right';
+    /** Unit suffix appended to every tick label (e.g. 'm', '°C'). @default '' */
+    units?: string;
+    /** Bar/label layout. @default 'horizontal' */
+    orientation?: ColorbarOrientation;
+    /** Map corner to dock in (MapLibre control position). @default 'bottom-right' */
+    position?: ControlPosition;
+    /** Stretch curve the raster applies before the colormap. Tick values are
+     * spaced to match it so the legend stays accurate under log / sqrt.
+     * @default 'linear' */
+    stretch?: ColorbarStretch;
+    /** Number of evenly spaced tick labels (>= 2). Ignored when
+     * {@link tickValues} is set. @default 5 */
+    ticks?: number;
+    /** Explicit tick values, overriding {@link ticks}. */
+    tickValues?: number[];
+    /** Fixed number of decimal places for tick labels. When omitted, labels use
+     * a compact auto format (2 decimals for |value| >= 1, else 4 sig figs). */
+    decimals?: number;
+    /** Length of the bar along its main axis, in px. @default 180 */
+    barLength?: number;
+    /** Thickness of the bar across its main axis, in px. @default 12 */
+    barThickness?: number;
+    /** Extra class added to the root element. */
+    className?: string;
+}
+
+/** Layout direction of the colorbar bar and its tick labels. */
+export declare type ColorbarOrientation = 'horizontal' | 'vertical';
+
+/** Stretch curve the raster applies before the colormap (mirrors RasterStretch). */
+export declare type ColorbarStretch = 'linear' | 'log' | 'sqrt';
+
+/**
+ * Canonical display casing for colormaps whose matplotlib name is mixed-case.
+ * The sprite keys are lowercased, so the value sent to the renderer stays
+ * lowercase (see {@link ColormapOption.name}); only the label is restored to
+ * the familiar matplotlib spelling (e.g. "ylorbr" → "YlOrBr", "rdbu" → "RdBu").
+ * Names not listed here are lowercase in matplotlib too (viridis, jet, …) and
+ * are shown as-is.
+ */
+export declare const COLORMAP_DISPLAY_NAMES: Readonly<Record<string, string>>;
+
 /** Alphabetical list of the named colormaps shipped in the sprite. */
 export declare const COLORMAP_NAMES: string[];
 
-/** Picker-ready options: name, display label, and the sprite row to
- * preview. */
+/** Picker-ready options: name (renderer value), display label, and the sprite
+ * row to preview. */
 export declare const COLORMAP_OPTIONS: ColormapOption[];
 
 /** Number of rows in the colormap sprite. */
 export declare const COLORMAP_ROW_COUNT: number;
 
+/**
+ * The matplotlib display label for a colormap key (its canonical casing when
+ * known, otherwise the key itself).
+ *
+ * @param name - The lowercase colormap key.
+ * @returns The display label.
+ */
+export declare function colormapDisplayName(name: string): string;
+
 export declare type ColormapOption = {
     name: string;
     label: string;
@@ -228,6 +356,21 @@ export declare type ImageSummary = {
     nodata: number | null;
 };
 
+/**
+ * Whether a name maps to a known colormap row in the sprite.
+ *
+ * @param name - A colormap name (case-insensitive).
+ * @returns True when the name has a sprite row.
+ */
+export declare function isKnownColormap(name: string): boolean;
+
+/**
+ * Loads (and memoizes) the colormap sprite PNG.
+ *
+ * @returns The decoded sprite image, shared across callers.
+ */
+export declare function loadColormapSprite(): Promise<HTMLImageElement>;
+
 /**
  * Open a GeoTIFF from a URL (http(s) or blob:). Equivalent to
  * `GeoTIFF.fromUrl(url)` plus the CORS workaround above. Dedupes concurrent
@@ -280,6 +423,31 @@ export declare const PALETTE_COLORMAP = "palette";
  */
 export declare function percentileFromHistogram(stats: BandStats, p: number): number;
 
+declare type Range_2 = [number, number];
+
+/**
+ * Per-layer colorbar legend config. When `visible`, the control shows a
+ * {@link import('./Colorbar').Colorbar} for the (single-band) layer, driven by
+ * its colormap, `reversed` flag, and effective rescale range. The fields here
+ * are the parts the data can't supply.
+ */
+declare interface RasterColorbarState {
+    /** Whether the legend is shown for this layer. */
+    visible: boolean;
+    /** Legend title; defaults to the layer name when empty. */
+    title?: string;
+    /** Horizontal alignment of the title. @default 'left' */
+    titleAlign?: 'left' | 'center' | 'right';
+    /** Unit suffix appended to tick labels. */
+    units?: string;
+    /** Fixed decimal places for tick labels; omitted = compact auto format. */
+    decimals?: number;
+    /** Bar orientation. @default 'horizontal' */
+    orientation?: ColorbarOrientation;
+    /** Map corner to dock the legend in. @default 'bottom-right' */
+    position?: ControlPosition;
+}
+
 /**
  * A MapLibre GL control for visualizing local and remote raster datasets
  * (GeoTIFF / Cloud Optimized GeoTIFF). A collapsible button expands into a
@@ -307,6 +475,12 @@ export declare class RasterControl implements IControl {
     private _panelUI?;
     private _inspector?;
     private _onReady;
+    /** On-map colorbar legends, one per layer whose `state.colorbar.visible`. */
+    private _colorbars;
+    /** User-chosen panel size from the resize handle, re-applied on reposition. */
+    private _userPanelSize;
+    /** Repositions the resize handle to the panel's inward corner. */
+    private _placeResizeHandle;
     private _resizeHandler;
     private _mapResizeHandler;
     private _clickOutsideHandler;
@@ -455,6 +629,19 @@ export declare class RasterControl implements IControl {
     setRasterBeforeId(id: string, beforeId: string | null): void;
     /** Re-emits LayerManager events through the control's event system. */
     private _forwardLayerManagerEvents;
+    /**
+     * Reconciles the on-map colorbar legends with the layers' colorbar state:
+     * adds/updates a {@link Colorbar} for each single-band layer whose
+     * `state.colorbar.visible` is set, and removes the rest. Driven by
+     * LayerManager change events, so the panel only has to write
+     * `state.colorbar`.
+     */
+    private _syncColorbars;
+    /** Builds colorbar options from a layer's colormap, reverse flag, and
+     * effective rescale range (explicit window, else auto-stats percentile). */
+    private _colorbarOptionsFor;
+    /** Removes all on-map colorbar legends. */
+    private _removeAllColorbars;
     /**
      * Emits an event to all registered handlers.
      *
@@ -476,6 +663,23 @@ export declare class RasterControl implements IControl {
      * @returns The panel element
      */
     private _createPanel;
+    /**
+     * Adds a drag handle that resizes the panel in both dimensions. The panel is
+     * absolutely positioned and anchored to its docking corner, so a custom
+     * handle is used instead of CSS `resize` (which is unreliable in WebKitGTK):
+     * it sits at the panel's inward corner and grows toward the map interior, in
+     * any corner. The anchored edges stay fixed; only width/height change.
+     *
+     * @param panel - The panel element to make resizable.
+     */
+    private _addResizeHandle;
+    /**
+     * Applies the user-chosen panel size, clamped to the room available from the
+     * panel's anchored corner to the opposite map edge. Re-run on reposition so
+     * the size survives expand / window-resize (which rewrite the panel's
+     * positioning) and stays within the map.
+     */
+    private _applyUserPanelSize;
     /**
      * Setup event listeners for panel positioning and click-outside behavior.
      */
@@ -640,6 +844,10 @@ export declare interface RasterLayerState {
     /** Colormap name (single-band mode only). 'palette' uses the image's
      * embedded color table; defaults to 'gray'. */
     colormap: string;
+    /** Sample the colormap back-to-front (single-band named colormaps only;
+     * ignored for 'palette', whose entries are categorical). Equivalent to a
+     * reversed variant of the ramp. */
+    reversed: boolean;
     /** Nodata handling. */
     nodata: RasterNodata;
     /** Layer transparency, 0 (invisible) to 1 (fully opaque). */
@@ -650,6 +858,8 @@ export declare interface RasterLayerState {
     stretch: RasterStretch;
     /** Whether the layer is drawn on the map. */
     visible: boolean;
+    /** Optional colorbar legend shown on the map for this layer. */
+    colorbar?: RasterColorbarState;
 }
 
 /** Rendering mode: RGB composite (one band per channel) or single band
@@ -684,6 +894,24 @@ export declare interface ResilientEpsgResolverOptions {
     fallback?: EpsgResolver;
 }
 
+/**
+ * Samples `steps` evenly spaced CSS `rgb()` colors from a named colormap by
+ * reading its row of the sprite. `reversed` samples `1 - f`, mirroring the GPU
+ * colormap shader, so a reversed legend matches a reversed render exactly.
+ *
+ * Returns an empty array for an unknown name, for `steps < 2`, or when a 2D
+ * canvas is unavailable (e.g. jsdom without the `canvas` package); callers
+ * should fall back to a plain gradient in that case.
+ *
+ * @param name - The colormap name (case-insensitive).
+ * @param steps - Number of color stops to sample (>= 2).
+ * @param reversed - Sample the ramp back-to-front.
+ * @returns Sampled `rgb(r, g, b)` strings, or [] when sampling is impossible.
+ */
+export declare function sampleColormapStops(name: string, steps: number, reversed?: boolean): Promise<string[]>;
+
+export declare function statsForBand(autoStats: AutoStats | null, band: number): BandStats | null;
+
 /** Pure derivation from an already-loaded GeoTIFF: no fetches, no I/O. */
 export declare function summarizeGeoTIFF(tiff: MetadataInput): MetadataSummary;
 

package/dist/types/react.d.ts

@@ -1,3 +1,4 @@
+import { ControlPosition } from 'maplibre-gl';
 import { Dispatch } from 'react';
 import { EpsgResolver } from '@developmentseed/proj';
 import { IControl } from 'maplibre-gl';
@@ -23,6 +24,9 @@ export declare interface AddRasterOptions {
     beforeId?: string;
 }
 
+/** Layout direction of the colorbar bar and its tick labels. */
+declare type ColorbarOrientation = 'horizontal' | 'vertical';
+
 /** Geographic (WGS84) bounds of a layer, as reported by COGLayer. */
 export declare type GeographicBounds = {
     west: number;
@@ -31,6 +35,29 @@ export declare type GeographicBounds = {
     north: number;
 };
 
+/**
+ * Per-layer colorbar legend config. When `visible`, the control shows a
+ * {@link import('./Colorbar').Colorbar} for the (single-band) layer, driven by
+ * its colormap, `reversed` flag, and effective rescale range. The fields here
+ * are the parts the data can't supply.
+ */
+declare interface RasterColorbarState {
+    /** Whether the legend is shown for this layer. */
+    visible: boolean;
+    /** Legend title; defaults to the layer name when empty. */
+    title?: string;
+    /** Horizontal alignment of the title. @default 'left' */
+    titleAlign?: 'left' | 'center' | 'right';
+    /** Unit suffix appended to tick labels. */
+    units?: string;
+    /** Fixed decimal places for tick labels; omitted = compact auto format. */
+    decimals?: number;
+    /** Bar orientation. @default 'horizontal' */
+    orientation?: ColorbarOrientation;
+    /** Map corner to dock the legend in. @default 'bottom-right' */
+    position?: ControlPosition;
+}
+
 /**
  * A MapLibre GL control for visualizing local and remote raster datasets
  * (GeoTIFF / Cloud Optimized GeoTIFF). A collapsible button expands into a
@@ -58,6 +85,12 @@ export declare class RasterControl implements IControl {
     private _panelUI?;
     private _inspector?;
     private _onReady;
+    /** On-map colorbar legends, one per layer whose `state.colorbar.visible`. */
+    private _colorbars;
+    /** User-chosen panel size from the resize handle, re-applied on reposition. */
+    private _userPanelSize;
+    /** Repositions the resize handle to the panel's inward corner. */
+    private _placeResizeHandle;
     private _resizeHandler;
     private _mapResizeHandler;
     private _clickOutsideHandler;
@@ -206,6 +239,19 @@ export declare class RasterControl implements IControl {
     setRasterBeforeId(id: string, beforeId: string | null): void;
     /** Re-emits LayerManager events through the control's event system. */
     private _forwardLayerManagerEvents;
+    /**
+     * Reconciles the on-map colorbar legends with the layers' colorbar state:
+     * adds/updates a {@link Colorbar} for each single-band layer whose
+     * `state.colorbar.visible` is set, and removes the rest. Driven by
+     * LayerManager change events, so the panel only has to write
+     * `state.colorbar`.
+     */
+    private _syncColorbars;
+    /** Builds colorbar options from a layer's colormap, reverse flag, and
+     * effective rescale range (explicit window, else auto-stats percentile). */
+    private _colorbarOptionsFor;
+    /** Removes all on-map colorbar legends. */
+    private _removeAllColorbars;
     /**
      * Emits an event to all registered handlers.
      *
@@ -227,6 +273,23 @@ export declare class RasterControl implements IControl {
      * @returns The panel element
      */
     private _createPanel;
+    /**
+     * Adds a drag handle that resizes the panel in both dimensions. The panel is
+     * absolutely positioned and anchored to its docking corner, so a custom
+     * handle is used instead of CSS `resize` (which is unreliable in WebKitGTK):
+     * it sits at the panel's inward corner and grows toward the map interior, in
+     * any corner. The anchored edges stay fixed; only width/height change.
+     *
+     * @param panel - The panel element to make resizable.
+     */
+    private _addResizeHandle;
+    /**
+     * Applies the user-chosen panel size, clamped to the room available from the
+     * panel's anchored corner to the opposite map edge. Re-run on reposition so
+     * the size survives expand / window-resize (which rewrite the panel's
+     * positioning) and stays within the map.
+     */
+    private _applyUserPanelSize;
     /**
      * Setup event listeners for panel positioning and click-outside behavior.
      */
@@ -443,6 +506,10 @@ export declare interface RasterLayerState {
     /** Colormap name (single-band mode only). 'palette' uses the image's
      * embedded color table; defaults to 'gray'. */
     colormap: string;
+    /** Sample the colormap back-to-front (single-band named colormaps only;
+     * ignored for 'palette', whose entries are categorical). Equivalent to a
+     * reversed variant of the ramp. */
+    reversed: boolean;
     /** Nodata handling. */
     nodata: RasterNodata;
     /** Layer transparency, 0 (invisible) to 1 (fully opaque). */
@@ -453,6 +520,8 @@ export declare interface RasterLayerState {
     stretch: RasterStretch;
     /** Whether the layer is drawn on the map. */
     visible: boolean;
+    /** Optional colorbar legend shown on the map for this layer. */
+    colorbar?: RasterColorbarState;
 }
 
 /** Rendering mode: RGB composite (one band per channel) or single band

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maplibre-gl-raster",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "A MapLibre GL JS plugin for visualizing local and remote raster datasets (GeoTIFF/COG)",
   "type": "module",
   "main": "./dist/index.mjs",