@djangocfg/ui-nextjs 1.4.45

package/src/hooks/useQueryParams.ts

@@ -0,0 +1,73 @@
+/**
+ * useQueryParams Hook
+ * 
+ * Safe hook to access URL query parameters without requiring Suspense boundary.
+ * Works on client-side only, returns empty URLSearchParams during SSR/prerendering.
+ * 
+ * @example
+ * ```tsx
+ * const params = useQueryParams();
+ * const flow = params.get('flow');
+ * const hasFlow = params.has('flow');
+ * const allTags = params.getAll('tags');
+ * ```
+ */
+
+'use client';
+
+import { useState, useEffect, useRef } from 'react';
+import { usePathname } from 'next/navigation';
+
+/**
+ * Hook to safely access URL query parameters without useSearchParams()
+ * 
+ * This hook reads query parameters directly from window.location.search,
+ * avoiding the need for Suspense boundaries that useSearchParams() requires.
+ * 
+ * Automatically updates when URL changes (navigation, back/forward, etc.)
+ * Uses pathname from Next.js to detect route changes and polls for query param changes.
+ * 
+ * Returns a URLSearchParams object with get(), getAll(), has(), etc.
+ * 
+ * @returns URLSearchParams object (empty during SSR)
+ */
+export function useQueryParams(): URLSearchParams {
+  const pathname = usePathname();
+  const [queryParams, setQueryParams] = useState<URLSearchParams>(() => {
+    if (typeof window === 'undefined') {
+      return new URLSearchParams();
+    }
+    return new URLSearchParams(window.location.search);
+  });
+  const lastSearchRef = useRef<string>('');
+
+  useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const updateQueryParams = () => {
+      const currentSearch = window.location.search;
+      if (currentSearch !== lastSearchRef.current) {
+        lastSearchRef.current = currentSearch;
+        setQueryParams(new URLSearchParams(currentSearch));
+      }
+    };
+
+    // Update when pathname changes (Next.js navigation)
+    updateQueryParams();
+
+    // Listen to popstate (back/forward navigation)
+    window.addEventListener('popstate', updateQueryParams);
+
+    // Poll for query param changes (for router.push with same pathname)
+    // This handles cases where Next.js router.push updates query params without changing pathname
+    const intervalId = setInterval(updateQueryParams, 100);
+
+    return () => {
+      window.removeEventListener('popstate', updateQueryParams);
+      clearInterval(intervalId);
+    };
+  }, [pathname]);
+
+  return queryParams;
+}
+

package/src/hooks/useSessionStorage.ts

@@ -0,0 +1,188 @@
+'use client';
+
+import { useState } from 'react';
+
+/**
+ * Simple sessionStorage hook with better error handling
+ * @param key - Storage key
+ * @param initialValue - Default value if key doesn't exist
+ * @returns [value, setValue, removeValue] - Current value, setter function, and remove function
+ */
+export function useSessionStorage<T>(key: string, initialValue: T) {
+  // Get initial value from sessionStorage or use provided initialValue
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    if (typeof window === 'undefined') {
+      return initialValue;
+    }
+
+    try {
+      const item = window.sessionStorage.getItem(key);
+      return item ? JSON.parse(item) : initialValue;
+    } catch (error) {
+      console.error(`Error reading sessionStorage key "${key}":`, error);
+      return initialValue;
+    }
+  });
+
+  // Check data size and limit
+  const checkDataSize = (data: any): boolean => {
+    try {
+      const jsonString = JSON.stringify(data);
+      const sizeInBytes = new Blob([jsonString]).size;
+      const sizeInKB = sizeInBytes / 1024;
+      
+      // Limit to 1MB per item
+      if (sizeInKB > 1024) {
+        console.warn(`Data size (${sizeInKB.toFixed(2)}KB) exceeds 1MB limit for key "${key}"`);
+        return false;
+      }
+      
+      return true;
+    } catch (error) {
+      console.error(`Error checking data size for key "${key}":`, error);
+      return false;
+    }
+  };
+
+  // Clear old data when sessionStorage is full
+  const clearOldData = () => {
+    try {
+      const keys = Object.keys(sessionStorage).filter(key => key && typeof key === 'string');
+      // Remove oldest items if we have more than 50 items
+      if (keys.length > 50) {
+        const itemsToRemove = Math.ceil(keys.length * 0.2);
+        for (let i = 0; i < itemsToRemove; i++) {
+          try {
+            const key = keys[i];
+            if (key) {
+              sessionStorage.removeItem(key);
+              sessionStorage.removeItem(`${key}_timestamp`);
+            }
+          } catch {
+            // Ignore errors when removing items
+          }
+        }
+      }
+    } catch (error) {
+      console.error('Error clearing old sessionStorage data:', error);
+    }
+  };
+
+  // Force clear all data if quota is exceeded
+  const forceClearAll = () => {
+    try {
+      const keys = Object.keys(sessionStorage);
+      for (const key of keys) {
+        try {
+          sessionStorage.removeItem(key);
+        } catch {
+          // Ignore errors when removing items
+        }
+      }
+    } catch (error) {
+      console.error('Error force clearing sessionStorage:', error);
+    }
+  };
+
+  // Update sessionStorage when value changes
+  const setValue = (value: T | ((val: T) => T)) => {
+    try {
+      const valueToStore = value instanceof Function ? value(storedValue) : value;
+      
+      // Check data size before attempting to save
+      if (!checkDataSize(valueToStore)) {
+        console.warn(`Data size too large for key "${key}", removing key`);
+        // Remove the key if data is too large
+        try {
+          window.sessionStorage.removeItem(key);
+          window.sessionStorage.removeItem(`${key}_timestamp`);
+        } catch {
+          // Ignore errors when removing
+        }
+        // Still update the state
+        setStoredValue(valueToStore);
+        return;
+      }
+      
+      setStoredValue(valueToStore);
+
+      if (typeof window !== 'undefined') {
+        // Try to set the value
+        try {
+          window.sessionStorage.setItem(key, JSON.stringify(valueToStore));
+          // Add timestamp for cleanup
+          window.sessionStorage.setItem(`${key}_timestamp`, Date.now().toString());
+        } catch (storageError: any) {
+          // If quota exceeded, clear old data and try again
+          if (storageError.name === 'QuotaExceededError' || 
+              storageError.code === 22 || 
+              storageError.message?.includes('quota')) {
+            console.warn('sessionStorage quota exceeded, clearing old data...');
+            clearOldData();
+            
+            // Try again after clearing
+            try {
+              window.sessionStorage.setItem(key, JSON.stringify(valueToStore));
+              window.sessionStorage.setItem(`${key}_timestamp`, Date.now().toString());
+            } catch (retryError) {
+              console.error(`Failed to set sessionStorage key "${key}" after clearing old data:`, retryError);
+              // If still fails, force clear all and try one more time
+              try {
+                forceClearAll();
+                window.sessionStorage.setItem(key, JSON.stringify(valueToStore));
+                window.sessionStorage.setItem(`${key}_timestamp`, Date.now().toString());
+              } catch (finalError) {
+                console.error(`Failed to set sessionStorage key "${key}" after force clearing:`, finalError);
+                // If still fails, just update the state without sessionStorage
+                setStoredValue(valueToStore);
+              }
+            }
+          } else {
+            throw storageError;
+          }
+        }
+      }
+    } catch (error) {
+      console.error(`Error setting sessionStorage key "${key}":`, error);
+      // Still update the state even if sessionStorage fails
+      const valueToStore = value instanceof Function ? value(storedValue) : value;
+      setStoredValue(valueToStore);
+    }
+  };
+
+  // Remove value from sessionStorage
+  const removeValue = () => {
+    try {
+      setStoredValue(initialValue);
+      if (typeof window !== 'undefined') {
+        try {
+          window.sessionStorage.removeItem(key);
+          window.sessionStorage.removeItem(`${key}_timestamp`);
+        } catch (removeError: any) {
+          // If removal fails due to quota, try to clear some data first
+          if (removeError.name === 'QuotaExceededError' || 
+              removeError.code === 22 || 
+              removeError.message?.includes('quota')) {
+            console.warn('sessionStorage quota exceeded during removal, clearing old data...');
+            clearOldData();
+            
+            try {
+              window.sessionStorage.removeItem(key);
+              window.sessionStorage.removeItem(`${key}_timestamp`);
+            } catch (retryError) {
+              console.error(`Failed to remove sessionStorage key "${key}" after clearing:`, retryError);
+              // If still fails, force clear all
+              forceClearAll();
+            }
+          } else {
+            throw removeError;
+          }
+        }
+      }
+    } catch (error) {
+      console.error(`Error removing sessionStorage key "${key}":`, error);
+    }
+  };
+
+  return [storedValue, setValue, removeValue] as const;
+}

package/src/hooks/useTheme.ts

@@ -0,0 +1,57 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+export type Theme = 'light' | 'dark';
+
+/**
+ * Hook to detect and track the current theme
+ * Supports both manual theme switching and system preference
+ */
+export const useTheme = (): Theme => {
+  const [theme, setTheme] = useState<Theme>('light');
+  
+  useEffect(() => {
+    const checkTheme = (): Theme => {
+      // Check if dark class is applied to html element (manual theme)
+      if (document.documentElement.classList.contains('dark')) {
+        return 'dark';
+      }
+      
+      // Check system preference
+      if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
+        return 'dark';
+      }
+      
+      return 'light';
+    };
+    
+    // Set initial theme
+    setTheme(checkTheme());
+    
+    // Listen for manual theme changes (class changes on html element)
+    const observer = new MutationObserver(() => {
+      setTheme(checkTheme());
+    });
+    
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ['class']
+    });
+    
+    // Listen for system theme changes
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    const handleMediaChange = () => {
+      setTheme(checkTheme());
+    };
+    
+    mediaQuery.addEventListener('change', handleMediaChange);
+    
+    return () => {
+      observer.disconnect();
+      mediaQuery.removeEventListener('change', handleMediaChange);
+    };
+  }, []);
+  
+  return theme;
+};

package/src/index.ts

@@ -0,0 +1,24 @@
+// ============================================================================
+// @djangocfg/ui - Main Export File
+// ============================================================================
+
+// Re-export everything from components
+export * from './components';
+
+// Re-export hooks
+export * from './hooks';
+
+// Re-export blocks
+export * from './blocks';
+
+// Re-export animations
+export * from './animations';
+
+// Re-export lib utilities
+export * from './lib';
+
+// Re-export tools
+export * from './tools';
+
+// Re-export theme
+export * from './theme';

package/src/lib/index.ts

@@ -0,0 +1,2 @@
+// Re-export from ui-core
+export * from '@djangocfg/ui-core/lib';

package/src/styles/index.css

@@ -0,0 +1,2 @@
+/* Re-export styles from ui-core */
+@import '@djangocfg/ui-core/styles';

package/src/theme/ForceTheme.tsx

@@ -0,0 +1,115 @@
+/**
+ * ForceTheme - Force a specific theme for a section
+ *
+ * Wraps content to override the global theme setting.
+ * Works by adding both the theme class and inline CSS variables
+ * to ensure proper theme application regardless of parent context.
+ */
+
+'use client';
+
+import React, { ReactNode } from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+
+interface ForceThemeProps {
+  theme: 'light' | 'dark';
+  children: ReactNode;
+  className?: string;
+}
+
+// Dark theme CSS variables
+const darkThemeVars = {
+  // Base HSL values
+  '--background': '0 0% 4%',
+  '--foreground': '0 0% 98%',
+  '--card': '0 0% 8%',
+  '--card-foreground': '0 0% 98%',
+  '--popover': '0 0% 12%',
+  '--popover-foreground': '0 0% 98%',
+  '--primary': '217 91% 60%',
+  '--primary-foreground': '0 0% 100%',
+  '--secondary': '0 0% 98%',
+  '--secondary-foreground': '0 0% 9%',
+  '--muted': '0 0% 10%',
+  '--muted-foreground': '0 0% 60%',
+  '--accent': '0 0% 15%',
+  '--accent-foreground': '0 0% 98%',
+  '--destructive': '0 84% 60%',
+  '--destructive-foreground': '0 0% 98%',
+  '--border': '0 0% 15%',
+  '--input': '0 0% 15%',
+  '--ring': '217 91% 60%',
+  // Tailwind color tokens (used by bg-*, text-*, etc)
+  '--color-background': 'hsl(0 0% 4%)',
+  '--color-foreground': 'hsl(0 0% 98%)',
+  '--color-card': 'hsl(0 0% 8%)',
+  '--color-card-foreground': 'hsl(0 0% 98%)',
+  '--color-primary': 'hsl(217 91% 60%)',
+  '--color-primary-foreground': 'hsl(0 0% 100%)',
+  '--color-secondary': 'hsl(0 0% 98%)',
+  '--color-secondary-foreground': 'hsl(0 0% 9%)',
+  '--color-muted': 'hsl(0 0% 10%)',
+  '--color-muted-foreground': 'hsl(0 0% 60%)',
+  '--color-accent': 'hsl(0 0% 15%)',
+  '--color-accent-foreground': 'hsl(0 0% 98%)',
+  '--color-destructive': 'hsl(0 84% 60%)',
+  '--color-destructive-foreground': 'hsl(0 0% 98%)',
+  '--color-border': 'hsl(0 0% 15%)',
+  '--color-input': 'hsl(0 0% 15%)',
+  '--color-ring': 'hsl(217 91% 60%)',
+} as React.CSSProperties;
+
+// Light theme CSS variables
+const lightThemeVars = {
+  // Base HSL values
+  '--background': '0 0% 96%',
+  '--foreground': '0 0% 9%',
+  '--card': '0 0% 100%',
+  '--card-foreground': '0 0% 9%',
+  '--popover': '0 0% 100%',
+  '--popover-foreground': '0 0% 9%',
+  '--primary': '217 91% 60%',
+  '--primary-foreground': '0 0% 100%',
+  '--secondary': '0 0% 9%',
+  '--secondary-foreground': '0 0% 98%',
+  '--muted': '0 0% 96%',
+  '--muted-foreground': '0 0% 40%',
+  '--accent': '0 0% 92%',
+  '--accent-foreground': '0 0% 9%',
+  '--destructive': '0 84% 60%',
+  '--destructive-foreground': '0 0% 98%',
+  '--border': '0 0% 90%',
+  '--input': '0 0% 90%',
+  '--ring': '217 91% 60%',
+  // Tailwind color tokens (used by bg-*, text-*, etc)
+  '--color-background': 'hsl(0 0% 96%)',
+  '--color-foreground': 'hsl(0 0% 9%)',
+  '--color-card': 'hsl(0 0% 100%)',
+  '--color-card-foreground': 'hsl(0 0% 9%)',
+  '--color-primary': 'hsl(217 91% 60%)',
+  '--color-primary-foreground': 'hsl(0 0% 100%)',
+  '--color-secondary': 'hsl(0 0% 9%)',
+  '--color-secondary-foreground': 'hsl(0 0% 98%)',
+  '--color-muted': 'hsl(0 0% 96%)',
+  '--color-muted-foreground': 'hsl(0 0% 40%)',
+  '--color-accent': 'hsl(0 0% 92%)',
+  '--color-accent-foreground': 'hsl(0 0% 9%)',
+  '--color-destructive': 'hsl(0 84% 60%)',
+  '--color-destructive-foreground': 'hsl(0 0% 98%)',
+  '--color-border': 'hsl(0 0% 90%)',
+  '--color-input': 'hsl(0 0% 90%)',
+  '--color-ring': 'hsl(217 91% 60%)',
+} as React.CSSProperties;
+
+export function ForceTheme({ theme, children, className }: ForceThemeProps) {
+  const themeVars = theme === 'dark' ? darkThemeVars : lightThemeVars;
+
+  return (
+    <div
+      className={cn(theme, className)}
+      style={themeVars}
+    >
+      {children}
+    </div>
+  );
+}

package/src/theme/ThemeProvider.tsx

@@ -0,0 +1,82 @@
+/**
+ * ThemeProvider - Universal theme management
+ *
+ * Provides theme context for the entire application with localStorage persistence.
+ */
+
+'use client';
+
+import React, { createContext, useContext, useEffect, ReactNode } from 'react';
+import { useLocalStorage } from '../hooks/useLocalStorage';
+
+// ─────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────
+
+type Theme = 'light' | 'dark';
+
+interface ThemeContextValue {
+  theme: Theme;
+  setTheme: (theme: Theme) => void;
+  toggleTheme: () => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Create Context
+// ─────────────────────────────────────────────────────────────────────────
+
+const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
+
+// ─────────────────────────────────────────────────────────────────────────
+// Provider Component
+// ─────────────────────────────────────────────────────────────────────────
+
+interface ThemeProviderProps {
+  children: ReactNode;
+  defaultTheme?: Theme;
+  storageKey?: string;
+}
+
+export function ThemeProvider({
+  children,
+  defaultTheme = 'light',
+  storageKey = 'theme'
+}: ThemeProviderProps) {
+  const [theme, setTheme] = useLocalStorage<Theme>(storageKey, defaultTheme);
+
+  useEffect(() => {
+    const root = window.document.documentElement;
+    root.classList.remove('light', 'dark');
+    root.classList.add(theme);
+  }, [theme]);
+
+  const toggleTheme = () => {
+    setTheme(theme === 'light' ? 'dark' : 'light');
+  };
+
+  const value: ThemeContextValue = {
+    theme,
+    setTheme,
+    toggleTheme,
+  };
+
+  return (
+    <ThemeContext.Provider value={value}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Custom Hook
+// ─────────────────────────────────────────────────────────────────────────
+
+export function useThemeContext(): ThemeContextValue {
+  const context = useContext(ThemeContext);
+
+  if (context === undefined) {
+    throw new Error('useThemeContext must be used within ThemeProvider');
+  }
+
+  return context;
+}

package/src/theme/ThemeToggle.tsx

@@ -0,0 +1,52 @@
+/**
+ * ThemeToggle - Theme switcher component
+ *
+ * Switches between light and dark themes by toggling the 'dark' class on the html element.
+ * Uses localStorage to persist the user's theme preference.
+ *
+ * @example
+ * ```tsx
+ * import { ThemeToggle } from '@djangocfg/ui-nextjs';
+ *
+ * <ThemeToggle />
+ * ```
+ */
+
+'use client';
+
+import { useEffect, useState } from 'react';
+import { Moon, Sun } from 'lucide-react';
+import { Button } from '@djangocfg/ui-core/components';
+import { useThemeContext } from './ThemeProvider';
+
+export function ThemeToggle() {
+  const { theme, toggleTheme } = useThemeContext();
+  const [isMounted, setIsMounted] = useState(false);
+
+  // Prevent hydration mismatch by only rendering after mount
+  useEffect(() => {
+    setIsMounted(true);
+  }, []);
+
+  // Don't render anything during SSR
+  if (!isMounted) {
+    return null;
+  }
+
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      onClick={toggleTheme}
+      className="h-9 w-9"
+      title={`Switch to ${theme === 'light' ? 'dark' : 'light'} theme`}
+    >
+      {theme === 'light' ? (
+        <Sun className="h-4 w-4" />
+      ) : (
+        <Moon className="h-4 w-4" />
+      )}
+      <span className="sr-only">Toggle theme</span>
+    </Button>
+  );
+}

package/src/theme/index.ts

@@ -0,0 +1,3 @@
+export { ThemeProvider, useThemeContext } from './ThemeProvider';
+export { ThemeToggle } from './ThemeToggle';
+export { ForceTheme } from './ForceTheme';