@djangocfg/layouts 2.1.103 → 2.1.104

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 (94) hide show
  1. package/package.json +33 -37
  2. package/src/components/RedirectPage/RedirectPage.tsx +2 -2
  3. package/src/components/core/ClientOnly.tsx +1 -1
  4. package/src/components/errors/ErrorLayout.tsx +1 -1
  5. package/src/components/errors/ErrorsTracker/components/ErrorButtons.tsx +1 -1
  6. package/src/components/index.ts +2 -0
  7. package/src/index.ts +2 -0
  8. package/src/layouts/AuthLayout/components/AuthHelp.tsx +1 -1
  9. package/src/layouts/AuthLayout/components/AuthSuccess.tsx +1 -1
  10. package/src/layouts/AuthLayout/components/IdentifierForm.tsx +1 -1
  11. package/src/layouts/AuthLayout/components/OTPForm.tsx +1 -1
  12. package/src/layouts/AuthLayout/components/TwoFactorForm.tsx +1 -1
  13. package/src/layouts/AuthLayout/components/TwoFactorSetup.tsx +1 -1
  14. package/src/layouts/AuthLayout/components/oauth/OAuthCallback.tsx +1 -1
  15. package/src/layouts/AuthLayout/components/oauth/OAuthProviders.tsx +1 -1
  16. package/src/layouts/PrivateLayout/PrivateLayout.tsx +3 -2
  17. package/src/layouts/PrivateLayout/components/PrivateHeader.tsx +2 -2
  18. package/src/layouts/ProfileLayout/ProfileLayout.tsx +1 -1
  19. package/src/layouts/ProfileLayout/__tests__/TwoFactorSection.test.tsx +1 -1
  20. package/src/layouts/ProfileLayout/components/AvatarSection.tsx +1 -1
  21. package/src/layouts/ProfileLayout/components/DeleteAccountSection.tsx +1 -1
  22. package/src/layouts/ProfileLayout/components/ProfileForm.tsx +1 -1
  23. package/src/layouts/ProfileLayout/components/TwoFactorSection.tsx +1 -1
  24. package/src/layouts/PublicLayout/components/PublicFooter/PublicFooter.tsx +1 -1
  25. package/src/layouts/PublicLayout/components/PublicMobileDrawer.tsx +1 -1
  26. package/src/layouts/PublicLayout/components/PublicNavigation.tsx +2 -2
  27. package/src/layouts/_components/UserMenu.tsx +1 -1
  28. package/src/layouts/index.ts +2 -0
  29. package/src/pages/index.ts +2 -0
  30. package/src/pages/legal/LegalPage.tsx +1 -1
  31. package/src/snippets/AuthDialog/AuthDialog.tsx +3 -2
  32. package/src/snippets/McpChat/components/AIChatWidget.tsx +1 -1
  33. package/src/snippets/McpChat/components/AskAIButton.tsx +1 -1
  34. package/src/snippets/McpChat/components/ChatMessages.tsx +1 -1
  35. package/src/snippets/McpChat/components/ChatPanel.tsx +1 -1
  36. package/src/snippets/McpChat/components/ChatSidebar.tsx +1 -1
  37. package/src/snippets/McpChat/components/ChatWidget.tsx +1 -1
  38. package/src/snippets/McpChat/components/MessageBubble.tsx +1 -1
  39. package/src/snippets/McpChat/components/MessageInput.tsx +1 -1
  40. package/src/snippets/McpChat/context/AIChatContext.tsx +1 -1
  41. package/src/snippets/McpChat/context/ChatContext.tsx +1 -1
  42. package/src/snippets/McpChat/hooks/useChatLayout.ts +1 -1
  43. package/src/snippets/PWAInstall/components/A2HSHint.tsx +0 -1
  44. package/src/snippets/PWAInstall/components/DesktopGuide.tsx +1 -1
  45. package/src/snippets/PWAInstall/components/IOSGuide.tsx +1 -1
  46. package/src/snippets/PWAInstall/components/IOSGuideDrawer.tsx +1 -1
  47. package/src/snippets/PWAInstall/components/IOSGuideModal.tsx +1 -1
  48. package/src/snippets/PWAInstall/hooks/useInstallPrompt.ts +2 -2
  49. package/src/snippets/PushNotifications/components/PushPrompt.tsx +1 -1
  50. package/src/snippets/index.ts +1 -0
  51. package/dist/AIChatWidget-LUPM7S2O.mjs +0 -1644
  52. package/dist/AIChatWidget-LUPM7S2O.mjs.map +0 -1
  53. package/dist/AIChatWidget-O23TJJ7C.mjs +0 -3
  54. package/dist/AIChatWidget-O23TJJ7C.mjs.map +0 -1
  55. package/dist/chunk-53YKWR6F.mjs +0 -6
  56. package/dist/chunk-53YKWR6F.mjs.map +0 -1
  57. package/dist/chunk-EI7TDN2G.mjs +0 -1652
  58. package/dist/chunk-EI7TDN2G.mjs.map +0 -1
  59. package/dist/components.cjs +0 -925
  60. package/dist/components.cjs.map +0 -1
  61. package/dist/components.d.mts +0 -583
  62. package/dist/components.d.ts +0 -583
  63. package/dist/components.mjs +0 -879
  64. package/dist/components.mjs.map +0 -1
  65. package/dist/index.cjs +0 -7573
  66. package/dist/index.cjs.map +0 -1
  67. package/dist/index.d.mts +0 -2376
  68. package/dist/index.d.ts +0 -2376
  69. package/dist/index.mjs +0 -5673
  70. package/dist/index.mjs.map +0 -1
  71. package/dist/layouts.cjs +0 -6530
  72. package/dist/layouts.cjs.map +0 -1
  73. package/dist/layouts.d.mts +0 -748
  74. package/dist/layouts.d.ts +0 -748
  75. package/dist/layouts.mjs +0 -4741
  76. package/dist/layouts.mjs.map +0 -1
  77. package/dist/pages.cjs +0 -178
  78. package/dist/pages.cjs.map +0 -1
  79. package/dist/pages.d.mts +0 -57
  80. package/dist/pages.d.ts +0 -57
  81. package/dist/pages.mjs +0 -168
  82. package/dist/pages.mjs.map +0 -1
  83. package/dist/snippets.cjs +0 -3793
  84. package/dist/snippets.cjs.map +0 -1
  85. package/dist/snippets.d.mts +0 -1192
  86. package/dist/snippets.d.ts +0 -1192
  87. package/dist/snippets.mjs +0 -3738
  88. package/dist/snippets.mjs.map +0 -1
  89. package/dist/utils.cjs +0 -34
  90. package/dist/utils.cjs.map +0 -1
  91. package/dist/utils.d.mts +0 -40
  92. package/dist/utils.d.ts +0 -40
  93. package/dist/utils.mjs +0 -25
  94. package/dist/utils.mjs.map +0 -1
package/dist/index.d.mts DELETED
@@ -1,2376 +0,0 @@
1
- import React$1, { ErrorInfo, ReactNode, Component } from 'react';
2
- import { LucideIcon as LucideIcon$1 } from 'lucide-react';
3
- import { AuthConfig, AuthLayoutProps, AuthFormContextType, AuthHelpProps } from '@djangocfg/api/auth';
4
- export { AuthChannel, AuthFormContextType, AuthFormState, AuthHelpProps, AuthLayoutConfig, AuthLayoutProps, AuthStep } from '@djangocfg/api/auth';
5
- import { ZodError } from 'zod';
6
- import * as react_jsx_runtime from 'react/jsx-runtime';
7
- export { useRouter } from 'nextjs-toploader/app';
8
- import { ButtonProps } from '@djangocfg/ui-nextjs';
9
- import * as consola from 'consola';
10
-
11
- /**
12
- * Provider Configuration Types
13
- *
14
- * Configuration types for layout providers (theme, SWR, MCP chat, Centrifugo)
15
- * Note: Analytics, PWA, Push, and Error types are defined in their respective modules
16
- */
17
- interface ThemeConfig {
18
- defaultTheme?: 'light' | 'dark' | 'system';
19
- storageKey?: string;
20
- }
21
- interface SWRConfigOptions {
22
- revalidateOnFocus?: boolean;
23
- revalidateOnReconnect?: boolean;
24
- dedupingInterval?: number;
25
- }
26
- interface McpChatConfig {
27
- /** Enable MCP chat widget */
28
- enabled?: boolean;
29
- /** API endpoint for chat */
30
- apiEndpoint?: string;
31
- /** Chat widget title */
32
- title?: string;
33
- /** Input placeholder */
34
- placeholder?: string;
35
- /** Greeting message */
36
- greeting?: string;
37
- /** Widget position */
38
- position?: 'bottom-right' | 'bottom-left';
39
- /** Widget variant */
40
- variant?: 'default' | 'minimal';
41
- /** Enable streaming responses */
42
- enableStreaming?: boolean;
43
- /** Auto-detect environment (dev/prod) */
44
- autoDetectEnvironment?: boolean;
45
- /** Custom class name */
46
- className?: string;
47
- }
48
- interface CentrifugoConfig {
49
- /** Enable Centrifugo (default: true) */
50
- enabled?: boolean;
51
- /** Auto-connect on mount (default: false) */
52
- autoConnect?: boolean;
53
- /** Centrifugo server URL */
54
- url?: string;
55
- }
56
-
57
- /**
58
- * Analytics Configuration Types
59
- *
60
- * Configuration for Google Analytics integration
61
- */
62
- interface AnalyticsConfig {
63
- /** Google Analytics tracking ID (e.g., 'G-XXXXXXXXXX') */
64
- googleTrackingId?: string;
65
- }
66
-
67
- /**
68
- * PWA Install Configuration Types
69
- *
70
- * Configuration for Progressive Web App installation features
71
- */
72
- interface PwaInstallConfig {
73
- /** Enable PWA installation features */
74
- enabled?: boolean;
75
- /** Show A2HS (Add to Home Screen) hint (enabled by default when enabled is true) */
76
- showInstallHint?: boolean;
77
- /** Number of days before re-showing dismissed hint (null = never show again) */
78
- resetAfterDays?: number | null;
79
- /** Delay before showing hint (ms) */
80
- delayMs?: number;
81
- /** App logo URL to display in hint */
82
- logo?: string;
83
- /**
84
- * Resume last page when opening PWA
85
- * When enabled, saves current pathname on navigation and restores it on PWA launch
86
- * @default false
87
- */
88
- resumeLastPage?: boolean;
89
- }
90
-
91
- /**
92
- * Platform Detection Types
93
- */
94
- /**
95
- * Platform detection result
96
- */
97
- interface PlatformInfo {
98
- isIOS: boolean;
99
- isAndroid: boolean;
100
- isDesktop: boolean;
101
- isSafari: boolean;
102
- isChrome: boolean;
103
- isEdge: boolean;
104
- isFirefox: boolean;
105
- isStandalone: boolean;
106
- canPrompt: boolean;
107
- shouldShowAndroidPrompt: boolean;
108
- shouldShowIOSGuide: boolean;
109
- }
110
-
111
- /**
112
- * PWA Installation Types
113
- */
114
- /**
115
- * Install prompt state
116
- */
117
- interface InstallPromptState {
118
- isIOS: boolean;
119
- isAndroid: boolean;
120
- isSafari: boolean;
121
- isChrome: boolean;
122
- isInstalled: boolean;
123
- canPrompt: boolean;
124
- deferredPrompt: BeforeInstallPromptEvent | null;
125
- }
126
- /**
127
- * BeforeInstallPrompt event (Android Chrome)
128
- */
129
- interface BeforeInstallPromptEvent extends Event {
130
- prompt: () => Promise<void>;
131
- userChoice: Promise<{
132
- outcome: 'accepted' | 'dismissed';
133
- platform: string;
134
- }>;
135
- }
136
- /**
137
- * Install outcome
138
- */
139
- type InstallOutcome = 'accepted' | 'dismissed' | null;
140
- /**
141
- * iOS guide dismissal state
142
- */
143
- interface IOSGuideState {
144
- dismissed: boolean;
145
- dismissedAt: number | null;
146
- shouldShow: boolean;
147
- }
148
-
149
- /**
150
- * Component Props Types
151
- */
152
-
153
- /**
154
- * Install context type
155
- */
156
- interface InstallContextType {
157
- platform: PlatformInfo;
158
- isInstalled: boolean;
159
- canPrompt: boolean;
160
- showIOSGuide: boolean;
161
- setShowIOSGuide: (show: boolean) => void;
162
- promptInstall: () => Promise<InstallOutcome>;
163
- dismissIOSGuide: () => void;
164
- }
165
- /**
166
- * Install manager props
167
- */
168
- interface InstallManagerProps {
169
- /**
170
- * Delay before showing iOS guide (ms)
171
- * @default 2000
172
- */
173
- delayMs?: number;
174
- /**
175
- * Number of days before re-showing dismissed guide
176
- * @default 7
177
- */
178
- resetDays?: number;
179
- /**
180
- * Custom class name for install button
181
- */
182
- buttonClassName?: string;
183
- /**
184
- * Custom button text
185
- */
186
- buttonText?: string;
187
- /**
188
- * Force show install UI (ignores platform detection)
189
- * Useful for testing on desktop in development
190
- * @default false
191
- */
192
- forceShow?: boolean;
193
- /**
194
- * Callback when install is successful
195
- */
196
- onInstallSuccess?: () => void;
197
- /**
198
- * Callback when install is dismissed
199
- */
200
- onInstallDismiss?: () => void;
201
- }
202
- /**
203
- * Android install button props
204
- */
205
- interface AndroidInstallButtonProps {
206
- onInstall: () => Promise<InstallOutcome>;
207
- className?: string;
208
- text?: string;
209
- }
210
- /**
211
- * iOS guide modal props
212
- */
213
- interface IOSGuideModalProps {
214
- onDismiss: () => void;
215
- open?: boolean;
216
- }
217
- /**
218
- * Install step for iOS guide
219
- */
220
- interface InstallStep {
221
- number: number;
222
- title: string;
223
- icon: React.ComponentType<{
224
- className?: string;
225
- }>;
226
- description: string;
227
- }
228
-
229
- /**
230
- * Push Notifications Configuration Types
231
- *
232
- * Configuration for Web Push Notifications with VAPID authentication
233
- */
234
- interface PushNotificationsConfig {
235
- /** Enable push notifications */
236
- enabled?: boolean;
237
- /** VAPID public key for push notifications (required when enabled) */
238
- vapidPublicKey: string;
239
- /** API endpoint for subscription (default: '/api/push/subscribe') */
240
- subscribeEndpoint?: string;
241
- /** Only show push prompt if PWA is installed (default: true) */
242
- requirePWA?: boolean;
243
- /** Delay before showing push prompt after PWA install (ms) */
244
- delayMs?: number;
245
- /** Number of days before re-showing dismissed push prompt */
246
- resetAfterDays?: number;
247
- /** Auto-subscribe on mount if permission already granted */
248
- autoSubscribe?: boolean;
249
- }
250
-
251
- /**
252
- * Push Notification Types
253
- */
254
- /**
255
- * Push notification state
256
- */
257
- interface PushNotificationState {
258
- isSupported: boolean;
259
- permission: NotificationPermission;
260
- isSubscribed: boolean;
261
- subscription: PushSubscription | null;
262
- }
263
- /**
264
- * Push notification options
265
- */
266
- interface PushNotificationOptions {
267
- vapidPublicKey: string;
268
- subscribeEndpoint?: string;
269
- }
270
-
271
- /**
272
- * Error Tracking Types
273
- *
274
- * Common types for all error tracking functionality
275
- */
276
-
277
- /**
278
- * Base error detail from CustomEvent
279
- */
280
- interface BaseErrorDetail {
281
- /** Timestamp of the error */
282
- timestamp: Date;
283
- }
284
- /**
285
- * Validation error detail (from zod-validation-error event)
286
- */
287
- interface ValidationErrorDetail extends BaseErrorDetail {
288
- type: 'validation';
289
- /** Operation/function name that failed validation */
290
- operation: string;
291
- /** API endpoint path */
292
- path: string;
293
- /** HTTP method */
294
- method: string;
295
- /** Zod validation error */
296
- error: ZodError;
297
- /** Raw response data that failed validation */
298
- response: any;
299
- }
300
- /**
301
- * CORS error detail (from cors-error event)
302
- */
303
- interface CORSErrorDetail extends BaseErrorDetail {
304
- type: 'cors';
305
- /** API endpoint that was blocked */
306
- url: string;
307
- /** HTTP method */
308
- method: string;
309
- /** Error message */
310
- error: string;
311
- }
312
- /**
313
- * Network error detail (from network-error event)
314
- */
315
- interface NetworkErrorDetail extends BaseErrorDetail {
316
- type: 'network';
317
- /** API endpoint that failed */
318
- url: string;
319
- /** HTTP method */
320
- method: string;
321
- /** Error message */
322
- error: string;
323
- /** Status code if available */
324
- statusCode?: number;
325
- }
326
- /**
327
- * Centrifugo error detail (from centrifugo-error event)
328
- */
329
- interface CentrifugoErrorDetail extends BaseErrorDetail {
330
- type: 'centrifugo';
331
- /** RPC method that failed */
332
- method: string;
333
- /** Error message */
334
- error: string;
335
- /** Error code from Centrifugo */
336
- code?: number;
337
- /** Additional data sent with the request */
338
- data?: any;
339
- }
340
- /**
341
- * Union type of all error details
342
- */
343
- type ErrorDetail = ValidationErrorDetail | CORSErrorDetail | NetworkErrorDetail | CentrifugoErrorDetail;
344
- /**
345
- * Stored error with unique ID
346
- */
347
- type StoredError<T extends ErrorDetail = ErrorDetail> = T & {
348
- /** Unique identifier for this error instance */
349
- id: string;
350
- };
351
- /**
352
- * Configuration for specific error type
353
- */
354
- interface ErrorTypeConfig {
355
- /**
356
- * Enable tracking for this error type
357
- * @default true
358
- */
359
- enabled?: boolean;
360
- /**
361
- * Show toast notifications
362
- * @default true
363
- */
364
- showToast?: boolean;
365
- /**
366
- * Maximum number of errors to keep in history
367
- * @default 50
368
- */
369
- maxErrors?: number;
370
- /**
371
- * Toast duration in milliseconds (0 = no auto-dismiss)
372
- * @default 8000 for validation, 0 for cors/network
373
- */
374
- duration?: number;
375
- }
376
- /**
377
- * Validation error specific config
378
- */
379
- interface ValidationErrorConfig extends ErrorTypeConfig {
380
- /**
381
- * Show operation name in toast
382
- * @default true
383
- */
384
- showOperation?: boolean;
385
- /**
386
- * Show endpoint path in toast
387
- * @default true
388
- */
389
- showPath?: boolean;
390
- /**
391
- * Show error count in toast
392
- * @default true
393
- */
394
- showErrorCount?: boolean;
395
- /**
396
- * Maximum number of issues to show in toast
397
- * @default 3
398
- */
399
- maxIssuesInToast?: number;
400
- }
401
- /**
402
- * CORS error specific config
403
- */
404
- interface CORSErrorConfig extends ErrorTypeConfig {
405
- /**
406
- * Show full URL in toast
407
- * @default true
408
- */
409
- showUrl?: boolean;
410
- /**
411
- * Show HTTP method in toast
412
- * @default true
413
- */
414
- showMethod?: boolean;
415
- }
416
- /**
417
- * Network error specific config
418
- */
419
- interface NetworkErrorConfig extends ErrorTypeConfig {
420
- /**
421
- * Show full URL in toast
422
- * @default true
423
- */
424
- showUrl?: boolean;
425
- /**
426
- * Show HTTP method in toast
427
- * @default true
428
- */
429
- showMethod?: boolean;
430
- /**
431
- * Show status code in toast
432
- * @default true
433
- */
434
- showStatusCode?: boolean;
435
- }
436
- /**
437
- * Centrifugo error specific config
438
- */
439
- interface CentrifugoErrorConfig extends ErrorTypeConfig {
440
- /**
441
- * Show RPC method in toast
442
- * @default true
443
- */
444
- showMethod?: boolean;
445
- /**
446
- * Show error code in toast
447
- * @default true
448
- */
449
- showCode?: boolean;
450
- }
451
- /**
452
- * Complete error tracking configuration
453
- */
454
- interface ErrorTrackingConfig {
455
- /**
456
- * Validation error tracking configuration
457
- */
458
- validation?: ValidationErrorConfig;
459
- /**
460
- * CORS error tracking configuration
461
- */
462
- cors?: CORSErrorConfig;
463
- /**
464
- * Network error tracking configuration
465
- */
466
- network?: NetworkErrorConfig;
467
- /**
468
- * Centrifugo error tracking configuration
469
- */
470
- centrifugo?: CentrifugoErrorConfig;
471
- /**
472
- * Custom error handler (called before toast for all errors)
473
- * Return false to prevent default toast notification
474
- */
475
- onError?: (error: ErrorDetail) => boolean | void;
476
- }
477
- /**
478
- * Error tracking context value
479
- */
480
- interface ErrorTrackingContextValue {
481
- /** All errors */
482
- errors: StoredError[];
483
- /** Validation errors only */
484
- validationErrors: StoredError<ValidationErrorDetail>[];
485
- /** CORS errors only */
486
- corsErrors: StoredError<CORSErrorDetail>[];
487
- /** Network errors only */
488
- networkErrors: StoredError<NetworkErrorDetail>[];
489
- /** Centrifugo errors only */
490
- centrifugoErrors: StoredError<CentrifugoErrorDetail>[];
491
- /** Clear all errors */
492
- clearErrors: () => void;
493
- /** Clear errors by type */
494
- clearErrorsByType: (type: 'validation' | 'cors' | 'network' | 'centrifugo') => void;
495
- /** Clear specific error by ID */
496
- clearError: (id: string) => void;
497
- /** Get error count */
498
- errorCount: number;
499
- /** Get latest error */
500
- latestError: StoredError | null;
501
- /** Configuration */
502
- config: {
503
- validation: Required<ValidationErrorConfig>;
504
- cors: Required<CORSErrorConfig>;
505
- network: Required<NetworkErrorConfig>;
506
- centrifugo: Required<CentrifugoErrorConfig>;
507
- };
508
- }
509
-
510
- /**
511
- * Error Handling Configuration Types
512
- *
513
- * Configuration types for ErrorTrackingProvider and ErrorBoundary
514
- */
515
-
516
- /**
517
- * Error Boundary Configuration
518
- *
519
- * Configuration for React ErrorBoundary component
520
- */
521
- interface ErrorBoundaryConfig {
522
- /** Enable error boundary (default: true) */
523
- enabled?: boolean;
524
- /** Support email to display in error UI */
525
- supportEmail?: string;
526
- /** Custom error handler called when error is caught */
527
- onError?: (error: Error, errorInfo: ErrorInfo) => void;
528
- }
529
-
530
- /**
531
- * UI Component Types
532
- *
533
- * Types for layout UI components (navigation, footer, user menu)
534
- */
535
-
536
- interface NavigationItem {
537
- label: string;
538
- href: string;
539
- icon?: LucideIcon$1 | string;
540
- badge?: string | number;
541
- external?: boolean;
542
- }
543
- interface NavigationSection {
544
- title?: string;
545
- items: NavigationItem[];
546
- }
547
- interface FooterLink$1 {
548
- label: string;
549
- path: string;
550
- external?: boolean;
551
- }
552
- interface FooterMenuSection$1 {
553
- title: string;
554
- items: FooterLink$1[];
555
- }
556
- interface FooterSocialLinks$1 {
557
- github?: string;
558
- linkedin?: string;
559
- twitter?: string;
560
- telegram?: string;
561
- youtube?: string;
562
- facebook?: string;
563
- instagram?: string;
564
- whatsapp?: string;
565
- email?: string;
566
- }
567
- interface FooterConfig {
568
- siteName?: string;
569
- description?: string;
570
- logo?: string;
571
- badge?: {
572
- icon: LucideIcon$1;
573
- text: string;
574
- };
575
- socialLinks?: FooterSocialLinks$1;
576
- links?: FooterLink$1[];
577
- menuSections?: FooterMenuSection$1[];
578
- copyright?: string;
579
- credits?: {
580
- text: string;
581
- url?: string;
582
- };
583
- variant?: 'full' | 'simple';
584
- }
585
- interface UserMenuItem {
586
- /** Menu item label */
587
- label: string;
588
- /** Link href (optional if onClick is provided) */
589
- href?: string;
590
- /** Icon component */
591
- icon?: LucideIcon$1;
592
- /** Visual variant */
593
- variant?: 'default' | 'destructive';
594
- /** Click handler (optional if href is provided) */
595
- onClick?: () => void;
596
- /** Open link in new tab */
597
- external?: boolean;
598
- }
599
- interface UserMenuGroup {
600
- /** Optional group title (renders DropdownMenuLabel) */
601
- title?: string;
602
- /** Menu items in this group */
603
- items: UserMenuItem[];
604
- }
605
- interface UserMenuConfig {
606
- /** Menu groups for authenticated users */
607
- groups?: UserMenuGroup[];
608
- /** Auth page path (for sign in button) */
609
- authPath?: string;
610
- }
611
-
612
- /**
613
- * Base Layout Types
614
- *
615
- * Core layout configuration that combines all provider configs
616
- */
617
-
618
- /**
619
- * Base Layout Props
620
- *
621
- * Core configuration for BaseApp component.
622
- * All provider configs are imported from their respective modules.
623
- */
624
- interface BaseLayoutProps {
625
- children: ReactNode;
626
- /** Theme configuration */
627
- theme?: ThemeConfig;
628
- /** Auth configuration */
629
- auth?: AuthConfig;
630
- /** Analytics configuration (from snippets/Analytics) */
631
- analytics?: AnalyticsConfig;
632
- /** Centrifugo configuration */
633
- centrifugo?: CentrifugoConfig;
634
- /** Error tracking configuration (from components/errors) */
635
- errorTracking?: ErrorTrackingConfig;
636
- /** SWR configuration */
637
- swr?: SWRConfigOptions;
638
- /** Error boundary configuration (from components/errors, enabled by default) */
639
- errorBoundary?: ErrorBoundaryConfig;
640
- /** MCP chat configuration */
641
- mcpChat?: McpChatConfig;
642
- /** PWA Install configuration (from snippets/PWAInstall) */
643
- pwaInstall?: PwaInstallConfig;
644
- /** Push Notifications configuration (from snippets/PushNotifications) */
645
- pushNotifications?: PushNotificationsConfig;
646
- }
647
-
648
- interface UserMenuProps {
649
- /** Display variant */
650
- variant?: 'desktop' | 'mobile';
651
- /** Menu groups for authenticated users */
652
- groups?: UserMenuGroup[];
653
- /** Auth page path (for sign in button) */
654
- authPath?: string;
655
- }
656
- declare function UserMenu({ variant, groups, authPath, }: UserMenuProps): react_jsx_runtime.JSX.Element;
657
-
658
- type LayoutMode = 'public' | 'private' | 'admin';
659
- interface AppLayoutProps {
660
- children: ReactNode;
661
- /** Public layout component with enabled paths */
662
- publicLayout?: {
663
- component: React$1.ComponentType<{
664
- children: ReactNode;
665
- }>;
666
- enabledPath?: string | string[];
667
- };
668
- /** Private layout component with enabled paths */
669
- privateLayout?: {
670
- component: React$1.ComponentType<{
671
- children: ReactNode;
672
- }>;
673
- enabledPath?: string | string[];
674
- };
675
- /** Admin layout component with enabled paths */
676
- adminLayout?: {
677
- component: React$1.ComponentType<{
678
- children: ReactNode;
679
- }>;
680
- enabledPath?: string | string[];
681
- };
682
- /**
683
- * Paths that render without any layout wrapper (fullscreen pages)
684
- * Providers (auth, theme, etc.) are still applied, only layout is skipped
685
- * Useful for: fullscreen terminal, embed pages, print views
686
- */
687
- noLayoutPaths?: string | string[];
688
- /** Theme configuration */
689
- theme?: ThemeConfig;
690
- /** Auth configuration */
691
- auth?: AuthConfig;
692
- /** Analytics configuration */
693
- analytics?: AnalyticsConfig;
694
- /** Centrifugo configuration */
695
- centrifugo?: CentrifugoConfig;
696
- /** Error tracking configuration */
697
- errorTracking?: ErrorTrackingConfig;
698
- /** SWR configuration */
699
- swr?: SWRConfigOptions;
700
- /** Error boundary configuration */
701
- errorBoundary?: ErrorBoundaryConfig;
702
- /** MCP Chat configuration */
703
- mcpChat?: McpChatConfig;
704
- /** PWA Install configuration */
705
- pwaInstall?: PwaInstallConfig;
706
- /** Push Notifications configuration */
707
- pushNotifications?: PushNotificationsConfig;
708
- }
709
- /**
710
- * AppLayout - Main Component with All Providers
711
- */
712
- declare function AppLayout(props: AppLayoutProps): react_jsx_runtime.JSX.Element;
713
-
714
- type BaseAppProps = BaseLayoutProps;
715
- /**
716
- * BaseApp - Core providers wrapper for any React/Next.js app
717
- *
718
- * Includes: ThemeProvider, TooltipProvider, SWRConfig, AuthProvider, AnalyticsProvider,
719
- * CentrifugoProvider, PwaProvider, PushProvider, ErrorTrackingProvider,
720
- * ErrorBoundary (optional), MCP Chat (optional)
721
- * Also renders global Toaster and PageProgress components
722
- */
723
- declare function BaseApp({ children, theme, auth, analytics, centrifugo, errorTracking, errorBoundary, swr, mcpChat, pwaInstall, pushNotifications, }: BaseAppProps): react_jsx_runtime.JSX.Element;
724
-
725
- interface PublicLayoutProps {
726
- children: ReactNode;
727
- /** Logo path or URL */
728
- logo?: string;
729
- /** Site name */
730
- siteName?: string;
731
- /** Navigation items */
732
- navigation?: NavigationItem[];
733
- /** User menu configuration (optional, uses useAuth() for authentication state) */
734
- userMenu?: UserMenuConfig;
735
- }
736
- declare function PublicLayout({ children, logo, siteName, navigation, userMenu, }: PublicLayoutProps): react_jsx_runtime.JSX.Element;
737
-
738
- /**
739
- * Public Footer Types
740
- */
741
-
742
- interface FooterLink {
743
- label: string;
744
- path: string;
745
- external?: boolean;
746
- }
747
- interface FooterMenuSection {
748
- title: string;
749
- items: FooterLink[];
750
- }
751
- interface FooterSocialLinks {
752
- github?: string;
753
- linkedin?: string;
754
- twitter?: string;
755
- telegram?: string;
756
- youtube?: string;
757
- facebook?: string;
758
- instagram?: string;
759
- whatsapp?: string;
760
- email?: string;
761
- }
762
- interface PublicFooterProps {
763
- /** Project name */
764
- siteName: string;
765
- /** Project description */
766
- description?: string;
767
- /** Logo path or URL */
768
- logo?: string;
769
- /** Optional badge */
770
- badge?: {
771
- icon: LucideIcon$1;
772
- text: string;
773
- };
774
- /** Social media links */
775
- socialLinks?: FooterSocialLinks;
776
- /** Quick links (bottom bar) */
777
- links?: FooterLink[];
778
- /** Footer menu sections (desktop grid) */
779
- menuSections?: FooterMenuSection[];
780
- /** Copyright text (auto-generated if not provided) */
781
- copyright?: string;
782
- /** Credits */
783
- credits?: {
784
- text: string;
785
- url?: string;
786
- };
787
- /** Variant: full (with all sections) or simple (minimal) */
788
- variant?: 'full' | 'simple';
789
- }
790
-
791
- declare function PublicFooter({ siteName, description, logo, badge, socialLinks, links, menuSections, copyright: copyrightProp, credits: creditsProp, variant, }: PublicFooterProps): react_jsx_runtime.JSX.Element;
792
-
793
- interface FooterProjectInfoProps {
794
- siteName: string;
795
- description?: string;
796
- logo?: string;
797
- badge?: {
798
- icon: LucideIcon$1;
799
- text: string;
800
- };
801
- socialLinks?: FooterSocialLinks;
802
- variant?: 'mobile' | 'desktop';
803
- }
804
- declare function FooterProjectInfo({ siteName, description, logo, badge, socialLinks, variant, }: FooterProjectInfoProps): react_jsx_runtime.JSX.Element;
805
-
806
- interface FooterMenuSectionsProps {
807
- menuSections: FooterMenuSection[];
808
- }
809
- declare function FooterMenuSections({ menuSections }: FooterMenuSectionsProps): react_jsx_runtime.JSX.Element;
810
-
811
- interface FooterBottomProps {
812
- copyright: string;
813
- credits?: {
814
- text: string;
815
- url?: string;
816
- };
817
- links?: FooterLink[];
818
- variant?: 'mobile' | 'desktop';
819
- }
820
- declare function FooterBottom({ copyright, credits, links, variant, }: FooterBottomProps): react_jsx_runtime.JSX.Element;
821
-
822
- interface FooterSocialLinksProps {
823
- socialLinks?: FooterSocialLinks;
824
- className?: string;
825
- iconClassName?: string;
826
- }
827
- declare function FooterSocialLinksComponent({ socialLinks, className, iconClassName, }: FooterSocialLinksProps): react_jsx_runtime.JSX.Element;
828
-
829
- /**
830
- * DjangoCFG Logo Component
831
- *
832
- * Default SVG logo for DjangoCFG
833
- */
834
- interface DjangoCFGLogoProps {
835
- className?: string;
836
- size?: number;
837
- }
838
- declare function DjangoCFGLogo({ className, size }: DjangoCFGLogoProps): react_jsx_runtime.JSX.Element;
839
-
840
- interface SidebarItem {
841
- label: string;
842
- href: string;
843
- icon?: string | LucideIcon$1;
844
- badge?: string | number;
845
- }
846
- interface SidebarConfig {
847
- items: SidebarItem[];
848
- homeHref?: string;
849
- }
850
- interface HeaderConfig {
851
- title?: string;
852
- /** User menu groups */
853
- groups?: UserMenuConfig['groups'];
854
- /** Auth page path (for sign in button) */
855
- authPath?: string;
856
- }
857
- interface PrivateLayoutProps {
858
- children: ReactNode;
859
- /** Sidebar configuration */
860
- sidebar?: SidebarConfig;
861
- /** Header configuration */
862
- header?: HeaderConfig;
863
- /** Content padding */
864
- contentPadding?: 'none' | 'default';
865
- }
866
- declare function PrivateLayout({ children, sidebar, header, contentPadding, }: PrivateLayoutProps): react_jsx_runtime.JSX.Element;
867
-
868
- /**
869
- * Auth Layout
870
- *
871
- * Layout for authentication pages with OTP (email/phone), OAuth (GitHub), and 2FA support.
872
- * Supports multi-step authentication flow: identifier → OTP → 2FA (if enabled)
873
- */
874
-
875
- declare const AuthLayout: React$1.FC<AuthLayoutProps>;
876
-
877
- declare const AuthFormProvider: React$1.FC<AuthLayoutProps>;
878
- declare const useAuthFormContext: () => AuthFormContextType;
879
-
880
- declare const IdentifierForm: React$1.FC;
881
-
882
- declare const OTPForm: React$1.FC;
883
-
884
- declare const AuthHelp: React$1.FC<AuthHelpProps>;
885
-
886
- /**
887
- * OAuth Providers Component
888
- *
889
- * Shows OAuth login buttons (GitHub, etc.) when enabled.
890
- */
891
- declare const OAuthProviders: React$1.FC;
892
-
893
- interface OAuthCallbackProps {
894
- onSuccess?: (user: any, isNewUser: boolean, provider: string) => void;
895
- onError?: (error: string) => void;
896
- redirectUrl?: string;
897
- }
898
- /**
899
- * OAuth Callback Handler Component
900
- *
901
- * Processes OAuth callback from providers (GitHub, etc.).
902
- * Reads code, state, and provider from URL params and exchanges for tokens.
903
- *
904
- * Usage:
905
- * Place this component on your /auth page to handle OAuth callbacks.
906
- *
907
- * @example
908
- * ```tsx
909
- * // app/auth/page.tsx
910
- * import { OAuthCallback, AuthLayout } from '@djangocfg/layouts';
911
- *
912
- * export default function AuthPage() {
913
- * return (
914
- * <>
915
- * <OAuthCallback
916
- * onSuccess={(user) => console.log('OAuth success:', user)}
917
- * onError={(error) => console.error('OAuth error:', error)}
918
- * />
919
- * <AuthLayout enableGithubAuth>
920
- * {/* Your auth content *\/}
921
- * </AuthLayout>
922
- * </>
923
- * );
924
- * }
925
- * ```
926
- */
927
- declare const OAuthCallback: React$1.FC<OAuthCallbackProps>;
928
-
929
- interface AdminLayoutProps extends PrivateLayoutProps {
930
- children: ReactNode;
931
- }
932
- /**
933
- * Admin Layout Component
934
- *
935
- * Wrapper around PrivateLayout with admin-specific defaults
936
- * Same API as PrivateLayout - just a convenience export
937
- */
938
- declare function AdminLayout(props: AdminLayoutProps): react_jsx_runtime.JSX.Element;
939
-
940
- interface ProfileLayoutProps {
941
- onUnauthenticated?: () => void;
942
- title?: string;
943
- enable2FA?: boolean;
944
- enableDeleteAccount?: boolean;
945
- }
946
- declare const ProfileLayout: React$1.FC<ProfileLayoutProps>;
947
-
948
- interface BreadcrumbItem {
949
- path: string;
950
- label: string;
951
- isActive: boolean;
952
- }
953
- declare function generateBreadcrumbsFromPath(pathname: string): BreadcrumbItem[];
954
-
955
- declare const DIALOG_EVENTS: {
956
- readonly OPEN_AUTH_DIALOG: "OPEN_AUTH_DIALOG";
957
- readonly CLOSE_AUTH_DIALOG: "CLOSE_AUTH_DIALOG";
958
- readonly AUTH_SUCCESS: "AUTH_SUCCESS";
959
- readonly AUTH_FAILURE: "AUTH_FAILURE";
960
- };
961
- interface AuthDialogProps {
962
- onAuthRequired?: () => void;
963
- authPath?: string;
964
- }
965
- declare const AuthDialog: React$1.FC<AuthDialogProps>;
966
-
967
- declare const AUTH_EVENTS: {
968
- readonly OPEN_AUTH_DIALOG: "OPEN_AUTH_DIALOG";
969
- readonly CLOSE_AUTH_DIALOG: "CLOSE_AUTH_DIALOG";
970
- readonly AUTH_SUCCESS: "AUTH_SUCCESS";
971
- readonly AUTH_FAILURE: "AUTH_FAILURE";
972
- };
973
- type AuthEventType = typeof AUTH_EVENTS[keyof typeof AUTH_EVENTS];
974
- interface OpenAuthDialogPayload {
975
- message?: string;
976
- redirectUrl?: string;
977
- }
978
- interface AuthSuccessPayload {
979
- user?: any;
980
- }
981
- interface AuthFailurePayload {
982
- error?: string;
983
- }
984
-
985
- /**
986
- * Hook to control auth dialog from anywhere in the app
987
- */
988
- declare function useAuthDialog(): {
989
- openAuthDialog: (options?: OpenAuthDialogPayload) => void;
990
- closeAuthDialog: () => void;
991
- };
992
-
993
- /**
994
- * useAnalytics Hook
995
- *
996
- * Provides Google Analytics tracking via react-ga4
997
- * Automatically tracks page views on route changes
998
- * Only works in production mode
999
- */
1000
- /**
1001
- * Analytics utility object for standalone usage (outside React components)
1002
- *
1003
- * @example
1004
- * ```ts
1005
- * import { Analytics } from '@djangocfg/layouts';
1006
- *
1007
- * // In an event handler or utility function
1008
- * Analytics.event('button_click', { category: 'engagement', label: 'signup' });
1009
- * ```
1010
- */
1011
- declare const Analytics: {
1012
- /**
1013
- * Initialize Google Analytics (called automatically by useAnalytics hook)
1014
- */
1015
- init: (trackingId: string) => void;
1016
- /**
1017
- * Check if Analytics is enabled and initialized
1018
- */
1019
- isEnabled: () => boolean;
1020
- /**
1021
- * Track a page view
1022
- */
1023
- pageview: (path: string) => void;
1024
- /**
1025
- * Track a custom event
1026
- * @param name - Event name (action)
1027
- * @param params - Optional event parameters
1028
- */
1029
- event: (name: string, params?: Record<string, any>) => void;
1030
- /**
1031
- * Set user ID for tracking
1032
- */
1033
- setUser: (userId: string) => void;
1034
- /**
1035
- * Set custom dimensions/metrics
1036
- */
1037
- set: (fieldsObject: Record<string, any>) => void;
1038
- };
1039
- /**
1040
- * Hook for Google Analytics tracking via react-ga4
1041
- *
1042
- * Automatically initializes GA and tracks page views on route changes
1043
- * Only works in production mode (NODE_ENV === 'production')
1044
- *
1045
- * @example
1046
- * ```tsx
1047
- * // Just call the hook - it auto-tracks pageviews
1048
- * useAnalytics();
1049
- *
1050
- * // Or use the returned methods for custom tracking
1051
- * const { event, isEnabled } = useAnalytics();
1052
- * event('button_click', { category: 'engagement', label: 'signup' });
1053
- * ```
1054
- */
1055
- declare function useAnalytics(trackingIdProp?: string): {
1056
- isEnabled: boolean;
1057
- trackingId: string;
1058
- pageview: (path: string) => void;
1059
- event: (name: string, params?: Record<string, any>) => void;
1060
- setUser: (userId: string) => void;
1061
- set: (fieldsObject: Record<string, any>) => void;
1062
- };
1063
-
1064
- interface AnalyticsProviderProps {
1065
- children: ReactNode;
1066
- /** Google Analytics tracking ID (optional if using AppContext) */
1067
- trackingId?: string;
1068
- }
1069
- /**
1070
- * Analytics Provider that initializes tracking
1071
- * Automatically:
1072
- * - Initializes GA4 with tracking ID from prop or config
1073
- * - Sets user ID when authenticated
1074
- * - Tracks page views on route changes
1075
- */
1076
- declare function AnalyticsProvider({ children, trackingId }: AnalyticsProviderProps): react_jsx_runtime.JSX.Element;
1077
-
1078
- /**
1079
- * Analytics Events Constants
1080
- *
1081
- * Predefined event names and categories for consistent tracking
1082
- * across the entire application.
1083
- */
1084
- /**
1085
- * Event Categories
1086
- */
1087
- declare const AnalyticsCategory: {
1088
- readonly AUTH: "auth";
1089
- readonly ERROR: "error";
1090
- readonly NAVIGATION: "navigation";
1091
- readonly ENGAGEMENT: "engagement";
1092
- readonly USER: "user";
1093
- };
1094
- /**
1095
- * Predefined Event Names
1096
- */
1097
- declare const AnalyticsEvent: {
1098
- readonly AUTH_OTP_REQUEST: "auth_otp_request";
1099
- readonly AUTH_OTP_VERIFY_SUCCESS: "auth_otp_verify_success";
1100
- readonly AUTH_OTP_VERIFY_FAIL: "auth_otp_verify_fail";
1101
- readonly AUTH_LOGIN_SUCCESS: "auth_login_success";
1102
- readonly AUTH_LOGOUT: "auth_logout";
1103
- readonly AUTH_SESSION_EXPIRED: "auth_session_expired";
1104
- readonly AUTH_TOKEN_REFRESH: "auth_token_refresh";
1105
- readonly AUTH_TOKEN_REFRESH_FAIL: "auth_token_refresh_fail";
1106
- readonly AUTH_OAUTH_START: "auth_oauth_start";
1107
- readonly AUTH_OAUTH_SUCCESS: "auth_oauth_success";
1108
- readonly AUTH_OAUTH_FAIL: "auth_oauth_fail";
1109
- readonly ERROR_BOUNDARY: "error_boundary";
1110
- readonly ERROR_API: "error_api";
1111
- readonly ERROR_VALIDATION: "error_validation";
1112
- readonly ERROR_NETWORK: "error_network";
1113
- readonly NAV_ADMIN_ENTER: "nav_admin_enter";
1114
- readonly NAV_DASHBOARD_ENTER: "nav_dashboard_enter";
1115
- readonly NAV_PAGE_VIEW: "nav_page_view";
1116
- readonly THEME_CHANGE: "theme_change";
1117
- readonly SIDEBAR_TOGGLE: "sidebar_toggle";
1118
- readonly MOBILE_MENU_OPEN: "mobile_menu_open";
1119
- readonly USER_PROFILE_VIEW: "user_profile_view";
1120
- readonly USER_PROFILE_UPDATE: "user_profile_update";
1121
- };
1122
- type AnalyticsCategoryType = typeof AnalyticsCategory[keyof typeof AnalyticsCategory];
1123
- type AnalyticsEventType = typeof AnalyticsEvent[keyof typeof AnalyticsEvent];
1124
-
1125
- /**
1126
- * Types for @djangocfg/mcp-chat
1127
- */
1128
-
1129
- /**
1130
- * AI Chat message role
1131
- */
1132
- type AIMessageRole = 'user' | 'assistant' | 'system';
1133
- /**
1134
- * AI Chat message
1135
- */
1136
- interface AIChatMessage {
1137
- id: string;
1138
- role: AIMessageRole;
1139
- content: string;
1140
- timestamp: Date;
1141
- /** Related documentation links */
1142
- sources?: AIChatSource[];
1143
- /** Is message still being generated */
1144
- isStreaming?: boolean;
1145
- }
1146
- /**
1147
- * AI Documentation source reference
1148
- */
1149
- interface AIChatSource {
1150
- title: string;
1151
- path: string;
1152
- url?: string;
1153
- section?: string;
1154
- score?: number;
1155
- }
1156
- /**
1157
- * Chat display mode
1158
- * - closed: Only FAB button visible
1159
- * - floating: Floating panel (default)
1160
- * - sidebar: Full-height sidebar on the right (desktop only)
1161
- */
1162
- type ChatDisplayMode = 'closed' | 'floating' | 'sidebar';
1163
- /**
1164
- * Chat widget configuration
1165
- */
1166
- interface ChatWidgetConfig {
1167
- /** API endpoint for chat (default: /api/chat) */
1168
- apiEndpoint?: string;
1169
- /** Widget title */
1170
- title?: string;
1171
- /** Placeholder text for input */
1172
- placeholder?: string;
1173
- /** Initial greeting message */
1174
- greeting?: string;
1175
- /** Position on screen */
1176
- position?: 'bottom-right' | 'bottom-left';
1177
- /** Theme variant */
1178
- variant?: 'default' | 'minimal';
1179
- /** Auto-detect environment (dev/prod) for API endpoint. If false (default), always uses production */
1180
- autoDetectEnvironment?: boolean;
1181
- }
1182
- /**
1183
- * AI Chat API response
1184
- */
1185
- interface AIChatApiResponse {
1186
- success: boolean;
1187
- content?: string;
1188
- sources?: Array<{
1189
- id?: string;
1190
- title: string;
1191
- path: string;
1192
- url?: string;
1193
- section?: string;
1194
- score?: number;
1195
- }>;
1196
- threadId?: string;
1197
- usage?: {
1198
- promptTokens: number;
1199
- completionTokens: number;
1200
- totalTokens: number;
1201
- };
1202
- error?: string;
1203
- }
1204
- /**
1205
- * useAIChat hook options
1206
- */
1207
- interface UseAIChatOptions {
1208
- /** API endpoint (default: /api/ai/chat) */
1209
- apiEndpoint?: string;
1210
- /** Initial messages */
1211
- initialMessages?: AIChatMessage[];
1212
- /** Callback on error */
1213
- onError?: (error: Error) => void;
1214
- /** Enable streaming responses (default: true) */
1215
- enableStreaming?: boolean;
1216
- /** Thread ID for conversation (generated if not provided) */
1217
- threadId?: string;
1218
- /** User ID for conversation (generated if not provided) */
1219
- userId?: string;
1220
- }
1221
- /**
1222
- * useAIChat hook return type
1223
- */
1224
- interface UseAIChatReturn {
1225
- messages: AIChatMessage[];
1226
- isLoading: boolean;
1227
- error: Error | null;
1228
- threadId: string;
1229
- userId: string;
1230
- sendMessage: (content: string) => Promise<void>;
1231
- clearMessages: () => void;
1232
- stopStreaming: () => void;
1233
- }
1234
- /**
1235
- * Context type for chat messages triggered from different parts of the app
1236
- */
1237
- type McpChatContextType = 'error' | 'question' | 'explain' | 'advice' | 'help' | 'custom';
1238
- /**
1239
- * Event detail for mcp:chat:send custom event
1240
- */
1241
- interface McpChatEventDetail {
1242
- /** Message to send to chat */
1243
- message: string;
1244
- /** Optional context about the message */
1245
- context?: {
1246
- /** Type of context */
1247
- type?: McpChatContextType;
1248
- /** Additional data (error object, selected element, etc.) */
1249
- data?: Record<string, any>;
1250
- /** Source component/page that triggered the event */
1251
- source?: string;
1252
- };
1253
- /** Auto-send message after opening chat (default: true) */
1254
- autoSend?: boolean;
1255
- /** Open chat in specific mode (default: 'floating') */
1256
- displayMode?: ChatDisplayMode;
1257
- }
1258
- /**
1259
- * useMcpChat hook return type
1260
- */
1261
- interface UseMcpChatReturn {
1262
- /** Send message to chat from anywhere in the app */
1263
- sendToChat: (detail: McpChatEventDetail) => void;
1264
- /** Check if chat is available */
1265
- isChatAvailable: () => boolean;
1266
- }
1267
-
1268
- interface AIChatWidgetProps extends ChatWidgetConfig {
1269
- /** Custom class name for the container */
1270
- className?: string;
1271
- /** Enable streaming responses (default: true) */
1272
- enableStreaming?: boolean;
1273
- }
1274
- /**
1275
- * AI Chat Widget component
1276
- *
1277
- * AI-powered documentation assistant with streaming support.
1278
- * Uses Mastra agent backend for intelligent responses.
1279
- *
1280
- * Can be used in two ways:
1281
- * 1. Standalone (wraps itself in AIChatProvider)
1282
- * 2. Inside an AIChatProvider (uses context directly)
1283
- *
1284
- * @example
1285
- * ```tsx
1286
- * // Standalone usage (always uses production API)
1287
- * <AIChatWidget />
1288
- *
1289
- * // Auto-detect environment (dev/prod)
1290
- * <AIChatWidget autoDetectEnvironment={true} />
1291
- *
1292
- * // With provider for custom control
1293
- * <AIChatProvider apiEndpoint="/api/ai/chat">
1294
- * <MyApp />
1295
- * <AIChatWidget />
1296
- * </AIChatProvider>
1297
- * ```
1298
- */
1299
- declare const AIChatWidget: React$1.FC<AIChatWidgetProps>;
1300
-
1301
- declare const ChatPanel: React$1.MemoExoticComponent<() => react_jsx_runtime.JSX.Element>;
1302
-
1303
- interface MessageBubbleProps {
1304
- message: AIChatMessage;
1305
- isCompact?: boolean;
1306
- }
1307
- declare const MessageBubble: React$1.NamedExoticComponent<MessageBubbleProps>;
1308
-
1309
- interface AIMessageInputProps {
1310
- onSend: (message: string) => void;
1311
- disabled?: boolean;
1312
- isLoading?: boolean;
1313
- placeholder?: string;
1314
- maxRows?: number;
1315
- }
1316
- declare const AIMessageInput: React$1.NamedExoticComponent<AIMessageInputProps>;
1317
-
1318
- interface AskAIButtonProps extends Omit<ButtonProps, 'onClick'> {
1319
- /** Message to send to AI */
1320
- message: string;
1321
- /** Additional context data */
1322
- contextData?: Record<string, any>;
1323
- /** Source component name */
1324
- source?: string;
1325
- /** Auto-send message (default: true) */
1326
- autoSend?: boolean;
1327
- /** Show icon (default: true) */
1328
- showIcon?: boolean;
1329
- /** Callback after sending */
1330
- onSent?: () => void;
1331
- }
1332
- /**
1333
- * Universal AI chat trigger button
1334
- *
1335
- * @example Basic usage
1336
- * ```tsx
1337
- * <AskAIButton message="Explain this feature">
1338
- * Explain this
1339
- * </AskAIButton>
1340
- * ```
1341
- *
1342
- * @example With context
1343
- * ```tsx
1344
- * <AskAIButton
1345
- * message="Why is this failing?"
1346
- * contextData={{ error: error.stack }}
1347
- * source="ErrorBoundary"
1348
- * >
1349
- * Ask AI
1350
- * </AskAIButton>
1351
- * ```
1352
- */
1353
- declare function AskAIButton({ message, contextData, source, autoSend, showIcon, onSent, children, variant, size, className, ...buttonProps }: AskAIButtonProps): react_jsx_runtime.JSX.Element;
1354
-
1355
- /**
1356
- * AI Chat context state
1357
- */
1358
- interface AIChatContextState {
1359
- /** All chat messages */
1360
- messages: AIChatMessage[];
1361
- /** Whether a request is in progress */
1362
- isLoading: boolean;
1363
- /** Last error if any */
1364
- error: Error | null;
1365
- /** Whether chat panel is open */
1366
- isOpen: boolean;
1367
- /** Whether chat is minimized */
1368
- isMinimized: boolean;
1369
- /** Configuration */
1370
- config: ChatWidgetConfig;
1371
- /** Current display mode */
1372
- displayMode: ChatDisplayMode;
1373
- /** Is on mobile device */
1374
- isMobile: boolean;
1375
- /** Thread ID for conversation */
1376
- threadId: string;
1377
- /** User ID for conversation */
1378
- userId: string;
1379
- }
1380
- /**
1381
- * AI Chat context actions
1382
- */
1383
- interface AIChatContextActions {
1384
- /** Send a message */
1385
- sendMessage: (content: string) => Promise<void>;
1386
- /** Clear all messages */
1387
- clearMessages: () => void;
1388
- /** Open chat panel */
1389
- openChat: () => void;
1390
- /** Close chat panel */
1391
- closeChat: () => void;
1392
- /** Toggle chat panel */
1393
- toggleChat: () => void;
1394
- /** Minimize/restore chat */
1395
- toggleMinimize: () => void;
1396
- /** Set display mode */
1397
- setDisplayMode: (mode: ChatDisplayMode) => void;
1398
- /** Stop streaming response */
1399
- stopStreaming: () => void;
1400
- }
1401
- type AIChatContextValue = AIChatContextState & AIChatContextActions;
1402
- /**
1403
- * AI Chat provider props
1404
- */
1405
- interface AIChatProviderProps {
1406
- children: ReactNode;
1407
- /** API endpoint for AI chat (default: /api/ai/chat) */
1408
- apiEndpoint?: string;
1409
- /** Widget configuration */
1410
- config?: Partial<ChatWidgetConfig>;
1411
- /** Callback on error */
1412
- onError?: (error: Error) => void;
1413
- /** Enable streaming (default: true) */
1414
- enableStreaming?: boolean;
1415
- }
1416
- /**
1417
- * AI Chat provider component
1418
- * Uses useAIChat hook with server-side persistence
1419
- */
1420
- declare function AIChatProvider({ children, apiEndpoint, config: userConfig, onError, enableStreaming, }: AIChatProviderProps): react_jsx_runtime.JSX.Element;
1421
- /**
1422
- * Hook to access AI chat context
1423
- */
1424
- declare function useAIChatContext(): AIChatContextValue;
1425
- /**
1426
- * Hook to check if AI chat context is available
1427
- */
1428
- declare function useAIChatContextOptional(): AIChatContextValue | null;
1429
-
1430
- /**
1431
- * AI Chat hook with streaming support and server-side history
1432
- * All persistence is handled through API endpoints - no localStorage
1433
- */
1434
- declare function useAIChat(options: UseAIChatOptions): UseAIChatReturn;
1435
-
1436
- /**
1437
- * Configuration for chat layout management
1438
- */
1439
- interface ChatLayoutConfig {
1440
- /** Initial width of sidebar in pixels */
1441
- initialWidth?: number;
1442
- /** Animation duration in ms */
1443
- animationDuration?: number;
1444
- /** Element to push (defaults to body) */
1445
- pushTarget?: 'body' | 'main' | string;
1446
- }
1447
- /**
1448
- * Return type for useChatLayout hook
1449
- */
1450
- interface UseChatLayoutReturn {
1451
- /** Current sidebar width */
1452
- sidebarWidth: number;
1453
- /** Apply layout changes for mode */
1454
- applyLayout: (mode: ChatDisplayMode) => void;
1455
- /** Reset layout to default */
1456
- resetLayout: () => void;
1457
- /** Update sidebar width (for resize) */
1458
- updateWidth: (width: number) => void;
1459
- /** Start resize operation */
1460
- startResize: (e: React.MouseEvent) => void;
1461
- /** Whether currently resizing */
1462
- isResizing: boolean;
1463
- /** Get CSS for sidebar container */
1464
- getSidebarStyles: () => React.CSSProperties;
1465
- /** Get CSS for floating container */
1466
- getFloatingStyles: (position: 'bottom-right' | 'bottom-left') => React.CSSProperties;
1467
- /** Get CSS for FAB button */
1468
- getFabStyles: (position: 'bottom-right' | 'bottom-left') => React.CSSProperties;
1469
- }
1470
- /**
1471
- * Hook for managing chat layout embedding modes
1472
- *
1473
- * Handles:
1474
- * - Sidebar mode: pushes content left by adding margin to target element
1475
- * AND automatically adjusts all position:fixed elements with right:0
1476
- * - Floating mode: positions chat at bottom-right/left
1477
- * - Closed mode: just shows FAB button
1478
- *
1479
- * @example
1480
- * ```tsx
1481
- * const { applyLayout, getSidebarStyles, getFloatingStyles } = useChatLayout({
1482
- * sidebarWidth: 400,
1483
- * });
1484
- *
1485
- * useEffect(() => {
1486
- * applyLayout(displayMode);
1487
- * }, [displayMode]);
1488
- * ```
1489
- */
1490
- declare function useChatLayout(config?: ChatLayoutConfig): UseChatLayoutReturn;
1491
-
1492
- /**
1493
- * Hook to send messages to MCP Chat from anywhere in the app
1494
- *
1495
- * @example
1496
- * ```tsx
1497
- * function ErrorBoundary({ error }) {
1498
- * const { sendToChat } = useMcpChat();
1499
- *
1500
- * const explainError = () => {
1501
- * sendToChat({
1502
- * message: `Explain this error: ${error.message}`,
1503
- * context: {
1504
- * type: 'error',
1505
- * data: { error: error.stack },
1506
- * source: 'ErrorBoundary'
1507
- * }
1508
- * });
1509
- * };
1510
- *
1511
- * return <button onClick={explainError}>Explain Error</button>;
1512
- * }
1513
- * ```
1514
- */
1515
- declare function useMcpChat(): UseMcpChatReturn;
1516
-
1517
- interface PwaContextValue {
1518
- isIOS: boolean;
1519
- isAndroid: boolean;
1520
- isDesktop: boolean;
1521
- isSafari: boolean;
1522
- isChrome: boolean;
1523
- isFirefox: boolean;
1524
- isEdge: boolean;
1525
- isOpera: boolean;
1526
- isBrave: boolean;
1527
- isArc: boolean;
1528
- isVivaldi: boolean;
1529
- isYandex: boolean;
1530
- isSamsungBrowser: boolean;
1531
- isUCBrowser: boolean;
1532
- isChromium: boolean;
1533
- browserName: string;
1534
- isInstalled: boolean;
1535
- canPrompt: boolean;
1536
- install: () => Promise<InstallOutcome>;
1537
- }
1538
- interface PwaConfig {
1539
- enabled?: boolean;
1540
- }
1541
- declare function PwaProvider({ children, ...config }: PwaConfig & {
1542
- children: ReactNode;
1543
- }): react_jsx_runtime.JSX.Element;
1544
- /**
1545
- * Use install context
1546
- * Must be used within <PwaProvider>
1547
- */
1548
- declare function useInstall(): PwaContextValue;
1549
-
1550
- interface A2HSHintProps {
1551
- /**
1552
- * Additional class names for the container
1553
- */
1554
- className?: string;
1555
- /**
1556
- * Number of days before re-showing dismissed hint
1557
- * @default 3
1558
- * Set to null to never reset (show once forever)
1559
- */
1560
- resetAfterDays?: number | null;
1561
- /**
1562
- * Delay before showing hint (ms)
1563
- * @default 3000
1564
- */
1565
- delayMs?: number;
1566
- /**
1567
- * Demo mode - shows hint on all platforms with appropriate guides
1568
- * Production: only iOS Safari & Android Chrome
1569
- * Demo: shows on desktop too with desktop install guide
1570
- * @default false
1571
- */
1572
- demo?: boolean;
1573
- /**
1574
- * App logo URL to display in hint
1575
- * If not provided, uses Share icon
1576
- */
1577
- logo?: string;
1578
- }
1579
- declare function A2HSHint({ className, resetAfterDays, delayMs, demo, logo, }?: A2HSHintProps): react_jsx_runtime.JSX.Element;
1580
-
1581
- declare function IOSGuide(props: IOSGuideModalProps): react_jsx_runtime.JSX.Element;
1582
-
1583
- declare function DesktopGuide({ onDismiss, open }: IOSGuideModalProps): react_jsx_runtime.JSX.Element;
1584
-
1585
- /**
1586
- * Options for useIsPWA hook
1587
- */
1588
- interface UseIsPWAOptions {
1589
- /**
1590
- * Use reliable check with additional validation for desktop browsers
1591
- * This prevents false positives on Safari macOS "Add to Dock"
1592
- * @default false
1593
- */
1594
- reliable?: boolean;
1595
- }
1596
- /**
1597
- * Hook to detect if app is running as PWA (standalone mode)
1598
- *
1599
- * @param options - Configuration options
1600
- * @returns true if app is running as PWA
1601
- */
1602
- declare function useIsPWA(options?: UseIsPWAOptions): boolean;
1603
- /**
1604
- * Clear isPWA cache
1605
- *
1606
- * Useful for testing or when you want to force a re-check
1607
- *
1608
- * @example
1609
- * ```typescript
1610
- * import { clearIsPWACache } from '@djangocfg/layouts/snippets';
1611
- * clearIsPWACache();
1612
- * window.location.reload();
1613
- * ```
1614
- */
1615
- declare function clearIsPWACache(): void;
1616
-
1617
- /**
1618
- * Platform Detection Utilities
1619
- *
1620
- * Centralized utilities for detecting PWA state, platform, and capabilities.
1621
- * Used by hooks to avoid code duplication.
1622
- */
1623
- /**
1624
- * Check if running as PWA (standalone mode)
1625
- *
1626
- * Checks if the app is running in standalone mode (added to home screen).
1627
- * This is the primary indicator that a PWA has been installed.
1628
- *
1629
- * @returns true if app is running in standalone mode
1630
- *
1631
- * @example
1632
- * ```typescript
1633
- * if (isStandalone()) {
1634
- * console.log('Running as PWA');
1635
- * }
1636
- * ```
1637
- */
1638
- declare function isStandalone(): boolean;
1639
- /**
1640
- * Check if device is mobile
1641
- *
1642
- * @returns true if device is mobile (iOS, Android, etc.)
1643
- */
1644
- declare function isMobileDevice(): boolean;
1645
- /**
1646
- * Check if web app manifest exists and is valid
1647
- *
1648
- * @returns true if manifest link exists in document head
1649
- */
1650
- declare function hasValidManifest(): boolean;
1651
- /**
1652
- * Reliable check for PWA mode with edge case handling
1653
- *
1654
- * This function provides additional validation for desktop browsers
1655
- * to avoid false positives (e.g., Safari macOS "Add to Dock").
1656
- *
1657
- * For mobile devices, standard standalone check is sufficient.
1658
- * For desktop, additionally validates that a manifest exists.
1659
- *
1660
- * @returns true if app is running as a genuine PWA
1661
- *
1662
- * @example
1663
- * ```typescript
1664
- * // Use this for more reliable detection
1665
- * if (isStandaloneReliable()) {
1666
- * console.log('Definitely running as PWA');
1667
- * }
1668
- * ```
1669
- */
1670
- declare function isStandaloneReliable(): boolean;
1671
- /**
1672
- * Get display mode from media query
1673
- *
1674
- * @returns Current display mode: 'standalone', 'fullscreen', 'minimal-ui', or 'browser'
1675
- */
1676
- declare function getDisplayMode(): 'standalone' | 'fullscreen' | 'minimal-ui' | 'browser';
1677
- /**
1678
- * Create a media query listener for display-mode changes
1679
- *
1680
- * @param callback - Function to call when display mode changes
1681
- * @returns Cleanup function to remove listener
1682
- *
1683
- * @example
1684
- * ```typescript
1685
- * const cleanup = onDisplayModeChange((isStandalone) => {
1686
- * console.log('Display mode changed:', isStandalone);
1687
- * });
1688
- *
1689
- * // Later: cleanup();
1690
- * ```
1691
- */
1692
- declare function onDisplayModeChange(callback: (isStandalone: boolean) => void): () => void;
1693
-
1694
- /**
1695
- * LocalStorage utilities for PWA install state persistence
1696
- */
1697
-
1698
- /**
1699
- * Clear all PWA install data
1700
- */
1701
- declare function clearAllPWAInstallData(): void;
1702
-
1703
- interface PushMessage {
1704
- id: string;
1705
- title: string;
1706
- body: string;
1707
- icon?: string;
1708
- badge?: string;
1709
- tag?: string;
1710
- timestamp: number;
1711
- data?: Record<string, unknown>;
1712
- }
1713
- interface DjangoPushContextValue {
1714
- isSupported: boolean;
1715
- permission: NotificationPermission;
1716
- isSubscribed: boolean;
1717
- subscription: PushSubscription | null;
1718
- isLoading: boolean;
1719
- error: Error | null;
1720
- pushes: PushMessage[];
1721
- subscribe: () => Promise<boolean>;
1722
- unsubscribe: () => Promise<boolean>;
1723
- sendTestPush: (message: {
1724
- title: string;
1725
- body: string;
1726
- url?: string;
1727
- }) => Promise<boolean>;
1728
- sendPush: (message: Omit<PushMessage, 'id' | 'timestamp'>) => Promise<void>;
1729
- clearPushes: () => void;
1730
- removePush: (id: string) => void;
1731
- }
1732
- interface DjangoPushProviderProps extends PushNotificationOptions {
1733
- children: React$1.ReactNode;
1734
- /**
1735
- * Auto-subscribe on mount if permission granted
1736
- * @default false
1737
- */
1738
- autoSubscribe?: boolean;
1739
- /**
1740
- * Callback when subscription created
1741
- */
1742
- onSubscribed?: (subscription: PushSubscription) => void;
1743
- /**
1744
- * Callback when subscription failed
1745
- */
1746
- onSubscribeError?: (error: Error) => void;
1747
- /**
1748
- * Callback when unsubscribed
1749
- */
1750
- onUnsubscribed?: () => void;
1751
- }
1752
- /**
1753
- * Provider for Django push notifications
1754
- */
1755
- declare function DjangoPushProvider({ children, vapidPublicKey, autoSubscribe, onSubscribed, onSubscribeError, onUnsubscribed, }: DjangoPushProviderProps): react_jsx_runtime.JSX.Element;
1756
- /**
1757
- * Hook to access Django push context
1758
- */
1759
- declare function useDjangoPushContext(): DjangoPushContextValue;
1760
-
1761
- interface PushPromptProps extends PushNotificationOptions {
1762
- /**
1763
- * Only show if PWA is installed
1764
- * @default true
1765
- */
1766
- requirePWA?: boolean;
1767
- /**
1768
- * Delay before showing prompt (ms)
1769
- * @default 5000
1770
- */
1771
- delayMs?: number;
1772
- /**
1773
- * Number of days before re-showing dismissed prompt
1774
- * @default 7
1775
- */
1776
- resetAfterDays?: number;
1777
- /**
1778
- * Callback when push is enabled
1779
- */
1780
- onEnabled?: () => void;
1781
- /**
1782
- * Callback when push is dismissed
1783
- */
1784
- onDismissed?: () => void;
1785
- }
1786
- declare function PushPrompt({ vapidPublicKey, subscribeEndpoint, requirePWA, delayMs, resetAfterDays, onEnabled, onDismissed, }: PushPromptProps): react_jsx_runtime.JSX.Element;
1787
-
1788
- declare function usePushNotifications(options?: PushNotificationOptions): {
1789
- subscribe: () => Promise<PushSubscription | null>;
1790
- unsubscribe: () => Promise<boolean>;
1791
- isSupported: boolean;
1792
- permission: NotificationPermission;
1793
- isSubscribed: boolean;
1794
- subscription: PushSubscription | null;
1795
- };
1796
-
1797
- interface UseDjangoPushOptions extends PushNotificationOptions {
1798
- /**
1799
- * Callback when subscription created
1800
- */
1801
- onSubscribed?: (subscription: PushSubscription) => void;
1802
- /**
1803
- * Callback when subscription failed
1804
- */
1805
- onSubscribeError?: (error: Error) => void;
1806
- /**
1807
- * Callback when unsubscribed
1808
- */
1809
- onUnsubscribed?: () => void;
1810
- }
1811
- interface UseDjangoPushReturn {
1812
- isSupported: boolean;
1813
- permission: NotificationPermission;
1814
- isSubscribed: boolean;
1815
- subscription: PushSubscription | null;
1816
- isLoading: boolean;
1817
- error: Error | null;
1818
- subscribe: () => Promise<boolean>;
1819
- unsubscribe: () => Promise<boolean>;
1820
- sendTestPush: (message: {
1821
- title: string;
1822
- body: string;
1823
- url?: string;
1824
- }) => Promise<boolean>;
1825
- }
1826
- /**
1827
- * Hook for Django-CFG push notifications integration
1828
- */
1829
- declare function useDjangoPush(options: UseDjangoPushOptions): UseDjangoPushReturn;
1830
-
1831
- /**
1832
- * Push Notifications Configuration
1833
- *
1834
- * Centralized constants for push notifications functionality.
1835
- *
1836
- * SECURITY NOTE:
1837
- * - VAPID_PRIVATE_KEY should NEVER be in frontend code
1838
- * - Private keys must only exist in backend/API routes
1839
- * - Frontend only needs the public key (NEXT_PUBLIC_* env vars)
1840
- * - VAPID_MAILTO should also remain on backend only
1841
- */
1842
- declare const DEFAULT_VAPID_PUBLIC_KEY: string;
1843
-
1844
- /**
1845
- * VAPID Key Utilities
1846
- *
1847
- * Provides validation and conversion utilities for VAPID public keys
1848
- * used in push notification subscriptions.
1849
- *
1850
- * VAPID keys must be:
1851
- * - Base64url encoded
1852
- * - 65 bytes after decoding (P-256 uncompressed public key)
1853
- * - Start with 0x04 (uncompressed point indicator)
1854
- */
1855
- /**
1856
- * Custom error class for VAPID key validation failures
1857
- */
1858
- declare class VapidKeyError extends Error {
1859
- readonly code: VapidKeyErrorCode;
1860
- constructor(message: string, code: VapidKeyErrorCode);
1861
- }
1862
- /**
1863
- * Error codes for VAPID key validation
1864
- */
1865
- type VapidKeyErrorCode = 'VAPID_EMPTY' | 'VAPID_INVALID_TYPE' | 'VAPID_INVALID_BASE64' | 'VAPID_INVALID_LENGTH' | 'VAPID_INVALID_FORMAT';
1866
- /**
1867
- * Convert base64url VAPID public key to Uint8Array
1868
- *
1869
- * Validates and converts a VAPID public key from base64url format
1870
- * to Uint8Array for use with PushManager.subscribe().
1871
- *
1872
- * @param base64String - VAPID public key in base64url format
1873
- * @returns Uint8Array ready for pushManager.subscribe()
1874
- * @throws VapidKeyError if key is invalid
1875
- *
1876
- * @example
1877
- * ```typescript
1878
- * try {
1879
- * const key = urlBase64ToUint8Array(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY);
1880
- * await registration.pushManager.subscribe({
1881
- * userVisibleOnly: true,
1882
- * applicationServerKey: key,
1883
- * });
1884
- * } catch (e) {
1885
- * if (e instanceof VapidKeyError) {
1886
- * console.error('Invalid VAPID key:', e.message, e.code);
1887
- * }
1888
- * }
1889
- * ```
1890
- */
1891
- declare function urlBase64ToUint8Array(base64String: string): Uint8Array;
1892
- /**
1893
- * Validate VAPID key without conversion
1894
- *
1895
- * Checks if a VAPID key is valid without converting it.
1896
- * Useful for validation before attempting subscription.
1897
- *
1898
- * @param base64String - VAPID public key to validate
1899
- * @returns true if key is valid
1900
- *
1901
- * @example
1902
- * ```typescript
1903
- * if (isValidVapidKey(vapidKey)) {
1904
- * // Proceed with subscription
1905
- * } else {
1906
- * console.error('Invalid VAPID key configuration');
1907
- * }
1908
- * ```
1909
- */
1910
- declare function isValidVapidKey(base64String: string): boolean;
1911
- /**
1912
- * Get VAPID key information for debugging
1913
- *
1914
- * Returns detailed information about a VAPID key for troubleshooting.
1915
- *
1916
- * @param base64String - VAPID public key to inspect
1917
- * @returns Key information object
1918
- *
1919
- * @example
1920
- * ```typescript
1921
- * const info = getVapidKeyInfo(process.env.NEXT_PUBLIC_VAPID_PUBLIC_KEY);
1922
- * console.log('VAPID Key Info:', info);
1923
- * // {
1924
- * // valid: true,
1925
- * // length: 65,
1926
- * // firstByte: '0x04',
1927
- * // format: 'P-256 uncompressed'
1928
- * // }
1929
- * ```
1930
- */
1931
- declare function getVapidKeyInfo(base64String: string): {
1932
- valid: boolean;
1933
- length?: number;
1934
- firstByte?: string;
1935
- format?: string;
1936
- error?: string;
1937
- errorCode?: VapidKeyErrorCode;
1938
- };
1939
- /**
1940
- * Safe VAPID key conversion with error handling
1941
- *
1942
- * Attempts to convert a VAPID key with detailed error logging.
1943
- * Returns null on failure instead of throwing.
1944
- *
1945
- * @param base64String - VAPID public key
1946
- * @param onError - Optional error callback
1947
- * @returns Uint8Array or null if conversion fails
1948
- *
1949
- * @example
1950
- * ```typescript
1951
- * const key = safeUrlBase64ToUint8Array(vapidKey, (error) => {
1952
- * console.error('VAPID conversion failed:', error.message, error.code);
1953
- * });
1954
- *
1955
- * if (key) {
1956
- * // Use key for subscription
1957
- * }
1958
- * ```
1959
- */
1960
- declare function safeUrlBase64ToUint8Array(base64String: string, onError?: (error: VapidKeyError) => void): Uint8Array | null;
1961
-
1962
- /**
1963
- * Clear all push notification data
1964
- */
1965
- declare function clearAllPushData(): void;
1966
-
1967
- interface ClientOnlyProps {
1968
- children: ReactNode;
1969
- /**
1970
- * Fallback to show during SSR and initial mount
1971
- * @default Preloader with "Loading..." text
1972
- */
1973
- fallback?: ReactNode;
1974
- }
1975
- /**
1976
- * ClientOnly - Prevents SSR hydration mismatch
1977
- *
1978
- * Use this to wrap components that:
1979
- * - Access browser-only APIs (window, localStorage, etc.)
1980
- * - Have different initial state on server vs client
1981
- * - Use authentication state that differs between SSR and CSR
1982
- */
1983
- declare function ClientOnly({ children, fallback, }: ClientOnlyProps): react_jsx_runtime.JSX.Element;
1984
-
1985
- interface JsonLdProps {
1986
- data: Record<string, any> | Record<string, any>[];
1987
- }
1988
- /**
1989
- * JsonLd Component
1990
- *
1991
- * Renders JSON-LD structured data for SEO.
1992
- * Use this for schema.org markup (Organization, WebSite, FAQPage, etc.)
1993
- *
1994
- * @example
1995
- * ```tsx
1996
- * <JsonLd data={{
1997
- * "@context": "https://schema.org",
1998
- * "@type": "Organization",
1999
- * "name": "My Company"
2000
- * }} />
2001
- * ```
2002
- */
2003
- declare function JsonLd({ data }: JsonLdProps): react_jsx_runtime.JSX.Element;
2004
-
2005
- interface LucideIconProps extends Omit<React$1.SVGProps<SVGSVGElement>, 'children'> {
2006
- /**
2007
- * Icon name (string) or icon component (LucideIcon)
2008
- * If string, will be resolved from lucide-react
2009
- * If component, will be used directly
2010
- */
2011
- icon?: LucideIcon$1 | string;
2012
- /**
2013
- * Fallback icon if name not found
2014
- * @default CloudLightning
2015
- */
2016
- fallback?: LucideIcon$1;
2017
- /**
2018
- * Additional CSS classes
2019
- */
2020
- className?: string;
2021
- }
2022
- /**
2023
- * LucideIcon Component
2024
- *
2025
- * Renders a Lucide icon either by name (string) or by component reference.
2026
- * Automatically resolves icon names from lucide-react package.
2027
- *
2028
- * Usage:
2029
- * ```tsx
2030
- * // By name (string)
2031
- * <LucideIcon icon="CloudLightning" className="w-4 h-4" />
2032
- *
2033
- * // By component
2034
- * import { CloudLightning } from 'lucide-react';
2035
- * <LucideIcon icon={CloudLightning} className="w-4 h-4" />
2036
- * ```
2037
- */
2038
- declare function LucideIcon({ icon, fallback, className, ...props }: LucideIconProps): react_jsx_runtime.JSX.Element;
2039
-
2040
- interface SuspenseProps {
2041
- children: ReactNode;
2042
- fallback?: ReactNode;
2043
- }
2044
- declare function Suspense({ children, fallback }: SuspenseProps): react_jsx_runtime.JSX.Element;
2045
-
2046
- interface ErrorBoundaryProps {
2047
- children: ReactNode;
2048
- supportEmail?: string;
2049
- onError?: (error: Error, errorInfo: ErrorInfo) => void;
2050
- }
2051
- interface ErrorBoundaryState {
2052
- hasError: boolean;
2053
- error: Error | null;
2054
- }
2055
- declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
2056
- constructor(props: ErrorBoundaryProps);
2057
- static getDerivedStateFromError(error: Error): ErrorBoundaryState;
2058
- componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
2059
- render(): string | number | bigint | boolean | Iterable<React$1.ReactNode> | Promise<string | number | bigint | boolean | React$1.ReactPortal | React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>> | Iterable<React$1.ReactNode>> | react_jsx_runtime.JSX.Element;
2060
- }
2061
-
2062
- interface ErrorLayoutProps {
2063
- /** Error code (e.g., "404", "500", "403") - if provided, auto-configures title/description/icon */
2064
- code?: string | number;
2065
- /** Error title (auto-generated from code if not provided) */
2066
- title?: string;
2067
- /** Error description (auto-generated from code if not provided) */
2068
- description?: string;
2069
- /** Custom action buttons */
2070
- actions?: React$1.ReactNode;
2071
- /** Show default actions (back, home) */
2072
- showDefaultActions?: boolean;
2073
- /** Custom illustration/icon (auto-generated from code if not provided) */
2074
- illustration?: React$1.ReactNode;
2075
- /** Support email for contact link */
2076
- supportEmail?: string;
2077
- }
2078
- /**
2079
- * ErrorLayout Component
2080
- */
2081
- declare function ErrorLayout({ code, title, description, actions, showDefaultActions, illustration, supportEmail, }: ErrorLayoutProps): react_jsx_runtime.JSX.Element;
2082
-
2083
- /**
2084
- * Universal Error Configuration
2085
- *
2086
- * Provides standard error content for common HTTP status codes
2087
- * Use this to maintain consistency across error pages
2088
- *
2089
- * NOTE: Only returns primitives (title, description) - NO React components
2090
- * This ensures safe serialization during prerendering
2091
- */
2092
- interface ErrorContent {
2093
- title: string;
2094
- description: string;
2095
- }
2096
- /**
2097
- * Get standardized error content based on status code
2098
- *
2099
- * @param statusCode - HTTP status code or custom error type
2100
- * @returns Error content configuration (title and description only)
2101
- *
2102
- * @example
2103
- * ```tsx
2104
- * const { title, description } = getErrorContent(404);
2105
- * <ErrorLayout title={title} description={description} code={404} />
2106
- * ```
2107
- */
2108
- declare function getErrorContent(statusCode?: number | string): ErrorContent;
2109
- /**
2110
- * Common error codes as constants
2111
- */
2112
- declare const ERROR_CODES: {
2113
- readonly BAD_REQUEST: 400;
2114
- readonly UNAUTHORIZED: 401;
2115
- readonly FORBIDDEN: 403;
2116
- readonly NOT_FOUND: 404;
2117
- readonly TIMEOUT: 408;
2118
- readonly SERVER_ERROR: 500;
2119
- readonly BAD_GATEWAY: 502;
2120
- readonly SERVICE_UNAVAILABLE: 503;
2121
- readonly GATEWAY_TIMEOUT: 504;
2122
- };
2123
-
2124
- interface RedirectPageProps {
2125
- /**
2126
- * Path to redirect to when user is authenticated
2127
- * @default '/private'
2128
- */
2129
- authenticatedPath?: string;
2130
- /**
2131
- * Path to redirect to when user is not authenticated
2132
- * @default '/auth'
2133
- */
2134
- unauthenticatedPath?: string;
2135
- /**
2136
- * Custom loading text
2137
- * @default 'Loading...'
2138
- */
2139
- loadingText?: string;
2140
- }
2141
- /**
2142
- * RedirectPage - Root page component that handles authentication redirect
2143
- *
2144
- * Redirects authenticated users to authenticatedPath, otherwise to unauthenticatedPath
2145
- *
2146
- * Usage:
2147
- * ```tsx
2148
- * // app/page.tsx
2149
- * import { RedirectPage } from '@djangocfg/layouts/components';
2150
- *
2151
- * export default function Page() {
2152
- * return (
2153
- * <RedirectPage
2154
- * authenticatedPath="/private"
2155
- * unauthenticatedPath="/auth"
2156
- * />
2157
- * );
2158
- * }
2159
- * ```
2160
- */
2161
- declare function RedirectPage({ authenticatedPath, unauthenticatedPath, loadingText, }: RedirectPageProps): react_jsx_runtime.JSX.Element;
2162
-
2163
- interface ErrorTrackingProviderProps {
2164
- children: ReactNode;
2165
- validation?: Partial<ValidationErrorConfig>;
2166
- cors?: Partial<CORSErrorConfig>;
2167
- network?: Partial<NetworkErrorConfig>;
2168
- centrifugo?: Partial<CentrifugoErrorConfig>;
2169
- onError?: (error: ErrorDetail) => boolean | void;
2170
- }
2171
- /**
2172
- * Universal Error Tracking Provider
2173
- *
2174
- * Tracks all error types with a single provider
2175
- */
2176
- declare function ErrorTrackingProvider({ children, validation: userValidationConfig, cors: userCorsConfig, network: userNetworkConfig, centrifugo: userCentrifugoConfig, onError, }: ErrorTrackingProviderProps): react_jsx_runtime.JSX.Element;
2177
- /**
2178
- * useErrors Hook
2179
- *
2180
- * Access errors from any component
2181
- *
2182
- * @example
2183
- * ```tsx
2184
- * function ErrorPanel() {
2185
- * const { errors, validationErrors, clearErrors } = useErrors();
2186
- *
2187
- * return (
2188
- * <div>
2189
- * <h3>Errors ({errors.length})</h3>
2190
- * <h4>Validation: {validationErrors.length}</h4>
2191
- * <button onClick={clearErrors}>Clear All</button>
2192
- * </div>
2193
- * );
2194
- * }
2195
- * ```
2196
- */
2197
- declare function useErrors(): ErrorTrackingContextValue;
2198
-
2199
- interface ErrorButtonsProps {
2200
- detail: ValidationErrorDetail | CORSErrorDetail | NetworkErrorDetail | CentrifugoErrorDetail;
2201
- }
2202
- /**
2203
- * Universal error buttons
2204
- */
2205
- declare function ErrorButtons({ detail }: ErrorButtonsProps): react_jsx_runtime.JSX.Element;
2206
-
2207
- /**
2208
- * ErrorToast - Universal toast for all error types
2209
- *
2210
- * Formats validation, CORS, and network errors with appropriate styling
2211
- */
2212
-
2213
- /**
2214
- * Create toast options for any error type
2215
- */
2216
- declare function createErrorToast(detail: ValidationErrorDetail | CORSErrorDetail | NetworkErrorDetail | CentrifugoErrorDetail, config: Required<ValidationErrorConfig | CORSErrorConfig | NetworkErrorConfig | CentrifugoErrorConfig>): {
2217
- title: string;
2218
- description: React$1.ReactNode;
2219
- variant: "destructive";
2220
- duration: number;
2221
- };
2222
-
2223
- /**
2224
- * Error Formatters
2225
- *
2226
- * Format different error types for display and copying
2227
- */
2228
-
2229
- /**
2230
- * Format Zod error issues for display
2231
- */
2232
- declare function formatZodIssues(error: ZodError, maxIssues?: number): string;
2233
- /**
2234
- * Format validation error for clipboard
2235
- */
2236
- declare function formatValidationErrorForClipboard(detail: ValidationErrorDetail): string;
2237
- /**
2238
- * Format CORS error for clipboard
2239
- */
2240
- declare function formatCORSErrorForClipboard(detail: CORSErrorDetail): string;
2241
- /**
2242
- * Format network error for clipboard
2243
- */
2244
- declare function formatNetworkErrorForClipboard(detail: NetworkErrorDetail): string;
2245
- /**
2246
- * Format centrifugo error for clipboard
2247
- */
2248
- declare function formatCentrifugoErrorForClipboard(detail: CentrifugoErrorDetail): string;
2249
- /**
2250
- * Extract domain from URL
2251
- */
2252
- declare function extractDomain(url: string): string;
2253
- /**
2254
- * Format error title based on type
2255
- */
2256
- declare function formatErrorTitle(detail: ValidationErrorDetail | CORSErrorDetail | NetworkErrorDetail | CentrifugoErrorDetail): string;
2257
-
2258
- interface CurlOptions {
2259
- method: string;
2260
- path: string;
2261
- token?: string;
2262
- body?: any;
2263
- headers?: Record<string, string>;
2264
- baseUrl?: string;
2265
- queryParams?: Record<string, string>;
2266
- }
2267
- /**
2268
- * Get authentication token from localStorage
2269
- */
2270
- declare function getAuthToken(): string | null;
2271
- /**
2272
- * Generate cURL command from request details
2273
- */
2274
- declare function generateCurl(options: CurlOptions): string;
2275
- /**
2276
- * Generate cURL from validation error details
2277
- * Auto-fetches token from localStorage
2278
- */
2279
- declare function generateCurlFromError(detail: {
2280
- method: string;
2281
- path: string;
2282
- response?: any;
2283
- }): string;
2284
-
2285
- /**
2286
- * Frontend configuration from environment variables
2287
- */
2288
- declare const config: {
2289
- /**
2290
- * Development mode flag
2291
- * In development mode, any OTP code is accepted for authentication
2292
- */
2293
- readonly isDevelopment: boolean;
2294
- };
2295
-
2296
- declare const logger: consola.ConsolaInstance;
2297
- /**
2298
- * Auth-specific logger
2299
- */
2300
- declare const authLogger: consola.ConsolaInstance;
2301
- /**
2302
- * Chat-specific logger
2303
- */
2304
- declare const chatLogger: consola.ConsolaInstance;
2305
- /**
2306
- * Support-specific logger
2307
- */
2308
- declare const supportLogger: consola.ConsolaInstance;
2309
- /**
2310
- * Payments-specific logger
2311
- */
2312
- declare const paymentsLogger: consola.ConsolaInstance;
2313
- /**
2314
- * Profile-specific logger
2315
- */
2316
- declare const profileLogger: consola.ConsolaInstance;
2317
- /**
2318
- * Dashboard-specific logger
2319
- */
2320
- declare const dashboardLogger: consola.ConsolaInstance;
2321
-
2322
- /**
2323
- * Legal page types
2324
- */
2325
- interface LegalPageSection {
2326
- title: string;
2327
- content: string | string[];
2328
- }
2329
- interface LegalPageConfig {
2330
- title: string;
2331
- lastUpdated?: string | Date;
2332
- sections: LegalPageSection[];
2333
- }
2334
-
2335
- interface LegalPageProps {
2336
- config: LegalPageConfig;
2337
- className?: string;
2338
- }
2339
- /**
2340
- * LegalPage Component
2341
- */
2342
- declare function LegalPage({ config, className }: LegalPageProps): react_jsx_runtime.JSX.Element;
2343
-
2344
- interface LegalPageComponentProps {
2345
- config?: LegalPageConfig;
2346
- }
2347
- /**
2348
- * Privacy Policy Page
2349
- */
2350
- declare function PrivacyPage({ config }?: LegalPageComponentProps): react_jsx_runtime.JSX.Element;
2351
- /**
2352
- * Terms of Service Page
2353
- */
2354
- declare function TermsPage({ config }?: LegalPageComponentProps): react_jsx_runtime.JSX.Element;
2355
- /**
2356
- * Cookie Policy Page
2357
- */
2358
- declare function CookiesPage({ config }?: LegalPageComponentProps): react_jsx_runtime.JSX.Element;
2359
- /**
2360
- * Security Policy Page
2361
- */
2362
- declare function SecurityPage({ config }?: LegalPageComponentProps): react_jsx_runtime.JSX.Element;
2363
-
2364
- /**
2365
- * Default legal page configurations
2366
- *
2367
- * Pre-configured content for common legal pages
2368
- * Can be customized or extended as needed
2369
- */
2370
-
2371
- declare const privacyConfig: LegalPageConfig;
2372
- declare const termsConfig: LegalPageConfig;
2373
- declare const cookiesConfig: LegalPageConfig;
2374
- declare const securityConfig: LegalPageConfig;
2375
-
2376
- export { A2HSHint, type AIChatApiResponse, type AIChatContextActions, type AIChatContextState, type AIChatContextValue, type AIChatMessage, AIChatProvider, type AIChatProviderProps, type AIChatSource, AIChatWidget, type AIChatWidgetProps, AIMessageInput, type AIMessageInputProps, type AIMessageRole, AUTH_EVENTS, AdminLayout, type AdminLayoutProps, Analytics, AnalyticsCategory, type AnalyticsCategoryType, type AnalyticsConfig, AnalyticsEvent, type AnalyticsEventType, AnalyticsProvider, type AndroidInstallButtonProps, AppLayout, type AppLayoutProps, AskAIButton, type AskAIButtonProps, AuthDialog, type AuthEventType, type AuthFailurePayload, AuthFormProvider, AuthHelp, AuthLayout, type AuthSuccessPayload, BaseApp, type BaseAppProps, type BaseLayoutProps, type BeforeInstallPromptEvent, type BreadcrumbItem, type CORSErrorConfig, type CORSErrorDetail, type CentrifugoConfig, type CentrifugoErrorConfig, type CentrifugoErrorDetail, type ChatLayoutConfig, ChatPanel, type ChatWidgetConfig, ClientOnly, type ClientOnlyProps, CookiesPage, type CurlOptions, DEFAULT_VAPID_PUBLIC_KEY, DIALOG_EVENTS, DesktopGuide, DjangoCFGLogo, DjangoPushProvider, ERROR_CODES, ErrorBoundary, type ErrorBoundaryConfig, ErrorButtons, type ErrorContent, type ErrorDetail, ErrorLayout, type ErrorLayoutProps, type ErrorTrackingConfig, type ErrorTrackingContextValue, ErrorTrackingProvider, FooterBottom, type FooterConfig, type FooterLink$1 as FooterLink, type FooterMenuSection$1 as FooterMenuSection, FooterMenuSections, FooterProjectInfo, type FooterSocialLinks$1 as FooterSocialLinks, FooterSocialLinksComponent, type HeaderConfig, IOSGuide, type IOSGuideModalProps, type IOSGuideState, IdentifierForm, type InstallContextType, type InstallManagerProps, type InstallOutcome, type InstallPromptState, type InstallStep, JsonLd, type LayoutMode, LegalPage, type LegalPageComponentProps, type LegalPageConfig, type LegalPageProps, type LegalPageSection, LucideIcon, type LucideIconProps, type McpChatConfig, type McpChatContextType, type McpChatEventDetail, MessageBubble, type MessageBubbleProps, type NavigationItem, type NavigationSection, type NetworkErrorConfig, type NetworkErrorDetail, OAuthCallback, type OAuthCallbackProps, OAuthProviders, OTPForm, type OpenAuthDialogPayload, type PlatformInfo, PrivacyPage, PrivateLayout, type PrivateLayoutProps, ProfileLayout, PublicFooter, type PublicFooterProps, PublicLayout, type PublicLayoutProps, type PushMessage, type PushNotificationOptions, type PushNotificationState, type PushNotificationsConfig, PushPrompt, DjangoPushProvider as PushProvider, type PwaInstallConfig, PwaProvider, RedirectPage, type RedirectPageProps, type SWRConfigOptions, SecurityPage, type SidebarConfig, type SidebarItem, type StoredError, Suspense, TermsPage, type ThemeConfig, type UseAIChatOptions, type UseAIChatReturn, type UseChatLayoutReturn, type UseIsPWAOptions, type UseMcpChatReturn, UserMenu, type UserMenuConfig, type UserMenuGroup, type UserMenuItem, type UserMenuProps, type ValidationErrorConfig, type ValidationErrorDetail, VapidKeyError, type VapidKeyErrorCode, authLogger, chatLogger, clearAllPWAInstallData, clearAllPushData, clearIsPWACache, config, cookiesConfig, createErrorToast, dashboardLogger, extractDomain, formatCORSErrorForClipboard, formatCentrifugoErrorForClipboard, formatErrorTitle, formatNetworkErrorForClipboard, formatValidationErrorForClipboard, formatZodIssues, generateBreadcrumbsFromPath, generateCurl, generateCurlFromError, getAuthToken, getDisplayMode, getErrorContent, getVapidKeyInfo, hasValidManifest, isMobileDevice, isStandalone, isStandaloneReliable, isValidVapidKey, logger, onDisplayModeChange, paymentsLogger, privacyConfig, profileLogger, safeUrlBase64ToUint8Array, securityConfig, supportLogger, termsConfig, urlBase64ToUint8Array, useAIChat, useAIChatContext, useAIChatContextOptional, useAnalytics, useAuthDialog, useAuthFormContext, useChatLayout, useDjangoPush, useDjangoPushContext, useErrors, useInstall, useIsPWA, useMcpChat, useDjangoPushContext as usePush, usePushNotifications };