Slider

# Brok UI: Scrubber (`scrubber`)

A Figma-style drag-to-scrub numeric control: drag anywhere along a labeled track to scrub the value, with optional tick marks, a live tabular-nums readout, and a thumb that springs in on hover or focus. Fully keyboard-accessible and direction-aware.

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

## Install

```bash
php artisan ui:add scrubber
```

## Usage

```blade
<div class="flex min-h-40 w-full items-center justify-center rounded-lg border border-border bg-card p-8">
    <x-ui.scrubber class="w-full max-w-xs" />
</div>
```

## Props

- `name` (mixed|null, default `null`) — Renders a hidden input with this name for form posts.
- `min` (int, default `0`) — Minimum value.
- `max` (int, default `100`) — Maximum value.
- `step` (int, default `1`) — Keyboard/drag snap increment.
- `value` (int, default `50`) — Current value.
- `label` (mixed|null, default `null`) — Optional text label shown beside the readout.
- `ticks` (bool, default `true`) — Shows evenly spaced tick marks under the track (capped at 20) when true.
- `unit` (mixed|null, default `null`) — Suffix appended to the readout, such as "px" or "%".

## Use when

- Use when continuous adjustment or immediate visual feedback helps users choose a value.
- Building a Figma-style numeric control where dragging anywhere on the track, not just the thumb, scrubs the value.
- Wanting optional tick marks and a live tabular-nums readout beside a compact draggable control.

## Avoid when

- Do not use for precise values or broad ranges without good landmarks; direct entry is better when accuracy matters.
- Wanting the thumb to stay visible at rest rather than spring in on hover/focus; use slider instead.

## Anti-patterns

- Using sliders for precise or unbounded values

## Rules

- Use the `<brok:scrubber>` tag (or `<x-ui.scrubber>`) 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/scrubber
- Registry JSON (files, props, contract): https://brokui.dev/r/open/scrubber.json

@props([
    'name' => null,
    'min' => 0,
    'max' => 100,
    'step' => 1,
    'value' => 50,
    'label' => null,
    'ticks' => true,
    'unit' => null,
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $recipe = $styles['slider'];
    $min = (float) $min;
    $max = (float) $max;
    $step = (float) $step;
    $value = max($min, min($max, (float) $value));
    $ticks = filter_var($ticks, FILTER_VALIDATE_BOOL);
    $unit = $unit === null ? '' : (string) $unit;
    $ariaLabel = $label ? __($label) : __('Value');

    // Build a small, capped set of evenly spaced tick positions (as percentages).
    $tickMarks = [];
    if ($ticks && $max > $min && $step > 0) {
        $count = (int) round(($max - $min) / $step);
        // Cap at 21 tick marks so dense ranges stay legible and cheap to render.
        $shown = min($count, 20);
        for ($i = 0; $i <= $shown; $i++) {
            $tickMarks[] = round(($i / $shown) * 100, 4);
        }
    }
@endphp

{{--
    Scrubber — a Figma-style drag-to-scrub numeric control. Drag anywhere on the track
    to scrub the value (snapped to `step`); the fill and thumb are positioned with the
    logical `inset-inline-start` so the control mirrors under dir="rtl", and both pointer
    and keyboard input are direction-aware. Optional tick marks sit under the track, and
    a live tabular-nums readout shows the formatted value. The thumb scales in on hover or
    focus via a motion-safe spring. An optional hidden input tracks the value for form posts.
--}}
<div
    data-slot="scrubber"
    x-data="uiScrubber({ min: @js($min), max: @js($max), step: @js($step), value: @js($value), unit: @js($unit) })"
    {{ $attributes->merge(['class' => 'flex flex-col gap-2']) }}
>
    <style>
        [data-slot="scrubber"] [data-slot="scrubber-thumb"] {
            transform: translateX(-50%) scale(0.55);
        }
        [dir="rtl"] [data-slot="scrubber"] [data-slot="scrubber-thumb"] {
            transform: translateX(50%) scale(0.55);
        }
        [data-slot="scrubber"]:hover [data-slot="scrubber-thumb"],
        [data-slot="scrubber"] [data-slot="scrubber-thumb"]:focus-visible,
        [data-slot="scrubber"][data-dragging="true"] [data-slot="scrubber-thumb"] {
            transform: translateX(-50%) scale(1);
        }
        [dir="rtl"] [data-slot="scrubber"]:hover [data-slot="scrubber-thumb"],
        [dir="rtl"] [data-slot="scrubber"] [data-slot="scrubber-thumb"]:focus-visible,
        [dir="rtl"] [data-slot="scrubber"][data-dragging="true"] [data-slot="scrubber-thumb"] {
            transform: translateX(50%) scale(1);
        }
        @media (prefers-reduced-motion: reduce) {
            [data-slot="scrubber"] [data-slot="scrubber-thumb"] {
                transform: translateX(-50%) scale(1);
            }
            [dir="rtl"] [data-slot="scrubber"] [data-slot="scrubber-thumb"] {
                transform: translateX(50%) scale(1);
            }
        }
    </style>

    {{-- Optional text label + live value readout --}}
    <div class="flex items-baseline justify-between gap-3">
        @if ($label)
            <span data-slot="scrubber-label" class="text-sm font-medium text-foreground">{{ __($label) }}</span>
        @endif
        <output
            data-slot="scrubber-value"
            class="text-sm font-medium tabular-nums text-muted-foreground {{ $label ? '' : 'ms-auto' }}"
            x-text="display"
        >{{ $value }}{{ $unit }}</output>
    </div>

    {{-- Track + fill + thumb. Dragging anywhere on the control scrubs the value. --}}
    <div
        data-slot="scrubber-control"
        x-bind:data-dragging="dragging.toString()"
        @pointerdown="startDrag($event)"
        class="{{ $recipe['control'] }} w-full py-3"
    >
        <div
            x-ref="track"
            data-slot="scrubber-track"
            class="{{ $recipe['track'] }}"
        >
            <div
                data-slot="scrubber-fill"
                class="{{ $recipe['fill'] }}"
                x-bind:style="`inset-inline-start: 0; width: ${percent(value)}%`"
            ></div>

            @if (! empty($tickMarks))
                <div data-slot="scrubber-ticks" aria-hidden="true" class="pointer-events-none absolute inset-x-0 top-full mt-2 h-1">
                    @foreach ($tickMarks as $pos)
                        <span
                            class="absolute top-0 h-1 w-px -translate-x-1/2 rounded-full bg-border rtl:translate-x-1/2"
                            style="inset-inline-start: {{ $pos }}%"
                        ></span>
                    @endforeach
                </div>
            @endif
        </div>

        <span
            data-slot="scrubber-thumb"
            role="slider"
            tabindex="0"
            aria-orientation="horizontal"
            x-bind:aria-valuemin="min"
            x-bind:aria-valuemax="max"
            x-bind:aria-valuenow="value"
            x-bind:aria-valuetext="display"
            aria-label="{{ $ariaLabel }}"
            @keydown="onKey($event)"
            class="{{ $recipe['thumb'] }} {{ $recipe['thumbSizes']['md'] }} shadow-md transition-transform duration-200 ease-out will-change-transform"
            x-bind:style="`inset-inline-start: ${percent(value)}%`"
        ></span>
    </div>

    @if ($name)
        <input type="hidden" name="{{ $name }}" x-bind:value="value" />
    @endif
</div>

/**
 * Scrubber behavior — a Figma-style drag-to-scrub numeric control.
 *
 * Holds one numeric `value`, clamped to [min, max] and snapped to `step`. The fill and
 * thumb are positioned with the logical `inset-inline-start`, so the control mirrors
 * automatically under `dir="rtl"`; pointer and keyboard input account for direction so
 * dragging and arrow keys always feel correct.
 *
 * Dragging anywhere on the track scrubs the value continuously; pointermove updates the
 * value while the pointer is held. Pointer listeners are added to `document` only for
 * the duration of a drag and are always removed on pointerup AND in `destroy()`, so
 * unmounting mid-drag can't leak.
 *
 * Self-registers on `alpine:init` so import order does not matter — import this file
 * once from your bundle (e.g. resources/js/ui/index.js).
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiScrubber', (config = {}) => ({
        min: config.min ?? 0,
        max: config.max ?? 100,
        step: config.step ?? 1,
        value: config.value ?? 50,
        unit: config.unit ?? '',

        dragging: false,

        // Bound listener refs so we can remove exactly what we added.
        _move: null,
        _up: null,

        init() {
            this.value = this.clamp(this.value);
            this._move = (e) => this.onMove(e);
            this._up = () => this.endDrag();
        },

        destroy() {
            // Remove any listeners still attached if unmounted mid-drag.
            document.removeEventListener('pointermove', this._move);
            document.removeEventListener('pointerup', this._up);
        },

        clamp(v) {
            v = Math.round(v / this.step) * this.step;
            v = Math.min(this.max, Math.max(this.min, v));
            const fromStep = String(this.step).split('.')[1]?.length ?? 0;
            return fromStep ? Number(v.toFixed(fromStep)) : v;
        },

        percent(v) {
            return this.max > this.min
                ? ((v - this.min) / (this.max - this.min)) * 100
                : 0;
        },

        /** Formatted readout, e.g. "50%". */
        get display() {
            return `${this.value}${this.unit}`;
        },

        valueFromClientX(clientX) {
            const r = this.$refs.track.getBoundingClientRect();
            let ratio = (clientX - r.left) / r.width;
            ratio = Math.min(1, Math.max(0, ratio));
            if (getComputedStyle(this.$el).direction === 'rtl') ratio = 1 - ratio;
            return this.min + ratio * (this.max - this.min);
        },

        startDrag(e) {
            e.preventDefault();
            this.dragging = true;
            this.apply(e.clientX);
            document.addEventListener('pointermove', this._move);
            document.addEventListener('pointerup', this._up);
        },

        onMove(e) {
            this.apply(e.clientX);
        },

        apply(clientX) {
            this.value = this.clamp(this.valueFromClientX(clientX));
        },

        endDrag() {
            this.dragging = false;
            document.removeEventListener('pointermove', this._move);
            document.removeEventListener('pointerup', this._up);
        },

        onKey(e) {
            const big = Math.max(this.step, this.step * 10);
            switch (e.key) {
                case 'ArrowLeft':
                case 'ArrowDown':
                    e.preventDefault();
                    this.value = this.clamp(this.value - this.step);
                    break;
                case 'ArrowRight':
                case 'ArrowUp':
                    e.preventDefault();
                    this.value = this.clamp(this.value + this.step);
                    break;
                case 'PageDown':
                    e.preventDefault();
                    this.value = this.clamp(this.value - big);
                    break;
                case 'PageUp':
                    e.preventDefault();
                    this.value = this.clamp(this.value + big);
                    break;
                case 'Home':
                    e.preventDefault();
                    this.value = this.min;
                    break;
                case 'End':
                    e.preventDefault();
                    this.value = this.max;
                    break;
            }
        },
    }));
});