@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/ellipsis/ellipsis.tsx

@@ -0,0 +1,153 @@
+import * as React from 'react';
+
+import { cn } from '@/utils/cn';
+import {
+  TooltipContent,
+  TooltipProvider,
+  TooltipRoot,
+  TooltipTrigger,
+} from '@/components/tooltip/tooltip';
+
+export interface EllipsisProps
+  extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'title'> {
+  /**
+   * 超长时显示的 tooltip 文本 — 不传时自动用 children 的纯文本(优先)或 `title` 属性。
+   * 显示规则:仅当实际渲染时检测到溢出(scrollWidth > clientWidth 或 scrollHeight > clientHeight)才挂载 Tooltip。
+   */
+  tooltip?: React.ReactNode;
+  /**
+   * 多行截断行数。传入数字 >1 时走 `-webkit-line-clamp` 多行模式;否则单行 truncate。
+   * @default 1
+   */
+  lines?: number;
+  /**
+   * 是否在文本右侧叠加渐变遮罩(对齐《Teamix UI 表单设计规范》§八 "截断 + 渐变遮罩 + hover tooltip 三件套")。
+   * 默认开启;在容器无溢出时 mask 自动隐藏(scrollWidth ≤ clientWidth)。
+   * @default true
+   */
+  fade?: boolean;
+  /**
+   * Tooltip 弹出方向。
+   * @default 'top'
+   */
+  tooltipSide?: 'top' | 'right' | 'bottom' | 'left';
+}
+
+/**
+ * `Ellipsis` 单行 / 多行文本截断 + 渐变遮罩 + 溢出时自动 tooltip 提示。
+ *
+ * 对齐《Teamix UI 表单设计规范》§八 "内容显示不完全 — 截断 + 渐变遮罩 + hover tooltip 三件套"。
+ *
+ * @example
+ * <Ellipsis>这一段超长文本会自动截断、右侧带渐变遮罩,hover 弹 tooltip 看全文</Ellipsis>
+ *
+ * @example // 多行
+ * <Ellipsis lines={2}>...</Ellipsis>
+ *
+ * @example // 显式 tooltip 内容
+ * <Ellipsis tooltip="完整内容...">概要</Ellipsis>
+ */
+const Ellipsis = React.forwardRef<HTMLSpanElement, EllipsisProps>(
+  (
+    {
+      children,
+      tooltip,
+      lines = 1,
+      fade = true,
+      tooltipSide = 'top',
+      className,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
+    const innerRef = React.useRef<HTMLSpanElement | null>(null);
+    const [overflowing, setOverflowing] = React.useState(false);
+
+    // 把外部 ref 与内部 ref 合并
+    const setRef = React.useCallback(
+      (node: HTMLSpanElement | null) => {
+        innerRef.current = node;
+        if (typeof ref === 'function') ref(node);
+        else if (ref) (ref as React.MutableRefObject<HTMLSpanElement | null>).current = node;
+      },
+      [ref],
+    );
+
+    // 监听容器尺寸变化,实时计算是否溢出
+    React.useEffect(() => {
+      const el = innerRef.current;
+      if (!el) return;
+      const check = () => {
+        setOverflowing(
+          el.scrollWidth > el.clientWidth ||
+            el.scrollHeight > el.clientHeight,
+        );
+      };
+      check();
+      const ro = new ResizeObserver(check);
+      ro.observe(el);
+      return () => ro.disconnect();
+    }, [children, lines]);
+
+    const isMulti = lines > 1;
+
+    const baseStyle: React.CSSProperties = isMulti
+      ? {
+          display: '-webkit-box',
+          WebkitLineClamp: lines,
+          WebkitBoxOrient: 'vertical',
+          overflow: 'hidden',
+        }
+      : {
+          display: 'block',
+          overflow: 'hidden',
+          whiteSpace: 'nowrap',
+          textOverflow: 'ellipsis',
+        };
+
+    // 渐变遮罩:仅在溢出时挂(避免短文本也带 mask)。
+    // mask 只用 alpha 通道,颜色字面量 black 是 CSS 关键字、非语义色,等价于 alpha=1。
+    const fadeStyle: React.CSSProperties =
+      fade && overflowing
+        ? {
+            maskImage:
+              'linear-gradient(to right, black calc(100% - 2rem), transparent)',
+            WebkitMaskImage:
+              'linear-gradient(to right, black calc(100% - 2rem), transparent)',
+          }
+        : {};
+
+    const node = (
+      <span
+        ref={setRef}
+        data-overflowing={overflowing ? '' : undefined}
+        style={{ ...baseStyle, ...fadeStyle, ...style }}
+        className={cn('min-w-0 max-w-full', className)}
+        {...props}
+      >
+        {children}
+      </span>
+    );
+
+    if (!overflowing) return node;
+
+    const tooltipBody = tooltip ?? children;
+
+    return (
+      <TooltipProvider delayDuration={200}>
+        <TooltipRoot>
+          <TooltipTrigger asChild>{node}</TooltipTrigger>
+          <TooltipContent side={tooltipSide}>
+            <div className="max-w-xs whitespace-normal break-words text-xs">
+              {tooltipBody}
+            </div>
+          </TooltipContent>
+        </TooltipRoot>
+      </TooltipProvider>
+    );
+  },
+);
+Ellipsis.displayName = 'Ellipsis';
+
+export { Ellipsis };

package/src/components/empty/empty.meta.md

@@ -2,12 +2,13 @@
 id: empty
 name: Empty
 type: component
-category: feedback
+category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 空状态
 ---
 
-# Empty
+# Empty 空状态
 
 空状态 — antd 独有补足。**列表 / 表格 / 搜索结果为空**时的占位提示,提供引导动作鼓励用户创建首条数据。
 
@@ -23,15 +24,19 @@ package: "@teamix-evo/ui"
 - 错误 / 失败 → `Result` 或 `Alert`
 - 表单字段空 → 直接 placeholder
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
 | `image` | `React.ReactNode` | – | – | 自定义图标(覆盖默认 Inbox)。 |
 | `description` | `React.ReactNode` | `"暂无数据"` | – | 描述文本。 |
 | `extra` | `React.ReactNode` | – | – | 操作区(放 Button 引导用户创建首条数据)。 |
-| `size` | `'sm' \| 'default'` | `"default"` | – | 尺寸 — `sm` 用于卡片内 / 表格空态;`default` 用于整区。 |
+| `size` | `'sm' \| 'md' \| 'default'` | `"default"` | – | 尺寸 — `sm` 用于卡片内 / 表格空态;`default` 用于整区。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 

package/src/components/empty/empty.stories.tsx

@@ -1,17 +1,17 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Plus } from 'lucide-react';
 import { Empty } from './empty';
 import { Button } from '@/components/button/button';
 
 const meta: Meta<typeof Empty> = {
-  title: '反馈与浮层 · Feedback/Empty',
+  title: '数据展示 · Data Display/Empty',
   component: Empty,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '空状态 — 列表 / 表格 / 搜索结果为空时的占位提示。提供 description 引导文案 + extra 主操作,鼓励用户创建首条数据。OpenTrek tokens 适配,等价 antd Empty。',
+          '空状态 — 列表 / 表格 / 搜索结果为空时的占位提示。提供 description 引导文案 + extra 主操作，鼓励用户创建首条数据。等价 antd Empty。',
       },
     },
   },
@@ -39,7 +39,7 @@ export const WithAction: Story = {
 export const Small: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="rounded-md border">
+    <div className="rounded-md border border-border">
       <Empty size="sm" description="无匹配的搜索结果" />
     </div>
   ),

package/src/components/empty/empty.tsx

@@ -14,12 +14,19 @@ export interface EmptyProps extends React.HTMLAttributes<HTMLDivElement> {
    * 尺寸 — `sm` 用于卡片内 / 表格空态;`default` 用于整区。
    * @default "default"
    */
-  size?: 'sm' | 'default';
+  size?: 'sm' | 'md' | 'default';
 }
 
 const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
   (
-    { image, description = '暂无数据', extra, size = 'default', className, ...props },
+    {
+      image,
+      description = '暂无数据',
+      extra,
+      size = 'md',
+      className,
+      ...props
+    },
     ref,
   ) => {
     const isSm = size === 'sm';
@@ -36,7 +43,7 @@ const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
         <div className={cn('opacity-40', isSm ? 'text-3xl' : 'text-5xl')}>
           {image ?? <Inbox className={isSm ? 'size-8' : 'size-16'} />}
         </div>
-        <div className={cn(isSm ? 'text-xs' : 'text-sm')}>{description}</div>
+        <div className="text-xs">{description}</div>
         {extra ? <div className="mt-1">{extra}</div> : null}
       </div>
     );

package/src/components/field/field.meta.md

@@ -1,13 +1,14 @@
 ---
 id: field
 name: Field
+displayName: 表单字段
 type: component
-category: form
+category: data-entry
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Field
+# Field 表单字段
 
 通用表单字段抽象 — shadcn 2025-10 新增。**比 `Form` 更通用**:Form 强绑定 RHF + zod;Field 是纯 UI 抽象,跟任何状态管理(Server Actions / RHF / TanStack Form / 原生 form)都能搭。提供 7 个语义槽:`Field` 容器 / `FieldLabel` 标签 / `FieldDescription` 帮助文案 / `FieldError` 错误提示 / `FieldGroup` 多字段纵向容器 / `FieldSet` 带边框分组 / `FieldLegend` 分组标题。
 
@@ -22,13 +23,19 @@ package: "@teamix-evo/ui"
 - 已用 `Form`(RHF)并接受其约定 → 优先 `FormItem / FormLabel / FormMessage`(更紧)
 - 控件本身没有 label / description → 直接用 `Input` / `Select` 自由布局
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
-| `orientation` | `'vertical' \| 'horizontal'` | `"vertical"` | – | 字段方向 — `vertical`(默认)Label 在控件上;`horizontal` Label 在控件左侧(配长表单)。 |
+| `orientation` | `ResponsiveValue<FieldOrientation>` | `"vertical"` | – | 字段方向 — 标量或 5 档断点响应式映射: - `vertical`(默认)Label 在控件上; - `horizontal` Label 在控件左侧(配长表单); - 响应式对象 `{ base, xs, s, m, l, xl }` 按视口断点自动切换 (对齐设计规范 §4.2:单栏表单 < 432 应改上下结构)。 |
 | `invalid` | `boolean` | `false` | – | 标记字段为 invalid — 子组件的 ring / 文字色会跟随;同时把内部 `<FieldError>` 渲染为可见。 |
+| `inputWidth` | `InputWidth` | – | – | 输入域宽度档位 — 5 档系统，对应 104 / 216 / 328 / 440 / 552 px。 通过 Context 下发，并在 Field 容器上注入 CSS 变量 `--field-input-width`，子组件可消费。 |
+| `children` | `React.ReactNode` | – | – | – |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -38,6 +45,7 @@ package: "@teamix-evo/ui"
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 | `label` | component | 表单字段标签 — Radix Label 包装,补 antd Form.Item 风格的 required / disabled 显式视觉 |
+| `use-breakpoint` | hook | 响应式断点 hook + pickByBreakpoint 工具 — 5 档断点(432/672/944/1200/1600,对齐《Teamix UI 表单设计规范》§4.1),给 Field 响应式 orientation / FilterBarPanel 响应式列数共用 |
 
 ### npm 依赖
 
@@ -48,14 +56,44 @@ pnpm add class-variance-authority@^0.7.0
 ```
 <!-- auto:deps:end -->
 
+## 子组件
+
+除上表中的核心 Field 外，本包还提供以下表单骨架子组件：
+
+- **`FieldGroup`**:多个 Field 的纵向容器。
+  - `density?: 'normal' | 'detail'`(默认 `normal`):
+    - `normal` → 20px 行距(`gap-5`,标准表单与混合详情)
+    - `detail` → 12px 行距(`gap-3`,纯详情页,对齐规范 §3.5)
+- **`FieldSection`**：表单字段分组容器。
+  - `title`：组标题（14px medium），有值时渲染标题行。
+  - `columns?: 1 | 2 | 3 | 4`：多栏 grid 列数（留空走单列 `flex-col`），列内 `gap-x-4`（16px）/ 行间 `gap-y-5`（20px，对齐规范 §3.1 规则 4）。
+  - 多个 FieldSection 之间由父容器提供 `gap-8`（32px）。是 "账号信息 / 联系方式" 这种小节划分的首选（不要用裸 div + space-y-*）。
+- **`FieldActions`**：表单操作按钮容器。
+  - `container?: 'page' | 'page-stepper' | 'modal' | 'drawer'`：容器场景预设(对齐规范 §六),一次性配齐 position/align/alignWithInput:
+    - `page` → inline + start + 基线对齐(页面基础/分组表单)
+    - `page-stepper` → sticky + start(页面分步表单)
+    - `modal` → inline + end(弹窗)
+    - `drawer` → sticky + start(抽屉)
+  - `position`：`'inline'` 底部跟随 / `'sticky'` 底部吸顶。未设时由 `container` 推导。
+  - `align`：`'start'` / `'end'`（默认 `end`）。未设时由 `container` 推导。
+  - `alignWithInput?: boolean`：水平表单（Field `orientation="horizontal"`）时让按钮起点对齐输入框左边界（规范 §六 "基础/分组表单按钮跟随基线对齐"）；通过 CSS 变量 `--form-label-width` 读取列宽，默认 `33.333%`。未设时由 `container` 推导。
+  - 代替裸 div + flex 手写。
+
 ## AI 生成纪律
 
-- **`invalid` 是单一真值**:置于 `<Field>`,内部 `FieldLabel` 会变红、`FieldError` 才可见;**不要**同时给控件再传 `aria-invalid`,重复
-- **`FieldError` children 为空时不渲染** — 直接传可空字符串 / `errors?.email` 即可,无需条件渲染
-- **`FieldLabel required`** 仅视觉(红 *);**业务层必填**仍要在 schema / submit handler 校验
-- **`FieldSet disabled`** 利用原生 fieldset 的级联禁用 — 内部所有原生 input 都会失能;**不要**手动给每个控件传 disabled
+- **`orientation` 支持响应式**：传 `ResponsiveValue<'vertical' | 'horizontal'>`,如 `{ base: 'vertical', xs: 'horizontal' }`(<432 上下、≥432 左右,对齐规范 §4.2 单栏自动切换)。底层走 `useBreakpoint`,SSR 首屏取 `base` 兜底。**不要**手写 `useMediaQuery` + 条件渲染。
+- **`invalid` 是单一真值**：置于 `<Field>`，内部 `FieldLabel` 会变红、`FieldError` 才可见；**不要**同时给控件再传 `aria-invalid`，重复
+- **`FieldError` children 为空时不渲染** — 直接传可空字符串 / `errors?.email` 即可，无需条件渲染
+- **`FieldLabel required`** 仅视觉（红 `*` **后置**在文字和 tooltip icon 右侧，顺序为 `文字 ⓘ *`）；**业务层必填**仍要在 schema / submit handler 校验
+- **`FieldSet disabled`** 利用原生 fieldset 的级联禁用 — 内部所有原生 input 都会失能；**不要**手动给每个控件传 disabled
 - **不要嵌套 `Field` in `Field`** — 那是 FieldGroup 的活
-- **与 `Form` 共存**:在 RHF 流程外的小表单(登录、邮件订阅)直接用 Field;复杂业务表单仍走 Form
+- **与 `Form` 共存**：在 RHF 流程外的小表单（登录、邮件订阅）直接用 Field；复杂业务表单仍走 Form
+- ✅ 使用 `inputWidth` 档位代替硬编码宽度值（不要手写 `w-[328px]` 或 `style={{ width: 328 }}`）
+- ✅ 多字段分组必须使用 `FieldSection`（不要用裸 div + space-y-*）
+- ✅ 操作按钮必须使用 `FieldActions`(不要用裸 div + flex);**根据所处容器优先用 `container` prop**(`page` / `page-stepper` / `modal` / `drawer`)而不是手设 position/align/alignWithInput,对齐规范 §六
+- ✅ 多个 `FieldSection` 的父容器必须用 `gap-8`（32px 组间距）
+- ✅ `orientation="horizontal"` 模式 Label 与 Input 间距固定为 **16px**（`gap-4`,组件内置）；不要手动加 `gap-3` / `gap-5` 等覆盖
+- ✅ horizontal 模式下 FieldLabel 自动 `max-width = ⅓ 输入域宽`(对齐规范 §七),超长 truncate;**显式 `maxWidth` 仍优先**。需要更长 label 时显式传 `maxWidth={数字 | 'XX%'}`
 
 ## Examples