@pablovsouza/react-datagrid 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pablo Souza
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,268 @@
1
- # Temporary Holding Version
1
+ # @pablovsouza/react-datagrid
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Keyboard-first data grid for React that behaves like a desktop grid (WinForms `DataGridView`, WPF `DataGrid`):
4
+
5
+ - Virtualized rows: tens of thousands of rows, only the visible ones in the DOM
6
+ - Columns: width, min / max, resize (drag the header edge), reorder (drag the header), hide, freeze at the start
7
+ or the end, alignment, value formatting, flexible width
8
+ - Sorting: click a header (ascending, descending, none), Shift+click for several columns, custom comparators,
9
+ or server-side (`manualSorting`)
10
+ - Row selection (default) or cell selection, with ranges: Shift+arrows, Shift+click, mouse drag, Ctrl+click,
11
+ Ctrl+A
12
+ - Clipboard: Ctrl+C copies the selection as tab-separated text (pastes into Excel, LibreOffice, Google Sheets);
13
+ Ctrl+V pastes into editable cells (one value fills the selection)
14
+ - In-place editing: F2, double-click or typing starts; Enter / Tab commit and move; Esc cancels; editor slots per
15
+ column; commit / cancel events with validation
16
+ - Theming by CSS variables; ARIA `grid` roles; touch (tap, long press, native swipe scrolling)
17
+
18
+ Status: `0.1.0`, developed against a real ERP (SAPE). Not published yet.
19
+
20
+ ## Installation
21
+
22
+ ```bash
23
+ npm install @pablovsouza/react-datagrid
24
+ ```
25
+
26
+ Peer dependencies: `react@^19`, `react-dom@^19`. The package ships ES modules for bundlers (Vite, webpack,
27
+ Next.js) and its own stylesheet, imported by the entry (no Tailwind or other setup in the app).
28
+
29
+ ## Quick start
30
+
31
+ ```tsx
32
+ import { DataGrid, type DataGridColumn } from '@pablovsouza/react-datagrid'
33
+
34
+ interface Product {
35
+ id: number
36
+ name: string
37
+ stock: number
38
+ price: number
39
+ }
40
+
41
+ const money = new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' })
42
+
43
+ const columns: DataGridColumn<Product>[] = [
44
+ { id: 'id', header: 'Code', width: 80, align: 'end', frozen: 'start' },
45
+ { id: 'name', header: 'Name', width: 260, grow: 1, editable: true },
46
+ { id: 'stock', header: 'Stock', width: 90, align: 'end' },
47
+ {
48
+ id: 'price',
49
+ header: 'Price',
50
+ width: 120,
51
+ align: 'end',
52
+ format: (value) => money.format(value as number)
53
+ }
54
+ ]
55
+
56
+ export function Products({ rows }: { rows: Product[] }) {
57
+ return (
58
+ <DataGrid
59
+ rows={rows}
60
+ columns={columns}
61
+ getRowId={(row) => String(row.id)}
62
+ onRowActivate={(row) => open(row)}
63
+ aria-label="Products"
64
+ style={{ height: 400 }}
65
+ />
66
+ )
67
+ }
68
+ ```
69
+
70
+ The grid fills the height you give it (`style`, `className`, or a flex parent) and scrolls inside.
71
+
72
+ ## Why TanStack Table and TanStack Virtual inside
73
+
74
+ Writing a grid from scratch means re-solving virtualization (scroll anchoring, overscan, `scrollToIndex` with
75
+ sticky headers) and the column model (ordering with hidden and pinned columns, sizing, multi-column sorting).
76
+ Two mature MIT libraries already do exactly that, headless, with no markup or styles of their own:
77
+
78
+ - **[TanStack Table](https://tanstack.com/table)** (v9): sorted row model, column order, sizing, visibility and
79
+ pinning. The grid owns the state (controlled or not) and feeds it in.
80
+ - **[TanStack Virtual](https://tanstack.com/virtual)** (v3): row virtualization.
81
+
82
+ What they do not give, this package adds: the desktop keyboard model, the current cell, row / cell selection with
83
+ ranges, clipboard, in-place editing, mouse and touch gestures, ARIA, theming. Full grids were considered and
84
+ rejected: AG Grid (the useful parts — range selection, clipboard — are in the paid Enterprise edition), MUI X
85
+ Data Grid (same: Pro / Premium, plus Material UI), Glide Data Grid (canvas: no DOM cells for custom React
86
+ content, harder ARIA), react-data-grid (closest fit, MIT, but its keyboard and selection model is not a desktop
87
+ grid's and cell ranges are not built in). Wrapping headless engines keeps the behaviour ours and the hard generic
88
+ parts maintained by others.
89
+
90
+ ## Columns
91
+
92
+ ```ts
93
+ interface DataGridColumn<T> {
94
+ id: string // unique, stable (state, sorting, events)
95
+ header: ReactNode
96
+ value?: (row: T) => unknown // default row[id]; used by sort, copy, paste, default cell
97
+ format?: (value: unknown, row: T) => string // shown and copied text
98
+ cell?: (context: CellContext<T>) => ReactNode // custom content
99
+ width?: number // default 150
100
+ minWidth?: number // default 40
101
+ maxWidth?: number
102
+ grow?: number // share of extra width (flex-grow)
103
+ align?: 'start' | 'center' | 'end'
104
+ sortable?: boolean // default true
105
+ resizable?: boolean // default true
106
+ reorderable?: boolean // default true
107
+ hideable?: boolean // default true
108
+ hidden?: boolean // initial
109
+ frozen?: 'start' | 'end' // initial
110
+ compare?: (a: unknown, b: unknown) => number // ascending; default: numbers, dates, natural text
111
+ editable?: boolean | ((row: T) => boolean)
112
+ editor?: (props: EditorProps<T>) => ReactNode // default: text input
113
+ parse?: (text: string, row: T) => unknown // typed / pasted text to value; undefined rejects
114
+ title?: string // header tooltip
115
+ headerClassName?: string
116
+ cellClassName?: string | ((row: T) => string | undefined)
117
+ }
118
+ ```
119
+
120
+ `CellContext<T>`: `{ row, rowIndex, rowId, column, value, text, selected, active }`.
121
+
122
+ ## Props
123
+
124
+ | Prop | Type | Default | |
125
+ | ------------------------------------------------------------------ | ------------------------------ | ------------------------------------------ | -------------------------------------------------------------------------------------------- |
126
+ | `rows` | `readonly T[]` | | Keep the array stable between renders. |
127
+ | `columns` | `readonly DataGridColumn<T>[]` | | Keep stable (module scope or `useMemo`). |
128
+ | `getRowId` | `(row, index) => string` | | |
129
+ | `selectionMode` | `'row' \| 'cell'` | `'row'` | |
130
+ | `multiSelect` | `boolean` | `true` | Ranges, Ctrl+click, Ctrl+A. |
131
+ | `activeCell` / `defaultActiveCell` / `onActiveCellChange` | `CellPosition \| null` | first cell | Controlled or not. |
132
+ | `activeRowIndex` / `onActiveRowChange` | `number` | | Row-mode shortcut for the current row (`-1`: none). |
133
+ | `selection` / `defaultSelection` / `onSelectionChange` | `CellRange[]` | | The ranges always contain the current cell. |
134
+ | `sorting` / `defaultSorting` / `onSortingChange` | `SortItem[]` | `[]` | `{ columnId, direction }`. |
135
+ | `manualSorting` | `boolean` | `false` | Rows come sorted (server side). |
136
+ | `columnState` / `defaultColumnState` / `onColumnStateChange` | `ColumnState` | from columns | `{ order, widths, hidden, frozenStart, frozenEnd }`: persist it to remember a user's layout. |
137
+ | `rowHeight` / `headerHeight` | `number` | `32` / row height | Pixels. |
138
+ | `overscan` | `number` | `8` | Rows rendered beyond the visible ones. |
139
+ | `editable` | `boolean` | `false` | Turns on editing and paste for `editable` columns. |
140
+ | `onCellEdit` | `(change) => void \| false` | | `false` keeps the editor open. |
141
+ | `onPaste` | `(changes) => void` | one `onCellEdit` per cell | |
142
+ | `onRowActivate` | `(row, rowIndex) => void` | | Enter and double-click (on cells that are not edited). |
143
+ | `onCellContextMenu` | `(cell, row, point) => void` | | Right-click and long press. |
144
+ | `onKeyDown` | `(event, context) => void` | | Runs first; `event.preventDefault()` stops the grid handling the key. |
145
+ | `tabBehavior` | `'cell' \| 'leave'` | `cell` mode: `'cell'`, row mode: `'leave'` | |
146
+ | `rowClassName` | `(row, rowIndex) => string` | | |
147
+ | `empty` | `ReactNode` | | Shown without rows. |
148
+ | `aria-label`, `aria-labelledby`, `className`, `style`, `autoFocus` | | | |
149
+
150
+ `CellChange<T>`: `{ row, rowIndex, rowId, columnId, value, previousValue }`. Row indexes are positions in the
151
+ displayed (sorted) rows.
152
+
153
+ ## Handle (`ref`)
154
+
155
+ ```ts
156
+ const grid = useRef<DataGridHandle>(null)
157
+ grid.current.focus()
158
+ grid.current.scrollToRow(500)
159
+ grid.current.getActiveCell() // { row, col } | null
160
+ grid.current.setActiveCell({ row: 0, col: 2 })
161
+ grid.current.selectAll()
162
+ grid.current.getSelectionText() // what Ctrl+C copies
163
+ grid.current.paste('a\tb\n1\t2') // what Ctrl+V does
164
+ grid.current.startEdit()
165
+ grid.current.getDisplayedRows()
166
+ grid.current.getColumnState()
167
+ grid.current.moveColumn('price', 0)
168
+ grid.current.setColumnWidth('name', 300) // null: back to the column's width
169
+ grid.current.setColumnHidden('stock', true)
170
+ grid.current.setColumnFrozen('id', 'start') // or 'end', null
171
+ ```
172
+
173
+ ## Keyboard
174
+
175
+ | Key | Row mode | Cell mode |
176
+ | ------------------------ | ------------------------------------------ | ------------------------------------------------------- |
177
+ | ↑ ↓ | previous / next row | cell above / below |
178
+ | ← → | current column (scrolls sideways) | cell left / right |
179
+ | Ctrl+arrow | first / last row or column | edge of the grid in that direction |
180
+ | Home / End | first / last row | first / last cell of the row |
181
+ | Ctrl+Home / Ctrl+End | first / last row | first / last cell of the grid |
182
+ | PageUp / PageDown | one page of rows | one page of rows |
183
+ | Shift + any of the above | extends the range | extends the range |
184
+ | Tab / Shift+Tab | leaves the grid (`tabBehavior`) | next / previous cell, wrapping rows; leaves at the ends |
185
+ | Enter / Shift+Enter | `onRowActivate`; else (editable) down / up | the same |
186
+ | F2 / typing | edits the current cell (editable columns) | the same |
187
+ | Esc | collapses a range; else not handled | the same |
188
+ | Ctrl+A | selects all | selects all |
189
+ | Ctrl+C / Ctrl+V | copies / pastes | copies / pastes |
190
+
191
+ While editing (default editor): Enter / Shift+Enter commit and move down / up, Tab / Shift+Tab commit and move
192
+ right / left, Esc cancels, leaving the cell commits. Custom editors call `commit(value, move)` and `cancel()`;
193
+ the slot cancels on Esc unless the editor called `preventDefault()` (an open dropdown, say).
194
+
195
+ Keys the grid does not use (F-keys, Insert, Delete, Space, Esc with nothing to collapse…) bubble normally, so
196
+ window or app shortcuts keep working. Keys it handles are stopped (`preventDefault` + `stopPropagation`).
197
+ Ctrl means Cmd on macOS.
198
+
199
+ ## Mouse and touch
200
+
201
+ Click selects (Shift extends, Ctrl / Cmd adds a range), dragging across cells selects a range, double-click edits
202
+ or activates, right-click calls `onCellContextMenu`. Header click sorts, dragging a header onto another moves it
203
+ there, dragging the header edge resizes and double-clicking it restores the width. On touch screens a tap
204
+ selects, a long press (550 ms) calls `onCellContextMenu`, and scrolling is the browser's own (both axes).
205
+
206
+ ## Theming
207
+
208
+ Set the variables on `.rdg`, a parent or `:root`:
209
+
210
+ | Variable | Default | |
211
+ | ---------------------------------------------------------- | ----------------------------- | ------------------------------------------ |
212
+ | `--rdg-bg`, `--rdg-fg` | `Canvas`, `CanvasText` | Grid colours. |
213
+ | `--rdg-border` | 14% text colour | Row and header lines. |
214
+ | `--rdg-header-bg`, `--rdg-header-fg` | | |
215
+ | `--rdg-row-odd-bg`, `--rdg-row-hover-bg` | | Striping, hover. |
216
+ | `--rdg-selected-bg`, `--rdg-selected-fg` | `Highlight`, `HighlightText` | Selected rows. |
217
+ | `--rdg-selected-bg-inactive`, `--rdg-selected-fg-inactive` | the same | Selected rows while the grid has no focus. |
218
+ | `--rdg-range-bg`, `--rdg-range-fg` | 22% selection colour, inherit | Cell mode ranges. |
219
+ | `--rdg-active-outline` | selection colour | Current cell (cell mode). |
220
+ | `--rdg-editor-bg`, `--rdg-editor-fg`, `--rdg-invalid` | | Editor. |
221
+ | `--rdg-font-size`, `--rdg-cell-padding` | inherit, `0 8px` | |
222
+
223
+ Mapping an app's theme, e.g. one with its own selection variables:
224
+
225
+ ```css
226
+ .rdg {
227
+ --rdg-bg: var(--background);
228
+ --rdg-fg: var(--foreground);
229
+ --rdg-border: var(--border);
230
+ --rdg-selected-bg: var(--app-selected-bg);
231
+ --rdg-selected-fg: var(--app-selected-fg);
232
+ }
233
+ ```
234
+
235
+ The base styles are in the CSS layer `rdg`. Unlayered app CSS always overrides them; an app that uses layers
236
+ (Tailwind v4 does) declares `rdg` first so its utilities win too:
237
+
238
+ ```css
239
+ @layer rdg;
240
+ @import 'tailwindcss';
241
+ ```
242
+
243
+ The selected-row text colour
244
+ is deliberately unlayered: whatever colour a cell sets for itself (status colours, utility classes such as
245
+ Tailwind's `text-*`), selected text takes `--rdg-selected-fg` and never disappears into the selection
246
+ background. Change the colour through the variables.
247
+
248
+ ## Accessibility
249
+
250
+ `role="grid"` with `aria-rowcount` / `aria-colcount` (all rows, not just the rendered ones), `aria-multiselectable`,
251
+ `aria-readonly`; header `role="columnheader"` with `aria-sort`; rows `role="row"` with `aria-rowindex` and
252
+ `aria-selected` (row mode); cells `role="gridcell"` with `aria-colindex`, `aria-selected` (cell mode) and
253
+ `aria-readonly` (editable grids). The grid keeps the focus and points at the current cell with
254
+ `aria-activedescendant`, so screen readers follow it through virtualization.
255
+
256
+ ## Development
257
+
258
+ ```bash
259
+ npm install
260
+ npm test # vitest + Testing Library (jsdom)
261
+ npm run typecheck
262
+ npm run build # dist/: ES modules, .d.ts, styles.css
263
+ npm run format:check
264
+ ```
265
+
266
+ ## License
267
+
268
+ MIT
@@ -0,0 +1,11 @@
1
+ import { type ReactElement, type Ref } from 'react';
2
+ import type { DataGridHandle, DataGridProps } from './types';
3
+ export declare const defaultCompare: (a: unknown, b: unknown) => number;
4
+ /**
5
+ * Keyboard-first data grid: virtualized rows, row or cell selection with ranges, clipboard, in-place
6
+ * editing, sortable / resizable / reorderable / hideable / frozen columns. See README.
7
+ */
8
+ export declare const DataGrid: <T>(props: DataGridProps<T> & {
9
+ ref?: Ref<DataGridHandle>;
10
+ }) => ReactElement;
11
+ //# sourceMappingURL=DataGrid.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"DataGrid.d.ts","sourceRoot":"","sources":["../src/DataGrid.tsx"],"names":[],"mappings":"AAAA,OAAO,EAaL,KAAK,YAAY,EAGjB,KAAK,GAAG,EACT,MAAM,OAAO,CAAA;AA6Bd,OAAO,KAAK,EAMV,cAAc,EACd,aAAa,EAGd,MAAM,SAAS,CAAA;AAkChB,eAAO,MAAM,cAAc,MAAO,OAAO,KAAK,OAAO,KAAG,MAMvD,CAAA;AAs7BD;;;GAGG;AACH,eAAO,MAAM,QAAQ,EAAgC,CAAC,CAAC,EACrD,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAA;CAAE,KACpD,YAAY,CAAA"}