@accelint/map-toolkit 0.4.1 → 0.6.0

package/dist/deckgl/shapes/display-shape-layer/use-shape-selection.js

@@ -0,0 +1,88 @@
+/*
+ * 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 { getOrCreateClearSelection, getOrCreateServerSnapshot, getOrCreateSetSelectedId, getOrCreateSnapshot, getOrCreateSubscription } from "./store.js";
+import { useSyncExternalStore } from "react";
+
+//#region src/deckgl/shapes/display-shape-layer/use-shape-selection.ts
+/**
+* Hook to manage shape selection state with automatic deselection
+*
+* This hook encapsulates the common pattern of:
+* 1. Listening to `shapes:selected` events and updating state
+* 2. Listening to `shapes:deselected` events and clearing state
+* 3. Listening to map clicks on empty space and emitting `shapes:deselected`
+*
+* Uses a store pattern with `useSyncExternalStore` for proper listener cleanup
+* during HMR (Hot Module Replacement) in development. The store ensures only
+* one bus listener exists per map instance, regardless of how many React
+* components subscribe.
+*
+* @param mapId - The map instance ID for event filtering
+* @returns Selection state and control functions
+*
+* @example Basic usage
+* ```tsx
+* import { useShapeSelection } from '@accelint/map-toolkit/deckgl/shapes';
+*
+* function MapWithShapes() {
+*   const { selectedId } = useShapeSelection(MAP_ID);
+*
+*   return (
+*     <BaseMap id={MAP_ID}>
+*       <displayShapeLayer
+*         id="shapes"
+*         mapId={MAP_ID}
+*         data={shapes}
+*         selectedShapeId={selectedId}
+*       />
+*     </BaseMap>
+*   );
+* }
+* ```
+*
+* @example With programmatic selection control
+* ```tsx
+* function MapWithShapes() {
+*   const { selectedId, setSelectedId, clearSelection } = useShapeSelection(MAP_ID);
+*
+*   return (
+*     <>
+*       <button onClick={() => setSelectedId(shapes[0].id)}>Select First Shape</button>
+*       <button onClick={clearSelection}>Clear Selection</button>
+*       <BaseMap id={MAP_ID}>
+*         <displayShapeLayer
+*           id="shapes"
+*           mapId={MAP_ID}
+*           data={shapes}
+*           selectedShapeId={selectedId}
+*         />
+*       </BaseMap>
+*     </>
+*   );
+* }
+* ```
+*/
+function useShapeSelection(mapId) {
+	return {
+		selectedId: useSyncExternalStore(getOrCreateSubscription(mapId), getOrCreateSnapshot(mapId), getOrCreateServerSnapshot(mapId)),
+		setSelectedId: getOrCreateSetSelectedId(mapId),
+		clearSelection: getOrCreateClearSelection(mapId)
+	};
+}
+
+//#endregion
+export { useShapeSelection };
+//# sourceMappingURL=use-shape-selection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-shape-selection.js","names":[],"sources":["../../../../src/deckgl/shapes/display-shape-layer/use-shape-selection.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\nimport { useSyncExternalStore } from 'react';\nimport {\n  getOrCreateClearSelection,\n  getOrCreateServerSnapshot,\n  getOrCreateSetSelectedId,\n  getOrCreateSnapshot,\n  getOrCreateSubscription,\n} from './store';\nimport type { UniqueId } from '@accelint/core';\nimport type { ShapeId } from '../shared/types';\n\n/**\n * Return type for useShapeSelection hook\n */\nexport interface UseShapeSelectionReturn {\n  /** Currently selected shape ID, or undefined if nothing selected */\n  selectedId: ShapeId | undefined;\n  /** Manually set the selected shape ID (useful for programmatic selection) */\n  setSelectedId: (id: ShapeId | undefined) => void;\n  /** Manually clear the selection */\n  clearSelection: () => void;\n}\n\n/**\n * Hook to manage shape selection state with automatic deselection\n *\n * This hook encapsulates the common pattern of:\n * 1. Listening to `shapes:selected` events and updating state\n * 2. Listening to `shapes:deselected` events and clearing state\n * 3. Listening to map clicks on empty space and emitting `shapes:deselected`\n *\n * Uses a store pattern with `useSyncExternalStore` for proper listener cleanup\n * during HMR (Hot Module Replacement) in development. The store ensures only\n * one bus listener exists per map instance, regardless of how many React\n * components subscribe.\n *\n * @param mapId - The map instance ID for event filtering\n * @returns Selection state and control functions\n *\n * @example Basic usage\n * ```tsx\n * import { useShapeSelection } from '@accelint/map-toolkit/deckgl/shapes';\n *\n * function MapWithShapes() {\n *   const { selectedId } = useShapeSelection(MAP_ID);\n *\n *   return (\n *     <BaseMap id={MAP_ID}>\n *       <displayShapeLayer\n *         id=\"shapes\"\n *         mapId={MAP_ID}\n *         data={shapes}\n *         selectedShapeId={selectedId}\n *       />\n *     </BaseMap>\n *   );\n * }\n * ```\n *\n * @example With programmatic selection control\n * ```tsx\n * function MapWithShapes() {\n *   const { selectedId, setSelectedId, clearSelection } = useShapeSelection(MAP_ID);\n *\n *   return (\n *     <>\n *       <button onClick={() => setSelectedId(shapes[0].id)}>Select First Shape</button>\n *       <button onClick={clearSelection}>Clear Selection</button>\n *       <BaseMap id={MAP_ID}>\n *         <displayShapeLayer\n *           id=\"shapes\"\n *           mapId={MAP_ID}\n *           data={shapes}\n *           selectedShapeId={selectedId}\n *         />\n *       </BaseMap>\n *     </>\n *   );\n * }\n * ```\n */\nexport function useShapeSelection(mapId: UniqueId): UseShapeSelectionReturn {\n  // Get cached functions for this mapId (maintains referential stability)\n  const subscribe = getOrCreateSubscription(mapId);\n  const getSnapshot = getOrCreateSnapshot(mapId);\n  const getServerSnapshot = getOrCreateServerSnapshot(mapId);\n\n  // Subscribe to store changes using React's built-in external store hook\n  const selectedId = useSyncExternalStore(\n    subscribe,\n    getSnapshot,\n    getServerSnapshot,\n  );\n\n  // Get cached action functions (maintains referential stability)\n  const setSelectedId = getOrCreateSetSelectedId(mapId);\n  const clearSelection = getOrCreateClearSelection(mapId);\n\n  return {\n    selectedId,\n    setSelectedId,\n    clearSelection,\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+FA,SAAgB,kBAAkB,OAA0C;AAiB1E,QAAO;EACL,YAXiB,qBALD,wBAAwB,MAAM,EAC5B,oBAAoB,MAAM,EACpB,0BAA0B,MAAM,CAOzD;EAQC,eALoB,yBAAyB,MAAM;EAMnD,gBALqB,0BAA0B,MAAM;EAMtD"}

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

@@ -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.
+ */
+
+import { StyledFeature } from "../../shared/types.js";
+import { Color } from "@deck.gl/core";
+
+//#region src/deckgl/shapes/display-shape-layer/utils/display-style.d.ts
+/**
+ * Get fill color for a feature
+ * Colors are passed through as-is unless applyBaseOpacity is true
+ *
+ * @param feature - The styled feature
+ * @param applyBaseOpacity - When true, multiplies alpha by BASE_FILL_OPACITY (0.6)
+ * @returns RGBA color array
+ */
+declare function getFillColor(feature: StyledFeature, applyBaseOpacity?: boolean): Color;
+/**
+ * Get stroke color for a feature
+ * Strokes are always rendered at their literal alpha value
+ *
+ * @param feature - The styled feature
+ * @returns RGBA color array
+ */
+declare function getStrokeColor(feature: StyledFeature): Color;
+/**
+ * Get line width for a feature
+ */
+declare function getLineWidth(feature: StyledFeature): number;
+/**
+ * Alias for getLineWidth (for compatibility)
+ */
+declare const getStrokeWidth: typeof getLineWidth;
+/**
+ * Get dash array for stroke pattern
+ */
+declare function getDashArray(feature: StyledFeature): [number, number] | null;
+/**
+ * Get hover-enhanced line width
+ */
+declare function getHoverLineWidth(feature: StyledFeature, isHovered: boolean): number;
+/**
+ * Get selection highlight color
+ * Returns the default highlight color or allows custom opacity override
+ */
+declare function getHighlightColor(opacity?: number): [number, number, number, number];
+/**
+ * Get highlight line width (base width + increase)
+ */
+declare function getHighlightLineWidth(feature: StyledFeature): number;
+//#endregion
+export { getDashArray, getFillColor, getHighlightColor, getHighlightLineWidth, getHoverLineWidth, getLineWidth, getStrokeColor, getStrokeWidth };
+//# sourceMappingURL=display-style.d.ts.map

package/dist/deckgl/shapes/display-shape-layer/utils/display-style.js

@@ -0,0 +1,111 @@
+/*
+ * 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 { BASE_FILL_OPACITY, DASH_ARRAYS, DEFAULT_COLORS, DEFAULT_STROKE_WIDTH, HIGHLIGHT_WIDTH_INCREASE, HOVER_WIDTH_INCREASE } from "../../shared/constants.js";
+
+//#region src/deckgl/shapes/display-shape-layer/utils/display-style.ts
+/**
+* Get fill color for a feature
+* Colors are passed through as-is unless applyBaseOpacity is true
+*
+* @param feature - The styled feature
+* @param applyBaseOpacity - When true, multiplies alpha by BASE_FILL_OPACITY (0.6)
+* @returns RGBA color array
+*/
+function getFillColor(feature, applyBaseOpacity = false) {
+	const rgba = normalizeColor((feature.properties?.styleProperties)?.fillColor ?? DEFAULT_COLORS.fill);
+	if (applyBaseOpacity) return [
+		rgba[0],
+		rgba[1],
+		rgba[2],
+		Math.round(rgba[3] * BASE_FILL_OPACITY)
+	];
+	return rgba;
+}
+/**
+* Get stroke color for a feature
+* Strokes are always rendered at their literal alpha value
+*
+* @param feature - The styled feature
+* @returns RGBA color array
+*/
+function getStrokeColor(feature) {
+	return normalizeColor((feature.properties?.styleProperties)?.strokeColor ?? DEFAULT_COLORS.stroke);
+}
+/**
+* Normalize a Color to a 4-element RGBA array
+* Handles RGB arrays (adds alpha 255), RGBA arrays, and typed arrays
+*/
+function normalizeColor(color) {
+	if (color instanceof Uint8Array || color instanceof Uint8ClampedArray) return [
+		color[0] ?? 0,
+		color[1] ?? 0,
+		color[2] ?? 0,
+		color[3] ?? 255
+	];
+	return [
+		color[0],
+		color[1],
+		color[2],
+		color[3] ?? 255
+	];
+}
+/**
+* Get line width for a feature
+*/
+function getLineWidth(feature) {
+	return (feature.properties?.styleProperties)?.strokeWidth ?? DEFAULT_STROKE_WIDTH;
+}
+/**
+* Alias for getLineWidth (for compatibility)
+*/
+const getStrokeWidth = getLineWidth;
+/**
+* Get dash array for stroke pattern
+*/
+function getDashArray(feature) {
+	return DASH_ARRAYS[(feature.properties?.styleProperties)?.strokePattern ?? "solid"] || null;
+}
+/**
+* Get hover-enhanced line width
+*/
+function getHoverLineWidth(feature, isHovered) {
+	const baseWidth = getLineWidth(feature);
+	return isHovered ? baseWidth + HOVER_WIDTH_INCREASE : baseWidth;
+}
+/**
+* Get selection highlight color
+* Returns the default highlight color or allows custom opacity override
+*/
+function getHighlightColor(opacity) {
+	const rgba = normalizeColor(DEFAULT_COLORS.highlight);
+	if (opacity !== void 0) return [
+		rgba[0],
+		rgba[1],
+		rgba[2],
+		Math.round(opacity * 255)
+	];
+	return rgba;
+}
+/**
+* Get highlight line width (base width + increase)
+*/
+function getHighlightLineWidth(feature) {
+	return getLineWidth(feature) + HIGHLIGHT_WIDTH_INCREASE;
+}
+
+//#endregion
+export { getDashArray, getFillColor, getHighlightColor, getHighlightLineWidth, getHoverLineWidth, getLineWidth, getStrokeColor, getStrokeWidth };
+//# sourceMappingURL=display-style.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"display-style.js","names":[],"sources":["../../../../../src/deckgl/shapes/display-shape-layer/utils/display-style.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\nimport {\n  BASE_FILL_OPACITY,\n  DASH_ARRAYS,\n  DEFAULT_COLORS,\n  DEFAULT_STROKE_WIDTH,\n  HIGHLIGHT_WIDTH_INCREASE,\n  HOVER_WIDTH_INCREASE,\n} from '../../shared/constants';\nimport type { Color } from '@deck.gl/core';\nimport type { StyledFeature } from '../../shared/types';\n\n/**\n * Get fill color for a feature\n * Colors are passed through as-is unless applyBaseOpacity is true\n *\n * @param feature - The styled feature\n * @param applyBaseOpacity - When true, multiplies alpha by BASE_FILL_OPACITY (0.6)\n * @returns RGBA color array\n */\nexport function getFillColor(\n  feature: StyledFeature,\n  applyBaseOpacity = false,\n): Color {\n  const styleProps = feature.properties?.styleProperties;\n  const color = styleProps?.fillColor ?? DEFAULT_COLORS.fill;\n\n  // Normalize to 4-element array\n  const rgba = normalizeColor(color);\n\n  if (applyBaseOpacity) {\n    // Apply base opacity multiplier to alpha channel\n    return [rgba[0], rgba[1], rgba[2], Math.round(rgba[3] * BASE_FILL_OPACITY)];\n  }\n\n  return rgba;\n}\n\n/**\n * Get stroke color for a feature\n * Strokes are always rendered at their literal alpha value\n *\n * @param feature - The styled feature\n * @returns RGBA color array\n */\nexport function getStrokeColor(feature: StyledFeature): Color {\n  const styleProps = feature.properties?.styleProperties;\n  const color = styleProps?.strokeColor ?? DEFAULT_COLORS.stroke;\n\n  return normalizeColor(color);\n}\n\n/**\n * Normalize a Color to a 4-element RGBA array\n * Handles RGB arrays (adds alpha 255), RGBA arrays, and typed arrays\n */\nfunction normalizeColor(color: Color): [number, number, number, number] {\n  if (color instanceof Uint8Array || color instanceof Uint8ClampedArray) {\n    return [color[0] ?? 0, color[1] ?? 0, color[2] ?? 0, color[3] ?? 255];\n  }\n\n  // Handle RGB (3-element) or RGBA (4-element) arrays\n  return [color[0], color[1], color[2], color[3] ?? 255];\n}\n\n/**\n * Get line width for a feature\n */\nexport function getLineWidth(feature: StyledFeature): number {\n  const styleProps = feature.properties?.styleProperties;\n  return styleProps?.strokeWidth ?? DEFAULT_STROKE_WIDTH;\n}\n\n/**\n * Alias for getLineWidth (for compatibility)\n */\nexport const getStrokeWidth = getLineWidth;\n\n/**\n * Get dash array for stroke pattern\n */\nexport function getDashArray(feature: StyledFeature): [number, number] | null {\n  const styleProps = feature.properties?.styleProperties;\n  const pattern = styleProps?.strokePattern ?? 'solid';\n\n  return DASH_ARRAYS[pattern] || null;\n}\n\n/**\n * Get hover-enhanced line width\n */\nexport function getHoverLineWidth(\n  feature: StyledFeature,\n  isHovered: boolean,\n): number {\n  const baseWidth = getLineWidth(feature);\n  return isHovered ? baseWidth + HOVER_WIDTH_INCREASE : baseWidth;\n}\n\n/**\n * Get selection highlight color\n * Returns the default highlight color or allows custom opacity override\n */\nexport function getHighlightColor(\n  opacity?: number,\n): [number, number, number, number] {\n  const rgba = normalizeColor(DEFAULT_COLORS.highlight);\n\n  if (opacity !== undefined) {\n    return [rgba[0], rgba[1], rgba[2], Math.round(opacity * 255)];\n  }\n\n  return rgba;\n}\n\n/**\n * Get highlight line width (base width + increase)\n */\nexport function getHighlightLineWidth(feature: StyledFeature): number {\n  const baseWidth = getLineWidth(feature);\n  return baseWidth + HIGHLIGHT_WIDTH_INCREASE;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,SAAgB,aACd,SACA,mBAAmB,OACZ;CAKP,MAAM,OAAO,gBAJM,QAAQ,YAAY,kBACb,aAAa,eAAe,KAGpB;AAElC,KAAI,iBAEF,QAAO;EAAC,KAAK;EAAI,KAAK;EAAI,KAAK;EAAI,KAAK,MAAM,KAAK,KAAK,kBAAkB;EAAC;AAG7E,QAAO;;;;;;;;;AAUT,SAAgB,eAAe,SAA+B;AAI5D,QAAO,gBAHY,QAAQ,YAAY,kBACb,eAAe,eAAe,OAE5B;;;;;;AAO9B,SAAS,eAAe,OAAgD;AACtE,KAAI,iBAAiB,cAAc,iBAAiB,kBAClD,QAAO;EAAC,MAAM,MAAM;EAAG,MAAM,MAAM;EAAG,MAAM,MAAM;EAAG,MAAM,MAAM;EAAI;AAIvE,QAAO;EAAC,MAAM;EAAI,MAAM;EAAI,MAAM;EAAI,MAAM,MAAM;EAAI;;;;;AAMxD,SAAgB,aAAa,SAAgC;AAE3D,SADmB,QAAQ,YAAY,kBACpB,eAAe;;;;;AAMpC,MAAa,iBAAiB;;;;AAK9B,SAAgB,aAAa,SAAiD;AAI5E,QAAO,aAHY,QAAQ,YAAY,kBACX,iBAAiB,YAEd;;;;;AAMjC,SAAgB,kBACd,SACA,WACQ;CACR,MAAM,YAAY,aAAa,QAAQ;AACvC,QAAO,YAAY,YAAY,uBAAuB;;;;;;AAOxD,SAAgB,kBACd,SACkC;CAClC,MAAM,OAAO,eAAe,eAAe,UAAU;AAErD,KAAI,YAAY,OACd,QAAO;EAAC,KAAK;EAAI,KAAK;EAAI,KAAK;EAAI,KAAK,MAAM,UAAU,IAAI;EAAC;AAG/D,QAAO;;;;;AAMT,SAAgB,sBAAsB,SAAgC;AAEpE,QADkB,aAAa,QAAQ,GACpB"}

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

@@ -0,0 +1,196 @@
+/*
+ * 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 { EditableShape } from "../../shared/types.js";
+
+//#region src/deckgl/shapes/display-shape-layer/utils/labels.d.ts
+/**
+ * Label positioning information including coordinates and screen-space offsets
+ */
+interface LabelPosition2d {
+  /** Geographic coordinates [longitude, latitude] */
+  coordinates: [number, number];
+  /** Horizontal text anchor point */
+  textAnchor: 'start' | 'middle' | 'end';
+  /** Vertical text alignment */
+  alignmentBaseline: 'top' | 'center' | 'bottom';
+  /** Pixel offset from coordinates [x, y] */
+  pixelOffset: [number, number];
+}
+/**
+ * Calculate a point along a line segment
+ * @param start - Start coordinate [lon, lat]
+ * @param end - End coordinate [lon, lat]
+ * @param ratio - Position along segment (0 = start, 0.5 = middle, 1 = end)
+ * @returns Interpolated coordinate [lon, lat]
+ *
+ * @example
+ * // Get a point 25% along a line segment
+ * const start: [number, number] = [-122.4, 37.8];
+ * const end: [number, number] = [-122.3, 37.9];
+ * const point = interpolatePoint(start, end, 0.25);
+ */
+declare function interpolatePoint(start: [number, number], end: [number, number], ratio: number): [number, number];
+/**
+ * Get the midpoint of a LineString
+ * @param coordinates - LineString coordinates array
+ * @returns Midpoint coordinate [lon, lat]
+ */
+declare function getLineStringMidpoint(coordinates: [number, number][]): [number, number];
+/**
+ * Get the end point of a LineString
+ * @param coordinates - LineString coordinates array
+ * @returns End coordinate [lon, lat]
+ */
+declare function getLineStringEndpoint(coordinates: [number, number][]): [number, number];
+/**
+ * Get the midpoint of a Polygon's outer ring
+ * @param coordinates - Polygon coordinates array (rings)
+ * @returns Midpoint of outer ring [lon, lat]
+ */
+declare function getPolygonMidpoint(coordinates: [number, number][][]): [number, number];
+/**
+ * Vertical label position relative to anchor point
+ */
+type LabelVerticalPosition = 'top' | 'middle' | 'bottom';
+/**
+ * Horizontal label position relative to anchor point
+ */
+type LabelHorizontalPosition = 'left' | 'center' | 'right';
+/**
+ * Cardinal direction anchor for positioning labels on geometry edges
+ * Uses edge positions relative to the geometry's bounding box
+ * Works for LineString, Polygon, and Circle geometries
+ * - 'center': centroid/midpoint of the geometry
+ * - 'top'/'right'/'bottom'/'left': edge positions
+ */
+type CardinalLabelCoordinateAnchor = 'center' | 'top' | 'right' | 'bottom' | 'left';
+/**
+ * Global label positioning options for DisplayShapeLayer
+ *
+ * ## Priority System
+ * Label positioning follows a three-tier priority system:
+ * 1. **Per-shape properties** in `styleProperties` (highest priority)
+ * 2. **Global options** via this interface
+ * 3. **Default values** (geometry-specific fallbacks)
+ *
+ * ## Label Appearance
+ *
+ * Labels use a clean text-only style:
+ * - **Text**: White uppercase, bold Roboto Mono, 10px
+ * - **Outline**: Black 2px outline for contrast
+ * - **No background or border**
+ *
+ * Text height ≈ 10px
+ *
+ * ## Positioning Concepts
+ *
+ * ### Coordinate Anchor
+ * Determines *where* on the geometry to place the label:
+ * - **Point**: Label is always at the point coordinate
+ * - **LineString/Polygon**: 'start', 'middle', or 'end' along the geometry
+ * - **Circle**: 'top', 'right', 'bottom', or 'left' on the perimeter
+ *
+ * ### Vertical/Horizontal Anchor
+ * Determines how the label aligns *relative to* the anchor point:
+ * - **Vertical**: 'top' (label text below point), 'middle' (centered), 'bottom' (label text above point)
+ * - **Horizontal**: 'left' (label text right of point), 'center' (centered), 'right' (label text left of point)
+ *
+ * ### Pixel Offset
+ * Fine-tune label position with [x, y] pixel offsets:
+ * - Positive x moves right, negative moves left
+ * - Positive y moves down, negative moves up
+ *
+ * @example Position circle labels at the top with 5px clearance
+ * ```tsx
+ * const labelOptions: LabelPositionOptions = {
+ *   circleLabelCoordinateAnchor: 'top',
+ *   circleLabelVerticalAnchor: 'bottom', // Label above the top point
+ *   circleLabelOffset: [0, -15], // -(10px text height + 5px clearance)
+ * };
+ * ```
+ *
+ * @example Position line labels at middle with offset to the right
+ * ```tsx
+ * const labelOptions: LabelPositionOptions = {
+ *   lineStringLabelCoordinateAnchor: 'middle',
+ *   lineStringLabelHorizontalAnchor: 'left',
+ *   lineStringLabelOffset: [10, 0], // 10px to the right
+ * };
+ * ```
+ */
+interface LabelPositionOptions {
+  /** Vertical anchor for Point labels @default 'top' */
+  pointLabelVerticalAnchor?: LabelVerticalPosition;
+  /** Horizontal anchor for Point labels @default 'center' */
+  pointLabelHorizontalAnchor?: LabelHorizontalPosition;
+  /** Pixel offset for Point labels [x, y] @default [0, 10] */
+  pointLabelOffset?: [number, number];
+  /** Position on LineString edge (top/right/bottom/left) @default 'bottom' */
+  lineStringLabelCoordinateAnchor?: CardinalLabelCoordinateAnchor;
+  /** Vertical anchor for LineString labels @default 'top' */
+  lineStringLabelVerticalAnchor?: LabelVerticalPosition;
+  /** Horizontal anchor for LineString labels @default 'center' */
+  lineStringLabelHorizontalAnchor?: LabelHorizontalPosition;
+  /** Pixel offset for LineString labels [x, y] @default [0, 10] */
+  lineStringLabelOffset?: [number, number];
+  /** Position on Polygon edge (top/right/bottom/left) @default 'bottom' */
+  polygonLabelCoordinateAnchor?: CardinalLabelCoordinateAnchor;
+  /** Vertical anchor for Polygon labels @default 'top' */
+  polygonLabelVerticalAnchor?: LabelVerticalPosition;
+  /** Horizontal anchor for Polygon labels @default 'center' */
+  polygonLabelHorizontalAnchor?: LabelHorizontalPosition;
+  /** Pixel offset for Polygon labels [x, y] @default [0, 10] */
+  polygonLabelOffset?: [number, number];
+  /** Position on Circle perimeter (top/right/bottom/left) @default 'bottom' */
+  circleLabelCoordinateAnchor?: CardinalLabelCoordinateAnchor;
+  /** Vertical anchor for Circle labels @default 'top' */
+  circleLabelVerticalAnchor?: LabelVerticalPosition;
+  /** Horizontal anchor for Circle labels @default 'center' */
+  circleLabelHorizontalAnchor?: LabelHorizontalPosition;
+  /** Pixel offset for Circle labels [x, y] @default [0, 10] */
+  circleLabelOffset?: [number, number];
+}
+/**
+ * Get 2D position for label based on geometry type
+ * Uses pixel-based offsets for consistent positioning at all zoom levels
+ *
+ * Priority for positioning:
+ * 1. Per-shape properties in styleProperties (highest)
+ * 2. Global labelOptions from layer props
+ * 3. Default values (fallback)
+ *
+ * Returns null if no valid coordinates can be determined
+ */
+declare function getLabelPosition2d(shape: EditableShape, options?: LabelPositionOptions): LabelPosition2d | null;
+/**
+ * Get label text for a shape
+ *
+ * Returns the display label for the shape on the map in uppercase.
+ * - `label`: Optional short display name shown on the map (e.g., "NYC")
+ * - `name`: Full shape name used internally (e.g., "New York City Office")
+ *
+ * If `label` is not provided, falls back to using `name`.
+ * Text is automatically converted to uppercase for display.
+ */
+declare function getLabelText(shape: EditableShape): string;
+/**
+ * Get label background color (uses RGB from shape fill color with fixed label opacity)
+ */
+declare function getLabelFillColor(shape: EditableShape): [number, number, number, number];
+/**
+ * Get label border color (uses RGB from shape stroke color with full opacity)
+ */
+declare function getLabelBorderColor(shape: EditableShape): [number, number, number, number];
+//#endregion
+export { CardinalLabelCoordinateAnchor, LabelHorizontalPosition, LabelPosition2d, LabelPositionOptions, LabelVerticalPosition, getLabelBorderColor, getLabelFillColor, getLabelPosition2d, getLabelText, getLineStringEndpoint, getLineStringMidpoint, getPolygonMidpoint, interpolatePoint };
+//# sourceMappingURL=labels.d.ts.map