@teamix-evo/ui 0.1.1

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

@@ -0,0 +1,122 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react';
+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 './form';
+import { Input } from '@/components/input/input';
+import { Button } from '@/components/button/button';
+
+const meta: Meta<typeof Form> = {
+  title: '表单与输入 · Form/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。',
+      },
+    },
+  },
+};
+
+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),
+      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>
+    );
+  },
+};

package/src/components/form/form.tsx

@@ -0,0 +1,194 @@
+import * as React from 'react';
+import * as LabelPrimitive from '@radix-ui/react-label';
+import { Slot } from '@radix-ui/react-slot';
+import {
+  Controller,
+  FormProvider,
+  useFormContext,
+  type ControllerProps,
+  type FieldPath,
+  type FieldValues,
+  type UseFormReturn,
+} from 'react-hook-form';
+
+import { cn } from '@/utils/cn';
+import { Label } from '@/components/label/label';
+
+/**
+ * `Form` props — 即 `useForm()` 返回值(`UseFormReturn<TFieldValues>`) 的全部方法,
+ * 加上 `children`。`Form` 本质是 `react-hook-form.FormProvider` 的别名;
+ * 该 interface 用于 Props 表生成与类型提示。
+ */
+export interface FormProps<TFieldValues extends FieldValues = FieldValues>
+  extends UseFormReturn<TFieldValues> {
+  /**
+   * 表单内容 — 通常是 `<form>` + `<FormField>` 列表。
+   */
+  children?: React.ReactNode;
+}
+
+/**
+ * `Form` = `react-hook-form` 的 `FormProvider` 别名。
+ * 配合 `useForm()` 使用,把表单实例下发给所有 `FormField`。
+ */
+const Form = FormProvider;
+
+// ─── FormField context ────────────────────────────────────────────────────────
+
+interface FormFieldContextValue<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> {
+  name: TName;
+}
+
+const FormFieldContext = React.createContext<FormFieldContextValue>(
+  {} as FormFieldContextValue,
+);
+
+/**
+ * `FormField` = `Controller` 包装,把 `name` 注入下层的 useFormField hook。
+ * 用法:`<FormField name="email" control={form.control} render={({ field }) => <FormItem>...</FormItem>} />`
+ */
+function FormField<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({ ...props }: ControllerProps<TFieldValues, TName>) {
+  return (
+    <FormFieldContext.Provider value={{ name: props.name }}>
+      <Controller {...props} />
+    </FormFieldContext.Provider>
+  );
+}
+
+// ─── FormItem context ─────────────────────────────────────────────────────────
+
+interface FormItemContextValue {
+  id: string;
+}
+
+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。
+ */
+const useFormField = () => {
+  const fieldContext = React.useContext(FormFieldContext);
+  const itemContext = React.useContext(FormItemContext);
+  const { getFieldState, formState } = useFormContext();
+  const fieldState = getFieldState(fieldContext.name, formState);
+
+  if (!fieldContext) {
+    throw new Error('useFormField should be used within <FormField>');
+  }
+  const { id } = itemContext;
+  return {
+    id,
+    name: fieldContext.name,
+    formItemId: `${id}-form-item`,
+    formDescriptionId: `${id}-form-item-description`,
+    formMessageId: `${id}-form-item-message`,
+    ...fieldState,
+  };
+};
+
+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}
+    />
+  );
+});
+FormLabel.displayName = 'FormLabel';
+
+const FormControl = React.forwardRef<
+  React.ElementRef<typeof Slot>,
+  React.ComponentPropsWithoutRef<typeof Slot>
+>(({ ...props }, ref) => {
+  const { error, formItemId, formDescriptionId, formMessageId } =
+    useFormField();
+  return (
+    <Slot
+      ref={ref}
+      id={formItemId}
+      aria-describedby={
+        error ? `${formDescriptionId} ${formMessageId}` : `${formDescriptionId}`
+      }
+      aria-invalid={!!error}
+      {...props}
+    />
+  );
+});
+FormControl.displayName = 'FormControl';
+
+const FormDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => {
+  const { formDescriptionId } = useFormField();
+  return (
+    <p
+      ref={ref}
+      id={formDescriptionId}
+      className={cn('text-xs text-muted-foreground', className)}
+      {...props}
+    />
+  );
+});
+FormDescription.displayName = 'FormDescription';
+
+const FormMessage = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, children, ...props }, ref) => {
+  const { error, formMessageId } = useFormField();
+  const body = error ? String(error?.message ?? '') : children;
+  if (!body) return null;
+  return (
+    <p
+      ref={ref}
+      id={formMessageId}
+      className={cn('text-xs font-medium text-destructive', className)}
+      {...props}
+    >
+      {body}
+    </p>
+  );
+});
+FormMessage.displayName = 'FormMessage';
+
+export {
+  useFormField,
+  Form,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormDescription,
+  FormMessage,
+  FormField,
+};

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

@@ -0,0 +1,87 @@
+---
+id: grid
+name: Grid
+type: component
+category: layout
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Grid (Row / Col)
+
+24 栅格系统 — antd 独有补足。**等价 antd `Row` + `Col`**:基于 CSS Grid 的 24 列容器,支持 `span` / `offset` / `order` / `flex` / `gutter` / `justify` / `align` 等核心 API,中后台表单 / 看板布局基石。
+
+## When to use
+
+- 中后台多列表单(`<Col span={12}>` 二等分,`<Col span={8}>` 三等分)
+- 数据看板的卡片网格(配 `gutter` 控制水平 / 垂直间距)
+- 响应式布局(配业务侧 Tailwind 断点 className,如 `className="md:col-span-12 col-span-24"`)
+
+## When NOT to use
+
+- 简单 flex 容器 → `Flex`
+- inline 间距小集合 → `Space`
+- 不固定列数的卡片墙 → 直接用 Tailwind `grid-cols-N` 或 `Item` 配 `ItemGroup`
+
+<!-- auto:props:begin -->
+_(组件无 `<Name>Props` interface — props 详见 [`grid.tsx`](./grid.tsx))_
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add grid` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+_无 — 本组件不依赖任何 npm 包。_
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **`span` 默认 24**(占满一行) — 不传等于"独占整行"
+- **`gutter` 走 design 间距刻度**:接受 number(等价 `[n, n]`)或 `[h, v]`,实际值就是 `n * 4px`(Tailwind gap-N 同源)
+- **`offset`** 用百分比定位,不要超过 24 - span(否则越界)
+- **`flex={true}`** 等价 antd `flex="auto"` — 撑满剩余空间;启用后 `span` 失效
+- **`span={0}` 隐藏**(antd 兼容行为) — 用 `0` 隐藏比 `display: none` 语义更明确
+- **响应式**:本组件不内置 antd 的 `xs/sm/md/lg/xl/xxl` 断点 prop — 业务侧请用 Tailwind `md:col-span-12` 等响应式 className(更原生、更可控)
+- **不要嵌套 Row 表达卡片网格** — 那是 `Item` + Tailwind grid 的活
+
+## Examples
+
+```tsx
+import { Row, Col } from '@/components/ui/grid';
+
+// 二等分表单
+<Row gutter={4}>
+  <Col span={12}>
+    <Field><FieldLabel>姓</FieldLabel><Input /></Field>
+  </Col>
+  <Col span={12}>
+    <Field><FieldLabel>名</FieldLabel><Input /></Field>
+  </Col>
+</Row>
+
+// 8-8-8 三等分
+<Row gutter={[4, 4]}>
+  <Col span={8}><Card /></Col>
+  <Col span={8}><Card /></Col>
+  <Col span={8}><Card /></Col>
+</Row>
+
+// 主区 + 侧边(主区 flex 撑满)
+<Row gutter={4}>
+  <Col flex><MainContent /></Col>
+  <Col span={6}><Sidebar /></Col>
+</Row>
+
+// 偏移
+<Row gutter={4}>
+  <Col span={8} offset={4}>居中的 8 列</Col>
+  <Col span={8} offset={4}>另一个</Col>
+</Row>
+```

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

@@ -0,0 +1,99 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Row, Col } from './grid';
+
+const meta: Meta<typeof Row> = {
+  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。',
+      },
+    },
+  },
+};
+
+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>
+);
+
+export const Playground: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Row gutter={4}>
+      <Col span={12}>
+        <Box>span = 12</Box>
+      </Col>
+      <Col span={12}>
+        <Box>span = 12</Box>
+      </Col>
+    </Row>
+  ),
+};
+
+export const Thirds: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Row gutter={[4, 4]}>
+      <Col span={8}>
+        <Box>span = 8</Box>
+      </Col>
+      <Col span={8}>
+        <Box>span = 8</Box>
+      </Col>
+      <Col span={8}>
+        <Box>span = 8</Box>
+      </Col>
+    </Row>
+  ),
+};
+
+export const WithFlex: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Row gutter={4}>
+      <Col flex>
+        <Box>flex(撑满)</Box>
+      </Col>
+      <Col span={6}>
+        <Box>span = 6 sidebar</Box>
+      </Col>
+    </Row>
+  ),
+};
+
+export const Offset: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Row gutter={4}>
+      <Col span={8} offset={4}>
+        <Box>span=8 offset=4</Box>
+      </Col>
+      <Col span={8} offset={4}>
+        <Box>span=8 offset=4</Box>
+      </Col>
+    </Row>
+  ),
+};
+
+export const JustifyCenter: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Row gutter={4} justify="center">
+      <Col span={6}>
+        <Box>1</Box>
+      </Col>
+      <Col span={6}>
+        <Box>2</Box>
+      </Col>
+      <Col span={6}>
+        <Box>3</Box>
+      </Col>
+    </Row>
+  ),
+};

package/src/components/grid/grid.tsx

@@ -0,0 +1,130 @@
+import * as React from 'react';
+
+import { cn } from '@/utils/cn';
+
+/**
+ * antd 24 栅格的端口实现。底层使用 CSS Grid + 24 column,与 antd `Row` / `Col` 语义对齐。
+ * `span` / `offset` 接受 1~24 整数;`gutter` 是 `[水平, 垂直]` 间距(任选传 number 等价 `[n, n]`)。
+ */
+
+const justifyMap = {
+  start: 'justify-start',
+  center: 'justify-center',
+  end: 'justify-end',
+  'space-between': 'justify-between',
+  'space-around': 'justify-around',
+  'space-evenly': 'justify-evenly',
+} as const;
+
+const alignMap = {
+  top: 'items-start',
+  middle: 'items-center',
+  bottom: 'items-end',
+  stretch: 'items-stretch',
+} as const;
+
+export interface RowProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 子项间距 — number 等价 `[n, n]`;`[h, v]` 分别控制水平 / 垂直。
+   * 注意:走 design 间距刻度,实际渲染值就是 `n * 4px`(Tailwind gap-N)。
+   * @default 0
+   */
+  gutter?: number | [number, number];
+  /**
+   * 水平排列(antd `justify` 并集)。
+   * @default "start"
+   */
+  justify?: keyof typeof justifyMap;
+  /**
+   * 垂直对齐(antd `align` 并集)。
+   * @default "top"
+   */
+  align?: keyof typeof alignMap;
+  /**
+   * 是否允许换行(antd `wrap` 并集)。
+   * @default true
+   */
+  wrap?: boolean;
+}
+
+const Row = React.forwardRef<HTMLDivElement, RowProps>(
+  (
+    {
+      gutter = 0,
+      justify = 'start',
+      align = 'top',
+      wrap = true,
+      className,
+      children,
+      style,
+      ...props
+    },
+    ref,
+  ) => {
+    const [hGutter, vGutter] =
+      Array.isArray(gutter) ? gutter : [gutter, gutter];
+    return (
+      <div
+        ref={ref}
+        className={cn('grid', justifyMap[justify], alignMap[align], className)}
+        style={{
+          gridTemplateColumns: 'repeat(24, minmax(0, 1fr))',
+          columnGap: `${hGutter * 4}px`,
+          rowGap: `${vGutter * 4}px`,
+          ...style,
+        }}
+        {...props}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+Row.displayName = 'Row';
+
+export interface ColProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 占用栅格数(1~24,antd `span` 并集) — 0 表示隐藏(对齐 antd 行为)。
+   * @default 24
+   */
+  span?: number;
+  /**
+   * 左侧偏移栅格数(antd `offset` 并集)。
+   * @default 0
+   */
+  offset?: number;
+  /**
+   * 顺序(antd `order` 并集) — 用于响应式 / a11y 顺序变更场景。
+   */
+  order?: number;
+  /**
+   * 自动撑满剩余空间(antd `flex="auto"` 等价) — 设置后忽略 span。
+   * @default false
+   */
+  flex?: boolean;
+}
+
+const Col = React.forwardRef<HTMLDivElement, ColProps>(
+  ({ span = 24, offset = 0, order, flex = false, className, style, ...props }, ref) => {
+    if (span === 0) return null;
+    const computedStyle: React.CSSProperties = { ...style };
+    if (flex) {
+      computedStyle.flex = '1 1 0%';
+    } else {
+      computedStyle.gridColumn = `span ${Math.max(1, Math.min(24, span))} / span ${Math.max(1, Math.min(24, span))}`;
+      if (offset > 0) computedStyle.marginLeft = `${(offset / 24) * 100}%`;
+    }
+    if (typeof order === 'number') computedStyle.order = order;
+    return (
+      <div
+        ref={ref}
+        className={cn('min-w-0', className)}
+        style={computedStyle}
+        {...props}
+      />
+    );
+  },
+);
+Col.displayName = 'Col';
+
+export { Row, Col };