@djangocfg/layouts 1.4.30 → 2.0.2

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

@@ -1,409 +0,0 @@
-# AdminLayout - Django CFG Layout with iframe Integration
-
-Universal layout component for Django CFG applications that handles iframe embedding, theme synchronization, and authentication communication.
-
-**Note:** AdminLayout is now integrated into AppLayout. For most use cases, use `AppLayout` with `isCfgAdmin={true}` instead of using AdminLayout 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 AdminLayout
-- Sets up iframe communication
-- Handles auth token passing
-- Syncs theme from parent window
-
-## Direct Usage (Advanced)
-
-If you need more control, you can use AdminLayout directly:
-
-### 1. Wrap your app with AdminLayout (Zero Config!)
-
-```tsx
-// apps/admin/src/pages/_app.tsx
-import { AdminLayout, AppLayout } from '@djangocfg/layouts';
-
-function MyApp({ Component, pageProps }) {
-  return (
-    <AdminLayout>
-      <AppLayout config={appLayoutConfig}>
-        <Component {...pageProps} />
-      </AppLayout>
-    </AdminLayout>
-  );
-}
-```
-
-**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
-<AdminLayout
-  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>
-</AdminLayout>
-```
-
-## 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>
-```
-
-### AdminLayout Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `children` | `ReactNode` | Required | Your app content |
-| `config` | `AdminLayoutConfig` | `{}` | Configuration object |
-| `enableParentSync` | `boolean` | `true` | Enable automatic theme/auth sync |
-
-### AdminLayoutConfig
-
-**All options are optional!** AdminLayout works with zero configuration.
-
-```typescript
-interface AdminLayoutConfig {
-  // 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 (sent on auth state change) |
-| `iframe-resize` | `{ height }` | Content height changed (sent on ResizeObserver trigger) |
-| `iframe-navigation` | `{ path }` | User navigated to new page (sent via Next.js Router.events) |
-
-## 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
-<AdminLayout enableParentSync={false}>
-  {/* Handle sync manually */}
-</AdminLayout>
-```
-
-### 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>
-```
-
-**What ParentSync does:**
-
-1. **Theme Sync** (Parent → iframe): Receives theme updates from Django Unfold and applies them
-2. **Auth Status Sync** (iframe → Parent): Sends authentication status when it changes
-3. **Auto Resize** (iframe → Parent): Sends content height for iframe resizing
-4. **Navigation Tracking** (iframe → Parent): Sends route changes for "Open in New Window" button
-
-**Navigation Tracking:**
-ParentSync automatically tracks route changes using Next.js Router and sends them to the parent window:
-
-```typescript
-// Automatically sent on every route change
-window.parent.postMessage({
-  type: 'iframe-navigation',
-  data: { path: '/admin/stocks' }
-}, '*');
-```
-
-This enables the "Open in New Window" button in the Django admin to open the exact page the user is currently viewing, not just the home page.
-
-## 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, AdminLayout, useCfgApp } from '@djangocfg/layouts';
-
-function AppLayoutWrapper() {
-  const { disableLayout, isEmbedded } = useCfgApp();
-  return (
-    <AppLayout disableLayout={disableLayout}>
-      {children}
-    </AppLayout>
-  );
-}
-
-export default function App() {
-  return (
-    <AdminLayout>
-      <AppLayoutWrapper>
-        {children}
-      </AppLayoutWrapper>
-    </AdminLayout>
-  );
-}
-```
-
-**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
-<AdminLayout
-  config={{
-    onAuthTokenReceived: (token, refresh) => {
-      console.log('Tokens received from parent');
-      // Additional custom logic
-    }
-  }}
->
-  <AppLayout config={config}>
-    <Component {...pageProps} />
-  </AppLayout>
-</AdminLayout>
-```
-
-## Related Files
-
-- Django Template: `src/django_cfg/templates/admin/index.html`
-- Django Views: `src/django_cfg/apps/frontend/views.py`
-- Example App: `src/django_admin/apps/admin/src/pages/_app.tsx`

package/src/layouts/AppLayout/layouts/AdminLayout/components/PagePreloader.example.tsx

@@ -1,98 +0,0 @@
-/**
- * PagePreloader - Usage Examples
- *
- * This file contains examples of how to use the PagePreloader component
- */
-
-import { PagePreloader, PagePreloaderDark } from './PagePreloader';
-
-// ============================================================================
-// Example 1: Basic Usage
-// ============================================================================
-export function Example1_Basic() {
-  return <PagePreloader />;
-}
-
-// ============================================================================
-// Example 2: Custom Text
-// ============================================================================
-export function Example2_CustomText() {
-  return <PagePreloader text="Loading your dashboard..." />;
-}
-
-// ============================================================================
-// Example 3: Different Sizes
-// ============================================================================
-export function Example3_DifferentSizes() {
-  return (
-    <>
-      <PagePreloader size="sm" text="Small" />
-      <PagePreloader size="md" text="Medium" />
-      <PagePreloader size="lg" text="Large" />
-      <PagePreloader size="xl" text="Extra Large" />
-    </>
-  );
-}
-
-// ============================================================================
-// Example 4: Dark Variant
-// ============================================================================
-export function Example4_Dark() {
-  return <PagePreloaderDark text="Loading..." />;
-}
-
-// ============================================================================
-// Example 5: No Text
-// ============================================================================
-export function Example5_NoText() {
-  return <PagePreloader showText={false} />;
-}
-
-// ============================================================================
-// Example 6: No Backdrop
-// ============================================================================
-export function Example6_NoBackdrop() {
-  return <PagePreloader backdrop={false} />;
-}
-
-// ============================================================================
-// Example 7: Custom Backdrop Opacity
-// ============================================================================
-export function Example7_CustomBackdropOpacity() {
-  return <PagePreloader backdropOpacity={50} text="50% opacity backdrop" />;
-}
-
-// ============================================================================
-// Example 8: Conditional Loading
-// ============================================================================
-export function Example8_ConditionalLoading({ isLoading }: { isLoading: boolean }) {
-  if (!isLoading) return null;
-  return <PagePreloader text="Loading data..." />;
-}
-
-// ============================================================================
-// Example 9: With Custom Styling
-// ============================================================================
-export function Example9_CustomStyling() {
-  return (
-    <PagePreloader
-      className="bg-gradient-to-br from-blue-500 to-purple-600"
-      text="Loading..."
-    />
-  );
-}
-
-// ============================================================================
-// Example 10: In AdminLayout
-// ============================================================================
-export function Example10_InAdminLayout() {
-  // Usage in AdminLayout component
-  const isLoading = true; // Replace with actual loading state
-
-  return (
-    <>
-      {isLoading && <PagePreloader text="Loading application..." />}
-      {/* Rest of your app */}
-    </>
-  );
-}

package/src/layouts/AppLayout/layouts/AdminLayout/components/PagePreloader.tsx

@@ -1,149 +0,0 @@
-/**
- * PagePreloader Component
- *
- * Full-page loading indicator with Lottie animation
- */
-
-'use client';
-
-import React from 'react';
-import { LottiePlayer } from '@djangocfg/ui/tools';
-import energizingAnimation from '../lottie/energizing.json';
-
-export interface PagePreloaderProps {
-  /**
-   * Custom loading text
-   * @default 'Loading...'
-   */
-  text?: string;
-
-  /**
-   * Show loading text
-   * @default true
-   */
-  showText?: boolean;
-
-  /**
-   * Animation size
-   * @default 'lg'
-   */
-  size?: 'sm' | 'md' | 'lg' | 'xl';
-
-  /**
-   * Whether to show backdrop
-   * @default true
-   */
-  backdrop?: boolean;
-
-  /**
-   * Backdrop opacity (0-100)
-   * @default 80
-   */
-  backdropOpacity?: number;
-
-  /**
-   * Additional CSS classes
-   */
-  className?: string;
-}
-
-/**
- * PagePreloader - Full-page loading indicator with energizing animation
- *
- * Features:
- * - Lottie animation with energizing effect
- * - Customizable text and size
- * - Optional backdrop
- * - Smooth fade-in animation
- *
- * Usage:
- * ```tsx
- * // Basic usage
- * <PagePreloader />
- *
- * // With custom text
- * <PagePreloader text="Loading your data..." />
- *
- * // Different size
- * <PagePreloader size="xl" />
- *
- * // Without backdrop
- * <PagePreloader backdrop={false} />
- *
- * // Custom styling
- * <PagePreloader className="bg-gradient-to-br from-blue-500 to-purple-600" />
- * ```
- */
-export function PagePreloader({
-  text = 'Loading...',
-  showText = true,
-  size = 'lg',
-  backdrop = true,
-  backdropOpacity = 80,
-  className,
-}: PagePreloaderProps) {
-  // Generate backdrop opacity classes based on opacity value with explicit light/dark variants
-  const getBackdropClasses = () => {
-    if (!backdrop) return 'bg-transparent';
-
-    // Use explicit light/dark classes for reliable theme support
-    if (backdropOpacity >= 90) {
-      return 'bg-white dark:bg-gray-950'; // Full opacity
-    } else if (backdropOpacity >= 70) {
-      return 'bg-white/90 dark:bg-gray-950/90'; // 90% opacity
-    } else if (backdropOpacity >= 50) {
-      return 'bg-white/80 dark:bg-gray-950/80'; // 80% opacity
-    } else {
-      return 'bg-white/60 dark:bg-gray-950/60'; // 60% opacity
-    }
-  };
-
-  return (
-    <div
-      className={`fixed inset-0 z-50 flex items-center justify-center ${getBackdropClasses()} ${className || ''}`}
-    >
-      <div className="flex flex-col items-center gap-6 animate-in fade-in duration-300">
-        {/* Lottie Animation */}
-        <div className="relative">
-          <LottiePlayer
-            src={energizingAnimation}
-            size={size}
-            autoplay
-            loop
-            speed={1}
-          />
-        </div>
-
-        {/* Loading Text */}
-        {showText && (
-          <div className="flex flex-col items-center gap-2">
-            <p className="text-lg font-medium text-gray-900 dark:text-gray-100">
-              {text}
-            </p>
-            <div className="flex gap-1">
-              <span className="h-2 w-2 animate-bounce rounded-full bg-blue-600 dark:bg-blue-400" style={{ animationDelay: '0ms' }} />
-              <span className="h-2 w-2 animate-bounce rounded-full bg-blue-600 dark:bg-blue-400" style={{ animationDelay: '150ms' }} />
-              <span className="h-2 w-2 animate-bounce rounded-full bg-blue-600 dark:bg-blue-400" style={{ animationDelay: '300ms' }} />
-            </div>
-          </div>
-        )}
-      </div>
-    </div>
-  );
-}
-
-/**
- * PagePreloaderDark - Dark variant of PagePreloader
- *
- * Same as PagePreloader but forces dark backdrop
- * Note: Regular PagePreloader now uses semantic theme colors,
- * so this is only needed for specific dark-only use cases
- */
-export function PagePreloaderDark(props: Omit<PagePreloaderProps, 'className'>) {
-  return (
-    <PagePreloader
-      {...props}
-      className="bg-gray-950/95"
-    />
-  );
-}