@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/empty/empty.tsx

@@ -1,54 +0,0 @@
-import * as React from 'react';
-import { Inbox } from 'lucide-react';
-
-import { cn } from '@/utils/cn';
-
-export interface EmptyProps extends React.HTMLAttributes<HTMLDivElement> {
-  /** 自定义图标(覆盖默认 Inbox)。 */
-  image?: React.ReactNode;
-  /** 描述文本。 @default "暂无数据" */
-  description?: React.ReactNode;
-  /** 操作区(放 Button 引导用户创建首条数据)。 */
-  extra?: React.ReactNode;
-  /**
-   * 尺寸 — `sm` 用于卡片内 / 表格空态;`default` 用于整区。
-   * @default "default"
-   */
-  size?: 'sm' | 'md' | 'default';
-}
-
-const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
-  (
-    {
-      image,
-      description = '暂无数据',
-      extra,
-      size = 'md',
-      className,
-      ...props
-    },
-    ref,
-  ) => {
-    const isSm = size === 'sm';
-    return (
-      <div
-        ref={ref}
-        className={cn(
-          'flex flex-col items-center justify-center gap-3 text-muted-foreground',
-          isSm ? 'py-8' : 'py-16',
-          className,
-        )}
-        {...props}
-      >
-        <div className={cn('opacity-40', isSm ? 'text-3xl' : 'text-5xl')}>
-          {image ?? <Inbox className={isSm ? 'size-8' : 'size-16'} />}
-        </div>
-        <div className="text-xs">{description}</div>
-        {extra ? <div className="mt-1">{extra}</div> : null}
-      </div>
-    );
-  },
-);
-Empty.displayName = 'Empty';
-
-export { Empty };

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

@@ -1,154 +0,0 @@
----
-id: field
-name: Field
-displayName: 表单字段
-type: component
-category: data-entry
-since: 0.1.0
-package: '@teamix-evo/ui'
----
-
-# Field 表单字段
-
-通用表单字段抽象 — shadcn 2025-10 新增。**比 `Form` 更通用**:Form 强绑定 RHF + zod;Field 是纯 UI 抽象,跟任何状态管理(Server Actions / RHF / TanStack Form / 原生 form)都能搭。提供 7 个语义槽:`Field` 容器 / `FieldLabel` 标签 / `FieldDescription` 帮助文案 / `FieldError` 错误提示 / `FieldGroup` 多字段纵向容器 / `FieldSet` 带边框分组 / `FieldLegend` 分组标题。
-
-## When to use
-
-- Server Actions / 原生 form / 任何非 RHF 流派的表单字段封装
-- 与现有 `Form`(RHF)互补:Form 管校验与状态,**控件内部**仍可用 Field 表达视觉结构
-- 大型表单分组(FieldSet + FieldLegend 表达"账号信息" / "联系方式"等小节)
-
-## When NOT to use
-
-- 已用 `Form`(RHF)并接受其约定 → 优先 `FormItem / FormLabel / FormMessage`(更紧)
-- 控件本身没有 label / description → 直接用 `Input` / `Select` 自由布局
-
-## Props
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `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 -->
-### 同库依赖
-
-> `teamix-evo ui add field` 时,以下 entry 会被自动连带安装(无需手动 add)。
-
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `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 依赖
-
-> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
-
-```bash
-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 生成纪律
-
-- **`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
-- ✅ 使用 `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
-
-```tsx
-import {
-  Field,
-  FieldLabel,
-  FieldDescription,
-  FieldError,
-  FieldGroup,
-  FieldSet,
-  FieldLegend,
-} from '@/components/ui/field';
-import { Input } from '@/components/ui/input';
-import { Switch } from '@/components/ui/switch';
-
-// 单字段
-<Field invalid={Boolean(errors.email)}>
-  <FieldLabel htmlFor="email" required>邮箱</FieldLabel>
-  <Input id="email" type="email" name="email" />
-  <FieldDescription>用于接收订单通知</FieldDescription>
-  <FieldError>{errors.email}</FieldError>
-</Field>
-
-// horizontal(长表单)
-<Field orientation="horizontal">
-  <FieldLabel htmlFor="notify" className="min-w-32">
-    邮件通知
-  </FieldLabel>
-  <Switch id="notify" defaultChecked />
-</Field>
-
-// 分组
-<FieldSet>
-  <FieldLegend>账号信息</FieldLegend>
-  <FieldGroup>
-    <Field>
-      <FieldLabel htmlFor="name">姓名</FieldLabel>
-      <Input id="name" name="name" />
-    </Field>
-    <Field>
-      <FieldLabel htmlFor="email">邮箱</FieldLabel>
-      <Input id="email" name="email" type="email" />
-    </Field>
-  </FieldGroup>
-</FieldSet>
-
-// 配 Server Actions
-<form action={createUser}>
-  <FieldGroup>
-    <Field>
-      <FieldLabel htmlFor="name" required>姓名</FieldLabel>
-      <Input id="name" name="name" required />
-    </Field>
-  </FieldGroup>
-  <button type="submit">提交</button>
-</form>
-```