@neynar/ui 0.1.1

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

@@ -0,0 +1,531 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState, useEffect } from "react";
+import { useTheme } from "../../../hooks/use-theme";
+import { Theme } from "../theme";
+import { ThemeToggle } from "../theme-toggle";
+import { Button } from "../button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "../card";
+import { Badge } from "../badge";
+import { Moon, Sun, Monitor } from "lucide-react";
+
+/**
+ * The useTheme hook provides a simple, powerful way to manage theme state in React applications.
+ * It handles system preference detection, cookie persistence, and synchronization across multiple instances.
+ */
+const meta: Meta = {
+  title: "Theme/useTheme",
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component: `
+The **useTheme** hook provides complete theme management functionality with automatic system preference detection, cookie persistence, and perfect synchronization across multiple instances.
+
+**Key Features:**
+- 🌓 **Automatic theme switching** - Follows system light/dark preference when set to "system"
+- 🍪 **Cookie persistence** - Maintains theme choice across browser sessions
+- 🔄 **Perfect synchronization** - Multiple hook instances stay in sync via custom events
+- ⚡ **Event-driven updates** - Responds to system theme changes in real-time
+- 🚀 **Zero configuration** - Works out of the box without providers
+- 🎯 **Type safe** - Full TypeScript support
+
+**Usage:**
+\`\`\`tsx
+import { useTheme } from "@neynar/ui";
+
+function ThemeToggle() {
+  const { preference, mode, setPreference } = useTheme();
+  
+  const toggleTheme = () => {
+    setPreference(mode === "dark" ? "light" : "dark");
+  };
+  
+  return (
+    <button onClick={toggleTheme}>
+      Current: {mode} (preference: {preference})
+    </button>
+  );
+}
+\`\`\`
+        `,
+      },
+    },
+  },
+  tags: ["autodocs"],
+};
+
+export default meta;
+type Story = StoryObj;
+
+// Demo component to show hook usage
+function ThemeDemo() {
+  const { preference, mode, setPreference } = useTheme();
+  const [systemTheme, setSystemTheme] = useState<"light" | "dark">("light");
+
+  useEffect(() => {
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+    setSystemTheme(mediaQuery.matches ? "dark" : "light");
+
+    const handleChange = (e: MediaQueryListEvent) => {
+      setSystemTheme(e.matches ? "dark" : "light");
+    };
+
+    mediaQuery.addEventListener("change", handleChange);
+    return () => mediaQuery.removeEventListener("change", handleChange);
+  }, []);
+
+  return (
+    <div className="space-y-6">
+      <Theme />
+
+      {/* Status Display */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-sm font-medium">Hook State</CardTitle>
+          <CardDescription>
+            Current values returned by the useTheme hook
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+            <div className="text-center p-4 border rounded-lg">
+              <div className="text-sm text-muted-foreground mb-2">
+                User Preference
+              </div>
+              <div className="flex items-center justify-center gap-2">
+                {preference === "system" && <Monitor className="h-4 w-4" />}
+                {preference === "light" && <Sun className="h-4 w-4" />}
+                {preference === "dark" && <Moon className="h-4 w-4" />}
+                <Badge variant="outline" className="text-sm">
+                  {preference}
+                </Badge>
+              </div>
+            </div>
+
+            <div className="text-center p-4 border rounded-lg">
+              <div className="text-sm text-muted-foreground mb-2">
+                Active Mode
+              </div>
+              <div className="flex items-center justify-center gap-2">
+                {mode === "light" && <Sun className="h-4 w-4" />}
+                {mode === "dark" && <Moon className="h-4 w-4" />}
+                <Badge variant="secondary" className="text-sm">
+                  {mode}
+                </Badge>
+              </div>
+            </div>
+
+            <div className="text-center p-4 border rounded-lg">
+              <div className="text-sm text-muted-foreground mb-2">
+                System Preference
+              </div>
+              <div className="flex items-center justify-center gap-2">
+                {systemTheme === "light" && <Sun className="h-4 w-4" />}
+                {systemTheme === "dark" && <Moon className="h-4 w-4" />}
+                <Badge variant="outline" className="text-sm">
+                  {systemTheme}
+                </Badge>
+              </div>
+            </div>
+          </div>
+
+          <div className="text-xs text-muted-foreground bg-muted/50 p-3 rounded">
+            <strong>Explanation:</strong> When preference is &quot;system&quot;,
+            the active mode follows your OS setting. When set to
+            &quot;light&quot; or &quot;dark&quot;, the mode is fixed regardless
+            of system preference.
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Theme Controls */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-sm font-medium">Theme Controls</CardTitle>
+          <CardDescription>
+            Use setPreference() to change the theme
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="flex flex-wrap gap-3">
+            <Button
+              variant={preference === "system" ? "default" : "outline"}
+              size="sm"
+              onClick={() => setPreference("system")}
+              className="flex items-center gap-2"
+            >
+              <Monitor className="h-4 w-4" />
+              System
+            </Button>
+
+            <Button
+              variant={preference === "light" ? "default" : "outline"}
+              size="sm"
+              onClick={() => setPreference("light")}
+              className="flex items-center gap-2"
+            >
+              <Sun className="h-4 w-4" />
+              Light
+            </Button>
+
+            <Button
+              variant={preference === "dark" ? "default" : "outline"}
+              size="sm"
+              onClick={() => setPreference("dark")}
+              className="flex items-center gap-2"
+            >
+              <Moon className="h-4 w-4" />
+              Dark
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+
+      {/* Code Example */}
+      <Card>
+        <CardHeader>
+          <CardTitle className="text-sm font-medium">Implementation</CardTitle>
+          <CardDescription>How the buttons above work</CardDescription>
+        </CardHeader>
+        <CardContent>
+          <pre className="text-xs bg-muted p-4 rounded overflow-x-auto">
+            {`const { preference, mode, setPreference } = useTheme();
+
+// Set to follow system preference
+<Button onClick={() => setPreference('system')}>
+  System ({mode})
+</Button>
+
+// Set to light mode
+<Button onClick={() => setPreference('light')}>
+  Light
+</Button>
+
+// Set to dark mode  
+<Button onClick={() => setPreference('dark')}>
+  Dark
+</Button>
+
+// Current state:
+// preference: "${preference}"
+// mode: "${mode}"`}
+          </pre>
+        </CardContent>
+      </Card>
+    </div>
+  );
+}
+
+/**
+ * Interactive demonstration of the useTheme hook showing all return values and methods.
+ * Change the theme preference and see how the hook state updates in real-time.
+ */
+export const Interactive: Story = {
+  render: () => <ThemeDemo />,
+};
+
+/**
+ * Multiple synchronized theme controls showing how the hook maintains consistency across instances.
+ * All controls share the same state through cookie persistence and custom event synchronization.
+ */
+export const MultipleSynchronizedInstances: Story = {
+  render: () => (
+    <div className="space-y-6">
+      <Theme />
+
+      <Card>
+        <CardHeader>
+          <CardTitle>Perfect Synchronization</CardTitle>
+          <CardDescription>
+            Multiple useTheme hook instances automatically stay in sync. Change
+            one and watch them all update.
+          </CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-6">
+          {/* Instance 1 - Button Group */}
+          <div className="border rounded-lg p-4">
+            <h3 className="text-sm font-medium mb-3">
+              Instance 1: Button Group
+            </h3>
+            <ThemeControlButtons />
+          </div>
+
+          {/* Instance 2 - Theme Toggle Component */}
+          <div className="border rounded-lg p-4">
+            <h3 className="text-sm font-medium mb-3">
+              Instance 2: ThemeToggle Component
+            </h3>
+            <div className="flex items-center justify-between">
+              <span className="text-sm text-muted-foreground">
+                Built-in component using useTheme:
+              </span>
+              <ThemeToggle showLabel />
+            </div>
+          </div>
+
+          {/* Instance 3 - Status Display */}
+          <div className="border rounded-lg p-4">
+            <h3 className="text-sm font-medium mb-3">
+              Instance 3: Live Status Display
+            </h3>
+            <ThemeStatusDisplay />
+          </div>
+
+          <div className="text-xs text-muted-foreground bg-accent/50 p-3 rounded">
+            <strong>Technical Details:</strong> Each useTheme instance
+            dispatches custom events when the theme changes. All other instances
+            listen for these events and update their state accordingly, ensuring
+            perfect synchronization without the need for React context or
+            external state management.
+          </div>
+        </CardContent>
+      </Card>
+    </div>
+  ),
+};
+
+/**
+ * Real-world usage examples showing common implementation patterns.
+ */
+export const UsagePatterns: Story = {
+  render: () => (
+    <div className="space-y-6">
+      <Theme />
+
+      <div className="grid gap-6 md:grid-cols-2">
+        {/* Pattern 1: Simple Toggle */}
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium">Simple Toggle</CardTitle>
+            <CardDescription>Basic light/dark mode toggle</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <SimpleToggleExample />
+            <pre className="text-xs bg-muted p-3 rounded mt-4 overflow-x-auto">
+              {`function SimpleToggle() {
+  const { mode, setPreference } = useTheme();
+  
+  const toggle = () => {
+    setPreference(mode === 'dark' ? 'light' : 'dark');
+  };
+  
+  return (
+    <Button onClick={toggle}>
+      {mode === 'dark' ? <Sun /> : <Moon />}
+      {mode} Mode
+    </Button>
+  );
+}`}
+            </pre>
+          </CardContent>
+        </Card>
+
+        {/* Pattern 2: Conditional Rendering */}
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium">
+              Conditional Content
+            </CardTitle>
+            <CardDescription>
+              Render different content based on theme
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <ConditionalContentExample />
+            <pre className="text-xs bg-muted p-3 rounded mt-4 overflow-x-auto">
+              {`function ThemedContent() {
+  const { mode } = useTheme();
+  
+  return (
+    <div>
+      {mode === 'dark' ? (
+        <div>🌙 Dark mode content</div>
+      ) : (
+        <div>☀️ Light mode content</div>
+      )}
+    </div>
+  );
+}`}
+            </pre>
+          </CardContent>
+        </Card>
+
+        {/* Pattern 3: System Preference Handler */}
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium">
+              System Integration
+            </CardTitle>
+            <CardDescription>
+              Respect user&apos;s system preference
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <SystemIntegrationExample />
+            <pre className="text-xs bg-muted p-3 rounded mt-4 overflow-x-auto">
+              {`function SystemThemeInfo() {
+  const { preference, mode } = useTheme();
+  
+  return (
+    <div>
+      <p>Preference: {preference}</p>
+      <p>Active: {mode}</p>
+      {preference === 'system' && (
+        <p>Following OS setting</p>
+      )}
+    </div>
+  );
+}`}
+            </pre>
+          </CardContent>
+        </Card>
+
+        {/* Pattern 4: Theme Status Badge */}
+        <Card>
+          <CardHeader>
+            <CardTitle className="text-sm font-medium">
+              Status Indicator
+            </CardTitle>
+            <CardDescription>Show current theme in UI</CardDescription>
+          </CardHeader>
+          <CardContent>
+            <ThemeStatusBadgeExample />
+            <pre className="text-xs bg-muted p-3 rounded mt-4 overflow-x-auto">
+              {`function ThemeStatusBadge() {
+  const { preference, mode } = useTheme();
+  
+  return (
+    <Badge variant="outline">
+      {preference === 'system' 
+        ? \`System (\${mode})\`
+        : mode
+      }
+    </Badge>
+  );
+}`}
+            </pre>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  ),
+};
+
+// Helper components for the stories
+function ThemeControlButtons() {
+  const { preference, setPreference } = useTheme();
+
+  return (
+    <div className="flex gap-2">
+      {(["system", "light", "dark"] as const).map((theme) => (
+        <Button
+          key={theme}
+          variant={preference === theme ? "default" : "outline"}
+          size="sm"
+          onClick={() => setPreference(theme)}
+          className="flex items-center gap-2"
+        >
+          {theme === "system" && <Monitor className="h-3 w-3" />}
+          {theme === "light" && <Sun className="h-3 w-3" />}
+          {theme === "dark" && <Moon className="h-3 w-3" />}
+          {theme.charAt(0).toUpperCase() + theme.slice(1)}
+        </Button>
+      ))}
+    </div>
+  );
+}
+
+function ThemeStatusDisplay() {
+  const { preference, mode } = useTheme();
+
+  return (
+    <div className="flex items-center gap-4 text-sm">
+      <div>
+        <span className="text-muted-foreground">Preference:</span>{" "}
+        <Badge variant="outline">{preference}</Badge>
+      </div>
+      <div>
+        <span className="text-muted-foreground">Active:</span>{" "}
+        <Badge variant="secondary">{mode}</Badge>
+      </div>
+    </div>
+  );
+}
+
+function SimpleToggleExample() {
+  const { mode, setPreference } = useTheme();
+
+  const toggle = () => {
+    setPreference(mode === "dark" ? "light" : "dark");
+  };
+
+  return (
+    <Button onClick={toggle} variant="outline" size="sm">
+      {mode === "dark" ? (
+        <Sun className="mr-2 h-4 w-4" />
+      ) : (
+        <Moon className="mr-2 h-4 w-4" />
+      )}
+      {mode === "dark" ? "Light" : "Dark"} Mode
+    </Button>
+  );
+}
+
+function ConditionalContentExample() {
+  const { mode } = useTheme();
+
+  return (
+    <div className="p-3 border rounded text-center">
+      {mode === "dark" ? (
+        <div className="flex items-center justify-center gap-2">
+          <Moon className="h-4 w-4" />
+          <span>🌙 Dark mode active</span>
+        </div>
+      ) : (
+        <div className="flex items-center justify-center gap-2">
+          <Sun className="h-4 w-4" />
+          <span>☀️ Light mode active</span>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function SystemIntegrationExample() {
+  const { preference, mode } = useTheme();
+
+  return (
+    <div className="space-y-2 text-sm">
+      <div>
+        Preference: <Badge variant="outline">{preference}</Badge>
+      </div>
+      <div>
+        Active Mode: <Badge variant="secondary">{mode}</Badge>
+      </div>
+      {preference === "system" && (
+        <div className="text-muted-foreground">✓ Following system setting</div>
+      )}
+    </div>
+  );
+}
+
+function ThemeStatusBadgeExample() {
+  const { preference, mode } = useTheme();
+
+  return (
+    <div className="flex justify-center">
+      <Badge variant="outline" className="flex items-center gap-2">
+        {preference === "system" && <Monitor className="h-3 w-3" />}
+        {preference === "light" && <Sun className="h-3 w-3" />}
+        {preference === "dark" && <Moon className="h-3 w-3" />}
+        {preference === "system" ? `System (${mode})` : mode}
+      </Badge>
+    </div>
+  );
+}

package/src/components/ui/switch.tsx

@@ -0,0 +1,106 @@
+import * as React from "react";
+import * as SwitchPrimitive from "@radix-ui/react-switch";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Switch component for binary toggle controls
+ *
+ * A versatile toggle switch component built on Radix UI primitives that provides
+ * an accessible way to toggle between on/off states. Commonly used for settings,
+ * preferences, and feature toggles that have immediate effects.
+ *
+ * Built with Radix UI Switch primitive and styled with Tailwind CSS to ensure
+ * consistent visual appearance across light and dark themes.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage with label
+ * <div className="flex items-center space-x-2">
+ *   <Switch id="airplane-mode" />
+ *   <Label htmlFor="airplane-mode">Airplane Mode</Label>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled switch with state
+ * const [enabled, setEnabled] = useState(false);
+ *
+ * <Switch
+ *   id="notifications"
+ *   checked={enabled}
+ *   onCheckedChange={setEnabled}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Switch with custom handler
+ * <Switch
+ *   checked={isDarkMode}
+ *   onCheckedChange={(checked) => {
+ *     setIsDarkMode(checked);
+ *     document.documentElement.classList.toggle("dark", checked);
+ *   }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Disabled switch
+ * <Switch disabled />
+ * <Switch disabled defaultChecked />
+ * ```
+ *
+ * @accessibility
+ * - Fully keyboard accessible with Space and Enter key support
+ * - ARIA attributes automatically managed by Radix UI
+ * - Screen reader announcements for state changes
+ * - Focus indicator with visible ring
+ * - Associates with labels via htmlFor/id pairing
+ * - Disabled state properly communicated to assistive technology
+ * - Follows WAI-ARIA Switch pattern
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/switch} shadcn/ui Switch documentation
+ * @since 1.0.0
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/switch} Radix UI Switch primitive
+ */
+/**
+ * Switch component props
+ *
+ * Extends all props from Radix UI Switch Root primitive, including:
+ * - `checked` - The controlled checked state of the switch
+ * - `defaultChecked` - The default checked state when uncontrolled
+ * - `onCheckedChange` - Event handler called when the checked state changes
+ * - `disabled` - Whether the switch is disabled
+ * - `required` - Whether the switch is required in forms
+ * - `name` - Name attribute for form submission
+ * - `value` - Value attribute for form submission
+ *
+ * @param className - Additional CSS classes to apply to the switch
+ * @param props - All other props from Radix UI Switch Root
+ */
+type SwitchProps = React.ComponentProps<typeof SwitchPrimitive.Root>;
+
+function Switch({ className, ...props }: SwitchProps) {
+  return (
+    <SwitchPrimitive.Root
+      data-slot="switch"
+      className={cn(
+        "peer data-[state=checked]:bg-primary data-[state=unchecked]:bg-input focus-visible:border-ring focus-visible:ring-ring/50 dark:data-[state=unchecked]:bg-input/80 inline-flex h-[1.15rem] w-8 shrink-0 items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50",
+        className,
+      )}
+      {...props}
+    >
+      <SwitchPrimitive.Thumb
+        data-slot="switch-thumb"
+        className={cn(
+          "bg-background dark:data-[state=unchecked]:bg-foreground dark:data-[state=checked]:bg-primary-foreground pointer-events-none block size-4 rounded-full ring-0 transition-transform data-[state=checked]:translate-x-[calc(100%-2px)] data-[state=unchecked]:translate-x-0",
+        )}
+      />
+    </SwitchPrimitive.Root>
+  );
+}
+
+export { Switch };