Blocks / Record grid

Record grid

Records as a sheet, edited in place: arrows, Enter or F2, type to replace, Escape, Tab, Delete.

import { RecordGrid } from "@forgeron/ui";
/01 → Default
name
stock
organic
Brie de Meaux42Yes
Comté 18 mois7No
Tomme de SavoieYes
import { RecordGrid, type CellValue, type DataField, type DataRecord } from "@forgeron/ui";
import { useState } from "react";

const fields: DataField[] = [
  { id: "name", name: "name", type: "text", required: true },
  { id: "stock", name: "stock", type: "number", decimals: 0 },
  { id: "organic", name: "organic", type: "boolean" },
];

export default function Default() {
  const [records, setRecords] = useState<DataRecord[]>([
    { id: "1", values: { name: "Brie de Meaux", stock: 42, organic: true } },
    { id: "2", values: { name: "Comté 18 mois", stock: 7, organic: false } },
    { id: "3", values: { name: "Tomme de Savoie", stock: null, organic: true } },
  ]);
  const change = (id: string, field: string, value: CellValue) =>
    setRecords((all) =>
      all.map((r) => (r.id === id ? { ...r, values: { ...r.values, [field]: value } } : r)),
    );
  return (
    <div style={{ width: 380 }}>
      <RecordGrid
        label="products"
        fields={fields}
        records={records}
        onChange={change}
        widths={{ name: 168 }}
      />
    </div>
  );
}
/02 → Spreadsheet
4 records
1Winter cheese boardsWon12480.00Fromagerie Roy2026-11-04YesB2BRetailcamille@roy.frquote-1042.pdf
2Refrigerated transport, Q1Quote8900.50Garnier Transports2026-12-15NoB2Bhugo@garnier.fr
3Export to GenevaLeadPetit & FilsNoExport
4Supermarket shelf spaceLost3200.00Martin Distribution2026-10-01NoRetaillea@martin.fr
// A table editor: every field type, rows to select and open, a + to add a record or a field, the
// headers sort. Click a cell, then use the keyboard: arrows, Enter or F2, type to replace, Escape,
// Tab, Delete, Space on a checkbox, Shift+Enter opens the record.
import {
  Drawer,
  RecordForm,
  RecordGrid,
  type CellValue,
  type DataField,
  type DataRecord,
  type RecordGridSort,
} from "@forgeron/ui";
import { useState } from "react";

const fields: DataField[] = [
  { id: "id", name: "id", type: "number", primary: true, decimals: 0 },
  { id: "name", name: "name", type: "text", required: true },
  {
    id: "stage",
    name: "stage",
    type: "select",
    choices: [
      { value: "lead", label: "Lead", color: "var(--ink-dim)" },
      { value: "quote", label: "Quote", color: "var(--warning)" },
      { value: "won", label: "Won", color: "var(--success)" },
      { value: "lost", label: "Lost", color: "var(--danger)" },
    ],
  },
  { id: "amount", name: "amount", type: "number", decimals: 2 },
  { id: "company", name: "company_id", type: "relation", relation: { table: "companies" } },
  { id: "close", name: "close_date", type: "date" },
  { id: "signed", name: "signed", type: "boolean" },
  {
    id: "tags",
    name: "tags",
    type: "multiSelect",
    choices: [
      { value: "b2b", label: "B2B", color: "var(--accent)" },
      { value: "export", label: "Export", color: "var(--success)" },
      { value: "retail", label: "Retail", color: "var(--ink-dim)" },
    ],
  },
  { id: "contact", name: "contact_email", type: "email" },
  { id: "files", name: "attachments", type: "file" },
];

const relations = {
  companies: [
    { id: "c-104", label: "Fromagerie Roy", hint: "Lyon" },
    { id: "c-212", label: "Garnier Transports", hint: "Grenoble" },
    { id: "c-318", label: "Petit & Fils", hint: "Annecy" },
    { id: "c-402", label: "Martin Distribution", hint: "Chambéry" },
  ],
};

const seed: DataRecord[] = [
  {
    id: "1",
    values: {
      id: 1,
      name: "Winter cheese boards",
      stage: "won",
      amount: 12480,
      company: ["c-104"],
      close: "2026-11-04",
      signed: true,
      tags: ["b2b", "retail"],
      contact: "camille@roy.fr",
      files: ["quote-1042.pdf"],
    },
  },
  {
    id: "2",
    values: {
      id: 2,
      name: "Refrigerated transport, Q1",
      stage: "quote",
      amount: 8900.5,
      company: ["c-212"],
      close: "2026-12-15",
      signed: false,
      tags: ["b2b"],
      contact: "hugo@garnier.fr",
      files: null,
    },
  },
  {
    id: "3",
    values: {
      id: 3,
      name: "Export to Geneva",
      stage: "lead",
      amount: null,
      company: ["c-318"],
      close: null,
      signed: false,
      tags: ["export"],
      contact: null,
      files: null,
    },
  },
  {
    id: "4",
    values: {
      id: 4,
      name: "Supermarket shelf space",
      stage: "lost",
      amount: 3200,
      company: ["c-402"],
      close: "2026-10-01",
      signed: false,
      tags: ["retail"],
      contact: "lea@martin.fr",
      files: null,
    },
  },
];

const compare = (a: CellValue, b: CellValue) => {
  if (a === b) return 0;
  if (a === null) return 1;
  if (b === null) return -1;
  return String(a).localeCompare(String(b), "en", { numeric: true });
};

export default function Spreadsheet() {
  const [records, setRecords] = useState(seed);
  const [selection, setSelection] = useState<string[]>([]);
  const [sort, setSort] = useState<RecordGridSort | null>(null);
  const [open, setOpen] = useState<string | null>(null);
  const change = (id: string, field: string, value: CellValue) =>
    setRecords((all) =>
      all.map((r) => (r.id === id ? { ...r, values: { ...r.values, [field]: value } } : r)),
    );
  const shown = sort
    ? [...records].sort(
        (a, b) =>
          compare(a.values[sort.field] ?? null, b.values[sort.field] ?? null) *
          (sort.direction === "asc" ? 1 : -1),
      )
    : records;
  const add = () => {
    const id = String(Math.max(...records.map((r) => Number(r.id))) + 1);
    setRecords([...records, { id, values: { id: Number(id), name: "New deal" } }]);
  };
  const record = records.find((r) => r.id === open);
  return (
    <div style={{ display: "flex", gap: 12, width: "100%", alignItems: "flex-start" }}>
      <div style={{ flex: 1, minWidth: 0, display: "grid", gap: 8 }}>
        <span style={{ font: "400 12px/16px var(--font-mono)", color: "var(--ink-muted)" }}>
          {selection.length ? `${selection.length} selected` : `${records.length} records`}
        </span>
        <RecordGrid
          label="deals"
          fields={fields}
          records={shown}
          relations={relations}
          onChange={change}
          selectable
          selection={selection}
          onSelectionChange={setSelection}
          onOpenRecord={setOpen}
          onAddRecord={add}
          onAddField={() => {}}
          sort={sort}
          onSortChange={setSort}
          fieldMenu={(f) => [
            { id: "edit", label: `Edit ${f.name}` },
            { id: "hide", label: "Hide the field" },
          ]}
        />
      </div>
      {record ? (
        <Drawer
          title={`deals.${record.id}`}
          description="Saved when you press Save."
          onClose={() => setOpen(null)}
        >
          <RecordForm
            key={record.id}
            mode="edit"
            fields={fields}
            defaultValue={record.values}
            relations={relations}
            onCancel={() => setOpen(null)}
            onSubmit={(values) => {
              setRecords((all) => all.map((r) => (r.id === record.id ? { ...r, values } : r)));
              setOpen(null);
            }}
          />
        </Drawer>
      ) : null}
    </div>
  );
}
/03 → Read only
Primary keyid
partner_id
amount_total
state
synced_at
INV/2026/041210421840.00posted2026-11-18 09:15
INV/2026/04132210312.40draftNULL
import { RecordGrid, type DataField } from "@forgeron/ui";

const fields: DataField[] = [
  { id: "id", name: "id", type: "text", primary: true },
  { id: "partner", name: "partner_id", type: "number", decimals: 0 },
  { id: "total", name: "amount_total", type: "number", decimals: 2 },
  { id: "state", name: "state", type: "text" },
  { id: "synced", name: "synced_at", type: "datetime" },
];

export default function ReadOnly() {
  return (
    <div style={{ width: "100%" }}>
      <RecordGrid
        label="odoo.account_move"
        fields={fields}
        showNull
        records={[
          {
            id: "INV/2026/0412",
            values: {
              id: "INV/2026/0412",
              partner: 1042,
              total: 1840,
              state: "posted",
              synced: "2026-11-18 09:15",
            },
          },
          {
            id: "INV/2026/0413",
            values: {
              id: "INV/2026/0413",
              partner: 2210,
              total: 312.4,
              state: "draft",
              synced: null,
            },
          },
        ]}
      />
    </div>
  );
}
API → Props
PropTypeDefaultDescription
labelstring—Names the grid: the table name.
fieldsDataField[]—{ id, name, type, primary?, required?, unique?, readOnly?, defaultValue?, description?, choices?, relation?: { table, multiple? }, decimals? }.
records{ id, values: Record<fieldId, CellValue> }[]—The rows. A list type (multi-select, relation, file) holds a string[].
relationsRecord<table, { id, label, hint? }[]>—The records relation fields can point at, by table: their labels and the picker.
onChange(recordId, fieldId, value) => void—Turns editing on. A typed value goes through parseValue: a wrong one stays in the cell with its problem.
selectablebooleanfalseA checkbox per row and in the header; Shift+Space toggles the current row.
selection / defaultSelectionstring[]—The selected record ids. Controlled or not.
onSelectionChange(ids: string[]) => void—When a box is ticked.
onOpenRecord(id) => void—An expand button per row, and Shift+Enter: open it in a Drawer with RecordForm.
onAddRecord() => void—A New record row at the end.
onAddField() => void—A + after the last column.
sort / onSortChange{ field, direction: "asc" | "desc" } | null—Headers become buttons that cycle ascending, descending, none.
fieldMenu / onFieldAction(field) => ActionMenuEntry[]—The actions of a column, behind a ⋯ in its header.
active / defaultActive{ record, field } | null—The current cell. Controlled or not, with onActiveChange.
widthsRecord<fieldId, number>—Column widths in px; by type otherwise.
showNullbooleanfalseWrites NULL in empty cells, as a database editor does.
markEditedbooleantrueAn ember corner on the cells changed since the grid was shown.
emptyReactNode"No records yet"Shown with no record.
classNamestring—Extra classes.