@kanunilabs/datagrid-react

@kanunilabs/datagrid-react / GridColumnDef

Interface: GridColumnDef<TRow>

Extended by

• ReactGridColumnDef

Type Parameters

TRow

TRow = GridRowData

Properties

align?

optional align?: ColumnAlign

band?

optional band?: string | string[]

Caption(s) of the band row(s) above this column's header — 'Sales' for one level, ['Contact', 'Address'] for two.

A PATH on the column rather than a nested column tree: the flat list is what carries width, order, pinning, visibility, persistence and virtualization, so keeping the model flat means banding costs nothing in the pipeline. Adjacent columns with the same path merge into one band cell.

bandShow?

optional bandShow?: "open" | "closed"

Whether this column survives its band being collapsed (gap analysis P2.6).

• omitted — always shown; collapsing the band does not affect it
• 'open' — only while the band is OPEN (the detail columns)
• 'closed' — only while the band is COLLAPSED (the summary that stands in for them)

A band with no column declaring either is not collapsible: there would be nothing to hide, and a toggle that does nothing is worse than no toggle.

calculateSortValue?

optional calculateSortValue?: (row) => unknown

Sort on a derived value (e.g. custom ordering) instead of the cell value.

Parameters

row

TRow

Returns

unknown

comparator?

optional comparator?: (valueA, valueB, rowA, rowB, descending) => number

Order this column by an arbitrary rule (gap analysis P1.8) — the escape hatch for orderings no data type describes: a T-shirt size scale, a domain-specific priority, a locale rule Intl.Collator gets wrong.

Prefer calculateSortValue when the rule can be expressed as a value to sort BY. That keeps the fast paths; this one closes them for this column:

• the radix/typed-array sort cannot run — a byte order cannot be derived from a function, so the column falls back to a comparator sort; • the WORKER cannot run the query at all — functions are unclonable, so a sort touching this column stays on the main thread whatever the row count. Correctness is preserved; the speed is what is spent.

The values arrive exactly as the column produces them, null/undefined INCLUDED: a custom order usually wants to place its own blanks, and the built-in "nils last" rule would pre-empt that decision.

descending is informational — the grid already inverts the result for a descending sort. It exists for rules that must NOT flip (keeping a "Total" row last in both directions).

Parameters

valueA

unknown

valueB

unknown

rowA

TRow

rowB

TRow

descending

boolean

Returns

number

dataType?

optional dataType?: GridDataType

dateFormat?

optional dateFormat?: string

How a date column is written and typed — 'dd.MM.yyyy', 'MM/dd/yyyy', 'dd/MM/yy', any separator. Defaults to 'yyyy-MM-dd'.

Governs BOTH directions: the cell renders through it, and the editor masks keystrokes into it, so what the user types back is the shape they were shown. Ignored on any other data type.

editable?

optional editable?: boolean

Editable in an Enterprise grid with editing on. Defaults to true; set false for a computed or server-owned column so the editor never opens on it.

excelFormat?

optional excelFormat?: string

Excel number format for the styled export (e.g. '#,##0.00', '"$"#,##0', '0.0%'). Without it a number column gets a plain thousands separator — currency and percent are never guessed, because guessing changes what the number means.

field?

optional field?: string

Property read from the row object (dot paths NOT expanded — use valueGetter).

filterable?

optional filterable?: boolean

groupable?

optional groupable?: boolean

headerName?

optional headerName?: string

id?

optional id?: string

Stable identity; defaults to field. Required when two columns share a field.

lookup?

optional lookup?: ColumnLookup<TRow>

Value list for a code→label column. Drives the select editor, and (for a static list) the displayed text.

maxWidth?

optional maxWidth?: number

minWidth?

optional minWidth?: number

pin?

optional pin?: ColumnPin

reorderable?

optional reorderable?: boolean

resizable?

optional resizable?: boolean

sortable?

optional sortable?: boolean

spanRows?

optional spanRows?: boolean | SpanComparator<TRow>

Merge this column's cell down over consecutive rows holding the same value (gap analysis P3.1).

Computed over the CURRENT view, which is the point: sorting a column into A A A B B is what makes the merge meaningful, and the same rows unsorted merge nothing. Blanks never merge, a group banner interrupts a run, and a run of one is left as an ordinary cell.

true compares with Object.is. Pass a function for values that need their own notion of equality — a column of objects, or a case-insensitive code.

The merged block is still N cells to everything else: selection, editing, the clipboard and export see the rows the data has. Only the DRAWING is merged, which is what a reader means by it.

sparkline?

optional sparkline?: ColumnSparkline

Draw this column's value as an in-cell chart (gap analysis P2.2).

The cell's value must be an ARRAY of numbers — a series per row. Config lives here, next to band and lookup, because it is data description rather than rendering: which numbers, and against what scale. The drawing belongs to the adapter, and the packaged renderer is Enterprise.

valueFormatter?

optional valueFormatter?: (value, row) => string

Display formatting hook (adapters render the returned string).

Parameters

value

unknown

row

TRow

Returns

string

valueGetter?

optional valueGetter?: (row) => unknown

Derive the cell value; overrides field access.

Parameters

row

TRow

Returns

unknown

visible?

optional visible?: boolean

width?

optional width?: number