@classic-homes/charts-core 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -1,15 +1,27 @@
 export { ChartSemanticColors, EChartsTheme, THEME_DARK, THEME_LIGHT, colorWithAlpha, darkChartColors, darkTheme, generateDarkTheme, generateLightTheme, getChartColors, lightChartColors, lightTheme } from './theme/index.cjs';
-import { BarChartData, LineChartData, PieSliceData, ScatterChartData, ChartFormatter, LabelFormatterParams, TooltipFormatterParams, AxisConfig, ChartLegendConfig, LegendItem } from './types/index.cjs';
-export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, CandlestickChartProps, CandlestickData, CandlestickEventParams, CandlestickItem, ChartLegendPosition, DataPointEventParams, DonutChartProps, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapData, HeatmapEventParams, LabelChartProps, LegendChartProps, LegendRenderProps, LineChartProps, LineSeriesData, PieChartProps, RadarChartData, RadarChartProps, RadarIndicator, RadarSeriesData, SankeyChartProps, SankeyData, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartProps, ScatterSeriesData, SliceEventParams, TreemapChartProps, TreemapEventParams, TreemapLevel, TreemapNode } from './types/index.cjs';
+import { ValueFormat, CategoryChartData, BarChartData, BoxPlotStats, BulletItem, HistogramBucket, LineChartData, PieSliceData, ScatterChartData, WaterfallStep, ChartFormatter, LabelFormatterParams, TooltipFormatterParams, AxisConfig, ChartLegendConfig, ReferenceBand, ReferenceLine, LegendItem, HistogramBin, CategorySeriesData, ChartDataTable, CandlestickData, HeatmapData, RadarChartData, RadarIndicator, SankeyData, TreemapNode } from './types/index.cjs';
+export { AreaChartData, AreaChartProps, AreaSeriesData, AxisChartProps, BarChartProps, BarSeriesData, BaseChartProps, BaseEventParams, BoxPlotChartProps, BoxPlotGroup, BulletChartProps, CandlestickChartProps, CandlestickEventParams, CandlestickItem, ChartEventHandlers, ChartExportConfig, ChartLegendPosition, ComboChartData, ComboChartProps, ComboSeriesData, DataPointEventParams, DonutChartProps, DotPlotChartData, DotPlotChartProps, DotPlotSeriesData, FunnelChartProps, FunnelSliceData, GaugeChartProps, HeatmapChartProps, HeatmapEventParams, HistogramChartProps, LabelChartProps, LegendChartProps, LegendRenderProps, LineChartProps, LineSeriesData, PieChartProps, RadarChartProps, RadarSeriesData, ReferenceChartProps, RowHeightProps, SankeyChartProps, SankeyEventParams, SankeyLink, SankeyNode, ScatterChartProps, ScatterSeriesData, SliceEventParams, SparklineProps, StatCardProps, StatDelta, TreemapChartProps, TreemapEventParams, TreemapLevel, ValueFormatPreset, WaterfallChartProps, ZoomChartProps } from './types/index.cjs';
 import 'echarts';
+import 'echarts/core';
 
 /**
  * Formatting utilities for chart values
  */
+
 /**
  * Format a number with thousand separators
  */
-declare function formatNumber(value: number, options?: Intl.NumberFormatOptions): string;
+declare function formatNumber(value: number, options?: Intl.NumberFormatOptions, locale?: string): string;
+/**
+ * Turn a `valueFormat` prop into a formatter function. Returns undefined when
+ * no format is set, so callers can fall back to ECharts' defaults.
+ */
+declare function resolveValueFormatter(format: ValueFormat | undefined, locale?: string): ((value: number) => string) | undefined;
+/**
+ * Format a possibly-missing value: numbers through the formatter (or with
+ * thousand separators), null and non-finite values as `empty`
+ */
+declare function formatValue(value: number | string | null | undefined, formatter?: (value: number) => string, empty?: string): string;
 /**
  * Format a number as currency
  */
@@ -49,14 +61,27 @@ declare function createTooltipFormatter(options?: {
  * Accessibility utilities for charts
  */
 
+type Formatter = ((value: number) => string) | undefined;
 /**
  * Generate an accessible description for a line chart
  */
-declare function generateLineChartDescription(title: string, data: LineChartData): string;
+declare function generateLineChartDescription(title: string, data: LineChartData, format?: Formatter): string;
+/**
+ * Generate an accessible description for an area chart
+ */
+declare function generateAreaChartDescription(title: string, data: CategoryChartData, format?: Formatter): string;
+/**
+ * Generate an accessible description for a combo chart
+ */
+declare function generateComboChartDescription(title: string, data: CategoryChartData, format?: Formatter): string;
 /**
  * Generate an accessible description for a bar chart
  */
-declare function generateBarChartDescription(title: string, data: BarChartData): string;
+declare function generateBarChartDescription(title: string, data: BarChartData, format?: Formatter): string;
+/**
+ * Generate an accessible description for a dot plot
+ */
+declare function generateDotPlotDescription(title: string, data: CategoryChartData, format?: Formatter): string;
 /**
  * Generate an accessible description for a pie/donut chart
  */
@@ -65,6 +90,25 @@ declare function generatePieChartDescription(title: string, data: PieSliceData[]
  * Generate an accessible description for a scatter chart
  */
 declare function generateScatterChartDescription(title: string, data: ScatterChartData): string;
+/**
+ * Generate an accessible description for a histogram
+ */
+declare function generateHistogramDescription(title: string, buckets: HistogramBucket[], total: number): string;
+/**
+ * Generate an accessible description for a box plot
+ */
+declare function generateBoxPlotDescription(title: string, groups: {
+    name: string;
+    stats: BoxPlotStats | null;
+}[], format?: Formatter): string;
+/**
+ * Generate an accessible description for a waterfall chart
+ */
+declare function generateWaterfallDescription(title: string, steps: WaterfallStep[], final: number, format?: Formatter): string;
+/**
+ * Generate an accessible description for a bullet chart
+ */
+declare function generateBulletDescription(title: string, items: BulletItem[], format?: Formatter): string;
 /**
  * Generate a data table for screen readers (hidden visually)
  */
@@ -230,5 +274,357 @@ declare function buildTooltip(base: AnyObject, { show, formatter, valueFormatter
  * tooltip is custom HTML (where ECharts' `valueFormatter` does not apply)
  */
 declare function formatTooltipValue(value: unknown, valueFormatter: ((value: number) => string) | undefined): string;
+/**
+ * A data label formatter that writes values with a value format, keeping any
+ * per-point label text
+ */
+declare function valueLabelFormatter(format: (value: number) => string): (params: LabelFormatterParams) => string;
+/**
+ * Give a value axis tick formatter from a value format, unless the axis
+ * config sets its own
+ */
+declare function valueAxisConfig(config: AxisConfig | undefined, format: ((value: number) => string) | undefined): AxisConfig | undefined;
+interface ChartFormatterOptions {
+    /** The `valueFormat` prop */
+    valueFormat?: ValueFormat;
+    /** The `locale` prop */
+    locale?: string;
+    /** The `tooltipValueFormatter` prop */
+    tooltipValueFormatter?: (value: number) => string;
+    /** The `labelFormatter` prop */
+    labelFormatter?: ChartFormatter<LabelFormatterParams>;
+}
+interface ChartFormatters {
+    /** The resolved value format, if any */
+    format: ((value: number) => string) | undefined;
+    /** Formatter for tooltip values */
+    tooltip: ((value: number) => string) | undefined;
+    /** Formatter for data labels */
+    label: ChartFormatter<LabelFormatterParams> | undefined;
+    /** Apply the value format to a value axis config */
+    axis: (config: AxisConfig | undefined) => AxisConfig | undefined;
+}
+/**
+ * Resolve `valueFormat` into the tooltip, label and axis formatters a chart
+ * uses; the explicit formatter props win over it
+ */
+declare function chartFormatters({ valueFormat, locale, tooltipValueFormatter, labelFormatter, }: ChartFormatterOptions): ChartFormatters;
+interface ReferenceMarkOptions {
+    /** Which axis carries values: 'y' for vertical charts, 'x' for horizontal ones */
+    valueAxis: 'x' | 'y';
+    /** Formats the default line label */
+    format?: (value: number) => string;
+    /** Default line colour */
+    color: string;
+    /** Default band colour */
+    bandColor: string;
+    /**
+     * Whether the category axis runs top to bottom (horizontal bars, dot
+     * plots), so a vertical line's far end is at the bottom
+     */
+    inverse?: boolean;
+}
+/**
+ * Build a series `markLine` for reference lines
+ */
+declare function buildMarkLine(lines: ReferenceLine[] | undefined, { valueAxis, format, color, inverse }: ReferenceMarkOptions): AnyObject | undefined;
+/**
+ * Build a series `markArea` for reference bands
+ */
+declare function buildMarkArea(bands: ReferenceBand[] | undefined, { valueAxis, bandColor }: ReferenceMarkOptions): AnyObject | undefined;
+/**
+ * Attach reference lines and bands to the series they name (the first series
+ * by default). Returns the series unchanged when there are none.
+ */
+declare function withReferenceMarks<S extends AnyObject>(series: S[], lines: ReferenceLine[] | undefined, bands: ReferenceBand[] | undefined, options: ReferenceMarkOptions): (S & {
+    markLine?: AnyObject;
+    markArea?: AnyObject;
+})[];
+/**
+ * Build `dataZoom` components for a category axis
+ */
+declare function buildDataZoom(mode: boolean | 'inside' | 'slider' | undefined, axis: 'x' | 'y', 
+/** Room taken by a bottom legend, so a slider sits above it */
+bottomOffset?: number): AnyObject[] | undefined;
+/**
+ * Grid room for a data zoom slider, added to a `gridInset` result
+ */
+declare function withZoomInset(inset: AnyObject | undefined, mode: boolean | 'inside' | 'slider' | undefined, axis: 'x' | 'y'): AnyObject | undefined;
+
+/**
+ * Data preparation for distribution, waterfall and stacked charts, and
+ * chart sizing helpers
+ */
+
+/**
+ * A "nice" step (1, 2, 2.5 or 5 times a power of ten) at least `rough`
+ */
+declare function niceStep(rough: number): number;
+interface BinValuesOptions {
+    /** A bucket count, or explicit buckets (defaults to Sturges' rule) */
+    bins?: number | HistogramBin[];
+    /** Width of equal buckets (takes precedence over a bucket count) */
+    binWidth?: number;
+    /** Formats bucket bounds in generated labels */
+    format?: (value: number) => string;
+}
+/**
+ * Count values into histogram buckets. Each bucket includes its start and
+ * excludes its end, except the last, which includes both. Non-finite values
+ * are ignored.
+ */
+declare function binValues(values: number[], options?: BinValuesOptions): HistogramBucket[];
+/**
+ * Quantile of sorted values by linear interpolation (the method spreadsheets
+ * and NumPy use by default)
+ */
+declare function quantile(sorted: number[], q: number): number;
+/**
+ * Five-number summary with Tukey whiskers (1.5 IQR) and outliers. Returns
+ * null when there are no finite values.
+ */
+declare function boxplotStats(values: number[]): BoxPlotStats | null;
+/**
+ * Where one waterfall step's bar sits
+ */
+interface WaterfallBar {
+    /** Running total before the step (0 for totals) */
+    start: number;
+    /** Running total after the step */
+    end: number;
+    /** The step's change, or the total for total steps */
+    value: number;
+    /** How the bar is coloured */
+    kind: 'increase' | 'decrease' | 'total';
+    /**
+     * Stacking pieces: an invisible `base`, then the `positive` part (above
+     * zero) and `negative` part (below zero) of the visible bar. ECharts stacks
+     * positive and negative values separately, so bars that cross zero draw
+     * correctly.
+     */
+    base: number;
+    positive: number;
+    negative: number;
+}
+/**
+ * Lay out waterfall steps as stacked bar pieces
+ */
+declare function waterfallLayout(steps: WaterfallStep[]): WaterfallBar[];
+/**
+ * Convert stacked series to each category's share of 100%. Missing values
+ * stay missing; a category whose values sum to zero gets zeros.
+ */
+declare function toPercentStack<S extends {
+    data: (number | null)[];
+}>(series: S[]): S[];
+/**
+ * Pair category labels with values for a time or value x-axis, which reads
+ * [x, y] points rather than values by category index
+ */
+declare function pairWithCategories<V>(categories: (string | number)[], values: V[], axisType: string | undefined): (V | [string | number, V])[];
+interface AutoHeightOptions {
+    /** Height per row (defaults to 28) */
+    rowHeight?: number;
+    /** Fixed space for axes and padding (defaults to 56) */
+    chrome?: number;
+    /** Lower bound (defaults to 160) */
+    minHeight?: number;
+    /** Upper bound */
+    maxHeight?: number;
+}
+/**
+ * Resolve a chart height: 'auto' sizes to the row count within the min and
+ * max bounds; any other height is returned unchanged
+ */
+declare function resolveChartHeight(height: number | string | undefined, rows: number, { rowHeight, chrome, minHeight, maxHeight }?: AutoHeightOptions): number | string | undefined;
+/**
+ * Whether every series is empty or holds only missing values
+ */
+declare function allSeriesEmpty(series: Pick<CategorySeriesData, 'data'>[] | undefined): boolean;
+/**
+ * Least-squares trend line through points, as its two end points. Returns
+ * null for fewer than two points or when every x is the same.
+ */
+declare function trendLine(points: [number, number][]): [[number, number], [number, number]] | null;
+/**
+ * A change between two values
+ */
+interface Delta {
+    /** current - previous */
+    change: number;
+    /** The change relative to |previous|, or null when previous is 0 */
+    ratio: number | null;
+    /** Which way the value moved */
+    direction: 'up' | 'down' | 'flat';
+}
+/**
+ * Compare a value with a previous one. Returns null when either is missing.
+ */
+declare function computeDelta(current: number | null | undefined, previous: number | null | undefined): Delta | null;
+
+/**
+ * Adapters from arrays of records (rows from an API or query) to chart data
+ */
+
+/** A field name or a function reading a value from a record */
+type Accessor<T, V> = keyof T | ((row: T) => V);
+/** How values that share a category (and series) are combined */
+type Aggregate = 'sum' | 'count' | 'avg' | 'min' | 'max' | 'first' | 'last';
+interface FromRecordsOptions<T> {
+    /** Field (or function) giving each record's category */
+    category: Accessor<T, unknown>;
+    /** Field (or function) giving each record's value; omit with `aggregate: 'count'` */
+    value?: Accessor<T, unknown>;
+    /**
+     * Field (or function) splitting records into series (long data). Omit for a
+     * single series named by `seriesName`.
+     */
+    series?: Accessor<T, unknown>;
+    /**
+     * Several value fields, each becoming a series (wide data), as
+     * `{ 'Series name': field }`. Replaces `value` and `series`.
+     */
+    measures?: Record<string, Accessor<T, unknown>>;
+    /** Name of the single series when neither `series` nor `measures` is given */
+    seriesName?: string;
+    /** How records sharing a category and series combine (defaults to 'sum') */
+    aggregate?: Aggregate;
+    /**
+     * Category order: by total descending ('total'), ascending ('total-asc'),
+     * alphabetically ('category'), first appearance ('none', the default), or
+     * a comparator of category labels
+     */
+    sort?: 'total' | 'total-asc' | 'category' | 'none' | ((a: string, b: string) => number);
+    /** Explicit category order; listed categories come first, the rest follow */
+    categoryOrder?: string[];
+    /** Keep only the first N categories after sorting (sorts by total when `sort` is unset) */
+    topN?: number;
+    /**
+     * Fold the categories beyond `topN` into one with this label (only for
+     * 'sum' and 'count', where folding is meaningful). Omit to drop them.
+     */
+    otherLabel?: string;
+    /** Explicit series order; listed series come first, the rest follow in first-appearance order */
+    seriesOrder?: string[];
+    /** Label for missing categories and series (defaults to 'Unknown') */
+    nullLabel?: string;
+    /** Value for category and series combinations with no records (defaults to null, a gap) */
+    fill?: number | null;
+    /** Series colours by series name */
+    colors?: Record<string, string>;
+}
+/**
+ * Pivot records into the categories x series shape used by line, bar, area,
+ * combo and dot plot charts
+ *
+ * ```ts
+ * fromRecords(rows, { category: 'builder', series: 'status', value: 'homes', sort: 'total', topN: 10 })
+ * fromRecords(rows, { category: 'month', measures: { Started: 'starts', Closed: 'closings' } })
+ * ```
+ */
+declare function fromRecords<T>(rows: T[], options: FromRecordsOptions<T>): CategoryChartData;
+interface ToSliceDataOptions<T> {
+    /** Field (or function) giving each slice's name */
+    name: Accessor<T, unknown>;
+    /** Field (or function) giving each slice's value; omit to count records */
+    value?: Accessor<T, unknown>;
+    /** How records sharing a name combine (defaults to 'sum') */
+    aggregate?: Aggregate;
+    /** Drop slices whose value is zero or missing (defaults to true) */
+    dropZero?: boolean;
+    /** Slice order (defaults to 'desc', largest first) */
+    sort?: 'desc' | 'asc' | 'none';
+    /** Keep only the largest N slices */
+    topN?: number;
+    /** Fold slices beyond `topN` into one with this label; omit to drop them */
+    otherLabel?: string;
+    /** Label for a missing name (defaults to 'Unknown') */
+    nullLabel?: string;
+    /** Slice colours by name */
+    colors?: Record<string, string>;
+}
+/**
+ * Aggregate records into pie, donut or funnel slices
+ */
+declare function toSliceData<T>(rows: T[], options: ToSliceDataOptions<T>): PieSliceData[];
+
+/**
+ * Chart data as tables, for the accessible data table and CSV export
+ */
+
+/**
+ * Categories x series as a table: one row per category, one column per series
+ */
+declare function categoryTable(data: CategoryChartData, categoryHeader?: string): ChartDataTable;
+/**
+ * Slices as a table with each slice's share of the total
+ */
+declare function sliceTable(slices: PieSliceData[], nameHeader?: string): ChartDataTable;
+/**
+ * Scatter points as a table
+ */
+declare function scatterTable(data: ScatterChartData, xHeader?: string, yHeader?: string): ChartDataTable;
+/**
+ * Radar series as a table: one row per indicator
+ */
+declare function radarTable(data: RadarChartData, indicators: RadarIndicator[]): ChartDataTable;
+/**
+ * Heatmap cells as a grid: one row per y label, one column per x label
+ */
+declare function heatmapTable(data: HeatmapData, xAxis: string[], yAxis: string[]): ChartDataTable;
+/**
+ * Treemap leaves as a table with their full path
+ */
+declare function treemapTable(nodes: TreemapNode[]): ChartDataTable;
+/**
+ * Sankey links as a table
+ */
+declare function sankeyTable(data: SankeyData): ChartDataTable;
+/**
+ * Candlestick prices as a table
+ */
+declare function candlestickTable(data: CandlestickData): ChartDataTable;
+/**
+ * Histogram buckets as a table
+ */
+declare function histogramTable(buckets: HistogramBucket[]): ChartDataTable;
+/**
+ * Box plot summaries as a table
+ */
+declare function boxPlotTable(groups: {
+    name: string;
+    stats: BoxPlotStats | null;
+}[]): ChartDataTable;
+/**
+ * Waterfall steps as a table with the running total
+ */
+declare function waterfallTable(steps: WaterfallStep[], bars: WaterfallBar[]): ChartDataTable;
+/**
+ * Bullet rows as a table
+ */
+declare function bulletTable(items: BulletItem[]): ChartDataTable;
+/**
+ * Format a table cell for display
+ */
+declare function formatTableCell(table: ChartDataTable, cell: string | number | null, column: number, format?: (value: number) => string): string;
+/**
+ * Serialise a table as CSV (RFC 4180). Numbers stay raw so spreadsheets can
+ * work with them; pass `format` to write formatted values instead.
+ */
+declare function tableToCsv(table: ChartDataTable, format?: (value: number) => string): string;
+/**
+ * A file name from a chart title: lowercase words joined by hyphens
+ */
+declare function chartFilename(title: string): string;
+/**
+ * Trigger a browser download of text or a data URL. Does nothing outside a
+ * browser.
+ */
+declare function downloadFile(content: string, filename: string, mimeType?: string): void;
+/**
+ * Download a table as a CSV file. A byte order mark makes Excel read it as
+ * UTF-8.
+ */
+declare function downloadCsv(table: ChartDataTable, filename: string): void;
 
-export { AxisConfig, BarChartData, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, ChartFormatter, ChartLegendConfig, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, ScatterChartData, TooltipFormatterParams, abbreviateNumber, anchorCenterGraphic, buildAxis, buildDataLabel, buildLegend, buildTooltip, createTooltipFormatter, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTooltipValue, generateBarChartDescription, generateDataTable, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, pointLabel, seriesLabelLookup, withPointLabels };
+export { type Accessor, type Aggregate, type AutoHeightOptions, AxisConfig, BarChartData, type BinValuesOptions, BoxPlotStats, type BuildDataLabelOptions, type BuildLegendOptions, type BuildTooltipOptions, BulletItem, CandlestickData, CategoryChartData, CategorySeriesData, ChartDataTable, ChartFormatter, type ChartFormatterOptions, type ChartFormatters, ChartLegendConfig, type Delta, type FromRecordsOptions, HeatmapData, HistogramBin, HistogramBucket, LabelFormatterParams, LegendItem, LineChartData, PieSliceData, type PointLabelLookup, RadarChartData, RadarIndicator, ReferenceBand, ReferenceLine, type ReferenceMarkOptions, SankeyData, ScatterChartData, type ToSliceDataOptions, TooltipFormatterParams, TreemapNode, ValueFormat, type WaterfallBar, WaterfallStep, abbreviateNumber, allSeriesEmpty, anchorCenterGraphic, binValues, boxPlotTable, boxplotStats, buildAxis, buildDataLabel, buildDataZoom, buildLegend, buildMarkArea, buildMarkLine, buildTooltip, bulletTable, candlestickTable, categoryTable, chartFilename, chartFormatters, computeDelta, createTooltipFormatter, downloadCsv, downloadFile, escapeHtml, formatCurrency, formatDate, formatNumber, formatPercent, formatTableCell, formatTooltipValue, formatValue, fromRecords, generateAreaChartDescription, generateBarChartDescription, generateBoxPlotDescription, generateBulletDescription, generateComboChartDescription, generateDataTable, generateDotPlotDescription, generateHistogramDescription, generateLineChartDescription, generatePieChartDescription, generateScatterChartDescription, generateWaterfallDescription, getLegendItems, getReplaceMerge, gridInset, hasPointLabels, heatmapTable, histogramTable, itemLabelLookup, legendCenter, mergeChartOption, nameLabelLookup, niceStep, pairWithCategories, pointLabel, quantile, radarTable, resolveChartHeight, resolveValueFormatter, sankeyTable, scatterTable, seriesLabelLookup, sliceTable, tableToCsv, toPercentStack, toSliceData, treemapTable, trendLine, valueAxisConfig, valueLabelFormatter, waterfallLayout, waterfallTable, withPointLabels, withReferenceMarks, withZoomInset };