@djangocfg/layouts 2.0.9 → 2.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.0.9",
+  "version": "2.0.10",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -92,9 +92,9 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^1.4.39",
-    "@djangocfg/centrifugo": "^1.4.39",
-    "@djangocfg/ui": "^1.4.39",
+    "@djangocfg/api": "^1.4.40",
+    "@djangocfg/centrifugo": "^1.4.40",
+    "@djangocfg/ui": "^1.4.40",
     "@hookform/resolvers": "^5.2.0",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -114,7 +114,7 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^1.4.39",
+    "@djangocfg/typescript-config": "^1.4.40",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",

package/src/components/core/ClientOnly.tsx

@@ -0,0 +1,73 @@
+/**
+ * ClientOnly Component
+ *
+ * Renders children only on the client side to prevent SSR hydration mismatch.
+ * Shows a fallback (loading state) during SSR and initial client mount.
+ *
+ * @example
+ * ```tsx
+ * import { ClientOnly } from '@djangocfg/layouts/components';
+ *
+ * // With default loading fallback
+ * <ClientOnly>
+ *   <ComponentThatUsesClientOnlyAPIs />
+ * </ClientOnly>
+ *
+ * // With custom fallback
+ * <ClientOnly fallback={<MyCustomLoader />}>
+ *   <ComponentThatUsesClientOnlyAPIs />
+ * </ClientOnly>
+ * ```
+ */
+
+'use client';
+
+import { useState, useEffect, ReactNode } from 'react';
+import { Preloader } from '@djangocfg/ui/components';
+
+export interface ClientOnlyProps {
+  children: ReactNode;
+  /**
+   * Fallback to show during SSR and initial mount
+   * @default Preloader with "Loading..." text
+   */
+  fallback?: ReactNode;
+}
+
+/**
+ * Default fallback - fullscreen preloader
+ */
+const defaultFallback = (
+  <Preloader
+    variant="fullscreen"
+    text="Loading..."
+    size="lg"
+    backdrop={true}
+    backdropOpacity={80}
+  />
+);
+
+/**
+ * ClientOnly - Prevents SSR hydration mismatch
+ *
+ * Use this to wrap components that:
+ * - Access browser-only APIs (window, localStorage, etc.)
+ * - Have different initial state on server vs client
+ * - Use authentication state that differs between SSR and CSR
+ */
+export function ClientOnly({
+  children,
+  fallback = defaultFallback,
+}: ClientOnlyProps) {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) {
+    return <>{fallback}</>;
+  }
+
+  return <>{children}</>;
+}

package/src/components/core/index.ts

@@ -2,6 +2,8 @@
  * Core components exports
  */
 
+export { ClientOnly } from './ClientOnly';
+export type { ClientOnlyProps } from './ClientOnly';
 export { JsonLd } from './JsonLd';
 export { LucideIcon } from './LucideIcon';
 export type { LucideIconProps } from './LucideIcon';

package/src/components/errors/ErrorLayout.tsx

@@ -73,13 +73,12 @@ function getErrorIcon(code?: string | number): React.ReactNode {
           viewBox="0 0 24 24"
           aria-hidden="true"
         >
-          {/* Server Error Icon */}
-          <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            strokeWidth={1.5}
-            d="M18.364 18.364A9 9 0 005.636 5.636m12.728 0l-6.849 6.849m0 0l-6.849-6.849m6.849 6.849V21m0 0h7.5M12 21v-7.5M7.5 21H3m7.5 0h7.5M3 18V9a4.5 4.5 0 014.5-4.5h9A4.5 4.5 0 0121 9v9a4.5 4.5 0 01-4.5 4.5h-9A4.5 4.5 0 013 18z"
-          />
+          {/* Server Error Icon - Server with X */}
+          <rect x="2" y="3" width="20" height="7" rx="1" strokeWidth={1.5} />
+          <rect x="2" y="14" width="20" height="7" rx="1" strokeWidth={1.5} />
+          <circle cx="6" cy="6.5" r="1" fill="currentColor" />
+          <circle cx="6" cy="17.5" r="1" fill="currentColor" />
+          <path strokeLinecap="round" strokeWidth={1.5} d="M22 2L2 22" />
         </svg>
       );
     case '403':

package/src/layouts/AppLayout/AppLayout.tsx

@@ -47,7 +47,7 @@ import { ErrorTrackingProvider, type ValidationErrorConfig, type CORSErrorConfig
 import { AnalyticsProvider } from '../../snippets/Analytics';
 import { PageProgress } from '../../components/core/PageProgress';
 import { UpdateNotifier } from '../../components/UpdateNotifier';
-import { Suspense } from '../../components/core';
+import { Suspense, ClientOnly } from '../../components/core';
 
 export type LayoutMode = 'public' | 'private' | 'admin';
 
@@ -148,22 +148,22 @@ export interface AppLayoutProps {
 
 /**
  * AppLayout Content - Renders layout with all providers
+ *
+ * SSR is only enabled for publicLayout.
+ * Private and admin layouts are wrapped in ClientOnly to avoid hydration mismatch.
  */
 function AppLayoutContent({
   children,
   publicLayout,
   privateLayout,
   adminLayout,
-  theme,
-  auth,
   analytics,
   centrifugo,
-  errorTracking,
   errorBoundary,
   updateNotifier,
 }: AppLayoutProps) {
   const pathname = usePathname();
-  
+
   const layoutMode = useMemo(
     () => determineLayoutMode(
       pathname,
@@ -173,46 +173,51 @@ function AppLayoutContent({
     ),
     [pathname, adminLayout, privateLayout, publicLayout]
   );
-  
+
   const enableErrorBoundary = errorBoundary?.enabled !== false;
-  
+
   // Render appropriate layout based on mode
   const renderLayout = () => {
     switch (layoutMode) {
       case 'admin':
         if (!adminLayout && privateLayout) {
-          // Fallback to private layout if no admin layout provided
           return (
-            <Suspense>
-              <privateLayout.component>{children}</privateLayout.component>
-            </Suspense>
+            <ClientOnly>
+              <Suspense>
+                <privateLayout.component>{children}</privateLayout.component>
+              </Suspense>
+            </ClientOnly>
           );
         }
         if (!adminLayout) {
           return children;
         }
         return (
-          <Suspense>
-            <adminLayout.component>{children}</adminLayout.component>
-          </Suspense>
+          <ClientOnly>
+            <Suspense>
+              <adminLayout.component>{children}</adminLayout.component>
+            </Suspense>
+          </ClientOnly>
         );
-        
+
       case 'private':
         if (!privateLayout) {
-          // Fallback to public if no private layout provided
           if (publicLayout) {
             return <publicLayout.component>{children}</publicLayout.component>;
           }
           return children;
         }
         return (
-          <Suspense>
-            <privateLayout.component>{children}</privateLayout.component>
-          </Suspense>
+          <ClientOnly>
+            <Suspense>
+              <privateLayout.component>{children}</privateLayout.component>
+            </Suspense>
+          </ClientOnly>
         );
-        
+
       case 'public':
       default:
+        // Public layout renders with SSR (no ClientOnly wrapper)
         if (!publicLayout) {
           return children;
         }

package/src/layouts/PrivateLayout/PrivateLayout.tsx

@@ -1,19 +1,20 @@
 /**
  * Private Layout
- * 
+ *
  * Layout for authenticated user pages (dashboard, profile, etc.)
  * Import and use directly with props - no complex configs needed!
- * 
+ *
  * Features:
  * - Responsive sidebar with mobile burger menu
  * - Keyboard shortcut (Ctrl/Cmd + B) to toggle sidebar
  * - Header with sidebar trigger and user menu
  * - Configurable content padding
- * 
+ * - NO SSR - renders only on client to avoid hydration mismatch
+ *
  * @example
  * ```tsx
  * import { PrivateLayout } from '@djangocfg/layouts';
- * 
+ *
  * <PrivateLayout
  *   sidebar={{
  *     items: [
@@ -28,7 +29,7 @@
  * >
  *   {children}
  * </PrivateLayout>
- * 
+ *
  * Note: User data (name, email, avatar) is automatically loaded from useAuth() context
  * Keyboard shortcut: Ctrl/Cmd + B to toggle sidebar
  * ```
@@ -37,7 +38,7 @@
 'use client';
 
 import React, { ReactNode } from 'react';
-import { SidebarProvider, SidebarInset, Preloader, Button, ButtonLink } from '@djangocfg/ui/components';
+import { SidebarProvider, SidebarInset, Preloader, ButtonLink } from '@djangocfg/ui/components';
 import { useAuth } from '../../auth';
 import { PrivateSidebar, PrivateHeader, PrivateContent } from './components';
 import type { LucideIcon as LucideIconType } from 'lucide-react';
@@ -76,20 +77,10 @@ export function PrivateLayout({
   header,
   contentPadding = 'default',
 }: PrivateLayoutProps) {
-  const { isAuthenticated, isLoading, user } = useAuth();
-
-  // Debug logging in development
-  if (process.env.NODE_ENV === 'development') {
-    console.log('[PrivateLayout] Render state:', {
-      isLoading,
-      isAuthenticated,
-      hasUser: !!user,
-      hasSidebar: !!sidebar,
-      hasHeader: !!header,
-    });
-  }
+  const { isAuthenticated, isLoading } = useAuth();
 
   // Show loading state while auth is being checked
+  // Note: SSR hydration is handled by ClientOnly wrapper in AppLayout
   if (isLoading) {
     return (
       <Preloader
@@ -104,9 +95,6 @@ export function PrivateLayout({
 
   // Don't render if user is not authenticated
   if (!isAuthenticated) {
-    if (process.env.NODE_ENV === 'development') {
-      console.warn('[PrivateLayout] User not authenticated, returning null');
-    }
     return (
       <div className="flex flex-col items-center justify-center min-h-screen gap-4">
         <h3 className="text-2xl font-bold">