@jielga/tmdatagrid 1.0.1 → 1.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.
@@ -0,0 +1,302 @@
1
+ ---
2
+ name: data
3
+ description: >
4
+ How a TMDataGrid presents the rows it has: pagination, virtualization, and
5
+ having nothing to show. Covers the three pagination modes (off,
6
+ enablePagination, manualPagination), the Footer's renderPagination slot over {
7
+ state, actions, Controls }, getTMDataGridPaginationApi, isPagingActive versus
8
+ canPaginate, always-on virtualization with overscan and meta.rowHeight,
9
+ scrollToRow and scrollerRef, the edge callbacks onScrollToBottom /
10
+ onScrollToRight and why onReachEnd is better for loading more, the header and
11
+ pinned-lane depth shadows, and the four empty states in precedence order with
12
+ meta.loading, renderEmptyState, hasActiveFilters, TMDataGrid.LoadingIndicator
13
+ and TMDataGrid.SummaryCount. Load when adding a pager, tuning scrolling,
14
+ scrolling to a row, or deciding what an empty grid should say.
15
+ metadata:
16
+ type: core
17
+ library: '@jielga/tmdatagrid'
18
+ library_version: '1.1.0'
19
+ sources:
20
+ - 'Jielga/TMDataGrid:src/docs/pagination.md'
21
+ - 'Jielga/TMDataGrid:src/docs/scrolling.md'
22
+ - 'Jielga/TMDataGrid:src/docs/loading-and-empty.md'
23
+ - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGridFooter.tsx'
24
+ ---
25
+
26
+ # TMDataGrid - Pagination, scrolling and empty states
27
+
28
+ ## Pagination
29
+
30
+ **Off by default.** The grid renders every filtered and sorted row and relies on
31
+ virtualization, which handles any row count - so paging is a choice about how
32
+ the reader navigates, not a performance workaround. Three modes:
33
+
34
+ ```tsx
35
+ // 1. None (default). TMDataGrid.Footer renders nothing.
36
+ const grid = useTMDataGrid({ data, columns });
37
+
38
+ // 2. Client. The table pages, the Footer renders its pager.
39
+ const grid = useTMDataGrid({ data, columns, enablePagination: true });
40
+
41
+ // 3. Manual. The server pages; manualPagination implies enablePagination.
42
+ const grid = useTMDataGrid({
43
+ data: page.rows,
44
+ columns,
45
+ manualPagination: true,
46
+ rowCount: page.total,
47
+ state: { pagination },
48
+ onPaginationChange: setPagination,
49
+ });
50
+ ```
51
+
52
+ Initial page size is 25, through `initialState.pagination`. `enablePagination`
53
+ is one of the two switches the grid defines itself, and the one switch that
54
+ defaults to off.
55
+
56
+ `TMDataGrid.Footer` takes a `renderPagination` slot handed three things: the
57
+ `state` the pager shows, the `actions` it can take, and `Controls` - the
58
+ built-in pieces, already wired.
59
+
60
+ ```tsx
61
+ <TMDataGrid.Footer
62
+ renderPagination={({ state, actions, Controls }) => (
63
+ <Group>
64
+ <Controls.PageSize />
65
+ <Button onClick={actions.previousPage} disabled={!state.canPreviousPage}>
66
+ Back
67
+ </Button>
68
+ <Text>
69
+ {state.pageIndex + 1} / {state.pageCount}
70
+ </Text>
71
+ <Controls.Pager />
72
+ </Group>
73
+ )}
74
+ />
75
+ ```
76
+
77
+ `Controls.PageSize`, `Controls.Range` and `Controls.Pager` are exactly what the
78
+ default footer renders, in that order - so a custom layout keeps the parts it
79
+ likes rather than rebuilding them to look the same, greying out under a
80
+ suspended pager included.
81
+
82
+ `state` carries `pageIndex`, `pageSize`, `pageCount`, `rowCount`,
83
+ `canPreviousPage`, `canNextPage`, `from`, `to` and `isPagingActive`. `actions`
84
+ carries `setPageIndex`, `setPageSize`, `previousPage`, `nextPage`, `firstPage`
85
+ and `lastPage`. `getTMDataGridPaginationApi(table)` returns the same
86
+ `{ state, actions }` outside the Footer; `Controls` are bound to the grid
87
+ context, so they exist only inside the slot.
88
+
89
+ Grouping suspends the pager and wins: it greys out and the range becomes
90
+ `Grouped · all N rows`. `isPagingActive(table, features)` is the live state -
91
+ whether the pager is slicing anything right now - while
92
+ `getGridCapabilities(...).canPaginate` is the configuration. The two differ
93
+ exactly while a grouping is active.
94
+
95
+ ## Scrolling
96
+
97
+ Virtualization is **always on**. There is no flag, no threshold and no "enable
98
+ for large data sets": only the rows within the viewport plus a small overscan
99
+ are ever mounted.
100
+
101
+ `overscan` (default `6`) is the one knob - raise it if a fast scroll flashes
102
+ blank rows, lower it when rows are expensive. Row height comes from
103
+ `meta.rowHeight`, or from `size` when that is not set, and rows are **fixed
104
+ height**, so the virtualizer's estimate is exact and the scrollbar is honest.
105
+ Row details are the exception: a row showing a panel is measured after it
106
+ mounts.
107
+
108
+ ```tsx
109
+ const grid = useTMDataGrid({
110
+ data,
111
+ columns,
112
+ getRowId: (row) => String(row.id),
113
+ overscan: 12,
114
+ meta: { rowHeight: 64 },
115
+ });
116
+
117
+ grid.scrollToRow({ rowId: "42", align: "center" });
118
+ ```
119
+
120
+ `scrollToRow` exists because the row may not be mounted, which is exactly what
121
+ `element.scrollIntoView()` cannot handle. `align` is `"start"`, `"center"`,
122
+ `"end"` or `"auto"`. `scrollerRef` is the scroll container itself.
123
+
124
+ `TMDataGrid.Table` reports arrivals at each edge - `onScrollToTop`,
125
+ `onScrollToBottom`, `onScrollToLeft`, `onScrollToRight` - firing **once** on
126
+ arrival rather than on every scroll event. For loading more rows prefer
127
+ `onReachEnd` (the `server-side` skill): it fires rows early rather than at the
128
+ very bottom, and latches per row count so a pending fetch is never asked twice.
129
+
130
+ Two depth cues are scroll-driven animations on the compositor, with no scroll
131
+ listener and no React render: a shadow under the sticky header once rows scroll
132
+ beneath it, and a band beside a pinned lane while it is actually covering
133
+ something.
134
+
135
+ ## Empty states
136
+
137
+ There are four ways to have nothing to show, and an empty body shows exactly one
138
+ of them, in this order:
139
+
140
+ 1. **Loading** - `meta.loading` is true: a centred loader. A grid that is
141
+ fetching never claims to be empty.
142
+ 2. **Entry rows** - an open entry row from `edit.addRow()`: only the entry
143
+ block, with no message competing with the form.
144
+ 3. **`renderEmptyState`** - your node, centred where the message would be.
145
+ 4. **Filtered-empty** - a filter or search is active: `labels.noResults`,
146
+ because this emptiness is the reader's own doing.
147
+ 5. **Truly-empty** - no data at all: `labels.noRows`.
148
+
149
+ `renderEmptyState` replaces the last two with one render prop, and
150
+ `hasActiveFilters` says which it is standing in for:
151
+
152
+ ```tsx
153
+ <TMDataGrid.Table<Employee>
154
+ renderEmptyState={({ hasActiveFilters, table }) =>
155
+ hasActiveFilters ? (
156
+ <Button variant="light" onClick={() => table.resetColumnFilters()}>
157
+ Clear filters
158
+ </Button>
159
+ ) : (
160
+ <Button onClick={openCreateModal}>Add the first employee</Button>
161
+ )
162
+ }
163
+ />
164
+ ```
165
+
166
+ An empty grid is where a reader is most likely to be stuck, so it is worth
167
+ giving them the action that unsticks them.
168
+
169
+ The body's loading state only appears while the grid is **empty**. A
170
+ server-driven grid refetching with rows still on screen keeps showing them;
171
+ `TMDataGrid.LoadingIndicator` is the signal for that case, a small spinner while
172
+ `meta.loading` is true. `TMDataGrid.SummaryCount` shows visible rows out of
173
+ total, where the total is `meta.totalRowCount` when provided and the pre-filtered
174
+ count otherwise.
175
+
176
+ ## Common mistakes
177
+
178
+ ### CRITICAL Turning pagination on to make a large grid fast
179
+
180
+ Virtualization is already unconditional, so paging a 200 000-row grid changes
181
+ nothing about rendering cost - it only takes navigation away from the reader.
182
+ Reach for it when the reader should move page by page, not for performance.
183
+
184
+ Source: `src/docs/pagination.md`, `src/docs/scrolling.md`.
185
+
186
+ ### CRITICAL A variable row height
187
+
188
+ The virtualizer needs one number, and rows are fixed height so the scrollbar
189
+ stays honest. Styling a taller row through CSS leaves the measurement and the
190
+ render disagreeing: rows overlap or gaps open as you scroll, and the effect
191
+ depends on scroll position, so it looks intermittent.
192
+
193
+ Wrong:
194
+
195
+ ```css
196
+ [data-dg-part="row"] { height: 64px; }
197
+ ```
198
+
199
+ Correct:
200
+
201
+ ```tsx
202
+ useTMDataGrid({ data, columns, meta: { rowHeight: 64 } });
203
+ ```
204
+
205
+ Source: `src/docs/scrolling.md` (Row height).
206
+
207
+ ### HIGH `scrollIntoView` on a row that is not mounted
208
+
209
+ Only the viewport's rows exist in the DOM, so a query for row 4 000 returns
210
+ nothing and the call silently does nothing.
211
+
212
+ Correct:
213
+
214
+ ```tsx
215
+ grid.scrollToRow({ rowId: "4000", align: "center" });
216
+ ```
217
+
218
+ `scrollToRow` returns `false` when the row is not in the current view - filtered
219
+ out, on another page, or an id matching no row - and nothing scrolled.
220
+
221
+ Source: `src/docs/scrolling.md` (Scrolling to a row).
222
+
223
+ ### HIGH Loading more rows from `onScrollToBottom`
224
+
225
+ It fires at the very bottom, so the reader waits at the end of the list for the
226
+ fetch. `onReachEnd` fires rows early and latches per row count, so a pending
227
+ fetch is never asked twice.
228
+
229
+ Source: `src/docs/scrolling.md` (Edge callbacks).
230
+
231
+ ### HIGH `SummaryCount` reporting the page under manual pagination
232
+
233
+ The client only holds one page, so without `meta.totalRowCount` the total is
234
+ whatever arrived. It shows "25 of 25" over a table of thousands.
235
+
236
+ Correct:
237
+
238
+ ```tsx
239
+ useTMDataGrid({
240
+ data: page.rows,
241
+ columns,
242
+ manualPagination: true,
243
+ rowCount: page.total,
244
+ meta: { totalRowCount: page.total },
245
+ });
246
+ ```
247
+
248
+ Source: `src/docs/loading-and-empty.md` (Counting what is there).
249
+
250
+ ### MEDIUM Rendering an empty message while data is loading
251
+
252
+ The order exists so a fetching grid never claims to be empty. A hand-rolled
253
+ `data.length === 0 ? <Empty /> : <Grid />` outside the grid flashes "No rows to
254
+ show" on every load.
255
+
256
+ Correct:
257
+
258
+ ```tsx
259
+ useTMDataGrid({ data, columns, meta: { loading: isFetching } });
260
+ ```
261
+
262
+ Source: `src/docs/loading-and-empty.md` (What wins).
263
+
264
+ ### MEDIUM Trusting the pager while grouped
265
+
266
+ `getPageCount()` still returns a number, but the pager is greyed out and the
267
+ grid is rendering the whole tree. A custom pager must read
268
+ `isPagingActive(table, features)` rather than the page count.
269
+
270
+ Source: `src/docs/pagination.md` (Grouping suspends it).
271
+
272
+ ## Reference
273
+
274
+ | Name | Kind | Type | Default | What it does |
275
+ | --- | --- | --- | --- | --- |
276
+ | `enablePagination` | Option | `boolean` | `false` | Client-side paging and the Footer's pager. Grid-defined. |
277
+ | `manualPagination` | Table option | `boolean` | `false` | The server pages. Implies `enablePagination`. |
278
+ | `rowCount` | Table option | `number` | – | The true total, required under `manualPagination`. |
279
+ | `initialState.pagination` | Table option | `{ pageIndex, pageSize }` | `{ 0, 25 }` | Where paging starts. A `data` slice, so it persists. |
280
+ | `onPaginationChange` | Table option | `OnChangeFn` | – | Controls the pagination state. |
281
+ | `TMDataGrid.Footer` | Component | `pageSizeOptions`, `pagination` | `[10, 25, 50, 100]` | The footer bar. Renders nothing when paging is off. |
282
+ | `Footer` `renderPagination` | Slot | `({ state, actions, Controls }) => ReactNode` | Built-in pager | Replaces the pager, and hands over its pieces. |
283
+ | `getTMDataGridPaginationApi` | Export | `(table) => { state, actions }` | – | The pager API, outside the Footer. |
284
+ | `TMDataGridPaginationState` · `TMDataGridPaginationActions` · `TMDataGridPaginationControls` | Exports | types | – | The three halves of the slot argument. |
285
+ | `isPagingActive` | Export | `(table, features) => boolean` | – | Whether the pager is slicing anything right now. |
286
+ | `overscan` | Option | `number` | `6` | Rows kept mounted beyond each edge of the viewport. |
287
+ | `meta.rowHeight` | Option | `number` | From `size` | Row height in pixels. The virtualizer needs a number. |
288
+ | `scrollToRow` | Hook return | `({ rowId, align? }) => boolean` | `align: "auto"` | Scrolls a row into view, mounted or not. |
289
+ | `scrollerRef` | Hook return | `RefObject<HTMLDivElement>` | – | The scroll container. |
290
+ | `onScrollToTop` · `onScrollToBottom` · `onScrollToLeft` · `onScrollToRight` | Table props | `() => void` | – | Fire once on arriving at that edge. |
291
+ | `TMDataGridScrollAlign` | Export | `"start" \| "center" \| "end" \| "auto"` | – | The `align` argument. |
292
+ | `meta.loading` | Option | `boolean` | `false` | A fetch is in flight. Outranks every empty message. |
293
+ | `meta.noResultsLabel` | Option | `string` | `labels.noResults` | The filtered-empty message, without a render prop. |
294
+ | `meta.totalRowCount` | Option | `number` | Pre-filtered count | The total `SummaryCount` reports. |
295
+ | `renderEmptyState` | Table prop | `({ hasActiveFilters, table }) => ReactNode` | – | Replaces both built-in empty messages. |
296
+ | `TMDataGrid.LoadingIndicator` | Component | – | – | Spinner while `meta.loading`, for when the body has rows. |
297
+ | `TMDataGrid.SummaryCount` | Component | `children` replaces the text | – | Visible rows out of total. |
298
+ | `--dg-header-shadow-color` | CSS variable | colour | Themed | The shadow under the sticky header. |
299
+ | `--dg-sticky-edge-range` | CSS variable | length | `20px` | How far the pinned-lane band takes to fade in. |
300
+
301
+ See also: the `server-side` skill for `manualPagination` and `onReachEnd`, and
302
+ the `grouping` skill for why the pager suspends.