# 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>
  );
}
```