@opencorestack/opengridx 2.0.4 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencorestack/opengridx",
-  "version": "2.0.4",
+  "version": "3.0.0",
   "description": "OpenGridX: High-performance React data infrastructure. Unlock advanced Row Grouping, Excel Export, and Column Pinning without the usual \"Pro\" gatekeeping. Built for speed, scale, and complete architectural freedom. Fully open, virtualization-ready, and feature-complete.",
   "type": "module",
   "main": "./dist/opengridx.umd.js",
@@ -20,11 +20,18 @@
   "files": [
     "dist",
     "lib",
+    "!lib/**/*.test.ts",
+    "!lib/**/*.test.tsx",
+    "!lib/**/__screenshots__",
+    "docs/architecture",
+    "docs/assets",
     "docs/components",
     "docs/customization",
     "docs/features",
+    "docs/migration",
     "docs/API_REFERENCE.md",
     "docs/README.md",
+    "docs/performance.md",
     "docs/roadmap.md",
     "README.md",
     "LICENSE",
@@ -38,11 +45,14 @@
   "scripts": {
     "dev": "vite",
     "build": "tsc --project tsconfig.build.json && vite build",
-    "build:lib": "tsc --project tsconfig.build.json && vite build --config vite.config.lib.js && cp lib/styles/opengridx.css.d.ts dist/opengridx.css.d.ts",
+    "build:lib": "tsc --project tsconfig.build.json && vite build --config vite.config.lib.js && cp lib/styles/opengridx.css.d.ts dist/opengridx.css.d.ts && node scripts/check-bundle.mjs",
     "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
     "preview": "vite preview",
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "vitest run --project unit",
+    "test:browser": "vitest run --project browser",
+    "test:all": "vitest run",
+    "test:watch": "vitest --project unit",
     "coverage": "vitest run --coverage",
     "prepublishOnly": "npm run build:lib"
   },
@@ -103,7 +113,8 @@
     "@types/react": "^19.2.5",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^5.1.1",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/browser-playwright": "^4.1.11",
+    "@vitest/coverage-v8": "^4.1.11",
     "eslint": "^9.39.1",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.4.24",
@@ -111,6 +122,7 @@
     "jsdom": "^29.1.1",
     "jspdf": "^4.2.1",
     "jspdf-autotable": "^5.0.8",
+    "playwright": "^1.58.2",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-router-dom": "^7.13.1",
@@ -118,6 +130,6 @@
     "typescript-eslint": "^8.65.0",
     "vite": "^7.2.4",
     "vite-plugin-dts": "^4.5.4",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.11"
   }
 }

package/lib/components/ColumnGroupHeader/ColumnGroupHeader.tsx

@@ -1,220 +0,0 @@
-import type { GridColumnGroup, GridColumnGroupingModel, GridColDef, GridRowModel } from '../../types';
-import './ColumnGroupHeader.css';
-
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-
-/** All leaf field names reachable from a group node (recursive). */
-function collectFields(group: GridColumnGroup): string[] {
-    const fields: string[] = [];
-    for (const child of group.children) {
-        if (typeof child === 'string') {
-            fields.push(child);
-        } else {
-            fields.push(...collectFields(child));
-        }
-    }
-    return fields;
-}
-
-/** Maximum nesting depth of any group tree. */
-function maxDepth(groups: GridColumnGroupingModel): number {
-    let d = 0;
-    function walk(g: GridColumnGroup, depth: number) {
-        d = Math.max(d, depth);
-        for (const child of g.children) {
-            if (typeof child !== 'string') walk(child, depth + 1);
-        }
-    }
-    groups.forEach(g => walk(g, 1));
-    return d;
-}
-
-/**
- * Flattened cell descriptor for one row of group headers.
- * `span` is the pixel width, `level` is 0-indexed depth.
- */
-interface GroupCell {
-    key: string;
-    label: string;
-    width: number;          // total pixel width spanned
-    isGroup: boolean;       // false → empty "filler" cell for ungrouped columns
-    groupId?: string;
-    headerClassName?: string;
-}
-
-/** Build one row of GroupCell descriptors for a given depth level. */
-function buildRow(
-    groups: GridColumnGroupingModel,
-    leafColumns: string[],
-    columnWidths: Record<string, number>,
-    level: number,
-): GroupCell[] {
-    const cells: GroupCell[] = [];
-
-    // Assign each leaf column to the group (at `level`) that contains it, if any.
-    // Consecutive columns in the same group merge into one cell.
-
-    // Build a map: field → group-at-this-level
-    const fieldToGroup = new Map<string, GridColumnGroup | null>();
-
-    function findGroupAtLevel(
-        groups: GridColumnGroupingModel,
-        field: string,
-        currentLevel: number,
-    ): GridColumnGroup | null {
-        for (const g of groups) {
-            const leafFields = collectFields(g);
-            if (!leafFields.includes(field)) continue;
-            if (currentLevel === level) return g;
-            // Go deeper
-            for (const child of g.children) {
-                if (typeof child !== 'string') {
-                    const found = findGroupAtLevel([child], field, currentLevel + 1);
-                    if (found) return found;
-                }
-            }
-            return null;
-        }
-        return null;
-    }
-
-    for (const f of leafColumns) {
-        fieldToGroup.set(f, findGroupAtLevel(groups, f, 0));
-    }
-
-    // Merge consecutive columns belonging to the same group
-    let i = 0;
-    while (i < leafColumns.length) {
-        const field = leafColumns[i];
-        const group = fieldToGroup.get(field) ?? null;
-
-        if (!group) {
-            // Ungrouped column — filler cell spanning just this column
-            cells.push({
-                key: `filler-${field}-${level}`,
-                label: '',
-                width: columnWidths[field] ?? 100,
-                isGroup: false,
-            });
-            i++;
-        } else {
-            // Collect all consecutive columns that belong to the same group instance
-            let totalWidth = 0;
-            let j = i;
-            while (j < leafColumns.length && fieldToGroup.get(leafColumns[j]) === group) {
-                totalWidth += columnWidths[leafColumns[j]] ?? 100;
-                j++;
-            }
-            cells.push({
-                key: `${group.groupId}-${level}`,
-                label: group.headerName,
-                width: totalWidth,
-                isGroup: true,
-                groupId: group.groupId,
-                headerClassName: group.headerClassName,
-            });
-            i = j;
-        }
-    }
-
-    return cells;
-}
-
-// ─── Component ────────────────────────────────────────────────────────────────
-
-export interface ColumnGroupHeaderProps<R extends GridRowModel = GridRowModel> {
-    columnGroupingModel: GridColumnGroupingModel;
-    /** The ordered, effective columns (already filtered for visibility). */
-    columns: GridColDef<R>[];
-    /** Resolved pixel widths for every column. */
-    columnWidths: Record<string, number>;
-    /** Whether a checkbox column is prepended. */
-    checkboxSelection?: boolean;
-    /** Whether a row-reorder handle column is prepended. */
-    rowReordering?: boolean;
-    /** Whether a detail-panel expand column is prepended. */
-    hasDetailPanel?: boolean;
-    /** height (px) of each group header row */
-    groupHeaderHeight?: number;
-}
-
-export function ColumnGroupHeader<R extends GridRowModel = GridRowModel>({
-    columnGroupingModel,
-    columns,
-    columnWidths,
-    checkboxSelection = false,
-    rowReordering = false,
-    hasDetailPanel = false,
-    groupHeaderHeight = 36,
-}: ColumnGroupHeaderProps<R>) {
-
-    const levels = maxDepth(columnGroupingModel);
-    if (levels === 0 || columns.length === 0) return null;
-
-    // Ordered leaf fields (visible columns only)
-    const leafFields = columns.map(c => c.field);
-
-    // Width of any prepended utility columns
-    const CHECKBOX_W = 52;
-    const REORDER_W = 40;
-    const EXPAND_W = 52;
-    const prefixWidth =
-        (checkboxSelection ? CHECKBOX_W : 0) +
-        (rowReordering ? REORDER_W : 0) +
-        (hasDetailPanel ? EXPAND_W : 0);
-
-    return (
-        <>
-            {Array.from({ length: levels }, (_, level) => {
-                const row = buildRow(
-                    columnGroupingModel,
-                    leafFields,
-                    columnWidths,
-                    level,
-                );
-
-                return (
-                    <div
-                        key={`group-row-${level}`}
-                        className="ogx-col-group-row"
-                        style={{ height: groupHeaderHeight }}
-                        role="row"
-                        aria-rowindex={level + 1}
-                    >
-                        {/* Spacer for checkbox / reorder / expand columns */}
-                        {prefixWidth > 0 && (
-                            <div
-                                className="ogx-col-group-cell ogx-col-group-cell--filler"
-                                style={{ width: prefixWidth, minWidth: prefixWidth }}
-                                role="columnheader"
-                            />
-                        )}
-
-                        {row.map((cell) => (
-                            <div
-                                key={cell.key}
-                                role="columnheader"
-                                aria-colspan={undefined /* pixel-based layout */}
-                                className={[
-                                    'ogx-col-group-cell',
-                                    cell.isGroup
-                                        ? 'ogx-col-group-cell--group'
-                                        : 'ogx-col-group-cell--filler',
-                                    cell.headerClassName ?? '',
-                                ].join(' ').trim()}
-                                style={{ width: cell.width, minWidth: cell.width }}
-                                title={cell.isGroup ? cell.label : undefined}
-                            >
-                                {cell.isGroup && (
-                                    <span className="ogx-col-group-cell__label">
-                                        {cell.label}
-                                    </span>
-                                )}
-                            </div>
-                        ))}
-                    </div>
-                );
-            })}
-        </>
-    );
-}

package/lib/components/ColumnVisibilityPanel/ColumnVisibilityPanel.test.tsx

@@ -1,85 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { render, screen } from '@testing-library/react';
-import { ColumnVisibilityPanel } from './ColumnVisibilityPanel';
-import type { GridColDef } from '../../types';
-
-const columns: GridColDef[] = [
-    { field: 'name', headerName: 'Name' },
-    { field: 'department', headerName: 'Department' },
-    { field: 'groupKey', headerName: 'Group Key', hideable: false },
-];
-
-const visibleColumns = new Set(['name', 'department', 'groupKey']);
-
-const noop = () => {};
-
-describe('ColumnVisibilityPanel', () => {
-    it('excludes hideable:false columns from the list by default', () => {
-        render(
-            <ColumnVisibilityPanel
-                columns={columns}
-                visibleColumns={visibleColumns}
-                onVisibilityChange={noop}
-                onShowAll={noop}
-                onHideAll={noop}
-            />
-        );
-        expect(screen.getByText('Name')).toBeInTheDocument();
-        expect(screen.getByText('Department')).toBeInTheDocument();
-        expect(screen.queryByText('Group Key')).not.toBeInTheDocument();
-    });
-
-    it('shows hideable:false columns as disabled when showNonHideableColumns is true', () => {
-        render(
-            <ColumnVisibilityPanel
-                columns={columns}
-                visibleColumns={visibleColumns}
-                onVisibilityChange={noop}
-                onShowAll={noop}
-                onHideAll={noop}
-                showNonHideableColumns
-            />
-        );
-        expect(screen.getByText('Name')).toBeInTheDocument();
-        expect(screen.getByText('Department')).toBeInTheDocument();
-        expect(screen.getByText('Group Key')).toBeInTheDocument();
-
-        // 3 columns shown + 1 "Show/Hide All" checkbox in footer = 4 checkboxes
-        // The 3rd column (Group Key, hideable:false) must be the disabled one
-        const checkboxes = screen.getAllByRole('checkbox');
-        const disabledCheckboxes = checkboxes.filter(cb => (cb as HTMLInputElement).disabled);
-        expect(disabledCheckboxes).toHaveLength(1);
-    });
-
-    it('does not render a disabled checkbox for hideable:false columns by default', () => {
-        render(
-            <ColumnVisibilityPanel
-                columns={columns}
-                visibleColumns={visibleColumns}
-                onVisibilityChange={noop}
-                onShowAll={noop}
-                onHideAll={noop}
-            />
-        );
-        const checkboxes = screen.getAllByRole('checkbox');
-        const disabledCheckboxes = checkboxes.filter(cb => (cb as HTMLInputElement).disabled);
-        expect(disabledCheckboxes).toHaveLength(0);
-    });
-
-    it('never shows hideable:false columns even when search would match them', () => {
-        // Without showNonHideableColumns, hideable:false columns are not in the base list
-        // so they cannot appear regardless of search. This test verifies the base list,
-        // not a dynamic search interaction.
-        render(
-            <ColumnVisibilityPanel
-                columns={columns}
-                visibleColumns={visibleColumns}
-                onVisibilityChange={noop}
-                onShowAll={noop}
-                onHideAll={noop}
-            />
-        );
-        // "Group Key" is hideable:false — must not appear in the default panel
-        expect(screen.queryByText('Group Key')).not.toBeInTheDocument();
-    });
-});

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

@@ -1,132 +0,0 @@
-/**
- * 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);
-        });
-    });
-});

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

@@ -1,58 +0,0 @@
-import React from 'react';
-import { describe, it, expect } from 'vitest';
-import { render, screen } from '@testing-library/react';
-import { DataGrid } from './DataGrid';
-import type { GridColDef } from '../../types';
-
-const COLUMNS: GridColDef[] = [
-    { field: 'id', headerName: 'ID', width: 80 },
-    { field: 'name', headerName: 'Name', width: 150 },
-    { field: 'age', headerName: 'Age', width: 100, type: 'number' },
-];
-
-const ROWS = [
-    { id: 1, name: 'Alice', age: 30 },
-    { id: 2, name: 'Bob', age: 25 },
-    { id: 3, name: 'Charlie', age: 35 },
-];
-
-describe('DataGrid — smoke tests', () => {
-    it('renders without throwing', () => {
-        expect(() =>
-            render(<DataGrid rows={ROWS} columns={COLUMNS} />)
-        ).not.toThrow();
-    });
-
-    it('renders column headers', () => {
-        render(<DataGrid rows={ROWS} columns={COLUMNS} />);
-        expect(screen.getByText('Name')).toBeInTheDocument();
-        expect(screen.getByText('Age')).toBeInTheDocument();
-    });
-
-    it('renders row data', () => {
-        render(<DataGrid rows={ROWS} columns={COLUMNS} />);
-        expect(screen.getByText('Alice')).toBeInTheDocument();
-        expect(screen.getByText('Bob')).toBeInTheDocument();
-        expect(screen.getByText('Charlie')).toBeInTheDocument();
-    });
-
-    it('renders with empty rows without throwing', () => {
-        expect(() =>
-            render(<DataGrid rows={[]} columns={COLUMNS} />)
-        ).not.toThrow();
-    });
-
-    it('renders with empty columns without throwing', () => {
-        expect(() =>
-            render(<DataGrid rows={ROWS} columns={[]} />)
-        ).not.toThrow();
-    });
-
-    it('renders with checkboxSelection enabled', () => {
-        const { container } = render(
-            <DataGrid rows={ROWS} columns={COLUMNS} checkboxSelection />
-        );
-        const checkboxes = container.querySelectorAll('input[type="checkbox"]');
-        expect(checkboxes.length).toBeGreaterThan(0);
-    });
-});