@teamix-evo/ui 0.4.0 → 0.5.0

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

@@ -1,153 +0,0 @@
----
-id: form
-name: Form
-displayName: 表单
-type: component
-category: data-entry
-since: 0.1.0
-package: '@teamix-evo/ui'
----
-
-# 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 校验**(行业惯例)。
-
-## When to use
-
-- 任何表单(登录、注册、设置、复杂数据填报)
-- 跨字段联动 / 条件校验
-- 异步校验(用户名查重)
-
-## When NOT to use
-
-- 单字段查询框 → `Input + onSubmit`
-- 一次性确认 → `AlertDialog` 单按钮
-- 无校验的"轻量提交" → 直接 `<form>` + 状态变量
-
-## Props
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。`Form` 是 `FormProvider` 别名,直接接受 `useForm()` 返回值;下表按子组件分节列出各自的 Props。
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `children` | `React.ReactNode` | – | – | 表单内容 — 通常是 `<form>` + `<FormField>` 列表。 |
-<!-- auto:props:end -->
-
-## 依赖
-
-> 以下表格由 `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) |
-| `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-slot@^1.1.0
-```
-<!-- auto:deps:end -->
-
-## 子组件
-
-除 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
-- **必填标记 `*` 总是后置**：`<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
-
-```tsx
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
-import {
-  Form,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormControl,
-  FormDescription,
-  FormMessage,
-} from '@/components/ui/form';
-import { Input } from '@/components/ui/input';
-import { Button } from '@/components/ui/button';
-
-const schema = z.object({
-  username: z.string().min(2, '至少 2 个字符'),
-  email: z.string().email('请输入有效邮箱'),
-});
-
-function MyForm() {
-  const form = useForm<z.infer<typeof schema>>({
-    resolver: zodResolver(schema),
-    defaultValues: { username: '', email: '' },
-  });
-
-  return (
-    <Form {...form}>
-      <form
-        onSubmit={form.handleSubmit((v) => console.log(v))}
-        className="space-y-4"
-      >
-        <FormField
-          control={form.control}
-          name="username"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel required>用户名</FormLabel>
-              <FormControl>
-                <Input placeholder="lyca" {...field} />
-              </FormControl>
-              <FormDescription>2~16 个字符。</FormDescription>
-              <FormMessage />
-            </FormItem>
-          )}
-        />
-        <FormField
-          control={form.control}
-          name="email"
-          render={({ field }) => (
-            <FormItem>
-              <FormLabel required>邮箱</FormLabel>
-              <FormControl>
-                <Input type="email" placeholder="you@example.com" {...field} />
-              </FormControl>
-              <FormMessage />
-            </FormItem>
-          )}
-        />
-        <Button type="submit">提交</Button>
-      </form>
-    </Form>
-  );
-}
-```

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

@@ -1,472 +0,0 @@
-import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react-vite';
-import { useForm } from 'react-hook-form';
-// `as never` casts on zodResolver(...) below: zod 3.25.x ships zod v4
-// internals while @hookform/resolvers@3.x still types Resolver against
-// zod v3 Schema. Remove when upgrading to @hookform/resolvers v4.
-import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
-import {
-  Form,
-  FormField,
-  FormItem,
-  FormLabel,
-  FormControl,
-  FormDescription,
-  FormMessage,
-  FormSection,
-  FormActions,
-} from './form';
-import { Input } from '@/components/input/input';
-import { Button } from '@/components/button/button';
-
-const meta: Meta<typeof Form> = {
-  title: '数据录入 · Data Entry/Form',
-  component: Form,
-  tags: ['autodocs'],
-  parameters: {
-    docs: {
-      description: {
-        component:
-          '表单 — `react-hook-form` + `zod` 校验 + 语义化字段组件（`FormItem` / `FormLabel` / `FormControl` / `FormDescription` / `FormMessage`）。对齐 shadcn Form 的可组合范式；对比 antd Form 用 `Field` 命令式注册的方式，本组件采用 RHF 的声明式 controller，类型安全且性能更好。`<FormLabel required>` 红色 `*` **后置**在文字和 tooltip icon 右侧（顺序为 `文字 ⓘ *`），对齐设计规范。',
-      },
-    },
-  },
-};
-
-export default meta;
-type Story = StoryObj<typeof Form>;
-
-const schema = z.object({
-  username: z.string().min(2, '至少 2 个字符').max(16, '最多 16 个字符'),
-  email: z.string().email('请输入有效邮箱'),
-  bio: z.string().max(140, '不超过 140 字').optional(),
-});
-
-export const ZodValidated: Story = {
-  parameters: { layout: 'centered' },
-  render: () => {
-    const form = useForm<z.infer<typeof schema>>({
-      resolver: zodResolver(schema as never),
-      defaultValues: { username: '', email: '', bio: '' },
-    });
-    const [submitted, setSubmitted] = React.useState<unknown>(null);
-
-    return (
-      <div className="w-80">
-        <Form {...form}>
-          <form
-            onSubmit={form.handleSubmit((v) => setSubmitted(v))}
-            className="space-y-4"
-          >
-            <FormField
-              control={form.control}
-              name="username"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel required>用户名</FormLabel>
-                  <FormControl>
-                    <Input placeholder="lyca" {...field} />
-                  </FormControl>
-                  <FormDescription>2~16 个字符。</FormDescription>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-            <FormField
-              control={form.control}
-              name="email"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel required>邮箱</FormLabel>
-                  <FormControl>
-                    <Input
-                      type="email"
-                      placeholder="you@example.com"
-                      {...field}
-                    />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-            <FormField
-              control={form.control}
-              name="bio"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>个人简介</FormLabel>
-                  <FormControl>
-                    <Input placeholder="一句话介绍自己" {...field} />
-                  </FormControl>
-                  <FormDescription>不超过 140 字。</FormDescription>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-            <div className="flex gap-2">
-              <Button type="submit">提交</Button>
-              <Button
-                type="button"
-                variant="outline"
-                onClick={() => form.reset()}
-              >
-                重置
-              </Button>
-            </div>
-          </form>
-        </Form>
-        {submitted ? (
-          <pre className="mt-4 rounded-md bg-muted p-3 text-xs">
-            {JSON.stringify(submitted, null, 2)}
-          </pre>
-        ) : null}
-      </div>
-    );
-  },
-};
-
-// ─── WithSections ─────────────────────────────────────────────────────────────
-
-const sectionsSchema = z.object({
-  name: z.string().min(2, '至少 2 个字符'),
-  email: z.string().email('请输入有效邮箱'),
-  phone: z.string().min(6, '至少 6 位'),
-  company: z.string().optional(),
-  role: z.string().optional(),
-});
-
-export const WithSections: Story = {
-  parameters: { layout: 'centered' },
-  render: () => {
-    const form = useForm<z.infer<typeof sectionsSchema>>({
-      resolver: zodResolver(sectionsSchema as never),
-      defaultValues: { name: '', email: '', phone: '', company: '', role: '' },
-    });
-    const [submitted, setSubmitted] = React.useState<unknown>(null);
-
-    return (
-      <div className="w-[480px]">
-        <Form {...form}>
-          <form
-            onSubmit={form.handleSubmit((v) => setSubmitted(v))}
-            className="flex flex-col gap-8"
-          >
-            <FormSection title="基本信息">
-              <FormField
-                control={form.control}
-                name="name"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel required>姓名</FormLabel>
-                    <FormControl>
-                      <Input placeholder="张三" {...field} />
-                    </FormControl>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-              <FormField
-                control={form.control}
-                name="email"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel required>邮箱</FormLabel>
-                    <FormControl>
-                      <Input type="email" placeholder="you@example.com" {...field} />
-                    </FormControl>
-                    <FormDescription>用于接收通知。</FormDescription>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-              <FormField
-                control={form.control}
-                name="phone"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel required>手机</FormLabel>
-                    <FormControl>
-                      <Input placeholder="13800000000" {...field} />
-                    </FormControl>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-            </FormSection>
-
-            <FormSection title="工作信息">
-              <FormField
-                control={form.control}
-                name="company"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel>公司</FormLabel>
-                    <FormControl>
-                      <Input placeholder="Acme Inc." {...field} />
-                    </FormControl>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-              <FormField
-                control={form.control}
-                name="role"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel>职位</FormLabel>
-                    <FormControl>
-                      <Input placeholder="Engineer" {...field} />
-                    </FormControl>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-            </FormSection>
-
-            <FormActions>
-              <Button
-                type="button"
-                variant="outline"
-                onClick={() => form.reset()}
-              >
-                重置
-              </Button>
-              <Button type="submit">提交</Button>
-            </FormActions>
-          </form>
-        </Form>
-        {submitted ? (
-          <pre className="mt-4 rounded-md bg-muted p-3 text-xs">
-            {JSON.stringify(submitted, null, 2)}
-          </pre>
-        ) : null}
-      </div>
-    );
-  },
-};
-
-// ─── MultiColumn ─────────────────────────────────────────────────────────────
-
-const multiColumnSchema = z.object({
-  firstName: z.string().min(1, '必填'),
-  lastName: z.string().min(1, '必填'),
-  province: z.string().min(1, '必填'),
-  city: z.string().min(1, '必填'),
-  district: z.string().min(1, '必填'),
-});
-
-export const MultiColumn: Story = {
-  parameters: { layout: 'centered' },
-  render: () => {
-    const form = useForm<z.infer<typeof multiColumnSchema>>({
-      resolver: zodResolver(multiColumnSchema as never),
-      defaultValues: {
-        firstName: '',
-        lastName: '',
-        province: '',
-        city: '',
-        district: '',
-      },
-    });
-    const [submitted, setSubmitted] = React.useState<unknown>(null);
-
-    return (
-      <div className="w-[640px]">
-        <Form {...form}>
-          <form
-            onSubmit={form.handleSubmit((v) => setSubmitted(v))}
-            className="flex flex-col gap-8"
-          >
-            <FormSection title="姓名（两栏）" columns={2}>
-              <FormField
-                control={form.control}
-                name="firstName"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel required>名</FormLabel>
-                    <FormControl>
-                      <Input placeholder="三" {...field} />
-                    </FormControl>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-              <FormField
-                control={form.control}
-                name="lastName"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel required>姓</FormLabel>
-                    <FormControl>
-                      <Input placeholder="张" {...field} />
-                    </FormControl>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-            </FormSection>
-
-            <FormSection title="地址（三栏）" columns={3}>
-              <FormField
-                control={form.control}
-                name="province"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel required>省份</FormLabel>
-                    <FormControl>
-                      <Input placeholder="浙江" {...field} />
-                    </FormControl>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-              <FormField
-                control={form.control}
-                name="city"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel required>城市</FormLabel>
-                    <FormControl>
-                      <Input placeholder="杭州" {...field} />
-                    </FormControl>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-              <FormField
-                control={form.control}
-                name="district"
-                render={({ field }) => (
-                  <FormItem>
-                    <FormLabel required>区县</FormLabel>
-                    <FormControl>
-                      <Input placeholder="西湖区" {...field} />
-                    </FormControl>
-                    <FormMessage />
-                  </FormItem>
-                )}
-              />
-            </FormSection>
-
-            <FormActions>
-              <Button type="submit">提交</Button>
-            </FormActions>
-          </form>
-        </Form>
-        {submitted ? (
-          <pre className="mt-4 rounded-md bg-muted p-3 text-xs">
-            {JSON.stringify(submitted, null, 2)}
-          </pre>
-        ) : null}
-      </div>
-    );
-  },
-};
-
-// ─── StickyActions ───────────────────────────────────────────────────────────
-const stickySchema = z.object({
-  title: z.string().min(1, '必填'),
-  description: z.string().optional(),
-  remark1: z.string().optional(),
-  remark2: z.string().optional(),
-  remark3: z.string().optional(),
-  remark4: z.string().optional(),
-  remark5: z.string().optional(),
-  remark6: z.string().optional(),
-});
-
-export const StickyActions: Story = {
-  parameters: { layout: 'centered' },
-  render: () => {
-    const form = useForm<z.infer<typeof stickySchema>>({
-      resolver: zodResolver(stickySchema as never),
-      defaultValues: {
-        title: '',
-        description: '',
-        remark1: '',
-        remark2: '',
-        remark3: '',
-        remark4: '',
-        remark5: '',
-        remark6: '',
-      },
-    });
-    const [submitted, setSubmitted] = React.useState<unknown>(null);
-
-    return (
-      <div className="flex h-[480px] w-[420px] flex-col overflow-hidden rounded-md border border-border">
-        <Form {...form}>
-          <form
-            onSubmit={form.handleSubmit((v) => setSubmitted(v))}
-            className="flex h-full flex-col"
-          >
-            <div className="flex-1 overflow-y-auto p-4">
-              <FormSection title="表单内容">
-                <FormField
-                  control={form.control}
-                  name="title"
-                  render={({ field }) => (
-                    <FormItem>
-                      <FormLabel required>标题</FormLabel>
-                      <FormControl>
-                        <Input placeholder="请输入标题" {...field} />
-                      </FormControl>
-                      <FormMessage />
-                    </FormItem>
-                  )}
-                />
-                <FormField
-                  control={form.control}
-                  name="description"
-                  render={({ field }) => (
-                    <FormItem>
-                      <FormLabel>描述</FormLabel>
-                      <FormControl>
-                        <Input placeholder="请输入描述" {...field} />
-                      </FormControl>
-                      <FormMessage />
-                    </FormItem>
-                  )}
-                />
-                {(['remark1', 'remark2', 'remark3', 'remark4', 'remark5', 'remark6'] as const).map(
-                  (n, i) => (
-                    <FormField
-                      key={n}
-                      control={form.control}
-                      name={n}
-                      render={({ field }) => (
-                        <FormItem>
-                          <FormLabel>备注 {i + 1}</FormLabel>
-                          <FormControl>
-                            <Input placeholder={`备注 ${i + 1}`} {...field} />
-                          </FormControl>
-                          <FormMessage />
-                        </FormItem>
-                      )}
-                    />
-                  ),
-                )}
-              </FormSection>
-            </div>
-            <FormActions position="sticky" className="px-4">
-              <Button
-                type="button"
-                variant="outline"
-                onClick={() => form.reset()}
-              >
-                重置
-              </Button>
-              <Button type="submit">提交</Button>
-            </FormActions>
-          </form>
-        </Form>
-        {submitted ? (
-          <pre className="m-4 rounded-md bg-muted p-3 text-xs">
-            {JSON.stringify(submitted, null, 2)}
-          </pre>
-        ) : null}
-      </div>
-    );
-  },
-};