diff --git a/README.md b/README.md index 9ac3443858..0bba832f16 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ [size-url]: https://bundlephobia.com/package/react-data-grid [type-badge]: https://img.shields.io/npm/types/react-data-grid [codecov-badge]: https://codecov.io/gh/adazzle/react-data-grid/branch/main/graph/badge.svg?token=cvrRSWiz0Q -[codecov-url]: https://app.codecov.io/gh/adazzle/react-data-grid/branch/main +[codecov-url]: https://app.codecov.io/gh/adazzle/react-data-grid [ci-badge]: https://github.com/adazzle/react-data-grid/workflows/CI/badge.svg [ci-url]: https://github.com/adazzle/react-data-grid/actions @@ -25,7 +25,7 @@ The DataGrid component is designed to handle large datasets efficiently while of - Tree-shaking support and only [one npm dependency](package.json) to keep your bundles slim - Great performance thanks to virtualization: columns and rows outside the viewport are not rendered - Strictly typed with TypeScript -- [Keyboard accessibility](<(https://adazzle.github.io/react-data-grid/#/CommonFeatures)>) +- [Keyboard accessibility](https://adazzle.github.io/react-data-grid/#/CommonFeatures) - Light and dark mode support out of the box. The light or dark themes can be enforced using the `rdg-light` or `rdg-dark` classes. - [Frozen columns](https://adazzle.github.io/react-data-grid/#/CommonFeatures): Freeze columns to keep them visible during horizontal scrolling. - [Column resizing](https://adazzle.github.io/react-data-grid/#/CommonFeatures) @@ -55,14 +55,24 @@ The DataGrid component is designed to handle large datasets efficiently while of ## Installation -to install `react-data-grid`, use npm or yarn: +Install `react-data-grid` using your favorite package manager: + +```sh +npm i react-data-grid +``` + +```sh +pnpm add react-data-grid +``` ```sh -npm install react-data-grid -# or yarn add react-data-grid ``` +```sh +bun add react-data-grid +``` + Additionally, import the default styles in your application: ```tsx @@ -78,14 +88,19 @@ Here is a basic example of how to use `react-data-grid` in your React applicatio ```tsx import 'react-data-grid/lib/styles.css'; -import { DataGrid } from 'react-data-grid'; +import { DataGrid, type Column } from 'react-data-grid'; -const columns = [ +interface Row { + id: number; + title: string; +} + +const columns: Column[] = [ { key: 'id', name: 'ID' }, { key: 'title', name: 'Title' } ]; -const rows = [ +const rows: Row[] = [ { id: 0, title: 'Example' }, { id: 1, title: 'Demo' } ]; @@ -195,7 +210,7 @@ function addNewRow() { setColumnWidths(new Map()); } -return +return ``` ###### `onColumnWidthsChange?: Maybe<(columnWidths: ColumnWidths) => void>` @@ -286,10 +301,10 @@ function MyGrid() { } ``` -Grid can be sorted on multiple columns using `ctrl (command) + click`. To disable multiple column sorting, change the `onSortColumnsChange` function to +More than one column can be sorted via `ctrl (command) + click`. To disable multiple column sorting, change the `onSortColumnsChange` function to ```tsx -onSortColumnsChange(sortColumns: SortColumn[]) { +function onSortColumnsChange(sortColumns: SortColumn[]) { setSortColumns(sortColumns.slice(-1)); } ``` @@ -331,6 +346,8 @@ function onCellMouseDown(args: CellMouseDownArgs, event: CellMouseEvent) ; ``` +See [`CellMouseArgs`](#cellmouseargs) and [`CellMouseEvent`](#cellmouseevent) + ###### `onCellClick?: Maybe<(args: CellMouseArgs, event: CellMouseEvent) => void>` Callback triggered when a cell is clicked. @@ -355,19 +372,7 @@ function onCellClick(args: CellMouseArgs, event: CellMouseEvent) { } ``` -Arguments: - -`args: CellMouseArgs` - -- `args.rowIdx`: `number` - row index of the currently selected cell -- `args.row`: `R` - row object of the currently selected cell -- `args.column`: `CalculatedColumn` - column object of the currently selected cell -- `args.selectCell`: `(enableEditor?: boolean) => void` - function to manually select the cell and optionally pass `true` to start editing - -`event` extends `React.MouseEvent` - -- `event.preventGridDefault:`: `() => void` -- `event.isGridDefaultPrevented`: `boolean` +See [`CellMouseArgs`](#cellmouseargs) and [`CellMouseEvent`](#cellmouseevent) ###### `onCellDoubleClick?: Maybe<(args: CellMouseArgs, event: CellMouseEvent) => void>` @@ -383,6 +388,8 @@ function onCellDoubleClick(args: CellMouseArgs, event: CellMouseEvent) { ; ``` +See [`CellMouseArgs`](#cellmouseargs) and [`CellMouseEvent`](#cellmouseevent) + ###### `onCellContextMenu?: Maybe<(args: CellMouseArgs, event: CellMouseEvent) => void>` Callback triggered when a cell is right-clicked. @@ -398,6 +405,8 @@ function onCellContextMenu(args: CellMouseArgs, event: CellMouseEvent) { ; ``` +See [`CellMouseArgs`](#cellmouseargs) and [`CellMouseEvent`](#cellmouseevent) + ###### `onCellKeyDown?: Maybe<(args: CellKeyDownArgs, event: CellKeyboardEvent) => void>` A function called when keydown event is triggered on a cell. This event can be used to customize cell navigation and editing behavior. @@ -494,7 +503,7 @@ function MyGrid() { } ``` -:warning: To prevent all rows from being unmounted on re-renders, make sure to pass a static or memoized component to `renderRow`. +:warning: To prevent all rows from being unmounted on re-renders, make sure to pass a static or memoized render function to `renderRow`. ###### `rowClass?: Maybe<(row: R, rowIdx: number) => Maybe>` @@ -522,7 +531,7 @@ This property sets the text direction of the grid, it defaults to `'ltr'` (left- - Columns flow from right to left - Frozen columns are pinned on the right -- Column resize handle is shown on the left edge of the column +- Column resize cursor is shown on the left edge of the column - Scrollbar is moved to the left ###### `className?: string | undefined` @@ -549,16 +558,17 @@ If the grid has a caption or description, `aria-describedby` can be set on the g ###### `'data-testid'?: Maybe` -This prop can be used to add a testid for testing. We recommend using `role` and `name` to find the grid element +This prop can be used to add a testid for testing. We recommend querying the grid by by its `role` and `name`. ```tsx function MyGrid() { return ; } -function MyGridTest() { +test('grid', () => { + render(); const grid = screen.getByRole('grid', { name: 'my-grid' }); -} +}); ``` #### `` @@ -668,10 +678,10 @@ A unique key to distinguish each column Width can be any valid css grid column value. If not specified, it will be determined automatically based on grid width and specified widths of other columns. ```tsx -width: 80; // pixels -width: '25%'; -width: 'max-content'; -width: 'minmax(100px, max-content)'; +width: 80, // pixels +width: '25%', +width: 'max-content', +width: 'minmax(100px, max-content)', ``` `max-content` can be used to expand the column to show all the content. Note that the grid is only able to calculate column width for visible rows. @@ -716,7 +726,7 @@ Render function to render the content of edit cells. When set, the column is aut ##### `editable?: Maybe boolean)>` -Enables cell editing. If set and no editor property specified, then a textinput will be used as the cell editor. +Enables cell editing. If set and no editor property specified, then a text input will be used as the cell editor. ##### `colSpan?: Maybe<(args: ColSpanArgs) => Maybe>` @@ -772,6 +782,32 @@ Commit changes when clicking outside the cell. Close the editor when the row changes externally. +#### `CellMouseArgs` + +##### `rowIdx: number` + +Row index of the currently selected cell + +##### `row: TRow` + +row object of the currently selected cell + +##### `column: CalculatedColumn` + +column object of the currently selected cell + +##### `selectCell: (enableEditor?: boolean) => void` + +function to manually select the cell and optionally pass `true` to start editing + +#### `CellMouseEvent` + +Extends `React.MouseEvent` + +##### `event.preventGridDefault: () => void` + +##### `event.isGridDefaultPrevented: boolean` + #### `DataGridHandle` #### `RenderEditCellProps` diff --git a/src/types.ts b/src/types.ts index 12dee6f6cb..da6c461468 100644 --- a/src/types.ts +++ b/src/types.ts @@ -20,7 +20,7 @@ export interface Column { readonly width?: Maybe; /** * Minimum column width in pixels - * @default '50px' + * @default 50 */ readonly minWidth?: Maybe; /** Maximum column width in pixels */