@trackunit/react-map 0.2.224 → 0.2.225

package/index.esm.js

@@ -1,6 +1,6 @@
 import { jsx, Fragment, jsxs } from 'react/jsx-runtime';
 import { useNamespaceTranslation, registerTranslations } from '@trackunit/i18n-library-translation';
-import { INITIAL_CAMERA_STATE, INITIAL_MAP_STATUS, KEYBOARD_PAN_AMOUNT, KEYBOARD_ZOOM_AMOUNT, mapAppearanceSchema, DEFAULT_MAP_APPEARANCE, EMPTY_DRAW_VALUE, WORLD_BBOX, INITIAL_INTERACTION_STATE, mapThemeSchema, mergeAntimeridianFeatures, extractSourceData, computeMarkerDomPortalZIndex, densifyGeodesicFeatures, angularDistance, intermediatePoint, GEODESIC_MAX_SEGMENT_KM, geometryTypeToShapeType, resolveStrokeColors } from '@trackunit/react-map-adapter-shared';
+import { INITIAL_CAMERA_STATE, INITIAL_MAP_STATUS, KEYBOARD_PAN_AMOUNT, KEYBOARD_ZOOM_AMOUNT, mapAppearanceSchema, DEFAULT_MAP_APPEARANCE, EMPTY_DRAW_VALUE, NO_DRAW_ERRORS, WORLD_BBOX, INITIAL_INTERACTION_STATE, mapThemeSchema, mergeAntimeridianFeatures, extractSourceData, computeMarkerDomPortalZIndex, densifyGeodesicFeatures, angularDistance, intermediatePoint, GEODESIC_MAX_SEGMENT_KM, geometryTypeToShapeType, resolveStrokeColors } from '@trackunit/react-map-adapter-shared';
 export { ANCHOR_SELECTOR, DEFAULT_MAP_APPEARANCE, EMPTY_DRAW_VALUE, HIT_SURFACE_SELECTOR, INITIAL_CAMERA_STATE, INITIAL_INTERACTION_STATE, INITIAL_MAP_STATE, INITIAL_MAP_STATUS, computeMarkerDomPortalZIndex, defineAdapter, geometryTypeToShapeType, mapAppearanceSchema, mapThemeSchema, mapTypeSchema } from '@trackunit/react-map-adapter-shared';
 import { useSyncExternalStore, useMemo, useState, useRef, useCallback, useLayoutEffect, useEffect, useReducer, createContext, useContext, memo, Suspense, useId, Fragment as Fragment$1, forwardRef } from 'react';
 import { cva } from '@trackunit/css-class-variance-utilities';
@@ -32,6 +32,7 @@ var defaultTranslations = {
 	"controls.stepper.increase": "Increase",
 	"controls.zoom": "Zoom",
 	"draw.clear": "Clear drawing",
+	"draw.limitReached": "Polygon limit reached. Clear the drawing to draw again",
 	"draw.polygon": "Draw polygon",
 	"draw.select": "Edit polygon",
 	"draw.selectDisabled": "Draw a polygon first",
@@ -40,6 +41,7 @@ var defaultTranslations = {
 	"map.loadingErrorMessage": "Unable to load the map. Please try again later.",
 	"multiGeometry.badge.tooltip": "Part of a multi-part shape",
 	"settings.mapStyle.dark": "Dark",
+	"settings.mapStyle.disabledWhileDrawing": "Finish drawing to change the map style",
 	"settings.mapStyle.light": "Light",
 	"settings.mapStyle.roadmap": "Road map",
 	"settings.mapStyle.roads": "Roads",
@@ -1831,14 +1833,44 @@ const RIGHT_CONTROL_POPOVER_PLACEMENT = "right-start";
 const RIGHT_CONTROL_TOOLTIP_PLACEMENT = "right";
 
 /**
- * Wraps standalone map controls with a right-aligned tooltip when `overlaySide` is `"right"`.
- * Callers should omit `title` on {@link IconButton} in that mode so tooltips do not stack.
+ * Whether `StandaloneControlTooltip` wraps its child: always on the right overlay
+ * side, and on any side when the caller requires it (a disabled `IconButton` drops
+ * its own tooltip, so a disabled reason needs the wrapper). Callers omit `title`
+ * on the `IconButton` whenever this is true so tooltips do not stack.
  */
-const StandaloneControlTooltip = ({ children, disabled = false, label, overlaySide = undefined, }) => {
-    if (overlaySide !== "right") {
+const isStandaloneTooltipWrapped = (overlaySide, required) => overlaySide === "right" || required;
+
+/**
+ * Wraps standalone map controls with a right-aligned tooltip when `overlaySide` is `"right"`,
+ * or on any side when `required`. Callers should omit `title` on {@link IconButton} whenever
+ * this wraps so tooltips do not stack; `isStandaloneTooltipWrapped` tells them.
+ */
+const StandaloneControlTooltip = ({ children, disabled = false, label, overlaySide = undefined, required = false, }) => {
+    if (!isStandaloneTooltipWrapped(overlaySide, required)) {
         return children;
     }
-    return (jsx(Tooltip, { delayed: true, disabled: disabled, interactable: false, label: label, placement: RIGHT_CONTROL_TOOLTIP_PLACEMENT, children: children }));
+    return (jsx(Tooltip, { delayed: true, disabled: disabled, interactable: false, label: label, placement: overlaySide === "right" ? RIGHT_CONTROL_TOOLTIP_PLACEMENT : "auto", children: children }));
+};
+
+/**
+ * A disabled control is not focusable and its tooltip is hover-only, so the reason it is
+ * disabled is also announced to assistive technology: a visually hidden copy of the reason,
+ * linked from the control through `aria-describedby`. One hook for every control that shows a
+ * `disabledReason`, so the pattern has one home (BooleanButton, Menu, AppearancePreview).
+ */
+const useDisabledReason = ({ disabled = false, disabledReason, }) => {
+    const id = useId();
+    return useMemo(() => {
+        if (!disabled || disabledReason === undefined) {
+            return { showsReason: false, reason: undefined, describedBy: undefined, description: null };
+        }
+        return {
+            showsReason: true,
+            reason: disabledReason,
+            describedBy: id,
+            description: (jsx("span", { className: "sr-only", id: id, children: disabledReason })),
+        };
+    }, [disabled, disabledReason, id]);
 };
 
 /**
@@ -1853,15 +1885,15 @@ const BooleanButton = ({ config, overlaySide = undefined, resolved }) => {
     const { className, "data-testid": dataTestId, label, onChange: onClickChange, value } = config;
     const { icon, size } = resolved;
     const [t] = useTranslation();
+    const { showsReason, reason, describedBy, description } = useDisabledReason(config);
     if (icon === undefined) {
         return null;
     }
     // A disabled control's tooltip explains what unblocks it rather than what clicking would do
-    const tooltipLabel = config.disabled === true && config.disabledReason !== undefined
-        ? config.disabledReason
-        : t("controls.boolean.tooltip", { label });
-    const useRightOverlay = overlaySide === "right";
-    return (jsx(StandaloneControlTooltip, { label: tooltipLabel, overlaySide: overlaySide, children: jsx(IconButton, { ...(useRightOverlay ? { ariaLabel: label } : { title: tooltipLabel }), "aria-pressed": value, className: className, "data-testid": dataTestId, disabled: config.disabled ?? false, icon: jsx(Icon, { name: icon, size: "small" }), onClick: () => onClickChange(!value), size: size, variant: value ? "primary" : "secondary" }) }));
+    const tooltipLabel = showsReason ? reason : t("controls.boolean.tooltip", { label });
+    // IconButton drops its own tooltip while disabled, so the reason needs the wrapper on every side.
+    const wrapped = isStandaloneTooltipWrapped(overlaySide, showsReason);
+    return (jsxs(Fragment, { children: [jsx(StandaloneControlTooltip, { label: tooltipLabel, overlaySide: overlaySide, required: showsReason, children: jsx(IconButton, { ...(wrapped ? { ariaLabel: label } : { title: tooltipLabel }), "aria-describedby": describedBy, "aria-pressed": value, className: className, "data-testid": dataTestId, disabled: config.disabled ?? false, icon: jsx(Icon, { name: icon, size: "small" }), onClick: () => onClickChange(!value), size: size, variant: value ? "primary" : "secondary" }) }), description] }));
 };
 
 /**
@@ -2376,6 +2408,9 @@ const SectionHeader = ({ title, className }) => (jsx("div", { className: twMerge
  */
 const Separator = ({ className }) => (jsx("div", { className: twMerge("my-1 h-px bg-neutral-200", className), role: "separator" }));
 
+/** A disabled menu's tooltip explains what unblocks it rather than what it opens. */
+const menuTooltipLabel = (config) => config.disabled === true && config.disabledReason !== undefined ? config.disabledReason : config.label;
+
 /**
  * Renders a menu item based on its type.
  * Calls resolveControl with placement: "menu" for each item.
@@ -2450,8 +2485,11 @@ const MenuContent = ({ availableSpace, customPortalId, isFullScreen, items }) =>
 /** Popover opens right; tooltip is suppressed while the menu is open. */
 const MenuRightPopover = ({ availableSpace, config, customPortalId, resolved, }) => {
     const { className, "data-testid": dataTestId, items, label } = config;
+    const disabled = config.disabled ?? false;
+    const tooltipLabel = menuTooltipLabel(config);
+    const { describedBy, description } = useDisabledReason(config);
     const isFullScreen = useIsFullscreen();
-    return (jsx("div", { className: className ?? "w-fit", children: jsx(Popover, { placement: RIGHT_CONTROL_POPOVER_PLACEMENT, children: ({ isOpen }) => (jsxs(Fragment$1, { children: [jsx(PopoverTrigger, { children: jsx(Tooltip, { delayed: true, disabled: isOpen, interactable: false, label: label, placement: RIGHT_CONTROL_TOOLTIP_PLACEMENT, children: jsx(IconButton, { ariaLabel: label, "data-testid": dataTestId, icon: jsx(Icon, { name: resolved.icon ?? "QuestionMarkCircle", size: "small" }), size: resolved.size, variant: "secondary" }) }) }), jsx(PopoverContent, { className: "overflow-clip", portalId: isFullScreen ? customPortalId : undefined, children: jsx(MenuContent, { availableSpace: availableSpace, customPortalId: customPortalId, isFullScreen: isFullScreen, items: items }) })] })) }) }));
+    return (jsxs("div", { className: className ?? "w-fit", children: [jsx(Popover, { placement: RIGHT_CONTROL_POPOVER_PLACEMENT, children: ({ isOpen }) => (jsxs(Fragment$1, { children: [jsx(PopoverTrigger, { children: jsx(Tooltip, { delayed: true, disabled: isOpen, interactable: false, label: tooltipLabel, placement: RIGHT_CONTROL_TOOLTIP_PLACEMENT, children: jsx(IconButton, { "aria-describedby": describedBy, ariaLabel: label, "data-testid": dataTestId, disabled: disabled, icon: jsx(Icon, { name: resolved.icon ?? "QuestionMarkCircle", size: "small" }), size: resolved.size, variant: "secondary" }) }) }), jsx(PopoverContent, { className: "overflow-clip", portalId: isFullScreen ? customPortalId : undefined, children: jsx(MenuContent, { availableSpace: availableSpace, customPortalId: customPortalId, isFullScreen: isFullScreen, items: items }) })] })) }), description] }));
 };
 /** Popover presentation -- renders a position-aware popover anchored to the trigger button. */
 const MenuAutoPopover = ({ availableSpace, config, containerRef, customPortalId, resolved, }) => {
@@ -2459,7 +2497,13 @@ const MenuAutoPopover = ({ availableSpace, config, containerRef, customPortalId,
     const isFullScreen = useIsFullscreen();
     const triggerRef = useRef(null);
     const popoverPlacement = usePopoverPlacement(triggerRef, containerRef);
-    return (jsx("div", { className: className ?? "w-fit", ref: triggerRef, children: jsxs(Popover, { placement: popoverPlacement, children: [jsx(PopoverTrigger, { children: jsx(IconButton, { "data-testid": dataTestId, icon: jsx(Icon, { name: resolved.icon ?? "QuestionMarkCircle", size: "small" }), size: resolved.size, title: label, variant: "secondary" }) }), jsx(PopoverContent, { className: "overflow-clip", portalId: isFullScreen ? customPortalId : undefined, children: jsx(MenuContent, { availableSpace: availableSpace, customPortalId: customPortalId, isFullScreen: isFullScreen, items: items }) })] }) }));
+    const disabled = config.disabled ?? false;
+    const tooltipLabel = menuTooltipLabel(config);
+    const { showsReason, describedBy, description } = useDisabledReason(config);
+    // IconButton drops its own tooltip while disabled, so a disabled reason needs the wrapper;
+    // the accessible name then moves from `title` to `ariaLabel` so the tooltips do not stack.
+    const trigger = (jsx(IconButton, { ...(showsReason ? { ariaLabel: label, "aria-describedby": describedBy } : { title: tooltipLabel }), "data-testid": dataTestId, disabled: disabled, icon: jsx(Icon, { name: resolved.icon ?? "QuestionMarkCircle", size: "small" }), size: resolved.size, variant: "secondary" }));
+    return (jsxs("div", { className: className ?? "w-fit", ref: triggerRef, children: [jsxs(Popover, { placement: popoverPlacement, children: [jsx(PopoverTrigger, { children: showsReason ? (jsx(StandaloneControlTooltip, { label: tooltipLabel, required: true, children: trigger })) : (trigger) }), jsx(PopoverContent, { className: "overflow-clip", portalId: isFullScreen ? customPortalId : undefined, children: jsx(MenuContent, { availableSpace: availableSpace, customPortalId: customPortalId, isFullScreen: isFullScreen, items: items }) })] }), description] }));
 };
 /**
  * Renders a menu control as a popover -- either anchored to the trigger (auto-placed) or
@@ -2778,11 +2822,17 @@ const cvaMapPreview = cva({
  *
  * @internal
  */
-const AppearancePreview = ({ adapterConfig, mapType, label, selected, onSelect, "data-testid": dataTestId, }) => {
+const AppearancePreview = ({ adapterConfig, mapType, label, selected, onSelect, disabled = false, disabledReason, "data-testid": dataTestId, }) => {
     const { Map } = usePreviewMap(adapterConfig, { mapType });
-    return (jsxs("label", { className: "cursor-pointer", "data-testid": dataTestId, children: [jsxs("div", { className: cvaInteractableItem({
+    const { showsReason, describedBy, description } = useDisabledReason({ disabled, disabledReason });
+    const cell = (jsxs("label", { className: disabled ? undefined : "cursor-pointer", "data-testid": dataTestId, children: [jsxs("div", { className: cvaInteractableItem({
+                    disabled,
                     className: cvaMapPreview({ selected }),
-                }), children: [jsx("input", { checked: selected, className: "sr-only", name: "map-style-preview", onChange: onSelect, type: "radio" }), jsx("div", { className: "absolute inset-px overflow-clip rounded-[calc(var(--radius)-1px)]", inert: true, children: jsx(Map, { "aria-label": label, style: { width: "72px", height: "96px", pointerEvents: "none" } }) })] }), jsx("span", { className: "line-clamp-2 w-[72px] text-center text-xs leading-tight text-neutral-700", children: label })] }));
+                }), children: [jsx("input", { "aria-describedby": describedBy, "aria-disabled": disabled || undefined, checked: selected, className: "sr-only", name: "map-style-preview", onChange: disabled ? undefined : onSelect, readOnly: disabled, type: "radio" }), jsx("div", { className: "absolute inset-px overflow-clip rounded-[calc(var(--radius)-1px)]", inert: true, children: jsx(Map, { "aria-label": label, style: { width: "72px", height: "96px", pointerEvents: "none" } }) })] }), jsx("span", { className: "line-clamp-2 w-[72px] text-center text-xs leading-tight text-neutral-700", children: label }), description] }));
+    if (showsReason) {
+        return jsx(Tooltip, { label: disabledReason, children: cell });
+    }
+    return cell;
 };
 
 /**
@@ -2797,7 +2847,7 @@ const AppearancePreview = ({ adapterConfig, mapType, label, selected, onSelect,
  *
  * @internal
  */
-const AppearancePreviewGrid = ({ adapterConfig, ariaLabel, options, currentTheme, currentMapType, onChange, }) => {
+const AppearancePreviewGrid = ({ adapterConfig, ariaLabel, options, currentTheme, currentMapType, onChange, disabled = false, disabledReason, }) => {
     const derivedOptions = useMemo(() => options.map(option => ({
         option,
         // Pin the full appearance per option: the main map's config may carry a
@@ -2811,7 +2861,7 @@ const AppearancePreviewGrid = ({ adapterConfig, ariaLabel, options, currentTheme
             showTraffic: false,
         }),
     })), [adapterConfig, options]);
-    return (jsx("div", { "aria-label": ariaLabel, className: "flex flex-wrap items-start gap-2 px-3 py-2", role: "radiogroup", children: derivedOptions.map(({ option, config }) => (jsx(AppearancePreview, { adapterConfig: config, "data-testid": `map-style-preview-${option.key}`, label: option.label, mapType: option.mapType, onSelect: () => onChange(option.theme, option.mapType), selected: option.theme === currentTheme && option.mapType === currentMapType }, option.key))) }));
+    return (jsx("div", { "aria-disabled": disabled || undefined, "aria-label": ariaLabel, className: "flex flex-wrap items-start gap-2 px-3 py-2", role: "radiogroup", children: derivedOptions.map(({ option, config }) => (jsx(AppearancePreview, { adapterConfig: config, "data-testid": `map-style-preview-${option.key}`, disabled: disabled, disabledReason: disabledReason, label: option.label, mapType: option.mapType, onSelect: () => onChange(option.theme, option.mapType), selected: option.theme === currentTheme && option.mapType === currentMapType }, option.key))) }));
 };
 
 // ============================================================================
@@ -3077,7 +3127,12 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
     }, [dispatch]);
     const previewOptions = useMemo(() => buildAppearanceOptions(themes, mapTypes, t), [themes, mapTypes, t]);
     const adapterConfig = api.adapterConfig;
+    // While a polygon is being drawn, a style change would recreate the map (Google) or
+    // reload the style (Mapbox) and drop the in-progress polygon, so the whole control is
+    // disabled with a reason. The persisted preferences keep displaying (ADR 0030).
+    const drawing = api.state.drawing === true;
     return useMemo(() => {
+        const drawingReason = drawing ? t("settings.mapStyle.disabledWhileDrawing") : undefined;
         const menuItems = [
             {
                 type: "custom",
@@ -3089,7 +3144,9 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
                 section: t("settings.mapStyle.title"),
                 render: () => (jsx(AppearancePreviewGrid, { adapterConfig: adapterConfig, 
                     // `SectionHeader` is role="presentation", so the header above names nothing.
-                    ariaLabel: t("settings.mapStyle.title"), currentMapType: localState.mapType, currentTheme: localState.theme, onChange: handleAppearanceChange, options: previewOptions })),
+                    ariaLabel: t("settings.mapStyle.title"), currentMapType: localState.mapType, currentTheme: localState.theme, 
+                    // Items disable on their own too: a flattened responsive menu has no trigger.
+                    disabled: drawing, disabledReason: drawingReason, onChange: handleAppearanceChange, options: previewOptions })),
             },
         ];
         const isSatelliteOrHybrid = localState.mapType === "satellite" || localState.mapType === "hybrid";
@@ -3103,6 +3160,8 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
                 id: "roads-overlay",
                 label: t("settings.mapStyle.roads"),
                 value: localState.showRoads,
+                disabled: drawing,
+                disabledReason: drawingReason,
                 onChange: handleRoadsChange,
                 "data-testid": "map-style-roads-toggle",
             });
@@ -3113,15 +3172,16 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
             // are off but keeps DISPLAYING the persisted preference — the setting is
             // still "on", it just cannot apply until roads return, and the tooltip says
             // so. Explicit "hybrid" always renders roads (and traffic), so the gate
-            // applies to "satellite" only.
+            // applies to "satellite" only. Drawing mode disables it as well (a traffic
+            // toggle recreates the Google map); the drawing reason wins while it lasts.
             const trafficBlockedByRoads = localState.mapType === "satellite" && !localState.showRoads;
             menuItems.push({
                 type: "toggle",
                 id: "traffic-overlay",
                 label: t("settings.mapStyle.traffic"),
                 value: localState.showTraffic,
-                disabled: trafficBlockedByRoads,
-                disabledReason: t("settings.mapStyle.trafficRequiresRoads"),
+                disabled: drawing || trafficBlockedByRoads,
+                disabledReason: drawingReason ?? t("settings.mapStyle.trafficRequiresRoads"),
                 onChange: handleTrafficChange,
                 "data-testid": "map-style-traffic-toggle",
             });
@@ -3133,12 +3193,15 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
                 icon: "Map",
                 label: t("settings.mapStyle.title"),
                 items: menuItems,
+                disabled: drawing,
+                disabledReason: drawingReason,
                 "data-testid": "map-style-menu",
             },
         ];
     }, [
         t,
         adapterConfig,
+        drawing,
         localState.mapType,
         localState.theme,
         localState.showRoads,
@@ -3388,10 +3451,20 @@ const useControls = (base, areas) => {
     }, [base, areas]);
 };
 
+/**
+ * Single dev-warning channel for react-map hooks (invalid data, invalid style, unhandled render errors).
+ * Messages are prefixed with the emitting hook, e.g. `[useHeatmap]`.
+ */
+const consoleWarnMap = (source, message, ...details) => {
+    // eslint-disable-next-line no-console -- Intentional: the one react-map warning channel; invalid input is dropped or defaulted and render errors without onError must stay visible
+    console.warn(`[${source}] ${message}`, ...details);
+};
+
 const noopUnsubscribe$1 = () => undefined;
 const subscribeNoop = () => noopUnsubscribe$1;
 const getIdle = () => "idle";
 const getEmpty = () => EMPTY_DRAW_VALUE;
+const getNoErrors = () => NO_DRAW_ERRORS;
 /**
  * Feature-facing hook for the optional drawing capability (ADR 0030).
  *
@@ -3423,13 +3496,56 @@ const useDraw = (api, options) => {
     const subscribe = useMemo(() => (port === undefined ? subscribeNoop : (listener) => port.subscribe(listener)), [port]);
     const getMode = useMemo(() => (port === undefined ? getIdle : () => port.getMode()), [port]);
     const getValue = useMemo(() => (port === undefined ? getEmpty : () => port.getValue()), [port]);
+    const getErrors = useMemo(() => (port === undefined ? getNoErrors : () => port.getErrors()), [port]);
     const mode = useSyncExternalStore(subscribe, getMode, getIdle);
     const value = useSyncExternalStore(subscribe, getValue, getEmpty);
+    const errors = useSyncExternalStore(subscribe, getErrors, getNoErrors);
+    const error = errors.engine ?? errors.value;
     // A disabled hook must not leave the map in a drawing mode it can no longer exit.
     useEffect(() => {
         if (!enabled)
             port?.setMode("idle");
     }, [enabled, port]);
+    const onError = options?.onError;
+    const onErrorRef = useRef(onError);
+    useEffect(() => {
+        onErrorRef.current = onError;
+    }, [onError]);
+    const errorHandler = useErrorHandlerOrNull();
+    // The app's error handler at most once per code per hook mount, like useHeatmap: a
+    // rejected stored boundary re-reports on every reconnect otherwise. A `value-rejected`
+    // verdict is reported too, deliberately: it is the only count of legacy boundaries
+    // the engine cannot render, kept until the Phase 2b pilot has run (ADR 0030).
+    const reportedCodesRef = useRef(new Set());
+    // Each slot reports once per new object: an engine error coming and going must not
+    // re-report the value verdict that stayed in place the whole time.
+    const reportedRef = useRef(NO_DRAW_ERRORS);
+    useEffect(() => {
+        const previous = reportedRef.current;
+        reportedRef.current = errors;
+        const fresh = [errors.engine, errors.value].flatMap(slot => slot !== null && slot !== previous.engine && slot !== previous.value ? [slot] : []);
+        for (const next of fresh) {
+            const detail = next.code === "value-rejected" ? next.reasons : next.cause;
+            if (errorHandler !== null && !reportedCodesRef.current.has(next.code)) {
+                reportedCodesRef.current.add(next.code);
+                errorHandler.captureException(new Error(`Map drawing failed: ${next.code}`, { cause: detail }), {
+                    level: "warning",
+                    fingerprint: ["react-map", "draw", next.code],
+                });
+            }
+            const handler = onErrorRef.current;
+            if (handler === undefined) {
+                consoleWarnMap("useDraw", `Drawing failed (${next.code}).`, detail);
+                continue;
+            }
+            try {
+                handler(next);
+            }
+            catch (handlerError) {
+                consoleWarnMap("useDraw", "onError threw.", handlerError, detail);
+            }
+        }
+    }, [errors, errorHandler]);
     const setMode = useCallback((nextMode) => {
         port?.setMode(nextMode);
     }, [port]);
@@ -3440,7 +3556,20 @@ const useDraw = (api, options) => {
         port?.setValue(EMPTY_DRAW_VALUE);
         port?.setMode("idle");
     }, [port]);
-    const hasPolygons = value.features.length > 0;
+    // Rejected features are in the value but not on the map, so there is nothing to
+    // select among them; the edit toggle follows what the map shows, whatever the
+    // engine slot says.
+    const rejectedCount = errors.value?.rejectedFeatureIndices.length ?? 0;
+    const hasPolygons = value.features.length - rejectedCount > 0;
+    const maxPolygons = options?.maxPolygons;
+    // A limit below one would lock the toggle with "clear the drawing" and nothing to clear.
+    const limitReached = maxPolygons !== undefined && maxPolygons >= 1 && value.features.length >= maxPolygons;
+    // Closing the polygon that reaches the limit ends polygon mode, so the next click
+    // on the map does not start another one.
+    useEffect(() => {
+        if (limitReached && mode === "polygon")
+            port?.setMode("idle");
+    }, [limitReached, mode, port]);
     const controls = useMemo(() => {
         if (!isSupported || !enabled)
             return [];
@@ -3452,6 +3581,10 @@ const useDraw = (api, options) => {
             section: t("controls.category.tools"),
             value: mode === "polygon",
             onChange: on => setMode(on ? "polygon" : "idle"),
+            // The limit effect above ends polygon mode as soon as it is reached, so the
+            // toggle is never both active and disabled for longer than one render.
+            disabled: limitReached,
+            disabledReason: limitReached ? t("draw.limitReached") : undefined,
             "data-testid": "map-draw-polygon-toggle",
         };
         const selectToggle = {
@@ -3477,17 +3610,19 @@ const useDraw = (api, options) => {
             "data-testid": "map-draw-clear-button",
         };
         return [polygonToggle, selectToggle, clearButton];
-    }, [clear, enabled, hasPolygons, isSupported, mode, setMode, t]);
+    }, [clear, enabled, hasPolygons, isSupported, limitReached, mode, setMode, t]);
     return useMemo(() => ({
         isSupported,
         isDrawing: mode !== "idle",
         mode,
         value,
+        error,
+        errors,
         setMode,
         setValue,
         clear,
         controls,
-    }), [clear, controls, isSupported, mode, setMode, setValue, value]);
+    }), [clear, controls, error, errors, isSupported, mode, setMode, setValue, value]);
 };
 
 /**
@@ -5994,15 +6129,6 @@ const useFitToContent = (api, handles, options) => {
     return useMemo(() => ({ hasFitted, isWaiting, fitNow }), [hasFitted, isWaiting, fitNow]);
 };
 
-/**
- * Single dev-warning channel for react-map hooks (invalid data, invalid style, unhandled render errors).
- * Messages are prefixed with the emitting hook, e.g. `[useHeatmap]`.
- */
-const consoleWarnMap = (source, message, ...details) => {
-    // eslint-disable-next-line no-console -- Intentional: the one react-map warning channel; invalid input is dropped or defaulted and render errors without onError must stay visible
-    console.warn(`[${source}] ${message}`, ...details);
-};
-
 /**
  * Converts consumer items into weighted GeoJSON `Point` features.
  *
@@ -12331,6 +12457,26 @@ const useShapeFillTiling = ({ api, handles, onFillGeometriesChange, onZIndexOver
     return useMemo(() => ({ queryAt, promoteFeature, clearPromotion, setDecorationHoverActive }), [queryAt, promoteFeature, clearPromotion, setDecorationHoverActive]);
 };
 
+const noop$1 = () => undefined;
+/** The handler set every consumer gets while drawing: nothing reaches the layers. */
+const INERT_LAYER_INTERACTION = {
+    hover: noop$1,
+    select: noop$1,
+    dblClick: noop$1,
+    click: undefined,
+    settleHover: noop$1,
+    decorationHover: noop$1,
+    decorationSelect: noop$1,
+};
+/**
+ * The one choke point for "drawing mode suppresses layer interaction" (ADR 0030).
+ * `<Layers>` builds its live handlers once, passes them through here, and hands the
+ * result to every consumer, so a new interaction path is gated by default instead
+ * of needing its own `if (drawing) return`. Programmatic `layers.select` and
+ * `layers.hover` calls from outside `<Layers>` are not affected.
+ */
+const useGatedLayerInteraction = (live, drawing) => useMemo(() => (drawing ? INERT_LAYER_INTERACTION : live), [drawing, live]);
+
 const applyPortalZIndex = (container, zIndex) => {
     container.style.zIndex = String(zIndex);
 };
@@ -12358,6 +12504,13 @@ const applyPortalZIndex = (container, zIndex) => {
  */
 const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
     const layerPort = useLayerPort();
+    // Drawing mode suppresses layer interaction (ADR 0030): shapes render non-interactive
+    // so Terra Draw gets every click without competing with existing polygons, and
+    // marker, cluster and decoration clicks and hovers are dropped so no panel opens and
+    // no hover state lingers under the draw tool. Every interaction consumer below gets
+    // its handlers from one gated set (`interaction`), so the rule lives in one place.
+    // Programmatic `layers.select` still works.
+    const drawing = api?.state.drawing === true;
     const [decorationLayers, setDecorationLayers] = useState([]);
     const [viewportStyleOverrides, setViewportStyleOverrides] = useState(new Map());
     const [fillGeometryOverrides, setFillGeometryOverrides] = useState(new Map());
@@ -12383,6 +12536,59 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
         // Fill tiling only fires on polygonal features — shapeType is always "polygon".
         layers.hover({ type: "shape", id: featureId, handleId, shapeType: "polygon" });
     }, [layers]);
+    // The remaining live handlers are defined here, before the hooks that consume them,
+    // so one gated set can feed every consumer. `setDomHoverActive` comes from
+    // `useEntityInteraction` further down, hence the ref.
+    const setDomHoverActiveRef = useRef(() => undefined);
+    const promoteFeatureRef = useRef(() => undefined);
+    const setDecorationHoverActiveRef = useRef(() => undefined);
+    const coordinatedSelect = useCallback((entity) => {
+        const hovered = hoveredEntityRef.current;
+        if (entity === null || hovered === null) {
+            layers.select(entity);
+            return;
+        }
+        // Default to the entity the click actually carried — it is the freshest,
+        // most direct signal of what the user hit, and it hit-tests per element
+        // for markers/clusters/routes. The single exception is a shape-on-shape
+        // conflict: the adapter resolves polygon clicks with its own z-order and
+        // full (unclipped) hit areas, so it cannot honor the fill-tiling ownership
+        // model that decides which overlapping site is visually on top (ADR-0021).
+        // There the settle-resolved hovered shape is the precise winner, so we
+        // trust it instead. This is also why an asset pill overlapping a site
+        // selects the asset: a marker click is never a shape, so it bypasses the
+        // exception even when a stale site shape is still the hovered entity.
+        if (entity.type === "shape" && hovered.type === "shape") {
+            layers.select(hovered);
+            return;
+        }
+        layers.select(entity);
+    }, [layers]);
+    const fitOnDblClick = useDblClickFit(api, layers.handles);
+    const handleDblClick = useCallback((entity) => {
+        onEntityDblClick?.(entity);
+        fitOnDblClick?.(entity);
+    }, [onEntityDblClick, fitOnDblClick]);
+    const coordinatedHover = useCallback((entity) => {
+        setDomHoverActiveRef.current(entity !== null);
+        setDecorationHoverActiveRef.current(entity !== null);
+        if (entity !== null && entity.type === "shape" && entity.handleId !== undefined) {
+            promoteFeatureRef.current(entity.handleId, entity.id);
+        }
+        layers.hover(entity);
+    }, [layers]);
+    const liveInteraction = useMemo(() => ({
+        hover: layers.hover,
+        select: coordinatedSelect,
+        dblClick: handleDblClick,
+        click: onEntityClick,
+        settleHover: onSettledHover,
+        decorationHover: coordinatedHover,
+        decorationSelect: layers.select,
+    }), [layers.hover, layers.select, coordinatedSelect, handleDblClick, onEntityClick, onSettledHover, coordinatedHover]);
+    // The one choke point for ADR 0030's interaction rule: while drawing, every consumer
+    // below receives handlers that do nothing (see useGatedLayerInteraction).
+    const interaction = useGatedLayerInteraction(liveInteraction, drawing);
     const suppressedFillIdsByHandle = useMemo(() => {
         const result = new Map();
         for (const [handleId, featureStyles] of viewportStyleOverrides) {
@@ -12401,16 +12607,14 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
         handles: layers.handles,
         onFillGeometriesChange: setFillGeometryOverrides,
         onZIndexOverridesChange: setZIndexOverrides,
-        onSettledHover,
+        onSettledHover: interaction.settleHover,
         selectedFeatureId: layers.interaction.selectedEntity?.type === "shape" ? String(layers.interaction.selectedEntity.id) : null,
         selectedHandleId: layers.interaction.selectedEntity?.type === "shape" ? layers.interaction.selectedEntity.handleId : null,
         suppressedFillIdsByHandle,
     });
-    const promoteFeatureRef = useRef(promoteFeature);
     useEffect(() => {
         promoteFeatureRef.current = promoteFeature;
     }, [promoteFeature]);
-    const setDecorationHoverActiveRef = useRef(setDecorationHoverActive);
     useEffect(() => {
         setDecorationHoverActiveRef.current = setDecorationHoverActive;
     }, [setDecorationHoverActive]);
@@ -12422,11 +12626,14 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
                 const fillOverrides = fillGeometryOverrides.get(handle.id);
                 const zIndexOverridesForHandle = zIndexOverrides.get(handle.id);
                 const queryShapesAt = (position) => queryAt(handle.id, position);
+                // The existing "none" mode removes the adapter's polygon hit-testing entirely.
+                const interactiveWhileDrawing = drawing ? { interactive: "none" } : {};
                 if (styleOverrides === undefined && fillOverrides === undefined && zIndexOverridesForHandle === undefined) {
-                    return { ...handle, queryShapesAt };
+                    return { ...handle, ...interactiveWhileDrawing, queryShapesAt };
                 }
                 return {
                     ...handle,
+                    ...interactiveWhileDrawing,
                     queryShapesAt,
                     ...(styleOverrides !== undefined ? { featureStyles: styleOverrides } : {}),
                     ...(fillOverrides !== undefined ? { featureFillGeometries: fillOverrides } : {}),
@@ -12440,50 +12647,35 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
                 return handle;
             return { ...handle, adaptiveResolution };
         });
-    }, [layers.handles, adaptiveByLayer, viewportStyleOverrides, fillGeometryOverrides, zIndexOverrides, queryAt]);
+    }, [
+        layers.handles,
+        adaptiveByLayer,
+        viewportStyleOverrides,
+        fillGeometryOverrides,
+        zIndexOverrides,
+        queryAt,
+        drawing,
+    ]);
     const { renderedSourceIds, hasSourceReadiness, readyRevision } = useLayerHandleSync(layerPort, enrichedHandles, layers.interaction, decorationLayers);
-    const coordinatedSelect = useCallback((entity) => {
-        const hovered = hoveredEntityRef.current;
-        if (entity === null || hovered === null) {
-            layers.select(entity);
-            return;
-        }
-        // Default to the entity the click actually carried — it is the freshest,
-        // most direct signal of what the user hit, and it hit-tests per element
-        // for markers/clusters/routes. The single exception is a shape-on-shape
-        // conflict: the adapter resolves polygon clicks with its own z-order and
-        // full (unclipped) hit areas, so it cannot honor the fill-tiling ownership
-        // model that decides which overlapping site is visually on top (ADR-0021).
-        // There the settle-resolved hovered shape is the precise winner, so we
-        // trust it instead. This is also why an asset pill overlapping a site
-        // selects the asset: a marker click is never a shape, so it bypasses the
-        // exception even when a stale site shape is still the hovered entity.
-        if (entity.type === "shape" && hovered.type === "shape") {
-            layers.select(hovered);
-            return;
-        }
-        layers.select(entity);
-    }, [layers]);
-    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,
+        hover: interaction.hover,
+        select: interaction.select,
+        dblClick: interaction.dblClick,
+        onClick: interaction.click,
     });
-    const coordinatedHover = useCallback((entity) => {
-        setDomHoverActive(entity !== null);
-        setDecorationHoverActiveRef.current(entity !== null);
-        if (entity !== null && entity.type === "shape" && entity.handleId !== undefined) {
-            promoteFeatureRef.current(entity.handleId, entity.id);
-        }
-        layers.hover(entity);
-    }, [layers, setDomHoverActive]);
+    useEffect(() => {
+        setDomHoverActiveRef.current = setDomHoverActive;
+    }, [setDomHoverActive]);
+    // Entering drawing mode drops whatever was hovered, so nothing stays highlighted
+    // under the draw tool; selection is left alone (the wizard may show the stored site).
+    useEffect(() => {
+        if (!drawing)
+            return;
+        setDomHoverActive(false);
+        setDecorationHoverActiveRef.current(false);
+        layers.hover(null);
+    }, [drawing, layers, setDomHoverActive]);
     const interactionMapStore = useShapeDecorations({
         onDecorationsChange: setDecorationLayers,
         onStyleOverridesChange: setViewportStyleOverrides,
@@ -12493,8 +12685,8 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
         hasSourceReadiness,
         readyRevision,
         interaction: layers.interaction,
-        select: layers.select,
-        hover: coordinatedHover,
+        select: interaction.decorationSelect,
+        hover: interaction.decorationHover,
     });
     const interactionMap = useSyncExternalStore(interactionMapStore.subscribe, interactionMapStore.getSnapshot, interactionMapStore.getSnapshot);
     const markerPortalStore = layerPort?.markerPortals ?? null;
@@ -12581,8 +12773,8 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
             }
             : itemState;
         const rendered = descriptor.renderFn(descriptor.sourceData, callState);
-        const interaction = interactionMap.get(sourceId);
-        return { descriptor, rendered, interaction, zIndex };
+        const decorationInteraction = interactionMap.get(sourceId);
+        return { descriptor, rendered, decorationInteraction, zIndex };
     };
     const portalEntries = [
         ...markerPortalDescriptors.map(d => buildPortalEntry(d, "marker")),
@@ -12596,9 +12788,9 @@ const Layers = ({ layers, api, onEntityClick, onEntityDblClick }) => {
     });
     if (portalEntries.length === 0)
         return null;
-    return (jsx(Fragment, { children: portalEntries.map(({ descriptor, rendered, interaction }) => {
-            if (interaction !== undefined) {
-                return createPortal(jsx(InteractiveDecoration, { entity: interaction.entity, hover: coordinatedHover, onClick: interaction.onClick, onDblClick: handleDblClick, onHover: interaction.onHover, select: layers.select, children: rendered }), descriptor.container, descriptor.key);
+    return (jsx(Fragment, { children: portalEntries.map(({ descriptor, rendered, decorationInteraction }) => {
+            if (decorationInteraction !== undefined) {
+                return createPortal(jsx(InteractiveDecoration, { entity: decorationInteraction.entity, hover: interaction.decorationHover, onClick: decorationInteraction.onClick, onDblClick: interaction.dblClick, onHover: decorationInteraction.onHover, select: interaction.decorationSelect, children: rendered }), descriptor.container, descriptor.key);
             }
             return createPortal(rendered, descriptor.container, descriptor.key);
         }) }));