@neynar/ui 0.3.1 → 0.5.0

package/src/components/ui/stories/item.stories.tsx

@@ -1,14 +1,19 @@
-import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { Meta, StoryObj } from "@storybook/react";
 import {
-  CheckCircle2,
-  ChevronRight,
-  Clock,
-  FileText,
-  Image as ImageIcon,
-  MoreVertical,
-  Star,
-  User,
+  CheckCircle2Icon,
+  ChevronRightIcon,
+  ClockIcon,
+  CopyIcon,
+  ExternalLinkIcon,
+  FileIcon,
+  KeyIcon,
+  MoreHorizontalIcon,
+  TrashIcon,
+  UserIcon,
+  WebhookIcon,
+  XCircleIcon,
 } from "lucide-react";
+
 import { Badge } from "../badge";
 import { Button } from "../button";
 import {
@@ -24,578 +29,921 @@ import {
   ItemTitle,
 } from "../item";
 
-const meta = {
-  title: "Layout and Structure/Item",
+const meta: Meta<typeof Item> = {
+  title: "Components/Advanced & Specialized/Item",
   component: Item,
   parameters: {
     layout: "centered",
-    docs: {
-      description: {
-        component:
-          "A flexible item component for displaying content with media, titles, descriptions, and actions. Perfect for lists, cards, and data displays.",
-      },
-    },
   },
   argTypes: {
     variant: {
-      control: { type: "select" },
+      control: "select",
       options: ["default", "outline", "muted"],
-      description: "The visual variant of the item",
+      description: "Visual style variant for the item",
     },
     size: {
-      control: { type: "select" },
-      options: ["default", "sm"],
-      description: "The size of the item",
-    },
-    asChild: {
-      control: { type: "boolean" },
-      description: "Render as a child component (e.g., for links)",
+      control: "select",
+      options: ["default", "sm", "xs"],
+      description: "Size variant affecting padding and spacing",
     },
     className: {
-      control: { type: "text" },
-      description: "Additional CSS classes to apply",
+      control: "text",
+      description: "Additional CSS classes",
     },
+    children: { table: { disable: true } },
   },
-  args: {
-    variant: "default",
-    size: "default",
-  },
-} satisfies Meta<typeof Item>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof Item>;
 
 /**
- * Interactive playground with all item properties.
+ * Neynar Dashboard - Realistic scenarios showing generic list items
+ * for API keys, webhooks, team members, and documents.
  */
-export const Interactive: Story = {
-  render: (args) => (
-    <div className="w-96">
-      <Item {...args}>
-        <ItemMedia variant="icon">
-          <FileText className="size-4" />
-        </ItemMedia>
-        <ItemContent>
-          <ItemTitle>Document Title</ItemTitle>
-          <ItemDescription>
-            A brief description of the document content.
-          </ItemDescription>
-        </ItemContent>
-        <ItemActions>
-          <Button variant="ghost" size="icon">
-            <MoreVertical className="size-4" />
-          </Button>
-        </ItemActions>
-      </Item>
-    </div>
-  ),
+export const InContext: Story = {
+  parameters: {
+    layout: "padded",
+  },
+  render: () => {
+    function DashboardLists() {
+      return (
+        <div className="w-full max-w-5xl space-y-8">
+          {/* API Keys List */}
+          <section className="space-y-4">
+            <div>
+              <h2 className="text-lg font-semibold">API Keys</h2>
+              <p className="text-muted-foreground text-sm">
+                Manage your Neynar API keys for production and development
+              </p>
+            </div>
+            <ItemGroup>
+              <Item variant="outline">
+                <ItemMedia variant="icon">
+                  <div className="bg-primary/10 text-primary rounded-md p-2">
+                    <KeyIcon className="size-5" />
+                  </div>
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>Production Key</ItemTitle>
+                  <ItemDescription>
+                    <code className="font-mono text-xs">
+                      neynar_sk_prod_****_****_8f3d
+                    </code>{" "}
+                    • Created 3 months ago
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost" size="icon-sm">
+                    <CopyIcon />
+                  </Button>
+                  <Button variant="ghost" size="icon-sm">
+                    <MoreHorizontalIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+
+              <Item variant="outline">
+                <ItemMedia variant="icon">
+                  <div className="bg-muted text-muted-foreground rounded-md p-2">
+                    <KeyIcon className="size-5" />
+                  </div>
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>Development Key</ItemTitle>
+                  <ItemDescription>
+                    <code className="font-mono text-xs">
+                      neynar_sk_dev_****_****_2a1b
+                    </code>{" "}
+                    • Created 1 week ago
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost" size="icon-sm">
+                    <CopyIcon />
+                  </Button>
+                  <Button variant="ghost" size="icon-sm">
+                    <MoreHorizontalIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+
+              <Item variant="outline">
+                <ItemMedia variant="icon">
+                  <div className="bg-red-500/10 text-red-500 rounded-md p-2">
+                    <KeyIcon className="size-5" />
+                  </div>
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>
+                    Staging Key
+                    <Badge variant="destructive">Revoked</Badge>
+                  </ItemTitle>
+                  <ItemDescription>
+                    <code className="font-mono text-xs">
+                      neynar_sk_stg_****_****_9c4e
+                    </code>{" "}
+                    • Revoked 2 days ago
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost" size="icon-sm" disabled>
+                    <CopyIcon />
+                  </Button>
+                  <Button variant="ghost" size="icon-sm">
+                    <TrashIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+            </ItemGroup>
+          </section>
+
+          {/* Webhook Endpoints List */}
+          <section className="space-y-4">
+            <div>
+              <h2 className="text-lg font-semibold">Webhook Endpoints</h2>
+              <p className="text-muted-foreground text-sm">
+                Monitor delivery status and manage webhook endpoints
+              </p>
+            </div>
+            <ItemGroup>
+              <Item variant="muted">
+                <ItemMedia variant="icon">
+                  <WebhookIcon className="text-green-500 size-5" />
+                </ItemMedia>
+                <ItemContent>
+                  <ItemHeader>
+                    <div className="flex flex-col gap-1">
+                      <ItemTitle>
+                        Production Webhook
+                        <Badge variant="secondary">Active</Badge>
+                      </ItemTitle>
+                      <ItemDescription>
+                        https://api.example.com/webhooks/neynar
+                      </ItemDescription>
+                    </div>
+                    <ItemActions>
+                      <Button variant="ghost">
+                        <ExternalLinkIcon data-icon="inline-start" />
+                        Test
+                      </Button>
+                      <Button variant="ghost" size="icon-sm">
+                        <MoreHorizontalIcon />
+                      </Button>
+                    </ItemActions>
+                  </ItemHeader>
+                </ItemContent>
+              </Item>
+
+              <ItemSeparator />
+
+              <Item variant="muted">
+                <ItemMedia variant="icon">
+                  <WebhookIcon className="text-muted-foreground size-5" />
+                </ItemMedia>
+                <ItemContent>
+                  <ItemHeader>
+                    <div className="flex flex-col gap-1">
+                      <ItemTitle>
+                        Development Webhook
+                        <Badge variant="outline">Paused</Badge>
+                      </ItemTitle>
+                      <ItemDescription>
+                        https://dev.example.com/webhooks/neynar
+                      </ItemDescription>
+                    </div>
+                    <ItemActions>
+                      <Button variant="ghost">Resume</Button>
+                      <Button variant="ghost" size="icon-sm">
+                        <MoreHorizontalIcon />
+                      </Button>
+                    </ItemActions>
+                  </ItemHeader>
+                </ItemContent>
+              </Item>
+
+              <ItemSeparator />
+
+              <Item variant="muted">
+                <ItemMedia variant="icon">
+                  <WebhookIcon className="text-red-500 size-5" />
+                </ItemMedia>
+                <ItemContent>
+                  <ItemHeader>
+                    <div className="flex flex-col gap-1">
+                      <ItemTitle>
+                        Staging Webhook
+                        <Badge variant="destructive">Failed</Badge>
+                      </ItemTitle>
+                      <ItemDescription>
+                        https://staging.example.com/webhooks/neynar
+                      </ItemDescription>
+                    </div>
+                    <ItemActions>
+                      <Button variant="ghost">Retry</Button>
+                      <Button variant="ghost" size="icon-sm">
+                        <MoreHorizontalIcon />
+                      </Button>
+                    </ItemActions>
+                  </ItemHeader>
+                  <ItemFooter className="border-border w-full border-t pt-2">
+                    <div className="flex items-center gap-2 text-sm">
+                      <XCircleIcon className="text-red-500 size-4" />
+                      <span className="text-muted-foreground">
+                        Last failure: Connection timeout (5xx)
+                      </span>
+                    </div>
+                  </ItemFooter>
+                </ItemContent>
+              </Item>
+            </ItemGroup>
+          </section>
+
+          {/* Team Members List */}
+          <section className="space-y-4">
+            <div className="flex items-center justify-between">
+              <div>
+                <h2 className="text-lg font-semibold">Team Members</h2>
+                <p className="text-muted-foreground text-sm">
+                  Manage access for your team
+                </p>
+              </div>
+              <Button>Invite Member</Button>
+            </div>
+            <ItemGroup>
+              <Item>
+                <ItemMedia variant="icon">
+                  <div className="bg-primary/10 text-primary flex size-10 items-center justify-center rounded-full text-sm font-semibold">
+                    JD
+                  </div>
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>
+                    Jane Doe
+                    <Badge variant="outline">Owner</Badge>
+                  </ItemTitle>
+                  <ItemDescription>
+                    jane.doe@example.com • Full access to all resources
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost" size="icon-sm">
+                    <MoreHorizontalIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+
+              <Item>
+                <ItemMedia variant="icon">
+                  <div className="bg-green-500/10 text-green-500 flex size-10 items-center justify-center rounded-full text-sm font-semibold">
+                    AB
+                  </div>
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>
+                    Alex Brown
+                    <Badge variant="outline">Admin</Badge>
+                  </ItemTitle>
+                  <ItemDescription>
+                    alex.brown@example.com • Can manage API keys and webhooks
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost">Edit</Button>
+                  <Button variant="ghost" size="icon-sm">
+                    <MoreHorizontalIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+
+              <Item>
+                <ItemMedia variant="icon">
+                  <div className="bg-blue-500/10 text-blue-500 flex size-10 items-center justify-center rounded-full text-sm font-semibold">
+                    SM
+                  </div>
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>
+                    Sarah Miller
+                    <Badge variant="outline">Developer</Badge>
+                  </ItemTitle>
+                  <ItemDescription>
+                    sarah.miller@example.com • Read-only access to analytics
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost">Edit</Button>
+                  <Button variant="ghost" size="icon-sm">
+                    <MoreHorizontalIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+            </ItemGroup>
+          </section>
+
+          {/* Recent Activity List */}
+          <section className="space-y-4">
+            <div>
+              <h2 className="text-lg font-semibold">Recent Activity</h2>
+              <p className="text-muted-foreground text-sm">
+                Track recent changes and events
+              </p>
+            </div>
+            <ItemGroup>
+              <Item size="xs">
+                <ItemMedia variant="icon">
+                  <CheckCircle2Icon className="text-green-500 size-4" />
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>API key created</ItemTitle>
+                  <ItemDescription>
+                    Production key created by jane.doe@example.com
+                  </ItemDescription>
+                </ItemContent>
+                <ItemContent>
+                  <div className="text-muted-foreground flex items-center gap-1 text-xs">
+                    <ClockIcon className="size-3" />2 hours ago
+                  </div>
+                </ItemContent>
+              </Item>
+
+              <Item size="xs">
+                <ItemMedia variant="icon">
+                  <UserIcon className="text-blue-500 size-4" />
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>Team member invited</ItemTitle>
+                  <ItemDescription>
+                    Invitation sent to sarah.miller@example.com
+                  </ItemDescription>
+                </ItemContent>
+                <ItemContent>
+                  <div className="text-muted-foreground flex items-center gap-1 text-xs">
+                    <ClockIcon className="size-3" />5 hours ago
+                  </div>
+                </ItemContent>
+              </Item>
+
+              <Item size="xs">
+                <ItemMedia variant="icon">
+                  <XCircleIcon className="text-red-500 size-4" />
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>Webhook delivery failed</ItemTitle>
+                  <ItemDescription>
+                    Staging webhook failed with 5xx error
+                  </ItemDescription>
+                </ItemContent>
+                <ItemContent>
+                  <div className="text-muted-foreground flex items-center gap-1 text-xs">
+                    <ClockIcon className="size-3" />1 day ago
+                  </div>
+                </ItemContent>
+              </Item>
+            </ItemGroup>
+          </section>
+
+          {/* Document List with Images */}
+          <section className="space-y-4">
+            <div>
+              <h2 className="text-lg font-semibold">Recent Documents</h2>
+              <p className="text-muted-foreground text-sm">
+                Access your recent files
+              </p>
+            </div>
+            <ItemGroup>
+              <Item variant="outline">
+                <ItemMedia variant="image">
+                  <div className="bg-gradient-to-br from-purple-500 to-pink-500 flex size-full items-center justify-center">
+                    <FileIcon className="text-white size-6" />
+                  </div>
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>API Documentation.pdf</ItemTitle>
+                  <ItemDescription>
+                    Last modified 3 days ago • 2.4 MB
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost">Download</Button>
+                  <Button variant="ghost" size="icon-sm">
+                    <ChevronRightIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+
+              <Item variant="outline">
+                <ItemMedia variant="image">
+                  <div className="bg-gradient-to-br from-blue-500 to-cyan-500 flex size-full items-center justify-center">
+                    <FileIcon className="text-white size-6" />
+                  </div>
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>Integration Guide.docx</ItemTitle>
+                  <ItemDescription>
+                    Last modified 1 week ago • 1.8 MB
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost">Download</Button>
+                  <Button variant="ghost" size="icon-sm">
+                    <ChevronRightIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+
+              <Item variant="outline">
+                <ItemMedia variant="image">
+                  <div className="bg-gradient-to-br from-orange-500 to-red-500 flex size-full items-center justify-center">
+                    <FileIcon className="text-white size-6" />
+                  </div>
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>Webhook Setup.pdf</ItemTitle>
+                  <ItemDescription>
+                    Last modified 2 weeks ago • 980 KB
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost">Download</Button>
+                  <Button variant="ghost" size="icon-sm">
+                    <ChevronRightIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+            </ItemGroup>
+          </section>
+        </div>
+      );
+    }
+
+    return <DashboardLists />;
+  },
 };
 
 /**
- * Showcase of all available item variants and compositions.
+ * Complete design system reference showing all item variants, sizes,
+ * media types, and composition patterns.
  */
 export const Variants: Story = {
+  parameters: {
+    layout: "padded",
+  },
   render: () => (
-    <div className="space-y-12 w-full max-w-2xl">
-      {/* Basic Items */}
-      <div className="space-y-4">
-        <h3 className="text-sm font-medium text-muted-foreground">
-          Basic Items
-        </h3>
-        <div className="space-y-2">
-          <Item>
-            <ItemContent>
-              <ItemTitle>Simple Item</ItemTitle>
-              <ItemDescription>Just title and description</ItemDescription>
-            </ItemContent>
-          </Item>
-
-          <Item variant="outline">
-            <ItemContent>
-              <ItemTitle>Outlined Item</ItemTitle>
-              <ItemDescription>With border styling</ItemDescription>
-            </ItemContent>
-          </Item>
-
-          <Item variant="muted">
-            <ItemContent>
-              <ItemTitle>Muted Item</ItemTitle>
-              <ItemDescription>With muted background</ItemDescription>
-            </ItemContent>
-          </Item>
+    <div className="w-full max-w-4xl space-y-10">
+      {/* Visual Variants */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Visual Variants</h3>
+          <p className="text-muted-foreground text-sm">
+            Different styles for different list contexts and emphasis levels.
+          </p>
         </div>
-      </div>
-
-      {/* With Icon Media */}
-      <div className="space-y-4">
-        <h3 className="text-sm font-medium text-muted-foreground">
-          With Icon Media
-        </h3>
-        <div className="space-y-2">
-          <Item>
+        <ItemGroup>
+          <Item variant="default">
             <ItemMedia variant="icon">
-              <FileText className="size-4" />
+              <KeyIcon className="size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Project Documentation</ItemTitle>
-              <ItemDescription>Last updated 2 hours ago</ItemDescription>
+              <ItemTitle>Default Variant</ItemTitle>
+              <ItemDescription>
+                Clean appearance with transparent border
+              </ItemDescription>
             </ItemContent>
           </Item>
 
-          <Item>
+          <Item variant="outline">
             <ItemMedia variant="icon">
-              <User className="size-4" />
-            </ItemMedia>
-            <ItemContent>
-              <ItemTitle>User Profile</ItemTitle>
-              <ItemDescription>View and edit profile information</ItemDescription>
-            </ItemContent>
-          </Item>
-        </div>
-      </div>
-
-      {/* With Image Media */}
-      <div className="space-y-4">
-        <h3 className="text-sm font-medium text-muted-foreground">
-          With Image Media
-        </h3>
-        <div className="space-y-2">
-          <Item>
-            <ItemMedia variant="image">
-              <div className="size-10 bg-gradient-to-br from-purple-400 to-pink-400 rounded-sm" />
+              <KeyIcon className="size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Abstract Artwork</ItemTitle>
-              <ItemDescription>Digital illustration by Artist Name</ItemDescription>
+              <ItemTitle>Outline Variant</ItemTitle>
+              <ItemDescription>
+                Visible border for clear separation
+              </ItemDescription>
             </ItemContent>
           </Item>
 
-          <Item>
-            <ItemMedia variant="image">
-              <div className="size-10 bg-gradient-to-br from-blue-400 to-cyan-400 rounded-sm" />
+          <Item variant="muted">
+            <ItemMedia variant="icon">
+              <KeyIcon className="size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Ocean Waves</ItemTitle>
-              <ItemDescription>Photography collection</ItemDescription>
+              <ItemTitle>Muted Variant</ItemTitle>
+              <ItemDescription>
+                Subtle background for grouped items
+              </ItemDescription>
             </ItemContent>
           </Item>
+        </ItemGroup>
+      </section>
+
+      {/* Size Variants */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Size Variants</h3>
+          <p className="text-muted-foreground text-sm">
+            Multiple sizes for different density needs and content complexity.
+          </p>
         </div>
-      </div>
-
-      {/* With Actions */}
-      <div className="space-y-4">
-        <h3 className="text-sm font-medium text-muted-foreground">
-          With Actions
-        </h3>
-        <div className="space-y-2">
-          <Item>
+        <div className="space-y-4">
+          <div className="space-y-2">
+            <p className="font-mono text-sm">size="default"</p>
+            <ItemGroup>
+              <Item variant="outline" size="default">
+                <ItemMedia variant="icon">
+                  <UserIcon className="size-5" />
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>Default Size Item</ItemTitle>
+                  <ItemDescription>
+                    Standard padding (py-3.5, px-4) with gap-3.5 for regular
+                    content
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost" size="icon-sm">
+                    <MoreHorizontalIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+            </ItemGroup>
+          </div>
+
+          <div className="space-y-2">
+            <p className="font-mono text-sm">size="sm"</p>
+            <ItemGroup>
+              <Item variant="outline">
+                <ItemMedia variant="icon">
+                  <UserIcon className="size-5" />
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>Small Size Item</ItemTitle>
+                  <ItemDescription>
+                    Reduced padding (py-2.5, px-3) with gap-2.5 for compact
+                    layouts
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost" size="icon-sm">
+                    <MoreHorizontalIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+            </ItemGroup>
+          </div>
+
+          <div className="space-y-2">
+            <p className="font-mono text-sm">size="xs"</p>
+            <ItemGroup>
+              <Item variant="outline" size="xs">
+                <ItemMedia variant="icon">
+                  <UserIcon className="size-4" />
+                </ItemMedia>
+                <ItemContent>
+                  <ItemTitle>Extra Small Size Item</ItemTitle>
+                  <ItemDescription>
+                    Minimal padding (py-2, px-2.5) with gap-2 for dense lists
+                  </ItemDescription>
+                </ItemContent>
+                <ItemActions>
+                  <Button variant="ghost" size="icon-xs">
+                    <MoreHorizontalIcon />
+                  </Button>
+                </ItemActions>
+              </Item>
+            </ItemGroup>
+          </div>
+        </div>
+      </section>
+
+      {/* Media Variants */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Media Variants</h3>
+          <p className="text-muted-foreground text-sm">
+            Different media types for icons, images, and avatars.
+          </p>
+        </div>
+        <ItemGroup>
+          <Item variant="outline">
             <ItemMedia variant="icon">
-              <FileText className="size-4" />
+              <WebhookIcon className="size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Important Document</ItemTitle>
-              <ItemDescription>Review required by tomorrow</ItemDescription>
+              <ItemTitle>Icon Variant</ItemTitle>
+              <ItemDescription>
+                Direct icon placement with auto-sizing
+              </ItemDescription>
             </ItemContent>
-            <ItemActions>
-              <Button variant="ghost" size="sm">
-                View
-              </Button>
-              <Button variant="ghost" size="icon">
-                <MoreVertical className="size-4" />
-              </Button>
-            </ItemActions>
           </Item>
 
-          <Item>
-            <ItemContent>
-              <ItemTitle>Task Item</ItemTitle>
-              <ItemDescription>Complete this task</ItemDescription>
-            </ItemContent>
-            <ItemActions>
-              <Button variant="ghost" size="icon">
-                <Star className="size-4" />
-              </Button>
-              <Button variant="ghost" size="icon">
-                <CheckCircle2 className="size-4" />
-              </Button>
-            </ItemActions>
-          </Item>
-        </div>
-      </div>
-
-      {/* With Header and Footer */}
-      <div className="space-y-4">
-        <h3 className="text-sm font-medium text-muted-foreground">
-          With Header and Footer
-        </h3>
-        <div className="space-y-2">
-          <Item>
+          <Item variant="outline">
             <ItemMedia variant="icon">
-              <Clock className="size-4" />
+              <div className="bg-primary/10 text-primary rounded-md p-2">
+                <WebhookIcon className="size-5" />
+              </div>
             </ItemMedia>
             <ItemContent>
-              <ItemHeader>
-                <ItemTitle>Meeting Notes</ItemTitle>
-                <Badge variant="secondary">New</Badge>
-              </ItemHeader>
+              <ItemTitle>Icon with Background</ItemTitle>
               <ItemDescription>
-                Notes from the team sync meeting
+                Icon wrapped in colored container
               </ItemDescription>
-              <ItemFooter>
-                <span className="text-xs text-muted-foreground">
-                  Updated 5 min ago
-                </span>
-                <span className="text-xs text-muted-foreground">3 comments</span>
-              </ItemFooter>
             </ItemContent>
           </Item>
-        </div>
-      </div>
-
-      {/* Small Size */}
-      <div className="space-y-4">
-        <h3 className="text-sm font-medium text-muted-foreground">
-          Small Size
-        </h3>
-        <div className="space-y-2">
-          <Item size="sm">
-            <ItemMedia variant="icon">
-              <FileText className="size-4" />
+
+          <Item variant="outline">
+            <ItemMedia variant="image">
+              <div className="bg-gradient-to-br from-purple-500 to-pink-500 flex size-full items-center justify-center">
+                <FileIcon className="text-white size-6" />
+              </div>
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Small Item</ItemTitle>
-              <ItemDescription>Compact layout</ItemDescription>
+              <ItemTitle>Image Variant</ItemTitle>
+              <ItemDescription>
+                Fixed size container (size-10) that scales with item size
+              </ItemDescription>
             </ItemContent>
           </Item>
 
-          <Item size="sm">
+          <Item variant="outline">
             <ItemMedia variant="icon">
-              <User className="size-4" />
+              <div className="bg-blue-500 text-white flex size-10 items-center justify-center rounded-full text-sm font-semibold">
+                AB
+              </div>
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Another Small Item</ItemTitle>
+              <ItemTitle>Avatar Style</ItemTitle>
+              <ItemDescription>
+                Custom avatar with initials or profile image
+              </ItemDescription>
             </ItemContent>
-            <ItemActions>
-              <Button variant="ghost" size="icon">
-                <ChevronRight className="size-4" />
-              </Button>
-            </ItemActions>
           </Item>
+        </ItemGroup>
+      </section>
+
+      {/* With Badges and Status */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">With Badges and Status</h3>
+          <p className="text-muted-foreground text-sm">
+            Items with status indicators and badges in titles.
+          </p>
         </div>
-      </div>
-
-      {/* Item Group */}
-      <div className="space-y-4">
-        <h3 className="text-sm font-medium text-muted-foreground">
-          Item Group with Separators
-        </h3>
         <ItemGroup>
-          <Item>
+          <Item variant="outline">
             <ItemMedia variant="icon">
-              <FileText className="size-4" />
+              <CheckCircle2Icon className="text-green-500 size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>First Item</ItemTitle>
-              <ItemDescription>First item in the group</ItemDescription>
+              <ItemTitle>
+                Active Status
+                <Badge variant="secondary">Active</Badge>
+              </ItemTitle>
+              <ItemDescription>
+                Item is currently active and operational
+              </ItemDescription>
             </ItemContent>
           </Item>
 
-          <ItemSeparator />
-
-          <Item>
+          <Item variant="outline">
             <ItemMedia variant="icon">
-              <ImageIcon className="size-4" />
+              <ClockIcon className="text-yellow-500 size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Second Item</ItemTitle>
-              <ItemDescription>Second item in the group</ItemDescription>
+              <ItemTitle>
+                Pending Status
+                <Badge variant="outline">Pending</Badge>
+              </ItemTitle>
+              <ItemDescription>
+                Item is waiting for approval or action
+              </ItemDescription>
             </ItemContent>
           </Item>
 
-          <ItemSeparator />
-
-          <Item>
+          <Item variant="outline">
             <ItemMedia variant="icon">
-              <User className="size-4" />
+              <XCircleIcon className="text-red-500 size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Third Item</ItemTitle>
-              <ItemDescription>Third item in the group</ItemDescription>
+              <ItemTitle>
+                Failed Status
+                <Badge variant="destructive">Failed</Badge>
+              </ItemTitle>
+              <ItemDescription>
+                Item encountered an error or failure
+              </ItemDescription>
             </ItemContent>
           </Item>
         </ItemGroup>
-      </div>
-    </div>
-  ),
-  parameters: {
-    layout: "padded",
-    docs: {
-      description: {
-        story:
-          "Complete showcase of item variants, sizes, media types, and compositions.",
-      },
-    },
-  },
-};
-
-/**
- * Real-world usage examples showing items in practical scenarios.
- */
-export const InContext: Story = {
-  render: () => (
-    <div className="space-y-8 w-full max-w-2xl">
-      {/* File List */}
-      <div className="space-y-4 p-6 border rounded-lg">
-        <h3 className="text-lg font-semibold">Recent Files</h3>
-        <ItemGroup>
-          <Item asChild>
-            <a href="#">
-              <ItemMedia variant="icon">
-                <FileText className="size-4" />
-              </ItemMedia>
-              <ItemContent>
-                <ItemHeader>
-                  <ItemTitle>Q4 Financial Report.pdf</ItemTitle>
-                  <Badge variant="secondary">PDF</Badge>
-                </ItemHeader>
-                <ItemDescription>Last modified today at 2:45 PM</ItemDescription>
-                <ItemFooter>
-                  <span className="text-xs text-muted-foreground">2.4 MB</span>
-                  <span className="text-xs text-muted-foreground">
-                    Shared with 5 people
-                  </span>
-                </ItemFooter>
-              </ItemContent>
-              <ItemActions>
-                <Button variant="ghost" size="icon">
-                  <MoreVertical className="size-4" />
-                </Button>
-              </ItemActions>
-            </a>
-          </Item>
-
-          <ItemSeparator />
-
-          <Item asChild>
-            <a href="#">
-              <ItemMedia variant="icon">
-                <FileText className="size-4" />
-              </ItemMedia>
-              <ItemContent>
-                <ItemTitle>Team Meeting Notes.docx</ItemTitle>
-                <ItemDescription>Last modified yesterday</ItemDescription>
-              </ItemContent>
-              <ItemActions>
-                <Button variant="ghost" size="icon">
-                  <Star className="size-4" />
-                </Button>
-                <Button variant="ghost" size="icon">
-                  <MoreVertical className="size-4" />
-                </Button>
-              </ItemActions>
-            </a>
-          </Item>
-
-          <ItemSeparator />
-
-          <Item asChild>
-            <a href="#">
-              <ItemMedia variant="icon">
-                <ImageIcon className="size-4" />
-              </ItemMedia>
-              <ItemContent>
-                <ItemTitle>Product Mockup.fig</ItemTitle>
-                <ItemDescription>Last modified 3 days ago</ItemDescription>
-              </ItemContent>
-              <ItemActions>
-                <Button variant="ghost" size="icon">
-                  <MoreVertical className="size-4" />
-                </Button>
-              </ItemActions>
-            </a>
-          </Item>
-        </ItemGroup>
-      </div>
-
-      {/* Notification List */}
-      <div className="space-y-4 p-6 border rounded-lg">
-        <h3 className="text-lg font-semibold">Notifications</h3>
+      </section>
+
+      {/* Composition Patterns */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Composition Patterns</h3>
+          <p className="text-muted-foreground text-sm">
+            Advanced layouts with header, footer, and multiple content areas.
+          </p>
+        </div>
         <ItemGroup>
-          <Item variant="muted">
+          <Item variant="outline">
             <ItemMedia variant="icon">
-              <User className="size-4" />
+              <WebhookIcon className="size-5" />
             </ItemMedia>
             <ItemContent>
               <ItemHeader>
-                <ItemTitle>New follower</ItemTitle>
-                <Badge>New</Badge>
+                <div className="flex flex-col gap-1">
+                  <ItemTitle>
+                    With Header Section
+                    <Badge variant="secondary">Active</Badge>
+                  </ItemTitle>
+                  <ItemDescription>
+                    Using ItemHeader for complex layouts
+                  </ItemDescription>
+                </div>
+                <ItemActions>
+                  <Button variant="outline">Configure</Button>
+                  <Button variant="ghost" size="icon-sm">
+                    <MoreHorizontalIcon />
+                  </Button>
+                </ItemActions>
               </ItemHeader>
-              <ItemDescription>
-                John Doe started following you
-              </ItemDescription>
-              <ItemFooter>
-                <span className="text-xs text-muted-foreground">5 min ago</span>
-              </ItemFooter>
             </ItemContent>
           </Item>
 
-          <ItemSeparator />
-
-          <Item>
+          <Item variant="outline">
             <ItemMedia variant="icon">
-              <CheckCircle2 className="size-4" />
+              <WebhookIcon className="size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Task completed</ItemTitle>
+              <ItemTitle>With Footer Section</ItemTitle>
               <ItemDescription>
-                "Update documentation" was marked as complete
+                Using ItemFooter for additional information
               </ItemDescription>
-              <ItemFooter>
-                <span className="text-xs text-muted-foreground">2 hours ago</span>
+              <ItemFooter className="border-border w-full border-t pt-2">
+                <div className="flex items-center gap-2 text-sm">
+                  <CheckCircle2Icon className="text-green-500 size-4" />
+                  <span className="text-muted-foreground">
+                    Last delivery: 2 minutes ago
+                  </span>
+                </div>
               </ItemFooter>
             </ItemContent>
           </Item>
 
-          <ItemSeparator />
-
-          <Item>
+          <Item variant="outline">
             <ItemMedia variant="icon">
-              <Clock className="size-4" />
+              <KeyIcon className="size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Meeting reminder</ItemTitle>
+              <ItemTitle>Multiple Content Areas</ItemTitle>
               <ItemDescription>
-                Team sync meeting in 30 minutes
+                First content area with description
               </ItemDescription>
-              <ItemFooter>
-                <span className="text-xs text-muted-foreground">
-                  Today at 3:30 PM
-                </span>
-              </ItemFooter>
             </ItemContent>
+            <ItemContent>
+              <div className="text-muted-foreground flex items-center gap-1 text-xs">
+                <ClockIcon className="size-3" />2 hours ago
+              </div>
+            </ItemContent>
+            <ItemActions>
+              <Button variant="ghost" size="icon-sm">
+                <MoreHorizontalIcon />
+              </Button>
+            </ItemActions>
           </Item>
         </ItemGroup>
-      </div>
-
-      {/* User List */}
-      <div className="space-y-4 p-6 border rounded-lg">
-        <h3 className="text-lg font-semibold">Team Members</h3>
+      </section>
+
+      {/* ItemGroup with Separator */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">ItemGroup with Separators</h3>
+          <p className="text-muted-foreground text-sm">
+            Using ItemGroup to organize related items with separators.
+          </p>
+        </div>
         <ItemGroup>
           <Item>
-            <ItemMedia variant="image">
-              <div className="size-10 bg-gradient-to-br from-purple-400 to-pink-400 rounded-full" />
+            <ItemMedia variant="icon">
+              <UserIcon className="size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Alice Johnson</ItemTitle>
-              <ItemDescription>Product Manager</ItemDescription>
+              <ItemTitle>First Item</ItemTitle>
+              <ItemDescription>Part of a grouped list</ItemDescription>
             </ItemContent>
-            <ItemActions>
-              <Button variant="outline" size="sm">
-                Message
-              </Button>
-            </ItemActions>
           </Item>
 
           <ItemSeparator />
 
           <Item>
-            <ItemMedia variant="image">
-              <div className="size-10 bg-gradient-to-br from-blue-400 to-cyan-400 rounded-full" />
+            <ItemMedia variant="icon">
+              <UserIcon className="size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Bob Smith</ItemTitle>
-              <ItemDescription>Lead Developer</ItemDescription>
+              <ItemTitle>Second Item</ItemTitle>
+              <ItemDescription>Separated from first item</ItemDescription>
             </ItemContent>
-            <ItemActions>
-              <Button variant="outline" size="sm">
-                Message
-              </Button>
-            </ItemActions>
           </Item>
 
           <ItemSeparator />
 
           <Item>
-            <ItemMedia variant="image">
-              <div className="size-10 bg-gradient-to-br from-green-400 to-emerald-400 rounded-full" />
+            <ItemMedia variant="icon">
+              <UserIcon className="size-5" />
             </ItemMedia>
             <ItemContent>
-              <ItemTitle>Carol White</ItemTitle>
-              <ItemDescription>UX Designer</ItemDescription>
+              <ItemTitle>Third Item</ItemTitle>
+              <ItemDescription>Separated from second item</ItemDescription>
             </ItemContent>
-            <ItemActions>
-              <Button variant="outline" size="sm">
-                Message
-              </Button>
-            </ItemActions>
-          </Item>
-        </ItemGroup>
-      </div>
-
-      {/* Settings Menu */}
-      <div className="space-y-4 p-6 border rounded-lg">
-        <h3 className="text-lg font-semibold">Settings</h3>
-        <ItemGroup>
-          <Item asChild size="sm">
-            <a href="#">
-              <ItemContent>
-                <ItemTitle>Profile</ItemTitle>
-              </ItemContent>
-              <ItemActions>
-                <ChevronRight className="size-4 text-muted-foreground" />
-              </ItemActions>
-            </a>
-          </Item>
-
-          <ItemSeparator />
-
-          <Item asChild size="sm">
-            <a href="#">
-              <ItemContent>
-                <ItemTitle>Notifications</ItemTitle>
-              </ItemContent>
-              <ItemActions>
-                <ChevronRight className="size-4 text-muted-foreground" />
-              </ItemActions>
-            </a>
-          </Item>
-
-          <ItemSeparator />
-
-          <Item asChild size="sm">
-            <a href="#">
-              <ItemContent>
-                <ItemTitle>Privacy & Security</ItemTitle>
-              </ItemContent>
-              <ItemActions>
-                <ChevronRight className="size-4 text-muted-foreground" />
-              </ItemActions>
-            </a>
-          </Item>
-
-          <ItemSeparator />
-
-          <Item asChild size="sm">
-            <a href="#">
-              <ItemContent>
-                <ItemTitle>Billing</ItemTitle>
-              </ItemContent>
-              <ItemActions>
-                <ChevronRight className="size-4 text-muted-foreground" />
-              </ItemActions>
-            </a>
           </Item>
         </ItemGroup>
-      </div>
+      </section>
+
+      {/* Variant × Size Matrix */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Variant × Size Matrix</h3>
+          <p className="text-muted-foreground text-sm">
+            Complete combination reference.
+          </p>
+        </div>
+        <div className="space-y-6">
+          {(["default", "outline", "muted"] as const).map((variant) => (
+            <div key={variant} className="space-y-2">
+              <p className="font-mono text-sm capitalize">
+                variant="{variant}"
+              </p>
+              <ItemGroup>
+                <Item variant={variant} size="default">
+                  <ItemMedia variant="icon">
+                    <KeyIcon className="size-5" />
+                  </ItemMedia>
+                  <ItemContent>
+                    <ItemTitle>Size: Default</ItemTitle>
+                    <ItemDescription>
+                      Standard spacing and padding
+                    </ItemDescription>
+                  </ItemContent>
+                </Item>
+
+                <Item variant={variant}>
+                  <ItemMedia variant="icon">
+                    <KeyIcon className="size-5" />
+                  </ItemMedia>
+                  <ItemContent>
+                    <ItemTitle>Size: Small</ItemTitle>
+                    <ItemDescription>
+                      Reduced spacing for compact layouts
+                    </ItemDescription>
+                  </ItemContent>
+                </Item>
+
+                <Item variant={variant} size="xs">
+                  <ItemMedia variant="icon">
+                    <KeyIcon className="size-4" />
+                  </ItemMedia>
+                  <ItemContent>
+                    <ItemTitle>Size: Extra Small</ItemTitle>
+                    <ItemDescription>
+                      Minimal spacing for dense lists
+                    </ItemDescription>
+                  </ItemContent>
+                </Item>
+              </ItemGroup>
+            </div>
+          ))}
+        </div>
+      </section>
     </div>
   ),
-  parameters: {
-    layout: "padded",
-    docs: {
-      description: {
-        story:
-          "Real-world examples showing items in file lists, notifications, user lists, and settings menus.",
-      },
-    },
+};
+
+/**
+ * Interactive playground for testing item props.
+ */
+export const Interactive: Story = {
+  args: {
+    variant: "default",
+    size: "default",
+    children: (
+      <>
+        <ItemMedia variant="icon">
+          <div className="bg-primary/10 text-primary rounded-md p-2">
+            <KeyIcon className="size-5" />
+          </div>
+        </ItemMedia>
+        <ItemContent>
+          <ItemTitle>Item Title</ItemTitle>
+          <ItemDescription>This is a description of the item</ItemDescription>
+        </ItemContent>
+        <ItemActions>
+          <Button variant="ghost" size="icon-sm">
+            <MoreHorizontalIcon />
+          </Button>
+        </ItemActions>
+      </>
+    ),
   },
 };