@pushwoosh/dumb-components 1.1.148 → 1.1.149

package/ProgressBar/ai-documentation.md

@@ -1,533 +0,0 @@
-# ProgressBar Component - @pushwoosh/dumb-components
-
-## Overview
-
-- **Component Name**: ProgressBar
-- **Import Path**: `@pushwoosh/dumb-components`
-- **Files**:
-  - `/src/ProgressBar/ProgressBar.tsx` - Main component implementation
-  - `/src/ProgressBar/types.ts` - TypeScript type definitions
-  - `/src/ProgressBar/styles.tsx` - Styled components
-  - `/src/ProgressBar/index.ts` - Component exports
-- **Type**: Display/Feedback
-- **Description**: A progress bar component that displays the completion percentage of a task. Features a spinning indicator, customizable colors, title display with percentage, and optional right slot for additional controls or information.
-
-## TypeScript Interfaces
-
-```typescript
-export type ProgressBarProps = {
-  percentValue: number;
-  title: string;
-  rightSlot?: ReactNode;
-  color?: string;
-  backgroundColor?: string;
-};
-```
-
-## Import & Usage
-
-```typescript
-import { ProgressBar } from '@pushwoosh/dumb-components';
-
-// Basic usage
-function MyComponent() {
-  const [progress, setProgress] = useState(0);
-
-  useEffect(() => {
-    const interval = setInterval(() => {
-      setProgress(prev => {
-        if (prev >= 100) {
-          clearInterval(interval);
-          return 100;
-        }
-        return prev + 10;
-      });
-    }, 500);
-
-    return () => clearInterval(interval);
-  }, []);
-
-  return (
-    <ProgressBar
-      percentValue={progress}
-      title="Loading"
-    />
-  );
-}
-
-// File upload progress
-function FileUploadProgress() {
-  const [uploadProgress, setUploadProgress] = useState(0);
-  const [fileName, setFileName] = useState('document.pdf');
-
-  const handleFileUpload = async (file: File) => {
-    setFileName(file.name);
-    
-    // Simulate upload progress
-    for (let i = 0; i <= 100; i += 5) {
-      setUploadProgress(i);
-      await new Promise(resolve => setTimeout(resolve, 100));
-    }
-  };
-
-  return (
-    <ProgressBar
-      percentValue={uploadProgress}
-      title={`Uploading ${fileName}`}
-    />
-  );
-}
-```
-
-## Advanced Examples
-
-```typescript
-// Progress with cancel button
-function CancellableProgress() {
-  const [progress, setProgress] = useState(0);
-  const [isRunning, setIsRunning] = useState(false);
-  const [taskName, setTaskName] = useState('Processing');
-  
-  const intervalRef = useRef<NodeJS.Timeout>();
-
-  const startProcess = () => {
-    setIsRunning(true);
-    setProgress(0);
-    
-    intervalRef.current = setInterval(() => {
-      setProgress(prev => {
-        if (prev >= 100) {
-          setIsRunning(false);
-          clearInterval(intervalRef.current);
-          return 100;
-        }
-        return prev + 2;
-      });
-    }, 100);
-  };
-
-  const cancelProcess = () => {
-    setIsRunning(false);
-    setProgress(0);
-    if (intervalRef.current) {
-      clearInterval(intervalRef.current);
-    }
-  };
-
-  useEffect(() => {
-    return () => {
-      if (intervalRef.current) {
-        clearInterval(intervalRef.current);
-      }
-    };
-  }, []);
-
-  const rightSlot = (
-    <button
-      onClick={cancelProcess}
-      disabled={!isRunning}
-      style={{
-        padding: '4px 8px',
-        fontSize: '12px',
-        border: '1px solid #dc3545',
-        backgroundColor: 'transparent',
-        color: '#dc3545',
-        borderRadius: '4px',
-        cursor: isRunning ? 'pointer' : 'not-allowed',
-      }}
-    >
-      Cancel
-    </button>
-  );
-
-  return (
-    <div>
-      {!isRunning && progress === 0 && (
-        <button onClick={startProcess} style={{ marginBottom: '16px' }}>
-          Start Process
-        </button>
-      )}
-      
-      {(isRunning || progress > 0) && (
-        <ProgressBar
-          percentValue={progress}
-          title={taskName}
-          rightSlot={rightSlot}
-          color="#28a745"
-          backgroundColor="#e9ecef"
-        />
-      )}
-      
-      {progress === 100 && (
-        <div style={{ marginTop: '16px', color: '#28a745' }}>
-          ✅ Process completed successfully!
-        </div>
-      )}
-    </div>
-  );
-}
-
-// Multi-step progress
-function MultiStepProgress() {
-  const [currentStep, setCurrentStep] = useState(0);
-  const [stepProgress, setStepProgress] = useState(0);
-  
-  const steps = [
-    'Initializing',
-    'Loading data',
-    'Processing',
-    'Validating',
-    'Finalizing'
-  ];
-
-  const totalSteps = steps.length;
-  const overallProgress = Math.floor(((currentStep + stepProgress / 100) / totalSteps) * 100);
-
-  const simulateStep = async () => {
-    setStepProgress(0);
-    
-    // Simulate step progress
-    for (let i = 0; i <= 100; i += 5) {
-      setStepProgress(i);
-      await new Promise(resolve => setTimeout(resolve, 50));
-    }
-    
-    if (currentStep < totalSteps - 1) {
-      setCurrentStep(prev => prev + 1);
-    }
-  };
-
-  useEffect(() => {
-    if (currentStep < totalSteps) {
-      simulateStep();
-    }
-  }, [currentStep]);
-
-  const rightSlot = (
-    <span style={{ fontSize: '12px', color: '#666' }}>
-      Step {currentStep + 1} of {totalSteps}
-    </span>
-  );
-
-  return (
-    <div>
-      <ProgressBar
-        percentValue={overallProgress}
-        title={steps[currentStep] || 'Complete'}
-        rightSlot={rightSlot}
-        color="#007bff"
-      />
-      
-      <div style={{ marginTop: '12px', fontSize: '14px' }}>
-        <div>Current step: <strong>{steps[currentStep]}</strong></div>
-        <div>Step progress: {stepProgress}%</div>
-        <div>Overall progress: {overallProgress}%</div>
-      </div>
-    </div>
-  );
-}
-
-// Data processing progress
-function DataProcessingProgress() {
-  const [processed, setProcessed] = useState(0);
-  const [total, setTotal] = useState(1000);
-  const [isProcessing, setIsProcessing] = useState(false);
-  const [processingRate, setProcessingRate] = useState(0);
-  const [startTime, setStartTime] = useState<Date | null>(null);
-
-  const progress = Math.min((processed / total) * 100, 100);
-
-  const startProcessing = () => {
-    setIsProcessing(true);
-    setProcessed(0);
-    setStartTime(new Date());
-    
-    const interval = setInterval(() => {
-      setProcessed(prev => {
-        if (prev >= total) {
-          setIsProcessing(false);
-          clearInterval(interval);
-          return total;
-        }
-        
-        // Variable processing rate
-        const increment = Math.floor(Math.random() * 10) + 1;
-        return Math.min(prev + increment, total);
-      });
-    }, 100);
-  };
-
-  // Calculate processing rate
-  useEffect(() => {
-    if (startTime && isProcessing) {
-      const elapsed = (Date.now() - startTime.getTime()) / 1000;
-      const rate = processed / elapsed;
-      setProcessingRate(Math.floor(rate));
-    }
-  }, [processed, startTime, isProcessing]);
-
-  // Estimate time remaining
-  const timeRemaining = processingRate > 0 ? Math.ceil((total - processed) / processingRate) : 0;
-
-  const rightSlot = (
-    <div style={{ textAlign: 'right', fontSize: '12px' }}>
-      <div>{processed.toLocaleString()} / {total.toLocaleString()}</div>
-      {isProcessing && (
-        <div style={{ color: '#666' }}>
-          {processingRate}/sec • {timeRemaining}s left
-        </div>
-      )}
-    </div>
-  );
-
-  return (
-    <div>
-      <div style={{ marginBottom: '16px' }}>
-        <label>
-          Total items: 
-          <input
-            type="number"
-            value={total}
-            onChange={(e) => setTotal(parseInt(e.target.value) || 1000)}
-            disabled={isProcessing}
-            style={{ marginLeft: '8px', width: '100px' }}
-          />
-        </label>
-        
-        <button
-          onClick={startProcessing}
-          disabled={isProcessing}
-          style={{ marginLeft: '16px', padding: '8px 16px' }}
-        >
-          {isProcessing ? 'Processing...' : 'Start Processing'}
-        </button>
-      </div>
-
-      <ProgressBar
-        percentValue={progress}
-        title="Processing records"
-        rightSlot={rightSlot}
-        color="#17a2b8"
-      />
-
-      {progress === 100 && (
-        <div style={{ marginTop: '16px', padding: '12px', backgroundColor: '#d4edda', borderRadius: '4px', color: '#155724' }}>
-          Processing completed! {total.toLocaleString()} records processed.
-        </div>
-      )}
-    </div>
-  );
-}
-
-// Download progress
-function DownloadProgress() {
-  const [downloads, setDownloads] = useState<{[key: string]: number}>({});
-  
-  const startDownload = (fileName: string, fileSize: number) => {
-    setDownloads(prev => ({ ...prev, [fileName]: 0 }));
-    
-    const interval = setInterval(() => {
-      setDownloads(prev => {
-        const current = prev[fileName] || 0;
-        if (current >= 100) {
-          clearInterval(interval);
-          return prev;
-        }
-        
-        return {
-          ...prev,
-          [fileName]: Math.min(current + Math.random() * 5, 100)
-        };
-      });
-    }, 200);
-  };
-
-  const removeDownload = (fileName: string) => {
-    setDownloads(prev => {
-      const { [fileName]: removed, ...rest } = prev;
-      return rest;
-    });
-  };
-
-  const downloadFiles = [
-    { name: 'report.pdf', size: 2.5 },
-    { name: 'data-export.xlsx', size: 8.2 },
-    { name: 'presentation.pptx', size: 15.7 },
-  ];
-
-  return (
-    <div>
-      <h3>File Downloads</h3>
-      
-      <div style={{ marginBottom: '20px' }}>
-        {downloadFiles.map(file => (
-          <button
-            key={file.name}
-            onClick={() => startDownload(file.name, file.size)}
-            disabled={file.name in downloads}
-            style={{ 
-              margin: '4px', 
-              padding: '8px 12px',
-              backgroundColor: file.name in downloads ? '#6c757d' : '#007bff',
-              color: 'white',
-              border: 'none',
-              borderRadius: '4px'
-            }}
-          >
-            Download {file.name} ({file.size}MB)
-          </button>
-        ))}
-      </div>
-
-      <div style={{ display: 'flex', flexDirection: 'column', gap: '16px' }}>
-        {Object.entries(downloads).map(([fileName, progress]) => {
-          const file = downloadFiles.find(f => f.name === fileName);
-          const rightSlot = (
-            <div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
-              <span style={{ fontSize: '12px' }}>
-                {file?.size}MB
-              </span>
-              <button
-                onClick={() => removeDownload(fileName)}
-                style={{
-                  padding: '2px 6px',
-                  fontSize: '12px',
-                  border: '1px solid #dc3545',
-                  backgroundColor: 'transparent',
-                  color: '#dc3545',
-                  borderRadius: '2px',
-                  cursor: 'pointer'
-                }}
-              >
-                ×
-              </button>
-            </div>
-          );
-
-          return (
-            <ProgressBar
-              key={fileName}
-              percentValue={Math.floor(progress)}
-              title={`Downloading ${fileName}`}
-              rightSlot={rightSlot}
-              color={progress === 100 ? '#28a745' : '#007bff'}
-            />
-          );
-        })}
-      </div>
-    </div>
-  );
-}
-```
-
-## Props Reference
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| `percentValue` | `number` | - | Yes | Progress percentage (0-100) |
-| `title` | `string` | - | Yes | Title text displayed above the progress bar |
-| `rightSlot` | `ReactNode` | `undefined` | No | Content displayed on the right side of the header |
-| `color` | `string` | `Color.BRIGHT` | No | Color of the progress bar fill |
-| `backgroundColor` | `string` | `Color.BRIGHT_LIGHT` | No | Background color of the progress bar |
-
-## AI Agent Guidelines
-
-### Recommended Patterns
-
-1. **Progress Validation**: Ensure percentage values are within valid range
-```typescript
-const clampedProgress = Math.min(Math.max(progress, 0), 100);
-
-<ProgressBar percentValue={clampedProgress} title="Loading" />
-```
-
-2. **Smooth Updates**: Use intervals or animation for smooth progress updates
-```typescript
-useEffect(() => {
-  const interval = setInterval(() => {
-    setProgress(prev => Math.min(prev + 1, 100));
-  }, 100);
-  
-  return () => clearInterval(interval);
-}, []);
-```
-
-3. **Descriptive Titles**: Use meaningful, action-oriented titles
-```typescript
-// Good - descriptive
-<ProgressBar title="Uploading document" />
-<ProgressBar title="Processing payment" />
-
-// Avoid - generic
-<ProgressBar title="Loading" />
-<ProgressBar title="Please wait" />
-```
-
-### Common Mistakes to Avoid
-
-1. **Invalid Percentage**: Don't pass values outside 0-100 range
-2. **Missing Progress Updates**: Ensure progress actually updates over time
-3. **Blocking UI**: Don't block user interaction during progress display
-4. **Memory Leaks**: Always clean up intervals and timeouts
-5. **Poor UX**: Provide cancel options for long-running tasks
-
-### Integration Tips
-
-1. **Async Operations**: Use with promises and async/await
-```typescript
-const handleAsyncTask = async () => {
-  setProgress(0);
-  
-  try {
-    for (let step of steps) {
-      await performStep(step);
-      setProgress(prev => prev + (100 / steps.length));
-    }
-  } catch (error) {
-    // Handle error
-  }
-};
-```
-
-2. **File Uploads**: Integrate with file upload progress
-```typescript
-const uploadFile = (file: File) => {
-  const xhr = new XMLHttpRequest();
-  
-  xhr.upload.addEventListener('progress', (e) => {
-    if (e.lengthComputable) {
-      const progress = (e.loaded / e.total) * 100;
-      setUploadProgress(progress);
-    }
-  });
-  
-  xhr.open('POST', '/upload');
-  xhr.send(file);
-};
-```
-
-3. **Real-time Updates**: Use WebSockets or polling for server progress
-```typescript
-useEffect(() => {
-  const ws = new WebSocket('/progress');
-  
-  ws.onmessage = (event) => {
-    const { progress, status } = JSON.parse(event.data);
-    setProgress(progress);
-    setStatus(status);
-  };
-  
-  return () => ws.close();
-}, []);
-```
-
-4. **Form Validation**: Show validation progress for complex forms
-5. **Accessibility**: Component includes ARIA attributes for screen readers
-
-## Related Components
-
-- **Spinner**: Used internally for the loading indicator
-- **Button**: Often used with progress for cancel actions
-- **Modal**: For progress dialogs
-- **Alert**: For progress completion notifications
-- **Skeleton**: Alternative for content loading states