react-glide-table 2.3.4 → 2.3.6

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/README.md CHANGED
@@ -104,7 +104,7 @@ Row-level UI → `slots.Row`. Cell content → `Column.render` or `Column.kind`.
104
104
  />
105
105
  ```
106
106
 
107
- `update` commits through `onCellChange` (preferred) or `onDataChange`. Prefer `update` over calling `setData` inside the render.
107
+ `update` commits through the same write callbacks as editing (see [Writing changes](#writing-changes)). Prefer `update` over calling `setData` inside the render.
108
108
 
109
109
  The same `update` is available on TanStack `ColumnDef.cell` when using `DataTable` directly (or `useGlideTable().getCellContext` with `flexRender`). Bare `cell.getContext()` does **not** include `update` at runtime — only the wrapped context does (`CellContextWithUpdate`).
110
110
 
@@ -133,6 +133,8 @@ Built-ins (DOM, inspired by [Glide All Cell Kinds](https://glideapps.github.io/g
133
133
 
134
134
  Priority: **column `render` > registry `kind` > default text**.
135
135
 
136
+ `protected` masks the value everywhere the table exposes it: the cell shows `****`, inline search skips the column, copy writes `****`, and the column is never editable or fill-able. It is still only a display mask: the raw value is in your `data`, so don't send real secrets to the browser. `uri` links allow only http(s)/mailto/relative URLs, and `image` / `drilldown` images only http(s)/blob/`data:image/*`/relative sources (`sanitizeUriHref`, `sanitizeImageSrc`).
137
+
136
138
  ```tsx
137
139
  const buttonRenderer = {
138
140
  kind: "my-button",
@@ -228,6 +230,50 @@ export function ProductTable({ data }: { data: Product[] }) {
228
230
 
229
231
  Wire `rowContextValue` into your own row/cell components for edit, selection, expand, and row-span behavior. Use `getCellContext(cell)` (not bare `cell.getContext()`) so `ColumnDef.cell` receives `update`.
230
232
 
233
+ ## Writing changes
234
+
235
+ Every write the table makes goes to the first callback you provide, in this order:
236
+
237
+ | Change | `onCellChange` | `onBatchChange` | `onDataChange` |
238
+ | ---------------------------------------- | -------------- | ---------------------- | ----------------------- |
239
+ | Double-click / Enter edit, render `update`, boolean checkbox | called once | one-item batch if no `onCellChange` | full patched `data` otherwise |
240
+ | Fill handle, Delete key | once per cell if no `onBatchChange` | called once | full patched `data` otherwise |
241
+ | Paste | – | – | – (use `onRowsPaste`) |
242
+
243
+ So any one of the three is enough for editing, fill, checkbox and Delete. `onDataChange` always receives the full original `data` (also for tree, sorted and paginated tables). Writes only reach `editable` columns that are not `kind: "protected"`; the fill handle is shown only when at least one column is editable and a write callback is set.
244
+
245
+ `kind: "boolean"` is the exception today: its checkbox writes unless `editable={false}`. The table warns once per column when `editable` is not set; a future major release will make it require `editable` like other cells.
246
+
247
+ ## Keyboard
248
+
249
+ Click a cell, or Tab to the table (which selects the first cell), then:
250
+
251
+ | Key | Behavior |
252
+ | --------------------------------- | ----------------------------------------------------------- |
253
+ | Arrows (W/A/S/D) | Move; with Shift, extend the selection |
254
+ | Home / End | First / last cell in the row (Ctrl/Cmd: first / last cell) |
255
+ | Ctrl/Cmd+A | Select every cell |
256
+ | Enter / F2 | Edit the active cell (`editable` columns) |
257
+ | Enter / Shift+Enter in the editor | Commit and move down / up |
258
+ | Tab / Shift+Tab in the editor | Commit and move right / left |
259
+ | Escape in the editor | Cancel |
260
+ | Delete / Backspace | Clear editable cells in the selection (writes `null`) |
261
+
262
+ Pressing anywhere outside the table hands the keyboard back to the page: arrows, Ctrl+C and the rest stop acting on the table until you click or Tab back into it. Ctrl+C also leaves the page alone when you have selected text outside the table. Set `enableWasdNavigation={false}` to keep W/A/S/D for typing or page shortcuts. A number editor with input the browser rejects stays open and gets `aria-invalid` instead of clearing the cell. Resize handles take focus and respond to ←/→ (Shift for larger steps).
263
+
264
+ ## Row selection
265
+
266
+ `rowSelectionMode="single" | "multi"` turns on row selection. With cell selection on (the default), clicking a cell selects the cell and does **not** toggle the row; use a `kind="row-select"` column for checkboxes. With `enableCellSelection={false}`, clicking a row toggles it unless `selectOnRowClick={false}`.
267
+
268
+ ```tsx
269
+ <ProductTable rowSelectionMode="multi">
270
+ <ProductTable.Header>
271
+ <ProductTable.Column field="select" virtual kind="row-select" />
272
+ <ProductTable.Column field="name">Name</ProductTable.Column>
273
+ </ProductTable.Header>
274
+ </ProductTable>
275
+ ```
276
+
231
277
  ## Clipboard copy & paste
232
278
 
233
279
  Cell selection ships with clipboard shortcuts. The table parses TSV and emits structured payloads; **your app applies domain conversion and updates data**.
@@ -284,7 +330,13 @@ import type { RowsPastePayload } from "react-glide-table/compound";
284
330
  </ProductTable>;
285
331
  ```
286
332
 
287
- Related props: `onRowsPaste`, `enableInsertPaste`, `enableSubtreeCopy`, `onCopyActionsReady`.
333
+ Set `escapeCopyFormulas` when the table shows data other users can write: copied cells that start with `=`, `+`, `-`, `@` get a leading `'` so Excel / Sheets paste them as text instead of running them as formulas (plain signed numbers like `-12.5` are left as-is).
334
+
335
+ The fill handle only writes into `editable` columns, the same rule as double-click editing.
336
+
337
+ `payload.editableColumnIds` lists the target columns the table itself would write (editable, not protected), so you can skip read-only columns the same way editing and fill do.
338
+
339
+ Related props: `onRowsPaste`, `enableInsertPaste`, `enableSubtreeCopy`, `escapeCopyFormulas`, `onCopyActionsReady`.
288
340
  Helpers (`/core`): `buildRowsPastePayload`, `parseClipboardTSV`, `parseClipboardTSVWithDepths`, `serializeSelectionToTSV`, …
289
341
 
290
342
  ## Column width
@@ -376,7 +428,7 @@ Helpers (`/core`): `applyLeafColumnOrder`, `moveColumnIds`, `collectLeafColumnId
376
428
 
377
429
  ## Column freeze
378
430
 
379
- Opt in with `enableColumnFreeze`. Mark columns with `frozen` — sticky insets are stacked so frozen cells never overlap, and **column order is unchanged** (middle columns may also freeze).
431
+ Opt in with `enableColumnFreeze`. Mark columns with `frozen` — sticky insets are stacked so frozen cells never overlap, and **column order is unchanged** (middle columns may also freeze). Columns without a `width` are measured after layout, so insets follow their real width.
380
432
 
381
433
  Keep vertical stickiness on the header via `classNames.head` (e.g. `sticky top-0`). Frozen header cells only stick horizontally (`left` / `right`); setting `top` on both `thead` and frozen `th` can detach the freeze band.
382
434
 
@@ -422,7 +474,7 @@ On tree tables (`toggleField`), search also scans **collapsed** descendants. Nav
422
474
 
423
475
  | Shortcut / control | Behavior |
424
476
  | ---------------------------- | ------------------------------ |
425
- | Ctrl/Cmd+F | Open (or focus) the search box |
477
+ | Ctrl/Cmd+F | Open (or focus) the search box once the table has been clicked or focused (until then the browser's find stays) |
426
478
  | Enter / ↓ | Next match |
427
479
  | Shift+Enter / ↑ | Previous match |
428
480
  | Escape / Ctrl+F (in box) / ✕ | Close |
@@ -433,11 +485,35 @@ On tree tables (`toggleField`), search also scans **collapsed** descendants. Nav
433
485
  | `showSearch` / `onSearchClose` | Controlled overlay visibility |
434
486
  | `searchValue` / `onSearchValueChange` | Controlled query |
435
487
  | `searchResults` / `onSearchResultsChanged` | Override / observe matches (`[colIndex, rowIndex]`) |
488
+ | `Column.searchValue` | `"value"` (default) / `"display"` (rendered text) / `(ctx) => string` |
489
+ | `labels.searchResultCount` | Status line text (`(status) => string`) |
436
490
  | `data-search-match` / `data-search-active` | Match highlight hooks on cells |
437
491
  | `classNames.search*` | Style the overlay |
438
492
 
439
493
  Helpers (`/core`): `useInlineSearch`, `collectSearchMatchesInRange`, `formatSearchResultLabel`, …
440
494
 
495
+ ## Sorting (compound `Table`)
496
+
497
+ `Table.Column sortable` adds a header button that cycles ascending → descending → unsorted, with `aria-sort` on the header. Sorting is uncontrolled by default; pass `sort` + `onSortChange` to control it (for example to sort on the server), or `defaultSort` for an initial order. `sortLocale` sets the string collation (default `"ko"`).
498
+
499
+ In a tree table (`toggleField` / `idField`), sorting reorders siblings and never moves a child out of its parent, and `Table.Pagination` pages by root rows (`pageSize` counts roots; each page shows its roots with their descendants). Nested `children` arrays keep their own order.
500
+
501
+ ## Tree tables
502
+
503
+ | Prop | Role |
504
+ | ----------------------------------------------------- | -------------------------------------------------------------------- |
505
+ | `idField` (alias of `toggleField`) | Row id field; turns tree mode on |
506
+ | `parentIdField` (alias of `childField`) | Field holding the parent row's id (flat data) |
507
+ | `childrenField` (alias of `flattenField`) | Nested children array field |
508
+ | `expandColumn` | Column id that shows the expand toggle |
509
+ | `expandedRows` / `onExpandedRowsChange` / `autoExpandOnLoad` | Controlled expansion / expand all once on load (default `true`) |
510
+
511
+ Tree rows carry `data-level` (0 = root) and the expand cell sets the `--table-row-level` CSS variable, so indentation can be styled per depth.
512
+
513
+ ## Styling notes
514
+
515
+ The selection outline reads the CSS variables `--color-brand-primary` (border) and `--color-brand-surface` (hides grid lines inside a merged selection). Define them in your styles; without them the outline is not drawn. The compound `Table` also takes `classNames.tableRoot` (outer wrapper) and `classNames.pagination`. `labels` covers the UI copy, including `count` (toolbar), `protectedCell`, `paginationPrevious` / `paginationNext` and `searchResultCount`.
516
+
441
517
  ## Public API
442
518
 
443
519
  | Export | Path | Role |