@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/data-table/stories.tsx

@@ -0,0 +1,1234 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { RefreshCw, Rows3, Settings2 } from 'lucide-react';
+import { useForm } from 'react-hook-form';
+
+import { Avatar, AvatarFallback, AvatarImage } from '@/components/avatar';
+import { Button } from '@/components/button';
+import {
+  ButtonGroup,
+  ButtonGroupOverflow,
+  ButtonGroupSeparator,
+} from '@/components/button-group';
+import { Checkbox } from '@/components/checkbox';
+import { DropdownMenuItem } from '@/components/dropdown-menu';
+import {
+  FilterBar,
+  FilterBarHeader,
+  FilterBarSearch,
+  FilterBarSearchKey,
+  FilterBarSearchValue,
+  FilterBarSearchAction,
+  FilterBarTrigger,
+  FilterBarContent,
+  FilterBarActions,
+  FilterBarField,
+} from '@/components/filter-bar';
+import { Input } from '@/components/input';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/popover';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/select';
+import { Tag } from '@/components/tag';
+import { Title, Paragraph } from '@/components/typography';
+import { DataTable, EditableCell, type DataTableColumn } from './index';
+
+const meta: Meta<typeof DataTable> = {
+  title: '数据展示 · Data Display/DataTable 数据表格',
+  component: DataTable,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+interface User {
+  id: string;
+  name: string;
+  age: number;
+  role: '管理员' | '开发' | '运维' | '产品';
+  status: 'active' | 'paused' | 'banned';
+  city: string;
+  [key: string]: unknown;
+}
+
+const users: User[] = [
+  {
+    id: '1',
+    name: '张三',
+    age: 28,
+    role: '管理员',
+    status: 'active',
+    city: '北京',
+  },
+  {
+    id: '2',
+    name: '李四',
+    age: 35,
+    role: '开发',
+    status: 'active',
+    city: '上海',
+  },
+  {
+    id: '3',
+    name: '王五',
+    age: 24,
+    role: '运维',
+    status: 'paused',
+    city: '杭州',
+  },
+  {
+    id: '4',
+    name: '赵六',
+    age: 41,
+    role: '产品',
+    status: 'active',
+    city: '深圳',
+  },
+  {
+    id: '5',
+    name: '钱七',
+    age: 30,
+    role: '开发',
+    status: 'banned',
+    city: '北京',
+  },
+  {
+    id: '6',
+    name: '孙八',
+    age: 27,
+    role: '开发',
+    status: 'active',
+    city: '成都',
+  },
+  {
+    id: '7',
+    name: '周九',
+    age: 33,
+    role: '运维',
+    status: 'active',
+    city: '上海',
+  },
+  {
+    id: '8',
+    name: '吴十',
+    age: 22,
+    role: '产品',
+    status: 'paused',
+    city: '广州',
+  },
+];
+
+const baseColumns: DataTableColumn<User>[] = [
+  { key: 'name', dataIndex: 'name', title: '姓名', width: 100 },
+  { key: 'age', dataIndex: 'age', title: '年龄', width: 80, align: 'right' },
+  { key: 'role', dataIndex: 'role', title: '角色', width: 100 },
+  { key: 'status', dataIndex: 'status', title: '状态', width: 100 },
+  { key: 'city', dataIndex: 'city', title: '城市' },
+];
+
+// ─── Default story 真实业务数据 (实例列表) ───────────────────────────────
+
+interface Instance {
+  id: string;
+  name: string;
+  instanceId: string;
+  tags: string[];
+  creator: string;
+  avatar?: string;
+  org: string;
+  ip: string;
+  spec: string;
+  status: string;
+  [key: string]: unknown;
+}
+
+const instances: Instance[] = [
+  {
+    id: '1',
+    name: 'Kvbkqv(置花计红子从省)',
+    instanceId: 'c4b7BFeC-e57f-80CC-d65B-E4A...',
+    tags: ['开发', '测试'],
+    creator: '必此机利',
+    org: '组织名称 连毛须系林利军',
+    ip: '私 237.11.254.139',
+    spec: '4核16G',
+    status: 'processing',
+  },
+  {
+    id: '2',
+    name: 'Siqqqoeh(她组术意办了住八众)',
+    instanceId: 'e1DDfb4a-b592-47db-309F-Ba9...',
+    tags: ['生产'],
+    creator: '百江四角',
+    org: '组织名称 金照二把切根',
+    ip: '私 170.113.46.126',
+    spec: '2核8G',
+    status: 'processing',
+  },
+  {
+    id: '3',
+    name: 'Kmdnqzlxi(强周压见之听调存)',
+    instanceId: '31845E5A-9c7B-Ca0F-73bd-fBCa...',
+    tags: ['开发', '线上'],
+    creator: '向八志省理',
+    org: '组织名称 见任地速了上快商',
+    ip: '私 14.218.57.70',
+    spec: '8核32G',
+    status: 'pause',
+  },
+  {
+    id: '4',
+    name: 'Ekkwbbiux(地由约求马性安)',
+    instanceId: 'd1bDe3ed-531A-c4Cb-5f95-5cF3...',
+    tags: ['测试', '预发'],
+    creator: '张它将高学什',
+    org: '组织名称 位住照志党元',
+    ip: '私 138.82.89.83',
+    spec: '4核16G',
+    status: 'processing',
+  },
+  {
+    id: '5',
+    name: 'Jbweksdc(点常头离加素)',
+    instanceId: 'd810277F-EB8A-A31E-f9Bf-e9A9...',
+    tags: ['生产', '核心'],
+    creator: '这次打眼又',
+    org: '组织名称 时石内响儿克术会',
+    ip: '私 131.167.88.128',
+    spec: '2核4G',
+    status: 'success',
+  },
+];
+
+const instanceColumns: DataTableColumn<Instance>[] = [
+  {
+    key: 'name',
+    dataIndex: 'name',
+    title: '实例ID/实例名称',
+    width: 280,
+    render: (_val, record) => (
+      <div className="flex flex-col gap-0.5">
+        <a
+          href="#"
+          className="font-medium text-primary"
+          onClick={(e) => e.preventDefault()}
+        >
+          {record.name}
+        </a>
+        <span className="text-muted-foreground">{record.instanceId}</span>
+      </div>
+    ),
+  },
+  {
+    key: 'tags',
+    dataIndex: 'tags',
+    title: '标签',
+    width: 140,
+    render: (val) => {
+      const tags = val as string[];
+      return (
+        <span className="inline-flex flex-wrap items-center gap-1">
+          {tags.map((t) => (
+            <Tag key={t} size="sm">
+              {t}
+            </Tag>
+          ))}
+        </span>
+      );
+    },
+  },
+  {
+    key: 'status',
+    dataIndex: 'status',
+    title: '状态',
+    width: 140,
+    render: (val) => (
+      <Tag
+        variant="status"
+        status={val as 'processing' | 'success' | 'pause'}
+        showIcon
+      >
+        {val === 'processing'
+          ? '运行中'
+          : val === 'success'
+          ? '已完成'
+          : '已停止'}
+      </Tag>
+    ),
+  },
+  {
+    key: 'ip',
+    dataIndex: 'ip',
+    title: 'IP 地址',
+    width: 180,
+  },
+  {
+    key: 'spec',
+    dataIndex: 'spec',
+    title: '规格',
+    width: 120,
+  },
+  {
+    key: 'creator',
+    dataIndex: 'creator',
+    title: '创建者',
+    width: 160,
+    render: (val) => (
+      <span className="inline-flex items-center gap-2">
+        <Avatar className="size-6">
+          <AvatarImage alt="@shadcn" src="https://github.com/shadcn.png" />
+          <AvatarFallback>{(val as string).slice(0, 1)}</AvatarFallback>
+        </Avatar>
+        <span>{val as string}</span>
+      </span>
+    ),
+  },
+  {
+    key: 'org',
+    dataIndex: 'org',
+    title: '组织',
+    width: 240,
+  },
+  {
+    key: 'actions',
+    title: '操作',
+    width: 220,
+    fixed: 'right',
+    render: () => (
+      <ButtonGroup className="h-4 gap-3">
+        <Button variant="link">管理</Button>
+        <ButtonGroupSeparator />
+        <Button variant="link">编辑</Button>
+        <ButtonGroupSeparator />
+        <Button variant="link">远程连接</Button>
+        <ButtonGroupSeparator />
+        <ButtonGroupOverflow variant="link">
+          <DropdownMenuItem>释放</DropdownMenuItem>
+          <DropdownMenuItem>暂停</DropdownMenuItem>
+          <DropdownMenuItem variant="destructive">删除</DropdownMenuItem>
+        </ButtonGroupOverflow>
+      </ButtonGroup>
+    ),
+  },
+];
+
+/**
+ * 默认用法：实例列表场景 — 小尺寸 + 锁列 + 富单元格渲染 + 分页。
+ *
+ * 外层工具栏（按钮、搜索、高级筛选）和筛选面板不属于 DataTable，由页面级组合实现。
+ * 右侧操作列 `fixed: 'right'` 产生的左侧边框是锁列指示器，横向滚动时可见。
+ */
+export const Default: Story = {
+  render: () => (
+    <DataTable<Instance>
+      columns={instanceColumns}
+      data={instances}
+      pagination={{
+        total: 100,
+        defaultPageSize: 5,
+        pageSizeOptions: [5, 10, 20],
+        showSizeChanger: true,
+        showTotal: true,
+      }}
+    />
+  ),
+};
+
+// ─── 完整页面组合示例 ─────────────────────────────────────────
+
+/**
+ * 完整页面组合：展示 DataTable 在真实业务页面中的使用方式。
+ *
+ * 体现 shadcn 组合式理念：页面级布局由多个独立组件自由组合，DataTable 只负责表格渲染，
+ * Toolbar / FilterBar / Typography 等是兄弟组件，通过外部 state 与 DataTable 通信。
+ */
+export const Full: Story = {
+  render: () => {
+    const form = useForm({
+      defaultValues: { instanceId: '', resourceGroup: '', region: '' },
+    });
+    const [size, setSize] = React.useState<'sm' | 'md'>('sm');
+    const [visibility, setVisibility] = React.useState<Record<string, boolean>>(
+      {},
+    );
+
+    return (
+      <div className="flex flex-col gap-4">
+        {/* 页头：标题 + 描述 */}
+        <div className="flex items-center gap-2">
+          <Title level={4}>实例列表</Title>
+          <Paragraph color="muted">
+            展示 DataTable 在完整页面中的组合使用方式
+          </Paragraph>
+        </div>
+
+        {/* FilterBar：搜索 + 高级筛选 + Toolbar */}
+        <FilterBar
+          form={form}
+          onFilter={(values) => console.log('filter:', values)}
+          addonBefore={
+            <div className="flex items-center gap-2">
+              <Button>数据请求</Button>
+              <Button variant="outline">二次确认</Button>
+            </div>
+          }
+          addonAfter={
+            <div className="flex items-center gap-1">
+              <Button variant="outline" size="icon">
+                <RefreshCw />
+              </Button>
+              <Button
+                variant="outline"
+                size="icon"
+                onClick={() => setSize(size === 'sm' ? 'md' : 'sm')}
+              >
+                <Rows3 />
+              </Button>
+              <Popover>
+                <PopoverTrigger asChild>
+                  <Button variant="outline" size="icon">
+                    <Settings2 />
+                  </Button>
+                </PopoverTrigger>
+                <PopoverContent align="end" className="w-40 p-2">
+                  <div className="flex flex-col gap-1.5">
+                    {instanceColumns.map((col) => {
+                      const id = col.key!;
+                      const checked = visibility[id] !== false;
+                      return (
+                        <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>
+                      );
+                    })}
+                  </div>
+                </PopoverContent>
+              </Popover>
+            </div>
+          }
+        >
+          <FilterBarHeader>
+            <FilterBarSearch>
+              <FilterBarSearchKey
+                options={[{ name: 'instanceId', label: '实例ID' }]}
+              />
+              <FilterBarSearchValue placeholder="请输入实例ID" />
+              <FilterBarSearchAction />
+            </FilterBarSearch>
+            <FilterBarTrigger />
+          </FilterBarHeader>
+          <FilterBarContent>
+            <FilterBarField name="instanceId" label="实例ID">
+              <Input placeholder="请输入" />
+            </FilterBarField>
+            <FilterBarField name="resourceGroup" label="资源集">
+              <Select>
+                <SelectTrigger>
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="teamix">Teamix</SelectItem>
+                  <SelectItem value="default">默认</SelectItem>
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="region" label="区域">
+              <Select>
+                <SelectTrigger>
+                  <SelectValue placeholder="全部区域" />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="cn-hangzhou">华东1</SelectItem>
+                  <SelectItem value="cn-beijing">华北1</SelectItem>
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarActions />
+          </FilterBarContent>
+        </FilterBar>
+
+        {/* DataTable：接收外部 state 控制 */}
+        <DataTable<Instance>
+          columns={instanceColumns}
+          data={instances}
+          size={size}
+          columnVisibility={visibility}
+          onColumnVisibilityChange={setVisibility}
+          pagination={{
+            total: 100,
+            defaultPageSize: 5,
+            pageSizeOptions: [5, 10, 20],
+            showSizeChanger: true,
+            showTotal: true,
+          }}
+        />
+      </div>
+    );
+  },
+};
+
+/** 列显隐：外部 Toolbar 通过 `columnVisibility` + `onColumnVisibilityChange` 控制列显示/隐藏。 */
+export const ColumnVisibility: Story = {
+  render: () => {
+    const [visibility, setVisibility] = React.useState<Record<string, boolean>>(
+      {},
+    );
+    const [size, setSize] = React.useState<'sm' | 'md'>('sm');
+    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 },
+      { key: 'status', dataIndex: 'status', title: '状态', width: 100 },
+      { key: 'city', dataIndex: 'city', title: '城市' },
+    ];
+    return (
+      <div className="flex flex-col gap-3">
+        {/* 外部 Toolbar — 密度切换 + 列配置 */}
+        <div className="flex items-center justify-end gap-2">
+          <Button
+            size="sm"
+            variant={size === 'sm' ? 'default' : 'outline'}
+            onClick={() => setSize('sm')}
+          >
+            紧凑
+          </Button>
+          <Button
+            size="sm"
+            variant={size === 'md' ? 'default' : 'outline'}
+            onClick={() => setSize('md')}
+          >
+            宽松
+          </Button>
+          <Popover>
+            <PopoverTrigger asChild>
+              <Button size="sm" variant="outline">
+                列配置
+              </Button>
+            </PopoverTrigger>
+            <PopoverContent align="end" className="w-40 p-2">
+              <div className="flex flex-col gap-1.5">
+                {columns.map((col) => {
+                  const id = col.key!;
+                  const checked = visibility[id] !== false;
+                  return (
+                    <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>
+                  );
+                })}
+              </div>
+            </PopoverContent>
+          </Popover>
+        </div>
+        {/* DataTable 接收受控 props */}
+        <DataTable
+          columns={columns}
+          data={users}
+          size={size}
+          columnVisibility={visibility}
+          onColumnVisibilityChange={setVisibility}
+        />
+      </div>
+    );
+  },
+};
+
+/** 列排序：通过 `sortable: true` 启用，单击表头切换 asc / desc / 无。 */
+export const WithSorting: Story = {
+  render: () => {
+    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} />;
+  },
+};
+
+/** 列过滤：`filters` 提供候选项，单击表头过滤图标弹出 Popover 选择。 */
+export const WithFiltering: Story = {
+  render: () => {
+    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} />;
+  },
+};
+
+/** 分页：默认开启分页，可通过 `pagination` 配置 pageSize / showSizeChanger / showTotal。 */
+export const WithPagination: Story = {
+  render: () => {
+    const data: User[] = Array.from({ length: 36 }, (_, i) => ({
+      id: String(i + 1),
+      name: `用户 ${i + 1}`,
+      age: 20 + (i % 30),
+      role: (['管理员', '开发', '运维', '产品'] as const)[i % 4]!,
+      status: (['active', 'paused', 'banned'] as const)[i % 3]!,
+      city: (['北京', '上海', '杭州', '深圳', '成都', '广州'] as const)[i % 6]!,
+    }));
+    return (
+      <DataTable
+        columns={baseColumns}
+        data={data}
+        pagination={{
+          defaultPageSize: 10,
+          pageSizeOptions: [5, 10, 20],
+          showSizeChanger: true,
+          showTotal: true,
+        }}
+      />
+    );
+  },
+};
+
+/** 多选行：`rowSelection` 多选模式（默认），表头全选 / 半选。 */
+export const RowSelectionMultiple: Story = {
+  render: () => {
+    const [keys, setKeys] = React.useState<string[]>([]);
+    return (
+      <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>
+    );
+  },
+};
+
+/** 单选行：`rowSelection.mode = 'single'`。 */
+export const RowSelectionSingle: Story = {
+  render: () => {
+    const [keys, setKeys] = React.useState<string[]>([]);
+    return (
+      <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>
+    );
+  },
+};
+
+/** 行展开：`expandable.expandedRowRender` 渲染额外区域。 */
+export const ExpandedRow: Story = {
+  render: () => (
+    <DataTable
+      columns={baseColumns}
+      data={users.slice(0, 4)}
+      expandable={{
+        expandedRowRender: (record) => (
+          <div className="flex flex-col gap-1 text-xs">
+            <p>姓名：{record.name}</p>
+            <p>城市：{record.city}</p>
+            <p>状态：{record.status}</p>
+          </div>
+        ),
+      }}
+    />
+  ),
+};
+
+/** Loading 与 Empty 状态。 */
+export const LoadingAndEmpty: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div>
+        <p className="mb-2 text-xs text-muted-foreground">loading</p>
+        <DataTable columns={baseColumns} data={users.slice(0, 3)} loading />
+      </div>
+      <div>
+        <p className="mb-2 text-xs text-muted-foreground">empty</p>
+        <DataTable columns={baseColumns} data={[]} />
+      </div>
+    </div>
+  ),
+};
+
+/** 自定义单元格渲染 + 操作列。 */
+export const CustomCell: Story = {
+  render: () => {
+    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" color="destructive">
+              删除
+            </Button>
+          </ButtonGroup>
+        ),
+      },
+    ];
+    return <DataTable columns={columns} data={users.slice(0, 5)} />;
+  },
+};
+
+// ─── P1 进阶能力 ───────────────────────────────────────────────────────────
+
+interface TreeUser extends User {
+  children?: TreeUser[];
+}
+
+const treeUsers: TreeUser[] = [
+  {
+    id: '1',
+    name: '产品中心',
+    age: 0,
+    role: '产品',
+    status: 'active',
+    city: '北京',
+    children: [
+      {
+        id: '1-1',
+        name: '前端组',
+        age: 0,
+        role: '开发',
+        status: 'active',
+        city: '北京',
+        children: [
+          {
+            id: '1-1-1',
+            name: '张三',
+            age: 28,
+            role: '开发',
+            status: 'active',
+            city: '北京',
+          },
+          {
+            id: '1-1-2',
+            name: '李四',
+            age: 35,
+            role: '开发',
+            status: 'active',
+            city: '上海',
+          },
+        ],
+      },
+      {
+        id: '1-2',
+        name: '后端组',
+        age: 0,
+        role: '开发',
+        status: 'active',
+        city: '杭州',
+        children: [
+          {
+            id: '1-2-1',
+            name: '王五',
+            age: 24,
+            role: '运维',
+            status: 'paused',
+            city: '杭州',
+          },
+        ],
+      },
+    ],
+  },
+  {
+    id: '2',
+    name: '运维中心',
+    age: 0,
+    role: '运维',
+    status: 'active',
+    city: '上海',
+    children: [
+      {
+        id: '2-1',
+        name: '钱七',
+        age: 30,
+        role: '运维',
+        status: 'active',
+        city: '上海',
+      },
+    ],
+  },
+];
+
+const wideUsers: User[] = Array.from({ length: 8 }, (_, i) => ({
+  id: String(i + 1),
+  name: `用户 ${i + 1}`,
+  age: 20 + (i % 30),
+  role: (['管理员', '开发', '运维', '产品'] as const)[i % 4]!,
+  status: (['active', 'paused', 'banned'] as const)[i % 3]!,
+  city: (['北京', '上海', '杭州', '深圳', '成都', '广州'] as const)[i % 6]!,
+  email: `user${i + 1}@example.com`,
+  phone: `1380000${String(i + 1).padStart(4, '0')}`,
+  department: (['研发', '测试', '运维', '产品', '设计'] as const)[i % 5]!,
+  level: `P${5 + (i % 4)}`,
+}));
+
+/** 锁列：通过 `fixed: 'left' | 'right'` 让列在水平滚动时保持位置。 */
+export const LockColumns: Story = {
+  render: () => {
+    const columns: DataTableColumn<User>[] = [
+      {
+        key: 'name',
+        dataIndex: 'name',
+        title: '姓名',
+        width: 120,
+        fixed: 'left',
+      },
+      {
+        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: 160 },
+      {
+        key: 'department',
+        dataIndex: 'department' as keyof User & string,
+        title: '部门',
+        width: 160,
+      },
+      {
+        key: 'level',
+        dataIndex: 'level' as keyof User & string,
+        title: '职级',
+        width: 100,
+      },
+      {
+        key: 'email',
+        dataIndex: 'email' as keyof User & string,
+        title: '邮箱',
+        width: 220,
+      },
+      {
+        key: 'phone',
+        dataIndex: 'phone' as keyof User & string,
+        title: '电话',
+        width: 160,
+      },
+      {
+        key: 'actions',
+        title: '操作',
+        width: 120,
+        align: 'right',
+        fixed: 'right',
+        cell: () => <Button variant="link">编辑</Button>,
+      },
+    ];
+    return (
+      <div style={{ width: 720 }}>
+        <DataTable columns={columns} data={wideUsers} />
+      </div>
+    );
+  },
+};
+
+/** 列宽拖拽：`enableColumnResizing` 全局开启，列上 `resizable: true` 启用，鼠标拖拽列右侧分隔线。 */
+export const ResizableColumns: Story = {
+  render: () => {
+    const [sizing, setSizing] = React.useState<Record<string, number>>({});
+    const columns: DataTableColumn<User>[] = [
+      {
+        key: 'name',
+        dataIndex: 'name',
+        title: '姓名',
+        width: 120,
+        resizable: true,
+      },
+      {
+        key: 'age',
+        dataIndex: 'age',
+        title: '年龄',
+        width: 80,
+        align: 'right',
+        resizable: true,
+      },
+      {
+        key: 'role',
+        dataIndex: 'role',
+        title: '角色',
+        width: 160,
+        resizable: true,
+      },
+      {
+        key: 'status',
+        dataIndex: 'status',
+        title: '状态',
+        width: 120,
+        resizable: true,
+      },
+      { key: 'city', dataIndex: 'city', title: '城市', width: 200 },
+    ];
+    return (
+      <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>
+    );
+  },
+};
+
+/** 树形数据：`isTree` + `children` 字段递归渲染，子行通过缩进 + 展开按钮表达层级。 */
+export const TreeData: Story = {
+  render: () => {
+    const columns: DataTableColumn<TreeUser>[] = [
+      { key: 'name', dataIndex: 'name', title: '姓名', width: 220 },
+      { key: 'role', dataIndex: 'role', title: '角色', width: 120 },
+      { key: 'status', dataIndex: 'status', title: '状态', width: 120 },
+      { key: 'city', dataIndex: 'city', title: '城市' },
+    ];
+    return (
+      <DataTable
+        columns={columns}
+        data={treeUsers}
+        isTree
+        indentSize={20}
+        pagination={false}
+      />
+    );
+  },
+};
+
+/** 固定表头：`stickyHeader` + `maxBodyHeight` 让表头滚动吸顶。 */
+export const FixedHeader: Story = {
+  render: () => {
+    const data: User[] = Array.from({ length: 50 }, (_, i) => ({
+      id: String(i + 1),
+      name: `用户 ${i + 1}`,
+      age: 20 + (i % 30),
+      role: (['管理员', '开发', '运维', '产品'] as const)[i % 4]!,
+      status: (['active', 'paused', 'banned'] as const)[i % 3]!,
+      city: (['北京', '上海', '杭州', '深圳', '成都', '广州'] as const)[i % 6]!,
+    }));
+    return (
+      <DataTable
+        columns={baseColumns}
+        data={data}
+        stickyHeader
+        maxBodyHeight={320}
+        pagination={false}
+      />
+    );
+  },
+};
+
+/** 十字辅助轴：`crossline` 同时高亮 hover 行与列，便于宽表格定位。 */
+export const Crossline: Story = {
+  render: () => {
+    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 />;
+  },
+};
+
+// ─── P2 高阶能力 ──────────────────────────────────────────────────────────
+
+/** 虚拟滚动：`virtual` 开启后只渲染可视区域的行，适合千条以上数据。需同时设置 `maxBodyHeight`。 */
+export const Virtual: Story = {
+  render: () => {
+    const data: User[] = Array.from({ length: 2000 }, (_, i) => ({
+      id: String(i + 1),
+      name: `用户 ${i + 1}`,
+      age: 20 + (i % 40),
+      role: (['管理员', '开发', '运维', '产品'] as const)[i % 4]!,
+      status: (['active', 'paused', 'banned'] as const)[i % 3]!,
+      city: (['北京', '上海', '杭州', '深圳', '成都', '广州'] as const)[i % 6]!,
+    }));
+    return (
+      <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>
+    );
+  },
+};
+
+/** 多级表头：列定义中传入 `children` 数组即可表示分组，头部渲染为两层 `<thead><tr>`。 */
+export const MultiHeader: Story = {
+  render: () => {
+    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} />;
+  },
+};
+
+/** 合并单元格：`cellProps` 返回 `{ rowSpan, colSpan }`，返回 0 则跳过该 td（与 TanStack 原生渲染拼接）。 */
+export const MergedCells: Story = {
+  render: () => {
+    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} />;
+  },
+};
+
+/** 可编辑单元格：`EditableCell` helper 双击切入输入框，Enter / blur 提交，Esc 取消。 */
+export const EditableCellStory: Story = {
+  name: 'EditableCell',
+  render: () => {
+    const [data, setData] = React.useState<User[]>(users.slice(0, 4));
+    const updateField = (
+      id: string,
+      field: keyof User,
+      value: string | number,
+    ) => {
+      setData((prev) =>
+        prev.map((u) => (u.id === id ? { ...u, [field]: value } : u)),
+      );
+    };
+    const columns: DataTableColumn<User>[] = [
+      {
+        key: 'name',
+        dataIndex: 'name',
+        title: '姓名 (可编辑)',
+        width: 160,
+        cell: ({ row }) => (
+          <EditableCell
+            value={row.original.name}
+            onCommit={(v) => updateField(row.original.id, 'name', v)}
+          />
+        ),
+      },
+      {
+        key: 'age',
+        dataIndex: 'age',
+        title: '年龄 (可编辑)',
+        width: 120,
+        align: 'right',
+        cell: ({ row }) => (
+          <EditableCell
+            type="number"
+            value={row.original.age}
+            onCommit={(v) => updateField(row.original.id, 'age', v)}
+          />
+        ),
+      },
+      { key: 'role', dataIndex: 'role', title: '角色', width: 120 },
+      { key: 'city', dataIndex: 'city', title: '城市' },
+    ];
+    return (
+      <div className="flex flex-col gap-2">
+        <p className="text-xs text-muted-foreground">
+          双击 “姓名” 或 “年龄” 单元格可进入编辑态。
+        </p>
+        <DataTable columns={columns} data={data} pagination={false} />
+      </div>
+    );
+  },
+};
+
+/** 行拖拽排序：`draggable` 开启后，首列出现拖拽手柄，拖拽排序后触发 `onDragEnd`。 */
+export const DraggableRow: Story = {
+  render: () => {
+    const [data, setData] = React.useState<User[]>(users.slice(0, 6));
+    return (
+      <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>
+    );
+  },
+};