@scalewing/react 1.38.0 → 1.40.0

package/dist/chart-scale.js

@@ -0,0 +1,116 @@
+/** How many steps a value axis aims for between its ends. */
+export const chartScaleSteps = 4;
+/** The multipliers a step takes within each power of ten. */
+const niceMultipliers = [1, 2, 2.5, 5, 10];
+/**
+ * The smallest round step (1, 2, 2.5 or 5 times a power of ten) that
+ * covers `span` in at most `steps` steps.
+ */
+export function niceStep(span, steps) {
+    if (!(span > 0))
+        return 1;
+    const raw = span / steps;
+    const power = 10 ** Math.floor(Math.log10(raw));
+    for (const multiplier of niceMultipliers) {
+        const step = multiplier * power;
+        if (step >= raw * (1 - 1e-9))
+            return step;
+    }
+    return 10 * power;
+}
+/** The least and greatest of some values, both stretched to reach zero. */
+export function extentThroughZero(values) {
+    let min = 0;
+    let max = 0;
+    for (const value of values) {
+        if (value < min)
+            min = value;
+        if (value > max)
+            max = value;
+    }
+    return { min, max };
+}
+/** Rounds away the floating-point dust of a step multiple. */
+function tidy(value, step) {
+    // toFixed takes at most 100 digits.
+    const decimals = Math.min(100, Math.max(0, -Math.floor(Math.log10(step)) + 2));
+    return Number(value.toFixed(decimals)) + 0;
+}
+function scaleFrom(step, below, above) {
+    const ticks = [];
+    for (let index = -below; index <= above; index += 1)
+        ticks.push(tidy(index * step, step));
+    return {
+        min: tidy(-below * step, step),
+        max: tidy(above * step, step),
+        step,
+        ticks,
+    };
+}
+/** Whole steps below and above zero for an extent at one step. */
+function stepsAround(extent, step) {
+    return {
+        below: Math.ceil(-extent.min / step - 1e-9),
+        above: Math.ceil(extent.max / step - 1e-9),
+    };
+}
+/** A scale for an extent aiming at a number of steps. */
+function scaleAiming(extent, steps) {
+    const span = extent.max - extent.min;
+    if (span === 0)
+        return scaleFrom(1, 0, 1);
+    let step = niceStep(span, steps);
+    let { below, above } = stepsAround(extent, step);
+    // Rounding each side up can add a step; widen the step once if so.
+    if (below + above > steps + 1 && steps > 1) {
+        step = niceStep(span, steps - 1);
+        ({ below, above } = stepsAround(extent, step));
+    }
+    return scaleFrom(step, Math.max(below, 0), Math.max(above, 0));
+}
+/**
+ * A value axis for an extent through zero: a round step, and as many whole
+ * steps either side of zero as the extent needs. An extent of only zero
+ * reads 0 to 1.
+ */
+export function chartScale(extent) {
+    return scaleAiming(extent, chartScaleSteps);
+}
+/** Whole steps a scale has below and above zero. */
+function sides(scale) {
+    return {
+        below: Math.round(-scale.min / scale.step),
+        above: Math.round(scale.max / scale.step),
+    };
+}
+/**
+ * Two value axes drawn on one plot, such as columns on the left and a
+ * running total on the right: each keeps its own round step, and both have
+ * the same number of steps below and above zero, so zero and every grid
+ * line fall at the same height on both. When the two lean different ways
+ * (one mostly above zero, the other below), both take fewer, longer steps
+ * so the plot keeps about as many grid lines as one scale would.
+ */
+export function alignedChartScales(first, second) {
+    let aligned = [
+        chartScale(first),
+        chartScale(second),
+    ];
+    for (let steps = chartScaleSteps; steps >= 1; steps -= 1) {
+        const a = scaleAiming(first, steps);
+        const b = scaleAiming(second, steps);
+        const below = Math.max(sides(a).below, sides(b).below);
+        const above = Math.max(sides(a).above, sides(b).above);
+        aligned = [
+            scaleFrom(a.step, below, above),
+            scaleFrom(b.step, below, above),
+        ];
+        if (below + above <= chartScaleSteps + 1)
+            break;
+    }
+    return aligned;
+}
+/** Where a value falls on a scale, as a share from its bottom (0) to top (1). */
+export function scaleShare(value, scale) {
+    return (value - scale.min) / (scale.max - scale.min);
+}

package/dist/chart-table-rows.d.ts

@@ -0,0 +1,8 @@
+/** One row of a chart's hidden table: what it is, and each column's words. */
+export type ChartTableRow = {
+    key: string;
+    header: string;
+    cells: readonly string[];
+    /** Marks the boxed current period. */
+    current?: boolean;
+};

package/dist/chart-table-rows.js

@@ -0,0 +1 @@
+export {};

package/dist/column-chart-bars.d.ts

@@ -0,0 +1,38 @@
+import { type ChartPlot } from './chart-axis.js';
+import { type ChartScale } from './chart-scale.js';
+/** How a category's columns sit: one on another, or side by side. */
+export declare const columnChartModes: readonly ["stacked", "grouped"];
+export type ColumnChartMode = (typeof columnChartModes)[number];
+/**
+ * One series' column in one category, in values: from `low` to `high`,
+ * and which of the category's slots it takes (always 0 when stacked).
+ */
+export type ColumnSpan = {
+    series: number;
+    category: number;
+    slot: number;
+    low: number;
+    high: number;
+};
+/**
+ * Each series' column in each category, in values. Stacked, the positive
+ * values stack up from zero and the negative ones down from it, each in
+ * series order; grouped, every value runs from zero in its own slot. A
+ * zero value has no column.
+ */
+export declare function columnSpans(series: readonly (readonly number[])[], categories: number, mode: ColumnChartMode): ColumnSpan[];
+/** A drawn column: which series and category, and its box. */
+export type PlacedColumn = {
+    series: number;
+    category: number;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Each span's box: a column, or its slot in the category's group. */
+export declare function placeColumns(input: {
+    series: readonly (readonly number[])[];
+    categories: number;
+    mode: ColumnChartMode;
+}, scale: ChartScale, plot: ChartPlot, band: number): PlacedColumn[];

package/dist/column-chart-bars.js

@@ -0,0 +1,82 @@
+import { valueY } from './chart-axis.js';
+import { chartColumnGap } from './css/chart-marks.js';
+/** How a category's columns sit: one on another, or side by side. */
+export const columnChartModes = ['stacked', 'grouped'];
+/**
+ * Each series' column in each category, in values. Stacked, the positive
+ * values stack up from zero and the negative ones down from it, each in
+ * series order; grouped, every value runs from zero in its own slot. A
+ * zero value has no column.
+ */
+export function columnSpans(series, categories, mode) {
+    const spans = [];
+    for (let category = 0; category < categories; category += 1) {
+        let up = 0;
+        let down = 0;
+        series.forEach((values, index) => {
+            const value = values[category];
+            if (value === 0)
+                return;
+            if (mode === 'grouped') {
+                spans.push({
+                    series: index,
+                    category,
+                    slot: index,
+                    low: Math.min(0, value),
+                    high: Math.max(0, value),
+                });
+            }
+            else if (value > 0) {
+                spans.push({
+                    series: index,
+                    category,
+                    slot: 0,
+                    low: up,
+                    high: up + value,
+                });
+                up += value;
+            }
+            else {
+                spans.push({
+                    series: index,
+                    category,
+                    slot: 0,
+                    low: down + value,
+                    high: down,
+                });
+                down += value;
+            }
+        });
+    }
+    return spans;
+}
+/** How much of a category's width its stacked column, or its group, takes. */
+const stackedShare = 0.6;
+const groupedShare = 0.72;
+/** Each span's box: a column, or its slot in the category's group. */
+export function placeColumns(input, scale, plot, band) {
+    const slots = input.mode === 'grouped' ? input.series.length : 1;
+    const group = band * (input.mode === 'grouped' ? groupedShare : stackedShare);
+    const slot = group / slots;
+    const gap = slots > 1 ? Math.min(chartColumnGap, slot / 4) : 0;
+    return columnSpans(input.series, input.categories, input.mode).map((span) => {
+        const top = valueY(span.high, scale, plot);
+        const bottom = valueY(span.low, scale, plot);
+        // A value too small to see still shows: a column at least 1 px tall,
+        // standing on zero (or hanging from it).
+        const height = Math.max(bottom - top, 1);
+        const y = span.low < 0 && span.high <= 0 ? top : bottom - height;
+        return {
+            series: span.series,
+            category: span.category,
+            x: plot.left +
+                band * span.category +
+                (band - group) / 2 +
+                slot * span.slot +
+                gap / 2,
+            y,
+            width: slot - gap,
+            height,
+        };
+    });
+}

package/dist/column-chart-callouts.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A callout pinned above the plot: its words in a row at the top, beside a
+ * dashed leader that runs down from the row to the column it is about.
+ */
+export type PlacedCallout = {
+    /** Its place in the chart's `callouts`. */
+    order: number;
+    /** The category it is about. */
+    index: number;
+    text: string;
+    /** The leader's x, the category's centre. */
+    x: number;
+    /** The words' start (or end) and baseline. */
+    textX: number;
+    textY: number;
+    anchor: 'start' | 'end';
+    /** The leader runs from the row (`leaderStart`) down to `leaderEnd`. */
+    leaderStart: number;
+    leaderEnd: number;
+};
+/**
+ * Where a callout's words sit: after its leader in the first half of the
+ * chart and before it in the second, the side with more room. Words
+ * longer than that room are moved in so they stay inside the chart,
+ * crossing their leader.
+ */
+export declare function besideLeader(x: number, width: number, bounds: {
+    left: number;
+    right: number;
+}): {
+    anchor: 'start' | 'end';
+    textX: number;
+};
+/**
+ * Sets each callout's words beside its leader (`besideLeader`) and gives it the first row from
+ * the top where it meets no other callout's words. Returns how many rows
+ * the callouts take.
+ */
+export declare function calloutRows(callouts: readonly {
+    index: number;
+    text: string;
+}[], centre: (index: number) => number, bounds: {
+    left: number;
+    right: number;
+}): {
+    rows: number;
+    callouts: PlacedCallout[];
+};

package/dist/column-chart-callouts.js

@@ -0,0 +1,54 @@
+import { chartGap, chartInset, chartTextWidth, chartType, } from './chart-metrics.js';
+function overlaps(a, b) {
+    return a.from < b.to + chartGap && b.from < a.to + chartGap;
+}
+/**
+ * Where a callout's words sit: after its leader in the first half of the
+ * chart and before it in the second, the side with more room. Words
+ * longer than that room are moved in so they stay inside the chart,
+ * crossing their leader.
+ */
+export function besideLeader(x, width, bounds) {
+    if (x <= (bounds.left + bounds.right) / 2)
+        return {
+            anchor: 'start',
+            textX: Math.max(bounds.left, Math.min(x + chartInset, bounds.right - width)),
+        };
+    return {
+        anchor: 'end',
+        textX: Math.min(bounds.right, Math.max(x - chartInset, bounds.left + width)),
+    };
+}
+/**
+ * Sets each callout's words beside its leader (`besideLeader`) and gives it the first row from
+ * the top where it meets no other callout's words. Returns how many rows
+ * the callouts take.
+ */
+export function calloutRows(callouts, centre, bounds) {
+    const rows = [];
+    const placed = callouts.map((callout, order) => {
+        const x = centre(callout.index);
+        const width = chartTextWidth(callout.text);
+        const { anchor, textX } = besideLeader(x, width, bounds);
+        const span = anchor === 'start'
+            ? { from: Math.min(x, textX), to: textX + width }
+            : { from: textX - width, to: Math.max(x, textX) };
+        let row = rows.findIndex((taken) => !taken.some((t) => overlaps(t, span)));
+        if (row === -1)
+            row = rows.push([]) - 1;
+        rows[row].push(span);
+        const rowTop = row * chartType.lineHeight;
+        return {
+            order,
+            index: callout.index,
+            text: callout.text,
+            x,
+            textX,
+            textY: rowTop + chartType.fontSize,
+            anchor,
+            leaderStart: rowTop + chartType.lineHeight / 2,
+            leaderEnd: rowTop + chartType.lineHeight / 2,
+        };
+    });
+    return { rows: rows.length, callouts: placed };
+}

package/dist/column-chart-input.d.ts

@@ -0,0 +1,40 @@
+import { type CategoricalColor } from '@scalewing/tokens';
+import { type ColumnChartMode } from './column-chart-bars.js';
+/** One series of a column chart: a value per category, in one hue. */
+export type ColumnChartSeries = {
+    /** Stable and unique within the chart. */
+    id: string;
+    label: string;
+    values: readonly number[];
+    tone: CategoricalColor;
+};
+/** A line over the columns, on its own scale: a value per category. */
+export type ColumnChartLine = {
+    label: string;
+    values: readonly number[];
+    /** Writes the line's last value beside its axis (default `true`). */
+    endLabel?: boolean;
+};
+/** Words pinned above one category's column, such as why it stands out. */
+export type ColumnChartCallout = {
+    index: number;
+    text: string;
+    /** The hue of its words and dot; the text colour when left out. */
+    tone?: CategoricalColor;
+};
+export type ColumnChartInput = {
+    label: string;
+    categories: readonly string[];
+    series: readonly ColumnChartSeries[];
+    mode: ColumnChartMode;
+    line?: ColumnChartLine;
+    highlight?: number;
+    callouts: readonly ColumnChartCallout[];
+};
+/**
+ * Refuses what a column chart cannot draw, with a `RangeError`: empty
+ * words, a series or line without one finite value per category, a
+ * repeated series id, a tone off the categorical scale, an unknown mode,
+ * and a highlight or callout that is not a category's index.
+ */
+export declare function assertColumnChartInput(input: ColumnChartInput): void;

package/dist/column-chart-input.js

@@ -0,0 +1,60 @@
+import { isCategoricalColor } from '@scalewing/tokens';
+import { columnChartModes } from './column-chart-bars.js';
+import { isOneOf } from './is-one-of.js';
+function refuse(message) {
+    throw new RangeError(`ColumnChart ${message}`);
+}
+function assertWords(what, value) {
+    if (typeof value !== 'string' || value.trim() === '')
+        refuse(`${what} must not be empty`);
+}
+function assertValues(what, values, count) {
+    if (values.length !== count)
+        refuse(`${what} must have one value per category (${count}); received ${values.length}`);
+    for (const value of values)
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            refuse(`${what} values must be finite numbers: ${String(value)}`);
+}
+function assertIndex(what, index, count) {
+    if (!Number.isInteger(index) ||
+        index < 0 ||
+        index >= count)
+        refuse(`${what} must be a category's index, 0 to ${count - 1}: ${String(index)}`);
+}
+/**
+ * Refuses what a column chart cannot draw, with a `RangeError`: empty
+ * words, a series or line without one finite value per category, a
+ * repeated series id, a tone off the categorical scale, an unknown mode,
+ * and a highlight or callout that is not a category's index.
+ */
+export function assertColumnChartInput(input) {
+    const count = input.categories.length;
+    assertWords('label', input.label);
+    for (const category of input.categories)
+        assertWords('category', category);
+    if (!isOneOf(columnChartModes, input.mode))
+        refuse(`mode must be one of ${columnChartModes.join(', ')}; received ${String(input.mode)}`);
+    const ids = new Set();
+    for (const series of input.series) {
+        assertWords('series id', series.id);
+        if (ids.has(series.id))
+            refuse(`series id must be unique: ${series.id}`);
+        ids.add(series.id);
+        assertWords('series label', series.label);
+        assertValues(`series ${series.id}`, series.values, count);
+        if (!isCategoricalColor(series.tone))
+            refuse(`series tone must be a categorical colour: ${String(series.tone)}`);
+    }
+    if (input.line) {
+        assertWords('line label', input.line.label);
+        assertValues('line', input.line.values, count);
+    }
+    if (input.highlight !== undefined)
+        assertIndex('highlight', input.highlight, count);
+    for (const callout of input.callouts) {
+        assertIndex('callout index', callout.index, count);
+        assertWords('callout text', callout.text);
+        if (callout.tone !== undefined && !isCategoricalColor(callout.tone))
+            refuse(`callout tone must be a categorical colour: ${String(callout.tone)}`);
+    }
+}

package/dist/column-chart-layout.d.ts

@@ -0,0 +1,63 @@
+import { type ChartPlot, type ChartTick } from './chart-axis.js';
+import { type ColumnChartMode, type PlacedColumn } from './column-chart-bars.js';
+import { type PlacedCallout } from './column-chart-callouts.js';
+export type ColumnChartLayoutInput = {
+    width: number;
+    categories: readonly string[];
+    series: readonly (readonly number[])[];
+    mode: ColumnChartMode;
+    /** The line's values, and the words at its last value (or none). */
+    line: {
+        values: readonly number[];
+        endLabel: string | null;
+    } | null;
+    highlight: number | null;
+    callouts: readonly {
+        index: number;
+        text: string;
+    }[];
+    formatTick: (value: number) => string;
+};
+export type ColumnChartLayout = {
+    width: number;
+    height: number;
+    compact: boolean;
+    plot: ChartPlot;
+    ticks: ChartTick[];
+    lineTicks: ChartTick[];
+    columns: PlacedColumn[];
+    categoryLabels: {
+        index: number;
+        x: number;
+        y: number;
+        text: string;
+    }[];
+    highlight: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    } | null;
+    line: {
+        points: {
+            x: number;
+            y: number;
+        }[];
+        end: {
+            x: number;
+            y: number;
+            text: string;
+        } | null;
+    } | null;
+    callouts: PlacedCallout[];
+};
+/**
+ * Lays a column chart out at a width: its value axis on the left (and a
+ * line's own scale on the right, its zero and grid lines level with the
+ * columns'), the columns, the category labels (fewer when they would
+ * crowd), the boxed period, the line with its last value beside its axis,
+ * and the callouts pinned in rows above the plot. A compact chart (under
+ * `chartCompactWidth`) has a shorter plot and draws no callouts: they are
+ * listed under it.
+ */
+export declare function columnChartLayout(input: ColumnChartLayoutInput): ColumnChartLayout;

package/dist/column-chart-layout.js

@@ -0,0 +1,97 @@
+import { endGutter, labelGutter, labelInside, periodBox, labelledPlaces, ticksClearOf, valueTicks, valueY, } from './chart-axis.js';
+import { chartCompactWidth, chartGap, chartInset, chartPlotHeight, chartType, } from './chart-metrics.js';
+import { alignedChartScales, chartScale, extentThroughZero, } from './chart-scale.js';
+import { columnSpans, placeColumns, } from './column-chart-bars.js';
+import { calloutRows } from './column-chart-callouts.js';
+function scalesFor(input) {
+    const spans = columnSpans(input.series, input.categories.length, input.mode);
+    const columns = extentThroughZero(spans.flatMap((s) => [s.low, s.high]));
+    if (!input.line)
+        return { values: chartScale(columns), line: null };
+    const [values, line] = alignedChartScales(columns, extentThroughZero(input.line.values));
+    return { values, line };
+}
+/**
+ * Lays a column chart out at a width: its value axis on the left (and a
+ * line's own scale on the right, its zero and grid lines level with the
+ * columns'), the columns, the category labels (fewer when they would
+ * crowd), the boxed period, the line with its last value beside its axis,
+ * and the callouts pinned in rows above the plot. A compact chart (under
+ * `chartCompactWidth`) has a shorter plot and draws no callouts: they are
+ * listed under it.
+ */
+export function columnChartLayout(input) {
+    const { width, categories } = input;
+    const compact = width < chartCompactWidth;
+    const scales = scalesFor(input);
+    const tickWords = scales.values.ticks.map(input.formatTick);
+    const lineWords = scales.line ? scales.line.ticks.map(input.formatTick) : [];
+    const endLabel = input.line?.endLabel ?? null;
+    const left = labelGutter(tickWords);
+    const end = endGutter({
+        width,
+        left,
+        axisWords: scales.line ? lineWords : [],
+        endLabel: scales.line ? endLabel : null,
+    });
+    const lineWordsShown = end.axisWordsShown;
+    const rightGutter = end.gutter;
+    const right = Math.max(left + 1, width - rightGutter);
+    const band = categories.length > 0 ? (right - left) / categories.length : 0;
+    const centre = (index) => left + band * (index + 0.5);
+    const placed = compact
+        ? { rows: 0, callouts: [] }
+        : calloutRows(input.callouts, centre, { left: 0, right: width });
+    const top = placed.rows * chartType.lineHeight + chartGap + chartType.lineHeight / 2;
+    const plot = {
+        left,
+        right,
+        top,
+        bottom: top + chartPlotHeight(compact),
+    };
+    const columns = placeColumns({ series: input.series, categories: categories.length, mode: input.mode }, scales.values, plot, band);
+    const line = input.line && scales.line
+        ? input.line.values.map((value, index) => ({
+            x: centre(index),
+            y: valueY(value, scales.line, plot),
+        }))
+        : null;
+    const last = line?.at(-1);
+    const endMark = last && endLabel
+        ? { x: right + chartGap, y: last.y, text: endLabel }
+        : null;
+    const lineTicks = scales.line && lineWordsShown
+        ? valueTicks(scales.line, plot, input.formatTick)
+        : [];
+    return {
+        width,
+        height: plot.bottom + chartGap + chartType.lineHeight,
+        compact,
+        plot,
+        ticks: valueTicks(scales.values, plot, input.formatTick),
+        lineTicks: endMark ? ticksClearOf(lineTicks, endMark.y) : lineTicks,
+        columns,
+        categoryLabels: labelledPlaces(categories, band).map((index) => ({
+            index,
+            x: labelInside(centre(index), categories[index], width),
+            y: plot.bottom + chartGap + chartType.fontSize,
+            text: categories[index],
+        })),
+        highlight: input.highlight === null || categories.length === 0
+            ? null
+            : periodBox(left + band * input.highlight, band, plot),
+        line: line ? { points: line, end: endMark } : null,
+        callouts: placed.callouts.map((callout) => leaderFrom(callout, columns, plot, scales.values)),
+    };
+}
+/** A callout's leader starts just above its category's tallest column. */
+function leaderFrom(callout, columns, plot, scale) {
+    let top = valueY(0, scale, plot);
+    for (const column of columns)
+        if (column.category === callout.index)
+            top = Math.min(top, column.y);
+    return {
+        ...callout,
+        leaderEnd: Math.max(top - chartInset, callout.leaderStart),
+    };
+}

package/dist/components/BarChart.d.ts

@@ -1,5 +1,5 @@
 import { type HTMLAttributes } from 'react';
-import { type BarChartTone, barChartTones } from '../css/css-chart.js';
+import { type BarChartTone, barChartTones } from '../css/css-bar-chart.js';
 export type { BarChartTone };
 export { barChartTones };
 export type BarChartItem = {

package/dist/components/BarChart.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { barChartFillRatio, barChartScaleMax, formatBarChartValue, } from '@scalewing/tokens';
 import { forwardRef } from 'react';
 import { cx } from '../class-names.js';
-import { barChartTones } from '../css/css-chart.js';
+import { barChartTones } from '../css/css-bar-chart.js';
 export { barChartTones };
 /** The fill's classes: the sign's (which also shapes a diverging bar) and the tone's. */
 function barChartFillClassName(item) {

package/dist/components/ChartLegend.d.ts

@@ -0,0 +1,38 @@
+import { type HTMLAttributes } from 'react';
+import { type ChartFillTone, chartFillTones, type ChartStrokeTone, chartStrokeTones, type ChartTone } from '../css/chart-tones.js';
+import { type ChartLegendSwatch, chartLegendSwatches } from '../css/css-chart-legend.js';
+export type { ChartFillTone, ChartLegendSwatch, ChartStrokeTone, ChartTone };
+export { chartFillTones, chartLegendSwatches, chartStrokeTones };
+/**
+ * One item of a legend: its words and the mark they name. A `bar` is a
+ * filled mark (a column, a range bar) and takes a fill tone: a categorical
+ * colour for a chart's series, or a range bar's statement tone (`danger`
+ * is DataBar's light shortage fill: for a shortage only, never for cash
+ * leaving). A `line`,
+ * a `marker` (a downward triangle) and a `box` (the boxed current period)
+ * are drawn strokes and take a stroke tone. Each swatch is the colour of
+ * the mark it names in the same tone.
+ */
+export type ChartLegendItem = {
+    label: string;
+    swatch: 'bar';
+    tone: ChartFillTone;
+} | {
+    label: string;
+    swatch: 'line' | 'marker' | 'box';
+    tone: ChartStrokeTone;
+};
+export type ChartLegendProps = Omit<HTMLAttributes<HTMLUListElement>, 'children'> & {
+    items: readonly ChartLegendItem[];
+};
+/**
+ * A chart's key: a list of its marks, each a swatch and its words, in a
+ * wrapping row in the caption type. Put it above the chart it names, or
+ * above a statement's range bars. The swatches are decorative
+ * (`aria-hidden`), so each item reads as its words; the list keeps its
+ * list role where a style would drop it. Empty words, or a swatch or tone the
+ * item cannot draw, throw a `RangeError`.
+ */
+export declare const ChartLegend: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLUListElement>, "children"> & {
+    items: readonly ChartLegendItem[];
+} & import("react").RefAttributes<HTMLUListElement>>;