Data grid guide

The data grid is the largest subsystem in the kit: the hc-datagrid component, the Data grid page template, and thirteen recipes that each add one operation a business grid is used for. Each of those pages documents its own markup and server contract in full — this page is the map: what exists, what depends on what, and the order a real grid grows in.

Start here

1. The component — the markup: sticky multi-level headers, frozen columns, numeric columns, states, and installDatagrid()’s keyboard model. Render your data with it before adding any operation.
2. The page template — the layout the grid sits in: an app shell where only the grid scrolls, the filter panel, and the chrome placement rules. Copy it rather than rediscovering its height rule.
3. Add operations as recipes — each stage below is independent; take only what the screen needs.

Stage 1 — display

No recipes yet: everything here is the component and the template.

You need to…	Where it lives
sticky headers, frozen columns, multi-level headers	Structure · Trailing frozen columns
right-aligned amounts, conditional formatting, row ordinals	Numeric columns · Conditional formatting · Row ordinals
the page layout where only the grid scrolls	Data grid page template

Stage 2 — operate (the read path)

Every read operation is the same wire: a form GETs the grid URL with namespaced params, and the server re-renders the grid (and the control’s own state) from them.

You need to…	Recipe
page from the server	Datagrid pagination
an editable, ordered sort set	Datagrid sort
per-column filters	Datagrid filter
per-user column choice	Datagrid columns
remembered widths and order	Datagrid prefs
open a row’s record and come back to the same list	Row detail
name the current filters and recall them as links	Saved views
bound what one search may return	Result cap

Stage 3 — edit (the write path)

Inline editing’s markup and keyboard model live on the component page; the two recipes are its error wires — each row is its own record tbody, so both re-render one record atomically.

You need to…	Recipe
reject a bad commit — 422 re-renders the record with the marked cell	Datagrid edit errors
optimistic locking per row — a stale save 409s into a conflict row	Datagrid edit conflict

Stage 4 — bulk & scale

You need to…	Recipe
select rows and POST one action against all of them	Datagrid bulk actions
bulk failures grouped by reason, rows linked from the report	Datagrid bulk errors
endless lists without page numbers	Datagrid infinite — requires --hc-datagrid-max-height: none; see the recipe
a work queue frozen at search time	Datagrid snapshot pager
hierarchy inside the grid	Datagrid tree

Related

• Errors & recovery — the status-code map (422 / 409 / 401) the edit and bulk wires build on.
• Filterbar — the condition read-out strip the template composes above the grid.
• Table — the static semantic table, for when you don’t need a grid at all.