@opencorestack/opengridx 3.5.1 → 3.6.0

package/lib/utils/export/exportToExcelAdvanced.ts

@@ -358,8 +358,15 @@ export async function exportToExcelAdvanced<R extends GridRowModel>(
         groupSubtotalFillColor = '#f0f4ff',
     } = options;
 
-    // Lazy-load ExcelJS to keep initial bundle lean
-    const ExcelJS = (await import('exceljs')).default;
+    // Lazy-load ExcelJS to keep initial bundle lean. The import must stay inside `try`: webpack
+    // (Next.js 15, plain webpack 5) and Turbopack (Next.js 16) treat an unresolvable import() in a
+    // try block as optional, so apps without the peer still build. Outside `try` the build fails.
+    let ExcelJS: typeof import('exceljs');
+    try {
+        ExcelJS = (await import('exceljs')).default;
+    } catch {
+        throw new Error("exportToExcelAdvanced requires 'exceljs'. Run: npm install exceljs");
+    }
     const workbook = new ExcelJS.Workbook();
     workbook.creator = 'OpenGridX';
     workbook.created = new Date();

package/lib/utils/export/exportToPdf.ts

@@ -206,7 +206,8 @@ export async function runPdfExport<R extends GridRowModel>(
     };
     checkAbort();
 
-    // Lazy-load peer deps — provides a clear error if not installed
+    // Lazy-load peer deps — provides a clear error if not installed. Keep the imports inside `try`:
+    // webpack and Turbopack only build an app without the peers when the import() sits in a try block.
     let JsPDF: new (opts: Record<string, unknown>) => JsPDFDoc;
     let autoTable: AutoTableFn;
     try {

package/lib/utils/filtering/index.ts

@@ -255,15 +255,56 @@ function getCachedQuickFilterTexts(row: GridRowModel, columns: GridColumnLookup
   return texts;
 }
 
-function compileQuickFilter(values: readonly string[] | undefined, columns: GridColumnLookup | undefined): RowPredicate | null {
-  const terms = (values ?? [])
+function quickFilterTerms(values: readonly string[] | undefined): string[] {
+  return (values ?? [])
     .map(value => String(value ?? '').trim().toLowerCase())
     .filter(term => term !== '');
+}
+
+function textsMatchTerms(texts: readonly string[], terms: readonly string[]): boolean {
+  // Plain loops: this runs once per row on every keystroke.
+  for (let t = 0; t < terms.length; t++) {
+    const term = terms[t];
+    let found = false;
+    for (let i = 0; i < texts.length; i++) {
+      if (texts[i].includes(term)) {
+        found = true;
+        break;
+      }
+    }
+    if (!found) return false;
+  }
+  return true;
+}
+
+function compileQuickFilter(values: readonly string[] | undefined, columns: GridColumnLookup | undefined): RowPredicate | null {
+  const terms = quickFilterTerms(values);
   if (terms.length === 0) return null;
-  return (row) => {
-    const texts = getCachedQuickFilterTexts(row, columns);
-    return terms.every(term => texts.some(text => text.includes(term)));
-  };
+  return (row) => textsMatchTerms(getCachedQuickFilterTexts(row, columns), terms);
+}
+
+// filterRows also keeps the texts of the last rows array it searched, by position, per column
+// lookup. Looking a text up by index is much cheaper than one WeakMap entry per row, and after an
+// edit (a new array with mostly the same row objects at the same positions) only the rows whose
+// object changed are read again.
+interface QuickFilterArrayTexts {
+  rows: readonly GridRowModel[];
+  texts: string[][];
+}
+const quickFilterArrayCache = new WeakMap<GridColumnLookup, QuickFilterArrayTexts>();
+
+function getQuickFilterTextsByIndex(rows: readonly GridRowModel[], columns: GridColumnLookup): string[][] {
+  const previous = quickFilterArrayCache.get(columns);
+  if (previous && previous.rows === rows) return previous.texts;
+  const texts = new Array<string[]>(rows.length);
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    texts[i] = previous && i < previous.rows.length && previous.rows[i] === row
+      ? previous.texts[i]
+      : getQuickFilterTexts(row, columns);
+  }
+  quickFilterArrayCache.set(columns, { rows, texts });
+  return texts;
 }
 
 /**
@@ -333,6 +374,17 @@ export function filterRows<R extends GridRowModel>(
   filterModel: GridFilterModel,
   columns?: GridColumnLookup
 ): R[] {
+  const terms = columns && filterModel ? quickFilterTerms(filterModel.quickFilterValues) : [];
+  if (columns && terms.length > 0) {
+    // The same result as createRowFilter's predicate: the quick filter and then the items.
+    const itemsPredicate = compileGroup(filterModel.items ?? [], filterModel.logicOperator ?? 'and', { columns, warned: new Set() });
+    const texts = getQuickFilterTextsByIndex(rows, columns);
+    const result: R[] = [];
+    for (let i = 0; i < rows.length; i++) {
+      if (textsMatchTerms(texts[i], terms) && (!itemsPredicate || itemsPredicate(rows[i]))) result.push(rows[i]);
+    }
+    return result;
+  }
   const predicate = createRowFilter(filterModel, columns);
   if (!predicate) return rows;
   return rows.filter(row => predicate(row));

package/lib/utils/headerFilterLocale.ts

@@ -0,0 +1,37 @@
+import type { GridFilterOperator, GridLocaleText } from '../types';
+import { HEADER_FILTER_OPERATOR_LABELS } from './headerFilters';
+
+/** The header filter row's strings, with the English defaults filled in. */
+export interface HeaderFilterLocale {
+    custom: string;
+    customTooltip: string;
+    cellLabel: (header: string) => string;
+    valueLabel: (header: string) => string;
+    operatorButtonLabel: (header: string, operatorLabel: string) => string;
+    operatorMenuLabel: (header: string) => string;
+    clearLabel: (header: string) => string;
+    clearTooltip: string;
+    any: string;
+    yes: string;
+    no: string;
+    operator: (operator: GridFilterOperator) => string;
+}
+
+/** Resolves the header filter strings of `localeText`, falling back to English. */
+export function resolveHeaderFilterLocale(localeText: GridLocaleText | undefined): HeaderFilterLocale {
+    const operators = localeText?.headerFilterOperators;
+    return {
+        custom: localeText?.headerFilterCustom ?? 'Custom filter',
+        customTooltip: localeText?.headerFilterCustomTooltip ?? 'Set in the filter panel',
+        cellLabel: localeText?.headerFilterCellLabel ?? (h => `Filter ${h}`),
+        valueLabel: localeText?.headerFilterValueLabel ?? (h => `Filter value for ${h}`),
+        operatorButtonLabel: localeText?.headerFilterOperatorButtonLabel ?? ((h, op) => `Filter operator for ${h}: ${op}`),
+        operatorMenuLabel: localeText?.headerFilterOperatorMenuLabel ?? (h => `Filter operator for ${h}`),
+        clearLabel: localeText?.headerFilterClearLabel ?? (h => `Clear filter for ${h}`),
+        clearTooltip: localeText?.headerFilterClearTooltip ?? 'Clear',
+        any: localeText?.headerFilterAny ?? 'Any',
+        yes: localeText?.headerFilterTrue ?? 'Yes',
+        no: localeText?.headerFilterFalse ?? 'No',
+        operator: op => operators?.[op] ?? HEADER_FILTER_OPERATOR_LABELS[op] ?? op,
+    };
+}

package/lib/utils/scroll/index.ts

@@ -1,3 +1,4 @@
+import { getScrollStart, setScrollStart } from '../direction';
 /**
  * Height of the sticky block at the bottom of the viewport (bottom-pinned rows, their expanded
  * detail panels and the aggregation footer), measured from the DOM.
@@ -68,11 +69,12 @@ export function scrollColumnIntoView(viewport: HTMLElement, unpinnedIndex: numbe
     const colLeft = contentStart + (unpinnedIndex > 0 ? unpinnedAccWidths[unpinnedIndex - 1] : 0);
     const colRight = contentStart + unpinnedAccWidths[unpinnedIndex];
     const stickyLeft = pinnedSystemColumnsWidth + leftWidth;
-    const { scrollLeft, clientWidth } = viewport;
+    const { clientWidth } = viewport;
+    const scrollLeft = getScrollStart(viewport);
 
     if (colLeft < scrollLeft + stickyLeft) {
-        viewport.scrollLeft = Math.max(0, colLeft - stickyLeft);
+        setScrollStart(viewport, Math.max(0, colLeft - stickyLeft));
     } else if (colRight > scrollLeft + clientWidth - rightWidth) {
-        viewport.scrollLeft = colRight - clientWidth + rightWidth;
+        setScrollStart(viewport, colRight - clientWidth + rightWidth);
     }
 }

package/lib/utils/sorting/index.ts

@@ -154,16 +154,20 @@ export function sortRows<R extends GridRowModel>(
   if (sortModel.length === 0) {
     return rows;
   }
-  return sortItemsBySortModel(rows, sortModel, (row, sortItem) => {
+  if (rows.length < 2) return [...rows];
+  const sortColumns = sortModel.map(sortItem => {
     const colDef = columns?.byField.get(sortItem.field);
-    const value = getCellValue(row, sortItem.field, colDef);
-    return {
-      value,
-      type: colDef?.type,
-      comparator: colDef?.sortComparator,
-      params: colDef?.sortComparator ? { id: getRowId(row), field: sortItem.field, row, value } : undefined,
-    };
+    const comparator = colDef?.sortComparator;
+    if (comparator) {
+      return genericSortColumn(rows.map(row => {
+        const value = getCellValue(row, sortItem.field, colDef);
+        return { value, type: colDef.type, comparator, params: { id: getRowId(row), field: sortItem.field, row, value } };
+      }));
+    }
+    const type = colDef?.type;
+    return encodeSortColumn(rows.length, i => getCellValue(rows[i], sortItem.field, colDef), () => type);
   });
+  return sortByColumns(rows, sortModel, sortColumns);
 }
 
 /** The value an item sorts by for one sort key, and how to compare it. */
@@ -194,26 +198,137 @@ export function sortItemsBySortModel<T>(
     return [...items];
   }
 
-  // Read and normalize every sort value once, instead of calling valueGetter and parsing dates
-  // O(n log n) times inside the comparator.
-  const values = sortModel.map(sortItem => items.map(item => readValue(item, sortItem)));
-  const keys = values.map(column => column.map(({ value, type }) => toSortKey(value, type)));
-
-  const order = items.map((_, index) => index);
-  order.sort((ia, ib) => {
-    for (let k = 0; k < sortModel.length; k++) {
-      const a = values[k][ia];
-      const b = values[k][ib];
-      const ascending = a.comparator && a.comparator === b.comparator && a.params && b.params
-        ? callSortComparator(a.comparator, a.params, b.params)
-        : compareSortKeys(keys[k][ia], keys[k][ib]);
-      const comparison = applySortDirection(ascending, sortModel[k].sort);
-      if (comparison !== 0) return comparison;
-    }
-    return ia - ib;
+  // Read every sort value once, instead of calling valueGetter and parsing dates O(n log n) times
+  // inside the comparator.
+  const columns = sortModel.map(sortItem => {
+    const values = items.map(item => readValue(item, sortItem));
+    // A key where no item carries a comparator compares by the built-in order only, so it can be
+    // encoded up front.
+    return values.some(v => v.comparator && v.params)
+      ? genericSortColumn(values)
+      : encodeSortColumn(values.length, i => values[i].value, i => values[i].type);
   });
+  return sortByColumns(items, sortModel, columns);
+}
+
+/** One sort key, ready to compare: encoded into typed arrays, or kept as values when a sortComparator applies. */
+type SortColumn =
+  | { kind: 'encoded'; group: Uint8Array; num: Float64Array }
+  | { kind: 'generic'; values: readonly GridSortValue[]; keys: readonly SortKey[] };
+
+/** The group of the empty bucket: after every rank, as in compareSortKeys. */
+const GROUP_EMPTY = RANK_OTHER + 1;
+
+/** Give each item of `buckets` (distinct text → item indexes) its text's position in collator order. */
+function rankTexts(buckets: Map<string, number[]>, num: Float64Array): void {
+  const distinct = [...buckets.keys()].sort(collator.compare);
+  // Texts the collator calls equal share a position, so they tie exactly as in compareSortKeys.
+  let position = 0;
+  for (let d = 0; d < distinct.length; d++) {
+    if (d > 0 && collator.compare(distinct[d - 1], distinct[d]) !== 0) position++;
+    for (const i of buckets.get(distinct[d]) ?? []) num[i] = position;
+  }
+}
+
+function addToBucket(buckets: Map<string, number[]>, text: string, index: number): void {
+  const bucket = buckets.get(text);
+  if (bucket) bucket.push(index);
+  else buckets.set(text, [index]);
+}
+
+/**
+ * Encode one key as (group, number) per item. The group is the value's rank, with the empty bucket
+ * last; the number is the value itself for numbers, dates and booleans, and for strings (and other
+ * values) the position of its text among the key's distinct texts in collator order. Comparing
+ * (group, number) gives exactly compareSortKeys' order, while the collator runs only to sort the
+ * distinct texts instead of in every row comparison.
+ */
+function encodeSortColumn(count: number, valueAt: (i: number) => unknown, typeAt: (i: number) => GridColDef['type']): SortColumn {
+  const group = new Uint8Array(count);
+  const num = new Float64Array(count);
+  const strings = new Map<string, number[]>();
+  const others = new Map<string, number[]>();
+  for (let i = 0; i < count; i++) {
+    const value = valueAt(i);
+    const type = typeAt(i);
+    if (typeof value === 'number' && type !== 'date') {
+      // toSortKey for a number, without the allocation.
+      if (Number.isNaN(value)) {
+        group[i] = GROUP_EMPTY;
+      } else {
+        group[i] = RANK_NUMBER;
+        num[i] = value;
+      }
+      continue;
+    }
+    const key = toSortKey(value, type);
+    if (key === null) {
+      group[i] = GROUP_EMPTY;
+    } else {
+      group[i] = key.rank;
+      if (key.rank === RANK_STRING) addToBucket(strings, key.str, i);
+      else if (key.rank === RANK_OTHER) addToBucket(others, key.str, i);
+      else num[i] = key.num;
+    }
+  }
+  rankTexts(strings, num);
+  rankTexts(others, num);
+  return { kind: 'encoded', group, num };
+}
+
+function genericSortColumn(values: readonly GridSortValue[]): SortColumn {
+  return { kind: 'generic', values, keys: values.map(({ value, type }) => toSortKey(value, type)) };
+}
+
+/** Ascending comparison of items `ia` and `ib` on one key. */
+function compareInColumn(column: SortColumn, ia: number, ib: number): number {
+  if (column.kind === 'encoded') {
+    const ga = column.group[ia];
+    const gb = column.group[ib];
+    if (ga !== gb) return ga - gb;
+    const na = column.num[ia];
+    const nb = column.num[ib];
+    return na < nb ? -1 : na > nb ? 1 : 0;
+  }
+  const a = column.values[ia];
+  const b = column.values[ib];
+  return a.comparator && a.comparator === b.comparator && a.params && b.params
+    ? callSortComparator(a.comparator, a.params, b.params)
+    : compareSortKeys(column.keys[ia], column.keys[ib]);
+}
 
-  return order.map(index => items[index]);
+/** Stable sort by prepared keys: the first key that differs decides, ties keep the input order. */
+function sortByColumns<T>(items: readonly T[], sortModel: readonly GridSortItem[], columns: readonly SortColumn[]): T[] {
+  const n = items.length;
+  const order = new Array<number>(n);
+  for (let i = 0; i < n; i++) order[i] = i;
+  const first = columns[0];
+  if (columns.length === 1 && first.kind === 'encoded') {
+    // The common single-key case, without the per-comparison key loop.
+    const { group, num } = first;
+    const sign = sortModel[0].sort === 'asc' ? 1 : -1;
+    order.sort((ia, ib) => {
+      const ga = group[ia];
+      const gb = group[ib];
+      if (ga !== gb) return (ga - gb) * sign;
+      const na = num[ia];
+      const nb = num[ib];
+      if (na < nb) return -sign;
+      if (na > nb) return sign;
+      return ia - ib;
+    });
+  } else {
+    order.sort((ia, ib) => {
+      for (let k = 0; k < columns.length; k++) {
+        const comparison = applySortDirection(compareInColumn(columns[k], ia, ib), sortModel[k].sort);
+        if (comparison !== 0) return comparison;
+      }
+      return ia - ib;
+    });
+  }
+  const result = new Array<T>(n);
+  for (let i = 0; i < n; i++) result[i] = items[order[i]];
+  return result;
 }
 
 /**

package/lib/utils/values.ts

@@ -53,6 +53,9 @@ export function tryGetCellValue<R extends GridRowModel>(
  * per column), so one bad record cannot take the whole grid down.
  */
 export function getCellValue<R extends GridRowModel>(row: R, field: string, colDef?: ValueGetterColumn<R>): unknown {
+    // Plain columns read the field directly: this runs once per row and column in every
+    // whole-dataset pass (sort, filter, grouping, aggregation), so it must not allocate.
+    if (!colDef?.valueGetter) return row[field];
     const { value, error } = tryGetCellValue(row, field, colDef);
     if (error !== undefined) {
         warnCallbackFailure(`valueGetter:${field}`, `valueGetter for column "${field}" threw; the value is read as undefined`, error);
@@ -72,12 +75,13 @@ export function getFormattedValue<R extends GridRowModel>(
 ): string | undefined {
     const formatter = colDef?.valueFormatter;
     if (!formatter) return undefined;
-    return callSafely(
-        () => formatter({ value, row, field }),
-        undefined,
-        `valueFormatter:${field}`,
-        `valueFormatter for column "${field}" threw; the value is shown unformatted`,
-    );
+    // callSafely inlined: this runs for every cell of the quick filter's first search.
+    try {
+        return formatter({ value, row, field });
+    } catch (error) {
+        warnCallbackFailure(`valueFormatter:${field}`, `valueFormatter for column "${field}" threw; the value is shown unformatted`, error);
+        return undefined;
+    }
 }
 
 /**

package/llms.txt

@@ -1,6 +1,6 @@
 # OpenGridX — AI Agent Context
 # Package: @opencorestack/opengridx
-# Version: 3.5.1
+# Version: 3.6.0
 # Docs: https://opencorestack.github.io/OpenGridX/
 # This file is machine-readable. AI developers: start here.
 
@@ -75,7 +75,7 @@ export default function App() {
 | autoHeight        | boolean   | false   | Fit height to rows (renders every row) |
 | overscanRowCount  | number    | 3       | Minimum rows rendered outside the viewport (raised automatically while scrolling fast) |
 | ariaLabel         | string    | —       | Accessible name for the grid          |
-| localeText        | GridLocaleText | —  | Override pager / no-rows strings: paginationRowsPerPage, paginationOf(from,to,count), paginationPage(page,count), noRowsLabel |
+| localeText        | GridLocaleText | —  | Override strings: paginationRowsPerPage, paginationOf(from,to,count), paginationPage(page,count), noRowsLabel, cellSelectionAnnouncement, aiAssistantButton; header filter row (3.6): headerFilterCustom, headerFilterCustomTooltip, headerFilterCellLabel(h), headerFilterValueLabel(h), headerFilterOperatorButtonLabel(h, op), headerFilterOperatorMenuLabel(h), headerFilterClearLabel(h), headerFilterClearTooltip, headerFilterAny, headerFilterTrue, headerFilterFalse, headerFilterOperators (Partial<Record<GridFilterOperator,string>>) |
 | rowHeight         | number    | 52      | Row height in pixels                   |
 | headerHeight      | number    | 56      | Header height in pixels                |
 | wrapHeaderText    | boolean   | false   | Wrap header titles within headerHeight (2 lines at 56px, 3 at 72, 4 at 88; ellipsis on the last line). Header never grows: raise headerHeight for more lines. Class ogx__header-cell--wrap. Per column: GridColDef.wrapHeaderText (3.3.0+) |
@@ -725,3 +725,5 @@ Arrows move between cells (skipping hidden columns); Home/End, Ctrl+Home/End, Pa
 17. **Server modes without dataSource**: with `paginationMode` / `sortingMode` / `filterMode` = `'server'` the grid shows `rows` as given (no slicing, sorting or filtering). Fetch from the change callbacks and control the models.
 18. **`valueFormatter` / `valueGetter` params are `unknown`-typed**: cast (`(value as number).toFixed(2)`) before calling methods, or TypeScript strict mode rejects it.
 19. **Inline `columns` are reused while shallow-equal**: a new array with the same column objects does not re-run filtering/sorting, but mutating a column object in place is not detected — pass new objects when a definition changes.
+20. **Next.js App Router**: render `<DataGrid>` from a `'use client'` file (column functions such as `valueFormatter` cannot cross from a Server Component) and import the stylesheet in `app/layout.tsx`. Rows fetched in a Server Component pass as props (serialisable data only). The ES bundle starts with `'use client'` (3.6+), so a Server Component may also render `<DataGrid>` with serialisable props. `next build` fails with `Can't resolve 'exceljs'` unless the optional peers are installed or aliased in `next.config.ts` (`turbopack.resolveAlias` to an empty module; webpack `resolve.alias[name] = false`). `@opencorestack/opengridx/ai` runs on the server too, but the validation brand is a Symbol that does not survive JSON: validate on the client (`createGridAiPromptHandler`). Guide: `docs/features/nextjs.md`.
+21. **Right-to-left**: wrap the grid in `dir="rtl"` (or set `document.dir`); no prop. Works without pinned columns (3.6+): column order, text alignment (`align: 'left'`/'right' = start/end), horizontal scrolling + column virtualization, ArrowLeft = next column, resize handle on the left edge, fill handle bottom-left, toolbar panels open rightwards. **Pinned columns are not supported in RTL** (they do not stick); do not pin in RTL grids. Guide: `docs/features/rtl.md`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencorestack/opengridx",
-  "version": "3.5.1",
+  "version": "3.6.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",