@teamix-evo/ui 0.1.1 → 0.2.0

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

@@ -1,13 +1,14 @@
 ---
 id: field
 name: Field
+displayName: 表单字段
 type: component
 category: form
 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,21 +23,36 @@ 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 在控件左侧(配长表单)。 |
-| `invalid` | `boolean` | `false` | – | 标记字段为 invalid — 子组件的 ring / 文字色会跟随;同时把内部 `<FieldError>` 渲染为可见。 |
+
+#### Field
+
+| 名称          | 类型                         | 默认值       | 必填 | 说明                                                                                      |
+| ------------- | ---------------------------- | ------------ | ---- | ----------------------------------------------------------------------------------------- |
+| `orientation` | `'vertical' \| 'horizontal'` | `"vertical"` | –    | 字段方向 — `vertical`（默认）Label 在控件上；`horizontal` Label 在控件左侧（配长表单）。  |
+| `invalid`     | `boolean`                    | `false`      | –    | 标记字段为 invalid — 子组件的 ring / 文字色会跟随；同时把内部 `<FieldError>` 渲染为可见。 |
+
+#### FieldLabel
+
+| 名称       | 类型      | 默认值  | 必填 | 说明                                                                                             |
+| ---------- | --------- | ------- | ---- | ------------------------------------------------------------------------------------------------ |
+| `required` | `boolean` | `false` | –    | 在 label 末尾追加 "\*" 强调必填（antd Form `required` 并集）— 仅视觉，业务侧需在校验层确保必填。 |
+
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add field` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry   | 类型      | 描述                                                                                  |
+| ------- | --------- | ------------------------------------------------------------------------------------- |
+| `cn`    | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                    |
 | `label` | component | 表单字段标签 — Radix Label 包装,补 antd Form.Item 风格的 required / disabled 显式视觉 |
 
 ### npm 依赖
@@ -46,13 +62,14 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add class-variance-authority@^0.7.0
 ```
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律
 
 - **`invalid` 是单一真值**:置于 `<Field>`,内部 `FieldLabel` 会变红、`FieldError` 才可见;**不要**同时给控件再传 `aria-invalid`,重复
 - **`FieldError` children 为空时不渲染** — 直接传可空字符串 / `errors?.email` 即可,无需条件渲染
-- **`FieldLabel required`** 仅视觉(红 *);**业务层必填**仍要在 schema / submit handler 校验
+- **`FieldLabel required`** 仅视觉(红 \*);**业务层必填**仍要在 schema / submit handler 校验
 - **`FieldSet disabled`** 利用原生 fieldset 的级联禁用 — 内部所有原生 input 都会失能;**不要**手动给每个控件传 disabled
 - **不要嵌套 `Field` in `Field`** — 那是 FieldGroup 的活
 - **与 `Form` 共存**:在 RHF 流程外的小表单(登录、邮件订阅)直接用 Field;复杂业务表单仍走 Form

package/src/components/field/field.stories.tsx

@@ -20,12 +20,15 @@ const meta: Meta<typeof Field> = {
     docs: {
       description: {
         component:
-          '通用表单字段抽象 — 比 Form 更通用(Form 强绑 RHF;Field 跟任何状态管理都能搭)。7 个语义槽:Field / FieldLabel / FieldDescription / FieldError / FieldGroup / FieldSet / FieldLegend。shadcn 2025-10 新增,与现有 Form 共存。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '通用表单字段抽象 — 比 Form 更通用（Form 强绑 RHF；Field 跟任何状态管理都能搭）。7 个语义槽：Field / FieldLabel / FieldDescription / FieldError / FieldGroup / FieldSet / FieldLegend。shadcn 2025-10 新增，与现有 Form 共存。',
       },
     },
   },
   argTypes: {
-    orientation: { control: 'inline-radio', options: ['vertical', 'horizontal'] },
+    orientation: {
+      control: 'inline-radio',
+      options: ['vertical', 'horizontal'],
+    },
     invalid: { control: 'boolean' },
   },
   args: { orientation: 'vertical', invalid: false },
@@ -92,7 +95,7 @@ export const ServerActionForm: Story = {
       onSubmit={(e) => {
         e.preventDefault();
         const fd = new FormData(e.currentTarget);
-        // eslint-disable-next-line no-alert
+
         alert(`提交: ${JSON.stringify(Object.fromEntries(fd.entries()))}`);
       }}
       className="w-96 space-y-4"

package/src/components/flex/flex.meta.md

@@ -1,13 +1,14 @@
 ---
 id: flex
 name: Flex
+displayName: 弹性布局
 type: component
 category: layout
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Flex
+# Flex 弹性布局
 
 Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+),把 Tailwind flex 的常用配置(对齐 / 间距 / 换行 / 方向 / 渲染元素)收敛为枚举,避免散落的 `flex flex-col items-start gap-4 ...` 反复手写。
 
@@ -23,30 +24,38 @@ Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+),把 Tai
 - 网格 → `Grid`(`Row + Col`)
 - 仅一次性自由布局 → 直接写 className 也行,不强求
 
+## Props
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `direction` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` | `"row"` | – | 方向(antd `vertical` 并集) — `row`(默认)/ `column` 直观可读;antd `vertical` boolean 映射为 `column`。 |
-| `gap` | `'none' \| 'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 子项之间的间距档位(走 design 间距刻度,不接受任意 number)。 |
-| `align` | `keyof typeof alignMap` | `"stretch"` | – | 副轴对齐方式。 |
-| `justify` | `keyof typeof justifyMap` | `"start"` | – | 主轴对齐方式。 |
-| `wrap` | `boolean` | `false` | – | 是否允许换行(antd `wrap` 并集)。 |
-| `inline` | `boolean` | `false` | – | inline-flex 而非 block-flex。 |
-| `as` | `keyof Pick< React.JSX.IntrinsicElements, 'div' \| 'section' \| 'header' \| 'footer' \| 'aside' \| 'main' \| 'nav' \| 'article' >` | `"div"` | – | 渲染元素(antd `component` 并集) — 支持 `section / header / aside / main / nav` 等语义标签。 |
+
+| 名称        | 类型                                                                                                                               | 默认值      | 必填 | 说明                                                                                                  |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---- | ----------------------------------------------------------------------------------------------------- |
+| `direction` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'`                                                                           | `"row"`     | –    | 方向(antd `vertical` 并集) — `row`(默认)/ `column` 直观可读;antd `vertical` boolean 映射为 `column`。 |
+| `gap`       | `'none' \| 'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl'`                                                                              | `"default"` | –    | 子项之间的间距档位(走 design 间距刻度,不接受任意 number)。                                            |
+| `align`     | `keyof typeof alignMap`                                                                                                            | `"stretch"` | –    | 副轴对齐方式。                                                                                        |
+| `justify`   | `keyof typeof justifyMap`                                                                                                          | `"start"`   | –    | 主轴对齐方式。                                                                                        |
+| `wrap`      | `boolean`                                                                                                                          | `false`     | –    | 是否允许换行(antd `wrap` 并集)。                                                                      |
+| `inline`    | `boolean`                                                                                                                          | `false`     | –    | inline-flex 而非 block-flex。                                                                         |
+| `as`        | `keyof Pick< React.JSX.IntrinsicElements, 'div' \| 'section' \| 'header' \| 'footer' \| 'aside' \| 'main' \| 'nav' \| 'article' >` | `"div"`     | –    | 渲染元素(antd `component` 并集) — 支持 `section / header / aside / main / nav` 等语义标签。           |
+
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add flex` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
 _无 — 本组件不依赖任何 npm 包。_
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/flex/flex.stories.tsx

@@ -10,7 +10,7 @@ const meta: Meta<typeof Flex> = {
     docs: {
       description: {
         component:
-          'Flex 布局容器 — 把 Tailwind flex 的常用配置(对齐 / 间距 / 换行 / 方向 / 渲染元素)收敛为枚举。等价 antd `Flex`(v5.10+),与 Space 互补:Flex 偏完整布局容器,Space 偏 inline 小集合。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          'Flex 布局容器 — 把 Tailwind flex 的常用配置(对齐 / 间距 / 换行 / 方向 / 渲染元素)收敛为枚举。等价 antd `Flex`(v5.10+),与 Space 互补:Flex 偏完整布局容器,Space 偏 inline 小集合。',
       },
     },
   },
@@ -19,7 +19,10 @@ const meta: Meta<typeof Flex> = {
       control: 'inline-radio',
       options: ['row', 'column', 'row-reverse', 'column-reverse'],
     },
-    gap: { control: 'select', options: ['none', 'xs', 'sm', 'default', 'lg', 'xl'] },
+    gap: {
+      control: 'select',
+      options: ['none', 'xs', 'sm', 'default', 'lg', 'xl'],
+    },
     align: {
       control: 'inline-radio',
       options: ['start', 'center', 'end', 'baseline', 'stretch'],
@@ -63,12 +66,23 @@ export const Playground: Story = {
 export const Header: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <Flex as="header" justify="between" align="center" className="rounded-md border bg-card px-6 py-3">
+    <Flex
+      as="header"
+      justify="between"
+      align="center"
+      className="rounded-md border bg-card px-6 py-3"
+    >
       <span className="font-semibold">Logo</span>
       <Flex gap="sm">
-        <a href="#" className="text-sm hover:underline">首页</a>
-        <a href="#" className="text-sm hover:underline">文档</a>
-        <a href="#" className="text-sm hover:underline">价格</a>
+        <a href="#" className="text-sm hover:underline">
+          首页
+        </a>
+        <a href="#" className="text-sm hover:underline">
+          文档
+        </a>
+        <a href="#" className="text-sm hover:underline">
+          价格
+        </a>
       </Flex>
       <Button size="sm">登录</Button>
     </Flex>
@@ -78,7 +92,11 @@ export const Header: Story = {
 export const ColumnStack: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <Flex direction="column" gap="sm" className="w-80 rounded-md border bg-card p-6">
+    <Flex
+      direction="column"
+      gap="sm"
+      className="w-80 rounded-md border bg-card p-6"
+    >
       <span className="text-lg font-semibold">标题</span>
       <span className="text-sm text-muted-foreground">这是一段描述文字</span>
       <Button>操作</Button>
@@ -100,13 +118,27 @@ export const WrapCloud: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <Flex wrap gap="sm" className="w-96 rounded-md border bg-card p-3">
-      {['React', 'Vue', 'Svelte', 'Solid', 'Angular', 'Lit', 'Qwik', 'Astro', 'Next', 'Remix', 'Nuxt', 'Gatsby'].map(
-        (t) => (
-          <span key={t} className="rounded-md border bg-muted px-2 py-0.5 text-xs">
-            {t}
-          </span>
-        ),
-      )}
+      {[
+        'React',
+        'Vue',
+        'Svelte',
+        'Solid',
+        'Angular',
+        'Lit',
+        'Qwik',
+        'Astro',
+        'Next',
+        'Remix',
+        'Nuxt',
+        'Gatsby',
+      ].map((t) => (
+        <span
+          key={t}
+          className="rounded-md border bg-muted px-2 py-0.5 text-xs"
+        >
+          {t}
+        </span>
+      ))}
     </Flex>
   ),
 };

package/src/components/float-button/float-button.meta.md

@@ -4,10 +4,11 @@ name: FloatButton
 type: component
 category: navigation
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 悬浮按钮
 ---
 
-# FloatButton
+# FloatButton 悬浮按钮
 
 悬浮按钮 — antd 独有补足。**等价 antd `FloatButton`**(v5.0 加入,取代旧 `BackTop`)。`position: fixed` 在右下角的强主张操作按钮:回到顶部、客服入口、新建按钮。配 `FloatButtonGroup` 纵向堆叠多个,`FloatButtonBackTop` 是预置的"回到顶部"快捷件。
 
@@ -24,23 +25,45 @@ package: "@teamix-evo/ui"
 - 列表行末操作 → 普通 `Button` / `DropdownMenu`
 - 多个无关操作堆在右下:容易遮挡内容,> 3 个 FloatButton 时换 SpeedDial 模式
 
+## Props
+
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `icon` | `React.ReactNode` | – | – | 图标(antd `icon` 并集)。 |
-| `variant` | `'primary' \| 'default'` | `"primary"` | – | 视觉风格 — `primary` 主色填充;`default` 灰色轮廓。 |
-| `shape` | `'circle' \| 'square'` | `"circle"` | – | 形状 — `circle`(默认)圆形;`square` 方形圆角。 |
-| `badge` | `React.ReactNode` | – | – | 触发徽标(antd `badge` 并集) — 简短数字 / 字符。 |
+
+#### FloatButton
+
+| 名称      | 类型                     | 默认值      | 必填 | 说明                                               |
+| --------- | ------------------------ | ----------- | ---- | -------------------------------------------------- |
+| `icon`    | `React.ReactNode`        | –           | –    | 图标(antd `icon` 并集)。                           |
+| `variant` | `'primary' \| 'default'` | `"primary"` | –    | 视觉风格 — `primary` 主色填充;`default` 灰色轮廓。 |
+| `shape`   | `'circle' \| 'square'`   | `"circle"`  | –    | 形状 — `circle`(默认)圆形;`square` 方形圆角。      |
+| `badge`   | `React.ReactNode`        | –           | –    | 触发徽标(antd `badge` 并集) — 简短数字 / 字符。    |
+
+#### FloatButtonGroup
+
+| 名称     | 类型     | 默认值 | 必填 | 说明                 |
+| -------- | -------- | ------ | ---- | -------------------- |
+| `right`  | `number` | `24`   | –    | 距视口右侧距离(px)。 |
+| `bottom` | `number` | `24`   | –    | 距视口底部距离(px)。 |
+
+#### FloatButtonBackTop
+
+| 名称               | 类型     | 默认值 | 必填 | 说明                                   |
+| ------------------ | -------- | ------ | ---- | -------------------------------------- |
+| `visibilityHeight` | `number` | `200`  | –    | 滚动距离超过此值(px)时才显示回到顶部。 |
+
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add float-button` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
@@ -49,6 +72,7 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add lucide-react@^0.460.0
 ```
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/float-button/float-button.stories.tsx

@@ -14,7 +14,7 @@ const meta: Meta<typeof FloatButton> = {
     docs: {
       description: {
         component:
-          '悬浮按钮 — position: fixed 在右下角的强主张操作按钮(回到顶部 / 客服 / 新建)。配 FloatButtonGroup 堆叠多个,FloatButtonBackTop 是预置的"回到顶部"。等价 antd `FloatButton`(v5.0,替代旧 BackTop)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '悬浮按钮 — position: fixed 在右下角的强主张操作按钮（回到顶部 / 客服 / 新建）。配 FloatButtonGroup 堆叠多个，FloatButtonBackTop 是预置的“回到顶部”。等价 antd `FloatButton`（v5.0，替代旧 BackTop）。',
       },
     },
   },
@@ -62,7 +62,9 @@ export const BackTopReal: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
     <>
-      <div className="text-sm text-muted-foreground">向下滚动 200px 查看回到顶部按钮:</div>
+      <div className="text-sm text-muted-foreground">
+        向下滚动 200px 查看回到顶部按钮:
+      </div>
       <div className="mt-3 space-y-3">
         {Array.from({ length: 30 }).map((_, i) => (
           <div key={i} className="rounded-md border bg-muted/30 p-6">

package/src/components/float-button/float-button.tsx

@@ -62,7 +62,7 @@ const FloatButton = React.forwardRef<HTMLButtonElement, FloatButtonProps>(
     >
       {icon ?? children}
       {badge != null ? (
-        <span className="absolute -right-1 -top-1 flex h-5 min-w-[1.25rem] items-center justify-center rounded-full bg-destructive px-1 text-[10px] font-medium leading-none text-destructive-foreground">
+        <span className="absolute -right-1 -top-1 flex h-5 min-w-counter items-center justify-center rounded-full bg-destructive px-1 text-xxs font-medium leading-none text-destructive-foreground">
           {badge}
         </span>
       ) : null}

package/src/components/form/form.meta.md

@@ -1,13 +1,14 @@
 ---
 id: form
 name: Form
+displayName: 表单
 type: component
 category: form
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Form
+# Form 表单
 
 表单 — 基于 [`react-hook-form`](https://react-hook-form.com/),shadcn 标准 7 件套(`Form / FormField / FormItem / FormLabel / FormControl / FormDescription / FormMessage`)。
 **配合 [`zod`](https://zod.dev/) + `@hookform/resolvers/zod` 做 schema 校验**(行业惯例)。
@@ -26,12 +27,46 @@ package: "@teamix-evo/ui"
 
 ## Props
 
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。`Form` 是 `FormProvider` 别名,直接接受 `useForm()` 返回值的所有方法;不存在专门的 props 表 —下表代表 `FormItem` 的 props 作为 docs anchor,实际用法见 Examples。
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。`Form` 是 `FormProvider` 别名,直接接受 `useForm()` 返回值;下表按子组件分节列出各自的 Props。
 
 <!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `children` | `React.ReactNode` | – | – | 表单内容 — 通常是 `<form>` + `<FormField>` 列表。 |
+
+#### Form
+
+| 名称       | 类型              | 默认值 | 必填 | 说明                                              |
+| ---------- | ----------------- | ------ | ---- | ------------------------------------------------- |
+| `children` | `React.ReactNode` | –      | –    | 表单内容 — 通常是 `<form>` + `<FormField>` 列表。 |
+
+> `Form` 透传 `useForm()` 返回值的所有属性(`UseFormReturn`),作为 `FormProvider` 下发给子组件。
+
+#### FormField
+
+| 名称      | 类型                                                       | 默认值 | 必填 | 说明                                        |
+| --------- | ---------------------------------------------------------- | ------ | ---- | ------------------------------------------- |
+| `name`    | `FieldPath<TFieldValues>`                                  | –      | ✔    | 字段名称,对应 schema 中的 key。             |
+| `control` | `Control<TFieldValues>`                                    | –      | ✔    | `useForm()` 返回的 `control` 实例。         |
+| `render`  | `({ field, fieldState, formState }) => React.ReactElement` | –      | ✔    | 渲染函数,接收 field/fieldState 注入到控件。 |
+
+#### FormItem
+
+> 单个表单字段容器,生成稳定 id 供 Label/Description/Message 关联。无自定义 props,仅透传 `HTMLDivElement` 属性。
+
+#### FormLabel
+
+> 扩展自 `Label` 组件,自动通过 `useFormField()` 关联 `htmlFor`,校验失败时自动变红。支持 `Label` 的所有 props(`required` / `disabled`)。
+
+#### FormControl
+
+> Slot 包装器,自动注入 `id` / `aria-describedby` / `aria-invalid` 到子控件。无自定义 props。
+
+#### FormDescription
+
+> 辅助说明文本(`text-xs text-muted-foreground`)。无自定义 props,仅透传 `HTMLParagraphElement` 属性。
+
+#### FormMessage
+
+> 错误消息显示,自动从 `fieldState.error` 读取。无自定义 props,仅透传 `HTMLParagraphElement` 属性。
+
 <!-- auto:props:end -->
 
 ## 依赖
@@ -39,13 +74,14 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
 
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add form` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry   | 类型      | 描述                                                                                  |
+| ------- | --------- | ------------------------------------------------------------------------------------- |
+| `cn`    | util      | Tailwind className 合并工具(clsx + tailwind-merge)                                    |
 | `label` | component | 表单字段标签 — Radix Label 包装,补 antd Form.Item 风格的 required / disabled 显式视觉 |
 
 ### npm 依赖
@@ -55,9 +91,8 @@ package: "@teamix-evo/ui"
 ```bash
 pnpm add react-hook-form@^7.50.0 @hookform/resolvers@^3.0.0 zod@^3.22.0 @radix-ui/react-label@^2.1.0 @radix-ui/react-slot@^1.1.0
 ```
-<!-- auto:deps:end -->
 
-> 完整子组件:`Form` / `FormField` / `FormItem` / `FormLabel` / `FormControl` / `FormDescription` / `FormMessage`,配合 `useFormField()` hook。
+<!-- auto:deps:end -->
 
 ## AI 生成纪律
 
@@ -76,8 +111,13 @@ import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
 import {
-  Form, FormField, FormItem, FormLabel, FormControl,
-  FormDescription, FormMessage,
+  Form,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormDescription,
+  FormMessage,
 } from '@/components/ui/form';
 import { Input } from '@/components/ui/input';
 import { Button } from '@/components/ui/button';
@@ -95,7 +135,10 @@ function MyForm() {
 
   return (
     <Form {...form}>
-      <form onSubmit={form.handleSubmit((v) => console.log(v))} className="space-y-4">
+      <form
+        onSubmit={form.handleSubmit((v) => console.log(v))}
+        className="space-y-4"
+      >
         <FormField
           control={form.control}
           name="username"

package/src/components/form/form.stories.tsx

@@ -23,7 +23,7 @@ const meta: Meta<typeof Form> = {
     docs: {
       description: {
         component:
-          '表单 — `react-hook-form` + `zod` 校验 + 语义化字段组件(`FormItem` / `FormLabel` / `FormControl` / `FormDescription` / `FormMessage`)。对齐 shadcn Form 的可组合范式；对比 antd Form 用 `Field` 命令式注册的方式，本组件采用 RHF 的声明式 controller，类型安全且性能更好。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '表单 — `react-hook-form` + `zod` 校验 + 语义化字段组件（`FormItem` / `FormLabel` / `FormControl` / `FormDescription` / `FormMessage`）。对齐 shadcn Form 的可组合范式；对比 antd Form 用 `Field` 命令式注册的方式，本组件采用 RHF 的声明式 controller，类型安全且性能更好。',
       },
     },
   },

package/src/components/grid/grid.meta.md

@@ -1,13 +1,14 @@
 ---
 id: grid
 name: Grid
+displayName: 栅格
 type: component
 category: layout
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Grid (Row / Col)
+# Grid (Row / Col) 栅格
 
 24 栅格系统 — antd 独有补足。**等价 antd `Row` + `Col`**:基于 CSS Grid 的 24 列容器,支持 `span` / `offset` / `order` / `flex` / `gutter` / `justify` / `align` 等核心 API,中后台表单 / 看板布局基石。
 
@@ -23,22 +24,46 @@ package: "@teamix-evo/ui"
 - inline 间距小集合 → `Space`
 - 不固定列数的卡片墙 → 直接用 Tailwind `grid-cols-N` 或 `Item` 配 `ItemGroup`
 
+## Props
+
 <!-- auto:props:begin -->
-_(组件无 `<Name>Props` interface — props 详见 [`grid.tsx`](./grid.tsx))_
+
+#### Row
+
+| 名称      | 类型                                                                | 默认值    | 必填 | 说明                                                                         |
+| --------- | ------------------------------------------------------------------- | --------- | ---- | ---------------------------------------------------------------------------- |
+| `gutter`  | `number \| [number, number]`                                        | `0`       | –    | 子项间距 — number 等价 `[n, n]`;`[h, v]` 分别控制水平 / 垂直(实际值 n×4px)。 |
+| `justify` | `'start' \| 'end' \| 'center' \| 'between' \| 'around' \| 'evenly'` | `"start"` | –    | 水平排列(antd `justify` 并集)。                                              |
+| `align`   | `'top' \| 'middle' \| 'bottom' \| 'stretch'`                        | `"top"`   | –    | 垂直对齐(antd `align` 并集)。                                                |
+| `wrap`    | `boolean`                                                           | `true`    | –    | 是否允许换行(antd `wrap` 并集)。                                             |
+
+#### Col
+
+| 名称     | 类型      | 默认值  | 必填 | 说明                                                          |
+| -------- | --------- | ------- | ---- | ------------------------------------------------------------- |
+| `span`   | `number`  | `24`    | –    | 占用栅格数(1~24,antd `span` 并集) — 0 表示隐藏。              |
+| `offset` | `number`  | `0`     | –    | 左侧偏移栅格数(antd `offset` 并集)。                          |
+| `order`  | `number`  | –       | –    | 顺序(antd `order` 并集) — 用于响应式 / a11y 顺序变更场景。    |
+| `flex`   | `boolean` | `false` | –    | 自动撑满剩余空间(antd `flex="auto"` 等价) — 设置后忽略 span。 |
+
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
+
 ### 同库依赖
 
 > `teamix-evo ui add grid` 时,以下 entry 会被自动连带安装(无需手动 add)。
 
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| Entry | 类型 | 描述                                               |
+| ----- | ---- | -------------------------------------------------- |
+| `cn`  | util | Tailwind className 合并工具(clsx + tailwind-merge) |
 
 ### npm 依赖
 
 _无 — 本组件不依赖任何 npm 包。_
+
 <!-- auto:deps:end -->
 
 ## AI 生成纪律

package/src/components/grid/grid.stories.tsx

@@ -9,7 +9,7 @@ const meta: Meta<typeof Row> = {
     docs: {
       description: {
         component:
-          '24 栅格 — 基于 CSS Grid 的 24 列容器(antd Row + Col)。中后台表单 / 看板布局基石,支持 span / offset / order / flex / gutter / justify / align。响应式建议直接用 Tailwind 断点 className(`md:col-span-12`),更原生可控。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '24 栅格 — 基于 CSS Grid 的 24 列容器(antd Row + Col)。中后台表单 / 看板布局基石,支持 span / offset / order / flex / gutter / justify / align。响应式建议直接用 Tailwind 断点 className。',
       },
     },
   },
@@ -19,7 +19,9 @@ export default meta;
 type Story = StoryObj<typeof Row>;
 
 const Box = ({ children }: { children: React.ReactNode }) => (
-  <div className="rounded-md bg-muted px-3 py-4 text-center text-sm">{children}</div>
+  <div className="rounded-md bg-muted px-3 py-4 text-center text-sm">
+    {children}
+  </div>
 );
 
 export const Playground: Story = {