@bmsuisse/datagrid 0.29.0 → 0.31.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode, ReactElement, ComponentType, RefObject } from 'react';
+import { ReactNode, ReactElement, MouseEvent, ComponentType, RefObject } from 'react';
 import { ColumnSizingState, RowData } from '@tanstack/react-table';
 export { ColumnSizingState } from '@tanstack/react-table';
 
@@ -209,9 +209,21 @@ interface BaseColumn<TRow> {
      * this cell, including the default editors' own `onChange`.
      */
     validateEdit?: (value: unknown, row: TRow) => string | undefined;
+    /**
+     * Overrides the plain-text form of this column's value used when copying a
+     * `cellEditing`-mode selection to the clipboard. Defaults to the same
+     * `defaultFormat` display text every other rendering path already uses —
+     * only needed for a column with a custom `cell` whose displayed content
+     * isn't a faithful plain-text rendering of the underlying value (e.g. a
+     * badge/icon), the same situation `renderFilter`/`renderEditCell` exist to
+     * override for their own concerns.
+     */
+    formatForClipboard?: (value: unknown, row: TRow) => string;
 }
 type StringColumn<TRow> = BaseColumn<TRow> & {
     type: "string";
+    /** Opt-in: defaults to false. Selects `MultilineStringEditor` (an auto-growing `<textarea>`) instead of `StringEditor`'s single-line `<Input>` for this column's default edit widget — same variant-flag idiom as `NumberColumn.currency`, not a separate `type`. Has no effect on static (non-editing) display, which stays whatever `column.cell`/`defaultFormat` already renders. */
+    multiline?: boolean;
 };
 type NumberColumn<TRow> = BaseColumn<TRow> & {
     type: "number" | "currency";
@@ -658,6 +670,16 @@ declare function DateEditor<TRow>({ column, rowId, value, onChange, error, autoF
 /** Default inline editor for `type: "enum"` columns: a single-value select over `column.options`. */
 declare function EnumEditor<TRow>({ column, rowId, value, onChange, error, autoFocus, }: EditWidgetProps<EnumColumn<TRow>>): ReactElement;
 
+/**
+ * Default inline editor for a `type: "string"` column with `multiline: true`:
+ * an auto-growing `<textarea>` in place of `StringEditor`'s single-line
+ * `<Input>`. Dispatched by `registry.tsx`'s existing `case "string":` branch
+ * — a rendering choice, not a new column `type` — so it works identically
+ * under both `DataGridProps.editing` (row-batch) and `.cellEditing`
+ * (immediate-apply) modes with zero extra wiring in either.
+ */
+declare function MultilineStringEditor<TRow>({ column, rowId, value, onChange, error, autoFocus, }: EditWidgetProps<StringColumn<TRow>>): ReactElement;
+
 /**
  * Default inline editor for `type: "number"` / `type: "currency"` columns: a
  * native number input. Emits `null` for an emptied field (not `NaN` or `""`)
@@ -784,6 +806,375 @@ interface EditingBarProps<TRow> {
  */
 declare function EditingBar<TRow>({ editing, pendingRowCount, editErrors, onSave, onDiscard, testIdPrefix, }: EditingBarProps<TRow>): ReactElement;
 
+/**
+ * Identifies one cell by stable row id + column id — never by DOM node or
+ * virtualization index, so a selection/edit survives a virtualized row
+ * mounting, unmounting, and remounting as the grid scrolls.
+ */
+interface CellAddress {
+    rowId: string;
+    columnId: string;
+}
+/**
+ * A rectangular block of cells, expressed as its two corners: `anchor` is
+ * the cell where the selection/drag started, `focus` is the other corner —
+ * the one that moves as you shift+arrow or drag the mouse. Either corner can
+ * be the top-left or bottom-right one; use `normalizeRange` (in
+ * `rangeUtils.ts`) to resolve that.
+ */
+interface CellRange {
+    anchor: CellAddress;
+    focus: CellAddress;
+}
+/**
+ * One committed cell edit — from a typed commit, a paste, or a fill-drag.
+ * `previousValue` isn't read by anything in this pass; it's carried now so a
+ * future undo/redo can be built on top of the same `CellChange` log without
+ * a breaking API change later.
+ */
+interface CellChange<TRow> {
+    rowId: string;
+    row: TRow;
+    columnId: string;
+    previousValue: unknown;
+    value: unknown;
+}
+/**
+ * Enables the "true spreadsheet" cell-editing mode on `<DataGrid>`: click or
+ * type directly into any cell, range-select, paste, fill-handle — every
+ * change applies immediately, with no row-level Save/Discard gate. This is a
+ * different state machine from `DataGridProps.editing`'s accumulate-then-save
+ * workflow, not a superset of it — set at most one of `editing`/`cellEditing`
+ * on a given `<DataGrid>`; `editing` is ignored once `cellEditing` is set.
+ */
+interface CellEditingOptions<TRow> {
+    /**
+     * Called once per gesture — one typed-cell commit, one paste, one
+     * fill-drag — with every cell that gesture changed. There's no debouncing:
+     * each gesture's full change set is computed synchronously before this
+     * fires, so a single keystroke commit is one `[change]`, and pasting a
+     * 50-cell block is one call with 50 entries.
+     *
+     * Fire-and-forget: a rejection does not roll back the grid's own local
+     * display of the new values — there's no "pending" state to roll back to
+     * in an immediate-apply model, unlike `EditingOptions.onSave`. Show your
+     * own error UI (e.g. a toast) if a change needs to be surfaced as failed.
+     */
+    onCellsChange: (changes: CellChange<TRow>[]) => void | Promise<void>;
+    /** Disables all cell-editing interaction — e.g. while a previous gesture's `onCellsChange` is still in flight. Defaults to false. */
+    disabled?: boolean;
+    /**
+     * Renders every editable cell's editor directly, all the time — no click,
+     * double-click, F2, or typed character needed to open one first. Selection
+     * (drag/shift+click/shift+arrow), copy, paste, and the fill-handle all
+     * still work exactly as they do without this flag; only the single-cell
+     * "one cell editing at a time" gate is gone, since with this on every
+     * editable cell already IS its own editor. A buffered (string/number/
+     * currency) editor still only commits on blur/Enter/Tab, same as always —
+     * this flag just means it's already open, not that it types straight
+     * through to `onCellsChange` on every keystroke. Defaults to false.
+     */
+    alwaysEdit?: boolean;
+}
+
+/** Maps each id to its position in `ids` — built once per (rowIds|columnIds) identity change, then reused for every lookup during a drag, rather than an O(n) `indexOf` per cell per mousemove. */
+declare function buildIndexMap(ids: string[]): Map<string, number>;
+/** A `CellRange`'s two corners resolved to ordinal row/column indices, with `start <= end` on both axes regardless of which corner `anchor`/`focus` was. */
+interface NormalizedRange {
+    rowStart: number;
+    rowEnd: number;
+    colStart: number;
+    colEnd: number;
+}
+/**
+ * Resolves a `CellRange` to ordinal indices via `rowIndex`/`columnIndex`
+ * (from `buildIndexMap`), or `undefined` if either endpoint's row or column
+ * id no longer exists — e.g. the row was removed from `data` since the
+ * selection was made.
+ */
+declare function normalizeRange(range: CellRange, rowIndex: Map<string, number>, columnIndex: Map<string, number>): NormalizedRange | undefined;
+/** True if `cell` falls inside `range` (inclusive on all sides). */
+declare function isCellInRange(cell: CellAddress, range: CellRange, rowIndex: Map<string, number>, columnIndex: Map<string, number>): boolean;
+/** Every cell address inside `range`, in row-major order (top-to-bottom, left-to-right), skipping the row-major walk entirely once `normalizeRange` can't resolve either endpoint. */
+declare function cellsInRange(range: CellRange, rowIds: string[], columnIds: string[], rowIndex: Map<string, number>, columnIndex: Map<string, number>): CellAddress[];
+/**
+ * Extends a fill-handle drag's `base` range (the source selection, already
+ * normalized) toward `target`, locked to whichever single axis — row or
+ * column — has the larger overshoot past `base`'s own edge on that axis.
+ * Matches Excel/Sheets' own autofill behavior: dragging the fill handle
+ * never extends diagonally, only straight down/up/left/right from the
+ * source range. Returns `base` unchanged if `target` is inside or on its
+ * border (no overshoot on either axis).
+ */
+declare function extendRangeForFill(base: NormalizedRange, target: {
+    row: number;
+    col: number;
+}): NormalizedRange;
+
+type NavigationDirection = "up" | "down" | "left" | "right";
+interface CellSelectionOptions {
+    /** Every row id, in on-screen order — the FULL logical row list, not just currently-mounted virtual items, so navigation and range math work correctly regardless of virtualization. */
+    rowIds: string[];
+    /** Every editable-surface column id, in on-screen order. */
+    columnIds: string[];
+    /** Called when navigation lands on a row id that (per the caller) may not currently be mounted — e.g. to `virtualizer.scrollToIndex` it into view. Not called for a move that stays on the same row (left/right). */
+    onNavigateToRow?: (rowId: string) => void;
+}
+interface CellSelectionController {
+    /** The committed selection (mouseup already happened, or a keyboard move), or `undefined` before any cell has ever been selected. */
+    selection: CellRange | undefined;
+    /** True while a mouse-drag range-select is in progress (between `startSelection` and `endDrag`). */
+    isDragging: boolean;
+    /** `selection` extended live to the drag's current cell while `isDragging`; otherwise identical to `selection`. This is the range a renderer should actually paint. */
+    effectiveRange: CellRange | undefined;
+    /** Mousedown on `cell`: starts a fresh single-cell selection, or (`extend: true`, e.g. shift+mousedown) extends the existing selection's focus corner to `cell` while keeping its anchor. Either way, also opens a drag (see `endDrag`) — a plain click-no-move sequence still round-trips through `startSelection`/`endDrag` and ends up exactly the same as if `updateDrag` were never called. */
+    startSelection: (cell: CellAddress, options?: {
+        extend?: boolean;
+    }) => void;
+    /** Mousemove while dragging: updates the live drag-focus cell. Callers should coalesce rapid calls themselves (e.g. one `requestAnimationFrame`-scheduled flush per animation frame) — this hook applies whatever it's given without its own throttling. No-op if not currently dragging. */
+    updateDrag: (cell: CellAddress) => void;
+    /** Mouseup: commits the in-progress drag's live focus cell as the real selection. No-op if not currently dragging. */
+    endDrag: () => void;
+    /** Keyboard navigation: moves the focus corner by one row/column in `direction`, clamped to grid bounds. Collapses the selection to the new single cell unless `extend` (shift+arrow), which instead moves only the focus corner, keeping the existing anchor. */
+    moveSelection: (direction: NavigationDirection, options?: {
+        extend?: boolean;
+    }) => void;
+    /** Directly replaces the selection, e.g. to leave a specific cell selected after a paste/fill commits. */
+    setSelection: (range: CellRange) => void;
+    clearSelection: () => void;
+    /** True while a fill-handle drag is in progress (between `startFillDrag` and `endFillDrag`). Mutually exclusive with `isDragging` — starting one doesn't check for the other, but a caller should never let both begin at once (the fill handle and the rest of a cell are different mousedown targets). */
+    isFillDragging: boolean;
+    /** The selection extended toward the fill-drag's current target cell, axis-locked (see `extendRangeForFill`'s own doc) — the range a renderer should paint as the live fill preview. `undefined` when not fill-dragging, or before the first `updateFillDrag` call of a given drag. */
+    fillPreviewRange: CellRange | undefined;
+    /** Starts a fill-drag from the current `selection` (mousedown on the fill handle). No-op if there's no selection yet. */
+    startFillDrag: () => void;
+    /** Updates the fill-drag's live target cell (mousemove while fill-dragging). Callers should coalesce rapid calls themselves, same as `updateDrag`. No-op if not currently fill-dragging. */
+    updateFillDrag: (cell: CellAddress) => void;
+    /**
+     * Commits the fill-drag (mouseup): sets the extended range as the new
+     * `selection` and returns both the original source range and the final
+     * extended one, so the caller can compute the actual fill values (which
+     * source cell each newly-covered cell copies from) — that data-dependent
+     * computation doesn't belong in this hook, which only knows row/column
+     * ids, not row data. Returns `undefined` if not fill-dragging, there was
+     * no base selection, or no target cell was ever reported (a drag that
+     * never moved) — in the last case, nothing to commit, current selection
+     * unchanged.
+     */
+    endFillDrag: () => {
+        sourceRange: CellRange;
+        finalRange: CellRange;
+    } | undefined;
+}
+/**
+ * Owns the rectangular range-selection cursor for `cellEditing` mode: the
+ * committed selection, an in-progress mouse-drag's live extent, and
+ * keyboard navigation — all keyed by row-id/column-id (via `rowIds`/
+ * `columnIds`'s ordinal position), never by DOM node or virtualized index,
+ * so a selection is meaningful even for a row that isn't currently mounted.
+ */
+declare function useCellSelection({ rowIds, columnIds, onNavigateToRow }: CellSelectionOptions): CellSelectionController;
+
+/**
+ * Everything `renderCellModeCell` needs to render one cell under
+ * `cellEditing` mode. Bundled into one object handed through a `useRef` for
+ * the identical reason `EditingCellContext` is (see that type's own doc):
+ * `<DataGrid>`'s `tanstackColumns` memo must not depend on anything that
+ * changes per-keystroke, or typing into one cell would remount the whole
+ * table body.
+ */
+interface CellEditingCellContext<TRow> {
+    /** Mirrors `CellEditingOptions.alwaysEdit` — every editable cell renders `AlwaysEditCell` instead of going through `editingCell`/`onBeginEdit` at all when this is set. */
+    alwaysEdit: boolean;
+    /** Mirrors `CellEditingOptions.disabled`. Click-to-edit mode blocks interaction by simply never opening an editor while this is set (see `onBeginEdit`'s own gate) — `AlwaysEditCell`'s editors are always open regardless, so it reads this directly to disable its rendered form control instead. */
+    disabled: boolean;
+    /** The one cell currently showing its editor, or `undefined` — at most one at a time, the same convention `EditingCellContext.activeRowId` uses at row granularity. Meaningless (always `undefined`) under `alwaysEdit`, where every editable cell already has its own editor. */
+    editingCell: CellAddress | undefined;
+    /** Replaces (doesn't append to) the editor's starting value when editing began by typing a printable character directly (Excel's "just start typing" gesture) rather than double-click/Enter/F2, which start from the cell's current value. `undefined` means "start from the current value." */
+    initialText: string | undefined;
+    /** Whether at least one `onChangeDraft` has fired this edit session — distinguishes "no keystrokes yet, show the starting value" from "the user explicitly typed something," including an empty string. */
+    hasDraft: boolean;
+    /** The in-progress typed value for `editingCell`, meaningful only when `hasDraft` is true. */
+    draftValue: unknown;
+    getRowId: (row: TRow) => string;
+    getError: (rowId: string, columnId: string) => string | undefined;
+    /**
+     * The value to actually display for one cell: `rawValue` (the row's real
+     * data) unless a still-"fresh" local override exists. An override is
+     * fresh only while `rawValue` still equals what it was at the moment of
+     * the edit (`previousValue`) — the instant the row's real data changes to
+     * ANYTHING else (the consumer's `onCellsChange` handler updated its own
+     * `data` to reflect the accepted edit, or a refetch landed with something
+     * different entirely, e.g. server-side normalization), real data is
+     * trusted again instead of the stale local echo. This is what lets a
+     * fire-and-forget, no-rollback model (see `CellEditingOptions.onCellsChange`'s
+     * own doc) still self-correct if the consumer's eventual real data
+     * diverges from what was optimistically shown.
+     */
+    resolveValue: (rowId: string, columnId: string, rawValue: unknown) => unknown;
+    /** Starts editing `cell`. */
+    onBeginEdit: (cell: CellAddress, initialText?: string) => void;
+    /** Reverts without committing — Escape, or a blur while the current draft is invalid. */
+    onCancelEdit: () => void;
+    /** Records a keystroke/selection's new value for the cell currently being edited — for an "atomic" editor (enum/boolean/date, where a single selection IS the complete gesture) the caller follows this immediately with `onCommitEdit`; for a free-text editor (string/number) this only buffers, and the caller commits separately on blur/Enter/Tab. */
+    onChangeDraft: (value: unknown) => void;
+    /** Commits the current draft (or, if `hasDraft` is false, effectively a no-op close) for the cell currently being edited, as one `CellChange`, and closes its editor. `previousValue` is the row's real value before this edit, for the resulting `CellChange.previousValue`. */
+    onCommitEdit: (row: TRow, previousValue: unknown) => void;
+    /**
+     * Commits an explicit `value` directly, bypassing the draft state
+     * entirely — for an "atomic" editor (enum/boolean/date) whose `onChange`
+     * fires once with the complete new value and wants to commit in that same
+     * call. `onCommitEdit` above can't be reused for this: it reads `hasDraft`/
+     * `draftValue` from React state, which a same-tick `onChangeDraft` call
+     * immediately before it would NOT yet reflect (state updates don't apply
+     * until the next render, even within the same event handler).
+     */
+    onCommitValue: (row: TRow, previousValue: unknown, value: unknown) => void;
+    onSetError: (rowId: string, columnId: string, message: string | undefined) => void;
+    /** Commits one independently-managed cell's change directly — for `AlwaysEditCell`, which owns its own draft state locally rather than through `editingCell`/`onChangeDraft`/`onCommitEdit`'s single shared slot (every editable cell needs its own simultaneous editor under `alwaysEdit`, not just one at a time). */
+    applyChange: (change: CellChange<TRow>) => void;
+    /**
+     * Reads (and clears) whether `onCommitEdit`/`onCommitValue` committed
+     * synchronously during the current call stack. `<DataGrid>`'s own keydown
+     * handler needs this: `renderCellModeCell`'s Enter/Tab commit deliberately
+     * doesn't stop the event from bubbling, so that handler can advance the
+     * selection afterward — but `editingCell` itself is React state, which
+     * doesn't reflect `closeEditor()`'s update until the next render, so
+     * reading it directly during that same bubbled dispatch always still
+     * shows the row that JUST closed. This ref-backed flag is the one piece of
+     * "did a commit just happen in this exact gesture" state that's readable
+     * synchronously, in the same event, immediately after the commit.
+     */
+    consumeJustCommitted: () => boolean;
+}
+interface CellEditingState<TRow> {
+    /** The live context, read directly by a render path with no remount-avoidance concerns of its own. */
+    ctx: CellEditingCellContext<TRow> | undefined;
+    /** Same context, mirrored into a ref every render — see `CellEditingCellContext`'s own doc for why `<DataGrid>`'s per-cell closures must read through this instead of closing over `ctx` directly. */
+    ctxRef: {
+        current: CellEditingCellContext<TRow> | undefined;
+    };
+    /** Commits a whole gesture's changes at once (paste, fill-drag) — no `editingCell` involved, unlike `onCommitEdit` above. */
+    applyChanges: (changes: CellChange<TRow>[]) => void;
+}
+/**
+ * Owns the "true spreadsheet" per-cell edit state: which single cell (if
+ * any) is showing its editor, that cell's in-progress typed draft, per-cell
+ * validation errors, and the local-override echo every committed change
+ * leaves behind until the consumer's own real data catches up. Every
+ * mutation — a typed commit, a future paste, a future fill-drag — funnels
+ * through `applyChanges`, so a later undo/redo can be built on top of that
+ * one function without a rearchitecture.
+ */
+declare function useCellEditingState<TRow>(cellEditing: CellEditingOptions<TRow> | undefined, getRowId: (row: TRow) => string): CellEditingState<TRow>;
+
+/**
+ * Renders one cell under `cellEditing` mode — the immediate-apply
+ * counterpart to `edit/renderEditableCell.tsx`'s accumulate-then-save one.
+ * Reuses the exact same per-type editor widgets via `registry.tsx`'s
+ * `renderDefaultEditWidget` (and the same `column.renderEditCell`/
+ * `column.validateEdit` escape hatches) — only the commit semantics differ.
+ *
+ * Not responsible for range-selection visuals — that's `SelectionOverlay`,
+ * one overlay for the whole grid — this only decides whether THIS cell is
+ * the one currently showing its editor.
+ */
+declare function renderCellModeCell<TRow>(column: ColumnDef<TRow>, row: TRow, rawValue: unknown, ctx: CellEditingCellContext<TRow> | undefined): ReactNode;
+
+/**
+ * Renders the current range selection (and, while a fill-handle drag is in
+ * progress, a dashed preview of the range it would extend to) as absolutely-
+ * positioned overlay divs, geometry read live from the DOM rects of the
+ * relevant cells' `data-cell-row`/`data-cell-col` nodes — deliberately not
+ * derived from `columnSizing`/row-height state, since reading the live DOM
+ * always matches exactly what's rendered (including natural, non-resizing
+ * column widths `columnSizing`'s own math doesn't account for).
+ *
+ * Must render as a CHILD of the scrollable container (not a sibling outside
+ * it), with that container given `position: relative` — position/left/top
+ * are computed in the container's own unscrolled content-space (rect minus
+ * the container's rect, plus the container's current scroll offset), so once
+ * set, the overlay scrolls together with the table content via ordinary
+ * browser scrolling with no scroll listener of its own. A virtualized grid's
+ * scroll-driven re-renders (the virtualizer's own React state) naturally
+ * recompute this on every such render; a non-virtualized grid never needs to
+ * (native scroll changes nothing in content-space).
+ *
+ * Deliberately isolated from `visibleColumns`/`tanstackColumns` — it reads
+ * nothing from either, only `range`/`fillPreviewRange` and the DOM — so
+ * painting/updating a selection or a fill-drag (including during a fast
+ * mouse-drag) never touches the column-definition memo that would otherwise
+ * remount the whole table body.
+ */
+declare function SelectionOverlay({ containerRef, range, fillPreviewRange, onFillHandleMouseDown, }: {
+    containerRef: {
+        current: HTMLDivElement | null;
+    };
+    range: CellRange | undefined;
+    /** The live preview range during a fill-handle drag, or `undefined` when not fill-dragging. */
+    fillPreviewRange?: CellRange | undefined;
+    /** Mousedown on the fill handle — starts a fill-drag. Omit to render no handle at all (e.g. a read-only or non-editable selection). */
+    onFillHandleMouseDown?: (event: MouseEvent<HTMLDivElement>) => void;
+}): ReactElement | null;
+
+/**
+ * Coerces one pasted/filled raw TSV cell string into the typed value a
+ * column's editor/validator expects — the paste/fill equivalent of
+ * `edit/registry.tsx`'s per-type dispatch, reusing the exact same `toDate`/
+ * `toNumber` parsing `column/format.ts` uses for display so paste coercion
+ * can't drift from what the grid already shows.
+ *
+ * Returns `undefined` for a value that can't be coerced at all (e.g. "abc"
+ * into a number column) — the caller's job to skip that cell rather than
+ * hand `onCellsChange` a `NaN`/`Invalid Date`. An empty string coerces to
+ * `null` for `number`/`currency` (pasting a blank cell over a numeric one
+ * clears it, matching `NumberEditor`'s own null-for-cleared convention) —
+ * `string` columns instead treat an empty string as itself a valid value.
+ * An Excel/Sheets error string (`#N/A`, `#DIV/0!`, etc.) pasted into any
+ * column but `string` is likewise skipped rather than coerced.
+ */
+declare function coerceValueForColumn<TRow>(column: ColumnDef<TRow>, raw: string): {
+    value: unknown;
+} | undefined;
+
+/**
+ * Serializes the cells inside `range` to Excel-compatible TSV text: tab-
+ * separated columns, newline-separated rows, walking `rowIds`/`columnIds` in
+ * their on-screen order (not `range`'s own anchor/focus order). Each cell's
+ * text comes from `column.formatForClipboard` if the column supplies one,
+ * else the same `defaultFormat` display text the grid itself renders —
+ * deliberately not a second "raw value to string" path.
+ */
+declare function rangeToTsv<TRow>(range: CellRange, rows: TRow[], rowIds: string[], columns: ColumnDef<TRow>[], columnIds: string[], getRowId: (row: TRow) => string): string;
+/**
+ * Parses Excel-compatible TSV/tab-delimited clipboard text into a 2D array
+ * of raw string cells. A small character-by-character state machine (not a
+ * naive split-by-newline-then-split-by-tab) so a quoted field's own embedded
+ * newline — a genuine multi-line cell copied from Excel/Sheets — isn't
+ * mistaken for a row boundary, and a doubled `""` inside a quoted field
+ * unescapes to one literal `"`.
+ */
+declare function parseTsv(text: string): string[][];
+
+/**
+ * Computes the `CellChange`s a fill-handle drag produces: every cell newly
+ * covered by `finalRange` but not already inside `sourceRange` copies its
+ * value from the corresponding source cell, TILING the source pattern across
+ * the fill direction when the extension is longer than the source itself —
+ * the same repeat-the-pattern behavior Excel's own fill-handle uses for a
+ * multi-cell source (a single-cell source is just the degenerate case: every
+ * new cell copies that one cell). Value-copy only, no numeric/date
+ * auto-increment — MVP scope, matching the akeneo hand-rolled
+ * implementation this feature replaces, which also only ever copies a
+ * single value uniformly.
+ *
+ * Cells already inside `sourceRange` are left out of the result entirely —
+ * they're untouched by a fill, only the newly-covered ones change.
+ * A target cell that's missing, not editable, or whose source cell is
+ * missing is silently skipped.
+ */
+declare function computeFillChanges<TRow>(sourceRange: CellRange, finalRange: CellRange, rowIds: string[], columnIds: string[], columns: ColumnDef<TRow>[], getRow: (rowId: string) => TRow | undefined): CellChange<TRow>[];
+
 /**
  * Column visibility keyed by `ColumnDef.id`. A missing key means visible —
  * this matches TanStack Table's own `VisibilityState` convention, so a
@@ -1151,6 +1542,16 @@ interface DataGridProps<TRow> {
      * contract — shared with `<TreeDataGrid>`'s own `editing` prop.
      */
     editing?: EditingOptions<TRow>;
+    /**
+     * Enables the "true spreadsheet" cell-editing mode: click/type directly
+     * into any cell, drag or shift+arrow to range-select, paste, drag a
+     * fill-handle — every change applies immediately, with no row-level
+     * Save/Discard gate. This is a different, mutually exclusive state machine
+     * from `editing` above, not a superset of it — set at most one of the two
+     * on a given `<DataGrid>`; `editing` is ignored once `cellEditing` is set.
+     * See `CellEditingOptions` for the full contract.
+     */
+    cellEditing?: CellEditingOptions<TRow>;
 }
 
 /**
@@ -1161,7 +1562,7 @@ interface DataGridProps<TRow> {
  * (`"server"`). Column filter UI defaults to the type-appropriate widget
  * from `src/filter` unless a column supplies its own `cell` renderer.
  */
-declare function DataGrid<TRow extends RowData>({ columns, dataSource, getRowId, rowActions, headerActions, enableMultiSort, initialState, columnVisibility, renderDetail, enableColumnResizing, columnResizeMode, columnSizing: controlledColumnSizing, onColumnSizingChange, virtualize, showPagination, getRowProps, getRowTestId, gridState, selectedIds: controlledSelectedIds, onSelectedIdsChange, testId, loading: loadingProp, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, editing, }: DataGridProps<TRow>): ReactElement;
+declare function DataGrid<TRow extends RowData>({ columns, dataSource, getRowId, rowActions, headerActions, enableMultiSort, initialState, columnVisibility, renderDetail, enableColumnResizing, columnResizeMode, columnSizing: controlledColumnSizing, onColumnSizingChange, virtualize, showPagination, getRowProps, getRowTestId, gridState, selectedIds: controlledSelectedIds, onSelectedIdsChange, testId, loading: loadingProp, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, editing, cellEditing, }: DataGridProps<TRow>): ReactElement;
 
 interface GridStateController {
     state: GridState;
@@ -1581,4 +1982,4 @@ interface UseTreeStateOptions<TRow> extends TreeAccessors<TRow> {
  */
 declare function useTreeState<TRow>({ data, getRowId, getChildren, hasChildren, onLoadChildren, expanded: controlledExpanded, onExpandedChange, childrenMap: controlledChildrenMap, onChildrenMapChange, }: UseTreeStateOptions<TRow>): TreeStateController<TRow>;
 
-export { ActionsMenu, type BaseColumn, type BooleanColumn, BooleanEditor, BooleanFilter, type ClientProcessingResult, type ColumnAlign, type ColumnDef, type ColumnGroup, ColumnSelector, type ColumnSelectorProps, type ColumnVisibility, type CompositeFilterDescriptor, DataGrid, type DataGridProps, type DataSource, type DateColumn, DateEditor, DateRangeFilter, type DebouncedCallback, EditFieldError, type EditWidgetProps, type EditedRow, EditingBar, type EditingBarProps, type EditingCellContext, type EditingOptions, type EditingState, type EnumColumn, EnumEditor, EnumFilter, type EnumOption, type FilterDescriptor, type FilterOperator, type FilterWidgetProps, type FlatTreeRow, type GridState, type GridStateController, type GroupExpansionController, type MenuItem, type MenuItemContext, type NumberColumn, NumberComparisonFilter, NumberEditor, NumberHistogramFilter, type NumberHistogramFilterProps, NumberRangeFilter, type PendingRowEdit, type ResolvedMenuItem, type SortDescriptor, type StickyGroupHeaderTop, type StringColumn, StringEditor, StringFilter, type TreeAccessors, TreeDataGrid, type TreeDataGridProps, type TreeStateController, UNARY_OPERATORS, type UseTreeStateOptions, alignClassName, canHideColumn, canHideGroup, countVisible, defaultAlign, defaultFormat, editErrorId, evaluateFilter, facetedNumberValues, fieldKey, flattenTree, getColumnValue, groupColumns, isColumnVisible, isCompositeFilterDescriptor, isEditable, isFilterDescriptor, isFilterable, isSortable, processClientData, renderDefaultEditWidget, renderDefaultFilterWidget, renderEditableCell, resolveMenuItems, storageKeyFor, toDate, useDebouncedCallback, useEditingState, useGridState, useGroupExpansion, useStickyGroupHeaderTop, useTreeState, useVisibleColumns };
+export { ActionsMenu, type BaseColumn, type BooleanColumn, BooleanEditor, BooleanFilter, type CellAddress, type CellChange, type CellEditingCellContext, type CellEditingOptions, type CellEditingState, type CellRange, type CellSelectionController, type CellSelectionOptions, type ClientProcessingResult, type ColumnAlign, type ColumnDef, type ColumnGroup, ColumnSelector, type ColumnSelectorProps, type ColumnVisibility, type CompositeFilterDescriptor, DataGrid, type DataGridProps, type DataSource, type DateColumn, DateEditor, DateRangeFilter, type DebouncedCallback, EditFieldError, type EditWidgetProps, type EditedRow, EditingBar, type EditingBarProps, type EditingCellContext, type EditingOptions, type EditingState, type EnumColumn, EnumEditor, EnumFilter, type EnumOption, type FilterDescriptor, type FilterOperator, type FilterWidgetProps, type FlatTreeRow, type GridState, type GridStateController, type GroupExpansionController, type MenuItem, type MenuItemContext, MultilineStringEditor, type NavigationDirection, type NormalizedRange, type NumberColumn, NumberComparisonFilter, NumberEditor, NumberHistogramFilter, type NumberHistogramFilterProps, NumberRangeFilter, type PendingRowEdit, type ResolvedMenuItem, SelectionOverlay, type SortDescriptor, type StickyGroupHeaderTop, type StringColumn, StringEditor, StringFilter, type TreeAccessors, TreeDataGrid, type TreeDataGridProps, type TreeStateController, UNARY_OPERATORS, type UseTreeStateOptions, alignClassName, buildIndexMap, canHideColumn, canHideGroup, cellsInRange, coerceValueForColumn, computeFillChanges, countVisible, defaultAlign, defaultFormat, editErrorId, evaluateFilter, extendRangeForFill, facetedNumberValues, fieldKey, flattenTree, getColumnValue, groupColumns, isCellInRange, isColumnVisible, isCompositeFilterDescriptor, isEditable, isFilterDescriptor, isFilterable, isSortable, normalizeRange, parseTsv, processClientData, rangeToTsv, renderCellModeCell, renderDefaultEditWidget, renderDefaultFilterWidget, renderEditableCell, resolveMenuItems, storageKeyFor, toDate, useCellEditingState, useCellSelection, useDebouncedCallback, useEditingState, useGridState, useGroupExpansion, useStickyGroupHeaderTop, useTreeState, useVisibleColumns };