@opencorestack/opengridx 3.5.0 → 3.6.0

package/docs/API_REFERENCE.md

@@ -243,7 +243,7 @@ Public CSS: `ogx__cell-fill-handle` (24 × 24 px hit area in the corner cell; th
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `localeText` | `GridLocaleText` | — | Override user-visible strings: the Pagination labels, the empty-state label (`noRowsLabel`, which wins over the `noRowsLabel` prop), the cell-range announcement and the Ask AI button (`aiAssistantButton`). See [`GridLocaleText`](#gridlocaletext). |
+| `localeText` | `GridLocaleText` | — | Override user-visible strings: the Pagination labels, the empty-state label (`noRowsLabel`, which wins over the `noRowsLabel` prop), the cell-range announcement, the Ask AI button (`aiAssistantButton`) and the header filter row (`headerFilter*`, v3.6). See [`GridLocaleText`](#gridlocaletext). |
 
 #### Imperative Ref
 
@@ -889,6 +889,19 @@ interface GridLocaleText {
   cellSelectionAnnouncement?: (cellCount: number, rowCount: number, columnCount: number) => string;
   /** v3.5: label of the toolbar's Ask AI button. Default "Ask AI". */
   aiAssistantButton?: string;
+  /** v3.6: header filter row strings (defaults in English). See features/header-filters.md#translating-the-row. */
+  headerFilterCustom?: string;                      // "Custom filter"
+  headerFilterCustomTooltip?: string;               // "Set in the filter panel"
+  headerFilterCellLabel?: (header: string) => string;           // "Filter Qty"
+  headerFilterValueLabel?: (header: string) => string;          // "Filter value for Qty"
+  headerFilterOperatorButtonLabel?: (header: string, operatorLabel: string) => string; // "Filter operator for Qty: Equals"
+  headerFilterOperatorMenuLabel?: (header: string) => string;   // "Filter operator for Qty"
+  headerFilterClearLabel?: (header: string) => string;          // "Clear filter for Qty"
+  headerFilterClearTooltip?: string;                // "Clear"
+  headerFilterAny?: string;                         // "Any"
+  headerFilterTrue?: string;                        // "Yes"
+  headerFilterFalse?: string;                       // "No"
+  headerFilterOperators?: Partial<Record<GridFilterOperator, string>>; // operator names
 }
 ```
 

package/docs/README.md

@@ -48,9 +48,11 @@ In-depth guides on the grid's functional capabilities.
 - **[Cell Spanning](features/cell-spanning.md)** - Row and Col span spanning
 - **[Master-Detail](features/master-detail.md)** - Expandable Detail Panels
 - **[Keyboard & Accessibility](features/keyboard-navigation.md)** - Keys, focus behaviour and ARIA structure
+- **[Right-to-Left (RTL)](features/rtl.md)** - What works in `dir="rtl"`, what was fixed, and the known limitations (pinned columns)
 - **[List View](features/list-view.md)** - Card-based responsive layout
 - **[Infinite Scroll](features/infinite-scroll.md)** - Advanced performance loading
 - **[Data Source](features/data-source.md)** - Server-side fetching and SSR
+- **[Next.js (App Router)](features/nextjs.md)** - Client components, server-fetched rows, Route Handlers, the AI toolkit on server and client, common errors
 - **[Export Guide](features/export-guide.md)** - Excel, CSV, JSON, and Print
 - **[AI Toolkit](features/ai-toolkit.md)** - JSON Schema of the grid state for your own model, a validator for its replies, the **Ask AI** panel (`aiAssistant`) and tools for AI agents (`@opencorestack/opengridx/ai`)
 

package/docs/architecture/datagrid-orchestration.md

@@ -71,7 +71,8 @@ in an effect, so **keep the call order when you move or add a hook**. In particu
 | 31 | `useGridScrollToIndexesApi` | `hooks/core/useGridScrollToIndexesApi.ts` | `scrollToIndexes` |
 | 31a | `useGridColumnAutosize` | `hooks/core/useGridColumnAutosize.ts` | `autosizeColumn` / `autosizeColumns` on the API, and the resize handle's auto-size handler (v3.1) |
 | 32 | `useGridViewport` | `hooks/core/useGridViewport.ts` | Scroll sync, viewport measurement, viewport callback ref |
-| 33 | `useGridVirtualization` | `hooks/core/useGridVirtualization.ts` | Render window |
+| 32a | `useGridMaxContentHeight` | `hooks/core/useGridMaxContentHeight.ts` | The tallest element this browser lays out (`utils/maxElementHeight.ts`, measured once per document after mount; `undefined` until then, `Infinity` without a layout engine) |
+| 33 | `useGridVirtualization` | `hooks/core/useGridVirtualization.ts` | Render window; `virtualContainerHeight` caps the rows' container to `maxContentHeight` (Firefox collapses taller elements) |
 | 34 | `useGridSortHandlers` | `hooks/core/useGridHeaderHandlers.ts` | Header sort / shift-sort |
 | 35 | `useGridKeyboardNavigation` | `hooks/core/useGridKeyboardNavigation.ts` | Focus and keyboard handling; takes `cellSelection.keyboard` (Shift+navigation, Escape, Ctrl/Cmd+A) |
 | 36 | `useGridPointerFocusHandlers` | `hooks/core/useGridFocusHandlers.ts` | Cell and header click focus |

package/docs/features/ai-toolkit.md

@@ -104,7 +104,7 @@ getGridAiSchema(
 
 ## `validateGridAiState(json, columns, options?)`
 
-Returns `{ state, errors }`, where `state` is a `GridAiState` (`filterModel`, `sortModel`, `rowGroupingModel`, `aggregationModel`, `pivotModel`, `columnVisibilityModel`, each present only when the reply contained it) and `errors` is a list of `{ path, message }`, such as `{ path: 'filterModel.items[2].field', message: 'Unknown field "revenue"' }`.
+Returns `{ state, errors }`, where `state` is a `GridAiState` (`filterModel`, `sortModel`, `rowGroupingModel`, `aggregationModel`, `pivotModel`, `columnVisibilityModel`, each present only when the reply contained it) and `errors` is a list of `{ path, message }`, such as `{ path: 'filterModel.items[2].field', message: 'Unknown field "revenue"' }`. A top-level string `message` key (the model's reply text, which `createGridAiPromptHandler` shows) is skipped in both object and JSON string input, so you can validate a whole reply without removing it first; a `message` that is not a string is reported.
 
 - `json` may be an object or a JSON string. Bad JSON gives one error and an empty state.
 - Unknown parts, unknown fields, fields a column does not allow (`filterable: false` …), operators that do not fit the column type, and functions or enum values outside the allowed list are **dropped**, each with an error. Parts outside `options.include` / `options.exclude` are dropped too.
@@ -172,7 +172,7 @@ A copied state (`{ ...result.state }`) or a hand-built one is not branded.
 Returns the `onPrompt` function. It builds the schema once (from `columns`, limited to `parts` and `schemaOptions`), then for each prompt:
 
 1. calls `callModel({ prompt, schema, currentState, history }, { signal })`;
-2. reads the reply: a state object, a JSON string, or text with a fenced `json` block (the text around the block becomes `result.message`). An object's string `message` key is the message, not state. Plain text with no JSON becomes the message with nothing to apply;
+2. reads the reply: a state object, a JSON string, or text with a fenced `json` block (the text around the block becomes `result.message`). A string `message` key in the state object (or in the JSON of a string reply) is the message, not state; when a fenced block has text around it and a `message` key inside, both are kept, joined by a blank line. Plain text with no JSON becomes the message with nothing to apply;
 3. validates it with `validateGridAiState` (same `parts`) and returns the branded `{ state, errors, message? }`.
 
 A `callModel` throw or rejection becomes `{ state: {}, errors: [{ path: '', message: 'The model call failed: …' }] }`. An abort (Stop, a new prompt, closing the panel) rejects with an `AbortError`, even when `callModel` ignores the signal.

package/docs/features/export-guide.md

@@ -2,6 +2,8 @@
 
 The DataGrid provides built-in export utilities for multiple formats. The standard exports (CSV, JSON, Print, basic Excel) have **zero dependencies**. The advanced Excel export uses [ExcelJS](https://github.com/exceljs/exceljs) loaded lazily.
 
+`exceljs` is an optional peer dependency: install it (`npm install exceljs`) only if you call `exportToExcelAdvanced`. Apps without it still build in Vite, webpack 5 and Next.js (Turbopack and webpack; webpack prints a `Module not found` warning for the optional import), and `exportToExcelAdvanced` then rejects with `exportToExcelAdvanced requires 'exceljs'. Run: npm install exceljs`. Before v3.6, webpack and Next.js builds failed without it.
+
 ## Available Export Formats
 
 | Format | Function | Deps | Description |

package/docs/features/header-filters.md

@@ -107,6 +107,40 @@ The filter row is a header row (`role="row"`) between the column headers and the
 
 Inside a control, arrow keys edit the text (or move through a select) and do not move the grid's focus, as in a cell editor. **Escape** returns focus to the filter cell. **Tab** leaves the grid: the grid stays a single Tab stop and every control in the row has `tabIndex={-1}`.
 
+## Translating the row
+
+Every string the row shows or announces comes from `localeText` (v3.6). Each key defaults to the English text below.
+
+| `GridLocaleText` key | Type | Default |
+| :--- | :--- | :--- |
+| `headerFilterCustom` | `string` | `"Custom filter"` |
+| `headerFilterCustomTooltip` | `string` | `"Set in the filter panel"` |
+| `headerFilterCellLabel` | `(header) => string` | `` `Filter ${header}` `` (the cell's `aria-label`) |
+| `headerFilterValueLabel` | `(header) => string` | `` `Filter value for ${header}` `` |
+| `headerFilterOperatorButtonLabel` | `(header, operatorLabel) => string` | `` `Filter operator for ${header}: ${operatorLabel}` `` |
+| `headerFilterOperatorMenuLabel` | `(header) => string` | `` `Filter operator for ${header}` `` |
+| `headerFilterClearLabel` | `(header) => string` | `` `Clear filter for ${header}` `` |
+| `headerFilterClearTooltip` | `string` | `"Clear"` |
+| `headerFilterAny` | `string` | `"Any"` (boolean and `singleSelect` selects) |
+| `headerFilterTrue` / `headerFilterFalse` | `string` | `"Yes"` / `"No"` |
+| `headerFilterOperators` | `Partial<Record<GridFilterOperator, string>>` | English names ("Contains", "Is empty", ...); operators left out keep them |
+
+```tsx
+<DataGrid
+    headerFilters
+    localeText={{
+        headerFilterAny: 'Tous',
+        headerFilterTrue: 'Oui',
+        headerFilterFalse: 'Non',
+        headerFilterCellLabel: (h) => `Filtrer ${h}`,
+        headerFilterOperators: { contains: 'Contient', isEmpty: 'Est vide' },
+    }}
+    /* ... */
+/>
+```
+
+The operator symbols on the buttons (`=`, `≠`, `>`) are not translated. Demo: *Locale Text* (`/locale-text`).
+
 ## Layout
 
 - The row sits inside the sticky header block (`.ogx__header-wrap`), under any column group rows and the column header row, so it stays at the top while rows scroll.

package/docs/features/keyboard-navigation.md

@@ -108,6 +108,8 @@ In `listView`, focus moves between whole rows instead of cells:
 
 Keys pressed in content your `renderCell` puts in a row (inputs, buttons) are left to that content.
 
+In a right-to-left grid (`dir="rtl"`, v3.6) ArrowLeft and ArrowRight follow the screen: ArrowLeft moves to the next column, and the Alt+Arrow shortcuts (expand / collapse, header resize) are mirrored the same way. See [Right-to-Left](rtl.md).
+
 ## ARIA structure
 
 | Element | Attributes |

package/docs/features/nextjs.md

@@ -0,0 +1,241 @@
+# Next.js (App Router)
+
+OpenGridX is a client component: it uses state, effects, context and the DOM. In the App Router you render it from a file marked `'use client'`, and fetch the data in Server Components or Route Handlers.
+
+Everything on this page was built with `next build`, served with `next start` and loaded in Chromium, Firefox and WebKit without console errors, on Next.js 16.4 (Turbopack; `next build --webpack` also builds) and 15.5 (webpack), React 19.3.
+
+## 1. Install and import the stylesheet
+
+```bash
+npm install @opencorestack/opengridx
+```
+
+Import the stylesheet once, in the root layout:
+
+```tsx
+// app/layout.tsx
+import type { ReactNode } from 'react';
+import '@opencorestack/opengridx/styles';
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+    return (
+        <html lang="en">
+            <body>{children}</body>
+        </html>
+    );
+}
+```
+
+### The optional export peers
+
+`exportToExcelAdvanced` needs `exceljs`, and `exportToPdf` needs `jspdf` + `jspdf-autotable`. The grid loads them with `import()` only when you call those functions. Install them if you use those exports:
+
+```bash
+npm install exceljs jspdf jspdf-autotable
+```
+
+If you do not install them, the app still builds (Turbopack and webpack treat these imports as optional; webpack prints a `Module not found` **warning**, not an error) and every other export works. Calling `exportToExcelAdvanced` or `exportToPdf` then rejects with an install hint such as `exportToExcelAdvanced requires 'exceljs'. Run: npm install exceljs`. No `next.config` alias is needed from v3.6. In 3.5.1 and earlier `next build` failed with `Module not found: Can't resolve 'exceljs'` without the peers.
+
+## 2. Render the grid from a client component
+
+Column definitions usually hold functions (`valueFormatter`, `renderCell`, `valueGetter`). Functions cannot cross from a Server Component to a Client Component, so **define the columns in the client file**:
+
+```tsx
+// app/OrdersGrid.tsx
+'use client';
+
+import { DataGrid, GridToolbar, type GridColDef } from '@opencorestack/opengridx';
+import type { Order } from '../lib/orders';
+
+const columns: GridColDef<Order>[] = [
+    { field: 'id', headerName: 'ID', type: 'number', width: 80 },
+    { field: 'customer', headerName: 'Customer', flex: 1 },
+    {
+        field: 'amount',
+        headerName: 'Amount',
+        type: 'number',
+        width: 140,
+        valueFormatter: ({ value }) => `$${Number(value).toFixed(2)}`,
+    },
+    { field: 'shipped', headerName: 'Shipped', type: 'boolean', width: 110 },
+];
+
+export function OrdersGrid({ rows }: { rows: Order[] }) {
+    return (
+        <DataGrid
+            rows={rows}
+            columns={columns}
+            height={480}
+            checkboxSelection
+            headerFilters
+            slots={{ toolbar: GridToolbar }}
+        />
+    );
+}
+```
+
+Give the grid a `height` (or a parent with a bounded height): without one it fills its container, and in an auto-height page that means every row renders. See [Virtualization](virtualization.md).
+
+## 3. Fetch rows in a Server Component
+
+The page stays a Server Component. It loads the rows and passes them as props. Props must be serialisable: plain objects, arrays, strings, numbers, booleans, `null`. `Date` objects survive; class instances, `Map`s with functions and functions do not.
+
+```tsx
+// app/page.tsx (Server Component, no 'use client')
+import { getOrders } from '../lib/orders';
+import { OrdersGrid } from './OrdersGrid';
+
+export default async function Page() {
+    const rows = await getOrders(); // a database query, fetch() to your API, ...
+    return <OrdersGrid rows={rows} />;
+}
+```
+
+The grid renders on the server (the first screen of rows is in the HTML) and hydrates in the browser.
+
+**Rendering `<DataGrid>` straight from a Server Component** works from v3.6, whose bundle starts with `'use client'`, as long as every prop is serialisable (`columns={[{ field: 'name' }]}`, no functions). In 3.5.1 and earlier it fails with `TypeError: createContext is not a function`. Wrapping the grid in your own client file, as above, works in every version and is where your column functions belong anyway.
+
+## 4. Server-side data with `dataSource` and a Route Handler
+
+For large tables, let the server sort, filter and page. The `dataSource` lives in the client file and calls a Route Handler:
+
+```tsx
+// app/orders/ServerOrdersGrid.tsx
+'use client';
+
+import { DataGrid, GridToolbar, type GridColDef, type GridDataSource } from '@opencorestack/opengridx';
+import type { Order } from '../../lib/orders';
+
+const columns: GridColDef<Order>[] = [
+    { field: 'id', headerName: 'ID', type: 'number', width: 80 },
+    { field: 'customer', headerName: 'Customer', flex: 1 },
+    { field: 'amount', headerName: 'Amount', type: 'number', width: 140 },
+];
+
+// Module scope (or useMemo): a new dataSource object on every render refetches.
+const dataSource: GridDataSource<Order> = {
+    getRows: async (params) => {
+        const res = await fetch('/api/orders', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(params),
+        });
+        if (!res.ok) throw new Error(`Orders request failed: ${res.status}`);
+        return res.json();
+    },
+};
+
+export function ServerOrdersGrid() {
+    return (
+        <DataGrid
+            rows={[]}
+            columns={columns}
+            dataSource={dataSource}
+            sortingMode="server"
+            filterMode="server"
+            paginationMode="server"
+            pagination
+            initialState={{ pagination: { paginationModel: { page: 0, pageSize: 25 } } }}
+            height={480}
+            slots={{ toolbar: GridToolbar }}
+        />
+    );
+}
+```
+
+```ts
+// app/api/orders/route.ts
+import type { GridGetRowsParams, GridGetRowsResponse } from '@opencorestack/opengridx';
+import { queryOrders } from '../../../lib/orders';
+
+export async function POST(request: Request) {
+    const params = (await request.json()) as GridGetRowsParams;
+    // params: startRow, endRow, sortModel, filterModel (items, quickFilterValues), groupKeys
+    const { rows, total } = await queryOrders(params);
+    const body: GridGetRowsResponse = { rows, rowCount: total };
+    return Response.json(body);
+}
+```
+
+Importing types from the package in a Route Handler is free: they are erased at build time. See [Data Source](data-source.md) for the request and response shapes.
+
+## 5. The AI toolkit (`@opencorestack/opengridx/ai`)
+
+`@opencorestack/opengridx/ai` has no React code and no imports, so it runs anywhere: Server Components, Route Handlers, middleware and the browser.
+
+- **On the server**: build the schema (`getGridAiSchema`) for your model call, and keep your API key there. You may also run `validateGridAiState` on the reply to log or reject bad answers.
+- **In the browser**: the grid applies a reply only if `validateGridAiState` branded it, and the brand is a `Symbol` that does not survive JSON. So the reply must be validated again on the client. `createGridAiPromptHandler` does that for you:
+
+```tsx
+// app/ai/AiOrdersGrid.tsx
+'use client';
+
+import { DataGrid, GridToolbar } from '@opencorestack/opengridx';
+import { createGridAiPromptHandler } from '@opencorestack/opengridx/ai';
+import { aiColumns } from '../../lib/aiColumns'; // plain column data, shared with the route
+import type { Order } from '../../lib/orders';
+
+const onPrompt = createGridAiPromptHandler({
+    columns: aiColumns,
+    callModel: async (request, { signal }) => {
+        // request: { prompt, schema, currentState, history }
+        const res = await fetch('/api/grid-ai', { method: 'POST', body: JSON.stringify(request), signal });
+        return res.json(); // e.g. { filterModel, sortModel, message }
+    },
+});
+
+export function AiOrdersGrid({ rows }: { rows: Order[] }) {
+    return <DataGrid rows={rows} columns={aiColumns} height={480} slots={{ toolbar: GridToolbar }} aiAssistant={{ onPrompt }} />;
+}
+```
+
+```ts
+// app/api/grid-ai/route.ts
+import { validateGridAiState } from '@opencorestack/opengridx/ai';
+import { aiColumns } from '../../../lib/aiColumns';
+
+export async function POST(request: Request) {
+    const { prompt, schema, currentState } = await request.json();
+    const reply = await callYourModel({ prompt, schema, currentState }); // your SDK, with `schema` as structured output
+    // Optional server-side check. A string `message` key is skipped, not reported as an error.
+    const { errors } = validateGridAiState(reply, aiColumns);
+    if (errors.length) console.info('Model reply had invalid parts:', errors);
+    return Response.json(reply);
+}
+```
+
+Columns shared between the route and the client must be plain data (no functions), or the server gets a client reference instead of the array. Keep a function-free list such as `aiColumns` in a module without `'use client'`, and spread extra function fields onto it in the client file if the grid needs them.
+
+## Pages Router
+
+The Pages Router has no Server Components: every page is a client component that also renders on the server. Import the grid directly in the page, and the stylesheet in `pages/_app.tsx`:
+
+```tsx
+// pages/_app.tsx
+import type { AppProps } from 'next/app';
+import '@opencorestack/opengridx/styles';
+
+export default function App({ Component, pageProps }: AppProps) {
+    return <Component {...pageProps} />;
+}
+```
+
+Column functions can stay in the page. Rows from `getServerSideProps` / `getStaticProps` must be JSON-serialisable (no `Date`; send ISO strings and use `valueGetter`).
+
+## Common errors
+
+| Error | Cause and fix |
+| :--- | :--- |
+| `You're importing a module that depends on useState into a React Server Component module` (webpack: `…needs useState. This React hook only works in a Client Component`) | A file of yours that calls hooks (or wraps the grid) has no `'use client'`. Add it at the top of the file that renders `<DataGrid>`. |
+| `TypeError: createContext is not a function` (build: "Failed to collect page data") | 3.5.1 or earlier, imported from a Server Component. Render the grid from a `'use client'` file, or upgrade. |
+| `Functions cannot be passed directly to Client Components` … `{field: "name", valueFormatter: function}` | Columns with functions built in a Server Component. Define them in the client file. |
+| `Module not found: Can't resolve 'exceljs'` (or `jspdf`) | 3.5.1 or earlier without the optional export peers. Upgrade, or install them (section 1). From v3.6 webpack shows this as a warning only. |
+| Unstyled grid, every row rendered, dev warning `[OpenGridX] The grid stylesheet is not loaded` | The stylesheet is not imported. Add `import '@opencorestack/opengridx/styles'` to `app/layout.tsx` (or `pages/_app.tsx`). |
+| `Hydration failed because the server rendered HTML didn't match the client` | Usually rows or cell text that differ between server and client: `Math.random()`, `Date.now()`, `toLocaleString()` without a fixed locale and time zone in a `valueFormatter`. Fetch rows on the server and pass them as props, and format with an explicit locale (`toLocaleString('en-US', { timeZone: 'UTC' })`). Rows created in an effect or with `typeof window` branches render differently on the server; build them once on the server instead. |
+| The grid refetches in a loop with `dataSource` | The `dataSource` object is recreated on every render. Define it at module scope or with `useMemo`. |
+
+## See also
+
+- [Data Source](data-source.md)
+- [AI Toolkit](ai-toolkit.md)
+- [Export Guide](export-guide.md)

package/docs/features/pdf-export.md

@@ -10,6 +10,8 @@ Generate a styled PDF report from grid data using `exportToPdf()`.
 npm install jspdf jspdf-autotable
 ```
 
+They are optional: an app that never calls `exportToPdf` need not install them, and still builds in Vite, webpack 5 and Next.js (webpack prints a `Module not found` warning for the optional import, not an error). Without them `exportToPdf` rejects with the install hint below.
+
 > **Currency symbols such as `₹` print as `?` by default.** The built-in Helvetica font only covers Latin-1. Pass the [`font` option](#non-latin-text-and-unicode-fonts) with a Unicode `.ttf`:
 >
 > ```ts

package/docs/features/pinning.md

@@ -35,6 +35,8 @@ Pinned column headers are not draggable and are not drop targets for header drag
 
 ---
 
+> **Right-to-left:** `left` and `right` are the inline **start** and **end** sides. In a `dir="rtl"` grid `pinnedColumns.left` (and the pinned checkbox, expand and reorder columns) stick to the right edge, `pinnedColumns.right` to the left edge, and the shadows fall towards the scrolling columns. The column menu's *Pin to Left* / *Pin to Right* items pin by screen side, so in RTL *Pin to Left* adds the column to `pinnedColumns.right`. See [Right-to-Left](rtl.md#pinned-columns).
+
 ## ⬆️ Row Pinning
 
 Rows can be pinned to the top or bottom of the grid. Pinned rows remain visible while the user scrolls vertically through the grid body.

package/docs/features/rtl.md

@@ -0,0 +1,58 @@
+# Right-to-Left (RTL)
+
+Put the grid inside an element with `dir="rtl"`, or set `dir="rtl"` on `<html>` (`document.dir = 'rtl'`). There is no prop: the grid follows the CSS `direction` it inherits.
+
+```tsx
+<div dir="rtl" lang="ar">
+    <DataGrid rows={rows} columns={columns} height={480} />
+</div>
+```
+
+**Status (v3.6):** RTL grids work: column order, text, horizontal scrolling with column virtualization, keyboard, cell ranges, the fill handle, resizing, the toolbar panels, pinned columns (see [Pinned columns](#pinned-columns)), mirrored icons and switching `dir` at runtime. Remaining gaps are under [Known limitations](#known-limitations). Checked in Chromium, Firefox and WebKit; `lib/components/DataGrid/DataGrid.rtl.browser.test.tsx` covers what is listed as working or fixed.
+
+Demo: *Right-to-Left* (`/rtl`), with Arabic and Hebrew sample data and an RTL toggle.
+
+## What was checked
+
+| Area | Result | Notes |
+| :--- | :--- | :--- |
+| Column order | Works | The first column is on the right. |
+| Header and cell text alignment | **Fixed in v3.6** | Cells used `text-align: left`; `align: 'left'` / `'right'` now mean start / end (`text-align: start` / `end`), so default text starts on the right and number columns end on the left, matching the header. |
+| Horizontal scrolling and column virtualization | **Fixed in v3.6** | Browsers report `scrollLeft` from 0 down to a negative number in RTL. The grid counted it as 0, so after a horizontal scroll it rendered the first columns (now scrolled out of view) and the body was blank. It now measures the scroll offset from the start edge. |
+| Keyboard ArrowLeft / ArrowRight | **Fixed in v3.6** | ArrowLeft moves to the column on the left (the next column), ArrowRight to the right; Home / End go to the first / last column and scroll it into view. Shift+Arrow extends a cell range the same way. Alt+ArrowLeft / Alt+ArrowRight on a tree or group row expand / collapse in the screen direction (ArrowLeft expands), as do Alt+Arrow column resizing on a header (ArrowLeft widens) and Arrow keys on a focused resize handle. |
+| Column resize handle | **Fixed in v3.6** | It was on the column's right edge (its start edge in RTL) and dragging it right narrowed the column. It now sits on the left (end) edge and dragging left widens the column. |
+| Cell range selection | **Fixed in v3.6** | The range outline was drawn on the inner edges in RTL (the `--range-left` / `--range-right` modifiers mark the first and last column); it now outlines the range's outer edges. Dragging past the left edge of the grid auto-scrolls towards the later columns (it did not scroll at all before). |
+| Fill handle | **Fixed in v3.6** | The square was on the bottom-right corner of the range; it is now on the bottom-left, where the range ends. Dragging it fills towards the pointer as in LTR. |
+| Toolbar panels (columns, filters, summaries, pivot) | **Fixed in v3.6** | They opened leftwards from the button, off the screen when the toolbar is on the left. In RTL they now open rightwards, lined up with the button's left edge. |
+| Column menu, header filter operator menu | Works | Placed under their button. |
+| Header filter row | Works | Filter cells line up with their columns. Operator symbols are mirrored by the browser's bidi rules (`∋` shows as `∈`), as in any RTL text. |
+| Ask AI panel | Works | Opens over the grid. |
+| Left / right pinned columns, pinned system columns | **Fixed in v3.6** | Sticky offsets were physical `left` / `right`, so pinned columns scrolled away. They are now logical (`inset-inline-start` / `-end`) in the header, column group rows, header filter row, body, skeleton rows and aggregation footer. See [Pinned columns](#pinned-columns). |
+| Pinned shadows and section borders | **Fixed in v3.6** | Mirrored: they face the scrolling columns. |
+| Range drag with pinned columns | **Fixed in v3.6** | Auto-scroll starts at the inner edge of the pinned section on each side. |
+| Pagination arrows, tree / group chevrons | **Fixed in v3.6** | Mirrored with `scaleX(-1)` under `:dir(rtl)`; tree indentation is on the start side. Sort arrows, search, close and other non-directional icons are not mirrored. |
+| Switching `dir` on a mounted grid | **Fixed in v3.6** | Firefox resets `scrollLeft` without a scroll event, which left the body blank; the grid re-reads the position when any `dir` attribute changes. Changing `direction` through a class or stylesheet is not observed: scroll the grid or remount it. |
+| Column reordering by drag | Works | Drops use the target header, not pointer offsets; the drop marker is on the target's start edge. |
+
+## Pinned columns
+
+`pinnedColumns.left` and `pinnedColumns.right` are **logical**: the inline start and end. In a right-to-left grid left-pinned columns, and the checkbox, expand and reorder columns pinned with `pinCheckboxColumn` / `pinExpandColumn`, stick to the **right** edge; right-pinned columns stick to the left edge. This is what MUI X and AG Grid do (AG Grid's `pinned: 'left'` and MUI's `pinnedColumns.left` move to the right in RTL), and it keeps one configuration for both directions: the identifier column a user reads first stays pinned where reading starts, and the system columns stay next to it.
+
+The column menu is labelled by screen side: in RTL *Pin to Left* adds the column to `pinnedColumns.right`. `onPinnedColumnsChange` and `apiRef` report the logical lists. Shadow tokens are swapped in RTL (`--ogx-grid-pinned-right-shadow` is used for the start section, which casts its shadow leftwards).
+
+## Known limitations
+
+- **Menu and panel labels are hard-coded English** ("Pin to Left", "Sort Ascending"); there is no `localeText` key for the column menu yet.
+- **Header filter operator symbols** are mirrored by the browser's bidi rules (`∋` shows as `∈`), as in any RTL text.
+- **`direction` set through CSS** (a class or stylesheet, not the `dir` attribute) and changed at runtime is not detected; scroll the grid or remount it with a `key`.
+- **Headless Chromium tests:** Playwright launches Chromium with `--hide-scrollbars`. With classic scrollbars (Linux) `scrollbar-gutter: stable` still reserves the gutter, and in RTL Chromium then cannot scroll the last gutter-width of the start into view (`scrollLeft` stops at minus the gutter). A plain scroller without the grid does the same and real browsers with visible scrollbars do not. Tests must compare with the browser's scroll origin, as `DataGrid.rtl.browser.test.tsx` does. To reproduce on macOS: `defaults write chrome-headless-shell AppleShowScrollBars Always` (undo with `defaults delete chrome-headless-shell`).
+
+## Left-to-right grids
+
+Every fix uses CSS logical properties (`text-align: start`, `inset-inline-end`, `margin-inline-start`) or applies only when the computed `direction` is `rtl`, so LTR grids are unchanged. A browser test measured 415 element positions (headers, cells, resize and fill handles, header filter controls, toolbar buttons and panels, before and after a horizontal scroll, with pinned columns) in all three engines before and after the change and found no difference; RTL part 2 repeated this with 2,211 boxes, shadows, borders and pseudo-element offsets (pinned and system columns, column groups, header filters, aggregation footer, before and after a scroll and with a range); `DataGrid.rtl.browser.test.tsx` keeps an LTR layout check.
+
+## See also
+
+- [Keyboard & Accessibility](keyboard-navigation.md)
+- [Pinning](pinning.md)
+- [Cell Range Selection](cell-selection.md)

package/docs/features/virtualization.md

@@ -29,11 +29,11 @@ The grid calculates which rows are visible based on:
 />
 ```
 
-**Performance characteristics** (when the grid has a bounded height — see below):
-- ✅ Renders ~15-25 rows regardless of total dataset size
-- ✅ Constant memory usage
-- ✅ Smooth 60fps scrolling
-- ⚠️ Not millions of rows. Browsers cap an element's height (33,554,432px in Chromium, about 17.9M px in Firefox) and the grid does no scroll scaling: it lays every row out at its real height, so rows past the cap cannot be scrolled to. The limit is roughly `33,554,432 / rowHeight` rows in Chromium (about 645,000 at the default 52px), and about half that in Firefox (about 340,000). Beyond that, use pagination, or server-side paging / infinite scroll. In development the grid warns when the content passes 17.8M px.
+**Performance characteristics** (when the grid has a bounded height — see below), measured by the [benchmark](../performance.md#benchmarks):
+- ✅ About 19 row elements at rest in an 800 px page at 52 px rows, at most about 86 while scrolling fast, whatever the row count (10k to 1M)
+- ✅ Scrolling keeps up with a 60 Hz display at 1M rows in Chromium (no missed frames) and Firefox; WebKit misses a frame or two on each long jump of the scroll position
+- ✅ The grid itself adds about 10 MB of JS heap at 100k rows and 79 MB at 1M (Chromium), on top of your row data
+- ⚠️ Not millions of rows at the default height. Browsers cap an element's height and the grid does no scroll scaling: it lays every row out at its real height. Chromium and WebKit stop at 33,554,428 px, so rows past about `33,554,428 / rowHeight` cannot be scrolled to (645,277 at the default 52 px; 1M rows fit at 32 px). Firefox's limit is about 17.9M px (about 344,000 rows at 52 px); since 3.5.1 the grid caps its content to the limit it measures, so Firefox scrolls normally up to there (on 3.5.0 and earlier, content past the limit collapsed and the grid did not scroll at all). Beyond that, use pagination, or server-side paging / infinite scroll. In development the grid warns when rows are cut off and names how many can be scrolled to. Measured reach per browser: [Performance → Reach](../performance.md#reach-the-browser-height-ceiling).
 
 ### Column Virtualization