@jielga/tmdatagrid 0.1.0

package/skills/columns/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: columns
+description: >
+  Define TMDataGrid columns with createTMDataGridColumnHelper: column meta
+  (label, type, flex, align, enableOrdering), fluid minmax sizing versus fixed
+  width, minSize and maxSize, per-column
+  enableSorting/enableColumnFilter/enableHiding/enablePinning/ enableResizing,
+  the generated SELECT_COLUMN_ID checkbox column, and the shared filter function
+  with its operator list and isFilterActive. Load when adding or changing
+  columns, controlling widths, or wiring column filters.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid'
+  library_version: '0.1.0'
+sources:
+  - 'Jielga/TMDataGrid:src/docs/columns.md'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/filterOperators.ts'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/columnUtils.ts'
+---
+
+# TMDataGrid — Columns
+
+`createTMDataGridColumnHelper<TData>()` returns a TanStack column helper bound to
+the grid feature set, which gives `meta` and `filterFn` their correct types.
+
+```tsx
+import { createTMDataGridColumnHelper } from "@jielga/tmdatagrid";
+
+const columnHelper = createTMDataGridColumnHelper<Employee>();
+
+const columns = columnHelper.columns([
+  columnHelper.accessor("salary", {
+    header: "Salary",
+    minSize: 130,
+    meta: { type: "number", align: "right" },
+    cell: (info) => formatSek(info.getValue()),
+  }),
+  columnHelper.accessor((row) => `${row.firstName} ${row.lastName}`, {
+    id: "fullName",
+    header: "Full name",
+    meta: { label: "Full name" },
+  }),
+]);
+```
+
+Define columns at module scope. A new array on every render rebuilds the table's
+column model.
+
+## meta
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` | String header, or column id | Name used in menus and the column manager. Required when `header` is a component. |
+| `type` | `"string" \| "number"` | `"string"` | Determines which filter operators are offered. |
+| `flex` | `number` | `1` | Share of the remaining width. |
+| `align` | `"left" \| "right" \| "center"` | `"left"` | Applied to both header and cells. |
+| `enableOrdering` | `boolean` | `true` | `false` keeps the column where it is. |
+
+`enableOrdering` lives in `meta` because column ordering is the one feature
+TanStack defines no column option for. See the `features` skill.
+
+## Sizing
+
+Columns are fluid. Each track is `minmax(minSize, flex fr)`.
+
+| Option | Effect |
+| --- | --- |
+| `minSize` | Minimum width, and the column's contribution to the grid minimum width. Defaults to `80`. |
+| `meta.flex` | Share of the remaining width. |
+| `minSize === maxSize` | Fixed width. The column is never fluid. |
+| `size` | Applied once the column becomes fixed by resizing or pinning. |
+
+A column switches to a fixed pixel width when resized or pinned. Pinning requires
+it because sticky offsets are calculated from `getSize()`, which cannot resolve
+an `fr` value. The grid stores the column's rendered width in `columnSizing` at
+the moment it is pinned, so its width does not change.
+
+```tsx
+// Fixed 64px action column that never flexes.
+columnHelper.display({
+  id: "actions",
+  minSize: 64,
+  maxSize: 64,
+  cell: (info) => <RowMenu id={info.row.original.id} />,
+});
+```
+
+## Column-level feature options
+
+Standard TanStack column options. Each also removes the corresponding interface.
+
+| Option | Effect when `false` |
+| --- | --- |
+| `enableSorting` | No sort indicator and no sort menu items. |
+| `enableColumnFilter` | No filter menu item. Excluded from the filter panel column list. |
+| `enableHiding` | No hide menu item. Checkbox disabled in the column manager. |
+| `enablePinning` | No pin menu items. |
+| `enableResizing` | The divider is displayed but cannot be dragged. |
+
+`meta.enableOrdering: false` belongs to the same set and removes the column's
+header dragging and move menu items. A column inside a header group is never
+movable whatever it says, because `columnOrder` sequences leaf columns.
+
+A column whose menu has no remaining items renders no menu button.
+
+## Checkbox column
+
+Unless `enableRowSelection` is `false`, a column with the id `SELECT_COLUMN_ID`
+is added as the first column and pinned to the left. It is listed as "Checkbox
+selection" in the column manager and can be hidden like any other column. It has
+no column menu and cannot be sorted, filtered, resized, re-pinned or moved.
+
+Because it cannot be moved, it also anchors the left pinned region: no column
+can be placed in front of it.
+
+## Filtering
+
+All columns share one filter function. The operator lives in the filter value
+rather than being selected through `filterFn`:
+
+```ts
+type TMDataGridFilterValue = {
+  operator: TMDataGridFilterOperator;
+  value: string;
+};
+```
+
+The filter model is therefore plain JSON and can be forwarded to a server without
+transformation. See the `server-side` skill.
+
+### Operators
+
+| Operator | Label | Column type |
+| --- | --- | --- |
+| `contains` | contains | `string` |
+| `equals` | equals | `string`, `number` |
+| `notEquals` | does not equal | `string`, `number` |
+| `startsWith` | starts with | `string` |
+| `endsWith` | ends with | `string` |
+| `greaterThan` | is greater than | `number` |
+| `greaterThanOrEqual` | is greater than or equal to | `number` |
+| `lessThan` | is less than | `number` |
+| `lessThanOrEqual` | is less than or equal to | `number` |
+| `isEmpty` | is empty | `string`, `number` |
+| `isNotEmpty` | is not empty | `string`, `number` |
+
+`meta.type` selects the list. String comparisons are case-insensitive.
+`FILTER_OPERATOR_LABELS` maps operators to their labels.
+
+To give a column its own matching logic, set `filterFn` on the column definition.
+The grid only provides `"tmDataGrid"` as the default.
+
+## Common mistakes
+
+### Component header without meta.label
+
+`getColumnLabel(column)` falls back to a *string* header, then the column id.
+When `header` is a component there is no string to fall back to, so the column
+manager and column menus show the raw id (`"fullName"`) instead of a name.
+
+```tsx
+// Wrong — menus show "fullName".
+columnHelper.accessor("fullName", { header: () => <Icon /> });
+
+// Right.
+columnHelper.accessor("fullName", {
+  header: () => <Icon />,
+  meta: { label: "Full name" },
+});
+```
+
+### Treating an empty filter as no filter
+
+A filter with an empty value stays in state so the panel keeps showing its row
+while the user types. It matches all rows and does not light up the header
+indicator. Test with `isFilterActive(value)` rather than checking for presence:
+
+```ts
+import { isFilterActive } from "@jielga/tmdatagrid";
+
+const active = columnFilters.filter((filter) => isFilterActive(filter.value));
+```
+
+### Numeric operators on a column without meta.type
+
+`getColumnType(column)` defaults to `"string"`, so a numeric column that omits
+`meta: { type: "number" }` offers only the string operators — `greaterThan` and
+the other comparisons never appear in the panel, and comparisons run as text.
+
+### Setting size to control width
+
+`size` is only applied once the column becomes fixed by resizing or pinning.
+On a fluid column it is ignored; the track is `minmax(minSize, flex fr)`. Use
+`minSize` for a floor and `meta.flex` for the share, or `minSize === maxSize`
+for a genuinely fixed column.

package/skills/features/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: features
+description: >
+  Enable or disable TMDataGrid interface elements through standard TanStack
+  table and column options, and reuse the same checks in your own components.
+  Covers the enableSorting/enableColumnFilters/enableHiding/enableColumnPinning/
+  enableColumnResizing/enableColumnOrdering/enableRowSelection matrix,
+  getGridCapabilities and getColumnCapabilities, why the features argument is
+  required for reactivity under the React Compiler, column pinning, column
+  ordering with moveColumn and moveColumnByStep, and always-on virtualization.
+  Load when building a read-only grid, hiding grid chrome, reordering columns
+  from code, or writing a custom toolbar button.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid'
+  library_version: '0.1.0'
+sources:
+  - 'Jielga/TMDataGrid:src/docs/features.md'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/capabilities.ts'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/columnOrdering.ts'
+---
+
+# TMDataGrid — Features and capabilities
+
+Almost every control is bound to the TanStack capability check for that feature,
+so setting the standard table or column option removes the corresponding
+interface. Empty menus and inactive buttons are never rendered.
+
+Column ordering is the one exception. TanStack's `columnOrderingFeature` ships
+state and APIs but no `enable` option, so the grid defines
+`enableColumnOrdering` and `meta.enableOrdering` itself. They behave like the
+options around them.
+
+## Option reference
+
+| Option | Level | Interface removed |
+| --- | --- | --- |
+| `enableSorting: false` | Table, column | Sort indicator, sort menu items, click-to-sort |
+| `enableColumnFilters: false` | Table | Filter menu item, `FilterButton`, filter panel |
+| `enableColumnFilter: false` | Column | That column's filter menu item and panel entry |
+| `enableHiding: false` | Table, column | Hide column, Manage columns, `ColumnsButton` |
+| `enableColumnPinning: false` | Table | Pin and unpin menu items |
+| `enablePinning: false` | Column | That column's pin menu items |
+| `enableColumnResizing: false` | Table | Resize dragging. The divider remains as a separator |
+| `enableResizing: false` | Column | That column's resize dragging |
+| `enableColumnOrdering: false` | Table | Header dragging and the move menu items |
+| `meta.enableOrdering: false` | Column | That column's header dragging and move menu items |
+| `enableRowSelection: false` | Table | The checkbox column |
+
+A column whose menu has no remaining items renders no menu button. Dividers are
+never left at the end of a menu.
+
+```tsx
+// Read-only grid: no selection, hiding, pinning or filtering.
+const grid = useTMDataGrid({
+  data,
+  columns,
+  enableRowSelection: false,
+  enableHiding: false,
+  enableColumnPinning: false,
+  enableColumnFilters: false,
+});
+```
+
+Pagination is not controlled by an option — omit `TMDataGrid.Footer` and no
+pagination controls are rendered.
+
+## Capability helpers
+
+Use these to apply the same checks in your own components.
+
+```tsx
+import { getGridCapabilities, useTMDataGridContext } from "@jielga/tmdatagrid";
+
+function ExportButton() {
+  const { table, features } = useTMDataGridContext();
+  const { canFilterAny } = getGridCapabilities(table, features);
+
+  if (!canFilterAny) return null;
+  return <Button onClick={exportRows}>Export</Button>;
+}
+```
+
+`getGridCapabilities(table, features)`:
+
+| Field | Description |
+| --- | --- |
+| `canSortAny` | At least one leaf column can be sorted. |
+| `canFilterAny` | At least one leaf column can be filtered. |
+| `canHideAny` | At least one leaf column can be hidden. |
+| `canPinAny` | At least one leaf column can be pinned. |
+| `canReorderAny` | At least one leaf column can be moved. |
+| `canSelectRows` | `enableRowSelection` is not `false`. |
+
+`getColumnCapabilities(column, features)` returns the same information for a
+single column as `canSort`, `canFilter`, `canHide`, `canPin`, `canResize` and
+`canReorder`.
+
+`readFeatureFlags(options)` derives the flags from a table options object.
+
+## Why capabilities take a features argument
+
+`features` is returned by `useTMDataGrid` and re-derived from the options object
+on every render. It is required *in addition to* TanStack's `getCanX()` methods
+because it is what makes the result reactive.
+
+`column.getCanSort()` is a method call on a column object whose identity is
+preserved across an options change. Under the React Compiler the call is
+memoized, so a grid whose `enableSorting` flips to `false` would keep rendering
+sort indicators. Passing `features` supplies a value that actually changes, while
+`getCanX()` still determines the outcome and applies per-column overrides.
+
+The same rule applies to any value derived from the table elsewhere in an
+application: read state through `useSelector(table.store, …)` and options through
+`features`, rather than calling methods on a long-lived object.
+
+## Column pinning
+
+Pin to left and Pin to right appear in each column menu. The current position is
+marked, and selecting it again unpins. Pinned columns are sticky within the
+scroll container, and the boundary is marked with a divider and a short gradient.
+
+Headers, cells and grid tracks are ordered left, centre, right from the same
+source, so pinning does not change a column's position relative to its group.
+
+Pinning is stored in `columnPinning`, one of the slices covered by `settingsKey`
+in the `options` skill.
+
+## Column ordering
+
+Enabled by default. Drag a column header sideways to move it; "Move left" and
+"Move right" in the column menu do the same one step at a time, and are the path
+that works without a pointer.
+
+A column only moves within its own pinned region, so a header in another region
+never accepts the drop. That follows TanStack's pipeline: pinning splits the
+grid into left, centre and right, then `columnOrder` sequences the centre while
+`columnPinning.left` / `.right` sequence the pinned lanes. Unpin first to move a
+column out of a pinned region.
+
+Ordering writes `columnOrder` as the complete leaf order — hidden and pinned
+columns included — so a column keeps its position when it is later shown or
+unpinned; moving a pinned column also rewrites its `columnPinning` array. Both
+slices are covered by `settingsKey`.
+
+A neighbour that cannot be moved acts as a wall rather than being stepped over,
+which is what keeps the checkbox column at the start of the left region.
+Columns inside a header group are never movable: `columnOrder` sequences leaf
+columns, so moving one would leave the group header spanning columns that no
+longer belong to it.
+
+```tsx
+import {
+  getStepTargetColumn,
+  moveColumn,
+  moveColumnByStep,
+} from "@jielga/tmdatagrid";
+
+moveColumn({ table, columnId: "salary", targetId: "age", side: "before" });
+moveColumnByStep({ table, columnId: "salary", direction: 1 });
+
+// null at the edge of a region — what the move menu items disable themselves on.
+const next = getStepTargetColumn({ table, columnId: "salary", direction: 1 });
+```
+
+Both movers are no-ops for a move that is not allowed, including one across
+regions.
+
+## Virtualization
+
+Always enabled and not configurable. Only rows within the viewport, plus a small
+overscan, are mounted, so page size does not affect how much is rendered.
+
+Row height comes from `meta.rowHeight`, or from the `size` prop when unset. Rows
+are fixed height; an accurate value keeps scrolling precise.
+
+## Common mistakes
+
+### Calling getCanX() in a custom component
+
+```tsx
+// Wrong — memoized under the React Compiler, so the button
+// never reappears when enableColumnFilters flips back to true.
+const { table } = useTMDataGridContext();
+if (!table.getAllLeafColumns().some((c) => c.getCanFilter())) return null;
+
+// Right — features is a value that changes.
+const { table, features } = useTMDataGridContext();
+const { canFilterAny } = getGridCapabilities(table, features);
+if (!canFilterAny) return null;
+```
+
+### Setting a custom row height in CSS only
+
+The virtualizer needs the height as a number to position rows. Overriding row
+height in a stylesheet leaves the virtualizer measuring the old value, so rows
+overlap or leave gaps as you scroll. Set `meta.rowHeight` instead.
+
+### Reordering a pinned column through columnOrder
+
+```tsx
+// Wrong — the left and right regions are sequenced by columnPinning,
+// so this moves nothing on screen.
+table.setColumnOrder(["__select__", "department", "id", …]);
+
+// Right — moveColumn writes whichever slice the column's region uses.
+moveColumn({ table, columnId: "department", targetId: "id", side: "before" });
+```
+
+### Expecting a table-level flag to override a column
+
+Table and column options compose — the table flag gates the feature, and the
+column flag narrows it further. `enableSorting: true` on a column does not
+re-enable sorting for a table that set `enableSorting: false`.

package/skills/getting-started/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: getting-started
+description: >
+  Set up TMDataGrid, a compound React data grid built on TanStack Table v9 and
+  Mantine. Covers useTMDataGrid, the TMDataGrid root, context, the component
+  catalog (Table, Footer, Toolbar, Spacer, SummaryCount, FilterButton,
+  ColumnsButton, FilterPanel, ColumnsPanel), the size scale and the
+  bounded-height layout requirement. Load when adding a grid, choosing which
+  parts to render, or when rows do not appear.
+metadata:
+  type: core
+  library: '@jielga/tmdatagrid'
+  library_version: '0.1.0'
+sources:
+  - 'Jielga/TMDataGrid:src/docs/getting-started.md'
+  - 'Jielga/TMDataGrid:src/docs/components.md'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/TMDataGrid.tsx'
+  - 'Jielga/TMDataGrid:src/tmdatagrid/sizes.ts'
+---
+
+# TMDataGrid — Getting started
+
+`useTMDataGrid` creates the table, `TMDataGrid` provides it through context, and
+the parts rendered inside read what they need from that context. Only the parts
+you render exist: leave out `TMDataGrid.Footer` and there is no pagination.
+
+## Install
+
+```sh
+npm install @jielga/tmdatagrid
+```
+
+Peer dependencies: `react` and `react-dom` (19.1+), `@mantine/core`,
+`@tanstack/react-table` (v9), `@tanstack/react-store`, `@tanstack/store`,
+`@tanstack/react-virtual`, `@tabler/icons-react`.
+
+Import both stylesheets once, Mantine's first, and render inside a
+`MantineProvider`:
+
+```ts
+import "@mantine/core/styles.css";
+import "@jielga/tmdatagrid/styles.css";
+```
+
+## Setup
+
+```tsx
+import {
+  createTMDataGridColumnHelper,
+  TMDataGrid,
+  useTMDataGrid,
+} from "@jielga/tmdatagrid";
+
+type Employee = { id: number; firstName: string; age: number };
+
+const columnHelper = createTMDataGridColumnHelper<Employee>();
+
+const columns = columnHelper.columns([
+  columnHelper.accessor("id", { header: "ID", meta: { type: "number" } }),
+  columnHelper.accessor("firstName", { header: "First name" }),
+  columnHelper.accessor("age", {
+    header: "Age",
+    meta: { type: "number", align: "right" },
+  }),
+]);
+
+export function Employees({ data }: { data: Employee[] }) {
+  const grid = useTMDataGrid({
+    data,
+    columns,
+    getRowId: (row) => String(row.id),
+  });
+
+  return (
+    <TMDataGrid {...grid} size="md" style={{ flex: 1, minHeight: 0 }}>
+      <TMDataGrid.Toolbar>
+        <TMDataGrid.SummaryCount />
+        <TMDataGrid.Spacer />
+        <TMDataGrid.FilterButton />
+        <TMDataGrid.ColumnsButton />
+      </TMDataGrid.Toolbar>
+
+      <TMDataGrid.Table<Employee> />
+      <TMDataGrid.Footer />
+    </TMDataGrid>
+  );
+}
+```
+
+Spread the hook result (`{...grid}`) rather than assigning `table`, `ui` and
+`features` individually.
+
+## Defaults
+
+| Behaviour | Notes |
+| --- | --- |
+| Virtualized rows | Always enabled, not configurable. Only rows in view are mounted. |
+| Resizable columns | Drag the divider on a header's trailing edge. |
+| Reorderable columns | Drag a header sideways, or use the column menu. |
+| Sorting | Click a header, or use the column menu. |
+| Column menu | On hover: sort, filter, pin, move, hide, manage columns. |
+| Filter panel | Column, operator and value rows. |
+| Column manager | Search, toggle, show/hide all, reset. |
+| Row selection | Checkbox column pinned to the left. |
+| Pagination | Only when `TMDataGrid.Footer` is rendered. |
+| Sizing | `size="xs"` to `size="xl"` scales rows, type and controls. |
+
+Each is bound to a capability check — disabling the standard table or column
+option also removes its interface. Column ordering is the one switch the grid
+defines itself, as `enableColumnOrdering`. See the `features` skill.
+
+## Layout
+
+`TMDataGrid` renders a flex column with `overflow: hidden`. It needs a bounded
+height, either `style={{ flex: 1, minHeight: 0 }}` inside a flex parent or a
+fixed height. The table area then fills the remaining space.
+
+Columns are fluid by default: each track is `minmax(minSize, flex fr)`. A column
+takes a fixed pixel width once resized or pinned.
+
+## Components
+
+All read the grid from context and must be rendered inside `TMDataGrid`. Order
+and presence are up to you — the root is a plain flex column.
+
+| Component | Props | Notes |
+| --- | --- | --- |
+| `TMDataGrid` | `table`, `ui`, `features`, `size`, `className`, `style` | Root. Provides context. |
+| `TMDataGrid.Table` | `onRowClick(row)` | Header, virtualized body, filter panel. |
+| `TMDataGrid.Footer` | `pageSizeOptions` (default `[10, 25, 50, 100]`) | Pagination controls. |
+| `TMDataGrid.Toolbar` | `children` | Flex row above the grid. |
+| `TMDataGrid.Spacer` | — | Pushes later toolbar items right. |
+| `TMDataGrid.SummaryCount` | `children` | Visible rows out of total. |
+| `TMDataGrid.FilterButton` | — | Toggles filter panel. Renders nothing if no column is filterable. |
+| `TMDataGrid.ColumnsButton` | — | Opens column manager. Renders nothing if no column is hideable. |
+| `TMDataGrid.FilterPanel` | — | Rendered by `.Table`; exported for custom layouts. |
+| `TMDataGrid.ColumnsPanel` | — | Rendered by `.ColumnsButton`; exported for custom layouts. |
+
+Pass the row type so `onRowClick` stays typed:
+
+```tsx
+<TMDataGrid.Table<Employee> onRowClick={(row) => open(row.original.id)} />
+```
+
+`TMDataGrid.Footer` reads totals from `table.getRowCount()`, which prefers
+`options.rowCount`. `TMDataGrid.SummaryCount` uses `meta.totalRowCount` when
+provided, otherwise the pre-filtered row count.
+
+## size
+
+Standard Mantine scale. Controls row height, header height, font size and cell
+padding, and selects the size of the Mantine controls the grid renders.
+
+| `size` | Row height | Header height | Font size | Cell padding |
+| --- | --- | --- | --- | --- |
+| `xs` | 34px | 32px | `xs` | 6px |
+| `sm` | 42px | 38px | `sm` | 8px |
+| `md` | 52px | 44px | `sm` | 10px |
+| `lg` | 62px | 52px | `md` | 14px |
+| `xl` | 72px | 60px | `lg` | 18px |
+
+The virtualizer needs row height as a number, so it cannot come from CSS alone.
+`SIZE_ROW_HEIGHT` is the exported source of these values and the stylesheet
+mirrors them. Set `meta.rowHeight` for a height outside the scale.
+
+## Helpers
+
+| Export | Description |
+| --- | --- |
+| `useTMDataGridContext()` | The enclosing grid context. Throws outside `TMDataGrid`. |
+| `openColumnFilter(api, columnId)` | Adds an empty filter for a column and opens the panel. |
+| `getColumnLabel(column)` | `meta.label`, a string header, or the column id. |
+| `getColumnType(column)` | `meta.type`, defaulting to `"string"`. |
+| `moveColumn({ table, columnId, targetId, side })` | Moves a column next to another. See the `features` skill. |
+| `moveColumnByStep({ table, columnId, direction })` | Moves a column one position within its region. |
+| `SELECT_COLUMN_ID` | Id of the generated checkbox column. |
+
+## Common mistakes
+
+### Columns or data defined during render
+
+A new array on every render rebuilds the table's column model. Define `columns`
+at module scope; keep `data` stable with `useMemo`.
+
+```tsx
+// Wrong — rebuilds the column model every render.
+export function Employees({ data }: { data: Employee[] }) {
+  const columns = columnHelper.columns([...]);
+  const grid = useTMDataGrid({ data, columns });
+}
+```
+
+### Root with no bounded height
+
+The root is `overflow: hidden`. Without `flex: 1; minHeight: 0` in a flex parent
+or an explicit height, the table area collapses and no rows are visible — there
+is no error.
+
+### Assigning the hook result field by field
+
+`<TMDataGrid table={grid.table}>` omits `ui` and `features`. Panels stop opening
+and feature toggles stop being reactive. Spread instead: `<TMDataGrid {...grid}>`.
+
+### Expecting Footer to control pagination
+
+Pagination is not an option. Omitting `TMDataGrid.Footer` removes the controls
+but the table still paginates at `pageSize: 25` — rows beyond the first page
+simply become unreachable. Set `initialState.pagination.pageSize` if you want
+every row on one page.