@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/badge/index.tsx

@@ -0,0 +1,299 @@
+/**
+ * 徽标 Badge
+ *
+ * 用于状态标识、计数提醒或角标指示。单组件支持四种形态：
+ * - **Label**：内联文本徽标（`<Badge>进行中</Badge>`），通过 `variant` 切换底色风格。
+ * - **Wrapped**：包裹目标元素，在右上角浮一个 `count` 数字胶囊或小红点（`<Badge count={5}><Avatar /></Badge>`）。
+ * - **Standalone**：不传 children，单独渲染数字胶囊或小红点（`<Badge count={25} />` / `<Badge dot />`）。
+ * - **Status**：语义状态点 + 文本（`<Badge status="processing">运行中</Badge>`），processing 带脉冲动画。
+ *
+ * 形态自动判定：传入 `status` / `dot` / `count` / `content` 时进入指示器形态，否则为 label。
+ *
+ * @when
+ * - 头像 / 图标 / 链接右上角的未读数 / 新消息红点
+ * - 列表项末尾的状态文本（进行中 / 已完成）
+ * - 任务 / 资源 5 档语义状态点
+ * - 顶栏图标的小红点提醒
+ */
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { Slot } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+// ─── Label cva（与 v1 完全一致，保证向后兼容） ──────────────────────────
+const badgeVariants = cva(
+  'group/badge inline-flex h-5 w-fit shrink-0 items-center justify-center gap-1 overflow-hidden rounded-full border border-transparent px-2 py-0.5 text-xs font-medium whitespace-nowrap transition-all focus-visible:border-ring focus-visible:ring-1 focus-visible:ring-ring has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 aria-invalid:border-destructive aria-invalid:ring-destructive/20 [&>svg]:pointer-events-none [&>svg]:size-3!',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground [a]:hover:bg-primary/80',
+        secondary:
+          'bg-secondary text-secondary-foreground [a]:hover:bg-secondary/80',
+        destructive:
+          'bg-destructive/10 text-destructive focus-visible:ring-destructive/20 [a]:hover:bg-destructive/20',
+        outline:
+          'border-border text-foreground [a]:hover:bg-muted [a]:hover:text-muted-foreground',
+        ghost: 'hover:bg-muted hover:text-muted-foreground',
+        link: 'text-primary',
+      },
+    },
+    defaultVariants: { variant: 'default' },
+  },
+);
+
+// ─── Status 5 档（对齐 antd / cloud-design 语义） ──────────────────────
+export type BadgeStatus =
+  | 'default'
+  | 'processing'
+  | 'success'
+  | 'warning'
+  | 'error';
+
+const STATUS_TOKEN_MAP: Record<BadgeStatus, string> = {
+  default: 'var(--color-muted-foreground)',
+  processing: 'var(--color-primary)',
+  success: 'var(--color-success)',
+  warning: 'var(--color-warning)',
+  error: 'var(--color-destructive)',
+};
+
+// ─── Props ─────────────────────────────────────────────────────────────
+export interface BadgeProps
+  extends Omit<React.ComponentProps<'span'>, 'content'>,
+    VariantProps<typeof badgeVariants> {
+  /** 使用 Slot 模式渲染（仅 label 形态生效） */
+  asChild?: boolean;
+  /** 数字内容；为 0 且 `showZero=false` 时不渲染 indicator */
+  count?: number;
+  /** count 封顶值，超出显示为 `${overflowCount}+`（默认 99） */
+  overflowCount?: number;
+  /** count 为 0 时是否仍显示 indicator（默认 false） */
+  showZero?: boolean;
+  /** 仅显示小红点（不显示数字） */
+  dot?: boolean;
+  /** 状态语义点；与 count / dot 互斥，触发 status 形态 */
+  status?: BadgeStatus;
+  /** 自定义 indicator 颜色（CSS 颜色字面量），覆盖 status / 默认红 */
+  color?: string;
+  /** 自定义 indicator 内容（图标 / 文本），优先级高于 count / dot */
+  content?: React.ReactNode;
+  /** indicator 像素偏移 [x, y]，仅 wrapped 模式生效 */
+  offset?: [number, number];
+  /** indicator 尺寸（默认 default） */
+  size?: 'sm' | 'default';
+}
+
+// ─── 形态分流工具 ──────────────────────────────────────────────────────
+type IndicatorKind = 'status' | 'dot' | 'count' | 'content' | null;
+
+function resolveKind(props: {
+  status?: BadgeStatus;
+  dot?: boolean;
+  count?: number;
+  content?: React.ReactNode;
+}): IndicatorKind {
+  if (props.status) return 'status';
+  if (props.dot) return 'dot';
+  if (props.count != null) return 'count';
+  if (props.content != null) return 'content';
+  return null;
+}
+
+function formatCount(count: number, overflowCount: number): string {
+  return count > overflowCount ? `${overflowCount}+` : String(count);
+}
+
+// ─── Indicator 子节点（wrapped / standalone 共用） ──────────────────────
+interface IndicatorProps {
+  kind: Exclude<IndicatorKind, null | 'status'>;
+  size: 'sm' | 'default';
+  color?: string;
+  content?: React.ReactNode;
+  countText?: string;
+  /** 是否处于 wrapped 模式（影响 ring + 绝对定位） */
+  wrapped: boolean;
+  offset?: [number, number];
+}
+
+function Indicator({
+  kind,
+  size,
+  color,
+  content,
+  countText,
+  wrapped,
+  offset,
+}: IndicatorProps) {
+  const isDot = kind === 'dot';
+  const isContent = kind === 'content';
+
+  const style: React.CSSProperties = {};
+  if (color) style.backgroundColor = color;
+  if (wrapped && offset) {
+    const [x, y] = offset;
+    style.transform = `translate(calc(50% + ${x}px), calc(-50% + ${y}px))`;
+  }
+  // content 形态：让用户完全自定义底色（透明 / 自定义），不强制 destructive
+  if (isContent && !color) style.backgroundColor = 'transparent';
+
+  return (
+    <span
+      data-slot="badge-indicator"
+      data-indicator-kind={kind}
+      data-size={size}
+      className={cn(
+        'pointer-events-none inline-flex items-center justify-center rounded-full font-medium leading-none select-none',
+        // 默认色（content 形态走透明，由 color / 自定义 className 决定）
+        !isContent && 'bg-destructive text-destructive-foreground',
+        // content 形态 + 有色非透明底 → 白色文字
+        isContent &&
+          color &&
+          color !== 'transparent' &&
+          'text-destructive-foreground',
+        // 尺寸
+        isDot
+          ? size === 'sm'
+            ? 'size-1.5'
+            : 'size-2'
+          : size === 'sm'
+          ? 'h-3.5 min-w-3.5 px-1 text-xs'
+          : 'h-4 min-w-4 px-1 text-xs',
+        // wrapped 模式：绝对定位 + ring 描边
+        wrapped &&
+          'absolute top-0 right-0 z-10 origin-center -translate-y-1/2 translate-x-1/2 ring-2 ring-background',
+      )}
+      style={style}
+    >
+      {isContent ? content : isDot ? null : countText}
+    </span>
+  );
+}
+
+// ─── 主组件 ────────────────────────────────────────────────────────────
+function Badge({
+  className,
+  variant = 'default',
+  asChild = false,
+  count,
+  overflowCount = 99,
+  showZero = false,
+  dot,
+  status,
+  color,
+  content,
+  offset,
+  size = 'default',
+  children,
+  ...props
+}: BadgeProps) {
+  const kind = resolveKind({ status, dot, count, content });
+
+  // ─── 1. Label 模式（向后兼容） ──────────────────────────────────────
+  if (kind === null) {
+    const Comp = asChild ? Slot.Root : 'span';
+    return (
+      <Comp
+        data-slot="badge"
+        data-mode="label"
+        data-variant={variant}
+        data-size={size}
+        className={cn(badgeVariants({ variant }), className)}
+        {...props}
+      >
+        {children}
+      </Comp>
+    );
+  }
+
+  // ─── 2. Status 模式：内联 [dot] [text] ─────────────────────────────
+  if (kind === 'status') {
+    const dotColor = color ?? STATUS_TOKEN_MAP[status!];
+    return (
+      <span
+        data-slot="badge"
+        data-mode="status"
+        data-status={status}
+        data-size={size}
+        className={cn(
+          'inline-flex items-center gap-1.5 text-xs whitespace-nowrap',
+          className,
+        )}
+        {...props}
+      >
+        <span
+          data-slot="badge-indicator"
+          data-indicator-kind="status"
+          className={cn(
+            'relative inline-flex shrink-0 rounded-full',
+            size === 'sm' ? 'size-1.5' : 'size-2',
+          )}
+        >
+          {status === 'processing' && (
+            <span
+              aria-hidden
+              className="absolute inset-0 inline-flex animate-ping rounded-full opacity-75"
+              style={{ backgroundColor: dotColor }}
+            />
+          )}
+          <span
+            aria-hidden
+            className="relative inline-flex size-full rounded-full"
+            style={{ backgroundColor: dotColor }}
+          />
+        </span>
+        {children}
+      </span>
+    );
+  }
+
+  // ─── 3. Count / Dot / Content 形态（wrapped 或 standalone） ────────
+  // count = 0 且 showZero=false → 不渲染 indicator
+  const hideZero = kind === 'count' && (count ?? 0) === 0 && !showZero;
+  const countText =
+    kind === 'count' ? formatCount(count ?? 0, overflowCount) : undefined;
+
+  const hasChildren = React.Children.count(children) > 0;
+
+  // 3a. Wrapped 模式（有 children）
+  if (hasChildren) {
+    return (
+      <span
+        data-slot="badge"
+        data-mode="wrapped"
+        data-size={size}
+        className={cn('relative inline-flex', className)}
+        {...props}
+      >
+        {children}
+        {!hideZero && (
+          <Indicator
+            kind={kind}
+            size={size}
+            color={color}
+            content={content}
+            countText={countText}
+            wrapped
+            offset={offset}
+          />
+        )}
+      </span>
+    );
+  }
+
+  // 3b. Standalone 模式（无 children）
+  if (hideZero) return null;
+  return (
+    <Indicator
+      kind={kind}
+      size={size}
+      color={color}
+      content={content}
+      countText={countText}
+      wrapped={false}
+    />
+  );
+}
+
+export { Badge, badgeVariants };

package/src/components/badge/meta.md

@@ -0,0 +1,237 @@
+# Badge
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+徽标 Badge
+用于状态标识、计数提醒或角标指示。单组件支持四种形态：
+- **Label**：内联文本徽标（`<Badge>进行中</Badge>`），通过 `variant` 切换底色风格。
+- **Wrapped**：包裹目标元素，在右上角浮一个 `count` 数字胶囊或小红点（`<Badge count={5}><Avatar /></Badge>`）。
+- **Standalone**：不传 children，单独渲染数字胶囊或小红点（`<Badge count={25} />` / `<Badge dot />`）。
+- **Status**：语义状态点 + 文本（`<Badge status="processing">运行中</Badge>`），processing 带脉冲动画。
+形态自动判定：传入 `status` / `dot` / `count` / `content` 时进入指示器形态，否则为 label。
+
+## 使用场景
+
+- 头像 / 图标 / 链接右上角的未读数 / 新消息红点
+- 列表项末尾的状态文本（进行中 / 已完成）
+- 任务 / 资源 5 档语义状态点
+- 顶栏图标的小红点提醒
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `variant` | `"default" \| "secondary" \| "destructive" \| "outline" \| "ghost" \| "link"` | `"default"` | – | – |
+| `asChild` | `boolean` | – | – | 使用 Slot 模式渲染（仅 label 形态生效） |
+| `count` | `number` | – | – | 数字内容；为 0 且 `showZero=false` 时不渲染 indicator |
+| `overflowCount` | `number` | – | – | count 封顶值，超出显示为 `${overflowCount}+`（默认 99） |
+| `showZero` | `boolean` | – | – | count 为 0 时是否仍显示 indicator（默认 false） |
+| `dot` | `boolean` | – | – | 仅显示小红点（不显示数字） |
+| `status` | `BadgeStatus` | – | – | 状态语义点；与 count / dot 互斥，触发 status 形态 |
+| `color` | `string` | – | – | 自定义 indicator 颜色（CSS 颜色字面量），覆盖 status / 默认红 |
+| `content` | `React.ReactNode` | – | – | 自定义 indicator 内容（图标 / 文本），优先级高于 count / dot |
+| `offset` | `[number, number]` | – | – | indicator 像素偏移 [x, y]，仅 wrapped 模式生效 |
+| `size` | `'sm' \| 'default'` | – | – | indicator 尺寸（默认 default） |
+
+## 示例
+
+### Variants
+
+所有 label 变体。
+
+```tsx
+<div className="flex flex-wrap items-center gap-2">
+  <Badge variant="default">Default</Badge>
+  <Badge variant="secondary">Secondary</Badge>
+  <Badge variant="destructive">Destructive</Badge>
+  <Badge variant="outline">Outline</Badge>
+  <Badge variant="ghost">Ghost</Badge>
+  <Badge variant="link">Link</Badge>
+</div>
+```
+
+### Basic
+
+基本：包裹元素后右上角浮一个数字胶囊。
+
+```tsx
+<div className="flex items-center gap-6">
+  <Badge count={5}>
+    <Avatar>
+      <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+      <AvatarFallback>SC</AvatarFallback>
+    </Avatar>
+  </Badge>
+  <Badge count={0} showZero>
+    <Avatar>
+      <AvatarFallback>SZ</AvatarFallback>
+    </Avatar>
+  </Badge>
+</div>
+```
+
+### Dot
+
+小红点：仅展示一个红点提示，不显示数字。
+
+```tsx
+<div className="flex items-center gap-6">
+  <Badge dot>
+    <Button variant="ghost" size="icon" aria-label="messages">
+      <MailIcon />
+    </Button>
+  </Badge>
+  <Badge dot>
+    <Button variant="ghost" size="icon" aria-label="notifications">
+      <BellIcon />
+    </Button>
+  </Badge>
+  <Badge dot>
+    <a href="#">A Link</a>
+  </Badge>
+</div>
+```
+
+### OverflowCount
+
+封顶数字：超过 `overflowCount` 显示为 `${overflowCount}+`。
+
+```tsx
+<div className="flex items-center gap-6">
+  <Badge count={99}>
+    <Avatar>
+      <AvatarFallback>99</AvatarFallback>
+    </Avatar>
+  </Badge>
+  <Badge count={100}>
+    <Avatar>
+      <AvatarFallback>A</AvatarFallback>
+    </Avatar>
+  </Badge>
+  <Badge count={100} overflowCount={10}>
+    <Avatar>
+      <AvatarFallback>B</AvatarFallback>
+    </Avatar>
+  </Badge>
+  <Badge count={1000} overflowCount={999}>
+    <Avatar>
+      <AvatarFallback>C</AvatarFallback>
+    </Avatar>
+  </Badge>
+</div>
+```
+
+### Standalone
+
+独立使用：不传 children，单独渲染数字 / 红点 / 自定义内容。
+
+```tsx
+<div className="flex flex-wrap items-center gap-3">
+  <Badge count={25} />
+  <Badge count={109} color="var(--color-success)" />
+  <Badge dot />
+  <Badge content="hot" color="var(--color-destructive)" />
+</div>
+```
+
+### CustomContent
+
+自定义内容：通过 `content` 注入文本或图标，`color` 覆盖底色。
+
+```tsx
+<div className="flex items-center gap-6">
+  <Badge content="hot" color="var(--color-destructive)">
+    <Avatar>
+      <AvatarFallback>H</AvatarFallback>
+    </Avatar>
+  </Badge>
+  <Badge content={<BellIcon className="size-3" />} color="transparent">
+    <Avatar>
+      <AvatarFallback>B</AvatarFallback>
+    </Avatar>
+  </Badge>
+</div>
+```
+
+### Clickable
+
+整个徽标 + 目标元素均可点击，外层 `<a>` 包裹 Badge。
+
+```tsx
+<a href="#" className="inline-block">
+  <Badge count={5}>
+    <Avatar>
+      <AvatarFallback>L</AvatarFallback>
+    </Avatar>
+  </Badge>
+</a>
+```
+
+### Status
+
+状态点：5 档语义色 + 文本，processing 带脉冲动画。
+
+```tsx
+<div className="flex flex-col gap-2">
+  <Badge status="default">Default</Badge>
+  <Badge status="processing">Processing</Badge>
+  <Badge status="success">Success</Badge>
+  <Badge status="warning">Warning</Badge>
+  <Badge status="error">Error</Badge>
+</div>
+```
+
+### Size
+
+尺寸：sm 与 default 对比。
+
+```tsx
+<div className="flex items-center gap-8">
+  <Badge size="sm" count={5}>
+    <Avatar>
+      <AvatarFallback>S</AvatarFallback>
+    </Avatar>
+  </Badge>
+  <Badge count={5}>
+    <Avatar>
+      <AvatarFallback>D</AvatarFallback>
+    </Avatar>
+  </Badge>
+  <Badge size="sm" dot>
+    <Avatar>
+      <AvatarFallback>S</AvatarFallback>
+    </Avatar>
+  </Badge>
+  <Badge dot>
+    <Avatar>
+      <AvatarFallback>D</AvatarFallback>
+    </Avatar>
+  </Badge>
+</div>
+```
+
+### Offset
+
+偏移：通过 `offset=[x, y]` 微调 indicator 位置。
+
+```tsx
+<div className="flex items-center gap-8">
+  <Badge count={5}>
+    <Avatar>
+      <AvatarFallback>0</AvatarFallback>
+    </Avatar>
+  </Badge>
+  <Badge count={5} offset={[-4, 4]}>
+    <Avatar>
+      <AvatarFallback>L</AvatarFallback>
+    </Avatar>
+  </Badge>
+  <Badge count={5} offset={[4, -4]}>
+    <Avatar>
+      <AvatarFallback>R</AvatarFallback>
+    </Avatar>
+  </Badge>
+</div>
+```