Slide to Unlock

# Brok UI: Slide to Unlock (`slide-to-unlock`)

The iOS slide-to-unlock control: a pill track with a shimmering label and a draggable thumb that unlocks when dragged past a threshold, dispatching an 'unlock' event.

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

## Install

```bash
php artisan ui:add slide-to-unlock
```

## 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.slide-to-unlock class="w-full max-w-xs" />
</div>
```

## Props

- `label` (mixed|null, default `null`) — Text shown while locked; defaults to "slide to unlock".
- `unlockedLabel` (mixed|null, default `null`) — Text shown and announced once unlocked; defaults to "unlocked".
- `threshold` (float, default `0.9`) — Fraction of the track width (0-1) the thumb must cross to unlock.
- `name` (mixed|null, default `null`) — Renders a hidden input (1 when unlocked) for form posts.

## Use when

- Use for immediate state changes that are obvious and reversible.
- Confirming a deliberate, hard-to-trigger-by-accident action, such as unlocking a device-style screen or arming a destructive action.
- Wanting the classic iOS slide-to-unlock gesture with a shimmering label.

## Avoid when

- Do not use for choices that need explanation, confirmation, or a later Save step.
- Collecting a numeric value; use slider or scrubber instead.
- Confirming an action that should also work with a single tap/click without a drag gesture; use button with a confirmation dialog instead.

## Anti-patterns

- Using a switch when Save is required
- Using a switch for irreversible actions

## Rules

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

@props([
    'label' => null,
    'unlockedLabel' => null,
    'threshold' => 0.9,
    'name' => null,
])

@php
    // iOS "slide to unlock". The centred label is rendered as shimmering text via
    // `bg-clip-text text-transparent` over a TOKEN gradient (from-/via-/to- semantic
    // tokens) — no raw colour anywhere. Only `background-position` is animated below;
    // the colours come from the Tailwind token utilities in the class list. The thumb
    // is positioned with `transform: translateX(px)` bound via x-bind:style (a standard
    // CSS string, not a spliced utility class). Reduced-motion users get a static label.
    $label = $label ?? __('slide to unlock');
    $unlockedLabel = $unlockedLabel ?? __('unlocked');
    $threshold = is_numeric($threshold) ? max(0.0, min(1.0, (float) $threshold)) : 0.9;
@endphp

<style>
    @keyframes ui-stu-shimmer {
        0%   { background-position: 200% center; }
        100% { background-position: -200% center; }
    }
    [data-slot="slide-to-unlock"] .ui-stu-shimmer {
        background-size: 200% auto;
        animation: ui-stu-shimmer 3s linear infinite;
    }
    @media (prefers-reduced-motion: reduce) {
        [data-slot="slide-to-unlock"] .ui-stu-shimmer {
            animation: none;
        }
    }
</style>

<div
    x-data="uiSlideToUnlock({ threshold: @js((float) $threshold) })"
    data-slot="slide-to-unlock"
    role="button"
    tabindex="0"
    aria-label="{{ $label }}"
    :aria-pressed="unlocked ? 'true' : 'false'"
    @keydown.enter.prevent="unlock()"
    @keydown.space.prevent="unlock()"
    {{ $attributes->merge(['class' => 'relative isolate flex h-12 select-none items-center overflow-hidden rounded-full bg-muted px-1 outline-none focus-visible:ring-2 focus-visible:ring-ring']) }}
>
    {{-- Shimmering centred label (decorative; real state is announced via aria-live below) --}}
    <span
        data-slot="slide-to-unlock-label"
        aria-hidden="true"
        class="pointer-events-none absolute inset-0 flex items-center justify-center px-12 text-sm font-medium"
    >
        <span
            x-show="!unlocked"
            class="ui-stu-shimmer bg-gradient-to-r from-muted-foreground/40 via-foreground to-muted-foreground/40 bg-clip-text text-transparent"
        >{{ $label }}</span>
        <span
            x-show="unlocked"
            x-cloak
            class="inline-flex items-center gap-2 text-foreground"
        >
            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4" aria-hidden="true">
                <path d="M20 6 9 17l-5-5" />
            </svg>
            {{ $unlockedLabel }}
        </span>
    </span>

    {{-- Draggable thumb --}}
    <span
        data-slot="slide-to-unlock-thumb"
        aria-hidden="true"
        @pointerdown="startDrag($event)"
        x-ref="thumb"
        :class="dragging ? '' : 'transition-transform motion-reduce:transition-none'"
        x-bind:style="thumbStyle()"
        class="relative z-10 inline-flex size-10 shrink-0 cursor-grab touch-none items-center justify-center rounded-full bg-background text-foreground shadow active:cursor-grabbing"
    >
        <svg x-show="!unlocked" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-5 rtl:-scale-x-100" aria-hidden="true">
            <path d="m9 18 6-6-6-6" />
        </svg>
        <svg x-show="unlocked" x-cloak viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-5" aria-hidden="true">
            <path d="M20 6 9 17l-5-5" />
        </svg>
    </span>

    {{-- Polite status announcement for assistive tech --}}
    <span data-slot="slide-to-unlock-status" class="sr-only" aria-live="polite">
        <span x-text="unlocked ? @js($unlockedLabel) : ''"></span>
    </span>

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

/**
 * Slide-to-unlock behavior — the iOS pill control.
 *
 * A draggable thumb sits at the start of a pill track. Pointer drag translates the
 * thumb along the track (clamped to [0, maxTravel], where maxTravel is the track's
 * inner width minus the thumb width, measured from the rendered DOM). On release, if
 * the thumb has crossed `threshold` (a fraction of the travel, default 0.9) the control
 * unlocks: the thumb locks at the end, the label swaps to its success state, the hidden
 * input flips to '1', and a bubbling `unlock` CustomEvent is dispatched. Released before
 * the threshold, the thumb springs back to 0 (CSS transition toggled via `dragging`).
 *
 * Keyboard fallback: Enter/Space on the root calls unlock() directly so the control is
 * fully operable without a pointer. Direction-aware so the drag axis still feels correct
 * under `dir="rtl"`.
 *
 * Pointer move/up listeners live on `document` and are removed on pointerup AND in
 * destroy(), so unmounting mid-drag can never leak a listener.
 *
 * 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('uiSlideToUnlock', (config = {}) => ({
        threshold: config.threshold ?? 0.9,

        x: 0,
        maxTravel: 0,
        dragging: false,
        unlocked: false,
        root: null,

        /** Bound document listeners, kept so they can be torn down. */
        _move: null,
        _up: null,

        init() {
            // `$el` is whichever element the running expression sits on — the thumb
            // inside its pointerdown handler — so the track is pinned here.
            this.root = this.$el;
            this.$nextTick(() => this.measure());
        },

        destroy() {
            this.stopListening();
        },

        /** Track inner width minus thumb width = furthest the thumb can travel. */
        measure() {
            const track = this.root.getBoundingClientRect();
            const thumb = this.$refs.thumb?.getBoundingClientRect();
            if (!thumb) return;
            // Account for the px-1 (4px each side) padding on the track.
            const style = getComputedStyle(this.root);
            const padStart = parseFloat(style.paddingInlineStart) || 0;
            const padEnd = parseFloat(style.paddingInlineEnd) || 0;
            this.maxTravel = Math.max(0, track.width - thumb.width - padStart - padEnd);
        },

        rtl() {
            return getComputedStyle(this.root).direction === 'rtl';
        },

        /** The thumb's transform: travel runs toward the end edge, so RTL flips it. */
        thumbStyle() {
            return `transform: translateX(${this.rtl() ? -this.x : this.x}px)`;
        },

        startDrag(e) {
            if (this.unlocked) return;
            e.preventDefault();
            this.measure();
            this.dragging = true;

            const startX = e.clientX;
            const startOffset = this.x;
            const sign = this.rtl() ? -1 : 1;

            this._move = (ev) => {
                const delta = (ev.clientX - startX) * sign;
                this.x = Math.min(this.maxTravel, Math.max(0, startOffset + delta));
            };
            this._up = () => this.release();

            document.addEventListener('pointermove', this._move);
            document.addEventListener('pointerup', this._up);
            document.addEventListener('pointercancel', this._up);
        },

        release() {
            this.stopListening();
            this.dragging = false;
            if (this.maxTravel > 0 && this.x / this.maxTravel >= this.threshold) {
                this.unlock();
            } else {
                this.x = 0;
            }
        },

        unlock() {
            if (this.unlocked) return;
            this.measure();
            this.unlocked = true;
            this.x = this.maxTravel;
            this.root.dispatchEvent(new CustomEvent('unlock', { bubbles: true }));
        },

        stopListening() {
            if (this._move) document.removeEventListener('pointermove', this._move);
            if (this._up) {
                document.removeEventListener('pointerup', this._up);
                document.removeEventListener('pointercancel', this._up);
            }
            this._move = null;
            this._up = null;
        },
    }));
});