@carbon/react
Version:
React components for the Carbon Design System
373 lines (372 loc) • 14.3 kB
TypeScript
/**
* Copyright IBM Corp. 2016, 2025
*
* This source code is licensed under the Apache-2.0 license found in the
* LICENSE file in the root directory of this source tree.
*/
import React, { Component, type ChangeEvent, type MouseEvent, type ReactElement, type ReactNode } from 'react';
import type { DataTableSortState } from './state/sortStates';
import Table from './Table';
import TableActionList from './TableActionList';
import TableBatchAction from './TableBatchAction';
import TableBatchActions from './TableBatchActions';
import TableBody from './TableBody';
import TableCell from './TableCell';
import TableContainer from './TableContainer';
import TableDecoratorRow from './TableDecoratorRow';
import TableExpandHeader from './TableExpandHeader';
import TableExpandRow from './TableExpandRow';
import TableExpandedRow from './TableExpandedRow';
import TableHead from './TableHead';
import TableHeader from './TableHeader';
import TableRow from './TableRow';
import TableSelectAll from './TableSelectAll';
import TableSelectRow from './TableSelectRow';
import TableSlugRow from './TableSlugRow';
import TableToolbar from './TableToolbar';
import TableToolbarAction from './TableToolbarAction';
import TableToolbarContent from './TableToolbarContent';
import TableToolbarSearch from './TableToolbarSearch';
import TableToolbarMenu from './TableToolbarMenu';
import { TranslateWithId } from '../../types/common';
declare const translationKeys: {
readonly expandRow: "carbon.table.row.expand";
readonly collapseRow: "carbon.table.row.collapse";
readonly expandAll: "carbon.table.all.expand";
readonly collapseAll: "carbon.table.all.collapse";
readonly selectAll: "carbon.table.all.select";
readonly unselectAll: "carbon.table.all.unselect";
readonly selectRow: "carbon.table.row.select";
readonly unselectRow: "carbon.table.row.unselect";
};
/**
* Message ids that will be passed to translateWithId().
*/
type TranslationKey = (typeof translationKeys)[keyof typeof translationKeys];
export type DataTableSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
export interface DataTableCell<T> {
id: string;
value: T;
isEditable: boolean;
isEditing: boolean;
isValid: boolean;
errors: null | Error[];
info: {
header: string;
};
hasAILabelHeader?: boolean;
hasDecoratorHeader?: boolean;
}
type DataTableCells<T extends any[]> = {
[K in keyof T]: DataTableCell<T[K]>;
};
export interface DataTableRow<ColTypes extends any[]> {
id: string;
cells: DataTableCells<ColTypes>;
disabled?: boolean;
isExpanded?: boolean;
isSelected?: boolean;
}
export interface DataTableHeader {
key: string;
header: ReactNode;
slug?: ReactElement;
decorator?: ReactElement;
}
export interface DataTableRenderProps<RowType, ColTypes extends any[]> {
headers: DataTableHeader[];
rows: (DataTableRow<ColTypes> & RowType)[];
selectedRows: (DataTableRow<ColTypes> & RowType)[];
getHeaderProps: (options: {
header: DataTableHeader;
isSortable?: boolean;
onClick?: (event: MouseEvent<HTMLButtonElement>, sortState: {
sortHeaderKey: string;
sortDirection: DataTableSortState;
}) => void;
[key: string]: unknown;
}) => {
isSortable: boolean | undefined;
isSortHeader: boolean;
key: string;
onClick: (event: MouseEvent<HTMLButtonElement>) => void;
sortDirection: DataTableSortState;
[key: string]: unknown;
};
getExpandHeaderProps: (options?: {
onClick?: (event: MouseEvent<HTMLButtonElement>, expandState: {
isExpanded?: boolean;
}) => void;
onExpand?: (event: MouseEvent<HTMLButtonElement>) => void;
[key: string]: unknown;
}) => {
['aria-label']: string;
isExpanded: boolean;
onExpand: (event: MouseEvent<HTMLButtonElement>) => void;
[key: string]: unknown;
};
getRowProps: (options: {
onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
row: DataTableRow<ColTypes>;
[key: string]: unknown;
}) => {
['aria-label']: string;
disabled: boolean | undefined;
isExpanded?: boolean;
isSelected?: boolean;
key: string;
onExpand: (event: MouseEvent<HTMLButtonElement>) => void;
[key: string]: unknown;
};
getExpandedRowProps: (options: {
row: DataTableRow<ColTypes>;
[key: string]: unknown;
}) => {
['id']: string;
[key: string]: unknown;
};
getSelectionProps: (options?: {
onClick?: (event: MouseEvent<HTMLInputElement, globalThis.MouseEvent>) => void;
row?: DataTableRow<ColTypes>;
[key: string]: unknown;
}) => {
'aria-label': string;
checked?: boolean | undefined;
disabled?: boolean | undefined;
id: string;
indeterminate?: boolean;
name: string;
onSelect: (event: MouseEvent<HTMLInputElement>) => void;
radio?: boolean | undefined;
[key: string]: unknown;
};
getToolbarProps: (options?: {
[key: string]: unknown;
}) => {
size: 'sm' | undefined;
[key: string]: unknown;
};
getBatchActionProps: (options?: {
[key: string]: unknown;
}) => {
onCancel: () => void;
onSelectAll?: () => void | undefined;
shouldShowBatchActions: boolean;
totalCount: number;
totalSelected: number;
[key: string]: unknown;
};
getTableProps: () => {
experimentalAutoAlign?: boolean;
isSortable?: boolean;
overflowMenuOnHover: boolean;
size: DataTableSize;
stickyHeader?: boolean;
useStaticWidth?: boolean;
useZebraStyles?: boolean;
};
getTableContainerProps: () => {
stickyHeader?: boolean;
useStaticWidth?: boolean;
};
getCellProps: (options: {
cell: DataTableCell<ColTypes>;
}) => {
[key: string]: unknown;
hasAILabelHeader?: boolean;
hasDecoratorHeader?: boolean;
};
onInputChange: (event: ChangeEvent<HTMLInputElement>, defaultValue?: string) => void;
sortBy: (headerKey: string) => void;
selectAll: () => void;
selectRow: (rowId: string) => void;
expandRow: (rowId: string) => void;
expandAll: () => void;
radio: boolean | undefined;
}
export interface DataTableProps<RowType, ColTypes extends any[]> extends TranslateWithId<TranslationKey> {
children?: (renderProps: DataTableRenderProps<RowType, ColTypes>) => ReactElement;
experimentalAutoAlign?: boolean;
filterRows?: (options: {
cellsById: Record<string, DataTableCell<ColTypes>>;
getCellId: (rowId: string, header: string) => string;
headers: DataTableHeader[];
inputValue: string;
rowIds: string[];
}) => string[];
headers: DataTableHeader[];
isSortable?: boolean;
locale?: string;
overflowMenuOnHover?: boolean;
radio?: boolean;
render?: (renderProps: DataTableRenderProps<RowType, ColTypes>) => ReactElement;
rows: Omit<DataTableRow<ColTypes>, 'cells'>[];
size?: DataTableSize;
sortRow?: (cellA: any, cellB: any, options: {
sortDirection: DataTableSortState;
sortStates: Record<DataTableSortState, DataTableSortState>;
locale: string;
key: string;
compare: (a: number | string, b: number | string, locale?: string) => number;
}) => number;
stickyHeader?: boolean;
useStaticWidth?: boolean;
useZebraStyles?: boolean;
}
interface DataTableState<ColTypes extends any[]> {
cellsById: Record<string, DataTableCell<ColTypes>>;
filterInputValue: string | null;
initialRowOrder: string[];
isExpandedAll: boolean;
rowIds: string[];
rowsById: Record<string, DataTableRow<ColTypes>>;
shouldShowBatchActions: boolean;
sortDirection: DataTableSortState;
sortHeaderKey: string | null;
}
/**
* Data Tables are used to represent a collection of resources, displaying a
* subset of their fields in columns, or headers. We prioritize direct updates
* to the state of what we're rendering, so internally we end up normalizing the
* given data and then denormalizing it when rendering.
*
* As a result, each part of the DataTable is accessible through look-up by id,
* and updating the state of the single entity will cascade updates to the
* consumer.
*/
declare class DataTable<RowType, ColTypes extends any[]> extends Component<DataTableProps<RowType, ColTypes>, DataTableState<ColTypes>> {
instanceId: number;
static translationKeys: ("carbon.table.row.expand" | "carbon.table.row.collapse" | "carbon.table.all.expand" | "carbon.table.all.collapse" | "carbon.table.all.select" | "carbon.table.all.unselect" | "carbon.table.row.select" | "carbon.table.row.unselect")[];
static Table: typeof Table;
static TableActionList: typeof TableActionList;
static TableBatchAction: typeof TableBatchAction;
static TableBatchActions: typeof TableBatchActions;
static TableBody: typeof TableBody;
static TableCell: typeof TableCell;
static TableContainer: typeof TableContainer;
static TableDecoratorRow: typeof TableDecoratorRow;
static TableExpandHeader: typeof TableExpandHeader;
static TableExpandRow: typeof TableExpandRow;
static TableExpandedRow: typeof TableExpandedRow;
static TableHead: typeof TableHead;
static TableHeader: typeof TableHeader;
static TableRow: typeof TableRow;
static TableSelectAll: typeof TableSelectAll;
static TableSelectRow: typeof TableSelectRow;
static TableSlugRow: typeof TableSlugRow;
static TableToolbar: typeof TableToolbar;
static TableToolbarAction: typeof TableToolbarAction;
static TableToolbarContent: typeof TableToolbarContent;
static TableToolbarSearch: typeof TableToolbarSearch;
static TableToolbarMenu: typeof TableToolbarMenu;
private readonly rp;
constructor(props: DataTableProps<RowType, ColTypes>);
shouldComponentUpdate(nextProps: DataTableProps<RowType, ColTypes>): boolean;
/**
* Get the props associated with the given header. Mostly used for adding in
* sorting behavior.
*/
getHeaderProps: (typeof this.rp)['getHeaderProps'];
/**
* Get the props associated with the given expand header.
*/
getExpandHeaderProps: (typeof this.rp)['getExpandHeaderProps'];
/**
* Decorate consumer's `onClick` event handler with sort parameters
*/
handleOnHeaderClick: (onClick: (event: MouseEvent<HTMLButtonElement>, sortParams: {
sortHeaderKey: string;
sortDirection: DataTableSortState;
}) => void, sortParams: {
sortHeaderKey: string;
sortDirection: DataTableSortState;
}) => (event: MouseEvent<HTMLButtonElement>) => void;
/**
* Decorate consumer's `onClick` event handler with expand parameters
*/
handleOnExpandHeaderClick: (onClick: (event: MouseEvent<HTMLButtonElement>, expandParams: {
isExpanded: boolean;
}) => void, expandParams: {
isExpanded: boolean;
}) => (event: MouseEvent<HTMLButtonElement>) => void;
/**
* Get the props associated with the given row. Mostly used for expansion.
*/
getRowProps: (typeof this.rp)['getRowProps'];
/**
* Get the props associated with an expanded row
*/
getExpandedRowProps: (typeof this.rp)['getExpandedRowProps'];
/**
* Gets the props associated with selection for a header or a row, where
* applicable. Most often used to indicate selection status of the table or
* for a specific row.
*/
getSelectionProps: (typeof this.rp)['getSelectionProps'];
getToolbarProps: (typeof this.rp)['getToolbarProps'];
getBatchActionProps: (typeof this.rp)['getBatchActionProps'];
getTableProps: (typeof this.rp)['getTableProps'];
getTableContainerProps: (typeof this.rp)['getTableContainerProps'];
/**
* Get the props associated with the given table cell.
*/
getCellProps: (typeof this.rp)['getCellProps'];
/**
* Helper utility to get all the currently selected rows
*
* @returns the array of rowIds that are currently selected
*/
getSelectedRows: () => string[];
/**
* Helper utility to get all of the available rows after applying the filter
*
* @returns the array of rowIds that are currently included through the filter
*/
getFilteredRowIds: () => string[];
/**
* Helper for getting the table prefix for elements that require an
* `id` attribute that is unique.
*/
getTablePrefix: () => string;
/**
* Helper for toggling all selected items in a state. Does not call
* setState, so use it when setting state.
*
* @returns object to put into this.setState (use spread operator)
*/
setAllSelectedState: (initialState: DataTableState<ColTypes>, isSelected: boolean, filteredRowIds: string[]) => Pick<DataTableState<ColTypes>, "rowsById">;
/**
* Handler for the `onCancel` event to hide the batch action bar and
* deselect all selected rows
*/
handleOnCancel: () => void;
/**
* Handler for toggling the selection state of all rows in the database
*/
handleSelectAll: () => void;
/**
* Handler for toggling the selection state of a given row.
*/
handleOnSelectRow: (rowId: string) => () => void;
/**
* Handler for toggling the expansion state of a given row.
*/
handleOnExpandRow: (rowId: string) => () => void;
/**
* Handler for changing the expansion state of all rows.
*/
handleOnExpandAll: () => void;
/**
* Handler for transitioning to the next sort state of the table
*
* @param headerKey - The field for the header that we are sorting by.
*/
handleSortBy: (headerKey: string) => () => void;
/**
* Event handler for transitioning input value state changes for the table
* filter component.
*/
handleOnInputValueChange: (event: ChangeEvent<HTMLInputElement>, defaultValue?: string) => void;
render(): React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | null;
}
export default DataTable;