GrDataTable

rowKey (the id field by default) takes part both in the :key for Vue and in the selection of rows. A row that has no value at the key gets a synthetic key tied to the identity of the object, and in dev mode the component warns about that in the console once.

A synthetic key survives sorting but does not survive a reload of the data: after a new fetch the same row will have a different one, which means a v-model:selected from the previous set will match nothing. For tables with selection, set rowKey explicitly — as a field or as a function:

<GrDataTable :rows="rows" :columns="columns" :row-key="row => `${row.type}:${row.id}`" />

The component sorts by itself until externalSort is set (then the rows arrive already sorted, and the table only reports the change through update:sortKey/update:sortDir/sortChange).

sortable: true over server-side pagination is a trap. What gets sorted is the array passed in, that is, the current page: the “largest write-off” column will show the maximum across twenty visible rows and will be read as the maximum across the log. If the data arrives paginated, the sorting moves into the request:

<GrDataTable
  v-model:sort-key="sortKey"
  v-model:sort-dir="sortDir"
  :rows="page.data"
  :columns="columns"
  external-sort
  @sortChange="reload"
/>

The choice here is not between “the sorting lies” and “there is no sorting”: externalSort leaves the headings clickable and announces the direction in aria-sort, while the order of the rows is computed by the one who knows about all of the pages.

The comparison rules live in grDataTableSort.ts and are tested without mounting:

• empty values (null, undefined, a whitespace string) are always at the end, in both directions. Coercion to a number through Number() would count them as zero, and empty cells would settle in the middle of a numeric series;
• numbers, numeric strings, Date and boolean are compared numerically;
• everything else uses localeCompare with sensitivity: 'base' and numeric: true, in the locale of the i18n adapter rather than in the locale of the browser.

sortCycle="asc-desc-none" adds a third click that removes the sorting; imperatively the same is done by clearSort().

The starting order is set by initialSortKey and initialSortDir (asc by default) — that is not the same as sortKey/sortDir: the former set the initial state and do not get in the user’s way afterwards, the latter make the sorting controlled, and then only the parent changes it. One of the two pairs has to be set: together they would mean the table received both an initial value and an owner of the state.

The sort button is named by the label of the column — the same one AT reads when moving across the cells. The direction is announced by aria-sort on the <th>, and “what will happen on a press” by hidden text inside the button (sr-only). An aria-label on the button is forbidden here: it replaces the name of the <th>, and instead of “Name” a screen reader reads “Sorted by Name ascending, press…”.

Loading and the empty state are announced by a live region that exists from the first render and is empty while there is nothing to announce: a region that appears already carrying text is not announced at all by some AT.

selectable + v-model:selected (an array of keys). Without v-model:selected the table keeps the selection inside itself — as with sorting without sortKey.

selectableRow excludes a row from the selection: no checkbox is rendered for it, and it does not enter “select all”. “Select all” works over the visible rows and does not touch keys that are not on the screen right now (filtered out ones, for instance).

A navigational click (@row-click) is suppressed exactly on the checkbox: marking a row and leaving by a transition in one click is not possible. The service cell itself remains an ordinary cell of the row — in a row excluded from the selection, where there is no checkbox, it is clickable like any other.

• @row-click gives { row, index, event };
• rowClass is a string or a function of the row;
• rowProps are arbitrary attributes (data-*, title);
• the slots #cell-<key>, #header-<key>, #summary-<key>, #empty, #loading, #caption, #footer;
• emptyText/loadingText — if text without a slot is enough;
• the width of a column is a number (pixels) or a string ('30%', '12rem'); it travels into the heading cell and works in any mode.

summaryRow holds values by the keys of the columns. The row goes into the <tfoot> on the same column grid as the body:

<GrDataTable :rows="rows" :columns="columns" :summary-row="{ channel: 'Total', net: total }" />

A column that is not in the object stays an empty cell — a total is not obliged to fill the whole row. Zero is printed in the process: “the total is zero” and “there is no total” are different statements.

Why a prop rather than markup by hand. GrTable deliberately does not style the cells, and a row assembled in #footer gets padding of its own — and that is tied to size. It is enough to give the table size="lg" for a hand-written px-3 py-2 to diverge from the body by four pixels along both axes. The same goes for alignment, width and pinning: align="right", width and pinned would have to be reproduced on every cell. summaryRow takes all of that from the same functions as a body row.

The styling of a cell is the #summary-<key> slot, and the scope gives away value and column:

<GrDataTable :rows="rows" :columns="columns" :summary-row="summaryRow">
  <template #summary-net="{ value }">
    <span class="text-[var(--gr-danger-text)]">{{ money(value) }}</span>
  </template>
</GrDataTable>

The row has no tone by default and none by a prop: “refunds” and “profit” are different messages, and the component cannot choose on the application’s behalf. By default a total gets only a separation and a weight.

The total is not summed by the component: what counts as the total — the filters, the page, the whole log — is known by the application, not by the table.

#footer remains: it is for what does not fit into a single typed row — several totals, a note, a colspan. It is rendered into the same <tfoot> after the summaryRow, so the content of the slot is table rows as well (<tr><td>) rather than a free block. A flex justify-between there will give a block that lies under the table but does not stand under its column.

The scope gives away the columns in their current order and their total number together with the selection column — so that the colspan is not guessed by eye:

<GrDataTable :rows="rows" :columns="columns">
  <template #footer="{ totalColumns }">
    <tr>
      <td :colspan="totalColumns">
        Refunds are included in the "Total" row
      </td>
    </tr>
  </template>
</GrDataTable>

columns is needed when a row is computed across several columns: the order there is the user’s (columnOrder), and repeating it by hand means diverging from the header at the very first move of a column.

virtual together with maxHeight keeps in the DOM only the window around the viewport.

<GrDataTable :rows="rows" :columns="columns" virtual sticky-header :max-height="420" />

The spacers here are rows, not pseudo-elements. In list components what is cut off is held by the ::before/::after of the container, but in a table that is not possible: a <tbody> ignores padding, and a pseudo-element inside a group of rows does not form a row with a controllable height. Service <tr> elements with a single cell spanning all of the columns therefore stand at the top and at the bottom — of the same shape as the loading and empty rows — and they are hidden from a screen reader.

What is measured is the row group, not the row. The body is assembled in groups of one row each, and the measurement hangs on the group — otherwise the second tier of an expanded row would not make it into the height (see “The second tier of a row”).

The layout is fixed. The width of a column is computed from the content of all of the rows, and in the DOM there is only the window of them: without fixing, the columns would jump on every scroll. Set the width of the columns — otherwise a fixed layout divides the space equally, and a narrow # gets as much as Email.

The number of rows is declared explicitly. A screen reader counts the rows by the markup, and there there is a window, so the table gives away aria-rowcount, and the rows aria-rowindex (the heading is the first, and the set starts with the second). In the ordinary mode those attributes are absent: there the set is visible in the DOM. How the primitive works — virtual-list.md.

reorderable-columns adds a drag handle to every header cell. A column is dragged with a pointer (with the mouse and with a finger) and moved from the keyboard — Shift+←/→ on the handle; the result is announced into a live region.

<GrDataTable
  v-model:column-order="order"
  reorderable-columns
  :columns="columns"
  :rows="rows"
/>

v-model:column-order is an array of keys. Without it the table remembers the order itself, as it does the sorting without v-model:sortKey. Beside it there is the columnReorder event ({ key, from, to }) — with it a single operation is convenient to save rather than the whole list.

The set of columns is set by columns, and the order only orders. A key that is not in the set is ignored; a column that is not in the order (it has just been added) goes to the end. Otherwise an edit of columns would lose columns silently.

The handle is a button of its own rather than the heading itself: a click on the heading remains sorting, and dragging does not intercept it. In the tab order the handles hold one stop for the whole header (a roving tabindex), and bare ←/→ walk the focus between them.

resizable-columns adds a handle to the right edge of every heading. The width is dragged with a pointer, and from the keyboard the handle behaves like a window splitter (role="separator", the GrSplitter pattern): ←/→ is a step of 16px, with Shift 48px, and Enter returns the column to automatic layout. A double click does the same.

v-model:column-widths holds the widths in pixels by column key; without it the table remembers them itself. The columnResize event ({ key, width }) arrives at the end of a gesture and on every step of the keyboard; a width of 0 means a return to automatic layout. A column does not become narrower than 48px — even the sort arrow stops fitting into it.

The handle names its width from the first render, before any dragging: while the column has no width of its own, the one measured from the header goes into aria-valuenow, and before the measurement the one declared in columns.

The mode switches the fixed layout of the table on. Otherwise the browser recomputes the columns by their content and the width set by the user disappears at the very first update of the data. An interrupted gesture (Esc, the loss of the pointer) returns the width that was there before the press.

The pinned: 'left' | 'right' of a column presses it against the edge during horizontal scrolling. The offsets inside a group are computed from the measured widths of the neighbours, so a column does not have to have a width; the recomputation runs on a change of the data and on ResizeObserver.

Three rules worth knowing before they surprise you:

• pinned columns always stand as a group at their edge — the order inside a group is the user’s, but a column cannot be moved from group to group, otherwise “pinned to the left” would stop meaning “on the left”;
• the selection column is pinned together with the left group — otherwise the checkbox would travel away from under a row that stayed in place;
• a pinned cell has an opaque background (otherwise what is moving underneath shows through it), so it repeats the highlight of a selected row itself.

Pinning is set by the user

pinnable-columns adds to the heading of every column a menu “pin left / right / unpin”, and v-model:pinned-columns holds the choice by column key. Without the prop pinned remains what it was — a declaration in the config that is changed only by code.

The menu items are menuitemradio with checked, not three commands: pinning is a choice of one of three positions, and in that form the screen reader names the current one itself. The menu stands on GrDropdownMenu, so the keyboard, the layer stack and the return of focus arrive ready-made.

null in the model means “unpinned”, not “as in the config”: without that distinction there would be nothing to remove a pinning declared on a column with — the absence of a key is precisely what means “the config decides”.

The choice also moves the column: the groups at the edges are the rule above, and a column from the middle, pinned to the left, travels to the beginning.

cell-navigation switches on the grid pattern from WAI-ARIA: the table gets role="grid", occupies one Tab stop, and the arrows lead inside.

The header is a grid row like any other: from it, going down lands in the first data row. The ring is not closed: the row below the last one is not the first one but “nowhere further”.

A separate prop, not the default behaviour. The grid takes Tab for itself, and for everyone who has already put the table in, the tab order would be rearranged.

The controls inside the cells leave the tab sequence — sorting, the reorder and width handles, the column menu, the checkbox, the expand button. Otherwise there would be as many stops as controls, that is, the pattern would not be fulfilled at all: they are reached by arrowing to the cell and Enter. For this GrCheckbox has a tabindex prop — it holds its stop as a literal, and there is no other way to remove it from outside.

It works with virtualisation. The set of cells is the rendered window, not the whole table: with ten thousand rows by six columns there would be sixty thousand keys. A step past the edge of the window scrolls the list and brings the focus to the row that appeared.

expandable adds a service column with a button; under the row the #detail slot unfolds.

<GrDataTable :rows="rows" :columns="columns" expandable v-model:expanded-keys="open">
  <template #detail="{ row }">
    <OrderLines :order-id="row.id" />
  </template>
</GrDataTable>

Expanding is done by the button, not a click on the row: a click on the row is already taken by rowClick and selection, and expanding on it would take navigation away from the consumer. The button stops propagation, so expanding does not select the row.

The column stands before the selection column: expanding relates to the whole row, and selection to its data.

The state is held by row key, not by index: sorting does not confuse the expanded row. accordion leaves one expanded.

A button of your own instead of the service column

expand-column="false" removes the column with the button; expanding is then driven by the consumer’s markup. The cell slots receive expanded and toggleExpand, so the button is put into your own actions column next to the others:

<GrDataTable :rows="rows" :columns="columns" expandable :expand-column="false">
  <template #cell-actions="{ expanded, toggleExpand }">
    <GrButton size="xs" :aria-expanded="expanded" @click="toggleExpand">
      {{ expanded ? 'Collapse' : 'Details' }}
    </GrButton>
  </template>
</GrDataTable>

aria-expanded in this mode lands on your button: the component has none of its own, and there is nothing for it to hang the state on. The link to the id of the details row through aria-controls also remains yours.

Loading on demand

loadDetail switches on loading at the moment of expanding:

<GrDataTable :load-detail="(row, signal) => api.order(row.id, { signal })" expandable>
  <template #detail="{ data }">{{ data.total }}</template>
</GrDataTable>

The second argument is an AbortSignal, and passing it into the request is mandatory: a row is collapsed more often than the response is waited for, and a collapsed row cancels its request. A response that started earlier and arrived later loses to the latest one.

The states arrive in the slot: state — idle | loading | ready | error, data — the result. Loading and failure have default markup (a skeleton and a retry button); it is overridden by the #detail-loading and #detail-error slots.

A skeleton rather than a spinner, deliberately: expanding has already shifted the height of the table, and a second change a moment later would read as jitter.

What has been loaded is kept while the row is alive: collapse and expand again — there is no request. A change of the identity of the rows array resets the cache (a mutation in place keeps it), and pointwise it is reset by invalidateDetail(key?) from the imperative API.

Together with virtual

It works: the row and its second tier lie in one row group, and the measurement of the virtualiser hangs on the group. On the row itself it would not see the height of the details — the spacer would be computed without it, and the list would drift silently.

There is nothing else in a table to wrap two <tr> in: a row group is the only container that exists for them. That is why the body of the table here is assembled in groups of one row each (rowGroups of GrTable) rather than a single <tbody> for everything. Several groups in a table are valid and change nothing for a screen reader: the row number comes from aria-rowindex, not from the position in the markup.

A side benefit: the ResizeObserver of the virtualiser watches the same group, so expanding and loading the details refine the height by themselves — there is no need to report them separately.

Accessibility

The button carries aria-expanded and aria-controls onto the details row; expanding and the end of loading are announced into the live region. The details row is not a row of the set: it does not get aria-rowindex, and aria-rowcount is counted by rows.

There is no grouping of rows and no editing of cells — that is a different class of table.