@trackunit/react-map 0.0.9 → 0.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {

package/src/appearance/useMapAppearanceControls.d.ts

@@ -19,11 +19,11 @@ import { type UseMapAppearanceControlsParams } from "./appearanceTypes";
  * const controlsConfig: ControlsConfig = {
  *   navigation: { controls: navigationControls },
  *   settings: { controls: appearanceControls },
- *   tools: null,
+ *   tools: { controls: [] },
  *   statistics: { controls: [] },
  * };
  *
- * <Controls api={api} controlsConfig={controlsConfig} />
+ * <Controls api={api} controls={controlsConfig} />
  * ```
  */
 export declare const useMapAppearanceControls: ({ api, options: appearanceOptions, persistenceKey, }: UseMapAppearanceControlsParams) => ReadonlyArray<MenuControlConfig>;

package/src/controls/Controls.d.ts

@@ -3,13 +3,10 @@ import type { ControlsConfig } from "./types";
 type ControlsProps = Readonly<{
     /** The map API object from useMap */
     api: MapApi;
+    /** Controls configuration built from useDefaultControls, useControls, or composeControlAreas */
+    controls: ControlsConfig;
     /** Additional CSS classes for the controls container */
     className?: string;
-    /**
-     * Custom controls configuration to override the default.
-     * If provided, this will be used instead of building from api.options.
-     */
-    controlsConfig?: ControlsConfig;
 }>;
-export declare const Controls: import("react").MemoExoticComponent<({ api, className, controlsConfig: controlsConfigProp }: ControlsProps) => import("react/jsx-runtime").JSX.Element>;
+export declare const Controls: import("react").MemoExoticComponent<({ api, controls, className }: ControlsProps) => import("react/jsx-runtime").JSX.Element>;
 export {};

package/src/controls/DefaultControls.d.ts

@@ -0,0 +1,37 @@
+import type { MapApi } from "../core/types";
+import { type UseDefaultControlsOptions } from "./useDefaultControls";
+type DefaultControlsProps = Readonly<{
+    /** The map API object from useMap */
+    api: MapApi;
+    /** Optional configuration to disable individual built-in controls */
+    options?: UseDefaultControlsOptions;
+    /** Additional CSS classes for the controls container */
+    className?: string;
+}>;
+/**
+ * Convenience wrapper that calls `useDefaultControls` and passes the result
+ * directly to `<Controls>`.
+ *
+ * Use this for the common case where only the built-in controls (zoom,
+ * fullscreen, my location, map style) are needed, with no custom additions.
+ * For custom control stacks, call `useDefaultControls` + `useControls` (or
+ * `composeControlAreas`) and pass the result to `<Controls>` directly.
+ *
+ * @example
+ * ```tsx
+ * import { useMap, DefaultControls } from "@trackunit/react-map";
+ * import { googleMapsAdapter } from "@trackunit/react-map-adapter-google";
+ *
+ * const MyMap = () => {
+ *   const [Map, api] = useMap(googleMapsAdapter({ apiKey }));
+ *
+ *   return (
+ *     <Map>
+ *       <DefaultControls api={api} />
+ *     </Map>
+ *   );
+ * };
+ * ```
+ */
+export declare const DefaultControls: ({ api, options, className }: DefaultControlsProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/src/controls/composeControlAreas.d.ts

@@ -0,0 +1,24 @@
+import { type ControlStackItem } from "./defineControlStack";
+import type { CategoryKey, ControlsConfig } from "./types";
+/**
+ * Input for `composeControlAreas`: a partial record of per-area control stacks.
+ * Omitted areas default to an empty controls array.
+ * `undefined` entries in each area array are filtered out by `defineControlStack`.
+ */
+export type ControlAreasInput = Partial<Record<CategoryKey, ReadonlyArray<ControlStackItem>>>;
+/**
+ * Pure function that builds a `ControlsConfig` from per-area control stacks.
+ *
+ * Each area in `areas` is passed through `defineControlStack` (which filters
+ * `undefined` entries and rejects duplicate ids). Omitted areas default to
+ * `{ controls: [] }`.
+ *
+ * @example
+ * ```ts
+ * const controls = composeControlAreas({
+ *   navigation: [builtIn.navigation.zoom, builtIn.navigation.fullscreen],
+ *   settings: [builtIn.settings.mapStyle],
+ * });
+ * ```
+ */
+export declare const composeControlAreas: (areas: ControlAreasInput) => ControlsConfig;

package/src/controls/types.d.ts

@@ -315,6 +315,10 @@ export type SettingsConfig = Readonly<{
 export type StatisticsConfig = Readonly<{
     controls: ReadonlyArray<ControlConfig>;
 }>;
+/** Tools area - array of controls */
+export type ToolsConfig = Readonly<{
+    controls: ReadonlyArray<ControlConfig>;
+}>;
 /** Complete controls configuration */
 export type ControlsConfig = Readonly<{
     /** Navigation controls: zoom, fullscreen, compass (future), reset view (future) */
@@ -322,12 +326,12 @@ export type ControlsConfig = Readonly<{
     /** Settings: layer toggles, layer settings (future), map style (future) */
     settings: SettingsConfig;
     /** Tools: drawing, measurement, selection (future) */
-    tools: null;
+    tools: ToolsConfig;
     /** Statistics: data summaries, counts */
     statistics: StatisticsConfig;
 }>;
 /**
- * Built-in navigation controls returned by `useControlsConfig`.
+ * Built-in navigation controls returned by `useDefaultControls`.
  *
  * Consumers composing custom control stacks can use these named handles instead
  * of re-identifying built-ins by their string ids after the controls are built.
@@ -337,11 +341,11 @@ export interface BuiltInNavigationConfig extends NavigationConfig {
     readonly fullscreen: ToggleControlConfig | undefined;
     readonly myLocation: ButtonControlConfig | undefined;
 }
-/** Built-in settings controls returned by `useControlsConfig`. */
+/** Built-in settings controls returned by `useDefaultControls`. */
 export interface BuiltInSettingsConfig extends SettingsConfig {
     readonly mapStyle: MenuControlConfig | undefined;
 }
-/** Controls config with named handles for the controls built by `useControlsConfig`. */
+/** Controls config with named handles for the controls built by `useDefaultControls`. */
 export interface BuiltInControlsConfig extends ControlsConfig {
     readonly navigation: BuiltInNavigationConfig;
     readonly settings: BuiltInSettingsConfig;
@@ -370,26 +374,14 @@ export type ResponsiveMode = "full" | "categorized" | "collapsed";
 /** The four semantic control areas used for categorization and section headers */
 export type CategoryKey = "navigation" | "settings" | "tools" | "statistics";
 /**
- * Options for configuring controls when calling useMap
- */
-export type ControlsOptions = Readonly<{
-    zoom?: Readonly<{
-        enabled?: boolean;
-    }>;
-    fullscreen?: Readonly<{
-        enabled?: boolean;
-    }>;
-    mapStyle?: Readonly<{
-        enabled?: boolean;
-    }>;
-    myLocation?: Readonly<{
-        enabled?: boolean;
-    }>;
-}>;
-/**
- * Options passed to useMap for configuring map behavior
+ * Per-area prepend/append modifiers for `useControls`.
+ *
+ * Each area key accepts an optional `prepend` and/or `append` array of
+ * `ControlConfig | undefined` items (undefined entries are filtered out by
+ * `defineControlStack`). Omitted areas are left untouched.
  */
-export type UseMapOptions = Readonly<{
-    controls?: ControlsOptions;
-}>;
+export type UseControlsAreas = Partial<Record<CategoryKey, Readonly<{
+    prepend?: ReadonlyArray<ControlConfig | undefined>;
+    append?: ReadonlyArray<ControlConfig | undefined>;
+}>>>;
 export {};

package/src/controls/useControlStack.d.ts

@@ -1,21 +1,23 @@
-import { collapseControls } from "./collapseControls";
+import { composeControlAreas } from "./composeControlAreas";
 import { defineControlStack } from "./defineControlStack";
 export type ControlStackHelpers = Readonly<{
     defineControlStack: typeof defineControlStack;
-    collapseControls: typeof collapseControls;
+    composeControlAreas: typeof composeControlAreas;
 }>;
 /**
- * Build-your-own hook: stable references to control composition/layout helpers.
+ * Build-your-own hook: stable references to control composition helpers.
  *
- * Returns `defineControlStack` and `collapseControls` for consumers building
- * custom control layouts without duplicating the stack-ordering and responsive-
- * collapse logic already used by `Controls`.
+ * Returns `defineControlStack` and `composeControlAreas` for consumers building
+ * custom control layouts without duplicating the stack-ordering logic already
+ * used by `Controls`.
  *
  * @example
  * ```tsx
- * const { defineControlStack, collapseControls } = useControlStack();
- * const controls = defineControlStack([myControl, undefined, otherControl]);
- * const collapsed = collapseControls(config, responsiveMode, metadata);
+ * const { defineControlStack, composeControlAreas } = useControlStack();
+ * const controls = composeControlAreas({
+ *   navigation: [builtIn.navigation.zoom, builtIn.navigation.fullscreen],
+ *   settings: [builtIn.settings.mapStyle],
+ * });
  * ```
  */
 export declare const useControlStack: () => ControlStackHelpers;

package/src/controls/useControls.d.ts

@@ -0,0 +1,20 @@
+import type { ControlsConfig, UseControlsAreas } from "./types";
+/**
+ * Merges per-area `prepend`/`append` modifier lists into a base `ControlsConfig`.
+ *
+ * Memoizes internally — stable references are returned when neither `base` nor
+ * `areas` has changed. Modifiers are applied via `defineControlStack`, which
+ * filters `undefined` entries and rejects duplicate control ids.
+ *
+ * When `areas` is omitted the `base` reference is returned as-is.
+ *
+ * @example
+ * ```ts
+ * const builtIn = useDefaultControls(api);
+ * const controls = useControls(builtIn, {
+ *   navigation: { append: [layerNavControl] },
+ *   settings: { prepend: [layerSettingsControl] },
+ * });
+ * ```
+ */
+export declare const useControls: (base: ControlsConfig, areas?: UseControlsAreas) => ControlsConfig;

package/src/controls/useDefaultControls.d.ts

@@ -0,0 +1,62 @@
+import type { AdapterConfig } from "@trackunit/react-map-adapter-shared";
+import type { ContainerRefHolder, MapActions, MapStatus } from "../core/types";
+import type { BuiltInControlsConfig } from "./types";
+/**
+ * Options for `useDefaultControls`.
+ * Each control can be individually disabled. Omitting the options object (or any
+ * sub-key) means all controls are enabled.
+ */
+export type UseDefaultControlsOptions = Readonly<{
+    navigation?: Readonly<{
+        zoom?: Readonly<{
+            enabled?: boolean;
+        }>;
+        fullscreen?: Readonly<{
+            enabled?: boolean;
+        }>;
+        myLocation?: Readonly<{
+            enabled?: boolean;
+        }>;
+    }>;
+    settings?: Readonly<{
+        mapStyle?: Readonly<{
+            enabled?: boolean;
+        }>;
+    }>;
+}>;
+/**
+ * Minimal slice of `MapApi` consumed by `useDefaultControls`.
+ * Using a structural sub-type avoids a direct dependency on the full MapApi.
+ */
+type DefaultControlsApi = Readonly<{
+    state: MapStatus;
+    actions: MapActions;
+    adapterConfig: AdapterConfig;
+    containerRef: ContainerRefHolder;
+}>;
+/**
+ * Builds the default built-in controls configuration (zoom, fullscreen, my
+ * location, map style) from the map API.
+ *
+ * Replaces `useControlsConfig` with a cleaner, flat options structure. Each
+ * control can be disabled individually via `options`. Omitting `options`
+ * enables all controls.
+ *
+ * Returns a `BuiltInControlsConfig` — a `ControlsConfig` enriched with named
+ * handles for each built-in control so consumers can reference them without
+ * searching by id.
+ *
+ * @example
+ * ```tsx
+ * const builtIn = useDefaultControls(api);
+ * return <Controls controls={builtIn} api={api} />;
+ * ```
+ * @example Disable specific controls
+ * ```tsx
+ * const builtIn = useDefaultControls(api, {
+ *   navigation: { myLocation: { enabled: false } },
+ * });
+ * ```
+ */
+export declare const useDefaultControls: (api: DefaultControlsApi, options?: UseDefaultControlsOptions) => BuiltInControlsConfig;
+export {};

package/src/core/types.d.ts

@@ -3,7 +3,6 @@ export type { CameraState, ContainerRefHolder, FitBoundsOptions, GeoJsonBbox, Ge
 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";
 /**
@@ -131,11 +130,6 @@ export type MapApi = Readonly<{
      * ```
      */
     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
@@ -174,14 +168,6 @@ export type MapApi = Readonly<{
      * 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.

package/src/core/useMap.d.ts

@@ -1,5 +1,4 @@
 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
@@ -15,7 +14,6 @@ import { type UseMapReturn } from "./types";
  * 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
@@ -54,4 +52,4 @@ import { type UseMapReturn } from "./types";
  * };
  * ```
  */
-export declare const useMap: <TConfig extends Record<string, unknown>>(adapterConfig: AdapterConfig<TConfig>, options?: UseMapOptions) => UseMapReturn;
+export declare const useMap: <TConfig extends Record<string, unknown>>(adapterConfig: AdapterConfig<TConfig>) => UseMapReturn;

package/src/index.d.ts

@@ -1,6 +1,6 @@
 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 type { AvailableSpace, BooleanControlConfig, BuiltInControlsConfig, BuiltInNavigationConfig, BuiltInSettingsConfig, ButtonControlConfig, CategoryKey, CheckboxControlConfig, Compactness, ControlConfig, ControlsConfig, CustomControlConfig, CustomControlRenderContext, IconName, MenuControlConfig, MenuItemConfig, NavigationConfig, OverflowBehavior, Placement, RadioGroupControlConfig, RenderContext, ResolvedControlProps, ResolvedControlPropsBase, ResponsiveMode, SearchControlConfig, SelectControlConfig, SeparatorItemConfig, SettingsConfig, StatisticsConfig, StepperControlConfig, ToggleControlConfig, ToggleGroupControlConfig, ToggleGroupOption, ToolsConfig, } 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";
@@ -9,9 +9,13 @@ 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 type { ControlAreasInput } from "./controls/composeControlAreas";
 export { Controls } from "./controls/Controls";
+export { DefaultControls } from "./controls/DefaultControls";
 export type { ControlStackItem } from "./controls/defineControlStack";
-export { useControlsConfig } from "./controls/useControlsConfig";
+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 { useMapAppearanceControls } from "./appearance/useMapAppearanceControls";
 export type { ControlMiddleware, MiddlewareContext } from "./controls/renderingRules";
@@ -23,16 +27,16 @@ 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 { 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_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 { 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";
@@ -40,7 +44,7 @@ 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 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";
@@ -52,18 +56,18 @@ export { useMarkers, type UseMarkersOptions, type UseMarkersReturn } from "./lay
 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 { 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 { useFitFeatureBounds, type FitFeatureBoundsHelpers } from "./layers/internal/useFitFeatureBounds";
+export { useAdaptiveMarkerHelpers, type AdaptiveMarkerHelpers } from "./layers/useMarkers/useAdaptiveMarkerHelpers";
 export { useShapeLabelHelpers, type ShapeLabelHelpers } from "./layers/useShapes/useShapeLabelHelpers";
+export { useMarkerStateResolvers, type MarkerStateResolvers } from "./markers/model/useMarkerStateResolvers";
+export { useMarkerColors, type MarkerColorHelpers } from "./markers/shared/useMarkerColors";
+export { useAutoPanResolver, type AutoPanResolverHelpers } from "./panel/utils/useAutoPanResolver";
 export { mockMapApi } from "./testing/mockMapApi";

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

@@ -1,5 +1,5 @@
 import { type GeoJsonBbox } from "@trackunit/geo-json-utils";
-import type { ControlConfig } from "../../controls/types";
+import type { CategoryKey, ControlConfig } from "../../controls/types";
 import type { FitParticipation, ImageOverlayHandle } from "../types";
 export type UseImageOverlayOptions = Readonly<{
     /** Unique ID for this layer */
@@ -12,8 +12,11 @@ export type UseImageOverlayOptions = Readonly<{
     imageBounds: GeoJsonBbox;
     /** Opacity from 0 to 1. Default: 1 */
     opacity?: number;
-    /** Optional controls to contribute to the map UI */
-    controls?: ReadonlyArray<ControlConfig>;
+    /**
+     * Controls to contribute to the map UI, keyed by semantic area.
+     * Omit entirely (or omit a key) to contribute nothing to that area.
+     */
+    controls?: Partial<Record<CategoryKey, 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"` */

package/src/layers/routes/useRoute.d.ts

@@ -1,5 +1,5 @@
 import { type GeoJsonPosition } from "@trackunit/geo-json-utils";
-import type { ControlConfig } from "../../controls/types";
+import type { CategoryKey, ControlConfig } from "../../controls/types";
 import type { FitParticipation, RouteLayerHandle, RouteStyle } from "../types";
 export type UseRouteOptions = Readonly<{
     /** Unique ID for this layer */
@@ -12,8 +12,11 @@ export type UseRouteOptions = Readonly<{
     style: RouteStyle;
     /** Whether the route is interactive (clickable/hoverable). Default: true */
     interactive?: boolean;
-    /** Optional controls to contribute to the map UI */
-    controls?: ReadonlyArray<ControlConfig>;
+    /**
+     * Controls to contribute to the map UI, keyed by semantic area.
+     * Omit entirely (or omit a key) to contribute nothing to that area.
+     */
+    controls?: Partial<Record<CategoryKey, 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"` */

package/src/layers/types.d.ts

@@ -1,6 +1,6 @@
 import type { GeoJsonBbox, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonPosition } from "@trackunit/geo-json-utils";
 import type { AdaptiveMarkerResolution, ClusterConfig, ClusterRenderConfig, RenderConfig, RouteStyle, ShapeInteractiveMode, ShapeStyle } from "@trackunit/react-map-adapter-shared";
-import type { ControlConfig } from "../controls/types";
+import type { CategoryKey, ControlConfig } from "../controls/types";
 import type { ShapeDecoration } from "./useShapes/shapeDecorations";
 import type { ShapeLabelResolutionContext } from "./useShapes/shapeLabelResolution";
 export type { AdaptiveMarkerResolution, AdaptiveRenderConfig, AdaptiveRenderState, AdaptiveResolutionContext, CircleSymbolDescriptor, ClientClusterConfig, ClusterConfig, ClusterDomRenderConfig, ClusterInfo, ClusterRenderConfig, ClusterRenderState, ClusterSymbolRenderConfig, ClusterSymbolStyle, CommonRenderState, DomPortalStackingInput, DomPortalStackingResolver, DomPortalStackingResult, DomRenderConfig, DomRenderState, GeoJsonFeature, GeoJsonFeatureCollection, GeoJsonGeometry, MarkerAnchor, MarkerDomPortalStackGeometry, MarkerDomPortalStackPhase, PixelOffset, RenderConfig, RenderMedium, ResolutionContext, RouteStyle, ServerClusterConfig, ShapeInteractiveMode, ShapeStyle, ShapeStyleOverrides, SymbolDescriptor, SymbolRenderConfig, SymbolRenderState, } from "@trackunit/react-map-adapter-shared";
@@ -35,8 +35,12 @@ export type LayerMeta = Readonly<{
     getBounds: () => GeoJsonBbox | null;
     /** Summary counts -- always cheap (derived from .length). Semantics depend on layer type. */
     counts: Readonly<Record<string, number>>;
-    /** Controls this layer wants to contribute to the map UI */
-    controls: ReadonlyArray<ControlConfig>;
+    /**
+     * Controls this layer wants to contribute to the map UI, keyed by semantic area.
+     * Each key maps to an array of controls for that area (navigation, settings, tools, statistics).
+     * Omit a key (or provide an empty array) to contribute nothing to that area.
+     */
+    controls: Readonly<Partial<Record<CategoryKey, ReadonlyArray<ControlConfig>>>>;
     /**
      * Controls whether this layer's bounds are included in fit-to-content operations.
      * Default: `"all"`.

package/src/layers/useLayers.d.ts

@@ -1,6 +1,6 @@
 import type { GeoJsonBbox } from "@trackunit/geo-json-utils";
 import { type Entity, type MapInteractionState } from "@trackunit/react-map-adapter-shared";
-import type { ControlConfig } from "../controls/types";
+import type { CategoryKey, ControlConfig } from "../controls/types";
 import type { MapApi } from "../core/types";
 import type { LayerHandle } from "./types";
 /**
@@ -24,8 +24,11 @@ export type UseLayersReturn = Readonly<{
     loading: boolean;
     /** Resolves when ALL layers have their initial data */
     ready: Promise<void>;
-    /** Aggregated controls from all layers */
-    controls: ReadonlyArray<ControlConfig>;
+    /**
+     * Aggregated controls from all layers, keyed by semantic area.
+     * All four CategoryKey areas are always present (empty arrays for areas with no controls).
+     */
+    controls: Readonly<Record<CategoryKey, ReadonlyArray<ControlConfig>>>;
     /** Layer handles (passed to Layers component for rendering) */
     handles: ReadonlyArray<LayerHandle>;
 }>;

package/src/layers/useMarkers/useMarkers.d.ts

@@ -1,5 +1,5 @@
 import { type GeoJsonPosition } from "@trackunit/geo-json-utils";
-import type { ControlConfig } from "../../controls/types";
+import type { CategoryKey, ControlConfig } from "../../controls/types";
 import type { ClusterConfig, ClusterInfo, ClusterRenderConfig, FitParticipation, MarkerLayerHandle, RenderConfig, ResolutionContext } from "../types";
 import { type ViewportResolutionContext } from "./resolveServerClusters";
 /**
@@ -38,8 +38,11 @@ export type UseMarkersOptions<TItem, TCluster = ClusterInfo> = Readonly<{
      * `data` (DOM mode only — symbol mode receives `memberItems: null`).
      */
     clusterRender?: ClusterRenderConfig<TCluster, TItem>;
-    /** Optional controls to contribute to the map UI */
-    controls?: ReadonlyArray<ControlConfig>;
+    /**
+     * Controls to contribute to the map UI, keyed by semantic area.
+     * Omit entirely (or omit a key) to contribute nothing to that area.
+     */
+    controls?: Partial<Record<CategoryKey, 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"` */

package/src/layers/useShapes/useShapes.d.ts

@@ -1,5 +1,5 @@
 import { type GeoJsonFeature, type GeoJsonFeatureCollection } from "@trackunit/geo-json-utils";
-import type { ControlConfig } from "../../controls/types";
+import type { CategoryKey, ControlConfig } from "../../controls/types";
 import type { FitParticipation, ShapeInteractiveMode, ShapeLayerHandle, ShapeStyle } from "../types";
 import type { ShapeDecoration } from "./shapeDecorations";
 import type { ShapeLabelResolutionContext } from "./shapeLabelResolution";
@@ -14,8 +14,11 @@ export type UseShapesOptions = Readonly<{
     resolveStyle: (feature: GeoJsonFeature, ctx?: ShapeLabelResolutionContext) => ShapeStyle;
     /** Which parts of the shape respond to interaction. Default: `"stroke"` */
     interactive?: ShapeInteractiveMode;
-    /** Optional controls to contribute to the map UI */
-    controls?: ReadonlyArray<ControlConfig>;
+    /**
+     * Controls to contribute to the map UI, keyed by semantic area.
+     * Omit entirely (or omit a key) to contribute nothing to that area.
+     */
+    controls?: Partial<Record<CategoryKey, ReadonlyArray<ControlConfig>>>;
     /**
      * Produce custom decorations for each feature. Called per-feature during the
      * decoration rendering pass. These are merged with auto-generated decorations

package/src/controls/useControlsConfig.d.ts

@@ -1,27 +0,0 @@
-import type { AdapterConfig } from "@trackunit/react-map-adapter-shared";
-import type { ContainerRefHolder, MapActions, MapStatus } from "../core/types";
-import type { BuiltInControlsConfig, UseMapOptions } from "./types";
-/**
- * Partial MapApi type used by useControlsConfig.
- * Includes only the fields this hook (and its sub-hooks) actually need,
- * avoiding a direct dependency on the full MapApi type.
- */
-type MapApiWithoutControls = Readonly<{
-    state: MapStatus;
-    actions: MapActions;
-    adapterConfig: AdapterConfig;
-    containerRef: ContainerRefHolder;
-}>;
-type UseControlsConfigParams = Readonly<{
-    options?: UseMapOptions;
-    api: MapApiWithoutControls;
-}>;
-/**
- * Builds the controls configuration from useMap options and api.
- *
- * Creates control config objects with bound callbacks for each enabled control.
- * The Controls component uses this configuration to render controls.
- * Consumers can compose custom stacks from the named built-in handles.
- */
-export declare const useControlsConfig: ({ options, api }: UseControlsConfigParams) => BuiltInControlsConfig;
-export {};