@zendir/ui 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @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

package/dist/react/charts/GroundTrackMap.d.ts

@@ -83,6 +83,29 @@ export interface MapPin {
     /** Who placed the pin (display-only; not enforced) */
     createdBy?: string;
 }
+/**
+ * A point light source rendered on the night side of the map.
+ * Use this to display city lights, base locations, RF emitters,
+ * or any glow that should only be visible after sunset.
+ *
+ * Light sources are masked by the terminator — they fade in
+ * through the twilight gradient and reach full brightness in
+ * deep night, matching real-world light-pollution behavior.
+ */
+export interface LightSource {
+    /** Latitude in degrees (−90 … 90) */
+    latitude: number;
+    /** Longitude in degrees (−180 … 180) */
+    longitude: number;
+    /** Glow radius in pixels (default 4). Larger values create wider halos. */
+    radius?: number;
+    /** Glow intensity 0–1 (default 0.8). Controls the peak alpha of the light dot. */
+    intensity?: number;
+    /** Light color — any CSS color string (default '#ffeedd', warm white). */
+    color?: string;
+    /** Optional label shown on hover (Leaflet) or in tooltip (Canvas). */
+    label?: string;
+}
 export interface GroundTrackMapProps {
     /** Single satellite ground track (legacy API) */
     groundTrack?: GroundTrackPoint[];
@@ -132,6 +155,25 @@ export interface GroundTrackMapProps {
     mapProvider?: 'leaflet' | 'canvas';
     /** Tile URL for Leaflet (default: CartoDB dark). Ignored when mapProvider is 'canvas'. */
     tileUrl?: string;
+    /**
+     * URL template for a "night" tile layer (e.g. NASA Black Marble, VIIRS city lights).
+     * When provided, this layer is rendered beneath the terminator overlay so that it
+     * appears only on the night side of the map — creating a realistic day/night transition.
+     * The day tiles remain visible on the sunlit side.
+     *
+     * Requires `showTerminator` to be enabled. Leaflet backend only.
+     *
+     * Example: `'https://map1.vis.earthdata.nasa.gov/wmts-webmerc/VIIRS_CityLights_2012/...'`
+     */
+    nightTileUrl?: string;
+    /**
+     * Array of point light sources rendered on the night side of the map.
+     * Each light appears as a soft glow dot that is masked by the terminator —
+     * invisible in daylight, fading in through twilight, full brightness at night.
+     *
+     * Use cases: city lights, base indicators, RF emitters, targets, population centers.
+     */
+    lightSources?: LightSource[];
     /** Array of user-placed pins displayed on the map */
     pins?: MapPin[];
     /**
@@ -147,5 +189,5 @@ export interface GroundTrackMapProps {
     /** Called when the user removes a pin */
     onPinRemove?: (pinId: string) => void;
 }
-export declare function GroundTrackMap({ groundTrack, satellites, groundStations, accessMask, teamPaths, showTerminator, terminatorTime, showGrid, showLegend, showEquator, showRecenterButton, isLoading, emptyMessage, width, height, minHeight, defaultCenter, defaultZoom, className, onSatelliteClick, onStationClick, mapProvider, tileUrl, pins, pinsEditable, onPinAdd, onPinUpdate, onPinRemove, }: GroundTrackMapProps): React.ReactElement;
+export declare function GroundTrackMap({ groundTrack, satellites, groundStations, accessMask, teamPaths, showTerminator, terminatorTime, showGrid, showLegend, showEquator, showRecenterButton, isLoading, emptyMessage, width, height, minHeight, defaultCenter, defaultZoom, className, onSatelliteClick, onStationClick, mapProvider, tileUrl, nightTileUrl, lightSources, pins, pinsEditable, onPinAdd, onPinUpdate, onPinRemove, }: GroundTrackMapProps): React.ReactElement;
 export default GroundTrackMap;

package/dist/react/charts/GroundTrackMap.js

@@ -68,25 +68,47 @@ function drawCoverageEllipse(ctx, centerLat, centerLon, radiusDeg, W, H, lonToX,
   }
   ctx.closePath();
 }
-function calculateTerminator(date, depressionDeg = 0, numPoints = 72) {
+function hexToRgb(hex) {
+  const h = hex.replace("#", "");
+  if (h.length === 3) {
+    return [parseInt(h[0] + h[0], 16), parseInt(h[1] + h[1], 16), parseInt(h[2] + h[2], 16)];
+  }
+  if (h.length >= 6) {
+    return [parseInt(h.slice(0, 2), 16), parseInt(h.slice(2, 4), 16), parseInt(h.slice(4, 6), 16)];
+  }
+  return [255, 238, 221];
+}
+function calculateTerminatorContinuous(date, depressionDeg = 0, numPoints = 360) {
   const dayOfYear = Math.floor((date.getTime() - new Date(date.getFullYear(), 0, 0).getTime()) / 864e5);
   const declination = -23.44 * Math.cos(2 * Math.PI / 365 * (dayOfYear + 10));
   const decRad = declination * Math.PI / 180;
   const hourAngle = (date.getUTCHours() + date.getUTCMinutes() / 60) / 24 * 360 - 180;
   const depRad = depressionDeg * Math.PI / 180;
-  const points = [];
+  const sunset = [];
+  const sunrise = [];
   for (let i = 0; i <= numPoints; i++) {
-    const latRad = (i / numPoints * 180 - 90) * (Math.PI / 180);
+    const lat = -89.999 + i / numPoints * 179.998;
+    const latRad = lat * (Math.PI / 180);
     const cosH = -(Math.sin(depRad) + Math.sin(latRad) * Math.sin(decRad)) / (Math.cos(latRad) * Math.cos(decRad));
-    let lon;
-    if (cosH < -1) lon = hourAngle + 180;
-    else if (cosH > 1) lon = hourAngle;
-    else lon = hourAngle + Math.acos(cosH) * 180 / Math.PI;
-    while (lon > 180) lon -= 360;
-    while (lon < -180) lon += 360;
-    points.push({ lat: i / numPoints * 180 - 90, lon });
+    if (cosH < -1) ;
+    else if (cosH > 1) {
+      sunset.push([lat, hourAngle]);
+      sunrise.push([lat, hourAngle + 360]);
+    } else {
+      const H = Math.acos(cosH) * 180 / Math.PI;
+      sunset.push([lat, hourAngle + H]);
+      sunrise.push([lat, hourAngle + 360 - H]);
+    }
   }
-  return points;
+  return { sunset, sunrise };
+}
+function buildNightPolygon(terminator) {
+  const { sunset, sunrise } = terminator;
+  if (!sunset.length || !sunrise.length) return [];
+  const poly = [];
+  poly.push(...sunset);
+  poly.push(...[...sunrise].reverse());
+  return poly;
 }
 function GroundTrackMap({
   groundTrack,
@@ -112,6 +134,8 @@ function GroundTrackMap({
   onStationClick,
   mapProvider = "leaflet",
   tileUrl,
+  nightTileUrl,
+  lightSources,
   pins,
   pinsEditable = false,
   onPinAdd,
@@ -202,63 +226,52 @@ function GroundTrackMap({
     ctx.fillRect(0, 0, W, H);
     if (showTerminator) {
       const now = terminatorTime ?? /* @__PURE__ */ new Date();
-      const twilightZones = [
-        { depression: 6, alpha: 0.08 },
-        // civil twilight
-        { depression: 12, alpha: 0.1 },
-        // nautical twilight
-        { depression: 18, alpha: 0.12 },
-        // astronomical twilight
-        { depression: 90, alpha: 0.22 }
-        // full night (beyond 18°)
-      ];
-      const normLon = (l) => {
-        let r = l;
-        while (r > 180) r -= 360;
-        while (r < -180) r += 360;
-        return r;
-      };
-      const fillNightSide = (terminator, isSunrise) => {
-        ctx.beginPath();
-        if (isSunrise) {
-          ctx.moveTo(0, 0);
-          ctx.lineTo(0, H);
-        } else {
-          ctx.moveTo(W, 0);
-          ctx.lineTo(W, H);
+      const BAND_STEP = 2;
+      const MAX_DEP = 24;
+      const NIGHT_ALPHA = 0.55;
+      const bandSteps = [];
+      for (let d = 0; d <= MAX_DEP; d += BAND_STEP) {
+        const t = Math.min(d / 18, 1);
+        const alpha = t * t * (NIGHT_ALPHA * 0.82) + (d > 18 ? (d - 18) / 6 * (NIGHT_ALPHA * 0.18) : 0);
+        bandSteps.push({ depression: d, alpha: Math.min(alpha, NIGHT_ALPHA) });
+      }
+      bandSteps.push({ depression: 90, alpha: NIGHT_ALPHA });
+      let prevAlpha = 0;
+      for (const zone of bandSteps) {
+        const dep = Math.min(zone.depression, 89);
+        const bandAlpha = zone.alpha - prevAlpha;
+        if (bandAlpha < 2e-3) {
+          prevAlpha = zone.alpha;
+          continue;
         }
-        let prevX = isSunrise ? 0 : W;
-        for (let i = terminator.length - 1; i >= 0; i--) {
-          const tLon = isSunrise ? normLon(terminator[i].lon - 180) : terminator[i].lon;
-          const x = lonToX(tLon, W);
-          const y = latToY(terminator[i].lat, H);
-          if (Math.abs(x - prevX) > W * 0.5 && i < terminator.length - 1) {
-            const edgeX = isSunrise ? prevX < W / 2 ? 0 : W : prevX > W / 2 ? W : 0;
-            ctx.lineTo(edgeX, y);
-            ctx.closePath();
-            ctx.fill();
-            ctx.beginPath();
-            ctx.moveTo(isSunrise ? 0 : W, y);
-          }
-          ctx.lineTo(x, y);
-          prevX = x;
+        const terminator = calculateTerminatorContinuous(now, dep);
+        if (terminator.sunset.length === 0) {
+          prevAlpha = zone.alpha;
+          continue;
         }
-        ctx.closePath();
-        ctx.fill();
-      };
-      let prevTerminator = null;
-      for (const zone of twilightZones) {
-        const dep = Math.min(zone.depression, 89);
-        const terminator = calculateTerminator(now, dep);
-        ctx.fillStyle = `rgba(0, 6, 24, ${zone.alpha})`;
-        if (prevTerminator) {
-          fillNightSide(terminator, false);
-          fillNightSide(terminator, true);
-        } else {
-          fillNightSide(terminator, false);
-          fillNightSide(terminator, true);
+        const poly = buildNightPolygon(terminator);
+        if (poly.length < 3) {
+          prevAlpha = zone.alpha;
+          continue;
+        }
+        ctx.fillStyle = `rgba(0, 6, 24, ${bandAlpha.toFixed(4)})`;
+        for (const offset of [-360, 0, 360]) {
+          ctx.beginPath();
+          for (let i = 0; i < poly.length; i++) {
+            const lat = poly[i][0];
+            const lon = poly[i][1] + offset;
+            const x = lonToX(lon, W);
+            const y = latToY(lat, H);
+            if (i === 0) {
+              ctx.moveTo(x, y);
+            } else {
+              ctx.lineTo(x, y);
+            }
+          }
+          ctx.closePath();
+          ctx.fill();
         }
-        prevTerminator = terminator;
+        prevAlpha = zone.alpha;
       }
     }
     ctx.fillStyle = COLORS.land;
@@ -482,6 +495,42 @@ function GroundTrackMap({
       ctx.textAlign = "center";
       ctx.fillText(gs.name.length > 14 ? gs.name.slice(0, 14) + "…" : gs.name, x, y + halfIcon + 12);
     }
+    if (lightSources && lightSources.length > 0 && showTerminator) {
+      const now = terminatorTime ?? /* @__PURE__ */ new Date();
+      for (const light of lightSources) {
+        const lx = lonToX(light.longitude, W);
+        const ly = latToY(light.latitude, H);
+        const r = light.radius ?? 4;
+        const intensity = light.intensity ?? 0.8;
+        const color = light.color ?? "#ffeedd";
+        const dayOfYear = Math.floor((now.getTime() - new Date(now.getFullYear(), 0, 0).getTime()) / 864e5);
+        const declination = -23.44 * Math.cos(2 * Math.PI / 365 * (dayOfYear + 10));
+        const decRad = declination * Math.PI / 180;
+        const hourAngle = (now.getUTCHours() + now.getUTCMinutes() / 60) / 24 * 360 - 180;
+        const latRad = light.latitude * Math.PI / 180;
+        const sinAlt = Math.sin(latRad) * Math.sin(decRad) + Math.cos(latRad) * Math.cos(decRad) * Math.cos((light.longitude - hourAngle) * Math.PI / 180);
+        const solarAltDeg = Math.asin(sinAlt) * 180 / Math.PI;
+        let nightFactor;
+        if (solarAltDeg >= 0) nightFactor = 0;
+        else if (solarAltDeg <= -18) nightFactor = 1;
+        else nightFactor = Math.min(1, -solarAltDeg / 18);
+        if (nightFactor < 0.01) continue;
+        const alpha = intensity * nightFactor;
+        const [cr, cg, cb] = hexToRgb(color);
+        const grad = ctx.createRadialGradient(lx, ly, 0, lx, ly, r * 2);
+        grad.addColorStop(0, `rgba(${cr}, ${cg}, ${cb}, ${alpha})`);
+        grad.addColorStop(0.4, `rgba(${cr}, ${cg}, ${cb}, ${alpha * 0.6})`);
+        grad.addColorStop(1, `rgba(${cr}, ${cg}, ${cb}, 0)`);
+        ctx.fillStyle = grad;
+        ctx.beginPath();
+        ctx.arc(lx, ly, r * 2, 0, Math.PI * 2);
+        ctx.fill();
+        ctx.fillStyle = `rgba(${cr}, ${cg}, ${cb}, ${Math.min(1, alpha * 1.3)})`;
+        ctx.beginPath();
+        ctx.arc(lx, ly, Math.max(1, r * 0.4), 0, Math.PI * 2);
+        ctx.fill();
+      }
+    }
     allSatellites.forEach((sat, satIdx) => {
       const track = sat.groundTrack;
       if (!track || track.length === 0) return;
@@ -790,7 +839,7 @@ function GroundTrackMap({
       ctx.textAlign = "center";
       ctx.fillText(emptyMessage, W / 2, H / 2);
     }
-  }, [allSatellites, groundStations, height, showTerminator, terminatorTime, showGrid, showLegend, showEquator, lonToX, latToY, COLORS, emptyMessage, pins, tokens.colors.accent.primary]);
+  }, [allSatellites, groundStations, height, showTerminator, terminatorTime, showGrid, showLegend, showEquator, lonToX, latToY, COLORS, emptyMessage, pins, lightSources, tokens.colors.accent.primary]);
   const handleMouseMove = useCallback((e) => {
     const canvas = canvasRef.current;
     if (!canvas) return;
@@ -918,6 +967,8 @@ function GroundTrackMap({
               minHeight,
               emptyMessage,
               tileUrl,
+              nightTileUrl,
+              lightSources,
               className,
               onSatelliteClick,
               onStationClick,