JSVision

Appearance

@jsvision/datagrid / GridColumn

Interface: GridColumn<T, V> ​

Defined in: datagrid/src/column.ts:31

One typed column of a data grid: a stable id, a header title, a typed value accessor (the sort/filter key), and optional display format, edit parse, sizing width, and align. When format is omitted the cell shows String(value); a read-only column may define format without parse. Author columns with column so V is inferred from value and format/parse are type-checked against it.

Type Parameters ​

T ​

T

V ​

V = unknown

Properties ​

align? ​

readonly optional align?: ColumnAlign

Defined in: datagrid/src/column.ts:88

Text alignment within the column width.

cellStyle? ​

readonly optional cellStyle?: CellStyle<T, V>

Defined in: datagrid/src/column.ts:107

Value-driven cell colour, composited under the fixed precedence (cursor > dirty > selected-row > cellStyle > zebra > normal): it paints only when no higher state (the cursor cell, a pending commit, or the selected/focused row) owns the cell.

compare? ​

readonly optional compare?: (a, b) => number

Defined in: datagrid/src/column.ts:113

Custom order for this column's values, overriding the type-aware default (numbers, dates, then a case-insensitive collator). Receives only non-null values — null/undefined ordering is governed by nulls. Returns <0 / 0 / >0 like Array.prototype.sort's comparator.

Parameters ​

a ​

V

b ​

V

Returns ​

number

editor? ​

readonly optional editor?: CellEditorSpec | ((row) => CellEditorSpec)

Defined in: datagrid/src/column.ts:95

The cell editor to mount: a literal CellEditorSpec, or a per-row function that returns one. Absent on an editable column (one with parse + set) mounts a plain text input; a read-only column ignores it. Use it to pick a typed widget — e.g. { kind: 'boolean' } or { kind: 'lookup', items } — or { kind: 'readonly' } to make an otherwise-editable column read-only.

filterable? ​

readonly optional filterable?: boolean

Defined in: datagrid/src/column.ts:152

Whether this column participates in filtering (default true). A false column shows no header funnel and its funnel cell is not hit-testable, its quick-filter input is omitted, and the Alt+Down open-filter shortcut is a no-op while one of its cells is focused — use it for action/icon columns, or any column that should never be filtered. Column geometry is unaffected: the funnel reserve and the quick-filter slot are simply not taken.

Example ​

ts
import { column } from '@jsvision/datagrid';
interface Row { name: string; }
// An action column that never shows a funnel and has no quick-filter input:
const actions = column({ id: 'actions', title: '', value: (_r: Row) => '', filterable: false });

filterType? ​

readonly optional filterType?: FilterType

Defined in: datagrid/src/column.ts:136

The operator family the column's filter popup presents ('text' / 'number' / 'date'). When omitted it is inferred at runtime from a sampled non-null value (a number → 'number', a Date or CalendarDate → 'date', otherwise 'text'); set it to override a sparse or ambiguous column whose sample would misclassify.

format? ​

readonly optional format?: (value, row) => string

Defined in: datagrid/src/column.ts:39

Formats the value for display (default: String(value)).

Parameters ​

value ​

V

row ​

T

Returns ​

string

id ​

readonly id: string

Defined in: datagrid/src/column.ts:33

Stable column identifier (used by sort/filter/layout state).

maxWidth? ​

readonly optional maxWidth?: number

Defined in: datagrid/src/column.ts:86

Maximum width in cells. Caps apportionment and bounds auto-fit (auto-fit falls back to a generous built-in default when omitted). An interactive resize is not capped unless this is set.

minWidth? ​

readonly optional minWidth?: number

Defined in: datagrid/src/column.ts:81

Minimum width in cells. A resize clamps to this floor and an 'auto'/fr column never apportions below it. Defaults to a small built-in floor when omitted.

nullable? ​

readonly optional nullable?: boolean

Defined in: datagrid/src/column.ts:122

Allow this cell to hold null: an editor that commits an empty value stores null (not ''), so a null round-trips distinctly from an empty string. A non-nullable column parses '' as usual. Consequence: a nullable column cannot also store a literal empty string distinct from null — empty means null there; a caller who needs a literal '' leaves the column non-nullable.

nullDisplay? ​

readonly optional nullDisplay?: string

Defined in: datagrid/src/column.ts:129

Text shown for a null/undefined value (default ''), distinct from an empty string and never the literal "null". Resolved in the render accessor upstream of format, so it applies to the default text path; a column with a custom render hook owns its own null handling (it receives the raw null, not nullDisplay).

nulls? ​

readonly optional nulls?: "first" | "last"

Defined in: datagrid/src/column.ts:115

Where null/undefined values sort, independent of direction (default 'last').

parse? ​

readonly optional parse?: (text) => typeof PARSE_FAILED | V

Defined in: datagrid/src/column.ts:45

Parses edited text back to the typed value (editable columns only). May return the PARSE_FAILED sentinel for an unparseable string (as the invertible fmt.* formatters do); the commit path rejects that — the record is left unchanged and the editor stays open.

Parameters ​

text ​

string

Returns ​

typeof PARSE_FAILED | V

render? ​

readonly optional render?: CellRenderer<T, V>

Defined in: datagrid/src/column.ts:101

Custom cell painter — the escape hatch for glyph indicators, badges, and traffic lights. Draws into a cell-local, cell-clipped context (origin at the cell's top-left) and is draw-error isolated: a throw degrades only its own cell. When set, it replaces the default formatted text for the cell.

set? ​

readonly optional set?: (row, value) => void

Defined in: datagrid/src/column.ts:52

Writes the parsed value back into the record (editable columns only). Pairs with parse: a column is editable exactly when it has both, so an edit round-trips text → value → record. The setter must be synchronous, deterministic, and non-throwing. Row-level rollback calls it more than once when compensation is required; violating this contract degrades recovery to best effort.

Parameters ​

row ​

T

value ​

V

Returns ​

void

showFunnel? ​

readonly optional showFunnel?: boolean

Defined in: datagrid/src/column.ts:170

Show the filter funnel ▽ on this column's header at all times (default false). By default a column's funnel appears only while it has an active filter (emphasized) and the header is otherwise clean; set this to advertise the filter affordance permanently — the glyph is drawn muted when unfiltered and emphasized when a filter is active. Independent of the keyboard opener: Alt+Down opens the condition popup on any filterable column regardless of this flag. Ignored when filterable is false (a non-filterable column never shows a funnel). Reserving the funnel cell clips a title that would otherwise fill the full column width by one cell.

Example ​

ts
import { column } from '@jsvision/datagrid';
interface Row { region: string; }
// A column that always advertises its filter funnel, even before any filter is applied:
const region = column({ id: 'region', title: 'Region', value: (r: Row) => r.region, showFunnel: true });

title ​

readonly title: string

Defined in: datagrid/src/column.ts:35

Header cell text.

validate? ​

readonly optional validate?: (value, row) => string | null

Defined in: datagrid/src/column.ts:74

Validate the parsed value at commit time (editable columns). Return null to accept, or a short message describing why the value is invalid. On a message the commit is blocked, nothing is written, the editor stays open, and the cell is marked in the gridInvalid role with the message surfaced in the grid's message band. Runs on the typed value after parse, so it composes with the editor's live keystroke filter (which is unaffected). Not called when a nullable column is cleared to null — an empty clear is not a typed value to validate, so a validator written for the typed V never receives null. Client-side validation is UX only: the authoritative gate is the caller's onCommit/source.

Parameters ​

value ​

V

row ​

T

Returns ​

string | null

Example ​

ts
import { column } from '@jsvision/datagrid';
interface Line { qty: number; }
const qty = column({
  id: 'qty', title: 'Qty', value: (r: Line) => r.qty,
  parse: (t) => Number(t), set: (r, v) => { r.qty = v; },
  validate: (v) => (v > 0 ? null : 'Quantity must be positive'),
});

value ​

readonly value: (row) => V

Defined in: datagrid/src/column.ts:37

Extracts this column's typed value from a row — the sort/filter key.

Parameters ​

row ​

T

Returns ​

V

width? ​

readonly optional width?: ColumnWidth

Defined in: datagrid/src/column.ts:76

Sizing rule (default 'auto' when adapted): fixed cells, ${n}fr, or 'auto'.