#Data Grid

Data Grid handles resource collections that need sorting, selection, bulk actions, and remote pagination. It builds on Table, Checkbox, Filter Bar, and Pagination without owning queries, authorization, or data fetching.

npm install @a3s-lab/ui@0.4.0

<section class="data-grid" data-responsive="stack" aria-labelledby="grid-title">
  <header>
    <div data-grid-identity><h2 id="grid-title">Environments</h2></div>
  </header>
  <div data-grid-viewport tabindex="0">
    <table class="table">
      <thead>
        <tr>
          <th>
            <input
              type="checkbox"
              data-grid-select-all
              aria-label="Select all"
            />
          </th>
          <th aria-sort="none">
            <button type="button" data-grid-sort="name">Name</button>
          </th>
        </tr>
      </thead>
      <tbody>
        <tr data-value="production">
          <td data-grid-select-cell>
            <input
              type="checkbox"
              data-grid-select
              value="production"
              aria-label="Select Production"
            />
          </td>
          <td data-label="Name">Production</td>
        </tr>
      </tbody>
    </table>
  </div>
</section>

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

#Usage

Load the runtime and Data Grid controller, or use the complete JavaScript bundle.

<script src="/assets/js/runtime.min.js" defer></script>
<script src="/assets/js/data-grid.min.js" defer></script>

<section class="data-grid" data-responsive="stack" aria-labelledby="grid-title">
  <header>
    <div data-grid-identity><h2 id="grid-title">Environments</h2></div>
  </header>
  <div data-grid-viewport tabindex="0">
    <table class="table">
      <thead>
        <tr>
          <th>
            <input
              type="checkbox"
              data-grid-select-all
              aria-label="Select all"
            />
          </th>
          <th aria-sort="none">
            <button type="button" data-grid-sort="name">Name</button>
          </th>
        </tr>
      </thead>
      <tbody>
        <tr data-value="production">
          <td data-grid-select-cell>
            <input
              type="checkbox"
              data-grid-select
              value="production"
              aria-label="Select Production"
            />
          </td>
          <td data-label="Name">Production</td>
        </tr>
      </tbody>
    </table>
  </div>
</section>

#Parameters

#JavaScript API

const grid = document.querySelector(".data-grid");
grid.setSelection(["production", "staging"]);
grid.toggleSelection("preview", true);
grid.setSort("name", "ascending");
grid.setState("loading", { message: "Refreshing environments…" });
console.log(grid.getState());
grid.addEventListener("a3s:data-grid-sort", ({ detail }) => loadPage(detail));

getSelection(), setSelection(), toggleSelection(), selectAll(), and clearSelection() keep checkboxes, selected rows, the header checkbox, and a nested Bulk Action Bar synchronized. getSort() and setSort() control one active sort. getState() returns view, selection, and sort snapshots; setState() switches feedback regions; refresh({ preserveSelection, preserveSort }) rebinds replaced rows.

The cancelable a3s:data-grid-before-selection-change, a3s:data-grid-before-sort, and a3s:data-grid-before-row-action hooks run before visible state is committed. Completed events are a3s:data-grid-selection-change, a3s:data-grid-sort, a3s:data-grid-row-action, and a3s:data-grid-state-change. Details identify previous, current, source, and originalEvent; legacy values, selectedCount, key, and direction fields remain available. The controller never reorders rows, fetches data, or authorizes a command.

#States and variants

Client collections may replace rows directly. Server collections should preserve the active filter, sort, rows, and column widths during a background request. Use separate data-grid-state="empty", error, and permission-denied regions so each state names the problem and recovery. Row actions are part of the grid contract rather than a separate public component.

The default narrow layout keeps horizontal scrolling. Use data-responsive="stack" only when a record still reads linearly. Keep scrolling for wide comparisons, editable cells, or many columns.

#Accessibility

Use real <th> elements and put aria-sort on the header rather than its button. Every checkbox needs a row-specific name. Do not move focus when bulk actions appear. Announce server result counts politely, and never discard the current selection during loading without explaining why.