@k2b/ui 0.50.0 → 0.51.0

package/dist/types/charts/core/svg-renderers.d.ts

@@ -0,0 +1,722 @@
+import type { IntentTone } from "../../semantics";
+import type { ChartDatum } from "./types";
+export type Point = {
+    x: number;
+    y: number;
+    /** Optional third dimension. Honored by `scatter` (controls dot radius);
+     *  ignored by `line` and `sparkline`. */
+    size?: number;
+    /** Symmetric ±error on the y value. Used by error-bar rendering on
+     *  `scatter` and `line`. Overridden by `errYHigh`/`errYLow` if set. */
+    errY?: number;
+    /** Asymmetric upper bound on y (relative magnitude added to y). */
+    errYHigh?: number;
+    /** Asymmetric lower bound on y (relative magnitude subtracted from y). */
+    errYLow?: number;
+    /** Symmetric ±error on the x value. Renders horizontal error bars. */
+    errX?: number;
+    /** Asymmetric upper bound on x. */
+    errXHigh?: number;
+    /** Asymmetric lower bound on x. */
+    errXLow?: number;
+};
+/** Marker shapes for `scatter` data points. Auto-cycles per series when
+ *  `autoVariant` is enabled on the chart. */
+export type MarkerShape = "circle" | "square" | "triangle" | "diamond" | "plus" | "cross";
+/** Line dash patterns for `line` series. Auto-cycles per series when
+ *  `autoVariant` is enabled. */
+export type LineStyle = "solid" | "dashed" | "dotted" | "dashdot";
+export type Series = {
+    /** Optional label for this series. Used by `legend` rendering. */
+    label?: string;
+    data: Point[];
+    /** Override the marker shape for this series. Default: `circle`, or
+     *  cycled from `DEFAULT_MARKERS` when the chart's `autoVariant` is true. */
+    marker?: MarkerShape;
+    /** Override the line dash pattern for this series. Default: `solid`, or
+     *  cycled from `DEFAULT_LINE_STYLES` when the chart's `autoVariant` is true. */
+    lineStyle?: LineStyle;
+};
+export type MapPoint = {
+    /** Latitude in decimal degrees, from -90 to 90. */
+    latitude: number;
+    /** Longitude in decimal degrees, from -180 to 180. */
+    longitude: number;
+    /** Optional label emitted as an escaped SVG `<title>`. */
+    label?: string;
+    /** Optional magnitude used to scale the point radius. */
+    size?: number;
+};
+export type MapSeries = {
+    /** Optional label used by the legend. */
+    label?: string;
+    data: MapPoint[];
+};
+export type MapViewport = {
+    /** Latitude at the center of the viewport. */
+    latitude: number;
+    /** Longitude at the center of the viewport. */
+    longitude: number;
+    /** Zoom level from 0 (full world) to 5. Each level doubles the scale. */
+    zoom: number;
+};
+export type MapOptions = ChartOptions & {
+    series: MapSeries[];
+    /** Deterministic map center and zoom. Values are normalized to the map bounds. */
+    viewport?: MapViewport;
+    /** Pixel-radius range used when at least one finite `size` exists. */
+    sizeRange?: [number, number];
+    /** Render a series legend below the map. Default false. */
+    legend?: boolean;
+};
+export type BarItem = {
+    label: string;
+    value: number;
+    colorIndex?: number;
+};
+export type SliceItem = {
+    label: string;
+    value: number;
+    colorIndex?: number;
+};
+export type AxisOptions = {
+    /** Exact inclusive bounds for comparisons. Must contain all finite plotted
+     * values (including error bounds/baselines); invalid bounds throw RangeError. */
+    domain?: [number, number];
+    /** Opt in to space beside exact endpoint labels. Numeric X labels align
+     * inward; adjacent nice ticks within one interval are omitted. Default false. */
+    insetEndpointLabels?: boolean;
+    /** Suggested tick count. Actual count may differ to keep ticks "nice". */
+    ticks?: number;
+    /** Format a tick value into a label string. Default: `String(v)`. */
+    format?: (value: number) => string;
+    /** Optional axis title rendered alongside the axis. */
+    label?: string;
+    /** Axis scale. `"linear"` (default) or `"log"`. Log axis requires all
+     *  data on this axis to be strictly positive; non-positive values are
+     *  filtered out before domain computation. */
+    scale?: "linear" | "log";
+    /** Render small subdivision ticks between major ticks. Default false. */
+    minorTicks?: boolean;
+};
+export type Padding = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/** One selectable datum in an inspected SVG. Indices refer to the source arrays.
+ * `anchor` uses the containing SVG coordinate system, including nested map SVGs.
+ * Values are raw data; `formatted` contains the renderer's axis/value formatting.
+ */
+/** Wrap renderer-owned geometry with escaped, inert inspection metadata. */
+export declare const chartDatumSvg: (svg: string, datum: ChartDatum, inspect?: boolean, titleText?: string) => string;
+export type ChartOptions = {
+    /** Emit inert datum metadata and SVG titles for progressive inspection. */
+    inspect?: boolean;
+    /** Default 400. */
+    width?: number;
+    /** Default 240. */
+    height?: number;
+    /** Default `{ top: 16, right: 16, bottom: 32, left: 40 }`. A single number
+     *  is applied to all four sides. */
+    padding?: number | Partial<Padding>;
+    /** Appended to the root `<svg>`'s class attribute (after `stdlib-chart`). */
+    className?: string;
+    /** Optional centered title rendered above the plot area. */
+    title?: string;
+    /** Optional centered subtitle rendered below the title. */
+    subtitle?: string;
+};
+/**
+ * A horizontal or vertical reference line drawn on a cartesian chart, e.g.
+ * for thresholds, targets, or averages.
+ */
+export type ReferenceLine = {
+    /** Data value at which to draw the line. */
+    value: number;
+    /** Axis the line is anchored to. `"y"` (default) draws a horizontal line
+     *  at the given y-value; `"x"` draws a vertical line at the x-value. */
+    axis?: "x" | "y";
+    /** Optional inline label rendered at the end of the line. */
+    label?: string;
+    /** Omit to retain the existing dashed line. */
+    style?: "solid" | "dashed" | "dotted";
+    /** Semantic color shared by the line and its label, with standalone SVG fallbacks. */
+    tone?: IntentTone;
+};
+/** Internal shared attributes for raw cartesian charts and UI bar layouts. */
+export declare const referenceLineAttributes: (ref: ReferenceLine, label?: boolean) => string;
+/** XML-escape a string for safe inclusion in attribute values or text content. */
+export declare const escapeXml: (s: string) => string;
+/** Normalize a `Padding` input (number or partial object) to a full `Padding`. */
+export declare const normalizePadding: (p: number | Partial<Padding> | undefined) => Padding;
+/**
+ * Compute `[min, max]` from a list of numeric values, ignoring non-finite
+ * entries. Returns `[0, 1]` for an empty/all-non-finite list and pads ±1
+ * around a single finite value.
+ */
+export declare const computeDomain: (values: readonly number[]) => [number, number];
+/**
+ * Pick a "nice" axis step (1, 2, 5, 10, 20, 50, ...) that splits `range`
+ * into roughly `target` intervals. Avoids ugly tick labels like 0.473.
+ */
+export declare const niceStep: (range: number, target: number) => number;
+/** The most ticks one linear axis counts, the same budget as a time axis; more never fit a readable axis. */
+export declare const MAX_AXIS_TICKS = 1000;
+/**
+ * Round `min` down and `max` up to the nearest multiples of `step`, so the
+ * domain edges fall on tick boundaries. Returns the extended domain plus the
+ * tick values within it (inclusive of both ends).
+ */
+export declare const extendDomainToNice: (min: number, max: number, step: number) => {
+    domain: [number, number];
+    ticks: number[];
+};
+/** Linear map of `value` from input domain `[d0, d1]` to output range `[r0, r1]`. */
+export declare const mapRange: (value: number, [d0, d1]: readonly [number, number], [r0, r1]: readonly [number, number]) => number;
+/**
+ * Logarithmic (base-10) map of `value` from input domain `[d0, d1]` to
+ * output range `[r0, r1]`. Both domain endpoints must be strictly positive.
+ * Non-positive values are clamped to a small epsilon to avoid `-Infinity`.
+ */
+export declare const mapLog: (value: number, [d0, d1]: readonly [number, number], [r0, r1]: readonly [number, number]) => number;
+/**
+ * Compute logarithmic ticks (powers of 10) within `[min, max]`. The
+ * returned array always includes both decade boundaries enclosing the
+ * domain so the axis line spans the data.
+ */
+export declare const niceLogTicks: (min: number, max: number) => {
+    domain: [number, number];
+    ticks: number[];
+};
+/**
+ * Least-squares linear regression. Returns slope, intercept, and r² for the
+ * regression line `y = slope * x + intercept`. Returns null for fewer than
+ * two finite points or all-x-equal input.
+ */
+export declare const linearRegression: (points: ReadonlyArray<{
+    x: number;
+    y: number;
+}>) => {
+    slope: number;
+    intercept: number;
+    r2: number;
+} | null;
+/**
+ * Compute box-plot statistics for a set of observations:
+ * min/max, quartiles (q1/q2/q3 via R-7 linear interpolation), Tukey whiskers
+ * (1.5×IQR rule clamped to data extents), and outliers beyond the whiskers.
+ *
+ * Returns null for an empty/all-non-finite input.
+ */
+export declare const computeBoxStats: (values: readonly number[]) => {
+    min: number;
+    max: number;
+    q1: number;
+    q2: number;
+    q3: number;
+    whiskerLow: number;
+    whiskerHigh: number;
+    outliers: number[];
+} | null;
+/**
+ * Bin a numeric dataset into a histogram. `bins` may be:
+ * - undefined → Sturges' formula `ceil(log2(n)) + 1`
+ * - a number → that many equal-width bins
+ * - an array of edges (length k+1 → k bins)
+ *
+ * Non-finite input values are filtered. Returns bin edges and per-bin counts.
+ */
+export declare const autoBin: (values: readonly number[], bins?: number | readonly number[]) => {
+    edges: number[];
+    counts: number[];
+};
+export type PlotArea = {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+};
+export declare const computePlotArea: (width: number, height: number, padding: Padding, hasXAxisLabel: boolean, hasYAxisLabel: boolean, headerHeight?: number, legendHeight?: number) => PlotArea;
+/**
+ * Render an optional centered header (title + subtitle) at the top of an
+ * SVG. Returns the SVG fragment plus the pixel height it consumed so the
+ * caller can shift the plot area down accordingly.
+ */
+export declare const renderHeader: (width: number, title: string | undefined, subtitle: string | undefined) => {
+    svg: string;
+    height: number;
+};
+/**
+ * Render a single-row centered legend at the bottom of the SVG. Returns the
+ * SVG fragment plus the height it consumed so callers can shift the plot
+ * area up accordingly. Empty input yields height 0.
+ */
+export declare const renderLegend: (items: ReadonlyArray<{
+    label: string;
+    seriesIndex: number;
+}>, width: number, yTop: number) => {
+    svg: string;
+    height: number;
+};
+/** Measure the total height a legend with `items` will consume in `width`,
+ *  without actually rendering. Used by chart functions to reserve vertical
+ *  space before computing the plot area. */
+export declare const measureLegendHeight: (items: ReadonlyArray<{
+    label: string;
+    seriesIndex: number;
+}>, width: number) => number;
+/** Wrap chart body in a root `<svg>` with embedded default styles. */
+export declare const svgRoot: (opts: {
+    width: number;
+    height: number;
+    className?: string;
+}, body: string) => string;
+/** Format an SVG path `d` attribute for a polyline through `points`. */
+export declare const linePathD: (points: ReadonlyArray<{
+    x: number;
+    y: number;
+}>) => string;
+/**
+ * Format an SVG path `d` for a smooth curve through `points` using cubic
+ * Bezier segments with Catmull-Rom-derived vertical control points.
+ *
+ * Vertical control points use neighboring `points[i-1]` and `points[i+2]`
+ * (reflecting the end points at boundaries) with the standard Catmull-Rom
+ * tension factor of 1/6. Horizontal control points stay at the segment's
+ * thirds, so x progresses linearly and never doubles back when point spacing
+ * is uneven.
+ */
+export declare const smoothPathD: (points: ReadonlyArray<{
+    x: number;
+    y: number;
+}>) => string;
+/**
+ * Build an SVG path `d` attribute for a pie slice (or donut sector).
+ *
+ * Angles are in radians, measured from the +X axis. Slices grow clockwise,
+ * which in SVG's y-down coordinate space means `a1 > a0` produces a clockwise
+ * arc when drawn with the large-arc and sweep flags set appropriately.
+ *
+ * Full-circle (a1 - a0 ≈ 2π) is split into two 180° arcs because a single
+ * `A` command can't draw a complete circle unambiguously.
+ */
+export declare const arcPathD: (cx: number, cy: number, r: number, a0: number, a1: number, innerR?: number) => string;
+/**
+ * SVG path `d` for a marker shape centered at `(cx, cy)` with circumradius `r`.
+ *
+ * The shapes are sized so a typical visual radius matches `r`:
+ *  - circle: full radius
+ *  - square: side = sqrt(2)·r so the diagonal equals 2·r (visually balanced
+ *    next to a circle of the same r)
+ *  - triangle: equilateral pointing up, circumradius r
+ *  - diamond: square rotated 45°, half-diagonal = r
+ *  - plus: cross-shape at thickness r·0.5
+ *  - cross: X-shape at thickness r·0.4
+ */
+export declare const markerPath: (shape: MarkerShape, cx: number, cy: number, r: number) => string;
+/**
+ * SVG path `d` for a step (stair) line. `mode` controls where the vertical
+ * step happens relative to the data points:
+ *  - `before` — vertical step at the new x BEFORE the value updates (state
+ *    machine "Mealy" style: change at input)
+ *  - `after`  — value updates at the data point's x and persists until next x
+ *  - `middle` — vertical step at the midpoint between consecutive x-values
+ */
+export declare const stepPathD: (points: ReadonlyArray<{
+    x: number;
+    y: number;
+}>, mode: "before" | "after" | "middle") => string;
+/** Format a number for SVG attributes — short, no scientific notation. */
+export declare const fmt: (n: number) => string;
+export declare const clamp: (value: number, min: number, max: number) => number;
+export type RgbColor = {
+    r: number;
+    g: number;
+    b: number;
+};
+export type AxisScale = {
+    domain: [number, number];
+    ticks: number[];
+    minorTicks: number[];
+    scale: "linear" | "log";
+};
+export type SeriesChartOptions = ChartOptions & {
+    series: Series[];
+    xAxis?: AxisOptions;
+    yAxis?: AxisOptions;
+    /** Reference lines (thresholds, targets, averages) drawn on the plot. */
+    references?: ReferenceLine[];
+    /** Render a single-row legend at the bottom of the chart, listing each
+     *  series's label with its color swatch. Series without a `label` are
+     *  shown as `Series N` (1-indexed). Default false. */
+    legend?: boolean;
+};
+export type ScatterOptions = SeriesChartOptions & {
+    /** Pixel-radius range for the optional `size` dimension on points.
+     *  Default `[3, 12]`. Only applied when at least one point has a finite
+     *  `size`; otherwise all points use the default radius (3px). */
+    sizeRange?: [number, number];
+    /** When true, automatically vary marker shape per series (cycling through
+     *  `circle, square, triangle, diamond, plus, cross`) so series remain
+     *  distinguishable in B/W or color-blind contexts. Default false. */
+    autoVariant?: boolean;
+    /** Overlay a least-squares linear regression line across all data points.
+     *  Default false. */
+    trendline?: boolean;
+};
+export type LineOptions = SeriesChartOptions & {
+    /** Render smooth Catmull-Rom curves. Default `true`. Pass `false` for
+     *  straight segments between points. */
+    smooth?: boolean;
+    /** Fill the area below each line with the series color (translucent).
+     *  Renders as a separate path so the line stroke remains crisp. Default false. */
+    area?: boolean;
+    /** Render a step (stair) line instead of a smooth/straight one. Implies
+     *  `smooth: false`. */
+    step?: "before" | "after" | "middle";
+    /** When true, automatically vary line dash pattern per series (cycling
+     *  through `solid, dashed, dotted, dashdot`). Default false. */
+    autoVariant?: boolean;
+    /** Render a translucent confidence band between each point's `errYLow` and
+     *  `errYHigh`. Points without explicit error fields are skipped. Default false. */
+    errorBand?: boolean;
+};
+/**
+ * Render a scatter plot. Each series produces a group of circles, one per
+ * data point, classed `stdlib-chart-series-N` so series colors stay
+ * consistent across charts.
+ *
+ * Non-finite x or y values are filtered out. An empty `series` (or one with
+ * no finite points) renders an empty-state SVG with a "no data" label.
+ *
+ * @example
+ * charts.scatter({ series: [{ data: [{x:1,y:2},{x:2,y:5},{x:3,y:3}] }] });
+ *
+ * @example
+ * charts.scatter({
+ *   series: [
+ *     { label: "Group A", data: [...] },
+ *     { label: "Group B", data: [...] },
+ *   ],
+ *   xAxis: { label: "Time (s)" },
+ *   yAxis: { label: "Value", format: v => `${v}k` },
+ * });
+ */
+export declare const scatter: (opts: ScatterOptions) => string;
+/**
+ * Render a line chart. Each series becomes a `<path class="stdlib-chart-line">`
+ * connecting its points (sorted by `x`). Multi-series charts get distinct
+ * `stdlib-chart-series-N` classes.
+ *
+ * Non-finite points are filtered. A series with fewer than 2 finite points
+ * is skipped (no path can be drawn). An empty/all-non-finite chart renders
+ * an empty-state SVG.
+ *
+ * @example
+ * charts.line({ series: [{ data: [{x:1,y:10},{x:2,y:25},{x:3,y:18}] }] });
+ *
+ * @example
+ * charts.line({
+ *   series: [
+ *     { label: "Revenue", data: [...] },
+ *     { label: "Costs",   data: [...] },
+ *   ],
+ *   yAxis: { format: v => `$${v}k` },
+ * });
+ */
+export declare const line: (opts: LineOptions) => string;
+export type BarChartOptions = ChartOptions & {
+    data: BarItem[];
+    yAxis?: AxisOptions;
+    /** When true, each bar gets its own series color (`series-0` ... `series-7`,
+     *  cyclic). When false (default), all bars share `series-0`. */
+    colorByBar?: boolean;
+    /** Reference lines on the y-axis (e.g. target threshold). x-axis references
+     *  are ignored on bar charts since the x-axis is categorical. */
+    references?: ReferenceLine[];
+    /** Render the formatted value above (positive) or below (negative) each bar.
+     *  Uses `yAxis.format` if provided, otherwise `String(value)`. Default false. */
+    showValues?: boolean;
+    /** Render a legend mapping each bar's label to its color. Only meaningful
+     *  when `colorByBar` is true; ignored otherwise (the default single-color
+     *  bar chart needs no legend). Default false. */
+    legend?: boolean;
+};
+/**
+ * Render a categorical bar chart. The y-domain always includes zero so bars
+ * rest on a visible baseline. Negative values produce bars below the zero
+ * line; mixed positive/negative inputs render the zero line as the X axis.
+ *
+ * Bars use class `stdlib-chart-bar stdlib-chart-series-0` (single-series
+ * only in v1 — grouped/stacked bars are out of scope).
+ *
+ * Non-finite values are filtered. Empty input renders an empty-state SVG.
+ *
+ * @example
+ * charts.bar({ data: [{label:"Q1",value:120},{label:"Q2",value:180}] });
+ *
+ * @example
+ * charts.bar({
+ *   data: [{label:"Profit",value:50},{label:"Loss",value:-20}],
+ *   yAxis: { format: v => `${v}k` },
+ * });
+ */
+export declare const bar: (opts: BarChartOptions) => string;
+export type PieChartOptions = ChartOptions & {
+    data: SliceItem[];
+    /** Render slice labels with percentages outside the chart area. Default false.
+     *  Note: for many small slices or one dominant slice, prefer `legend: true`
+     *  to avoid overlapping labels. */
+    showLabels?: boolean;
+    /** Render a wrapping legend below the chart with `Label (XX%)` entries.
+     *  Recommended when slices are many or when one slice dominates — outside
+     *  labels collide in those cases. Default false. */
+    legend?: boolean;
+    /** Inner radius as a fraction of outer radius (0..1). 0 = pie, 0.6 = donut.
+     *  Values outside `[0, 0.95]` are clamped. */
+    innerRadius?: number;
+};
+/**
+ * Render a pie chart. Slices are drawn clockwise starting at 12 o'clock,
+ * proportional to each item's `value`. Pass `showLabels: true` to render
+ * `Label (XX%)` outside each slice, or `legend: true` to render a wrapping
+ * legend below the chart.
+ *
+ * Use `legend` (not `showLabels`) when slices are many or one slice dominates —
+ * outside labels collide in those cases.
+ *
+ * Non-positive and non-finite values are filtered. A 100%-single-slice draws
+ * a complete circle. Empty/all-zero input renders an empty-state SVG.
+ *
+ * @example
+ * charts.pie({ data: [{label:"A",value:30},{label:"B",value:50},{label:"C",value:20}] });
+ *
+ * @example
+ * charts.pie({ data: [...], showLabels: true });
+ *
+ * @example
+ * charts.pie({ data: [...], legend: true }); // recommended for many small slices
+ */
+export declare const pie: (opts: PieChartOptions) => string;
+/**
+ * Render a donut chart. Identical to {@link pie} but with a hollow center
+ * (default `innerRadius: 0.6`). Override `innerRadius` for a thicker or
+ * thinner ring.
+ *
+ * @example
+ * charts.donut({ data: [{label:"Used",value:67},{label:"Free",value:33}] });
+ *
+ * @example
+ * charts.donut({ data: [...], innerRadius: 0.4, showLabels: true });
+ *
+ * @example
+ * charts.donut({ data: [...], legend: true }); // wrapping legend below the ring
+ */
+export declare const donut: (opts: PieChartOptions) => string;
+export type HistogramOptions = ChartOptions & {
+    /** Raw observations. Non-finite entries are filtered. */
+    data: number[];
+    /** Bin specification:
+     *   - undefined → Sturges' formula `ceil(log2(n)) + 1`
+     *   - number → that many equal-width bins
+     *   - array of bin edges (length k+1 → k bins) */
+    bins?: number | number[];
+    yAxis?: AxisOptions;
+    xAxis?: AxisOptions;
+    references?: ReferenceLine[];
+};
+/**
+ * Render a histogram (frequency distribution) of the given observations.
+ * Uses Sturges' formula by default for bin count, or accepts an explicit
+ * count or list of bin edges.
+ *
+ * Bars are adjacent (no inter-bar gap) since a histogram represents a
+ * continuous distribution. The x-axis is numeric (bin edges as ticks).
+ *
+ * @example
+ * charts.histogram({ data: observations, title: "Reaction times (ms)" });
+ *
+ * @example
+ * charts.histogram({ data: scores, bins: 20, yAxis: { label: "Count" } });
+ */
+export declare const histogram: (opts: HistogramOptions) => string;
+export type BoxPlotItem = {
+    label: string;
+    values: number[];
+};
+export type BoxPlotOptions = ChartOptions & {
+    /** Groups of observations, one box per group. */
+    groups: BoxPlotItem[];
+    yAxis?: AxisOptions;
+    /** When true (default), render outliers as individual dots beyond the
+     *  whiskers (1.5×IQR fences). */
+    showOutliers?: boolean;
+    references?: ReferenceLine[];
+    /** When true, each box gets its own series color. Default false (all use
+     *  series-0). */
+    colorByBox?: boolean;
+};
+/**
+ * Render a box plot (Tukey style): box for the IQR (Q1-Q3), median line,
+ * whiskers extending to 1.5×IQR fences, and individual outlier dots.
+ *
+ * Useful for comparing distributions across categorical groups (e.g. test
+ * scores per class, reaction times per condition).
+ *
+ * @example
+ * charts.boxplot({
+ *   groups: [
+ *     { label: "Class A", values: scoresA },
+ *     { label: "Class B", values: scoresB },
+ *   ],
+ *   yAxis: { label: "Score" },
+ * });
+ */
+export declare const boxplot: (opts: BoxPlotOptions) => string;
+export type Threshold = {
+    /** Inclusive upper bound for this threshold segment. */
+    value: number;
+    /** Optional label for legends or future consumers. */
+    label?: string;
+    /** Optional SVG color. When omitted, the series CSS variables are used. */
+    color?: string;
+};
+export type GaugeOptions = ChartOptions & {
+    value: number;
+    min?: number;
+    max?: number;
+    label?: string;
+    unit?: string;
+    format?: (value: number) => string;
+    thresholds?: Threshold[];
+    showNeedle?: boolean;
+};
+export type BarGaugeItem = {
+    label: string;
+    value: number;
+    min?: number;
+    max?: number;
+    unit?: string;
+};
+export type BarGaugeOptions = ChartOptions & {
+    data: BarGaugeItem[];
+    min?: number;
+    max?: number;
+    unit?: string;
+    format?: (value: number) => string;
+    thresholds?: Threshold[];
+};
+export type StatOptions = ChartOptions & {
+    label: string;
+    value: number | string;
+    unit?: string;
+    delta?: number | string;
+    deltaFormat?: (value: number) => string;
+    trend?: "up" | "down" | "neutral";
+    sparkline?: number[] | Point[];
+    format?: (value: number) => string;
+};
+export type HeatmapDatum = {
+    x: string;
+    y: string;
+    value: number;
+};
+export type HeatmapOptions = ChartOptions & {
+    data: HeatmapDatum[];
+    xLabels?: string[];
+    yLabels?: string[];
+    min?: number;
+    max?: number;
+    format?: (value: number) => string;
+    showValues?: boolean;
+};
+export type StateInterval = {
+    from: number;
+    to: number;
+    state: string;
+    label?: string;
+};
+export type StateTimelineRow = {
+    label: string;
+    intervals: StateInterval[];
+};
+export type StateStyle = {
+    state: string;
+    label?: string;
+    color?: string;
+};
+export type StateTimelineOptions = ChartOptions & {
+    rows: StateTimelineRow[];
+    states?: StateStyle[];
+    xAxis?: Pick<AxisOptions, "format" | "label">;
+    legend?: boolean;
+};
+/**
+ * Render a radial single-value gauge for KPI, quota, saturation, or SLO style
+ * dashboard panels.
+ */
+export declare const gauge: (opts: GaugeOptions) => string;
+/** Render compact horizontal bar gauges for multiple reduced metrics. */
+export declare const barGauge: (opts: BarGaugeOptions) => string;
+/** Render a large value panel with optional delta and inline sparkline. */
+export declare const stat: (opts: StatOptions) => string;
+/**
+ * Render a categorical two-dimensional heatmap. Cell opacity represents value
+ * intensity; labels are derived from first occurrence order unless provided.
+ */
+export declare const heatmap: (opts: HeatmapOptions) => string;
+/**
+ * Render state regions over a numeric timeline for services, jobs, deploys, or
+ * health checks.
+ */
+export declare const stateTimeline: (opts: StateTimelineOptions) => string;
+export type SparklineOptions = {
+    inspect?: boolean;
+    /** Series of values. Bare numbers auto-x to their array index. */
+    data: number[] | Point[];
+    /** Default 80. */
+    width?: number;
+    /** Default 20. */
+    height?: number;
+    /** Render with smooth Catmull-Rom curves. Default `true`. */
+    smooth?: boolean;
+    /** Render a small dot at the last data point. Default false. */
+    showLast?: boolean;
+    /** Render dots at the highest and lowest data points. Skipped when all
+     *  values are equal. Default false. */
+    showMinMax?: boolean;
+    /** Render a soft gradient fill below the stroke line, fading from a
+     *  translucent `currentColor` at the top to fully transparent at the
+     *  bottom — the classic dashboard-tile look. The stroke line stays
+     *  visible on top, and dots from `showLast`/`showMinMax` compose over
+     *  the fill. Default false. */
+    area?: boolean;
+    /** Appended to the root `<svg>`'s class attribute. */
+    className?: string;
+};
+/**
+ * Render a minimalist sparkline — a tiny inline chart with no axes, no
+ * labels, and minimal padding. Designed to fit alongside text or in dense
+ * tables.
+ *
+ * Stroke uses `currentColor` by default, so it adopts the surrounding text
+ * color. Pass `className` to scope a different color.
+ *
+ * @example
+ * charts.sparkline({ data: [3, 7, 5, 9, 12, 10, 14] });
+ *
+ * @example
+ * charts.sparkline({
+ *   data: [3, 7, 5, 9, 12, 10, 14],
+ *   smooth: true,
+ *   showLast: true,
+ *   width: 120,
+ * });
+ *
+ * @example
+ * // Dashboard-tile look: stroke + soft gradient fill fading to transparent.
+ * charts.sparkline({ data: [3, 7, 5, 9, 12, 10, 14], area: true });
+ */
+export declare const sparkline: (opts: SparklineOptions) => string;