@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/pagination/pagination.meta.md

@@ -1,230 +0,0 @@
----
-id: pagination
-name: Pagination
-displayName: 分页
-type: component
-category: navigation
-since: 0.1.0
-package: '@teamix-evo/ui'
----
-
-# Pagination 分页
-
-**分页 — 在大量内容中按页切换浏览,带受控/非受控 + 页码窗口折叠 + 三档密度 + 三种形态**。两套 API:
-
-1. **shadcn primitives**(`Pagination / Content / Item / Link / Previous / Next / Ellipsis`)— 完全可组合,适合自定义复杂分页布局
-2. **`SimplePagination`**(antd 风格 props 化高阶包装)— `total / pageSize / current / onChange` 即用,**自动计算页码窗口 + 折叠 ellipsis + 显示总数**;支持 `size` (`sm`/`md`/`lg`)、`type` (`normal`/`simple`/`mini`)、`pageSizeSelector` + `pageSizeList`、`showJump`、`showFirstLast`
-
-## When to use
-
-- 列表 / 表格分页(配 Data Table)
-- 长内容多页阅读
-- 搜索结果分页
-- **空间紧凑场景** → `type="mini"`(仅前后箭头 + 页号/总页)
-- **移动端 / 卡片右下角** → `type="simple"`(prev + 当前/总 + next)
-
-## When NOT to use
-
-- 无限滚动 → IntersectionObserver + `hasMore` flag
-- 总数小(< 1 页)→ 不显示
-
-## Props
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `current` | `number` | – | – | 当前页(1-based,受控)。与 `defaultCurrent` 互斥。 |
-| `defaultCurrent` | `number` | `1` | – | 默认当前页(非受控)。 |
-| `onChange` | `(page: number, pageSize: number) => void` | – | – | 页码 / pageSize 变化回调。第二参为变化后的 pageSize。 |
-| `total` | `number` | – | ✓ | 总条数。 |
-| `pageSize` | `number` | – | – | 每页大小(受控)。与 `defaultPageSize` 互斥。 |
-| `defaultPageSize` | `number` | `10` | – | 默认每页大小(非受控)。 |
-| `pageSizeList` | `number[]` | `[10, 20, 50, 100]` | – | 每页大小可选项(用于 `pageSizeSelector`)。 |
-| `pageSizeSelector` | `boolean` | `false` | – | 显示每页大小选择器(对齐 antd `showSizeChanger` / cloud-design `pageSizeSelector`)。 |
-| `onPageSizeChange` | `(pageSize: number) => void` | – | – | pageSize 变化回调。 |
-| `size` | `PaginationSize` | `"md"` | – | 组件大小,对齐 Button / Input 的 sm(h-7) / md(h-8) / lg(h-9) 三档。 |
-| `type` | `PaginationType` | `"normal"` | – | 组件类型 — `normal` 完整 / `simple` 简化(prev + 页码/总页 + next) / `mini` 极简(仅前后箭头)。 |
-| `showFirstLast` | `boolean` | `false` | – | `normal` 类型下,显示首末页快捷按钮。 |
-| `showTotal` | `boolean` | `true` | – | 显示总数文本(`mini` 类型默认不显示)。 |
-| `totalRender` | `(total: number, range: [number, number]) => React.ReactNode` | – | – | 自定义总数渲染。 |
-| `showJump` | `boolean` | `false` | – | `normal` 类型下,显示跳转输入框。 |
-| `siblingCount` | `number` | `5` | – | 中间显示几个页号。建议奇数。 |
-| `className` | `string` | – | – | 容器 className。 |
-<!-- auto:props:end -->
-
-## 依赖
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
-
-<!-- auto:deps:begin -->
-### 同库依赖
-
-> `teamix-evo ui add pagination` 时,以下 entry 会被自动连带安装(无需手动 add)。
-
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `button` | component | 通用按钮 — shadcn 实现 + cloud-design 能力并集(loading / icon / shape / block / dashed variant / color 语义双 prop / disabledTooltip)。同文件合一导出 ButtonGroup + ButtonGroupText(等价 antd Space.Compact + cd SplitButton)。 |
-
-### npm 依赖
-
-> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
-
-```bash
-pnpm add class-variance-authority@^0.7.0 lucide-react@^0.460.0
-```
-<!-- auto:deps:end -->
-
-## AI 生成纪律
-
-- **业务侧用 `SimplePagination`**:除非要完全自定义布局,默认走高阶 API
-- **`size` 三档对齐 Button/Input**:`sm`(h-7) / `md`(h-8,默认) / `lg`(h-9);**不要**自己加 `h-[28px]` 等 arbitrary value
-- **`type` 三态语义清晰**:
-  - `normal` = 完整(页码列表 + prev/next + 可选 pageSizeSelector / showJump / showFirstLast)
-  - `simple` = 简化(prev + 当前页/总页 + next),适合卡片角落
-  - `mini` = 极简(仅 prev/next 图标 + 页号/总页文本),适合表格行内 / 工具条
-- **`pageSizeSelector` 仅 normal 生效**:`simple` / `mini` 形态下传入会被忽略
-- **当前页 1-based**:antd 惯例,与 0-based 数组索引区分清楚
-- **`pageSize` 默认 10**:与 antd / Web 主流一致;`pageSizeList` 默认 `[10, 20, 50, 100]`
-- **`siblingCount` 控制中间窗口**:奇数(5/7)效果好,偶数会产生不对称
-- **`onChange` 第二参为 pageSize**:`(page, pageSize) => void` — 切换 pageSize 时会回到第 1 页并触发一次 `onChange(1, newSize)`
-- **不要嵌套 Pagination**:同一容器只一组分页
-- **不要传 antd 的 `defaultPageSize` 同时传 `pageSize`**:受控/非受控择一(运行时以受控值为准)
-- **跳转输入框**:`showJump` 默认 `false`,启用后回车提交;非数字静默忽略
-
-## Examples
-
-```tsx
-import { SimplePagination } from '@/components/ui/pagination';
-import * as React from 'react';
-
-// 受控 + 默认 normal × md
-const [page, setPage] = React.useState(1);
-<SimplePagination
-  total={245}
-  current={page}
-  pageSize={10}
-  onChange={(p) => setPage(p)}
-/>
-
-// 三档尺寸
-<SimplePagination total={245} size="sm" current={page} onChange={(p) => setPage(p)} />
-<SimplePagination total={245} size="md" current={page} onChange={(p) => setPage(p)} />
-<SimplePagination total={245} size="lg" current={page} onChange={(p) => setPage(p)} />
-
-// 简化形态(卡片右下角)
-<SimplePagination
-  type="simple"
-  total={245}
-  current={page}
-  onChange={(p) => setPage(p)}
-/>
-
-// 极简形态(表格行内 / 工具条)
-<SimplePagination
-  type="mini"
-  total={245}
-  current={page}
-  onChange={(p) => setPage(p)}
-/>
-
-// 完整能力 — pageSizeSelector + showJump + showFirstLast
-<SimplePagination
-  total={1234}
-  current={page}
-  pageSizeSelector
-  pageSizeList={[10, 20, 50, 100]}
-  showJump
-  showFirstLast
-  onChange={(p, s) => {
-    setPage(p);
-    /* s 是当前 pageSize */
-  }}
-  onPageSizeChange={(s) => console.log('pageSize →', s)}
-/>
-
-// 自定义总数文本
-<SimplePagination
-  total={245}
-  current={page}
-  onChange={(p) => setPage(p)}
-  totalRender={(t, [s, e]) => `${s}-${e} of ${t}`}
-/>
-
-// 非受控 — defaultCurrent + defaultPageSize
-<SimplePagination total={245} defaultCurrent={2} defaultPageSize={20} pageSizeSelector />
-```
-
-```tsx
-// 自由组合(primitives)— 自定义任意布局
-import {
-  Pagination,
-  PaginationContent,
-  PaginationItem,
-  PaginationLink,
-  PaginationPrevious,
-  PaginationNext,
-  PaginationEllipsis,
-} from '@/components/ui/pagination';
-
-<Pagination>
-  <PaginationContent>
-    <PaginationItem>
-      <PaginationPrevious size="md" onClick={...} />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink size="md" onClick={...}>1</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink size="md" isActive>2</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationLink size="md" onClick={...}>3</PaginationLink>
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationEllipsis size="md" />
-    </PaginationItem>
-    <PaginationItem>
-      <PaginationNext size="md" onClick={...} />
-    </PaginationItem>
-  </PaginationContent>
-</Pagination>;
-```
-
----
-
-## Pagination 形态 — 旧库 API → 新映射
-
-> 旧库 `Pagination`(hybridcloud) → 新库 `SimplePagination`(高阶 API) + Pagination Primitives(自由组合)。
-> 新库提供两层架构:SimplePagination 开箱即用;Primitives 用于自定义布局。
-
-### 命名 & 结构映射
-
-| 旧库                               | 新库                               | 说明                         |
-| ---------------------------------- | ---------------------------------- | ---------------------------- |
-| `Pagination`                       | `SimplePagination`                 | 高阶封装(开箱即用)           |
-| —                                  | `Pagination` + Primitives          | 新库新增自由组合层           |
-| `type: 'normal'\|'simple'\|'mini'` | `type: 'normal'\|'simple'\|'mini'` | 保持一致                     |
-| `size: small/medium/large`         | `size: 'sm' \| 'md' \| 'lg'`       | md = medium                  |
-| `onChange(current, e)`             | `onChange(page, pageSize)`         | 签名变更,第二参改为 pageSize |
-| `pageSizeSelector='dropdown'`      | `pageSizeSelector={true}`          | 简化为布尔                   |
-| `pageShowCount`                    | `siblingCount`                     | 当前页两侧显示页数           |
-| `showJump`                         | `showJump`                         | 跳转输入框                   |
-| `totalRender`                      | `totalRender`                      | 总条数自定义渲染             |
-| `hideOnlyOnePage`                  | 不复刻                             | 业务层条件渲染更灵活         |
-| `link` (链接模式)                  | 不复刻                             | Primitives 自行用 `<a>`      |
-| `shape`                            | 不复刻                             | 不再设计多种箭头变体         |
-| `pageSizePosition`                 | 不复刻                             | 固定右侧                     |
-| `useFloatLayout`                   | 不复刻                             | 用 flexbox 替代              |
-| `pageNumberRender`                 | 不复刻                             | 通过 Primitives 自行实现     |
-
-### 迁移 FAQ
-
-| 问题                         | 回答                                                                           |
-| ---------------------------- | ------------------------------------------------------------------------------ |
-| onChange 签名差异?           | 旧: `(current, event)` → 新: `(page, pageSize)` — 第二参从 event 改为 pageSize |
-| 怎么做自定义布局?            | 用 Primitives(Pagination + PaginationContent + PaginationLink + …)             |
-| showFirstLast?               | SimplePagination 已内置首/末页按钮(P0 新增能力)                                |
-| pageSizeSelector 选项怎么配? | `pageSizeList` prop 传入 `[10, 20, 50, 100]` 数组                              |

package/src/components/pagination/pagination.stories.tsx

@@ -1,284 +0,0 @@
-import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { SimplePagination } from './pagination';
-
-const meta: Meta<typeof SimplePagination> = {
-  title: '导航 · Navigation/Pagination',
-  component: SimplePagination,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '**分页 Pagination —— 在大量内容中按页切换浏览,带受控/非受控 + 页码窗口折叠**。shadcn primitives(`Pagination / Content / Item / Link / Previous / Next / Ellipsis`)+ 高阶 `SimplePagination`(antd 风格 props 化)。**对齐 antd `size` / `defaultPageSize` / `pageSizeOptions` / `showSizeChanger` 与 cloud-design `type` / `pageSizeSelector` / `pageSizeList` / `showJump` 的并集**:`size` (`sm`/`md`/`lg` 对齐 Button/Input)、`type` (`normal`/`simple`/`mini`)、`pageSizeSelector`、`pageSizeList`、`showJump`、`showFirstLast`、`showTotal`、`totalRender`、`siblingCount`。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。',
-      },
-    },
-  },
-  argTypes: {
-    total: { control: 'number' },
-    pageSize: { control: 'number' },
-    siblingCount: { control: 'number' },
-    showFirstLast: { control: 'boolean' },
-    showTotal: { control: 'boolean' },
-    showJump: { control: 'boolean' },
-    pageSizeSelector: { control: 'boolean' },
-    size: { control: 'inline-radio', options: ['sm', 'md', 'lg'] },
-    type: { control: 'inline-radio', options: ['normal', 'simple', 'mini'] },
-  },
-  args: {
-    total: 245,
-    pageSize: 10,
-    siblingCount: 5,
-    size: 'md',
-    type: 'normal',
-  },
-  decorators: [(Story) => <div className="w-[760px]">{Story()}</div>],
-};
-
-export default meta;
-type Story = StoryObj<typeof SimplePagination>;
-
-export const Playground: Story = {
-  render: (args) => {
-    const [page, setPage] = React.useState(args.current ?? 1);
-    return (
-      <SimplePagination
-        {...args}
-        current={page}
-        onChange={(p) => setPage(p)}
-      />
-    );
-  },
-};
-
-// ─── size 三档 ────────────────────────────────────────────────────────────────
-
-export const SizeSmall: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const [page, setPage] = React.useState(3);
-    return (
-      <SimplePagination
-        total={245}
-        size="sm"
-        current={page}
-        onChange={(p) => setPage(p)}
-      />
-    );
-  },
-};
-
-export const SizeMedium: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const [page, setPage] = React.useState(3);
-    return (
-      <SimplePagination
-        total={245}
-        size="md"
-        current={page}
-        onChange={(p) => setPage(p)}
-      />
-    );
-  },
-};
-
-export const SizeLarge: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const [page, setPage] = React.useState(3);
-    return (
-      <SimplePagination
-        total={245}
-        size="lg"
-        current={page}
-        onChange={(p) => setPage(p)}
-      />
-    );
-  },
-};
-
-// ─── type 三态 ────────────────────────────────────────────────────────────────
-
-export const TypeNormal: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const [page, setPage] = React.useState(3);
-    return (
-      <SimplePagination
-        total={245}
-        type="normal"
-        current={page}
-        onChange={(p) => setPage(p)}
-      />
-    );
-  },
-};
-
-export const TypeSimple: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const [page, setPage] = React.useState(3);
-    return (
-      <SimplePagination
-        total={245}
-        type="simple"
-        current={page}
-        onChange={(p) => setPage(p)}
-      />
-    );
-  },
-};
-
-export const TypeMini: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const [page, setPage] = React.useState(3);
-    return (
-      <SimplePagination
-        total={245}
-        type="mini"
-        current={page}
-        onChange={(p) => setPage(p)}
-      />
-    );
-  },
-};
-
-// ─── 矩阵:type × size(共 9 个组合)─────────────────────────────────────────
-
-export const Matrix: Story = {
-  parameters: {
-    controls: { disable: true },
-    docs: {
-      description: {
-        story:
-          '`type × size` 的完整矩阵 — 用于一眼比对所有形态的视觉密度与高度对齐(对应 Button/Input 的 h-7 / h-8 / h-9 三档)。',
-      },
-    },
-  },
-  render: () => {
-    const types: Array<'normal' | 'simple' | 'mini'> = [
-      'normal',
-      'simple',
-      'mini',
-    ];
-    const sizes: Array<'sm' | 'md' | 'lg'> = ['sm', 'md', 'lg'];
-    return (
-      <div className="flex flex-col gap-6">
-        {types.map((t) => (
-          <div key={t} className="flex flex-col gap-3">
-            <div className="text-sm font-medium text-muted-foreground">
-              type = {t}
-            </div>
-            {sizes.map((s) => {
-              // 每行独立受控 — 让 demo 可交互
-              return (
-                <MatrixRow
-                  key={`${t}-${s}`}
-                  type={t}
-                  size={s}
-                  showTotal={t !== 'mini'}
-                />
-              );
-            })}
-          </div>
-        ))}
-      </div>
-    );
-  },
-};
-
-const MatrixRow = ({
-  type,
-  size,
-  showTotal,
-}: {
-  type: 'normal' | 'simple' | 'mini';
-  size: 'sm' | 'md' | 'lg';
-  showTotal?: boolean;
-}) => {
-  const [page, setPage] = React.useState(3);
-  return (
-    <div className="flex items-center gap-4">
-      <span className="w-10 shrink-0 text-xs text-muted-foreground">
-        {size}
-      </span>
-      <SimplePagination
-        total={245}
-        type={type}
-        size={size}
-        showTotal={showTotal}
-        current={page}
-        onChange={(p) => setPage(p)}
-      />
-    </div>
-  );
-};
-
-// ─── pageSizeSelector + showJump(normal 专属)─────────────────────────────
-
-export const WithPageSizeSelector: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const [page, setPage] = React.useState(1);
-    const [size, setSize] = React.useState(10);
-    return (
-      <SimplePagination
-        total={1234}
-        current={page}
-        pageSize={size}
-        pageSizeSelector
-        pageSizeList={[10, 20, 50, 100]}
-        onChange={(p, s) => {
-          setPage(p);
-          setSize(s);
-        }}
-        onPageSizeChange={(s) => setSize(s)}
-      />
-    );
-  },
-};
-
-export const WithJumpAndFirstLast: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const [page, setPage] = React.useState(15);
-    return (
-      <SimplePagination
-        total={1234}
-        current={page}
-        showFirstLast
-        showJump
-        pageSizeSelector
-        onChange={(p) => setPage(p)}
-      />
-    );
-  },
-};
-
-// ─── 自定义总数文本 ─────────────────────────────────────────────────────────
-
-export const CustomTotal: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => {
-    const [page, setPage] = React.useState(1);
-    return (
-      <SimplePagination
-        total={245}
-        current={page}
-        onChange={(p) => setPage(p)}
-        totalRender={(t, [s, e]) => `${s}–${e} of ${t}`}
-      />
-    );
-  },
-};
-
-// ─── 非受控 ─────────────────────────────────────────────────────────────────
-
-export const Uncontrolled: Story = {
-  parameters: { controls: { disable: true } },
-  render: () => (
-    <SimplePagination total={245} defaultCurrent={2} pageSizeSelector />
-  ),
-};