@accelint/map-toolkit 1.4.0 → 2.0.0

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2025 Hypergiant Galactic Systems Inc. All rights reserved.
+ * Copyright 2026 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
@@ -10,23 +10,12 @@
  * governing permissions and limitations under the License.
  */
 
-import { ShapeId } from "../shared/types.js";
-import { DisplayShapeLayerProps } from "./types.js";
+import { DisplayShapeLayerProps, DisplayShapeLayerState } 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 type for DisplayShapeLayer
- */
-type 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
  *
@@ -36,24 +25,27 @@ type DisplayShapeLayerState = {
  * ## 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**: Border/outline width increases on hover for better UX
+ * - **Interactive selection**: Click handling with brightness overlay on polygon select, optional highlight effect for non-icon-Point shapes (if showHighlight=true)
+ * - **Hover effects**: Polygon fills brighten via material lighting; outline width increases by 2px on hover
  * - **Customizable labels**: Flexible label positioning with per-shape or global options
  * - **Style properties**: Full control over colors, border/outline 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 border/outline pattern changes to dotted
- * - An optional highlight renders underneath (controlled by `showHighlight` prop)
+ * ## Interaction Philosophy
+ * Interactions never modify a shape's innate styling. Hover and selection are always
+ * additive overlays rendered apart from the main layer using opacity-scaled fill colors
+ * and material-based brightness — the base shape is never altered.
  *
  * ## 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)
+ * Renders up to seven sublayers (in order, bottom to top):
+ * 1. **Select layer**: Selection brightness overlay for polygon shapes
+ * 2. **Hover layer**: Hover brightness overlay for polygon shapes
+ * 3. **Coffin corners layer**: Selection/hover feedback for Point shapes with icons
+ * 4. **Elevation visualization**: Curtains (LineStrings) or wireframes (polygons) — elevation only
+ * 5. **Elevation indicators**: Vertical strut lines for elevated non-polygon shapes — elevation only
+ * 6. **Main GeoJsonLayer**: Shape geometries with styling and interaction
+ * 7. **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
@@ -115,6 +107,10 @@ declare class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {
   state: DisplayShapeLayerState;
   /** Cache for transformed features to avoid recreating objects on every render */
   private featuresCache;
+  /** Cache for elevation classification and curtain features */
+  private elevationCache;
+  /** Cache for elevation indicator line segments */
+  private indicatorCache;
   static layerName: string;
   static defaultProps: {
     pickable: boolean;
@@ -127,6 +123,18 @@ declare class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {
    * Clean up state and caches when layer is destroyed
    */
   finalizeState(): void;
+  /**
+   * Resolved highlight color — uses prop if provided, falls back to default.
+   */
+  private get resolvedHighlight();
+  /**
+   * Handle picking events from the main shapes layer
+   */
+  private handleMainLayerPick;
+  /**
+   * Handle picking events from curtain layers and map back to original LineString
+   */
+  private handleCurtainPick;
   /**
    * Override getPickingInfo to handle events from sublayers
    * This is the correct pattern for CompositeLayer event handling
@@ -138,7 +146,7 @@ declare class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {
   }: {
     info: PickingInfo;
     mode?: string;
-    sourceLayer?: any;
+    sourceLayer?: Layer | null;
   }): {
     color: Uint8Array | null;
     layer: Layer | null;
@@ -173,21 +181,32 @@ declare class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {
    */
   private handleShapeHover;
   /**
-   * Render highlight sublayer (underneath main layer)
-   * Note: Points with icons use coffin corners instead of highlight layer
+   * Get or compute elevation-derived data (feature classification + curtain features).
+   * Cached on features identity and applyBaseOpacity to avoid per-frame recomputation.
+   */
+  private getElevationData;
+  /**
+   * 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
+   * Render selection overlay layer for polygon shapes.
+   * Mirrors renderHoverLayer but triggers on selectedShapeId instead of hover.
+   * When a shape is both selected and hovered, both layers stack for a brighter combined effect.
    */
-  private renderCoffinCornersLayer;
+  private renderSelectLayer;
   /**
-   * 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.
+   * Render hover layer for all polygon shapes (2D and 3D).
+   * Overlays the shape's base fill with brighter material lighting.
+   * Stacks with other interaction layers (e.g. selection highlight underneath).
    */
-  private getIconConfig;
+  private renderHoverLayer;
+  /**
+   * Render coffin corners layer for Point geometries that have icons on hover/select
+   * Coffin corners provide visual feedback for points instead of select layer
+   */
+  private renderCoffinCornersLayer;
   /**
    * Render main shapes layer
    */
@@ -200,6 +219,26 @@ declare class DisplayShapeLayer extends CompositeLayer<DisplayShapeLayerProps> {
    * - 'never': No labels
    */
   private renderLabelsLayer;
+  /**
+   * Render vertical elevation indicator lines for non-polygon shapes.
+   * Creates vertical "strut" lines from ground level to elevated features.
+   * For LineStrings, creates a "curtain" effect with vertical lines at each coordinate.
+   * Polygons use wireframe extrusion instead.
+   */
+  private renderElevationIndicatorLayer;
+  /**
+   * Create a single curtain GeoJsonLayer with shared configuration.
+   */
+  private createCurtainGeoJsonLayer;
+  /**
+   * Render curtain layers for elevated LineStrings.
+   * Creates three separate layers for main, hovered, and selected states.
+   */
+  private renderCurtainLayers;
+  /**
+   * Render elevation visualization layers (curtains for lines, wireframes for polygons).
+   */
+  private renderElevationVisualizationLayer;
   /**
    * Render all sublayers
    */