react-gridix 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,1043 @@
+# react-gridix
+
+A React `DataGrid` with per-column filters, in-cell editing, nested fields, themes and custom components, plus the `Checkbox` it uses.
+
+**Contents**
+
+1. [Overview](#1-overview)
+2. [Installation](#2-installation)
+3. [Quick start](#3-quick-start)
+4. [Theming](#4-theming)
+5. [Checkbox](#5-checkbox)
+6. [DataGrid](#6-datagrid)
+7. [Demos](#7-demos)
+8. [Development, building and publishing](#8-development-building-and-publishing)
+9. [Troubleshooting](#9-troubleshooting)
+
+---
+
+## 1. Overview
+
+| Component | Purpose |
+| --- | --- |
+| `DataGrid` | Data table with sorting, search, per-column filters, pagination, in-cell editing, nested fields, striping, themes and custom column components |
+| `Checkbox` | Checkbox in three looks (button with a span, tick, native), toggles with one click. The grid uses it for boolean columns, and you can use it on its own |
+
+Everything is written in TypeScript, ships its own type definitions, and uses plain CSS (no CSS-in-JS runtime). The grid is 100% of its container's width by default.
+
+---
+
+## 2. Installation
+
+**Requirements:** React 18 or newer and `react-dom`.
+
+```bash
+npm install react-gridix
+```
+
+The stylesheet is included in the package's `style.css`. Import it once, near the root of your app:
+
+```tsx
+import "react-gridix/style.css";
+```
+
+The library does not inject CSS by itself. If the grid looks unstyled, this import is missing.
+
+---
+
+## 3. Quick start
+
+```tsx
+import { useState } from "react";
+import { DataGrid, type ColumnDef } from "react-gridix";
+import "react-gridix/style.css";
+
+interface Person {
+  id: number;
+  name: string;
+  contact: { email: string; phone: string };
+}
+
+const columns: ColumnDef<Person>[] = [
+  { field: "id", headerName: "ID", type: "number", editable: false },
+  { field: "name", headerName: "Name", filterable: true },
+  { field: "contact.email", headerName: "Email" },
+  { field: "contact.phone", headerName: "Phone" },
+];
+
+export default function App() {
+  const [rows, setRows] = useState<Person[]>([
+    { id: 1, name: "Amina", contact: { email: "amina@example.com", phone: "+256 700 100 200" } },
+    { id: 2, name: "Brian", contact: { email: "brian@example.com", phone: "+256 700 100 237" } },
+  ]);
+
+  return (
+    <DataGrid
+      columns={columns}
+      rows={rows}
+      getRowId={(r) => r.id}
+      editable
+      onRowsChange={setRows}
+      theme="ocean"
+    />
+  );
+}
+```
+
+---
+
+## 4. Theming
+
+### 4.1 Built-in themes
+
+Pass a theme name to the grid. **Without a `theme` prop nothing changes**: the grid keeps its plain default look.
+
+```tsx
+<DataGrid theme="midnight" ... />
+```
+
+| Theme | Look |
+| --- | --- |
+| `"ocean"` | Light, cool blues, blue gradient header, soft shadow |
+| `"midnight"` | Dark slate, indigo accent, dark popups and inputs |
+| `"sunset"` | Warm cream, orange-to-pink gradient header, serif font, rounded corners |
+| `"forest"` | Calm greens, solid dark-green header, sharper corners |
+
+A theme is only a set of CSS variables on `[data-rk-theme="name"]`, written with `:where()` (zero specificity). So you can still override any variable or any class on top of a theme. The filter popup is drawn in `document.body`, and the grid copies the theme attribute onto it, so the popup follows the theme too.
+
+**Making your own theme.** Any other string works as a theme name. Define the variables you want:
+
+```css
+[data-rk-theme="brand"] {
+  --rk-header-bg: #7c3aed;
+  --rk-header-text: #fff;
+  --rk-row-hover: #f5f3ff;
+  --rk-primary: #7c3aed;
+}
+```
+
+```tsx
+<DataGrid theme="brand" ... />
+```
+
+### 4.2 CSS variables
+
+Every variable is optional and is read with a fallback, so nothing is declared on the grid itself. Set them on `:root`, on any parent element, in your own theme, or in the grid's `style`.
+
+| Variable | Default | Used for |
+| --- | --- | --- |
+| `--rk-font` | system UI stack | Font family |
+| `--rk-text` | `#111827` | Main text |
+| `--rk-muted` | `#6b7280` | Secondary text, empty state |
+| `--rk-border` | `#d1d5db` | Borders |
+| `--rk-surface` | `#ffffff` | Background of the grid, inputs, buttons |
+| `--rk-bg-subtle` | `#f3f4f6` | Header and footer background |
+| `--rk-primary` | `#4f46e5` | Focus rings, active editor border |
+| `--rk-danger` | `#dc2626` | Invalid editor border |
+| `--rk-invalid-bg` | `#fef2f2` | Invalid editor background |
+| `--rk-grid-bg` | `--rk-surface` | Grid background |
+| `--rk-grid-radius` | `10px` | Grid corner radius |
+| `--rk-grid-shadow` | `none` | Grid shadow |
+| `--rk-toolbar-bg` | `transparent` | Toolbar background |
+| `--rk-input-bg`, `--rk-input-border`, `--rk-input-text` | surface, border, inherit | Search box, filter box, editor, page controls |
+| `--rk-header-bg` | `--rk-bg-subtle` | Header background. Any CSS background, so gradients work |
+| `--rk-header-text` | inherit | Header text colour |
+| `--rk-header-hover-bg` | `rgba(0,0,0,.06)` | Header hover |
+| `--rk-header-border` | `--rk-border` | Line under the header |
+| `--rk-cell-border` | `#eef0f3` | Lines between rows |
+| `--rk-row-hover` | `#f3f4f6` | Row hover |
+| `--rk-stripe-a`, `--rk-stripe-b` | `transparent`, `#fafafa` | Alternating row colours (see [stripes](#striped-rows)) |
+| `--rk-footer-bg`, `--rk-footer-text` | subtle, muted | Pagination bar |
+| `--rk-btn-hover` | `#e5e7eb` | Page button and Clear button hover |
+| `--rk-filter-active` | `--rk-primary` | Filter dot colour while a filter is set |
+| `--rk-filter-glow` | `rgba(79,70,229,.25)` | Ring around an active filter dot |
+| `--rk-popup-bg`, `--rk-popup-text`, `--rk-popup-border` | white, dark, grey | Filter popup |
+| `--rk-popup-radius`, `--rk-popup-shadow` | `10px`, soft shadow | Filter popup shape |
+| `--rk-row-duration` | `0.38s` | Row entrance animation length |
+| `--rk-row-stagger` | `28ms` | Extra delay per row in the entrance animation |
+| `--rk-checkbox-size` | `20px` | Checkbox width and height |
+| `--rk-checkbox-border-width` | `1px` | Checkbox border width |
+| `--rk-checkbox-radius` | `0` | Checkbox corner radius (no rounding by default) |
+| `--rk-checkbox-color` | `#4f46e5` | Checked colour (also the focus ring and the native accent) |
+| `--rk-checkbox-border` | `#9ca3af` | Border colour of an unchecked `"button"` / `"tick"` checkbox |
+| `--rk-checkbox-bg` | `#ffffff` | Background of an unchecked `"button"` / `"tick"` checkbox |
+| `--rk-checkbox-tick` | `#ffffff` | Colour of the tick, and of a custom character in the `"tick"` variant |
+
+```css
+:root {
+  --rk-primary: #0d9488;
+  --rk-row-hover: #f0fdfa;
+}
+```
+
+---
+
+## 5. Checkbox
+
+A checkbox in three looks. Every variant toggles with **one click** (or the Space key when it has focus), and clicking the label text toggles it too.
+
+```tsx
+<Checkbox variant="button" checked={a} onChange={setA} label="Button + span" />
+<Checkbox variant="tick" checked={b} onChange={setB} label="Tick" />
+<Checkbox variant="native" checked={c} onChange={setC} label="Native" />
+```
+
+| Variant | What it is |
+| --- | --- |
+| `"button"` | A `<button role="checkbox">` drawn as a box, with a `<span>` inside that is hidden when unchecked and shown when checked |
+| `"tick"` | The same button, but the box fills with the checked colour and the span holds a tick icon |
+| `"native"` | The browser's own `<input type="checkbox">` |
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checked` | `boolean` | required | Current value (controlled) |
+| `indeterminate` | `boolean` | `false` | Shows the mixed ("some selected") state: a dash instead of a tick. Use it with `checked={false}`. A click then calls `onChange(true)` |
+| `onChange` | `(checked: boolean) => void` | required | Called once per toggle with the new value |
+| `variant` | `"button" \| "tick" \| "native"` | `"native"` | Which look to use |
+| `disabled` | `boolean` | `false` | Disables the checkbox and dims it |
+| `label` | `ReactNode` | | Text next to the box. Clicking it toggles the checkbox. An empty string, `null` or `false` renders no label |
+| `aria-label` | `string` | | Accessible name when there is no visible `label` |
+| `id` | `string` | | `id` of the control |
+| `name` | `string` | | `name` of the input (`"native"` variant only) |
+| `indicator` | `ReactNode` | | A custom character or icon drawn inside the `"button"` and `"tick"` variants when checked, for example `"★"` |
+| `className` | `string` | | Classes for the root element (same as `classNames.root`) |
+| `style` | `CSSProperties` | | Inline styles for the root element (same as `styles.root`) |
+| `classNames` | `Partial<Record<CheckboxSlot, string>>` | | Classes per part |
+| `styles` | `Partial<Record<CheckboxSlot, CSSProperties>>` | | Inline styles per part |
+
+**Parts (`CheckboxSlot`):** `root` (the wrapping `<label>`), `control` (the `<button>` or `<input>`), `indicator` (the span inside, button variants only) and `label` (the text).
+
+**Customising the look from outside**
+
+1. **Classes and inline styles per part**, including Tailwind:
+
+   ```tsx
+   <Checkbox
+     variant="tick"
+     checked={on}
+     onChange={setOn}
+     classNames={{ control: "rounded-full border-emerald-500 aria-checked:bg-emerald-500" }}
+     styles={{ root: { gap: 12 } }}
+   />
+   ```
+
+   (`aria-checked:` works for the `"button"` and `"tick"` variants. The native input has no `aria-checked`, so use the `--rk-checkbox-color` variable for it.)
+2. **CSS variables**: `--rk-checkbox-size`, `--rk-checkbox-border-width`, `--rk-checkbox-radius`, `--rk-checkbox-color`, `--rk-checkbox-border`, `--rk-checkbox-bg` and `--rk-checkbox-tick` (see [Theming](#42-css-variables)). Set them anywhere above the checkbox:
+
+   ```tsx
+   <Checkbox styles={{ root: { "--rk-checkbox-color": "#dc2626" } as CSSProperties }} ... />
+   ```
+3. **A custom character**, for example `indicator="★"` (any text, emoji or React node). It shows when the box is checked, in the `"button"` and `"tick"` variants. The default fill is dropped; the character is sized to the box (70% of `--rk-checkbox-size`) and coloured with `--rk-checkbox-color` in the button variant and `--rk-checkbox-tick` in the tick variant. Restyle it through `classNames.indicator` / `styles.indicator`.
+4. **Plain CSS** with these stable classes: `.rk-checkbox`, `.rk-checkbox--button`, `.rk-checkbox--tick`, `.rk-checkbox--native`, `.rk-checkbox--checked`, `.rk-checkbox--indeterminate`, `.rk-checkbox--disabled`, `.rk-checkbox__control`, `.rk-checkbox__indicator`, `.rk-checkbox__indicator--custom` and `.rk-checkbox__label`. State is also exposed as `data-state="checked"`, `"unchecked"` or `"indeterminate"` and, on the button variants, `aria-checked` (`"true"`, `"false"` or `"mixed"`).
+
+**Defaults:** a 1px border and square corners (`--rk-checkbox-border-width: 1px`, `--rk-checkbox-radius: 0`). Round them with `--rk-checkbox-radius: 999px` or a Tailwind `rounded-*` class on `classNames.control`.
+
+The checkbox CSS is written with `:where()` (zero specificity), so any class you add wins without `!important`.
+
+**Accessibility:** the button variants have `role="checkbox"` and `aria-checked`, and the native variant is a real checkbox. When you don't pass a `label`, pass an `aria-label`.
+
+---
+
+---
+
+## 6. DataGrid
+
+### 6.1 Concepts
+
+```tsx
+<DataGrid columns={columns} rows={rows} />
+```
+
+- **`rows`** is an array of plain objects.
+- **`columns`** is an array of column definitions. Each one names a `field` (a key of the row object) and describes how to show, sort, filter and edit it.
+- **Row ids.** Pass `getRowId` when your rows have a stable id. Without it the grid uses each row's index in `rows`, which is fine for static data.
+- **`rowIndex`** in callbacks and params is always the row's index in your original `rows` array, not its position on screen.
+- **The grid keeps its own copy of the rows** so edits appear immediately. It re-syncs whenever the `rows` prop changes identity. See [section 6.8](#68-editing).
+
+The grid is generic: `DataGrid<T>` infers `T` from `rows`, and `ColumnDef<T>` checks that each `field` is a real key of `T` or a dot path into a nested object (see [nested fields](#611-nested-fields)).
+
+### 6.2 DataGrid props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `columns` | `ColumnDef<T>[]` | required | Column definitions |
+| `rows` | `T[]` | required | Data |
+| `getRowId` | `(row, index) => string \| number` | row index | Stable id for each row |
+| `editable` | `boolean` | `false` | Allow editing cells. Columns can override this |
+| `enterMovesDown` | `boolean` | `true` | After Enter saves a cell, edit the cell below |
+| `onCellEdit` | `(event: CellEditEvent<T>) => void` | | Called after a cell edit is saved |
+| `onRowsChange` | `(rows: T[]) => void` | | Called with the full updated array after an edit |
+| `sortable` | `boolean` | `true` | Click headers to sort. Columns can override |
+| `defaultSort` | `SortModel \| null` | `null` | Initial sort. Read once, on mount |
+| `onSortChange` | `(sort: SortModel \| null) => void` | | Called when the sort changes |
+| `searchable` | `boolean` | `true` | Show the global search box |
+| `searchPlaceholder` | `string` | `"Search…"` | Placeholder of the search box |
+| `pagination` | `boolean` | `true` | Split rows into pages |
+| `paginationPosition` | `"bottom" \| "top" \| "both"` | `"bottom"` | Where the row count and page controls go |
+| `pageSize` | `number` | `10` | Initial rows per page. Read once, on mount |
+| `pageSizeOptions` | `number[]` | `[5, 10, 25, 50]` | Choices in the page size menu. The current page size is added if missing |
+| `onRowClick` | `(row, rowIndex) => void` | | Called when a row is clicked |
+| `toolbar` | `ReactNode` | | Extra content on the right of the toolbar |
+| `emptyMessage` | `ReactNode` | `"No rows to show"` | Shown when no rows match |
+| `striped` | `boolean` | `false` | Alternate row shading |
+| `stripeColors` | `[string, string]` | | Two colours for the alternating rows. Implies `striped`. See [striped rows](#striped-rows) |
+| `animateRows` | `boolean` | `true` | Rows slide up and fade in when they render. See [row animation](#row-animation) |
+| `theme` | `"ocean" \| "midnight" \| "sunset" \| "forest" \| string` | | Applies a theme. Nothing changes without it. See [Theming](#4-theming) |
+| `checkboxVariant` | `"button" \| "tick" \| "native"` | `"native"` | Checkbox look for `type: "boolean"` columns. Columns can override it. See [Checkbox columns](#checkbox-columns-type-boolean) |
+| `maxHeight` | `number \| string` | | Makes the body scroll, with a sticky header. Example: `400` or `"60vh"` |
+| `className` | `string` | | Classes for the root element (Tailwind works). The grid is `width: 100%` of its container by default |
+| `style` | `CSSProperties` | | Inline styles for the root element |
+| `classNames` | `Partial<Record<GridSlot, string>>` | | Classes for individual parts. See [6.10](#610-styling) |
+| `styles` | `Partial<Record<GridSlot, CSSProperties>>` | | Inline styles for individual parts |
+| `rowClassName` | `string \| (row, rowIndex) => string` | | Classes for rows |
+| `rowStyle` | `CSSProperties \| (row, rowIndex) => CSSProperties` | | Inline styles for rows |
+
+### 6.3 Column definitions
+
+```ts
+const columns: ColumnDef<Employee>[] = [
+  { field: "name", headerName: "Name" },
+  { field: "salary", headerName: "Salary", type: "number", align: "right" },
+];
+```
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `field` | `FieldPath<T>` | **Required.** Key of the row object this column reads and writes. Use dot notation for nested objects: `"contact.phone"` |
+| `headerName` | `string` | Header text. Defaults to the field name, except in `type: "boolean"` columns, where it defaults to an empty string |
+| `type` | `"text" \| "number" \| "boolean"` | `"number"` columns edit and parse as numbers. `"boolean"` columns show a checkbox. Default `"text"` |
+| `width` | `number \| string` | Header cell width |
+| `minWidth` | `number \| string` | Header cell minimum width |
+| `align` | `"left" \| "center" \| "right"` | Text alignment for the header, cells and editor |
+| `sortable` | `boolean` | Overrides the grid-level `sortable` |
+| `filterable` | `boolean` | Show a filter indicator in this column's header (default `false`). Clicking it opens the filter popup. See [6.5](#65-searching-and-filtering) |
+| `filterPlaceholder` | `string` | Placeholder of the default filter text box |
+| `filterIndicator` | `ComponentType<FilterIndicatorProps<T>>` | Your own component drawn instead of the default dot |
+| `filterIndicatorClassName` | `string` | Classes for this column's indicator button |
+| `filterIndicatorStyle` | `CSSProperties` | Inline styles for this column's indicator button |
+| `filterPopupClassName` | `string` | Classes for this column's filter popup |
+| `filterPopupStyle` | `CSSProperties` | Inline styles for this column's filter popup |
+| `editable` | `boolean \| (params: CellEditableParams<T>) => boolean` | Overrides the grid-level `editable`. A function decides per cell |
+| `valueFormatter` | `(value, row) => string` | Text used for display, search, filtering. Does not change the stored value |
+| `valueParser` | `(text, row) => unknown` | Turns typed text into the value to store |
+| `validate` | `(value, row) => boolean` | Return `false` to reject an edit |
+| `comparator` | `(a, b, rowA, rowB) => number` | Custom sort order |
+| `cellRenderer` | `ComponentType<CellParams<T>>` | Component that renders the cell |
+| `cellEditor` | `ComponentType<CellEditorProps<T>>` | Component used instead of the text box when editing |
+| `headerRenderer` | `ComponentType<HeaderRendererProps<T>>` | Component that renders the header label |
+| `filterRenderer` | `ComponentType<FilterRendererProps<T>>` | Component that replaces the filter text box inside the popup |
+| `className` | `string` | Classes for the whole column: its header cell and every body cell (Tailwind works) |
+| `style` | `CSSProperties` | Inline styles for the whole column: its header cell and every body cell |
+| `headerClassName` | `string` | Classes for this column's header cell only |
+| `headerStyle` | `CSSProperties` | Inline styles for this column's header cell |
+| `cellClassName` | `string \| (params) => string` | Classes for this column's cells |
+| `cellStyle` | `CSSProperties \| (params) => CSSProperties` | Inline styles for this column's cells |
+| `checkbox` | `ColumnCheckboxOptions` | Look of the checkbox in a `type: "boolean"` column: `variant`, `indicator`, `className`, `style`, `classNames`, `styles` |
+| `headerCheckbox` | `boolean` | On a `type: "boolean"` column, draws a select-all checkbox in the header, labelled with the header name (no label when it is empty). See [Select-all header checkbox](#select-all-header-checkbox) |
+
+### 6.4 Sorting
+
+- Click a header to sort ascending, click again for descending, click a third time to clear the sort.
+- Only one column is sorted at a time.
+- Numbers sort numerically, dates by time, booleans false before true. Everything else sorts as text with natural number ordering (`"item 2"` before `"item 10"`), ignoring case.
+- Empty values (`null`, `undefined`, `""`) always sort last, in both directions.
+- Add a `comparator` to sort any other way:
+
+```tsx
+{ field: "priority", comparator: (a, b) => order.indexOf(a) - order.indexOf(b) }
+```
+
+- Set an initial sort with `defaultSort={{ field: "salary", direction: "desc" }}` and react to changes with `onSortChange`.
+- Headers are keyboard accessible (Tab to a header, Enter or Space to sort) and expose `aria-sort`.
+- Turn sorting off for the whole grid with `sortable={false}` or per column with `sortable: false`.
+
+### 6.5 Searching and filtering
+
+**Global search.** The box above the grid matches rows where any column's displayed text contains the typed text (case-insensitive). "Displayed text" means the result of `valueFormatter` if there is one.
+
+**Column filters.** Filters are set per column, in the column definition. Only columns with `filterable: true` get one:
+
+```tsx
+const columns: ColumnDef<Person>[] = [
+  { field: "name", filterable: true },
+  { field: "department", filterable: true, filterPlaceholder: "Which team?" },
+  { field: "salary" },                      // no filter
+];
+```
+
+- A filterable column shows a small **indicator** in its header, next to the label. By default it is a dot. It is dim while no filter is set, and lit (with a glow) while one is active.
+- **Clicking the indicator** opens a popup right below it with a text box. The popup is not there until you click. It closes on Escape, on a click outside, or on Enter in the text box. Clicking the indicator does not sort the column.
+- The popup shows a **Clear** button while a filter is set.
+- Filters work as a case-insensitive "contains" on the displayed text, and combine with each other and with the global search.
+- The popup is drawn in `document.body` and positioned next to the indicator, so a scrolling grid never clips it. It follows scrolling and resizing, and stays inside the window.
+- There is no grid-level filter prop: a column without `filterable: true` has no filter, and a filter value is ignored if its column stops being filterable.
+
+**Styling each indicator separately.** Every column has its own options:
+
+```tsx
+{
+  field: "status",
+  filterable: true,
+  filterIndicatorClassName: "text-amber-300",        // Tailwind on this indicator only
+  filterIndicatorStyle: { color: "#f59e0b" },        // or inline styles
+  filterPopupStyle: { borderColor: "#f59e0b" },      // style this column's popup
+}
+```
+
+The dot takes its colour from the button's text colour, so `color` (or `text-*`) restyles it. The colour while a filter is active comes from `--rk-filter-active`. To style all indicators or popups at once, use `classNames.filterIndicator`, `classNames.filterPopup`, `classNames.filterInput` (or the matching `styles`).
+
+**A custom indicator component.** Replace the dot with any component. It receives `{ column, active, open }`:
+
+```tsx
+function FunnelIndicator({ active }: FilterIndicatorProps<Employee>) {
+  return (
+    <svg width="14" height="14" viewBox="0 0 16 16" aria-hidden="true">
+      <path d="M1.5 2h13l-5 6v5l-3 1.5V8z" fill={active ? "currentColor" : "none"} stroke="currentColor" strokeWidth="1.5" />
+    </svg>
+  );
+}
+
+{ field: "department", filterable: true, filterIndicator: FunnelIndicator }
+```
+
+The component is drawn inside the indicator `<button>`, so do not put another button in it.
+
+**A custom filter control.** `filterRenderer` replaces the text box inside the popup (see [filterRenderer](#filterrenderer-custom-filter-control)).
+
+Notes:
+
+- Searching and filtering use the displayed text, so a salary shown as `$52,000` is found by `52,000` and not by `52000` unless your formatter says so.
+- Filtering is a substring match. Filtering a status column for `active` also matches `inactive`. For exact choices, use a `filterRenderer` and a distinct display text, or format the values so they don't overlap.
+- Changing the search, a filter, the sort or the page size sends the grid back to page 1.
+- Turn off the search box with `searchable={false}`. Leave out `filterable` (or set it to `false`) to give a column no filter.
+
+### 6.6 Pagination
+
+```tsx
+<DataGrid pageSize={20} pageSizeOptions={[10, 20, 50, 100]} paginationPosition="both" />
+```
+
+The pagination bar shows the row range ("11–20 of 200"), a rows-per-page menu, first/previous/next/last buttons and "Page x of y".
+
+| `paginationPosition` | Result |
+| --- | --- |
+| `"bottom"` | Bar under the table (default) |
+| `"top"` | Bar above the table, below the search box |
+| `"both"` | Both bars, kept in sync |
+
+With `pagination={false}` every row is rendered and only the row count shows, at the bottom. Combine it with `maxHeight` to get a scrolling grid with a sticky header:
+
+```tsx
+<DataGrid pagination={false} maxHeight={400} />
+```
+
+`pageSize` is only read when the grid first mounts. The user's choice in the menu is then kept inside the grid.
+
+### 6.7 Row click, toolbar and empty state
+
+```tsx
+<DataGrid
+  onRowClick={(row, rowIndex) => navigate(`/people/${row.id}`)}
+  toolbar={<button onClick={exportCsv}>Export</button>}
+  emptyMessage="Nothing matches your search"
+  striped
+/>
+```
+
+### 6.8 Editing
+
+Turn editing on with `editable` on the grid, then lock or unlock columns:
+
+```tsx
+<DataGrid editable columns={[
+  { field: "id", editable: false },                                   // locked column
+  { field: "name" },                                                  // editable (grid default)
+  { field: "status", editable: ({ row }) => row.department !== "HR" } // decided per cell
+]} />
+```
+
+A column can also be the only editable one: leave the grid's `editable` off and set `editable: true` on that column.
+
+**Starting an edit**
+
+| Action | Result |
+| --- | --- |
+| Double-click a cell | Opens the editor, cursor at the end |
+| Select a cell (click or Tab) and press **Enter** or **F2** | Opens the editor, cursor at the end |
+| Select a cell and type a character | Opens the editor with that character replacing the old value |
+
+Typing to start does not apply to columns with a custom `cellEditor`. Those open with double-click, Enter or F2.
+
+**While editing**
+
+| Key | Result |
+| --- | --- |
+| **Enter** | Save, then edit the cell below (the text is pre-selected so typing replaces it) |
+| **Shift+Enter** | Save, then edit the cell above |
+| **Tab** / **Shift+Tab** | Save, then edit the next / previous editable cell, wrapping across rows |
+| **Esc** | Cancel without saving |
+| Click elsewhere | Save |
+
+Details:
+
+- When there is no editable cell in that direction (for example Enter on the last row of the page), the value is saved and the editor closes. Focus returns to the cell.
+- Set `enterMovesDown={false}` to make Enter save and stay put.
+- Cells locked by `editable` are skipped when moving.
+- If sorting, filtering or paging changes the position of rows while you move between cells, editing follows the row, not the screen position.
+
+**How the typed text becomes a value**
+
+1. If the column has a `valueParser`, its return value is stored.
+2. Otherwise, in a `type: "number"` column, an empty text stores `null`, a valid number stores that number, and anything else is rejected.
+3. Otherwise the text is stored as a string.
+
+**Validation.** After parsing, `validate(value, row)` is called. If it returns `false` (or a number could not be parsed), the value is not saved, the editor stays open, and it gets the `rk-grid__editor--invalid` class and `aria-invalid="true"`. Pressing Esc or clicking away discards the invalid text.
+
+```tsx
+{ field: "email", validate: (v) => /^\S+@\S+\.\S+$/.test(String(v)) }
+```
+
+A value that equals the old value is treated as "no change" and fires no events.
+
+**Events.** When a value is saved the grid calls, in this order:
+
+```ts
+onCellEdit({ rowId, rowIndex, field, oldValue, newValue, row })  // row is the updated row
+onRowsChange(nextRows)                                            // the whole updated array
+```
+
+**Keeping your data in sync.** The simplest pattern is state plus `onRowsChange`:
+
+```tsx
+const [rows, setRows] = useState(initialRows);
+<DataGrid rows={rows} onRowsChange={setRows} editable />
+```
+
+Important: the grid copies `rows` into its own state and re-syncs whenever the `rows` prop *changes identity*. If your parent re-creates the array on every render (for example `rows={data.map(...)}` written inline), the grid resets to it each time and edits are lost. Keep `rows` in state or memoize it with `useMemo`.
+
+**Saving to a server:**
+
+```tsx
+<DataGrid
+  rows={rows}
+  onRowsChange={setRows}
+  onCellEdit={async (e) => {
+    await fetch(`/api/people/${e.rowId}`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ [e.field]: e.newValue }),
+    });
+  }}
+/>
+```
+
+### 6.9 Custom components per column
+
+Four hooks let you replace parts of a column with your own React components. They are rendered as real components, so they can use hooks and state.
+
+> **Define these components at module level**, not inline inside your render function. An inline component gets a new identity on every render, so React unmounts and remounts it each time (inputs lose focus, state resets).
+
+#### `cellRenderer`: custom cell content
+
+Receives `CellParams<T>`:
+
+| Prop | Description |
+| --- | --- |
+| `value` | The raw value from the row |
+| `formattedValue` | The value as text, after `valueFormatter` |
+| `row` | The whole row |
+| `rowIndex` | Index of the row in `rows` |
+| `field` | The column's field |
+| `column` | The column definition |
+| `editable` | `true` if the cell may be changed (the column's `editable`, or the grid's) |
+| `updateValue(value)` | Saves a new value for this cell right away, without opening the editor. It runs `validate` and fires `onCellEdit` / `onRowsChange`. Returns `false` if the value was rejected or the cell is not editable |
+
+```tsx
+function StatusCell({ value }: CellParams<Employee>) {
+  return <span className={value === "active" ? "text-green-700" : "text-gray-500"}>{String(value)}</span>;
+}
+
+{ field: "status", cellRenderer: StatusCell }
+```
+
+Searching, filtering and sorting still use the underlying value and `valueFormatter`, not what your component draws.
+
+#### `cellEditor`: custom editor
+
+Replaces the text box when the cell is being edited. Receives `CellEditorProps<T>`:
+
+| Prop | Description |
+| --- | --- |
+| `value` | The current draft value. Starts as the cell's raw value |
+| `row`, `rowIndex`, `field`, `column` | Same as in `CellParams` |
+| `onChange(value)` | Update the draft without saving |
+| `onCommit(value?, move?)` | Save and close. Pass a value to save it, or nothing to save the latest draft. `move` can be `"down" \| "up" \| "left" \| "right" \| "none"` (default `"none"`) and also starts editing the neighbouring cell |
+| `onCancel()` | Close without saving |
+
+Rules your editor should follow:
+
+- Focus something when it mounts (`autoFocus` or a ref) so the keyboard works straight away.
+- Esc is handled by the grid. Clicking or tabbing out of the editor saves the current draft.
+- A value passed to `onCommit` is stored as is. `valueParser` and the `type: "number"` conversion are not applied, but `validate` still is.
+
+```tsx
+function StatusEditor({ value, onCommit }: CellEditorProps<Employee>) {
+  return (
+    <select autoFocus value={String(value)} onChange={(e) => onCommit(e.target.value)}>
+      <option>active</option>
+      <option>pending</option>
+      <option>inactive</option>
+    </select>
+  );
+}
+
+{ field: "status", cellEditor: StatusEditor }
+```
+
+An editor with its own keyboard handling, saving and moving down on Enter:
+
+```tsx
+function SliderEditor({ value, onChange, onCommit }: CellEditorProps<Employee>) {
+  return (
+    <input
+      autoFocus
+      type="range"
+      value={Number(value) || 0}
+      onChange={(e) => onChange(Number(e.target.value))}
+      onKeyDown={(e) => e.key === "Enter" && onCommit(undefined, "down")}
+    />
+  );
+}
+```
+
+#### `headerRenderer`: custom header label
+
+Receives `{ column, sortDirection }`. The filter indicator (if `filterable`) and the sort arrow are still added next to it. The whole header cell is clickable for sorting, so call `event.stopPropagation()` on any interactive element you put inside.
+
+```tsx
+function SalaryHeader({ column }: HeaderRendererProps<Employee>) {
+  return <span>{column.headerName} <small>USD</small></span>;
+}
+```
+
+#### `filterRenderer`: custom filter control
+
+Shown inside the filter popup instead of the text box (the column still needs `filterable: true`). Receives `{ column, value, onChange }`, where `value` is the filter text. Whatever string you pass to `onChange` is matched with "contains" against the displayed text.
+
+```tsx
+function DepartmentFilter({ value, onChange }: FilterRendererProps<Employee>) {
+  return (
+    <select value={value} onChange={(e) => onChange(e.target.value)}>
+      <option value="">All</option>
+      <option>Engineering</option>
+      <option>Design</option>
+    </select>
+  );
+}
+```
+
+#### Checkbox columns (`type: "boolean"`)
+
+Set `type: "boolean"` on a column and each cell shows a [Checkbox](#checkbox). One click saves the new `true` / `false` value.
+
+```tsx
+const columns: ColumnDef<Task>[] = [
+  { field: "title", headerName: "Task" },
+  { field: "done", type: "boolean", align: "center", checkbox: { variant: "button" } },        // no headerName: the header is empty
+  { field: "starred", headerName: "Starred", type: "boolean", checkbox: { variant: "button", indicator: "★" } }, // custom character
+  { field: "urgent", headerName: "Urgent", type: "boolean", align: "center", checkbox: { variant: "tick" } },
+  { field: "archived", headerName: "Archived", type: "boolean", align: "center" },          // grid default: native
+  { field: "approved", headerName: "Approved", type: "boolean", editable: false },          // shown disabled
+];
+
+<DataGrid columns={columns} rows={rows} editable onRowsChange={setRows} checkboxVariant="native" />
+```
+
+How it behaves:
+
+- **One click saves.** The change goes through the same path as a typed edit: `validate` runs, then `onCellEdit` and `onRowsChange` fire. Space toggles a focused checkbox, and Tab reaches them.
+- **Who can click.** A checkbox is active only where the cell is editable: grid `editable`, overridden per column by `editable: true | false` or a function. Otherwise it is shown disabled.
+- **No text editor.** Boolean cells never open the text editor, and Enter and Tab navigation skip them. A click on the checkbox does not trigger `onRowClick`.
+- **Sorting, search and filters.** Unchecked sorts before checked. Search and filters match the text `Yes` / `No`, or whatever your `valueFormatter` returns. A missing value (`null`, `undefined`) shows unchecked.
+- **Header label.** The header of a boolean column is empty unless you set `headerName`. Screen readers still get the field name.
+- **Custom character.** `checkbox: { indicator: "★" }` draws that character instead of the default fill or tick when checked. Colour it with `--rk-checkbox-color` (button variant) or `--rk-checkbox-tick` (tick variant), for example through `checkbox.styles.root`.
+- **Defaults.** 1px border, no rounded corners. See [Checkbox](#5-checkbox).
+- **A column with its own `cellEditor`** is treated as a normal editable column instead.
+
+**Choosing and styling the checkbox**
+
+| Where | How |
+| --- | --- |
+| Whole grid | `checkboxVariant="tick"` |
+| One column | `checkbox: { variant: "tick" }` |
+| Whole grid, classes or inline styles | `classNames` / `styles` slots `checkbox`, `checkboxControl`, `checkboxIndicator` |
+| One column, classes or inline styles | `checkbox: { className, style, classNames, styles, indicator }` (same parts as the standalone `Checkbox`) |
+| Colours and size | CSS variables such as `--rk-checkbox-color`, set on the grid's `className` / `style`, or per column in `checkbox.styles.root` |
+
+```tsx
+<DataGrid
+  checkboxVariant="tick"
+  classNames={{
+    checkboxControl: "rounded-full border-emerald-500 aria-checked:bg-emerald-500",
+    checkboxIndicator: "text-white",
+  }}
+  ...
+/>
+```
+
+When both are given, the column's options are merged after the grid-level ones, so the column wins.
+
+**Fully custom checkbox in a cell.** Any `cellRenderer` can toggle the value itself through `updateValue`. This example is the "button with a span inside" written by hand:
+
+```tsx
+function PinCell({ value, editable, updateValue }: CellParams<Task>) {
+  return (
+    <button
+      type="button"
+      aria-pressed={!!value}
+      disabled={!editable}
+      onClick={(e) => {
+        e.stopPropagation(); // keep onRowClick from also firing
+        updateValue(!value);
+      }}
+    >
+      <span style={{ visibility: value ? "visible" : "hidden" }}>✓</span>
+    </button>
+  );
+}
+
+{ field: "pinned", cellRenderer: PinCell }
+```
+
+#### Select-all header checkbox
+
+Add `headerCheckbox: true` to a boolean column. The header label becomes a checkbox (the header name is its label, or no label if the name is empty) that checks or clears the whole column.
+
+```tsx
+{ field: "done", headerName: "Done", type: "boolean", align: "center", headerCheckbox: true, checkbox: { variant: "tick" } }
+{ field: "done", type: "boolean", headerCheckbox: true }   // just the checkbox, no text
+```
+
+- **Click:** if every target row is checked, it unchecks them all. Otherwise (none or only some are checked) it checks them all.
+- **Which rows:** every row that matches the current search and column filters, on all pages, and whose cell is editable. Rows the filters hide are left alone.
+- **State:** checked when all target rows are checked, a dash (mixed) when only some are, unchecked when none are. It updates as you toggle individual rows.
+- **Events:** `onCellEdit` fires once for each row that changed, and `onRowsChange` fires once with the whole updated array. Rows already at the target value, and rows where `validate` rejects the value, are skipped.
+- **Locked columns:** if no cell in the column is editable, the header checkbox is disabled but still shows the real state.
+- **Look:** it uses the same variant and styling as the column's cell checkboxes (`checkbox` options, `checkboxVariant`, and the `checkbox`, `checkboxControl` and `checkboxIndicator` slots).
+- **Sorting:** clicking the checkbox or its label does not sort. Click the sort arrow beside it (or the empty part of the header cell) to sort.
+- **Custom header:** if the column also has a `headerRenderer`, that is used and `headerCheckbox` is ignored. `headerCheckbox` does nothing on columns that are not `type: "boolean"`.
+
+### 6.10 Styling
+
+#### Whole grid
+
+```tsx
+<DataGrid className="rounded-xl shadow-lg" style={{ maxWidth: 900 }} ... />
+```
+
+#### Parts of the grid
+
+`classNames` and `styles` take the same keys. Each key is a part ("slot") of the grid:
+
+| Slot | Element |
+| --- | --- |
+| `root` | Outer container |
+| `toolbar` | Bar holding the search box and your `toolbar` content |
+| `search` | Global search input |
+| `scroll` | Scrolling wrapper around the table |
+| `table` | The `<table>` |
+| `thead` | The `<thead>` |
+| `headerRow` | The row of column headers |
+| `headerCell` | Each column header (`<th>`) |
+| `filterIndicator` | Each column's filter indicator button |
+| `filterPopup` | The filter popup (drawn in `document.body`) |
+| `filterInput` | The default filter text box in the popup |
+| `tbody` | The `<tbody>` |
+| `row` | Each body row |
+| `cell` | Each body cell (`<td>`) |
+| `editor` | The default text editor input |
+| `empty` | The "no rows" cell |
+| `footer` | The pagination bar (both top and bottom) |
+| `rowCount` | The "1–10 of 200" text |
+| `pageInfo` | The "Page 1 of 20" text |
+| `pageSize` | The rows-per-page `<select>` |
+| `pagination` | Wrapper around the page-size menu and buttons |
+| `pageButton` | Each first/previous/next/last button |
+| `checkbox` | Root of each checkbox in a `type: "boolean"` column |
+| `checkboxControl` | The checkbox's button or input |
+| `checkboxIndicator` | The span inside the `"button"` / `"tick"` checkboxes |
+
+#### Tailwind
+
+```tsx
+<DataGrid
+  className="rounded-2xl border-0 shadow-xl ring-1 ring-slate-200"
+  classNames={{
+    toolbar: "bg-slate-50 px-4 py-3",
+    search: "rounded-full border-slate-300 px-4",
+    headerCell: "bg-slate-900 text-xs uppercase tracking-wider text-slate-100",
+    row: "hover:bg-indigo-50",
+    footer: "bg-slate-50 text-slate-500",
+    pageButton: "rounded-full hover:bg-indigo-100",
+  }}
+  rowClassName={(row) => (row.status === "inactive" ? "opacity-50" : "")}
+/>
+```
+
+You do not need to add the library to Tailwind's `content` setting, because the class names live in your own code.
+
+The grid's built-in CSS is written with `:where()`, which gives it zero specificity. That means any class you add, Tailwind utilities included, overrides it without `!important`.
+
+#### Inline styles
+
+```tsx
+<DataGrid
+  style={{ border: "2px solid #111", borderRadius: 0 }}
+  styles={{
+    headerCell: { background: "#111", color: "#ffe66d" },
+    footer: { background: "#ffe66d" },
+  }}
+  rowStyle={(row) => (row.status === "pending" ? { background: "#fff7cc" } : {})}
+/>
+```
+
+When both are given, `style` wins over `styles.root`.
+
+#### Per column and per cell
+
+`className` and `style` style a whole column (its header and every cell). The `header*` and `cell*` options target only one part:
+
+```tsx
+{
+  field: "salary",
+  className: "font-mono text-slate-700",     // header and every cell (Tailwind)
+  style: { letterSpacing: 0.3 },            // header and every cell (inline)
+  headerClassName: "text-right",
+  headerStyle: { minWidth: 120 },
+  cellClassName: ({ value }) => (Number(value) > 100000 ? "font-bold text-green-600" : ""),
+  cellStyle: ({ value }) => (value === null ? { color: "#9ca3af" } : {}),
+}
+```
+
+#### Striped rows
+
+```tsx
+<DataGrid striped />                                   // default shading
+<DataGrid stripeColors={["#fef3c7", "#e0f2fe"]} />     // your two colours (implies striped)
+```
+
+Rows alternate between the two colours, starting with the first. `stripeColors` sets `--rk-stripe-a` and `--rk-stripe-b` on the grid. You can also set those variables in your own CSS or theme, and turn on `striped`. Hovering a row still highlights it (`--rk-row-hover`).
+
+#### Row animation
+
+When rows render (the first load, a new page, a sort, a search or a filter), they slide up and fade in, one after another. It is on by default.
+
+```tsx
+<DataGrid animateRows={false} />        // turn it off
+```
+
+Tune it with `--rk-row-duration` (default `0.38s`) and `--rk-row-stagger` (default `28ms` per row, up to 24 rows). Changing page or sort also scrolls the grid's own scroll area smoothly back to the top. Visitors who ask their system for reduced motion get no animation (`prefers-reduced-motion`).
+
+#### Width
+
+The grid is `width: 100%` of its container by default (it never overflows it: `max-width: 100%; min-width: 0`). To make it narrower, give it a width through `className` (`max-w-3xl`) or `style` (`{ maxWidth: 900 }`).
+
+#### Plain CSS class reference
+
+If you prefer writing CSS, these class names are stable.
+
+| Class | Element |
+| --- | --- |
+| `.rk-grid` | Root |
+| `.rk-grid__toolbar`, `.rk-grid__search` | Toolbar and search box |
+| `.rk-grid__scroll`, `.rk-grid__table`, `.rk-grid__thead`, `.rk-grid__tbody` | Table structure |
+| `.rk-grid__tr` | Every row |
+| `.rk-grid__th`, `.rk-grid__th--sortable`, `.rk-grid__th-content`, `.rk-grid__sort` | Header cells and sort arrow |
+| `.rk-grid__filter-btn`, `.rk-grid__filter-btn--active`, `.rk-grid__filter-btn--open`, `.rk-grid__filter-dot` | Filter indicator button and its default dot |
+| `.rk-grid-popup`, `.rk-grid__filter-input`, `.rk-grid__filter-clear` | Filter popup (in `document.body`), its text box and Clear button |
+| `.rk-grid__row`, `.rk-grid__row--stripe-a`, `.rk-grid__row--stripe-b`, `.rk-grid__row--enter`, `.rk-grid__row--clickable` | Body rows |
+| `.rk-grid__td`, `.rk-grid__td--editable`, `.rk-grid__td--editing` | Body cells |
+| `.rk-grid__editor`, `.rk-grid__editor--invalid`, `.rk-grid__custom-editor` | Editors |
+| `.rk-grid__empty` | Empty state |
+| `.rk-grid__checkbox-cell` | Wrapper around a checkbox in a boolean column (the checkbox's own classes start with `.rk-checkbox`, see [Checkbox](#checkbox)) |
+| `.rk-grid__footer`, `.rk-grid__footer--top` | Pagination bar (`data-position="top"` or `"bottom"`) |
+| `.rk-grid__count`, `.rk-grid__pagination`, `.rk-grid__page-size-label`, `.rk-grid__page-size`, `.rk-grid__page-btn`, `.rk-grid__page-info` | Pagination parts |
+
+
+### 6.11 Nested fields
+
+A column's `field` can point into nested objects with dot notation:
+
+```tsx
+interface Person {
+  id: number;
+  name: string;
+  contact: { email: string; phone: string };
+  address: { city: string };
+}
+
+const columns: ColumnDef<Person>[] = [
+  { field: "name" },
+  { field: "contact.email", headerName: "Email", filterable: true },
+  { field: "contact.phone", headerName: "Phone" },
+  { field: "address.city", headerName: "City" },
+];
+```
+
+- **TypeScript checks the path.** `field` is typed `FieldPath<Person>`: `"contact.phone"` is accepted, `"contact.fax"` is a type error. It follows up to 5 levels deep, and arrays and dates are treated as plain values.
+- **Everything uses the path:** display, global search, filters, sorting, editing, `valueFormatter`, `cellRenderer` (`value`, `field`), and boolean columns and select-all headers (`"prefs.newsletter"`).
+- **Editing never mutates your data.** Saving `contact.phone` copies `row` and `row.contact` and replaces the value, so the original objects are left alone. A missing level on the way is created. `onCellEdit` reports `field: "contact.phone"` and the updated row.
+- **A missing level reads as empty.** If `row.contact` is `undefined`, the cell is blank and sorts last. No error is thrown.
+- A key that really contains a dot (`{ "a.b": 1 }`) is read as that literal key first.
+- `__proto__`, `prototype` and `constructor` are never read or written through a path.
+- `getRowId`, `onRowClick` and other callbacks work as before.
+
+### 6.12 Keyboard reference
+
+| Where | Key | Action |
+| --- | --- | --- |
+| Header | Enter / Space | Sort by this column |
+| Selected cell | Enter / F2 | Start editing |
+| Selected cell | Any character | Start editing, replacing the value |
+| Editor | Enter | Save, edit cell below |
+| Editor | Shift+Enter | Save, edit cell above |
+| Editor | Tab / Shift+Tab | Save, edit next / previous cell |
+| Editor | Esc | Cancel |
+
+Arrow-key navigation between cells is not implemented. Use Tab, or the mouse, to select a cell.
+
+### 6.13 Accessibility
+
+- The table has `role="grid"`. Sortable headers are focusable, expose `aria-sort`, and work with Enter and Space.
+- Editable cells are focusable (`tabindex="0"`).
+- The search box, filter indicators (`aria-haspopup="dialog"`, `aria-expanded`), filter popups (`role="dialog"`), editors, page buttons and page-size menu have `aria-label`s. Checkboxes in columns with an empty header are named after the field.
+- Invalid editors set `aria-invalid="true"`.
+- Custom components you supply are responsible for their own accessibility.
+
+### 6.14 TypeScript
+
+All types are exported:
+
+```ts
+import type {
+  ColumnDef,
+  DataGridProps,
+  CellParams,
+  CellEditEvent,
+  CellEditorProps,
+  HeaderRendererProps,
+  FilterRendererProps,
+  GridSlot,
+  SortModel,
+  SortDirection,
+  MoveDirection,
+  PaginationPosition,
+  CellEditableParams,
+  ColumnCheckboxOptions,
+  FilterIndicatorProps,
+  FieldPath,
+  GridTheme,
+  CheckboxProps,
+  CheckboxVariant,
+  CheckboxSlot,
+} from "react-gridix";
+```
+
+Typing tips:
+
+```tsx
+const columns: ColumnDef<Employee>[] = [ ... ];       // field is checked against Employee (dot paths too)
+function Cell({ row }: CellParams<Employee>) { ... }   // row is typed as Employee
+```
+
+### 6.15 Recipes
+
+**Read-only grid**
+
+```tsx
+<DataGrid columns={columns} rows={rows} />   // editable defaults to false
+```
+
+**Currency column that accepts "$1,200" when typed**
+
+```tsx
+{
+  field: "salary",
+  type: "number",
+  align: "right",
+  valueFormatter: (v) => (v == null ? "" : money.format(v)),
+  valueParser: (text) => Number(text.replace(/[$,]/g, "")),
+  validate: (v) => Number.isFinite(v),
+}
+```
+
+(The editor opens with the raw number, such as `52000`. The parser only matters if the user types symbols.)
+
+**Only one column editable**
+
+```tsx
+<DataGrid columns={[{ field: "id" }, { field: "notes", editable: true }]} />
+```
+
+**Lock rows after approval**
+
+```tsx
+{ field: "amount", editable: ({ row }) => !row.approved }
+```
+
+**Scrolling grid with sticky header**
+
+```tsx
+<DataGrid pagination={false} maxHeight="60vh" />
+```
+
+**Highlight a row based on its data**
+
+```tsx
+<DataGrid rowClassName={(row) => (row.overdue ? "bg-red-50" : "")} />
+```
+
+### 6.16 Known limitations
+
+Not included (yet):
+
+- Column resizing, reordering, hiding or pinning
+- Row selection as its own concept (a set of selected rows with `onSelectionChange`). True/false checkbox columns, including a select-all header (`headerCheckbox`), are supported, see [Checkbox columns](#checkbox-columns-type-boolean)
+- Multi-column sorting
+- Row virtualization (very large pages render every row, so keep `pageSize` moderate)
+- Server-side sorting, filtering and paging (the grid works on the array you give it)
+- Arrow-key navigation between cells
+- Controlled search, filter or page state (only `defaultSort` and `pageSize` initial values)
+
+Behaviours to be aware of:
+
+- Column filters match by substring, so `active` also matches `inactive`.
+- Only one filter popup is open at a time (opening another closes the first by its outside click).
+- Stripes and the row animation restart on every page, sort, search or filter change.
+- `defaultSort` and `pageSize` are read once, on mount. Changing them later has no effect.
+- `rows` must keep a stable identity between renders, otherwise edits are discarded (see [6.8](#68-editing)).
+- `onRowClick` also fires for clicks inside a cell that is being edited.
+- A `valueParser` that returns `NaN` stores `NaN`. Add `validate: (v) => Number.isFinite(v)` to reject it.
+- Date values display with `toLocaleDateString()`. Editing a `Date` cell shows its `String()` form, so store dates as ISO strings (`"2026-11-05"`) or provide a `cellEditor`.
+
+---
+
+## 7. Troubleshooting
+
+| Problem | Cause and fix |
+| --- | --- |
+| Everything looks unstyled | Import `react-gridix/style.css` once in your app |
+| `theme="ocean"` does nothing | The theme CSS ships in `style.css`: make sure it is imported. The attribute `data-rk-theme` should appear on the grid root |
+| I can't find the filter input | Filters are per column: set `filterable: true` in the column definition, then click the dot in the header. The old grid-level `columnFilters` prop no longer exists |
+| Type error on `field: "contact.phone"` | The path must exist in your row type (optional objects are fine). If `rows` is typed loosely (`any`), type the columns as `ColumnDef<Person>[]` |
+| My checkbox column header is empty | By design: boolean columns default to no label. Set `headerName` to show one |
+| No row animation | `animateRows` is off, or the system has "reduce motion" turned on |
+| My Tailwind class doesn't change the grid | Put it in the right slot (`classNames.headerCell`, and so on). The library CSS has zero specificity, so a class in the right place wins |
+| Edits disappear on the next render | `rows` gets a new identity every render. Keep it in `useState` or `useMemo` |
+| A custom editor or renderer loses focus or resets while typing | The component is defined inline inside render. Move it to module level |
+| Typing in a custom editor column doesn't start editing | By design: custom editors open with double-click, Enter or F2 |
+| Enter doesn't move to the next row | The cell below is locked, you are on the last row of the page, or `enterMovesDown` is `false` |
+| Filtering "active" also shows "inactive" | Filters are substring matches. Use a `filterRenderer` with distinct values or different display text |
+| Changing `pageSize` or `defaultSort` after mount does nothing | They are initial values only |
+| A checkbox in a boolean column is greyed out and won't toggle | The cell isn't editable. Set `editable` on the grid, or `editable: true` on that column |
+| Type error: `field` not assignable | `field` must be a key of your row type. Check the spelling, and that `ColumnDef<T>` uses the same `T` as `rows` |