@trackunit/react-map-adapter-shared 0.0.4-alpha-9d327375fc1.0

package/src/layerApiTypes.d.ts

@@ -0,0 +1,68 @@
+export type { GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry } from "@trackunit/geo-json-utils";
+export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterDomRenderConfig, ClusterInfo, ClusterRenderConfig, ClusterRenderState, ClusterSymbolRenderConfig, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, PixelOffset, RenderConfig, RenderMedium, ResolutionContext, ServerClusterConfig, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "./markerTypes";
+export { computeMarkerDomPortalZIndex } from "./markerTypes";
+/**
+ * Controls which geometric parts of a shape respond to click/hover/dblclick.
+ *
+ * - `"stroke"` — only line layers (Mapbox) or polyline overlays (Google)
+ *   respond to interaction. Polygon fills are inert.
+ * - `"stroke-and-fill"` — all layers respond, including polygon fills.
+ * - `"none"` — no interaction at all.
+ *
+ * **Points/circles are always interactive** regardless of mode (when not
+ * `"none"`). They have no meaningful fill-vs-stroke distinction and are too
+ * small for stroke-only targeting to be usable.
+ */
+export type ShapeInteractiveMode = "stroke" | "stroke-and-fill" | "none";
+/**
+ * The five visual properties that can be overridden per interaction state
+ * (hovered, selected). Excludes `pointRadius` because radius should not
+ * change on hover/select.
+ */
+export type ShapeStyleOverrides = Readonly<{
+    /** Fill color (CSS color string). Only applies to polygons and points. */
+    fill?: string;
+    /** Fill opacity from 0 to 1. Adapter applies geometry-aware defaults (polygon 0.05, point 0.2). */
+    fillOpacity?: number;
+    /** Stroke color (CSS color string) */
+    stroke?: string;
+    /** Stroke opacity from 0 to 1. Default: 1 */
+    strokeOpacity?: number;
+    /** Stroke width in pixels */
+    strokeWidth?: number;
+}>;
+/**
+ * Provider-agnostic style for shapes (polygons, lines, points).
+ * Each adapter maps these to its own style format.
+ *
+ * Prefer opaque colors for `fill` and `stroke`; use `fillOpacity` and
+ * `strokeOpacity` to control transparency. Alpha channels in color strings
+ * are still respected but multiply with these opacity values.
+ *
+ * `hovered` and `selected` allow per-shape override of visual properties
+ * when the shape is in that interaction state. Unset properties fall back
+ * to adapter-computed defaults (e.g. darkened stroke for hover).
+ */
+export interface ShapeStyle extends ShapeStyleOverrides {
+    /** Radius of point features in pixels. Default: 5 */
+    readonly pointRadius?: number;
+    /** Visual overrides applied when this shape is hovered */
+    readonly hovered?: ShapeStyleOverrides;
+    /** Visual overrides applied when this shape is selected */
+    readonly selected?: ShapeStyleOverrides;
+}
+/**
+ * Provider-agnostic style for routes/polylines.
+ */
+export type RouteStyle = Readonly<{
+    /** Line color (CSS color string) */
+    color?: string;
+    /** Line width in pixels */
+    width?: number;
+    /** Opacity from 0 to 1 */
+    opacity?: number;
+    /** Dash pattern. Omit for solid lines. */
+    dashArray?: ReadonlyArray<number>;
+    /** Whether to show directional arrows along the route */
+    showDirectionArrows?: boolean;
+}>;

package/src/layerPortHelpers.d.ts

@@ -0,0 +1,259 @@
+import type { AdaptiveRenderState, CircleSymbolDescriptor, GeoJsonFeature, GeoJsonFeatureCollection, MarkerAnchor, RenderMedium, SymbolDescriptor, SymbolRenderState } from "./layerApiTypes";
+import type { DomPortalDescriptor, MarkerSourceConfig } from "./LayerPort";
+type ReactNode = import("react").ReactNode;
+/** Simple {lng, lat} coordinate pair used across adapters */
+export type LngLat = Readonly<{
+    lng: number;
+    lat: number;
+}>;
+/**
+ * Extract {lng, lat} coordinates from a GeoJSON Point feature's geometry.
+ * Returns null if the geometry is null (unlocated feature) or not a Point.
+ */
+export declare const extractPointCoordinates: (feature: GeoJsonFeature) => LngLat | null;
+/**
+ * Extract coordinates array from a GeoJSON LineString feature.
+ * Returns an array of {lat, lng} objects, or null if empty.
+ * Returns null if the geometry is null (unlocated feature) or not a LineString.
+ */
+export declare const extractLineCoordinates: (feature: GeoJsonFeature) => Array<LngLat> | null;
+/**
+ * Extract coordinates from GeoJSON Polygon coordinates.
+ * Returns an array of rings (outer ring + holes), each an array of {lat, lng}.
+ */
+export declare const extractPolygonPaths: (coordinates: unknown) => Array<Array<LngLat>> | null;
+/**
+ * Check whether two GeoJSON feature collections contain the same features
+ * by comparing the count and individual feature IDs. Returns true if both
+ * are null, or if they have the same number of features with matching IDs
+ * in the same order.
+ *
+ * Used by adapters to skip unnecessary full marker rebuilds when a new config
+ * object is created but the underlying data hasn't changed (e.g. only callback
+ * references differ due to a React re-render).
+ */
+export declare const hasSameFeatureIds: (a: GeoJsonFeatureCollection | null, b: GeoJsonFeatureCollection | null) => boolean;
+/**
+ * Determines whether an existing marker source can be patched in place
+ * (position + portal update) instead of requiring a full teardown/rebuild.
+ *
+ * A full rebuild is required when the Mapbox/Google marker `anchor` or
+ * `pixelOffset` changes, because both are immutable after marker construction.
+ * Without this check the DOM marker keeps a stale anchor/offset while React
+ * renders with the new values.
+ */
+export declare const canPatchMarkerInPlace: (existing: MarkerSourceConfig, incoming: MarkerSourceConfig) => boolean;
+/**
+ * Extract the original source data from GeoJSON feature properties.
+ * useMarkers stores the original TItem / TCluster in properties.__data
+ * so that style functions receive the full typed object, not raw GeoJSON properties.
+ */
+export declare const extractSourceData: (properties: Readonly<Record<string, unknown>> | null) => unknown;
+type PatchPortalDescriptorsResult = Readonly<{
+    descriptors: Array<DomPortalDescriptor>;
+    changed: boolean;
+}>;
+/**
+ * Patch portal descriptors for features whose data or render function changed,
+ * preserving the existing container and key so React can update in-place
+ * without a remove-then-add cycle (which causes visible flickering).
+ *
+ * Pure function: returns a new descriptors array and a `changed` flag.
+ * Both adapters delegate to this from their `patchDomMarkers` method.
+ */
+export declare const patchPortalDescriptors: (descriptors: ReadonlyArray<DomPortalDescriptor>, sourceId: string, features: ReadonlyArray<GeoJsonFeature>, render: DomPortalDescriptor["renderFn"]) => PatchPortalDescriptorsResult;
+/**
+ * Defaults for a {@link CircleSymbolDescriptor} (per ADR-0011).
+ * - `diameterPx`: 16
+ * - `opacity`: 1
+ * - `borderColor`: null (no border)
+ * - `borderWidthPx`: 0 (no border)
+ */
+export declare const CIRCLE_SYMBOL_DEFAULT_DIAMETER_PX = 16;
+export declare const CIRCLE_SYMBOL_DEFAULT_OPACITY = 1;
+/**
+ * Resolved circle-symbol style with all defaults filled and `radiusPx` /
+ * `hasBorder` precomputed for adapter consumption (Mapbox `circle-radius`,
+ * Google canvas `ctx.arc`, conditional stroke).
+ */
+export type ResolvedCircleSymbol = Readonly<{
+    color: string;
+    diameterPx: number;
+    radiusPx: number;
+    opacity: number;
+    borderColor: string | null;
+    borderWidthPx: number;
+    hasBorder: boolean;
+}>;
+/**
+ * Fill {@link CircleSymbolDescriptor} defaults and compute `radiusPx`
+ * (`= diameterPx / 2`) and `hasBorder` (`= borderColor !== null && borderWidthPx > 0`).
+ *
+ * Pure function — adapters use this once per feature to derive the values they
+ * pass to their style format (Mapbox paint expression or canvas `ctx.arc`).
+ */
+export declare const resolveCircleSymbolDefaults: (descriptor: CircleSymbolDescriptor) => ResolvedCircleSymbol;
+/**
+ * Resolve a {@link SymbolDescriptor} by calling the style function with the
+ * source data extracted from `properties.__data`.
+ */
+export declare const resolveSymbolDescriptor: (style: (item: unknown) => SymbolDescriptor, properties: Readonly<Record<string, unknown>> | null) => SymbolDescriptor;
+/**
+ * Result of discriminating a unified `render(item, state)` return value
+ * (ADR-0009). One render callback can return either a {@link SymbolDescriptor}
+ * for map-native symbol rendering or a {@link ReactNode} for DOM portal
+ * rendering; adapters route on the discriminated `kind`.
+ */
+export type DiscriminatedRenderResult = Readonly<{
+    kind: "symbol";
+    symbol: SymbolDescriptor;
+}> | Readonly<{
+    kind: "dom";
+    node: ReactNode;
+}>;
+/**
+ * Discriminate the result of a unified `render(item, state)` callback into a
+ * symbol descriptor or a DOM node (ADR-0009).
+ *
+ * Rules:
+ * - Plain object with `color: string` → `{ kind: "symbol", symbol }`.
+ * - Anything else (strings, numbers, `null`, fragments, iterables) → treated
+ *   as a DOM node so consumers can return primitives like text directly.
+ *
+ * When the optional `expectedMedium` argument is set (adaptive routing), a dev-only
+ * `console.warn` runs if the discriminated `kind` disagrees with it — e.g.
+ * the consumer returned a `ReactNode` while `state.medium` was `"symbol"`.
+ * Omitted in production builds (`NODE_ENV === "production"`).
+ */
+export declare const discriminateRenderResult: (result: SymbolDescriptor | ReactNode, expectedMedium?: RenderMedium) => DiscriminatedRenderResult;
+/**
+ * Build a `(item) → SymbolDescriptor` closure from an adaptive
+ * {@link AdaptiveRenderConfig.render} callback (ADR-0009).
+ *
+ * Adapters that render a feature in symbol medium under `mode: "adaptive"`
+ * call render with the supplied `SymbolRenderState`, then route the result
+ * via {@link discriminateRenderResult}. When the discriminated kind is
+ * `"symbol"`, the descriptor is returned; when it disagrees with the
+ * requested medium (the consumer accidentally returned a `ReactNode`), a
+ * neutral fallback descriptor is returned so rendering can proceed (with a
+ * dev-only `console.warn` via {@link discriminateRenderResult}).
+ */
+export declare const buildAdaptiveSymbolStyleFn: (render: (item: unknown, state: AdaptiveRenderState) => SymbolDescriptor | ReactNode, state: SymbolRenderState) => ((item: unknown) => SymbolDescriptor);
+/**
+ * Build a `DomPortalDescriptor["renderFn"]` from an adaptive
+ * {@link AdaptiveRenderConfig.render} callback (ADR-0009).
+ *
+ * Adapters wrap the consumer's unified render with this when registering a
+ * DOM portal for an adaptive feature: the closure forwards the
+ * `DomRenderState` (a member of `AdaptiveRenderState`) into render, then
+ * routes the result via {@link discriminateRenderResult}, returning the
+ * `ReactNode` for `kind === "dom"` and `null` for the mismatch case where
+ * the consumer accidentally returned a `SymbolDescriptor` (with a dev-only
+ * `console.warn` via {@link discriminateRenderResult}).
+ */
+export declare const buildAdaptiveDomRenderFn: (render: (item: unknown, state: AdaptiveRenderState) => SymbolDescriptor | ReactNode) => DomPortalDescriptor["renderFn"];
+/**
+ * Create a styled cluster pin DOM element.
+ * Used by both Google Maps and Mapbox adapters for symbol-mode cluster rendering.
+ *
+ * Cluster pins keep their always-on white border (visual distinction from
+ * individual markers); only `color` is read from the descriptor.
+ */
+export declare const createClusterPinElement: (descriptor: CircleSymbolDescriptor, count: unknown) => HTMLElement;
+/**
+ * Create a default cluster element with the default blue color.
+ */
+export declare const createDefaultClusterElement: (count: unknown) => HTMLElement;
+/**
+ * Create a styled dot element for symbol-mode markers (e.g. client-clustering
+ * paths that emit per-marker DOM elements). Uses the resolved descriptor's
+ * `diameterPx` for sizing and applies the border only when `hasBorder` is true.
+ */
+export declare const createSymbolDotElement: (resolved: ResolvedCircleSymbol) => HTMLElement;
+/**
+ * Feature IDs that render as DOM markers in adaptive mode (i.e. resolved
+ * medium is `"dom"`).
+ */
+export declare const getAdaptiveDomFeatureIds: (config: MarkerSourceConfig) => Set<string>;
+/**
+ * Returns true when a render mode requires the WebGL/canvas circle layer
+ * (symbol or adaptive). Use to branch between the canvas path and
+ * the individual DOM-marker-per-feature path.
+ */
+export declare const isCanvasMarkerMode: (mode: "symbol" | "dom" | "adaptive") => boolean;
+/**
+ * Shared loop body for adaptive DOM overlay creation. Handles guards, feature
+ * iteration, and renderFn construction, then delegates marker creation to the
+ * adapter via `createMarker`.
+ *
+ * Returns one entry per DOM-rendered feature so each adapter can apply its own
+ * post-creation work (zIndex, interaction listeners, tracked-marker bookkeeping).
+ */
+export declare const buildAdaptiveDomEntries: <TMarker>(config: MarkerSourceConfig, createMarker: (featureId: string, coords: LngLat, sourceId: string, data: unknown, renderFn: DomPortalDescriptor["renderFn"]) => TMarker) => ReadonlyArray<{
+    featureId: string;
+    coords: LngLat;
+    domMarker: TMarker;
+}>;
+/**
+ * Collect the set of non-empty feature IDs from a GeoJSON feature collection.
+ * Returns an empty set when `collection` is null.
+ *
+ * Used by adapters to diff feature ID sets between config updates so they can
+ * remove gone markers and add new ones without a full teardown/rebuild.
+ */
+export declare const collectFeatureIdSet: (collection: GeoJsonFeatureCollection | null) => Set<string>;
+/**
+ * Returns true when an adaptive marker source can be patched incrementally
+ * after a viewport refetch — i.e. structural config (render mode, anchor,
+ * clustering mode, cluster render mode) matches between existing and incoming,
+ * but marker/cluster feature IDs may differ.
+ *
+ * When this returns true, adapters should diff by feature ID (add new,
+ * remove gone) instead of doing a full teardown/rebuild. This prevents
+ * existing DOM markers from flickering when only the set of visible IDs changes.
+ *
+ * Callback references (render functions) are intentionally not compared:
+ * they change on every React render and are always captured fresh during the patch.
+ */
+export declare const canPatchAdaptiveViewport: (existing: MarkerSourceConfig, incoming: MarkerSourceConfig) => boolean;
+/**
+ * Returns true when an adaptive marker source can be patched incrementally for
+ * mode transitions / portal updates where feature IDs and cluster data are stable.
+ */
+export declare const canPatchAdaptiveMarker: (existing: MarkerSourceConfig, incoming: MarkerSourceConfig) => boolean;
+type RemoveGoneIndexedMarkersInput<TMarker> = Readonly<{
+    incomingFeatureIds: ReadonlySet<string>;
+    markerIndex: Map<string, TMarker>;
+    markers: Array<TMarker>;
+    portalDescriptors: Array<DomPortalDescriptor>;
+    sourceId: string;
+    detachMarker: (marker: TMarker) => void;
+}>;
+type RemoveGoneIndexedMarkersResult<TMarker> = Readonly<{
+    markerIndex: Map<string, TMarker>;
+    markers: Array<TMarker>;
+    portalDescriptors: Array<DomPortalDescriptor>;
+    markersChanged: boolean;
+    portalDescriptorsChanged: boolean;
+}>;
+/**
+ * Removes indexed native markers whose feature IDs are no longer present and
+ * removes the matching DOM portal descriptors. The marker index is mutated in
+ * place because adapters keep it as their long-lived native marker registry.
+ */
+export declare const removeGoneIndexedMarkers: <TMarker>({ incomingFeatureIds, markerIndex, markers, portalDescriptors, sourceId, detachMarker, }: RemoveGoneIndexedMarkersInput<TMarker>) => RemoveGoneIndexedMarkersResult<TMarker>;
+/**
+ * Convert a MarkerAnchor value to a CSS transform string.
+ * Assumes the element's **bottom-center** is at the coordinate by default.
+ * Google Maps AdvancedMarkerElement positions custom DOM content at
+ * bottom-center, so all Google DOM elements (symbol dots, shape point dots,
+ * and DOM markers) need this to correct anchoring.
+ */
+export declare const anchorFromBottomCenter: (anchor: MarkerAnchor) => string;
+export declare const LAYER_FADE_DURATION_MS = 200;
+/**
+ * Start an element at opacity 0 and animate it in via CSS transition.
+ * Used for DOM-based markers in both Mapbox and Google adapters.
+ */
+export declare const fadeInElement: (el: HTMLElement) => void;
+export {};

package/src/mapEventUtils.d.ts

@@ -0,0 +1,3 @@
+import type { MapEvent, MapEventOfType } from "./primitiveMapTypes";
+/** Type predicate to narrow a MapEvent to a specific event type */
+export declare const isEventOfType: <TEventType extends MapEvent["type"]>(mapEvent: MapEvent, type: TEventType) => mapEvent is MapEventOfType<TEventType>;

package/src/mapStateUtils.d.ts

@@ -0,0 +1,11 @@
+import { type CameraState, type GeoJsonBbox, type InitialViewport, type MapAppearance, type MapState } from "./primitiveMapTypes";
+/**
+ * Compute the initial MapState from a config's appearance and optional viewport.
+ * Shared by both Google Maps and Mapbox adapters.
+ */
+export declare const computeInitialState: (appearance: MapAppearance, initialViewport?: InitialViewport) => MapState;
+export declare const bboxEquals: (a: Readonly<GeoJsonBbox> | null, b: Readonly<GeoJsonBbox> | null) => boolean;
+/** Field-wise equality for camera state (center, zoom, bounds, isIdle). */
+export declare const cameraStateEquals: (a: CameraState, b: CameraState) => boolean;
+/** Field-wise equality for the full combined MapState. */
+export declare const mapStateEquals: (a: MapState, b: MapState) => boolean;

package/src/markerDomPortalStacking.d.ts

@@ -0,0 +1,36 @@
+import type { MapTheme } from "./primitiveMapTypes";
+/**
+ * Visual role of a DOM portal marker for **global** stacking (z-index) on the map.
+ *
+ * Ordering (back → front): `cluster` < `circle` < `pill` < `stick`.
+ * Cluster DOM is kept behind individual markers so promoted pins stay clickable.
+ */
+export type MarkerDomPortalStackGeometry = "circle" | "pill" | "stick" | "cluster";
+/**
+ * Interaction-driven band within a geometry tier. Back → front:
+ * `expanded` < `idle` < `hovered` < `selected`.
+ */
+export type MarkerDomPortalStackPhase = "expanded" | "idle" | "hovered" | "selected";
+/**
+ * Inputs threaded from {@link DomRenderState} for portal stacking decisions.
+ */
+export type DomPortalStackingInput = Readonly<{
+    selected: boolean;
+    hovered: boolean;
+    labelVisible: boolean;
+    isMounting: boolean;
+    theme: MapTheme;
+}>;
+export type DomPortalStackingResult = Readonly<{
+    geometry: MarkerDomPortalStackGeometry;
+    phase: MarkerDomPortalStackPhase;
+}>;
+export type DomPortalStackingResolver = (item: unknown, input: DomPortalStackingInput) => DomPortalStackingResult;
+/**
+ * Single source of truth for DOM marker portal `z-index` values.
+ *
+ * Higher geometry tiers always sort above lower tiers regardless of phase
+ * (e.g. any `pill` stacks above any `circle`). Within a tier, phase orders
+ * expanded → idle → hovered → selected.
+ */
+export declare const computeMarkerDomPortalZIndex: (geometry: MarkerDomPortalStackGeometry, phase: MarkerDomPortalStackPhase) => number;