Virtualizer

A box that scrolls a long collection, such as thousands of rows, and renders only the rows in view.

<script>
  import Tree from '@brumate/ui/Tree.brm';
  import TreeItem from '@brumate/ui/TreeItem.brm';
  import Virtualizer from '@brumate/ui/Virtualizer.brm';

  interface File {
    id: string;
    name: string;
  }
  const files: File[] = Array.from({ length: 5000 }, (_, index) => ({
    id: `file-${index}`,
    name: `Photo ${String(index + 1).padStart(4, '0')}.jpg`,
  }));
</script>

<Virtualizer class="ui-virtualizer" rowHeight=(32)>
  <Tree class="ui-tree" aria-label="5000 photos" items=files item=file />
</Virtualizer>

#template file(file: File) {
  <TreeItem class="ui-treerow" textValue=(file.name)>{file.name}</TreeItem>
}

<Virtualizer rowHeight=(32) style="height: 300px">
  <Tree aria-label="Photos" items=files item=file />
</Virtualizer>

• A Virtualizer is a box that scrolls. Give it a height. rowHeight is the height of a row in pixels, 32 by default.
• A Tree in it renders only the rows in view, as the user scrolls. A Tree takes rowHeight itself too, in a box of your own that scrolls.
• The server renders the first rows, with spacers for the height of the rest, so the page has its height before its code loads.
• A row that leaves the view keeps its state while it is in the list.

Other collections

A GridList, a ListBox or a Table takes items, as a Tree does, and renders only the rows in view when it is in a Virtualizer:

<Virtualizer rowHeight=(32) style="height: 300px">
  <ListBox aria-label="Files" items=files item=file getTextValue=((file) => file.name) />
</Virtualizer>

A Table takes items and getTextValue, and its TableBody takes item. Their keys read the data, as the keyboard section says.

Rows that you write out or render from a #for of your own have no data to read. Give the #for window(height), and it renders only the rows in view, in the box that scrolls:

<Virtualizer style="height: 300px">
  <Table aria-label="Files">
    <TableHeader>…</TableHeader>
    <TableBody>
      #for (file of files by file.id) window(32) {
        <Row id=(file.id)>…</Row>
      }
    </TableBody>
  </Table>
</Virtualizer>

See windowed lists for how it renders.

Keyboard

• In a Tree, and in a GridList, a ListBox or a Table that has items, the keys read the data of all the rows, not only those that render. Home, End, PageUp and PageDown, Ctrl+A, a range with Shift, and letters reach rows that are out of view. In a Tree, Left reaches the row that holds a row. A move to a row that is not rendered scrolls it into view, then focuses it.
• In a Table, the box in the header selects every row that can be selected, also those that are not rendered.
• Letters match the text of a row that renders, and for the others the text that getTextValue returns for the item, such as getTextValue=((file) => file.name). Without it, letters match the rows in view only.
• The Tree has aria-rowcount with the count of all its rows, and each row aria-rowindex, since not all the rows are in the page. The other collections do not have them yet.
• A ListBox windows a vertical list that no field filters, so a ListBox in a ComboBox renders all its items. A GridList windowed with onReorder drags only between the rows that render.
• The rows of a collection that has no items move between the rows that are rendered. A move to the edge of the view scrolls it, and the rows that come into view render, so Up and Down go through the whole list. Home and End go to the first and the last row that are rendered.