insomni-plot 0.1.0-alpha.0

package/src/range-presets.test.ts

@@ -0,0 +1,345 @@
+import { describe, expect, test } from "vite-plus/test";
+
+import { viewportFrame } from "insomni";
+import {
+  createRangePresets,
+  linearPreset,
+  logPreset,
+  timePreset,
+  type RangePreset,
+} from "./range-presets.ts";
+import { createDataViewport } from "./viewport.ts";
+
+const FROZEN_NOW = new Date("2026-05-20T12:00:00Z").getTime();
+const now = () => FROZEN_NOW;
+
+const linearViewport = (domain: [number, number] = [0, 100]) =>
+  createDataViewport({
+    frame: viewportFrame(400, 300),
+    x: { type: "linear", domain },
+    y: { type: "linear", domain: [0, 100] },
+  });
+
+const timeViewport = (domain: [Date, Date]) =>
+  createDataViewport({
+    frame: viewportFrame(400, 300),
+    x: { type: "time", domain },
+    y: { type: "linear", domain: [0, 100] },
+  });
+
+describe("createRangePresets — preset resolution", () => {
+  test("time presets resolve against a frozen `now`", () => {
+    const dataDomain: [Date, Date] = [new Date("2024-01-01T00:00:00Z"), new Date(FROZEN_NOW)];
+    const vp = timeViewport(dataDomain);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [timePreset("24H"), timePreset("7D"), timePreset("1M"), timePreset("MAX")],
+      dataDomain,
+      now,
+    });
+
+    ctl.setActive("24H");
+    const [s24, e24] = vp.visibleXDomain as readonly [Date, Date];
+    expect(e24.getTime()).toBe(FROZEN_NOW);
+    expect(s24.getTime()).toBe(FROZEN_NOW - 24 * 3600_000);
+
+    ctl.setActive("7D");
+    const [s7] = vp.visibleXDomain as readonly [Date, Date];
+    expect(s7.getTime()).toBe(FROZEN_NOW - 7 * 24 * 3600_000);
+
+    ctl.setActive("1M");
+    const [s1m] = vp.visibleXDomain as readonly [Date, Date];
+    expect(s1m.getTime()).toBe(FROZEN_NOW - 30 * 24 * 3600_000);
+  });
+
+  test("YTD spans January 1 to now", () => {
+    const dataDomain: [Date, Date] = [new Date("2020-01-01T00:00:00Z"), new Date(FROZEN_NOW)];
+    const vp = timeViewport(dataDomain);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [timePreset("YTD")],
+      dataDomain,
+      now,
+    });
+    ctl.setActive("YTD");
+    const [start, end] = vp.visibleXDomain as readonly [Date, Date];
+    expect(end.getTime()).toBe(FROZEN_NOW);
+    expect(start.getUTCFullYear()).toBe(2026);
+    expect(start.getUTCMonth()).toBe(0);
+    expect(start.getUTCDate()).toBe(1);
+  });
+
+  test("MAX resets to the full data extent", () => {
+    const dataDomain: [Date, Date] = [new Date("2024-01-01T00:00:00Z"), new Date(FROZEN_NOW)];
+    const vp = timeViewport(dataDomain);
+    vp.setVisibleDomain({
+      x: [new Date("2025-06-01T00:00:00Z"), new Date("2025-09-01T00:00:00Z")] as const,
+    });
+
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [timePreset("MAX")],
+      dataDomain,
+      now,
+    });
+    ctl.setActive("MAX");
+    const [start, end] = vp.visibleXDomain as readonly [Date, Date];
+    expect(start.getTime()).toBe(dataDomain[0].getTime());
+    expect(end.getTime()).toBe(dataDomain[1].getTime());
+  });
+
+  test("linearPreset shows the last `span` units", () => {
+    const vp = linearViewport([0, 100]);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "L20", label: "Last 20", span: 20 })],
+      dataDomain: [0, 100],
+    });
+    ctl.setActive("L20");
+    expect(vp.visibleXDomain).toEqual([80, 100]);
+  });
+
+  test("linearPreset with Infinity clamps to data extent", () => {
+    const vp = linearViewport([0, 100]);
+    vp.setVisibleDomain({ x: [25, 50] });
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "max", label: "MAX", span: Infinity })],
+      dataDomain: [0, 100],
+    });
+    ctl.setActive("max");
+    expect(vp.visibleXDomain).toEqual([0, 100]);
+  });
+
+  test("logPreset shows the last N decades, clamped to data lower bound", () => {
+    const vp = linearViewport([1, 1000]);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [
+        logPreset({ key: "1d", label: "1 decade", decades: 1 }),
+        logPreset({ key: "5d", label: "5 decades", decades: 5 }),
+      ],
+      dataDomain: [1, 1000],
+    });
+    ctl.setActive("1d");
+    expect(vp.visibleXDomain).toEqual([100, 1000]);
+
+    ctl.setActive("5d");
+    // 1000 / 10^5 = 0.01, clamped to data lower bound = 1
+    expect(vp.visibleXDomain).toEqual([1, 1000]);
+  });
+
+  test("custom resolver preset receives ctx and applies returned domain", () => {
+    const vp = linearViewport([0, 100]);
+    const seen: Array<{ dataDomain: unknown; now: number }> = [];
+    const custom: RangePreset = {
+      key: "half",
+      label: "Half",
+      resolve: (ctx) => {
+        seen.push({ dataDomain: ctx.dataDomain, now: ctx.now });
+        const [lo, hi] = ctx.dataDomain as readonly [number, number];
+        return [lo + (hi - lo) / 2, hi] as const;
+      },
+    };
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [custom],
+      dataDomain: [0, 100],
+      now,
+    });
+    ctl.setActive("half");
+    expect(vp.visibleXDomain).toEqual([50, 100]);
+    expect(seen).toEqual([{ dataDomain: [0, 100], now: FROZEN_NOW }]);
+  });
+
+  test("preset returning null leaves the viewport untouched and clears active", () => {
+    const vp = linearViewport([0, 100]);
+    vp.setVisibleDomain({ x: [10, 20] });
+    const declining: RangePreset = {
+      key: "nope",
+      label: "Nope",
+      resolve: () => null,
+    };
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [declining],
+    });
+    ctl.setActive("nope");
+    expect(vp.visibleXDomain).toEqual([10, 20]);
+    expect(ctl.getActive()).toBeNull();
+  });
+});
+
+describe("createRangePresets — active state + manual-change detection", () => {
+  test("setActive(null) clears active without touching the viewport", () => {
+    const vp = linearViewport([0, 100]);
+    vp.setVisibleDomain({ x: [30, 70] });
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "L20", label: "20", span: 20 })],
+      dataDomain: [0, 100],
+    });
+    ctl.setActive("L20");
+    expect(ctl.getActive()).toBe("L20");
+    expect(vp.visibleXDomain).toEqual([80, 100]);
+
+    ctl.setActive(null);
+    expect(ctl.getActive()).toBeNull();
+    // Viewport stays where the preset left it.
+    expect(vp.visibleXDomain).toEqual([80, 100]);
+  });
+
+  test("manual panBy clears active to null", () => {
+    const vp = linearViewport([0, 100]);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "L20", label: "20", span: 20 })],
+      dataDomain: [0, 100],
+    });
+    ctl.setActive("L20");
+    expect(ctl.getActive()).toBe("L20");
+
+    vp.panBy(10, 0);
+    expect(ctl.getActive()).toBeNull();
+  });
+
+  test("manual setVisibleDomain by consumer clears active", () => {
+    const vp = linearViewport([0, 100]);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "L20", label: "20", span: 20 })],
+      dataDomain: [0, 100],
+    });
+    ctl.setActive("L20");
+    expect(ctl.getActive()).toBe("L20");
+
+    vp.setVisibleDomain({ x: [40, 60] });
+    expect(ctl.getActive()).toBeNull();
+  });
+
+  test("y-axis change does not clear x-axis preset", () => {
+    const vp = linearViewport([0, 100]);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "L20", label: "20", span: 20 })],
+      dataDomain: [0, 100],
+    });
+    ctl.setActive("L20");
+    expect(ctl.getActive()).toBe("L20");
+
+    vp.setVisibleDomain({ y: [10, 50] });
+    expect(ctl.getActive()).toBe("L20");
+  });
+
+  test("re-activating the same preset is idempotent (no subscriber call)", () => {
+    const vp = linearViewport([0, 100]);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "L20", label: "20", span: 20 })],
+      dataDomain: [0, 100],
+    });
+    const calls: Array<string | null> = [];
+    ctl.subscribe((k) => calls.push(k));
+    ctl.setActive("L20");
+    ctl.setActive("L20");
+    expect(calls).toEqual(["L20"]);
+  });
+
+  test("subscribe fires on activate and on manual-change reset", () => {
+    const vp = linearViewport([0, 100]);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "L20", label: "20", span: 20 })],
+      dataDomain: [0, 100],
+    });
+    const calls: Array<string | null> = [];
+    const unsub = ctl.subscribe((k) => calls.push(k));
+
+    ctl.setActive("L20");
+    vp.panBy(5, 0);
+    expect(calls).toEqual(["L20", null]);
+
+    unsub();
+    ctl.setActive("L20");
+    expect(calls).toEqual(["L20", null]);
+  });
+
+  test("dispose unsubscribes from viewport and drops subscribers", () => {
+    const vp = linearViewport([0, 100]);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "L20", label: "20", span: 20 })],
+      dataDomain: [0, 100],
+    });
+    const calls: Array<string | null> = [];
+    ctl.subscribe((k) => calls.push(k));
+    ctl.setActive("L20");
+
+    ctl.dispose();
+    // After dispose, a manual pan should not produce any more subscriber
+    // calls (active-state diff is also disabled because we unsubscribed).
+    vp.panBy(10, 0);
+    expect(calls).toEqual(["L20"]);
+  });
+});
+
+describe("createRangePresets — dataDomain fallback", () => {
+  test("snapshots viewport's domain when dataDomain is omitted", () => {
+    const vp = linearViewport([0, 100]);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "max", label: "MAX", span: Infinity })],
+      // dataDomain omitted — should snapshot [0, 100] at construction.
+    });
+    vp.setVisibleDomain({ x: [25, 50] });
+    ctl.setActive("max");
+    expect(vp.visibleXDomain).toEqual([0, 100]);
+  });
+
+  test("dataDomain getter is re-read on each setActive", () => {
+    const vp = linearViewport([0, 100]);
+    let domain: [number, number] = [0, 100];
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "max", label: "MAX", span: Infinity })],
+      dataDomain: () => domain,
+    });
+    ctl.setActive("max");
+    expect(vp.visibleXDomain).toEqual([0, 100]);
+
+    // Simulate data appended — extent grows; next activation should reflect it.
+    domain = [0, 200];
+    ctl.setActive("max");
+    expect(vp.visibleXDomain).toEqual([0, 200]);
+  });
+});
+
+describe("createRangePresets — error handling", () => {
+  test("unknown key throws", () => {
+    const vp = linearViewport([0, 100]);
+    const ctl = createRangePresets({
+      viewport: vp,
+      axis: "x",
+      presets: [linearPreset({ key: "L20", label: "20", span: 20 })],
+      dataDomain: [0, 100],
+    });
+    expect(() => ctl.setActive("missing")).toThrow(/unknown preset key/);
+  });
+});

package/src/range-presets.ts

@@ -0,0 +1,349 @@
+// ---------------------------------------------------------------------------
+// createRangePresets — headless axis-range preset controller
+// ---------------------------------------------------------------------------
+// Generic across any continuous axis: time, linear, log, score thresholds,
+// spatial extents. Given a `DataViewport` and a list of `RangePreset`s, the
+// controller exposes `{ presets, setActive, getActive, subscribe, dispose }`.
+//
+// "Headless" means the library never touches the DOM — consumers render their
+// own chips/buttons/menu and call `setActive(key)` on click. The library owns
+// preset resolution + active-state diffing.
+//
+// Active-state goes to `null` ("custom") whenever the viewport's visible
+// domain on the controlled axis no longer matches the resolved domain the
+// last `setActive` applied. This makes manual pan / zoom / programmatic
+// `setVisibleDomain` calls correctly clear the active chip without the
+// consumer wiring anything else.
+
+import type { DateDomain, NumericDomain } from "./scales.ts";
+import type { DataViewport } from "./viewport.ts";
+import type { VisibleDomainInput } from "./viewport/axis-state.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Axis the controller drives. */
+export type RangePresetAxis = "x" | "y";
+
+/**
+ * Resolved domain a preset applies to the viewport. Numeric pair for linear /
+ * log / score axes; Date pair for time axes.
+ */
+export type RangePresetDomain = NumericDomain | DateDomain;
+
+/** Optional getter form for the data-extent fallback. */
+export type RangePresetDataDomain = RangePresetDomain | (() => RangePresetDomain);
+
+/**
+ * Context passed to a preset's `resolve` function. `dataDomain` is the full
+ * extent of the underlying data (either provided by the consumer at
+ * construction time or, if omitted, the viewport's current visible domain
+ * sampled at construction). `now` is the current time (epoch ms) — relevant
+ * for time presets; helpers like `linearPreset` ignore it.
+ */
+export interface RangePresetContext {
+  dataDomain: RangePresetDomain;
+  now: number;
+}
+
+/**
+ * A single preset entry. `resolve` returns the domain the viewport should be
+ * set to when the user activates this key. Return `null` to express "this
+ * preset has no valid domain given the current data" — the controller will
+ * leave the viewport untouched and not mark itself active.
+ */
+export interface RangePreset {
+  key: string;
+  label: string;
+  resolve: (ctx: RangePresetContext) => RangePresetDomain | null;
+}
+
+export interface RangePresetsOptions {
+  /**
+   * Any `DataViewport` regardless of axis-value type — accepts the
+   * `DataViewport<number, number>` returned by `MountedPlot.viewport` as
+   * well as the unparameterized form. The controller only reads visible
+   * domains and applies new ones through the viewport's continuous-axis
+   * API, so X/Y value types are not constrained at this layer.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  viewport: DataViewport<any, any>;
+  axis: RangePresetAxis;
+  presets: readonly RangePreset[];
+  /**
+   * Full data extent. Either a fixed `[min, max]` (numbers or Dates) or a
+   * getter that re-reads on each preset evaluation. If omitted, the
+   * controller snapshots the viewport's current visible domain at
+   * construction time and reuses it as the data domain.
+   */
+  dataDomain?: RangePresetDataDomain;
+  /** Defaults to `Date.now`. Re-evaluated on every `setActive`. */
+  now?: () => number;
+  /**
+   * Relative tolerance for the diff-against-snapshot custom check. A change
+   * smaller than `epsilon * max(|a|, |b|, 1)` on either endpoint is ignored.
+   * Defaults to `1e-6` — tight enough to detect a one-pixel pan, loose
+   * enough to absorb float round-trips through the axis scale.
+   */
+  epsilon?: number;
+}
+
+/** Subscriber receives the new active key, or `null` for "custom". */
+export type RangePresetsSubscriber = (active: string | null) => void;
+
+export interface RangePresetsController {
+  readonly presets: readonly RangePreset[];
+  /**
+   * Activate a preset by key. Re-resolves the preset, applies the resulting
+   * domain to the viewport, and remembers the resolved snapshot so future
+   * `onChange` events can detect manual changes. Passing `null` clears the
+   * active state without touching the viewport.
+   */
+  setActive(key: string | null): void;
+  /** Currently active preset key, or `null` if user has panned/zoomed manually. */
+  getActive(): string | null;
+  /** Subscribe to active-state changes. Returns an unsubscribe fn. */
+  subscribe(fn: RangePresetsSubscriber): () => void;
+  dispose(): void;
+}
+
+// ---------------------------------------------------------------------------
+// createRangePresets
+// ---------------------------------------------------------------------------
+
+export function createRangePresets(opts: RangePresetsOptions): RangePresetsController {
+  const viewport = opts.viewport;
+  const axis = opts.axis;
+  const presets = opts.presets;
+  const nowFn = opts.now ?? Date.now;
+  const epsilon = opts.epsilon ?? 1e-6;
+
+  const presetByKey = new Map(presets.map((p) => [p.key, p] as const));
+  const resolveDataDomain = (): RangePresetDomain => {
+    if (typeof opts.dataDomain === "function")
+      return (opts.dataDomain as () => RangePresetDomain)();
+    if (opts.dataDomain) return opts.dataDomain;
+    return readAxisDomain(viewport, axis);
+  };
+
+  // Snapshot the viewport's domain at construction to use as a fallback
+  // dataDomain, so a caller that omits `dataDomain` still gets a stable
+  // extent (rather than re-reading the current — possibly already panned —
+  // visible domain on every preset evaluation).
+  const snapshotDataDomain = opts.dataDomain === undefined ? readAxisDomain(viewport, axis) : null;
+  const getDataDomain = (): RangePresetDomain => snapshotDataDomain ?? resolveDataDomain();
+
+  let activeKey: string | null = null;
+  // Last domain the controller applied via setActive — used to detect when a
+  // subsequent viewport change came from outside (pan/zoom/setVisibleDomain
+  // by the consumer) and flip active back to `null`.
+  let lastAppliedDomain: RangePresetDomain | null = null;
+  let applying = 0;
+  const subscribers = new Set<RangePresetsSubscriber>();
+
+  const setActiveInternal = (next: string | null): void => {
+    if (next === activeKey) return;
+    activeKey = next;
+    for (const fn of subscribers) fn(next);
+  };
+
+  const unsubViewport = viewport.onChange(() => {
+    if (applying > 0) return;
+    if (activeKey === null || lastAppliedDomain === null) return;
+    const current = readAxisDomain(viewport, axis);
+    if (!domainsEqual(current, lastAppliedDomain, epsilon)) {
+      lastAppliedDomain = null;
+      setActiveInternal(null);
+    }
+  });
+
+  return {
+    presets,
+    setActive(key) {
+      if (key === null) {
+        lastAppliedDomain = null;
+        setActiveInternal(null);
+        return;
+      }
+      const preset = presetByKey.get(key);
+      if (!preset) {
+        throw new Error(`createRangePresets: unknown preset key "${key}"`);
+      }
+      const domain = preset.resolve({ dataDomain: getDataDomain(), now: nowFn() });
+      if (domain === null) {
+        // Preset declined to produce a domain — clear active without touching
+        // the viewport so the consumer's chip UI reflects the no-op.
+        lastAppliedDomain = null;
+        setActiveInternal(null);
+        return;
+      }
+      applying++;
+      try {
+        viewport.setVisibleDomain({ [axis]: domain as VisibleDomainInput });
+      } finally {
+        applying--;
+      }
+      // Re-read the viewport's domain post-apply. If clamping (panBounds,
+      // minZoom, maxZoom) altered the request, treat the *clamped* domain as
+      // the snapshot — that's what subsequent pans will be diffed against.
+      lastAppliedDomain = readAxisDomain(viewport, axis);
+      setActiveInternal(key);
+    },
+    getActive() {
+      return activeKey;
+    },
+    subscribe(fn) {
+      subscribers.add(fn);
+      return () => {
+        subscribers.delete(fn);
+      };
+    },
+    dispose() {
+      unsubViewport();
+      subscribers.clear();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Built-in preset helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Recognized time-preset keys. Each maps to a window relative to `now`
+ * (except `MAX`, which uses the full data extent, and `YTD` which goes
+ * from January 1 of the current year to `now`).
+ */
+export type TimePresetKey = "24H" | "7D" | "1M" | "3M" | "6M" | "1Y" | "YTD" | "MAX";
+
+const TIME_PRESET_MS: Record<Exclude<TimePresetKey, "YTD" | "MAX">, number> = {
+  "24H": 24 * 3600_000,
+  "7D": 7 * 24 * 3600_000,
+  "1M": 30 * 24 * 3600_000,
+  "3M": 90 * 24 * 3600_000,
+  "6M": 182 * 24 * 3600_000,
+  "1Y": 365 * 24 * 3600_000,
+};
+
+const TIME_PRESET_LABEL: Record<TimePresetKey, string> = {
+  "24H": "24H",
+  "7D": "7D",
+  "1M": "1M",
+  "3M": "3M",
+  "6M": "6M",
+  "1Y": "1Y",
+  YTD: "YTD",
+  MAX: "MAX",
+};
+
+/**
+ * Time-axis preset. Resolves to a `DateDomain` ending at `now` (or the data
+ * domain's end, for `MAX`). Built-in months use calendar-approximate
+ * constants (30/90/182/365 days) — close enough for chart UI.
+ */
+export function timePreset(key: TimePresetKey, label?: string): RangePreset {
+  const resolveLabel = label ?? TIME_PRESET_LABEL[key];
+  return {
+    key,
+    label: resolveLabel,
+    resolve: ({ dataDomain, now }) => {
+      if (key === "MAX") {
+        return toDateDomain(dataDomain);
+      }
+      if (key === "YTD") {
+        const start = new Date(Date.UTC(new Date(now).getUTCFullYear(), 0, 1));
+        return [start, new Date(now)] as DateDomain;
+      }
+      const span = TIME_PRESET_MS[key];
+      return [new Date(now - span), new Date(now)] as DateDomain;
+    },
+  };
+}
+
+/**
+ * Linear / numeric preset showing the last `span` units of `dataDomain` —
+ * i.e. `[max - span, max]`. Useful for "last 100m", "last 50 errors", etc.
+ * `MAX`-style behavior comes from passing `Infinity` (will clamp to the
+ * full data domain).
+ */
+export function linearPreset(opts: { key: string; label: string; span: number }): RangePreset {
+  return {
+    key: opts.key,
+    label: opts.label,
+    resolve: ({ dataDomain }) => {
+      const [lo, hi] = toNumericDomain(dataDomain);
+      if (!Number.isFinite(opts.span)) return [lo, hi] as NumericDomain;
+      const start = Math.max(lo, hi - opts.span);
+      return [start, hi] as NumericDomain;
+    },
+  };
+}
+
+/**
+ * Log-axis preset showing the last `decades` decades of the data — i.e.
+ * `[max / 10^decades, max]`, clamped to the data domain's lower bound.
+ * The viewport itself stays linear-or-log depending on its scale config;
+ * this helper just picks the domain endpoints.
+ */
+export function logPreset(opts: { key: string; label: string; decades: number }): RangePreset {
+  return {
+    key: opts.key,
+    label: opts.label,
+    resolve: ({ dataDomain }) => {
+      const [lo, hi] = toNumericDomain(dataDomain);
+      if (hi <= 0) return [lo, hi] as NumericDomain;
+      const candidate = hi / Math.pow(10, opts.decades);
+      const start = Math.max(lo, candidate);
+      return [start, hi] as NumericDomain;
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function readAxisDomain(viewport: DataViewport, axis: RangePresetAxis): RangePresetDomain {
+  const domain = axis === "x" ? viewport.visibleXDomain : viewport.visibleYDomain;
+  if (!Array.isArray(domain) || domain.length !== 2) {
+    throw new Error(`createRangePresets: ${axis}-axis must be a continuous (numeric or date) axis`);
+  }
+  // `Array.isArray` widens to `any[]`; the length check above guarantees this is
+  // a 2-tuple of numbers or Dates (band domains have length !== 2 only by luck,
+  // but a continuous axis is required by contract — hence the throw above).
+  return domain as unknown as RangePresetDomain;
+}
+
+function toNumericDomain(domain: RangePresetDomain): NumericDomain {
+  const [a, b] = domain;
+  return [domainEndAsNumber(a), domainEndAsNumber(b)] as NumericDomain;
+}
+
+function toDateDomain(domain: RangePresetDomain): DateDomain {
+  const [a, b] = domain;
+  return [domainEndAsDate(a), domainEndAsDate(b)] as DateDomain;
+}
+
+function domainEndAsNumber(value: number | Date): number {
+  return typeof value === "number" ? value : value.getTime();
+}
+
+function domainEndAsDate(value: number | Date): Date {
+  return typeof value === "number" ? new Date(value) : value;
+}
+
+function domainsEqual(a: RangePresetDomain, b: RangePresetDomain, epsilon: number): boolean {
+  const a0 = domainEndAsNumber(a[0]);
+  const a1 = domainEndAsNumber(a[1]);
+  const b0 = domainEndAsNumber(b[0]);
+  const b1 = domainEndAsNumber(b[1]);
+  return numberClose(a0, b0, epsilon) && numberClose(a1, b1, epsilon);
+}
+
+function numberClose(a: number, b: number, epsilon: number): boolean {
+  if (a === b) return true;
+  const diff = Math.abs(a - b);
+  const scale = Math.max(Math.abs(a), Math.abs(b), 1);
+  return diff <= epsilon * scale;
+}