@teamix-evo/ui 0.1.1 → 0.3.0

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

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { useForm } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
 import { z } from 'zod';
@@ -11,19 +11,21 @@ import {
   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: '表单与输入 · Form/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，类型安全且性能更好。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+          '表单 — `react-hook-form` + `zod` 校验 + 语义化字段组件（`FormItem` / `FormLabel` / `FormControl` / `FormDescription` / `FormMessage`）。对齐 shadcn Form 的可组合范式；对比 antd Form 用 `Field` 命令式注册的方式，本组件采用 RHF 的声明式 controller，类型安全且性能更好。`<FormLabel required>` 红色 `*` **后置**在文字和 tooltip icon 右侧（顺序为 `文字 ⓘ *`），对齐设计规范。',
       },
     },
   },
@@ -120,3 +122,348 @@ export const ZodValidated: Story = {
     );
   },
 };
+
+// ─── 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),
+      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),
+      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),
+      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>
+    );
+  },
+};

package/src/components/form/form.tsx

@@ -1,5 +1,4 @@
 import * as React from 'react';
-import * as LabelPrimitive from '@radix-ui/react-label';
 import { Slot } from '@radix-ui/react-slot';
 import {
   Controller,
@@ -12,7 +11,17 @@ import {
 } from 'react-hook-form';
 
 import { cn } from '@/utils/cn';
-import { Label } from '@/components/label/label';
+import {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldSection,
+  FieldActions,
+  type FieldProps,
+  type FieldLabelProps,
+  type FieldSectionProps,
+  type FieldActionsProps,
+} from '@/components/field/field';
 
 /**
  * `Form` props — 即 `useForm()` 返回值(`UseFormReturn<TFieldValues>`) 的全部方法,
@@ -71,22 +80,6 @@ const FormItemContext = React.createContext<FormItemContextValue>(
   {} as FormItemContextValue,
 );
 
-/**
- * `FormItem` 渲染单个表单字段容器,生成稳定 id 给 Label/Description/Message 关联。
- */
-const FormItem = React.forwardRef<
-  HTMLDivElement,
-  React.HTMLAttributes<HTMLDivElement>
->(({ className, ...props }, ref) => {
-  const id = React.useId();
-  return (
-    <FormItemContext.Provider value={{ id }}>
-      <div ref={ref} className={cn('space-y-2', className)} {...props} />
-    </FormItemContext.Provider>
-  );
-});
-FormItem.displayName = 'FormItem';
-
 /**
  * 组合 FormField + FormItem 的字段元数据,用于 Label / Control / Description / Message。
  */
@@ -110,22 +103,74 @@ const useFormField = () => {
   };
 };
 
-const FormLabel = React.forwardRef<
-  React.ElementRef<typeof LabelPrimitive.Root>,
-  React.ComponentPropsWithoutRef<typeof Label>
->(({ className, ...props }, ref) => {
-  const { error, formItemId } = useFormField();
-  return (
-    <Label
-      ref={ref}
-      className={cn(error && 'text-destructive', className)}
-      htmlFor={formItemId}
-      {...props}
-    />
-  );
-});
+// ─── FormItem(下沉到 Field atom)─────────────────────────────────────────────
+
+/**
+ * `FormItemProps` 透传 Field 所有 props(orientation 响应式 / inputWidth / 等),
+ * **但不接受 `invalid`** — RHF 流程下 invalid 由 fieldState.error 自动决定。
+ */
+export type FormItemProps = Omit<FieldProps, 'invalid'>;
+
+/**
+ * `FormItem` 渲染单个表单字段容器 — 内部用 `Field` 作为视觉骨架,
+ * 自动从 RHF `fieldState.error` 注入 `invalid`,Label/Description/Message 关联用稳定 id。
+ *
+ * 等于"RHF 接入 + 自动 invalid 注入" 的 Field —— 完整继承 Field 的:
+ *   - orientation(标量 / 响应式)
+ *   - inputWidth(5 档宽度)
+ *   - className / style / data-* 透传
+ */
+const FormItem = React.forwardRef<HTMLDivElement, FormItemProps>(
+  ({ children, ...fieldProps }, ref) => {
+    const id = React.useId();
+    return (
+      <FormItemContext.Provider value={{ id }}>
+        <FormItemBody ref={ref} {...fieldProps}>
+          {children}
+        </FormItemBody>
+      </FormItemContext.Provider>
+    );
+  },
+);
+FormItem.displayName = 'FormItem';
+
+const FormItemBody = React.forwardRef<HTMLDivElement, FormItemProps>(
+  ({ children, ...fieldProps }, ref) => {
+    const { error } = useFormField();
+    return (
+      <Field ref={ref} invalid={!!error} {...fieldProps}>
+        {children}
+      </Field>
+    );
+  },
+);
+FormItemBody.displayName = 'FormItemBody';
+
+// ─── FormLabel / FormControl / FormDescription / FormMessage ─────────────────
+
+/**
+ * `FormLabel` = `FieldLabel` 包装 + 自动 `htmlFor=formItemId`。
+ * 着色(invalid → destructive)/ 必填 `*` / horizontal max ⅓ 等所有视觉行为继承自 FieldLabel。
+ */
+const FormLabel = React.forwardRef<HTMLLabelElement, FieldLabelProps>(
+  ({ className, ...props }, ref) => {
+    const { formItemId } = useFormField();
+    return (
+      <FieldLabel
+        ref={ref}
+        htmlFor={formItemId}
+        className={className}
+        {...props}
+      />
+    );
+  },
+);
 FormLabel.displayName = 'FormLabel';
 
+/**
+ * `FormControl` 用 Radix Slot 注入 `id` / `aria-describedby` / `aria-invalid` 到子控件。
+ * 内部仅放真正的输入控件(Input / Select / Checkbox / RadioGroup 等)。
+ */
 const FormControl = React.forwardRef<
   React.ElementRef<typeof Slot>,
   React.ComponentPropsWithoutRef<typeof Slot>
@@ -146,22 +191,30 @@ const FormControl = React.forwardRef<
 });
 FormControl.displayName = 'FormControl';
 
+/**
+ * `FormDescription` = `FieldDescription` 包装 + 自动 `id=formDescriptionId`(给 aria-describedby 用)。
+ */
 const FormDescription = React.forwardRef<
   HTMLParagraphElement,
   React.HTMLAttributes<HTMLParagraphElement>
 >(({ className, ...props }, ref) => {
   const { formDescriptionId } = useFormField();
   return (
-    <p
+    <FieldDescription
       ref={ref}
       id={formDescriptionId}
-      className={cn('text-xs text-muted-foreground', className)}
+      className={className}
       {...props}
     />
   );
 });
 FormDescription.displayName = 'FormDescription';
 
+/**
+ * `FormMessage` 渲染错误信息 — 有 RHF `error.message` 时取其文本,否则取 children;都没就不渲染。
+ * 视觉等同 FieldError(`-mt-1 text-xs font-medium text-destructive`),
+ * 但显示条件由 `error || children` 决定(非 Field.invalid),保留 shadcn 原语义。
+ */
 const FormMessage = React.forwardRef<
   HTMLParagraphElement,
   React.HTMLAttributes<HTMLParagraphElement>
@@ -173,7 +226,8 @@ const FormMessage = React.forwardRef<
     <p
       ref={ref}
       id={formMessageId}
-      className={cn('text-xs font-medium text-destructive', className)}
+      role="alert"
+      className={cn('-mt-1 text-xs font-medium text-destructive', className)}
       {...props}
     >
       {body}
@@ -182,6 +236,16 @@ const FormMessage = React.forwardRef<
 });
 FormMessage.displayName = 'FormMessage';
 
+// ─── FormSection / FormActions ────────────────────────────────────────────────
+//
+// 共享 Field 包的同款实现 — 同一职责一处实现(避免规范变更时双写)。
+//  - FormSection: title + columns(1|2|3|4 多栏 grid)
+//  - FormActions: container 容器感知 + position + align + alignWithInput(基线对齐)
+// 见 `packages/ui/src/components/field/field.tsx`。
+
+export type FormSectionProps = FieldSectionProps;
+export type FormActionsProps = FieldActionsProps;
+
 export {
   useFormField,
   Form,
@@ -191,4 +255,6 @@ export {
   FormDescription,
   FormMessage,
   FormField,
+  FieldSection as FormSection,
+  FieldActions as FormActions,
 };

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,10 +24,14 @@ package: "@teamix-evo/ui"
 - inline 间距小集合 → `Space`
 - 不固定列数的卡片墙 → 直接用 Tailwind `grid-cols-N` 或 `Item` 配 `ItemGroup`
 
+## Props
+
 <!-- auto:props:begin -->
 _(组件无 `<Name>Props` interface — props 详见 [`grid.tsx`](./grid.tsx))_
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 

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

@@ -1,15 +1,15 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { Row, Col } from './grid';
 
 const meta: Meta<typeof Row> = {
-  title: '布局与容器 · Layout/Grid',
+  title: '布局 · Layout/Grid',
   component: Row,
   tags: ['autodocs'],
   parameters: {
     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 = {