Reorder

# Brok UI: Sortable (`sortable`)

A drag-to-reorder list that moves the way the kanban board does: the row lifts under the pointer, a live placeholder and gliding rows show where it lands; keyboard reordering from the grip, hidden inputs mirroring the order, and a change event.

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

## Install

```bash
php artisan ui:add sortable
```

## Usage

```blade
<div class="w-full max-w-md">
    <x-ui.sortable name="order" />
</div>
```

## Props

- `items` (array, default `[…]`) — Array of items, each with an id, a label, and an optional meta line.
- `name` (string, default `order`) — Field name used for the hidden inputs that mirror the current order as name[].

## Use when

- Use to group related content into scannable units for browsing, prioritization, or rearrangement.
- Letting users reorder a single flat list of items, such as a priority list or a set of steps.
- Needing the new order to submit in a plain form via hidden inputs, without a full JavaScript round trip.

## Avoid when

- Do not use card-like structures when dense row-by-row comparison would be clearer in a list or table.
- Items need to move between grouped columns or lanes; use kanban instead.
- The list is a uniform grid of tiles rather than a vertical list; use swappable-grid.

## Anti-patterns

- Turning every object into a card

## Rules

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

@props([
    'items' => [
        ['id' => 'a', 'label' => 'Research competitors', 'meta' => 'Due Monday'],
        ['id' => 'b', 'label' => 'Draft the proposal', 'meta' => 'In review'],
        ['id' => 'c', 'label' => 'Design the landing page', 'meta' => 'Assigned'],
        ['id' => 'd', 'label' => 'Ship the release', 'meta' => 'Blocked'],
    ],
    'name' => 'order',
])

<div
    x-data="uiSortable({ items: @js(array_values($items)), name: @js($name) })"
    data-slot="sortable"
    {{ $attributes->merge(['class' => 'relative w-full']) }}
>
    <ul role="list" class="flex flex-col gap-2">
        <template x-for="(it, i) in items" :key="it.id">
            <li
                data-slot="sortable-item"
                role="listitem"
                x-bind:data-id="it.id"
                x-bind:data-index="i"
                x-bind:data-placeholder="isDragging(it.id) ? 'true' : null"
                @pointerdown="startDrag($event, i)"
                class="flex cursor-grab touch-none select-none items-center gap-3 rounded-md border border-border bg-card p-3 text-card-foreground shadow-xs transition-[box-shadow,border-color] hover:border-input active:cursor-grabbing data-[placeholder=true]:border-dashed data-[placeholder=true]:bg-muted/60 data-[placeholder=true]:shadow-none data-[placeholder=true]:[&>*]:invisible motion-reduce:transition-none"
            >
                {{-- Handle: the keyboard target (Arrow keys reorder); the whole row drags. --}}
                <button
                    type="button"
                    data-slot="sortable-handle"
                    x-bind:data-index="i"
                    @keydown="onKey($event, i)"
                    aria-label="{{ __('Drag to reorder') }}"
                    class="inline-flex shrink-0 cursor-grab items-center justify-center rounded text-muted-foreground outline-none transition-colors hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background active:cursor-grabbing motion-reduce:transition-none"
                >
                    <svg viewBox="0 0 24 24" fill="currentColor" class="size-4" aria-hidden="true"><circle cx="9" cy="6" r="1.5" /><circle cx="15" cy="6" r="1.5" /><circle cx="9" cy="12" r="1.5" /><circle cx="15" cy="12" r="1.5" /><circle cx="9" cy="18" r="1.5" /><circle cx="15" cy="18" r="1.5" /></svg>
                </button>

                {{-- Label + optional meta. --}}
                <div class="min-w-0 flex-1">
                    <p class="truncate text-sm font-medium leading-snug" x-text="it.label"></p>
                    <p class="mt-0.5 truncate text-xs text-muted-foreground" x-show="it.meta" x-text="it.meta"></p>
                </div>
            </li>
        </template>
    </ul>

    {{-- Floating row that follows the pointer. --}}
    <template x-if="ghost && dragItem">
        <div
            data-slot="sortable-ghost"
            aria-hidden="true"
            class="pointer-events-none fixed z-overlay flex scale-[1.02] items-center gap-3 rounded-md border border-border bg-card p-3 text-card-foreground shadow-xl ring-1 ring-ring/40"
            x-bind:style="`left:${ghost.x}px; top:${ghost.y}px; width:${ghost.w}px; height:${ghost.h}px;`"
        >
            <span class="inline-flex shrink-0 text-muted-foreground"><svg viewBox="0 0 24 24" fill="currentColor" class="size-4" aria-hidden="true"><circle cx="9" cy="6" r="1.5" /><circle cx="15" cy="6" r="1.5" /><circle cx="9" cy="12" r="1.5" /><circle cx="15" cy="12" r="1.5" /><circle cx="9" cy="18" r="1.5" /><circle cx="15" cy="18" r="1.5" /></svg></span>
            <div class="min-w-0 flex-1">
                <p class="truncate text-sm font-medium leading-snug" x-text="dragItem.label"></p>
                <p class="mt-0.5 truncate text-xs text-muted-foreground" x-show="dragItem.meta" x-text="dragItem.meta"></p>
            </div>
        </div>
    </template>

    {{-- Mirror the current order to hidden inputs for normal form submission. --}}
    <template x-for="(it, i) in items" :key="'field-' + it.id">
        <input type="hidden" x-bind:name="hiddenName + '[]'" x-bind:value="it.id" />
    </template>

    {{-- Polite status region announces reorders to assistive tech. --}}
    <div class="sr-only" role="status" aria-live="polite" x-text="status"></div>
</div>

/**
 * Sortable list behavior — drag to reorder, the way the kanban board moves cards.
 *
 * Pointer: pointerdown on a row lifts it as a floating ghost under the pointer
 * and turns its list entry into a hollow placeholder. The placeholder moves
 * LIVE to the slot the drop would land in (the item is reordered in the data
 * as the pointer moves) and the other rows glide around it (FLIP: positions
 * measured before and after each move, the difference animated away). Release
 * settles the ghost onto the placeholder. Keyboard: the handle takes Arrow
 * Up/Down (Home/End to the ends); those moves glide too. The order is
 * mirrored to hidden `name[]` inputs, announced through the live region and
 * dispatched as `sortable:change` { order }. Reduced motion skips the glides.
 *
 * Self-registers on `alpine:init` so import order does not matter.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiSortable', (config = {}) => ({
        items: (config.items ?? []).map((it) => ({ ...it })),
        hiddenName: config.name ?? 'order',
        dragItem: null,
        dragIndex: null,
        ghost: null,
        status: '',
        root: null,
        _reduced: false,
        _origin: null,
        _move: null,
        _up: null,

        init() {
            this.root = this.$el;
            this._reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
            this._move = (e) => this.onMove(e);
            this._up = () => this.onUp();
        },

        isDragging(id) {
            return this.dragItem !== null && this.dragItem.id === id;
        },

        rows() {
            return [...this.root.querySelectorAll('[data-slot="sortable-item"]')];
        },

        // ---- Shared reorder primitive ---------------------------------------

        reorder(from, to) {
            const last = this.items.length - 1;
            const dest = Math.max(0, Math.min(to, last));
            if (from === dest) return undefined;
            const [moved] = this.items.splice(from, 1);
            this.items.splice(dest, 0, moved);
            return dest;
        },

        rowRects() {
            const rects = new Map();
            for (const el of this.rows()) rects.set(el.dataset.id, el.getBoundingClientRect());
            return rects;
        },

        glide(before) {
            if (this._reduced) return;
            this.$nextTick(() => {
                for (const el of this.rows()) {
                    const prev = before.get(el.dataset.id);
                    if (!prev || el.dataset.placeholder === 'true') continue;
                    const now = el.getBoundingClientRect();
                    const dy = prev.top - now.top;
                    if (!dy) continue;
                    el.getAnimations().forEach((a) => a.cancel());
                    el.animate([{ transform: `translateY(${dy}px)` }, { transform: 'none' }], { duration: 200, easing: 'cubic-bezier(0.22, 1, 0.36, 1)' });
                }
            });
        },

        announce(i) {
            const it = this.items[i];
            if (!it) return;
            this.status = `${it.label}, position ${i + 1} of ${this.items.length}`;
        },

        emit() {
            this.$dispatch('sortable:change', { order: this.items.map((it) => it.id) });
        },

        // ---- Keyboard reordering --------------------------------------------

        move(i, to) {
            const before = this.rowRects();
            const dest = this.reorder(i, to);
            if (dest === undefined) return;
            this.glide(before);
            this.announce(dest);
            this.emit();
            this.$nextTick(() => this.focusHandle(dest));
        },

        onKey(e, i) {
            const map = { ArrowUp: i - 1, ArrowDown: i + 1, Home: 0, End: this.items.length - 1 };
            if (!(e.key in map)) return;
            e.preventDefault();
            this.move(i, map[e.key]);
        },

        focusHandle(i) {
            this.root.querySelector(`[data-slot="sortable-handle"][data-index="${i}"]`)?.focus();
        },

        // ---- Pointer drag ---------------------------------------------------

        startDrag(e, i) {
            if (e.button !== undefined && e.button !== 0) return;
            // Links, fields and other buttons keep their own pointer behaviour.
            if (e.target.closest('a, input, textarea, select, button:not([data-slot="sortable-handle"])')) return;
            const el = e.currentTarget;
            const r = el.getBoundingClientRect();
            this.dragItem = this.items[i];
            this.dragIndex = i;
            this._origin = i;
            this.ghost = { w: r.width, h: r.height, dx: e.clientX - r.left, dy: e.clientY - r.top, x: r.left, y: r.top };
            window.addEventListener('pointermove', this._move);
            window.addEventListener('pointerup', this._up);
            window.addEventListener('pointercancel', this._up);
            e.preventDefault();
        },

        onMove(e) {
            if (!this.dragItem) return;
            this.ghost.x = e.clientX - this.ghost.dx;
            this.ghost.y = e.clientY - this.ghost.dy;
            // The slot is decided by row midpoints; the placeholder itself is skipped.
            let target = this.items.length - 1;
            for (const row of this.rows()) {
                if (row.dataset.placeholder === 'true') continue;
                const r = row.getBoundingClientRect();
                if (e.clientY < r.top + r.height / 2) {
                    const idx = Number(row.dataset.index);
                    target = idx > this.dragIndex ? idx - 1 : idx;
                    break;
                }
            }
            if (target !== this.dragIndex) {
                const before = this.rowRects();
                const dest = this.reorder(this.dragIndex, target);
                if (dest !== undefined) {
                    this.dragIndex = dest;
                    this.glide(before);
                }
            }
        },

        onUp() {
            if (!this.dragItem) return;
            window.removeEventListener('pointermove', this._move);
            window.removeEventListener('pointerup', this._up);
            window.removeEventListener('pointercancel', this._up);
            const placeholder = this.root.querySelector(`[data-slot="sortable-item"][data-id="${this.dragItem.id}"]`);
            const ghostEl = this.root.querySelector('[data-slot="sortable-ghost"]');
            const index = this.dragIndex;
            const moved = index !== this._origin;
            const finish = () => {
                this.dragItem = null;
                this.dragIndex = null;
                this.ghost = null;
                if (moved) {
                    this.announce(index);
                    this.emit();
                }
            };
            if (ghostEl && placeholder && !this._reduced) {
                const to = placeholder.getBoundingClientRect();
                const anim = ghostEl.animate(
                    [{ left: `${this.ghost.x}px`, top: `${this.ghost.y}px`, transform: 'scale(1.02)' }, { left: `${to.left}px`, top: `${to.top}px`, transform: 'none' }],
                    { duration: 180, easing: 'cubic-bezier(0.22, 1, 0.36, 1)', fill: 'forwards' },
                );
                anim.onfinish = finish;
                anim.oncancel = finish;
            } else {
                finish();
            }
        },

        destroy() {
            window.removeEventListener('pointermove', this._move);
            window.removeEventListener('pointerup', this._up);
            window.removeEventListener('pointercancel', this._up);
        },
    }));
});