@djangocfg/layouts 1.2.5 → 1.2.7

package/src/layouts/AppLayout/layouts/CfgLayout/README.md

@@ -0,0 +1,389 @@
+# CfgLayout - Django CFG Layout with iframe Integration
+
+Universal layout component for Django CFG applications that handles iframe embedding, theme synchronization, and authentication communication.
+
+**Note:** CfgLayout is now integrated into AppLayout. For most use cases, use `AppLayout` with `isCfgAdmin={true}` instead of using CfgLayout directly.
+
+## Features
+
+- 🖼️ **iframe Embedding Detection** - Automatically detects when running inside an iframe
+- 🎨 **Theme Synchronization** - Syncs theme from Django Unfold parent window
+- 🔐 **Auth Token Passing** - Receives JWT tokens from parent window via postMessage
+- 📤 **Auth Status Reporting** - Sends authentication status to parent window
+- 📏 **Auto Resize** - Automatically adjusts iframe height based on content
+- 🔒 **Secure Communication** - Origin validation for postMessage security
+- ⚡ **Lightweight** - Minimal overhead, works with any layout system
+
+## Installation
+
+Already included in `@djangocfg/layouts` package.
+
+## Recommended Usage (via AppLayout)
+
+### Simple - Enable Django CFG Admin Mode
+
+```tsx
+// apps/admin/src/pages/_app.tsx
+import { AppLayout } from '@djangocfg/layouts';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <AppProviders>
+      <AppLayout config={appLayoutConfig} isCfgAdmin={true}>
+        <Component {...pageProps} />
+      </AppLayout>
+    </AppProviders>
+  );
+}
+```
+
+**That's it!** Setting `isCfgAdmin={true}` automatically:
+- Wraps your app with CfgLayout
+- Sets up iframe communication
+- Handles auth token passing
+- Syncs theme from parent window
+
+## Direct Usage (Advanced)
+
+If you need more control, you can use CfgLayout directly:
+
+### 1. Wrap your app with CfgLayout (Zero Config!)
+
+```tsx
+// apps/admin/src/pages/_app.tsx
+import { CfgLayout, AppLayout } from '@djangocfg/layouts';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <CfgLayout>
+      <AppLayout config={appLayoutConfig}>
+        <Component {...pageProps} />
+      </AppLayout>
+    </CfgLayout>
+  );
+}
+```
+
+**That's it!** Auth tokens are automatically set in the API client when received from parent window.
+
+### 2. With custom auth handler (optional)
+
+```tsx
+// Only if you need additional logic when tokens are received
+<CfgLayout
+  config={{
+    onAuthTokenReceived: (authToken, refreshToken) => {
+      // Tokens are already set in API client automatically
+      console.log('Tokens received!');
+      // Your custom logic here
+    }
+  }}
+>
+  <AppLayout config={appLayoutConfig}>
+    <Component {...pageProps} />
+  </AppLayout>
+</CfgLayout>
+```
+
+## Hook Usage
+
+### Use useCfgApp hook to access embedding state
+
+```tsx
+import { useCfgApp } from '@djangocfg/layouts';
+
+function MyComponent() {
+  const { isEmbedded, disableLayout, parentTheme } = useCfgApp();
+
+  return (
+    <div>
+      {isEmbedded && <p>Running in iframe mode</p>}
+      <p>Current theme from parent: {parentTheme}</p>
+    </div>
+  );
+}
+```
+
+### Use with AppLayout's disableLayout prop
+
+```tsx
+import { AppLayout, useCfgApp } from '@djangocfg/layouts';
+
+function MyApp({ Component, pageProps }) {
+  const { disableLayout } = useCfgApp();
+
+  return (
+    <AppLayout
+      config={config}
+      disableLayout={disableLayout}
+      isCfgAdmin={true}
+    >
+      <Component {...pageProps} />
+    </AppLayout>
+  );
+}
+```
+
+## API Reference
+
+### AppLayout with isCfgAdmin
+
+**Recommended approach:**
+
+```typescript
+<AppLayout
+  config={appLayoutConfig}
+  isCfgAdmin={true}  // ← Enables Django CFG admin mode
+  fontFamily={manrope.style.fontFamily}
+>
+  {children}
+</AppLayout>
+```
+
+### CfgLayout Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `children` | `ReactNode` | Required | Your app content |
+| `config` | `CfgLayoutConfig` | `{}` | Configuration object |
+| `enableParentSync` | `boolean` | `true` | Enable automatic theme/auth sync |
+
+### CfgLayoutConfig
+
+**All options are optional!** CfgLayout works with zero configuration.
+
+```typescript
+interface CfgLayoutConfig {
+  // Optional: Called when auth tokens are received from parent
+  // Note: Tokens are ALWAYS automatically set in API client
+  // Use this only if you need additional custom logic
+  onAuthTokenReceived?: (authToken, refreshToken?) => void;
+
+  // Enable/disable theme sync (default: true)
+  enableThemeSync?: boolean;
+
+  // Enable/disable auth status sync (default: true)
+  enableAuthStatusSync?: boolean;
+}
+```
+
+### useCfgApp Hook
+
+```typescript
+const {
+  isEmbedded,        // true if running in iframe
+  isStandalone,      // true if running as PWA
+  disableLayout,     // true if layout should be disabled
+  referrer,          // parent URL if embedded
+  isMounted,         // true after client-side mount
+  parentTheme,       // 'light' | 'dark' | null
+  parentThemeMode,   // 'auto' | 'light' | 'dark' | null
+} = useCfgApp({
+  onAuthTokenReceived: (authToken, refreshToken) => {
+    // Handle tokens (optional - tokens are auto-set in API client)
+  }
+});
+```
+
+**Note:** `useApp` is also exported as an alias for backward compatibility.
+
+## postMessage Communication Protocol
+
+### Parent → iframe
+
+| Message Type | Data | Description |
+|-------------|------|-------------|
+| `parent-theme` | `{ theme: 'dark'\|'light', themeMode: 'auto'\|'dark'\|'light' }` | Theme from Django Unfold |
+| `parent-auth` | `{ authToken, refreshToken }` | JWT authentication tokens |
+
+### iframe → Parent
+
+| Message Type | Data | Description |
+|-------------|------|-------------|
+| `iframe-ready` | `{ url, referrer }` | iframe loaded successfully |
+| `iframe-auth-status` | `{ isAuthenticated, isLoading, hasUser }` | Auth status update |
+| `iframe-resize` | `{ height }` | Content height changed |
+| `iframe-navigation` | `{ path, route }` | User navigated to new page |
+
+## Advanced Usage
+
+### Manual Theme Sync
+
+```tsx
+import { useCfgApp } from '@djangocfg/layouts';
+import { useThemeContext } from '@djangocfg/ui';
+
+function MyThemeSync() {
+  const { isEmbedded, parentTheme } = useCfgApp();
+  const { setTheme } = useThemeContext();
+
+  useEffect(() => {
+    if (isEmbedded && parentTheme) {
+      setTheme(parentTheme);
+    }
+  }, [isEmbedded, parentTheme, setTheme]);
+
+  return null;
+}
+```
+
+### Disable Auto Sync
+
+```tsx
+<CfgLayout enableParentSync={false}>
+  {/* Handle sync manually */}
+</CfgLayout>
+```
+
+### URL Override
+
+Force iframe mode via URL:
+```
+https://example.com/admin/?embed=true
+```
+
+Disable iframe mode:
+```
+https://example.com/admin/?embed=false
+```
+
+## Integration with Django
+
+See Django template at: `src/django_cfg/templates/admin/index.html`
+
+The Django template uses an iframe to load the Next.js app:
+```html
+<iframe
+  id="nextjs-dashboard-iframe"
+  src="{% nextjs_admin_url 'private' %}"
+  title="Next.js Dashboard"
+></iframe>
+```
+
+## Components
+
+### ParentSync
+
+Handles bidirectional communication with parent window. Automatically included when using `isCfgAdmin={true}`.
+
+```tsx
+import { ParentSync } from '@djangocfg/layouts';
+
+// Usually placed inside AppLayout (automatic with isCfgAdmin={true})
+<AuthProvider>
+  <ThemeProvider>
+    <ParentSync />
+    {children}
+  </ThemeProvider>
+</AuthProvider>
+```
+
+## Security Considerations
+
+- All postMessage communications validate origins
+- Tokens are only accepted from expected parent origins
+- iframe uses sandbox attribute with specific permissions
+- localStorage is used for token persistence (XSS protection needed)
+
+## Migration from Old API
+
+**Old approach:**
+```tsx
+import { AppLayout, CfgLayout, useCfgApp } from '@djangocfg/layouts';
+
+function AppLayoutWrapper() {
+  const { disableLayout, isEmbedded } = useCfgApp();
+  return (
+    <AppLayout disableLayout={disableLayout}>
+      {children}
+    </AppLayout>
+  );
+}
+
+export default function App() {
+  return (
+    <CfgLayout>
+      <AppLayoutWrapper>
+        {children}
+      </AppLayoutWrapper>
+    </CfgLayout>
+  );
+}
+```
+
+**New approach:**
+```tsx
+import { AppLayout } from '@djangocfg/layouts';
+
+export default function App({ Component, pageProps }) {
+  return (
+    <AppLayout config={appLayoutConfig} isCfgAdmin={true}>
+      <Component {...pageProps} />
+    </AppLayout>
+  );
+}
+```
+
+## Troubleshooting
+
+### Theme not syncing
+- Check parent window is sending `parent-theme` messages
+- Verify ThemeProvider is in component tree
+- Enable debug logging in `useApp.ts`
+
+### Auth tokens not working
+- Tokens are automatically set in API client
+- Check parent window sends `parent-auth` message
+- Inspect localStorage for tokens: `auth_token`, `refresh_token`
+
+### Layout not hiding in iframe
+- Use `isCfgAdmin={true}` on AppLayout (recommended)
+- Or manually pass `disableLayout` from `useCfgApp()` hook
+- Try URL override: `?embed=true`
+
+### Static export build fails
+- Make sure ParentSync is wrapped with SSR protection (already handled)
+- Check that `useAuth()` is only called on client-side
+- Verify `'use client'` directive is present in components
+
+## Examples
+
+**Simple Django CFG Admin:**
+```tsx
+<AppLayout config={config} isCfgAdmin={true}>
+  <Component {...pageProps} />
+</AppLayout>
+```
+
+**With custom font:**
+```tsx
+<AppLayout
+  config={config}
+  isCfgAdmin={true}
+  fontFamily={manrope.style.fontFamily}
+>
+  <Component {...pageProps} />
+</AppLayout>
+```
+
+**With custom auth logic:**
+```tsx
+<CfgLayout
+  config={{
+    onAuthTokenReceived: (token, refresh) => {
+      console.log('Tokens received from parent');
+      // Additional custom logic
+    }
+  }}
+>
+  <AppLayout config={config}>
+    <Component {...pageProps} />
+  </AppLayout>
+</CfgLayout>
+```
+
+## Related Files
+
+- Django Template: `src/django_cfg/templates/admin/index.html`
+- Django Views: `src/django_cfg/apps/frontend/views.py`
+- Example App: `src/@frontend/apps/admin/src/pages/_app.tsx`

package/src/layouts/AppLayout/layouts/CfgLayout/components/ParentSync.tsx

@@ -0,0 +1,149 @@
+// ============================================================================
+// Parent Sync Component
+// ============================================================================
+// Handles all synchronization between iframe and parent window:
+// - Theme sync (parent → iframe)
+// - Auth status sync (iframe → parent)
+// Must be used inside AuthProvider and ThemeProvider contexts
+
+'use client';
+
+import { useEffect, useState } from 'react';
+import { useAuth } from '../../../../../auth';
+import { useThemeContext } from '@djangocfg/ui';
+import { useCfgApp } from '../hooks/useApp';
+
+/**
+ * ParentSync Component
+ *
+ * Handles bidirectional communication with parent window when embedded:
+ * 1. Receives theme updates from parent (Django Unfold) and applies to ThemeProvider
+ * 2. Sends auth status to parent when authentication state changes
+ *
+ * Usage:
+ * - Place inside AppLayout (after AuthProvider and ThemeProvider)
+ * - Automatically handles all iframe ↔ parent communication
+ *
+ * Note: Safe for static export - only runs on client-side after hydration
+ */
+export function ParentSync() {
+  const [isClient, setIsClient] = useState(false);
+
+  // Wait for client-side hydration to avoid SSR/static export errors
+  useEffect(() => {
+    setIsClient(true);
+  }, []);
+
+  // Early return during SSR/static export
+  if (!isClient) {
+    return null;
+  }
+
+  return <ParentSyncClient />;
+}
+
+/**
+ * Client-only component that uses auth context
+ * Separated to avoid SSR issues during static export
+ */
+function ParentSyncClient() {
+  const auth = useAuth();
+  const { setTheme } = useThemeContext();
+  const { isEmbedded, isMounted, parentTheme } = useCfgApp();
+
+  // 1. Sync theme from parent → iframe
+  useEffect(() => {
+    if (isEmbedded && parentTheme) {
+      // console.log('[ParentSync] 🎨 Syncing theme from parent:', parentTheme);
+      setTheme(parentTheme);
+    }
+  }, [isEmbedded, parentTheme, setTheme]);
+
+  // 2. Send auth status from iframe → parent
+  useEffect(() => {
+    // Only send if embedded and mounted
+    if (!isEmbedded || !isMounted) {
+      // console.log('[ParentSync] Skipping auth sync - not embedded or not mounted:', {
+      //   isEmbedded,
+      //   isMounted
+      // });
+      return;
+    }
+
+    const authData = {
+      isAuthenticated: auth.isAuthenticated,
+      isLoading: auth.isLoading,
+      hasUser: !!auth.user
+    };
+
+    // console.log('[ParentSync] 📤 Sending auth status to parent:', authData);
+
+    try {
+      window.parent.postMessage({
+        type: 'iframe-auth-status',
+        data: authData
+      }, '*');
+      // console.log('[ParentSync] ✅ Auth status sent successfully');
+    } catch (e) {
+      console.error('[ParentSync] ❌ Failed to send auth status:', e);
+    }
+  }, [auth.isAuthenticated, auth.isLoading, auth.user, isEmbedded, isMounted]);
+
+  // 3. Send iframe height changes to parent for auto-resize
+  useEffect(() => {
+    // Only send if embedded and mounted
+    if (!isEmbedded || !isMounted) {
+      return;
+    }
+
+    // Function to send height to parent
+    const sendHeight = () => {
+      const height = document.documentElement.scrollHeight;
+      // console.log('[ParentSync] 📏 Sending height to parent:', height);
+
+      try {
+        window.parent.postMessage({
+          type: 'iframe-resize',
+          data: { height }
+        }, '*');
+      } catch (e) {
+        console.error('[ParentSync] ❌ Failed to send height:', e);
+      }
+    };
+
+    // Send initial height
+    sendHeight();
+
+    // Watch for content height changes with ResizeObserver
+    const resizeObserver = new ResizeObserver(() => {
+      sendHeight();
+    });
+
+    // Observe body element for size changes
+    resizeObserver.observe(document.body);
+
+    // Also observe on route changes (for Next.js)
+    const handleRouteChange = () => {
+      // Delay to allow content to render
+      setTimeout(sendHeight, 100);
+    };
+
+    // Listen for Next.js router events if available
+    if (typeof window !== 'undefined') {
+      window.addEventListener('popstate', handleRouteChange);
+    }
+
+    return () => {
+      resizeObserver.disconnect();
+      if (typeof window !== 'undefined') {
+        window.removeEventListener('popstate', handleRouteChange);
+      }
+    };
+  }, [isEmbedded, isMounted]);
+
+  // This component doesn't render anything
+  return null;
+}
+
+// Export with old name for backward compatibility
+export { ParentSync as AuthStatusSync };

package/src/layouts/AppLayout/layouts/CfgLayout/components/index.ts

@@ -0,0 +1 @@
+export { ParentSync, AuthStatusSync } from './ParentSync';

package/src/layouts/AppLayout/layouts/CfgLayout/hooks/index.ts

@@ -0,0 +1,6 @@
+export { useCfgApp } from './useApp';
+export type { UseCfgAppReturn, UseCfgAppOptions } from './useApp';
+
+// Backward compatibility alias
+export { useCfgApp as useApp } from './useApp';
+export type { UseCfgAppReturn as UseAppReturn, UseCfgAppOptions as UseAppOptions } from './useApp';