@neynar/ui 0.3.1 → 0.5.0

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

@@ -1,431 +0,0 @@
-"use client";
-
-import { Monitor, Moon, Sun } from "lucide-react";
-import { Button, buttonVariants } from "@/components/ui/button";
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
-import { useTheme } from "@/hooks/use-theme";
-import { cn } from "@/lib/utils";
-import { type VariantProps } from "class-variance-authority";
-
-/**
- * Props for ThemeToggle (Documentation only - NOT used in component implementation)
- *
- * Combines Button variant props with DropdownMenu positioning props to create a complete
- * theme switching interface. All props are optional with sensible defaults for immediate usage.
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type ThemeToggleDocsProps = {
-  /**
-   * Visual style variant for the toggle button (inherited from Button component)
-   *
-   * Controls the appearance and semantic meaning of the theme toggle button:
-   * - `"default"` - Primary action button with brand colors and elevated appearance
-   * - `"destructive"` - Red-themed button for dangerous actions (not recommended for theme toggles)
-   * - `"outline"` - Secondary action with subtle border and background hover states (recommended)
-   * - `"secondary"` - Alternative secondary styling with muted colors
-   * - `"ghost"` - Minimal styling with hover states, ideal for toolbars and navigation
-   * - `"link"` - Text-only button styled like a hyperlink with underline on hover
-   *
-   * @default "outline"
-   */
-  variant?:
-    | "default"
-    | "destructive"
-    | "outline"
-    | "secondary"
-    | "ghost"
-    | "link";
-
-  /**
-   * Size variant for the toggle button (inherited from Button component)
-   *
-   * Controls the dimensions and padding of the theme toggle button:
-   * - `"default"` - Standard height (36px) suitable for most interfaces
-   * - `"sm"` - Compact height (32px) for dense layouts or secondary areas
-   * - `"lg"` - Large height (40px) for prominent placement in headers
-   * - `"icon"` - Square (36px × 36px) optimized for icon-only display
-   *
-   * When using non-icon sizes, consider enabling `showLabel` for better UX.
-   *
-   * @default "icon"
-   */
-  size?: "default" | "sm" | "lg" | "icon";
-
-  /**
-   * Additional CSS classes to apply to the toggle button
-   *
-   * Allows for custom styling and integration with your design system.
-   * Classes are merged with the default button styles using the `cn` utility.
-   *
-   * @example
-   * ```tsx
-   * // Add custom border and shadow
-   * <ThemeToggle className="border-2 border-primary shadow-lg" />
-   *
-   * // Position in a flex container
-   * <ThemeToggle className="ml-auto" />
-   * ```
-   */
-  className?: string;
-
-  /**
-   * Whether to show the current theme name as text next to the icon
-   *
-   * When enabled, displays the current theme preference ("System", "Light", or "Dark")
-   * alongside the theme icon. Automatically enabled for non-icon button sizes to
-   * provide better context and accessibility.
-   *
-   * The text appears with proper spacing and responsive behavior:
-   * - Hidden on very small screens to prevent overflow
-   * - Uses semantic theme labels for screen readers
-   * - Updates immediately when theme changes
-   *
-   * @default `size !== "icon"` (true for default/sm/lg sizes, false for icon size)
-   *
-   * @example
-   * ```tsx
-   * // Icon-only button (most common)
-   * <ThemeToggle size="icon" /> // showLabel=false by default
-   *
-   * // Button with text labels
-   * <ThemeToggle size="default" /> // showLabel=true by default
-   * <ThemeToggle size="icon" showLabel /> // Force labels on icon button
-   * ```
-   */
-  showLabel?: boolean;
-
-  /**
-   * Alignment of the dropdown menu relative to the trigger button
-   *
-   * Controls how the theme selection dropdown is positioned relative to the toggle button.
-   * Uses Radix UI's alignment system with intelligent collision detection.
-   *
-   * - `"start"` - Align dropdown to the left edge of the button (LTR) or right edge (RTL)
-   * - `"center"` - Center the dropdown relative to the button
-   * - `"end"` - Align dropdown to the right edge of the button (LTR) or left edge (RTL)
-   *
-   * The dropdown automatically adjusts position to stay within viewport boundaries.
-   *
-   * @default "end"
-   *
-   * @example
-   * ```tsx
-   * // Align dropdown to button start (typical for left-side placement)
-   * <ThemeToggle align="start" />
-   *
-   * // Center alignment (good for isolated buttons)
-   * <ThemeToggle align="center" />
-   *
-   * // End alignment (typical for right-side placement like headers)
-   * <ThemeToggle align="end" /> // This is the default
-   * ```
-   */
-  align?: "start" | "center" | "end";
-} & React.ComponentProps<"button"> & {
-    /**
-     * Render as child element, merging props and behavior (inherited from Button component)
-     * @default false
-     */
-    asChild?: boolean;
-  };
-
-type ThemeToggleProps = {
-  /**
-   * Whether to show the current theme name as text next to the icon
-   * @default `size !== "icon"`
-   */
-  showLabel?: boolean;
-  /**
-   * Alignment of the dropdown menu relative to the trigger button
-   * @default "end"
-   */
-  align?: "start" | "center" | "end";
-} & React.ComponentProps<typeof Button> &
-  VariantProps<typeof buttonVariants>;
-
-/**
- * ThemeToggle - A zero-configuration theme switcher with system, light, and dark modes
- *
- * A completely self-contained theme toggle component that provides an intuitive dropdown
- * interface for switching between system preference, light mode, and dark mode. Works
- * immediately without any provider setup, context configuration, or additional dependencies.
- *
- * Built on top of shadcn/ui components (Button + DropdownMenu) with the Neynar useTheme
- * hook for state management. Handles theme persistence via cookies, system preference
- * detection, real-time system changes, and synchronization across multiple instances.
- *
- * **Zero Configuration Design:**
- * Just import and use - no providers, no setup, no configuration required. The component
- * handles all theme management internally and provides a complete solution out of the box.
- *
- * **Perfect for:**
- * - Application headers and navigation bars
- * - Settings panels and preference screens
- * - Toolbars and floating action areas
- * - Any location where users need quick theme access
- *
- * @example Basic usage (most common - icon button)
- * ```tsx
- * // Just drop it in! Works immediately with zero setup
- * function Header() {
- *   return (
- *     <header className="flex items-center justify-between p-4">
- *       <Logo />
- *       <ThemeToggle /> // That's it!
- *     </header>
- *   );
- * }
- * ```
- *
- * @example With text labels for better UX
- * ```tsx
- * // Show current theme name next to icon
- * <ThemeToggle size="default" showLabel />
- *
- * // In a settings panel
- * <div className="space-y-4">
- *   <h3>Appearance</h3>
- *   <div className="flex items-center justify-between">
- *     <span>Theme</span>
- *     <ThemeToggle size="sm" showLabel />
- *   </div>
- * </div>
- * ```
- *
- * @example Different visual variants
- * ```tsx
- * // Ghost button for minimalist toolbars
- * <ThemeToggle variant="ghost" />
- *
- * // Secondary style for subtle integration
- * <ThemeToggle variant="secondary" size="sm" />
- *
- * // Outline style (default) for clear boundaries
- * <ThemeToggle variant="outline" size="lg" />
- * ```
- *
- * @example Custom positioning and styling
- * ```tsx
- * // Custom alignment and styling
- * <ThemeToggle
- *   align="start"
- *   className="border-2 border-primary shadow-lg"
- * />
- *
- * // Multiple synchronized instances
- * function App() {
- *   return (
- *     <>
- *       <Header>
- *         <ThemeToggle /> // Changes sync automatically
- *       </Header>
- *       <Sidebar>
- *         <ThemeToggle variant="ghost" size="sm" /> // Stays in sync
- *       </Sidebar>
- *     </>
- *   );
- * }
- * ```
- *
- * @example Integration with navigation patterns
- * ```tsx
- * // Header navigation with multiple controls
- * <header className="border-b bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
- *   <div className="container flex h-14 items-center">
- *     <div className="flex items-center space-x-2">
- *       <Logo />
- *       <nav className="hidden md:flex items-center space-x-6">
- *         <Link href="/docs">Documentation</Link>
- *         <Link href="/examples">Examples</Link>
- *       </nav>
- *     </div>
- *     <div className="flex items-center space-x-2 ml-auto">
- *       <Button variant="ghost" size="sm">Settings</Button>
- *       <ThemeToggle />
- *       <UserMenu />
- *     </div>
- *   </div>
- * </header>
- *
- * // Sidebar with theme control in footer
- * <aside className="w-64 border-r bg-muted/40">
- *   <nav className="flex-1 p-4">
- *     // Navigation items
- *   </nav>
- *   <footer className="p-4 border-t">
- *     <div className="flex items-center justify-between">
- *       <UserProfile compact />
- *       <ThemeToggle variant="ghost" size="sm" />
- *     </div>
- *   </footer>
- * </aside>
- * ```
- *
- * @example Advanced usage patterns
- * ```tsx
- * // Responsive behavior with different sizes
- * <div className="flex items-center gap-2">
- *   <span className="hidden sm:inline-block text-sm">Theme:</span>
- *   <ThemeToggle
- *     size={{ base: "sm", md: "default" }}
- *     showLabel={{ base: false, sm: true }}
- *   />
- * </div>
- *
- * // Conditional rendering based on user preferences
- * function CustomThemeControl({ userPrefersAdvanced }: { userPrefersAdvanced: boolean }) {
- *   if (userPrefersAdvanced) {
- *     return <AdvancedThemePanel />;
- *   }
- *   return <ThemeToggle showLabel />;
- * }
- * ```
- *
- * @param variant - Visual style variant inherited from Button component (default: "outline")
- * @param size - Size variant inherited from Button component (default: "icon")
- * @param className - Additional CSS classes for custom styling
- * @param showLabel - Whether to show theme name text (auto-enabled for non-icon sizes)
- * @param align - Dropdown menu alignment relative to trigger button (default: "end")
- *
- * @features
- * - **Zero Configuration**: Import and use immediately - no setup required
- * - **System Detection**: Automatically follows OS dark/light preference changes
- * - **Perfect Persistence**: Theme choice saved via cookies for SSR compatibility
- * - **Multi-Instance Sync**: Multiple toggles stay perfectly synchronized
- * - **Real-Time Updates**: Responds to system theme changes while app is running
- * - **Smooth Transitions**: CSS-based theme switching with no flash of wrong content
- * - **Accessibility First**: Full keyboard navigation and screen reader support
- * - **Touch Optimized**: Works perfectly on mobile and tablet devices
- * - **Framework Agnostic**: Works with Next.js, Vite, Create React App, etc.
- *
- * @accessibility
- * - **Keyboard Navigation**: Full support for Enter, Space, and Arrow keys
- * - **Screen Reader Support**: Proper ARIA labels and role announcements
- * - **Focus Management**: Visible focus indicators meeting WCAG 2.1 AA standards
- * - **State Communication**: Current selection clearly indicated with checkmarks
- * - **High Contrast**: Works with system high contrast modes
- * - **Reduced Motion**: Respects user's motion preferences
- * - **Semantic HTML**: Uses proper button and menu semantics
- * - **Live Regions**: Theme changes announced to assistive technology
- *
- * @technical
- * **Component Architecture:**
- * - Built with Radix UI primitives for robust accessibility
- * - Uses Tailwind CSS with CSS custom properties for theming
- * - State managed by custom `useTheme` hook with event-driven synchronization
- * - Cookie-based persistence with 1-year expiration
- * - Client-side hydration safe with SSR support
- *
- * **Performance Characteristics:**
- * - Minimal bundle size impact (only imports what's needed)
- * - No context overhead (direct hook usage)
- * - Efficient event-driven updates (single state change per theme switch)
- * - Lazy loading compatible (works in code-split components)
- * - No memory leaks (automatic cleanup of event listeners)
- *
- * **Browser Support:**
- * - Modern browsers with CSS custom properties support
- * - IE11+ with polyfills for CustomEvent and matchMedia
- * - Graceful degradation for older browsers
- * - Progressive enhancement for advanced features
- *
- * @remarks
- * **State Management:**
- * This component uses the {@link useTheme} hook internally to manage theme state.
- * Theme changes are persisted automatically via cookies and synchronized across
- * all browser tabs and multiple component instances using custom events.
- *
- * **Styling Integration:**
- * The component integrates with your existing design system through Tailwind CSS
- * and shadcn/ui patterns. Themes are applied via CSS custom properties and dark
- * mode class toggles, ensuring compatibility with most styling approaches.
- *
- * **Server-Side Rendering:**
- * Fully compatible with SSR frameworks like Next.js. Theme preference is stored
- * in cookies to prevent hydration mismatches, and the component gracefully handles
- * server/client differences.
- *
- * @see {@link useTheme} - The underlying theme management hook with event-driven architecture
- * @see {@link Button} - Base button component providing variant and size styling
- * @see {@link DropdownMenu} - Menu component providing accessible dropdown interaction
- * @see {@link DropdownMenuContent} - Content container with positioning and collision detection
- * @see {@link DropdownMenuItem} - Individual menu items with proper focus management
- * @see {@link ThemePreference} - Type definition for available theme options
- * @since 1.0.0
- */
-function ThemeToggle({
-  variant = "outline",
-  size = "icon",
-  className,
-  showLabel,
-  align = "end",
-  ...props
-}: ThemeToggleProps) {
-  // Auto-enable showLabel for non-icon sizes if not explicitly set
-  const shouldShowLabel = showLabel !== undefined ? showLabel : size !== "icon";
-  const { preference, setPreference } = useTheme();
-
-  // Simple icons and labels - no configuration needed
-  const items = [
-    {
-      mode: "system" as const,
-      icon: <Monitor className="h-4 w-4" />,
-      label: "System",
-    },
-    {
-      mode: "light" as const,
-      icon: <Sun className="h-4 w-4" />,
-      label: "Light",
-    },
-    {
-      mode: "dark" as const,
-      icon: <Moon className="h-4 w-4" />,
-      label: "Dark",
-    },
-  ];
-
-  // Get current item based on preference, not resolved mode
-  const currentItem =
-    items.find((item) => item.mode === preference) || items[0];
-
-  return (
-    <DropdownMenu>
-      <DropdownMenuTrigger asChild>
-        <Button
-          variant={variant}
-          size={size}
-          className={cn(className)}
-          {...props}
-        >
-          {currentItem?.icon}
-          {shouldShowLabel && (
-            <span className="ml-2">{currentItem?.label}</span>
-          )}
-          <span className="sr-only">Toggle theme</span>
-        </Button>
-      </DropdownMenuTrigger>
-      <DropdownMenuContent align={align}>
-        {items.map((item) => (
-          <DropdownMenuItem
-            key={item.mode}
-            onClick={() => setPreference(item.mode)}
-            className="flex items-center gap-2"
-          >
-            {item.icon}
-            <span>{item.label}</span>
-            {preference === item.mode && (
-              <span className="ml-auto text-xs opacity-60">✓</span>
-            )}
-          </DropdownMenuItem>
-        ))}
-      </DropdownMenuContent>
-    </DropdownMenu>
-  );
-}
-
-export { ThemeToggle };

package/src/components/ui/theme.tsx

@@ -1,247 +0,0 @@
-"use client";
-
-import { useTheme } from "../../hooks/use-theme";
-
-/**
- * Props for Theme (Documentation only - NOT used in component implementation)
- *
- * The Theme component requires no props as it operates with zero configuration.
- * It automatically detects and applies the user's theme preference from cookies
- * and system settings without any external input.
- */
-// eslint-disable-next-line unused-imports/no-unused-vars
-type ThemeDocsProps = Record<string, never>;
-
-/**
- * Theme - Prevents flash of unstyled content (FOUC) during theme initialization
- *
- * A critical component that prevents the flash of incorrect theme styling by applying
- * the user's preferred theme before the page renders. This component should be placed
- * once at the root of your application, ideally in the document head or at the very
- * beginning of the body.
- *
- * The component works by injecting a small inline script that:
- * 1. Reads the stored theme preference from cookies
- * 2. Detects system theme preference if set to "system"
- * 3. Applies the appropriate theme class and color scheme immediately
- * 4. Executes synchronously before first paint to prevent FOUC
- *
- * Built as a zero-configuration component that requires no props or setup. Simply
- * drop it into your application's root layout and it will handle theme initialization
- * automatically.
- *
- * @component
- * @example Basic usage in Next.js App Router
- * ```tsx
- * import { Theme } from "@neynar/ui";
- *
- * export default function RootLayout({ children }) {
- *   return (
- *     <html lang="en" suppressHydrationWarning>
- *       <head>
- *         <Theme />
- *       </head>
- *       <body>{children}</body>
- *     </html>
- *   );
- * }
- * ```
- *
- * @example Usage in Vite/React
- * ```tsx
- * import { Theme } from "@neynar/ui";
- *
- * function App() {
- *   return (
- *     <>
- *       <Theme />
- *       <div className="app">
- *         App content here
- *       </div>
- *     </>
- *   );
- * }
- * ```
- *
- * @example Usage with Remix
- * ```tsx
- * import { Theme } from "@neynar/ui";
- *
- * export default function Root() {
- *   return (
- *     <html lang="en">
- *       <head>
- *         <Theme />
- *         <Meta />
- *         <Links />
- *       </head>
- *       <body>
- *         <Outlet />
- *         <ScrollRestoration />
- *         <Scripts />
- *       </body>
- *     </html>
- *   );
- * }
- * ```
- *
- * @example Usage with Gatsby
- * ```tsx
- * import { Theme } from "@neynar/ui";
- *
- * export function wrapRootElement({ element }) {
- *   return (
- *     <>
- *       <Theme />
- *       {element}
- *     </>
- *   );
- * }
- * ```
- *
- * @example Usage in plain React
- * ```tsx
- * import { Theme } from "@neynar/ui";
- * import { createRoot } from "react-dom/client";
- *
- * const root = createRoot(document.getElementById('root'));
- * root.render(
- *   <>
- *     <Theme />
- *     <App />
- *   </>
- * );
- * ```
- *
- * @features
- * - **FOUC Prevention**: Applies theme before first paint to eliminate flash
- * - **Framework Agnostic**: Works with Next.js, Vite, Remix, Gatsby, and other React frameworks
- * - **SSR Compatible**: Handles server-side rendering correctly without hydration issues
- * - **System Detection**: Automatically follows OS dark/light preference when set to "system"
- * - **Cookie Persistence**: Maintains theme preference across browser sessions and tabs
- * - **Minimal Overhead**: Tiny inline script (~0.5KB minified) with no external dependencies
- * - **Zero Configuration**: Works immediately without any setup or props
- * - **Error Resilient**: Graceful fallback to light theme on any execution errors
- *
- * @accessibility
- * - Respects `prefers-color-scheme` media query for system theme preference
- * - Maintains proper color contrast ratios in both light and dark themes
- * - Compatible with screen readers and assistive technology
- * - Follows WCAG 2.1 guidelines for color and contrast accessibility
- * - Supports high contrast mode when available in the operating system
- * - No accessibility barriers introduced by the theme switching mechanism
- *
- * @performance
- * - **Critical Path Optimization**: Executes before React hydration to prevent FOUC
- * - **Zero Dependencies**: No external libraries or network requests required
- * - **Inline Execution**: Script runs immediately without additional round trips
- * - **Minimal Size**: Compressed script adds negligible overhead to page load
- * - **No Runtime Cost**: Zero ongoing performance impact after initial execution
- * - **Memory Efficient**: No persistent JavaScript objects or event listeners
- *
- * @security
- * - **Safe HTML Injection**: Uses `dangerouslySetInnerHTML` with verified safe content
- * - **No External Sources**: All code is inline with no external script references
- * - **No Dynamic Evaluation**: No use of `eval()`, `Function()`, or similar dynamic execution
- * - **Error Boundaries**: Comprehensive try-catch blocks prevent script failures
- * - **Cookie Safety**: Proper parsing and validation of cookie data
- * - **XSS Protection**: No user input or dynamic content injection
- *
- * @browser-support
- * - **Modern Browsers**: Full support in all modern browsers (Chrome 60+, Firefox 55+, Safari 12+)
- * - **Legacy Browsers**: Graceful degradation in older browsers (defaults to light theme)
- * - **Mobile Browsers**: Full support on iOS Safari, Chrome Mobile, Samsung Internet
- * - **Media Query Support**: Requires `matchMedia` API for system theme detection
- * - **Cookie Support**: Requires cookies for theme persistence (standard in all browsers)
- * - **JavaScript Required**: Non-functional with JavaScript disabled (graceful degradation)
- *
- * @implementation-details
- * **Script Execution Flow:**
- * 1. Parse theme cookie using safe JSON parsing with error handling
- * 2. Extract user preference (system/light/dark) from stored data
- * 3. If "system", query `prefers-color-scheme` media query for OS preference
- * 4. Apply corresponding CSS class ('dark') and color-scheme property
- * 5. Handle any errors by defaulting to light theme
- *
- * **Cookie Structure:**
- * ```json
- * {
- *   "preference": "system" | "light" | "dark",
- *   "mode": "light" | "dark"
- * }
- * ```
- *
- * **DOM Modifications:**
- * - Adds or removes 'dark' class on `document.documentElement`
- * - Sets `color-scheme` CSS property for native element theming
- * - Changes are applied synchronously before first paint
- *
- * @remarks
- * This component must be used alongside the {@link useTheme} hook and
- * {@link ThemeToggle} component for a complete theming solution. The Theme
- * component handles initial theme application (FOUC prevention), while the
- * hook manages runtime theme changes and the toggle provides user interface.
- *
- * **Architecture Overview:**
- * - **Theme Component**: Prevents FOUC by applying initial theme
- * - **useTheme Hook**: Manages theme state and preference changes at runtime
- * - **ThemeToggle Component**: Provides user interface for theme selection
- * - **Cookie Persistence**: Shared storage mechanism between all components
- *
- * The component is designed to work with Tailwind CSS's dark mode strategy,
- * specifically the 'dark' class approach. It applies the 'dark' class to the
- * document root and sets the appropriate color-scheme CSS property for native
- * element theming.
- *
- * **Integration Requirements:**
- * - Tailwind CSS configured with `darkMode: 'class'` strategy
- * - CSS custom properties for theme-aware color definitions
- * - Proper color contrast ratios defined for both light and dark themes
- * - Optional: CSS transitions for smooth theme switching
- *
- * @see {@link useTheme} - Hook for managing theme state and preferences at runtime
- * @see {@link ThemeToggle} - UI component for user-initiated theme switching
- * @see {@link https://tailwindcss.com/docs/dark-mode} - Tailwind CSS dark mode documentation
- * @since 1.0.0
- */
-export function Theme() {
-  useTheme();
-  return (
-    <script
-      dangerouslySetInnerHTML={{
-        __html: `
-          (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 the 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';
-            }
-          })();
-        `,
-      }}
-    />
-  );
-}