@teamix-evo/ui 0.1.1 → 0.3.0

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

@@ -2,16 +2,18 @@
 id: hover-card
 name: HoverCard
 type: component
-category: feedback
+category: data-display
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
+displayName: 悬浮卡片
 ---
 
-# HoverCard
+# HoverCard 悬浮卡片
 
-悬浮信息卡 — Radix HoverCard 包装。**shadcn-only**(antd 无对标 — antd Tooltip 仅文字,Popover 是 click 触发,HoverCard 是 hover 触发的富内容)。
+悬浮信息卡 — Radix HoverCard 包装。**shadcn-only**(antd 无对标 — antd Tooltip 仅文字,Popover 是 click 触发,HoverCard 是 hover 触发的富内容)。与 Tooltip / Popover 对齐,使用 `showArrow` 统一控制尖角(默认 `false`)。
 
 `Tooltip` 与 `HoverCard` 的边界:
+
 - 1 行简短文字 → `Tooltip`
 - 多行 / 含图片 / 含弱交互(链接 / Avatar)→ `HoverCard`
 
@@ -32,7 +34,9 @@ package: "@teamix-evo/ui"
 > 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。下表为 `HoverCardContent` 的 props;`HoverCard` Root 透传 `openDelay / closeDelay / open / defaultOpen / onOpenChange`。
 
 <!-- auto:props:begin -->
-_(no props)_
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `showArrow` | `boolean` | `false` | – | 是否显示三角形箭头(antd `arrow` 并集)。 与 Tooltip / Popover 统一用 `showArrow`。 |
 <!-- auto:props:end -->
 
 ## 依赖
@@ -63,18 +67,23 @@ pnpm add @radix-ui/react-hover-card@^1.1.0
 - **`openDelay` 别太短**:用户快速划过时不要把卡片闪一下;**默认 700ms** 通常合理
 - **HoverCard 内不放表单**:表单需要 click 焦点 → 用 `Popover`
 - **不要嵌套 HoverCard**:嵌套 hover 状态混乱
+- **尖角名称用 `showArrow`**:与 Tooltip / Popover 保持一致;资源卡/名片场景建议保持默认无尖角以减少视觉噪点,仅在需要强调与 trigger 的联动时开启
 
 ## Examples
 
 ```tsx
 import {
-  HoverCard, HoverCardTrigger, HoverCardContent,
+  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>
+    <a href="/u/lyca" className="font-medium text-primary hover:underline">
+      @lyca
+    </a>
   </HoverCardTrigger>
   <HoverCardContent>
     <div className="flex gap-3">
@@ -84,9 +93,11 @@ import { Avatar, AvatarImage, AvatarFallback } from '@/components/ui/avatar';
       </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>
+        <p className="text-xs text-muted-foreground">
+          Frontend engineer · Joined 2020
+        </p>
       </div>
     </div>
   </HoverCardContent>
-</HoverCard>
+</HoverCard>;
 ```

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

@@ -1,16 +1,20 @@
-import type { Meta, StoryObj } from '@storybook/react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
 import { HoverCard, HoverCardTrigger, HoverCardContent } from './hover-card';
-import { Avatar, AvatarImage, AvatarFallback } from '@/components/avatar/avatar';
+import {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+} from '@/components/avatar/avatar';
 
 const meta: Meta<typeof HoverCardContent> = {
-  title: '反馈与浮层 · Feedback/HoverCard',
+  title: '数据展示 · Data Display/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。',
+          '悬浮卡片 —— 鼠标悬停时延迟展示富内容(用户名片、链接预览、缩略卡)。基于 Radix HoverCard 实现:**仅鼠标悬停触发**,键盘聚焦不触发,与 Tooltip(纯文本)/ Popover(click 富内容)互补;支持 `side` / `align` 定位、`openDelay` / `closeDelay` 延迟、`showArrow` 尖角(命名与 Tooltip / Popover 统一)。shadcn 专有,antd 可由 `Popover trigger="hover"` 近似实现。视觉走 OpenTrek semantic tokens,所有样式来自 `@teamix-evo/tokens`,无 mock。',
       },
     },
   },
@@ -23,8 +27,9 @@ const meta: Meta<typeof HoverCardContent> = {
       control: 'inline-radio',
       options: ['start', 'center', 'end'],
     },
+    showArrow: { control: 'boolean' },
   },
-  args: { side: 'bottom', align: 'center' },
+  args: { side: 'bottom', align: 'center', showArrow: false },
   decorators: [
     (Story) => (
       <div className="flex h-48 items-center justify-center">
@@ -66,3 +71,27 @@ export const Playground: Story = {
     </HoverCard>
   ),
 };
+
+export const WithArrow: Story = {
+  name: 'showArrow · 有尖角',
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <HoverCard openDelay={150}>
+      <HoverCardTrigger asChild>
+        <a
+          href="#"
+          onClick={(e) => e.preventDefault()}
+          className="font-medium text-primary hover:underline"
+        >
+          带箭头悬浮
+        </a>
+      </HoverCardTrigger>
+      <HoverCardContent showArrow>
+        <h4 className="text-sm font-semibold">资源 · ECS i-xxx</h4>
+        <p className="mt-1 text-xs text-muted-foreground">
+          ap-southeast-1 · 4 vCPU · 8 GiB · 状态正常
+        </p>
+      </HoverCardContent>
+    </HoverCard>
+  ),
+};

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

@@ -4,26 +4,64 @@ import * as HoverCardPrimitive from '@radix-ui/react-hover-card';
 import { cn } from '@/utils/cn';
 
 const HoverCard = HoverCardPrimitive.Root;
-const HoverCardTrigger = HoverCardPrimitive.Trigger;
+const HoverCardTrigger = React.forwardRef<
+  React.ElementRef<typeof HoverCardPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof HoverCardPrimitive.Trigger>
+>(({ className, ...props }, ref) => (
+  <HoverCardPrimitive.Trigger
+    ref={ref}
+    className={cn('cursor-pointer', className)}
+    {...props}
+  />
+));
+HoverCardTrigger.displayName = HoverCardPrimitive.Trigger.displayName;
 
 export interface HoverCardContentProps
-  extends React.ComponentPropsWithoutRef<typeof HoverCardPrimitive.Content> {}
+  extends React.ComponentPropsWithoutRef<typeof HoverCardPrimitive.Content> {
+  /**
+   * 是否显示三角形箭头(antd `arrow` 并集)。
+   * 与 Tooltip / Popover 统一用 `showArrow`。
+   * @default false
+   */
+  showArrow?: boolean;
+}
 
 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}
-  />
-));
+      align = 'center',
+      sideOffset = 4,
+      showArrow = false,
+      children,
+      ...props
+    },
+    ref,
+  ) => (
+    <HoverCardPrimitive.Content
+      ref={ref}
+      align={align}
+      sideOffset={sideOffset}
+      className={cn(
+        'z-50 w-64 rounded-md border border-border bg-popover p-4 text-xs 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}
+    >
+      {children}
+      {showArrow ? (
+        <HoverCardPrimitive.Arrow
+          className="fill-popover"
+          width={10}
+          height={5}
+        />
+      ) : null}
+    </HoverCardPrimitive.Content>
+  ),
+);
 HoverCardContent.displayName = HoverCardPrimitive.Content.displayName;
 
 export { HoverCard, HoverCardTrigger, HoverCardContent };