@trackunit/react-map 0.2.171 → 0.2.173

package/index.cjs.js

@@ -40,7 +40,9 @@ var defaultTranslations = {
 	"settings.mapStyle.roadmap": "Road map",
 	"settings.mapStyle.roads": "Roads",
 	"settings.mapStyle.satellite": "Satellite",
-	"settings.mapStyle.title": "Map style"
+	"settings.mapStyle.title": "Map style",
+	"settings.mapStyle.traffic": "Traffic",
+	"settings.mapStyle.trafficRequiresRoads": "Turn on Roads to show traffic"
 };
 
 /** The translation namespace for this library */
@@ -1370,6 +1372,8 @@ const useMap = (adapterConfig) => {
         setMapType: adapter.setMapType.bind(adapter),
         setTheme: adapter.setTheme.bind(adapter),
         setShowRoads: adapter.setShowRoads.bind(adapter),
+        // Optional capability: stays undefined for adapters without traffic support
+        setShowTraffic: adapter.setShowTraffic?.bind(adapter),
     }), [adapter]);
     // Stable event subscription callback
     const on = react.useMemo(() => adapter.on.bind(adapter), [adapter]);
@@ -1846,9 +1850,12 @@ const BooleanButton = ({ config, overlaySide = undefined, resolved }) => {
     if (icon === undefined) {
         return null;
     }
-    const tooltipLabel = t("controls.boolean.tooltip", { label });
+    // 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 (jsxRuntime.jsx(StandaloneControlTooltip, { label: tooltipLabel, overlaySide: overlaySide, children: jsxRuntime.jsx(reactComponents.IconButton, { ...(useRightOverlay ? { ariaLabel: label } : { title: tooltipLabel }), "aria-pressed": value, className: className, "data-testid": dataTestId, icon: jsxRuntime.jsx(reactComponents.Icon, { name: icon, size: "small" }), onClick: () => onClickChange(!value), size: size, variant: value ? "primary" : "secondary" }) }));
+    return (jsxRuntime.jsx(StandaloneControlTooltip, { label: tooltipLabel, overlaySide: overlaySide, children: jsxRuntime.jsx(reactComponents.IconButton, { ...(useRightOverlay ? { ariaLabel: label } : { title: tooltipLabel }), "aria-pressed": value, className: className, "data-testid": dataTestId, disabled: config.disabled ?? false, icon: jsxRuntime.jsx(reactComponents.Icon, { name: icon, size: "small" }), onClick: () => onClickChange(!value), size: size, variant: value ? "primary" : "secondary" }) }));
 };
 
 /**
@@ -2090,6 +2097,13 @@ const usePopoverPlacement = (triggerRef, containerRef, options = {}) => {
     return placement;
 };
 
+const cvaMenuBooleanItemLabel = cssClassVarianceUtilities.cva({
+    base: ["flex", "items-center", "gap-2", "text-sm", "font-medium"],
+    variants: {
+        disabled: { true: "text-neutral-400", false: "text-neutral-700" },
+    },
+    defaultVariants: { disabled: false },
+});
 /**
  * Shared menu layout for boolean controls (toggle and checkbox).
  * Renders: [label] [icon] ...space... [children]
@@ -2097,22 +2111,30 @@ const usePopoverPlacement = (triggerRef, containerRef, options = {}) => {
  * The caller provides the specific input control (ToggleSwitch or Checkbox)
  * as children.
  *
+ * The disabled reason renders as a tooltip on the row itself, not on the
+ * input: the full-width dimmed row is what users hover, and a natively
+ * disabled input (checkbox case) suppresses its own hover events anyway.
+ *
  * @internal
  */
-const MenuBooleanItem = ({ children, className, "data-testid": dataTestId, icon = undefined, label, }) => (jsxRuntime.jsxs("label", { className: cvaControlMenuItemBase({
-        className: [
-            "flex",
-            "cursor-pointer",
-            "items-center",
-            "justify-between",
-            "gap-3",
-            "hover:bg-neutral-50",
-            "active:bg-neutral-100",
-            "transition-colors",
-            "duration-150",
-            className,
-        ],
-    }), "data-testid": dataTestId, children: [jsxRuntime.jsxs("span", { className: "flex items-center gap-2 text-sm font-medium text-neutral-700", children: [label, icon !== undefined ? jsxRuntime.jsx(reactComponents.Icon, { className: "text-neutral-500", name: icon, size: "small" }) : null] }), children] }));
+const MenuBooleanItem = ({ children, className, "data-testid": dataTestId, disabled = false, disabledReason = undefined, disabledReasonId = undefined, icon = undefined, label, }) => {
+    const row = (jsxRuntime.jsxs("label", { className: cvaControlMenuItemBase({
+            className: [
+                "flex",
+                "items-center",
+                "justify-between",
+                "gap-3",
+                "transition-colors",
+                "duration-150",
+                ...(disabled ? ["cursor-not-allowed"] : ["cursor-pointer", "hover:bg-neutral-50", "active:bg-neutral-100"]),
+                className,
+            ],
+        }), "data-testid": dataTestId, children: [jsxRuntime.jsxs("span", { className: cvaMenuBooleanItemLabel({ disabled }), children: [label, icon !== undefined ? jsxRuntime.jsx(reactComponents.Icon, { className: "text-neutral-500", name: icon, size: "small" }) : null] }), disabled && disabledReason !== undefined ? (jsxRuntime.jsx("span", { className: "sr-only", id: disabledReasonId, children: disabledReason })) : null, children] }));
+    if (disabled && disabledReason !== undefined) {
+        return jsxRuntime.jsx(reactComponents.Tooltip, { label: disabledReason, children: row });
+    }
+    return row;
+};
 
 /**
  * Renders a checkbox control within a menu context.
@@ -2120,7 +2142,13 @@ const MenuBooleanItem = ({ children, className, "data-testid": dataTestId, icon
  *
  * @internal
  */
-const MenuCheckbox = ({ config, resolved }) => (jsxRuntime.jsx(MenuBooleanItem, { className: config.className, "data-testid": config["data-testid"], icon: resolved.icon, label: config.label, children: jsxRuntime.jsx(reactFormComponents.Checkbox, { checked: config.value, onChange: e => config.onChange(e.target.checked) }) }));
+const MenuCheckbox = ({ config, resolved }) => {
+    // See MenuToggle: the row tooltip is hover-only, so the input also points
+    // aria-describedby at a visually hidden copy of the reason.
+    const disabledReasonId = react.useId();
+    const isDisabledWithReason = config.disabled === true && config.disabledReason !== undefined;
+    return (jsxRuntime.jsx(MenuBooleanItem, { className: config.className, "data-testid": config["data-testid"], disabled: config.disabled, disabledReason: config.disabledReason, disabledReasonId: disabledReasonId, icon: resolved.icon, label: config.label, children: jsxRuntime.jsx(reactFormComponents.Checkbox, { "aria-describedby": isDisabledWithReason ? disabledReasonId : undefined, checked: config.value, disabled: config.disabled ?? false, onChange: e => config.onChange(e.target.checked) }) }));
+};
 
 /**
  * Renders a toggle control within a menu context.
@@ -2128,7 +2156,18 @@ const MenuCheckbox = ({ config, resolved }) => (jsxRuntime.jsx(MenuBooleanItem,
  *
  * @internal
  */
-const MenuToggle = ({ config, resolved }) => (jsxRuntime.jsx(MenuBooleanItem, { className: config.className, "data-testid": config["data-testid"], icon: resolved.icon, label: config.label, children: jsxRuntime.jsx(reactFormComponents.ToggleSwitch, { onChange: toggled => config.onChange(toggled), showInputFocus: false, size: "small", tabIndex: -1, toggled: config.value }) }));
+const MenuToggle = ({ config, resolved }) => {
+    // The reason must also reach non-mouse users: the row tooltip is hover-only,
+    // so the input additionally points aria-describedby at a visually hidden copy.
+    const disabledReasonId = react.useId();
+    const isDisabledWithReason = config.disabled === true && config.disabledReason !== undefined;
+    return (jsxRuntime.jsx(MenuBooleanItem, { className: config.className, "data-testid": config["data-testid"], disabled: config.disabled, disabledReason: config.disabledReason, disabledReasonId: disabledReasonId, icon: resolved.icon, label: config.label, children: jsxRuntime.jsx(reactFormComponents.ToggleSwitch, { "aria-describedby": isDisabledWithReason ? disabledReasonId : undefined, 
+            // readOnly, not disabled: same dimmed visual and blocked interaction, but the
+            // input stays focusable and is announced as dimmed instead of losing
+            // focusability and being skipped in some AT browse modes (see the `disabled`
+            // JSDoc on BooleanControlFields for the toggle/checkbox split).
+            onChange: toggled => config.onChange(toggled), readOnly: config.disabled ?? false, showInputFocus: false, size: "small", tabIndex: -1, toggled: config.value }) }));
+};
 
 /**
  * Renders a button control within a menu context.
@@ -2775,19 +2814,26 @@ const AppearancePreviewGrid = ({ adapterConfig, ariaLabel, options, currentTheme
 // Version
 // ============================================================================
 /**
- * Increment this number to invalidate stored appearance settings in localStorage
- * and reset all users to defaults.
+ * Increment this number when the persisted appearance shape changes, and add a
+ * matching migration step in useMapAppearanceControls so stored settings are
+ * upgraded instead of reset. (v2: added showTraffic.)
  */
-const APPEARANCE_SETTINGS_VERSION = 1;
+const APPEARANCE_SETTINGS_VERSION = 2;
 // ============================================================================
 // Persisted Appearance Schema (extends core mapAppearanceSchema with version)
 // ============================================================================
 const persistedAppearanceSchema = reactMapAdapterShared.mapAppearanceSchema.extend({
+    // Required here (unlike the core schema, where it is optional for external
+    // compatibility): the v2 migration guarantees stored data carries the key,
+    // and useLocalStorageReducer needs an input = output schema.
+    showTraffic: zod.z.boolean(),
     version: zod.z.literal(APPEARANCE_SETTINGS_VERSION),
 });
 /** Default persisted appearance when nothing is stored */
 const DEFAULT_PERSISTED_APPEARANCE = {
     ...reactMapAdapterShared.DEFAULT_MAP_APPEARANCE,
+    // The core field is optional (absent = false); persisted state requires it
+    showTraffic: reactMapAdapterShared.DEFAULT_MAP_APPEARANCE.showTraffic ?? false,
     version: APPEARANCE_SETTINGS_VERSION,
 };
 /** Reducer for persisted appearance state */
@@ -2799,6 +2845,8 @@ const appearanceReducer = (state, action) => {
             return { ...state, mapType: action.payload };
         case "setShowRoads":
             return { ...state, showRoads: action.payload };
+        case "setShowTraffic":
+            return { ...state, showTraffic: action.payload };
         default: {
             throw new Error(`${action} is not known`);
         }
@@ -2807,12 +2855,39 @@ const appearanceReducer = (state, action) => {
 
 const DEFAULT_THEMES = ["light", "dark"];
 const DEFAULT_MAP_TYPES = ["roadmap", "satellite"];
-const APPEARANCE_STORAGE_VERSION = 1;
+/**
+ * The v1 persisted shape, frozen as a literal. Deliberately NOT derived from
+ * the live mapAppearanceSchema: deriving would make every future appearance
+ * field retroactively required on v1-era data, failing the parse below and
+ * resetting exactly the users the migration exists to carry over.
+ */
+const appearanceV1Schema = zod.z.object({
+    theme: zod.z.enum(["light", "dark"]),
+    mapType: zod.z.enum(["roadmap", "satellite", "hybrid"]),
+    showRoads: zod.z.boolean(),
+    version: zod.z.literal(1),
+});
 const appearanceMigrationV1 = {
-    version: APPEARANCE_STORAGE_VERSION,
+    version: 1,
+    migrate: data => {
+        const result = appearanceV1Schema.safeParse(data);
+        // Pass unrecognized data through: it may already be a newer shape
+        // (stored without a version envelope), which the next step recognizes.
+        return result.success ? result.data : data;
+    },
+};
+/** v2 added the showTraffic preference; carry v1 settings over instead of resetting them */
+const appearanceMigrationV2 = {
+    version: APPEARANCE_SETTINGS_VERSION,
     migrate: data => {
-        const result = persistedAppearanceSchema.safeParse(data);
-        return result.success ? result.data : DEFAULT_PERSISTED_APPEARANCE;
+        const current = persistedAppearanceSchema.safeParse(data);
+        if (current.success) {
+            return current.data;
+        }
+        const v1 = appearanceV1Schema.safeParse(data);
+        return v1.success
+            ? { ...v1.data, showTraffic: false, version: APPEARANCE_SETTINGS_VERSION }
+            : DEFAULT_PERSISTED_APPEARANCE;
     },
 };
 const themeToTranslationKey = (theme) => {
@@ -2886,6 +2961,8 @@ const buildAppearanceOptions = (themes, mapTypes, t) => {
  * Returns an array with a single `MenuControlConfig` that contains:
  * - A custom item with a grid of live tiny map previews
  * - A toggle item for roads overlay (when satellite/hybrid is selected)
+ * - A toggle item for live traffic (when the adapter supports it; disabled on
+ *   satellite while roads are off, since traffic only renders on hybrid)
  *
  * @example
  * ```tsx
@@ -2906,19 +2983,35 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
     const themes = appearanceOptions?.themes ?? DEFAULT_THEMES;
     const mapTypes = appearanceOptions?.mapTypes ?? DEFAULT_MAP_TYPES;
     const showRoadsToggle = appearanceOptions?.roads !== false;
+    // Traffic is an optional adapter capability: no setShowTraffic action means no toggle
+    const setShowTraffic = api.actions.setShowTraffic;
+    // `traffic: false` opts the whole surface out of traffic, not just out of the toggle:
+    // with a shared persistence key another surface may have stored showTraffic: true,
+    // and rendering traffic here with no toggle to turn it off would trap the user.
+    const trafficOptedOut = appearanceOptions?.traffic === false;
+    const showTrafficToggle = !trafficOptedOut && setShowTraffic !== undefined;
     const [localState, dispatch] = reactComponents.useLocalStorageReducer({
         key: persistenceKey,
         defaultState: DEFAULT_PERSISTED_APPEARANCE,
-        migration: { version: APPEARANCE_STORAGE_VERSION, steps: [appearanceMigrationV1] },
+        migration: { version: APPEARANCE_SETTINGS_VERSION, steps: [appearanceMigrationV1, appearanceMigrationV2] },
         reducer: appearanceReducer,
         schema: persistedAppearanceSchema,
     });
-    // Push localStorage state to the adapter when it changes
+    // Push localStorage state to the adapter when it changes. Traffic is pushed as the
+    // raw preference: the adapter itself suppresses rendering where the provider cannot
+    // draw traffic (plain satellite, low zoom), so the preference survives roads/mapType
+    // changes and is restored when they change back.
     reactComponents.useWatch({
-        value: { mapType: localState.mapType, showRoads: localState.showRoads, theme: localState.theme },
-        onChange: ({ mapType, showRoads, theme }) => {
+        value: {
+            mapType: localState.mapType,
+            showRoads: localState.showRoads,
+            showTraffic: trafficOptedOut ? false : localState.showTraffic,
+            theme: localState.theme,
+        },
+        onChange: ({ mapType, showRoads, showTraffic, theme }) => {
             void api.actions.setMapType(mapType);
             void api.actions.setShowRoads(showRoads);
+            void setShowTraffic?.(showTraffic);
             void api.actions.setTheme(theme);
         },
         immediate: true,
@@ -2939,6 +3032,14 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
             if (appearance.showRoads !== localState.showRoads) {
                 dispatch({ type: "setShowRoads", payload: appearance.showRoads });
             }
+            // Only sync traffic back where the toggle is live. An unsupported adapter (and
+            // an opted-out surface) reports showTraffic: false forever, and syncing that
+            // back would wipe a preference stored by another map surface sharing the same
+            // persistence key.
+            const adapterShowTraffic = appearance.showTraffic ?? false;
+            if (showTrafficToggle && adapterShowTraffic !== localState.showTraffic) {
+                dispatch({ type: "setShowTraffic", payload: adapterShowTraffic });
+            }
         },
         skip: !api.state.isReady,
     });
@@ -2949,6 +3050,9 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
     const handleRoadsChange = react.useCallback((value) => {
         dispatch({ type: "setShowRoads", payload: value });
     }, [dispatch]);
+    const handleTrafficChange = react.useCallback((value) => {
+        dispatch({ type: "setShowTraffic", payload: value });
+    }, [dispatch]);
     const previewOptions = react.useMemo(() => buildAppearanceOptions(themes, mapTypes, t), [themes, mapTypes, t]);
     const adapterConfig = api.adapterConfig;
     return react.useMemo(() => {
@@ -2967,8 +3071,12 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
             },
         ];
         const isSatelliteOrHybrid = localState.mapType === "satellite" || localState.mapType === "hybrid";
-        if (showRoadsToggle && isSatelliteOrHybrid) {
-            menuItems.push({ type: "separator" }, {
+        const includeRoadsToggle = showRoadsToggle && isSatelliteOrHybrid;
+        if (includeRoadsToggle || showTrafficToggle) {
+            menuItems.push({ type: "separator" });
+        }
+        if (includeRoadsToggle) {
+            menuItems.push({
                 type: "toggle",
                 id: "roads-overlay",
                 label: t("settings.mapStyle.roads"),
@@ -2977,6 +3085,25 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
                 "data-testid": "map-style-roads-toggle",
             });
         }
+        if (showTrafficToggle) {
+            // On satellite, traffic can only render on top of the roads overlay (Google
+            // renders no traffic on plain SATELLITE); the toggle is disabled while roads
+            // 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.
+            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"),
+                onChange: handleTrafficChange,
+                "data-testid": "map-style-traffic-toggle",
+            });
+        }
         return [
             {
                 type: "menu",
@@ -2993,10 +3120,13 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
         localState.mapType,
         localState.theme,
         localState.showRoads,
+        localState.showTraffic,
         handleAppearanceChange,
         handleRoadsChange,
+        handleTrafficChange,
         previewOptions,
         showRoadsToggle,
+        showTrafficToggle,
     ]);
 };
 
@@ -12586,7 +12716,7 @@ const INITIAL_STATE = {
     isIdle: true,
     isReady: true,
     initializationFailed: false,
-    appearance: { theme: "light", mapType: "roadmap", showRoads: false },
+    appearance: { theme: "light", mapType: "roadmap", showRoads: false, showTraffic: false },
     tileSize: 256,
 };
 const noop = () => undefined;
@@ -12635,6 +12765,7 @@ const mockMapApi = (overrides) => {
         setMapType: resolvedVoid,
         setTheme: resolvedVoid,
         setShowRoads: resolvedVoid,
+        setShowTraffic: resolvedVoid,
         ...(overrides?.actions ?? {}),
     };
     const adapterConfig = {
@@ -12661,6 +12792,7 @@ const mockMapApi = (overrides) => {
             setMapType: resolvedVoid,
             setTheme: resolvedVoid,
             setShowRoads: resolvedVoid,
+            setShowTraffic: resolvedVoid,
             on: () => noopUnsubscribe,
             notifyInitializationFailed: noop,
             destroy: noop,

package/index.esm.js

@@ -39,7 +39,9 @@ var defaultTranslations = {
 	"settings.mapStyle.roadmap": "Road map",
 	"settings.mapStyle.roads": "Roads",
 	"settings.mapStyle.satellite": "Satellite",
-	"settings.mapStyle.title": "Map style"
+	"settings.mapStyle.title": "Map style",
+	"settings.mapStyle.traffic": "Traffic",
+	"settings.mapStyle.trafficRequiresRoads": "Turn on Roads to show traffic"
 };
 
 /** The translation namespace for this library */
@@ -1369,6 +1371,8 @@ const useMap = (adapterConfig) => {
         setMapType: adapter.setMapType.bind(adapter),
         setTheme: adapter.setTheme.bind(adapter),
         setShowRoads: adapter.setShowRoads.bind(adapter),
+        // Optional capability: stays undefined for adapters without traffic support
+        setShowTraffic: adapter.setShowTraffic?.bind(adapter),
     }), [adapter]);
     // Stable event subscription callback
     const on = useMemo(() => adapter.on.bind(adapter), [adapter]);
@@ -1845,9 +1849,12 @@ const BooleanButton = ({ config, overlaySide = undefined, resolved }) => {
     if (icon === undefined) {
         return null;
     }
-    const tooltipLabel = t("controls.boolean.tooltip", { label });
+    // 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, icon: jsx(Icon, { name: icon, size: "small" }), onClick: () => onClickChange(!value), size: size, variant: value ? "primary" : "secondary" }) }));
+    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" }) }));
 };
 
 /**
@@ -2089,6 +2096,13 @@ const usePopoverPlacement = (triggerRef, containerRef, options = {}) => {
     return placement;
 };
 
+const cvaMenuBooleanItemLabel = cva({
+    base: ["flex", "items-center", "gap-2", "text-sm", "font-medium"],
+    variants: {
+        disabled: { true: "text-neutral-400", false: "text-neutral-700" },
+    },
+    defaultVariants: { disabled: false },
+});
 /**
  * Shared menu layout for boolean controls (toggle and checkbox).
  * Renders: [label] [icon] ...space... [children]
@@ -2096,22 +2110,30 @@ const usePopoverPlacement = (triggerRef, containerRef, options = {}) => {
  * The caller provides the specific input control (ToggleSwitch or Checkbox)
  * as children.
  *
+ * The disabled reason renders as a tooltip on the row itself, not on the
+ * input: the full-width dimmed row is what users hover, and a natively
+ * disabled input (checkbox case) suppresses its own hover events anyway.
+ *
  * @internal
  */
-const MenuBooleanItem = ({ children, className, "data-testid": dataTestId, icon = undefined, label, }) => (jsxs("label", { className: cvaControlMenuItemBase({
-        className: [
-            "flex",
-            "cursor-pointer",
-            "items-center",
-            "justify-between",
-            "gap-3",
-            "hover:bg-neutral-50",
-            "active:bg-neutral-100",
-            "transition-colors",
-            "duration-150",
-            className,
-        ],
-    }), "data-testid": dataTestId, children: [jsxs("span", { className: "flex items-center gap-2 text-sm font-medium text-neutral-700", children: [label, icon !== undefined ? jsx(Icon, { className: "text-neutral-500", name: icon, size: "small" }) : null] }), children] }));
+const MenuBooleanItem = ({ children, className, "data-testid": dataTestId, disabled = false, disabledReason = undefined, disabledReasonId = undefined, icon = undefined, label, }) => {
+    const row = (jsxs("label", { className: cvaControlMenuItemBase({
+            className: [
+                "flex",
+                "items-center",
+                "justify-between",
+                "gap-3",
+                "transition-colors",
+                "duration-150",
+                ...(disabled ? ["cursor-not-allowed"] : ["cursor-pointer", "hover:bg-neutral-50", "active:bg-neutral-100"]),
+                className,
+            ],
+        }), "data-testid": dataTestId, children: [jsxs("span", { className: cvaMenuBooleanItemLabel({ disabled }), children: [label, icon !== undefined ? jsx(Icon, { className: "text-neutral-500", name: icon, size: "small" }) : null] }), disabled && disabledReason !== undefined ? (jsx("span", { className: "sr-only", id: disabledReasonId, children: disabledReason })) : null, children] }));
+    if (disabled && disabledReason !== undefined) {
+        return jsx(Tooltip, { label: disabledReason, children: row });
+    }
+    return row;
+};
 
 /**
  * Renders a checkbox control within a menu context.
@@ -2119,7 +2141,13 @@ const MenuBooleanItem = ({ children, className, "data-testid": dataTestId, icon
  *
  * @internal
  */
-const MenuCheckbox = ({ config, resolved }) => (jsx(MenuBooleanItem, { className: config.className, "data-testid": config["data-testid"], icon: resolved.icon, label: config.label, children: jsx(Checkbox, { checked: config.value, onChange: e => config.onChange(e.target.checked) }) }));
+const MenuCheckbox = ({ config, resolved }) => {
+    // See MenuToggle: the row tooltip is hover-only, so the input also points
+    // aria-describedby at a visually hidden copy of the reason.
+    const disabledReasonId = useId();
+    const isDisabledWithReason = config.disabled === true && config.disabledReason !== undefined;
+    return (jsx(MenuBooleanItem, { className: config.className, "data-testid": config["data-testid"], disabled: config.disabled, disabledReason: config.disabledReason, disabledReasonId: disabledReasonId, icon: resolved.icon, label: config.label, children: jsx(Checkbox, { "aria-describedby": isDisabledWithReason ? disabledReasonId : undefined, checked: config.value, disabled: config.disabled ?? false, onChange: e => config.onChange(e.target.checked) }) }));
+};
 
 /**
  * Renders a toggle control within a menu context.
@@ -2127,7 +2155,18 @@ const MenuCheckbox = ({ config, resolved }) => (jsx(MenuBooleanItem, { className
  *
  * @internal
  */
-const MenuToggle = ({ config, resolved }) => (jsx(MenuBooleanItem, { className: config.className, "data-testid": config["data-testid"], icon: resolved.icon, label: config.label, children: jsx(ToggleSwitch, { onChange: toggled => config.onChange(toggled), showInputFocus: false, size: "small", tabIndex: -1, toggled: config.value }) }));
+const MenuToggle = ({ config, resolved }) => {
+    // The reason must also reach non-mouse users: the row tooltip is hover-only,
+    // so the input additionally points aria-describedby at a visually hidden copy.
+    const disabledReasonId = useId();
+    const isDisabledWithReason = config.disabled === true && config.disabledReason !== undefined;
+    return (jsx(MenuBooleanItem, { className: config.className, "data-testid": config["data-testid"], disabled: config.disabled, disabledReason: config.disabledReason, disabledReasonId: disabledReasonId, icon: resolved.icon, label: config.label, children: jsx(ToggleSwitch, { "aria-describedby": isDisabledWithReason ? disabledReasonId : undefined, 
+            // readOnly, not disabled: same dimmed visual and blocked interaction, but the
+            // input stays focusable and is announced as dimmed instead of losing
+            // focusability and being skipped in some AT browse modes (see the `disabled`
+            // JSDoc on BooleanControlFields for the toggle/checkbox split).
+            onChange: toggled => config.onChange(toggled), readOnly: config.disabled ?? false, showInputFocus: false, size: "small", tabIndex: -1, toggled: config.value }) }));
+};
 
 /**
  * Renders a button control within a menu context.
@@ -2774,19 +2813,26 @@ const AppearancePreviewGrid = ({ adapterConfig, ariaLabel, options, currentTheme
 // Version
 // ============================================================================
 /**
- * Increment this number to invalidate stored appearance settings in localStorage
- * and reset all users to defaults.
+ * Increment this number when the persisted appearance shape changes, and add a
+ * matching migration step in useMapAppearanceControls so stored settings are
+ * upgraded instead of reset. (v2: added showTraffic.)
  */
-const APPEARANCE_SETTINGS_VERSION = 1;
+const APPEARANCE_SETTINGS_VERSION = 2;
 // ============================================================================
 // Persisted Appearance Schema (extends core mapAppearanceSchema with version)
 // ============================================================================
 const persistedAppearanceSchema = mapAppearanceSchema.extend({
+    // Required here (unlike the core schema, where it is optional for external
+    // compatibility): the v2 migration guarantees stored data carries the key,
+    // and useLocalStorageReducer needs an input = output schema.
+    showTraffic: z.boolean(),
     version: z.literal(APPEARANCE_SETTINGS_VERSION),
 });
 /** Default persisted appearance when nothing is stored */
 const DEFAULT_PERSISTED_APPEARANCE = {
     ...DEFAULT_MAP_APPEARANCE,
+    // The core field is optional (absent = false); persisted state requires it
+    showTraffic: DEFAULT_MAP_APPEARANCE.showTraffic ?? false,
     version: APPEARANCE_SETTINGS_VERSION,
 };
 /** Reducer for persisted appearance state */
@@ -2798,6 +2844,8 @@ const appearanceReducer = (state, action) => {
             return { ...state, mapType: action.payload };
         case "setShowRoads":
             return { ...state, showRoads: action.payload };
+        case "setShowTraffic":
+            return { ...state, showTraffic: action.payload };
         default: {
             throw new Error(`${action} is not known`);
         }
@@ -2806,12 +2854,39 @@ const appearanceReducer = (state, action) => {
 
 const DEFAULT_THEMES = ["light", "dark"];
 const DEFAULT_MAP_TYPES = ["roadmap", "satellite"];
-const APPEARANCE_STORAGE_VERSION = 1;
+/**
+ * The v1 persisted shape, frozen as a literal. Deliberately NOT derived from
+ * the live mapAppearanceSchema: deriving would make every future appearance
+ * field retroactively required on v1-era data, failing the parse below and
+ * resetting exactly the users the migration exists to carry over.
+ */
+const appearanceV1Schema = z.object({
+    theme: z.enum(["light", "dark"]),
+    mapType: z.enum(["roadmap", "satellite", "hybrid"]),
+    showRoads: z.boolean(),
+    version: z.literal(1),
+});
 const appearanceMigrationV1 = {
-    version: APPEARANCE_STORAGE_VERSION,
+    version: 1,
+    migrate: data => {
+        const result = appearanceV1Schema.safeParse(data);
+        // Pass unrecognized data through: it may already be a newer shape
+        // (stored without a version envelope), which the next step recognizes.
+        return result.success ? result.data : data;
+    },
+};
+/** v2 added the showTraffic preference; carry v1 settings over instead of resetting them */
+const appearanceMigrationV2 = {
+    version: APPEARANCE_SETTINGS_VERSION,
     migrate: data => {
-        const result = persistedAppearanceSchema.safeParse(data);
-        return result.success ? result.data : DEFAULT_PERSISTED_APPEARANCE;
+        const current = persistedAppearanceSchema.safeParse(data);
+        if (current.success) {
+            return current.data;
+        }
+        const v1 = appearanceV1Schema.safeParse(data);
+        return v1.success
+            ? { ...v1.data, showTraffic: false, version: APPEARANCE_SETTINGS_VERSION }
+            : DEFAULT_PERSISTED_APPEARANCE;
     },
 };
 const themeToTranslationKey = (theme) => {
@@ -2885,6 +2960,8 @@ const buildAppearanceOptions = (themes, mapTypes, t) => {
  * Returns an array with a single `MenuControlConfig` that contains:
  * - A custom item with a grid of live tiny map previews
  * - A toggle item for roads overlay (when satellite/hybrid is selected)
+ * - A toggle item for live traffic (when the adapter supports it; disabled on
+ *   satellite while roads are off, since traffic only renders on hybrid)
  *
  * @example
  * ```tsx
@@ -2905,19 +2982,35 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
     const themes = appearanceOptions?.themes ?? DEFAULT_THEMES;
     const mapTypes = appearanceOptions?.mapTypes ?? DEFAULT_MAP_TYPES;
     const showRoadsToggle = appearanceOptions?.roads !== false;
+    // Traffic is an optional adapter capability: no setShowTraffic action means no toggle
+    const setShowTraffic = api.actions.setShowTraffic;
+    // `traffic: false` opts the whole surface out of traffic, not just out of the toggle:
+    // with a shared persistence key another surface may have stored showTraffic: true,
+    // and rendering traffic here with no toggle to turn it off would trap the user.
+    const trafficOptedOut = appearanceOptions?.traffic === false;
+    const showTrafficToggle = !trafficOptedOut && setShowTraffic !== undefined;
     const [localState, dispatch] = useLocalStorageReducer({
         key: persistenceKey,
         defaultState: DEFAULT_PERSISTED_APPEARANCE,
-        migration: { version: APPEARANCE_STORAGE_VERSION, steps: [appearanceMigrationV1] },
+        migration: { version: APPEARANCE_SETTINGS_VERSION, steps: [appearanceMigrationV1, appearanceMigrationV2] },
         reducer: appearanceReducer,
         schema: persistedAppearanceSchema,
     });
-    // Push localStorage state to the adapter when it changes
+    // Push localStorage state to the adapter when it changes. Traffic is pushed as the
+    // raw preference: the adapter itself suppresses rendering where the provider cannot
+    // draw traffic (plain satellite, low zoom), so the preference survives roads/mapType
+    // changes and is restored when they change back.
     useWatch({
-        value: { mapType: localState.mapType, showRoads: localState.showRoads, theme: localState.theme },
-        onChange: ({ mapType, showRoads, theme }) => {
+        value: {
+            mapType: localState.mapType,
+            showRoads: localState.showRoads,
+            showTraffic: trafficOptedOut ? false : localState.showTraffic,
+            theme: localState.theme,
+        },
+        onChange: ({ mapType, showRoads, showTraffic, theme }) => {
             void api.actions.setMapType(mapType);
             void api.actions.setShowRoads(showRoads);
+            void setShowTraffic?.(showTraffic);
             void api.actions.setTheme(theme);
         },
         immediate: true,
@@ -2938,6 +3031,14 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
             if (appearance.showRoads !== localState.showRoads) {
                 dispatch({ type: "setShowRoads", payload: appearance.showRoads });
             }
+            // Only sync traffic back where the toggle is live. An unsupported adapter (and
+            // an opted-out surface) reports showTraffic: false forever, and syncing that
+            // back would wipe a preference stored by another map surface sharing the same
+            // persistence key.
+            const adapterShowTraffic = appearance.showTraffic ?? false;
+            if (showTrafficToggle && adapterShowTraffic !== localState.showTraffic) {
+                dispatch({ type: "setShowTraffic", payload: adapterShowTraffic });
+            }
         },
         skip: !api.state.isReady,
     });
@@ -2948,6 +3049,9 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
     const handleRoadsChange = useCallback((value) => {
         dispatch({ type: "setShowRoads", payload: value });
     }, [dispatch]);
+    const handleTrafficChange = useCallback((value) => {
+        dispatch({ type: "setShowTraffic", payload: value });
+    }, [dispatch]);
     const previewOptions = useMemo(() => buildAppearanceOptions(themes, mapTypes, t), [themes, mapTypes, t]);
     const adapterConfig = api.adapterConfig;
     return useMemo(() => {
@@ -2966,8 +3070,12 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
             },
         ];
         const isSatelliteOrHybrid = localState.mapType === "satellite" || localState.mapType === "hybrid";
-        if (showRoadsToggle && isSatelliteOrHybrid) {
-            menuItems.push({ type: "separator" }, {
+        const includeRoadsToggle = showRoadsToggle && isSatelliteOrHybrid;
+        if (includeRoadsToggle || showTrafficToggle) {
+            menuItems.push({ type: "separator" });
+        }
+        if (includeRoadsToggle) {
+            menuItems.push({
                 type: "toggle",
                 id: "roads-overlay",
                 label: t("settings.mapStyle.roads"),
@@ -2976,6 +3084,25 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
                 "data-testid": "map-style-roads-toggle",
             });
         }
+        if (showTrafficToggle) {
+            // On satellite, traffic can only render on top of the roads overlay (Google
+            // renders no traffic on plain SATELLITE); the toggle is disabled while roads
+            // 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.
+            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"),
+                onChange: handleTrafficChange,
+                "data-testid": "map-style-traffic-toggle",
+            });
+        }
         return [
             {
                 type: "menu",
@@ -2992,10 +3119,13 @@ const useMapAppearanceControls = ({ api, options: appearanceOptions, persistence
         localState.mapType,
         localState.theme,
         localState.showRoads,
+        localState.showTraffic,
         handleAppearanceChange,
         handleRoadsChange,
+        handleTrafficChange,
         previewOptions,
         showRoadsToggle,
+        showTrafficToggle,
     ]);
 };
 
@@ -12585,7 +12715,7 @@ const INITIAL_STATE = {
     isIdle: true,
     isReady: true,
     initializationFailed: false,
-    appearance: { theme: "light", mapType: "roadmap", showRoads: false },
+    appearance: { theme: "light", mapType: "roadmap", showRoads: false, showTraffic: false },
     tileSize: 256,
 };
 const noop = () => undefined;
@@ -12634,6 +12764,7 @@ const mockMapApi = (overrides) => {
         setMapType: resolvedVoid,
         setTheme: resolvedVoid,
         setShowRoads: resolvedVoid,
+        setShowTraffic: resolvedVoid,
         ...(overrides?.actions ?? {}),
     };
     const adapterConfig = {
@@ -12660,6 +12791,7 @@ const mockMapApi = (overrides) => {
             setMapType: resolvedVoid,
             setTheme: resolvedVoid,
             setShowRoads: resolvedVoid,
+            setShowTraffic: resolvedVoid,
             on: () => noopUnsubscribe,
             notifyInitializationFailed: noop,
             destroy: noop,

package/package.json

@@ -1,22 +1,22 @@
 {
   "name": "@trackunit/react-map",
-  "version": "0.2.171",
+  "version": "0.2.173",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "engines": {
     "node": ">=24.x"
   },
   "dependencies": {
-    "@trackunit/react-components": "3.2.0",
-    "@trackunit/css-class-variance-utilities": "2.0.19",
-    "@trackunit/react-form-components": "2.7.11",
-    "@trackunit/react-core-hooks": "1.22.4",
-    "@trackunit/geo-json-utils": "1.15.52",
-    "@trackunit/i18n-library-translation": "2.5.4",
+    "@trackunit/react-components": "3.2.2",
+    "@trackunit/css-class-variance-utilities": "2.0.21",
+    "@trackunit/react-form-components": "2.7.13",
+    "@trackunit/react-core-hooks": "1.22.6",
+    "@trackunit/geo-json-utils": "1.15.54",
+    "@trackunit/i18n-library-translation": "2.5.6",
     "react-minimal-pie-chart": "^8.4.0",
-    "@trackunit/react-map-adapter-shared": "0.0.137",
-    "@trackunit/react-map-color-utils": "0.0.112",
-    "@trackunit/ui-design-tokens": "1.15.40",
+    "@trackunit/react-map-adapter-shared": "0.0.139",
+    "@trackunit/react-map-color-utils": "0.0.114",
+    "@trackunit/ui-design-tokens": "1.15.41",
     "@floating-ui/react": "^0.26.25",
     "es-toolkit": "^1.39.10",
     "tailwind-merge": "^2.0.0",

package/src/appearance/appearanceTypes.d.ts

@@ -2,25 +2,29 @@ import type { AdapterConfig } from "@trackunit/react-map-adapter-shared";
 import { z } from "zod";
 import { type MapActions, type MapStatus, type MapTheme, type MapType } from "../core/types";
 /**
- * Increment this number to invalidate stored appearance settings in localStorage
- * and reset all users to defaults.
+ * Increment this number when the persisted appearance shape changes, and add a
+ * matching migration step in useMapAppearanceControls so stored settings are
+ * upgraded instead of reset. (v2: added showTraffic.)
  */
-export declare const APPEARANCE_SETTINGS_VERSION = 1;
+export declare const APPEARANCE_SETTINGS_VERSION = 2;
 export declare const persistedAppearanceSchema: z.ZodObject<{
     theme: z.ZodEnum<["light", "dark"]>;
     mapType: z.ZodEnum<["roadmap", "satellite", "hybrid"]>;
     showRoads: z.ZodBoolean;
 } & {
-    version: z.ZodLiteral<1>;
+    showTraffic: z.ZodBoolean;
+    version: z.ZodLiteral<2>;
 }, "strip", z.ZodTypeAny, {
     mapType: "roadmap" | "satellite" | "hybrid";
     theme: "light" | "dark";
-    version: 1;
+    showTraffic: boolean;
+    version: 2;
     showRoads: boolean;
 }, {
     mapType: "roadmap" | "satellite" | "hybrid";
     theme: "light" | "dark";
-    version: 1;
+    showTraffic: boolean;
+    version: 2;
     showRoads: boolean;
 }>;
 /** Appearance state persisted to localStorage (MapAppearance + migration version) */
@@ -39,7 +43,11 @@ type SetShowRoadsAction = Readonly<{
     type: "setShowRoads";
     payload: boolean;
 }>;
-export type AppearanceAction = Readonly<SetThemeAction | SetMapTypeAction | SetShowRoadsAction>;
+type SetShowTrafficAction = Readonly<{
+    type: "setShowTraffic";
+    payload: boolean;
+}>;
+export type AppearanceAction = Readonly<SetThemeAction | SetMapTypeAction | SetShowRoadsAction | SetShowTrafficAction>;
 /** Reducer for persisted appearance state */
 export declare const appearanceReducer: (state: PersistedAppearance, action: AppearanceAction) => PersistedAppearance;
 /** Configuration for which appearance options to show in the settings panel */
@@ -50,6 +58,8 @@ export type AppearanceOptions = Readonly<{
     mapTypes?: ReadonlyArray<MapType>;
     /** Whether to show the roads toggle when satellite/hybrid is selected. Default: true */
     roads?: boolean;
+    /** Whether to show the traffic toggle when the adapter supports traffic. Default: true */
+    traffic?: boolean;
 }>;
 /**
  * Narrowed API surface that useMapAppearanceControls actually needs.

package/src/appearance/useMapAppearanceControls.d.ts

@@ -11,6 +11,8 @@ import { type UseMapAppearanceControlsParams } from "./appearanceTypes";
  * Returns an array with a single `MenuControlConfig` that contains:
  * - A custom item with a grid of live tiny map previews
  * - A toggle item for roads overlay (when satellite/hybrid is selected)
+ * - A toggle item for live traffic (when the adapter supports it; disabled on
+ *   satellite while roads are off, since traffic only renders on hybrid)
  *
  * @example
  * ```tsx

package/src/controls/renderers/boolean/MenuBooleanItem.d.ts

@@ -4,6 +4,15 @@ type MenuBooleanItemProps = Readonly<{
     children: ReactNode;
     className?: string;
     "data-testid"?: string;
+    disabled?: boolean;
+    /** Why the control is disabled; shown as a tooltip over the whole row */
+    disabledReason?: string;
+    /**
+     * Id for the visually hidden copy of the reason, so callers can point the
+     * input's aria-describedby at it (tooltips are hover-only: invisible to
+     * touch, keyboard, and screen readers).
+     */
+    disabledReasonId?: string;
     icon?: IconName;
     label: string;
 }>;
@@ -14,7 +23,11 @@ type MenuBooleanItemProps = Readonly<{
  * The caller provides the specific input control (ToggleSwitch or Checkbox)
  * as children.
  *
+ * The disabled reason renders as a tooltip on the row itself, not on the
+ * input: the full-width dimmed row is what users hover, and a natively
+ * disabled input (checkbox case) suppresses its own hover events anyway.
+ *
  * @internal
  */
-export declare const MenuBooleanItem: ({ children, className, "data-testid": dataTestId, icon, label, }: MenuBooleanItemProps) => import("react").JSX.Element;
+export declare const MenuBooleanItem: ({ children, className, "data-testid": dataTestId, disabled, disabledReason, disabledReasonId, icon, label, }: MenuBooleanItemProps) => import("react").JSX.Element;
 export {};

package/src/controls/types.d.ts

@@ -87,6 +87,24 @@ type BooleanControlFields = Readonly<{
     label: string;
     value: boolean;
     onChange: (value: boolean) => void;
+    /**
+     * Disables interaction and dims the control while keeping it visible,
+     * for options that only apply in the current context (e.g. the traffic
+     * toggle on satellite while roads are off).
+     *
+     * Rendering differs deliberately per control: menu toggles map this to
+     * ToggleSwitch's `readOnly` (announced as dimmed, keeps its switch role;
+     * native `disabled` would drop focusability and get skipped in some AT
+     * browse modes), while checkboxes use native `disabled` because Checkbox
+     * forwards `readOnly` to an input type="checkbox", where it is inert and
+     * does not block label-dispatched activation.
+     */
+    disabled?: boolean;
+    /**
+     * Why the control is disabled, shown as a tooltip on the disabled control
+     * so users learn what unblocks it (e.g. "Turn on Roads to show traffic").
+     */
+    disabledReason?: string;
     /**
      * State-dependent icons shown when the control is on or off (standalone only).
      * Both must be provided together — this prevents partial-icon bugs where

package/src/core/types.d.ts

@@ -79,6 +79,19 @@ export type MapActions = Readonly<{
      * @returns Promise that resolves when the change is applied
      */
     setShowRoads: (showRoads: boolean) => Promise<void>;
+    /**
+     * Set whether live traffic conditions are shown on the map.
+     *
+     * Undefined when the adapter does not support traffic rendering — UI such as
+     * the built-in map-style control hides its traffic toggle in that case.
+     * The value records the user's preference; the adapter may still suppress
+     * rendering where the provider cannot draw traffic (plain satellite) or
+     * below TRAFFIC_MIN_ZOOM.
+     *
+     * @param showTraffic - Whether traffic should be shown
+     * @returns Promise that resolves when the change is applied
+     */
+    setShowTraffic?: (showTraffic: boolean) => Promise<void>;
 }>;
 /**
  * The API object returned as the second element of the useMap tuple.

package/migrations/entry.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../../../libs/react/map/migrations/entry.ts"],"names":[],"mappings":"","sourcesContent":["export {};\n"]}