velo-plot 2.0.0 → 3.0.0

package/dist/svelte/index.test.ts

@@ -0,0 +1,20 @@
+import { describe, it, expect } from "vitest";
+import * as svelte from "./index";
+
+describe("svelte index", () => {
+  it("re-exports public svelte bindings", () => {
+    expect(svelte.createVeloPlot).toBeTypeOf("function");
+    expect(svelte.useVeloPlot).toBe(svelte.createVeloPlot);
+    expect(svelte.createStackedPlot).toBeTypeOf("function");
+    expect(svelte.useStackedPlot).toBe(svelte.createStackedPlot);
+    expect(svelte.useIndicator).toBeTypeOf("function");
+    expect(svelte.useChartSync).toBeTypeOf("function");
+    expect(svelte.useChartGroup).toBe(svelte.useChartSync);
+  });
+
+  it("keeps SciPlot aliases for backward compatibility", () => {
+    expect(svelte.useSciPlot).toBe(svelte.useVeloPlot);
+    expect(svelte.createSciPlot).toBe(svelte.createVeloPlot);
+    expect(svelte.useSciChart).toBe(svelte.useVeloPlot);
+  });
+});

package/dist/svelte/index.ts

@@ -0,0 +1,15 @@
+export { createVeloPlot, useVeloPlot, type UseVeloPlotOptions } from "./useVeloPlot";
+export { createStackedPlot, useStackedPlot } from "./useStackedPlot";
+export { useIndicator } from "./useIndicator";
+export { useChartSync, useChartGroup } from "./useChartSync";
+
+import { useVeloPlot as useVeloPlotImpl, createVeloPlot as createVeloPlotImpl } from "./useVeloPlot";
+
+/** @deprecated Use `useVeloPlot` / `createVeloPlot` instead. **Removed in v4.0.** */
+export const useSciPlot = useVeloPlotImpl;
+/** @deprecated Use `createVeloPlot` instead. **Removed in v4.0.** */
+export const createSciPlot = createVeloPlotImpl;
+/** @deprecated Use `useVeloPlot` instead. **Removed in v4.0.** */
+export const useSciChart = useVeloPlotImpl;
+
+// Svelte components: import from 'velo-plot/svelte/VeloPlot.svelte' (shipped as source)

package/dist/svelte/useChartSync.d.ts

@@ -0,0 +1,8 @@
+import { ChartLike, SyncOptions, ChartGroup } from '../core/sync';
+
+export declare function useChartSync(getCharts: () => ChartLike[], options?: SyncOptions): {
+    group: import('svelte/store').Writable<ChartGroup | null>;
+    sync: () => void;
+    destroy: () => void;
+};
+export declare const useChartGroup: typeof useChartSync;

package/dist/svelte/useChartSync.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi } from "vitest";
+import { get } from "svelte/store";
+import { useChartSync } from "./useChartSync";
+import { buildMockChart } from "../bindings/test-utils";
+
+const destroy = vi.fn();
+const mockGroup = { destroy };
+
+vi.mock("../bindings/shared", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../bindings/shared")>();
+  return {
+    ...actual,
+    createChartSync: vi.fn(() => ({ group: mockGroup, destroy })),
+  };
+});
+
+describe("useChartSync svelte", () => {
+  it("re-sync destroys previous chart sync handle", () => {
+    const charts = [buildMockChart("a"), buildMockChart("b")];
+    const api = useChartSync(() => charts, { axis: "x" });
+    api.sync();
+    api.sync();
+    expect(destroy).toHaveBeenCalled();
+  });
+
+  it("syncs multiple charts with options", () => {
+    const charts = [buildMockChart("a"), buildMockChart("b")];
+    const api = useChartSync(() => charts, { axis: "y" });
+    api.sync();
+    expect(get(api.group)).toBe(mockGroup);
+    api.destroy();
+    expect(destroy).toHaveBeenCalled();
+  });
+
+  it("syncs multiple charts and destroys", () => {
+    const charts = [buildMockChart("a"), buildMockChart("b")];
+    const api = useChartSync(() => charts);
+    api.sync();
+    expect(get(api.group)).toBe(mockGroup);
+    api.destroy();
+    expect(destroy).toHaveBeenCalled();
+  });
+
+  it("skips sync for single chart", () => {
+    const api = useChartSync(() => [buildMockChart()]);
+    api.sync();
+    expect(get(api.group)).toBeNull();
+  });
+});

package/dist/svelte/useChartSync.ts

@@ -0,0 +1,29 @@
+import { writable } from "svelte/store";
+import type { ChartLike, SyncOptions } from "../core/sync";
+import { ChartGroup } from "../core/sync";
+import { createChartSync } from "../bindings/shared";
+
+export function useChartSync(getCharts: () => ChartLike[], options?: SyncOptions) {
+  const group = writable<ChartGroup | null>(null);
+  let handle: ReturnType<typeof createChartSync> | null = null;
+
+  const sync = () => {
+    handle?.destroy();
+    const charts = getCharts();
+    if (charts.length < 2) {
+      group.set(null);
+      return;
+    }
+    handle = createChartSync(charts, options);
+    group.set(handle.group);
+  };
+
+  const destroy = () => {
+    handle?.destroy();
+    group.set(null);
+  };
+
+  return { group, sync, destroy };
+}
+
+export const useChartGroup = useChartSync;

package/dist/svelte/useIndicator.d.ts

@@ -0,0 +1,13 @@
+import { AddIndicatorOptions, AddIndicatorResult } from '../core/indicator/addIndicator';
+import { IndicatorPresetName } from '../core/indicator/indicatorPresets';
+import { IndicatorHost } from '../bindings/shared';
+
+export declare function useIndicator(getHost: () => IndicatorHost, preset: IndicatorPresetName, options?: AddIndicatorOptions): {
+    result: import('svelte/store').Writable<(AddIndicatorResult & {
+        paneId?: string;
+    }) | null>;
+    isLoading: import('svelte/store').Writable<boolean>;
+    error: import('svelte/store').Writable<Error | null>;
+    run: () => Promise<void>;
+    cleanup: () => void;
+};

package/dist/svelte/useIndicator.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { get } from "svelte/store";
+import { useIndicator } from "./useIndicator";
+import { buildMockChart } from "../bindings/test-utils";
+
+vi.mock("../bindings/shared", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../bindings/shared")>();
+  return {
+    ...actual,
+    addIndicatorToHost: vi.fn(async () => ({ id: "rsi", seriesIds: ["rsi"] })),
+    removeIndicatorFromChart: vi.fn(),
+    isStackedChart: vi.fn(() => false),
+  };
+});
+
+describe("useIndicator svelte", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("loads indicator and cleans up on chart host", async () => {
+    const chart = buildMockChart();
+    const api = useIndicator(() => chart, "rsi");
+    await api.run();
+    expect(get(api.result)?.id).toBe("rsi");
+    api.cleanup();
+    const { removeIndicatorFromChart } = await import("../bindings/shared");
+    expect(removeIndicatorFromChart).toHaveBeenCalledWith(chart, "rsi");
+  });
+
+  it("records errors", async () => {
+    const { addIndicatorToHost } = await import("../bindings/shared");
+    vi.mocked(addIndicatorToHost).mockRejectedValueOnce(new Error("fail"));
+    const api = useIndicator(() => buildMockChart(), "macd");
+    await api.run();
+    expect(get(api.error)?.message).toBe("fail");
+  });
+
+  it("skips when host is null", async () => {
+    const api = useIndicator(() => null, "rsi");
+    await api.run();
+    expect(get(api.result)).toBeNull();
+  });
+
+  it("cleanup no-ops without indicator result", () => {
+    const api = useIndicator(() => buildMockChart(), "rsi");
+    api.cleanup();
+  });
+
+  it("skips cleanup for stacked chart hosts", async () => {
+    const { isStackedChart, removeIndicatorFromChart } = await import("../bindings/shared");
+    vi.mocked(isStackedChart).mockReturnValueOnce(true);
+    const chart = buildMockChart();
+    const api = useIndicator(() => chart, "ema");
+    await api.run();
+    api.cleanup();
+    expect(removeIndicatorFromChart).not.toHaveBeenCalled();
+  });
+
+  it("wraps non-error rejections", async () => {
+    const { addIndicatorToHost } = await import("../bindings/shared");
+    vi.mocked(addIndicatorToHost).mockRejectedValueOnce("plain failure");
+    const api = useIndicator(() => buildMockChart(), "macd");
+    await api.run();
+    expect(get(api.error)?.message).toBe("plain failure");
+  });
+});

package/dist/svelte/useIndicator.ts

@@ -0,0 +1,43 @@
+import { writable } from "svelte/store";
+import type { AddIndicatorOptions, AddIndicatorResult } from "../core/indicator/addIndicator";
+import type { IndicatorPresetName } from "../core/indicator/indicatorPresets";
+import { addIndicatorToHost, isStackedChart, removeIndicatorFromChart, type IndicatorHost } from "../bindings/shared";
+import type { Chart } from "../core/chart/types";
+
+export function useIndicator(
+  getHost: () => IndicatorHost,
+  preset: IndicatorPresetName,
+  options: AddIndicatorOptions = {},
+) {
+  const result = writable<(AddIndicatorResult & { paneId?: string }) | null>(null);
+  const isLoading = writable(false);
+  const error = writable<Error | null>(null);
+
+  const run = async () => {
+    const host = getHost();
+    if (!host) return;
+    isLoading.set(true);
+    try {
+      const res = await addIndicatorToHost(host, preset, options);
+      result.set(res);
+      isLoading.set(false);
+    } catch (e) {
+      error.set(e instanceof Error ? e : new Error(String(e)));
+      isLoading.set(false);
+    }
+  };
+
+  const cleanupIndicator = () => {
+    const host = getHost();
+    let currentId: string | null = null;
+    const unsub = result.subscribe((r) => {
+      currentId = r?.id ?? null;
+    });
+    unsub();
+    if (currentId && host && !isStackedChart(host)) {
+      removeIndicatorFromChart(host as Chart, currentId);
+    }
+  };
+
+  return { result, isLoading, error, run, cleanup: cleanupIndicator };
+}

package/dist/svelte/useStackedPlot.d.ts

@@ -0,0 +1,16 @@
+import { StackedChart, StackedChartOptions } from '../core/stacked';
+import { Range } from '../types';
+
+export declare function createStackedPlot(options: Omit<StackedChartOptions, "container">): {
+    stack: import('svelte/store').Writable<StackedChart | null>;
+    isReady: import('svelte/store').Writable<boolean>;
+    mount: (container: HTMLDivElement) => void;
+    unmount: () => void;
+    sync: (next: Omit<StackedChartOptions, "container">) => void;
+    fitAll: (opts?: {
+        x?: Range;
+        padding?: number;
+    }) => void | undefined;
+    resetAll: () => void | undefined;
+};
+export { createStackedPlot as useStackedPlot };

package/dist/svelte/useStackedPlot.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi } from "vitest";
+import { get } from "svelte/store";
+import { createStackedPlot } from "./useStackedPlot";
+
+const mockStack = {
+  destroy: vi.fn(),
+  whenReady: () => Promise.resolve(),
+  container: document.createElement("div"),
+  fitAll: vi.fn(),
+  resetAll: vi.fn(),
+};
+
+let paneKey = "a";
+
+vi.mock("../core/stacked", () => ({
+  createStackedChart: vi.fn(() => mockStack),
+}));
+
+vi.mock("../bindings/shared", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../bindings/shared")>();
+  return {
+    ...actual,
+    stackedStructureKey: () => paneKey,
+    syncStackedPaneSeries: vi.fn(() => new Map()),
+    syncStackedOptions: vi.fn(),
+  };
+});
+
+describe("createStackedPlot svelte", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    paneKey = "a";
+  });
+
+  it("mounts stacked chart", () => {
+    const el = document.createElement("div");
+    const api = createStackedPlot({ panes: [{ id: "p", height: 1, series: [] }] });
+    api.mount(el);
+    expect(get(api.stack)).toBe(mockStack);
+    api.fitAll();
+    api.resetAll();
+    api.unmount();
+    expect(mockStack.destroy).toHaveBeenCalled();
+  });
+
+  it("syncs options when structure is unchanged", async () => {
+    const { syncStackedOptions } = await import("../bindings/shared");
+    paneKey = "same";
+    const el = document.createElement("div");
+    const api = createStackedPlot({ panes: [{ id: "p", height: 1, series: [] }], theme: "dark" });
+    api.mount(el);
+    await mockStack.whenReady();
+    api.sync({ panes: [{ id: "p", height: 1, series: [] }], theme: "light" });
+    expect(syncStackedOptions).toHaveBeenCalled();
+    api.unmount();
+  });
+
+  it("skips sync when stack is not ready", async () => {
+    const { syncStackedOptions } = await import("../bindings/shared");
+    paneKey = "same";
+    const api = createStackedPlot({ panes: [{ id: "p", height: 1, series: [] }] });
+    api.sync({ panes: [{ id: "p", height: 1, series: [] }], theme: "dark" });
+    expect(syncStackedOptions).not.toHaveBeenCalled();
+  });
+
+  it("remounts when pane structure changes", async () => {
+    paneKey = "a";
+    const el = document.createElement("div");
+    const api = createStackedPlot({ panes: [{ id: "p", height: 1, series: [] }] });
+    api.mount(el);
+    await mockStack.whenReady();
+    paneKey = "b";
+    api.sync({ panes: [{ id: "q", height: 1, series: [] }] });
+    expect(mockStack.destroy).toHaveBeenCalled();
+  });
+});

package/dist/svelte/useStackedPlot.ts

@@ -0,0 +1,54 @@
+import { writable, get } from "svelte/store";
+import { createStackedChart } from "../core/stacked";
+import type { StackedChart, StackedChartOptions } from "../core/stacked";
+import type { Range } from "../types";
+import { stackedStructureKey, syncStackedOptions, syncStackedPaneSeries } from "../bindings/shared";
+import type { VeloPlotSeries } from "../bindings/shared";
+
+export function createStackedPlot(options: Omit<StackedChartOptions, "container">) {
+  const stack = writable<StackedChart | null>(null);
+  const isReady = writable(false);
+  let destroy: (() => void) | null = null;
+  let structureKey = stackedStructureKey(options.panes);
+  let paneSeries = new Map<string, Map<string, VeloPlotSeries>>();
+
+  const mount = (container: HTMLDivElement) => {
+    destroy?.();
+    const created = createStackedChart({ ...options, container });
+    stack.set(created);
+    destroy = () => created.destroy();
+    structureKey = stackedStructureKey(options.panes);
+    paneSeries = syncStackedPaneSeries(created, options.panes, new Map());
+    created.whenReady().then(() => isReady.set(true));
+  };
+
+  const sync = (next: Omit<StackedChartOptions, "container">) => {
+    const s = get(stack);
+    if (!s || !get(isReady)) return;
+    const nextKey = stackedStructureKey(next.panes);
+    if (nextKey !== structureKey) {
+      mount(s.container);
+      return;
+    }
+    syncStackedOptions(s, next);
+    paneSeries = syncStackedPaneSeries(s, next.panes, paneSeries);
+  };
+
+  const unmount = () => {
+    destroy?.();
+    stack.set(null);
+    isReady.set(false);
+  };
+
+  return {
+    stack,
+    isReady,
+    mount,
+    unmount,
+    sync,
+    fitAll: (opts?: { x?: Range; padding?: number }) => get(stack)?.fitAll(opts),
+    resetAll: () => get(stack)?.resetAll(),
+  };
+}
+
+export { createStackedPlot as useStackedPlot };

package/dist/svelte/useVeloPlot.d.ts

@@ -0,0 +1,21 @@
+import { Chart } from '../core/Chart';
+import { SeriesOptions, SeriesUpdateData, ZoomOptions, Bounds } from '../types';
+import { ChartBindingOptions } from '../bindings/shared';
+
+export interface UseVeloPlotOptions extends ChartBindingOptions {
+}
+export declare function createVeloPlot(options?: UseVeloPlotOptions): {
+    chart: import('svelte/store').Writable<Chart | null>;
+    isReady: import('svelte/store').Writable<boolean>;
+    error: import('svelte/store').Writable<Error | null>;
+    bounds: import('svelte/store').Writable<Bounds | null>;
+    mount: (container: HTMLDivElement) => void;
+    unmount: () => void;
+    updateOptions: (next: UseVeloPlotOptions) => void;
+    addSeries: (opts: SeriesOptions) => void;
+    updateSeries: (id: string, data: SeriesUpdateData) => void | undefined;
+    removeSeries: (id: string) => void | undefined;
+    zoom: (z: ZoomOptions) => void | undefined;
+    resetZoom: () => void;
+};
+export { createVeloPlot as useVeloPlot };

package/dist/svelte/useVeloPlot.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { get } from "svelte/store";
+import { createVeloPlot } from "./useVeloPlot";
+import { buildMockChart } from "../bindings/test-utils";
+import * as shared from "../bindings/shared";
+
+const mockChart = buildMockChart();
+
+vi.mock("../bindings/shared/chartLifecycle", () => ({
+  createChartLifecycle: vi.fn(() => ({
+    chart: mockChart,
+    getBounds: () => mockChart.getViewBounds(),
+    destroy: mockChart.destroy,
+  })),
+}));
+
+vi.spyOn(shared, "optionsChanged").mockReturnValue(true);
+vi.spyOn(shared, "syncChartOptions");
+
+describe("createVeloPlot svelte", () => {
+  afterEach(() => {
+    document.body.replaceChildren();
+    vi.clearAllMocks();
+    vi.mocked(shared.optionsChanged).mockReturnValue(true);
+  });
+
+  it("mounts and exercises chart API", () => {
+    const el = document.createElement("div");
+    document.body.appendChild(el);
+    const api = createVeloPlot({ animations: false });
+    api.mount(el);
+    expect(get(api.isReady)).toBe(true);
+    api.addSeries({ id: "s", type: "line", data: { x: new Float32Array(), y: new Float32Array() } });
+    api.updateSeries("s", { x: new Float32Array(), y: new Float32Array() });
+    api.removeSeries("s");
+    api.zoom({ x: [0, 1] });
+    api.resetZoom();
+    api.updateOptions({ theme: "dark" });
+    expect(shared.syncChartOptions).toHaveBeenCalled();
+    api.unmount();
+    expect(mockChart.destroy).toHaveBeenCalled();
+    el.remove();
+  });
+
+  it("remounts chart on second mount call", () => {
+    const el = document.createElement("div");
+    const api = createVeloPlot({});
+    api.mount(el);
+    api.mount(el);
+    expect(mockChart.destroy).toHaveBeenCalled();
+    api.unmount();
+  });
+
+  it("invokes onBoundsChange from lifecycle", async () => {
+    const el = document.createElement("div");
+    const api = createVeloPlot({});
+    api.mount(el);
+    const { createChartLifecycle } = await import("../bindings/shared/chartLifecycle");
+    const callbacks = vi.mocked(createChartLifecycle).mock.calls.at(-1)?.[2] ?? {};
+    callbacks.onBoundsChange?.(mockChart.getViewBounds());
+    expect(get(api.bounds)).toEqual(mockChart.getViewBounds());
+    api.unmount();
+  });
+
+  it("updateOptions skips sync when chart is missing", () => {
+    const api = createVeloPlot({ theme: "dark" });
+    vi.mocked(shared.syncChartOptions).mockClear();
+    api.updateOptions({ theme: "light" });
+    expect(shared.syncChartOptions).not.toHaveBeenCalled();
+  });
+
+  it("updateOptions skips sync when options are unchanged", () => {
+    vi.mocked(shared.optionsChanged).mockReturnValue(false);
+    const el = document.createElement("div");
+    const api = createVeloPlot({ theme: "dark" });
+    api.mount(el);
+    vi.mocked(shared.syncChartOptions).mockClear();
+    api.updateOptions({ theme: "dark" });
+    expect(shared.syncChartOptions).not.toHaveBeenCalled();
+    api.unmount();
+  });
+
+  it("records lifecycle errors", async () => {
+    const { createChartLifecycle } = await import("../bindings/shared/chartLifecycle");
+    vi.mocked(createChartLifecycle).mockImplementationOnce((_el, _opts, callbacks = {}) => {
+      queueMicrotask(() => callbacks.onError?.(new Error("svelte lifecycle")));
+      return {
+        chart: mockChart,
+        getBounds: () => mockChart.getViewBounds(),
+        destroy: mockChart.destroy,
+      };
+    });
+    const el = document.createElement("div");
+    const api = createVeloPlot({});
+    api.mount(el);
+    await Promise.resolve();
+    expect(get(api.error)?.message).toBe("svelte lifecycle");
+    api.unmount();
+  });
+});

package/dist/svelte/useVeloPlot.ts

@@ -0,0 +1,81 @@
+/**
+ * Svelte composables for velo-plot (exported as functions).
+ */
+
+import { writable, get } from "svelte/store";
+import type { Chart } from "../core/Chart";
+import type { SeriesOptions, SeriesUpdateData, ZoomOptions, Bounds } from "../types";
+import {
+  createChartLifecycle,
+  type ChartBindingOptions,
+  optionsChanged,
+  syncChartOptions,
+  pickSyncableOptions,
+} from "../bindings/shared";
+
+export interface UseVeloPlotOptions extends ChartBindingOptions {}
+
+export function createVeloPlot(options: UseVeloPlotOptions = {}) {
+  const chart = writable<Chart | null>(null);
+  const isReady = writable(false);
+  const error = writable<Error | null>(null);
+  const bounds = writable<Bounds | null>(null);
+
+  let destroy: (() => void) | null = null;
+  let prevSync = pickSyncableOptions(options);
+
+  const mount = (container: HTMLDivElement) => {
+    destroy?.();
+    const handle = createChartLifecycle(container, options, {
+      onBoundsChange: (b) => bounds.set(b),
+      onError: (e) => error.set(e),
+    });
+    chart.set(handle.chart);
+    destroy = handle.destroy;
+    bounds.set(handle.getBounds());
+    isReady.set(true);
+    prevSync = pickSyncableOptions(options);
+  };
+
+  const updateOptions = (next: UseVeloPlotOptions) => {
+    const c = get(chart);
+    if (!c) return;
+    const picked = pickSyncableOptions(next);
+    if (optionsChanged(prevSync, picked)) {
+      syncChartOptions(c, prevSync, picked);
+      prevSync = picked;
+    }
+  };
+
+  const unmount = () => {
+    destroy?.();
+    destroy = null;
+    chart.set(null);
+    isReady.set(false);
+  };
+
+  return {
+    chart,
+    isReady,
+    error,
+    bounds,
+    mount,
+    unmount,
+    updateOptions,
+    addSeries: (opts: SeriesOptions) => {
+      get(chart)?.addSeries(opts);
+      const c = get(chart);
+      if (c) bounds.set(c.getViewBounds());
+    },
+    updateSeries: (id: string, data: SeriesUpdateData) => get(chart)?.updateSeries(id, data),
+    removeSeries: (id: string) => get(chart)?.removeSeries(id),
+    zoom: (z: ZoomOptions) => get(chart)?.zoom(z),
+    resetZoom: () => {
+      get(chart)?.resetZoom();
+      const c = get(chart);
+      if (c) bounds.set(c.getViewBounds());
+    },
+  };
+}
+
+export { createVeloPlot as useVeloPlot };

package/dist/svelte.d.ts

@@ -0,0 +1 @@
+export * from './svelte/index'