List View API Reference

API reference › The list view module

All 29 pages Everything on one page → Developer guide →

The list view module

modules/listview is an opt-in, standalone list: selection, drag-and-drop reorder and transfer between lists, and a data API, over one column of a real Lattice grid. House rule: a module's list or table is a real grid - createList configures the page's own createGrid (injected, never bundled, so the list shares the page's one licensed core) with no header, no grid lines, one row per item, the row's cell drawn by your own template. Virtual scrolling, keyboard navigation, ARIA and row drag all come from the grid underneath for nothing - this module is wiring, not a second implementation of any of them.

import { createList } from '@toclocoinc/lattice-grid/modules/listview';

const list = createList(document.querySelector('#list'), {
  createGrid,                     // the page's own grid factory (injected, never bundled)
  data: [{ id: 1, name: 'Ada' }, { id: 2, name: 'Grace' }],
  template: (item) => `<div class="row">${item.name}</div>`,
  selection: 'multi',
  dragMode: 'both',
});

Drag and drop is two already-shipped grid primitives, wired, not rebuilt. dragMode maps onto the inner grid's own rowReorder (the handle, and reorder within one list) and rowTransfer (rows crossing between two grid instances): 'source' only sends, 'target' only receives, 'both' does either, and false (the default) does neither. Neither list needs a shared group to interact - any two lists on a page already match - so moving or copying (dragCopy: true) between two listview instances needs no pairing registry of its own. A target's beforeDrop handler may veto a drop by returning false (or a Promise of it): the same veto-before-mutation gate the grid's own rowTransfer uses guarantees a veto leaves both lists exactly as they were, and afterDrop fires only once a move or copy has actually committed. A drag that leaves a list without landing on another fires dragOut.

The Data API never drifts from what is on screen. list.data drives every mutation through the inner grid's own keyed-diff, sort and filter surface, so serialize() - the items in current on-screen order - can never disagree with what is actually painted, and filter(fn) hides items without removing them from the store (call with no arguments to clear it). list.selection is driven through the same inner grid's own selection model, so a click, a keypress and a direct API call all agree; in 'single' mode getId() is the selected id or null, and in 'multi' mode it is always an array. An input or change event fired by a control inside a row's own template bubbles out through list.on carrying that row's item id, so a host never has to walk the DOM to know which item a field belongs to.

Row size, controls in templates and where a drag starts. The single item column fills the list's width and follows host resizes, so a template's block content spans the row. itemHeight is a number of pixels, or 'auto': every row is then sized to its template with the grid's own auto row height (multi-line content is shown in full, it measures at any list length, and a row whose item changes through data.update is measured again). An HTML-string template is sanitised by the grid, which drops form controls; with allowUnsafeTemplates: true it keeps input, select, textarea, button and label elements and their attributes, while script elements, event-handler attributes and javascript: URLs are still removed. Typing or clicking in such a control reaches list.on('input' | 'change') with the item id, and a click on a link, button, input, select, textarea or label does not also select the row unless the control (or an ancestor) carries data-row-select. dragHandle is 'grip' (the default, the drawn handle) or 'row', which also starts a drag from anywhere on the row except on those controls or an element marked data-no-drag; a double-click still selects a word. A row moved to another list leaves the source completely - its rows, paint, order and selection - and a copy leaves the source untouched.

The data API, selection and config knobs, executed

Three items seeded, an insert, a patch, a field sort, a filter that hides without losing anything, selection add/remove/clear, a removal and a full clear - run headless on every build with the suite's own DOM test double, since this module always needs a real element and an injected grid.

const { createTestDom, flushFrames } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid } = await import('../packages/dom/src/index.js');
const { createList } = await import('../packages/modules/listview/index.js');

const seen = [];
const host = createTestDom().root;
const list = createList(host, {
  createGrid,
  data: [{ id: 1, name: 'Ada', done: false }, { id: 2, name: 'Grace', done: true }, { id: 3, name: 'Linus', done: false }],
  key: 'id',
  template: (item) => `<div class="row">${item.name}</div>`,
  itemHeight: 40,
  css: 'demo-row',
  selection: 'multi',
  dragMode: 'both',
  dragCopy: false,
  dragHandle: 'row',
  emptyText: 'No items',
});
list.on('selectionChange', (e) => seen.push(`sel:${e.ids.join(',')}`));
list.on('afterDrop', (e) => seen.push('afterDrop'));

const initial = list.data.serialize().map((i) => i.name).join(',');     // Ada,Grace,Linus
list.data.add({ id: 4, name: 'Margaret', done: false }, 1);
const afterAdd = list.data.serialize().map((i) => i.id).join(',');       // 1,4,2,3
list.data.update(2, { name: 'Grace H.' });
const updated = list.data.getItem(2).name;                               // Grace H.
list.data.sort('name');
const sorted = list.data.serialize().map((i) => i.id).join(',');
list.data.filter((item) => item.done === false);
const filteredCount = list.data.serialize().length;
const totalCount = list.data.getLength();
list.data.filter();
list.data.sort();
const restored = list.data.serialize().map((i) => i.id).join(',');       // 1,4,2,3
const indexOf4 = list.data.getIndex(4);
list.selection.add([1, 4]);
const selected = list.selection.getId().join(',');
list.selection.remove(1);
const afterRemove = list.selection.getId().join(',');
list.selection.clear();
const cleared = list.selection.getId().join(',') || 'none';
list.data.remove(3);
const afterDelete = list.data.serialize().map((i) => i.id).join(',');
list.data.removeAll();
const empty = list.data.getLength();
const events = seen.join('|');
list.destroy();
return [initial, afterAdd, updated, sorted, filteredCount, totalCount, restored, indexOf4, selected, afterRemove, cleared, afterDelete, empty, events].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 list view module

ListViewConfig

The configuration for {@link createList}. `createGrid` is the page's own grid factory, injected so the list shares the page's one licensed core - `createList` wraps it as a one-column, headerless, borderless grid, one row per item, the cell drawn by `template`.

ListViewDataApi

`list.data`: the Data API. Every method runs through the inner grid's own keyed-diff/sort/filter surface, so {@link serialize} never drifts from what is on screen.

ListViewSelectionApi

`list.selection`: the selection API, driven through the inner grid's own selection model.

ListViewItemEvent

The payload `itemClick`/`itemDoubleClick` carry.

ListViewBeforeDropEvent

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

ListViewAfterDropEvent

The `afterDrop` payload: a move or copy between two lists (or a reorder within one) committed.

ListViewDragOutEvent

The `dragOut` payload: a drag left this list without a cross-list drop landing.

ListViewSelectionChangeEvent

The `selectionChange` payload: always an array, regardless of `ListViewConfig.selection` mode.

ListViewTemplateEvent

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

ListViewItemContextMenuEvent

The `itemContextMenu` payload: a right-click on a row (and the context-menu key on a focused one).

ListViewEventPayloads

The payload each list event name carries.

ListView

The list instance {@link createList} 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.