@wick-charts/react 0.3.1 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wick-charts/react",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "High-performance canvas timeseries charts for React — candlestick, line, bar, pie. Tree-shakeable, zero runtime deps.",
   "license": "MIT",
   "repository": {
@@ -49,7 +49,7 @@
     "react-dom": ">=18.0.0"
   },
   "devDependencies": {
-    "@wick-charts/core": "^0.3.1"
+    "@wick-charts/core": "^0.3.2"
   },
   "scripts": {
     "build": "vite build"

package/src/BarSeries.tsx

@@ -7,6 +7,7 @@ import { useChartInstance } from './context';
 export 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;

package/src/CandlestickSeries.tsx

@@ -12,7 +12,9 @@ import { useChartInstance } from './context';
 const BULK_THRESHOLD = 20;
 
 export 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;

package/src/ChartContainer.tsx

@@ -19,6 +19,7 @@ import { ChartContext } from './context';
 import { ThemeProvider, useThemeOptional } from './ThemeContext';
 import { InfoBar } from './ui/InfoBar';
 import { Legend, type LegendProps } from './ui/Legend';
+import { Navigator } from './ui/Navigator';
 import { PieLegend, type PieLegendProps } from './ui/PieLegend';
 import { Title } from './ui/Title';
 
@@ -31,14 +32,28 @@ export 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 };
   };
   /** Show the chart background gradient. Defaults to true. */
@@ -46,7 +61,10 @@ export interface ChartContainerProps {
   /** Enable zoom, pan, and crosshair interactions. Defaults to true. */
   interactive?: boolean;
   /** Background grid configuration. Default: `{ visible: true }`. */
-  grid?: { visible: boolean };
+  grid?: {
+    /** Whether the background grid is rendered. Default: `true`. */
+    visible: boolean;
+  };
   /**
    * How `<Title>` and `<InfoBar>` are positioned relative to the canvas.
    * - `'overlay'` (default): absolute overlays on top of the canvas — the grid
@@ -66,7 +84,9 @@ export 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;
 }
 
@@ -88,12 +108,14 @@ export function siftContainerChildren(children: ReactNode): {
   legendEl: ReactElement<LegendProps> | null;
   pieLegendEl: ReactElement<PieLegendProps> | null;
   tooltipLegendEl: ReactElement | null;
+  navigatorEl: ReactElement | null;
   overlay: ReactNode[];
 } {
   let titleEl: ReactElement | null = null;
   let legendEl: ReactElement<LegendProps> | null = null;
   let pieLegendEl: ReactElement<PieLegendProps> | null = null;
   let tooltipLegendEl: ReactElement | null = null;
+  let navigatorEl: ReactElement | null = null;
   const overlay: ReactNode[] = [];
 
   const visit = (child: ReactNode): void => {
@@ -127,12 +149,16 @@ export function siftContainerChildren(children: ReactNode): {
         tooltipLegendEl = child;
         return;
       }
+      if (child.type === Navigator) {
+        navigatorEl = child;
+        return;
+      }
     }
     overlay.push(child);
   };
 
   Children.forEach(children, visit);
-  return { titleEl, legendEl, pieLegendEl, tooltipLegendEl, overlay };
+  return { titleEl, legendEl, pieLegendEl, tooltipLegendEl, navigatorEl, overlay };
 }
 
 /**
@@ -254,7 +280,7 @@ export function ChartContainer({
 
   const chart = chartRef.current;
 
-  const { titleEl, legendEl, pieLegendEl, tooltipLegendEl, overlay } = siftContainerChildren(children);
+  const { titleEl, legendEl, pieLegendEl, tooltipLegendEl, navigatorEl, overlay } = siftContainerChildren(children);
   const legendPosition = legendEl?.props.position ?? 'bottom';
   const pieLegendPosition = pieLegendEl?.props.position ?? 'bottom';
   // Either legend type can pull the layout into row-mode. `Legend` and
@@ -390,6 +416,12 @@ export function ChartContainer({
     </ChartContext.Provider>
   );
 
+  const hoistedNavigator = chart && navigatorEl && (
+    <ChartContext.Provider value={chart}>
+      <ThemeProvider value={resolvedTheme ?? chart.getTheme()}>{navigatorEl}</ThemeProvider>
+    </ChartContext.Provider>
+  );
+
   return (
     <div
       className={className}
@@ -422,6 +454,7 @@ export function ChartContainer({
         {hoistedLegend}
         {hoistedPieLegend}
       </div>
+      {hoistedNavigator}
     </div>
   );
 }

package/src/LineSeries.tsx

@@ -7,6 +7,7 @@ import { useChartInstance } from './context';
 export 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;

package/src/PieSeries.tsx

@@ -5,7 +5,9 @@ import type { PieSeriesOptions, PieSliceData } from '@wick-charts/core';
 import { useChartInstance } from './context';
 
 export 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;

package/src/index.ts

@@ -26,6 +26,12 @@ export type {
   /** @deprecated Use {@link TimePoint} instead. */
   LineData,
   LineSeriesOptions,
+  NavigatorCandlePoint,
+  NavigatorControllerParams,
+  NavigatorData,
+  NavigatorLinePoint,
+  NavigatorOptions,
+  NavigatorSeriesType,
   OHLCData,
   OHLCInput,
   PieSeriesOptions,
@@ -53,6 +59,7 @@ export type {
 } from '@wick-charts/core';
 export {
   ChartInstance,
+  NavigatorController,
   andromeda,
   autoGradient,
   ayuMirage,
@@ -115,6 +122,8 @@ export { InfoBar } from './ui/InfoBar';
 export type { LegendItemOverride, LegendProps } from './ui/Legend';
 // Legend
 export { Legend } from './ui/Legend';
+export type { NavigatorProps } from './ui/Navigator';
+export { Navigator } from './ui/Navigator';
 export { NumberFlow } from './ui/NumberFlow';
 export type { PieLegendMode, PieLegendPosition, PieLegendProps, PieLegendRenderContext } from './ui/PieLegend';
 export { PieLegend } from './ui/PieLegend';

package/src/ui/Navigator.tsx

@@ -0,0 +1,84 @@
+import { type CSSProperties, useEffect, useLayoutEffect, useRef } from 'react';
+
+import { NavigatorController, type NavigatorData } from '@wick-charts/core';
+
+import { useChartInstance } from '../context';
+import { useTheme } from '../ThemeContext';
+
+export 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;
+}
+
+/**
+ * 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.
+ */
+export function Navigator({ data, height, style, className }: NavigatorProps) {
+  const chart = useChartInstance();
+  // Subscribe to theme via context so a `<ThemeProvider>` swap re-renders the
+  // strip with the new default height. Reading from `chart.getTheme()` would
+  // miss those updates because the chart instance reference is stable.
+  const theme = useTheme();
+  const containerRef = useRef<HTMLDivElement>(null);
+  const controllerRef = useRef<NavigatorController | null>(null);
+
+  useLayoutEffect(() => {
+    if (!containerRef.current) return;
+    const controller = new NavigatorController({
+      container: containerRef.current,
+      chart,
+      data,
+      options: height !== undefined ? { height } : undefined,
+    });
+    controllerRef.current = controller;
+
+    return () => {
+      controller.destroy();
+      controllerRef.current = null;
+    };
+    // Mount-only. Data/height changes are synced by the two effects below.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [chart]);
+
+  useEffect(() => {
+    controllerRef.current?.setData(data);
+  }, [data]);
+
+  useEffect(() => {
+    controllerRef.current?.setOptions(height !== undefined ? { height } : {});
+  }, [height]);
+
+  const resolvedHeight = height ?? theme.navigator.height;
+
+  return (
+    <div
+      ref={containerRef}
+      className={className}
+      data-chart-navigator=""
+      style={{
+        position: 'relative',
+        width: '100%',
+        height: resolvedHeight,
+        flexShrink: 0,
+        ...style,
+      }}
+    />
+  );
+}

package/src/ui/NumberFlow.tsx

@@ -1,6 +1,7 @@
 import { type CSSProperties, useEffect, useMemo, useRef } from 'react';
 
 export 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
@@ -12,9 +13,13 @@ export 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;
 }
 

package/src/ui/Sparkline.tsx

@@ -10,7 +10,9 @@ export type SparklineVariant = 'line' | 'bar';
 export type SparklineValuePosition = 'left' | 'right' | 'none';
 
 export 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;
@@ -27,7 +29,10 @@ export interface SparklineProps {
   /** Secondary color for negative bars */
   negativeColor?: string;
   /** Show area fill under line */
-  area?: { visible: boolean };
+  area?: {
+    /** Whether the area fill is rendered under the sparkline. Defaults to `true`. */
+    visible: boolean;
+  };
   /** @deprecated Use {@link area} instead. */
   areaFill?: boolean;
   /** Chart width (default: 140) */