@delightui/components 0.1.104 → 0.1.106

package/docs/components/molecules/ProgressBar.md

@@ -0,0 +1,624 @@
+# ProgressBar
+
+## Description
+
+A progress indicator component that visually represents the completion status of a task or process. Provides customizable value ranges, label display options, and styling controls for creating loading indicators, form progress, file uploads, and multi-step workflow progress visualization.
+
+## Aliases
+
+- ProgressBar
+- ProgressIndicator
+- LoadingBar
+- ProgressMeter
+- StatusBar
+- Gauge
+
+## Props Breakdown
+
+**Extends:** Standalone interface (no HTML element inheritance)
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `value` | `number` | - | Yes | Current progress value |
+| `min` | `number` | `0` | No | Minimum value of the progress bar |
+| `max` | `number` | `100` | No | Maximum value of the progress bar |
+| `showLabel` | `'Percentage' \| 'Text'` | - | No | Determines if and how the label is displayed |
+| `label` | `ReactNode` | - | No | Custom label displayed when showLabel is 'Text' |
+| `className` | `string` | - | No | Additional CSS class names |
+
+## Examples
+
+### Basic Usage
+```tsx
+import { ProgressBar } from '@delightui/components';
+
+function BasicExample() {
+  const [progress, setProgress] = useState(0);
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setProgress(prev => {
+        if (prev >= 100) return 0;
+        return prev + 10;
+      });
+    }, 500);
+
+    return () => clearInterval(timer);
+  }, []);
+
+  return (
+    <div className="progress-demo">
+      <ProgressBar value={progress} />
+    </div>
+  );
+}
+```
+
+### Progress with Percentage Label
+```tsx
+function PercentageLabelExample() {
+  const [uploadProgress, setUploadProgress] = useState(0);
+
+  const simulateUpload = () => {
+    setUploadProgress(0);
+    const timer = setInterval(() => {
+      setUploadProgress(prev => {
+        if (prev >= 100) {
+          clearInterval(timer);
+          return 100;
+        }
+        return prev + Math.random() * 15;
+      });
+    }, 200);
+  };
+
+  return (
+    <div className="upload-progress">
+      <Text type="Heading6">File Upload Progress</Text>
+      
+      <ProgressBar 
+        value={uploadProgress} 
+        showLabel="Percentage"
+      />
+      
+      <div className="upload-actions">
+        <Button onClick={simulateUpload}>
+          Start Upload
+        </Button>
+        
+        {uploadProgress === 100 && (
+          <Text type="BodySmall" className="success">
+            Upload Complete!
+          </Text>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### Custom Text Label
+```tsx
+function CustomLabelExample() {
+  const [taskProgress, setTaskProgress] = useState(3);
+  const totalTasks = 8;
+
+  const nextTask = () => {
+    if (taskProgress < totalTasks) {
+      setTaskProgress(prev => prev + 1);
+    }
+  };
+
+  const resetTasks = () => {
+    setTaskProgress(0);
+  };
+
+  const progressValue = (taskProgress / totalTasks) * 100;
+
+  return (
+    <div className="task-progress">
+      <Text type="Heading6">Project Tasks</Text>
+      
+      <ProgressBar 
+        value={progressValue}
+        showLabel="Text"
+        label={`${taskProgress} of ${totalTasks} tasks completed`}
+      />
+      
+      <div className="task-actions">
+        <Button 
+          onClick={nextTask}
+          disabled={taskProgress >= totalTasks}
+        >
+          Complete Task
+        </Button>
+        <Button type="Outlined" onClick={resetTasks}>
+          Reset
+        </Button>
+      </div>
+      
+      {taskProgress === totalTasks && (
+        <div className="completion-message">
+          <Icon icon="CheckCircle" className="success-icon" />
+          <Text>All tasks completed!</Text>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### Custom Range Progress
+```tsx
+function CustomRangeExample() {
+  const [score, setScore] = useState(750);
+  const minScore = 300;
+  const maxScore = 850;
+
+  const increaseScore = () => {
+    setScore(prev => Math.min(prev + 50, maxScore));
+  };
+
+  const decreaseScore = () => {
+    setScore(prev => Math.max(prev - 50, minScore));
+  };
+
+  const getScoreRating = (score) => {
+    if (score < 500) return { rating: 'Poor', color: 'red' };
+    if (score < 650) return { rating: 'Fair', color: 'orange' };
+    if (score < 750) return { rating: 'Good', color: 'blue' };
+    return { rating: 'Excellent', color: 'green' };
+  };
+
+  const { rating, color } = getScoreRating(score);
+
+  return (
+    <div className="credit-score">
+      <Text type="Heading6">Credit Score</Text>
+      
+      <div className="score-display">
+        <Text type="Heading3">{score}</Text>
+        <Text type="BodySmall" style={{ color }}>
+          {rating}
+        </Text>
+      </div>
+      
+      <ProgressBar 
+        value={score}
+        min={minScore}
+        max={maxScore}
+        showLabel="Text"
+        label={`Score: ${score} / ${maxScore}`}
+        className={`score-${color}`}
+      />
+      
+      <div className="score-range">
+        <Text type="Caption">Poor</Text>
+        <Text type="Caption">Fair</Text>
+        <Text type="Caption">Good</Text>
+        <Text type="Caption">Excellent</Text>
+      </div>
+      
+      <div className="score-actions">
+        <Button 
+          type="Outlined" 
+          onClick={decreaseScore}
+          disabled={score <= minScore}
+        >
+          Decrease
+        </Button>
+        <Button 
+          onClick={increaseScore}
+          disabled={score >= maxScore}
+        >
+          Increase
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Multi-step Form Progress
+```tsx
+function FormProgressExample() {
+  const [currentStep, setCurrentStep] = useState(1);
+  const totalSteps = 4;
+  
+  const steps = [
+    { id: 1, name: 'Personal Info', completed: false },
+    { id: 2, name: 'Contact Details', completed: false },
+    { id: 3, name: 'Preferences', completed: false },
+    { id: 4, name: 'Review', completed: false }
+  ];
+
+  const [stepStates, setStepStates] = useState(steps);
+
+  const nextStep = () => {
+    if (currentStep < totalSteps) {
+      setStepStates(prev => 
+        prev.map(step => 
+          step.id === currentStep ? { ...step, completed: true } : step
+        )
+      );
+      setCurrentStep(prev => prev + 1);
+    }
+  };
+
+  const prevStep = () => {
+    if (currentStep > 1) {
+      setCurrentStep(prev => prev - 1);
+    }
+  };
+
+  const progressValue = ((currentStep - 1) / (totalSteps - 1)) * 100;
+  const completedSteps = stepStates.filter(step => step.completed).length;
+
+  return (
+    <div className="form-wizard">
+      <Text type="Heading5">Account Setup</Text>
+      
+      <div className="progress-section">
+        <ProgressBar 
+          value={progressValue}
+          showLabel="Text"
+          label={`Step ${currentStep} of ${totalSteps}`}
+        />
+        
+        <div className="step-indicators">
+          {stepStates.map(step => (
+            <div 
+              key={step.id}
+              className={`step-indicator ${
+                step.id === currentStep ? 'current' : 
+                step.completed ? 'completed' : 'pending'
+              }`}
+            >
+              {step.completed ? (
+                <Icon icon="Check" />
+              ) : (
+                <Text type="Caption">{step.id}</Text>
+              )}
+              <Text type="BodySmall">{step.name}</Text>
+            </div>
+          ))}
+        </div>
+      </div>
+      
+      <div className="form-content">
+        <Text type="Heading6">
+          {stepStates.find(s => s.id === currentStep)?.name}
+        </Text>
+        <Text>Form content for step {currentStep} goes here...</Text>
+      </div>
+      
+      <div className="form-navigation">
+        <Button 
+          type="Outlined" 
+          onClick={prevStep}
+          disabled={currentStep === 1}
+        >
+          Previous
+        </Button>
+        
+        <div className="step-info">
+          <Text type="BodySmall">
+            {completedSteps} of {totalSteps} steps completed
+          </Text>
+        </div>
+        
+        <Button 
+          onClick={nextStep}
+          disabled={currentStep === totalSteps}
+        >
+          {currentStep === totalSteps ? 'Finish' : 'Next'}
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Animated Loading States
+```tsx
+function LoadingStatesExample() {
+  const [loadingState, setLoadingState] = useState('idle');
+  const [progress, setProgress] = useState(0);
+
+  const loadingStates = {
+    idle: { label: 'Ready to start', value: 0 },
+    connecting: { label: 'Connecting to server...', value: 25 },
+    downloading: { label: 'Downloading data...', value: 50 },
+    processing: { label: 'Processing files...', value: 75 },
+    complete: { label: 'Complete!', value: 100 }
+  };
+
+  const startLoading = async () => {
+    const states = Object.keys(loadingStates);
+    
+    for (let i = 1; i < states.length; i++) {
+      setLoadingState(states[i]);
+      setProgress(loadingStates[states[i]].value);
+      
+      // Simulate loading time
+      await new Promise(resolve => setTimeout(resolve, 1000));
+    }
+    
+    // Reset after completion
+    setTimeout(() => {
+      setLoadingState('idle');
+      setProgress(0);
+    }, 2000);
+  };
+
+  const currentState = loadingStates[loadingState];
+
+  return (
+    <div className="loading-demo">
+      <Text type="Heading6">Loading Simulation</Text>
+      
+      <div className="loading-progress">
+        <ProgressBar 
+          value={progress}
+          showLabel="Text"
+          label={currentState.label}
+          className={`loading-${loadingState}`}
+        />
+        
+        <div className="loading-status">
+          {loadingState !== 'idle' && loadingState !== 'complete' && (
+            <Spinner size="Small" />
+          )}
+          
+          {loadingState === 'complete' && (
+            <Icon icon="CheckCircle" className="success-icon" />
+          )}
+        </div>
+      </div>
+      
+      <Button 
+        onClick={startLoading}
+        disabled={loadingState !== 'idle' && loadingState !== 'complete'}
+      >
+        {loadingState === 'idle' ? 'Start Loading' : 'Loading...'}
+      </Button>
+    </div>
+  );
+}
+```
+
+### Skill Level Indicator
+```tsx
+function SkillIndicatorExample() {
+  const skills = [
+    { name: 'JavaScript', level: 90 },
+    { name: 'React', level: 85 },
+    { name: 'TypeScript', level: 75 },
+    { name: 'Node.js', level: 70 },
+    { name: 'Python', level: 60 }
+  ];
+
+  const getSkillLevel = (level) => {
+    if (level >= 90) return 'Expert';
+    if (level >= 75) return 'Advanced';
+    if (level >= 60) return 'Intermediate';
+    if (level >= 40) return 'Beginner';
+    return 'Learning';
+  };
+
+  return (
+    <div className="skills-chart">
+      <Text type="Heading6">Technical Skills</Text>
+      
+      <div className="skills-list">
+        {skills.map((skill, index) => (
+          <div key={skill.name} className="skill-item">
+            <div className="skill-header">
+              <Text type="BodyMedium">{skill.name}</Text>
+              <Text type="BodySmall" className="skill-level">
+                {getSkillLevel(skill.level)}
+              </Text>
+            </div>
+            
+            <ProgressBar 
+              value={skill.level}
+              showLabel="Percentage"
+              className={`skill-progress skill-${Math.floor(skill.level / 20)}`}
+            />
+          </div>
+        ))}
+      </div>
+      
+      <div className="skills-legend">
+        <div className="legend-item">
+          <div className="legend-color expert" />
+          <Text type="Caption">Expert (90%+)</Text>
+        </div>
+        <div className="legend-item">
+          <div className="legend-color advanced" />
+          <Text type="Caption">Advanced (75-89%)</Text>
+        </div>
+        <div className="legend-item">
+          <div className="legend-color intermediate" />
+          <Text type="Caption">Intermediate (60-74%)</Text>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Storage Usage Indicator
+```tsx
+function StorageUsageExample() {
+  const [storageData, setStorageData] = useState({
+    used: 45.6,
+    total: 100,
+    breakdown: {
+      documents: 15.2,
+      images: 18.4,
+      videos: 8.3,
+      other: 3.7
+    }
+  });
+
+  const usagePercent = (storageData.used / storageData.total) * 100;
+  const freeSpace = storageData.total - storageData.used;
+
+  const getUsageStatus = (percent) => {
+    if (percent >= 90) return { status: 'Critical', color: 'red' };
+    if (percent >= 75) return { status: 'High', color: 'orange' };
+    if (percent >= 50) return { status: 'Medium', color: 'blue' };
+    return { status: 'Low', color: 'green' };
+  };
+
+  const { status, color } = getUsageStatus(usagePercent);
+
+  return (
+    <div className="storage-usage">
+      <Text type="Heading6">Cloud Storage</Text>
+      
+      <div className="storage-overview">
+        <div className="storage-stats">
+          <Text type="Heading4">{storageData.used} GB</Text>
+          <Text type="BodySmall">of {storageData.total} GB used</Text>
+        </div>
+        
+        <div className="storage-status">
+          <Chip 
+            size="Small" 
+            style={color === 'green' ? 'Success' : 
+                  color === 'blue' ? 'Primary' : 
+                  color === 'orange' ? 'Warning' : 'Danger'}
+          >
+            {status} Usage
+          </Chip>
+        </div>
+      </div>
+      
+      <ProgressBar 
+        value={usagePercent}
+        showLabel="Text"
+        label={`${freeSpace.toFixed(1)} GB free space remaining`}
+        className={`storage-progress ${color}`}
+      />
+      
+      <div className="storage-breakdown">
+        <Text type="BodyMedium">Storage Breakdown</Text>
+        
+        {Object.entries(storageData.breakdown).map(([type, size]) => (
+          <div key={type} className="breakdown-item">
+            <div className="breakdown-info">
+              <Text type="BodySmall">{type.charAt(0).toUpperCase() + type.slice(1)}</Text>
+              <Text type="BodySmall">{size} GB</Text>
+            </div>
+            
+            <ProgressBar 
+              value={(size / storageData.total) * 100}
+              className={`breakdown-progress ${type}`}
+            />
+          </div>
+        ))}
+      </div>
+      
+      <div className="storage-actions">
+        <Button type="Outlined" size="Small">
+          Manage Storage
+        </Button>
+        <Button size="Small">
+          Upgrade Plan
+        </Button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Fitness Goals Progress
+```tsx
+function FitnessProgressExample() {
+  const [fitnessGoals, setFitnessGoals] = useState({
+    steps: { current: 8234, target: 10000, unit: 'steps' },
+    calories: { current: 1850, target: 2200, unit: 'cal' },
+    water: { current: 6, target: 8, unit: 'glasses' },
+    sleep: { current: 7.5, target: 8, unit: 'hours' }
+  });
+
+  const updateGoal = (goalType, increment) => {
+    setFitnessGoals(prev => ({
+      ...prev,
+      [goalType]: {
+        ...prev[goalType],
+        current: Math.max(0, prev[goalType].current + increment)
+      }
+    }));
+  };
+
+  return (
+    <div className="fitness-dashboard">
+      <Text type="Heading6">Today's Goals</Text>
+      
+      <div className="goals-grid">
+        {Object.entries(fitnessGoals).map(([goalType, goal]) => {
+          const percentage = Math.min((goal.current / goal.target) * 100, 100);
+          const isCompleted = goal.current >= goal.target;
+          
+          return (
+            <div key={goalType} className="goal-card">
+              <div className="goal-header">
+                <Text type="BodyMedium">
+                  {goalType.charAt(0).toUpperCase() + goalType.slice(1)}
+                </Text>
+                {isCompleted && (
+                  <Icon icon="CheckCircle" className="completed-icon" />
+                )}
+              </div>
+              
+              <div className="goal-stats">
+                <Text type="Heading5">
+                  {goal.current.toLocaleString()}
+                </Text>
+                <Text type="BodySmall">
+                  / {goal.target.toLocaleString()} {goal.unit}
+                </Text>
+              </div>
+              
+              <ProgressBar 
+                value={percentage}
+                showLabel="Percentage"
+                className={`goal-progress ${isCompleted ? 'completed' : ''}`}
+              />
+              
+              <div className="goal-actions">
+                <Button 
+                  size="Small" 
+                  type="Ghost"
+                  onClick={() => updateGoal(goalType, -100)}
+                >
+                  -
+                </Button>
+                <Button 
+                  size="Small" 
+                  type="Ghost"
+                  onClick={() => updateGoal(goalType, 100)}
+                >
+                  +
+                </Button>
+              </div>
+            </div>
+          );
+        })}
+      </div>
+      
+      <div className="daily-summary">
+        <Text type="BodyMedium">Daily Summary</Text>
+        <Text type="BodySmall">
+          {Object.values(fitnessGoals).filter(goal => 
+            goal.current >= goal.target
+          ).length} of {Object.keys(fitnessGoals).length} goals completed
+        </Text>
+      </div>
+    </div>
+  );
+}
+```