@zerodep-dev/vue-tsx-pro-ui 0.0.0-stage → 0.1.0

package/dist/charts/TreemapChart.js

@@ -0,0 +1,155 @@
+import { toNumber } from "../utils/data/numeric.js";
+import { useLang } from "../config/context.js";
+import { useFormat } from "../config/lang/format.js";
+import { Skeleton } from "../feedback/Skeleton.js";
+import { ChartFrame, chartTooltip } from "./frame.js";
+import { resolveColor, seriesValue } from "./series.js";
+import { useSingleChart } from "./single.js";
+import { computed, createVNode, mergeProps, shallowRef } from "vue";
+import { _component, bindable, readonlyProp, restProps } from "@zerodep-dev/vue-tsx-pro-tsx";
+import * as css from "@zerodep-dev/vue-tsx-pro-tsx/styles";
+import { Treemap } from "@unovis/ts";
+//#region src/charts/TreemapChart.tsx
+/**
+* 矩形树图：一个总量按层级分块（销售额按区域 → 供应商、费用按科目），块的面积是数值，一眼看出谁占得多。
+*
+*   <TreemapChart
+*     aria-label="采购额构成"
+*     data={savings}
+*     groups={['region', 'supplier']}     // 从外到内的层级
+*     value="amount"
+*     unit="万元"
+*   />
+*
+* 数据是扁平的明细，按 groups 的字段逐级分组（Unovis 的 Treemap）；同一个顶层分组同一种颜色（按色板），
+* 里面的块按亮度区分；点图例隐藏一个顶层分组，占比按剩下的算。悬停看路径、数值与占比；读屏的数据表列出每一块。
+*/
+/** 未声明的属性落到外层 div（role="figure"）上；aria-label 是图表的名称 */
+/** TreemapChart 的样式 */
+var treemapChartStyles = css.create({ skeleton: {
+	display: "block",
+	width: "100%",
+	height: "100%"
+} });
+/** 矩形树图 */
+var TreemapChart = /*#__PURE__*/ _component((_props, _ctx) => {
+	const _cache = [];
+	const data = readonlyProp(_props, "data");
+	const groups = readonlyProp(_props, "groups");
+	const value = readonlyProp(_props, "value");
+	const valueFormat = readonlyProp(_props, "valueFormat");
+	const unit = readonlyProp(_props, "unit");
+	const height = readonlyProp(_props, "height", 300);
+	const groupLabels = readonlyProp(_props, "groupLabels", false);
+	const hiddenGroups = bindable(_props, "_hiddenGroups", () => [], _ctx.emit);
+	const loading = readonlyProp(_props, "loading", false);
+	const empty = readonlyProp(_props, "empty");
+	const tooltip = readonlyProp(_props, "tooltip", true);
+	const rest = restProps(_props, _ctx, true);
+	const lang = useLang();
+	const format = useFormat();
+	const numberOf = (row) => {
+		const amount = seriesValue(row, value.value);
+		return amount === void 0 ? 0 : Math.max(toNumber(amount), 0);
+	};
+	const topOf = (row) => String(row[groups.value[0]] ?? "");
+	const visible = computed(() => data.value.filter((row) => !hiddenGroups.value.includes(topOf(row))));
+	const total = computed(() => visible.value.reduce((sum, row) => sum + numberOf(row), 0));
+	const topColors = computed(() => new Map([...new Set(data.value.map(topOf))].map((key, position) => [key, resolveColor(void 0, position)])));
+	const valueText = (amount) => format.number(amount, unit.value ? {
+		...valueFormat.value,
+		suffix: unit.value
+	} : valueFormat.value);
+	const shareText = (amount) => total.value === 0 ? lang.emptyValue : format.number(amount / total.value, {
+		style: "percent",
+		maximumFractionDigits: 1
+	});
+	/** 一个节点的路径：从顶层到它 */
+	const pathOf = (node) => node.ancestors().reverse().slice(1).map((item) => item.data.key ?? "").join(" / ");
+	function toggle(key) {
+		hiddenGroups.value = hiddenGroups.value.includes(key) ? hiddenGroups.value.filter((item) => item !== key) : [...hiddenGroups.value, key];
+	}
+	let plot = shallowRef(null);
+	const chart = useSingleChart(() => ({
+		element: plot.value,
+		ready: !loading.value && visible.value.length > 0,
+		tooltip: tooltip.value,
+		build: (instance) => {
+			const treemap = instance("treemap", () => new Treemap({ layers: [] }));
+			treemap.setConfig({
+				value: numberOf,
+				layers: groups.value.map((key) => (row) => String(row[key] ?? "")),
+				tileColor: (node) => {
+					const base = topColors.value.get(node.topLevelParent?.data.key ?? "") ?? resolveColor(void 0, 0);
+					return node.children ? `color-mix(in srgb, ${base} 18%, transparent)` : base;
+				},
+				tileLabel: (node) => node.data.key ?? "",
+				labelInternalNodes: groupLabels.value,
+				enableTileLabelFontSizeVariation: false,
+				tilePadding: 3,
+				tilePaddingTop: groupLabels.value ? 20 : void 0,
+				tileBorderRadius: 4
+			});
+			return {
+				component: treemap,
+				data: [...visible.value],
+				triggers: { [Treemap.selectors.tile]: (node) => chart.tooltip(chartTooltip(pathOf(node), [{
+					label: lang.chartValue,
+					color: topColors.value.get(node.topLevelParent?.data.key ?? "") ?? "transparent",
+					value: valueText(node.value)
+				}, {
+					label: lang.chartShare,
+					color: "transparent",
+					value: shareText(node.value)
+				}])) }
+			};
+		}
+	}));
+	return () => createVNode(ChartFrame, mergeProps(rest, {
+		"unit": unit.value,
+		"height": height.value,
+		"legend": [...topColors.value].map(([key, color]) => ({
+			key,
+			label: key,
+			color
+		})),
+		"hiddenKeys": hiddenGroups.value,
+		"onLegendToggle": toggle,
+		"loading": loading.value,
+		"skeleton": createVNode(Skeleton, { "sx": treemapChartStyles.skeleton }, null),
+		"isEmpty": data.value.length === 0,
+		"empty": empty.value,
+		"table": {
+			columns: [
+				lang.chartCategory,
+				unit.value ? `${lang.chartValue}（${unit.value}）` : lang.chartValue,
+				lang.chartShare
+			],
+			rows: visible.value.map((row) => ({
+				header: groups.value.map((key) => String(row[key] ?? "")).join(" / "),
+				cells: [valueText(seriesValue(row, value.value) ?? 0), shareText(numberOf(row))]
+			}))
+		},
+		"plotRef": _cache[0] || (_cache[0] = (element) => plot.value = element)
+	}), null);
+}, {
+	name: "TreemapChart",
+	props: [
+		"data",
+		"groups",
+		"value",
+		"valueFormat",
+		"unit",
+		"height",
+		"groupLabels",
+		"_hiddenGroups",
+		"onUpdate:_hiddenGroups",
+		"loading",
+		"empty",
+		"tooltip"
+	]
+});
+//#endregion
+export { TreemapChart, treemapChartStyles };
+
+//# sourceMappingURL=TreemapChart.js.map

package/dist/charts/TreemapChart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreemapChart.js","names":["_vtp_readonlyProp","_vtp_bindable","_vtp_restProps","_vue_computed","_vue_shallowRef","_createVNode","_mergeProps"],"sources":["../../src/charts/TreemapChart.tsx"],"sourcesContent":["/**\n * 矩形树图：一个总量按层级分块（销售额按区域 → 供应商、费用按科目），块的面积是数值，一眼看出谁占得多。\n *\n *   <TreemapChart\n *     aria-label=\"采购额构成\"\n *     data={savings}\n *     groups={['region', 'supplier']}     // 从外到内的层级\n *     value=\"amount\"\n *     unit=\"万元\"\n *   />\n *\n * 数据是扁平的明细，按 groups 的字段逐级分组（Unovis 的 Treemap）；同一个顶层分组同一种颜色（按色板），\n * 里面的块按亮度区分；点图例隐藏一个顶层分组，占比按剩下的算。悬停看路径、数值与占比；读屏的数据表列出每一块。\n */\nimport { Treemap, type TreemapNode } from '@unovis/ts';\nimport { _component } from '@zerodep-dev/vue-tsx-pro-tsx';\nimport * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';\nimport type { VNodeChild } from 'vue';\nimport { useLang } from '../config/context';\nimport { useFormat, type NumericFormat } from '../config/lang/format';\nimport { Skeleton } from '../feedback/Skeleton';\nimport { toNumber, type NumericValue } from '../utils/data/numeric';\nimport type { PartProps } from '../utils/props';\nimport { chartTooltip, ChartFrame, type ChartFrameParts } from './frame';\nimport { resolveColor, seriesValue, type NumericKey } from './series';\nimport { useSingleChart, type SingleChart } from './single';\n\n/** 未声明的属性落到外层 div（role=\"figure\"）上；aria-label 是图表的名称 */\nexport interface TreemapChartProps<T extends object>\n  extends PartProps<'div', 'role' | 'aria-busy'>, ChartFrameParts {\n  /** 明细 */\n  data: readonly T[];\n  /** 分组的字段，从外到内（区域、供应商） */\n  groups: readonly (keyof T & string)[];\n  /** 面积的数值字段 */\n  value: NumericKey<T>;\n  /** 数值的格式 */\n  valueFormat?: NumericFormat;\n  /** 单位：显示在左上方，提示框与数据表的数值后面带上 */\n  unit?: string;\n  /**\n   * 绘图区的高度；数字按 px\n   * @default 300\n   */\n  height?: number | string;\n  /** 外层分组也写名字（块够大时） */\n  groupLabels?: boolean;\n  /** 隐藏的顶层分组：点图例时写回，父级可以写 _hiddenGroups={keys} */\n  _hiddenGroups?: string[];\n  /** 加载中：绘图区显示骨架 */\n  loading?: boolean;\n  /** 没有数据时显示的内容 */\n  empty?: VNodeChild;\n  /** 悬停时的提示框，默认 true */\n  tooltip?: boolean;\n}\n\n/** TreemapChart 的样式 */\nexport const treemapChartStyles = css.create({\n  skeleton: { display: 'block', width: '100%', height: '100%' },\n});\n\n/** 矩形树图 */\nexport const TreemapChart = _component(\n  <T extends object>({\n    data,\n    groups,\n    value,\n    valueFormat,\n    unit,\n    height = 300,\n    groupLabels = false,\n    _hiddenGroups: hiddenGroups = _bindable<string[]>([]),\n    loading = false,\n    empty,\n    tooltip = true,\n    ...rest\n  }: TreemapChartProps<T>) => {\n    const lang = useLang();\n    const format = useFormat();\n    const numberOf = (row: T) => {\n      const amount = seriesValue(row, value);\n      return amount === undefined ? 0 : Math.max(toNumber(amount), 0);\n    };\n    const topOf = (row: T) => String(row[groups[0]!] ?? '');\n    const visible = _derived(data.filter((row) => !hiddenGroups.includes(topOf(row))));\n    const total = _derived(visible.reduce((sum, row) => sum + numberOf(row), 0));\n    // 顶层分组的颜色：按第一次出现的顺序取色板\n    const topColors = _derived(\n      new Map(\n        [...new Set(data.map(topOf))].map((key, position) => [\n          key,\n          resolveColor(undefined, position),\n        ]),\n      ),\n    );\n    const valueText = (amount: NumericValue) =>\n      format.number(amount, unit ? { ...valueFormat, suffix: unit } : valueFormat);\n    const shareText = (amount: number) =>\n      total === 0\n        ? lang.emptyValue\n        : format.number(amount / total, { style: 'percent', maximumFractionDigits: 1 });\n    /** 一个节点的路径：从顶层到它 */\n    const pathOf = (node: TreemapNode<T>) =>\n      node\n        .ancestors()\n        .reverse()\n        .slice(1)\n        .map((item) => item.data.key ?? '')\n        .join(' / ');\n\n    function toggle(key: string) {\n      hiddenGroups = hiddenGroups.includes(key)\n        ? hiddenGroups.filter((item) => item !== key)\n        : [...hiddenGroups, key];\n    }\n\n    let plot = _state.raw<HTMLElement | null>(null);\n    const chart: SingleChart = useSingleChart<T[]>(() => ({\n      element: plot,\n      ready: !loading && visible.length > 0,\n      tooltip,\n      build: (instance) => {\n        const treemap = instance('treemap', () => new Treemap<T>({ layers: [] }));\n        treemap.setConfig({\n          value: numberOf,\n          layers: groups.map((key) => (row: T) => String(row[key] ?? '')),\n          // 外层分组是浅色的底，叶子是实色：同一组里的块靠底色的缝隙分开\n          tileColor: (node) => {\n            const base =\n              topColors.get(node.topLevelParent?.data.key ?? '') ?? resolveColor(undefined, 0);\n            return node.children ? `color-mix(in srgb, ${base} 18%, transparent)` : base;\n          },\n          tileLabel: (node) => node.data.key ?? '',\n          labelInternalNodes: groupLabels,\n          enableTileLabelFontSizeVariation: false,\n          tilePadding: 3,\n          // 分组的名字写在顶边留出的地方\n          tilePaddingTop: groupLabels ? 20 : undefined,\n          tileBorderRadius: 4,\n        });\n        return {\n          component: treemap,\n          data: [...visible],\n          triggers: {\n            [Treemap.selectors.tile]: (node: TreemapNode<T>) =>\n              chart.tooltip(\n                chartTooltip(pathOf(node), [\n                  {\n                    label: lang.chartValue,\n                    color: topColors.get(node.topLevelParent?.data.key ?? '') ?? 'transparent',\n                    value: valueText(node.value),\n                  },\n                  { label: lang.chartShare, color: 'transparent', value: shareText(node.value) },\n                ]),\n              ),\n          },\n        };\n      },\n    }));\n\n    return () => (\n      <ChartFrame\n        {...rest}\n        unit={unit}\n        height={height}\n        legend={[...topColors].map(([key, color]) => ({ key, label: key, color }))}\n        hiddenKeys={hiddenGroups}\n        onLegendToggle={toggle}\n        loading={loading}\n        skeleton={<Skeleton sx={treemapChartStyles.skeleton} />}\n        isEmpty={data.length === 0}\n        empty={empty}\n        table={{\n          columns: [\n            lang.chartCategory,\n            unit ? `${lang.chartValue}（${unit}）` : lang.chartValue,\n            lang.chartShare,\n          ],\n          rows: visible.map((row) => ({\n            header: groups.map((key) => String(row[key] ?? '')).join(' / '),\n            cells: [valueText(seriesValue(row, value) ?? 0), shareText(numberOf(row))],\n          })),\n        }}\n        plotRef={(element) => (plot = element)}\n      />\n    );\n  },\n);\n"],"mappings":"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"}

package/dist/charts/WaterfallChart.d.ts

@@ -0,0 +1,61 @@
+import { type NumericValue } from '../utils/data/numeric';
+import { type ChartColor } from './series';
+import { type XYChartProps } from './XYChart';
+/** 瀑布图的一步 */
+export interface WaterfallStep {
+    /** 名称：类目轴的刻度 */
+    label: string;
+    /** 这一步的变动；合计柱写了时是新的累计（作为之后的起点） */
+    value?: NumericValue;
+    /** 合计柱：从 0 画到当时的累计 */
+    total?: boolean;
+}
+/** 画图用的一行（waterfallRows 算出）：柱子从 low 画到 high；跨过 0 的分成正负两段（Unovis 的堆叠正负分开叠） */
+export interface WaterfallRow {
+    /** 名称 */
+    label: string;
+    /** 这一步的种类：决定颜色 */
+    kind: 'increase' | 'decrease' | 'total';
+    /** 这一步的变动（原值，提示框与数据表按它格式化） */
+    change: NumericValue | undefined;
+    /** 这一步之后的累计 */
+    cumulative: number;
+    /** 透明的垫底：柱子悬在上一步的累计处 */
+    base: number;
+    /** 看得见的一段 */
+    bar: number;
+    /** 跨过 0 时负的那一段 */
+    below: number;
+    /** 柱子的下沿 */
+    low: number;
+    /** 柱子的上沿 */
+    high: number;
+}
+/** 未声明的属性落到外层 div（role="figure"）上；aria-label 是图表的名称 */
+export interface WaterfallChartProps extends Omit<XYChartProps<WaterfallRow>, 'data' | 'index' | 'series' | 'indexFormat' | 'legend' | 'hiddenSeries' | 'onItemClick'> {
+    /** 各步：按顺序从左到右 */
+    steps: readonly WaterfallStep[];
+    /** 往上走的颜色，默认 success */
+    increaseColor?: ChartColor;
+    /** 往下走的颜色，默认 danger */
+    decreaseColor?: ChartColor;
+    /** 合计柱的颜色，默认 chart1 */
+    totalColor?: ChartColor;
+    /**
+     * 柱子末端的圆角（px）
+     * @default 2
+     */
+    radius?: number;
+    /**
+     * 数值轴从 0 起；false 时从接近最低的累计处起：合计很大、各步变动很小时变动也看得清
+     * （合计柱被截短，读数看轴上的刻度）。写了 valueDomain 时以它为准
+     * @default true
+     */
+    fromZero?: boolean;
+    /** 点了一步（下钻）：参数是这一步与它的位置；写了它时指针是手形 */
+    onItemClick?: (step: WaterfallStep, index: number) => void;
+}
+/** 各步算成画图用的行：累计、每根柱子的上下沿 */
+export declare function waterfallRows(steps: readonly WaterfallStep[]): WaterfallRow[];
+/** 瀑布图 */
+export declare const WaterfallChart: import("@zerodep-dev/vue-tsx-pro-tsx").TsxComponent<WaterfallChartProps>;

package/dist/charts/WaterfallChart.js

@@ -0,0 +1,167 @@
+import { toNumber } from "../utils/data/numeric.js";
+import { useLang } from "../config/context.js";
+import { useFormat } from "../config/lang/format.js";
+import { useChartValueText } from "./frame.js";
+import { resolveColor } from "./series.js";
+import { XYChart } from "./XYChart.js";
+import { computed, createVNode, mergeProps } from "vue";
+import { _component, readonlyProp, restProps } from "@zerodep-dev/vue-tsx-pro-tsx";
+import { StackedBar } from "@unovis/ts";
+//#region src/charts/WaterfallChart.tsx
+/**
+* 瀑布图：从起点出发，一步步加减到终点，看总数是怎么变过来的（测算两版之间各参数的影响、预算到实际的差异拆解）。
+*
+*   <WaterfallChart
+*     aria-label="V1 到 V2 的变化"
+*     steps={[
+*       { label: 'V1 测算', value: 120, total: true },
+*       { label: '材料单价', value: -18 },
+*       { label: '工时', value: 6.5 },
+*       { label: 'V2 测算', total: true },
+*     ]}
+*     unit="万元"
+*   />
+*
+* 每一步是 { label, value }：value 是这一步的变动（正数往上、负数往下），可以是 Decimal、bigint；
+* total: true 的是合计柱，从 0 画到当时的累计（写了 value 时以它为准，作为新的起点，如“V1 测算”）。
+* 往上的步用 success 色、往下的用 danger 色、合计用 chart1（increaseColor、decreaseColor、totalColor 可改：
+* 成本类的图里减少是好事时对调）。提示框与读屏的数据表列出变动与累计。
+* 坐标轴、目标线、下钻、加载与空状态同 BarChart（见 XYChart）。
+*/
+/** 瀑布图的一步 */
+/** 画图用的一行（waterfallRows 算出）：柱子从 low 画到 high；跨过 0 的分成正负两段（Unovis 的堆叠正负分开叠） */
+/** 未声明的属性落到外层 div（role="figure"）上；aria-label 是图表的名称 */
+/** 各步算成画图用的行：累计、每根柱子的上下沿 */
+function waterfallRows(steps) {
+	let running = 0;
+	return steps.map((step) => {
+		const before = step.total ? 0 : running;
+		if (step.total) running = step.value === void 0 ? running : toNumber(step.value);
+		else running += step.value === void 0 ? 0 : toNumber(step.value);
+		const [low, high] = before <= running ? [before, running] : [running, before];
+		const crosses = low < 0 && high > 0;
+		const base = crosses ? 0 : high <= 0 ? high : low;
+		const bar = crosses ? high : high <= 0 ? low - high : high - low;
+		return {
+			label: step.label,
+			kind: step.total ? "total" : running >= before ? "increase" : "decrease",
+			change: step.value,
+			cumulative: running,
+			base,
+			bar,
+			below: crosses ? low : 0,
+			low,
+			high
+		};
+	});
+}
+/** 瀑布图 */
+var WaterfallChart = /*#__PURE__*/ _component((_props, _ctx) => {
+	const steps = readonlyProp(_props, "steps");
+	const increaseColor = readonlyProp(_props, "increaseColor");
+	const decreaseColor = readonlyProp(_props, "decreaseColor");
+	const totalColor = readonlyProp(_props, "totalColor");
+	const radius = readonlyProp(_props, "radius", 2);
+	const fromZero = readonlyProp(_props, "fromZero", true);
+	const onItemClick = readonlyProp(_props, "onItemClick");
+	const rest = restProps(_props, _ctx, true);
+	const lang = useLang();
+	const format = useFormat();
+	const valueText = useChartValueText(() => ({
+		valueFormat: rest.valueFormat,
+		unit: rest.unit
+	}));
+	const rows = computed(() => waterfallRows(steps.value));
+	const colorOf = (row) => resolveColor(row.kind === "total" ? totalColor.value ?? "chart1" : row.kind === "increase" ? increaseColor.value ?? "success" : decreaseColor.value ?? "danger", 0);
+	/** 变动：带正负号；suffix 时数值后面带单位（提示框） */
+	const changeText = (row, suffix = false) => row.change === void 0 ? lang.emptyValue : format.number(row.change, {
+		...rest.valueFormat,
+		signDisplay: "exceptZero",
+		...suffix && rest.unit ? { suffix: rest.unit } : {}
+	});
+	const cumulativeText = (row) => format.number(row.cumulative, rest.valueFormat);
+	const kind = computed(() => ({
+		skeleton: "bars",
+		stacked: true,
+		domainValues: (list) => list.flatMap((row) => [row.low, row.high]),
+		itemSelector: StackedBar.selectors.bar,
+		components: ({ x, instance, events }) => {
+			const bars = instance("waterfall", () => new StackedBar({
+				x,
+				y: []
+			}));
+			bars.setConfig({
+				x,
+				y: [
+					(row) => row.base,
+					(row) => row.bar,
+					(row) => row.below
+				],
+				color: (row, position) => position === 0 ? "transparent" : colorOf(row),
+				roundedCorners: radius.value,
+				barPadding: .3,
+				barMaxWidth: 56,
+				events
+			});
+			return [bars];
+		},
+		tooltipItems: (row) => [{
+			label: row.kind === "total" ? lang.chartTotal : lang.chartChange,
+			color: colorOf(row),
+			value: row.kind === "total" ? valueText(row.cumulative) : changeText(row, true)
+		}, ...row.kind === "total" ? [] : [{
+			label: lang.chartCumulative,
+			color: "transparent",
+			value: valueText(row.cumulative)
+		}]],
+		table: (list) => ({
+			columns: [
+				lang.chartCategory,
+				rest.unit ? `${lang.chartChange}（${rest.unit}）` : lang.chartChange,
+				rest.unit ? `${lang.chartCumulative}（${rest.unit}）` : lang.chartCumulative
+			],
+			rows: list.map((row) => ({
+				header: row.label,
+				cells: [row.kind === "total" ? lang.emptyValue : changeText(row), cumulativeText(row)]
+			}))
+		})
+	}));
+	/**
+	* 不从 0 起时轴的下沿：最低的累计再往下留出变动幅度的一半（没有变动时留出它的一成）；
+	* 有负的累计时仍按数据自动取，不截
+	*/
+	const zoomedDomain = () => {
+		const values = rows.value.flatMap((row) => row.kind === "total" ? [row.high] : [row.low, row.high]);
+		const low = Math.min(...values);
+		if (low <= 0) return [void 0, void 0];
+		const span = Math.max(...values) - low || low * .1;
+		return [Math.max(0, low - span * .5), void 0];
+	};
+	return () => createVNode(XYChart, mergeProps(rest, {
+		"valueDomain": rest.valueDomain ?? (fromZero.value || rows.value.length === 0 ? void 0 : zoomedDomain()),
+		"data": rows.value,
+		"index": "label",
+		"series": [{
+			key: "bar",
+			label: lang.chartChange
+		}],
+		"legend": false,
+		"kind": kind.value,
+		"onItemClick": onItemClick.value && ((_row, position) => onItemClick.value(steps.value[position], position))
+	}), null);
+}, {
+	name: "WaterfallChart",
+	props: [
+		"steps",
+		"increaseColor",
+		"decreaseColor",
+		"totalColor",
+		"radius",
+		"fromZero",
+		"onItemClick"
+	]
+});
+//#endregion
+export { WaterfallChart, waterfallRows };
+
+//# sourceMappingURL=WaterfallChart.js.map

package/dist/charts/WaterfallChart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WaterfallChart.js","names":["_vtp_readonlyProp","_vtp_restProps","_vue_computed","_createVNode","_mergeProps"],"sources":["../../src/charts/WaterfallChart.tsx"],"sourcesContent":["/**\n * 瀑布图：从起点出发，一步步加减到终点，看总数是怎么变过来的（测算两版之间各参数的影响、预算到实际的差异拆解）。\n *\n *   <WaterfallChart\n *     aria-label=\"V1 到 V2 的变化\"\n *     steps={[\n *       { label: 'V1 测算', value: 120, total: true },\n *       { label: '材料单价', value: -18 },\n *       { label: '工时', value: 6.5 },\n *       { label: 'V2 测算', total: true },\n *     ]}\n *     unit=\"万元\"\n *   />\n *\n * 每一步是 { label, value }：value 是这一步的变动（正数往上、负数往下），可以是 Decimal、bigint；\n * total: true 的是合计柱，从 0 画到当时的累计（写了 value 时以它为准，作为新的起点，如“V1 测算”）。\n * 往上的步用 success 色、往下的用 danger 色、合计用 chart1（increaseColor、decreaseColor、totalColor 可改：\n * 成本类的图里减少是好事时对调）。提示框与读屏的数据表列出变动与累计。\n * 坐标轴、目标线、下钻、加载与空状态同 BarChart（见 XYChart）。\n */\nimport { StackedBar } from '@unovis/ts';\nimport { _component } from '@zerodep-dev/vue-tsx-pro-tsx';\nimport { useLang } from '../config/context';\nimport { useFormat } from '../config/lang/format';\nimport { toNumber, type NumericValue } from '../utils/data/numeric';\nimport { useChartValueText } from './frame';\nimport { resolveColor, type ChartColor } from './series';\nimport { XYChart, type XYChartKind, type XYChartProps } from './XYChart';\n\n/** 瀑布图的一步 */\nexport interface WaterfallStep {\n  /** 名称：类目轴的刻度 */\n  label: string;\n  /** 这一步的变动；合计柱写了时是新的累计（作为之后的起点） */\n  value?: NumericValue;\n  /** 合计柱：从 0 画到当时的累计 */\n  total?: boolean;\n}\n\n/** 画图用的一行（waterfallRows 算出）：柱子从 low 画到 high；跨过 0 的分成正负两段（Unovis 的堆叠正负分开叠） */\nexport interface WaterfallRow {\n  /** 名称 */\n  label: string;\n  /** 这一步的种类：决定颜色 */\n  kind: 'increase' | 'decrease' | 'total';\n  /** 这一步的变动（原值，提示框与数据表按它格式化） */\n  change: NumericValue | undefined;\n  /** 这一步之后的累计 */\n  cumulative: number;\n  /** 透明的垫底：柱子悬在上一步的累计处 */\n  base: number;\n  /** 看得见的一段 */\n  bar: number;\n  /** 跨过 0 时负的那一段 */\n  below: number;\n  /** 柱子的下沿 */\n  low: number;\n  /** 柱子的上沿 */\n  high: number;\n}\n\n/** 未声明的属性落到外层 div（role=\"figure\"）上；aria-label 是图表的名称 */\nexport interface WaterfallChartProps extends Omit<\n  XYChartProps<WaterfallRow>,\n  'data' | 'index' | 'series' | 'indexFormat' | 'legend' | 'hiddenSeries' | 'onItemClick'\n> {\n  /** 各步：按顺序从左到右 */\n  steps: readonly WaterfallStep[];\n  /** 往上走的颜色，默认 success */\n  increaseColor?: ChartColor;\n  /** 往下走的颜色，默认 danger */\n  decreaseColor?: ChartColor;\n  /** 合计柱的颜色，默认 chart1 */\n  totalColor?: ChartColor;\n  /**\n   * 柱子末端的圆角（px）\n   * @default 2\n   */\n  radius?: number;\n  /**\n   * 数值轴从 0 起；false 时从接近最低的累计处起：合计很大、各步变动很小时变动也看得清\n   * （合计柱被截短，读数看轴上的刻度）。写了 valueDomain 时以它为准\n   * @default true\n   */\n  fromZero?: boolean;\n  /** 点了一步（下钻）：参数是这一步与它的位置；写了它时指针是手形 */\n  onItemClick?: (step: WaterfallStep, index: number) => void;\n}\n\n/** 各步算成画图用的行：累计、每根柱子的上下沿 */\nexport function waterfallRows(steps: readonly WaterfallStep[]): WaterfallRow[] {\n  let running = 0;\n  return steps.map((step) => {\n    const before = step.total ? 0 : running;\n    if (step.total) running = step.value === undefined ? running : toNumber(step.value);\n    else running += step.value === undefined ? 0 : toNumber(step.value);\n    const [low, high] = before <= running ? [before, running] : [running, before];\n    // 不跨 0：透明的一段垫到较近 0 的一端，看得见的一段补到另一端；跨 0：正负各一段，不垫底\n    const crosses = low < 0 && high > 0;\n    const base = crosses ? 0 : high <= 0 ? high : low;\n    const bar = crosses ? high : high <= 0 ? low - high : high - low;\n    return {\n      label: step.label,\n      kind: step.total ? 'total' : running >= before ? 'increase' : 'decrease',\n      change: step.value,\n      cumulative: running,\n      base,\n      bar,\n      below: crosses ? low : 0,\n      low,\n      high,\n    };\n  });\n}\n\n/** 瀑布图 */\nexport const WaterfallChart = _component(\n  ({\n    steps,\n    increaseColor,\n    decreaseColor,\n    totalColor,\n    radius = 2,\n    fromZero = true,\n    onItemClick,\n    ...rest\n  }: WaterfallChartProps) => {\n    const lang = useLang();\n    const format = useFormat();\n    const valueText = useChartValueText(() => ({ valueFormat: rest.valueFormat, unit: rest.unit }));\n    const rows = _derived(waterfallRows(steps));\n    const colorOf = (row: WaterfallRow) =>\n      resolveColor(\n        row.kind === 'total'\n          ? (totalColor ?? 'chart1')\n          : row.kind === 'increase'\n            ? (increaseColor ?? 'success')\n            : (decreaseColor ?? 'danger'),\n        0,\n      );\n    /** 变动：带正负号；suffix 时数值后面带单位（提示框） */\n    const changeText = (row: WaterfallRow, suffix = false) =>\n      row.change === undefined\n        ? lang.emptyValue\n        : format.number(row.change, {\n            ...rest.valueFormat,\n            signDisplay: 'exceptZero',\n            ...(suffix && rest.unit ? { suffix: rest.unit } : {}),\n          });\n    const cumulativeText = (row: WaterfallRow) => format.number(row.cumulative, rest.valueFormat);\n\n    const kind = _derived<XYChartKind<WaterfallRow>>({\n      skeleton: 'bars',\n      stacked: true,\n      domainValues: (list) => list.flatMap((row) => [row.low, row.high]),\n      itemSelector: StackedBar.selectors.bar,\n      components: ({ x, instance, events }) => {\n        const bars = instance('waterfall', () => new StackedBar<WaterfallRow>({ x, y: [] }));\n        bars.setConfig({\n          x,\n          y: [(row) => row.base, (row) => row.bar, (row) => row.below],\n          // 垫底的一段透明：看起来柱子悬在上一步的累计处\n          color: (row: WaterfallRow, position: number) =>\n            position === 0 ? 'transparent' : colorOf(row),\n          roundedCorners: radius,\n          barPadding: 0.3,\n          barMaxWidth: 56,\n          events,\n        });\n        return [bars];\n      },\n      tooltipItems: (row) => [\n        {\n          label: row.kind === 'total' ? lang.chartTotal : lang.chartChange,\n          color: colorOf(row),\n          value: row.kind === 'total' ? valueText(row.cumulative) : changeText(row, true),\n        },\n        ...(row.kind === 'total'\n          ? []\n          : [\n              {\n                label: lang.chartCumulative,\n                color: 'transparent',\n                value: valueText(row.cumulative),\n              },\n            ]),\n      ],\n      table: (list) => ({\n        columns: [\n          lang.chartCategory,\n          rest.unit ? `${lang.chartChange}（${rest.unit}）` : lang.chartChange,\n          rest.unit ? `${lang.chartCumulative}（${rest.unit}）` : lang.chartCumulative,\n        ],\n        rows: list.map((row) => ({\n          header: row.label,\n          cells: [row.kind === 'total' ? lang.emptyValue : changeText(row), cumulativeText(row)],\n        })),\n      }),\n    });\n\n    /**\n     * 不从 0 起时轴的下沿：最低的累计再往下留出变动幅度的一半（没有变动时留出它的一成）；\n     * 有负的累计时仍按数据自动取，不截\n     */\n    const zoomedDomain = (): [number | undefined, undefined] => {\n      const values = rows.flatMap((row) =>\n        row.kind === 'total' ? [row.high] : [row.low, row.high],\n      );\n      const low = Math.min(...values);\n      if (low <= 0) return [undefined, undefined];\n      const span = Math.max(...values) - low || low * 0.1;\n      return [Math.max(0, low - span * 0.5), undefined];\n    };\n\n    return () => (\n      <XYChart<WaterfallRow>\n        {...rest}\n        valueDomain={\n          rest.valueDomain ?? (fromZero || rows.length === 0 ? undefined : zoomedDomain())\n        }\n        data={rows}\n        index=\"label\"\n        // 系列只用来给十字线定位与算范围；画法、提示框、数据表由 kind 决定\n        series={[{ key: 'bar', label: lang.chartChange }]}\n        legend={false}\n        kind={kind}\n        onItemClick={onItemClick && ((_row, position) => onItemClick(steps[position]!, position))}\n      />\n    );\n  },\n);\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0FA,SAAgB,cAAc,OAAiD;CAC7E,IAAI,UAAU;CACd,OAAO,MAAM,KAAK,SAAS;EACzB,MAAM,SAAS,KAAK,QAAQ,IAAI;EAChC,IAAI,KAAK,OAAO,UAAU,KAAK,UAAU,KAAA,IAAY,UAAU,SAAS,KAAK,KAAK;OAC7E,WAAW,KAAK,UAAU,KAAA,IAAY,IAAI,SAAS,KAAK,KAAK;EAClE,MAAM,CAAC,KAAK,QAAQ,UAAU,UAAU,CAAC,QAAQ,OAAO,IAAI,CAAC,SAAS,MAAM;EAE5E,MAAM,UAAU,MAAM,KAAK,OAAO;EAClC,MAAM,OAAO,UAAU,IAAI,QAAQ,IAAI,OAAO;EAC9C,MAAM,MAAM,UAAU,OAAO,QAAQ,IAAI,MAAM,OAAO,OAAO;EAC7D,OAAO;GACL,OAAO,KAAK;GACZ,MAAM,KAAK,QAAQ,UAAU,WAAW,SAAS,aAAa;GAC9D,QAAQ,KAAK;GACb,YAAY;GACZ;GACA;GACA,OAAO,UAAU,MAAM;GACvB;GACA;EACF;CACF,CAAC;AACH;;AAGA,IAAa,iBAAiB,0BAC5B,QAAA,SAS2B;CAAA,MAAA,QAAAA,aAAA,QAAA,OAAA;CAAA,MAAA,gBAAAA,aAAA,QAAA,eAAA;CAAA,MAAA,gBAAAA,aAAA,QAAA,eAAA;CAAA,MAAA,aAAAA,aAAA,QAAA,YAAA;CAAA,MAAA,SAAAA,aAAA,QAAA,UAJhB,CAAC;CAAA,MAAA,WAAAA,aAAA,QAAA,YACC,IAAI;CAAA,MAAA,cAAAA,aAAA,QAAA,aAAA;CAAA,MAEZ,OAAIC,UAAA,QAAA,MAAA,IAAA;CAEP,MAAM,OAAO,QAAQ;CACrB,MAAM,SAAS,UAAU;CACzB,MAAM,YAAY,yBAAyB;EAAE,aAAa,KAAK;EAAa,MAAM,KAAK;CAAK,EAAE;CAC9F,MAAM,OAAIC,eAAY,cAAa,MAAA,KAAM,CAAC;CAC1C,MAAM,WAAW,QACf,aACE,IAAI,SAAS,UACR,WAAA,SAAc,WACf,IAAI,SAAS,aACV,cAAA,SAAiB,YACjB,cAAA,SAAiB,UACxB,CACF;;CAEF,MAAM,cAAc,KAAmB,SAAS,UAC9C,IAAI,WAAW,KAAA,IACX,KAAK,aACL,OAAO,OAAO,IAAI,QAAQ;EACxB,GAAG,KAAK;EACR,aAAa;EACb,GAAI,UAAU,KAAK,OAAO,EAAE,QAAQ,KAAK,KAAK,IAAI,CAAC;CACrD,CAAC;CACP,MAAM,kBAAkB,QAAsB,OAAO,OAAO,IAAI,YAAY,KAAK,WAAW;CAE5F,MAAM,OAAIA,gBAAuC;EAC/C,UAAU;EACV,SAAS;EACT,eAAe,SAAS,KAAK,SAAS,QAAQ,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC;EACjE,cAAc,WAAW,UAAU;EACnC,aAAa,EAAE,GAAG,UAAU,aAAa;GACvC,MAAM,OAAO,SAAS,mBAAmB,IAAI,WAAyB;IAAE;IAAG,GAAG,CAAA;GAAG,CAAC,CAAC;GACnF,KAAK,UAAU;IACb;IACA,GAAG;MAAE,QAAQ,IAAI;MAAO,QAAQ,IAAI;MAAM,QAAQ,IAAI;IAAK;IAE3D,QAAQ,KAAmB,aACzB,aAAa,IAAI,gBAAgB,QAAQ,GAAG;IAC9C,gBAAc,OAAA;IACd,YAAY;IACZ,aAAa;IACb;GACF,CAAC;GACD,OAAO,CAAC,IAAI;EACd;EACA,eAAe,QAAQ,CACrB;GACE,OAAO,IAAI,SAAS,UAAU,KAAK,aAAa,KAAK;GACrD,OAAO,QAAQ,GAAG;GAClB,OAAO,IAAI,SAAS,UAAU,UAAU,IAAI,UAAU,IAAI,WAAW,KAAK,IAAI;EAChF,GACA,GAAI,IAAI,SAAS,UACb,CAAA,IACA,CACE;GACE,OAAO,KAAK;GACZ,OAAO;GACP,OAAO,UAAU,IAAI,UAAU;EACjC,CAAC,CACD;EAER,QAAQ,UAAU;GAChB,SAAS;IACP,KAAK;IACL,KAAK,OAAO,GAAG,KAAK,YAAW,GAAI,KAAK,KAAI,KAAM,KAAK;IACvD,KAAK,OAAO,GAAG,KAAK,gBAAe,GAAI,KAAK,KAAI,KAAM,KAAK;GAAe;GAE5E,MAAM,KAAK,KAAK,SAAS;IACvB,QAAQ,IAAI;IACZ,OAAO,CAAC,IAAI,SAAS,UAAU,KAAK,aAAa,WAAW,GAAG,GAAG,eAAe,GAAG,CAAC;GACvF,EAAE;EACJ;CACF,EAAC;;;;;CAMD,MAAM,qBAAsD;EAC1D,MAAM,SAAS,KAAA,MAAK,SAAS,QAC3B,IAAI,SAAS,UAAU,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI,IAAI,CACxD;EACA,MAAM,MAAM,KAAK,IAAI,GAAG,MAAM;EAC9B,IAAI,OAAO,GAAG,OAAO,CAAC,KAAA,GAAW,KAAA,CAAS;EAC1C,MAAM,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,OAAO,MAAM;EAChD,OAAO,CAAC,KAAK,IAAI,GAAG,MAAM,OAAO,EAAG,GAAG,KAAA,CAAS;CAClD;CAEA,aAAOC,YAAA,SAAAC,WAEC,MAAI;EAAA,eAEN,KAAK,gBAAgB,SAAA,SAAY,KAAA,MAAK,WAAW,IAAI,KAAA,IAAY,aAAa;EAAE,QAAA,KAAA;EAAA,SAAA;EAAA,UAK1E,CAAC;GAAE,KAAK;GAAO,OAAO,KAAK;EAAY,CAAC;EAAC,UACzC;EAAK,QAAA,KAAA;EAAA,eAEA,YAAA,WAAiB,MAAM,aAAa,YAAA,MAAY,MAAA,MAAM,WAAY,QAAQ;CAAE,CAAA,GAAA,IAAA;AAG/F,GAAC;CAAA,MAAA;CAAA,OAAA;EAAA;EAAA;EAAA;EAAA;EAAA;EAAA;EAAA;CAAA;AAAA,CACH"}

package/dist/charts/XYChart.d.ts

@@ -0,0 +1,206 @@
+/**
+ * 直角坐标图表（柱状图、折线图、面积图）的公共部分：坐标轴、十字线与提示框、数值范围；外层结构（图例、单位、
+ * 空与加载状态、给读屏的数据表）交给 ChartFrame。
+ * 绘图交给 Unovis 的 XYContainer：组件实例只建一次，数据与配置变化时 update，卸载时 destroy；
+ * 绘图区换了元素（加载、空状态之后重新出现）时容器连同全部实例一起重建。
+ * 各种图只决定画什么（kind.components），坐标轴、十字线、提示框、配色都在这里统一。
+ * 目标线（targets）用 Unovis 的 Plotline。点了下钻（onItemClick）：有图形可点的图（柱子）按图形的点击事件
+ * （kind.itemSelector），折线、面积图按十字线所在的那一行，散点图按悬停的点。
+ *
+ * 标注（annotations）：类目上的事件画成竖线（Plotline），圈出某个系列的值画成空心圈带文字（Scatter）；
+ * 区间（bands）画成浅色的带（Plotband）。百分比堆叠（kind.percent）按每个类目里各系列的占比画。
+ * 第二数值轴（kind.secondary，组合图）：刻度与主轴对齐（alignedTicks），第二轴的系列换算到主轴的坐标里画，
+ * 右侧的刻度文字是不裁剪的 Plotline 标签。
+ */
+import { type XYComponentCore } from '@unovis/ts';
+import * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+import { type VNodeChild } from 'vue';
+import { type NumericFormat } from '../config/lang/format';
+import { type NumericValue } from '../utils/data/numeric';
+import type { PartProps } from '../utils/props';
+import { type ChartFrameParts, type ChartTable, type ChartTooltipItem } from './frame';
+import { type ChartColor, type ChartSeries, type ResolvedSeries } from './series';
+/** 目标线（参考线）：数值轴上的一条虚线 */
+export interface ChartTarget {
+    /** 位置：数值轴上的值 */
+    value: NumericValue;
+    /** 标签：写在线的一端，后面带上格式化的数值（“年度指标 1,200”） */
+    label?: string;
+    /** 颜色；默认是 danger（要够到的线） */
+    color?: ChartColor;
+}
+/** 标注：类目上发生的事（竖线），或圈出某个系列在这个类目上的值 */
+export interface ChartAnnotation {
+    /** 标在哪个类目上：index 字段的值（散点图是横轴上的数值） */
+    at: unknown;
+    /** 文字 */
+    label: string;
+    /** 圈出这个系列在这里的值（系列的 key）；不写时是一条竖线（换供应商、调价生效这类事件） */
+    series?: string;
+    /** 颜色；竖线默认是次要色，圈默认是系列色 */
+    color?: ChartColor;
+}
+/** 区间：类目轴上的一段（试运行期、促销期），或数值轴上的一段（目标区间） */
+export interface ChartBand {
+    /** 在哪条轴上，默认 index（类目轴） */
+    axis?: 'index' | 'value';
+    /** 起点：类目轴是 index 字段的值（含这一项），数值轴是数值 */
+    from: unknown;
+    /** 终点：同 from（含这一项） */
+    to: unknown;
+    /** 文字：类目轴上的写在带的左下角，数值轴上的写在左上角 */
+    label?: string;
+    /** 颜色，默认 neutral；画成很浅的底色 */
+    color?: ChartColor;
+}
+/** 第二数值轴（右侧）：哪些系列画在它上面，它的格式与单位 */
+export interface ChartSecondaryAxis {
+    /** 画在第二数值轴上的系列 */
+    keys: readonly string[];
+    /** 数值的格式 */
+    format?: NumericFormat;
+    /** 单位：显示在右上方，提示框与数据表的数值后面带上 */
+    unit?: string;
+}
+/** 加载中的骨架 */
+export interface ChartSkeletons {
+    /** 一排高低不一的柱（柱状图） */
+    bars: unknown;
+    /** 一整块（默认） */
+    block: unknown;
+}
+/** 直角坐标图表共有的属性；未声明的属性落到外层 div（role="figure"）上，aria-label 是图表的名称 */
+export interface XYChartProps<T extends object> extends PartProps<'div', 'role' | 'aria-busy'>, ChartFrameParts {
+    /** 数据：每一行是类目轴上的一项（一个月、一个项目） */
+    data: readonly T[];
+    /** 类目字段：类目轴的刻度、提示框的标题、数据表的第一列 */
+    index: keyof T & string;
+    /** 系列：每个系列画成一组柱子、一条线或一片面积 */
+    series: readonly ChartSeries<T>[];
+    /** 类目的显示文字；不写时把字段的值转成字符串 */
+    indexFormat?: (value: T[keyof T & string], row: T) => string;
+    /**
+     * 数值的格式：数值轴、提示框、数据表共用，按当前语言格式化。以万元为单位画金额时写
+     * `{ scale: 10_000, maximumFractionDigits: 1 }` 并配 `unit="万元"`
+     */
+    valueFormat?: NumericFormat;
+    /** 单位：显示在数值轴上方，提示框与数据表的数值后面带上 */
+    unit?: string;
+    /**
+     * 绘图区的高度；数字按 px
+     * @default 240
+     */
+    height?: number | string;
+    /** 图例：默认多于一个系列时显示；点图例可以隐藏、恢复系列 */
+    legend?: boolean;
+    /**
+     * 数值轴的网格线
+     * @default true
+     */
+    grid?: boolean;
+    /** 数值轴的范围 [最小, 最大]；不写的一端按数据自动取，最小值默认从 0 起（数据有负数时取负数） */
+    valueDomain?: readonly [number | undefined, number | undefined];
+    /**
+     * 悬停时的提示框
+     * @default true
+     */
+    tooltip?: boolean;
+    /**
+     * 加载中：绘图区显示扫光的骨架（柱状图是一排高低不一的柱），带 aria-busy
+     * @default false
+     */
+    loading?: boolean;
+    /** 隐藏的系列（存系列的 key）：点图例时写回，父级可以写 _hiddenSeries={keys} */
+    _hiddenSeries?: string[];
+    /** 没有数据时显示的内容，默认是“暂无数据” */
+    empty?: VNodeChild;
+    /** 目标线、参考线：数值轴上的虚线（横向图是竖线），如年度销售指标；数值轴的范围会包含它 */
+    targets?: readonly ChartTarget[];
+    /** 标注：类目上的事件（竖线），或圈出某个系列的值（横向图只画竖线） */
+    annotations?: readonly ChartAnnotation[];
+    /** 区间：类目轴或数值轴上的一段，画成浅色的带（数值轴的范围会包含它） */
+    bands?: readonly ChartBand[];
+    /**
+     * 点了一个类目（下钻，如跳到筛好条件的台账）：参数是这一行与它的位置；写了它时绘图区的指针是手形。
+     * 点图是鼠标的捷径：同样的去处在页面上还要有链接或按钮，键盘与读屏才到得了（WCAG 2.1.1）
+     */
+    onItemClick?: (row: T, index: number) => void;
+    /** 缩放：绘图区下面一条区间滑块，选一段类目放大看（几年的月度数据）；读屏的数据表仍是全部 */
+    zoom?: boolean;
+    /** 缩放的区间 [起, 止]：类目的位置，含两端；父级可以写 _zoomRange={range}，null 是全部 */
+    _zoomRange?: [number, number] | null;
+}
+/** 交给各种图的绘制上下文 */
+export interface XYChartContext<T extends object> {
+    /** 显示中的系列（去掉了图例里隐藏的），颜色已定 */
+    series: ResolvedSeries<T>[];
+    /** 类目的位置：第几行 */
+    x: (row: T, index: number) => number;
+    /** 系列的取值函数，空值返回 undefined（Unovis 跳过） */
+    y: (series: ResolvedSeries<T>) => (row: T) => number | undefined;
+    /** 取一个跨渲染保留的组件实例：第一次调用时创建；Unovis 组件保留实例，更新时才有过渡动画 */
+    instance: <C>(key: string, create: () => C) => C;
+    /** 点图形下钻的事件（写了 itemSelector 时）：并进组件的 events；没有 onItemClick 时是空的。参数同 Unovis：图形的数据、事件、位置 */
+    events: Record<string, Record<string, (row: T, event: Event, index: number) => void>>;
+}
+/** 一种图：画哪些组件，以及与坐标轴、十字线有关的差别 */
+export interface XYChartKind<T extends object> {
+    /** 配置并返回要画的 Unovis 组件（每次数据或属性变化都会调用） */
+    components: (context: XYChartContext<T>) => XYComponentCore<T>[];
+    /** 横向：类目在纵轴、数值在横轴 */
+    horizontal?: boolean;
+    /** 十字线上给每个系列画圆点（折线图、面积图）；柱状图不画 */
+    crosshairDots?: boolean;
+    /** 加载中的骨架，默认 block */
+    skeleton?: keyof ChartSkeletons;
+    /** 绘图区四周的留白（px）：折线两端不贴着边缘 */
+    padding?: {
+        left?: number;
+        right?: number;
+        top?: number;
+        bottom?: number;
+    };
+    /** 数值范围按堆叠后的总和算（堆叠的柱子、面积） */
+    stacked?: boolean;
+    /** 百分比堆叠：各系列按它在这个类目里的占比画（加起来 100%），数值轴是百分比，提示框带上占比 */
+    percent?: boolean;
+    /** 第二数值轴（组合图）：这些系列画在右侧的轴上，刻度与主轴对齐 */
+    secondary?: ChartSecondaryAxis;
+    /** 十字线只在这些系列上画圆点（组合图里只给线画）；不写时按 crosshairDots */
+    crosshairSeries?: (series: ResolvedSeries<T>) => boolean;
+    /** 横轴是连续的数值（散点图）：取值、刻度与提示框里的写法、数据表的列名、轴下方的标题；不写时横轴是类目（第几行） */
+    continuousX?: {
+        value: (row: T) => number | undefined;
+        format: (value: number) => string;
+        label: string;
+        title?: string;
+    };
+    /** 数值轴默认从 0 起（数据有负数时取负数）；false 时按数据自动取（散点图） */
+    zeroBaseline?: boolean;
+    /** 提示框跟着数据点（散点图），没有十字线：按选择器触发，悬停的数据是这一行 */
+    pointTooltip?: string;
+    /** 提示框里列的项；不写时每个显示中的系列一行（瀑布图列变动与累计） */
+    tooltipItems?: (row: T) => ChartTooltipItem[];
+    /** 数值轴（主轴）的范围要包含的值；shown 是显示中的系列（第二数值轴的已去掉）。不写时按系列的值（stacked 时按正负各自的总和） */
+    domainValues?: (rows: readonly T[], shown: readonly ResolvedSeries<T>[]) => number[];
+    /** 给读屏的数据表；不写时类目一列加每个系列一列 */
+    table?: (rows: readonly T[]) => ChartTable;
+    /** 点哪种图形算点了这一行（柱子的选择器，图形绑定的数据是这一行）；不写时按十字线所在的那一行 */
+    itemSelector?: string;
+}
+/** XYChart 的样式：hideCrosshairLine 与加载中的骨架（外层结构的样式见 chartStyles） */
+export declare const xyChartStyles: Readonly<{
+    readonly hideCrosshairLine: css.CompiledStyles;
+    readonly skeleton: css.CompiledStyles;
+    readonly zoom: css.CompiledStyles;
+    readonly zoomSlider: css.CompiledStyles;
+    readonly skeletonBars: css.CompiledStyles;
+    readonly skeletonBarsHorizontal: css.CompiledStyles;
+    readonly skeletonBar: css.CompiledStyles;
+    readonly skeletonBarSize: (percent: string) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+    readonly skeletonBarSizeHorizontal: (percent: string) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+}>;
+/** 直角坐标图表的公共实现（组件库内部用，见 BarChart、LineChart、AreaChart） */
+export declare const XYChart: <T extends object>(props: XYChartProps<T> & {
+    kind: XYChartKind<T>;
+}) => import("@zerodep-dev/vue-tsx-pro-tsx").TsxNode;