@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/form/form.tsx

@@ -1,260 +0,0 @@
-import * as React from 'react';
-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 {
-  Field,
-  FieldLabel,
-  FieldDescription,
-  FieldSection,
-  FieldActions,
-  type FieldProps,
-  type FieldLabelProps,
-  type FieldSectionProps,
-  type FieldActionsProps,
-} from '@/components/field/field';
-
-/**
- * `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,
-);
-
-/**
- * 组合 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,
-  };
-};
-
-// ─── 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>
->(({ ...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';
-
-/**
- * `FormDescription` = `FieldDescription` 包装 + 自动 `id=formDescriptionId`(给 aria-describedby 用)。
- */
-const FormDescription = React.forwardRef<
-  HTMLParagraphElement,
-  React.HTMLAttributes<HTMLParagraphElement>
->(({ className, ...props }, ref) => {
-  const { formDescriptionId } = useFormField();
-  return (
-    <FieldDescription
-      ref={ref}
-      id={formDescriptionId}
-      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>
->(({ 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}
-      role="alert"
-      className={cn('-mt-1 text-xs font-medium text-destructive', className)}
-      {...props}
-    >
-      {body}
-    </p>
-  );
-});
-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,
-  FormItem,
-  FormLabel,
-  FormControl,
-  FormDescription,
-  FormMessage,
-  FormField,
-  FieldSection as FormSection,
-  FieldActions as FormActions,
-};

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

@@ -1,92 +0,0 @@
----
-id: grid
-name: Grid
-displayName: 栅格
-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`
-
-## Props
-
-<!-- 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

@@ -1,101 +0,0 @@
-import type { Meta, StoryObj } from '@storybook/react-vite';
-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。',
-      },
-    },
-  },
-};
-
-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

@@ -1,130 +0,0 @@
-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 };

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

@@ -1,103 +0,0 @@
----
-id: hover-card
-name: HoverCard
-type: component
-category: data-display
-since: 0.1.0
-package: '@teamix-evo/ui'
-displayName: 悬浮卡片
----
-
-# HoverCard 悬浮卡片
-
-悬浮信息卡 — Radix HoverCard 包装。**shadcn-only**(antd 无对标 — antd Tooltip 仅文字,Popover 是 click 触发,HoverCard 是 hover 触发的富内容)。与 Tooltip / Popover 对齐,使用 `showArrow` 统一控制尖角(默认 `false`)。
-
-`Tooltip` 与 `HoverCard` 的边界:
-
-- 1 行简短文字 → `Tooltip`
-- 多行 / 含图片 / 含弱交互(链接 / Avatar)→ `HoverCard`
-
-## When to use
-
-- 鼠标悬浮在 @username / 资源名 上展示卡片(GitHub / Twitter 风格)
-- 列表项的 hover 预览(标题 + 摘要 + tag)
-- 缩略链接预览(URL + 简介 + 域名)
-
-## When NOT to use
-
-- 移动端首要功能 → 触屏不触发 hover,改 `Popover`
-- 强交互 → `Popover`
-- 简短文字 → `Tooltip`
-
-## Props
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表为 `HoverCardContent` 的 props;`HoverCard` Root 透传 `openDelay / closeDelay / open / defaultOpen / onOpenChange`。
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `showArrow` | `boolean` | `false` | – | 是否显示三角形箭头(antd `arrow` 并集)。 与 Tooltip / Popover 统一用 `showArrow`。 |
-<!-- auto:props:end -->
-
-## 依赖
-
-> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
-
-<!-- auto:deps:begin -->
-### 同库依赖
-
-> `teamix-evo ui add hover-card` 时,以下 entry 会被自动连带安装(无需手动 add)。
-
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-
-### npm 依赖
-
-> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
-
-```bash
-pnpm add @radix-ui/react-hover-card@^1.1.0
-```
-<!-- auto:deps:end -->
-
-## AI 生成纪律
-
-- **Trigger 用 `asChild`**:wrap 已有元素而非新增 button
-- **`openDelay` 别太短**:用户快速划过时不要把卡片闪一下;**默认 700ms** 通常合理
-- **HoverCard 内不放表单**:表单需要 click 焦点 → 用 `Popover`
-- **不要嵌套 HoverCard**:嵌套 hover 状态混乱
-- **尖角名称用 `showArrow`**:与 Tooltip / Popover 保持一致;资源卡/名片场景建议保持默认无尖角以减少视觉噪点,仅在需要强调与 trigger 的联动时开启
-
-## Examples
-
-```tsx
-import {
-  HoverCard,
-  HoverCardTrigger,
-  HoverCardContent,
-} from '@/components/ui/hover-card';
-import { Avatar, AvatarImage, AvatarFallback } from '@/components/ui/avatar';
-
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <a href="/u/lyca" className="font-medium text-primary hover:underline">
-      @lyca
-    </a>
-  </HoverCardTrigger>
-  <HoverCardContent>
-    <div className="flex gap-3">
-      <Avatar>
-        <AvatarImage src="/u/lyca.jpg" />
-        <AvatarFallback>LY</AvatarFallback>
-      </Avatar>
-      <div className="space-y-1">
-        <h4 className="text-sm font-semibold">@lyca</h4>
-        <p className="text-xs text-muted-foreground">
-          Frontend engineer · Joined 2020
-        </p>
-      </div>
-    </div>
-  </HoverCardContent>
-</HoverCard>;
-```