fix(time-slider): honor temporal adapter cadence (#1502)

* fix(time-slider): honor temporal adapter cadence

* fix(time-slider): reconcile display unit constraints

* test(time-slider): cover display unit restoration

Author: giswqs

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

@@ -686,7 +686,10 @@ export function bindTemporalLayer(
   adapter: TemporalLayerAdapter,
   mapControllerRef?: RefObject<MapController | null>,
 ): boolean {
-  const binding = buildSelectorTimeBinding(adapter.dimension ?? "time", adapter.getTimeValues());
+  const binding = buildSelectorTimeBinding(adapter.dimension ?? "time", adapter.getTimeValues(), {
+    granularity: adapter.granularity,
+    displayUnits: adapter.displayUnits,
+  });
   if (!binding) return false;
   const store = useAppStore.getState();
   const layer = store.layers.find((item) => item.id === layerId);

packages/plugins/src/plugins/maplibre-time-slider.ts

@@ -18,7 +18,9 @@ import {
   getTemporalLayerAdapter,
   isSelectorTimeBinding,
   nearestTimeIndex,
+  resolveSelectorDisplayUnits,
   subscribeTemporalLayers,
+  TIME_GRANULARITIES,
   toEpochMsAxis,
   type SelectorTimeBinding,
   type TemporalLayerAdapter,
@@ -466,6 +468,7 @@ let preBindingRange: {
   // value (setRange treats a null/undefined end as open).
   end: string | undefined;
   granularity: TimeBinding["granularity"];
+  granularities: TimeGranularity[];
 } | null = null;
 // Guards our own timeFilter writes from re-entering the store subscription.
 let applyingBoundFilters = false;
@@ -758,7 +761,11 @@ function reconcileBoundLayers(control: TimeSliderControl): void {
     ) {
       granularity = pickGranularity(max - min);
     }
-    const rangeKey = `${min}|${max}|${granularity}`;
+    const orderedDisplayUnits = resolveSelectorDisplayUnits(
+      selectors.map(({ binding }) => binding),
+      granularity,
+    );
+    const rangeKey = `${min}|${max}|${granularity}|${orderedDisplayUnits?.join(",") ?? ""}`;
     if (rangeKey !== lastBoundRangeKey) {
       // Capture the range the control had before any binding overrode it, so it
       // can be restored when every binding is later removed.
@@ -768,10 +775,17 @@ function reconcileBoundLayers(control: TimeSliderControl): void {
           start: config.startDate,
           end: config.endDate,
           granularity: config.granularity,
+          granularities: [...(config.granularities ?? TIME_GRANULARITIES)],
         };
       }
       lastBoundRangeKey = rangeKey;
       control.setRange(new Date(min), new Date(max), undefined, granularity);
+      control.setGranularities(
+        orderedDisplayUnits
+          ? orderedDisplayUnits
+          : (preBindingRange?.granularities ??
+              control.getConfig().granularities ?? [...TIME_GRANULARITIES]),
+      );
     }
   } else {
     // The last binding/frame was removed: restore the pre-binding range so any
@@ -783,6 +797,7 @@ function reconcileBoundLayers(control: TimeSliderControl): void {
         undefined,
         preBindingRange.granularity,
       );
+      control.setGranularities(preBindingRange.granularities);
     }
     preBindingRange = null;
     lastBoundRangeKey = null;
@@ -798,6 +813,11 @@ function reconcileBoundLayers(control: TimeSliderControl): void {
   applyTimeOverlayVisibility(control, frames);
 }
 
+/** Exercise binding reconciliation with a stub control in unit tests. */
+export function __reconcileBoundLayersForTests(control: TimeSliderControl): void {
+  reconcileBoundLayers(control);
+}
+
 /**
  * Wire the control's date changes and the GeoLibre store together so bound
  * layers track the timeline. Returns a detacher that also clears every applied

packages/plugins/src/plugins/temporal-layers.ts

@@ -1,5 +1,7 @@
 import { parseTimeValue, pickGranularity, type TimeGranularity } from "./time-slider-binding";
 
+export const TIME_GRANULARITIES: readonly TimeGranularity[] = ["hour", "day", "month", "year"];
+
 /**
  * A layer whose time is an **internal dimension** rather than a feature property
  * or a separate dated source: a Zarr data cube with a `time` axis, a plugin's
@@ -28,6 +30,16 @@ export interface TemporalLayerAdapter {
    * axis the timeline was bound to. Defaults to `"time"`.
    */
   dimension?: string;
+  /**
+   * Stepping unit for the Time Slider. When omitted, GeoLibre derives one from
+   * the full axis span.
+   */
+  granularity?: TimeGranularity;
+  /**
+   * Units offered by the Time Slider's granularity controls. For example, a
+   * daily cube can use `["day"]` to keep the track and labels at its cadence.
+   */
+  displayUnits?: TimeGranularity[];
 }
 
 /**
@@ -48,6 +60,8 @@ export interface SelectorTimeBinding {
   max: number;
   /** Suggested stepping granularity derived from the axis span. */
   granularity: TimeGranularity;
+  /** Units offered by the Time Slider while this binding is active. */
+  displayUnits?: TimeGranularity[];
 }
 
 /**
@@ -142,6 +156,7 @@ export function nearestTimeIndex(axis: readonly number[], targetMs: number): num
 export function buildSelectorTimeBinding(
   dimension: string,
   values: ReadonlyArray<Date | number | string> | null | undefined,
+  options?: Pick<TemporalLayerAdapter, "granularity" | "displayUnits">,
 ): SelectorTimeBinding | null {
   const axis = toEpochMsAxis(values);
   if (!axis) return null;
@@ -156,15 +171,42 @@ export function buildSelectorTimeBinding(
   // A single-slice cube still needs a non-zero span so the slider can move,
   // matching the vector path's treatment of a single-instant dataset.
   if (max <= min) max = min + 86_400_000;
+  const granularity = options?.granularity ?? pickGranularity(max - min);
+  const displayUnits = options?.displayUnits
+    ? TIME_GRANULARITIES.filter(
+        (unit) => unit === granularity || options.displayUnits?.includes(unit),
+      )
+    : undefined;
   return {
     kind: "selector",
     dimension: dimension.trim() || "time",
     min,
     max,
-    granularity: pickGranularity(max - min),
+    granularity,
+    ...(displayUnits ? { displayUnits } : {}),
   };
 }
 
+/**
+ * Resolve display-unit constraints for a shared slider. Constrained selector
+ * bindings contribute their intersection. If that intersection cannot expose
+ * the active stepping unit, the active unit is the only safe shared control.
+ */
+export function resolveSelectorDisplayUnits(
+  bindings: readonly SelectorTimeBinding[],
+  activeGranularity: TimeGranularity,
+): TimeGranularity[] | undefined {
+  const constrained = bindings.filter(
+    (binding): binding is SelectorTimeBinding & { displayUnits: TimeGranularity[] } =>
+      Boolean(binding.displayUnits?.length),
+  );
+  if (constrained.length === 0) return undefined;
+  const intersection = TIME_GRANULARITIES.filter((unit) =>
+    constrained.every((binding) => binding.displayUnits.includes(unit)),
+  );
+  return intersection.includes(activeGranularity) ? intersection : [activeGranularity];
+}
+
 // ----- Registry --------------------------------------------------------------
 // Adapters are transient: they belong to a *live* layer instance, so they are
 // registered when the layer is created (natively by the Zarr flow, or by an

tests/temporal-layers.test.ts

@@ -8,6 +8,7 @@ import {
   isSelectorTimeBinding,
   nearestTimeIndex,
   registerTemporalLayer,
+  resolveSelectorDisplayUnits,
   subscribeTemporalLayers,
   toEpochMsAxis,
   type TemporalLayerAdapter,
@@ -99,6 +100,54 @@ describe("buildSelectorTimeBinding", () => {
     assert.equal(binding.granularity, "day");
   });
 
+  it("honors an adapter's granularity and displayed slider units", () => {
+    const values = Array.from({ length: 35 * 365 }, (_, i) => Date.UTC(1990, 0, 1) + i * DAY);
+    const binding = buildSelectorTimeBinding("time", values, {
+      granularity: "day",
+      displayUnits: ["day"],
+    });
+    assert.ok(binding);
+    assert.equal(binding.granularity, "day");
+    assert.deepEqual(binding.displayUnits, ["day"]);
+  });
+
+  it("keeps the active granularity in the displayed slider units", () => {
+    const binding = buildSelectorTimeBinding("time", [Date.UTC(2020, 0, 1), Date.UTC(2020, 0, 2)], {
+      granularity: "day",
+      displayUnits: ["month"],
+    });
+    assert.deepEqual(binding?.displayUnits, ["day", "month"]);
+  });
+
+  it("intersects shared display units and falls back to the active granularity", () => {
+    const base = {
+      kind: "selector" as const,
+      dimension: "time",
+      min: Date.UTC(2020, 0, 1),
+      max: Date.UTC(2020, 0, 2),
+    };
+    assert.deepEqual(
+      resolveSelectorDisplayUnits(
+        [
+          { ...base, granularity: "day", displayUnits: ["day", "month"] },
+          { ...base, granularity: "month", displayUnits: ["month"] },
+        ],
+        "month",
+      ),
+      ["month"],
+    );
+    assert.deepEqual(
+      resolveSelectorDisplayUnits(
+        [
+          { ...base, granularity: "day", displayUnits: ["day"] },
+          { ...base, granularity: "month", displayUnits: ["month"] },
+        ],
+        "day",
+      ),
+      ["day"],
+    );
+  });
+
   it("gives a single-slice cube a non-zero span so the slider can still move", () => {
     const binding = buildSelectorTimeBinding("time", [Date.UTC(2020, 0, 1)]);
     assert.ok(binding);

tests/time-slider-config.test.ts

@@ -2,13 +2,15 @@ import assert from "node:assert/strict";
 import { afterEach, describe, it } from "node:test";
 import { DEFAULT_LAYER_STYLE, useAppStore, type GeoLibreLayer } from "@geolibre/core";
 import {
+  __reconcileBoundLayersForTests,
   configToOptions,
   getLayerTimeBinding,
   createStoreLayer,
   isTimeSliderIdle,
   maplibreTimeSliderPlugin,
 } from "../packages/plugins/src/plugins/maplibre-time-slider";
-import type { SourceSpec } from "maplibre-gl-time-slider";
+import { registerTemporalLayer } from "../packages/plugins/src/plugins/temporal-layers";
+import type { SourceSpec, TimeSliderControl } from "maplibre-gl-time-slider";
 
 // applyProjectState / getProjectState touch no app methods while no control is
 // active (the plugin is never activated here), so a bare stub satisfies the type.
@@ -69,6 +71,60 @@ describe("Time Slider open-ended end date persistence", () => {
   });
 });
 
+describe("Time Slider selector display-unit restoration", () => {
+  it("restores the previous controls after the last selector is unbound", () => {
+    const store = useAppStore.getState();
+    const previousLayers = store.layers;
+    const layer = {
+      id: "restore-units",
+      name: "Daily cube",
+      type: "geojson",
+      source: {},
+      visible: true,
+      opacity: 1,
+      style: { ...DEFAULT_LAYER_STYLE },
+      metadata: {
+        timeBinding: {
+          kind: "selector",
+          dimension: "time",
+          min: Date.UTC(2020, 0, 1),
+          max: Date.UTC(2020, 0, 2),
+          granularity: "day",
+          displayUnits: ["day"],
+        },
+      },
+    } satisfies GeoLibreLayer;
+    const ranges: unknown[][] = [];
+    const granularities: string[][] = [];
+    const control = {
+      getConfig: () =>
+        baseConfig({
+          granularities: ["year", "month"],
+        }),
+      setRange: (...args: unknown[]) => ranges.push(args),
+      setGranularities: (units: string[]) => granularities.push(units),
+    } as unknown as TimeSliderControl;
+    const detach = registerTemporalLayer(layer.id, {
+      getTimeValues: () => [Date.UTC(2020, 0, 1), Date.UTC(2020, 0, 2)],
+      setTime: () => {},
+    });
+
+    try {
+      useAppStore.setState({ layers: [layer] });
+      __reconcileBoundLayersForTests(control);
+      assert.deepEqual(granularities.at(-1), ["day"]);
+
+      useAppStore.getState().updateLayer(layer.id, { metadata: {} });
+      __reconcileBoundLayersForTests(control);
+      assert.deepEqual(granularities.at(-1), ["year", "month"]);
+      assert.equal(ranges.at(-1)?.[3], "year");
+    } finally {
+      detach();
+      useAppStore.setState({ layers: previousLayers });
+    }
+  });
+});
+
 describe("Time Slider mosaic source persistence", () => {
   const mosaicSource = (overrides: Record<string, unknown> = {}): Record<string, unknown> => ({
     type: "mosaic",