@ornery/ui-grid-react 0.1.4 → 0.1.6

package/src/UiGrid.tsx

@@ -19,7 +19,13 @@ export interface UiGridProps {
   className?: string;
 }
 
-export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRenderer, className }: UiGridProps) {
+export function UiGrid({
+  options,
+  onRegisterApi,
+  cellRenderer,
+  expandableRenderer,
+  className,
+}: UiGridProps) {
   const state = useGridState(options, onRegisterApi);
 
   const {
@@ -57,13 +63,103 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
     overscan: 3,
   });
 
+  const headerGridRef = React.useRef<HTMLDivElement | null>(null);
+  const filterGridRef = React.useRef<HTMLDivElement | null>(null);
+  const [openPinMenuColumn, setOpenPinMenuColumn] = React.useState<string | null>(null);
+  const [headerStickyHeight, setHeaderStickyHeight] = React.useState(0);
+  const [filterStickyHeight, setFilterStickyHeight] = React.useState(0);
+  const stickyChromeHeight = headerStickyHeight + filterStickyHeight;
+  const scrollContainerHeight = `${(options.viewportHeight ?? 560) + stickyChromeHeight}px`;
+
+  const eventPathIncludesClass = React.useCallback((event: Event, className: string): boolean => {
+    const eventPath = typeof event.composedPath === 'function'
+      ? event.composedPath()
+      : (event.target ? [event.target] : []);
+
+    return eventPath.some((target) => {
+      if (!target || typeof target !== 'object' || !('classList' in target)) {
+        return false;
+      }
+
+      const classList = (target as { classList?: DOMTokenList }).classList;
+      return classList?.contains(className) ?? false;
+    });
+  }, []);
+
+  const isPinMenuOpen = React.useCallback(
+    (column: GridColumnDef) => openPinMenuColumn === column.name,
+    [openPinMenuColumn],
+  );
+
+  const pinButtonLabel = React.useCallback(
+    (column: GridColumnDef) => (state.isPinned(column) ? labels.unpin : labels.pinColumn),
+    [labels, state],
+  );
+
+  const onPinTrigger = React.useCallback(
+    (column: GridColumnDef, event?: React.MouseEvent) => {
+      event?.stopPropagation();
+      if (state.isPinned(column)) {
+        setOpenPinMenuColumn(null);
+        state.gridApi.pinning.pinColumn(column.name, 'none');
+        return;
+      }
+
+      setOpenPinMenuColumn((current) => (current === column.name ? null : column.name));
+    },
+    [state],
+  );
+
+  const choosePinDirection = React.useCallback(
+    (column: GridColumnDef, direction: 'left' | 'right', event?: React.MouseEvent) => {
+      event?.stopPropagation();
+      setOpenPinMenuColumn(null);
+      state.gridApi.pinning.pinColumn(column.name, direction);
+    },
+    [state],
+  );
+
+  React.useLayoutEffect(() => {
+    setHeaderStickyHeight(headerGridRef.current?.offsetHeight ?? 0);
+    setFilterStickyHeight(filterGridRef.current?.offsetHeight ?? 0);
+  }, [visibleColumns, filteringFeature, options.enableFiltering]);
+
+  React.useEffect(() => {
+    if (!openPinMenuColumn) {
+      return;
+    }
+
+    const handleDocumentClick = (event: MouseEvent) => {
+      if (eventPathIncludesClass(event, 'pin-control')) {
+        return;
+      }
+
+      setOpenPinMenuColumn(null);
+    };
+
+    const handleDocumentEscape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        setOpenPinMenuColumn(null);
+      }
+    };
+
+    document.addEventListener('click', handleDocumentClick);
+    document.addEventListener('keydown', handleDocumentEscape);
+
+    return () => {
+      document.removeEventListener('click', handleDocumentClick);
+      document.removeEventListener('keydown', handleDocumentEscape);
+    };
+  }, [eventPathIncludesClass, openPinMenuColumn]);
+
   const itemsToRender = virtualizationEnabled
     ? displayItems.slice(virtualScroll.visibleRange.start, virtualScroll.visibleRange.end)
     : displayItems;
 
-  const onViewportScroll = (event: React.UIEvent<HTMLDivElement>) => {
-    virtualScroll.onScroll(event);
-    const startIndex = Math.floor(event.currentTarget.scrollTop / rowSize);
+  const onGridTableScroll = (event: React.UIEvent<HTMLDivElement>) => {
+    const bodyScrollTop = Math.max(0, event.currentTarget.scrollTop - stickyChromeHeight);
+    virtualScroll.setScrollTop(bodyScrollTop);
+    const startIndex = Math.floor(bodyScrollTop / rowSize);
     state.onViewportScroll(startIndex);
   };
 
@@ -80,9 +176,18 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
           style={{ gridColumn: '1 / -1', paddingInlineStart: `${item.depth * 1.25 + 1}rem` }}
           onClick={() => state.toggleGroup(item)}
         >
-          <strong>{item.field}: {item.label}</strong>
-          <span>{item.count} {labels.groupRowsSuffix}</span>
-          <svg className="toggle-icon group-disclosure-icon" viewBox="0 0 24 24" aria-hidden="true" focusable={false}>
+          <strong>
+            {item.field}: {item.label}
+          </strong>
+          <span>
+            {item.count} {labels.groupRowsSuffix}
+          </span>
+          <svg
+            className="toggle-icon group-disclosure-icon"
+            viewBox="0 0 24 24"
+            aria-hidden="true"
+            focusable={false}
+          >
             <path d={item.collapsed ? 'M10 7l5 5-5 5z' : 'M7 10l5 5 5-5z'} />
           </svg>
           <span className="sr-only ui-grid-sr-only">{state.groupDisclosureLabel(item)}</span>
@@ -107,10 +212,13 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
     if (item.kind !== 'row') return null;
     const rowItem = item as RowItem;
 
-    return visibleColumns.map((column) => (
+    return visibleColumns.map((column) => {
+      const pinned = state.isPinned(column);
+      const pinOffset = pinned ? state.pinnedOffset(column) : null;
+      return (
       <div
         key={`${rowItem.row.id}-${column.name}`}
-        className={cellClassName(rowItem, column)}
+        className={`${cellClassName(rowItem, column)}${pinned ? ' is-pinned' : ''}`}
         data-part="body-cell"
         role="gridcell"
         tabIndex={0}
@@ -120,8 +228,17 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
         onClick={() => state.focusCell(rowItem.row, column)}
         onDoubleClick={(e) => state.handleCellDoubleClick(rowItem.row, column, e)}
         onKeyDown={(e) => state.handleCellKeyDown(rowItem.row, column, e)}
+        style={{
+          position: pinned ? 'sticky' : undefined,
+          left: pinOffset?.side === 'left' ? pinOffset.offset : undefined,
+          right: pinOffset?.side === 'right' ? pinOffset.offset : undefined,
+          zIndex: pinned ? 2 : undefined,
+        }}
       >
-        <div className="cell-shell" style={{ paddingInlineStart: state.cellIndent(rowItem.row, column) }}>
+        <div
+          className="cell-shell"
+          style={{ paddingInlineStart: state.cellIndent(rowItem.row, column) }}
+        >
           {treeViewFeature && state.showTreeToggle(rowItem.row, column) && (
             <button
               type="button"
@@ -132,7 +249,9 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
               onClick={(e) => state.toggleTreeRow(rowItem.row, e)}
             >
               <svg className="toggle-icon" viewBox="0 0 24 24" aria-hidden="true" focusable={false}>
-                <path d={state.isTreeRowExpanded(rowItem.row) ? 'M7 10l5 5 5-5z' : 'M10 7l5 5-5 5z'} />
+                <path
+                  d={state.isTreeRowExpanded(rowItem.row) ? 'M7 10l5 5 5-5z' : 'M10 7l5 5-5 5z'}
+                />
               </svg>
             </button>
           )}
@@ -164,14 +283,16 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
                 onBlur={(e) => state.handleEditorBlur(e)}
               />
             ) : cellRenderer ? (
-              cellRenderer(state.cellContext(rowItem.row, column)) ?? state.displayValue(rowItem.row, column)
+              (cellRenderer(state.cellContext(rowItem.row, column)) ??
+              state.displayValue(rowItem.row, column))
             ) : (
               state.displayValue(rowItem.row, column)
             )}
           </span>
         </div>
       </div>
-    ));
+      );
+    });
   }
 
   function cellClassName(item: RowItem, column: GridColumnDef): string {
@@ -222,11 +343,21 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
           </div>
 
           <div className="hero-actions">
-            <button type="button" className="action action-secondary" data-part="action benchmark-action" onClick={() => state.runBenchmark()}>
+            <button
+              type="button"
+              className="action action-secondary"
+              data-part="action benchmark-action"
+              onClick={() => state.runBenchmark()}
+            >
               Benchmark
             </button>
             {csvExportFeature && (
-              <button type="button" className="action action-secondary" data-part="action export-action" onClick={() => state.exportCsv()}>
+              <button
+                type="button"
+                className="action action-secondary"
+                data-part="action export-action"
+                onClick={() => state.exportCsv()}
+              >
                 Export CSV
               </button>
             )}
@@ -237,7 +368,11 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
           </div>
         </header>
 
-        <section className="metrics-strip" data-part="metrics" aria-label="Grid performance metrics">
+        <section
+          className="metrics-strip"
+          data-part="metrics"
+          aria-label="Grid performance metrics"
+        >
           <article data-part="metric-card">
             <strong>{pipelineMs.toFixed(2)} ms</strong>
             <span>pipeline</span>
@@ -256,33 +391,56 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
           </article>
         </section>
 
-        <section className="grid-frame ui-grid" data-part="grid-frame" role="grid" aria-label={options.title ?? 'Data grid'}>
+        <section
+          className="grid-frame ui-grid"
+          data-part="grid-frame"
+          role="grid"
+          aria-label={options.title ?? 'Data grid'}
+        >
           <div className="grid-toolbar" data-part="grid-toolbar">
             <div>
               <strong>{visibleRowCount}</strong>
-              <span>{labels.toolbarOf} {totalRows} {labels.toolbarRows}</span>
+              <span>
+                {labels.toolbarOf} {totalRows} {labels.toolbarRows}
+              </span>
             </div>
             <p>
-              `gridOptions` compatibility layer: sorting, filtering, grouping, column moving, templating,
-              and virtualized rendering.
+              `gridOptions` compatibility layer: sorting, filtering, grouping, column moving,
+              templating, and virtualized rendering.
             </p>
           </div>
 
-          <div className="grid-table ui-grid-contents-wrapper" data-part="grid-table">
+          <div
+            className="grid-table ui-grid-contents-wrapper"
+            data-part="grid-table"
+            style={virtualizationEnabled ? { height: scrollContainerHeight, overflowY: 'auto' } : undefined}
+            onScroll={virtualizationEnabled ? onGridTableScroll : undefined}
+          >
             {/* Header row */}
             <div
               className="header-grid ui-grid-header ui-grid-header-canvas"
               data-part="header"
               role="row"
+              ref={headerGridRef}
               style={{ gridTemplateColumns }}
             >
-              {visibleColumns.map((column) => (
+              {visibleColumns.map((column) => {
+                const pinned = state.isPinned(column);
+                const pinOffset = pinned ? state.pinnedOffset(column) : null;
+                const pinMenuOpen = isPinMenuOpen(column);
+                return (
                 <div
                   key={column.name}
-                  className={`header-cell ui-grid-header-cell${sortingFeature && state.sortDirection(column) !== 'none' ? ' is-active' : ''}`}
+                  className={`header-cell ui-grid-header-cell${sortingFeature && state.sortDirection(column) !== 'none' ? ' is-active' : ''}${pinned ? ' is-pinned' : ''}${pinMenuOpen ? ' is-pin-menu-open' : ''}`}
                   data-part="header-cell"
                   role="columnheader"
-                  aria-sort={sortingFeature ? state.sortAriaSort(column) as any : undefined}
+                  aria-sort={sortingFeature ? (state.sortAriaSort(column) as any) : undefined}
+                  style={{
+                    position: pinned ? 'sticky' : undefined,
+                    left: pinOffset?.side === 'left' ? pinOffset.offset : undefined,
+                    right: pinOffset?.side === 'right' ? pinOffset.offset : undefined,
+                    zIndex: pinMenuOpen ? 8 : pinned ? 2 : undefined,
+                  }}
                 >
                   <span className="header-label">{state.headerLabel(column)}</span>
 
@@ -297,36 +455,123 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
                         onClick={() => state.toggleSort(column)}
                       >
                         {renderSortIcon(column)}
-                        <span className="sr-only ui-grid-sr-only">{state.sortButtonLabel(column)}</span>
+                        <span className="sr-only ui-grid-sr-only">
+                          {state.sortButtonLabel(column)}
+                        </span>
                       </button>
                     )}
 
-                    {groupingFeature && state.isGroupingEnabled() && column.enableGrouping !== false && (
-                      <button
-                        type="button"
-                        className={`chip-action${state.isGrouped(column) ? ' chip-action-active' : ''}`}
-                        data-part="group-toggle"
-                        aria-label={state.groupingButtonLabel(column)}
-                        title={state.groupingButtonLabel(column)}
-                        onClick={(e) => state.toggleGrouping(column, e)}
-                      >
-                        <svg viewBox="0 0 24 24" aria-hidden="true" focusable={false}>
-                          <path d="M4 6h8v4H4V6Zm0 8h8v4H4v-4Zm10-8h6v4h-6V6Zm0 8h6v4h-6v-4Z" />
-                        </svg>
-                        <span className="sr-only ui-grid-sr-only">{state.groupingButtonLabel(column)}</span>
-                      </button>
-                    )}
+                    {groupingFeature &&
+                      state.isGroupingEnabled() &&
+                      column.enableGrouping !== false && (
+                        <button
+                          type="button"
+                          className={`chip-action${state.isGrouped(column) ? ' chip-action-active' : ''}`}
+                          data-part="group-toggle"
+                          aria-label={state.groupingButtonLabel(column)}
+                          title={state.groupingButtonLabel(column)}
+                          onClick={(e) => state.toggleGrouping(column, e)}
+                        >
+                          <svg viewBox="0 0 24 24" aria-hidden="true" focusable={false}>
+                            <path d="M4 6h8v4H4V6Zm0 8h8v4H4v-4Zm10-8h6v4h-6V6Zm0 8h6v4h-6v-4Z" />
+                          </svg>
+                          <span className="sr-only ui-grid-sr-only">
+                            {state.groupingButtonLabel(column)}
+                          </span>
+                        </button>
+                      )}
+                    {state.pinningFeature &&
+                      state.isPinningEnabled() &&
+                      state.isColumnPinnable(column) && (
+                        <div className={`pin-control${pinMenuOpen ? ' pin-control-open' : ''}`} onClick={(event) => event.stopPropagation()}>
+                          <button
+                            type="button"
+                            className={`chip-action pin-trigger${pinned || pinMenuOpen ? ' chip-action-active' : ''}`}
+                            data-part="pin-toggle"
+                            aria-label={pinButtonLabel(column)}
+                            title={pinButtonLabel(column)}
+                            aria-haspopup={pinned ? undefined : 'menu'}
+                            aria-expanded={pinned ? undefined : pinMenuOpen}
+                            onClick={(event) => onPinTrigger(column, event)}
+                          >
+                            <svg viewBox="0 0 24 24" aria-hidden="true" focusable={false}>
+                              <path d="M16 12V4h1V2H7v2h1v8l-2 2v2h5v6l1 1 1-1v-6h5v-2l-2-2z" />
+                            </svg>
+                            <span className="sr-only ui-grid-sr-only">{pinButtonLabel(column)}</span>
+                          </button>
+
+                          <div
+                            className="pin-menu"
+                            data-part="pin-menu"
+                            role="menu"
+                            aria-label="Pin options"
+                            aria-hidden={!pinMenuOpen}
+                          >
+                            <button
+                              type="button"
+                              className="pin-menu-action"
+                              data-part="pin-left-action"
+                              role="menuitem"
+                              aria-label={labels.pinLeft}
+                              title={labels.pinLeft}
+                              tabIndex={pinMenuOpen ? 0 : -1}
+                              onClick={(event) => choosePinDirection(column, 'left', event)}
+                            >
+                              <svg viewBox="0 0 24 24" aria-hidden="true" focusable={false}>
+                                <path d="M10 6 4 12l6 6v-4h10v-4H10V6z" />
+                              </svg>
+                              <span className="sr-only ui-grid-sr-only">{labels.pinLeft}</span>
+                            </button>
+                            <button
+                              type="button"
+                              className="pin-menu-action"
+                              data-part="pin-right-action"
+                              role="menuitem"
+                              aria-label={labels.pinRight}
+                              title={labels.pinRight}
+                              tabIndex={pinMenuOpen ? 0 : -1}
+                              onClick={(event) => choosePinDirection(column, 'right', event)}
+                            >
+                              <svg viewBox="0 0 24 24" aria-hidden="true" focusable={false}>
+                                <path d="M14 6v4H4v4h10v4l6-6-6-6z" />
+                              </svg>
+                              <span className="sr-only ui-grid-sr-only">{labels.pinRight}</span>
+                            </button>
+                          </div>
+                        </div>
+                      )}
                   </div>
                 </div>
-              ))}
+                );
+              })}
             </div>
 
             {/* Filter row */}
             {filteringFeature && state.isFilteringEnabled() && (
-              <div className="filter-grid ui-grid-header" data-part="filters" style={{ gridTemplateColumns }}>
-                {visibleColumns.map((column) => (
-                  <label key={column.name} className="filter-cell ui-grid-filter-container" data-part="filter-cell">
-                    <span className="sr-only ui-grid-sr-only">{labels.filterColumn} {state.headerLabel(column)}</span>
+              <div
+                className="filter-grid ui-grid-header"
+                data-part="filters"
+                ref={filterGridRef}
+                style={{ gridTemplateColumns, ['--ui-grid-header-sticky-top' as string]: `${headerStickyHeight}px` }}
+              >
+                {visibleColumns.map((column) => {
+                  const pinned = state.isPinned(column);
+                  const pinOffset = pinned ? state.pinnedOffset(column) : null;
+                  return (
+                  <label
+                    key={column.name}
+                    className={`filter-cell ui-grid-filter-container${pinned ? ' is-pinned' : ''}`}
+                    data-part="filter-cell"
+                    style={{
+                      position: pinned ? 'sticky' : undefined,
+                      left: pinOffset?.side === 'left' ? pinOffset.offset : undefined,
+                      right: pinOffset?.side === 'right' ? pinOffset.offset : undefined,
+                      zIndex: pinned ? 2 : undefined,
+                    }}
+                  >
+                    <span className="sr-only ui-grid-sr-only">
+                      {labels.filterColumn} {state.headerLabel(column)}
+                    </span>
                     <input
                       className="ui-grid-filter-input"
                       type="text"
@@ -336,36 +581,27 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
                       onChange={(e) => state.updateFilter(column.name, e.target.value)}
                     />
                   </label>
-                ))}
+                  );
+                })}
               </div>
             )}
 
             {/* Body */}
             {displayItems.length > 0 ? (
               virtualizationEnabled ? (
-                <div
-                  className="grid-viewport ui-grid-viewport"
-                  data-part="viewport"
-                  ref={virtualScroll.viewportRef}
-                  style={{ height: viewportHeightPx, overflow: 'auto', position: 'relative' }}
-                  onScroll={onViewportScroll}
-                >
-                  <div style={{ height: `${virtualScroll.totalHeight}px`, position: 'relative' }}>
-                    <div
-                      className="body-grid ui-grid-canvas"
-                      data-part="body"
-                      role="rowgroup"
-                      style={{
-                        gridTemplateColumns,
-                        position: 'absolute',
-                        top: 0,
-                        left: 0,
-                        right: 0,
-                        transform: `translateY(${virtualScroll.offsetY}px)`,
-                      }}
-                    >
-                      {itemsToRender.map(renderDisplayItem)}
-                    </div>
+                <div className="grid-virtual-spacer" style={{ height: `${virtualScroll.totalHeight}px` }}>
+                  <div
+                    className="body-grid ui-grid-canvas grid-virtual-body"
+                    data-part="body"
+                    role="rowgroup"
+                    style={{
+                      gridTemplateColumns,
+                      position: 'absolute',
+                      top: `${virtualScroll.offsetY}px`,
+                      left: 0,
+                    }}
+                  >
+                    {itemsToRender.map(renderDisplayItem)}
                   </div>
                 </div>
               ) : (
@@ -387,7 +623,12 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
 
             {/* Pagination footer */}
             {paginationFeature && state.showPaginationControls() && (
-              <footer className="pagination-bar ui-grid-pagination" data-part="pagination" role="navigation" aria-label={labels.paginationPage}>
+              <footer
+                className="pagination-bar ui-grid-pagination"
+                data-part="pagination"
+                role="navigation"
+                aria-label={labels.paginationPage}
+              >
                 <p>{state.paginationSummary()}</p>
                 <div className="pagination-controls">
                   <button
@@ -397,12 +638,20 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
                     disabled={paginationCurrentPage <= 1}
                     onClick={() => state.previousPage()}
                   >
-                    <svg className="pagination-icon" viewBox="0 0 24 24" aria-hidden="true" focusable={false}>
+                    <svg
+                      className="pagination-icon"
+                      viewBox="0 0 24 24"
+                      aria-hidden="true"
+                      focusable={false}
+                    >
                       <path d="M15.41 7.41L14 6l-6 6 6 6 1.41-1.41L10.83 12z" />
                     </svg>
                     <span className="sr-only">{labels.paginationPrevious}</span>
                   </button>
-                  <span>{labels.paginationPage} {paginationCurrentPage} {labels.paginationOf} {paginationTotalPages}</span>
+                  <span>
+                    {labels.paginationPage} {paginationCurrentPage} {labels.paginationOf}{' '}
+                    {paginationTotalPages}
+                  </span>
                   <button
                     type="button"
                     className="action action-secondary pagination-button"
@@ -410,7 +659,12 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
                     disabled={paginationCurrentPage >= paginationTotalPages}
                     onClick={() => state.nextPage()}
                   >
-                    <svg className="pagination-icon" viewBox="0 0 24 24" aria-hidden="true" focusable={false}>
+                    <svg
+                      className="pagination-icon"
+                      viewBox="0 0 24 24"
+                      aria-hidden="true"
+                      focusable={false}
+                    >
                       <path d="M8.59 16.59L10 18l6-6-6-6-1.41 1.41L13.17 12z" />
                     </svg>
                     <span className="sr-only">{labels.paginationNext}</span>
@@ -424,7 +678,9 @@ export function UiGrid({ options, onRegisterApi, cellRenderer, expandableRendere
                         onChange={(e) => state.onPageSizeChange(e.target.value)}
                       >
                         {state.pageSizeOptions().map((size) => (
-                          <option key={size} value={size}>{size}</option>
+                          <option key={size} value={size}>
+                            {size}
+                          </option>
                         ))}
                       </select>
                     </label>

package/src/gridStateMath.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import type { GridColumnDef } from '@ornery/ui-grid';
+import {
+  buildGridTemplateColumns,
+  computeViewportHeightPx,
+  computeViewportRows,
+  formatPaginationSummary,
+  orderVisibleColumns,
+  resolveBenchmarkIterations,
+} from './gridStateMath';
+
+describe('gridStateMath', () => {
+  const columns: GridColumnDef[] = [
+    { name: 'status', width: '2fr' },
+    { name: 'owner', visible: false },
+    { name: 'revenue', width: '120px' },
+    { name: 'customer' },
+  ];
+
+  it('orders only visible columns by the provided column order', () => {
+    expect(orderVisibleColumns(columns, ['customer', 'revenue', 'status', 'owner']).map((column) => column.name)).toEqual([
+      'customer',
+      'revenue',
+      'status',
+    ]);
+  });
+
+  it('builds grid template columns deterministically', () => {
+    expect(buildGridTemplateColumns(orderVisibleColumns(columns, ['status', 'revenue', 'customer']))).toBe('2fr 120px minmax(11rem, max-content)');
+  });
+
+  it('resolves benchmark iterations with a minimum of one', () => {
+    expect(resolveBenchmarkIterations(undefined, undefined)).toBe(25);
+    expect(resolveBenchmarkIterations(undefined, 7)).toBe(7);
+    expect(resolveBenchmarkIterations(0, 7)).toBe(1);
+  });
+
+  it('formats pagination summaries', () => {
+    expect(formatPaginationSummary(0, 0, 0)).toBe('0-0 of 0');
+    expect(formatPaginationSummary(42, 10, 19)).toBe('11-20 of 42');
+  });
+
+  it('computes viewport height and viewport rows', () => {
+    expect(computeViewportHeightPx(undefined, undefined)).toBe('560px');
+    expect(computeViewportHeightPx(620, 480)).toBe('620px');
+    expect(computeViewportRows(undefined, undefined)).toBe(13);
+    expect(computeViewportRows(220, 44)).toBe(5);
+  });
+});

package/src/gridStateMath.ts

@@ -0,0 +1,32 @@
+import type { GridColumnDef } from '@ornery/ui-grid';
+import { gridColumnWidth } from '@ornery/ui-grid';
+
+export function orderVisibleColumns(columns: readonly GridColumnDef[], order: readonly string[]): GridColumnDef[] {
+  return [...columns]
+    .filter((column) => column.visible !== false)
+    .sort((left, right) => order.indexOf(left.name) - order.indexOf(right.name));
+}
+
+export function buildGridTemplateColumns(columns: readonly GridColumnDef[]): string {
+  return columns.map((column) => gridColumnWidth(column)).join(' ');
+}
+
+export function resolveBenchmarkIterations(iterations?: number, configuredIterations?: number): number {
+  return Math.max(1, iterations ?? configuredIterations ?? 25);
+}
+
+export function formatPaginationSummary(totalItems: number, firstRowIndex: number, lastRowIndex: number): string {
+  if (totalItems === 0) {
+    return '0-0 of 0';
+  }
+
+  return `${firstRowIndex + 1}-${lastRowIndex + 1} of ${totalItems}`;
+}
+
+export function computeViewportHeightPx(viewportHeight?: number, autoViewportHeight?: number | null): string {
+  return `${viewportHeight ?? autoViewportHeight ?? 560}px`;
+}
+
+export function computeViewportRows(viewportHeight?: number, rowHeight?: number): number {
+  return Math.max(1, Math.ceil((viewportHeight ?? 560) / (rowHeight ?? 44)));
+}

package/src/index.ts

@@ -1,9 +1,12 @@
 export { UiGrid } from './UiGrid';
 export type { UiGridProps } from './UiGrid';
+export { mountUiGrid } from './mountUiGrid';
 export { useGridState } from './useGridState';
 export type { UseGridStateResult } from './useGridState';
 export { useVirtualScroll } from './useVirtualScroll';
 export type { UseVirtualScrollOptions, UseVirtualScrollResult } from './useVirtualScroll';
+export { orderVisibleColumns, buildGridTemplateColumns, resolveBenchmarkIterations, formatPaginationSummary, computeViewportHeightPx, computeViewportRows } from './gridStateMath';
+export { enableReactUiGridWasmEngine, registerReactUiGridWasmEngineFromModule } from './rustWasmGridEngine';
 
 export type {
   GridOptions,