@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/empty/index.tsx

@@ -0,0 +1,431 @@
+/**
+ * 空状态 / 结果页 Empty
+ *
+ * 用于无数据、错误页、操作结果等占位反馈,既支持复合组件组装,也支持 status 预设一行写完。
+ *
+ * @when
+ * - 列表 / 表格无数据
+ * - 搜索无结果或筛选无匹配
+ * - 异常页面:403 / 404 / 500 / 网络错误 / 浏览器不兼容
+ * - 操作结果反馈:创建成功 / 失败、导入数据等
+ * - 初始引导态,提示用户进行下一步操作
+ *
+ * 组合结构:Empty > EmptyMedia + EmptyHeader (EmptyTitle + EmptyDescription) + EmptyContent
+ */
+
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import {
+  AlertTriangleIcon,
+  CheckCircle2Icon,
+  FileQuestionIcon,
+  InboxIcon,
+  InfoIcon,
+  MonitorXIcon,
+  SearchXIcon,
+  ServerCrashIcon,
+  ShieldOffIcon,
+  UploadIcon,
+  WifiOffIcon,
+  XCircleIcon,
+  type LucideIcon,
+} from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+
+/* -------------------------------------------------------------------------------------------------
+ * Variants
+ * -----------------------------------------------------------------------------------------------*/
+
+const emptyVariants = cva(
+  'group/empty flex w-full min-w-0 flex-1 items-center justify-center text-balance',
+  {
+    variants: {
+      layout: {
+        vertical: 'flex-col text-center',
+        horizontal: 'flex-row text-left min-h-80',
+      },
+      size: {
+        sm: 'p-4',
+        default: 'p-6',
+        lg: 'p-8',
+      },
+      bordered: {
+        true: 'rounded-xl border border-dashed border-border',
+        false: '',
+      },
+    },
+    compoundVariants: [
+      // 竖向 — media / header / content 堆叠间距
+      { layout: 'vertical', size: 'sm', class: 'gap-2' },
+      { layout: 'vertical', size: 'default', class: 'gap-3' },
+      { layout: 'vertical', size: 'lg', class: 'gap-4' },
+      // 横向 — 左 img 与右侧文本列之间间距（lg = 40px 对齐 cloud-design Result spec）
+      { layout: 'horizontal', size: 'sm', class: 'gap-6' },
+      { layout: 'horizontal', size: 'default', class: 'gap-8' },
+      { layout: 'horizontal', size: 'lg', class: 'gap-10' },
+    ],
+    defaultVariants: {
+      layout: 'vertical',
+      size: 'default',
+      bordered: false,
+    },
+  },
+);
+
+/* -------------------------------------------------------------------------------------------------
+ * Status presets
+ * -----------------------------------------------------------------------------------------------*/
+
+/** 内置语义状态枚举(覆盖 cloud-design Result 全量 + antd Result 通用补充) */
+export type EmptyStatus =
+  | '403'
+  | '404'
+  | '500'
+  | 'noData'
+  | 'noSearch'
+  | 'noNetwork'
+  | 'browserError'
+  | 'createSuccess'
+  | 'createError'
+  | 'import'
+  | 'success'
+  | 'error'
+  | 'info'
+  | 'warning';
+
+type EmptyTone = 'neutral' | 'success' | 'destructive' | 'warning' | 'info';
+
+interface StatusPreset {
+  icon: LucideIcon;
+  title?: string;
+  description?: string;
+  tone: EmptyTone;
+}
+
+const STATUS_PRESETS: Record<EmptyStatus, StatusPreset> = {
+  '403': {
+    icon: ShieldOffIcon,
+    title: '抱歉，您没有访问权限',
+    description: '您可以检查所访问的页面域名,或者返回上一级',
+    tone: 'neutral',
+  },
+  '404': {
+    icon: FileQuestionIcon,
+    title: '抱歉，您访问的页面不存在',
+    description: '您可以检查所访问的页面域名,或者返回上一级',
+    tone: 'neutral',
+  },
+  '500': {
+    icon: ServerCrashIcon,
+    title: '抱歉，服务器出错了',
+    description: '我们正在尽快修复,请稍后重试',
+    tone: 'destructive',
+  },
+  noData: {
+    icon: InboxIcon,
+    title: '暂无数据',
+    description: '当前没有可显示的数据',
+    tone: 'neutral',
+  },
+  noSearch: {
+    icon: SearchXIcon,
+    title: '没有找到结果',
+    description: '尝试更换搜索词或清除筛选条件',
+    tone: 'neutral',
+  },
+  noNetwork: {
+    icon: WifiOffIcon,
+    title: '暂无网络',
+    description: '请检查网络连接后重试',
+    tone: 'neutral',
+  },
+  browserError: {
+    icon: MonitorXIcon,
+    title: '浏览器不兼容',
+    description: '请使用 Chrome / Edge 等现代浏览器访问',
+    tone: 'neutral',
+  },
+  createSuccess: {
+    icon: CheckCircle2Icon,
+    title: '创建成功',
+    description: '数据已成功创建',
+    tone: 'success',
+  },
+  createError: {
+    icon: XCircleIcon,
+    title: '创建失败',
+    description: '请检查参数后重试，或联系管理员',
+    tone: 'destructive',
+  },
+  import: {
+    icon: UploadIcon,
+    title: '导入数据',
+    description: '请上传 CSV / Excel 文件以批量导入',
+    tone: 'neutral',
+  },
+  success: {
+    icon: CheckCircle2Icon,
+    title: '操作成功',
+    description: '操作已成功完成',
+    tone: 'success',
+  },
+  error: {
+    icon: XCircleIcon,
+    title: '操作失败',
+    description: '操作未完成，请稍后重试',
+    tone: 'destructive',
+  },
+  info: {
+    icon: InfoIcon,
+    tone: 'info',
+  },
+  warning: {
+    icon: AlertTriangleIcon,
+    tone: 'warning',
+  },
+};
+
+const TONE_TEXT_CLASS: Record<EmptyTone, string> = {
+  neutral: 'text-muted-foreground',
+  success: 'text-success',
+  destructive: 'text-destructive',
+  warning: 'text-warning',
+  info: 'text-info',
+};
+
+type EmptySize = NonNullable<VariantProps<typeof emptyVariants>['size']>;
+type EmptyLayout = NonNullable<VariantProps<typeof emptyVariants>['layout']>;
+
+/** 竖向布局下的 icon 尺寸 — 容器内空态 / 中小型赋能反馈场景。 */
+const MEDIA_ICON_SIZE: Record<EmptySize, string> = {
+  sm: 'size-6',
+  default: 'size-10',
+  lg: 'size-16',
+};
+
+/** 横向布局下左侧 icon 尺寸 — 页面级 403/404/500 占位，调高视觉权重与插画区对齐。 */
+const HORIZONTAL_ICON_SIZE: Record<EmptySize, string> = {
+  sm: 'size-12',
+  default: 'size-20',
+  lg: 'size-32',
+};
+
+/* -------------------------------------------------------------------------------------------------
+ * Empty
+ * -----------------------------------------------------------------------------------------------*/
+
+export interface EmptyProps
+  extends Omit<React.ComponentProps<'div'>, 'title'>,
+    VariantProps<typeof emptyVariants> {
+  /** 内置语义状态,自动映射图标与默认中文文案;可被 title / description / media 覆盖 */
+  status?: EmptyStatus;
+  /** 标题(等价 EmptyTitle),与 status 配合时若不传则使用预设文案 */
+  title?: React.ReactNode;
+  /** 描述(等价 EmptyDescription),与 status 配合时若不传则使用预设文案 */
+  description?: React.ReactNode;
+  /** 自定义插画 / 图标(等价 EmptyMedia),传入后覆盖 status 内置图标 */
+  media?: React.ReactNode;
+  /** 操作区（等价 EmptyContent），通常放置返回 / 重试 / 新建等按钮 */
+  extra?: React.ReactNode;
+  /** 内置 status 图标的描边粗细（lucide 原生 strokeWidth），默认 horizontal=1.25 / 竖向=1.5；传入 media 时不生效 */
+  iconStrokeWidth?: number;
+}
+
+function Empty({
+  status,
+  title,
+  description,
+  media,
+  extra,
+  iconStrokeWidth,
+  layout = 'vertical',
+  size,
+  bordered = false,
+  className,
+  children,
+  ...props
+}: EmptyProps) {
+  const preset = status ? STATUS_PRESETS[status] : undefined;
+  const resolvedSize: EmptySize =
+    size ?? (layout === 'horizontal' ? 'lg' : 'default');
+  const resolvedLayout: EmptyLayout = layout ?? 'vertical';
+  const isHorizontal = resolvedLayout === 'horizontal';
+  const StatusIcon = preset?.icon;
+  const toneClass = TONE_TEXT_CLASS[preset?.tone ?? 'neutral'];
+  const iconSizeClass =
+    resolvedLayout === 'horizontal'
+      ? HORIZONTAL_ICON_SIZE[resolvedSize]
+      : MEDIA_ICON_SIZE[resolvedSize];
+  const resolvedStrokeWidth =
+    iconStrokeWidth ?? (resolvedLayout === 'horizontal' ? 1.25 : 1.5);
+
+  const resolvedTitle = title ?? preset?.title;
+  const resolvedDescription = description ?? preset?.description;
+  const hasHeader =
+    resolvedTitle != null && resolvedTitle !== false
+      ? true
+      : resolvedDescription != null && resolvedDescription !== false;
+
+  const showMedia = media != null || StatusIcon != null;
+
+  const headerNode = hasHeader ? (
+    <EmptyHeader>
+      {resolvedTitle != null && resolvedTitle !== false && (
+        <EmptyTitle>{resolvedTitle}</EmptyTitle>
+      )}
+      {resolvedDescription != null && resolvedDescription !== false && (
+        <EmptyDescription>{resolvedDescription}</EmptyDescription>
+      )}
+    </EmptyHeader>
+  ) : null;
+
+  const contentNode =
+    extra != null && extra !== false ? (
+      <EmptyContent className={isHorizontal ? 'mt-10' : undefined}>
+        {extra}
+      </EmptyContent>
+    ) : null;
+
+  const mediaNode = showMedia ? (
+    <EmptyMedia className={cn(isHorizontal && 'w-80 shrink-0')}>
+      {media ??
+        (StatusIcon ? (
+          <StatusIcon
+            strokeWidth={resolvedStrokeWidth}
+            className={cn(iconSizeClass, toneClass)}
+          />
+        ) : null)}
+    </EmptyMedia>
+  ) : null;
+
+  return (
+    <div
+      data-slot="empty"
+      data-layout={layout}
+      data-size={resolvedSize}
+      data-status={status}
+      className={cn(
+        emptyVariants({ layout, size: resolvedSize, bordered }),
+        className,
+      )}
+      {...props}
+    >
+      {children ??
+        (isHorizontal ? (
+          <>
+            {mediaNode}
+            <div
+              data-slot="empty-text"
+              className="flex w-96 flex-col items-start"
+            >
+              {headerNode}
+              {contentNode}
+            </div>
+          </>
+        ) : (
+          <>
+            {mediaNode}
+            {headerNode}
+            {contentNode}
+          </>
+        ))}
+    </div>
+  );
+}
+
+/* -------------------------------------------------------------------------------------------------
+ * Composable subcomponents
+ * -----------------------------------------------------------------------------------------------*/
+
+function EmptyHeader({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="empty-header"
+      className={cn(
+        'flex max-w-md flex-col items-center gap-2 group-data-[layout=horizontal]/empty:items-start',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+const emptyMediaVariants = cva(
+  'flex shrink-0 items-center justify-center [&_svg]:pointer-events-none [&_svg]:shrink-0',
+  {
+    variants: {
+      variant: {
+        default: 'bg-transparent',
+        icon: "size-8 rounded-md bg-muted text-foreground [&_svg:not([class*='size-'])]:size-4",
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+    },
+  },
+);
+
+function EmptyMedia({
+  className,
+  variant = 'default',
+  ...props
+}: React.ComponentProps<'div'> & VariantProps<typeof emptyMediaVariants>) {
+  return (
+    <div
+      data-slot="empty-media"
+      data-variant={variant}
+      className={cn(emptyMediaVariants({ variant, className }))}
+      {...props}
+    />
+  );
+}
+
+function EmptyTitle({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="empty-title"
+      className={cn(
+        'font-medium tracking-tight text-foreground group-data-[size=sm]/empty:text-sm group-data-[size=default]/empty:text-base group-data-[size=lg]/empty:text-2xl group-data-[size=lg]/empty:leading-9 group-data-[layout=horizontal]/empty:text-muted-foreground',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function EmptyDescription({ className, ...props }: React.ComponentProps<'p'>) {
+  return (
+    <div
+      data-slot="empty-description"
+      className={cn(
+        'text-xs text-muted-foreground [&>a]:text-primary [&>a:hover]:text-primary/80',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function EmptyContent({ className, ...props }: React.ComponentProps<'div'>) {
+  return (
+    <div
+      data-slot="empty-content"
+      className={cn(
+        'flex w-full max-w-md min-w-0 flex-col items-center gap-2.5 text-sm text-balance group-data-[layout=horizontal]/empty:items-start',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export {
+  Empty,
+  EmptyHeader,
+  EmptyTitle,
+  EmptyDescription,
+  EmptyContent,
+  EmptyMedia,
+  emptyVariants,
+};

package/src/components/empty/meta.md

@@ -0,0 +1,274 @@
+# Empty
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+空状态 / 结果页 Empty
+用于无数据、错误页、操作结果等占位反馈,既支持复合组件组装,也支持 status 预设一行写完。
+
+## 使用场景
+
+- 列表 / 表格无数据
+- 搜索无结果或筛选无匹配
+- 异常页面:403 / 404 / 500 / 网络错误 / 浏览器不兼容
+- 操作结果反馈:创建成功 / 失败、导入数据等
+- 初始引导态,提示用户进行下一步操作
+- 组合结构:Empty > EmptyMedia + EmptyHeader (EmptyTitle + EmptyDescription) + EmptyContent
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `layout` | `"vertical" \| "horizontal"` | – | – | – |
+| `size` | `"sm" \| "default" \| "lg"` | – | – | – |
+| `bordered` | `"true" \| "false"` | – | – | – |
+| `defaultVariants` | `"layout" \| "size" \| "bordered"` | – | – | – |
+| `noData` | `"icon" \| "title" \| "description" \| "tone"` | – | – | – |
+| `noSearch` | `"icon" \| "title" \| "description" \| "tone"` | – | – | – |
+| `noNetwork` | `"icon" \| "title" \| "description" \| "tone"` | – | – | – |
+| `browserError` | `"icon" \| "title" \| "description" \| "tone"` | – | – | – |
+| `createSuccess` | `"icon" \| "title" \| "description" \| "tone"` | – | – | – |
+| `createError` | `"icon" \| "title" \| "description" \| "tone"` | – | – | – |
+| `import` | `"icon" \| "title" \| "description" \| "tone"` | – | – | – |
+| `success` | `"icon" \| "title" \| "description" \| "tone"` | – | – | – |
+| `error` | `"icon" \| "title" \| "description" \| "tone"` | – | – | – |
+| `info` | `"icon" \| "tone"` | – | – | – |
+| `warning` | `"icon" \| "tone"` | – | – | – |
+| `variants` | `"variant" \| "default" \| "icon"` | – | – | – |
+| `status` | `EmptyStatus` | – | – | 内置语义状态,自动映射图标与默认中文文案;可被 title / description / media 覆盖 |
+| `title` | `React.ReactNode` | – | – | 标题(等价 EmptyTitle),与 status 配合时若不传则使用预设文案 |
+| `description` | `React.ReactNode` | – | – | 描述(等价 EmptyDescription),与 status 配合时若不传则使用预设文案 |
+| `media` | `React.ReactNode` | – | – | 自定义插画 / 图标(等价 EmptyMedia),传入后覆盖 status 内置图标 |
+| `extra` | `React.ReactNode` | – | – | 操作区（等价 EmptyContent），通常放置返回 / 重试 / 新建等按钮 |
+| `iconStrokeWidth` | `number` | – | – | 内置 status 图标的描边粗细（lucide 原生 strokeWidth），默认 horizontal=1.25 / 竖向=1.5；传入 media 时不生效 |
+
+## 示例
+
+### Status403
+
+403 — 没有访问权限。
+
+```tsx
+<Empty layout="horizontal" status="403" extra={<PageActions />} />
+```
+
+### Status404
+
+404 — 页面不存在。
+
+```tsx
+<Empty layout="horizontal" status="404" extra={<PageActions />} />
+```
+
+### Status500
+
+500 — 服务器错误。
+
+```tsx
+<Empty
+  layout="horizontal"
+  status="500"
+  extra={
+    <div className="flex gap-3">
+      <Button size="lg">重试</Button>
+      <Button size="lg" variant="outline">
+        联系客服
+      </Button>
+    </div>
+  }
+/>
+```
+
+### NoSearch
+
+搜索结果为空。
+
+```tsx
+<Empty
+  layout="horizontal"
+  status="noSearch"
+  extra={
+    <Button size="lg" variant="outline">
+      清除筛选
+    </Button>
+  }
+/>
+```
+
+### NoData
+
+数据为空。
+
+```tsx
+<Empty
+  layout="horizontal"
+  status="noData"
+  extra={<Button size="lg">新建</Button>}
+/>
+```
+
+### NoNetwork
+
+暂无网络。
+
+```tsx
+<Empty
+  layout="horizontal"
+  status="noNetwork"
+  extra={<Button size="lg">重试</Button>}
+/>
+```
+
+### BrowserError
+
+浏览器不兼容。
+
+```tsx
+<Empty
+  layout="horizontal"
+  status="browserError"
+  extra={
+    <Button size="lg" variant="outline">
+      了解详情
+    </Button>
+  }
+/>
+```
+
+### CreateSuccess
+
+创建成功。
+
+```tsx
+<Empty
+  layout="horizontal"
+  status="createSuccess"
+  extra={
+    <div className="flex gap-3">
+      <Button size="lg">查看详情</Button>
+      <Button size="lg" variant="outline">
+        继续创建
+      </Button>
+    </div>
+  }
+/>
+```
+
+### CreateError
+
+创建失败。
+
+```tsx
+<Empty
+  layout="horizontal"
+  status="createError"
+  extra={<Button size="lg">重试</Button>}
+/>
+```
+
+### ImportData
+
+导入数据。
+
+```tsx
+<Empty
+  layout="horizontal"
+  status="import"
+  extra={<Button size="lg">上传文件</Button>}
+/>
+```
+
+### InContainer
+
+容器内使用 — 竖向布局,放在带边框的容器里,适合表格 / 列表无数据时的占位。
+
+```tsx
+<div className="w-full max-w-2xl rounded-md border border-border bg-card">
+  <Empty status="noData" />
+</div>
+```
+
+### WithMessage
+
+使用 message 区域 — 在描述与按钮之间内嵌 Alert,补充上下文信息。
+
+```tsx
+<Empty
+  layout="horizontal"
+  status="404"
+  extra={
+    <div className="flex flex-col gap-4">
+      <Alert>
+        <InfoIcon />
+        <AlertDescription>
+          当前数据包:数据包名称名称数据包名称名称数据包名称名称
+        </AlertDescription>
+      </Alert>
+      <PageActions />
+    </div>
+  }
+/>
+```
+
+### WithIcon
+
+带图标 — 横向小尺寸,内联状态图标 + 标题/描述/按钮,适合抽屉、对话框 M/L 中的结果反馈。
+
+```tsx
+<Empty
+  layout="horizontal"
+  size="sm"
+  status="success"
+  title="创建成功,标题居左对齐,标题(不含 icon)宽度根据文字内容自适应,超过 400px 后折行"
+  description="描述内容,文案居左对齐,宽度根据文字内容自适应,超出 400px 后折行,此样式适用于页面、抽屉、对话框 M/L 中的结果反馈。文字区域主要用于辅助信息说明,同时如有后续引导操作或者内容区,可在容器底部呈现。"
+  extra={<PageActions />}
+/>
+```
+
+### Sizes
+
+三档尺寸对照 — sm / default / lg。
+
+```tsx
+<div className="flex flex-col gap-6">
+  <Empty size="sm" status="noData" />
+  <Empty size="default" status="noData" />
+  <Empty size="lg" status="noData" />
+</div>
+```
+
+### Bordered
+
+显式 bordered — 卡片态空状态,适合需要明确边界的容器内场景。
+
+```tsx
+<Empty
+  bordered
+  status="noData"
+  title="暂无数据"
+  description="点击下方按钮新建。"
+  extra={<Button>新建</Button>}
+/>
+```
+
+### Composable
+
+完全组装写法 — 绕过 status 预设,所有内容自定义。
+
+```tsx
+<Empty>
+  <EmptyMedia>
+    <InfoIcon className="size-10 text-info" />
+  </EmptyMedia>
+  <EmptyHeader>
+    <EmptyTitle>自定义标题</EmptyTitle>
+    <EmptyDescription>
+      完全使用复合组件组装,适合需要精细控制的场景。
+    </EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button>开始</Button>
+  </EmptyContent>
+</Empty>
+```