@djangocfg/layouts 1.2.32 → 1.2.34

package/src/validation/REFACTORING.md

@@ -0,0 +1,162 @@
+# Validation Error System - Refactoring Summary
+
+## Changes Made
+
+### ✅ Added: Copy as cURL Feature
+
+**New Files:**
+- `curl-generator.ts` - cURL command generation
+- `ValidationErrorButtons.tsx` - Button component using `useCopy` hook
+
+**Key Improvements:**
+1. **Auto token injection** - Token automatically fetched from localStorage
+2. **useCopy integration** - Uses existing `useCopy` hook instead of custom clipboard logic
+3. **Two buttons layout** - Both buttons at bottom of toast (not on the side)
+4. **Clean separation** - Buttons in separate component, generator in separate file
+
+### 🗑️ Removed: Legacy Code
+
+**Removed Functions:**
+- `copyToClipboard()` from ValidationErrorToast.tsx (replaced by `useCopy`)
+- `copyCurlToClipboard()` from curl-generator.ts (replaced by `useCopy`)
+- `createCopyAction()` (replaced by ValidationErrorButtons)
+- `createCopyErrorAction()` (replaced by ValidationErrorButtons)
+- `createCopyCurlAction()` (replaced by ValidationErrorButtons)
+
+### ♻️ Refactored: Cleaner API
+
+**Before:**
+```typescript
+// Multiple separate functions
+createCopyAction(detail, onSuccess, onError);
+createCopyErrorAction(detail, onSuccess, onError);
+createCopyCurlAction(detail, onSuccess, onError);
+```
+
+**After:**
+```typescript
+// Single component with useCopy
+<ValidationErrorButtons detail={detail} />
+```
+
+### 📦 File Structure
+
+```
+validation/
+├── curl-generator.ts              # cURL generation logic only
+├── ValidationErrorButtons.tsx     # Button component (uses useCopy)
+├── ValidationErrorToast.tsx       # Toast utilities (no copy logic)
+├── ValidationErrorContext.tsx     # Provider & hook
+├── index.ts                       # Public exports
+└── README.md                      # Documentation
+```
+
+## Benefits
+
+1. **No code duplication** - Uses existing `useCopy` instead of custom clipboard code
+2. **Consistent UX** - All copy operations show the same toast feedback
+3. **Cleaner separation** - Each file has single responsibility
+4. **Easier to maintain** - Less code, clearer structure
+5. **Better DX** - Simple `<ValidationErrorButtons />` instead of 3 separate functions
+
+## API Changes
+
+### Removed Exports
+```typescript
+// ❌ No longer exported
+createCopyAction
+createCopyErrorAction
+createCopyCurlAction
+copyCurlToClipboard
+```
+
+### New Exports
+```typescript
+// ✅ New exports
+ValidationErrorButtons          // Component
+generateCurl                    // Generate cURL string
+generateCurlFromError          // Generate from error detail
+getAuthToken                   // Get token from localStorage
+```
+
+### Unchanged Exports
+```typescript
+// ✅ Still available
+ValidationErrorProvider
+useValidationErrors
+createValidationErrorToast
+formatErrorForClipboard
+buildToastTitle
+buildToastDescription
+```
+
+## Migration Guide
+
+If you were using the old `createCopyAction`:
+
+**Before:**
+```typescript
+const toastOptions = createValidationErrorToast(errorDetail, {
+  onCopySuccess: () => console.log('Copied'),
+  onCopyError: (e) => console.error(e),
+});
+```
+
+**After:**
+```typescript
+// Just use it - ValidationErrorButtons handles everything
+const toastOptions = createValidationErrorToast(errorDetail);
+// That's it! Toast feedback is automatic via useCopy
+```
+
+## Implementation Details
+
+### ValidationErrorButtons Component
+
+Uses `useCopy` hook from `@djangocfg/ui`:
+
+```typescript
+const { copyToClipboard } = useCopy();
+
+const handleCopyError = async (e) => {
+  const json = JSON.stringify(errorData, null, 2);
+  await copyToClipboard(json, '✅ Error details copied');
+};
+
+const handleCopyCurl = async (e) => {
+  const curl = generateCurlFromError(detail);
+  await copyToClipboard(curl, '✅ cURL command copied');
+};
+```
+
+### Auto Token Injection
+
+```typescript
+export function generateCurl(options: CurlOptions): string {
+  const { token = getAuthToken() || undefined } = options;
+  // ...
+}
+```
+
+Token is auto-fetched if not provided.
+
+## Testing
+
+1. Trigger validation error (e.g., visit `/api/proxies/proxies/`)
+2. Toast appears with two buttons at bottom
+3. Click **📋 Copy Error** → Success toast appears → JSON in clipboard
+4. Click **🔄 Copy cURL** → Success toast appears → cURL in clipboard
+5. Paste cURL in terminal → Works with your auth token!
+
+## What's Next
+
+Possible future enhancements:
+- [ ] Support POST/PUT body in cURL
+- [ ] Option to copy without token
+- [ ] Different formats (fetch, axios)
+- [ ] Copy request+response together
+
+---
+
+**Date:** 2025-11-11
+**Impact:** Breaking changes for anyone using internal copy functions (unlikely)

package/src/validation/ValidationErrorButtons.tsx

@@ -0,0 +1,80 @@
+/**
+ * ValidationErrorButtons Component
+ *
+ * Copy buttons for validation errors using useCopy hook
+ */
+
+'use client';
+
+import React from 'react';
+import { Button, useCopy } from '@djangocfg/ui';
+import { generateCurlFromError } from './curl-generator';
+import type { ValidationErrorDetail } from './ValidationErrorToast';
+
+export interface ValidationErrorButtonsProps {
+  detail: ValidationErrorDetail;
+}
+
+export function ValidationErrorButtons({ detail }: ValidationErrorButtonsProps) {
+  const { copyToClipboard } = useCopy();
+
+  const handleCopyError = async (e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+
+    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 }),
+      })),
+      response: detail.response,
+      total_errors: detail.error.issues.length,
+    };
+
+    const formattedError = JSON.stringify(errorData, null, 2);
+    await copyToClipboard(formattedError, '✅ Error details copied');
+  };
+
+  const handleCopyCurl = async (e: React.MouseEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+
+    const curl = generateCurlFromError({
+      method: detail.method,
+      path: detail.path,
+      response: detail.response,
+    });
+
+    await copyToClipboard(curl, '✅ cURL command copied');
+  };
+
+  return (
+    <div className="flex gap-2 mt-2">
+      <Button
+        size="sm"
+        variant="outline"
+        onClick={handleCopyError}
+        className="h-8 text-xs"
+      >
+        📋 Copy Error
+      </Button>
+      <Button
+        size="sm"
+        variant="outline"
+        onClick={handleCopyCurl}
+        className="h-8 text-xs"
+      >
+        🔄 Copy cURL
+      </Button>
+    </div>
+  );
+}

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;
+}