@dynostack/react-grid 0.3.2 → 0.4.0

package/README.md

@@ -13,12 +13,45 @@ Built on [TanStack Table v8](https://tanstack.com/table) · [Radix UI](https://w
 
 </div>
 
+**[Live showcase](https://dynostack-react-grid.vercel.app)** · **[Interactive playground](https://dynostack-react-grid.vercel.app/playground)** · **[Setup and configuration docs](https://dynostack-react-grid.vercel.app/docs)**
+
+Try every feature on real sample data, customize themes and density, share a configuration link, and copy the matching React props. The demo includes spring-based interactions and works on mobile.
+
 ---
 
 A single `<DataTable />` component that gives you ag-grid–level functionality with a fraction of the API surface and a shadcn/ui aesthetic. Every behavior is opt-in via props — drop it in and it works; configure it and it scales.
 
+## Showcase
+
+<p align="center">
+  <img src="public/table-images/Screenshot%202026-05-25%20233937.png" alt="React data grid with toolbar, sorting, filters, pagination, export, and add-row controls" width="100%" />
+</p>
+
+| Selection + bulk actions | Column menu |
+| --- | --- |
+| <img src="public/table-images/Screenshot%202026-05-25%20234013.png" alt="Rows selected with bulk delete and clear actions visible in the toolbar" width="100%" /> | <img src="public/table-images/Screenshot%202026-05-25%20234035.png" alt="Column menu with ascending sort, descending sort, pin, unpin, and hide column actions" width="100%" /> |
+
+| Filter builder | Column visibility |
+| --- | --- |
+| <img src="public/table-images/Screenshot%202026-05-25%20234221.png" alt="Column filter builder with operator select, value input, add condition, clear, close, and apply controls" width="100%" /> | <img src="public/table-images/Screenshot%202026-05-25%20234246.png" alt="Column visibility popover with checked columns and reset control" width="100%" /> |
+
+| Export selected rows | Inline add and edit |
+| --- | --- |
+| <img src="public/table-images/Screenshot%202026-05-25%20234301.png" alt="Export menu for selected rows with CSV and Excel options" width="100%" /> | <img src="public/table-images/Screenshot%202026-05-25%20234313.png" alt="Inline add-row editing with text fields, select input, date input, save, and cancel controls" width="100%" /> |
+
+| Row actions | Details panel |
+| --- | --- |
+| <img src="public/table-images/Screenshot%202026-05-25%20234410.png" alt="Row actions menu with view, edit, duplicate, and delete commands" width="100%" /> | <img src="public/table-images/Screenshot%202026-05-25%20234428.png" alt="Right-side details panel with compact, relaxed, and comfy density controls" width="100%" /> |
+
+| Search |
+| --- |
+| <img src="public/table-images/Screenshot%202026-05-25%20234453.png" alt="Search input expanded in the table toolbar" width="100%" /> |
+
 ## Highlights
 
+- **Layout and state controls** — `initialSorting`, `onSelectionChange`, `ariaLabel`, `striped`, `stickyHeader`, and `maxHeight`. Disabling pagination renders all matching loaded rows.
+- **Safer exports and editing** — spreadsheet formulas in untrusted text are neutralized; row editing respects `meta.isEditable`; theme values cannot escape scoped CSS declarations.
+
 - **Filters that actually filter** — text, number, date with operators (`contains`, `not contains`, `equals`, `before`, `after`, `in range`, `blank`, `not blank`, …), AND/OR combine of two conditions, and a set filter with search + select-all
 - **Inline editing** — double-click cell to edit, or enter row-edit mode with `Save` / `Cancel`
 - **Add row** — local optimistic insert, edit, then commit on save
@@ -39,6 +72,7 @@ A single `<DataTable />` component that gives you ag-grid–level functionality
 ## Table of contents
 
 - [Install](#install)
+- [Showcase](#showcase)
 - [Tailwind setup](#tailwind-setup)
 - [Theme tokens](#theme-tokens)
 - [Quick start](#quick-start)
@@ -67,6 +101,34 @@ A single `<DataTable />` component that gives you ag-grid–level functionality
 
 ## Install
 
+### Run the showcase locally
+
+```sh
+git clone https://github.com/wanted-coder-vijay/wcv-data-grid.git
+cd wcv-data-grid
+npm install
+npm run build
+npm install --prefix showcase
+npm run showcase:dev
+```
+
+### New layout controls
+
+```tsx
+<DataTable
+  data={rows}
+  columns={columns}
+  initialSorting={[{ id: "name", desc: false }]}
+  onSelectionChange={(selectedRows) => setSelectedRows(selectedRows)}
+  ariaLabel="Project workspace"
+  striped
+  stickyHeader
+  maxHeight="480px"
+/>
+```
+
+`onSelectionChange` returns selected **loaded** row objects; server-side exports and selection do not fetch unseen pages. Editing flags are UI controls: your server must also validate fields, values, and permissions. CSV/Excel exports neutralize formula prefixes in strings while preserving actual numeric values. Excel output remains an HTML-based `.xls`, not native XLSX. Theme tokens reject declaration delimiters, CSS comments, backslash escapes, and URL expressions.
+
 ```sh
 npm i @dynostack/react-grid
 # or
@@ -75,7 +137,7 @@ pnpm add @dynostack/react-grid
 yarn add @dynostack/react-grid
 ```
 
-**Peer deps:** `react >= 18`, `react-dom >= 18`. All other deps (`@tanstack/react-table`, `radix-ui`, `lucide-react`, `class-variance-authority`, `clsx`, `tailwind-merge`) are bundled.
+**Peer deps:** `react >= 18.2`, `react-dom >= 18.2`. All other runtime dependencies (`@tanstack/react-table`, `radix-ui`, `lucide-react`, `class-variance-authority`, `clsx`, `tailwind-merge`) are installed automatically and remain external to the package bundle.
 
 ## Tailwind setup
 
@@ -850,6 +912,12 @@ operations and only renders the returned page.
 | `pageSizeOptions`         | `number[]`                                                 | shadcn defaults        | Page-size dropdown options.                            |
 | `initialColumnPinning`    | `ColumnPinningState`                                       | `{ left: [], right: [] }` | Initial pinned columns.                            |
 | `initialColumnVisibility` | `VisibilityState`                                          | `{}`                   | Initial hidden columns.                                |
+| `initialSorting`          | `SortingState`                                             | `[]`                   | Initial column sort order.                             |
+| `onSelectionChange`       | `(rows: TData[]) => void`                                  | —                      | Observe selected loaded rows.                          |
+| `ariaLabel`               | `string`                                                   | `"Data table"`         | Accessible name for the table.                         |
+| `striped`                 | `boolean`                                                  | `false`                | Alternate row backgrounds.                             |
+| `stickyHeader`            | `boolean`                                                  | `false`                | Keep headers visible in the scroll viewport.           |
+| `maxHeight`               | `CSSProperties["maxHeight"]`                               | —                      | Limit the vertical scroll viewport.                    |
 | `globalFilter`            | `string`                                                   | uncontrolled           | Controlled global filter value.                        |
 | `onGlobalFilterChange`    | `(value: string) => void`                                  | —                      | Controlled global filter setter.                       |
 | `className`               | `string`                                                   | —                      | Extra classes on the table root.                       |

package/dist/index.cjs

@@ -283,15 +283,21 @@ function PopoverContent({
 }
 
 // src/export.ts
+function sanitizeSpreadsheetValue(value) {
+  if (value == null) return "";
+  const text = String(value);
+  if (typeof value === "string" && (/^[\s\u0000-\u001f]*[=+\-@＝＋－＠]/u.test(text) || /^[\t\r\n]/.test(text))) return `'${text}`;
+  return text;
+}
 function escapeCsv(value) {
   if (value === null || value === void 0) return "";
-  const s = String(value);
+  const s = sanitizeSpreadsheetValue(value);
   if (/[",\n\r]/.test(s)) return `"${s.replace(/"/g, '""')}"`;
   return s;
 }
 function escapeHtml(value) {
   if (value === null || value === void 0) return "";
-  return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return sanitizeSpreadsheetValue(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
 function getExportRows(table) {
   const visible = table.getVisibleLeafColumns().filter((c) => {
@@ -1901,7 +1907,7 @@ function EditableCell({
     if (typeof flag === "function") return flag(row.original);
     return flag;
   })();
-  if (!isEditing) {
+  if (!isEditing || !isEditable) {
     const display = renderDisplay(initial, editor, meta);
     return /* @__PURE__ */ jsxRuntime.jsx(
       "div",
@@ -1918,7 +1924,9 @@ function EditableCell({
       }
     );
   }
-  const commit = (value) => onCommit(value);
+  const commit = (value) => {
+    if (isEditable) onCommit(value);
+  };
   const handleKey = (e) => {
     if (e.key === "Enter") commit(local);
     else if (e.key === "Escape") onCancel();
@@ -2048,6 +2056,9 @@ var TOKEN_TO_VAR = {
   radius: "--radius",
   fontFamily: "--font-family"
 };
+function isSafeToken(value) {
+  return typeof value === "string" && !/[;{}<>@\\\u0000-\u001f]/.test(value) && !/\/\*|\*\/|url\s*\(|expression\s*\(/i.test(value);
+}
 function isModed(theme) {
   if (!theme) return false;
   return "light" in theme || "dark" in theme;
@@ -2056,8 +2067,8 @@ function tokensToStyle(tokens) {
   if (!tokens) return {};
   const out = {};
   for (const [k, v] of Object.entries(tokens)) {
-    if (v == null) continue;
-    const cssVar = TOKEN_TO_VAR[k];
+    if (!isSafeToken(v)) continue;
+    const cssVar = Object.prototype.hasOwnProperty.call(TOKEN_TO_VAR, k) ? TOKEN_TO_VAR[k] : void 0;
     if (cssVar) out[cssVar] = v;
   }
   return out;
@@ -2131,8 +2142,8 @@ function tokensToCssBlock(tokens) {
   if (!tokens) return "";
   const parts = [];
   for (const [k, v] of Object.entries(tokens)) {
-    if (v == null) continue;
-    const cssVar = TOKEN_TO_VAR[k];
+    if (!isSafeToken(v)) continue;
+    const cssVar = Object.prototype.hasOwnProperty.call(TOKEN_TO_VAR, k) ? TOKEN_TO_VAR[k] : void 0;
     if (cssVar) parts.push(`${cssVar}:${v}`);
   }
   return parts.join(";");
@@ -2556,6 +2567,10 @@ function useEditingContext() {
   if (!ctx) throw new Error("DataTable editing context missing");
   return ctx;
 }
+function DefaultCellHost(ctx) {
+  const value = ctx.getValue();
+  return value == null ? null : String(value);
+}
 function EditableCellHost(ctx) {
   const {
     editingCell,
@@ -2677,6 +2692,7 @@ var DENSITY_CLASS = {
   default: "",
   comfortable: "[&_tbody_td]:py-2"
 };
+var EMPTY_DATA = [];
 function DataTable({
   data,
   columns,
@@ -2700,6 +2716,12 @@ function DataTable({
   pageSizeOptions,
   initialColumnPinning,
   initialColumnVisibility,
+  initialSorting,
+  onSelectionChange,
+  ariaLabel = "Data table",
+  striped = false,
+  stickyHeader = false,
+  maxHeight,
   globalFilter: globalFilterProp,
   onGlobalFilterChange,
   className,
@@ -2776,7 +2798,7 @@ function DataTable({
     }
     setConfirmCtx(null);
   };
-  const [sorting, setSorting] = react.useState([]);
+  const [sorting, setSorting] = react.useState(initialSorting ?? []);
   const [columnFilters, setColumnFilters] = react.useState([]);
   const [internalGlobalFilter, setInternalGlobalFilter] = react.useState("");
   const isControlledFilter = globalFilterProp !== void 0;
@@ -2872,7 +2894,7 @@ function DataTable({
     // eslint-disable-next-line react-hooks/exhaustive-deps
     ...dataSourceDeps
   ]);
-  const baseData = dataSourceEnabled ? sourceRows : data ?? [];
+  const baseData = dataSourceEnabled ? sourceRows : data ?? EMPTY_DATA;
   const effectiveIsLoading = dataSourceEnabled ? sourceLoading : isLoading;
   const effectiveIsFetching = dataSourceEnabled ? sourceFetching : isFetching;
   const effectiveOnRefresh = dataSourceEnabled ? () => setSourceRefreshKey((key) => key + 1) : onRefresh;
@@ -2916,7 +2938,7 @@ function DataTable({
             title: headerLabel
           }
         ),
-        cell: hasEditor ? EditableCellHost : original
+        cell: hasEditor ? EditableCellHost : original ?? DefaultCellHost
       };
     };
     const built = columns.map(wrap);
@@ -3028,10 +3050,10 @@ function DataTable({
     enableColumnFilters: f.filtering,
     enableColumnResizing: f.resizing,
     columnResizeMode: "onChange",
-    enableRowSelection: true,
+    enableRowSelection: enableSelection,
     enableExpanding: !!(renderSubRow || getSubRows),
     enablePinning: f.pinning,
-    manualPagination: isServerSideDataSource,
+    manualPagination: isServerSideDataSource || !f.pagination,
     manualSorting: isServerSideDataSource,
     manualFiltering: isServerSideDataSource,
     pageCount: isServerSideDataSource ? Math.max(1, Math.ceil(effectiveTotalRecords / pagination.pageSize)) : void 0,
@@ -3121,6 +3143,11 @@ function DataTable({
     setEditingRowId(tempId);
   } : void 0;
   const rows = table.getRowModel().rows;
+  const selectionCallback = react.useRef(onSelectionChange);
+  selectionCallback.current = onSelectionChange;
+  react.useEffect(() => {
+    selectionCallback.current?.(table.getSelectedRowModel().flatRows.map((row) => row.original));
+  }, [rowSelection, mergedData, table]);
   const visibleLeafCount = table.getVisibleLeafColumns().length;
   const editingContextValue = react.useMemo(
     () => ({
@@ -3198,17 +3225,18 @@ function DataTable({
                 labels
               }
             ),
-            /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "relative w-full overflow-auto", children: [
+            /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "relative w-full overflow-auto", style: { maxHeight }, children: [
               /* @__PURE__ */ jsxRuntime.jsxs(
                 "table",
                 {
-                  className: "w-full caption-bottom text-sm",
+                  "aria-label": ariaLabel,
+                  className: cn("w-full caption-bottom text-sm", striped && "[&_tbody>tr:nth-child(even)]:bg-muted/25"),
                   style: {
                     width: table.getCenterTotalSize() ? void 0 : "100%",
                     minWidth: "100%"
                   },
                   children: [
-                    /* @__PURE__ */ jsxRuntime.jsx("thead", { className: "sticky top-0 z-10 bg-card/95 backdrop-blur supports-[backdrop-filter]:bg-card/70", children: table.getHeaderGroups().map((hg) => /* @__PURE__ */ jsxRuntime.jsx("tr", { className: "border-b", children: hg.headers.map((header) => {
+                    /* @__PURE__ */ jsxRuntime.jsx("thead", { className: cn("bg-card", stickyHeader && "sticky top-0 z-10"), children: table.getHeaderGroups().map((hg) => /* @__PURE__ */ jsxRuntime.jsx("tr", { className: "border-b", children: hg.headers.map((header) => {
                       const meta = header.column.columnDef.meta;
                       const isUtility = header.column.id === "__select" || header.column.id === "__expand" || header.column.id === "__actions";
                       const isPinned = !!header.column.getIsPinned();
@@ -3401,6 +3429,7 @@ exports.exportToCsv = exportToCsv;
 exports.exportToExcel = exportToExcel;
 exports.isFilterActive = isFilterActive;
 exports.numberFilterFn = numberFilterFn;
+exports.sanitizeSpreadsheetValue = sanitizeSpreadsheetValue;
 exports.setFilterFn = setFilterFn;
 exports.splitTheme = splitTheme;
 exports.textFilterFn = textFilterFn;