@teamix-evo/ui 0.7.1 → 0.7.2

package/src/components/data-table/meta.md

@@ -69,6 +69,176 @@ Table primitives + Pagination 实现 排序 / 过滤 / 分页 / 行选择 / 行
 
 ## 示例
 
+### Full
+
+完整页面组合：展示 DataTable 在真实业务页面中的使用方式。 体现 shadcn 组合式理念：页面级布局由多个独立组件自由组合，DataTable 只负责表格渲染， Toolbar / FilterBar / Typography 等是兄弟组件，通过外部 state 与 DataTable 通信。
+
+```tsx
+<label
+  key={id}
+  className="flex cursor-pointer items-center gap-2 text-xs"
+>
+  <Checkbox
+    checked={checked}
+    onCheckedChange={(c) =>
+      setVisibility((prev) => ({
+        ...prev,
+        [id]: c === true,
+      }))
+    }
+  />
+  <span>
+    {typeof col.title === 'string' ? col.title : id}
+  </span>
+</label>
+```
+
+### ColumnVisibility
+
+列显隐：外部 Toolbar 通过 `columnVisibility` + `onColumnVisibilityChange` 控制列显示/隐藏。
+
+```tsx
+<label
+  key={id}
+  className="flex cursor-pointer items-center gap-2 text-xs"
+>
+  <Checkbox
+    checked={checked}
+    onCheckedChange={(c) =>
+      setVisibility((prev) => ({
+        ...prev,
+        [id]: c === true,
+      }))
+    }
+  />
+  <span>
+    {typeof col.title === 'string' ? col.title : id}
+  </span>
+</label>
+```
+
+### WithSorting
+
+列排序：通过 `sortable: true` 启用，单击表头切换 asc / desc / 无。
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  { key: 'name', dataIndex: 'name', title: '姓名', width: 100 },
+  {
+    key: 'age',
+    dataIndex: 'age',
+    title: '年龄',
+    width: 100,
+    align: 'right',
+    sortable: true,
+  },
+  { key: 'role', dataIndex: 'role', title: '角色', width: 120 },
+  { key: 'city', dataIndex: 'city', title: '城市' },
+];
+return <DataTable columns={columns} data={users} />;
+```
+
+### WithFiltering
+
+列过滤：`filters` 提供候选项，单击表头过滤图标弹出 Popover 选择。
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  { key: 'name', dataIndex: 'name', title: '姓名', width: 100 },
+  {
+    key: 'age',
+    dataIndex: 'age',
+    title: '年龄',
+    width: 80,
+    align: 'right',
+  },
+  {
+    key: 'role',
+    dataIndex: 'role',
+    title: '角色',
+    width: 120,
+    filters: [
+      { label: '管理员', value: '管理员' },
+      { label: '开发', value: '开发' },
+      { label: '运维', value: '运维' },
+      { label: '产品', value: '产品' },
+    ],
+  },
+  {
+    key: 'status',
+    dataIndex: 'status',
+    title: '状态',
+    width: 100,
+    filterMode: 'single',
+    filters: [
+      { label: '活跃', value: 'active' },
+      { label: '暂停', value: 'paused' },
+      { label: '已封', value: 'banned' },
+    ],
+  },
+  { key: 'city', dataIndex: 'city', title: '城市' },
+];
+return <DataTable columns={columns} data={users} />;
+```
+
+### WithPagination
+
+分页：默认开启分页，可通过 `pagination` 配置 pageSize / showSizeChanger / showTotal。
+
+```tsx
+<DataTable
+  columns={baseColumns}
+  data={data}
+  pagination={{
+    defaultPageSize: 10,
+    pageSizeOptions: [5, 10, 20],
+    showSizeChanger: true,
+    showTotal: true,
+  }}
+/>
+```
+
+### RowSelectionMultiple
+
+多选行：`rowSelection` 多选模式（默认），表头全选 / 半选。
+
+```tsx
+<div className="flex flex-col gap-2">
+  <p className="text-xs text-muted-foreground">
+    已选：{keys.length} 项 — {keys.join(', ') || '无'}
+  </p>
+  <DataTable
+    columns={baseColumns}
+    data={users}
+    rowSelection={{
+      selectedRowKeys: keys,
+      onChange: (k) => setKeys(k),
+    }}
+  />
+</div>
+```
+
+### RowSelectionSingle
+
+单选行：`rowSelection.mode = 'single'`。
+
+```tsx
+<div className="flex flex-col gap-2">
+  <p className="text-xs text-muted-foreground">
+    当前选中：{keys[0] ?? '无'}
+  </p>
+  <DataTable
+    columns={baseColumns}
+    data={users}
+    rowSelection={{
+      mode: 'single',
+      selectedRowKeys: keys,
+      onChange: (k) => setKeys(k),
+    }}
+  />
+</div>
+```
+
 ### ExpandedRow
 
 行展开：`expandable.expandedRowRender` 渲染额外区域。
@@ -105,3 +275,252 @@ Loading 与 Empty 状态。
   </div>
 </div>
 ```
+
+### CustomCell
+
+自定义单元格渲染 + 操作列。
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  { key: 'name', dataIndex: 'name', title: '姓名', width: 100 },
+  {
+    key: 'age',
+    dataIndex: 'age',
+    title: '年龄',
+    width: 80,
+    align: 'right',
+  },
+  {
+    key: 'status',
+    dataIndex: 'status',
+    title: '状态',
+    width: 100,
+    render: (val) => {
+      const v = val as User['status'];
+      const map = {
+        active: { label: '活跃', status: 'success' as const },
+        paused: { label: '暂停', status: 'warning' as const },
+        banned: { label: '已封', status: 'error' as const },
+      };
+      return (
+        <Tag variant="status" status={map[v].status} showIcon>
+          {map[v].label}
+        </Tag>
+      );
+    },
+  },
+  { key: 'city', dataIndex: 'city', title: '城市' },
+  {
+    key: 'actions',
+    title: '操作',
+    width: 120,
+    align: 'right',
+    cell: () => (
+      <ButtonGroup className="h-4 gap-3">
+        <Button variant="link">编辑</Button>
+        <ButtonGroupSeparator />
+        <Button
+          variant="link"
+          className="text-destructive hover:text-destructive"
+        >
+          删除
+        </Button>
+      </ButtonGroup>
+    ),
+  },
+];
+return <DataTable columns={columns} data={users.slice(0, 5)} />;
+```
+
+### LockColumns
+
+锁列：通过 `fixed: 'left' | 'right'` 让列在水平滚动时保持位置。
+
+```tsx
+<div style={{ width: 720 }}>
+  <DataTable columns={columns} data={wideUsers} />
+</div>
+```
+
+### ResizableColumns
+
+列宽拖拽：`enableColumnResizing` 全局开启，列上 `resizable: true` 启用，鼠标拖拽列右侧分隔线。
+
+```tsx
+<div className="flex flex-col gap-2">
+  <p className="text-xs text-muted-foreground">
+    当前列宽：{JSON.stringify(sizing)}
+  </p>
+  <DataTable
+    columns={columns}
+    data={users}
+    enableColumnResizing
+    columnSizing={sizing}
+    onColumnSizingChange={setSizing}
+  />
+</div>
+```
+
+### TreeData
+
+树形数据：`isTree` + `children` 字段递归渲染，子行通过缩进 + 展开按钮表达层级。
+
+```tsx
+<DataTable
+  columns={columns}
+  data={treeUsers}
+  isTree
+  indentSize={20}
+  pagination={false}
+/>
+```
+
+### FixedHeader
+
+固定表头：`stickyHeader` + `maxBodyHeight` 让表头滚动吸顶。
+
+```tsx
+<DataTable
+  columns={baseColumns}
+  data={data}
+  stickyHeader
+  maxBodyHeight={320}
+  pagination={false}
+/>
+```
+
+### Crossline
+
+十字辅助轴：`crossline` 同时高亮 hover 行与列，便于宽表格定位。
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  { key: 'name', dataIndex: 'name', title: '姓名', width: 120 },
+  {
+    key: 'age',
+    dataIndex: 'age',
+    title: '年龄',
+    width: 80,
+    align: 'right',
+  },
+  { key: 'role', dataIndex: 'role', title: '角色', width: 120 },
+  { key: 'status', dataIndex: 'status', title: '状态', width: 120 },
+  { key: 'city', dataIndex: 'city', title: '城市', width: 120 },
+];
+return <DataTable columns={columns} data={users} crossline />;
+```
+
+### Virtual
+
+虚拟滚动：`virtual` 开启后只渲染可视区域的行，适合千条以上数据。需同时设置 `maxBodyHeight`。
+
+```tsx
+<div className="flex flex-col gap-2">
+  <p className="text-xs text-muted-foreground">
+    总计 {data.length} 条，开启虚拟滚动后仅渲染可见区域。
+  </p>
+  <DataTable
+    columns={baseColumns}
+    data={data}
+    virtual
+    stickyHeader
+    maxBodyHeight={400}
+    estimateRowHeight={40}
+    pagination={false}
+  />
+</div>
+```
+
+### MultiHeader
+
+多级表头：列定义中传入 `children` 数组即可表示分组，头部渲染为两层 `<thead><tr>`。
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  { key: 'name', dataIndex: 'name', title: '姓名', width: 120 },
+  {
+    key: 'profile',
+    title: '个人信息',
+    children: [
+      {
+        key: 'age',
+        dataIndex: 'age',
+        title: '年龄',
+        width: 80,
+        align: 'right',
+      },
+      { key: 'city', dataIndex: 'city', title: '城市', width: 120 },
+    ],
+  },
+  {
+    key: 'work',
+    title: '工作信息',
+    children: [
+      { key: 'role', dataIndex: 'role', title: '角色', width: 120 },
+      { key: 'status', dataIndex: 'status', title: '状态', width: 120 },
+    ],
+  },
+];
+return <DataTable columns={columns} data={users} />;
+```
+
+### MergedCells
+
+合并单元格：`cellProps` 返回 `{ rowSpan, colSpan }`，返回 0 则跳过该 td（与 TanStack 原生渲染拼接）。
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  { key: 'name', dataIndex: 'name', title: '姓名', width: 100 },
+  { key: 'role', dataIndex: 'role', title: '角色', width: 120 },
+  { key: 'city', dataIndex: 'city', title: '城市', width: 120 },
+  { key: 'status', dataIndex: 'status', title: '状态', width: 120 },
+];
+// 示例：头三行 “角色” 同为 “管理员” 时合并 rowSpan=3；后面两行返回 rowSpan=0 跳过。
+const cellProps = (rowIndex: number, colIndex: number) => {
+  // colIndex 1 对应 role 列
+  if (colIndex !== 1) return undefined;
+  if (rowIndex === 0) return { rowSpan: 3 };
+  if (rowIndex === 1 || rowIndex === 2) return { rowSpan: 0 };
+  return undefined;
+};
+const data = [
+  { ...users[0]!, role: '管理员' as const },
+  { ...users[1]!, role: '管理员' as const },
+  { ...users[2]!, role: '管理员' as const },
+  ...users.slice(3),
+];
+return <DataTable columns={columns} data={data} cellProps={cellProps} />;
+```
+
+### EditableCellStory
+
+可编辑单元格：`EditableCell` helper 双击切入输入框，Enter / blur 提交，Esc 取消。
+
+```tsx
+<div className="flex flex-col gap-2">
+  <p className="text-xs text-muted-foreground">
+    双击 “姓名” 或 “年龄” 单元格可进入编辑态。
+  </p>
+  <DataTable columns={columns} data={data} pagination={false} />
+</div>
+```
+
+### DraggableRow
+
+行拖拽排序：`draggable` 开启后，首列出现拖拽手柄，拖拽排序后触发 `onDragEnd`。
+
+```tsx
+<div className="flex flex-col gap-2">
+  <p className="text-xs text-muted-foreground">
+    拖拽首列手柄调整行顺序。
+  </p>
+  <DataTable
+    columns={baseColumns}
+    data={data}
+    rowKey="id"
+    draggable
+    onDragEnd={({ data: next }) => setData(next)}
+    pagination={false}
+  />
+</div>
+```

package/src/components/date-picker/meta.md

@@ -80,6 +80,51 @@
 </div>
 ```
 
+### Controlled
+
+受控
+
+```tsx
+<div className="flex flex-col gap-2">
+  <DatePicker value={value} onChange={setValue} />
+  <p className="text-xs text-muted-foreground">
+    {value?.toLocaleDateString() ?? '(空)'}
+  </p>
+</div>
+```
+
+### WithShowTime
+
+带时间选择
+
+```tsx
+<DatePicker showTime placeholder="选择日期时间" />
+```
+
+### MonthPicker
+
+月份选择
+
+```tsx
+<DatePicker picker="month" />
+```
+
+### YearPicker
+
+年份选择
+
+```tsx
+<DatePicker picker="year" />
+```
+
+### WithPresets
+
+快捷选项
+
+```tsx
+<DatePicker presets />
+```
+
 ### DisabledDates
 
 禁用部分日期
@@ -91,6 +136,14 @@
 />
 ```
 
+### ErrorStatus
+
+错误状态
+
+```tsx
+<DatePicker status="error" placeholder="请选择日期" />
+```
+
 ### Loading
 
 加载态：右侧图标替换为 spinner，loading > clear > CalendarIcon 互斥。
@@ -101,3 +154,41 @@
   <DateRangePicker loading />
 </div>
 ```
+
+### Range
+
+日期范围选择器
+
+```tsx
+<DateRangePicker />
+```
+
+### RangeControlled
+
+日期范围 - 受控
+
+```tsx
+<div className="flex flex-col gap-2">
+  <DateRangePicker value={value} onChange={setValue} />
+  <p className="text-xs text-muted-foreground">
+    {value?.from?.toLocaleDateString()} ~{' '}
+    {value?.to?.toLocaleDateString()}
+  </p>
+</div>
+```
+
+### RangeWithTime
+
+日期范围 + 时间
+
+```tsx
+<DateRangePicker showTime />
+```
+
+### RangeWithPresets
+
+日期范围 + 快捷选项
+
+```tsx
+<DateRangePicker presets />
+```

package/src/components/descriptions/index.tsx

@@ -474,7 +474,7 @@ function DescriptionsLabel({
         // —— label 本身取文本行高（约 12px font × 1.5 ≈ 18px），与 content 中 24px 的 sm Button / Tag 顶对齐会产生
         // 基线偏误；强制 min-h-6 + inline-flex items-center 后，label 框同样 24px，文字垂直居中，与
         // 控件内文字基线自然对齐。如 content 是 h-8 / h-10 等更高控件，在 <DescriptionsItem align="center"> 带动。
-        !ctx.bordered && horizontal && 'min-w-24 min-h-6',
+        !ctx.bordered && horizontal && 'min-h-6 min-w-24',
         className,
       )}
       {...props}