@neynar/ui 0.1.1 → 0.1.2

package/dist/components/ui/textarea.d.ts

@@ -1,19 +1,20 @@
 import * as React from "react";
 /**
- * A multi-line text input control built on the native HTML textarea element
+ * Textarea - Multi-line text input control for extended content entry
  *
- * The Textarea component provides a styled textarea for entering longer pieces
- * of text that span multiple lines, such as comments, descriptions, or messages.
- * Features automatic content-based resizing using CSS field-sizing when supported
- * by the browser.
+ * A styled textarea component built on the native HTML textarea element for entering
+ * longer pieces of text that span multiple lines, such as comments, descriptions,
+ * messages, or any content that requires multiple lines of input. Features automatic
+ * content-based resizing using CSS field-sizing when supported by the browser.
  *
  * Built following shadcn/ui design patterns with consistent styling and behavior
- * across form elements.
+ * across form elements. Inherits all native HTML textarea functionality while
+ * providing enhanced visual design and better accessibility patterns.
  *
  * @example
  * ```tsx
  * // Basic usage
- * <Textarea placeholder="Type your message here." />
+ * <Textarea placeholder="Type your message here..." />
  * ```
  *
  * @example
@@ -25,14 +26,16 @@ import * as React from "react";
  *     id="description"
  *     placeholder="Enter a description..."
  *     rows={4}
+ *     required
  *   />
  * </div>
  * ```
  *
  * @example
  * ```tsx
- * // Controlled with character limit
+ * // Controlled with character limit and validation
  * const [bio, setBio] = useState("");
+ * const [error, setError] = useState("");
  * const maxLength = 160;
  *
  * <div className="space-y-2">
@@ -40,43 +43,117 @@ import * as React from "react";
  *   <Textarea
  *     id="bio"
  *     value={bio}
- *     onChange={(e) => setBio(e.target.value)}
+ *     onChange={(e) => {
+ *       setBio(e.target.value);
+ *       if (e.target.value.length > maxLength) {
+ *         setError("Bio is too long");
+ *       } else {
+ *         setError("");
+ *       }
+ *     }}
  *     placeholder="Tell us about yourself..."
  *     maxLength={maxLength}
+ *     aria-invalid={!!error}
+ *     aria-describedby={error ? "bio-error" : "bio-count"}
  *   />
- *   <p className="text-sm text-muted-foreground">
- *     {bio.length}/{maxLength} characters
- *   </p>
+ *   <div className="flex justify-between items-center">
+ *     <p id="bio-count" className="text-sm text-muted-foreground">
+ *       {bio.length}/{maxLength} characters
+ *     </p>
+ *     {error && (
+ *       <p id="bio-error" className="text-sm text-destructive">
+ *         {error}
+ *       </p>
+ *     )}
+ *   </div>
  * </div>
  * ```
  *
  * @example
  * ```tsx
- * // With error state
+ * // Auto-resizing with minimum height
  * <Textarea
- *   placeholder="Enter your feedback"
- *   aria-invalid="true"
- *   aria-describedby="feedback-error"
- *   className="border-destructive"
+ *   placeholder="This textarea grows with content"
+ *   className="min-h-[100px] max-h-[300px]"
+ *   style={{ resize: "vertical" }}
  * />
- * <p id="feedback-error" className="text-sm text-destructive">
- *   This field is required
- * </p>
  * ```
  *
- * @param className - Additional CSS classes to apply
- * @param ...props - All standard HTML textarea attributes are supported
+ * @example
+ * ```tsx
+ * // Form integration with validation
+ * <form onSubmit={handleSubmit}>
+ *   <div className="space-y-2">
+ *     <Label htmlFor="feedback">Feedback</Label>
+ *     <Textarea
+ *       id="feedback"
+ *       name="feedback"
+ *       placeholder="Share your thoughts..."
+ *       required
+ *       minLength={10}
+ *       maxLength={500}
+ *       rows={3}
+ *     />
+ *   </div>
+ *   <Button type="submit">Submit Feedback</Button>
+ * </form>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Different wrap behaviors for code/text
+ * <div className="space-y-4">
+ *   <div>
+ *     <Label>Code (no wrapping)</Label>
+ *     <Textarea
+ *       wrap="off"
+ *       placeholder="Enter code here..."
+ *       className="font-mono text-sm"
+ *       style={{ resize: "both" }}
+ *     />
+ *   </div>
+ *   <div>
+ *     <Label>Text (soft wrapping)</Label>
+ *     <Textarea
+ *       wrap="soft"
+ *       placeholder="Enter text content..."
+ *     />
+ *   </div>
+ * </div>
+ * ```
  *
  * @accessibility
- * - Inherits all native textarea accessibility features
- * - Supports keyboard navigation with visible focus indicators
- * - Compatible with screen readers and assistive technologies
- * - Properly handles aria-invalid for validation states
- * - Works seamlessly with Label components via htmlFor/id association
- * - Respects disabled and readonly states
- * - Auto-resizing maintains proper focus and scroll behavior
+ * - Full keyboard navigation with Tab to focus and Shift+Tab to unfocus
+ * - Screen reader compatible with proper labeling support
+ * - ARIA state management for validation (aria-invalid, aria-describedby)
+ * - Supports assistive technology form field recognition
+ * - Visible focus indicators with ring outline for keyboard users
+ * - Respects disabled and read-only states for interaction prevention
+ * - Automatic association with Label components via htmlFor/id pattern
+ * - Auto-resizing maintains proper focus and scroll position
+ * - Character limits announced to screen readers when using aria-describedby
+ * - Spell checking integration with assistive technologies
+ *
+ * @behavior
+ * - Auto-resizing based on content using CSS field-sizing property
+ * - Smooth transitions for focus states and validation changes
+ * - Native browser resize handle (unless overridden with CSS resize property)
+ * - Form validation integration with HTML5 constraint validation API
+ * - Clipboard operations (cut, copy, paste) work as expected
+ * - Text selection and manipulation using standard keyboard shortcuts
+ *
+ * @styling
+ * - Base styles provide consistent appearance across form elements
+ * - Focus-visible styles with ring and border color changes
+ * - Error state styling via aria-invalid attribute with destructive colors
+ * - Dark mode support with appropriate background and text colors
+ * - Shadow and border transitions for interactive feedback
+ * - Disabled state with reduced opacity and pointer-events disabled
  *
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea} MDN textarea documentation
  * @see {@link https://ui.shadcn.com/docs/components/textarea} shadcn/ui Textarea documentation
+ * @see {@link Label} For proper labeling and accessibility association
+ * @see {@link Input} Single-line text input alternative
  * @since 1.0.0
  */
 declare function Textarea({ className, ...props }: React.ComponentProps<"textarea">): import("react/jsx-runtime").JSX.Element;

package/dist/components/ui/textarea.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"textarea.d.ts","sourceRoot":"","sources":["../../../src/components/ui/textarea.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,iBAAS,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,UAAU,CAAC,2CAW1E;AAED,OAAO,EAAE,QAAQ,EAAE,CAAC"}
+{"version":3,"file":"textarea.d.ts","sourceRoot":"","sources":["../../../src/components/ui/textarea.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AA8E/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4JG;AACH,iBAAS,QAAQ,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,UAAU,CAAC,2CAW1E;AAED,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/components/ui/theme-toggle.d.ts

@@ -1,105 +1,230 @@
-/**
- * Props for the ThemeToggle component
- */
-export type ThemeToggleProps = {
-    /** Visual style variant for the toggle button */
-    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link";
-    /** Size of the toggle button */
-    size?: "default" | "sm" | "lg" | "icon";
-    /** Additional CSS classes */
-    className?: string;
-    /** Whether to show text labels (only applies when size is not "icon") */
+import { Button, buttonVariants } from "@/components/ui/button";
+import { type VariantProps } from "class-variance-authority";
+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 */
+    /**
+     * 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-config theme switcher with system, light, and dark modes
+ * 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.
  *
- * A self-contained theme toggle component that works without any provider setup.
- * Provides an intuitive dropdown interface for switching between system preference,
- * light mode, and dark mode. The component handles theme persistence using cookies
- * for SSR compatibility and automatically detects system theme changes.
+ * 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.
  *
- * Built as a custom Neynar component that extends the standard shadcn/ui patterns
- * with enhanced theme management capabilities.
+ * **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.
  *
- * @component
- * @example Basic usage (icon button)
+ * **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
- * // Most common usage - just drop it in!
- * <ThemeToggle />
+ * // 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
+ * @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 Custom styling variants
+ * @example Different visual variants
  * ```tsx
- * // Ghost button for minimalist UI
+ * // Ghost button for minimalist toolbars
  * <ThemeToggle variant="ghost" />
  *
- * // Secondary style for subtlety
+ * // Secondary style for subtle integration
  * <ThemeToggle variant="secondary" size="sm" />
  *
- * // Custom positioning
- * <ThemeToggle align="start" className="border-2" />
+ * // 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 In navigation components
+ * @example Integration with navigation patterns
  * ```tsx
- * // Header navigation
- * <header className="flex items-center justify-between p-4">
- *   <Logo />
- *   <div className="flex items-center gap-2">
- *     <Button variant="ghost">Settings</Button>
- *     <ThemeToggle />
+ * // 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 footer
- * <SidebarFooter>
- *   <div className="flex items-center justify-between">
- *     <UserProfile />
- *     <ThemeToggle variant="ghost" size="sm" />
- *   </div>
- * </SidebarFooter>
+ * // 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 - Button style variant (inherits from Button component)
- * @param size - Button size, defaults to "icon" for compact display
+ * @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
+ * @param align - Dropdown menu alignment relative to trigger button (default: "end")
  *
  * @features
- * - **Zero Configuration**: Works immediately without providers or setup
- * - **System Detection**: Automatically follows OS dark/light preference
- * - **SSR Compatible**: Uses cookies for theme persistence across server/client
- * - **Smooth Transitions**: CSS-based theme switching with no flash
- * - **Accessibility**: Full keyboard navigation and screen reader support
- * - **Responsive**: Touch-friendly on mobile devices
+ * - **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
- * - Screen reader label: "Toggle theme" for assistive technology
- * - Keyboard navigation: Enter, Space, and Arrow keys for dropdown
- * - Current selection indicated with checkmark and visual styling
- * - High contrast support across all theme modes
- * - Focus visible indicators for keyboard users
+ * - **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 and synchronized across browser tabs.
- * The component is fully self-contained and doesn't interfere with existing
- * theme systems in your application.
+ * 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
- * @see {@link Button} - Base button component for styling options
- * @see {@link DropdownMenu} - Menu component used for theme selection
+ * @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
  */
-export declare function ThemeToggle({ variant, size, className, showLabel, align, }: ThemeToggleProps): import("react/jsx-runtime").JSX.Element;
+declare function ThemeToggle({ variant, size, className, showLabel, align, ...props }: ThemeToggleProps): import("react/jsx-runtime").JSX.Element;
+declare namespace ThemeToggle {
+    var displayName: string;
+}
+export { ThemeToggle };
 //# sourceMappingURL=theme-toggle.d.ts.map

package/dist/components/ui/theme-toggle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"theme-toggle.d.ts","sourceRoot":"","sources":["../../../src/components/ui/theme-toggle.tsx"],"names":[],"mappings":"AAaA;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iDAAiD;IACjD,OAAO,CAAC,EACJ,SAAS,GACT,aAAa,GACb,SAAS,GACT,WAAW,GACX,OAAO,GACP,MAAM,CAAC;IAEX,gCAAgC;IAChC,IAAI,CAAC,EAAE,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAAC;IAExC,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,yEAAyE;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB,qCAAqC;IACrC,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;CACpC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuFG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAmB,EACnB,IAAa,EACb,SAAS,EACT,SAA2B,EAC3B,KAAa,GACd,EAAE,gBAAgB,2CAmDlB"}
+{"version":3,"file":"theme-toggle.d.ts","sourceRoot":"","sources":["../../../src/components/ui/theme-toggle.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAShE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AA4H7D,KAAK,gBAAgB,GAAG;IACtB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;CACpC,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,MAAM,CAAC,GACrC,YAAY,CAAC,OAAO,cAAc,CAAC,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiNG;AACH,iBAAS,WAAW,CAAC,EACnB,OAAmB,EACnB,IAAa,EACb,SAAS,EACT,SAAS,EACT,KAAa,EACb,GAAG,KAAK,EACT,EAAE,gBAAgB,2CA6DlB;kBApEQ,WAAW;;;AAwEpB,OAAO,EAAE,WAAW,EAAE,CAAC"}

package/dist/components/ui/theme.d.ts

@@ -12,6 +12,10 @@
  * 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
@@ -67,43 +71,123 @@
  * }
  * ```
  *
+ * @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
- * - **Framework Agnostic**: Works with Next.js, Vite, Remix, and other React frameworks
- * - **SSR Compatible**: Handles server-side rendering correctly
- * - **System Detection**: Automatically follows OS dark/light preference
- * - **Cookie Persistence**: Maintains theme across browser sessions
- * - **Minimal Overhead**: Tiny inline script with no external dependencies
+ * - **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 system preference for reduced motion
- * - Maintains proper color contrast ratios
- * - Works with screen readers and assistive technology
- * - Follows WCAG guidelines for theme switching
+ * - 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
- * - Executes before React hydration
- * - No network requests or external dependencies
- * - Minified inline script for optimal performance
- * - Zero runtime overhead after initial execution
+ * - **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
- * - Uses dangerouslySetInnerHTML with known safe content
- * - No external script sources or eval usage
- * - Cookie reading with proper error handling
- * - Graceful fallback on script execution errors
+ * - **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 script
- * handles initial theme application, while the hook manages runtime theme changes.
+ * {@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.
+ * 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
- * @see {@link ThemeToggle} - UI component for 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 declare function Theme(): import("react/jsx-runtime").JSX.Element;