@teamix-evo/ui 0.1.1

package/src/components/notification/notification.stories.tsx

@@ -0,0 +1,96 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Toaster } from '@/components/sonner/sonner';
+import { notification } from './notification';
+import { Button } from '@/components/button/button';
+
+const meta: Meta = {
+  title: '反馈与浮层 · Feedback/Notification',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '卡片式通知 — 右上角 title + description 卡片(部署成功 / 配额提醒)。基于 sonner toast.custom,业务侧只需挂载一次 `<Toaster />`,后续在任意地方 imperative 触发。等价 antd `Notification`,与 toast(message)互补。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Playground: Story = {
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <Toaster position="top-right" />
+      <div className="flex flex-wrap gap-2">
+        <Button
+          variant="outline"
+          onClick={() =>
+            notification.info({ title: '提示', description: '这是一条 info 通知' })
+          }
+        >
+          Info
+        </Button>
+        <Button
+          onClick={() =>
+            notification.success({
+              title: '部署成功',
+              description: '用户可在 1 分钟内访问新版本',
+            })
+          }
+        >
+          Success
+        </Button>
+        <Button
+          variant="outline"
+          onClick={() =>
+            notification.warning({
+              title: '配额即将到期',
+              description: '请在 3 天内续费,否则服务将暂停',
+            })
+          }
+        >
+          Warning
+        </Button>
+        <Button
+          variant="destructive"
+          onClick={() =>
+            notification.error({
+              title: '上传失败',
+              description: '请检查网络连接后重试',
+            })
+          }
+        >
+          Error
+        </Button>
+      </div>
+    </div>
+  ),
+};
+
+export const WithAction: Story = {
+  render: () => (
+    <div className="flex flex-col gap-2">
+      <Toaster position="top-right" />
+      <Button
+        onClick={() =>
+          notification.open({
+            type: 'info',
+            title: '新版本可用',
+            description: 'v2.5 已发布,刷新页面以应用更新',
+            action: {
+              label: '刷新',
+              onClick: () => {
+                // eslint-disable-next-line no-alert
+                alert('刷新');
+              },
+            },
+          })
+        }
+      >
+        显示带操作的通知
+      </Button>
+    </div>
+  ),
+};

package/src/components/notification/notification.tsx

@@ -0,0 +1,84 @@
+import * as React from 'react';
+import { toast, type ExternalToast } from 'sonner';
+import { AlertCircle, CheckCircle2, Info, XCircle } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+/**
+ * 卡片式通知 — antd 独有补足。**等价 antd `Notification`**(右上角卡片,与 sonner 同一栈)。
+ * 基于 sonner 二次封装,提供 antd 风格的"标题 + 描述 + 状态图标"卡片化 API,
+ * 与 `Toaster`(toast 容器)共用同一渲染层 —— 业务侧只需要挂载一次 `<Toaster />`。
+ *
+ * 与 `toast()` 区别:
+ *   - `toast()` 是无标题短文字(对应 antd `message`)
+ *   - `notification.open()` 是 **title + description 卡片**(对应 antd `notification`)
+ */
+
+export type NotificationType = 'info' | 'success' | 'warning' | 'error';
+
+export interface NotificationOptions extends Omit<ExternalToast, 'description' | 'icon'> {
+  /** 标题(antd `message` 并集,但 antd 这里命名为 message,易混淆 — 我们用更准确的 `title`)。 */
+  title: React.ReactNode;
+  /** 描述(antd `description` 并集)。 */
+  description?: React.ReactNode;
+  /**
+   * 状态 — 决定左侧 icon 颜色;`open()` 默认 `info`。
+   * `success` / `warning` / `error` 也可用对应快捷方法。
+   */
+  type?: NotificationType;
+}
+
+const iconMap: Record<NotificationType, React.ReactNode> = {
+  info: <Info className="size-5 text-primary" />,
+  success: <CheckCircle2 className="size-5 text-emerald-500" />,
+  warning: <AlertCircle className="size-5 text-amber-500" />,
+  error: <XCircle className="size-5 text-destructive" />,
+};
+
+function fire(
+  type: NotificationType,
+  { title, description, ...rest }: NotificationOptions,
+) {
+  return toast.custom(
+    (id) => (
+      <div
+        role="alert"
+        className={cn(
+          'flex w-[360px] gap-3 rounded-md border bg-background p-4 text-sm shadow-lg',
+        )}
+      >
+        <span className="mt-0.5 shrink-0">{iconMap[type]}</span>
+        <div className="min-w-0 flex-1">
+          <div className="font-semibold leading-tight">{title}</div>
+          {description ? (
+            <div className="mt-1 text-muted-foreground">{description}</div>
+          ) : null}
+        </div>
+        <button
+          type="button"
+          aria-label="关闭"
+          onClick={() => toast.dismiss(id)}
+          className="text-muted-foreground transition-colors hover:text-foreground"
+        >
+          ×
+        </button>
+      </div>
+    ),
+    rest,
+  );
+}
+
+const notification = {
+  /**
+   * 通用打开 — 通过 `type` 区分状态;若只传 title,样式同 `info`。
+   */
+  open: (opts: NotificationOptions) => fire(opts.type ?? 'info', opts),
+  info: (opts: Omit<NotificationOptions, 'type'>) => fire('info', opts),
+  success: (opts: Omit<NotificationOptions, 'type'>) => fire('success', opts),
+  warning: (opts: Omit<NotificationOptions, 'type'>) => fire('warning', opts),
+  error: (opts: Omit<NotificationOptions, 'type'>) => fire('error', opts),
+  /** 主动关闭某条(传 `id`)/ 全部(不传)。 */
+  destroy: (id?: string | number) => toast.dismiss(id),
+};
+
+export { notification };

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

@@ -0,0 +1,127 @@
+---
+id: pagination
+name: Pagination
+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 + 显示总数**
+
+## When to use
+
+- 列表 / 表格分页(配 Data Table)
+- 长内容多页阅读
+- 搜索结果分页
+
+## When NOT to use
+
+- 无限滚动 → IntersectionObserver + `hasMore` flag
+- 总数小(< 1 页)→ 不显示
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表是 `SimplePagination` 的 props(高阶 API);primitives 的 props 详见 [`pagination.tsx`](./pagination.tsx)。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `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。 |
+<!-- 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 实现 + antd 功能扩展(loading / icon / shape / block / dashed variant) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+> 子组件(primitives):`Pagination`(nav)/ `PaginationContent`(ul)/ `PaginationItem`(li)/ `PaginationLink`(支持 `isActive`)/ `PaginationPrevious` / `PaginationNext` / `PaginationEllipsis`。
+
+## AI 生成纪律
+
+- **业务侧用 `SimplePagination`**:除非要完全自定义布局,默认走高阶 API
+- **当前页 1-based**:antd 惯例,与 0-based 数组索引区分清楚
+- **`pageSize` 默认 10**:与 antd / Web 主流一致
+- **`siblingCount` 控制中间窗口**:奇数(5/7)效果好,偶数会产生不对称
+- **`showSizeChanger` / `showQuickJumper` 在 v0.x**:本版不内置(简化 props),需要时业务侧组合 Select + Input
+- **不要嵌套 Pagination**:同一容器只一组分页
+
+## Examples
+
+```tsx
+import { SimplePagination } from '@/components/ui/pagination';
+import * as React from 'react';
+
+// 高阶 API(推荐)
+const [page, setPage] = React.useState(1);
+<SimplePagination
+  total={245}
+  current={page}
+  pageSize={10}
+  onChange={setPage}
+/>
+
+// 自定义总数文本
+<SimplePagination
+  total={245}
+  pageSize={10}
+  current={page}
+  onChange={setPage}
+  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} />
+```
+
+```tsx
+// 自由组合(primitives)
+import {
+  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>
+  </PaginationContent>
+</Pagination>
+```

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

@@ -0,0 +1,62 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+import { SimplePagination } from './pagination';
+
+const meta: Meta<typeof SimplePagination> = {
+  title: '导航 · Navigation/Pagination',
+  component: SimplePagination,
+  tags: ['autodocs'],
+  argTypes: {
+    total: { control: 'number' },
+    pageSize: { control: 'number' },
+    siblingCount: { control: 'number' },
+    showFirstLast: { control: 'boolean' },
+    showTotal: { control: 'boolean' },
+  },
+  args: { total: 245, pageSize: 10, siblingCount: 5 },
+  decorators: [(Story) => <div className="w-[640px]">{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={setPage} />
+    );
+  },
+};
+
+export const FirstLast: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [page, setPage] = React.useState(15);
+    return (
+      <SimplePagination
+        total={500}
+        pageSize={10}
+        current={page}
+        onChange={setPage}
+        showFirstLast
+      />
+    );
+  },
+};
+
+export const CustomTotal: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => {
+    const [page, setPage] = React.useState(1);
+    return (
+      <SimplePagination
+        total={245}
+        pageSize={10}
+        current={page}
+        onChange={setPage}
+        totalRender={(t, [s, e]) => `${s}–${e} of ${t}`}
+      />
+    );
+  },
+};

package/src/components/pagination/pagination.tsx

@@ -0,0 +1,285 @@
+import * as React from 'react';
+import {
+  ChevronLeft,
+  ChevronRight,
+  ChevronsLeft,
+  ChevronsRight,
+  MoreHorizontal,
+} from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import { Button, type ButtonProps } from '@/components/button/button';
+
+// ─── shadcn-style primitives ──────────────────────────────────────────────────
+
+const Pagination = ({
+  className,
+  ...props
+}: React.ComponentProps<'nav'>) => (
+  <nav
+    role="navigation"
+    aria-label="pagination"
+    className={cn('mx-auto flex w-full justify-center', className)}
+    {...props}
+  />
+);
+Pagination.displayName = 'Pagination';
+
+const PaginationContent = React.forwardRef<
+  HTMLUListElement,
+  React.ComponentProps<'ul'>
+>(({ className, ...props }, ref) => (
+  <ul
+    ref={ref}
+    className={cn('flex flex-row items-center gap-1', className)}
+    {...props}
+  />
+));
+PaginationContent.displayName = 'PaginationContent';
+
+const PaginationItem = React.forwardRef<
+  HTMLLIElement,
+  React.ComponentProps<'li'>
+>(({ className, ...props }, ref) => (
+  <li ref={ref} className={cn('', className)} {...props} />
+));
+PaginationItem.displayName = 'PaginationItem';
+
+interface PaginationLinkProps
+  extends Pick<ButtonProps, 'size'>,
+    React.ComponentProps<'button'> {
+  isActive?: boolean;
+}
+
+const PaginationLink = ({
+  className,
+  isActive,
+  size = 'icon',
+  ...props
+}: PaginationLinkProps) => (
+  <Button
+    aria-current={isActive ? 'page' : undefined}
+    variant={isActive ? 'outline' : 'ghost'}
+    size={size}
+    className={cn(className)}
+    {...props}
+  />
+);
+PaginationLink.displayName = 'PaginationLink';
+
+const PaginationPrevious = ({
+  className,
+  ...props
+}: React.ComponentProps<typeof PaginationLink>) => (
+  <PaginationLink
+    aria-label="Go to previous page"
+    size="default"
+    className={cn('gap-1 pl-2.5', className)}
+    {...props}
+  >
+    <ChevronLeft className="size-4" />
+    <span>上一页</span>
+  </PaginationLink>
+);
+PaginationPrevious.displayName = 'PaginationPrevious';
+
+const PaginationNext = ({
+  className,
+  ...props
+}: React.ComponentProps<typeof PaginationLink>) => (
+  <PaginationLink
+    aria-label="Go to next page"
+    size="default"
+    className={cn('gap-1 pr-2.5', className)}
+    {...props}
+  >
+    <span>下一页</span>
+    <ChevronRight className="size-4" />
+  </PaginationLink>
+);
+PaginationNext.displayName = 'PaginationNext';
+
+const PaginationEllipsis = ({
+  className,
+  ...props
+}: React.ComponentProps<'span'>) => (
+  <span
+    aria-hidden="true"
+    className={cn('flex size-9 items-center justify-center', className)}
+    {...props}
+  >
+    <MoreHorizontal className="size-4" />
+    <span className="sr-only">More pages</span>
+  </span>
+);
+PaginationEllipsis.displayName = 'PaginationEllipsis';
+
+// ─── Higher-level wrapper(antd 风格 props 化分页器)───────────────────────
+
+export interface SimplePaginationProps {
+  /** 当前页(1-based)。 */
+  current?: number;
+  /** 受控变化回调。 */
+  onChange?: (page: number) => void;
+  /** 总条数。 */
+  total: number;
+  /** 每页大小。 @default 10 */
+  pageSize?: number;
+  /** 是否显示首末页快捷按钮。 @default false */
+  showFirstLast?: boolean;
+  /** 是否显示总数文本(antd `showTotal` 并集,简化版)。 @default true */
+  showTotal?: boolean;
+  /** 自定义总数渲染。返回字符串或 ReactNode。 */
+  totalRender?: (total: number, range: [number, number]) => React.ReactNode;
+  /** 显示页号窗口大小(中间显示几个页号)。 @default 5 */
+  siblingCount?: number;
+  /** 容器 className。 */
+  className?: string;
+}
+
+/**
+ * 高阶 Pagination — antd 风格 `total / pageSize / current / onChange` props 化用法,
+ * 自动计算页码窗口 + 折叠 ellipsis。
+ *
+ * 内部组合 `Pagination / PaginationContent / PaginationItem / PaginationLink /
+ * PaginationPrevious / PaginationNext / PaginationEllipsis` 这套 shadcn primitives,
+ * 业务方需要更细粒度时直接使用 primitives 自行拼装。
+ */
+const SimplePagination = ({
+  current = 1,
+  onChange,
+  total,
+  pageSize = 10,
+  showFirstLast = false,
+  showTotal = true,
+  totalRender,
+  siblingCount = 5,
+  className,
+}: SimplePaginationProps) => {
+  const totalPages = Math.max(1, Math.ceil(total / pageSize));
+  const page = Math.min(Math.max(1, current), totalPages);
+
+  const pages = React.useMemo(() => {
+    const half = Math.floor(siblingCount / 2);
+    let start = Math.max(1, page - half);
+    let 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 goto = (n: number) => {
+    if (n < 1 || n > totalPages || n === page) return;
+    onChange?.(n);
+  };
+
+  const rangeStart = total === 0 ? 0 : (page - 1) * pageSize + 1;
+  const rangeEnd = Math.min(page * pageSize, total);
+
+  const showLeftEllipsis = pages[0]! > 2;
+  const showRightEllipsis = pages[pages.length - 1]! < totalPages - 1;
+
+  return (
+    <div
+      className={cn(
+        'flex w-full flex-wrap items-center justify-between gap-3',
+        className,
+      )}
+    >
+      {showTotal ? (
+        <p className="text-sm text-muted-foreground tabular-nums">
+          {totalRender
+            ? totalRender(total, [rangeStart, rangeEnd])
+            : `共 ${total} 条 · 第 ${rangeStart}-${rangeEnd} 条`}
+        </p>
+      ) : (
+        <span />
+      )}
+      <Pagination className="mx-0 w-auto">
+        <PaginationContent>
+          {showFirstLast ? (
+            <PaginationItem>
+              <PaginationLink
+                aria-label="First"
+                disabled={page === 1}
+                onClick={() => goto(1)}
+              >
+                <ChevronsLeft className="size-4" />
+              </PaginationLink>
+            </PaginationItem>
+          ) : null}
+          <PaginationItem>
+            <PaginationPrevious
+              disabled={page === 1}
+              onClick={() => goto(page - 1)}
+            />
+          </PaginationItem>
+          {pages[0]! > 1 ? (
+            <PaginationItem>
+              <PaginationLink onClick={() => goto(1)}>1</PaginationLink>
+            </PaginationItem>
+          ) : null}
+          {showLeftEllipsis ? (
+            <PaginationItem>
+              <PaginationEllipsis />
+            </PaginationItem>
+          ) : null}
+          {pages.map((p) => (
+            <PaginationItem key={p}>
+              <PaginationLink
+                isActive={p === page}
+                onClick={() => goto(p)}
+              >
+                {p}
+              </PaginationLink>
+            </PaginationItem>
+          ))}
+          {showRightEllipsis ? (
+            <PaginationItem>
+              <PaginationEllipsis />
+            </PaginationItem>
+          ) : null}
+          {pages[pages.length - 1]! < totalPages ? (
+            <PaginationItem>
+              <PaginationLink onClick={() => goto(totalPages)}>
+                {totalPages}
+              </PaginationLink>
+            </PaginationItem>
+          ) : null}
+          <PaginationItem>
+            <PaginationNext
+              disabled={page === totalPages}
+              onClick={() => goto(page + 1)}
+            />
+          </PaginationItem>
+          {showFirstLast ? (
+            <PaginationItem>
+              <PaginationLink
+                aria-label="Last"
+                disabled={page === totalPages}
+                onClick={() => goto(totalPages)}
+              >
+                <ChevronsRight className="size-4" />
+              </PaginationLink>
+            </PaginationItem>
+          ) : null}
+        </PaginationContent>
+      </Pagination>
+    </div>
+  );
+};
+SimplePagination.displayName = 'SimplePagination';
+
+export {
+  Pagination,
+  PaginationContent,
+  PaginationItem,
+  PaginationLink,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
+  SimplePagination,
+};