@kanunilabs/datagrid / GridColumnDef

Interface: GridColumnDef<TRow>

Defined in: datagrid-core/dist/index.d.ts:513

Type Parameters

TRow

TRow = GridRowData

Properties

align?

optional align?: ColumnAlign

Defined in: datagrid-core/dist/index.d.ts:572

band?

optional band?: string | string[]

Defined in: datagrid-core/dist/index.d.ts:528

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"

Defined in: datagrid-core/dist/index.d.ts:540

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

Defined in: datagrid-core/dist/index.d.ts:593

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

Defined in: datagrid-core/dist/index.d.ts:616

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

Defined in: datagrid-core/dist/index.d.ts:568

dateFormat?

optional dateFormat?: string

Defined in: datagrid-core/dist/index.d.ts:627

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

Defined in: datagrid-core/dist/index.d.ts:584

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

Defined in: datagrid-core/dist/index.d.ts:634

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

Defined in: datagrid-core/dist/index.d.ts:517

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

filterable?

optional filterable?: boolean

Defined in: datagrid-core/dist/index.d.ts:576

groupable?

optional groupable?: boolean

Defined in: datagrid-core/dist/index.d.ts:579

headerName?

optional headerName?: string

Defined in: datagrid-core/dist/index.d.ts:518

id?

optional id?: string

Defined in: datagrid-core/dist/index.d.ts:515

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

lookup?

optional lookup?: ColumnLookup<TRow>

Defined in: datagrid-core/dist/index.d.ts:589

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

maxWidth?

optional maxWidth?: number

Defined in: datagrid-core/dist/index.d.ts:571

minWidth?

optional minWidth?: number

Defined in: datagrid-core/dist/index.d.ts:570

pin?

optional pin?: ColumnPin

Defined in: datagrid-core/dist/index.d.ts:573

reorderable?

optional reorderable?: boolean

Defined in: datagrid-core/dist/index.d.ts:578

resizable?

optional resizable?: boolean

Defined in: datagrid-core/dist/index.d.ts:577

sortable?

optional sortable?: boolean

Defined in: datagrid-core/dist/index.d.ts:575

spanRows?

optional spanRows?: boolean | SpanComparator<TRow>

Defined in: datagrid-core/dist/index.d.ts:567

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

Defined in: datagrid-core/dist/index.d.ts:549

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

Defined in: datagrid-core/dist/index.d.ts:618

Display formatting hook (adapters render the returned string).

Parameters

value

unknown

row

TRow

Returns

string

valueGetter?

optional valueGetter?: (row) => unknown

Defined in: datagrid-core/dist/index.d.ts:591

Derive the cell value; overrides field access.

Parameters

row

TRow

Returns

unknown

visible?

optional visible?: boolean

Defined in: datagrid-core/dist/index.d.ts:574

width?

optional width?: number

Defined in: datagrid-core/dist/index.d.ts:569