npm - @djangocfg/layouts - Versions diffs - 2.1.218 → 2.1.221 - Mend

@djangocfg/layouts 2.1.218 → 2.1.221

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md +133 -678
package/package.json +17 -16
package/src/layouts/AppLayout/AppLayout.tsx +10 -0
package/src/layouts/AppLayout/BaseApp.tsx +20 -1
package/src/layouts/types/layout.types.ts +6 -0

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # @djangocfg/layouts
-Simple, straightforward layout components for Next.js - import and use with props.
+Layout components and providers for Next.js apps.
 **Part of [DjangoCFG](https://djangocfg.com)** — modern Django framework for production-ready SaaS applications.
@@ -10,26 +10,33 @@ Simple, straightforward layout components for Next.js - import and use with prop
 pnpm add @djangocfg/layouts
 ```
-## Core Components
+Add to `globals.css` (before `@import "tailwindcss"`):
-### BaseApp
+```css
+@import "@djangocfg/ui-nextjs/styles";
+@import "@djangocfg/layouts/styles";
+@import "@djangocfg/ui-tools/styles";
+@import "@djangocfg/debuger/styles";
+@import "tailwindcss";
+```
+## BaseApp
-Core providers wrapper - use when you need providers without layout routing:
+Core providers wrapper. Use directly when you don't need route-based layout switching.
 ```tsx
 import { BaseApp } from '@djangocfg/layouts';
-// app/layout.tsx
 export default function RootLayout({ children }) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body>
         <BaseApp
-          theme={{ defaultTheme: 'dark' }}
+          project="my-app"
+          theme={{ defaultTheme: 'dark', storageKey: 'my-theme' }}
+          auth={{ apiUrl: process.env.NEXT_PUBLIC_API_URL }}
           analytics={{ googleTrackingId: 'G-XXXXXXXXXX' }}
-          centrifugo={{ enabled: true, url: process.env.NEXT_PUBLIC_CENTRIFUGO_URL }}
-          pwaInstall={{ enabled: true, showInstallHint: true }}
-          mcpChat={{ enabled: true, autoDetectEnvironment: true }}
+          debug={true}
         >
           {children}
         </BaseApp>
@@ -39,29 +46,35 @@ export default function RootLayout({ children }) {
 }
 ```
-**Included providers:**
-- **ThemeProvider** - Light/dark/system theme management
-- **TooltipProvider** - Tooltip positioning context
-- **SWRConfig** - Data fetching configuration
-- **AuthProvider** - Authentication context (from `@djangocfg/api`)
-- **AnalyticsProvider** - Google Analytics (optional)
-- **CentrifugoProvider** - WebSocket real-time (optional)
-- **PwaProvider** - PWA installation (optional)
-- **ErrorTrackingProvider** - Error handling and tracking
-- **ErrorBoundary** - React error boundary
-- **MonitorProvider** - Frontend error monitoring via `@djangocfg/monitor` (optional)
-- **MCP Chat Widget** - AI chat assistant (optional)
-**Global components:**
-- **PageProgress** - NProgress bar for route changes
-- **Toaster** - Toast notifications container
-- **A2HSHint** - PWA install hint (if enabled)
-> **Note:** Auth functionality is provided by `@djangocfg/api` package. See [@djangocfg/api documentation](../api/README.md) for auth usage.
-### AppLayout
+**Props:**
-Smart layout router built on BaseApp - automatically selects layout based on route:
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `project` | `string` | — | App name — auto-passed to `MonitorProvider` and debug panel |
+| `theme` | `ThemeConfig` | — | Theme config (defaultTheme, storageKey) |
+| `auth` | `AuthConfig` | — | Auth provider config |
+| `analytics` | `AnalyticsConfig` | — | Google Analytics config |
+| `centrifugo` | `CentrifugoConfig` | — | WebSocket real-time config |
+| `errorTracking` | `ErrorTrackingConfig` | — | Validation/CORS/network error capture |
+| `errorBoundary` | `ErrorBoundaryConfig` | enabled | React error boundary |
+| `swr` | `SWRConfigOptions` | — | SWR data fetching config |
+| `pwaInstall` | `PwaInstallConfig` | — | PWA install prompt |
+| `mcpChat` | `McpChatConfig` | — | AI chat widget |
+| `monitor` | `MonitorConfig` | — | Override monitor config (project/environment come from `project` prop by default) |
+| `debug` | `boolean` | `true` | Debug panel — `Cmd+D` or `?debug=1` to open |
+**Included automatically:**
+- ThemeProvider, TooltipProvider, SWRConfig, DialogProvider
+- AuthProvider + AuthDialog
+- AnalyticsProvider, CentrifugoProvider, PwaProvider
+- ErrorTrackingProvider, ErrorBoundary
+- MonitorProvider (auto-enabled via `project` prop)
+- DebugButton from `@djangocfg/debuger` (disable with `debug={false}`)
+- NextTopLoader, Toaster
+## AppLayout
+Smart layout router — selects layout based on current route. Wraps `BaseApp`, accepts all its props.
 ```tsx
 import { AppLayout } from '@djangocfg/layouts';
@@ -69,32 +82,20 @@ import { PublicLayout } from './_layouts/PublicLayout';
 import { PrivateLayout } from './_layouts/PrivateLayout';
 import { AdminLayout } from './_layouts/AdminLayout';
-// app/layout.tsx
 export default function RootLayout({ children }) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body>
         <AppLayout
-          // Provider configs (passed to BaseApp)
+          project="my-app"
           theme={{ defaultTheme: 'system' }}
-          analytics={{ googleTrackingId: 'G-XXXXXXXXXX' }}
-          pwaInstall={{ enabled: true }}
-          // Layout components
-          publicLayout={{
-            component: PublicLayout,
-            enabledPath: ['/', '/legal', '/contact']
-          }}
-          privateLayout={{
-            component: PrivateLayout,
-            enabledPath: ['/dashboard', '/profile']
-          }}
-          adminLayout={{
-            component: AdminLayout,
-            enabledPath: '/admin'
-          }}
-          // Skip layout for fullscreen pages (providers still applied)
+          auth={{ apiUrl: process.env.NEXT_PUBLIC_API_URL }}
+          debug={true}
+          publicLayout={{ component: PublicLayout, enabledPath: ['/', '/legal', '/contact'] }}
+          privateLayout={{ component: PrivateLayout, enabledPath: ['/dashboard', '/profile'] }}
+          adminLayout={{ component: AdminLayout, enabledPath: '/admin' }}
           noLayoutPaths={['/private/terminal', '/embed']}
         >
           {children}
@@ -105,709 +106,163 @@ export default function RootLayout({ children }) {
 }
 ```
-**Monitor prop** — pass `monitor` to enable frontend error monitoring (installs `window.monitor` in DevTools):
-```tsx
-<AppLayout
-  monitor={{
-    project: 'my-app',
-    environment: process.env.NODE_ENV,
-  }}
-  // ...
->
-  {children}
-</AppLayout>
-```
-After mount, `window.monitor.error(...)`, `.warn(...)`, `.flush()`, `.status()` are available in the browser console.
 **Layout priority:** Admin → Private → Public → Fallback
-**noLayoutPaths:** Paths that render without any layout wrapper. Useful for fullscreen pages (terminal, embed, print). Providers (auth, theme, centrifugo) are still applied.
-## Layouts
-Simple, props-based layout components. No complex configs needed!
+**`noLayoutPaths`** — render without layout wrapper (providers still active). Useful for fullscreen pages.
-### Available Layouts
+### i18n
 ```tsx
-import { PublicLayout, PrivateLayout, AuthLayout } from '@djangocfg/layouts';
+import { useLocaleSwitcher } from '@djangocfg/nextjs/i18n/client';
-// Public page
-<PublicLayout
-  logo="/logo.svg"
-  siteName="My App"
-  navigation={navItems}
->
-  {children}
-</PublicLayout>
-// Private page
-<PrivateLayout
-  sidebar={{
-    groups: [
-      { label: 'Main', items: menuItems }
-    ]
-  }}
-  header={{ title: 'Dashboard' }}
->
-  {children}
-</PrivateLayout>
+const { locale, locales, changeLocale } = useLocaleSwitcher();
-// Auth page
-<AuthLayout
-  logo="/logo.svg"
-  title="Sign In"
-  subtitle="Welcome back"
+<AppLayout
+  i18n={{ locale, locales, onLocaleChange: changeLocale }}
 >
-  <LoginForm />
-</AuthLayout>
+  {children}
+</AppLayout>
 ```
-| Layout | Description |
-|--------|-------------|
-| `BaseApp` | Core providers wrapper (Theme, Auth, SWR, ErrorTracking, Toaster) |
-| `AppLayout` | Smart layout router with route-based layout switching |
-| `PublicLayout` | Public pages (home, docs, contact, legal) |
-| `PrivateLayout` | Authenticated user pages (dashboard, profile) |
-| `AuthLayout` | Authentication pages (login, signup, password reset) |
-| `AdminLayout` | Admin panel layout |
-| `ProfileLayout` | User profile pages |
-### i18n Support
-Pass `i18n` config to AppLayout for locale switching in all layouts:
+## Built-in Layouts
 ```tsx
-import { AppLayout } from '@djangocfg/layouts';
-import { useLocaleSwitcher } from '@djangocfg/nextjs/i18n/client';
-function RootLayout({ children }) {
-  const { locale, locales, changeLocale } = useLocaleSwitcher();
-  return (
-    <AppLayout
-      // ... other configs
-      i18n={{
-        locale,
-        locales,
-        onLocaleChange: changeLocale,
-      }}
-    >
-      {children}
-    </AppLayout>
-  );
-}
+import { PublicLayout, PrivateLayout, AuthLayout, AdminLayout, ProfileLayout } from '@djangocfg/layouts';
 ```
-The `LocaleSwitcher` component will automatically appear in PublicLayout and PrivateLayout headers.
-### LocaleSwitcher Component
+| Layout | Description |
+|--------|-------------|
+| `PublicLayout` | Public pages with nav (home, docs, contact, legal) |
+| `PrivateLayout` | Authenticated pages with sidebar |
+| `AuthLayout` | OTP + OAuth + 2FA authentication flow |
+| `AdminLayout` | Admin panel |
+| `ProfileLayout` | User profile with 2FA management |
-A presentational locale switcher component that can be used standalone:
+### AuthLayout
 ```tsx
-import { LocaleSwitcher } from '@djangocfg/layouts';
-// Basic usage (pass locale data via props)
-<LocaleSwitcher
-  locale="en"
-  locales={['en', 'ru', 'ko']}
-  onChange={(locale) => router.push(`/${locale}`)}
-/>
-// With custom labels and styling
-<LocaleSwitcher
-  locale={currentLocale}
-  locales={['en', 'ru', 'ko']}
-  onChange={handleLocaleChange}
-  labels={{ en: 'English', ru: 'Русский', ko: '한국어' }}
-  variant="outline"
-  size="sm"
-  showIcon={true}
+<AuthLayout
+  sourceUrl="https://example.com"
+  redirectUrl="/dashboard"
+  logoUrl="/logo.svg"
+  enableGithubAuth={true}
+  termsUrl="/terms"
+  privacyUrl="/privacy"
 />
 ```
-**Props:**
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `locale` | `string` | - | Current locale code |
-| `locales` | `string[]` | - | Available locale codes |
-| `onChange` | `(locale: string) => void` | - | Callback when locale changes |
-| `labels` | `Record<string, string>` | Built-in | Custom labels for locales |
-| `showCode` | `boolean` | `false` | Show locale code with label |
-| `variant` | `'ghost' \| 'outline' \| 'default'` | `'ghost'` | Button variant |
-| `size` | `'sm' \| 'default' \| 'lg' \| 'icon'` | `'sm'` | Button size |
-| `showIcon` | `boolean` | `true` | Show globe icon |
-| `className` | `string` | - | Custom CSS class |
-> **Smart version:** For automatic locale detection with next-intl hooks, use `@djangocfg/nextjs/i18n/components` which wraps this component.
-> **Extension Layouts:** Additional layouts like `SupportLayout` and `PaymentsLayout` are available in extension packages:
-> - `@djangocfg/ext-support` - Support ticket layouts
-> - `@djangocfg/ext-payments` - Payment flow layouts
-## Analytics
-Google Analytics integration via `react-ga4`. Auto-tracks pageviews and user sessions.
-### Setup
-Add tracking ID to your config:
+### ProfileLayout
 ```tsx
-// appLayoutConfig.ts
-export const appLayoutConfig: AppLayoutConfig = {
-  // ...
-  analytics: {
-    googleTrackingId: 'G-XXXXXXXXXX',
-  },
-};
+<ProfileLayout
+  enable2FA={true}
+  showMemberSince={true}
+/>
 ```
-Analytics is automatically initialized by `AppLayout`. Works only in production (`NODE_ENV === 'production'`).
+## Monitor & Debug
-### Usage
+Both are auto-enabled via `project` prop — no extra config needed.
 ```tsx
-import { useAnalytics, Analytics, AnalyticsEvent, AnalyticsCategory } from '@djangocfg/layouts';
-// In React components - auto-tracks pageviews
-const { event, isEnabled } = useAnalytics();
-event(AnalyticsEvent.THEME_CHANGE, {
-  category: AnalyticsCategory.ENGAGEMENT,
-  label: 'dark',
-});
-// Outside React (utilities, handlers)
-Analytics.event('button_click', { category: 'engagement', label: 'signup' });
-Analytics.setUser('user-123');
+// Monitor auto-starts, window.monitor available in DevTools:
+window.monitor.error('Something broke', { context: 'checkout' })
+window.monitor.warn('Slow response', { ms: 2500 })
+window.monitor.flush()   // send buffer immediately
+window.monitor.status()  // show current state
 ```
-### Predefined Events
-| Category | Events |
-|----------|--------|
-| **Auth** | `AUTH_LOGIN_SUCCESS`, `AUTH_LOGOUT`, `AUTH_SESSION_EXPIRED`, `AUTH_TOKEN_REFRESH` |
-| **OAuth** | `AUTH_OAUTH_START`, `AUTH_OAUTH_SUCCESS`, `AUTH_OAUTH_FAIL` |
-| **Error** | `ERROR_BOUNDARY`, `ERROR_API`, `ERROR_VALIDATION`, `ERROR_NETWORK` |
-| **Navigation** | `NAV_ADMIN_ENTER`, `NAV_DASHBOARD_ENTER`, `NAV_PAGE_VIEW` |
-| **Engagement** | `THEME_CHANGE`, `SIDEBAR_TOGGLE`, `MOBILE_MENU_OPEN` |
-### Auto-tracking
-Built-in tracking for:
-- **Page views** - on every route change
-- **User ID** - automatically set when user is authenticated
-- **Auth events** - login, logout, session expiry (from `@djangocfg/api`)
-- **OAuth events** - GitHub OAuth start, success, failure
-- **Errors** - React ErrorBoundary errors
-## PWA Installation
-Enable PWA installation prompts with `pwaInstall` config:
+Override monitor defaults:
 ```tsx
-import { BaseApp } from '@djangocfg/layouts';
 <BaseApp
-  pwaInstall={{
-    enabled: true,
-    showInstallHint: true,      // Show A2HS hint
-    resetAfterDays: 3,           // Re-show after dismissal
-    delayMs: 1000,               // Delay before showing
-    logo: '/logo192.png',        // PWA logo
-    resumeLastPage: true,        // Resume last page on PWA launch
-  }}
+  project="my-app"
+  monitor={{ baseUrl: 'https://api.example.com', captureConsole: false }}
 >
-  {children}
-</BaseApp>
 ```
-**Features:**
-- **A2HSHint** - Platform-specific install hints (iOS Safari/Chrome/Firefox, Android Chrome, Desktop)
-- **Page Resume** - Automatically navigate to last viewed page when PWA is launched
-- **Auto-detection** - Detects if running as PWA
-- **Dismissal tracking** - Respects user dismissal with localStorage
-- **Custom timing** - Configurable delay and reset periods
+Debug panel: `Cmd+D` or `?debug=1` in URL. Disable: `debug={false}`.
-**Page Resume:**
-When `resumeLastPage: true`, the app saves the current pathname on every navigation and restores it when the PWA is launched. Pages like `/auth`, `/login`, `/error` are automatically excluded. Data expires after 24 hours.
-### Usage
+## Error Tracking
 ```tsx
-import { usePwa } from '@djangocfg/layouts/snippets';
-// PWA status
-const { isPWA, isInstallable } = usePwa();
-```
+import { useErrorEmitter, emitRuntimeError } from '@djangocfg/layouts';
-## Snippets
+// In components
+const { emitError } = useErrorEmitter('MyComponent');
+emitError('Something failed', error);
-Reusable UI components and hooks ready to use.
-```tsx
-import {
-  Breadcrumbs,
-  AuthDialog,
-  usePwa,
-} from '@djangocfg/layouts/snippets';
+// Outside React
+emitRuntimeError('MyUtil', 'Operation failed', error);
 ```
-| Snippet | Description |
-|---------|-------------|
-| `Breadcrumbs` | Navigation breadcrumbs with automatic path generation |
-| `AuthDialog` | Auth modal (login/register) with event-based triggers |
-| `AnalyticsProvider` | Analytics wrapper component |
-| `usePwa` | PWA status hook (isPWA, isInstallable, etc.) |
-| `usePWAPageResume` | Resume last page on PWA launch |
-| `A2HSHint` | Add to Home Screen hint component |
-| `PWAPageResumeManager` | Component for PWA page resume (use via BaseApp config) |
-> **Extension Snippets:** Additional components are available in extension packages:
-> - `@djangocfg/ext-leads` - ContactForm, ContactPage, ContactInfo
-> - `@djangocfg/ext-knowbase` - KnowledgeChat, ChatWidget, ChatUIProvider
-> - `@djangocfg/ext-newsletter` - Hero (with newsletter subscription)
-### Breadcrumbs
-```tsx
-import Breadcrumbs from '@djangocfg/layouts/snippets';
-// Auto-generate from current path
-<Breadcrumbs />
-// Or provide custom items
-<Breadcrumbs
-  items={[
-    { path: '/', label: 'Home', isActive: false },
-    { path: '/products', label: 'Products', isActive: true },
-  ]}
-/>
-```
-### AuthDialog
-```tsx
-import { AuthDialog, openAuthDialog } from '@djangocfg/layouts/snippets';
-// Add to layout
-<AuthDialog authPath="/auth" />
-// Trigger from anywhere
-openAuthDialog({ message: 'Sign in to continue' });
-```
-## Components
-Utility components organized by category.
-### Core Components
-```tsx
-import {
-  JsonLd,
-  LucideIcon,
-  PageProgress,
-  Suspense
-} from '@djangocfg/layouts/components/core';
-```
-| Component | Description |
-|-----------|-------------|
-| `JsonLd` | JSON-LD structured data component |
-| `LucideIcon` | Lucide icon wrapper component |
-| `PageProgress` | Page loading progress indicator |
-| `Suspense` | Suspense wrapper component |
-### Error Components
+## Error Pages
 ```tsx
-import {
-  ErrorBoundary,
-  ErrorLayout,
-  getErrorContent,
-  ERROR_CODES
-} from '@djangocfg/layouts/components/errors';
-```
-| Component | Description |
-|-----------|-------------|
-| `ErrorBoundary` | React error boundary component |
-| `ErrorLayout` | Reusable error page layout (404, 500, etc.) |
-| `getErrorContent` | Get error content by status code |
-| `ERROR_CODES` | Common HTTP error code constants |
-**ErrorLayout Usage:**
-```tsx
-// app/not-found.tsx
 import { ErrorLayout } from '@djangocfg/layouts/components/errors';
+// app/not-found.tsx
 export default function NotFound() {
   return <ErrorLayout code={404} supportEmail="support@example.com" />;
 }
+```
-// app/error.tsx
-'use client';
-import { ErrorLayout } from '@djangocfg/layouts/components/errors';
+## PWA
-export default function Error({ error, reset }) {
-  return <ErrorLayout code={500} supportEmail="support@example.com" />;
-}
+```tsx
+<BaseApp
+  pwaInstall={{
+    enabled: true,
+    showInstallHint: true,
+    logo: '/logo192.png',
+    delayMs: 3000,
+    resetAfterDays: 7,
+    resumeLastPage: true,
+  }}
+>
 ```
-### Redirect Component
+## Redirect
 ```tsx
 import { RedirectPage } from '@djangocfg/layouts/components/RedirectPage';
-// app/page.tsx
 export default function Page() {
-  return (
-    <RedirectPage
-      authenticatedPath="/dashboard"
-      unauthenticatedPath="/auth"
-      loadingText="Loading..."
-    />
-  );
+  return <RedirectPage authenticatedPath="/dashboard" unauthenticatedPath="/auth" />;
 }
 ```
-### Error Tracking
+## Legal Pages
 ```tsx
-import {
-  ErrorTrackingProvider,
-  useErrors,
-  useErrorEmitter,
-  emitRuntimeError,
-} from '@djangocfg/layouts';
-// Wrap your app
-<ErrorTrackingProvider>
-  <YourApp />
-</ErrorTrackingProvider>
-// In React components - use hook
-function MyComponent() {
-  const { emitError } = useErrorEmitter('MyComponent');
-  try {
-    doSomething();
-  } catch (error) {
-    emitError('Something failed', error);
-  }
-}
-// Outside React (utilities, libraries) - use standalone function
-import { emitRuntimeError } from '@djangocfg/layouts';
+import { PrivacyPage, TermsPage, CookiesPage, SecurityPage } from '@djangocfg/layouts/pages/legal';
-try {
-  doSomething();
-} catch (error) {
-  emitRuntimeError('MyUtility', 'Something failed', error);
-}
-// Access errors
-const { errors, clearErrors } = useErrors();
-```
-### Update Notifier
-```tsx
-import { UpdateNotifier } from '@djangocfg/layouts/components/UpdateNotifier';
-<UpdateNotifier />
-```
-## Pages
-Ready-to-use page components.
-### Legal Pages
-Pre-built legal page components with default configurations.
-```tsx
-import {
-  PrivacyPage,
-  TermsPage,
-  CookiesPage,
-  SecurityPage
-} from '@djangocfg/layouts/pages/legal';
-// app/legal/privacy/page.tsx
 export default PrivacyPage;
-// Or customize
-import { PrivacyPage, privacyConfig } from '@djangocfg/layouts/pages/legal';
-export default function CustomPrivacy() {
-  return <PrivacyPage config={{
-    ...privacyConfig,
-    lastUpdated: '2024-01-01',
-  }} />;
-}
 ```
-| Page | Description |
-|------|-------------|
-| `PrivacyPage` | Privacy policy page |
-| `TermsPage` | Terms of service page |
-| `CookiesPage` | Cookie policy page |
-| `SecurityPage` | Security policy page |
-## Utils
-Utility functions and helpers.
-```tsx
-import {
-  generateOgImageUrl,
-  getAbsoluteOgImageUrl,
-  createOgImageUrlBuilder
-} from '@djangocfg/layouts/utils/og-image';
-// Generate OG image URL
-const ogUrl = generateOgImageUrl('/api/og', {
-  title: 'My Page',
-  description: 'Page description',
-  siteName: 'My Site',
-});
-```
-| Utility | Description |
-|---------|-------------|
-| `generateOgImageUrl` | Generate OG image URL with base64 encoding |
-| `getAbsoluteOgImageUrl` | Get absolute OG image URL |
-| `createOgImageUrlBuilder` | Create OG image URL builder with defaults |
 ## Exports
 | Path | Content |
 |------|---------|
-| `@djangocfg/layouts` | Main exports (all modules) |
+| `@djangocfg/layouts` | All exports |
 | `@djangocfg/layouts/layouts` | Layout components |
-| `@djangocfg/layouts/snippets` | Reusable components + Analytics |
-| `@djangocfg/layouts/components` | All utility components |
-| `@djangocfg/layouts/pages` | Page components (legal pages) |
-| `@djangocfg/layouts/pages/legal` | Legal page components |
-| `@djangocfg/layouts/utils` | Utilities (og-image, logger) |
+| `@djangocfg/layouts/snippets` | Reusable components |
+| `@djangocfg/layouts/components` | Utility components |
+| `@djangocfg/layouts/pages/legal` | Legal pages |
+| `@djangocfg/layouts/utils` | OG image utils |
 | `@djangocfg/layouts/styles` | CSS |
-| `@djangocfg/layouts/styles/dashboard` | Dashboard-specific CSS |
-> **Auth Exports:** For authentication, use `@djangocfg/api/auth` - See [@djangocfg/api documentation](../api/README.md)
+| `@djangocfg/layouts/styles/dashboard` | Dashboard CSS |
 ## Extension Packages
-Additional functionality is available in extension packages:
-| Extension | Package | Description |
-|-----------|---------|-------------|
-| **Newsletter** | `@djangocfg/ext-newsletter` | Newsletter subscription and campaigns |
-| **Knowledge Base** | `@djangocfg/ext-knowbase` | Documentation, chat, RAG-powered AI |
-| **Leads** | `@djangocfg/ext-leads` | Lead capture and contact forms |
-| **Payments** | `@djangocfg/ext-payments` | Payment processing and subscriptions |
-| **Support** | `@djangocfg/ext-support` | Support tickets and helpdesk |
-Each extension has its own layouts, contexts, and components. See individual extension documentation for details.
-## Requirements
-- Next.js >= 15
-- React >= 19
-- Tailwind CSS >= 4
-- react-ga4 (bundled)
-- @djangocfg/ui-nextjs (peer dependency)
-- @djangocfg/api (peer dependency)
-## Philosophy
-This package follows a **simple, props-based approach**:
-- ✅ **No complex configs** - just pass props
-- ✅ **Type-safe** - full TypeScript support
-- ✅ **Flexible** - compose layouts as needed
-- ✅ **Production-ready** - built for real apps
-- ✅ **Modular** - core layouts in one package, extensions separate
-## Examples
-### Complete App Setup
-```tsx
-// app/layout.tsx
-import { AppLayout } from '@djangocfg/layouts';
-import { appLayoutConfig } from './_config/appLayoutConfig';
-export default function RootLayout({ children }) {
-  return (
-    <AppLayout config={appLayoutConfig}>
-      {children}
-    </AppLayout>
-  );
-}
-```
-### Public Page
-```tsx
-// app/page.tsx
-import { PublicLayout } from '@djangocfg/layouts';
-export default function HomePage() {
-  return (
-    <PublicLayout
-      logo="/logo.svg"
-      siteName="My App"
-      navigation={[
-        { label: 'Home', href: '/' },
-        { label: 'Docs', href: '/docs' },
-        { label: 'Contact', href: '/contact' }
-      ]}
-    >
-      <h1>Welcome</h1>
-    </PublicLayout>
-  );
-}
-```
-### Private Dashboard
-```tsx
-// app/dashboard/page.tsx
-import { PrivateLayout } from '@djangocfg/layouts';
-export default function DashboardPage() {
-  return (
-    <PrivateLayout
-      sidebar={{
-        groups: [
-          {
-            label: 'Main',
-            items: [
-              { label: 'Dashboard', href: '/dashboard', icon: 'LayoutDashboard' },
-              { label: 'Settings', href: '/settings', icon: 'Settings' }
-            ]
-          }
-        ],
-        homeHref: '/dashboard'
-      }}
-      header={{ title: 'Dashboard' }}
-    >
-      <h1>Dashboard</h1>
-    </PrivateLayout>
-  );
-}
-```
-### Auth Page (OTP + 2FA Authentication)
-```tsx
-// app/auth/page.tsx
-'use client';
-import { AuthLayout } from '@djangocfg/layouts';
-export default function AuthPage() {
-  return (
-    <AuthLayout
-      sourceUrl="https://example.com"
-      supportUrl="/support"
-      termsUrl="/terms"
-      privacyUrl="/privacy"
-      enablePhoneAuth={false}
-      enableGithubAuth={true}
-      logoUrl="/logo.svg"
-      redirectUrl="/dashboard"
-      onOTPSuccess={() => {
-        console.log('Authentication successful');
-      }}
-      onOAuthSuccess={(user, isNewUser, provider) => {
-        console.log('OAuth success:', { user, isNewUser, provider });
-      }}
-    >
-      <div className="text-center mb-6">
-        <h2 className="text-2xl font-bold">Welcome to My App</h2>
-        <p className="text-muted-foreground mt-2">
-          Sign in with your email or phone
-        </p>
-      </div>
-    </AuthLayout>
-  );
-}
-```
-**Authentication Flow:**
-1. **Identifier** → Enter email/phone or click GitHub OAuth
-2. **OTP** → Enter 6-digit verification code
-3. **2FA** → Enter TOTP code (if 2FA enabled for user)
-4. **Success** → Show logo animation, then redirect
-**AuthLayout Props:**
-| Prop | Type | Description |
-|------|------|-------------|
-| `sourceUrl` | `string` | Application URL for OTP emails |
-| `redirectUrl` | `string` | URL to redirect after successful auth (default: `/dashboard`) |
-| `logoUrl` | `string` | Logo URL for success screen (SVG recommended) |
-| `enablePhoneAuth` | `boolean` | Enable phone number authentication |
-| `enableGithubAuth` | `boolean` | Enable GitHub OAuth |
-| `enable2FASetup` | `boolean` | Enable 2FA setup prompt after login (default: `true`). Set to `false` to skip 2FA setup prompt - users can then configure 2FA from ProfileLayout instead. |
-| `termsUrl` | `string` | Terms of service URL (shows checkbox if provided) |
-| `privacyUrl` | `string` | Privacy policy URL |
-| `supportUrl` | `string` | Support page URL |
-| `onOTPSuccess` | `() => void` | Callback after successful authentication |
-| `onOAuthSuccess` | `(user, isNewUser, provider) => void` | Callback after successful OAuth |
-| `onError` | `(message: string) => void` | Error callback |
-### Profile Page (with 2FA Management)
-```tsx
-// app/profile/page.tsx
-'use client';
-import { ProfileLayout } from '@djangocfg/layouts';
-export default function ProfilePage() {
-  return (
-    <ProfileLayout
-      title="Profile Settings"
-      description="Manage your account"
-      enable2FA={true}  // Show 2FA management section
-      showMemberSince={true}
-      showLastLogin={true}
-      onUnauthenticated={() => {
-        // Redirect to login
-      }}
-    />
-  );
-}
-```
-**ProfileLayout Props:**
-| Prop | Type | Description |
-|------|------|-------------|
-| `title` | `string` | Page title (default: "Profile Settings") |
-| `description` | `string` | Page description |
-| `enable2FA` | `boolean` | Show 2FA management section (default: `false`). When enabled, users can enable/disable Two-Factor Authentication from their profile. |
-| `showMemberSince` | `boolean` | Show member since date (default: `true`) |
-| `showLastLogin` | `boolean` | Show last login date (default: `true`) |
-| `onUnauthenticated` | `() => void` | Callback when user is not authenticated |
-**2FA Configuration Strategy:**
-- Use `enable2FASetup={false}` in AuthLayout to skip post-login 2FA setup prompt
-- Use `enable2FA={true}` in ProfileLayout to allow users to manage 2FA from settings
-- This gives users control over when to enable 2FA instead of forcing it during login
+| Package | Description |
+|---------|-------------|
+| `@djangocfg/ext-newsletter` | Newsletter subscription |
+| `@djangocfg/ext-knowbase` | Knowledge base + AI chat |
+| `@djangocfg/ext-leads` | Lead capture forms |
+| `@djangocfg/ext-payments` | Payments & subscriptions |
+| `@djangocfg/ext-support` | Support tickets |
 ## License
-MIT
-## Links
-- [DjangoCFG Documentation](https://djangocfg.com)
-- [GitHub](https://github.com/markolofsen/django-cfg)
+MIT — [DjangoCFG](https://djangocfg.com) · [GitHub](https://github.com/markolofsen/django-cfg)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.218",
+  "version": "2.1.221",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -74,13 +74,13 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.218",
-    "@djangocfg/centrifugo": "^2.1.218",
-    "@djangocfg/i18n": "^2.1.218",
-    "@djangocfg/monitor": "^2.1.218",
-    "@djangocfg/ui-core": "^2.1.218",
-    "@djangocfg/ui-nextjs": "^2.1.218",
-    "@djangocfg/ui-tools": "^2.1.218",
+    "@djangocfg/api": "^2.1.221",
+    "@djangocfg/centrifugo": "^2.1.221",
+    "@djangocfg/i18n": "^2.1.221",
+    "@djangocfg/monitor": "^2.1.221",
+    "@djangocfg/ui-core": "^2.1.221",
+    "@djangocfg/ui-nextjs": "^2.1.221",
+    "@djangocfg/ui-tools": "^2.1.221",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -102,20 +102,21 @@
     }
   },
   "dependencies": {
+    "@djangocfg/debuger": "^2.1.221",
     "nextjs-toploader": "^3.9.17",
     "qrcode.react": "^4.2.0",
     "react-ga4": "^2.1.0",
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.218",
-    "@djangocfg/i18n": "^2.1.218",
-    "@djangocfg/centrifugo": "^2.1.218",
-    "@djangocfg/monitor": "^2.1.218",
-    "@djangocfg/typescript-config": "^2.1.218",
-    "@djangocfg/ui-core": "^2.1.218",
-    "@djangocfg/ui-nextjs": "^2.1.218",
-    "@djangocfg/ui-tools": "^2.1.218",
+    "@djangocfg/api": "^2.1.221",
+    "@djangocfg/i18n": "^2.1.221",
+    "@djangocfg/centrifugo": "^2.1.221",
+    "@djangocfg/monitor": "^2.1.221",
+    "@djangocfg/typescript-config": "^2.1.221",
+    "@djangocfg/ui-core": "^2.1.221",
+    "@djangocfg/ui-nextjs": "^2.1.221",
+    "@djangocfg/ui-tools": "^2.1.221",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/layouts/AppLayout/AppLayout.tsx CHANGED Viewed

@@ -91,6 +91,9 @@ interface LayoutConfig {
 export interface AppLayoutProps {
   children: ReactNode;
+  /** Project name — used as default for monitor.project and debug panel title */
+  project?: string;
   /** Public layout component with enabled paths */
   publicLayout?: LayoutConfig;
@@ -139,6 +142,9 @@ export interface AppLayoutProps {
   /** Monitor configuration — initialises window.monitor + auto-captures JS errors & console */
   monitor?: MonitorConfig;
+  /** Debug panel — set false to disable. Default: true */
+  debug?: boolean;
 }
 /**
@@ -251,6 +257,7 @@ function AppLayoutContent({
  */
 export function AppLayout(props: AppLayoutProps) {
   const {
+    project,
     theme,
     auth,
     analytics,
@@ -261,10 +268,12 @@ export function AppLayout(props: AppLayoutProps) {
     mcpChat,
     pwaInstall,
     monitor,
+    debug,
   } = props;
   return (
     <BaseApp
+      project={project}
       theme={theme}
       auth={auth}
       analytics={analytics}
@@ -275,6 +284,7 @@ export function AppLayout(props: AppLayoutProps) {
       mcpChat={mcpChat}
       pwaInstall={pwaInstall}
       monitor={monitor}
+      debug={debug}
     >
       <AppLayoutContent {...props} />
     </BaseApp>

package/src/layouts/AppLayout/BaseApp.tsx CHANGED Viewed

@@ -57,12 +57,19 @@ import { A2HSHint, PWAPageResumeManager, PwaProvider } from '../../snippets/PWAI
 import type { BaseLayoutProps } from '../types/layout.types';
+// Lazy load DebugButton from @djangocfg/debuger
+const DebugButton = dynamic(
+  () => import('@djangocfg/debuger').then(mod => ({ default: mod.DebugButton })),
+  { ssr: false }
+);
 // Lazy load MCP Chat Widget with dynamic import
 const AIChatWidget = dynamic(
   () => import('../../snippets/McpChat/components/AIChatWidget').then(mod => ({ default: mod.AIChatWidget })),
   { ssr: false }
 );
 // For backwards compatibility, re-export as BaseAppProps
 export type BaseAppProps = BaseLayoutProps;
@@ -76,6 +83,7 @@ export type BaseAppProps = BaseLayoutProps;
  */
 export function BaseApp({
   children,
+  project,
   theme,
   auth,
   analytics,
@@ -86,6 +94,7 @@ export function BaseApp({
   mcpChat,
   pwaInstall,
   monitor,
+  debug,
 }: BaseAppProps) {
   // ErrorBoundary is enabled by default
   const enableErrorBoundary = errorBoundary?.enabled !== false;
@@ -98,6 +107,13 @@ export function BaseApp({
   const centrifugoUrl = centrifugo?.url || process.env.NEXT_PUBLIC_CENTRIFUGO_URL;
   const centrifugoEnabled = centrifugo?.enabled !== false;
+  // Monitor — project prop as default, override with monitor config
+  const monitorConfig = {
+    project,
+    environment: process.env.NODE_ENV,
+    ...monitor,
+  };
   const content = (
     <ThemeProvider
       defaultTheme={theme?.defaultTheme || 'system'}
@@ -130,7 +146,7 @@ export function BaseApp({
                     network={errorTracking?.network}
                     onError={errorTracking?.onError}
                   >
-                    {monitor && <MonitorProvider {...monitor} />}
+                    <MonitorProvider {...monitorConfig} />
                     {children}
                     <NextTopLoader
                       color="hsl(var(--primary))"
@@ -171,6 +187,9 @@ export function BaseApp({
                     {/* Auth Dialog - global auth prompt */}
                     <AuthDialog authPath={auth?.routes?.auth} />
+                    {/* Debug Panel — enabled by default, disable with debug={false} */}
+                    {debug !== false && <DebugButton />}
                   </ErrorTrackingProvider>
                 </PwaProvider>
               </CentrifugoProvider>

package/src/layouts/types/layout.types.ts CHANGED Viewed

@@ -29,6 +29,9 @@ import type { MonitorConfig } from '@djangocfg/monitor';
 export interface BaseLayoutProps {
   children: ReactNode;
+  /** Project name — used as default for monitor.project and debug panel title */
+  project?: string;
   /** Theme configuration */
   theme?: ThemeConfig;
@@ -58,4 +61,7 @@ export interface BaseLayoutProps {
   /** Monitor configuration — initialises window.monitor + auto-captures JS errors & console */
   monitor?: MonitorConfig;
+  /** Debug panel — set false to disable. Default: true */
+  debug?: boolean;
 }