@classic-homes/charts-core 0.1.37 → 0.3.0

package/dist/types/index.d.ts

@@ -1,3 +1,6 @@
+import { EChartsOption } from 'echarts';
+import { EChartsType } from 'echarts/core';
+
 /**
  * Data structure types for all chart components
  */
@@ -10,10 +13,17 @@ interface LineChartData {
 interface LineSeriesData {
     /** Series name (shown in legend) */
     name: string;
-    /** Data values corresponding to categories */
-    data: number[];
+    /** Data values corresponding to categories; `null` marks a missing value (a gap) */
+    data: (number | null)[];
     /** Override theme color for this series */
     color?: string;
+    /** Per-point label text, by data index (shown on those points; templates allowed) */
+    labels?: (string | null | undefined)[];
+    /**
+     * Stack group: series with the same id stack on each other. Overrides the
+     * chart's `stacked` prop for this series.
+     */
+    stack?: string;
 }
 interface BarChartData {
     /** Category labels */
@@ -24,10 +34,17 @@ interface BarChartData {
 interface BarSeriesData {
     /** Series name (shown in legend) */
     name: string;
-    /** Data values corresponding to categories */
-    data: number[];
+    /** Data values corresponding to categories; `null` marks a missing value (a gap) */
+    data: (number | null)[];
     /** Override theme color for this series */
     color?: string;
+    /** Per-point label text, by data index (shown on those points; templates allowed) */
+    labels?: (string | null | undefined)[];
+    /**
+     * Stack group: series with the same id stack on each other. Overrides the
+     * chart's `stacked` prop for this series.
+     */
+    stack?: string;
 }
 interface PieSliceData {
     /** Slice name (shown in legend/tooltip) */
@@ -36,6 +53,8 @@ interface PieSliceData {
     value: number;
     /** Override theme color for this slice */
     color?: string;
+    /** Label text shown for this slice instead of the default (templates allowed) */
+    label?: string;
 }
 interface AreaChartData {
     /** X-axis category labels */
@@ -46,10 +65,17 @@ interface AreaChartData {
 interface AreaSeriesData {
     /** Series name (shown in legend) */
     name: string;
-    /** Data values corresponding to categories */
-    data: number[];
+    /** Data values corresponding to categories; `null` marks a missing value (a gap) */
+    data: (number | null)[];
     /** Override theme color for this series */
     color?: string;
+    /** Per-point label text, by data index (shown on those points; templates allowed) */
+    labels?: (string | null | undefined)[];
+    /**
+     * Stack group: series with the same id stack on each other. Overrides the
+     * chart's `stacked` prop for this series.
+     */
+    stack?: string;
 }
 interface ScatterChartData {
     /** Data series */
@@ -62,6 +88,8 @@ interface ScatterSeriesData {
     data: [number, number][];
     /** Override theme color for this series */
     color?: string;
+    /** Per-point label text, by data index (shown on those points; templates allowed) */
+    labels?: (string | null | undefined)[];
 }
 interface RadarChartData {
     /** Data series */
@@ -90,6 +118,8 @@ interface FunnelSliceData {
     value: number;
     /** Override theme color for this slice */
     color?: string;
+    /** Label text shown for this stage instead of the default (templates allowed) */
+    label?: string;
 }
 interface HeatmapData {
     /** Data points as [xIndex, yIndex, value] */
@@ -108,6 +138,8 @@ interface TreemapNode {
     children?: TreemapNode[];
     /** Override theme color for this node */
     color?: string;
+    /** Label text shown for this node instead of the default (templates allowed) */
+    label?: string;
 }
 interface TreemapLevel {
     /** Level index (0 = root) */
@@ -153,6 +185,8 @@ interface SankeyNode {
     name: string;
     /** Override theme color for this node */
     color?: string;
+    /** Label text shown for this node instead of the default (templates allowed) */
+    label?: string;
 }
 interface SankeyLink {
     /** Source node name */
@@ -162,6 +196,147 @@ interface SankeyLink {
     /** Flow value */
     value: number;
 }
+/**
+ * The categories x series shape shared by line, bar and area charts
+ */
+interface CategoryChartData {
+    /** Category labels */
+    categories: string[];
+    /** Data series */
+    series: CategorySeriesData[];
+}
+interface CategorySeriesData {
+    /** Series name (shown in legend) */
+    name: string;
+    /** Values by category index; `null` marks a missing value */
+    data: (number | null)[];
+    /** Override theme color for this series */
+    color?: string;
+    /** Per-point label text, by data index */
+    labels?: (string | null | undefined)[];
+    /** Stack group id */
+    stack?: string;
+}
+interface ComboChartData {
+    /** Category labels */
+    categories: string[];
+    /** Data series, each drawn as bars, a line or an area */
+    series: ComboSeriesData[];
+}
+interface ComboSeriesData extends CategorySeriesData {
+    /** How the series is drawn (defaults to 'bar') */
+    type?: 'bar' | 'line' | 'area';
+    /** Value axis the series is measured on (defaults to 'primary', on the left) */
+    axis?: 'primary' | 'secondary';
+}
+interface DotPlotChartData {
+    /** Category labels, one row each */
+    categories: string[];
+    /** Data series; each draws one dot per category */
+    series: DotPlotSeriesData[];
+}
+interface DotPlotSeriesData {
+    /** Series name (shown in legend) */
+    name: string;
+    /** Values by category index; `null` leaves the row empty */
+    data: (number | null)[];
+    /**
+     * Per-point weight (e.g. a sample size) that scales the dot area, by
+     * category index
+     */
+    sizes?: (number | null)[];
+    /** Override theme color for this series */
+    color?: string;
+    /** Per-point label text, by data index */
+    labels?: (string | null | undefined)[];
+}
+interface BulletItem {
+    /** Row label */
+    name: string;
+    /** Measured value */
+    value: number;
+    /** Target value, drawn as a tick */
+    target?: number;
+    /**
+     * Qualitative range boundaries in ascending order, e.g. `[50, 75, 100]`
+     * for poor / fair / good. Shaded behind the bar.
+     */
+    ranges?: number[];
+    /** Override the bar colour */
+    color?: string;
+    /** Label text shown instead of the formatted value */
+    label?: string;
+}
+/**
+ * An explicit histogram bucket. `start` is inclusive and `end` exclusive,
+ * except for the last bucket, which includes its end.
+ */
+interface HistogramBin {
+    /** Lower bound (inclusive); omit for no lower bound */
+    start?: number;
+    /** Upper bound (exclusive); omit for no upper bound */
+    end?: number;
+    /** Axis label (defaults to "start-end") */
+    label?: string;
+}
+/**
+ * A computed histogram bucket
+ */
+interface HistogramBucket {
+    /** Axis label */
+    label: string;
+    /** Lower bound (inclusive), -Infinity when open */
+    start: number;
+    /** Upper bound, Infinity when open */
+    end: number;
+    /** Number of values in the bucket */
+    count: number;
+}
+interface BoxPlotGroup {
+    /** Category label */
+    name: string;
+    /** Raw observations; non-finite values are ignored */
+    values: number[];
+}
+/**
+ * Five-number summary of a box plot group
+ */
+interface BoxPlotStats {
+    /** Lower whisker: the smallest value within 1.5 IQR of Q1 */
+    low: number;
+    /** First quartile */
+    q1: number;
+    /** Median */
+    median: number;
+    /** Third quartile */
+    q3: number;
+    /** Upper whisker: the largest value within 1.5 IQR of Q3 */
+    high: number;
+    /** Values beyond the whiskers */
+    outliers: number[];
+    /** Number of observations */
+    count: number;
+    /** Arithmetic mean */
+    mean: number;
+}
+interface WaterfallStep {
+    /** Step label */
+    name: string;
+    /**
+     * Change contributed by this step. For a total step, the value is ignored
+     * unless `isTotal` is 'value' (the running total is shown instead).
+     */
+    value: number;
+    /**
+     * Draw this step as a total bar from zero: `true` shows the running total
+     * up to this step, 'value' shows `value` and resets the running total to it
+     */
+    isTotal?: boolean | 'value';
+    /** Override the bar colour */
+    color?: string;
+    /** Label text shown instead of the formatted value */
+    label?: string;
+}
 
 /**
  * Event parameter types for chart interactions
@@ -272,6 +447,208 @@ interface SankeyEventParams extends BaseEventParams {
     target?: string;
 }
 
+/**
+ * Types for customising chart labels, axes, tooltips and legends
+ */
+/**
+ * A formatter: either an ECharts string template (e.g. `'{b}: {c}'`) or a
+ * function returning the text to show.
+ */
+type ChartFormatter<P> = string | ((params: P) => string);
+/**
+ * Normalised parameters passed to label and tooltip formatter functions
+ */
+interface LabelFormatterParams {
+    /** Category, slice or node name */
+    name: string;
+    /** Data value ([x, y] for scatter, [x, y, value] for heatmap) */
+    value: number | number[];
+    /** Series name */
+    seriesName: string;
+    /** Series index */
+    seriesIndex: number;
+    /** Data index within the series */
+    dataIndex: number;
+    /** Share of the total, for pie, donut and funnel slices */
+    percent?: number;
+    /** Colour of the data point */
+    color?: string;
+    /** Per-point label text supplied in the chart data, if any */
+    label?: string;
+}
+/**
+ * Parameters passed to a tooltip formatter function, one entry per series
+ * under the pointer (a single entry for item tooltips)
+ */
+interface TooltipFormatterParams extends LabelFormatterParams {
+    /** HTML for the coloured dot ECharts draws before each series */
+    marker: string;
+    /** Axis value under the pointer, for axis tooltips */
+    axisValue?: string | number;
+}
+/**
+ * Axis customisation for charts with cartesian axes. Refers to the visual
+ * axis: `xAxisConfig` is always the horizontal one.
+ */
+interface AxisConfig {
+    /** Show the axis (defaults to true) */
+    show?: boolean;
+    /**
+     * Axis scale. Category charts default to 'category'; set 'time' (ISO date
+     * strings or timestamps as categories) or 'value' to plot categories on a
+     * continuous scale. Value axes can use 'log'.
+     */
+    type?: 'category' | 'time' | 'value' | 'log';
+    /** Axis title */
+    name?: string;
+    /** Where the axis title sits (defaults to 'middle') */
+    nameLocation?: 'start' | 'middle' | 'end';
+    /** Distance between the axis title and the axis line, in pixels */
+    nameGap?: number;
+    /** Tick label formatter: a template such as `'{value} kg'` or a function */
+    formatter?: string | ((value: string | number, index: number) => string);
+    /** Tick label rotation in degrees */
+    rotate?: number;
+    /** Axis minimum */
+    min?: number | 'dataMin';
+    /** Axis maximum */
+    max?: number | 'dataMax';
+    /** Fixed interval between ticks (value axes) */
+    interval?: number;
+}
+/** Where the legend is placed */
+type ChartLegendPosition = 'top' | 'right' | 'bottom' | 'left';
+/**
+ * Built-in legend customisation
+ */
+interface ChartLegendConfig {
+    /** Legend placement (defaults to 'bottom') */
+    position?: ChartLegendPosition;
+    /** Alignment along the legend's edge (defaults to 'center') */
+    align?: 'start' | 'center' | 'end';
+    /** Item flow; defaults to horizontal for top/bottom, vertical for left/right */
+    orient?: 'horizontal' | 'vertical';
+    /** Legend marker shape */
+    icon?: 'circle' | 'rect' | 'roundRect' | 'line' | 'none';
+    /** Item text: a template such as `'{name}'` or a function of the series name */
+    formatter?: ChartFormatter<string>;
+    /** Page the legend when items overflow instead of wrapping */
+    scroll?: boolean;
+}
+/**
+ * One entry of a chart legend
+ */
+interface LegendItem {
+    /** Series, slice or indicator name */
+    name: string;
+    /** Colour the chart draws the item in */
+    color: string;
+    /** Whether the item is currently shown */
+    visible: boolean;
+}
+/**
+ * State and actions handed to a custom legend renderer
+ */
+interface LegendRenderProps {
+    /** Legend entries in chart order */
+    items: LegendItem[];
+    /** Requested legend placement */
+    position: ChartLegendPosition;
+    /** Chart title, for labelling the legend */
+    chartTitle: string;
+    /** Show or hide an item */
+    toggle: (name: string) => void;
+    /** Set an item's visibility */
+    setVisible: (name: string, visible: boolean) => void;
+    /** Show only this item */
+    showOnly: (name: string) => void;
+    /** Show every item */
+    showAll: () => void;
+}
+/**
+ * Named number formats for `valueFormat`
+ *
+ * - `number`: thousand separators, up to 2 decimals
+ * - `integer`: rounded, thousand separators
+ * - `compact`: 1.2K, 3.4M
+ * - `currency`: USD, no cents (`currencyCents` keeps them)
+ * - `currencyCents`: USD with cents
+ * - `percent`: a 0-1 ratio as a percentage (0.42 -> 42%)
+ * - `percentValue`: a value already in percent (42 -> 42%)
+ * - `days`: a whole number of days (12 -> "12 days")
+ */
+type ValueFormatPreset = 'number' | 'integer' | 'compact' | 'currency' | 'currencyCents' | 'percent' | 'percentValue' | 'days';
+/**
+ * How chart values are written in axes, tooltips, data labels and data
+ * tables: a preset, `Intl.NumberFormat` options, or a function
+ */
+type ValueFormat = ValueFormatPreset | Intl.NumberFormatOptions | ((value: number) => string);
+/**
+ * A horizontal or vertical line marking a target, threshold or statistic
+ */
+interface ReferenceLine {
+    /** A fixed value, or a statistic of the series' values */
+    value: number | 'average' | 'median' | 'min' | 'max';
+    /** Text shown at the end of the line (defaults to the formatted value) */
+    label?: string;
+    /**
+     * Series the line belongs to, by name (defaults to the first). Statistics
+     * are computed from this series, and the line hides with it in the legend.
+     */
+    series?: string;
+    /** Line style (defaults to 'dashed') */
+    style?: 'dashed' | 'solid' | 'dotted';
+    /** Line colour (defaults to the muted foreground colour) */
+    color?: string;
+}
+/**
+ * A shaded range of values, e.g. a target band
+ */
+interface ReferenceBand {
+    /** Range start */
+    from: number;
+    /** Range end */
+    to: number;
+    /** Text shown inside the band */
+    label?: string;
+    /** Fill colour (defaults to a translucent muted colour) */
+    color?: string;
+    /** Series the band belongs to, by name (defaults to the first) */
+    series?: string;
+}
+/**
+ * Chart data as a table, for the accessible data table and CSV export
+ */
+interface ChartDataTable {
+    /** Column headings */
+    headers: string[];
+    /** Rows of raw cell values */
+    rows: (string | number | null)[][];
+    /**
+     * How each column's numbers are displayed: 'value' uses the chart's
+     * `valueFormat`, 'number' plain separators, 'percent' a share already in
+     * percent. Text columns ignore it. Defaults to 'value'.
+     */
+    columns?: ('value' | 'number' | 'percent' | 'text')[];
+}
+
+/**
+ * Handlers for raw ECharts events, keyed by event name (`'datazoom'`,
+ * `'legendselectchanged'`, `'brushselected'`, `'dblclick'`, ...). Handlers
+ * receive ECharts' own event parameters.
+ */
+type ChartEventHandlers = Record<string, ((params: any) => void) | undefined>;
+/**
+ * Export controls shown in the chart's top corner
+ */
+interface ChartExportConfig {
+    /** Offer a PNG download (defaults to true) */
+    image?: boolean;
+    /** Offer a CSV download of the chart data (defaults to true) */
+    csv?: boolean;
+    /** File name without extension (defaults to the chart title) */
+    filename?: string;
+}
 /**
  * Base chart props shared across all chart components
  */
@@ -280,16 +657,22 @@ interface BaseChartProps {
     title: string;
     /** Optional description for screen readers */
     description?: string;
-    /** Chart height in pixels or CSS value */
+    /**
+     * Chart height in pixels or a CSS value. Charts with one row per category
+     * (horizontal bar, bullet, dot plot) also accept 'auto', which sizes the
+     * chart to its rows (see `rowHeight`).
+     */
     height?: number | string;
-    /** Minimum height constraint */
+    /** Minimum height in pixels; also bounds an 'auto' height */
     minHeight?: number;
-    /** Maximum height constraint */
+    /** Maximum height in pixels; also bounds an 'auto' height */
     maxHeight?: number;
     /** Show loading skeleton */
     loading?: boolean;
     /** Error message to display */
     error?: string | null;
+    /** Show a Retry button on the error state, calling this */
+    onRetry?: () => void;
     /** Message shown when data is empty */
     emptyMessage?: string;
     /** Theme preference */
@@ -302,13 +685,105 @@ interface BaseChartProps {
     showTooltip?: boolean;
     /** Show grid lines (where applicable) */
     showGrid?: boolean;
+    /**
+     * Custom tooltip content: an ECharts template or a function returning HTML.
+     * The function always receives an array (one entry for item tooltips).
+     * Escape any data you interpolate (see `escapeHtml`).
+     */
+    tooltipFormatter?: ChartFormatter<TooltipFormatterParams[]>;
+    /** Format the values in the default tooltip, e.g. as currency */
+    tooltipValueFormatter?: (value: number) => string;
+    /**
+     * How values are written in value axes, tooltips, data labels and the data
+     * table: a preset such as 'currency' or 'percent', `Intl.NumberFormat`
+     * options, or a function. More specific formatters (`tooltipValueFormatter`,
+     * `labelFormatter`, an axis `formatter`) take precedence.
+     */
+    valueFormat?: ValueFormat;
+    /** Locale for `valueFormat` (defaults to 'en-US') */
+    locale?: string;
+    /**
+     * Raw ECharts option deep-merged over the generated one, for anything the
+     * props do not cover. Arrays such as `series` merge by index. Mark lines,
+     * mark areas, data zoom, datasets and graphics are always available.
+     */
+    option?: EChartsOption;
+    /**
+     * Called with the ECharts instance whenever it is created (on mount and on
+     * a theme change), for imperative access such as `getDataURL`
+     */
+    onReady?: (chart: EChartsType) => void;
+    /** Raw ECharts event handlers, keyed by event name */
+    events?: ChartEventHandlers;
+    /**
+     * Render the chart data as a table: 'sr-only' (the default) for screen
+     * readers only, `true` for a visible "Show data" toggle, `false` for none
+     */
+    showDataTable?: boolean | 'sr-only';
+    /** Show download buttons (PNG image and CSV data) */
+    exportable?: boolean | ChartExportConfig;
+    /** Fill series with patterns as well as colour, for colour-blind readers */
+    patterns?: boolean;
     /** Custom CSS class */
     class?: string;
 }
+/**
+ * Props for charts with a legend
+ */
+interface LegendChartProps {
+    /** Built-in legend placement and formatting */
+    legend?: ChartLegendConfig;
+    /** Called when legend items are shown or hidden, with every item's visibility */
+    onLegendChange?: (visible: Record<string, boolean>) => void;
+}
+/**
+ * Props for charts with data labels
+ */
+interface LabelChartProps {
+    /** Data label text: an ECharts template or a function */
+    labelFormatter?: ChartFormatter<LabelFormatterParams>;
+}
+/**
+ * Props for charts with cartesian axes
+ */
+interface AxisChartProps {
+    /** Horizontal axis customisation */
+    xAxisConfig?: AxisConfig;
+    /** Vertical axis customisation */
+    yAxisConfig?: AxisConfig;
+}
+/**
+ * Props for charts with value axes that can carry reference marks
+ */
+interface ReferenceChartProps {
+    /** Lines marking targets, thresholds or averages */
+    referenceLines?: ReferenceLine[];
+    /** Shaded value ranges */
+    referenceBands?: ReferenceBand[];
+}
+/**
+ * Props for charts with a category axis that can be zoomed
+ */
+interface ZoomChartProps {
+    /**
+     * Let users zoom and pan the category axis: 'inside' (wheel and drag),
+     * 'slider' (a range slider below the chart) or `true` for both
+     */
+    dataZoom?: boolean | 'inside' | 'slider';
+}
+/**
+ * Props for charts whose height can follow their row count
+ */
+interface RowHeightProps {
+    /** Height per category row for `height="auto"` (defaults to 28) */
+    rowHeight?: number;
+}
 /**
  * Line chart specific props
  */
-interface LineChartProps extends BaseChartProps {
+interface LineChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps {
+    /** Show data labels */
+    showLabels?: boolean;
     /** Chart data */
     data: LineChartData;
     /** Use smooth curved lines */
@@ -317,8 +792,10 @@ interface LineChartProps extends BaseChartProps {
     areaFilled?: boolean;
     /** Show data points on the line */
     showDataPoints?: boolean;
-    /** Stack multiple series */
-    stacked?: boolean;
+    /** Stack multiple series; 'percent' stacks each category's share of 100% */
+    stacked?: boolean | 'percent';
+    /** Draw the line across missing (`null`) values instead of leaving a gap */
+    connectNulls?: boolean;
     /** Click event handler */
     onClick?: (params: DataPointEventParams) => void;
     /** Hover event handler */
@@ -327,22 +804,27 @@ interface LineChartProps extends BaseChartProps {
 /**
  * Bar chart specific props
  */
-interface BarChartProps extends BaseChartProps {
+interface BarChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps, RowHeightProps {
     /** Chart data */
     data: BarChartData;
-    /** Bar orientation */
+    /**
+     * Bar orientation. Horizontal bars list categories top to bottom in data
+     * order.
+     */
     orientation?: 'vertical' | 'horizontal';
-    /** Stack multiple series */
-    stacked?: boolean;
+    /** Stack multiple series; 'percent' stacks each category's share of 100% */
+    stacked?: boolean | 'percent';
     /** Show value labels on bars */
     showValues?: boolean;
     /** Click event handler */
     onClick?: (params: DataPointEventParams) => void;
+    /** Hover event handler */
+    onHover?: (params: DataPointEventParams) => void;
 }
 /**
  * Pie chart specific props
  */
-interface PieChartProps extends BaseChartProps {
+interface PieChartProps extends BaseChartProps, LegendChartProps, LabelChartProps {
     /** Chart data */
     data: PieSliceData[];
     /** Show slice labels */
@@ -368,22 +850,30 @@ interface DonutChartProps extends Omit<PieChartProps, 'innerRadius'> {
 /**
  * Area chart specific props
  */
-interface AreaChartProps extends BaseChartProps {
+interface AreaChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps, ZoomChartProps {
+    /** Show data labels */
+    showLabels?: boolean;
     /** Chart data */
     data: AreaChartData;
     /** Use smooth curved lines */
     smooth?: boolean;
-    /** Stack multiple series */
-    stacked?: boolean;
+    /** Stack multiple series; 'percent' stacks each category's share of 100% */
+    stacked?: boolean | 'percent';
+    /** Draw the area across missing (`null`) values instead of leaving a gap */
+    connectNulls?: boolean;
     /** Use gradient fill */
     gradient?: boolean;
     /** Click event handler */
     onClick?: (params: DataPointEventParams) => void;
+    /** Hover event handler */
+    onHover?: (params: DataPointEventParams) => void;
 }
 /**
  * Scatter chart specific props
  */
-interface ScatterChartProps extends BaseChartProps {
+interface ScatterChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps {
+    /** Show data labels */
+    showLabels?: boolean;
     /** Chart data */
     data: ScatterChartData;
     /** Show trend/regression line */
@@ -392,22 +882,28 @@ interface ScatterChartProps extends BaseChartProps {
     symbolSize?: number | ((value: number[]) => number);
     /** Click event handler */
     onClick?: (params: DataPointEventParams) => void;
+    /** Hover event handler */
+    onHover?: (params: DataPointEventParams) => void;
 }
 /**
  * Radar chart specific props
  */
-interface RadarChartProps extends BaseChartProps {
+interface RadarChartProps extends BaseChartProps, LegendChartProps, LabelChartProps {
+    /** Show data labels */
+    showLabels?: boolean;
     /** Chart data */
     data: RadarChartData;
     /** Radar indicators/dimensions */
     indicators: RadarIndicator[];
     /** Radar shape */
     shape?: 'polygon' | 'circle';
+    /** Click event handler */
+    onClick?: (params: DataPointEventParams) => void;
 }
 /**
  * Funnel chart specific props
  */
-interface FunnelChartProps extends BaseChartProps {
+interface FunnelChartProps extends BaseChartProps, LegendChartProps, LabelChartProps {
     /** Chart data */
     data: FunnelSliceData[];
     /** Sort order */
@@ -433,13 +929,15 @@ interface GaugeChartProps extends BaseChartProps {
     splitNumber?: number;
     /** Show progress arc */
     showProgress?: boolean;
-    /** Value format function */
+    /** Value format function (takes precedence over `valueFormat`) */
     formatValue?: (value: number) => string;
+    /** Click event handler */
+    onClick?: (params: DataPointEventParams) => void;
 }
 /**
  * Heatmap chart specific props
  */
-interface HeatmapChartProps extends BaseChartProps {
+interface HeatmapChartProps extends BaseChartProps, LabelChartProps, AxisChartProps {
     /** Chart data */
     data: HeatmapData;
     /** X-axis labels */
@@ -454,7 +952,7 @@ interface HeatmapChartProps extends BaseChartProps {
 /**
  * Treemap chart specific props
  */
-interface TreemapChartProps extends BaseChartProps {
+interface TreemapChartProps extends BaseChartProps, LabelChartProps {
     /** Hierarchical data */
     data: TreemapNode[];
     /** Level configurations */
@@ -465,18 +963,23 @@ interface TreemapChartProps extends BaseChartProps {
 /**
  * Candlestick chart specific props
  */
-interface CandlestickChartProps extends BaseChartProps {
+interface CandlestickChartProps extends BaseChartProps, AxisChartProps {
     /** Chart data */
     data: CandlestickData;
     /** Show volume bars */
     showVolume?: boolean;
+    /**
+     * Initial zoom window start, as a percentage of the dates (defaults to 80,
+     * showing the latest fifth). 0 shows everything.
+     */
+    zoomStart?: number;
     /** Click event handler */
     onClick?: (params: CandlestickEventParams) => void;
 }
 /**
  * Sankey chart specific props
  */
-interface SankeyChartProps extends BaseChartProps {
+interface SankeyChartProps extends BaseChartProps, LabelChartProps {
     /** Chart data with nodes and links */
     data: SankeyData;
     /** Flow orientation */
@@ -484,5 +987,207 @@ interface SankeyChartProps extends BaseChartProps {
     /** Click event handler */
     onClick?: (params: SankeyEventParams) => void;
 }
+/**
+ * Combo chart: bars, lines and areas over shared categories, on one or two
+ * value axes
+ */
+interface ComboChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, ReferenceChartProps, ZoomChartProps {
+    /** Chart data */
+    data: ComboChartData;
+    /** Horizontal (category) axis customisation */
+    xAxisConfig?: AxisConfig;
+    /** Left (primary) value axis customisation */
+    yAxisConfig?: AxisConfig;
+    /** Right (secondary) value axis customisation */
+    secondaryYAxisConfig?: AxisConfig;
+    /** Value format for series on the secondary axis (defaults to `valueFormat`) */
+    secondaryValueFormat?: ValueFormat;
+    /** Stack bar series that share a stack id (or all bars when true) */
+    stacked?: boolean;
+    /** Use smooth curved lines */
+    smooth?: boolean;
+    /** Show data labels */
+    showLabels?: boolean;
+    /** Draw lines across missing (`null`) values */
+    connectNulls?: boolean;
+    /** Click event handler */
+    onClick?: (params: DataPointEventParams) => void;
+    /** Hover event handler */
+    onHover?: (params: DataPointEventParams) => void;
+}
+/**
+ * Dot plot: one row per category with a dot per series, on a value axis that
+ * need not start at zero
+ */
+interface DotPlotChartProps extends BaseChartProps, LegendChartProps, LabelChartProps, ReferenceChartProps, RowHeightProps {
+    /** Chart data */
+    data: DotPlotChartData;
+    /** Value axis customisation (min/max default to the data range) */
+    valueAxisConfig?: AxisConfig;
+    /** Category axis customisation */
+    categoryAxisConfig?: AxisConfig;
+    /** Dot diameter in pixels, or the [smallest, largest] range when sizes are set */
+    dotSize?: number | [number, number];
+    /** Draw a line between the dots of a row (for comparing two series) */
+    connect?: boolean;
+    /** Show value labels beside the dots */
+    showLabels?: boolean;
+    /** Click event handler */
+    onClick?: (params: DataPointEventParams) => void;
+}
+/**
+ * Bullet chart: a measured bar per row against a target tick and shaded
+ * qualitative ranges
+ */
+interface BulletChartProps extends BaseChartProps, LabelChartProps, RowHeightProps {
+    /** One row per item */
+    data: BulletItem[];
+    /** Value axis customisation */
+    valueAxisConfig?: AxisConfig;
+    /** Show value labels at the end of each bar */
+    showLabels?: boolean;
+    /** Click event handler */
+    onClick?: (params: DataPointEventParams) => void;
+}
+/**
+ * Histogram: the distribution of raw values across buckets
+ */
+interface HistogramChartProps extends BaseChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps {
+    /**
+     * Raw observations; non-finite values are ignored. `valueFormat` writes
+     * the bucket bounds; counts are plain numbers.
+     */
+    values: number[];
+    /**
+     * Buckets: a count of equal-width buckets, or explicit buckets such as
+     * aging ranges (defaults to Sturges' rule)
+     */
+    bins?: number | HistogramBin[];
+    /** Width of equal buckets (takes precedence over a bin count) */
+    binWidth?: number;
+    /** Series name, shown in tooltips (defaults to 'Count') */
+    seriesName?: string;
+    /** Bar colour */
+    color?: string;
+    /** Show counts above the bars */
+    showLabels?: boolean;
+    /** Click event handler; `name` is the bucket label and `value` its count */
+    onClick?: (params: DataPointEventParams) => void;
+}
+/**
+ * Box plot: the spread of raw values per category (quartiles, whiskers at
+ * 1.5 IQR, outliers)
+ */
+interface BoxPlotChartProps extends BaseChartProps, AxisChartProps, ReferenceChartProps {
+    /** One box per group */
+    data: BoxPlotGroup[];
+    /** Box orientation */
+    orientation?: 'vertical' | 'horizontal';
+    /** Draw values beyond the whiskers as dots (defaults to true) */
+    showOutliers?: boolean;
+    /** Box colour */
+    color?: string;
+    /** Click event handler; `value` is [low, q1, median, q3, high] */
+    onClick?: (params: DataPointEventParams) => void;
+}
+/**
+ * Waterfall: how a starting value moves through increases and decreases to
+ * a total
+ */
+interface WaterfallChartProps extends BaseChartProps, LabelChartProps, AxisChartProps, ReferenceChartProps {
+    /** Steps in order */
+    data: WaterfallStep[];
+    /** Show each step's change above its bar (defaults to true) */
+    showLabels?: boolean;
+    /** Colour for increases (defaults to the success colour) */
+    increaseColor?: string;
+    /** Colour for decreases (defaults to the destructive colour) */
+    decreaseColor?: string;
+    /** Colour for totals (defaults to the first series colour) */
+    totalColor?: string;
+    /** Click event handler; `value` is the step's change (or total) */
+    onClick?: (params: DataPointEventParams) => void;
+}
+/**
+ * Sparkline: a small, axis-free trend line drawn as SVG
+ */
+interface SparklineProps {
+    /** Values in order; `null` leaves a gap */
+    data: (number | null)[];
+    /** How the values are drawn */
+    variant?: 'line' | 'area' | 'bar';
+    /** Width in pixels, or a CSS value (defaults to '100%') */
+    width?: number | string;
+    /** Height in pixels (defaults to 32) */
+    height?: number;
+    /** Stroke/fill colour (defaults to the first chart colour, `chart-1`) */
+    color?: string;
+    /** Mark the last value with a dot (defaults to true for line and area) */
+    showLastPoint?: boolean;
+    /** A horizontal reference line, e.g. a target or average */
+    referenceLine?: number | 'average';
+    /** Lower bound of the scale (defaults to the smallest value, or 0 for bars) */
+    min?: number;
+    /** Upper bound of the scale (defaults to the largest value) */
+    max?: number;
+    /**
+     * Accessible label; when omitted the sparkline is decorative and hidden
+     * from screen readers
+     */
+    label?: string;
+    /** Custom CSS class */
+    class?: string;
+}
+/**
+ * A change between two periods, for `StatCard`
+ */
+interface StatDelta {
+    /** The value being compared against (e.g. last year's) */
+    previous: number | null | undefined;
+    /** The current value (defaults to the card's `value` when it is a number) */
+    current?: number | null;
+    /**
+     * How the change is shown: 'percent' (+12%), 'absolute' (+12, using the
+     * card's value format) or 'both' (defaults to 'percent')
+     */
+    display?: 'percent' | 'absolute' | 'both';
+    /** Which direction is good, for colouring (defaults to 'up'); 'none' stays neutral */
+    goodWhen?: 'up' | 'down' | 'none';
+    /** Text after the change, e.g. 'vs last year' */
+    label?: string;
+}
+/**
+ * Stat card: a headline metric with its change and trend
+ */
+interface StatCardProps {
+    /** Metric name */
+    label: string;
+    /** The value; numbers are formatted with `valueFormat` */
+    value: number | string | null | undefined;
+    /** How a numeric value is written */
+    valueFormat?: ValueFormat;
+    /** Locale for `valueFormat` (defaults to 'en-US') */
+    locale?: string;
+    /** Change against a previous value */
+    delta?: StatDelta;
+    /** Secondary text under the value */
+    hint?: string;
+    /** Definition of the metric, shown in an info tooltip beside the label */
+    definition?: string;
+    /** Make the card a link */
+    href?: string;
+    /** Trend values, drawn as a sparkline */
+    trend?: (number | null)[];
+    /** Sparkline variant */
+    trendVariant?: SparklineProps['variant'];
+    /** Tone of the value itself, e.g. to flag a breached threshold */
+    tone?: 'default' | 'success' | 'warning' | 'destructive';
+    /** Text shown when the value is missing (defaults to '—') */
+    emptyValue?: string;
+    /** Show a loading placeholder */
+    loading?: boolean;
+    /** Custom CSS class */
+    class?: string;
+}
 
-export type { AreaChartData, AreaChartProps, AreaSeriesData, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, DataPointEventParams, DonutChartProps, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode };
+export type { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, AxisConfig, BarChartData, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BoxPlotStats, BulletChartProps, BulletItem, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, CategoryChartData, CategorySeriesData, ChartDataTable, ChartEventHandlers, ChartExportConfig, ChartFormatter, ChartLegendConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, HistogramBin, HistogramBucket, HistogramChartProps, LabelChartProps, LabelFormatterParams, LegendChartProps, LegendItem, LegendRenderProps, LineChartData, LineChartProps, LineSeriesData, PieChartProps, PieSliceData, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, ReferenceBand, ReferenceChartProps, ReferenceLine, RowHeightProps, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartData, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TooltipFormatterParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode, ValueFormat, ValueFormatPreset, WaterfallChartProps, WaterfallStep, ZoomChartProps };