@trackunit/react-map 0.2.208 → 0.2.210-alpha-7afddbbe4cc.0

package/index.cjs.js

@@ -5888,10 +5888,10 @@ const useFitToContent = (api, handles, options) => {
 };
 
 /**
- * Single dev-warning channel for `useHeatmap` (invalid data).
+ * Single dev-warning channel for `useHeatmap` (invalid data, invalid style).
  */
 const warnHeatmap = (message, ...details) => {
-    // eslint-disable-next-line no-console -- Intentional: the one heatmap warning channel; invalid input is dropped and must stay visible
+    // eslint-disable-next-line no-console -- Intentional: the one heatmap warning channel; invalid input is dropped or defaulted and must stay visible
     console.warn(`[useHeatmap] ${message}`, ...details);
 };
 
@@ -5938,6 +5938,99 @@ const normalizeHeatmapData = ({ data, getPosition, getWeight, }) => {
     };
 };
 
+const HEX_PATTERN = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const RGB_PATTERN = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)$/i;
+const parseHex = (hex) => {
+    const expanded = hex.length === 3
+        ? hex
+            .split("")
+            .map(char => char + char)
+            .join("")
+        : hex;
+    const channel = (index) => parseInt(expanded.slice(index * 2, index * 2 + 2), 16);
+    const alpha = expanded.length === 8 ? channel(3) / 255 : 1;
+    return [channel(0), channel(1), channel(2), alpha];
+};
+const isChannel = (value) => Number.isFinite(value) && value >= 0 && value <= 255;
+/**
+ * Parses a CSS colour into `[r, g, b, a]`.
+ *
+ * Supports `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb()` and `rgba()`; returns `null` otherwise.
+ */
+const parseHeatmapColor = (input) => {
+    const color = input.trim();
+    const hexMatch = HEX_PATTERN.exec(color);
+    if (hexMatch?.[1] !== undefined)
+        return parseHex(hexMatch[1]);
+    const rgbMatch = RGB_PATTERN.exec(color);
+    if (rgbMatch === null)
+        return null;
+    const red = Number(rgbMatch[1]);
+    const green = Number(rgbMatch[2]);
+    const blue = Number(rgbMatch[3]);
+    const alpha = rgbMatch[4] === undefined ? 1 : Number(rgbMatch[4]);
+    if (!isChannel(red) || !isChannel(green) || !isChannel(blue))
+        return null;
+    if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1)
+        return null;
+    return [red, green, blue, alpha];
+};
+
+/** Movement page gradient (legacy Google heatmap), low to high density. */
+const DEFAULT_HEATMAP_COLOR_RANGE = [
+    "rgba(0, 255, 255, 0)",
+    "#0000ff",
+    "#00ffff",
+    "#00ff00",
+    "#ffff00",
+    "#ff0000",
+];
+const DEFAULT_PARSED_COLOR_RANGE = DEFAULT_HEATMAP_COLOR_RANGE.map(parseHeatmapColor).filter(sharedUtils.nonNullable);
+const resolveColorRange = (colorRange) => {
+    if (colorRange === undefined)
+        return DEFAULT_PARSED_COLOR_RANGE;
+    const parsed = colorRange.map(parseHeatmapColor);
+    const valid = parsed.filter(sharedUtils.nonNullable);
+    if (colorRange.length >= 2 && valid.length === parsed.length)
+        return valid;
+    warnHeatmap("colorRange needs at least two supported colours (#rgb, #rrggbb, #rrggbbaa, rgb(), rgba()); using the default.", colorRange);
+    return DEFAULT_PARSED_COLOR_RANGE;
+};
+const HEATMAP_STYLE_RULES = {
+    radiusPixels: { defaultValue: 30, min: 1, max: 100 },
+    intensity: { defaultValue: 1, min: 0, max: Number.POSITIVE_INFINITY },
+    opacity: { defaultValue: 1, min: 0, max: 1 },
+};
+/**
+ * Applies defaults and supported ranges so both adapters receive identical style values.
+ *
+ * Finite values are clamped; non-finite values fall back to the default with one warning.
+ */
+const resolveHeatmapStyle = (style) => {
+    const nonFiniteKeys = [];
+    const resolveValue = (key) => {
+        const rule = HEATMAP_STYLE_RULES[key];
+        const value = style?.[key];
+        if (value === undefined)
+            return rule.defaultValue;
+        if (!Number.isFinite(value)) {
+            nonFiniteKeys.push(key);
+            return rule.defaultValue;
+        }
+        return Math.min(rule.max, Math.max(rule.min, value));
+    };
+    const resolved = {
+        radiusPixels: resolveValue("radiusPixels"),
+        intensity: resolveValue("intensity"),
+        opacity: resolveValue("opacity"),
+        colorRange: resolveColorRange(style?.colorRange),
+    };
+    if (nonFiniteKeys.length > 0) {
+        warnHeatmap(`Non-finite style value(s) for ${nonFiniteKeys.join(", ")} replaced with defaults.`);
+    }
+    return resolved;
+};
+
 const EMPTY_CONTROLS$2 = {};
 /**
  * Weighted point heatmap layer handle (provider-agnostic).
@@ -5958,11 +6051,18 @@ const useHeatmap = (options) => {
         setPrevData(data);
         setNormalized(normalizeHeatmapData({ data, getPosition, getWeight }));
     }
-    const resolvedStyle = react.useMemo(() => ({
-        radiusPixels: style?.radiusPixels ?? 30,
-        intensity: style?.intensity ?? 1,
-        opacity: style?.opacity ?? 1,
-    }), [style?.radiusPixels, style?.intensity, style?.opacity]);
+    // Holds the last structurally-equal reference so an inline `colorRange` literal
+    // doesn't change the handle every render; the original array is validated as-is.
+    const [colorRange, setColorRange] = react.useState(style?.colorRange);
+    if (style?.colorRange !== colorRange && !esToolkit.isEqual(style?.colorRange, colorRange)) {
+        setColorRange(style?.colorRange);
+    }
+    const resolvedStyle = react.useMemo(() => resolveHeatmapStyle({
+        radiusPixels: style?.radiusPixels,
+        intensity: style?.intensity,
+        opacity: style?.opacity,
+        colorRange,
+    }), [style?.radiusPixels, style?.intensity, style?.opacity, colorRange]);
     const getBounds = react.useMemo(() => createLazyGetter(() => computeBoundsFromPositions(normalized.positions)), [normalized.positions]);
     const counts = react.useMemo(() => ({ total: data.length, points: normalized.features.features.length }), [data.length, normalized.features.features.length]);
     return react.useMemo(() => ({

package/index.esm.js

@@ -12,7 +12,7 @@ import { isEqual } from 'es-toolkit';
 import { useGeolocation, useErrorHandlerOrNull } from '@trackunit/react-core-hooks';
 import { Checkbox, ToggleSwitch, RadioGroup as RadioGroup$1, RadioItem, FormGroup, Search as Search$1, SelectField, BaseSelect } from '@trackunit/react-form-components';
 import { z } from 'zod';
-import { readLocalStorageValue } from '@trackunit/shared-utils';
+import { readLocalStorageValue, nonNullable } from '@trackunit/shared-utils';
 import { PieChart } from 'react-minimal-pie-chart';
 import { tailwindPalette } from '@trackunit/ui-design-tokens';
 import { lngLatToMercatorPxWS, validateBboxWithFallback, extractPositionsFromGeometry, geoJsonPositionSchema, validateFeatureCollection, EMPTY_FEATURE_COLLECTION, splitAntimeridianCrossingFeatures, validateBbox, projectPolygonalToWebMercator, geoJsonPolygonDifference, unprojectPolygonalFromWebMercator, geoJsonPolygonSchema, geoJsonMultiPolygonSchema, distanceToGeoJsonPolygonBoundary, getGeoJsonPolygonIntersection, isFullyContainedInGeometry, isGeoJsonPointInPolygon, isBboxInsideFeatureCollection, extractEdges, computeGeometryCentroid, mercatorPxToLngLatWS, isPositionInsideRing, lngLatToWebMercatorPx, edgePixelLength, isFullyContainedInGeoJsonGeometry } from '@trackunit/geo-json-utils';
@@ -5887,10 +5887,10 @@ const useFitToContent = (api, handles, options) => {
 };
 
 /**
- * Single dev-warning channel for `useHeatmap` (invalid data).
+ * Single dev-warning channel for `useHeatmap` (invalid data, invalid style).
  */
 const warnHeatmap = (message, ...details) => {
-    // eslint-disable-next-line no-console -- Intentional: the one heatmap warning channel; invalid input is dropped and must stay visible
+    // eslint-disable-next-line no-console -- Intentional: the one heatmap warning channel; invalid input is dropped or defaulted and must stay visible
     console.warn(`[useHeatmap] ${message}`, ...details);
 };
 
@@ -5937,6 +5937,99 @@ const normalizeHeatmapData = ({ data, getPosition, getWeight, }) => {
     };
 };
 
+const HEX_PATTERN = /^#([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+const RGB_PATTERN = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)$/i;
+const parseHex = (hex) => {
+    const expanded = hex.length === 3
+        ? hex
+            .split("")
+            .map(char => char + char)
+            .join("")
+        : hex;
+    const channel = (index) => parseInt(expanded.slice(index * 2, index * 2 + 2), 16);
+    const alpha = expanded.length === 8 ? channel(3) / 255 : 1;
+    return [channel(0), channel(1), channel(2), alpha];
+};
+const isChannel = (value) => Number.isFinite(value) && value >= 0 && value <= 255;
+/**
+ * Parses a CSS colour into `[r, g, b, a]`.
+ *
+ * Supports `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb()` and `rgba()`; returns `null` otherwise.
+ */
+const parseHeatmapColor = (input) => {
+    const color = input.trim();
+    const hexMatch = HEX_PATTERN.exec(color);
+    if (hexMatch?.[1] !== undefined)
+        return parseHex(hexMatch[1]);
+    const rgbMatch = RGB_PATTERN.exec(color);
+    if (rgbMatch === null)
+        return null;
+    const red = Number(rgbMatch[1]);
+    const green = Number(rgbMatch[2]);
+    const blue = Number(rgbMatch[3]);
+    const alpha = rgbMatch[4] === undefined ? 1 : Number(rgbMatch[4]);
+    if (!isChannel(red) || !isChannel(green) || !isChannel(blue))
+        return null;
+    if (!Number.isFinite(alpha) || alpha < 0 || alpha > 1)
+        return null;
+    return [red, green, blue, alpha];
+};
+
+/** Movement page gradient (legacy Google heatmap), low to high density. */
+const DEFAULT_HEATMAP_COLOR_RANGE = [
+    "rgba(0, 255, 255, 0)",
+    "#0000ff",
+    "#00ffff",
+    "#00ff00",
+    "#ffff00",
+    "#ff0000",
+];
+const DEFAULT_PARSED_COLOR_RANGE = DEFAULT_HEATMAP_COLOR_RANGE.map(parseHeatmapColor).filter(nonNullable);
+const resolveColorRange = (colorRange) => {
+    if (colorRange === undefined)
+        return DEFAULT_PARSED_COLOR_RANGE;
+    const parsed = colorRange.map(parseHeatmapColor);
+    const valid = parsed.filter(nonNullable);
+    if (colorRange.length >= 2 && valid.length === parsed.length)
+        return valid;
+    warnHeatmap("colorRange needs at least two supported colours (#rgb, #rrggbb, #rrggbbaa, rgb(), rgba()); using the default.", colorRange);
+    return DEFAULT_PARSED_COLOR_RANGE;
+};
+const HEATMAP_STYLE_RULES = {
+    radiusPixels: { defaultValue: 30, min: 1, max: 100 },
+    intensity: { defaultValue: 1, min: 0, max: Number.POSITIVE_INFINITY },
+    opacity: { defaultValue: 1, min: 0, max: 1 },
+};
+/**
+ * Applies defaults and supported ranges so both adapters receive identical style values.
+ *
+ * Finite values are clamped; non-finite values fall back to the default with one warning.
+ */
+const resolveHeatmapStyle = (style) => {
+    const nonFiniteKeys = [];
+    const resolveValue = (key) => {
+        const rule = HEATMAP_STYLE_RULES[key];
+        const value = style?.[key];
+        if (value === undefined)
+            return rule.defaultValue;
+        if (!Number.isFinite(value)) {
+            nonFiniteKeys.push(key);
+            return rule.defaultValue;
+        }
+        return Math.min(rule.max, Math.max(rule.min, value));
+    };
+    const resolved = {
+        radiusPixels: resolveValue("radiusPixels"),
+        intensity: resolveValue("intensity"),
+        opacity: resolveValue("opacity"),
+        colorRange: resolveColorRange(style?.colorRange),
+    };
+    if (nonFiniteKeys.length > 0) {
+        warnHeatmap(`Non-finite style value(s) for ${nonFiniteKeys.join(", ")} replaced with defaults.`);
+    }
+    return resolved;
+};
+
 const EMPTY_CONTROLS$2 = {};
 /**
  * Weighted point heatmap layer handle (provider-agnostic).
@@ -5957,11 +6050,18 @@ const useHeatmap = (options) => {
         setPrevData(data);
         setNormalized(normalizeHeatmapData({ data, getPosition, getWeight }));
     }
-    const resolvedStyle = useMemo(() => ({
-        radiusPixels: style?.radiusPixels ?? 30,
-        intensity: style?.intensity ?? 1,
-        opacity: style?.opacity ?? 1,
-    }), [style?.radiusPixels, style?.intensity, style?.opacity]);
+    // Holds the last structurally-equal reference so an inline `colorRange` literal
+    // doesn't change the handle every render; the original array is validated as-is.
+    const [colorRange, setColorRange] = useState(style?.colorRange);
+    if (style?.colorRange !== colorRange && !isEqual(style?.colorRange, colorRange)) {
+        setColorRange(style?.colorRange);
+    }
+    const resolvedStyle = useMemo(() => resolveHeatmapStyle({
+        radiusPixels: style?.radiusPixels,
+        intensity: style?.intensity,
+        opacity: style?.opacity,
+        colorRange,
+    }), [style?.radiusPixels, style?.intensity, style?.opacity, colorRange]);
     const getBounds = useMemo(() => createLazyGetter(() => computeBoundsFromPositions(normalized.positions)), [normalized.positions]);
     const counts = useMemo(() => ({ total: data.length, points: normalized.features.features.length }), [data.length, normalized.features.features.length]);
     return useMemo(() => ({

package/migrations/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../../../libs/react/map/migrations/entry.ts"],"names":[],"mappings":"","sourcesContent":["export {};\n"]}

package/package.json

@@ -1,23 +1,23 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.2.208",
+  "version": "0.2.210-alpha-7afddbbe4cc.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "3.8.2",
-    "@trackunit/css-class-variance-utilities": "2.3.5",
-    "@trackunit/react-form-components": "2.10.9",
-    "@trackunit/react-core-hooks": "1.25.5",
-    "@trackunit/geo-json-utils": "1.18.5",
-    "@trackunit/i18n-library-translation": "2.8.5",
+    "@trackunit/react-components": "3.8.4-alpha-7afddbbe4cc.0",
+    "@trackunit/css-class-variance-utilities": "2.3.7-alpha-7afddbbe4cc.0",
+    "@trackunit/react-form-components": "2.10.11-alpha-7afddbbe4cc.0",
+    "@trackunit/react-core-hooks": "1.25.7-alpha-7afddbbe4cc.0",
+    "@trackunit/geo-json-utils": "1.18.7-alpha-7afddbbe4cc.0",
+    "@trackunit/i18n-library-translation": "2.8.7-alpha-7afddbbe4cc.0",
     "react-minimal-pie-chart": "^8.4.0",
-    "@trackunit/react-map-adapter-shared": "0.0.156",
-    "@trackunit/react-map-color-utils": "0.0.131",
-    "@trackunit/shared-utils": "1.19.5",
-    "@trackunit/ui-design-tokens": "1.18.5",
+    "@trackunit/react-map-adapter-shared": "0.0.158-alpha-7afddbbe4cc.0",
+    "@trackunit/react-map-color-utils": "0.0.133-alpha-7afddbbe4cc.0",
+    "@trackunit/shared-utils": "1.19.7-alpha-7afddbbe4cc.0",
+    "@trackunit/ui-design-tokens": "1.18.7-alpha-7afddbbe4cc.0",
     "@floating-ui/react": "^0.26.25",
     "es-toolkit": "^1.52.0",
     "tailwind-merge": "^2.0.0",

package/src/index.d.ts

@@ -16,15 +16,15 @@ export type { ControlStackItem } from "./controls/defineControlStack";
 export type { UseControlsAreas } from "./controls/types";
 export { useControls } from "./controls/useControls";
 export { useDefaultControls, type UseDefaultControlsOptions } from "./controls/useDefaultControls";
-export type { AppearanceAction, AppearanceOption, AppearanceOptions, MapAppearanceApi, PersistedAppearance, UseMapAppearanceControlsParams, } from "./appearance/appearanceTypes";
 export { DEFAULT_APPEARANCE_PERSISTENCE_KEY } from "./appearance/appearanceTypes";
+export type { AppearanceAction, AppearanceOption, AppearanceOptions, MapAppearanceApi, PersistedAppearance, UseMapAppearanceControlsParams, } from "./appearance/appearanceTypes";
 export { useMapAppearanceControls } from "./appearance/useMapAppearanceControls";
 export { usePersistedAppearanceSeed, type MapAppearanceSeed, type UsePersistedAppearanceSeedParams, } from "./appearance/usePersistedAppearanceSeed";
 export type { ControlMiddleware, MiddlewareContext } from "./controls/renderingRules";
 export type { CategoryMetadata } from "./controls/collapseControls";
 export type { ClusterEntity, Entity, MapInteractionState, MarkerEntity, RouteEntity, ShapeEntity, ShapeType, } from "@trackunit/react-map-adapter-shared";
 export { geometryTypeToShapeType, INITIAL_INTERACTION_STATE } from "@trackunit/react-map-adapter-shared";
-export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterInfo, ClusterRenderState, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, FitParticipation, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, HeatmapLayerHandle, ImageOverlayHandle, LayerHandle, LayerMeta, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, MarkerLayerHandle, RenderConfig, RenderMedium, ResolutionContext, RouteLayerHandle, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeLayerHandle, ShapeOverlapConfig, ShapeStyle, ShapeStyleOverrides, ShapesUnderCursorHit, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "./layers/types";
+export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterInfo, ClusterRenderState, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, FitParticipation, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, HeatmapLayerHandle, HeatmapRgbaColor, ImageOverlayHandle, LayerHandle, LayerMeta, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, MarkerLayerHandle, RenderConfig, RenderMedium, ResolutionContext, RouteLayerHandle, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeLayerHandle, ShapeOverlapConfig, ShapeStyle, ShapeStyleOverrides, ShapesUnderCursorHit, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "./layers/types";
 export { computeMarkerDomPortalZIndex } from "./layers/types";
 export { ANCHOR_SELECTOR, HIT_SURFACE_SELECTOR } from "@trackunit/react-map-adapter-shared";
 export { ClusterMarker, type ClusterMarkerProps, type ClusterMarkerStickInput, type ClusterSegment, } from "./clusters/ClusterMarker";

package/src/layers/types.d.ts

@@ -6,7 +6,7 @@ import type { ShapesUnderCursorHit } from "./useShapes/shapeFillTiling";
 import type { ShapeLabelResolutionContext } from "./useShapes/shapeLabelResolution";
 import type { ResolveShapeStackOrder } from "./useShapes/shapeStackOrder";
 export type { ShapesUnderCursorHit };
-export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterDomRenderConfig, ClusterInfo, ClusterRenderConfig, ClusterRenderState, ClusterSymbolRenderConfig, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, HeatmapRenderStyle, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, PixelOffset, RenderConfig, RenderMedium, ResolutionContext, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeStyle, ShapeStyleOverrides, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "@trackunit/react-map-adapter-shared";
+export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterDomRenderConfig, ClusterInfo, ClusterRenderConfig, ClusterRenderState, ClusterSymbolRenderConfig, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, HeatmapRenderStyle, HeatmapRgbaColor, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, PixelOffset, RenderConfig, RenderMedium, ResolutionContext, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeStyle, ShapeStyleOverrides, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "@trackunit/react-map-adapter-shared";
 export { computeMarkerDomPortalZIndex } from "@trackunit/react-map-adapter-shared";
 /**
  * Controls whether a layer's bounds are included in fit-to-content operations.

package/src/layers/useHeatmap/useHeatmap.d.ts

@@ -2,9 +2,17 @@ import type { GeoJsonPosition } from "@trackunit/geo-json-utils";
 import type { CategoryKey, ControlConfig } from "../../controls/types";
 import type { FitParticipation, HeatmapLayerHandle } from "../types";
 export type HeatmapStyle = Readonly<{
+    /** Point radius in pixels. Default `30`, clamped to 1–100. */
     radiusPixels?: number;
+    /** Density multiplier. Default `1`, minimum `0`. */
     intensity?: number;
+    /** Layer opacity. Default `1`, clamped to 0–1. */
     opacity?: number;
+    /**
+     * Low-to-high density colours (at least two). Supports `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb()` and `rgba()`.
+     * Defaults to the Movement page gradient (transparent cyan, blue, cyan, green, yellow, red).
+     */
+    colorRange?: ReadonlyArray<string>;
 }>;
 export type UseHeatmapOptions<TItem> = Readonly<{
     id: string;

package/src/layers/useHeatmap/utils/parseHeatmapColor.d.ts

@@ -0,0 +1,7 @@
+import type { HeatmapRgbaColor } from "@trackunit/react-map-adapter-shared";
+/**
+ * Parses a CSS colour into `[r, g, b, a]`.
+ *
+ * Supports `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb()` and `rgba()`; returns `null` otherwise.
+ */
+export declare const parseHeatmapColor: (input: string) => HeatmapRgbaColor | null;

package/src/layers/useHeatmap/utils/resolveHeatmapStyle.d.ts

@@ -0,0 +1,16 @@
+import type { HeatmapRenderStyle } from "@trackunit/react-map-adapter-shared";
+type HeatmapStyleInput = Readonly<{
+    radiusPixels: number | undefined;
+    intensity: number | undefined;
+    opacity: number | undefined;
+    colorRange: ReadonlyArray<string> | undefined;
+}>;
+/** Movement page gradient (legacy Google heatmap), low to high density. */
+export declare const DEFAULT_HEATMAP_COLOR_RANGE: ReadonlyArray<string>;
+/**
+ * Applies defaults and supported ranges so both adapters receive identical style values.
+ *
+ * Finite values are clamped; non-finite values fall back to the default with one warning.
+ */
+export declare const resolveHeatmapStyle: (style: HeatmapStyleInput | undefined) => HeatmapRenderStyle;
+export {};

package/src/layers/useHeatmap/utils/warnHeatmap.d.ts

@@ -1,4 +1,4 @@
 /**
- * Single dev-warning channel for `useHeatmap` (invalid data).
+ * Single dev-warning channel for `useHeatmap` (invalid data, invalid style).
  */
 export declare const warnHeatmap: (message: string, ...details: ReadonlyArray<unknown>) => void;