Modal Surfaces

# Brok UI: Drawer (`drawer`)

Bottom sheet with a drag handle and drag-to-dismiss, built on the dialog focus-trap base. Teleported overlay, Escape-to-close, focus restoration and background inertness.

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

## Install

```bash
php artisan ui:add drawer
```

## Usage

```blade
<x-ui.drawer>
    <x-ui.drawer.trigger class="inline-flex h-10 items-center justify-center rounded-md bg-primary px-4 text-sm font-medium text-primary-foreground transition-colors hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background">
        {{ __('Open drawer') }}
    </x-ui.drawer.trigger>

    <x-ui.drawer.content>
        <x-ui.drawer.handle />
        <x-ui.drawer.header>
            <x-ui.drawer.title>{{ __('Move goal') }}</x-ui.drawer.title>
            <x-ui.drawer.description>{{ __('Set your daily activity goal. Drag the handle down to dismiss.') }}</x-ui.drawer.description>
        </x-ui.drawer.header>

        <div class="mt-4 space-y-2">
            <x-ui.label for="goal">{{ __('Daily goal') }}</x-ui.label>
            <x-ui.input id="goal" value="350 cal" />
        </div>

        <x-ui.drawer.footer>
            <button type="button" @click="hide()" class="inline-flex h-10 items-center justify-center rounded-md border border-border bg-background px-4 text-sm font-medium text-foreground transition-colors hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background">
                {{ __('Close') }}
            </button>
        </x-ui.drawer.footer>
    </x-ui.drawer.content>
</x-ui.drawer>
```

## Props

- `sticky` (bool, default `false`) — Declared by @props in the registry Blade source.

## Use when

- Use for short, self-contained work that benefits from preserving page context, or for interruptions that truly deserve focused attention.
- A mobile-first action or detail surface should enter from the bottom.
- Drag-to-dismiss is a useful, discoverable complement to explicit close controls.

## Avoid when

- Do not use for long forms, multi-step tasks, or broad comparison work that needs more room and less interruption.
- Use for side tasks, inspectors, or secondary controls that should coexist with the main canvas; avoid making it the primary flow.
- Desktop edge-aligned navigation or inspection is the primary use case; use sheet.
- The content is a small contextual disclosure; use popover.

## Anti-patterns

- Long forms in dialogs
- Multi-step or comparison-heavy modal workflows

## Rules

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

<template x-teleport="body">
    <div
        data-slot="drawer-portal"
        x-ref="portal"
        x-show="open"
        x-cloak
        class="fixed inset-0 z-modal"
        {{-- Defers to any surface that already handled the key (a nested menu
             calling preventDefault() on its own Escape) and to a nested layer
             that claims the first Escape via pushEscapeLayer() before this
             closes the panel itself. --}}
        @keydown.escape.window="open && !$event.defaultPrevented && escape()"
    >
        {{-- Announces an in-place subject change (see announceSubjectChange())
             without re-announcing on ordinary open, which the dialog role
             already covers. --}}
        <p data-slot="drawer-live-region" aria-live="polite" class="sr-only" x-text="subjectAnnouncement"></p>

        {{-- Overlay --}}
        <div
            data-slot="drawer-overlay"
            x-show="open"
            x-transition:enter="motion-safe:transition-opacity motion-safe:duration-150"
            x-transition:enter-start="opacity-0"
            x-transition:enter-end="opacity-100"
            x-transition:leave="motion-safe:transition-opacity motion-safe:duration-150"
            x-transition:leave-start="opacity-100"
            x-transition:leave-end="opacity-0"
            class="absolute inset-0 bg-scrim/50"
            @click="hide()"
        ></div>

        {{-- Panel --}}
        <div
            data-slot="drawer-content"
            x-ref="panel"
            role="dialog"
            aria-modal="true"
            tabindex="-1"
            x-bind:aria-labelledby="hasTitle ? $id('drawer-title') : null"
            x-bind:aria-describedby="hasDescription ? $id('drawer-description') : null"
            x-show="open"
            @keydown.tab.prevent="trap($event)"
            {{-- Inline transform only while the gesture owns the panel: `transition: none`
                 keeps it glued to the finger mid-drag, and dropping the style entirely at
                 rest lets the class-based enter/leave transitions run uncontested.
                 The resting transition lists only `transform` (the drag snap-back):
                 `transition-transform` also covers `translate`, so removing the
                 enter-end `translate-y-0` class started a second transition after
                 the open had finished. --}}
            :style="dragging ? `transform: translateY(${offset}px); transition: none` : (offset !== 0 ? `transform: translateY(${offset}px)` : null)"
            x-transition:enter="motion-safe:transition-transform motion-safe:duration-200"
            x-transition:enter-start="translate-y-full"
            x-transition:enter-end="translate-y-0"
            x-transition:leave="motion-safe:transition-transform motion-safe:duration-200"
            x-transition:leave-start="translate-y-0"
            x-transition:leave-end="translate-y-full"
            {{ $attributes->merge(['class' => 'fixed inset-x-0 bottom-0 z-10 mt-24 flex min-w-0 max-h-[90vh] flex-col overflow-y-auto rounded-t-lg border-t border-border bg-card p-dialog text-card-foreground shadow-lg motion-safe:transition-[transform] motion-reduce:transition-none']) }}
        >
            {{ $slot }}
        </div>
    </div>
</template>

// The dialog registry dependency installs this module beside this file.
import {
    announceOverlaySubjectChange,
    focusOverlayInitial,
    lockOverlayInert,
    lockOverlayScroll,
    overlayFocusables,
    popOverlayEscapeLayer,
    pushOverlayEscapeLayer,
    resolveOverlayEscape,
    trapOverlayFocus,
    unlockOverlayInert,
    unlockOverlayScroll,
} from './overlay-lifecycle.js';

/**
 * Drawer behavior (dialog base + drag-to-dismiss).
 *
 * Built on the dialog focus-trap (spec §17: focus trap, Escape, focus return).
 * On open we remember the element that had focus, move focus into the panel,
 * and lock body scroll. Tab is trapped inside the panel. On close we restore
 * focus to the trigger. Escape and overlay click both close.
 *
 * Drag-to-dismiss: pointer drag on the handle tracks vertical offset; releasing
 * past the threshold dismisses the drawer, otherwise it animates back to rest.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiDrawer', () => ({
        open: false,
        previouslyFocused: null,
        offset: 0,
        dragging: false,
        // Set by <x-ui.drawer.title>/<x-ui.drawer.description> when present, so
        // the panel only advertises aria-labelledby/aria-describedby when the
        // referenced node actually exists (no dangling idref / nameless dialog).
        hasTitle: false,
        hasDescription: false,
        scrollLocked: false,
        inertLocked: false,
        inertPortal: null,
        escapeLayers: [],
        // Polite live region text — see announceSubjectChange().
        subjectAnnouncement: '',

        // Bound drag listener refs so we can remove exactly what we added.
        _onMove: null,
        _onUp: null,
        _dismissTimer: null,
        _focusRestoreTimer: null,

        // Body-scroll lock is reference-counted across stacked overlays so a
        // nested close (or an unmount while open) never clears the lock while
        // another overlay still needs it. The counter is a single shared global
        // key that every overlay item duplicates (copy-into-app model).
        lockScroll() {
            lockOverlayScroll(this);
        },

        unlockScroll() {
            unlockOverlayScroll(this);
        },

        lockInert() {
            lockOverlayInert(this, this.$refs.portal);
        },

        unlockInert() {
            unlockOverlayInert(this);
        },

        /** A nested layer (an inline form, a stepper) claims Escape while active. */
        pushEscapeLayer(close) {
            pushOverlayEscapeLayer(this, close);
        },

        popEscapeLayer(close) {
            popOverlayEscapeLayer(this, close);
        },

        /** Announce an in-place subject change without re-announcing on open. */
        announceSubjectChange(message) {
            announceOverlaySubjectChange(this, message);
        },

        /** Escape unwinds one layer at a time before it closes the panel. */
        escape() {
            if (!this.open) return;
            if (resolveOverlayEscape(this)) return;
            this.hide();
        },

        destroy() {
            // Remove any drag listeners still attached if unmounted mid-drag.
            window.removeEventListener('pointermove', this._onMove);
            window.removeEventListener('pointerup', this._onUp);
            window.clearTimeout(this._dismissTimer);
            window.clearTimeout(this._focusRestoreTimer);
            // Release the locks if unmounted while still open.
            if (this.open) {
                this.unlockScroll();
                this.unlockInert();
            }
        },

        show() {
            window.clearTimeout(this._focusRestoreTimer);
            // A WebKit click does not focus the button, so activeElement is
            // then a focusable ancestor of the trigger (a tab panel, a card).
            // Return focus to the trigger itself in that case.
            const active = document.activeElement;
            const trigger = this.$refs.trigger;
            this.previouslyFocused =
                trigger && active instanceof HTMLElement && active !== trigger && active.contains(trigger)
                    ? trigger
                    : active;
            this.offset = 0;
            this.open = true;
            this.lockScroll();
            this.lockInert();
            this.$nextTick(() => this.focusInitial());
        },

        hide() {
            if (!this.open) {
                return;
            }
            this.open = false;
            this.unlockScroll();
            this.unlockInert();
            const previous = this.previouslyFocused;
            const target =
                previous instanceof HTMLElement &&
                previous !== document.body &&
                previous !== document.documentElement
                    ? previous
                    : this.$refs.trigger;
            if (target) {
                this.$nextTick(() => {
                    target.focus({ preventScroll: true });

                    // WebKit can move focus back to the leaving panel while it
                    // finishes the exit transition. Restore it again after the
                    // 200 ms transition so every browser has the same result.
                    this._focusRestoreTimer = window.setTimeout(() => {
                        if (!this.open && target.isConnected) {
                            target.focus({ preventScroll: true });
                        }
                    }, 250);
                });
            }
        },

        focusables() {
            return overlayFocusables(this.$refs.panel);
        },

        focusInitial() {
            focusOverlayInitial(this.$refs.panel);
        },

        /** Tab is always prevented in markup; we move focus manually. */
        trap(event) {
            trapOverlayFocus(this.$refs.panel, event);
        },

        /** Begin a drag-to-dismiss gesture from the handle. */
        startDrag(event) {
            const startY = event.clientY;
            let lastY = startY;
            let lastTime = performance.now();
            let velocity = 0;

            this.dragging = true;

            // Bind once so the same refs can be removed later (here or in destroy()).
            this._onMove = (ev) => {
                const now = performance.now();
                velocity = (ev.clientY - lastY) / Math.max(now - lastTime, 1);
                lastY = ev.clientY;
                lastTime = now;

                const delta = ev.clientY - startY;
                // Upward drag rubber-bands with resistance instead of hard-stopping.
                this.offset = delta >= 0 ? delta : delta / 3;
            };

            this._onUp = () => {
                window.removeEventListener('pointermove', this._onMove);
                window.removeEventListener('pointerup', this._onUp);
                this.dragging = false;
                // Dismiss past the distance threshold or on a downward flick (px/ms).
                if (this.offset > 120 || (velocity > 0.11 && this.offset > 0)) {
                    this.dismissFromDrag();
                } else {
                    this.offset = 0;
                }
            };

            window.addEventListener('pointermove', this._onMove);
            window.addEventListener('pointerup', this._onUp);
        },

        /** Slide out from the release point instead of snapping back before closing. */
        dismissFromDrag() {
            const panel = this.$refs.panel;
            this.offset = panel ? panel.offsetHeight : this.offset;
            this._dismissTimer = window.setTimeout(() => {
                this.hide();
                this.offset = 0;
            }, 200);
        },
    }));
});