@accelint/map-toolkit 0.4.1 → 0.6.0

package/dist/deckgl/shapes/display-shape-layer/constants.js

@@ -0,0 +1,61 @@
+/*
+ * 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';
+
+//#region src/deckgl/shapes/display-shape-layer/constants.ts
+/**
+* Map interaction constants
+* Values derived from ngc2 for consistency
+*/
+const MAP_INTERACTION = {
+	LINE_WIDTH_MIN_PIXELS: 1,
+	ICON_SIZE: 38,
+	ICON_HOVER_SIZE_INCREASE: 5
+};
+/**
+* Selection highlight configuration
+*/
+const SELECTION_HIGHLIGHT = {
+	COLOR: [
+		40,
+		245,
+		190,
+		100
+	],
+	ICON_SIZE_INCREASE: 8
+};
+/**
+* Coffin corners configuration for Point selection/hover feedback
+* Coffin corners are bracket-like corners that appear around points
+*/
+const COFFIN_CORNERS = {
+	HOVER_ICON: "coffin-corners-hover",
+	SELECTED_ICON: "coffin-corners-selected",
+	SELECTED_HOVER_ICON: "coffin-corners-selected-hover",
+	SIZE: 38
+};
+/**
+* Default props for DisplayShapeLayer
+*/
+const DEFAULT_DISPLAY_PROPS = {
+	pickable: true,
+	showLabels: true,
+	showHighlight: false,
+	applyBaseOpacity: true,
+	highlightColor: SELECTION_HIGHLIGHT.COLOR
+};
+
+//#endregion
+export { COFFIN_CORNERS, DEFAULT_DISPLAY_PROPS, MAP_INTERACTION, SELECTION_HIGHLIGHT };
+//# sourceMappingURL=constants.js.map

package/dist/deckgl/shapes/display-shape-layer/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","names":[],"sources":["../../../../src/deckgl/shapes/display-shape-layer/constants.ts"],"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\n/**\n * Map interaction constants\n * Values derived from ngc2 for consistency\n */\nexport const MAP_INTERACTION = {\n  LINE_WIDTH_MIN_PIXELS: 1, // Minimum line width in pixels\n  ICON_SIZE: 38, // Size of shape icons\n  ICON_HOVER_SIZE_INCREASE: 5, // Additional pixels added on hover\n} as const;\n\n/**\n * Selection highlight configuration\n */\nexport const SELECTION_HIGHLIGHT = {\n  COLOR: [40, 245, 190, 100] as [number, number, number, number], // Turquoise/cyan at ~39% opacity\n  ICON_SIZE_INCREASE: 8, // Additional pixels for highlight icon\n} as const;\n\n/**\n * Coffin corners configuration for Point selection/hover feedback\n * Coffin corners are bracket-like corners that appear around points\n */\nexport const COFFIN_CORNERS = {\n  /** Icon name for hover state (white corners with background fill) */\n  HOVER_ICON: 'coffin-corners-hover',\n  /** Icon name for selected state (blue corners, no fill) */\n  SELECTED_ICON: 'coffin-corners-selected',\n  /** Icon name for selected+hover state (blue corners with background fill) */\n  SELECTED_HOVER_ICON: 'coffin-corners-selected-hover',\n  /** Size of the coffin corners icon */\n  SIZE: 38,\n} as const;\n\n/**\n * Default props for DisplayShapeLayer\n */\nexport const DEFAULT_DISPLAY_PROPS = {\n  pickable: true,\n  showLabels: true,\n  showHighlight: false,\n  applyBaseOpacity: true,\n  highlightColor: SELECTION_HIGHLIGHT.COLOR,\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAkBA,MAAa,kBAAkB;CAC7B,uBAAuB;CACvB,WAAW;CACX,0BAA0B;CAC3B;;;;AAKD,MAAa,sBAAsB;CACjC,OAAO;EAAC;EAAI;EAAK;EAAK;EAAI;CAC1B,oBAAoB;CACrB;;;;;AAMD,MAAa,iBAAiB;CAE5B,YAAY;CAEZ,eAAe;CAEf,qBAAqB;CAErB,MAAM;CACP;;;;AAKD,MAAa,wBAAwB;CACnC,UAAU;CACV,YAAY;CACZ,eAAe;CACf,kBAAkB;CAClB,gBAAgB,oBAAoB;CACrC"}

package/dist/deckgl/shapes/display-shape-layer/fiber.d.ts

@@ -0,0 +1,25 @@
+/*
+ * 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 { DisplayShapeLayerProps } from "./types.js";
+
+//#region src/deckgl/shapes/display-shape-layer/fiber.d.ts
+declare global {
+  namespace React {
+    namespace JSX {
+      interface IntrinsicElements {
+        displayShapeLayer: DisplayShapeLayerProps;
+      }
+    }
+  }
+}
+//# sourceMappingURL=fiber.d.ts.map

package/dist/deckgl/shapes/display-shape-layer/fiber.js

@@ -0,0 +1,21 @@
+/*
+ * 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 { DisplayShapeLayer } from "./index.js";
+import { extend } from "@deckgl-fiber-renderer/dom";
+
+//#region src/deckgl/shapes/display-shape-layer/fiber.ts
+extend({ DisplayShapeLayer });
+
+//#endregion
+//# sourceMappingURL=fiber.js.map

package/dist/deckgl/shapes/display-shape-layer/fiber.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fiber.js","names":[],"sources":["../../../../src/deckgl/shapes/display-shape-layer/fiber.ts"],"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\nimport { extend } from '@deckgl-fiber-renderer/dom';\nimport { DisplayShapeLayer } from './index';\nimport type { DisplayShapeLayerProps } from './types';\n\nextend({ DisplayShapeLayer });\n\ndeclare global {\n  namespace React {\n    // biome-ignore lint/style/useNamingConvention: Built-in React namespace.\n    namespace JSX {\n      interface IntrinsicElements {\n        displayShapeLayer: DisplayShapeLayerProps;\n      }\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAgBA,OAAO,EAAE,mBAAmB,CAAC"}

package/dist/deckgl/shapes/display-shape-layer/index.d.ts

@@ -0,0 +1,206 @@
+/*
+ * 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 { ShapeId } from "../shared/types.js";
+import { DisplayShapeLayerProps } from "./types.js";
+import * as _deck_gl_core0 from "@deck.gl/core";
+import { CompositeLayer, Layer, PickingInfo } from "@deck.gl/core";
+
+//#region src/deckgl/shapes/display-shape-layer/index.d.ts
+/**
+ * State interface for DisplayShapeLayer
+ */
+interface DisplayShapeLayerState {
+  /** Index of currently hovered shape, undefined when not hovering */
+  hoverIndex?: number;
+  /** ID of the last hovered shape for event deduplication */
+  lastHoveredId?: ShapeId | null;
+  /** Allow additional properties from base layer state */
+  [key: string]: unknown;
+}
+/**
+ * DisplayShapeLayer - Read-only shapes visualization layer
+ *
+ * A composite deck.gl layer for displaying geographic shapes with interactive features.
+ * Ideal for rendering shapes from external APIs or displaying read-only geographic data.
+ *
+ * ## Features
+ * - **Multiple geometry types**: Point, LineString, Polygon, and Circle
+ * - **Icon support**: Custom icons for Point geometries via icon atlases
+ * - **Interactive selection**: Click handling with dotted border and optional highlight
+ * - **Hover effects**: Line width increases on hover for better UX
+ * - **Customizable labels**: Flexible label positioning with per-shape or global options
+ * - **Style properties**: Full control over colors, stroke patterns, and opacity
+ * - **Event bus integration**: Automatically emits shape events via @accelint/bus
+ * - **Multi-map support**: Events include map instance ID for isolation
+ *
+ * ## Selection Visual Feedback
+ * When a shape is selected via `selectedShapeId`:
+ * - The shape's stroke pattern changes to dotted
+ * - An optional highlight renders underneath (controlled by `showHighlight` prop)
+ *
+ * ## Layer Structure
+ * Renders up to four sublayers (in order, bottom to top):
+ * 1. **Highlight layer**: Selection highlight effect for non-icon-Point shapes (if showHighlight=true)
+ * 2. **Coffin corners layer**: Selection/hover feedback for Point shapes with icons
+ * 3. **Main GeoJsonLayer**: Shape geometries with styling and interaction
+ * 4. **Label layer**: Text labels (if showLabels enabled)
+ *
+ * ## Icon Atlas Constraint
+ * When using icons for Point geometries, all shapes in a single layer must share the
+ * same icon atlas. The layer uses the first atlas found across all features. If you
+ * need icons from different atlases, use separate DisplayShapeLayer instances.
+ *
+ * ## Event Bus Integration
+ * Automatically emits shape events that can be consumed anywhere in your app:
+ * - `shapes:selected` - Emitted when a shape is clicked (includes mapId)
+ * - `shapes:hovered` - Emitted when the hovered shape changes (deduplicated, includes mapId)
+ *
+ * For selection with auto-deselection, use the companion `useShapeSelection` hook which handles
+ * all the event wiring automatically. See the example below.
+ *
+ * @example Basic usage with useShapeSelection hook (recommended)
+ * ```tsx
+ * import '@accelint/map-toolkit/deckgl/shapes/display-shape-layer/fiber';
+ * import { useShapeSelection } from '@accelint/map-toolkit/deckgl/shapes';
+ * import { uuid } from '@accelint/core';
+ *
+ * const MAP_ID = uuid();
+ *
+ * function MapWithShapes() {
+ *   const { selectedId } = useShapeSelection(MAP_ID);
+ *
+ *   return (
+ *     <BaseMap id={MAP_ID}>
+ *       <displayShapeLayer
+ *         id="my-shapes"
+ *         mapId={MAP_ID}
+ *         data={shapes}
+ *         selectedShapeId={selectedId}
+ *         showLabels={true}
+ *         pickable={true}
+ *       />
+ *     </BaseMap>
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom label positioning
+ * ```tsx
+ * <displayShapeLayer
+ *   id="my-shapes"
+ *   data={shapes}
+ *   showLabels={true}
+ *   labelOptions={{
+ *     // Position circle labels at the top
+ *     circleLabelCoordinateAnchor: 'top',
+ *     circleLabelVerticalAnchor: 'bottom',
+ *     circleLabelOffset: [0, -10],
+ *     // Position line labels at the middle
+ *     lineStringLabelCoordinateAnchor: 'middle',
+ *   }}
+ * />
+ * ```
+ */
+declare class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {
+  state: DisplayShapeLayerState;
+  /** Cache for transformed features to avoid recreating objects on every render */
+  private featuresCache;
+  static layerName: string;
+  static defaultProps: {
+    pickable: boolean;
+    showLabels: boolean;
+    showHighlight: boolean;
+    applyBaseOpacity: boolean;
+    highlightColor: [number, number, number, number];
+  };
+  /**
+   * Clean up state and caches when layer is destroyed
+   */
+  finalizeState(): void;
+  /**
+   * Override getPickingInfo to handle events from sublayers
+   * This is the correct pattern for CompositeLayer event handling
+   */
+  getPickingInfo({
+    info,
+    mode,
+    sourceLayer
+  }: {
+    info: PickingInfo;
+    mode?: string;
+    sourceLayer?: any;
+  }): {
+    color: Uint8Array | null;
+    layer: Layer | null;
+    sourceLayer?: Layer | null;
+    viewport?: _deck_gl_core0.Viewport;
+    index: number;
+    picked: boolean;
+    object?: any;
+    x: number;
+    y: number;
+    pixel?: [number, number];
+    coordinate?: number[];
+    devicePixel?: [number, number];
+    pixelRatio: number;
+  };
+  /**
+   * Convert shapes to GeoJSON features with shapeId in properties.
+   * Uses caching to avoid recreating objects on every render cycle.
+   */
+  private getFeaturesWithId;
+  /**
+   * Look up a shape by ID from the data prop.
+   * Used by event handlers to get full shape without storing in feature properties.
+   */
+  private getShapeById;
+  /**
+   * Handle shape click
+   */
+  private handleShapeClick;
+  /**
+   * Handle shape hover
+   */
+  private handleShapeHover;
+  /**
+   * Render highlight sublayer (underneath main layer)
+   * Note: Points with icons use coffin corners instead of highlight layer
+   */
+  private renderHighlightLayer;
+  /**
+   * Render coffin corners layer for Point geometries that have icons on hover/select
+   * Coffin corners provide visual feedback for points instead of highlight layer
+   */
+  private renderCoffinCornersLayer;
+  /**
+   * Extract icon configuration from features in a single pass.
+   * Returns the first icon's atlas and mapping (all shapes share the same atlas).
+   * Uses early return for O(1) best case when first feature has icons.
+   */
+  private getIconConfig;
+  /**
+   * Render main shapes layer
+   */
+  private renderMainLayer;
+  /**
+   * Render labels layer
+   */
+  private renderLabelsLayer;
+  /**
+   * Render all sublayers
+   */
+  renderLayers(): Layer[];
+}
+//#endregion
+export { DisplayShapeLayer };
+//# sourceMappingURL=index.d.ts.map