Tabs

# Brok UI: Tabs (`tabs`)

Accessible tabbed interface (wire:model/x-model bind the active value through x-modelable) with roving tabindex, arrow-key navigation, touch swipe between panels, orientation, line/pills/boxed variants and full-width and disabled-tab support, with opt-in URL sync (`param`) so a tab is shareable as a link.

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

## Install

```bash
php artisan ui:add tabs
```

## Usage

```blade
<x-ui.tabs default="account" class="w-full max-w-md">
    <x-ui.tabs.list>
        <x-ui.tabs.trigger value="account">{{ __('Account') }}</x-ui.tabs.trigger>
        <x-ui.tabs.trigger value="password">{{ __('Password') }}</x-ui.tabs.trigger>
    </x-ui.tabs.list>
    <x-ui.tabs.content value="account">
        <p class="text-muted-foreground">{{ __('Make changes to your account here. Use the arrow keys to move between tabs.') }}</p>
    </x-ui.tabs.content>
    <x-ui.tabs.content value="password">
        <p class="text-muted-foreground">{{ __('Change your password here. Focus follows the selected tab automatically.') }}</p>
    </x-ui.tabs.content>
</x-ui.tabs>
```

## Props

- `default` (mixed|null, default `null`) — Value of the tab active on mount, before any URL param or bound model overrides it.
- `orientation` (string, default `horizontal`) — Layout and arrow-key axis: horizontal or vertical.
- `variant` (pills|line|boxed, default `pills`) — Visual style of the tab list: line, pills, or boxed.
- `marker` (string, default `default`) — Active-tab indicator style: default (a raised surface or foreground line) or filled (the marker takes the primary fill and the active trigger inverts onto it).
- `fullWidth` (bool, default `false`) — Stretches triggers to fill the available width instead of sizing to content.
- `param` (mixed|null, default `null`) — Opt-in URL sync: the query key that names the active tab. The URL wins over default on load, and selections are written back with replaceState so a tab is shareable as a link.
- `disabled` (false|true, default `false`) — Documented catalog control used by the preview workbench.
- `value` (mixed, default `required`) — Declared by @props in the registry Blade source.

## Use when

- Use for a few peer sections with relatively long content and likely back-and-forth switching.
- Switching between several panels of content that share the same context and screen space.
- Needing the active tab to bind with wire:model or x-model, or to sync into the URL for a shareable link.

## Avoid when

- Do not use for many short sections where accordions or a list would fit better.
- Best for a few longer peer sections when users are likely to switch between them.
- The panels are steps in a sequence the user progresses through in order; use a stepper instead.
- The choice should navigate to a distinct page rather than swap content in place; use plain links or navigation-menu.

## Anti-patterns

- Using tabs for sequential progress
- Creating too many tabs to scan

## Rules

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

@props([
    'default' => null,
    'orientation' => 'horizontal',
    'variant' => 'pills',
    // default: the marker is a raised surface (pills/boxed) or a foreground
    // line. filled: the marker takes the primary fill and the active trigger
    // inverts onto it — the former animated-tabs look.
    'marker' => 'default',
    'fullWidth' => false,
    // Opt-in URL sync: the query key that names the active tab (`?tab=…`).
    // The URL wins over `default` on load; selections are written back with
    // replaceState so a record tab is shareable as a link.
    'param' => null,
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $marker = $marker === 'filled' ? 'filled' : 'default';
    // animated-tabs renders this component under its own name; the browser
    // keeps only the first of two identical attributes, so read the override
    // out of the bag and print exactly one.
    $slotName = (string) ($attributes->get('data-slot') ?: 'tabs');
@endphp

{{--
    Tabs (spec §17 keyboard + §19 behavior layer).
    Active tab lives on the root. Triggers use roving tabindex with arrow-key
    navigation; panels are shown/hidden by value.

    Visual options (behaviour unchanged — keyboard/aria identical across them):
      - variant:     pills (default, segmented track) | line (underline bar) | boxed (enclosed tab strip)
      - marker:      default (raised surface / foreground line) | filled (primary fill, inverted active label)
      - orientation: horizontal (default) | vertical  (arrow keys follow axis, RTL-aware)
      - fullWidth:   stretch triggers to share the row equally (horizontal only)
      - param:       query key to read/write the active tab from/to the URL (deep-linkable tabs)

    Children read variant/orientation/fullWidth through @aware so the list and
    triggers style themselves consistently without prop drilling.
--}}
<div
    x-data="uiTabs({ default: @js($default), orientation: @js($orientation), param: @js($param) })"
    x-modelable="active"
    x-id="['tabs-trigger', 'tabs-panel']"
    data-slot="{{ $slotName }}"
    data-variant="{{ $variant }}"
    data-marker="{{ $marker }}"
    :data-orientation="orientation"
    {{ $attributes->except('data-slot')->merge(['class' => 'flex flex-col gap-4 data-[orientation=vertical]:flex-row']) }}
>
    {{ $slot }}
</div>

@aware([
    'variant' => 'pills',
    'marker' => 'default',
    'fullWidth' => false,
    'orientation' => 'horizontal',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $recipe = $styles['tabs'] ?? [];

    $listMap = $recipe['list'] ?? [];
    $listClass = ($recipe['listBase'] ?? '').' '.($listMap[$variant] ?? $listMap['pills'] ?? '');

    // fullWidth stretches each trigger to share the row; only meaningful on the
    // horizontal axis (vertical lists already stretch via data-orientation).
    $fullWidthClass = $fullWidth ? ($recipe['listFull'] ?? '') : '';

    // Sliding active marker; the vertical line variant swaps to a block-axis
    // bar, and marker="filled" swaps the surface for the primary fill.
    $filled = $marker === 'filled';
    $markerMap = ($orientation === 'vertical' ? ($recipe[$filled ? 'markerFilledVertical' : 'markerVertical'] ?? []) : [])
        + ($recipe[$filled ? 'markerFilled' : 'marker'] ?? []);
    $markerClass = $markerMap[$variant] ?? $markerMap['pills'] ?? '';
@endphp

<div
    data-slot="tabs-list"
    data-variant="{{ $variant }}"
    role="tablist"
    :aria-orientation="orientation"
    @keydown="onKey($event)"
    :data-orientation="orientation"
    {{ $attributes->merge(['class' => trim($listClass).' '.$fullWidthClass]) }}
>
    <span
        x-ref="marker"
        data-slot="tabs-marker"
        data-variant="{{ $variant }}"
        aria-hidden="true"
        class="{{ $markerClass }}"
    ></span>

    {{ $slot }}
</div>

@aware([
    'variant' => 'pills',
    'marker' => 'default',
    'fullWidth' => false,
])

@props([
    'value',
    'disabled' => false,
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $recipe = $styles['tabs'] ?? [];

    $triggerMap = $recipe['trigger'] ?? [];
    $triggerClass = ($recipe['triggerBase'] ?? '').' '.($triggerMap[$variant] ?? $triggerMap['pills'] ?? '');
    // marker="filled": the active label inverts onto the primary marker.
    if ($marker === 'filled') {
        $triggerClass .= ' '.(($recipe['triggerFilled'] ?? [])[$variant] ?? '');
    }

    // fullWidth lets each trigger flex-grow to share the row equally.
    $fullWidthClass = $fullWidth ? ($recipe['triggerFull'] ?? '') : '';
@endphp

<button
    type="button"
    data-slot="tabs-trigger"
    data-variant="{{ $variant }}"
    role="tab"
    data-value="{{ $value }}"
    x-init="register(@js($value), {{ $disabled ? 'true' : 'false' }})"
    :id="$id('tabs-trigger', @js($value))"
    :aria-selected="isActive(@js($value))"
    :tabindex="isActive(@js($value)) ? 0 : -1"
    :data-state="isActive(@js($value)) ? 'active' : 'inactive'"
    x-bind:aria-controls="$id('tabs-panel', @js($value))"
    @click="select(@js($value))"
    @disabled($disabled)
    @if ($disabled) aria-disabled="true" @endif
    {{ $attributes->merge(['class' => trim($triggerClass).' '.$fullWidthClass]) }}
>
    {{ $slot }}
</button>

/**
 * Tabs behavior (spec §17 keyboard navigation + §19 behavior layer).
 *
 * Triggers register themselves so the first one can become active by default
 * and arrow-key navigation knows the order. Navigation respects orientation
 * (ArrowLeft/Right for horizontal, ArrowUp/Down for vertical) and is RTL-aware.
 *
 * Touch swipe: a horizontal touch drag that begins inside a tab panel
 * (data-slot="tabs-content") past a small threshold advances to the next/prev
 * enabled tab (clamped at the ends, RTL-aware, horizontal orientation only). It
 * is gated to `pointerType === 'touch'` so mouse/keyboard interaction and any
 * horizontal scrolling inside panel content are left untouched. Listeners are
 * added in init() and removed in destroy() so unmounting can't leak.
 *
 * URL sync (`param`): a record page with several tabs is shared as a link
 * to one of them. When `param` names a query key, the tab named in the URL
 * on load wins over `default` (only if a trigger with that value exists —
 * an unknown value is ignored, never trusted), and every later selection is
 * written back with `history.replaceState` so the address bar follows the
 * operator without growing the back stack. Off unless asked for.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiTabs', (config = {}) => ({
        active: config.default ?? null,
        orientation: config.orientation ?? 'horizontal',
        param: typeof config.param === 'string' && config.param !== '' ? config.param : null,
        values: [],

        // Touch-swipe bookkeeping.
        _swipeId: null,
        _swipeX: 0,
        _swipeY: 0,
        _onPointerDown: null,
        _onPointerUp: null,

        // Sliding-marker bookkeeping.
        _markerObserver: null,
        _markerPlaced: false,

        init() {
            this._bindSwipe();
            this._readParam();
            if (this.param !== null) {
                this.$watch('active', () => this._writeParam());
            }

            // Keep the active marker under the active trigger: on selection
            // change (after the DOM updates) and on any size change.
            this.$watch('active', () => this.$nextTick(() => this.syncMarker()));
            this.$nextTick(() => this.syncMarker());
            if (window.ResizeObserver) {
                this._markerObserver = new ResizeObserver(() => this.syncMarker());
                this._markerObserver.observe(this.$el);
            }
        },

        register(value, disabled = false) {
            if (!this.values.includes(value)) {
                this.values.push(value);
            }
            // A tab named in the URL claims the initial selection as soon as
            // its trigger registers; `default` and first-enabled only apply
            // when the URL names nothing (or nothing that exists).
            if (this._requested !== null && this._requested === value && !disabled) {
                this.active = value;
                this._requested = null;
                return;
            }
            // Don't let a disabled trigger become the default active tab; the
            // first enabled trigger claims it instead.
            if (this.active === null && !disabled) {
                this.active = value;
            }
        },

        // --- URL sync (opt-in via `param`) ------------------------------------
        _requested: null,

        _readParam() {
            if (this.param === null || typeof window === 'undefined') return;
            try {
                const value = new URLSearchParams(window.location.search).get(this.param);
                if (value !== null && value !== '') {
                    this._requested = value;
                }
            } catch {
                this._requested = null;
            }
        },

        _writeParam() {
            if (this.param === null || typeof window === 'undefined' || this.active === null) return;
            try {
                const url = new URL(window.location.href);
                if (url.searchParams.get(this.param) === String(this.active)) return;
                url.searchParams.set(this.param, String(this.active));
                window.history.replaceState(window.history.state, '', url);
            } catch {
                /* A sandboxed or file: document may refuse replaceState; the tab still switches. */
            }
        },

        isActive(value) {
            return this.active === value;
        },

        select(value) {
            this.active = value;
        },

        /**
         * Move the sliding marker under the active trigger. Uses physical
         * offsets (offsetLeft/offsetTop are relative to the list, which is the
         * offset parent), so it is RTL-correct without logical mapping. The
         * first placement snaps instead of sliding in from 0,0.
         */
        syncMarker() {
            const marker = this.$refs.marker;
            if (!marker) {
                return;
            }

            const active =
                this.active === null
                    ? null
                    : this.$el.querySelector(
                          `[data-slot="tabs-trigger"][data-value="${CSS.escape(String(this.active))}"]`
                      );
            if (!active) {
                marker.style.opacity = '0';
                return;
            }

            const firstPlacement = !this._markerPlaced;
            if (firstPlacement) {
                marker.style.transition = 'none';
            }

            const vertical = this.orientation === 'vertical';
            if (marker.dataset.variant === 'line') {
                // Line marker is a thin bar on the active edge; only the
                // in-axis position and length track the trigger.
                if (vertical) {
                    marker.style.transform = `translateY(${active.offsetTop}px)`;
                    marker.style.height = `${active.offsetHeight}px`;
                } else {
                    marker.style.transform = `translateX(${active.offsetLeft}px)`;
                    marker.style.width = `${active.offsetWidth}px`;
                }
            } else {
                marker.style.transform = `translate(${active.offsetLeft}px, ${active.offsetTop}px)`;
                marker.style.width = `${active.offsetWidth}px`;
                marker.style.height = `${active.offsetHeight}px`;
            }
            marker.style.opacity = '1';

            if (firstPlacement) {
                this._markerPlaced = true;
                void marker.offsetWidth;
                marker.style.transition = '';
            }
        },

        onKey(event) {
            const triggers = Array.from(
                this.$el.querySelectorAll('[data-slot="tabs-trigger"]:not(:disabled)')
            );
            const current = triggers.indexOf(event.target);

            if (current === -1) {
                return;
            }

            const rtl = getComputedStyle(this.$el).direction === 'rtl';
            const horizontal = this.orientation !== 'vertical';
            const nextKey = horizontal ? (rtl ? 'ArrowLeft' : 'ArrowRight') : 'ArrowDown';
            const prevKey = horizontal ? (rtl ? 'ArrowRight' : 'ArrowLeft') : 'ArrowUp';

            let next;
            if (event.key === nextKey) {
                next = (current + 1) % triggers.length;
            } else if (event.key === prevKey) {
                next = (current - 1 + triggers.length) % triggers.length;
            } else if (event.key === 'Home') {
                next = 0;
            } else if (event.key === 'End') {
                next = triggers.length - 1;
            } else {
                return;
            }

            event.preventDefault();
            const target = triggers[next];
            target.focus();
            this.select(target.getAttribute('data-value'));
        },

        // --- Touch swipe between panels (additive, touch-only) ----------------
        // Advance to the next/previous enabled tab, clamped at the ends. Returns
        // without changing state if there is no enabled neighbour in that
        // direction, so existing selection state and events are respected.
        _swipeTo(forward) {
            const triggers = Array.from(
                this.$el.querySelectorAll('[data-slot="tabs-trigger"]:not(:disabled)')
            );
            const values = triggers.map((t) => t.getAttribute('data-value'));
            const current = values.indexOf(this.active);
            if (current === -1) return;

            const next = forward ? current + 1 : current - 1;
            if (next < 0 || next > values.length - 1) return; // clamp at ends
            this.select(values[next]);
        },

        _bindSwipe() {
            const root = this.$el;
            if (!root) return;

            this._onPointerDown = (event) => {
                if (event.pointerType !== 'touch') return;
                // Only react to swipes that begin inside a tab panel, not the
                // trigger row (which has its own gestures/focus behaviour).
                if (!event.target.closest('[data-slot="tabs-content"]')) return;
                this._swipeId = event.pointerId;
                this._swipeX = event.clientX;
                this._swipeY = event.clientY;
            };
            this._onPointerUp = (event) => {
                if (this._swipeId === null || event.pointerId !== this._swipeId) return;
                const dx = event.clientX - this._swipeX;
                const dy = event.clientY - this._swipeY;
                this._swipeId = null;

                // Swipe only drives the horizontal tab axis.
                if (this.orientation === 'vertical') return;

                const threshold = 40;
                // Ignore mostly-vertical drags so content scroll isn't hijacked.
                if (Math.abs(dx) < threshold || Math.abs(dx) <= Math.abs(dy)) return;

                const rtl = getComputedStyle(root).direction === 'rtl';
                // Swipe left = advance (next); inverted under RTL.
                const forward = rtl ? dx > 0 : dx < 0;
                this._swipeTo(forward);
            };

            root.addEventListener('pointerdown', this._onPointerDown);
            root.addEventListener('pointerup', this._onPointerUp);
        },

        destroy() {
            const root = this.$el;
            if (root && this._onPointerDown) {
                root.removeEventListener('pointerdown', this._onPointerDown);
                root.removeEventListener('pointerup', this._onPointerUp);
            }
            this._onPointerDown = null;
            this._onPointerUp = null;
            if (this._markerObserver) {
                this._markerObserver.disconnect();
                this._markerObserver = null;
            }
        },
    }));
});