@neynar/ui 0.3.1 → 0.5.0

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

@@ -1,5 +1,14 @@
-import type { Meta, StoryObj } from "@storybook/react-vite";
-import { Home, Slash, ChevronDown } from "lucide-react";
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  HomeIcon,
+  KeyIcon,
+  LayoutDashboardIcon,
+  SettingsIcon,
+  SlashIcon,
+  UsersIcon,
+  WebhookIcon,
+} from "lucide-react";
+
 import {
   Breadcrumb,
   BreadcrumbEllipsis,
@@ -9,473 +18,650 @@ import {
   BreadcrumbPage,
   BreadcrumbSeparator,
 } from "../breadcrumb";
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from "../dropdown-menu";
 
-const meta = {
-  title: "Navigation & Menus/Breadcrumb",
+const meta: Meta<typeof Breadcrumb> = {
+  title: "Components/Navigation & Menus/Breadcrumb",
   component: Breadcrumb,
   parameters: {
-    layout: "padded",
-    docs: {
-      description: {
-        component:
-          "A breadcrumb navigation component that shows the current page location within a navigational hierarchy. Built with accessibility in mind and supports custom separators, ellipsis for long paths, and composition patterns.",
-      },
-    },
+    layout: "centered",
   },
   argTypes: {
-    // No direct props on Breadcrumb component, but we can show composition options
-    children: {
-      description: "BreadcrumbList containing breadcrumb items",
-      control: false,
+    className: {
+      control: "text",
+      description: "Additional CSS classes",
     },
   },
-} satisfies Meta<typeof Breadcrumb>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof Breadcrumb>;
 
-export const Interactive: Story = {
-  args: {},
-  render: (args) => (
-    <div className="space-y-8">
-      <div>
-        <h3 className="text-lg font-semibold mb-4">Basic Breadcrumb</h3>
-        <Breadcrumb {...args}>
-          <BreadcrumbList>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/">Home</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/components">Components</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
-            </BreadcrumbItem>
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
-
-      <div>
-        <h3 className="text-lg font-semibold mb-4">With Icons</h3>
-        <Breadcrumb {...args}>
-          <BreadcrumbList>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/">
-                <Home className="h-4 w-4" />
-                Home
-              </BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/documents">Documents</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbPage>Design System</BreadcrumbPage>
-            </BreadcrumbItem>
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
-
-      <div>
-        <h3 className="text-lg font-semibold mb-4">With Custom Separator</h3>
-        <Breadcrumb {...args}>
-          <BreadcrumbList>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/">Home</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator>
-              <Slash className="h-3 w-3" />
-            </BreadcrumbSeparator>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/products">Products</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator>
-              <Slash className="h-3 w-3" />
-            </BreadcrumbSeparator>
-            <BreadcrumbItem>
-              <BreadcrumbPage>Shoes</BreadcrumbPage>
-            </BreadcrumbItem>
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
+/**
+ * Dashboard Navigation - Realistic Neynar Dashboard scenarios showing breadcrumb
+ * navigation across different sections: API settings, team management, and webhooks.
+ */
+export const InContext: Story = {
+  parameters: {
+    layout: "padded",
+  },
+  render: () => {
+    function DashboardBreadcrumbs() {
+      return (
+        <div className="w-full max-w-4xl space-y-10">
+          {/* API Settings Path */}
+          <section className="space-y-4">
+            <div>
+              <h3 className="text-lg font-semibold">API Settings Navigation</h3>
+              <p className="text-muted-foreground text-sm">
+                Deep navigation path within API key management.
+              </p>
+            </div>
+            <div className="border-border bg-card rounded-lg border p-6">
+              <Breadcrumb>
+                <BreadcrumbList>
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#">
+                      <HomeIcon className="size-4" />
+                    </BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#">
+                      <LayoutDashboardIcon className="mr-2 size-4" />
+                      Dashboard
+                    </BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#">Settings</BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbPage>
+                      <KeyIcon className="mr-2 size-4" />
+                      API
+                    </BreadcrumbPage>
+                  </BreadcrumbItem>
+                </BreadcrumbList>
+              </Breadcrumb>
+              <div className="mt-6">
+                <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>
+            </div>
+          </section>
 
-      <div>
-        <h3 className="text-lg font-semibold mb-4">With Ellipsis</h3>
-        <Breadcrumb {...args}>
-          <BreadcrumbList>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/">Home</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbEllipsis />
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/components">Components</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
-            </BreadcrumbItem>
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
+          {/* Team Management Path */}
+          <section className="space-y-4">
+            <div>
+              <h3 className="text-lg font-semibold">Team Management</h3>
+              <p className="text-muted-foreground text-sm">
+                Breadcrumb with slash separator and team context.
+              </p>
+            </div>
+            <div className="border-border bg-card rounded-lg border p-6">
+              <Breadcrumb>
+                <BreadcrumbList>
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#">Home</BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator>
+                    <SlashIcon />
+                  </BreadcrumbSeparator>
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#">Organization</BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator>
+                    <SlashIcon />
+                  </BreadcrumbSeparator>
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#">
+                      <UsersIcon className="mr-2 size-4" />
+                      Team
+                    </BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator>
+                    <SlashIcon />
+                  </BreadcrumbSeparator>
+                  <BreadcrumbItem>
+                    <BreadcrumbPage>Members</BreadcrumbPage>
+                  </BreadcrumbItem>
+                </BreadcrumbList>
+              </Breadcrumb>
+              <div className="mt-6">
+                <h2 className="text-lg font-semibold">Team Members</h2>
+                <p className="text-muted-foreground text-sm">
+                  Invite and manage your team members.
+                </p>
+              </div>
+            </div>
+          </section>
 
-      <div>
-        <h3 className="text-lg font-semibold mb-4">With Dropdown</h3>
-        <Breadcrumb {...args}>
-          <BreadcrumbList>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/">Home</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <DropdownMenu>
-                <DropdownMenuTrigger className="flex items-center gap-1 hover:text-foreground transition-colors">
-                  <BreadcrumbEllipsis className="h-4 w-4" />
-                  <ChevronDown className="h-3 w-3" />
-                </DropdownMenuTrigger>
-                <DropdownMenuContent align="start">
-                  <DropdownMenuItem>Documentation</DropdownMenuItem>
-                  <DropdownMenuItem>Components</DropdownMenuItem>
-                  <DropdownMenuItem>Navigation</DropdownMenuItem>
-                </DropdownMenuContent>
-              </DropdownMenu>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
-            </BreadcrumbItem>
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
+          {/* Truncated Long Path with Ellipsis */}
+          <section className="space-y-4">
+            <div>
+              <h3 className="text-lg font-semibold">Truncated Navigation</h3>
+              <p className="text-muted-foreground text-sm">
+                Long paths with ellipsis for better space management.
+              </p>
+            </div>
+            <div className="border-border bg-card rounded-lg border p-6">
+              <Breadcrumb>
+                <BreadcrumbList>
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#">Home</BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#">Dashboard</BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbEllipsis />
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#">Integrations</BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbLink href="#">
+                      <WebhookIcon className="mr-2 size-4" />
+                      Webhooks
+                    </BreadcrumbLink>
+                  </BreadcrumbItem>
+                  <BreadcrumbSeparator />
+                  <BreadcrumbItem>
+                    <BreadcrumbPage>Configuration</BreadcrumbPage>
+                  </BreadcrumbItem>
+                </BreadcrumbList>
+              </Breadcrumb>
+              <div className="mt-6">
+                <h2 className="text-lg font-semibold">Webhook Configuration</h2>
+                <p className="text-muted-foreground text-sm">
+                  Configure webhook endpoints and event subscriptions.
+                </p>
+              </div>
+            </div>
+          </section>
+        </div>
+      );
+    }
 
-      <div>
-        <h3 className="text-lg font-semibold mb-4">AsChild Pattern</h3>
-        <Breadcrumb {...args}>
-          <BreadcrumbList>
-            <BreadcrumbItem>
-              <BreadcrumbLink asChild>
-                <a href="/">Home</a>
-              </BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbLink asChild>
-                <button
-                  onClick={() => console.log("Navigate to docs")}
-                  className="text-left"
-                >
-                  Documentation
-                </button>
-              </BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbPage>Getting Started</BreadcrumbPage>
-            </BreadcrumbItem>
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Interactive playground showcasing all breadcrumb variations including basic usage, icons, custom separators, ellipsis, dropdown menus, and the asChild composition pattern.",
-      },
-    },
+    return <DashboardBreadcrumbs />;
   },
 };
 
+/**
+ * Complete design system reference showing all breadcrumb patterns,
+ * separators, states, and composition options.
+ */
 export const Variants: Story = {
+  parameters: {
+    layout: "padded",
+  },
   render: () => (
-    <div className="space-y-6">
-      <div>
-        <h4 className="text-sm font-medium text-muted-foreground mb-2">
-          Default Separator (ChevronRight)
-        </h4>
-        <Breadcrumb>
-          <BreadcrumbList>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/">Home</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/products">Products</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbPage>Current Page</BreadcrumbPage>
-            </BreadcrumbItem>
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
-
-      <div>
-        <h4 className="text-sm font-medium text-muted-foreground mb-2">
-          Slash Separator
-        </h4>
-        <Breadcrumb>
-          <BreadcrumbList>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/">Home</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator>
-              <Slash className="h-3 w-3" />
-            </BreadcrumbSeparator>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/products">Products</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator>
-              <Slash className="h-3 w-3" />
-            </BreadcrumbSeparator>
-            <BreadcrumbItem>
-              <BreadcrumbPage>Current Page</BreadcrumbPage>
-            </BreadcrumbItem>
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
-
-      <div>
-        <h4 className="text-sm font-medium text-muted-foreground mb-2">
-          With Home Icon
-        </h4>
-        <Breadcrumb>
-          <BreadcrumbList>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/">
-                <Home className="h-4 w-4" />
-                Home
-              </BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/products">Products</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbPage>Current Page</BreadcrumbPage>
-            </BreadcrumbItem>
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
+    <div className="w-full max-w-4xl space-y-10">
+      {/* Basic Breadcrumbs */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Basic Breadcrumbs</h3>
+          <p className="text-muted-foreground text-sm">
+            Standard breadcrumb navigation with default chevron separator.
+          </p>
+        </div>
+        <div className="space-y-6">
+          <div>
+            <p className="text-muted-foreground mb-2 text-sm">Two levels</p>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Home</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbPage>Dashboard</BreadcrumbPage>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+          <div>
+            <p className="text-muted-foreground mb-2 text-sm">Three levels</p>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Home</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Dashboard</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbPage>Settings</BreadcrumbPage>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+          <div>
+            <p className="text-muted-foreground mb-2 text-sm">
+              Multiple levels
+            </p>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Home</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Dashboard</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Settings</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">API</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbPage>Keys</BreadcrumbPage>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+        </div>
+      </section>
 
-      <div>
-        <h4 className="text-sm font-medium text-muted-foreground mb-2">
-          With Ellipsis (Collapsed Items)
-        </h4>
-        <Breadcrumb>
-          <BreadcrumbList>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/">Home</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbEllipsis />
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/category">Category</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbPage>Current Page</BreadcrumbPage>
-            </BreadcrumbItem>
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
+      {/* Custom Separators */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Custom Separators</h3>
+          <p className="text-muted-foreground text-sm">
+            Different separator styles for various design preferences.
+          </p>
+        </div>
+        <div className="space-y-6">
+          <div>
+            <p className="text-muted-foreground mb-2 text-sm">
+              Default Chevron (ChevronRightIcon)
+            </p>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Home</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Docs</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbPage>Components</BreadcrumbPage>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+          <div>
+            <p className="text-muted-foreground mb-2 text-sm">
+              Slash separator
+            </p>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Home</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator>
+                  <SlashIcon />
+                </BreadcrumbSeparator>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Docs</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator>
+                  <SlashIcon />
+                </BreadcrumbSeparator>
+                <BreadcrumbItem>
+                  <BreadcrumbPage>Components</BreadcrumbPage>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+          <div>
+            <p className="text-muted-foreground mb-2 text-sm">Text separator</p>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Home</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator>
+                  <span className="text-muted-foreground">→</span>
+                </BreadcrumbSeparator>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Docs</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator>
+                  <span className="text-muted-foreground">→</span>
+                </BreadcrumbSeparator>
+                <BreadcrumbItem>
+                  <BreadcrumbPage>Components</BreadcrumbPage>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+        </div>
+      </section>
 
-      <div>
-        <h4 className="text-sm font-medium text-muted-foreground mb-2">
-          Interactive Dropdown
-        </h4>
-        <Breadcrumb>
-          <BreadcrumbList>
-            <BreadcrumbItem>
-              <BreadcrumbLink href="/">Home</BreadcrumbLink>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <DropdownMenu>
-                <DropdownMenuTrigger className="flex items-center gap-1 hover:text-foreground transition-colors">
-                  Categories
-                  <ChevronDown className="h-3 w-3" />
-                </DropdownMenuTrigger>
-                <DropdownMenuContent align="start">
-                  <DropdownMenuItem>Electronics</DropdownMenuItem>
-                  <DropdownMenuItem>Clothing</DropdownMenuItem>
-                  <DropdownMenuItem>Books</DropdownMenuItem>
-                </DropdownMenuContent>
-              </DropdownMenu>
-            </BreadcrumbItem>
-            <BreadcrumbSeparator />
-            <BreadcrumbItem>
-              <BreadcrumbPage>Current Page</BreadcrumbPage>
-            </BreadcrumbItem>
-          </BreadcrumbList>
-        </Breadcrumb>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Systematic display of all breadcrumb variants including different separators, icons, ellipsis states, and interactive dropdowns.",
-      },
-    },
-  },
-};
+      {/* With Icons */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">With Icons</h3>
+          <p className="text-muted-foreground text-sm">
+            Breadcrumbs enhanced with icons for better visual hierarchy.
+          </p>
+        </div>
+        <div className="space-y-6">
+          <div>
+            <p className="text-muted-foreground mb-2 text-sm">Home icon only</p>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#" aria-label="Home">
+                    <HomeIcon className="size-4" />
+                  </BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Settings</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbPage>Profile</BreadcrumbPage>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+          <div>
+            <p className="text-muted-foreground mb-2 text-sm">
+              Icons with text
+            </p>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">
+                    <HomeIcon className="size-4" />
+                  </BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">
+                    <LayoutDashboardIcon className="mr-2 size-4" />
+                    Dashboard
+                  </BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbPage>
+                    <SettingsIcon className="mr-2 size-4" />
+                    Settings
+                  </BreadcrumbPage>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+          <div>
+            <p className="text-muted-foreground mb-2 text-sm">
+              Context-specific icons
+            </p>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">
+                    <HomeIcon className="size-4" />
+                  </BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">
+                    <UsersIcon className="mr-2 size-4" />
+                    Team
+                  </BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbPage>
+                    <KeyIcon className="mr-2 size-4" />
+                    API Keys
+                  </BreadcrumbPage>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+        </div>
+      </section>
 
-export const InContext: Story = {
-  render: () => (
-    <div className="min-h-[400px] bg-background">
-      {/* Header */}
-      <header className="border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
-        <div className="container mx-auto px-4 py-3">
-          <div className="flex items-center justify-between">
-            <div className="flex items-center space-x-4">
-              <h1 className="text-lg font-semibold">E-Commerce Store</h1>
-            </div>
-            <nav className="flex items-center space-x-4">
-              <a
-                href="#"
-                className="text-sm text-muted-foreground hover:text-foreground"
-              >
-                Account
-              </a>
-              <a
-                href="#"
-                className="text-sm text-muted-foreground hover:text-foreground"
-              >
-                Cart (0)
-              </a>
-            </nav>
+      {/* Truncated Paths */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Truncated Paths</h3>
+          <p className="text-muted-foreground text-sm">
+            Using ellipsis to show collapsed middle sections of long paths.
+          </p>
+        </div>
+        <div className="space-y-6">
+          <div>
+            <p className="text-muted-foreground mb-2 text-sm">
+              Ellipsis in the middle
+            </p>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Home</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Dashboard</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbEllipsis />
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Settings</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbPage>API</BreadcrumbPage>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
+          </div>
+          <div>
+            <p className="text-muted-foreground mb-2 text-sm">
+              Long path with multiple collapsed sections
+            </p>
+            <Breadcrumb>
+              <BreadcrumbList>
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">
+                    <HomeIcon className="size-4" />
+                  </BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbEllipsis />
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbLink href="#">Projects</BreadcrumbLink>
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbEllipsis />
+                </BreadcrumbItem>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbPage>README.md</BreadcrumbPage>
+                </BreadcrumbItem>
+              </BreadcrumbList>
+            </Breadcrumb>
           </div>
         </div>
-      </header>
+      </section>
 
-      {/* Main Content */}
-      <main className="container mx-auto px-4 py-6">
-        {/* Breadcrumb Navigation */}
-        <div className="mb-6">
+      {/* Responsive Behavior */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Responsive Behavior</h3>
+          <p className="text-muted-foreground text-sm">
+            Breadcrumbs automatically wrap on smaller screens.
+          </p>
+        </div>
+        <div className="max-w-md">
           <Breadcrumb>
             <BreadcrumbList>
               <BreadcrumbItem>
-                <BreadcrumbLink href="/">
-                  <Home className="h-4 w-4" />
-                  Home
-                </BreadcrumbLink>
+                <BreadcrumbLink href="#">Home</BreadcrumbLink>
               </BreadcrumbItem>
               <BreadcrumbSeparator />
               <BreadcrumbItem>
-                <BreadcrumbLink href="/categories">Categories</BreadcrumbLink>
+                <BreadcrumbLink href="#">Organization Settings</BreadcrumbLink>
               </BreadcrumbItem>
               <BreadcrumbSeparator />
               <BreadcrumbItem>
-                <DropdownMenu>
-                  <DropdownMenuTrigger className="flex items-center gap-1 hover:text-foreground transition-colors">
-                    <BreadcrumbEllipsis className="h-4 w-4" />
-                    <ChevronDown className="h-3 w-3" />
-                  </DropdownMenuTrigger>
-                  <DropdownMenuContent align="start">
-                    <DropdownMenuItem>Electronics</DropdownMenuItem>
-                    <DropdownMenuItem>Computers & Tablets</DropdownMenuItem>
-                    <DropdownMenuItem>Laptops</DropdownMenuItem>
-                  </DropdownMenuContent>
-                </DropdownMenu>
+                <BreadcrumbLink href="#">Team Management</BreadcrumbLink>
               </BreadcrumbItem>
               <BreadcrumbSeparator />
               <BreadcrumbItem>
-                <BreadcrumbLink href="/categories/electronics/laptops/gaming">
-                  Gaming Laptops
-                </BreadcrumbLink>
+                <BreadcrumbLink href="#">Member Permissions</BreadcrumbLink>
               </BreadcrumbItem>
               <BreadcrumbSeparator />
               <BreadcrumbItem>
-                <BreadcrumbPage>ASUS ROG Strix G15</BreadcrumbPage>
+                <BreadcrumbPage>Role Assignment</BreadcrumbPage>
               </BreadcrumbItem>
             </BreadcrumbList>
           </Breadcrumb>
         </div>
+      </section>
 
-        {/* Page Content */}
-        <div className="grid grid-cols-1 lg:grid-cols-2 gap-8">
-          <div className="space-y-4">
-            <div className="aspect-square bg-muted rounded-lg flex items-center justify-center">
-              <span className="text-muted-foreground">Product Image</span>
-            </div>
-            <div className="grid grid-cols-4 gap-2">
-              {[1, 2, 3, 4].map((i) => (
-                <div
-                  key={i}
-                  className="aspect-square bg-muted rounded-md flex items-center justify-center"
-                >
-                  <span className="text-xs text-muted-foreground">{i}</span>
-                </div>
-              ))}
-            </div>
-          </div>
-
-          <div className="space-y-6">
-            <div>
-              <h1 className="text-3xl font-bold">
-                ASUS ROG Strix G15 Gaming Laptop
-              </h1>
-              <p className="text-xl text-muted-foreground mt-2">$1,299.99</p>
-            </div>
-
-            <div className="space-y-4">
-              <p className="text-muted-foreground">
-                Experience ultimate gaming performance with the ASUS ROG Strix
-                G15. Featuring the latest AMD Ryzen processor and NVIDIA GeForce
-                RTX graphics, this laptop delivers exceptional power for gaming
-                and content creation.
-              </p>
-
-              <div className="flex space-x-4">
-                <button className="px-6 py-2 bg-primary text-primary-foreground rounded-md hover:bg-primary/90">
-                  Add to Cart
-                </button>
-                <button className="px-6 py-2 border border-input rounded-md hover:bg-accent">
-                  Add to Wishlist
-                </button>
-              </div>
-            </div>
-
-            <div className="border-t pt-6">
-              <h3 className="font-semibold mb-2">Product Features</h3>
-              <ul className="space-y-1 text-sm text-muted-foreground">
-                <li>• AMD Ryzen 7 5800H Processor</li>
-                <li>• NVIDIA GeForce RTX 3060 Graphics</li>
-                <li>• 16GB DDR4 RAM</li>
-                <li>• 512GB NVMe SSD Storage</li>
-                <li>• 15.6&quot; Full HD 144Hz Display</li>
-              </ul>
-            </div>
-          </div>
+      {/* Component States */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Component States</h3>
+          <p className="text-muted-foreground text-sm">
+            Different states: links (interactive), page (current), and ellipsis.
+          </p>
+        </div>
+        <div className="overflow-x-auto">
+          <table className="w-full border-collapse">
+            <thead>
+              <tr className="text-muted-foreground border-b text-left text-sm">
+                <th className="pb-3 pr-4 font-medium">Component</th>
+                <th className="pb-3 pr-4 font-medium">Example</th>
+                <th className="pb-3 pr-4 font-medium">Use Case</th>
+              </tr>
+            </thead>
+            <tbody className="align-middle">
+              <tr className="border-b">
+                <td className="py-3 pr-4 font-mono text-sm">BreadcrumbLink</td>
+                <td className="py-3 pr-4">
+                  <Breadcrumb>
+                    <BreadcrumbList>
+                      <BreadcrumbItem>
+                        <BreadcrumbLink href="#">
+                          Interactive Link
+                        </BreadcrumbLink>
+                      </BreadcrumbItem>
+                    </BreadcrumbList>
+                  </Breadcrumb>
+                </td>
+                <td className="text-muted-foreground py-3 pr-4 text-sm">
+                  Navigable parent pages with hover state
+                </td>
+              </tr>
+              <tr className="border-b">
+                <td className="py-3 pr-4 font-mono text-sm">BreadcrumbPage</td>
+                <td className="py-3 pr-4">
+                  <Breadcrumb>
+                    <BreadcrumbList>
+                      <BreadcrumbItem>
+                        <BreadcrumbPage>Current Page</BreadcrumbPage>
+                      </BreadcrumbItem>
+                    </BreadcrumbList>
+                  </Breadcrumb>
+                </td>
+                <td className="text-muted-foreground py-3 pr-4 text-sm">
+                  Current page (non-interactive, higher contrast)
+                </td>
+              </tr>
+              <tr className="border-b">
+                <td className="py-3 pr-4 font-mono text-sm">
+                  BreadcrumbEllipsis
+                </td>
+                <td className="py-3 pr-4">
+                  <Breadcrumb>
+                    <BreadcrumbList>
+                      <BreadcrumbItem>
+                        <BreadcrumbEllipsis />
+                      </BreadcrumbItem>
+                    </BreadcrumbList>
+                  </Breadcrumb>
+                </td>
+                <td className="text-muted-foreground py-3 pr-4 text-sm">
+                  Collapsed sections in long paths
+                </td>
+              </tr>
+              <tr>
+                <td className="py-3 pr-4 font-mono text-sm">
+                  BreadcrumbSeparator
+                </td>
+                <td className="py-3 pr-4">
+                  <Breadcrumb>
+                    <BreadcrumbList>
+                      <BreadcrumbItem>
+                        <BreadcrumbLink href="#">Item</BreadcrumbLink>
+                      </BreadcrumbItem>
+                      <BreadcrumbSeparator />
+                      <BreadcrumbItem>
+                        <BreadcrumbPage>Item</BreadcrumbPage>
+                      </BreadcrumbItem>
+                    </BreadcrumbList>
+                  </Breadcrumb>
+                </td>
+                <td className="text-muted-foreground py-3 pr-4 text-sm">
+                  Visual separator between items (customizable)
+                </td>
+              </tr>
+            </tbody>
+          </table>
         </div>
-      </main>
+      </section>
     </div>
   ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Real-world example showing breadcrumb navigation in an e-commerce product page context. Demonstrates how breadcrumbs help users understand their location in a deep category hierarchy and provide easy navigation back to parent categories.",
-      },
-    },
-  },
+};
+
+/**
+ * Interactive playground for testing breadcrumb composition.
+ */
+export const Interactive: Story = {
+  render: () => (
+    <Breadcrumb>
+      <BreadcrumbList>
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">Home</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbLink href="#">Dashboard</BreadcrumbLink>
+        </BreadcrumbItem>
+        <BreadcrumbSeparator />
+        <BreadcrumbItem>
+          <BreadcrumbPage>Settings</BreadcrumbPage>
+        </BreadcrumbItem>
+      </BreadcrumbList>
+    </Breadcrumb>
+  ),
 };