feat(time-slider): drive a layer's internal time dimension via a generic temporal adapter (#1450)

* feat(time-slider): drive a layer's internal time dimension via a temporal adapter

The Time Slider understood two kinds of temporal layer: a vector layer
filtered by a timestamp property, and a raster time series of dated
sources. Neither fits a data cube, which is one store whose time is an
internal dimension the timeline should index into. Zarr layers therefore
could not join the timeline at all, and each ended up with its own
bespoke time control.

Add a third binding kind: a generic per-layer temporal adapter.

- `TemporalLayerAdapter` (getTimeValues + setTime) with a registry, and a
  `SelectorTimeBinding` persisted on `layer.metadata.timeBinding` beside
  the vector binding so it survives a project round-trip. The time values
  themselves stay transient: they belong to the data store, not the
  project.
- The slider owns the snapping, so it skips a tick that lands on the
  slice already showing and applies at most one change per throttle
  interval per layer. A bound cube shares the track with vector bindings
  and dated overlays: the range is their union and the widest dataset
  sets the stepping granularity.
- `addZarrLayer` registers an adapter for a store's `time` axis,
  decoding CF `units` ("days since 1970-01-01") from the store's own
  metadata. The units are consulted before the generic reader because a
  raw `1980` is a plausible calendar year *and* a plausible days-since
  offset. A calendar Gregorian arithmetic cannot decode (360_day,
  noleap) reports no axis rather than a drifting one.
- Plugins can register an adapter for their own custom layers via
  `app.registerTemporalLayer(layerId, adapter, { bind: true })`.
- The Layers panel offers "Bind time dimension to Time Slider" for any
  layer with an adapter, binding in one step with no property to pick.

Fixes #1448

* Address CodeRabbit review feedback

- Fix an unregister that escaped its guard: the Zarr control's `layerremove`
  handler dropped *every* cube's temporal adapter when any one cube was
  removed, so a second cube silently stopped tracking the timeline. The
  new two-cube test CodeRabbit asked for is what caught it.
- Serialize `setTime` per layer. Throttled ticks fired detached async
  tasks, so two chunk fetches for the same layer could resolve out of
  order and strand the renderer on the older slice while the memo
  recorded the newer index. Applies now chain per layer, so the last
  requested index is also the last applied.
- Key the in-flight add context by store URL instead of two module-level
  slots. `addCloudNetcdfLayer` runs off `addZarrRasterLayer`'s queue, so
  overlapping adds could clobber each other's headers or kerchunk refs
  and resolve a cube's time axis against the wrong credentials.
- Stop caching a metadata lookup that found nothing, so a transient
  outage (or a first, unauthenticated add of a store later added with
  credentials) no longer permanently disables the binding for that store.
- Bound each metadata fetch with `AbortSignal.timeout`, so a store that
  accepts the connection and never answers cannot leave the cached
  promise -- and every later add awaiting it -- pending forever.
- Clear a layer's transient `timeFilter` when a selector binding replaces
  a vector one, matching what the vector bind dialog already does.
- Reuse each locale's established term for the Time Slider rather than
  inventing a second name for the same dock, and fix the Arabic
  gender agreement (`هذا الطبقة` -> `هذه الطبقة`).

* Address CodeRabbit review feedback (round 2)

Same-URL concurrent adds could still cross each other. `addCloudNetcdfLayer`
ran off the queue that `addZarrRasterLayer` uses, so two adds of one store
could both be inside `control.addLayer` at once. The control's `layeradd`
carries no correlation id, so each add's capture handler then latched onto
whichever event fired last: one layer got two adapters (the later
registration winning, with the wrong context) and the other got none.

Keying the pending context by URL, as the previous round did, could not fix
this -- the URL is the same. So:

- Route every programmatic add through one `queueZarrAdd` helper, which is
  what `addZarrRasterLayer` already did and what its own comment says is
  needed ("two overlapping adds would each see the other's event and could
  return the wrong layer"). `addCloudNetcdfLayer` simply was not on it.
- Drop the URL-keyed context map. Each add now registers its own layer's
  adapter after its add resolves, with its own headers/references in
  lexical scope. A refcounted set of in-flight programmatic URLs is all
  that remains, so the shared handler knows to leave those layers alone
  and only registers the Zarr panel's own adds (which carry no context).

The new test asserts the guarantee directly -- `addLayer` is never
re-entered -- and fails against the un-queued version.

* feat(zarr): add a time-series sample dataset to the Zarr Layer panel

The panel's only sample was the CarbonPlan climate cube, whose non-spatial
dimensions are `band` and a bare 1-12 `month` climatology with no CF
`units`. That is not a series of instants, so no temporal adapter is
registered for it and the Layers panel correctly offers no bind action --
leaving the Time Slider binding from this PR with nothing to demonstrate.

Add NOAA OI SST V2 monthly means (1981-2023, 1-degree global, public
domain), published to Source Cooperative and chunked one time step per
chunk (~165 KiB) so stepping the timeline is a single small read. The ARCO
weather archives are chunked along time instead, which is right for
extracting a series at a point but means drawing one instant pulls the
whole series for every spatial tile.

The entry carries its own variable, color limits, colormap and selector,
because the panel's `default*` options are the CarbonPlan sample's: `sst`
against a 0-300 ramp is a flat white wash, and `{ band, month }` names
dimensions this store does not have. That needs maplibre-gl-components
0.28.0 (opengeos/maplibre-gl-components#123), bumped here.

`ZARR_COLORMAP_STOPS` moves above `ZARR_OPTIONS` because that initializer
now resolves a ramp; a const referenced before its declaration would throw
at module evaluation.

Author: giswqs

apps/geolibre-desktop/package.json

@@ -64,7 +64,7 @@
     "maplibre-gl": "^5.24.0",
     "maplibre-gl-3d-tiles": "^0.5.4",
     "maplibre-gl-basemap-control": "^0.13.0",
-    "maplibre-gl-components": "^0.27.0",
+    "maplibre-gl-components": "^0.28.0",
     "maplibre-gl-duckdb": "^0.2.3",
     "maplibre-gl-earth-engine": "^0.4.2",
     "maplibre-gl-enviroatlas": "^0.1.1",

apps/geolibre-desktop/src/components/panels/LayerPanel.tsx

@@ -8,6 +8,7 @@ import {
   useEffect,
   useMemo,
   useRef,
+  useSyncExternalStore,
   useState,
 } from "react";
 import { useTranslation } from "react-i18next";
@@ -31,9 +32,12 @@ import {
   canEditLayerGeometry,
   detectTimePropertiesFromRecords,
   formatTimeExtentInput,
+  getTemporalLayerAdapter,
+  getTemporalLayersVersion,
   getLayerTimeBinding,
   isTileVectorLayer,
   isTimeSliderIdle,
+  subscribeTemporalLayers,
   parseTimeValue,
   sampleTileFeatureRecords,
   BASEMAP_CONTROL_PLUGIN_ID,
@@ -61,7 +65,7 @@ import {
   placeholderMessage,
 } from "@geolibre/map";
 import { getIsMobileViewport } from "../../hooks/useIsMobileViewport";
-import { createAppAPI, usePluginRegistry } from "../../hooks/usePlugins";
+import { bindTemporalLayer, createAppAPI, usePluginRegistry } from "../../hooks/usePlugins";
 import { useDesktopSettingsStore } from "../../hooks/useDesktopSettings";
 import {
   clearFeatureSelection,
@@ -642,6 +646,11 @@ export function LayerPanel({
   // stale async scan or confirm (even for the same layer reopened) is dropped
   // when it no longer matches the latest token.
   const bindRequestRef = useRef(0);
+  // A layer becomes temporal when its renderer finishes resolving a time axis
+  // (a Zarr cube loads its `time` coordinate asynchronously), which happens
+  // outside the store, so the menu subscribes to the adapter registry to offer
+  // "Bind to Time Slider" as soon as one appears.
+  useSyncExternalStore(subscribeTemporalLayers, getTemporalLayersVersion, getTemporalLayersVersion);
   const { isActive: isPluginActive, toggle: togglePlugin } = usePluginRegistry();
   const [internalCollapsed, setInternalCollapsed] = useState(getIsMobileViewport);
   // In the shared left-sidebar mode the parent owns collapse (controlled);
@@ -1713,6 +1722,23 @@ export function LayerPanel({
     closeBindTimeSliderDialog,
     t,
   ]);
+  // Bind a layer whose time is an internal dimension (a Zarr data cube's `time`
+  // axis, or a plugin's own custom layer). There is nothing to ask the user:
+  // the adapter already knows the axis, so the binding is written and the dock
+  // opens in one step rather than through the property-picking dialog.
+  const handleBindTemporalLayer = useCallback(
+    (layer: GeoLibreLayer) => {
+      const adapter = getTemporalLayerAdapter(layer.id);
+      if (!adapter) return;
+      if (bindTemporalLayer(layer.id, adapter, mapControllerRef)) return;
+      setRefreshStatuses((current) => ({
+        ...current,
+        [layer.id]: { type: "error", message: t("layers.bindNoTimeDimension") },
+      }));
+      scheduleStatusClear(layer.id);
+    },
+    [mapControllerRef, scheduleStatusClear, t],
+  );
 
   // Remove a layer's binding and clear its transient time filter so it shows
   // every feature again. The Time Slider stays active for any other bindings.
@@ -2488,7 +2514,12 @@ export function LayerPanel({
             // filter evaluated per feature as each tile decodes, so it needs no
             // local copy of the data (see the bind dialog for how the timeline's
             // extent is established without one).
-            const canBindTimeSlider = layer.type === "geojson" || isTileVectorLayer(layer);
+            // A layer whose time is an internal dimension (a Zarr data cube)
+            // binds through its registered temporal adapter instead, with no
+            // property to pick: see handleBindTemporalLayer.
+            const temporalAdapter = getTemporalLayerAdapter(layer.id);
+            const canBindTimeSlider =
+              layer.type === "geojson" || isTileVectorLayer(layer) || Boolean(temporalAdapter);
             const timeBinding = getLayerTimeBinding(layer);
             // Raster/COG layers backed by a downloadable file (a retained
             // local-bytes blob URL or a source URL) export to GeoTIFF.
@@ -2924,6 +2955,8 @@ export function LayerPanel({
                               onSelect={() => {
                                 if (timeBinding) {
                                   handleUnbindTimeSlider(layer);
+                                } else if (temporalAdapter) {
+                                  handleBindTemporalLayer(layer);
                                 } else {
                                   void openBindTimeSliderDialog(layer);
                                 }
@@ -2932,7 +2965,9 @@ export function LayerPanel({
                               <CalendarClock className="me-2 h-3.5 w-3.5" />
                               {timeBinding
                                 ? t("layers.unbindFromTimeSlider")
-                                : t("layers.bindToTimeSlider")}
+                                : temporalAdapter
+                                  ? t("layers.bindTimeDimensionToTimeSlider")
+                                  : t("layers.bindToTimeSlider")}
                             </DropdownMenuItem>
                           )}
                           {canExportLayer && (

apps/geolibre-desktop/src/hooks/usePlugins.ts

@@ -6,6 +6,11 @@ import {
 import {
   addCogRasterLayer,
   addZarrRasterLayer,
+  buildSelectorTimeBinding,
+  registerTemporalLayer,
+  unregisterTemporalLayer,
+  TIME_SLIDER_PLUGIN_ID,
+  type TemporalLayerAdapter,
   setZarrLayerSelector,
   maplibreAnnotationsPlugin,
   maplibreBasemapControlPlugin,
@@ -625,6 +630,44 @@ function ensureExternalPluginsLoadedWithSettings(
   externalPluginsLoadPromise = loadPromise;
   return loadPromise;
 }
+/**
+ * Bind a layer's internal time dimension to the Time Slider: persist the
+ * binding on the layer's metadata (mirroring how a vector layer's `TimeBinding`
+ * is stored, so it survives a project round-trip) and open the dock if it is not
+ * already showing.
+ *
+ * Shared by the Layers panel's "Bind to Time Slider" action and the plugin API's
+ * `registerTemporalLayer(..., { bind: true })`, so both write the same thing.
+ *
+ * @param layerId - The store layer to bind.
+ * @param adapter - Its temporal adapter, whose time values set the timeline range.
+ * @param mapControllerRef - Used to build the app API when activating the dock.
+ * @returns True when the layer was bound; false when its time axis holds no
+ *   usable timestamp, or the layer is gone.
+ */
+export function bindTemporalLayer(
+  layerId: string,
+  adapter: TemporalLayerAdapter,
+  mapControllerRef?: RefObject<MapController | null>,
+): boolean {
+  const binding = buildSelectorTimeBinding(adapter.dimension ?? "time", adapter.getTimeValues());
+  if (!binding) return false;
+  const store = useAppStore.getState();
+  const layer = store.layers.find((item) => item.id === layerId);
+  if (!layer) return false;
+  store.updateLayer(layerId, {
+    metadata: { ...layer.metadata, timeBinding: binding },
+    // A selector binding replaces whatever was on the layer before. Drop any
+    // transient filter a previous vector binding left behind, or it would keep
+    // hiding features alongside the adapter (matching what the vector bind
+    // dialog does when it commits).
+    timeFilter: undefined,
+  });
+  if (!manager.isActive(TIME_SLIDER_PLUGIN_ID)) {
+    manager.toggle(TIME_SLIDER_PLUGIN_ID, createAppAPI(mapControllerRef));
+  }
+  return true;
+}
 
 export function createAppAPI(mapControllerRef?: RefObject<MapController | null>) {
   const store = useAppStore.getState();
@@ -760,6 +803,20 @@ export function createAppAPI(mapControllerRef?: RefObject<MapController | null>)
       }),
     setZarrLayerSelector: (layerId: string, selector: Record<string, number | string>) =>
       setZarrLayerSelector(layerId, selector),
+    // A layer whose time is an internal dimension joins the Time Slider through
+    // an adapter rather than a filter or a source swap. Registering only makes
+    // it bindable; `bind` writes the binding and opens the dock, which is what a
+    // plugin that just loaded a cube usually wants.
+    registerTemporalLayer: (
+      layerId: string,
+      adapter: TemporalLayerAdapter,
+      options?: { bind?: boolean },
+    ) => {
+      const detach = registerTemporalLayer(layerId, adapter);
+      if (options?.bind) bindTemporalLayer(layerId, adapter, mapControllerRef);
+      return detach;
+    },
+    unregisterTemporalLayer: (layerId: string) => unregisterTemporalLayer(layerId),
     getActiveBasemap: () => useAppStore.getState().basemapStyleUrl,
     onBasemapChange: (callback: (styleUrl: string) => void) =>
       useAppStore.subscribe((state, prev) => {

apps/geolibre-desktop/src/i18n/locales/ar.json

@@ -4186,6 +4186,8 @@
     "styleCopied": "تم نسخ النمط من \"{{name}}\".",
     "stylePasted": "تم لصق النمط من \"{{name}}\".",
     "bindToTimeSlider": "ربط بمنزلق الزمن…",
+    "bindTimeDimensionToTimeSlider": "ربط البُعد الزمني بمنزلق الزمن",
+    "bindNoTimeDimension": "لا تحتوي هذه الطبقة على بُعد زمني قابل للقراءة.",
     "unbindFromTimeSlider": "فك الربط عن منزلق الزمن",
     "bindDialogDescription": "تصفية معالم هذه الطبقة حسب خاصية تاريخ أو طابع زمني أثناء تحريك الخط الزمني. تحتفظ الطبقة بنمطها وعتامتها.",
     "bindScanning": "جارٍ فحص المعالم بحثًا عن خصائص التاريخ والطابع الزمني…",

apps/geolibre-desktop/src/i18n/locales/de.json

@@ -3955,6 +3955,8 @@
     "styleCopied": "Stil von „{{name}}“ kopiert.",
     "stylePasted": "Stil von „{{name}}“ eingefügt.",
     "bindToTimeSlider": "An Zeitschieberegler binden…",
+    "bindTimeDimensionToTimeSlider": "Zeitdimension an Zeitschieberegler binden",
+    "bindNoTimeDimension": "Diese Ebene hat keine lesbare Zeitdimension.",
     "unbindFromTimeSlider": "Von Zeitschieberegler lösen",
     "bindDialogDescription": "Filtert die Objekte dieser Ebene anhand einer Datums- oder Zeitstempel-Eigenschaft, während Sie die Zeitleiste durchlaufen. Die Ebene behält ihre Symbolisierung und Deckkraft.",
     "bindScanning": "Objekte werden nach Datums- und Zeitstempel-Eigenschaften durchsucht…",

apps/geolibre-desktop/src/i18n/locales/en.json

@@ -4115,6 +4115,8 @@
     "styleCopied": "Copied style from \"{{name}}\".",
     "stylePasted": "Pasted style from \"{{name}}\".",
     "bindToTimeSlider": "Bind to Time Slider…",
+    "bindTimeDimensionToTimeSlider": "Bind time dimension to Time Slider",
+    "bindNoTimeDimension": "This layer has no readable time dimension.",
     "unbindFromTimeSlider": "Unbind from Time Slider",
     "bindDialogDescription": "Filter this layer's features by a date or timestamp property as you scrub the timeline. The layer keeps its styling and opacity.",
     "bindScanning": "Scanning features for date and timestamp properties…",

apps/geolibre-desktop/src/i18n/locales/es.json

@@ -3966,6 +3966,8 @@
     "styleCopied": "Estilo copiado de «{{name}}».",
     "stylePasted": "Estilo pegado de «{{name}}».",
     "bindToTimeSlider": "Vincular al control deslizante de tiempo…",
+    "bindTimeDimensionToTimeSlider": "Vincular la dimensión temporal al control deslizante de tiempo",
+    "bindNoTimeDimension": "Esta capa no tiene una dimensión temporal legible.",
     "unbindFromTimeSlider": "Desvincular del control deslizante de tiempo",
     "bindDialogDescription": "Filtra las entidades de esta capa por una propiedad de fecha o marca de tiempo mientras recorre la línea de tiempo. La capa conserva su estilo y opacidad.",
     "bindScanning": "Buscando propiedades de fecha y marca de tiempo en las entidades…",

apps/geolibre-desktop/src/i18n/locales/fr.json

@@ -3955,6 +3955,8 @@
     "styleCopied": "Style copié depuis « {{name}} ».",
     "stylePasted": "Style collé depuis « {{name}} ».",
     "bindToTimeSlider": "Lier au curseur temporel…",
+    "bindTimeDimensionToTimeSlider": "Lier la dimension temporelle au curseur temporel",
+    "bindNoTimeDimension": "Cette couche n'a pas de dimension temporelle lisible.",
     "unbindFromTimeSlider": "Délier du curseur temporel",
     "bindDialogDescription": "Filtrer les entités de cette couche par une propriété de date ou d'horodatage lorsque vous parcourez la chronologie. La couche conserve son style et son opacité.",
     "bindScanning": "Analyse des entités pour les propriétés de date et d'horodatage…",

apps/geolibre-desktop/src/i18n/locales/hi.json

@@ -3955,6 +3955,8 @@
     "styleCopied": "\"{{name}}\" से शैली कॉपी की गई।",
     "stylePasted": "\"{{name}}\" से शैली पेस्ट की गई।",
     "bindToTimeSlider": "टाइम स्लाइडर से बाइंड करें…",
+    "bindTimeDimensionToTimeSlider": "समय आयाम को टाइम स्लाइडर से बाइंड करें",
+    "bindNoTimeDimension": "इस लेयर में कोई पठनीय समय आयाम नहीं है।",
     "unbindFromTimeSlider": "टाइम स्लाइडर से अनबाइंड करें",
     "bindDialogDescription": "टाइमलाइन को स्क्रब करते समय इस लेयर के फ़ीचर को दिनांक या टाइमस्टैम्प प्रॉपर्टी के अनुसार फ़िल्टर करें। लेयर अपनी शैली और अपारदर्शिता बनाए रखती है।",
     "bindScanning": "दिनांक और टाइमस्टैम्प प्रॉपर्टी के लिए फ़ीचर स्कैन किए जा रहे हैं…",

apps/geolibre-desktop/src/i18n/locales/id.json

@@ -3897,6 +3897,8 @@
     "styleCopied": "Gaya disalin dari \"{{name}}\".",
     "stylePasted": "Gaya ditempel dari \"{{name}}\".",
     "bindToTimeSlider": "Ikat ke Penggeser Waktu…",
+    "bindTimeDimensionToTimeSlider": "Ikat dimensi waktu ke Penggeser Waktu",
+    "bindNoTimeDimension": "Lapisan ini tidak memiliki dimensi waktu yang dapat dibaca.",
     "unbindFromTimeSlider": "Lepas dari Penggeser Waktu",
     "bindDialogDescription": "Filter fitur layer ini berdasarkan properti tanggal atau timestamp saat Anda menggeser linimasa. Layer mempertahankan gaya dan opasitasnya.",
     "bindScanning": "Memindai fitur untuk properti tanggal dan timestamp…",