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

package/src/core/types.d.ts

@@ -0,0 +1,208 @@
+export { DEFAULT_MAP_APPEARANCE, INITIAL_CAMERA_STATE, INITIAL_MAP_STATE, INITIAL_MAP_STATUS, mapAppearanceSchema, mapThemeSchema, mapTypeSchema, } from "@trackunit/react-map-adapter-shared";
+export type { CameraState, ContainerRefHolder, FitBoundsOptions, GeoJsonBbox, GeoJsonPosition, InitialViewport, MapAppearance, MapComponentProps, MapEvent, MapEventHandler, MapEventOfType, MapState, MapStatus, MapTheme, MapType, StoredEventHandler, } from "@trackunit/react-map-adapter-shared";
+import type { AdapterConfig, CameraState, ContainerRefHolder, FitBoundsOptions, GeoJsonBbox, GeoJsonPosition, MapComponentProps, MapEvent, MapEventHandler, MapStatus, MapTheme, MapType } from "@trackunit/react-map-adapter-shared";
+import type { ComponentType } from "react";
+import type { MapAnnotationStore } from "../annotations/mapAnnotations";
+import type { ControlsConfig, UseMapOptions } from "../controls/types";
+import type { PanelStore } from "../panel/store/panels";
+import type { MapLoadingIndicatorStore } from "./loadingIndicator";
+/**
+ * Map actions - methods to control the map
+ * All action references are stable across re-renders
+ */
+export type MapActions = Readonly<{
+    /**
+     * Set the map center
+     *
+     * @param center - Position as [longitude, latitude]
+     * @returns Promise that resolves when the map finishes moving
+     */
+    setCenter: (center: GeoJsonPosition) => Promise<void>;
+    /**
+     * Set the zoom level (absolute)
+     *
+     * @param zoom - Zoom level (0-22)
+     * @returns Promise that resolves when the map finishes zooming
+     */
+    setZoom: (zoom: number) => Promise<void>;
+    /**
+     * Adjust zoom by delta (relative)
+     *
+     * @param delta - Amount to adjust zoom (positive = zoom in, negative = zoom out)
+     * @returns Promise that resolves when the map finishes zooming
+     */
+    zoomBy: (delta: number) => Promise<void>;
+    /**
+     * Fit the map to the given bounds
+     *
+     * @param bounds - Bounding box as [minLon, minLat, maxLon, maxLat]
+     * @param options - Optional configuration for the fit operation
+     * @param options.padding - Padding in pixels around the bounds. Defaults to 0 if omitted.
+     * @param options.maxZoom - Maximum zoom level after fitting
+     * @param options.animate - Whether to animate the transition
+     * @returns Promise that resolves when the map finishes fitting
+     */
+    fitBounds: (bounds: GeoJsonBbox, options?: FitBoundsOptions) => Promise<void>;
+    /**
+     * Pan the map to the given center with animation
+     *
+     * @param center - Position as [longitude, latitude]
+     * @returns Promise that resolves when the map finishes panning
+     */
+    panTo: (center: GeoJsonPosition) => Promise<void>;
+    /**
+     * Pan the map by pixel offsets (for keyboard navigation and UI-driven panning).
+     * Unlike geographic methods (setCenter, panTo), this operates in screen space.
+     *
+     * @param deltaX - Horizontal offset in pixels (positive = right)
+     * @param deltaY - Vertical offset in pixels (positive = down)
+     * @returns Promise that resolves when the map finishes panning
+     */
+    panBy: (deltaX: number, deltaY: number) => Promise<void>;
+    /**
+     * Set the map type (base layer)
+     *
+     * @param type - Map type ("roadmap", "satellite", or "hybrid")
+     * @returns Promise that resolves when the map type is set
+     */
+    setMapType: (type: MapType) => Promise<void>;
+    /**
+     * Set the map theme (visual appearance)
+     *
+     * @param theme - Map theme ("light" or "dark")
+     * @returns Promise that resolves when the theme is applied
+     */
+    setTheme: (theme: MapTheme) => Promise<void>;
+    /**
+     * Set whether road labels are shown over satellite/hybrid imagery
+     *
+     * @param showRoads - Whether to show road labels
+     * @returns Promise that resolves when the change is applied
+     */
+    setShowRoads: (showRoads: boolean) => Promise<void>;
+}>;
+/**
+ * The API object returned as the second element of the useMap tuple.
+ * Contains low-frequency map status, actions, event subscription, and controls
+ * configuration. All properties are readonly and action references are stable.
+ *
+ * `api.state` is the MapStatus channel. `api` identity is stable between camera
+ * events (pan/zoom), so components that only need status are not tied to viewport
+ * updates. To react to viewport changes, use `useCameraState(api)`.
+ */
+export type MapApi = Readonly<{
+    /**
+     * MapStatus — lifecycle and appearance state.
+     * Changes on initialization, failure, theme/type changes, or tile-size updates.
+     * For viewport state (center, zoom, bounds, isIdle), use `useCameraState(api)`.
+     */
+    state: MapStatus;
+    /**
+     * Subscribe to camera state changes (center, zoom, bounds, isIdle).
+     * Stable reference across re-renders (only changes on adapter swap).
+     * Prefer `useCameraState(api)` from React components; this method is exposed
+     * for lower-level integration code.
+     */
+    subscribeCamera: (listener: () => void) => () => void;
+    /**
+     * Get the latest camera state snapshot.
+     * Stable reference across re-renders (only changes on adapter swap).
+     * Prefer `useCameraState(api)` when a React component should re-render on
+     * camera changes.
+     */
+    getCameraState: () => CameraState;
+    /**
+     * Map actions - stable references for controlling the map
+     */
+    actions: MapActions;
+    /**
+     * Subscribe to map events
+     *
+     * @param event - Event type to listen for
+     * @param handler - Handler function called when event occurs
+     * @returns Unsubscribe function
+     * @example
+     * ```tsx
+     * useEffect(() => {
+     *   return api.on("click", (e) => {
+     *     console.log("Clicked at:", e.position);
+     *   });
+     * }, [api.on]);
+     * ```
+     */
+    on: <TEventType extends MapEvent["type"]>(event: TEventType, handler: MapEventHandler<TEventType>) => () => void;
+    /**
+     * Options passed to useMap for controls configuration.
+     * Used by the Controls component to build the controls config.
+     */
+    options?: UseMapOptions;
+    /**
+     * Stabilized adapter configuration used to create this map instance.
+     * Use `adapterConfig.derive(overrides)` to create variant configs
+     * for spawning sibling map instances (e.g., preview maps with different themes).
+     * Equivalent inline adapter factory calls do not replace this reference.
+     *
+     * @example
+     * ```typescript
+     * const darkPreview = api.adapterConfig.derive({ theme: "dark" });
+     * ```
+     */
+    adapterConfig: AdapterConfig;
+    /**
+     * Ref to the Map component's wrapper div.
+     * Can be used for fullscreen requests, portal targeting, or measuring the container.
+     * The ref is populated after the Map component mounts.
+     */
+    containerRef: ContainerRefHolder;
+    /**
+     * Annotation store for registering map-level labels and status content.
+     * Used by `useMapAnnotation` to register annotations and by `Controls`
+     * to subscribe and render them. Stable reference across re-renders.
+     */
+    annotations: MapAnnotationStore;
+    /**
+     * Loading indicator store. `useLayers` pushes its aggregated loading
+     * state here; the Map component subscribes and renders a spinner overlay.
+     * Stable reference across re-renders.
+     */
+    loadingIndicator: MapLoadingIndicatorStore;
+    /**
+     * Panel store for marker/layer info panels. Layers register panels via
+     * `usePanel`; the Map's internal `PanelOrchestrator` subscribes
+     * and renders them as a Sheet (narrow containers) or floating elements
+     * anchored to the marker (wide containers). Stable reference across
+     * re-renders.
+     */
+    panels: PanelStore;
+    /**
+     * Controls configuration - pure data describing what controls are enabled.
+     * Used by the Controls component to determine what to render.
+     *
+     * @deprecated Use `api.options` for `useMap` options, or pass `controlsConfig`
+     * directly to `<Controls />` for custom controls.
+     */
+    controlsConfig?: ControlsConfig;
+}>;
+/**
+ * Result returned by useMap hook as a tuple.
+ *
+ * First element is the Map component, second is the API object.
+ * This follows the idiomatic React pattern (like useState, useReducer).
+ *
+ * @example
+ * ```tsx
+ * const [Map, api] = useMap(googleMapsAdapter({ apiKey }));
+ *
+ * return (
+ *   <Map>
+ *     <Controls api={api} />
+ *   </Map>
+ * );
+ * ```
+ */
+export type UseMapReturn = readonly [
+    /** Map component to render - reference is stable across re-renders */
+    ComponentType<MapComponentProps>,
+    /** API object with status, actions, event subscriptions, and map stores */
+    MapApi
+];

package/src/core/useCameraIdle.d.ts

@@ -0,0 +1,2 @@
+import type { MapApi } from "./types";
+export declare const useCameraIdle: (api: MapApi | undefined) => boolean;

package/src/core/useCameraState.d.ts

@@ -0,0 +1,3 @@
+import { type CameraState } from "@trackunit/react-map-adapter-shared";
+import type { MapApi } from "./types";
+export declare const useCameraState: (api: MapApi | undefined) => CameraState;

package/src/core/useMap.d.ts

@@ -0,0 +1,57 @@
+import { type AdapterConfig } from "@trackunit/react-map-adapter-shared";
+import type { UseMapOptions } from "../controls/types";
+import { type UseMapReturn } from "./types";
+/**
+ * useMap hook - the main entry point for using the map
+ *
+ * Returns a tuple of [Map, api] where Map is the component to render
+ * and api contains map status, actions, event subscriptions, containerRef, and
+ * controls configuration. `api.state` is MapStatus only: use it for readiness,
+ * initialization failure, appearance, and tile size.
+ *
+ * Camera state (center, zoom, bounds, isIdle) is exposed through
+ * `useCameraState(api)` so components opt in to high-frequency viewport updates.
+ *
+ * All action functions and the Map component reference are stable across re-renders.
+ *
+ * @param adapterConfig - Adapter configuration from an adapter factory (e.g., googleMapsAdapter)
+ * @param options - Optional configuration for controls and other features
+ * @returns Tuple of [Map component, API object]
+ * @example Basic usage
+ * ```tsx
+ * import { useMap, Controls } from "@trackunit/react-map";
+ * import { googleMapsAdapter } from "@trackunit/react-map-adapter-google";
+ *
+ * const MyMap = () => {
+ *   const [Map, api] = useMap(googleMapsAdapter({
+ *     apiKey: "...",
+ *     theme: "light",
+ *   }));
+ *
+ *   return (
+ *     <Map>
+ *       <Controls api={api} />
+ *     </Map>
+ *   );
+ * };
+ * ```
+ * @example Accessing camera state (center, zoom, bounds)
+ * Camera state (viewport) can update continuously during panning and zooming.
+ * Use `useCameraState` only from components that render or react to viewport changes:
+ * ```tsx
+ * import { useDebounce } from "@trackunit/react-components";
+ * import { useMap, useCameraState } from "@trackunit/react-map";
+ * import { googleMapsAdapter } from "@trackunit/react-map-adapter-google";
+ *
+ * const MyComponent = () => {
+ *   const [Map, api] = useMap(googleMapsAdapter({ apiKey: "..." }));
+ *   const { center, zoom, bounds } = useCameraState(api);
+ *
+ *   // Debounce bounds for API calls (wait 200ms after map stops moving)
+ *   const debouncedBounds = useDebounce(bounds, { delay: 200 });
+ *
+ *   return <Map>...</Map>;
+ * };
+ * ```
+ */
+export declare const useMap: <TConfig extends Record<string, unknown>>(adapterConfig: AdapterConfig<TConfig>, options?: UseMapOptions) => UseMapReturn;

package/src/core/useMapAdapterState.d.ts

@@ -0,0 +1,14 @@
+import type { AdapterConfig, AdapterInstance } from "@trackunit/react-map-adapter-shared";
+type MapAdapterState = Readonly<{
+    adapter: AdapterInstance;
+    renderConfig: AdapterConfig;
+}>;
+/**
+ * Manages adapter instance and render config as related state.
+ * Handles adapter switching when adapterConfig changes to a different provider,
+ * preserving viewport (center, zoom, bounds when available).
+ *
+ * @internal
+ */
+export declare function useMapAdapterState(adapterConfig: AdapterConfig): MapAdapterState;
+export {};

package/src/core/useMapKeyboardNavigation.d.ts

@@ -0,0 +1,38 @@
+import type { RefObject } from "react";
+import type { ContainerRefHolder } from "./types";
+/**
+ * Narrow structural type for the keyboard navigation hook.
+ * Contains only the stable properties the hook actually reads:
+ * - `actions.panBy` and `actions.zoomBy` (stable — memoized on adapter)
+ * - `containerRef` (stable — created via useState)
+ *
+ * `MapApi` satisfies this type via structural subtyping, so consumers
+ * can pass `api` from `useMap()` directly without any assertion.
+ */
+export type MapKeyboardNavigationApi = Readonly<{
+    actions: Readonly<{
+        panBy: (deltaX: number, deltaY: number) => Promise<void>;
+        zoomBy: (delta: number) => Promise<void>;
+    }>;
+    containerRef: ContainerRefHolder;
+}>;
+/**
+ * Opt-in keyboard navigation hook for map components.
+ * Provides consistent keyboard shortcuts:
+ * - Arrow keys: Pan the map in all directions
+ * - `=` key: Zoom in
+ * - `-` key: Zoom out
+ *
+ * **Usage:**
+ * ```tsx
+ * import { useMap, useMapKeyboardNavigation } from "@trackunit/react-map";
+ * import { googleMapsAdapter } from "@trackunit/react-map-adapter-google";
+ *
+ * const [Map, api] = useMap(googleMapsAdapter({ apiKey }));
+ * useMapKeyboardNavigation(api);
+ * ```
+ *
+ * @param api - The map API object (or any object matching `MapKeyboardNavigationApi`)
+ * @param containerRef - Optional override for the keyboard event target. Defaults to `api.containerRef`.
+ */
+export declare const useMapKeyboardNavigation: (api: MapKeyboardNavigationApi, containerRef?: RefObject<HTMLElement | null>) => void;

package/src/core/usePreviewMap.d.ts

@@ -0,0 +1,43 @@
+import type { AdapterConfig } from "@trackunit/react-map-adapter-shared";
+import { type ComponentType } from "react";
+import type { MapComponentProps, MapType } from "./types";
+/**
+ * Options for the preview map
+ */
+type UsePreviewMapOptions = Readonly<{
+    /** Map type to set once the map is ready (e.g., "satellite" for satellite previews) */
+    mapType?: MapType;
+}>;
+/**
+ * Return value of the `usePreviewMap` hook.
+ *
+ * Provides `Map` (a stable, memoised component reference) and `ready`
+ * to indicate whether the adapter instance has finished initializing.
+ */
+export type UsePreviewMapReturn = Readonly<{
+    /** Stable Map component reference — safe to render without triggering the static-components lint rule */
+    Map: ComponentType<MapComponentProps>;
+    /** Whether the preview adapter instance reports `isReady` */
+    ready: boolean;
+}>;
+/**
+ * Creates a lightweight, non-interactive sibling map from a derived AdapterConfig.
+ *
+ * Returns a stable `Map` component reference and a `ready` flag.
+ * Use this to spawn preview maps for map style settings.
+ *
+ * The preview map optionally sets a mapType after the adapter connects,
+ * which is needed for satellite/hybrid previews where the base layer
+ * differs from the default.
+ *
+ * @param adapterConfig - Adapter config (typically from `api.adapterConfig.derive(overrides)`)
+ * @param options - Optional settings like mapType
+ * @returns Object with a stable `Map` component and a `ready` boolean
+ * @example
+ * ```tsx
+ * const { Map: PreviewMap } = usePreviewMap(api.adapterConfig.derive({ theme: "dark" }));
+ * return <PreviewMap className="h-18 w-18" />;
+ * ```
+ */
+export declare const usePreviewMap: (adapterConfig: AdapterConfig, options?: UsePreviewMapOptions) => UsePreviewMapReturn;
+export {};

package/src/index.d.ts

@@ -0,0 +1,69 @@
+export type { CameraState, ContainerRefHolder, FitBoundsOptions, GeoJsonBbox, GeoJsonPosition, InitialViewport, MapActions, MapApi, MapAppearance, MapComponentProps, MapEvent, MapEventHandler, MapEventOfType, MapState, MapStatus, MapTheme, MapType, UseMapReturn, } from "./core/types";
+export { DEFAULT_MAP_APPEARANCE, INITIAL_CAMERA_STATE, INITIAL_MAP_STATE, INITIAL_MAP_STATUS, mapAppearanceSchema, mapThemeSchema, mapTypeSchema, } from "./core/types";
+export type { AvailableSpace, BooleanControlConfig, BuiltInControlsConfig, BuiltInNavigationConfig, BuiltInSettingsConfig, ButtonControlConfig, CategoryKey, CheckboxControlConfig, Compactness, ControlConfig, ControlsConfig, ControlsOptions, CustomControlConfig, CustomControlRenderContext, IconName, MenuControlConfig, MenuItemConfig, NavigationConfig, OverflowBehavior, Placement, RadioGroupControlConfig, RenderContext, ResolvedControlProps, ResolvedControlPropsBase, ResponsiveMode, SearchControlConfig, SelectControlConfig, SeparatorItemConfig, SettingsConfig, StatisticsConfig, StepperControlConfig, ToggleControlConfig, ToggleGroupControlConfig, ToggleGroupOption, UseMapOptions, } from "./controls/types";
+export { defineAdapter } from "@trackunit/react-map-adapter-shared";
+export type { AdapterConfig, AdapterConfigBase, AdapterInstance, AdapterRendererProps, SafeAreaInsets, } from "@trackunit/react-map-adapter-shared";
+export { useCameraIdle } from "./core/useCameraIdle";
+export { useCameraState } from "./core/useCameraState";
+export { useMap } from "./core/useMap";
+export { useMapKeyboardNavigation, type MapKeyboardNavigationApi } from "./core/useMapKeyboardNavigation";
+export { usePreviewMap, type UsePreviewMapReturn } from "./core/usePreviewMap";
+export { MapLoadingState } from "./core/MapLoadingState";
+export { Controls } from "./controls/Controls";
+export type { ControlStackItem } from "./controls/defineControlStack";
+export { useControlsConfig } from "./controls/useControlsConfig";
+export type { AppearanceAction, AppearanceOption, AppearanceOptions, MapAppearanceApi, PersistedAppearance, UseMapAppearanceControlsParams, } from "./appearance/appearanceTypes";
+export { useMapAppearanceControls } from "./appearance/useMapAppearanceControls";
+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, ImageOverlayHandle, LayerHandle, LayerMeta, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, MarkerLayerHandle, RenderConfig, RenderMedium, ResolutionContext, RouteLayerHandle, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeLayerHandle, ShapeStyle, ShapeStyleOverrides, 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";
+export { ClusterStick, type ClusterStickProps } from "./clusters/ClusterStick";
+export { useDirectionIndicator, type DirectionIndicatorDisplay, } from "./markers/geometry/useDirectionIndicator";
+export { MapMarker, type MapMarkerProps } from "./markers/MapMarker";
+export { MapMarkerIcon } from "./markers/MapMarkerIcon";
+export type { MapMarkerDomPortalStackingByMarkerState, MapMarkerDomPortalStackingByPromotion, MapMarkerDomPortalStackingParams, } from "./markers/model/mapMarkerDomPortalStacking";
+export type { ClusterStickState, MarkerDomSize, MarkerForm, MarkerSizeDimensions, MarkerState, StickDistanceMode, StickPositioning, } from "./markers/model/markerDomTypes";
+export type { MarkerRenderStateInput } from "./markers/model/markerResolvers";
+export { MARKER_PILL_CONTENT_LAYOUT_SIZE, MARKER_SIZE_MAP, } from "./markers/model/markerSizeMap";
+export { MARKER_TUNING } from "./markers/model/markerTuningParams";
+export { cvaMapMarker, cvaMarkerIndicator } from "./markers/shared/mapMarkerVariants";
+export { MARKER_DARK_PILL, MARKER_LIGHT_PILL, } from "./markers/shared/markerColors";
+export type { MarkerColorConfig, MarkerColorCssVars, ResolvedMarkerColors } from "./markers/shared/markerColors";
+export { type HoverPanelPreloadInitiator, type PanelPreloadInitiator, type PanelPreloadInitiatorType, type ProximityPanelPreloadInitiator, } from "./panel/preload/preloadInitiators";
+export { usePanelPreload, type UsePanelPreloadOptions } from "./panel/preload/usePanelPreload";
+export { type PanelStore } from "./panel/store/panels";
+export { usePanel, type UsePanelOptions } from "./panel/usePanel";
+export { type AutoPanContext, type AutoPanResult } from "./panel/utils/autoPan";
+export type { DecorationAnchor, EdgeSide, ShapeDecoration } from "./layers/useShapes/shapeDecorations";
+export { type AnnotationContext, type ShapeLabelPolicy, } from "./layers/useShapes/shapeLabelPolicy";
+export type { ResolveShapeLabel, ShapeLabelResolution, ShapeLabelResolutionContext, } from "./layers/useShapes/shapeLabelResolution";
+export { useImageOverlay, type UseImageOverlayOptions, type UseImageOverlayReturn, } from "./layers/image-overlay/useImageOverlay";
+export { buildExpandedIds, useExpandedIds, type MapFocus, type MapFocusTier, type MapFocusTierDisplay, } from "./layers/mapFocus";
+export { useRoute, type UseRouteOptions, type UseRouteReturn } from "./layers/routes/useRoute";
+export { useFitToContent, type FitToContentOptions, type FitToContentResult } from "./layers/useFitToContent";
+export { useLayers, type UseLayersReturn } from "./layers/useLayers";
+export { DEFAULT_MARKER_SIZE_BREAKPOINTS, MARKER_DISC_BORDER_WIDTH_PX, type MarkerSizeBreakpoint, type PickMarkerSizeOptions, type PickRenderMediumOptions, type PickSymbolDiameterOptions, } from "./layers/useMarkers/adaptiveHelpers";
+export { useMarkers, type UseMarkersOptions, type UseMarkersReturn } from "./layers/useMarkers/useMarkers";
+export { useShapes, type UseShapesOptions, type UseShapesReturn } from "./layers/useShapes/useShapes";
+export { Layers } from "./layers/Layers";
+export { type MapLoadingIndicatorStore } from "./core/loadingIndicator";
+export { type MapAnnotationDescriptor, type MapAnnotationStore, } from "./annotations/mapAnnotations";
+export { useMapAnnotation } from "./annotations/useMapAnnotation";
+export { useMapAnnotations } from "./annotations/useMapAnnotations";
+export { ShapeAnnotationLabel } from "./layers/useShapes/ShapeAnnotationLabel";
+export { useViewportContext, type ViewportContext } from "./layers/internal/useViewportContext";
+export type { AnchoredContentConfig, EntityInteractionEvent, EntityInteractionHandler, ImageOverlayConfig as ImageOverlaySourceConfig, InteractiveMarkerConfig, LayerPort, LayerSnapshot, MapLayer, MarkerSourceConfig, RouteSourceConfig, ShapeInteractionState, ShapeSourceConfig, } from "@trackunit/react-map-adapter-shared";
+export { useAdaptiveMarkerHelpers, type AdaptiveMarkerHelpers } from "./layers/useMarkers/useAdaptiveMarkerHelpers";
+export { useFitFeatureBounds, type FitFeatureBoundsHelpers } from "./layers/internal/useFitFeatureBounds";
+export { useAutoPanResolver, type AutoPanResolverHelpers } from "./panel/utils/useAutoPanResolver";
+export { useClusterCountFormat, type ClusterCountFormatHelpers } from "./clusters/useClusterCountFormat";
+export { useControlStack, type ControlStackHelpers } from "./controls/useControlStack";
+export { useMarkerColors, type MarkerColorHelpers } from "./markers/shared/useMarkerColors";
+export { useMarkerStateResolvers, type MarkerStateResolvers } from "./markers/model/useMarkerStateResolvers";
+export { useShapeLabelHelpers, type ShapeLabelHelpers } from "./layers/useShapes/useShapeLabelHelpers";
+export { mockMapApi } from "./testing/mockMapApi";

package/src/interactions/interactionReducer.d.ts

@@ -0,0 +1,31 @@
+import { type Entity, type MapInteractionState } from "@trackunit/react-map-adapter-shared";
+type SelectAction = Readonly<{
+    type: "SELECT";
+    entity: Entity | null;
+}>;
+type HoverAction = Readonly<{
+    type: "HOVER";
+    entity: Entity | null;
+}>;
+type ClearSelectionAction = Readonly<{
+    type: "CLEAR_SELECTION";
+}>;
+type ClearHoverAction = Readonly<{
+    type: "CLEAR_HOVER";
+}>;
+type ClearAllAction = Readonly<{
+    type: "CLEAR_ALL";
+}>;
+/**
+ * Discriminated union of all interaction actions.
+ */
+export type InteractionAction = Readonly<SelectAction | HoverAction | ClearSelectionAction | ClearHoverAction | ClearAllAction>;
+/**
+ * Pure reducer for map entity interaction state.
+ *
+ * - SELECT / HOVER replace the current selected/hovered entity (cross-layer).
+ * - CLEAR_SELECTION / CLEAR_HOVER reset that specific field.
+ * - CLEAR_ALL resets both to null.
+ */
+export declare const interactionReducer: (state: MapInteractionState, action: InteractionAction) => MapInteractionState;
+export {};

package/src/layers/Layers.d.ts

@@ -0,0 +1,32 @@
+import type { MapApi } from "../core/types";
+import type { UseLayersReturn } from "./useLayers";
+type LayersProps = Readonly<{
+    /** The result from `useLayers()` */
+    layers: UseLayersReturn;
+    /** Map API for viewport-aware features (e.g. edge labels). Optional for backward compat. */
+    api?: MapApi;
+}>;
+/**
+ * `<Layers>` -- rendering bridge between layer handles and the map adapter.
+ *
+ * Rendered as a child of `<Map>`. Reads the `LayerPort` from context
+ * (provided by `createMapComponent`) and pushes a full `LayerSnapshot` to
+ * the adapter on every change. The adapter owns the diff.
+ *
+ * This component is renderless -- it produces no DOM output. It exists
+ * solely to manage the lifecycle of layer sources on the adapter.
+ *
+ * @example
+ * ```tsx
+ * const layers = useLayers(api, [markers, zones]);
+ *
+ * return (
+ *   <Map>
+ *     <Controls api={api} />
+ *     <Layers api={api} layers={layers} />
+ *   </Map>
+ * );
+ * ```
+ */
+export declare const Layers: ({ layers, api }: LayersProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

package/src/layers/__testHelpers.d.ts

@@ -0,0 +1,24 @@
+import type { GeoJsonBbox, GeoJsonFeature, GeoJsonFeatureCollection } from "@trackunit/geo-json-utils";
+import type { LayerPort } from "@trackunit/react-map-adapter-shared";
+import { type Mock } from "vitest";
+import type { MapApi, MapState } from "../core/types";
+import type { LayerHandle, ShapeLayerHandle } from "./types";
+import type { UseLayersReturn } from "./useLayers";
+export declare const POLYGON_FEATURES: GeoJsonFeatureCollection;
+export declare const VIEWPORT_BOUNDS: GeoJsonBbox;
+/** Viewport entirely inside the polygon (edges at 0/10) so no edge is visible */
+export declare const INTERIOR_ONLY_BOUNDS: GeoJsonBbox;
+export type MockLayerPort = LayerPort & {
+    setSnapshot: Mock;
+    onEntityInteraction: Mock;
+    onBackgroundClick: Mock;
+    onSourceReady: Mock;
+};
+export type MockLayerPortWithReadiness = {
+    port: MockLayerPort;
+    fireSourceReady: (configId: string) => void;
+};
+export declare const createMockLayerPort: () => MockLayerPortWithReadiness;
+export declare const createMockMapApi: (bounds?: GeoJsonBbox | null, stateOverrides?: Partial<MapState>) => MapApi;
+export declare const createShapeHandle: (id: string, labelFn?: (feature: GeoJsonFeature) => string | undefined, features?: GeoJsonFeatureCollection) => ShapeLayerHandle;
+export declare const createMockLayersReturn: (handles: ReadonlyArray<LayerHandle>) => UseLayersReturn;

package/src/layers/buildExpandedIds.d.ts

@@ -0,0 +1,17 @@
+import type { MapFocus } from "./mapFocus";
+/**
+ * Builds the set of item ids that should render as expanded by walking tiers
+ * in order and filling up to `limit`.
+ *
+ * When `getPosition` is provided and a tier would overflow the remaining
+ * budget, farthest-point spread sampling is applied so the chosen markers
+ * are distributed across the viewport rather than biased toward whatever
+ * order the server happened to return.
+ *
+ * When `previousIds` is provided, candidates that appear in it are
+ * pre-selected within each tier before the spread runs on the remaining
+ * candidates. This produces hysteresis: markers that were already expanded
+ * stay expanded across incremental data updates. Tier order is always
+ * respected — a lower-tier incumbent never displaces a higher-tier newcomer.
+ */
+export declare const buildExpandedIds: <TAsset>(items: ReadonlyArray<TAsset>, getId: (item: TAsset) => string, focus: MapFocus<TAsset>, limit: number, getPosition?: (item: TAsset) => readonly [number, number, ...Array<number>], previousIds?: ReadonlySet<string>) => ReadonlySet<string>;

package/src/layers/image-overlay/useImageOverlay.d.ts

@@ -0,0 +1,39 @@
+import { type GeoJsonBbox } from "@trackunit/geo-json-utils";
+import type { ControlConfig } from "../../controls/types";
+import type { FitParticipation, ImageOverlayHandle } from "../types";
+export type UseImageOverlayOptions = Readonly<{
+    /** Unique ID for this layer */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** URL of the image to display on the map */
+    url: string;
+    /** Geographic bounds the image covers as [minLon, minLat, maxLon, maxLat] */
+    imageBounds: GeoJsonBbox;
+    /** Opacity from 0 to 1. Default: 1 */
+    opacity?: number;
+    /** Optional controls to contribute to the map UI */
+    controls?: ReadonlyArray<ControlConfig>;
+    /** Whether the layer is currently loading its initial data. Omit for static (non-loading) layers. */
+    loading?: boolean;
+    /** Controls whether this layer's bounds are included in fit-to-content operations. Default: `"all"` */
+    fitParticipation?: FitParticipation;
+}>;
+export type UseImageOverlayReturn = ImageOverlayHandle;
+/**
+ * `useImageOverlay` -- creates an image overlay layer handle.
+ *
+ * Renders a georeferenced image on the map within the given bounds.
+ *
+ * @example
+ * ```tsx
+ * const overlay = useImageOverlay({
+ *   id: "site-plan",
+ *   name: "Site Plan",
+ *   url: "https://example.com/site-plan.png",
+ *   imageBounds: [-73.99, 40.74, -73.97, 40.76],
+ *   opacity: 0.7,
+ * });
+ * ```
+ */
+export declare const useImageOverlay: (options: UseImageOverlayOptions) => UseImageOverlayReturn;

package/src/layers/internal/MapLayerContext.d.ts

@@ -0,0 +1,24 @@
+import type { LayerPort } from "@trackunit/react-map-adapter-shared";
+/**
+ * Internal context that provides the adapter's LayerPort to layer rendering components.
+ *
+ * Provided by `createMapComponent` when the adapter has layer capabilities.
+ * Consumed by the `<Layers>` component to communicate layer data to the adapter.
+ *
+ * @internal
+ */
+export declare const MapLayerContext: import("react").Context<Readonly<{
+    setSnapshot: (snapshot: import("@trackunit/react-map-adapter-shared").LayerSnapshot) => void;
+    onEntityInteraction: (handler: import("@trackunit/react-map-adapter-shared").EntityInteractionHandler) => () => void;
+    onBackgroundClick: (handler: () => void) => () => void;
+    onSourceReady: (configId: string, callback: () => void) => () => void;
+    markerPortals?: import("@trackunit/react-map-adapter-shared").DomPortalStore | null;
+    clusterPortals?: import("@trackunit/react-map-adapter-shared").DomPortalStore | null;
+}> | null>;
+/**
+ * Hook to access the LayerPort from the nearest MapLayerContext.
+ * Returns null if the adapter doesn't support layers.
+ *
+ * @internal
+ */
+export declare const useLayerPort: () => LayerPort | null;

package/src/layers/internal/adaptiveMarkerResolution.d.ts

@@ -0,0 +1,33 @@
+import type { GeoJsonFeatureCollection } from "@trackunit/geo-json-utils";
+import { type AdaptiveMarkerResolution, type AdaptiveRenderConfig, type MapInteractionState, type RenderMedium } from "@trackunit/react-map-adapter-shared";
+import type { MapApi } from "../../core/types";
+import type { LayerHandle } from "../types";
+type AdaptiveResolutionInputs = Readonly<{
+    zoom: number;
+    markersInViewport: number;
+    selectedMarkerId: string | null;
+    hoveredMarkerId: string | null;
+    debouncedHoveredMarkerId: string | null;
+}>;
+/**
+ * Pure resolution for one adaptive marker layer (used by the hook and tests).
+ */
+export declare const computeAdaptiveMarkerResolutionForLayer: (collection: GeoJsonFeatureCollection, markerRender: AdaptiveRenderConfig<unknown>, inputs: AdaptiveResolutionInputs, previousModes: ReadonlyMap<string, RenderMedium> | undefined) => AdaptiveMarkerResolution;
+/**
+ * Computes per-feature adaptive modes for all `mode: "adaptive"` marker layers.
+ * Intended for use inside `<Layers>` only.
+ *
+ * Resolution is computed **during render** (via `useMemo`) so it stays aligned with
+ * `interaction` in the same commit — avoids one frame of stale `adaptiveResolution`
+ * on hover/select before effects ran (which caused visible DOM/symbol flicker).
+ *
+ * Viewport state (`zoom`, `bounds`) is read from the camera store with
+ * `useSyncExternalStore`, keeping idle/moving transitions aligned with the same
+ * snapshot that drives viewport consumers.
+ *
+ * Previous-frame mode tracking (for animation continuity) is intentionally left to
+ * each adapter — they own the mutable DOM marker state and can diff their own
+ * previous modes on each `setSnapshot` call without coupling to React render cycles.
+ */
+export declare const useAdaptiveMarkerResolution: (handles: ReadonlyArray<LayerHandle>, interaction: MapInteractionState, api: MapApi | undefined) => ReadonlyMap<string, AdaptiveMarkerResolution>;
+export {};