@wick-charts/react 0.3.1 → 0.3.2

package/dist/index.d.ts

@@ -110,7 +110,9 @@ export declare type AxisBound = 'auto' | number | string | ((values: number[]) =
 
 /** Grouped axis configuration for both axes. */
 export declare interface AxisConfig {
+    /** Y-axis configuration — width, bounds, and visibility of the value axis. */
     y?: YAxisConfig;
+    /** X-axis configuration — height and visibility of the time axis. */
     x?: XAxisConfig;
 }
 
@@ -134,6 +136,7 @@ export declare interface BarSeriesOptions {
     label?: string;
     /** One color per layer. */
     colors: string[];
+    /** Width of each bar as a fraction of the available bar slot (0–1). `1` = bars touch; `0.6` = roughly 60 % of the slot. Default: 0.7. */
     barWidthRatio: number;
     /** Stacking mode. Default: 'off'. */
     stacking: StackingMode;
@@ -175,6 +178,7 @@ export declare interface BarSeriesOptions {
 declare interface BarSeriesProps {
     /** Array of datasets — one per layer. A single-layer bar chart uses `[data]`. */
     data: TimePoint[][];
+    /** Visual options override — colours per layer, bar-width ratio, stacking, entrance animation, smoothing. */
     options?: Partial<BarSeriesOptions>;
     /** Stable series ID — same value across remounts. */
     id?: string;
@@ -233,7 +237,9 @@ export declare interface BuildLastSnapshotsArgs {
  * `autoGradient(color)` for the subtle lightened/darkened look.
  */
 declare interface CandlestickDirectionColors {
+    /** Body fill — single colour for flat, `[top, bottom]` tuple for a 2-stop vertical gradient. */
     body: string | [string, string];
+    /** Wick stroke colour. */
     wick: string;
 }
 
@@ -254,7 +260,9 @@ export declare function CandlestickSeries({ data, options, id: idProp }: Candles
 export declare interface CandlestickSeriesOptions {
     /** Display label shown in the tooltip. */
     label?: string;
+    /** Colours for bullish candles (close ≥ open). */
     up: CandlestickDirectionColors;
+    /** Colours for bearish candles (close < open). */
     down: CandlestickDirectionColors;
     /** Width of candle body as a fraction of the available bar slot (0-1). */
     bodyWidthRatio: number;
@@ -294,7 +302,9 @@ export declare interface CandlestickSeriesOptions {
 }
 
 declare interface CandlestickSeriesProps {
+    /** OHLC candles to render. Each element carries `time/open/high/low/close` and an optional `volume`. */
     data: OHLCInput[];
+    /** Visual options override — colours, body width, entrance animation, smoothing. Merged onto theme defaults. */
     options?: Partial<CandlestickSeriesOptions>;
     /** Stable series ID — same value across remounts. */
     id?: string;
@@ -325,16 +335,30 @@ declare interface ChartContainerProps {
     /** Grouped axis configuration (Y/X visibility, bounds, sizing). */
     axis?: AxisConfig;
     /**
-     * Viewport padding. `top`/`bottom` are in pixels. `left`/`right` accept either pixels (`50`)
-     * or data intervals (`{ intervals: 3 }`). Set to 0 for edge-to-edge sparklines. Applied on mount only.
-     * Defaults: `{ top: 20, bottom: 20, right: { intervals: 3 }, left: { intervals: 0 } }`.
+     * Viewport padding around the plot area. Applied on mount only — changing
+     * this prop after mount is ignored. Set every side to `0` for an
+     * edge-to-edge sparkline.
+     *
+     * @default `{ top: 20, bottom: 20, right: { intervals: 3 }, left: { intervals: 0 } }`
      */
     padding?: {
+        /** Pixels of empty space above the plot area. Default `20`. */
         top?: number;
+        /** Pixels of empty space below the plot area. Default `20`. */
         bottom?: number;
+        /**
+         * Empty space on the right edge. A `number` is pixels (e.g. `50`); an
+         * object pads by data intervals on the time axis (e.g. `{ intervals: 3 }`
+         * leaves room for three more bars/candles past the latest point). Default
+         * `{ intervals: 3 }`.
+         */
         right?: number | {
             intervals: number;
         };
+        /**
+         * Empty space on the left edge. A `number` is pixels; an object pads by
+         * data intervals on the time axis. Default `{ intervals: 0 }`.
+         */
         left?: number | {
             intervals: number;
         };
@@ -345,6 +369,7 @@ declare interface ChartContainerProps {
     interactive?: boolean;
     /** Background grid configuration. Default: `{ visible: true }`. */
     grid?: {
+        /** Whether the background grid is rendered. Default: `true`. */
         visible: boolean;
     };
     /**
@@ -366,7 +391,9 @@ declare interface ChartContainerProps {
      * Only read at mount; changing this prop after the chart is created is ignored.
      */
     perf?: PerfOption;
+    /** Inline style for the chart's outer wrapper element. */
     style?: CSSProperties;
+    /** Extra class for the chart's outer wrapper element. */
     className?: string;
 }
 
@@ -449,6 +476,12 @@ export declare class ChartInstance extends EventEmitter<ChartEvents> {
     /** Auto-fit the viewport to show all data across every series. */
     fitContent(): void;
     getVisibleRange(): VisibleRange;
+    /**
+     * Return the full span of registered data, or `null` before any data has
+     * arrived. `{ from: dataStart, to: dataEnd }` mirrors the viewport's own
+     * tracking and is cheaper than recomputing from series stores.
+     */
+    getDataRange(): VisibleRange | null;
     /**
      * Imperatively set the visible time range.
      *
@@ -707,10 +740,13 @@ export declare interface ChartTheme {
     background: string;
     /** Chart area gradient [top, bottom] — subtle vignette for depth */
     chartGradient: [string, string];
+    /** Font family and base size used across the chart's text. */
     typography: Typography;
     /** Grid line appearance in the chart area. */
     grid: {
+        /** Grid line stroke colour. */
         color: string;
+        /** Grid line dash pattern. */
         style: 'solid' | 'dashed' | 'dotted';
     };
     /**
@@ -722,33 +758,48 @@ export declare interface ChartTheme {
      * want the subtle lightened/darkened look pass `autoGradient(color)`.
      */
     candlestick: {
+        /** Bullish candle (close ≥ open). */
         up: {
+            /** Body fill — single colour for flat, `[top, bottom]` tuple for a 2-stop vertical gradient. */
             body: string | [string, string];
+            /** Wick stroke colour. */
             wick: string;
         };
+        /** Bearish candle (close < open). */
         down: {
+            /** Body fill — single colour for flat, `[top, bottom]` tuple for a 2-stop vertical gradient. */
             body: string | [string, string];
+            /** Wick stroke colour. */
             wick: string;
         };
     };
     /** Default line series appearance including area gradient fill. */
     line: {
+        /** Stroke colour of the line. */
         color: string;
+        /** Stroke width in CSS pixels. */
         width: number;
+        /** Top stop of the area-fill vertical gradient (closest to the line). */
         areaTopColor: string;
+        /** Bottom stop of the area-fill vertical gradient (closest to the X axis). */
         areaBottomColor: string;
     };
     /** Color palette for multi-series charts (stacked bars, overlays). */
     seriesColors: string[];
     /** Bollinger band / envelope fill colors. */
     bands: {
+        /** Fill for the upper band region (above the middle band). */
         upper: string;
+        /** Fill for the lower band region (below the middle band). */
         lower: string;
     };
     /** Crosshair line and axis label styling. */
     crosshair: {
+        /** Stroke colour of the crosshair lines. */
         color: string;
+        /** Background fill of the X/Y axis label pills shown at the crosshair position. */
         labelBackground: string;
+        /** Text colour inside the crosshair axis label pills. */
         labelTextColor: string;
     };
     /**
@@ -758,32 +809,114 @@ export declare interface ChartTheme {
      * diverge.
      */
     axis: {
+        /** Default tick-label font size shared by both axes. */
         fontSize: number;
+        /** Default tick-label colour shared by both axes. */
         textColor: string;
+        /** Override the shared defaults on the X axis only. */
         x?: {
+            /** X-axis tick-label font size. Falls back to `axis.fontSize`. */
             fontSize?: number;
+            /** X-axis tick-label colour. Falls back to `axis.textColor`. */
             textColor?: string;
         };
+        /** Override the shared defaults on the Y axis only. */
         y?: {
+            /** Y-axis tick-label font size. Falls back to `axis.fontSize`. */
             fontSize?: number;
+            /** Y-axis tick-label colour. Falls back to `axis.textColor`. */
             textColor?: string;
         };
     };
     /** Floating label shown at the current value level on the Y axis. */
     yLabel: {
+        /** Font size of the value text inside the floating Y label. */
         fontSize: number;
+        /** Pill background when the latest delta is positive. */
         upBackground: string;
+        /** Pill background when the latest delta is negative. */
         downBackground: string;
+        /** Pill background when the latest delta is zero / unknown. */
         neutralBackground: string;
+        /** Text colour inside the floating Y label pill. */
         textColor: string;
     };
     /** Hover tooltip styling. */
     tooltip: {
+        /** Tooltip body font size. */
         fontSize: number;
+        /** Tooltip background fill. */
         background: string;
+        /** Tooltip text colour. */
         textColor: string;
+        /** Tooltip outer border colour. */
         borderColor: string;
     };
+    /**
+     * Navigator strip shown below the main chart — a miniature overview with a
+     * draggable window indicating the visible range.
+     *
+     * The `candlestick` shape mirrors the root {@link ChartTheme.candlestick}
+     * (including `[top, bottom]` gradient tuples) so candle-type mini views can
+     * share colors with the main plot.
+     */
+    navigator: {
+        /** Default height of the navigator strip in CSS pixels. */
+        height: number;
+        /** Strip background (behind the miniature series). */
+        background: string;
+        /** Color used for the strip's top + bottom inner-shadow separators. */
+        borderColor: string;
+        /** Line / close-price miniature color and geometry. */
+        line: {
+            /** Stroke colour of the miniature line. */
+            color: string;
+            /** Stroke width of the miniature line in CSS pixels. */
+            width: number;
+            /** Top stop of the miniature area-fill gradient. */
+            areaTopColor: string;
+            /** Bottom stop of the miniature area-fill gradient. */
+            areaBottomColor: string;
+        };
+        /** Colors for candlestick-type miniature rendering. */
+        candlestick: {
+            /** Bullish miniature candle (close ≥ open). */
+            up: {
+                /** Body fill — single colour for flat, `[top, bottom]` tuple for a vertical gradient. */
+                body: string | [string, string];
+                /** Wick stroke colour. */
+                wick: string;
+            };
+            /** Bearish miniature candle (close < open). */
+            down: {
+                /** Body fill — single colour for flat, `[top, bottom]` tuple for a vertical gradient. */
+                body: string | [string, string];
+                /** Wick stroke colour. */
+                wick: string;
+            };
+        };
+        /** The draggable visible-range window indicator. */
+        window: {
+            /** Fill inside the visible-range window. Usually a translucent tint. */
+            fill: string;
+            /** Stroke colour around the window. */
+            border: string;
+            /** Stroke width of the window border in CSS pixels. */
+            borderWidth: number;
+        };
+        /** Left/right resize handles on the window edges. */
+        handle: {
+            /** Stroke colour of the handle marker. */
+            color: string;
+            /** Handle marker width in CSS pixels. */
+            width: number;
+        };
+        /** Dim overlay covering the regions outside the window. */
+        mask: {
+            /** Fill of the dim overlay applied to regions outside the window. */
+            fill: string;
+        };
+    };
 }
 
 export declare function computeTooltipPosition(args: TooltipPositionArgs): TooltipPosition;
@@ -1034,6 +1167,7 @@ export declare interface LineSeriesOptions {
     strokeWidth: number;
     /** Area-fill configuration. Default: `{ visible: true }`. */
     area: {
+        /** Whether the area gradient under the line is rendered. Default: `true`. */
         visible: boolean;
     };
     /**
@@ -1088,6 +1222,7 @@ export declare interface LineSeriesOptions {
 declare interface LineSeriesProps {
     /** Array of datasets — one per layer. A single line uses `[data]`. */
     data: TimePoint[][];
+    /** Visual options override — colours per layer, stroke width, area fill, stacking, entrance animation, smoothing. */
     options?: Partial<LineSeriesOptions>;
     /** Stable series ID — same value across remounts. */
     id?: string;
@@ -1103,6 +1238,111 @@ export declare const mintBreeze: ThemePreset;
 
 export declare const monokaiPro: ThemePreset;
 
+/**
+ * Miniature navigator strip with a draggable window indicator for the main
+ * chart's visible range. Must be rendered as a child of `<ChartContainer>`
+ * so the chart instance is available via context.
+ *
+ * `ChartContainer` sifts this element out of its children and places it as a
+ * flex sibling below the canvas area — it does not render inline.
+ */
+declare function Navigator_2({ data, height, style, className }: NavigatorProps): JSX_2.Element;
+export { Navigator_2 as Navigator }
+
+/** Minimal point shape for candlestick miniature series. */
+export declare interface NavigatorCandlePoint {
+    time: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+}
+
+/**
+ * Drives the navigator strip rendered below the main chart.
+ *
+ * Layout: the container holds a canvas (series miniature) and a DOM overlay
+ * with five absolutely-positioned divs — left mask, right mask, window body,
+ * left handle, right handle. The overlay is purely visual; pointer input is
+ * captured on the canvas and hit-tested against the current window geometry.
+ *
+ * Both layers reserve `chart.yAxisWidth` on the right so the navigator's
+ * active zone aligns with the main chart's plot area (matches the TimeAxis).
+ *
+ * Event topology — navigator is a pure listener on the chart side, never emits:
+ *   chart.viewportChange → reposition window DOM + redraw on next frame
+ *   chart.overlayChange  → full redraw (catches data + theme swaps)
+ *   ResizeObserver       → resize canvas + full redraw
+ */
+export declare class NavigatorController {
+    #private;
+    constructor(params: NavigatorControllerParams);
+    setData(data: NavigatorData): void;
+    setOptions(options: NavigatorOptions): void;
+    destroy(): void;
+    /** CSS pixel height of the strip — theme default unless overridden. */
+    get height(): number;
+}
+
+export declare interface NavigatorControllerParams {
+    container: HTMLElement;
+    chart: ChartInstance;
+    data: NavigatorData;
+    options?: NavigatorOptions;
+}
+
+/**
+ * Data passed to the navigator. The discriminant `type` selects the miniature
+ * rendering style. Line and bar accept either a single `points` array
+ * (shorthand) or `series` for multi-series overlays — every series shares the
+ * same y-range and is drawn in the navigator's neutral foreground color.
+ * Candlestick stays single-series; multi-candlestick miniatures don't read.
+ */
+export declare type NavigatorData = {
+    type: 'line' | 'bar';
+    points: readonly NavigatorLinePoint[];
+} | {
+    type: 'line' | 'bar';
+    series: readonly (readonly NavigatorLinePoint[])[];
+} | {
+    type: 'candlestick';
+    points: readonly NavigatorCandlePoint[];
+};
+
+/** Minimal point shape for line and bar miniature series. */
+export declare interface NavigatorLinePoint {
+    time: number;
+    value: number;
+}
+
+export declare interface NavigatorOptions {
+    /**
+     * Strip height in CSS pixels. When omitted, falls back to
+     * `chart.getTheme().navigator.height`.
+     */
+    height?: number;
+}
+
+export declare interface NavigatorProps {
+    /**
+     * Data to render in the miniature view. Shape:
+     *   { type: 'line' | 'bar',     points: { time, value }[] }
+     *   { type: 'candlestick',      points: { time, open, high, low, close }[] }
+     *
+     * Usually the same series you feed into the main chart.
+     */
+    data: NavigatorData;
+    /** Strip height in CSS pixels. Defaults to `theme.navigator.height` (60). */
+    height?: number;
+    /** Style override for the outer wrapper div. */
+    style?: CSSProperties;
+    /** Extra class on the outer wrapper div. */
+    className?: string;
+}
+
+/** Series type the navigator should render in its miniature view. */
+export declare type NavigatorSeriesType = 'line' | 'bar' | 'candlestick';
+
 export declare const nightOwl: ThemePreset;
 
 /** Convert a {@link TimeValue} (number ms or Date) to a millisecond timestamp. */
@@ -1111,6 +1351,7 @@ export declare function normalizeTime(t: TimeValue): number;
 export declare function NumberFlow({ value, format, locale, spinDuration, className, style }: NumberFlowProps): JSX_2.Element;
 
 declare interface NumberFlowProps {
+    /** Numeric value to display. Each digit that changes between renders animates with a vertical spin. */
     value: number;
     /**
      * Value-to-string formatter. Defaults to the current locale's
@@ -1122,9 +1363,13 @@ declare interface NumberFlowProps {
      * from before this prop was a function.
      */
     format?: ((value: number) => string) | Intl.NumberFormatOptions;
+    /** BCP 47 locale tag used by the default formatter. Defaults to `'en-US'`. */
     locale?: string;
+    /** Per-digit spin animation duration in milliseconds. Defaults to `350`. */
     spinDuration?: number;
+    /** Extra class on the root `<span>`. */
     className?: string;
+    /** Inline style on the root `<span>`. Useful for `fontVariantNumeric: 'tabular-nums'`. */
     style?: CSSProperties;
 }
 
@@ -1406,7 +1651,9 @@ export declare interface PieSeriesOptions {
 }
 
 declare interface PieSeriesProps {
+    /** Slices to render. A flat array of `{ label, value, color? }` entries. */
     data: PieSliceData[];
+    /** Visual options override — palette, donut hole, slice gap, label rendering, hover/entrance animations. */
     options?: Partial<PieSeriesOptions>;
     /** Stable series ID — same value across remounts. */
     id?: string;
@@ -1531,7 +1778,9 @@ export declare const solarizedLight: ThemePreset;
 export declare function Sparkline({ data, theme, variant, valuePosition, formatValue, label, sublabel, color, negativeColor, area, areaFill, width, height, strokeWidth, gradient, style, }: SparklineProps): JSX_2.Element;
 
 export declare interface SparklineProps {
+    /** Data points plotted by the sparkline. A flat `TimePoint[]` — the sparkline only ever shows one tiny line/bar. */
     data: TimePoint[];
+    /** Visual theme. Drives series colour, background gradient, and the change-direction colours used in the value block. */
     theme: ChartTheme;
     /** 'line' (default) or 'bar' */
     variant?: SparklineVariant;
@@ -1549,6 +1798,7 @@ export declare interface SparklineProps {
     negativeColor?: string;
     /** Show area fill under line */
     area?: {
+        /** Whether the area fill is rendered under the sparkline. Defaults to `true`. */
         visible: boolean;
     };
     /** @deprecated Use {@link area} instead. */
@@ -1594,6 +1844,19 @@ export declare interface ThemeConfig {
     axis?: Partial<ChartTheme['axis']>;
     yLabel?: Partial<ChartTheme['yLabel']>;
     tooltip?: Partial<ChartTheme['tooltip']>;
+    navigator?: {
+        height?: number;
+        background?: string;
+        borderColor?: string;
+        line?: Partial<ChartTheme['navigator']['line']>;
+        candlestick?: {
+            up?: Partial<ChartTheme['navigator']['candlestick']['up']>;
+            down?: Partial<ChartTheme['navigator']['candlestick']['down']>;
+        };
+        window?: Partial<ChartTheme['navigator']['window']>;
+        handle?: Partial<ChartTheme['navigator']['handle']>;
+        mask?: Partial<ChartTheme['navigator']['mask']>;
+    };
     /** URL to load the font (e.g. Google Fonts). */
     fontUrl?: string | null;
 }
@@ -1808,6 +2071,7 @@ export declare type TooltipSort = 'none' | 'asc' | 'desc';
 
 /** Font family and base font size used across the chart. */
 export declare interface Typography {
+    /** CSS `font-family` stack applied to all text rendered by the chart. */
     fontFamily: string;
     /** Base body font size — titles, infobar, pie tooltip/legend default to this. */
     fontSize: number;