@chenzy-design/svelte 0.1.0

package/src/table/TableKbdFixture.svelte

@@ -0,0 +1,35 @@
+<!--
+  仅供 Table.kbd.test.ts（browser project）使用的键盘 e2e 夹具。
+  交互态（列带 sorter）下 Table 升级为 WAI-ARIA Grid Pattern：role=grid +
+  columnheader/gridcell + 单元格 roving tabindex。前后各放一个按钮，验证
+  Tab 进入 grid 只停在单一 roving 单元格（roving 单停靠点），而非逐格进 Tab 序。
+-->
+<script lang="ts">
+  import { LocaleProvider } from '../locale-provider/index.js';
+  import Table from './Table.svelte';
+
+  interface Row {
+    key: string;
+    name: string;
+    age: number;
+    [k: string]: unknown;
+  }
+
+  const dataSource: Row[] = [
+    { key: '1', name: 'Alice', age: 30 },
+    { key: '2', name: 'Bob', age: 25 },
+    { key: '3', name: 'Carol', age: 28 },
+  ];
+
+  // 列带 sorter → isInteractive → gridEnabled，触发 grid 键盘漫游。
+  const columns = [
+    { key: 'name', dataIndex: 'name', title: 'Name', sorter: true },
+    { key: 'age', dataIndex: 'age', title: 'Age', sorter: true },
+  ];
+</script>
+
+<LocaleProvider locale="en_US">
+  <button type="button" data-testid="before">before</button>
+  <Table {columns} {dataSource} rowKey="key" ariaLabel="Users grid" />
+  <button type="button" data-testid="after">after</button>
+</LocaleProvider>

package/src/table/grid-nav.test.ts

@@ -0,0 +1,173 @@
+import { describe, it, expect } from 'vitest';
+import {
+  buildGridCols,
+  nextGridCoord,
+  isFocusCell,
+  rovingTabindexAt,
+  type GridCoord,
+} from './grid-nav.js';
+
+// Table 交互态 Grid Pattern 二维漫游纯逻辑用例（WAI-ARIA APG Grid）。
+// 渲染层把 row=-1 当表头、0..n-1 当数据行，col 索引进 buildGridCols 扁平表。
+// 委托键盘事件无法可靠合成（红线），故对纯坐标算法做穷尽边界测试。
+
+const params = (over: Partial<Parameters<typeof nextGridCoord>[2]> = {}) => ({
+  current: { row: 0, col: 0 } as GridCoord,
+  rowCount: 5,
+  colCount: 4,
+  pageRows: 3,
+  ...over,
+});
+
+const move = (
+  key: string,
+  current: GridCoord,
+  over: Partial<Parameters<typeof nextGridCoord>[2]> = {},
+  mods: { ctrl?: boolean; meta?: boolean } = {},
+) => nextGridCoord(key, mods, params({ ...over, current }));
+
+describe('buildGridCols — 网格列扁平表', () => {
+  it('仅数据列时 1:1 映射', () => {
+    const cols = buildGridCols({ hasExpand: false, hasSelection: false, dataColumnCount: 3 });
+    expect(cols).toEqual([
+      { kind: 'data', dataCol: 0 },
+      { kind: 'data', dataCol: 1 },
+      { kind: 'data', dataCol: 2 },
+    ]);
+  });
+
+  it('expand + selection 前置占位列在数据列之前', () => {
+    const cols = buildGridCols({ hasExpand: true, hasSelection: true, dataColumnCount: 2 });
+    expect(cols.map((c) => c.kind)).toEqual(['expand', 'selection', 'data', 'data']);
+    // 第一个数据列的网格列索引 = 2（前置 2 列）
+    expect(cols.findIndex((c) => c.kind === 'data')).toBe(2);
+  });
+
+  it('仅 selection 时占位 1 列', () => {
+    const cols = buildGridCols({ hasExpand: false, hasSelection: true, dataColumnCount: 1 });
+    expect(cols.map((c) => c.kind)).toEqual(['selection', 'data']);
+  });
+});
+
+describe('roving tabindex — 单一 Tab 停靠点派生', () => {
+  it('未聚焦时表头首格 (-1,0) 为唯一 tabindex=0', () => {
+    const focus = { row: 0, col: 0, hasFocused: false };
+    expect(isFocusCell(-1, 0, focus)).toBe(true);
+    expect(rovingTabindexAt(-1, 0, focus)).toBe(0);
+    // 其余全部 -1
+    expect(rovingTabindexAt(0, 0, focus)).toBe(-1);
+    expect(rovingTabindexAt(-1, 1, focus)).toBe(-1);
+    expect(rovingTabindexAt(2, 3, focus)).toBe(-1);
+  });
+
+  it('聚焦后仅当前焦点坐标 tabindex=0，其余 -1', () => {
+    const focus = { row: 2, col: 1, hasFocused: true };
+    expect(rovingTabindexAt(2, 1, focus)).toBe(0);
+    // 同行不同列 / 同列不同行 / 表头 均 -1（整 grid 单一停靠点）
+    expect(rovingTabindexAt(2, 0, focus)).toBe(-1);
+    expect(rovingTabindexAt(1, 1, focus)).toBe(-1);
+    expect(rovingTabindexAt(-1, 0, focus)).toBe(-1);
+  });
+
+  it('聚焦后表头首格不再是停靠点', () => {
+    const focus = { row: 0, col: 0, hasFocused: true };
+    expect(isFocusCell(-1, 0, focus)).toBe(false);
+    expect(isFocusCell(0, 0, focus)).toBe(true);
+  });
+});
+
+describe('nextGridCoord — 行向漫游（↑↓）', () => {
+  it('ArrowDown 逐行下移', () => {
+    expect(move('ArrowDown', { row: 0, col: 1 })).toEqual({ row: 1, col: 1 });
+  });
+
+  it('ArrowDown 到最后一行后 clamp（不环绕）', () => {
+    expect(move('ArrowDown', { row: 4, col: 1 })).toEqual({ row: 4, col: 1 });
+  });
+
+  it('ArrowUp 从首数据行回到表头行(-1)', () => {
+    expect(move('ArrowUp', { row: 0, col: 2 })).toEqual({ row: -1, col: 2 });
+  });
+
+  it('ArrowUp 在表头行 clamp 到 -1（不越过表头）', () => {
+    expect(move('ArrowUp', { row: -1, col: 2 })).toEqual({ row: -1, col: 2 });
+  });
+
+  it('ArrowDown 从表头进入首数据行', () => {
+    expect(move('ArrowDown', { row: -1, col: 0 })).toEqual({ row: 0, col: 0 });
+  });
+});
+
+describe('nextGridCoord — 列向漫游（←→）', () => {
+  it('ArrowRight 逐列右移', () => {
+    expect(move('ArrowRight', { row: 2, col: 0 })).toEqual({ row: 2, col: 1 });
+  });
+
+  it('ArrowRight 到末列 clamp（不环绕）', () => {
+    expect(move('ArrowRight', { row: 2, col: 3 })).toEqual({ row: 2, col: 3 });
+  });
+
+  it('ArrowLeft 到首列 clamp（不环绕）', () => {
+    expect(move('ArrowLeft', { row: 2, col: 0 })).toEqual({ row: 2, col: 0 });
+  });
+});
+
+describe('nextGridCoord — Home / End（行内）', () => {
+  it('Home 跳行内首列，行不变', () => {
+    expect(move('Home', { row: 3, col: 2 })).toEqual({ row: 3, col: 0 });
+  });
+
+  it('End 跳行内末列，行不变', () => {
+    expect(move('End', { row: 3, col: 1 })).toEqual({ row: 3, col: 3 });
+  });
+});
+
+describe('nextGridCoord — Ctrl/Cmd+Home / End（表格首末）', () => {
+  it('Ctrl+Home 跳表头首格 (-1,0)', () => {
+    expect(move('Home', { row: 4, col: 3 }, {}, { ctrl: true })).toEqual({ row: -1, col: 0 });
+  });
+
+  it('Cmd+End 跳末数据行末格', () => {
+    expect(move('End', { row: 0, col: 0 }, {}, { meta: true })).toEqual({ row: 4, col: 3 });
+  });
+});
+
+describe('nextGridCoord — PageUp / PageDown（翻屏）', () => {
+  it('PageDown 下翻 pageRows 行', () => {
+    expect(move('PageDown', { row: 0, col: 1 }, { pageRows: 3 })).toEqual({ row: 3, col: 1 });
+  });
+
+  it('PageDown 越界 clamp 到末行', () => {
+    expect(move('PageDown', { row: 3, col: 1 }, { pageRows: 3 })).toEqual({ row: 4, col: 1 });
+  });
+
+  it('PageUp 上翻 pageRows 行', () => {
+    expect(move('PageUp', { row: 4, col: 2 }, { pageRows: 3 })).toEqual({ row: 1, col: 2 });
+  });
+
+  it('PageUp 越界 clamp 到表头行(-1)', () => {
+    expect(move('PageUp', { row: 1, col: 2 }, { pageRows: 3 })).toEqual({ row: -1, col: 2 });
+  });
+
+  it('PageDown 从表头落到首屏末行', () => {
+    expect(move('PageDown', { row: -1, col: 0 }, { pageRows: 3 })).toEqual({ row: 2, col: 0 });
+  });
+});
+
+describe('nextGridCoord — 非漫游键 / 边界', () => {
+  it('非漫游键返回 null（不拦截）', () => {
+    expect(move('a', { row: 0, col: 0 })).toBeNull();
+    expect(move('Tab', { row: 0, col: 0 })).toBeNull();
+    expect(move('Enter', { row: 0, col: 0 })).toBeNull();
+  });
+
+  it('空数据表（rowCount=0）下移仍 clamp 到表头行', () => {
+    expect(move('ArrowDown', { row: -1, col: 0 }, { rowCount: 0 })).toEqual({ row: -1, col: 0 });
+  });
+
+  it('不修改入参坐标对象（纯函数）', () => {
+    const cur = { row: 0, col: 0 };
+    nextGridCoord('ArrowDown', {}, params({ current: cur }));
+    expect(cur).toEqual({ row: 0, col: 0 });
+  });
+});

package/src/table/grid-nav.ts

@@ -0,0 +1,146 @@
+/**
+ * Table 交互态 Grid Pattern — 纯函数二维漫游核心（与 DOM/Svelte 无关，可单测）。
+ *
+ * 焦点坐标用「逻辑索引」表示：
+ * - row: -1 = 表头行；0..rowCount-1 = 数据行（逻辑序，与虚拟化是否渲染无关）。
+ * - col: 索引进「网格列」扁平表 [expand?, selection?, ...dataColumns]。
+ *
+ * 渲染层持有 row/col 的 $state 与命令式 focus()，本模块只据按键算「下一坐标」
+ * （WAI-ARIA APG Grid Pattern 二维漫游 + Home/End/Ctrl+Home/End/PageUp/PageDown）。
+ *
+ * See specs/components/show/Table.spec.md §6（无障碍 · grid 键盘）。
+ */
+
+import { nextRovingIndex } from '@chenzy-design/core';
+
+export type GridColKind = 'expand' | 'selection' | 'data';
+export interface GridCol {
+  kind: GridColKind;
+  /** data 列对应的原 columns 索引；非 data 列为 -1 */
+  dataCol: number;
+}
+
+export interface GridCoord {
+  /** -1 = 表头行；>=0 = 数据行逻辑索引 */
+  row: number;
+  /** 网格列索引 */
+  col: number;
+}
+
+/**
+ * 构建网格列扁平表：前置 expand / selection 占位列 + 数据列。
+ * 仅用于焦点坐标 ↔ 实际列的换算。
+ */
+export function buildGridCols(opts: {
+  hasExpand: boolean;
+  hasSelection: boolean;
+  dataColumnCount: number;
+}): GridCol[] {
+  const out: GridCol[] = [];
+  if (opts.hasExpand) out.push({ kind: 'expand', dataCol: -1 });
+  if (opts.hasSelection) out.push({ kind: 'selection', dataCol: -1 });
+  for (let i = 0; i < opts.dataColumnCount; i++) {
+    out.push({ kind: 'data', dataCol: i });
+  }
+  return out;
+}
+
+/**
+ * 某 (row,col) 是否为当前 roving 焦点格（纯函数，render 期只读）。
+ * 未聚焦过（hasFocused=false）时，首个 tab 停靠点固定为表头首格 (-1, 0)。
+ */
+export function isFocusCell(
+  row: number,
+  col: number,
+  focus: { row: number; col: number; hasFocused: boolean },
+): boolean {
+  if (!focus.hasFocused) return row === -1 && col === 0;
+  return row === focus.row && col === focus.col;
+}
+
+/**
+ * 单元格 roving tabindex：焦点格 0，其余 -1（WAI-ARIA roving，单一 Tab 停靠点）。
+ */
+export function rovingTabindexAt(
+  row: number,
+  col: number,
+  focus: { row: number; col: number; hasFocused: boolean },
+): 0 | -1 {
+  return isFocusCell(row, col, focus) ? 0 : -1;
+}
+
+export interface GridNavParams {
+  /** 当前焦点坐标 */
+  current: GridCoord;
+  /** 数据行数（不含表头） */
+  rowCount: number;
+  /** 网格列数 */
+  colCount: number;
+  /** PageUp/PageDown 每次翻动的行数（>=1） */
+  pageRows: number;
+}
+
+/**
+ * 据键盘事件 key + 修饰键算出下一焦点坐标（纯函数，不改入参）。
+ * 返回 null 表示该键不是漫游键（不处理）。
+ *
+ * 行向：ArrowUp/Down 逐行（表头 row=-1 为上界，最后数据行为下界，不环绕）。
+ * 列向：ArrowLeft/Right 逐列（复用 core nextRovingIndex，clamp 不环绕）。
+ * Home/End：行内首/末列；Ctrl/Cmd+Home/End：跳表头首格 / 末数据行末格。
+ * PageUp/PageDown：上/下翻 pageRows 行（clamp 到 [-1, lastRow]）。
+ */
+export function nextGridCoord(
+  key: string,
+  modifiers: { ctrl?: boolean; meta?: boolean },
+  params: GridNavParams,
+): GridCoord | null {
+  const { current, rowCount, colCount, pageRows } = params;
+  const lastRow = rowCount - 1;
+  const lastCol = colCount - 1;
+  const ctrlOrMeta = !!modifiers.ctrl || !!modifiers.meta;
+  let { row, col } = current;
+
+  switch (key) {
+    case 'ArrowUp':
+      row = row <= -1 ? -1 : row - 1;
+      break;
+    case 'ArrowDown':
+      row = row >= lastRow ? lastRow : row + 1;
+      break;
+    case 'ArrowLeft':
+      col = nextRovingIndex(col, colCount, 'prev');
+      break;
+    case 'ArrowRight':
+      col = nextRovingIndex(col, colCount, 'next');
+      break;
+    case 'Home':
+      if (ctrlOrMeta) {
+        row = -1;
+        col = 0;
+      } else {
+        col = 0;
+      }
+      break;
+    case 'End':
+      if (ctrlOrMeta) {
+        row = lastRow;
+        col = lastCol;
+      } else {
+        col = lastCol;
+      }
+      break;
+    case 'PageDown':
+      row = row < 0 ? Math.min(lastRow, pageRows - 1) : Math.min(lastRow, row + pageRows);
+      break;
+    case 'PageUp':
+      row = row < 0 ? -1 : Math.max(-1, row - pageRows);
+      break;
+    default:
+      return null;
+  }
+
+  // colCount 为 0 时 col clamp 到 0；lastRow < -1（无数据行）时 row 不超过 -1。
+  if (lastRow < -1) row = -1;
+  if (row > lastRow && lastRow >= -1) row = Math.max(-1, lastRow);
+  return { row, col };
+}

package/src/table/index.ts

@@ -0,0 +1,13 @@
+export { default as Table } from './Table.svelte';
+export { meta as tableMeta } from './meta.js';
+export type {
+  ColumnDef,
+  RowSelection,
+  Expandable,
+  TreeTable,
+  TableChangeInfo,
+  TableChangeAction,
+  TableScrollInfo,
+  ScrollConfig,
+} from './types.js';
+export type { RowKey, SortState, SortOrder } from '@chenzy-design/core';

package/src/table/meta.ts

@@ -0,0 +1,121 @@
+/**
+ * Machine-readable component metadata for AI/docs consumption.
+ * Table — see specs/components/show/Table.spec.md
+ */
+export const meta = {
+  name: 'Table',
+  category: 'show',
+  description:
+    '表格：列定义驱动渲染，三态排序(升/降/无)、客户端分页、行选择(含半选 indeterminate)；sortState / rowSelection.selectedRowKeys / pagination.current 受控不回写，仅经 onSortChange / onChange 通知。复用 @chenzy-design/core 纯函数算法与 Pagination 组件。支持行展开 expandable（受控/非受控）。固定列 fixed、列筛选 filters/onFilter、列宽拖拽 resizable（本地覆盖宽度不写回 columns）。树形数据 tree（行含 children 自动嵌套，第一列展开三角+缩进，排序/分页作用于顶层行，扁平化用 core flattenTreeRows 纯函数，受控展开 keys 不回写）。树形行选择父子联动 rowSelection.checkStrictly（默认 false 勾父连带后代+半选，true 父子独立；联动用 core conductRows/toggleRowCheck 纯函数）。行虚拟滚动 virtualized：仅渲染视口内行切片（复用 core fixedRange），首尾 padding spacer tr 撑总高，保持原生 table 语义；thead sticky 固定顶部；与 pagination 互斥（虚拟时忽略分页）。',
+  exports: ['Table'],
+  props: [
+    { name: 'columns', type: 'ColumnDef<T>[]', default: '[]', desc: '列定义：key/dataIndex/title/width/fixed/resizable/align/ellipsis/sorter/filters/onFilter/render' },
+    { name: 'dataSource', type: 'T[]', default: '[]', desc: '数据行' },
+    { name: 'rowKey', type: "string | ((record: T) => RowKey)", default: "'key'", desc: '行唯一键解析' },
+    { name: 'size', type: "'small'|'default'|'large'", default: "'default'" },
+    { name: 'bordered', type: 'boolean', default: 'false', desc: '单元格边框' },
+    { name: 'stripe', type: 'boolean', default: 'false', desc: '斑马纹' },
+    { name: 'loading', type: 'boolean', default: 'false', desc: '半透明遮罩 + spinner' },
+    { name: 'sortState', type: 'SortState', default: 'undefined', desc: '受控排序态；受控时不回写，仅 onSortChange' },
+    { name: 'defaultSortState', type: 'SortState', default: '{ key: null, order: null }', desc: '非受控初始排序' },
+    { name: 'onSortChange', type: '(state: SortState) => void', default: 'undefined' },
+    {
+      name: 'pagination',
+      type: "false | { pageSize?: number; current?: number; defaultCurrent?: number; onChange?: (page: number) => void }",
+      default: 'undefined',
+      desc: 'false 关闭；对象/缺省启用内置分页(pageSize 默认 10)。current 受控不回写',
+    },
+    {
+      name: 'rowSelection',
+      type: 'RowSelection<T>',
+      default: 'undefined',
+      desc: 'selectedRowKeys 受控不回写；defaultSelectedRowKeys / onChange / getCheckboxProps；checkStrictly(默认 false) 树形父子联动开关：false 勾父连带勾后代+后代部分选中父行半选，true 父子独立',
+    },
+    {
+      name: 'expandable',
+      type: 'Expandable<T>',
+      default: 'undefined',
+      desc: 'expandedRowRender / rowExpandable / expandedRowKeys 受控不回写 / defaultExpandedRowKeys / onExpand',
+    },
+    {
+      name: 'tree',
+      type: 'boolean | TreeTable',
+      default: 'undefined',
+      desc: '树形数据：true 或 { childrenColumnName(默认 children) / indentSize(默认 16) / expandedRowKeys 受控不回写 / defaultExpandedRowKeys / onExpand }。第一列内展开三角+逐级缩进；排序/分页/筛选作用于顶层行',
+    },
+    { name: 'rowClassName', type: '(record: T, index: number) => string', default: 'undefined' },
+    { name: 'empty', type: 'string', default: "'暂无数据'", desc: '空数据占位文案' },
+    { name: 'ariaLabel', type: 'string', default: 'undefined', desc: 'table aria-label' },
+    { name: 'onRowClick', type: '(info: { record: T; index: number }) => void', default: 'undefined' },
+    { name: 'virtualized', type: 'boolean', default: 'false', desc: '行虚拟滚动：仅渲染视口内行，适合大数据(1000+)。启用时忽略 pagination(全量滚动)、表头 sticky 固定顶部；假定行等高，不建议与 expandable 混用' },
+    { name: 'height', type: 'number', default: '400', desc: '虚拟滚动视口高度(px)，virtualized 时生效' },
+    { name: 'rowHeight', type: 'number', default: '48', desc: '虚拟滚动行高(px)，virtualized 时生效' },
+  ],
+  events: [
+    { name: 'onSortChange', desc: '表头排序切换(三态循环)' },
+    { name: 'rowSelection.onChange', desc: '行选择变更，回传 keys 与对应 rows' },
+    { name: 'pagination.onChange', desc: '页码变更' },
+    { name: 'onRowClick', desc: '行点击(复选框/排序按钮已阻止冒泡)' },
+  ],
+  slots: [
+    { name: 'column.render', desc: '单元格自定义渲染 Snippet<[{ value, record, index }]>' },
+    { name: 'empty', desc: '空态文案经 empty prop 配置(字符串)' },
+  ],
+  a11y: {
+    hasRole: true,
+    focusable: true,
+    pattern: 'grid|table',
+    keyboard: '↑↓ 行 / ←→ 列 / Home·End 行内首末 / Ctrl·Cmd+Home·End 表首末 / PageUp·PageDown 翻屏 / Enter·F2 进入单元格交互、Esc 退出',
+    note: '交互态(排序/筛选/行选择/展开/树形/行点击任一)遵循 WAI-ARIA APG Grid Pattern：role=grid + aria-rowcount/colcount(虚拟化为逻辑总数) + role=row(aria-rowindex 真实序) + role=columnheader/rowheader/gridcell + aria-colindex；单元格 roving tabindex(整 grid 单一 Tab 停靠点，纯派生)，二维方向键漫游(纯函数 nextGridCoord)，命令式 focusCell 聚焦；虚拟化下方向键移到未渲染行先滚动进视口再 tick 后聚焦，焦点行被回收时回退到 grid 容器并 announce(不掉 body)；Enter/F2 进入单元格内控件交互模式、Esc 退出回导航(导航模式下单元格内控件 tabindex=-1 不破坏 roving)。纯展示表(无交互)降级为 role=table 省漫游。可排序列 aria-sort(ascending/descending/none)；行选择原生 checkbox，全选 aria-label「全选」、行选「选择此行」，半选经 attachment 命令式设 input.indeterminate(只写属性、不读几何、无响应式循环)；焦点环 --cd-focus-ring；reduced-motion 关闭 spinner 与图标过渡。',
+  },
+  tokens: [
+    '--cd-table-bg',
+    '--cd-table-header-bg',
+    '--cd-table-header-text',
+    '--cd-table-cell-text',
+    '--cd-table-border-color',
+    '--cd-table-row-hover-bg',
+    '--cd-table-row-selected-bg',
+    '--cd-table-row-stripe-bg',
+    '--cd-table-cell-padding-y',
+    '--cd-table-cell-padding-x',
+    '--cd-table-cell-padding-y-small',
+    '--cd-table-cell-padding-y-large',
+    '--cd-table-sort-active-color',
+    '--cd-table-sort-icon-color',
+    '--cd-table-loading-mask',
+    '--cd-table-empty-color',
+    '--cd-table-radius',
+  ],
+  responsive: false,
+  examples: [
+    {
+      title: '基础',
+      code: '<Table {columns} dataSource={data} rowKey="id" />',
+    },
+    {
+      title: '可排序',
+      code: '<Table columns={[{ dataIndex: "age", title: "年龄", sorter: true }]} dataSource={data} />',
+    },
+    {
+      title: '行选择 + 分页',
+      code: '<Table {columns} dataSource={data} rowSelection={{ onChange: (keys) => (selected = keys) }} pagination={{ pageSize: 10 }} />',
+    },
+    {
+      title: '列宽拖拽',
+      code: '<Table columns={[{ dataIndex: "name", title: "姓名", width: 160, resizable: true }]} dataSource={data} />',
+    },
+    {
+      title: '树形数据',
+      code: '<Table {columns} dataSource={treeRows} rowKey="key" tree={{ defaultExpandedRowKeys: [1] }} />',
+    },
+    {
+      title: '树形行选择父子联动',
+      code: '<Table {columns} dataSource={treeRows} rowKey="key" tree rowSelection={{ onChange: (keys) => (selected = keys) }} />',
+    },
+    {
+      title: '行虚拟滚动（大数据）',
+      code: '<Table {columns} dataSource={bigData} rowKey="id" virtualized height={400} rowHeight={48} />',
+    },
+  ],
+} as const;

package/src/table/types.ts

@@ -0,0 +1,133 @@
+/**
+ * Table 公共类型 — 由 Table.svelte 消费、index.ts 对外 re-export。
+ * 拆成独立模块以避免 .svelte 组件无法导出类型声明的限制。
+ * See specs/components/show/Table.spec.md
+ */
+import type { Snippet } from 'svelte';
+import type { RowKey } from '@chenzy-design/core';
+
+export type Align = 'left' | 'center' | 'right';
+export type TableSize = 'small' | 'default' | 'large';
+
+export interface ColumnDef<T> {
+  /** 列唯一键，缺省回退 dataIndex / 列索引 */
+  key?: string;
+  /** 取值字段 */
+  dataIndex?: keyof T & string;
+  /** 表头文案 */
+  title: string;
+  /** 列宽 */
+  width?: number | string;
+  /** 固定列：横向滚动时左/右侧 sticky 锁定（需配合 width 数值） */
+  fixed?: 'left' | 'right';
+  /** 列宽可拖拽调整：列头右侧出现拖拽手柄，指针拖拽实时改列宽 */
+  resizable?: boolean;
+  /** 对齐方式，默认 left */
+  align?: Align;
+  /** 单元格溢出省略 */
+  ellipsis?: boolean;
+  /** true 按 dataIndex 默认比较；或自定义比较器 */
+  sorter?: boolean | ((a: T, b: T) => number);
+  /** 受控排序状态（当前列）*/
+  sortOrder?: 'ascend' | 'descend' | null;
+  /** 默认排序状态 */
+  defaultSortOrder?: 'ascend' | 'descend' | null;
+  /** 列头筛选项（下拉多选）；配合 onFilter 过滤数据 */
+  filters?: { text: string; value: string | number }[];
+  /** 受控列筛选值 */
+  filteredValue?: (string | number)[] | null;
+  /** 是否多选筛选，默认 true */
+  filterMultiple?: boolean;
+  /** 行是否匹配某筛选值；缺省时按 dataIndex 全等比较 */
+  onFilter?: (value: string | number, record: T) => boolean;
+  /** 单元格自定义渲染 */
+  render?: Snippet<[{ value: unknown; record: T; index: number }]>;
+}
+
+export interface Expandable<T> {
+  /** 展开行内容渲染 */
+  expandedRowRender: Snippet<[{ record: T; index: number }]>;
+  /** 该行是否可展开，默认全部可展开 */
+  rowExpandable?: (record: T) => boolean;
+  /** 受控展开行 key 列表 */
+  expandedRowKeys?: RowKey[];
+  /** 非受控初始展开 */
+  defaultExpandedRowKeys?: RowKey[];
+  /** 展开/收起回调 */
+  onExpand?: (expanded: boolean, record: T) => void;
+}
+
+export interface TreeTable {
+  /** 子行字段名，默认 'children' */
+  childrenColumnName?: string;
+  /** 每层缩进像素，默认 16 */
+  indentSize?: number;
+  /** 非受控初始展开行 key 列表 */
+  defaultExpandedRowKeys?: RowKey[];
+  /** 受控展开行 key 列表；受控时不回写，仅 onExpand 通知 */
+  expandedRowKeys?: RowKey[];
+  /** 展开/收起回调 */
+  onExpand?: (expanded: boolean, key: RowKey) => void;
+}
+
+export interface RowSelection<T> {
+  /** 受控选中行 key 列表 */
+  selectedRowKeys?: RowKey[];
+  /** 非受控初始选中 */
+  defaultSelectedRowKeys?: RowKey[];
+  /** 选择变更回调 */
+  onChange?: (keys: RowKey[], rows: T[]) => void;
+  /** 逐行定制复选框属性（如 disabled） */
+  getCheckboxProps?: (record: T) => { disabled?: boolean };
+  /**
+   * 树形表父子选择是否独立。默认 false：勾选父行连带勾选所有后代，
+   * 后代部分选中时父行显示半选(indeterminate)。true 时父子互不联动
+   * （等同非树形表逐行选择，向后兼容）。仅在 tree 启用时生效。
+   */
+  checkStrictly?: boolean;
+  /** 选择方式: checkbox（多选）或 radio（单选），默认 checkbox */
+  type?: 'checkbox' | 'radio';
+  /** 单行选择回调 */
+  onSelect?: (record: T, selected: boolean, selectedRows: T[]) => void;
+  /** 全选回调 */
+  onSelectAll?: (selected: boolean, selectedRows: T[], changedRows: T[]) => void;
+  /** 选择列固定 */
+  fixed?: boolean | 'left';
+  /** 选择列宽度 */
+  columnWidth?: number | string;
+  /** 隐藏全选框 */
+  hideSelectAll?: boolean;
+}
+
+export interface ScrollConfig {
+  x?: number | string;
+  y?: number | string;
+  scrollToFirstRowOnChange?: boolean;
+}
+
+/** 聚合 onChange 的 extra.action 取值 */
+export type TableChangeAction = 'paginate' | 'sort' | 'filter';
+
+/** 聚合 onChange 载荷（排序/筛选/分页任一变化的主入口，spec §4） */
+export interface TableChangeInfo {
+  pagination: { current: number; pageSize: number };
+  filters: Record<string, (string | number)[]>;
+  sorter: SortStateLike;
+  extra: { action: TableChangeAction };
+}
+
+/** onScroll 载荷（spec §4，含触底用于无限加载） */
+export interface TableScrollInfo {
+  scrollLeft: number;
+  scrollTop: number;
+  atLeft: boolean;
+  atRight: boolean;
+  atTop: boolean;
+  atBottom: boolean;
+}
+
+// 局部别名，避免在本文件引入对 SortState 的运行期依赖说明
+type SortStateLike = import('@chenzy-design/core').SortState;
+
+export type { RowKey } from '@chenzy-design/core';
+export type { SortState, SortOrder } from '@chenzy-design/core';