@norconsult-digital-public/isypixel 2.0.2 → 2.0.4-canary.1

package/dist/docs/web-components/ip-exp-data-grid/llm.md

@@ -0,0 +1,598 @@
+# ip-exp-data-grid
+
+Virtualised data grid over rows the application supplies.
+
+The grid never fetches anything. You hand it rows, it indexes the fields your `ip-exp-data-grid-column`
+children declare, and it answers queries against that index. Row heights and column widths are
+numbers, never measured from content, which is what keeps rows from jumping as data arrives.
+
+Nothing is written to disk. The index lives in memory for as long as the page does.
+
+> Not finished. Import it from `@norconsult-digital-public/isypixel/experimental/web-components`; the API may change
+> without a major version.
+
+## Attributes
+
+| Name                  | Type      | Default  | Allowed values               | Description                                                                                                                                |
+| --------------------- | --------- | -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `row-height`          | `number`  | `36`     | any positive px              | Height of every row. Fixed, so scroll position is arithmetic rather than measurement.                                                      |
+| `cell-lines`          | `number`  | `1`      | any positive count           | Lines of text a cell may show before the rest is cut off. Rows grow to fit; one line keeps the ellipsis. The settings panel offers 1 to 5. |
+| `plain-text`          | `boolean` | `false`  | –                            | Shows only the value in each cell, ignoring the template a column declares. Brings search highlighting back.                               |
+| `header-height`       | `number`  | `0`      | any positive px              | Height of the header row. Zero follows the row height.                                                                                     |
+| `visible-rows`        | `number`  | `0`      | any positive count           | Rows to size the viewport for. `0` makes the grid fill its container, which needs a height.                                                |
+| `dataset-id`          | `string`  | `''`     | any id                       | Shares one index between views. Two elements with the same id read the same index.                                                         |
+| `zebra`               | `boolean` | `false`  | –                            | Alternating row backgrounds.                                                                                                               |
+| `row-lines`           | `boolean` | `true`   | –                            | Separator line under each row.                                                                                                             |
+| `column-lines`        | `boolean` | `true`   | –                            | Separator line between columns.                                                                                                            |
+| `row-numbers`         | `boolean` | `false`  | –                            | Shows the position of each row in the current order.                                                                                       |
+| `lock-first-column`   | `boolean` | `false`  | –                            | Keeps the leftmost column in place while the grid scrolls sideways.                                                                        |
+| `selection`           | `string`  | `'none'` | `none`, `single`, `multiple` | Whether rows can be picked, and how many at a time. Adds a column of boxes on the left.                                                    |
+| `resizable-columns`   | `boolean` | `false`  | –                            | Adds a grip on each column edge for dragging, keyboard resizing and autofit.                                                               |
+| `reorderable-columns` | `boolean` | `false`  | –                            | Lets the user drag a heading to move the column, or move it with Ctrl and an arrow key.                                                    |
+| `remember-state`      | `boolean` | `true`   | –                            | Remembers the setup in sessionStorage, per tab. Needs a `state-key` or a `dataset-id`; without one nothing is stored.                      |
+| `state-key`           | `string`  | `''`     | any key                      | Key the setup is stored under. Falls back to `dataset-id`.                                                                                 |
+| `group-by`            | `string`  | `''`     | comma-separated              | Fields to group by, outermost first. Only declared columns can be grouped on.                                                              |
+| `groups-expanded`     | `boolean` | `false`  | –                            | Whether groups start open. Closed by default, so a grouped table opens as an overview.                                                     |
+| `group-panel`         | `boolean` | `false`  | –                            | Shows a zone above the header where columns can be dropped to group by them.                                                               |
+| `aggregate-menu`      | `boolean` | `false`  | –                            | Lets the user right-click a heading to choose which figures the column shows.                                                              |
+| `view`                | `string`  | `table`  | `table`, `cards`, `auto`     | Draws the rows as a table or as cards. Needs an `ip-exp-data-grid-card` child to show cards at all.                                        |
+| `actions-menu`        | `boolean` | `false`  | –                            | A column at the right edge whose heading holds the list's commands: columns, settings, Excel export, setup files, reset.                   |
+| `search`              | `string`  | `''`     | any text or expression       | Searched for across every indexed column. Takes the same expressions a filter field does.                                                  |
+| `search-box`          | `boolean` | `false`  | –                            | Shows the grid's own search box above the header.                                                                                          |
+| `filter-row`          | `boolean` | `false`  | –                            | Shows a row of filter fields under the headings, one per column.                                                                           |
+| `value-list`          | `boolean` | `false`  | –                            | Gives each heading a button that opens the column's distinct values to pick from.                                                          |
+| `highlight-matches`   | `boolean` | `true`   | –                            | Marks the matched text inside the cells. Off leaves the values as they read.                                                               |
+
+## Properties
+
+Set from JavaScript. An array of objects cannot be an attribute.
+
+| Name         | Type                          | Default | Description                                                                                                                  |
+| ------------ | ----------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `rows`       | `readonly object[]`           | `[]`    | The rows to show. The application fetches them; the grid indexes them. Any object array, including your own typed interface. |
+| `groupBy`    | `string \| readonly string[]` | `''`    | Fields to group by. The array form for JavaScript, the comma-separated attribute for markup.                                 |
+| `filterRows` | `readonly BuilderRow[]`       | `[]`    | Everything filtering the table, as one list. Bind it to share the filter with an `ip-exp-filter-builder` or a card view.     |
+| `selected`   | `readonly number[]`           | `[]`    | The picked rows, as indexes into `rows`. Two-way: set it to pick from outside, read it after `ipRowSelectionChange`.         |
+
+## Slots
+
+| Name    | Description                                                                                                                                                        |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| default | `ip-exp-data-grid-column`, `ip-exp-data-grid-column-group`, `ip-exp-data-grid-card` and `ip-exp-data-grid-action` elements. Read as configuration, never rendered. |
+| `empty` | Shown instead of rows when there are none. A message, an illustration, a button to add data.                                                                       |
+
+## Events
+
+| Name                   | Payload                                                 | Description                                                                  |
+| ---------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `ipSortChange`         | `{ field: string; direction: 'asc' \| 'desc' } \| null` | The user sorted by a column. `null` when the sort was cleared again.         |
+| `ipSetupChange`        | `GridSetup`                                             | The setup changed. Store this as "my setup"; see Saved setups below.         |
+| `ipSearchChange`       | `{ query: string; matches: number }`                    | The search text changed, with the rows left after it.                        |
+| `ipFilterChange`       | `{ filter: FilterNode \| null; rows: BuilderRow[] }`    | The filter changed, whichever surface changed it.                            |
+| `ipRowSelectionChange` | `{ rows: number[] }`                                    | The picked rows changed, as indexes into `rows`.                             |
+| `ipSettingsChange`     | `GridSettings`                                          | The user changed a display setting in the settings panel.                    |
+| `ipRowAction`          | `{ name: string; row: number; data: object }`           | A row action button was pressed. `row` indexes the rows the grid was handed. |
+
+## Methods
+
+| Name                    | Description                                                                             |
+| ----------------------- | --------------------------------------------------------------------------------------- |
+| `getSetup()`            | The whole setup as JSON: column order, widths, sort and grouping.                       |
+| `applySetup(setup)`     | Applies a setup, given either as an object or as JSON text. Unknown fields are ignored. |
+| `resetSetup()`          | Returns to what the markup declares.                                                    |
+| `expandAllGroups(open)` | Opens or closes every group at once.                                                    |
+
+## Behaviour
+
+**Index scope.** Only the fields declared as columns are indexed. Index cost scales with fields
+times rows and field count dominates, so a wide row indexed in full costs several times what the
+displayed columns cost. Nothing outside the declared columns can be sorted.
+
+**Indexing is sliced.** A large dataset is indexed in slices of a few milliseconds so the page never
+freezes. While that runs the grid shows a skeleton and reports `aria-busy="true"`. A small dataset
+finishes within the first slice, so no skeleton flashes.
+
+**Sorting permutes indices.** Rows are never moved. A numeric column sorts as numbers, so 9 comes
+before 10, and empty cells go last in both directions because an empty cell is the absence of a
+value rather than a small one. Clicking a header cycles ascending, descending, and back to the order
+the rows arrived in. The collation locale comes from `PixelLocaleService`.
+
+**Arranging columns.** With `resizable-columns`, each column gets a grip on its trailing edge:
+drag it, or focus it and use the arrow keys, or double-click it to fit the column to the values
+currently on screen. That autofit is the only place a width comes from content, and only because the
+user asked for it. With `reorderable-columns`, a heading can be dragged, or moved with Ctrl and an
+arrow key while the heading is focused. A heading that can be moved shows the grab cursor, and the
+closed-hand cursor while it is being dragged.
+
+**Grouping.** `group-by` names the fields to group on, outermost first. Each group becomes one line in
+the same virtualised list as the rows, so a grouped table of a hundred thousand rows costs no more to
+render than a flat one. Opening a group keeps the view where it is, because it is the same list with
+more of it showing; a new sort or a new grouping starts from the top, because it is a different list.
+Only declared columns can be grouped on, since nothing else is indexed.
+
+**The grouping zone.** With `group-panel`, a dashed zone appears above the header. Drag a heading
+onto it to group by that column, or hold Ctrl and press G while a groupable heading has focus. Only
+columns declared `groupable` are accepted, and the zone lights up while one is in the air so the
+target is visible before the drop.
+
+Each level is an `ip-chip`, and their order is the grouping order, outermost first. Drag one chip onto
+another to change that order, or hold Ctrl and press an arrow key with a chip focused, the same keys
+that move a column in the header. The level number is not printed on the chip, because the order says
+it; it stays in the chip's accessible name, where a user who cannot see the order still needs it.
+The chip's remove button drops that level, and removing the last one ungroups the table.
+
+Once grouping has been taken over this way, or by `applySetup`, an empty grouping means no grouping
+rather than a fall back to the `group-by` attribute. Changing that attribute takes grouping back.
+
+**Figures.** A column with an `aggregate` shows that figure in the summary row and in every group
+header, aligned under the column it belongs to. The summary row covers the whole result and sits
+sticky at the bottom of the same scroll container as the columns, which is what stops the grid from
+growing a second horizontal scrollbar. Group figures are worked out for the headers actually on
+screen, so a table with thousands of groups does no work nobody sees.
+
+The summary row also reports how many rows are left after the search and the filters. With
+`row-numbers` the count sits in the row number column, under the numbers it totals; without it, the
+count leads the first column's cell, labelled the way the other figures are.
+
+**Choosing figures.** With `aggregate-menu`, right-clicking a heading opens a menu with sum, average,
+smallest, largest and count. Several can be on at once for one column: they stack under each other,
+in the summary row and in every group header, and both grow to fit them. A grouped list is then two
+line heights rather than one, which the scroll position accounts for. What the user picks replaces what the
+column declared, and turning them all off is a choice the setup remembers. The context menu key opens
+the same menu, since that is what a browser turns into a right-click for whatever has focus.
+
+**The command menu.** `actions-menu` gives the grid a column of its own at the right edge, stuck
+there while the table scrolls sideways. Its heading holds a menu of the commands that belong to the
+list rather than to a column: the column picker, the settings, saving the setup to a file, loading
+one back, and a reset that puts the whole arrangement back to what the markup declared.
+
+A real column rather than a button floating over the header, because anything focusable inside
+`role="grid"` has to be a real cell in a real row.
+
+**Row actions.** The cells under that heading hold one button per `ip-exp-data-grid-action` child, and
+`ipRowAction` reports which was pressed on which row. The column grows to fit them. Without any such
+child the cells stay empty and the column is only as wide as the command menu. See
+`ip-exp-data-grid-action` for the whole of it.
+
+**Cell templates.** A column may declare a `<template>` saying what its cells draw, with `[[field]]`
+standing in for a value from the row. It is parsed once and built per visible row as virtual DOM, so
+it costs the twenty rows on screen rather than the five hundred thousand behind them. See
+`ip-exp-data-grid-column` for the whole of it, including why the CSS has to travel inside the template.
+
+Only put trusted fields, or fields with a fixed set of values, into a `style` attribute. Never put free
+text from the data there.
+
+**Plain text mode.** `plain-text` turns every template off and shows the value instead. The densest
+reading of the table, and the only one where a search marks what it matched: a template decides its
+own content, so the grid cannot reach inside it to wrap a run of text. It leaves the action column,
+the row numbers and the tick boxes alone.
+
+**Lines per cell.** `cell-lines` lets a cell show more than one line. The settings panel offers one to five. The rows grow to
+fit the count rather than the text, so a row height is still a number the component works out and
+scroll position is still arithmetic: five hundred thousand rows cost the same to scroll at five lines
+as at one. One line keeps the cheaper ellipsis.
+
+There is deliberately no "as many as it takes". That would mean measuring every cell, which is the
+one thing this grid does not do, and is why rows never jump as data arrives.
+
+**Export to Excel.** The menu writes what is on screen out as a real `.xlsx`: the visible columns,
+in their current order, and the rows left after the search and the filters, in the sorted order. A
+second command writes only the picked rows, and is off until some are. Values that read as plain
+numbers are written as numbers so Excel can sum them; everything else goes in as text.
+
+No spreadsheet library is involved. An `.xlsx` is a ZIP holding five small XML documents, and
+`src/utils/zip.ts` and `src/utils/xlsx.ts` write both. Entries are deflated through
+`CompressionStream` where the platform has it and stored uncompressed where it does not, which are
+both valid ZIP.
+
+**A setup as a file.** Save writes `GridSetup` out as JSON named after `state-key` or `dataset-id`,
+for the user to keep or send to a colleague. Load reads one back through `applySetup`, which
+validates it field by field, so a file that is not a setup changes nothing and fields the grid does
+not have are ignored.
+
+The grid produces the file itself rather than only the JSON, because the command is in its own menu
+and a menu item that needs the application to implement it before it does anything is a dead item.
+An application that would rather keep setups on a server has `getSetup` and `ipSetupChange`.
+
+**The column picker** turns declared columns off and on. A hidden field keeps its place in the order
+and its width, so turning it back on puts it where it was rather than at the end. The last visible
+column cannot be turned off, since nothing would be left to turn it back on from. What is hidden
+travels in `GridSetup.hidden`, so it survives a reload with `remember-state` and moves with a shared
+setup.
+
+A column declared with the native `hidden` attribute starts turned off, so a list can offer more
+columns than it shows. Until the user picks something, `GridSetup.hidden` is `null` and the declared
+ones are hidden; Reset list goes back to that. Being the native boolean attribute, `hidden="false"`
+still hides: leave the attribute out, or bind the property (`[hidden]` in Angular).
+
+Hiding is separate from a closed column group. A group closing down to one column is a temporary
+narrowing of a band; the picker is the user saying they do not want the column at all.
+
+**The settings panel** changes how the table looks, in six groups: row height, lines per cell, style
+and appearance (alternating backgrounds, row and column lines, row numbers, a locked first column),
+filter and search (header filters, grouping, the filter row, the search box, remembering filters),
+whether rows can be picked, and, where a card layout is declared, whether the rows are drawn as a
+table or as cards.
+
+Every row says what it does and which way the component ships, so a user can find their way back
+to a default without pressing the button that resets all of them. A button in the heading lays the
+groups out in one column instead of two, for a narrow window.
+
+Nothing applies until **Save**. A settings panel is a form, so the table stays still while the
+user is deciding, and closing it leaves things exactly as they were found. **Restore defaults**
+puts the panel back to what the component ships with, still without applying it. Save writes every
+setting onto the element, so a framework binding sees the new values, and `ipSettingsChange` carries
+the lot.
+
+These are preferences about how a list should look, not how this list is arranged, so they are
+**not** part of `GridSetup` and the grid does not store them. An application that wants them to
+follow the user has to keep them itself.
+
+**Cards.** `view` draws the rows as cards instead of rows: `cards` always, `auto` when the columns
+would not fit the width, `table` never. An `ip-exp-data-grid-card` child says which field goes in which
+part of the card; without one the grid stays a table whatever `view` says.
+
+It is the same grid either way. The search, the filters, the sort, the grouping and the picked rows
+all carry across the switch, because only the drawing changes. Group headings look and behave the
+same as in the table, and the picking boxes move onto the cards.
+
+You set no card height. The grid measures the first card and holds every other one to it, which is
+safe in a way measuring a table row would not be: every card holds the same roles clipped to the
+same number of lines, so one measurement describes all of them and scrolling stays arithmetic.
+
+Cards have no columns, so the command menu moves from the action column into a header above the
+list, in the same corner. A filter button sits beside it, opening the filter dialog.
+
+**The filter dialog** holds an `ip-exp-filter-builder` over the declared columns, and the grouping the
+table is arranged by. Columns the index stored as a dictionary have few distinct values and already
+hold them, so those become pickers for nothing; the rest stay text fields. The builder's free-text
+field and the grid's search box are the same search: the dialog opens with what the box holds, and
+applying it writes the field back to `search`.
+
+Grouping sits beside the builder rather than inside it, because `ip-exp-filter-builder` is used on its
+own wherever something needs searching, and there is no grouping to speak of there.
+
+**Picking rows.** `selection` adds a column of boxes on the left, after the row numbers when those are shown.
+`multiple` gives every row a checkbox and the header a Select all that takes everything left after
+the search and the filters, showing partly filled while only some of them are picked. `single` gives
+every row a radio, and picking one gives the previous one back.
+
+Picking is done in that column rather than by clicking anywhere on the row. A click inside a cell
+then still means what the cell says it means, and the keyboard reaches the boxes without the grid
+having to take over the arrow keys.
+
+The picked rows are indexes into `rows`, in `selected` and in `ipRowSelectionChange`. Indexes rather
+than keys, because the grid is never told which field identifies a row, and the consumer already
+holds the array they point into. Setting `rows` clears the selection, since the old indexes point at
+an array that is gone. The selection is deliberately **not** part of `GridSetup`: a setup is stored
+and shared, and indexes restored against different data would pick the wrong rows.
+
+**One filter, four views of it.** The search box, the filter fields, the value lists and an
+`ip-exp-filter-builder` are not four filters that happen to be ANDed together: they are four ways of
+editing one list of conditions the grid owns. Each shows the same condition rather than a description
+of it, so `{ city, is, Oslo }` reads as `=Oslo` in the filter field, as a ticked Oslo in the value
+list, and as an editable row in the builder. Edit it anywhere and the others follow.
+
+`filterRows` is that list, `ipFilterChange` reports every change to it with both the rows and the tree
+they make, and the whole thing travels in the saved setup. Because it is plain data, a card view of the
+same rows can be handed the same filter and pick up where the grid left off.
+
+A filter field edits its whole column at once, and a value list edits that column's `is` conditions
+without touching a `>100` the builder put there.
+
+**Searching.** `search` narrows the whole list to the rows that carry the text in any indexed column,
+so the application can own the input and bind it, or turn on `search-box` and let the grid own one.
+Both write to the same place. `ipSearchChange` reports the text and how many rows are left.
+
+A plain word is answered from the index rather than by reading the rows: a dictionary column is
+searched in its dictionary, so a status column with five distinct values costs five comparisons
+whatever the row count, and text columns are compared as bytes without building a string per cell.
+Typing one more letter narrows the previous answer instead of scanning again.
+
+The box also takes the whole expression language below, so `Tromsø & !Bergen` or `>100 | <10` are
+searches too. An expression is evaluated as a tree rather than through the indexed path; a plain word
+still takes the fast one. A half-typed expression is marked and the last answer stands, rather than
+the table emptying on a stray bracket.
+
+**Column filters.** `filter-row` puts a field under each heading. Each takes an expression over that
+column, not just a word:
+
+| Written        | Means                 |
+| -------------- | --------------------- |
+| `bergen`       | contains "bergen"     |
+| `=AS`          | is exactly "AS"       |
+| `!=AS`         | is anything else      |
+| `^kristian`    | starts with           |
+| `sund$`        | ends with             |
+| `>100`         | greater than          |
+| `10..50`       | between, inclusive    |
+| `a \| b`       | either                |
+| `a & !b`       | one but not the other |
+| `(a \| b) & c` | grouped               |
+
+`&`, `|` and `!` can also be written `and`, `or` and `not`, and a space between two terms means `and`.
+
+**A column of dates gets a calendar instead.** Where a column holds dates, the filter field under its
+heading is an `ip-exp-date-picker` picking a span, and the span becomes the same `>= & <=` run the field
+would have written by hand, so the advanced filter and the value list see an ordinary condition. The
+column works this out from its own values; `type` on `ip-exp-data-grid-column` overrides it either way.
+
+A condition the picker cannot hold sends that cell back to its text field, so a filter built in the
+advanced dialog is always readable where it was made.
+Filters are combined with AND across columns, and the search runs inside what they left, so a narrow
+filter makes the search cheaper as well as narrower.
+
+**A field takes a run of conditions, not any expression at all.** `Oslo | Bergen` and `>10 & <100`
+each become conditions; `(a | b) & !c` is refused and the field says why. That is the price of the
+field and the builder always agreeing about what is set, and anything more involved belongs in the
+builder. Mixing `&` and `|` in one field is refused for the same reason: the parser binds them the way
+boolean algebra does and the builder groups them the way its form draws, so a mixed expression would
+mean two different things in the two places it appears.
+
+A field whose text does not read is marked and left out rather than applied, so the rows keep their
+last answer while the user is still typing rather than emptying out on a stray bracket. The search
+box, which does not have to agree with a form, still takes the whole language.
+
+**Picking values.** `value-list` puts a button in each heading that opens an `ip-exp-value-list` with the
+column's distinct values and a count each. Ticking values narrows the table to any one of them, and
+that combines with the column's filter text rather than replacing it.
+
+The counts are taken over what the _other_ columns have already left, not over the whole table, so a
+list offers what is still worth choosing between. A column's own selection is excluded from its own
+count, or ticking one value would leave the list showing only that value. A column with too many
+distinct values to list says so instead.
+
+**Marking the matches.** `highlight-matches` is on by default and marks the matched runs inside the
+cells, from the search and the column filters alike. A term under a `!` is not marked, because nothing
+in the cell matched it. The plain text is rendered when nothing is being looked for, so a grid drawing
+thousands of cells a second pays nothing for the feature until it is used.
+
+**Column groups.** Wrapping columns in an `ip-exp-data-grid-column-group` draws a shared band above them,
+as a second header row. A `collapsible` band closes down to a single column, the one marked
+`keep-collapsed`, so a quarterly breakdown can fold away to its total. Columns stay inside their group
+when they are reordered, and which groups are closed travels in the saved setup. See the
+`ip-exp-data-grid-column-group` docs.
+
+**Saved setups.** `getSetup()` returns one JSON payload holding the column order, the widths, the sort,
+the grouping, the figures per column, the closed column groups, and `filterRows`, which holds the whole filter,
+whichever surface set each part of it. The rows travel as the text the user typed rather than as a
+parsed tree, because the text is what has to reappear in the field. The search text is not in it: a
+search is where you are looking right now, not
+how the table is arranged. There is nothing machine-specific in it, so it can be stored against a user account
+and handed to someone else as it stands. `applySetup()` takes it back, as an object or as text, and is
+deliberately forgiving: fields this grid no longer has are ignored rather than making the whole setup
+fail, so a setup saved before a column was removed still works, and so does one from a colleague whose
+columns differ slightly. `version` says which shape the payload is in.
+
+Naming setups, keeping a list of them, letting the user pick one and sharing them is the application's
+job: that belongs to accounts, permissions and storage. The grid's part is the payload.
+
+**Storing it in the browser.** `ipSetupChange` carries the whole setup every time it changes, which is
+what an application stores against the signed-in user and hands back through `applySetup()`.
+`remember-state` additionally keeps it in sessionStorage, per tab: useful within a session, and
+deliberately gone when the tab closes, because a setup tied to the machine rather than to an account is
+the wrong thing to leave behind on a shared computer.
+
+Nothing else is written to disk. The index itself never leaves memory.
+
+**Shared index.** Two elements with the same `dataset-id` read one index, and it survives one of
+them unmounting, which is what a route change in a single-page application looks like. Give the rows
+to one of them; the other reads the same index.
+
+## Language
+
+The grid's own words go through `PixelI18nService` under the key `ip-exp-data-grid`: the figure labels
+(sum, avg, min, max, count), the grouping hint and level labels, the name of the row number column, the
+value shown for a group whose rows have none, what is announced while the index is built, the search
+and filter placeholders, and the five messages a filter expression can fail with. English and Norwegian
+ship with it; override any of them the way the other components are overridden.
+
+The parser itself returns an error code and a character position rather than a message, so what the
+user reads is translated here rather than baked into the engine.
+
+Figures are labelled with words rather than symbols, because a sigma tells nobody what it is unless
+they already know.
+
+## Accessibility
+
+The viewport is a `role="grid"` reporting `aria-rowcount` for the whole dataset rather than the
+rendered slice, so assistive technology hears "row 1002 of 5001" while only a few dozen rows exist
+in the DOM. Every row carries `aria-rowindex` and every cell `aria-colindex`. The sorted column
+carries `aria-sort`. Sort buttons are reachable and operable from the keyboard.
+
+With `selection`, the grid reports `aria-multiselectable` when more than one row may be picked, and
+every row carries `aria-selected`. The pick boxes are real checkboxes and radios, so the keyboard
+and assistive technology get them for nothing. The column heading has no room for a word at 44px, so
+it carries its name as visually hidden text rather than as a label on an empty cell.
+
+## Design tokens
+
+| Token                                                    | Role                                                                  |
+| -------------------------------------------------------- | --------------------------------------------------------------------- |
+| `$ip_color_table_header_background_primary_default`      | Header row background                                                 |
+| `$ip_color_table_header_background_secondary_default`    | Alternating row background                                            |
+| `$ip_color_table_column_header_text_primary_default`     | Header text                                                           |
+| `$ip_color_table_column_header_border_primary_default`   | Line under the header row                                             |
+| `$ip_color_table_column_header_border_secondary_default` | Line between header cells                                             |
+| `$ip_color_table_column_header_icon_primary_default`     | Sort direction mark, pick box                                         |
+| `$ip_color_table_row_background_primary_default`         | Row background                                                        |
+| `$ip_color_table_row_background_primary_hover`           | Row background on hover                                               |
+| `$ip_color_table_row_cell_background_primary_default`    | Grid background                                                       |
+| `$ip_color_table_row_cell_text_primary_default`          | Cell text                                                             |
+| `$ip_color_table_row_cell_border_primary_default`        | Row separator, skeleton bars                                          |
+| `$ip_color_border_primary_default`                       | Outer border                                                          |
+| `$ip_color_button_focus_default`                         | Focus ring on a sort button                                           |
+| `$ip_color_text_secondary_default`                       | Row numbers, empty state text                                         |
+| `$ip_color_extended_yellow-300`                          | Background of a search or filter match in a cell                      |
+| `$ip_color_extended_yellow-950`                          | Text of a search or filter match in a cell                            |
+| `$ip_color_extended_red-600`                             | An expression in a filter field or the search box that does not parse |
+| `$ip_color_brand_accent_primary_default`                 | Value list button on a heading whose column is narrowed               |
+| `$ip_color_button_background_destructive_default`        | A destructive row action                                              |
+| `$ip_color_border_primary_strong`                        | Border of the option radios in the settings panel                     |
+| `$ip_color_button_background_secondary_default`          | Background of the Close button in the column picker                   |
+| `$ip_color_button_text_secondary_default`                | Text of the Close button in the column picker                         |
+
+## Usage
+
+### HTML
+
+```html
+<div style="height: 480px">
+  <ip-exp-data-grid id="grid" row-numbers zebra lock-first-column>
+    <ip-exp-data-grid-column field="name" label="Name" width="220"></ip-exp-data-grid-column>
+    <ip-exp-data-grid-column field="city" label="City" width="140"></ip-exp-data-grid-column>
+    <ip-exp-data-grid-column field="employees" label="Employees" width="110"></ip-exp-data-grid-column>
+    <span slot="empty">No companies yet</span>
+  </ip-exp-data-grid>
+</div>
+
+<script type="module">
+  import '@norconsult-digital-public/isypixel/experimental/web-components';
+
+  await customElements.whenDefined('ip-exp-data-grid');
+  document.getElementById('grid').rows = await fetch('/api/companies').then((response) => response.json());
+</script>
+```
+
+### React
+
+```tsx
+import { IpExpDataGrid, IpExpDataGridColumn } from '@norconsult-digital-public/isypixel/experimental/web-components/react';
+
+export function Companies({ rows }: { rows: Company[] }) {
+  return (
+    <div style={{ height: 480 }}>
+      <IpExpDataGrid rows={rows} rowNumbers zebra onIpSortChange={(event) => console.log(event.detail)}>
+        <IpExpDataGridColumn field='name' label='Name' width={220} />
+        <IpExpDataGridColumn field='city' label='City' width={140} />
+        <IpExpDataGridColumn field='employees' label='Employees' width={110} />
+      </IpExpDataGrid>
+    </div>
+  );
+}
+```
+
+### Vue
+
+```vue
+<template>
+  <div style="height: 480px">
+    <IpExpDataGrid :rows="rows" row-numbers zebra @ipSortChange="onSort">
+      <IpExpDataGridColumn field="name" label="Name" :width="220" />
+      <IpExpDataGridColumn field="city" label="City" :width="140" />
+      <IpExpDataGridColumn field="employees" label="Employees" :width="110" />
+    </IpExpDataGrid>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { IpExpDataGrid, IpExpDataGridColumn } from '@norconsult-digital-public/isypixel/experimental/web-components/vue';
+
+const props = defineProps<{ rows: Company[] }>();
+const onSort = (event: CustomEvent) => console.log(event.detail);
+</script>
+```
+
+### Angular
+
+```ts
+import { IpExpDataGrid, IpExpDataGridColumn } from '@norconsult-digital-public/isypixel/experimental/web-components/angular';
+
+@Component({
+  selector: 'app-companies',
+  imports: [IpExpDataGrid, IpExpDataGridColumn],
+  template: `
+    <div style="height: 480px">
+      <ip-exp-data-grid [rows]="rows()" row-numbers zebra (ipSortChange)="onSort($event)">
+        <ip-exp-data-grid-column field="name" label="Name" width="220"></ip-exp-data-grid-column>
+        <ip-exp-data-grid-column field="city" label="City" width="140"></ip-exp-data-grid-column>
+        <ip-exp-data-grid-column field="employees" label="Employees" width="110"></ip-exp-data-grid-column>
+      </ip-exp-data-grid>
+    </div>
+  `,
+})
+export class CompaniesComponent {
+  readonly rows = signal<Company[]>([]);
+
+  onSort(event: CustomEvent): void {
+    console.log(event.detail);
+  }
+}
+```
+
+### Svelte
+
+```svelte
+<script lang="ts">
+  import '@norconsult-digital-public/isypixel/experimental/web-components';
+
+  let { rows }: { rows: Company[] } = $props();
+</script>
+
+<div style="height: 480px">
+  <ip-exp-data-grid {rows} row-numbers zebra onipSortChange={(event) => console.log(event.detail)}>
+    <ip-exp-data-grid-column field="name" label="Name" width="220"></ip-exp-data-grid-column>
+    <ip-exp-data-grid-column field="city" label="City" width="140"></ip-exp-data-grid-column>
+    <ip-exp-data-grid-column field="employees" label="Employees" width="110"></ip-exp-data-grid-column>
+  </ip-exp-data-grid>
+</div>
+```
+
+### Blazor
+
+```razor
+<div style="height: 480px">
+  <ip-exp-data-grid @ref="grid" row-numbers zebra>
+    <ip-exp-data-grid-column field="name" label="Name" width="220"></ip-exp-data-grid-column>
+    <ip-exp-data-grid-column field="city" label="City" width="140"></ip-exp-data-grid-column>
+    <ip-exp-data-grid-column field="employees" label="Employees" width="110"></ip-exp-data-grid-column>
+  </ip-exp-data-grid>
+</div>
+
+@code {
+  private ElementReference grid;
+
+  protected override async Task OnAfterRenderAsync(bool firstRender)
+  {
+      if (firstRender)
+      {
+          // rows is a JS array; set it as a property, not an attribute.
+          await JS.InvokeVoidAsync("setGridRows", grid, Companies);
+      }
+  }
+}
+```
+
+```js
+// wwwroot/grid-interop.js
+window.setGridRows = (element, rows) => {
+  element.rows = rows;
+};
+```
+
+### Picking rows
+
+One attribute and one event, the same in every framework. The indexes are positions in the `rows`
+array you handed the grid, so the application looks the objects up itself.
+
+```html
+<ip-exp-data-grid id="grid" selection="multiple" row-numbers>
+  <ip-exp-data-grid-column field="name" label="Name" width="220"></ip-exp-data-grid-column>
+  <ip-exp-data-grid-column field="city" label="City" width="140"></ip-exp-data-grid-column>
+</ip-exp-data-grid>
+
+<script type="module">
+  const grid = document.getElementById('grid');
+  grid.rows = companies;
+
+  grid.addEventListener('ipRowSelectionChange', (event) => {
+    const picked = event.detail.rows.map((index) => companies[index]);
+    console.log(`${picked.length} companies picked`);
+  });
+
+  // Picking from outside works the same way, so a Clear button is one line.
+  document.getElementById('clear').addEventListener('click', () => {
+    grid.selected = [];
+  });
+</script>
+```