npm - @djangocfg/layouts - Versions diffs - 2.1.37 → 2.1.39 - Mend

@djangocfg/layouts 2.1.37 → 2.1.39

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 (77) hide show

package/README.md CHANGED Viewed

@@ -24,7 +24,17 @@ export default function RootLayout({ children }) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body>
-        <BaseApp theme={{ defaultTheme: 'dark' }}>
+        <BaseApp
+          theme={{ defaultTheme: 'dark' }}
+          analytics={{ googleTrackingId: 'G-XXXXXXXXXX' }}
+          centrifugo={{ enabled: true, url: process.env.NEXT_PUBLIC_CENTRIFUGO_URL }}
+          pwaInstall={{ enabled: true, showInstallHint: true }}
+          pushNotifications={{
+            enabled: true,
+            vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_KEY || ''
+          }}
+          mcpChat={{ enabled: true, autoDetectEnvironment: true }}
+        >
           {children}
         </BaseApp>
       </body>
@@ -34,12 +44,23 @@ export default function RootLayout({ children }) {
 ```
 **Included providers:**
-- ThemeProvider (light/dark/system)
-- TooltipProvider
-- SWRConfig
-- AuthProvider (from `@djangocfg/api`)
-- ErrorTrackingProvider
-- Toaster + PageProgress
+- **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)
+- **DjangoPushProvider** - Django web push integration with history (optional)
+- **ErrorTrackingProvider** - Error handling and tracking
+- **ErrorBoundary** - React error boundary
+- **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)
+- **PushPrompt** - Push notification prompt (if enabled)
 > **Note:** Auth functionality is provided by `@djangocfg/api` package. See [@djangocfg/api documentation](../api/README.md) for auth usage.
@@ -51,6 +72,7 @@ Smart layout router built on BaseApp - automatically selects layout based on rou
 import { AppLayout } from '@djangocfg/layouts';
 import { PublicLayout } from './_layouts/PublicLayout';
 import { PrivateLayout } from './_layouts/PrivateLayout';
+import { AdminLayout } from './_layouts/AdminLayout';
 // app/layout.tsx
 export default function RootLayout({ children }) {
@@ -58,6 +80,16 @@ export default function RootLayout({ children }) {
     <html lang="en" suppressHydrationWarning>
       <body>
         <AppLayout
+          // Provider configs (passed to BaseApp)
+          theme={{ defaultTheme: 'system' }}
+          analytics={{ googleTrackingId: 'G-XXXXXXXXXX' }}
+          pwaInstall={{ enabled: true }}
+          pushNotifications={{
+            enabled: true,
+            vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_KEY || ''
+          }}
+          // Layout components
           publicLayout={{
             component: PublicLayout,
             enabledPath: ['/', '/legal', '/contact']
@@ -66,7 +98,10 @@ export default function RootLayout({ children }) {
             component: PrivateLayout,
             enabledPath: ['/dashboard', '/profile']
           }}
-          theme={{ defaultTheme: 'system' }}
+          adminLayout={{
+            component: AdminLayout,
+            enabledPath: '/admin'
+          }}
         >
           {children}
         </AppLayout>
@@ -185,14 +220,131 @@ Built-in tracking for:
 - **OAuth events** - GitHub OAuth start, success, failure
 - **Errors** - React ErrorBoundary errors
+## PWA & Push Notifications
+Progressive Web App features and Web Push notifications support.
+### PWA Installation
+Enable PWA installation prompts with `pwaInstall` config:
+```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
+  }}
+>
+  {children}
+</BaseApp>
+```
+**Features:**
+- **A2HSHint** - Platform-specific install hints (iOS Safari, Android Chrome, Desktop)
+- **Auto-detection** - Detects if running as PWA
+- **Dismissal tracking** - Respects user dismissal with localStorage
+- **Custom timing** - Configurable delay and reset periods
+### Push Notifications
+Enable Web Push notifications with `pushNotifications` config:
+```tsx
+import { BaseApp } from '@djangocfg/layouts';
+<BaseApp
+  pushNotifications={{
+    enabled: true,
+    vapidPublicKey: process.env.NEXT_PUBLIC_VAPID_KEY || '',
+    subscribeEndpoint: '/api/push/subscribe',  // Backend subscription endpoint
+    requirePWA: true,                          // Only show if installed as PWA
+    autoSubscribe: false,                      // Auto-subscribe on install
+    delayMs: 5000,                             // Delay before showing prompt
+    resetAfterDays: 7,                         // Re-show after dismissal
+  }}
+>
+  {children}
+</BaseApp>
+```
+**Features:**
+- **PushPrompt** - Permission request prompt
+- **VAPID authentication** - Secure push with VAPID keys
+- **Subscription management** - Auto-subscribe and unsubscribe
+- **PWA integration** - Can require PWA installation first
+- **Custom timing** - Configurable delay and reset
+### Usage
+```tsx
+import { usePwa, useDjangoPushContext } from '@djangocfg/layouts/snippets';
+// PWA status
+const { isPWA, isInstallable } = usePwa();
+// Push notifications (Django integration)
+const {
+  isSupported,
+  isSubscribed,
+  permission,
+  pushes,
+  subscribe,
+  unsubscribe,
+  sendPush,
+  clearPushes,
+  removePush,
+} = useDjangoPushContext();
+// Subscribe to push
+await subscribe();
+// Send test notification (via Django API)
+await sendPush({
+  title: 'Hello!',
+  body: 'Test notification',
+  icon: '/icon.png',
+});
+// Manage push history
+clearPushes(); // Clear all
+removePush(pushId); // Remove specific push
+```
+### VAPID Keys Generation
+Generate VAPID keys for push notifications:
+```bash
+# Using web-push CLI
+npx web-push generate-vapid-keys
+# Or use openssl
+openssl ecparam -name prime256v1 -genkey -noout -out vapid_private.pem
+openssl ec -in vapid_private.pem -pubout -out vapid_public.pem
+```
+Add keys to `.env.local`:
+```env
+NEXT_PUBLIC_VAPID_PUBLIC_KEY=your_public_key_here
+VAPID_PRIVATE_KEY=your_private_key_here
+```
 ## Snippets
-Reusable UI components ready to use.
+Reusable UI components and hooks ready to use.
 ```tsx
 import {
   Breadcrumbs,
   AuthDialog,
+  usePwa,
+  useDjangoPushContext,
 } from '@djangocfg/layouts/snippets';
 ```
@@ -201,6 +353,11 @@ import {
 | `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.) |
+| `useDjangoPushContext` | Django push notifications hook (subscribe, send, history) |
+| `usePush` | Generic push hook (for non-Django apps) |
+| `A2HSHint` | Add to Home Screen hint component |
+| `PushPrompt` | Push notification permission prompt |
 > **Extension Snippets:** Additional components are available in extension packages:
 > - `@djangocfg/ext-leads` - ContactForm, ContactPage, ContactInfo
@@ -516,27 +673,56 @@ export default function DashboardPage() {
 }
 ```
-### Auth Page
+### Auth Page (OTP Authentication)
 ```tsx
-// app/auth/login/page.tsx
+// app/auth/page.tsx
+'use client';
 import { AuthLayout } from '@djangocfg/layouts';
-import { LoginForm } from './_components/LoginForm';
-export default function LoginPage() {
+export default function AuthPage() {
   return (
     <AuthLayout
-      logo="/logo.svg"
-      siteName="My App"
-      title="Sign In"
-      subtitle="Welcome back! Please sign in to continue."
+      sourceUrl="https://example.com"
+      supportUrl="/support"
+      termsUrl="/terms"
+      privacyUrl="/privacy"
+      enablePhoneAuth={false}
+      enableGithubAuth={true}
+      redirectUrl="/dashboard"
+      onOTPSuccess={() => {
+        console.log('OTP authentication successful');
+      }}
+      onOAuthSuccess={(user, isNewUser, provider) => {
+        console.log('OAuth success:', { user, isNewUser, provider });
+      }}
     >
-      <LoginForm />
+      <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>
   );
 }
 ```
+**AuthLayout Props:**
+| Prop | Type | Description |
+|------|------|-------------|
+| `sourceUrl` | `string` | Application URL for OTP emails |
+| `redirectUrl` | `string` | URL to redirect after successful auth (default: `/dashboard`) |
+| `enablePhoneAuth` | `boolean` | Enable phone number authentication |
+| `enableGithubAuth` | `boolean` | Enable GitHub OAuth |
+| `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 OTP verification |
+| `onOAuthSuccess` | `(user, isNewUser, provider) => void` | Callback after successful OAuth |
+| `onError` | `(message: string) => void` | Error callback |
 ## License
 MIT

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.37",
+  "version": "2.1.39",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -92,9 +92,9 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.37",
-    "@djangocfg/centrifugo": "^2.1.37",
-    "@djangocfg/ui-nextjs": "^2.1.37",
+    "@djangocfg/api": "^2.1.39",
+    "@djangocfg/centrifugo": "^2.1.39",
+    "@djangocfg/ui-nextjs": "^2.1.39",
     "@hookform/resolvers": "^5.2.0",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -114,7 +114,7 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/typescript-config": "^2.1.37",
+    "@djangocfg/typescript-config": "^2.1.39",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/errors/index.ts CHANGED Viewed

@@ -8,3 +8,12 @@ export type { ErrorLayoutProps } from './ErrorLayout';
 export { getErrorContent, ERROR_CODES } from './errorConfig';
 export type { ErrorContent } from './errorConfig';
+// Configuration types
+export type {
+  ErrorBoundaryConfig,
+  ErrorTrackingConfig,
+  ValidationErrorConfig,
+  CORSErrorConfig,
+  NetworkErrorConfig,
+} from './types';

package/src/components/errors/types.ts ADDED Viewed

@@ -0,0 +1,38 @@
+/**
+ * Error Handling Configuration Types
+ *
+ * Configuration types for ErrorTrackingProvider and ErrorBoundary
+ */
+import type { ErrorInfo } from 'react';
+// Re-export ErrorTrackingConfig from ErrorsTracker
+export type {
+  ErrorTrackingConfig,
+  ValidationErrorConfig,
+  CORSErrorConfig,
+  NetworkErrorConfig,
+  ErrorTypeConfig,
+  ErrorDetail,
+  ValidationErrorDetail,
+  CORSErrorDetail,
+  NetworkErrorDetail,
+  StoredError,
+  ErrorTrackingContextValue,
+} from './ErrorsTracker/types';
+/**
+ * Error Boundary Configuration
+ *
+ * Configuration for React ErrorBoundary component
+ */
+export interface ErrorBoundaryConfig {
+  /** Enable error boundary (default: true) */
+  enabled?: boolean;
+  /** Support email to display in error UI */
+  supportEmail?: string;
+  /** Custom error handler called when error is caught */
+  onError?: (error: Error, errorInfo: ErrorInfo) => void;
+}

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

@@ -38,18 +38,19 @@
 import React, { ReactNode, useMemo } from 'react';
 import { usePathname } from 'next/navigation';
-import { CentrifugoProvider } from '@djangocfg/centrifugo';
-import { getCentrifugoAuthTokenRetrieve } from '@djangocfg/api';
-import { AnalyticsProvider } from '../../snippets/Analytics';
 import { Suspense, ClientOnly } from '../../components/core';
 import { BaseApp } from './BaseApp';
 import type {
   ThemeConfig,
-  LayoutErrorTrackingConfig,
+  AnalyticsConfig,
+  CentrifugoConfig,
+  ErrorTrackingConfig,
   ErrorBoundaryConfig,
   SWRConfigOptions,
   McpChatConfig,
-} from '../shared/types';
+  PwaInstallConfig,
+  PushNotificationsConfig,
+} from '../types';
 import type { AuthConfig } from '@djangocfg/api/auth';
 export type LayoutMode = 'public' | 'private' | 'admin';
@@ -114,19 +115,13 @@ export interface AppLayoutProps {
   auth?: AuthConfig;
   /** Analytics configuration */
-  analytics?: {
-    googleTrackingId?: string;
-  };
+  analytics?: AnalyticsConfig;
   /** Centrifugo configuration */
-  centrifugo?: {
-    enabled?: boolean;
-    autoConnect?: boolean;
-    url?: string;
-  };
+  centrifugo?: CentrifugoConfig;
   /** Error tracking configuration */
-  errorTracking?: LayoutErrorTrackingConfig;
+  errorTracking?: ErrorTrackingConfig;
   /** SWR configuration */
   swr?: SWRConfigOptions;
@@ -136,6 +131,12 @@ export interface AppLayoutProps {
   /** MCP Chat configuration */
   mcpChat?: McpChatConfig;
+  /** PWA Install configuration */
+  pwaInstall?: PwaInstallConfig;
+  /** Push Notifications configuration */
+  pushNotifications?: PushNotificationsConfig;
 }
 /**
@@ -213,52 +214,39 @@ function AppLayoutContent({
     }
   };
-  const layoutContent = renderLayout();
-  // Wrap with providers (order matters!)
-  let content: ReactNode = layoutContent;
-  // Analytics Provider (if enabled)
-  if (analytics?.googleTrackingId) {
-    content = <AnalyticsProvider trackingId={analytics.googleTrackingId}>{content}</AnalyticsProvider>;
-  }
-  // Centrifugo Provider (always wrap, but only enable if configured)
-  // This ensures useCentrifugo() hook works even when Centrifugo is disabled
-  const centrifugoUrl = centrifugo?.url || process.env.NEXT_PUBLIC_CENTRIFUGO_URL;
-  const centrifugoEnabled = centrifugo?.enabled !== false;
-  content = (
-    <CentrifugoProvider
-      enabled={centrifugoEnabled}
-      autoConnect={centrifugoEnabled && centrifugo?.autoConnect}
-      url={centrifugoUrl}
-      onTokenRefresh={async () => {
-        const response = await getCentrifugoAuthTokenRetrieve();
-        return response.token;
-      }}
-    >
-      {content}
-    </CentrifugoProvider>
-  );
-  return content;
+  // No providers here - all providers now in BaseApp
+  return renderLayout();
 }
 /**
  * AppLayout - Main Component with All Providers
  */
 export function AppLayout(props: AppLayoutProps) {
-  const { theme, auth, errorTracking, errorBoundary, swr, mcpChat } = props;
+  const {
+    theme,
+    auth,
+    analytics,
+    centrifugo,
+    errorTracking,
+    errorBoundary,
+    swr,
+    mcpChat,
+    pwaInstall,
+    pushNotifications,
+  } = props;
   return (
     <BaseApp
       theme={theme}
       auth={auth}
+      analytics={analytics}
+      centrifugo={centrifugo}
       errorTracking={errorTracking}
       errorBoundary={errorBoundary}
       swr={swr}
       mcpChat={mcpChat}
+      pwaInstall={pwaInstall}
+      pushNotifications={pushNotifications}
     >
       <AppLayoutContent {...props} />
     </BaseApp>