@djangocfg/layouts 1.2.32 → 1.2.33

package/src/validation/ValidationErrorContext.tsx

@@ -0,0 +1,333 @@
+/**
+ * ValidationErrorContext - Global Zod validation error tracking
+ *
+ * Automatically captures all Zod validation errors from API client
+ * using browser CustomEvent API and provides centralized state management.
+ *
+ * Features:
+ * - Automatic error capture via window.addEventListener
+ * - Toast notifications for user feedback
+ * - Error history with timestamps
+ * - Configurable error limits
+ * - React Context API for component access
+ *
+ * @example
+ * ```tsx
+ * import { useValidationErrors } from '@djangocfg/layouts';
+ *
+ * function MyComponent() {
+ *   const { errors, clearErrors, clearError } = useValidationErrors();
+ *
+ *   return (
+ *     <div>
+ *       <h2>Recent Validation Errors ({errors.length})</h2>
+ *       {errors.map((error) => (
+ *         <div key={error.id}>
+ *           <strong>{error.operation}</strong>
+ *           <p>{error.timestamp.toLocaleString()}</p>
+ *           <button onClick={() => clearError(error.id)}>Clear</button>
+ *         </div>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+
+'use client';
+
+import React, { createContext, useContext, useCallback, useEffect, useState, ReactNode } from 'react';
+import type { ZodError } from 'zod';
+import { toast } from '@djangocfg/ui';
+import { createValidationErrorToast } from './ValidationErrorToast';
+
+/**
+ * Validation error detail from CustomEvent
+ */
+export interface ValidationErrorDetail {
+  /** Operation/function name that failed validation */
+  operation: string;
+  /** API endpoint path */
+  path: string;
+  /** HTTP method */
+  method: string;
+  /** Zod validation error */
+  error: ZodError;
+  /** Raw response data that failed validation */
+  response: any;
+  /** Timestamp of the error */
+  timestamp: Date;
+}
+
+/**
+ * Stored validation error with unique ID
+ */
+export interface StoredValidationError extends ValidationErrorDetail {
+  /** Unique identifier for this error instance */
+  id: string;
+}
+
+/**
+ * Configuration for ValidationErrorProvider
+ */
+export interface ValidationErrorConfig {
+  /**
+   * Maximum number of errors to keep in history
+   * @default 50
+   */
+  maxErrors?: number;
+
+  /**
+   * Enable toast notifications on validation errors
+   * @default true
+   */
+  enableToast?: boolean;
+
+  /**
+   * Toast notification settings
+   */
+  toastSettings?: {
+    /** Show operation name in toast */
+    showOperation?: boolean;
+    /** Show endpoint path in toast */
+    showPath?: boolean;
+    /** Show error count in toast */
+    showErrorCount?: boolean;
+    /** Toast duration in milliseconds (0 = no auto-dismiss) */
+    duration?: number;
+  };
+
+  /**
+   * Custom error handler (called before toast)
+   * Return false to prevent default toast notification
+   */
+  onError?: (error: ValidationErrorDetail) => boolean | void;
+}
+
+/**
+ * Context value
+ */
+export interface ValidationErrorContextValue {
+  /** Array of validation errors */
+  errors: StoredValidationError[];
+
+  /** Clear all errors */
+  clearErrors: () => void;
+
+  /** Clear specific error by ID */
+  clearError: (id: string) => void;
+
+  /** Get error count */
+  errorCount: number;
+
+  /** Get latest error */
+  latestError: StoredValidationError | null;
+
+  /** Configuration */
+  config: Required<ValidationErrorConfig>;
+}
+
+const ValidationErrorContext = createContext<ValidationErrorContextValue | undefined>(undefined);
+
+/**
+ * Default configuration
+ */
+const defaultConfig: Required<ValidationErrorConfig> = {
+  maxErrors: 50,
+  enableToast: true,
+  toastSettings: {
+    showOperation: true,
+    showPath: true,
+    showErrorCount: true,
+    duration: 8000, // 8 seconds
+  },
+  onError: () => true,
+};
+
+/**
+ * Generate unique ID for error
+ */
+let errorIdCounter = 0;
+function generateErrorId(): string {
+  return `validation-error-${Date.now()}-${++errorIdCounter}`;
+}
+
+/**
+ * Format Zod error issues for display
+ */
+function formatZodIssues(error: ZodError): string {
+  const issues = error.issues.slice(0, 3); // Show max 3 issues
+  const formatted = issues.map((issue) => {
+    const path = issue.path.join('.') || 'root';
+    return `${path}: ${issue.message}`;
+  });
+
+  if (error.issues.length > 3) {
+    formatted.push(`... and ${error.issues.length - 3} more`);
+  }
+
+  return formatted.join(', ');
+}
+
+export interface ValidationErrorProviderProps {
+  children: ReactNode;
+  config?: Partial<ValidationErrorConfig>;
+}
+
+/**
+ * ValidationErrorProvider Component
+ *
+ * Wraps application and provides validation error tracking.
+ * Automatically listens to 'zod-validation-error' CustomEvents
+ * from the API client.
+ */
+export function ValidationErrorProvider({ children, config: userConfig }: ValidationErrorProviderProps) {
+  const [errors, setErrors] = useState<StoredValidationError[]>([]);
+
+  // Merge user config with defaults
+  const config: Required<ValidationErrorConfig> = {
+    ...defaultConfig,
+    ...userConfig,
+    toastSettings: {
+      ...defaultConfig.toastSettings,
+      ...userConfig?.toastSettings,
+    },
+  };
+
+  /**
+   * Clear all errors
+   */
+  const clearErrors = useCallback(() => {
+    setErrors([]);
+  }, []);
+
+  /**
+   * Clear specific error
+   */
+  const clearError = useCallback((id: string) => {
+    setErrors((prev) => prev.filter((error) => error.id !== id));
+  }, []);
+
+  /**
+   * Handle validation error event
+   */
+  const handleValidationError = useCallback(
+    (event: Event) => {
+      if (!(event instanceof CustomEvent)) return;
+
+      const detail = event.detail as ValidationErrorDetail;
+
+      // Create stored error with ID
+      const storedError: StoredValidationError = {
+        ...detail,
+        id: generateErrorId(),
+      };
+
+      // Add to errors array (limited by maxErrors)
+      setErrors((prev) => {
+        const updated = [storedError, ...prev];
+        return updated.slice(0, config.maxErrors);
+      });
+
+      // Call custom error handler
+      const shouldShowToast = config.onError?.(detail) !== false;
+
+      // Show toast notification with copy button
+      if (config.enableToast && shouldShowToast) {
+        const { showOperation, showPath, showErrorCount } = config.toastSettings;
+
+        // Create toast with custom copy action button
+        const toastOptions = createValidationErrorToast(detail, {
+          config: {
+            showOperation,
+            showPath,
+            showErrorCount,
+            maxIssuesInDescription: 3,
+            titlePrefix: '❌ Validation Error',
+          },
+          duration: config.toastSettings.duration,
+          onCopySuccess: () => {
+            // Show success feedback when error details are copied
+            toast({
+              title: '✅ Copied!',
+              description: 'Error details copied to clipboard',
+              duration: 2000,
+            });
+          },
+          onCopyError: (error) => {
+            // Show error feedback if copy fails
+            toast({
+              title: '❌ Copy failed',
+              description: 'Could not copy error details',
+              variant: 'destructive',
+              duration: 2000,
+            });
+          },
+        });
+
+        toast(toastOptions);
+      }
+    },
+    [config]
+  );
+
+  /**
+   * Setup event listener
+   */
+  useEffect(() => {
+    // Only run in browser
+    if (typeof window === 'undefined') return;
+
+    window.addEventListener('zod-validation-error', handleValidationError);
+
+    return () => {
+      window.removeEventListener('zod-validation-error', handleValidationError);
+    };
+  }, [handleValidationError]);
+
+  const value: ValidationErrorContextValue = {
+    errors,
+    clearErrors,
+    clearError,
+    errorCount: errors.length,
+    latestError: errors[0] || null,
+    config,
+  };
+
+  return (
+    <ValidationErrorContext.Provider value={value}>
+      {children}
+    </ValidationErrorContext.Provider>
+  );
+}
+
+/**
+ * useValidationErrors Hook
+ *
+ * Access validation errors from any component
+ *
+ * @example
+ * ```tsx
+ * function ErrorPanel() {
+ *   const { errors, clearErrors } = useValidationErrors();
+ *
+ *   if (errors.length === 0) return null;
+ *
+ *   return (
+ *     <div>
+ *       <h3>Validation Errors ({errors.length})</h3>
+ *       <button onClick={clearErrors}>Clear All</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useValidationErrors(): ValidationErrorContextValue {
+  const context = useContext(ValidationErrorContext);
+
+  if (context === undefined) {
+    throw new Error('useValidationErrors must be used within ValidationErrorProvider');
+  }
+
+  return context;
+}

package/src/validation/ValidationErrorToast.tsx

@@ -0,0 +1,251 @@
+/**
+ * ValidationErrorToast Component
+ *
+ * Custom toast for validation errors with copy button
+ * Formats Zod validation errors and provides one-click copy functionality
+ */
+
+'use client';
+
+import React from 'react';
+import { ToastAction } from '@djangocfg/ui';
+import type { ZodError } from 'zod';
+
+export interface ValidationErrorDetail {
+  operation: string;
+  path: string;
+  method: string;
+  error: ZodError;
+  response: any;
+  timestamp: Date;
+}
+
+export interface ValidationErrorToastConfig {
+  /** Show operation name in title */
+  showOperation?: boolean;
+  /** Show API path in description */
+  showPath?: boolean;
+  /** Show error count in description */
+  showErrorCount?: boolean;
+  /** Maximum number of issues to show in description */
+  maxIssuesInDescription?: number;
+  /** Custom title prefix */
+  titlePrefix?: string;
+}
+
+const defaultConfig: ValidationErrorToastConfig = {
+  showOperation: true,
+  showPath: true,
+  showErrorCount: true,
+  maxIssuesInDescription: 3,
+  titlePrefix: '❌ Validation Error',
+};
+
+/**
+ * Format Zod error issues for display in toast description
+ */
+export function formatZodIssuesForToast(
+  error: ZodError,
+  maxIssues: number = 3
+): string {
+  const issues = error.issues.slice(0, maxIssues);
+  const formatted = issues.map((issue) => {
+    const path = issue.path.join('.') || 'root';
+    return `${path}: ${issue.message}`;
+  });
+
+  if (error.issues.length > maxIssues) {
+    formatted.push(`... and ${error.issues.length - maxIssues} more`);
+  }
+
+  return formatted.join(', ');
+}
+
+/**
+ * Format full error details for copying to clipboard
+ * Includes all error information in structured JSON format
+ */
+export function formatErrorForClipboard(detail: ValidationErrorDetail): string {
+  const errorData = {
+    timestamp: detail.timestamp.toISOString(),
+    operation: detail.operation,
+    endpoint: {
+      method: detail.method,
+      path: detail.path,
+    },
+    validation_errors: detail.error.issues.map((issue) => ({
+      path: issue.path.join('.') || 'root',
+      message: issue.message,
+      code: issue.code,
+      ...(('expected' in issue) && { expected: issue.expected }),
+      ...(('received' in issue) && { received: issue.received }),
+      ...(('minimum' in issue) && { minimum: issue.minimum }),
+      ...(('maximum' in issue) && { maximum: issue.maximum }),
+    })),
+    response: detail.response,
+    total_errors: detail.error.issues.length,
+  };
+
+  return JSON.stringify(errorData, null, 2);
+}
+
+/**
+ * Copy text to clipboard
+ */
+async function copyToClipboard(text: string): Promise<boolean> {
+  if (typeof window === 'undefined') return false;
+
+  try {
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      await navigator.clipboard.writeText(text);
+      return true;
+    } else {
+      // Fallback for older browsers
+      const textarea = document.createElement('textarea');
+      textarea.value = text;
+      textarea.style.position = 'fixed';
+      textarea.style.opacity = '0';
+      document.body.appendChild(textarea);
+      textarea.select();
+      const success = document.execCommand('copy');
+      document.body.removeChild(textarea);
+      return success;
+    }
+  } catch (error) {
+    console.error('Failed to copy to clipboard:', error);
+    return false;
+  }
+}
+
+/**
+ * Build toast title from validation error
+ */
+export function buildToastTitle(
+  detail: ValidationErrorDetail,
+  config: ValidationErrorToastConfig = defaultConfig
+): string {
+  const titleParts: string[] = [config.titlePrefix || '❌ Validation Error'];
+
+  if (config.showOperation) {
+    titleParts.push(`in ${detail.operation}`);
+  }
+
+  return titleParts.join(' ');
+}
+
+/**
+ * Build toast description from validation error
+ */
+export function buildToastDescription(
+  detail: ValidationErrorDetail,
+  config: ValidationErrorToastConfig = defaultConfig
+): string {
+  const descriptionParts: string[] = [];
+
+  // Add HTTP method and path
+  if (config.showPath) {
+    descriptionParts.push(`${detail.method} ${detail.path}`);
+  }
+
+  // Add error count
+  if (config.showErrorCount) {
+    const count = detail.error.issues.length;
+    const plural = count === 1 ? 'error' : 'errors';
+    descriptionParts.push(`${count} ${plural}`);
+  }
+
+  // Add formatted error messages
+  descriptionParts.push(
+    formatZodIssuesForToast(
+      detail.error,
+      config.maxIssuesInDescription
+    )
+  );
+
+  return descriptionParts.join(' • ');
+}
+
+/**
+ * Create copy action button for toast
+ *
+ * @param detail - Validation error details
+ * @param onCopySuccess - Optional callback when copy succeeds
+ * @param onCopyError - Optional callback when copy fails
+ */
+export function createCopyAction(
+  detail: ValidationErrorDetail,
+  onCopySuccess?: () => void,
+  onCopyError?: (error: Error) => void
+): React.ReactElement<typeof ToastAction> {
+  const handleCopy = async (e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+
+    try {
+      const formattedError = formatErrorForClipboard(detail);
+      const success = await copyToClipboard(formattedError);
+
+      if (success) {
+        console.log('✅ Validation error copied to clipboard');
+        onCopySuccess?.();
+      } else {
+        throw new Error('Clipboard API failed');
+      }
+    } catch (error) {
+      console.error('❌ Failed to copy validation error:', error);
+      onCopyError?.(error as Error);
+    }
+  };
+
+  return (
+    <ToastAction
+      altText="Copy error details"
+      onClick={handleCopy}
+      className="shrink-0"
+    >
+      📋 Copy
+    </ToastAction>
+  );
+}
+
+/**
+ * Create complete toast options for validation error
+ *
+ * Usage:
+ * ```typescript
+ * const { toast } = useToast();
+ *
+ * const toastOptions = createValidationErrorToast(errorDetail, {
+ *   onCopySuccess: () => toast({ title: '✅ Copied!' }),
+ *   onCopyError: () => toast({ title: '❌ Copy failed', variant: 'destructive' }),
+ * });
+ *
+ * toast(toastOptions);
+ * ```
+ */
+export function createValidationErrorToast(
+  detail: ValidationErrorDetail,
+  options?: {
+    config?: Partial<ValidationErrorToastConfig>;
+    duration?: number;
+    onCopySuccess?: () => void;
+    onCopyError?: (error: Error) => void;
+  }
+) {
+  const config: ValidationErrorToastConfig = {
+    ...defaultConfig,
+    ...options?.config,
+  };
+
+  return {
+    title: buildToastTitle(detail, config),
+    description: buildToastDescription(detail, config),
+    variant: 'destructive' as const,
+    duration: options?.duration,
+    action: createCopyAction(
+      detail,
+      options?.onCopySuccess,
+      options?.onCopyError
+    ),
+  };
+}

package/src/validation/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Validation Error Tracking
+ *
+ * Automatic capture and management of Zod validation errors
+ * from API client using browser CustomEvent API.
+ */
+
+export {
+  ValidationErrorProvider,
+  useValidationErrors,
+  type ValidationErrorDetail,
+  type StoredValidationError,
+  type ValidationErrorConfig,
+  type ValidationErrorContextValue,
+} from './ValidationErrorContext';
+
+export {
+  createValidationErrorToast,
+  createCopyAction,
+  buildToastTitle,
+  buildToastDescription,
+  formatZodIssuesForToast,
+  formatErrorForClipboard,
+  type ValidationErrorToastConfig,
+} from './ValidationErrorToast';