@bmsuisse/datagrid 0.26.0 → 0.27.0

package/dist/index.d.ts

@@ -172,9 +172,20 @@ interface BaseColumn<TRow> {
      * A cell doesn't become an editor just because this is true, though:
      * clicking (or Enter/Space-ing) any editable cell in a row is what
      * activates editors for every editable column in THAT row at once — the
-     * rest of the grid's rows stay static until clicked into themselves. A
-     * row stays active until its edits are saved or discarded, and
-     * activating one row never deactivates another.
+     * rest of the grid's rows stay static until clicked into themselves. At
+     * most one row is active at a time: activating a row deactivates whatever
+     * row was active before it (edit row by row, not several open at once) —
+     * this does NOT discard the row you switch away from, its own pending
+     * edits stay exactly as they were, just no longer shown as editors.
+     *
+     * Until a cell is activated, its content renders inside a clickable
+     * `<span role="button">` (this is what makes clicking it activate the
+     * row) — a column that's both `editable` and has a custom `cell`
+     * returning its own focusable content (a link, a button) produces nested
+     * interactive elements once wrapped this way. Prefer a non-focusable
+     * element (styled to look like a link, e.g.) in `cell` for a column
+     * that's also `editable`, the same caution `renderHeader` needs under
+     * `sortable`.
      */
     editable?: boolean | ((row: TRow) => boolean);
     /**
@@ -506,7 +517,7 @@ declare function defaultFormat<TRow>(column: ColumnDef<TRow>, value: unknown): s
 
 /**
  * One row carrying at least one pending edit, as handed to
- * `DataGridEditingOptions.onSave`. `values` is keyed by column id and holds
+ * `EditingOptions.onSave`. `values` is keyed by column id and holds
  * only the columns that actually changed — not a full patched `TRow` — so
  * this works uniformly for `accessorKey` columns (which have one obvious
  * field to write back into) and `accessorFn` columns (which may not: a
@@ -519,6 +530,58 @@ interface EditedRow<TRow> {
     row: TRow;
     values: Record<string, unknown>;
 }
+/**
+ * Drives the built-in inline-editing workflow shared by `<DataGrid>` and
+ * `<TreeDataGrid>`: cells in a column with `editable` set become
+ * interactive editors, and every change accumulates locally (never written
+ * back onto the caller's `data`, never sent anywhere on its own) until the
+ * user clicks the Save button this renders in a bar above the grid — or
+ * Discard, to drop everything back to unedited. There is no partial/per-cell
+ * autosave; see `onSave` below for the all-or-nothing commit point.
+ *
+ * This package has no translation/i18n layer anywhere — `saveLabel`/
+ * `discardLabel` are plain strings (or a count-aware function) you supply
+ * directly, the same convention every other caller-facing string in this
+ * package already follows (`header`, menu item labels, etc.).
+ */
+interface EditingOptions<TRow> {
+    /**
+     * Called once, when the user clicks Save, with every row currently
+     * holding at least one pending edit and no validation error
+     * (`validateEdit`-failing rows are excluded — Save itself stays disabled
+     * while ANY row has one, so in practice this only ever fires once none
+     * do). Pending-edit state stays exactly as it was until this resolves:
+     * **throw or reject to leave every pending edit in place** (e.g. your own
+     * save request failed) rather than losing the user's in-progress edits —
+     * nothing of this package's own surfaces for that case, so show your own
+     * error UI. Resolve (or return) normally to clear every pending edit that
+     * was included in this call — and only those; an edit made to a different
+     * cell while this was still in flight is never touched by this call's own
+     * resolution, whenever it lands.
+     */
+    onSave: (edits: EditedRow<TRow>[]) => void | Promise<void>;
+    /** Called after the built-in Discard button clears every pending edit. Omit for no extra behavior beyond that clear. */
+    onDiscard?: () => void;
+    /**
+     * Label for the Save button. A plain string renders as-is — no
+     * placeholder substitution, since there's no templating/i18n layer here.
+     * Pass a function instead for a count-aware label, e.g. `(count) =>
+     * `Apply ${count} change${count === 1 ? "" : "s"}``. Defaults to that
+     * exact "Save N change(s)" function.
+     */
+    saveLabel?: string | ((changedRowCount: number) => ReactNode);
+    /** Label for the Discard button. Same convention as `saveLabel`. Defaults to `"Discard"`. */
+    discardLabel?: string | ((changedRowCount: number) => ReactNode);
+    /**
+     * Disables the Save and Discard buttons and shows Save in a pending
+     * state — set this while your own `onSave` promise is in flight (a
+     * caller-driven flag, not something this package infers on its own, since
+     * `onSave` may resolve without the grid ever finding out your own server
+     * call afterward e.g. still triggered a background refetch). Defaults to
+     * false.
+     */
+    saving?: boolean;
+}
 
 /**
  * Contract every built-in edit widget implements — the `renderEditCell`
@@ -600,6 +663,19 @@ declare function EnumEditor<TRow>({ column, rowId, value, onChange, error, autoF
  * native number input. Emits `null` for an emptied field (not `NaN` or `""`)
  * so `validateEdit`/`onSave` see an explicit "cleared" value; otherwise emits
  * a real `number`, never the input's raw string.
+ *
+ * Keeps its own local `text` state instead of deriving the input's `value`
+ * straight from the `value` prop on every render — a native
+ * `type="number"` input's own `.value` getter reads back as `""` while the
+ * user is mid-typing a string that isn't yet a complete valid float ("12.",
+ * "-", "1e"), even though the field still visually shows what they typed.
+ * Deriving the controlled `value` prop straight from a re-parsed number
+ * would feed that `""` back in on every such keystroke, wiping the decimal
+ * point/minus sign before the user can finish typing it. `lastEmittedRef` +
+ * the effect below only resync `text` from an EXTERNAL change to `value`
+ * (Escape-revert, switching rows and back, a row's data refetched) — the
+ * same pattern `NumberComparisonFilter` already uses for the identical
+ * reason; see that component's own doc.
  */
 declare function NumberEditor<TRow>({ column, rowId, value, onChange, error, autoFocus, }: EditWidgetProps<NumberColumn<TRow>>): ReactElement;
 
@@ -616,6 +692,98 @@ declare function StringEditor<TRow>({ column, rowId, value, onChange, error, aut
  */
 declare function renderDefaultEditWidget<TRow>(column: ColumnDef<TRow>, rowId: string, value: unknown, onChange: (next: unknown) => void, error?: string, autoFocus?: boolean): ReactElement;
 
+/** One row's accumulated pending edits. */
+interface PendingRowEdit<TRow> {
+    /** The row as it looked when its first still-pending edit was made this session. */
+    row: TRow;
+    values: Map<string, unknown>;
+}
+/**
+ * Everything a cell-rendering path (`renderEditableCell`) needs to decide
+ * whether/how to render a given cell as an editor. Bundled into one object
+ * so `<DataGrid>` can hand it through a `useRef` (see that component's own
+ * doc on why — TanStack's `flexRender` treats `columnDef.cell` as a
+ * component type, so a closure that changes identity on every edit would
+ * remount the whole table body) while `<TreeDataGrid>`, which has no such
+ * memoized column-def layer, can just read the hook's plain `ctx` value
+ * directly every render.
+ */
+interface EditingCellContext<TRow> {
+    pendingEdits: Map<string, PendingRowEdit<TRow>>;
+    editErrors: Map<string, Map<string, string>>;
+    /**
+     * The one row currently showing editors, or `null`. Deliberately NOT the
+     * same thing as "has a pending edit": a row can be active with nothing
+     * changed yet (just clicked into). At most one at a time — activating a
+     * row deactivates whatever was active before it (edit row by row, not
+     * several open at once). This does NOT discard the row you switch away
+     * from: its own pending edits stay exactly as they were in `pendingEdits`,
+     * just no longer shown as editors.
+     */
+    activeRowId: string | null;
+    /** Set only by the click that activated a row — see `EditWidgetProps.autoFocus`'s own doc for why this exists. */
+    autoFocusTarget: {
+        rowId: string;
+        columnId: string;
+    } | null;
+    getRowId: (row: TRow) => string;
+    onEdit: (column: ColumnDef<TRow>, row: TRow, value: unknown) => void;
+    /** Activates `rowId` (deactivating whatever row was active before it) and requests autofocus on `columnId`'s editor specifically — the column whose static cell was actually clicked. */
+    onActivateRow: (rowId: string, columnId: string) => void;
+}
+interface EditingState<TRow> {
+    pendingEdits: Map<string, PendingRowEdit<TRow>>;
+    editErrors: Map<string, Map<string, string>>;
+    hasEditErrors: boolean;
+    /** The live editing context — read directly during a render body that has no remount-avoidance concerns of its own (e.g. `<TreeDataGrid>`'s plain per-row render). */
+    ctx: EditingCellContext<TRow> | undefined;
+    /** Same context, mirrored into a ref every render — for a caller (`<DataGrid>`) whose cell-rendering closures must stay referentially stable and so can't close over `ctx` directly. */
+    ctxRef: {
+        current: EditingCellContext<TRow> | undefined;
+    };
+    handleSaveEdits: () => Promise<void>;
+    handleDiscardEdits: () => void;
+}
+/**
+ * Owns the full accumulate-then-save inline-editing state machine: pending
+ * edits, validation errors, which row is active, autofocus targeting, and
+ * the Save/Discard commit logic — shared by `<DataGrid>` and
+ * `<TreeDataGrid>` so the tricky parts (the async-save race around edits
+ * made while `onSave` is in flight, the one-shot autoFocus consumption) only
+ * exist, and only need fixing, in one place.
+ */
+declare function useEditingState<TRow>(editing: EditingOptions<TRow> | undefined, getRowId: (row: TRow) => string): EditingState<TRow>;
+
+/**
+ * Renders one cell for a column that may or may not be `editable`, given the
+ * live editing context (or `undefined` when no `editing` prop was supplied
+ * at all). Shared by `<DataGrid>` and `<TreeDataGrid>` so the click-to-
+ * activate/Escape-to-revert/autoFocus behavior — and its bug fixes — only
+ * exist in one place; see `useEditingState`'s own module doc.
+ *
+ * Not itself responsible for choosing WHICH raw value to start from
+ * (`<DataGrid>` reads it off TanStack's `CellContext.getValue()`,
+ * `<TreeDataGrid>` off a plain accessor) — callers pass `rawValue` in.
+ */
+declare function renderEditableCell<TRow>(column: ColumnDef<TRow>, row: TRow, rawValue: unknown, ctx: EditingCellContext<TRow> | undefined): ReactNode;
+
+interface EditingBarProps<TRow> {
+    editing: EditingOptions<TRow>;
+    pendingRowCount: number;
+    editErrors: Map<string, Map<string, string>>;
+    onSave: () => void;
+    onDiscard: () => void;
+    /** `data-testid` for the outer bar element. Defaults to `"datagrid-edit-bar"` (also the default for the Save/Discard buttons' own testids, unless overridden below). */
+    testIdPrefix?: string;
+}
+/**
+ * The Save/Discard bar `<DataGrid>` and `<TreeDataGrid>` both render above
+ * themselves once at least one pending edit exists — shared so the two
+ * grids' editing UI (and its `aria-live`/row-naming behavior) can't drift
+ * apart from each other.
+ */
+declare function EditingBar<TRow>({ editing, pendingRowCount, editErrors, onSave, onDiscard, testIdPrefix, }: EditingBarProps<TRow>): ReactElement;
+
 /**
  * Column visibility keyed by `ColumnDef.id`. A missing key means visible —
  * this matches TanStack Table's own `VisibilityState` convention, so a
@@ -775,56 +943,6 @@ interface DataGridVirtualizeOptions {
     /** Whether more rows exist beyond what's currently loaded. `onEndReached` never fires while this is `false`. Defaults to `true`. */
     hasMore?: boolean;
 }
-/**
- * Drives `<DataGrid>`'s built-in inline-editing workflow: cells in a column
- * with `editable` set become interactive editors, and every change
- * accumulates locally (never written back onto the caller's `data`, never
- * sent anywhere on its own) until the user clicks the Save button this
- * renders in a bar above the grid — or Discard, to drop everything back to
- * unedited. There is no partial/per-cell autosave; see `onSave` below for
- * the all-or-nothing commit point.
- *
- * This package has no translation/i18n layer anywhere — `saveLabel`/
- * `discardLabel` are plain strings (or a count-aware function) you supply
- * directly, the same convention every other caller-facing string in this
- * package already follows (`header`, menu item labels, etc.).
- */
-interface DataGridEditingOptions<TRow> {
-    /**
-     * Called once, when the user clicks Save, with every row currently
-     * holding at least one pending edit and no validation error
-     * (`validateEdit`-failing rows are excluded — Save itself stays disabled
-     * while ANY row has one, so in practice this only ever fires once none
-     * do). `<DataGrid>` keeps its pending-edit state exactly as it was until
-     * this resolves: **throw or reject to leave every pending edit in place**
-     * (e.g. your own save request failed) rather than losing the user's
-     * in-progress edits — `<DataGrid>` surfaces nothing of its own for that
-     * case, so show your own error UI. Resolve (or return) normally to clear
-     * every pending edit that was included in this call.
-     */
-    onSave: (edits: EditedRow<TRow>[]) => void | Promise<void>;
-    /** Called after the built-in Discard button clears every pending edit. Omit for no extra behavior beyond that clear. */
-    onDiscard?: () => void;
-    /**
-     * Label for the Save button. A plain string renders as-is — no
-     * placeholder substitution, since there's no templating/i18n layer here.
-     * Pass a function instead for a count-aware label, e.g. `(count) =>
-     * `Apply ${count} change${count === 1 ? "" : "s"}``. Defaults to that
-     * exact "Save N change(s)" function.
-     */
-    saveLabel?: string | ((changedRowCount: number) => ReactNode);
-    /** Label for the Discard button. Same convention as `saveLabel`. Defaults to `"Discard"`. */
-    discardLabel?: string | ((changedRowCount: number) => ReactNode);
-    /**
-     * Disables the Save and Discard buttons and shows Save in a pending
-     * state — set this while your own `onSave` promise is in flight (a
-     * caller-driven flag, not something `<DataGrid>` infers on its own, since
-     * `onSave` may resolve without `<DataGrid>` ever finding out your own
-     * server call afterward e.g. still triggered a background refetch).
-     * Defaults to false.
-     */
-    saving?: boolean;
-}
 interface DataGridProps<TRow> {
     columns: ColumnDef<TRow>[];
     dataSource: DataSource<TRow>;
@@ -1010,10 +1128,10 @@ interface DataGridProps<TRow> {
      * locally, and a Save/Discard bar appears above the grid once at least
      * one exists. Omit entirely to disable — every `editable` column then
      * just falls back to its normal static `cell`/`defaultFormat` rendering,
-     * same as if `editable` were never set. See `DataGridEditingOptions` for
-     * the full contract.
+     * same as if `editable` were never set. See `EditingOptions` for the full
+     * contract — shared with `<TreeDataGrid>`'s own `editing` prop.
      */
-    editing?: DataGridEditingOptions<TRow>;
+    editing?: EditingOptions<TRow>;
 }
 
 /**
@@ -1273,6 +1391,18 @@ interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
     isRowSelectionDisabled?: (row: TRow) => boolean;
     /** Alternates body row backgrounds for readability on wide/dense tables. Defaults to true. */
     zebra?: boolean;
+    /**
+     * Enables the same built-in inline-editing workflow `<DataGrid>` has:
+     * any column with `editable` set renders as an interactive editor
+     * (clicking one editable cell activates every editable column in that
+     * row, one row active at a time), edits accumulate locally, and a
+     * Save/Discard bar appears above the tree once at least one exists. Omit
+     * entirely to disable — every `editable` column then just falls back to
+     * its normal static `cell`/`defaultFormat` rendering, same as if
+     * `editable` were never set. See `EditingOptions` (shared with
+     * `<DataGrid>`) for the full contract.
+     */
+    editing?: EditingOptions<TRow>;
 }
 
 /**
@@ -1289,7 +1419,7 @@ interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
  * column's cell matches `treeColumnId` (defaults to `columns[0]`); every
  * other column renders exactly like it would in `<DataGrid>`.
  */
-declare function TreeDataGrid<TRow>({ columns, data, treeColumnId, getRowId, getChildren, hasChildren, onLoadChildren, initialExpandedLevel, expanded: controlledExpanded, onExpandedChange, childrenMap: controlledChildrenMap, onChildrenMapChange, indentSize, getRowProps, getRowTestId, rowActions, virtualizeThreshold, estimatedRowHeight, maxBodyHeight, selectedIds: controlledSelectedIds, onSelectedIdsChange, getRowSelectionState, isRowSelectionDisabled, zebra, }: TreeDataGridProps<TRow>): ReactElement;
+declare function TreeDataGrid<TRow>({ columns, data, treeColumnId, getRowId, getChildren, hasChildren, onLoadChildren, initialExpandedLevel, expanded: controlledExpanded, onExpandedChange, childrenMap: controlledChildrenMap, onChildrenMapChange, indentSize, getRowProps, getRowTestId, rowActions, virtualizeThreshold, estimatedRowHeight, maxBodyHeight, selectedIds: controlledSelectedIds, onSelectedIdsChange, getRowSelectionState, isRowSelectionDisabled, zebra, editing, }: TreeDataGridProps<TRow>): ReactElement;
 
 interface FlatTreeRow<TRow> {
     row: TRow;
@@ -1345,4 +1475,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 DataGridEditingOptions, type DataGridProps, type DataSource, type DateColumn, DateEditor, DateRangeFilter, type DebouncedCallback, EditFieldError, type EditWidgetProps, type EditedRow, type EnumColumn, EnumEditor, EnumFilter, type EnumOption, type FilterDescriptor, type FilterOperator, type FilterWidgetProps, type FlatTreeRow, type GridState, type GridStateController, type MenuItem, type MenuItemContext, type NumberColumn, NumberComparisonFilter, NumberEditor, NumberHistogramFilter, type NumberHistogramFilterProps, NumberRangeFilter, type ResolvedMenuItem, type SortDescriptor, 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, resolveMenuItems, storageKeyFor, toDate, useDebouncedCallback, useGridState, useTreeState };
+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 MenuItem, type MenuItemContext, type NumberColumn, NumberComparisonFilter, NumberEditor, NumberHistogramFilter, type NumberHistogramFilterProps, NumberRangeFilter, type PendingRowEdit, type ResolvedMenuItem, type SortDescriptor, 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, useTreeState };