# ProgressBar

A flexible progress indicator component that supports both circular and linear display modes with customizable status states and styling.

## Installation

```bash
npm install @ticatec/uniface-element
```

## Import

```typescript
import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
```

## Basic Usage

### Circular Progress Bar

```svelte
<script>
  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
  
  let progress = 65;
  let status = ProgressStatus.progressing;
</script>

<ProgressBar {progress} {status} />
```

### Linear Progress Bar

```svelte
<script>
  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
  
  let progress = 45;
  let status = ProgressStatus.progressing;
</script>

<ProgressBar type="liner" {progress} {status} />
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `progress` | `number` | `0` | Progress value (0-100) |
| `size` | `number` | `100` | Size of the circular progress bar |
| `type` | `"circular" \| "liner"` | `"circular"` | Display type of the progress bar |
| `height` | `number` | `5` | Height/thickness of the progress bar |
| `showText` | `boolean` | `true` | Whether to display progress text |
| `status` | `ProgressStatus` | `ProgressStatus.progressing` | Current status of the progress |

## ProgressStatus Enum

```typescript
enum ProgressStatus {
  progressing = 'progressing',
  successful = 'successful',
  failure = 'failure',
  canceled = 'canceled'
}
```

## Status Indicators

The progress bar displays different indicators based on the status:

- **progressing**: Shows percentage (e.g., "65%")
- **successful**: Shows checkmark (✔)
- **failure**: Shows X mark (✕)
- **canceled**: Shows exclamation mark (!)

## Examples

### Different Status States

```svelte
<script>
  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
</script>

<!-- In progress -->
<ProgressBar progress={75} status={ProgressStatus.progressing} />

<!-- Successful completion -->
<ProgressBar progress={100} status={ProgressStatus.successful} />

<!-- Failed -->
<ProgressBar progress={45} status={ProgressStatus.failure} />

<!-- Canceled -->
<ProgressBar progress={30} status={ProgressStatus.canceled} />
```

### Custom Sizing

```svelte
<!-- Large circular progress -->
<ProgressBar size={150} height={8} progress={60} />

<!-- Thin linear progress -->
<ProgressBar type="liner" height={2} progress={40} />
```

### Without Text Display

```svelte
<ProgressBar progress={80} showText={false} />
```

## CSS Custom Properties

The component uses CSS custom properties for theming:

```css
:root {
  /* Default progress color */
  --uniface-progress-bar-color: #22BDFF;
  
  /* Background color */
  --uniface-progress-bar-bg: #E2E8F0;
  
  /* Success state color */
  --uniface-progress-bar-success-color: #2DC071;
  
  /* Failure state color */
  --uniface-progress-bar-failure-color: #FF685B;
  
  /* Canceled state color */
  --uniface-progress-bar-canceled-color: #FFC532;
}
```

## Styling Examples

### Custom Theme

```css
.custom-progress {
  --uniface-progress-bar-color: #8B5CF6;
  --uniface-progress-bar-success-color: #10B981;
  --uniface-progress-bar-failure-color: #EF4444;
}
```

```svelte
<div class="custom-progress">
  <ProgressBar progress={70} />
</div>
```

## Advanced Usage

### Animated Progress

```svelte
<script>
  import { onMount } from 'svelte';
  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
  
  let progress = 0;
  let status = ProgressStatus.progressing;
  
  onMount(() => {
    const interval = setInterval(() => {
      progress += 1;
      if (progress >= 100) {
        status = ProgressStatus.successful;
        clearInterval(interval);
      }
    }, 50);
    
    return () => clearInterval(interval);
  });
</script>

<ProgressBar {progress} {status} />
```

### Upload Progress Example

```svelte
<script>
  import ProgressBar, { ProgressStatus } from "@ticatec/uniface-element/ProgressBar";
  
  let uploadProgress = 0;
  let uploadStatus = ProgressStatus.progressing;
  
  async function handleUpload() {
    uploadProgress = 0;
    uploadStatus = ProgressStatus.progressing;
    
    try {
      // Simulate upload progress
      for (let i = 0; i <= 100; i += 10) {
        uploadProgress = i;
        await new Promise(resolve => setTimeout(resolve, 200));
      }
      uploadStatus = ProgressStatus.successful;
    } catch (error) {
      uploadStatus = ProgressStatus.failure;
    }
  }
</script>

<ProgressBar 
  type="liner" 
  progress={uploadProgress} 
  status={uploadStatus} 
  height={6}
/>
```

## Accessibility

- Uses proper ARIA attributes for screen readers
- Text content changes based on status for better accessibility
- Color changes are accompanied by symbol changes for color-blind users
- Proper contrast ratios maintained for all status states

## Best Practices

1. **Progress Range**: Keep progress values between 0-100
2. **Status Management**: Update status appropriately based on operation outcome
3. **Visual Feedback**: Use different status states to provide clear user feedback
4. **Responsive Design**: Consider using percentage-based sizing for responsive layouts
5. **Color Accessibility**: Don't rely solely on color to convey status information

## Browser Support

- Modern browsers with SVG support (for circular type)
- CSS custom properties support
- Compatible with Svelte 5+

## Related Components

- `ProgressStepBar` - Multi-step progress indicator
- `Button` - For triggering operations that show progress
- `Dialog` - For displaying progress in modal contexts