UNPKG

react-data-grid

Version:

Feature-rich and customizable data grid React component

506 lines (434 loc) • 21 kB
import { Context } from 'react'; import { JSX } from 'react/jsx-runtime'; import type { Key } from 'react'; import type { ReactElement } from 'react'; import { ReactNode } from 'react'; declare interface BaseRenderRowProps<TRow, TSummaryRow = unknown> extends Omit_2<React.ComponentProps<'div'>, 'style' | 'children'>, Pick<DataGridProps<TRow, TSummaryRow>, 'onCellClick' | 'onCellDoubleClick' | 'onCellContextMenu'> { viewportColumns: readonly CalculatedColumn<TRow, TSummaryRow>[]; rowIdx: number; selectedCellIdx: number | undefined; isRowSelectionDisabled: boolean; isRowSelected: boolean; gridRowStart: number; selectCell: (position: Position, enableEditor?: Maybe<boolean>) => void; } export declare interface CalculatedColumn<TRow, TSummaryRow = unknown> extends Column<TRow, TSummaryRow> { readonly parent: CalculatedColumnParent<TRow, TSummaryRow> | undefined; readonly idx: number; readonly level: number; readonly width: number | string; readonly minWidth: number; readonly maxWidth: number | undefined; readonly resizable: boolean; readonly sortable: boolean; readonly draggable: boolean; readonly frozen: boolean; readonly renderCell: (props: RenderCellProps<TRow, TSummaryRow>) => ReactNode; readonly renderHeaderCell: (props: RenderHeaderCellProps<TRow, TSummaryRow>) => ReactNode; } export declare type CalculatedColumnOrColumnGroup<R, SR> = CalculatedColumnParent<R, SR> | CalculatedColumn<R, SR>; export declare interface CalculatedColumnParent<R, SR> { readonly name: string | ReactElement; readonly parent: CalculatedColumnParent<R, SR> | undefined; readonly idx: number; readonly colSpan: number; readonly level: number; readonly headerCellClass?: Maybe<string>; } export declare const Cell: <R, SR>(props: CellRendererProps<R, SR>) => React.JSX.Element; export declare interface CellClickArgs<TRow, TSummaryRow = unknown> { column: CalculatedColumn<TRow, TSummaryRow>; row: TRow; rowIdx: number; selectCell: (enableEditor?: boolean) => void; } declare type CellClipboardEvent = React.ClipboardEvent<HTMLDivElement>; export declare type CellCopyEvent<TRow, TSummaryRow = unknown> = CellCopyPasteEvent<TRow, TSummaryRow>; declare interface CellCopyPasteEvent<TRow, TSummaryRow = unknown> { column: CalculatedColumn<TRow, TSummaryRow>; row: TRow; } declare type CellEvent<E extends React.SyntheticEvent<HTMLDivElement>> = E & { preventGridDefault: () => void; isGridDefaultPrevented: () => boolean; }; export declare type CellKeyboardEvent = CellEvent<React.KeyboardEvent<HTMLDivElement>>; export declare type CellKeyDownArgs<TRow, TSummaryRow = unknown> = SelectCellKeyDownArgs<TRow, TSummaryRow> | EditCellKeyDownArgs<TRow, TSummaryRow>; export declare type CellMouseEvent = CellEvent<React.MouseEvent<HTMLDivElement>>; export declare type CellPasteEvent<TRow, TSummaryRow = unknown> = CellCopyPasteEvent<TRow, TSummaryRow>; export declare interface CellRendererProps<TRow, TSummaryRow> extends Pick<RenderRowProps<TRow, TSummaryRow>, 'row' | 'rowIdx' | 'selectCell'>, Omit_2<React.ComponentProps<'div'>, 'children' | 'onClick' | 'onDoubleClick' | 'onContextMenu'> { column: CalculatedColumn<TRow, TSummaryRow>; colSpan: number | undefined; isDraggedOver: boolean; isCellSelected: boolean; onClick: RenderRowProps<TRow, TSummaryRow>['onCellClick']; onDoubleClick: RenderRowProps<TRow, TSummaryRow>['onCellDoubleClick']; onContextMenu: RenderRowProps<TRow, TSummaryRow>['onCellContextMenu']; onRowChange: (column: CalculatedColumn<TRow, TSummaryRow>, newRow: TRow) => void; } export declare interface CellSelectArgs<TRow, TSummaryRow = unknown> { rowIdx: number; row: TRow | undefined; column: CalculatedColumn<TRow, TSummaryRow>; } export declare type ColSpanArgs<TRow, TSummaryRow> = { type: 'HEADER'; } | { type: 'ROW'; row: TRow; } | { type: 'SUMMARY'; row: TSummaryRow; }; export declare interface Column<TRow, TSummaryRow = unknown> { /** The name of the column. Displayed in the header cell by default */ readonly name: string | ReactElement; /** A unique key to distinguish each column */ readonly key: string; /** * Column width. If not specified, it will be determined automatically based on grid width and specified widths of other columns * @default 'auto' */ readonly width?: Maybe<number | string>; /** * Minimum column width in pixels * @default '50px' */ readonly minWidth?: Maybe<number>; /** Maximum column width in pixels */ readonly maxWidth?: Maybe<number>; /** Class name(s) for the cell */ readonly cellClass?: Maybe<string | ((row: TRow) => Maybe<string>)>; /** Class name(s) for the header cell */ readonly headerCellClass?: Maybe<string>; /** Class name(s) for the summary cell */ readonly summaryCellClass?: Maybe<string | ((row: TSummaryRow) => Maybe<string>)>; /** Render function to render the content of cells */ readonly renderCell?: Maybe<(props: RenderCellProps<TRow, TSummaryRow>) => ReactNode>; /** Render function to render the content of the header cell */ readonly renderHeaderCell?: Maybe<(props: RenderHeaderCellProps<TRow, TSummaryRow>) => ReactNode>; /** Render function to render the content of summary cells */ readonly renderSummaryCell?: Maybe<(props: RenderSummaryCellProps<TSummaryRow, TRow>) => ReactNode>; /** Render function to render the content of group cells */ readonly renderGroupCell?: Maybe<(props: RenderGroupCellProps<TRow, TSummaryRow>) => ReactNode>; /** Render function to render the content of edit cells. When set, the column is automatically set to be editable */ readonly renderEditCell?: Maybe<(props: RenderEditCellProps<TRow, TSummaryRow>) => ReactNode>; /** Enables cell editing. If set and no editor property specified, then a textinput will be used as the cell editor */ readonly editable?: Maybe<boolean | ((row: TRow) => boolean)>; readonly colSpan?: Maybe<(args: ColSpanArgs<TRow, TSummaryRow>) => Maybe<number>>; /** Determines whether column is frozen */ readonly frozen?: Maybe<boolean>; /** Enable resizing of the column */ readonly resizable?: Maybe<boolean>; /** Enable sorting of the column */ readonly sortable?: Maybe<boolean>; /** Enable dragging of the column */ readonly draggable?: Maybe<boolean>; /** Sets the column sort order to be descending instead of ascending the first time the column is sorted */ readonly sortDescendingFirst?: Maybe<boolean>; /** Options for cell editing */ readonly editorOptions?: Maybe<{ /** * Render the cell content in addition to the edit cell. * Enable this option when the editor is rendered outside the grid, like a modal for example. * By default, the cell content is not rendered when the edit cell is open. * @default false */ readonly displayCellContent?: Maybe<boolean>; /** * Commit changes when clicking outside the cell * @default true */ readonly commitOnOutsideClick?: Maybe<boolean>; /** * Close the editor when the row changes externally * @default true */ readonly closeOnExternalRowChange?: Maybe<boolean>; }>; } export declare interface ColumnGroup<R, SR = unknown> { /** The name of the column group, it will be displayed in the header cell */ readonly name: string | ReactElement; readonly headerCellClass?: Maybe<string>; readonly children: readonly ColumnOrColumnGroup<R, SR>[]; } export declare type ColumnOrColumnGroup<R, SR = unknown> = Column<R, SR> | ColumnGroup<R, SR>; /** * Main API Component to render a data grid of rows and columns * * @example * * <DataGrid columns={columns} rows={rows} /> */ export declare function DataGrid<R, SR = unknown, K extends Key = Key>(props: DataGridProps<R, SR, K>): JSX.Element; export declare const DataGridDefaultRenderersContext: Context<Maybe<Renderers<any, any>>>; export declare interface DataGridHandle { element: HTMLDivElement | null; scrollToCell: (position: PartialPosition) => void; selectCell: (position: Position, enableEditor?: Maybe<boolean>) => void; } export declare interface DataGridProps<R, SR = unknown, K extends Key = Key> extends SharedDivProps { ref?: Maybe<React.Ref<DataGridHandle>>; /** * Grid and data Props */ /** An array of column definitions */ columns: readonly ColumnOrColumnGroup<NoInfer<R>, NoInfer<SR>>[]; /** A function called for each rendered row that should return a plain key/value pair object */ rows: readonly R[]; /** Rows pinned at the top of the grid for summary purposes */ topSummaryRows?: Maybe<readonly SR[]>; /** Rows pinned at the bottom of the grid for summary purposes */ bottomSummaryRows?: Maybe<readonly SR[]>; /** Function to return a unique key/identifier for each row */ rowKeyGetter?: Maybe<(row: NoInfer<R>) => K>; /** Callback triggered when rows are changed */ onRowsChange?: Maybe<(rows: NoInfer<R>[], data: RowsChangeData<NoInfer<R>, NoInfer<SR>>) => void>; /** * Dimensions props */ /** * Height of each row in pixels * @default 35 */ rowHeight?: Maybe<number | ((row: NoInfer<R>) => number)>; /** * Height of the header row in pixels * @default 35 */ headerRowHeight?: Maybe<number>; /** * Height of each summary row in pixels * @default 35 */ summaryRowHeight?: Maybe<number>; /** * Feature props */ /** A set of selected row keys */ selectedRows?: Maybe<ReadonlySet<K>>; /** Function to determine if row selection is disabled for a specific row */ isRowSelectionDisabled?: Maybe<(row: NoInfer<R>) => boolean>; /** Callback triggered when the selection changes */ onSelectedRowsChange?: Maybe<(selectedRows: Set<NoInfer<K>>) => void>; /** An array of sorted columns */ sortColumns?: Maybe<readonly SortColumn[]>; /** Callback triggered when sorting changes */ onSortColumnsChange?: Maybe<(sortColumns: SortColumn[]) => void>; /** Default options applied to all columns */ defaultColumnOptions?: Maybe<DefaultColumnOptions<NoInfer<R>, NoInfer<SR>>>; onFill?: Maybe<(event: FillEvent<NoInfer<R>>) => NoInfer<R>>; /** * Event props */ /** Callback triggered when a cell is clicked */ onCellClick?: Maybe<(args: CellClickArgs<NoInfer<R>, NoInfer<SR>>, event: CellMouseEvent) => void>; /** Callback triggered when a cell is double-clicked */ onCellDoubleClick?: Maybe<(args: CellClickArgs<NoInfer<R>, NoInfer<SR>>, event: CellMouseEvent) => void>; /** Callback triggered when a cell is right-clicked */ onCellContextMenu?: Maybe<(args: CellClickArgs<NoInfer<R>, NoInfer<SR>>, event: CellMouseEvent) => void>; /** Callback triggered when a key is pressed in a cell */ onCellKeyDown?: Maybe<(args: CellKeyDownArgs<NoInfer<R>, NoInfer<SR>>, event: CellKeyboardEvent) => void>; /** Callback triggered when a cell's content is copied */ onCellCopy?: Maybe<(args: CellCopyEvent<NoInfer<R>, NoInfer<SR>>, event: CellClipboardEvent) => void>; /** Callback triggered when content is pasted into a cell */ onCellPaste?: Maybe<(args: CellPasteEvent<NoInfer<R>, NoInfer<SR>>, event: CellClipboardEvent) => NoInfer<R>>; /** Function called whenever cell selection is changed */ onSelectedCellChange?: Maybe<(args: CellSelectArgs<NoInfer<R>, NoInfer<SR>>) => void>; /** Callback triggered when the grid is scrolled */ onScroll?: Maybe<(event: React.UIEvent<HTMLDivElement>) => void>; /** Callback triggered when column is resized */ onColumnResize?: Maybe<(column: CalculatedColumn<R, SR>, width: number) => void>; /** Callback triggered when columns are reordered */ onColumnsReorder?: Maybe<(sourceColumnKey: string, targetColumnKey: string) => void>; /** * Toggles and modes */ /** @default true */ enableVirtualization?: Maybe<boolean>; /** * Miscellaneous */ /** Custom renderers for cells, rows, and other components */ renderers?: Maybe<Renderers<NoInfer<R>, NoInfer<SR>>>; /** Function to apply custom class names to rows */ rowClass?: Maybe<(row: NoInfer<R>, rowIdx: number) => Maybe<string>>; /** Custom class name for the header row */ headerRowClass?: Maybe<string>; /** * Text direction of the grid ('ltr' or 'rtl') * @default 'ltr' * */ direction?: Maybe<Direction>; 'data-testid'?: Maybe<string>; 'data-cy'?: Maybe<string>; } export declare type DefaultColumnOptions<R, SR> = Pick<Column<R, SR>, 'renderCell' | 'renderHeaderCell' | 'width' | 'minWidth' | 'maxWidth' | 'resizable' | 'sortable' | 'draggable'>; declare type Direction = 'ltr' | 'rtl'; declare interface EditCellKeyDownArgs<TRow, TSummaryRow = unknown> { mode: 'EDIT'; column: CalculatedColumn<TRow, TSummaryRow>; row: TRow; rowIdx: number; navigate: () => void; onClose: (commitChanges?: boolean, shouldFocusCell?: boolean) => void; } export declare interface FillEvent<TRow> { columnKey: string; sourceRow: TRow; targetRow: TRow; } declare interface GroupRow<TRow> { readonly childRows: readonly TRow[]; readonly id: string; readonly parentId: unknown; readonly groupKey: unknown; readonly isExpanded: boolean; readonly level: number; readonly posInSet: number; readonly setSize: number; readonly startRowIndex: number; } declare type Maybe<T> = T | undefined | null; declare type Omit_2<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>; declare interface PartialPosition { readonly idx?: number | undefined; readonly rowIdx?: number | undefined; } declare interface Position { readonly idx: number; readonly rowIdx: number; } export declare interface RenderCellProps<TRow, TSummaryRow = unknown> { column: CalculatedColumn<TRow, TSummaryRow>; row: TRow; rowIdx: number; isCellEditable: boolean; tabIndex: number; onRowChange: (row: TRow) => void; } export declare function renderCheckbox({ onChange, indeterminate, ...props }: RenderCheckboxProps): JSX.Element; export declare interface RenderCheckboxProps extends Pick<React.ComponentProps<'input'>, 'aria-label' | 'aria-labelledby' | 'checked' | 'tabIndex' | 'disabled'> { indeterminate?: boolean | undefined; onChange: (checked: boolean, shift: boolean) => void; } export declare interface RenderEditCellProps<TRow, TSummaryRow = unknown> { column: CalculatedColumn<TRow, TSummaryRow>; row: TRow; rowIdx: number; onRowChange: (row: TRow, commitChanges?: boolean) => void; onClose: (commitChanges?: boolean, shouldFocusCell?: boolean) => void; } export declare interface Renderers<TRow, TSummaryRow> { renderCell?: Maybe<(key: Key, props: CellRendererProps<TRow, TSummaryRow>) => ReactNode>; renderCheckbox?: Maybe<(props: RenderCheckboxProps) => ReactNode>; renderRow?: Maybe<(key: Key, props: RenderRowProps<TRow, TSummaryRow>) => ReactNode>; renderSortStatus?: Maybe<(props: RenderSortStatusProps) => ReactNode>; noRowsFallback?: Maybe<ReactNode>; } export declare interface RenderGroupCellProps<TRow, TSummaryRow = unknown> { groupKey: unknown; column: CalculatedColumn<TRow, TSummaryRow>; row: GroupRow<TRow>; childRows: readonly TRow[]; isExpanded: boolean; tabIndex: number; toggleGroup: () => void; } export declare function renderHeaderCell<R, SR>({ column, sortDirection, priority }: RenderHeaderCellProps<R, SR>): string | JSX.Element; export declare interface RenderHeaderCellProps<TRow, TSummaryRow = unknown> { column: CalculatedColumn<TRow, TSummaryRow>; sortDirection: SortDirection | undefined; priority: number | undefined; tabIndex: number; } export declare interface RenderRowProps<TRow, TSummaryRow = unknown> extends BaseRenderRowProps<TRow, TSummaryRow> { row: TRow; lastFrozenColumnIndex: number; draggedOverCellIdx: number | undefined; selectedCellEditor: ReactElement<RenderEditCellProps<TRow>> | undefined; onRowChange: (column: CalculatedColumn<TRow, TSummaryRow>, rowIdx: number, newRow: TRow) => void; rowClass: Maybe<(row: TRow, rowIdx: number) => Maybe<string>>; setDraggedOverRowIdx: ((overRowIdx: number) => void) | undefined; } export declare function renderSortIcon({ sortDirection }: RenderSortIconProps): JSX.Element | null; export declare interface RenderSortIconProps { sortDirection: SortDirection | undefined; } export declare function renderSortPriority({ priority }: RenderSortPriorityProps): number | undefined; export declare interface RenderSortPriorityProps { priority: number | undefined; } export declare interface RenderSortStatusProps extends RenderSortIconProps, RenderSortPriorityProps { } export declare interface RenderSummaryCellProps<TSummaryRow, TRow = unknown> { column: CalculatedColumn<TRow, TSummaryRow>; row: TSummaryRow; tabIndex: number; } export declare function renderToggleGroup<R, SR>(props: RenderGroupCellProps<R, SR>): JSX.Element; export declare function renderValue<R, SR>(props: RenderCellProps<R, SR>): ReactNode; export declare const Row: <R, SR>(props: RenderRowProps<R, SR>) => React.JSX.Element; export declare type RowHeightArgs<TRow> = { type: 'ROW'; row: TRow; } | { type: 'GROUP'; row: GroupRow<TRow>; }; export declare interface RowsChangeData<R, SR = unknown> { indexes: number[]; column: CalculatedColumn<R, SR>; } export declare const SELECT_COLUMN_KEY = "rdg-select-column"; export declare function SelectCellFormatter({ value, tabIndex, indeterminate, disabled, onChange, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy }: SelectCellFormatterProps): ReactNode; declare interface SelectCellFormatterProps extends SharedInputProps { value: boolean; } declare interface SelectCellKeyDownArgs<TRow, TSummaryRow = unknown> { mode: 'SELECT'; column: CalculatedColumn<TRow, TSummaryRow>; row: TRow; rowIdx: number; selectCell: (position: Position, enableEditor?: Maybe<boolean>) => void; } export declare const SelectColumn: Column<any, any>; export declare interface SelectHeaderRowEvent { checked: boolean; } export declare interface SelectRowEvent<TRow> { row: TRow; checked: boolean; isShiftClick: boolean; } declare type SharedDivProps = Pick<React.ComponentProps<'div'>, 'role' | 'aria-label' | 'aria-labelledby' | 'aria-description' | 'aria-describedby' | 'aria-rowcount' | 'className' | 'style'>; declare type SharedInputProps = Pick<RenderCheckboxProps, 'disabled' | 'tabIndex' | 'aria-label' | 'aria-labelledby' | 'indeterminate' | 'onChange'>; export declare interface SortColumn { readonly columnKey: string; readonly direction: SortDirection; } export declare type SortDirection = 'ASC' | 'DESC'; export declare function textEditor<TRow, TSummaryRow>({ row, column, onRowChange, onClose }: RenderEditCellProps<TRow, TSummaryRow>): JSX.Element; export declare function ToggleGroup<R, SR>({ groupKey, isExpanded, tabIndex, toggleGroup }: RenderGroupCellProps<R, SR>): JSX.Element; export declare function TreeDataGrid<R, SR = unknown, K extends Key = Key>({ columns: rawColumns, rows: rawRows, rowHeight: rawRowHeight, rowKeyGetter: rawRowKeyGetter, onCellKeyDown: rawOnCellKeyDown, onCellCopy: rawOnCellCopy, onCellPaste: rawOnCellPaste, onRowsChange, selectedRows: rawSelectedRows, onSelectedRowsChange: rawOnSelectedRowsChange, renderers, groupBy: rawGroupBy, rowGrouper, expandedGroupIds, onExpandedGroupIdsChange, groupIdGetter: rawGroupIdGetter, ...props }: TreeDataGridProps<R, SR, K>): JSX.Element; export declare interface TreeDataGridProps<R, SR = unknown, K extends Key = Key> extends Omit_2<DataGridProps<R, SR, K>, 'columns' | 'role' | 'aria-rowcount' | 'rowHeight' | 'onFill' | 'isRowSelectionDisabled'> { columns: readonly Column<NoInfer<R>, NoInfer<SR>>[]; rowHeight?: Maybe<number | ((args: RowHeightArgs<NoInfer<R>>) => number)>; groupBy: readonly string[]; rowGrouper: (rows: readonly NoInfer<R>[], columnKey: string) => Record<string, readonly NoInfer<R>[]>; expandedGroupIds: ReadonlySet<unknown>; onExpandedGroupIdsChange: (expandedGroupIds: Set<unknown>) => void; groupIdGetter?: Maybe<(groupKey: string, parentId?: string) => string>; } export declare function useHeaderRowSelection(): { isIndeterminate: boolean; isRowSelected: boolean; onRowSelectionChange: (selectRowEvent: SelectHeaderRowEvent) => void; }; export declare function useRowSelection(): { isRowSelectionDisabled: boolean; isRowSelected: boolean; onRowSelectionChange: (selectRowEvent: SelectRowEvent<any>) => void; }; export { }