@jielga/tmdatagrid 0.1.0

package/skills/options/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: options
+description: >
+  useTMDataGrid options, return value and state persistence. Covers passthrough
+  of TanStack TableOptions, the default initialState (pagination, columnPinning,
+  globalFilterFn), the meta object (loading, noResultsLabel, rowHeight,
+  totalRowCount), the grid's own persist and enableColumnOrdering options, the
+  persist option with dataKey/settingsKey slice selection and storageMode, the
+  returned table/ui/features triple, ui panel and column drag actions, and
+  reading grid state with useSelector. Load when configuring the hook,
+  persisting column layout or filters, or reacting to grid state from a parent.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid'
+  library_version: '0.1.0'
+sources:
+  - 'Jielga/TMDataGrid:src/docs/use-tm-data-grid.md'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/persistence.ts'
+---
+
+# TMDataGrid — useTMDataGrid
+
+Creates the table instance and the state used by the grid interface.
+
+```tsx
+const grid = useTMDataGrid<TData>(options);
+// { table, ui, features }
+```
+
+Spread the result onto `TMDataGrid`.
+
+## Options
+
+All TanStack `TableOptions` are supported and passed through unchanged, including
+`data`, `columns`, `getRowId`, `state`, the `onXChange` callbacks, the `manual*`
+flags and `rowCount`. The `features` option is supplied internally and cannot be
+overridden.
+
+`persist` and `enableColumnOrdering` are the grid's own options and are consumed
+by the hook rather than forwarded to TanStack.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `TData[]` | – | Row data. Keep the reference stable with `useMemo`. |
+| `columns` | `ColumnDef[]` | – | Created with `createTMDataGridColumnHelper`. |
+| `getRowId` | `(row, index) => string` | Row index | Used by row selection and virtualization. |
+| `enableRowSelection` | `boolean \| (row) => boolean` | `true` | `false` removes the checkbox column. |
+| `enableSorting` | `boolean` | `true` | Enables sorting for the table. |
+| `enableColumnFilters` | `boolean` | `true` | Enables filtering for the table. |
+| `enableHiding` | `boolean` | `true` | Enables column visibility for the table. |
+| `enableColumnPinning` | `boolean` | `true` | Enables pinning for the table. |
+| `enableColumnResizing` | `boolean` | `true` | Enables resizing for the table. |
+| `enableColumnOrdering` | `boolean` | `true` | Enables header dragging and the move menu items. Defined by the grid. |
+| `columnResizeMode` | `"onChange" \| "onEnd"` | `"onChange"` | Resize update strategy. |
+| `initialState` | `Partial<TableState>` | See below | Merged over the grid defaults. |
+| `meta` | `TMDataGridTableMeta` | `{}` | Grid configuration, see below. |
+| `persist` | `TMDataGridPersistence` | – | State persistence, see below. |
+
+### Default initial state
+
+| Slice | Default |
+| --- | --- |
+| `pagination` | `{ pageIndex: 0, pageSize: 25 }` |
+| `columnPinning.left` | The checkbox column, followed by any columns you provide |
+| `globalFilterFn` | `"includesString"` |
+
+## meta
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `loading` | `boolean` | – | Displays a loader instead of the empty state. |
+| `noResultsLabel` | `string` | `"No rows match your filters"` | Empty state text. |
+| `rowHeight` | `number` | From `size` | Row height in px. Overrides the size scale. |
+| `totalRowCount` | `number` | – | Unfiltered total used by `SummaryCount`. Required for server-side data. |
+
+## persist
+
+Restores table state on mount and writes it back on every change. State is split
+across two keys because the groups have different lifetimes: column configuration
+stays valid indefinitely, while filters and pagination go stale as the data
+changes. Separate keys let one group be cleared without touching the other.
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `dataKey` | `string \| [string, DataSlice[]]` | – | Storage key for the data group. |
+| `settingsKey` | `string \| [string, SettingsSlice[]]` | – | Storage key for the settings group. |
+| `storageMode` | `"localStorage" \| "sessionStorage"` | `"localStorage"` | Storage area. |
+| `serialize` | `(value) => string` | `JSON.stringify` | Serializes before storing. |
+| `deserialize` | `(value: string) => unknown` | `JSON.parse` | Parses a stored payload. |
+
+Both keys are optional.
+
+```tsx
+import type { TMDataGridPersistence } from "@jielga/tmdatagrid";
+
+// Module scope: the object is a dependency of the write subscription.
+const persist = {
+  dataKey: "employees.data",
+  settingsKey: "employees.settings",
+} satisfies TMDataGridPersistence;
+
+const grid = useTMDataGrid({ data, columns, persist });
+```
+
+### Selecting slices
+
+A bare key persists every slice in its group. Pass `[key, slices]` for a subset:
+
+```tsx
+const persist = {
+  // Restore filters and sorting, but always start on the first page.
+  dataKey: ["employees.data", ["columnFilters", "sorting"]],
+  // Restore column layout but not widths.
+  settingsKey: ["employees.settings", ["columnVisibility", "columnOrder"]],
+  storageMode: "sessionStorage",
+} satisfies TMDataGridPersistence;
+```
+
+| Group | Available slices |
+| --- | --- |
+| `dataKey` | `columnFilters`, `globalFilter`, `sorting`, `pagination` |
+| `settingsKey` | `columnVisibility`, `columnSizing`, `columnOrder`, `columnPinning` |
+
+`DATA_STATE_SLICES` and `SETTINGS_STATE_SLICES` export the same values. Slice
+names are typed per group, so only valid names are accepted.
+
+Restoring happens once on mount through `initialState`. Writing is a subscription
+to the table store, so state changed directly through the table API is persisted
+too. Only selected slices are read back, and unrecognised keys are ignored. All
+storage access is guarded — if storage is unavailable, disabled or full,
+persistence is skipped rather than throwing.
+
+## Return value
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `table` | `Table<TMDataGridFeatures, TData>` | The TanStack table instance. |
+| `ui` | `Store<TMDataGridUiState, TMDataGridUiActions>` | State of the filter and column panels. |
+| `features` | `TMDataGridFeatureFlags` | Table-level feature switches, re-read on each render. |
+
+Both stores are subscribable, which is how a parent reacts to grid state without
+owning it:
+
+```tsx
+import { useSelector } from "@tanstack/react-store";
+
+const selectedCount = useSelector(
+  grid.table.store,
+  (state) => Object.keys(state.rowSelection).length,
+);
+
+const filterPanelOpen = useSelector(grid.ui, (state) => state.filterPanelOpen);
+```
+
+### ui actions
+
+| Action | Signature |
+| --- | --- |
+| `openFilterPanel` | `(columnId?: string \| null) => void` |
+| `closeFilterPanel` | `() => void` |
+| `setColumnsPanelOpen` | `(open: boolean) => void` |
+| `toggleColumnsPanel` | `() => void` |
+| `startColumnDrag` | `(columnId: string) => void` |
+| `endColumnDrag` | `() => void` |
+
+The last two are called by the header cells while a column is being dragged, and
+`ui.draggedColumnId` holds the column being moved — browsers keep `dataTransfer`
+unreadable until the drop.
+
+`openColumnFilter(grid, columnId)` combines the two steps the column menu uses:
+add an empty filter row for the column if none exists, then open the panel.
+
+## Common mistakes
+
+### Reading store state during render
+
+`grid.table.store.state` is a plain read — it does not subscribe the component,
+so the value is correct on first render and then never updates.
+
+```tsx
+// Wrong — never re-renders when the selection changes.
+const count = Object.keys(grid.table.store.state.rowSelection).length;
+
+// Right.
+const count = useSelector(
+  grid.table.store,
+  (state) => Object.keys(state.rowSelection).length,
+);
+```
+
+### persist object built during render
+
+The object is a dependency of the write subscription. A fresh literal on every
+render tears down and re-establishes the subscription each time. Define it at
+module scope, or `useMemo` it if the keys depend on props.
+
+### Unnamespaced storage keys
+
+Storage keys are not namespaced automatically. Where several users can share a
+browser profile, one user's column layout and filters are restored for the next.
+Include a tenant or user identifier in the key.
+
+### Unstable data reference
+
+A new array identity on each render re-runs the row model. `data={rows ?? []}`
+allocates a fresh `[]` every render when `rows` is undefined — hoist the empty
+array to a module-scope constant or `useMemo` the expression.

package/skills/server-side/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: server-side
+description: >
+  Drive TMDataGrid from a server with TanStack manual modes — manualPagination,
+  manualSorting, manualFiltering, rowCount, controlled state and onXChange
+  callbacks. Covers the loading and totalRowCount meta fields, forwarding the
+  plain-JSON columnFilters model to an API with isFilterActive, persistence
+  interaction, and row selection across pages. Load when the grid is backed by a
+  paginated API rather than a local array.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid'
+  library_version: '0.1.0'
+sources:
+  - 'Jielga/TMDataGrid:src/docs/server-side.md'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/useTMDataGrid.tsx'
+---
+
+# TMDataGrid — Server-side data
+
+The grid reads rows through `getPaginatedRowModel()` and totals through
+`getRowCount()` and `getPageCount()`, all of which respect TanStack's manual
+modes. A server-driven grid therefore needs only the standard `manual*`
+configuration — no grid-specific options.
+
+## Setup
+
+```tsx
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import { useState } from "react";
+import { TMDataGrid, useTMDataGrid } from "@jielga/tmdatagrid";
+
+const [pagination, setPagination] = useState({ pageIndex: 0, pageSize: 25 });
+const [sorting, setSorting] = useState([]);
+const [columnFilters, setColumnFilters] = useState([]);
+
+const { data, isFetching } = useQuery({
+  queryKey: ["employees", pagination, sorting, columnFilters],
+  queryFn: () => fetchEmployees({ pagination, sorting, columnFilters }),
+  placeholderData: keepPreviousData,
+});
+
+const grid = useTMDataGrid({
+  columns,
+  data: data?.rows ?? [],
+  getRowId: (row) => String(row.id),
+
+  manualPagination: true,
+  manualSorting: true,
+  manualFiltering: true,
+  rowCount: data?.total ?? 0,
+
+  state: { pagination, sorting, columnFilters },
+  onPaginationChange: setPagination,
+  onSortingChange: setSorting,
+  onColumnFiltersChange: setColumnFilters,
+
+  meta: { loading: isFetching, totalRowCount: data?.totalUnfiltered },
+});
+```
+
+## Differences from client-side data
+
+| Concern | Client-side | Server-side |
+| --- | --- | --- |
+| Rendered rows | The current page, sliced locally | The rows returned by the server |
+| Footer total | Pre-paginated row count | `options.rowCount` |
+| `SummaryCount` total | Pre-filtered row count | `meta.totalRowCount` |
+| Loading state | Not applicable | `meta.loading` |
+
+Column menus, the filter panel and the column manager behave identically in both
+modes.
+
+## Sending filters
+
+Filter values are plain JSON, so `columnFilters` forwards without transformation:
+
+```json
+[
+  { "id": "lastName", "value": { "operator": "contains", "value": "holm" } },
+  { "id": "age", "value": { "operator": "greaterThan", "value": "30" } }
+]
+```
+
+Translate at the API boundary, and skip entries whose value is still empty —
+those match all rows:
+
+```ts
+import { isFilterActive } from "@jielga/tmdatagrid";
+
+const active = columnFilters.filter((filter) => isFilterActive(filter.value));
+```
+
+Debounce requests. The filter value input updates on every keystroke.
+
+## Persistence
+
+`persist` works unchanged. `dataKey` restores filters, sorting and pagination
+before the first request, so reloading repeats the query the user last ran.
+
+If the same state is also held in your own `useState`, initialise it from the
+same source or let the grid own it. Do not maintain both independently.
+
+## Row selection
+
+Selection is keyed by `getRowId`, so ids must be stable across pages. Under
+`manualPagination`, rows selected on an earlier page stay in `rowSelection` even
+though they are no longer mounted. Read the state, not the row models:
+
+```ts
+import { useSelector } from "@tanstack/react-store";
+
+const selectedIds = useSelector(grid.table.store, (state) =>
+  Object.keys(state.rowSelection),
+);
+```
+
+## Common mistakes
+
+### Omitting rowCount under manualPagination
+
+Without `rowCount` the table derives the total from the rows it was handed —
+one page — so `getPageCount()` returns 1. The footer shows "1–25 of 25" and the
+next-page button is disabled, with no error. Pass the server total.
+
+### Filters sent without isFilterActive
+
+An empty filter value stays in `columnFilters` while the user is still typing.
+Forwarded verbatim it becomes `operator: "contains", value: ""` at the API,
+which most backends translate into a real predicate. Filter with
+`isFilterActive` first.
+
+### SummaryCount without meta.totalRowCount
+
+`SummaryCount` falls back to the pre-filtered row count, which under manual
+filtering is just the current page. It reads "25 of 25" regardless of how many
+rows the server holds. Pass the unfiltered total as `meta.totalRowCount`.
+
+### Unstable getRowId across pages
+
+Defaulting to the row index means row 0 of page 2 shares an id with row 0 of
+page 1, so paging silently transfers the selection to different records. Always
+set `getRowId` from a stable primary key when paginating on the server.
+
+### Duplicating grid state in local state
+
+Holding `pagination` in `useState` *and* letting `persist.dataKey` restore it
+gives two sources of truth: the grid restores the stored page while `useState`
+starts at 0, and the first query runs for the wrong page. Initialise the local
+state from the same store, or drop `pagination` from the persisted slices.