@zendir/ui 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,84 +1,142 @@
-# @zendir/ui
-
-## 0.2.2
-
-### Features
-
-#### GroundTrackMap — Night Visualization
-
-- **Seamless night polygon** — completely rewritten terminator geometry: sunset/sunrise curves are now computed as continuous longitude pairs, producing a single closed polygon with no antimeridian artifacts. Eliminates all "jerk" lines and rendering glitches at the poles.
-- **`nightTileUrl` prop** — optional second tile layer (e.g. NASA Black Marble, VIIRS city lights) rendered beneath the terminator overlay. The graduated twilight gradient naturally masks the day-to-night tile transition. Leaflet backend only.
-- **`lightSources` prop** — array of point light sources (`LightSource` interface) rendered as soft glow dots on the night side of the map. Each light is masked by the terminator: invisible in daylight, fading in through twilight, full brightness at night. Supports custom colors, radii, intensity, and labels.
-- **Solar elevation masking** — light source visibility is computed per-point using the exact solar elevation angle (not polygon containment), giving a smooth and physically correct twilight fade for each individual light.
-
-### Documentation
-
-- **City Lights at Night** story — 35+ world cities as `lightSources`, demonstrating realistic nighttime glow.
-- **City Lights Time Travel** story — interactive UTC hour slider showing lights switching on/off as the terminator sweeps.
-- **Custom Light Sources** story — mission scenario with colored RF emitters, bases, and relay nodes.
-- **Night Tile Layer** story — demonstrates `nightTileUrl` combined with `lightSources`.
-- Updated component description with Night Tile Layer and Dynamic Light Sources sections.
-
-### Bug Fixes
-
-- Fixed terminator night polygon antimeridian wrapping — sunset and sunrise curves are now generated as continuous coordinate pairs (no `lon ± 180` mirroring), preventing the polygon from crossing the day side.
-- Removed unused `buildBandPolygon` function from Leaflet backend.
-
----
-
-## 0.2.0
-
-### Features
-
-#### SDK Category System (New)
-- **`CategoryDef`** — shared interface for a named, colored data category (`id`, `color`, `label?`), used across Timeline, GroundTrackMap, and any future component.
-- **`CategoryPalette`** — utility class that maps category IDs to stable colors and labels, with built-in fallback palettes for auto-assignment.
-- **`CategoryProvider` / `useCategoryPalette`** — optional React Context for sharing a `CategoryPalette` and a custom display label (e.g. "Squad", "Division") across an entire dashboard. Fully opt-in; components work standalone without it.
-- New Storybook documentation page (`SDK Category Concept`) with interactive examples, architecture diagrams, and integration guidance.
-
-#### UnifiedTimeline
-- **Team / category-aware events** — events now carry structured team identity (`id`, `color`, `label?`), enabling category-colored event bars and badges.
-- **Multi-select team filter** — replaces the former boolean `teamColoredOnly` toggle; users can filter by specific teams via pill-style checkboxes.
-- **`teamLabel` prop** — devs can rename "Team" to any domain-specific term (e.g. "Squad", "Division"); also readable from `CategoryProvider` context.
-- **Day markers** — `showDayMarkers` draws labeled day boundaries on multi-day timelines.
-- **Redesigned filter bar** — collapsible panel with Astro UX filter icon, search field moved to top header row, responsive breakpoints.
-- **Performance** — bounding-box culling for `ChartView` events outside the visible viewport.
-
-#### GroundTrackMap
-- **Twilight terminator with gradient zones** — realistic Civil / Nautical / Astronomical / Full Night shading derived from solar depression angle, replacing the former hard-edge day/night line. Uses `depressionDeg` for precise boundaries.
-- **Collaborative pins** — new `MapPin` interface and `pins` / `pinsEditable` / `onPinAdd` / `onPinUpdate` / `onPinRemove` props for placing colored points-of-interest synced across terminals.
-- **Enhanced satellite visualization** — `showFootprint` / `footprintRadius` for sensor coverage circles, `futureTrackIndex` for solid-past / dashed-future track split, `passMarkers` for AOS/LOS diamonds.
-- **Ground station antenna icons** — `dish`, `phased-array`, `omni`, and `relay` icon types with coverage circles and Astro status colors.
-- **Legend overlay** — auto-generated satellite + ground station legend with status indicators.
-- Category-aware pin colors via `CategoryProvider` integration.
-
-#### SimulationControls
-- Increased control-button background opacities for better visibility on dark themes.
-
-### Documentation
-- Comprehensive Storybook updates for Timeline (`WithCategoryProvider`, `MultiDayWithCategories` stories) and GroundTrackMap (`SDK Category Integration` section).
-- New `CategoryConcept` Storybook page with `PaletteBasics`, `ProviderAndHook`, and `DynamicCategories` interactive stories.
-
-### Breaking Changes
-- `TimelineEvent.color` replaced by `TimelineEvent.team` (`TimelineTeam` / `CategoryDef`). Plain string colors are still accepted for backward compatibility but are treated as legacy entries.
-- `TimelineFilter.teamColoredOnly` replaced by `TimelineFilter.teams` (multi-select `string[]`).
-
----
-
-## 0.1.0
-
-Initial public release.
-
-### Features
-
-- 60+ React components for space, air, land, and maritime operations
-- Built on Astro UX Design System
-- Themeable (Zen, Hybrid, Astro, Glass) with dark/light mode
-- ECharts-based charting (line, area, bar, radar, treemap, sankey, and more)
-- 3D viewers (Earth, Solar System, ZenSpace3D) via Three.js
-- Ground track maps (Leaflet and canvas backends)
-- Mission control widgets (MissionClock, SimulationControls, UnifiedTimeline)
-- Layout primitives (Box, Flex, Grid, Stack, Container, SideNav, SidePanel)
-- Accessibility-first (WCAG 2.2 AA oriented)
-- Design tokens as JS objects and CSS custom properties
-- Optional @zendir/sdk integration with graceful fallback
+# @zendir/ui
+
+## 0.2.4
+
+### Features
+
+#### GroundTrackMap — Layers Panel
+
+- **Layers icon + dropdown panel** — the top-right control bar now shows a stacked-diamond icon that opens a clean dropdown panel with two sections: **Base Map** (Dark/Satellite radio) and **Overlays** (toggle switches for Day/Night terminator, Grid Lines, and custom layers).
+- **Custom layers API** — pass `customLayers: MapLayerDef[]` to add your own toggle items to the Overlays section. The map provides the toggle UI; the consumer app renders its own overlay content via `onLayerChange(layerId, enabled)`.
+- **Persistent tile style** — Dark/Satellite choice is saved to `localStorage` and restored across tabs and page reloads.
+- **Unified control bar** — Recenter, Layers, and Zoom (+/−) are now a single horizontal row at top-right, replacing both the old separate controls and Leaflet's native zoom.
+- **Runtime overlay toggling** — built-in overlays (Terminator, Grid) can now be toggled on/off at runtime from the Layers panel without remounting the map.
+
+### Breaking Changes
+
+- `showMapStyleToggle` prop is still accepted but now controls whether the "Base Map" section appears in the Layers panel (default `true`).
+- Leaflet's native zoom controls have been replaced by custom-styled buttons matching the Astro UXDS dark ops aesthetic.
+
+### Documentation
+
+- **LayersPanel** story — demonstrates the full layers panel with base map toggle and overlay switches.
+- **CustomLayers** story — shows how to add developer-defined overlay toggles with `MapLayerDef[]` and respond via `onLayerChange`.
+
+---
+
+## 0.2.3
+
+### Features
+
+#### GroundTrackMap — Map Style Toggle
+
+- **Built-in Dark / Satellite tile switcher** — when no explicit `tileUrl` is passed, a compact toggle appears below the Leaflet zoom controls allowing operators to switch between Dark (CartoDB) and Satellite (Esri World Imagery) tile layers.
+- **No-flash tile swap** — toggling swaps only the tile layer without recreating the Leaflet map, preserving the current zoom, pan, and overlay state.
+- **`showMapStyleToggle` prop** — defaults to `true`. Set to `false` to hide the toggle. Automatically hidden when an explicit `tileUrl` is provided (backward compatible).
+- **`TILE_PRESETS`** — exported preset URLs (`dark`, `satellite`, `light`) for quick tile configuration.
+
+#### GroundTrackMap — Terminator Boundary Line
+
+- **Geometric terminator line** — a subtle dashed line at the 0° solar depression boundary (geometric sunset/sunrise) is now drawn on both Canvas and Leaflet backends, giving a clear visual reference for the day/night edge while the graduated fade provides the realistic transition.
+
+#### UnifiedTimeline — Playhead Auto-Follow
+
+- **Auto-scroll to playhead** — when the playhead marker moves near the edge of the visible chart viewport, the view auto-scrolls to keep it centered. Throttled at 300ms to avoid fighting user scrolling.
+- **Smooth playhead animation** — the playhead line now uses a CSS transition (`left 0.4s linear`) for glide-smooth movement between position updates.
+
+### Documentation
+
+- **Map Style Toggle** story — demonstrates the built-in tile switcher with a satellite track and terminator, including opt-out patterns.
+- Updated component description with Map Style Toggle feature.
+
+### Internal
+
+- Refactored tile layer lifecycle in `GroundTrackMapLeaflet` — tile creation is now a separate effect from map initialization, enabling smooth in-place tile swaps.
+- **Fixed duplicate tile layer on mount** — the initial mount effect no longer creates a tile layer; the dedicated tile-swap effect is solely responsible, eliminating z-order conflicts that caused the terminator overlay to render behind tiles.
+- **Attribution management** — tile swap effect now properly adds/removes Carto vs OSM attribution when switching tile styles.
+- Map controls repositioned to bottom-left for reliable visibility across container sizes.
+
+---
+
+## 0.2.2
+
+### Features
+
+#### GroundTrackMap — Night Visualization
+
+- **Seamless night polygon** — completely rewritten terminator geometry: sunset/sunrise curves are now computed as continuous longitude pairs, producing a single closed polygon with no antimeridian artifacts. Eliminates all "jerk" lines and rendering glitches at the poles.
+- **`nightTileUrl` prop** — optional second tile layer (e.g. NASA Black Marble, VIIRS city lights) rendered beneath the terminator overlay. The graduated twilight gradient naturally masks the day-to-night tile transition. Leaflet backend only.
+- **`lightSources` prop** — array of point light sources (`LightSource` interface) rendered as soft glow dots on the night side of the map. Each light is masked by the terminator: invisible in daylight, fading in through twilight, full brightness at night. Supports custom colors, radii, intensity, and labels.
+- **Solar elevation masking** — light source visibility is computed per-point using the exact solar elevation angle (not polygon containment), giving a smooth and physically correct twilight fade for each individual light.
+
+### Documentation
+
+- **City Lights at Night** story — 35+ world cities as `lightSources`, demonstrating realistic nighttime glow.
+- **City Lights Time Travel** story — interactive UTC hour slider showing lights switching on/off as the terminator sweeps.
+- **Custom Light Sources** story — mission scenario with colored RF emitters, bases, and relay nodes.
+- **Night Tile Layer** story — demonstrates `nightTileUrl` combined with `lightSources`.
+- Updated component description with Night Tile Layer and Dynamic Light Sources sections.
+
+### Bug Fixes
+
+- Fixed terminator night polygon antimeridian wrapping — sunset and sunrise curves are now generated as continuous coordinate pairs (no `lon ± 180` mirroring), preventing the polygon from crossing the day side.
+- Removed unused `buildBandPolygon` function from Leaflet backend.
+
+---
+
+## 0.2.0
+
+### Features
+
+#### SDK Category System (New)
+- **`CategoryDef`** — shared interface for a named, colored data category (`id`, `color`, `label?`), used across Timeline, GroundTrackMap, and any future component.
+- **`CategoryPalette`** — utility class that maps category IDs to stable colors and labels, with built-in fallback palettes for auto-assignment.
+- **`CategoryProvider` / `useCategoryPalette`** — optional React Context for sharing a `CategoryPalette` and a custom display label (e.g. "Squad", "Division") across an entire dashboard. Fully opt-in; components work standalone without it.
+- New Storybook documentation page (`SDK Category Concept`) with interactive examples, architecture diagrams, and integration guidance.
+
+#### UnifiedTimeline
+- **Team / category-aware events** — events now carry structured team identity (`id`, `color`, `label?`), enabling category-colored event bars and badges.
+- **Multi-select team filter** — replaces the former boolean `teamColoredOnly` toggle; users can filter by specific teams via pill-style checkboxes.
+- **`teamLabel` prop** — devs can rename "Team" to any domain-specific term (e.g. "Squad", "Division"); also readable from `CategoryProvider` context.
+- **Day markers** — `showDayMarkers` draws labeled day boundaries on multi-day timelines.
+- **Redesigned filter bar** — collapsible panel with Astro UX filter icon, search field moved to top header row, responsive breakpoints.
+- **Performance** — bounding-box culling for `ChartView` events outside the visible viewport.
+
+#### GroundTrackMap
+- **Twilight terminator with gradient zones** — realistic Civil / Nautical / Astronomical / Full Night shading derived from solar depression angle, replacing the former hard-edge day/night line. Uses `depressionDeg` for precise boundaries.
+- **Collaborative pins** — new `MapPin` interface and `pins` / `pinsEditable` / `onPinAdd` / `onPinUpdate` / `onPinRemove` props for placing colored points-of-interest synced across terminals.
+- **Enhanced satellite visualization** — `showFootprint` / `footprintRadius` for sensor coverage circles, `futureTrackIndex` for solid-past / dashed-future track split, `passMarkers` for AOS/LOS diamonds.
+- **Ground station antenna icons** — `dish`, `phased-array`, `omni`, and `relay` icon types with coverage circles and Astro status colors.
+- **Legend overlay** — auto-generated satellite + ground station legend with status indicators.
+- Category-aware pin colors via `CategoryProvider` integration.
+
+#### SimulationControls
+- Increased control-button background opacities for better visibility on dark themes.
+
+### Documentation
+- Comprehensive Storybook updates for Timeline (`WithCategoryProvider`, `MultiDayWithCategories` stories) and GroundTrackMap (`SDK Category Integration` section).
+- New `CategoryConcept` Storybook page with `PaletteBasics`, `ProviderAndHook`, and `DynamicCategories` interactive stories.
+
+### Breaking Changes
+- `TimelineEvent.color` replaced by `TimelineEvent.team` (`TimelineTeam` / `CategoryDef`). Plain string colors are still accepted for backward compatibility but are treated as legacy entries.
+- `TimelineFilter.teamColoredOnly` replaced by `TimelineFilter.teams` (multi-select `string[]`).
+
+---
+
+## 0.1.0
+
+Initial public release.
+
+### Features
+
+- 60+ React components for space, air, land, and maritime operations
+- Built on Astro UX Design System
+- Themeable (Zen, Hybrid, Astro, Glass) with dark/light mode
+- ECharts-based charting (line, area, bar, radar, treemap, sankey, and more)
+- 3D viewers (Earth, Solar System, ZenSpace3D) via Three.js
+- Ground track maps (Leaflet and canvas backends)
+- Mission control widgets (MissionClock, SimulationControls, UnifiedTimeline)
+- Layout primitives (Box, Flex, Grid, Stack, Container, SideNav, SidePanel)
+- Accessibility-first (WCAG 2.2 AA oriented)
+- Design tokens as JS objects and CSS custom properties
+- Optional @zendir/sdk integration with graceful fallback

package/dist/react/astro/UnifiedTimeline.js

@@ -1,5 +1,5 @@
 import { jsxs, jsx, Fragment } from "react/jsx-runtime";
-import { memo, useState, useCallback, useMemo, useRef } from "react";
+import { memo, useState, useCallback, useMemo, useRef, useEffect } from "react";
 import { classNames, safeAccentText } from "../utils/index.js";
 import { useCategoryPalette } from "../context/CategoryContext.js";
 import { Icon } from "../core/Icon.js";
@@ -578,6 +578,28 @@ const ChartView = memo(function ChartView2({
   const currentPlayheadTime = playheadTime || /* @__PURE__ */ new Date();
   const now = currentPlayheadTime.getTime();
   const playheadPercent = showPlayhead && now >= start.getTime() && now <= end.getTime() ? (now - start.getTime()) / totalDuration * 100 : null;
+  const lastAutoScrollRef = useRef(0);
+  useEffect(() => {
+    if (playheadPercent === null) return;
+    const container = scrollContainerRef.current;
+    if (!container) return;
+    const contentWidth = container.scrollWidth;
+    const viewportWidth = container.clientWidth;
+    if (contentWidth <= viewportWidth) return;
+    const timelineContentWidth = contentWidth - trackLabelWidth;
+    const playheadPx = trackLabelWidth + playheadPercent / 100 * timelineContentWidth;
+    const scrollLeft = container.scrollLeft;
+    const visibleLeft = scrollLeft + trackLabelWidth;
+    const visibleRight = scrollLeft + viewportWidth;
+    const margin = viewportWidth * 0.15;
+    if (playheadPx > visibleRight - margin || playheadPx < visibleLeft + margin) {
+      const nowMs = Date.now();
+      if (nowMs - lastAutoScrollRef.current < 300) return;
+      lastAutoScrollRef.current = nowMs;
+      const targetScroll = playheadPx - viewportWidth * 0.5;
+      container.scrollTo({ left: Math.max(0, targetScroll), behavior: "smooth" });
+    }
+  }, [playheadPercent, trackLabelWidth]);
   const hoveredEventData = hoveredEvent ? events.find((e) => e.id === hoveredEvent) : null;
   return /* @__PURE__ */ jsxs("div", { style: { position: "relative" }, children: [
     /* @__PURE__ */ jsx(
@@ -946,7 +968,8 @@ const ChartView = memo(function ChartView2({
                     backgroundColor: tokens.colors.accent.primary,
                     boxShadow: `0 0 12px ${tokens.colors.accent.primary}`,
                     zIndex: Z.trackEventHovered,
-                    pointerEvents: "none"
+                    pointerEvents: "none",
+                    transition: "left 0.4s linear"
                   },
                   children: [
                     /* @__PURE__ */ jsx(