@x12i/charts 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -1,166 +1,274 @@
+import { D as Datasets, C as ChartSpec, R as Row, S as StackMode, a as ChartModel, L as LayoutOptions, b as ChartLayout, c as ChartMessagesInput } from './echarts-option-DHFfEvN1.js';
+export { A as AXIS_FONT_SIZE, d as Annotation, e as AnnotationLayout, f as AnnotationTone, g as AxisLayout, h as AxisMarginInput, i as AxisSpec, j as AxisTick, B as BandScale, k as BinSpec, l as Box, m as BuildModelOptions, n as ChartA11y, o as ChartData, p as ChartFormatters, q as ChartInteractions, r as ChartLabels, s as ChartMessages, t as ChartPointInfo, u as ChartThemeColors, v as ChartType, w as ColorScale, x as ContinuousKind, y as ContinuousScale, z as ContinuousScaleOptions, E as DEFAULT_LOCALE, F as DashStyle, G as DomainOptions, H as DonutSpec, I as EChartsOptionInput, J as EChartsOptionObject, K as Encoding, M as FieldType, N as FitLabelsOptions, O as FittedLabel, P as FocusShape, Q as Formatter, T as GaugeSpec, U as HistogramBin, V as HistogramOptions, W as HitStrategy, X as HitTarget, Y as LabelFit, Z as LayoutMark, _ as LegendEntry, $ as LegendSpec, a0 as MAX_HUES, a1 as Margin, a2 as MarkKind, a3 as MarkerShape, a4 as ModelGauge, a5 as ModelPoint, a6 as ModelSeries, a7 as ModelSlice, a8 as ModelStatus, a9 as NavKey, aa as NavigationMode, ab as NumberFormatOptions, ac as PointScale, ad as RenderTarget, ae as RendererChoice, af as ResolveRendererInput, ag as SVG_POINT_LIMIT, ah as ScaleSpec, ai as ScaleType, aj as SeriesMark, ak as SeriesPoint, al as SeriesSpec, am as SeriesStyle, an as SeriesTone, ao as TICK_PADDING, ap as TICK_SIZE, aq as TextLabel, ar as Threshold, as as TooltipContent, at as TooltipRow, au as Transform, av as TransformContext, aw as WaterfallSpec, ax as WaterfallStep, ay as XKind, az as annotationTone, aA as applyTransforms, aB as buildChartModel, aC as capitalize, aD as categoricalTones, aE as chartTypes, aF as computeAxisMargins, aG as countPoints, aH as createBandScale, aI as createContinuousScale, aJ as createDateFormatter, aK as createFormatters, aL as createNumberFormatter, aM as createPointScale, aN as createTimeTickFormatter, aO as dashArrays, aP as dashStyles, aQ as defaultMessages, aR as defineChartSpec, aS as describeTarget, aT as divergingColor, aU as dodgePositions, aV as effectiveStack, aW as estimateTextWidth, aX as fitTickLabels, aY as formatList, aZ as formatMessage, a_ as formatShare, a$ as fractionDigitsForStep, b0 as histogramBins, b1 as hitTest, b2 as isNavKey, b3 as isOpenMarker, b4 as isRtlLocale, b5 as isSupportedMark, b6 as markerPath, b7 as markerShapes, b8 as navKeys, b9 as navigate, ba as niceTicks, bb as pointInfo, bc as rampGradient, bd as readField, be as resolveMessages, bf as resolveRenderer, bg as resolveRows, bh as sequentialColor, bi as seriesStyle, bj as supportedMarks, bk as targetById, bl as themeColorsFromTokens, bm as toCategory, bn as toEChartsOption, bo as toNumber, bp as toTime, bq as toneCssVar, br as toneTokenPath, bs as toneVarName, bt as tooltipFor, bu as truncateLabel, bv as usesBandX, bw as valueDomain } from './echarts-option-DHFfEvN1.js';
+import '@x12i/tokens';
+
 /**
- * ChartSpec: a JSON-serializable description of one chart (spec section 8).
- * The grammar is deliberately smaller than Vega-Lite. Renderers read a spec and
- * draw it with kit tokens, so an engine can change without breaking apps.
- */
-/** Chart types by family. Entries marked 1.x in the spec are included so specs written today stay valid. */
-declare const chartTypes: readonly ["bar", "lollipop", "dot-plot", "bullet", "slope", "dumbbell", "line", "area", "step", "sparkline", "range-band", "candlestick", "ohlc", "histogram", "box-plot", "density", "strip", "beeswarm", "violin", "ecdf", "donut", "treemap", "waterfall", "funnel", "waffle", "sunburst", "marimekko", "scatter", "bubble", "connected-scatter", "heatmap", "hexbin", "contour", "stat", "gauge", "progress-ring", "sankey", "chord", "alluvial", "choropleth", "point-map", "heat-layer", "flow-map", "gantt", "timeline", "burndown", "cumulative-flow", "calendar-heatmap"];
-type ChartType = (typeof chartTypes)[number];
-type FieldType = "category" | "number" | "time" | "boolean";
-/** Where the rows come from: a named dataset resolved by the app, or inline values. */
-type ChartData = {
-    ref: string;
-} | {
-    values: ReadonlyArray<Record<string, unknown>>;
-};
-interface Encoding {
-    field: string;
-    type: FieldType;
-    /** A named format such as `compact` or `percent`, or an ICU pattern. */
-    format?: string;
-    /** Axis or legend title. Axis titles carry units. */
-    title?: string;
+ * Spec validation. `validateChartSpec` accepts `unknown` so it can check JSON
+ * from files, databases or an AI, and returns a list of issues instead of
+ * throwing. Messages are for developers (English); the renderers never show
+ * them.
+ */
+
+type IssueSeverity = "error" | "warning";
+interface ChartIssue {
+    severity: IssueSeverity;
+    /** Stable code, for example `title-missing`. */
+    code: string;
+    /** Where in the spec, for example `series[1].axis`. */
+    path: string;
+    message: string;
 }
-/** Transforms run in order before drawing. */
-type Transform = {
-    type: "aggregate";
-    groupBy: string[];
-    op: "sum" | "mean" | "min" | "max" | "count";
-    field?: string;
-    as: string;
-} | {
-    type: "bin";
-    field: string;
-    maxBins?: number;
-    as: string;
-} | {
-    type: "stack";
-    field: string;
-    groupBy?: string[];
-    offset?: "zero" | "normalize";
-} | {
-    type: "percent-of-total";
-    field: string;
-    as: string;
-} | {
-    type: "sort";
-    field: string;
-    order?: "asc" | "desc";
-} | {
-    type: "top-n";
-    field: string;
-    n: number;
-    otherLabel?: string;
-} | {
-    type: "rolling-average";
-    field: string;
-    window: number;
-    as: string;
-} | {
-    type: "cumulative-sum";
-    field: string;
-    as: string;
-} | {
-    type: "period-change";
-    field: string;
-    periods?: number;
-    as: string;
-} | {
-    type: "downsample";
-    method: "lttb";
-    field: string;
-    threshold: number;
-};
-/** Targets, limits and forecasts are always labeled marks, never unlabeled lines. */
-type Annotation = {
-    type: "reference-line";
-    x?: number | string;
-    y?: number | string;
-    label: string;
-} | {
-    type: "reference-band";
-    from: number | string;
-    to: number | string;
-    axis: "x" | "y";
-    label: string;
-} | {
-    type: "text";
-    x: number | string;
-    y: number | string;
-    text: string;
-} | {
-    type: "forecast";
-    from: number | string;
-    label: string;
-};
-interface ChartInteractions {
-    tooltip?: boolean;
-    /** Brush to filter other charts and grids through the shared filter store. */
-    brush?: boolean;
-    /** Click a legend entry to isolate a series. */
-    legendIsolate?: boolean;
-    zoom?: boolean;
-    /** Click to drill down through the shared filter store. */
-    drilldown?: boolean;
+interface ValidateOptions {
+    /** Datasets for `data.ref`. With them, missing refs are errors and fields are checked against rows. */
+    datasets?: Datasets | undefined;
+}
+/** Checks a spec and returns every problem found. An empty list means the spec is valid. */
+declare function validateChartSpec(input: unknown, options?: ValidateOptions): ChartIssue[];
+/** True when `validateChartSpec` finds no errors (warnings are allowed). */
+declare function isValidChartSpec(input: unknown, options?: ValidateOptions): input is ChartSpec;
+
+/**
+ * A tiny, safe expression language for `highlight.where`, for example
+ * `week == 'W4'` or `revenue > 100 && region in ['EU', 'US']`.
+ *
+ * Grammar: literals (numbers, quoted strings, true, false, null), field names,
+ * `== != < <= > >=`, `in [..]`, `!`, `&&`, `||` and parentheses. It never calls
+ * `eval` or `Function`, so specs from untrusted sources are safe to evaluate.
+ */
+
+declare class ExpressionError extends Error {
+    constructor(message: string);
+}
+/** Returns an error message when the expression does not parse, otherwise `null`. */
+declare function checkWhere(expression: string): string | null;
+/**
+ * Compiles an expression into a row predicate. An expression that does not
+ * parse matches nothing, so a typo never highlights the wrong marks; use
+ * `checkWhere` (or `validateChartSpec`) to report the problem.
+ */
+declare function compileWhere(expression: string): (row: Row) => boolean;
+/** Evaluates `expression` against one row. */
+declare function evaluateWhere(expression: string, row: Row): boolean;
+
+/**
+ * Downsampling for long series. Both methods keep the first and last point and
+ * return indices into the input, so callers can pick rows or points.
+ */
+interface XY {
+    x: number;
+    y: number;
+}
+/**
+ * Largest-Triangle-Three-Buckets (Steinarsson, 2013). Keeps the visual shape of
+ * a line while reducing it to `threshold` points. The input must be sorted by x.
+ * Returns the kept indices in ascending order. When `threshold` is at least the
+ * input length, or under 3, every index (or just the ends) is returned.
+ */
+declare function lttbIndices(points: ReadonlyArray<XY>, threshold: number): number[];
+/** LTTB over any items, with accessors for x and y. Items with a non-finite x or y are dropped first. */
+declare function lttb<T>(items: ReadonlyArray<T>, getX: (item: T) => number, getY: (item: T) => number, threshold: number): T[];
+/**
+ * Min/max bucket downsampling. Splits the input into `buckets` equal runs and
+ * keeps the lowest and highest point of each, so spikes always survive. Output
+ * has at most `2 * buckets` points, in input order. The input must be sorted by x.
+ */
+declare function minMaxIndices(points: ReadonlyArray<XY>, buckets: number): number[];
+declare function minMax<T>(items: ReadonlyArray<T>, getX: (item: T) => number, getY: (item: T) => number, buckets: number): T[];
+
+interface StackedValue {
+    /** Lower edge of the segment. */
+    y0: number;
+    /** Upper edge of the segment. */
+    y1: number;
+}
+/**
+ * Stacks values per category. `values[s][c]` is series `s` at category `c`
+ * (`null` counts as zero). Returns the same shape with a `[y0, y1]` segment
+ * for each cell.
+ *
+ * - `none`: every segment starts at zero.
+ * - `stacked`: segments add up.
+ * - `normalized`: each category adds up to 1 (so format as percent).
+ * - `diverging`: positives stack above zero and negatives below it.
+ */
+declare function stackValues(values: ReadonlyArray<ReadonlyArray<number | null>>, mode: StackMode): StackedValue[][];
+
+type MaybeNumber = number | null | undefined;
+declare function sum(values: ReadonlyArray<MaybeNumber>): number;
+/** Arithmetic mean, or `null` when there are no values. */
+declare function mean(values: ReadonlyArray<MaybeNumber>): number | null;
+/** Linear-interpolated quantile for `p` in [0, 1] (the R-7 method), or `null` when empty. */
+declare function quantile(values: ReadonlyArray<MaybeNumber>, p: number): number | null;
+declare function median(values: ReadonlyArray<MaybeNumber>): number | null;
+/** Sample variance (n - 1 denominator), or `null` with fewer than two values. */
+declare function variance(values: ReadonlyArray<MaybeNumber>): number | null;
+declare function standardDeviation(values: ReadonlyArray<MaybeNumber>): number | null;
+/** Smallest and largest finite value, or `null` when empty. */
+declare function extent(values: ReadonlyArray<MaybeNumber>): [number, number] | null;
+interface LinearRegression {
+    slope: number;
+    intercept: number;
+    /** Coefficient of determination, from 0 to 1. 1 when all y values are equal. */
+    r2: number;
+    /** Number of points used. */
+    count: number;
+    predict: (x: number) => number;
+}
+/** Ordinary least squares over `[x, y]` pairs. Returns `null` with fewer than two distinct x values. */
+declare function linearRegression(points: ReadonlyArray<readonly [number, number]>): LinearRegression | null;
+/** Pearson correlation of paired values, or `null` when it is undefined. */
+declare function correlation(xs: ReadonlyArray<MaybeNumber>, ys: ReadonlyArray<MaybeNumber>): number | null;
+interface MovingAverageOptions {
+    /** `trailing` averages the current and earlier values; `centered` looks both ways. Defaults to `trailing`. */
+    align?: "trailing" | "centered";
+    /**
+     * When true (default), the first `window - 1` outputs are `null` instead of
+     * partial averages, so the line never starts with a misleading short window.
+     */
+    strict?: boolean;
+}
+/**
+ * Moving average over `window` values. The output has the same length as the
+ * input. Missing values inside a window are skipped; a window with no values
+ * gives `null`.
+ */
+declare function movingAverage(values: ReadonlyArray<MaybeNumber>, window: number, { align, strict }?: MovingAverageOptions): Array<number | null>;
+/** Running total. Missing values add nothing and keep the previous total. */
+declare function cumulativeSum(values: ReadonlyArray<MaybeNumber>): number[];
+/**
+ * Change from `from` to `to` as a fraction (0.25 means +25%), or `null` when
+ * the starting value is zero or missing. Negative starting values use the
+ * absolute value so that an increase is always positive.
+ */
+declare function percentChange(from: MaybeNumber, to: MaybeNumber): number | null;
+/** Period-over-period change as fractions. The first `periods` entries are `null`. */
+declare function periodChange(values: ReadonlyArray<MaybeNumber>, periods?: number): Array<number | null>;
+type Trend = "rising" | "falling" | "flat";
+/**
+ * Overall direction of a series. Fits a line through the values; the trend is
+ * `flat` when the fitted change over the whole series is under `tolerance`
+ * (default 5%) of the value range.
+ */
+declare function trendDirection(values: ReadonlyArray<MaybeNumber>, tolerance?: number): Trend;
+interface RegressionBand {
+    x: number;
+    y: number;
+    lower: number;
+    upper: number;
 }
-/** Accessibility fields. Every chart has an accessible name, a description and a table view. */
-interface ChartA11y {
-    /** The long description read to screen reader users. */
-    description: string;
-    /** Show the underlying data as a table behind a "View as table" toggle. Defaults to true. */
-    table?: boolean;
+/**
+ * Confidence band around a linear fit, using the standard error of the
+ * estimate and a normal critical value (`z`, default 1.96 for about 95%).
+ * `at` lists the x values to evaluate, so the band can extend past the data
+ * for a forecast overlay.
+ */
+declare function regressionBand(points: ReadonlyArray<readonly [number, number]>, at: ReadonlyArray<number>, z?: number): RegressionBand[];
+/**
+ * Linear forecast: continues the fitted line for `steps` more points spaced
+ * `step` apart, starting after the last x. Returns `[]` when no line can be fit.
+ */
+declare function forecastLinear(points: ReadonlyArray<readonly [number, number]>, steps: number, step?: number): Array<[number, number]>;
+
+/**
+ * Hatch pattern for the series at `styleIndex`: none for the first series, then
+ * a different pattern for each further one (all of them with `all`, for print).
+ * The palette repeats its eight hues, so each pass shifts the patterns, which
+ * keeps every hue and pattern pair unique for up to 64 series.
+ */
+declare function patternIndex(styleIndex: number, all?: boolean): number;
+
+/**
+ * Lays a model out in `width` by `height` pixels: axes with ticks, marks as
+ * plain geometry, text labels, annotations, legend entries and the keyboard and
+ * pointer targets. All coordinates are SVG user units. The result is plain
+ * data, so it can be rendered on a server, snapshot-tested, or drawn by
+ * something other than the bundled React renderer.
+ */
+declare function layoutChart(model: ChartModel, options: LayoutOptions): ChartLayout;
+
+/**
+ * Generated text alternatives: an accessible name and a long description built
+ * from the data (type, series, ranges, extremes, overall trend, thresholds).
+ * Authors still write `a11y.description` (the finding); this adds the facts a
+ * screen reader user would otherwise read off the plot. Pure and server-safe.
+ */
+
+interface ChartDescription {
+    /** The accessible name: the title and the chart type, for example "Revenue (line chart)". */
+    name: string;
+    /** Type, series count and point count in one sentence. */
+    summary: string;
+    /** Sentences about axes, series extremes, trends, thresholds and breaches. */
+    details: string[];
+    /** The author's description, the summary and the details, in reading order. */
+    text: string;
 }
-type RendererChoice = "svg" | "canvas" | "auto";
-interface ChartSpec {
-    /** Schema version, so saved specs can be migrated. */
-    version?: 1;
-    /** The finding: a sentence that states what the chart shows. */
-    title: string;
-    /** Scope and units. */
-    subtitle?: string;
-    /** Where the data came from. Required in reports. */
-    source?: string;
-    data: ChartData;
-    mark: ChartType;
-    x?: Encoding;
-    y?: Encoding;
-    /** Series that differ in kind use the categorical palette, capped at 8 hues. */
-    color?: Encoding;
-    size?: Encoding;
-    /** One accent on what the title is about, for example `week == 'W4'`. */
-    highlight?: {
-        where: string;
-    };
-    transforms?: Transform[];
-    annotations?: Annotation[];
-    interactions?: ChartInteractions;
-    /** Dual axes only behind an explicit flag, which adds a visible warning. */
-    dualAxis?: boolean;
-    renderer?: RendererChoice;
-    /** Whether axes mirror in right-to-left locales. */
-    direction?: "ltr" | "rtl" | "auto";
-    a11y: ChartA11y;
+interface DescribeOptions {
+    datasets?: Datasets | undefined;
+    locale?: string | undefined;
+    messages?: ChartMessagesInput | undefined;
+    /** Ids of hidden series, which are mentioned but not described. */
+    hidden?: ReadonlySet<string> | undefined;
+    /** At most this many series get their own sentences. Defaults to 6. */
+    maxSeries?: number | undefined;
 }
-/** Identity helper that gives authoring-time type checking and autocomplete. */
-declare function defineChartSpec(spec: ChartSpec): ChartSpec;
+/** Describes a built model. Prefer this when you already have one. */
+declare function describeModel(model: ChartModel, options?: DescribeOptions): ChartDescription;
+/**
+ * Builds the accessible name and long description of a chart from its spec.
+ * Combine with `spec.a11y.description`, which is placed first in `text`.
+ */
+declare function describeChart(spec: ChartSpec, options?: DescribeOptions): ChartDescription;
 
 /**
- * The SVG renderer is comfortable up to roughly this many points per chart
- * (spec section 8: about 1,000 to 5,000). Beyond it, auto mode uses canvas.
+ * The data table alternative and CSV export. Both read the model, so they show
+ * exactly the values the chart draws (after transforms), and work on the
+ * server. Pure.
  */
-declare const SVG_POINT_LIMIT = 5000;
-type RenderTarget = "screen" | "print" | "report";
-interface ResolveRendererInput {
-    renderer?: RendererChoice;
-    mark: ChartType;
-    pointCount: number;
-    target?: RenderTarget;
+
+interface TableColumn {
+    key: string;
+    label: string;
+    /** True for number columns, which right-align (inline-end) and use tabular figures. */
+    numeric: boolean;
+}
+interface TableCell {
+    /** Machine value: a number, an ISO date string for times, text, or null when missing. */
+    value: string | number | null;
+    /** Display text, formatted for the locale. */
+    text: string;
+}
+interface ChartTable {
+    caption: string;
+    columns: TableColumn[];
+    rows: TableCell[][];
+}
+interface TableOptions {
+    datasets?: Datasets | undefined;
+    locale?: string | undefined;
+    messages?: ChartMessagesInput | undefined;
+}
+/** The table behind a built model. */
+declare function modelToTable(model: ChartModel, options?: TableOptions): ChartTable;
+/** The data table for a spec: the same rows the chart draws, as columns and cells. */
+declare function chartToTable(spec: ChartSpec, options?: TableOptions): ChartTable;
+interface CsvOptions extends TableOptions {
+    /** Field separator. Defaults to a comma. */
+    delimiter?: string;
+    /** Prefix a byte order mark so Excel opens the file as UTF-8. Defaults to false. */
+    bom?: boolean;
+    /** Include the header row. Defaults to true. */
+    header?: boolean;
 }
+/** Quotes a field when needed and neutralizes spreadsheet formulas in text. */
+declare function escapeCsvField(value: string | number | null, delimiter?: string): string;
+/** CSV text (RFC 4180 quoting, CRLF line breaks) for a built table. Machine values: raw numbers, ISO dates. */
+declare function tableToCsv(table: ChartTable, { delimiter, bom, header }?: CsvOptions): string;
 /**
- * Picks a renderer for a chart. Reports and print always use SVG so the output
- * stays vector; on screen, `auto` switches to canvas by point count and type.
+ * CSV export of a spec's data. Text cells that start with `=`, `+`, `-` or `@`
+ * are prefixed with an apostrophe so spreadsheets never run them as formulas.
  */
-declare function resolveRenderer({ renderer, mark, pointCount, target, }: ResolveRendererInput): "svg" | "canvas";
+declare function chartToCsv(spec: ChartSpec, options?: CsvOptions): string;
 
-export { SVG_POINT_LIMIT, chartTypes, defineChartSpec, resolveRenderer };
-export type { Annotation, ChartA11y, ChartData, ChartInteractions, ChartSpec, ChartType, Encoding, FieldType, RenderTarget, RendererChoice, ResolveRendererInput, Transform };
+export { ChartLayout, ChartMessagesInput, ChartModel, ChartSpec, Datasets, ExpressionError, LayoutOptions, Row, StackMode, chartToCsv, chartToTable, checkWhere, compileWhere, correlation, cumulativeSum, describeChart, describeModel, escapeCsvField, evaluateWhere, extent, forecastLinear, isValidChartSpec, layoutChart, linearRegression, lttb, lttbIndices, mean, median, minMax, minMaxIndices, modelToTable, movingAverage, patternIndex, percentChange, periodChange, quantile, regressionBand, stackValues, standardDeviation, sum, tableToCsv, trendDirection, validateChartSpec, variance };
+export type { ChartDescription, ChartIssue, ChartTable, CsvOptions, DescribeOptions, IssueSeverity, LinearRegression, MaybeNumber, MovingAverageOptions, RegressionBand, StackedValue, TableCell, TableColumn, TableOptions, Trend, ValidateOptions, XY };