@kanunilabs/datagrid 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,501 @@
+import { GridRowData, DataGridController, GridDictionary, RowNode, GridColumnDef, DataGridCoreConfig, GridTheme, GridPalette, GridDensity, DescribeFilterOptions, RowKey, StateStoringConfig } from '@kanunilabs/datagrid-core';
+export { DENSITY_ROW_HEIGHT, DataGridController, GridColumnDef, GridDensity, GridRowData, GridTheme, RowKey, RowNode, SortDescriptor, THEME_ROW_HEIGHT, presetRowHeight } from '@kanunilabs/datagrid-core';
+
+/** What a header menu is opened against — the React shape, verbatim. */
+interface HeaderMenuContext {
+    columnId: string;
+    /** Header text as rendered, for labels and announcements. */
+    headerName: string;
+}
+interface HeaderMenuDeps<TRow = GridRowData> {
+    controller: DataGridController<TRow>;
+    t: GridDictionary;
+    /** Current UI switches the menu toggles operate on. */
+    groupPanelVisible: boolean;
+    footerVisible: boolean;
+    onToggleGroupPanel: () => void;
+    onToggleFooter: () => void;
+    onOpenFieldChooser: () => void;
+    onBestFit: (columnId: string) => void;
+    onBestFitAll: () => void;
+    /** Grouping levels allowed — 1 in Community, the React rule. */
+    maxGroupLevels: number;
+}
+declare function buildHeaderMenu<TRow = GridRowData>(context: HeaderMenuContext, deps: HeaderMenuDeps<TRow>): GridMenuItem<HeaderMenuContext>[];
+
+/** 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. */
+declare const CHECKBOX_COLUMN_WIDTH = 36;
+/** Same value as the React renderer's master-detail expander column. */
+declare const DETAIL_COLUMN_WIDTH = 28;
+/** MIME type carrying a dragged row. The SAME string the React renderer uses,
+ *  so a row can cross between a React grid and a vanilla grid on one page. */
+declare const ROW_DRAG_MIME = "application/x-kanuni-row";
+/** What travels in `dataTransfer` when a row leaves its grid. */
+interface RowDragPayload {
+    /** Grid the row started in — a same-grid drop is a REORDER, not a move. */
+    gridId: string;
+    /** Only grids sharing a group exchange rows. */
+    group: string | null;
+    rowKey: RowKey;
+    /** The row itself, so the receiving grid can insert it without a round trip. */
+    row: unknown;
+}
+interface RowReorderEvent<TRow = GridRowData> {
+    dragKey: RowKey;
+    /** Row it was dropped onto, or null for the empty space past the last row. */
+    targetKey: RowKey | null;
+    position: 'before' | 'after';
+    row: TRow | undefined;
+}
+interface RowDropEvent<TRow = GridRowData> {
+    /** Row that crossed over, as the source grid had it. */
+    row: TRow;
+    rowKey: RowKey;
+    /** Grid it came from / went to. */
+    otherGridId: string;
+    targetKey: RowKey | null;
+    position: 'before' | 'after';
+}
+/** The React `rowDrag` prop's shape, DOM-flavoured. */
+interface RowDragConfig<TRow = GridRowData> {
+    enabled?: boolean;
+    /** Grids sharing a group can exchange rows. */
+    group?: string;
+    /** Reordering within this grid. Default true. */
+    allowReordering?: boolean;
+    /** Accept rows from another grid in the group. Default true when `group` is set. */
+    allowDropInsert?: boolean;
+    /** A row was moved within this grid. Without a handler the grid reorders its
+     *  own source array; with one, YOU own the order. */
+    onReorder?: (event: RowReorderEvent<TRow>) => void;
+    /** A row arrived from another grid. */
+    onAdd?: (event: RowDropEvent<TRow>) => void;
+}
+/** Default row cap. Report-sized results print; result sets do not. */
+declare const PRINT_MAX_ROWS = 5000;
+interface PrintLayoutOptions {
+    /** Stay in print layout permanently — for a grid rendered INTO a report page. */
+    always?: boolean;
+    /** Above this many rows the grid does NOT switch (default 5.000): print
+     *  layout puts every row in the DOM, and past report sizes that is a frozen
+     *  tab behind a dialog the user cannot cancel. Use exportPdf() there. */
+    maxRows?: number;
+}
+/** What a row template is handed — the React `RowTemplateContext`. */
+interface RowTemplateContext<TRow> {
+    row: TRow;
+    node: RowNode<TRow>;
+    /** Position in the current view, not in the source array. */
+    rowIndex: number;
+    selected: boolean;
+    /** True when this is the focused row (`focusedRow` is on). */
+    focused: boolean;
+}
+/** The React `GridMenuItem`, DOM-flavoured: `icon` is a string or a Node. */
+interface GridMenuItem<TContext = unknown> {
+    /** Stable key; falls back to the index when omitted. */
+    id?: string;
+    label?: string;
+    icon?: string | Node;
+    /** Right-aligned hint, e.g. "Ctrl+C". Purely visual — no binding is created. */
+    shortcut?: string;
+    disabled?: boolean;
+    /** Renders a divider instead of an item. */
+    separator?: boolean;
+    /** One level of nesting. */
+    items?: GridMenuItem<TContext>[];
+    onSelect?: (context: TContext) => void;
+}
+/** What a row menu is opened against — the React shape, verbatim. */
+interface RowMenuContext<TRow = GridRowData> {
+    row: TRow;
+    node: RowNode<TRow>;
+    /** Index in the current view. */
+    rowIndex: number;
+    /** Column under the pointer, when the menu was opened from a cell. */
+    columnId: string | null;
+    /** Selected row keys at the moment the menu opened. */
+    selectedKeys: RowKey[];
+}
+/**
+ * What the Enterprise cell slots are handed — the React `CellSlotContext`,
+ * verbatim. `rowIndex`/`columnIndex` are VIEW coordinates (a range is a
+ * rectangle over what the user sees).
+ */
+interface CellSlotContext<TRow = GridRowData> {
+    node: RowNode<TRow>;
+    columnId: string;
+    rowIndex: number;
+    columnIndex: number;
+    value: unknown;
+}
+/** Which cell a note belongs to — the React `NoteCellContext`, verbatim. */
+interface NoteCellContext<TRow = GridRowData> {
+    rowKey: RowKey;
+    columnId: string;
+    row: TRow;
+}
+/**
+ * Cell notes (P3.3) — the React `GridNotesConfig`, verbatim. The grid SHOWS
+ * notes (marker + tooltip) and, with `onChange`, collects edits; it does not
+ * decide where they live, because a note that survives a reload has to go
+ * somewhere only the app knows about.
+ */
+interface GridNotesConfig<TRow = GridRowData> {
+    /** This cell's note, or null. Called for every RENDERED cell — make it a lookup. */
+    get: (ctx: NoteCellContext<TRow>) => string | null | undefined;
+    /** The user changed a note; `text` is null when they cleared it. Its PRESENCE makes notes editable. */
+    onChange?: (ctx: NoteCellContext<TRow> & {
+        text: string | null;
+    }) => void;
+    /** Append add/edit/delete items to the row context menu. Default true when `onChange` is given. */
+    menu?: boolean;
+}
+/** What a custom cell renderer is handed — the React `CellRenderContext`, DOM-flavoured. */
+interface CellRenderContext<TRow = GridRowData> {
+    value: unknown;
+    row: TRow;
+    node: RowNode<TRow>;
+    column: GridColumnDef<TRow>;
+}
+/**
+ * Column definition, plus the vanilla escape hatch.
+ *
+ * `renderCell` returns a string (set as textContent — safe by construction, no
+ * HTML parsing) or a Node (adopted as the cell's content). This is the honest
+ * translation of React's ReactNode contract: there is no vanilla equivalent of
+ * an element tree, and pretending otherwise would mean shipping an HTML-string
+ * API and its injection surface.
+ */
+type VanillaColumnDef<TRow = GridRowData> = GridColumnDef<TRow> & {
+    renderCell?: (ctx: CellRenderContext<TRow>) => string | Node;
+    /** Replace the header cell's LABEL — the React `renderHeader`, DOM-typed.
+     *  Sorting, funnel, reorder and resize chrome behave as the def's own flags
+     *  say; a chrome column (the command column) turns them all off itself. */
+    renderHeader?: (ctx: {
+        column: VanillaColumnDef<TRow>;
+    }) => string | Node;
+    /**
+     * Tooltip for this column's cells — the React column extension, DOM-typed.
+     * A string is static; a function runs only for the cell under the pointer,
+     * so it may be as expensive as it needs to be. Return null to suppress the
+     * tooltip INCLUDING the truncation fallback.
+     */
+    tooltip?: string | ((ctx: CellRenderContext<TRow>) => string | null | undefined);
+    /** Read the tooltip from another field of the row. `tooltip` wins. */
+    tooltipField?: string;
+    /**
+     * Let this column's text WRAP, and let the row grow to fit it. Only
+     * RENDERED rows can be measured, so the scrollbar firms up as the user
+     * travels — every virtualized grid that measures has this property.
+     */
+    autoHeight?: boolean;
+};
+interface CreateGridConfig<TRow = GridRowData> extends Omit<DataGridCoreConfig<TRow>, 'columns'> {
+    columns: VanillaColumnDef<TRow>[];
+    theme?: GridTheme;
+    palette?: GridPalette;
+    density?: GridDensity;
+    dark?: boolean;
+    /** Zebra rows. Default TRUE — the React renderer's default. */
+    striped?: boolean;
+    /** Leading 1-based row-number column. Adapter chrome; core never sees it. */
+    rowNumbers?: boolean;
+    /** Text of the empty-state overlay. Defaults to the locale dictionary. */
+    emptyText?: string;
+    /** Label of the busy overlay. Defaults to the locale dictionary. */
+    loadingText?: string;
+    /**
+     * The busy overlay. `true` (default) shows it after 300 ms of continuous
+     * FOREGROUND work; a number sets that delay; `false` turns it off entirely.
+     *
+     * The delay is not decoration. Every filter keystroke re-runs the pipeline,
+     * and a pass that finishes in 20 ms would raise and drop the overlay faster
+     * than anyone can read it — a strobe. Background passes (a streamed
+     * transaction batch, a block fetch caused by scrolling) never raise it at
+     * all: the user did not ask for them and is not waiting on them.
+     *
+     * `controller.showLoadingOverlay()` is an explicit decision rather than a
+     * flicker to absorb, so it appears at once, delay skipped.
+     */
+    loadingOverlay?: boolean | number;
+    /** Dictionary locale (core's twelve). Default 'en'. */
+    locale?: string;
+    /** Totals row pinned to the bottom edge. Values come from `summaries`. */
+    footer?: boolean;
+    /**
+     * Wording for the filter panel's sentence — operator captions, the list
+     * separator, and `maxListValues` (how long an `in` list gets before it
+     * collapses to "N values").
+     *
+     * Defaults come from the grid's LOCALE; what you pass overrides key by key,
+     * so an app can rename one operator without restating the other thirteen.
+     */
+    filterPanelLabels?: DescribeFilterOptions;
+    /**
+     * Replace each DATA row's content. Group headers and detail panels keep
+     * their own rendering — a template that had to handle those too would be a
+     * template of the whole grid.
+     *
+     * The row ELEMENT stays: it carries the height, the aria indices, the zebra
+     * and selection classes and the handlers the virtualizer depends on. What
+     * the template replaces are the CELLS — including the lead ones, so the row
+     * number, the detail expander and the selection checkbox are not drawn while
+     * it is on, and in-cell editing and range selection have nothing to attach
+     * to. (The drag grip survives: it is not a cell.) React draws exactly the
+     * same line.
+     *
+     * For per-cell customization that keeps the column layout, use a column's
+     * `renderCell`.
+     *
+     * Returning the SAME node you returned last time is how a template says
+     * "nothing changed" — the DOM is then left alone, so a focused input inside
+     * it keeps its caret.
+     */
+    renderRow?: (context: RowTemplateContext<TRow>) => string | Node | null | undefined;
+    /**
+     * A polite live region reporting row count, sort and selection to screen
+     * readers. Default true.
+     *
+     * Sorting and filtering are otherwise visual-only events: the rows change
+     * under a screen-reader user with nothing said. The text is built from the
+     * resolved dictionary, so it is announced in the grid's language.
+     */
+    announcements?: boolean;
+    /**
+     * Clicking a footer cell opens the aggregation picker — No total / Count /
+     * Sum / Average / Min / Max, filtered to what the column's data type
+     * supports, so a text column is never offered a Sum (`Number()` over names
+     * totals 0, and a 0 in a footer is indistinguishable from a real zero).
+     * Default true; `false` makes the footer read-only.
+     *
+     * With it on, a cell holding no total shows a faint dot — otherwise the
+     * only affordance is an empty rectangle nobody thinks to click.
+     */
+    footerMenu?: boolean;
+    /** Rows fixed above the scrolling body. Adapter chrome, like React's. */
+    pinnedTopRows?: readonly TRow[];
+    /** Rows fixed below the scrolling body. */
+    pinnedBottomRows?: readonly TRow[];
+    /** Drag the trailing edge of a header to resize. Default true. */
+    resizable?: boolean;
+    /** Drag a header onto another to reorder. Default true. */
+    reorderable?: boolean;
+    /** Per-column text inputs under the header. */
+    filterRow?: boolean;
+    /** ms before typed filter text reaches the engine. Same default as React:
+     *  0 for local data (the pipeline is the debounce), 200 for remote. */
+    filterDebounce?: number;
+    /** Funnel buttons opening the distinct-value checkbox popup. */
+    headerFilter?: boolean;
+    /**
+     * When the header's funnel icon is visible: `'hover'` (default) reveals it
+     * on hover or keyboard focus, `'always'` pins it. An ACTIVE filter stays
+     * visible in both modes — it is the only sign that rows are being withheld.
+     */
+    filterIconMode?: 'hover' | 'always';
+    /** The active filter, in words, with one-click clear. */
+    /**
+     * The strip under the grid that says, in words, what is being filtered —
+     * with an × to drop it and a checkbox to suspend it without losing it.
+     *
+     * `'always'` keeps the strip on screen with no filter applied, so the
+     * control does not appear and disappear under the pointer.
+     */
+    filterPanel?: boolean | 'always';
+    /**
+     * Opens the app's filter builder from the panel's chevron. Without it the
+     * chevron is not drawn, because a control that opens nothing is worse than
+     * no control — React's rule, and the Enterprise wrapper wires it to its own
+     * builder.
+     */
+    onOpenFilterBuilder?: () => void;
+    /** Highlight the row that holds focus. Default false — the React default. */
+    focusedRow?: boolean;
+    /**
+     * Focus this row when the grid is built — the React `focusedRowKey` prop.
+     *
+     * React re-applies it whenever the prop changes; a vanilla config is read
+     * once, so this is the STARTING focus and later moves go through
+     * `grid.controller.focusRow(key)`. Said plainly because a silently
+     * one-shot prop is exactly the kind of thing that costs an afternoon.
+     */
+    focusedRowKey?: RowKey | null;
+    /** Fired when the focused ROW changes — not on every cell move within it. */
+    onFocusedRowChanged?: (event: {
+        rowKey: RowKey | null;
+        row?: TRow;
+    }) => void;
+    /** Fired on a click anywhere in a row, before the grid's own row event. */
+    onRowClick?: (node: RowNode<TRow>) => void;
+    /** Fired on Enter / double-click over the focused row. */
+    onRowActivate?: (node: RowNode<TRow>) => void;
+    /**
+     * Where the totals row sits: `'bottom'` (default) or `'top'`, directly
+     * under the header — the React `footerPosition` prop. Enterprise, like the
+     * totals themselves.
+     */
+    footerPosition?: 'top' | 'bottom';
+    /**
+     * Cell notes (P3.3): a marker on noted cells, the note as the hover
+     * tooltip, and — with `onChange` — add/edit/delete on the row menu with an
+     * anchored textarea. Enterprise: ignored (reported under `debugMode`)
+     * without `enterpriseEdition`, the React rule.
+     */
+    notes?: GridNotesConfig<TRow>;
+    /**
+     * Wrap search matches in `<mark>` inside the cell. Default true — the React
+     * `highlightSearch` prop. Applied to the FINISHED text (after the lookup,
+     * the formatter and the date format), because that is what the reader
+     * searched.
+     */
+    highlightSearch?: boolean;
+    /**
+     * Sorting for the whole grid. Default true; `false` turns every header into
+     * a plain label. A column can still opt out on its own with
+     * `sortable: false` on its definition — the React prop of the same name.
+     */
+    sortable?: boolean;
+    /**
+     * Column widths on startup. `'none'` (default) keeps the declared widths.
+     *
+     * `'fitGrid'` divides the grid's width among the columns and RE-RUNS on every
+     * grid resize, taking the current widths as its proportions — so a column the
+     * user dragged wider stays proportionally wider.
+     *
+     * `'fitCells'` measures what the first rows actually rendered and runs ONCE:
+     * before the first paint there is nothing to measure. It can overflow the
+     * grid; that is the point of asking for content-width columns.
+     */
+    autoSizeStrategy?: 'none' | 'fitGrid' | 'fitCells';
+    /**
+     * @deprecated Retired 2026-08-15 and inert in BOTH renderers; accepted so
+     * existing call sites keep working.
+     *
+     * It rendered a strip under the grid whose only content was the row count.
+     * The per-column totals it once carried moved into the footer ROW, where
+     * each number sits under its own column — leaving a whole bar to say one
+     * number, printed a second time whenever the Enterprise status bar was on.
+     *
+     * The count lives in the **status bar** (Enterprise: total, filtered,
+     * selected) or in the **pager**, which shows the total when pagination is on.
+     *
+     * Unlike React, this renderer says so once in the console when you set it —
+     * a vanilla caller has no editor surfacing the `@deprecated` tag.
+     */
+    showRowCount?: boolean;
+    /** Quick-search + CSV export bar above the grid. */
+    toolbar?: boolean;
+    /** "Columns" button in the toolbar opening the visibility chooser. */
+    toolbarColumnChooser?: boolean;
+    /**
+     * Extra toolbar buttons, appended after the grid's own — the React
+     * `toolbarItemsAfter` prop, DOM-flavoured. Ignored without `toolbar`.
+     */
+    toolbarItemsAfter?: HTMLElement[];
+    /** Extra toolbar buttons, BEFORE the grid's own — React's `toolbarItemsBefore`. */
+    toolbarItemsBefore?: HTMLElement[];
+    /**
+     * Excel entries (all rows / selected rows) on the toolbar's export menu.
+     * Enterprise: shown only under `enterpriseEdition`, hidden rather than
+     * shown-and-failing — the controller would throw, and a menu entry whose
+     * only outcome is an error is worse than no entry (the React rule).
+     */
+    toolbarExcel?: boolean;
+    /** PDF entry on the export menu — Enterprise, same gate as `toolbarExcel`. */
+    toolbarPdf?: boolean;
+    /** Right-click menu with Copy / Copy with headers. Default true. */
+    cellMenu?: boolean;
+    /**
+     * App-defined right-click menu for data rows — the React `rowMenu` prop,
+     * DOM-flavoured. A function receives the row that was clicked so the items
+     * can depend on it. The grid's own entries (Copy…) append BELOW after a
+     * separator, so an app's menu keeps the order it wrote.
+     */
+    rowMenu?: GridMenuItem<RowMenuContext<TRow>>[] | ((context: RowMenuContext<TRow>) => GridMenuItem<RowMenuContext<TRow>>[]);
+    /**
+     * Right-click menu on column headers — the React `headerMenu` prop,
+     * DOM-flavoured. `true`/omitted shows the default items (sort, group,
+     * pin, hide, best fit…); `false` turns it off; a function receives the
+     * context and the defaults and returns the finished list, so an app can
+     * reorder, drop or append without rebuilding what the grid provides.
+     */
+    headerMenu?: boolean | ((context: HeaderMenuContext, defaults: GridMenuItem<HeaderMenuContext>[]) => GridMenuItem<HeaderMenuContext>[]);
+    /**
+     * Drag rows to reorder them, and — with a shared `group` — between two
+     * grids. A grip appears at the start of each row on hover. Reordering the
+     * grid's own array only works on an UNSORTED view (the React caveat).
+     */
+    rowDrag?: RowDragConfig<TRow>;
+    /**
+     * Grids naming the same group keep their column layout and horizontal
+     * scroll in step — a scrolling body with a totals strip below it. Sort,
+     * filter, selection and vertical scroll deliberately do NOT travel.
+     * (Aligns with other VANILLA grids; the React registry is separate.)
+     */
+    alignedGrids?: string;
+    /**
+     * Render EVERY row while the browser prints, so the print engine paginates
+     * real content instead of one clipped screenful. `true` = only while the
+     * print dialog is open; an options object can pin it `always` (report
+     * pages) or move the `maxRows` refusal point.
+     */
+    printLayout?: boolean | PrintLayoutOptions;
+    /** Persist and restore the view (sort, filters, widths…). Core's service. */
+    stateStoring?: StateStoringConfig;
+    /** Hover tooltips. `false` disables, a number overrides the 400ms delay. */
+    tooltip?: boolean | {
+        delay?: number;
+    };
+    /** 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;
+    /** Replace a body cell's content. `undefined` = the default painter runs. */
+    renderCellContent?: (ctx: CellSlotContext<TRow>) => Node | string | undefined;
+    /**
+     * Panel body for a master-detail row. With the engine's `masterDetail`
+     * config present, supplying this turns the leading expander column on —
+     * the React `renderDetail` prop, DOM-typed.
+     */
+    renderDetail?: (row: TRow) => Node | string;
+    /**
+     * Body for an in-grid edit form row (`mode: 'form'`). `row` is undefined
+     * for a record that does not exist yet — the form still opens, because the
+     * alternative is pressing "New row" and seeing nothing happen.
+     */
+    renderEditForm?: (rowKey: RowKey, row: TRow | undefined) => Node | string;
+    /**
+     * The edition flag, set by the Enterprise wrapper — the React prop of the
+     * same name. It gates what the CONTROLLER agrees to do (styled exports,
+     * master-detail…); without it the `masterDetail` config is stripped, the
+     * way the React Community renderer strips it.
+     */
+    enterpriseEdition?: boolean;
+    /** Extra classes for a body cell (pending edit, range, fill preview…). */
+    getCellClassName?: (ctx: CellSlotContext<TRow>) => string | undefined;
+    onCellPointerDown?: (ctx: CellSlotContext<TRow>, event: MouseEvent) => void;
+    onCellPointerEnter?: (ctx: CellSlotContext<TRow>, event: MouseEvent) => void;
+    onCellDoubleClick?: (ctx: CellSlotContext<TRow>) => void;
+}
+interface GridApi<TRow = GridRowData> {
+    /** The engine, whole. The same object React hands to `onReady`. */
+    controller: DataGridController<TRow>;
+    /** The `.kanuni-datagrid-root` element this grid built. */
+    element: HTMLElement;
+    setData(rows: TRow[]): void;
+    setColumns(columns: VanillaColumnDef<TRow>[]): void;
+    destroy(): void;
+}
+declare function createGrid<TRow = GridRowData>(container: HTMLElement, config: CreateGridConfig<TRow>): GridApi<TRow>;
+
+/**
+ * Width that fits the header and every rendered cell of `columnId`.
+ * Returns null when nothing could be measured (no such column on screen, or no
+ * canvas — jsdom, SSR), so the caller can leave the width alone.
+ */
+declare function measureBestFitWidth(root: HTMLElement, columnId: string): number | null;
+
+export { CHECKBOX_COLUMN_WIDTH, type CellRenderContext, type CellSlotContext, type CreateGridConfig, DETAIL_COLUMN_WIDTH, 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 VanillaColumnDef, buildHeaderMenu, createGrid, measureBestFitWidth };