@neynar/ui 0.1.1

package/src/components/ui/stories/theme-toggle.stories.tsx

@@ -0,0 +1,275 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { ThemeToggle } from "../theme-toggle";
+
+/**
+ * ThemeToggle component stories for design system documentation
+ *
+ * This story file demonstrates the ThemeToggle component's capabilities through three focused stories:
+ * - Interactive: Playground for testing all props and custom theme configurations
+ * - Variants: Systematic showcase of all available styles, sizes, and theme combinations
+ * - InContext: Real-world usage examples for business and design teams
+ */
+const meta = {
+  title: "Theme/ThemeToggle",
+  component: ThemeToggle,
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component:
+          "An advanced theme toggle component that supports custom themes, visual styling, and color-coded indicators. Built on top of the framework-agnostic useTheme hook for maximum compatibility across different React environments.",
+      },
+    },
+  },
+  tags: ["autodocs"],
+  argTypes: {
+    variant: {
+      control: { type: "select" },
+      options: [
+        "default",
+        "destructive",
+        "outline",
+        "secondary",
+        "ghost",
+        "link",
+      ],
+      description: "Visual style variant for the toggle button",
+    },
+    size: {
+      control: { type: "select" },
+      options: ["default", "sm", "lg", "icon"],
+      description:
+        "Size of the toggle button - icon shows only icon, others include text",
+    },
+    className: {
+      control: "text",
+      description: "Additional CSS classes to apply to the button",
+    },
+  },
+  args: {
+    variant: "outline",
+    size: "icon",
+  },
+} satisfies Meta<typeof ThemeToggle>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Interactive Playground Story
+ *
+ * Use this story to test all ThemeToggle props and configurations through Storybook controls.
+ * Perfect for designers and developers to experiment with custom themes and styling options.
+ */
+export const Interactive: Story = {
+  args: {
+    variant: "outline",
+    size: "icon",
+    showLabel: false,
+    align: "end",
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Interactive playground for testing all ThemeToggle properties. Use the controls panel to experiment with custom themes, colors, variants, and visual options. The component will persist theme changes using cookies.",
+      },
+    },
+  },
+};
+
+/**
+ * Variants Showcase Story
+ *
+ * Systematic display of all available ThemeToggle variants, sizes, and custom theme configurations.
+ * Helps design teams understand the full range of available options and styling capabilities.
+ */
+export const Variants: Story = {
+  render: () => (
+    <div className="space-y-8">
+      {/* Size Variants */}
+      <div className="space-y-4">
+        <h3 className="text-lg font-semibold">Size Variants</h3>
+        <div className="flex items-center gap-4">
+          <div className="space-y-2">
+            <div className="text-sm text-muted-foreground">Icon</div>
+            <ThemeToggle size="icon" />
+          </div>
+          <div className="space-y-2">
+            <div className="text-sm text-muted-foreground">Small</div>
+            <ThemeToggle size="sm" />
+          </div>
+          <div className="space-y-2">
+            <div className="text-sm text-muted-foreground">Default</div>
+            <ThemeToggle size="default" />
+          </div>
+          <div className="space-y-2">
+            <div className="text-sm text-muted-foreground">Large</div>
+            <ThemeToggle size="lg" />
+          </div>
+        </div>
+      </div>
+
+      {/* Visual Variants */}
+      <div className="space-y-4">
+        <h3 className="text-lg font-semibold">Visual Variants</h3>
+        <div className="flex flex-wrap gap-3">
+          <ThemeToggle variant="default" size="sm" />
+          <ThemeToggle variant="outline" size="sm" />
+          <ThemeToggle variant="secondary" size="sm" />
+          <ThemeToggle variant="ghost" size="sm" />
+          <ThemeToggle variant="link" size="sm" />
+        </div>
+      </div>
+
+      {/* Custom Themes */}
+      <div className="space-y-4">
+        <h3 className="text-lg font-semibold">Custom Themes</h3>
+        <div className="space-y-3">
+          <div className="space-y-2">
+            <div className="text-sm text-muted-foreground">
+              Basic Custom Themes
+            </div>
+            <ThemeToggle size="default" />
+          </div>
+
+          <div className="space-y-2">
+            <div className="text-sm text-muted-foreground">
+              With Color Indicators
+            </div>
+            <ThemeToggle size="default" />
+          </div>
+
+          <div className="space-y-2">
+            <div className="text-sm text-muted-foreground">
+              System-Respecting Theme
+            </div>
+            <ThemeToggle size="default" />
+          </div>
+        </div>
+      </div>
+
+      {/* Advanced Styling */}
+      <div className="space-y-4">
+        <h3 className="text-lg font-semibold">Advanced Styling</h3>
+        <div className="flex flex-wrap gap-3">
+          <ThemeToggle variant="outline" size="default" className="border-2" />
+
+          <ThemeToggle variant="secondary" size="lg" className="border-2" />
+        </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        story:
+          "Complete showcase of all ThemeToggle variants, sizes, custom theme configurations, and styling options. Use this as a reference for what's available in the design system and how custom themes work.",
+      },
+    },
+  },
+};
+
+/**
+ * Real-world Context Story
+ *
+ * Demonstrates the ThemeToggle component in realistic UI scenarios.
+ * Helps business teams and designers understand practical usage patterns and integration approaches.
+ */
+export const InContext: Story = {
+  render: () => (
+    <div className="space-y-8 max-w-2xl">
+      {/* Application Header */}
+      <div className="space-y-4">
+        <h3 className="text-lg font-semibold">Application Header</h3>
+        <div className="flex items-center justify-between p-4 border rounded-lg bg-card">
+          <div className="flex items-center gap-3">
+            <div className="h-8 w-8 rounded-full bg-primary" />
+            <h2 className="font-semibold">My Application</h2>
+          </div>
+          <div className="flex items-center gap-2">
+            <button className="px-3 py-1.5 text-sm rounded-md hover:bg-muted">
+              Profile
+            </button>
+            <ThemeToggle variant="ghost" size="icon" />
+          </div>
+        </div>
+      </div>
+
+      {/* Settings Panel */}
+      <div className="space-y-4">
+        <h3 className="text-lg font-semibold">Settings Panel</h3>
+        <div className="p-6 border rounded-lg bg-card space-y-4">
+          <h4 className="font-medium">Appearance</h4>
+          <div className="space-y-3">
+            <div className="flex items-center justify-between">
+              <div>
+                <div className="font-medium">Theme</div>
+                <div className="text-sm text-muted-foreground">
+                  Choose your preferred color scheme
+                </div>
+              </div>
+              <ThemeToggle size="default" variant="outline" />
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* Design System Demo */}
+      <div className="space-y-4">
+        <h3 className="text-lg font-semibold">Design System Customization</h3>
+        <div className="p-6 border rounded-lg bg-card space-y-4">
+          <h4 className="font-medium">Brand Themes</h4>
+          <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+            <div className="space-y-2">
+              <div className="text-sm font-medium">Marketing Site</div>
+              <ThemeToggle size="sm" variant="secondary" />
+            </div>
+
+            <div className="space-y-2">
+              <div className="text-sm font-medium">Creative Tools</div>
+              <ThemeToggle size="sm" variant="outline" />
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* Mobile Layout */}
+      <div className="space-y-4">
+        <h3 className="text-lg font-semibold">Mobile Navigation</h3>
+        <div className="max-w-sm mx-auto border rounded-lg bg-card">
+          <div className="p-4 border-b">
+            <div className="flex items-center justify-between">
+              <h4 className="font-medium">Settings</h4>
+              <ThemeToggle size="icon" variant="ghost" />
+            </div>
+          </div>
+          <div className="p-4 space-y-3">
+            <div className="flex items-center justify-between py-2">
+              <span>Notifications</span>
+              <div className="w-10 h-6 bg-primary rounded-full" />
+            </div>
+            <div className="flex items-center justify-between py-2">
+              <span>Theme</span>
+              <ThemeToggle size="sm" variant="outline" />
+            </div>
+            <div className="flex items-center justify-between py-2">
+              <span>Language</span>
+              <span className="text-sm text-muted-foreground">English</span>
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        story:
+          "Real-world usage examples showing how ThemeToggle integrates into common UI patterns like application headers, settings panels, and mobile layouts. These patterns demonstrate practical implementation approaches for different use cases.",
+      },
+    },
+  },
+};

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

@@ -0,0 +1,412 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { Theme } from "../theme";
+import { ThemeToggle } from "../theme-toggle";
+import { Card, CardHeader, CardTitle, CardContent } from "../card";
+import { Button } from "../button";
+
+/**
+ * Theme stories demonstrate FOUC prevention and theming system setup
+ *
+ * The Theme component prevents flash of unstyled content (FOUC) by applying
+ * the user's preferred theme before the page renders. It should be placed once
+ * at the root of your application for optimal theming experience.
+ *
+ * These stories showcase:
+ * - Basic Theme component setup
+ * - Integration with ThemeToggle for user controls
+ * - Multiple synchronized theme toggles
+ * - Framework-agnostic theming patterns
+ */
+const meta = {
+  title: "Theme/Theme",
+  component: Theme,
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component: `
+The Theme component prevents flash of unstyled content (FOUC) by injecting a small script that applies the correct theme before the page renders.
+
+**Key Features:**
+- ⚡ Prevents FOUC (flash of unstyled content)
+- 🌐 Framework agnostic (Next.js, Vite, Remix, etc.)
+- 🔄 Perfect synchronization across multiple theme toggles
+- 🍪 Persistent theme storage via cookies
+- 🎨 System theme detection and following
+- ⚙️ Zero configuration required
+
+**Usage:**
+Place the Theme component once at the root of your application, ideally in the document head or at the very top of your app component.
+        `,
+      },
+    },
+  },
+  tags: ["autodocs"],
+} satisfies Meta<typeof Theme>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Basic usage showing the Theme component with a simple themed interface.
+ * The Theme component should be placed at the top of your application to prevent FOUC.
+ */
+export const Basic: Story = {
+  render: () => (
+    <div className="min-h-screen bg-background text-foreground p-8">
+      <Theme />
+
+      <div className="max-w-2xl mx-auto space-y-6">
+        <div className="text-center space-y-2">
+          <h1 className="text-3xl font-bold">Theme Setup Demo</h1>
+          <p className="text-muted-foreground">
+            The Theme component prevents FOUC and enables theming system
+          </p>
+        </div>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>Themed Content</CardTitle>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            <p className="text-sm text-muted-foreground">
+              This content is themed correctly without any flash of unstyled
+              content. The Theme component loads the user&apos;s preferred theme
+              before first paint.
+            </p>
+
+            <div className="flex items-center justify-center">
+              <ThemeToggle />
+            </div>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Demonstrates multiple synchronized theme toggles working together.
+ * All toggles stay perfectly in sync through the custom event system.
+ */
+export const MultipleSynchronizedToggles: Story = {
+  render: () => (
+    <div className="min-h-screen bg-background text-foreground">
+      <Theme />
+
+      {/* Header with theme toggle */}
+      <header className="border-b p-4">
+        <div className="max-w-4xl mx-auto flex items-center justify-between">
+          <h1 className="text-xl font-semibold">My App</h1>
+          <ThemeToggle />
+        </div>
+      </header>
+
+      {/* Main content */}
+      <main className="p-8">
+        <div className="max-w-4xl mx-auto grid gap-6 md:grid-cols-2">
+          <Card>
+            <CardHeader>
+              <div className="flex items-center justify-between">
+                <CardTitle>Settings Panel</CardTitle>
+                <ThemeToggle variant="ghost" size="sm" />
+              </div>
+            </CardHeader>
+            <CardContent className="space-y-4">
+              <p className="text-sm text-muted-foreground">
+                This toggle is synchronized with all other theme toggles on the
+                page. Try switching themes and watch how they all update
+                together.
+              </p>
+              <Button variant="outline">Configure Settings</Button>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <div className="flex items-center justify-between">
+                <CardTitle>User Profile</CardTitle>
+                <ThemeToggle variant="secondary" showLabel />
+              </div>
+            </CardHeader>
+            <CardContent className="space-y-4">
+              <p className="text-sm text-muted-foreground">
+                All theme toggles use the same underlying state via cookies and
+                custom events. This ensures perfect synchronization without any
+                providers or context.
+              </p>
+              <Button>Update Profile</Button>
+            </CardContent>
+          </Card>
+        </div>
+      </main>
+
+      {/* Footer with another toggle */}
+      <footer className="border-t mt-8 p-4">
+        <div className="max-w-4xl mx-auto flex items-center justify-between">
+          <p className="text-sm text-muted-foreground">
+            Footer content with synchronized theme
+          </p>
+          <ThemeToggle variant="outline" size="sm" />
+        </div>
+      </footer>
+    </div>
+  ),
+};
+
+/**
+ * Framework integration examples showing how to use Theme with different React frameworks.
+ * This story demonstrates the setup patterns for Next.js, Vite, and other frameworks.
+ */
+export const FrameworkIntegration: Story = {
+  render: () => (
+    <div className="min-h-screen bg-background text-foreground p-8">
+      <Theme />
+
+      <div className="max-w-4xl mx-auto space-y-8">
+        <div className="text-center space-y-2">
+          <h1 className="text-3xl font-bold">Framework Integration</h1>
+          <p className="text-muted-foreground">
+            Theme component works with any React framework
+          </p>
+        </div>
+
+        <div className="grid gap-6 md:grid-cols-2">
+          <Card>
+            <CardHeader>
+              <CardTitle>Next.js App Router</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <pre className="text-xs bg-muted p-3 rounded overflow-x-auto">
+                {`// app/layout.tsx
+import { Theme } from "@neynar/ui";
+
+export default function RootLayout({ children }) {
+  return (
+    <html suppressHydrationWarning>
+      <head>
+        <Theme /> {/* Prevents FOUC */}
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}`}
+              </pre>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Vite + React</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <pre className="text-xs bg-muted p-3 rounded overflow-x-auto">
+                {`// App.tsx
+import { Theme } from "@neynar/ui";
+
+function App() {
+  return (
+    <>
+      <Theme /> {/* Place at the top */}
+      <div className="app">
+        {/* Your content */}
+      </div>
+    </>
+  );
+}`}
+              </pre>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Next.js Pages Router</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <pre className="text-xs bg-muted p-3 rounded overflow-x-auto">
+                {`// pages/_document.tsx
+import { Theme } from "@neynar/ui";
+
+export default function Document() {
+  return (
+    <Html>
+      <Head>
+        <Theme /> {/* In document head */}
+      </Head>
+      <body>
+        <Main />
+        <NextScript />
+      </body>
+    </Html>
+  );
+}`}
+              </pre>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Remix</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <pre className="text-xs bg-muted p-3 rounded overflow-x-auto">
+                {`// app/root.tsx
+import { Theme } from "@neynar/ui";
+
+export default function Root() {
+  return (
+    <html>
+      <head>
+        <Theme /> {/* Before other head content */}
+        <Meta />
+        <Links />
+      </head>
+      <body>
+        <Outlet />
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}`}
+              </pre>
+            </CardContent>
+          </Card>
+        </div>
+
+        <Card>
+          <CardHeader>
+            <CardTitle>Live Demo</CardTitle>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            <p className="text-sm text-muted-foreground">
+              The Theme component is already active on this page, preventing
+              FOUC and enabling the theme system to work correctly. Use the
+              toggle below to test theme switching.
+            </p>
+
+            <div className="flex items-center justify-center">
+              <ThemeToggle showLabel />
+            </div>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Technical implementation details showing how the Theme component works internally.
+ * This story provides insight into the script content and architecture.
+ */
+export const TechnicalDetails: Story = {
+  render: () => (
+    <div className="min-h-screen bg-background text-foreground p-8">
+      <Theme />
+
+      <div className="max-w-4xl mx-auto space-y-6">
+        <div className="text-center space-y-2">
+          <h1 className="text-3xl font-bold">How Theme Works</h1>
+          <p className="text-muted-foreground">
+            Under the hood technical details
+          </p>
+        </div>
+
+        <div className="grid gap-6">
+          <Card>
+            <CardHeader>
+              <CardTitle>Script Content</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <p className="text-sm text-muted-foreground mb-4">
+                The Theme component injects a small inline script that executes
+                before React hydration:
+              </p>
+              <pre className="text-xs bg-muted p-3 rounded overflow-x-auto max-h-60">
+                {`// Injected script content (minified in production)
+(function() {
+  try {
+    // Read theme preference from cookie
+    var cookie = document.cookie.match(/theme=([^;]*)/);
+    var stored = cookie ? JSON.parse(decodeURIComponent(cookie[1])) : null;
+    var preference = stored ? stored.preference : 'system';
+    var mode;
+    
+    // Determine active theme mode
+    if (preference === 'system') {
+      mode = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+    } else {
+      mode = preference;
+    }
+    
+    // Apply theme to document root
+    if (mode === 'dark') {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+    
+    // Set color-scheme for native elements
+    document.documentElement.style.colorScheme = mode;
+  } catch (e) {
+    // Graceful fallback - default to light theme
+    document.documentElement.classList.remove('dark');
+    document.documentElement.style.colorScheme = 'light';
+  }
+})();`}
+              </pre>
+            </CardContent>
+          </Card>
+
+          <Card>
+            <CardHeader>
+              <CardTitle>Synchronization Architecture</CardTitle>
+            </CardHeader>
+            <CardContent className="space-y-4">
+              <p className="text-sm text-muted-foreground">
+                Multiple theme toggles stay perfectly synchronized through
+                custom events:
+              </p>
+
+              <div className="space-y-3">
+                <div className="flex items-center gap-3">
+                  <div className="w-2 h-2 bg-blue-500 rounded-full" />
+                  <span className="text-sm">
+                    Cookie stores theme preference (single source of truth)
+                  </span>
+                </div>
+                <div className="flex items-center gap-3">
+                  <div className="w-2 h-2 bg-green-500 rounded-full" />
+                  <span className="text-sm">
+                    Custom &apos;theme-change&apos; events broadcast changes
+                  </span>
+                </div>
+                <div className="flex items-center gap-3">
+                  <div className="w-2 h-2 bg-purple-500 rounded-full" />
+                  <span className="text-sm">
+                    All useTheme hooks listen and update in sync
+                  </span>
+                </div>
+                <div className="flex items-center gap-3">
+                  <div className="w-2 h-2 bg-orange-500 rounded-full" />
+                  <span className="text-sm">
+                    DOM updates happen immediately (no React re-render delay)
+                  </span>
+                </div>
+              </div>
+
+              <div className="flex items-center justify-center pt-4">
+                <div className="flex gap-2">
+                  <ThemeToggle variant="default" size="sm" />
+                  <ThemeToggle variant="outline" size="sm" />
+                  <ThemeToggle variant="ghost" size="sm" />
+                  <ThemeToggle variant="secondary" size="sm" />
+                </div>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+      </div>
+    </div>
+  ),
+};