@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/pagination/index.tsx

@@ -0,0 +1,580 @@
+/**
+ * 分页 Pagination
+ *
+ * 展示分页导航，支持翻页、跳转和省略标识。
+ * 两套 API：
+ * 1. primitives（Pagination / Content / Item / Link / Previous / Next / Ellipsis）— 完全可组合
+ * 2. Pagination — props 化高阶封装，自动计算页码窗口 + 折叠 ellipsis
+ *
+ * @when
+ * - 数据列表条目过多需分页展示
+ * - 配合 Table / DataTable 组件使用
+ * - 内容流布局底部导航
+ */
+
+import * as React from 'react';
+import {
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  ChevronsLeftIcon,
+  ChevronsRightIcon,
+  MoreHorizontalIcon,
+} from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/button';
+import { Input } from '@/components/input';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/select';
+
+// ─── 尺寸映射 ────────────────────────────────────────────────────────────────
+
+export type PaginationSize = 'sm' | 'md' | 'lg';
+export type PaginationType = 'normal' | 'simple' | 'mini';
+
+/** pagination size → Button/Input size */
+const toComponentSize = (s: PaginationSize) =>
+  s === 'sm' ? 'sm' : s === 'lg' ? 'lg' : ('default' as const);
+
+const sizeClass: Record<PaginationSize, string> = {
+  sm: 'text-xs',
+  md: 'text-xs',
+  lg: 'text-sm',
+};
+
+const buttonHeightClass: Record<PaginationSize, string> = {
+  sm: 'size-6',
+  md: 'size-8',
+  lg: 'size-9',
+};
+
+// ─── shadcn-style primitives ────────────────────────────────────────────────
+
+/** 分页根容器（内部使用）。 */
+function PaginationNav({ className, ...props }: React.ComponentProps<'nav'>) {
+  return (
+    <nav
+      role="navigation"
+      aria-label="pagination"
+      data-slot="pagination"
+      className={cn(
+        'mx-auto flex w-full items-center justify-center',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/** 分页项列表。 */
+function PaginationContent({
+  className,
+  ...props
+}: React.ComponentProps<'ul'>) {
+  return (
+    <ul
+      data-slot="pagination-content"
+      className={cn('flex items-center gap-1', className)}
+      {...props}
+    />
+  );
+}
+
+/** 单个分页项包裹。 */
+function PaginationItem({ ...props }: React.ComponentProps<'li'>) {
+  return <li data-slot="pagination-item" {...props} />;
+}
+
+interface PaginationLinkProps
+  extends Omit<
+    React.ComponentProps<typeof Button>,
+    'size' | 'variant' | 'shape'
+  > {
+  /** 当前激活状态(高亮选中页)。 */
+  isActive?: boolean;
+  /** 尺寸。 @default "md" */
+  size?: PaginationSize;
+}
+
+/** 可点击的分页链接/按钮。 */
+function PaginationLink({
+  className,
+  isActive,
+  size = 'md',
+  ...props
+}: PaginationLinkProps) {
+  return (
+    <Button
+      aria-current={isActive ? 'page' : undefined}
+      data-slot="pagination-link"
+      data-active={isActive}
+      variant="ghost"
+      size={toComponentSize(size)}
+      className={cn(
+        // 让数字键近似方块: min-width = height
+        buttonHeightClass[size],
+        'min-w-0 p-0 tabular-nums',
+        isActive
+          ? 'border border-primary bg-card text-primary hover:bg-card hover:text-primary'
+          : 'hover:bg-muted hover:text-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+interface PaginationNavProps
+  extends Omit<
+    React.ComponentProps<typeof Button>,
+    'size' | 'variant' | 'shape'
+  > {
+  /** 尺寸。 @default "md" */
+  size?: PaginationSize;
+  /** 仅显示图标(不显示文字)。 @default false */
+  iconOnly?: boolean;
+}
+
+/** 上一页按钮。 */
+function PaginationPrevious({
+  className,
+  size = 'md',
+  iconOnly = false,
+  children,
+  ...props
+}: PaginationNavProps) {
+  return (
+    <Button
+      aria-label="Go to previous page"
+      data-slot="pagination-previous"
+      variant="ghost"
+      size={toComponentSize(size)}
+      className={cn(
+        buttonHeightClass[size],
+        'min-w-0 p-0 text-muted-foreground hover:bg-muted hover:text-foreground',
+        iconOnly && 'aspect-square',
+        !iconOnly && 'gap-1 px-2.5',
+        className,
+      )}
+      {...props}
+    >
+      <ChevronLeftIcon className="size-4" />
+      {!iconOnly && (children ?? <span>上一页</span>)}
+    </Button>
+  );
+}
+
+/** 下一页按钮。 */
+function PaginationNext({
+  className,
+  size = 'md',
+  iconOnly = false,
+  children,
+  ...props
+}: PaginationNavProps) {
+  return (
+    <Button
+      aria-label="Go to next page"
+      data-slot="pagination-next"
+      variant="ghost"
+      size={toComponentSize(size)}
+      className={cn(
+        buttonHeightClass[size],
+        'min-w-0 p-0 text-muted-foreground hover:bg-muted hover:text-foreground',
+        iconOnly && 'aspect-square',
+        !iconOnly && 'gap-1 px-2.5',
+        className,
+      )}
+      {...props}
+    >
+      {!iconOnly && (children ?? <span>下一页</span>)}
+      <ChevronRightIcon className="size-4" />
+    </Button>
+  );
+}
+
+/** 省略号标识。 */
+function PaginationEllipsis({
+  className,
+  size = 'md',
+  ...props
+}: React.ComponentProps<'span'> & { size?: PaginationSize }) {
+  return (
+    <span
+      aria-hidden="true"
+      data-slot="pagination-ellipsis"
+      className={cn(
+        'flex items-center justify-center text-muted-foreground',
+        buttonHeightClass[size],
+        className,
+      )}
+      {...props}
+    >
+      <MoreHorizontalIcon className="size-4" />
+      <span className="sr-only">More pages</span>
+    </span>
+  );
+}
+
+// ─── Pagination 高阶组件 ────────────────────────────────────────────────────
+
+export interface PaginationProps {
+  /** 当前页(1-based，受控)。与 `defaultCurrent` 互斥。 */
+  current?: number;
+  /** 默认当前页(非受控)。 @default 1 */
+  defaultCurrent?: number;
+  /** 页码 / pageSize 变化回调。第二参为变化后的 pageSize。 */
+  onChange?: (page: number, pageSize: number) => void;
+  /** 总条数。 */
+  total: number;
+  /** 每页大小(受控)。与 `defaultPageSize` 互斥。 */
+  pageSize?: number;
+  /** 默认每页大小(非受控)。 @default 10 */
+  defaultPageSize?: number;
+  /** 每页大小可选项。 @default [10, 20, 50, 100] */
+  pageSizeOptions?: number[];
+  /** 显示每页大小选择器。 @default false */
+  showSizeChanger?: boolean;
+  /** pageSize 变化回调。 */
+  onPageSizeChange?: (pageSize: number) => void;
+  /** 组件大小: sm(h-6) / md(h-8) / lg(h-9)。 @default "md" */
+  size?: PaginationSize;
+  /** 组件类型: normal(完整) / simple(简化) / mini(极简)。 @default "normal" */
+  type?: PaginationType;
+  /** normal 类型下显示首末页快捷按钮。 @default false */
+  showFirstLast?: boolean;
+  /** 显示总数文本。 @default false */
+  showTotal?: boolean;
+  /** 自定义总数渲染。 */
+  totalRender?: (total: number, range: [number, number]) => React.ReactNode;
+  /** normal 类型下显示快速跳转输入框。 @default false */
+  showQuickJumper?: boolean;
+  /** 中间显示几个页号(建议奇数)。 @default 5 */
+  siblingCount?: number;
+  /** 容器 className。 */
+  className?: string;
+}
+
+/**
+ * Pagination — props 化用法，
+ * 自动计算页码窗口 + 折叠 ellipsis，支持 size / type / showSizeChanger。
+ */
+function Pagination({
+  current,
+  defaultCurrent = 1,
+  onChange,
+  total,
+  pageSize,
+  defaultPageSize = 10,
+  pageSizeOptions = [10, 20, 50, 100],
+  showSizeChanger = false,
+  onPageSizeChange,
+  size = 'md',
+  type = 'normal',
+  showFirstLast = false,
+  showTotal = false,
+  totalRender,
+  showQuickJumper = false,
+  siblingCount = 5,
+  className,
+}: PaginationProps) {
+  const [innerCurrent, setInnerCurrent] = React.useState(defaultCurrent);
+  const [innerPageSize, setInnerPageSize] = React.useState(defaultPageSize);
+
+  const finalCurrent = current ?? innerCurrent;
+  const finalPageSize = pageSize ?? innerPageSize;
+  const totalPages = Math.max(1, Math.ceil(total / finalPageSize));
+  const page = Math.min(Math.max(1, finalCurrent), totalPages);
+
+  const goto = (n: number) => {
+    if (n < 1 || n > totalPages || n === page) return;
+    if (current === undefined) setInnerCurrent(n);
+    onChange?.(n, finalPageSize);
+  };
+
+  const handlePageSizeChange = (value: string) => {
+    const v = Number(value);
+    if (Number.isNaN(v)) return;
+    if (pageSize === undefined) setInnerPageSize(v);
+    if (current === undefined) setInnerCurrent(1);
+    onPageSizeChange?.(v);
+    onChange?.(1, v);
+  };
+
+  const [jumperVal, setJumperVal] = React.useState('');
+  const handleJumpKey = (e: React.KeyboardEvent<HTMLInputElement>) => {
+    if (e.key !== 'Enter') return;
+    const v = Number(jumperVal);
+    if (Number.isFinite(v)) goto(v);
+    setJumperVal('');
+  };
+
+  const pages = React.useMemo(() => {
+    const half = Math.floor(siblingCount / 2);
+    let start = Math.max(1, page - half);
+    const end = Math.min(totalPages, start + siblingCount - 1);
+    if (end - start + 1 < siblingCount) {
+      start = Math.max(1, end - siblingCount + 1);
+    }
+    const arr: number[] = [];
+    for (let i = start; i <= end; i++) arr.push(i);
+    return arr;
+  }, [page, siblingCount, totalPages]);
+
+  const rangeStart = total === 0 ? 0 : (page - 1) * finalPageSize + 1;
+  const rangeEnd = Math.min(page * finalPageSize, total);
+
+  const showLeftEllipsis = (pages[0] ?? 1) > 2;
+  const showRightEllipsis =
+    (pages[pages.length - 1] ?? totalPages) < totalPages - 1;
+
+  // ─── 总数文本 ─────────────────────────────────────────────────────────────
+  const totalNode =
+    showTotal && type !== 'mini' ? (
+      <p className={cn('text-muted-foreground tabular-nums', sizeClass[size])}>
+        {totalRender
+          ? totalRender(total, [rangeStart, rangeEnd])
+          : `共 ${total} 条`}
+      </p>
+    ) : null;
+
+  // ─── 主体 ─────────────────────────────────────────────────────────────────
+  let body: React.ReactNode;
+
+  if (type === 'mini') {
+    body = (
+      <PaginationNav className="mx-0 w-auto">
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationPrevious
+              size={size}
+              iconOnly
+              disabled={page === 1}
+              onClick={() => goto(page - 1)}
+            />
+          </PaginationItem>
+          <PaginationItem>
+            <PaginationNext
+              size={size}
+              iconOnly
+              disabled={page === totalPages}
+              onClick={() => goto(page + 1)}
+            />
+          </PaginationItem>
+        </PaginationContent>
+      </PaginationNav>
+    );
+  } else if (type === 'simple') {
+    body = (
+      <PaginationNav className="mx-0 w-auto">
+        <PaginationContent>
+          <PaginationItem>
+            <PaginationPrevious
+              size={size}
+              iconOnly
+              disabled={page === 1}
+              onClick={() => goto(page - 1)}
+            />
+          </PaginationItem>
+          <PaginationItem>
+            <span
+              className={cn(
+                'flex items-center gap-1 px-2 tabular-nums',
+                sizeClass[size],
+              )}
+            >
+              <span className="text-foreground">{page}</span>
+              <span className="text-muted-foreground">/</span>
+              <span className="text-muted-foreground">{totalPages}</span>
+            </span>
+          </PaginationItem>
+          <PaginationItem>
+            <PaginationNext
+              size={size}
+              iconOnly
+              disabled={page === totalPages}
+              onClick={() => goto(page + 1)}
+            />
+          </PaginationItem>
+        </PaginationContent>
+      </PaginationNav>
+    );
+  } else {
+    body = (
+      <PaginationNav className="mx-0 w-auto">
+        <PaginationContent>
+          {showFirstLast && (
+            <PaginationItem>
+              <PaginationLink
+                aria-label="First"
+                size={size}
+                disabled={page === 1}
+                onClick={() => goto(1)}
+              >
+                <ChevronsLeftIcon className="size-4" />
+              </PaginationLink>
+            </PaginationItem>
+          )}
+          <PaginationItem>
+            <PaginationPrevious
+              size={size}
+              iconOnly
+              disabled={page === 1}
+              onClick={() => goto(page - 1)}
+            />
+          </PaginationItem>
+          {(pages[0] ?? 1) > 1 && (
+            <PaginationItem>
+              <PaginationLink size={size} onClick={() => goto(1)}>
+                1
+              </PaginationLink>
+            </PaginationItem>
+          )}
+          {showLeftEllipsis && (
+            <PaginationItem>
+              <PaginationEllipsis size={size} />
+            </PaginationItem>
+          )}
+          {pages.map((p) => (
+            <PaginationItem key={p}>
+              <PaginationLink
+                size={size}
+                isActive={p === page}
+                onClick={() => goto(p)}
+              >
+                {p}
+              </PaginationLink>
+            </PaginationItem>
+          ))}
+          {showRightEllipsis && (
+            <PaginationItem>
+              <PaginationEllipsis size={size} />
+            </PaginationItem>
+          )}
+          {(pages[pages.length - 1] ?? totalPages) < totalPages && (
+            <PaginationItem>
+              <PaginationLink size={size} onClick={() => goto(totalPages)}>
+                {totalPages}
+              </PaginationLink>
+            </PaginationItem>
+          )}
+          <PaginationItem>
+            <PaginationNext
+              size={size}
+              iconOnly
+              disabled={page === totalPages}
+              onClick={() => goto(page + 1)}
+            />
+          </PaginationItem>
+          {showFirstLast && (
+            <PaginationItem>
+              <PaginationLink
+                aria-label="Last"
+                size={size}
+                disabled={page === totalPages}
+                onClick={() => goto(totalPages)}
+              >
+                <ChevronsRightIcon className="size-4" />
+              </PaginationLink>
+            </PaginationItem>
+          )}
+        </PaginationContent>
+        {/* 页码指示器 */}
+        <span
+          className={cn(
+            'ml-2 tabular-nums text-muted-foreground',
+            sizeClass[size],
+          )}
+        >
+          {page}/{totalPages}
+        </span>
+      </PaginationNav>
+    );
+  }
+
+  // ─── 附加区域（pageSizeSelector / 跳转）仅 normal 生效 ─────────────────────
+  const showAddons = type === 'normal' && (showSizeChanger || showQuickJumper);
+
+  const addons = showAddons ? (
+    <div className={cn('flex items-center gap-2', sizeClass[size])}>
+      {showSizeChanger && (
+        <Select
+          value={String(finalPageSize)}
+          onValueChange={handlePageSizeChange}
+        >
+          <SelectTrigger
+            size={size === 'sm' ? 'sm' : 'default'}
+            aria-label="每页显示"
+          >
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent>
+            {pageSizeOptions.map((opt) => (
+              <SelectItem key={opt} value={String(opt)}>
+                {opt} 条/页
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      )}
+      {showQuickJumper && (
+        <span className="inline-flex items-center gap-2 text-muted-foreground">
+          到第
+          <Input
+            size={size === 'sm' ? 'sm' : size === 'lg' ? 'lg' : 'default'}
+            inputMode="numeric"
+            value={jumperVal}
+            onChange={(e) => setJumperVal(e.target.value)}
+            onKeyDown={handleJumpKey}
+            className="w-12 text-center tabular-nums"
+            aria-label="跳转到页"
+          />
+          页
+          <Button
+            variant="outline"
+            size={toComponentSize(size)}
+            className="text-foreground hover:text-foreground"
+            onClick={() => {
+              const v = Number(jumperVal);
+              if (Number.isFinite(v)) goto(v);
+              setJumperVal('');
+            }}
+          >
+            确定
+          </Button>
+        </span>
+      )}
+    </div>
+  ) : null;
+
+  return (
+    <div
+      className={cn(
+        'flex w-full flex-wrap items-center justify-end gap-3',
+        className,
+      )}
+    >
+      {totalNode}
+      <div className="flex flex-wrap items-center gap-3">
+        {body}
+        {addons}
+      </div>
+    </div>
+  );
+}
+
+export {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNav,
+  PaginationNext,
+  PaginationPrevious,
+};

package/src/components/pagination/meta.md

@@ -0,0 +1,39 @@
+# Pagination
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+分页 Pagination
+展示分页导航，支持翻页、跳转和省略标识。
+两套 API：
+1. primitives（Pagination / Content / Item / Link / Previous / Next / Ellipsis）— 完全可组合
+2. Pagination — props 化高阶封装，自动计算页码窗口 + 折叠 ellipsis
+
+## 使用场景
+
+- 数据列表条目过多需分页展示
+- 配合 Table / DataTable 组件使用
+- 内容流布局底部导航
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `current` | `number` | – | – | 当前页(1-based，受控)。与 `defaultCurrent` 互斥。 |
+| `defaultCurrent` | `number` | `1` | – | 默认当前页(非受控)。 |
+| `onChange` | `(page: number, pageSize: number) => void` | – | – | 页码 / pageSize 变化回调。第二参为变化后的 pageSize。 |
+| `total` | `number` | – | ✓ | 总条数。 |
+| `pageSize` | `number` | – | – | 每页大小(受控)。与 `defaultPageSize` 互斥。 |
+| `defaultPageSize` | `number` | `10` | – | 默认每页大小(非受控)。 |
+| `pageSizeOptions` | `number[]` | `[10, 20, 50, 100]` | – | 每页大小可选项。 |
+| `showSizeChanger` | `boolean` | `false` | – | 显示每页大小选择器。 |
+| `onPageSizeChange` | `(pageSize: number) => void` | – | – | pageSize 变化回调。 |
+| `size` | `PaginationSize` | `"md"` | – | 组件大小: sm(h-6) / md(h-8) / lg(h-9)。 |
+| `type` | `PaginationType` | `"normal"` | – | 组件类型: normal(完整) / simple(简化) / mini(极简)。 |
+| `showFirstLast` | `boolean` | `false` | – | normal 类型下显示首末页快捷按钮。 |
+| `showTotal` | `boolean` | `false` | – | 显示总数文本。 |
+| `totalRender` | `(total: number, range: [number, number]) => React.ReactNode` | – | – | 自定义总数渲染。 |
+| `showQuickJumper` | `boolean` | `false` | – | normal 类型下显示快速跳转输入框。 |
+| `siblingCount` | `number` | `5` | – | 中间显示几个页号(建议奇数)。 |
+| `className` | `string` | – | – | 容器 className。 |