@djangocfg/ui-nextjs 1.4.45

package/src/components/sonner.tsx

@@ -0,0 +1,31 @@
+"use client"
+
+import { useTheme } from "next-themes"
+import { Toaster as Sonner } from "sonner"
+
+type ToasterProps = React.ComponentProps<typeof Sonner>
+
+const Toaster = ({ ...props }: ToasterProps) => {
+  const { theme = "system" } = useTheme()
+
+  return (
+    <Sonner
+      theme={theme as ToasterProps["theme"]}
+      className="toaster group"
+      toastOptions={{
+        classNames: {
+          toast:
+            "group toast group-[.toaster]:bg-background group-[.toaster]:text-foreground group-[.toaster]:border-border group-[.toaster]:shadow-lg",
+          description: "group-[.toast]:text-muted-foreground",
+          actionButton:
+            "group-[.toast]:bg-primary group-[.toast]:text-primary-foreground",
+          cancelButton:
+            "group-[.toast]:bg-muted group-[.toast]:text-muted-foreground",
+        },
+      }}
+      {...props}
+    />
+  )
+}
+
+export { Toaster }

package/src/components/ssr-pagination.tsx

@@ -0,0 +1,237 @@
+'use client';
+
+import React from 'react';
+import { usePathname } from 'next/navigation';
+import Link from 'next/link';
+import { cn } from '@djangocfg/ui-core/lib';
+import { useIsMobile } from '@djangocfg/ui-core/hooks';
+import { useQueryParams } from '../hooks';
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+} from './pagination';
+
+interface SSRPaginationProps {
+  currentPage: number;
+  totalPages: number;
+  totalItems: number;
+  itemsPerPage: number;
+  hasNextPage: boolean;
+  hasPreviousPage: boolean;
+  className?: string;
+  showInfo?: boolean;
+  maxVisiblePages?: number;
+  baseUrl?: string;
+  pathname?: string;
+  preserveQuery?: boolean;
+  prefetch?: boolean;
+}
+
+export const SSRPagination: React.FC<SSRPaginationProps> = ({
+  currentPage,
+  totalPages,
+  totalItems,
+  itemsPerPage,
+  hasNextPage,
+  hasPreviousPage,
+  className,
+  showInfo = true,
+  maxVisiblePages = 7,
+  baseUrl,
+  pathname: propPathname,
+  preserveQuery = true,
+  prefetch = true,
+}) => {
+  const queryParams = useQueryParams();
+  const pathname = usePathname();
+  const isMobile = useIsMobile();
+
+  // Get current page from URL if available, otherwise use prop
+  const getCurrentPageFromUrl = (): number => {
+    const pageParam = queryParams.get('page');
+    if (pageParam) {
+      const pageNum = parseInt(pageParam, 10);
+      return isNaN(pageNum) ? 1 : pageNum;
+    }
+    return 1;
+  };
+
+  const actualCurrentPage = getCurrentPageFromUrl() || currentPage;
+
+  // Calculate actual navigation state based on current page from URL
+  const actualHasPreviousPage = actualCurrentPage > 1;
+  
+  // Smart total pages calculation - if we're on a page higher than totalPages,
+  // extend totalPages to include current page + some extra
+  const smartTotalPages = Math.max(
+    totalPages,
+    actualCurrentPage + (hasNextPage ? 5 : 0)
+  );
+  
+  const actualHasNextPage = hasNextPage;
+
+  // Generate URL for a specific page
+  const getPageUrl = (page: number): string => {
+    if (baseUrl) {
+      return `${baseUrl}?page=${page}`;
+    }
+
+    // Use current route with updated page parameter
+    const newSearchParams = preserveQuery 
+      ? new URLSearchParams(queryParams.toString())
+      : new URLSearchParams();
+
+    newSearchParams.set('page', page.toString());
+
+    // Remove page=1 from URL to keep URLs clean
+    if (page === 1) {
+      newSearchParams.delete('page');
+    }
+
+    const queryString = newSearchParams.toString();
+    const basePath = propPathname || pathname || '';
+    return queryString ? `${basePath}?${queryString}` : basePath;
+  };
+
+  // Generate array of page numbers to display
+  const getVisiblePages = (): (number | 'ellipsis')[] => {
+    // On mobile, show fewer pages
+    const mobileMaxVisible = 3;
+    const effectiveMaxVisible = isMobile ? mobileMaxVisible : maxVisiblePages;
+    
+    if (smartTotalPages <= effectiveMaxVisible) {
+      return Array.from({ length: smartTotalPages }, (_, i) => i + 1);
+    }
+
+    const pages: (number | 'ellipsis')[] = [];
+    const halfVisible = Math.floor(effectiveMaxVisible / 2);
+
+    if (isMobile) {
+      // Mobile: Show only current page and adjacent pages
+      if (actualCurrentPage > 1) {
+        pages.push(actualCurrentPage - 1);
+      }
+      pages.push(actualCurrentPage);
+      if (actualCurrentPage < smartTotalPages) {
+        pages.push(actualCurrentPage + 1);
+      }
+    } else {
+      // Desktop: Full pagination logic
+      // Always show first page
+      pages.push(1);
+
+      let start = Math.max(2, actualCurrentPage - halfVisible);
+      let end = Math.min(smartTotalPages - 1, actualCurrentPage + halfVisible);
+
+      // Adjust range if we're near the beginning or end
+      if (actualCurrentPage <= halfVisible + 1) {
+        end = Math.min(smartTotalPages - 1, effectiveMaxVisible - 1);
+      } else if (actualCurrentPage >= smartTotalPages - halfVisible) {
+        start = Math.max(2, smartTotalPages - effectiveMaxVisible + 2);
+      }
+
+      // Add ellipsis after first page if needed
+      if (start > 2) {
+        pages.push('ellipsis');
+      }
+
+      // Add middle pages
+      for (let i = start; i <= end; i++) {
+        pages.push(i);
+      }
+
+      // Add ellipsis before last page if needed
+      if (end < smartTotalPages - 1) {
+        pages.push('ellipsis');
+      }
+
+      // Always show last page (if more than 1 page)
+      if (smartTotalPages > 1) {
+        pages.push(smartTotalPages);
+      }
+    }
+
+    return pages;
+  };
+
+  // Don't render if there's only one page or no pages
+  if (smartTotalPages <= 1) {
+    return null;
+  }
+
+  const visiblePages = getVisiblePages();
+  const startItem = (actualCurrentPage - 1) * itemsPerPage + 1;
+  const endItem = Math.min(actualCurrentPage * itemsPerPage, totalItems);
+
+  return (
+    <div className={cn("space-y-4", className)}>
+      {/* Pagination Info */}
+      {showInfo && (
+        <div className="text-sm text-muted-foreground text-center">
+          {isMobile ? (
+            `Page ${actualCurrentPage} of ${smartTotalPages}`
+          ) : (
+            `Showing ${startItem.toLocaleString()} to ${endItem.toLocaleString()} of ${totalItems.toLocaleString()} results`
+          )}
+        </div>
+      )}
+
+      {/* Pagination Controls */}
+      <Pagination>
+        <PaginationContent>
+          {/* Previous Button */}
+          <PaginationItem>
+            {actualHasPreviousPage ? (
+              <Link href={getPageUrl(actualCurrentPage - 1)} prefetch={prefetch} passHref legacyBehavior>
+                <PaginationPrevious />
+              </Link>
+            ) : (
+              <PaginationPrevious 
+                href="#" 
+                className="pointer-events-none opacity-50"
+                onClick={(e) => e.preventDefault()}
+              />
+            )}
+          </PaginationItem>
+
+          {/* Page Numbers */}
+          {visiblePages.map((page, index) => (
+            <PaginationItem key={index}>
+              {page === 'ellipsis' ? (
+                <PaginationEllipsis />
+              ) : (
+                <Link href={getPageUrl(page)} prefetch={prefetch} passHref legacyBehavior>
+                  <PaginationLink isActive={page === actualCurrentPage}>
+                    {page}
+                  </PaginationLink>
+                </Link>
+              )}
+            </PaginationItem>
+          ))}
+
+          {/* Next Button */}
+          <PaginationItem>
+            {hasNextPage ? (
+              <Link href={getPageUrl(actualCurrentPage + 1)} prefetch={prefetch} passHref legacyBehavior>
+                <PaginationNext />
+              </Link>
+            ) : (
+              <PaginationNext 
+                href="#" 
+                className="pointer-events-none opacity-50"
+                onClick={(e) => e.preventDefault()}
+              />
+            )}
+          </PaginationItem>
+        </PaginationContent>
+      </Pagination>
+    </div>
+  );
+};
+
+SSRPagination.displayName = 'SSRPagination';

package/src/hooks/index.ts

@@ -0,0 +1,19 @@
+// ============================================================================
+// Re-export all hooks from @djangocfg/ui-core
+// ============================================================================
+export * from '@djangocfg/ui-core/hooks';
+
+// ============================================================================
+// Next.js/Browser specific hooks
+// ============================================================================
+
+// Storage hooks (browser localStorage/sessionStorage)
+export { useLocalStorage } from './useLocalStorage';
+export { useSessionStorage } from './useSessionStorage';
+
+// Theme hook (uses next-themes)
+export { useTheme } from './useTheme';
+
+// Next.js router hooks
+export { useQueryParams } from './useQueryParams';
+export { useCfgRouter } from './useCfgRouter';

package/src/hooks/useCfgRouter.ts

@@ -0,0 +1,153 @@
+/**
+ * Universal Router Hook with BasePath Support
+ *
+ * Wrapper around Next.js useRouter that automatically handles basePath
+ * for static builds served via iframe or subdirectory
+ * 
+ * IMPORTANT: In Next.js 15 App Router, router.push() does NOT automatically
+ * handle basePath (unlike Pages Router). This is a breaking change in App Router.
+ * 
+ * This hook ensures basePath is always included when navigating, especially
+ * important for static exports served via iframe where basePath is critical.
+ * 
+ * @see https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration
+ */
+
+'use client';
+
+import { useRouter as useNextRouter } from 'next/navigation';
+import { useCallback, useMemo } from 'react';
+
+/**
+ * Get base path from environment variable
+ */
+function getBasePath(): string {
+  if (typeof process === 'undefined') {
+    return '';
+  }
+  return process.env.NEXT_PUBLIC_BASE_PATH || '';
+}
+
+/**
+ * Add base path to a route path
+ */
+function withBasePath(path: string, basePath: string): string {
+  if (!basePath) {
+    return path;
+  }
+  // Ensure path starts with /
+  const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+  // Remove trailing slash from basePath
+  const normalizedBasePath = basePath.replace(/\/$/, '');
+  return `${normalizedBasePath}${normalizedPath}`;
+}
+
+/**
+ * Router with basePath support
+ *
+ * Automatically adds basePath to all navigation methods when basePath is configured.
+ * In Next.js 15 App Router, router.push() doesn't handle basePath automatically,
+ * so this hook uses window.location to ensure basePath is always included.
+ *
+ * @example
+ * ```tsx
+ * const router = useCfgRouter();
+ *
+ * // With basePath='/cfg/admin':
+ * router.push('/dashboard');     // Client-side navigation to '/cfg/admin/dashboard'
+ * router.replace('/auth');       // Client-side replace with '/cfg/admin/auth'
+ * router.hardPush('/dashboard'); // Full page reload to '/cfg/admin/dashboard'
+ * router.hardReplace('/auth');   // Full page replace with '/cfg/admin/auth'
+ * ```
+ */
+export function useCfgRouter() {
+  const router = useNextRouter();
+
+  // Get basePath and check if we're in static build mode
+  const basePath = useMemo(() => getBasePath(), []);
+  const isStaticBuild = useMemo(() => {
+    return typeof process !== 'undefined' && process.env.NEXT_PUBLIC_STATIC_BUILD === 'true';
+  }, []);
+
+  const push = useCallback((href: string, options?: { scroll?: boolean }) => {
+    if (basePath) {
+      // App Router doesn't handle basePath automatically, use window.location
+      window.location.href = withBasePath(href, basePath);
+    } else {
+      // No basePath configured, use standard router
+      router.push(href, options);
+    }
+  }, [router, basePath]);
+
+  const replace = useCallback((href: string, options?: { scroll?: boolean }) => {
+    if (basePath) {
+      // App Router doesn't handle basePath automatically, use window.location
+      window.location.replace(withBasePath(href, basePath));
+    } else {
+      // No basePath configured, use standard router
+      router.replace(href, options);
+    }
+  }, [router, basePath]);
+
+  /**
+   * Hard push - always uses window.location.href for full page reload
+   *
+   * Use this for auth redirects where React contexts need to reinitialize.
+   * Unlike push(), this ALWAYS triggers a full page reload, ensuring all
+   * contexts are reinitialized with fresh state.
+   *
+   * @example
+   * ```tsx
+   * // After successful login - contexts need to reload with new auth state
+   * router.hardPush('/dashboard');
+   * ```
+   */
+  const hardPush = useCallback((href: string) => {
+    window.location.href = withBasePath(href, basePath);
+  }, [basePath]);
+
+  /**
+   * Hard replace - always uses window.location.replace for full page reload
+   *
+   * Same as hardPush but replaces current history entry.
+   * Use for auth redirects where you don't want back button to return to login.
+   *
+   * @example
+   * ```tsx
+   * // After logout - replace so back button doesn't go to protected page
+   * router.hardReplace('/auth');
+   * ```
+   */
+  const hardReplace = useCallback((href: string) => {
+    window.location.replace(withBasePath(href, basePath));
+  }, [basePath]);
+
+  const prefetch = useCallback((href: string) => {
+    // Prefetch doesn't need basePath handling, Next.js handles it
+    router.prefetch(href);
+  }, [router]);
+
+  const back = useCallback(() => {
+    router.back();
+  }, [router]);
+
+  const forward = useCallback(() => {
+    router.forward();
+  }, [router]);
+
+  const refresh = useCallback(() => {
+    router.refresh();
+  }, [router]);
+
+  return {
+    push,
+    replace,
+    hardPush,
+    hardReplace,
+    prefetch,
+    back,
+    forward,
+    refresh,
+  };
+}
+

package/src/hooks/useLocalStorage.ts

@@ -0,0 +1,221 @@
+'use client';
+
+import { useEffect, useState, useRef } from 'react';
+
+/**
+ * Simple localStorage hook with better error handling
+ *
+ * IMPORTANT: To prevent hydration mismatch, this hook:
+ * - Always returns initialValue on first render (same as SSR)
+ * - Reads from localStorage only after component mounts
+ *
+ * @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 useLocalStorage<T>(key: string, initialValue: T) {
+  // Always start with initialValue to match SSR
+  const [storedValue, setStoredValue] = useState<T>(initialValue);
+  const [isHydrated, setIsHydrated] = useState(false);
+  const isInitialized = useRef(false);
+
+  // Read from localStorage after mount (avoids hydration mismatch)
+  useEffect(() => {
+    if (isInitialized.current) return;
+    isInitialized.current = true;
+
+    try {
+      const item = window.localStorage.getItem(key);
+      if (item !== null) {
+        // Try to parse as JSON first, fallback to string
+        try {
+          setStoredValue(JSON.parse(item));
+        } catch {
+          // If JSON.parse fails, return as string
+          setStoredValue(item as T);
+        }
+      }
+    } catch (error) {
+      console.error(`Error reading localStorage key "${key}":`, error);
+    }
+
+    setIsHydrated(true);
+  }, [key]);
+
+  // 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 localStorage is full
+  const clearOldData = () => {
+    try {
+      const keys = Object.keys(localStorage).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) {
+              localStorage.removeItem(key);
+              localStorage.removeItem(`${key}_timestamp`);
+            }
+          } catch {
+            // Ignore errors when removing items
+          }
+        }
+      }
+    } catch (error) {
+      console.error('Error clearing old localStorage data:', error);
+    }
+  };
+
+  // Force clear all data if quota is exceeded
+  const forceClearAll = () => {
+    try {
+      const keys = Object.keys(localStorage);
+      for (const key of keys) {
+        try {
+          localStorage.removeItem(key);
+        } catch {
+          // Ignore errors when removing items
+        }
+      }
+    } catch (error) {
+      console.error('Error force clearing localStorage:', error);
+    }
+  };
+
+  // Update localStorage 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.localStorage.removeItem(key);
+          window.localStorage.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 {
+          // For strings, store directly without JSON.stringify
+          if (typeof valueToStore === 'string') {
+            window.localStorage.setItem(key, valueToStore);
+          } else {
+            window.localStorage.setItem(key, JSON.stringify(valueToStore));
+          }
+          // Add timestamp for cleanup
+          window.localStorage.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('localStorage quota exceeded, clearing old data...');
+            clearOldData();
+            
+            // Try again after clearing
+            try {
+              // For strings, store directly without JSON.stringify
+              if (typeof valueToStore === 'string') {
+                window.localStorage.setItem(key, valueToStore);
+              } else {
+                window.localStorage.setItem(key, JSON.stringify(valueToStore));
+              }
+              window.localStorage.setItem(`${key}_timestamp`, Date.now().toString());
+            } catch (retryError) {
+              console.error(`Failed to set localStorage key "${key}" after clearing old data:`, retryError);
+              // If still fails, force clear all and try one more time
+              try {
+                forceClearAll();
+                // For strings, store directly without JSON.stringify
+                if (typeof valueToStore === 'string') {
+                  window.localStorage.setItem(key, valueToStore);
+                } else {
+                  window.localStorage.setItem(key, JSON.stringify(valueToStore));
+                }
+                window.localStorage.setItem(`${key}_timestamp`, Date.now().toString());
+              } catch (finalError) {
+                console.error(`Failed to set localStorage key "${key}" after force clearing:`, finalError);
+                // If still fails, just update the state without localStorage
+                setStoredValue(valueToStore);
+              }
+            }
+          } else {
+            throw storageError;
+          }
+        }
+      }
+    } catch (error) {
+      console.error(`Error setting localStorage key "${key}":`, error);
+      // Still update the state even if localStorage fails
+      const valueToStore = value instanceof Function ? value(storedValue) : value;
+      setStoredValue(valueToStore);
+    }
+  };
+
+  // Remove value from localStorage
+  const removeValue = () => {
+    try {
+      setStoredValue(initialValue);
+      if (typeof window !== 'undefined') {
+        try {
+          window.localStorage.removeItem(key);
+          window.localStorage.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('localStorage quota exceeded during removal, clearing old data...');
+            clearOldData();
+            
+            try {
+              window.localStorage.removeItem(key);
+              window.localStorage.removeItem(`${key}_timestamp`);
+            } catch (retryError) {
+              console.error(`Failed to remove localStorage key "${key}" after clearing:`, retryError);
+              // If still fails, force clear all
+              forceClearAll();
+            }
+          } else {
+            throw removeError;
+          }
+        }
+      }
+    } catch (error) {
+      console.error(`Error removing localStorage key "${key}":`, error);
+    }
+  };
+
+  return [storedValue, setValue, removeValue] as const;
+}