Editable Cell

Install

pnpm exec vegastack-design verify editable-cell

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

Usage

import { EditableCell } from "@/components/ui/editable-cell";

<EditableCell
  value={deal.name}
  label="Deal name"
  onSave={(name) => api.updateDeal({ name })}
/>;

Edit looks like view. There is no border, ring or background change when the cell edits: the field inherits the font, size, weight, line height, tracking and colour of its surroundings, and only the caret and the selection show it is being edited. The display and the field share one box — a grid cell holding the value text with the field laid over it — so the field grows with its content, wraps when the value wraps, and entering or leaving edit changes neither the width nor the line box.

Saving. Blur or a click outside saves; Enter saves a single-line value and

⌘/Ctrl+Enter a multiline one; Escape cancels and restores. Nothing is saved when the value is unchanged. When onSave returns a promise the display updates at once; a subtle spinner trails the value only if the save takes longer than 300ms; on failure the value rolls back, the failure is announced and a toast offers Retry (the app mounts Toaster). onCommit is the older name of onSave and still works.

Affordance. No fill at rest, on hover or while editing — the text cursor and an optional tooltip are the only pointer affordances. Keyboard focus on the resting value shows the system's focus tint; Tab reaches the cell and Enter or

F2 starts editing.

In a property list. Inside a PropertyValue the inline cell's box turns compact — 6px and 2px of padding hung outside by equal negative margins — so its text lines up exactly (left edge, baseline, row height) with the read-only values beside it, in every state; the box keeps its hit area but paints no fill. See Property List.

Scope

Anatomy

Examples

Table cell

variant="cell" fills the table cell, so the field is as wide as the column and the column never resizes. Only the text starts an edit: a click beside it goes to the row (a row link keeps working). With onNavigate, Enter and Tab save and hand the host a direction to move to the next cell (Shift goes back).

Page title

variant="heading" keeps the heading's size and weight and wraps naturally, in view and in edit. It has no box padding, so the title is edited exactly where it is rendered — idle and editing sit at the same position, lined up with the lines below, and only the text cursor marks it editable. Put the cell inside the heading element rather than restyling its parts.

Give a stored name its limit with editor={{ type: "text", maxLength }}: the field stops there, a paste keeps what fits and says so, and a quiet n/max count shows under the field from 90% of the limit — so what is typed or pasted never runs past what the store accepts. (A value that is already longer is shown and kept as it is; maxLength only limits what is added.)

<h1 className="text-2xl font-semibold">
  <EditableCell
    variant="heading"
    required
    label="Meeting title"
    value={title}
    onSave={rename}
  />
</h1>

Single-line

The default. A long value truncates with an ellipsis and offers the full value as its title; opening the editor shows all of it. wrap breaks it onto more lines instead.

Multiline

multiline edits several lines: Enter adds a line, ⌘/Ctrl+Enter or blur saves.

Required

With required, clearing the value saves nothing: the previous value comes back and requiredMessage (default {label} can't be empty) is announced and toasted.

Save error

A rejected onSave rolls the value back, announces it and raises an error toast whose Retry runs the same save again. saveErrorToast={false} leaves the toast to the host.

Slow save

The value updates optimistically; the trailing spinner appears only after 300ms, so fast saves never flash it.

Parity

The same value in view and in edit mode, over a 20px baseline grid: the text sits on the same line, at the same x, with the same width.

Whole-cell triggers

In a list, the WHOLE cell is the click target — a priority's flag and its text, a status, an assignee, a date — never just the icon. The date and select editors already fill a cell variant cell; an app-owned editor (a status, priority or assignee menu) puts InlineEditTrigger behind its DropdownMenuTrigger or PopoverTrigger. Both carry no border at rest and the properties-panel tint on hover, keyboard focus and while open, and both open with

Enter or Space. Mark the column interactive, and render a plain value where the viewer may not edit.

Select editor

Real inline editors are per-type: a stage field edits with a popover list, not a text box. The select editor renders a Select whose popover is the editor; the save fires on selection.

Number editor

editor={{ type: "number", unit, min, max, step }} edits a spec value. The value is still a string: it displays formatted in the reader's locale with the unit muted after it (1,250 mm), and edits as the raw number with a decimal keyboard and the unit trailing the caret inside the same box. A draft that is not a number, falls outside min/max or is off step does not save: the field stays open with the draft, marked aria-invalid, and the rule is announced. Grouping (1,250) is accepted and saved without it; an empty draft saves "".

Below, each editor type inside a PropertyList variant="inline" — text, number with a unit, and select — lines up with the read-only value above it at rest, on hover and while editing.

Custom editor with a label

When the value is an id — an owner, a customer, a project — pass renderValue so the cell shows the name a person reads instead of the stored id. It is used while displaying, for every editor type; the editor still works on the raw value, and an empty value keeps the placeholder.

States

Managed focus (grid hosts)

Inside a grid the grid's roving focus model owns reachability. focusMode="managed" removes the cell's own tab stop, and the host opens the editor from its keyboard model through the controlled editing / onEditingChange pair:

<EditableCell
  variant="cell"
  value={cell.value}
  label={column.header}
  focusMode="managed"
  editing={isEditingThisCell}
  onEditingChange={(editing) => grid.setEditingCell(editing ? cellId : null)}
  onNavigate={(direction) => grid.moveEditor(direction)}
  status={grid.cellStatus(rowId, column.key)}
  onSave={(next) => grid.commitCell(rowId, column.key, next)}
/>

API Reference

InlineEditTrigger

EditableCellRest

What DataGrid renders for a resting cell whose column has a custom editor: the display's button and value, accessible name and description, and the same box, with no state, effects or live region. A click on the value (not on a link chip inside it) or Enter, F2 or Space on it calls onStartEditing; the grid then mounts EditableCell for that cell. A clipped value gets its full text as the title when the pointer or focus reaches it.

Editor contract

The custom editor receives EditableCellEditorProps: the value, the seed (the printable key that opened it, through editSeed), commit(next, move?) and cancel. A move — down, up, right or left — is handed to onNavigate after the commit, so an editor follows the spreadsheet keys (Enter down, Shift+Enter up, Tab right,

Shift+Tab left). An editor that saves a typed value itself leaves the cell with commit(value, move): an unchanged commit saves nothing.

Accessibility

• Read mode is a role="button" labelled Edit {label}, described by the value; edit mode is a text field labelled label (then placeholder, then a generic name).
• Saves and errors are announced through a visually hidden polite live region — "Saved", Couldn't save {label} — value restored, and the required message. The spinner is decorative.
• Escape cancels, restores the prior value and returns focus to the display.
• In focusMode="managed" the cell has no tab stop of its own — the host grid owns reachability. Inside DataGrid its announcements are spoken through the grid's one live region rather than a region per cell.

Do / Don't