@icen.ai/ui 0.9.0 → 0.10.0

package/dist/behaviors/charts.d.mts

@@ -1,4 +1,4 @@
-/** 色调名：内置 5 语义名（经 --token-* 取色）；`string & {}` 保自动补全同时放行 registerChartTone 注册的命名档 */
+/** 色调名：内置 5 语义名（经 --icen-token-* 取色）；`string & {}` 保自动补全同时放行 registerChartTone 注册的命名档 */
 type ChartTone = 'accent' | 'success' | 'warning' | 'error' | 'muted' | (string & {});
 interface ChartSeriesOptions extends ChartChromeOptions {
     labels: string[];
@@ -31,6 +31,14 @@ interface ChartSegmentsOptions extends ChartChromeOptions {
  * spec.series[0].tone = 'brand';
  */
 declare function registerChartTone(name: string, cssVar: string): void;
+/**
+ * Largest-Triangle-Three-Buckets 降采样（纯函数）。
+ * 大点数序列渲染前的视觉保形抽样：保端点、保序（抽样序号严格递增）、
+ * 峰值/谷值优先保留。threshold < 3 或 ≥ 长度时原样返回（不抽样）。
+ * 标准实现（Steinarsson 2013）：首点与末点必留，中间每桶取与
+ * 「前保点 + 下一桶质心」构成三角形面积最大的点。
+ */
+declare function lttb<T>(points: T[], threshold: number, getX: (p: T) => number, getY: (p: T) => number): T[];
 /** 多系列系列项（ChartSpec 的 series 与各图型共用形态）；tone 可为语义名或调色盘序号 1..6 */
 interface ChartSeriesSpec {
     name: string;
@@ -118,7 +126,7 @@ interface ChartHeatmapOptions extends ChartChromeOptions {
     /** 列数（周），默认按数据量推算（向上取整到整周） */
     weeks?: number;
     tone?: ChartTone;
-    /** 本地化：周首日（0=周日，默认 1=周一；与 date-picker 的 data-date-picker-week-start 语义对齐）与标签文案（纯字符串，保持 JSON 可序列化） */
+    /** 本地化：周首日（0=周日，默认 1=周一；与 date-picker 的 data-icen-date-picker-week-start 语义对齐）与标签文案（纯字符串，保持 JSON 可序列化） */
     weekStart?: 0 | 1;
     labels?: ChartI18nLabels;
     emptyLabel?: string;
@@ -145,7 +153,7 @@ interface ChartCalendarOptions extends ChartChromeOptions {
     /** 精确形态：{date, value}[]（与 dates+values 二选一，优先） */
     data?: HeatmapDatum[];
     tone?: ChartTone;
-    /** 本地化：周首日（0=周日，默认 1=周一；与 date-picker 的 data-date-picker-week-start 语义对齐）与标签文案（纯字符串，保持 JSON 可序列化） */
+    /** 本地化：周首日（0=周日，默认 1=周一；与 date-picker 的 data-icen-date-picker-week-start 语义对齐）与标签文案（纯字符串，保持 JSON 可序列化） */
     weekStart?: 0 | 1;
     labels?: ChartI18nLabels;
     emptyLabel?: string;
@@ -194,6 +202,27 @@ interface ChartDims {
     /** 散点 size 字段（默认 'size'） */
     size?: string;
 }
+/** 标记线语义色（纯 JSON；缺省 muted 参考线） */
+type ChartMarkTone = 'success' | 'warning' | 'error' | 'info';
+/**
+ * 图表标记（纯 JSON，可序列化）：
+ * - line：参考线——axis 'y' 画水平线（value 为数值），axis 'x' 画垂直线（value 为类目名或索引）；
+ * - point：标记点——label 定位类目，seriesIndex 选系列（缺省首系列），value 可覆盖纵轴值，text 为标注文案。
+ * 无效标记（类目不存在 / 值 NaN）跳过并 console.warn 一次，不炸渲染。
+ */
+type ChartMark = {
+    type: 'line';
+    axis: 'y' | 'x';
+    value: number | string;
+    label?: string;
+    tone?: ChartMarkTone;
+} | {
+    type: 'point';
+    label: string;
+    seriesIndex?: number;
+    value?: number;
+    text?: string;
+};
 /** 统一图表规格（纯 JSON；type 缺省由 inferChartType 推断） */
 interface ChartSpec {
     type?: string;
@@ -235,13 +264,24 @@ interface ChartSpec {
     i18n?: ChartI18nLabels & {
         weekStart?: 0 | 1;
     };
+    /** 大点数降采样（LTTB，仅 line/area/scatter 生效；vbar 类目语义不降采样）：
+     * true → 阈值 1000；number → 自定阈值。发生抽样时头部行显示 faint 提示「已抽样 N→M 点」 */
+    downsample?: boolean | number;
+    /** 缩放/刷选（仅 line/area/vbar 生效）：'x' 横向拖选；'brush' 自由框选（仍按类目索引区间切片）。
+     * 拖拽选区松开后按像素→类目索引映射重渲，派 icen:chart-zoom { chart, from, to }；
+     * 头部出现「重置缩放」chip，双击 plot 也复原 */
+    zoom?: 'x' | 'brush';
+    /** 标记线/标记点（line/area/vbar 生效；无效项跳过 + warn 一次） */
+    marks?: ChartMark[];
+    /** 加载态：渲染骨架 shimmer（优先于空态） */
+    loading?: boolean;
 }
 /** 格式化描述符 → 函数（底层渲染器的 formatValue 槽） */
 declare function chartFormatValue(format?: ChartValueFormat): (value: number) => string;
 /**
  * 归一化 ChartSpec：字符串输入尝试 JSON.parse；类型别名纠正；数值容错转换；
  * data[] + dims pivot 到 labels/values/series/points。不抛异常——纠不了的
- * 字段丢弃，返回的 spec 一定可交给 infer/render（空数据走 .chart-empty）。
+ * 字段丢弃，返回的 spec 一定可交给 infer/render（空数据走 .icen-chart-empty）。
  */
 declare function normalizeChartSpec(raw: unknown): ChartSpec;
 /** 未指定 type 时的自动选型（确定性规则，AI 只给数据也能画对） */
@@ -267,19 +307,35 @@ interface ChartHandle {
     update(next: ChartSpec | unknown): void;
     /** icen:chart-<name> 监听糖（hover/click/dblclick/contextmenu）；返回解绑函数 */
     on(name: ChartEventName, listener: (detail: ChartEventDetail, event: Event) => void): () => void;
+    /**
+     * 流式追加（line/area/vbar）：复用当前 spec 对象 push 类目与点后重渲（交互委托不动），
+     * 超出 maxPoints 时头部淘汰；缩放窗开启时跟随尾部；与 downsample 同开时重渲后重新降采样。
+     * 非生效类型 no-op + console.warn 一次。
+     */
+    append(label: string, values: number[], opts?: {
+        maxPoints?: number;
+    }): void;
+    /**
+     * 导出 PNG dataURL（SVG 序列化 → canvas 按 scale 光栅化，默认 2x）。
+     * 诚实不抛：SSR / 无 canvas / 纯 DOM 图型（vbar 等无 SVG）返回 undefined；
+     * SVG→Image 光栅化异步——首次调用触发绘制返回 undefined，完成后同 scale 再次调用取回。
+     */
+    toDataURL?(opts?: {
+        scale?: number;
+    }): string | undefined;
     /** 清空渲染并解绑交互委托（destroy 后可重新 renderChart） */
     destroy(): void;
 }
 /**
  * 在图表容器上挂交互委托（幂等，沿用 __icenChartBound 标记）：pointer / click /
- * dblclick / contextmenu 归一到 [data-chart-mark] 标记 → icen:chart-hover
+ * dblclick / contextmenu 归一到 [data-icen-chart-mark] 标记 → icen:chart-hover
  * （phase enter/move/leave）/ icen:chart-click / icen:chart-dblclick /
  * icen:chart-contextmenu（均 bubbles，detail 含 index/seriesIndex/seriesName/
  * label/value/指针坐标；右键默认 preventDefault），内置 tooltip portal 跟随指针。
  *
  * renderChart 内部即调它；12 个底层渲染器（renderVBar…renderScatter）收尾也会
  * 自动调用——**直调底层渲染器同样能收 icen:chart-\* 事件**，无需经过 renderChart
- * （detail.chart 报该渲染器的图型）。容器已处于某个绑定了委托的外层图表容器
+ * （detail.icen-chart 报该渲染器的图型）。容器已处于某个绑定了委托的外层图表容器
  * 内时自动跳过（renderChart → 底层渲染器路径，外层已覆盖该子树，防重复派发）。
  * 返回解绑函数（移除全部监听并复位标记；解绑后可重新 bind / 重新渲染）。
  */
@@ -289,7 +345,15 @@ declare function bindChartEvents(root: HTMLElement): () => void;
  * 渲染器，并在 el 上挂交互委托（hover/click/dblclick/contextmenu → icen:chart-*，
  * bubbles，detail 含 index/seriesIndex/seriesName/label/value/指针坐标）与可选
  * tooltip（spec.tooltip !== false 时 portal 跟随指针；右键默认 preventDefault）。
- * spec.title 有值时渲染 .chart-title。返回 { el, spec, update, on, destroy }。
+ * spec.title 有值时渲染 .icen-chart-title。返回 { el, spec, update, append, on, toDataURL, destroy }。
+ *
+ * 重度数据场景（spec 纯 JSON 直接可给）：
+ * - loading：骨架 shimmer（优先于空态，根挂 .is-loading）；
+ * - downsample：line/area/scatter 的 LTTB 降采样，抽样时头部行 faint 提示「已抽样 N→M 点」；
+ * - zoom('x'|'brush')：line/area/vbar 拖选缩放，派 icen:chart-zoom { chart, from, to }
+ *   （类目索引区间含端点），头部「重置缩放」chip / 双击 plot 复原；位移 <5px 视为点击；
+ * - marks：line/area/vbar 标记线/标记点（无效项跳过 + warn 一次）；
+ * - append(label, values, { maxPoints })：line/area/vbar 流式追加（头部淘汰 + 缩放窗跟尾）。
  */
 declare function renderChart(el: HTMLElement, raw: ChartSpec | unknown): ChartHandle;
 /** 图谱节点（GraphRAG 实体）。weight 缺省以度中心性（邻边数）参与定尺寸 */
@@ -395,4 +459,4 @@ declare function renderGraph(el: HTMLElement, raw: GraphSpec | unknown): DatumCh
  */
 declare function renderMap(el: HTMLElement, raw: MapSpec | unknown): DatumChartHandle<MapSpec>;
 
-export { type ChartCalendarOptions, type ChartChromeOptions, type ChartDatum, type ChartDatumDetail, type ChartDims, type ChartEventDetail, type ChartEventName, type ChartGaugeOptions, type ChartHandle, type ChartHeatmapOptions, type ChartI18nLabels, type ChartLineOptions, type ChartMarkData, type ChartPointSpec, type ChartRadarOptions, type ChartScatterOptions, type ChartSegment, type ChartSegmentsOptions, type ChartSeriesOptions, type ChartSeriesSpec, type ChartSpec, type ChartTone, type ChartType, type ChartVBarOptions, type ChartValueFormat, type DatumChartHandle, type GraphEdgeSpec, type GraphLayoutOptions, type GraphNodeSpec, type GraphSpec, type HeatmapDatum, type MapPointSpec, type MapSpec, type RadarSeries, bindChartEvents, chartFormatValue, inferChartType, layoutGraph, normalizeChartSpec, registerChartTone, renderArea, renderCalendar, renderChart, renderDonut, renderGauge, renderGraph, renderHBar, renderHeatmap, renderLine, renderMap, renderRadar, renderScatter, renderSparkline, renderStack, renderVBar };
+export { type ChartCalendarOptions, type ChartChromeOptions, type ChartDatum, type ChartDatumDetail, type ChartDims, type ChartEventDetail, type ChartEventName, type ChartGaugeOptions, type ChartHandle, type ChartHeatmapOptions, type ChartI18nLabels, type ChartLineOptions, type ChartMark, type ChartMarkData, type ChartMarkTone, type ChartPointSpec, type ChartRadarOptions, type ChartScatterOptions, type ChartSegment, type ChartSegmentsOptions, type ChartSeriesOptions, type ChartSeriesSpec, type ChartSpec, type ChartTone, type ChartType, type ChartVBarOptions, type ChartValueFormat, type DatumChartHandle, type GraphEdgeSpec, type GraphLayoutOptions, type GraphNodeSpec, type GraphSpec, type HeatmapDatum, type MapPointSpec, type MapSpec, type RadarSeries, bindChartEvents, chartFormatValue, inferChartType, layoutGraph, lttb, normalizeChartSpec, registerChartTone, renderArea, renderCalendar, renderChart, renderDonut, renderGauge, renderGraph, renderHBar, renderHeatmap, renderLine, renderMap, renderRadar, renderScatter, renderSparkline, renderStack, renderVBar };