@teamix-evo/ui 0.2.0 → 0.4.0

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

@@ -10,16 +10,18 @@ package: '@teamix-evo/ui'
 
 # Pagination 分页
 
-分页 — 两套 API:
+**分页 — 在大量内容中按页切换浏览,带受控/非受控 + 页码窗口折叠 + 三档密度 + 三种形态**。两套 API:
 
 1. **shadcn primitives**(`Pagination / Content / Item / Link / Previous / Next / Ellipsis`)— 完全可组合,适合自定义复杂分页布局
-2. **`SimplePagination`**(antd 风格 props 化高阶包装)— `total / pageSize / current / onChange` 即用,**自动计算页码窗口 + 折叠 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
 
@@ -31,27 +33,25 @@ package: '@teamix-evo/ui'
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
-
-#### SimplePagination
-
-| 名称            | 类型                                                          | 默认值  | 必填 | 说明                                             |
-| --------------- | ------------------------------------------------------------- | ------- | ---- | ------------------------------------------------ |
-| `current`       | `number`                                                      | –       | –    | 当前页(1-based)。                                |
-| `onChange`      | `(page: number) => void`                                      | –       | –    | 受控变化回调。                                   |
-| `total`         | `number`                                                      | –       | ✓    | 总条数。                                         |
-| `pageSize`      | `number`                                                      | `10`    | –    | 每页大小。                                       |
-| `showFirstLast` | `boolean`                                                     | `false` | –    | 是否显示首末页快捷按钮。                         |
-| `showTotal`     | `boolean`                                                     | `true`  | –    | 是否显示总数文本(antd `showTotal` 并集,简化版)。 |
-| `totalRender`   | `(total: number, range: [number, number]) => React.ReactNode` | –       | –    | 自定义总数渲染。返回字符串或 ReactNode。         |
-| `siblingCount`  | `number`                                                      | `5`     | –    | 显示页号窗口大小(中间显示几个页号)。             |
-| `className`     | `string`                                                      | –       | –    | 容器 className。                                 |
-
-#### PaginationLink
-
-| 名称       | 类型      | 默认值 | 必填 | 说明                 |
-| ---------- | --------- | ------ | ---- | -------------------- |
-| `isActive` | `boolean` | –      | –    | 当前激活状态(高亮)。 |
-
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `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 -->
 
 ## 依赖
@@ -59,34 +59,40 @@ package: '@teamix-evo/ui'
 > 以下表格由 `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 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+| 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 lucide-react@^0.460.0
+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 主流一致
+- **`pageSize` 默认 10**:与 antd / Web 主流一致;`pageSizeList` 默认 `[10, 20, 50, 100]`
 - **`siblingCount` 控制中间窗口**:奇数(5/7)效果好,偶数会产生不对称
-- **`showSizeChanger` / `showQuickJumper` 在 v0.x**:本版不内置(简化 props),需要时业务侧组合 Select + Input
+- **`onChange` 第二参为 pageSize**:`(page, pageSize) => void` — 切换 pageSize 时会回到第 1 页并触发一次 `onChange(1, newSize)`
 - **不要嵌套 Pagination**:同一容器只一组分页
+- **不要传 antd 的 `defaultPageSize` 同时传 `pageSize`**:受控/非受控择一(运行时以受控值为准)
+- **跳转输入框**:`showJump` 默认 `false`,启用后回车提交;非数字静默忽略
 
 ## Examples
 
@@ -94,33 +100,65 @@ pnpm add lucide-react@^0.460.0
 import { SimplePagination } from '@/components/ui/pagination';
 import * as React from 'react';
 
-// 高阶 API(推荐)
+// 受控 + 默认 normal × md
 const [page, setPage] = React.useState(1);
 <SimplePagination
   total={245}
   current={page}
   pageSize={10}
-  onChange={setPage}
+  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}
-  pageSize={10}
   current={page}
-  onChange={setPage}
+  onChange={(p) => setPage(p)}
   totalRender={(t, [s, e]) => `${s}-${e} of ${t}`}
 />
 
-// 显示首末快捷
-<SimplePagination total={500} current={page} onChange={setPage} showFirstLast />
-
-// 不显示总数
-<SimplePagination total={245} current={page} onChange={setPage} showTotal={false} />
+// 非受控 — defaultCurrent + defaultPageSize
+<SimplePagination total={245} defaultCurrent={2} defaultPageSize={20} pageSizeSelector />
 ```
 
 ```tsx
-// 自由组合(primitives)
+// 自由组合(primitives)— 自定义任意布局
 import {
   Pagination,
   PaginationContent,
@@ -134,25 +172,59 @@ import {
 <Pagination>
   <PaginationContent>
     <PaginationItem>
-      <PaginationPrevious href="#" />
+      <PaginationPrevious size="md" onClick={...} />
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#">1</PaginationLink>
+      <PaginationLink size="md" onClick={...}>1</PaginationLink>
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#" isActive>
-        2
-      </PaginationLink>
+      <PaginationLink size="md" isActive>2</PaginationLink>
     </PaginationItem>
     <PaginationItem>
-      <PaginationLink href="#">3</PaginationLink>
+      <PaginationLink size="md" onClick={...}>3</PaginationLink>
     </PaginationItem>
     <PaginationItem>
-      <PaginationEllipsis />
+      <PaginationEllipsis size="md" />
     </PaginationItem>
     <PaginationItem>
-      <PaginationNext href="#" />
+      <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,5 +1,5 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { SimplePagination } from './pagination';
 
 const meta: Meta<typeof SimplePagination> = {
@@ -10,7 +10,7 @@ const meta: Meta<typeof SimplePagination> = {
     docs: {
       description: {
         component:
-          '分页 — 两套 API:SimplePagination(antd 风格 props 化,total / pageSize / current / onChange 即用) + shadcn primitives(完全可组合)。自动计算页码窗口 + 折叠 ellipsis + 显示总数。',
+          '**分页 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。',
       },
     },
   },
@@ -20,9 +20,19 @@ const meta: Meta<typeof SimplePagination> = {
     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 },
-  decorators: [(Story) => <div className="w-[640px]">{Story()}</div>],
+  args: {
+    total: 245,
+    pageSize: 10,
+    siblingCount: 5,
+    size: 'md',
+    type: 'normal',
+  },
+  decorators: [(Story) => <div className="w-[760px]">{Story()}</div>],
 };
 
 export default meta;
@@ -31,26 +41,224 @@ 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={setPage} />;
+    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 FirstLast: Story = {
+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={500}
-        pageSize={10}
+        total={1234}
         current={page}
-        onChange={setPage}
         showFirstLast
+        showJump
+        pageSizeSelector
+        onChange={(p) => setPage(p)}
       />
     );
   },
 };
 
+// ─── 自定义总数文本 ─────────────────────────────────────────────────────────
+
 export const CustomTotal: Story = {
   parameters: { controls: { disable: true } },
   render: () => {
@@ -58,11 +266,19 @@ export const CustomTotal: Story = {
     return (
       <SimplePagination
         total={245}
-        pageSize={10}
         current={page}
-        onChange={setPage}
+        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 />
+  ),
+};