@nexgrid/react 0.1.0 → 0.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 A server-driven data grid for React and Next.js.
 
-NexGrid renders one page of rows at a time and never holds the dataset. Every
+TableX renders one page of rows at a time and never holds the dataset. Every
 piece of user intent — page, page size, sort, search, filters — is expressed as
 a single `QueryState` object that **you** own; the grid hands you the next one
 and re-renders when you hand back the matching page. That is the whole contract.
@@ -10,16 +10,23 @@ There is no local sort that quietly reorders 10 rows out of 40,000, and no
 client-side filter that hides records the total still counts.
 
 Around that core it provides the things every real admin table ends up needing:
-debounced global search, a sort cycle, column visibility, row density,
-selection, formatted Excel and CSV export, a paginated footer with a page-jump,
-loading / empty / error states, and a card layout for phones — all styled by one
-stylesheet shared with the Angular and vanilla adapters, so the same grid looks
-identical on every platform.
+- 🗂️ **Column Header Grouping (Multi-Level / Stacked Headers)** — Group sub-columns beneath parent categories with automatic `colSpan` and `rowSpan` calculation.
+- 🚀 **Client-Side Pagination & In-Memory Engine** — Zero-config in-memory paging, sorting, search, filtering, and export over local arrays.
+- 💾 **Grid State Persistence (`storageKey`)** — Automatically saves column widths, column order, hidden columns, and row density to `localStorage`.
+- ↔️ **Column Resizing & Auto-Fit** — Interactive drag resize handles and double-click auto-fit measuring.
+- 🏷️ **Active Filter Pills Bar** — Interactive chip badges beneath the toolbar for active search & column filters with one-click `✕` removal and "Clear all".
+- 🔍 **Debounced global search** (350 ms), 3-state sorting cycle (`asc → desc → cleared`), multi-column sorting.
+- 📌 **Pinned columns** (left / right freeze), master-detail accordion row expansion, summary/aggregation footer row.
+- 📊 **Formatted Excel (`.xls`) and CSV export**, including whole-dataset export across pages.
+- 📱 **Responsive layout** — Full desktop table at ≥ 768 px, smart card list below.
+- 💛 **Dual Language Support** — 100% compatible with both **TypeScript (TSX)** and **plain JavaScript (JSX)** with JSDoc typing.
 
 - Zero runtime dependencies beyond `@nexgrid/core`. React is a peer dependency.
-- Written for strict TypeScript, generic over your row type.
-- Ships ESM and CJS, with a `"use client"` banner so it drops straight into the
-  Next.js App Router.
+- Ships ESM and CJS, with a `"use client"` banner so it drops straight into the Next.js App Router.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ChhaganSinha/NexGrid/master/docs/assets/tablex-preview.png" alt="TableX React Data Grid Preview" width="100%" />
+</p>
 
 ## Installation
 
@@ -43,10 +50,10 @@ changes, and pass the result straight through.
 
 import { useCallback, useEffect, useState } from "react";
 import {
-  NexGrid,
+  TableX,
   defaultQuery,
   serializeQuery,
-  type NexGridReactColumn,
+  type TableXReactColumn,
   type PagedResponse,
   type QueryState,
 } from "@nexgrid/react";
@@ -60,7 +67,7 @@ interface Student {
   joinedAt: string;
 }
 
-const columns: NexGridReactColumn<Student>[] = [
+const columns: TableXReactColumn<Student>[] = [
   { accessorKey: "name", header: "Name", meta: { minWidth: 180 } },
   { accessorKey: "email", header: "Email" },
   {
@@ -105,7 +112,7 @@ export function StudentsGrid() {
   }, [load, query]);
 
   return (
-    <NexGrid
+    <TableX
       caption="Students"
       columns={columns}
       data={page?.items ?? []}
@@ -132,7 +139,7 @@ Your endpoint must answer with a `PagedResponse<T>`:
 { "items": [], "page": 1, "pageSize": 10, "total": 0, "totalPages": 1 }
 ```
 
-If your API is ASP.NET Core, `NexGrid.AspNetCore` binds exactly the query string
+If your API is ASP.NET Core, `TableX.AspNetCore` binds exactly the query string
 `serializeQuery` produces and returns exactly this shape.
 
 ### Putting the query in the URL
@@ -145,7 +152,7 @@ const searchParams = useSearchParams();
 const router = useRouter();
 const query = useMemo(() => parseQuery(searchParams.toString()), [searchParams]);
 
-<NexGrid
+<TableX
   query={query}
   onQueryChange={(next) => router.replace(`?${serializeQuery(next)}`)}
   {...rest}
@@ -158,7 +165,7 @@ never put the grid into an impossible state.
 
 ## Next.js App Router
 
-The published bundle starts with `"use client"`, so `<NexGrid />` can be imported
+The published bundle starts with `"use client"`, so `<TableX />` can be imported
 directly from a Server Component without a wrapper:
 
 ```tsx
@@ -182,33 +189,41 @@ Two notes:
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `columns` | `NexGridReactColumn<TData>[]` | required | Column definitions, in display order. |
-| `data` | `TData[]` | required | The **current page** of rows only. |
-| `total` | `number` | required | Total filtered row count from the server. Drives the pager. |
-| `query` | `QueryState` | required | The query the `data` above answers. |
-| `onQueryChange` | `(next: QueryState) => void` | required | Called with the next query on page / size / sort / search changes. |
-| `caption` | `string` | required | Accessible name for the table; also the default export file name and sheet title. |
-| `density` | `"compact" \| "default" \| "comfortable"` | `"default"` | **Initial** density. The user owns it afterwards. |
-| `isLoading` | `boolean` | `false` | Replaces the rows with a spinner. The toolbar and footer stay usable. |
-| `error` | `boolean` | `false` | Replaces the **whole grid** with an error card. |
-| `onRetry` | `() => void` | — | When set, the error card offers a retry button. |
-| `enableSelection` | `boolean` | `false` | Renders selection checkboxes. |
-| `onSelectionChange` | `(ids: string[], allAcrossSelected: boolean) => void` | — | Fires after each selection change. `allAcrossSelected` is reserved and always `false`. |
+| `columns` | `TableXReactColumn<TData>[]` | required | Column definitions, in display order (supports multi-level `columns`). |
+| `data` | `TData[]` | required | The current page of rows, or the entire array if `clientSidePagination` is true. |
+| `total` | `number` | optional in client mode | Total filtered row count from the server. Drives the pager. |
+| `query` | `QueryState` | optional in client mode | The query the `data` above answers. |
+| `onQueryChange` | `(next: QueryState) => void` | optional in client mode | Called with the next query on page / size / sort / search changes. |
+| `clientSidePagination` | `boolean` | `false` | Enables zero-config in-memory paging, sorting, search, and filtering over local data. |
+| `storageKey` | `string` | — | Persists custom column widths, column order, hidden columns, and density to `localStorage`. |
+| `caption` | `string` | required | Accessible name for the table; also default export filename and sheet title. |
+| `density` | `"compact" \| "default" \| "comfortable"` | `"default"` | Initial density preset. |
+| `enableColumnResize` | `boolean` | `true` | Enables interactive drag-to-resize and double-click auto-fit on column borders. |
+| `enableColumnFilters` | `boolean` | `true` | Enables 3-dot column filter popovers (⋮) for text, select, and range filters. |
+| `enableSorting` | `boolean` | `true` | Global switch for column sorting. |
+| `enableSummaryRow` | `boolean` | `false` | Renders a summary / aggregation row in `<tfoot>`. |
+| `enableRowExpansion` | `boolean` | `false` | Master-detail accordion expandable sub-rows. |
+| `renderExpandedRow` | `(row: TData) => ReactNode` | — | Render function for expanded row content. |
+| `enableBulkActions` | `boolean` | `false` | Floating bottom pill bar for batch operations on selected rows. |
+| `isLoading` | `boolean` | `false` | Replaces rows with a spinner while keeping toolbar and footer interactive. |
+| `error` | `boolean` | `false` | Replaces the whole grid with an accessible error card. |
+| `onRetry` | `() => void` | — | When set, the error card displays a retry button. |
+| `enableSelection` | `boolean` | `false` | Renders row selection checkboxes. |
+| `selectionMode` | `"multi" \| "single"` | `"multi"` | Whether multiple rows or only one row can be selected. |
+| `onSelectionChange` | `(ids: string[]) => void` | — | Fires after each selection change. |
 | `enableSearch` | `boolean` | `true` | Shows the debounced global search box. |
 | `searchPlaceholder` | `string` | `locale.searchPlaceholder` | Placeholder text for the search box. |
-| `toolbarActions` | `ReactNode` | — | Rendered at the end of the toolbar, after the export menu. |
-| `onRowClick` | `(row: TData) => void` | — | Row / card click handler. Adds a pointer cursor and makes rows keyboard-activatable. |
+| `toolbarActions` | `ReactNode` | — | Custom actions rendered at the end of the toolbar. |
+| `onRowClick` | `(row: TData) => void` | — | Row / card click handler. Adds pointer cursor and keyboard activation. |
 | `getRowId` | `(row: TData) => string` | `String(row.id ?? row)` | Stable row identity, used for selection and React keys. |
-| `className` | `string` | — | Extra class(es) on the grid root. |
-| `showSerialNumber` | `boolean` | `true` | Shows the automatic `S.No.` column, numbered across the whole result set. |
-| `enableExport` | `boolean` | `true` | Shows the export menu. |
-| `exportFileName` | `string` | caption, lower-cased and underscored | File name prefix, without extension. |
-| `onExportAll` | `() => void \| Promise<void>` | — | Takes over exporting entirely; the built-in flow never runs. |
-| `fetchEndpoint` | `string` | — | List endpoint used to page in the rest of the dataset when exporting. |
-| `badgeRules` | `readonly ExcelBadgeRule[]` | core's `DEFAULT_BADGE_RULES` | Value-based cell styling for the Excel export. |
-| `locale` | `Partial<NexGridLocale>` | English defaults | Overrides for any user-facing string. |
-| `onNotify` | `(notice: NexGridNotice) => void` | no-op | Receives `{ type, message }` for export progress, failures, and successes. |
-| `theme` | `"light" \| "dark" \| "auto"` | `"light"` | Adds `.nxg-dark` / `.nxg-auto` to the root. |
+| `showSerialNumber` | `boolean` | `true` | Shows automatic `S.No.` column, numbered across pages. |
+| `enableExport` | `boolean` | `true` | Shows the export menu (Excel, CSV, Clipboard). |
+| `exportFileName` | `string` | caption, slug-safe | File name prefix without extension. |
+| `fetchEndpoint` | `string` | — | Endpoint used to page in the full dataset during export. |
+| `badgeRules` | `readonly ExcelBadgeRule[]` | core's `DEFAULT_BADGE_RULES` | Value-based cell styling for Excel export. |
+| `locale` | `Partial<TableXLocale>` | English defaults | Overrides for any user-facing string. |
+| `onNotify` | `(notice: TableXNotice) => void` | no-op | Receives `{ type, message }` for notifications. |
+| `theme` | `"light" \| "dark" \| "auto"` | `"light"` | Sets `.tbx-dark` / `.tbx-auto` theme mode. |
 
 ## Column definitions
 
@@ -220,9 +235,10 @@ A column is a plain object, structurally compatible with TanStack Table's
 | `id` | `string` | Column id. Falls back to `accessorKey`. |
 | `accessorKey` | `string` | The row property this column reads. |
 | `header` | `string \| (ctx) => ReactNode` | Header content. A string is also used for menus and export headers. |
+| `columns` | `TableXReactColumn<TData>[]` | Nested sub-columns for multi-level stacked column header groups. |
 | `cell` | `(ctx: { row: { original: TData }, getValue(): unknown }) => ReactNode` | Custom cell renderer. Without it the raw value is rendered as text. |
 | `enableSorting` | `boolean` | Sorting is on by default; set `false` to opt out. |
-| `meta` | `NexGridColumnMeta` | Layout and behavior hints — see below. |
+| `meta` | `TableXColumnMeta` | Layout and behavior hints — see below. |
 
 ### `meta`
 
@@ -245,7 +261,7 @@ hideable, and never exported.
 the mobile card list, so the two can never drift apart.
 
 ```tsx
-const columns: NexGridReactColumn<Student>[] = [
+const columns: TableXReactColumn<Student>[] = [
   // A status pill.
   {
     accessorKey: "status",
@@ -298,38 +314,38 @@ Every color and shape in the stylesheet reads a CSS custom property, so you
 re-skin the grid by overriding tokens — no class overrides, no `!important`.
 
 ```css
-.nxg-root {
-  --nxg-primary: #7c3aed;
-  --nxg-primary-fg: #ffffff;
-  --nxg-radius: 8px;
-  --nxg-font: "Inter", system-ui, sans-serif;
+.tbx-root {
+  --tbx-primary: #7c3aed;
+  --tbx-primary-fg: #ffffff;
+  --tbx-radius: 8px;
+  --tbx-font: "Inter", system-ui, sans-serif;
 }
 ```
 
 | Token | Purpose |
 |-------|---------|
-| `--nxg-font`, `--nxg-font-mono` | Body font, and the serial-number font. |
-| `--nxg-bg` | Input and pager background. |
-| `--nxg-card`, `--nxg-card-2` | Panel background, and the table header band. |
-| `--nxg-border` | Every border and divider. |
-| `--nxg-fg`, `--nxg-muted-fg` | Primary and secondary text. |
-| `--nxg-muted` | Hover fills and subtle chips. |
-| `--nxg-primary`, `--nxg-primary-fg` | Accent: sort icons, current page, selection. |
-| `--nxg-danger` | Destructive accents. |
-| `--nxg-radius`, `--nxg-radius-sm` | Panel and control corner radii. |
-| `--nxg-shadow`, `--nxg-focus-ring` | Elevation, and the focus ring. |
+| `--tbx-font`, `--tbx-font-mono` | Body font, and the serial-number font. |
+| `--tbx-bg` | Input and pager background. |
+| `--tbx-card`, `--tbx-card-2` | Panel background, and the table header band. |
+| `--tbx-border` | Every border and divider. |
+| `--tbx-fg`, `--tbx-muted-fg` | Primary and secondary text. |
+| `--tbx-muted` | Hover fills and subtle chips. |
+| `--tbx-primary`, `--tbx-primary-fg` | Accent: sort icons, current page, selection. |
+| `--tbx-danger` | Destructive accents. |
+| `--tbx-radius`, `--tbx-radius-sm` | Panel and control corner radii. |
+| `--tbx-shadow`, `--tbx-focus-ring` | Elevation, and the focus ring. |
 
 Dark mode is a class, not a media query, so it can follow whatever your app
 already uses:
 
 ```tsx
-<NexGrid theme="dark" {...props} />   {/* always dark          */}
-<NexGrid theme="auto" {...props} />   {/* follows the OS       */}
+<TableX theme="dark" {...props} />   {/* always dark          */}
+<TableX theme="auto" {...props} />   {/* follows the OS       */}
 ```
 
-`theme="dark"` puts `.nxg-dark` on the grid root. If your app already toggles a
-dark class higher up the tree, add `nxg-dark` alongside it and leave `theme`
-alone — the stylesheet matches `.nxg-dark .nxg-root` as well.
+`theme="dark"` puts `.tbx-dark` on the grid root. If your app already toggles a
+dark class higher up the tree, add `tbx-dark` alongside it and leave `theme`
+alone — the stylesheet matches `.tbx-dark .tbx-root` as well.
 
 Responsive behavior is driven entirely by the stylesheet: the grid renders both a
 table and a card list, and CSS shows the table at ≥ 768px and the cards below it.
@@ -348,7 +364,7 @@ If those requests fail it notifies you and falls back to the current page rather
 than producing nothing.
 
 ```tsx
-<NexGrid
+<TableX
   fetchEndpoint="/api/students"
   exportFileName="student_roster"
   badgeRules={[
@@ -375,7 +391,7 @@ is `"info" | "success" | "error"`, ready to forward to whatever you already use.
 Every user-facing string comes from a locale object. Override any subset:
 
 ```tsx
-<NexGrid
+<TableX
   locale={{
     searchPlaceholder: "Rechercher…",
     emptyText: "Aucun enregistrement ne correspond à votre recherche.",
@@ -428,5 +444,5 @@ one and that the sort cycle stays `asc → desc → cleared` across every adapte
 
 ## License
 
-[MIT](https://github.com/ChhaganSinha/NexGrid/blob/main/LICENSE) © 2026 Chhagan Sinha
+[MIT](https://github.com/ChhaganSinha/TableX/blob/main/LICENSE) © 2026 Chhagan Sinha