@trackunit/react-map 0.0.10 → 0.1.0

package/index.esm.js

@@ -1238,7 +1238,6 @@ function useMapAdapterState(adapterConfig) {
  * 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
@@ -1277,7 +1276,7 @@ function useMapAdapterState(adapterConfig) {
  * };
  * ```
  */
-const useMap = (adapterConfig, options) => {
+const useMap = (adapterConfig) => {
     const { adapter, renderConfig } = useMapAdapterState(adapterConfig);
     // Subscribe to status changes only (isReady, appearance, etc. — low frequency).
     // Camera state (center/zoom/bounds) is accessed via useCameraState(api) instead,
@@ -1354,7 +1353,6 @@ const useMap = (adapterConfig, options) => {
         actions,
         on,
         containerRef: containerRefHolder,
-        options,
         adapterConfig: renderConfig,
         annotations: annotationStore,
         loadingIndicator: loadingIndicatorStore,
@@ -1366,7 +1364,6 @@ const useMap = (adapterConfig, options) => {
         actions,
         on,
         containerRefHolder,
-        options,
         renderConfig,
         annotationStore,
         loadingIndicatorStore,
@@ -1606,7 +1603,12 @@ const collapseAll = (categories, allControls) => {
     }
     // Nothing to show
     if (allItems.length === 0) {
-        return { navigation: { controls: [] }, settings: { controls: [] }, tools: null, statistics: { controls: [] } };
+        return {
+            navigation: { controls: [] },
+            settings: { controls: [] },
+            tools: { controls: [] },
+            statistics: { controls: [] },
+        };
     }
     const singleMenu = {
         type: "menu",
@@ -1619,7 +1621,7 @@ const collapseAll = (categories, allControls) => {
     return {
         navigation: { controls: [singleMenu] },
         settings: { controls: [] },
-        tools: null,
+        tools: { controls: [] },
         statistics: { controls: [] },
     };
 };
@@ -1643,10 +1645,12 @@ const collapseControls = (config, mode, metadata) => {
     if (mode === "full")
         return config;
     // Categories that participate in collapse (statistics excluded — summary widgets stay visible).
+    // Tools fold into the single all-controls menu in "collapsed" mode; in "full"/"categorized"
+    // they render standalone in the top-right corner.
     const categories = [
         { key: "navigation", label: metadata.navigation.label, controls: config.navigation.controls },
         { key: "settings", label: metadata.settings.label, controls: config.settings.controls },
-        // tools are still null - to be implemented
+        { key: "tools", label: metadata.tools.label, controls: config.tools.controls },
     ];
     if (mode === "collapsed") {
         const collapsed = collapseAll(categories, metadata.allControls);
@@ -1659,7 +1663,10 @@ const collapseControls = (config, mode, metadata) => {
     const settings = {
         controls: collapseCategory(config.settings.controls, "settings", metadata.settings),
     };
-    return { navigation, settings, tools: null, statistics: config.statistics };
+    const tools = {
+        controls: collapseCategory(config.tools.controls, "tools", metadata.tools),
+    };
+    return { navigation, settings, tools, statistics: config.statistics };
 };
 
 /**
@@ -2412,6 +2419,109 @@ const GLOBE_CENTERS = [
 /** Pick the globe icon whose projection center is closest to the given longitude. */
 const longitudeToGlobeIcon = (longitude) => GLOBE_CENTERS.reduce((closest, current) => Math.abs(current.center - longitude) < Math.abs(closest.center - longitude) ? current : closest).icon;
 
+/**
+ * Internal component that renders controls.
+ * Separated to allow Suspense boundary in parent.
+ */
+const ControlsContent = ({ api, controls: baseControlsConfig, className }) => {
+    const [t] = useTranslation();
+    // Measure container to derive available space and responsive mode
+    const containerRef = useRef(null);
+    const { ref: measureRef, geometry } = useMeasure();
+    const mergedRef = useMergeRefs([containerRef, measureRef]);
+    const { displayAnnotations, isExiting, shouldRender: shouldRenderAnnotations, } = useAnnotationPresence(api.annotations);
+    const skipContainerBreakpoints = baseControlsConfig.navigation.controls.length === 0 &&
+        baseControlsConfig.settings.controls.length === 0 &&
+        baseControlsConfig.tools.controls.length === 0 &&
+        baseControlsConfig.statistics.controls.length === 0 &&
+        !shouldRenderAnnotations;
+    const breakpoints = useContainerBreakpoints(containerRef, { skip: skipContainerBreakpoints });
+    const containerHeight = geometry?.height ?? Infinity;
+    const safeAreaLayout = useContext(SafeAreaLayoutContext);
+    const measuredAvailableSpace = breakpoints.isSm && containerHeight >= HEIGHT_COMFORTABLE_THRESHOLD ? "comfortable" : "constrained";
+    const measuredResponsiveMode = deriveResponsiveMode(breakpoints.isSm, breakpoints.isMd, containerHeight);
+    const availableSpace = safeAreaLayout?.availableSpace ?? measuredAvailableSpace;
+    const responsiveMode = safeAreaLayout?.responsiveMode ?? measuredResponsiveMode;
+    // Menus use modals only in collapsed mode (narrowest containers); popovers otherwise
+    const menuPresentation = responsiveMode === "collapsed" ? "modal" : "popover";
+    // Derive portal ID from the map container's stable ID (set by createMapComponent)
+    const portalId = api.containerRef.current?.id;
+    // Geolocation position for region-appropriate globe icon (updated if the user clicks "My Location")
+    const { position } = useGeolocation();
+    const navigationIcon = position !== null ? longitudeToGlobeIcon(position[0]) : "GlobeEuropeAfrica";
+    // Category metadata: icon + translated label for menu triggers, tooltips, and section headers
+    const categoryMetadata = useMemo(() => ({
+        navigation: { icon: navigationIcon, label: t("controls.category.navigation") },
+        settings: { icon: "Cog6Tooth", label: t("controls.category.settings") },
+        tools: { icon: "Wrench", label: t("controls.category.tools") },
+        statistics: { icon: "ChartBarSquare", label: t("controls.category.statistics") },
+        allControls: { icon: "EllipsisHorizontal", label: t("controls.allControls") },
+    }), [t, navigationIcon]);
+    // Apply responsive collapsing -- restructures config based on available space
+    const controlsConfig = useMemo(() => collapseControls(baseControlsConfig, responsiveMode, categoryMetadata), [baseControlsConfig, responsiveMode, categoryMetadata]);
+    useLayoutEffect(() => api.annotations.claimRenderer(), [api.annotations]);
+    const { navigation, settings, tools, statistics } = controlsConfig;
+    const hasNavigationControls = navigation.controls.length > 0;
+    const hasSettingsControls = settings.controls.length > 0;
+    const hasToolsControls = tools.controls.length > 0;
+    const hasStatisticsControls = statistics.controls.length > 0;
+    const hasStatisticsAreaContent = shouldRenderAnnotations || hasStatisticsControls;
+    if (!hasNavigationControls && !hasSettingsControls && !hasToolsControls && !hasStatisticsAreaContent) {
+        return null;
+    }
+    return (jsxs("div", { className: twMerge(
+        // Overlay positioning within Map's ZStack grid
+        "col-start-1 row-start-1", 
+        // Pointer events only on children, not the overlay itself
+        "pointer-events-none", 
+        // Layout grid for semantic areas
+        "grid h-full w-full", 
+        // Responsive grid: navigation bottom-right, settings top-left, statistics bottom-left
+        "grid-cols-[1fr_auto] grid-rows-[auto_1fr_auto]", 
+        // Isolate creates a new stacking context to avoid z-index issues
+        "isolate", className), "data-testid": "map-controls", ref: mergedRef, children: [hasToolsControls ? (jsx("div", { className: "pointer-events-auto col-start-2 row-start-1 flex flex-col gap-1", "data-testid": "map-controls-tools", children: tools.controls.map(control => (jsx(ControlRenderer, { availableSpace: availableSpace, containerRef: containerRef, control: control, customPortalId: portalId, menuPresentation: menuPresentation }, control.id))) })) : null, hasNavigationControls ? (jsx("div", { className: "pointer-events-auto col-start-2 row-start-3 flex flex-col gap-1", children: navigation.controls.map(control => (jsx(ControlRenderer, { availableSpace: availableSpace, containerRef: containerRef, control: control, customPortalId: portalId, menuPresentation: menuPresentation }, control.id))) })) : null, hasSettingsControls ? (jsx("div", { className: "pointer-events-auto col-start-1 row-start-1 flex w-fit flex-col gap-1", "data-testid": "map-controls-settings", children: settings.controls.map(control => (jsx(ControlRenderer, { availableSpace: availableSpace, containerRef: containerRef, control: control, customPortalId: portalId, menuPresentation: menuPresentation }, control.id))) })) : null, hasStatisticsAreaContent ? (jsxs("div", { className: twMerge("pointer-events-none col-start-1 row-start-3 flex max-h-full max-w-[20rem] flex-col items-start justify-end gap-1 overflow-visible", !hasStatisticsControls && "self-end"), "data-testid": "map-controls-statistics", children: [shouldRenderAnnotations ? (jsx("div", { className: "pointer-events-auto", "data-testid": "map-controls-statistics-annotations", children: jsx(AnnotationStack, { annotations: displayAnnotations, isExiting: isExiting }) })) : null, hasStatisticsControls ? (jsx("div", { className: "pointer-events-auto flex max-h-full w-fit max-w-full flex-col gap-1 overflow-auto", "data-testid": "map-controls-statistics-controls", children: statistics.controls.map(control => (jsx(ControlRenderer, { availableSpace: availableSpace, containerRef: containerRef, control: control, customPortalId: portalId, menuPresentation: menuPresentation }, control.id))) })) : null] })) : null] }));
+};
+/**
+ * Map controls renderer — lays out a `ControlsConfig` across the four semantic
+ * areas of the map (top-right tools, bottom-right navigation, top-left settings,
+ * bottom-left statistics + annotations).
+ *
+ * Build the `controls` prop with `useDefaultControls`, `useControls`, or
+ * `composeControlAreas`. For the common "default built-ins only" case prefer
+ * the `<DefaultControls>` wrapper which combines these two steps.
+ *
+ * Inherits layout decisions from the surrounding SafeAreaOverlay when rendered
+ * inside `<Map>`, and falls back to its own container measurement when
+ * rendered standalone.
+ *
+ * Uses Suspense internally to handle translation loading without blocking the map.
+ *
+ * @example
+ * ```tsx
+ * import { useMap, useDefaultControls, Controls } from "@trackunit/react-map";
+ * import { googleMapsAdapter } from "@trackunit/react-map-adapter-google";
+ *
+ * const MyMap = () => {
+ *   const [Map, api] = useMap(googleMapsAdapter({ apiKey }));
+ *   const controls = useDefaultControls(api);
+ *
+ *   return (
+ *     <Map>
+ *       <Controls api={api} controls={controls} />
+ *     </Map>
+ *   );
+ * };
+ * ```
+ */
+const ControlsInner = ({ api, controls, className }) => {
+    // Wrap in Suspense to handle useTranslation loading without blocking parent components
+    return (jsx(Suspense, { fallback: null, children: jsx(ControlsContent, { api: api, className: className, controls: controls }) }));
+};
+// `api` identity is stable between camera events since useMap only re-runs its useMemo
+// when MapStatus (isReady, appearance, etc.) changes — not on pan/zoom. Default React.memo
+// shallow equality is sufficient; no custom comparator needed.
+const Controls = memo(ControlsInner);
+
 const cvaMapPreview = cvaMerge([
     "relative",
     "h-[72px]",
@@ -2607,11 +2717,11 @@ const buildAppearanceOptions = (themes, mapTypes, t) => {
  * 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} />
  * ```
  */
 const useMapAppearanceControls = ({ api, options: appearanceOptions, persistenceKey = "map-appearance-settings", }) => {
@@ -2729,17 +2839,36 @@ const defineControlStack = (controls) => {
     return stack;
 };
 
+// ============================================================================
+// Hook
+// ============================================================================
 /**
- * Builds the controls configuration from useMap options and api.
+ * 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.
  *
- * 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.
+ * 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 } },
+ * });
+ * ```
  */
-const useControlsConfig = ({ options, api }) => {
+const useDefaultControls = (api, options) => {
     const [t] = useTranslation();
     const { getPosition } = useGeolocation();
-    // Fullscreen state and callbacks derived from the container ref
     const isFullscreen = useIsFullscreen();
     const requestFullscreen = useCallback(() => {
         void api.containerRef.current?.requestFullscreen();
@@ -2747,20 +2876,18 @@ const useControlsConfig = ({ options, api }) => {
     const exitFullscreen = useCallback(() => {
         void document.exitFullscreen();
     }, []);
-    const zoomControl = useMemo(() => options?.controls?.zoom?.enabled === false
+    const zoomControl = useMemo(() => options?.navigation?.zoom?.enabled === false
         ? undefined
         : {
-            // Zoom stepper control - uses relative zoom(delta)
             type: "stepper",
             id: "zoom",
             label: t("controls.zoom"),
             increment: () => void api.actions.zoomBy(1),
             decrement: () => void api.actions.zoomBy(-1),
-        }, [api.actions, options?.controls?.zoom?.enabled, t]);
-    const fullscreenControl = useMemo(() => options?.controls?.fullscreen?.enabled === false
+        }, [api.actions, options?.navigation?.zoom?.enabled, t]);
+    const fullscreenControl = useMemo(() => options?.navigation?.fullscreen?.enabled === false
         ? undefined
         : {
-            // Fullscreen toggle control
             type: "toggle",
             id: "fullscreen",
             icon: { on: "ArrowsPointingIn", off: "ArrowsPointingOut" },
@@ -2775,11 +2902,10 @@ const useControlsConfig = ({ options, api }) => {
                 }
             },
             "data-testid": "map-fullscreen-button",
-        }, [exitFullscreen, isFullscreen, options?.controls?.fullscreen?.enabled, requestFullscreen, t]);
-    const myLocationControl = useMemo(() => options?.controls?.myLocation?.enabled === false
+        }, [exitFullscreen, isFullscreen, options?.navigation?.fullscreen?.enabled, requestFullscreen, t]);
+    const myLocationControl = useMemo(() => options?.navigation?.myLocation?.enabled === false
         ? undefined
         : {
-            // My location button - zooms the map to a ~2x2 km box around the user's position
             type: "button",
             id: "my-location",
             icon: "Gps",
@@ -2789,7 +2915,6 @@ const useControlsConfig = ({ options, api }) => {
                     if (pos === null)
                         return;
                     const [longitude, latitude] = pos;
-                    // ~1 km in degrees: lat is constant, lon varies by cos(lat)
                     const latOffset = 1 / 111;
                     const lonOffset = 1 / (111 * Math.cos((latitude * Math.PI) / 180));
                     void api.actions.fitBounds([
@@ -2801,11 +2926,10 @@ const useControlsConfig = ({ options, api }) => {
                 });
             },
             "data-testid": "map-my-location-button",
-        }, [api.actions, getPosition, options?.controls?.myLocation?.enabled, t]);
+        }, [api.actions, getPosition, options?.navigation?.myLocation?.enabled, t]);
     const navigationControls = useMemo(() => defineControlStack([zoomControl, fullscreenControl, myLocationControl]), [fullscreenControl, myLocationControl, zoomControl]);
-    // Map appearance controls (settings area) - live mini-map previews for switching theme/style
     const mapAppearanceControls = useMapAppearanceControls({ api });
-    const mapStyleControl = useMemo(() => options?.controls?.mapStyle?.enabled === false ? undefined : mapAppearanceControls[0], [mapAppearanceControls, options?.controls?.mapStyle?.enabled]);
+    const mapStyleControl = useMemo(() => options?.settings?.mapStyle?.enabled === false ? undefined : mapAppearanceControls[0], [mapAppearanceControls, options?.settings?.mapStyle?.enabled]);
     const settingsControls = useMemo(() => defineControlStack([mapStyleControl]), [mapStyleControl]);
     return useMemo(() => ({
         navigation: {
@@ -2818,107 +2942,112 @@ const useControlsConfig = ({ options, api }) => {
             controls: settingsControls,
             mapStyle: mapStyleControl,
         },
-        tools: null,
+        tools: { controls: [] },
         statistics: { controls: [] },
     }), [fullscreenControl, mapStyleControl, myLocationControl, navigationControls, settingsControls, zoomControl]);
 };
 
 /**
- * Internal component that builds and renders controls.
- * Separated to allow Suspense boundary in parent.
- */
-const ControlsContent = ({ api, className, controlsConfigProp }) => {
-    const [t] = useTranslation();
-    // Measure container to derive available space and responsive mode
-    const containerRef = useRef(null);
-    const { ref: measureRef, geometry } = useMeasure();
-    const mergedRef = useMergeRefs([containerRef, measureRef]);
-    const builtControlsConfig = useControlsConfig({ options: api.options, api });
-    const baseControlsConfig = controlsConfigProp ?? builtControlsConfig;
-    const { displayAnnotations, isExiting, shouldRender: shouldRenderAnnotations, } = useAnnotationPresence(api.annotations);
-    const skipContainerBreakpoints = baseControlsConfig.navigation.controls.length === 0 &&
-        baseControlsConfig.settings.controls.length === 0 &&
-        baseControlsConfig.statistics.controls.length === 0 &&
-        !shouldRenderAnnotations;
-    const breakpoints = useContainerBreakpoints(containerRef, { skip: skipContainerBreakpoints });
-    const containerHeight = geometry?.height ?? Infinity;
-    const safeAreaLayout = useContext(SafeAreaLayoutContext);
-    const measuredAvailableSpace = breakpoints.isSm && containerHeight >= HEIGHT_COMFORTABLE_THRESHOLD ? "comfortable" : "constrained";
-    const measuredResponsiveMode = deriveResponsiveMode(breakpoints.isSm, breakpoints.isMd, containerHeight);
-    const availableSpace = safeAreaLayout?.availableSpace ?? measuredAvailableSpace;
-    const responsiveMode = safeAreaLayout?.responsiveMode ?? measuredResponsiveMode;
-    // Menus use modals only in collapsed mode (narrowest containers); popovers otherwise
-    const menuPresentation = responsiveMode === "collapsed" ? "modal" : "popover";
-    // Derive portal ID from the map container's stable ID (set by createMapComponent)
-    const portalId = api.containerRef.current?.id;
-    // Geolocation position for region-appropriate globe icon (updated if the user clicks "My Location")
-    const { position } = useGeolocation();
-    const navigationIcon = position !== null ? longitudeToGlobeIcon(position[0]) : "GlobeEuropeAfrica";
-    // Category metadata: icon + translated label for menu triggers, tooltips, and section headers
-    const categoryMetadata = useMemo(() => ({
-        navigation: { icon: navigationIcon, label: t("controls.category.navigation") },
-        settings: { icon: "Cog6Tooth", label: t("controls.category.settings") },
-        tools: { icon: "Wrench", label: t("controls.category.tools") },
-        statistics: { icon: "ChartBarSquare", label: t("controls.category.statistics") },
-        allControls: { icon: "EllipsisHorizontal", label: t("controls.allControls") },
-    }), [t, navigationIcon]);
-    // Apply responsive collapsing -- restructures config based on available space
-    const controlsConfig = useMemo(() => collapseControls(baseControlsConfig, responsiveMode, categoryMetadata), [baseControlsConfig, responsiveMode, categoryMetadata]);
-    useLayoutEffect(() => api.annotations.claimRenderer(), [api.annotations]);
-    const { navigation, settings, statistics } = controlsConfig;
-    const hasNavigationControls = navigation.controls.length > 0;
-    const hasSettingsControls = settings.controls.length > 0;
-    const hasStatisticsControls = statistics.controls.length > 0;
-    const hasStatisticsAreaContent = shouldRenderAnnotations || hasStatisticsControls;
-    if (!hasNavigationControls && !hasSettingsControls && !hasStatisticsAreaContent) {
-        return null;
-    }
-    return (jsxs("div", { className: twMerge(
-        // Overlay positioning within Map's ZStack grid
-        "col-start-1 row-start-1", 
-        // Pointer events only on children, not the overlay itself
-        "pointer-events-none", 
-        // Layout grid for semantic areas
-        "grid h-full w-full", 
-        // Responsive grid: navigation bottom-right, settings top-left, statistics bottom-left
-        "grid-cols-[1fr_auto] grid-rows-[auto_1fr_auto]", 
-        // Isolate creates a new stacking context to avoid z-index issues
-        "isolate", className), "data-testid": "map-controls", ref: mergedRef, children: [hasNavigationControls ? (jsx("div", { className: "pointer-events-auto col-start-2 row-start-3 flex flex-col gap-1", children: navigation.controls.map(control => (jsx(ControlRenderer, { availableSpace: availableSpace, containerRef: containerRef, control: control, customPortalId: portalId, menuPresentation: menuPresentation }, control.id))) })) : null, hasSettingsControls ? (jsx("div", { className: "pointer-events-auto col-start-1 row-start-1 flex w-fit flex-col gap-1", "data-testid": "map-controls-settings", children: settings.controls.map(control => (jsx(ControlRenderer, { availableSpace: availableSpace, containerRef: containerRef, control: control, customPortalId: portalId, menuPresentation: menuPresentation }, control.id))) })) : null, hasStatisticsAreaContent ? (jsxs("div", { className: twMerge("pointer-events-none col-start-1 row-start-3 flex max-h-full max-w-[20rem] flex-col items-start justify-end gap-1 overflow-visible", !hasStatisticsControls && "self-end"), "data-testid": "map-controls-statistics", children: [shouldRenderAnnotations ? (jsx("div", { className: "pointer-events-auto", "data-testid": "map-controls-statistics-annotations", children: jsx(AnnotationStack, { annotations: displayAnnotations, isExiting: isExiting }) })) : null, hasStatisticsControls ? (jsx("div", { className: "pointer-events-auto flex max-h-full w-fit max-w-full flex-col gap-1 overflow-auto", "data-testid": "map-controls-statistics-controls", children: statistics.controls.map(control => (jsx(ControlRenderer, { availableSpace: availableSpace, containerRef: containerRef, control: control, customPortalId: portalId, menuPresentation: menuPresentation }, control.id))) })) : null] })) : null] }));
-};
-/**
- * Map controls component that renders navigation and settings controls.
- *
- * Builds controls configuration internally using useControlsConfig hook.
- * Uses semantic areas (navigation, settings, tools, statistics) for organization.
- * All layout decisions are owned by this component for responsive positioning.
- *
- * Inherits layout decisions from the surrounding SafeAreaOverlay when rendered
- * inside <Map>, and falls back to its own measurement when rendered standalone.
+ * Convenience wrapper that calls `useDefaultControls` and passes the result
+ * directly to `<Controls>`.
  *
- * Uses Suspense internally to handle translation loading without blocking the map.
+ * 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, Controls } from "@trackunit/react-map";
+ * import { useMap, DefaultControls } from "@trackunit/react-map";
  * import { googleMapsAdapter } from "@trackunit/react-map-adapter-google";
  *
- * const [Map, api] = useMap(googleMapsAdapter({ apiKey }));
+ * const MyMap = () => {
+ *   const [Map, api] = useMap(googleMapsAdapter({ apiKey }));
  *
- * return (
- *   <Map>
- *     <Controls api={api} />
- *   </Map>
- * );
+ *   return (
+ *     <Map>
+ *       <DefaultControls api={api} />
+ *     </Map>
+ *   );
+ * };
  * ```
  */
-const ControlsInner = ({ api, className, controlsConfig: controlsConfigProp }) => {
-    // Wrap in Suspense to handle useTranslation loading without blocking parent components
-    return (jsx(Suspense, { fallback: null, children: jsx(ControlsContent, { api: api, className: className, controlsConfigProp: controlsConfigProp }) }));
+const DefaultControls = ({ api, options, className }) => {
+    const controls = useDefaultControls(api, options);
+    return jsx(Controls, { api: api, className: className, controls: controls });
+};
+
+// ============================================================================
+// Internal helpers
+// ============================================================================
+/**
+ * Applies prepend/append modifiers to a single area section.
+ * Returns the original section reference unchanged when no modifiers are given.
+ */
+const applyAreaModifiers = (section, area) => {
+    const { prepend, append } = area;
+    const hasPrepend = prepend !== undefined && prepend.length > 0;
+    const hasAppend = append !== undefined && append.length > 0;
+    if (!hasPrepend && !hasAppend)
+        return section;
+    return {
+        ...section,
+        controls: defineControlStack([...(prepend ?? []), ...section.controls, ...(append ?? [])]),
+    };
+};
+const CATEGORY_KEYS = ["navigation", "settings", "tools", "statistics"];
+// ============================================================================
+// Hook
+// ============================================================================
+/**
+ * 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] },
+ * });
+ * ```
+ */
+const useControls = (base, areas) => {
+    return useMemo(() => {
+        if (areas === undefined)
+            return base;
+        let hasChanges = false;
+        const updated = {
+            navigation: base.navigation,
+            settings: base.settings,
+            tools: base.tools,
+            statistics: base.statistics,
+        };
+        for (const key of CATEGORY_KEYS) {
+            const area = areas[key];
+            if (area === undefined)
+                continue;
+            const modified = applyAreaModifiers(base[key], area);
+            if (modified !== base[key]) {
+                updated[key] = modified;
+                hasChanges = true;
+            }
+        }
+        if (!hasChanges)
+            return base;
+        return {
+            navigation: updated.navigation,
+            settings: updated.settings,
+            tools: updated.tools,
+            statistics: updated.statistics,
+        };
+    }, [base, areas]);
 };
-// `api` identity is stable between camera events since useMap only re-runs its useMemo
-// when MapStatus (isReady, appearance, etc.) changes — not on pan/zoom. Default React.memo
-// shallow equality is sufficient; no custom comparator needed.
-const Controls = memo(ControlsInner);
 
 const MARKER_SPRING_CONFIG = {
     stiffness: 380,
@@ -4591,7 +4720,7 @@ const useLayerReady = (loading) => {
 // ============================================================================
 // Constants
 // ============================================================================
-const EMPTY_CONTROLS$4 = [];
+const EMPTY_CONTROLS$3 = {};
 // ============================================================================
 // Hook
 // ============================================================================
@@ -4631,7 +4760,7 @@ const useImageOverlay = (options) => {
         ready: layerReady.ready,
         getBounds,
         counts,
-        controls: controls ?? EMPTY_CONTROLS$4,
+        controls: controls ?? EMPTY_CONTROLS$3,
         fitParticipation,
         layerType: "image-overlay",
         url,
@@ -4912,7 +5041,7 @@ const createLazyGetter = (compute) => {
 // ============================================================================
 // Constants
 // ============================================================================
-const EMPTY_CONTROLS$3 = [];
+const EMPTY_CONTROLS$2 = {};
 const EMPTY_FEATURES$1 = { type: "FeatureCollection", features: [] };
 // ============================================================================
 // Internal helpers
@@ -5000,7 +5129,7 @@ const useRoute = (options) => {
         ready: layerReady.ready,
         getBounds,
         counts,
-        controls: controls ?? EMPTY_CONTROLS$3,
+        controls: controls ?? EMPTY_CONTROLS$2,
         fitParticipation,
         layerType: "route",
         features,
@@ -5190,7 +5319,12 @@ const interactionReducer = (state, action) => {
 // ============================================================================
 // Constants
 // ============================================================================
-const EMPTY_CONTROLS$2 = [];
+const EMPTY_AREA_CONTROLS = {
+    navigation: [],
+    settings: [],
+    tools: [],
+    statistics: [],
+};
 const RESOLVED_PROMISE = Promise.resolve();
 // ============================================================================
 // Hook
@@ -5256,17 +5390,28 @@ const useLayers = (api, layers) => {
         const promises = layers.map(layer => layer.ready);
         return Promise.all(promises).then(() => undefined);
     }, [layers]);
-    // ---- Controls (aggregated from all layers) ----
+    // ---- Controls (aggregated per area from all layers) ----
     const controls = useMemo(() => {
-        const allControls = [];
+        const areaKeys = ["navigation", "settings", "tools", "statistics"];
+        const areas = {
+            navigation: [],
+            settings: [],
+            tools: [],
+            statistics: [],
+        };
+        let hasAny = false;
         for (const layer of layers) {
-            if (layer.controls.length > 0) {
-                allControls.push(...layer.controls);
+            for (const key of areaKeys) {
+                const areaControls = layer.controls[key];
+                if (areaControls !== undefined && areaControls.length > 0) {
+                    areas[key].push(...areaControls);
+                    hasAny = true;
+                }
             }
         }
-        if (allControls.length === 0)
-            return EMPTY_CONTROLS$2;
-        return allControls;
+        if (!hasAny)
+            return EMPTY_AREA_CONTROLS;
+        return areas;
     }, [layers]);
     // ---- Build the return object ----
     return useMemo(() => ({
@@ -5482,7 +5627,7 @@ const resolveServerClusters = (cluster, data, getId, resolveGroups, viewportCtx)
 // Empty constants (stable references)
 // ============================================================================
 const EMPTY_FEATURES = { type: "FeatureCollection", features: [] };
-const EMPTY_CONTROLS$1 = [];
+const EMPTY_CONTROLS$1 = {};
 /**
  * Filter items to only those with valid positions and extract id + position.
  * Invalid positions (e.g. latitude out of range) are skipped. Logs once when any are filtered.
@@ -6183,7 +6328,7 @@ const buildMultiPartDecorations = (feature, strokeColor, pointRadius, strokeWidt
 // ============================================================================
 // Constants
 // ============================================================================
-const EMPTY_CONTROLS = [];
+const EMPTY_CONTROLS = {};
 const EMPTY_STYLE = {};
 // ============================================================================
 // Internal helpers
@@ -6667,7 +6812,7 @@ const noopGuard = (_active) => undefined;
  *   suppresses adapter hover-start/hover-end). Call with `false` when the DOM
  *   hover ends, allowing adapter events to flow again.
  */
-const useEntityInteraction = ({ layerPort, hover, select, dblClick, }) => {
+const useEntityInteraction = ({ layerPort, hover, select, dblClick, onClick, }) => {
     const hoverRef = useRef(hover);
     useEffect(() => {
         hoverRef.current = hover;
@@ -6680,6 +6825,10 @@ const useEntityInteraction = ({ layerPort, hover, select, dblClick, }) => {
     useEffect(() => {
         dblClickRef.current = dblClick;
     }, [dblClick]);
+    const onClickRef = useRef(onClick);
+    useEffect(() => {
+        onClickRef.current = onClick;
+    }, [onClick]);
     const guardRef = useRef(noopGuard);
     useEffect(() => {
         if (layerPort === null)
@@ -6697,6 +6846,7 @@ const useEntityInteraction = ({ layerPort, hover, select, dblClick, }) => {
             const { type } = event;
             switch (type) {
                 case "click":
+                    onClickRef.current?.(event.entity);
                     selectRef.current(event.entity);
                     break;
                 case "dblclick":
@@ -8770,7 +8920,7 @@ const applyPortalZIndex = (container, zIndex) => {
  * );
  * ```
  */
-const Layers = ({ layers, api }) => {
+const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
     const layerPort = useLayerPort();
     const [decorationLayers, setDecorationLayers] = useState([]);
     const [viewportStyleOverrides, setViewportStyleOverrides] = useState(new Map());
@@ -8804,12 +8954,17 @@ const Layers = ({ layers, api }) => {
             layers.select(entity);
         }
     }, [layers]);
-    const handleDblClick = useDblClickFit(api, layers.handles);
+    const fitOnDblClick = useDblClickFit(api, layers.handles);
+    const handleDblClick = useCallback((entity) => {
+        onEntityDblClick?.(entity);
+        fitOnDblClick?.(entity);
+    }, [onEntityDblClick, fitOnDblClick]);
     const setDomHoverActive = useEntityInteraction({
         layerPort,
         hover: layers.hover,
         select: coordinatedSelect,
         dblClick: handleDblClick,
+        onClick: onEntityClick,
     });
     const coordinatedHover = useCallback((entity) => {
         setDomHoverActive(entity !== null);
@@ -9254,80 +9409,68 @@ const ShapeAnnotationLabel = ({ geometry, color, label, theme, isHovered = false
     return jsx("div", { className: "pointer-events-none", children: pill });
 };
 
-const markerStateFromParams = (params) => {
-    if ("markerState" in params) {
-        return params.markerState;
-    }
-    const input = {
-        selected: params.selected,
-        hovered: params.hovered,
-        expandedRank: params.expandedRank,
-    };
-    return resolveMarkerState(input);
-};
-const stackPhaseForMarkerState = (markerState) => {
-    if (markerState === "selected")
-        return "selected";
-    if (markerState === "hovered")
-        return "hovered";
-    if (markerState === "expanded")
-        return "expanded";
-    return "idle";
-};
 /**
- * Maps `<MapMarker>` presentation + state to `DomPortalStackingResult` for use with
- * `markerRender.resolveDomPortalStacking` in `<Layers>`.
+ * Build-your-own hook: stable reference to the cluster count formatter.
  *
- * Pass either `expandedRank` (for `resolveMarkerState`) or a pre-resolved `markerState`
- * when the expanded state is data-driven and does not use `expandedRank` (for example, story helpers).
+ * Returns `formatClusterCount` for consumers building custom cluster markers
+ * that need consistent `"1.2k / 3.4m"` formatting without reimplementing
+ * the truncation rules.
+ *
+ * @example
+ * ```tsx
+ * const { formatClusterCount } = useClusterCountFormat();
+ * // Inside your cluster render:
+ * return <div>{formatClusterCount(clusterCount)}</div>;
+ * ```
  */
-const resolveMapMarkerDomPortalStacking = (params) => {
-    const { hasStick, isMounting, labelVisible } = params;
-    if (isMounting === true) {
-        return { geometry: "circle", phase: "idle" };
-    }
-    const markerState = markerStateFromParams(params);
-    const form = resolveMarkerForm(markerState, labelVisible);
-    const geometry = hasStick === true ? "stick" : form === "pill" ? "pill" : "circle";
-    return {
-        geometry,
-        phase: stackPhaseForMarkerState(markerState),
-    };
+const useClusterCountFormat = () => {
+    return useMemo(() => ({
+        formatClusterCount,
+    }), []);
 };
 
 /**
- * Build-your-own hook: stable references to the full adaptive marker kit.
+ * Pure function that builds a `ControlsConfig` from per-area control stacks.
  *
- * Returns the complete set of primitives needed to hand-roll an adaptive marker
- * layer (DOM ↔ symbol mode switching, zoom-based sizing, portal stacking) while
- * staying consistent with `useMarkers`'s built-in rendering pipeline.
+ * Each area in `areas` is passed through `defineControlStack` (which filters
+ * `undefined` entries and rejects duplicate ids). Omitted areas default to
+ * `{ controls: [] }`.
  *
  * @example
- * ```tsx
- * const {
- *   pickRenderMedium, pickMarkerSize, pickSymbolDescriptor,
- *   resolveAdaptiveMarkerState, resolveMapMarkerDomPortalStacking,
- * } = useAdaptiveMarkerHelpers();
+ * ```ts
+ * const controls = composeControlAreas({
+ *   navigation: [builtIn.navigation.zoom, builtIn.navigation.fullscreen],
+ *   settings: [builtIn.settings.mapStyle],
+ * });
+ * ```
+ */
+const composeControlAreas = (areas) => ({
+    navigation: { controls: defineControlStack(areas.navigation ?? []) },
+    settings: { controls: defineControlStack(areas.settings ?? []) },
+    tools: { controls: defineControlStack(areas.tools ?? []) },
+    statistics: { controls: defineControlStack(areas.statistics ?? []) },
+});
+
+/**
+ * Build-your-own hook: stable references to control composition helpers.
  *
- * // Inside your adaptive render callback:
- * const medium = pickRenderMedium(ctx);
- * if (medium === "symbol") return pickSymbolDescriptor(color, theme, ctx);
- * const size  = pickMarkerSize(ctx);
- * const state = resolveAdaptiveMarkerState({ selected, hovered });
+ * Returns `defineControlStack` and `composeControlAreas` for consumers building
+ * custom control layouts without duplicating the stack-ordering logic already
+ * used by `Controls`.
+ *
+ * @example
+ * ```tsx
+ * const { defineControlStack, composeControlAreas } = useControlStack();
+ * const controls = composeControlAreas({
+ *   navigation: [builtIn.navigation.zoom, builtIn.navigation.fullscreen],
+ *   settings: [builtIn.settings.mapStyle],
+ * });
  * ```
  */
-const useAdaptiveMarkerHelpers = () => {
+const useControlStack = () => {
     return useMemo(() => ({
-        pickMarkerSize,
-        pickRenderMedium,
-        pickSymbolDescriptor,
-        pickSymbolDiameter,
-        resolveAdaptiveMarkerState,
-        downgradeMarkerDomSize,
-        upgradeMarkerDomSize,
-        resolveMapMarkerDomPortalStacking,
-        DEFAULT_MARKER_SIZE_BREAKPOINTS,
-        MARKER_DISC_BORDER_WIDTH_PX,
+        defineControlStack,
+        composeControlAreas,
     }), []);
 };
 
@@ -9351,188 +9494,80 @@ const useFitFeatureBounds = () => {
     }), []);
 };
 
-const PADDING_PX = 12;
-/**
- * Default auto-pan resolver: pans the minimum amount to give the panel the
- * best possible screen space. Handles two cases:
- *
- * 1. **Clipping** — panel bleeds outside the map container on any side. Pans
- *    to clear the bleed with 12 px of breathing room.
- *
- * 2. **Scroll-squish** — panel is within the container but shift-pressed against
- *    an edge, so content overflows and the panel scrolls. Pans to give the panel
- *    room to grow, up to the CSS `max-height` cap (`panelCssMaxHeight`).
- *
- * Returns `null` when the panel already fits without scrolling and without
- * clipping — meaning no pan is needed.
- *
- * Pass as `resolveAutoPan` to {@link usePanel} for the standard behavior:
- *
- * ```tsx
- * usePanel(api, {
- *   id: "my-panel",
- *   open: isOpen,
- *   resolveAutoPan: defaultAutoPanResolver,
- *   children: <MyPanelContent />,
- * });
- * ```
- */
-const defaultAutoPanResolver = (ctx) => {
-    const { clipping, placement, panelRect, anchorRect, panelScrollHeight, panelCssMaxHeight } = ctx;
-    // --- Clipping: clear overflow past container edges ---
-    const x = clipping.right > 0 ? clipping.right + PADDING_PX : clipping.left > 0 ? -(clipping.left + PADDING_PX) : 0;
-    const clippingY = clipping.bottom > 0 ? clipping.bottom + PADDING_PX : clipping.top > 0 ? -(clipping.top + PADDING_PX) : 0;
-    // --- Scroll-squish: pan to give the panel room to stop scrolling.
-    // Cap at panelCssMaxHeight — panning further cannot reduce scrolling.
-    const squishAmount = Math.max(0, Math.min(panelScrollHeight, panelCssMaxHeight) - panelRect.height);
-    let squishY = 0;
-    if (squishAmount > 0) {
-        if (placement.startsWith("top")) {
-            // Panel is above the anchor. Move anchor down (negative y) to open space above.
-            squishY = -(squishAmount + PADDING_PX);
-        }
-        else if (placement.startsWith("bottom")) {
-            // Panel is below the anchor. Move anchor up (positive y) to open space below.
-            squishY = squishAmount + PADDING_PX;
-        }
-        else {
-            // left/right placements: panel is vertically centered on the anchor.
-            // Infer which edge shift pressed the panel against by comparing the
-            // panel's natural center position to its actual rendered top.
-            const anchorCenterY = anchorRect.top + anchorRect.height / 2;
-            const naturalPanelTop = anchorCenterY - panelRect.height / 2;
-            const shiftDelta = panelRect.top - naturalPanelTop;
-            if (shiftDelta > 1) {
-                // Shift pressed panel down (anchor near top) — move anchor down.
-                squishY = -(squishAmount + PADDING_PX);
-            }
-            else if (shiftDelta < -1) {
-                // Shift pressed panel up (anchor near bottom) — move anchor up.
-                squishY = squishAmount + PADDING_PX;
-            }
-            // shiftDelta ≈ 0: squish is from CSS max-height alone, not position — skip.
-        }
+const markerStateFromParams = (params) => {
+    if ("markerState" in params) {
+        return params.markerState;
     }
-    // After shift, clippingY and squishY are mutually exclusive on the same axis
-    // (shift keeps the panel within container bounds). clippingY takes priority as
-    // a defensive fallback for the edge case where both are non-zero.
-    const y = clippingY || squishY;
-    if (x === 0 && y === 0)
-        return null;
-    return { x, y, restoreOnDismiss: true };
-};
-
-/**
- * Build-your-own hook: stable reference to the default auto-pan resolver.
- *
- * Returns `defaultAutoPanResolver` for consumers who want to pass it to
- * `usePanel({ resolveAutoPan })` or use it as a baseline to wrap/replace
- * with custom logic.
- *
- * @example
- * ```tsx
- * const { defaultAutoPanResolver } = useAutoPanResolver();
- * usePanel(api, {
- *   id: "my-panel",
- *   open: isOpen,
- *   resolveAutoPan: defaultAutoPanResolver,
- *   children: <MyContent />,
- * });
- * ```
- */
-const useAutoPanResolver = () => {
-    return useMemo(() => ({
-        defaultAutoPanResolver,
-    }), []);
+    const input = {
+        selected: params.selected,
+        hovered: params.hovered,
+        expandedRank: params.expandedRank,
+    };
+    return resolveMarkerState(input);
 };
-
-/**
- * Build-your-own hook: stable reference to the cluster count formatter.
- *
- * Returns `formatClusterCount` for consumers building custom cluster markers
- * that need consistent `"1.2k / 3.4m"` formatting without reimplementing
- * the truncation rules.
- *
- * @example
- * ```tsx
- * const { formatClusterCount } = useClusterCountFormat();
- * // Inside your cluster render:
- * return <div>{formatClusterCount(clusterCount)}</div>;
- * ```
- */
-const useClusterCountFormat = () => {
-    return useMemo(() => ({
-        formatClusterCount,
-    }), []);
+const stackPhaseForMarkerState = (markerState) => {
+    if (markerState === "selected")
+        return "selected";
+    if (markerState === "hovered")
+        return "hovered";
+    if (markerState === "expanded")
+        return "expanded";
+    return "idle";
 };
-
 /**
- * Build-your-own hook: stable references to control composition/layout helpers.
- *
- * Returns `defineControlStack` and `collapseControls` for consumers building
- * custom control layouts without duplicating the stack-ordering and responsive-
- * collapse logic already used by `Controls`.
+ * Maps `<MapMarker>` presentation + state to `DomPortalStackingResult` for use with
+ * `markerRender.resolveDomPortalStacking` in `<Layers>`.
  *
- * @example
- * ```tsx
- * const { defineControlStack, collapseControls } = useControlStack();
- * const controls = defineControlStack([myControl, undefined, otherControl]);
- * const collapsed = collapseControls(config, responsiveMode, metadata);
- * ```
+ * Pass either `expandedRank` (for `resolveMarkerState`) or a pre-resolved `markerState`
+ * when the expanded state is data-driven and does not use `expandedRank` (for example, story helpers).
  */
-const useControlStack = () => {
-    return useMemo(() => ({
-        defineControlStack,
-        collapseControls,
-    }), []);
+const resolveMapMarkerDomPortalStacking = (params) => {
+    const { hasStick, isMounting, labelVisible } = params;
+    if (isMounting === true) {
+        return { geometry: "circle", phase: "idle" };
+    }
+    const markerState = markerStateFromParams(params);
+    const form = resolveMarkerForm(markerState, labelVisible);
+    const geometry = hasStick === true ? "stick" : form === "pill" ? "pill" : "circle";
+    return {
+        geometry,
+        phase: stackPhaseForMarkerState(markerState),
+    };
 };
 
 /**
- * Build-your-own hook: stable references to theme-aware marker color primitives.
+ * Build-your-own hook: stable references to the full adaptive marker kit.
  *
- * Returns the `defaultMarkerColorConfig` factory and `resolveMarkerColors` resolver
- * for consumers building custom marker components that need to stay visually
- * consistent with `MapMarker`'s pill/indicator color system.
+ * Returns the complete set of primitives needed to hand-roll an adaptive marker
+ * layer (DOM ↔ symbol mode switching, zoom-based sizing, portal stacking) while
+ * staying consistent with `useMarkers`'s built-in rendering pipeline.
  *
  * @example
  * ```tsx
- * const { defaultMarkerColorConfig, resolveMarkerColors } = useMarkerColors();
- * const config  = defaultMarkerColorConfig(theme);
- * const colors  = resolveMarkerColors(fillColor, state, theme, config);
- * // Spread colors.cssVars onto the marker root element.
- * ```
- */
-const useMarkerColors = () => {
-    return useMemo(() => ({
-        defaultMarkerColorConfig,
-        resolveMarkerColors,
-        MARKER_DARK_PILL,
-        MARKER_LIGHT_PILL,
-    }), []);
-};
-
-/**
- * Build-your-own hook: stable references to marker state resolution primitives.
- *
- * Returns a memoized object of the pure resolver functions for consumers that
- * want to hand-roll their own MapMarker replacement while staying consistent
- * with the library's state priority rules (selected → expanded → hovered → default).
+ * const {
+ *   pickRenderMedium, pickMarkerSize, pickSymbolDescriptor,
+ *   resolveAdaptiveMarkerState, resolveMapMarkerDomPortalStacking,
+ * } = useAdaptiveMarkerHelpers();
  *
- * @example
- * ```tsx
- * const { resolveMarkerState, resolveMarkerForm } = useMarkerStateResolvers();
- * const state = resolveMarkerState({ selected, hovered, expandedRank });
- * const form  = resolveMarkerForm(state, labelVisible);
+ * // Inside your adaptive render callback:
+ * const medium = pickRenderMedium(ctx);
+ * if (medium === "symbol") return pickSymbolDescriptor(color, theme, ctx);
+ * const size  = pickMarkerSize(ctx);
+ * const state = resolveAdaptiveMarkerState({ selected, hovered });
  * ```
  */
-const useMarkerStateResolvers = () => {
+const useAdaptiveMarkerHelpers = () => {
     return useMemo(() => ({
-        resolveMarkerState,
-        resolveMarkerForm,
-        resolveEffectiveSize,
-        resolveMarkerDomSize,
+        pickMarkerSize,
+        pickRenderMedium,
+        pickSymbolDescriptor,
+        pickSymbolDiameter,
         resolveAdaptiveMarkerState,
-        MARKER_SIZE_MAP,
+        downgradeMarkerDomSize,
+        upgradeMarkerDomSize,
+        resolveMapMarkerDomPortalStacking,
+        DEFAULT_MARKER_SIZE_BREAKPOINTS,
+        MARKER_DISC_BORDER_WIDTH_PX,
     }), []);
 };
 
@@ -9630,6 +9665,150 @@ const useShapeLabelHelpers = () => {
     }), []);
 };
 
+/**
+ * Build-your-own hook: stable references to marker state resolution primitives.
+ *
+ * Returns a memoized object of the pure resolver functions for consumers that
+ * want to hand-roll their own MapMarker replacement while staying consistent
+ * with the library's state priority rules (selected → expanded → hovered → default).
+ *
+ * @example
+ * ```tsx
+ * const { resolveMarkerState, resolveMarkerForm } = useMarkerStateResolvers();
+ * const state = resolveMarkerState({ selected, hovered, expandedRank });
+ * const form  = resolveMarkerForm(state, labelVisible);
+ * ```
+ */
+const useMarkerStateResolvers = () => {
+    return useMemo(() => ({
+        resolveMarkerState,
+        resolveMarkerForm,
+        resolveEffectiveSize,
+        resolveMarkerDomSize,
+        resolveAdaptiveMarkerState,
+        MARKER_SIZE_MAP,
+    }), []);
+};
+
+/**
+ * Build-your-own hook: stable references to theme-aware marker color primitives.
+ *
+ * Returns the `defaultMarkerColorConfig` factory and `resolveMarkerColors` resolver
+ * for consumers building custom marker components that need to stay visually
+ * consistent with `MapMarker`'s pill/indicator color system.
+ *
+ * @example
+ * ```tsx
+ * const { defaultMarkerColorConfig, resolveMarkerColors } = useMarkerColors();
+ * const config  = defaultMarkerColorConfig(theme);
+ * const colors  = resolveMarkerColors(fillColor, state, theme, config);
+ * // Spread colors.cssVars onto the marker root element.
+ * ```
+ */
+const useMarkerColors = () => {
+    return useMemo(() => ({
+        defaultMarkerColorConfig,
+        resolveMarkerColors,
+        MARKER_DARK_PILL,
+        MARKER_LIGHT_PILL,
+    }), []);
+};
+
+const PADDING_PX = 12;
+/**
+ * Default auto-pan resolver: pans the minimum amount to give the panel the
+ * best possible screen space. Handles two cases:
+ *
+ * 1. **Clipping** — panel bleeds outside the map container on any side. Pans
+ *    to clear the bleed with 12 px of breathing room.
+ *
+ * 2. **Scroll-squish** — panel is within the container but shift-pressed against
+ *    an edge, so content overflows and the panel scrolls. Pans to give the panel
+ *    room to grow, up to the CSS `max-height` cap (`panelCssMaxHeight`).
+ *
+ * Returns `null` when the panel already fits without scrolling and without
+ * clipping — meaning no pan is needed.
+ *
+ * Pass as `resolveAutoPan` to {@link usePanel} for the standard behavior:
+ *
+ * ```tsx
+ * usePanel(api, {
+ *   id: "my-panel",
+ *   open: isOpen,
+ *   resolveAutoPan: defaultAutoPanResolver,
+ *   children: <MyPanelContent />,
+ * });
+ * ```
+ */
+const defaultAutoPanResolver = (ctx) => {
+    const { clipping, placement, panelRect, anchorRect, panelScrollHeight, panelCssMaxHeight } = ctx;
+    // --- Clipping: clear overflow past container edges ---
+    const x = clipping.right > 0 ? clipping.right + PADDING_PX : clipping.left > 0 ? -(clipping.left + PADDING_PX) : 0;
+    const clippingY = clipping.bottom > 0 ? clipping.bottom + PADDING_PX : clipping.top > 0 ? -(clipping.top + PADDING_PX) : 0;
+    // --- Scroll-squish: pan to give the panel room to stop scrolling.
+    // Cap at panelCssMaxHeight — panning further cannot reduce scrolling.
+    const squishAmount = Math.max(0, Math.min(panelScrollHeight, panelCssMaxHeight) - panelRect.height);
+    let squishY = 0;
+    if (squishAmount > 0) {
+        if (placement.startsWith("top")) {
+            // Panel is above the anchor. Move anchor down (negative y) to open space above.
+            squishY = -(squishAmount + PADDING_PX);
+        }
+        else if (placement.startsWith("bottom")) {
+            // Panel is below the anchor. Move anchor up (positive y) to open space below.
+            squishY = squishAmount + PADDING_PX;
+        }
+        else {
+            // left/right placements: panel is vertically centered on the anchor.
+            // Infer which edge shift pressed the panel against by comparing the
+            // panel's natural center position to its actual rendered top.
+            const anchorCenterY = anchorRect.top + anchorRect.height / 2;
+            const naturalPanelTop = anchorCenterY - panelRect.height / 2;
+            const shiftDelta = panelRect.top - naturalPanelTop;
+            if (shiftDelta > 1) {
+                // Shift pressed panel down (anchor near top) — move anchor down.
+                squishY = -(squishAmount + PADDING_PX);
+            }
+            else if (shiftDelta < -1) {
+                // Shift pressed panel up (anchor near bottom) — move anchor up.
+                squishY = squishAmount + PADDING_PX;
+            }
+            // shiftDelta ≈ 0: squish is from CSS max-height alone, not position — skip.
+        }
+    }
+    // After shift, clippingY and squishY are mutually exclusive on the same axis
+    // (shift keeps the panel within container bounds). clippingY takes priority as
+    // a defensive fallback for the edge case where both are non-zero.
+    const y = clippingY || squishY;
+    if (x === 0 && y === 0)
+        return null;
+    return { x, y, restoreOnDismiss: true };
+};
+
+/**
+ * Build-your-own hook: stable reference to the default auto-pan resolver.
+ *
+ * Returns `defaultAutoPanResolver` for consumers who want to pass it to
+ * `usePanel({ resolveAutoPan })` or use it as a baseline to wrap/replace
+ * with custom logic.
+ *
+ * @example
+ * ```tsx
+ * const { defaultAutoPanResolver } = useAutoPanResolver();
+ * usePanel(api, {
+ *   id: "my-panel",
+ *   open: isOpen,
+ *   resolveAutoPan: defaultAutoPanResolver,
+ *   children: <MyContent />,
+ * });
+ * ```
+ */
+const useAutoPanResolver = () => {
+    return useMemo(() => ({
+        defaultAutoPanResolver,
+    }), []);
+};
+
 const VIEWPORT_BOUNDS = [-50, -50, 50, 50];
 const INITIAL_STATE = {
     center: [0, 0],
@@ -9749,4 +9928,4 @@ const mockMapApi = (overrides) => {
  */
 setupLibraryTranslations();
 
-export { ClusterMarker, ClusterStick, Controls, DEFAULT_MARKER_SIZE_BREAKPOINTS, Layers, MARKER_DARK_PILL, MARKER_DISC_BORDER_WIDTH_PX, MARKER_LIGHT_PILL, MARKER_PILL_CONTENT_LAYOUT_SIZE, MARKER_SIZE_MAP, MARKER_TUNING, MapLoadingState, MapMarker, MapMarkerIcon, ShapeAnnotationLabel, buildExpandedIds, cvaMapMarker, cvaMarkerIndicator, mockMapApi, useAdaptiveMarkerHelpers, useAutoPanResolver, useCameraIdle, useCameraState, useClusterCountFormat, useControlStack, useControlsConfig, useDirectionIndicator, useExpandedIds, useFitFeatureBounds, useFitToContent, useImageOverlay, useLayers, useMap, useMapAnnotation, useMapAnnotations, useMapAppearanceControls, useMapKeyboardNavigation, useMarkerColors, useMarkerStateResolvers, useMarkers, usePanel, usePanelPreload, usePreviewMap, useRoute, useShapeLabelHelpers, useShapes, useViewportContext };
+export { ClusterMarker, ClusterStick, Controls, DEFAULT_MARKER_SIZE_BREAKPOINTS, DefaultControls, Layers, MARKER_DARK_PILL, MARKER_DISC_BORDER_WIDTH_PX, MARKER_LIGHT_PILL, MARKER_PILL_CONTENT_LAYOUT_SIZE, MARKER_SIZE_MAP, MARKER_TUNING, MapLoadingState, MapMarker, MapMarkerIcon, ShapeAnnotationLabel, buildExpandedIds, cvaMapMarker, cvaMarkerIndicator, mockMapApi, useAdaptiveMarkerHelpers, useAutoPanResolver, useCameraIdle, useCameraState, useClusterCountFormat, useControlStack, useControls, useDefaultControls, useDirectionIndicator, useExpandedIds, useFitFeatureBounds, useFitToContent, useImageOverlay, useLayers, useMap, useMapAnnotation, useMapAnnotations, useMapAppearanceControls, useMapKeyboardNavigation, useMarkerColors, useMarkerStateResolvers, useMarkers, usePanel, usePanelPreload, usePreviewMap, useRoute, useShapeLabelHelpers, useShapes, useViewportContext };