Data View API Reference

API reference › The data view module

All 29 pages Everything on one page → Developer guide →

The data view module

modules/dataview is the list view's card-grid sibling: items laid out as cards that wrap into rows, each card drawn by your own template. A person selects cards (single and multi), moves through them with the arrow keys in two dimensions, and drags a card to a new position; a drop indicator shows where it lands. It builds on nothing but the DOM - there is no grid factory to inject - and draws only the rows of cards in (or just beyond) the viewport, so 5,000 items cost the same as a screenful.

import { createDataView } from '@toclocoinc/lattice-grid/modules/dataview';

const view = createDataView(document.querySelector('#cards'), {   // give the host a height
  data: [{ id: 1, name: 'Ada' }, { id: 2, name: 'Grace' }],
  template: (item) => `<h4>${item.name}</h4>`,
  itemWidth: 180, itemHeight: 96, gap: 12,    // or columns: 4 to fill the width
  selection: 'multi',
  dragMode: 'both',
});

Layout. Cards are itemWidth by itemHeight (default 200 by 120) with gap (default 8) between them, and as many as fit go on a row. Set columns: n instead and exactly n cards share the width, so the row is always full; itemWidth is then ignored. The view resizes with its host. Give the host element a height - the view fills it and scrolls inside it.

The list view's API, reused. view.data, view.selection and the event names are the list view's, and live in one shared file both modules import, so serialize(), filter(), sort() and the rest mean the same thing on both and always read back what is on screen. A returned template string goes through the same sanitiser the grid applies to template output; a returned element is used as it is.

Keyboard and pointer. A click selects a card; the platform modifier (Cmd on macOS, Ctrl elsewhere) toggles one into a 'multi' selection and Shift extends a range. One card is in the tab order; the arrow keys move between cards in two dimensions (Left and Right wrap across rows, Up and Down keep the column), Home and End go to the ends of a row (with the platform modifier, of the whole set), PageUp and PageDown move a screenful, Space toggles, Enter activates (itemDoubleClick) and Shift with an arrow extends the selection. In 'single' mode the selection follows the focus.

Drag and drop. dragMode is the list view's: 'source' lets a card be picked up (reordering within the view, or sending it to another), 'target' receives, 'both' does either and false (the default) neither; dragCopy: true leaves the source card behind. A card dropped before the card whose left half the pointer is in lands there; afterDrop reports the new order and serialize() already matches the screen. A drag between two data views, or to and from a listview list, goes through the target's single beforeDrop: return false (or a Promise of it) and both sides are left exactly as they were. A reorder within one view is refused, with the reason announced, while a sort or filter is active, because the drop position would have no single meaning in the stored order.

Accessibility. The view is an ARIA grid of rows of gridcell cards with aria-rowcount, aria-colcount, aria-rowindex and aria-colindex, and aria-selected when selection is on. With no items it shows emptyText (default “No items”).

Layout, the data API and selection, executed

Cards per row from a width and from a column count, five items seeded, an insert, a patch, a sort, a filter that hides without losing anything, selection, and the redrawn cards in the same order as serialize() - run headless on every build with the suite's own DOM test double.

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { createDataView } = await import('../packages/modules/dataview/index.js');
const { computeColumns } = await import('../packages/modules/dataview/layout.js');

const fit = computeColumns({ width: 640, itemWidth: 100, gap: 10 }).columns;   // 5 cards of 100 and 4 gaps of 10 = 540
const filled = computeColumns({ width: 640, columns: 4, gap: 10 }).cardWidth;   // (640 - 3 * 10) / 4

const seen = [];
const host = createTestDom().root;
const view = createDataView(host, {
  data: [{ id: 1, name: 'Ada' }, { id: 2, name: 'Grace' }, { id: 3, name: 'Linus' }],
  key: 'id',
  template: (item) => `<h4>${item.name}</h4>`,
  itemWidth: 100,
  itemHeight: 60,
  columns: 2,
  gap: 10,
  css: 'person',
  selection: 'multi',
  dragMode: 'both',
  dragCopy: false,
  emptyText: 'No people',
});
view.on('selectionChange', (e) => seen.push(`sel:${e.ids.join(',')}`));

view.data.add({ id: 4, name: 'Margaret' }, 1);
view.data.update(2, { name: 'Grace H.' });
const added = view.data.serialize().map((i) => i.id).join(',');
view.data.sort('name', 'desc');
const sorted = view.data.serialize().map((i) => i.id).join(',');
view.data.filter((item) => item.name.length < 6);
const shown = `${view.data.serialize().length}/${view.data.getLength()}`;
view.data.filter();
view.data.sort();
view.selection.add([1, 3]);
view.selection.remove(1);
const selected = view.selection.getId().join(',');
view.selection.clear();
await Promise.resolve();                                                     // the cards redraw once, after a burst of changes
const cards = [...host.querySelectorAll('.lat-dv-card.person')]
  .sort((a, b) => a.getAttribute('data-index') - b.getAttribute('data-index'))
  .map((c) => c.getAttribute('data-key')).join(',');
const rows = host.querySelector('[role="grid"]').getAttribute('aria-rowcount');
view.destroy();
return [fit, filled, added, sorted, shown, selected, cards, rows, seen.join('|')].join(' || ');

Type reference

Generated from the type declarations, so it always matches the release. Each surface lists its properties, its methods and the events it raises as three tables; an option or value type lists its members once.

The data view module

DataViewConfig

The configuration for {@link createDataView}: items laid out as cards that wrap into rows, each card drawn by `template`. Cards are `itemWidth` wide and as many as fit go on a row, or `columns` of them share the width.

DataViewDataApi

`view.data`: the list view's Data API, over the view's own items. `serialize()` is always the order on screen.

DataViewSelectionApi

`view.selection`: the list view's selection API, over the view's own selection.

DataViewItemEvent

The payload `itemClick`/`itemDoubleClick` carry.

DataViewBeforeDropEvent

The cancellable `beforeDrop` payload: return `false` (or a Promise of it) to veto, leaving both views unchanged.

DataViewAfterDropEvent

The `afterDrop` payload: a move or copy between two views, or a reorder within one, committed.

DataViewDragOutEvent

The `dragOut` payload: a drag moved out of this view.

DataViewSelectionChangeEvent

The `selectionChange` payload: always an array, whatever the selection mode.

DataViewTemplateEvent

The `input`/`change` payload: an event bubbled from inside a card's template, carrying the item's identity.

DataViewEventPayloads

The payload each data view event name carries.

DataView

The instance {@link createDataView} returns.

Properties

Methods

Events

This surface raises events, but the names are not declared: on() accepts any string. They cannot be listed here until the declaration names them.