@teamix-evo/ui 0.1.1 → 0.3.0

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

@@ -1,16 +1,17 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Flex } from './flex';
 import { Button } from '@/components/button/button';
+import { Separator } from '@/components/separator/separator';
 
 const meta: Meta<typeof Flex> = {
-  title: '布局与容器 · Layout/Flex',
+  title: '布局 · Layout/Flex',
   component: Flex,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          'Flex 布局容器 — 把 Tailwind flex 的常用配置(对齐 / 间距 / 换行 / 方向 / 渲染元素)收敛为枚举。等价 antd `Flex`(v5.10+),与 Space 互补:Flex 偏完整布局容器,Space 偏 inline 小集合。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          'Flex 弹性布局 —— 以架构者语言描述一维 / 二维的子项排列。**等价 antd `Flex`**(v5.10+) **∪ antd `Space`**——覆盖完整布局容器(页头 / 卡片 / 整页)与 inline 小集合(按钮组 / tag 组 / 链接组)两类场景:`direction`(row/column/-reverse) / `gap`(none→xl 6 档走 design 间距刻度) / `align` / `justify` / `wrap` / `inline`(等价 antd `Space`) / `as`(语义标签 section/header/main…) / `split`(等价 antd `Space.split`,在相邻子项间插入分隔节点)。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
       },
     },
   },
@@ -19,7 +20,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'],
@@ -45,14 +49,14 @@ export default meta;
 type Story = StoryObj<typeof Flex>;
 
 const swatch = (label: string) => (
-  <div className="grid h-12 w-20 place-items-center rounded-md border bg-muted text-xs">
+  <div className="grid h-12 w-20 place-items-center rounded-md border border-border bg-muted text-xs">
     {label}
   </div>
 );
 
 export const Playground: Story = {
   render: (args) => (
-    <Flex {...args} className="min-h-32 rounded-md border bg-card p-4">
+    <Flex {...args} className="min-h-32 rounded-md border border-border bg-card p-4">
       {swatch('A')}
       {swatch('B')}
       {swatch('C')}
@@ -63,12 +67,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 border-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 +93,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 border-border bg-card p-6"
+    >
       <span className="text-lg font-semibold">标题</span>
       <span className="text-sm text-muted-foreground">这是一段描述文字</span>
       <Button>操作</Button>
@@ -89,24 +108,92 @@ export const ColumnStack: Story = {
 export const Toolbar: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <Flex justify="end" gap="sm" className="rounded-md border bg-card p-3">
+    <Flex justify="end" gap="sm" className="rounded-md border border-border bg-card p-3">
       <Button variant="outline">取消</Button>
       <Button>提交</Button>
     </Flex>
   ),
 };
 
+/**
+ * inline 小集合——等价 antd `Space`。加 `inline` + 小 `gap` + `align="center"` 即可覆盖原 Space 场景。
+ */
+export const InlineGroup: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Flex inline gap="sm" align="center">
+      <Button variant="outline">取消</Button>
+      <Button>确定</Button>
+      <Button variant="ghost">更多</Button>
+    </Flex>
+  ),
+};
+
+/**
+ * 链接组带分隔——等价 antd `Space.split`。`split` 接受任意 ReactNode,常用 `<Separator orientation="vertical" />`。
+ */
+export const WithSplit: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Flex
+      inline
+      gap="sm"
+      align="center"
+      split={<Separator orientation="vertical" className="h-4" />}
+    >
+      <a href="#" className="text-sm text-primary hover:underline">
+        查看
+      </a>
+      <a href="#" className="text-sm text-primary hover:underline">
+        编辑
+      </a>
+      <a href="#" className="text-sm text-destructive hover:underline">
+        删除
+      </a>
+    </Flex>
+  ),
+};
+
+/**
+ * 主轴分几——表单行 “总计 / 金额”。等价 antd `Space justify="between"`。
+ */
+export const Between: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="w-80 rounded-md border border-border p-3">
+      <Flex justify="between" align="center">
+        <span className="text-sm text-muted-foreground">总计</span>
+        <span className="text-lg font-semibold">¥ 1,299</span>
+      </Flex>
+    </div>
+  ),
+};
+
 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>
-        ),
-      )}
+    <Flex wrap gap="sm" className="w-96 rounded-md border border-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 border-border bg-muted px-2 py-0.5 text-xs"
+        >
+          {t}
+        </span>
+      ))}
     </Flex>
   ),
 };

package/src/components/flex/flex.tsx

@@ -67,13 +67,21 @@ export interface FlexProps extends React.HTMLAttributes<HTMLDivElement> {
     React.JSX.IntrinsicElements,
     'div' | 'section' | 'header' | 'footer' | 'aside' | 'main' | 'nav' | 'article'
   >;
+  /**
+   * 子项之间的分隔节点(antd `Space.split` 并集) — 常用 `<Separator orientation="vertical" />`、`'·'`、`'|'`。
+   * 设置后会在每两个相邻子项之间插入该节点。
+   */
+  split?: React.ReactNode;
 }
 
 /**
- * Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+),提供 Tailwind flex 的语义封装,
- * 把常用对齐 / 间距 / 换行 / 方向 / 渲染元素收敛为枚举,避免散落的 className 反复手写。
+ * Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+) ∪ **antd `Space`**(`split`)。
+ * 把 Tailwind flex 的常用对齐 / 间距 / 换行 / 方向 / 渲染元素 / 分隔节点收敛为枚举,避免散落的 className 反复手写。
  *
- * 与 `Space` 区别:Flex 偏向**完整布局容器**(页头、卡片体、整页),Space 偏向 inline 小集合。
+ * 用法约定:
+ * - 完整布局容器(页头、卡片体、整页): `<Flex as="header" justify="between" align="center" />`
+ * - inline 小集合(按钮组、tag 组、链接组): `<Flex inline gap="sm" align="center" />`(等价 antd `Space`)
+ * - 链接组带分隔: `<Flex inline gap="sm" split={<Separator orientation="vertical" />} />`
  */
 const Flex = React.forwardRef<HTMLDivElement, FlexProps>(
   (
@@ -85,7 +93,9 @@ const Flex = React.forwardRef<HTMLDivElement, FlexProps>(
       wrap = false,
       inline = false,
       as = 'div',
+      split,
       className,
+      children,
       ...props
     },
     ref,
@@ -100,6 +110,17 @@ const Flex = React.forwardRef<HTMLDivElement, FlexProps>(
             ? 'flex-row-reverse'
             : 'flex-col-reverse';
 
+    const content = split
+      ? React.Children.toArray(children)
+          .filter(Boolean)
+          .map((child, i) => (
+            <React.Fragment key={i}>
+              {i > 0 ? split : null}
+              {child}
+            </React.Fragment>
+          ))
+      : children;
+
     return (
       <Tag
         ref={ref}
@@ -113,7 +134,9 @@ const Flex = React.forwardRef<HTMLDivElement, FlexProps>(
           className,
         )}
         {...props}
-      />
+      >
+        {content}
+      </Tag>
     );
   },
 );

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

@@ -2,12 +2,13 @@
 id: float-button
 name: FloatButton
 type: component
-category: navigation
+category: deprecated
 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,6 +25,8 @@ package: "@teamix-evo/ui"
 - 列表行末操作 → 普通 `Button` / `DropdownMenu`
 - 多个无关操作堆在右下:容易遮挡内容,> 3 个 FloatButton 时换 SpeedDial 模式
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -33,6 +36,8 @@ package: "@teamix-evo/ui"
 | `badge` | `React.ReactNode` | – | – | 触发徽标(antd `badge` 并集) — 简短数字 / 字符。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 

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

@@ -1,4 +1,4 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { MessageCircle, Plus } from 'lucide-react';
 import {
   FloatButton,
@@ -7,14 +7,14 @@ import {
 } from './float-button';
 
 const meta: Meta<typeof FloatButton> = {
-  title: '导航 · Navigation/FloatButton',
+  title: '废弃 · Deprecated/FloatButton',
   component: FloatButton,
   tags: ['autodocs'],
   parameters: {
     docs: {
       description: {
         component:
-          '悬浮按钮 — position: fixed 在右下角的强主张操作按钮(回到顶部 / 客服 / 新建)。配 FloatButtonGroup 堆叠多个,FloatButtonBackTop 是预置的"回到顶部"。等价 antd `FloatButton`(v5.0,替代旧 BackTop)。视觉走 OpenTrek tokens,所有样式来自 `@teamix-evo/design`,无 mock。',
+          '⚠️ **已废弃** — 仅 Storybook 留档,不通过 manifest 对外发布。\n\n悬浮按钮 — position: fixed 在右下角的强主张操作按钮（回到顶部 / 客服 / 新建）。配 FloatButtonGroup 堆叠多个，FloatButtonBackTop 是预置的“回到顶部”。等价 antd `FloatButton`（v5.0，替代旧 BackTop）。',
       },
     },
   },
@@ -26,7 +26,7 @@ type Story = StoryObj<typeof FloatButton>;
 export const Playground: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="relative h-72 overflow-hidden rounded-md border">
+    <div className="relative h-72 overflow-hidden rounded-md border border-border">
       <div className="p-4 text-sm text-muted-foreground">
         ← 右下角是 FloatButton 演示
       </div>
@@ -40,7 +40,7 @@ export const Playground: Story = {
 export const Group: Story = {
   parameters: { controls: { disable: true } },
   render: () => (
-    <div className="relative h-96 overflow-hidden rounded-md border">
+    <div className="relative h-96 overflow-hidden rounded-md border border-border">
       <div className="p-4 text-sm text-muted-foreground">右下角浮动按钮组</div>
       <div className="absolute bottom-6 right-6 flex flex-col items-end gap-3">
         <FloatButton
@@ -62,10 +62,12 @@ 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">
+          <div key={i} className="rounded-md border border-border bg-muted/30 p-6">
             占位段落 {i + 1}
           </div>
         ))}

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
+category: data-entry
 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,7 +27,7 @@ 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 -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
@@ -46,28 +47,41 @@ package: "@teamix-evo/ui"
 | Entry | 类型 | 描述 |
 | --- | --- | --- |
 | `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-| `label` | component | 表单字段标签 — Radix Label 包装,补 antd Form.Item 风格的 required / disabled 显式视觉 |
+| `field` | component | 通用表单字段抽象 — shadcn 2025-10 新增。Field / FieldLabel / FieldDescription / FieldError / FieldGroup / FieldSet / FieldLegend 7 个语义槽,跟任何状态管理(Server Actions / RHF / TanStack Form)都能搭,与 form 共存 |
 
 ### npm 依赖
 
 > 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
 
 ```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
+pnpm add react-hook-form@^7.50.0 @hookform/resolvers@^3.0.0 zod@^3.22.0 @radix-ui/react-slot@^1.1.0
 ```
 <!-- auto:deps:end -->
 
-> 完整子组件:`Form` / `FormField` / `FormItem` / `FormLabel` / `FormControl` / `FormDescription` / `FormMessage`,配合 `useFormField()` hook。
+## 子组件
+
+除 shadcn 7 件套（`Form / FormField / FormItem / FormLabel / FormControl / FormDescription / FormMessage`）外，本包补两个表单骨架子组件：
+
+- **`FormSection`**：表单分组容器，支持 `title`（组标题，14px medium）和 `columns`（`1 \| 2 \| 3 \| 4` 多栏 grid）。代替手写 h3 + Row/Col。
+- **`FormActions`**：表单操作按钮容器，支持 `position`（`'inline'` / `'sticky'`）、`align`（`'start'` / `'end'`）和 `alignWithInput`（与输入域基线对齐，避免按钮与 label 列重叠）。
+
+> **实现共享**：`FormSection` / `FormActions` 是 Field 包同名组件的 re-export 别名（一处实现，规范变更只改一处）。Props 与行为完全等同 `FieldSection` / `FieldActions`，详见 [`field.meta.md`](../field/field.meta.md)。
 
 ## AI 生成纪律
 
-- **`Form` 必包 `useForm()`**:`<Form {...form}>...</Form>`,把整个 form instance 散开传入(FormProvider 期望)
-- **每个字段必有 `<FormField name="..." control={form.control} render={({ field }) => <FormItem>...</FormItem>} />`**:不要直接渲染 input 不走 Field,会失去校验关联
-- **`<FormControl>` 只放真正的输入控件**:input / textarea / Select / Checkbox 等;Slot 模式自动注入 id / aria-describedby / aria-invalid
-- **错误消息走 `<FormMessage />`**:不要手写 `{errors.x?.message}` — FormMessage 自动连接 fieldState
-- **schema 优先**:用 zod 写 schema → `useForm({ resolver: zodResolver(schema) })`;校验逻辑集中在 schema,不要散在 input 上
-- **提交后保留状态**:`form.reset()` 重置;**不要**手动清空每个字段
-- **不要嵌套 Form**:嵌套会破坏 React Context
+- **`Form` 必包 `useForm()`**：`<Form {...form}>...</Form>`，把整个 form instance 散开传入（FormProvider 期望）
+- **每个字段必有 `<FormField name="..." control={form.control} render={({ field }) => <FormItem>...</FormItem>} />`**：不要直接渲染 input 不走 Field，会失去校验关联
+- **`<FormControl>` 只放真正的输入控件**：input / textarea / Select / Checkbox 等；Slot 模式自动注入 id / aria-describedby / aria-invalid
+- **错误消息走 `<FormMessage />`**：不要手写 `{errors.x?.message}` — FormMessage 自动连接 fieldState
+- **必填标记 `*` 总是后置**：`<FormLabel required>` 由底层 `Label` 组件在文字与 tooltip icon **后**渲染红色 `*`（顺序为 `文字 ⓘ *`），对齐设计规范；不要手写 `<FormLabel>邮箱 *</FormLabel>` 或 `<FormLabel>* 邮箱</FormLabel>`。同时记得在 schema 里 `z.string().min(1)` 或控件上 `aria-required="true"`。
+- **schema 优先**：用 zod 写 schema → `useForm({ resolver: zodResolver(schema) })`；校验逻辑集中在 schema，不要散在 input 上
+- **提交后保留状态**：`form.reset()` 重置；**不要**手动清空每个字段
+- **不要嵌套 Form**：嵌套会破坏 React Context
+- ✅ 复杂表单必须用 `FormSection` 分组（组标题用 `title` prop，不要手写 `<h3>`）
+- ✅ 多栏布局用 `FormSection columns={N}`（不要手写 `Row`/`Col` 或 `grid grid-cols-N`）
+- ✅ 表单提交 / 取消按钮必须用 `FormActions`
+- ✅ 多个 `FormSection` 的父容器必须用 `gap-8`（32px 组间距）
+- ✅ 错误信息（`FormMessage`）紧贴 input，不要额外加 `mt-*` 或包裹 `<div>`
 
 ## Examples
 
@@ -76,8 +90,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 +114,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"