@teamix-evo/ui 0.1.1

package/src/components/empty/empty.stories.tsx

@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Plus } from 'lucide-react';
+import { Empty } from './empty';
+import { Button } from '@/components/button/button';
+
+const meta: Meta<typeof Empty> = {
+  title: '反馈与浮层 · Feedback/Empty',
+  component: Empty,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '空状态 — 列表 / 表格 / 搜索结果为空时的占位提示。提供 description 引导文案 + extra 主操作,鼓励用户创建首条数据。OpenTrek tokens 适配,等价 antd Empty。',
+      },
+    },
+  },
+  argTypes: {
+    size: { control: 'inline-radio', options: ['sm', 'default'] },
+  },
+  args: { size: 'default' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Empty>;
+
+export const Default: Story = {};
+
+export const WithAction: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Empty
+      description="还没有项目"
+      extra={<Button icon={<Plus />}>创建项目</Button>}
+    />
+  ),
+};
+
+export const Small: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="rounded-md border">
+      <Empty size="sm" description="无匹配的搜索结果" />
+    </div>
+  ),
+};

package/src/components/empty/empty.tsx

@@ -0,0 +1,47 @@
+import * as React from 'react';
+import { Inbox } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+
+export interface EmptyProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** 自定义图标(覆盖默认 Inbox)。 */
+  image?: React.ReactNode;
+  /** 描述文本。 @default "暂无数据" */
+  description?: React.ReactNode;
+  /** 操作区(放 Button 引导用户创建首条数据)。 */
+  extra?: React.ReactNode;
+  /**
+   * 尺寸 — `sm` 用于卡片内 / 表格空态;`default` 用于整区。
+   * @default "default"
+   */
+  size?: 'sm' | 'default';
+}
+
+const Empty = React.forwardRef<HTMLDivElement, EmptyProps>(
+  (
+    { image, description = '暂无数据', extra, size = 'default', className, ...props },
+    ref,
+  ) => {
+    const isSm = size === 'sm';
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          'flex flex-col items-center justify-center gap-3 text-muted-foreground',
+          isSm ? 'py-8' : 'py-16',
+          className,
+        )}
+        {...props}
+      >
+        <div className={cn('opacity-40', isSm ? 'text-3xl' : 'text-5xl')}>
+          {image ?? <Inbox className={isSm ? 'size-8' : 'size-16'} />}
+        </div>
+        <div className={cn(isSm ? 'text-xs' : 'text-sm')}>{description}</div>
+        {extra ? <div className="mt-1">{extra}</div> : null}
+      </div>
+    );
+  },
+);
+Empty.displayName = 'Empty';
+
+export { Empty };

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

@@ -0,0 +1,116 @@
+---
+id: field
+name: Field
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Field
+
+通用表单字段抽象 — shadcn 2025-10 新增。**比 `Form` 更通用**:Form 强绑定 RHF + zod;Field 是纯 UI 抽象,跟任何状态管理(Server Actions / RHF / TanStack Form / 原生 form)都能搭。提供 7 个语义槽:`Field` 容器 / `FieldLabel` 标签 / `FieldDescription` 帮助文案 / `FieldError` 错误提示 / `FieldGroup` 多字段纵向容器 / `FieldSet` 带边框分组 / `FieldLegend` 分组标题。
+
+## When to use
+
+- Server Actions / 原生 form / 任何非 RHF 流派的表单字段封装
+- 与现有 `Form`(RHF)互补:Form 管校验与状态,**控件内部**仍可用 Field 表达视觉结构
+- 大型表单分组(FieldSet + FieldLegend 表达"账号信息" / "联系方式"等小节)
+
+## When NOT to use
+
+- 已用 `Form`(RHF)并接受其约定 → 优先 `FormItem / FormLabel / FormMessage`(更紧)
+- 控件本身没有 label / description → 直接用 `Input` / `Select` 自由布局
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `orientation` | `'vertical' \| 'horizontal'` | `"vertical"` | – | 字段方向 — `vertical`(默认)Label 在控件上;`horizontal` Label 在控件左侧(配长表单)。 |
+| `invalid` | `boolean` | `false` | – | 标记字段为 invalid — 子组件的 ring / 文字色会跟随;同时把内部 `<FieldError>` 渲染为可见。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add field` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `label` | component | 表单字段标签 — Radix Label 包装,补 antd Form.Item 风格的 required / disabled 显式视觉 |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```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 校验
+- **`FieldSet disabled`** 利用原生 fieldset 的级联禁用 — 内部所有原生 input 都会失能;**不要**手动给每个控件传 disabled
+- **不要嵌套 `Field` in `Field`** — 那是 FieldGroup 的活
+- **与 `Form` 共存**:在 RHF 流程外的小表单(登录、邮件订阅)直接用 Field;复杂业务表单仍走 Form
+
+## Examples
+
+```tsx
+import {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldSet,
+  FieldLegend,
+} from '@/components/ui/field';
+import { Input } from '@/components/ui/input';
+import { Switch } from '@/components/ui/switch';
+
+// 单字段
+<Field invalid={Boolean(errors.email)}>
+  <FieldLabel htmlFor="email" required>邮箱</FieldLabel>
+  <Input id="email" type="email" name="email" />
+  <FieldDescription>用于接收订单通知</FieldDescription>
+  <FieldError>{errors.email}</FieldError>
+</Field>
+
+// horizontal(长表单)
+<Field orientation="horizontal">
+  <FieldLabel htmlFor="notify" className="min-w-32">
+    邮件通知
+  </FieldLabel>
+  <Switch id="notify" defaultChecked />
+</Field>
+
+// 分组
+<FieldSet>
+  <FieldLegend>账号信息</FieldLegend>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="name">姓名</FieldLabel>
+      <Input id="name" name="name" />
+    </Field>
+    <Field>
+      <FieldLabel htmlFor="email">邮箱</FieldLabel>
+      <Input id="email" name="email" type="email" />
+    </Field>
+  </FieldGroup>
+</FieldSet>
+
+// 配 Server Actions
+<form action={createUser}>
+  <FieldGroup>
+    <Field>
+      <FieldLabel htmlFor="name" required>姓名</FieldLabel>
+      <Input id="name" name="name" required />
+    </Field>
+  </FieldGroup>
+  <button type="submit">提交</button>
+</form>
+```

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

@@ -0,0 +1,117 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldSet,
+  FieldLegend,
+} from './field';
+import { Input } from '@/components/input/input';
+import { Switch } from '@/components/switch/switch';
+import { Button } from '@/components/button/button';
+
+const meta: Meta<typeof Field> = {
+  title: '表单与输入 · Form/Field',
+  component: Field,
+  tags: ['autodocs'],
+  parameters: {
+    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。',
+      },
+    },
+  },
+  argTypes: {
+    orientation: { control: 'inline-radio', options: ['vertical', 'horizontal'] },
+    invalid: { control: 'boolean' },
+  },
+  args: { orientation: 'vertical', invalid: false },
+};
+
+export default meta;
+type Story = StoryObj<typeof Field>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <Field {...args} className="w-80">
+      <FieldLabel htmlFor="email-pg" required>
+        邮箱
+      </FieldLabel>
+      <Input id="email-pg" type="email" placeholder="you@example.com" />
+      <FieldDescription>用于接收订单通知</FieldDescription>
+      <FieldError>邮箱格式不正确</FieldError>
+    </Field>
+  ),
+};
+
+export const Horizontal: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Field orientation="horizontal" className="w-96">
+      <FieldLabel htmlFor="notify-h" className="min-w-28 pt-2">
+        邮件通知
+      </FieldLabel>
+      <div className="flex-1">
+        <Switch id="notify-h" defaultChecked />
+        <FieldDescription className="mt-1">
+          有重要事件时给您发邮件
+        </FieldDescription>
+      </div>
+    </Field>
+  ),
+};
+
+export const Grouped: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <FieldSet className="w-96">
+      <FieldLegend>账号信息</FieldLegend>
+      <FieldGroup>
+        <Field>
+          <FieldLabel htmlFor="name-g">姓名</FieldLabel>
+          <Input id="name-g" />
+        </Field>
+        <Field>
+          <FieldLabel htmlFor="email-g" required>
+            邮箱
+          </FieldLabel>
+          <Input id="email-g" type="email" />
+        </Field>
+      </FieldGroup>
+    </FieldSet>
+  ),
+};
+
+export const ServerActionForm: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <form
+      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"
+    >
+      <FieldGroup>
+        <Field>
+          <FieldLabel htmlFor="name-srv" required>
+            姓名
+          </FieldLabel>
+          <Input id="name-srv" name="name" required />
+        </Field>
+        <Field>
+          <FieldLabel htmlFor="email-srv" required>
+            邮箱
+          </FieldLabel>
+          <Input id="email-srv" name="email" type="email" required />
+        </Field>
+      </FieldGroup>
+      <Button type="submit">提交</Button>
+    </form>
+  ),
+};

package/src/components/field/field.tsx

@@ -0,0 +1,164 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+
+import { cn } from '@/utils/cn';
+import { Label } from '@/components/label/label';
+
+// ─── FieldSet / FieldLegend(分组的语义边框)────────────────────────────
+
+const FieldSet = React.forwardRef<
+  HTMLFieldSetElement,
+  React.FieldsetHTMLAttributes<HTMLFieldSetElement>
+>(({ className, ...props }, ref) => (
+  <fieldset
+    ref={ref}
+    className={cn(
+      'flex flex-col gap-4 rounded-md border bg-card p-4 disabled:cursor-not-allowed disabled:opacity-60',
+      className,
+    )}
+    {...props}
+  />
+));
+FieldSet.displayName = 'FieldSet';
+
+const FieldLegend = React.forwardRef<
+  HTMLLegendElement,
+  React.HTMLAttributes<HTMLLegendElement>
+>(({ className, ...props }, ref) => (
+  <legend
+    ref={ref}
+    className={cn('px-1 text-sm font-semibold leading-none', className)}
+    {...props}
+  />
+));
+FieldLegend.displayName = 'FieldLegend';
+
+// ─── FieldGroup(纵向排列多个 Field 的容器)──────────────────────────────
+
+const FieldGroup = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn('flex flex-col gap-4', className)} {...props} />
+));
+FieldGroup.displayName = 'FieldGroup';
+
+// ─── Field(单个字段容器:Label + Control + Description + Error)────────
+
+const fieldVariants = cva('flex', {
+  variants: {
+    orientation: {
+      vertical: 'flex-col gap-1.5',
+      horizontal: 'flex-row items-start gap-3',
+    },
+  },
+  defaultVariants: { orientation: 'vertical' },
+});
+
+export interface FieldProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof fieldVariants> {
+  /**
+   * 字段方向 — `vertical`(默认)Label 在控件上;`horizontal` Label 在控件左侧(配长表单)。
+   * @default "vertical"
+   */
+  orientation?: 'vertical' | 'horizontal';
+  /**
+   * 标记字段为 invalid — 子组件的 ring / 文字色会跟随;同时把内部 `<FieldError>` 渲染为可见。
+   * @default false
+   */
+  invalid?: boolean;
+}
+
+const FieldContext = React.createContext<{ invalid: boolean }>({ invalid: false });
+
+const Field = React.forwardRef<HTMLDivElement, FieldProps>(
+  ({ orientation, invalid = false, className, ...props }, ref) => (
+    <FieldContext.Provider value={{ invalid }}>
+      <div
+        ref={ref}
+        data-invalid={invalid ? '' : undefined}
+        className={cn(fieldVariants({ orientation }), className)}
+        {...props}
+      />
+    </FieldContext.Provider>
+  ),
+);
+Field.displayName = 'Field';
+
+// ─── FieldLabel(label,继承 invalid 着色)──────────────────────────────
+
+export interface FieldLabelProps
+  extends React.ComponentPropsWithoutRef<typeof Label> {
+  /**
+   * 在 label 末尾追加 "*" 强调必填(antd Form `required` 并集) — 仅视觉,业务侧需在校验层确保必填。
+   * @default false
+   */
+  required?: boolean;
+}
+
+const FieldLabel = React.forwardRef<
+  React.ElementRef<typeof Label>,
+  FieldLabelProps
+>(({ required = false, className, children, ...props }, ref) => {
+  const { invalid } = React.useContext(FieldContext);
+  return (
+    <Label
+      ref={ref}
+      className={cn(invalid && 'text-destructive', className)}
+      {...props}
+    >
+      {children}
+      {required ? (
+        <span aria-hidden="true" className="ml-0.5 text-destructive">
+          *
+        </span>
+      ) : null}
+    </Label>
+  );
+});
+FieldLabel.displayName = 'FieldLabel';
+
+// ─── FieldDescription / FieldError ────────────────────────────────────
+
+const FieldDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <p
+    ref={ref}
+    className={cn('text-xs text-muted-foreground', className)}
+    {...props}
+  />
+));
+FieldDescription.displayName = 'FieldDescription';
+
+const FieldError = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, children, ...props }, ref) => {
+  const { invalid } = React.useContext(FieldContext);
+  if (!invalid || !children) return null;
+  return (
+    <p
+      ref={ref}
+      role="alert"
+      className={cn('text-xs font-medium text-destructive', className)}
+      {...props}
+    >
+      {children}
+    </p>
+  );
+});
+FieldError.displayName = 'FieldError';
+
+export {
+  Field,
+  FieldLabel,
+  FieldDescription,
+  FieldError,
+  FieldGroup,
+  FieldSet,
+  FieldLegend,
+  fieldVariants,
+};

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

@@ -0,0 +1,94 @@
+---
+id: flex
+name: Flex
+type: component
+category: layout
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Flex
+
+Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+),把 Tailwind flex 的常用配置(对齐 / 间距 / 换行 / 方向 / 渲染元素)收敛为枚举,避免散落的 `flex flex-col items-start gap-4 ...` 反复手写。
+
+## When to use
+
+- 完整页面 / 卡片 / Section 的容器布局
+- 需要语义化 HTML 标签(`<header>` `<aside>` `<main>` `<nav>`)时用 `as`
+- 多次重复的相同对齐组合(可以靠 Flex 收敛模板)
+
+## When NOT to use
+
+- 小集合 inline 间距 → `Space`
+- 网格 → `Grid`(`Row + Col`)
+- 仅一次性自由布局 → 直接写 className 也行,不强求
+
+<!-- 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` 等语义标签。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add flex` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+_无 — 本组件不依赖任何 npm 包。_
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **`gap` 是档位枚举**(none / xs / sm / default / lg / xl),**不接受 number** — 走 design 间距刻度
+- **`direction="column"` 等价 antd `vertical`** — antd 的 `vertical={true}` 我们没沿用 boolean,直接走 direction 更直观
+- **`as` 仅限语义化标签集**(`section / header / aside / main / nav / footer / article / div`)— 不要传 `'span' / 'h1'` 等非 block 标签
+- **不要嵌套 Flex 表达栅格** — 用 `Grid (Row/Col)`
+- **align/justify 默认值**:`align="stretch"`(子项填满高度)、`justify="start"`(主轴起始)— 大部分场景符合直觉
+
+## Examples
+
+```tsx
+import { Flex } from '@/components/ui/flex';
+
+// 居中对话框
+<Flex justify="center" align="center" className="min-h-screen">
+  <Dialog />
+</Flex>
+
+// 页头:logo + 导航 + 头像
+<Flex as="header" justify="between" align="center" className="border-b px-6 py-3">
+  <Logo />
+  <Nav />
+  <Avatar />
+</Flex>
+
+// 纵向卡片体
+<Flex direction="column" gap="sm" className="p-6">
+  <Title>标题</Title>
+  <Paragraph>正文...</Paragraph>
+  <Button>操作</Button>
+</Flex>
+
+// 工具栏(右对齐)
+<Flex justify="end" gap="sm">
+  <Button variant="outline">取消</Button>
+  <Button>提交</Button>
+</Flex>
+
+// 标签云
+<Flex wrap gap="sm">
+  {tags.map((t) => <Tag key={t}>{t}</Tag>)}
+</Flex>
+```