@accelint/map-toolkit 0.0.2 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# @accelint/map-toolkit
+
+## 0.2.0
+
+### Minor Changes
+
+- b4d1b9b: Add map mode system with authorization flow for managing interaction modes.
+
+  **New Features:**
+  - `MapProvider` component for managing map mode state with instance isolation
+  - `useMapMode()` hook for accessing and requesting mode changes
+  - Authorization flow for resolving ownership conflicts when switching modes
+  - Event bus integration for decoupled mode change communication
+  - Support for multiple independent map instances with isolated state
+
+  **API:**
+  - `MapProvider` component (internal to `BaseMap`)
+  - `useMapMode(id)` hook for UI components
+  - `BaseMap` now requires `id` prop for instance identification
+  - Observable store pattern using React's `useSyncExternalStore`
+
+- 998dee6: add deckgl-layer-text for default text styling
+
+### Patch Changes
+
+- 303b61f: Pins the dependency version of Deck.gl to 9.1.14. We are not yet able to support 9.2.
+- 0d697fa: Fixed definitions in package files for longhand repository definitions, while disabling the option in syncpack that changed it.
+- a8b8de2: Update README content in map-toolkit
+- f99f294: Updated syncpack and realigned all packages for dependency versions
+- 935b8e5: Updated the package names in the Constellation configuration file.
+
+## 0.1.0
+
+### Minor Changes
+
+- 24e2def: Open-source the deckgl-layer-symbol package. Adds support for rendering MIL-STD-2525 symbologies as a Deck.gl layer.
+- 5f45f43: Adds base-map component and DeckGL onClick and onHover event emitters. The example story shows how to use the @accelint/bus/react useOn hook to subscribe to the emitted events.
+- 405d875: Introduced basic implementation for storybook for map-toolkit, including a decorator for deckGL for new stories.
+
+### Patch Changes
+
+- 64280a7: - Released `@accelint/constellation-tracker` - A tool that helps maintain catalog-info.yaml files for Constellation integration
+  - Ensures all packages include catalog-info.yaml in their published files for better discoverability and integration with Constellation
+  - Provides automated tracking and updating of component metadata across the project
+  - Enhanced package metadata to support better integration with internal tooling
+
+## 0.0.2
+
+### Patch Changes
+
+- 56d5af8: Initialization of Map Toolkit (MapTK) library

package/README.md

@@ -1,32 +1,108 @@
 # @accelint/map-toolkit
 
+A collection of components and utilities to simplify visualizing and working with geospatial data. This toolkit provides ready-to-use map components and layers for deck.gl and MapLibre, making it easier to build interactive mapping applications.
+
+## What is Map Toolkit?
+
+Map Toolkit is a comprehensive library that provides:
+
+- **Deck.gl Components**: Pre-configured layers and components for rendering geospatial data, including symbol layers for military symbology (MIL-STD-2525)
+- **MapLibre Integration**: Components and utilities for working with MapLibre GL JS
+- **React Support**: React-friendly components with hooks and utilities via `@deckgl-fiber-renderer`
+- **Geospatial Utilities**: Helper functions and decorators for common mapping tasks
+
+The package is organized by technology (e.g., `deckgl/`, `maplibre/`) with feature-specific exports, allowing you to import only what you need.
+
 ## Installation
 
 ```sh
 npm install @accelint/map-toolkit
 ```
 
-## Structure
+### Optional Dependencies
 
-- standard-toolkit/packages/map-toolkit
-  - src
-    - deckgl
-      - [feature folders]
-      - index.ts (generated by indexer)
+To minimize bundle size, Map Toolkit uses optional dependencies. Install only the technologies you need:
 
-    - [other technology folders, ex: maplibre]
+```sh
+# For deck.gl features
+pnpm i --save-optional @deck.gl/core @deck.gl/layers @deck.gl/extensions
 
-    - ~~index.ts~~ (do not create a root level barrel, there should only be tech level barrels, but also support individual feature exports in package.json)
+# For React/deck.gl features
+pnpm i --save-optional react @deckgl-fiber-renderer/dom
 
-  - [misc files, ex: package.json, etc]
+# For MapLibre features
+pnpm i --save-optional maplibre-gl
 
-## Installing New Packages
-Similar to DesignTK, all features within a technology MUST work together, to help guarantee this we will not publish them as individual packages, but as part of a single package.
+# For military symbology
+pnpm i --save-optional milsymbol
+```
 
-In an effort to reduce the number of unnecessary dependencies being installed by consumers, we are opting to use `optionalDependencies`, instead of `peerDependencies`. This allows us for more flexibility, but also requires us to be more mindful of how these packages are being used.
+## Usage
 
-### Example
-`pnpm i --save-optional deckgl@latest`
+Import components from their technology-specific paths:
 
-## Usage
-- Under Construction 🚧
+```ts
+// Deck.gl components
+import { SymbolLayer } from '@accelint/map-toolkit/deckgl';
+
+// MapLibre components
+import { /* components */ } from '@accelint/map-toolkit/maplibre';
+
+// React/Fiber components
+import { /* components */ } from '@accelint/map-toolkit/deckgl/fiber';
+```
+
+For detailed examples and interactive demos, see the [Storybook documentation](https://map-toolkit.accelint.io/?path=/docs/deckgl-symbol-layer--docs).
+
+## Running Locally
+
+To work on Map Toolkit locally:
+
+```bash
+# Install dependencies
+pnpm i
+
+# Run Storybook development server
+pnpm --filter=@accelint/map-toolkit preview
+
+# Build the package
+pnpm --filter=@accelint/map-toolkit build
+```
+
+If you encounter errors, try running `pnpm build` after installing dependencies, then run the preview command again.
+
+## Testing
+
+Run the test suite:
+
+```bash
+# Run tests once
+pnpm --filter=@accelint/map-toolkit test
+
+# Run tests in watch mode
+pnpm --filter=@accelint/map-toolkit test:watch
+
+# Run benchmarks
+pnpm --filter=@accelint/map-toolkit bench
+```
+
+## Documentation
+
+- **[Storybook](https://map-toolkit.accelint.io/?path=/docs/deckgl-symbol-layer--docs)** - Interactive component documentation and examples
+- **[Changelog](./CHANGELOG.md)** - Release notes and version history
+
+## Package Structure
+
+```
+packages/map-toolkit/
+  src/
+    deckgl/           # Deck.gl layers and components
+    maplibre/         # MapLibre utilities and components
+    decorators/       # Shared decorators and utilities
+```
+
+Each technology folder exports its components via barrel files, and individual features are also exported via `package.json` for granular imports.
+
+## License
+
+Apache-2.0

package/catalog-info.yaml

@@ -0,0 +1,44 @@
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: accelint_map-toolkit
+  title: Accelint Map Toolkit
+  description: >-
+    A collection of components and utilities to simplify visualizing and working
+    with geospatial data.
+
+
+    Dependencies:
+
+    accelint_biome-config@1.0.2, accelint_bus@2.0.0,
+    accelint_constellation-tracker@1.0.1, accelint_core@0.5.0,
+    accelint_design-toolkit@7.0.0, accelint_typescript-config@0.1.4,
+    accelint_vitest-config@0.1.5
+  annotations:
+    backstage.io/edit-url: https://github.com/gohypergiant/standard-toolkit/blob/main/packages/map-toolkit/catalog-info.yaml
+    backstage.io/techdocs-ref: dir:.
+    package/version: 0.2.0
+    github.com/project-slug: gohypergiant/standard-toolkit
+  links:
+    - url: https://github.com/gohypergiant/standard-toolkit/tree/main/packages/map-toolkit
+      title: Documentation
+      icon: docs
+      type: documentation
+  tags:
+    - deckgl
+    - geospatial
+    - map-tk
+    - maplibre
+spec:
+  type: library
+  lifecycle: production
+  owner: group:default/pathfinder
+  dependsOn:
+    - component:accelint_biome-config
+    - component:accelint_bus
+    - component:accelint_constellation-tracker
+    - component:accelint_core
+    - component:accelint_design-toolkit
+    - component:accelint_typescript-config
+    - component:accelint_vitest-config

package/dist/deckgl/base-map/constants.d.ts

@@ -0,0 +1,16 @@
+declare const BASE_MAP_STYLE = "https://tiles.basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
+declare const PARAMETERS: {
+    depthWriteEnabled: boolean;
+    depthCompare: string;
+    depthBias: number;
+    blend: boolean;
+    depthTest: boolean;
+    blendColorSrcFactor: string;
+    blendColorDstFactor: string;
+    blendAlphaSrcFactor: string;
+    blendAlphaDstFactor: string;
+    blendColorOperation: string;
+    blendAlphaOperation: string;
+};
+
+export { BASE_MAP_STYLE, PARAMETERS };

package/dist/deckgl/base-map/constants.js

@@ -0,0 +1,18 @@
+const BASE_MAP_STYLE = "https://tiles.basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
+const PARAMETERS = {
+  depthWriteEnabled: true,
+  depthCompare: "always",
+  depthBias: 0,
+  blend: true,
+  depthTest: false,
+  blendColorSrcFactor: "src-alpha",
+  blendColorDstFactor: "one-minus-src-alpha",
+  blendAlphaSrcFactor: "one",
+  blendAlphaDstFactor: "one-minus-src-alpha",
+  blendColorOperation: "add",
+  blendAlphaOperation: "add"
+};
+
+export { BASE_MAP_STYLE, PARAMETERS };
+//# sourceMappingURL=constants.js.map
+//# sourceMappingURL=constants.js.map

package/dist/deckgl/base-map/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/deckgl/base-map/constants.ts"],"names":[],"mappings":"AAaO,MAAM,cAAA,GACX;AAEK,MAAM,UAAA,GAAa;AAAA,EACxB,iBAAA,EAAmB,IAAA;AAAA,EACnB,YAAA,EAAc,QAAA;AAAA,EACd,SAAA,EAAW,CAAA;AAAA,EACX,KAAA,EAAO,IAAA;AAAA,EACP,SAAA,EAAW,KAAA;AAAA,EACX,mBAAA,EAAqB,WAAA;AAAA,EACrB,mBAAA,EAAqB,qBAAA;AAAA,EACrB,mBAAA,EAAqB,KAAA;AAAA,EACrB,mBAAA,EAAqB,qBAAA;AAAA,EACrB,mBAAA,EAAqB,KAAA;AAAA,EACrB,mBAAA,EAAqB;AACvB","file":"constants.js","sourcesContent":["// __private-exports\n/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport const BASE_MAP_STYLE =\n  'https://tiles.basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json';\n\nexport const PARAMETERS = {\n  depthWriteEnabled: true,\n  depthCompare: 'always',\n  depthBias: 0,\n  blend: true,\n  depthTest: false,\n  blendColorSrcFactor: 'src-alpha',\n  blendColorDstFactor: 'one-minus-src-alpha',\n  blendAlphaSrcFactor: 'one',\n  blendAlphaDstFactor: 'one-minus-src-alpha',\n  blendColorOperation: 'add',\n  blendAlphaOperation: 'add',\n};\n"]}

package/dist/deckgl/base-map/events.d.ts

@@ -0,0 +1,7 @@
+declare const MapEventsNamespace = "map";
+declare const MapEvents: {
+    readonly click: "map:click";
+    readonly hover: "map:hover";
+};
+
+export { MapEvents, MapEventsNamespace };

package/dist/deckgl/base-map/events.js

@@ -0,0 +1,9 @@
+const MapEventsNamespace = "map";
+const MapEvents = {
+  click: `${MapEventsNamespace}:click`,
+  hover: `${MapEventsNamespace}:hover`
+};
+
+export { MapEvents, MapEventsNamespace };
+//# sourceMappingURL=events.js.map
+//# sourceMappingURL=events.js.map

package/dist/deckgl/base-map/events.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/deckgl/base-map/events.ts"],"names":[],"mappings":"AAYO,MAAM,kBAAA,GAAqB;AAE3B,MAAM,SAAA,GAAY;AAAA,EACvB,KAAA,EAAO,GAAG,kBAAkB,CAAA,MAAA,CAAA;AAAA,EAC5B,KAAA,EAAO,GAAG,kBAAkB,CAAA,MAAA;AAC9B","file":"events.js","sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\nexport const MapEventsNamespace = 'map';\n\nexport const MapEvents = {\n  click: `${MapEventsNamespace}:click`,\n  hover: `${MapEventsNamespace}:hover`,\n} as const;\n"]}

package/dist/deckgl/base-map/index.d.ts

@@ -0,0 +1,98 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { UniqueId } from '@accelint/core';
+import { DeckglProps } from '@deckgl-fiber-renderer/types';
+
+/**
+ * Props for the BaseMap component.
+ * Extends all Deck.gl props and adds additional map-specific properties.
+ */
+type BaseMapProps = DeckglProps & {
+    /** Optional CSS class name to apply to the map container element */
+    className?: string;
+    /**
+     * Unique identifier for this map instance (required).
+     *
+     * Used to isolate map mode state between multiple map instances (e.g., main map vs minimap).
+     * This should be a UUID generated using `uuid()` from `@accelint/core`.
+     *
+     * The same id should be passed to `useMapMode()` when accessing map mode state
+     * from components rendered outside of the BaseMap's children (i.e., as siblings).
+     */
+    id: UniqueId;
+};
+/**
+ * A React component that provides a Deck.gl-powered base map with MapLibre GL integration.
+ *
+ * This component serves as the foundation for building interactive map applications with
+ * support for click and hover events through a centralized event bus. It integrates
+ * Deck.gl for 3D visualizations with MapLibre GL for the base map tiles.
+ *
+ * **Map Mode Integration**: BaseMap automatically creates a `MapProvider` internally,
+ * which sets up the map mode state management for this instance.
+ * - **Children**: Only Deck.gl layer components can be rendered as children. Custom Deck.gl
+ *   layers can use `useMapMode()` without parameters to access context.
+ * - **Siblings**: UI components (buttons, toolbars, etc.) must be rendered as siblings
+ *   and pass `id` to `useMapMode(id)`.
+ *
+ * **Event Bus**: Click and hover events are emitted through the event bus with the `id`
+ * included in the payload, allowing multiple map instances to coexist without interference.
+ *
+ * @param props - Component props including id (required), className, onClick, onHover, and all Deck.gl props
+ * @returns A map component with Deck.gl and MapLibre GL integration
+ *
+ * @example
+ * Basic usage with id (recommended: module-level constant):
+ * ```tsx
+ * import { BaseMap } from '@accelint/map-toolkit/deckgl';
+ * import { View } from '@deckgl-fiber-renderer/dom';
+ * import { uuid } from '@accelint/core';
+ *
+ * // Create id at module level for stability and easy sharing
+ * const MAIN_MAP_ID = uuid();
+ *
+ * export function MapView() {
+ *   return (
+ *     <BaseMap className="w-full h-full" id={MAIN_MAP_ID}>
+ *       <View id="main" controller />
+ *     </BaseMap>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With map mode and event handlers (module-level constant for sharing):
+ * ```tsx
+ * import { BaseMap } from '@accelint/map-toolkit/deckgl';
+ * import { useMapMode } from '@accelint/map-toolkit/map-mode';
+ * import { uuid } from '@accelint/core';
+ * import type { PickingInfo } from '@deck.gl/core';
+ * import type { MjolnirGestureEvent } from 'mjolnir.js';
+ *
+ * // Module-level constant - stable and shareable across all components
+ * const MAIN_MAP_ID = uuid();
+ *
+ * function Toolbar() {
+ *   // Access map mode using the shared id
+ *   const { mode, requestModeChange } = useMapMode(MAIN_MAP_ID);
+ *   return <div>Current mode: {mode}</div>;
+ * }
+ *
+ * export function InteractiveMap() {
+ *   const handleClick = (info: PickingInfo, event: MjolnirGestureEvent) => {
+ *     console.log('Clicked:', info.object);
+ *   };
+ *
+ *   return (
+ *     <div className="relative w-full h-full">
+ *       <BaseMap className="absolute inset-0" id={MAIN_MAP_ID} onClick={handleClick}>
+ *         <View id="main" controller />
+ *       </BaseMap>
+ *       <Toolbar />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function BaseMap({ className, children, id, onClick, onHover, parameters, ...rest }: BaseMapProps): react_jsx_runtime.JSX.Element;
+
+export { BaseMap, type BaseMapProps };

package/dist/deckgl/base-map/index.js

@@ -0,0 +1,99 @@
+import { jsx } from 'react/jsx-runtime';
+import 'client-only';
+import { useEmit } from '@accelint/bus/react';
+import { useDeckgl, Deckgl } from '@deckgl-fiber-renderer/dom';
+import { useId, useMemo, useCallback } from 'react';
+import { INITIAL_VIEW_STATE } from '../../maplibre/constants.js';
+import { useMapLibre } from '../../maplibre/hooks/use-maplibre.js';
+import { BASE_MAP_STYLE, PARAMETERS } from './constants.js';
+import { MapEvents } from './events.js';
+import { MapProvider } from './provider.js';
+
+function BaseMap({
+  className,
+  children,
+  id,
+  onClick,
+  onHover,
+  parameters,
+  ...rest
+}) {
+  const deckglInstance = useDeckgl();
+  const container = useId();
+  const mapOptions = useMemo(
+    () => ({
+      container,
+      center: [INITIAL_VIEW_STATE.longitude, INITIAL_VIEW_STATE.latitude],
+      zoom: INITIAL_VIEW_STATE.zoom,
+      doubleClickZoom: false,
+      dragRotate: false,
+      pitchWithRotate: false,
+      rollEnabled: false
+    }),
+    [container]
+  );
+  useMapLibre(deckglInstance, BASE_MAP_STYLE, mapOptions);
+  const emitClick = useEmit(MapEvents.click);
+  const emitHover = useEmit(MapEvents.hover);
+  const handleMapClick = useCallback(
+    (info, event) => {
+      onClick?.(info, event);
+      const { viewport, ...infoRest } = info;
+      const {
+        stopImmediatePropagation,
+        stopPropagation,
+        preventDefault,
+        srcEvent,
+        rootElement,
+        target,
+        changedPointers,
+        pointers,
+        ...eventRest
+      } = event;
+      emitClick({
+        info: infoRest,
+        event: eventRest,
+        id
+      });
+    },
+    [emitClick, id, onClick]
+  );
+  const handleMapHover = useCallback(
+    (info, event) => {
+      onHover?.(info, event);
+      const { viewport, ...infoRest } = info;
+      const {
+        stopImmediatePropagation,
+        stopPropagation,
+        preventDefault,
+        srcEvent,
+        rootElement,
+        target,
+        ...eventRest
+      } = event;
+      emitHover({
+        info: infoRest,
+        event: eventRest,
+        id
+      });
+    },
+    [emitHover, id, onHover]
+  );
+  return /* @__PURE__ */ jsx("div", { id: container, className, children: /* @__PURE__ */ jsx(MapProvider, { id, children: /* @__PURE__ */ jsx(
+    Deckgl,
+    {
+      ...rest,
+      controller: true,
+      interleaved: true,
+      useDevicePixels: false,
+      onHover: handleMapHover,
+      onClick: handleMapClick,
+      parameters: { ...PARAMETERS, ...parameters },
+      children
+    }
+  ) }) });
+}
+
+export { BaseMap };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/deckgl/base-map/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/deckgl/base-map/index.tsx"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/*\n * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.\n * This file is licensed to you under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License. You may obtain a copy\n * of the License at https://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software distributed under\n * the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS\n * OF ANY KIND, either express or implied. See the License for the specific language\n * governing permissions and limitations under the License.\n */\n\n'use client';\n\nimport 'client-only';\nimport { useEmit } from '@accelint/bus/react';\nimport { Deckgl, useDeckgl } from '@deckgl-fiber-renderer/dom';\nimport { useCallback, useId, useMemo } from 'react';\nimport { INITIAL_VIEW_STATE } from '../../maplibre/constants';\nimport { useMapLibre } from '../../maplibre/hooks/use-maplibre';\nimport { BASE_MAP_STYLE, PARAMETERS } from './constants';\nimport { MapEvents } from './events';\nimport { MapProvider } from './provider';\nimport type { UniqueId } from '@accelint/core';\nimport type { PickingInfo } from '@deck.gl/core';\nimport type { DeckglProps } from '@deckgl-fiber-renderer/types';\nimport type { IControl } from 'maplibre-gl';\nimport type { MjolnirGestureEvent, MjolnirPointerEvent } from 'mjolnir.js';\nimport type { MapClickEvent, MapHoverEvent } from './types';\n\n/**\n * Props for the BaseMap component.\n * Extends all Deck.gl props and adds additional map-specific properties.\n */\nexport type BaseMapProps = DeckglProps & {\n  /** Optional CSS class name to apply to the map container element */\n  className?: string;\n  /**\n   * Unique identifier for this map instance (required).\n   *\n   * Used to isolate map mode state between multiple map instances (e.g., main map vs minimap).\n   * This should be a UUID generated using `uuid()` from `@accelint/core`.\n   *\n   * The same id should be passed to `useMapMode()` when accessing map mode state\n   * from components rendered outside of the BaseMap's children (i.e., as siblings).\n   */\n  id: UniqueId;\n};\n\n/**\n * A React component that provides a Deck.gl-powered base map with MapLibre GL integration.\n *\n * This component serves as the foundation for building interactive map applications with\n * support for click and hover events through a centralized event bus. It integrates\n * Deck.gl for 3D visualizations with MapLibre GL for the base map tiles.\n *\n * **Map Mode Integration**: BaseMap automatically creates a `MapProvider` internally,\n * which sets up the map mode state management for this instance.\n * - **Children**: Only Deck.gl layer components can be rendered as children. Custom Deck.gl\n *   layers can use `useMapMode()` without parameters to access context.\n * - **Siblings**: UI components (buttons, toolbars, etc.) must be rendered as siblings\n *   and pass `id` to `useMapMode(id)`.\n *\n * **Event Bus**: Click and hover events are emitted through the event bus with the `id`\n * included in the payload, allowing multiple map instances to coexist without interference.\n *\n * @param props - Component props including id (required), className, onClick, onHover, and all Deck.gl props\n * @returns A map component with Deck.gl and MapLibre GL integration\n *\n * @example\n * Basic usage with id (recommended: module-level constant):\n * ```tsx\n * import { BaseMap } from '@accelint/map-toolkit/deckgl';\n * import { View } from '@deckgl-fiber-renderer/dom';\n * import { uuid } from '@accelint/core';\n *\n * // Create id at module level for stability and easy sharing\n * const MAIN_MAP_ID = uuid();\n *\n * export function MapView() {\n *   return (\n *     <BaseMap className=\"w-full h-full\" id={MAIN_MAP_ID}>\n *       <View id=\"main\" controller />\n *     </BaseMap>\n *   );\n * }\n * ```\n *\n * @example\n * With map mode and event handlers (module-level constant for sharing):\n * ```tsx\n * import { BaseMap } from '@accelint/map-toolkit/deckgl';\n * import { useMapMode } from '@accelint/map-toolkit/map-mode';\n * import { uuid } from '@accelint/core';\n * import type { PickingInfo } from '@deck.gl/core';\n * import type { MjolnirGestureEvent } from 'mjolnir.js';\n *\n * // Module-level constant - stable and shareable across all components\n * const MAIN_MAP_ID = uuid();\n *\n * function Toolbar() {\n *   // Access map mode using the shared id\n *   const { mode, requestModeChange } = useMapMode(MAIN_MAP_ID);\n *   return <div>Current mode: {mode}</div>;\n * }\n *\n * export function InteractiveMap() {\n *   const handleClick = (info: PickingInfo, event: MjolnirGestureEvent) => {\n *     console.log('Clicked:', info.object);\n *   };\n *\n *   return (\n *     <div className=\"relative w-full h-full\">\n *       <BaseMap className=\"absolute inset-0\" id={MAIN_MAP_ID} onClick={handleClick}>\n *         <View id=\"main\" controller />\n *       </BaseMap>\n *       <Toolbar />\n *     </div>\n *   );\n * }\n * ```\n */\nexport function BaseMap({\n  className,\n  children,\n  id,\n  onClick,\n  onHover,\n  parameters,\n  ...rest\n}: BaseMapProps) {\n  const deckglInstance = useDeckgl();\n  const container = useId();\n\n  // Memoize MapLibre options to avoid creating new object on every render\n  const mapOptions = useMemo(\n    () => ({\n      container,\n      center: [INITIAL_VIEW_STATE.longitude, INITIAL_VIEW_STATE.latitude] as [\n        number,\n        number,\n      ],\n      zoom: INITIAL_VIEW_STATE.zoom,\n      doubleClickZoom: false,\n      dragRotate: false,\n      pitchWithRotate: false,\n      rollEnabled: false,\n    }),\n    [container],\n  );\n\n  // Use the custom hook to handle MapLibre\n  useMapLibre(deckglInstance as IControl, BASE_MAP_STYLE, mapOptions);\n\n  const emitClick = useEmit<MapClickEvent>(MapEvents.click);\n  const emitHover = useEmit<MapHoverEvent>(MapEvents.hover);\n\n  const handleMapClick = useCallback(\n    (info: PickingInfo, event: MjolnirGestureEvent) => {\n      // send full pickingInfo and event to user-defined onClick\n      onClick?.(info, event);\n\n      // the bus cannot serialize functions, so we omit them from the event payloads\n      const { viewport, ...infoRest } = info;\n      const {\n        stopImmediatePropagation,\n        stopPropagation,\n        preventDefault,\n        srcEvent,\n        rootElement,\n        target,\n        changedPointers,\n        pointers,\n        ...eventRest\n      } = event;\n\n      emitClick({\n        info: infoRest,\n        event: eventRest,\n        id,\n      });\n    },\n    [emitClick, id, onClick],\n  );\n\n  const handleMapHover = useCallback(\n    (info: PickingInfo, event: MjolnirPointerEvent) => {\n      // send full pickingInfo and event to user-defined onHover\n      onHover?.(info, event);\n\n      // the bus cannot serialize functions, so we omit them from the event payloads\n      const { viewport, ...infoRest } = info;\n      const {\n        stopImmediatePropagation,\n        stopPropagation,\n        preventDefault,\n        srcEvent,\n        rootElement,\n        target,\n        ...eventRest\n      } = event;\n\n      emitHover({\n        info: infoRest,\n        event: eventRest,\n        id,\n      });\n    },\n    [emitHover, id, onHover],\n  );\n\n  return (\n    <div id={container} className={className}>\n      <MapProvider id={id}>\n        <Deckgl\n          {...rest}\n          controller\n          interleaved\n          useDevicePixels={false}\n          onHover={handleMapHover}\n          onClick={handleMapClick}\n          // @ts-expect-error - DeckglProps parameters type is overly strict for WebGL parameter spreading.\n          // The merged object is valid at runtime but TypeScript cannot verify all possible parameter combinations.\n          parameters={{ ...PARAMETERS, ...parameters }}\n        >\n          {children}\n        </Deckgl>\n      </MapProvider>\n    </div>\n  );\n}\n"]}

package/dist/deckgl/base-map/provider.d.ts

@@ -0,0 +1,133 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { UniqueId } from '@accelint/core';
+
+/**
+ * React context for map ID.
+ * Use the `useMapMode` hook to access the map mode state.
+ */
+declare const MapContext: React.Context<UniqueId | null>;
+/**
+ * Props for the MapProvider component.
+ */
+type MapProviderProps = {
+    /** Child components that will have access to map mode context */
+    children: ReactNode;
+    /**
+     * Unique identifier for this map instance.
+     *
+     * Used to isolate mode changes between different map instances (e.g., main map vs minimap).
+     * This is required and should be provided by the parent component (typically BaseMap).
+     *
+     * @example
+     * ```tsx
+     * // Multiple independent map instances
+     * const mainMapId = uuid();
+     * const minimapId = uuid();
+     *
+     * <MapProvider id={mainMapId}>
+     *  // Map layers and components
+     * </MapProvider>
+     *
+     * <MapProvider id={minimapId}>
+     *  // Minimap layers and components
+     * </MapProvider>
+     * ```
+     */
+    id: UniqueId;
+};
+/**
+ * Provider component for managing map modes with ownership and authorization.
+ *
+ * **Note**: This provider is used internally by `BaseMap` and should not be used directly.
+ * Consumers should pass the `id` prop to `BaseMap`, which will create this provider automatically.
+ *
+ * This component uses a hybrid architecture combining React Context (for map instance identity)
+ * with an external observable store (for state management). The provider:
+ * - Provides a unique `id` via Context
+ * - Creates an isolated MapModeStore instance for this map
+ * - Allows components to subscribe to mode changes via `useMapMode` hook (which uses `useSyncExternalStore`)
+ *
+ * The external store manages a state machine for map modes where components can request
+ * mode changes with ownership. When a mode is owned by a component, other components
+ * must request authorization to change to a different mode. The store handles:
+ *
+ * - Automatic mode changes when no ownership conflicts exist
+ * - Authorization flow when switching between owned modes
+ * - Per-mode ownership tracking that persists throughout the session
+ * - Pending request management (one pending request per requester)
+ * - Auto-acceptance of first pending request when mode owner returns to default
+ * - Auto-rejection of other pending requests when one is approved
+ * - Event emission through a centralized event bus
+ * - Instance isolation for multiple map scenarios (main map + minimap)
+ * - Always initializes in 'default' mode
+ *
+ * ## Instance Isolation
+ *
+ * Each MapProvider instance operates independently. Mode changes in one instance
+ * do not affect other instances, even when multiple maps are rendered on the same page.
+ * This enables scenarios like:
+ * - Main map in "drawing" mode while minimap stays in "view" mode
+ * - Multiple independent map views with different interaction modes
+ *
+ * Events are scoped to specific instances using the `id` prop. The event bus
+ * filters events to ensure each provider only responds to events for its own instance.
+ *
+ * ## Pending Request Behavior
+ *
+ * - Pending requests are stored by requester ID (not mode owner)
+ * - Each requester can have only one pending request at a time
+ * - New requests from the same requester auto-replace previous requests
+ * - Pending requests persist when mode owner switches between their own modes
+ * - When any request is approved, all other pending requests are auto-rejected
+ * - When mode owner returns to default mode:
+ *   - If first pending request is for default mode, all pending requests are rejected (already in requested mode)
+ *   - If first pending request is for a different mode, that request is auto-approved and others are rejected
+ *
+ * ## Instance ID Stability and Lifecycle
+ *
+ * The provider uses React's `key` prop to force a complete remount when the `id` changes.
+ * This ensures:
+ * - Clean cleanup of the old store (no memory leaks)
+ * - Fresh initialization for the new ID
+ * - All child components remount with the new context
+ *
+ * While the `id` prop should typically remain stable (created as a module-level constant
+ * or with `useState`), changing it will work correctly due to the remount behavior.
+ *
+ * @param props - Provider props including children and required id
+ * @returns Provider component that wraps children with map instance identity context
+ *
+ * @example
+ * Internal usage within BaseMap:
+ * ```tsx
+ * // BaseMap automatically creates the provider
+ * function BaseMap({ id, children, ...props }: BaseMapProps) {
+ *   return (
+ *     <div>
+ *       <MapProvider id={id}>
+ *         <Deckgl {...props}>
+ *           {children}
+ *         </Deckgl>
+ *       </MapProvider>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * With authorization handling - use id in event payloads:
+ * ```tsx
+ * useOn(MapModeEvents.changeAuthorization, (event) => {
+ *   const { authId, id } = event.payload;
+ *   emitDecision({ authId, approved: true, owner: 'tool', id });
+ * });
+ * ```
+ */
+/**
+ * Public wrapper that forces remount when id changes.
+ * This ensures clean lifecycle management and prevents memory leaks.
+ */
+declare function MapProvider({ children, id }: MapProviderProps): react_jsx_runtime.JSX.Element;
+
+export { MapContext, MapProvider, type MapProviderProps };

package/dist/deckgl/base-map/provider.js

@@ -0,0 +1,22 @@
+import { jsx } from 'react/jsx-runtime';
+import 'client-only';
+import { createContext, useEffect } from 'react';
+import { getOrCreateStore, destroyStore } from '../../map-mode/store.js';
+
+const MapContext = createContext(null);
+function MapProvider({ children, id }) {
+  return /* @__PURE__ */ jsx(MapProviderInternal, { id, children }, id);
+}
+function MapProviderInternal({ children, id }) {
+  getOrCreateStore(id);
+  useEffect(() => {
+    return () => {
+      destroyStore(id);
+    };
+  }, [id]);
+  return /* @__PURE__ */ jsx(MapContext.Provider, { value: id, children });
+}
+
+export { MapContext, MapProvider };
+//# sourceMappingURL=provider.js.map
+//# sourceMappingURL=provider.js.map