@loidolt/theme-charts 0.7.0

package/dist/core/builders/more.js

@@ -0,0 +1,530 @@
+import { chartColors } from '@loidolt/theme-tokens';
+import { joinList } from '../describe.js';
+import { formatCompact, formatNumber } from '../format.js';
+import { seriesColor } from '../theme.js';
+import { invariant } from '../validate.js';
+const formatter = (format) => (value) => formatNumber(value, format);
+/** The least-squares line through `points`, or `null` when it is undefined (all x equal). */
+export function linearFit(points) {
+    const n = points.length;
+    if (n < 2)
+        return null;
+    const [sumX, sumY] = points.reduce(([x, y], point) => [x + point[0], y + point[1]], [0, 0]);
+    const [meanX, meanY] = [sumX / n, sumY / n];
+    let numerator = 0;
+    let denominator = 0;
+    for (const [x, y] of points) {
+        numerator += (x - meanX) * (y - meanY);
+        denominator += (x - meanX) ** 2;
+    }
+    if (denominator === 0)
+        return null;
+    const slope = numerator / denominator;
+    return { slope, intercept: meanY - slope * meanX };
+}
+export function buildScatterOption(data, options = {}, colors = chartColors()) {
+    const { showTrendLine = false, symbolSize = 8, showLegend = data.length > 1, showTooltip = true, } = options;
+    const [formatX, formatY] = [formatter(options.xFormat), formatter(options.yFormat)];
+    const series = [];
+    data.forEach((one, index) => {
+        const color = one.color ?? seriesColor(colors, index);
+        series.push({
+            type: 'scatter',
+            name: one.name,
+            data: one.data,
+            symbolSize,
+            itemStyle: { color, opacity: 0.85 },
+            emphasis: { focus: 'series' },
+        });
+        const fit = showTrendLine ? linearFit(one.data) : null;
+        if (fit) {
+            const xs = one.data.map(([x]) => x);
+            const [low, high] = [Math.min(...xs), Math.max(...xs)];
+            series.push({
+                type: 'line',
+                name: `${one.name} trend`,
+                data: [
+                    [low, fit.intercept + fit.slope * low],
+                    [high, fit.intercept + fit.slope * high],
+                ],
+                showSymbol: false,
+                lineStyle: { color, type: 'dashed', width: 1.5 },
+                tooltip: { show: false },
+                silent: true,
+            });
+        }
+    });
+    return {
+        legend: showLegend ? { type: 'scroll', top: 0, left: 0 } : undefined,
+        tooltip: showTooltip
+            ? {
+                trigger: 'item',
+                formatter: (params) => `${params.seriesName}<br>${formatX(params.value[0])}, ${formatY(params.value[1])}`,
+            }
+            : undefined,
+        grid: { left: 8, right: 16, top: showLegend ? 40 : 16, bottom: 8, containLabel: true },
+        xAxis: {
+            type: 'value',
+            name: options.xAxisName,
+            scale: true,
+            axisLabel: { formatter: formatX },
+        },
+        yAxis: {
+            type: 'value',
+            name: options.yAxisName,
+            scale: true,
+            axisLabel: { formatter: formatY },
+        },
+        series,
+    };
+}
+export function scatterTable(data, { seriesLabel = 'Series', xLabel = 'X', yLabel = 'Y' } = {}) {
+    return {
+        columns: [seriesLabel, xLabel, yLabel],
+        rows: data.flatMap((one) => one.data.map(([x, y]) => [one.name, x, y])),
+    };
+}
+export function describeScatter(data) {
+    const points = data.reduce((sum, one) => sum + one.data.length, 0);
+    if (!points)
+        return 'Empty scatter chart.';
+    const trends = data.map((one) => {
+        const fit = linearFit(one.data);
+        const direction = !fit || fit.slope === 0
+            ? 'no clear trend'
+            : fit.slope > 0
+                ? 'y rising with x'
+                : 'y falling as x rises';
+        return `${one.name}: ${one.data.length} points, ${direction}`;
+    });
+    return `Scatter chart of ${points} points in ${data.length} series. ${trends.join('; ')}.`;
+}
+export function buildRadarOption(data, options = {}, colors = chartColors()) {
+    for (const one of data.series) {
+        invariant(one.values.length === data.indicators.length, 'buildRadarOption', `series "${one.name}" has ${one.values.length} values for ${data.indicators.length} indicators`);
+    }
+    const { shape = 'polygon', area = true, showLegend = data.series.length > 1, showTooltip = true, } = options;
+    return {
+        legend: showLegend ? { type: 'scroll', bottom: 0, left: 'center' } : undefined,
+        tooltip: showTooltip ? { trigger: 'item' } : undefined,
+        radar: {
+            shape,
+            radius: '65%',
+            indicator: data.indicators.map((indicator, index) => ({
+                name: indicator.name,
+                min: indicator.min ?? 0,
+                max: indicator.max ?? Math.max(1, ...data.series.map((one) => one.values[index] ?? 0)) * 1.1,
+            })),
+        },
+        series: [
+            {
+                type: 'radar',
+                data: data.series.map((one, index) => {
+                    const color = one.color ?? seriesColor(colors, index);
+                    return {
+                        name: one.name,
+                        value: one.values,
+                        symbol: 'rect',
+                        symbolSize: 5,
+                        itemStyle: { color },
+                        lineStyle: { color, width: 2 },
+                        areaStyle: area ? { color, opacity: 0.14 } : undefined,
+                    };
+                }),
+            },
+        ],
+    };
+}
+export function radarTable(data, indicatorLabel = 'Measure') {
+    return {
+        columns: [indicatorLabel, ...data.series.map((one) => one.name)],
+        rows: data.indicators.map((indicator, index) => [
+            indicator.name,
+            ...data.series.map((one) => one.values[index] ?? null),
+        ]),
+    };
+}
+export function describeRadar(data) {
+    if (!data.series.length)
+        return 'Empty radar chart.';
+    const strongest = data.series.map((one) => {
+        const best = one.values.indexOf(Math.max(...one.values));
+        return `${one.name} is strongest in ${data.indicators[best]?.name ?? 'none'}`;
+    });
+    return `Radar chart comparing ${data.series.length} series across ${data.indicators.length} measures. ${strongest.join('; ')}.`;
+}
+export function buildGaugeOption(data, options = {}, colors = chartColors()) {
+    const { value, min = 0, max = 100 } = data;
+    invariant(min < max, 'buildGaugeOption', `min (${min}) must be below max (${max})`);
+    invariant(Number.isFinite(value), 'buildGaugeOption', 'value must be a finite number');
+    const { splitNumber = 5, showProgress = true, valueFormat, label } = options;
+    const format = formatter(valueFormat);
+    return {
+        series: [
+            {
+                type: 'gauge',
+                min,
+                max,
+                splitNumber,
+                radius: '90%',
+                progress: { show: showProgress, width: 12, itemStyle: { color: colors.accent } },
+                axisLine: { lineStyle: { width: 12, color: [[1, colors.grid]] } },
+                axisTick: { distance: -12, length: 4, lineStyle: { color: colors.axis } },
+                splitLine: { distance: -12, length: 12, lineStyle: { color: colors.axis, width: 1 } },
+                axisLabel: { distance: 18, color: colors.muted, fontSize: 10, formatter: format },
+                pointer: {
+                    show: !showProgress,
+                    width: 4,
+                    length: '62%',
+                    itemStyle: { color: colors.text },
+                },
+                anchor: {
+                    show: !showProgress,
+                    icon: 'rect',
+                    size: 10,
+                    itemStyle: { color: colors.text, borderWidth: 0 },
+                },
+                title: {
+                    show: Boolean(label),
+                    offsetCenter: [0, '72%'],
+                    color: colors.muted,
+                    fontSize: 11,
+                },
+                detail: {
+                    valueAnimation: true,
+                    offsetCenter: [0, '40%'],
+                    color: colors.text,
+                    fontSize: 24,
+                    fontWeight: 600,
+                    formatter: format,
+                },
+                data: [{ value, name: label ?? '' }],
+            },
+        ],
+    };
+}
+export function gaugeTable(data, { readingLabel = 'Reading', valueLabel = 'Value', minLabel = 'Minimum', maxLabel = 'Maximum', } = {}) {
+    return {
+        columns: [readingLabel, valueLabel],
+        rows: [
+            [valueLabel, data.value],
+            [minLabel, data.min ?? 0],
+            [maxLabel, data.max ?? 100],
+        ],
+    };
+}
+export function describeGauge(data, format) {
+    const { value, min = 0, max = 100 } = data;
+    const share = Math.round(((value - min) / (max - min)) * 100);
+    return `Gauge reading ${formatNumber(value, format)} on a scale of ${formatNumber(min, format)} to ${formatNumber(max, format)} (${share}%).`;
+}
+export function buildHeatmapOption(data, options = {}, colors = chartColors()) {
+    for (const [x, y] of data.values) {
+        invariant(Number.isInteger(x) &&
+            Number.isInteger(y) &&
+            x >= 0 &&
+            y >= 0 &&
+            x < data.x.length &&
+            y < data.y.length, 'buildHeatmapOption', `cell [${x}, ${y}] is outside the ${data.x.length} × ${data.y.length} grid`);
+    }
+    const values = data.values
+        .map(([, , value]) => value)
+        .filter((value) => value != null);
+    const { showValues = false, showTooltip = true, showScale = true, valueFormat } = options;
+    const format = formatter(valueFormat);
+    const min = options.min ?? Math.min(0, ...values);
+    const max = options.max ?? Math.max(min + 1, ...values);
+    return {
+        tooltip: showTooltip
+            ? {
+                trigger: 'item',
+                formatter: (params) => {
+                    const [x, y, value] = params.value;
+                    return `${data.y[y]} · ${data.x[x]}<br>${format(value)}`;
+                },
+            }
+            : undefined,
+        grid: { left: 8, right: 16, top: 16, bottom: showScale ? 56 : 8, containLabel: true },
+        xAxis: { type: 'category', data: data.x, splitArea: { show: false } },
+        yAxis: { type: 'category', data: data.y, splitArea: { show: false } },
+        visualMap: {
+            min,
+            max,
+            calculable: false,
+            show: showScale,
+            orient: 'horizontal',
+            left: 'center',
+            bottom: 0,
+            itemWidth: 12,
+            formatter: format,
+            inRange: { color: colors.sequential },
+        },
+        series: [
+            {
+                type: 'heatmap',
+                data: data.values,
+                itemStyle: { borderColor: colors.surface, borderWidth: 1 },
+                label: showValues
+                    ? {
+                        show: true,
+                        fontSize: 10,
+                        formatter: (params) => format(params.value[2]),
+                    }
+                    : { show: false },
+                emphasis: { itemStyle: { borderColor: colors.text, borderWidth: 1 } },
+            },
+        ],
+    };
+}
+export function heatmapTable(data, cornerLabel = 'Row') {
+    const grid = data.y.map(() => data.x.map(() => null));
+    for (const [x, y, value] of data.values)
+        grid[y][x] = value;
+    return {
+        columns: [cornerLabel, ...data.x],
+        rows: data.y.map((label, index) => [label, ...grid[index]]),
+    };
+}
+export function describeHeatmap(data, format) {
+    let best = null;
+    let worst = null;
+    for (const [x, y, value] of data.values) {
+        if (value == null)
+            continue;
+        if (!best || value > best[2])
+            best = [x, y, value];
+        if (!worst || value < worst[2])
+            worst = [x, y, value];
+    }
+    const where = (cell) => `${formatNumber(cell[2], format)} at ${data.y[cell[1]]} · ${data.x[cell[0]]}`;
+    if (!best || !worst)
+        return 'Empty heatmap.';
+    return `Heatmap of ${data.y.length} rows by ${data.x.length} columns. Highest ${where(best)}; lowest ${where(worst)}.`;
+}
+/** A node's own value, or the sum of its children's. */
+export const nodeValue = (node) => node.value ?? (node.children ?? []).reduce((sum, child) => sum + nodeValue(child), 0);
+export function buildTreemapOption(data, options = {}, colors = chartColors()) {
+    const { showTooltip = true, showBreadcrumb = true, valueFormat } = options;
+    const format = formatter(valueFormat);
+    const colour = (nodes, depth) => nodes.map((node, index) => {
+        invariant(node.value === undefined || (Number.isFinite(node.value) && node.value >= 0), 'buildTreemapOption', `"${node.name}" must have a value of 0 or more`);
+        const color = node.color ?? (depth === 0 ? seriesColor(colors, index) : undefined);
+        return {
+            name: node.name,
+            value: nodeValue(node),
+            itemStyle: color ? { color } : undefined,
+            children: node.children ? colour(node.children, depth + 1) : undefined,
+        };
+    });
+    return {
+        tooltip: showTooltip ? { trigger: 'item', valueFormatter: format } : undefined,
+        series: [
+            {
+                type: 'treemap',
+                roam: false,
+                nodeClick: 'zoomToNode',
+                top: 8,
+                left: 0,
+                right: 0,
+                bottom: showBreadcrumb ? 32 : 0,
+                breadcrumb: {
+                    show: showBreadcrumb,
+                    itemStyle: {
+                        color: colors.surface,
+                        borderColor: colors.axis,
+                        textStyle: { color: colors.text },
+                    },
+                    emphasis: { itemStyle: { color: colors.background } },
+                },
+                label: { show: true, color: colors.surface, fontSize: 11 },
+                upperLabel: { show: false },
+                itemStyle: { borderColor: colors.surface, borderWidth: 1, gapWidth: 1 },
+                levels: [
+                    { itemStyle: { borderColor: colors.surface, borderWidth: 2, gapWidth: 2 } },
+                    { colorSaturation: [0.35, 0.6], itemStyle: { borderColorSaturation: 0.7, gapWidth: 1 } },
+                ],
+                data: colour(data, 0),
+            },
+        ],
+    };
+}
+export function treemapTable(data, { pathLabel = 'Item', valueLabel = 'Value' } = {}) {
+    const rows = [];
+    const walk = (nodes, trail) => {
+        for (const node of nodes) {
+            const path = [...trail, node.name];
+            rows.push([path.join(' › '), nodeValue(node)]);
+            if (node.children)
+                walk(node.children, path);
+        }
+    };
+    walk(data, []);
+    return { columns: [pathLabel, valueLabel], rows };
+}
+export function describeTreemap(data, format) {
+    if (!data.length)
+        return 'Empty treemap.';
+    const total = data.reduce((sum, node) => sum + nodeValue(node), 0);
+    const top = [...data]
+        .sort((a, b) => nodeValue(b) - nodeValue(a))
+        .slice(0, 3)
+        .map((node) => `${node.name} ${formatNumber(nodeValue(node), format)}`);
+    return `Treemap of ${data.length} groups totalling ${formatNumber(total, format)}. Largest: ${joinList(top)}.`;
+}
+export function buildCandlestickOption(data, options = {}, colors = chartColors()) {
+    for (const day of data) {
+        invariant(day.low <= Math.min(day.open, day.close) && day.high >= Math.max(day.open, day.close), 'buildCandlestickOption', `${day.date}: low and high must bracket open and close`);
+    }
+    const { showVolume = data.some((day) => day.volume != null), zoom = false, showTooltip = true, upColor = colors.positive, downColor = colors.negative, valueFormat, } = options;
+    const format = formatter(valueFormat);
+    const dates = data.map((day) => day.date);
+    // Price takes most of the height; volume a strip under it, above the zoom slider if any.
+    const bottom = zoom ? 48 : 8;
+    const grids = showVolume
+        ? [
+            { left: 8, right: 16, top: 16, bottom: zoom ? '38%' : '28%', containLabel: true },
+            { left: 8, right: 16, height: '16%', bottom, containLabel: true },
+        ]
+        : [{ left: 8, right: 16, top: 16, bottom, containLabel: true }];
+    const axes = showVolume ? [0, 1] : [0];
+    return {
+        tooltip: showTooltip
+            ? { trigger: 'axis', axisPointer: { type: 'cross' }, valueFormatter: format }
+            : undefined,
+        axisPointer: showVolume ? { link: [{ xAxisIndex: 'all' }] } : undefined,
+        grid: grids,
+        xAxis: axes.map((index) => ({
+            type: 'category',
+            gridIndex: index,
+            data: dates,
+            boundaryGap: true,
+            axisLabel: { show: index === axes.length - 1 },
+        })),
+        yAxis: axes.map((index) => index === 0
+            ? {
+                type: 'value',
+                gridIndex: 0,
+                scale: true,
+                splitNumber: 4,
+                axisLabel: { formatter: format },
+            }
+            : {
+                type: 'value',
+                gridIndex: 1,
+                splitNumber: 1,
+                splitLine: { show: false },
+                axisLabel: { formatter: (value) => formatCompact(value) },
+            }),
+        dataZoom: zoom
+            ? [
+                { type: 'inside', xAxisIndex: axes },
+                { type: 'slider', xAxisIndex: axes, bottom: 8, height: 24 },
+            ]
+            : undefined,
+        series: [
+            {
+                type: 'candlestick',
+                name: 'Price',
+                data: data.map((day) => [day.open, day.close, day.low, day.high]),
+                itemStyle: {
+                    color: upColor,
+                    color0: downColor,
+                    borderColor: upColor,
+                    borderColor0: downColor,
+                },
+            },
+            ...(showVolume
+                ? [
+                    {
+                        type: 'bar',
+                        name: 'Volume',
+                        xAxisIndex: 1,
+                        yAxisIndex: 1,
+                        data: data.map((day) => ({
+                            value: day.volume ?? null,
+                            itemStyle: { color: day.close >= day.open ? upColor : downColor, opacity: 0.6 },
+                        })),
+                    },
+                ]
+                : []),
+        ],
+    };
+}
+export function candlestickTable(data, { dateLabel = 'Date', openLabel = 'Open', highLabel = 'High', lowLabel = 'Low', closeLabel = 'Close', volumeLabel = 'Volume', } = {}) {
+    const volume = data.some((day) => day.volume != null);
+    return {
+        columns: [
+            dateLabel,
+            openLabel,
+            highLabel,
+            lowLabel,
+            closeLabel,
+            ...(volume ? [volumeLabel] : []),
+        ],
+        rows: data.map((day) => [
+            day.date,
+            day.open,
+            day.high,
+            day.low,
+            day.close,
+            ...(volume ? [day.volume ?? null] : []),
+        ]),
+    };
+}
+export function describeCandlestick(data, format) {
+    if (!data.length)
+        return 'Empty candlestick chart.';
+    const [first, last] = [data[0], data[data.length - 1]];
+    const high = Math.max(...data.map((day) => day.high));
+    const low = Math.min(...data.map((day) => day.low));
+    const change = first.open ? Math.round(((last.close - first.open) / first.open) * 1000) / 10 : 0;
+    return `Candlestick chart of ${data.length} periods, ${first.date} to ${last.date}. Opened at ${formatNumber(first.open, format)} and closed at ${formatNumber(last.close, format)} (${change >= 0 ? '+' : ''}${change}%), trading between ${formatNumber(low, format)} and ${formatNumber(high, format)}.`;
+}
+export function buildSankeyOption(data, options = {}, colors = chartColors()) {
+    const names = new Set(data.nodes.map((node) => node.name));
+    for (const link of data.links) {
+        invariant(names.has(link.source) && names.has(link.target), 'buildSankeyOption', `link ${link.source} → ${link.target} names a node that is not in \`nodes\``);
+        invariant(link.source !== link.target, 'buildSankeyOption', `${link.source} links to itself`);
+        invariant(link.value > 0, 'buildSankeyOption', `link ${link.source} → ${link.target} needs a positive value`);
+    }
+    const { orientation = 'horizontal', showTooltip = true, valueFormat } = options;
+    return {
+        tooltip: showTooltip ? { trigger: 'item', valueFormatter: formatter(valueFormat) } : undefined,
+        series: [
+            {
+                type: 'sankey',
+                orient: orientation,
+                left: 8,
+                right: orientation === 'horizontal' ? 96 : 8,
+                top: 8,
+                bottom: orientation === 'horizontal' ? 8 : 32,
+                nodeWidth: 12,
+                nodeGap: 10,
+                emphasis: { focus: 'adjacency' },
+                label: { color: colors.text },
+                lineStyle: { color: 'gradient', opacity: 0.35, curveness: 0.5 },
+                itemStyle: { borderWidth: 0 },
+                data: data.nodes.map((node, index) => ({
+                    name: node.name,
+                    itemStyle: { color: node.color ?? seriesColor(colors, index) },
+                })),
+                links: data.links,
+            },
+        ],
+    };
+}
+export function sankeyTable(data, { sourceLabel = 'From', targetLabel = 'To', valueLabel = 'Value' } = {}) {
+    return {
+        columns: [sourceLabel, targetLabel, valueLabel],
+        rows: data.links.map((link) => [link.source, link.target, link.value]),
+    };
+}
+export function describeSankey(data, format) {
+    if (!data.links.length)
+        return 'Empty flow diagram.';
+    const top = [...data.links]
+        .sort((a, b) => b.value - a.value)
+        .slice(0, 3)
+        .map((link) => `${link.source} to ${link.target} (${formatNumber(link.value, format)})`);
+    return `Flow diagram of ${data.links.length} flows between ${data.nodes.length} nodes. Largest: ${joinList(top)}.`;
+}

package/dist/core/builders/slices.d.ts

@@ -0,0 +1,36 @@
+import { type FormatOptions } from '../format.js';
+import type { ChartColors, ChartOption, ChartTable, SliceDatum } from '../types.js';
+export interface PieOptions {
+    /** Hole size as a percentage of the radius; above 0 draws a donut. */
+    innerRadius?: number;
+    showLabels?: boolean;
+    /** Labels on leader lines outside, or printed on the slices. */
+    labelPosition?: 'outside' | 'inside';
+    showLegend?: boolean;
+    showTooltip?: boolean;
+    /** Large text in a donut's hole, e.g. the total. */
+    centerValue?: string;
+    /** Small caption under `centerValue`. */
+    centerLabel?: string;
+    valueFormat?: FormatOptions;
+}
+/** A pie, or a donut with `innerRadius`. */
+export declare function buildPieOption(data: SliceDatum[], options?: PieOptions, colors?: ChartColors): ChartOption;
+export interface FunnelOptions {
+    /** `descending` puts the largest stage first; `none` keeps the given order. */
+    sort?: 'descending' | 'ascending' | 'none';
+    orientation?: 'vertical' | 'horizontal';
+    showLabels?: boolean;
+    showTooltip?: boolean;
+    valueFormat?: FormatOptions;
+}
+/** Stages narrowing from first to last — a conversion funnel. */
+export declare function buildFunnelOption(data: SliceDatum[], options?: FunnelOptions, colors?: ChartColors): ChartOption;
+/** The data behind a pie, donut or funnel, with each part's share of the whole. */
+export declare function sliceTable(data: SliceDatum[], { nameLabel, valueLabel, shareLabel }?: {
+    nameLabel?: string | undefined;
+    valueLabel?: string | undefined;
+    shareLabel?: string | undefined;
+}): ChartTable;
+export declare const describePie: (data: SliceDatum[], format?: FormatOptions) => string;
+export declare const describeFunnel: (data: SliceDatum[], format?: FormatOptions) => string;

package/dist/core/builders/slices.js

@@ -0,0 +1,117 @@
+import { chartColors } from '@loidolt/theme-tokens';
+import { describeSlices } from '../describe.js';
+import { formatNumber } from '../format.js';
+import { inkOn, seriesColor } from '../theme.js';
+import { invariant } from '../validate.js';
+function checkSlices(data, builder) {
+    for (const slice of data) {
+        invariant(Number.isFinite(slice.value) && slice.value >= 0, builder, `"${slice.name}" must be a finite value of 0 or more, not ${slice.value}`);
+    }
+}
+/** A pie, or a donut with `innerRadius`. */
+export function buildPieOption(data, options = {}, colors = chartColors()) {
+    checkSlices(data, 'buildPieOption');
+    const { innerRadius = 0, showLabels = true, labelPosition = 'outside', showLegend = false, showTooltip = true, centerValue, centerLabel, valueFormat, } = options;
+    invariant(innerRadius >= 0 && innerRadius < 70, 'buildPieOption', 'innerRadius is a percentage below the outer radius (0–69)');
+    const format = (value) => formatNumber(value, valueFormat);
+    const inside = labelPosition === 'inside';
+    return {
+        tooltip: showTooltip ? { trigger: 'item', valueFormatter: format } : undefined,
+        legend: showLegend ? { type: 'scroll', bottom: 0, left: 'center' } : undefined,
+        title: innerRadius > 0 && (centerValue || centerLabel)
+            ? {
+                text: centerValue,
+                subtext: centerLabel,
+                left: 'center',
+                top: 'center',
+                textStyle: { color: colors.text, fontSize: 22, fontWeight: 600 },
+                subtextStyle: { color: colors.muted, fontSize: 11 },
+                itemGap: 4,
+            }
+            : undefined,
+        series: [
+            {
+                type: 'pie',
+                radius: [`${innerRadius}%`, '70%'],
+                center: ['50%', showLegend ? '45%' : '50%'],
+                // Slices are divided by the surface colour, not an outline that competes with the data.
+                itemStyle: { borderColor: colors.surface, borderWidth: 2 },
+                label: showLabels
+                    ? {
+                        show: true,
+                        position: inside ? 'inside' : 'outside',
+                        color: colors.text,
+                        formatter: inside ? '{d}%' : '{b}',
+                    }
+                    : { show: false },
+                labelLine: { show: showLabels && !inside, lineStyle: { color: colors.axis } },
+                emphasis: { scale: true, scaleSize: 4 },
+                data: data.map((slice, index) => {
+                    const color = slice.color ?? seriesColor(colors, index);
+                    return {
+                        name: slice.name,
+                        value: slice.value,
+                        itemStyle: { color },
+                        // Text printed on a slice takes whichever ink reads on that slice.
+                        label: inside ? { color: inkOn(color, colors) } : undefined,
+                    };
+                }),
+            },
+        ],
+    };
+}
+/** Stages narrowing from first to last — a conversion funnel. */
+export function buildFunnelOption(data, options = {}, colors = chartColors()) {
+    checkSlices(data, 'buildFunnelOption');
+    const { sort = 'descending', orientation = 'vertical', showLabels = true, showTooltip = true, valueFormat, } = options;
+    const format = (value) => formatNumber(value, valueFormat);
+    const max = Math.max(0, ...data.map((slice) => slice.value));
+    return {
+        tooltip: showTooltip ? { trigger: 'item', valueFormatter: format } : undefined,
+        series: [
+            {
+                type: 'funnel',
+                sort,
+                orient: orientation,
+                min: 0,
+                max,
+                left: '10%',
+                right: '10%',
+                top: 16,
+                bottom: 16,
+                gap: 2,
+                itemStyle: { borderColor: colors.surface, borderWidth: 1 },
+                label: showLabels ? { show: true, position: 'inside', formatter: '{b}' } : { show: false },
+                data: data.map((slice, index) => {
+                    const color = slice.color ?? seriesColor(colors, index);
+                    return {
+                        name: slice.name,
+                        value: slice.value,
+                        itemStyle: { color },
+                        label: { color: inkOn(color, colors) },
+                    };
+                }),
+            },
+        ],
+    };
+}
+/** The data behind a pie, donut or funnel, with each part's share of the whole. */
+export function sliceTable(data, { nameLabel = 'Name', valueLabel = 'Value', shareLabel = 'Share' } = {}) {
+    const total = data.reduce((sum, slice) => sum + slice.value, 0);
+    return {
+        columns: [nameLabel, valueLabel, shareLabel],
+        rows: data.map((slice) => [
+            slice.name,
+            slice.value,
+            total ? `${Math.round((slice.value / total) * 1000) / 10}%` : null,
+        ]),
+    };
+}
+export const describePie = (data, format) => describeSlices(data, { kind: 'pie chart', format });
+export const describeFunnel = (data, format) => {
+    if (!data.length)
+        return 'Empty funnel chart.';
+    const [first, last] = [data[0], data[data.length - 1]];
+    const kept = first.value ? Math.round((last.value / first.value) * 100) : 0;
+    return `Funnel chart of ${data.length} stages, from ${first.name} (${formatNumber(first.value, format)}) to ${last.name} (${formatNumber(last.value, format)}): ${kept}% carried through.`;
+};