apex-grid 3.5.0 → 3.6.0

package/controllers/editing.d.ts

@@ -1,6 +1,6 @@
 import type { ReactiveController } from 'lit';
 import type { ColumnConfiguration, EditMode, EditTrigger, GridHost, Keys } from '../internal/types.js';
-import type { HistoryController } from './history.js';
+import type { EditCommand, HistoryController } from './history.js';
 /**
  * The default editing configuration used when the grid has none set.
  */
@@ -10,11 +10,17 @@ export declare const DEFAULT_EDITING_CONFIG: Readonly<{
     trigger: EditTrigger;
 }>;
 interface ActiveCell<T> {
+    /**
+     * The record's view index (matches {@link ApexGrid.pageItems}), refreshed
+     * after every grid update; `-1` for a pinned record or one on another page.
+     */
     rowIndex: number;
     columnKey: Keys<T>;
     /**
      * Live reference to the underlying record (preserved through the pipeline so
-     * the source array can be mutated on commit).
+     * the source array can be mutated on commit). The edit is bound to this
+     * record, never to the view index, so a sort, filter, page or data change
+     * cannot move the editor onto another record.
      */
     data: T;
 }
@@ -39,6 +45,12 @@ export interface ApplyCellEditOptions {
      * previously valid value during undo/redo).
      */
     validate?: boolean;
+    /**
+     * Emit the cancellable `cellValueChanging` before writing. Defaults to
+     * `true`. Set to `false` when the caller already ran the gate for this
+     * write (a row commit gates every cell before writing any).
+     */
+    gate?: boolean;
 }
 /**
  * Reactive controller backing inline cell + row editing.
@@ -56,7 +68,10 @@ export declare class EditingController<T extends object> implements ReactiveCont
     protected history?: HistoryController<T> | undefined;
     /** The cell currently in edit mode, or `null`. */
     activeCell: ActiveCell<T> | null;
-    /** The row currently in edit mode (row mode only), or `null`. */
+    /**
+     * The row currently in edit mode (row mode only), or `null`. Bound to its
+     * record like {@link activeCell}.
+     */
     activeRow: {
         rowIndex: number;
         data: T;
@@ -64,18 +79,27 @@ export declare class EditingController<T extends object> implements ReactiveCont
     /**
      * Pending values keyed by column for the currently editing row. Populated in
      * row mode as the user edits individual cells; flushed on
-     * {@link commitRow}.
+     * {@link commitRow}. Holds only values that differ from the record.
      */
     pending: Map<Keys<T>, unknown>;
     /**
-     * Monotonic token bumped whenever the validation-error set changes. Forwarded
-     * down to each cell as a reactive property so a validation-only change
-     * re-renders the affected cells (toggling `aria-invalid` and the error node)
-     * without re-running the data pipeline. Stays `0` until the first failure.
+     * Monotonic token bumped whenever the validation-error set or the staged
+     * row-mode values change. Forwarded down to each cell as a reactive property
+     * so such a change re-renders the affected cells (toggling `aria-invalid`
+     * and the error node, showing a staged value) without re-running the data
+     * pipeline. Stays `0` until the first failure or staged value.
      */
     get validationVersion(): number;
     constructor(host: GridHost<T>, history?: HistoryController<T> | undefined);
     hostConnected(): void;
+    /**
+     * Keeps an open edit bound to its record after the view changed: refreshes
+     * the reported view index, and cancels the edit when the record left the
+     * view (removed, filtered out, replaced by a copy), so no hidden editor can
+     * commit later. A record on another page or in a pinned band stays open.
+     * Runs only while an edit is open.
+     */
+    hostUpdated(): void;
     /**
      * Whether editing is enabled at the grid level.
      */
@@ -93,22 +117,29 @@ export declare class EditingController<T extends object> implements ReactiveCont
      */
     isEditable(column: ColumnConfiguration<T>): boolean;
     /**
-     * Whether the cell `(rowIndex, columnKey)` is currently in edit mode.
+     * Whether the cell `(data, columnKey)` is currently in edit mode.
      */
-    isCellEditing(rowIndex: number, columnKey: Keys<T>): boolean;
+    isCellEditing(data: T, columnKey: Keys<T>): boolean;
     /**
-     * Whether the given row is currently in edit mode (row mode).
+     * Begins editing the cell at `(rowIndex, columnKey)`, where `rowIndex` is
+     * the view index (matches {@link ApexGrid.pageItems}). See
+     * {@link editRecord}.
      */
-    isRowEditing(rowIndex: number): boolean;
+    editCell(rowIndex: number, columnKey: Keys<T>): Promise<boolean>;
     /**
-     * Begins editing the cell at `(rowIndex, columnKey)`. Auto-commits any cell
-     * already in edit mode (in cell mode); in row mode it switches the active
-     * cell within the same row and rejects cross-row moves.
+     * Begins editing the `columnKey` cell of the record `data`, a body or a
+     * pinned row. Auto-commits any cell already in edit mode (in cell mode); in
+     * row mode it stages that cell and commits the row first on a cross-row
+     * move.
      *
-     * @returns `true` if edit started, `false` if rejected (column not editable
-     * or row-mode constraint violated).
+     * @returns `true` if edit started, `false` if rejected (column not editable,
+     * `data` a row a feature synthesized, the in-flight cell's commit was
+     * rejected, or the previous row could not be committed). A rejected commit
+     * keeps the in-flight editor open, unless its record is on another page:
+     * an edit the user cannot see or correct is cancelled instead, so it cannot
+     * block every other edit.
      */
-    editCell(rowIndex: number, columnKey: Keys<T>): Promise<boolean>;
+    editRecord(data: T, columnKey: Keys<T>): Promise<boolean>;
     /**
      * Begins editing the given row in row mode. Emits `rowEditStarted` on
      * success. No-op in cell mode.
@@ -133,8 +164,18 @@ export declare class EditingController<T extends object> implements ReactiveCont
      * Runs the column's declarative validators against a candidate value and
      * returns the collected error messages (empty when the value passes or the
      * column has no validators).
+     *
+     * @param row - What validators see as `ctx.data`: the record itself, or in
+     * a row commit the staged row (the record with the staged values applied).
      */
-    validateCell(rowIndex: number, columnKey: Keys<T>, data: T, value: unknown): string[];
+    validateCell(rowIndex: number, columnKey: Keys<T>, data: T, value: unknown, row?: T): string[];
+    /**
+     * The staged row-mode values of `data` keyed by column, or `null` when
+     * `data` is not the row in edit. Cells read it to show staged values.
+     */
+    stagedValues(data: T): ReadonlyMap<Keys<T>, unknown> | null;
+    /** The command staged with the row edit of `data` for `columnKey`, if any. */
+    stagedEffect(data: T, columnKey: Keys<T>): EditCommand | undefined;
     /**
      * The current validation errors for `(data, columnKey)`, or `null` when the
      * cell is valid. Read by {@link ApexGridCell} to drive `aria-invalid` and the
@@ -149,26 +190,51 @@ export declare class EditingController<T extends object> implements ReactiveCont
      * Clears every validation error recorded for a record (all columns).
      */
     clearRecordErrors(data: T): void;
+    /**
+     * Records the open editor's current, uncommitted value. A later
+     * {@link commitCell} without an argument commits it. No-op while no cell is
+     * in edit mode.
+     */
+    setDraft(value: unknown): void;
+    /**
+     * The draft held for the open editor of `(data, columnKey)`, or `null` when
+     * that cell is not in edit or nothing was typed. An editor rendered again
+     * for an edit already open (its record paged or scrolled back into view)
+     * resumes from it, so it shows what a bare {@link commitCell} commits.
+     */
+    heldDraft(data: T, columnKey: Keys<T>): {
+        value: unknown;
+    } | null;
     /**
      * Commits a candidate value for the currently editing cell. In cell mode the
      * value is written through to {@link ApexGrid.data}; in row mode it is staged
      * in {@link pending} until {@link commitRow} is called.
      *
-     * @param value - The candidate value.
+     * @param args - The candidate value, committed as given (`undefined`
+     * included). Called with no argument, it commits the open editor's draft
+     * (see {@link setDraft}), or keeps the current value when nothing was typed.
+     * An optional command rides with the value: it runs once the value is
+     * accepted (or, in row mode, when the row commits), joins the same undo
+     * step, and is dropped when the edit is rejected or the row cancelled.
      * @returns `true` if accepted (or staged), `false` if rejected by
-     * `cellValueChanging.preventDefault()`.
+     * `cellValueChanging.preventDefault()` or a validator.
      */
-    commitCell(value?: unknown): Promise<boolean>;
+    commitCell(...args: [value?: unknown, effect?: EditCommand]): Promise<boolean>;
     /**
-     * Writes `value` directly to the cell at `(rowIndex, columnKey)` without
-     * entering edit mode. Used by interactive display widgets (e.g. the boolean
-     * checkbox) that handle their own input. Goes through the same
-     * `cellValueChanging` / `cellValueChanged` event path as a normal commit.
+     * Writes `value` directly to the `columnKey` cell of the record `data` (a
+     * body or a pinned row) without entering edit mode. Used by interactive
+     * display widgets (e.g. the boolean checkbox) that handle their own input.
+     * Goes through the same `cellValueChanging` / `cellValueChanged` event path
+     * as a normal commit. In row mode the value joins the row's staged values
+     * instead (opening the row edit first), so it commits or cancels with the
+     * rest of the row.
      *
-     * @returns `true` if the value was applied, `false` if rejected by
-     * `cellValueChanging.preventDefault()` or the column is not editable.
+     * @returns `true` if the value was applied (or staged), `false` if rejected
+     * by `cellValueChanging.preventDefault()`, a validator, a previous row that
+     * could not be committed, the column is not editable, or `data` is a row a
+     * feature synthesized (as in {@link editRecord}).
      */
-    commitImmediate(rowIndex: number, columnKey: Keys<T>, value: unknown): Promise<boolean>;
+    commitImmediate(data: T, columnKey: Keys<T>, value: unknown): Promise<boolean>;
     /**
      * Discards the current cell edit without writing. In row mode the row edit
      * stays open.
@@ -178,8 +244,15 @@ export declare class EditingController<T extends object> implements ReactiveCont
      * Commits all pending edits for the currently editing row. Emits
      * `cellValueChanging` for every changed cell and `rowEditEnded` at the end.
      *
-     * @returns `true` if the row was applied, `false` if any cell change was
-     * cancelled (the row remains in edit mode in that case).
+     * @remarks
+     * Validators see the staged row as `ctx.data`, and once any value is staged
+     * the other editable cells of the row are validated too, so a cross-field
+     * rule judges the row being saved. Every cell passes its `cellValueChanging`
+     * gate before any is written: an invalid or cancelled cell aborts the whole
+     * row.
+     *
+     * @returns `true` if the row was applied, `false` if any cell failed
+     * validation or its change was cancelled (the row remains in edit mode).
      */
     commitRow(): Promise<boolean>;
     /**
@@ -187,11 +260,5 @@ export declare class EditingController<T extends object> implements ReactiveCont
      * Emits `rowEditEnded` with `committed: false`.
      */
     cancelRow(): void;
-    /**
-     * Returns the current pending or committed value for `(rowIndex, columnKey)`.
-     * Cells in row mode read this so unstaged-but-pending values are reflected
-     * during the edit.
-     */
-    getValue(rowIndex: number, columnKey: Keys<T>): unknown;
 }
 export {};