@abdullahjaswal/tickyr-charts-solid 0.1.0

package/dist/charts/candle-chart-controller.d.ts

@@ -0,0 +1,353 @@
+import { CandleSeries, LiveState, EventMarker, DrawingType } from '../domain';
+import { Personalization, ChartFormatter } from '../personalization';
+import { CandleType, CandleChartBaseProps, CandleStaleBannerRenderProps, VolumeBarTooltipProps, SignalTooltipProps, OrderTooltipProps, PositionTooltipProps, ExtremeHoverState, HoverState, ResolvedSeriesArrays, CandleChartTooltipProps } from './candle-chart-helpers';
+import { ExtremeTooltipProps } from './line-chart-helpers';
+/** Provider snapshot - same shape as the other chart-controllers. */
+export interface CandleChartProviderSnapshot {
+    theme: import('../personalization').ThemeInput;
+    palette: string;
+    locale: string;
+    timeZone: string | undefined;
+    visualStyle: import('../personalization').VisualStyle;
+    outlineFillColor: "auto" | string;
+    outlineFillOpacity: number;
+    cornerRadius: number;
+    borderWidth: number;
+    accents: boolean;
+    osTheme: import('../personalization').Theme;
+    appTheme: import('../personalization').Theme;
+}
+/** Snapshot of derived state the adapter consumes for JSX. */
+export interface CandleChartRenderContext {
+    personalization: Personalization;
+    formatter: ChartFormatter;
+    resolvedLocaleBase: string;
+    resolvedTimeZone: string | undefined;
+    series: CandleSeries;
+    arr: ResolvedSeriesArrays;
+    candleType: CandleType;
+    ariaLabel: string;
+    isSparkline: boolean;
+    cssWidth: number;
+    cssHeight: number;
+}
+/** Closest marker under the pointer (within `MARKER_HIT_RADIUS_PX`).
+ *  Adapter renders the matching tooltip JSX (signal/order/position/event)
+ *  via the corresponding host-supplied render-prop. */
+export interface MarkerHoverState {
+    readonly kind: "signal" | "order" | "position" | "event";
+    /** Index in the marker array; `-1` for `'position'` (singleton). */
+    readonly idx: number;
+    readonly pointerX: number;
+    readonly pointerY: number;
+}
+export interface CandleChartControllerCallbacks {
+    onContextChange(ctx: CandleChartRenderContext): void;
+    onHoverChange(hover: HoverState | null): void;
+    onExtremeHoverChange(eh: ExtremeHoverState | null): void;
+    onLiveStateChange(s: LiveState): void;
+    onReducedMotionChange(v: boolean): void;
+    /** Whether a drawing tool is armed (host's UI typically reflects this
+     *  with a pressed-button state on the toolbar). */
+    onArmedToolChange(isDrawing: boolean): void;
+    /** Internal selection - fires when the controller's state changes. The
+     *  host can also pass `selectedDrawingId` as a controlled prop, in
+     *  which case this fires only when the host clears its prop and the
+     *  controller takes over. */
+    onSelectedDrawingIdChange(id: string | undefined): void;
+    /** Drawing currently under the pointer (used by `drawingHandlesMode:
+     *  'on-hover'`). `undefined` when the cursor is over empty area. */
+    onHoverDrawingIdChange(id: string | undefined): void;
+    /** Closest marker (signal/order/position/event) under the pointer; `null`
+     *  when nothing is in range. Adapter renders the matching tooltip JSX. */
+    onMarkerHoverChange(marker: MarkerHoverState | null): void;
+    /** Theme-cross-fade key - incremented every time `personalization.theme`
+     *  flips (light↔dark). Adapter uses it as a React `key` on the static
+     *  canvas to retrigger a CSS opacity-fade animation. Initial mount
+     *  emits `0`; subsequent flips emit `1`, `2`, … so the adapter can
+     *  skip the fade on first render. */
+    onThemeFadeKeyChange(key: number): void;
+    /** Whether the pointer is currently over the volume-pane divider band
+     *  (within `PANE_DRAG_HANDLE_PX`). Adapter swaps the cursor to
+     *  `row-resize` when `true`. */
+    onOverDividerChange(over: boolean): void;
+}
+/** Controller-specific prop type. Extends the framework-agnostic
+ *  `CandleChartBaseProps` (in `candle-chart-helpers.ts`) with the eight
+ *  render-prop fields whose return type is widened to `unknown` so both
+ *  the React adapter (returns `React.ReactNode`) and the Solid adapter
+ *  (returns `JSX.Element`) pass type-check via covariance. */
+export interface CandleChartControllerProps extends CandleChartBaseProps {
+    tooltip?: undefined | false | ((p: CandleChartTooltipProps) => unknown);
+    extremeTooltip?: boolean | ((p: ExtremeTooltipProps) => unknown);
+    volumeBarTooltip?: boolean | ((p: VolumeBarTooltipProps) => unknown);
+    staleBanner?: boolean | ((p: CandleStaleBannerRenderProps) => unknown);
+    signalTooltip?: false | ((p: SignalTooltipProps) => unknown);
+    orderTooltip?: false | ((p: OrderTooltipProps) => unknown);
+    positionTooltip?: false | ((p: PositionTooltipProps) => unknown);
+    eventTooltip?: false | ((p: {
+        marker: EventMarker;
+        pointerX: number;
+        pointerY: number;
+        formatter: ChartFormatter;
+    }) => unknown);
+}
+export interface CandleChartControllerMountOptions extends CandleChartControllerCallbacks {
+    /** The chart's outer container DOM node. Used by the visibility source
+     *  to pause draws when scrolled off-screen. May be null (e.g. in
+     *  controller-only test harnesses) - visibility then falls back to a
+     *  page-visibility-only stub. */
+    container?: HTMLElement | null;
+    staticCanvas: HTMLCanvasElement;
+    dynamicCanvas: HTMLCanvasElement | null;
+    initialProps: CandleChartControllerProps;
+    initialProvider: CandleChartProviderSnapshot;
+}
+export declare class CandleChartController {
+    private staticCanvas;
+    private dynamicCanvas;
+    private callbacks;
+    private props;
+    private providerCtx;
+    private handle;
+    private hoverState;
+    private extremeHoverState;
+    private dynCfg;
+    private liveStateInputs;
+    private reducedMotion;
+    private liveState;
+    private crosshairAlpha;
+    private armedTool;
+    private internalSelectedId;
+    private hoverDrawingId;
+    private keydownCleanup;
+    private markerHover;
+    private themeFadeKey;
+    private prevTheme;
+    private volumeHeightRatio;
+    private dividerDrag;
+    private overDivider;
+    /** External (prop-provided) volume ratio. When the prop changes, we
+     *  reset our internal state to it; user drag mutations override until
+     *  the prop changes again. */
+    private propVolumeHeightRatio;
+    private crosshairFadeAnim;
+    private crosshairFadeRafId;
+    private zoomWindow;
+    private panDrag;
+    /** Visible slice of `arr` after applying `zoomWindow`. When the window
+     *  is null, this aliases `arr`. Used for layout + drawFullCandleChart. */
+    private visibleArr;
+    private animState;
+    private animationRafId;
+    private bgChromeCanvas;
+    private fgChromeCanvas;
+    /** Closure captured at the end of `runStaticDraw()` that knows how to
+     *  composite the chrome caches + bars-only draw. Invoked per
+     *  animation rAF tick - bypasses the full static-draw path so axes /
+     *  text / drawings / markers stay cached. */
+    private directRedraw;
+    private series;
+    private historySeries;
+    private combinedSeries;
+    /** Dirty-rect tracking for partial dynamic-layer repaints.
+     *  Crosshair / marker overlays disturb only thin
+     *  strips + live-bar zone - clipping to those rectangles gives a
+     *  real GPU-fill saving. Auto-disabled below `shouldUseDirtyRects`
+     *  threshold; force-disabled via `partialRepaints: false` prop. */
+    private dirtyRing;
+    private dirtyScratch;
+    private useDirtyRects;
+    private prevHoverSnapX;
+    private prevHoverSnapY;
+    private prevHoverActive;
+    /** Unified marker quadtree. Holds POINT
+     *  markers - signals + events - at their resolved (px, py) coords.
+     *  ID encoded as `(kind << 24) | idx` so a single .nearest query
+     *  resolves to a (kind, idx) pair without per-pointer-event linear
+     *  scans. Order + position markers stay linear-tested because they
+     *  are horizontal-LINE markers (any-x at a fixed y), not points,
+     *  and a point quadtree wouldn't accelerate them. */
+    private markerQuadtree;
+    private markerQuadtreeBuilding;
+    /** Live last-bar overlay accumulated by `onTick(t, p, s)`. When set,
+     *  resolveDerived applies it to the most recent bar (high/low/close/
+     *  volume update - open is preserved from `props.data`). Reset whenever
+     *  `props.data` changes identity. */
+    private liveLastBar;
+    private liveLastBarSourceId;
+    /** rAF coalescer for onTick - multiple ticks in one frame yield a
+     *  single static-draw call. */
+    private onTickRafId;
+    /** Engine-backed streaming aggregator. Created lazily on the first
+     *  `onTick()` call when `props.streaming` is configured; otherwise
+     *  null and onTick falls through to JS-side last-bar mutation. */
+    private streamingEngine;
+    private streamingMarket;
+    /** Reused AggregationEvent scratch - engine writes into this per
+     *  pushTick (zero allocation per tick). */
+    private streamingEventScratch;
+    /** Identity of the `streaming` config we built the engine against;
+     *  changes → engine is torn down + rebuilt next tick. */
+    private streamingConfigId;
+    /** Pending engine-driven bars appended past `props.data` - when
+     *  `Engine.pushTick` returns `AppendNew`, we append a fresh bar
+     *  here so subsequent draws render the engine-aggregated history. */
+    private streamingAppendedTimes;
+    private streamingAppendedOpens;
+    private streamingAppendedHighs;
+    private streamingAppendedLows;
+    private streamingAppendedCloses;
+    private streamingAppendedVolumes;
+    private streamingAppendedLength;
+    private streamingAppendedCapacity;
+    /** VWAP overlay values. Computed once per static-draw when
+     *  `props.vwap` is configured + volumes are present. `null` when
+     *  inactive. Value math is
+     *  the engine's `vwap(highs, lows, closes, volumes, sessionStarts)`. */
+    private vwapValues;
+    private combinedArr;
+    private arr;
+    private personalization;
+    private resolvedLocale;
+    private formatter;
+    private candleType;
+    private isSparkline;
+    /** Resolved animation axes - clamped by reducedMotion. */
+    private animSettings;
+    private mqCleanup;
+    private staleTimeoutId;
+    private indicatorAbort;
+    private rafId;
+    private staticDrawAbort;
+    private disposed;
+    /** Visibility source - pauses the rAF loop when the chart is hidden
+     *  (tab background / scrolled off-screen). */
+    private visibility;
+    private visibilityUnsubscribe;
+    /** Watermark subscription - when `props.watermark` is `{ image: src }`,
+     *  the global `_watermarkSubscribers` set fires this on image load
+     *  so we can re-run the static draw to paint the now-decoded bitmap. */
+    private watermarkSub;
+    constructor(opts: CandleChartControllerMountOptions);
+    /** Arm a drawing tool. The next pointerdown captures anchor #1; subsequent
+     *  pointerdowns capture additional anchors; once `ANCHOR_COUNTS[type]`
+     *  anchors are captured, the drawing commits via `props.onDrawingsChange`
+     *  and the tool disarms. Hosts typically call this from a toolbar button. */
+    startDrawing(type: DrawingType): void;
+    /** Cancel an in-flight drawing without committing. */
+    cancelDrawing(): void;
+    /** Whether a drawing tool is currently armed. */
+    isDrawing(): boolean;
+    update(props: CandleChartControllerProps, providerCtx: CandleChartProviderSnapshot): void;
+    handlePointerMove(e: PointerEvent): void;
+    handlePointerLeave(): void;
+    /** Pointer-up - releases an in-flight pan-drag or divider-drag. */
+    handlePointerUp(e?: PointerEvent): void;
+    /** Wheel handler - zoom-around-cursor. Updates `zoomWindow` and
+     *  re-runs static draw. Snap-zoom (no smoothing
+     *  rAF) for now; smoothing is a future extension that adds an rAF
+     *  ramp over `panZoomSmoothing`-resolved duration. */
+    handleWheel(e: WheelEvent): void;
+    /** Pointerdown handles three roles depending on state:
+     *  1. If a drawing tool is armed: capture the next anchor at the
+     *     pointer's data-coordinate. When `ANCHOR_COUNTS[type]` anchors
+     *     are captured, commit the drawing via `props.onDrawingsChange`
+     *     and disarm the tool.
+     *  2. If no tool is armed and the pointer is over an existing drawing:
+     *     select that drawing.
+     *  3. Otherwise: clear selection. */
+    handlePointerDown(e: PointerEvent): void;
+    /** Imperative live-tick API. Two modes:
+     *
+     *  **Engine-backed (preferred):** when `props.streaming` is set the
+     *  controller routes ticks through the engine's `Engine.pushTick`
+     *  for validate-then-aggregate semantics. The engine handles bucket
+     *  transitions, anomaly detection, and OHLC math correctly. On
+     *  `AppendNew` events the new bar is appended to the visible series.
+     *
+     *  **JS-side (fallback):** updates high/low/close of the current last
+     *  bar in-place. Open is preserved - host owns bar progression (call
+     *  `update({ data })` with a fresh last bar to start a new bucket).
+     *
+     *  Multiple ticks per rAF coalesce into a single static-draw call.
+     *  Primitive args - no per-tick object allocation. */
+    onTick(time: number, price: number, size?: number): void;
+    /** Manual last-bar mutation path. Host owns bar progression. */
+    private routeTickJsSide;
+    /** Engine-backed path. Lazy-spawns the streaming engine on first
+     *  use; routes the tick through `Engine.pushTick`; folds the result
+     *  into either the live-bar overlay (`MutateLast`) or the appended
+     *  ring (`AppendNew`). */
+    private routeTickThroughEngine;
+    /** Compute the live-bar overlay for the most recent visible bar based
+     *  on the engine's `MutateLast` event. */
+    private applyLiveLastBarFromEvent;
+    /** Grow the engine-bar ring + append the freshly-closed bar. */
+    private appendEngineBar;
+    /** Concatenate engine-appended bars onto the host-provided series.
+     *  Allocates one set of typed arrays per static draw. */
+    private appendEngineBarsToSeries;
+    /** Internal: clone the base series's last bar with live-tick
+     *  high/low/close/volume merged in. Open is preserved. Allocates one
+     *  set of typed arrays per static draw. */
+    private applyLiveLastBar;
+    dispose(): void;
+    private setHover;
+    private setExtremeHover;
+    private setMarkerHover;
+    private setSelectedDrawingId;
+    private setHoverDrawingId;
+    /** Build a `DrawCtx` for hit-test against drawings. Mirrors the
+     *  shape `drawDrawing` consumes; `selected` is unused here so we
+     *  pass a placeholder. */
+    private makeDrawCtx;
+    /** Esc keydown handler. Cancels an in-flight drawing tool, otherwise
+     *  deletes the selected drawing (if any) and `drawingDeleteOnEsc` is
+     *  not disabled. */
+    private setupKeydownListener;
+    private repaintDynamic;
+    /** Push V-strip + H-strip + marker-dot + live-bar-zone rects into
+     *  the dirty ring covering both the previous and current hover
+     *  positions. */
+    private pushDynamicDirtyRects;
+    private resolveDerived;
+    private applyDynamicCfgFromProps;
+    private applyLiveStateInputsFromProps;
+    private setupReducedMotionWatcher;
+    private tearDownReducedMotionWatcher;
+    private kickStaleTimeout;
+    private kickRafLoop;
+    private tearDownRafLoop;
+    /** Detect data changes since the previous prop snapshot. Mounts the
+     *  entry animation once on first 0→N transition; later last-bar
+     *  mutations (same length, new lastClose) trigger the update animation.
+     *  Mirrors the React adapter's detect-data-changes useEffect. */
+    private detectDataChanges;
+    /** Animation rAF - engages only while entry or update is in flight.
+     *  This loop does NOT trigger any state
+     *  change; it mutates `animState` in place and invokes `directRedraw`
+     *  which composites the chrome cache + paints just the bars. No
+     *  layout rebuild. */
+    private kickAnimationRaf;
+    private tearDownAnimationRaf;
+    /** Crosshair fade - ramps `crosshairAlpha` toward `target` over
+     *  `personalization.crosshairFadeDuration` ms. The rAF
+     *  body mutates state in place, no allocations per frame. Instant
+     *  (no rAF) when duration === 0 or already at target. */
+    private kickCrosshairFade;
+    private tearDownCrosshairFadeRaf;
+    /** When `props.watermark` is `{ image: src }`, the watermark image
+     *  loads asynchronously via the global cache. Subscribe so the chart
+     *  can re-run static draw once the image is decoded - the bitmap then
+     *  composites into the FG chrome offscreen on the next paint. */
+    private setupWatermarkSubscription;
+    private tearDownWatermarkSubscription;
+    private runStaticDraw;
+    /** Build (or rebuild) the unified marker quadtree. Async because the
+     *  engine's Quadtree ctor lives in WASM; the pointer-query path is
+     *  sync. While rebuild is in flight the previous tree continues to
+     *  serve queries (stale coords); we swap on completion. */
+    private kickMarkerQuadtreeRebuild;
+}
+export type { CandleType, HoverState, ExtremeHoverState, ChartHandle, ChartLayout, DynamicCfg, ResolvedSeriesArrays, IndicatorComputeResult, LiveStateInputs, CandleChartBaseProps, } from './candle-chart-helpers';