@bmsuisse/datagrid 0.25.2 → 0.26.0

package/dist/index.d.ts

@@ -161,6 +161,43 @@ interface BaseColumn<TRow> {
      * any, since `<DataGrid>` has no way to tell your content lacks one.
      */
     renderHeader?: (column: BaseColumn<TRow>) => ReactNode;
+    /**
+     * Opt-in: defaults to false — must be explicitly set (or return true) for
+     * `<DataGrid>` to render this column's cells as inline editors. A function
+     * makes it conditional per row (e.g. a "locked" row that can't be
+     * edited). See `DataGridProps.editing` for the accumulate-then-save
+     * workflow this feeds into — editable cells with no `editing` prop
+     * supplied just render as static text, same as if `editable` were unset.
+     *
+     * 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.
+     */
+    editable?: boolean | ((row: TRow) => boolean);
+    /**
+     * Overrides the default type-based editor (see `renderDefaultEditWidget`)
+     * for this column's cells. Receives the cell's current value (the row's
+     * original value, or a still-pending edit if the user already changed it
+     * this session), the row itself, an `onChange` to record a new pending
+     * value, this cell's current validation error message (from
+     * `validateEdit` below) if any, and whether this specific cell is the one
+     * whose click just activated the row (see `editable`'s own doc) — forward
+     * it to your control's native `autoFocus` so the row-activating click also
+     * focuses the field the user actually clicked, not just some other cell
+     * in the same row.
+     */
+    renderEditCell?: (value: unknown, row: TRow, onChange: (next: unknown) => void, error: string | undefined, autoFocus: boolean) => ReactNode;
+    /**
+     * Validates a pending edit before it's allowed into `editing.onSave`'s
+     * payload. Returning a message string blocks the Save button (and shows
+     * the message under the cell) until the value is fixed or reverted to its
+     * original; returning `undefined` means valid. Runs on every change to
+     * this cell, including the default editors' own `onChange`.
+     */
+    validateEdit?: (value: unknown, row: TRow) => string | undefined;
 }
 type StringColumn<TRow> = BaseColumn<TRow> & {
     type: "string";
@@ -191,6 +228,8 @@ declare function getColumnValue<TRow>(column: ColumnDef<TRow>, row: TRow): unkno
 declare function isSortable<TRow>(column: ColumnDef<TRow>): boolean;
 /** True only if a column explicitly opts in (`filterable: true`) — the default is false. */
 declare function isFilterable<TRow>(column: ColumnDef<TRow>): boolean;
+/** True only if a column explicitly opts in to `editable` — for this specific row, when `editable` is a predicate. Default is false. */
+declare function isEditable<TRow>(column: ColumnDef<TRow>, row: TRow): boolean;
 
 /**
  * Default filter widget for `type: "boolean"` columns: a 3-way All/Yes/No
@@ -450,6 +489,14 @@ declare function renderDefaultFilterWidget<TRow>(column: ColumnDef<TRow>, value:
 declare function defaultAlign<TRow>(column: ColumnDef<TRow>): ColumnAlign;
 /** The literal Tailwind class for a column's default alignment; see `defaultAlign`. */
 declare function alignClassName<TRow>(column: ColumnDef<TRow>): string;
+/**
+ * Parses an arbitrary raw cell value into a `Date`, or `null` if it isn't
+ * one. Exported (unlike `toNumber` below, which stays internal) because
+ * `edit/DateEditor.tsx` needs the exact same date-only-vs-datetime parsing
+ * this module already uses for display — a second copy would risk drifting
+ * from the UTC-midnight fix documented below.
+ */
+declare function toDate(value: unknown): Date | null;
 /**
  * Renders a raw cell value as a display string, using the type-appropriate
  * default formatter for `column.type`. Columns with a custom `cell` render
@@ -457,6 +504,118 @@ declare function alignClassName<TRow>(column: ColumnDef<TRow>): string;
  */
 declare function defaultFormat<TRow>(column: ColumnDef<TRow>, value: unknown): string;
 
+/**
+ * One row carrying at least one pending edit, as handed to
+ * `DataGridEditingOptions.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
+ * derived/computed column has no single field of `TRow` an edit could patch
+ * back onto).
+ */
+interface EditedRow<TRow> {
+    rowId: string;
+    /** The row as it looked when its first still-pending edit was made — not necessarily the row's current on-screen data if it was refetched since. */
+    row: TRow;
+    values: Record<string, unknown>;
+}
+
+/**
+ * Contract every built-in edit widget implements — the `renderEditCell`
+ * equivalent of `filter/widget-types.ts`'s `FilterWidgetProps`. `TColumn` is
+ * narrowed to the specific column shape the widget knows how to render (e.g.
+ * `EnumColumn` for `EnumEditor`) — `renderDefaultEditWidget` picks the right
+ * widget by `column.type` before handing it a column, so the widget itself
+ * never has to branch on `type`.
+ *
+ * `value` is the cell's current value: the row's original value, or a
+ * still-pending edit if the user already changed it this session.
+ * `onChange` records a new pending value — it does not itself validate or
+ * persist anything. `error`, when set, is this cell's current
+ * `column.validateEdit` message; every built-in widget shows it as small
+ * text under its control and marks the control `aria-invalid`.
+ *
+ * `rowId` exists purely so each built-in widget's own `data-testid` (`edit-
+ * ${rowId}-${column.id}`) stays unique per cell — unlike a filter widget,
+ * which renders exactly once per column (in the header), an edit widget
+ * renders once per (row, column) pair, so a column-id-only testid would
+ * collide across every row the moment a grid has more than one.
+ *
+ * `autoFocus` is true for exactly one cell per row-activation: the specific
+ * column whose static cell the user clicked (or Enter/Space'd) to turn the
+ * whole row into editors — every other cell in that same row gets `false`.
+ * Every built-in widget forwards it straight to its underlying control's own
+ * native `autoFocus` prop, so the browser focuses that one control the
+ * moment it mounts, without an extra click to actually start typing.
+ */
+interface EditWidgetProps<TColumn> {
+    column: TColumn;
+    rowId: string;
+    value: unknown;
+    onChange: (next: unknown) => void;
+    error?: string;
+    autoFocus?: boolean;
+}
+/**
+ * The `id` every built-in widget gives its own error `<span>`, so its
+ * control's `aria-describedby` can point at it — a screen reader announces
+ * `aria-invalid` alone with no indication of *why*, so the association
+ * matters, not just the flag. Exported for a custom `renderEditCell` that
+ * wants the same convention instead of inventing its own id scheme.
+ */
+declare function editErrorId(rowId: string, columnId: string): string;
+
+/**
+ * The error text every built-in editor shows under its control, associated
+ * with it via `id` + the control's own `aria-describedby={editErrorId(...)}`
+ * — pulled out to one place so the a11y wiring/styling convention can't
+ * drift between the 5 editors the way five independent copies of the same
+ * `<span>` inevitably would.
+ */
+declare function EditFieldError({ id, message }: {
+    id: string;
+    message: string;
+}): ReactElement;
+
+/** Default inline editor for `type: "boolean"` columns: a single checkbox. */
+declare function BooleanEditor<TRow>({ column, rowId, value, onChange, error, autoFocus, }: EditWidgetProps<BooleanColumn<TRow>>): ReactElement;
+
+/**
+ * Default inline editor for `type: "date"` / `type: "datetime"` columns: a
+ * native `<input type="date">`/`<input type="datetime-local">`. Emits a
+ * `Date` (or `null` for an emptied field), via `parseISO` rather than the
+ * bare `new Date(...)` constructor — same convention `DateRangeFilter`'s
+ * `parseBound` and `format.ts`'s `toDate` already use, since a native date
+ * input's value is a date-only `"YYYY-MM-DD"` string for `type: "date"`,
+ * which the JS spec would otherwise parse as UTC midnight instead of local
+ * midnight.
+ */
+declare function DateEditor<TRow>({ column, rowId, value, onChange, error, autoFocus, }: EditWidgetProps<DateColumn<TRow>>): ReactElement;
+
+/** 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 `type: "number"` / `type: "currency"` columns: a
+ * 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.
+ */
+declare function NumberEditor<TRow>({ column, rowId, value, onChange, error, autoFocus, }: EditWidgetProps<NumberColumn<TRow>>): ReactElement;
+
+/** Default inline editor for `type: "string"` columns: a plain text input. */
+declare function StringEditor<TRow>({ column, rowId, value, onChange, error, autoFocus, }: EditWidgetProps<StringColumn<TRow>>): ReactElement;
+
+/**
+ * Picks and renders the default inline-edit widget for a column, based
+ * purely on `column.type` — the `renderEditCell` equivalent of
+ * `filter/registry.tsx`'s `renderDefaultFilterWidget`. `<DataGrid>` calls
+ * this itself for any editable column that doesn't set its own
+ * `renderEditCell`; a consuming app only reaches for it directly to wrap or
+ * extend one of these defaults rather than writing an editor from scratch.
+ */
+declare function renderDefaultEditWidget<TRow>(column: ColumnDef<TRow>, rowId: string, value: unknown, onChange: (next: unknown) => void, error?: string, autoFocus?: boolean): ReactElement;
+
 /**
  * Column visibility keyed by `ColumnDef.id`. A missing key means visible —
  * this matches TanStack Table's own `VisibilityState` convention, so a
@@ -616,6 +775,56 @@ 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>;
@@ -795,6 +1004,16 @@ interface DataGridProps<TRow> {
     onExpandedGroupsChange?: (expanded: Record<string, boolean>) => void;
     /** Alternates body row backgrounds for readability on wide/dense tables. Defaults to true. */
     zebra?: boolean;
+    /**
+     * Enables the built-in inline-editing workflow: any column with
+     * `editable` set renders as an interactive editor, edits accumulate
+     * 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.
+     */
+    editing?: DataGridEditingOptions<TRow>;
 }
 
 /**
@@ -805,7 +1024,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, }: 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, }: DataGridProps<TRow>): ReactElement;
 
 interface GridStateController {
     state: GridState;
@@ -1126,4 +1345,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, BooleanFilter, type ClientProcessingResult, type ColumnAlign, type ColumnDef, type ColumnGroup, ColumnSelector, type ColumnSelectorProps, type ColumnVisibility, type CompositeFilterDescriptor, DataGrid, type DataGridProps, type DataSource, type DateColumn, DateRangeFilter, type DebouncedCallback, type EnumColumn, EnumFilter, type EnumOption, type FilterDescriptor, type FilterOperator, type FilterWidgetProps, type FlatTreeRow, type GridState, type GridStateController, type MenuItem, type MenuItemContext, type NumberColumn, NumberComparisonFilter, NumberHistogramFilter, type NumberHistogramFilterProps, NumberRangeFilter, type ResolvedMenuItem, type SortDescriptor, type StringColumn, StringFilter, type TreeAccessors, TreeDataGrid, type TreeDataGridProps, type TreeStateController, UNARY_OPERATORS, type UseTreeStateOptions, alignClassName, canHideColumn, canHideGroup, countVisible, defaultAlign, defaultFormat, evaluateFilter, facetedNumberValues, fieldKey, flattenTree, getColumnValue, groupColumns, isColumnVisible, isCompositeFilterDescriptor, isFilterDescriptor, isFilterable, isSortable, processClientData, renderDefaultFilterWidget, resolveMenuItems, storageKeyFor, 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 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 };