@djangocfg/layouts 1.2.5 → 1.2.7

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

@@ -0,0 +1,282 @@
+// ============================================================================
+// CfgApp Hook - Application State and Embedding Detection
+// ============================================================================
+
+'use client';
+
+import { useState, useEffect } from 'react';
+import { useRouter } from 'next/router';
+
+export interface UseCfgAppReturn {
+  /**
+   * Whether the app is embedded in an iframe
+   */
+  isEmbedded: boolean;
+
+  /**
+   * Whether the app is running in standalone mode (PWA)
+   */
+  isStandalone: boolean;
+
+  /**
+   * Whether to disable the layout (useful for iframes)
+   */
+  disableLayout: boolean;
+
+  /**
+   * The referrer URL if embedded
+   */
+  referrer: string | null;
+
+  /**
+   * Whether the app has been mounted on the client
+   */
+  isMounted: boolean;
+
+  /**
+   * The theme received from parent (if embedded)
+   */
+  parentTheme: 'light' | 'dark' | null;
+
+  /**
+   * The theme mode from parent ('dark', 'light', 'auto')
+   */
+  parentThemeMode: string | null;
+
+  /**
+   * Handler for setting auth token (used by parent window)
+   */
+  setToken?: (authToken: string, refreshToken?: string) => void;
+}
+
+export interface UseCfgAppOptions {
+  /**
+   * Handler for setting auth token when received from parent
+   */
+  onAuthTokenReceived?: (authToken: string, refreshToken?: string) => void;
+}
+
+/**
+ * Custom hook for detecting app embedding and providing app-level state
+ *
+ * Features:
+ * - Detects iframe embedding
+ * - Detects URL-based embedding (`?embed=true`)
+ * - Detects standalone PWA mode
+ * - Provides referrer information
+ * - Handles postMessage communication with parent window
+ * - Syncs theme from parent window
+ * - Receives auth tokens from parent window
+ * - SSR-safe (returns default values on server)
+ *
+ * Usage:
+ * ```tsx
+ * const { isEmbedded, disableLayout, referrer, parentTheme } = useCfgApp({
+ *   onAuthTokenReceived: (authToken, refreshToken) => {
+ *     api.setToken(authToken, refreshToken);
+ *   }
+ * });
+ *
+ * return (
+ *   <AppLayout disableLayout={disableLayout}>
+ *     {isEmbedded && <div>Running in embedded mode from {referrer}</div>}
+ *   </AppLayout>
+ * );
+ * ```
+ */
+export function useCfgApp(options?: UseCfgAppOptions): UseCfgAppReturn {
+  const router = useRouter();
+  const [isMounted, setIsMounted] = useState(false);
+  const [isEmbedded, setIsEmbedded] = useState(false);
+  const [isStandalone, setIsStandalone] = useState(false);
+  const [referrer, setReferrer] = useState<string | null>(null);
+  const [parentTheme, setParentTheme] = useState<'light' | 'dark' | null>(null);
+  const [parentThemeMode, setParentThemeMode] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Debug logging (uncomment for debugging)
+    // console.log('[useCfgApp] Hook initializing...');
+    setIsMounted(true);
+
+    // Check if running in iframe
+    const inIframe = window.self !== window.top;
+    // console.log('[useCfgApp] Iframe detection:', { inIframe });
+    setIsEmbedded(inIframe);
+
+    // Check if running as standalone PWA
+    const standalone = window.matchMedia('(display-mode: standalone)').matches;
+    setIsStandalone(standalone);
+
+    // Get referrer if embedded
+    if (inIframe && document.referrer) {
+      // console.log('[useCfgApp] Referrer:', document.referrer);
+      setReferrer(document.referrer);
+    }
+
+    // Setup resize observer and interval for iframe height updates
+    let resizeObserver: ResizeObserver | null = null;
+    let checkHeightInterval: NodeJS.Timeout | null = null;
+
+    // Notify parent window that iframe is ready
+    if (inIframe) {
+      try {
+        // console.log('[useCfgApp] Sending iframe-ready message to parent');
+        window.parent.postMessage({
+          type: 'iframe-ready',
+          data: {
+            url: window.location.href,
+            referrer: document.referrer
+          }
+        }, '*'); // Use '*' or specific origin for security
+        // console.log('[useCfgApp] iframe-ready message sent');
+      } catch (e) {
+        console.error('[useCfgApp] Failed to notify parent:', e);
+      }
+
+      // Send current content height (both increases and decreases)
+      const sendHeight = () => {
+        try {
+          // Use body.scrollHeight to avoid iframe height feedback loop
+          // document.documentElement.scrollHeight includes iframe's own height!
+          const bodyScrollHeight = document.body.scrollHeight;
+          const bodyOffsetHeight = document.body.offsetHeight;
+          const height = Math.max(bodyScrollHeight, bodyOffsetHeight);
+
+          window.parent.postMessage({
+            type: 'iframe-resize',
+            data: { height }
+          }, '*');
+        } catch (e) {
+          console.error('[useCfgApp] Failed to send height:', e);
+        }
+      };
+
+      // Send height immediately after mount
+      setTimeout(sendHeight, 100);
+
+      // Watch for content size changes using ResizeObserver
+      resizeObserver = new ResizeObserver(() => {
+        sendHeight();
+      });
+
+      // Observe document body for size changes
+      resizeObserver.observe(document.body);
+
+      // Also observe on route changes and after data loads
+      checkHeightInterval = setInterval(sendHeight, 1000);
+    }
+
+    // Listen for messages from parent window
+    const handleMessage = (event: MessageEvent) => {
+      // console.log('[useCfgApp] Message received:', {
+      //   origin: event.origin,
+      //   type: event.data?.type,
+      //   data: event.data?.data
+      // });
+
+      // Verify origin for security (optional - adjust for your needs)
+      // if (event.origin !== window.location.origin) return;
+
+      const { type, data } = event.data || {};
+
+      switch (type) {
+        case 'parent-auth':
+          // console.log('[useCfgApp] Processing parent-auth message');
+          // Receive authentication tokens from parent
+          if (data?.authToken && options?.onAuthTokenReceived) {
+            try {
+              // console.log('[useCfgApp] Calling onAuthTokenReceived');
+              options.onAuthTokenReceived(data.authToken, data.refreshToken);
+              // console.log('[useCfgApp] Auth tokens received from parent');
+            } catch (e) {
+              console.error('[useCfgApp] Failed to process auth tokens:', e);
+            }
+          }
+          break;
+
+        case 'parent-theme':
+          // console.log('[useCfgApp] Processing parent-theme message');
+          // Receive theme from parent
+          if (data?.theme) {
+            try {
+              // console.log('[useCfgApp] Setting theme:', {
+              //   theme: data.theme,
+              //   themeMode: data.themeMode
+              // });
+              setParentTheme(data.theme);
+              if (data.themeMode) {
+                setParentThemeMode(data.themeMode);
+              }
+              // console.log('[useCfgApp] Theme received from parent:', data.theme, 'mode:', data.themeMode);
+            } catch (e) {
+              console.error('[useCfgApp] Failed to process theme:', e);
+            }
+          }
+          break;
+
+        case 'parent-resize':
+          // Handle parent window resize (optional)
+          // console.log('[useCfgApp] Parent resized:', data);
+          break;
+
+        default:
+          // if (type) {
+          //   console.log('[useCfgApp] Unknown message type:', type);
+          // }
+          break;
+      }
+    };
+
+    // console.log('[useCfgApp] Adding message event listener');
+    window.addEventListener('message', handleMessage);
+
+    return () => {
+      // console.log('[useCfgApp] Cleaning up message event listener');
+      window.removeEventListener('message', handleMessage);
+
+      // Cleanup resize observer and interval
+      if (resizeObserver) {
+        resizeObserver.disconnect();
+      }
+      if (checkHeightInterval) {
+        clearInterval(checkHeightInterval);
+      }
+    };
+  }, [options]);
+
+  // Notify parent about route changes
+  useEffect(() => {
+    if (!isEmbedded || !isMounted) return;
+
+    try {
+      window.parent.postMessage({
+        type: 'iframe-navigation',
+        data: {
+          path: router.asPath,
+          route: router.pathname
+        }
+      }, '*');
+    } catch (e) {
+      console.error('[iframe] Failed to notify parent about navigation:', e);
+    }
+  }, [router.asPath, router.pathname, isEmbedded, isMounted]);
+
+  // Check URL parameter for embed mode
+  const embedParam = router.query.embed === 'true' || router.query.embed === '1';
+
+  // Determine if layout should be disabled
+  // Disable layout if:
+  // 1. Running in iframe AND no explicit embed=false param
+  // 2. URL has embed=true param
+  const shouldDisableLayout = (isEmbedded && router.query.embed !== 'false') || embedParam;
+
+  return {
+    isEmbedded,
+    isStandalone,
+    disableLayout: shouldDisableLayout,
+    referrer,
+    isMounted,
+    parentTheme,
+    parentThemeMode,
+  };
+}

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

@@ -0,0 +1,20 @@
+/**
+ * CfgLayout - Django CFG Layout with iframe Integration
+ *
+ * Universal layout component for Django CFG applications
+ * Handles iframe embedding, theme sync, and auth communication
+ */
+
+// Main component
+export { CfgLayout } from './CfgLayout';
+export type { CfgLayoutProps } from './CfgLayout';
+
+// Hooks
+export { useCfgApp, useApp } from './hooks';
+export type { UseCfgAppReturn, UseCfgAppOptions, UseAppReturn, UseAppOptions } from './hooks';
+
+// Components
+export { ParentSync, AuthStatusSync } from './components';
+
+// Types
+export type { CfgLayoutConfig } from './types';

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

@@ -0,0 +1,45 @@
+import { ReactNode } from 'react';
+
+/**
+ * Configuration for CfgLayout
+ * All options are optional - CfgLayout works out of the box with zero config
+ */
+export interface CfgLayoutConfig {
+  /**
+   * Optional handler called when auth tokens are received from parent window
+   *
+   * Note: Tokens are ALWAYS automatically set in API client via `api.setToken()`.
+   * Use this callback only if you need additional custom logic.
+   *
+   * @example
+   * ```tsx
+   * <CfgLayout config={{
+   *   onAuthTokenReceived: (authToken, refreshToken) => {
+   *     console.log('Tokens received and set in API client');
+   *     // Additional custom logic here
+   *   }
+   * }}>
+   * ```
+   */
+  onAuthTokenReceived?: (authToken: string, refreshToken?: string) => void;
+
+  /**
+   * Whether to automatically sync theme from parent window
+   * @default true
+   */
+  enableThemeSync?: boolean;
+
+  /**
+   * Whether to automatically send auth status to parent window
+   * @default true
+   */
+  enableAuthStatusSync?: boolean;
+}
+
+/**
+ * Props for CfgLayout component
+ */
+export interface CfgLayoutProps {
+  children: ReactNode;
+  config?: CfgLayoutConfig;
+}

package/src/layouts/UILayout/config/components/data.config.tsx

@@ -21,6 +21,17 @@ import {
   Toggle,
   ToggleGroup,
   ToggleGroupItem,
+  Calendar,
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselNext,
+  CarouselPrevious,
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  ChartLegend,
+  ChartLegendContent,
 } from '@djangocfg/ui';
 import type { ComponentConfig } from './types';
 
@@ -305,4 +316,118 @@ export const DATA_COMPONENTS: ComponentConfig[] = [
       </div>
     ),
   },
+  {
+    name: 'Calendar',
+    category: 'data',
+    description: 'Date picker calendar component',
+    importPath: `import { Calendar } from '@djangocfg/ui';`,
+    example: `<Calendar
+  mode="single"
+  selected={date}
+  onSelect={setDate}
+  className="rounded-md border"
+/>`,
+    preview: (
+      <Calendar
+        mode="single"
+        className="rounded-md border"
+      />
+    ),
+  },
+  {
+    name: 'Carousel',
+    category: 'data',
+    description: 'Image and content carousel with navigation',
+    importPath: `import {
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselNext,
+  CarouselPrevious,
+} from '@djangocfg/ui';`,
+    example: `<Carousel className="w-full max-w-xs">
+  <CarouselContent>
+    <CarouselItem>
+      <div className="p-6 border rounded-md">
+        <span className="text-4xl font-semibold">1</span>
+      </div>
+    </CarouselItem>
+    <CarouselItem>
+      <div className="p-6 border rounded-md">
+        <span className="text-4xl font-semibold">2</span>
+      </div>
+    </CarouselItem>
+    <CarouselItem>
+      <div className="p-6 border rounded-md">
+        <span className="text-4xl font-semibold">3</span>
+      </div>
+    </CarouselItem>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>`,
+    preview: (
+      <Carousel className="w-full max-w-xs">
+        <CarouselContent>
+          {Array.from({ length: 5 }).map((_, index) => (
+            <CarouselItem key={index}>
+              <div className="p-6 border rounded-md bg-muted/50">
+                <div className="flex aspect-square items-center justify-center">
+                  <span className="text-4xl font-semibold">{index + 1}</span>
+                </div>
+              </div>
+            </CarouselItem>
+          ))}
+        </CarouselContent>
+        <CarouselPrevious />
+        <CarouselNext />
+      </Carousel>
+    ),
+  },
+  {
+    name: 'Chart',
+    category: 'data',
+    description: 'Data visualization charts powered by Recharts',
+    importPath: `import { ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent } from '@djangocfg/ui';`,
+    example: `import { Bar, BarChart, XAxis, YAxis } from 'recharts';
+
+const chartConfig = {
+  sales: { label: "Sales", color: "hsl(var(--chart-1))" },
+  profit: { label: "Profit", color: "hsl(var(--chart-2))" },
+};
+
+const chartData = [
+  { month: "Jan", sales: 400, profit: 240 },
+  { month: "Feb", sales: 300, profit: 180 },
+  { month: "Mar", sales: 500, profit: 300 },
+];
+
+<ChartContainer config={chartConfig} className="min-h-[200px] w-full">
+  <BarChart data={chartData}>
+    <XAxis dataKey="month" />
+    <YAxis />
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <ChartLegend content={<ChartLegendContent />} />
+    <Bar dataKey="sales" fill="var(--color-sales)" />
+    <Bar dataKey="profit" fill="var(--color-profit)" />
+  </BarChart>
+</ChartContainer>`,
+    preview: (
+      <div className="p-6 border rounded-md bg-muted/50">
+        <p className="text-sm text-muted-foreground mb-4">
+          Chart components built on Recharts with:
+        </p>
+        <ul className="space-y-2 text-sm text-muted-foreground">
+          <li>• Bar, Line, Area, Pie charts</li>
+          <li>• Responsive container</li>
+          <li>• Theme-aware colors</li>
+          <li>• Tooltips and legends</li>
+          <li>• Customizable styling</li>
+        </ul>
+        <p className="text-xs text-muted-foreground mt-4">
+          See <strong>Recharts documentation</strong> for all chart types
+        </p>
+      </div>
+    ),
+  },
 ];

package/src/layouts/UILayout/config/components/feedback.config.tsx

@@ -14,6 +14,7 @@ import {
   AvatarImage,
   Button,
   useToast,
+  Toaster,
 } from '@djangocfg/ui';
 import type { ComponentConfig } from './types';
 
@@ -243,4 +244,47 @@ export const FEEDBACK_COMPONENTS: ComponentConfig[] = [
       </div>
     ),
   },
+  {
+    name: 'Toaster',
+    category: 'feedback',
+    description: 'Global toast notification container (works with Toast component)',
+    importPath: `import { Toaster, useToast } from '@djangocfg/ui';`,
+    example: `// Add Toaster once in your app layout
+<Toaster />
+
+// Then use the useToast hook anywhere
+function MyComponent() {
+  const { toast } = useToast();
+
+  return (
+    <Button
+      onClick={() => {
+        toast({
+          title: "Scheduled: Catch up",
+          description: "Friday, February 10, 2023 at 5:57 PM",
+        });
+      }}
+    >
+      Show Toast
+    </Button>
+  );
+}`,
+    preview: (
+      <div className="p-6 border rounded-md bg-muted/50">
+        <p className="text-sm text-muted-foreground mb-4">
+          Toaster is the global container for Toast notifications:
+        </p>
+        <ul className="space-y-2 text-sm text-muted-foreground">
+          <li>• Add once to your app layout</li>
+          <li>• Use with useToast hook</li>
+          <li>• Manages toast queue and positioning</li>
+          <li>• Accessible and keyboard navigable</li>
+          <li>• Works with Toast component</li>
+        </ul>
+        <p className="text-xs text-muted-foreground mt-4">
+          ℹ️ Different from Sonner - this is the built-in Toast system
+        </p>
+      </div>
+    ),
+  },
 ];