@opencorestack/opengridx 0.1.8 → 1.0.0

package/CHANGELOG.md

@@ -5,6 +5,65 @@
 
 ---
 
+## [1.0.0] — July 30, 2026 🚀
+
+First stable public release. All 32 demo pages ship with a live source viewer. npm publish workflow is live.
+
+### Added
+- **npm publish workflow**: GitHub Actions workflow (`.github/workflows/npm-publish.yml`) triggers on any `v*.*.*` tag push — runs lint, build, then `npm publish`. The package is now publicly available as `@opencorestack/opengridx` on the npm registry.
+- **Source viewer on all 32 demos**: Every demo page now uses `DocsLayout` with a collapsible "View Source" tab showing the full component source code. Previously only 7 of 32 demos had this; the remaining 25 have been migrated.
+
+### Changed
+- **Version**: `0.1.x` pre-release series → `1.0.0` stable. The public API (`DataGridProps`, `GridColDef`, `GridApi`, all hooks and types) is now considered stable.
+- **Demo consistency**: All 32 demos share the same `DocsLayout` shell — consistent title, description, live preview, and source viewer. Inline `<h1>` / `<h2>` + `<p>` manual headers removed from every migrated demo.
+
+### Fixed (during migration)
+- `PivotModeDemo` — `apiRef: any`, `fallbackRows: any[]`, `props: any` toolbar → fully typed
+- `InfiniteScrollDemo` — introduced `PersonRow` interface, all `any` in data source and sort params replaced
+- `ServerSideAggregationDemo` — `(a as any)[field]` field access → `keyof Employee` keyed access
+- `AggregationFooter` + `ServerSideAggregationDemo` — `valueFormatter: { value: any }` → `unknown` with narrowing
+- `SlotsDemo` — added `EmployeeRow` interface, `renderCell: (params: any)` × 2 replaced
+- `CRUDTutorial` — `renderCell: (params: any)` → `GridRenderCellParams<User>`
+- `RealEstatePortfolio` — `useState<any>` for pinnedColumns → `useState<GridColumnPinning>`
+- `ExportDemo` — `apiRef: any` → `ReturnType<typeof useGridApiRef>`, `rowsToPrint: any[]` → typed
+- `CustomPagination` — `(props: any)` component signature → explicit typed interface
+- `Editing` — `handleProcessRowUpdate = (newRow: any)` → `MockRow` inferred from data
+
+---
+
+## [0.1.10] — July 30, 2026 🐛🔒
+
+### Fixed
+- **`onRowClick` never fired when `onCellClick` was registered**: `Cell.tsx` was calling `e.stopPropagation()` inside its click handler whenever `onCellClick` was provided. This silently ate the event before it could bubble to the row's `onClick` handler, making `onRowClick` permanently unreachable from cell clicks. Removed the stopPropagation — both callbacks now fire in the natural bubble order (cell first, then row), matching standard data grid behavior.
+- **Column visibility panel list not updating after column reorder**: The toolbar was receiving `effectiveColumns` (the pre-ordering array, in original definition order) instead of `orderedColumns` (the reordered array). After a drag-reorder in the panel, the grid columns reordered correctly but the panel list stayed frozen in definition order. Fixed `toolbarProps.columns` to use `orderedColumns`.
+- **Reset button ignoring column sequence**: The Reset button in the column visibility panel called `onShowAll` only (restoring visibility), leaving any user-reordered sequence in place. Added `onColumnOrderReset` prop threaded from `ColumnVisibilityPanel` → `ColumnsPanelWrapper` → `GridToolbar` → `DataGrid`. DataGrid provides `() => setInternalColumnOrder(columns.map(c => c.field))` to restore original definition order on reset.
+- **`FilterPanelDemo` filter panel inaccessible**: The demo had no `slots={{ toolbar: GridToolbar }}`, so the toolbar never rendered and the filter icon never appeared. Added the toolbar slot and rewrote the demo to use `DocsLayout` (consistent with all other demos).
+- **`EventsDemo` event handlers never fired**: `onRowClick` was broken by the stopPropagation bug above. `onFilterModelChange` and `onColumnOrderChange` were dead — no toolbar existed to trigger them. Fixed by adding `slots={{ toolbar: GridToolbar }}`. Also replaced three `any`-typed handler signatures with `GridSortItem[]`, `GridFilterModel`, and `GridColumnOrderChangeParams`.
+- **`FilterPanel` debounce stale-closure bug**: The 300 ms debounce `useEffect` read `item`, `col.field`, and `currentOperator` directly from closure (stale values after operator or field changes), suppressed with `eslint-disable-next-line`. Replaced with a refs-sync pattern (`useLayoutEffect` writing `itemRef`, `colFieldRef`, `operatorRef` each render) so the effect reads current values without the lint suppression and without stale closures.
+
+### Changed
+- **Type safety — full `any` elimination**: Every `any` across `lib/` replaced with explicit types or `unknown`. Key changes: `GridRowModel` index signature `any → unknown` (with explicit internal row fields added to the type), all cell/value/error params typed as `unknown`, aggregation functions typed as `(values: unknown[]) => unknown`, `GridAggregationResult` typed as `Record<string, unknown>`, slot component types use `Record<string, unknown>`, export utilities narrowed with `instanceof Error` guards.
+- **No more lint suppressions**: Removed all `eslint-disable-next-line react-hooks/exhaustive-deps` comments — every case fixed at the root cause rather than suppressed. Methods include: state refactors (`scrollTick` anti-pattern → `scrollTop`/`scrollLeft` state), ref patterns for stable callbacks, and correct dep arrays.
+- **DataGrid.tsx continued decomposition**: Further hooks and components extracted — `useGridScrollSync` (RAF-batched scroll state), `useGridVirtualization`, `useGridVisibleRows`, `useGridColumns`, `GridAggregationFooter`, `GridEmptyState`, `GridErrorOverlay`, `GridVirtualRows`, `GridPinnedRows`, `GridStandaloneColumnPanel`, `GridListView`. Each module has a single clear responsibility and typed params/return interface.
+
+---
+
+## [0.1.9] — July 29, 2026 🛠️✨
+
+### Added
+- **`GridApi.scrollToIndexes`**: New imperative API method `apiRef.current.scrollToIndexes({ rowIndex?, colIndex? })` scrolls the viewport to bring any row and/or column into view. Column index addresses all data columns (left-pinned + unpinned + right-pinned); pinned columns are always visible so they are silently skipped. Row scrolling accounts for variable-height rows (expanded detail panels, grouped rows).
+- **`useGridKeyboardNavigation` hook**: Extracted ~370 lines of keyboard navigation state and handlers from `DataGrid.tsx` into a standalone `useGridKeyboardNavigation` hook. Fixes a previously dead code path where pressing Enter/Space on a header cell never triggered column sort (the edit handler ran first). The hook is part of the public `lib/` source.
+- **`useLayout` hook**: Extracted all layout-computation logic from `DataGrid.tsx` into a standalone `useLayout` hook, reducing the main component by ~350 lines.
+- **Test suite**: Added Vitest + `@testing-library/react` infrastructure with 65 unit tests covering `filterRows`, `sortRows`, `useAggregation`, and a DataGrid smoke test.
+- **ScrollToIndexes demo**: New `/scroll-to` demo page showcasing the `scrollToIndexes` API with live row/column index controls.
+
+### Fixed
+- **Excel export file format error**: `exportToExcel` generates an HTML-table file with `application/vnd.ms-excel` MIME type (the legacy XLS trick). All demo call-sites were passing explicit `.xlsx` filenames, causing Excel 2007+ to reject the download with "file format or file extension is not valid". Changed all `exportToExcel` usages to `.xls`. `exportToExcelAdvanced` (ExcelJS, real OOXML) is unaffected and correctly keeps `.xlsx`.
+- **Keyboard sort on column headers**: Enter/Space on a focused header cell now correctly triggers sort. Previously the generic Enter-edit handler ran first, making header sort unreachable via keyboard.
+- **ESLint errors**: Resolved all lint errors across the library — hooks called after conditional early returns (`Cell.tsx`, `Row.tsx`), ref mutations in the render phase moved to `useLayoutEffect`, and portal targets reading `ref.current` during render moved to `useState + useLayoutEffect`.
+
+---
+
 ## [0.1.8] — March 18, 2026 🐛✨
 
 ### Fixed

package/dist/index.d.ts

@@ -34,9 +34,9 @@ declare function CellImpl<R extends GridRowModel = GridRowModel>(props: CellProp
 
 declare 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;
@@ -52,7 +52,7 @@ declare 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;
     isHiddenByRowSpan?: boolean;
@@ -75,7 +75,7 @@ export declare interface CsvExportOptions {
     includeHeaders?: boolean;
     delimiter?: string;
     selectedRows?: (string | number)[];
-    aggregationResult?: Record<string, any> | null;
+    aggregationResult?: Record<string, unknown> | null;
     aggregationModel?: GridAggregationModel | null;
 }
 
@@ -218,7 +218,7 @@ export declare interface DataGridProps<R extends GridRowModel = GridRowModel> {
     /** Callback to process an updated row after inline editing. Supports promises and validation. */
     processRowUpdate?: (newRow: R, oldRow: R) => R | Promise<R>;
     /** Callback fired if `processRowUpdate` throws or rejects. */
-    onProcessRowUpdateError?: (error: any) => void;
+    onProcessRowUpdateError?: (error: unknown) => void;
     /** Interface for connecting the grid to an external (server-side) data source. */
     dataSource?: GridDataSource<R>;
     /** Callback fired when scrolling reaches the bottom of the grid viewport. */
@@ -228,23 +228,23 @@ export declare interface DataGridProps<R extends GridRowModel = GridRowModel> {
     /** Custom components to replace internal grid parts. */
     slots?: {
         /** Component rendered as the grid toolbar. */
-        toolbar?: React.ComponentType<any>;
+        toolbar?: React.ComponentType<Record<string, unknown>>;
         /** Component rendered as the pagination control. */
-        pagination?: React.ComponentType<any>;
+        pagination?: React.ComponentType<Record<string, unknown>>;
         /** Component rendered when the grid is empty. */
-        noRowsOverlay?: React.ComponentType<any>;
+        noRowsOverlay?: React.ComponentType<Record<string, unknown>>;
         /** Component rendered during loading states. */
-        loadingOverlay?: React.ComponentType<any>;
+        loadingOverlay?: React.ComponentType<Record<string, unknown>>;
         /** Component rendered at the very bottom of the grid. */
-        footer?: React.ComponentType<any>;
+        footer?: React.ComponentType<Record<string, unknown>>;
     };
     /** Properties passed directly to custom slots. */
     slotProps?: {
-        toolbar?: any;
-        pagination?: any;
-        noRowsOverlay?: any;
-        loadingOverlay?: any;
-        footer?: any;
+        toolbar?: Record<string, unknown>;
+        pagination?: Record<string, unknown>;
+        noRowsOverlay?: Record<string, unknown>;
+        loadingOverlay?: Record<string, unknown>;
+        footer?: Record<string, unknown>;
     };
     /** When true, renders the grid as a single-column list of cards. Perfect for mobile/responsive views. */
     listView?: boolean;
@@ -293,7 +293,7 @@ export declare interface ExcelAdvancedExportOptions {
     /** Body font size (default: 10) */
     bodyFontSize?: number;
     /** Current aggregation result */
-    aggregationResult?: Record<string, any> | null;
+    aggregationResult?: Record<string, unknown> | null;
     /** Current aggregation model */
     aggregationModel?: GridAggregationModel | null;
     /** Currently selected row IDs */
@@ -325,7 +325,7 @@ export declare interface ExcelExportOptions {
     sheetName?: string;
     includeHeaders?: boolean;
     selectedRows?: (string | number)[];
-    aggregationResult?: Record<string, any> | null;
+    aggregationResult?: Record<string, unknown> | null;
     aggregationModel?: GridAggregationModel | null;
 }
 
@@ -373,13 +373,13 @@ declare interface FilterPanelProps {
     onFilterModelChange: (model: GridFilterModel) => void;
 }
 
-export declare function formatAggregationValue(value: any, fnName: string): string;
+export declare function formatAggregationValue(value: unknown, fnName: string): string;
 
 export declare interface GridAggregationModel {
     [field: string]: string;
 }
 
-export declare type GridAggregationResult = Record<string, any>;
+export declare type GridAggregationResult = Record<string, unknown>;
 
 export declare type GridAlignment = 'left' | 'center' | 'right';
 
@@ -398,7 +398,7 @@ export declare interface GridApi {
     /** Returns all rows currently visible after filtering and sorting. */
     getVisibleRows: () => GridRowModel[];
     /** Returns the current aggregation results. */
-    getAggregationResult: () => Record<string, any> | null;
+    getAggregationResult: () => Record<string, unknown> | null;
     /** Returns the active aggregation configuration. */
     getAggregationModel: () => GridAggregationModel | null;
     /** Returns the column definition for the given field. */
@@ -453,7 +453,7 @@ export declare interface GridApi {
 export declare interface GridCellParams<R extends GridRowModel = GridRowModel> {
     row: R;
     field: string;
-    value: any;
+    value: unknown;
     colDef: GridColDef<R>;
     rowIndex: number;
     colIndex: number;
@@ -498,15 +498,17 @@ export declare interface GridColDef<R extends GridRowModel = GridRowModel> {
     hideable?: boolean;
     /** If false, the column cannot be pinned. */
     pinnable?: boolean;
+    /** Internal: marks this column as a virtual spacer used for horizontal virtualization. */
+    isSpacer?: boolean;
     /** Type used to determine default operators and formatting logic. */
     type?: 'string' | 'number' | 'date' | 'boolean' | 'singleSelect' | 'image';
     /** Options used for 'singleSelect' type. */
     valueOptions?: Array<string | number | {
-        value: any;
+        value: unknown;
         label: string;
     }>;
     /** Function to compute a cell value from raw row data. */
-    valueGetter?: (params: GridValueGetterParams<R>) => any;
+    valueGetter?: (params: GridValueGetterParams<R>) => unknown;
     /** Function to format a value into a human-readable string. */
     valueFormatter?: (params: GridValueFormatterParams<R>) => string;
     /** Custom component or element to render in the cell. */
@@ -615,12 +617,12 @@ export declare interface GridDataSource<R extends GridRowModel = GridRowModel> {
     /**
      * Optional: Fetches aggregation results for the entire dataset.
      */
-    getAggregations?: (params: Omit<GridGetRowsParams, 'startRow' | 'endRow'>) => Promise<Record<string, any>>;
+    getAggregations?: (params: Omit<GridGetRowsParams, 'startRow' | 'endRow'>) => Promise<Record<string, unknown>>;
 }
 
 declare interface GridDataSourceState {
     loading: boolean;
-    error?: any;
+    error?: unknown;
 }
 
 export declare interface GridDensityState {
@@ -654,7 +656,7 @@ export declare interface GridFilterItem {
     /** The comparison operator. */
     operator: GridFilterOperator;
     /** The value to compare against. */
-    value?: any;
+    value?: unknown;
 }
 
 /** The overall state of grid filtering. */
@@ -685,7 +687,7 @@ export declare interface GridGetRowsParams {
 export declare interface GridGetRowsResponse<R extends GridRowModel = GridRowModel> {
     rows: R[];
     rowCount?: number;
-    aggregationResults?: Record<string, any>;
+    aggregationResults?: Record<string, unknown>;
 }
 
 export declare type GridInitialState = GridState;
@@ -725,7 +727,7 @@ export declare interface GridPivotValueField {
 /** Parameters passed to the `renderCell` function. */
 export declare interface GridRenderCellParams<R extends GridRowModel = GridRowModel> {
     /** The current cell value. */
-    value: any;
+    value: unknown;
     /** The row object. */
     row: R;
     /** The field name and unique ID. */
@@ -753,8 +755,24 @@ export declare type GridRowId = string | number;
 export declare interface GridRowModel {
     /** Uniquely identifies the row. */
     id: GridRowId;
+    /** Internal: row has child nodes (tree data / row grouping). */
+    _hasChildren?: boolean;
+    /** Internal: row is a skeleton placeholder during infinite-scroll loading. */
+    _isSkeleton?: boolean;
+    /** Internal: depth in the tree or grouping hierarchy. */
+    _treeDepth?: number;
+    /** Internal: whether the group/tree node is currently expanded. */
+    _isExpanded?: boolean;
+    /** Internal: field used for grouping at this level. */
+    _groupingField?: string;
+    /** Internal: grouping field value at this level. */
+    _groupingValue?: unknown;
+    /** Internal: total descendant count for tree/grouping nodes. */
+    _descendantCount?: number;
+    /** Internal: server-reported child count for lazy-loaded tree nodes. */
+    serverChildrenCount?: number;
     /** Any other dynamic row properties. */
-    [key: string]: any;
+    [key: string]: unknown;
 }
 
 export declare interface GridRowOrderChangeParams<R extends GridRowModel = GridRowModel> {
@@ -958,7 +976,7 @@ export declare interface GridThemeTypography {
     fontSizeXl?: string;
 }
 
-export declare function GridToolbar({ columns, baseColumns, aggregationModel, onAggregationModelChange, pivotModel, onPivotModelChange, filterModel, onFilterModelChange, columnVisibilityModel, onColumnVisibilityModelChange, onColumnReorder, forceColumnsOpen, onColumnsPanelClose, children, rightContent, style, }: GridToolbarProps): JSX.Element;
+export declare function GridToolbar({ columns, baseColumns, aggregationModel, onAggregationModelChange, pivotModel, onPivotModelChange, filterModel, onFilterModelChange, columnVisibilityModel, onColumnVisibilityModelChange, onColumnReorder, onColumnOrderReset, forceColumnsOpen, onColumnsPanelClose, children, rightContent, style, }: GridToolbarProps): JSX.Element;
 
 export declare interface GridToolbarProps {
     columns?: GridColDef[];
@@ -976,6 +994,7 @@ export declare interface GridToolbarProps {
     columnVisibilityModel?: Record<string, boolean>;
     onColumnVisibilityModelChange?: (model: Record<string, boolean>) => void;
     onColumnReorder?: (fromField: string, toField: string) => void;
+    onColumnOrderReset?: () => void;
     forceColumnsOpen?: boolean;
     onColumnsPanelClose?: () => void;
     children?: default_2.ReactNode;
@@ -1006,9 +1025,9 @@ export declare interface GridTreeNode {
     /** The field this node is grouping by. */
     groupingField?: string;
     /** The actual value being grouped. */
-    groupingValue?: any;
+    groupingValue?: unknown;
     /** Computed aggregation results for this group. */
-    aggregatedValues?: Record<string, any>;
+    aggregatedValues?: Record<string, unknown>;
     /** Position of the aggregation row relative to the group. */
     aggregationPosition?: 'inline' | 'footer' | null;
     /** Current expansion state. */
@@ -1026,7 +1045,7 @@ export declare interface GridTreeNode {
 /** Parameters passed to the `valueFormatter` function. */
 export declare interface GridValueFormatterParams<R extends GridRowModel = GridRowModel> {
     /** The raw value to format. */
-    value: any;
+    value: unknown;
     /** The row object. */
     row: R;
     /** The field name. */
@@ -1040,7 +1059,7 @@ export declare interface GridValueGetterParams<R extends GridRowModel = GridRowM
     /** The field name. */
     field: string;
     /** The raw value from the row object. */
-    value: any;
+    value: unknown;
 }
 
 export declare function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps<R>): JSX.Element;
@@ -1095,7 +1114,7 @@ export declare interface JsonExportOptions {
     fileName?: string;
     pretty?: boolean;
     selectedRows?: (string | number)[];
-    aggregationResult?: Record<string, any> | null;
+    aggregationResult?: Record<string, unknown> | null;
     aggregationModel?: GridAggregationModel | null;
 }
 
@@ -1107,7 +1126,7 @@ export declare function printGrid<R extends GridRowModel>(rows: R[], columns: Gr
 export declare interface PrintOptions {
     title?: string;
     selectedRows?: (string | number)[];
-    aggregationResult?: Record<string, any> | null;
+    aggregationResult?: Record<string, unknown> | null;
     aggregationModel?: GridAggregationModel | null;
 }
 
@@ -1144,12 +1163,12 @@ declare interface RowProps<R extends GridRowModel = GridRowModel> {
     editingCell?: {
         id: GridRowId;
         field: string;
-        value: any;
+        value: unknown;
     } | null;
     onEditStart?: (params: {
         id: GridRowId;
         field: string;
-        value: any;
+        value: unknown;
     }) => void;
     onEditStop?: (params?: {
         cancel?: boolean;
@@ -1157,7 +1176,7 @@ declare interface RowProps<R extends GridRowModel = GridRowModel> {
     onEditCellValueChange?: (params: {
         id: GridRowId;
         field: string;
-        value: any;
+        value: unknown;
     }) => void;
     focusedCellField?: string | null;
     isFocusVisible?: boolean;
@@ -1194,7 +1213,7 @@ export declare interface UseAggregationParams<R extends GridRowModel> {
 export declare interface UseAggregationReturn {
     aggregationResult: GridAggregationResult;
     isLoading: boolean;
-    error: any;
+    error: unknown;
 }
 
 /**