@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/icon/index.tsx

@@ -0,0 +1,225 @@
+/**
+ * 面性状态图标集合 Icon
+ *
+ * 9 档语义状态的面性 SVG 图标。外圈以 `fill="currentColor"` 描色，由上层
+ * 包裹元素的 `text-{tone}` 控制颜色；内部字符固定白色（`fill-white` /
+ * `stroke-white`），与各家面性反馈图标的视觉惯例一致。
+ *
+ * @when
+ * - Alert / Tag / Notification / Toast 等反馈组件需要状态语义图标时
+ * - 与 lucide stroke 图标语义对应不上的面性反馈场景（lucide 不提供面性版）
+ *
+ * 9 档：
+ * - 5 大反馈语义：success / warning / error / info / help
+ * - 4 个动态/中性：processing / pause / mention / default
+ * - **不含 loading**（请直接用 `lucide-react` 的 `Loader2` + `animate-spin`，
+ *   面性 loading 视觉辨识度低）
+ *
+ * 颜色绑定：
+ * ```tsx
+ * <span className="text-success"><SuccessFilledIcon /></span>
+ * ```
+ *
+ * 尺寸：默认 `size-5`（20px），通过 `className` 覆盖（如 `size-3.5` / `size-4`）。
+ * viewBox 采用 `-1 -1 22 22`，使图形在容器内自带 1px 内边距留白。
+ */
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+
+type FilledIconProps = React.ComponentProps<'svg'>;
+
+function BaseFilledIcon({
+  className,
+  children,
+  ...props
+}: FilledIconProps & { children: React.ReactNode }) {
+  return (
+    <svg
+      data-slot="icon"
+      viewBox="-1 -1 22 22"
+      aria-hidden="true"
+      className={cn('size-5 shrink-0', className)}
+      {...props}
+    >
+      {children}
+    </svg>
+  );
+}
+
+/** 成功 — 实心圆 + 对号 */
+export function SuccessFilledIcon(props: FilledIconProps) {
+  return (
+    <BaseFilledIcon {...props}>
+      <circle cx="10" cy="10" r="10" fill="currentColor" />
+      <path
+        d="m6 10 2.7 2.7L14 7.5"
+        className="stroke-white"
+        strokeWidth="1.5"
+        fill="none"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </BaseFilledIcon>
+  );
+}
+
+/** 警告 — 实心三角 + 感叹号 */
+export function WarningFilledIcon(props: FilledIconProps) {
+  return (
+    <BaseFilledIcon {...props}>
+      <path
+        d="M11.51 2.5a1.74 1.74 0 0 0-3.02 0L1.09 15.35A1.74 1.74 0 0 0 2.6 17.95h14.8a1.74 1.74 0 0 0 1.51-2.6L11.51 2.5Z"
+        fill="currentColor"
+      />
+      <rect
+        x="9.2"
+        y="7"
+        width="1.6"
+        height="5.5"
+        rx="0.8"
+        className="fill-white"
+      />
+      <circle cx="10" cy="14.6" r="0.9" className="fill-white" />
+    </BaseFilledIcon>
+  );
+}
+
+/** 错误 — 实心圆 + ×（语义对应 Alert.destructive / Tag.error） */
+export function ErrorFilledIcon(props: FilledIconProps) {
+  return (
+    <BaseFilledIcon {...props}>
+      <circle cx="10" cy="10" r="10" fill="currentColor" />
+      <path
+        d="m6.5 6.5 7 7m0-7-7 7"
+        className="stroke-white"
+        strokeWidth="1.5"
+        strokeLinecap="round"
+      />
+    </BaseFilledIcon>
+  );
+}
+
+/** 信息 — 实心圆 + i */
+export function InfoFilledIcon(props: FilledIconProps) {
+  return (
+    <BaseFilledIcon {...props}>
+      <circle cx="10" cy="10" r="10" fill="currentColor" />
+      <circle cx="10" cy="6" r="0.9" className="fill-white" />
+      <rect
+        x="9.2"
+        y="8.5"
+        width="1.6"
+        height="6.6"
+        rx="0.8"
+        className="fill-white"
+      />
+    </BaseFilledIcon>
+  );
+}
+
+/** 帮助 — 实心圆 + ? */
+export function HelpFilledIcon(props: FilledIconProps) {
+  return (
+    <BaseFilledIcon {...props}>
+      <circle cx="10" cy="10" r="10" fill="currentColor" />
+      <path
+        d="M8.1 7.6a1.9 1.9 0 1 1 2.65 1.75c-.5.22-.75.6-.75 1.05v.6"
+        className="stroke-white"
+        strokeWidth="1.3"
+        strokeLinecap="round"
+        fill="none"
+      />
+      <circle cx="10" cy="14.3" r="0.85" className="fill-white" />
+    </BaseFilledIcon>
+  );
+}
+
+/** 进行中 — 实心圆 + 播放三角（建议外层加 animate-pulse） */
+export function ProcessingFilledIcon(props: FilledIconProps) {
+  return (
+    <BaseFilledIcon {...props}>
+      <circle cx="10" cy="10" r="10" fill="currentColor" />
+      <path d="M8.2 6 14.2 10 8.2 14 Z" className="fill-white" />
+    </BaseFilledIcon>
+  );
+}
+
+/** 暂停 — 实心圆 + 双竖线 */
+export function PauseFilledIcon(props: FilledIconProps) {
+  return (
+    <BaseFilledIcon {...props}>
+      <circle cx="10" cy="10" r="10" fill="currentColor" />
+      <rect
+        x="7.4"
+        y="6.5"
+        width="1.6"
+        height="7"
+        rx="0.5"
+        className="fill-white"
+      />
+      <rect
+        x="11"
+        y="6.5"
+        width="1.6"
+        height="7"
+        rx="0.5"
+        className="fill-white"
+      />
+    </BaseFilledIcon>
+  );
+}
+
+/** 提及 — 实心圆 + 对话气泡（语义对齐 antd MessageCircle） */
+export function MentionFilledIcon(props: FilledIconProps) {
+  return (
+    <BaseFilledIcon {...props}>
+      <circle cx="10" cy="10" r="10" fill="currentColor" />
+      <path
+        d="M5.5 8.2 A2.7 2.7 0 0 1 8.2 5.5 H11.8 A2.7 2.7 0 0 1 14.5 8.2 V11 A2.7 2.7 0 0 1 11.8 13.7 H10 L7.5 15.2 V13.7 A2.7 2.7 0 0 1 5.5 11 Z"
+        className="fill-white"
+      />
+      <circle cx="8" cy="9.6" r="0.7" fill="currentColor" />
+      <circle cx="10" cy="9.6" r="0.7" fill="currentColor" />
+      <circle cx="12" cy="9.6" r="0.7" fill="currentColor" />
+    </BaseFilledIcon>
+  );
+}
+
+/** 默认 — 实心圆 + 中心白点（中性指示灯样） */
+export function DefaultFilledIcon(props: FilledIconProps) {
+  return (
+    <BaseFilledIcon {...props}>
+      <circle cx="10" cy="10" r="10" fill="currentColor" />
+      <circle cx="10" cy="10" r="2.2" className="fill-white" />
+    </BaseFilledIcon>
+  );
+}
+
+/** 9 档面性状态图标的语义键 */
+export type FilledIconStatus =
+  | 'success'
+  | 'warning'
+  | 'error'
+  | 'info'
+  | 'help'
+  | 'processing'
+  | 'pause'
+  | 'mention'
+  | 'default';
+
+/** 语义键 → 组件映射，便于消费方按 status 切换 */
+export const FILLED_STATUS_ICON_MAP: Record<
+  FilledIconStatus,
+  React.ComponentType<FilledIconProps>
+> = {
+  success: SuccessFilledIcon,
+  warning: WarningFilledIcon,
+  error: ErrorFilledIcon,
+  info: InfoFilledIcon,
+  help: HelpFilledIcon,
+  processing: ProcessingFilledIcon,
+  pause: PauseFilledIcon,
+  mention: MentionFilledIcon,
+  default: DefaultFilledIcon,
+};

package/src/components/icon/meta.md

@@ -0,0 +1,102 @@
+# Icon
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+面性状态图标集合 Icon
+9 档语义状态的面性 SVG 图标。外圈以 `fill="currentColor"` 描色，由上层
+包裹元素的 `text-{tone}` 控制颜色；内部字符固定白色（`fill-white` /
+`stroke-white`），与各家面性反馈图标的视觉惯例一致。
+
+## 使用场景
+
+- Alert / Tag / Notification / Toast 等反馈组件需要状态语义图标时
+- 与 lucide stroke 图标语义对应不上的面性反馈场景（lucide 不提供面性版）
+- 9 档：
+- 5 大反馈语义：success / warning / error / info / help
+- 4 个动态/中性：processing / pause / mention / default
+- **不含 loading**（请直接用 `lucide-react` 的 `Loader2` + `animate-spin`，
+- 面性 loading 视觉辨识度低）
+- 颜色绑定：
+- ```tsx
+- <span className="text-success"><SuccessFilledIcon /></span>
+- ```
+- 尺寸：默认 `size-5`（20px），通过 `className` 覆盖（如 `size-3.5` / `size-4`）。
+- viewBox 采用 `-1 -1 22 22`，使图形在容器内自带 1px 内边距留白。
+
+## 示例
+
+### Gallery
+
+9 档面性图标总览。
+
+```tsx
+<div className="grid grid-cols-3 gap-4">
+  {SWATCHES.map(({ status, toneClass, label }) => {
+    const Icon = FILLED_STATUS_ICON_MAP[status];
+    return (
+      <div
+        key={status}
+        className="flex items-center gap-2 rounded-md border border-border p-3"
+      >
+        <span className={toneClass}>
+          <Icon />
+        </span>
+        <span className="text-sm font-medium text-foreground">{label}</span>
+      </div>
+    );
+  })}
+</div>
+```
+
+### SingleIcons
+
+默认尺寸 size-5（20px），通过外层 `text-{tone}` 切换颜色。
+
+```tsx
+<div className="flex items-center gap-3">
+  <span className="text-success">
+    <SuccessFilledIcon />
+  </span>
+  <span className="text-warning">
+    <WarningFilledIcon />
+  </span>
+  <span className="text-destructive">
+    <ErrorFilledIcon />
+  </span>
+  <span className="text-info">
+    <InfoFilledIcon />
+  </span>
+  <span className="text-help">
+    <HelpFilledIcon />
+  </span>
+  <span className="text-primary">
+    <ProcessingFilledIcon />
+  </span>
+  <span className="text-muted-foreground">
+    <PauseFilledIcon />
+  </span>
+  <span className="text-primary">
+    <MentionFilledIcon />
+  </span>
+  <span className="text-muted-foreground">
+    <DefaultFilledIcon />
+  </span>
+</div>
+```
+
+### Sizes
+
+通过 `className` 覆盖默认 size-5。
+
+```tsx
+<div className="flex items-center gap-3 text-success">
+  <SuccessFilledIcon className="size-3" />
+  <SuccessFilledIcon className="size-3.5" />
+  <SuccessFilledIcon className="size-4" />
+  <SuccessFilledIcon />
+  <SuccessFilledIcon className="size-6" />
+  <SuccessFilledIcon className="size-8" />
+</div>
+```

package/src/components/icon/stories.tsx

@@ -0,0 +1,127 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import * as React from 'react';
+
+import {
+  DefaultFilledIcon,
+  ErrorFilledIcon,
+  FILLED_STATUS_ICON_MAP,
+  HelpFilledIcon,
+  InfoFilledIcon,
+  MentionFilledIcon,
+  PauseFilledIcon,
+  ProcessingFilledIcon,
+  SuccessFilledIcon,
+  WarningFilledIcon,
+  type FilledIconStatus,
+} from './index';
+
+const meta: Meta = {
+  title: '工具 · Utilities/Icon 面性状态图标',
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '9 档面性状态图标。外圈以 `currentColor` 着色，由上层 `text-{tone}` 决定颜色；内部字符固定白色。供 Alert / Tag / Notification / Toast 等反馈组件复用，与 lucide stroke 图标语义对应不上的面性场景使用。不含 loading（请用 `Loader2` + `animate-spin`）。',
+      },
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj;
+
+// ─── 9 档总览（按对应语义 token 着色） ─────────────────────────────────
+
+interface SwatchItem {
+  status: FilledIconStatus;
+  toneClass: string;
+  label: string;
+}
+
+const SWATCHES: SwatchItem[] = [
+  { status: 'success', toneClass: 'text-success', label: 'success' },
+  { status: 'warning', toneClass: 'text-warning', label: 'warning' },
+  { status: 'error', toneClass: 'text-destructive', label: 'error' },
+  { status: 'info', toneClass: 'text-info', label: 'info' },
+  { status: 'help', toneClass: 'text-help', label: 'help' },
+  { status: 'processing', toneClass: 'text-primary', label: 'processing' },
+  { status: 'pause', toneClass: 'text-muted-foreground', label: 'pause' },
+  { status: 'mention', toneClass: 'text-primary', label: 'mention' },
+  { status: 'default', toneClass: 'text-muted-foreground', label: 'default' },
+];
+
+/** 9 档面性图标总览。 */
+export const Gallery: Story = {
+  render: () => (
+    <div className="grid grid-cols-3 gap-4">
+      {SWATCHES.map(({ status, toneClass, label }) => {
+        const Icon = FILLED_STATUS_ICON_MAP[status];
+        return (
+          <div
+            key={status}
+            className="flex items-center gap-2 rounded-md border border-border p-3"
+          >
+            <span className={toneClass}>
+              <Icon />
+            </span>
+            <span className="text-sm font-medium text-foreground">{label}</span>
+          </div>
+        );
+      })}
+    </div>
+  ),
+};
+
+// ─── 单个图标使用示例 ─────────────────────────────────────────────────
+
+/** 默认尺寸 size-5（20px），通过外层 `text-{tone}` 切换颜色。 */
+export const SingleIcons: Story = {
+  render: () => (
+    <div className="flex items-center gap-3">
+      <span className="text-success">
+        <SuccessFilledIcon />
+      </span>
+      <span className="text-warning">
+        <WarningFilledIcon />
+      </span>
+      <span className="text-destructive">
+        <ErrorFilledIcon />
+      </span>
+      <span className="text-info">
+        <InfoFilledIcon />
+      </span>
+      <span className="text-help">
+        <HelpFilledIcon />
+      </span>
+      <span className="text-primary">
+        <ProcessingFilledIcon />
+      </span>
+      <span className="text-muted-foreground">
+        <PauseFilledIcon />
+      </span>
+      <span className="text-primary">
+        <MentionFilledIcon />
+      </span>
+      <span className="text-muted-foreground">
+        <DefaultFilledIcon />
+      </span>
+    </div>
+  ),
+};
+
+// ─── 不同尺寸 ─────────────────────────────────────────────────────────
+
+/** 通过 `className` 覆盖默认 size-5。 */
+export const Sizes: Story = {
+  render: () => (
+    <div className="flex items-center gap-3 text-success">
+      <SuccessFilledIcon className="size-3" />
+      <SuccessFilledIcon className="size-3.5" />
+      <SuccessFilledIcon className="size-4" />
+      <SuccessFilledIcon />
+      <SuccessFilledIcon className="size-6" />
+      <SuccessFilledIcon className="size-8" />
+    </div>
+  ),
+};

package/src/components/image/index.tsx

@@ -0,0 +1,147 @@
+/**
+ * 图片 Image
+ *
+ * 带加载占位、错误兜底和点击预览的增强图片组件。
+ *
+ * @when
+ * - 需要展示外部图片并处理加载/失败状态
+ * - 需要点击放大预览原图
+ * - 需要为图片提供统一的加载骨架占位
+ */
+'use client';
+
+/* eslint-disable teamix-evo/no-arbitrary-tw-value -- Image needs rounded-[inherit] and viewport-relative sizing for preview */
+
+import * as React from 'react';
+import { ImageOff, XIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import {
+  Dialog,
+  DialogContent,
+  DialogTitle,
+  DialogTrigger,
+} from '@/components/dialog';
+import { Skeleton } from '@/components/skeleton';
+
+export interface ImageProps
+  extends Omit<React.ComponentProps<'img'>, 'src' | 'placeholder'> {
+  /** 图片地址 */
+  src: string;
+  /** 无障碍替代文本 */
+  alt: string;
+  /**
+   * 是否启用点击预览（模态展示原图）
+   * @default true
+   */
+  preview?: boolean;
+  /** 加载失败时的占位元素，不传则用默认图标 */
+  fallback?: React.ReactNode;
+  /** 加载中的占位元素，不传则用 Skeleton */
+  placeholder?: React.ReactNode;
+  /** 容器 className */
+  className?: string;
+  /** img 元素的 className（控制尺寸/圆角/object-fit） */
+  imgClassName?: string;
+}
+
+function Image({
+  src,
+  alt,
+  preview = true,
+  fallback,
+  placeholder,
+  className,
+  imgClassName,
+  onLoad,
+  onError,
+  ...props
+}: ImageProps) {
+  const [status, setStatus] = React.useState<'loading' | 'loaded' | 'error'>(
+    'loading',
+  );
+
+  const img = (
+    <img
+      data-slot="image-img"
+      src={src}
+      alt={alt}
+      onLoad={(e) => {
+        setStatus('loaded');
+        onLoad?.(e);
+      }}
+      onError={(e) => {
+        setStatus('error');
+        onError?.(e);
+      }}
+      className={cn(
+        'block transition-opacity',
+        status !== 'loaded' && 'opacity-0',
+        imgClassName,
+      )}
+      {...props}
+    />
+  );
+
+  const overlay = (
+    <>
+      {status === 'loading' && (
+        <div className="absolute inset-0">
+          {placeholder ?? <Skeleton className="size-full rounded-[inherit]" />}
+        </div>
+      )}
+      {status === 'error' && (
+        <div className="absolute inset-0 flex flex-col items-center justify-center gap-1 rounded-[inherit] bg-muted text-muted-foreground">
+          {fallback ?? (
+            <>
+              <ImageOff className="size-6" />
+              <span className="text-xs">加载失败</span>
+            </>
+          )}
+        </div>
+      )}
+    </>
+  );
+
+  const inner = (
+    <span
+      data-slot="image"
+      className={cn(
+        'relative inline-block overflow-hidden',
+        preview &&
+          status === 'loaded' &&
+          'cursor-zoom-in transition-opacity hover:opacity-90',
+        className,
+      )}
+    >
+      {img}
+      {overlay}
+    </span>
+  );
+
+  if (!preview || status !== 'loaded') return inner;
+
+  return (
+    <Dialog>
+      <DialogTrigger asChild>{inner}</DialogTrigger>
+      <DialogContent
+        className="max-w-[90vw] border-0 bg-transparent p-0 shadow-none sm:max-w-[90vw]"
+        showCloseButton={false}
+      >
+        <DialogTitle className="sr-only">{alt}</DialogTitle>
+        <div className="relative">
+          <img
+            src={src}
+            alt={alt}
+            className="max-h-[85vh] w-auto rounded-md object-contain"
+          />
+          <div className="pointer-events-none absolute -top-3 -right-3 flex size-8 items-center justify-center rounded-full bg-background text-foreground shadow">
+            <XIcon className="size-4" />
+          </div>
+        </div>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+export { Image };

package/src/components/image/meta.md

@@ -0,0 +1,55 @@
+# Image
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+图片 Image
+带加载占位、错误兜底和点击预览的增强图片组件。
+
+## 使用场景
+
+- 需要展示外部图片并处理加载/失败状态
+- 需要点击放大预览原图
+- 需要为图片提供统一的加载骨架占位
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `src` | `string` | – | ✓ | 图片地址 |
+| `alt` | `string` | – | ✓ | 无障碍替代文本 |
+| `preview` | `boolean` | `true` | – | 是否启用点击预览（模态展示原图） |
+| `fallback` | `React.ReactNode` | – | – | 加载失败时的占位元素，不传则用默认图标 |
+| `placeholder` | `React.ReactNode` | – | – | 加载中的占位元素，不传则用 Skeleton |
+| `className` | `string` | – | – | 容器 className |
+| `imgClassName` | `string` | – | – | img 元素的 className（控制尺寸/圆角/object-fit） |
+
+## 示例
+
+### NoPreview
+
+关闭预览功能的纯展示图片。
+
+```tsx
+<Image
+  src="https://placehold.co/120x120/e5e7eb/6b7280?text=Avatar"
+  alt="头像"
+  preview={false}
+  className="rounded-full"
+  imgClassName="size-12 object-cover rounded-full"
+/>
+```
+
+### ErrorState
+
+图片加载失败时的兜底状态。
+
+```tsx
+<Image
+  src="https://this-domain-does-not-exist.example/x.jpg"
+  alt="加载失败示例"
+  className="rounded-md"
+  imgClassName="size-48 object-cover"
+/>
+```

package/src/components/image/stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Image } from './index';
+
+const meta: Meta<typeof Image> = {
+  title: '数据展示 · Data Display/Image 图片',
+  component: Image,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 默认带预览功能的图片，点击可放大查看。 */
+export const Default: Story = {
+  render: () => (
+    <Image
+      src="https://placehold.co/640x360/e5e7eb/6b7280?text=Cover"
+      alt="封面"
+      className="rounded-md"
+      imgClassName="w-64 object-cover"
+    />
+  ),
+};
+
+/** 关闭预览功能的纯展示图片。 */
+export const NoPreview: Story = {
+  render: () => (
+    <Image
+      src="https://placehold.co/120x120/e5e7eb/6b7280?text=Avatar"
+      alt="头像"
+      preview={false}
+      className="rounded-full"
+      imgClassName="size-12 object-cover rounded-full"
+    />
+  ),
+};
+
+/** 图片加载失败时的兜底状态。 */
+export const ErrorState: Story = {
+  render: () => (
+    <Image
+      src="https://this-domain-does-not-exist.example/x.jpg"
+      alt="加载失败示例"
+      className="rounded-md"
+      imgClassName="size-48 object-cover"
+    />
+  ),
+};