Field Cell

Install

pnpm exec vegastack-design verify field-cell

pnpm dlx shadcn@4.21.0 add @vegastack/field-cell

Usage

import {
  FieldCellDisplay,
  FieldCellEditor,
  FieldInput,
} from "@/components/ui/field-cell";

// Show a value
<FieldCellDisplay type="currency" value={1240.5} config={{ currency: "EUR" }} />

// Edit it in a grid cell: the column's render is the display, the custom editor gets the row
render: (row) => <FieldCellDisplay type="single_choice" value={row.status} config={{ options }} />,
editable: {
  type: "custom",
  render: ({ row, value, seed, commit, cancel }) => (
    // The editor commits a TYPED value: save it, then leave the slot (and move, with the key).
    <FieldCellEditor type="single_choice" label="Status" value={row.status}
      config={{ options }} seed={seed}
      onCommit={(v, move) => { save(row.id, "status", v); commit(value, move); }}
      onCancel={cancel} />
  ),
}

// Edit it in a panel or a form
<FieldInput type="date" aria-label="Due" value={due} onChange={setDue} />;

field-cell is one display and one editor per field type, so a table's cells, a row panel and a record page's custom fields agree. FieldCellDisplay shows a value on one line; FieldCellEditor is what a grid cell opens and commits a typed value (not a string); FieldInput is the same editor as a plain form control.

Field types are data types. Everything a host knows — the options, the people, how records are found, a link kind's icon and noun (the host's InlineChip kinds) — comes in through config and the host's providers. Locale and time zone come from the reader (TimeZoneProvider).

Scope

Anatomy

Examples

Choice values

A choice value is a Badge filled in its option's hue — Badge's custom colour route on the tag tokens, never an outlined pill — and FieldChoiceBadge is that badge, so every surface draws an option the same way: a cell, a phone card, the editor's list, a form trigger. Use it wherever the host shows an option outside a field cell (a board card, a filter value). A cell shows two and "+N"; a cut name and the hidden ones show on hover and keyboard focus.

import { FieldChoiceBadge } from "@/components/ui/field-cell";

<FieldChoiceBadge hue="green">
  <span className="min-w-0 truncate">Sent</span>
</FieldChoiceBadge>;

In a grid the choice editor puts no field in the cell: the cell keeps its badges where they were, and the option list opens under it at once — the search field first, each option as its badge, a check on the chosen ones, and "Add “…”" at the end when config.onCreateOption is given. A single choice commits on the pick. A multiple choice toggles with the list open and commits on

Tab, on Enter with no option highlighted, or when the list closes (a click away); Escape cancels. As a form control (FieldInput, a record's property row) a choice is a SearchableSelect field with the same badges in its list.

Editors as form controls

A cell editor

A picker commits on choosing (chosen with Enter, it also moves down) — a multiple choice when the edit ends, as above; text, numbers and date-times commit on Enter or when focus leaves the editor (not into its own calendar); long text opens in a popover, with the @ mention menu when config.mentions is given (with mentionHref and mentionImage, as TextEdit takes them; the row panel's FieldInput too); Escape cancels. The editor takes focus as it opens — a picker's list or calendar opens with it, and long text's editor takes the caret. In a grid it follows the spreadsheet keys:

Enter commits and moves down (Shift+Enter up), Tab right and Shift+Tab left — through onCommit's move — and Tab first steps through a date-time's own date and time. The key that opened it (seed) replaces a text, URL, email, phone, number or long-text value (keys typed while long text's editor loads follow it); a date opens as a field that takes a typed date ("12/3", "Mar 12", "today") starting from it; and a choice, person or link picker opens searching for it. A date-time opens as it is. While an IME is composing, no key commits or moves.

API Reference

FieldInput

FieldCellEditor

Config

FieldChoiceBadge

Accessibility

• Every editor is named by its field (aria-label / label) and marks a value it refuses aria-invalid (an invalid URL, email or phone).
• Each link chip stays on one line and is never broken inside a name, even inside a host's prose; a cell that grows (className="flex-wrap", a page's table block) wraps whole chips.
• A truncated text, number, date, tag or link name is revealed on hover and on keyboard focus; a link list's "+2" names what it hides on hover and on keyboard focus (an unreachable link only by its state); every overflowed list (links, people, files) is read in full by screen readers; the row panel shows every value whole.
• A restricted link is muted and never a link; an unavailable or deleted one says so.

Do / Don't