@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/form/stories.tsx

@@ -0,0 +1,301 @@
+/**
+ * @fileoverview Form stories — react-hook-form 薄封装演示
+ *
+ * 注：dynamic source 模式会把 `<Form {...form}>` 的 RHF 实例展开成大量内部 props，
+ * 因此每个 story 用 `parameters.docs.source.code` 手写一份与 render 等价的源码字符串，
+ * 让 showcode 直接呈现用户应该抄走的代码。
+ */
+import type { Meta, StoryObj } from '@storybook/react';
+import { useForm } from 'react-hook-form';
+
+import {
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from '.';
+import { Input } from '@/components/input';
+import { Button } from '@/components/button';
+
+const meta: Meta<typeof Form> = {
+  title: '数据录入 · Data Entry/Form 表单',
+  component: Form,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          'react-hook-form 极薄封装，将 RHF FormProvider / Controller 与 Field 系列原子组合，实现自动 aria 注入和错误状态联动。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Form>;
+
+/** 基础用法:用户名 + 邮箱字段,含校验规则与描述文案。 */
+export const Basic: Story = {
+  name: '基础用法',
+  render: () => {
+    const form = useForm({
+      defaultValues: { username: '', email: '' },
+    });
+    return (
+      <Form {...form}>
+        <form
+          onSubmit={form.handleSubmit((data) => console.log(data))}
+          className="flex w-80 flex-col gap-4"
+        >
+          <FormField
+            name="username"
+            rules={{ required: '用户名不能为空' }}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>用户名</FormLabel>
+                <FormControl>
+                  <Input placeholder="请输入用户名" {...field} />
+                </FormControl>
+                <FormDescription>这是你的公开显示名称。</FormDescription>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <FormField
+            name="email"
+            rules={{
+              required: '邮箱不能为空',
+              pattern: { value: /^\S+@\S+$/i, message: '邮箱格式不正确' },
+            }}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>邮箱</FormLabel>
+                <FormControl>
+                  <Input
+                    type="email"
+                    placeholder="name@example.com"
+                    {...field}
+                  />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <Button type="submit">提交</Button>
+        </form>
+      </Form>
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `function BasicForm() {
+  const form = useForm({
+    defaultValues: { username: '', email: '' },
+  });
+  return (
+    <Form {...form}>
+      <form
+        onSubmit={form.handleSubmit((data) => console.log(data))}
+        className="flex w-80 flex-col gap-4"
+      >
+        <FormField
+          name="username"
+          rules={{ required: '用户名不能为空' }}
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>用户名</FormLabel>
+              <FormControl>
+                <Input placeholder="请输入用户名" {...field} />
+              </FormControl>
+              <FormDescription>这是你的公开显示名称。</FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <FormField
+          name="email"
+          rules={{
+            required: '邮箱不能为空',
+            pattern: { value: /^\\S+@\\S+$/i, message: '邮箱格式不正确' },
+          }}
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>邮箱</FormLabel>
+              <FormControl>
+                <Input type="email" placeholder="name@example.com" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">提交</Button>
+      </form>
+    </Form>
+  );
+}`,
+      },
+    },
+  },
+};
+
+/** 错误状态:必填 + minLength 校验,提交时联动 `data-invalid` 与 FormMessage。 */
+export const ErrorState: Story = {
+  name: '错误状态',
+  render: () => {
+    const form = useForm({
+      defaultValues: { name: '' },
+    });
+    return (
+      <Form {...form}>
+        <form
+          onSubmit={form.handleSubmit((data) => console.log(data))}
+          className="flex w-80 flex-col gap-4"
+        >
+          <FormField
+            name="name"
+            rules={{
+              required: '此字段必填',
+              minLength: { value: 2, message: '最少 2 个字符' },
+            }}
+            render={({ field }) => (
+              <FormItem>
+                <FormLabel>姓名</FormLabel>
+                <FormControl>
+                  <Input placeholder="请输入姓名" {...field} />
+                </FormControl>
+                <FormMessage />
+              </FormItem>
+            )}
+          />
+          <Button type="submit">验证</Button>
+        </form>
+      </Form>
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `function ErrorStateForm() {
+  const form = useForm({
+    defaultValues: { name: '' },
+  });
+  return (
+    <Form {...form}>
+      <form
+        onSubmit={form.handleSubmit((data) => console.log(data))}
+        className="flex w-80 flex-col gap-4"
+      >
+        <FormField
+          name="name"
+          rules={{
+            required: '此字段必填',
+            minLength: { value: 2, message: '最少 2 个字符' },
+          }}
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>姓名</FormLabel>
+              <FormControl>
+                <Input placeholder="请输入姓名" {...field} />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">验证</Button>
+      </form>
+    </Form>
+  );
+}`,
+      },
+    },
+  },
+};
+
+/** 水平布局:FormItem `orientation="responsive"`,标签与控件并排。 */
+export const Horizontal: Story = {
+  name: '水平布局',
+  render: () => {
+    const form = useForm({
+      defaultValues: { firstName: '', lastName: '' },
+    });
+    return (
+      <Form {...form}>
+        <form
+          onSubmit={form.handleSubmit((data) => console.log(data))}
+          className="flex w-96 flex-col gap-4"
+        >
+          <FormField
+            name="firstName"
+            render={({ field }) => (
+              <FormItem orientation="responsive">
+                <FormLabel>姓</FormLabel>
+                <FormControl>
+                  <Input {...field} />
+                </FormControl>
+              </FormItem>
+            )}
+          />
+          <FormField
+            name="lastName"
+            render={({ field }) => (
+              <FormItem orientation="responsive">
+                <FormLabel>名</FormLabel>
+                <FormControl>
+                  <Input {...field} />
+                </FormControl>
+              </FormItem>
+            )}
+          />
+          <Button type="submit">提交</Button>
+        </form>
+      </Form>
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: `function HorizontalForm() {
+  const form = useForm({
+    defaultValues: { firstName: '', lastName: '' },
+  });
+  return (
+    <Form {...form}>
+      <form
+        onSubmit={form.handleSubmit((data) => console.log(data))}
+        className="flex w-96 flex-col gap-4"
+      >
+        <FormField
+          name="firstName"
+          render={({ field }) => (
+            <FormItem orientation="responsive">
+              <FormLabel>姓</FormLabel>
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+            </FormItem>
+          )}
+        />
+        <FormField
+          name="lastName"
+          render={({ field }) => (
+            <FormItem orientation="responsive">
+              <FormLabel>名</FormLabel>
+              <FormControl>
+                <Input {...field} />
+              </FormControl>
+            </FormItem>
+          )}
+        />
+        <Button type="submit">提交</Button>
+      </form>
+    </Form>
+  );
+}`,
+      },
+    },
+  },
+};

package/src/components/hover-card/index.tsx

@@ -0,0 +1,103 @@
+/**
+ * 悬停卡片 HoverCard
+ *
+ * 鼠标悬停时展示补充信息的弹出卡片，支持自定义打开 / 关闭延时与尖角箭头。
+ *
+ * @when
+ * - 用户名称悬停展示个人信息
+ * - 链接悬停预览内容
+ * - 无需点击即可查看详情
+ *
+ * 组合结构：HoverCard > HoverCardTrigger + HoverCardContent (> HoverCardArrow?)
+ */
+
+'use client';
+
+import * as React from 'react';
+import { HoverCard as HoverCardPrimitive } from 'radix-ui';
+
+import { cn } from '@/lib/utils';
+
+export interface HoverCardProps
+  extends Omit<
+    React.ComponentProps<typeof HoverCardPrimitive.Root>,
+    'open' | 'defaultOpen' | 'onOpenChange' | 'openDelay' | 'closeDelay'
+  > {
+  /** 受控显示状态。 */
+  open?: boolean;
+  /** 非受控初始显示状态。 @default false */
+  defaultOpen?: boolean;
+  /**
+   * 显示 / 关闭状态变化回调。
+   * @param open 当前是否显示
+   */
+  onOpenChange?: (open: boolean) => void;
+  /** 悬停多久后打开（毫秒）。 @default 700 */
+  openDelay?: number;
+  /** 离开多久后关闭（毫秒）。 @default 300 */
+  closeDelay?: number;
+}
+
+function HoverCard({ ...props }: HoverCardProps) {
+  return <HoverCardPrimitive.Root data-slot="hover-card" {...props} />;
+}
+
+function HoverCardTrigger({
+  ...props
+}: React.ComponentProps<typeof HoverCardPrimitive.Trigger>) {
+  return (
+    <HoverCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
+  );
+}
+
+export interface HoverCardContentProps
+  extends React.ComponentProps<typeof HoverCardPrimitive.Content> {
+  /** 浮层渲染容器，透传给 Portal。 @default document.body */
+  container?: HTMLElement | null;
+}
+
+function HoverCardContent({
+  className,
+  align = 'center',
+  sideOffset = 4,
+  container,
+  ...props
+}: HoverCardContentProps) {
+  return (
+    <HoverCardPrimitive.Portal container={container}>
+      <HoverCardPrimitive.Content
+        data-slot="hover-card-content"
+        align={align}
+        sideOffset={sideOffset}
+        className={cn(
+          'group/hover-card-content relative z-50 w-64 origin-(--radix-hover-card-content-transform-origin) rounded-md bg-popover p-2.5 text-xs text-popover-foreground shadow-md ring-1 ring-foreground/10 outline-hidden duration-100 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
+          className,
+        )}
+        {...props}
+      />
+    </HoverCardPrimitive.Portal>
+  );
+}
+
+function HoverCardArrow({
+  className,
+  ...props
+}: React.ComponentProps<typeof HoverCardPrimitive.Arrow>) {
+  // ant Balloon 风格：方块 rotate-45 半截嵌入 Content、半截露出。
+  // Radix Popper 已按 side 为外层 wrapper 自动旋转（top:0 / bottom:180° / left:-90° / right:90°），
+  // 所以 SVG 本地坐标系中 “朝外露出的两条边” 永远是 right + bottom，在四个方向下都是连续描边。
+  return (
+    <HoverCardPrimitive.Arrow
+      data-slot="hover-card-arrow"
+      width={10}
+      height={10}
+      className={cn(
+        'block size-2 -translate-y-1/2 rotate-45 border-0 border-r border-b border-foreground/10 bg-popover fill-popover',
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+export { HoverCard, HoverCardArrow, HoverCardContent, HoverCardTrigger };

package/src/components/hover-card/meta.md

@@ -0,0 +1,71 @@
+# HoverCard
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+悬停卡片 HoverCard
+鼠标悬停时展示补充信息的弹出卡片，支持自定义打开 / 关闭延时与尖角箭头。
+
+## 使用场景
+
+- 用户名称悬停展示个人信息
+- 链接悬停预览内容
+- 无需点击即可查看详情
+- 组合结构：HoverCard > HoverCardTrigger + HoverCardContent (> HoverCardArrow?)
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `open` | `boolean` | – | – | 受控显示状态。 |
+| `defaultOpen` | `boolean` | `false` | – | 非受控初始显示状态。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 显示 / 关闭状态变化回调。 |
+| `openDelay` | `number` | `700` | – | 悬停多久后打开（毫秒）。 |
+| `closeDelay` | `number` | `300` | – | 离开多久后关闭（毫秒）。 |
+| `container` | `HTMLElement \| null` | `document.body` | – | 浮层渲染容器，透传给 Portal。 |
+
+## 示例
+
+### CustomDelay
+
+自定义打开 / 关闭延时。
+
+```tsx
+<div className="flex items-center gap-4">
+  <HoverCard openDelay={0} closeDelay={0}>
+    <HoverCardTrigger asChild>
+      <Button>立即</Button>
+    </HoverCardTrigger>
+    <HoverCardContent>
+      <p className="text-muted-foreground">openDelay=0 / closeDelay=0</p>
+    </HoverCardContent>
+  </HoverCard>
+  <HoverCard openDelay={1000} closeDelay={300}>
+    <HoverCardTrigger asChild>
+      <Button>1s</Button>
+    </HoverCardTrigger>
+    <HoverCardContent>
+      <p className="text-muted-foreground">
+        openDelay=1000 / closeDelay=300
+      </p>
+    </HoverCardContent>
+  </HoverCard>
+</div>
+```
+
+### WithArrow
+
+显示尖角箭头。
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button>带箭头</Button>
+  </HoverCardTrigger>
+  <HoverCardContent>
+    <p className="text-muted-foreground">带尖角箭头的悬浮卡片。</p>
+    <HoverCardArrow />
+  </HoverCardContent>
+</HoverCard>
+```

package/src/components/hover-card/stories.tsx

@@ -0,0 +1,107 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import {
+  HoverCard,
+  HoverCardArrow,
+  HoverCardContent,
+  HoverCardTrigger,
+} from './index';
+import { Button } from '@/components/button';
+
+const meta: Meta<typeof HoverCard> = {
+  title: '数据展示 · Data Display/HoverCard 悬浮卡片',
+  component: HoverCard,
+  tags: ['autodocs'],
+};
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** 基础悬浮卡片，悬停链接时显示详细信息。 */
+export const Default: Story = {
+  render: () => (
+    <HoverCard>
+      <HoverCardTrigger asChild>
+        <a
+          href="#"
+          className="text-xs font-medium underline underline-offset-4"
+        >
+          @teamix
+        </a>
+      </HoverCardTrigger>
+      <HoverCardContent className="w-64">
+        <div className="flex flex-col gap-2">
+          <p className="text-xs font-medium">Teamix UI</p>
+          <p className="text-xs text-muted-foreground">
+            企业级 React 组件库，基于 Radix + Tailwind CSS 构建。
+          </p>
+          <p className="text-xs text-muted-foreground">加入于 2024 年 1 月</p>
+        </div>
+      </HoverCardContent>
+    </HoverCard>
+  ),
+};
+
+/** 12 方向矩阵：side × align 组合。 */
+export const AllPositions: Story = {
+  render: () => {
+    const sides = ['top', 'right', 'bottom', 'left'] as const;
+    const aligns = ['start', 'center', 'end'] as const;
+    return (
+      <div className="grid grid-cols-3 gap-4">
+        {sides.flatMap((side) =>
+          aligns.map((align) => (
+            <HoverCard key={`${side}-${align}`}>
+              <HoverCardTrigger asChild>
+                <Button>{`${side}-${align}`}</Button>
+              </HoverCardTrigger>
+              <HoverCardContent side={side} align={align}>
+                <p className="text-muted-foreground">{`${side} / ${align}`}</p>
+              </HoverCardContent>
+            </HoverCard>
+          )),
+        )}
+      </div>
+    );
+  },
+};
+
+/** 自定义打开 / 关闭延时。 */
+export const CustomDelay: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <HoverCard openDelay={0} closeDelay={0}>
+        <HoverCardTrigger asChild>
+          <Button>立即</Button>
+        </HoverCardTrigger>
+        <HoverCardContent>
+          <p className="text-muted-foreground">openDelay=0 / closeDelay=0</p>
+        </HoverCardContent>
+      </HoverCard>
+      <HoverCard openDelay={1000} closeDelay={300}>
+        <HoverCardTrigger asChild>
+          <Button>1s</Button>
+        </HoverCardTrigger>
+        <HoverCardContent>
+          <p className="text-muted-foreground">
+            openDelay=1000 / closeDelay=300
+          </p>
+        </HoverCardContent>
+      </HoverCard>
+    </div>
+  ),
+};
+
+/** 显示尖角箭头。 */
+export const WithArrow: Story = {
+  render: () => (
+    <HoverCard>
+      <HoverCardTrigger asChild>
+        <Button>带箭头</Button>
+      </HoverCardTrigger>
+      <HoverCardContent>
+        <p className="text-muted-foreground">带尖角箭头的悬浮卡片。</p>
+        <HoverCardArrow />
+      </HoverCardContent>
+    </HoverCard>
+  ),
+};