@aguacerowx/javascript-sdk 0.0.21 → 0.0.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aguacerowx/javascript-sdk",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -25,6 +25,11 @@
       "import": "./src/nexrad_support.js",
       "require": "./src/nexrad_support.js",
       "default": "./src/nexrad_support.js"
+    },
+    "./nexradTiltCoalesce.js": {
+      "import": "./src/nexradTiltCoalesce.js",
+      "require": "./src/nexradTiltCoalesce.js",
+      "default": "./src/nexradTiltCoalesce.js"
     }
   },
   "files": [

package/src/AguaceroCore.js

@@ -23,7 +23,9 @@ import {
     nexradColormapFldKey,
     variableToNexradGroup,
     getAvailableNexradTilts,
+    getRawNexradTiltsForCoalesce,
 } from './nexrad_support.js';
+import { nexradLayerTiltToDisplayOption } from './nexradTiltCoalesce.js';
 import { NEXRAD_LEVEL3_ELEV, getNexradLevel3EntryByRadarKey } from './nexrad_level3_catalog.js';
 import {
     setRadarTiltsManifest,
@@ -142,12 +144,7 @@ export class AguaceroCore extends EventEmitter {
         const initialSatellite = initialMode === 'satellite';
         const initialNexrad = initialMode === 'nexrad';
         const initialNexradProd = userLayerOptions.nexradProduct || 'REF';
-        const initialNexradDs =
-            userLayerOptions.nexradDataSource != null
-                ? userLayerOptions.nexradDataSource === 'level3'
-                    ? 'level3'
-                    : 'level2'
-                : inferNexradDataSourceForProduct(initialNexradProd);
+        const initialNexradDs = inferNexradDataSourceForProduct(initialNexradProd);
         const initialNexradFld = initialNexrad
             ? nexradColormapFldKey(initialNexradDs, initialNexradProd)
             : initialVariable;
@@ -224,6 +221,27 @@ export class AguaceroCore extends EventEmitter {
     async setState(newState) {
         const patch = { ...newState };
         if ('satelliteKey' in patch) delete patch.satelliteKey;
+        if ('nexradDataSource' in patch && !('nexradProduct' in patch)) {
+            delete patch.nexradDataSource;
+        }
+        const willBeNexrad =
+            patch.isNexrad !== undefined ? Boolean(patch.isNexrad) : this.state.isNexrad;
+        if (willBeNexrad && 'nexradProduct' in patch && patch.nexradProduct != null) {
+            const p = (patch.nexradProduct || 'REF').toUpperCase();
+            const prevP = (this.state.nexradProduct || 'REF').toUpperCase();
+            const ds = inferNexradDataSourceForProduct(p);
+            patch.nexradProduct = p;
+            patch.nexradDataSource = ds;
+            patch.variable = nexradColormapFldKey(ds, p);
+            if (!('nexradStormRelative' in newState)) {
+                // Default: base radial velocity (L3 N0G only) — one fetch per time; fast scrub.
+                // SRV (N0G + N0S) is opt-in: setNexradStormRelative(true) or pass nexradStormRelative in setState.
+                // Re-selecting the same product (e.g. VEL → VEL) leaves the current SRV flag alone.
+                if (p !== 'VEL' || prevP !== 'VEL') {
+                    patch.nexradStormRelative = false;
+                }
+            }
+        }
         if ('forecastHour' in patch && patch.forecastHour != null) {
             patch.forecastHour = Number(patch.forecastHour);
         }
@@ -363,13 +381,6 @@ export class AguaceroCore extends EventEmitter {
         return `${site}_${group}_${elevNormUse}`;
     }
 
-    /** Storm-relative Level-III velocity (N0G + N0S) — matches aguacero-frontend `level3StormRelative` for VEL. */
-    _nexradStormRelativeFor(nexradDataSource, nexradProduct) {
-        const ds = nexradDataSource === 'level3' ? 'level3' : 'level2';
-        const p = (nexradProduct || 'REF').toUpperCase();
-        return ds === 'level3' && p === 'VEL';
-    }
-
     _emitStateChange() {
         const { colormap, baseUnit } = this._getColormapForVariable(this.state.variable);
         const toUnit = this._getTargetUnit(baseUnit, this.state.units);
@@ -922,13 +933,7 @@ export class AguaceroCore extends EventEmitter {
             };
         } else if (mode === 'nexrad') {
             const nexradProduct = options.nexradProduct || 'REF';
-            const nexradDataSource =
-                options.nexradDataSource != null
-                    ? options.nexradDataSource === 'level3'
-                        ? 'level3'
-                        : 'level2'
-                    : inferNexradDataSourceForProduct(nexradProduct);
-            const fld = nexradColormapFldKey(nexradDataSource, nexradProduct);
+            const p = nexradProduct.toUpperCase();
             const site = options.nexradSite ?? null;
             let tilt =
                 options.nexradTilt != null
@@ -940,10 +945,8 @@ export class AguaceroCore extends EventEmitter {
                 isNexrad: true,
                 isMRMS: false,
                 isSatellite: false,
-                variable: fld,
                 nexradSite: site,
-                nexradDataSource,
-                nexradProduct,
+                nexradProduct: p,
                 nexradTilt: tilt,
                 nexradTimestamp: options.nexradTimestamp != null ? Number(options.nexradTimestamp) : null,
                 nexradStormRelative: options.nexradStormRelative === true,
@@ -985,26 +988,23 @@ export class AguaceroCore extends EventEmitter {
     }
 
     /**
-     * Keep `nexradTilt` on an angle returned by {@link getAvailableNexradTilts} (matches aguacero-frontend elevation buttons).
+     * Keep `nexradTilt` on a coalesced elevation (same rules as aguacero-frontend tilt controls).
      */
     async _snapNexradTiltToAvailableOptions() {
         const s = this.state;
         if (!s.isNexrad || !s.nexradSite) return;
-        const tilts = getAvailableNexradTilts(
+        const raw = getRawNexradTiltsForCoalesce(
             s.nexradSite,
             s.nexradDataSource || 'level2',
             s.nexradProduct || 'REF',
         );
-        if (!tilts.length) return;
+        if (!raw.length) return;
         const t = s.nexradTilt;
-        const match = (a, b) => Math.abs(Number(a) - Number(b)) < 1e-4;
-        if (t != null && tilts.some((x) => match(x, t))) return;
         const target = t != null && Number.isFinite(Number(t)) ? Number(t) : getDefaultRadarTilt(s.nexradSite);
-        let best = tilts[0];
-        for (const x of tilts) {
-            if (Math.abs(x - target) < Math.abs(best - target)) best = x;
-        }
-        await this.setState({ nexradTilt: best });
+        const canonical = nexradLayerTiltToDisplayOption(target, raw);
+        const match = (a, b) => Math.abs(Number(a) - Number(b)) < 1e-4;
+        if (match(s.nexradTilt, canonical)) return;
+        await this.setState({ nexradTilt: canonical });
     }
 
     async refreshNexradTimes() {
@@ -1044,6 +1044,18 @@ export class AguaceroCore extends EventEmitter {
                 listWindowHours: listingHours,
             };
         }
+        const filtered = this._getFilteredNexradTimestampsForVariable(out.unixTimes || []);
+        const map = out.timeToKeyMap || {};
+        if (filtered.length > 0) {
+            const cur = this.state.nexradTimestamp != null ? Number(this.state.nexradTimestamp) : null;
+            const hasKey = cur != null && Object.prototype.hasOwnProperty.call(map, String(cur));
+            const inWindow = cur != null && filtered.includes(cur);
+            if (cur == null || !inWindow || !hasKey) {
+                this.state.nexradTimestamp = filtered[filtered.length - 1];
+            }
+        } else if (this.state.nexradTimestamp != null) {
+            this.state.nexradTimestamp = null;
+        }
         this._emitStateChange();
     }
 
@@ -1067,10 +1079,7 @@ export class AguaceroCore extends EventEmitter {
     async setNexradProduct(product) {
         if (!this.state.isNexrad) return;
         const p = (product || 'REF').toUpperCase();
-        const ds = inferNexradDataSourceForProduct(p);
-        const fld = nexradColormapFldKey(ds, p);
-        const nexradStormRelative = this._nexradStormRelativeFor(ds, p);
-        await this.setState({ nexradProduct: p, nexradDataSource: ds, variable: fld, nexradStormRelative });
+        await this.setState({ nexradProduct: p });
         await this.refreshNexradTimes();
         const filtered = this._getFilteredNexradTimestampsForVariable(
             this.nexradTimesByStation[this._nexradTimesCacheKey()]?.unixTimes || [],
@@ -1080,48 +1089,19 @@ export class AguaceroCore extends EventEmitter {
         }
     }
 
-    async setNexradDataSource(source) {
-        if (!this.state.isNexrad) return;
-        const ds = source === 'level3' ? 'level3' : 'level2';
-        const p = (this.state.nexradProduct || 'REF').toUpperCase();
-        const fld = nexradColormapFldKey(ds, p);
-        const nexradStormRelative = this._nexradStormRelativeFor(ds, p);
-        await this.setState({ nexradDataSource: ds, variable: fld, nexradStormRelative });
+    async setNexradTilt(tilt) {
+        if (!this.state.isNexrad || !this.state.nexradSite) return;
+        await this.setState({ nexradTilt: tilt != null ? Number(tilt) : null });
         await this.refreshNexradTimes();
-        const filtered = this._getFilteredNexradTimestampsForVariable(
-            this.nexradTimesByStation[this._nexradTimesCacheKey()]?.unixTimes || [],
-        );
-        if (filtered.length > 0) {
-            await this.setState({ nexradTimestamp: filtered[filtered.length - 1] });
-        }
     }
 
     /**
-     * Sets NEXRAD product and archive source together (single refresh). Prefer {@link setNexradProduct}
-     * for product-only changes (Level II vs III is inferred). Use this when you must force a specific
-     * archive source (rare).
-     * @param {'level2'|'level3'} dataSource
-     * @param {string} product - Level-II variable (REF, VEL, …) or Level-III radar key (N0H, HHC, …)
+     * Opt-in storm-relative velocity (L3: N0G + N0S). When off (default), only base radial velocity is used (faster).
+     * @param {boolean} enabled
      */
-    async setNexradProductMode(dataSource, product) {
+    async setNexradStormRelative(enabled) {
         if (!this.state.isNexrad) return;
-        const ds = dataSource === 'level3' ? 'level3' : 'level2';
-        const p = (product || 'REF').toUpperCase();
-        const fld = nexradColormapFldKey(ds, p);
-        const nexradStormRelative = this._nexradStormRelativeFor(ds, p);
-        await this.setState({ nexradDataSource: ds, nexradProduct: p, variable: fld, nexradStormRelative });
-        await this.refreshNexradTimes();
-        const filtered = this._getFilteredNexradTimestampsForVariable(
-            this.nexradTimesByStation[this._nexradTimesCacheKey()]?.unixTimes || [],
-        );
-        if (filtered.length > 0) {
-            await this.setState({ nexradTimestamp: filtered[filtered.length - 1] });
-        }
-    }
-
-    async setNexradTilt(tilt) {
-        if (!this.state.isNexrad || !this.state.nexradSite) return;
-        await this.setState({ nexradTilt: tilt != null ? Number(tilt) : null });
+        await this.setState({ nexradStormRelative: Boolean(enabled) });
         await this.refreshNexradTimes();
     }
 

package/src/index.js

@@ -39,4 +39,5 @@ export {
 
 /** NEXRAD tilt + listing helpers (also importable via subpaths; root re-export fixes Vite/esbuild subpath resolution). */
 export * from './nexradTilts.js';
+export * from './nexradTiltCoalesce.js';
 export * from './nexrad_support.js';

package/src/nexradTiltCoalesce.js

@@ -0,0 +1,95 @@
+/**
+ * NEXRAD tilt coalescing (matches aguacero-frontend `nexradTiltCoalesce.ts`).
+ * Adjacent manifest tilts within {@link NEXRAD_TILT_COALESCE_MAX_GAP}° are merged for UI/listings:
+ * pairs → higher tilt; runs of three or more consecutive steps merge the first two into the lower tilt.
+ */
+
+/** Adjacent tilts (sorted) within this gap share one listing / control. */
+export const NEXRAD_TILT_COALESCE_MAX_GAP = 0.1;
+
+/**
+ * @param {number[]} segment
+ * @param {Map<number, number>} map
+ */
+function mergeCoalesceSegment(segment, map) {
+    if (segment.length === 0) return;
+    if (segment.length === 1) {
+        map.set(segment[0], segment[0]);
+        return;
+    }
+    if (segment.length === 2) {
+        const canonical = Math.max(segment[0], segment[1]);
+        map.set(segment[0], canonical);
+        map.set(segment[1], canonical);
+        return;
+    }
+    const low = segment[0];
+    map.set(segment[0], low);
+    map.set(segment[1], low);
+    mergeCoalesceSegment(segment.slice(2), map);
+}
+
+/**
+ * @param {number[]} sortedUnique
+ * @returns {Map<number, number>}
+ */
+export function chainCoalesceToCanonical(sortedUnique) {
+    const map = new Map();
+    let i = 0;
+    while (i < sortedUnique.length) {
+        let j = i + 1;
+        while (
+            j < sortedUnique.length &&
+            sortedUnique[j] - sortedUnique[j - 1] <= NEXRAD_TILT_COALESCE_MAX_GAP + 1e-9
+        ) {
+            j++;
+        }
+        const segment = sortedUnique.slice(i, j);
+        mergeCoalesceSegment(segment, map);
+        i = j;
+    }
+    return map;
+}
+
+/**
+ * Manifest tilt list with adjacent options merged (pairs → higher; triple+ splits per merge rules).
+ * @param {number[]} tilts
+ * @returns {number[]}
+ */
+export function coalesceNexradTiltOptionsForDisplay(tilts) {
+    const sorted = [...new Set(tilts)]
+        .filter((t) => Number.isFinite(t))
+        .sort((a, b) => a - b);
+    if (sorted.length <= 1) return sorted;
+    const tiltToCanonical = chainCoalesceToCanonical(sorted);
+    const reps = [];
+    let prevRep;
+    for (const t of sorted) {
+        const c = tiltToCanonical.get(t);
+        if (c === undefined) continue;
+        if (c !== prevRep) {
+            reps.push(c);
+            prevRep = c;
+        }
+    }
+    return reps;
+}
+
+/**
+ * Map stored/clamped tilt to the coalesced elevation value (same rules as {@link coalesceNexradTiltOptionsForDisplay}).
+ * @param {number} layerTilt
+ * @param {number[]} manifestTilts raw manifest tilts (before coalescing)
+ * @returns {number}
+ */
+export function nexradLayerTiltToDisplayOption(layerTilt, manifestTilts) {
+    const sorted = [...new Set(manifestTilts)]
+        .filter((t) => Number.isFinite(t))
+        .sort((a, b) => a - b);
+    if (sorted.length === 0) return layerTilt;
+    const tiltToCanonical = chainCoalesceToCanonical(sorted);
+    if (tiltToCanonical.has(layerTilt)) return tiltToCanonical.get(layerTilt);
+    const nearest = sorted.reduce((best, x) =>
+        Math.abs(x - layerTilt) < Math.abs(best - layerTilt) ? x : best,
+    sorted[0]);
+    return tiltToCanonical.get(nearest) ?? layerTilt;
+}

package/src/nexrad_support.js

@@ -8,6 +8,7 @@ import {
     getDefaultRadarTilt,
     getRadarTilts,
 } from './nexradTilts.js';
+import { coalesceNexradTiltOptionsForDisplay } from './nexradTiltCoalesce.js';
 import {
     NEXRAD_LEVEL3_ELEV,
     NEXRAD_LEVEL3_MOTION_PRODUCT,
@@ -16,7 +17,7 @@ import {
 
 /**
  * Whether listings and archive fetches for this product use Level-II sweep lambda vs Level-III S3 products.
- * AguaceroCore applies this from the product key; set `nexradDataSource` in layer options only to override (rare).
+ * AguaceroCore derives this from the product key only (not user-configurable).
  * @param {string} [nexradProduct] - Radar variable key (e.g. REF, KDP, VEL).
  * @returns {'level2'|'level3'}
  */
@@ -263,25 +264,43 @@ export async function fetchNexradTimesListing(opts) {
 const L3_TILT_INDEX_MANIFEST_SLOTS = 6;
 
 /**
- * Tilt angles for the UI (manifest-driven L2 list; Level III KDP/N0H use the first slots like aguacero-frontend).
+ * Raw manifest tilt list before coalescing (same rules as aguacero-frontend `radarTiltOptionsRaw`).
+ * Use {@link coalesceNexradTiltOptionsForDisplay} or {@link getAvailableNexradTilts} for UI controls.
+ *
  * @param {string} siteId
  * @param {'level2'|'level3'} nexradDataSource
  * @param {string} [nexradProduct]
  * @returns {number[]}
  */
-export function getAvailableNexradTilts(siteId, nexradDataSource, nexradProduct) {
+export function getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct) {
     if (!siteId) return [];
     const v = (nexradProduct || 'REF').toUpperCase();
     const ds = nexradDataSource === 'level3' ? 'level3' : 'level2';
     const tilts = getRadarTilts(siteId, v);
+    /** L3 super-res VEL (N*G) uses the same first-N manifest slots as KDP/N0H — not the full L2 g2-only list. */
+    if (v === 'VEL') {
+        return tilts.slice(0, L3_TILT_INDEX_MANIFEST_SLOTS);
+    }
     if (ds === 'level2') {
         return [...tilts];
     }
     if (v === 'KDP' || v === 'N0H') {
         return tilts.slice(0, L3_TILT_INDEX_MANIFEST_SLOTS);
     }
-    if (v === 'VEL') {
-        return [...tilts];
-    }
     return [];
 }
+
+/**
+ * Tilt angles for the UI: manifest tilts with adjacent 0.1° steps merged like aguacero-frontend
+ * ({@link coalesceNexradTiltOptionsForDisplay}).
+ *
+ * @param {string} siteId
+ * @param {'level2'|'level3'} nexradDataSource
+ * @param {string} [nexradProduct]
+ * @returns {number[]}
+ */
+export function getAvailableNexradTilts(siteId, nexradDataSource, nexradProduct) {
+    const raw = getRawNexradTiltsForCoalesce(siteId, nexradDataSource, nexradProduct);
+    if (!raw.length) return [];
+    return coalesceNexradTiltOptionsForDisplay(raw);
+}