# ProgressStepBar

A multi-step progress indicator component that visualizes the completion status of sequential steps in a process. Supports both horizontal and vertical layouts.

## Installation

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

## Import

```typescript
import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
```

## Basic Usage

### Horizontal Step Progress

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  
  let steps: Array<ProgressStep> = [
    {
      topic: 'Registration',
      comment: 'Complete your profile',
      status: ProgressStepStatus.Completed
    },
    {
      topic: 'Verification',
      comment: 'Verify your email',
      status: ProgressStepStatus.Processing
    },
    {
      topic: 'Setup',
      comment: 'Configure preferences',
      status: ProgressStepStatus.Pending
    }
  ];
</script>

<ProgressStepBar {steps} />
```

### Vertical Step Progress

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  
  let steps: Array<ProgressStep> = [
    {
      topic: 'Order Placed',
      comment: 'Your order has been received',
      status: ProgressStepStatus.Completed
    },
    {
      topic: 'Processing',
      comment: 'Preparing your items',
      status: ProgressStepStatus.Processing
    },
    {
      topic: 'Shipped',
      comment: 'On the way to you',
      status: ProgressStepStatus.Pending
    },
    {
      topic: 'Delivered',
      comment: 'Package delivered',
      status: ProgressStepStatus.Pending
    }
  ];
</script>

<ProgressStepBar {steps} direction="vertical" />
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `steps` | `Array<ProgressStep>` | Required | Array of progress steps |
| `direction` | `"horizontal" \| "vertical"` | `"horizontal"` | Layout direction of the steps |
| `backgroundColor` | `string` | `"var(--uniface-progress-step-bar-bg, #ffffff)"` | Background color of the step bar |
| `style` | `string` | `""` | Additional CSS styles |

## ProgressStep Interface

```typescript
interface ProgressStep {
  topic: string;        // Step title/name
  comment?: string;     // Optional description
  status: ProgressStepStatus;  // Current status
}
```

## ProgressStepStatus Enum

```typescript
enum ProgressStepStatus {
  Pending = 'pending',       // Not yet started
  Processing = 'processing', // Currently active
  Completed = 'completed'    // Finished
}
```

## Status Indicators

Each step displays different visual indicators based on its status:

- **Pending**: Shows step number in a muted style
- **Processing**: Shows step number with highlighted styling
- **Completed**: Shows checkmark (✔) with success styling

## Examples

### Dynamic Progress

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  import { onMount } from 'svelte';
  
  let steps: Array<ProgressStep> = [
    { topic: 'Initialization', comment: 'Setting up...', status: ProgressStepStatus.Pending },
    { topic: 'Data Loading', comment: 'Fetching data...', status: ProgressStepStatus.Pending },
    { topic: 'Processing', comment: 'Analyzing...', status: ProgressStepStatus.Pending },
    { topic: 'Completion', comment: 'Finalizing...', status: ProgressStepStatus.Pending }
  ];
  
  let currentStep = 0;
  
  onMount(() => {
    const interval = setInterval(() => {
      if (currentStep < steps.length) {
        // Mark current step as processing
        steps[currentStep].status = ProgressStepStatus.Processing;
        steps = [...steps];
        
        setTimeout(() => {
          // Mark as completed and move to next
          steps[currentStep].status = ProgressStepStatus.Completed;
          currentStep++;
          
          if (currentStep < steps.length) {
            steps[currentStep].status = ProgressStepStatus.Processing;
          }
          steps = [...steps];
        }, 1500);
      } else {
        clearInterval(interval);
      }
    }, 2000);
    
    return () => clearInterval(interval);
  });
</script>

<ProgressStepBar {steps} />
```

### Custom Background Color

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  
  let steps: Array<ProgressStep> = [
    { topic: 'Step 1', status: ProgressStepStatus.Completed },
    { topic: 'Step 2', status: ProgressStepStatus.Processing },
    { topic: 'Step 3', status: ProgressStepStatus.Pending }
  ];
</script>

<!-- Light gray background -->
<ProgressStepBar {steps} backgroundColor="#f8f9fa" />

<!-- Dark theme -->
<ProgressStepBar {steps} backgroundColor="#2d3748" />
```

### Without Comments

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  
  let steps: Array<ProgressStep> = [
    { topic: 'Login', status: ProgressStepStatus.Completed },
    { topic: 'Verify', status: ProgressStepStatus.Processing },
    { topic: 'Complete', status: ProgressStepStatus.Pending }
  ];
</script>

<ProgressStepBar {steps} />
```

### Workflow Example

```svelte
<script>
  import ProgressStepBar, { ProgressStepStatus, type ProgressStep } from "@ticatec/uniface-element/ProgressStepBar";
  import Button from "@ticatec/uniface-element/Button";
  
  let currentStepIndex = 0;
  let steps: Array<ProgressStep> = [
    { topic: 'Account Setup', comment: 'Create your account', status: ProgressStepStatus.Processing },
    { topic: 'Profile Details', comment: 'Add personal information', status: ProgressStepStatus.Pending },
    { topic: 'Preferences', comment: 'Choose your settings', status: ProgressStepStatus.Pending },
    { topic: 'Confirmation', comment: 'Review and confirm', status: ProgressStepStatus.Pending }
  ];
  
  function nextStep() {
    if (currentStepIndex < steps.length - 1) {
      steps[currentStepIndex].status = ProgressStepStatus.Completed;
      currentStepIndex++;
      steps[currentStepIndex].status = ProgressStepStatus.Processing;
      steps = [...steps];
    }
  }
  
  function prevStep() {
    if (currentStepIndex > 0) {
      steps[currentStepIndex].status = ProgressStepStatus.Pending;
      currentStepIndex--;
      steps[currentStepIndex].status = ProgressStepStatus.Processing;
      steps = [...steps];
    }
  }
</script>

<ProgressStepBar {steps} />

<div style="margin-top: 20px;">
  <Button label="Previous" onClick={prevStep} disabled={currentStepIndex === 0} />
  <Button label="Next" onClick={nextStep} disabled={currentStepIndex === steps.length - 1} />
</div>
```

## CSS Custom Properties

The component uses CSS custom properties for theming:

```css
:root {
  /* Background color */
  --uniface-progress-step-bar-bg: #ffffff;
  
  /* Step indicator colors (defined in uniface-progress-step-bar.scss) */
  --progress-step-pending-color: #e2e8f0;
  --progress-step-processing-color: #22bdff;
  --progress-step-completed-color: #2dc071;
}
```

## Styling Examples

### Custom Step Colors

```css
.custom-steps {
  --progress-step-pending-color: #cbd5e0;
  --progress-step-processing-color: #8b5cf6;
  --progress-step-completed-color: #10b981;
}
```

```svelte
<div class="custom-steps">
  <ProgressStepBar {steps} />
</div>
```

## Layout Considerations

### Horizontal Layout
- Best for processes with 3-6 steps
- Takes full width of container
- Steps are evenly distributed
- Ideal for linear workflows

### Vertical Layout
- Better for detailed step descriptions
- Fixed width, grows in height
- Suitable for sidebar placement
- Good for processes with many steps

## Best Practices

1. **Step Count**: Keep steps between 3-7 for optimal user experience
2. **Clear Titles**: Use concise, descriptive step titles
3. **Helpful Comments**: Provide useful context in step comments
4. **Status Management**: Update step status appropriately during process flow
5. **Visual Hierarchy**: Use consistent styling and spacing
6. **Responsive Design**: Consider layout direction based on available space

## Accessibility

- Proper semantic markup for screen readers
- Clear visual distinction between step states
- Color is not the only indicator of step status
- Descriptive text for each step state

## Browser Support

- Modern browsers with CSS Grid support
- Compatible with Svelte 5+
- Responsive design principles

## Related Components

- `ProgressBar` - Simple progress indicator
- `Wizard` - Step-by-step form navigation
- `Breadcrumbs` - Navigation hierarchy display