Disclosure

# Brok UI: Accordion (`accordion`)

Vertically stacked, keyboard-accessible disclosure panels with single or multiple open modes, chevron/plus-minus indicators, and default/separated/ghost/filled variants.

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

## Install

```bash
php artisan ui:add accordion
```

## Usage

```blade
<x-ui.accordion class="w-full max-w-md">
    <x-ui.accordion.item value="item-1">
        <x-ui.accordion.trigger>{{ __('Is it accessible?') }}</x-ui.accordion.trigger>
        <x-ui.accordion.content>{{ __('Yes. It follows the WAI-ARIA disclosure pattern with aria-expanded and full keyboard support.') }}</x-ui.accordion.content>
    </x-ui.accordion.item>
    <x-ui.accordion.item value="item-2">
        <x-ui.accordion.trigger>{{ __('Is it animated?') }}</x-ui.accordion.trigger>
        <x-ui.accordion.content>{{ __('Yes, with a reduced-motion-safe transition. Motion is skipped when the user prefers reduced motion.') }}</x-ui.accordion.content>
    </x-ui.accordion.item>
    <x-ui.accordion.item value="item-3">
        <x-ui.accordion.trigger>{{ __('Can multiple panels open?') }}</x-ui.accordion.trigger>
        <x-ui.accordion.content>{{ __('Pass :multiple="true" to the accordion root to allow several panels open at once.') }}</x-ui.accordion.content>
    </x-ui.accordion.item>
</x-ui.accordion>
```

## Props

- `multiple` (bool, default `false`) — Allows more than one item to stay open at once instead of closing others when a new one opens.
- `default` (mixed|null, default `null`) — Value or array of values open on mount.
- `variant` (default|separated|ghost|filled, default `default`) — Visual style: default (bordered, divided container), separated, ghost, or filled.
- `indicator` (string, default `chevron`) — Expand/collapse icon style: chevron or plus-minus.
- `chevronSide` (string, default `end`) — Logical side the indicator sits on: end or start (mirrors under dir="rtl").
- `inset` (bool, default `true`) — When false, runs triggers and panels flush to the container edge with no horizontal inset or hover tint, for an editorial full-width list.
- `type` (single|multiple, default `single`) — Whether one or many items can be open.
- `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.
- `subtitle` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `icon` (mixed|null, default `null`) — Declared by @props in the registry Blade source.

## Use when

- Use for secondary or optional content, especially when users usually inspect one short section at a time.
- Grouping several related sections (an FAQ, settings groups) where only the relevant ones need to stay expanded.
- Needing single- or multiple-open disclosure behaviour with built-in keyboard navigation between headings.

## Avoid when

- Do not hide required workflow content or comparison-heavy information because disclosure controls reduce visibility and increase interaction cost.
- Best for many short secondary sections. It reduces visibility and adds interaction cost, so keep required workflow content visible.
- Only one section ever needs to expand and collapse; use collapsible for a single disclosure.
- The content is a long list that should reveal more of the same content, not distinct sections; use show-more.

## Anti-patterns

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

## Rules

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

@props([
    'multiple' => false,
    'default' => null,
    'variant' => 'default',
    'indicator' => 'chevron',
    'chevronSide' => 'end',
    // false runs triggers and panels flush to the container edge (no
    // horizontal inset, no hover tint) — an editorial list whose dividers
    // span the full width. Read by trigger/content through @aware.
    'inset' => true,
])

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

    // Backward compatible: omitting variant reproduces the original bordered,
    // divided container. Children read `variant`/`indicator`/`chevronSide`
    // through @aware so triggers and items style themselves consistently.
    $rootMap = $styles['accordion']['root'] ?? [];
    $rootClass = $rootMap[$variant] ?? $rootMap['default'] ?? '';
@endphp

{{--
    Accordion (spec §19 behavior layer + §17 accessibility).
    Single or multiple open panels. Open state lives on the root via the
    `uiAccordion` Alpine component; items only carry their own value, so
    nested accordions and many instances on one page work independently.

    Variants (visual only, behaviour unchanged):
      - variant:     default | separated | ghost | filled
      - indicator:   chevron | plus-minus
      - chevronSide: end | start  (logical, mirrors under dir="rtl")
      - inset:       true | false (flush triggers and panels)
    Triggers expose expandAll()/collapseAll() on the root for controls.
--}}
<div
    x-data="uiAccordion({ multiple: {{ $multiple ? 'true' : 'false' }}, default: @js($default) })"
    data-slot="accordion"
    data-variant="{{ $variant }}"
    @if (! filter_var($inset, FILTER_VALIDATE_BOOLEAN)) data-inset="false" @endif
    @keydown="onKey($event)"
    {{ $attributes->merge(['class' => $rootClass]) }}
>
    {{ $slot }}
</div>

@aware([
    'variant' => 'default',
])

@props([
    'value',
])

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

    // `separated`/`filled` wrap each item as its own card; `default`/`ghost`
    // leave the item transparent and let the root's dividers do the work.
    $itemMap = $styles['accordion']['item'] ?? [];
    $itemClass = $itemMap[$variant] ?? $itemMap['default'] ?? '';
@endphp

<div
    data-slot="accordion-item"
    data-variant="{{ $variant }}"
    x-data="{ value: @js($value) }"
    x-id="['accordion-panel']"
    {{ $attributes->merge(['class' => $itemClass]) }}
>
    {{ $slot }}
</div>

@aware([
    'indicator' => 'chevron',
    'chevronSide' => 'end',
    'inset' => true,
])

@props([
    'subtitle' => null,
    'icon' => null,
    'disabled' => false,
])

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

    $triggerClass = ($recipe['trigger'] ?? '').' '.(filter_var($inset, FILTER_VALIDATE_BOOLEAN) ? ($recipe['triggerInset'] ?? 'px-6 py-4 hover:bg-muted/50') : ($recipe['triggerFlush'] ?? 'py-4'));
    $indicatorClass = $recipe['indicator'] ?? '';
    $subtitleClass = $recipe['subtitle'] ?? '';

    // chevronSide is logical: `start` puts the indicator before the label and
    // mirrors under dir="rtl"; `end` keeps the classic right-aligned layout.
    $indicatorFirst = $chevronSide === 'start';
    $layoutClass = $indicatorFirst ? 'justify-start gap-3' : 'justify-between gap-4';
@endphp

<h3 class="flex" data-slot="accordion-heading">
    <button
        type="button"
        data-slot="accordion-trigger"
        :data-value="value"
        :aria-expanded="isOpen(value)"
        :data-state="isOpen(value) ? 'open' : 'closed'"
        x-bind:aria-controls="$id('accordion-panel')"
        @click="toggle(value)"
        @disabled($disabled)
        @if ($disabled) aria-disabled="true" @endif
        {{ $attributes->merge(['class' => $triggerClass.' '.$layoutClass]) }}
    >
        @if ($indicator === 'plus-minus')
            {{-- Plus that loses its vertical stroke when open, reading as a minus.
                 The horizontal stroke stays put; only the vertical scales away. --}}
            <svg
                aria-hidden="true"
                viewBox="0 0 24 24"
                fill="none"
                stroke="currentColor"
                stroke-width="2"
                stroke-linecap="round"
                class="{{ $indicatorClass }} {{ $indicatorFirst ? 'order-first' : 'order-last' }}"
            >
                <path d="M5 12h14" />
                <path
                    d="M12 5v14"
                    class="origin-center transition-transform duration-200 motion-reduce:transition-none"
                    :class="isOpen(value) && 'scale-y-0'"
                />
            </svg>
        @else
            {{-- end-side: a down-chevron that flips to point up when open.
                 start-side: an end-pointing chevron (logical; mirrors under RTL)
                 that rotates a quarter-turn down when open. --}}
            <svg
                aria-hidden="true"
                viewBox="0 0 24 24"
                fill="none"
                stroke="currentColor"
                stroke-width="2"
                stroke-linecap="round"
                stroke-linejoin="round"
                class="{{ $indicatorClass }} group-hover:text-foreground {{ $indicatorFirst ? 'order-first rtl:-scale-x-100' : 'order-last' }}"
                :class="isOpen(value) && '{{ $indicatorFirst ? 'rotate-90' : 'rotate-180' }}'"
            >
                @if ($indicatorFirst)
                    <path d="m9 18 6-6-6-6" />
                @else
                    <path d="m6 9 6 6 6-6" />
                @endif
            </svg>
        @endif

        @if ($icon)
            <span class="shrink-0 text-muted-foreground" data-slot="accordion-trigger-icon" aria-hidden="true">{{ $icon }}</span>
        @endif

        <span class="{{ $indicatorFirst ? '' : 'flex-1' }}">
            {{ $slot }}
            @if ($subtitle)
                <span class="block {{ $subtitleClass }}" data-slot="accordion-subtitle">{{ $subtitle }}</span>
            @endif
        </span>
    </button>
</h3>

@aware([
    'inset' => true,
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $recipe = $styles['accordion'] ?? [];
    $bodyClass = filter_var($inset, FILTER_VALIDATE_BOOLEAN) ? ($recipe['contentInset'] ?? 'px-5 pb-4 pt-0') : ($recipe['contentFlush'] ?? 'pb-4 pt-0');
@endphp

<div
    data-slot="accordion-content"
    role="region"
    x-bind:id="$id('accordion-panel')"
    :data-state="isOpen(value) ? 'open' : 'closed'"
    x-cloak
    {{-- inert (not just aria-hidden): the closed panel leaves the a11y tree AND the tab order. --}}
    x-bind:inert="! isOpen(value)"
    {{-- Grid rows 0fr → 1fr animate height without JS measurement; the panel stays rendered. --}}
    :class="isOpen(value) ? 'grid-rows-[1fr] opacity-100' : 'grid-rows-[0fr] opacity-0'"
    {{ $attributes->merge(['class' => 'grid text-sm text-muted-foreground transition-[grid-template-rows,opacity] duration-base ease-standard motion-reduce:transition-none']) }}
>
    <div class="min-h-0 overflow-hidden">
        <div class="{{ $bodyClass }} leading-relaxed">
            {{ $slot }}
        </div>
    </div>
</div>

/**
 * Accordion behavior (spec §19 behavior layer).
 *
 * Open state is held on the root component so a single accordion can run in
 * "single" or "multiple" mode. Items only carry their own value, which keeps
 * nested accordions and multiple instances on a page independent.
 *
 * 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('uiAccordion', (config = {}) => ({
        multiple: config.multiple ?? false,
        open: config.default != null ? [config.default] : [],

        isOpen(value) {
            return this.open.includes(value);
        },

        toggle(value) {
            if (this.isOpen(value)) {
                this.open = this.open.filter((v) => v !== value);
            } else {
                this.open = this.multiple ? [...this.open, value] : [value];
            }
        },

        /** Values of every (enabled) item, read straight off the triggers. */
        allValues() {
            return Array.from(
                this.$el.querySelectorAll('[data-slot="accordion-trigger"]:not(:disabled)')
            ).map((el) => el.dataset.value);
        },

        /**
         * Open every panel. Only meaningful in `multiple` mode — single mode can
         * by definition hold one open panel, so we open the first instead.
         */
        expandAll() {
            const values = this.allValues();
            this.open = this.multiple ? values : values.slice(0, 1);
        },

        /** Close every panel. */
        collapseAll() {
            this.open = [];
        },

        /** Roving keyboard navigation across the accordion triggers. */
        onKey(event) {
            const triggers = Array.from(
                this.$el.querySelectorAll('[data-slot="accordion-trigger"]:not(:disabled)')
            );
            const current = triggers.indexOf(event.target);

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

            let next;
            switch (event.key) {
                case 'ArrowDown':
                    next = (current + 1) % triggers.length;
                    break;
                case 'ArrowUp':
                    next = (current - 1 + triggers.length) % triggers.length;
                    break;
                case 'Home':
                    next = 0;
                    break;
                case 'End':
                    next = triggers.length - 1;
                    break;
                default:
                    return;
            }

            event.preventDefault();
            triggers[next].focus();
        },
    }));
});