@jielga/tmdatagrid 2.0.0-beta.4 → 2.0.0-beta.7

package/src/tmdatagrid/core/editEngine.ts

@@ -19,10 +19,21 @@ import type { TMDataGridColumnType } from "./filterOperators";
 import type { TMDataGridSize } from "./sizes";
 
 /**
- * How commits happen - one axis, each mode a thin policy over the same
- * engine. See `editMode` on `UseTMDataGridOptions`.
+ * What counts as a commit - one axis, each mode a thin policy over the same
+ * engine. Where a commit *goes* is the other axis, `editing.draft`: out to
+ * the consumer, or into the draft store. See `editing` on
+ * `UseTMDataGridOptions`.
+ *
+ * | Mode | Enter | Tab | Focus leaves | Escape |
+ * | ---- | ----- | --- | ------------ | ------ |
+ * | `"cell"` | commits | commits, caret moves on | commits | cancels |
+ * | `"cellConfirm"` | commits | keeps the draft, caret moves on | keeps the draft | cancels |
+ * | `"row"` | commits the row | the browser's, along the row | nothing | cancels the row |
+ *
+ * An entry row is row-shaped in every mode - every editable cell open at
+ * once, the browser's Tab between them, and an explicit ✓.
  */
-export type TMDataGridEditMode = "cell" | "cellConfirm" | "row" | "draft";
+export type TMDataGridEditMode = "cell" | "cellConfirm" | "row";
 
 /**
  * One editing row's live form. TanStack Form's `FormApi`, not a wrapper: the
@@ -82,6 +93,45 @@ export type TMDataGridRowValidators = {
   onSubmitAsyncDebounceMs?: number;
 };
 
+/** What `editing.tableValidators` is handed for one commit. */
+export type TMDataGridTableValidateArgs<
+  TData extends RowData = TMDataGridRowData,
+> = {
+  /** The committing row, as drafted. */
+  value: TData;
+  /** Its id - `addRow`'s temp id for an entry row. */
+  rowId: string;
+  /** Whether the row is an entry row, not yet in `data`. */
+  isNew: boolean;
+  /**
+   * The collection as it would stand if this commit landed: every data row
+   * overlaid with its draft where one is held (this row's `value` included),
+   * entry rows appended, deletion-marked rows removed. Unfiltered - a rule
+   * sees the whole collection whatever the view shows.
+   */
+  rows: ReadonlyArray<{ rowId: string; value: TData }>;
+};
+
+/**
+ * `editing.tableValidators` - rules that need the other rows: no duplicate
+ * keys, no overlapping ranges, allocations summing to a total. Run at every
+ * commit, after the row's own validators, and again per parked row during
+ * `saveDrafts` - so a draft invalidated by a later edit blocks the save.
+ *
+ * Return nothing to pass, a message, or Form's `{ form, fields }` shape;
+ * pathed issues land on the committing row's cells, pathless ones on the row.
+ * `onSubmit` runs first, and its failure stands without `onSubmitAsync`
+ * running.
+ */
+export type TMDataGridTableValidators<
+  TData extends RowData = TMDataGridRowData,
+> = {
+  onSubmit?: (args: TMDataGridTableValidateArgs<TData>) => unknown;
+  onSubmitAsync?: (
+    args: TMDataGridTableValidateArgs<TData>,
+  ) => unknown | Promise<unknown>;
+};
+
 /** One field's before/after across a commit. */
 export type TMDataGridEditChange = {
   /** Column the field maps back to, for consumers thinking in columns. */
@@ -108,8 +158,17 @@ export type TMDataGridEditCommitArgs<TData extends RowData> = {
 export type TMDataGridEditRowProjection = {
   /** Field names whose value differs from the original. */
   dirtyFields: ReadonlyArray<string>;
-  /** Field names carrying a validation error. */
+  /** Field names carrying a validation error, live or from a failed commit. */
   errorFields: ReadonlyArray<string>;
+  /**
+   * Those errors as text: what each cell editor is showing, plus what the
+   * row's last failed commit found. The second half is the reason this
+   * exists - Form clears a field's errors when its editor unmounts, so a row
+   * left invalid would go back to looking like an ordinary edited row. Such
+   * a message is dropped as soon as its field's value moves: the fix is what
+   * clears the mark.
+   */
+  errorMessages: ReadonlyArray<{ field: string; message: string }>;
   /** A row-level error - a pathless `.refine()`, or a rejected commit. */
   hasRowError: boolean;
   isSubmitting: boolean;
@@ -147,19 +206,18 @@ export type TMDataGridEditState = {
    * values stay in the row's form, this records which side of the line the
    * row is on. `begin` on one of these takes it back out, into form state.
    *
-   * Only draft mode parks; the immediate modes send a commit straight to the
-   * consumer and drop the form, so there this stays empty.
+   * Only `editing.draft` parks. Without it a commit goes straight to the
+   * consumer and the form is dropped, so this stays empty.
    */
   committedRowIds: ReadonlyArray<string>;
   /**
    * Rows being created, not yet in `data`. `committed` is the draft store's
    * add slice: the entry row passed its submit and renders as a value row
-   * until `begin` re-opens it. Under the immediate modes a commit adds
-   * through `onRowAdd` and the entry is dropped, so there it never turns
-   * `true`.
+   * until `begin` re-opens it. Without `editing.draft` a commit adds through
+   * `onRowAdd` and the entry is dropped, so it never turns `true`.
    */
   newRows: ReadonlyArray<{ tempId: string; committed: boolean }>;
-  /** The draft store's delete slice: rows marked deleted under draft mode. */
+  /** The draft store's delete slice: rows marked deleted, awaiting the save. */
   deletedRowIds: ReadonlyArray<string>;
 };
 
@@ -172,6 +230,30 @@ const EMPTY_EDIT_STATE: TMDataGridEditState = {
   deletedRowIds: [],
 };
 
+/**
+ * The rows still *open*: holding a live form nobody has decided yet.
+ *
+ * Narrower than {@link TMDataGridEditState.openRowIds}, which is every row
+ * with a form, the parked ones included. A row qualifies here when it is not
+ * parked in the draft store and there is something to lose - an entered row
+ * always counts, an existing one only once a value has moved.
+ *
+ * The order is the engine's: the order the forms were opened.
+ */
+export function getOpenRowIds(
+  state: TMDataGridEditState,
+): ReadonlyArray<string> {
+  return state.openRowIds.filter(
+    (rowId) =>
+      !state.committedRowIds.includes(rowId) &&
+      !state.newRows.some(
+        (newRow) => newRow.tempId === rowId && newRow.committed,
+      ) &&
+      (state.newRows.some((newRow) => newRow.tempId === rowId) ||
+        (state.rows[rowId]?.dirtyFields.length ?? 0) > 0),
+  );
+}
+
 type ErasedRow = Row<TMDataGridFeatures, TMDataGridRowData>;
 type ErasedColumn = Column<TMDataGridFeatures, TMDataGridRowData, unknown>;
 
@@ -289,7 +371,7 @@ export type TMDataGridColumnEditOptions = {
   mapValue?: TMDataGridEditValueMap;
 };
 
-/** A new row being committed - `onRowAdd`, and `submitAll`'s `added`. */
+/** A new row being committed - `onRowAdd`, and `saveDrafts`'s `created`. */
 export type TMDataGridRowAddArgs<TData extends RowData> = {
   /** The engine's placeholder id; the real id is the consumer's to mint. */
   tempId: string;
@@ -366,7 +448,15 @@ export type TMDataGridEditCommitDraftsArgs<TData extends RowData> =
 export type TMDataGridEditEngineContext = {
   table: TMDataGridTable<TMDataGridRowData>;
   editMode: TMDataGridEditMode;
+  /** `editing.draft` - whether a commit parks instead of reaching out. */
+  draft: boolean;
   rowValidators?: TMDataGridRowValidators;
+  tableValidators?: TMDataGridTableValidators;
+  /**
+   * `editing.columns` - the allowlist, or `undefined` for "every column that
+   * maps to a field".
+   */
+  editableColumnIds?: ReadonlyArray<string>;
   isRowEditable?: (row: ErasedRow) => boolean;
   onEditCommit?: (
     args: TMDataGridEditCommitArgs<TMDataGridRowData>,
@@ -468,6 +558,13 @@ export type TMDataGridEditApi<
   canEditCell: (row: ErasedRow, column: ErasedColumn) => boolean;
   /** Whether the row takes edits at all - the edit lane's pencil gate. */
   canEditRow: (row: ErasedRow) => boolean;
+  /**
+   * Whether the column takes edits at all, with no row in hand: it maps to a
+   * field, `editing.columns` lists it if that option is set, and
+   * `meta.edit.enabled` is not `false`. A per-row `enabled` predicate is the
+   * row's half of the question - `canEditCell` asks both.
+   */
+  isColumnEditable: (column: ErasedColumn) => boolean;
   /**
    * Opens an editor. In row mode the whole row opens either way and `columnId`
    * only says which cell takes the caret; `null` (the lane's pencil) leaves it
@@ -491,10 +588,10 @@ export type TMDataGridEditApi<
   cancelAll: () => void;
   /**
    * Submits every open row, as if each had been OK'd: a row that validates
-   * commits (into the draft store under draft mode, straight to the consumer
-   * under the immediate modes), a row that fails stays open with its errors.
-   * `true` when every row committed. Sends nothing to the consumer by itself
-   * under draft mode - that is `saveDrafts`.
+   * commits (into the draft store with `editing.draft` on, straight to the
+   * consumer without it), a row that fails stays open with its errors.
+   * `true` when every row committed. Under `editing.draft` it sends nothing
+   * to the consumer by itself - that is `saveDrafts`.
    */
   commitAll: () => Promise<boolean>;
   /**
@@ -513,13 +610,45 @@ export type TMDataGridEditApi<
   submitAll: () => Promise<boolean>;
   /** Writes the type's empty value into a cell and commits it - Delete. */
   clearCell: (rowId: string, columnId: string) => Promise<boolean>;
+  /**
+   * Writes one cell and commits the row - a typed edit without the typing,
+   * for toolbar actions and bulk fills. Under `editing.draft` the row parks
+   * in the draft store exactly as a hand-made edit does, so it carries the
+   * same change markers and the same per-row revert.
+   *
+   * The row need not be mounted; a row inside a collapsed group takes the
+   * write. Resolves `false` when the cell takes no edit - no such row or
+   * column, `editing.columns` excludes it, `meta.edit.enabled` is off, or the
+   * row is not editable - and when validation refuses the value, which leaves
+   * the row open carrying its errors.
+   *
+   * `value` is the stored value: no editor runs, so `meta.edit.mapValue`
+   * does not either. `meta.edit.validate` does.
+   */
+  setCellValue: (
+    rowId: string,
+    columnId: string,
+    value: unknown,
+  ) => Promise<boolean>;
+  /**
+   * {@link setCellValue} for several cells of one row, in a single commit -
+   * one consumer call and one draft entry rather than one per column. Keys
+   * are column ids.
+   *
+   * All or nothing: if any named cell takes no edit, nothing is written and
+   * this resolves `false`.
+   */
+  setRowValues: (
+    rowId: string,
+    values: Record<string, unknown>,
+  ) => Promise<boolean>;
   /**
    * Opens a new entry row (the sticky block under the header) seeded from
    * `newRowDefaults`. `values` overrides that seed key by key, so
    * `addRow()` opens a blank row and `addRow({ status: "draft" })` opens one
    * that starts filled in. Returns its temporary id - a form with no backing
-   * row yet. Committing it calls `onRowAdd` (immediate modes) or joins
-   * `submitAll`'s `added` (draft).
+   * row yet. Committing it calls `onRowAdd`, or parks it for `saveDrafts`
+   * under `editing.draft`.
    */
   addRow: (values?: Partial<TData>) => string;
   /**
@@ -528,8 +657,8 @@ export type TMDataGridEditApi<
    * `newRowDefaults` exactly as `addRow` does.
    *
    * `commit: true` submits each row as it lands, which is what an import
-   * wants: rows that validate commit (parked in the draft store under draft
-   * mode, added through `onRowAdd` under the immediate modes - once per row),
+   * wants: rows that validate commit (parked in the draft store under
+   * `editing.draft`, added through `onRowAdd` without it - once per row),
    * and rows that fail stay open in the entry block carrying their errors,
    * for the user to fix. The result says which went which way.
    */
@@ -538,10 +667,10 @@ export type TMDataGridEditApi<
     options?: TMDataGridAddRowsOptions,
   ) => Promise<TMDataGridAddRowsResult>;
   /**
-   * Deletes a row: `onRowDelete` straight away under the immediate modes;
-   * under draft it toggles the id in `deletedRowIds` - the row renders
-   * struck through until `submitAll` reports it. On an uncommitted entry
-   * row it just discards the entry.
+   * Deletes a row: `onRowDelete` straight away, or under `editing.draft` a
+   * toggle of the id in `deletedRowIds` - the row renders struck through
+   * until `saveDrafts` reports it. On an uncommitted entry row it just
+   * discards the entry.
    */
   deleteRow: (rowId: string) => void;
   /** Whether delete chrome makes sense - the lane's trash gate. */
@@ -584,6 +713,34 @@ function hasAnyError(errors: ReadonlyArray<unknown>): boolean {
   return errors.some((error) => error !== undefined && error !== null);
 }
 
+/**
+ * The first error as text, whatever shape the validator produced - TanStack
+ * Form keeps errors verbatim, so a Zod issue arrives as `{ message }`, a
+ * plain function's return arrives as it was, and a form-level schema's
+ * pathless issues arrive keyed under an empty path (`{ "": [issues] }`).
+ * This digs until it finds a message.
+ */
+export function firstErrorText(error: unknown): string | undefined {
+  if (error === null || error === undefined) return undefined;
+  if (typeof error === "string") return error;
+  if (Array.isArray(error)) {
+    for (const entry of error) {
+      const text = firstErrorText(entry);
+      if (text !== undefined) return text;
+    }
+    return undefined;
+  }
+  if (typeof error === "object") {
+    const message = (error as { message?: unknown }).message;
+    if (typeof message === "string") return message;
+    for (const value of Object.values(error)) {
+      const text = firstErrorText(value);
+      if (text !== undefined) return text;
+    }
+  }
+  return undefined;
+}
+
 /**
  * The triggers a submit runs, in the order Form would: a value that fails its
  * column's `onChange` rule fails the submit too.
@@ -658,10 +815,18 @@ export function createEditEngine(
     /** Set by the wrapped onSubmit when the consumer's commit resolved. */
     lastSubmitOk: boolean;
     /**
-     * Draft mode's park: this submit validates and puts the row in the draft
-     * store instead of calling the consumer. Set by `commit` per attempt -
-     * `true` only under draft outside `saveDrafts`, which is what closes the
-     * per-row escape hatches (the lane's ✓, Delete-to-clear) at the engine.
+     * What the last failed commit found, field by field, with the value it
+     * found it on. Form clears a field's errors when its editor unmounts, so
+     * without this a row that failed on the way out would keep its draft and
+     * lose the reason. `project` drops an entry once its value has moved.
+     */
+    submitErrors: Array<{ field: string; value: unknown; message: string }>;
+    /**
+     * The park: this submit validates and puts the row in the draft store
+     * instead of calling the consumer. Set by `commit` per attempt - `true`
+     * only while `editing.draft` is on and outside `saveDrafts`, which is
+     * what closes the per-row escape hatches (the lane's ✓,
+     * Delete-to-clear) at the engine.
      */
     parkOnly: boolean;
     /** A commit already running - Enter and blur race on the same edit. */
@@ -684,15 +849,22 @@ export function createEditEngine(
   let draftAddCollector: Array<TMDataGridRowAddArgs<TMDataGridRowData>> | null =
     null;
 
+  /**
+   * The column's half of the rule, with no row in hand: it is a consumer
+   * column mapping to a field, `editing.columns` lists it if that is set, and
+   * `meta.edit.enabled` has not switched it off outright. A per-row predicate
+   * on `enabled` is the row's half and is not asked here.
+   */
+  const isColumnEditable = (column: ErasedColumn): boolean => {
+    if (isControlColumn(column.id)) return false;
+    if (getEditFieldName(column) === null) return false;
+    const allowed = getContext().editableColumnIds;
+    if (allowed !== undefined && !allowed.includes(column.id)) return false;
+    return !isColumnEditSwitchedOff(column);
+  };
+
   const editableColumns = (): Array<ErasedColumn> =>
-    getContext()
-      .table.getAllLeafColumns()
-      .filter(
-        (column) =>
-          !isControlColumn(column.id) &&
-          !isColumnEditSwitchedOff(column) &&
-          getEditFieldName(column) !== null,
-      );
+    getContext().table.getAllLeafColumns().filter(isColumnEditable);
 
   /**
    * Every column's `meta.edit.validate`, run against a row's values.
@@ -736,9 +908,124 @@ export function createEditEngine(
   };
 
   /**
-   * The row's `validators`, with column validation folded into the submit
-   * pass. The consumer's own `rowValidators` are passed through untouched
-   * except for `onSubmitAsync`, which now also carries the column rules.
+   * The collection as a table validator sees it: every data row overlaid
+   * with its draft where a form holds one, entry rows appended, and rows
+   * marked deleted removed. The committing row contributes the values being
+   * submitted, not what `data` still says. Built from the core row model, so
+   * it is unfiltered and never contains group rows.
+   */
+  const mergedRows = (
+    rowId: string,
+    value: TMDataGridRowData,
+    isNew: boolean,
+  ): Array<{ rowId: string; value: TMDataGridRowData }> => {
+    const deleted = new Set(store.state.deletedRowIds);
+    const rows: Array<{ rowId: string; value: TMDataGridRowData }> = [];
+    for (const row of getContext().table.getCoreRowModel().flatRows) {
+      if (deleted.has(row.id)) continue;
+      if (row.id === rowId) {
+        rows.push({ rowId, value });
+        continue;
+      }
+      const held = forms.get(row.id);
+      rows.push({
+        rowId: row.id,
+        value:
+          held === undefined
+            ? (row.original as TMDataGridRowData)
+            : (held.form.state.values as TMDataGridRowData),
+      });
+    }
+    for (const newRow of store.state.newRows) {
+      if (newRow.tempId === rowId) continue;
+      const held = forms.get(newRow.tempId);
+      if (held === undefined || deleted.has(newRow.tempId)) continue;
+      rows.push({
+        rowId: newRow.tempId,
+        value: held.form.state.values as TMDataGridRowData,
+      });
+    }
+    if (isNew) rows.push({ rowId, value });
+    return rows;
+  };
+
+  /**
+   * Runs `editing.tableValidators` for one commit. `onSubmit` first; its
+   * failure stands and `onSubmitAsync` is not consulted, mirroring how the
+   * column triggers short-circuit.
+   */
+  const runTableValidators = async (
+    value: TMDataGridRowData,
+    rowId: string,
+    isNew: boolean,
+  ): Promise<unknown> => {
+    const validators = getContext().tableValidators;
+    if (
+      validators?.onSubmit === undefined &&
+      validators?.onSubmitAsync === undefined
+    ) {
+      return undefined;
+    }
+    const args: TMDataGridTableValidateArgs = {
+      value,
+      rowId,
+      isNew,
+      rows: mergedRows(rowId, value, isNew),
+    };
+    const sync = validators.onSubmit?.(args);
+    if (isValidationError(sync)) return sync;
+    return await validators.onSubmitAsync?.(args);
+  };
+
+  /**
+   * One submit pass's results folded into Form's error shape. A single
+   * source passes through untouched (its own shape preserved); several merge
+   * into `{ form, fields }`, the later source winning a field collision and
+   * the form slot alike.
+   */
+  const mergeSubmitResults = (
+    results: ReadonlyArray<unknown>,
+    fields: Record<string, unknown> | undefined,
+  ): unknown => {
+    const errors = results.filter(isValidationError);
+    if (errors.length === 0) {
+      return fields === undefined ? undefined : { fields };
+    }
+    if (errors.length === 1) {
+      const only = errors[0];
+      if (fields === undefined) return only;
+      if (typeof only === "object" && only !== null) {
+        const shape = only as { fields?: Record<string, unknown> };
+        return { ...shape, fields: { ...fields, ...(shape.fields ?? {}) } };
+      }
+      return { form: only, fields };
+    }
+    let form: unknown;
+    let mergedFields: Record<string, unknown> = { ...(fields ?? {}) };
+    for (const error of errors) {
+      if (typeof error === "object" && error !== null) {
+        const shape = error as {
+          form?: unknown;
+          fields?: Record<string, unknown>;
+        };
+        if (isValidationError(shape.form)) form = shape.form;
+        mergedFields = { ...mergedFields, ...(shape.fields ?? {}) };
+      } else {
+        form = error;
+      }
+    }
+    const merged: { form?: unknown; fields?: Record<string, unknown> } = {};
+    if (form !== undefined) merged.form = form;
+    if (Object.keys(mergedFields).length > 0) merged.fields = mergedFields;
+    return merged;
+  };
+
+  /**
+   * The row's `validators`, with column validation and the table rules folded
+   * into the submit pass. The consumer's own `rowValidators` are passed
+   * through untouched except for `onSubmitAsync`, which now also carries the
+   * column rules and `editing.tableValidators` - later sources win a merge,
+   * so the order is columns, then the table rules, then the row's own.
    */
   const composeValidators = (
     rowId: string,
@@ -752,30 +1039,14 @@ export function createEditEngine(
     return {
       ...rowValidators,
       onSubmitAsync: async (args: { value: unknown }) => {
+        const value = args.value as TMDataGridRowData;
         const fromConsumer =
           consumerAsync === undefined
             ? undefined
             : await (consumerAsync as (a: unknown) => unknown)(args);
-        const fields = await validateColumnFields(
-          args.value as TMDataGridRowData,
-          rowId,
-          isNew,
-        );
-        if (fields === undefined) return fromConsumer;
-        if (!isValidationError(fromConsumer)) return { fields };
-        // The consumer's row-level result stands alongside the column
-        // errors: theirs keeps whatever shape it had, ours lands on fields.
-        if (typeof fromConsumer === "object" && fromConsumer !== null) {
-          const consumerShape = fromConsumer as {
-            form?: unknown;
-            fields?: Record<string, unknown>;
-          };
-          return {
-            ...consumerShape,
-            fields: { ...fields, ...(consumerShape.fields ?? {}) },
-          };
-        }
-        return { form: fromConsumer, fields };
+        const fromTable = await runTableValidators(value, rowId, isNew);
+        const fields = await validateColumnFields(value, rowId, isNew);
+        return mergeSubmitResults([fromTable, fromConsumer], fields);
       },
     };
   };
@@ -799,23 +1070,33 @@ export function createEditEngine(
 
   const project = (entry: FormEntry): TMDataGridEditRowProjection => {
     const state = entry.form.state;
-    const errorFields = Object.entries(state.fieldMeta)
-      .filter(
-        ([name, meta]) =>
-          // The empty path is a pathless (row-level) issue's landing spot -
-          // it belongs to `hasRowError`, not to any cell's marker.
-          name !== "" &&
-          hasAnyError((meta as { errors: ReadonlyArray<unknown> }).errors),
-      )
-      .map(([name]) => name);
+    const values = state.values as TMDataGridRowData;
+    const live = Object.entries(state.fieldMeta).flatMap(([name, meta]) => {
+      // The empty path is a pathless (row-level) issue's landing spot - it
+      // belongs to `hasRowError`, not to any cell's marker.
+      if (name === "") return [];
+      const errors = (meta as { errors: ReadonlyArray<unknown> }).errors;
+      if (!hasAnyError(errors)) return [];
+      return [{ field: name, message: firstErrorText(errors) ?? "" }];
+    });
+    // What a closed editor left behind, minus everything the user has since
+    // changed - editing the field is the answer to its message.
+    const kept = entry.submitErrors.filter(
+      (error) =>
+        !live.some((current) => current.field === error.field) &&
+        sameValue(getBy(values, error.field), error.value),
+    );
+    const errorMessages = [
+      ...live,
+      ...kept.map(({ field, message }) => ({ field, message })),
+    ];
     return {
-      dirtyFields: diff(entry, state.values as TMDataGridRowData).map(
-        (change) => change.field,
-      ),
-      errorFields,
+      dirtyFields: diff(entry, values).map((change) => change.field),
+      errorFields: errorMessages.map((error) => error.field),
+      errorMessages,
       hasRowError: hasAnyError(state.errors),
       isSubmitting: state.isSubmitting,
-      values: state.values as TMDataGridRowData,
+      values,
     };
   };
 
@@ -898,6 +1179,7 @@ export function createEditEngine(
       isNew,
       committed: false,
       lastSubmitOk: false,
+      submitErrors: [],
       parkOnly: false,
       pendingCommit: null,
       unsubscribe: () => {},
@@ -984,8 +1266,7 @@ export function createEditEngine(
   const canEditCell = (row: ErasedRow, column: ErasedColumn): boolean => {
     const context = getContext();
     if (row.getIsGrouped()) return false;
-    if (isControlColumn(column.id)) return false;
-    if (getEditFieldName(column) === null) return false;
+    if (!isColumnEditable(column)) return false;
     if (!isColumnEditableForRow(column, row)) return false;
     if (context.isRowEditable !== undefined && !context.isRowEditable(row)) {
       return false;
@@ -1002,6 +1283,26 @@ export function createEditEngine(
     }
   };
 
+  /**
+   * The row's field errors as they stand, with the value each was found on.
+   * Read straight after a failed submit, while every editor is still mounted
+   * and Form still holds what its validators said.
+   */
+  const takeFieldErrors = (
+    entry: FormEntry,
+  ): Array<{ field: string; value: unknown; message: string }> => {
+    const values = entry.form.state.values as TMDataGridRowData;
+    return Object.entries(entry.form.state.fieldMeta).flatMap(
+      ([field, meta]) => {
+        if (field === "") return [];
+        const errors = (meta as { errors: ReadonlyArray<unknown> }).errors;
+        const message = hasAnyError(errors) ? firstErrorText(errors) : undefined;
+        if (message === undefined) return [];
+        return [{ field, value: getBy(values, field), message }];
+      },
+    );
+  };
+
   const commit = async (rowId: string): Promise<boolean> => {
     const entry = forms.get(rowId);
     if (entry === undefined) return true;
@@ -1023,14 +1324,21 @@ export function createEditEngine(
     // block `canSubmit` forever. The validator puts back whatever still holds.
     clearFormSourcedFieldErrors(entry.form);
     entry.lastSubmitOk = false;
-    entry.parkOnly = getContext().editMode === "draft" && !savingDrafts;
+    entry.submitErrors = [];
+    entry.parkOnly = getContext().draft && !savingDrafts;
     entry.pendingCommit = (async () => {
       try {
         await entry.form.handleSubmit();
       } finally {
         entry.pendingCommit = null;
       }
-      if (!entry.lastSubmitOk) return false;
+      if (!entry.lastSubmitOk) {
+        // Snapshot before the caller closes the editor: the field errors go
+        // with it, and the row is about to be left carrying them.
+        entry.submitErrors = takeFieldErrors(entry);
+        publishRow(rowId);
+        return false;
+      }
       if (entry.parkOnly) {
         // Into the draft store: the row's values stay in its form, and the
         // grid records that they are decided. An entry row renders as a
@@ -1052,7 +1360,8 @@ export function createEditEngine(
 
   const beginOn = (rowId: string, columnId: string | null) => {
     // An entry row has no backing row in the table; opening one re-arms its
-    // editors - under draft, that is how a confirmed row is edited again.
+    // editors - with `editing.draft` on, that is how a parked row is edited
+    // again.
     const entryForm = forms.get(rowId);
     if (entryForm?.isNew === true) {
       entryForm.committed = false;
@@ -1083,11 +1392,19 @@ export function createEditEngine(
     // | Mode | Another row open |
     // | ---- | ---------------- |
     // | cell | committed - Sheets; a failed commit keeps holding the edit |
-    // | row, cellConfirm, draft | accumulates. Every draft waits for its own
-    //   save, so a second row opening can neither discard the first nor be
-    //   refused by it - nothing about one row's form bears on another's |
+    // | row, cellConfirm | accumulates. Every draft waits for its own save,
+    //   so a second row opening can neither discard the first nor be refused
+    //   by it - nothing about one row's form bears on another's |
+    //
+    // A parked row is not "open": it has had its submit and is waiting for
+    // the save, so it is skipped rather than put through a second one. An
+    // entry row is skipped too - it is row-shaped in every mode, and its ✓
+    // is the decision, so the sweep must not add a half-typed row.
     if (editMode === "cell") {
-      const openElsewhere = [...forms.keys()].find((id) => id !== rowId);
+      const openElsewhere = [...forms.keys()].find((id) => {
+        const other = forms.get(id);
+        return id !== rowId && other?.committed !== true && other?.isNew !== true;
+      });
       if (openElsewhere !== undefined) {
         void commit(openElsewhere).then((ok) => {
           if (ok) beginOn(rowId, columnId);
@@ -1184,7 +1501,7 @@ export function createEditEngine(
       return;
     }
     const context = getContext();
-    if (context.editMode === "draft") {
+    if (context.draft) {
       // A toggle: the second press unmarks - the mark is a draft too.
       store.setState((prev) => ({
         ...prev,
@@ -1202,7 +1519,7 @@ export function createEditEngine(
 
   const canDeleteRows = (): boolean => {
     const context = getContext();
-    if (context.editMode === "draft") {
+    if (context.draft) {
       return (
         context.onRowDelete !== undefined ||
         context.onSaveDrafts !== undefined
@@ -1244,7 +1561,7 @@ export function createEditEngine(
 
   const saveDrafts = (): Promise<boolean> => {
     if (saveInFlight !== null) return saveInFlight;
-    // While this runs, `commit` really commits - under draft it parks
+    // While this runs, `commit` really commits - `editing.draft` parks
     // otherwise. Single-threaded flag, same idiom as the collectors.
     savingDrafts = true;
     saveInFlight = saveDraftsInner().finally(() => {
@@ -1351,25 +1668,81 @@ export function createEditEngine(
     return committedOk && savedOk;
   };
 
-  const clearCell = async (
+  /**
+   * The write path behind `clearCell`, `setCellValue` and `setRowValues`:
+   * fill the row's own form and commit it, exactly as a ✓ on an open editor
+   * would. Uses the form already open on the row when there is one, so a
+   * programmatic write joins an edit in progress rather than discarding it.
+   *
+   * No editor is involved, so `meta.edit.mapValue` does not run - the caller
+   * writes the stored value itself. Validation is untouched: this is the same
+   * `commit`, so `meta.edit.validate` and `editing.rowValidators` still decide
+   * whether the row lands, and a failure leaves the row open carrying its
+   * errors.
+   */
+  const writeFields = async (
     rowId: string,
-    columnId: string,
+    writes: ReadonlyArray<{ field: string; value: unknown }>,
   ): Promise<boolean> => {
-    const context = getContext();
     const row = getRow(rowId);
-    const column = context.table.getColumn(columnId);
-    if (row === undefined || column === undefined) return false;
-    if (!canEditCell(row, column)) return false;
-    const field = getEditFieldName(column);
-    if (field === null) return false;
+    if (row === undefined) return false;
+    if (writes.length === 0) return true;
     const entry = forms.get(rowId) ?? createForm(rowId, row.original, false);
-    entry.form.setFieldValue(
-      field as never,
-      clearedValueForType(column.columnDef.meta?.type ?? "string") as never,
-    );
+    for (const { field, value } of writes) {
+      entry.form.setFieldValue(field as never, value as never);
+    }
     return commit(rowId);
   };
 
+  /** The field a cell writes to, or `null` when that cell takes no edit. */
+  const writableField = (rowId: string, columnId: string): string | null => {
+    const row = getRow(rowId);
+    const column = getContext().table.getColumn(columnId);
+    if (row === undefined || column === undefined) return null;
+    if (!canEditCell(row, column)) return null;
+    return getEditFieldName(column);
+  };
+
+  const clearCell = async (
+    rowId: string,
+    columnId: string,
+  ): Promise<boolean> => {
+    const column = getContext().table.getColumn(columnId);
+    const field = writableField(rowId, columnId);
+    if (field === null || column === undefined) return false;
+    return writeFields(rowId, [
+      {
+        field,
+        value: clearedValueForType(column.columnDef.meta?.type ?? "string"),
+      },
+    ]);
+  };
+
+  const setCellValue = async (
+    rowId: string,
+    columnId: string,
+    value: unknown,
+  ): Promise<boolean> => {
+    const field = writableField(rowId, columnId);
+    if (field === null) return false;
+    return writeFields(rowId, [{ field, value }]);
+  };
+
+  const setRowValues = async (
+    rowId: string,
+    values: Record<string, unknown>,
+  ): Promise<boolean> => {
+    const writes: Array<{ field: string; value: unknown }> = [];
+    for (const [columnId, value] of Object.entries(values)) {
+      const field = writableField(rowId, columnId);
+      // All or nothing: one cell that takes no edit fails the call before
+      // anything is written, so a bulk action cannot half-apply unnoticed.
+      if (field === null) return false;
+      writes.push({ field, value });
+    }
+    return writeFields(rowId, writes);
+  };
+
   return {
     store,
     get state() {
@@ -1378,6 +1751,7 @@ export function createEditEngine(
     getForm: (rowId) => forms.get(rowId)?.form,
     canEditCell,
     canEditRow,
+    isColumnEditable,
     begin,
     commit,
     cancel,
@@ -1387,6 +1761,8 @@ export function createEditEngine(
     saveDrafts,
     submitAll,
     clearCell,
+    setCellValue,
+    setRowValues,
     addRow,
     addRows,
     deleteRow,