@1771technologies/lytenyte-pro/dist/+types.d.ts

Blazingly fast headless React data grid with 100s of features.

import type { ReactNode } from "react";
/**
 * The initial props that may be passed to the `useLyteNyte` hook. The hook
 *     returns the state representation of LyteNyte Grid.
 *
 *   @group Grid State
 */
export interface UseLyteNyteProps<T> {
    /**
     * The initial column definitions.
     */
    readonly columns?: Column<T>[];
    /**
     * The base column definition.
     */
    readonly columnBase?: ColumnBase<T>;
    /**
     * The default expansion state for column groups if not specified explicitly.
     */
    readonly columnGroupDefaultExpansion?: boolean;
    /**
     * The initial expansion state for column groups.
     */
    readonly columnGroupExpansions?: Record<string, boolean>;
    /**
     * A delimiter used to concatenate group paths into a single group id.
     */
    readonly columnGroupJoinDelimiter?: string;
    /**
     * Indicates whether the grid should size columns to fit the available width.
     */
    readonly columnSizeToFit?: boolean;
    /**
     * The height in pixels that the header should occupy.
     */
    readonly headerHeight?: number;
    /**
     * The height in pixels for the header groups.
     */
    readonly headerGroupHeight?: number;
    /**
     * A unique identifier for the grid instance.
     */
    readonly gridId: string;
    /**
     * The data source used by LyteNyte Grid to manage and provide row data.
     */
    readonly rowDataSource?: RowDataSource<T>;
    /**
     * Initial height guess for auto-height rows, used before actual measurement.
     */
    readonly rowAutoHeightGuess?: number;
    /**
     * Row height strategy used by LyteNyte Grid for rendering rows.
     */
    readonly rowHeight?: RowHeight;
    /**
     * The number of columns LyteNyte Grid should scan when computing layout.
     */
    readonly colScanDistance?: number;
    /**
     * The number of rows LyteNyte Grid should scan when computing layout.
     */
    readonly rowScanDistance?: number;
    /**
     * The number of rows above the first visible row to render.
     */
    readonly rowOverscanTop?: number;
    /**
     * The number of rows below the last visible row to render.
     */
    readonly rowOverscanBottom?: number;
    /**
     * The number of columns before the first visible column to render.
     */
    readonly colOverscanStart?: number;
    /**
     * The number of columns after the last visible column to render.
     */
    readonly colOverscanEnd?: number;
    /**
     * The function predicate used to determine if a row should be rendered as full width.
     */
    readonly rowFullWidthPredicate?: RowFullWidthPredicate<T> | null;
    /**
     * The renderer used to render the content of a full width row.
     */
    readonly rowFullWidthRenderer?: RowFullWidthRendererFn<T>;
    /**
     * The map of named cell renderers that can be referenced by name in the grid.
     */
    readonly cellRenderers?: Record<string, CellRendererFn<T>>;
    /**
     * Whether to use right-to-left rendering. If false, left-to-right is assumed.
     */
    readonly rtl?: boolean;
    /**
     * The initial sort model to apply to the grid.
     */
    readonly sortModel?: SortModelItem<T>[];
    /**
     * The initial filter model to apply to the grid.
     */
    readonly filterModel?: Record<string, FilterModelItem<T>>;
    /**
     * The initial aggregation model to apply to LyteNyte Grid.
     */
    readonly aggModel?: {
        [columnId: string]: {
            fn: AggModelFn<T>;
        };
    };
    /**
     * Template for generating row group columns dynamically.
     */
    readonly rowGroupColumn?: RowGroupColumn<T>;
    /**
     * The initial row group model configuration to apply.
     */
    readonly rowGroupModel?: RowGroupModelItem<T>[];
    /**
     * The row group display mode to use in the grid.
     */
    readonly rowGroupDisplayMode?: RowGroupDisplayMode;
    /**
     * Default expansion depth for row groups. Can be a boolean or a depth number.
     */
    readonly rowGroupDefaultExpansion?: boolean | number;
    /**
     * Initial expansion state of specific row groups by row id.
     */
    readonly rowGroupExpansions?: {
        [rowId: string]: boolean | undefined;
    };
    /**
     * The height in px of the floating row.
     */
    readonly floatingRowHeight?: number;
    /**
     * A boolean indicating if the floating row should be enabled.
     */
    readonly floatingRowEnabled?: boolean;
    /**
     * The floating cell renderers that may be referenced by name.
     */
    readonly floatingCellRenderers?: Record<string, HeaderFloatingCellRendererFn<T>>;
    /**
     * The header cell renderers that may be referenced by name.
     */
    readonly headerCellRenderers?: Record<string, HeaderCellRendererFn<T>>;
    /**
     * The edit renderers that may be referenced by name.
     */
    readonly editRenderers?: Record<string, EditRendererFn<T>>;
    /**
     * A function for validating grid updates at a row level.
     */
    readonly editRowValidatorFn?: EditRowValidatorFn<T>;
    /**
     * The mouse interaction that should begin cell editing.
     */
    readonly editClickActivator?: EditClickActivator;
    /**
     * The initial cell edit mode.
     */
    readonly editCellMode?: EditCellMode;
    /**
     * The column marker definition.
     */
    readonly columnMarker?: ColumnMarker<T>;
    /**
     * A boolean indicating if the column marker should be visible.
     */
    readonly columnMarkerEnabled?: boolean;
    /**
     * A boolean indicating if double click to autosize a column should be enabled.
     */
    readonly columnDoubleClickToAutosize?: boolean;
    /**
     * A function used to render the content for a row detail area.
     */
    readonly rowDetailRenderer?: RowDetailRendererFn<T>;
    /**
     * The height of the row detail area.
     */
    readonly rowDetailHeight?: RowDetailHeight;
    /**
     * The initial row detail expansion state.
     */
    readonly rowDetailExpansions?: Set<string>;
    /**
     * The initial guess of the height of a row detail area before the actual height is observed.
     */
    readonly rowDetailAutoHeightGuess?: number;
    /**
     * The initial selected row ids.
     */
    readonly rowSelectedIds?: Set<string>;
    /**
     * The row selection mode to use.
     */
    readonly rowSelectionMode?: RowSelectionMode;
    /**
     * The mouse interaction that should begin row selection.
     */
    readonly rowSelectionActivator?: RowSelectionActivator;
    /**
     * A boolean indicating if the row selection should select children as well.
     */
    readonly rowSelectChildren?: boolean;
    /**
     * A boolean indicating if the columns in the grid should be virtualized.
     */
    readonly virtualizeCols?: boolean;
    /**
     * A boolean indicating if the rows in the grid should be virtualized.
     */
    readonly virtualizeRows?: boolean;
    /**
     * The quick search filter value.
     */
    readonly quickSearch?: string | null;
    /**
     * The case sensitivity of the quick search filter.
     */
    readonly quickSearchSensitivity?: FilterQuickSearchSensitivity;
    /**
     * A boolean indicating if the column pivot mode should be on.
     */
    readonly columnPivotMode?: boolean;
    /**
     * The initial column pivot model to apply to LyteNyte Grid.
     */
    readonly columnPivotModel?: ColumnPivotModel<T>;
    /**
     * The dialog frames available in the grid.
     */
    readonly dialogFrames?: Record<string, DialogFrame<T>>;
    /**
     * The popover frames available in the grid.
     */
    readonly popoverFrames?: Record<string, PopoverFrame<T>>;
    /**
     * The in (set) filter model to apply to LyteNyte Grid.
     */
    readonly filterInModel?: Record<string, FilterIn>;
    /**
     * The initial cell selections in the grid.
     */
    readonly cellSelections?: DataRect[];
    /**
     * The cell selection mode to use.
     */
    readonly cellSelectionMode?: CellSelectionMode;
}
/**
 * The declarative state object of LyteNyte Grid. This state encapsulates all mutable and observable
 *   grid properties that affect layout, data, selection, and rendering. Updating any of these atoms will trigger
 *   corresponding changes in the grid UI. These state values can also be used to create and synchronize external
 *   components such as toolbars, panels, or widgets.
 *
 *   @group Grid State
 */
export interface GridState<T> {
    /**
     * All column definitions registered in the grid, including both visible and hidden columns.
     */
    readonly columns: GridAtom<Column<T>[]>;
    /**
     * Computed metadata for each column in the grid, including rendering metrics and positional
     *   information. Useful for custom layout or advanced plugin behavior.
     */
    readonly columnMeta: GridAtomReadonly<ColumnMeta<T>>;
    /**
     * A base column configuration object used as a fallback for individual columns.
     */
    readonly columnBase: GridAtom<ColumnBase<T>>;
    /**
     * The default expansion state for column groups when no specific state has been set.
     */
    readonly columnGroupDefaultExpansion: GridAtom<boolean>;
    /**
     * A map of column group ids to their expansion state. This controls whether individual groups
     *   are expanded or collapsed. Direct mutation bypasses grid events.
     */
    readonly columnGroupExpansions: GridAtom<Record<string, boolean>>;
    /**
     * The delimiter string used to construct hierarchical column group ids by joining nested keys.
     */
    readonly columnGroupJoinDelimiter: GridAtom<string>;
    /**
     * Computed metadata about the column group structure in the grid. This is used internally for
     *   layout and interaction logic involving grouped headers.
     */
    readonly columnGroupMeta: GridAtomReadonly<ColumnGroupMeta>;
    /**
     * Controls whether columns should automatically resize to fit the available width of the grid viewport.
     */
    readonly columnSizeToFit: GridAtom<boolean>;
    /**
     * A unique identifier associated with the grid instance.
     */
    readonly gridId: GridAtom<string>;
    /**
     * The horizontal (x-axis) pixel positions of each visible column in the grid. Used to determine
     *   where each column should render on screen.
     */
    readonly xPositions: GridAtomReadonly<Uint32Array>;
    /**
     * The vertical (y-axis) pixel positions of rows in the grid. Determines how each row is positioned
     *   within the scrollable area.
     */
    readonly yPositions: GridAtomReadonly<Uint32Array>;
    /**
     * The total combined width (in pixels) of all visible columns in the grid.
     */
    readonly widthTotal: GridAtomReadonly<number>;
    /**
     * The total height (in pixels) of all rows currently present in the grid.
     */
    readonly heightTotal: GridAtomReadonly<number>;
    /**
     * The HTML element representing the viewport of the grid. May be null before initialization.
     */
    readonly viewport: GridAtom<HTMLElement | null>;
    /**
     * The internal width of the viewport, usually equal to the clientWidth of the viewport element.
     */
    readonly viewportWidthInner: GridAtom<number>;
    /**
     * The outer width of the viewport, corresponding to its offsetWidth.
     */
    readonly viewportWidthOuter: GridAtom<number>;
    /**
     * The internal height of the viewport, typically matching the clientHeight of the viewport element.
     */
    readonly viewportHeightInner: GridAtom<number>;
    /**
     * The outer height of the viewport, corresponding to its offsetHeight.
     */
    readonly viewportHeightOuter: GridAtom<number>;
    /**
     * The vertical height (in pixels) allocated for the header row of the grid.
     */
    readonly headerHeight: GridAtom<number>;
    /**
     * The vertical height (in pixels) allocated for grouped header rows, if present.
     */
    readonly headerGroupHeight: GridAtom<number>;
    /**
     * The backing store for row data within the grid. This is managed internally and should not be
     *   mutated directly unless implementing a custom data source.
     */
    readonly rowDataStore: RowDataStore<T>;
    /**
     * The configured row data source for the grid. This defines how rows are fetched, paged, or
     *   streamed into the grid.
     */
    readonly rowDataSource: GridAtom<RowDataSource<T>>;
    /**
     * A fallback row height (in pixels) used before actual row heights are measured.
     *   Especially useful when rendering rows with dynamic or unknown content heights.
     */
    readonly rowAutoHeightGuess: GridAtom<number>;
    /**
     * The height configuration for rows in the grid. This may be a fixed number, a function, or a
     *   configuration object.
     */
    readonly rowHeight: GridAtom<RowHeight>;
    /**
     * Controls how many rows back the grid should look when computing layout for row-spanning cells.
     *   Higher values allow larger spans but impact performance.
     */
    readonly rowScanDistance: GridAtom<number>;
    /**
     * Controls how many columns back the grid should look when computing layout for column-spanning
     *   cells. Larger values allow broader spans but can reduce rendering efficiency.
     */
    readonly colScanDistance: GridAtom<number>;
    /**
     * Specifies the number of additional rows to render above the visible viewport. Increasing this
     *   value can reduce visible loading artifacts when scrolling upward, at the cost of performance.
     */
    readonly rowOverscanTop: GridAtom<number>;
    /**
     * Specifies the number of additional rows to render below the visible viewport. Increasing this
     *   value can reduce flickering when scrolling downward, but may negatively impact rendering performance.
     */
    readonly rowOverscanBottom: GridAtom<number>;
    /**
     * Specifies the number of extra columns to render before the first visible column. Helps with
     *   smoother horizontal scrolling to the left.
     */
    readonly colOverscanStart: GridAtom<number>;
    /**
     * Specifies the number of extra columns to render after the last visible column. Helps with
     *   smoother horizontal scrolling to the right.
     */
    readonly colOverscanEnd: GridAtom<number>;
    /**
     * A predicate function used to determine whether a given row should be rendered as a
     *   full-width row. Full-width rows span across all columns and bypass standard cell layout.
     */
    readonly rowFullWidthPredicate: GridAtom<{
        fn: RowFullWidthPredicate<T> | null;
    }>;
    /**
     * The component function that renders full-width rows in the grid. This renderer is called
     *   whenever a row matches the full-width predicate.
     */
    readonly rowFullWidthRenderer: GridAtom<{
        fn: RowFullWidthRendererFn<T>;
    }>;
    /**
     * A registry of named cell renderer functions. These can be referenced by name in
     *   individual column definitions to customize cell rendering behavior.
     */
    readonly cellRenderers: GridAtom<Record<string, CellRendererFn<T>>>;
    /**
     * Boolean flag that determines whether the grid renders in right-to-left (RTL) mode.
     */
    readonly rtl: GridAtom<boolean>;
    /**
     * An array representing the current sort state of the grid. Each entry defines
     *   a column and its sort direction. An empty array means no active sorting.
     */
    readonly sortModel: GridAtom<SortModelItem<T>[]>;
    /**
     * An array of filters currently applied to the grid. If empty, no filters are active.
     */
    readonly filterModel: GridAtom<Record<string, FilterModelItem<T>>>;
    /**
     * The aggregation model configuration for the grid. Each entry maps a column id to its associated
     *   aggregation function. Aggregation results are typically displayed in group or summary rows.
     */
    readonly aggModel: GridAtom<{
        [columnId: string]: {
            fn: AggModelFn<T>;
        };
    }>;
    /**
     * An array representing the fields or columns being used to group rows. An empty array
     *   disables row grouping.
     */
    readonly rowGroupModel: GridAtom<RowGroupModelItem<T>[]>;
    /**
     * Defines the template or configuration for the automatically generated row group column.
     *   This controls its appearance and behavior.
     */
    readonly rowGroupColumn: GridAtom<RowGroupColumn<T>>;
    /**
     * Specifies how automatically generated row group columns should be displayed in the grid.
     *   This controls their visibility and layout.
     */
    readonly rowGroupDisplayMode: GridAtom<RowGroupDisplayMode>;
    /**
     * Controls the default expansion state of all row groups. If a number is provided, groups up to that
     *   depth will be expanded by default.
     */
    readonly rowGroupDefaultExpansion: GridAtom<boolean | number>;
    /**
     * An object mapping row group ids to their expansion state. Updating this directly will not trigger
     *   grid events and should be done with care.
     */
    readonly rowGroupExpansions: GridAtom<{
        [rowId: string]: boolean | undefined;
    }>;
    /**
     * Controls whether the floating row is enabled in the grid. When enabled, the floating row
     *   appears fixed below the column headers.
     */
    readonly floatingRowEnabled: GridAtom<boolean>;
    /**
     * Specifies the height, in pixels, of the floating row when enabled.
     */
    readonly floatingRowHeight: GridAtom<number>;
    /**
     * A map of named floating row cell renderers. These renderers can be assigned by name
     *   in the floating row column configurations.
     */
    readonly floatingCellRenderers: GridAtom<Record<string, HeaderFloatingCellRendererFn<T>>>;
    /**
     * A map of named header cell renderers. These can be referenced in column definitions to
     *   customize how column headers are displayed.
     */
    readonly headerCellRenderers: GridAtom<Record<string, HeaderCellRendererFn<T>>>;
    /**
     * A map of named edit renderers. These renderers are used to customize the editing
     *   experience for cells in editable columns.
     */
    readonly editRenderers: GridAtom<Record<string, EditRendererFn<T>>>;
    /**
     * A function used to validate updates to a row during an edit. This validator can prevent
     *   invalid edits before they are applied to the grid state.
     */
    readonly editRowValidatorFn: GridAtom<{
        fn: EditRowValidatorFn<T>;
    }>;
    /**
     * Specifies the mouse interaction pattern (e.g., single click, double click) required to
     *   activate a cell edit.
     */
    readonly editClickActivator: GridAtom<EditClickActivator>;
    /**
     * Determines the cell edit mode for the grid. Modes include read-only and editable states.
     */
    readonly editCellMode: GridAtom<EditCellMode>;
    /**
     * Represents the current active edit position in the grid. If no edit is active, this is null.
     */
    readonly editActivePosition: GridAtomReadonly<EditActivePosition<T> | null>;
    /**
     * Configuration object for the marker column, which is often used to indicate row-specific states
     *   like expansion or editing.
     */
    readonly columnMarker: GridAtom<ColumnMarker<T>>;
    /**
     * Enables or disables the marker column in the grid.
     */
    readonly columnMarkerEnabled: GridAtom<boolean>;
    /**
     * If true, double-clicking on a column's resize handle will trigger an autosize
     *   for that column based on its content.
     */
    readonly columnDoubleClickToAutosize: GridAtom<boolean>;
    /**
     * The function that renders additional row detail content when a row is expanded.
     */
    readonly rowDetailRenderer: GridAtom<{
        fn: RowDetailRendererFn<T>;
    }>;
    /**
     * Specifies the height of the row detail section when expanded.
     */
    readonly rowDetailHeight: GridAtom<RowDetailHeight>;
    /**
     * The default estimated height for row detail sections before their actual height has
     *   been measured.
     */
    readonly rowDetailAutoHeightGuess: GridAtom<number>;
    /**
     * Represents the set of row ids with expanded row detail sections.
     */
    readonly rowDetailExpansions: GridAtom<Set<string>>;
    /**
     * A set of selected row ids in the grid.
     */
    readonly rowSelectedIds: GridAtom<Set<string>>;
    /**
     * Specifies the selection mode of the grid, such as single or multiple row selection.
     */
    readonly rowSelectionMode: GridAtom<RowSelectionMode>;
    /**
     * Identifies the anchor row used for shift-based range selections. Defines the selection
     *   starting point.
     */
    readonly rowSelectionPivot: GridAtom<string | null>;
    /**
     * Specifies the interaction pattern or input trigger that initiates row selection,
     *   such as clicks or keyboard inputs.
     */
    readonly rowSelectionActivator: GridAtom<RowSelectionActivator>;
    /**
     * If true, selecting a parent row will automatically select its child rows. Useful for hierarchical
     *   or grouped data selection.
     */
    readonly rowSelectChildren: GridAtom<boolean>;
    /**
     * The current view bounds of the grid, representing the row and column segments
     *   that should be rendered based on scroll position and viewport.
     */
    readonly viewBounds: GridAtomReadonly<ViewBounds>;
    /**
     * Controls whether columns should be virtualized. Improves performance for large column
     *   sets by only rendering visible columns. Enabled by default.
     */
    readonly virtualizeCols: GridAtom<boolean>;
    /**
     * Controls whether rows should be virtualized. Improves performance for large datasets
     *   by only rendering visible rows. Enabled by default.
     */
    readonly virtualizeRows: GridAtom<boolean>;
    /**
     * Represents the current quick search input applied to the grid. When set, rows will be filtered
     *   using this value. If null or an empty string, no quick search filtering will be applied.
     */
    readonly quickSearch: GridAtom<string | null>;
    /**
     * Specifies whether the quick search is case-sensitive or insensitive. Controls how text is matched
     *   during quick search filtering.
     */
    readonly quickSearchSensitivity: GridAtom<FilterQuickSearchSensitivity>;
    /**
     * The current column pivot model in use. This model defines how column pivoting is structured
     *   in the grid and which columns are used to generate pivot dimensions.
     */
    readonly columnPivotModel: GridAtom<ColumnPivotModel<T>>;
    /**
     * Controls whether column pivoting is enabled in the grid. When true, pivot columns will be
     *   generated based on the active pivot model.
     */
    readonly columnPivotMode: GridAtom<boolean>;
    /**
     * The generated columns from the current pivot model. These columns represent data values
     *   derived from pivot operations. They may be updated, but changes may be overridden if the pivot model changes.
     */
    readonly columnPivotColumns: GridAtom<Column<T>[]>;
    /**
     * Tracks the expansion state of row groups generated by the current pivot model. Each key is
     *   a row group id, and the value determines its expansion state.
     */
    readonly columnPivotRowGroupExpansions: GridAtom<{
        [rowId: string]: boolean | undefined;
    }>;
    /**
     * Tracks the expansion state of column groups generated by pivot operations. Each key is
     *   a group id, and the value indicates whether it's expanded or collapsed.
     */
    readonly columnPivotColumnGroupExpansions: GridAtom<Record<string, boolean | undefined>>;
    /**
     * The in (set) filter model to apply to LyteNyte Grid.
     */
    readonly filterInModel: GridAtom<Record<string, FilterIn>>;
    /**
     * A dictionary of dialog frames currently managed by the grid. These frames can be programmatically
     *   opened or closed using the `dialogFrameOpen` and `dialogFrameClose` API methods.
     */
    readonly dialogFrames: GridAtom<Record<string, DialogFrame<T>>>;
    /**
     * A dictionary of popover frames currently managed by the grid. These can be dynamically shown
     *   or hidden using the `popoverFrameOpen` and `popoverFrameClose` API methods.
     */
    readonly popoverFrames: GridAtom<Record<string, PopoverFrame<T>>>;
    /**
     * An array of cell selections currently active in the grid. Each selection is a rectangular
     *   range of selected cells, useful for bulk editing, clipboard actions, or analytics.
     */
    readonly cellSelections: GridAtom<DataRect[]>;
    /**
     * Controls the grid's current cell selection mode. This determines how users may interact with
     *   and select individual or grouped cells.
     */
    readonly cellSelectionMode: GridAtom<CellSelectionMode>;
}
/**
 * Defines the viewport boundaries for rendering rows and columns in LyteNyte Grid.
 *   These bounds are calculated based on the scroll position and the visible area of the grid.
 *
 *   @group Grid View
 */
export interface ViewBounds {
    /**
     * Index of the first row pinned to the top of the grid. This will always be 0.
     */
    readonly rowTopStart: number;
    /**
     * Index just past the last top-pinned row. Equal to `1 + number of pinned rows`.
     */
    readonly rowTopEnd: number;
    /**
     * Start index of the scrollable rows that should be rendered in the viewport.
     */
    readonly rowCenterStart: number;
    /**
     * End index of the scrollable rows that should be rendered.
     */
    readonly rowCenterEnd: number;
    /**
     * Index one past the last possible scrollable row in the dataset.
     */
    readonly rowCenterLast: number;
    /**
     * Index of the first row pinned to the bottom of the grid.
     */
    readonly rowBotStart: number;
    /**
     * Index just past the last bottom-pinned row.
     */
    readonly rowBotEnd: number;
    /**
     * Index of the first column pinned to the start (left side for LTR).
     */
    readonly colStartStart: number;
    /**
     * Index one past the last column pinned to the start.
     */
    readonly colStartEnd: number;
    /**
     * Start index of scrollable columns to render.
     */
    readonly colCenterStart: number;
    /**
     * End index of scrollable columns to render.
     */
    readonly colCenterEnd: number;
    /**
     * Index one past the last possible scrollable column in the grid.
     */
    readonly colCenterLast: number;
    /**
     * Index of the first column pinned to the end (right side for LTR).
     */
    readonly colEndStart: number;
    /**
     * Index one past the last column pinned to the end.
     */
    readonly colEndEnd: number;
}
/**
 * The grid object encapsulates the full LyteNyte Grid instance, including its state, view, and imperative API.
 *   It is returned by the `useLyteNyte` hook and serves as the primary interface for interacting with the grid programmatically.
 *
 *   @group Grid State
 */
export interface Grid<T> {
    /**
     * The declarative state of LyteNyte Grid. This contains all core
     *       and optional features represented as atoms.
     */
    readonly state: GridState<T>;
    /**
     * The current layout view of the grid, reflecting visible headers and rows
     *       based on virtualization and scroll position.
     */
    readonly view: GridAtomReadonly<GridView<T>>;
    /**
     * The imperative API of LyteNyte Grid for triggering actions such
     *       as column resizing, row expansion, and selection.
     */
    readonly api: GridApi<T>;
}
/**
 * Represents the current visual layout of the grid including headers and rows.
 *   This structure is used by LyteNyte Grid headless components
 *   or for building custom visualizations.
 *
 *   @group Grid View
 */
export interface GridView<T> {
    /**
     * Header layout structure currently being rendered in the viewport.
     */
    readonly header: HeaderLayout<T>;
    /**
     * Row layout sections (top, center, bottom) rendered in the viewport.
     */
    readonly rows: RowSectionLayouts<T>;
}
/**
 * Describes a standard header cell layout in the grid, used to position and render individual column headers.
 *
 *   @group Grid View
 */
export interface HeaderCellLayout<T> {
    /**
     * The starting row index in the header hierarchy for this cell.
     */
    readonly rowStart: number;
    /**
     * The exclusive ending row index in the header hierarchy for this cell.
     */
    readonly rowEnd: number;
    /**
     * The number of header rows this header spans vertically.
     */
    readonly rowSpan: number;
    /**
     * The starting column index in the visible layout this header covers.
     */
    readonly colStart: number;
    /**
     * The exclusive ending column index in the visible layout this header covers.
     */
    readonly colEnd: number;
    /**
     * The number of columns this header spans horizontally.
     */
    readonly colSpan: number;
    /**
     * Indicates which pin section this column belongs to: 'start', 'end', or 'center'.
     */
    readonly colPin: ColumnPin;
    /**
     * True if this column is the first column in the set of columns pinned to the end.
     */
    readonly colFirstEndPin?: boolean;
    /**
     * True if this column is the last column in the set of columns pinned to the start.
     */
    readonly colLastStartPin?: boolean;
    /**
     * A unique identifier that can be used for rendering keys or tracking elements.
     */
    readonly id: string;
    /**
     * A discriminator indicating this is a standard header cell.
     */
    readonly kind: "cell";
    /**
     * A reference to a column definition in LyteNyte Grid.
     */
    readonly column: Column<T>;
}
/**
 * Describes a floating header cell layout, which remains fixed during scroll operations.
 *
 *   @group Grid View
 */
export interface HeaderCellFloating<T> {
    /**
     * The starting row index in the header hierarchy for this cell.
     */
    readonly rowStart: number;
    /**
     * The exclusive ending row index in the header hierarchy for this cell.
     */
    readonly rowEnd: number;
    /**
     * The number of header rows this header spans vertically.
     */
    readonly rowSpan: number;
    /**
     * The starting column index in the visible layout this header covers.
     */
    readonly colStart: number;
    /**
     * The exclusive ending column index in the visible layout this header covers.
     */
    readonly colEnd: number;
    /**
     * The number of columns this header spans horizontally.
     */
    readonly colSpan: number;
    /**
     * Indicates which pin section this column belongs to: 'start', 'end', or 'center'.
     */
    readonly colPin: ColumnPin;
    /**
     * True if this column is the first column in the set of columns pinned to the end.
     */
    readonly colFirstEndPin?: boolean;
    /**
     * True if this column is the last column in the set of columns pinned to the start.
     */
    readonly colLastStartPin?: boolean;
    /**
     * A unique identifier that can be used for rendering keys or tracking elements.
     */
    readonly id: string;
    /**
     * A discriminator indicating this is a floating (sticky) header cell.
     */
    readonly kind: "floating";
    /**
     * A reference to a column definition in LyteNyte Grid.
     */
    readonly column: Column<T>;
}
/**
 * Describes a group of columns within the header. Used by LyteNyte
 *   Grid to render grouped column headers with optional collapsibility and structural metadata.
 *
 *   @group Grid View
 */
export interface HeaderGroupCellLayout {
    /**
     * The starting row index in the header hierarchy for this cell.
     */
    readonly rowStart: number;
    /**
     * The exclusive ending row index in the header hierarchy for this cell.
     */
    readonly rowEnd: number;
    /**
     * The number of header rows this header spans vertically.
     */
    readonly rowSpan: number;
    /**
     * The starting column index in the visible layout this header covers.
     */
    readonly colStart: number;
    /**
     * The exclusive ending column index in the visible layout this header covers.
     */
    readonly colEnd: number;
    /**
     * The number of columns this header spans horizontally.
     */
    readonly colSpan: number;
    /**
     * Indicates which pin section this column belongs to: 'start', 'end', or 'center'.
     */
    readonly colPin: ColumnPin;
    /**
     * True if this column is the first column in the set of columns pinned to the end.
     */
    readonly colFirstEndPin?: boolean;
    /**
     * True if this column is the last column in the set of columns pinned to the start.
     */
    readonly colLastStartPin?: boolean;
    /**
     * Discriminant indicating this layout item is a header group.
     */
    readonly kind: "group";
    /**
     * Indicates whether this column group can be collapsed in the UI.
     */
    readonly isCollapsible: boolean;
    /**
     * The id for the header group. Note this is not unique across all header groups. In particular
     *       split header groups with the same path will share the same id. Prefer `idOccurrence` for unique keys.
     */
    readonly id: string;
    /**
     * Unique identifier that includes header split occurrence information.
     */
    readonly idOccurrence: string;
    /**
     * Hierarchy path representing this column group's position and ancestry.
     */
    readonly groupPath: string[];
    /**
     * Column ids that are included within this header group.
     */
    readonly columnIds: string[];
    /**
     * Start index of the group in the column layout.
     */
    readonly start: number;
    /**
     * Exclusive end index of the group in the column layout.
     */
    readonly end: number;
    /**
     * Indicates that this is a temporary placeholder group for drag-and-drop movement.
     *       Should be ignored for typical rendering.
     */
    readonly isHiddenMove?: boolean;
}
/**
 * Defines the overall structure of header rows in the grid.
 *   This layout is recalculated based on viewport changes and virtualized rendering.
 *
 *   @group Grid View
 */
export interface HeaderLayout<T> {
    /**
     * Total number of header rows rendered, including groups and nested headers.
     */
    readonly maxRow: number;
    /**
     * Total number of columns involved in the header layout.
     */
    readonly maxCol: number;
    /**
     * Two-dimensional array of header layout cells organized by row hierarchy.
     */
    readonly layout: HeaderLayoutCell<T>[][];
}
/**
 * Represents a union of all possible header layout cell types:
 *   normal header, floating header, or header group.
 *
 *   @group Grid View
 */
export type HeaderLayoutCell<T> = HeaderCellLayout<T> | HeaderCellFloating<T> | HeaderGroupCellLayout;
/**
 * Represents the layout metadata for a single cell within a row, including span and contextual info.
 *
 *   @group Grid View
 */
export interface RowCellLayout<T> {
    /**
     * Discriminator to identify a standard cell layout object.
     */
    readonly kind: "cell";
    /**
     * Number of columns this cell spans across.
     */
    readonly colSpan: number;
    /**
     * Number of rows this cell spans across.
     */
    readonly rowSpan: number;
    /**
     * Indicates if this cell is row spanned over and will not be rendered
     */
    readonly isDeadRow: boolean;
    /**
     * Indicates if this cell is column spanned over and will not be rendered
     */
    readonly isDeadCol: boolean;
    /**
     * A unique identifier that can be used for rendering keys or tracking elements.
     */
    readonly id: string;
    /**
     * The zero-based index of the row.
     */
    readonly rowIndex: number;
    /**
     * The zero-based index of the column.
     */
    readonly colIndex: number;
    /**
     * A reactive atom for the row node, allowing updates without subscriptions.
     */
    readonly row: GridAtomReadonlyUnwatchable<RowNode<T> | null>;
    /**
     * A reference to a column definition in LyteNyte Grid.
     */
    readonly column: Column<T>;
    /**
     * The pinning state of a column, used to fix it to the left or right side.
     */
    readonly colPin: ColumnPin;
    /**
     * The pinning state of a row, used to fix it to the top or bottom of the grid.
     */
    readonly rowPin: RowPin;
    /**
     * True if this column is the first column in the set of columns pinned to the end.
     */
    readonly colFirstEndPin?: boolean;
    /**
     * True if this column is the last column in the set of columns pinned to the start.
     */
    readonly colLastStartPin?: boolean;
    /**
     * True if this row is the last row pinned to the top of the grid.
     */
    readonly rowLastPinTop?: boolean;
    /**
     * True if this row is the first row pinned to the bottom of the grid.
     */
    readonly rowFirstPinBottom?: boolean;
    /**
     * True if this row contains the currently focused cell and should be included in layout calculation.
     */
    readonly rowIsFocusRow?: boolean;
}
/**
 * Describes the layout of a full-width row which spans all columns.
 *   These are typically used for summary or group rows.
 *
 *   @group Grid View
 */
export interface RowFullWidthRowLayout<T> {
    /**
     * Discriminator for identifying full-width row layout objects.
     */
    readonly kind: "full-width";
    /**
     * A unique identifier that can be used for rendering keys or tracking elements.
     */
    readonly id: string;
    /**
     * The zero-based index of the row.
     */
    readonly rowIndex: number;
    /**
     * A reactive atom for the row node, allowing updates without subscriptions.
     */
    readonly row: GridAtomReadonlyUnwatchable<RowNode<T> | null>;
    /**
     * The pinning state of a row, used to fix it to the top or bottom of the grid.
     */
    readonly rowPin: RowPin;
    /**
     * True if this row is the last row pinned to the top of the grid.
     */
    readonly rowLastPinTop?: boolean;
    /**
     * True if this row is the first row pinned to the bottom of the grid.
     */
    readonly rowFirstPinBottom?: boolean;
    /**
     * True if this row contains the currently focused cell and should be included in layout calculation.
     */
    readonly rowIsFocusRow?: boolean;
}
/**
 * A row layout is either a standard row or a full-width row, depending on its content and configuration.
 *
 *   @group Grid View
 */
export type RowLayout<T> = RowNormalRowLayout<T> | RowFullWidthRowLayout<T>;
/**
 * Describes the layout of a standard row in LyteNyte Grid,
 *   including cell arrangement and row-level metadata.
 *
 *   @group Grid View
 */
export interface RowNormalRowLayout<T> {
    /**
     * Discriminator identifying this layout as a normal row.
     */
    readonly kind: "row";
    /**
     * The zero-based index of the row.
     */
    readonly rowIndex: number;
    /**
     * A reactive atom for the row node, allowing updates without subscriptions.
     */
    readonly row: GridAtomReadonlyUnwatchable<RowNode<T> | null>;
    /**
     * The pinning state of a row, used to fix it to the top or bottom of the grid.
     */
    readonly rowPin: RowPin;
    /**
     * True if this row is the last row pinned to the top of the grid.
     */
    readonly rowLastPinTop?: boolean;
    /**
     * True if this row is the first row pinned to the bottom of the grid.
     */
    readonly rowFirstPinBottom?: boolean;
    /**
     * True if this row contains the currently focused cell and should be included in layout calculation.
     */
    readonly rowIsFocusRow?: boolean;
    /**
     * A unique identifier that can be used for rendering keys or tracking elements.
     */
    readonly id: string;
    /**
     * List of cell layout metadata for this row.
     */
    readonly cells: RowCellLayout<T>[];
}
/**
 * Organizes the rows into three separate sections: top (pinned), center (scrollable),
 *   and bottom (pinned). Used to optimize row virtualization and rendering.
 *
 *   @group Grid View
 */
export interface RowSectionLayouts<T> {
    /**
     * Layout information for pinned rows at the top of the grid.
     */
    readonly top: RowLayout<T>[];
    /**
     * Layout information for scrollable rows in the grid.
     */
    readonly center: RowLayout<T>[];
    /**
     * Layout information for pinned rows at the bottom of the grid.
     */
    readonly bottom: RowLayout<T>[];
    /**
     * Cumulative height of all top-pinned rows in pixels.
     */
    readonly rowTopTotalHeight: number;
    /**
     * Cumulative height of all scrollable center rows in pixels.
     */
    readonly rowCenterTotalHeight: number;
    /**
     * Cumulative height of all bottom-pinned rows in pixels.
     */
    readonly rowBottomTotalHeight: number;
    /**
     * Index of the currently focused row, if it exists. Focused rows may
     *       appear in the layout even if not otherwise visible.
     */
    readonly rowFocusedIndex: number | null;
    /**
     * Index of the first center (scrollable) row.
     */
    readonly rowFirstCenter: number;
}
/**
 * A function used by LyteNyte Grid to determine the ideal width for a column based
 * on a representative sample of cell content.
 *
 * This is called when autosize is triggered via the grid's API. Returning `null`
 * disables sizing behavior.
 *
 * @group Column
 */
export type AutosizeCellFn<T> = (
/**
 * The input parameters passed to the autosize function to determine the optimal
 * column width.
 */
params: AutosizeCellParams<T>) => number | null;
/**
 * Parameters passed to the {@link AutosizeCellFn} function.
 *
 * These provide context about the cell and grid configuration so that the function
 * can determine the optimal column width based on cell content.
 *
 * @group Column
 */
export interface AutosizeCellParams<T> {
    /**
     * A reference to a column definition in LyteNyte Grid.
     */
    readonly column: Column<T>;
    /**
     * A reference to the LyteNyte Grid instance.
     */
    readonly grid: Grid<T>;
    /**
     * The row node instance in LyteNyte Grid.
     */
    readonly row: RowNode<T>;
}
/**
 * A function used by LyteNyte Grid to calculate the ideal width for a column header
 * based on the header's rendered content.
 *
 * This is called as part of the grid's autosize process.
 *
 * @group Column
 */
export type AutosizeHeaderFn<T> = (
/**
 * The input parameters used to evaluate the ideal width for a column header.
 */
params: AutosizeHeaderParams<T>) => number | null;
/**
 * Parameters passed to the {@link AutosizeHeaderFn} function.
 *
 * These are used by LyteNyte Grid to calculate the ideal column width based on the
 * header content.
 *
 * @group Column
 */
export interface AutosizeHeaderParams<T> {
    /**
     * A reference to a column definition in LyteNyte Grid.
     */
    readonly column: Column<T>;
    /**
     * A reference to the LyteNyte Grid instance.
     */
    readonly grid: Grid<T>;
}
/**
 * Represents the default column configuration used by LyteNyte Grid.
 *
 * This serves as a base template that provides fallback values for various column properties.
 * Rather than merging, LyteNyte Grid looks up configuration properties on the column first,
 * then on the default.
 *
 * This allows you to set column-wide defaults that apply retroactively to all applicable columns
 * without rewriting each one.
 *
 * @group Column
 */
export interface ColumnBase<T> {
    /**
     * Controls the visibility of the column. When set to `true`, the column is hidden from the grid display.
     */
    readonly hide?: boolean;
    /**
     * Specifies the preferred width of the column. This value is ignored if flex sizing is used, or if it violates the column's min/max bounds.
     */
    readonly width?: number;
    /**
     * Defines the maximum width the column is allowed to occupy.
     */
    readonly widthMax?: number;
    /**
     * Defines the minimum width the column is allowed to occupy.
     */
    readonly widthMin?: number;
    /**
     * Specifies the flex ratio this column should take when distributing remaining space.
     *
     *   Similar to CSS `flex`, it controls how extra space is shared among flex-enabled columns.
     */
    readonly widthFlex?: number;
    /**
     * Function used to render the column's header. Must return a React node.
     */
    readonly headerRenderer?: HeaderCellRenderer<T>;
    /**
     * Function used to render a floating row cell. Only called when floating rows are enabled. Must return a React node.
     */
    readonly floatingCellRenderer?: HeaderFloatingCellRenderer<T>;
    /**
     * Defines how to render the cell content. Accepts a renderer function or a string referencing a registered renderer.
     */
    readonly cellRenderer?: string | CellRendererFn<T>;
    /**
     * Describes the capabilities and intended UI behavior of the column. These hints are used by external UI components.
     */
    readonly uiHints?: ColumnUIHints;
    /**
     * Controls whether cells in the column can be edited.
     *
     *   Editing is only possible when both the grid is in edit mode and this flag is set.
     */
    readonly editable?: Editable<T>;
    /**
     * Specifies a custom cell editor to use when the cell enters edit mode.
     */
    readonly editRenderer?: EditRenderer<T>;
    /**
     * Custom logic for applying an edit to the row's data. Required when editing fields that need special update logic.
     */
    readonly editSetter?: EditSetterFn<T>;
    /**
     * Function that computes the ideal width for the column based on sampled cell content.
     */
    readonly autosizeCellFn?: AutosizeCellFn<T>;
    /**
     * Function that computes the ideal width for the column header based on its content.
     */
    readonly autosizeHeaderFn?: AutosizeHeaderFn<T>;
    /**
     * When `true`, the column is excluded from the quick search filter.
     *
     * Useful for non-textual or metadata columns that should not be searchable by users.
     */
    readonly quickSearchIgnore?: boolean;
}
/**
 * Defines the structure of a marker column.
 *
 *   The marker column is a grid managed column used to support features like selection checkboxes or row drag handles.
 *
 *   @group Column
 */
export interface ColumnMarker<T> {
    /**
     * Defines how to render the cell content. Accepts a renderer function or a string referencing a registered renderer.
     */
    readonly cellRenderer?: string | CellRendererFn<T>;
    /**
     * Function used to render the column's header. Must return a React node.
     */
    readonly headerRenderer?: HeaderCellRenderer<T>;
    /**
     * Function used to render a floating row cell. Only called when floating rows are enabled. Must return a React node.
     */
    readonly floatingCellRenderer?: HeaderFloatingCellRenderer<T>;
    /**
     * Specifies the preferred width of the column. This value is ignored if flex sizing is used, or if it violates the column's min/max bounds.
     */
    readonly width?: number;
    /**
     * Describes the capabilities and intended UI behavior of the column. These hints are used by external UI components.
     */
    readonly uiHints?: ColumnUIHints;
}
/**
 * Represents runtime metadata for the current column configuration in LyteNyte Grid.
 *
 * This metadata is primarily useful for programmatic interaction with the grid. The values
 * are derived from the grid's internal column state and may change depending on modes
 * like pivoting. For example, when pivot mode is enabled, `columnsVisible` refers to
 * visible pivot columns instead of the regular ones.
 *
 * @group Column
 */
export interface ColumnMeta<T> {
    /**
     * An array of currently visible columns, accounting for `hide` flags and
     * column group collapse states.
     */
    readonly columnsVisible: Column<T>[];
    /**
     * A lookup map from column id to column definition. Useful for quick access or
     * metadata introspection.
     */
    readonly columnLookup: Map<string, Column<T>>;
    /**
     * The count of visible columns pinned to the start of the grid.
     */
    readonly columnVisibleStartCount: number;
    /**
     * The count of visible columns that are unpinned (center-aligned).
     */
    readonly columnVisibleCenterCount: number;
    /**
     * The count of visible columns pinned to the end of the grid.
     */
    readonly columnVisibleEndCount: number;
}
/**
 * Represents the possible pinned positions a column can occupy in LyteNyte Grid.
 *
 * The actual position is determined by the document's reading direction:
 * - In left-to-right (LTR) mode, `"start"` pins to the left and `"end"` to the right.
 * - In right-to-left (RTL) mode, this behavior is reversed.
 *
 * This approach aligns with CSS logical properties for layout direction.
 *
 * @group Column
 */
export type ColumnPin = "start" | "end" | null;
/**
 * Describes UI hints related to column pivot functionality.
 *
 * These hints indicate whether a column is eligible to act as a value, row group, or
 * column pivot in a pivot table configuration. External components can use these values
 * to determine pivot-related capabilities.
 *
 * @group Column
 */
export interface ColumnPivotUIHints {
    /**
     * Indicates whether the column can be used as a pivot value.
     */
    readonly value?: boolean;
    /**
     * Indicates whether the column can be used as a pivot row group.
     */
    readonly rows?: boolean;
    /**
     * Indicates whether the column can be used as a pivot column header.
     */
    readonly columns?: boolean;
}
/**
 * Describes a column definition in LyteNyte Grid.
 *
 * Columns define how data is presented and interacted with in the grid. They control
 * rendering, grouping, sorting, filtering, editing, and more.
 *
 * A grid must define at least one column to display meaningful data. Columns are essential
 * for determining