@coderyo/renderer-lite 1.0.3 → 1.1.1

package/dist/index.d.ts

@@ -1,6 +1,7 @@
+import * as lightweight_charts from 'lightweight-charts';
+import { IChartApi, LineData, UTCTimestamp, LogicalRange } from 'lightweight-charts';
 import { Interval, Bar } from '@coderyo/data';
 import { IndicatorConfig } from '@coderyo/indicators';
-import { IChartApi, LineData, UTCTimestamp } from 'lightweight-charts';
 
 interface ChartVisibleRange {
     fromMs: number;
@@ -21,6 +22,7 @@ declare class TimeScaleBus {
     visibleFromMs: number;
     visibleToMs: number;
     register(chart: IChartApi): void;
+    unregister(chart: IChartApi): void;
     subscribeTransform(listener: TransformListener): () => void;
     setBarsTimeRange(fromMs: number, toMs: number): void;
     getVisibleRange(): ChartVisibleRange | null;
@@ -28,10 +30,45 @@ declare class TimeScaleBus {
     setBarSpacing(spacing: number): void;
     setVisibleTimeRange(range: ChartVisibleRange): void;
     scrollToLogicalPosition(position: number, animated?: boolean): void;
+    /**
+     * DESIGN §10.4.1: after historical prepend, shift every pane's logical range by Δ
+     * so canonical `visibleFromMs` / `visibleToMs` (and crosshair time mapping) stay fixed.
+     */
+    compensatePrependLogicalRange(delta: number, referenceChart?: IChartApi, sliceTimes?: readonly number[]): void;
     private syncFrom;
     private emit;
 }
 
+/** Trim; empty / whitespace → independent pane (no cross-pane sync). */
+declare function normalizeSyncGroupId(id?: string | null): string | null;
+type PaneSyncKey = 'main' | 'volume' | 'indicator';
+declare function independentBusKey(pane: PaneSyncKey): string;
+declare function resolveBusMapKey(groupId: string | null | undefined, pane: PaneSyncKey): string;
+interface PaneSyncGroupPatch {
+    main?: string | null;
+    volume?: string | null;
+    indicator?: string | null;
+}
+/**
+ * One {@link TimeScaleBus} per sync group id; empty group id → per-pane independent bus.
+ */
+declare class TimeScaleBusRegistry {
+    private readonly buses;
+    private readonly paneKeys;
+    private activeKey;
+    constructor();
+    getOrCreateBus(key: string): TimeScaleBus;
+    getBusKeyForPane(pane: PaneSyncKey): string;
+    getBusForPane(pane: PaneSyncKey): TimeScaleBus;
+    /** Active bus for IChart viewport APIs (follows last-focused chart pane). */
+    get activeBus(): TimeScaleBus;
+    getActiveBusKey(): string;
+    setActivePane(pane: PaneSyncKey): void;
+    setPaneSyncGroup(pane: PaneSyncKey, groupId: string | null | undefined): string;
+    forEachBus(fn: (key: string, bus: TimeScaleBus) => void): void;
+    moveChart(chart: IChartApi, fromKey: string, toKey: string, copyRange?: boolean): void;
+}
+
 type ScaleMode = 'linear' | 'log';
 interface CrosshairPayload {
     time: number;
@@ -49,8 +86,18 @@ interface PinePlotLine {
     color?: string;
     values: (number | null)[];
 }
+type ChartPaneId = 'main' | 'volume' | 'indicator';
+declare function isLayeredPaneMount(opts: Pick<PaneOrchestratorOptions, 'volumeMount'>): boolean;
+declare function shouldResizeChartPane(focus: Set<ChartPaneId> | null, pane: ChartPaneId): boolean;
 interface PaneOrchestratorOptions {
+    /** Main candlestick mount (required). */
     container: HTMLElement;
+    /**
+     * P2: separate volume layer host; when set, no flex column in container.
+     * Mount order: create empty `chartMain` + `chartVolume` nodes first, pass to compositor widgets,
+     * then `createChart(chartMain, { volumeMount: chartVolume })` so LWC mounts after layer frames apply.
+     */
+    volumeMount?: HTMLElement;
     indicatorRoot?: HTMLElement;
     theme?: 'dark' | 'light';
     scaleMode?: ScaleMode;
@@ -68,9 +115,22 @@ interface PaneOrchestratorOptions {
     /** When true (default), set bar spacing on interval reload — does not change visible bar count. */
     autoBarSpacingOnInterval?: boolean;
     barSpacingByInterval?: Partial<Record<Interval, number>>;
+    /**
+     * When false, do not listen for `tradview:pane-resize` (ChartController owns that path).
+     * @default true for standalone orchestrator use; ChartController passes false.
+     */
+    listenPaneResizeEvents?: boolean;
 }
 declare class PaneOrchestrator {
-    readonly bus: TimeScaleBus;
+    readonly busRegistry: TimeScaleBusRegistry;
+    /** Active sync group bus (last-focused pane); used by ChartController viewport APIs. */
+    get bus(): TimeScaleBus;
+    private readonly layeredPanes;
+    private readonly mainEl;
+    private readonly volWrap;
+    private detachMainVolResizer;
+    private resizeFocusPanes;
+    private readonly listenPaneResizeEvents;
     private readonly mainChart;
     private readonly volumeChart;
     private readonly mainSeries;
@@ -93,6 +153,9 @@ declare class PaneOrchestrator {
     private barTimesOrdered;
     private didInitialFit;
     private skipNextInitialFit;
+    /** setBars ran before the pane had layout size; refit on first real resize. */
+    private pendingViewportFit;
+    private pendingViewportBars;
     private indicatorConfig;
     private onIndicatorConfigChange?;
     private currentInterval;
@@ -102,6 +165,7 @@ declare class PaneOrchestrator {
     private barAnimator;
     private smoothPriceDurationMs;
     constructor(opts: PaneOrchestratorOptions);
+    private readonly onPaneResize;
     setSmoothPriceUpdate(enabled: boolean, durationMs?: number): void;
     /** Update the last candle (and price line); optional smooth interpolation. */
     updateLastBar(target: Bar, opts?: {
@@ -113,12 +177,27 @@ declare class PaneOrchestrator {
     setIntervalContext(interval: Interval): void;
     setTheme(theme: 'dark' | 'light'): void;
     setIndicatorConfig(config: IndicatorConfig | null): void;
+    private isVolumeVisible;
+    private closeVolumePane;
+    private applyVolumeVisibility;
+    /** Assign per-pane sync group ids (`''` / omit = independent). Re-registers LWC charts on group change. */
+    setPaneSyncGroups(patch: PaneSyncGroupPatch): void;
+    setActiveSyncPane(pane: ChartPaneId): void;
+    /** P2: when set, only these panes get LWC resize (panes in the same sync group still share TimeScaleBus). */
+    setResizeFocusPanes(panes: ChartPaneId[] | null): void;
+    /** Current resize focus (null = all panes). @internal — not part of public package API. */
+    getResizeFocusPanes(): ChartPaneId[] | null;
+    private shouldResizePane;
+    private rebuildMainVolumeResizer;
     setPinePlots(plots: PinePlotLine[] | null): void;
     private teardownIndicatorStack;
     private applyMainOverlays;
     private syncPinePlotSeries;
     setShowGrid(show: boolean): void;
     setBars(bars: Bar[], gaps?: number[]): void;
+    private mainPaneHasSize;
+    private tryInitialViewportFit;
+    private flushPendingViewportFit;
     subscribeCrosshair(listener: (payload: CrosshairPayload | null) => void): () => void;
     private findNearestBar;
     private createIndicatorStack;
@@ -133,6 +212,11 @@ declare class PaneOrchestrator {
     resetViewState(): void;
     /** Skip the next automatic fitContent after setBars (used by reloadHistory). */
     preserveViewportOnNextSetBars(): void;
+    /**
+     * DESIGN §10.4.1: after `mergeBars(..., prepend)` shift logical ranges on every sync bus
+     * so canonical ms viewport and crosshair `t` stay stable.
+     */
+    compensatePrependForBuses(sortedTimesBefore: readonly number[], sortedTimesAfter: readonly number[], interval: Interval): void;
     getVisibleRange(): ChartVisibleRange | null;
     getBarSpace(): number;
     setBarSpace(px: number): void;
@@ -144,6 +228,11 @@ declare class PaneOrchestrator {
     scrollToRealtime(): void;
     setLogScale(enabled: boolean): void;
     resize(): void;
+    /**
+     * Resize every LWC pane once for viewport fit; does **not** change {@link resizeFocusPanes}.
+     * @internal Used by ChartController data refresh paths.
+     */
+    resizeAllPanes(): void;
     getOverlayCanvas(): HTMLCanvasElement | null;
     timeToX(tMs: number): number | null;
     priceToY(price: number): number | null;
@@ -158,6 +247,12 @@ declare class PaneOrchestrator {
     private layoutForTheme;
 }
 
+declare function attachPaneResizer(topPane: HTMLElement, bottomPane: HTMLElement, opts?: {
+    minTopPx?: number;
+    minBottomPx?: number;
+    storageKey?: string;
+}): () => void;
+
 type IndicatorPaneId = 'macd' | 'rsi' | 'kdj';
 interface IndicatorPaneStackOptions {
     theme?: 'dark' | 'light';
@@ -192,6 +287,8 @@ declare class IndicatorPaneStack {
     setConfig(config: IndicatorConfig): void;
     private closePane;
     private applyPaneVisibility;
+    /** Rebuild flex children and drag handles only between visible panes. */
+    private rebuildPaneLayout;
     clearBars(): void;
     private warmupLookback;
     private detectBarMutation;
@@ -206,6 +303,8 @@ declare class IndicatorPaneStack {
     destroy(): void;
     private createPaneWrap;
     private layoutForTheme;
+    /** LWC instances for sync-group reassignment. */
+    getCharts(): IChartApi[];
 }
 declare function maOverlayLine(bars: Bar[], period?: number, source?: IndicatorConfig['source']): LineData<UTCTimestamp>[];
 declare function volMaOverlayLine(bars: Bar[], period?: number): LineData<UTCTimestamp>[];
@@ -216,6 +315,46 @@ declare function bollOverlayLines(bars: Bar[], period: number, mult: number, sou
     lower: LineData<UTCTimestamp>[];
 };
 
+/** Slice of loaded bar open times for the current render window (DESIGN §10.4.1). */
+declare function buildSliceTimes(sortedTimes: readonly number[], renderFromMs: number, renderToMs: number): number[];
+/** Count bars newly present in slice after prepend merge. */
+declare function countPrependSliceDelta(beforeSlice: readonly number[], afterSlice: readonly number[]): number;
+/** Map LWC logical index (position in slice) to canonical bar time `t` (ms). */
+declare function logicalIndexToBarTimeMs(sliceTimes: readonly number[], logicalIndex: number): number | null;
+/** Mirrors {@link VirtualWindow.getRenderRange} for prepend slice math. */
+declare function deriveRenderRange(visibleFromMs: number, visibleToMs: number, sortedTimes: readonly number[], intervalMs: number): {
+    renderFromMs: number;
+    renderToMs: number;
+};
+/** Logical range covering canonical visible ms within a slice (DESIGN §10.4.1 fallback). */
+declare function logicalRangeForVisibleWindow(sliceTimes: readonly number[], visibleFromMs: number, visibleToMs: number): LogicalRange | null;
+interface PrependSliceDeltaInput {
+    sortedTimesBefore: readonly number[];
+    sortedTimesAfter: readonly number[];
+    visibleFromMs: number;
+    visibleToMs: number;
+    intervalMs: number;
+}
+/** Δ new bars in render slice after historical prepend (canonical ms window unchanged). */
+declare function computePrependSliceDeltaForViewport(input: PrependSliceDeltaInput): number;
+interface CompensatePrependOnRegistryOptions {
+    registry: TimeScaleBusRegistry;
+    sortedTimesBefore: readonly number[];
+    sortedTimesAfter: readonly number[];
+    intervalMs: number;
+    /** Reference chart for logical range read (e.g. main pane). */
+    referenceChart?: lightweight_charts.IChartApi;
+}
+/** Apply §10.4.1 logicalRange offset on every bus with an initialized visible window. */
+declare function compensatePrependOnRegistry(opts: CompensatePrependOnRegistryOptions): void;
+interface CompensatePrependOnBusOptions {
+    sortedTimesBefore: readonly number[];
+    sortedTimesAfter: readonly number[];
+    intervalMs: number;
+    referenceChart?: lightweight_charts.IChartApi;
+}
+declare function compensatePrependOnBus(bus: TimeScaleBus, opts: CompensatePrependOnBusOptions): void;
+
 /**
  * Default horizontal bar spacing (px) per interval so candle width feels consistent
  * when the integrator controls how many bars are loaded / visible.
@@ -223,4 +362,4 @@ declare function bollOverlayLines(bars: Bar[], period: number, mult: number, sou
 declare function defaultBarSpacingForInterval(interval: Interval): number;
 declare function resolveBarSpacingForInterval(interval: Interval, overrides?: Partial<Record<Interval, number>>): number;
 
-export { type ChartVisibleRange, type CrosshairPayload, type IndicatorPaneId, IndicatorPaneStack, type IndicatorPaneStackOptions, PaneOrchestrator, type PaneOrchestratorOptions, type PinePlotLine, type ScaleMode, TimeScaleBus, type TransformState, bollOverlayLines, defaultBarSpacingForInterval, detectIndicatorBarMutation, emaOverlayLine, maOverlayLine, resolveBarSpacingForInterval, volMaOverlayLine };
+export { type ChartPaneId, type ChartVisibleRange, type CompensatePrependOnBusOptions, type CompensatePrependOnRegistryOptions, type CrosshairPayload, type IndicatorPaneId, IndicatorPaneStack, type IndicatorPaneStackOptions, PaneOrchestrator, type PaneOrchestratorOptions, type PaneSyncGroupPatch, type PaneSyncKey, type PinePlotLine, type PrependSliceDeltaInput, type ScaleMode, TimeScaleBus, TimeScaleBusRegistry, type TransformState, attachPaneResizer, bollOverlayLines, buildSliceTimes, compensatePrependOnBus, compensatePrependOnRegistry, computePrependSliceDeltaForViewport, countPrependSliceDelta, defaultBarSpacingForInterval, deriveRenderRange, detectIndicatorBarMutation, emaOverlayLine, independentBusKey, isLayeredPaneMount, logicalIndexToBarTimeMs, logicalRangeForVisibleWindow, maOverlayLine, normalizeSyncGroupId, resolveBarSpacingForInterval, resolveBusMapKey, shouldResizeChartPane, volMaOverlayLine };