@neynar/ui 0.1.1

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

@@ -0,0 +1,433 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { cn } from "../../../lib/utils";
+import { Theme } from "../theme";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "../card";
+import { Badge } from "../badge";
+
+/**
+ * The cn utility function combines class names with Tailwind CSS conflict resolution.
+ * It uses clsx for conditional class handling and tailwind-merge to ensure later classes
+ * override earlier ones when they conflict.
+ */
+const meta: Meta = {
+  title: "Utilities/cn",
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component: `
+The **cn** utility function is a powerful class name combiner that handles Tailwind CSS class conflicts intelligently.
+
+**Key Features:**
+- 🎯 **Smart conflict resolution** - Later Tailwind classes override earlier ones
+- 🔄 **Conditional classes** - Supports boolean, object, and array syntax
+- ⚡ **Performance optimized** - Uses clsx and tailwind-merge under the hood
+- 🎨 **Custom class support** - Extended with custom Tailwind classes
+- 💪 **Type safe** - Full TypeScript support with ClassValue types
+
+**Usage:**
+\`\`\`tsx
+import { cn } from "@neynar/ui";
+
+// Basic combining
+cn("px-4 py-2", "bg-blue-500", "text-white")
+
+// Conditional classes
+cn(
+  "base-class",
+  isActive && "active-class",
+  isDisabled && "disabled-class"
+)
+
+// Conflict resolution
+cn("px-4", "px-2") // Returns: "px-2" (later wins)
+cn("text-red-500", "text-blue-500") // Returns: "text-blue-500"
+\`\`\`
+        `,
+      },
+    },
+  },
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj;
+
+// Demo component to show cn usage
+function CnDemo() {
+  const examples = [
+    {
+      title: "Basic Combining",
+      code: `cn("px-4 py-2", "bg-blue-500", "text-white")`,
+      result: cn("px-4 py-2", "bg-blue-500", "text-white"),
+      description: "Combines multiple class strings into one",
+    },
+    {
+      title: "Conflict Resolution",
+      code: `cn("px-4", "px-2")`,
+      result: cn("px-4", "px-2"),
+      description: "Later padding class (px-2) overrides earlier one (px-4)",
+    },
+    {
+      title: "Color Conflicts",
+      code: `cn("text-red-500", "text-blue-500", "text-green-500")`,
+      result: cn("text-red-500", "text-blue-500", "text-green-500"),
+      description: "Last color class wins (text-green-500)",
+    },
+    {
+      title: "Conditional Classes",
+      code: `cn("base", true && "active", false && "disabled")`,
+      result: cn("base", "active", "disabled"),
+      description: "Only truthy conditions are included",
+    },
+    {
+      title: "Object Syntax",
+      code: `cn({ "font-bold": true, "italic": false, "underline": true })`,
+      result: cn({ "font-bold": true, italic: false, underline: true }),
+      description: "Object keys with truthy values are included",
+    },
+    {
+      title: "Complex Example",
+      code: `cn("btn", "px-4 py-2", isActive && "bg-blue-500", !isActive && "bg-gray-500")`,
+      result: cn("btn", "px-4 py-2", "bg-blue-500", "bg-gray-500"),
+      description: "Real-world component styling with conditions",
+    },
+  ];
+
+  return (
+    <div className="space-y-6">
+      <Theme />
+
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-sm font-medium">
+            Interactive Examples
+          </CardTitle>
+          <CardDescription>
+            Live demonstrations of cn utility function behavior
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-6">
+          {examples.map((example, index) => (
+            <div key={index} className="space-y-3">
+              <div className="flex items-center gap-2">
+                <Badge variant="outline" className="text-xs">
+                  {example.title}
+                </Badge>
+                <span className="text-sm text-muted-foreground">
+                  {example.description}
+                </span>
+              </div>
+
+              <div className="grid gap-3 md:grid-cols-2">
+                <div className="space-y-2">
+                  <div className="text-xs text-muted-foreground font-medium">
+                    Code
+                  </div>
+                  <pre className="text-xs bg-muted p-3 rounded overflow-x-auto">
+                    {example.code}
+                  </pre>
+                </div>
+
+                <div className="space-y-2">
+                  <div className="text-xs text-muted-foreground font-medium">
+                    Result
+                  </div>
+                  <div className="bg-muted p-3 rounded">
+                    <code className="text-xs break-all">
+                      &quot;{example.result}&quot;
+                    </code>
+                  </div>
+                </div>
+              </div>
+            </div>
+          ))}
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+/**
+ * Interactive demonstration of the cn utility function showing class combining and conflict resolution.
+ * Explore how cn handles different class combinations and Tailwind CSS conflicts.
+ */
+export const Interactive: Story = {
+  render: () => <CnDemo />,
+};
+
+/**
+ * Common usage patterns showing how cn is used in real component development.
+ */
+export const UsagePatterns: Story = {
+  render: () => (
+    <div className="space-y-6">
+      <Theme />
+
+      <div className="grid gap-6 md:grid-cols-2">
+        {/* Pattern 1: Component Variants */}
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium">
+              Component Variants
+            </CardTitle>
+            <CardDescription>
+              Using cn to create button variants
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <ComponentVariantExample />
+            <pre className="text-xs bg-muted p-3 rounded mt-4 overflow-x-auto">
+              {`function Button({ variant, size, className, ...props }) {
+  return (
+    <button
+      className={cn(
+        "inline-flex items-center justify-center",
+        "rounded-md font-medium transition-colors",
+        {
+          "bg-primary text-primary-foreground": variant === "default",
+          "border border-input bg-background": variant === "outline",
+          "bg-secondary text-secondary-foreground": variant === "secondary",
+        },
+        {
+          "h-10 px-4 py-2": size === "default",
+          "h-9 rounded-md px-3": size === "sm",
+          "h-11 rounded-md px-8": size === "lg",
+        },
+        className
+      )}
+      {...props}
+    />
+  );
+}`}
+            </pre>
+          </CardContent>
+        </Card>
+
+        {/* Pattern 2: Conditional Styling */}
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium">
+              Conditional Styling
+            </CardTitle>
+            <CardDescription>State-based class application</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <ConditionalStylingExample />
+            <pre className="text-xs bg-muted p-3 rounded mt-4 overflow-x-auto">
+              {`function Card({ isActive, isDisabled, className }) {
+  return (
+    <div
+      className={cn(
+        "border rounded-lg p-4",
+        "transition-all duration-200",
+        isActive && "border-primary bg-primary/5",
+        isDisabled && "opacity-50 cursor-not-allowed",
+        !isDisabled && "hover:shadow-md",
+        className
+      )}
+    />
+  );
+}`}
+            </pre>
+          </CardContent>
+        </Card>
+
+        {/* Pattern 3: Responsive Design */}
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium">
+              Responsive Classes
+            </CardTitle>
+            <CardDescription>Combining responsive utilities</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <ResponsiveExample />
+            <pre className="text-xs bg-muted p-3 rounded mt-4 overflow-x-auto">
+              {`function ResponsiveGrid({ columns, className }) {
+  return (
+    <div
+      className={cn(
+        "grid gap-4",
+        {
+          "grid-cols-1": columns === 1,
+          "grid-cols-1 md:grid-cols-2": columns === 2,
+          "grid-cols-1 md:grid-cols-2 lg:grid-cols-3": columns === 3,
+        },
+        "sm:gap-6 lg:gap-8",
+        className
+      )}
+    />
+  );
+}`}
+            </pre>
+          </CardContent>
+        </Card>
+
+        {/* Pattern 4: Override Protection */}
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium">
+              Safe Overrides
+            </CardTitle>
+            <CardDescription>Allowing prop-based customization</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <OverrideExample />
+            <pre className="text-xs bg-muted p-3 rounded mt-4 overflow-x-auto">
+              {`function Alert({ variant, className }) {
+  return (
+    <div
+      className={cn(
+        // Base styles
+        "relative w-full rounded-lg border p-4",
+        "[&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4",
+        // Variant styles (can be overridden)
+        {
+          "bg-background text-foreground": variant === "default",
+          "border-destructive/50 text-destructive": variant === "destructive",
+        },
+        // User overrides come last
+        className
+      )}
+    />
+  );
+}`}
+            </pre>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  ),
+};
+
+// Helper components for the examples
+function ComponentVariantExample() {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const Button = ({ variant, size, className, children, ...props }: any) => (
+    <button
+      className={cn(
+        "inline-flex items-center justify-center",
+        "rounded-md font-medium transition-colors",
+        {
+          "bg-primary text-primary-foreground hover:bg-primary/90":
+            variant === "default",
+          "border border-input bg-background hover:bg-accent":
+            variant === "outline",
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80":
+            variant === "secondary",
+        },
+        {
+          "h-10 px-4 py-2 text-sm": size === "default",
+          "h-9 rounded-md px-3 text-xs": size === "sm",
+          "h-11 rounded-md px-8": size === "lg",
+        },
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+
+  return (
+    <div className="flex flex-wrap gap-2">
+      <Button variant="default" size="sm">
+        Primary
+      </Button>
+      <Button variant="outline" size="sm">
+        Outline
+      </Button>
+      <Button variant="secondary" size="sm">
+        Secondary
+      </Button>
+    </div>
+  );
+}
+
+function ConditionalStylingExample() {
+  const states = [
+    { label: "Normal", isActive: false, isDisabled: false },
+    { label: "Active", isActive: true, isDisabled: false },
+    { label: "Disabled", isActive: false, isDisabled: true },
+  ];
+
+  return (
+    <div className="space-y-2">
+      {states.map((state) => (
+        <div
+          key={state.label}
+          className={cn(
+            "border rounded-lg p-3 text-sm",
+            "transition-all duration-200",
+            state.isActive && "border-primary bg-primary/5",
+            state.isDisabled && "opacity-50 cursor-not-allowed",
+            !state.isDisabled && "hover:shadow-sm",
+          )}
+        >
+          {state.label} State
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function ResponsiveExample() {
+  return (
+    <div
+      className={cn(
+        "grid gap-2",
+        "grid-cols-1 md:grid-cols-2 lg:grid-cols-3",
+        "sm:gap-3 lg:gap-4",
+      )}
+    >
+      {[1, 2, 3].map((i) => (
+        <div key={i} className="bg-muted rounded p-2 text-center text-xs">
+          Item {i}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function OverrideExample() {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const Alert = ({ variant, className, children }: any) => (
+    <div
+      className={cn(
+        "relative w-full rounded-lg border p-3",
+        {
+          "bg-background text-foreground": variant === "default",
+          "border-destructive/50 text-destructive dark:border-destructive":
+            variant === "destructive",
+        },
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+
+  return (
+    <div className="space-y-2">
+      <Alert variant="default">
+        <div className="text-xs">Default alert styling</div>
+      </Alert>
+      <Alert variant="destructive">
+        <div className="text-xs">Destructive alert styling</div>
+      </Alert>
+      <Alert
+        variant="default"
+        className="bg-blue-50 border-blue-200 text-blue-800 dark:bg-blue-950 dark:border-blue-800 dark:text-blue-200"
+      >
+        <div className="text-xs">Custom override with className prop</div>
+      </Alert>
+    </div>
+  );
+}

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

@@ -0,0 +1,256 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import * as React from "react";
+import { ChevronDown, Settings, HelpCircle, Info } from "lucide-react";
+import { Collapsible, CollapsibleTrigger, CollapsibleContent } from "../collapsible";
+import { Button } from "../button";
+
+const meta = {
+  title: "Layout and Structure/Collapsible",
+  component: Collapsible,
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component:
+          "An interactive component which expands/collapses a panel. Built with Radix UI primitives and perfect for FAQ sections, expandable details, and settings panels.",
+      },
+    },
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    open: {
+      control: "boolean",
+      description: "Controls the open state of the collapsible",
+    },
+    defaultOpen: {
+      control: "boolean", 
+      description: "The initial open state when uncontrolled",
+    },
+    disabled: {
+      control: "boolean",
+      description: "When true, prevents the user from interacting with the collapsible",
+    },
+    onOpenChange: {
+      action: "onOpenChange",
+      description: "Callback fired when the open state changes",
+    },
+  },
+} satisfies Meta<typeof Collapsible>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Interactive playground for testing all collapsible props and behaviors.
+ * Use the controls panel to experiment with different configurations.
+ */
+export const Interactive: Story = {
+  render: (args) => {
+    const [isOpen, setIsOpen] = React.useState(args.defaultOpen ?? false);
+    
+    return (
+      <Collapsible 
+        {...args}
+        open={args.open ?? isOpen}
+        onOpenChange={(open) => {
+          setIsOpen(open);
+          args.onOpenChange?.(open);
+        }}
+        className="w-96 space-y-2"
+      >
+        <CollapsibleTrigger asChild>
+          <Button variant="outline" className="w-full justify-between" disabled={args.disabled}>
+            Can I use this in my project?
+            <ChevronDown className="h-4 w-4" />
+          </Button>
+        </CollapsibleTrigger>
+        <CollapsibleContent className="rounded-md border px-4 py-3 bg-muted/50">
+          <p className="text-sm">
+            Yes. Free to use for personal and commercial projects. 
+            No attribution required.
+          </p>
+          <p className="text-sm text-muted-foreground mt-2">
+            This interactive example demonstrates the collapsible functionality
+            with smooth animations and accessibility features.
+          </p>
+        </CollapsibleContent>
+      </Collapsible>
+    );
+  },
+  args: {
+    defaultOpen: false,
+    disabled: false,
+  },
+};
+
+/**
+ * Showcase of different collapsible variants and styling approaches.
+ * Demonstrates various visual styles and use cases.
+ */
+export const Variants: Story = {
+  render: () => (
+    <div className="w-96 space-y-6">
+      {/* Basic Button Style */}
+      <div className="space-y-2">
+        <h4 className="text-sm font-semibold text-muted-foreground">Button Style</h4>
+        <Collapsible className="space-y-2">
+          <CollapsibleTrigger asChild>
+            <Button variant="outline" className="w-full justify-between">
+              Basic Button Trigger
+              <ChevronDown className="h-4 w-4" />
+            </Button>
+          </CollapsibleTrigger>
+          <CollapsibleContent className="rounded-md border px-4 py-3 bg-muted/50">
+            <p className="text-sm">Content revealed with button-style trigger.</p>
+          </CollapsibleContent>
+        </Collapsible>
+      </div>
+
+      {/* Custom Trigger Style */}
+      <div className="space-y-2">
+        <h4 className="text-sm font-semibold text-muted-foreground">Custom Trigger</h4>
+        <Collapsible className="space-y-2">
+          <CollapsibleTrigger className="flex items-center justify-between w-full p-3 bg-secondary rounded-md hover:bg-secondary/80 transition-colors">
+            <span className="font-medium flex items-center gap-2">
+              <Settings className="h-4 w-4" />
+              Advanced Settings
+            </span>
+            <ChevronDown className="h-4 w-4" />
+          </CollapsibleTrigger>
+          <CollapsibleContent className="rounded-md border px-4 py-3">
+            <p className="text-sm">Settings panel with custom styled trigger.</p>
+          </CollapsibleContent>
+        </Collapsible>
+      </div>
+
+      {/* FAQ Style */}
+      <div className="space-y-2">
+        <h4 className="text-sm font-semibold text-muted-foreground">FAQ Style</h4>
+        <Collapsible className="space-y-2">
+          <CollapsibleTrigger className="flex items-center gap-3 w-full p-3 text-left bg-background border rounded-md hover:bg-muted/50 transition-colors">
+            <HelpCircle className="h-4 w-4 text-blue-500" />
+            <span className="font-medium">How does this work?</span>
+            <ChevronDown className="h-4 w-4 ml-auto" />
+          </CollapsibleTrigger>
+          <CollapsibleContent className="px-4 py-3 border rounded-md bg-muted/30">
+            <p className="text-sm">FAQ-style implementation with question and answer format.</p>
+          </CollapsibleContent>
+        </Collapsible>
+      </div>
+
+      {/* Minimal Style */}
+      <div className="space-y-2">
+        <h4 className="text-sm font-semibold text-muted-foreground">Minimal Style</h4>
+        <Collapsible>
+          <CollapsibleTrigger className="font-medium hover:underline cursor-pointer">
+            Show technical details
+          </CollapsibleTrigger>
+          <CollapsibleContent className="mt-2 text-sm text-muted-foreground">
+            <p>Minimal styling with just text and underline hover effect.</p>
+          </CollapsibleContent>
+        </Collapsible>
+      </div>
+
+      {/* Alert Style */}
+      <div className="space-y-2">
+        <h4 className="text-sm font-semibold text-muted-foreground">Alert Style</h4>
+        <Collapsible className="space-y-2">
+          <CollapsibleTrigger className="flex items-center gap-3 w-full p-3 text-left bg-blue-50 border border-blue-200 rounded-md hover:bg-blue-100 transition-colors">
+            <Info className="h-4 w-4 text-blue-600" />
+            <span className="font-medium text-blue-900">Important Information</span>
+            <ChevronDown className="h-4 w-4 ml-auto text-blue-600" />
+          </CollapsibleTrigger>
+          <CollapsibleContent className="px-4 py-3 bg-blue-50 border border-blue-200 rounded-md">
+            <p className="text-sm text-blue-800">
+              Alert-style collapsible with colored background and borders.
+            </p>
+          </CollapsibleContent>
+        </Collapsible>
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Real-world usage example showing collapsibles in a dashboard settings context.
+ * Demonstrates how designers and business teams might use this component.
+ */
+export const InContext: Story = {
+  render: () => (
+    <div className="w-full max-w-2xl mx-auto space-y-6 p-6 bg-background border rounded-lg">
+      <div className="space-y-2">
+        <h2 className="text-xl font-semibold">Dashboard Settings</h2>
+        <p className="text-sm text-muted-foreground">
+          Configure your dashboard preferences and advanced options.
+        </p>
+      </div>
+
+      <div className="space-y-4">
+        {/* Profile Settings */}
+        <Collapsible defaultOpen className="space-y-3">
+          <CollapsibleTrigger className="flex items-center justify-between w-full p-4 bg-card border rounded-lg hover:bg-muted/50 transition-colors">
+            <div className="text-left">
+              <h3 className="font-medium">Profile Settings</h3>
+              <p className="text-sm text-muted-foreground">Manage your account and personal information</p>
+            </div>
+            <ChevronDown className="h-5 w-5 text-muted-foreground" />
+          </CollapsibleTrigger>
+          <CollapsibleContent className="px-4 py-3 border rounded-lg bg-muted/30">
+            <div className="grid grid-cols-2 gap-3">
+              <Button variant="outline" size="sm">Edit Profile</Button>
+              <Button variant="outline" size="sm">Change Password</Button>
+              <Button variant="outline" size="sm">Privacy Settings</Button>
+              <Button variant="outline" size="sm">Notifications</Button>
+            </div>
+          </CollapsibleContent>
+        </Collapsible>
+
+        {/* Advanced Configuration */}
+        <Collapsible className="space-y-3">
+          <CollapsibleTrigger className="flex items-center justify-between w-full p-4 bg-card border rounded-lg hover:bg-muted/50 transition-colors">
+            <div className="text-left">
+              <h3 className="font-medium">Advanced Configuration</h3>
+              <p className="text-sm text-muted-foreground">API keys, webhooks, and developer settings</p>
+            </div>
+            <ChevronDown className="h-5 w-5 text-muted-foreground" />
+          </CollapsibleTrigger>
+          <CollapsibleContent className="px-4 py-3 border rounded-lg bg-muted/30">
+            <div className="space-y-3">
+              <div className="flex items-center justify-between">
+                <span className="text-sm font-medium">API Access</span>
+                <Button variant="outline" size="sm">Manage Keys</Button>
+              </div>
+              <div className="flex items-center justify-between">
+                <span className="text-sm font-medium">Webhooks</span>
+                <Button variant="outline" size="sm">Configure</Button>
+              </div>
+              <div className="flex items-center justify-between">
+                <span className="text-sm font-medium">Developer Mode</span>
+                <Button variant="outline" size="sm">Enable</Button>
+              </div>
+            </div>
+          </CollapsibleContent>
+        </Collapsible>
+
+        {/* Help & Support */}
+        <Collapsible className="space-y-3">
+          <CollapsibleTrigger className="flex items-center justify-between w-full p-4 bg-card border rounded-lg hover:bg-muted/50 transition-colors">
+            <div className="text-left">
+              <h3 className="font-medium">Help & Support</h3>
+              <p className="text-sm text-muted-foreground">Documentation, tutorials, and support resources</p>
+            </div>
+            <ChevronDown className="h-5 w-5 text-muted-foreground" />
+          </CollapsibleTrigger>
+          <CollapsibleContent className="px-4 py-3 border rounded-lg bg-muted/30">
+            <div className="space-y-2">
+              <a href="#" className="block text-sm text-blue-600 hover:underline">Getting Started Guide</a>
+              <a href="#" className="block text-sm text-blue-600 hover:underline">API Documentation</a>
+              <a href="#" className="block text-sm text-blue-600 hover:underline">Video Tutorials</a>
+              <a href="#" className="block text-sm text-blue-600 hover:underline">Contact Support</a>
+            </div>
+          </CollapsibleContent>
+        </Collapsible>
+      </div>
+    </div>
+  ),
+};