@opencorestack/opengridx 0.1.9 → 1.0.0

package/docs/README.md

@@ -22,6 +22,9 @@ Detailed reference for the core structural components.
 - **[Column Visibility](components/column-visibility.md)** - Managing visible fields
 - **[Column Grouping](components/column-group-header.md)** - Multi-level nested headers
 - **[Column Resizing](components/column-resize.md)** - Dynamic width controls
+- **[Empty State](components/empty-state.md)** - No-rows overlay and `noRowsOverlay` slot
+- **[Error Overlay](components/error-overlay.md)** - Data source error display
+- **[Aggregation Footer](components/aggregation-footer.md)** - Sticky totals row
 ---
 
 ## 🚀 Features
@@ -55,6 +58,17 @@ Make the grid your own.
 
 ---
 
+## 🏛️ Architecture — Internal Hooks
+Reference for core hooks extracted from `DataGrid.tsx`. Intended for contributors.
+
+- **[useGridControlledState](architecture/use-grid-controlled-state.md)** - Controlled/uncontrolled state for all 7 state pairs
+- **[useGridRowPipeline](architecture/use-grid-row-pipeline.md)** - Filter → pin → sort → paginate row pipeline
+- **[useGridVirtualization](architecture/use-grid-virtualization.md)** - Render context and scroll-position math
+- **[useGridColumns](architecture/use-grid-columns.md)** - Column management: effective, ordered, visible, reorder handlers
+- **[useGridVisibleRows](architecture/use-grid-visible-rows.md)** - Render window: pinned + virtual center merge
+- **[useGridScrollSync](architecture/use-grid-scroll-sync.md)** - RAF-batched scroll tick, scrollPosRef, onRowsScrollEnd threshold
+- **[useGridStateSnapshot](architecture/use-grid-state-snapshot.md)** - onStateChange callback delivery on sort/filter/pagination/column changes
+
 ## 🛠️ Project Meta
 - **[Development Roadmap](roadmap.md)** - What's built and what's next
 - **[Research Notes](research/FEATURE_CATALOG.md)** - Comparative analysis and design decisions

package/docs/components/aggregation-footer.md

@@ -0,0 +1,48 @@
+# `<GridAggregationFooter />`
+
+Internal component that renders the sticky aggregation totals row pinned to the bottom of the grid. Displays function name labels (e.g. `sum`, `avg`) alongside their computed values for each configured column.
+
+## ⚙️ Props
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `columns` | `GridColDef[]` | Ordered list of visible column definitions used to lay out cells. |
+| `aggregationModel` | `GridAggregationModel` | Maps field names to function names (`'sum' \| 'avg' \| 'count' \| 'min' \| 'max'`). |
+| `aggregationResult` | `GridAggregationResult` | Computed values keyed by field name, produced by `useAggregation`. |
+| `columnWidths` | `Record<string, number>` | Runtime pixel widths for each field, kept in sync with user resize actions. |
+| `rowHeight` | `number` | Sets `min-height` on the footer row, matching the grid's configured row height. |
+| `checkboxSelection` | `boolean` | When `true`, inserts a 48px spacer at the start to align with the checkbox column. |
+| `hasDetailPanel` | `boolean` | When `true`, inserts a 48px spacer to align with the expand/collapse column. |
+| `rowReordering` | `boolean` | When `true`, inserts a 48px spacer to align with the drag handle column. |
+
+## 🔄 When it renders
+
+`GridAggregationFooter` renders when `aggregationModel` has at least one entry and `aggregationResult` contains the corresponding computed values. The footer is sticky — it remains visible when the user scrolls vertically.
+
+## 🔢 Value formatting
+
+Values are formatted by `formatAggregationValue` from `useAggregation`:
+- `count` → integer (e.g. `42`)
+- `sum` / `avg` / `min` / `max` → `toLocaleString()` with up to 2 decimal places
+
+## 🎨 Usage via DataGrid prop
+
+```tsx
+<DataGrid
+    aggregationModel={{
+        salary: 'sum',
+        age: 'avg',
+        department: 'count'
+    }}
+/>
+```
+
+The footer renders automatically. No additional configuration required.
+
+## ♿ Accessibility
+
+The footer row uses `role="row"` and `aria-label="Aggregation totals"`. Each cell uses `role="gridcell"`. The container uses `aria-live="polite"` so screen readers announce value updates when the data changes.
+
+## 🔗 Related
+- [DataGrid](datagrid.md)
+- [Aggregation & Pivot](../features/aggregation-pivot.md)

package/docs/components/datagrid.md

@@ -68,3 +68,6 @@ Customize internal components using the `slots` prop.
 - [Column Visibility](column-visibility.md)
 - [Column Grouping](column-group-header.md)
 - [Column Resizing](column-resize.md)
+- [Empty State](empty-state.md)
+- [Error Overlay](error-overlay.md)
+- [Aggregation Footer](aggregation-footer.md)

package/docs/components/empty-state.md

@@ -0,0 +1,50 @@
+# `<GridEmptyState />`
+
+Internal component rendered when the grid has no rows to display. Replaces the row viewport with a centered icon and message.
+
+## ⚙️ Props
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `noRowsLabel` | `string` | Text shown beneath the empty-state icon. Controlled by the `noRowsLabel` DataGrid prop. |
+| `width` | `number` | Pixel width of the empty-state container, matched to the grid's total column width. |
+
+## 🔄 When it renders
+
+`GridEmptyState` renders when `allRenderableRows.length === 0` and the grid is not in a loading state. The loading skeleton takes precedence — if `loading={true}` the skeleton rows are shown instead.
+
+## 🎨 Customizing via slot
+
+Replace the default empty state with any React component using the `noRowsOverlay` slot:
+
+```tsx
+function MyEmptyState() {
+    return (
+        <div style={{ textAlign: 'center', padding: '40px' }}>
+            <p>No results match your filter.</p>
+            <button onClick={clearFilters}>Clear filters</button>
+        </div>
+    );
+}
+
+<DataGrid
+    slots={{ noRowsOverlay: MyEmptyState }}
+    slotProps={{ noRowsOverlay: { /* custom props if needed */ } }}
+/>
+```
+
+## 💬 Custom label (without a full slot replacement)
+
+To only change the message text without replacing the whole component, use `noRowsLabel`:
+
+```tsx
+<DataGrid
+    noRowsLabel="No employees found for this department."
+/>
+```
+
+Default value: `"No rows"`
+
+## 🔗 Related
+- [DataGrid](datagrid.md)
+- [Loading States](../features/loading-states.md)

package/docs/components/error-overlay.md

@@ -0,0 +1,40 @@
+# `<GridErrorOverlay />`
+
+Internal component rendered when a `GridDataSource` fetch fails. Displays an error icon, a human-readable message, and a **Retry** button that calls `window.location.reload()`.
+
+## ⚙️ Props
+
+| Prop | Type | Description |
+| :--- | :--- | :--- |
+| `error` | `{ message?: string } \| null` | The error object from `state.dataSource.error`. When `null` the component renders nothing (`null` return). |
+
+## 🔄 When it renders
+
+`GridErrorOverlay` only appears when using a server-side `dataSource` prop. When a fetch throws, DataGrid catches the error and stores it in internal state. The overlay replaces the row viewport until the user retries.
+
+```tsx
+<DataGrid
+    dataSource={{
+        getRows: async ({ filterModel, sortModel, paginationModel }) => {
+            const res = await fetch('/api/employees');
+            if (!res.ok) throw new Error(`HTTP ${res.status}`);
+            return res.json();
+        }
+    }}
+/>
+```
+
+If `getRows` throws, the overlay renders with the thrown error's `message`.
+
+## ♿ Accessibility
+
+The overlay container uses `role="alert"` and `aria-live="assertive"` so screen readers announce the error immediately when it appears.
+
+## 🎨 Customizing
+
+`GridErrorOverlay` is not currently exposed as a configurable slot. To implement custom error handling, catch errors in your `dataSource.getRows` and manage the error display in your own component wrapping the grid.
+
+## 🔗 Related
+- [DataGrid](datagrid.md)
+- [Data Source](../features/data-source.md)
+- [Loading States](../features/loading-states.md)

package/docs/roadmap.md

@@ -54,6 +54,20 @@ This document tracks the current status of features in `OpenGridX` and outlines
 *   **Demo**: `AdvancedExcelExportDemo` in demo app (`Data Management` category).
 *   **Docs**: `docs/features/export-guide.md` fully updated with feature comparison table and all options.
 
+### Code Quality & Architecture *(completed 2026-07-29 → 2026-07-30)*
+*   **DataGrid decomposition**: Extracted `useGridControlledState`, `useGridRowPipeline`, `useGridVirtualization`, `useGridScrollSync`, `useGridVisibleRows`, `useGridColumns` hooks, plus `GridEmptyState`, `GridErrorOverlay`, `GridAggregationFooter`, `GridVirtualRows`, `GridPinnedRows`, `GridStandaloneColumnPanel`, `GridListView` components from `DataGrid.tsx`. Each module has a single clear responsibility with typed params and return interfaces.
+*   **Full `any` elimination**: Every `any` across `lib/` replaced with proper types or `unknown`. `GridRowModel` index signature, all cell/value/error params, aggregation functions, slot types, and export utilities are now fully typed. Zero `eslint-disable` suppressions remain — every case fixed at the root.
+*   **Regression test suite**: 3 test files covering column-visibility-model persistence, pivot aggregation correctness including grand-total avg and null-value exclusion, and pagination rendering/row key stability.
+*   **Pivot null-value fix**: `Number(null) === 0` caused null numeric fields to be silently included as `0` in avg/min/max pivot aggregation. Both the per-row bucket loop and the grand-total bucket loop in `usePivot.ts` now guard with `raw != null` before pushing values.
+
+### Bug Fixes *(completed 2026-07-30)*
+*   **`onRowClick` never fired when `onCellClick` was registered**: `Cell.tsx` called `e.stopPropagation()` on every cell click, silently preventing events from reaching the row's `onClick` handler. Removed — both callbacks now fire in natural bubble order.
+*   **Column visibility panel order not updating after reorder**: Panel received `effectiveColumns` (pre-ordering, definition order) instead of `orderedColumns`. Fixed — panel list now reflects the live reordered sequence.
+*   **Reset button ignoring column sequence**: Reset only restored visibility; column order was left wherever the user dragged it. Added `onColumnOrderReset` callback that restores `internalColumnOrder` to original definition order.
+*   **`FilterPanel` debounce stale-closure**: Debounce effect read `item`/`col.field`/`currentOperator` from stale closure, previously suppressed with `eslint-disable`. Replaced with `useLayoutEffect` refs-sync pattern.
+*   **`FilterPanelDemo` inaccessible**: Missing `slots={{ toolbar: GridToolbar }}` meant the filter panel had no UI entry point. Fixed; demo also migrated to `DocsLayout`.
+*   **`EventsDemo` dead handlers**: Fixed broken `onRowClick`, dead filter/column-order callbacks, and three `any`-typed handler signatures.
+
 ---
 
 ## 📅 Upcoming Features
@@ -66,6 +80,11 @@ This document tracks the current status of features in `OpenGridX` and outlines
 ### DX & Publishing
 *   **npm publish**: Finalize `package.json` metadata, `README.md`, and publish to npm registry.
 
+### Demo Site
+*   **Full source viewer coverage**: Migrate all 32 examples to `DocsLayout` using Vite `?raw` auto-loading (eliminates string-literal source maintenance). See `docs/superpowers/plans/2026-07-29-demo-app-refactor.md`.
+*   **Syntax highlighting**: Prism.js token-based highlighting in the source viewer.
+*   **GitHub Pages deployment**: CI/CD via GitHub Actions (`base: '/OpenGridX/'` already configured in `vite.config.js`).
+
 ## ✅ Implemented Features (Recent)
-*   **Storybook / Docs site**: Interactive component documentation with source code viewer and categorized navigation (implemented via `demo` app).
+*   **Demo app (partial)**: 32 interactive examples across 6 categories (Main features, Advanced features, Components, Customization, Tutorials, Resources) with categorized sidebar navigation and per-page Table of Contents. Source code viewer present on 6 of 32 examples. Syntax highlighting and public deployment are in the upcoming Demo Site section above.
 *   **Quickstart & Installation Guides**: Comprehensive onboarding documentation for developers.

package/lib/components/Cell/Cell.tsx

@@ -7,9 +7,9 @@ import { GridEditInputCell } from './GridEditInputCell';
 
 export interface CellProps<R extends GridRowModel = GridRowModel> {
     onCellClick?: (params: GridCellParams<R>) => void;
-    onCellEditStart?: (field: string, value: any) => void;
-    onCellValueChange?: (field: string, newValue: any) => void;
-    value: any;
+    onCellEditStart?: (field: string, value: unknown) => void;
+    onCellValueChange?: (field: string, newValue: unknown) => void;
+    value: unknown;
     row: R;
     colDef: GridColDef<R>;
     rowIndex: number;
@@ -27,7 +27,7 @@ export interface CellProps<R extends GridRowModel = GridRowModel> {
     isEditing?: boolean;
     onEditStart?: () => void;
     onEditStop?: (cancel?: boolean) => void;
-    onValueChange?: (newValue: any) => void;
+    onValueChange?: (newValue: unknown) => void;
 
     colSpanInfo?: CellColSpanInfo;
     rowSpan?: number;
@@ -63,7 +63,7 @@ function CellImpl<R extends GridRowModel = GridRowModel>(props: CellProps<R>) {
     } = props;
 
     // All hooks must come before any early returns (Rules of Hooks)
-    const handleValueChange = React.useCallback((newValue: any) => {
+    const handleValueChange = React.useCallback((newValue: unknown) => {
         if (onCellValueChange) {
             onCellValueChange(colDef.field, newValue);
         } else {
@@ -94,7 +94,7 @@ function CellImpl<R extends GridRowModel = GridRowModel>(props: CellProps<R>) {
                     value,
                     row,
                     field: colDef.field,
-                    colDef: colDef as any,
+                    colDef,
                     rowIndex,
                     colIndex
                 });
@@ -104,7 +104,7 @@ function CellImpl<R extends GridRowModel = GridRowModel>(props: CellProps<R>) {
                     value={value}
                     row={row}
                     field={colDef.field}
-                    colDef={colDef as any}
+                    colDef={colDef as unknown as GridColDef}
                     rowIndex={rowIndex}
                     colIndex={colIndex}
                     onValueChange={handleValueChange}
@@ -119,7 +119,7 @@ function CellImpl<R extends GridRowModel = GridRowModel>(props: CellProps<R>) {
                 value,
                 row,
                 field: colDef.field,
-                colDef: colDef as any,
+                colDef,
                 rowIndex,
                 colIndex
             });
@@ -131,7 +131,7 @@ function CellImpl<R extends GridRowModel = GridRowModel>(props: CellProps<R>) {
     const resolvedCellClassName = React.useMemo(() => {
         if (!colDef.cellClassName) return '';
         if (typeof colDef.cellClassName === 'function') {
-            return colDef.cellClassName({ value, row, field: colDef.field, colDef: colDef as any, rowIndex, colIndex }) || '';
+            return colDef.cellClassName({ value, row, field: colDef.field, colDef, rowIndex, colIndex }) || '';
         }
         return colDef.cellClassName;
     }, [colDef, value, row, rowIndex, colIndex]);
@@ -162,7 +162,6 @@ function CellImpl<R extends GridRowModel = GridRowModel>(props: CellProps<R>) {
 
     const handleClick = (e: React.MouseEvent) => {
         if (onCellClick) {
-            e.stopPropagation();
             onCellClick({
                 row,
                 field: colDef.field,

package/lib/components/Cell/GridEditInputCell.tsx

@@ -2,7 +2,7 @@ import { useEffect, useRef, useState } from 'react';
 import type { GridRenderCellParams } from '../../types';
 
 export interface GridEditInputCellProps extends GridRenderCellParams {
-    onValueChange: (value: any) => void;
+    onValueChange: (value: unknown) => void;
     onCommit: () => void;
     onCancel: () => void;
 }
@@ -31,7 +31,7 @@ function TextEditor({ value, onValueChange, onCommit, onCancel }: GridEditInputC
 
 // ─── Number ───────────────────────────────────────────────────────────────────
 function NumberEditor({ value, onValueChange, onCommit, onCancel }: GridEditInputCellProps) {
-    const [local, setLocal] = useState(value ?? '');
+    const [local, setLocal] = useState<string | number>(typeof value === 'number' ? value : '');
     const ref = useRef<HTMLInputElement>(null);
     useEffect(() => { ref.current?.focus(); ref.current?.select(); }, []);
 
@@ -94,7 +94,7 @@ function SelectEditor({ value, colDef, onValueChange, onCommit, onCancel }: Grid
         <select
             ref={ref}
             className="ogx__edit-select"
-            value={value ?? ''}
+            value={String(value ?? '')}
             onChange={e => { onValueChange(e.target.value); }}
             onBlur={onCommit}
             onKeyDown={e => {
@@ -113,7 +113,7 @@ function SelectEditor({ value, colDef, onValueChange, onCommit, onCancel }: Grid
 
 // ─── Date ─────────────────────────────────────────────────────────────────────
 function DateEditor({ value, onValueChange, onCommit, onCancel }: GridEditInputCellProps) {
-    const [local, setLocal] = useState(value ?? '');
+    const [local, setLocal] = useState<string>(typeof value === 'string' ? value : String(value ?? ''));
     const ref = useRef<HTMLInputElement>(null);
     useEffect(() => { ref.current?.focus(); }, []);
 

package/lib/components/ColumnVisibilityPanel/ColumnVisibilityPanel.tsx

@@ -10,6 +10,7 @@ export interface ColumnVisibilityPanelProps<R extends GridRowModel = GridRowMode
     onShowAll: () => void;
     onHideAll: () => void;
     onColumnReorder?: (fromField: string, toField: string) => void;
+    onColumnOrderReset?: () => void;
 }
 
 function SearchIcon() {
@@ -43,7 +44,7 @@ function DragHandleIcon() {
 export function ColumnVisibilityPanel<R extends GridRowModel = GridRowModel>(
     props: ColumnVisibilityPanelProps<R>
 ) {
-    const { columns, visibleColumns, onVisibilityChange, onShowAll, onHideAll, onColumnReorder } = props;
+    const { columns, visibleColumns, onVisibilityChange, onShowAll, onHideAll, onColumnReorder, onColumnOrderReset } = props;
     const [searchQuery, setSearchQuery] = useState('');
     const [dragOverField, setDragOverField] = useState<string | null>(null);
     const dragFieldRef = useRef<string | null>(null);
@@ -180,7 +181,7 @@ export function ColumnVisibilityPanel<R extends GridRowModel = GridRowModel>(
                 </label>
                 <button
                     className="ogx-column-visibility-panel__reset-btn"
-                    onClick={onShowAll}
+                    onClick={() => { onShowAll(); onColumnOrderReset?.(); }}
                 >
                     Reset
                 </button>

package/lib/components/DataGrid/DataGrid.regression.test.tsx

@@ -0,0 +1,132 @@
+/**
+ * Regression tests for bugs fixed in the DataGrid render layer.
+ *
+ * Tests cover:
+ *   - getVisibleRows() respects pagination (not returning all rows)
+ *   - Row DOM nodes are not remounted when column widths change
+ *
+ * Not covered here (require a real browser / ResizeObserver):
+ *   - translateY offset — depends on computed cumulativeHeights, which requires
+ *     a real viewport; jsdom reports all dimensions as 0
+ *   - scroll-ref RAF batching — requires scroll events that jsdom fires but
+ *     requestAnimationFrame does not execute by default
+ */
+
+import React from 'react';
+import { describe, it, expect } from 'vitest';
+import { render, act } from '@testing-library/react';
+import { DataGrid } from './DataGrid';
+import { useGridApiRef } from '../../hooks/core/useGridApiRef';
+import type { GridColDef } from '../../types';
+
+const COLS: GridColDef[] = [
+    { field: 'id',   headerName: 'ID',   width: 80 },
+    { field: 'name', headerName: 'Name', width: 150 },
+    { field: 'age',  headerName: 'Age',  width: 100 },
+];
+
+// 10 rows so pagination actually clips the visible set
+const ROWS = Array.from({ length: 10 }, (_, i) => ({
+    id: i + 1,
+    name: `User ${i + 1}`,
+    age: 20 + i,
+}));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Bug: getVisibleRows() was returning sortedUnpinnedRows (all rows) regardless
+// of whether pagination was active. Fixed: now returns paginatedUnpinnedRows
+// when a paginationModel is set.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('getVisibleRows respects pagination', () => {
+    it('returns only the current page rows, not all rows', () => {
+        const assigningRef = React.createRef<import('../../types').GridApi>();
+
+        function GridWithRef() {
+            const ref = useGridApiRef();
+            // expose ref to test scope after render
+            React.useEffect(() => {
+                (assigningRef as React.MutableRefObject<import('../../types').GridApi>).current = ref.current;
+            });
+            return (
+                <DataGrid
+                    rows={ROWS}
+                    columns={COLS}
+                    apiRef={ref}
+                    pagination
+                    paginationModel={{ page: 0, pageSize: 3 }}
+                />
+            );
+        }
+
+        act(() => {
+            render(<GridWithRef />);
+        });
+
+        // pageSize=3, total=10 → page 0 should expose 3 rows, not 10.
+        const visible = assigningRef.current?.getVisibleRows() ?? [];
+        expect(visible.length).toBe(3);
+        expect(visible.map(r => r.id)).toEqual([1, 2, 3]);
+    });
+
+    it('returns all rows when no pagination is provided', () => {
+        const assigningRef = React.createRef<import('../../types').GridApi>();
+
+        function GridNoPagination() {
+            const ref = useGridApiRef();
+            React.useEffect(() => {
+                (assigningRef as React.MutableRefObject<import('../../types').GridApi>).current = ref.current;
+            });
+            return <DataGrid rows={ROWS} columns={COLS} apiRef={ref} />;
+        }
+
+        act(() => {
+            render(<GridNoPagination />);
+        });
+
+        const visible = assigningRef.current?.getVisibleRows() ?? [];
+        // Without pagination the full sorted set is returned.
+        expect(visible.length).toBe(ROWS.length);
+    });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Bug: row keys were `${row.id}-${virtualization.totalWidth}`, so every column
+// resize unmounted and remounted every DOM row node.
+// Fixed: key is now simply `row.id`.
+//
+// Test strategy: capture DOM element identity before and after a column prop
+// change. If the key includes totalWidth the elements will be new nodes; if
+// the key is stable they will be the exact same DOM nodes.
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('row DOM nodes are stable across column width changes', () => {
+    it('does not remount rows when column widths change', () => {
+        const { rerender, container } = render(
+            <DataGrid rows={ROWS.slice(0, 3)} columns={COLS} />
+        );
+
+        // Collect the row cell elements before the update.
+        const cellsBefore = Array.from(
+            container.querySelectorAll('[role="gridcell"]')
+        );
+        expect(cellsBefore.length).toBeGreaterThan(0);
+
+        // Update the Name column width — simulates a resize.
+        const updatedCols: GridColDef[] = COLS.map(c =>
+            c.field === 'name' ? { ...c, width: 250 } : c
+        );
+
+        rerender(<DataGrid rows={ROWS.slice(0, 3)} columns={updatedCols} />);
+
+        const cellsAfter = Array.from(
+            container.querySelectorAll('[role="gridcell"]')
+        );
+
+        // Same number of cells, and critically the same DOM node instances.
+        expect(cellsAfter.length).toBe(cellsBefore.length);
+        cellsBefore.forEach((node, i) => {
+            expect(cellsAfter[i]).toBe(node);
+        });
+    });
+});