Action Bar

# Brok UI: Action Bar (`action-bar`)

Floating contextual toolbar for bulk-selection actions: follows a live selection count, sticks to the viewport or the content area, and holds a suggested action, an Actions menu and Clear. Dismissable via button or Escape key.

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

## Install

```bash
php artisan ui:add action-bar
```

## Usage

```blade
{{-- Selecting rows shows the bar; dismissing it (button or Escape) dispatches
     `action-bar:close`, so the host clears its selection and can open it again. --}}
<div
    x-data="{ selected: [] }"
    @action-bar:close="selected = []"
    class="flex min-h-56 w-full max-w-md flex-col gap-2"
>
    @foreach ([__('Quarterly report.pdf'), __('Brand guidelines.fig'), __('Launch checklist.md')] as $i => $file)
        <label class="flex items-center gap-3 rounded-md border border-border bg-card px-3 py-2 text-sm text-foreground hover:bg-muted">
            <x-ui.checkbox value="{{ $i }}" x-model="selected" />
            <span>{{ $file }}</span>
        </label>
    @endforeach

    <x-ui.action-bar :count="0" x-effect="selected.length ? show(selected.length) : hide()">
        <x-ui.action-bar.action><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="2" y="3" width="20" height="5" rx="1" /><path d="M4 8v11a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8M10 12h4" /></svg> {{ __('Archive') }}</x-ui.action-bar.action>
        <x-ui.action-bar.action><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12.6 2.6 21 11l-9.4 9.4a2 2 0 0 1-2.8 0L2.6 14.2a2 2 0 0 1 0-2.8L11 3a2 2 0 0 1 1.6-.4Z" /><circle cx="7.5" cy="7.5" r="1.5" /></svg> {{ __('Label') }}</x-ui.action-bar.action>
        <x-ui.action-bar.action tone="destructive"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 6h18" /><path d="M8 6V4h8v2" /><path d="M19 6l-1 14H6L5 6" /><path d="M10 11v6M14 11v6" /></svg> {{ __('Delete') }}</x-ui.action-bar.action>
    </x-ui.action-bar>
</div>
```

## Props

- `open` (bool, default `false`) — Whether the bar is visible on mount.
- `count` (int, default `0`) — Number of selected items shown in the count chip.
- `label` (string, default `selected`) — Unit label appended after the count; it is translated with __().
- `variant` (default|inverse|bar, default `default`) — Surface style: default (popover pill), inverse (primary fill), or bar (card).
- `position` (string, default `bottom`) — Placement: bottom or top (fixed to the viewport), sticky (the bottom of the scrolling content area, so it centres on the list beside a sidebar), or static (in normal document flow).
- `countFrom` (string|null, default `null`) — Alpine expression for the live count, such as selected.length or $wire.selected.length. The bar opens while the count is above 0 and closes at 0.
- `clearLabel` (string|null, default `null`) — Visible text for the dismiss button, such as Clear. Null keeps the icon-only Dismiss button.
- `countTone` (neutral|primary, default `neutral`) — The count chip fill: neutral (secondary tokens, the default) keeps the readout calm so the view's one primary action stands out; primary restores the brand fill. The inverse variant keeps its own chip.
- `tone` (string, default `default`) — Declared by @props in the registry Blade source.

## Use when

- Use for secondary actions when compact access is more important than constant visibility.
- Surfacing bulk actions (archive, delete, export) after the user selects rows in a table or list.
- Needing a floating toolbar that appears and disappears in response to a changing selection count.

## Avoid when

- Do not hide the most frequent or highest-value actions in a menu when discoverability matters.
- Showing actions for a single row; use inline row buttons or a dropdown menu.
- Presenting one-off contextual actions on right-click; use context-menu instead.

## Anti-patterns

- Hiding primary actions in menus

## Rules

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

{{--
    Action Bar — floating contextual toolbar for bulk-selection actions.

    Props:
      open     (bool)   — whether the bar is visible on mount             [false]
      count    (int)    — number of selected items shown in the chip      [0]
      label    (string) — unit label appended to the count chip           ['selected']
      variant  (string) — default (popover pill) | inverse (primary fill) | bar (card) ['default']
      position (string) — bottom | top (fixed) | sticky (bottom of the
                          scrolling content area) | static (in flow)      ['bottom']
      countFrom (string)— Alpine expression for the live count, such as
                          "selected.length" or "$wire.selected.length"; the
                          bar then opens while it is above 0              [null]
      clearLabel (string)— visible text for the dismiss button ("Clear");
                          null keeps the icon-only button                 [null]
      countTone (string)— neutral (secondary fill) | primary (brand fill)
                          for the count chip; ignored by inverse        ['neutral']

    Slots: the default slot holds the suggested action(s); `actions` holds one
    "Actions" menu (a dropdown), after a divider.

    Usage:
      <x-ui.action-bar :open="true" :count="3">
          <x-ui.action-bar.action>Archive</x-ui.action-bar.action>
          <x-ui.action-bar.action tone="destructive">Delete</x-ui.action-bar.action>
      </x-ui.action-bar>

    A bottom or sticky bar that is open sets --ui-action-bar-inset on <html>;
    the toaster stacks above it, so a toast never covers Clear or Actions.

    The bar is self-contained: call `show(n)` / `hide()` on it, or dispatch
    `action-bar:show` { count } / `action-bar:hide` on the window. Dismissing
    (button or Escape) dispatches `action-bar:close` from the root, so the host
    can drop its own selection state and re-open the bar next time.
--}}
@props([
    'open'  => false,
    'count' => 0,
    'label' => 'selected',
    'variant' => 'default',
    'position' => 'bottom',
    'countFrom' => null,
    'clearLabel' => null,
    'countTone' => 'neutral',
])

@php
    // Accept a string, a backed enum or a Stringable for `variant`.
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $variant = in_array($variant, ['default', 'inverse', 'bar'], true) ? $variant : 'default';
    $position = in_array($position, ['bottom', 'top', 'sticky', 'static'], true) ? $position : 'bottom';
    $label = __($label);
    $clearLabel = filled($clearLabel) ? __($clearLabel) : null;
    $place = match ($position) {
        'top' => 'fixed inset-x-0 top-6 z-popover mx-auto w-fit',
        'static' => 'relative w-fit',
        // Sticks to the bottom of the scrolling content area (not the
        // viewport), so it centres on the list beside a sidebar.
        'sticky' => 'sticky bottom-6 z-sticky mx-auto w-fit',
        default => 'fixed inset-x-0 bottom-6 z-popover mx-auto w-fit',
    };
    $surface = match ($variant) {
        'inverse' => 'gap-2 rounded-full bg-primary px-3 py-2 text-primary-foreground shadow-lg',
        'bar' => 'gap-3 rounded-md border border-border bg-popover px-4 py-2 text-popover-foreground shadow-lg',
        default => 'gap-2 rounded-full border border-border bg-popover px-3 py-2 text-popover-foreground shadow-lg',
    };
    // The count is a readout, not the view's primary action: it stays
    // neutral unless the app opts into the brand fill.
    $countTone = $countTone === 'primary' ? 'primary' : 'neutral';
    $chip = match (true) {
        $variant === 'inverse' => 'bg-primary-foreground/15 text-primary-foreground',
        $countTone === 'primary' => 'bg-primary text-primary-foreground',
        default => 'bg-secondary text-secondary-foreground',
    };
    $enterFrom = $position === 'top' ? 'motion-safe:-translate-y-4' : 'motion-safe:translate-y-4';
@endphp

<div
    x-data="uiActionBar({ open: @js((bool) $open), count: @js((int) $count), label: @js($label), cleared: @js(__('Selection cleared')), dock: @js(in_array($position, ['bottom', 'sticky'], true)) })"
    data-slot="action-bar"
    data-variant="{{ $variant }}"
    data-position="{{ $position }}"
    @action-bar:show.window="show($event.detail?.count)"
    @action-bar:hide.window="hide()"
    @if (filled($countFrom))
        x-effect="sync({{ $countFrom }})"
    @endif
    {{ $attributes->merge(['class' => 'group/bar '.$place]) }}
>
    {{-- Announces the count as it changes ("3 selected"), also while the
         bar itself is hidden, so a cleared selection is heard too. --}}
    <span data-slot="action-bar-status" role="status" aria-live="polite" aria-atomic="true" class="sr-only" x-text="announcement"></span>
    <div
        x-show="open"
        x-transition:enter="motion-safe:transition motion-safe:ease-emphasized motion-safe:duration-200"
        x-transition:enter-start="{{ $enterFrom }} motion-safe:opacity-0"
        x-transition:enter-end="motion-safe:translate-y-0 motion-safe:opacity-100"
        x-transition:leave="motion-safe:transition motion-safe:ease-standard motion-safe:duration-150"
        x-transition:leave-start="motion-safe:translate-y-0 motion-safe:opacity-100"
        x-transition:leave-end="{{ $enterFrom }} motion-safe:opacity-0"
        role="toolbar"
        :aria-label="count + ' ' + @js($label)"
        {{-- Escape clears, unless a menu, listbox or dialog took the key. --}}
        @keydown.escape.window="open && !$event.defaultPrevented && !$event.target.closest?.('[role=menu],[role=listbox],[role=dialog],[role=alertdialog]') && dismiss()"
        class="flex items-center motion-reduce:transition-none {{ $surface }}"
    >
        {{-- Count chip --}}
        <span
            data-slot="action-bar-count"
            data-tone="{{ $countTone }}"
            x-text="count + ' ' + @js($label)"
            class="inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium tabular-nums {{ $chip }}"
        ></span>

        <span class="h-4 w-px shrink-0 bg-current/20" aria-hidden="true"></span>

        {{-- Action buttons slot --}}
        {{ $slot }}

        @isset($actions)
            <span class="h-4 w-px shrink-0 bg-current/20" aria-hidden="true"></span>
            <span data-slot="action-bar-actions" class="inline-flex items-center">{{ $actions }}</span>
        @endisset

        <span class="h-4 w-px shrink-0 bg-current/20" aria-hidden="true"></span>

        {{-- Dismiss button: clears the selection through action-bar:close. --}}
        @if ($clearLabel)
            <button
                type="button"
                data-slot="action-bar-dismiss"
                @click="dismiss()"
                aria-keyshortcuts="Escape"
                class="inline-flex h-7 items-center gap-1 rounded-full px-2 text-xs font-medium opacity-70 transition-[opacity,background-color] hover:bg-current/10 hover:opacity-100 focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring motion-reduce:transition-none"
            >
                <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12" /></svg>
                <span>{{ $clearLabel }}</span>
            </button>
        @else
            <button
                type="button"
                data-slot="action-bar-dismiss"
                @click="dismiss()"
                aria-label="{{ __('Dismiss') }}"
                aria-keyshortcuts="Escape"
                class="inline-flex size-7 items-center justify-center rounded-full opacity-70 transition-[opacity,background-color] hover:bg-current/10 hover:opacity-100 focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring motion-reduce:transition-none"
            >
                <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12" /></svg>
            </button>
        @endif
    </div>
</div>

/**
 * Action Bar — floating contextual toolbar for bulk-selection actions.
 *
 * show(n)   — open the bar, optionally updating the count.
 * hide()    — close the bar silently (the host changed the selection itself).
 * sync(n)   — follow a live count (the `count-from` expression): open above
 *             0, close at 0.
 * dismiss() — close from the bar's own controls (button, Escape) and tell the
 *             host with `action-bar:close`, so it can clear its selection
 *             state and open the bar again next time.
 *
 * Also driven from outside: `action-bar:show` { count } and `action-bar:hide`
 * on the window (wired in the template).
 *
 * A bottom or sticky bar reserves its space while it is open: it writes the
 * distance from its top edge to the bottom of the viewport to
 * `--ui-action-bar-inset` on <html>. The toaster sits on that inset, so a
 * toast never covers Clear or the actions (WCAG 2.4.11 Focus Not Obscured).
 */
const docked = new Map();

function publishInset() {
    const inset = Math.max(0, ...docked.values());
    const root = document.documentElement;
    if (inset > 0) {
        root.style.setProperty('--ui-action-bar-inset', `${inset}px`);
    } else {
        root.style.removeProperty('--ui-action-bar-inset');
    }
}

document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiActionBar', (config = {}) => ({
        open: config.open ?? false,
        count: config.count ?? 0,
        label: config.label ?? '',
        cleared: config.cleared ?? '',
        announcement: '',
        dock: config.dock ?? false,

        init() {
            if (!this.dock) return;
            this.measure = () => this.reserve();
            this.observer = new ResizeObserver(this.measure);
            this.observer.observe(this.$el);
            window.addEventListener('resize', this.measure);
            this.$watch('open', this.measure);
            this.$nextTick(this.measure);
        },

        destroy() {
            this.observer?.disconnect();
            if (this.measure) window.removeEventListener('resize', this.measure);
            docked.delete(this);
            publishInset();
        },

        reserve() {
            // The root carries no transform, so its box is where the bar
            // settles even while the toolbar is still sliding in.
            const top = this.$el.getBoundingClientRect().top;
            const inset = Math.round(window.innerHeight - top);
            if (this.open && this.$el.offsetHeight > 0 && inset > 0 && inset < window.innerHeight) {
                docked.set(this, inset);
            } else {
                docked.delete(this);
            }
            publishInset();
        },

        show(n) {
            if (Number.isFinite(n)) this.count = n;
            this.open = true;
            this.announce();
        },

        hide() {
            const wasOpen = this.open;
            this.open = false;
            if (wasOpen) this.announce();
        },

        sync(n) {
            const count = Math.max(0, Number(n) || 0);
            if (count > 0) {
                this.show(count);
            } else {
                this.count = 0;
                this.hide();
            }
        },

        announce() {
            this.announcement = this.open ? `${this.count} ${this.label}`.trim() : this.cleared;
        },

        dismiss() {
            this.open = false;
            this.announce();
            this.$dispatch('action-bar:close', { count: this.count });
        },
    }));
});