feat: so many feats

Author: hrodmn

CLAUDE.md

@@ -15,8 +15,8 @@ Key UX requirements:
 
 - **Build tool:** Vite
 - **Language:** TypeScript
-- **Mapping:** MapLibre GL JS (supports globe projection natively)
-- **Deployment:** GitHub Pages (static site, `gh-pages` branch)
+- **Mapping:** MapLibre GL JS v5 (supports globe projection natively)
+- **Deployment:** GitHub Pages (static site, `gh-pages` branch via `gh-pages` npm package)
 
 ## Development Commands
 
@@ -41,33 +41,86 @@ npm run deploy
 
 The backend API is documented at https://developmentseed.org/titiler-cmr. Key endpoints used by this app:
 
-- **TileJSON:** `GET /{backend}/tilejson.json` — returns metadata including tile URL template; pass as a `raster-source` in MapLibre
+- **TileJSON:** `GET /{backend}/WebMercatorQuad/tilejson.json` — returns metadata including tile URL template; pass as a `raster-source` in MapLibre
 - **Tiles:** `GET /{backend}/tiles/{z}/{x}/{y}` — the actual tile imagery (`rasterio` backend for GeoTIFF/COG, `xarray` for NetCDF/HDF5)
-- **Granule search:** `GET /bbox/{minx},{miny},{maxx},{maxy}/granules` — find available granules in a bounding box
 
-Common query parameters for tile requests: `concept_id`, `datetime`, `assets`/`bands`, `rescale`, `colormap_name`.
+Common query parameters for tile requests: `collection_concept_id`, `datetime`, `assets`/`variables`, `assets_regex`, `rescale`, `colormap_name`, `expression`, `minzoom`, `maxzoom`.
 
-The hosted titiler-cmr instance URL should be stored in a single config constant (e.g., `src/config.ts`) so it can be easily swapped between environments.
+The hosted titiler-cmr instance URL is stored in `src/config.ts` as `TITILER_ENDPOINT` (currently `https://staging.openveda.cloud/api/titiler-cmr`).
 
 ## Architecture
 
-Single-page static site, no server-side code. Globe projection via MapLibre GL JS v5 (`map.setProjection({ type: 'globe' })` called on `load`).
+Single-page static site, no server-side code. Globe projection via MapLibre GL JS v5 (`map.setProjection({ type: 'globe' })` called on `load`). Base map style: CartoCDN dark-matter.
+
+MapLibre parallel image request limits are bumped to 64 (`MAX_PARALLEL_IMAGE_REQUESTS` and `MAX_PARALLEL_IMAGE_REQUESTS_PER_FRAME`) because CMR tiles are slow and benefit from aggressive parallel fetching.
 
 ```
 src/
-  config.ts       # TITILER_ENDPOINT, DatasetConfig/CollectionConfig/RenderConfig types, DATASETS array
-  main.ts         # Map init, wires controls → layers → zoom-guard → loading
-  controls.ts     # Dataset/Collection/Render selects + date picker; exports getState()
-  layers.ts       # updateLayer(): removes old source/layer, builds TileJSON URL, adds new raster source
+  config.ts       # TITILER_ENDPOINT, type definitions, DATASETS array
+  main.ts         # Map init, sky/globe setup, wires controls → layers → zoom-guard → loading
+  controls.ts     # Dataset/Collection/Render selects + date picker + extra params; exports getState()
+  layers.ts       # updateLayer(): removes old CMR sources/layers, builds TileJSON URL, adds new raster source(s)
   loading.ts      # Shows #loading spinner on map `dataloading`, hides on `idle`
   zoom-guard.ts   # Shows #zoom-guard message when zoom < collection.minzoom
   style.css       # Full-viewport map, absolute-positioned overlay panels
 ```
 
-### Adding a new dataset
-
-Add a new `DatasetConfig` entry to the `DATASETS` array in `src/config.ts`. No other code changes are needed. Each collection needs: `conceptId`, `assetsRegex`, `backend` (`rasterio` | `xarray`), `minzoom`/`maxzoom`, `defaultDate`, and a `renders` array of `RenderConfig` objects.
-
-### Layer update flow
-
-Controls emit a `ControlState` on any change → `updateLayer()` removes the previous `cmr-layer`/`cmr-source` and adds a new raster source pointing at the TileJSON endpoint with all render params encoded in the URL. MapLibre fetches TileJSON natively when `type: 'raster'` with a `url` field is used.
+## Type System (`src/config.ts`)
+
+### `DatasetConfig`
+Top-level entry in `DATASETS`. Has `id`, `label`, and `collection` (a single `CollectionConfig` hides the collection selector; an array shows it).
+
+### `CollectionConfig`
+Describes one CMR collection. Key fields:
+- `collectionConceptId` — CMR concept ID passed as `collection_concept_id`
+- `backend` — `"rasterio"` (GeoTIFF/COG) or `"xarray"` (NetCDF/HDF5)
+- `assetsRegex` — optional regex forwarded to titiler-cmr for asset filtering
+- `minzoom` / `maxzoom`
+- `attribution` — HTML string shown in MapLibre attribution control
+- `date: DateConfig` — controls date picker UI and `datetime` param format
+- `renders: RenderConfig[]`
+- `queryParams?: QueryParamConfig[]` — optional extra controls surfaced in the "Advanced" panel
+
+### `DateConfig`
+Controls how the date UI is rendered and how `datetime` is serialized:
+- `{ mode: "single"; default: string }` — one date input; datetime sent as a single-day range
+- `{ mode: "range"; default: [string, string] }` — two date inputs (start / end)
+- `{ mode: "month"; default: string }` — month/year picker; datetime sent as full calendar month range
+
+### `RenderConfig`
+One entry in `collection.renders`. Has `label`, optional `assets[]` (rasterio) or `variables[]` (xarray), `params` (arbitrary extra query params, values may be arrays for repeated params), and optional `subLayers`.
+
+### `SubLayerSpec`
+When `render.subLayers` is set, `updateLayer()` creates one map layer per entry instead of a single layer. Each sub-layer has its own `params` override (e.g. `group` for xarray) and `minzoom`/`maxzoom`. Used for NISAR frequencyA/B switching based on zoom level.
+
+### `QueryParamConfig`
+Union of four control types surfaced in the "Advanced" collapsible:
+- `RangeQueryParam` — two number inputs rendered as `"min,max"`
+- `SelectQueryParam` — dropdown; value sent as-is
+- `TextQueryParam` — free-text input
+- `AttributeQueryParam` — CMR additional-attribute filter; serialized as `attributeType,attributeName,value` under the `attribute` key. Supports a null value to omit the filter.
+
+## Layer Update Flow
+
+Controls emit a `ControlState` on any change → `updateLayer()`:
+1. Scans and removes all `cmr-0`…`cmr-7` layers/sources (fixed ID space, tolerates partial failures)
+2. Builds `URLSearchParams` from collection + render + datetime + extraParams
+3. If `render.subLayers` exists: adds one `raster` source+layer per sub-layer with per-sub-layer `minzoom`/`maxzoom`
+4. Otherwise: adds a single `cmr-0` raster source+layer
+
+MapLibre fetches TileJSON natively when `type: 'raster'` with a `url` field is used.
+
+## Adding a New Dataset
+
+Add a new `DatasetConfig` entry to the `DATASETS` array in `src/config.ts`. No other code changes are needed. Key decisions per collection:
+- `backend`: use `rasterio` for GeoTIFF/COG, `xarray` for NetCDF/HDF5
+- `date.mode`: `"month"` works well for high-revisit optical (HLS); `"range"` for SAR/sparse; `"single"` for daily products (SST)
+- `queryParams`: add `cloud_cover` range for optical sensors, `attribute` filters for orbit direction etc.
+- `subLayers`: use when different zoom levels should hit different xarray groups (e.g. NISAR frequencyA vs frequencyB)
+- `assetsRegex`: use for rasterio collections where asset names follow a pattern (e.g. `"B[0-9][0-9]"` for HLS)
+
+## Existing Datasets
+
+- **HLS** (`C2021957657-LPCLOUD` / `C2021957295-LPCLOUD`) — Harmonized Landsat/Sentinel-2, rasterio, minzoom 5, True Color + False Color renders, cloud cover filter
+- **NISAR Beta GCOV** (`C3622214170-ASF`) — xarray, minzoom 6, HHHH/HVHV RGB render with frequencyA/B sub-layers, orbit direction attribute filter
+- **MUR SST** (`C1996881146-POCLOUD`) — xarray, minzoom 0, SST + sea ice fraction renders

index.html

@@ -12,17 +12,55 @@
     <button id="controls-toggle" aria-label="Toggle controls" aria-expanded="false">☰</button>
     <div id="controls"></div>
 
-    <div id="logo">
-      <img src="/titiler-cmr.png" alt="titiler-cmr" />
+    <div id="brand">
+      <div class="brand-name">titiler-cmr</div>
+      <div class="brand-links">
+        <a href="https://developmentseed.org/titiler-cmr" target="_blank" rel="noopener">docs</a>
+        <a href="https://github.com/developmentseed/titiler-cmr-browser" target="_blank" rel="noopener">source</a>
+        <button id="about-trigger">about</button>
+      </div>
     </div>
 
-    <div id="zoom-guard">Zoom in further to see data</div>
+<div id="zoom-guard">Zoom in further to see data</div>
 
     <div id="loading">
       <div class="spinner"></div>
       Loading tiles&hellip;
     </div>
 
+    <div id="legend"></div>
+
+    <div id="about-backdrop" aria-hidden="true"></div>
+    <div id="about-modal" role="dialog" aria-modal="true" aria-labelledby="about-title">
+      <div class="about-panel">
+      <button id="about-close" aria-label="Close">&times;</button>
+      <h2 id="about-title">About</h2>
+      <div class="about-body">
+        <section>
+          <h3>This app</h3>
+          <p>An interactive map showcasing <a href="https://developmentseed.org/titiler-cmr" target="_blank" rel="noopener">titiler-cmr</a>'s ability to render NASA Earthdata assets on-the-fly. Browse datasets, adjust date ranges, and explore rendering options — all served as map tiles from a live titiler-cmr instance.</p>
+        </section>
+        <section>
+          <h3>NASA CMR</h3>
+          <p>The <a href="https://cmr.earthdata.nasa.gov" target="_blank" rel="noopener">Common Metadata Repository</a> is NASA's catalog for Earth science data. It indexes thousands of collections — satellite imagery, atmospheric data, ocean observations — and exposes a unified search API used to locate assets for rendering.</p>
+        </section>
+        <section>
+          <h3>titiler-cmr</h3>
+          <p><a href="https://developmentseed.org/titiler-cmr" target="_blank" rel="noopener">titiler-cmr</a> is a dynamic tile server built on <a href="https://developmentseed.org/titiler" target="_blank" rel="noopener">TiTiler</a> that reads Cloud-Optimized GeoTIFFs and NetCDF/HDF5 assets directly from CMR, reprojects them, and serves map tiles without any preprocessing or data duplication.</p>
+        </section>
+      </div>
+      </div>
+    </div>
+
+    <div id="collection-details-backdrop" aria-hidden="true"></div>
+    <div id="collection-details-modal" role="dialog" aria-modal="true" aria-labelledby="collection-details-title">
+      <div class="about-panel">
+        <button id="collection-details-close" aria-label="Close">&times;</button>
+        <h2 id="collection-details-title">Collection Details</h2>
+        <div class="collection-details-body"></div>
+      </div>
+    </div>
+
     <script type="module" src="/src/main.ts"></script>
   </body>
 </html>

src/about.ts

@@ -0,0 +1,31 @@
+/**
+ * Wires up the about modal: open on trigger click, close on backdrop/button/Escape.
+ */
+export function initAbout(): void {
+  const trigger = document.getElementById("about-trigger")!;
+  const modal = document.getElementById("about-modal")!;
+  const backdrop = document.getElementById("about-backdrop")!;
+  const closeBtn = document.getElementById("about-close")!;
+
+  function open() {
+    modal.classList.add("visible");
+    backdrop.classList.add("visible");
+  }
+
+  function close() {
+    modal.classList.remove("visible");
+    backdrop.classList.remove("visible");
+  }
+
+  const panel = modal.querySelector(".about-panel")!;
+
+  trigger.addEventListener("click", open);
+  closeBtn.addEventListener("click", close);
+  // Close when clicking the full-screen container outside the panel
+  modal.addEventListener("click", close);
+  // Prevent clicks inside the panel from bubbling up to the container
+  panel.addEventListener("click", (e) => e.stopPropagation());
+  document.addEventListener("keydown", (e) => {
+    if (e.key === "Escape" && !modal.hidden) close();
+  });
+}

src/collection-details.ts

@@ -0,0 +1,169 @@
+import type { CollectionConfig } from "./config";
+
+const CMR_SEARCH = "https://cmr.earthdata.nasa.gov/search";
+
+type CmrRangeDateTime = {
+  BeginningDateTime?: string;
+  EndingDateTime?: string;
+  EndsAtPresentFlag?: boolean;
+};
+
+type CmrUmm = {
+  Abstract?: string;
+  TemporalExtents?: Array<{ RangeDateTimes?: CmrRangeDateTime[] }>;
+  DOI?: { DOI: string };
+  RelatedUrls?: Array<{ Type: string; URL: string }>;
+};
+
+const cache = new Map<string, Promise<CmrUmm | null>>();
+
+export function fetchMetadata(conceptId: string): Promise<CmrUmm | null> {
+  if (!cache.has(conceptId)) {
+    cache.set(
+      conceptId,
+      fetch(
+        `${CMR_SEARCH}/collections.umm_json?concept_id=${encodeURIComponent(conceptId)}`
+      )
+        .then((r) => r.json())
+        .then((data) => (data.items?.[0]?.umm as CmrUmm) ?? null)
+        .catch(() => null)
+    );
+  }
+  return cache.get(conceptId)!;
+}
+
+/** Formats an ISO datetime string as a short date (YYYY-MM-DD). */
+function shortDate(iso: string): string {
+  return iso.slice(0, 10);
+}
+
+/** Builds the metadata section DOM from a fetched UMM record. */
+function renderMetadata(body: HTMLElement, umm: CmrUmm, conceptId: string): void {
+  body.innerHTML = "";
+
+  if (umm.Abstract) {
+    const abstract = document.createElement("p");
+    abstract.className = "collection-details-abstract";
+    abstract.textContent = umm.Abstract;
+    body.appendChild(abstract);
+  }
+
+  const dl = document.createElement("dl");
+  dl.className = "collection-details-meta";
+
+  function addRow(label: string, content: string | HTMLElement): void {
+    const dt = document.createElement("dt");
+    dt.textContent = label;
+    const dd = document.createElement("dd");
+    if (typeof content === "string") {
+      dd.textContent = content;
+    } else {
+      dd.appendChild(content);
+    }
+    dl.appendChild(dt);
+    dl.appendChild(dd);
+  }
+
+  // Temporal coverage
+  const rangeDateTime =
+    umm.TemporalExtents?.[0]?.RangeDateTimes?.[0];
+  if (rangeDateTime) {
+    const start = rangeDateTime.BeginningDateTime
+      ? shortDate(rangeDateTime.BeginningDateTime)
+      : "unknown";
+    const end = rangeDateTime.EndsAtPresentFlag
+      ? "present"
+      : rangeDateTime.EndingDateTime
+        ? shortDate(rangeDateTime.EndingDateTime)
+        : "present";
+    addRow("Temporal", `${start} – ${end}`);
+  }
+
+  // Concept ID with Earthdata Search link
+  const conceptLink = document.createElement("a");
+  conceptLink.href = `https://search.earthdata.nasa.gov/search?q=${encodeURIComponent(conceptId)}`;
+  conceptLink.target = "_blank";
+  conceptLink.rel = "noopener";
+  conceptLink.textContent = conceptId;
+  addRow("Concept ID", conceptLink);
+
+  // DOI
+  if (umm.DOI?.DOI) {
+    const doiLink = document.createElement("a");
+    doiLink.href = `https://doi.org/${umm.DOI.DOI}`;
+    doiLink.target = "_blank";
+    doiLink.rel = "noopener";
+    doiLink.textContent = umm.DOI.DOI;
+    addRow("DOI", doiLink);
+  }
+
+  // Dataset landing page from RelatedUrls
+  const landingUrl = umm.RelatedUrls?.find(
+    (u) => u.Type === "DATA SET LANDING PAGE"
+  )?.URL;
+  if (landingUrl) {
+    const landingLink = document.createElement("a");
+    landingLink.href = landingUrl;
+    landingLink.target = "_blank";
+    landingLink.rel = "noopener";
+    landingLink.textContent = "Dataset landing page";
+    addRow("More info", landingLink);
+  }
+
+  body.appendChild(dl);
+}
+
+/**
+ * Opens the collection details modal for the given collection, fetching CMR
+ * metadata on demand and caching it for subsequent views.
+ */
+export function showCollectionDetails(collection: CollectionConfig): void {
+  const modal = document.getElementById("collection-details-modal")!;
+  const backdrop = document.getElementById("collection-details-backdrop")!;
+  const title = document.getElementById("collection-details-title")!;
+  const body = modal.querySelector<HTMLElement>(".collection-details-body")!;
+
+  title.textContent = collection.label;
+
+  // Show spinner while fetching
+  body.innerHTML = `<div class="collection-details-loading"><div class="spinner"></div></div>`;
+
+  modal.classList.add("visible");
+  backdrop.classList.add("visible");
+
+  fetchMetadata(collection.collectionConceptId).then((umm) => {
+    // Ensure the modal is still showing this collection (user may have closed it)
+    if (!modal.classList.contains("visible")) return;
+
+    if (umm) {
+      renderMetadata(body, umm, collection.collectionConceptId);
+    } else {
+      body.innerHTML =
+        '<p class="collection-details-error">Could not load collection metadata.</p>';
+    }
+  });
+}
+
+/**
+ * Wires up the collection details modal close interactions.
+ * Call once during app initialization.
+ */
+export function initCollectionDetails(): void {
+  const modal = document.getElementById("collection-details-modal")!;
+  const backdrop = document.getElementById("collection-details-backdrop")!;
+  const closeBtn = document.getElementById("collection-details-close")!;
+
+  function close(): void {
+    modal.classList.remove("visible");
+    backdrop.classList.remove("visible");
+  }
+
+  closeBtn.addEventListener("click", close);
+  modal.addEventListener("click", close);
+  modal
+    .querySelector(".about-panel")!
+    .addEventListener("click", (e) => e.stopPropagation());
+  document.addEventListener("keydown", (e) => {
+    if (e.key === "Escape" && modal.classList.contains("visible")) close();
+  });
+}