@teamix-evo/ui 0.3.0 → 0.5.0

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

@@ -1,281 +0,0 @@
-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,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]` 数组                              |