munza-x-data-grid 3.0.0-beta.9 → 3.0.2

package/README.md

@@ -1,288 +1,572 @@
-# munza-x-data-grid
+# Grid Component — Usage Guide
 
-A flexible, feature-rich React data grid component built on top of [@tanstack/react-table](https://tanstack.com/table), with Tailwind CSS v4 styling and shadcn/ui primitives.
+`Grid` is a reusable data-table component built on top of `@tanstack/react-table`, with built-in support for sorting, filtering, pagination, column pinning, row pinning, column resizing, and more.
 
----
-
-## Installation
+## 1. Installation
 
 ```bash
 npm install munza-x-data-grid
+# or
+yarn add munza-x-data-grid
+# or
+pnpm add munza-x-data-grid
 ```
 
-Import the stylesheet in your app entry point:
+**Peer dependencies** (must already be installed in your project):
 
-```js
-import 'munza-x-data-grid/style.css';
+```bash
+npm install react@^18 || ^19 react-dom@^18 || ^19
 ```
 
-### Peer Dependencies
+### Importing the stylesheet
 
-```bash
-npm install react react-dom
-```
+The package ships with a CSS file that needs to be imported once at your app's entry point (e.g. `main.tsx` or `App.tsx`):
 
-Requires **React 18 or 19**.
+```tsx
+import 'munza-x-data-grid/style.css';
+```
 
----
+### Imports
 
-## Basic Usage
+Everything — components, hooks, utilities, and types — is exported from the single package entry point:
 
 ```tsx
-import { Grid, useGridState, type ColumnDef } from 'munza-x-data-grid';
-import 'munza-x-data-grid/style.css';
+import {
+  Grid,
+  useGrid,
+  useGridState,
+  useQueryArgs,
+  URLSearch,
+  type ColumnDef,
+} from 'munza-x-data-grid';
+```
 
-type Person = {
-  firstName: string;
-  lastName: string;
-  age: number;
-};
+> Note: if you're importing from a local source within the same repo (monorepo / linked package), the path may differ, e.g. `./package` or `../package`.
 
-const columns: ColumnDef<Person>[] = [
-  { accessorKey: 'firstName', header: 'First Name' },
-  { accessorKey: 'lastName', header: 'Last Name' },
-  { accessorKey: 'age', header: 'Age' },
-];
+## 2. Basic Usage
 
-const data: Person[] = [{ firstName: 'Alice', lastName: 'Smith', age: 30 }];
+```tsx
+import { useMemo } from 'react';
+import { Grid, useGridState, type ColumnDef } from 'munza-x-data-grid';
+
+const App = () => {
+  const columns = useMemo<ColumnDef<MyDataType, unknown>[]>(
+    () => [
+      {
+        id: 'id',
+        accessorKey: 'id',
+        header: () => <div>ID</div>,
+        cell: (info) => info.getValue(),
+        meta: { filterVariant: 'text' },
+        enableHiding: false,
+      },
+      {
+        id: 'name',
+        accessorKey: 'name',
+        header: () => <div>Name</div>,
+        cell: (info) => info.getValue(),
+        meta: { filterVariant: 'text' },
+      },
+    ],
+    [],
+  );
 
-export default function App() {
   const { state, handlers } = useGridState();
 
   return (
     <Grid
+      payload={{ data: myData, total: 0 }}
       columns={columns}
-      payload={{ data, total: data.length }}
+      isLoading={false}
+      isError={false}
+      manualPagination={true}
       state={state}
       {...handlers}
     />
   );
-}
-```
+};
 
----
+export default App;
+```
 
-## API Reference
+## 3. The `useGridState` Hook
 
-### `<Grid />`
+Use this hook to manage all table state (`columnFilters`, `pagination`, `sorting`, `rowSelection`, `globalFilter`) and their change handlers in one place.
 
-The top-level component that renders the full data grid.
+```tsx
+const { state, handlers, rowSelection } = useGridState();
 
-| Prop                    | Type                                       | Required | Description                                              |
-| ----------------------- | ------------------------------------------ | -------- | -------------------------------------------------------- |
-| `columns`               | `ColumnDef<T>[]`                           | ✅       | Column definitions (TanStack Table format)               |
-| `payload`               | `{ data: T[], total: number }`             | ✅       | Row data and total count for pagination                  |
-| `state`                 | `Partial<TableState>`                      | ✅       | Controlled table state (from `useGridState`)             |
-| `onColumnFiltersChange` | `OnChangeFn<ColumnFiltersState>`           | —        | Callback for column filter changes                       |
-| `onPaginationChange`    | `OnChangeFn<PaginationState>`              | —        | Callback for pagination changes                          |
-| `onSortingChange`       | `OnChangeFn<SortingState>`                 | —        | Callback for sort changes                                |
-| `setGlobalFilter`       | `Dispatch<SetStateAction<string>>`         | —        | Callback to update the global search filter              |
-| `isLoading`             | `boolean`                                  | —        | Displays a loading state                                 |
-| `isError`               | `boolean`                                  | —        | Displays an error state                                  |
-| `manualPagination`      | `boolean`                                  | —        | Set `true` for server-side pagination (default: `false`) |
-| `getRowCanExpand`       | `(row: Row<T>) => boolean`                 | —        | Controls which rows are expandable                       |
-| `renderSubComponent`    | `(props: { row: Row<T> }) => ReactElement` | —        | Renders expanded row content                             |
+<Grid
+  columns={columns}
+  payload={{ data, total }}
+  state={state}
+  {...handlers}
+/>;
+```
 
----
+`handlers` includes:
 
-### `useGridState()`
+- `onColumnFiltersChange`
+- `onPaginationChange`
+- `onSortingChange`
+- `setGlobalFilter`
+- `onRowSelectionChange`
 
-Hook that provides controlled state and event handlers to pass into `<Grid />`.
+You can also use pieces separately, e.g. tracking selected rows via `rowSelection`:
 
 ```tsx
-const { state, handlers } = useGridState();
+console.log(rowSelection);
 ```
 
-**Returns:**
+## 4. `Grid` Component Props
+
+| Prop                    | Type                                       | Description                                                       |
+| ----------------------- | ------------------------------------------ | ----------------------------------------------------------------- |
+| `columns`               | `ColumnDef<T>[]`                           | Table column definitions (required)                               |
+| `payload`               | `{ data: T[]; total: number }`             | Table data and total row count                                    |
+| `state`                 | `Partial<TableState>`                      | State obtained from `useGridState`                                |
+| `onColumnFiltersChange` | `OnChangeFn<ColumnFiltersState>`           | Handler for column filter changes                                 |
+| `onPaginationChange`    | `OnChangeFn<PaginationState>`              | Handler for pagination changes                                    |
+| `onSortingChange`       | `OnChangeFn<SortingState>`                 | Handler for sorting changes                                       |
+| `onRowSelectionChange`  | `OnChangeFn<RowSelectionState>`            | Handler for row selection changes                                 |
+| `setGlobalFilter`       | `Dispatch<SetStateAction<string>>`         | Function to set the global search/filter                          |
+| `manualPagination`      | `boolean`                                  | Set to `true` to enable server-side pagination                    |
+| `enableRowSelection`    | `boolean`                                  | Enables/disables row selection (default `true`)                   |
+| `isLoading`             | `boolean`                                  | Shows the loading state                                           |
+| `isError`               | `boolean`                                  | Shows the error state                                             |
+| `isFetching`            | `boolean`                                  | For a refetching indicator                                        |
+| `refetch`               | `() => void`                               | Function to reload the data                                       |
+| `renderSubComponent`    | `(props: { row: Row<T> }) => ReactElement` | Custom content for expandable rows                                |
+| `getRowCanExpand`       | `(row: Row<T>) => boolean`                 | Determines which rows can be expanded                             |
+| `height`                | `string`                                   | Table height (default `'65vh'`)                                   |
+| `isToolbar`             | `boolean`                                  | Whether to show the toolbar (default `true`)                      |
+| `isPagination`          | `boolean`                                  | Whether to show the pagination component (default `true`)         |
+| `name`                  | `string`                                   | Unique grid name, used to persist local state (default `'munza'`) |
+| `children`              | `ReactNode`                                | Renders extra content inside the grid                             |
+
+## 5. Special Column Definition Features
+
+### Filter variant
+
+Set `meta.filterVariant` on each column to determine the filter type. The following variants are supported:
+
+- `'text'`
+- `'number'`
+- `'tel'`
+- `'url'`
+- `'color'`
+- `'range'`
+- `'select'`
+- `'dateRange'`
+- `'date'`
+- `'datetime-local'`
+- `'month'`
+- `'time'`
+- `'week'`
 
-| Key        | Description                                                                                           |
-| ---------- | ----------------------------------------------------------------------------------------------------- |
-| `state`    | Partial `TableState` object (sorting, pagination, filters, etc.)                                      |
-| `handlers` | Object containing `onSortingChange`, `onPaginationChange`, `onColumnFiltersChange`, `setGlobalFilter` |
+```tsx
+meta: {
+  filterVariant: 'text', // 'number' | 'tel' | 'url' | 'color' | 'range' | 'select' | 'dateRange' | 'date' | 'datetime-local' | 'month' | 'time' | 'week'
+},
+```
 
-Spread `handlers` directly onto `<Grid />`:
+Example — a numeric range filter:
 
 ```tsx
-<Grid state={state} {...handlers} columns={columns} payload={payload} />
+{
+  id: 'price',
+  accessorKey: 'price',
+  header: () => <div>Price</div>,
+  cell: (info) => info.getValue(),
+  meta: { filterVariant: 'range' },
+},
 ```
 
-### Tailwind v4 Setup
+Example — a date filter:
 
-If you're using Tailwind v4, add this to your `app.css` so Tailwind scans the grid's classes:
-
-```css
-@source "../node_modules/munza-x-data-grid/**/*.{js,ts,jsx,tsx}";
-@theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --color-border: var(--border);
-  --color-muted: var(--muted);
-  --color-accent: var(--accent);
-}
+```tsx
+{
+  id: 'createdAt',
+  accessorKey: 'createdAt',
+  header: () => <div>Created At</div>,
+  cell: (info) => info.getValue(),
+  meta: { filterVariant: 'date' },
+},
+```
 
-:root {
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
-  --border: oklch(0.922 0 0);
-  --muted: oklch(0.97 0 0);
-  --accent: oklch(0.97 0 0);
-}
+To disable filtering on a specific column:
 
-.dark {
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
-  --border: oklch(1 0 0 / 10%);
-  --muted: oklch(0.269 0 0);
-  --accent: oklch(0.269 0 0);
-}
+```tsx
+enableColumnFilter: false,
 ```
 
----
-
-## Column Definitions
+### Row pinning
 
-Columns follow the standard [TanStack Table `ColumnDef`](https://tanstack.com/table/latest/docs/api/core/column-def) format with an additional `meta` field for filter configuration.
+Use `row.pin()` and `row.getIsPinned()` to pin/unpin rows:
 
-### Filter Variants
+```tsx
+cell: ({ row }) =>
+  row.getIsPinned() ? (
+    <button onClick={() => row.pin(false)}>❌</button>
+  ) : (
+    <>
+      <button onClick={() => row.pin('top')}>⬆️</button>
+      <button onClick={() => row.pin('bottom')}>⬇️</button>
+    </>
+  ),
+```
 
-Set `meta.filterVariant` on a column to control its filter UI:
+### Row number column
 
 ```tsx
 {
-  accessorKey: 'status',
-  header: 'Status',
-  meta: {
-    filterVariant: 'select', // dropdown filter
+  accessorFn: (_row, index) => index + 1,
+  id: 'rowNumber',
+  header: '#',
+  cell: ({ row, table }) => {
+    const { pageIndex, pageSize } = table.getState().pagination;
+    return pageIndex * pageSize + row.index + 1;
   },
-}
+},
+```
 
-{
-  accessorKey: 'age',
-  header: 'Age',
-  meta: {
-    filterVariant: 'text', // text input filter
-  },
-}
+### Column size limits
+
+```tsx
+size: 52,
+maxSize: 52,
 ```
 
-### Row Number Column
+### Non-hideable column
 
 ```tsx
-{
-  accessorFn: (_row, index) => index + 1,
-  cell: ({ row }) => row.index + 1,
-  id: 'rowNumber',
-  header: '',
-  size: 54,
-  maxSize: 54,
-  enableColumnFilter: false,
-}
+enableHiding: false,
 ```
 
-### Checkbox Selection Column
+## 6. Building Server-Side Queries
+
+Use the `useQueryArgs` hook to build query parameters from the table state that can be sent to an API:
 
 ```tsx
-{
-  id: 'select',
-  header: ({ table }) => (
-    <Checkbox
-      checked={
-        table.getIsAllPageRowsSelected() ||
-        (table.getIsSomePageRowsSelected() && 'indeterminate')
-      }
-      onCheckedChange={(value) => table.toggleAllPageRowsSelected(!!value)}
-      aria-label="Select all"
-    />
-  ),
-  cell: ({ row }) => (
-    <Checkbox
-      checked={row.getIsSelected()}
-      onCheckedChange={(value) => row.toggleSelected(!!value)}
-      aria-label="Select row"
-    />
-  ),
-  size: 40,
-  maxSize: 40,
-  enableColumnFilter: false,
-}
+import { useQueryArgs } from 'munza-x-data-grid';
+
+const { pagination, queryParams, sort, globalFilter } = useQueryArgs(state);
 ```
 
----
+(`useQueryArgs` is exported from the same main entry point, no separate sub-path needed.)
+
+It returns:
+
+- `pagination` — current page/page size
+- `queryParams` — query parameters built from column filters
+- `sort` — sort string
+- `globalFilter` — global search text
+
+## 7. Syncing State to the URL — `URLSearch`
 
-## Server-Side Pagination
+`URLSearch` converts the grid's query state (`QueryArgs`) into a MongoDB-style query string, so you can sync table state to the URL or forward it straight to a REST API that understands Mongo-style filter operators.
 
-Set `manualPagination` to `true` and pass `payload.total` as the full server-side count.
+### Import
 
 ```tsx
-<Grid
-  columns={columns}
-  payload={{ data: serverData, total: serverTotal }}
-  state={state}
-  {...handlers}
-  manualPagination={true}
-/>
+import { URLSearch } from 'munza-x-data-grid';
 ```
 
-The built-in pagination UI supports the following page sizes:
+### `QueryArgs` shape
 
+```ts
+interface ColumnFilter {
+  id: string;
+  value: unknown;
+}
+
+interface SortingItem {
+  id: string;
+  desc: boolean;
+}
+
+interface Pagination {
+  pageIndex: number;
+  pageSize: number;
+}
+
+interface QueryArgs {
+  columnFilters: ColumnFilter[];
+  globalFilter?: string;
+  pagination: Pagination;
+  sorting: SortingItem[];
+  rowSelection?: Record<string, boolean>;
+}
 ```
-20, 30, 40, 50, 60, 70, 80, 90, 100, 200, 300, 400, 500, 600, 700, 800, 900, 1000
+
+### Basic usage
+
+```tsx
+const { state } = useGridState();
+
+console.log(URLSearch(state));
+// e.g. "?page=1&limit=20&sort=-createdAt&q=john"
 ```
 
----
+### What it does
+
+`URLSearch(queryArgs: QueryArgs): string` builds a `URLSearchParams` string with the following rules:
+
+| State                  | Resulting query param(s)                                                                        |
+| ---------------------- | ----------------------------------------------------------------------------------------------- |
+| `pagination.pageIndex` | `page` (1-indexed, so `pageIndex + 1`)                                                          |
+| `pagination.pageSize`  | `limit`                                                                                         |
+| `sorting`              | `sort` — comma-separated column ids, prefixed with `-` for descending (e.g. `sort=-price,name`) |
+| `globalFilter`         | `q` — only included if non-empty                                                                |
+| `columnFilters`        | one or more params per filter, see below                                                        |
+
+### Column filter handling
+
+Each entry in `columnFilters` is passed through `appendColumnFilter`, which converts the filter's `id` into dot-notation (underscores become dots — useful for nested/populated fields) and then branches on the shape of `value`:
+
+1. **Range value** — a 2-item array (e.g. from a `range` or `dateRange` filter):
+
+   ```ts
+   { id: 'price', value: [10, 100] }
+   // → price[gte]=10&price[lte]=100
+   ```
+
+   Empty/`null` bounds are skipped, so `[null, 100]` only sets `price[lte]=100`.
+
+2. **Operator object** — a plain object whose keys are MongoDB-style operators:
+
+   ```ts
+   { id: 'status', value: { in: ['active', 'pending'] } }
+   // → status[in]=active,pending
+   ```
+
+   Only keys present in the supported operator list are included; unsupported keys and empty/`null` values are ignored.
 
-## Expandable Rows
+3. **Plain scalar value** — anything else (string, number, boolean):
+   ```ts
+   { id: 'name', value: 'john' }
+   // → name=john
+   ```
+   Empty strings and `null`/`undefined` are skipped entirely.
+
+### Supported MongoDB-style operators
+
+```
+eq, ne, gt, gte, lt, lte, in, nin, regex, exists, all, size,
+elemMatch, type, mod, not, and, or, nor, text, where,
+geoWithin, geoIntersects, near, nearSphere, expr, jsonSchema,
+bitsAllClear, bitsAllSet, bitsAnyClear, bitsAnySet, rand
+```
+
+Any operator outside this list is silently dropped from the query string.
+
+### Full example
 
 ```tsx
-<Grid
-  columns={columns}
-  payload={payload}
-  state={state}
-  {...handlers}
-  getRowCanExpand={(row) => !!row.original.subRows?.length}
-  renderSubComponent={({ row }) => (
-    <div className="p-4">
-      <pre>{JSON.stringify(row.original, null, 2)}</pre>
-    </div>
-  )}
-/>
+const queryArgs: QueryArgs = {
+  pagination: { pageIndex: 0, pageSize: 20 },
+  sorting: [{ id: 'createdAt', desc: true }],
+  globalFilter: 'john',
+  columnFilters: [
+    { id: 'price', value: [10, 100] },
+    { id: 'status', value: { in: ['active', 'pending'] } },
+    { id: 'department_name', value: 'Engineering' },
+  ],
+};
+
+URLSearch(queryArgs);
+// "?page=1&limit=20&price[gte]=10&price[lte]=100&status[in]=active%2Cpending&department.name=Engineering&sort=-createdAt&q=john"
 ```
 
----
+> Note: `department_name` becomes `department.name` — underscores in a column `id` are converted to dots, which is handy for filtering on nested/populated document fields in MongoDB-backed APIs.
 
-## Column Pinning
+## 8. Customizing via `useGrid` (inside `<Grid>` children)
 
-Column pinning is managed internally by the grid. No additional configuration is required — use the built-in toolbar UI to pin columns left or right.
+`Grid` exposes its internal context — the live `@tanstack/react-table` `table` instance, density, split-view state, column pinning, scroll pane refs, and more — through the `useGrid()` hook. This lets you build custom toolbar buttons, headers, footers, or any other UI that needs access to the table without having to lift state yourself.
 
----
+> **Important:** `useGrid()` only works **inside** `<Grid>` — i.e. in a component rendered as a _child_ of `<Grid>`. Calling it in the same component that renders `<Grid>` (like your `App` component) will throw, because the context provider wraps `Grid`'s children, not `Grid` itself.
 
-## Default Column Sizing
+### Import
 
-| Property  | Default |
-| --------- | ------- |
-| `size`    | `180px` |
-| `minSize` | `180px` |
-| `maxSize` | `180px` |
+```tsx
+import { Grid, useGrid } from 'munza-x-data-grid';
+```
 
-Override per-column:
+### What `useGrid()` returns
+
+| Property                               | Type                        | Description                                                                                                             |
+| -------------------------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `table`                                | `Table<T>`                  | The underlying `@tanstack/react-table` instance — full access to rows, columns, filtering/sorting/pagination APIs, etc. |
+| `density`                              | `DensityState`              | Current row density (e.g. compact/comfortable)                                                                          |
+| `isSplit` / `setIsSplit`               | `boolean` / setter          | Split-view state, for side-by-side pinned/unpinned panes                                                                |
+| `columnPinning`                        | `ColumnPinningState`        | Current left/right pinned columns                                                                                       |
+| `globalFilter`                         | `string`                    | The current global search text                                                                                          |
+| `setGlobalFilter`                      | setter                      | Update the global search text                                                                                           |
+| `isLoading` / `isError` / `isFetching` | `boolean`                   | Data-fetch status flags passed down to `Grid`                                                                           |
+| `refetch`                              | `() => void`                | Re-triggers the data fetch, if provided to `Grid`                                                                       |
+| `height`                               | `string`                    | The table height passed to `Grid`                                                                                       |
+| `renderSubComponent`                   | function                    | The expanded-row renderer passed to `Grid`                                                                              |
+| `gridWrapperRef`                       | `RefObject<HTMLDivElement>` | Ref to the grid's outer wrapper element                                                                                 |
+| `paneRef1`–`paneRef6`                  | `RefObject<HTMLDivElement>` | Refs to the internal scroll panes (pinned-left/main/pinned-right, header/body), used for scroll syncing                 |
+
+### Example — a custom toolbar button using `table`
 
 ```tsx
-{
-  accessorKey: 'id',
-  size: 60,
-  minSize: 60,
-  maxSize: 60,
+import { Grid, useGrid, useGridState } from 'munza-x-data-grid';
+
+const ResetFiltersButton = () => {
+  const { table } = useGrid();
+
+  return (
+    <button onClick={() => table.resetColumnFilters()}>Clear filters</button>
+  );
+};
+
+const App = () => {
+  const { state, handlers } = useGridState();
+
+  return (
+    <Grid
+      payload={{ data, total }}
+      columns={columns}
+      state={state}
+      {...handlers}
+    >
+      <ResetFiltersButton />
+    </Grid>
+  );
+};
+```
+
+### Example — reading selected rows from `table`
+
+```tsx
+const SelectionSummary = () => {
+  const { table } = useGrid();
+  const selectedCount = table.getSelectedRowModel().rows.length;
+
+  return <span>{selectedCount} row(s) selected</span>;
+};
+
+<Grid columns={columns} payload={{ data, total }} state={state} {...handlers}>
+  <SelectionSummary />
+</Grid>;
+```
+
+### Example — toggling density or split view
+
+```tsx
+const ViewControls = () => {
+  const { density, isSplit, setIsSplit } = useGrid();
+
+  return (
+    <div>
+      <span>Density: {density}</span>
+      <button onClick={() => setIsSplit((prev) => !prev)}>
+        {isSplit ? 'Unsplit view' : 'Split view'}
+      </button>
+    </div>
+  );
+};
+
+<Grid columns={columns} payload={{ data, total }} state={state} {...handlers}>
+  <ViewControls />
+</Grid>;
+```
+
+## 9. Theming
+
+`Grid` is styled with CSS variables, so you can restyle it (including light/dark mode) without touching component code. Define these variables in your global stylesheet — the `:root` block sets the light theme, and the `.dark` block overrides it for dark mode (e.g. toggled via a `dark` class on `<html>` or `<body>`).
+
+```css
+:root {
+  --background: oklch(100% 0 0);
+  --foreground: oklch(14.5% 0 0);
+  --primary: oklch(20.5% 0 0);
+  --primary-foreground: oklch(98.5% 0 0);
+  --secondary: oklch(97% 0 0);
+  --secondary-foreground: oklch(20.5% 0 0);
+  --muted: oklch(97% 0 0);
+  --muted-foreground: oklch(55.6% 0 0);
+  --accent: oklch(97% 0 0);
+  --accent-foreground: oklch(20.5% 0 0);
+  --destructive: oklch(57.7% 0.245 27.325);
+  --border: oklch(92.2% 0 0);
+  --input: oklch(92.2% 0 0);
+  --ring: oklch(70.8% 0 0);
+  --radius: 0.625rem;
+}
+
+.dark {
+  --background: oklch(14.5% 0 0);
+  --foreground: oklch(98.5% 0 0);
+  --primary: oklch(92.2% 0 0);
+  --primary-foreground: oklch(20.5% 0 0);
+  --secondary: oklch(26.9% 0 0);
+  --secondary-foreground: oklch(98.5% 0 0);
+  --muted: oklch(26.9% 0 0);
+  --muted-foreground: oklch(70.8% 0 0);
+  --accent: oklch(26.9% 0 0);
+  --accent-foreground: oklch(98.5% 0 0);
+  --destructive: oklch(70.4% 0.191 22.216);
+  --border: oklch(100% 0 0/0.1);
+  --input: oklch(100% 0 0/0.15);
+  --ring: oklch(55.6% 0 0);
 }
 ```
 
----
+### Where to put it
 
-## TypeScript
+Add this CSS **after** the package stylesheet import, so your custom values override the defaults:
 
-All props and hooks are fully typed. Import types directly from the package:
+```tsx
+import 'munza-x-data-grid/style.css';
+import './theme.css'; // your theme variables above
+```
 
-```ts
-import type { ColumnDef } from 'munza-x-data-grid';
+### Variable reference
+
+| Variable                 | Used for                                                     |
+| ------------------------ | ------------------------------------------------------------ |
+| `--background`           | Base grid/page background                                    |
+| `--foreground`           | Default text color                                           |
+| `--primary`              | Primary buttons/actions, active states                       |
+| `--primary-foreground`   | Text/icon color on top of `--primary`                        |
+| `--secondary`            | Secondary buttons, toolbar surfaces                          |
+| `--secondary-foreground` | Text/icon color on top of `--secondary`                      |
+| `--muted`                | Subtle backgrounds (e.g. striped rows, disabled states)      |
+| `--muted-foreground`     | Secondary/lower-emphasis text                                |
+| `--accent`               | Hover/highlight backgrounds                                  |
+| `--accent-foreground`    | Text/icon color on top of `--accent`                         |
+| `--destructive`          | Error states, destructive actions (e.g. delete)              |
+| `--border`               | Table/cell/input borders                                     |
+| `--input`                | Input field borders/backgrounds                              |
+| `--ring`                 | Focus ring color                                             |
+| `--radius`               | Base border radius, used to derive component corner rounding |
+
+### Toggling dark mode
+
+Add/remove the `dark` class on a parent element (commonly `<html>`):
+
+```tsx
+document.documentElement.classList.toggle('dark');
 ```
 
-TanStack Table types (`Row`, `TableState`, `PaginationState`, etc.) are re-exported and available from `@tanstack/react-table`.
+## 10. Example: Full Flow
+
+```tsx
+const { state, handlers } = useGridState();
+const queryArgs = useQueryArgs(state);
+
+// Call your API with queryArgs, then pass the result as payload
+<Grid
+  payload={{ data: apiResponse.data, total: apiResponse.total }}
+  columns={columns}
+  manualPagination
+  isLoading={isFetching}
+  isError={isError}
+  refetch={refetch}
+  state={state}
+  {...handlers}
+/>;
+```