@snowcone-app/ui 0.1.43 → 0.2.0

package/src/themes/useTheme.tsx

@@ -0,0 +1,450 @@
+"use client";
+
+'use client';
+
+/**
+ * Shared Theme Hook
+ *
+ * This is the single source of truth for theme state management.
+ * All apps (next-ecommerce, docs, canvas) can use this same hook.
+ *
+ * Features:
+ * - State management for current theme
+ * - localStorage persistence
+ * - Light/dark toggle
+ * - Theme cycling
+ * - Calls applyTheme() on theme change
+ */
+
+import { useState, useEffect, useCallback, useMemo, createContext, useContext, type ReactNode } from 'react';
+import type { ThemePreset, FontPairing } from './types';
+import { presetThemes, findTheme } from './presets';
+import { applyTheme } from './apply-theme';
+
+const STORAGE_KEY = 'snowcone-theme';
+const COOKIE_NAME = 'snowcone-theme';
+
+/**
+ * Set a cookie with the theme name
+ * Uses a 1-year expiry and sameSite=lax for security
+ */
+function setThemeCookie(themeName: string): void {
+  if (typeof document === 'undefined') return;
+  const maxAge = 60 * 60 * 24 * 365; // 1 year
+  document.cookie = `${COOKIE_NAME}=${encodeURIComponent(themeName)}; path=/; max-age=${maxAge}; samesite=lax`;
+}
+
+export interface ThemeContextValue {
+  /** Current theme configuration */
+  currentTheme: ThemePreset;
+  /** Update the current theme */
+  setCurrentTheme: (theme: ThemePreset | ((prev: ThemePreset) => ThemePreset)) => void;
+  /** Current theme index in presetThemes array */
+  currentThemeIndex: number;
+  /** All available preset themes */
+  presetThemes: ThemePreset[];
+  /** Select a theme by index */
+  selectPresetTheme: (index: number, respectLightDark?: boolean) => void;
+  /** Toggle between light and dark variants of current theme */
+  toggleLightDark: () => void;
+  /** Get info about current theme's light/dark state */
+  getCurrentThemeVariant: () => { isDark: boolean; hasLightVariant: boolean; hasDarkVariant: boolean } | null;
+  /** Reset to default theme */
+  resetTheme: () => void;
+  /** Whether auto-cycling is enabled */
+  isAutoTheme: boolean;
+  /** Toggle auto-cycling mode */
+  toggleAutoTheme: () => void;
+  /** Selected font pairing (separate from theme's font) */
+  selectedFontPairing: FontPairing | null;
+  /** Set selected font pairing */
+  setSelectedFontPairing: (pairing: FontPairing | null) => void;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export interface ThemeProviderProps {
+  children: ReactNode;
+  /** Default theme to use (defaults to first preset) */
+  defaultTheme?: ThemePreset;
+  /** Storage key for localStorage persistence */
+  storageKey?: string;
+  /** Auto-apply theme on mount and changes */
+  autoApply?: boolean;
+}
+
+/**
+ * Theme Provider Component
+ *
+ * Wrap your app with this provider to enable theme functionality.
+ *
+ * @example
+ * ```tsx
+ * <ThemeProvider>
+ *   <App />
+ * </ThemeProvider>
+ * ```
+ */
+export function ThemeProvider({
+  children,
+  defaultTheme = presetThemes[0],
+  storageKey = STORAGE_KEY,
+  autoApply = true,
+}: ThemeProviderProps) {
+  const [currentTheme, setCurrentThemeState] = useState<ThemePreset>(defaultTheme);
+  const [currentThemeIndex, setCurrentThemeIndex] = useState(() => {
+    const idx = presetThemes.findIndex(t => t.name === defaultTheme.name);
+    return idx >= 0 ? idx : 0;
+  });
+  const [isAutoTheme, setIsAutoTheme] = useState(false);
+  const [selectedFontPairing, setSelectedFontPairing] = useState<FontPairing | null>(null);
+  const [isInitialized, setIsInitialized] = useState(false);
+
+  // Load saved theme from localStorage on mount
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    try {
+      const saved = localStorage.getItem(storageKey);
+      if (saved) {
+        const parsed = JSON.parse(saved);
+        const savedTheme = findTheme(parsed.name);
+        // Only update state if localStorage theme differs from defaultTheme
+        // (defaultTheme may already be set correctly from server-side cookie)
+        if (savedTheme && savedTheme.name !== defaultTheme.name) {
+          setCurrentThemeState(savedTheme);
+          const idx = presetThemes.findIndex(t => t.name === savedTheme.name);
+          if (idx >= 0) setCurrentThemeIndex(idx);
+        }
+      }
+    } catch {
+      // Ignore localStorage errors
+    }
+    setIsInitialized(true);
+  }, [storageKey, defaultTheme.name]);
+
+  // Apply theme when it changes
+  useEffect(() => {
+    if (!isInitialized || !autoApply) return;
+
+    // Apply the theme
+    applyTheme(currentTheme);
+
+    // Save to localStorage
+    try {
+      localStorage.setItem(storageKey, JSON.stringify({ name: currentTheme.name }));
+    } catch {
+      // Ignore localStorage errors
+    }
+
+    // Save to cookie for SSR
+    setThemeCookie(currentTheme.name);
+  }, [currentTheme, isInitialized, autoApply, storageKey]);
+
+  const setCurrentTheme = useCallback((themeOrUpdater: ThemePreset | ((prev: ThemePreset) => ThemePreset)) => {
+    setCurrentThemeState(prev => {
+      const newTheme = typeof themeOrUpdater === 'function' ? themeOrUpdater(prev) : themeOrUpdater;
+      const idx = presetThemes.findIndex(t => t.name === newTheme.name);
+      if (idx >= 0) setCurrentThemeIndex(idx);
+      return newTheme;
+    });
+  }, []);
+
+  const selectPresetTheme = useCallback((index: number, respectLightDark = false) => {
+    if (index < 0 || index >= presetThemes.length) return;
+
+    let targetTheme = presetThemes[index];
+
+    // If respectLightDark is true, match the current light/dark mode
+    if (respectLightDark && currentThemeIndex >= 0) {
+      const currentIsDark = presetThemes[currentThemeIndex]?.isDark || false;
+      const targetIsDark = targetTheme.isDark || false;
+
+      if (currentIsDark !== targetIsDark) {
+        const variantName = currentIsDark ? targetTheme.darkVariant : targetTheme.lightVariant;
+        if (variantName) {
+          const variantIndex = presetThemes.findIndex(t => t.name === variantName);
+          if (variantIndex >= 0) {
+            targetTheme = presetThemes[variantIndex];
+            index = variantIndex;
+          }
+        }
+      }
+    }
+
+    setCurrentThemeState(targetTheme);
+    setCurrentThemeIndex(index);
+    setIsAutoTheme(false);
+  }, [currentThemeIndex]);
+
+  const toggleLightDark = useCallback(() => {
+    const current = presetThemes[currentThemeIndex];
+    if (!current) return;
+
+    const targetName = current.isDark ? current.lightVariant : current.darkVariant;
+    if (targetName) {
+      const targetIndex = presetThemes.findIndex(t => t.name === targetName);
+      if (targetIndex >= 0) {
+        selectPresetTheme(targetIndex);
+      }
+    }
+  }, [currentThemeIndex, selectPresetTheme]);
+
+  const getCurrentThemeVariant = useCallback(() => {
+    const current = presetThemes[currentThemeIndex];
+    if (!current) return null;
+
+    return {
+      isDark: current.isDark || false,
+      hasLightVariant: !!(current.isDark && current.lightVariant),
+      hasDarkVariant: !!(!current.isDark && current.darkVariant),
+    };
+  }, [currentThemeIndex]);
+
+  const resetTheme = useCallback(() => {
+    setCurrentThemeState(defaultTheme);
+    const idx = presetThemes.findIndex(t => t.name === defaultTheme.name);
+    setCurrentThemeIndex(idx >= 0 ? idx : 0);
+    setIsAutoTheme(false);
+  }, [defaultTheme]);
+
+  const toggleAutoTheme = useCallback(() => {
+    setIsAutoTheme(prev => !prev);
+  }, []);
+
+  // Auto theme cycling effect
+  useEffect(() => {
+    if (!isAutoTheme) return;
+
+    const interval = setInterval(() => {
+      setCurrentThemeIndex(prev => {
+        const nextIndex = (prev + 1) % presetThemes.length;
+        setCurrentThemeState(presetThemes[nextIndex]);
+        return nextIndex;
+      });
+    }, 3000);
+
+    return () => clearInterval(interval);
+  }, [isAutoTheme]);
+
+  const value = useMemo<ThemeContextValue>(() => ({
+    currentTheme,
+    setCurrentTheme,
+    currentThemeIndex,
+    presetThemes,
+    selectPresetTheme,
+    toggleLightDark,
+    getCurrentThemeVariant,
+    resetTheme,
+    isAutoTheme,
+    toggleAutoTheme,
+    selectedFontPairing,
+    setSelectedFontPairing,
+  }), [
+    currentTheme,
+    setCurrentTheme,
+    currentThemeIndex,
+    selectPresetTheme,
+    toggleLightDark,
+    getCurrentThemeVariant,
+    resetTheme,
+    isAutoTheme,
+    toggleAutoTheme,
+    selectedFontPairing,
+  ]);
+
+  return (
+    <ThemeContext.Provider value={value}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+/**
+ * Hook to access theme context
+ *
+ * Must be used within a ThemeProvider.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { currentTheme, toggleLightDark } = useTheme();
+ *   return (
+ *     <button onClick={toggleLightDark}>
+ *       {currentTheme.isDark ? 'Light Mode' : 'Dark Mode'}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useTheme(): ThemeContextValue {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error('useTheme must be used within a ThemeProvider');
+  }
+  return context;
+}
+
+/**
+ * Standalone hook for theme management without context
+ *
+ * Use this when you don't need a provider (e.g., single-page apps).
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const theme = useThemeStandalone();
+ *   return <div>Current theme: {theme.currentTheme.name}</div>;
+ * }
+ * ```
+ */
+export function useThemeStandalone(options?: {
+  defaultTheme?: ThemePreset;
+  storageKey?: string;
+  autoApply?: boolean;
+}): ThemeContextValue {
+  const { defaultTheme = presetThemes[0], storageKey = STORAGE_KEY, autoApply = true } = options || {};
+
+  const [currentTheme, setCurrentThemeState] = useState<ThemePreset>(defaultTheme);
+  const [currentThemeIndex, setCurrentThemeIndex] = useState(() => {
+    const idx = presetThemes.findIndex(t => t.name === defaultTheme.name);
+    return idx >= 0 ? idx : 0;
+  });
+  const [isAutoTheme, setIsAutoTheme] = useState(false);
+  const [selectedFontPairing, setSelectedFontPairing] = useState<FontPairing | null>(null);
+  const [isInitialized, setIsInitialized] = useState(false);
+
+  // Load saved theme from localStorage on mount
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    try {
+      const saved = localStorage.getItem(storageKey);
+      if (saved) {
+        const parsed = JSON.parse(saved);
+        const savedTheme = findTheme(parsed.name);
+        // Only update state if localStorage theme differs from defaultTheme
+        if (savedTheme && savedTheme.name !== defaultTheme.name) {
+          setCurrentThemeState(savedTheme);
+          const idx = presetThemes.findIndex(t => t.name === savedTheme.name);
+          if (idx >= 0) setCurrentThemeIndex(idx);
+        }
+      }
+    } catch {
+      // Ignore localStorage errors
+    }
+    setIsInitialized(true);
+  }, [storageKey, defaultTheme.name]);
+
+  // Apply theme when it changes
+  useEffect(() => {
+    if (!isInitialized || !autoApply) return;
+    applyTheme(currentTheme);
+    try {
+      localStorage.setItem(storageKey, JSON.stringify({ name: currentTheme.name }));
+    } catch {
+      // Ignore localStorage errors
+    }
+    // Save to cookie for SSR
+    setThemeCookie(currentTheme.name);
+  }, [currentTheme, isInitialized, autoApply, storageKey]);
+
+  const setCurrentTheme = useCallback((themeOrUpdater: ThemePreset | ((prev: ThemePreset) => ThemePreset)) => {
+    setCurrentThemeState(prev => {
+      const newTheme = typeof themeOrUpdater === 'function' ? themeOrUpdater(prev) : themeOrUpdater;
+      const idx = presetThemes.findIndex(t => t.name === newTheme.name);
+      if (idx >= 0) setCurrentThemeIndex(idx);
+      return newTheme;
+    });
+  }, []);
+
+  const selectPresetTheme = useCallback((index: number, respectLightDark = false) => {
+    if (index < 0 || index >= presetThemes.length) return;
+    let targetTheme = presetThemes[index];
+    if (respectLightDark && currentThemeIndex >= 0) {
+      const currentIsDark = presetThemes[currentThemeIndex]?.isDark || false;
+      const targetIsDark = targetTheme.isDark || false;
+      if (currentIsDark !== targetIsDark) {
+        const variantName = currentIsDark ? targetTheme.darkVariant : targetTheme.lightVariant;
+        if (variantName) {
+          const variantIndex = presetThemes.findIndex(t => t.name === variantName);
+          if (variantIndex >= 0) {
+            targetTheme = presetThemes[variantIndex];
+            index = variantIndex;
+          }
+        }
+      }
+    }
+    setCurrentThemeState(targetTheme);
+    setCurrentThemeIndex(index);
+    setIsAutoTheme(false);
+  }, [currentThemeIndex]);
+
+  const toggleLightDark = useCallback(() => {
+    const current = presetThemes[currentThemeIndex];
+    if (!current) return;
+    const targetName = current.isDark ? current.lightVariant : current.darkVariant;
+    if (targetName) {
+      const targetIndex = presetThemes.findIndex(t => t.name === targetName);
+      if (targetIndex >= 0) selectPresetTheme(targetIndex);
+    }
+  }, [currentThemeIndex, selectPresetTheme]);
+
+  const getCurrentThemeVariant = useCallback(() => {
+    const current = presetThemes[currentThemeIndex];
+    if (!current) return null;
+    return {
+      isDark: current.isDark || false,
+      hasLightVariant: !!(current.isDark && current.lightVariant),
+      hasDarkVariant: !!(!current.isDark && current.darkVariant),
+    };
+  }, [currentThemeIndex]);
+
+  const resetTheme = useCallback(() => {
+    setCurrentThemeState(defaultTheme);
+    const idx = presetThemes.findIndex(t => t.name === defaultTheme.name);
+    setCurrentThemeIndex(idx >= 0 ? idx : 0);
+    setIsAutoTheme(false);
+  }, [defaultTheme]);
+
+  const toggleAutoTheme = useCallback(() => setIsAutoTheme(prev => !prev), []);
+
+  // Auto theme cycling
+  useEffect(() => {
+    if (!isAutoTheme) return;
+    const interval = setInterval(() => {
+      setCurrentThemeIndex(prev => {
+        const nextIndex = (prev + 1) % presetThemes.length;
+        setCurrentThemeState(presetThemes[nextIndex]);
+        return nextIndex;
+      });
+    }, 3000);
+    return () => clearInterval(interval);
+  }, [isAutoTheme]);
+
+  return useMemo(() => ({
+    currentTheme,
+    setCurrentTheme,
+    currentThemeIndex,
+    presetThemes,
+    selectPresetTheme,
+    toggleLightDark,
+    getCurrentThemeVariant,
+    resetTheme,
+    isAutoTheme,
+    toggleAutoTheme,
+    selectedFontPairing,
+    setSelectedFontPairing,
+  }), [
+    currentTheme,
+    setCurrentTheme,
+    currentThemeIndex,
+    selectPresetTheme,
+    toggleLightDark,
+    getCurrentThemeVariant,
+    resetTheme,
+    isAutoTheme,
+    toggleAutoTheme,
+    selectedFontPairing,
+  ]);
+}

package/src/utils/dev-warnings.ts

@@ -0,0 +1,161 @@
+/**
+ * Development-only warnings for detecting configuration issues
+ *
+ * This utility helps catch common setup problems early by checking
+ * if Tailwind styles are properly applied to components.
+ */
+
+let hasCheckedConfig = false;
+let configCheckPassed = false;
+
+/**
+ * Check if Tailwind CSS is properly configured
+ * This runs once per page load in development mode
+ */
+export function checkTailwindConfig() {
+  // Only run in development
+  if (process.env.NODE_ENV !== 'development') return true;
+
+  // Only check once
+  if (hasCheckedConfig) return configCheckPassed;
+  hasCheckedConfig = true;
+
+  try {
+    // Create a test element with Tailwind classes
+    const testElement = document.createElement('div');
+    testElement.className = 'bg-background text-foreground';
+    testElement.style.position = 'absolute';
+    testElement.style.visibility = 'hidden';
+    testElement.style.pointerEvents = 'none';
+    document.body.appendChild(testElement);
+
+    // Check if styles are applied
+    const styles = window.getComputedStyle(testElement);
+    const hasBackgroundColor = styles.backgroundColor && styles.backgroundColor !== 'rgba(0, 0, 0, 0)';
+    const hasTextColor = styles.color && styles.color !== 'rgb(0, 0, 0)';
+
+    // Clean up
+    document.body.removeChild(testElement);
+
+    if (!hasBackgroundColor || !hasTextColor) {
+      console.error(
+        '%c🚨 @snowcone-app/ui: Tailwind styles not detected!',
+        'font-size: 14px; font-weight: bold; color: #ef4444;',
+        '\n\n' +
+        '❌ Your components may look unstyled.\n\n' +
+        'Common causes:\n' +
+        '  1. Missing or incorrect @source paths in globals.css\n' +
+        '  2. Forgot to restart dev server after changing globals.css\n' +
+        '  3. Tailwind CSS not imported in globals.css\n\n' +
+        'Quick fix:\n' +
+        '  Run: npx snowcone-cli init\n\n' +
+        'Or manually check:\n' +
+        '  https://developers.snowcone.app/llm-kit/latest/theme-setup.md\n'
+      );
+      configCheckPassed = false;
+      return false;
+    }
+
+    configCheckPassed = true;
+    return true;
+
+  } catch (error) {
+    console.warn('@snowcone-app/ui: Could not verify Tailwind configuration', error);
+    configCheckPassed = false;
+    return false;
+  }
+}
+
+/**
+ * Check if a specific component has styles applied
+ * Use this in individual components to provide more specific warnings
+ */
+export function checkComponentStyles(
+  element: HTMLElement | null,
+  componentName: string
+): boolean {
+  // Only run in development
+  if (process.env.NODE_ENV !== 'development') return true;
+  if (!element) return false;
+
+  try {
+    const styles = window.getComputedStyle(element);
+
+    // Check if any Tailwind styles are applied
+    // Look for non-default values on common properties
+    const hasStyles =
+      (styles.backgroundColor && styles.backgroundColor !== 'rgba(0, 0, 0, 0)') ||
+      (styles.padding && styles.padding !== '0px') ||
+      (styles.margin && styles.margin !== '0px') ||
+      (styles.display && !['inline', 'block'].includes(styles.display));
+
+    if (!hasStyles) {
+      console.warn(
+        `%c⚠️ ${componentName}: Missing Tailwind styles`,
+        'font-size: 12px; color: #f59e0b;',
+        '\n' +
+        'Component may not render correctly.\n' +
+        'Check @source configuration in globals.css or run: npx snowcone-cli init'
+      );
+      return false;
+    }
+
+    return true;
+
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Check if required CSS variables (theme tokens) are defined
+ */
+export function checkThemeTokens(): boolean {
+  // Only run in development
+  if (process.env.NODE_ENV !== 'development') return true;
+
+  try {
+    const requiredTokens = [
+      '--color-background',
+      '--color-foreground',
+      '--color-primary',
+      '--color-card',
+    ];
+
+    const rootStyles = getComputedStyle(document.documentElement);
+    const missingTokens = requiredTokens.filter(
+      (token) => !rootStyles.getPropertyValue(token)
+    );
+
+    if (missingTokens.length > 0) {
+      console.warn(
+        '%c⚠️ @snowcone-app/ui: Missing theme tokens',
+        'font-size: 12px; color: #f59e0b;',
+        '\n' +
+        `Missing: ${missingTokens.join(', ')}\n\n` +
+        'Components may not render correctly.\n' +
+        'Add theme tokens to globals.css:\n' +
+        '  https://developers.snowcone.app/llm-kit/latest/themes.css'
+      );
+      return false;
+    }
+
+    return true;
+
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Run all configuration checks
+ * Call this once when the app initializes
+ */
+export function runConfigChecks(): boolean {
+  if (process.env.NODE_ENV !== 'development') return true;
+
+  const tailwindOk = checkTailwindConfig();
+  const themesOk = checkThemeTokens();
+
+  return tailwindOk && themesOk;
+}