@jielga/tmdatagrid 2.0.0-beta.2 → 2.0.0-beta.21

package/skills/data/SKILL.md

@@ -6,21 +6,26 @@ description: >
   enablePagination, manualPagination), the Footer's renderPagination slot over {
   state, actions, Controls }, getTMDataGridPaginationApi, isPagingActive versus
   canPaginate, always-on virtualization with overscan and meta.rowHeight,
-  scrollToRow and scrollerRef, the edge callbacks onScrollToBottom /
-  onScrollToRight and why onReachEnd is better for loading more, the header and
-  pinned-lane depth shadows, and the four empty states in precedence order with
-  meta.loading, renderEmptyState, hasActiveFilters, TMDataGrid.LoadingIndicator
-  and TMDataGrid.SummaryCount. Load when adding a pager, tuning scrolling,
-  scrolling to a row, or deciding what an empty grid should say.
+  scrollToRow, the edge callbacks onScrollToBottom / onScrollToRight and why
+  onReachEnd is better for loading more, the header and pinned-lane depth
+  shadows, and the four empty states in precedence order with meta.loading,
+  renderEmptyState, hasActiveFilters, TMDataGrid.LoadingIndicator and
+  TMDataGrid.SummaryCount, and export: TMDataGrid.Menu.Export and
+  Menu.ExportSelected, useTMDataGridExport, exportGrid, exportOptions, the
+  csvExcel / csv / tsv / json formats, meta.exportValue and meta.enableExport.
+  Load when adding a pager, tuning scrolling, scrolling to a row, deciding what
+  an empty grid should say, or exporting rows to Excel or CSV.
 metadata:
   type: core
   library: '@jielga/tmdatagrid'
-  library_version: '2.0.0-beta.2'
+  library_version: '2.0.0-beta.21'
 sources:
-  - 'Jielga/TMDataGrid:src/docs/pagination.md'
-  - 'Jielga/TMDataGrid:src/docs/scrolling.md'
-  - 'Jielga/TMDataGrid:src/docs/loading-and-empty.md'
-  - 'Jielga/TMDataGrid:src/tmdatagrid/components/TMDataGridFooter.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/pagination.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/scrolling.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/loading-and-empty.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/docs/export.md'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/components/TMDataGridFooter.tsx'
+  - 'Jielga/TMDataGrid:packages/tmdatagrid/src/core/export.ts'
 ---
 
 # TMDataGrid - Pagination, scrolling and empty states
@@ -77,7 +82,10 @@ pieces, already wired.
 `Controls.PageSize`, `Controls.Range` and `Controls.Pager` are what the default
 footer renders, in that order, so a custom layout can keep the parts it wants
 instead of rebuilding them. They behave exactly as before, including greying out
-under a suspended pager.
+under a suspended pager. `Controls.PageNumber` - the "Page 3 of 200" label a
+server-paged grid usually shows in place of a row range - is a fourth control,
+not in the default footer; put it in through the slot rather than writing it by
+hand.
 
 `state` carries `pageIndex`, `pageSize`, `pageCount`, `rowCount`,
 `canPreviousPage`, `canNextPage`, `from`, `to` and `isPagingActive`. `actions`
@@ -118,8 +126,13 @@ grid.scrollToRow({ rowId: "42", align: "center" });
 
 `scrollToRow` exists because the target row may not be mounted, and
 `element.scrollIntoView()` cannot find an element that is not rendered. `align`
-is `"start"`, `"center"`, `"end"` or `"auto"`. `scrollerRef` is the scroll
-container itself.
+is `"start"`, `"center"`, `"end"` or `"auto"`. It answers whether the row could
+be reached: `false` when it is filtered out, on another page or an id matching
+no row, and a pinned row answers `true` without scrolling.
+
+The hook reaches the virtualizer through `scrollerRef`, which
+`TMDataGrid.Table` fills in. That is internal wiring, not an API - spread the
+whole grid object onto `<TMDataGrid>` or nothing scrolls.
 
 `TMDataGrid.Table` reports arrivals at each edge - `onScrollToTop`,
 `onScrollToBottom`, `onScrollToLeft`, `onScrollToRight` - firing **once** on
@@ -173,6 +186,71 @@ server-driven grid refetching with rows still on screen keeps showing them.
 total, where the total is `meta.totalRowCount` when provided and the pre-filtered
 count otherwise.
 
+## Export
+
+Every filtered and sorted row across every page, or the selected rows, as a
+file. The built-in entry points are menu items; a button of your own uses the
+hook.
+
+```tsx
+const grid = useTMDataGrid({
+  data,
+  columns,
+  exportOptions: { format: csvFormat(), fileName: "employees" },
+});
+
+<TMDataGrid.Menu>
+  <TMDataGrid.Menu.Export />
+  <TMDataGrid.Menu.ExportSelected />
+</TMDataGrid.Menu>
+```
+
+```tsx
+function ExportButton() {
+  const { exportAll, exportSelected, selectedCount, canExportSelected } =
+    useTMDataGridExport();
+  return <Button onClick={() => void exportAll()}>Export</Button>;
+}
+```
+
+What is written: the data columns in render order (never the generated lanes,
+never a column with `meta.enableExport: false`), every row after filtering and
+sorting (a grouped grid writes the records under every group, never the group
+rows), and each cell's **value** rather than what it renders -
+`meta.exportValue: ({ value, row, column }) => unknown` substitutes one.
+`columns` on `exportOptions`, the items and the functions is `"visible"` (the
+default), `"all"` (hidden columns too) or a list of ids; `columns="custom"` on
+a menu item opens a picker instead - every exportable column, the visible ones
+ticked, Export and Cancel - driven by `ui.state.exportPicker` and
+`ui.actions.openExportPicker`. `TMDataGrid.Menu.ExportSelected` counts and
+writes the ticked rows of the current view, in grid order; it renders nothing
+when row selection is off.
+
+Formats, each a `TMDataGridExportFormat` from a factory:
+
+| Factory | Writes |
+| --- | --- |
+| `csvExcelFormat()` (default) | BOM, `sep=;` line, CRLF, `;` fields, `,` decimal - opens straight into columns in Excel. `separator`, `decimalComma` for another locale. |
+| `csvFormat()` | RFC 4180: `,` fields, `.` decimal, BOM, no `sep=` line - for Google Sheets, Numbers and tooling. |
+| `tsvFormat()` | Tab-separated, the clipboard shape as a file. |
+| `jsonFormat()` | One object per row keyed by column label, numbers as numbers, dates as ISO strings. |
+| `xlsxFormat()` | Excel workbook, from the separate `@jielga/tmdatagrid-xlsx` package. |
+
+The text formats guard against formula injection by default: a value starting
+with `=`, `+`, `-` or `@` that is not a number is prefixed with `'`.
+`escapeFormulas: false` on the format turns that off.
+
+`exportGrid({ table, rows: "all" | "selected" | rows, options })` is the same
+export for code outside a component; `buildExportData` is the step before the
+file. A format of your own is `{ id, extension, mimeType, write(data, { includeHeaders }) }`
+returning a string, a `Blob`, or a promise of either.
+
+Deprecated for one beta: `exportGridToCsv`, the `cellExport` Table prop,
+`TMDataGridCellExportOptions`, `buildCellMatrix` / `buildGridCellMatrix`,
+`toExcelCsv`, `downloadTextFile`, `labels.exportCsv`.
+
+Source: `packages/tmdatagrid/docs/export.md`.
+
 ## Common mistakes
 
 ### CRITICAL Turning pagination on to make a large grid fast
@@ -181,7 +259,7 @@ Virtualization is already unconditional, so paging a 200 000-row grid changes
 nothing about rendering cost. It only changes how users navigate. Enable it when
 they should move page by page, not for performance.
 
-Source: `src/docs/pagination.md`, `src/docs/scrolling.md`.
+Source: `packages/tmdatagrid/docs/pagination.md`, `packages/tmdatagrid/docs/scrolling.md`.
 
 ### CRITICAL A variable row height
 
@@ -202,7 +280,7 @@ Correct:
 useTMDataGrid({ data, columns, meta: { rowHeight: 64 } });
 ```
 
-Source: `src/docs/scrolling.md` (Row height).
+Source: `packages/tmdatagrid/docs/scrolling.md` (Row height).
 
 ### HIGH `scrollIntoView` on a row that is not mounted
 
@@ -218,7 +296,7 @@ grid.scrollToRow({ rowId: "4000", align: "center" });
 `scrollToRow` returns `false` when the row is not in the current view (filtered
 out, on another page, or an id matching no row) and nothing scrolled.
 
-Source: `src/docs/scrolling.md` (Scrolling to a row).
+Source: `packages/tmdatagrid/docs/scrolling.md` (Scrolling to a row).
 
 ### HIGH Loading more rows from `onScrollToBottom`
 
@@ -226,7 +304,7 @@ It fires at the very bottom, so the user waits at the end of the list for the
 fetch. `onReachEnd` fires a number of rows earlier and latches per row count, so
 a pending fetch is not requested twice.
 
-Source: `src/docs/scrolling.md` (Edge callbacks).
+Source: `packages/tmdatagrid/docs/scrolling.md` (Edge callbacks).
 
 ### HIGH `SummaryCount` reporting the page under manual pagination
 
@@ -245,7 +323,7 @@ useTMDataGrid({
 });
 ```
 
-Source: `src/docs/loading-and-empty.md` (Counting what is there).
+Source: `packages/tmdatagrid/docs/loading-and-empty.md` (Counting what is there).
 
 ### MEDIUM Rendering an empty message while data is loading
 
@@ -259,7 +337,7 @@ Correct:
 useTMDataGrid({ data, columns, meta: { loading: isFetching } });
 ```
 
-Source: `src/docs/loading-and-empty.md` (What wins).
+Source: `packages/tmdatagrid/docs/loading-and-empty.md` (What wins).
 
 ### MEDIUM Trusting the pager while grouped
 
@@ -267,7 +345,7 @@ Source: `src/docs/loading-and-empty.md` (What wins).
 grid is rendering the whole tree. A custom pager must read
 `isPagingActive(table, features)` rather than the page count.
 
-Source: `src/docs/pagination.md` (Grouping suspends it).
+Source: `packages/tmdatagrid/docs/pagination.md` (Grouping suspends it).
 
 ## Reference
 
@@ -278,7 +356,7 @@ Source: `src/docs/pagination.md` (Grouping suspends it).
 | `rowCount` | Table option | `number` | – | The true total, required under `manualPagination`. |
 | `initialState.pagination` | Table option | `{ pageIndex, pageSize }` | `{ 0, 25 }` | Where paging starts. A `data` slice, so it persists. |
 | `onPaginationChange` | Table option | `OnChangeFn` | – | Controls the pagination state. |
-| `TMDataGrid.Footer` | Component | `pageSizeOptions`, `pagination` | `[10, 25, 50, 100]` | The footer bar. Renders nothing when paging is off. |
+| `TMDataGrid.Footer` | Component | `pageSizeOptions`, `renderPagination`, Mantine `BoxProps` | `[10, 25, 50, 100]` | The footer bar. Renders nothing when paging is off. Style props set on the bar. |
 | `Footer` `renderPagination` | Slot | `({ state, actions, Controls }) => ReactNode` | Built-in pager | Replaces the pager, and hands over its pieces. |
 | `getTMDataGridPaginationApi` | Export | `(table) => { state, actions }` | – | The pager API, outside the Footer. |
 | `TMDataGridPaginationState` · `TMDataGridPaginationActions` · `TMDataGridPaginationControls` | Exports | types | – | The three parts of the slot argument. |
@@ -286,7 +364,6 @@ Source: `src/docs/pagination.md` (Grouping suspends it).
 | `overscan` | Option | `number` | `6` | Rows kept mounted beyond each edge of the viewport. |
 | `meta.rowHeight` | Option | `number` | From `size` | Row height in pixels. The virtualizer needs a number. |
 | `scrollToRow` | Hook return | `({ rowId, align? }) => boolean` | `align: "auto"` | Scrolls a row into view, mounted or not. |
-| `scrollerRef` | Hook return | `RefObject<HTMLDivElement>` | – | The scroll container. |
 | `onScrollToTop` · `onScrollToBottom` · `onScrollToLeft` · `onScrollToRight` | Table props | `() => void` | – | Fire once on arriving at that edge. |
 | `TMDataGridScrollAlign` | Export | `"start" \| "center" \| "end" \| "auto"` | – | The `align` argument. |
 | `meta.loading` | Option | `boolean` | `false` | A fetch is in flight. Takes precedence over every empty message. |