@teamix-evo/ui 0.1.1

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

@@ -0,0 +1,92 @@
+---
+id: hover-card
+name: HoverCard
+type: component
+category: feedback
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# HoverCard
+
+悬浮信息卡 — Radix HoverCard 包装。**shadcn-only**(antd 无对标 — antd Tooltip 仅文字,Popover 是 click 触发,HoverCard 是 hover 触发的富内容)。
+
+`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 -->
+_(no props)_
+<!-- 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 状态混乱
+
+## 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>
+```

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

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { HoverCard, HoverCardTrigger, HoverCardContent } from './hover-card';
+import { Avatar, AvatarImage, AvatarFallback } from '@/components/avatar/avatar';
+
+const meta: Meta<typeof HoverCardContent> = {
+  title: '反馈与浮层 · Feedback/HoverCard',
+  component: HoverCardContent,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '悬浮卡片 — 鼠标悬停时延迟展示更多信息(常用于用户名片、链接预览)。基于 Radix HoverCard，**仅鼠标悬停触发**(键盘聚焦不触发，交互场景与 Tooltip / Popover 互补)；支持 `side` / `align` 定位与 `openDelay` / `closeDelay`。shadcn 专有，antd 可由 `Popover` 的 trigger="hover" 近似实现。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/design`，无 mock。',
+      },
+    },
+  },
+  argTypes: {
+    side: {
+      control: 'inline-radio',
+      options: ['top', 'right', 'bottom', 'left'],
+    },
+    align: {
+      control: 'inline-radio',
+      options: ['start', 'center', 'end'],
+    },
+  },
+  args: { side: 'bottom', align: 'center' },
+  decorators: [
+    (Story) => (
+      <div className="flex h-48 items-center justify-center">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof HoverCardContent>;
+
+export const Playground: Story = {
+  render: (args) => (
+    <HoverCard openDelay={150}>
+      <HoverCardTrigger asChild>
+        <a
+          href="#"
+          onClick={(e) => e.preventDefault()}
+          className="font-medium text-primary hover:underline"
+        >
+          @lyca
+        </a>
+      </HoverCardTrigger>
+      <HoverCardContent {...args}>
+        <div className="flex gap-3">
+          <Avatar>
+            <AvatarImage src="https://github.com/shadcn.png" />
+            <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 Dec 2020
+            </p>
+          </div>
+        </div>
+      </HoverCardContent>
+    </HoverCard>
+  ),
+};

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

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import * as HoverCardPrimitive from '@radix-ui/react-hover-card';
+
+import { cn } from '@/utils/cn';
+
+const HoverCard = HoverCardPrimitive.Root;
+const HoverCardTrigger = HoverCardPrimitive.Trigger;
+
+export interface HoverCardContentProps
+  extends React.ComponentPropsWithoutRef<typeof HoverCardPrimitive.Content> {}
+
+const HoverCardContent = React.forwardRef<
+  React.ElementRef<typeof HoverCardPrimitive.Content>,
+  HoverCardContentProps
+>(({ className, align = 'center', sideOffset = 4, ...props }, ref) => (
+  <HoverCardPrimitive.Content
+    ref={ref}
+    align={align}
+    sideOffset={sideOffset}
+    className={cn(
+      'z-50 w-64 rounded-md border bg-popover p-4 text-sm text-popover-foreground shadow-md outline-none animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 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',
+      className,
+    )}
+    {...props}
+  />
+));
+HoverCardContent.displayName = HoverCardPrimitive.Content.displayName;
+
+export { HoverCard, HoverCardTrigger, HoverCardContent };

package/src/components/image/image.meta.md

@@ -0,0 +1,94 @@
+---
+id: image
+name: Image
+type: component
+category: foundation
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Image
+
+图片 — antd 独有补足。**自动处理加载态(Skeleton 占位)+ 失败态(图标)+ 点击预览**(Dialog 模态展示原图)。
+
+## When to use
+
+- 用户上传 / 远程图片(尺寸不可控,需要占位避免布局抖动)
+- 详情页大图 + 点击放大查看
+- 图片画廊 / 缩略图列表
+
+## When NOT to use
+
+- 装饰图标 → `lucide-react`
+- 强需求 lazy-load + 优化 → 用框架自带(Next.js `<Image>`)
+- 仅显示固定尺寸图标 → `<img>` 直接用
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `src` | `string` | – | ✓ | – |
+| `alt` | `string` | – | ✓ | – |
+| `preview` | `boolean` | `true` | – | 是否启用点击预览(antd `preview` 并集) — 点击后弹模态展示原图。 |
+| `fallback` | `React.ReactNode` | – | – | 加载失败时显示的占位元素;不传则用默认 `ImageOff` 图标。 |
+| `placeholder` | `React.ReactNode` | – | – | 加载中显示的占位 — 默认 Skeleton 占位与图片同尺寸。 |
+| `className` | `string` | – | – | 容器 className(图片本身用 `imgClassName`)。 |
+| `imgClassName` | `string` | – | – | 真实 `<img>` 的 className(尺寸 / 圆角 / object-fit)。 |
+<!-- auto:props:end -->
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add image` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `dialog` | component | 模态对话框 — Radix Dialog + antd Modal 并集(组合式 Header/Footer/Title/Description) |
+| `skeleton` | component | 骨架屏 — shadcn pulse 单元素 + antd Avatar/Image/Button/Input/Paragraph 子家族,自动 motion-reduce |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+## AI 生成纪律
+
+- **`alt` 必填**:无障碍要求(屏幕阅读器朗读)
+- **`width / height` 或容器 `className` 必有一个**:否则加载前占位高度为 0,导致布局抖动
+- **`preview={false}` 用于头像 / 小缩略图**:不需要点击放大的场景
+- **`fallback` 自定义占位**:品牌侧统一图(LOGO 灰)用 `<img src="/fallback.svg" />` 传入
+- **不要嵌套 Image**:嵌套预览模态行为混乱
+
+## Examples
+
+```tsx
+import { Image } from '@/components/ui/image';
+
+// 基础(自带预览)
+<Image
+  src="/cover.jpg"
+  alt="项目封面"
+  className="rounded-md"
+  imgClassName="size-64 object-cover"
+/>
+
+// 关闭预览
+<Image
+  src="/avatar.jpg"
+  alt="头像"
+  preview={false}
+  imgClassName="size-10 rounded-full object-cover"
+/>
+
+// 自定义失败占位
+<Image
+  src="/might-fail.jpg"
+  alt="..."
+  fallback={<img src="/brand-fallback.svg" alt="" />}
+  imgClassName="size-32 object-cover"
+/>
+```

package/src/components/image/image.stories.tsx

@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { Image } from './image';
+
+const meta: Meta<typeof Image> = {
+  title: '基础原语 · Foundation/Image',
+  component: Image,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '图片 — 自动处理加载(Skeleton 占位)+ 失败(图标占位)+ 点击预览(Dialog 模态原图)。alt 必填(无障碍)。OpenTrek tokens 适配,等价 antd Image。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Image>;
+
+export const Default: Story = {
+  render: () => (
+    <Image
+      src="https://placehold.co/640x360/e5e7eb/6b7280?text=Cover"
+      alt="封面"
+      className="rounded-md"
+      imgClassName="w-64 object-cover"
+    />
+  ),
+};
+
+export const Avatar: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Image
+      src="https://github.com/shadcn.png"
+      alt="头像"
+      preview={false}
+      className="rounded-full"
+      imgClassName="size-12 object-cover rounded-full"
+    />
+  ),
+};
+
+export const ErrorState: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <Image
+      src="https://this-domain-does-not-exist-xyz.example/x.jpg"
+      alt="加载失败示例"
+      className="rounded-md"
+      imgClassName="size-48 object-cover"
+    />
+  ),
+};

package/src/components/image/image.tsx

@@ -0,0 +1,138 @@
+import * as React from 'react';
+import { ImageOff, X } from 'lucide-react';
+
+import { cn } from '@/utils/cn';
+import {
+  Dialog,
+  DialogContent,
+  DialogTrigger,
+} from '@/components/dialog/dialog';
+import { Skeleton } from '@/components/skeleton/skeleton';
+
+export interface ImageProps
+  extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, 'src' | 'placeholder'> {
+  src: string;
+  alt: string;
+  /**
+   * 是否启用点击预览(antd `preview` 并集) — 点击后弹模态展示原图。
+   * @default true
+   */
+  preview?: boolean;
+  /**
+   * 加载失败时显示的占位元素;不传则用默认 `ImageOff` 图标。
+   */
+  fallback?: React.ReactNode;
+  /**
+   * 加载中显示的占位 — 默认 Skeleton 占位与图片同尺寸。
+   */
+  placeholder?: React.ReactNode;
+  /** 容器 className(图片本身用 `imgClassName`)。 */
+  className?: string;
+  /** 真实 `<img>` 的 className(尺寸 / 圆角 / object-fit)。 */
+  imgClassName?: string;
+}
+
+const Image = React.forwardRef<HTMLImageElement, ImageProps>(
+  (
+    {
+      src,
+      alt,
+      preview = true,
+      fallback,
+      placeholder,
+      className,
+      imgClassName,
+      onLoad,
+      onError,
+      ...props
+    },
+    ref,
+  ) => {
+    const [status, setStatus] = React.useState<
+      'loading' | 'loaded' | 'error'
+    >('loading');
+
+    const img = (
+      <img
+        ref={ref}
+        src={src}
+        alt={alt}
+        onLoad={(e) => {
+          setStatus('loaded');
+          onLoad?.(e);
+        }}
+        onError={(e) => {
+          setStatus('error');
+          onError?.(e);
+        }}
+        className={cn(
+          'block transition-opacity',
+          status !== 'loaded' && 'opacity-0',
+          imgClassName,
+        )}
+        {...props}
+      />
+    );
+
+    const overlay = (
+      <>
+        {status === 'loading' ? (
+          <div className="absolute inset-0">
+            {placeholder ?? <Skeleton className="size-full rounded-[inherit]" />}
+          </div>
+        ) : null}
+        {status === 'error' ? (
+          <div className="absolute inset-0 flex flex-col items-center justify-center gap-1 rounded-[inherit] bg-muted text-muted-foreground">
+            {fallback ?? (
+              <>
+                <ImageOff className="size-6" />
+                <span className="text-xs">加载失败</span>
+              </>
+            )}
+          </div>
+        ) : null}
+      </>
+    );
+
+    const inner = (
+      <span
+        className={cn(
+          'relative inline-block overflow-hidden',
+          preview &&
+            status === 'loaded' &&
+            'cursor-zoom-in transition-opacity hover:opacity-90',
+          className,
+        )}
+      >
+        {img}
+        {overlay}
+      </span>
+    );
+
+    if (!preview || status !== 'loaded') return inner;
+
+    return (
+      <Dialog>
+        <DialogTrigger asChild>{inner}</DialogTrigger>
+        <DialogContent
+          className="max-w-[90vw] border-0 bg-transparent p-0 shadow-none"
+          showClose={false}
+        >
+          <div className="relative">
+            <img
+              src={src}
+              alt={alt}
+              className="max-h-[85vh] w-auto rounded-md object-contain"
+            />
+            <div className="pointer-events-none absolute -top-3 -right-3 flex size-8 items-center justify-center rounded-full bg-background text-foreground shadow">
+              <X className="size-4" />
+            </div>
+          </div>
+        </DialogContent>
+      </Dialog>
+    );
+  },
+);
+Image.displayName = 'Image';
+
+export { Image };

package/src/components/input/input.meta.md

@@ -0,0 +1,109 @@
+---
+id: input
+name: Input
+type: component
+category: form
+since: 0.1.0
+package: "@teamix-evo/ui"
+---
+
+# Input
+
+文本输入框 — shadcn 简洁版基底 + antd 的 `prefix / suffix / clearable / showCount / addonBefore / addonAfter / size`。
+单组件覆盖大部分表单输入场景,保持 forwardRef + 原生 `<input>` 透传。
+
+## When to use
+
+- 任何文本输入(text / email / password / number / search / tel / url)
+- 配合 `prefix` 加搜索图标
+- 配合 `addonBefore="https://"` 输入域名
+- 配合 `clearable` 给搜索框一键清空
+- 配合 `showCount + maxLength` 给社媒发文限制字数
+
+## When NOT to use
+
+- 多行文本 → `Textarea`
+- 数字微调 → `Input type="number"` 已足够,需要步进按钮考虑独立 `InputNumber`
+- 选择类 → `Select` / `Combobox`
+- OTP 验证码 → `InputOTP`(v0.x)
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `prefix` | `React.ReactNode` | – | – | 输入框前置图标 / 文本(antd `prefix` 并集)。 |
+| `suffix` | `React.ReactNode` | – | – | 输入框后置图标 / 文本(antd `suffix` 并集)。 |
+| `clearable` | `boolean` | `false` | – | 显示清除按钮,有内容时点击清空(antd `allowClear` 并集)。 |
+| `showCount` | `boolean` | `false` | – | 显示字符计数(antd `showCount` 并集);需配合 `maxLength` 一起使用。 |
+| `addonBefore` | `React.ReactNode` | – | – | 输入框前置标签(antd `addonBefore` 并集),与外层组合形成 input-group。 |
+| `addonAfter` | `React.ReactNode` | – | – | 输入框后置标签(antd `addonAfter` 并集)。 |
+| `size` | `'sm' \| 'default' \| 'lg'` | `"default"` | – | 尺寸。 |
+| `value` | `string` | – | – | 受控值,用于 clearable / showCount 的逻辑;未传时回退到 uncontrolled 行为。 |
+| `defaultValue` | `string` | – | – | uncontrolled 初始值。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add input` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0
+```
+<!-- auto:deps:end -->
+
+> 透传所有 `<input>` 原生属性(`type` / `placeholder` / `name` / `id` / `aria-*` / `onChange` / ...)。
+
+## AI 生成纪律
+
+- **`prefix/suffix` 与 `addonBefore/addonAfter` 区别**:`prefix/suffix` 在边框**内**,`addon*` 是独立按钮形态在边框**外**(常用于域名 / 单位 / 协议头)
+- **`showCount` 必须配 `maxLength`**:无 maxLength 时 showCount 不显示
+- **`clearable` 与 `suffix` 互斥位置**:有内容时 clear 优先,suffix 仍渲染但视觉权重需协调;**不要**同时塞太多 affix 内容
+- **type="password" 的可见切换**:用 `suffix={<Eye />}` + 状态控制 type 切换(组件不内置,业务侧做)
+- **`type="search"` 配合 `clearable`**:搜索框最佳搭档,提交按钮用 `addonAfter`
+- **不要硬编码颜色**:`bg-background` / `border-input` / `placeholder:text-muted-foreground` 都是 design token,**不要**改成 `bg-white`
+
+## Examples
+
+```tsx
+import { Input } from '@/components/ui/input';
+import { Search, Mail } from 'lucide-react';
+
+// 基础
+<Input placeholder="请输入..." />
+
+// 受控
+const [v, setV] = React.useState('');
+<Input value={v} onChange={(e) => setV(e.target.value)} />
+
+// 前置图标
+<Input prefix={<Search />} placeholder="搜索..." />
+
+// 可清除 + 字数统计
+<Input clearable showCount maxLength={140} placeholder="动态..." />
+
+// 域名 input(addon-before)
+<Input addonBefore="https://" addonAfter=".com" defaultValue="teamix-evo" />
+
+// 邮箱 + suffix
+<Input type="email" suffix={<Mail />} placeholder="you@example.com" />
+
+// 尺寸
+<Input size="sm" placeholder="紧凑" />
+<Input size="lg" placeholder="宽松" />
+```