@vuu-ui/vuu-chart 4.0.0-beta.7 → 4.0.0

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.0.0-beta.7",
+  "version": "4.0.0",
   "description": "support for apache echarts using vuu data",
   "main": "./src/index.js",
   "license": "Apache-2.0",
@@ -9,16 +9,16 @@
     "type-defs": "node ../../scripts/build-type-defs.mjs"
   },
   "devDependencies": {
-    "@vuu-ui/vuu-data-types": "4.0.0-beta.7",
-    "@vuu-ui/vuu-protocol-types": "4.0.0-beta.7",
-    "@vuu-ui/vuu-data-local": "4.0.0-beta.7"
+    "@vuu-ui/vuu-data-types": "4.0.0",
+    "@vuu-ui/vuu-protocol-types": "4.0.0",
+    "@vuu-ui/vuu-data-local": "4.0.0"
   },
   "dependencies": {
-    "@salt-ds/styles": "0.4.1",
+    "@salt-ds/styles": "0.4.2",
     "@salt-ds/window": "0.1.2",
-    "@vuu-ui/vuu-context-menu": "4.0.0-beta.7",
-    "@vuu-ui/vuu-ui-controls": "4.0.0-beta.7",
-    "@vuu-ui/vuu-utils": "4.0.0-beta.7",
+    "@vuu-ui/vuu-context-menu": "4.0.0",
+    "@vuu-ui/vuu-ui-controls": "4.0.0",
+    "@vuu-ui/vuu-utils": "4.0.0",
     "clsx": "^2.0.0",
     "echarts": "6.1.0"
   },

package/src/Chart.js

@@ -61,12 +61,14 @@ const Chart_Chart = ({ categoryColumnName, chartSettings = {
     useEffect(()=>{
         if (!chartElement) return;
         const chart = init(chartElement, null, chartSettings);
+        chartElement.echartsInstance = chart;
         chart.on("contextmenu", onContextMenu);
         chart.on("click", onClick);
         chart.on("mouseover", onMouseOver);
         chart.on("mouseout", onMouseOut);
         return ()=>{
             chart?.dispose();
+            delete chartElement.echartsInstance;
         };
     }, [
         chartElement,

package/src/ChartSeries.js

@@ -120,7 +120,8 @@ class ChartSeries extends EventEmitter {
                             name: seriesColumn,
                             symbol,
                             symbolSize: 20,
-                            type: "scatter"
+                            type: "scatter",
+                            z: 3
                         };
                     }
                     if (scatterSeries) seriesMap.set(seriesColumn, [

package/types/chart-data/ChartDataStore.d.ts

@@ -0,0 +1,53 @@
+import type { DataSource, DataSourceRow, DataSourceSubscribeCallback } from "@vuu-ui/vuu-data-types";
+import type { VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
+import { type ColumnMap, EventEmitter } from "@vuu-ui/vuu-utils";
+export declare const DEFAULT_MAX_ROWS = 1000;
+export type ChartDataStoreEvents = {
+    update: () => void;
+};
+export interface ChartDataStoreOptions {
+    /**
+     * The number of rows requested from the DataSource (the viewport range
+     * will be 0 - maxRows). Default 1000.
+     */
+    maxRows?: number;
+}
+/**
+ * Subscribes to a single DataSource and keeps a dense, index-ordered copy of
+ * the rows within the subscribed range. Emits 'update' whenever rows or size
+ * change. Consumers (chart projections) read `rows` and `columnMap`.
+ *
+ * A DataSource supports a single subscriber, so each DataSource used by a
+ * chart should not be shared with another component (e.g. a Table).
+ */
+export declare class ChartDataStore extends EventEmitter<ChartDataStoreEvents> {
+    #private;
+    constructor(dataSource: DataSource, { maxRows }?: ChartDataStoreOptions);
+    get columnMap(): ColumnMap;
+    get dataSource(): DataSource;
+    get isSubscribed(): boolean;
+    /**
+     * The rows currently held, in DataSource (index) order, with no gaps.
+     */
+    get rows(): DataSourceRow[];
+    get size(): number;
+    /**
+     * Incremented on every change, can be used to cheaply detect changes.
+     */
+    get version(): number;
+    getValue(row: DataSourceRow, columnName: string): VuuRowDataItemType | undefined;
+    subscribe(): void;
+    dispose(): void;
+    private changed;
+    handleData: DataSourceSubscribeCallback;
+}
+/**
+ * Manages one ChartDataStore per distinct DataSource instance.
+ */
+export declare class ChartDataStores {
+    #private;
+    constructor(dataSources: DataSource[], options: ChartDataStoreOptions, onUpdate: () => void);
+    get(dataSource: DataSource): ChartDataStore;
+    subscribe(): void;
+    dispose(): void;
+}

package/types/chart-data/projection-utils.d.ts

@@ -0,0 +1,28 @@
+import type { DataSourceRow } from "@vuu-ui/vuu-data-types";
+import type { VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
+import type { ColumnMap } from "@vuu-ui/vuu-utils";
+import type { ChartTheme } from "../theme/chartTheme";
+import type { Aggregation, ColorBy, MarkLineDef, RowMatch } from "../vuu-chart-types";
+export declare const toNumber: (value: VuuRowDataItemType | bigint | undefined) => number | null;
+export declare const getColumnValue: (row: DataSourceRow, columnMap: ColumnMap, columnName: string) => VuuRowDataItemType | undefined;
+export declare const getNumber: (row: DataSourceRow, columnMap: ColumnMap, columnName: string) => number | null;
+export declare const filterRows: (rows: DataSourceRow[], columnMap: ColumnMap, where?: RowMatch) => DataSourceRow[];
+/**
+ * Returns rows sorted (stable) by a numeric column, ascending. If rows
+ * are already in order (the common case, when the DataSource is sorted),
+ * the original array is returned.
+ */
+export declare const sortRowsByNumber: (rows: DataSourceRow[], columnMap: ColumnMap, columnName: string, descending?: boolean) => DataSourceRow[];
+export declare const colorForRow: (row: DataSourceRow, columnMap: ColumnMap, colorBy: ColorBy, theme: ChartTheme) => string | undefined;
+export declare class Aggregator {
+    #private;
+    count: number;
+    constructor(aggregation: Aggregation);
+    add(value: number | null): void;
+    get value(): number | null;
+}
+export declare const computeMarkLineValue: (def: MarkLineDef, values: Array<number | null>, weights?: Array<number | null>) => number | null;
+/**
+ * Binary search, returns the index of the last value <= target, or -1.
+ */
+export declare const findFloorIndex: (sortedValues: number[], target: number) => number;

package/types/chart-types.d.ts

@@ -37,6 +37,7 @@ export interface LineSeries extends SeriesBase {
 }
 export interface ScatterSeries extends SeriesBase {
     type: "scatter";
+    z?: number;
 }
 export type Series = LineSeries | ScatterSeries;
 export type ChartSelectionModel = "none" | "single" | "single-no-deselect" | "extended";

package/types/charts/CandlestickChart.d.ts

@@ -0,0 +1,9 @@
+import type { VuuChartBaseProps } from "../vuu-chart-types";
+import { type CandlestickChartOptions } from "./candlestick-model";
+export interface CandlestickChartProps extends Omit<VuuChartBaseProps, "legend">, CandlestickChartOptions {
+}
+/**
+ * OHLC candlestick chart with optional volume pane and overlay series
+ * (e.g. a vwap line, or fills as scatter markers from a second DataSource).
+ */
+export declare const CandlestickChart: ({ crosshair, dataSource, dataZoom, formatTime, legend, markLines, ohlcColumnNames, overlays, showTooltip, timeColumnName, volumeColumnName, volumePaneHeight, xAxisType, ...props }: CandlestickChartProps) => import("react/jsx-runtime").JSX.Element;

package/types/charts/CartesianChart.d.ts

@@ -0,0 +1,10 @@
+import type { VuuChartBaseProps } from "../vuu-chart-types";
+import { type CartesianChartOptions } from "./cartesian-model";
+export interface CartesianChartProps extends Omit<VuuChartBaseProps, "legend">, CartesianChartOptions {
+}
+/**
+ * Line, area (including stepped), bar (vertical, horizontal, stacked) and
+ * scatter series, on a category, time or value x axis. Series may be read
+ * from multiple DataSources.
+ */
+export declare const CartesianChart: ({ aggregation, crosshair, dataSource, dataZoom, legend, orientation, series, showTooltip, xAxis, yAxes, ...props }: CartesianChartProps) => import("react/jsx-runtime").JSX.Element;

package/types/charts/DepthChart.d.ts

@@ -0,0 +1,8 @@
+import type { VuuChartBaseProps } from "../vuu-chart-types";
+import { type DepthChartOptions } from "./depth-model";
+export interface DepthChartProps extends Omit<VuuChartBaseProps, "legend">, DepthChartOptions {
+}
+/**
+ * Market depth chart: stepped cumulative bid and ask areas, by price.
+ */
+export declare const DepthChart: ({ askValue, bidValue, cumulativeSizeColumnName, dataSource, legend, priceColumnName, showMidPrice, showTooltip, sideColumnName, sizeColumnName, ...props }: DepthChartProps) => import("react/jsx-runtime").JSX.Element;

package/types/charts/HeatmapChart.d.ts

@@ -0,0 +1,9 @@
+import type { VuuChartBaseProps } from "../vuu-chart-types";
+import { type HeatmapChartOptions } from "./heatmap-model";
+export interface HeatmapChartProps extends Omit<VuuChartBaseProps, "legend">, HeatmapChartOptions {
+}
+/**
+ * Heatmap of a value column by two dimensions, e.g. traded quantity by
+ * price level and time bucket.
+ */
+export declare const HeatmapChart: ({ aggregation, colorScale, dataSource, dataZoom, formatTime, max, min, showTooltip, showVisualMap, valueColumnName, where, xAxis, yAxis, ...props }: HeatmapChartProps) => import("react/jsx-runtime").JSX.Element;

package/types/charts/HierarchyChart.d.ts

@@ -0,0 +1,15 @@
+import type { VuuChartBaseProps } from "../vuu-chart-types";
+import { type HierarchyChartOptions } from "./hierarchy-model";
+export interface HierarchyChartProps extends Omit<VuuChartBaseProps, "legend">, HierarchyChartOptions {
+}
+/**
+ * Treemap, sunburst or pie breakdown of a value column, grouped by one or
+ * more columns e.g. exposure by sector -> ric.
+ */
+export declare const HierarchyChart: ({ aggregation, colorMode, dataSource, donut, formatValue, groupByColumnNames, legend, showTooltip, type, valueColumnName, where, ...props }: HierarchyChartProps) => import("react/jsx-runtime").JSX.Element;
+export type TreemapChartProps = Omit<HierarchyChartProps, "type" | "donut">;
+export declare const TreemapChart: (props: TreemapChartProps) => import("react/jsx-runtime").JSX.Element;
+export type SunburstChartProps = Omit<HierarchyChartProps, "type" | "donut">;
+export declare const SunburstChart: (props: SunburstChartProps) => import("react/jsx-runtime").JSX.Element;
+export type PieChartProps = Omit<HierarchyChartProps, "type">;
+export declare const PieChart: (props: PieChartProps) => import("react/jsx-runtime").JSX.Element;

package/types/charts/candlestick-model.d.ts

@@ -0,0 +1,62 @@
+import type { DataSource } from "@vuu-ui/vuu-data-types";
+import type { ChartModel } from "../engine/ChartModel";
+import type { ColorBy, DataZoomOption, LegendPosition, MarkLineDef, RowMatch } from "../vuu-chart-types";
+export interface OhlcColumnNames {
+    open: string;
+    high: string;
+    low: string;
+    close: string;
+}
+export interface CandlestickOverlayDef {
+    type: "line" | "scatter";
+    /** Column providing the (price) value */
+    columnName: string;
+    /** Default is columnName */
+    id?: string;
+    name?: string;
+    /**
+     * Read the overlay from a different DataSource (e.g. fills). Points are
+     * placed at the bar whose interval contains their timestamp.
+     */
+    dataSource?: DataSource;
+    /** Timestamp column of the overlay DataSource, default is timeColumnName */
+    timeColumnName?: string;
+    where?: RowMatch;
+    /** css colour or 'up' | 'down' | 'palette-n' */
+    color?: string;
+    colorBy?: ColorBy;
+    /** echarts symbol e.g 'circle', 'triangle', 'diamond', 'pin' */
+    symbol?: string;
+    symbolSize?: number;
+    markLines?: MarkLineDef[];
+}
+export interface CandlestickChartOptions {
+    /** Default 'both' */
+    dataZoom?: DataZoomOption;
+    /** Show axis crosshair with tooltip. Default true */
+    crosshair?: boolean;
+    /** DataSource providing OHLC bars, e.g the vuu 'bars' table */
+    dataSource: DataSource;
+    /** Formats time values (epoch millis) for axis labels */
+    formatTime?: (timestamp: number) => string;
+    legend?: LegendPosition;
+    /** Mark lines on the price axis, 'last' is the last close */
+    markLines?: MarkLineDef[];
+    /** Defaults to open, high, low, close */
+    ohlcColumnNames?: Partial<OhlcColumnNames>;
+    /** Additional series overlaid on the price chart */
+    overlays?: CandlestickOverlayDef[];
+    showTooltip?: boolean;
+    /** Bar start timestamp column (epoch millis). Default 'start' */
+    timeColumnName?: string;
+    /** If provided, volume bars are rendered in a pane below the price chart */
+    volumeColumnName?: string;
+    /** Height of the volume pane, as a percentage of chart height. Default 20 */
+    volumePaneHeight?: number;
+    /**
+     * 'category' (default) spaces bars evenly, with no gaps for periods
+     * without bars. 'time' uses a continuous time axis.
+     */
+    xAxisType?: "category" | "time";
+}
+export declare const createCandlestickModel: ({ crosshair, dataSource, dataZoom, formatTime, legend, markLines, ohlcColumnNames, overlays, showTooltip, timeColumnName, volumeColumnName, volumePaneHeight, xAxisType, }: CandlestickChartOptions) => ChartModel;

package/types/charts/cartesian-model.d.ts

@@ -0,0 +1,78 @@
+import type { DataSource } from "@vuu-ui/vuu-data-types";
+import type { ChartModel } from "../engine/ChartModel";
+import type { Aggregation, ColorBy, DataZoomOption, LegendPosition, MarkLineDef, RowMatch, XAxisType } from "../vuu-chart-types";
+export type CartesianSeriesType = "line" | "area" | "bar" | "scatter";
+export interface CartesianSeriesDef {
+    type: CartesianSeriesType;
+    /** Column providing the (y) value */
+    columnName: string;
+    /** Default is columnName. Used to identify series in echartsOptions overrides. */
+    id?: string;
+    /** Display name (legend/tooltip), default is columnName */
+    name?: string;
+    /**
+     * Read this series from a different DataSource than the chart default
+     * (e.g. to overlay fills on a price line).
+     */
+    dataSource?: DataSource;
+    /** x column, if different from the chart xAxis.columnName */
+    xColumnName?: string;
+    /** Restrict the rows used for this series e.g { side: "BUY" } */
+    where?: RowMatch;
+    /** index into yAxes, default 0 */
+    yAxisIndex?: number;
+    /** series with same stack name are stacked (bar, line, area) */
+    stack?: string;
+    /** stepped line/area */
+    step?: "start" | "middle" | "end";
+    smooth?: boolean;
+    /** default true for scatter, false for line/area */
+    showSymbol?: boolean;
+    symbolSize?: number;
+    /** css colour or 'up' | 'down' | 'palette-n' */
+    color?: string;
+    /** per point colour, by value of a column */
+    colorBy?: ColorBy;
+    /** area fill opacity (area series), default 0.25 */
+    areaOpacity?: number;
+    markLines?: MarkLineDef[];
+}
+export interface CartesianXAxisDef {
+    columnName: string;
+    /**
+     * 'time' expects epoch millisecond timestamps (vuu epochtimestamp),
+     * 'category' (default) uses distinct values in DataSource order,
+     * 'value' a numeric axis.
+     */
+    type?: XAxisType;
+    name?: string;
+}
+export interface CartesianYAxisDef {
+    name?: string;
+    position?: "left" | "right";
+    /** Do not force axis to include zero. Default true unless chart has bars */
+    scale?: boolean;
+    type?: "value" | "log";
+    min?: number;
+    max?: number;
+}
+export interface CartesianChartOptions {
+    /**
+     * Category axis only. Aggregate the values of rows that share the same
+     * category (e.g. sum notional by sector).
+     */
+    aggregation?: Aggregation;
+    /** Show axis crosshair with tooltip. Default true */
+    crosshair?: boolean;
+    dataSource: DataSource;
+    dataZoom?: DataZoomOption;
+    legend?: LegendPosition;
+    /** 'horizontal' places the category/x axis vertically (horizontal bars) */
+    orientation?: "vertical" | "horizontal";
+    series: CartesianSeriesDef[];
+    showTooltip?: boolean;
+    xAxis: CartesianXAxisDef;
+    yAxes?: CartesianYAxisDef[];
+}
+export declare const seriesIds: (series: CartesianSeriesDef[]) => string[];
+export declare const createCartesianModel: ({ aggregation, crosshair, dataSource, dataZoom, legend, orientation, series, showTooltip, xAxis, yAxes, }: CartesianChartOptions) => ChartModel;

package/types/charts/depth-model.d.ts

@@ -0,0 +1,43 @@
+import type { DataSource, DataSourceRow } from "@vuu-ui/vuu-data-types";
+import type { ChartModel } from "../engine/ChartModel";
+import type { LegendPosition } from "../vuu-chart-types";
+export interface DepthChartOptions {
+    /** Value of sideColumnName for bids. Default 'BUY' */
+    bidValue?: string;
+    /** Value of sideColumnName for asks. Default 'SELL' */
+    askValue?: string;
+    /**
+     * Optional column with the cumulative size at each level (e.g. 'cumSize').
+     * If not provided, cumulative size is computed from sizeColumnName.
+     */
+    cumulativeSizeColumnName?: string;
+    /** DataSource of price levels, e.g the vuu 'depth' table */
+    dataSource: DataSource;
+    legend?: LegendPosition;
+    /** Default 'price' */
+    priceColumnName?: string;
+    /** Show a mark line at the mid price. Default true */
+    showMidPrice?: boolean;
+    showTooltip?: boolean;
+    /** Default 'side' */
+    sideColumnName?: string;
+    /** Default 'size' */
+    sizeColumnName?: string;
+}
+type Level = {
+    price: number;
+    size: number;
+    cum?: number;
+    row: DataSourceRow;
+};
+/**
+ * Builds cumulative depth points, from best price outwards. Bids are sorted
+ * by descending price, asks by ascending price.
+ */
+export declare const cumulativeDepth: (levels: Level[], side: "bid" | "ask") => {
+    price: number;
+    cumSize: number;
+    row: DataSourceRow;
+}[];
+export declare const createDepthModel: ({ askValue, bidValue, cumulativeSizeColumnName, dataSource, legend, priceColumnName, showMidPrice, showTooltip, sideColumnName, sizeColumnName, }: DepthChartOptions) => ChartModel;
+export {};

package/types/charts/heatmap-model.d.ts

@@ -0,0 +1,43 @@
+import type { DataSource } from "@vuu-ui/vuu-data-types";
+import type { ChartModel } from "../engine/ChartModel";
+import type { Aggregation, DataZoomOption, RowMatch } from "../vuu-chart-types";
+export interface HeatmapAxisDef {
+    columnName: string;
+    /**
+     * Numeric values are rounded down to a multiple of bucketSize, e.g. 60000
+     * to bucket timestamps by minute, or 0.5 to bucket prices.
+     */
+    bucketSize?: number;
+    /**
+     * 'time' formats (epoch millis) values as times, 'value' sorts numeric
+     * values, 'category' (default for non numeric values) uses DataSource order.
+     */
+    type?: "time" | "value" | "category";
+    name?: string;
+}
+export interface HeatmapChartOptions {
+    /** How values falling in the same cell are combined. Default 'sum' */
+    aggregation?: Aggregation;
+    /**
+     * 'sequential' (default) maps low to high values onto theme.heatmapColors.
+     * 'diverging' maps negative values to the down colour and positive values
+     * to the up colour, symmetric around zero, e.g. for pnl.
+     */
+    colorScale?: "sequential" | "diverging";
+    dataSource: DataSource;
+    dataZoom?: DataZoomOption;
+    /** Formats time values (epoch millis) for axis labels */
+    formatTime?: (timestamp: number) => string;
+    /** Fixed visualMap range, by default computed from data */
+    max?: number;
+    min?: number;
+    showTooltip?: boolean;
+    /** Show the visualMap colour scale. Default true */
+    showVisualMap?: boolean;
+    /** Column providing the cell value. */
+    valueColumnName: string;
+    where?: RowMatch;
+    xAxis: HeatmapAxisDef;
+    yAxis: HeatmapAxisDef;
+}
+export declare const createHeatmapModel: ({ aggregation, colorScale, dataSource, dataZoom, formatTime, max, min, showTooltip, showVisualMap, valueColumnName, where, xAxis, yAxis, }: HeatmapChartOptions) => ChartModel;

package/types/charts/hierarchy-model.d.ts

@@ -0,0 +1,62 @@
+import type { DataSource, DataSourceRow } from "@vuu-ui/vuu-data-types";
+import { Aggregator } from "../chart-data/projection-utils";
+import { type ChartModel } from "../engine/ChartModel";
+import type { Aggregation, LegendPosition, RowMatch } from "../vuu-chart-types";
+export type HierarchyChartType = "treemap" | "sunburst" | "pie";
+/**
+ * - 'palette': each top level group is assigned a palette colour
+ * - 'sign': node size is the absolute value, colour is up (positive) or
+ *    down (negative), e.g. for pnl or long/short exposure
+ */
+export type HierarchyColorMode = "palette" | "sign";
+export interface HierarchyChartOptions {
+    /** Default 'sum' */
+    aggregation?: Aggregation;
+    /** Default 'palette' */
+    colorMode?: HierarchyColorMode;
+    dataSource: DataSource;
+    /**
+     * Columns defining the hierarchy, outermost first, e.g. ["sector", "ric"].
+     * Pie charts use only the first column.
+     */
+    groupByColumnNames: string[];
+    /** Pie chart only, renders a donut. Default false */
+    donut?: boolean;
+    /** Formats values in labels and tooltips */
+    formatValue?: (value: number) => string;
+    /** Pie only, default 'none' */
+    legend?: LegendPosition;
+    showTooltip?: boolean;
+    type: HierarchyChartType;
+    /** Column providing the value to be aggregated, e.g "notional" */
+    valueColumnName: string;
+    where?: RowMatch;
+}
+export interface HierarchyNode {
+    name: string;
+    /**
+     * size of the node, absolute value in colorMode 'sign'. For parent nodes,
+     * the sum of the children's sizes.
+     */
+    value: number;
+    /** aggregated value, which may be negative */
+    signedValue: number;
+    vuuGroupKey: string;
+    itemStyle?: {
+        color: string;
+    };
+    children?: HierarchyNode[];
+}
+interface GroupBuilder {
+    name: string;
+    key: string;
+    aggregator: Aggregator;
+    rows: DataSourceRow[];
+    children?: Map<string, GroupBuilder>;
+}
+/**
+ * Group rows by the given columns (outermost first), aggregating values.
+ */
+export declare const buildHierarchy: (rows: DataSourceRow[], getGroupValue: (row: DataSourceRow, depth: number) => unknown, getValue: (row: DataSourceRow) => number | null, depth: number, aggregation: Aggregation) => GroupBuilder[];
+export declare const createHierarchyModel: ({ aggregation, colorMode, dataSource, donut, formatValue, groupByColumnNames, legend, showTooltip, type, valueColumnName, where, }: HierarchyChartOptions) => ChartModel;
+export {};

package/types/echarts.d.ts

@@ -0,0 +1,2 @@
+export { getInstanceByDom, init } from "echarts/core";
+export type { ECElementEvent, ECharts, EChartsCoreOption, } from "echarts/core";

package/types/engine/ChartModel.d.ts

@@ -0,0 +1,55 @@
+import type { DataSource, DataSourceRow } from "@vuu-ui/vuu-data-types";
+import type { ColumnMap } from "@vuu-ui/vuu-utils";
+import type { EChartsCoreOption } from "echarts/core";
+import type { ChartTheme } from "../theme/chartTheme";
+export interface SeriesRows {
+    dataSource: DataSource;
+    /** rows, in the same order as the series data items */
+    rows: DataSourceRow[];
+    /**
+     * For aggregated items (e.g. hierarchy nodes), rows keyed by group key.
+     * Data items carry the key in a `vuuGroupKey` property.
+     */
+    groups?: Map<string, DataSourceRow[]>;
+}
+/** Separator used in group keys (ascii unit separator) */
+export declare const GROUP_KEY_SEPARATOR = "\u001F";
+export interface ChartRowData {
+    columnMap: ColumnMap;
+    /** rows in DataSource (index) order */
+    rows: DataSourceRow[];
+}
+/**
+ * Provides the current rows for each DataSource used by a chart.
+ */
+export interface ChartDataLookup {
+    get: (dataSource: DataSource) => ChartRowData;
+}
+export interface ChartDataOption {
+    /**
+     * Partial option, containing only data dependent values (series data,
+     * category axis data, markLines, visualMap ranges). Merged (by component
+     * id) into the existing chart option on each data update.
+     */
+    option: EChartsCoreOption;
+    /** Keyed by series id, used to resolve rows for item events */
+    rowLookup?: Record<string, SeriesRows>;
+}
+/**
+ * Describes a chart to the chart engine. Each chart type creates a model
+ * from its props.
+ */
+export interface ChartModel {
+    /** All DataSources that will be read by buildDataOption */
+    dataSources: DataSource[];
+    /**
+     * The structural option - series definitions (without data), axes, grids,
+     * tooltip, legend etc. Rebuilt only when props or theme change.
+     */
+    buildBaseOption: (theme: ChartTheme) => EChartsCoreOption;
+    /**
+     * Builds the data dependent part of the option from the current rows.
+     * Invoked at most once per animation frame while data is changing.
+     */
+    buildDataOption: (data: ChartDataLookup, theme: ChartTheme) => ChartDataOption;
+}

package/types/engine/VuuChartContainer.d.ts

@@ -0,0 +1,17 @@
+import type { VuuChartBaseProps } from "../vuu-chart-types";
+import { type ChartModel } from "./ChartModel";
+export interface VuuChartContainerProps extends VuuChartBaseProps {
+    chartType: string;
+    model: ChartModel;
+}
+/**
+ * The chart engine, shared by all chart types.
+ *
+ * - creates (and disposes) the ECharts instance
+ * - subscribes to (and unsubscribes from) DataSources, via ChartDataStores
+ * - applies the full option, with notMerge, only when the chart model,
+ *   theme or user overrides change
+ * - applies data updates as a partial option, merged by component id, at
+ *   most once per animation frame, without re-rendering React
+ */
+export declare const VuuChartContainer: ({ chartType, className, echartsOptions, height, legend: _legend, maxRows, model, onChartReady, onItemClick, onItemContextMenu, renderer, resizeStrategy, showTooltip: _showTooltip, style, theme: themeOverrides, width, ...htmlAttributes }: VuuChartContainerProps) => import("react/jsx-runtime").JSX.Element;

package/types/engine/useStructuralMemo.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Structural equality for plain objects and arrays. Class instances (e.g.
+ * DataSource) and functions are compared by identity.
+ */
+export declare const isStructurallyEqual: (a: unknown, b: unknown) => boolean;
+/**
+ * Returns the previous value if structurally equal to the new value. Allows
+ * consumers to pass inline object/array literals as props without causing
+ * the chart structure to be rebuilt on every render.
+ */
+export declare const useStructuralMemo: <T>(value: T) => T;

package/types/options/common.d.ts

@@ -0,0 +1,156 @@
+import type { ChartTheme } from "../theme/chartTheme";
+import type { DataZoomOption, LegendPosition, MarkLineDef } from "../vuu-chart-types";
+/**
+ * Format an epoch millisecond timestamp for an axis label. Shows seconds
+ * only when present, date only at midnight.
+ */
+export declare const formatTimeLabel: (ts: number) => string;
+export declare const formatTimestamp: (ts: number) => string;
+export declare const textStyle: (theme: ChartTheme) => {
+    color: string;
+    fontFamily: string;
+};
+export declare const GRID_OUTER_BOUNDS: {
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+};
+export declare const axisStyle: (theme: ChartTheme, showSplitLine?: boolean) => {
+    axisLine: {
+        lineStyle: {
+            color: string;
+        };
+    };
+    axisTick: {
+        lineStyle: {
+            color: string;
+        };
+    };
+    axisLabel: {
+        color: string;
+        fontFamily: string;
+        hideOverlap: boolean;
+    };
+    nameTextStyle: {
+        color: string;
+        fontFamily: string;
+    };
+    splitLine: {
+        show: boolean;
+        lineStyle: {
+            color: string;
+        };
+    };
+};
+export declare const axisPointerLabel: (theme: ChartTheme) => {
+    backgroundColor: string;
+    color: string;
+    fontFamily: string;
+};
+export declare const tooltipOption: (theme: ChartTheme, { crosshair, show, trigger, }?: {
+    crosshair?: boolean;
+    show?: boolean;
+    trigger?: "axis" | "item";
+}) => {
+    show: boolean;
+    trigger: "axis" | "item";
+    confine: boolean;
+    className: string;
+    backgroundColor: string;
+    borderColor: string;
+    textStyle: {
+        color: string;
+        fontFamily: string;
+        fontSize: number;
+    };
+    axisPointer: {
+        type: string;
+        lineStyle: {
+            color: string;
+            type: string;
+        };
+        crossStyle: {
+            color: string;
+        };
+        label: {
+            backgroundColor: string;
+            color: string;
+            fontFamily: string;
+        };
+    } | undefined;
+};
+export declare const legendOption: (theme: ChartTheme, position: LegendPosition) => {
+    show: boolean;
+    type?: undefined;
+    textStyle?: undefined;
+    pageTextStyle?: undefined;
+} | {
+    [x: string]: string | number | boolean | {
+        color: string;
+        fontFamily: string;
+    } | {
+        fontFamily?: undefined;
+        color: string;
+    };
+    show: boolean;
+    type: string;
+    textStyle: {
+        color: string;
+        fontFamily: string;
+    };
+    pageTextStyle: {
+        color: string;
+    };
+};
+export declare const hasSlider: (dataZoom: DataZoomOption | undefined) => dataZoom is "both" | "slider";
+export declare const dataZoomOption: (dataZoom: DataZoomOption | undefined, theme: ChartTheme, axisIndex?: number[], orientation?: "x" | "y") => Record<string, unknown>[];
+/**
+ * Build a series markLine option from declarative mark line definitions.
+ * Values are computed from the current series values, so this is rebuilt
+ * on each data update.
+ */
+export declare const markLineOption: (defs: MarkLineDef[] | undefined, theme: ChartTheme, values: Array<number | null>, { axis, defaultColor, weights, }?: {
+    axis?: "xAxis" | "yAxis";
+    defaultColor?: string;
+    weights?: Array<number | null>;
+}) => {
+    silent: boolean;
+    symbol: string[];
+    animation: boolean;
+    data: {
+        [x: string]: string | number | {
+            color: string;
+            type: "dashed" | "dotted" | "solid";
+            width: number;
+            backgroundColor?: undefined;
+            padding?: undefined;
+            borderRadius?: undefined;
+            position?: undefined;
+            formatter?: undefined;
+        } | {
+            type?: undefined;
+            width?: undefined;
+            color: string;
+            backgroundColor: string;
+            padding: number[];
+            borderRadius: number;
+            position: import("..").MarkLineLabelPosition;
+            formatter: string;
+        };
+        name: string;
+        lineStyle: {
+            color: string;
+            type: "dashed" | "dotted" | "solid";
+            width: number;
+        };
+        label: {
+            color: string;
+            backgroundColor: string;
+            padding: number[];
+            borderRadius: number;
+            position: import("..").MarkLineLabelPosition;
+            formatter: string;
+        };
+    }[];
+} | undefined;

package/types/options/mergeOptions.d.ts

@@ -0,0 +1,9 @@
+import type { EChartsCoreOption } from "echarts/core";
+/**
+ * Deep merge user supplied ECharts options over chart generated options.
+ * Plain objects are merged recursively. Arrays of components (e.g. series,
+ * xAxis, yAxis, grid, dataZoom) are merged item by item, matched by `id`
+ * where present, otherwise by position. Any other value (including data
+ * arrays, functions and primitives) in the override replaces the original.
+ */
+export declare const mergeEChartsOptions: (base: EChartsCoreOption, ...overrides: Array<EChartsCoreOption | undefined>) => EChartsCoreOption;

package/types/src/Chart.d.ts

@@ -0,0 +1,28 @@
+import { ChartOptionsProps } from "./useChartOptions";
+import { type MeasuredContainerProps } from "@vuu-ui/vuu-ui-controls";
+type OptionSettings = {
+    notMerge: boolean;
+};
+type ChartSettings = {
+    /**
+     * Default value will be svg
+     */
+    renderer: "svg" | "canvas";
+    /**
+     * Enlarges 'click zone' around interactive elements.
+     * Default value true;
+     */
+    useCoarsePointer: boolean;
+};
+export interface ChartProps extends ChartOptionsProps, Omit<MeasuredContainerProps, "children" | "onResize"> {
+    chartSettings?: Partial<ChartSettings>;
+    optionSettings?: OptionSettings;
+    /**
+     * An array of color values that will be assigned, in the order given
+     * to rendered series.
+     */
+    palette?: string[];
+    showTooltip?: boolean;
+}
+export declare const Chart: ({ categoryColumnName, chartSettings, className, config, dataExclusions, dataSource, height, optionSettings, palette, resizeStrategy, showTooltip, style, seriesColumnNames, width, ...htmlAttributes }: ChartProps) => import("react").JSX.Element;
+export {};

package/types/src/ChartSeries.d.ts

@@ -0,0 +1,32 @@
+import { DataSource, DataSourceRow, DataSourceSubscribeCallback } from "@vuu-ui/vuu-data-types";
+import { EventEmitter } from "@vuu-ui/vuu-utils";
+import { Series } from "./chart-types";
+import { ChartConfig, DataExclusionOptions } from "./useChartOptions";
+export type DataSourceValue = {
+    key: string;
+    readonly row: DataSourceRow;
+    value: number | null;
+};
+export type ChartEvents = {
+    update: () => void;
+};
+export interface ChartSeriesConstructorProps {
+    dataExclusions?: DataExclusionOptions;
+    dataSource: DataSource;
+    config: ChartConfig;
+    palette: string[];
+}
+export declare class ChartSeries extends EventEmitter<ChartEvents> {
+    #private;
+    handleData: DataSourceSubscribeCallback;
+    buildCategoriesAndSeries(): void;
+    constructor({ config, dataExclusions, dataSource, palette, }: ChartSeriesConstructorProps);
+    get palette(): (string | undefined)[];
+    get categoryColumn(): string;
+    set categoryColumn(categoryColumn: string);
+    get seriesColumnNames(): string[];
+    set seriesColumnNames(seriesColumnNames: string[]);
+    get categories(): string[];
+    get series(): Series[];
+    private getCategoriesAndSeries;
+}

package/types/src/DataRowMovingWindow.d.ts

@@ -0,0 +1,23 @@
+import { DataSourceRow } from "@vuu-ui/vuu-data-types";
+import { VuuRange } from "@vuu-ui/vuu-protocol-types";
+import { WindowRange } from "@vuu-ui/vuu-utils";
+export declare class MovingDataRowWindow {
+    #private;
+    data: DataSourceRow[];
+    rowCount: number;
+    constructor({ from, to }: VuuRange);
+    setRowCount: (rowCount: number) => void;
+    add(data: DataSourceRow): void;
+    getAtIndex(index: number): DataSourceRow | undefined;
+    getByKey(key: string): DataSourceRow | undefined;
+    isWithinRange(index: number): boolean;
+    setRange({ from, to }: VuuRange): void;
+    get hasData(): boolean;
+    /**
+     * This will throw if there is no data. Check `hasData` first
+     * to guard against this, if not certain.
+     */
+    get firstRow(): DataSourceRow;
+    get range(): WindowRange;
+    get hasAllRowsWithinRange(): boolean;
+}

package/types/src/chart-types.d.ts

@@ -0,0 +1,42 @@
+import { DataSourceValue } from "./ChartSeries";
+export declare const defaultItemColorFunction: ItemColorFunction;
+export type EChartsCallbackParams = {
+    color: string;
+    data: DataSourceValue;
+    dataIndex: number;
+    name: string;
+    /**
+     * This is the Vuu column name
+     */
+    seriesName: string;
+};
+export type SymbolSizeFunction = (value: number, params: EChartsCallbackParams) => number | [number, number];
+export type SymbolSize = number | [number, number] | SymbolSizeFunction;
+export type SymbolType = "emptyCircle" | "circle" | `path://${string}`;
+export type ItemColorFunction = (params: EChartsCallbackParams) => string;
+export interface SeriesBase {
+    data: DataSourceValue[];
+    id: string;
+    itemStyle?: {
+        borderColor?: string;
+        color: string | ItemColorFunction;
+        borderWidth?: number;
+    };
+    label: string;
+    name: string;
+    symbol?: SymbolType;
+    symbolSize: SymbolSize;
+}
+export interface LineSeries extends SeriesBase {
+    connectNulls?: boolean;
+    lineStyle: {
+        color?: string;
+        width: number;
+    };
+    type: "line";
+}
+export interface ScatterSeries extends SeriesBase {
+    type: "scatter";
+}
+export type Series = LineSeries | ScatterSeries;
+export type ChartSelectionModel = "none" | "single" | "single-no-deselect" | "extended";

package/types/src/chartTooltip.d.ts

@@ -0,0 +1,12 @@
+import { DataSourceValue } from "./ChartSeries";
+export interface TooltipParams {
+    axisValueLabel: string;
+    color: string;
+    componentType: string;
+    componentSubType: string;
+    data: DataSourceValue;
+    seriesName: string;
+    seriesType: 'line' | 'scatter';
+    value: number;
+}
+export declare const chartTooltip: (params: TooltipParams[]) => string | undefined;

package/types/src/index.d.ts

@@ -0,0 +1,5 @@
+export { Chart, type ChartProps } from "./Chart";
+export type { ItemColorFunction, LineSeries as Series } from './chart-types';
+export { ChartSeries, type DataSourceValue } from "./ChartSeries";
+export type { ChartContextMenuOptions, ChartMenuLocation } from "./useChartContextMenu";
+export type { ChartConfig, DataExclusionOptions } from './useChartOptions';

package/types/src/useChartContextMenu.d.ts

@@ -0,0 +1,16 @@
+import { DataSourceRow } from "@vuu-ui/vuu-data-types";
+import { ECElementEvent } from "echarts";
+import { ColumnMap } from "@vuu-ui/vuu-utils";
+export type ChartMenuLocation = "canvas" | "series";
+export type ChartContextMenuOptions = {
+    column: string;
+    columnMap: ColumnMap;
+    row: DataSourceRow;
+};
+interface ChartContextMenuHookProps {
+    allowContextMenu?: boolean;
+    categoryColumnName?: string;
+    columnMap: ColumnMap;
+}
+export declare const useChartContextMenu: ({ columnMap, }: ChartContextMenuHookProps) => ({ data, event, seriesName }: ECElementEvent) => void;
+export {};

package/types/src/useChartOptions.d.ts

@@ -0,0 +1,28 @@
+import { DataSource, DataSourceRow } from "@vuu-ui/vuu-data-types";
+import { ColumnMap } from "@vuu-ui/vuu-utils";
+import { type EChartsCoreOption } from "echarts";
+import type { ChartSelectionModel, ItemColorFunction, SymbolSize, SymbolSizeFunction, SymbolType } from "./chart-types";
+export interface ChartConfig {
+    itemColorFunction?: ItemColorFunction;
+    selectionModel?: ChartSelectionModel;
+    symbolSize?: SymbolSize;
+}
+export interface DataExclusionOptions {
+    isExcludedData: (row: DataSourceRow, columnMap: ColumnMap, column: string) => boolean;
+    /**
+     * An embedded SVG path. If provided, will be used to render excluded values.
+     */
+    symbol?: SymbolType;
+}
+export interface ChartOptionsProps {
+    categoryColumnName: string;
+    config: ChartConfig;
+    dataExclusions?: DataExclusionOptions;
+    dataSource: DataSource;
+    itemColorFunction?: ItemColorFunction;
+    palette?: string[];
+    seriesColumnNames: string[];
+    showTooltip?: boolean;
+    symbolSizeFunction?: SymbolSizeFunction;
+}
+export declare const useChartOptions: ({ categoryColumnName, config, dataExclusions, dataSource, itemColorFunction, palette, seriesColumnNames, showTooltip, symbolSizeFunction: symbolSize, }: ChartOptionsProps) => EChartsCoreOption;

package/types/src/useChartSelection.d.ts

@@ -0,0 +1,14 @@
+import { ECElementEvent } from "echarts";
+import { ChartSelectionModel, ItemColorFunction, SymbolSizeFunction } from "./chart-types";
+interface ChartSelectionHookProps {
+    selectionModel?: ChartSelectionModel;
+    categoryColumnName: string;
+}
+export declare const useChartSelection: (_props: ChartSelectionHookProps) => {
+    onClick: ({ data, event, seriesName: column }: ECElementEvent) => void;
+    onMouseOver: ({ data, seriesName }: ECElementEvent) => void;
+    onMouseOut: () => void;
+    itemColorFunction: ItemColorFunction;
+    symbolSizeFunction: SymbolSizeFunction;
+};
+export {};

package/types/theme/chartTheme.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Chart colours are resolved from CSS custom properties at runtime, so that
+ * charts follow the Salt/Vuu theme (including light/dark mode) and work with
+ * the canvas renderer (which cannot resolve css var() references itself).
+ *
+ * All tokens are declared, with Salt-based defaults, in Chart.css on the
+ * .vuuChart class and can be overridden in application css.
+ */
+export interface ChartTheme {
+    axisLineColor: string;
+    backgroundColor: string;
+    crosshairColor: string;
+    /** colour of declining candles/bars, negative values, SELL side */
+    downColor: string;
+    fontFamily: string;
+    foregroundColor: string;
+    /** low/high colours used for heatmaps */
+    heatmapColors: [string, string];
+    /** categorical palette, assigned to series in order */
+    palette: string[];
+    secondaryForegroundColor: string;
+    splitLineColor: string;
+    tooltipBackgroundColor: string;
+    tooltipBorderColor: string;
+    /** colour of rising candles/bars, positive values, BUY side */
+    upColor: string;
+}
+export declare const defaultPalette: string[];
+export declare const defaultChartTheme: ChartTheme;
+/**
+ * Read chart theme tokens from the computed style of the chart element.
+ */
+export declare const resolveChartTheme: (element: HTMLElement | null, overrides?: Partial<ChartTheme>) => ChartTheme;
+/**
+ * Colour values in declarative chart props may reference theme colours by
+ * name: 'up', 'down' or 'palette-n' (1 based).
+ */
+export declare const resolveColor: (color: string | undefined, theme: ChartTheme) => string | undefined;

package/types/vuu-chart-types.d.ts

@@ -0,0 +1,117 @@
+import type { DataSource, DataSourceRow } from "@vuu-ui/vuu-data-types";
+import type { VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
+import type { MeasuredContainerProps } from "@vuu-ui/vuu-ui-controls";
+import type { ColumnMap } from "@vuu-ui/vuu-utils";
+import type { ECharts, EChartsCoreOption } from "echarts/core";
+import type { ChartTheme } from "./theme/chartTheme";
+export type ChartRenderer = "canvas" | "svg";
+/**
+ * true is equivalent to 'inside'.
+ */
+export type DataZoomOption = boolean | "inside" | "slider" | "both";
+export type LegendPosition = "top" | "bottom" | "none";
+export type XAxisType = "time" | "category" | "value";
+export type RowPredicate = (row: DataSourceRow, columnMap: ColumnMap) => boolean;
+/**
+ * Restrict the rows used by a series. Either a map of column name to required
+ * value (all must match) or a predicate.
+ * e.g { side: "BUY" }
+ */
+export type RowMatch = Record<string, VuuRowDataItemType> | RowPredicate;
+/**
+ * Colour each data point according to the value in a column.
+ * Colours may be any css colour or one of the theme colour names
+ * 'up', 'down', 'palette-1' ... 'palette-8'.
+ * e.g { columnName: "side", colors: { BUY: "up", SELL: "down" } }
+ */
+export interface ColorBy {
+    columnName: string;
+    colors: Record<string, string>;
+    defaultColor?: string;
+}
+export type Aggregation = "sum" | "avg" | "min" | "max" | "count" | "last";
+/**
+ * - number: a fixed value
+ * - 'last': the value of the last (most recent) data point
+ * - 'min' | 'max' | 'average': computed over the series values
+ * - { weightedAverage: column }: average of series values weighted by the
+ *    named column (e.g. average fill price weighted by quantity)
+ */
+export type MarkLineValue = number | "last" | "min" | "max" | "average" | {
+    weightedAverage: string;
+};
+export interface MarkLineDef {
+    value: MarkLineValue;
+    label?: string;
+    /** css colour or theme colour name ('up', 'down', 'palette-n') */
+    color?: string;
+    lineType?: "solid" | "dashed" | "dotted";
+    /**
+     * Position of the label, relative to the line. Default 'insideEndTop'
+     * (inside the plot area, at the end of the line, so never clipped). Use
+     * 'end' to place the label beyond the end of the line, e.g over a right
+     * hand price axis.
+     */
+    labelPosition?: MarkLineLabelPosition;
+}
+export type MarkLineLabelPosition = "start" | "middle" | "end" | "insideStartTop" | "insideStartBottom" | "insideMiddleTop" | "insideMiddleBottom" | "insideEndTop" | "insideEndBottom";
+export type EChartsOptionsOverride = EChartsCoreOption | ((generated: EChartsCoreOption) => EChartsCoreOption);
+export interface ChartItemEvent {
+    columnMap: ColumnMap;
+    dataSource: DataSource;
+    /** The DataSourceRow behind the clicked item, where one can be identified */
+    row: DataSourceRow | undefined;
+    /**
+     * For aggregated items (hierarchy nodes, aggregated categories), all rows
+     * contributing to the item.
+     */
+    rows?: DataSourceRow[];
+    /** For hierarchy nodes, the group values from root to node */
+    groupPath?: string[];
+    seriesId: string;
+    seriesName: string;
+    dataIndex: number;
+    value: unknown;
+    nativeEvent?: Event;
+}
+export type ChartItemEventHandler = (event: ChartItemEvent) => void;
+export interface VuuChartBaseProps extends Omit<MeasuredContainerProps, "children" | "onResize" | "onClick"> {
+    /**
+     * Additional raw ECharts options, deep merged over the generated options.
+     * Arrays of components (series, xAxis, yAxis, grid, dataZoom etc) are
+     * merged item by item, matched by id where present, otherwise by index.
+     * Generated ids are documented in the README.
+     * If a function is provided, it receives the generated option and returns
+     * the option to be used. Note: overrides are applied when the chart
+     * structure is (re)built, not on each data update.
+     */
+    echartsOptions?: EChartsOptionsOverride;
+    /**
+     * Maximum number of rows to be read from each DataSource. Default 1000.
+     */
+    maxRows?: number;
+    /**
+     * Invoked once the ECharts instance has been created.
+     */
+    onChartReady?: (chart: ECharts) => void;
+    onItemClick?: ChartItemEventHandler;
+    onItemContextMenu?: ChartItemEventHandler;
+    /**
+     * Default is 'canvas', which performs better with streaming data.
+     */
+    renderer?: ChartRenderer;
+    /**
+     * Show a legend. Default depends on chart type, generally shown when there
+     * are multiple series.
+     */
+    legend?: LegendPosition;
+    /**
+     * Default true
+     */
+    showTooltip?: boolean;
+    /**
+     * Override any of the theme colours (by default resolved from css tokens).
+     */
+    theme?: Partial<ChartTheme>;
+}
+export type { ChartTheme };