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

package/dist/table/DataTableView.d.ts

@@ -0,0 +1,328 @@
+import * as css from '@zerodep-dev/vue-tsx-pro-tsx/styles';
+import { type VNodeChild } from 'vue';
+import { type ButtonBaseProps } from '../base/ButtonBase';
+import { type IconButtonProps } from '../base/IconButton';
+import { type EmptyProps } from '../feedback/Empty';
+import { type ProgressProps } from '../feedback/Progress';
+import { type SkeletonShapeProps } from '../feedback/Skeleton';
+import { type CheckboxProps } from '../input/Checkbox';
+import { type RadioProps } from '../input/Radio';
+import { type ScrollAreaProps } from '../layout/ScrollArea';
+import { type PartProps } from '../utils/props';
+import type { SelectionModes } from '../utils/data/selection';
+import type { VirtualScrollOptions, VisibleRange } from '../utils/virtual/virtualizer';
+import { type ColumnMenuActions } from './ColumnHeaderActions';
+import { type ColumnResizerProps } from './ColumnResizer';
+import { type ColumnFilterOption, type DataTableColumnGroup, type SortState, type StickyOffsets, type DataTableColumn } from './columns';
+import { type DataTableDensities, type DataTableOptions, type DataTableVariants } from './table-styles';
+/** 要渲染的一行：DataTable 是平铺的行，TreeDataTable 是展开后的树（带层级） */
+export interface DataTableRowModel<T> {
+    /** 行的 key（选择、展开、测量都按它） */
+    key: string;
+    /** 这一行的数据 */
+    data: T;
+    /** 层级（TreeDataTable），从 0 开始 */
+    depth: number;
+}
+/** 行、单元格的部件属性：可以按行（与列）计算 */
+type RowPartProps<T> = PartProps<'tr'> | ((row: T, index: number) => PartProps<'tr'>);
+type CellPartProps<T> = PartProps<'td'> | ((row: T, column: DataTableColumn<T>) => PartProps<'td'>);
+/** DataTableView 的属性；未声明的属性落到 table 上（aria-label 或 aria-labelledby 是表格的名称） */
+export interface DataTableViewProps<T> extends PartProps<'table', 'role'>, DataTableOptions {
+    /** 要渲染的行（已排序、已按展开状态展开） */
+    rows: readonly DataTableRowModel<T>[];
+    /** 列 */
+    columns: readonly DataTableColumn<T>[];
+    /** 当前排序：一列，或多列（前面的优先） */
+    sort?: SortState | readonly SortState[] | null;
+    /** 点了可排序的列标题（多列排序时按住 Shift 是追加） */
+    onSortClick?: (key: string, event: MouseEvent) => void;
+    /** 表头筛选：各列选中的值（列定义写了 filter 的列，列标题上有筛选按钮） */
+    filters?: Readonly<Record<string, readonly string[]>>;
+    /** 改了一列的筛选 */
+    onFilterChange?: (key: string, values: string[]) => void;
+    /** 表头筛选的选项（列出出现过的值时要看全部行，由外层给） */
+    filterOptionsOf?: (column: DataTableColumn<T>) => readonly ColumnFilterOption[];
+    /** 列菜单：列标题结尾多一个 ⋮，排序、固定、移动、隐藏，选了交给 onColumnAction */
+    columnMenu?: boolean;
+    /** 选了列菜单里的一项；width 是这一列现在的宽度（固定没写宽度的列时，外层把它记成列宽） */
+    onColumnAction?: (key: string, action: keyof ColumnMenuActions, width: number) => void;
+    /** 单元格导航：表格是 role="grid"，方向键在格之间走，只有一格能 Tab 进入；有可编辑的列时默认开 */
+    cellNavigation?: boolean;
+    /** 正在编辑的格 */
+    editing?: CellPosition | null;
+    /** 正在编辑的格里放的编辑器 */
+    renderEditor?: (row: T, column: DataTableColumn<T>) => VNodeChild;
+    /** 各行的校验错误：列的 key → 原因（行校验，如“结束日期早于开始日期”），标在格上 */
+    rowErrors?: (row: T) => Readonly<Record<string, string>> | null | undefined;
+    /** 在可编辑的格上按 Enter / F2、双击，或直接打字（text 是打的字，替换原值）：开始编辑 */
+    onEditStart?: (cell: CellPosition, text?: string) => void;
+    /** 编辑中的按键（Enter 提交、Tab 提交并到下一格、Esc 放弃），由外层处理 */
+    onEditKeydown?: (event: KeyboardEvent, cell: CellPosition) => void;
+    /** 选择方式；不写时没有勾选列。多选时表头有全选 */
+    selectionMode?: keyof SelectionModes;
+    /** 已选行的 key */
+    selectedKeys?: readonly string[];
+    /** 部分勾选的行的 key（树形表格的父行：子孙只勾了一部分）：勾选框显示横线，读屏念“部分选中” */
+    partialKeys?: readonly string[];
+    /** 勾选或取消一行 */
+    onToggleRow?: (key: string) => void;
+    /** 表头的全选：全部选中时取消全部，否则全选 */
+    onToggleAll?: () => void;
+    /** 各列当前的宽度（px）：拖动调整过的、或列定义里写的 */
+    widths: Readonly<Record<string, number | undefined>>;
+    /** 拖动或用键盘调整了某列的宽度 */
+    onResize?: (key: string, width: number) => void;
+    /** 列宽可以调整（列定义里的 resizable 优先） */
+    resizable?: boolean;
+    /** 加载中 */
+    loading?: boolean;
+    /** 没有数据时显示的内容；默认是 Empty（文案取语言包） */
+    empty?: VNodeChild;
+    /** 第一个数据列的单元格内容前面加的东西（TreeDataTable 的缩进与展开按钮） */
+    leading?: (row: DataTableRowModel<T>, index: number) => VNodeChild;
+    /** 行的估计高度（px）；不写时按密度估计，渲染后以实际高度为准 */
+    estimateRowHeight?: number;
+    /** 行的色调：导入校验的错误行、即将超期的行整行着浅色底（不透明，固定列也盖得住） */
+    rowTone?: (row: T) => RowTone | undefined;
+    /** 主从视图里正在看的那一行的 key：整行高亮、起始边一条竖线，带 aria-current */
+    activeKey?: string | null;
+    /**
+     * 点了一行（点在按钮、链接、输入框上的除外）：主从视图里打开这一行的详情。
+     * 只是鼠标的捷径：行里还要有键盘能到的入口（如名称做成按钮或链接）
+     */
+    onRowClick?: (row: T, key: string) => void;
+    /** 这一行能不能勾选：不能的勾选框不可用，全选也跳过它 */
+    isRowSelectable?: (row: T) => boolean;
+    /** 隐藏的列的 key：列显示设置（用 Menu 的 MenuCheckboxItem 组合）写回这里 */
+    hiddenColumns?: readonly string[];
+    /** 合计行第一列的文字（第一列自己没写 summary 时），默认取语言包（合计） */
+    summaryLabel?: VNodeChild;
+    /** 分组表头：相邻的几列上方共用一个标题，表头变成两行；没分组的列跨两行 */
+    columnGroups?: readonly DataTableColumnGroup[];
+    /** 行的详情：写了它时多一列展开按钮，展开的行下面多一行跨全部列的详情 */
+    renderDetail?: (row: T) => VNodeChild;
+    /** 这一行有没有详情：没有的不显示展开按钮；默认都有 */
+    hasDetail?: (row: T) => boolean;
+    /** 展开了详情的行的 key */
+    expandedRows?: readonly string[];
+    /** 点了一行的展开按钮 */
+    onToggleDetail?: (key: string) => void;
+    /** 可见行范围变化（不含 overscan）：接近末尾时加载更多 */
+    onRangeChange?: (range: VisibleRange) => void;
+    /** 挂载后拿到滚动到某一行的方法：`handle={(api) => (table = api)}` */
+    handle?: (api: DataTableHandle) => void;
+    /**
+     * 放在竖排的弹性容器（ViewportFill、Flex direction="column"）里：按行数自己的高度，最多占到剩下的高度，
+     * 再多在表格里滚动；分页紧跟在表格下面。不写时最高 32em
+     */
+    flexible?: boolean;
+    /** 外层滚动区域（决定表格的高度）的部件属性；高度用 sx 给，默认最高 32em */
+    propsRoot?: Partial<ScrollAreaProps>;
+    /** 每一行（tr）的部件属性，可以按行计算 */
+    propsRow?: RowPartProps<T>;
+    /** 每个单元格（td）的部件属性，可以按行与列计算 */
+    propsCell?: CellPartProps<T>;
+    /** 每个列标题（th）的部件属性，可以按列计算 */
+    propsHeaderCell?: PartProps<'th'> | ((column: DataTableColumn<T>) => PartProps<'th'>);
+    /** 空状态的部件属性 */
+    propsEmpty?: Partial<EmptyProps>;
+    /** 加载中占位的部件属性 */
+    propsSkeleton?: SkeletonShapeProps;
+    /** 分组标题（th，跨组里的几列）的部件属性，可以按组计算 */
+    propsGroupHeaderCell?: PartProps<'th'> | ((group: DataTableColumnGroup) => PartProps<'th'>);
+    /** 可排序列标题里的排序按钮的部件属性 */
+    propsSortButton?: Partial<ButtonBaseProps>;
+    /** 列宽调整手柄的部件属性 */
+    propsResizer?: Partial<ColumnResizerProps>;
+    /** 可排序列标题里的文字（排序按钮里、图标前）的部件属性 */
+    propsSortLabel?: PartProps<'span'>;
+    /** 表头（thead，吸顶）的部件属性 */
+    propsHead?: PartProps<'thead'>;
+    /** 表头的行（tr）的部件属性；分组表头的两行都用它 */
+    propsHeadRow?: PartProps<'tr', 'aria-rowindex'>;
+    /** 表头勾选列（th，多选时里面是全选框）的部件属性 */
+    propsSelectHeaderCell?: PartProps<'th', 'scope'>;
+    /** 每行勾选列（td）的部件属性 */
+    propsSelectCell?: PartProps<'td'>;
+    /** 表头的全选框（多选时）的部件属性；勾选状态、不可用与切换由组件管理 */
+    propsSelectAll?: Omit<Partial<CheckboxProps>, SelectCheckboxManaged | 'disabled'>;
+    /** 每一行的勾选框（多选时）的部件属性；勾选状态、切换与名称（选择第 N 行，每行不同）由组件管理 */
+    propsSelectCheckbox?: Omit<Partial<CheckboxProps>, SelectCheckboxManaged | 'aria-label'>;
+    /** 每一行的单选框（单选时）的部件属性；选中状态、切换与名称由组件管理 */
+    propsSelectRadio?: Omit<Partial<RadioProps>, 'value' | 'disabled' | 'aria-label'>;
+    /** 第一个数据列里 leading 与内容的外层（有 leading 时才有）的部件属性 */
+    propsLeading?: PartProps<'div'>;
+    /** 第一个数据列里内容的包装（有 leading 时才有）的部件属性 */
+    propsContent?: PartProps<'div'>;
+    /** 刷新中表头下方的进度条的部件属性 */
+    propsProgress?: Partial<ProgressProps>;
+    /** 空状态所在的单元格（td，跨全部列）的部件属性 */
+    propsEmptyCell?: PartProps<'td', 'colspan'>;
+    /** 详情列的列标题（th，文字只给读屏）的部件属性 */
+    propsDetailHeaderCell?: PartProps<'th', 'scope'>;
+    /** 每行展开按钮所在单元格（td）的部件属性 */
+    propsDetailToggleCell?: PartProps<'td'>;
+    /** 展开按钮的部件属性；展开状态、关联的详情与点击由组件管理 */
+    propsDetailToggle?: Omit<Partial<IconButtonProps>, 'aria-expanded' | 'aria-controls' | 'onClick'>;
+    /** 详情行（tr）的部件属性 */
+    propsDetailRow?: PartProps<'tr', 'aria-rowindex'>;
+    /** 详情所在的单元格（td，跨全部列）的部件属性 */
+    propsDetailCell?: PartProps<'td', 'colspan'>;
+    /** 表尾（tfoot，合计行，吸底）的部件属性 */
+    propsFoot?: PartProps<'tfoot'>;
+    /** 合计行每个单元格的部件属性，可以按列计算 */
+    propsSummaryCell?: PartProps<'td'> | ((column: DataTableColumn<T>) => PartProps<'td'>);
+}
+/** 一格的位置：行的 key 与列的 key */
+export interface CellPosition {
+    /** 行的 key */
+    row: string;
+    /** 列的 key */
+    column: string;
+}
+/** DataTable、TreeDataTable 的 handle 拿到的方法 */
+export interface DataTableHandle {
+    /**
+     * 滚动到 key 这一行：还没渲染（虚拟滚动）的行也行，停在吸顶表头之下、吸底合计行之上；
+     * align 默认 auto（已经完整可见就不动）。树形表格里只能滚到已展开的行。找不到这一行时返回 false
+     */
+    scrollToRow: (key: string, options?: VirtualScrollOptions) => boolean;
+}
+/** 行的色调：整行浅色底 */
+export type RowTone = 'info' | 'success' | 'warning' | 'danger';
+/** 勾选列里的勾选框由表格管理的属性 */
+type SelectCheckboxManaged = 'checked' | 'indeterminate' | 'onChange';
+/** DataTable、TreeDataTable 的样式：行的色调（不透明的浅色底，悬停加深） */
+export declare const dataTableRowToneStyles: Readonly<{
+    danger: css.CompiledStyles;
+    info: css.CompiledStyles;
+    success: css.CompiledStyles;
+    warning: css.CompiledStyles;
+}>;
+/** DataTable、TreeDataTable 的样式：width、minWidth、height、start、end、percent */
+export declare const dataTableDynamicStyles: Readonly<{
+    readonly width: (px: number) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+    readonly minWidth: (px: number) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+    readonly height: (px: number) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+    readonly start: (px: number) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+    readonly end: (px: number) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+    readonly indent: (px: number) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+    readonly percent: (value: string) => Readonly<[css.CompiledStyles, css.InlineStyles]>;
+}>;
+/** DataTableRow 的属性：一行要用到的全部数据；除了 row、index、selected，同一张表里各行都相同 */
+export interface DataTableRowProps<T> {
+    /** 这一行 */
+    row: DataTableRowModel<T>;
+    /** 在全部行里的序号 */
+    index: number;
+    /** 是否已选 */
+    selected: boolean;
+    /** 部分勾选（树形表格的父行） */
+    partial?: boolean;
+    /** 能不能勾选，默认 true */
+    selectable?: boolean;
+    /** 整行的色调 */
+    tone?: RowTone;
+    /** 主从视图里正在看的一行 */
+    active?: boolean;
+    /** 点了这一行 */
+    onRowClick?: (row: T, key: string) => void;
+    /** 选择方式；不写时没有勾选列 */
+    selectionMode?: keyof SelectionModes;
+    /** 列 */
+    columns: readonly DataTableColumn<T>[];
+    /** 密度 */
+    density: keyof DataTableDensities;
+    /** 样式 */
+    variant: keyof DataTableVariants;
+    /** 斑马纹 */
+    striped: boolean;
+    /** 固定列的偏移 */
+    offsets: StickyOffsets;
+    /** 表头有几行（分组表头是两行）：行的 aria-rowindex 从表头之后算起，默认 1 */
+    headerRows?: number;
+    /** 在表体里的位置（展开的详情也算一行）：测量与 aria-rowindex 用它；默认等于 index */
+    position?: number;
+    /** 表格有详情列 */
+    detailColumn?: boolean;
+    /** 这一行有详情（显示展开按钮），默认 true */
+    expandable?: boolean;
+    /** 详情已展开 */
+    expanded?: boolean;
+    /** 详情单元格的 id（展开按钮的 aria-controls） */
+    detailId?: string;
+    /** 详情列单元格的部件属性 */
+    propsDetailToggleCell?: PartProps<'td'>;
+    /** 展开按钮的部件属性 */
+    propsDetailToggle?: DataTableViewProps<T>['propsDetailToggle'];
+    /** 点了展开按钮 */
+    onToggleDetail?: (key: string) => void;
+    /** 第一个数据列前面加的东西（TreeDataTable 的缩进与展开按钮） */
+    leading?: (row: DataTableRowModel<T>, index: number) => VNodeChild;
+    /** 行的部件属性 */
+    propsRow?: RowPartProps<T>;
+    /** 单元格的部件属性 */
+    propsCell?: CellPartProps<T>;
+    /** 勾选列单元格的部件属性 */
+    propsSelectCell?: PartProps<'td'>;
+    /** 勾选框的部件属性 */
+    propsSelectCheckbox?: DataTableViewProps<T>['propsSelectCheckbox'];
+    /** 单选框的部件属性 */
+    propsSelectRadio?: DataTableViewProps<T>['propsSelectRadio'];
+    /** leading 与内容外层的部件属性 */
+    propsLeading?: PartProps<'div'>;
+    /** 内容包装的部件属性 */
+    propsContent?: PartProps<'div'>;
+    /** 测量行高（虚拟滚动） */
+    measure: (element: unknown) => void;
+    /** 勾选或取消这一行 */
+    onToggle?: (key: string) => void;
+    /** 单元格导航：数据格可以聚焦，可编辑的格响应 Enter / F2、双击、打字 */
+    cellNavigation?: boolean;
+    /** 这一行正在编辑的列 */
+    editingColumn?: string;
+    /** 正在编辑的格里放的编辑器 */
+    renderEditor?: DataTableViewProps<T>['renderEditor'];
+    /** 这一行的校验错误 */
+    rowErrors?: DataTableViewProps<T>['rowErrors'];
+    /** 开始编辑一格 */
+    onEditStart?: DataTableViewProps<T>['onEditStart'];
+    /** 编辑中的按键 */
+    onEditKeydown?: DataTableViewProps<T>['onEditKeydown'];
+}
+/**
+ * 表格的一行：单独成组件，props 没变的行在表格重新渲染时直接跳过——
+ * 滚动只挂载新进入视口的行，勾选一行只更新这一行（原来每次都重建全部可见行与其中的勾选框）
+ */
+export declare const DataTableRow: <T>(props: DataTableRowProps<T>) => import("@zerodep-dev/vue-tsx-pro-tsx").TsxNode;
+/** 行的名称（展开按钮用）：第一列的文字，没有时用行的 key */
+export declare function rowLabel<T>(columns: readonly DataTableColumn<T>[], row: DataTableRowModel<T>): string;
+/** DataTableDetailRow 的属性 */
+export interface DataTableDetailRowProps<T> {
+    /** 详情所属的行 */
+    row: DataTableRowModel<T>;
+    /** 在表体里的位置（测量与 aria-rowindex） */
+    position: number;
+    /** 表头有几行 */
+    headerRows: number;
+    /** 跨几列（全部列，含勾选列与详情列） */
+    span: number;
+    /** 勾选列与展开列的宽度（px）：内容让过它们，和第一个数据列对齐 */
+    indent: number;
+    /** 详情单元格的 id（展开按钮的 aria-controls 指向它） */
+    id: string;
+    /** 详情的内容 */
+    renderDetail: (row: T) => VNodeChild;
+    /** 详情行的部件属性 */
+    propsDetailRow?: PartProps<'tr', 'aria-rowindex'>;
+    /** 详情单元格的部件属性 */
+    propsDetailCell?: PartProps<'td', 'colspan'>;
+    /** 测量行高（虚拟滚动） */
+    measure: (element: unknown) => void;
+}
+/** 展开的详情：一行一个跨全部列的单元格；单独成组件，滚动时没变的详情不必重渲 */
+export declare const DataTableDetailRow: <T>(props: DataTableDetailRowProps<T>) => import("@zerodep-dev/vue-tsx-pro-tsx").TsxNode;
+/** 表格的渲染层：虚拟滚动的行、吸顶表头、固定列、排序、勾选、列宽调整、加载与空状态 */
+export declare const DataTableView: <T>(props: DataTableViewProps<T>) => import("@zerodep-dev/vue-tsx-pro-tsx").TsxNode;
+export {};