# Progress

Displays an indicator showing the completion progress of a task, typically displayed as a progress bar.

Source: https://webjs.dev/ui/docs/components/progress

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { progressClass } from '#components/ui/progress.ts';

// shadcn's demo starts at 13 and moves to 66 half a second after mount. A
// static demo shows the value the reader sees, 66.
export default function ProgressDemo() {
  return html`
    <progress data-slot="progress" value="66" max="100" aria-label="Progress" class=${cn(progressClass(), 'w-[60%]')}></progress>
  `;
}
```

## Installation

```bash
npx @webjsdev/ui add progress
```

### Copy and paste the following code into your project.

````ts title="components/ui/progress.ts"
/**
 * Progress: progress bar. Tier-1 class helper over the native
 * `<progress>` element. The native element supplies the `progressbar`
 * role and `aria-valuenow` automatically from its `value` / `max`
 * attributes, so no JS, no custom element.
 *
 * shadcn parity:
 *   Progress  → progressClass()  (visual: 2px track + animated fill,
 *                                 styled via `::-webkit-progress-bar`,
 *                                 `::-webkit-progress-value`, and
 *                                 `::-moz-progress-bar`)
 *
 * A11y (required for accessible output): give the <progress> an accessible
 * name with aria-label (or a <label for>), e.g. aria-label="Upload
 * progress". The native element supplies the role and value; only the name
 * is the author's responsibility.
 *
 * Design tokens used: --primary.
 *
 * @example
 * ```html
 * <progress value="42" max="100" class=${progressClass()}></progress>
 *
 * <!-- Indeterminate state, with no value attribute. -->
 * <progress class=${progressClass()}></progress>
 * ```
 */

/**
 * Class for the native `<progress>` element. The track + fill colours
 * come from Tailwind utilities. The browser handles the actual bar
 * rendering through the `::-webkit-progress-value` and
 * `::-moz-progress-bar` pseudo-elements. We expose them via the
 * `[&::-webkit-progress-value]:bg-primary` and
 * `[&::-moz-progress-bar]:bg-primary` Tailwind variants.
 *
 * Indeterminate state (no `value` attribute on the element) gets a
 * pulse animation via `:indeterminate { animate-pulse }`.
 */
export const progressClass = (): string =>
  [
    // Reset native styling. WebKit / Blink draw a default 3D bar that we
    // strip via appearance-none + classic clear of the border. The TRACK
    // colour is the style's (`.cn-progress` sets the element's background),
    // so the native track pseudo-element is transparent and shows it, and
    // overflow-hidden clips the fill to the style's corners. A colour here
    // would sit in the utilities layer and beat every style.
    'block h-2 overflow-hidden rounded-full bg-primary/20 w-full',
    'appearance-none overflow-hidden border-0 [&::-webkit-progress-bar]:bg-transparent',
    // Bar fill: blink/webkit + firefox both via Tailwind 4's arbitrary-
    // pseudo variant. Smooth animation on width change matches shadcn.
    "[&::-webkit-progress-value]:bg-primary [&::-webkit-progress-value]:transition-all",
    "[&::-moz-progress-bar]:bg-primary",
    // Indeterminate state animates the track itself (no value -> no bar
    // to color, so we pulse the bg).
    'indeterminate:animate-pulse',
  ].join(' ');
````

### Update the import paths to match your project setup.

## Usage

```ts
import { progressClass } from '#components/ui/progress.ts';
```

```ts
<progress value="33" max="100" aria-label="Progress" class=${progressClass()}></progress>
```

## Label

Use a [Field](https://webjs.dev/ui/docs/components/field) to add a label to the progress bar, linked by the `for` and `id` pair.

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { fieldClass, fieldLabelClass } from '#components/ui/field.ts';
import { progressClass } from '#components/ui/progress.ts';

export default function ProgressWithLabel() {
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" class=${cn(fieldClass(), 'w-full max-w-sm')}>
      <label data-slot="field-label" for="progress-upload" class=${fieldLabelClass()}>
        <span>Upload progress</span>
        <span class="ml-auto">66%</span>
      </label>
      <progress data-slot="progress" id="progress-upload" value="66" max="100" class=${progressClass()}></progress>
    </div>
  `;
}
```

## Controlled

A progress bar that can be controlled by a slider.

```ts
import { html } from '@webjsdev/core';
import { progressClass } from '#components/ui/progress.ts';
import { sliderClass } from '#components/ui/slider.ts';

// shadcn's demo keeps the bar and the slider in step through React state.
// In an app, set the bar's value from the slider's ui-value-change event
// (see the Controlled section); this preview shows both at the start value.
export default function ProgressControlled() {
  return html`
    <div class="flex w-full max-w-sm flex-col gap-4">
      <progress data-slot="progress" value="50" max="100" aria-label="Progress" class=${progressClass()}></progress>
      <ui-slider>
        <input type="range" min="0" max="100" step="1" value="50" aria-label="Value" class=${sliderClass()}>
      </ui-slider>
    </div>
  `;
}
```

The bar is a native `<progress>`, so setting its `value` is the whole update. Listen for the slider's `ui-value-change` event and write the value across:

```ts
const slider = document.querySelector('ui-slider');
const bar = document.querySelector('progress');
slider.addEventListener('ui-value-change', (event) => {
  bar.value = event.detail.value[0];
});
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { fieldClass, fieldLabelClass } from '#components/ui/field.ts';
import { progressClass } from '#components/ui/progress.ts';

// shadcn's demo switches language with a selector; the page shows its
// default, Arabic, with Arabic numerals. shadcn rotates its bar under rtl
// because Radix draws it with divs; a native <progress> already fills from
// the right in a right-to-left page.
const translations = {
  en: { dir: 'ltr', values: { label: 'Upload progress' } },
  ar: { dir: 'rtl', values: { label: 'تقدم الرفع' } },
  he: { dir: 'rtl', values: { label: 'התקדמות העלאה' } },
};

const ARABIC_NUMERALS = ['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩'];
const toArabicNumerals = (num: number) =>
  num.toString().split('').map((digit) => ARABIC_NUMERALS[Number(digit)]).join('');

export default function ProgressRtl() {
  const { dir, values: t } = translations.ar;
  return html`
    <div role="group" data-slot="field" data-orientation="vertical" dir=${dir} class=${cn(fieldClass(), 'w-full max-w-sm')}>
      <label data-slot="field-label" for="progress-upload-rtl" class=${fieldLabelClass()}>
        <span>${t.label}</span>
        <span class="ms-auto">${toArabicNumerals(66)}%</span>
      </label>
      <progress data-slot="progress" id="progress-upload-rtl" value="66" max="100" class=${progressClass()}></progress>
    </div>
  `;
}
```

## API Reference

### progressClass

`progressClass()` returns the classes for a native `<progress>` element. It takes no options. The element supplies the `progressbar` role and its value to assistive technology on its own, so the one thing to add is an accessible name, an `aria-label` or a `<label for>`.

| Attribute | Type | Default |
| --- | --- | --- |
| `value` | `number` |  |
| `max` | `number` | `1` |

Leave `value` off for the indeterminate state, which pulses.
