@opencorestack/opengridx 3.5.0 → 3.6.0

package/lib/utils/direction.ts

@@ -0,0 +1,52 @@
+/** Whether `element` lays out right to left (`dir="rtl"` on it or an ancestor, or `direction: rtl`). */
+export function isRtl(element: Element | null | undefined): boolean {
+    if (!element) return false;
+    const view = element.ownerDocument.defaultView;
+    return view ? view.getComputedStyle(element).direction === 'rtl' : false;
+}
+
+/**
+ * The key as seen in a left-to-right layout: in a right-to-left one ArrowLeft and ArrowRight are
+ * swapped, so ArrowLeft always moves (or resizes, expands) towards the left of the screen.
+ */
+export function logicalArrowKey(key: string, rtl: boolean): string {
+    if (!rtl) return key;
+    if (key === 'ArrowLeft') return 'ArrowRight';
+    if (key === 'ArrowRight') return 'ArrowLeft';
+    return key;
+}
+
+/**
+ * How far `element` is scrolled from its inline start, never negative. In a right-to-left
+ * scroller modern engines report `scrollLeft` from 0 (at the start, on the right) down to
+ * `-(scrollWidth - clientWidth)`; the grid's column maths counts from the start edge.
+ */
+export function getScrollStart(element: HTMLElement): number {
+    return isRtl(element) ? -element.scrollLeft : element.scrollLeft;
+}
+
+/** Scrolls `element` to `offset` pixels from its inline start (see `getScrollStart`). */
+export function setScrollStart(element: HTMLElement, offset: number): void {
+    element.scrollLeft = isRtl(element) ? -offset : offset;
+}
+
+/** Fixed position of a toolbar panel under its button. */
+export interface GridPanelPosition {
+    top: number;
+    /** Distance from the viewport's right edge to the panel's right edge (left-to-right). */
+    right?: number;
+    /** Distance from the viewport's left edge to the panel's left edge (right-to-left). */
+    left?: number;
+}
+
+/**
+ * Places a panel under `anchor`, lined up with the button's end edge and opening towards the
+ * grid: leftwards in a left-to-right grid, rightwards in a right-to-left one.
+ */
+export function getPanelPosition(anchor: HTMLElement | null, viewportWidth: number): GridPanelPosition {
+    if (!anchor) return { top: 0, right: 0 };
+    const rect = anchor.getBoundingClientRect();
+    return isRtl(anchor)
+        ? { top: rect.bottom + 6, left: rect.left }
+        : { top: rect.bottom + 6, right: viewportWidth - rect.right };
+}

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/maxElementHeight.ts

@@ -0,0 +1,53 @@
+/**
+ * The tallest element this browser lays out. Browsers cap element heights: Chromium and Safari at
+ * about 33.5M px, Firefox at about 17.9M px. Firefox does not clamp an element that is taller — it
+ * collapses it, so a grid whose content is taller than the cap cannot be scrolled at all.
+ *
+ * Measured once per document with an invisible probe (one layout), from the largest candidate down.
+ * Returns `Infinity` where there is no layout engine (jsdom, SSR), so nothing is capped there.
+ */
+const CANDIDATES = [33_554_400, 17_895_000, 10_000_000, 5_000_000] as const;
+
+const cache = new WeakMap<Document, number>();
+
+function measure(doc: Document): number {
+    const body = doc.body;
+    if (!body) return Infinity;
+    const probe = doc.createElement('div');
+    probe.setAttribute('aria-hidden', 'true');
+    probe.style.cssText = 'position:absolute;top:0;left:-10000px;width:1px;visibility:hidden;pointer-events:none;';
+    body.appendChild(probe);
+    try {
+        probe.style.height = '100px';
+        // No layout engine: every element reads 0 tall.
+        if (Math.abs(probe.getBoundingClientRect().height - 100) > 1) return Infinity;
+        for (const height of CANDIDATES) {
+            probe.style.height = `${height}px`;
+            if (Math.abs(probe.getBoundingClientRect().height - height) < 2) return height;
+        }
+        return CANDIDATES[CANDIDATES.length - 1];
+    } finally {
+        probe.remove();
+    }
+}
+
+export function getMaxElementHeight(doc: Document | null | undefined): number {
+    if (!doc) return Infinity;
+    const known = cache.get(doc);
+    if (known !== undefined) return known;
+    const height = measure(doc);
+    cache.set(doc, height);
+    return height;
+}
+
+/** How many of the unpinned rows end at or above `limit` px (the rows a user can scroll to). */
+export function countReachableRows(cumulativeHeights: readonly number[], limit: number): number {
+    if (!Number.isFinite(limit)) return cumulativeHeights.length;
+    let lo = 0;
+    let hi = cumulativeHeights.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (cumulativeHeights[mid] <= limit) lo = mid + 1; else hi = mid;
+    }
+    return lo;
+}

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.0
+# 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.0",
+  "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",
@@ -53,12 +53,13 @@
     "build": "tsc --project tsconfig.build.json && vite build",
     "build:lib": "tsc --project tsconfig.build.json && vite build --config vite.config.lib.js && vite build --config vite.config.lib.js --mode ai && 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 && tsc -p e2e/tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit && tsc -p e2e/tsconfig.json && tsc -p bench/tsconfig.json",
     "preview": "vite preview",
     "test": "vitest run --project unit",
     "test:browser": "vitest run --project browser",
     "test:all": "vitest run",
     "test:smoke": "node scripts/smoke.mjs",
+    "bench": "node bench/run.mjs",
     "test:watch": "vitest --project unit",
     "coverage": "vitest run --coverage",
     "prepublishOnly": "npm run build:lib",