Progress

# Brok UI: Progress (`progress`)

Displays a determinate progress indicator with an optional threshold tone and a striped or shimmer animated fill.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add progress
```

## Usage

```blade
<div class="w-full max-w-sm space-y-6">
    <div class="space-y-2">
        <p class="text-sm text-muted-foreground">{{ __('Uploading…') }} (60%)</p>
        <x-ui.progress value="60" />
    </div>
    <div class="space-y-2">
        <p class="text-sm text-muted-foreground">{{ __('Working…') }} ({{ __('indeterminate') }})</p>
        <x-ui.progress indeterminate />
    </div>
</div>
```

## Props

- `value` (int, default `0`) — Current value, clamped between 0 and max.
- `max` (int, default `100`) — Maximum value the indicator represents.
- `indeterminate` (bool, default `false`) — Renders an animated marquee fill instead of a determinate width.
- `tone` (neutral|primary|success|warning|destructive|default, default `neutral`) — Fill colour: neutral (the foreground colour, so primary stays reserved for the main action and focus), primary (the brand primary), or the threshold tones success, warning and destructive. default is kept as an alias of neutral.
- `animation` (string, default `none`) — Decorative overlay on the determinate fill: none, striped, or shimmer; ignored while indeterminate.
- `label` (mixed|null, default `null`) — Accessible name for the progressbar; falls back to a generic "Progress" label when no aria-label/aria-labelledby is supplied.
- `bind` (mixed|null, default `null`) — An Alpine expression for a live value; the indicator width and aria-valuenow follow it instead of the static value prop.
- `size` (default|edge, default `default`) — Track shape: default is the 8px rounded bar; edge is a 2px square-ended strip (data-size="edge") that sits on the top edge of a panel or row while background work runs. Position it with the consumer's class (for example absolute inset-x-0 top-0 inside a relative parent); the strip drops its own relative position when that class sets absolute, fixed or sticky. Works with indeterminate, tone and bind.

## Use when

- Use to show real progress, ordered stages, or process status when visibility helps completion.
- Showing a determinate percentage-complete value for uploads, wizards, or long-running tasks.
- Needing an indeterminate marquee state before a real percentage is known.

## Avoid when

- Do not add progress UI to tiny tasks or to flows whose steps are not meaningfully sequential.
- Showing a looping, self-contained onboarding checklist; use onboard-card instead.
- Indicating a generic busy state with no measurable percentage; use spinner or a loader component instead.

## Anti-patterns

- Decorative or inaccurate progress
- Steppers for nonsequential exploration

## Rules

- Use the `<brok:progress>` tag (or `<x-ui.progress>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/progress
- Registry JSON (files, props, contract): https://brokui.dev/r/open/progress.json

@props([
    'value' => 0,
    'max' => 100,
    'indeterminate' => false,
    // neutral (default) | primary | success | warning | destructive. `default`
    // is kept as an alias of neutral for 1.x callers.
    'tone' => 'neutral',
    // 'none' (default) | 'striped' | 'shimmer' — decorative motion over the
    // determinate fill. Ignored while indeterminate (which has its own marquee).
    'animation' => 'none',
    // Accessible name — role="progressbar" requires one (WCAG). Pass a
    // meaningful label in context; falls back to a generic name. Skipped when
    // the consumer supplies aria-label/aria-labelledby themselves.
    'label' => null,
    // An Alpine expression for a live value (a wizard step, an upload count):
    // the indicator width and aria-valuenow follow it, so a block never needs
    // a second hand-rolled track beside the server-rendered one.
    'bind' => null,
    // default (8px rounded track) | edge (a 2px square-ended strip that sits
    // on the top edge of a panel or row while background work runs).
    'size' => 'default',
])
@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $value = max(0, min((float) $value, (float) $max));
    $pct = $max > 0 ? round($value / $max * 100, 2) : 0;
    // The fallbacks keep an older _styles.php (without neutral/primary) working.
    $tones = $styles['progress']['tones'] + ['neutral' => 'bg-foreground', 'primary' => 'bg-primary'];
    $tone = array_key_exists($tone, $tones) && $tone !== 'default' ? $tone : 'neutral';
    // The fill colour is drawn from the root's data-tone (the group variants),
    // so a live tone change on the root recolours the indicator, not the track.
    $toneClass = $tones[$tone].' group-data-[tone=neutral]/progress:bg-foreground group-data-[tone=default]/progress:bg-foreground group-data-[tone=primary]/progress:bg-primary group-data-[tone=success]/progress:bg-success group-data-[tone=warning]/progress:bg-warning group-data-[tone=destructive]/progress:bg-destructive';
    $animation = in_array($animation, ['none', 'striped', 'shimmer'], true) ? $animation : 'none';
    $animated = ! $indeterminate && $animation !== 'none';
    $size = $size === 'edge' ? 'edge' : 'default';
    $edge = $size === 'edge';
    // An edge strip is usually pinned by the caller (absolute inset-x-0
    // top-0), so it only claims `relative` when no position class is given.
    $positioned = preg_match('/(?:^|\s)!?(?:absolute|fixed|sticky)(?:\s|$)/', (string) $attributes->get('class', '')) === 1;
    $rootClass = $edge
        ? 'group/progress w-full overflow-hidden bg-muted '.($positioned ? '' : 'relative ').($styles['progress']['sizes']['edge'] ?? 'h-0.5 rounded-none')
        : 'group/progress relative h-2 w-full overflow-hidden rounded-full bg-muted';
    $needsName = $label === null && ! $attributes->has('aria-label') && ! $attributes->has('aria-labelledby');
@endphp
<div
    data-slot="progress"
    role="progressbar"
    aria-valuemin="0"
    aria-valuemax="{{ $max }}"
    @if ($label !== null) aria-label="{{ $label }}" @elseif ($needsName) aria-label="{{ __('Progress') }}" @endif
    @unless ($indeterminate) aria-valuenow="{{ $value }}" @endunless
    @if ($bind !== null && ! $indeterminate) x-bind:aria-valuenow="{{ $bind }}" @endif
    data-state="{{ $indeterminate ? 'indeterminate' : 'determinate' }}"
    data-tone="{{ $tone }}"
    @if ($animated) data-animation="{{ $animation }}" @endif
    @if ($edge) data-size="edge" @endif
    {{ $attributes->merge(['class' => $rootClass]) }}
>
    @if ($indeterminate)
        {{-- Animated marquee bar (RTL-safe via inset-inline-start; see ui.css keyframes). --}}
        <div
            data-slot="progress-indicator"
            @class([
                'absolute inset-y-0 w-2/5',
                'rounded-none' => $edge,
                'rounded-full' => ! $edge,
                'motion-safe:animate-[ui-progress-indeterminate_1.4s_ease-in-out_infinite] motion-reduce:w-full',
                $toneClass,
            ])
        ></div>
    @else
        <div
            data-slot="progress-indicator"
            @class([
                'h-full',
                'rounded-none' => $edge,
                'rounded-full' => ! $edge,
                'transition-[width] duration-300 ease-out motion-reduce:transition-none',
                $toneClass,
            ])
            style="width: {{ $pct }}%;"
            @if ($bind !== null) x-bind:style="'width: ' + Math.max(0, Math.min(100, ({{ $bind }}) / {{ (float) $max }} * 100)) + '%'" @endif
        ></div>
    @endif

    @if ($animated)
        {{-- Striped / shimmer overlay. Colour comes from the surface token at low
             opacity (hsl(var()) is the repo's safe in-<style> token form — it is
             NOT an inline style, so it never trips the raw-colour guards). The
             sweep is gated behind prefers-reduced-motion so it sits still for
             reduced-motion users while keeping the texture. --}}
        <style>
            [data-slot="progress"][data-animation="striped"] [data-slot="progress-indicator"] {
                background-image: repeating-linear-gradient(
                    45deg,
                    color-mix(in oklab, var(--background-color, hsl(var(--background))) calc(0.22 * 100%), transparent) 0 0.5rem,
                    transparent 0.5rem 1rem
                );
                background-size: 1rem 1rem;
            }
            [data-slot="progress"][data-animation="shimmer"] [data-slot="progress-indicator"] {
                background-image: linear-gradient(
                    90deg,
                    transparent 0%,
                    color-mix(in oklab, var(--background-color, hsl(var(--background))) calc(0.45 * 100%), transparent) 50%,
                    transparent 100%
                );
                background-size: 200% 100%;
                background-repeat: no-repeat;
            }
            @media (prefers-reduced-motion: no-preference) {
                [data-slot="progress"][data-animation="striped"] [data-slot="progress-indicator"] {
                    animation: ui-progress-stripes 1s linear infinite;
                }
                [data-slot="progress"][data-animation="shimmer"] [data-slot="progress-indicator"] {
                    animation: ui-progress-shimmer 1.6s ease-in-out infinite;
                }
            }
            @keyframes ui-progress-stripes {
                from { background-position-x: 0; }
                to { background-position-x: 1rem; }
            }
            @keyframes ui-progress-shimmer {
                from { background-position-x: 200%; }
                to { background-position-x: -200%; }
            }
        </style>
    @endif
</div>