@icen.ai/ui 0.8.1 → 0.10.0

package/dist/behaviors/datatable.d.mts

@@ -1,6 +1,24 @@
 import { ContextMenuItem } from './context-menu.js';
+import './icons.js';
 import './popover.js';
 
+type TableFrozenSide = 'left' | 'right';
+/** 行分组聚合器：内置五种 + 自定义函数（收数字数组，返回展示串） */
+type TableAggregate = 'sum' | 'avg' | 'count' | 'min' | 'max' | ((values: number[]) => string);
+/** 单元格编辑类型：true = 'text' */
+type TableCellEditable = boolean | 'text' | 'number' | 'select';
+/** select 编辑器选项（纯字符串或 value/label 对） */
+type TableEditOption = string | {
+    value: string;
+    label: string;
+};
+/** 排序栈条目（sorts[0] = 主排序） */
+interface TableSortEntry {
+    key: string;
+    dir: 'asc' | 'desc';
+}
+/** 汇总行逐列规格；'label' = 显示「合计」 */
+type TableSummarySpec = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'label';
 interface TableColumn<Row = Record<string, unknown>> {
     key: string;
     title: string;
@@ -14,8 +32,14 @@ interface TableColumn<Row = Record<string, unknown>> {
     /** 返回 Node 可嵌套任意组件；返回 string/number 走 textContent（安全） */
     render?: (value: unknown, row: Row, rowIndex: number) => Node | string | number | null;
     hidden?: boolean;
-    /** 冻结列（左固定，横向滚动时不跟随） */
-    frozen?: boolean;
+    /** 冻结列：true/'left' 左固定（默认），'right' 右固定（横向滚动不跟随） */
+    frozen?: boolean | TableFrozenSide;
+    /** 行分组聚合器（groupBy 开启时组头摘要 chip；summaryRow: true 时同名复用） */
+    aggregate?: TableAggregate;
+    /** 单元格编辑：true/'text' 文本；'number' 数字（非法值抖动不提交）；'select' 需 editOptions */
+    editable?: TableCellEditable;
+    /** select 编辑器选项 */
+    editOptions?: TableEditOption[];
 }
 interface TableOptions<Row = Record<string, unknown>> {
     columns: TableColumn<Row>[];
@@ -49,11 +73,22 @@ interface TableOptions<Row = Record<string, unknown>> {
     columnVisibility?: boolean;
     /** 导出 CSV 按钮显示在工具栏（默认 false） */
     exportable?: boolean;
+    /** 多列排序：Shift+点击表头追加次级排序，徽标显示优先级（单点击行为与单排序完全一致） */
+    multiSort?: boolean;
+    /** 表头拖拽列重排（冻结/非冻结分区互不跨越；完成派 icen:table-column-reorder） */
+    reorderable?: boolean;
+    /** 行分组：字段名或函数 → 组头行（组名 + 计数 + 聚合 chip，点击折叠，状态跨 setData 保持） */
+    groupBy?: keyof Row | ((row: Row) => string);
+    /** 汇总行：true 按各列 aggregate 汇总；或逐列规格（'label' 列显示「合计」）。
+     *  数据口径 = 当前管线（搜索/筛选后、分页前）。 */
+    summaryRow?: boolean | Record<string, TableSummarySpec>;
     /** 行自定义 class（条件着色 / 状态行） */
     rowClassName?: (row: Row, index: number) => string;
     onSelectionChange?: (rows: Row[]) => void;
     onRowClick?: (row: Row) => void;
     onSortChange?: (key: string | null, dir: 'asc' | 'desc') => void;
+    /** 单元格编辑提交（与 icen:table-cell-edit 双通道；宿主决定是否采纳：调 handle.updateCell 或 setData） */
+    onCellEdit?: (rowKey: string, field: string, value: unknown, row: Row) => void;
     /** 搜索谓词（默认跨列 String includes；自定义拼音/高亮/索引匹配） */
     searchFn?: (query: string, row: Row) => boolean;
     /** 服务端/受控分页：开启后翻页只派事件与回调，不再本地切片（配 totalCount + setData/setPage 喂数） */
@@ -71,6 +106,14 @@ interface TableHandle<Row = Record<string, unknown>> {
     /** values=null 清除该列筛选 */
     setFilter(key: string, values: string[] | null): void;
     setSort(key: string | null, dir?: 'asc' | 'desc'): void;
+    /** 当前排序栈（[0] = 主排序）；返回副本，改之不影响内部状态 */
+    getSorts(): TableSortEntry[];
+    /** 整体替换排序栈（与 setSort 同纪律：不派 icen:table-sort-change，只回调 onSortChange） */
+    setSorts(sorts: TableSortEntry[]): void;
+    /** 列重排：把 key 移到当前可见列序的 toIndex（冻结分区约束内自动夹取；派 icen:table-column-reorder） */
+    moveColumn(key: string, toIndex: number): void;
+    /** 采纳编辑值：按行键写回 data 并重渲（宿主在 onCellEdit / icen:table-cell-edit 里调用） */
+    updateCell(rowKey: string, field: string, value: unknown): void;
     /** 获取当前管线（搜索→筛选→排序）后的数据 */
     getData(): Row[];
     /** 导出当前管线数据为 CSV 并触发下载 */
@@ -85,6 +128,13 @@ interface TableHandle<Row = Record<string, unknown>> {
     refresh(): void;
     destroy(): void;
 }
+/**
+ * 计算各聚合列的展示值（纯函数）。
+ * - sum/avg/min/max：只统计可转数字的值（字符串数字计入；空/非数字跳过），无有效值 → '—'
+ * - count：非空值计数（null/undefined/'' 跳过），与类型无关
+ * - 自定义函数：收数字数组（同一口径过滤后），返回串由宿主决定
+ */
+declare function computeAggregates<Row = Record<string, unknown>>(rows: Row[], columns: Array<TableColumn<Row>>): Record<string, string>;
 declare function createTable<Row = Record<string, unknown>>(el: HTMLElement, opts: TableOptions<Row>): TableHandle<Row>;
 
-export { type TableColumn, type TableHandle, type TableOptions, createTable };
+export { type TableAggregate, type TableCellEditable, type TableColumn, type TableEditOption, type TableFrozenSide, type TableHandle, type TableOptions, type TableSortEntry, type TableSummarySpec, computeAggregates, createTable };