@neynar/ui 0.4.0 → 0.5.0

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

@@ -1,354 +1,891 @@
-import type { Meta, StoryObj } from "@storybook/react-vite";
-import { Calendar, User } from "lucide-react";
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  CalendarIcon,
+  CheckCircle2Icon,
+  MapPinIcon,
+  UsersIcon,
+} from "lucide-react";
+
 import { Avatar, AvatarFallback, AvatarImage } from "../avatar";
 import { Badge } from "../badge";
 import { Button } from "../button";
 import { HoverCard, HoverCardContent, HoverCardTrigger } from "../hover-card";
 
-const meta = {
-  title: "Overlays/HoverCard",
+const meta: Meta<typeof HoverCard> = {
+  title: "Components/Overlays & Dialogs/HoverCard",
   component: HoverCard,
   parameters: {
     layout: "centered",
-    docs: {
-      description: {
-        component:
-          "A hover card component for displaying rich content when hovering over a trigger element. Built with Radix UI and Tailwind CSS 4.",
-      },
-    },
   },
   argTypes: {
+    defaultOpen: {
+      control: "boolean",
+      description: "Initial open state (uncontrolled)",
+    },
+    open: {
+      control: "boolean",
+      description: "Controlled open state",
+    },
     openDelay: {
-      control: { type: "number" },
-      description: "The delay in milliseconds before the hover card opens",
+      control: { type: "number", min: 0, max: 1000, step: 50 },
+      description: "Delay in ms before the hover card opens (default: 700)",
     },
     closeDelay: {
-      control: { type: "number" },
-      description: "The delay in milliseconds before the hover card closes",
+      control: { type: "number", min: 0, max: 1000, step: 50 },
+      description: "Delay in ms before the hover card closes (default: 300)",
     },
+    // Hide event handlers
+    onOpenChange: { table: { disable: true } },
+    children: { table: { disable: true } },
   },
-} satisfies Meta<typeof HoverCard>;
+};
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-// Interactive playground with all customizable props
-export const Interactive: Story = {
-  args: {
-    openDelay: 700,
-    closeDelay: 300,
-  },
-  argTypes: {
-    openDelay: {
-      control: { type: "range", min: 0, max: 2000, step: 100 },
-      description: "Delay in milliseconds before opening",
-    },
-    closeDelay: {
-      control: { type: "range", min: 0, max: 1000, step: 50 },
-      description: "Delay in milliseconds before closing",
-    },
-  },
-  render: (args) => (
-    <div className="flex justify-center p-8">
-      <HoverCard openDelay={args.openDelay} closeDelay={args.closeDelay}>
-        <HoverCardTrigger asChild>
-          <Button variant="link">@nextjs</Button>
-        </HoverCardTrigger>
-        <HoverCardContent className="w-80">
-          <div className="flex justify-between gap-4">
-            <Avatar>
-              <AvatarImage src="https://github.com/vercel.png" />
-              <AvatarFallback>VC</AvatarFallback>
-            </Avatar>
-            <div className="space-y-1">
-              <h4 className="text-sm font-semibold">@nextjs</h4>
-              <p className="text-sm text-muted-foreground">
-                The React Framework – created and maintained by @vercel.
-              </p>
-              <div className="flex items-center pt-2">
-                <Calendar className="mr-2 h-4 w-4 opacity-70" />
-                <span className="text-xs text-muted-foreground">
-                  Joined December 2021
-                </span>
-              </div>
-            </div>
-          </div>
-        </HoverCardContent>
-      </HoverCard>
-    </div>
-  ),
+/**
+ * Farcaster User Profile Preview - A realistic scenario showing hover cards
+ * for previewing user profiles in the Neynar Dashboard feed.
+ */
+export const InContext: Story = {
   parameters: {
-    docs: {
-      description: {
-        story: "Interactive playground to test all hover card props and behaviors. Adjust the timing controls to see how delays affect the user experience.",
-      },
-    },
+    layout: "padded",
   },
-};
-
-// Showcase of different variants and positioning options
-export const Variants: Story = {
-  render: () => (
-    <div className="grid grid-cols-2 gap-8 p-8">
-      {/* User Profile */}
-      <div className="space-y-4">
-        <h3 className="font-semibold">User Profile</h3>
+  render: () => {
+    function UserProfileHoverCard({
+      username,
+      displayName,
+      avatarUrl,
+      bio,
+      followers,
+      following,
+      location,
+      joinDate,
+      verified,
+    }: {
+      username: string;
+      displayName: string;
+      avatarUrl: string;
+      bio: string;
+      followers: number;
+      following: number;
+      location?: string;
+      joinDate: string;
+      verified?: boolean;
+    }) {
+      return (
         <HoverCard>
-          <HoverCardTrigger asChild>
-            <Button variant="ghost" className="justify-start">
-              <Avatar className="h-6 w-6 mr-2">
-                <AvatarImage src="https://github.com/shadcn.png" />
-                <AvatarFallback>CN</AvatarFallback>
+          <HoverCardTrigger>
+            <button className="inline-flex items-center gap-2 rounded-md p-1 transition-colors hover:bg-muted">
+              <Avatar size="sm">
+                <AvatarImage src={avatarUrl} alt={displayName} />
+                <AvatarFallback>
+                  {displayName.slice(0, 2).toUpperCase()}
+                </AvatarFallback>
               </Avatar>
-              @shadcn
-            </Button>
+              <span className="font-medium hover:underline">@{username}</span>
+            </button>
           </HoverCardTrigger>
           <HoverCardContent className="w-80">
-            <div className="flex justify-between gap-4">
-              <Avatar>
-                <AvatarImage src="https://github.com/shadcn.png" />
-                <AvatarFallback>CN</AvatarFallback>
-              </Avatar>
-              <div className="space-y-1">
-                <h4 className="text-sm font-semibold">@shadcn</h4>
-                <p className="text-sm text-muted-foreground">
-                  Creator of shadcn/ui. Building beautiful, accessible components.
-                </p>
-                <div className="flex gap-1 pt-2">
-                  <Badge variant="secondary" className="text-xs">TypeScript</Badge>
-                  <Badge variant="secondary" className="text-xs">React</Badge>
+            <div className="space-y-3">
+              {/* Header with avatar and follow button */}
+              <div className="flex items-start justify-between">
+                <div className="flex items-center gap-3">
+                  <Avatar size="lg">
+                    <AvatarImage src={avatarUrl} alt={displayName} />
+                    <AvatarFallback>
+                      {displayName.slice(0, 2).toUpperCase()}
+                    </AvatarFallback>
+                  </Avatar>
+                  <div>
+                    <div className="flex items-center gap-1.5">
+                      <p className="font-semibold">{displayName}</p>
+                      {verified && (
+                        <CheckCircle2Icon
+                          className="text-primary size-4"
+                          aria-label="Verified"
+                        />
+                      )}
+                    </div>
+                    <p className="text-muted-foreground text-sm">@{username}</p>
+                  </div>
+                </div>
+                <Button size="sm">Follow</Button>
+              </div>
+
+              {/* Bio */}
+              <p className="text-sm leading-relaxed">{bio}</p>
+
+              {/* Stats */}
+              <div className="flex items-center gap-4 text-sm">
+                <div className="flex items-center gap-1">
+                  <UsersIcon className="text-muted-foreground size-3.5" />
+                  <span className="font-semibold">
+                    {followers.toLocaleString()}
+                  </span>
+                  <span className="text-muted-foreground">followers</span>
+                </div>
+                <div className="flex items-center gap-1">
+                  <span className="font-semibold">
+                    {following.toLocaleString()}
+                  </span>
+                  <span className="text-muted-foreground">following</span>
+                </div>
+              </div>
+
+              {/* Metadata */}
+              <div className="text-muted-foreground flex flex-wrap items-center gap-3 text-xs">
+                {location && (
+                  <div className="flex items-center gap-1">
+                    <MapPinIcon className="size-3.5" />
+                    <span>{location}</span>
+                  </div>
+                )}
+                <div className="flex items-center gap-1">
+                  <CalendarIcon className="size-3.5" />
+                  <span>Joined {joinDate}</span>
                 </div>
               </div>
             </div>
           </HoverCardContent>
         </HoverCard>
+      );
+    }
+
+    return (
+      <div className="w-full max-w-2xl space-y-6">
+        {/* Feed simulation */}
+        <div>
+          <h2 className="mb-4 text-lg font-semibold">Recent Casts</h2>
+          <div className="space-y-4">
+            {/* Cast 1 */}
+            <div className="border-border rounded-lg border p-4">
+              <div className="mb-2 flex items-center gap-2">
+                <UserProfileHoverCard
+                  username="dwr"
+                  displayName="Dan Romero"
+                  avatarUrl="https://i.imgur.com/DmDQRdx.jpg"
+                  bio="Building Farcaster and Warpcast. Previously VP Eng at Coinbase."
+                  followers={124500}
+                  following={428}
+                  location="Los Angeles, CA"
+                  joinDate="Oct 2020"
+                  verified
+                />
+                <span className="text-muted-foreground text-sm">2h ago</span>
+              </div>
+              <p className="text-sm">
+                Excited to share the latest updates to Farcaster protocol. New
+                features coming soon!
+              </p>
+            </div>
+
+            {/* Cast 2 */}
+            <div className="border-border rounded-lg border p-4">
+              <div className="mb-2 flex items-center gap-2">
+                <UserProfileHoverCard
+                  username="v"
+                  displayName="Varun Srinivasan"
+                  avatarUrl="https://i.imgur.com/gF4B4Kl.jpg"
+                  bio="Co-founder of Farcaster. Formerly at Coinbase and Microsoft."
+                  followers={89200}
+                  following={312}
+                  location="San Francisco, CA"
+                  joinDate="Oct 2020"
+                  verified
+                />
+                <span className="text-muted-foreground text-sm">4h ago</span>
+              </div>
+              <p className="text-sm">
+                Just pushed some performance improvements to the hub network.
+                Should see faster sync times.
+              </p>
+            </div>
+
+            {/* Cast 3 */}
+            <div className="border-border rounded-lg border p-4">
+              <div className="mb-2 flex items-center gap-2">
+                <UserProfileHoverCard
+                  username="deodad"
+                  displayName="Rish"
+                  avatarUrl="https://i.imgur.com/2WQtz2K.jpg"
+                  bio="Building @neynar - developer tools for Farcaster. Previously at Meta."
+                  followers={15800}
+                  following={524}
+                  location="New York, NY"
+                  joinDate="Jan 2023"
+                />
+                <span className="text-muted-foreground text-sm">6h ago</span>
+              </div>
+              <p className="text-sm">
+                New Neynar API endpoints just dropped. Check out the docs for
+                more details!
+              </p>
+            </div>
+          </div>
+        </div>
       </div>
+    );
+  },
+};
+
+/**
+ * Complete design system reference showing all positioning options,
+ * content variations, and interaction patterns.
+ */
+export const Variants: Story = {
+  parameters: {
+    layout: "padded",
+  },
+  render: () => (
+    <div className="w-full max-w-4xl space-y-12">
+      {/* Positioning Options */}
+      <section className="space-y-6">
+        <div>
+          <h3 className="text-lg font-semibold">Positioning Options</h3>
+          <p className="text-muted-foreground text-sm">
+            HoverCard can be positioned on all sides of the trigger element.
+          </p>
+        </div>
+        <div className="grid grid-cols-2 gap-8 md:grid-cols-4">
+          {/* Top */}
+          <div className="flex flex-col items-center gap-4">
+            <span className="text-muted-foreground text-sm font-medium">
+              Top
+            </span>
+            <HoverCard>
+              <HoverCardTrigger>
+                <Button variant="outline" size="sm">
+                  Top
+                </Button>
+              </HoverCardTrigger>
+              <HoverCardContent side="top">
+                <div className="space-y-1">
+                  <h4 className="font-semibold">Positioned Top</h4>
+                  <p className="text-muted-foreground text-xs">
+                    This card appears above the trigger.
+                  </p>
+                </div>
+              </HoverCardContent>
+            </HoverCard>
+          </div>
+
+          {/* Right */}
+          <div className="flex flex-col items-center gap-4">
+            <span className="text-muted-foreground text-sm font-medium">
+              Right
+            </span>
+            <HoverCard>
+              <HoverCardTrigger>
+                <Button variant="outline" size="sm">
+                  Right
+                </Button>
+              </HoverCardTrigger>
+              <HoverCardContent side="right">
+                <div className="space-y-1">
+                  <h4 className="font-semibold">Positioned Right</h4>
+                  <p className="text-muted-foreground text-xs">
+                    This card appears to the right.
+                  </p>
+                </div>
+              </HoverCardContent>
+            </HoverCard>
+          </div>
 
-      {/* Repository Info */}
-      <div className="space-y-4">
-        <h3 className="font-semibold">Repository</h3>
-        <p className="text-sm">
-          Check out{" "}
+          {/* Bottom (default) */}
+          <div className="flex flex-col items-center gap-4">
+            <span className="text-muted-foreground text-sm font-medium">
+              Bottom
+            </span>
+            <HoverCard>
+              <HoverCardTrigger>
+                <Button variant="outline" size="sm">
+                  Bottom
+                </Button>
+              </HoverCardTrigger>
+              <HoverCardContent side="bottom">
+                <div className="space-y-1">
+                  <h4 className="font-semibold">Positioned Bottom</h4>
+                  <p className="text-muted-foreground text-xs">
+                    This is the default position.
+                  </p>
+                </div>
+              </HoverCardContent>
+            </HoverCard>
+          </div>
+
+          {/* Left */}
+          <div className="flex flex-col items-center gap-4">
+            <span className="text-muted-foreground text-sm font-medium">
+              Left
+            </span>
+            <HoverCard>
+              <HoverCardTrigger>
+                <Button variant="outline" size="sm">
+                  Left
+                </Button>
+              </HoverCardTrigger>
+              <HoverCardContent side="left">
+                <div className="space-y-1">
+                  <h4 className="font-semibold">Positioned Left</h4>
+                  <p className="text-muted-foreground text-xs">
+                    This card appears to the left.
+                  </p>
+                </div>
+              </HoverCardContent>
+            </HoverCard>
+          </div>
+        </div>
+      </section>
+
+      {/* Alignment Options */}
+      <section className="space-y-6">
+        <div>
+          <h3 className="text-lg font-semibold">Alignment Options</h3>
+          <p className="text-muted-foreground text-sm">
+            Control how the card aligns relative to the trigger.
+          </p>
+        </div>
+        <div className="grid grid-cols-1 gap-8 md:grid-cols-3">
+          {/* Start align */}
+          <div className="flex flex-col items-center gap-4">
+            <span className="text-muted-foreground text-sm font-medium">
+              Start
+            </span>
+            <HoverCard>
+              <HoverCardTrigger>
+                <Button variant="outline" size="sm">
+                  Align Start
+                </Button>
+              </HoverCardTrigger>
+              <HoverCardContent align="start">
+                <div className="space-y-1">
+                  <h4 className="font-semibold">Start Aligned</h4>
+                  <p className="text-muted-foreground text-xs">
+                    Aligned to the start edge.
+                  </p>
+                </div>
+              </HoverCardContent>
+            </HoverCard>
+          </div>
+
+          {/* Center align (default) */}
+          <div className="flex flex-col items-center gap-4">
+            <span className="text-muted-foreground text-sm font-medium">
+              Center
+            </span>
+            <HoverCard>
+              <HoverCardTrigger>
+                <Button variant="outline" size="sm">
+                  Align Center
+                </Button>
+              </HoverCardTrigger>
+              <HoverCardContent align="center">
+                <div className="space-y-1">
+                  <h4 className="font-semibold">Center Aligned</h4>
+                  <p className="text-muted-foreground text-xs">
+                    Centered on the trigger.
+                  </p>
+                </div>
+              </HoverCardContent>
+            </HoverCard>
+          </div>
+
+          {/* End align */}
+          <div className="flex flex-col items-center gap-4">
+            <span className="text-muted-foreground text-sm font-medium">
+              End
+            </span>
+            <HoverCard>
+              <HoverCardTrigger>
+                <Button variant="outline" size="sm">
+                  Align End
+                </Button>
+              </HoverCardTrigger>
+              <HoverCardContent align="end">
+                <div className="space-y-1">
+                  <h4 className="font-semibold">End Aligned</h4>
+                  <p className="text-muted-foreground text-xs">
+                    Aligned to the end edge.
+                  </p>
+                </div>
+              </HoverCardContent>
+            </HoverCard>
+          </div>
+        </div>
+      </section>
+
+      {/* Content Variations */}
+      <section className="space-y-6">
+        <div>
+          <h3 className="text-lg font-semibold">Content Variations</h3>
+          <p className="text-muted-foreground text-sm">
+            Different types of content that can be displayed in hover cards.
+          </p>
+        </div>
+        <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
+          {/* Simple text */}
           <HoverCard>
-            <HoverCardTrigger asChild>
-              <Button variant="link" className="p-0 h-auto">
-                shadcn/ui
+            <HoverCardTrigger>
+              <Button variant="outline" className="w-full">
+                Simple Text
+              </Button>
+            </HoverCardTrigger>
+            <HoverCardContent>
+              <p className="text-sm">
+                A simple text-only hover card with helpful information.
+              </p>
+            </HoverCardContent>
+          </HoverCard>
+
+          {/* With image */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <Button variant="outline" className="w-full">
+                With Avatar
+              </Button>
+            </HoverCardTrigger>
+            <HoverCardContent>
+              <div className="flex gap-3">
+                <Avatar>
+                  <AvatarFallback>JD</AvatarFallback>
+                </Avatar>
+                <div className="space-y-1">
+                  <h4 className="text-sm font-semibold">John Doe</h4>
+                  <p className="text-muted-foreground text-xs">
+                    Product Designer
+                  </p>
+                </div>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+
+          {/* With badges */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <Button variant="outline" className="w-full">
+                With Badges
+              </Button>
+            </HoverCardTrigger>
+            <HoverCardContent>
+              <div className="space-y-2">
+                <h4 className="text-sm font-semibold">Project Tags</h4>
+                <div className="flex flex-wrap gap-1.5">
+                  <Badge variant="secondary">React</Badge>
+                  <Badge variant="secondary">TypeScript</Badge>
+                  <Badge variant="secondary">Tailwind</Badge>
+                </div>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+
+          {/* With list */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <Button variant="outline" className="w-full">
+                With List
+              </Button>
+            </HoverCardTrigger>
+            <HoverCardContent>
+              <div className="space-y-2">
+                <h4 className="text-sm font-semibold">Quick Actions</h4>
+                <ul className="text-muted-foreground space-y-1 text-xs">
+                  <li>View details</li>
+                  <li>Edit settings</li>
+                  <li>Share link</li>
+                </ul>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+
+          {/* Rich content */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <Button variant="outline" className="w-full">
+                Rich Content
               </Button>
             </HoverCardTrigger>
             <HoverCardContent className="w-72">
+              <div className="space-y-3">
+                <div className="flex items-start gap-3">
+                  <Avatar size="sm">
+                    <AvatarFallback>FC</AvatarFallback>
+                  </Avatar>
+                  <div className="flex-1 space-y-1">
+                    <h4 className="text-sm font-semibold">
+                      Farcaster Protocol
+                    </h4>
+                    <p className="text-muted-foreground text-xs">
+                      A sufficiently decentralized social network.
+                    </p>
+                  </div>
+                </div>
+                <div className="flex gap-2">
+                  <Button size="xs" variant="secondary">
+                    Learn More
+                  </Button>
+                  <Button size="xs" variant="outline">
+                    Documentation
+                  </Button>
+                </div>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+
+          {/* Custom width */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <Button variant="outline" className="w-full">
+                Custom Width
+              </Button>
+            </HoverCardTrigger>
+            <HoverCardContent className="w-96">
               <div className="space-y-2">
-                <h4 className="text-sm font-semibold">shadcn/ui</h4>
-                <p className="text-sm text-muted-foreground">
-                  Beautifully designed components built with Radix UI and Tailwind CSS.
+                <h4 className="text-sm font-semibold">Wide Content Card</h4>
+                <p className="text-muted-foreground text-xs leading-relaxed">
+                  This hover card has a custom width to accommodate longer
+                  content. The width can be adjusted using the className prop on
+                  HoverCardContent.
                 </p>
-                <div className="flex items-center gap-4 pt-2 text-xs text-muted-foreground">
-                  <span className="flex items-center gap-1">
-                    <div className="w-3 h-3 bg-blue-500 rounded-full"></div>
-                    TypeScript
-                  </span>
-                  <span>⭐ 45.2k</span>
-                  <span>🍴 2.1k</span>
-                </div>
               </div>
             </HoverCardContent>
           </HoverCard>
-        </p>
-      </div>
+        </div>
+      </section>
 
-      {/* Custom Positioning */}
-      <div className="space-y-4">
-        <h3 className="font-semibold">Custom Position</h3>
-        <HoverCard>
-          <HoverCardTrigger asChild>
-            <Button variant="outline">Top Aligned</Button>
-          </HoverCardTrigger>
-          <HoverCardContent side="top" align="start" className="w-60">
-            <div className="space-y-1">
-              <h4 className="font-semibold">Custom Position</h4>
-              <p className="text-sm text-muted-foreground">
-                This card appears above with start alignment.
-              </p>
-            </div>
-          </HoverCardContent>
-        </HoverCard>
-      </div>
+      {/* Delay Options */}
+      <section className="space-y-6">
+        <div>
+          <h3 className="text-lg font-semibold">Timing Controls</h3>
+          <p className="text-muted-foreground text-sm">
+            Control when the hover card appears and disappears.
+          </p>
+        </div>
+        <div className="grid grid-cols-1 gap-6 md:grid-cols-3">
+          {/* Quick open */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <Button variant="outline" className="w-full">
+                Instant Open
+              </Button>
+            </HoverCardTrigger>
+            <HoverCardContent>
+              <div className="space-y-1">
+                <h4 className="text-sm font-semibold">No Delay</h4>
+                <p className="text-muted-foreground text-xs">
+                  Opens immediately on hover.
+                </p>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
 
-      {/* Simple Text */}
-      <div className="space-y-4">
-        <h3 className="font-semibold">Simple Content</h3>
-        <p className="text-sm">
-          Learn about{" "}
+          {/* Default timing */}
           <HoverCard>
-            <HoverCardTrigger asChild>
-              <Button variant="link" className="p-0 h-auto">
-                React 19
+            <HoverCardTrigger>
+              <Button variant="outline" className="w-full">
+                Default Timing
               </Button>
             </HoverCardTrigger>
             <HoverCardContent>
               <div className="space-y-1">
-                <h4 className="font-semibold">React 19</h4>
-                <p className="text-sm text-muted-foreground">
-                  Latest React with Compiler and improved performance.
+                <h4 className="text-sm font-semibold">Balanced</h4>
+                <p className="text-muted-foreground text-xs">
+                  Default delay settings.
                 </p>
               </div>
             </HoverCardContent>
           </HoverCard>
-        </p>
-      </div>
+
+          {/* Slow open */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <Button variant="outline" className="w-full">
+                Delayed Open
+              </Button>
+            </HoverCardTrigger>
+            <HoverCardContent>
+              <div className="space-y-1">
+                <h4 className="text-sm font-semibold">Long Delay</h4>
+                <p className="text-muted-foreground text-xs">
+                  Opens after 500ms.
+                </p>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+        </div>
+      </section>
+
+      {/* Interactive Triggers */}
+      <section className="space-y-6">
+        <div>
+          <h3 className="text-lg font-semibold">Trigger Types</h3>
+          <p className="text-muted-foreground text-sm">
+            HoverCard works with any trigger element using.
+          </p>
+        </div>
+        <div className="flex flex-wrap items-center gap-4">
+          {/* Button trigger */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <Button variant="default" size="sm">
+                Button Trigger
+              </Button>
+            </HoverCardTrigger>
+            <HoverCardContent>
+              <p className="text-sm">Triggered by a button component.</p>
+            </HoverCardContent>
+          </HoverCard>
+
+          {/* Link trigger */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <a
+                href="#"
+                className="text-primary text-sm font-medium hover:underline"
+              >
+                Link Trigger
+              </a>
+            </HoverCardTrigger>
+            <HoverCardContent>
+              <p className="text-sm">Triggered by a link element.</p>
+            </HoverCardContent>
+          </HoverCard>
+
+          {/* Badge trigger */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <span>
+                <Badge variant="secondary" className="cursor-pointer">
+                  Badge Trigger
+                </Badge>
+              </span>
+            </HoverCardTrigger>
+            <HoverCardContent>
+              <p className="text-sm">Triggered by a badge component.</p>
+            </HoverCardContent>
+          </HoverCard>
+
+          {/* Avatar trigger */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <button>
+                <Avatar className="cursor-pointer">
+                  <AvatarFallback>AT</AvatarFallback>
+                </Avatar>
+              </button>
+            </HoverCardTrigger>
+            <HoverCardContent>
+              <div className="space-y-1">
+                <h4 className="text-sm font-semibold">Avatar Trigger</h4>
+                <p className="text-muted-foreground text-xs">
+                  Triggered by an avatar.
+                </p>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+
+          {/* Text trigger */}
+          <HoverCard>
+            <HoverCardTrigger>
+              <span className="text-muted-foreground cursor-help text-sm underline decoration-dotted">
+                Text Trigger
+              </span>
+            </HoverCardTrigger>
+            <HoverCardContent>
+              <p className="text-sm">
+                Triggered by inline text with help cursor.
+              </p>
+            </HoverCardContent>
+          </HoverCard>
+        </div>
+      </section>
     </div>
   ),
-  parameters: {
-    docs: {
-      description: {
-        story: "Showcase of different hover card variants including user profiles, repository information, custom positioning, and simple text content.",
-      },
-    },
-  },
 };
 
-// Real-world usage in a dashboard-like interface
-export const InContext: Story = {
+/**
+ * Frosted hover card effect with backdrop blur over colorful backgrounds.
+ * HoverCards use 75% opacity and backdrop-blur for a frosted glass appearance.
+ */
+export const Frosted: Story = {
+  parameters: {
+    layout: "padded",
+  },
   render: () => (
-    <div className="max-w-4xl mx-auto p-6 space-y-6">
-      {/* Header with user profile */}
-      <div className="flex items-center justify-between border-b pb-4">
-        <h1 className="text-2xl font-bold">Project Dashboard</h1>
-        <div className="flex items-center gap-3">
-          <span className="text-sm text-muted-foreground">Welcome back,</span>
+    <div className="w-full max-w-4xl space-y-8">
+      <div>
+        <h3 className="text-lg font-semibold">Frosted Surface Effect</h3>
+        <p className="text-muted-foreground text-sm">
+          HoverCards use transparent backgrounds with backdrop blur for a
+          frosted glass look. Hover over the triggers to see the effect.
+        </p>
+      </div>
+
+      {/* Busy background with color blocks */}
+      <div className="relative overflow-hidden rounded-2xl p-8 bg-gradient-to-br from-indigo-500 via-purple-500 to-pink-500">
+        {/* Color blocks behind */}
+        <div className="absolute inset-0 p-4 grid grid-cols-4 gap-3 opacity-90">
+          <div className="rounded-lg bg-yellow-400 p-3">
+            <p className="font-bold text-yellow-900 text-sm">Yellow</p>
+            <p className="text-xs text-yellow-800">Lorem ipsum</p>
+          </div>
+          <div className="rounded-lg bg-green-400 p-3">
+            <p className="font-bold text-green-900 text-sm">Green</p>
+            <p className="text-xs text-green-800">Dolor sit amet</p>
+          </div>
+          <div className="rounded-lg bg-blue-400 p-3">
+            <p className="font-bold text-blue-900 text-sm">Blue</p>
+            <p className="text-xs text-blue-800">Consectetur</p>
+          </div>
+          <div className="rounded-lg bg-red-400 p-3">
+            <p className="font-bold text-red-900 text-sm">Red</p>
+            <p className="text-xs text-red-800">Adipiscing elit</p>
+          </div>
+          <div className="rounded-lg bg-orange-400 p-3">
+            <p className="font-bold text-orange-900 text-sm">Orange</p>
+            <p className="text-xs text-orange-800">Sed do eiusmod</p>
+          </div>
+          <div className="rounded-lg bg-teal-400 p-3">
+            <p className="font-bold text-teal-900 text-sm">Teal</p>
+            <p className="text-xs text-teal-800">Tempor incididunt</p>
+          </div>
+          <div className="rounded-lg bg-pink-300 p-3">
+            <p className="font-bold text-pink-900 text-sm">Pink</p>
+            <p className="text-xs text-pink-800">Ut labore et</p>
+          </div>
+          <div className="rounded-lg bg-cyan-400 p-3">
+            <p className="font-bold text-cyan-900 text-sm">Cyan</p>
+            <p className="text-xs text-cyan-800">Dolore magna</p>
+          </div>
+        </div>
+
+        {/* Triggers on top */}
+        <div className="relative flex items-center justify-center gap-8 mt-32 mb-8">
           <HoverCard>
-            <HoverCardTrigger asChild>
-              <Button variant="ghost" className="p-1">
-                <Avatar className="h-8 w-8">
-                  <AvatarImage src="https://github.com/vercel.png" />
-                  <AvatarFallback>JD</AvatarFallback>
-                </Avatar>
-              </Button>
+            <HoverCardTrigger>
+              <Button variant="secondary">Hover Me</Button>
             </HoverCardTrigger>
-            <HoverCardContent align="end" className="w-72">
+            <HoverCardContent className="w-80">
               <div className="space-y-3">
-                <div className="flex items-center gap-3">
+                <div className="flex items-start gap-3">
                   <Avatar>
-                    <AvatarImage src="https://github.com/vercel.png" />
-                    <AvatarFallback>JD</AvatarFallback>
+                    <AvatarFallback>FC</AvatarFallback>
                   </Avatar>
-                  <div>
-                    <h4 className="font-semibold">John Doe</h4>
-                    <p className="text-sm text-muted-foreground">Product Manager</p>
+                  <div className="flex-1">
+                    <h4 className="font-semibold">Frosted Glass HoverCard</h4>
+                    <p className="text-muted-foreground text-sm">@farcaster</p>
                   </div>
+                  <Button size="sm">Follow</Button>
                 </div>
-                <div className="border-t pt-2">
-                  <div className="flex flex-col gap-1">
-                    <Button size="sm" variant="ghost" className="justify-start">
-                      <User className="mr-2 h-4 w-4" />
-                      View Profile
-                    </Button>
-                    <Button size="sm" variant="ghost" className="justify-start">
-                      Settings
-                    </Button>
+                <p className="text-sm">
+                  Notice how you can see the colorful blocks behind through the
+                  75% opacity background with 12px blur.
+                </p>
+                <div className="flex gap-4 text-sm">
+                  <div>
+                    <span className="font-semibold">12.5K</span>{" "}
+                    <span className="text-muted-foreground">followers</span>
+                  </div>
+                  <div>
+                    <span className="font-semibold">428</span>{" "}
+                    <span className="text-muted-foreground">following</span>
                   </div>
                 </div>
               </div>
             </HoverCardContent>
           </HoverCard>
-        </div>
-      </div>
 
-      {/* Team section with multiple hover cards */}
-      <div className="space-y-4">
-        <h2 className="text-lg font-semibold">Team Members</h2>
-        <div className="flex gap-4">
-          {[
-            { name: "Alice Johnson", role: "Frontend Dev", avatar: "https://github.com/vercel.png", initials: "AJ" },
-            { name: "Bob Smith", role: "Backend Dev", avatar: "https://github.com/shadcn.png", initials: "BS" },
-            { name: "Carol White", role: "Designer", avatar: "https://github.com/vercel.png", initials: "CW" },
-          ].map((member, i) => (
-            <HoverCard key={i}>
-              <HoverCardTrigger asChild>
-                <Button variant="outline" className="h-auto p-3">
-                  <Avatar className="h-8 w-8 mr-2">
-                    <AvatarImage src={member.avatar} />
-                    <AvatarFallback>{member.initials}</AvatarFallback>
-                  </Avatar>
-                  <div className="text-left">
-                    <div className="font-medium text-sm">{member.name}</div>
-                    <div className="text-xs text-muted-foreground">{member.role}</div>
-                  </div>
-                </Button>
-              </HoverCardTrigger>
-              <HoverCardContent className="w-80">
-                <div className="flex gap-4">
-                  <Avatar>
-                    <AvatarImage src={member.avatar} />
-                    <AvatarFallback>{member.initials}</AvatarFallback>
+          <HoverCard>
+            <HoverCardTrigger>
+              <Button variant="secondary">Profile Card</Button>
+            </HoverCardTrigger>
+            <HoverCardContent side="top" className="w-72">
+              <div className="space-y-2">
+                <div className="flex items-center gap-3">
+                  <Avatar size="lg">
+                    <AvatarFallback>VB</AvatarFallback>
                   </Avatar>
-                  <div className="space-y-1 flex-1">
-                    <h4 className="font-semibold">{member.name}</h4>
-                    <p className="text-sm text-muted-foreground">{member.role}</p>
-                    <p className="text-xs text-muted-foreground">
-                      Available • Last seen 2h ago
+                  <div>
+                    <h4 className="font-semibold">Vitalik Buterin</h4>
+                    <p className="text-muted-foreground text-sm">
+                      @vitalik.eth
                     </p>
-                    <div className="flex gap-2 pt-2">
-                      <Button size="sm" variant="outline">Message</Button>
-                      <Button size="sm" variant="ghost">View Tasks</Button>
-                    </div>
                   </div>
                 </div>
-              </HoverCardContent>
-            </HoverCard>
-          ))}
+                <p className="text-sm">
+                  Ethereum creator. The frosted effect lets you peek through!
+                </p>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
         </div>
       </div>
 
-      {/* Project links */}
-      <div className="space-y-4">
-        <h2 className="text-lg font-semibold">Active Projects</h2>
-        <div className="grid grid-cols-2 gap-4">
-          <div className="p-4 border rounded-lg">
-            <h3 className="font-medium mb-2">Frontend Redesign</h3>
-            <p className="text-sm text-muted-foreground mb-3">
-              Built with{" "}
-              <HoverCard>
-                <HoverCardTrigger asChild>
-                  <Button variant="link" className="p-0 h-auto text-sm">
-                    Next.js 15
-                  </Button>
-                </HoverCardTrigger>
-                <HoverCardContent>
-                  <div className="space-y-2">
-                    <h4 className="font-semibold">Next.js 15</h4>
-                    <p className="text-sm text-muted-foreground">
-                      The React Framework with App Router, Server Components, and improved performance.
-                    </p>
-                  </div>
-                </HoverCardContent>
-              </HoverCard>
-              {" and "}
-              <HoverCard>
-                <HoverCardTrigger asChild>
-                  <Button variant="link" className="p-0 h-auto text-sm">
-                    Tailwind CSS
-                  </Button>
-                </HoverCardTrigger>
-                <HoverCardContent>
-                  <div className="space-y-2">
-                    <h4 className="font-semibold">Tailwind CSS</h4>
-                    <p className="text-sm text-muted-foreground">
-                      Utility-first CSS framework for rapidly building modern websites.
-                    </p>
-                  </div>
-                </HoverCardContent>
-              </HoverCard>
-            </p>
+      {/* Gradient background */}
+      <div className="relative overflow-hidden rounded-2xl p-8 bg-gradient-to-r from-cyan-500 to-blue-600">
+        <div className="absolute inset-0 flex items-center justify-center text-white/20">
+          <div className="text-center">
+            <p className="text-6xl font-bold">BACKGROUND</p>
+            <p className="text-2xl">This text is behind the hover card</p>
           </div>
         </div>
+        <div className="relative flex items-center justify-center py-16">
+          <HoverCard>
+            <HoverCardTrigger>
+              <Button variant="secondary" size="lg">
+                Hover for Frosted Effect
+              </Button>
+            </HoverCardTrigger>
+            <HoverCardContent className="w-80">
+              <div className="space-y-2">
+                <h4 className="font-semibold">Customizable Blur</h4>
+                <p className="text-sm">
+                  The frosted glass effect is controlled by CSS tokens:
+                </p>
+                <ul className="text-sm text-muted-foreground list-disc pl-4 space-y-1">
+                  <li>
+                    <code>--surface-blur: 12px</code>
+                  </li>
+                  <li>
+                    <code>--popover</code> at 75% opacity
+                  </li>
+                </ul>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+        </div>
       </div>
     </div>
   ),
-  parameters: {
-    docs: {
-      description: {
-        story: "Real-world example showing hover cards in a dashboard interface. Demonstrates user profiles, team member info, and contextual information throughout the UI.",
-      },
-    },
+};
+
+/**
+ * Interactive playground for testing hover card props and positioning.
+ */
+export const Interactive: Story = {
+  args: {
+    defaultOpen: false,
+    openDelay: 700,
+    closeDelay: 300,
   },
-};
+  render: (args) => (
+    <HoverCard {...args}>
+      <HoverCardTrigger>
+        <Button variant="outline">Hover over me</Button>
+      </HoverCardTrigger>
+      <HoverCardContent>
+        <div className="space-y-2">
+          <h4 className="font-semibold">Interactive HoverCard</h4>
+          <p className="text-sm">
+            This is a hover card that appears when you hover over the trigger
+            element.
+          </p>
+          <div className="flex items-center gap-2 pt-2">
+            <Badge variant="secondary">Interactive</Badge>
+            <Badge variant="outline">Customizable</Badge>
+          </div>
+        </div>
+      </HoverCardContent>
+    </HoverCard>
+  ),
+};