@smartnet360/svelte-components 0.0.66 → 0.0.68

package/dist/map-v2/features/cells/layers/CellLabelsLayer.svelte

@@ -0,0 +1,237 @@
+<script lang="ts">
+	/**
+	 * CellLabelsLayer - Renders tech-aware cell labels positioned along azimuth
+	 * 
+	 * Features:
+	 * - Groups cells by site + azimuth (with configurable tolerance)
+	 * - Projects labels along bearing from site center
+	 * - Stacks multiple labels vertically when cells share direction
+	 * - Tech-specific field selection (2G vs 4G/5G)
+	 * - Configurable styling (size, color, halo, zoom)
+	 */
+	
+	import { onMount, onDestroy } from 'svelte';
+	import { useMapbox } from '../../../core/hooks/useMapbox';
+	import { waitForStyleLoad, generateLayerId, generateSourceId } from '../../../shared/utils/mapboxHelpers';
+	import type { CellStoreContext } from '../stores/cellStoreContext.svelte';
+	import type { Cell } from '../types';
+	import * as turf from '@turf/turf';
+	
+	interface Props {
+		/** Cell store context */
+		store: CellStoreContext;
+		/** Unique namespace for layer/source IDs */
+		namespace: string;
+	}
+	
+	let { store, namespace }: Props = $props();
+	
+	const mapStore = useMapbox();
+	const sourceId = generateSourceId(namespace, 'cell-labels');
+	const layerId = generateLayerId(namespace, 'cell-labels');
+	
+	let map = $state<mapboxgl.Map | null>(null);
+	let unsubscribe: (() => void) | null = null;
+	
+	/**
+	 * Get label text for a cell based on tech and selected field
+	 */
+	function getCellLabelText(cell: Cell, field: keyof Cell | 'none'): string {
+		if (field === 'none') return '';
+		
+		const value = cell[field];
+		return value == null ? '' : String(value);
+	}
+	
+	/**
+	 * Round azimuth to nearest tolerance value
+	 */
+	function roundAzimuth(azimuth: number, tolerance: number): number {
+		return Math.round(azimuth / tolerance) * tolerance;
+	}
+	
+	/**
+	 * Group cells by site + rounded azimuth
+	 */
+	function groupCellsByAzimuth(cells: Cell[], tolerance: number): Map<string, Cell[]> {
+		const groups = new Map<string, Cell[]>();
+		
+		cells.forEach(cell => {
+			const roundedAzimuth = roundAzimuth(cell.azimuth, tolerance);
+			const groupKey = `${cell.siteId}:${roundedAzimuth}`;
+			
+			if (!groups.has(groupKey)) {
+				groups.set(groupKey, []);
+			}
+			groups.get(groupKey)!.push(cell);
+		});
+		
+		return groups;
+	}
+	
+	/**
+	 * Build GeoJSON features for cell labels
+	 */
+	function buildLabelFeatures(): GeoJSON.FeatureCollection {
+		const features: GeoJSON.Feature[] = [];
+		
+		if (!store.showLabels || store.filteredCells.length === 0) {
+			return { type: 'FeatureCollection', features: [] };
+		}
+		
+		// Group cells by site + azimuth
+		const cellGroups = groupCellsByAzimuth(store.filteredCells, store.azimuthTolerance);
+		
+		cellGroups.forEach((cells, groupKey) => {
+			// Sort cells within group for consistent stacking
+			cells.sort((a, b) => a.id.localeCompare(b.id));
+			
+			cells.forEach((cell, index) => {
+				// Determine which fields to use based on tech
+				const is2G = cell.tech === '2G';
+				const primaryField = is2G ? store.primaryLabelField2G : store.primaryLabelField4G5G;
+				const secondaryField = is2G ? store.secondaryLabelField2G : store.secondaryLabelField4G5G;
+				
+				// Get label text
+				const primaryText = getCellLabelText(cell, primaryField);
+				const secondaryText = getCellLabelText(cell, secondaryField);
+				
+				// Build combined label (on single line with separator)
+				let labelText = primaryText;
+				if (secondaryText) {
+					labelText += ` | ${secondaryText}`;
+				}
+				
+				if (!labelText.trim()) return; // Skip if no text
+				
+				// Project label position along azimuth
+				const origin = turf.point([cell.siteLongitude, cell.siteLatitude]);
+				const labelPosition = turf.destination(
+					origin,
+					store.labelOffset / 1000, // Convert meters to kilometers
+					cell.azimuth,
+					{ units: 'kilometers' }
+				);
+				
+				// Calculate vertical offset for stacking (pixels)
+				const stackOffset = index * (store.labelSize + 4);
+				
+				features.push({
+					type: 'Feature',
+					geometry: labelPosition.geometry,
+					properties: {
+						text: labelText,
+						stackOffset,
+						cellId: cell.id
+					}
+				});
+			});
+		});
+		
+		return { type: 'FeatureCollection', features };
+	}
+	
+	/**
+	 * Update label layer on map
+	 */
+	function updateLabels() {
+		if (!map || !map.getSource(sourceId)) return;
+		
+		const geojson = buildLabelFeatures();
+		const source = map.getSource(sourceId) as mapboxgl.GeoJSONSource;
+		source.setData(geojson);
+	}
+	
+	onMount(async () => {
+		unsubscribe = mapStore.subscribe(async (m) => {
+			if (!m) {
+				map = null;
+				return;
+			}
+			
+			map = m;
+			
+			// Wait for style to load
+			await waitForStyleLoad(map);
+			
+			// Add source
+			if (!map.getSource(sourceId)) {
+				map.addSource(sourceId, {
+					type: 'geojson',
+					data: { type: 'FeatureCollection', features: [] }
+				});
+			}
+			
+			// Add label layer
+			if (!map.getLayer(layerId)) {
+				map.addLayer({
+					id: layerId,
+					type: 'symbol',
+					source: sourceId,
+					minzoom: store.minLabelZoom,
+					layout: {
+						'text-field': ['get', 'text'],
+						'text-font': ['Open Sans Regular', 'Arial Unicode MS Regular'],
+						'text-size': store.labelSize,
+						'text-anchor': 'center',
+						'text-offset': [
+							0,
+							['/', ['get', 'stackOffset'], store.labelSize] // Dynamic vertical offset
+						],
+						'text-allow-overlap': true,
+						'text-ignore-placement': false,
+						'text-max-width': 999, // Essentially disable wrapping
+						'text-justify': 'center' // Center multi-line text
+					},
+					paint: {
+						'text-color': store.labelColor,
+						'text-halo-color': store.labelHaloColor,
+						'text-halo-width': store.labelHaloWidth
+					}
+				});
+			}
+			
+			// Initial render
+			updateLabels();
+		});
+	});
+	
+	// Watch for changes in store properties and update labels
+	$effect(() => {
+		// Dependencies that should trigger label refresh
+		store.filteredCells;
+		store.showLabels;
+		store.primaryLabelField4G5G;
+		store.secondaryLabelField4G5G;
+		store.primaryLabelField2G;
+		store.secondaryLabelField2G;
+		store.labelOffset;
+		store.azimuthTolerance;
+		
+		updateLabels();
+	});
+	
+	// Watch for style changes and update layer paint/layout properties
+	$effect(() => {
+		if (!map || !map.getLayer(layerId)) return;
+		
+		map.setLayoutProperty(layerId, 'text-size', store.labelSize);
+		map.setPaintProperty(layerId, 'text-color', store.labelColor);
+		map.setPaintProperty(layerId, 'text-halo-color', store.labelHaloColor);
+		map.setPaintProperty(layerId, 'text-halo-width', store.labelHaloWidth);
+		map.setLayerZoomRange(layerId, store.minLabelZoom, 24);
+	});
+	
+	onDestroy(() => {
+		unsubscribe?.();
+		
+		if (map) {
+			if (map.getLayer(layerId)) {
+				map.removeLayer(layerId);
+			}
+			if (map.getSource(sourceId)) {
+				map.removeSource(sourceId);
+			}
+		}
+	});
+</script>

package/dist/map-v2/features/cells/layers/CellLabelsLayer.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { CellStoreContext } from '../stores/cellStoreContext.svelte';
+interface Props {
+    /** Cell store context */
+    store: CellStoreContext;
+    /** Unique namespace for layer/source IDs */
+    namespace: string;
+}
+declare const CellLabelsLayer: import("svelte").Component<Props, {}, "">;
+type CellLabelsLayer = ReturnType<typeof CellLabelsLayer>;
+export default CellLabelsLayer;

package/dist/map-v2/features/cells/stores/cellStoreContext.svelte.d.ts

@@ -13,6 +13,18 @@ export interface CellStoreValue {
     lineWidth: number;
     fillOpacity: number;
     baseRadius: number;
+    showLabels: boolean;
+    primaryLabelField4G5G: keyof Cell;
+    secondaryLabelField4G5G: keyof Cell | 'none';
+    primaryLabelField2G: keyof Cell;
+    secondaryLabelField2G: keyof Cell | 'none';
+    labelSize: number;
+    labelColor: string;
+    labelOffset: number;
+    labelHaloColor: string;
+    labelHaloWidth: number;
+    minLabelZoom: number;
+    azimuthTolerance: number;
     statusStyles: Map<CellStatus, CellStatusStyle>;
     groupingConfig: CellTreeConfig;
     groupColorMap: Map<string, string>;
@@ -32,6 +44,18 @@ export interface CellStoreContext {
     readonly groupingConfig: CellTreeConfig;
     readonly groupColorMap: Map<string, string>;
     readonly cellGroupMap: Map<string, string>;
+    readonly showLabels: boolean;
+    readonly primaryLabelField4G5G: keyof Cell;
+    readonly secondaryLabelField4G5G: keyof Cell | 'none';
+    readonly primaryLabelField2G: keyof Cell;
+    readonly secondaryLabelField2G: keyof Cell | 'none';
+    readonly labelSize: number;
+    readonly labelColor: string;
+    readonly labelOffset: number;
+    readonly labelHaloColor: string;
+    readonly labelHaloWidth: number;
+    readonly minLabelZoom: number;
+    readonly azimuthTolerance: number;
     setFilteredCells(cells: Cell[]): void;
     setIncludePlannedCells(value: boolean): void;
     setShowCells(value: boolean): void;
@@ -46,6 +70,18 @@ export interface CellStoreContext {
     getGroupColor(groupKey: string): string | undefined;
     setGroupColor(groupKey: string, color: string): void;
     clearGroupColor(groupKey: string): void;
+    setShowLabels(value: boolean): void;
+    setPrimaryLabelField4G5G(field: keyof Cell): void;
+    setSecondaryLabelField4G5G(field: keyof Cell | 'none'): void;
+    setPrimaryLabelField2G(field: keyof Cell): void;
+    setSecondaryLabelField2G(field: keyof Cell | 'none'): void;
+    setLabelSize(value: number): void;
+    setLabelColor(value: string): void;
+    setLabelOffset(value: number): void;
+    setLabelHaloColor(value: string): void;
+    setLabelHaloWidth(value: number): void;
+    setMinLabelZoom(value: number): void;
+    setAzimuthTolerance(value: number): void;
 }
 /**
  * Create a cell store context with reactive state

package/dist/map-v2/features/cells/stores/cellStoreContext.svelte.js

@@ -57,7 +57,20 @@ export function createCellStoreContext(cells) {
         groupingConfig: persistedSettings.groupingConfig ?? DEFAULT_CELL_TREE_CONFIG,
         groupColorMap: initialColorMap,
         cellGroupMap: new Map(), // Will be populated when tree is built
-        currentZoom: 12 // Default zoom
+        currentZoom: 12, // Default zoom
+        // Label settings with defaults
+        showLabels: persistedSettings.showLabels ?? false,
+        primaryLabelField4G5G: (persistedSettings.primaryLabelField4G5G ?? 'fband'),
+        secondaryLabelField4G5G: (persistedSettings.secondaryLabelField4G5G ?? 'none'),
+        primaryLabelField2G: (persistedSettings.primaryLabelField2G ?? 'bcch'),
+        secondaryLabelField2G: (persistedSettings.secondaryLabelField2G ?? 'none'),
+        labelSize: persistedSettings.labelSize ?? 12,
+        labelColor: persistedSettings.labelColor ?? '#000000',
+        labelOffset: persistedSettings.labelOffset ?? 300,
+        labelHaloColor: persistedSettings.labelHaloColor ?? '#ffffff',
+        labelHaloWidth: persistedSettings.labelHaloWidth ?? 1,
+        minLabelZoom: persistedSettings.minLabelZoom ?? 14,
+        azimuthTolerance: persistedSettings.azimuthTolerance ?? 5
     });
     // Derived: Filter cells by status based on includePlannedCells flag
     // IMPORTANT: This is a pure $derived - it only READS from state, never writes
@@ -79,7 +92,20 @@ export function createCellStoreContext(cells) {
             fillOpacity: state.fillOpacity,
             baseRadius: state.baseRadius,
             groupingConfig: state.groupingConfig,
-            groupColors: groupColorsObj
+            groupColors: groupColorsObj,
+            // Label settings
+            showLabels: state.showLabels,
+            primaryLabelField4G5G: state.primaryLabelField4G5G,
+            secondaryLabelField4G5G: state.secondaryLabelField4G5G,
+            primaryLabelField2G: state.primaryLabelField2G,
+            secondaryLabelField2G: state.secondaryLabelField2G,
+            labelSize: state.labelSize,
+            labelColor: state.labelColor,
+            labelOffset: state.labelOffset,
+            labelHaloColor: state.labelHaloColor,
+            labelHaloWidth: state.labelHaloWidth,
+            minLabelZoom: state.minLabelZoom,
+            azimuthTolerance: state.azimuthTolerance
         };
         saveSettings(settings);
     });
@@ -107,6 +133,19 @@ export function createCellStoreContext(cells) {
         get groupingConfig() { return state.groupingConfig; },
         get groupColorMap() { return state.groupColorMap; },
         get cellGroupMap() { return state.cellGroupMap; },
+        // Label getters
+        get showLabels() { return state.showLabels; },
+        get primaryLabelField4G5G() { return state.primaryLabelField4G5G; },
+        get secondaryLabelField4G5G() { return state.secondaryLabelField4G5G; },
+        get primaryLabelField2G() { return state.primaryLabelField2G; },
+        get secondaryLabelField2G() { return state.secondaryLabelField2G; },
+        get labelSize() { return state.labelSize; },
+        get labelColor() { return state.labelColor; },
+        get labelOffset() { return state.labelOffset; },
+        get labelHaloColor() { return state.labelHaloColor; },
+        get labelHaloWidth() { return state.labelHaloWidth; },
+        get minLabelZoom() { return state.minLabelZoom; },
+        get azimuthTolerance() { return state.azimuthTolerance; },
         // Methods
         setFilteredCells(cells) {
             state.filteredCells = cells;
@@ -152,6 +191,43 @@ export function createCellStoreContext(cells) {
         clearGroupColor(groupKey) {
             state.groupColorMap.delete(groupKey);
             state.groupColorMap = new Map(state.groupColorMap);
+        },
+        // Label setters
+        setShowLabels(value) {
+            state.showLabels = value;
+        },
+        setPrimaryLabelField4G5G(field) {
+            state.primaryLabelField4G5G = field;
+        },
+        setSecondaryLabelField4G5G(field) {
+            state.secondaryLabelField4G5G = field;
+        },
+        setPrimaryLabelField2G(field) {
+            state.primaryLabelField2G = field;
+        },
+        setSecondaryLabelField2G(field) {
+            state.secondaryLabelField2G = field;
+        },
+        setLabelSize(value) {
+            state.labelSize = value;
+        },
+        setLabelColor(value) {
+            state.labelColor = value;
+        },
+        setLabelOffset(value) {
+            state.labelOffset = value;
+        },
+        setLabelHaloColor(value) {
+            state.labelHaloColor = value;
+        },
+        setLabelHaloWidth(value) {
+            state.labelHaloWidth = value;
+        },
+        setMinLabelZoom(value) {
+            state.minLabelZoom = value;
+        },
+        setAzimuthTolerance(value) {
+            state.azimuthTolerance = value;
         }
     };
 }

package/dist/map-v2/features/cells/types.d.ts

@@ -82,13 +82,19 @@ export interface ParsedTechBand {
 }
 /**
  * Available fields for grouping cells in the filter tree
+ * Now accepts any property key from Cell interface
  */
-export type CellGroupingField = 'tech' | 'band' | 'status' | 'siteId' | 'customSubgroup' | 'type' | 'planner' | 'none';
+export type CellGroupingField = keyof Cell | 'none';
+/**
+ * Optional label map for human-readable field names
+ * Maps field keys to display labels
+ */
+export type CellGroupingLabels = Partial<Record<CellGroupingField, string>>;
 /**
  * Configuration for dynamic tree grouping
  */
 export interface CellTreeConfig {
-    /** Primary grouping field (required) */
+    /** Primary grouping field (required, cannot be 'none') */
     level1: Exclude<CellGroupingField, 'none'>;
     /** Secondary grouping field (optional, can be 'none') */
     level2: CellGroupingField;

package/dist/map-v2/features/cells/types.js

@@ -8,5 +8,5 @@
  */
 export const DEFAULT_CELL_TREE_CONFIG = {
     level1: 'tech',
-    level2: 'band'
+    level2: 'frq'
 };

package/dist/map-v2/features/cells/utils/cellTree.d.ts

@@ -2,9 +2,9 @@
  * Cell Tree Builder
  *
  * Build hierarchical tree structure for cell filtering
- * Structure: Tech → Band → Status → Individual Cells (configurable)
+ * Structure: Configurable hierarchy with any Cell properties
  */
-import type { Cell, CellTreeConfig } from '../types';
+import type { Cell, CellTreeConfig, CellGroupingLabels } from '../types';
 import type { TreeNode } from '../../../../core/TreeView/tree.model';
 /**
  * Build hierarchical tree from flat cell array with dynamic grouping
@@ -12,9 +12,10 @@ import type { TreeNode } from '../../../../core/TreeView/tree.model';
  * @param cells - Array of cells to build tree from
  * @param config - Grouping configuration (level1, level2)
  * @param colorMap - Optional map of leaf group IDs to custom colors
+ * @param labelMap - Optional map of field keys to human-readable labels
  * @returns Object with tree and cell-to-group lookup map
  */
-export declare function buildCellTree(cells: Cell[], config: CellTreeConfig, colorMap?: Map<string, string>): {
+export declare function buildCellTree(cells: Cell[], config: CellTreeConfig, colorMap?: Map<string, string>, labelMap?: CellGroupingLabels): {
     tree: TreeNode;
     cellGroupMap: Map<string, string>;
 };

package/dist/map-v2/features/cells/utils/cellTree.js

@@ -2,55 +2,54 @@
  * Cell Tree Builder
  *
  * Build hierarchical tree structure for cell filtering
- * Structure: Tech → Band → Status → Individual Cells (configurable)
+ * Structure: Configurable hierarchy with any Cell properties
  */
+/**
+ * Smart sort comparator that handles numeric suffixes
+ *
+ * Examples:
+ *   "700", "1800" → sorted as 700, 1800 (numeric)
+ *   "LTE700", "LTE1800" → sorted as 700, 1800 (numeric suffix)
+ *   "On_Air", "Planned" → sorted alphabetically
+ *
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @returns Sort order (-1, 0, 1)
+ */
+function smartSort(a, b) {
+    // Extract trailing 3-4 digits
+    const numRegex = /(\d{3,4})$/;
+    const matchA = a.match(numRegex);
+    const matchB = b.match(numRegex);
+    // If both have numeric suffixes, compare numerically
+    if (matchA && matchB) {
+        const numA = parseInt(matchA[1], 10);
+        const numB = parseInt(matchB[1], 10);
+        return numA - numB;
+    }
+    // Otherwise alphabetical
+    return a.localeCompare(b);
+}
 /**
  * Get the value of a grouping field from a cell
  */
 function getGroupingValue(cell, field) {
-    switch (field) {
-        case 'tech':
-            return cell.tech;
-        case 'band':
-            return cell.frq; // Use numeric band from 'frq' field
-        case 'status':
-            return cell.status;
-        case 'siteId':
-            return cell.siteId;
-        case 'customSubgroup':
-            return cell.customSubgroup || 'Ungrouped';
-        case 'type':
-            return cell.type;
-        case 'planner':
-            return cell.planner || 'Unassigned';
-        case 'none':
-            return '';
-        default:
-            return 'Unknown';
-    }
+    if (field === 'none')
+        return '';
+    const value = cell[field];
+    // Handle null/undefined
+    if (value == null)
+        return 'Unassigned';
+    // Convert to string
+    return String(value);
 }
 /**
  * Get a human-readable label for a grouping field value
  */
-function getGroupLabel(field, value, count) {
-    switch (field) {
-        case 'tech':
-            return `${value} (${count})`;
-        case 'band':
-            return `${value} MHz (${count})`;
-        case 'status':
-            return `${value} (${count})`;
-        case 'siteId':
-            return `${value} (${count})`;
-        case 'customSubgroup':
-            return `${value} (${count})`;
-        case 'type':
-            return `${value} (${count})`;
-        case 'planner':
-            return `${value} (${count})`;
-        default:
-            return `${value} (${count})`;
-    }
+function getGroupLabel(field, value, count, labelMap) {
+    // Use custom label if provided
+    const fieldLabel = labelMap?.[field] || String(field);
+    return `${value} (${count})`;
 }
 /**
  * Generate a unique node ID based on grouping path
@@ -67,21 +66,22 @@ function generateNodeId(field, value, parentId) {
  * @param cells - Array of cells to build tree from
  * @param config - Grouping configuration (level1, level2)
  * @param colorMap - Optional map of leaf group IDs to custom colors
+ * @param labelMap - Optional map of field keys to human-readable labels
  * @returns Object with tree and cell-to-group lookup map
  */
-export function buildCellTree(cells, config, colorMap) {
+export function buildCellTree(cells, config, colorMap, labelMap) {
     const { level1, level2 } = config;
     // If level2 is 'none', create flat 2-level tree
     if (level2 === 'none') {
-        return buildFlatTree(cells, level1, colorMap);
+        return buildFlatTree(cells, level1, colorMap, labelMap);
     }
     // Otherwise, create nested 3-level tree
-    return buildNestedTree(cells, level1, level2, colorMap);
+    return buildNestedTree(cells, level1, level2, colorMap, labelMap);
 }
 /**
  * Build flat 2-level tree (Root → Level1 groups)
  */
-function buildFlatTree(cells, level1, colorMap) {
+function buildFlatTree(cells, level1, colorMap, labelMap) {
     // Group cells by level1 field
     const groups = new Map();
     const cellGroupMap = new Map();
@@ -92,8 +92,8 @@ function buildFlatTree(cells, level1, colorMap) {
         }
         groups.get(value).push(cell);
     });
-    // Sort groups alphabetically
-    const sortedGroups = Array.from(groups.entries()).sort(([a], [b]) => a.localeCompare(b));
+    // Sort groups with smart numeric/alphabetical sorting
+    const sortedGroups = Array.from(groups.entries()).sort(([a], [b]) => smartSort(a, b));
     // Build tree nodes and populate cellGroupMap
     const children = sortedGroups.map(([value, groupCells]) => {
         const nodeId = generateNodeId(level1, value);
@@ -105,7 +105,7 @@ function buildFlatTree(cells, level1, colorMap) {
         });
         return {
             id: nodeId,
-            label: getGroupLabel(level1, value, groupCells.length),
+            label: getGroupLabel(level1, value, groupCells.length, labelMap),
             defaultChecked: true,
             children: [],
             metadata: {
@@ -131,7 +131,7 @@ function buildFlatTree(cells, level1, colorMap) {
 /**
  * Build nested 3-level tree (Root → Level1 → Level2 groups)
  */
-function buildNestedTree(cells, level1, level2, colorMap) {
+function buildNestedTree(cells, level1, level2, colorMap, labelMap) {
     // Group cells by level1, then by level2
     const level1Groups = new Map();
     const cellGroupMap = new Map();
@@ -147,13 +147,13 @@ function buildNestedTree(cells, level1, level2, colorMap) {
         }
         level2Groups.get(value2).push(cell);
     });
-    // Sort level1 groups
-    const sortedLevel1 = Array.from(level1Groups.entries()).sort(([a], [b]) => a.localeCompare(b));
+    // Sort level1 groups with smart numeric/alphabetical sorting
+    const sortedLevel1 = Array.from(level1Groups.entries()).sort(([a], [b]) => smartSort(a, b));
     // Build tree nodes and populate cellGroupMap
     const children = sortedLevel1.map(([value1, level2Groups]) => {
         const parentId = generateNodeId(level1, value1);
-        // Sort level2 groups
-        const sortedLevel2 = Array.from(level2Groups.entries()).sort(([a], [b]) => a.localeCompare(b));
+        // Sort level2 groups with smart numeric/alphabetical sorting
+        const sortedLevel2 = Array.from(level2Groups.entries()).sort(([a], [b]) => smartSort(a, b));
         const level2Children = sortedLevel2.map(([value2, groupCells]) => {
             const nodeId = generateNodeId(level2, value2, parentId);
             const color = colorMap?.get(nodeId);
@@ -164,7 +164,7 @@ function buildNestedTree(cells, level1, level2, colorMap) {
             });
             return {
                 id: nodeId,
-                label: getGroupLabel(level2, value2, groupCells.length),
+                label: getGroupLabel(level2, value2, groupCells.length, labelMap),
                 defaultChecked: true,
                 children: [],
                 metadata: {
@@ -182,7 +182,7 @@ function buildNestedTree(cells, level1, level2, colorMap) {
         const totalCells = Array.from(level2Groups.values()).flat().length;
         return {
             id: parentId,
-            label: getGroupLabel(level1, value1, totalCells),
+            label: getGroupLabel(level1, value1, totalCells, labelMap),
             defaultChecked: true,
             children: level2Children,
             metadata: {

package/dist/map-v2/index.d.ts

@@ -4,8 +4,8 @@
  * A decoupled, feature-based architecture for Mapbox cellular network visualization.
  * Each feature (sites, cells) is completely independent with its own store, layers, and controls.
  */
-export { type MapStore, MAP_CONTEXT_KEY, MapboxProvider, ViewportSync, MapStyleControl, createMapStore, createViewportStore, type ViewportStore, type ViewportState, useMapbox, tryUseMapbox } from './core';
+export { type MapStore, MAP_CONTEXT_KEY, MapboxProvider, ViewportSync, MapStoreBridge, MapStyleControl, createMapStore, createViewportStore, type ViewportStore, type ViewportState, useMapbox, tryUseMapbox } from './core';
 export { MapControl, addSourceIfMissing, removeSourceIfExists, addLayerIfMissing, removeLayerIfExists, updateGeoJSONSource, removeLayerAndSource, isStyleLoaded, waitForStyleLoad, setFeatureState, removeFeatureState, generateLayerId, generateSourceId } from './shared';
-export { type Site, type SiteStoreValue, type SiteStoreContext, createSiteStore, createSiteStoreContext, SitesLayer, SiteFilterControl, SiteSizeSlider, sitesToGeoJSON, siteToFeature, buildSiteTree, getFilteredSites } from './features/sites';
-export { type Cell, type CellStatus, type CellStatusStyle, type CellGroupingField, type CellTreeConfig, type TechnologyBandKey, type CellStoreValue, type CellStoreContext, createCellStoreContext, CellsLayer, CellFilterControl, CellStyleControl, cellsToGeoJSON, buildCellTree, getFilteredCells, calculateRadius, getZoomFactor, createArcPolygon, DEFAULT_CELL_TREE_CONFIG, TECHNOLOGY_BAND_COLORS, DEFAULT_STATUS_STYLES, RADIUS_MULTIPLIER } from './features/cells';
+export { type Site, type SiteStoreValue, type SiteStoreContext, createSiteStore, createSiteStoreContext, SitesLayer, SiteFilterControl, SiteSelectionControl, SiteSizeSlider, sitesToGeoJSON, siteToFeature, buildSiteTree, getFilteredSites } from './features/sites';
+export { type Cell, type CellStatus, type CellStatusStyle, type CellGroupingField, type CellGroupingLabels, type CellTreeConfig, type TechnologyBandKey, type CellStoreValue, type CellStoreContext, createCellStoreContext, CellsLayer, CellLabelsLayer, CellFilterControl, CellStyleControl, cellsToGeoJSON, buildCellTree, getFilteredCells, calculateRadius, getZoomFactor, createArcPolygon, DEFAULT_CELL_TREE_CONFIG, TECHNOLOGY_BAND_COLORS, DEFAULT_STATUS_STYLES, RADIUS_MULTIPLIER } from './features/cells';
 export { DemoMap, demoSites, demoCells } from './demo';