@trackunit/react-map 0.2.224 → 0.2.225

package/package.json

@@ -1,23 +1,23 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.2.224",
+  "version": "0.2.225",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "3.10.3",
-    "@trackunit/css-class-variance-utilities": "2.5.1",
-    "@trackunit/react-form-components": "2.12.4",
-    "@trackunit/react-core-hooks": "1.27.2",
-    "@trackunit/geo-json-utils": "1.20.1",
-    "@trackunit/i18n-library-translation": "2.10.2",
+    "@trackunit/react-components": "3.11.0",
+    "@trackunit/css-class-variance-utilities": "2.6.0",
+    "@trackunit/react-form-components": "2.13.0",
+    "@trackunit/react-core-hooks": "1.28.0",
+    "@trackunit/geo-json-utils": "1.21.0",
+    "@trackunit/i18n-library-translation": "2.11.0",
     "react-minimal-pie-chart": "^8.4.0",
-    "@trackunit/react-map-adapter-shared": "0.0.166",
-    "@trackunit/react-map-color-utils": "0.0.140",
-    "@trackunit/shared-utils": "1.21.1",
-    "@trackunit/ui-design-tokens": "1.20.1",
+    "@trackunit/react-map-adapter-shared": "0.0.167",
+    "@trackunit/react-map-color-utils": "0.0.141",
+    "@trackunit/shared-utils": "1.22.0",
+    "@trackunit/ui-design-tokens": "1.21.0",
     "@floating-ui/react": "^0.26.25",
     "es-toolkit": "^1.52.0",
     "tailwind-merge": "^3.7.0",

package/src/appearance/AppearancePreview.d.ts

@@ -1,4 +1,5 @@
 import type { AdapterConfig } from "@trackunit/react-map-adapter-shared";
+import type { ReactElement } from "react";
 import type { MapType } from "../core/types";
 type AppearancePreviewProps = Readonly<{
     /** Derived adapter config for this preview (with the correct theme baked in) */
@@ -11,6 +12,14 @@ type AppearancePreviewProps = Readonly<{
     selected: boolean;
     /** Called when this preview is clicked */
     onSelect: () => void;
+    /**
+     * Keeps the cell visible but not selectable. The radio stays focusable (not
+     * `disabled`) so keyboard and screen-reader users still reach it and hear the
+     * reason; selection is blocked in the change handler instead.
+     */
+    disabled?: boolean;
+    /** Why the cell is disabled: shown as a tooltip and announced through `aria-describedby`. */
+    disabledReason?: string;
     /** Test ID */
     "data-testid"?: string;
 }>;
@@ -23,5 +32,5 @@ type AppearancePreviewProps = Readonly<{
  *
  * @internal
  */
-export declare const AppearancePreview: ({ adapterConfig, mapType, label, selected, onSelect, "data-testid": dataTestId, }: AppearancePreviewProps) => import("react").JSX.Element;
+export declare const AppearancePreview: ({ adapterConfig, mapType, label, selected, onSelect, disabled, disabledReason, "data-testid": dataTestId, }: AppearancePreviewProps) => ReactElement;
 export {};

package/src/appearance/AppearancePreviewGrid.d.ts

@@ -14,6 +14,13 @@ type AppearancePreviewGridProps = Readonly<{
     currentMapType: MapType;
     /** Called when user selects an appearance option */
     onChange: (theme: MapTheme, mapType: MapType) => void;
+    /**
+     * Keeps the grid visible but inert, for example while drawing (a style change
+     * would recreate the map and drop an in-progress polygon, ADR 0030).
+     */
+    disabled?: boolean;
+    /** Why the grid is disabled, shown as each option's tooltip. */
+    disabledReason?: string;
 }>;
 /**
  * Grid of tiny live map previews for selecting map appearance.
@@ -27,5 +34,5 @@ type AppearancePreviewGridProps = Readonly<{
  *
  * @internal
  */
-export declare const AppearancePreviewGrid: ({ adapterConfig, ariaLabel, options, currentTheme, currentMapType, onChange, }: AppearancePreviewGridProps) => import("react").JSX.Element;
+export declare const AppearancePreviewGrid: ({ adapterConfig, ariaLabel, options, currentTheme, currentMapType, onChange, disabled, disabledReason, }: AppearancePreviewGridProps) => import("react").JSX.Element;
 export {};

package/src/controls/renderers/menu/utils/menuTooltipLabel.d.ts

@@ -0,0 +1,3 @@
+import type { MenuControlConfig } from "../../../types";
+/** A disabled menu's tooltip explains what unblocks it rather than what it opens. */
+export declare const menuTooltipLabel: (config: Pick<MenuControlConfig, "label" | "disabled" | "disabledReason">) => string;

package/src/controls/renderers/shared/StandaloneControlTooltip.d.ts

@@ -5,10 +5,19 @@ type StandaloneControlTooltipProps = Readonly<{
     disabled?: boolean;
     label: string;
     overlaySide?: ControlOverlaySide;
+    /**
+     * Wrap on every overlay side, not only the right one. Needed when the child
+     * cannot show the tooltip itself: `IconButton` switches its own `title` tooltip
+     * off while the button is disabled, so a disabled control's reason would never
+     * appear. Browsers still deliver hover to the disabled button, and the wrapper
+     * listens for it.
+     */
+    required?: boolean;
 }>;
 /**
- * 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.
+ * 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.
  */
-export declare const StandaloneControlTooltip: ({ children, disabled, label, overlaySide, }: StandaloneControlTooltipProps) => ReactNode;
+export declare const StandaloneControlTooltip: ({ children, disabled, label, overlaySide, required, }: StandaloneControlTooltipProps) => ReactNode;
 export {};

package/src/controls/renderers/shared/useDisabledReason.d.ts

@@ -0,0 +1,28 @@
+import { type ReactElement } from "react";
+type UseDisabledReasonInput = Readonly<{
+    disabled?: boolean;
+    disabledReason?: string;
+}>;
+export type UseDisabledReasonResult = Readonly<{
+    /** True when the control is disabled and has a reason to show. */
+    showsReason: true;
+    /** The reason, for the tooltip. */
+    reason: string;
+    /** Value for the control's `aria-describedby`. */
+    describedBy: string;
+    /** The visually hidden copy of the reason; render it next to the control. */
+    description: ReactElement;
+}> | Readonly<{
+    showsReason: false;
+    reason: undefined;
+    describedBy: undefined;
+    description: null;
+}>;
+/**
+ * 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).
+ */
+export declare const useDisabledReason: ({ disabled, disabledReason, }: UseDisabledReasonInput) => UseDisabledReasonResult;
+export {};

package/src/controls/renderers/shared/utils/isStandaloneTooltipWrapped.d.ts

@@ -0,0 +1,8 @@
+import type { ControlOverlaySide } from "../../../controlOverlaySide";
+/**
+ * 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.
+ */
+export declare const isStandaloneTooltipWrapped: (overlaySide: ControlOverlaySide | undefined, required: boolean) => boolean;

package/src/controls/types.d.ts

@@ -195,6 +195,15 @@ export type MenuControlConfig = BaseControlConfig<"menu"> & Readonly<{
     label: string;
     /** Items in the menu */
     items: ReadonlyArray<MenuItemConfig>;
+    /**
+     * Disables the trigger while keeping it visible, for menus whose every option is
+     * unavailable in the current context (the map-style menu while drawing). Only the
+     * standalone trigger reads this: when responsive collapsing flattens the menu into
+     * the overflow menu, its items render on their own, so disable them too.
+     */
+    disabled?: boolean;
+    /** Why the menu is disabled, shown as the trigger's tooltip instead of `label`. */
+    disabledReason?: string;
 }>;
 /**
  * Context passed to custom control render functions.

package/src/draw/useDraw.d.ts

@@ -1,4 +1,4 @@
-import { type DrawMode, type DrawValue } from "@trackunit/react-map-adapter-shared";
+import { type DrawError, type DrawErrors, type DrawMode, type DrawValue } from "@trackunit/react-map-adapter-shared";
 import type { ControlConfig } from "../controls/types";
 import type { MapApi } from "../core/types";
 /** Minimal slice of `MapApi` consumed by `useDraw`. */
@@ -11,6 +11,25 @@ export type UseDrawOptions = Readonly<{
      * the hook, for example while a feature flag is off. Default `true`.
      */
     enabled?: boolean;
+    /**
+     * Most polygons the drawing may hold. Once `value` holds that many, the "Draw
+     * polygon" toggle is disabled with a reason and polygon mode ends by itself after
+     * the polygon that reaches the limit is closed; editing and clearing stay
+     * available. The library itself is multi-polygon: a site wizard sets `1` here
+     * (ADR 0030, decided 19 Oct 2026). Features the engine rejected count too, so a
+     * stored boundary that needs a redraw is cleared first. Values below one are
+     * ignored. Default: no limit.
+     */
+    maxPolygons?: number;
+    /**
+     * Called once per error the drawing reports (same shape as `useHeatmap`): the
+     * engine failed to load or update, or part of a committed value could not be
+     * rendered (`value-rejected`, with the indices of the features that are not on the
+     * map). The committed `value` is never changed by an error. Without a handler the
+     * error is logged with `console.warn`; it is reported to the app's error handler
+     * either way, when the host provides one, at most once per code per mount.
+     */
+    onError?: (error: DrawError) => void;
 }>;
 export type UseDrawReturn = Readonly<{
     /** False when the adapter has no drawing capability; `controls` is then empty. */
@@ -24,6 +43,19 @@ export type UseDrawReturn = Readonly<{
      * polygon, and when `setValue` is called.
      */
     value: DrawValue;
+    /**
+     * The error to show now, or null: the engine failure while one is pending, else the
+     * verdict on the committed value. Read `errors` when both matter.
+     */
+    error: DrawError | null;
+    /**
+     * Both error slots. `engine` clears when the engine recovers; `value` (a
+     * `value-rejected` verdict with the indices of the features that are not on the
+     * map) clears when the committed geometry changes. A pending engine failure never
+     * hides the value verdict, so a "redraw this boundary" notice can stay up while
+     * the engine reloads. See `UseDrawOptions.onError`.
+     */
+    errors: DrawErrors;
     /** Enter a drawing mode; `"idle"` ends drawing. */
     setMode: (mode: DrawMode) => void;
     /** Replace the committed polygons (controlled-input style). */

package/src/index.d.ts

@@ -17,7 +17,7 @@ export type { UseControlsAreas } from "./controls/types";
 export { useControls } from "./controls/useControls";
 export { useDefaultControls, type UseDefaultControlsOptions } from "./controls/useDefaultControls";
 export { EMPTY_DRAW_VALUE } from "@trackunit/react-map-adapter-shared";
-export type { DrawMode, DrawPort, DrawValue } from "@trackunit/react-map-adapter-shared";
+export type { DrawEngineError, DrawError, DrawErrorCode, DrawErrors, DrawMode, DrawPort, DrawValue, DrawValueRejection, } from "@trackunit/react-map-adapter-shared";
 export { useDraw, type UseDrawOptions, type UseDrawReturn } from "./draw/useDraw";
 export { DEFAULT_APPEARANCE_PERSISTENCE_KEY } from "./appearance/appearanceTypes";
 export type { AppearanceAction, AppearanceOption, AppearanceOptions, MapAppearanceApi, PersistedAppearance, UseMapAppearanceControlsParams, } from "./appearance/appearanceTypes";

package/src/layers/utils/useGatedLayerInteraction.d.ts

@@ -0,0 +1,25 @@
+import type { Entity } from "@trackunit/react-map-adapter-shared";
+/**
+ * Every handler an interaction consumer inside `<Layers>` receives: the adapter event
+ * path (`hover`, `select`, `dblClick`, `click`), the fill-tiling settle channel
+ * (`settleHover`) and the DOM decoration path (`decorationHover`, `decorationSelect`).
+ */
+export type LayerInteractionHandlers = Readonly<{
+    hover: (entity: Entity | null) => void;
+    select: (entity: Entity | null) => void;
+    dblClick: (entity: Entity) => void;
+    click: ((entity: Entity) => void) | undefined;
+    settleHover: (handleId: string, featureId: string) => void;
+    decorationHover: (entity: Entity | null) => void;
+    decorationSelect: (entity: Entity | null) => void;
+}>;
+/** The handler set every consumer gets while drawing: nothing reaches the layers. */
+export declare const INERT_LAYER_INTERACTION: LayerInteractionHandlers;
+/**
+ * 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.
+ */
+export declare const useGatedLayerInteraction: (live: LayerInteractionHandlers, drawing: boolean) => LayerInteractionHandlers;