@icen.ai/ui 0.8.1 → 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,8 +345,118 @@ 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 缺省以度中心性（邻边数）参与定尺寸 */
+interface GraphNodeSpec {
+    id: string;
+    label?: string;
+    /** 簇 key（社区/Leiden id 等）：配色按簇索引走既有调色盘 */
+    cluster?: string;
+    /** 节点权重（映射半径 6–18px）；缺省用度数 */
+    weight?: number;
+    /** 原始元数据：事件 datum 原样回传（实体卡数据源） */
+    meta?: Record<string, unknown>;
+}
+/** 图谱边（默认无向；directed 时带箭头）。weight 映射线宽 0.6–2.5px */
+interface GraphEdgeSpec {
+    source: string;
+    target: string;
+    weight?: number;
+}
+interface GraphSpec extends ChartSpec {
+    type: 'graph';
+    nodes: GraphNodeSpec[];
+    edges: GraphEdgeSpec[];
+    /** 有向图：边带箭头（默认无向） */
+    directed?: boolean;
+    /** 簇 key → 显示名（图例 / tooltip） */
+    clusterLabels?: Record<string, string>;
+}
+/** 嵌入地图点：x/y 为预投影 2D 坐标（UMAP/t-SNE 产物；本组件只做视口缩放，不算投影） */
+interface MapPointSpec {
+    id: string;
+    x: number;
+    y: number;
+    cluster?: string;
+    label?: string;
+    meta?: Record<string, unknown>;
+}
+interface MapSpec extends ChartSpec {
+    type: 'map';
+    points: MapPointSpec[];
+    /** 簇 key → 显示名（图例） */
+    clusters?: Record<string, string>;
+}
+/** icen:chart-* 的 datum 负载：graph 命中节点 / map 命中点（meta 原样回传） */
+interface ChartDatum {
+    id: string;
+    label: string;
+    cluster?: string;
+    meta?: Record<string, unknown>;
+}
+/** graph / map 的事件 detail：既有 ChartEventDetail + datum */
+interface ChartDatumDetail extends ChartEventDetail {
+    datum?: ChartDatum;
+}
+/** graph / map 句柄（对齐 ChartHandle 形状；事件 detail 换 ChartDatumDetail） */
+interface DatumChartHandle<S extends GraphSpec | MapSpec = GraphSpec | MapSpec> {
+    el: HTMLElement;
+    /** 归一后的当前规格 */
+    spec: S;
+    /** 原地重渲染（graph 重新布局；保留事件委托与句柄） */
+    update(next: S | unknown): void;
+    /** icen:chart-<name> 监听糖（hover/click/dblclick/contextmenu）；返回解绑函数 */
+    on(name: ChartEventName, listener: (detail: ChartDatumDetail, event: Event) => void): () => void;
+    /** 清空渲染并解绑委托（destroy 后可重新渲染） */
+    destroy(): void;
+}
+interface GraphLayoutOptions {
+    /** 布局域宽（默认 320） */
+    width?: number;
+    /** 布局域高（默认 200） */
+    height?: number;
+    /** 松弛轮数（默认 300） */
+    iterations?: number;
+    /** 初始环相位偏移（度，默认 0）。无随机源——同输入 + 同 seed 必同布局 */
+    seed?: number;
+}
+/** 确定性力导向布局（纯函数，导出便于测试）：环初始化 → 松弛 → fit → id → {x, y} */
+declare function layoutGraph(nodes: Array<{
+    id: unknown;
+}>, edges: Array<{
+    source: unknown;
+    target: unknown;
+}>, opts?: GraphLayoutOptions): Map<string, {
+    x: number;
+    y: number;
+}>;
+/**
+ * 力导向知识图谱（GraphRAG 实体关系）。确定性布局（同数据同布局，无随机源）；
+ * 节点半径 6–18px（weight 归一，缺省用度中心性）、边宽 0.6–2.5px（line-soft）、
+ * 簇着色走既有调色盘（无 cluster 单色 tone）；节点拖拽 = pointer + 局部松弛
+ * 20 轮（rAF 批处理）；hover 显示节点 label（≤8 字截断）+ 内置 tooltip；
+ * 事件走既有通道 icen:chart-hover/click/dblclick/contextmenu，detail.datum =
+ * {id, label, cluster?, meta?}（点击节点回实体卡数据）。图例可点击隐藏簇
+ * （icen:chart-legend-toggle；边随任一端簇隐藏淡化）。
+ */
+declare function renderGraph(el: HTMLElement, raw: GraphSpec | unknown): DatumChartHandle<GraphSpec>;
+/**
+ * embedding 2D 散点地图：坐标为预投影值（UMAP/t-SNE 产物，本函数只做视口
+ * min-max 缩放，不算投影）；无轴刻度只留细虚线网格；点 4px 半透明
+ * （fill-opacity .7，高密度层叠可辨）；簇着色走既有调色盘 + 可点击图例。
+ * 点击点 → icen:chart-click（detail.datum = {id, label, cluster?, meta?}，
+ * 点选回 chunk）。TODO: lasso 框选（icen:chart-select + 命中列表），暂不做。
+ */
+declare function renderMap(el: HTMLElement, raw: MapSpec | unknown): DatumChartHandle<MapSpec>;
 
-export { type ChartCalendarOptions, type ChartChromeOptions, 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 HeatmapDatum, type RadarSeries, bindChartEvents, chartFormatValue, inferChartType, normalizeChartSpec, registerChartTone, renderArea, renderCalendar, renderChart, renderDonut, renderGauge, renderHBar, renderHeatmap, renderLine, 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 };