@kanunilabs/datagrid-react 1.5.0 → 1.7.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import { ReactNode, RefObject } from 'react';
-import { GridRowData, DataGridController, StateStoringConfig, RowKey, RowNode, GridColumnDef, DataGridCoreConfig, InferColumnsOptions, GridThemeName, GridPalette, DescribeFilterOptions, GridDensity, ColumnRuntime, ColumnLayout, SortDescriptor, ColumnModel, SummaryDef, FilterNode, ColumnState, BusyPhase, GridDictionary, DataRowNode, VirtualWindow, ChartBoxSpec, ChartBoxModel, ChartSpec, ChartModel, ChartXYSpec, ChartXYModel } from '@kanunilabs/datagrid-core';
-export { BusyChangedEvent, BusyPhase, ClientRowModel, ColumnLayout, ColumnLookup, ColumnModel, ColumnPin, ColumnRuntime, ColumnState, ColumnStateChangedEvent, ContentReadyEvent, DEFAULT_ROW_HEIGHT, DENSITY_ROW_HEIGHT, DataGridController, DataGridCoreConfig, DataRowNode, DataSource, FilterChangedEvent, FilterCondition, FilterGroupNode, FilterNode, FilterOperator, FocusedRowChangedEvent, GRID_PALETTES, GRID_THEMES, GridColumnDef, GridDataType, GridDensity, GridEventMap, GridPalette, GridRowData, GridStateStore, GridTheme, GridThemeName, GridViewState, GroupRowNode, GroupingConfig, HeaderBandCell, InferColumnsOptions, LoadOptions, LoadResult, LookupItem, NewRowPosition, RowDropPosition, RowKey, RowNode, SUMMARY_TYPE_LABEL, ScrollingConfig, SelectionDescriptor, SortChangedEvent, SortDescriptor, SortDirection, StateStoringConfig, SummaryDef, SummaryType, THEME_ROW_HEIGHT, ViewportChangedEvent, VirtualWindow, VirtualWindowEngine, allowedSummaryTypes, andFilters, attachStateStoring, bandDepth, bandPath, computeColumnLayout, computeHeaderBands, createRestDataSource, describeFilter, downloadBlob, fillText, filterInputFromNode, formatSummaryValue, humanizeField, importCsv, inferColumns, isDataRow, isDataSource, isFilterGroup, isGroupRow, isPackagedTheme, lookupLabel, moveRowInArray, parseCsv, parseFilterInput, sniffDelimiter, summaryKey, summaryLabel, summaryTypeLabels, themeClassName } from '@kanunilabs/datagrid-core';
+import { GridRowData, DataGridController, StateStoringConfig, RowKey, RowNode, GridColumnDef, DataGridCoreConfig, FilterRenderContextBase, FilterNode, InferColumnsOptions, GridThemeName, GridPaletteName, DescribeFilterOptions, GridDensity, CardViewOptions, RowChange, ColumnRuntime, ColumnLayout, SortDescriptor, ColumnModel, DataRowNode, ColSpanPlan, SummaryDef, ColumnState, BusyPhase, GridDictionary, VirtualWindow, ChartBoxSpec, ChartBoxModel, ChartSpec, ChartModel, ChartXYSpec, ChartXYModel, CellRange, RangeSelectionEngine, ColumnSelectMode, EditMode, ValidationRule, CrudHandlers, EditingPermissions, NewRowPosition, EditingEngine, GridDataType, LookupItem, LookupMatchMode } from '@kanunilabs/datagrid-core';
+export { BusyChangedEvent, BusyPhase, ClientRowModel, ColumnLayout, ColumnLookup, ColumnModel, ColumnPin, ColumnRuntime, ColumnState, ColumnStateChangedEvent, ContentReadyEvent, CustomFilterOperator, CustomFilterOperatorId, DEFAULT_ROW_HEIGHT, DENSITY_ROW_HEIGHT, DataGridController, DataGridCoreConfig, DataRowNode, DataSource, FilterChangedEvent, FilterCondition, FilterGroupNode, FilterNode, FilterOperator, FocusedRowChangedEvent, GRID_COLOR_SCHEMES, GRID_PALETTES, GRID_THEMES, GridColorScheme, GridColumnDef, GridDataType, GridDensity, GridEventMap, GridPalette, GridPaletteName, GridRowData, GridStateStore, GridTheme, GridThemeName, GridViewState, GroupRowNode, GroupingConfig, HeaderBandCell, InferColumnsOptions, LoadOptions, LoadResult, LookupItem, NewRowPosition, RowDropPosition, RowKey, RowNode, SUMMARY_TYPE_LABEL, ScrollingConfig, SelectionDescriptor, SortChangedEvent, SortDescriptor, SortDirection, StateStoringConfig, SummaryDef, SummaryType, THEME_ROW_HEIGHT, ViewportChangedEvent, VirtualWindow, VirtualWindowEngine, allowedSummaryTypes, andFilters, attachStateStoring, bandDepth, bandPath, computeColumnLayout, computeHeaderBands, createRestDataSource, describeFilter, downloadBlob, fillText, filterInputFromNode, formatSummaryValue, humanizeField, importCsv, inferColumns, isDataRow, isDataSource, isFilterGroup, isGroupRow, isPackagedTheme, lookupLabel, moveRowInArray, parseCsv, parseFilterInput, sniffDelimiter, summaryKey, summaryLabel, summaryTypeLabels, themeClassName } from '@kanunilabs/datagrid-core';
 
 /** Formats an export menu can offer. */
 type ExportKind = 'csv' | 'excel' | 'excel-selected' | 'pdf';
@@ -165,6 +165,14 @@ interface EditorRenderContext<TRow = GridRowData> {
     commit: () => void;
     cancel: () => void;
 }
+/**
+ * What a column's own filter UI is handed (`renderFilter`). `value` is the
+ * filter that surface holds now — re-read on every filter change, so the UI
+ * follows a cleared filter or a restored saved view.
+ */
+interface FilterRenderContext<TRow = GridRowData> extends FilterRenderContextBase<TRow> {
+    value: FilterNode | null;
+}
 interface ReactGridColumnDef<TRow = GridRowData> extends GridColumnDef<TRow> {
     /** Expensive escape hatch — renders arbitrary React per cell. */
     renderCell?: (ctx: CellRenderContext<TRow>) => ReactNode;
@@ -175,6 +183,19 @@ interface ReactGridColumnDef<TRow = GridRowData> extends GridColumnDef<TRow> {
      * against your own API.
      */
     renderEditor?: (ctx: EditorRenderContext<TRow>) => ReactNode;
+    /**
+     * Replace this column's filter UI with your own — a range slider, a date
+     * picker, a tag list. Drawn in the filter row's cell (`surface: 'row'`)
+     * when `filterRow` is on, and as the header popup's content
+     * (`surface: 'popup'`) when `headerFilter` is on; branch on `surface` to
+     * draw each differently.
+     *
+     * Call `setValue` with any filter for this column — a built-in condition,
+     * a group, or one using a custom operator from `filterOperators` — or
+     * null to clear. It goes through the same `setColumnFilter` the built-in
+     * surfaces use, so the funnel, the filter panel and saved views see it.
+     */
+    renderFilter?: (ctx: FilterRenderContext<TRow>) => ReactNode;
     /**
      * Extra class(es) on every cell of this column — a monospace SKU column, a
      * status tint. A function form allows per-VALUE classes without paying for a
@@ -221,6 +242,14 @@ interface ReactGridColumnDef<TRow = GridRowData> extends GridColumnDef<TRow> {
      * `tooltip` wins if both are given.
      */
     tooltipField?: string;
+    /**
+     * Rich tooltip content for this column's cells (P-TOOL-01): an image, a
+     * small table, a link — anything React can draw. Wins over `tooltip` and
+     * `tooltipField`; return null to show no tooltip for that cell. Runs only for
+     * the cell the tooltip is about. Pair it with `tooltip.interactive` when the
+     * content holds something to click.
+     */
+    renderTooltip?: (ctx: CellRenderContext<TRow>) => ReactNode;
     /** Tooltip for this column's HEADER cell. */
     headerTooltip?: string;
 }
@@ -318,6 +347,20 @@ interface GridTooltipConfig {
      * the behaviour the column API exists to override, not the other way round.
      */
     showOnTruncation?: boolean;
+    /**
+     * What opens a cell's tooltip (P-TOOL-01). `'hover'` (default): the mouse
+     * resting on it. `'focus'`: the cell taking keyboard focus — arrowing onto
+     * it, or tapping it on a touch screen, where there is no hover. `'both'`.
+     * A focus tooltip is tied to its cell with `aria-describedby`, so a screen
+     * reader reads it with the cell; Escape closes it.
+     */
+    trigger?: 'hover' | 'focus' | 'both';
+    /**
+     * Let the pointer move onto the tooltip (P-TOOL-01): it stays open while the
+     * pointer is on it, so its text can be selected and a link in it clicked.
+     * Default false — a tooltip that steps out of the way of the pointer.
+     */
+    interactive?: boolean;
 }
 type ReactColumnRuntime<TRow = GridRowData> = Omit<ColumnRuntime<TRow>, 'def'> & {
     def: ReactGridColumnDef<TRow>;
@@ -364,6 +407,27 @@ interface RowMenuContext<TRow = GridRowData> {
     /** Selected row keys at the moment the menu opened. */
     selectedKeys: RowKey[];
 }
+/** Single-cell editing in the Community grid — see `DataGridProps.editing`. */
+interface DataGridEditingOptions<TRow = GridRowData> {
+    /** Default true once `editing` is given. */
+    enabled?: boolean;
+    /**
+     * Always `'cell'` here — accepted so the same object works in both editions
+     * (`EnterpriseDataGrid` defaults to `'batch'` and adds the other modes).
+     */
+    mode?: 'cell';
+    /**
+     * Persist one committed cell. Called after the value is written to the row;
+     * a rejected promise is reported in the grid and the edit stays visible.
+     */
+    onSave?: (changes: RowChange<TRow>[]) => Promise<void> | void;
+    /** Typing a printable character on a focused cell opens its editor. Default true. */
+    editOnKeyPress?: boolean;
+    /** Tab moves between cells inside the grid instead of leaving it. Default true. */
+    focusCellOnTab?: boolean;
+    /** Tab past the last editable cell of a row wraps to the next row. Default true. */
+    focusCellOnCycle?: boolean;
+}
 interface DataGridProps<TRow = GridRowData> extends Omit<DataGridCoreConfig<TRow>, 'columns'> {
     /**
      * Optional: with an ARRAY data source and no columns, one column per field
@@ -392,7 +456,7 @@ interface DataGridProps<TRow = GridRowData> extends Omit<DataGridCoreConfig<TRow
     /** Applies the packaged dark palette. */
     dark?: boolean;
     /**
-     * A packaged look — `'quartz'`, `'balham'`, `'material'`, `'alpine'`,
+     * A packaged look — `'minimal'`, `'ledger'`, `'elevated'`, `'framed'`,
      * `'kanuni'` or `'kanuni-midnight'`. Omit for the default palette, which is
      * unchanged and always will be.
      *
@@ -417,18 +481,36 @@ interface DataGridProps<TRow = GridRowData> extends Omit<DataGridCoreConfig<TRow
      * `'nord'`, `'dracula'`, `'solarized'`, `'gruvbox'`, `'catppuccin'` or
      * `'tokyo-night'`.
      *
-     * Independent of `theme`, so the two multiply: Balham's dense ruled grid in
-     * Nord's blues, or Material's tall one in the same blues. Works with `dark`
+     * Independent of `theme`, so the two multiply: Ledger's dense ruled grid in
+     * Nord's blues, or Elevated's tall one in the same blues. Works with `dark`
      * (each palette ships both), and without a `theme` it recolours the packaged
      * default. Omit it and the theme's own colours apply.
+     *
+     * Also one of the 36 packaged colour schemes (`GRID_COLOR_SCHEMES` —
+     * `'porcelain'`, `'graphite'`…; each light OR dark, whatever `dark` says),
+     * with its stylesheet `@kanunilabs/datagrid-react/themes/<id>.css` imported
+     * after `styles.css`; or the name of your own scheme from the Theme Builder.
      */
-    palette?: GridPalette;
+    palette?: GridPaletteName;
     /** Alternating row background. */
     striped?: boolean;
     /** Shown when the pipeline yields no rows. */
     emptyText?: string;
     /** Header click sorting (multi-sort follows `sorting.multi` + Shift). */
     sortable?: boolean;
+    /**
+     * Let the header row grow to fit its tallest caption — the partner of a
+     * column's `wrapHeaderText`. Default false: the header keeps the theme's
+     * fixed height and a long caption ends in an ellipsis (or, wrapped, is
+     * clipped).
+     *
+     * Off by default because the height is MEASURED after layout: everything
+     * stuck under the header (the filter row, pinned rows, the totals row at
+     * the top, sticky group headers) has to move with it, and a grid that never
+     * wraps a caption should not pay for that. Only the columns on screen are measured,
+     * so scrolling sideways onto a longer caption can grow the header then.
+     */
+    autoHeaderHeight?: boolean;
     /** Text-input row under the header, one box per column. */
     filterRow?: boolean;
     /**
@@ -594,6 +676,28 @@ interface DataGridProps<TRow = GridRowData> extends Omit<DataGridCoreConfig<TRow
      * customization that keeps the column layout, use a column's `renderCell`.
      */
     renderRow?: (ctx: RowTemplateContext<TRow>) => ReactNode;
+    /**
+     * Rows as cards on a narrow grid — a phone, a side panel. Below
+     * `breakpoint` pixels (default 600) each data row is drawn as a card: the
+     * first field as its title, the rest as "Header  value" lines, as wide as
+     * the grid. The column headers give way to a sort control.
+     *
+     * Sort, filter, search, selection, grouping, virtual scrolling and remote
+     * data keep working. What needs a cell does not apply while cards are shown:
+     * in-cell editing, range selection, the fill handle and column resizing.
+     * A card shows each field's TEXT (formatters and lookups included); a
+     * column's `renderCell` is not used on a card. While cards are shown they
+     * replace `renderRow`.
+     *
+     * `columns` picks the fields and their order (the first is the title);
+     * default: the visible columns.
+     */
+    cardView?: boolean | CardViewOptions;
+    /**
+     * The grid switched between cards and the table (`cardView`), as its width
+     * crossed the breakpoint. `true` while cards are shown.
+     */
+    onCardViewChange?: (active: boolean) => void;
     /**
      * Remember the user's columns, sort, filters and grouping between visits.
      * Off by default: persisting a layout the app never asked to persist is a
@@ -718,6 +822,22 @@ interface DataGridProps<TRow = GridRowData> extends Omit<DataGridCoreConfig<TRow
      * (useCallback) or it will fire on every render.
      */
     onReady?: (controller: DataGridController<TRow>) => void;
+    /**
+     * Edit a cell in place — free in Community since 2026-10-12.
+     *
+     * Off unless this object is given (`editing={{ onSave }}`); `enabled: false`
+     * turns it off again. Double-click, F2 or typing opens the editor on
+     * an editable column; Enter commits and moves down, Tab moves to the next
+     * editable cell, Esc cancels. Each committed cell is written to its row and
+     * passed to `onSave` — one call per edit — and `cellValueChanged` fires.
+     * A column with `editable: false`, a `lookup` or a `renderEditor` stays
+     * read-only here.
+     *
+     * Batch, row, form and popup modes, validation rules, add/delete,
+     * per-row permissions, lookup and custom editors, undo/redo, range
+     * selection, fill and paste are `EnterpriseDataGrid`.
+     */
+    editing?: DataGridEditingOptions<TRow>;
     /** Replace a cell's content (e.g. with an editor). Return undefined for default. */
     renderCellContent?: (ctx: CellSlotContext<TRow>) => ReactNode | undefined;
     /** Extra class names per cell (dirty marker, range highlight, invalid). */
@@ -728,6 +848,15 @@ interface DataGridProps<TRow = GridRowData> extends Omit<DataGridCoreConfig<TRow
     onCellPointerDown?: (ctx: CellSlotContext<TRow>, event: React.MouseEvent) => void;
     onCellPointerEnter?: (ctx: CellSlotContext<TRow>, event: React.MouseEvent) => void;
     onCellDoubleClick?: (ctx: CellSlotContext<TRow>) => void;
+    /**
+     * A click on a column header, asked before it sorts; return true to take it
+     * (the header then does not sort). Column selection uses it (G-SEL-02).
+     */
+    onHeaderClick?: (columnId: string, event: React.MouseEvent) => boolean;
+    /** Extra class names per header cell. Must be a fresh function when the answer changes. */
+    getHeaderClassName?: (columnId: string) => string | undefined;
+    /** Replace a header's label (a rename box). Undefined = the label. Fresh when the answer changes. */
+    renderHeaderLabel?: (columnId: string) => ReactNode | undefined;
     /**
      * Unlocks the Enterprise edition. **Set by `EnterpriseDataGrid`** — an app
      * rendering `DataGrid` directly leaves it off.
@@ -836,8 +965,17 @@ interface GridHeaderProps<TRow = GridRowData> {
      * shows the direction of the first one, since its click sorts them all.
      */
     groupLevels?: readonly string[];
+    /**
+     * A click on a header cell, asked BEFORE it sorts. True means the click was
+     * taken (Enterprise column selection, G-SEL-02) and the header does not sort.
+     */
+    onHeaderClick?: (columnId: string, event: React.MouseEvent) => boolean;
+    /** Extra class names per header cell (a selected column). */
+    getHeaderClassName?: (columnId: string) => string | undefined;
+    /** Replace a header's label (the Enterprise rename box, G-CORE-06). Undefined = the label. */
+    renderHeaderLabel?: (columnId: string) => React.ReactNode | undefined;
 }
-declare function GridHeaderImpl<TRow = GridRowData>({ bandOffset, stickyInsets, layout, centerColumns, leadingSpacer, trailingSpacer, sort, sortable, onSort, headerFilter, filteredColumns, onOpenFilter, filterIconMode, checkboxColumn, detailColumn, rowNumberColumn, rowNumberHeader, selectAllState, selectAllDisabled, onToggleSelectAll, draggable, reorderable, onReorder, resizable, onResize, onAutoFit, onHeaderContextMenu, groupLevels, }: GridHeaderProps<TRow>): react.JSX.Element;
+declare function GridHeaderImpl<TRow = GridRowData>({ bandOffset, stickyInsets, layout, centerColumns, leadingSpacer, trailingSpacer, sort, sortable, onSort, headerFilter, filteredColumns, onOpenFilter, filterIconMode, checkboxColumn, detailColumn, rowNumberColumn, rowNumberHeader, selectAllState, selectAllDisabled, onToggleSelectAll, draggable, reorderable, onReorder, resizable, onResize, onAutoFit, onHeaderContextMenu, groupLevels, onHeaderClick, getHeaderClassName, renderHeaderLabel, }: GridHeaderProps<TRow>): react.JSX.Element;
 declare const GridHeader: typeof GridHeaderImpl;
 
 /**
@@ -985,6 +1123,20 @@ interface GridRowProps<TRow = GridRowData> {
     } | {
         kind: 'covered';
     } | null;
+    /**
+     * How this data row's cells span columns (G-CORE-03), or null. Resolved by
+     * the caller — the plan needs the column window — through ONE stable
+     * function for the same reason as `getSpan`: a closure per row would defeat
+     * the memo.
+     */
+    resolveColSpans?: (node: DataRowNode<TRow>) => ColSpanPlan<TRow> | null;
+    /**
+     * Find without filtering (P-FIND-01): how a cell takes part — the current
+     * match, another match, or not at all. `findStamp` changes whenever the
+     * marks do, so the memoised row redraws.
+     */
+    findKind?: (rowKey: RowKey, columnId: string) => 'active' | 'match' | null;
+    findStamp?: string;
     /**
      * The number to show, already resolved (see `rowNumberAt` in geometry).
      *
@@ -1065,7 +1217,7 @@ interface GridRowProps<TRow = GridRowData> {
     onCellPointerEnter?: (ctx: CellSlotContext<TRow>, event: React.MouseEvent) => void;
     onCellDoubleClick?: (ctx: CellSlotContext<TRow>) => void;
 }
-declare function GridRowImpl<TRow = GridRowData>({ gridId, node, index, layout, columnModel, centerColumns, centerIndices, stickyInsets, leadingSpacer, trailingSpacer, striped, selected, ariaSelectable, selectable, groupSelection, onToggleGroupSelect, groupDisplay, focusedColumnId, rowFocused, renderRow, checkboxColumn, rowNumberColumn, rowNumber, getNote, getSpan, headerRowCount, onRowClick, onRowMouseDown, onRowDoubleClick, onToggleSelect, onCellMouseDown, onRowContextMenu, searchNeedle, onToggleGroup, summaryDefs, detailColumn, detailExpanded, onToggleDetail, onToggleTreeRow, renderDetail, renderEditForm, renderCellContent, getCellClassName, onCellPointerDown, onCellPointerEnter, onCellDoubleClick, rowDrag, dropSide, height, }: GridRowProps<TRow>): react.JSX.Element | null;
+declare function GridRowImpl<TRow = GridRowData>({ gridId, node, index, layout, columnModel, centerColumns, centerIndices, stickyInsets, leadingSpacer, trailingSpacer, striped, selected, ariaSelectable, selectable, groupSelection, onToggleGroupSelect, groupDisplay, focusedColumnId, rowFocused, renderRow, checkboxColumn, rowNumberColumn, rowNumber, getNote, getSpan, resolveColSpans, findKind, headerRowCount, onRowClick, onRowMouseDown, onRowDoubleClick, onToggleSelect, onCellMouseDown, onRowContextMenu, searchNeedle, onToggleGroup, summaryDefs, detailColumn, detailExpanded, onToggleDetail, onToggleTreeRow, renderDetail, renderEditForm, renderCellContent, getCellClassName, onCellPointerDown, onCellPointerEnter, onCellDoubleClick, rowDrag, dropSide, height, }: GridRowProps<TRow>): react.JSX.Element | null;
 declare const GridRow: typeof GridRowImpl;
 
 interface GridFilterRowProps<TRow = GridRowData> {
@@ -1107,6 +1259,18 @@ interface GridFilterRowProps<TRow = GridRowData> {
      */
     periodSuggestions?: readonly string[];
     periodListId?: string;
+    /**
+     * The operator picked in a column's operator menu, by column id — `''` (or
+     * absent) for the default entry, which keeps the box's typed rules. Only
+     * columns with `filterOperators` show the menu.
+     */
+    operators?: Record<string, string>;
+    onOperatorChange?: (columnId: string, operatorId: string) => void;
+    /**
+     * The app's own filter UI for a column with `renderFilter`, drawn in place of
+     * the box. Returns undefined for a column without one.
+     */
+    renderCustom?: (columnId: string) => React.ReactNode | undefined;
 }
 
 /** What the reconciler needs to know about one column. Kept tiny so it is testable. */
@@ -1144,7 +1308,7 @@ interface FilterInputSyncProbe {
  * re-render entirely.
  */
 declare function reconcileFilterInputs(prev: Record<string, string>, probe: FilterInputSyncProbe, columnIds?: readonly string[]): Record<string, string>;
-declare function GridFilterRowImpl<TRow = GridRowData>({ bandOffset, stickyInsets, layout, centerColumns, leadingSpacer, trailingSpacer, values, checkboxColumn, detailColumn, rowNumberColumn, placeholder, onChange, onCommit, periodSuggestions, periodListId, }: GridFilterRowProps<TRow>): react.JSX.Element;
+declare function GridFilterRowImpl<TRow = GridRowData>({ bandOffset, stickyInsets, layout, centerColumns, leadingSpacer, trailingSpacer, values, checkboxColumn, detailColumn, rowNumberColumn, placeholder, onChange, onCommit, periodSuggestions, periodListId, operators, onOperatorChange, renderCustom, }: GridFilterRowProps<TRow>): react.JSX.Element;
 declare const GridFilterRow: typeof GridFilterRowImpl;
 
 interface DistinctEntry {
@@ -1536,6 +1700,8 @@ declare function useAlignedGrids<TRow = GridRowData>(controller: DataGridControl
 /** What the tooltip should say and where it should point. */
 interface TooltipState {
     text: string;
+    /** Rich content from a column's `renderTooltip` (P-TOOL-01); drawn instead of `text`. */
+    content?: ReactNode;
     /** Viewport rectangle of the element being described. */
     anchor: {
         top: number;
@@ -1543,6 +1709,14 @@ interface TooltipState {
         width: number;
         height: number;
     };
+    /** `tooltip.interactive`: the pointer may move onto it (P-TOOL-01). */
+    interactive?: boolean;
+    /** The pointer reached the tooltip — keep it open. */
+    hold?: () => void;
+    /** The pointer left the tooltip — close it. */
+    release?: () => void;
+    /** The tooltip element's id, which the described cell points at with `aria-describedby`. */
+    id?: string;
 }
 interface CellTooltipOptions<TRow = GridRowData> {
     rootRef: RefObject<HTMLElement | null>;
@@ -1559,8 +1733,14 @@ interface CellTooltipOptions<TRow = GridRowData> {
      */
     getRowNode: (rawKey: string) => DataRowNode<TRow> | undefined;
     config?: GridTooltipConfig;
+    /**
+     * The grid's controller and id — needed for `trigger: 'focus'` (P-TOOL-01),
+     * which follows the focused cell and finds it by the id the row gives it.
+     */
+    controller?: DataGridController<TRow>;
+    gridId?: string;
 }
-declare function useCellTooltip<TRow = GridRowData>({ rootRef, columnModel, getRowNode, getNote, config, }: CellTooltipOptions<TRow>): TooltipState | null;
+declare function useCellTooltip<TRow = GridRowData>({ rootRef, columnModel, getRowNode, getNote, config, controller, gridId, }: CellTooltipOptions<TRow>): TooltipState | null;
 
 interface GridTooltipProps {
     state: TooltipState;
@@ -1573,6 +1753,12 @@ interface GridPinnedRowsProps<TRow = GridRowData> {
     /** Which edge — decides the sticky side and the border. */
     side: 'top' | 'bottom';
     rows: readonly TRow[];
+    /**
+     * Parallel to `rows`: null for a row the app passed, the data row's key for
+     * one the USER pinned (G-CORE-05) — only those open the pin menu.
+     */
+    rowKeys?: readonly (RowKey | null)[];
+    onUserRowContextMenu?: (key: RowKey, row: TRow, event: React.MouseEvent) => void;
     layout: ColumnLayout<TRow>;
     columnModel: ColumnModel<TRow>;
     centerColumns: ReactColumnRuntime<TRow>[];
@@ -1607,7 +1793,7 @@ interface GridPinnedRowsProps<TRow = GridRowData> {
      */
     ariaRowBase: number;
 }
-declare function GridPinnedRowsImpl<TRow = GridRowData>({ gridId, side, rows, layout, columnModel, centerColumns, centerIndices, stickyInsets, leadingSpacer, trailingSpacer, checkboxColumn, detailColumn, rowNumberColumn, rowHeight, bandOffset, headerRowsBetween, ariaRowBase, }: GridPinnedRowsProps<TRow>): react.JSX.Element | null;
+declare function GridPinnedRowsImpl<TRow = GridRowData>({ gridId, side, rows, rowKeys, onUserRowContextMenu, layout, columnModel, centerColumns, centerIndices, stickyInsets, leadingSpacer, trailingSpacer, checkboxColumn, detailColumn, rowNumberColumn, rowHeight, bandOffset, headerRowsBetween, ariaRowBase, }: GridPinnedRowsProps<TRow>): react.JSX.Element | null;
 declare const GridPinnedRows: typeof GridPinnedRowsImpl;
 
 type UseDataGridOptions<TRow = GridRowData> = DataGridCoreConfig<TRow>;
@@ -1681,7 +1867,7 @@ declare function buildCellMenuItems<TRow = GridRowData>(controller: DataGridCont
 interface GridSurfaceProviderProps {
     theme?: GridThemeName;
     density?: GridDensity;
-    palette?: GridPalette;
+    palette?: GridPaletteName;
     children: ReactNode;
 }
 declare function GridSurfaceProvider({ theme, density, palette, children, }: GridSurfaceProviderProps): react.JSX.Element;
@@ -1700,4 +1886,326 @@ declare function GridTextProvider({ locale, messages, children }: GridTextProvid
 /** The resolved dictionary. Stable between language changes. */
 declare function useGridText(): GridDictionary;
 
-export { type AlignedGridsApi, BAND_ROW_HEIGHT, type CellMenuOptions, type CellRenderContext, type CellSlotContext, type CellTooltipOptions, DEFAULT_HEADER_MENU_LABELS, DataGrid, type DataGridProps, type DistinctEntry, type EditorRenderContext, type ExportOutcome, GridColumnChooser, type GridColumnChooserProps, GridContextMenu, type GridContextMenuProps, GridFilterPanel, type GridFilterPanelProps, GridFilterRow, type GridFilterRowProps, GridFooterRow, type GridFooterRowProps, GridGroupPanel, type GridGroupPanelProps, GridHeader, GridHeaderBands, type GridHeaderBandsProps, GridHeaderFilterPopup, type GridHeaderFilterPopupProps, type GridHeaderProps, GridLoadingOverlay, type GridLoadingOverlayProps, type GridMenuItem, GridNoteEditor, type GridNotesConfig, GridPager, type GridPagerProps, GridPinnedRows, type GridPinnedRowsProps, GridPopupPanel, type GridPopupPanelProps, GridPortal, type GridPortalProps, GridRow, type GridRowProps, GridSummaryBar, type GridSummaryBarProps, GridSurfaceProvider, type GridSurfaceProviderProps, GridTextProvider, type GridTextProviderProps, GridToolbar, type GridToolbarProps, GridTooltip, type GridTooltipConfig, type GridTooltipProps, type HeaderMenuContext, type HeaderMenuDeps, type HeaderMenuLabels, type HeaderRenderContext, type NoteCellContext, PRINT_MAX_ROWS, type PrintLayoutOptions, type PrintLayoutState, ROW_DRAG_MIME, type ReactColumnRuntime, type ReactGridColumnDef, type RowDragConfig, type RowDragHandlers, type RowDragPayload, type RowDropEvent, type RowMenuContext, type RowReorderEvent, type RowTemplateContext, SHORTCUT_COPY, SHORTCUT_CUT, SHORTCUT_PASTE, type TooltipState, type UseDataGridOptions, type UseDataGridResult, buildCellMenuItems, buildHeaderMenu, copyToClipboard, headerMenuLabels, measureBestFitWidth, reconcileFilterInputs, runGridExport, useAlignedGrids, useAnchoredPopup, useCellTooltip, useDataGrid, useGridChartBoxData, useGridChartData, useGridChartXYData, useGridSurfaceClass, useGridText, usePrintLayout, useRowDrag, useStateStoring, writeClipboardText };
+interface UseGridEditingOptions<TRow = GridRowData> {
+    controller: DataGridController<TRow> | null;
+    mode?: EditMode;
+    rules?: Record<string, ValidationRule<TRow>[]>;
+    onSave?: (changes: unknown[]) => Promise<void> | void;
+    /** Per-row persistence — the app's own insert/update/delete calls. */
+    crud?: CrudHandlers<TRow>;
+    allowAdding?: boolean;
+    allowUpdating?: EditingPermissions<TRow>['allowUpdating'];
+    allowDeleting?: EditingPermissions<TRow>['allowDeleting'];
+    onInitNewRow?: (values: Record<string, unknown>) => void;
+    onRowInserted?: (key: RowKey, row: TRow | undefined) => void;
+    onRowUpdated?: (key: RowKey, row: TRow | undefined, values: Record<string, unknown>) => void;
+    onRowRemoved?: (key: RowKey, row: TRow | undefined) => void;
+    /** Typing a printable key on a focused cell starts editing. Default true. */
+    editOnKeyPress?: boolean;
+    /**
+     * `Insert` opens a blank row ABOVE the focused one. Default false.
+     *
+     * Off by default because Insert is not a neutral key: some users have it
+     * bound elsewhere, and a grid that starts creating records on a keypress
+     * nobody asked for is a surprise.
+     */
+    insertKey?: boolean;
+    /**
+     * Arrow-down on the LAST row appends a blank one. Default false.
+     *
+     * The other half of the same data-entry habit: fill a row, press down, keep
+     * typing. Also off by default — with it on, a user who holds arrow-down to
+     * reach the bottom creates a row when they arrive.
+     */
+    appendOnArrowDown?: boolean;
+    /** Where `addRow()` puts the new record. Default 'last'. */
+    newRowPosition?: NewRowPosition;
+    /** Tab moves between cells inside the grid instead of leaving it. Default true. */
+    focusCellOnTab?: boolean;
+    /** Tab past the end of a row wraps to the next one. Default true. */
+    focusCellOnCycle?: boolean;
+    /** Keep the editor open when Tab moves. Default false. */
+    keepEditingOnTab?: boolean;
+    /**
+     * Ask before deleting. Default: a browser confirm.
+     *
+     * `false` deletes straight away. A FUNCTION replaces the prompt with the
+     * app's own dialog — return false (or a promise of false) to abandon it.
+     */
+    confirmDelete?: boolean | ((rowKey: RowKey, row: TRow | undefined) => boolean | Promise<boolean>);
+    /** Wording for the built-in prompt. Ignored when `confirmDelete` is a function. */
+    confirmDeleteMessage?: string;
+    /** Disables editing entirely (`editing={{ enabled: false }}`). */
+    enabled?: boolean;
+    /**
+     * `editing.range` — the rectangle, the fill handle and the clipboard
+     * gestures (cut / paste). Default true. Off means Ctrl+X and Ctrl+V are left
+     * alone too, the same as the vanilla renderer: one switch, all three.
+     */
+    range?: boolean;
+    /**
+     * Undo / redo: Ctrl+Z and Ctrl+Y (Cmd on a Mac) and `controller.undo()`.
+     * Default true. The free grid passes false — single-cell editing is
+     * Community, history is Enterprise (owner decision, 2026-10-12).
+     */
+    history?: boolean;
+    /**
+     * An extra say on which columns open an editor, on top of the column's own
+     * `editable: false`. The free grid uses it to keep lookup and custom-editor
+     * columns read-only — those editors are Enterprise.
+     */
+    canEditColumn?: (columnId: string) => boolean;
+}
+/**
+ * What the footer strip shows for the current range.
+ *
+ * `numeric` is null when the range holds no numbers at all (a text column), and
+ * `truncated` is true when the range was too large to total — see the limit
+ * below. Both cases are reported rather than shown as zeros.
+ */
+interface SelectionStats {
+    cells: number;
+    truncated: boolean;
+    numeric: {
+        sum: number;
+        count: number;
+        avg: number;
+        min: number;
+        max: number;
+    } | null;
+}
+/** A delete the user has asked for and not yet confirmed. */
+interface PendingDelete {
+    rowKey: RowKey;
+    message: string;
+}
+/** A save the engine refused, with the cell to blame when validation refused it. */
+interface BatchSaveError {
+    message: string;
+    rowKey?: RowKey;
+    columnId?: string;
+}
+/** Range API that keeps React in sync (see the wrapper in the hook). */
+interface RangeApi {
+    start(row: number, column: number): void;
+    /** Begin another range and keep the selected ones (Ctrl/Cmd+click or drag, G-SEL-01). */
+    add(row: number, column: number): void;
+    extend(row: number, column: number): void;
+    finish(): void;
+    clear(): void;
+    contains(row: number, column: number): boolean;
+    isAnchor(row: number, column: number): boolean;
+    getRange(): CellRange | null;
+    getBounds(): ReturnType<RangeSelectionEngine['getBounds']>;
+    /** TSV for the selected rectangle; `textAt` supplies each cell's text. */
+    toTsv(textAt: (row: number, column: number) => string): string;
+    /** Select a whole column (G-SEL-02); false when there are no rows. */
+    selectColumn(column: number, rowCount: number, mode: ColumnSelectMode): boolean;
+    /** The column indexes some range covers from the first row to the last. */
+    fullColumns(rowCount: number): Set<number>;
+}
+interface UseGridEditingResult<TRow = GridRowData> {
+    engine: EditingEngine<TRow> | null;
+    range: RangeApi;
+    /** Bumped on every engine change; consumers read through it. */
+    version: number;
+    beginEdit: (rowKey: RowKey, columnId: string) => void;
+    /**
+     * Open a whole ROW (row / form / popup modes). False when the mode does not
+     * support it, or another row is already open — the caller decides what to
+     * do with the first one rather than having it saved or discarded silently.
+     */
+    beginRowEdit: (rowKey: RowKey) => boolean;
+    /** Validate and persist the open row. Resolves false and stays open on failure. */
+    saveRowEdit: () => Promise<boolean>;
+    /** Discard the open row's edits. Other rows keep theirs. */
+    cancelRowEdit: () => void;
+    /** Message from the last rejected row save; null once anything changes. */
+    rowSaveError: string | null;
+    /**
+     * Adds a pending row and opens its first editable cell. Null when not allowed.
+     *
+     * `beforeKey` puts it directly above that row instead of at the end — what
+     * the Insert key needs.
+     */
+    addRow: (values?: Record<string, unknown>, beforeKey?: RowKey) => RowKey | null;
+    /**
+     * Commit and move to the next (1) or previous (-1) editable cell. By default
+     * the destination is only FOCUSED; pass `open: true` to carry the editor
+     * along, `cycle: false` to stop at the end of a row instead of wrapping.
+     */
+    editAdjacentCell: (direction: 1 | -1, options?: {
+        open?: boolean;
+        cycle?: boolean;
+    }) => boolean;
+    /** Open the editor on the focused cell, seeded with a typed character. */
+    editFocusedCellWith: (char: string) => boolean;
+    /**
+     * Return DOM focus to the grid's scroller. Closing an editor destroys the
+     * element that held focus, so every path that ends a session has to call
+     * this or the keyboard goes dead until the user clicks the grid again.
+     */
+    focusScroller: () => void;
+    deleteRow: (rowKey: RowKey) => boolean;
+    saveChanges: () => Promise<void>;
+    /** Why the last save was refused, or null. */
+    saveError: BatchSaveError | null;
+    /** Dismiss the save error once the user has read it. */
+    clearSaveError: () => void;
+    /** A delete waiting on confirmation, or null. */
+    pendingDelete: PendingDelete | null;
+    /** Answer the confirmation: true deletes, false abandons. */
+    resolveDelete: (confirmed: boolean) => void;
+    cancelChanges: () => void;
+    handleKeyDown: (event: React.KeyboardEvent) => boolean;
+    /**
+     * Copy the selected RANGE, then clear the cells the user may clear. One undo
+     * step. False when there was nothing to cut.
+     *
+     * Cells the permissions refuse are copied but left in place: the user asked
+     * for the part they own, and refusing the whole rectangle over one read-only
+     * column would be the less useful answer.
+     */
+    cut: (target?: {
+        rowKey: RowKey;
+        columnId: string;
+    } | null) => boolean;
+    /**
+     * Copy the selected RANGE. False when no range is selected, which lets the
+     * Community row copy take the gesture instead.
+     */
+    copySelection: () => boolean;
+    /**
+     * Paste the clipboard over the range, anchored at its top-left cell. With no
+     * range, at `target` (the cell a context menu was opened over), else at the
+     * focused cell. Cells the permissions refuse are skipped, as cut skips them.
+     */
+    paste: (target?: {
+        rowKey: RowKey;
+        columnId: string;
+    } | null) => Promise<void>;
+    /** Fill preview rectangle while the handle is dragged, else null. */
+    /** Totals for the current range, or null when nothing is selected. */
+    selectionStats: SelectionStats | null;
+    fillPreview: CellRange | null;
+    startFillDrag: (row: number, column: number) => void;
+    moveFillDrag: (row: number, column: number) => void;
+    endFillDrag: () => void;
+    isDraggingFill: boolean;
+}
+declare function useGridEditing<TRow = GridRowData>(options: UseGridEditingOptions<TRow>): UseGridEditingResult<TRow>;
+
+interface GridCellEditorProps {
+    value: unknown;
+    dataType: GridDataType | undefined;
+    /**
+     * Choices for a lookup/select editor. `null` means the list is still being
+     * fetched — the control renders disabled rather than empty, so the user
+     * cannot commit a blank over a value while the options are in flight.
+     */
+    options?: readonly LookupItem[] | null;
+    /** Let the user type a value outside `options`. */
+    allowCustom?: boolean;
+    /** How typed text narrows the lookup list. Default `'startsWith'`. */
+    matchMode?: LookupMatchMode;
+    /** Accessible name for the editor, used by the lookup combo box. */
+    ariaLabel?: string;
+    /** Format for a `date` column — governs both the mask and the display. */
+    dateFormat?: string;
+    /** Validation message for the current value; null when valid. */
+    error: string | null;
+    /**
+     * The editor was opened by TYPING, so `value` is the character the user just
+     * pressed. The caret goes after it instead of selecting it — selecting would
+     * make the second keystroke erase the first.
+     */
+    seeded?: boolean;
+    onChange: (value: unknown) => void;
+    onCommit: (move: 'down' | 'none') => void;
+    /** Tab / Shift+Tab: commit here and keep editing in the adjacent cell. */
+    onTab: (direction: 1 | -1) => void;
+    onCancel: () => void;
+}
+declare function GridCellEditor({ value, dataType, error, seeded, options, allowCustom, matchMode, ariaLabel, dateFormat, onChange, onCommit, onTab, onCancel, }: GridCellEditorProps): react.JSX.Element;
+
+interface GridDateEditorProps {
+    value: unknown;
+    /** Column format. Defaults to `yyyy-MM-dd`. */
+    format?: string;
+    invalid?: boolean;
+    disabled?: boolean;
+    /**
+     * Take focus on mount. True for a cell editor, false in `row` mode where
+     * every editable cell mounts one at once.
+     */
+    autoFocus?: boolean;
+    testId?: string;
+    columnId?: string;
+    ariaLabel?: string;
+    /**
+     * Commit shape follows the value the editor was GIVEN: a column holding
+     * `Date` objects gets a `Date` back, one holding ISO strings gets a string.
+     * Changing an app's storage shape on save is not the editor's business.
+     */
+    onChange: (value: unknown) => void;
+    onCommit: () => void;
+    onCancel: () => void;
+    onTab?: (shiftKey: boolean) => void;
+}
+declare function GridDateEditor({ value, format, invalid, disabled, autoFocus, testId, columnId, ariaLabel, onChange, onCommit, onCancel, onTab, }: GridDateEditorProps): react.JSX.Element;
+
+interface GridLookupEditorProps {
+    options: readonly LookupItem[];
+    value: unknown;
+    /** Prefix (default) or substring. */
+    matchMode?: LookupMatchMode;
+    /** Let text that matches nothing become the value. Default false. */
+    allowCustom?: boolean;
+    invalid?: boolean;
+    /**
+     * Take focus on mount. True for a cell editor — it opened BECAUSE the user
+     * asked to edit that one cell. False in `row` mode, where every editable cell
+     * mounts an editor at once and each would grab focus in turn, landing the
+     * caret on whichever lookup happened to render last.
+     */
+    autoFocus?: boolean;
+    testId?: string;
+    /** Stamped as `data-column-id`, so callers can find one field of a row. */
+    columnId?: string;
+    ariaLabel?: string;
+    onChange: (value: unknown) => void;
+    /** Commit (Enter / picking an item), handed back to the engine. */
+    onCommit: () => void;
+    /**
+     * Whether picking an item counts as committing. True for a cell editor —
+     * the pick IS the edit. False in `row`/`form` mode, where picking fills one
+     * field of a record the user is still filling in and only Save ends it.
+     */
+    commitOnPick?: boolean;
+    onCancel: () => void;
+    /** Tab moves to the adjacent cell; the engine owns that. */
+    onTab?: (shiftKey: boolean) => void;
+}
+/**
+ * The same match, as items. Kept for callers and tests that want the simple
+ * shape; the component itself works in indices to avoid the copy.
+ */
+declare function matchOptions(options: readonly LookupItem[], query: string, mode: LookupMatchMode): readonly LookupItem[];
+declare function GridLookupEditor({ options, value, matchMode, allowCustom, invalid, autoFocus, testId, columnId, ariaLabel, onChange, onCommit, commitOnPick, onCancel, onTab, }: GridLookupEditorProps): react.JSX.Element;
+
+interface GridDialogProps {
+    open: boolean;
+    title: string;
+    message: string;
+    /** Omitted for an acknowledgement dialog, which gets only the confirm button. */
+    cancelLabel?: string;
+    confirmLabel: string;
+    /** Styles the confirm button as destructive. */
+    danger?: boolean;
+    dark?: boolean;
+    onConfirm: () => void;
+    onCancel: () => void;
+}
+declare function GridDialog({ open, title, message, cancelLabel, confirmLabel, danger, dark, onConfirm, onCancel, }: GridDialogProps): react.ReactPortal | null;
+
+export { type AlignedGridsApi, BAND_ROW_HEIGHT, type BatchSaveError, type CellMenuOptions, type CellRenderContext, type CellSlotContext, type CellTooltipOptions, DEFAULT_HEADER_MENU_LABELS, DataGrid, type DataGridProps, type DistinctEntry, type EditorRenderContext, type ExportOutcome, type FilterRenderContext, GridCellEditor, type GridCellEditorProps, GridColumnChooser, type GridColumnChooserProps, GridContextMenu, type GridContextMenuProps, GridDateEditor, type GridDateEditorProps, GridDialog, type GridDialogProps, GridFilterPanel, type GridFilterPanelProps, GridFilterRow, type GridFilterRowProps, GridFooterRow, type GridFooterRowProps, GridGroupPanel, type GridGroupPanelProps, GridHeader, GridHeaderBands, type GridHeaderBandsProps, GridHeaderFilterPopup, type GridHeaderFilterPopupProps, type GridHeaderProps, GridLoadingOverlay, type GridLoadingOverlayProps, GridLookupEditor, type GridLookupEditorProps, type GridMenuItem, GridNoteEditor, type GridNotesConfig, GridPager, type GridPagerProps, GridPinnedRows, type GridPinnedRowsProps, GridPopupPanel, type GridPopupPanelProps, GridPortal, type GridPortalProps, GridRow, type GridRowProps, GridSummaryBar, type GridSummaryBarProps, GridSurfaceProvider, type GridSurfaceProviderProps, GridTextProvider, type GridTextProviderProps, GridToolbar, type GridToolbarProps, GridTooltip, type GridTooltipConfig, type GridTooltipProps, type HeaderMenuContext, type HeaderMenuDeps, type HeaderMenuLabels, type HeaderRenderContext, type NoteCellContext, PRINT_MAX_ROWS, type PendingDelete, type PrintLayoutOptions, type PrintLayoutState, ROW_DRAG_MIME, type RangeApi, type ReactColumnRuntime, type ReactGridColumnDef, type RowDragConfig, type RowDragHandlers, type RowDragPayload, type RowDropEvent, type RowMenuContext, type RowReorderEvent, type RowTemplateContext, SHORTCUT_COPY, SHORTCUT_CUT, SHORTCUT_PASTE, type SelectionStats, type TooltipState, type UseDataGridOptions, type UseDataGridResult, type UseGridEditingOptions, type UseGridEditingResult, buildCellMenuItems, buildHeaderMenu, copyToClipboard, headerMenuLabels, matchOptions, measureBestFitWidth, reconcileFilterInputs, runGridExport, useAlignedGrids, useAnchoredPopup, useCellTooltip, useDataGrid, useGridChartBoxData, useGridChartData, useGridChartXYData, useGridEditing, useGridSurfaceClass, useGridText, usePrintLayout, useRowDrag, useStateStoring, writeClipboardText };