Slider

# Brok UI: Angle Slider (`angle-slider`)

A circular dial control for selecting an angle value between 0° and 360°.

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

## Install

```bash
php artisan ui:add angle-slider
```

## Usage

```blade
<x-ui.angle-slider :value="45" name="angle" />
```

## Props

- `value` (int, default `0`) — Current angle.
- `min` (int, default `0`) — Minimum angle.
- `max` (int, default `360`) — Maximum angle.
- `step` (int, default `1`) — Degrees per keyboard step.
- `size` (int, default `160`) — Diameter of the dial, in pixels.
- `name` (mixed|null, default `null`) — Renders a hidden input with this name for form posts.

## Use when

- Use when continuous adjustment or immediate visual feedback helps users choose a value.
- Selecting a rotational value such as a compass heading, hue angle or gradient direction.
- Wanting a dial-style control instead of a linear track.

## Avoid when

- Do not use for precise values or broad ranges without good landmarks; direct entry is better when accuracy matters.
- Selecting a plain linear numeric value; use slider instead.

## Anti-patterns

- Using sliders for precise or unbounded values

## Rules

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

@props([
    'value' => 0,
    'min'   => 0,
    'max'   => 360,
    'step'  => 1,
    'size'  => 160,
    'name'  => null,
])
<div
    x-data="uiAngleSlider({ value: @js((float) $value), min: @js((float) $min), max: @js((float) $max), step: @js((float) $step) })"
    {{-- Modelable: `x-model` (Alpine) and `wire:model` (Livewire binds through
         the same x-model contract) attach to the root. Inert without either. --}}
    x-modelable="value"
    data-slot="angle-slider"
    @pointerdown="startDrag($event)"
    style="width: {{ (int) $size }}px; height: {{ (int) $size }}px;"
    {{ $attributes->merge(['class' => 'relative inline-flex cursor-pointer touch-none select-none items-center justify-center rounded-full']) }}
>
    {{-- Track ring, sweep arc from 0° (top, clockwise) to the value, and quarter ticks --}}
    <svg data-slot="angle-slider-track" class="absolute inset-0 size-full" viewBox="0 0 100 100" aria-hidden="true">
        <circle cx="50" cy="50" r="45" fill="none" class="stroke-muted" stroke-width="6" />
        <circle
            cx="50" cy="50" r="45" fill="none"
            class="stroke-primary transition-[stroke-dashoffset] motion-reduce:transition-none"
            stroke-width="6" stroke-linecap="round" pathLength="360"
            stroke-dasharray="360"
            :stroke-dashoffset="360 - value"
            :style="dragging ? 'transition: none' : ''"
            transform="rotate(-90 50 50)"
        />
        @foreach ([0, 90, 180, 270] as $tick)
            <line x1="50" y1="1" x2="50" y2="4" class="stroke-muted-foreground/60" stroke-width="1.5" stroke-linecap="round" transform="rotate({{ $tick }} 50 50)" />
        @endforeach
    </svg>

    {{-- Draggable grip on the ring --}}
    <span
        data-slot="angle-slider-thumb"
        role="slider"
        tabindex="0"
        aria-label="{{ __('Angle') }}"
        aria-orientation="horizontal"
        aria-valuemin="{{ $min }}"
        aria-valuemax="{{ $max }}"
        :aria-valuenow="value"
        :aria-valuetext="`${value}°`"
        @keydown="onKey($event)"
        class="absolute top-0 left-0 size-5 rounded-full border-2 border-background bg-primary shadow-md ring-1 ring-border transition-transform focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background motion-reduce:transition-none"
        :style="`transform: translate(${thumbLeft}px, ${thumbTop}px);${dragging ? ' transition: none;' : ''}`"
    ></span>

    {{-- Central readout --}}
    <span
        data-slot="angle-slider-readout"
        class="pointer-events-none flex select-none flex-col items-center leading-none"
        aria-hidden="true"
    >
        <span class="text-lg font-semibold tabular-nums text-foreground" x-text="`${value}°`"></span>
    </span>

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

/**
 * Angle Slider behavior — a circular dial that selects an angle value (0–360°).
 *
 * The thumb is absolutely positioned on the circumference of the circular track
 * using trigonometry derived from the current `value` (in degrees). Pointer drag
 * calculates the new angle via `atan2` from the element centre. Keyboard input
 * supports Arrow keys (±step), Home (min) and End (max). The `radius` reactive
 * property is computed at init time from the element's rendered size so that it
 * works with any `size` prop without needing a hard-coded constant.
 *
 * 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('uiAngleSlider', (config = {}) => ({
        value:  config.value  ?? 0,
        min:    config.min    ?? 0,
        max:    config.max    ?? 360,
        step:   config.step   ?? 1,

        /** Half the element's rendered width/height — set in init(). */
        radius: 60,

        /** True while a pointer drag owns the dial (kills transitions inline). */
        dragging: false,

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

        /** Thumb position (top-left corner in px) on the ring, which sits at 90% of the radius; the thumb is 20px. */
        get ringRadius() {
            return this.radius * 0.9;
        },
        get thumbTop() {
            const rad = ((this.value - 90) * Math.PI) / 180;
            return this.radius + this.ringRadius * Math.sin(rad) - 10;
        },
        get thumbLeft() {
            const rad = ((this.value - 90) * Math.PI) / 180;
            return this.radius + this.ringRadius * Math.cos(rad) - 10;
        },

        init() {
            // Derive radius from the rendered element dimensions.
            this.$nextTick(() => {
                const r = this.$el.getBoundingClientRect();
                if (r.width > 0) {
                    this.radius = r.width / 2;
                }
            });
            this.value = this.clamp(this.value);
        },

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

        clamp(v) {
            v = Math.round(v / this.step) * this.step;
            return Math.min(this.max, Math.max(this.min, v));
        },

        /**
         * Compute the angle (in degrees, 0 = top, clockwise) from the centre of
         * the element to the pointer position.
         */
        angleFromPointer(clientX, clientY) {
            const r   = this.$el.getBoundingClientRect();
            const cx  = r.left + r.width  / 2;
            const cy  = r.top  + r.height / 2;
            const dx  = clientX - cx;
            const dy  = clientY - cy;
            // atan2 returns angle from positive-x axis; we want 0 = top (negative-y).
            let deg = (Math.atan2(dx, -dy) * 180) / Math.PI;
            if (deg < 0) deg += 360;
            return this.clamp(deg);
        },

        startDrag(e) {
            e.preventDefault();
            this.dragging = true;
            this.value = this.angleFromPointer(e.clientX, e.clientY);

            // Bind once so the same refs can be removed later (here or in destroy()).
            this._move = (ev) => {
                this.value = this.angleFromPointer(ev.clientX, ev.clientY);
            };
            this._up = () => {
                this.dragging = false;
                window.removeEventListener('pointermove', this._move);
                window.removeEventListener('pointerup',   this._up);
            };
            window.addEventListener('pointermove', this._move);
            window.addEventListener('pointerup',   this._up);
        },

        onKey(e) {
            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 'Home':
                    e.preventDefault();
                    this.value = this.min;
                    break;
                case 'End':
                    e.preventDefault();
                    this.value = this.max;
                    break;
            }
        },
    }));
});