# Navigator

A step/wizard navigation component that guides users through a multi-step process. Visualizes progress and allows users to navigate between steps with clear status indicators.

## Features

- **Step Visualization**: Visual representation of wizard steps
- **Status Indicators**: Completed, Warning, and Not Started states
- **Active Tracking**: Highlights the current active step
- **Item Highlighting**: Highlight specific items for attention
- **Click Navigation**: Click to navigate between steps
- **Custom Styling**: Flexible styling options
- **Dynamic Items**: Support for dynamic step lists

## Installation

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

```typescript
import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
```

## Basic Usage

```svelte
<script>
  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';

  let activeItem = 0;
  let items = [
    { text: 'Step 1' },
    { text: 'Step 2' },
    { text: 'Step 3' },
    { text: 'Step 4' }
  ];

  function getStatus(item) {
    const index = items.indexOf(item);
    if (index < activeItem) return NavItemStatus.Completed;
    if (index === activeItem) return NavItemStatus.Completed;
    return NavItemStatus.NotStart;
  }

  function handleClick(item) {
    activeItem = items.indexOf(item);
    console.log('Navigated to:', item.text);
  }
</script>

<Navigator
  {items}
  activeItem={items[activeItem]}
  retrieveStatus={getStatus}
  itemClickHandler={handleClick}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `items` | `Array<any>` | Required | Array of navigation items (must have `text` property) |
| `activeItem` | `any` | `null` | Currently active item |
| `highlights` | `Array<any>` | `[]` | Items to highlight for attention |
| `itemClickHandler` | `(item: any) => void` | Required | Callback when item is clicked |
| `retrieveStatus` | `(item: any) => NavItemStatus` | Required | Function to get item status |
| `style` | `string` | `''` | Custom CSS styles |

## NavItemStatus Enum

| Status | Value | Description |
|--------|-------|-------------|
| `NavItemStatus.Completed` | `'nav-completed'` | Step is completed |
| `NavItemStatus.Warning` | `'nav-warning'` | Step has warnings |
| `NavItemStatus.NotStart` | `'nav-not-start'` | Step not started |

## Examples

### Basic Wizard Navigation

```svelte
<script>
  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';

  let currentStep = 0;

  const steps = [
    { text: 'Personal Info' },
    { text: 'Contact Details' },
    { text: 'Preferences' },
    { text: 'Review' }
  ];

  function getStepStatus(step) {
    const index = steps.indexOf(step);
    if (index < currentStep) return NavItemStatus.Completed;
    if (index === currentStep) return NavItemStatus.Completed;
    return NavItemStatus.NotStart;
  }

  function handleStepClick(step) {
    const index = steps.indexOf(step);
    if (index <= currentStep) {
      currentStep = index;
    }
  }

  function nextStep() {
    if (currentStep < steps.length - 1) {
      currentStep++;
    }
  }

  function prevStep() {
    if (currentStep > 0) {
      currentStep--;
    }
  }
</script>

<Navigator
  items={steps}
  activeItem={steps[currentStep]}
  retrieveStatus={getStepStatus}
  itemClickHandler={handleStepClick}
/>

<div style="margin-top: 32px; padding: 24px; border: 1px solid #ddd;">
  <h2>{steps[currentStep].text}</h2>
  <p>Content for step {currentStep + 1}</p>

  <div style="margin-top: 16px; display: flex; gap: 8px;">
    <button disabled={currentStep === 0} on:click={prevStep}>Previous</button>
    <button disabled={currentStep === steps.length - 1} on:click={nextStep}>Next</button>
  </div>
</div>
```

### With Warning Status

```svelte
<script>
  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';

  let currentStep = 2;
  const warningSteps = [1];

  const steps = [
    { text: 'Account' },
    { text: 'Profile' },
    { text: 'Settings' },
    { text: 'Confirm' }
  ];

  function getStepStatus(step) {
    const index = steps.indexOf(step);
    if (warningSteps.includes(index)) return NavItemStatus.Warning;
    if (index <= currentStep) return NavItemStatus.Completed;
    return NavItemStatus.NotStart;
  }

  function handleStepClick(step) {
    const index = steps.indexOf(step);
    if (index <= currentStep) {
      currentStep = index;
    }
  }
</script>

<Navigator
  items={steps}
  activeItem={steps[currentStep]}
  retrieveStatus={getStepStatus}
  itemClickHandler={handleStepClick}
/>
```

### With Highlights

```svelte
<script>
  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';

  let currentStep = 1;
  let highlightedSteps = [2, 3];

  const steps = [
    { text: 'Upload' },
    { text: 'Process' },
    { text: 'Verify' },
    { text: 'Complete' }
  ];

  function getStepStatus(step) {
    const index = steps.indexOf(step);
    if (index < currentStep) return NavItemStatus.Completed;
    if (index === currentStep) return NavItemStatus.Completed;
    return NavItemStatus.NotStart;
  }

  function handleStepClick(step) {
    const index = steps.indexOf(step);
    if (index <= currentStep) {
      currentStep = index;
    }
  }
</script>

<Navigator
  items={steps}
  activeItem={steps[currentStep]}
  highlights={highlightedSteps.map(i => steps[i])}
  retrieveStatus={getStepStatus}
  itemClickHandler={handleStepClick}
/>
```

### Custom Styling

```svelte
<script>
  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';

  const steps = [
    { text: '①' },
    { text: '②' },
    { text: '③' },
    { text: '④' }
  ];

  function getStepStatus(step) {
    return NavItemStatus.NotStart;
  }

  function handleStepClick(step) {
    console.log('Clicked:', step.text);
  }
</script>

<Navigator
  items={steps}
  activeItem={steps[0]}
  retrieveStatus={getStepStatus}
  itemClickHandler={handleStepClick}
  style="background: #f5f5f5; padding: 16px; border-radius: 8px;"
/>
```

### Complete Form Wizard

```svelte
<script>
  import Navigator, { NavItemStatus } from '@ticatec/uniface-element/Navigator';
  import Button from '@ticatec/uniface-element/Button';

  let currentStep = 0;
  let formData = {
    name: '',
    email: '',
    phone: '',
    address: ''
  };

  const wizardSteps = [
    { text: 'Personal' },
    { text: 'Contact' },
    { text: 'Location' },
    { text: 'Review' }
  ];

  function getStepStatus(step) {
    const index = wizardSteps.indexOf(step);
    if (index < currentStep) return NavItemStatus.Completed;
    if (index === currentStep) return NavItemStatus.Completed;
    return NavItemStatus.NotStart;
  }

  function handleStepClick(step) {
    const index = wizardSteps.indexOf(step);
    if (index <= currentStep) {
      currentStep = index;
    }
  }

  function canProceed() {
    switch(currentStep) {
      case 0: return formData.name.length > 0;
      case 1: return formData.email.length > 0;
      case 2: return formData.address.length > 0;
      default: return true;
    }
  }
</script>

<div style="max-width: 800px; margin: 0 auto; padding: 24px;">
  <Navigator
    items={wizardSteps}
    activeItem={wizardSteps[currentStep]}
    retrieveStatus={getStepStatus}
    itemClickHandler={handleStepClick}
  />

  <div style="margin-top: 32px; padding: 24px; border: 1px solid #ddd; border-radius: 8px;">
    {#if currentStep === 0}
      <h2>Personal Information</h2>
      <label>
        Full Name:
        <input type="text" bind:value={formData.name} placeholder="Enter your name" />
      </label>
    {:else if currentStep === 1}
      <h2>Contact Information</h2>
      <label>
        Email:
        <input type="email" bind:value={formData.email} placeholder="your@email.com" />
      </label>
    {:else if currentStep === 2}
      <h2>Location</h2>
      <label>
        Address:
        <input type="text" bind:value={formData.address} placeholder="Your address" />
      </label>
    {:else}
      <h2>Review Your Information</h2>
      <pre>{JSON.stringify(formData, null, 2)}</pre>
    {/if}

    <div style="margin-top: 24px; display: flex; justify-content: space-between;">
      <Button
        disabled={currentStep === 0}
        onclick={() => currentStep--}
      >
        Previous
      </Button>

      {#if currentStep < wizardSteps.length - 1}
        <Button
          type="primary"
          disabled={!canProceed()}
          onclick={() => currentStep++}
        >
          Next
        </Button>
      {:else}
        <Button type="primary" onclick={() => console.log('Submit:', formData)}>
          Submit
        </Button>
      {/if}
    </div>
  </div>
</div>
```

## Best Practices

1. **Clear Steps**: Use concise, descriptive text for each step
2. **Status Logic**: Implement clear status logic based on your workflow
3. **Navigation Control**: Control which steps are clickable based on progress
4. **Visual Feedback**: Use warnings to indicate issues or attention needed
5. **Validation**: Prevent proceeding if current step is incomplete
6. **Progress Indication**: Make it clear which step is active

## Use Cases

- **Multi-step Forms**: Break complex forms into manageable steps
- **Wizards**: Guide users through complex processes
- **Onboarding**: Step-by-step user onboarding flows
- **Checkouts**: E-commerce checkout processes
- **Configuration**: Multi-stage configuration workflows

## Accessibility

- Keyboard navigation support
- Clear visual indicators for current step
- Semantic HTML structure
- ARIA attributes for screen readers