#Bulk Action Bar

Bulk Action Bar is a temporary command region for a collection with an active selection. It keeps the selected scope, eligibility, batch commands, and the way out of selection mode in one predictable place.

npm install @a3s-lab/ui@0.4.0

<section
class="bulk-action-bar"
data-state="selected"
data-bulk-focus-return="#bulk-action-bar-collection-en"
role="region"
aria-label="Selected environment actions"
>
<div data-bulk-selection>
  <output data-selected-count>3</output> selected
</div>
<span data-bulk-summary aria-live="polite">
  2 items can be archived
</span>
<div data-bulk-actions>
  <button type="button" class="btn" data-variant="outline" data-bulk-action="move">
    Move
  </button>
  <button type="button" class="btn" data-variant="outline" data-bulk-action="archive">
    Archive 2
  </button>
  <button type="button" class="btn" data-variant="destructive" data-bulk-action="delete">
    Delete
  </button>
  <button type="button" class="btn" data-variant="ghost" data-bulk-action="clear" data-bulk-clear>
    Clear selection
  </button>
</div>
</section>

import "@a3s-lab/ui/a3s.css";
import "@a3s-lab/ui/all";

#Usage

Keep the bar adjacent to the collection that owns the selection. Give the root a collection-specific accessible name, keep the exact selected count visible, and label each command with the number of eligible items when eligibility is partial. The host owns permission checks, confirmation, requests, optimistic updates, rollback, and retry.

The controller can be loaded with the complete runtime or as a split entry:

<script src="/assets/js/runtime.min.js" defer></script>
<script src="/assets/js/bulk-action-bar.min.js" defer></script>

The integrated preview above is the canonical HTML, React, and Vue example. Its source disclosure keeps the install command, setup entry, and example file in one workspace; switch the tabs in the preview toolbar to copy the active file.

#Contract

setPending(action, true, { message, allowClear }) disables the pending command and every contradictory command while retaining the original disabled states. allowClear defaults to true; set it to false when leaving selection mode would conflict with a host request. Clearing during pending does not cancel the request and preserves the pending region until the host completes it.

#States and recovery

The live preview toolbar includes the state acceptance matrix. It verifies that empty hides the region, selected preserves the scope, loading disables contradictory commands, and disabled applies native disabled semantics to every command.

<section class="bulk-action-bar" data-state="selected" data-result="error" role="region" aria-label="Selected run actions">
    <div data-bulk-selection>
      <output data-selected-count>2</output> selected
    </div>
    <span data-bulk-summary role="status">
      Archive failed: production permission is missing. Retry after access is granted or clear selection.
    </span>
    <div data-bulk-actions>
      <button type="button" class="btn" data-size="sm" data-variant="outline" data-bulk-action="archive">
        Retry archive for 2
      </button>
      <button type="button" class="btn" data-size="sm" data-variant="ghost" data-bulk-action="clear" data-bulk-clear>
        Clear selection
      </button>
    </div>
  </section>

When five items are selected but only three are eligible, label the command “Retry 3”, not “Retry 5” followed by a silent server-side skip. Destructive commands still require Alert Dialog confirmation with the affected count.

#Accessibility and ownership

The root region must be named for the collection it affects and must not move focus when it appears. Selection count, eligible count, progress, and outcome are expressed as text. The pending command keeps its label and exposes aria-busy="true" on the root; clear remains available only when allowClear permits it. After a rejected request, preserve the selection and focus context so the recovery command is still reachable. After a successful clear or completion, restore focus to the stable collection target instead of leaving focus on a hidden action.

React and Vue use the same controller events and methods. They do not create a framework-specific selection store or perform network work inside the adapter.