@djangocfg/layouts 1.2.31 → 1.2.33

package/src/validation/README.md

@@ -0,0 +1,507 @@
+# Validation Error System
+
+Automatic Zod validation error tracking with toast notifications and copy-to-clipboard functionality.
+
+---
+
+## Features
+
+✅ **Auto-capture validation errors** from API client via CustomEvent
+✅ **Toast notifications** with destructive styling
+✅ **Copy button** - One-click copy full error details to clipboard
+✅ **Error history** - Store and manage validation errors
+✅ **Configurable** - Customize display and behavior
+✅ **Type-safe** - Full TypeScript support
+
+---
+
+## Quick Start
+
+### 1. Setup Provider
+
+Wrap your app with `ValidationErrorProvider`:
+
+```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,
+}));
+```
+
+### 3. See Results
+
+You'll see a toast with:
+- **Title**: "❌ Validation Error in operation_name"
+- **Description**: Endpoint, error count, first 3 errors
+- **Copy Button**: "📋 Copy" - Copies full error JSON to clipboard
+
+---
+
+## 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
+}
+```
+
+### 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
+
+```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>
+```
+
+### Custom Toast Config
+
+Create custom toast programmatically:
+
+```typescript
+import { useToast } from '@djangocfg/ui';
+import { createValidationErrorToast } from '@djangocfg/layouts/validation';
+
+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`
+
+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;
+}
+```
+
+---
+
+### `useValidationErrors()`
+
+Hook to access validation error state.
+
+**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
+
+```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);
+    },
+  }}
+>
+  {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>
+  );
+}
+```
+
+---
+
+## 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
+
+```
+validation/
+├── index.ts                      # Public exports
+├── ValidationErrorContext.tsx    # Provider & hook
+├── ValidationErrorToast.tsx      # Toast utilities & copy button
+└── README.md                     # This file
+```
+
+---
+
+## 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)
+
+---
+
+## Changelog
+
+### 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