@dwlf/charting 1.0.0 → 1.1.1

package/dist/charting/types.d.ts

@@ -0,0 +1,454 @@
+export interface LinePoint {
+    t: number;
+    v: number;
+}
+export interface OhlcPoint {
+    t: number;
+    o: number;
+    h: number;
+    l: number;
+    c: number;
+}
+export type Candle = OhlcPoint;
+export type SeriesType = 'line' | 'hist' | 'area' | 'ohlc' | 'marker' | 'position';
+export interface SeriesStyle {
+    color?: string;
+    lineWidth?: number;
+    dashed?: boolean;
+    opacity?: number;
+    markerShape?: 'arrow-up' | 'arrow-down' | 'circle';
+    markerSize?: number;
+    markerOffsetY?: number;
+    markerFontSize?: number;
+    markerTextColor?: string;
+    markerTextOffsetY?: number;
+    riskColor?: string;
+    rewardColor?: string;
+    bubbleColor?: string;
+    textColor?: string;
+    fontSize?: number;
+    pointer?: boolean;
+    padding?: number;
+}
+export type TooltipFormatter = (point: any) => string;
+export interface SeriesSpec {
+    key: string;
+    type: SeriesType;
+    data: any[];
+    /** Shorthand for style.color. If both are set, style.color takes precedence. */
+    color?: string;
+    style?: SeriesStyle;
+    tooltipFormatter?: TooltipFormatter;
+    showInTooltip?: boolean;
+    /**
+     * Optional click handler invoked when a point belonging to this series is
+     * clicked. The callback receives the raw datum found by the hit-testing
+     * logic (for markers this is typically the marker datum; for OHLC, the
+     * candle; for lines, the nearest LinePoint).
+     *
+     * Consumers should treat this as best-effort hit-testing around the
+     * current crosshair time.
+     */
+    onClick?: (raw: any) => void;
+}
+export interface PaneGuide {
+    y: number;
+    dashed?: boolean;
+    label?: string;
+    color?: string;
+    /**
+     * Optional start time for partial-width guides (e.g., S/R lines that start
+     * at their formation bar). If omitted, the guide extends from the left edge.
+     */
+    startTime?: number;
+    /**
+     * Optional end time for partial-width guides. If omitted, the guide extends
+     * to the right edge.
+     */
+    endTime?: number;
+}
+export interface PaneSpec {
+    id: string;
+    title?: string;
+    heightRatio: number;
+    yScale: {
+        mode: 'auto' | 'fixed';
+        min?: number;
+        max?: number;
+    };
+    series: SeriesSpec[];
+    guides?: PaneGuide[];
+}
+export interface ChartSpec {
+    panes: PaneSpec[];
+    timeFormatter?: (t: number) => string;
+    onCrosshairMove?: (t: number) => void;
+    /**
+     * When true, include all series (markers, positions, overlays) when deriving
+     * the automatic Y-domain for panes that contain OHLC data. By default only
+     * OHLC series influence the auto-scale, while panes without OHLC series
+     * continue to consider every series to avoid empty domains.
+     */
+    includeOverlaysInAutoScale?: boolean;
+    /**
+     * Optional global handler fired when the user clicks on the chart canvas
+     * and a nearest series/point has been resolved. This is useful for
+     * higher-level interactions (e.g. selecting a cycle-low marker) without
+     * requiring every series to declare its own onClick handler.
+     */
+    onSeriesPointClick?: (info: {
+        paneId: string;
+        seriesKey: string;
+        time: number;
+        raw: any;
+    }) => void;
+}
+export interface PaneComputedScale {
+    domain: [number, number];
+    scale: (value: number) => number;
+    invert: (value: number) => number;
+}
+/** X-axis scale function with optional invert/range accessors */
+export type XScale = ((value: number) => number) & {
+    invert?: (value: number) => number | Date;
+    range?: () => [number, number];
+};
+export type AnnotationType = 'hline' | 'vline' | 'text' | 'trendline' | 'ray' | 'crossline' | 'rectangle' | 'emoji' | 'timerange' | 'arrow' | 'channel' | 'fibRetracement' | 'measure' | 'alert_line' | 'brush' | 'pitchfork' | 'fib_extension' | 'order_block' | 'fair_value_gap' | 'bos_line';
+export type LineStyle = 'solid' | 'dashed' | 'dotted';
+export interface AnnotationBase {
+    id: string;
+    type: AnnotationType;
+    symbol: string;
+    timeframe: string;
+    /** Timeframes this annotation is visible on. Null/undefined/empty = visible on all. */
+    visibleTimeframes?: string[];
+    createdAt: number;
+    updatedAt: number;
+}
+export interface HLineAnnotation extends AnnotationBase {
+    type: 'hline';
+    price: number;
+    color: string;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    label?: string;
+    showPrice: boolean;
+}
+export interface VLineAnnotation extends AnnotationBase {
+    type: 'vline';
+    time: number;
+    color: string;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    label?: string;
+    showTime: boolean;
+}
+export interface TextAnnotation extends AnnotationBase {
+    type: 'text';
+    time: number;
+    price: number;
+    text: string;
+    color: string;
+    backgroundColor?: string;
+    fontSize: number;
+}
+/** A single point in a freehand brush stroke (chart coordinates). */
+export type BrushPoint = LinePoint;
+/** Standard Fibonacci retracement level ratios */
+export declare const FIB_LEVELS_DEFAULT: readonly [0, 0.236, 0.382, 0.5, 0.618, 0.786, 1];
+/** Optional extension levels beyond the 0–100% range */
+export declare const FIB_EXTENSIONS_DEFAULT: readonly [1.272, 1.618, 2, 2.618];
+export interface TrendLineAnnotation extends AnnotationBase {
+    type: 'trendline';
+    time1: number;
+    price1: number;
+    time2: number;
+    price2: number;
+    color?: string;
+    lineWidth?: number;
+    lineStyle?: LineStyle;
+    label?: string;
+    extendLeft: boolean;
+    extendRight: boolean;
+}
+export interface ChannelAnnotation extends AnnotationBase {
+    type: 'channel';
+    /** First anchor point of the base line */
+    time1: number;
+    price1: number;
+    /** Second anchor point of the base line */
+    time2: number;
+    price2: number;
+    /**
+     * Price offset for the parallel line. Positive = above the base line,
+     * negative = below. The parallel line runs through
+     * (time1, price1 + priceOffset) → (time2, price2 + priceOffset).
+     */
+    priceOffset: number;
+    color: string;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    label?: string;
+    /** Opacity of the fill between the two parallel lines (0–1) */
+    fillOpacity: number;
+    extendLeft: boolean;
+    extendRight: boolean;
+}
+export interface RayAnnotation extends AnnotationBase {
+    type: 'ray';
+    time1: number;
+    price1: number;
+    time2: number;
+    price2: number;
+    color: string;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    label?: string;
+}
+export interface RectangleAnnotation extends AnnotationBase {
+    type: 'rectangle';
+    time1: number;
+    price1: number;
+    time2: number;
+    price2: number;
+    color: string;
+    fillOpacity: number;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    label?: string;
+}
+export interface TimeRangeAnnotation extends AnnotationBase {
+    type: 'timerange';
+    time1: number;
+    time2: number;
+    color: string;
+    fillOpacity: number;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    label?: string;
+}
+export interface CrossLineAnnotation extends AnnotationBase {
+    type: 'crossline';
+    time: number;
+    price: number;
+    color: string;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    label?: string;
+    showPrice: boolean;
+    showTime: boolean;
+}
+export interface AlertLineAnnotation extends AnnotationBase {
+    type: 'alert_line';
+    price: number;
+    color: string;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    label?: string;
+    showPrice: boolean;
+    /** Whether the alert has been triggered */
+    triggered: boolean;
+    /** Direction: 'above' = alert when price crosses above, 'below' = crosses below */
+    direction: 'above' | 'below';
+    /** Server-side alert ID from POST /v2/alerts (set after sync) */
+    alertId?: string;
+}
+export interface EmojiAnnotation extends AnnotationBase {
+    type: 'emoji';
+    time: number;
+    price: number;
+    emoji: string;
+    size: number;
+}
+export interface ArrowAnnotation extends AnnotationBase {
+    type: 'arrow';
+    /** Text box / callout origin point */
+    time1: number;
+    price1: number;
+    /** Arrow target point (arrowhead rendered here) */
+    time2: number;
+    price2: number;
+    text: string;
+    color: string;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    fontSize: number;
+}
+export interface FibRetracementAnnotation extends AnnotationBase {
+    type: 'fibRetracement' | 'measure';
+    /** Swing point 1 (typically the high or low where the move starts) */
+    time1: number;
+    price1: number;
+    /** Swing point 2 (the other extreme of the move) */
+    time2: number;
+    price2: number;
+    color: string;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    label?: string;
+    /** Opacity of the fill bands between adjacent levels (0–1) */
+    fillOpacity: number;
+    /** Fib ratios to display. Defaults to FIB_LEVELS_DEFAULT. */
+    levels: number[];
+    /** Whether to show extension levels beyond 100% */
+    showExtensions: boolean;
+    /** Whether to extend level lines to the right edge of the chart */
+    extendRight: boolean;
+}
+export interface MeasureAnnotation extends AnnotationBase {
+    type: 'measure';
+    /** First anchor point */
+    time1: number;
+    price1: number;
+    /** Second anchor point */
+    time2: number;
+    price2: number;
+    color: string;
+}
+export interface BrushAnnotation extends AnnotationBase {
+    type: 'brush';
+    /** Ordered array of points forming the freehand path. */
+    points: BrushPoint[];
+    color: string;
+    lineWidth: number;
+}
+/**
+ * Andrew's Pitchfork — three-point tool.
+ * P1 is the pivot (start of the median line).
+ * P2 and P3 define the swing high/low.
+ * The median line extends from P1 through the midpoint of P2–P3.
+ * Upper parallel runs through P2; lower parallel runs through P3.
+ */
+export interface PitchforkAnnotation extends AnnotationBase {
+    type: 'pitchfork';
+    /** Pivot point (start of median line) */
+    time1: number;
+    price1: number;
+    /** Second anchor (e.g., swing high) */
+    time2: number;
+    price2: number;
+    /** Third anchor (e.g., swing low) */
+    time3: number;
+    price3: number;
+    color: string;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    label?: string;
+    /** Opacity of the fill between upper and lower parallels (0–1) */
+    fillOpacity: number;
+    /** Extend lines to chart edges */
+    extendRight: boolean;
+}
+/**
+ * Fibonacci Extension — three-point tool for projecting price targets.
+ * P1 is the start of the initial move (e.g., swing low).
+ * P2 is the end of the initial move (e.g., swing high).
+ * P3 is the end of the retracement (e.g., pullback low).
+ * Extension levels are projected from P3 using the P1→P2 move distance.
+ */
+export interface FibExtensionAnnotation extends AnnotationBase {
+    type: 'fib_extension';
+    /** Start of initial move */
+    time1: number;
+    price1: number;
+    /** End of initial move */
+    time2: number;
+    price2: number;
+    /** End of retracement */
+    time3: number;
+    price3: number;
+    color: string;
+    lineStyle: LineStyle;
+    lineWidth: number;
+    label?: string;
+    /** Extension levels to display (e.g., [0, 0.618, 1, 1.272, 1.618, 2, 2.618]) */
+    levels: number[];
+    /** Opacity of the fill between levels (0–1) */
+    fillOpacity: number;
+    /** Show price labels on each level */
+    showPrices: boolean;
+}
+/**
+ * SMC Order Block — a zone where institutional activity occurred.
+ * Rendered as a shaded price zone between low and high of the block candle.
+ */
+export interface OrderBlockAnnotation extends AnnotationBase {
+    type: 'order_block';
+    /** Time of the order block candle */
+    time: number;
+    /** High price of the order block candle */
+    high: number;
+    /** Low price of the order block candle */
+    low: number;
+    /** Direction: bullish (green) or bearish (red) */
+    direction: 'bullish' | 'bearish';
+    /** Current state of the order block */
+    state: 'active' | 'tested' | 'mitigated';
+    /** Color (auto-computed from direction if not provided) */
+    color?: string;
+    /** Fill opacity (0-1) */
+    fillOpacity: number;
+    /** Border line style */
+    lineStyle: LineStyle;
+    /** Border line width */
+    lineWidth: number;
+    /** Optional label (e.g., "OB", "Buy OB") */
+    label?: string;
+}
+/**
+ * SMC Fair Value Gap — the unfilled gap between three consecutive candles.
+ * The gap is between the low of the middle candle and high of the adjacent candle.
+ */
+export interface FairValueGapAnnotation extends AnnotationBase {
+    type: 'fair_value_gap';
+    /** Time of the first candle (left side of gap) */
+    time1: number;
+    /** Time of the third candle (right side of gap) */
+    time2: number;
+    /** Top of the FVG zone (high of candle1 vs candle3, whichever is higher) */
+    top: number;
+    /** Bottom of the FVG zone (low of candle1 vs candle3, whichever is lower) */
+    bottom: number;
+    /** Direction: bullish (green) or bearish (red) */
+    direction: 'bullish' | 'bearish';
+    /** Whether the FVG has been filled (mitigated) */
+    filled: boolean;
+    /** Color (auto-computed from direction if not provided) */
+    color?: string;
+    /** Fill opacity (0-1) */
+    fillOpacity: number;
+    /** Border line style */
+    lineStyle: LineStyle;
+    /** Border line width */
+    lineWidth: number;
+    /** Optional label (e.g., "FVG") */
+    label?: string;
+}
+/**
+ * SMC BOS (Break of Structure) or ChoCH (Change of Character) level line.
+ * A horizontal line at the level where price broke a structure.
+ */
+export interface BosLineAnnotation extends AnnotationBase {
+    type: 'bos_line';
+    /** Time at which the break occurred */
+    time: number;
+    /** Price level of the break */
+    price: number;
+    /** Type: BOS or ChoCH */
+    bosType: 'BOS' | 'ChoCH';
+    /** Direction: bullish (green) or bearish (red) */
+    direction: 'bullish' | 'bearish';
+    /** Whether this is a confirmed break (vs pending) */
+    confirmed: boolean;
+    /** Color (auto-computed from direction if not provided) */
+    color?: string;
+    /** Line style */
+    lineStyle: LineStyle;
+    /** Line width */
+    lineWidth: number;
+    /** Show price label */
+    showPrice: boolean;
+    /** Show type label (BOS/ChoCH) */
+    showLabel: boolean;
+}
+export type Annotation = HLineAnnotation | VLineAnnotation | TextAnnotation | TrendLineAnnotation | RayAnnotation | CrossLineAnnotation | RectangleAnnotation | EmojiAnnotation | TimeRangeAnnotation | ArrowAnnotation | ChannelAnnotation | FibRetracementAnnotation | MeasureAnnotation | AlertLineAnnotation | BrushAnnotation | PitchforkAnnotation | FibExtensionAnnotation | OrderBlockAnnotation | FairValueGapAnnotation | BosLineAnnotation;

package/dist/charting.css

@@ -1 +1 @@
-.dwlf-chart-container{font-family:Inter,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;color:#1a202c}.dwlf-chart-svg{display:block}.dwlf-pane-tooltip{position:absolute;padding:6px 10px;background:#111827d9;color:#f7fafc;border-radius:6px;border:1px solid rgba(148,163,184,.2);font-size:11px;pointer-events:none;max-width:220px;-webkit-backdrop-filter:blur(4px);backdrop-filter:blur(4px)}.dwlf-pane-tooltip__title{font-weight:600;margin-bottom:2px}.dwlf-pane-tooltip__content{display:flex;flex-direction:column;gap:2px}.dwlf-pane-tooltip__row{display:flex;justify-content:space-between;gap:8px;white-space:nowrap}.dwlf-candles path{shape-rendering:crispEdges}.dwlf-y-axis text{text-anchor:end}.dwlf-x-axis text{pointer-events:none;font-variant-numeric:tabular-nums}.dwlf-chart-container.fade-transition{transition:opacity .5s ease-out,background-color .3s ease-out}.dwlf-chart-container.fade-transition.loading,.dwlf-chart-container.fade-transition.background{opacity:1}.dwlf-chart-container.fade-transition .dwlf-chart-svg g{transition:opacity .3s ease-out}.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-candles{transition:opacity .2s ease-out}.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-line,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-area{transition:opacity .4s ease-out}@media(prefers-reduced-motion:reduce){.dwlf-chart-container,.dwlf-chart-container.fade-transition,.dwlf-chart-container.fade-transition .dwlf-chart-svg g,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-candles,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-line,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-area{transition:none!important;@keyframes marker-drop{0%{opacity:0;transform:translateY(-20px)}60%{opacity:.8;transform:translateY(2px)}80%{opacity:1;transform:translateY(-1px)}to{opacity:1;transform:translateY(0)}}// charting styles}.dwlf-chart-container .marker-overlay-animated .dwlf-marker-drop,.dwlf-chart-container.fade-transition .marker-overlay-animated .dwlf-marker-drop,.dwlf-chart-container.fade-transition .dwlf-chart-svg g .marker-overlay-animated .dwlf-marker-drop,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-candles .marker-overlay-animated .dwlf-marker-drop,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-line .marker-overlay-animated .dwlf-marker-drop,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-area .marker-overlay-animated .dwlf-marker-drop{animation:marker-drop .6s ease-out forwards;opacity:0;transform:translateY(-20px)}.dwlf-chart-container .marker-overlay-animated .dwlf-marker-drop,.dwlf-chart-container.fade-transition .marker-overlay-animated .dwlf-marker-drop,.dwlf-chart-container.fade-transition .dwlf-chart-svg g .marker-overlay-animated .dwlf-marker-drop,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-candles .marker-overlay-animated .dwlf-marker-drop,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-line .marker-overlay-animated .dwlf-marker-drop,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-area .marker-overlay-animated .dwlf-marker-drop{animation:none!important;opacity:1!important;transform:none!important}.dwlf-chart-container .annotation-layer,.dwlf-chart-container.fade-transition .annotation-layer,.dwlf-chart-container.fade-transition .dwlf-chart-svg g .annotation-layer,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-candles .annotation-layer,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-line .annotation-layer,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-area .annotation-layer{transition:opacity .4s ease-in-out}.dwlf-chart-container .annotation-layer,.dwlf-chart-container.fade-transition .annotation-layer,.dwlf-chart-container.fade-transition .dwlf-chart-svg g .annotation-layer,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-candles .annotation-layer,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-line .annotation-layer,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-area .annotation-layer{transition:none!important}}
+.dwlf-chart-container{font-family:Inter,system-ui,-apple-system,BlinkMacSystemFont,Segoe UI,sans-serif;color:#1a202c}.dwlf-chart-svg{display:block}.dwlf-pane-tooltip{position:absolute;padding:6px 10px;background:#111827d9;color:#f7fafc;border-radius:6px;border:1px solid rgba(148,163,184,.2);font-size:11px;pointer-events:none;max-width:220px;-webkit-backdrop-filter:blur(4px);backdrop-filter:blur(4px)}.dwlf-pane-tooltip__title{font-weight:600;margin-bottom:2px}.dwlf-pane-tooltip__content{display:flex;flex-direction:column;gap:2px}.dwlf-pane-tooltip__row{display:flex;justify-content:space-between;gap:8px;white-space:nowrap}.dwlf-candles path{shape-rendering:crispEdges}.dwlf-y-axis text{text-anchor:end}.dwlf-x-axis text{pointer-events:none;font-variant-numeric:tabular-nums}.dwlf-chart-container.fade-transition{transition:opacity .5s ease-out,background-color .3s ease-out}.dwlf-chart-container.fade-transition.loading,.dwlf-chart-container.fade-transition.background{opacity:1}.dwlf-chart-container.fade-transition .dwlf-chart-svg g{transition:opacity .3s ease-out}.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-candles{transition:opacity .2s ease-out}.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-line,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-area{transition:opacity .4s ease-out}@media(prefers-reduced-motion:reduce){.dwlf-chart-container,.dwlf-chart-container.fade-transition,.dwlf-chart-container.fade-transition .dwlf-chart-svg g,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-candles,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-line,.dwlf-chart-container.fade-transition .dwlf-chart-svg .dwlf-series-area{transition:none!important}}.marker-overlay-animated .dwlf-marker-drop{animation:marker-drop .6s ease-out forwards;opacity:0;transform:translateY(-20px)}@keyframes marker-drop{0%{opacity:0;transform:translateY(-20px)}60%{opacity:.8;transform:translateY(2px)}80%{opacity:1;transform:translateY(-1px)}to{opacity:1;transform:translateY(0)}}@media(prefers-reduced-motion:reduce){.marker-overlay-animated .dwlf-marker-drop{animation:none!important;opacity:1!important;transform:none!important}}.annotation-layer{transition:opacity .4s ease-in-out}@media(prefers-reduced-motion:reduce){.annotation-layer{transition:none!important}}

package/dist/components/DWLFChart.d.ts

@@ -0,0 +1,119 @@
+import { default as React } from 'react';
+import { Annotation, ChartSpec, PaneGuide, PaneSpec, SeriesSpec } from '../charting/types';
+import { ChartAnimationState } from '../hooks/useChartAnimations';
+type HoverSeries = {
+    key: string;
+    color?: string;
+    value: number | null;
+    display: string;
+    raw: any;
+};
+declare const computeSeriesHover: (series: SeriesSpec, time: number) => HoverSeries;
+export interface AxisColorConfig {
+    light?: string;
+    dark?: string;
+}
+export interface DWLFChartProps {
+    spec?: ChartSpec;
+    darkMode?: boolean;
+    showGrid?: boolean;
+    className?: string;
+    style?: React.CSSProperties;
+    enablePanZoom?: boolean;
+    timeframe?: string;
+    initialVisibleCount?: number;
+    extraRightSlots?: number;
+    compressGaps?: boolean;
+    axisColors?: AxisColorConfig;
+    crosshairSnapMode?: 'series' | 'pointer';
+    /**
+     * When true, draw a small price label on the right-hand axis that tracks
+     * the crosshair position for each pane.
+     *
+     * This mirrors the old Chart.js behaviour used in the portfolio frontend
+     * and is wired to the global "Crosshair Price Label" user preference.
+     */
+    showCrosshairPriceLabel?: boolean;
+    /**
+     * Chart annotations (horizontal lines, text labels) for the price pane.
+     * Rendered as an overlay layer above series but below crosshair.
+     */
+    annotations?: Annotation[];
+    /**
+     * Currently selected annotation ID (shows selection handles).
+     */
+    selectedAnnotationId?: string | null;
+    /**
+     * Callback when an annotation is clicked/selected.
+     */
+    onAnnotationSelect?: (id: string | null) => void;
+    /**
+     * Callback when an annotation is moved (drag).
+     */
+    onAnnotationMove?: (id: string, update: Partial<Annotation>) => void;
+    /**
+     * Callback when text annotation requests edit (double-click).
+     */
+    onAnnotationTextEdit?: (id: string) => void;
+    /**
+     * Callback when an annotation is double-clicked.
+     */
+    onAnnotationDoubleClick?: (id: string) => void;
+    /**
+     * Callback when user clicks on chart canvas (for placing annotations).
+     * Receives { time, price, paneId, screenX, screenY }.
+     */
+    onChartCanvasClick?: (info: {
+        time: number;
+        price: number;
+        paneId: string;
+        screenX: number;
+        screenY: number;
+    }) => void;
+    /**
+     * Callback when user moves mouse over chart canvas (for annotation previews).
+     * Only fires when the prop is provided to avoid unnecessary overhead.
+     * Receives { time, price, paneId, screenX, screenY }.
+     */
+    onCanvasMouseMove?: (info: {
+        time: number;
+        price: number;
+        paneId: string;
+        screenX: number;
+        screenY: number;
+    }) => void;
+    /**
+     * Alias for onCanvasMouseMove - callback when user hovers over chart canvas.
+     * Receives { time, price } coordinates for annotation preview generation.
+     */
+    onChartCanvasHover?: (info: {
+        time: number;
+        price: number;
+    }) => void;
+    /**
+     * Optional animation state for controlling chart reveal animations.
+     * When provided, the chart will render based on the current animation phase.
+     */
+    animationState?: ChartAnimationState;
+}
+export interface DwlfChartHandle {
+    setSpec(spec: ChartSpec): void;
+    addPane(pane: PaneSpec): void;
+    removePane(paneId: string): void;
+    updatePane(paneId: string, patch: Partial<PaneSpec>): void;
+    addSeries(paneId: string, series: SeriesSpec): void;
+    updateSeries(paneId: string, key: string, data: any[]): void;
+    removeSeries(paneId: string, key: string): void;
+    addGuide(paneId: string, guide: PaneGuide): void;
+    removeGuide(paneId: string, y: number): void;
+    enableSharedCrosshair(enabled: boolean): void;
+    zoomIn(): void;
+    zoomOut(): void;
+    resetView(): void;
+    panToStart(): void;
+    panToEnd(): void;
+}
+declare const DWLFChart: React.ForwardRefExoticComponent<DWLFChartProps & React.RefAttributes<DwlfChartHandle>>;
+export { computeSeriesHover as __computeSeriesHoverForTests };
+export type { DwlfChartHandle, DWLFChartProps };
+export default DWLFChart;

package/dist/components/index.d.ts

@@ -0,0 +1,2 @@
+export { default as DWLFChart, __computeSeriesHoverForTests } from './DWLFChart';
+export type { DwlfChartHandle, DWLFChartProps } from './DWLFChart';

package/dist/components/overlays/AlertLineAnnotationView.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+import { AlertLineAnnotation, PaneComputedScale } from '../../charting/types';
+export interface AlertLineAnnotationViewProps {
+    annotation: AlertLineAnnotation;
+    yScale: PaneComputedScale;
+    chartWidth: number;
+    paneHeight: number;
+    darkMode?: boolean;
+    selected?: boolean;
+    onSelect?: (id: string | null) => void;
+    onMove?: (id: string, newPrice: number) => void;
+}
+declare const AlertLineAnnotationView: React.FC<AlertLineAnnotationViewProps>;
+export default AlertLineAnnotationView;

package/dist/components/overlays/AnnotationLayer.d.ts

@@ -0,0 +1,55 @@
+import { default as React } from 'react';
+import { Annotation, HLineAnnotation, VLineAnnotation, TextAnnotation, TrendLineAnnotation, RayAnnotation, CrossLineAnnotation, RectangleAnnotation, EmojiAnnotation, TimeRangeAnnotation, ArrowAnnotation, ChannelAnnotation, FibRetracementAnnotation, MeasureAnnotation, AlertLineAnnotation, BrushAnnotation, PitchforkAnnotation, FibExtensionAnnotation, OrderBlockAnnotation, FairValueGapAnnotation, BosLineAnnotation, PaneComputedScale, XScale } from '../../charting/types';
+export interface AnnotationLayerProps {
+    annotations: Annotation[];
+    xScale: XScale;
+    yScale: PaneComputedScale;
+    chartWidth: number;
+    paneHeight: number;
+    darkMode?: boolean;
+    selectedAnnotationId?: string | null;
+    onAnnotationSelect?: (id: string | null) => void;
+    onAnnotationDoubleClick?: (id: string) => void;
+    onAnnotationMove?: (id: string, update: Partial<Annotation>) => void;
+    onAnnotationTextEdit?: (id: string) => void;
+    /** Convert raw timestamp to index when compressGaps is enabled */
+    timeToIndex?: (time: number) => number | undefined;
+    /** Convert index back to raw timestamp when compressGaps is enabled */
+    indexToTime?: (index: number) => number;
+    /** Number of data points (required for closest index search when compressGaps enabled) */
+    dataLength?: number;
+    /** Pre-computed compressed times array (avoids redundant reconstruction from indexToTime) */
+    compressedTimes?: number[];
+    /** Optional time formatter for vertical line labels */
+    timeFormatter?: (t: number) => string;
+    /** Current chart timeframe — used to filter annotations by visibleTimeframes */
+    currentTimeframe?: string;
+    /** Animation phase for controlling fade-in transitions */
+    animationPhase?: string;
+}
+declare const AnnotationLayer: React.FC<AnnotationLayerProps>;
+export default AnnotationLayer;
+export declare const createHLineAnnotation: (symbol: string, timeframe: string, price: number, options?: Partial<Omit<HLineAnnotation, "id" | "type" | "symbol" | "timeframe" | "price" | "createdAt" | "updatedAt">>) => HLineAnnotation;
+export declare const createVLineAnnotation: (symbol: string, timeframe: string, time: number, options?: Partial<Omit<VLineAnnotation, "id" | "type" | "symbol" | "timeframe" | "time" | "createdAt" | "updatedAt">>) => VLineAnnotation;
+export declare const createTextAnnotation: (symbol: string, timeframe: string, time: number, price: number, text: string, options?: Partial<Omit<TextAnnotation, "id" | "type" | "symbol" | "timeframe" | "time" | "price" | "text" | "createdAt" | "updatedAt">>) => TextAnnotation;
+export declare const createTrendLineAnnotation: (symbol: string, timeframe: string, time1: number, price1: number, time2: number, price2: number, options?: Partial<Omit<TrendLineAnnotation, "id" | "type" | "symbol" | "timeframe" | "time1" | "price1" | "time2" | "price2" | "createdAt" | "updatedAt">>) => TrendLineAnnotation;
+export declare const createRayAnnotation: (symbol: string, timeframe: string, time1: number, price1: number, time2: number, price2: number, options?: Partial<Omit<RayAnnotation, "id" | "type" | "symbol" | "timeframe" | "time1" | "price1" | "time2" | "price2" | "createdAt" | "updatedAt">>) => RayAnnotation;
+export declare const createCrossLineAnnotation: (symbol: string, timeframe: string, time: number, price: number, options?: Partial<Omit<CrossLineAnnotation, "id" | "type" | "symbol" | "timeframe" | "time" | "price" | "createdAt" | "updatedAt">>) => CrossLineAnnotation;
+export declare const createRectangleAnnotation: (symbol: string, timeframe: string, time1: number, price1: number, time2: number, price2: number, options?: Partial<Omit<RectangleAnnotation, "id" | "type" | "symbol" | "timeframe" | "time1" | "price1" | "time2" | "price2" | "createdAt" | "updatedAt">>) => RectangleAnnotation;
+export declare const createEmojiAnnotation: (symbol: string, timeframe: string, time: number, price: number, emoji: string, options?: Partial<Omit<EmojiAnnotation, "id" | "type" | "symbol" | "timeframe" | "time" | "price" | "emoji" | "createdAt" | "updatedAt">>) => EmojiAnnotation;
+export declare const createTimeRangeAnnotation: (symbol: string, timeframe: string, time1: number, time2: number, options?: Partial<Omit<TimeRangeAnnotation, "id" | "type" | "symbol" | "timeframe" | "time1" | "time2" | "createdAt" | "updatedAt">>) => TimeRangeAnnotation;
+export declare const createArrowAnnotation: (symbol: string, timeframe: string, time1: number, price1: number, time2: number, price2: number, text: string, options?: Partial<Omit<ArrowAnnotation, "id" | "type" | "symbol" | "timeframe" | "time1" | "price1" | "time2" | "price2" | "text" | "createdAt" | "updatedAt">>) => ArrowAnnotation;
+export declare const createChannelAnnotation: (symbol: string, timeframe: string, time1: number, price1: number, time2: number, price2: number, priceOffset: number, options?: Partial<Omit<ChannelAnnotation, "id" | "type" | "symbol" | "timeframe" | "time1" | "price1" | "time2" | "price2" | "priceOffset" | "createdAt" | "updatedAt">>) => ChannelAnnotation;
+export declare const createFibRetracementAnnotation: (symbol: string, timeframe: string, time1: number, price1: number, time2: number, price2: number, options?: Partial<Omit<FibRetracementAnnotation, "id" | "type" | "symbol" | "timeframe" | "time1" | "price1" | "time2" | "price2" | "createdAt" | "updatedAt">>) => FibRetracementAnnotation;
+export declare const createMeasureAnnotation: (symbol: string, timeframe: string, time1: number, price1: number, time2: number, price2: number, options?: Partial<Omit<MeasureAnnotation, "id" | "type" | "symbol" | "timeframe" | "time1" | "price1" | "time2" | "price2" | "createdAt" | "updatedAt">>) => MeasureAnnotation;
+export declare const createAlertLineAnnotation: (symbol: string, timeframe: string, price: number, options?: Partial<Omit<AlertLineAnnotation, "id" | "type" | "symbol" | "timeframe" | "price" | "createdAt" | "updatedAt">>) => AlertLineAnnotation;
+export declare const createBrushAnnotation: (symbol: string, timeframe: string, points: {
+    t: number;
+    v: number;
+}[], options?: Partial<Omit<BrushAnnotation, "id" | "type" | "symbol" | "timeframe" | "points" | "createdAt" | "updatedAt">>) => BrushAnnotation;
+export declare const createPitchforkAnnotation: (symbol: string, timeframe: string, time1: number, price1: number, time2: number, price2: number, time3: number, price3: number, options?: Partial<Omit<PitchforkAnnotation, "id" | "type" | "symbol" | "timeframe" | "time1" | "price1" | "time2" | "price2" | "time3" | "price3" | "createdAt" | "updatedAt">>) => PitchforkAnnotation;
+export declare const createFibExtensionAnnotation: (symbol: string, timeframe: string, time1: number, price1: number, time2: number, price2: number, time3: number, price3: number, options?: Partial<Omit<FibExtensionAnnotation, "id" | "type" | "symbol" | "timeframe" | "time1" | "price1" | "time2" | "price2" | "time3" | "price3" | "createdAt" | "updatedAt">>) => FibExtensionAnnotation;
+export declare const createOrderBlockAnnotation: (symbol: string, timeframe: string, time: number, high: number, low: number, direction: "bullish" | "bearish", options?: Partial<Omit<OrderBlockAnnotation, "id" | "type" | "symbol" | "timeframe" | "time" | "high" | "low" | "direction" | "createdAt" | "updatedAt">>) => OrderBlockAnnotation;
+export declare const createFairValueGapAnnotation: (symbol: string, timeframe: string, time1: number, time2: number, top: number, bottom: number, direction: "bullish" | "bearish", options?: Partial<Omit<FairValueGapAnnotation, "id" | "type" | "symbol" | "timeframe" | "time1" | "time2" | "top" | "bottom" | "direction" | "createdAt" | "updatedAt">>) => FairValueGapAnnotation;
+export declare const createBosLineAnnotation: (symbol: string, timeframe: string, time: number, price: number, bosType: "BOS" | "ChoCH", direction: "bullish" | "bearish", options?: Partial<Omit<BosLineAnnotation, "id" | "type" | "symbol" | "timeframe" | "time" | "price" | "bosType" | "direction" | "createdAt" | "updatedAt">>) => BosLineAnnotation;
+export declare const ANNOTATION_COLORS: readonly ["#ef4444", "#f97316", "#eab308", "#22c55e", "#06b6d4", "#3b82f6", "#8b5cf6", "#ec4899", "#64748b", "#ffffff"];