@neynar/ui 0.1.1

package/src/hooks/use-mobile.ts

@@ -0,0 +1,91 @@
+import * as React from "react"
+
+const MOBILE_BREAKPOINT = 768
+
+/**
+ * Hook for detecting mobile viewport width based on Tailwind CSS breakpoints
+ * 
+ * A React hook that monitors viewport width and returns true when the width
+ * is less than 768px (Tailwind's `md` breakpoint). This hook provides a
+ * consistent way to conditionally render mobile and desktop layouts, following
+ * the same responsive patterns used throughout the shadcn/ui ecosystem.
+ * 
+ * The hook uses `window.matchMedia` for efficient viewport monitoring and
+ * properly handles server-side rendering by returning `false` initially,
+ * then updating on the client side.
+ * 
+ * @returns `true` if viewport width is less than 768px, `false` otherwise
+ * 
+ * @example
+ * Basic responsive layout switching
+ * ```tsx
+ * function ResponsiveComponent() {
+ *   const isMobile = useIsMobile();
+ *   
+ *   return (
+ *     <div>
+ *       {isMobile ? (
+ *         <MobileLayout />
+ *       ) : (
+ *         <DesktopLayout />
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ * 
+ * @example
+ * Conditional navigation rendering
+ * ```tsx
+ * function Navigation() {
+ *   const isMobile = useIsMobile();
+ *   
+ *   if (isMobile) {
+ *     return <Sheet><MobileNavContent /></Sheet>;
+ *   }
+ *   
+ *   return <NavigationMenu><DesktopNavContent /></NavigationMenu>;
+ * }
+ * ```
+ * 
+ * @example
+ * Responsive component behavior within forms
+ * ```tsx
+ * function SearchDialog() {
+ *   const isMobile = useIsMobile();
+ *   
+ *   if (isMobile) {
+ *     return <Drawer><SearchForm /></Drawer>;
+ *   }
+ *   
+ *   return <Dialog><SearchForm /></Dialog>;
+ * }
+ * ```
+ * 
+ * @remarks
+ * - Uses the standard 768px breakpoint matching Tailwind's `md` breakpoint
+ * - Similar pattern to `isMobile` property in shadcn/ui's `useSidebar` hook
+ * - Handles viewport resize events automatically
+ * - SSR-safe implementation prevents hydration mismatches
+ * - Respects user's browser zoom settings
+ * 
+ * @see {@link https://tailwindcss.com/docs/responsive-design} Tailwind CSS responsive design
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/matchMedia} MDN matchMedia documentation
+ * 
+ * @since 1.0.0
+ */
+export function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState<boolean | undefined>(undefined)
+
+  React.useEffect(() => {
+    const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`)
+    const onChange = () => {
+      setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    }
+    mql.addEventListener("change", onChange)
+    setIsMobile(window.innerWidth < MOBILE_BREAKPOINT)
+    return () => mql.removeEventListener("change", onChange)
+  }, [])
+
+  return !!isMobile
+}

package/src/hooks/use-theme.ts

@@ -0,0 +1,319 @@
+"use client"
+
+import { useEffect, useState } from "react"
+
+/**
+ * Theme preference options for the theme system
+ * 
+ * Controls how the application determines the active theme:
+ * - `"system"` - Automatically follows the user's OS preference
+ * - `"light"` - Forces light theme regardless of system preference
+ * - `"dark"` - Forces dark theme regardless of system preference
+ * 
+ * @example
+ * ```tsx
+ * const { preference, setPreference } = useTheme();
+ * 
+ * // Switch to dark mode
+ * setPreference("dark");
+ * 
+ * // Follow system preference
+ * setPreference("system");
+ * ```
+ * 
+ * @since 1.0.0
+ */
+export type ThemePreference = "system" | "light" | "dark"
+
+/**
+ * Internal theme state structure stored in cookies
+ * 
+ * Maintains both the user's preference and the actual mode value
+ * to handle system theme changes efficiently.
+ * 
+ * @internal
+ */
+type ThemeState = {
+  /** User's selected theme preference */
+  preference: ThemePreference
+  /** Actual mode applied to the DOM */
+  mode: "light" | "dark"
+}
+
+/**
+ * Cookie configuration for theme persistence
+ * 
+ * Uses secure defaults for cross-site compatibility and long-term storage.
+ * 
+ * @internal
+ */
+const COOKIE_NAME = "theme"
+const COOKIE_OPTIONS = {
+  path: "/",
+  maxAge: 60 * 60 * 24 * 365, // 1 year
+  sameSite: "lax" as const,
+}
+
+/**
+ * Retrieves the stored theme preference from browser cookies
+ * 
+ * Safely parses the cookie value and handles malformed data gracefully.
+ * Returns null if no valid theme data is found or if running server-side.
+ * 
+ * @returns The stored theme state or null if unavailable
+ * @internal
+ */
+function getThemeFromCookie(): ThemeState | null {
+  if (typeof document === "undefined") return null
+  const match = document.cookie.match(new RegExp(`(?:^|; )${COOKIE_NAME}=([^;]*)`))
+  if (!match) return null
+
+  try {
+    const decoded = decodeURIComponent(match[1] || "")
+    return JSON.parse(decoded)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Persists the current theme state to browser cookies
+ * 
+ * Stores the complete theme state as a JSON string with appropriate
+ * cookie settings for security and longevity. Safe for server-side rendering.
+ * 
+ * @param state - The theme state to persist
+ * @internal
+ */
+function setThemeCookie(state: ThemeState) {
+  if (typeof document === "undefined") return
+
+  const value = JSON.stringify(state)
+  let cookieString = `${COOKIE_NAME}=${encodeURIComponent(value)}`
+
+  cookieString += `; path=${COOKIE_OPTIONS.path}`
+  cookieString += `; max-age=${COOKIE_OPTIONS.maxAge}`
+  cookieString += `; samesite=${COOKIE_OPTIONS.sameSite}`
+
+  document.cookie = cookieString
+}
+
+/**
+ * Detects the user's system theme preference
+ * 
+ * Uses the CSS media query `prefers-color-scheme` to determine if the user
+ * has configured their OS to prefer dark or light themes. Falls back to
+ * light theme for server-side rendering or unsupported browsers.
+ * 
+ * @returns The system's preferred theme
+ * @internal
+ */
+function getSystemTheme(): "light" | "dark" {
+  if (typeof window === "undefined") return "light"
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"
+}
+
+/**
+ * Applies the specified theme to the document
+ * 
+ * Updates the document's class list and color-scheme CSS property to reflect
+ * the chosen theme. This triggers CSS-based theme switching throughout the
+ * application and ensures native elements respect the theme choice.
+ * 
+ * @param theme - The theme to apply ("light" or "dark")
+ * @internal
+ */
+function applyTheme(theme: "light" | "dark") {
+  if (typeof document === "undefined") return
+  
+  // For light theme, remove dark class (light is default)
+  // For dark theme, add dark class
+  if (theme === "dark") {
+    document.documentElement.classList.add("dark")
+  } else {
+    document.documentElement.classList.remove("dark")
+  }
+  
+  // Set color-scheme for native elements
+  document.documentElement.style.colorScheme = theme
+}
+
+/**
+ * Hook for managing application theme with automatic system preference detection
+ * 
+ * A complete theme management solution that handles persistence, system preference
+ * detection, and DOM manipulation without requiring any context providers. Designed
+ * for applications that need simple light/dark mode switching with optional system
+ * preference following.
+ * 
+ * This hook works in conjunction with the {@link Theme} component to provide a complete
+ * theming solution with FOUC prevention and perfect synchronization across multiple
+ * instances.
+ * 
+ * Features:
+ * - **Perfect synchronization**: Multiple hook instances stay in sync via custom events
+ * - **Automatic persistence**: Theme preference saved to cookies across sessions
+ * - **System preference detection**: Automatically follows OS dark/light mode when set to "system"
+ * - **Live system updates**: Responds to system theme changes in real-time
+ * - **SSR compatible**: Works safely during server-side rendering
+ * - **Type safe**: Full TypeScript support with proper type definitions
+ * - **No provider required**: Self-contained hook that works out of the box
+ * 
+ * @example Basic theme switching
+ * ```tsx
+ * function ThemeToggle() {
+ *   const { preference, mode, setPreference } = useTheme();
+ *   
+ *   const toggleTheme = () => {
+ *     setPreference(mode === "dark" ? "light" : "dark");
+ *   };
+ *   
+ *   return (
+ *     <button onClick={toggleTheme}>
+ *       Switch to {mode === "dark" ? "light" : "dark"} mode
+ *     </button>
+ *   );
+ * }
+ * ```
+ * 
+ * @example Theme selector dropdown
+ * ```tsx
+ * function ThemeSelector() {
+ *   const { preference, setPreference } = useTheme();
+ *   
+ *   return (
+ *     <select value={preference} onChange={(e) => setPreference(e.target.value as ThemePreference)}>
+ *       <option value="system">Follow system</option>
+ *       <option value="light">Light mode</option>
+ *       <option value="dark">Dark mode</option>
+ *     </select>
+ *   );
+ * }
+ * ```
+ * 
+ * @example Multiple synchronized toggles
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <>
+ *       <Header>
+ *         <ThemeToggle />
+ *       </Header>
+ *       <Sidebar>
+ *         <ThemeToggle />
+ *       </Sidebar>
+ *     </>
+ *   );
+ * }
+ * ```
+ * 
+ * @example Conditional rendering based on theme
+ * ```tsx
+ * function ThemedIcon() {
+ *   const { mode } = useTheme();
+ *   
+ *   return mode === "dark" ? <MoonIcon /> : <SunIcon />;
+ * }
+ * ```
+ * 
+ * @returns Object containing current theme state and setter function
+ * @returns returns.preference - The user's selected theme preference
+ * @returns returns.mode - The actual theme currently applied (always "light" or "dark")
+ * @returns returns.setPreference - Function to change the theme preference
+ * 
+ * @remarks
+ * **Synchronization Architecture:**
+ * - All theme changes are broadcasted via custom 'theme-change' events
+ * - Single setState per change across ALL hook instances (no duplicates)
+ * - Event-driven updates ensure perfect synchronization
+ * - Cookie serves as the single source of truth for persistence
+ * 
+ * **Implementation Details:**
+ * - Theme state is automatically persisted to cookies with 1-year expiration
+ * - System preference changes are detected via `matchMedia` API
+ * - DOM updates are applied immediately when theme changes
+ * - Hook is safe to use during SSR (falls back to light theme)
+ * - Custom events handle cross-instance synchronization
+ * 
+ * **Performance:**
+ * - Single setState per theme change (no duplicate updates)
+ * - Efficient event-driven architecture
+ * - No context overhead: direct hook usage without providers
+ * - Automatic cleanup: removes event listeners on component unmount
+ * 
+ * **Browser Support:**
+ * - Modern browsers with `matchMedia` support for system detection
+ * - CustomEvent support for synchronization (IE11+ with polyfill)
+ * - Graceful degradation for older browsers (defaults to light theme)
+ * - Cookie support required for persistence across sessions
+ * 
+ * @see {@link ThemePreference} - Available theme preference options
+ * @see {@link Theme} - Component for FOUC prevention
+ * @see {@link ThemeToggle} - UI component for theme switching
+ * @since 1.0.0
+ */
+export function useTheme() {
+  // Initialize state from cookie or default to system
+  const [state, setState] = useState<ThemeState>(() => {
+    const saved = getThemeFromCookie()
+    if (saved) return saved
+    
+    const mode = getSystemTheme()
+    return { preference: "system", mode }
+  })
+
+  // Set theme preference - dispatch event, let event handler update state
+  const setPreference = (newPreference: ThemePreference) => {
+    const mode = newPreference === "system" ? getSystemTheme() : newPreference
+    const newState = { preference: newPreference, mode }
+    
+    // Update cookie and DOM immediately
+    setThemeCookie(newState)
+    applyTheme(mode)
+    
+    // Broadcast change - ALL instances (including this one) will update state from this event
+    window.dispatchEvent(new CustomEvent('theme-change', { 
+      detail: newState 
+    }))
+  }
+
+  // Single event handler for ALL state updates (including from this instance)
+  useEffect(() => {
+    const handleThemeChange = (event: CustomEvent) => {
+      setState(event.detail)  // Single setState for all instances
+    }
+    
+    window.addEventListener('theme-change', handleThemeChange as EventListener)
+    return () => window.removeEventListener('theme-change', handleThemeChange as EventListener)
+  }, [])
+
+  // Listen for system theme changes when in system mode
+  useEffect(() => {
+    if (state.preference !== "system") return
+
+    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)")
+    const handleChange = () => {
+      const mode = getSystemTheme()
+      const newState = { preference: state.preference, mode }
+      
+      // Same pattern: update cookie/DOM, then broadcast
+      setThemeCookie(newState)
+      applyTheme(mode)
+      window.dispatchEvent(new CustomEvent('theme-change', { detail: newState }))
+    }
+
+    mediaQuery.addEventListener("change", handleChange)
+    return () => mediaQuery.removeEventListener("change", handleChange)
+  }, [state.preference])
+
+  // Apply theme on mount (only for initial hydration)
+  useEffect(() => {
+    applyTheme(state.mode)
+  }, [state.mode])
+
+  return {
+    preference: state.preference,
+    mode: state.mode,
+    setPreference,
+  }
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+// Form & Input Components
+export * from "./components/ui/button";
+export * from "./components/ui/text-field";
+export * from "./components/ui/select";
+export * from "./components/ui/combobox";
+export * from "./components/ui/input";
+export * from "./components/ui/textarea";
+export * from "./components/ui/checkbox";
+export * from "./components/ui/switch";
+export * from "./components/ui/radio-group";
+export * from "./components/ui/date-picker";
+export * from "./components/ui/calendar";
+export * from "./components/ui/label";
+
+// Layout & Structure
+export * from "./components/ui/container";
+export * from "./components/ui/stack";
+export * from "./components/ui/card";
+export * from "./components/ui/separator";
+export * from "./components/ui/aspect-ratio";
+export * from "./components/ui/accordion";
+export * from "./components/ui/collapsible";
+export * from "./components/ui/resizable";
+export * from "./components/ui/scroll-area";
+
+// Navigation & Menus
+export * from "./components/ui/navigation-menu";
+export * from "./components/ui/tabs";
+export * from "./components/ui/breadcrumb";
+export * from "./components/ui/pagination";
+export * from "./components/ui/sidebar";
+export * from "./components/ui/dropdown-menu";
+export * from "./components/ui/context-menu";
+export * from "./components/ui/menubar";
+
+// Overlays & Dialogs
+export * from "./components/ui/dialog";
+export * from "./components/ui/alert-dialog";
+export * from "./components/ui/popover";
+export * from "./components/ui/tooltip";
+export * from "./components/ui/sheet";
+export * from "./components/ui/hover-card";
+export * from "./components/ui/drawer";
+
+// Typography
+export * from "./components/ui/typography";
+
+// Data Display
+export * from "./components/ui/table";
+export * from "./components/ui/badge";
+export * from "./components/ui/avatar";
+export * from "./components/ui/alert";
+export * from "./components/ui/progress";
+export * from "./components/ui/skeleton";
+export * from "./components/ui/empty-state";
+export * from "./components/ui/sonner";
+
+// Interactive Controls
+export * from "./components/ui/toggle";
+export * from "./components/ui/toggle-group";
+export * from "./components/ui/slider";
+export * from "./components/ui/command";
+
+// Charts & Visualization
+export * from "./components/ui/chart";
+export * from "./components/ui/carousel";
+
+// Theme & Utilities
+export * from "./components/ui/theme";
+export * from "./components/ui/theme-toggle";
+
+// Utilities
+export * from "./lib/utils";
+
+// Hooks
+export * from "./hooks/use-mobile";
+export * from "./hooks/use-theme";

package/src/lib/utils.ts

@@ -0,0 +1,57 @@
+import { clsx, type ClassValue } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+
+/**
+ * Custom tailwind-merge instance with support for custom classes
+ */
+const twMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      'font-size': ['text-microcopy'],
+    },
+  },
+});
+
+/**
+ * cn - Combines class names with Tailwind CSS conflict resolution
+ * 
+ * This utility function combines multiple class names into a single string,
+ * automatically resolving Tailwind CSS class conflicts. It uses clsx for
+ * conditional class handling and tailwind-merge to ensure later classes
+ * override earlier ones when they conflict.
+ * 
+ * @param inputs - Class names to combine. Can be strings, objects, arrays,
+ *                 undefined, null, or boolean values
+ * @returns A single string of combined and merged class names
+ * 
+ * @example
+ * ```tsx
+ * // Basic usage
+ * cn("px-2 py-1", "bg-blue-500", "text-white")
+ * // Returns: "px-2 py-1 bg-blue-500 text-white"
+ * ```
+ * 
+ * @example
+ * ```tsx
+ * // With conditional classes
+ * cn(
+ *   "base-class",
+ *   isActive && "active-class",
+ *   isDisabled && "disabled-class"
+ * )
+ * ```
+ * 
+ * @example
+ * ```tsx
+ * // Overriding Tailwind classes
+ * cn("px-4", "px-2") // Returns: "px-2" (later class wins)
+ * cn("text-red-500", "text-blue-500") // Returns: "text-blue-500"
+ * ```
+ * 
+ * @see {@link https://github.com/lukeed/clsx} - clsx documentation
+ * @see {@link https://github.com/dcastil/tailwind-merge} - tailwind-merge documentation
+ * @since 1.0.0
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}