gridcn2.0.0
Concepts

Cell type model

Understand how one cell type object drives display, editing, clipboard, sort, search, and filter, and which rules keep a custom type safe.

A custom cell type is a bigger decision than a column option. This page explains the model behind the CellType object and the rules that the built-in types follow.

The mental model

A cell type is one object. Cell renders a value, and Editor edits it. The methods toText, fromText, clearValue, and isEmpty form the value pipeline. Clipboard, fill, delete, search, import, and export read through it. Sort uses compare and filter matches the raw value.

The optional members tell the grid more: compare, toDisplayText, toSearchText, align, numeric, validate, activate, href, and filter. The grid reads these members from the type and not from the type name.

One generic implementation of each feature runs against this contract for every type. A bug in fromText therefore reaches every consumer of the type. CellType contract lists each member.

Keypoint checklist

The built-in types follow these rules. Each rule has a reason. CellType contract holds the exact rule for each member.

Value pipeline

Each feature reads a value through its own member. The CellType contract lists the member for print, autosize, clipboard, export, sort, search, filter, and fill. A custom Cell decides its own display.

Search matches text, and filter matches the stored value. A select column searches the choice label. Its filters take the stored choice values and not the labels.

Follow these rules for the methods:

  • fromText receives any text from paste and import. A throw rejects that cell. Call rejectText() for text it cannot parse: the cell keeps its value, and the grid reports the text. Return clearValue() only to empty the cell on purpose.
  • Store serializable primitives. Use an ISO yyyy-mm-dd string and not a Date, and a plain number and not a money object. Compare, clipboard, and JSON then stay simple, and no time zone shifts a day.
  • Choose isEmpty for each type. For text, the empty string is empty. For number and checkbox, only null and undefined are empty, so 0 and false are values. For a column with a comparator (compare or sortCompare), isEmpty decides which cells sort last. isEmpty also decides where Mod+Arrow stops, and which cells Mod+A takes as the data region.
  • Format for people in toDisplayText. Keep toText a plain string that fromText parses back.
  • Accept a stored value and a displayed label on paste. The select type writes the label in toText, and its fromText matches a pasted value first and a label second.

Rendering and performance

Cell renders once per visible cell, and scrolling mounts cells all the time.

  • Create costly objects once. The date type keeps its Intl.DateTimeFormat instances in a cache.
  • Key a cache on serialized option values, not on object identity. A column definition creates its options object on every render, so an identity key never hits. The date and number caches key on the locale and the JSON of the format. The JSON is computed once per format object, so replace the object to change the format.
  • Pin every locale. Intl formatters fall back to the runtime locale, and a server and a browser can differ. The date type formats with options.locale and defaults to en-US, so server and client text match.

Editor UX

The editor holds its draft. onChange(value) stashes the draft in the grid, and commit(movement?) applies the stashed value and moves the active cell. cancel() discards the edit. Call onChange and then commit, or call commitValue(value, movement) to commit a value in one call. A commit without an earlier onChange applies the opening value.

  • Build a text editor on useCellEditor. It owns the draft, the focus, the one-shot commit guard, and the Enter, Escape, and blur bindings. It ignores Enter and Escape during IME composition.
  • When an editor commits from more than one path, such as Enter followed by blur, use useCommitGuard. tryCommit() returns true once, and reset() arms it again.
  • Commit Enter with { dx: 0, dy: 1 }. Commit blur, click-away, and a picked option with { dx: 0, dy: 0 }. Escape calls cancel(), and it never calls onChange.
  • While pending is true, set the input readOnly. Never set it disabled, because a disabled input cannot receive Escape or blur. When rejectionCount changes, re-arm the commit guard.
  • Portaled editor content, such as a popover, keeps the edit and the cell range on a press, a double click, and a focus. The data-grid-cell-editor marker is optional. An editor that commits on blur also commits when the focus moves into its portaled content.
  • A picker popover, such as select or date, commits on an explicit pick. When it closes without a pick, the editor cancels the edit. The longText popover commits its draft on an outside press and cancels on Escape.
  • A type with activate commits in place. Enter, F2, Space, a click on the active cell, and a double-click call activate(value, options) and open no editor. The checkbox type uses it.
  • Leave Tab to the browser. A Tab blur commits with { dx: 0, dy: 0 } while the browser moves the focus. A commit with { dx: 1, dy: 0 } on Tab moves the active cell away from the focus move.
  • Build editor controls from the components/ui primitives of your project.

Typing

Declare the value and options of a custom type through GridCellTypes, so that defineColumns narrows them:

export {};

declare module "@/components/data-grid/types" {
  interface GridCellTypes {
    currency: {
      value: number | null;
      options: { currency: string; locale?: string };
    };
  }
}

Set the module path to where components.json installs types.ts. Without the augmentation, a currency column still works, but its options and its value type are unknown.

CellTypeKey is the union of the keys in GridCellTypes. AnyCellType is the value type of a cellTypes registry entry. The data grid entry exports the built-in types as textCellType, numberCellType, checkboxCellType, selectCellType, dateCellType, urlCellType, and longTextCellType.

Wrap the type in defineCellType("currency", currencyCellType). It returns the type unchanged and ties it to the GridCellTypes key.

The cellTypes registry prop does not check an entry against its key. A null entry removes a type. A column whose type matches no entry renders as text, and its edits, pastes, and deletes write nothing. A development warning names the column and the type.

On this page