velo-plot 1.11.1 → 1.15.0

package/dist/core/stacked/types.d.ts

@@ -0,0 +1,120 @@
+import { Chart } from '../chart/types';
+import { ChartGroup, SyncAxis, SyncOptions } from '../sync';
+import { ChartOptions as RootChartOptions, Range, SeriesOptions } from '../../types';
+import { LayoutOptions } from '../layout';
+
+/** Stack layout direction */
+export type StackDirection = "vertical" | "horizontal";
+/** Per-pane configuration (max 5 panes per stack) */
+export interface StackedPaneConfig {
+    id: string;
+    /** Flex ratio (e.g. 0.6) or CSS length ("24%", "80px") — height ratio when vertical, width ratio when horizontal */
+    height: number | string;
+    /** Chart options excluding container/id (series added via chart API or `series`) */
+    chart?: Omit<RootChartOptions, "container" | "id">;
+    /** Series to add immediately after pane chart is created */
+    series?: SeriesOptions[];
+    /** Show native X axis (default: only bottom pane when vertical + sharedXAxis; each pane when horizontal) */
+    showXAxis?: boolean;
+    /** Show native Y axis (default: only first pane when horizontal + sharedYAxis) */
+    showYAxis?: boolean;
+    /** Receive pan/zoom (default: true on every pane) */
+    interactive?: boolean;
+    /** Lock Y range — skips auto fit on Y for this pane */
+    yRange?: Range | "auto";
+}
+export interface StackedChartOptions {
+    /** Root container (will be cleared and filled with pane layout) */
+    container: HTMLDivElement;
+    /** 1–5 stacked panes */
+    panes: StackedPaneConfig[];
+    /** Layout direction (default: vertical — panes top to bottom) */
+    direction?: StackDirection;
+    /** Pane that drives sync (default: first pane) */
+    masterPaneId?: string;
+    /** Shared date/time row on bottom pane only (vertical layout) */
+    sharedXAxis?: "bottom" | "none";
+    /** Shared Y axis on left pane only (horizontal layout) */
+    sharedYAxis?: "left" | "none";
+    /** Shared theme applied to every pane */
+    theme?: string | object;
+    devicePixelRatio?: number;
+    /** Gap between panes in CSS pixels (default: 0) */
+    gap?: number;
+    /** Enable VS Code–style drag resize between panes (default: false) */
+    resizable?: boolean | {
+        /** Min pane height as fraction of available stack height (default: 1/6) */
+        minPaneRatio?: number;
+        /** Absolute min pane height in px — overrides ratio when larger */
+        minPanePx?: number;
+        dividerSize?: number;
+    };
+    /** Show legend on panes (default: false — set true on stack or per-pane chart) */
+    showLegend?: boolean;
+    /**
+     * Pan/zoom sync between panes.
+     * Default: X-axis sync via master pane (`axis: 'x'`, Y independent).
+     * Pass `false` for fully independent panes.
+     */
+    sync?: boolean | StackedSyncOptions;
+    /** Shared margin overrides — left/right aligned automatically across panes */
+    layout?: Partial<LayoutOptions>;
+}
+export interface StackedChart {
+    readonly container: HTMLDivElement;
+    getPane(id: string): Chart | undefined;
+    getPanes(): Chart[];
+    getMaster(): Chart;
+    getGroup(): ChartGroup;
+    fitAll(options?: {
+        x?: Range;
+        padding?: number;
+    }): void;
+    resetAll(): void;
+    resize(): void;
+    /** Current flex ratios keyed by pane id */
+    getPaneRatios(): Record<string, number>;
+    /** Set flex ratios (same keys as pane ids); triggers resize */
+    setPaneRatios(ratios: Record<string, number>): void;
+    /** Sync axis mode: `x` (default), `y`, `xy`, or `none` */
+    setSyncAxis(axis: SyncAxis): void;
+    getSyncAxis(): SyncAxis;
+    /** Update pan/zoom/cursor sync options at runtime */
+    setSyncOptions(options: Partial<StackedSyncOptions>): void;
+    /** Resolves when all pane charts have started rendering */
+    whenReady(): Promise<void>;
+    /** Export the entire stack as one PNG/JPEG/WebP image (WYSIWYG layout) */
+    exportImage(options?: StackSnapshotOptions): Promise<string>;
+    /** Alias for exportImage */
+    snapshot(options?: StackSnapshotOptions): Promise<string>;
+    destroy(): void;
+}
+export declare const STACKED_MAX_PANES = 5;
+/** Default minimum pane height as a fraction of available stack height (1/6). */
+export declare const STACKED_DEFAULT_MIN_PANE_RATIO: number;
+export declare const STACKED_COMPACT_MARGIN: {
+    top: number;
+    bottom: number;
+    left: number;
+};
+export declare const STACKED_FULL_X_MARGIN: {
+    bottom: number;
+};
+export declare const STACKED_FULL_Y_MARGIN: {
+    left: number;
+};
+/** Options for full-stack image export */
+export type StackSnapshotFormat = "png" | "jpeg" | "webp";
+export type StackSnapshotResolution = "standard" | "2k" | "4k" | "8k" | number;
+export interface StackSnapshotOptions {
+    format?: StackSnapshotFormat;
+    quality?: number;
+    resolution?: StackSnapshotResolution;
+    includeBackground?: boolean;
+    includeDividers?: boolean;
+    transparent?: boolean;
+    download?: boolean;
+    fileName?: string;
+}
+/** Pan/zoom sync between stacked panes (Y stays independent when axis is `x`). */
+export type StackedSyncOptions = Pick<SyncOptions, "axis" | "syncCursor" | "syncSelection" | "syncZoom" | "syncPan" | "bidirectional" | "debounce">;

package/dist/core/sync/index.d.ts

@@ -2,66 +2,54 @@ import { Bounds, Range } from '../../types';
 
 export type SyncAxis = 'x' | 'y' | 'xy' | 'none';
 export interface SyncOptions {
-    /** Synchronize axis (default: 'x') */
     axis?: SyncAxis;
-    /** Synchronize cursor position (default: true) */
     syncCursor?: boolean;
-    /** Synchronize selection state (default: false) */
     syncSelection?: boolean;
-    /** Synchronize zoom level (default: true) */
     syncZoom?: boolean;
-    /** Synchronize pan (default: true) */
     syncPan?: boolean;
-    /** Debounce time for sync events in ms (default: 0) */
     debounce?: number;
-    /** Enable bidirectional sync (default: true) */
     bidirectional?: boolean;
+    /** When set, used for fitAll; with bidirectional sync any pane can drive pan/zoom */
+    masterId?: string;
 }
 export interface ChartLike {
-    /** Unique identifier for the chart */
     getId(): string;
-    /** Get current view bounds */
     getViewBounds(): Bounds;
-    /** Set view bounds (zoom) */
     zoom(options: {
         x?: Range;
         y?: Range;
         animate?: boolean;
     }): void;
-    /** Pan the chart */
     pan(dx: number, dy: number): void;
-    /** Get cursor position */
+    fit?(options?: {
+        x?: Range;
+        y?: Range;
+        padding?: number | {
+            x?: number;
+            y?: number;
+        };
+    }): void;
     getCursorPosition?(): {
         x: number;
         y: number;
     } | null;
-    /** Set external cursor position */
     setExternalCursor?(x: number, y: number): void;
-    /** Clear external cursor */
     clearExternalCursor?(): void;
-    /** Get selected points */
     getSelectedPoints?(): {
         seriesId: string;
         indices: number[];
     }[];
-    /** Set selection */
     selectPoints?(points: {
         seriesId: string;
         indices: number[];
     }[]): void;
-    /** Clear selection */
     clearSelection?(): void;
-    /** Subscribe to events */
     on(event: string, callback: (...args: unknown[]) => void): void;
-    /** Unsubscribe from events */
     off(event: string, callback: (...args: unknown[]) => void): void;
 }
 export interface SyncEvent {
-    /** Source chart ID */
     sourceId: string;
-    /** Event type */
     type: 'zoom' | 'pan' | 'cursor' | 'selection' | 'bounds';
-    /** Event data */
     data: unknown;
 }
 export declare class ChartGroup {
@@ -70,59 +58,34 @@ export declare class ChartGroup {
     private eventHandlers;
     private isUpdating;
     private debounceTimers;
+    private rafTimers;
     constructor(options?: SyncOptions);
-    /**
-     * Add a chart to the group
-     */
     add(chart: ChartLike): this;
-    /**
-     * Add multiple charts at once
-     */
     addAll(...charts: ChartLike[]): this;
-    /**
-     * Remove a chart from the group
-     */
     remove(chart: ChartLike): this;
-    /**
-     * Get all charts in the group
-     */
     getCharts(): ChartLike[];
-    /**
-     * Get chart count
-     */
     size(): number;
-    /**
-     * Check if a chart is in the group
-     */
     has(chart: ChartLike): boolean;
-    /**
-     * Set synchronization axis
-     */
     syncAxis(axis: SyncAxis): this;
-    /**
-     * Enable/disable cursor synchronization
-     */
+    syncZoom(enabled: boolean): this;
+    syncPan(enabled: boolean): this;
     syncCursor(enabled: boolean): this;
-    /**
-     * Enable/disable selection synchronization
-     */
     syncSelection(enabled: boolean): this;
-    /**
-     * Synchronize all charts to a specific view
-     */
+    /** Update sync options and re-bind event handlers on all charts */
+    updateOptions(partial: Partial<SyncOptions>): this;
+    getOptions(): Readonly<SyncOptions>;
     syncTo(bounds: Partial<Bounds>, excludeChartId?: string): void;
-    /**
-     * Reset all charts to auto-scale
-     */
     resetAll(): void;
-    /**
-     * Clear all selections in the group
-     */
+    fitAll(options?: {
+        x?: Range;
+        padding?: number;
+    }): void;
+    batch<T>(fn: () => T): T;
     clearAllSelections(): void;
-    /**
-     * Destroy the group and cleanup
-     */
     destroy(): void;
+    private isSyncSource;
+    private canPropagateFrom;
+    private hasValidViewBounds;
     private attachEventHandlers;
     private detachEventHandlers;
     private handleZoom;
@@ -131,17 +94,9 @@ export declare class ChartGroup {
     private handleSelection;
     private propagateZoom;
     private propagatePan;
+    private scheduleSyncAction;
     private debounceAction;
 }
-/**
- * Create a chart group with specified charts
- */
 export declare function createChartGroup(charts: ChartLike[], options?: SyncOptions): ChartGroup;
-/**
- * Link two charts for synchronized viewing
- */
 export declare function linkCharts(chart1: ChartLike, chart2: ChartLike, options?: SyncOptions): ChartGroup;
-/**
- * Create a master-slave relationship (master controls slave)
- */
 export declare function createMasterSlave(master: ChartLike, slave: ChartLike, axis?: SyncAxis): ChartGroup;