@kanunilabs/datagrid 1.6.0 → 1.8.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { GridRowData, DataGridController, GridDictionary, RowNode, GridColumnDef, DataGridCoreConfig, GridThemeName, GridPalette, GridDensity, DescribeFilterOptions, RowKey, StateStoringConfig, InferColumnsOptions } from '@kanunilabs/datagrid-core';
-export { DENSITY_ROW_HEIGHT, DataGridController, GridColumnDef, GridDensity, GridRowData, GridTheme, GridThemeName, RowKey, RowNode, SortDescriptor, THEME_ROW_HEIGHT, isPackagedTheme, presetRowHeight } from '@kanunilabs/datagrid-core';
+import { GridRowData, DataGridController, GridDictionary, GridDataType, LookupItem, LookupMatchMode, EditingEngineOptions, RowKey, EditingEngine, RowChange, RowNode, GridColumnDef, DataGridCoreConfig, FilterRenderContextBase, FilterNode, GridThemeName, GridPaletteName, GridDensity, DescribeFilterOptions, CardViewOptions, StateStoringConfig, InferColumnsOptions } from '@kanunilabs/datagrid-core';
+export { CustomFilterOperator, CustomFilterOperatorId, DENSITY_ROW_HEIGHT, DataGridController, FilterNode, GRID_COLOR_SCHEMES, GridColorScheme, GridColumnDef, GridDensity, GridPaletteName, GridRowData, GridTheme, GridThemeName, RowKey, RowNode, SortDescriptor, THEME_ROW_HEIGHT, isPackagedTheme, presetRowHeight } from '@kanunilabs/datagrid-core';
 
 /** What a header menu is opened against — the React shape, verbatim. */
 interface HeaderMenuContext {
@@ -26,6 +26,156 @@ declare function buildHeaderMenu<TRow = GridRowData>(context: HeaderMenuContext,
 /** Formats an export menu can offer. */
 type ExportKind = 'csv' | 'excel' | 'excel-selected' | 'pdf';
 
+/** What the cell editor hands a lookup builder — the Enterprise `buildLookupEditor` takes it as is. */
+interface CellLookupEditorSpec {
+    options: readonly LookupItem[];
+    value: unknown;
+    matchMode?: LookupMatchMode;
+    allowCustom?: boolean;
+    invalid?: boolean;
+    testId?: string;
+    ariaLabel?: string;
+    surfaceClass?: string;
+    onPortalOpen?: (close: () => void) => void;
+    noMatchText: string;
+    onChange: (value: unknown) => void;
+    onCommit: () => void;
+    onCancel: () => void;
+    onTab?: (shiftKey: boolean) => void;
+}
+interface CellEditorSpec {
+    value: unknown;
+    dataType: GridDataType | undefined;
+    /** 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;
+    /**
+     * Choices for a lookup column. `null` = 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 (E3).
+     */
+    options?: readonly LookupItem[] | null;
+    allowCustom?: boolean;
+    matchMode?: LookupMatchMode;
+    /** Format for a `date` column — governs both the mask and the display. */
+    dateFormat?: string;
+    ariaLabel?: string;
+    /**
+     * Called when the editor opens a layer on `document.body` (the lookup list,
+     * the date calendar), handing back the function that closes it again.
+     *
+     * The layer outlives its cell by design — it is portalled so the grid's
+     * scroller cannot clip it — which means removing the grid's DOM does not
+     * remove it. Without this the layer stayed on screen after
+     * `grid.destroy()`, hanging over whatever the app rendered next, until the
+     * next scroll or resize let `place()` notice the input was gone.
+     *
+     * The editing layer keeps the closer and calls it on dispose. Scoped per
+     * grid on purpose: a global registry would let one grid's teardown close
+     * another grid's open dropdown.
+     */
+    onPortalOpen?: (close: () => void) => void;
+    /** The portal surface classes for the calendar / lookup list. */
+    surfaceClass?: string;
+    /** Dictionary — the date calendar's captions and the no-match text. */
+    t?: GridDictionary;
+    /**
+     * Builds the combo box for a lookup column (`options` non-empty). Supplied
+     * by the Enterprise edition; without it a lookup column falls back to the
+     * plain editor for its data type.
+     */
+    renderLookup?: (spec: CellLookupEditorSpec) => HTMLElement;
+    onChange: (value: unknown) => void;
+    onCommit: (move: 'down' | 'none') => void;
+    /** Tab / Shift+Tab: commit here and keep going in the adjacent cell. */
+    onTab: (direction: 1 | -1) => void;
+    onCancel: () => void;
+}
+/** Build the editor. The caller drops the fragment into the CELL. */
+declare function buildCellEditor(spec: CellEditorSpec): DocumentFragment;
+
+/**
+ * The Community `editing` option of `createGrid`. Passing the object turns
+ * single-cell editing on; `{ enabled: false }` turns it off again. Columns
+ * with `editable: false` stay read-only.
+ */
+interface CellEditingOptions<TRow = GridRowData> {
+    /** Default true once `editing` is passed. */
+    enabled?: boolean;
+    /**
+     * Persist a committed cell. Called once per commit with the change (the
+     * Enterprise `onSave` shape). A rejection is shown in a dialog and the user
+     * is put back on the cell.
+     */
+    onSave?: (changes: RowChange<TRow>[]) => Promise<void> | void;
+    /** Typing a printable key on a focused cell starts editing. Default true. */
+    editOnKeyPress?: boolean;
+    /** Tab moves between editable cells inside the grid. Default true. */
+    focusCellOnTab?: boolean;
+    /** Tab past the end of a row wraps to the next one. Default true. */
+    focusCellOnCycle?: boolean;
+}
+interface CellEditingHelpers {
+    /** Theme classes for portalled layers (the dialog, the date calendar). */
+    surfaceClass(): string;
+}
+/**
+ * What the Enterprise layer adds. Not part of the Community surface: the
+ * Community grid never builds one.
+ */
+interface CellEditingExtension<TRow = GridRowData> {
+    /** Engine options beyond the Community set — mode, rules, CRUD, permissions. */
+    engine?: Partial<EditingEngineOptions<TRow>>;
+    /** Column-level editability. Default: the column's `editable` flag. */
+    isColumnEditable?: (columnId: string) => boolean;
+    /** Keep the editor open when Tab moves. Default false. */
+    keepEditingOnTab?: boolean;
+    /** After every engine change and the repaint it requests. */
+    onChange?: () => void;
+    /** The choices for a lookup cell; `options: undefined` = not a lookup. */
+    resolveLookup?: (rowKey: RowKey, columnId: string) => {
+        options: readonly LookupItem[] | null | undefined;
+        allowCustom?: boolean;
+        matchMode?: LookupMatchMode;
+    };
+    /** The lookup combo box builder, for `buildCellEditor`. */
+    renderLookup?: CellEditorSpec['renderLookup'];
+    /** Honour a column's `renderEditor`. Default false. */
+    customEditors?: boolean;
+    /** Something drawn into a cell that is NOT being edited (the fill handle). */
+    cellAdornment?: (ctx: CellSlotContext<TRow>) => Node | null;
+}
+interface CellEditingLayer<TRow = GridRowData> {
+    engine: EditingEngine<TRow>;
+    renderCellContent(ctx: CellSlotContext<TRow>): Node | string | undefined;
+    getCellClassName(ctx: CellSlotContext<TRow>): string | undefined;
+    onCellDoubleClick(ctx: CellSlotContext<TRow>): void;
+    /** Capture-phase keyboard. True = consumed. */
+    handleKeyDown(event: KeyboardEvent): boolean;
+    /** Escape over an orphaned session, and Tab with no editor open. */
+    handleSessionKeys(event: KeyboardEvent): boolean;
+    /** F2 and type-to-edit — checked last so they never shadow a binding. */
+    handleOpenKeys(event: KeyboardEvent): boolean;
+    /** Commit the open editor and move to the next (1) or previous (-1) editable cell. */
+    editAdjacentCell(direction: 1 | -1, opts?: {
+        open?: boolean;
+        cycle?: boolean;
+    }): boolean;
+    /** Put DOM focus back on the grid after an editor closed. */
+    focusGrid(): void;
+    /** Hands a portalled layer's closer to `dispose()`. */
+    trackPortal(close: () => void): void;
+    /** What the Community renderer would paint for `value` in this cell. */
+    defaultContent(ctx: CellSlotContext<TRow>, value: unknown): Node | string;
+    dispose(): void;
+}
+declare function attachCellEditing<TRow = GridRowData>(grid: Pick<GridApi<TRow>, 'controller' | 'element'>, options: CellEditingOptions<TRow>, t: GridDictionary, helpers: CellEditingHelpers, extension?: CellEditingExtension<TRow>): CellEditingLayer<TRow>;
+
 /** Same value as the React renderer's lead column. */
 declare const ROW_NUMBER_COLUMN_WIDTH = 60;
 /** Same value as the React renderer's CHECKBOX_COLUMN_WIDTH. */
@@ -221,12 +371,38 @@ interface VanillaEditorRenderContext<TRow = GridRowData> {
     commit: () => void;
     cancel: () => void;
 }
+/**
+ * What a column's own filter UI is handed (`renderFilter`) — the React
+ * `FilterRenderContext`, DOM-flavoured. The control is built ONCE into its
+ * host, so instead of a `value` that re-renders it reads `getValue()` and
+ * subscribes with `onValueChange` (a cleared filter, a restored view).
+ */
+interface VanillaFilterRenderApi<TRow = GridRowData> extends FilterRenderContextBase<TRow> {
+    /** The filter this surface holds now. */
+    getValue: () => FilterNode | null;
+    /** Called with the surface's filter after every filter change; returns an unsubscribe. */
+    onValueChange: (listener: (value: FilterNode | null) => void) => () => void;
+}
 type VanillaColumnDef<TRow = GridRowData> = GridColumnDef<TRow> & {
     renderCell?: (ctx: CellRenderContext<TRow>) => string | Node;
+    /**
+     * Replace this column's filter UI with your own — the React `renderFilter`,
+     * DOM-typed. Build the control into `host`; return a teardown if it holds
+     * anything to release. Drawn in the filter row's cell (`api.surface ===
+     * 'row'`) when `filterRow` is on, and as the header popup's content
+     * (`'popup'`) when `headerFilter` is on.
+     *
+     * `api.setValue` takes any filter for this column — a built-in condition, a
+     * group, or one using a custom operator from `filterOperators` — or null to
+     * clear, through the same `setColumnFilter` the built-in surfaces use. The
+     * filter row repaints its cells on column changes and horizontal scroll, so
+     * the control may be built more than once: seed it from `api.getValue()`.
+     */
+    renderFilter?: (host: HTMLElement, api: VanillaFilterRenderApi<TRow>) => (() => void) | void;
     /**
      * Replace this column's cell editor outright — the React `renderEditor`,
-     * DOM-typed. Enterprise: `createGrid` never edits, so a Community grid
-     * ignores this the way it ignores every other editing option.
+     * DOM-typed. Enterprise: a Community grid with `editing` on edits this
+     * column with the built-in editor for its data type and ignores this.
      *
      * Return the control itself (an `<input>`, a fragment, a whole widget). The
      * grid focuses it, routes Escape/Tab around it and tears it down; everything
@@ -260,6 +436,13 @@ type VanillaColumnDef<TRow = GridRowData> = GridColumnDef<TRow> & {
      * strips a flash pulse mid-animation.
      */
     cellClassName?: string | ((ctx: CellRenderContext<TRow>) => string | undefined);
+    /**
+     * Rich tooltip content for this column's cells (P-TOOL-01) — the React
+     * `renderTooltip`, DOM-typed: return a node (an image, a small table, a
+     * link) or text. Wins over `tooltip` and `tooltipField`; null shows none.
+     * Pair it with `tooltip.interactive` when the content holds something to click.
+     */
+    renderTooltip?: (ctx: CellRenderContext<TRow>) => Node | string | null | undefined;
     /**
      * Tooltip for this column's HEADER cell. Static by nature — a header has one
      * value — which is why it is a string and not the cell tooltip's union.
@@ -281,7 +464,12 @@ interface CreateGridConfig<TRow = GridRowData> extends Omit<DataGridCoreConfig<T
      * theme has no row-height preset — set `rowHeight` or `density` with it.
      */
     theme?: GridThemeName;
-    palette?: GridPalette;
+    /**
+     * A classic palette, one of the 36 packaged colour schemes (with
+     * `@kanunilabs/datagrid/themes/<id>.css` loaded after `styles.css`), or your
+     * own scheme's name from the Theme Builder.
+     */
+    palette?: GridPaletteName;
     density?: GridDensity;
     dark?: boolean;
     /** Zebra rows. Default TRUE — the React renderer's default. */
@@ -340,6 +528,21 @@ interface CreateGridConfig<TRow = GridRowData> extends Omit<DataGridCoreConfig<T
      * it keeps its caret.
      */
     renderRow?: (context: RowTemplateContext<TRow>) => string | Node | null | undefined;
+    /**
+     * 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). While
+     * cards are shown they replace `renderRow`. The React prop, unchanged.
+     */
+    cardView?: boolean | CardViewOptions;
+    /** The grid switched between cards (`true`) and the table, as its width crossed the breakpoint. */
+    onCardViewChange?: (active: boolean) => void;
     /**
      * A polite live region reporting row count, sort and selection to screen
      * readers. Default true.
@@ -368,6 +571,14 @@ interface CreateGridConfig<TRow = GridRowData> extends Omit<DataGridCoreConfig<T
     resizable?: boolean;
     /** Drag a header onto another to reorder. Default true. */
     reorderable?: 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. The React prop, unchanged: the height is measured after
+     * layout (only the columns on screen), and everything stuck under the
+     * header moves with it.
+     */
+    autoHeaderHeight?: boolean;
     /** Per-column text inputs under the header. */
     filterRow?: boolean;
     /** ms before typed filter text reaches the engine. Same default as React:
@@ -557,11 +768,35 @@ interface CreateGridConfig<TRow = GridRowData> extends Omit<DataGridCoreConfig<T
         enabled?: boolean;
         delay?: number;
         showOnTruncation?: boolean;
+        /**
+         * What opens a cell's tooltip (P-TOOL-01): `'hover'` (default), `'focus'`
+         * (the cell taking keyboard focus — arrowing onto it, or tapping it on
+         * a touch screen) or `'both'`. A focus tooltip is tied to its cell with
+         * `aria-describedby`; Escape closes it.
+         */
+        trigger?: 'hover' | 'focus' | 'both';
+        /** Let the pointer move onto the tooltip, to select its text or click a link in it. */
+        interactive?: boolean;
     };
     /** Drop strip above the grid: drag a header here to group by it. Reads
      *  `grouping.panel` exactly like the React prop shape. */
     /** Search box debounce, ms. React's default. */
     searchDebounce?: number;
+    /**
+     * Single-cell editing (Community since 2026-10-12). Off unless passed:
+     * `editing: {}` turns it on, `{ enabled: false }` off again. Double-click,
+     * F2 or typing opens the in-cell editor (text, number, date, checkbox);
+     * Enter commits and moves down, Tab / Shift+Tab commit and move to the next
+     * editable cell, Escape cancels. Each commit is written to the row and
+     * handed to `onSave`. Columns with `editable: false` stay read-only, and so
+     * do lookup and cell-formula columns, whose editors are Enterprise.
+     *
+     * Batch/row/form/popup modes, validation rules, CRUD handlers, permissions,
+     * custom and lookup editors, undo/redo and range selection are Enterprise
+     * (`createEnterpriseGrid`); passed here they are ignored, and named in the
+     * console under `debugMode`.
+     */
+    editing?: CellEditingOptions<TRow>;
     /** Replace a body cell's content. `undefined` = the default painter runs. */
     renderCellContent?: (ctx: CellSlotContext<TRow>) => Node | string | undefined;
     /**
@@ -588,6 +823,15 @@ interface CreateGridConfig<TRow = GridRowData> extends Omit<DataGridCoreConfig<T
     onCellPointerDown?: (ctx: CellSlotContext<TRow>, event: MouseEvent) => void;
     onCellPointerEnter?: (ctx: CellSlotContext<TRow>, event: 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: MouseEvent) => boolean;
+    /** Extra class names per header cell, re-read on every paint (a selected column). */
+    getHeaderClassName?: (columnId: string) => string | undefined;
+    /** Replace a header's label when the header is built (a rename box). Undefined = the label. */
+    renderHeaderLabel?: (columnId: string) => Node | undefined;
 }
 interface GridApi<TRow = GridRowData> {
     /** The engine, whole. The same object React hands to `onReady`. */
@@ -607,4 +851,55 @@ declare function createGrid<TRow = GridRowData>(container: HTMLElement, config:
  */
 declare function measureBestFitWidth(root: HTMLElement, columnId: string): number | null;
 
-export { CHECKBOX_COLUMN_WIDTH, type CellMenuOptions, type CellRenderContext, type CellSlotContext, type CreateGridConfig, DETAIL_COLUMN_WIDTH, type ExportKind, type GridApi, type GridMenuItem, type GridNotesConfig, type HeaderMenuContext, type HeaderMenuDeps, type NoteCellContext, PRINT_MAX_ROWS, type PrintLayoutOptions, ROW_DRAG_MIME, ROW_NUMBER_COLUMN_WIDTH, type RowDragConfig, type RowDragPayload, type RowDropEvent, type RowMenuContext, type RowReorderEvent, type RowTemplateContext, type VanillaColumnDef, type VanillaEditorRenderContext, buildHeaderMenu, createGrid, measureBestFitWidth };
+interface DateEditorSpec {
+    value: unknown;
+    /** Column format. Defaults to `yyyy-MM-dd`. */
+    format?: string;
+    invalid?: boolean;
+    disabled?: boolean;
+    autoFocus?: boolean;
+    testId?: string;
+    columnId?: string;
+    ariaLabel?: string;
+    /** The portal's surface classes, so the calendar resolves --dg tokens. */
+    surfaceClass?: string;
+    t: GridDictionary;
+    /** Commit shape follows the value the editor was GIVEN: a Date column gets
+     *  a Date back, an ISO-string column gets a string. */
+    onChange: (value: unknown) => void;
+    onCommit: () => void;
+    onCancel: () => void;
+    /**
+     * Called when the editor opens a layer on `document.body` (the lookup list,
+     * the date calendar), handing back the function that closes it again.
+     *
+     * The layer outlives its cell by design — it is portalled so the grid's
+     * scroller cannot clip it — which means removing the grid's DOM does not
+     * remove it. Without this the layer stayed on screen after
+     * `grid.destroy()`, hanging over whatever the app rendered next, until the
+     * next scroll or resize let `place()` notice the input was gone.
+     *
+     * The editing layer keeps the closer and calls it on dispose. Scoped per
+     * grid on purpose: a global registry would let one grid's teardown close
+     * another grid's open dropdown.
+     */
+    onPortalOpen?: (close: () => void) => void;
+    onTab?: (shiftKey: boolean) => void;
+}
+declare function buildDateEditor(spec: DateEditorSpec): HTMLElement;
+
+interface ConfirmDialogSpec {
+    title: string;
+    message: string;
+    confirmLabel: string;
+    /** Omitted for an acknowledgement dialog, which gets only confirm. */
+    cancelLabel?: string;
+    /** Styles the confirm button as destructive. */
+    danger?: boolean;
+    /** The enterprise wrapper's theme/dark classes, re-established here. */
+    surfaceClass?: string;
+}
+/** Open the dialog; resolves the user's answer and removes itself. */
+declare function openConfirmDialog(spec: ConfirmDialogSpec): Promise<boolean>;
+
+export { CHECKBOX_COLUMN_WIDTH, type CellEditingExtension, type CellEditingHelpers, type CellEditingLayer, type CellEditingOptions, type CellEditorSpec, type CellLookupEditorSpec, type CellMenuOptions, type CellRenderContext, type CellSlotContext, type ConfirmDialogSpec, type CreateGridConfig, DETAIL_COLUMN_WIDTH, type DateEditorSpec, type ExportKind, type GridApi, type GridMenuItem, type GridNotesConfig, type HeaderMenuContext, type HeaderMenuDeps, type NoteCellContext, PRINT_MAX_ROWS, type PrintLayoutOptions, ROW_DRAG_MIME, ROW_NUMBER_COLUMN_WIDTH, type RowDragConfig, type RowDragPayload, type RowDropEvent, type RowMenuContext, type RowReorderEvent, type RowTemplateContext, type VanillaColumnDef, type VanillaEditorRenderContext, type VanillaFilterRenderApi, attachCellEditing, buildCellEditor, buildDateEditor, buildHeaderMenu, createGrid, measureBestFitWidth, openConfirmDialog };