@teamix-evo/ui 0.4.0 → 0.5.2

package/src/components/table/meta.md

@@ -0,0 +1,148 @@
+# Table
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+表格 Table
+展示结构化数据的基础表格组件，shadcn 极薄 composable 范式。提供 size / bordered / striped /
+stickyHeader / hoverable / crossline / loading / empty / maxBodyHeight 等视觉与状态能力。
+交互逻辑（排序 / 过滤 / 分页 / 选择 / 展开 / 锁列 / 虚拟滚动等）由 DataTable 高阶组件承载。
+
+## 使用场景
+
+- 需要表格化展示结构化数据
+- 作为 DataTable 的底层渲染基础
+- 简单数据列表展示，无需交互逻辑时直接使用
+- 组合结构：Table > TableHeader / TableBody / TableFooter > TableRow > TableHead / TableCell ; TableCaption 可选
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `layout` | `"auto" \| "fixed"` | `"auto"` | – | – |
+| `size` | `TableSize` | – | – | 尺寸，sm = 紧凑（py-2 px-2，白底表头），md = 默认（thead py-3 px-4 + 浅灰底，tbody py-3 px-4） |
+| `bordered` | `boolean` | – | – | 是否显示外边框与单元格分隔线（默认 false：仅保留行底边线 + 表头浅底） |
+| `striped` | `boolean` | – | – | 是否启用斑马纹（偶数行底色） |
+| `hoverable` | `boolean` | – | – | 是否启用行 hover 高亮（默认开启） |
+| `crossline` | `boolean` | – | – | 是否启用十字辅助轴（hover 行 + 列高亮） |
+| `stickyHeader` | `boolean` | – | – | 是否吸顶表头（配合 maxBodyHeight 使用） |
+| `maxBodyHeight` | `number \| string` | – | – | 表格容器最大高度，超出滚动；可传字符串如 '400px' 或数字（视为 px） |
+| `loading` | `boolean` | – | – | 是否显示加载态蒙层 |
+| `loadingNode` | `React.ReactNode` | – | – | 自定义加载态节点；默认居中 spinner |
+| `empty` | `React.ReactNode` | – | – | 空数据节点；当传入时覆盖 tbody 默认渲染（一般由 DataTable 控制） |
+| `containerClassName` | `string` | – | – | 容器层 className |
+
+## 示例
+
+### Sizes
+
+通过 `size` 切换紧凑（sm）与默认（md）密度。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <div>
+    <p className="mb-2 text-xs text-muted-foreground">size = "sm"</p>
+    <Table size="sm">
+      {renderHeader()}
+      <TableBody>{renderRows(invoices)}</TableBody>
+    </Table>
+  </div>
+  <div>
+    <p className="mb-2 text-xs text-muted-foreground">
+      size = "md"（默认）
+    </p>
+    <Table size="md">
+      {renderHeader()}
+      <TableBody>{renderRows(invoices)}</TableBody>
+    </Table>
+  </div>
+</div>
+```
+
+### Bordered
+
+`bordered` 默认关闭（仅表头浅底 + 行底边线）；开启后补齐外框 + 单元格分隔线。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <div>
+    <p className="mb-2 text-xs text-muted-foreground">
+      bordered=false（默认）
+    </p>
+    <Table>
+      {renderHeader()}
+      <TableBody>{renderRows(invoices)}</TableBody>
+    </Table>
+  </div>
+  <div>
+    <p className="mb-2 text-xs text-muted-foreground">bordered=true</p>
+    <Table bordered>
+      {renderHeader()}
+      <TableBody>{renderRows(invoices)}</TableBody>
+    </Table>
+  </div>
+</div>
+```
+
+### Striped
+
+启用 `striped` 斑马纹（偶数行底色）。
+
+```tsx
+<Table striped>
+  {renderHeader()}
+  <TableBody>{renderRows([...invoices, ...invoices])}</TableBody>
+</Table>
+```
+
+### Loading
+
+`loading` 显示居中蒙层；可通过 `loadingNode` 自定义。
+
+```tsx
+<Table loading>
+  {renderHeader()}
+  <TableBody>{renderRows(invoices)}</TableBody>
+</Table>
+```
+
+### Empty
+
+通过 `empty` slot 渲染空状态（一般由 DataTable 控制；此处演示直接传入）。
+
+```tsx
+<Table empty>
+  {renderHeader()}
+  <TableBody />
+</Table>
+```
+
+### Crossline
+
+`crossline` 启用十字辅助轴：行 hover 高亮（列高亮由 DataTable 配合 data-col-hover 实现）。
+
+```tsx
+<Table crossline>
+  {renderHeader()}
+  <TableBody>{renderRows(invoices)}</TableBody>
+</Table>
+```
+
+### Composition
+
+完整组合：caption + header + body + footer。
+
+```tsx
+<Table>
+  <TableCaption>本月发票汇总。</TableCaption>
+  {renderHeader()}
+  <TableBody>{renderRows(invoices)}</TableBody>
+  <TableFooter>
+    <TableRow>
+      <TableCell colSpan={3}>合计</TableCell>
+      <TableCell className="text-right">¥1,200.00</TableCell>
+    </TableRow>
+  </TableFooter>
+</Table>
+```

package/src/components/table/stories.tsx

@@ -0,0 +1,189 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Table,
+  TableHeader,
+  TableBody,
+  TableFooter,
+  TableHead,
+  TableRow,
+  TableCell,
+  TableCaption,
+} from './index';
+
+const meta: Meta<typeof Table> = {
+  title: '数据展示 · Data Display/Table 表格',
+  component: Table,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+interface Invoice {
+  id: string;
+  status: string;
+  method: string;
+  amount: string;
+}
+
+const invoices: Invoice[] = [
+  { id: 'INV001', status: '已支付', method: '信用卡', amount: '¥250.00' },
+  { id: 'INV002', status: '待付款', method: '支付宝', amount: '¥150.00' },
+  { id: 'INV003', status: '已支付', method: '微信支付', amount: '¥350.00' },
+  { id: 'INV004', status: '已取消', method: '银行转账', amount: '¥450.00' },
+];
+
+const renderRows = (data: Invoice[]) =>
+  data.map((inv) => (
+    <TableRow key={inv.id}>
+      <TableCell className="font-medium">{inv.id}</TableCell>
+      <TableCell>{inv.status}</TableCell>
+      <TableCell>{inv.method}</TableCell>
+      <TableCell className="text-right">{inv.amount}</TableCell>
+    </TableRow>
+  ));
+
+const renderHeader = () => (
+  <TableHeader>
+    <TableRow>
+      <TableHead className="w-24">发票号</TableHead>
+      <TableHead>状态</TableHead>
+      <TableHead>支付方式</TableHead>
+      <TableHead className="text-right">金额</TableHead>
+    </TableRow>
+  </TableHeader>
+);
+
+/** 基础表格展示。 */
+export const Default: Story = {
+  render: () => (
+    <Table>
+      <TableCaption>最近的发票列表。</TableCaption>
+      {renderHeader()}
+      <TableBody>{renderRows(invoices)}</TableBody>
+    </Table>
+  ),
+};
+
+/** 通过 `size` 切换紧凑（sm）与默认（md）密度。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div>
+        <p className="mb-2 text-xs text-muted-foreground">size = "sm"</p>
+        <Table size="sm">
+          {renderHeader()}
+          <TableBody>{renderRows(invoices)}</TableBody>
+        </Table>
+      </div>
+      <div>
+        <p className="mb-2 text-xs text-muted-foreground">
+          size = "md"（默认）
+        </p>
+        <Table size="md">
+          {renderHeader()}
+          <TableBody>{renderRows(invoices)}</TableBody>
+        </Table>
+      </div>
+    </div>
+  ),
+};
+
+/** `bordered` 默认关闭（仅表头浅底 + 行底边线）；开启后补齐外框 + 单元格分隔线。 */
+export const Bordered: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div>
+        <p className="mb-2 text-xs text-muted-foreground">
+          bordered=false（默认）
+        </p>
+        <Table>
+          {renderHeader()}
+          <TableBody>{renderRows(invoices)}</TableBody>
+        </Table>
+      </div>
+      <div>
+        <p className="mb-2 text-xs text-muted-foreground">bordered=true</p>
+        <Table bordered>
+          {renderHeader()}
+          <TableBody>{renderRows(invoices)}</TableBody>
+        </Table>
+      </div>
+    </div>
+  ),
+};
+
+/** 启用 `striped` 斑马纹（偶数行底色）。 */
+export const Striped: Story = {
+  render: () => (
+    <Table striped>
+      {renderHeader()}
+      <TableBody>{renderRows([...invoices, ...invoices])}</TableBody>
+    </Table>
+  ),
+};
+
+/** 配合 `maxBodyHeight` 使用 `stickyHeader` 实现表头吸顶。 */
+export const StickyHeader: Story = {
+  render: () => {
+    const longList: Invoice[] = Array.from({ length: 30 }, (_, i) => ({
+      id: `INV${String(i + 1).padStart(3, '0')}`,
+      status: i % 3 === 0 ? '已支付' : i % 3 === 1 ? '待付款' : '已取消',
+      method: ['信用卡', '支付宝', '微信支付', '银行转账'][i % 4]!,
+      amount: `¥${(100 + i * 25).toFixed(2)}`,
+    }));
+    return (
+      <Table stickyHeader maxBodyHeight={300}>
+        {renderHeader()}
+        <TableBody>{renderRows(longList)}</TableBody>
+      </Table>
+    );
+  },
+};
+
+/** `loading` 显示居中蒙层；可通过 `loadingNode` 自定义。 */
+export const Loading: Story = {
+  render: () => (
+    <Table loading>
+      {renderHeader()}
+      <TableBody>{renderRows(invoices)}</TableBody>
+    </Table>
+  ),
+};
+
+/** 通过 `empty` slot 渲染空状态（一般由 DataTable 控制；此处演示直接传入）。 */
+export const Empty: Story = {
+  render: () => (
+    <Table empty>
+      {renderHeader()}
+      <TableBody />
+    </Table>
+  ),
+};
+
+/** `crossline` 启用十字辅助轴：行 hover 高亮（列高亮由 DataTable 配合 data-col-hover 实现）。 */
+export const Crossline: Story = {
+  render: () => (
+    <Table crossline>
+      {renderHeader()}
+      <TableBody>{renderRows(invoices)}</TableBody>
+    </Table>
+  ),
+};
+
+/** 完整组合：caption + header + body + footer。 */
+export const Composition: Story = {
+  render: () => (
+    <Table>
+      <TableCaption>本月发票汇总。</TableCaption>
+      {renderHeader()}
+      <TableBody>{renderRows(invoices)}</TableBody>
+      <TableFooter>
+        <TableRow>
+          <TableCell colSpan={3}>合计</TableCell>
+          <TableCell className="text-right">¥1,200.00</TableCell>
+        </TableRow>
+      </TableFooter>
+    </Table>
+  ),
+};