Split View

# Brok UI: Split View (`split-view`)

The list + detail layout of a triage (inbox) screen: list and detail panes side by side with a resizable divider, one pane at a time with a Back button in a narrow container, and focus returned to the row that opened the detail.

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

## Install

```bash
php artisan ui:add split-view
```

## Usage

```blade
{{-- Give the root a height. Each row is a real link with data-split-view-open:
     with JavaScript it opens the detail pane (and, in a narrow container, slides
     it in with a Back button); without it the link still navigates. --}}
@php
    $messages = [
        ['id' => 1, 'from' => 'Ada Lovelace', 'subject' => __('Quarterly report draft'), 'preview' => __('The figures for the third quarter are in. Can you check the totals?'), 'time' => __('09:12')],
        ['id' => 2, 'from' => 'Grace Hopper', 'subject' => __('Deploy window moved'), 'preview' => __('We moved the release to Thursday afternoon.'), 'time' => __('08:40')],
        ['id' => 3, 'from' => 'Alan Turing', 'subject' => __('Invoice 2041 paid'), 'preview' => __('Payment arrived this morning. No action needed.'), 'time' => __('Yesterday')],
    ];
@endphp
<div x-data="{ selected: null }" class="w-full">
    <x-ui.split-view class="h-96 w-full overflow-hidden rounded-lg border border-border" persist="split-view-demo">
        <x-slot:header class="flex items-center justify-between gap-2 px-4 py-2">
            <h2 class="text-sm font-semibold">{{ __('Inbox') }}</h2>
            <span class="text-sm text-muted-foreground">{{ __('3 messages') }}</span>
        </x-slot:header>

        <x-slot:list>
            <ul role="list" class="divide-y divide-border">
                @foreach ($messages as $message)
                    <li>
                        <a
                            href="#message-{{ $message['id'] }}"
                            data-split-view-open
                            x-on:click.prevent="selected = {{ $message['id'] }}"
                            :aria-current="selected === {{ $message['id'] }} ? 'true' : null"
                            class="flex min-h-11 min-w-0 flex-col gap-1 px-4 py-2 outline-none hover:bg-muted focus-visible:bg-muted focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring aria-[current=true]:bg-muted"
                        >
                            <span class="flex min-w-0 items-baseline justify-between gap-2">
                                <span class="truncate text-sm font-medium">{{ $message['from'] }}</span>
                                <span class="shrink-0 text-xs text-muted-foreground">{{ $message['time'] }}</span>
                            </span>
                            <span class="truncate text-sm">{{ $message['subject'] }}</span>
                            <span class="truncate text-xs text-muted-foreground">{{ $message['preview'] }}</span>
                        </a>
                    </li>
                @endforeach
            </ul>
        </x-slot:list>

        <x-slot:detail>
            @foreach ($messages as $message)
                <article id="message-{{ $message['id'] }}" x-show="selected === {{ $message['id'] }}" class="flex flex-col gap-2 p-6">
                    <h3 class="text-sm font-semibold">{{ $message['subject'] }}</h3>
                    <p class="text-xs text-muted-foreground">{{ __('From :name at :time', ['name' => $message['from'], 'time' => $message['time']]) }}</p>
                    <p class="text-sm">{{ $message['preview'] }}</p>
                </article>
            @endforeach
        </x-slot:detail>
    </x-ui.split-view>
</div>
```

## Props

- `detailOpen` (bool, default `false`) — Server-rendered open state. In a narrow container it shows the detail pane instead of the list; side by side (detailMode toggle) it shows the detail slot instead of the empty state. x-model or wire:model on the root binds the same state (x-modelable onto the namespaced splitViewOpen, so the bound name, such as detailOpen, stays the consumer's own variable).
- `detailMode` (toggle|on-demand, default `toggle`) — toggle: the open state shows or hides the detail in both layouts. on-demand: side by side the detail slot always shows (the empty state only when the slot is empty), so the selected record stays visible; stacked, the list and header show first and the detail pane appears only once a row, the model or an event opens it. An unknown value falls back to toggle.
- `listSize` (float, default `36`) — The list pane's initial share of the width in percent, clamped to minListSize and maxListSize.
- `minListSize` (float, default `24`) — The narrowest the list pane can be resized to, in percent.
- `maxListSize` (float, default `56`) — The widest the list pane can be resized to, in percent.
- `persist` (string|null, default `null`) — localStorage key that remembers the resized list width (passed to resizable); null keeps it for the page only.
- `backLabel` (string|null, default `null`) — Visible text and accessible name of the Back button shown in a narrow container; null uses "Back".
- `listLabel` (string|null, default `null`) — Accessible name of the list region; null uses "List".
- `detailLabel` (string|null, default `null`) — Accessible name of the detail region; null uses "Detail".
- `resizeLabel` (string|null, default `null`) — Accessible name of the divider; null uses "Resize list".
- `emptyText` (string|null, default `null`) — Text in the detail pane while nothing is open; null uses "Select an item to see its details." The empty slot replaces it.

## Use when

- Use for secondary or optional content, especially when users usually inspect one short section at a time.
- Building a triage screen (inbox, queue, review list) where picking a row shows its detail beside the list.
- Needing the list/detail pair to collapse to one pane with a Back control on narrow screens and inside narrow app shells.

## Avoid when

- Do not hide required workflow content or comparison-heavy information because disclosure controls reduce visibility and increase interaction cost.
- The two panels are peers with no list/detail relationship (code and preview, editor and inspector); use resizable.
- The detail should cover the page as an overlay without leaving the list context; use sheet or drawer.
- The page shows one record with no list beside it; use a detail page layout.

## Anti-patterns

- Hiding required workflow content
- Using accordions for cross-section comparison

## Rules

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

@props([
    // Server-rendered open state; x-model / wire:model on the root take over after boot.
    'detailOpen' => false,
    // toggle: the open state shows or hides the detail in both layouts.
    // on-demand: side by side the detail slot always shows (the empty state
    // only when the slot is empty); stacked, the list and header show first
    // and the detail pane appears only once it is opened.
    'detailMode' => 'toggle',
    // List pane share of the width in percent, and its resize limits.
    'listSize' => 36,
    'minListSize' => 24,
    'maxListSize' => 56,
    // localStorage key that remembers the resized list width; null keeps it for the page only.
    'persist' => null,
    'backLabel' => null,
    'listLabel' => null,
    'detailLabel' => null,
    'resizeLabel' => null,
    // Text shown in the detail pane while nothing is open (the `empty` slot overrides it).
    'emptyText' => null,
])

@php
    $minListSize = max(10, min(90, (float) $minListSize));
    $maxListSize = max($minListSize, min(90, (float) $maxListSize));
    $listSize = max($minListSize, min($maxListSize, (float) $listSize));
    $detailSize = 100 - $listSize;
    $detailMode = $detailMode === 'on-demand' ? 'on-demand' : 'toggle';
    // A stable default id: the pane ids derive from it, and an id that
    // changed on every render made Livewire morph the panes as new elements.
    // It comes from the persist key, else from the labels, mode and size. A
    // second split view with the same base in one request gets -2, -3, so
    // two default split views on one page never share ids.
    $rootId = $attributes->get('id');
    if (blank($rootId)) {
        $rootId = 'split-view-'.substr(md5(filled($persist)
            ? 'persist|'.$persist
            : implode('|', [(string) $listLabel, (string) $detailLabel, (string) $backLabel, $detailMode, (string) $listSize])), 0, 8);
        $splitViewIds = request()->attributes->get('brok.split-view.ids', []);
        $splitViewIds[$rootId] = ($splitViewIds[$rootId] ?? 0) + 1;
        request()->attributes->set('brok.split-view.ids', $splitViewIds);
        if ($splitViewIds[$rootId] > 1) {
            $rootId .= '-'.$splitViewIds[$rootId];
        }
    }
    $hasDetail = isset($detail) && $detail->isNotEmpty();
    $hasEmpty = isset($empty) && $empty->isNotEmpty();
    $onDemand = $detailMode === 'on-demand';
    // on-demand, side by side (a 48rem split-view container): the detail slot
    // shows whatever the open state is. The important modifier outranks the
    // open/closed rules in ui.css.
    $wideContentClass = $onDemand ? ' @3xl/split-view:!block' : '';
    $wideEmptyClass = $onDemand ? ($hasDetail ? ' @3xl/split-view:!hidden' : ' @3xl/split-view:!flex') : '';
@endphp

{{--
    Split View — the list + detail layout of a triage (inbox) screen. Side by
    side, the list and detail panes share a resizable divider (composes
    `resizable`). In a narrow container only one pane shows: opening an item
    slides the detail in with a Back button; Back and Escape return to the list
    and put focus back on the row that opened it. Any element in the list with
    `data-split-view-open` opens the detail when clicked; a link keeps its href,
    so the list still navigates without JavaScript. Give the root a height.

    The component's own Alpine state is namespaced (`splitViewOpen`,
    `splitViewStacked`), so a consumer variable such as `detailOpen` in an
    outer x-data is not shadowed inside the slots. Bind the open state with
    x-model / wire:model on the root, or listen for split-view-open and
    split-view-close.
--}}
<div
    x-data="uiSplitView({ open: @js((bool) $detailOpen) })"
    x-modelable="splitViewOpen"
    data-slot="split-view"
    data-state="{{ $detailOpen ? 'open' : 'closed' }}"
    @if ($onDemand) data-detail-mode="on-demand" @endif
    :data-state="splitViewOpen ? 'open' : 'closed'"
    :data-stacked="splitViewStacked ? 'true' : 'false'"
    {{ $attributes->merge(['id' => $rootId, 'class' => 'flex min-h-0 min-w-0 flex-col bg-background text-foreground']) }}
>
    @isset($header)
        <div
            data-slot="split-view-header"
            @if ($onDemand) x-show="!(splitViewStacked && splitViewOpen)" @endif
            {{ $header->attributes->merge(['class' => 'min-w-0 shrink-0 border-b border-border']) }}
        >
            {{ $header }}
        </div>
    @endisset

    <x-ui.resizable :persist="$persist" class="min-h-0 flex-1">
        <x-ui.resizable.panel
            data-split-view-pane="list"
            :default-size="$listSize"
            :min-size="$minListSize"
            :max-size="$maxListSize"
            style="width: {{ $listSize }}%"
        >
            <section
                id="{{ $rootId }}-list"
                data-slot="split-view-list"
                tabindex="-1"
                aria-label="{{ filled($listLabel) ? $listLabel : __('List') }}"
                class="min-h-full min-w-0 break-words outline-none"
            >
                {{ $list ?? '' }}
            </section>
        </x-ui.resizable.panel>

        <x-ui.resizable.handle
            :label="filled($resizeLabel) ? $resizeLabel : __('Resize list')"
            aria-controls="{{ $rootId }}-list"
        />

        <x-ui.resizable.panel
            data-split-view-pane="detail"
            :default-size="$detailSize"
            :min-size="100 - $maxListSize"
            :max-size="100 - $minListSize"
            style="width: {{ $detailSize }}%"
        >
            <section
                id="{{ $rootId }}-detail"
                data-slot="split-view-detail"
                tabindex="-1"
                aria-label="{{ filled($detailLabel) ? $detailLabel : __('Detail') }}"
                x-on:keydown.escape="splitViewEscape($event)"
                class="min-h-full min-w-0 break-words bg-background outline-none"
            >
                <div data-slot="split-view-back" class="sticky top-0 z-10 border-b border-border bg-background px-2 py-1">
                    <x-ui.button variant="ghost" x-on:click="close()">
                        <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="size-4 shrink-0 rtl:-scale-x-100"><path d="m15 18-6-6 6-6" /></svg>
                        <span class="truncate">{{ filled($backLabel) ? $backLabel : __('Back') }}</span>
                    </x-ui.button>
                </div>

                @if ($hasDetail)
                    <div data-slot="split-view-detail-content" {{ $detail->attributes->merge(['class' => 'min-w-0'.$wideContentClass]) }}>
                        {{ $detail }}
                    </div>
                @endif

                <div data-slot="split-view-empty" class="flex min-h-full items-center justify-center p-6 text-center text-sm text-muted-foreground{{ $wideEmptyClass }}">
                    @if ($hasEmpty)
                        {{ $empty }}
                    @else
                        <p>{{ filled($emptyText) ? $emptyText : __('Select an item to see its details.') }}</p>
                    @endif
                </div>
            </section>
        </x-ui.resizable.panel>
    </x-ui.resizable>
</div>

/**
 * Split View behaviour — the list + detail layout of a triage screen.
 *
 * `splitViewOpen` is the single open state (x-modelable, so x-model and
 * wire:model on the root drive it). The state is namespaced so it never
 * shadows a consumer variable of the same plain name inside the slots.
 * The layout itself is CSS: a container query on the root stacks the panes
 * below 48rem and sets `--split-view-stacked: 1` on the resizable group,
 * which this component reads to know which mode it is in.
 * The divider is the composed `resizable` primitive; nothing here drags.
 *
 * Opening records the element that opened it (a clicked `[data-split-view-open]`
 * row, or the focused list element). When stacked, opening moves focus to the
 * detail region, and every close path (Back, Escape, close(), the model, the
 * `close-split-view` event) returns focus to that opener. Side by side, focus
 * returns only when it was inside the detail pane.
 *
 * Events: dispatches `split-view-open` / `split-view-close` (bubbling, detail
 * `{ id }`) and listens on window for `open-split-view` / `close-split-view`
 * (optional `detail.id` targets one instance by its root id).
 *
 * Self-registers on `alpine:init` so import order does not matter.
 */
document.addEventListener('alpine:init', () => {
    // Where Escape belongs to a nested control rather than to the split view.
    const OWNS_ESCAPE = [
        'textarea',
        'select',
        'input:not([type=checkbox]):not([type=radio]):not([type=button]):not([type=submit]):not([type=reset])',
        '[contenteditable]:not([contenteditable=false])',
        '[role=menu]',
        '[role=menubar]',
        '[role=listbox]',
        '[role=combobox]',
        '[role=dialog]',
        '[role=alertdialog]',
        '[aria-modal=true]',
        'dialog',
        '[aria-expanded=true]',
    ].join(',');

    window.Alpine.data('uiSplitView', (config = {}) => {
        // Only the namespaced state, open(), close() and splitViewEscape()
        // live on the Alpine scope: everything in it is visible to the list
        // and detail slots, so any other name could shadow a consumer's own
        // variable (a `detailOpen` in an outer x-data). Helpers and bookkeeping
        // stay in this closure. Methods also run from nested scopes (the
        // resizable panels), where `this.$el` is the nearest nested element,
        // so the root and the reactive scope are kept here too.
        let root = null;
        let scope = null;
        let opener = null;
        let observer = null;
        let onClick = null;
        let onOpenEvent = null;
        let onCloseEvent = null;

        const targets = (event) => {
            const id = event.detail?.id;
            return !id || id === root.id;
        };

        const pane = (name) => root.querySelector(`#${CSS.escape(root.id)}-${name}`);

        const measure = () => {
            const group = root.querySelector(':scope > [data-slot="resizable"]');
            scope.splitViewStacked = Boolean(group) && getComputedStyle(group).getPropertyValue('--split-view-stacked').trim() === '1';
        };

        /** The opener, else the list's current row, else the list region. */
        const returnFocus = () => {
            const list = pane('list');
            const current = list?.querySelector('[data-split-view-open][aria-current]:not([aria-current=false])');
            const target = [opener, current, list].find((el) => el?.isConnected && el.getClientRects().length);
            target?.focus();
        };

        const changed = (open) => {
            root.dispatchEvent(new CustomEvent(open ? 'split-view-open' : 'split-view-close', { bubbles: true, detail: { id: root.id } }));
            const detail = pane('detail');
            if (open) {
                if (scope.splitViewStacked) window.Alpine.nextTick(() => detail?.focus({ preventScroll: true }));
                return;
            }
            const focusWasInDetail = detail?.contains(document.activeElement);
            if (!scope.splitViewStacked && !focusWasInDetail) return;
            window.Alpine.nextTick(returnFocus);
        };

        return {
            splitViewOpen: Boolean(config.open),
            splitViewStacked: false,

            init() {
                root = this.$el;
                scope = this;
                measure();
                if (typeof ResizeObserver === 'function') {
                    observer = new ResizeObserver(measure);
                    observer.observe(root);
                }

                onClick = (event) => {
                    const trigger = event.target.closest?.('[data-split-view-open]');
                    if (trigger && trigger.closest('[data-slot="split-view"]') === root) scope.open(trigger);
                };
                root.addEventListener('click', onClick);

                onOpenEvent = (event) => {
                    if (targets(event)) scope.open();
                };
                onCloseEvent = (event) => {
                    if (targets(event)) scope.close();
                };
                window.addEventListener('open-split-view', onOpenEvent);
                window.addEventListener('close-split-view', onCloseEvent);

                this.$watch('splitViewOpen', (open) => changed(Boolean(open)));
            },

            destroy() {
                observer?.disconnect();
                root?.removeEventListener('click', onClick);
                window.removeEventListener('open-split-view', onOpenEvent);
                window.removeEventListener('close-split-view', onCloseEvent);
            },

            /** Open the detail pane. `trigger` gets focus back on close. */
            open(trigger = null) {
                const list = pane('list');
                const active = document.activeElement;
                opener = trigger ?? (list?.contains(active) && active !== list ? active : opener);
                scope.splitViewOpen = true;
            },

            close() {
                scope.splitViewOpen = false;
            },

            /** Escape on the stacked detail pane returns to the list. */
            splitViewEscape(event) {
                if (!scope.splitViewStacked || !scope.splitViewOpen || event.defaultPrevented) return;
                if (event.target.closest(OWNS_ESCAPE)) return;
                event.preventDefault();
                scope.close();
            },
        };
    });
});