@djangocfg/layouts 2.1.167 → 2.1.169

package/README.md

@@ -466,16 +466,37 @@ export default function Page() {
 import {
   ErrorTrackingProvider,
   useErrors,
-  ErrorButtons,
-  ErrorToast
-} from '@djangocfg/layouts/components/errors/ErrorsTracker';
+  useErrorEmitter,
+  emitRuntimeError,
+} from '@djangocfg/layouts';
 
+// Wrap your app
 <ErrorTrackingProvider>
   <YourApp />
 </ErrorTrackingProvider>
 
-// In components
-const { addError, clearErrors, errors } = useErrors();
+// In React components - use hook
+function MyComponent() {
+  const { emitError } = useErrorEmitter('MyComponent');
+
+  try {
+    doSomething();
+  } catch (error) {
+    emitError('Something failed', error);
+  }
+}
+
+// Outside React (utilities, libraries) - use standalone function
+import { emitRuntimeError } from '@djangocfg/layouts';
+
+try {
+  doSomething();
+} catch (error) {
+  emitRuntimeError('MyUtility', 'Something failed', error);
+}
+
+// Access errors
+const { errors, clearErrors } = useErrors();
 ```
 
 ### Update Notifier

package/package.json

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

package/src/components/errors/ErrorsTracker/components/ErrorToast.tsx

@@ -16,10 +16,12 @@ import type {
   CORSErrorDetail,
   NetworkErrorDetail,
   CentrifugoErrorDetail,
+  RuntimeErrorDetail,
   ValidationErrorConfig,
   CORSErrorConfig,
   NetworkErrorConfig,
   CentrifugoErrorConfig,
+  RuntimeErrorConfig,
 } from '../types';
 /**
  * Build validation error description
@@ -151,12 +153,32 @@ function buildCentrifugoDescription(
   );
 }
 
+/**
+ * Build runtime error description
+ */
+function buildRuntimeDescription(
+  detail: RuntimeErrorDetail,
+  config: Required<RuntimeErrorConfig>
+): React.ReactNode {
+  return (
+    <div className="flex flex-col gap-2 text-sm">
+      {config.showSource && (
+        <div className="font-mono text-xs opacity-90">
+          Source: {detail.source}
+        </div>
+      )}
+
+      <div className="opacity-90">{detail.message}</div>
+    </div>
+  );
+}
+
 /**
  * Create toast options for any error type
  */
 export function createErrorToast(
-  detail: ValidationErrorDetail | CORSErrorDetail | NetworkErrorDetail | CentrifugoErrorDetail,
-  config: Required<ValidationErrorConfig | CORSErrorConfig | NetworkErrorConfig | CentrifugoErrorConfig>
+  detail: ValidationErrorDetail | CORSErrorDetail | NetworkErrorDetail | CentrifugoErrorDetail | RuntimeErrorDetail,
+  config: Required<ValidationErrorConfig | CORSErrorConfig | NetworkErrorConfig | CentrifugoErrorConfig | RuntimeErrorConfig>
 ) {
   let description: React.ReactNode;
 
@@ -167,6 +189,8 @@ export function createErrorToast(
     description = buildCORSDescription(detail, config as Required<CORSErrorConfig>);
   } else if (detail.type === 'centrifugo') {
     description = buildCentrifugoDescription(detail, config as Required<CentrifugoErrorConfig>);
+  } else if (detail.type === 'runtime') {
+    description = buildRuntimeDescription(detail, config as Required<RuntimeErrorConfig>);
   } else {
     description = buildNetworkDescription(detail, config as Required<NetworkErrorConfig>);
   }

package/src/components/errors/ErrorsTracker/hooks/useErrorEmitter.ts

@@ -0,0 +1,72 @@
+/**
+ * useErrorEmitter - Universal error emitter hook
+ *
+ * Emits runtime errors that are caught by ErrorTrackingProvider
+ * and displayed as toasts.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { emitError } = useErrorEmitter('tour');
+ *
+ *   useEffect(() => {
+ *     try {
+ *       document.querySelectorAll(invalidSelector);
+ *     } catch (error) {
+ *       emitError('Invalid selector', error);
+ *     }
+ *   }, []);
+ * }
+ * ```
+ */
+
+'use client';
+
+import { useCallback } from 'react';
+
+import { ERROR_EVENTS } from '../types';
+
+export interface EmitErrorOptions {
+  /** Additional context data */
+  context?: Record<string, unknown>;
+}
+
+export interface ErrorEmitter {
+  /**
+   * Emit an error to be shown as a toast
+   * @param message - Human-readable error message
+   * @param error - Original Error object (optional)
+   * @param options - Additional options
+   */
+  emitError: (message: string, error?: Error, options?: EmitErrorOptions) => void;
+}
+
+/**
+ * Hook to emit runtime errors
+ *
+ * @param source - Error source identifier (e.g., 'tour', 'form', 'api')
+ */
+export function useErrorEmitter(source: string): ErrorEmitter {
+  const emitError = useCallback(
+    (message: string, error?: Error, options?: EmitErrorOptions) => {
+      if (typeof window === 'undefined') return;
+
+      const event = new CustomEvent(ERROR_EVENTS.RUNTIME, {
+        detail: {
+          source,
+          message,
+          error,
+          context: options?.context,
+          timestamp: new Date(),
+        },
+      });
+
+      window.dispatchEvent(event);
+    },
+    [source]
+  );
+
+  return { emitError };
+}
+
+export default useErrorEmitter;

package/src/components/errors/ErrorsTracker/hooks.ts

@@ -5,6 +5,8 @@
  */
 
 export { useErrors } from './providers/ErrorTrackingProvider';
+export { useErrorEmitter } from './hooks/useErrorEmitter';
+export type { ErrorEmitter, EmitErrorOptions } from './hooks/useErrorEmitter';
 
 // Type exports for convenience
 export type { ErrorTrackingContextValue } from './types';

package/src/components/errors/ErrorsTracker/index.ts

@@ -1,13 +1,20 @@
 /**
  * Error Tracking - Unified error tracking for all error types
  *
- * Single provider and hook for validation, CORS, network, and Centrifugo errors
+ * Single provider and hook for validation, CORS, network, Centrifugo, and runtime errors
  */
 
 // Main provider and hook
 export { ErrorTrackingProvider } from './providers/ErrorTrackingProvider';
 export { useErrors } from './hooks';
 
+// Error emitter hook (for emitting runtime errors from React components)
+export { useErrorEmitter } from './hooks';
+export type { ErrorEmitter, EmitErrorOptions } from './hooks';
+
+// Re-export standalone emitRuntimeError from ui-core (for use outside React)
+export { emitRuntimeError } from '@djangocfg/ui-core/utils';
+
 // Types
 export type {
   ErrorDetail,
@@ -15,15 +22,20 @@ export type {
   CORSErrorDetail,
   NetworkErrorDetail,
   CentrifugoErrorDetail,
+  RuntimeErrorDetail,
   StoredError,
   ErrorTrackingConfig,
   ValidationErrorConfig,
   CORSErrorConfig,
   NetworkErrorConfig,
   CentrifugoErrorConfig,
+  RuntimeErrorConfig,
   ErrorTrackingContextValue,
 } from './types';
 
+// Event names (for manual event dispatching)
+export { ERROR_EVENTS } from './types';
+
 // Components
 export { ErrorButtons } from './components/ErrorButtons';
 export { createErrorToast } from './components/ErrorToast';
@@ -35,6 +47,7 @@ export {
   formatCORSErrorForClipboard,
   formatNetworkErrorForClipboard,
   formatCentrifugoErrorForClipboard,
+  formatRuntimeErrorForClipboard,
   formatErrorTitle,
   extractDomain,
 } from './utils/formatters';

package/src/components/errors/ErrorsTracker/providers/ErrorTrackingProvider.tsx

@@ -37,6 +37,7 @@ import {
     DEFAULT_CENTRIFUGO_CONFIG,
     DEFAULT_CORS_CONFIG,
     DEFAULT_NETWORK_CONFIG,
+    DEFAULT_RUNTIME_CONFIG,
     DEFAULT_VALIDATION_CONFIG,
     ERROR_EVENTS
 } from '../types';
@@ -48,10 +49,12 @@ import type {
   CORSErrorConfig,
   NetworkErrorConfig,
   CentrifugoErrorConfig,
+  RuntimeErrorConfig,
   ValidationErrorDetail,
   CORSErrorDetail,
   NetworkErrorDetail,
   CentrifugoErrorDetail,
+  RuntimeErrorDetail,
   ErrorTrackingContextValue,
 } from '../types';
 const ErrorTrackingContext = createContext<ErrorTrackingContextValue | undefined>(undefined);
@@ -78,6 +81,8 @@ function getErrorDedupeKey(detail: ErrorDetail): string {
       return `network:${detail.url}:${detail.statusCode || 'unknown'}`;
     case 'centrifugo':
       return `centrifugo:${detail.method}:${detail.code || 'unknown'}`;
+    case 'runtime':
+      return `runtime:${detail.source}:${detail.message.slice(0, 50)}`;
     default:
       return `unknown:${Date.now()}`;
   }
@@ -148,6 +153,7 @@ export interface ErrorTrackingProviderProps {
   cors?: Partial<CORSErrorConfig>;
   network?: Partial<NetworkErrorConfig>;
   centrifugo?: Partial<CentrifugoErrorConfig>;
+  runtime?: Partial<RuntimeErrorConfig>;
   onError?: (error: ErrorDetail) => boolean | void;
 }
 
@@ -162,6 +168,7 @@ export function ErrorTrackingProvider({
   cors: userCorsConfig,
   network: userNetworkConfig,
   centrifugo: userCentrifugoConfig,
+  runtime: userRuntimeConfig,
   onError,
 }: ErrorTrackingProviderProps) {
   const [errors, setErrors] = useState<StoredError[]>([]);
@@ -187,6 +194,11 @@ export function ErrorTrackingProvider({
     ...userCentrifugoConfig,
   };
 
+  const runtimeConfig: Required<RuntimeErrorConfig> = {
+    ...DEFAULT_RUNTIME_CONFIG,
+    ...userRuntimeConfig,
+  };
+
   /**
    * Clear all errors
    */
@@ -212,7 +224,7 @@ export function ErrorTrackingProvider({
    * Handle any error event
    */
   const handleError = useCallback(
-    (detail: ErrorDetail, config: Required<ValidationErrorConfig | CORSErrorConfig | NetworkErrorConfig | CentrifugoErrorConfig>) => {
+    (detail: ErrorDetail, config: Required<ValidationErrorConfig | CORSErrorConfig | NetworkErrorConfig | CentrifugoErrorConfig | RuntimeErrorConfig>) => {
       // Check for duplicate errors (within deduplication window)
       const isUnique = shouldShowError(detail);
 
@@ -314,19 +326,38 @@ export function ErrorTrackingProvider({
       handlers.push({ event: ERROR_EVENTS.CENTRIFUGO, handler });
     }
 
+    // Runtime errors (generic JS errors from anywhere in the app)
+    if (runtimeConfig.enabled) {
+      const handler = (event: Event) => {
+        if (!(event instanceof CustomEvent)) return;
+        const detail: RuntimeErrorDetail = {
+          type: 'runtime' as const,
+          source: event.detail.source || 'unknown',
+          message: event.detail.message || 'Unknown error',
+          error: event.detail.error,
+          context: event.detail.context,
+          timestamp: event.detail.timestamp || new Date(),
+        };
+        handleError(detail, runtimeConfig);
+      };
+      window.addEventListener(ERROR_EVENTS.RUNTIME, handler);
+      handlers.push({ event: ERROR_EVENTS.RUNTIME, handler });
+    }
+
     // Cleanup
     return () => {
       handlers.forEach(({ event, handler }) => {
         window.removeEventListener(event, handler);
       });
     };
-  }, [handleError, validationConfig, corsConfig, networkConfig, centrifugoConfig]);
+  }, [handleError, validationConfig, corsConfig, networkConfig, centrifugoConfig, runtimeConfig]);
 
   // Filter errors by type
   const validationErrors = errors.filter((e) => e.type === 'validation') as StoredError<ValidationErrorDetail>[];
   const corsErrors = errors.filter((e) => e.type === 'cors') as StoredError<CORSErrorDetail>[];
   const networkErrors = errors.filter((e) => e.type === 'network') as StoredError<NetworkErrorDetail>[];
   const centrifugoErrors = errors.filter((e) => e.type === 'centrifugo') as StoredError<CentrifugoErrorDetail>[];
+  const runtimeErrors = errors.filter((e) => e.type === 'runtime') as StoredError<RuntimeErrorDetail>[];
 
   const value: ErrorTrackingContextValue = {
     errors,
@@ -334,6 +365,7 @@ export function ErrorTrackingProvider({
     corsErrors,
     networkErrors,
     centrifugoErrors,
+    runtimeErrors,
     clearErrors,
     clearErrorsByType,
     clearError,
@@ -344,6 +376,7 @@ export function ErrorTrackingProvider({
       cors: corsConfig,
       network: networkConfig,
       centrifugo: centrifugoConfig,
+      runtime: runtimeConfig,
     },
   };
 

package/src/components/errors/ErrorsTracker/types.ts

@@ -74,10 +74,26 @@ export interface CentrifugoErrorDetail extends BaseErrorDetail {
   data?: any;
 }
 
+/**
+ * Runtime/generic error detail (from runtime-error event)
+ * Used for any JS errors that need to be shown to user (e.g., Tour selector errors)
+ */
+export interface RuntimeErrorDetail extends BaseErrorDetail {
+  type: 'runtime';
+  /** Error source/category (e.g., 'tour', 'component', etc.) */
+  source: string;
+  /** Error message */
+  message: string;
+  /** Original error object if available */
+  error?: Error;
+  /** Additional context data */
+  context?: Record<string, unknown>;
+}
+
 /**
  * Union type of all error details
  */
-export type ErrorDetail = ValidationErrorDetail | CORSErrorDetail | NetworkErrorDetail | CentrifugoErrorDetail;
+export type ErrorDetail = ValidationErrorDetail | CORSErrorDetail | NetworkErrorDetail | CentrifugoErrorDetail | RuntimeErrorDetail;
 
 /**
  * Stored error with unique ID
@@ -202,6 +218,17 @@ export interface CentrifugoErrorConfig extends ErrorTypeConfig {
   showCode?: boolean;
 }
 
+/**
+ * Runtime error specific config
+ */
+export interface RuntimeErrorConfig extends ErrorTypeConfig {
+  /**
+   * Show error source in toast
+   * @default true
+   */
+  showSource?: boolean;
+}
+
 /**
  * Complete error tracking configuration
  */
@@ -226,6 +253,11 @@ export interface ErrorTrackingConfig {
    */
   centrifugo?: CentrifugoErrorConfig;
 
+  /**
+   * Runtime error tracking configuration
+   */
+  runtime?: RuntimeErrorConfig;
+
   /**
    * Custom error handler (called before toast for all errors)
    * Return false to prevent default toast notification
@@ -252,11 +284,14 @@ export interface ErrorTrackingContextValue {
   /** Centrifugo errors only */
   centrifugoErrors: StoredError<CentrifugoErrorDetail>[];
 
+  /** Runtime errors only */
+  runtimeErrors: StoredError<RuntimeErrorDetail>[];
+
   /** Clear all errors */
   clearErrors: () => void;
 
   /** Clear errors by type */
-  clearErrorsByType: (type: 'validation' | 'cors' | 'network' | 'centrifugo') => void;
+  clearErrorsByType: (type: 'validation' | 'cors' | 'network' | 'centrifugo' | 'runtime') => void;
 
   /** Clear specific error by ID */
   clearError: (id: string) => void;
@@ -273,6 +308,7 @@ export interface ErrorTrackingContextValue {
     cors: Required<CORSErrorConfig>;
     network: Required<NetworkErrorConfig>;
     centrifugo: Required<CentrifugoErrorConfig>;
+    runtime: Required<RuntimeErrorConfig>;
   };
 }
 
@@ -285,6 +321,8 @@ export const ERROR_EVENTS = {
   NETWORK: 'network-error',
   /** Unified Centrifugo event - filter by detail.type === 'error' */
   CENTRIFUGO: 'centrifugo',
+  /** Runtime/generic errors (Tour, components, etc.) */
+  RUNTIME: 'runtime-error',
 } as const;
 
 /**
@@ -326,3 +364,9 @@ export const DEFAULT_CENTRIFUGO_CONFIG: Required<CentrifugoErrorConfig> = {
   showMethod: true,
   showCode: true,
 };
+
+export const DEFAULT_RUNTIME_CONFIG: Required<RuntimeErrorConfig> = {
+  ...DEFAULT_ERROR_CONFIG,
+  duration: 8000,
+  showSource: true,
+};

package/src/components/errors/ErrorsTracker/utils/formatters.ts

@@ -5,7 +5,7 @@
  */
 
 import type { ZodError } from 'zod';
-import type { ValidationErrorDetail, CORSErrorDetail, NetworkErrorDetail, CentrifugoErrorDetail } from '../types';
+import type { ValidationErrorDetail, CORSErrorDetail, NetworkErrorDetail, CentrifugoErrorDetail, RuntimeErrorDetail } from '../types';
 
 /**
  * Format Zod error issues for display
@@ -111,10 +111,30 @@ export function extractDomain(url: string): string {
   }
 }
 
+/**
+ * Format runtime error for clipboard
+ */
+export function formatRuntimeErrorForClipboard(detail: RuntimeErrorDetail): string {
+  const errorData = {
+    type: 'runtime',
+    timestamp: detail.timestamp.toISOString(),
+    source: detail.source,
+    message: detail.message,
+    ...(detail.error && {
+      errorName: detail.error.name,
+      errorMessage: detail.error.message,
+      stack: detail.error.stack,
+    }),
+    ...(detail.context && { context: detail.context }),
+  };
+
+  return JSON.stringify(errorData, null, 2);
+}
+
 /**
  * Format error title based on type
  */
-export function formatErrorTitle(detail: ValidationErrorDetail | CORSErrorDetail | NetworkErrorDetail | CentrifugoErrorDetail): string {
+export function formatErrorTitle(detail: ValidationErrorDetail | CORSErrorDetail | NetworkErrorDetail | CentrifugoErrorDetail | RuntimeErrorDetail): string {
   switch (detail.type) {
     case 'validation':
       return `❌ Validation Error in ${detail.operation}`;
@@ -128,6 +148,8 @@ export function formatErrorTitle(detail: ValidationErrorDetail | CORSErrorDetail
       return detail.code !== undefined
         ? `🔌 Centrifugo Error (${detail.code})`
         : '🔌 Centrifugo Error';
+    case 'runtime':
+      return `⚠️ ${detail.source} Error`;
     default:
       return '❌ Error';
   }