@djangocfg/layouts 1.2.39 → 1.2.41

package/src/validation/README.md

@@ -1,593 +1,191 @@
-# Validation Error System
+# Error Tracking System
 
-Automatic Zod validation error tracking with toast notifications and copy-to-clipboard functionality.
+**Universal error tracking for React apps with automatic toast notifications.**
 
----
-
-## Features
-
-✅ **Auto-capture validation errors** from API client via CustomEvent
-✅ **Toast notifications** with destructive styling
-✅ **Copy Error button** - One-click copy full error details JSON to clipboard
-✅ **Copy cURL button** - Generate and copy cURL command with auth token
-✅ **Error history** - Store and manage validation errors
-✅ **Configurable** - Customize display and behavior
-✅ **Type-safe** - Full TypeScript support
-
----
-
-## Quick Start
-
-### 1. Setup Provider
+## The Essence
 
-Wrap your app with `ValidationErrorProvider`:
+One provider that listens to browser `CustomEvent`s from API client and shows toast notifications automatically:
 
 ```tsx
-// apps/admin/src/layouts/RootLayout.tsx
-import { ValidationErrorProvider } from '@djangocfg/layouts/validation';
-
-export default function RootLayout({ children }) {
-  return (
-    <ValidationErrorProvider>
-      {children}
-    </ValidationErrorProvider>
-  );
-}
-```
-
-### 2. Trigger Validation Error
-
-Use the test button in UILayout header:
-
-```tsx
-// In UILayout header, click "Test Validation" button
-// Select any error type (Simple, Multiple, Nested, Array)
-```
-
-Or dispatch manually:
-
-```typescript
-import type { ValidationErrorDetail } from '@djangocfg/layouts/validation';
-
-const errorDetail: ValidationErrorDetail = {
-  operation: 'createUser',
-  path: '/api/users',
-  method: 'POST',
-  error: zodError, // ZodError instance
-  response: responseData,
-  timestamp: new Date(),
-};
-
-window.dispatchEvent(new CustomEvent('zod-validation-error', {
-  detail: errorDetail,
-  bubbles: true,
-  cancelable: false,
-}));
-```
+// Setup once
+<ErrorTrackingProvider>
+  <App />
+</ErrorTrackingProvider>
 
-### 3. See Results
+// API client dispatches events
+window.dispatchEvent(new CustomEvent('zod-validation-error', { detail: {...} }));
+window.dispatchEvent(new CustomEvent('cors-error', { detail: {...} }));
+window.dispatchEvent(new CustomEvent('network-error', { detail: {...} }));
 
-You'll see a toast with:
-- **Title**: "❌ Validation Error in operation_name"
-- **Description**: Endpoint, error count, first 3 errors
-- **Two Buttons** (displayed at bottom):
-  - **📋 Copy Error** - Copies full error JSON to clipboard
-  - **🔄 Copy cURL** - Generates and copies cURL command with auth token
-
----
-
-## Toast with Copy Button
-
-The system automatically shows toasts with a copy button for all validation errors.
-
-### What Gets Copied
-
-When you click "📋 Copy", the following JSON is copied to clipboard:
-
-```json
-{
-  "timestamp": "2025-11-11T00:39:22.123Z",
-  "operation": "createUser",
-  "endpoint": {
-    "method": "POST",
-    "path": "/api/users"
-  },
-  "validation_errors": [
-    {
-      "path": "email",
-      "message": "Invalid email format",
-      "code": "invalid_string",
-      "expected": "email",
-      "received": "string"
-    },
-    {
-      "path": "age",
-      "message": "Number must be greater than 0",
-      "code": "too_small",
-      "minimum": 0
-    }
-  ],
-  "response": {
-    "email": "not-an-email",
-    "age": -5
-  },
-  "total_errors": 2
-}
+// Provider catches them → shows toast → stores in state
+const { errors } = useErrors();
 ```
 
-### Copy Success/Error Feedback
-
-- **Success**: Shows "✅ Copied! Error details copied to clipboard" for 2 seconds
-- **Error**: Shows "❌ Copy failed - Could not copy error details" for 2 seconds
-
----
-
-## Configuration
-
-### Provider Config
+## Quick Start
 
 ```tsx
-<ValidationErrorProvider
-  config={{
-    enableToast: true,           // Show toast notifications
-    maxErrors: 50,               // Max errors to store in history
-    toastSettings: {
-      duration: 5000,            // Toast duration in ms
-      showOperation: true,       // Show operation name in title
-      showPath: true,            // Show endpoint path in description
-      showErrorCount: true,      // Show error count in description
-    },
-    onError: (detail) => {
-      // Custom error handler
-      console.error('Validation error:', detail);
-      // Return false to prevent toast
-      return true;
-    },
-  }}
->
-  {children}
-</ValidationErrorProvider>
-```
+import { ErrorTrackingProvider, useErrors } from '@djangocfg/layouts';
 
-### Custom Toast Config
-
-Create custom toast programmatically:
-
-```typescript
-import { useToast } from '@djangocfg/ui';
-import { createValidationErrorToast } from '@djangocfg/layouts/validation';
+// 1. Wrap your app
+<ErrorTrackingProvider
+  validation={{ enabled: true, showToast: true }}
+  cors={{ enabled: true, showToast: true }}
+  network={{ enabled: false }}
+>
+  <App />
+</ErrorTrackingProvider>
 
+// 2. Access errors anywhere
 function MyComponent() {
-  const { toast } = useToast();
-
-  const handleError = (errorDetail: ValidationErrorDetail) => {
-    const toastOptions = createValidationErrorToast(errorDetail, {
-      config: {
-        showOperation: true,
-        showPath: true,
-        showErrorCount: true,
-        maxIssuesInDescription: 5,  // Show up to 5 errors
-        titlePrefix: '🚨 API Error',  // Custom prefix
-      },
-      duration: 10000,  // 10 seconds
-      onCopySuccess: () => {
-        toast({ title: 'Copied!', duration: 1000 });
-      },
-      onCopyError: (error) => {
-        console.error('Copy failed:', error);
-      },
-    });
-
-    toast(toastOptions);
-  };
-
-  return <button onClick={() => handleError(errorDetail)}>Trigger Error</button>;
-}
-```
-
----
-
-## API Reference
-
-### `ValidationErrorProvider`
+  const { errors, validationErrors, corsErrors, clearErrors } = useErrors();
 
-Main provider component for validation error tracking.
-
-**Props:**
-```typescript
-interface ValidationErrorProviderProps {
-  children: ReactNode;
-  config?: Partial<ValidationErrorConfig>;
-}
-
-interface ValidationErrorConfig {
-  enableToast: boolean;              // Default: true
-  maxErrors: number;                 // Default: 50
-  toastSettings: {
-    duration: number;                // Default: 5000ms
-    showOperation: boolean;          // Default: true
-    showPath: boolean;               // Default: true
-    showErrorCount: boolean;         // Default: true
-  };
-  onError?: (detail: ValidationErrorDetail) => boolean | void;
+  return <div>Total errors: {errors.length}</div>;
 }
 ```
 
----
-
-### `useValidationErrors()`
+## Error Types
 
-Hook to access validation error state.
+| Type | Event Name | Source | Toast Content |
+|------|-----------|--------|---------------|
+| **Validation** | `zod-validation-error` | API client Zod schema validation | Field errors, copy buttons |
+| **CORS** | `cors-error` | API client CORS blocked | Causes, solutions, troubleshooting |
+| **Network** | `network-error` | API client network issues | Error details, status code |
 
-**Returns:**
-```typescript
-interface ValidationErrorContextValue {
-  errors: StoredValidationError[];    // All errors in history
-  clearErrors: () => void;            // Clear all errors
-  clearError: (id: string) => void;   // Clear specific error
-}
-```
-
-**Usage:**
-```typescript
-import { useValidationErrors } from '@djangocfg/layouts/validation';
-
-function ErrorList() {
-  const { errors, clearErrors, clearError } = useValidationErrors();
-
-  return (
-    <div>
-      <button onClick={clearErrors}>Clear All</button>
-      {errors.map((error) => (
-        <div key={error.id}>
-          <p>{error.operation}: {error.error.issues.length} errors</p>
-          <button onClick={() => clearError(error.id)}>Clear</button>
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
----
-
-### `createValidationErrorToast()`
-
-Create custom toast options with copy button.
-
-**Signature:**
-```typescript
-function createValidationErrorToast(
-  detail: ValidationErrorDetail,
-  options?: {
-    config?: Partial<ValidationErrorToastConfig>;
-    duration?: number;
-    onCopySuccess?: () => void;
-    onCopyError?: (error: Error) => void;
-  }
-): ToastOptions
-```
-
-**Returns:** Object with `title`, `description`, `variant`, `duration`, `action` (copy button)
-
----
-
-### `formatErrorForClipboard()`
-
-Format error details as JSON for clipboard.
-
-**Signature:**
-```typescript
-function formatErrorForClipboard(detail: ValidationErrorDetail): string
-```
-
-**Returns:** Formatted JSON string with all error details
-
----
-
-### `createCopyAction()`
-
-Create standalone copy button for toast.
-
-**Signature:**
-```typescript
-function createCopyAction(
-  detail: ValidationErrorDetail,
-  onCopySuccess?: () => void,
-  onCopyError?: (error: Error) => void
-): React.ReactElement
-```
-
-**Returns:** `<ToastAction>` component with copy functionality
-
----
-
-## Testing
-
-### Test Button in UILayout
-
-The `TestValidationButton` in UILayout header provides 4 test scenarios:
-
-1. **Simple Error** - Single field validation (email)
-2. **Multiple Errors** - 3 validation errors (email, age, username)
-3. **Nested Object** - Nested property errors (address.street, address.zipCode)
-4. **Array Validation** - Array item errors (items[0].quantity, items[1].price)
-
-Each test:
-- Dispatches CustomEvent
-- Triggers toast with copy button
-- Logs to console
-
----
-
-## Browser Compatibility
-
-### Clipboard API
-
-**Modern browsers** (Chrome 66+, Firefox 63+, Safari 13.1+):
-- Uses `navigator.clipboard.writeText()` (async)
-
-**Older browsers**:
-- Fallback to `document.execCommand('copy')`
-
----
-
-## Examples
-
-### Example 1: Basic Setup
+## Props
 
 ```tsx
-import { ValidationErrorProvider } from '@djangocfg/layouts/validation';
-
-function App() {
-  return (
-    <ValidationErrorProvider>
-      <YourApp />
-    </ValidationErrorProvider>
-  );
-}
-```
-
-### Example 2: Custom Error Handler
-
-```tsx
-<ValidationErrorProvider
-  config={{
-    onError: (detail) => {
-      // Log to external service
-      logToSentry(detail);
-
-      // Only show toast for POST/PUT/PATCH errors
-      return ['POST', 'PUT', 'PATCH'].includes(detail.method);
-    },
+<ErrorTrackingProvider
+  validation={{
+    enabled: true,           // Enable tracking
+    showToast: true,         // Show toast
+    maxErrors: 50,           // Max history
+    duration: 8000,          // Toast duration (ms)
+    showOperation: true,     // Show operation name
+    showPath: true,          // Show API path
+    showErrorCount: true,    // Show error count
+    maxIssuesInToast: 3      // Max issues in toast
   }}
->
-  {children}
-</ValidationErrorProvider>
-```
-
-### Example 3: Manual Toast Trigger
-
-```typescript
-import { useToast } from '@djangocfg/ui';
-import { createValidationErrorToast } from '@djangocfg/layouts/validation';
-
-function MyForm() {
-  const { toast } = useToast();
-
-  const handleSubmit = async (data) => {
-    try {
-      await api.createUser(data);
-    } catch (error) {
-      if (error instanceof ZodError) {
-        const toastOptions = createValidationErrorToast({
-          operation: 'createUser',
-          path: '/api/users',
-          method: 'POST',
-          error: error,
-          response: data,
-          timestamp: new Date(),
-        }, {
-          onCopySuccess: () => console.log('Copied!'),
-        });
-
-        toast(toastOptions);
-      }
-    }
-  };
-
-  return <form onSubmit={handleSubmit}>...</form>;
-}
-```
-
-### Example 4: Error History Display
-
-```tsx
-import { useValidationErrors } from '@djangocfg/layouts/validation';
-
-function ErrorHistory() {
-  const { errors, clearErrors } = useValidationErrors();
-
-  return (
-    <div className="space-y-4">
-      <div className="flex justify-between items-center">
-        <h2>Validation Error History ({errors.length})</h2>
-        <Button onClick={clearErrors} variant="outline" size="sm">
-          Clear All
-        </Button>
-      </div>
-
-      {errors.map((error) => (
-        <div key={error.id} className="border p-4 rounded">
-          <div className="flex justify-between">
-            <div>
-              <p className="font-semibold">{error.operation}</p>
-              <p className="text-sm text-muted-foreground">
-                {error.method} {error.path}
-              </p>
-            </div>
-            <p className="text-xs text-muted-foreground">
-              {error.timestamp.toLocaleString()}
-            </p>
-          </div>
-          <div className="mt-2">
-            <p className="text-sm">
-              {error.error.issues.length} validation errors
-            </p>
-          </div>
-        </div>
-      ))}
-    </div>
-  );
-}
+  cors={{
+    enabled: true,
+    showToast: true,
+    duration: 0,             // 0 = no auto-dismiss
+    showUrl: true,
+    showMethod: true
+  }}
+  network={{
+    enabled: false,          // Disabled by default
+    showToast: true,
+    showUrl: true,
+    showMethod: true,
+    showStatusCode: true
+  }}
+  onError={(error) => {
+    // Custom handler
+    // Return false to prevent toast
+  }}
+/>
 ```
 
----
-
-## Troubleshooting
-
-### Toast not showing
-
-1. **Check Toaster is rendered**:
-   ```tsx
-   import { Toaster } from '@djangocfg/ui';
-   // In your root layout
-   <Toaster />
-   ```
-
-2. **Check ValidationErrorProvider is wrapping your app**
-
-3. **Check config.enableToast is true**
-
-### Copy button not working
-
-1. **Check HTTPS**: Clipboard API requires secure context (HTTPS or localhost)
-2. **Check browser permissions**: Some browsers may block clipboard access
-3. **Check console**: Look for clipboard errors
-
-### Test button not visible
-
-1. **Check NODE_ENV**: Button only shows in development by default
-2. **Override in production**: Pass `showInProduction={true}` to TestValidationButton
-
----
-
-## File Structure
+## Structure
 
 ```
 validation/
-├── index.ts                      # Public exports
-├── ValidationErrorContext.tsx    # Provider & hook
-├── ValidationErrorToast.tsx      # Toast utilities & copy button
-└── README.md                     # This file
+├── providers/ErrorTrackingProvider.tsx    # Single provider
+├── components/
+│   ├── ErrorToast.tsx                     # Universal toast
+│   └── ErrorButtons.tsx                   # Copy buttons
+├── utils/
+│   ├── formatters.ts                      # Format errors
+│   └── curl-generator.ts                  # Generate cURL
+├── types.ts                               # TypeScript types
+├── hooks.ts                               # useErrors()
+└── index.ts                               # Public API
+```
+
+## How It Works
+
+```
+API Client (TypeScript)
+    ↓
+Throws Error
+    ↓
+Dispatches CustomEvent → window.dispatchEvent('zod-validation-error')
+    ↓
+ErrorTrackingProvider (React)
+    ↓
+Listens via window.addEventListener()
+    ↓
+1. Stores error in state
+2. Shows toast notification
+3. Provides via useErrors()
 ```
 
----
-
-## Related Components
-
-- **TestValidationButton** - Test button in UILayout header
-- **UILayout** - Layout with validation test button
-- **Toaster** - Toast notification container (@djangocfg/ui)
-- **useToast** - Toast hook (@djangocfg/ui)
+## Features
 
----
+- ✅ **Single provider** for all error types
+- ✅ **Automatic toast** notifications with copy buttons
+- ✅ **Type-safe** TypeScript throughout
+- ✅ **Theme-aware** buttons (no color issues)
+- ✅ **Lucide icons** instead of emojis
+- ✅ **Error history** with filtering by type
+- ✅ **Custom handlers** for logging to Sentry/etc
+- ✅ **SSR-safe** (checks `typeof window`)
 
-## Copy as cURL Feature
+## Migration from v1
 
-### What Gets Copied
+```tsx
+// Before
+<ValidationErrorProvider>
+  <CORSErrorProvider>
+    <App />
+  </CORSErrorProvider>
+</ValidationErrorProvider>
 
-When you click **🔄 Copy cURL**, a ready-to-use cURL command is generated:
+// After
+<ErrorTrackingProvider
+  validation={{ ... }}
+  cors={{ ... }}
+>
+  <App />
+</ErrorTrackingProvider>
 
-```bash
-curl 'http://localhost:8000/api/proxies/proxies/?page=1&page_size=100' \
-  -H 'Accept: */*' \
-  -H 'Content-Type: application/json' \
-  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+// Hooks
+useValidationErrors() → useErrors().validationErrors
+useCORSErrors() → useErrors().corsErrors
 ```
 
-The generator automatically:
-- ✅ Adds your auth token from localStorage
-- ✅ Formats headers properly
-- ✅ Uses correct HTTP method
-- ✅ Escapes special characters
-
-### Token Auto-Detection
-
-The cURL generator looks for your token in localStorage:
-- `access_token` (default)
-- `token`
-- `auth_token`
-
-### Manual cURL Generation
+## API
 
-You can also generate cURL commands programmatically:
+### `useErrors()`
 
-```typescript
-import { generateCurl, copyCurlToClipboard } from '@djangocfg/layouts/validation';
-
-// Generate cURL
-const curl = generateCurl({
-  method: 'POST',
-  path: '/api/users/',
-  token: 'your-token',
-  body: { name: 'John' },
-  headers: { 'X-Custom': 'value' },
-});
-
-// Copy to clipboard
-await copyCurlToClipboard(curl);
-```
+```tsx
+const {
+  errors,              // All errors
+  validationErrors,    // Validation only
+  corsErrors,          // CORS only
+  networkErrors,       // Network only
+  clearErrors,         // Clear all
+  clearErrorsByType,   // Clear by type
+  clearError,          // Clear one
+  errorCount,          // Total count
+  latestError,         // Latest error
+  config               // Current config
+} = useErrors();
+```
+
+### Event Details
 
-### API Reference - cURL
+```tsx
+// Validation
+{ type: 'validation', operation, path, method, error: ZodError, response, timestamp }
 
-#### `generateCurl(options: CurlOptions): string`
+// CORS
+{ type: 'cors', url, method, error: string, timestamp }
 
-**Options:**
-```typescript
-interface CurlOptions {
-  method: string;              // HTTP method
-  path: string;                // API path
-  token?: string;              // Auth token (auto-fetched if omitted)
-  body?: any;                  // Request body
-  headers?: Record<string, string>;  // Custom headers
-  baseUrl?: string;            // API base URL (from env by default)
-}
+// Network
+{ type: 'network', url, method, error: string, statusCode?, timestamp }
 ```
 
-#### `generateCurlFromError(detail): string`
-
-Generate cURL from validation error details. Auto-fetches token from localStorage.
-
-#### `getAuthToken(): string | null`
-
-Get authentication token from localStorage.
-
-#### `copyCurlToClipboard(curl: string): Promise<boolean>`
-
-Copy cURL command to clipboard. Returns `true` on success.
-
 ---
 
-## Changelog
-
-### 2025-11-11 - v2.1.0
-- ✨ Added **Copy cURL button** with automatic token injection
-- ✨ Added `curl-generator.ts` utilities
-- ✨ Added two buttons layout at bottom of toast
-- ✨ Auto-detect auth token from localStorage
-- 📝 Updated documentation with cURL examples
-
-### 2025-11-11 - v2.0.0
-- ✨ Added copy-to-clipboard button in toast
-- ✨ Added `ValidationErrorToast` utilities
-- ✨ Added `formatErrorForClipboard()` function
-- ✨ Added success/error feedback for copy action
-- 📝 Added comprehensive documentation
-
-### 2025-11-10 - v1.0.0
-- 🎉 Initial release
-- ✨ ValidationErrorProvider component
-- ✨ useValidationErrors hook
-- ✨ CustomEvent-based error capture
-- ✨ Toast notifications
+**Built with React Context + Browser CustomEvents**