@accelint/map-toolkit 0.6.0 → 1.1.0

package/dist/deckgl/shapes/edit-shape-layer/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","names":["DEFAULT_EDITING_STATE: EditingState"],"sources":["../../../../src/deckgl/shapes/edit-shape-layer/store.ts"],"sourcesContent":["/*\n * Copyright 2026 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\n/**\n * Edit Shape Store\n *\n * Manages editing state for shape modification.\n *\n * @example\n * ```tsx\n * import { editStore } from '@accelint/map-toolkit/deckgl/shapes';\n *\n * function EditControls({ mapId }) {\n *   const { state, edit, save, cancel } = editStore.use(mapId);\n *\n *   return (\n *     <div>\n *       <p>Editing: {state.editingShape?.name ?? 'none'}</p>\n *       <button onClick={save}>Save</button>\n *       <button onClick={cancel}>Cancel</button>\n *     </div>\n *   );\n * }\n * ```\n */\n\nimport { Broadcast } from '@accelint/bus';\nimport { getLogger } from '@accelint/logger';\nimport { createMapStore } from '@/shared/create-map-store';\nimport { MapEvents } from '../../base-map/events';\nimport {\n  isCircleShape,\n  isEllipseShape,\n  isPointShape,\n  isRectangleShape,\n} from '../shared/types';\nimport {\n  releaseModeAndCursor,\n  requestCursorChange,\n  requestModeChange,\n} from '../shared/utils/mode-utils';\nimport {\n  EDIT_CURSOR_MAP,\n  EDIT_SHAPE_LAYER_ID,\n  EDIT_SHAPE_MODE,\n} from './constants';\nimport { EditShapeEvents } from './events';\nimport type { UniqueId } from '@accelint/core';\nimport type { Feature } from 'geojson';\nimport type { MapEventType } from '../../base-map/types';\nimport type { Shape } from '../shared/types';\nimport type {\n  EditShapeEvent,\n  ShapeEditCanceledEvent,\n  ShapeEditingEvent,\n  ShapeUpdatedEvent,\n} from './events';\nimport type {\n  EditFunction,\n  EditingState,\n  EditMode,\n  EditShapeOptions,\n} from './types';\n\nconst logger = getLogger({\n  enabled:\n    process.env.NODE_ENV !== 'production' && process.env.NODE_ENV !== 'test',\n  level: 'warn',\n  prefix: '[EditShapeLayer]',\n  pretty: true,\n});\n\n/**\n * Typed event bus instances\n */\nconst editShapeBus = Broadcast.getInstance<EditShapeEvent>();\nconst mapEventBus = Broadcast.getInstance<MapEventType>();\n\n/**\n * Default editing state\n */\nconst DEFAULT_EDITING_STATE: EditingState = {\n  editingShape: null,\n  editMode: 'view',\n  featureBeingEdited: null,\n};\n\n/**\n * Actions for edit shape store\n */\ntype EditShapeActions = {\n  /** Start editing a shape */\n  edit: EditFunction;\n  /** Save the current edits */\n  save: () => void;\n  /** Cancel editing */\n  cancel: () => void;\n};\n\n/**\n * Determine the appropriate edit mode for a shape type\n */\nfunction getEditModeForShape(shape: Shape): EditMode {\n  if (isPointShape(shape)) {\n    return 'translate';\n  }\n  if (isCircleShape(shape)) {\n    return 'circle-transform';\n  }\n  if (isEllipseShape(shape) || isRectangleShape(shape)) {\n    return 'bounding-transform';\n  }\n  return 'vertex-transform';\n}\n\n/**\n * Start editing a shape\n */\nfunction startEditing(\n  mapId: UniqueId,\n  state: EditingState,\n  shape: Shape,\n  options: EditShapeOptions | undefined,\n  notify: () => void,\n  setState: (updates: Partial<EditingState>) => void,\n): void {\n  // Prevent editing locked shapes\n  if (shape.locked) {\n    logger.warn(`Cannot edit locked shape: \"${shape.name}\"`);\n    return;\n  }\n\n  // Already editing - cancel first\n  if (state.editingShape) {\n    cancelEditingInternal(mapId, state, notify, setState);\n  }\n\n  // Determine edit mode (can be overridden via options)\n  const editMode = options?.mode ?? getEditModeForShape(shape);\n\n  // Update state with new object reference\n  setState({\n    editingShape: shape,\n    editMode,\n    featureBeingEdited: shape.feature,\n  });\n\n  // Request map mode and cursor\n  requestModeChange(mapId, EDIT_SHAPE_MODE, EDIT_SHAPE_LAYER_ID);\n  const cursor = EDIT_CURSOR_MAP[editMode];\n  requestCursorChange(mapId, cursor, EDIT_SHAPE_LAYER_ID);\n\n  // Disable map panning during editing\n  mapEventBus.emit(MapEvents.disablePan, { id: mapId });\n\n  // Emit editing started event\n  editShapeBus.emit(EditShapeEvents.editing, {\n    shape,\n    mapId,\n  } as unknown as ShapeEditingEvent['payload']);\n\n  notify();\n}\n\n/**\n * Save editing and create updated shape\n */\nfunction saveEditingInternal(\n  mapId: UniqueId,\n  state: EditingState,\n  notify: () => void,\n  setState: (updates: Partial<EditingState>) => void,\n): Shape | null {\n  if (!(state.editingShape && state.featureBeingEdited)) {\n    return null;\n  }\n\n  const originalShape = state.editingShape;\n  const updatedFeature = state.featureBeingEdited;\n\n  // Create updated shape with new geometry\n  const updatedShape = {\n    ...originalShape,\n    feature: {\n      ...updatedFeature,\n      properties: {\n        ...originalShape.feature.properties,\n        ...updatedFeature.properties,\n      },\n    },\n    lastUpdated: Date.now(),\n  } as Shape;\n\n  // Reset state\n  setState({\n    editingShape: null,\n    editMode: 'view',\n    featureBeingEdited: null,\n  });\n\n  // Return to default mode and cursor\n  releaseModeAndCursor(mapId, EDIT_SHAPE_LAYER_ID);\n\n  // Re-enable map panning\n  mapEventBus.emit(MapEvents.enablePan, { id: mapId });\n\n  // Emit shape updated event\n  editShapeBus.emit(EditShapeEvents.updated, {\n    shape: updatedShape,\n    mapId,\n  } as unknown as ShapeUpdatedEvent['payload']);\n\n  notify();\n\n  return updatedShape;\n}\n\n/**\n * Cancel the current editing operation\n */\nfunction cancelEditingInternal(\n  mapId: UniqueId,\n  state: EditingState,\n  notify: () => void,\n  setState: (updates: Partial<EditingState>) => void,\n): void {\n  if (!state.editingShape) {\n    return; // Nothing to cancel\n  }\n\n  const originalShape = state.editingShape;\n\n  // Reset state\n  setState({\n    editingShape: null,\n    editMode: 'view',\n    featureBeingEdited: null,\n  });\n\n  // Return to default mode and cursor\n  releaseModeAndCursor(mapId, EDIT_SHAPE_LAYER_ID);\n\n  // Re-enable map panning\n  mapEventBus.emit(MapEvents.enablePan, { id: mapId });\n\n  // Emit canceled event\n  editShapeBus.emit(EditShapeEvents.canceled, {\n    shape: originalShape,\n    mapId,\n  } as unknown as ShapeEditCanceledEvent['payload']);\n\n  notify();\n}\n\n/**\n * Edit shape store\n */\nexport const editStore = createMapStore<EditingState, EditShapeActions>({\n  defaultState: { ...DEFAULT_EDITING_STATE },\n\n  actions: (mapId, { get, set, notify }) => ({\n    edit: (shape: Shape, options?: EditShapeOptions) => {\n      startEditing(mapId, get(), shape, options, notify, set);\n    },\n\n    save: () => {\n      saveEditingInternal(mapId, get(), notify, set);\n    },\n\n    cancel: () => {\n      cancelEditingInternal(mapId, get(), notify, set);\n    },\n  }),\n\n  // Note: EditShapeLayer is \"neutral\" regarding mode change authorization.\n  // It doesn't auto-cancel or reject mode changes - those decisions are\n  // left to UI components that can prompt the user.\n\n  onCleanup: (mapId, state) => {\n    // Cancel any active editing before cleanup\n    if (state.editingShape) {\n      // Return to default mode and cursor\n      releaseModeAndCursor(mapId, EDIT_SHAPE_LAYER_ID);\n\n      // Re-enable map panning\n      mapEventBus.emit(MapEvents.enablePan, { id: mapId });\n\n      // Emit canceled event\n      editShapeBus.emit(EditShapeEvents.canceled, {\n        shape: state.editingShape,\n        mapId,\n      } as unknown as ShapeEditCanceledEvent['payload']);\n    }\n  },\n});\n\n// =============================================================================\n// Convenience exports\n// =============================================================================\n\n/**\n * Get the current editing state for a mapId\n * Returns null if no store instance exists\n */\nexport function getEditingState(mapId: UniqueId): EditingState | null {\n  if (!editStore.exists(mapId)) {\n    return null;\n  }\n  return editStore.get(mapId);\n}\n\n/**\n * Hook for editing state\n */\nexport function useEditingState(\n  mapId: UniqueId,\n): { state: EditingState } & EditShapeActions {\n  return editStore.use(mapId);\n}\n\n/**\n * Manually clear editing state for a specific mapId.\n */\nexport function clearEditingState(mapId: UniqueId): void {\n  editStore.clear(mapId);\n}\n\n/**\n * Update feature from the layer component (called during drag operations)\n */\nexport function updateFeatureFromLayer(\n  mapId: UniqueId,\n  feature: Feature,\n): void {\n  editStore.set(mapId, { featureBeingEdited: feature });\n}\n\n/**\n * Cancel editing (called by the layer component on ESC)\n */\nexport function cancelEditingFromLayer(mapId: UniqueId): void {\n  editStore.actions(mapId).cancel();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2EA,MAAM,SAAS,UAAU;CACvB,SACE,QAAQ,IAAI,aAAa,gBAAgB,QAAQ,IAAI,aAAa;CACpE,OAAO;CACP,QAAQ;CACR,QAAQ;CACT,CAAC;;;;AAKF,MAAM,eAAe,UAAU,aAA6B;AAC5D,MAAM,cAAc,UAAU,aAA2B;;;;AAKzD,MAAMA,wBAAsC;CAC1C,cAAc;CACd,UAAU;CACV,oBAAoB;CACrB;;;;AAiBD,SAAS,oBAAoB,OAAwB;AACnD,KAAI,aAAa,MAAM,CACrB,QAAO;AAET,KAAI,cAAc,MAAM,CACtB,QAAO;AAET,KAAI,eAAe,MAAM,IAAI,iBAAiB,MAAM,CAClD,QAAO;AAET,QAAO;;;;;AAMT,SAAS,aACP,OACA,OACA,OACA,SACA,QACA,UACM;AAEN,KAAI,MAAM,QAAQ;AAChB,SAAO,KAAK,8BAA8B,MAAM,KAAK,GAAG;AACxD;;AAIF,KAAI,MAAM,aACR,uBAAsB,OAAO,OAAO,QAAQ,SAAS;CAIvD,MAAM,WAAW,SAAS,QAAQ,oBAAoB,MAAM;AAG5D,UAAS;EACP,cAAc;EACd;EACA,oBAAoB,MAAM;EAC3B,CAAC;AAGF,mBAAkB,OAAO,iBAAiB,oBAAoB;CAC9D,MAAM,SAAS,gBAAgB;AAC/B,qBAAoB,OAAO,QAAQ,oBAAoB;AAGvD,aAAY,KAAK,UAAU,YAAY,EAAE,IAAI,OAAO,CAAC;AAGrD,cAAa,KAAK,gBAAgB,SAAS;EACzC;EACA;EACD,CAA4C;AAE7C,SAAQ;;;;;AAMV,SAAS,oBACP,OACA,OACA,QACA,UACc;AACd,KAAI,EAAE,MAAM,gBAAgB,MAAM,oBAChC,QAAO;CAGT,MAAM,gBAAgB,MAAM;CAC5B,MAAM,iBAAiB,MAAM;CAG7B,MAAM,eAAe;EACnB,GAAG;EACH,SAAS;GACP,GAAG;GACH,YAAY;IACV,GAAG,cAAc,QAAQ;IACzB,GAAG,eAAe;IACnB;GACF;EACD,aAAa,KAAK,KAAK;EACxB;AAGD,UAAS;EACP,cAAc;EACd,UAAU;EACV,oBAAoB;EACrB,CAAC;AAGF,sBAAqB,OAAO,oBAAoB;AAGhD,aAAY,KAAK,UAAU,WAAW,EAAE,IAAI,OAAO,CAAC;AAGpD,cAAa,KAAK,gBAAgB,SAAS;EACzC,OAAO;EACP;EACD,CAA4C;AAE7C,SAAQ;AAER,QAAO;;;;;AAMT,SAAS,sBACP,OACA,OACA,QACA,UACM;AACN,KAAI,CAAC,MAAM,aACT;CAGF,MAAM,gBAAgB,MAAM;AAG5B,UAAS;EACP,cAAc;EACd,UAAU;EACV,oBAAoB;EACrB,CAAC;AAGF,sBAAqB,OAAO,oBAAoB;AAGhD,aAAY,KAAK,UAAU,WAAW,EAAE,IAAI,OAAO,CAAC;AAGpD,cAAa,KAAK,gBAAgB,UAAU;EAC1C,OAAO;EACP;EACD,CAAiD;AAElD,SAAQ;;;;;AAMV,MAAa,YAAY,eAA+C;CACtE,cAAc,EAAE,GAAG,uBAAuB;CAE1C,UAAU,OAAO,EAAE,KAAK,KAAK,cAAc;EACzC,OAAO,OAAc,YAA+B;AAClD,gBAAa,OAAO,KAAK,EAAE,OAAO,SAAS,QAAQ,IAAI;;EAGzD,YAAY;AACV,uBAAoB,OAAO,KAAK,EAAE,QAAQ,IAAI;;EAGhD,cAAc;AACZ,yBAAsB,OAAO,KAAK,EAAE,QAAQ,IAAI;;EAEnD;CAMD,YAAY,OAAO,UAAU;AAE3B,MAAI,MAAM,cAAc;AAEtB,wBAAqB,OAAO,oBAAoB;AAGhD,eAAY,KAAK,UAAU,WAAW,EAAE,IAAI,OAAO,CAAC;AAGpD,gBAAa,KAAK,gBAAgB,UAAU;IAC1C,OAAO,MAAM;IACb;IACD,CAAiD;;;CAGvD,CAAC;;;;AAoCF,SAAgB,uBACd,OACA,SACM;AACN,WAAU,IAAI,OAAO,EAAE,oBAAoB,SAAS,CAAC;;;;;AAMvD,SAAgB,uBAAuB,OAAuB;AAC5D,WAAU,QAAQ,MAAM,CAAC,QAAQ"}

package/dist/deckgl/shapes/edit-shape-layer/types.d.ts

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { DistanceUnitAbbreviation } from "../../../shared/units.js";
+import { Shape } from "../shared/types.js";
+import { UniqueId } from "@accelint/core";
+import { Feature } from "geojson";
+
+//#region src/deckgl/shapes/edit-shape-layer/types.d.ts
+/**
+ * Edit mode for shape editing
+ * - 'view': Not editing, shape is viewable only
+ * - 'bounding-transform': Scale/rotate/translate via bounding box handles (ellipses, rectangles)
+ * - 'vertex-transform': Drag vertices OR scale/rotate/translate (polygons, lines)
+ * - 'circle-transform': Drag edge to resize, drag body to translate (circles)
+ * - 'translate': Drag to move the shape (points)
+ */
+type EditMode = 'view' | 'bounding-transform' | 'vertex-transform' | 'circle-transform' | 'translate';
+/**
+ * State for the editing store
+ */
+type EditingState = {
+  /** Shape currently being edited */
+  editingShape: Shape | null;
+  /** Current edit mode */
+  editMode: EditMode;
+  /** Live feature being edited (updates in real-time during drag) */
+  featureBeingEdited: Feature | null;
+};
+/**
+ * Options for starting an edit operation
+ */
+type EditShapeOptions = {
+  /** Override the default edit mode (auto-detected from shape type by default) */
+  mode?: 'bounding-transform' | 'vertex-transform' | 'circle-transform' | 'translate';
+};
+/**
+ * Options for the useEditShape hook
+ */
+type UseEditShapeOptions = {
+  /** Callback when a shape edit is saved */
+  onUpdate?: (shape: Shape) => void;
+  /** Callback when editing is canceled */
+  onCancel?: (shape: Shape) => void;
+};
+/**
+ * Return type for the useEditShape hook
+ */
+type UseEditShapeReturn = {
+  /** Current editing state (null when not editing) */
+  editingState: EditingState | null;
+  /** Start editing a shape with optional mode override */
+  edit: (shape: Shape, options?: EditShapeOptions) => void;
+  /** Save the current edits and emit updated event */
+  save: () => void;
+  /** Cancel editing and revert to original shape */
+  cancel: () => void;
+  /** Whether currently in editing mode */
+  isEditing: boolean;
+  /** The shape currently being edited (null if not editing) */
+  editingShape: Shape | null;
+};
+/**
+ * Props for the EditShapeLayer component
+ */
+type EditShapeLayerProps = {
+  /** Layer ID (defaults to 'edit-shape-layer') */
+  id?: string;
+  /**
+   * Map instance ID for multi-map isolation.
+   * Optional when used inside a MapProvider (uses context).
+   * Required when used outside a MapProvider.
+   */
+  mapId?: UniqueId;
+  /** Distance unit for tooltip measurements (defaults to 'km') */
+  unit?: DistanceUnitAbbreviation;
+};
+/**
+ * Function type for the edit action
+ */
+type EditFunction = (shape: Shape, options?: EditShapeOptions) => void;
+//#endregion
+export { EditFunction, EditMode, EditShapeLayerProps, EditShapeOptions, EditingState, UseEditShapeOptions, UseEditShapeReturn };
+//# sourceMappingURL=types.d.ts.map

package/dist/deckgl/shapes/edit-shape-layer/types.js

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+'use client';

package/dist/deckgl/shapes/edit-shape-layer/use-edit-shape.d.ts

@@ -0,0 +1,82 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { UseEditShapeOptions, UseEditShapeReturn } from "./types.js";
+import { UniqueId } from "@accelint/core";
+
+//#region src/deckgl/shapes/edit-shape-layer/use-edit-shape.d.ts
+
+/**
+ * Hook to access the shape editing state and actions.
+ *
+ * This hook uses `useSyncExternalStore` to subscribe to editing state changes,
+ * providing concurrent-safe state updates. Uses a fan-out pattern where
+ * a single bus listener per map instance notifies N React component subscribers.
+ *
+ * @param mapId - Optional map instance ID. If not provided, will use the ID from `MapContext`.
+ * @param options - Optional callbacks for onUpdate and onCancel events
+ * @returns Editing state, edit/save/cancel functions, and convenience flags
+ * @throws Error if no `mapId` is provided and hook is used outside of `MapProvider`
+ *
+ * @example
+ * ```tsx
+ * // Inside MapProvider (within BaseMap children) - uses context
+ * function ShapeEditor() {
+ *   const { edit, save, cancel, isEditing, editingShape } = useEditShape(undefined, {
+ *     onUpdate: (shape) => {
+ *       console.log('Shape updated:', shape);
+ *       setShapes(prev => prev.map(s => s.id === shape.id ? shape : s));
+ *     },
+ *     onCancel: (shape) => {
+ *       console.log('Editing canceled:', shape.name);
+ *     },
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {selectedShape && !isEditing && (
+ *         <button onClick={() => edit(selectedShape)}>
+ *           Edit Shape
+ *         </button>
+ *       )}
+ *       {isEditing && (
+ *         <>
+ *           <button onClick={save}>Save</button>
+ *           <button onClick={cancel}>Cancel</button>
+ *         </>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Outside MapProvider - pass mapId directly
+ * function ExternalEditControl({ mapId, shape }: { mapId: UniqueId; shape: Shape }) {
+ *   const { edit, isEditing } = useEditShape(mapId);
+ *
+ *   return (
+ *     <button
+ *       onClick={() => edit(shape)}
+ *       disabled={isEditing}
+ *     >
+ *       Edit
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+declare function useEditShape(mapId?: UniqueId, options?: UseEditShapeOptions): UseEditShapeReturn;
+//#endregion
+export { useEditShape };
+//# sourceMappingURL=use-edit-shape.d.ts.map

package/dist/deckgl/shapes/edit-shape-layer/use-edit-shape.js

@@ -0,0 +1,114 @@
+/*
+ * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+
+'use client';
+
+import { MapContext } from "../../base-map/provider.js";
+import { EditShapeEvents } from "./events.js";
+import { editStore } from "./store.js";
+import { useContext, useMemo } from "react";
+import { useBus } from "@accelint/bus/react";
+
+//#region src/deckgl/shapes/edit-shape-layer/use-edit-shape.ts
+/**
+* Hook to access the shape editing state and actions.
+*
+* This hook uses `useSyncExternalStore` to subscribe to editing state changes,
+* providing concurrent-safe state updates. Uses a fan-out pattern where
+* a single bus listener per map instance notifies N React component subscribers.
+*
+* @param mapId - Optional map instance ID. If not provided, will use the ID from `MapContext`.
+* @param options - Optional callbacks for onUpdate and onCancel events
+* @returns Editing state, edit/save/cancel functions, and convenience flags
+* @throws Error if no `mapId` is provided and hook is used outside of `MapProvider`
+*
+* @example
+* ```tsx
+* // Inside MapProvider (within BaseMap children) - uses context
+* function ShapeEditor() {
+*   const { edit, save, cancel, isEditing, editingShape } = useEditShape(undefined, {
+*     onUpdate: (shape) => {
+*       console.log('Shape updated:', shape);
+*       setShapes(prev => prev.map(s => s.id === shape.id ? shape : s));
+*     },
+*     onCancel: (shape) => {
+*       console.log('Editing canceled:', shape.name);
+*     },
+*   });
+*
+*   return (
+*     <div>
+*       {selectedShape && !isEditing && (
+*         <button onClick={() => edit(selectedShape)}>
+*           Edit Shape
+*         </button>
+*       )}
+*       {isEditing && (
+*         <>
+*           <button onClick={save}>Save</button>
+*           <button onClick={cancel}>Cancel</button>
+*         </>
+*       )}
+*     </div>
+*   );
+* }
+* ```
+*
+* @example
+* ```tsx
+* // Outside MapProvider - pass mapId directly
+* function ExternalEditControl({ mapId, shape }: { mapId: UniqueId; shape: Shape }) {
+*   const { edit, isEditing } = useEditShape(mapId);
+*
+*   return (
+*     <button
+*       onClick={() => edit(shape)}
+*       disabled={isEditing}
+*     >
+*       Edit
+*     </button>
+*   );
+* }
+* ```
+*/
+function useEditShape(mapId, options) {
+	const contextId = useContext(MapContext);
+	const actualId = mapId ?? contextId;
+	if (!actualId) throw new Error("useEditShape requires either a mapId parameter or to be used within a MapProvider");
+	const { onUpdate, onCancel } = options ?? {};
+	const { state: editingState, edit, save, cancel } = editStore.use(actualId);
+	const { useOn: useOn$1 } = useBus();
+	useOn$1(EditShapeEvents.updated, (event) => {
+		if (event.payload.mapId === actualId && onUpdate) onUpdate(event.payload.shape);
+	});
+	useOn$1(EditShapeEvents.canceled, (event) => {
+		if (event.payload.mapId === actualId && onCancel) onCancel(event.payload.shape);
+	});
+	return useMemo(() => ({
+		editingState,
+		edit,
+		save,
+		cancel,
+		isEditing: !!editingState?.editingShape,
+		editingShape: editingState?.editingShape ?? null
+	}), [
+		editingState,
+		edit,
+		save,
+		cancel
+	]);
+}
+
+//#endregion
+export { useEditShape };
+//# sourceMappingURL=use-edit-shape.js.map

package/dist/deckgl/shapes/edit-shape-layer/use-edit-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-edit-shape.js","names":[],"sources":["../../../../src/deckgl/shapes/edit-shape-layer/use-edit-shape.ts"],"sourcesContent":["/*\n * Copyright 2026 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 { useBus } from '@accelint/bus/react';\nimport { useContext, useMemo } from 'react';\nimport { MapContext } from '../../base-map/provider';\nimport { EditShapeEvents } from './events';\nimport { editStore } from './store';\nimport type { UniqueId } from '@accelint/core';\nimport type { EditShapeEvent } from './events';\nimport type { UseEditShapeOptions, UseEditShapeReturn } from './types';\n\n/**\n * Hook to access the shape editing state and actions.\n *\n * This hook uses `useSyncExternalStore` to subscribe to editing state changes,\n * providing concurrent-safe state updates. Uses a fan-out pattern where\n * a single bus listener per map instance notifies N React component subscribers.\n *\n * @param mapId - Optional map instance ID. If not provided, will use the ID from `MapContext`.\n * @param options - Optional callbacks for onUpdate and onCancel events\n * @returns Editing state, edit/save/cancel functions, and convenience flags\n * @throws Error if no `mapId` is provided and hook is used outside of `MapProvider`\n *\n * @example\n * ```tsx\n * // Inside MapProvider (within BaseMap children) - uses context\n * function ShapeEditor() {\n *   const { edit, save, cancel, isEditing, editingShape } = useEditShape(undefined, {\n *     onUpdate: (shape) => {\n *       console.log('Shape updated:', shape);\n *       setShapes(prev => prev.map(s => s.id === shape.id ? shape : s));\n *     },\n *     onCancel: (shape) => {\n *       console.log('Editing canceled:', shape.name);\n *     },\n *   });\n *\n *   return (\n *     <div>\n *       {selectedShape && !isEditing && (\n *         <button onClick={() => edit(selectedShape)}>\n *           Edit Shape\n *         </button>\n *       )}\n *       {isEditing && (\n *         <>\n *           <button onClick={save}>Save</button>\n *           <button onClick={cancel}>Cancel</button>\n *         </>\n *       )}\n *     </div>\n *   );\n * }\n * ```\n *\n * @example\n * ```tsx\n * // Outside MapProvider - pass mapId directly\n * function ExternalEditControl({ mapId, shape }: { mapId: UniqueId; shape: Shape }) {\n *   const { edit, isEditing } = useEditShape(mapId);\n *\n *   return (\n *     <button\n *       onClick={() => edit(shape)}\n *       disabled={isEditing}\n *     >\n *       Edit\n *     </button>\n *   );\n * }\n * ```\n */\nexport function useEditShape(\n  mapId?: UniqueId,\n  options?: UseEditShapeOptions,\n): UseEditShapeReturn {\n  const contextId = useContext(MapContext);\n  const actualId = mapId ?? contextId;\n\n  if (!actualId) {\n    throw new Error(\n      'useEditShape requires either a mapId parameter or to be used within a MapProvider',\n    );\n  }\n\n  const { onUpdate, onCancel } = options ?? {};\n\n  // Use the v2 store API directly\n  const { state: editingState, edit, save, cancel } = editStore.use(actualId);\n\n  // Listen for completion/cancellation events to trigger callbacks\n  // useOn handles cleanup automatically and uses useEffectEvent for stable callbacks\n  const { useOn } = useBus<EditShapeEvent>();\n\n  useOn(EditShapeEvents.updated, (event) => {\n    if (event.payload.mapId === actualId && onUpdate) {\n      onUpdate(event.payload.shape);\n    }\n  });\n\n  useOn(EditShapeEvents.canceled, (event) => {\n    if (event.payload.mapId === actualId && onCancel) {\n      onCancel(event.payload.shape);\n    }\n  });\n\n  // Memoize the return value to prevent unnecessary re-renders\n  return useMemo(\n    () => ({\n      editingState,\n      edit,\n      save,\n      cancel,\n      isEditing: !!editingState?.editingShape,\n      editingShape: editingState?.editingShape ?? null,\n    }),\n    [editingState, edit, save, cancel],\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqFA,SAAgB,aACd,OACA,SACoB;CACpB,MAAM,YAAY,WAAW,WAAW;CACxC,MAAM,WAAW,SAAS;AAE1B,KAAI,CAAC,SACH,OAAM,IAAI,MACR,oFACD;CAGH,MAAM,EAAE,UAAU,aAAa,WAAW,EAAE;CAG5C,MAAM,EAAE,OAAO,cAAc,MAAM,MAAM,WAAW,UAAU,IAAI,SAAS;CAI3E,MAAM,EAAE,mBAAU,QAAwB;AAE1C,SAAM,gBAAgB,UAAU,UAAU;AACxC,MAAI,MAAM,QAAQ,UAAU,YAAY,SACtC,UAAS,MAAM,QAAQ,MAAM;GAE/B;AAEF,SAAM,gBAAgB,WAAW,UAAU;AACzC,MAAI,MAAM,QAAQ,UAAU,YAAY,SACtC,UAAS,MAAM,QAAQ,MAAM;GAE/B;AAGF,QAAO,eACE;EACL;EACA;EACA;EACA;EACA,WAAW,CAAC,CAAC,cAAc;EAC3B,cAAc,cAAc,gBAAgB;EAC7C,GACD;EAAC;EAAc;EAAM;EAAM;EAAO,CACnC"}

package/dist/deckgl/shapes/index.d.ts

@@ -10,11 +10,20 @@
  * governing permissions and limitations under the License.
  */
 
-import { CircleProperties, CircleRadius, DisplayShape, EditableShape, ShapeFeature, ShapeFeatureProperties, ShapeFeatureType, ShapeFeatureTypeValues, ShapeId, StyleProperties } from "./shared/types.js";
+import { CircleFeatureProperties, CircleProperties, CircleRadius, CircleShape, EllipseFeatureProperties, EllipseProperties, EllipseShape, LineStringShape, PointShape, PolygonShape, RectangleShape, Shape, ShapeFeature, ShapeFeatureProperties, ShapeFeatureType, ShapeFeatureTypeValues, ShapeId, StyleProperties, Subscription, isCircleShape, isEllipseShape, isLineStringShape, isPointShape, isPolygonShape, isRectangleShape } from "./shared/types.js";
 import { CardinalLabelCoordinateAnchor, LabelHorizontalPosition, LabelPosition2d, LabelPositionOptions, LabelVerticalPosition } from "./display-shape-layer/utils/labels.js";
-import { DisplayShapeLayerProps, StyledFeature, StyledFeatureProperties } from "./display-shape-layer/types.js";
+import { DisplayShapeLayerProps, ShowLabelsMode, StyledFeature, StyledFeatureProperties } from "./display-shape-layer/types.js";
 import { DisplayShapeLayer } from "./display-shape-layer/index.js";
-import { UseShapeSelectionReturn, useShapeSelection } from "./display-shape-layer/use-shape-selection.js";
-import { BASE_FILL_OPACITY, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, SHAPE_LAYER_IDS, STROKE_PATTERNS, STROKE_WIDTHS } from "./shared/constants.js";
-import { SHAPE_EVENTS, ShapeEventHandler, ShapeEventPayload, ShapeEventType, ShapeEvents } from "./shared/events.js";
-export { BASE_FILL_OPACITY, type CardinalLabelCoordinateAnchor, type CircleProperties, type CircleRadius, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, type DisplayShape, DisplayShapeLayer, type DisplayShapeLayerProps, type EditableShape, type LabelHorizontalPosition, type LabelPosition2d, type LabelPositionOptions, type LabelVerticalPosition, SHAPE_EVENTS, SHAPE_LAYER_IDS, STROKE_PATTERNS, STROKE_WIDTHS, type ShapeEventHandler, type ShapeEventPayload, type ShapeEventType, ShapeEvents, type ShapeFeature, type ShapeFeatureProperties, ShapeFeatureType, type ShapeFeatureTypeValues, type ShapeId, type StyleProperties, type StyledFeature, type StyledFeatureProperties, type UseShapeSelectionReturn, useShapeSelection };
+import { UseSelectShapeReturn, useSelectShape } from "./display-shape-layer/use-select-shape.js";
+import { DrawShapeEvent, DrawShapeEventType, DrawShapeEvents, ShapeDrawCanceledEvent, ShapeDrawingEvent, ShapeDrawnEvent } from "./draw-shape-layer/events.js";
+import { DrawShapeLayerProps, DrawShapeOptions, DrawingState, UseDrawShapeOptions, UseDrawShapeReturn } from "./draw-shape-layer/types.js";
+import { DrawShapeLayer } from "./draw-shape-layer/index.js";
+import { useDrawShape } from "./draw-shape-layer/use-draw-shape.js";
+import { EditShapeEvent, EditShapeEventType, EditShapeEvents, ShapeEditCanceledEvent, ShapeEditingEvent, ShapeUpdatedEvent } from "./edit-shape-layer/events.js";
+import { EditMode, EditShapeLayerProps, EditShapeOptions, EditingState, UseEditShapeOptions, UseEditShapeReturn } from "./edit-shape-layer/types.js";
+import { EditShapeLayer } from "./edit-shape-layer/index.js";
+import { useEditShape } from "./edit-shape-layer/use-edit-shape.js";
+import { BASE_FILL_OPACITY, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_EDIT_HANDLE_COLOR, DEFAULT_EDIT_HANDLE_OUTLINE_COLOR, DEFAULT_STYLE_PROPERTIES, LINE_PATTERNS, LINE_WIDTHS, SHAPE_LAYER_IDS } from "./shared/constants.js";
+import { ShapeEventType, ShapeEvents } from "./shared/events.js";
+import { getDashArray, getFillColor, getLineColor, getLineWidth, normalizeColor } from "./shared/utils/style-utils.js";
+export { BASE_FILL_OPACITY, type CardinalLabelCoordinateAnchor, type CircleFeatureProperties, type CircleProperties, type CircleRadius, type CircleShape, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_EDIT_HANDLE_COLOR, DEFAULT_EDIT_HANDLE_OUTLINE_COLOR, DEFAULT_STYLE_PROPERTIES, DisplayShapeLayer, type DisplayShapeLayerProps, type DrawShapeEvent, type DrawShapeEventType, DrawShapeEvents, DrawShapeLayer, type DrawShapeLayerProps, type DrawShapeOptions, type DrawingState, type EditMode, type EditShapeEvent, type EditShapeEventType, EditShapeEvents, EditShapeLayer, type EditShapeLayerProps, type EditShapeOptions, type EditingState, type EllipseFeatureProperties, type EllipseProperties, type EllipseShape, LINE_PATTERNS, LINE_WIDTHS, type LabelHorizontalPosition, type LabelPosition2d, type LabelPositionOptions, type LabelVerticalPosition, type LineStringShape, type PointShape, type PolygonShape, type RectangleShape, SHAPE_LAYER_IDS, type Shape, type ShapeDrawCanceledEvent, type ShapeDrawingEvent, type ShapeDrawnEvent, type ShapeEditCanceledEvent, type ShapeEditingEvent, type ShapeEventType, ShapeEvents, type ShapeFeature, type ShapeFeatureProperties, ShapeFeatureType, type ShapeFeatureTypeValues, type ShapeId, type ShapeUpdatedEvent, type ShowLabelsMode, type StyleProperties, type StyledFeature, type StyledFeatureProperties, type Subscription, type UseDrawShapeOptions, type UseDrawShapeReturn, type UseEditShapeOptions, type UseEditShapeReturn, type UseSelectShapeReturn, getDashArray, getFillColor, getLineColor, getLineWidth, isCircleShape, isEllipseShape, isLineStringShape, isPointShape, isPolygonShape, isRectangleShape, normalizeColor, useDrawShape, useEditShape, useSelectShape };

package/dist/deckgl/shapes/index.js

@@ -11,10 +11,17 @@
  */
 
 
-import { BASE_FILL_OPACITY, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, SHAPE_LAYER_IDS, STROKE_PATTERNS, STROKE_WIDTHS } from "./shared/constants.js";
-import { SHAPE_EVENTS, ShapeEvents } from "./shared/events.js";
+import { BASE_FILL_OPACITY, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_EDIT_HANDLE_COLOR, DEFAULT_EDIT_HANDLE_OUTLINE_COLOR, DEFAULT_STYLE_PROPERTIES, LINE_PATTERNS, LINE_WIDTHS, SHAPE_LAYER_IDS } from "./shared/constants.js";
+import { ShapeEvents } from "./shared/events.js";
+import { getDashArray, getFillColor, getLineColor, getLineWidth, normalizeColor } from "./shared/utils/style-utils.js";
+import { ShapeFeatureType, isCircleShape, isEllipseShape, isLineStringShape, isPointShape, isPolygonShape, isRectangleShape } from "./shared/types.js";
 import { DisplayShapeLayer } from "./display-shape-layer/index.js";
-import { useShapeSelection } from "./display-shape-layer/use-shape-selection.js";
-import { ShapeFeatureType } from "./shared/types.js";
+import { useSelectShape } from "./display-shape-layer/use-select-shape.js";
+import { DrawShapeEvents } from "./draw-shape-layer/events.js";
+import { DrawShapeLayer } from "./draw-shape-layer/index.js";
+import { useDrawShape } from "./draw-shape-layer/use-draw-shape.js";
+import { EditShapeEvents } from "./edit-shape-layer/events.js";
+import { EditShapeLayer } from "./edit-shape-layer/index.js";
+import { useEditShape } from "./edit-shape-layer/use-edit-shape.js";
 
-export { BASE_FILL_OPACITY, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STYLE_PROPERTIES, DisplayShapeLayer, SHAPE_EVENTS, SHAPE_LAYER_IDS, STROKE_PATTERNS, STROKE_WIDTHS, ShapeEvents, ShapeFeatureType, useShapeSelection };
+export { BASE_FILL_OPACITY, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_EDIT_HANDLE_COLOR, DEFAULT_EDIT_HANDLE_OUTLINE_COLOR, DEFAULT_STYLE_PROPERTIES, DisplayShapeLayer, DrawShapeEvents, DrawShapeLayer, EditShapeEvents, EditShapeLayer, LINE_PATTERNS, LINE_WIDTHS, SHAPE_LAYER_IDS, ShapeEvents, ShapeFeatureType, getDashArray, getFillColor, getLineColor, getLineWidth, isCircleShape, isEllipseShape, isLineStringShape, isPointShape, isPolygonShape, isRectangleShape, normalizeColor, useDrawShape, useEditShape, useSelectShape };

package/dist/deckgl/shapes/shared/constants.d.ts

@@ -23,56 +23,51 @@ declare const SHAPE_LAYER_IDS: {
   readonly DISPLAY_LABELS: "DISPLAY_SHAPES::Labels";
 };
 /**
- * Base fill opacity multiplier (60%) for standard semi-transparent look
+ * Base fill opacity multiplier for standard semi-transparent look.
+ * Multiplies alpha by 0.2 (reduces to 20% of original opacity).
  */
 declare const BASE_FILL_OPACITY = 0.2;
 /**
- * Default stroke width in pixels when not specified in styleProperties
- */
-declare const DEFAULT_STROKE_WIDTH = 2;
-/**
- * Additional pixels added to stroke width on hover
- */
-declare const HOVER_WIDTH_INCREASE = 2;
-/**
- * Additional pixels added to stroke width for selection highlight
- */
-declare const HIGHLIGHT_WIDTH_INCREASE = 5;
-/**
- * Fixed opacity for label background (0-255)
- */
-declare const LABEL_BACKGROUND_OPACITY = 200;
-/**
- * Fixed opacity for label border (0-255)
- */
-declare const LABEL_BORDER_OPACITY = 255;
-/**
- * Default colors as RGBA arrays for DeckGL layers
+ * Default colors as RGBA arrays for DeckGL layers.
+ *
+ * These are the canonical color values used throughout the shapes system.
+ * All other color constants should derive from these to maintain consistency.
  */
 declare const DEFAULT_COLORS: {
-  /** Default fill color (background-surface-muted gray at full alpha) */
+  /** Default fill color (white at full alpha) */
   readonly fill: Color;
-  /** Default stroke color (outline-interactive-hover gray at full alpha) */
-  readonly stroke: Color;
+  /** Default border/outline color (outline-interactive-hover: #888a8f) */
+  readonly line: Color;
   /** Highlight/selection color (turquoise at ~39% alpha) */
   readonly highlight: Color;
 };
 /**
- * Default style properties for new shapes
+ * Default style properties for saved shapes.
+ *
+ * These are applied when a shape is completed/saved.
+ * Can be overridden via styleDefaults in draw options.
  */
 declare const DEFAULT_STYLE_PROPERTIES: StyleProperties;
 /**
- * Stroke width options
+ * Border/outline width options (in pixels)
  */
-declare const STROKE_WIDTHS: readonly [1, 2, 4, 8];
+declare const LINE_WIDTHS: readonly [1, 2, 4, 8];
 /**
- * Stroke pattern options
+ * Border/outline pattern options
  */
-declare const STROKE_PATTERNS: readonly ["solid", "dashed", "dotted"];
+declare const LINE_PATTERNS: readonly ["solid", "dashed", "dotted"];
 /**
- * Dash array patterns for stroke rendering
+ * Dash array patterns for border/outline rendering
  */
 declare const DASH_ARRAYS: Record<'solid' | 'dashed' | 'dotted', [number, number] | null>;
+/**
+ * Default edit handle color (white) - used by both draw and edit layers
+ */
+declare const DEFAULT_EDIT_HANDLE_COLOR: Color;
+/**
+ * Edit handle outline color (dark for contrast)
+ */
+declare const DEFAULT_EDIT_HANDLE_OUTLINE_COLOR: Color;
 //#endregion
-export { BASE_FILL_OPACITY, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STROKE_WIDTH, DEFAULT_STYLE_PROPERTIES, HIGHLIGHT_WIDTH_INCREASE, HOVER_WIDTH_INCREASE, LABEL_BACKGROUND_OPACITY, LABEL_BORDER_OPACITY, SHAPE_LAYER_IDS, STROKE_PATTERNS, STROKE_WIDTHS };
+export { BASE_FILL_OPACITY, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_EDIT_HANDLE_COLOR, DEFAULT_EDIT_HANDLE_OUTLINE_COLOR, DEFAULT_STYLE_PROPERTIES, LINE_PATTERNS, LINE_WIDTHS, SHAPE_LAYER_IDS };
 //# sourceMappingURL=constants.d.ts.map