@djangocfg/layouts 1.4.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Layout system and components for Unrealon applications",
   "author": {
     "name": "DjangoCFG",
@@ -63,9 +63,9 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^1.4.0",
-    "@djangocfg/og-image": "^1.4.0",
-    "@djangocfg/ui": "^1.4.0",
+    "@djangocfg/api": "^1.4.1",
+    "@djangocfg/og-image": "^1.4.1",
+    "@djangocfg/ui": "^1.4.1",
     "@hookform/resolvers": "^5.2.0",
     "consola": "^3.4.2",
     "lucide-react": "^0.468.0",
@@ -86,7 +86,7 @@
     "vidstack": "0.6.15"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^1.4.0",
+    "@djangocfg/typescript-config": "^1.4.1",
     "@types/node": "^24.7.2",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.1",

package/src/index.ts

@@ -10,6 +10,9 @@ export * from './auth';
 // Layout components
 export * from './layouts';
 
+// Types
+export * from './types';
+
 // Snippets - Reusable UI components
 export * from './snippets';
 

package/src/layouts/AppLayout/AppLayout.tsx

@@ -36,9 +36,8 @@ import { AuthLayout } from './layouts/AuthLayout';
 import { PagePreloader } from './layouts/AdminLayout/components';
 import { determineLayoutMode, getRedirectUrl } from './utils';
 import { useAuth } from '../../auth';
-import type { AppLayoutConfig } from './types';
+import type { AppLayoutConfig, PageWithLayout, LayoutMode } from './types';
 import type { ValidationErrorConfig, CORSErrorConfig, NetworkErrorConfig } from '../../validation';
-import type { PageWithConfig } from '../../types/pageConfig';
 import { determinePageConfig } from '../../types/pageConfig';
 import packageJson from '../../../package.json';
 
@@ -52,31 +51,16 @@ export interface AppLayoutProps {
   children: ReactNode;
   config: AppLayoutConfig;
   /**
-   * Next.js page component (for reading pageConfig)
+   * Next.js page component (for reading pageConfig and layout preferences)
+   * Pass Component from _app.tsx to enable smart layout detection
    * @example component={Component}
    */
-  component?: PageWithConfig | any;
+  component?: PageWithLayout | any;
   /**
    * Next.js page props (for reading dynamic pageConfig from SSR)
    * @example pageProps={pageProps}
    */
   pageProps?: Record<string, any>;
-  /**
-   * Disable layout rendering (Navigation, Sidebar, Footer)
-   * Only providers and SEO remain active
-   * Useful for custom layouts like landing pages
-   */
-  disableLayout?: boolean;
-  /**
-   * Force a specific layout regardless of route
-   * Overrides automatic layout detection
-   *
-   * @example forceLayout="public" - always use PublicLayout
-   * @example forceLayout="private" - always use PrivateLayout
-   * @example forceLayout="auth" - always use AuthLayout
-   * @example forceLayout="admin" - Django CFG admin mode with iframe integration
-   */
-  forceLayout?: 'public' | 'private' | 'auth' | 'admin';
   /**
    * Font family to apply globally
    * Accepts Next.js font object or CSS font-family string
@@ -110,18 +94,18 @@ export interface AppLayoutProps {
 /**
  * Layout Router Component
  *
- * Determines which layout to use based on route
- * Uses AppContext - no props passed down!
+ * Smart layout detection with priority:
+ * 1. component.getLayout (custom layout function)
+ * 2. component.layoutMode ('none' | 'public' | 'private' | 'auth' | 'admin')
+ * 3. Automatic route-based detection
  */
 function LayoutRouter({
   children,
-  disableLayout,
-  forceLayout,
+  component,
   config
 }: {
   children: ReactNode;
-  disableLayout?: boolean;
-  forceLayout?: 'public' | 'private' | 'auth' | 'admin';
+  component?: PageWithLayout | any;
   config: AppLayoutConfig;
 }) {
   const router = useRouter();
@@ -133,8 +117,18 @@ function LayoutRouter({
     setIsMounted(true);
   }, []);
 
-  // If layout is disabled, render children directly (providers still active!)
-  if (disableLayout) {
+  // Priority 1: Check if page has custom getLayout function
+  const hasCustomLayout = component && typeof component.getLayout === 'function';
+  if (hasCustomLayout) {
+    // Use custom layout - render children directly (getLayout applied in _app.tsx)
+    return <>{children}</>;
+  }
+
+  // Priority 2: Check component.layoutMode
+  const componentLayoutMode = component?.layoutMode;
+
+  // If layoutMode is 'none', render children directly
+  if (componentLayoutMode === 'none') {
     return <>{children}</>;
   }
 
@@ -145,7 +139,7 @@ function LayoutRouter({
 
   // Admin routes: Always show loading during SSR and initial client render
   // This prevents hydration mismatch when isAuthenticated differs between server/client
-  if (isAdminRoute && !forceLayout) {
+  if ((isAdminRoute && !componentLayoutMode) || componentLayoutMode === 'admin') {
     // In embedded mode (iframe), render AdminLayout immediately to receive postMessage
     const isEmbedded = typeof window !== 'undefined' && window !== window.parent;
 
@@ -186,7 +180,7 @@ function LayoutRouter({
 
   // Private routes: Always show loading during SSR and initial client render
   // This prevents hydration mismatch when isAuthenticated differs between server/client
-  if (isPrivateRoute && !forceLayout) {
+  if ((isPrivateRoute && !componentLayoutMode) || componentLayoutMode === 'private') {
     if (!isMounted || isLoading) {
       return <PagePreloader />;
     }
@@ -207,11 +201,12 @@ function LayoutRouter({
     return <PrivateLayout>{children}</PrivateLayout>;
   }
 
-  // Determine layout mode for non-private routes
+  // Determine layout mode for non-private/admin routes
   const getLayoutMode = (): 'public' | 'auth' | 'admin' => {
-    if (forceLayout === 'auth') return 'auth';
-    if (forceLayout === 'public') return 'public';
-    if (forceLayout === 'admin') return 'admin';
+    // Priority: componentLayoutMode > auto-detect
+    if (componentLayoutMode === 'auth') return 'auth';
+    if (componentLayoutMode === 'public') return 'public';
+    if (componentLayoutMode === 'admin') return 'admin';
     if (isAuthRoute) return 'auth';
     return 'public';
   };
@@ -251,33 +246,35 @@ function LayoutRouter({
 /**
  * AppLayout - Main Component
  *
- * Single entry point for all layout logic
+ * Single entry point for all layout logic with smart layout detection
  * Wrap your app once in _app.tsx
  *
  * @example
  * ```tsx
- * // With layout (default - auto-detect)
- * <AppLayout config={appLayoutConfig}>
- *   <Component {...pageProps} />
+ * // Smart auto-detection (recommended)
+ * <AppLayout config={appLayoutConfig} component={Component} pageProps={pageProps}>
+ *   {Component.getLayout ? Component.getLayout(<Component {...pageProps} />) : <Component {...pageProps} />}
  * </AppLayout>
  *
  * // With custom font
- * <AppLayout config={appLayoutConfig} fontFamily={manrope.style.fontFamily}>
+ * <AppLayout config={appLayoutConfig} component={Component} fontFamily={inter.style.fontFamily}>
  *   <Component {...pageProps} />
  * </AppLayout>
  *
- * // Without layout (providers still active)
- * <AppLayout config={appLayoutConfig} disableLayout>
- *   <CustomLandingPage />
- * </AppLayout>
+ * // Page with custom layout (in page file)
+ * const Page: PageWithLayout = () => <div>Content</div>;
+ * Page.getLayout = (page) => <CustomLayout>{page}</CustomLayout>;
  *
- * // Force public layout for all pages
- * <AppLayout config={appLayoutConfig} forceLayout="public">
- *   <Component {...pageProps} />
- * </AppLayout>
+ * // Page with forced layout mode (in page file)
+ * const DashboardPage: PageWithLayout = () => <div>Dashboard</div>;
+ * DashboardPage.layoutMode = 'private';
+ *
+ * // Page without layout (in page file)
+ * const LandingPage: PageWithLayout = () => <FullPageDesign />;
+ * LandingPage.layoutMode = 'none';
  * ```
  */
-export function AppLayout({ children, config, component, pageProps, disableLayout = false, forceLayout, fontFamily, showUpdateNotifier, validation, cors, network }: AppLayoutProps) {
+export function AppLayout({ children, config, component, pageProps, fontFamily, showUpdateNotifier, validation, cors, network }: AppLayoutProps) {
   const router = useRouter();
 
   // Check if ErrorBoundary is enabled (default: true)
@@ -318,7 +315,7 @@ export function AppLayout({ children, config, component, pageProps, disableLayou
       <PageProgress />
 
       {/* Smart Layout Router */}
-      <LayoutRouter disableLayout={disableLayout} forceLayout={forceLayout} config={config}>
+      <LayoutRouter component={component} config={config}>
         {children}
       </LayoutRouter>
     </AppContextProvider>

package/src/layouts/AppLayout/index.ts

@@ -1,7 +1,7 @@
 /**
  * AppLayout - Unified Application Layout System
  *
- * Single self-sufficient component for all layout needs
+ * Smart layout system with automatic detection
  */
 
 // Main component
@@ -19,6 +19,7 @@ export type {
   NavigationSection,
   DashboardMenuItem,
   DashboardMenuGroup,
+  PageWithLayout,
 } from './types';
 
 // Context and hooks

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

@@ -8,3 +8,4 @@ export * from './config';
 export * from './layout';
 export * from './navigation';
 export * from './routes';
+export * from './page';

package/src/layouts/AppLayout/types/page.ts

@@ -0,0 +1,80 @@
+/**
+ * Page Type Definitions
+ *
+ * Universal types for Next.js pages with layout and SEO support
+ */
+
+import type { ReactElement, ReactNode } from 'react';
+import type { NextPage } from 'next';
+import type { PageConfig } from '../../../types/pageConfig';
+
+/**
+ * Layout mode types
+ *
+ * - 'public': Public layout (landing, docs, etc.)
+ * - 'private': Private layout (dashboard, authenticated pages)
+ * - 'auth': Auth layout (login, register, OTP)
+ * - 'admin': Admin layout (Django CFG iframe integration)
+ * - 'none': No layout (fully custom page)
+ */
+export type LayoutMode = 'public' | 'private' | 'auth' | 'admin' | 'none';
+
+/**
+ * Universal Page Type - combines layout and SEO configuration
+ *
+ * Extends NextPage with:
+ * - Layout control (getLayout, layoutMode)
+ * - SEO metadata (pageConfig)
+ *
+ * @example
+ * ```tsx
+ * // Custom layout using getLayout
+ * const Page: PageWithLayout = () => <div>Content</div>;
+ * Page.getLayout = (page) => <CustomLayout>{page}</CustomLayout>;
+ *
+ * // Force specific layout mode
+ * const DashboardPage: PageWithLayout = () => <div>Dashboard</div>;
+ * DashboardPage.layoutMode = 'private';
+ *
+ * // With SEO config
+ * const HomePage: PageWithLayout = () => <div>Home</div>;
+ * HomePage.pageConfig = {
+ *   title: 'Home Page',
+ *   description: 'Welcome to our site',
+ *   ogImage: { title: 'Home', subtitle: 'Welcome' }
+ * };
+ *
+ * // Disable all layouts
+ * const LandingPage: PageWithLayout = () => <FullPageDesign />;
+ * LandingPage.layoutMode = 'none';
+ * ```
+ */
+export type PageWithLayout<P = {}, IP = P> = NextPage<P, IP> & {
+  /**
+   * Custom layout function
+   * When provided, AppLayout will use this instead of automatic layout detection
+   *
+   * @param page - The page component wrapped in React element
+   * @returns Layout-wrapped page
+   */
+  getLayout?: (page: ReactElement) => ReactNode;
+
+  /**
+   * Force specific layout mode
+   * Overrides automatic route detection
+   *
+   * - undefined: Auto-detect based on route
+   * - 'public': Always use PublicLayout
+   * - 'private': Always use PrivateLayout
+   * - 'auth': Always use AuthLayout
+   * - 'admin': Always use AdminLayout
+   * - 'none': No layout (page renders directly)
+   */
+  layoutMode?: LayoutMode;
+
+  /**
+   * Page SEO and metadata configuration
+   * Used for <head> tags, OpenGraph, Twitter cards, etc.
+   */
+  pageConfig?: PageConfig;
+};

package/src/layouts/AppLayout/types/routes.ts

@@ -41,8 +41,3 @@ export interface RouteDetectors {
   /** Get page title for route */
   getPageTitle: (path: string) => string;
 }
-
-/**
- * Layout mode based on route
- */
-export type LayoutMode = 'public' | 'private' | 'admin' | 'auth';

package/src/types/index.ts

@@ -1 +1,2 @@
-export type { PageConfig, PageWithConfig } from "./pageConfig";
+export type { PageConfig } from "./pageConfig";
+export { determinePageConfig } from "./pageConfig";

package/src/types/pageConfig.ts

@@ -54,16 +54,13 @@ export interface PageConfig {
   twitter?: TwitterConfig;
 }
 
-// Type for a Page component that includes page configuration
-export type PageWithConfig<T = {}> = FC<T> & {
-  pageConfig?: PageConfig;
-  [key: string]: any;
-};
-
 // --- Helper Function ---
+/**
+ * Determine final page config by merging static and dynamic configs
+ */
 export const determinePageConfig = (
-  Component: PageWithConfig,
-  pageProps: Record<string, any>, // Use a general type for pageProps
+  Component: any,
+  pageProps: Record<string, any>,
   defaultTitle?: string,
   defaultDescription?: string,
 ): PageConfig => {