@astryx-vue/charts 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,799 @@
+import { Ref, VNodeChild } from "vue";
+import { ScaleBand, ScaleLinear, scaleBand, scaleLinear } from "d3-scale";
+//#region src/color.d.ts
+/**
+ * 颜色解析与序列化。图表配色、透明度换算、GL 通道都用这里的函数。
+ *
+ * 只认三类输入：hex（`#rgb`、`#rgba`、`#rrggbb`、`#rrggbbaa`，带不带 `#` 都行）、
+ * `rgb()` / `rgba()`、以及 token 表达式里用到的几个颜色名。解析不了（比如
+ * `var()`、`oklch()`）一律返回 null，让调用方原样保留原表达式，而不是猜一个值。
+ */
+/** 一个颜色拆成 0-255 的 RGB 三个通道和 0-1 的透明度。 */
+interface RGBA {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+/**
+ * 解析 hex 颜色。支持 `#rgb`、`#rgba`、`#rrggbb`、`#rrggbbaa`，`#` 可有可无。
+ * 其它输入返回 null。
+ */
+export declare function parseHex(hex: string): RGBA | null;
+/**
+ * 解析 `rgb()` / `rgba()`。通道可以用逗号或空格分隔，可以用 `/ alpha`，
+ * 也可以写百分比。通道和透明度都会夹到合法范围。
+ */
+export declare function parseRgb(value: string): RGBA | null;
+/**
+ * 解析一个具体的 CSS 颜色字符串：hex、`rgb()` / `rgba()`，以及 token 表达式里
+ * 用到的几个颜色名。解析不了返回 null。
+ */
+export declare function parseColor(value: string): RGBA | null;
+/** 把 0-255 的三个通道拼成大写 `#RRGGBB`。 */
+export declare function formatHex(r: number, g: number, b: number): string;
+/** 完全不透明时输出 `#RRGGBB`，否则输出 `rgba(r, g, b, a)`。 */
+export declare function formatColor({ r, g, b, a }: RGBA): string;
+/**
+ * 把解析后的颜色转成 0-1 的 `[r, g, b]` 浮点数，给 WebGL 的 uniform 和顶点属性用。
+ *
+ * 参数是解析后的结果，所以每个调用方都走同一条校验路径：`toGLFloats(parseHex(color))`。
+ * 传 null 或通道非有限时返回中性灰。透明度故意丢掉，GL 那边自己混合。
+ */
+export declare function toGLFloats(color: RGBA | null): [number, number, number];
+//#endregion
+//#region src/types.d.ts
+/**
+ * 图表的核心类型。比例尺、标记、交互都从这里取。
+ *
+ * 和上游的区别只有两处：① `render()` 返回 Vue 的 `VNodeChild`，不再是 ReactNode；
+ * ② `render()` 是可选的——这个包目前只做「算」，不算「画」，渲染由后续工作补上。
+ */
+type ChartScale = ScaleLinear<number, number> | ScaleBand<string>;
+/**
+ * 一个标记的颜色：要么是一串固定颜色，要么是一个按数据点取色的函数
+ * （比如正值一个色、负值一个色）。
+ */
+type ColorAccessor = string | ((datum: Record<string, unknown>, index: number) => string);
+/**
+ * 没有显式 `yDomain` 时，y 轴范围怎么定：
+ * - `'auto'`（默认）：带零基线的标记（bar、area）把 0 算进范围；只有连续点的
+ *   图表（line、dot 等）上下留一点余量，免得点和边缘粘在一起。
+ * - `'zero'`：以 0 为中心对称，适合正负数据（比如盈亏）。
+ * - `'data'`：紧贴数据范围，不强制含 0，也不留余量。
+ */
+type YBaseline = 'auto' | 'zero' | 'data';
+interface ChartMargin {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+/** 一个数据点算出来的像素位置。 */
+interface ResolvedPoint {
+  /** 绘图区坐标系里的 x 像素 */
+  px: number;
+  /** 绘图区坐标系里的 y 像素（标记的顶边） */
+  py: number;
+  /** y 方向的基线像素（标记的底边）；堆叠时和 `py` 不同 */
+  py0: number;
+  /** 在数据数组里的下标 */
+  dataIndex: number;
+}
+/** 传给每个系列的 `resolve()` 和 `render()` 的上下文。 */
+interface SeriesContext {
+  data: Record<string, unknown>[];
+  xKey: string;
+  xScale: ChartScale;
+  yScale: ScaleLinear<number, number>;
+  /**
+   * 按行排布的标记（如热力图）用的分类 y 比例尺。只有系列声明了
+   * `layout.yBandKey` 时才存在，这时 y 轴是分类轴，线性 `yScale` 便用不上了。
+   */
+  yBandScale?: ScaleBand<string>;
+  /** 绘图区宽度 */
+  width: number;
+  /** 绘图区高度 */
+  height: number;
+}
+/**
+ * 每个标记工厂返回的对象的统一形状。标记自己知道怎么算位置、怎么画，
+ * 图表根只负责遍历和调用。
+ *
+ * 一个 SeriesDef 只能用一次：布局和渲染会就地往上写 `_uid`、`_isTopOfStack`、
+ * `_resolvedColor`，所以同一个对象不能同时给两个 `<Chart>` 用。每张图都要新建一份。
+ */
+interface SeriesDef {
+  /** 标记类型标识 */
+  readonly type: string;
+  /**
+   * 这个系列的语义键，通常就是 dataKey。既当图例文案的兜底，也用来协调堆叠和分组。
+   * 它不保证唯一（两个系列可以共用同一个 dataKey），所以绝不能当 Map 的键或列表的
+   * 渲染键——那是 `_uid` 的活。
+   */
+  readonly key: string;
+  /** 这个系列读哪些数据列——用来算 y 轴范围 */
+  readonly dataKeys: string[];
+  /**
+   * 一次布局里唯一的实例身份，由布局按系列在 `series` 数组里的位置赋值。
+   * 算好的点位映射、渲染键、提示框查找都用它。不要自己设。
+   */
+  _uid?: string;
+  /** 这个系列是不是所在堆叠组的最上一层（布局时写入） */
+  _isTopOfStack?: boolean;
+  /** 图例上显示的固定颜色。颜色是按点取色时为 undefined。 */
+  readonly color?: string;
+  /**
+   * 图表根给没写死颜色的系列（自动配色或按点取色）分配的调色板颜色。
+   * 既当渲染兜底，也当图例和提示框的代表色。不要自己设。
+   */
+  _resolvedColor?: string;
+  /** 图例上的可读文案，没给就用 `key`。 */
+  readonly label?: string;
+  /** 图表根用来跨系列协调的布局提示 */
+  readonly layout: {
+    /** 堆叠组：同一组的系列累加 */
+    stack?: string;
+    /** 柱状分组：同一组的系列把带宽平分 */
+    group?: string;
+    /** 这个系列是否要求 y 轴范围包含 0 */
+    includeZero?: boolean;
+    /**
+     * 设了它，图表的 y 轴就按这个数据列的不同取值建分类比例尺（比如热力图的每一天），
+     * 而不是数值比例尺。布局会把它以 `yBandScale` 交给标记和坐标轴，左侧坐标轴就能把
+     * 分类对齐到每一行。热力图还应该写 `dataKeys: []`，免得喂给（已经用不上的）线性 y 轴范围。
+     */
+    yBandKey?: string;
+  };
+  /**
+   * 算出每个数据点的像素位置。布局阶段由图表根调用。
+   * 堆叠时收到预先算好的累计偏移。
+   */
+  resolve: (ctx: SeriesContext, stackOffsets?: {
+    y0: number;
+    y1: number;
+  }[], groupInfo?: {
+    index: number;
+    count: number;
+  }) => ResolvedPoint[];
+  /**
+   * 按算好的位置把标记画出来。渲染阶段由图表根调用。
+   * 返回 SVG 元素（WebGL 标记自己管 canvas）。
+   */
+  render?: (resolved: ResolvedPoint[], ctx: SeriesContext) => VNodeChild;
+}
+/** 所有系列算好的位置 */
+type ResolvedPositions = Map<string, ResolvedPoint[]>;
+/** 换算成绘图区坐标的指针事件 */
+interface ChartPointerEvent {
+  x: number;
+  y: number;
+  nearest: (ResolvedPoint & {
+    seriesKey: string;
+  }) | null;
+  active: boolean;
+}
+/** 图表根提供给交互子组件的上下文 */
+interface ChartContext {
+  width: number;
+  height: number;
+  margin: ChartMargin;
+  data: Record<string, unknown>[];
+  xKey: string;
+  xScale: ChartScale;
+  yScale: ScaleLinear<number, number>;
+  /**
+   * 分类 y 比例尺（比如热力图的每一行），系列声明了 `layout.yBandKey` 时才有。
+   * 画 y 轴的东西（`ChartAxis`）在它存在时应该优先用它。
+   */
+  yBandScale?: ScaleBand<string>;
+  resolved: Map<string, ResolvedPoint[]>;
+  onPointer: (handler: (e: ChartPointerEvent) => void) => () => void;
+  svgRef: Ref<SVGSVGElement | null>;
+}
+/** 这个标记类型是不是纯标注类。 */
+export declare function isUtilityMarkType(type: string): boolean;
+//#endregion
+//#region src/legend.d.ts
+interface LegendItem {
+  label: string;
+  color: string;
+  /** 标记类型——决定色块形状（柱状是方块，其余是短线） */
+  type?: string;
+}
+/** 从系列列表推出图例项，跳过标注类标记。 */
+export declare function deriveLegendItems(series: readonly SeriesDef[]): LegendItem[];
+//#endregion
+//#region src/ChartLegend/types.d.ts
+/** 图例摆在图表的哪一边。`start` / `end` 是逻辑方位，跟着书写方向走。 */
+type LegendPosition = 'top' | 'bottom' | 'start' | 'end';
+/** 图例在它所在的那条边上怎么对齐。 */
+type LegendAlignment = 'start' | 'center' | 'end';
+interface ChartLegendProps {
+  /** 要显示的图例项 @default [] */
+  items?: LegendItem[];
+  /** 图例相对图表的位置 @default 'bottom' */
+  position?: LegendPosition;
+  /** 图例在位置上怎么对齐 @default 'start' */
+  alignment?: LegendAlignment;
+}
+//#endregion
+//#region src/tooltip.d.ts
+/**
+ * 提示框里的一行：某个系列在鼠标停留的 x 位置上的取值。
+ * 形状稳定，用户可以依赖它写自己的提示框内容。
+ */
+interface TooltipSeriesValue {
+  /** 系列键（就是 SeriesDef.key） */
+  key: string;
+  /** 显示文案，系列没写就用 key */
+  label: string;
+  /** 系列颜色 */
+  color: string;
+  /** 标记类型——决定默认样式里色块的形状 */
+  type: string;
+  /** 这个系列在鼠标位置的原始值 */
+  value: unknown;
+}
+/**
+ * 生成提示框要显示的行。跳过标注类标记，也跳过布局没能算出点位的系列。
+ *
+ * 纯函数、同步，调用方可以放心缓存结果。
+ */
+export declare function deriveTooltipSeriesValues(series: readonly SeriesDef[], datum: Record<string, unknown> | undefined, resolvedKeys: ReadonlySet<string>): TooltipSeriesValue[];
+/**
+ * 鼠标停在某个下标上时，这个系列要不要画一个悬停圆点。
+ * 柱状改成高亮整条「带」，标注类标记没有数据点可高亮。
+ */
+export declare function shouldRenderHoverDot(seriesType: string): boolean;
+//#endregion
+//#region src/ChartTooltip/types.d.ts
+/** 提示框相对悬停点的位置。 */
+type ChartTooltipPlacement = 'auto' | 'right' | 'left' | 'top';
+interface ChartTooltipProps {
+  /**
+   * 系列定义：用来把悬停的那行走成每个系列一行的内容。
+   * 通过 `<Chart tooltip>` 打开时由 Chart 自动注入；单独用的时候要把同一份 `series` 传进来。
+   */
+  series?: readonly SeriesDef[];
+  /**
+   * 要不要在悬停的 x 位置画指示。柱状图在 band 轴上画整列高亮，折线/面积/散点画竖线。
+   * @default true
+   */
+  hoverIndicator?: boolean;
+  /** 要不要在每个系列的点上画一个悬停圆点（柱状跳过）。@default true */
+  showHoverDots?: boolean;
+  /**
+   * 卡片相对悬停点的位置。`auto` 放在右边，放不下就翻到左边。
+   * @default 'auto'
+   */
+  placement?: ChartTooltipPlacement;
+}
+interface ChartTooltipSlots {
+  /**
+   * 自定义卡片内容，作用域参数是悬停的 x 值和每个系列的一行。
+   * 不写就用内置样式。返回空内容时不显示卡片，但高亮和圆点照画。
+   */
+  content?: (scope: {
+    xValue: unknown;
+    rows: TooltipSeriesValue[];
+  }) => unknown;
+}
+//#endregion
+//#region src/Chart/types.d.ts
+/** 不写 `margin` 时绘图区四周留多少像素。 */
+export declare const DEFAULT_MARGIN: ChartMargin;
+/**
+ * 数据点（行数 × 数据列数）不超过这个数时，额外输出一张视觉隐藏的数据表。
+ * 再多的表对读屏用户只是噪音，所以大图表只保留名字。
+ */
+export declare const MAX_TABLE_POINTS = 100;
+/** 图例的配置。`legend` 给 `true` 就是用这一份默认值。 */
+type ChartLegendConfig = Omit<ChartLegendProps, 'items'> & {
+  /** 显式指定图例项；不写就从系列推出来。 */
+  items?: ChartLegendProps['items'];
+};
+/** 提示框的配置。自定义内容用 `<Chart>` 的 `tooltip` 插槽，不走 props。 */
+type ChartTooltipConfig = Omit<ChartTooltipProps, 'series'>;
+interface ChartProps {
+  /** 要画的数据行。每行既有 x 那一列，也有一到多个系列的数据列。 */
+  data: Record<string, unknown>[];
+  /** 每行里当 x 用的字段名，所有系列共用。 */
+  xKey: string;
+  /** 标记定义，按顺序画在同一条 x/y 坐标系上。 */
+  series: SeriesDef[];
+  /** 图表高度（CSS 像素）。非有限值和负数都当 0。@default 300 */
+  height?: number;
+  /**
+   * 图表宽度（CSS 像素）。浏览器里第一次量到容器宽度之后就不再用了，
+   * 服务端渲染没有容器可量，靠它出图。
+   * @default 0
+   */
+  width?: number;
+  /** 绘图区内边距的部分覆盖值，没写的边用默认值。 */
+  margin?: Partial<ChartMargin>;
+  /** 没写 `yDomain` 时 y 轴范围怎么定。@default 'auto' */
+  yBaseline?: YBaseline;
+  /** 显式 y 轴范围 `[min, max]`。它说了算——不加基线、不留余量。 */
+  yDomain?: [number, number];
+  /** 数值 x 轴的显式范围 `[min, max]`。`data` 为空时也照用（流式窗口要稳定）。band 轴上忽略。 */
+  xDomain?: [number, number];
+  /** 显示从系列推出来的图例，或者改成别的摆位。@default false */
+  legend?: boolean | ChartLegendConfig;
+  /** 显示分组的悬停提示框。@default false */
+  tooltip?: boolean | ChartTooltipConfig;
+  /** 图表标题，同时是 SVG 的无障碍名字。 */
+  title?: string;
+  /** 标题下面的补充说明，同时是 SVG 的无障碍描述。 */
+  subtitle?: string;
+}
+interface ChartSlots {
+  /** 画在系列后面的网格，一般是 `<ChartGrid>`。 */
+  grid?: () => unknown;
+  /** 画在系列后面的坐标轴，一般是若干个 `<ChartAxis>`。 */
+  axes?: () => unknown;
+  /** 画在指针捕获层上面的交互层。 */
+  interactions?: () => unknown;
+  /** 提示框的自定义内容，作用域参数是 `{ xValue, rows }`。 */
+  tooltip?: (scope: {
+    xValue: unknown;
+    rows: unknown[];
+  }) => unknown;
+  /** 额外内容，画在内置提示框之后。 */
+  default?: () => unknown;
+}
+//#endregion
+//#region src/Chart/Chart.vue.d.ts
+type __VLS_Slots = ChartSlots;
+declare const __VLS_base: import("vue").DefineComponent<ChartProps, {
+  element: import("vue").Ref<HTMLElement | null, HTMLElement | null>;
+}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ChartProps> & Readonly<{}>, {
+  height: number;
+  width: number;
+  margin: Partial<ChartMargin>;
+  yBaseline: YBaseline;
+  yDomain: [number, number];
+  xDomain: [number, number];
+  legend: boolean | ChartLegendConfig;
+  tooltip: boolean | ChartTooltipConfig;
+  title: string;
+  subtitle: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export$5: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default: typeof __VLS_export$5;
+type __VLS_WithSlots<T, S> = T & {
+  new (): {
+    $slots: S;
+  };
+};
+//#endregion
+//#region src/ChartAxis/types.d.ts
+/** 坐标轴画在绘图区的哪一条边上。 */
+type ChartAxisPosition = 'top' | 'right' | 'bottom' | 'left';
+interface ChartAxisProps {
+  /** 画在哪条边上 */
+  position: ChartAxisPosition;
+  /** 想要几个刻度（近似值，d3 决定最终数量）@default 5 */
+  tickCount?: number;
+  /** 最多显示几个刻度文字，超出的按等间隔跳过 */
+  maxTicks?: number;
+  /** 自定义刻度文字 */
+  tickFormat?: (value: unknown) => string;
+  /** 把刻度文字截断到这么多个字（末尾补省略号） */
+  truncate?: number;
+  /** 刻度滑动时要不要过渡动画，流式更新时更好看 @default true */
+  animated?: boolean;
+  /**
+   * 画不画轴线。默认只有 `position="bottom"` 画。
+   * 开了 `showTicks` 会强制画上，不然刻度线没有着落。
+   */
+  showAxisLine?: boolean;
+  /** 每个刻度处画不画一小段垂直的短刻度线 @default false */
+  showTicks?: boolean;
+}
+//#endregion
+//#region src/ChartAxis/ChartAxis.vue.d.ts
+declare const __VLS_export$4: import("vue").DefineComponent<ChartAxisProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ChartAxisProps> & Readonly<{}>, {
+  tickCount: number;
+  maxTicks: number;
+  tickFormat: (value: unknown) => string;
+  truncate: number;
+  animated: boolean;
+  showAxisLine: boolean;
+  showTicks: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$1: typeof __VLS_export$4;
+//#endregion
+//#region src/ChartGrid/types.d.ts
+interface ChartGridProps {
+  /** 画不画横向网格线 @default true */
+  horizontal?: boolean;
+  /** 画不画纵向网格线 @default false */
+  vertical?: boolean;
+  /**
+   * 每条轴上大约画几条网格线。和 `<ChartAxis>` 的 `tickCount` 保持一致，
+   * 网格线才会和刻度落在同一个值上。
+   * @default 5
+   */
+  tickCount?: number;
+}
+//#endregion
+//#region src/ChartGrid/ChartGrid.vue.d.ts
+declare const __VLS_export$3: import("vue").DefineComponent<ChartGridProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ChartGridProps> & Readonly<{}>, {
+  tickCount: number;
+  horizontal: boolean;
+  vertical: boolean;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$2: typeof __VLS_export$3;
+//#endregion
+//#region src/ChartLegend/ChartLegend.vue.d.ts
+declare const __VLS_export$2: import("vue").DefineComponent<ChartLegendProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ChartLegendProps> & Readonly<{}>, {
+  items: LegendItem[];
+  position: LegendPosition;
+  alignment: LegendAlignment;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$3: typeof __VLS_export$2;
+//#endregion
+//#region src/ChartSwatch/types.d.ts
+/** 色块的视觉形态，由标记类型决定。 */
+type ChartSwatchVariant = 'square' | 'line';
+interface ChartSwatchProps {
+  /** 填充色，一般就是系列颜色 */
+  color: string;
+  /**
+   * 形态。`square` 是方块（柱状系列），`line` 是一小段横线（折线、散点、面积等）。
+   * @default 'square'
+   */
+  variant?: ChartSwatchVariant;
+}
+//#endregion
+//#region src/ChartSwatch/ChartSwatch.vue.d.ts
+declare const __VLS_export$1: import("vue").DefineComponent<ChartSwatchProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ChartSwatchProps> & Readonly<{}>, {
+  variant: ChartSwatchVariant;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$4: typeof __VLS_export$1;
+//#endregion
+//#region src/ChartSwatch/swatch.d.ts
+/**
+ * 标记类型对应的色块形态：柱状是方块，其余（折线、散点、面积……）都是一小段线。
+ *
+ * 图例和提示框都走这一条规则，同一个系列在两处长得一样。
+ */
+export declare function swatchVariantForType(type: string | undefined): ChartSwatchVariant;
+//#endregion
+//#region src/ChartTooltip/ChartTooltip.vue.d.ts
+declare const __VLS_export: import("vue").DefineComponent<ChartTooltipProps, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<ChartTooltipProps> & Readonly<{}>, {
+  series: readonly SeriesDef[];
+  hoverIndicator: boolean;
+  showHoverDots: boolean;
+  placement: ChartTooltipPlacement;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
+declare const _default$5: typeof __VLS_export;
+//#endregion
+//#region src/ChartTooltip/position.d.ts
+interface CardPositionInput {
+  /** 卡片左上角贴着悬停点时，在视口里的位置 */
+  anchorLeft: number;
+  anchorTop: number;
+  /** 卡片自身的尺寸 */
+  width: number;
+  height: number;
+  /** 视口尺寸 */
+  viewportWidth: number;
+  viewportHeight: number;
+}
+export declare function computeCardPosition(input: CardPositionInput, placement: ChartTooltipPlacement): {
+  x: number;
+  y: number;
+};
+//#endregion
+//#region src/context.d.ts
+/**
+ * 读当前图表的上下文。只能在 `<Chart>` 里用。
+ *
+ * 返回的对象身份不变，字段是活的：图表重新量到宽度、重新布局之后，
+ * 同样的对象读出来的比例尺和尺寸就是新的。所以取值要写在 `computed` 或渲染里，
+ * 不要在 `setup` 里一次性解构出来。
+ */
+export declare function useChart(): ChartContext;
+//#endregion
+//#region src/getChartColors.d.ts
+/**
+ * 从一个「取变量值」的函数算出整套图表配色，不需要 DOM、不需要主题对象。
+ *
+ * 三套配色都能适应任意数量：类别色在固定的槽位里循环；顺序色和发散色在色阶停靠点
+ * 够用时直接取设计好的那几档，要得更多就在色阶上插值，而不是默默截断。
+ */
+/** 顺序色阶可用的色相名 */
+type SequentialHue = 'blue' | 'shamrock' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow' | 'gray';
+/** 配色 API */
+interface ChartColorsAPI {
+  categorical: (n: number) => string[];
+  sequential: Record<SequentialHue, (n: number) => string[]>;
+  diverging: {
+    positiveNegative: (n: number) => string[];
+    coldHot: (n: number) => string[];
+    custom: (neg: SequentialHue, pos: SequentialHue, n: number, midpoint?: string) => string[];
+  };
+  semantic: {
+    positive: string;
+    negative: string;
+    warning: string;
+    neutral: string;
+  };
+  /** 图表骨架（坐标轴、网格、刻度、标签）的结构色 */
+  structural: {
+    axis: string;
+    grid: string;
+    tick: string;
+    label: string;
+  };
+  alpha: (hex: string, opacity: number) => string;
+}
+/** 把一个变量名取成当前值 */
+type TokenResolver = (name: string) => string;
+/** 从一个取变量值的函数算出整套配色。这是最底层的入口。 */
+export declare function getChartColorsFromResolver(resolve: TokenResolver): ChartColorsAPI;
+//#endregion
+//#region src/useChartColors.d.ts
+/**
+ * 当前主题下的图表配色。
+ *
+ * ```ts
+ * const colors = useChartColors()
+ * colors.categorical(5)
+ * colors.semantic.positive
+ * ```
+ *
+ * 返回的对象整个包共用一份，身份不变，可以直接放进 `watch` / `computed` 的依赖里。
+ */
+export declare function useChartColors(): ChartColorsAPI;
+//#endregion
+//#region src/formatters.d.ts
+/**
+ * 数字、货币、百分比和日期的格式化函数。
+ *
+ * 三条约定：
+ * - 不好看的值原样返回。非有限数（NaN、±Infinity）和读不出数字的字符串不加工，
+ *   免得出现「InfinityB」这类垃圾；任何输入都不抛错。
+ * - 数字和日期都交给带缓存的 `Intl` 格式化器，所以输出跟随语言，进位也正确。
+ * - 日期按格里高利历输出。有些语言（如 `fa-IR`、`th-TH`）默认用别的历法，
+ *   不指定就会变成波斯历数字或佛历年份。
+ */
+/** 一种 BCP 47 语言标签，例如 `'en-US'`、`'de-DE'`。 */
+type ChartLocale = string;
+/** 按语言把几个词连成「甲、乙和丙」这样的并列短语。 */
+export declare function formatList(values: readonly string[], locale: ChartLocale): string;
+/**
+ * 缩写数字：`1200` → 「1.2K」，`1500000` → 「1.5M」，`1e12` → 「1T」。
+ *
+ * 读不成有限数的值原样返回，所以可以直接拿它当坐标轴刻度格式化器。
+ */
+export declare function compactNumber(value: unknown, locale: ChartLocale): string;
+/**
+ * 生成货币格式化函数。
+ *
+ * 负号的顺序是「符号在前、货币符号在后」，所以负数读作「-$1.5K」而不是「$-1.5K」。
+ * 一千以上用缩写，一千以内用带千分位的普通数字。
+ *
+ * @example
+ * ```
+ * currency('$', locale)(1500)  // $1.5K
+ * currency('€', locale)(12)    // €12
+ * ```
+ */
+export declare function currency(symbol?: string, locale?: ChartLocale): (value: unknown) => string;
+/**
+ * 百分比格式化：`0.45` → 「45%」，`1.2` → 「120%」，`0.005` → 「0.5%」。
+ *
+ * 入参是比例，不是百分数。整数百分比不显示小数位，其余最多一位。
+ */
+export declare function percent(value: unknown, locale: ChartLocale): string;
+/** 短日期，例如「Jan 5」「Mar 12」。 */
+export declare function shortDate(value: unknown, locale: ChartLocale): string;
+/** 年月，例如「Jan 2024」「Mar 2025」。 */
+export declare function monthYear(value: unknown, locale: ChartLocale): string;
+//#endregion
+//#region src/layout.d.ts
+interface LayoutInput {
+  data: Record<string, unknown>[];
+  xKey: string;
+  series: SeriesDef[];
+  width: number;
+  height: number;
+  /** 没给 `yDomain` 时 y 轴范围怎么定，默认 `'auto'`。 */
+  yBaseline?: YBaseline;
+  /** 显式 y 轴范围 `[min, max]`。它说了算——不加基线、不留余量、不 `nice()`。 */
+  yDomain?: [number, number];
+  /**
+   * 数值/线性 x 轴的显式范围 `[min, max]`。它说了算，`data` 为空时也照用
+   * （流式窗口要稳定）。band 比例尺时忽略。
+   */
+  xDomain?: [number, number];
+}
+interface LayoutResult {
+  xScale: ChartScale;
+  yScale: ReturnType<typeof scaleLinear<number, number>>;
+  /**
+   * 分类 y 比例尺。有系列声明了 `layout.yBandKey`（比如热力图的每一行）时才有，
+   * 这时 y 轴是分类轴，线性 `yScale` 用不上。
+   */
+  yBandScale?: ReturnType<typeof scaleBand<string>>;
+  resolved: Map<string, ResolvedPoint[]>;
+}
+export declare function computeLayout({ data, xKey, series, width, height, yBaseline, yDomain, xDomain }: LayoutInput): LayoutResult;
+//#endregion
+//#region src/markColor.d.ts
+/** 整个系列共用一种颜色时（line、area、band 等）的取色。 */
+export declare function seriesFill(def: SeriesDef, color: ColorAccessor | undefined): string;
+/** 每个数据点各取一色：取色函数优先，其次固定串，最后调色板。 */
+export declare function pointFill(def: SeriesDef, color: ColorAccessor | undefined, datum: Record<string, unknown>, index: number): string;
+//#endregion
+//#region src/marks/area.d.ts
+interface AreaOptions {
+  color?: string;
+  opacity?: number;
+  curve?: 'linear' | 'monotone' | 'natural' | 'step';
+  stack?: string;
+  gradient?: boolean;
+  stroke?: boolean;
+  label?: string;
+}
+/**
+ * 面积系列：线下面填色，支持堆叠和渐变。
+ *
+ * 缺失值、非有限值（包括堆叠基线断开的位置）给 NaN，画的时候留空洞，
+ * 而不是掉到 0 画成一片假的面积。
+ */
+export declare function area(dataKey: string, options?: AreaOptions): SeriesDef;
+//#endregion
+//#region src/marks/band.d.ts
+interface BandOptions {
+  upper: string;
+  lower: string;
+  color?: string;
+  opacity?: number;
+}
+/**
+ * 置信区间带：上下界之间的那条面积。
+ *
+ * 上下界缺失或不是数字时给 NaN，画的时候断成空洞，而不是塌成一条零基线。
+ * 属于标注类标记，不进图例和提示框。
+ */
+export declare function band(options: BandOptions): SeriesDef;
+//#endregion
+//#region src/marks/bar.d.ts
+interface BarOptions {
+  color?: ColorAccessor;
+  opacity?: number;
+  radius?: number;
+  stack?: string;
+  group?: string;
+  label?: string;
+}
+/**
+ * 柱状图系列。y 轴按 `includeZero` 把 0 算进范围，负值从 0 往下长。
+ *
+ * 每条柱的像素宽度和偏移取决于分组情况，由 `resolve()` 现算并记在 `slot` 里，
+ * 画的时候从同一份状态里取，所以两条路径看到的是同一个宽度。
+ */
+export declare function bar(dataKey: string, options?: BarOptions): SeriesDef;
+//#endregion
+//#region src/marks/candlestick.d.ts
+interface CandlestickOptions {
+  open: string;
+  high: string;
+  low: string;
+  close: string;
+  upColor?: string;
+  downColor?: string;
+}
+/**
+ * K 线（OHLC）系列。band 比例尺和线性/时间比例尺都能用。
+ * 点位的 y 取收盘价；缺任何一个 OHLC 字段的那根蜡烛画的时候跳过，而不是画到 0。
+ * 属于数据系列，会进图例和提示框。
+ */
+export declare function candlestick(options: CandlestickOptions): SeriesDef;
+//#endregion
+//#region src/marks/dot.d.ts
+interface DotOptions {
+  color?: ColorAccessor;
+  radius?: number;
+  opacity?: number;
+  dodge?: boolean;
+  label?: string;
+}
+/**
+ * 散点系列。
+ *
+ * 缺失值和非有限值给 NaN，画的时候跳过，不会落到基线上。开了 `dodge` 会把落在
+ * 同一 x 上的点横向错开，错开时不管非有限的点，一个缺失值不会把整组挤歪。
+ */
+export declare function dot(dataKey: string, options?: DotOptions): SeriesDef;
+//#endregion
+//#region src/marks/errorBar.d.ts
+interface ErrorBarOptions {
+  /** 上界的数据列 */
+  high: string;
+  /** 下界的数据列 */
+  low: string;
+  /** 描边颜色 */
+  color?: string;
+  /** 描边宽度 */
+  strokeWidth?: number;
+  /** 须线两端小横杠的宽度（像素） */
+  capWidth?: number;
+}
+/**
+ * 误差条（须线）系列：上下界是绝对值，所以不对称的区间也能画。
+ * 配对 `bar()` 或 `dot()` 用。缺任何一侧上下界的点画的时候跳过，
+ * 而不是贴着坐标轴画一根误导人的零高度须线。
+ * 属于标注类标记，不进图例和提示框。
+ *
+ * @example
+ * ```
+ * series={[bar('mean'), errorBar({high: 'upper95', low: 'lower95'})]}
+ * ```
+ */
+export declare function errorBar(options: ErrorBarOptions): SeriesDef;
+//#endregion
+//#region src/marks/line.d.ts
+type CurveType = 'linear' | 'monotone' | 'natural' | 'step';
+interface LineOptions {
+  color?: string;
+  curve?: CurveType;
+  strokeWidth?: number;
+  dots?: boolean;
+  label?: string;
+}
+/**
+ * 折线系列。
+ *
+ * 缺失值和非有限值给 NaN，画的时候会断开（而不是掉到基线画出一条假线），
+ * 逐点的小圆点也只画在有限的位置上。
+ */
+export declare function line(dataKey: string, options?: LineOptions): SeriesDef;
+//#endregion
+//#region src/marks/referenceLine.d.ts
+interface ReferenceLineOptions {
+  /** 在这个 y 值处画一条横线 */
+  y?: number;
+  /** 第二个 y 值——在 y 和 y2 之间涂一条带 */
+  y2?: number;
+  /** 在这个 x 值处画一条竖线 */
+  x?: number;
+  /** 线或带的颜色 */
+  color?: string;
+  /** 描边宽度（画线时用） */
+  strokeWidth?: number;
+  /** 虚线样式 */
+  strokeDasharray?: string;
+  /** 文字标签 */
+  label?: string;
+  /** 标签位置 */
+  labelPosition?: 'start' | 'end';
+  /** 涂带的透明度（设了 y2 时用） */
+  bandOpacity?: number;
+}
+/**
+ * 横向或纵向的参考线、参考带。它不是数据系列，画在固定的数值上。
+ *
+ * 画的位置要现算（取决于比例尺、绘图区大小和标签宽度），所以这个工厂没有点位可算，
+ * `resolve()` 永远返回空数组——所有几何都在 `render()` 里。
+ * 标签牌会被夹在绘图区内（绘图区本身是裁切的），横竖两个方向都一样。
+ */
+export declare function referenceLine(options: ReferenceLineOptions): SeriesDef;
+//#endregion
+//#region src/utils.d.ts
+/** 判断一个比例尺是不是 d3 的 band 比例尺（分类轴上每个类占一条「带」）。 */
+export declare function isBandScale(scale: ChartScale): scale is ScaleBand<string>;
+/**
+ * 算出一条数据在 x 方向的像素位置。band 比例尺返回这条「带」的中心。
+ *
+ * 非 band 比例尺走数值路径：有限数字直接用，Date 和数字字符串也照 d3 的规则转换。
+ * 转出来不是有限值的（读不成数字、或者原始值就是 ±Infinity）一律给 NaN——标记看到
+ * NaN 会跳过这个点（画在画布外），而不是照 d3 的换算画到某个错位置。
+ */
+export declare function xPixel(d: Record<string, unknown>, xKey: string, xScale: ChartScale): number;
+//#endregion
+export { type AreaOptions, type BandOptions, type BarOptions, type CandlestickOptions, type CardPositionInput, _default as Chart, _default$1 as ChartAxis, type ChartAxisPosition, type ChartAxisProps, type ChartColorsAPI, type ChartContext, _default$2 as ChartGrid, type ChartGridProps, _default$3 as ChartLegend, type ChartLegendConfig, type ChartLegendProps, type ChartLocale, type ChartMargin, type ChartPointerEvent, type ChartProps, type ChartScale, type ChartSlots, _default$4 as ChartSwatch, type ChartSwatchProps, type ChartSwatchVariant, _default$5 as ChartTooltip, type ChartTooltipConfig, type ChartTooltipPlacement, type ChartTooltipProps, type ChartTooltipSlots, type ColorAccessor, type DotOptions, type ErrorBarOptions, type LayoutInput, type LayoutResult, type LegendAlignment, type LegendItem, type LegendPosition, type LineOptions, type RGBA, type ReferenceLineOptions, type ResolvedPoint, type ResolvedPositions, type SequentialHue, type SeriesContext, type SeriesDef, type TokenResolver, type TooltipSeriesValue, type YBaseline };