@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/page-header/page-header.tsx

@@ -0,0 +1,281 @@
+import * as React from 'react';
+import { ArrowLeft } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import { Skeleton, SkeletonParagraph } from '@/components/skeleton/skeleton';
+
+// ─── PageHeader: 顶层容器(<header>) ─────────────────────────────────────────
+
+export interface PageHeaderProps extends React.HTMLAttributes<HTMLElement> {
+  /**
+   * 右下角背景装饰图 URL — 通过 inline `style.backgroundImage` 注入(Tailwind 不支持
+   * 动态 URL)。固定 `bg-no-repeat bg-right-bottom`。
+   */
+  backgroundImage?: string;
+}
+
+const PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(
+  ({ className, backgroundImage, style, children, ...props }, ref) => {
+    const bgStyle: React.CSSProperties | undefined = backgroundImage
+      ? {
+          backgroundImage: `url(${backgroundImage})`,
+          backgroundRepeat: 'no-repeat',
+          backgroundPosition: 'right bottom',
+          ...style,
+        }
+      : style;
+
+    return (
+      <header
+        ref={ref}
+        className={cn(
+          'relative flex flex-col gap-4 overflow-hidden bg-background px-6 py-4',
+          className,
+        )}
+        style={bgStyle}
+        {...props}
+      >
+        {children}
+      </header>
+    );
+  },
+);
+PageHeader.displayName = 'PageHeader';
+
+// ─── PageHeaderNav: 导航层(面包屑 + 右侧链接)──────────────────────────────
+
+const PageHeaderNav = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      'flex min-h-5 items-center justify-between text-xs',
+      className,
+    )}
+    {...props}
+  />
+));
+PageHeaderNav.displayName = 'PageHeaderNav';
+
+// ─── PageHeaderContent: 主内容区(左右双列)─────────────────────────────────
+
+const PageHeaderContent = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      'flex flex-wrap items-start justify-between gap-4',
+      className,
+    )}
+    {...props}
+  />
+));
+PageHeaderContent.displayName = 'PageHeaderContent';
+
+// ─── PageHeaderHeading: 标题行 ───────────────────────────────────────────────
+
+export interface PageHeaderHeadingProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 前置返回按钮。为 `true` 时渲染 `ArrowLeft` 图标按钮,点击触发 `onBack`。
+   * @default false
+   */
+  goBack?: boolean;
+  /** 返回按钮点击回调。 */
+  onBack?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+}
+
+const PageHeaderHeading = React.forwardRef<
+  HTMLDivElement,
+  PageHeaderHeadingProps
+>(({ className, goBack = false, onBack, children, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex items-center gap-3', className)}
+    {...props}
+  >
+    {goBack ? (
+      <button
+        type="button"
+        onClick={onBack}
+        aria-label="返回"
+        className={cn(
+          'inline-flex size-8 shrink-0 cursor-pointer items-center justify-center text-muted-foreground transition-colors',
+          'hover:text-foreground',
+          'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+        )}
+      >
+        <ArrowLeft className="size-5" aria-hidden="true" />
+      </button>
+    ) : null}
+    {children}
+  </div>
+));
+PageHeaderHeading.displayName = 'PageHeaderHeading';
+
+// ─── PageHeaderDescription: 描述文字(<p>) ──────────────────────────────────
+
+const PageHeaderDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={cn('text-xs text-muted-foreground', className)}
+    {...props}
+  />
+));
+PageHeaderDescription.displayName = 'PageHeaderDescription';
+
+// ─── PageHeaderActions: 操作按钮区 ───────────────────────────────────────────
+
+const PageHeaderActions = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex shrink-0 items-center gap-2', className)}
+    {...props}
+  />
+));
+PageHeaderActions.displayName = 'PageHeaderActions';
+
+// ─── PageHeaderData / PageHeaderDataItem: 数据概览 ───────────────────────────
+
+const PageHeaderData = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('flex shrink-0 items-end gap-6', className)}
+    {...props}
+  />
+));
+PageHeaderData.displayName = 'PageHeaderData';
+
+const dataItemColor = {
+  default: 'text-foreground',
+  primary: 'text-primary',
+  success: 'text-success',
+  warning: 'text-warning',
+  destructive: 'text-destructive',
+} as const;
+
+export interface PageHeaderDataItemProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /** 数据标签(上行,muted 小字)。 */
+  label: React.ReactNode;
+  /**
+   * 值的语义色(调色板) — 对齐 [ADR 0021](../../../../../docs/adr/0021-semantic-color-api-unification.md)。
+   *
+   * 填充背景类场景 default 本身为中性色,省略 muted 档;信息色用 `primary`,不收 `info`。
+   * @default "default"
+   */
+  color?: keyof typeof dataItemColor;
+}
+
+const PageHeaderDataItem = React.forwardRef<
+  HTMLDivElement,
+  PageHeaderDataItemProps
+>(({ className, label, color = 'default', children, ...props }, ref) => (
+  <div ref={ref} className={cn('flex flex-col', className)} {...props}>
+    <span className="text-xs text-muted-foreground">{label}</span>
+    <span
+      className={cn(
+        'text-base font-semibold tabular-nums',
+        dataItemColor[color],
+      )}
+    >
+      {children}
+    </span>
+  </div>
+));
+PageHeaderDataItem.displayName = 'PageHeaderDataItem';
+
+// ─── PageHeaderFooter: 底部详情 ──────────────────────────────────────────────
+
+const PageHeaderFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn('mt-4 border-t border-t-border pt-4', className)}
+    {...props}
+  />
+));
+PageHeaderFooter.displayName = 'PageHeaderFooter';
+
+// ─── PageHeaderSkeleton: 骨架屏 ──────────────────────────────────────────────
+
+export interface PageHeaderSkeletonProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 显示面包屑骨架行。
+   * @default true
+   */
+  showNav?: boolean;
+  /**
+   * 显示描述骨架行。
+   * @default true
+   */
+  showDescription?: boolean;
+  /**
+   * 显示底部详情骨架(3 列 × 2 行网格)。
+   * @default false
+   */
+  showFooter?: boolean;
+}
+
+const PageHeaderSkeleton = React.forwardRef<
+  HTMLDivElement,
+  PageHeaderSkeletonProps
+>(
+  (
+    {
+      className,
+      showNav = true,
+      showDescription = true,
+      showFooter = false,
+      ...props
+    },
+    ref,
+  ) => (
+    <div
+      ref={ref}
+      className={cn('flex flex-col gap-4 bg-background px-6 py-4', className)}
+      aria-busy="true"
+      {...props}
+    >
+      {showNav ? <Skeleton shape="line" className="h-3 w-48" /> : null}
+      <div className="flex items-center gap-3">
+        <Skeleton shape="rect" className="size-8 rounded-md" />
+        <Skeleton shape="line" className="h-6 w-80" />
+      </div>
+      {showDescription ? <Skeleton shape="line" className="h-4 w-96" /> : null}
+      {showFooter ? <SkeletonParagraph rows={2} className="pt-3" /> : null}
+    </div>
+  ),
+);
+PageHeaderSkeleton.displayName = 'PageHeaderSkeleton';
+
+// ─── exports ─────────────────────────────────────────────────────────────────
+
+export {
+  PageHeader,
+  PageHeaderNav,
+  PageHeaderContent,
+  PageHeaderHeading,
+  PageHeaderDescription,
+  PageHeaderActions,
+  PageHeaderData,
+  PageHeaderDataItem,
+  PageHeaderFooter,
+  PageHeaderSkeleton,
+};

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

@@ -1,23 +1,27 @@
 ---
 id: pagination
 name: Pagination
+displayName: 分页
 type: component
 category: navigation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Pagination
+# 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
 
@@ -26,19 +30,27 @@ package: "@teamix-evo/ui"
 
 ## Props
 
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表是 `SimplePagination` 的 props(高阶 API);primitives 的 props 详见 [`pagination.tsx`](./pagination.tsx)。
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
 
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `current` | `number` | – | – | 当前页(1-based)。 |
-| `onChange` | `(page: number) => void` | – | – | 受控变化回调。 |
+| `current` | `number` | – | – | 当前页(1-based,受控)。与 `defaultCurrent` 互斥。 |
+| `defaultCurrent` | `number` | `1` | – | 默认当前页(非受控)。 |
+| `onChange` | `(page: number, pageSize: number) => void` | – | – | 页码 / pageSize 变化回调。第二参为变化后的 pageSize。 |
 | `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` | – | 显示页号窗口大小(中间显示几个页号)。 |
+| `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 -->
 
@@ -54,27 +66,33 @@ package: "@teamix-evo/ui"
 | Entry | 类型 | 描述 |
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `button` | component | 通用按钮 — shadcn 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+| `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 -->
 
-> 子组件(primitives):`Pagination`(nav)/ `PaginationContent`(ul)/ `PaginationItem`(li)/ `PaginationLink`(支持 `isActive`)/ `PaginationPrevious` / `PaginationNext` / `PaginationEllipsis`。
-
 ## 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
 
@@ -82,46 +100,131 @@ 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, PaginationItem, PaginationLink,
-  PaginationPrevious, PaginationNext, PaginationEllipsis,
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
 } from '@/components/ui/pagination';
 
 <Pagination>
   <PaginationContent>
-    <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
-    <PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem>
-    <PaginationItem><PaginationLink href="#" isActive>2</PaginationLink></PaginationItem>
-    <PaginationItem><PaginationLink href="#">3</PaginationLink></PaginationItem>
-    <PaginationItem><PaginationEllipsis /></PaginationItem>
-    <PaginationItem><PaginationNext href="#" /></PaginationItem>
+    <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>;
 ```
+
+---
+
+## 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]` 数组                              |