# ProgressTracker

A component that displays the current step in a multi-step process or workflow.

## Usage

Use standalone.
```svelte
<ProgressTracker {...props} />
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

```svelte
<ol class="whole" {...rest}>
  {#each labels as label}
    <li class="middle">
      <div class="main">
        <div class="aux" conditional>{aux}</div>
        <div class="label">{label} or {children}</div>
      </div>
      <div class="extra" aria-hidden="true" conditional>{extra}</div>
    </li>
  {/each}
</ol>
```

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `current*` | `number` | `0` | Index of the step currently progressing |
| `labels*` | `string[]` | - | Step labels |
| `children` | `Snippet` | - | Step content; receives index, label, and variant |
| `aux` | `Snippet` | - | Auxiliary content; receives index, label, and variant |
| `extra` | `boolean | Snippet` | `true` | Between-step connector: `true` default connector, Snippet customizes, `false` hides |
| `statusLabels` | `Record` | - | Maps a variant to a screen-reader-only suffix appended to each step |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Variant |
| `eachVariant` | `SvelteMap` | - | Per-step variant |
`*` required. Other `HTMLOlAttributes` are passed to `<ol>` via rest props; `class` is merged onto the root.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

Current step and `whole` part are applied `neutral`. Steps less than current step will be `active`, greater than current will be `inactive`. If the `variant` prop is specified, the specified value is applied instead of `neutral`.

### Default Class Name

`svs-progress-tracker`

## Accessibility

### ARIA Roles and Attributes

The component applies these automatically:

- Steps (`middle` `<li>`): `aria-current="step"` on the current step, and `aria-label` on non-current steps when a status suffix is available.
- Connector (`extra` `<div>`, when rendered): `aria-hidden="true"`.

Pass `statusLabels` when custom variants need a screen-reader suffix; otherwise the default active state suffix is used.

## Exports

### Types

```ts
interface ProgressTrackerProps extends Omit<HTMLOlAttributes, "children"> {
  current: number; // (0)
  labels: string[];
  children?: Snippet<[number, string, string]>; // Snippet<[index,label,variant]>
  aux?: Snippet<[number, string, string]>; // Snippet<[index,label,variant]>
  extra?: boolean | Snippet<[number, string, string]>; // (true) Snippet<[index,label,variant]>
  statusLabels?: Partial<Record<string, string>>; // variant -> screen-reader suffix
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
  eachVariant?: SvelteMap<number, string> | Map<number, string>;
  // other HTMLOlAttributes are passed to <ol> via ...rest; `class` is merged onto the root
}
type ProgressTrackerReqdProps = "current" | "labels";
type ProgressTrackerBindProps = never;
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=ProgressTrackerBasic.svelte
<script lang="ts">
  import { ProgressTracker } from "svseeds";

  const labels = ["Step 1", "Step 2", "Step 3"];
  const num = ["(1)", "(2)", "(3)"];
  const styling = {
    whole: "mx-2 flex flex-nowrap min-w-60 overflow-auto",
    middle: "flex items-center",
    main: "flex items-center gap-2",
    aux: {
      base: "text-2xl",
      neutral: "",
      active: "text-teal-500",
      inactive: "text-gray-400",
    },
    label: {
      base: "text-nowrap",
      neutral: "",
      active: "text-teal-500",
      inactive: "text-gray-400",
    },
    extra: {
      base: "mx-2 w-full min-w-4 h-0.5",
      neutral: "bg-gray-400",
      active: "bg-teal-500",
    },
  };
  const myProps = {
    current: 1,
    labels,
    styling,
  };
</script>

<ProgressTracker {...myProps}>
  {#snippet aux(i)}
    {num[i]}
  {/snippet}
</ProgressTracker>
```
### With Interactive Variant

**Code**

```svelte src=ProgressTrackerPract.svelte
<script lang="ts">
  import { ProgressTracker } from "svseeds";
  import CircleCheck from "@lucide/svelte/icons/circle-check";
  import Circle from "@lucide/svelte/icons/circle";
  import CircleDot from "@lucide/svelte/icons/circle-dot";

  let { variant = $bindable() } = $props();
  let current = $state(1);
  const labels = [
    { label: "Step 1", text: "Additional text 1" },
    { label: "Step 2", text: "Additional text 2" },
    { label: "Step 3", text: "Additional text 3" },
    { label: "Step 4", text: "Additional text 4" },
  ];
  const variantStyle1 = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const variantStyle2 = {
    neutral: "",
    active: "text-teal-500",
    inactive: "text-gray-400",
  };
  const variantStyle3 = {
    neutral: "bg-gray-400",
    active: "bg-teal-500",
  };
  const styling = {
    whole: {
      base: "flex flex-col flex-nowrap [&_div]:transition-colors [&_div]:duration-500",
      ...variantStyle1,
    },
    middle: "flex flex-col",
    main: "flex items-center gap-2",
    aux: {
      base: "text-2xl",
      ...variantStyle2,
    },
    label: {
      base: "flex flex-col",
      ...variantStyle2,
    },
    extra: {
      base: "my-2 ml-5 min-h-2 w-0.5",
      ...variantStyle3,
    },
  };
  const cls = "px-2 rounded-md border text-center cursor-pointer";
</script>

<div class="flex flex-col flex-nowrap items-center">
  <ProgressTracker {current} {variant} labels={labels.map((x) => x.label)} {styling}>
    {#snippet aux(index)}
      {#if index < current}
        <CircleCheck class="size-10 stroke-teal-500" />
      {:else if index > current}
        <Circle class="size-10 stroke-gray-400" />
      {:else}
        <CircleDot class="size-10" />
      {/if}
    {/snippet}
    {#snippet children(index)}
      <div>{labels[index].label}</div>
      <div class="text-sm">{labels[index].text}</div>
    {/snippet}
  </ProgressTracker>

  <div class="mt-5 w-50 flex justify-around">
    <button type="button" class={cls} onclick={() => current--}>Prev.</button>
    <button type="button" class={cls} onclick={() => current++}>Next</button>
  </div>
</div>
```