@accelint/map-toolkit 0.5.0 → 0.6.0

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

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

@@ -0,0 +1,368 @@
+/*
+ * 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 { LABEL_BACKGROUND_OPACITY, LABEL_BORDER_OPACITY } from "../../shared/constants.js";
+
+//#region src/deckgl/shapes/display-shape-layer/utils/labels.ts
+/**
+* Label positioning utilities for shapes
+*
+* This module provides utilities for positioning labels on shapes and calculating
+* points along line segments. Use these to customize label placement in your shape data.
+*
+* ## Label Styling
+*
+* Labels use a text-only style for legibility across different map backgrounds:
+* - **Text**: White uppercase with bold Roboto Mono font at 10px
+* - **Outline**: Black 2px outline around text for contrast
+* - **No background or border**: Clean text-only appearance
+*
+* ### Calculating Offsets
+*
+* When positioning labels, the text height is approximately 10px.
+* For example, to position a label exactly 5px above a point:
+* - Label height ≈ text height (10px)
+* - Offset needed: [0, -(10 + 5)] = [0, -15]
+*
+* @example Position label at the middle of a LineString
+* ```typescript
+* import { getLineStringMidpoint } from '@accelint/map-toolkit/deckgl/shapes/display-shape-layer/utils/labels';
+*
+* // Calculate midpoint for custom positioning
+* const coordinates = [[-122.4, 37.8], [-122.3, 37.9], [-122.2, 38.0]];
+* const midpoint = getLineStringMidpoint(coordinates);
+*
+* // Use in shape data with custom label properties
+* const shape = {
+*   feature: {
+*     properties: {
+*       styleProperties: {
+*         labelVerticalAnchor: 'top',
+*         labelHorizontalAnchor: 'center',
+*         labelOffset: [0, -10], // Small offset above the line
+*       }
+*     }
+*   }
+* };
+* ```
+*/
+/**
+* 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);
+*/
+function interpolatePoint(start, end, ratio) {
+	const clampedRatio = Math.max(0, Math.min(1, ratio));
+	return [start[0] + (end[0] - start[0]) * clampedRatio, start[1] + (end[1] - start[1]) * clampedRatio];
+}
+/**
+* Calculate segment lengths for a line
+*/
+function calculateSegmentLengths(coordinates) {
+	let total = 0;
+	const lengths = [];
+	for (let i = 0; i < coordinates.length - 1; i++) {
+		const start = coordinates[i];
+		const end = coordinates[i + 1];
+		if (start && end) {
+			const length = Math.sqrt((end[0] - start[0]) ** 2 + (end[1] - start[1]) ** 2);
+			lengths.push(length);
+			total += length;
+		}
+	}
+	return {
+		lengths,
+		total
+	};
+}
+/**
+* Find point at specific distance along line
+*/
+function findPointAtDistance(coordinates, segmentLengths, targetDistance) {
+	let accumulatedLength = 0;
+	for (let i = 0; i < segmentLengths.length; i++) {
+		const segmentLength = segmentLengths[i];
+		if (!segmentLength) continue;
+		if (accumulatedLength + segmentLength >= targetDistance) {
+			const start = coordinates[i];
+			const end = coordinates[i + 1];
+			if (start && end) return interpolatePoint(start, end, (targetDistance - accumulatedLength) / segmentLength);
+		}
+		accumulatedLength += segmentLength;
+	}
+	return coordinates[coordinates.length - 1] ?? [0, 0];
+}
+/**
+* Get the midpoint of a LineString
+* @param coordinates - LineString coordinates array
+* @returns Midpoint coordinate [lon, lat]
+*/
+function getLineStringMidpoint(coordinates) {
+	if (coordinates.length === 0) return [0, 0];
+	if (coordinates.length === 1) return coordinates[0] ?? [0, 0];
+	const { lengths, total } = calculateSegmentLengths(coordinates);
+	return findPointAtDistance(coordinates, lengths, total / 2);
+}
+/**
+* Get the end point of a LineString
+* @param coordinates - LineString coordinates array
+* @returns End coordinate [lon, lat]
+*/
+function getLineStringEndpoint(coordinates) {
+	if (coordinates.length === 0) return [0, 0];
+	return coordinates[coordinates.length - 1] ?? [0, 0];
+}
+/**
+* Get the midpoint of a Polygon's outer ring
+* @param coordinates - Polygon coordinates array (rings)
+* @returns Midpoint of outer ring [lon, lat]
+*/
+function getPolygonMidpoint(coordinates) {
+	const outerRing = coordinates[0];
+	if (!outerRing || outerRing.length === 0) return [0, 0];
+	return getLineStringMidpoint(outerRing);
+}
+/**
+* Convert vertical/horizontal position to deck.gl textAnchor and alignmentBaseline
+*/
+function convertPositionToAnchors(vertical, horizontal) {
+	return {
+		textAnchor: {
+			left: "start",
+			center: "middle",
+			right: "end"
+		}[horizontal],
+		alignmentBaseline: {
+			top: "top",
+			middle: "center",
+			bottom: "bottom"
+		}[vertical]
+	};
+}
+/**
+* Helper to resolve label properties with priority: shape > options > default
+*/
+function resolveLabelProperties(shapeOffset, shapeVertical, shapeHorizontal, defaultOffset, defaultVertical, defaultHorizontal, optionsOffset, optionsVertical, optionsHorizontal) {
+	return {
+		pixelOffset: shapeOffset ?? optionsOffset ?? defaultOffset,
+		...convertPositionToAnchors(shapeVertical ?? optionsVertical ?? defaultVertical, shapeHorizontal ?? optionsHorizontal ?? defaultHorizontal)
+	};
+}
+/**
+* Get position for Point geometry
+*/
+function getPointPosition(geometry, shapeOffset, shapeVertical, shapeHorizontal, options) {
+	const resolved = resolveLabelProperties(shapeOffset, shapeVertical, shapeHorizontal, [0, 10], "top", "center", options?.pointLabelOffset, options?.pointLabelVerticalAnchor, options?.pointLabelHorizontalAnchor);
+	return {
+		coordinates: [geometry.coordinates[0] ?? 0, geometry.coordinates[1] ?? 0],
+		...resolved
+	};
+}
+/**
+* Get position for LineString geometry
+* Uses cardinal direction positioning to find the edge point
+*/
+function getLineStringPosition(geometry, shapeOffset, shapeVertical, shapeHorizontal, shapeCoordinateAnchor, options) {
+	const defaultOffset = [0, 10];
+	const defaultVertical = "top";
+	const defaultHorizontal = "center";
+	const defaultCoordinateAnchor = "bottom";
+	const resolved = resolveLabelProperties(shapeOffset, shapeVertical, shapeHorizontal, defaultOffset, defaultVertical, defaultHorizontal, options?.lineStringLabelOffset, options?.lineStringLabelVerticalAnchor, options?.lineStringLabelHorizontalAnchor);
+	const coordinateAnchor = shapeCoordinateAnchor ?? options?.lineStringLabelCoordinateAnchor ?? defaultCoordinateAnchor;
+	const coordinates = findEdgePoint(geometry.coordinates, coordinateAnchor);
+	if (!coordinates) return null;
+	return {
+		coordinates,
+		...resolved
+	};
+}
+/**
+* Get vertex coordinate from ring
+*/
+function getVertexCoordinate(vertex) {
+	if (!vertex || vertex[0] === void 0 || vertex[1] === void 0) return null;
+	return [vertex[0], vertex[1]];
+}
+/**
+* Check if a vertex should replace the current target based on edge position
+*/
+function shouldUpdateEdgeVertex(vertexValue, targetValue, position) {
+	return position === "top" || position === "right" ? vertexValue > targetValue : vertexValue < targetValue;
+}
+/**
+* Get the coordinate index based on edge position (0 for x/longitude, 1 for y/latitude)
+*/
+function getCoordinateIndexForEdgePosition(position) {
+	return position === "top" || position === "bottom" ? 1 : 0;
+}
+/**
+* Calculate the centroid (center point) of a set of coordinates
+* For polygons, this calculates the geometric center
+* For lines, this calculates the midpoint of the bounding box
+* Returns null if no valid coordinates exist
+*/
+function calculateCentroid(coordinates) {
+	if (coordinates.length === 0) return null;
+	let sumX = 0;
+	let sumY = 0;
+	let count = 0;
+	for (const coord of coordinates) if (coord && coord[0] !== void 0 && coord[1] !== void 0) {
+		sumX += coord[0];
+		sumY += coord[1];
+		count++;
+	}
+	if (count === 0) return null;
+	return [sumX / count, sumY / count];
+}
+/**
+* Find the point on a geometry's perimeter at the specified edge position
+* @param coordinates - Array of coordinates (ring or line)
+* @param position - Edge position (center/top/right/bottom/left) relative to bounding box
+* @returns Coordinate at the specified edge position, or null if no valid coordinates
+*/
+function findEdgePoint(coordinates, position) {
+	if (!coordinates || coordinates.length === 0) return null;
+	if (position === "center") return calculateCentroid(coordinates);
+	let targetVertex = coordinates[0];
+	const coordinateIndex = getCoordinateIndexForEdgePosition(position);
+	for (const vertex of coordinates) {
+		if (!vertex) continue;
+		if (!targetVertex) continue;
+		const vertexValue = vertex[coordinateIndex];
+		const targetValue = targetVertex[coordinateIndex];
+		if (vertexValue === void 0 || targetValue === void 0) continue;
+		if (shouldUpdateEdgeVertex(vertexValue, targetValue, position)) targetVertex = vertex;
+	}
+	return getVertexCoordinate(targetVertex);
+}
+/**
+* Get position for Circle geometry (special case of Polygon)
+*/
+function getCirclePosition(ring, shapeOffset, shapeVertical, shapeHorizontal, shapeCoordinateAnchor, options) {
+	const defaultOffset = [0, 10];
+	const defaultVertical = "top";
+	const defaultHorizontal = "center";
+	const defaultCoordinateAnchor = "bottom";
+	const resolved = resolveLabelProperties(shapeOffset, shapeVertical, shapeHorizontal, defaultOffset, defaultVertical, defaultHorizontal, options?.circleLabelOffset, options?.circleLabelVerticalAnchor, options?.circleLabelHorizontalAnchor);
+	const coordinates = findEdgePoint(ring, shapeCoordinateAnchor ?? options?.circleLabelCoordinateAnchor ?? defaultCoordinateAnchor);
+	if (!coordinates) return null;
+	return {
+		coordinates,
+		...resolved
+	};
+}
+/**
+* Get position for Polygon geometry
+* Uses cardinal direction positioning to find the edge point
+*/
+function getPolygonPosition(geometry, shape, shapeOffset, shapeVertical, shapeHorizontal, shapeCoordinateAnchor, options) {
+	const ring = geometry.coordinates[0];
+	if (shape.shapeType === "Circle") return getCirclePosition(ring, shapeOffset, shapeVertical, shapeHorizontal, shapeCoordinateAnchor, options);
+	const defaultOffset = [0, 10];
+	const defaultVertical = "top";
+	const defaultHorizontal = "center";
+	const defaultCoordinateAnchor = "bottom";
+	const resolved = resolveLabelProperties(shapeOffset, shapeVertical, shapeHorizontal, defaultOffset, defaultVertical, defaultHorizontal, options?.polygonLabelOffset, options?.polygonLabelVerticalAnchor, options?.polygonLabelHorizontalAnchor);
+	const coordinates = findEdgePoint(ring, shapeCoordinateAnchor ?? options?.polygonLabelCoordinateAnchor ?? defaultCoordinateAnchor);
+	if (!coordinates) return null;
+	return {
+		coordinates,
+		...resolved
+	};
+}
+/**
+* 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
+*/
+function getLabelPosition2d(shape, options) {
+	const { geometry } = shape.feature;
+	const styleProps = shape.feature.properties?.styleProperties;
+	const shapeOffset = styleProps?.labelOffset;
+	const shapeVertical = styleProps?.labelVerticalAnchor;
+	const shapeHorizontal = styleProps?.labelHorizontalAnchor;
+	const shapeCoordinateAnchor = styleProps?.labelCoordinateAnchor;
+	switch (geometry.type) {
+		case "Point": return getPointPosition(geometry, shapeOffset, shapeVertical, shapeHorizontal, options);
+		case "LineString": return getLineStringPosition(geometry, shapeOffset, shapeVertical, shapeHorizontal, shapeCoordinateAnchor, options);
+		case "Polygon": return getPolygonPosition(geometry, shape, shapeOffset, shapeVertical, shapeHorizontal, shapeCoordinateAnchor, options);
+		default: return 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.
+*/
+function getLabelText(shape) {
+	return (shape.label || shape.name).toUpperCase();
+}
+/**
+* Get label background color (uses RGB from shape fill color with fixed label opacity)
+*/
+function getLabelFillColor(shape) {
+	const fillColor = (shape.feature.properties?.styleProperties)?.fillColor ?? [
+		98,
+		166,
+		255,
+		255
+	];
+	return [
+		fillColor[0] ?? 98,
+		fillColor[1] ?? 166,
+		fillColor[2] ?? 255,
+		LABEL_BACKGROUND_OPACITY
+	];
+}
+/**
+* Get label border color (uses RGB from shape stroke color with full opacity)
+*/
+function getLabelBorderColor(shape) {
+	const strokeColor = (shape.feature.properties?.styleProperties)?.strokeColor ?? [
+		98,
+		166,
+		255,
+		255
+	];
+	return [
+		strokeColor[0] ?? 98,
+		strokeColor[1] ?? 166,
+		strokeColor[2] ?? 255,
+		LABEL_BORDER_OPACITY
+	];
+}
+
+//#endregion
+export { getLabelBorderColor, getLabelFillColor, getLabelPosition2d, getLabelText, getLineStringEndpoint, getLineStringMidpoint, getPolygonMidpoint, interpolatePoint };
+//# sourceMappingURL=labels.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"labels.js","names":["lengths: number[]","defaultOffset: [number, number]","defaultVertical: LabelVerticalPosition","defaultHorizontal: LabelHorizontalPosition","defaultCoordinateAnchor: CardinalLabelCoordinateAnchor"],"sources":["../../../../../src/deckgl/shapes/display-shape-layer/utils/labels.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/**\n * Label positioning utilities for shapes\n *\n * This module provides utilities for positioning labels on shapes and calculating\n * points along line segments. Use these to customize label placement in your shape data.\n *\n * ## Label Styling\n *\n * Labels use a text-only style for legibility across different map backgrounds:\n * - **Text**: White uppercase with bold Roboto Mono font at 10px\n * - **Outline**: Black 2px outline around text for contrast\n * - **No background or border**: Clean text-only appearance\n *\n * ### Calculating Offsets\n *\n * When positioning labels, the text height is approximately 10px.\n * For example, to position a label exactly 5px above a point:\n * - Label height ≈ text height (10px)\n * - Offset needed: [0, -(10 + 5)] = [0, -15]\n *\n * @example Position label at the middle of a LineString\n * ```typescript\n * import { getLineStringMidpoint } from '@accelint/map-toolkit/deckgl/shapes/display-shape-layer/utils/labels';\n *\n * // Calculate midpoint for custom positioning\n * const coordinates = [[-122.4, 37.8], [-122.3, 37.9], [-122.2, 38.0]];\n * const midpoint = getLineStringMidpoint(coordinates);\n *\n * // Use in shape data with custom label properties\n * const shape = {\n *   feature: {\n *     properties: {\n *       styleProperties: {\n *         labelVerticalAnchor: 'top',\n *         labelHorizontalAnchor: 'center',\n *         labelOffset: [0, -10], // Small offset above the line\n *       }\n *     }\n *   }\n * };\n * ```\n */\n\n'use client';\n\nimport {\n  LABEL_BACKGROUND_OPACITY,\n  LABEL_BORDER_OPACITY,\n} from '../../shared/constants';\nimport type { LineString, Point, Polygon } from 'geojson';\nimport type { EditableShape } from '../../shared/types';\n\n/**\n * Label positioning information including coordinates and screen-space offsets\n */\nexport interface LabelPosition2d {\n  /** Geographic coordinates [longitude, latitude] */\n  coordinates: [number, number];\n  /** Horizontal text anchor point */\n  textAnchor: 'start' | 'middle' | 'end';\n  /** Vertical text alignment */\n  alignmentBaseline: 'top' | 'center' | 'bottom';\n  /** Pixel offset from coordinates [x, y] */\n  pixelOffset: [number, number];\n}\n\n/**\n * Calculate a point along a line segment\n * @param start - Start coordinate [lon, lat]\n * @param end - End coordinate [lon, lat]\n * @param ratio - Position along segment (0 = start, 0.5 = middle, 1 = end)\n * @returns Interpolated coordinate [lon, lat]\n *\n * @example\n * // Get a point 25% along a line segment\n * const start: [number, number] = [-122.4, 37.8];\n * const end: [number, number] = [-122.3, 37.9];\n * const point = interpolatePoint(start, end, 0.25);\n */\nexport function interpolatePoint(\n  start: [number, number],\n  end: [number, number],\n  ratio: number,\n): [number, number] {\n  const clampedRatio = Math.max(0, Math.min(1, ratio));\n  return [\n    start[0] + (end[0] - start[0]) * clampedRatio,\n    start[1] + (end[1] - start[1]) * clampedRatio,\n  ];\n}\n\n/**\n * Calculate segment lengths for a line\n */\nfunction calculateSegmentLengths(coordinates: [number, number][]): {\n  lengths: number[];\n  total: number;\n} {\n  let total = 0;\n  const lengths: number[] = [];\n\n  for (let i = 0; i < coordinates.length - 1; i++) {\n    const start = coordinates[i];\n    const end = coordinates[i + 1];\n    if (start && end) {\n      const length = Math.sqrt(\n        (end[0] - start[0]) ** 2 + (end[1] - start[1]) ** 2,\n      );\n      lengths.push(length);\n      total += length;\n    }\n  }\n\n  return { lengths, total };\n}\n\n/**\n * Find point at specific distance along line\n */\nfunction findPointAtDistance(\n  coordinates: [number, number][],\n  segmentLengths: number[],\n  targetDistance: number,\n): [number, number] {\n  let accumulatedLength = 0;\n\n  for (let i = 0; i < segmentLengths.length; i++) {\n    const segmentLength = segmentLengths[i];\n    if (!segmentLength) {\n      continue;\n    }\n\n    if (accumulatedLength + segmentLength >= targetDistance) {\n      const start = coordinates[i];\n      const end = coordinates[i + 1];\n      if (start && end) {\n        const ratio = (targetDistance - accumulatedLength) / segmentLength;\n        return interpolatePoint(start, end, ratio);\n      }\n    }\n    accumulatedLength += segmentLength;\n  }\n\n  return coordinates[coordinates.length - 1] ?? [0, 0];\n}\n\n/**\n * Get the midpoint of a LineString\n * @param coordinates - LineString coordinates array\n * @returns Midpoint coordinate [lon, lat]\n */\nexport function getLineStringMidpoint(\n  coordinates: [number, number][],\n): [number, number] {\n  if (coordinates.length === 0) {\n    return [0, 0];\n  }\n  if (coordinates.length === 1) {\n    return coordinates[0] ?? [0, 0];\n  }\n\n  const { lengths, total } = calculateSegmentLengths(coordinates);\n  const halfLength = total / 2;\n\n  return findPointAtDistance(coordinates, lengths, halfLength);\n}\n\n/**\n * Get the end point of a LineString\n * @param coordinates - LineString coordinates array\n * @returns End coordinate [lon, lat]\n */\nexport function getLineStringEndpoint(\n  coordinates: [number, number][],\n): [number, number] {\n  if (coordinates.length === 0) {\n    return [0, 0];\n  }\n  return coordinates[coordinates.length - 1] ?? [0, 0];\n}\n\n/**\n * Get the midpoint of a Polygon's outer ring\n * @param coordinates - Polygon coordinates array (rings)\n * @returns Midpoint of outer ring [lon, lat]\n */\nexport function getPolygonMidpoint(\n  coordinates: [number, number][][],\n): [number, number] {\n  const outerRing = coordinates[0];\n  if (!outerRing || outerRing.length === 0) {\n    return [0, 0];\n  }\n  // Use the outer ring (first ring)\n  return getLineStringMidpoint(outerRing);\n}\n\n/**\n * Vertical label position relative to anchor point\n */\nexport type LabelVerticalPosition = 'top' | 'middle' | 'bottom';\n\n/**\n * Horizontal label position relative to anchor point\n */\nexport type LabelHorizontalPosition = 'left' | 'center' | 'right';\n\n/**\n * Cardinal direction anchor for positioning labels on geometry edges\n * Uses edge positions relative to the geometry's bounding box\n * Works for LineString, Polygon, and Circle geometries\n * - 'center': centroid/midpoint of the geometry\n * - 'top'/'right'/'bottom'/'left': edge positions\n */\nexport type CardinalLabelCoordinateAnchor =\n  | 'center'\n  | 'top'\n  | 'right'\n  | 'bottom'\n  | 'left';\n\n/**\n * Global label positioning options for DisplayShapeLayer\n *\n * ## Priority System\n * Label positioning follows a three-tier priority system:\n * 1. **Per-shape properties** in `styleProperties` (highest priority)\n * 2. **Global options** via this interface\n * 3. **Default values** (geometry-specific fallbacks)\n *\n * ## Label Appearance\n *\n * Labels use a clean text-only style:\n * - **Text**: White uppercase, bold Roboto Mono, 10px\n * - **Outline**: Black 2px outline for contrast\n * - **No background or border**\n *\n * Text height ≈ 10px\n *\n * ## Positioning Concepts\n *\n * ### Coordinate Anchor\n * Determines *where* on the geometry to place the label:\n * - **Point**: Label is always at the point coordinate\n * - **LineString/Polygon**: 'start', 'middle', or 'end' along the geometry\n * - **Circle**: 'top', 'right', 'bottom', or 'left' on the perimeter\n *\n * ### Vertical/Horizontal Anchor\n * Determines how the label aligns *relative to* the anchor point:\n * - **Vertical**: 'top' (label text below point), 'middle' (centered), 'bottom' (label text above point)\n * - **Horizontal**: 'left' (label text right of point), 'center' (centered), 'right' (label text left of point)\n *\n * ### Pixel Offset\n * Fine-tune label position with [x, y] pixel offsets:\n * - Positive x moves right, negative moves left\n * - Positive y moves down, negative moves up\n *\n * @example Position circle labels at the top with 5px clearance\n * ```tsx\n * const labelOptions: LabelPositionOptions = {\n *   circleLabelCoordinateAnchor: 'top',\n *   circleLabelVerticalAnchor: 'bottom', // Label above the top point\n *   circleLabelOffset: [0, -15], // -(10px text height + 5px clearance)\n * };\n * ```\n *\n * @example Position line labels at middle with offset to the right\n * ```tsx\n * const labelOptions: LabelPositionOptions = {\n *   lineStringLabelCoordinateAnchor: 'middle',\n *   lineStringLabelHorizontalAnchor: 'left',\n *   lineStringLabelOffset: [10, 0], // 10px to the right\n * };\n * ```\n */\nexport interface LabelPositionOptions {\n  // Point geometry options\n  /** Vertical anchor for Point labels @default 'top' */\n  pointLabelVerticalAnchor?: LabelVerticalPosition;\n  /** Horizontal anchor for Point labels @default 'center' */\n  pointLabelHorizontalAnchor?: LabelHorizontalPosition;\n  /** Pixel offset for Point labels [x, y] @default [0, 10] */\n  pointLabelOffset?: [number, number];\n\n  // LineString geometry options\n  /** Position on LineString edge (top/right/bottom/left) @default 'bottom' */\n  lineStringLabelCoordinateAnchor?: CardinalLabelCoordinateAnchor;\n  /** Vertical anchor for LineString labels @default 'top' */\n  lineStringLabelVerticalAnchor?: LabelVerticalPosition;\n  /** Horizontal anchor for LineString labels @default 'center' */\n  lineStringLabelHorizontalAnchor?: LabelHorizontalPosition;\n  /** Pixel offset for LineString labels [x, y] @default [0, 10] */\n  lineStringLabelOffset?: [number, number];\n\n  // Polygon geometry options\n  /** Position on Polygon edge (top/right/bottom/left) @default 'bottom' */\n  polygonLabelCoordinateAnchor?: CardinalLabelCoordinateAnchor;\n  /** Vertical anchor for Polygon labels @default 'top' */\n  polygonLabelVerticalAnchor?: LabelVerticalPosition;\n  /** Horizontal anchor for Polygon labels @default 'center' */\n  polygonLabelHorizontalAnchor?: LabelHorizontalPosition;\n  /** Pixel offset for Polygon labels [x, y] @default [0, 10] */\n  polygonLabelOffset?: [number, number];\n\n  // Circle geometry options\n  /** Position on Circle perimeter (top/right/bottom/left) @default 'bottom' */\n  circleLabelCoordinateAnchor?: CardinalLabelCoordinateAnchor;\n  /** Vertical anchor for Circle labels @default 'top' */\n  circleLabelVerticalAnchor?: LabelVerticalPosition;\n  /** Horizontal anchor for Circle labels @default 'center' */\n  circleLabelHorizontalAnchor?: LabelHorizontalPosition;\n  /** Pixel offset for Circle labels [x, y] @default [0, 10] */\n  circleLabelOffset?: [number, number];\n}\n\n/**\n * Convert vertical/horizontal position to deck.gl textAnchor and alignmentBaseline\n */\nfunction convertPositionToAnchors(\n  vertical: LabelVerticalPosition,\n  horizontal: LabelHorizontalPosition,\n): {\n  textAnchor: 'start' | 'middle' | 'end';\n  alignmentBaseline: 'top' | 'center' | 'bottom';\n} {\n  // Map horizontal to textAnchor\n  const textAnchorMap: Record<\n    LabelHorizontalPosition,\n    'start' | 'middle' | 'end'\n  > = {\n    left: 'start',\n    center: 'middle',\n    right: 'end',\n  };\n\n  // Map vertical to alignmentBaseline\n  const alignmentBaselineMap: Record<\n    LabelVerticalPosition,\n    'top' | 'center' | 'bottom'\n  > = {\n    top: 'top',\n    middle: 'center',\n    bottom: 'bottom',\n  };\n\n  return {\n    textAnchor: textAnchorMap[horizontal],\n    alignmentBaseline: alignmentBaselineMap[vertical],\n  };\n}\n\n/**\n * Helper to resolve label properties with priority: shape > options > default\n */\nfunction resolveLabelProperties(\n  shapeOffset: [number, number] | undefined,\n  shapeVertical: string | undefined,\n  shapeHorizontal: string | undefined,\n  defaultOffset: [number, number],\n  defaultVertical: LabelVerticalPosition,\n  defaultHorizontal: LabelHorizontalPosition,\n  optionsOffset?: [number, number],\n  optionsVertical?: LabelVerticalPosition,\n  optionsHorizontal?: LabelHorizontalPosition,\n) {\n  const vertical = (shapeVertical ??\n    optionsVertical ??\n    defaultVertical) as LabelVerticalPosition;\n  const horizontal = (shapeHorizontal ??\n    optionsHorizontal ??\n    defaultHorizontal) as LabelHorizontalPosition;\n  const pixelOffset = shapeOffset ?? optionsOffset ?? defaultOffset;\n\n  const anchors = convertPositionToAnchors(vertical, horizontal);\n\n  return {\n    pixelOffset,\n    ...anchors,\n  };\n}\n\n/**\n * Get position for Point geometry\n */\nfunction getPointPosition(\n  geometry: Point,\n  shapeOffset: [number, number] | undefined,\n  shapeVertical: string | undefined,\n  shapeHorizontal: string | undefined,\n  options?: LabelPositionOptions,\n): LabelPosition2d {\n  const defaultOffset: [number, number] = [0, 10];\n  const defaultVertical: LabelVerticalPosition = 'top';\n  const defaultHorizontal: LabelHorizontalPosition = 'center';\n\n  const resolved = resolveLabelProperties(\n    shapeOffset,\n    shapeVertical,\n    shapeHorizontal,\n    defaultOffset,\n    defaultVertical,\n    defaultHorizontal,\n    options?.pointLabelOffset,\n    options?.pointLabelVerticalAnchor,\n    options?.pointLabelHorizontalAnchor,\n  );\n\n  return {\n    coordinates: [\n      geometry.coordinates[0] ?? 0,\n      geometry.coordinates[1] ?? 0,\n    ] as [number, number],\n    ...resolved,\n  };\n}\n\n/**\n * Get position for LineString geometry\n * Uses cardinal direction positioning to find the edge point\n */\nfunction getLineStringPosition(\n  geometry: LineString,\n  shapeOffset: [number, number] | undefined,\n  shapeVertical: string | undefined,\n  shapeHorizontal: string | undefined,\n  shapeCoordinateAnchor: string | undefined,\n  options?: LabelPositionOptions,\n): LabelPosition2d | null {\n  const defaultOffset: [number, number] = [0, 10];\n  const defaultVertical: LabelVerticalPosition = 'top';\n  const defaultHorizontal: LabelHorizontalPosition = 'center';\n  const defaultCoordinateAnchor: CardinalLabelCoordinateAnchor = 'bottom';\n\n  const resolved = resolveLabelProperties(\n    shapeOffset,\n    shapeVertical,\n    shapeHorizontal,\n    defaultOffset,\n    defaultVertical,\n    defaultHorizontal,\n    options?.lineStringLabelOffset,\n    options?.lineStringLabelVerticalAnchor,\n    options?.lineStringLabelHorizontalAnchor,\n  );\n\n  // Determine coordinate anchor (priority: shape > options > default)\n  const coordinateAnchor = (shapeCoordinateAnchor ??\n    options?.lineStringLabelCoordinateAnchor ??\n    defaultCoordinateAnchor) as CardinalLabelCoordinateAnchor;\n\n  // Calculate position based on cardinal direction\n  const coordinates = findEdgePoint(\n    geometry.coordinates as number[][],\n    coordinateAnchor,\n  );\n\n  if (!coordinates) {\n    return null;\n  }\n\n  return {\n    coordinates,\n    ...resolved,\n  };\n}\n\n/**\n * Get vertex coordinate from ring\n */\nfunction getVertexCoordinate(\n  vertex: number[] | undefined,\n): [number, number] | null {\n  if (!vertex || vertex[0] === undefined || vertex[1] === undefined) {\n    return null;\n  }\n  return [vertex[0], vertex[1]];\n}\n\n/**\n * Check if a vertex should replace the current target based on edge position\n */\nfunction shouldUpdateEdgeVertex(\n  vertexValue: number,\n  targetValue: number,\n  position: CardinalLabelCoordinateAnchor,\n): boolean {\n  // For top and right, find maximum value\n  // For bottom and left, find minimum value\n  return position === 'top' || position === 'right'\n    ? vertexValue > targetValue\n    : vertexValue < targetValue;\n}\n\n/**\n * Get the coordinate index based on edge position (0 for x/longitude, 1 for y/latitude)\n */\nfunction getCoordinateIndexForEdgePosition(\n  position: CardinalLabelCoordinateAnchor,\n): number {\n  return position === 'top' || position === 'bottom' ? 1 : 0;\n}\n\n/**\n * Calculate the centroid (center point) of a set of coordinates\n * For polygons, this calculates the geometric center\n * For lines, this calculates the midpoint of the bounding box\n * Returns null if no valid coordinates exist\n */\nfunction calculateCentroid(coordinates: number[][]): [number, number] | null {\n  if (coordinates.length === 0) {\n    return null;\n  }\n\n  let sumX = 0;\n  let sumY = 0;\n  let count = 0;\n\n  for (const coord of coordinates) {\n    if (coord && coord[0] !== undefined && coord[1] !== undefined) {\n      sumX += coord[0];\n      sumY += coord[1];\n      count++;\n    }\n  }\n\n  if (count === 0) {\n    return null;\n  }\n\n  return [sumX / count, sumY / count];\n}\n\n/**\n * Find the point on a geometry's perimeter at the specified edge position\n * @param coordinates - Array of coordinates (ring or line)\n * @param position - Edge position (center/top/right/bottom/left) relative to bounding box\n * @returns Coordinate at the specified edge position, or null if no valid coordinates\n */\nfunction findEdgePoint(\n  coordinates: number[][] | undefined,\n  position: CardinalLabelCoordinateAnchor,\n): [number, number] | null {\n  if (!coordinates || coordinates.length === 0) {\n    return null;\n  }\n\n  // Handle center positioning\n  if (position === 'center') {\n    return calculateCentroid(coordinates);\n  }\n\n  // Find the vertex with max/min latitude or longitude\n  let targetVertex = coordinates[0];\n  const coordinateIndex = getCoordinateIndexForEdgePosition(position);\n\n  for (const vertex of coordinates) {\n    if (!vertex) {\n      continue;\n    }\n    if (!targetVertex) {\n      continue;\n    }\n\n    const vertexValue = vertex[coordinateIndex];\n    const targetValue = targetVertex[coordinateIndex];\n\n    if (vertexValue === undefined || targetValue === undefined) {\n      continue;\n    }\n\n    if (shouldUpdateEdgeVertex(vertexValue, targetValue, position)) {\n      targetVertex = vertex;\n    }\n  }\n\n  return getVertexCoordinate(targetVertex);\n}\n\n/**\n * Get position for Circle geometry (special case of Polygon)\n */\nfunction getCirclePosition(\n  ring: number[][] | undefined,\n  shapeOffset: [number, number] | undefined,\n  shapeVertical: string | undefined,\n  shapeHorizontal: string | undefined,\n  shapeCoordinateAnchor: string | undefined,\n  options?: LabelPositionOptions,\n): LabelPosition2d | null {\n  const defaultOffset: [number, number] = [0, 10];\n  const defaultVertical: LabelVerticalPosition = 'top';\n  const defaultHorizontal: LabelHorizontalPosition = 'center';\n  const defaultCoordinateAnchor: CardinalLabelCoordinateAnchor = 'bottom';\n\n  const resolved = resolveLabelProperties(\n    shapeOffset,\n    shapeVertical,\n    shapeHorizontal,\n    defaultOffset,\n    defaultVertical,\n    defaultHorizontal,\n    options?.circleLabelOffset,\n    options?.circleLabelVerticalAnchor,\n    options?.circleLabelHorizontalAnchor,\n  );\n\n  // Determine coordinate anchor (priority: shape > options > default)\n  const coordinateAnchor = (shapeCoordinateAnchor ??\n    options?.circleLabelCoordinateAnchor ??\n    defaultCoordinateAnchor) as CardinalLabelCoordinateAnchor;\n\n  // Calculate position based on coordinate anchor\n  const coordinates = findEdgePoint(ring, coordinateAnchor);\n\n  if (!coordinates) {\n    return null;\n  }\n\n  return {\n    coordinates,\n    ...resolved,\n  };\n}\n\n/**\n * Get position for Polygon geometry\n * Uses cardinal direction positioning to find the edge point\n */\nfunction getPolygonPosition(\n  geometry: Polygon,\n  shape: EditableShape,\n  shapeOffset: [number, number] | undefined,\n  shapeVertical: string | undefined,\n  shapeHorizontal: string | undefined,\n  shapeCoordinateAnchor: string | undefined,\n  options?: LabelPositionOptions,\n): LabelPosition2d | null {\n  const ring = geometry.coordinates[0];\n\n  // Circle shapes use circle-specific options\n  if (shape.shapeType === 'Circle') {\n    return getCirclePosition(\n      ring,\n      shapeOffset,\n      shapeVertical,\n      shapeHorizontal,\n      shapeCoordinateAnchor,\n      options,\n    );\n  }\n\n  // Regular polygons use cardinal direction positioning\n  const defaultOffset: [number, number] = [0, 10];\n  const defaultVertical: LabelVerticalPosition = 'top';\n  const defaultHorizontal: LabelHorizontalPosition = 'center';\n  const defaultCoordinateAnchor: CardinalLabelCoordinateAnchor = 'bottom';\n\n  const resolved = resolveLabelProperties(\n    shapeOffset,\n    shapeVertical,\n    shapeHorizontal,\n    defaultOffset,\n    defaultVertical,\n    defaultHorizontal,\n    options?.polygonLabelOffset,\n    options?.polygonLabelVerticalAnchor,\n    options?.polygonLabelHorizontalAnchor,\n  );\n\n  // Determine coordinate anchor (priority: shape > options > default)\n  const coordinateAnchor = (shapeCoordinateAnchor ??\n    options?.polygonLabelCoordinateAnchor ??\n    defaultCoordinateAnchor) as CardinalLabelCoordinateAnchor;\n\n  // Calculate position based on cardinal direction\n  const coordinates = findEdgePoint(ring, coordinateAnchor);\n\n  if (!coordinates) {\n    return null;\n  }\n\n  return {\n    coordinates,\n    ...resolved,\n  };\n}\n\n/**\n * Get 2D position for label based on geometry type\n * Uses pixel-based offsets for consistent positioning at all zoom levels\n *\n * Priority for positioning:\n * 1. Per-shape properties in styleProperties (highest)\n * 2. Global labelOptions from layer props\n * 3. Default values (fallback)\n *\n * Returns null if no valid coordinates can be determined\n */\nexport function getLabelPosition2d(\n  shape: EditableShape,\n  options?: LabelPositionOptions,\n): LabelPosition2d | null {\n  const { geometry } = shape.feature;\n  const styleProps = shape.feature.properties?.styleProperties;\n\n  // Check if shape has custom label properties\n  const shapeOffset = styleProps?.labelOffset as [number, number] | undefined;\n  const shapeVertical = styleProps?.labelVerticalAnchor;\n  const shapeHorizontal = styleProps?.labelHorizontalAnchor;\n  const shapeCoordinateAnchor = styleProps?.labelCoordinateAnchor;\n\n  switch (geometry.type) {\n    case 'Point':\n      return getPointPosition(\n        geometry,\n        shapeOffset,\n        shapeVertical,\n        shapeHorizontal,\n        options,\n      );\n\n    case 'LineString':\n      return getLineStringPosition(\n        geometry,\n        shapeOffset,\n        shapeVertical,\n        shapeHorizontal,\n        shapeCoordinateAnchor,\n        options,\n      );\n\n    case 'Polygon':\n      return getPolygonPosition(\n        geometry,\n        shape,\n        shapeOffset,\n        shapeVertical,\n        shapeHorizontal,\n        shapeCoordinateAnchor,\n        options,\n      );\n\n    default:\n      // Unknown geometry type - return null\n      return null;\n  }\n}\n\n/**\n * Get label text for a shape\n *\n * Returns the display label for the shape on the map in uppercase.\n * - `label`: Optional short display name shown on the map (e.g., \"NYC\")\n * - `name`: Full shape name used internally (e.g., \"New York City Office\")\n *\n * If `label` is not provided, falls back to using `name`.\n * Text is automatically converted to uppercase for display.\n */\nexport function getLabelText(shape: EditableShape): string {\n  return (shape.label || shape.name).toUpperCase();\n}\n\n/**\n * Get label background color (uses RGB from shape fill color with fixed label opacity)\n */\nexport function getLabelFillColor(\n  shape: EditableShape,\n): [number, number, number, number] {\n  const styleProps = shape.feature.properties?.styleProperties;\n  const fillColor = styleProps?.fillColor ?? [98, 166, 255, 255];\n\n  // Extract RGB, use fixed opacity for label background\n  const r = fillColor[0] ?? 98;\n  const g = fillColor[1] ?? 166;\n  const b = fillColor[2] ?? 255;\n\n  return [r, g, b, LABEL_BACKGROUND_OPACITY];\n}\n\n/**\n * Get label border color (uses RGB from shape stroke color with full opacity)\n */\nexport function getLabelBorderColor(\n  shape: EditableShape,\n): [number, number, number, number] {\n  const styleProps = shape.feature.properties?.styleProperties;\n  const strokeColor = styleProps?.strokeColor ?? [98, 166, 255, 255];\n\n  // Extract RGB, use full opacity for border\n  const r = strokeColor[0] ?? 98;\n  const g = strokeColor[1] ?? 166;\n  const b = strokeColor[2] ?? 255;\n\n  return [r, g, b, LABEL_BORDER_OPACITY];\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,20 @@
+/*
+ * 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 { CircleProperties, CircleRadius, DisplayShape, EditableShape, ShapeFeature, ShapeFeatureProperties, ShapeFeatureType, ShapeFeatureTypeValues, ShapeId, StyleProperties } 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 { 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 };