@opencorestack/opengridx 3.0.0 → 3.0.1

package/docs/API_REFERENCE.md

@@ -27,7 +27,7 @@ The main component for displaying and interacting with data.
 | `onPaginationModelChange` | `(model: GridPaginationModel) => void` | — | Fired when page or page size changes. |
 | `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Available page size options. The uncontrolled default page size is 100 when offered, else the first option. |
 | `rowCount` | `number` | — | Server total for `paginationMode="server"` when you fetch pages yourself (read on every render). With a `dataSource`, the response's `rowCount` is used and this is only the fallback before the first response. |
-| `height` | `number \| string` | `undefined` | Total height of the grid container. |
+| `height` | `number \| string` | `undefined` | Total height of the grid. Without it the grid fills its container (`height: 100%`, or `flex: 1 1 auto; min-height: 0` as a flex item; v3.0.1+), and grows to fit every row in an auto-height container. |
 | `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Visual row density: compact = the theme's `grid.rowHeightCompact` or 32 px, standard = `rowHeight`, comfortable = the theme's `grid.rowHeightComfortable` or 72 px. |
 | `initialState` | `GridInitialState` | `undefined` | Starting state (sort, filter, pagination, columns, density), read on mount. Seeds the grid's uncontrolled state; see [State Persistence](features/state-persistence.md). |
 | `slots` | `GridSlots` | — | Custom component overrides: `toolbar`, `pagination`, `noRowsOverlay`, `loadingOverlay`, `footer`. See [`GridSlots`](#gridslots-and-gridslotprops) and the [Slots API](customization/slots-api.md). |
@@ -156,7 +156,7 @@ The main component for displaying and interacting with data.
 
 | Prop | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
-| `apiRef` | `React.MutableRefObject<GridApi>` | — | Reactive ref to the imperative API. Create with `useGridApiRef()`. |
+| `apiRef` | `React.MutableRefObject<GridApi<R>> \| React.MutableRefObject<GridApi>` | — | Reactive ref to the imperative API. Create with `useGridApiRef()`, or `useGridApiRef<Row>()` for typed row getters (v3.0.1+). |
 
 #### List View
 
@@ -197,7 +197,7 @@ const columns: GridColDef<Employee>[] = [
 - A `GridColDef<Row>` for a type-alias row (or an interface that extends `GridRowModel`) can be used where a `GridColDef` is expected: the row callbacks are declared as methods, so they are checked bivariantly.
 - `params.value` stays `unknown`; read typed values from `params.row`, or render `params.formattedValue`.
 - The export functions, `usePivot` and `useAggregation` accept the same typed or untyped columns, and their options' `getRowId` takes your row type.
-- `apiRef` methods (`getRow`, `getAllRows` …) return `GridRowModel`: the API object is not generic.
+- `apiRef` row getters (`getRow`, `getAllRows`, `getVisibleRows`, `getAllFilteredRows`) return your row type when the ref is created with `useGridApiRef<Row>()` (v3.0.1+); a plain `useGridApiRef()` returns `GridRowModel`.
 - For the component's props type, use `DataGridProps<R>`. `React.ComponentProps<typeof DataGrid>` resolves to the untyped-columns overload.
 
 ### `GridSlots` and `GridSlotProps`
@@ -279,9 +279,9 @@ Access these methods via the `apiRef` prop.
 
 | Method | Return | Description |
 | :--- | :--- | :--- |
-| `getRow(id)` | `GridRowModel \| null` | Get row data by ID (your row object, unchanged). |
-| `getAllRows()` | `GridRowModel[]` | Get all loaded rows. |
-| `getVisibleRows()` | `GridRowModel[]` | Get the rows on screen after filtering/sorting: pinned-top rows, the current page (or all rows without pagination), pinned-bottom rows. Under row grouping and tree data this is the visible hierarchy, group rows included. |
+| `getRow(id)` | `R \| null` | Get row data by ID (your row object, unchanged). `R` is the type passed to `useGridApiRef<R>()`, `GridRowModel` by default. |
+| `getAllRows()` | `R[]` | Get all loaded rows. |
+| `getVisibleRows()` | `R[]` | Get the rows on screen after filtering/sorting: pinned-top rows, the current page (or all rows without pagination), pinned-bottom rows. Under row grouping and tree data this is the visible hierarchy, group rows included. |
 | `getColumn(field)` | `GridColDef \| null` | Get column definition by field. |
 | `getVisibleColumns()` | `GridColDef[]` | Get the columns on screen, in render order (hidden columns excluded): left-pinned, unpinned, right-pinned, as the header shows them (v3.0+; before, pinned columns kept their unpinned position). |
 | `selectRow(id, isSelected = true)` | `void` | Set selection for a single row. Fires `onRowSelectionModelChange`, unless nothing changes (selecting a selected row, deselecting an unselected one; v3.0+). Ids of rows the grid made (group headers, subtotals, auto-created tree parents, the pivot Grand Total) are ignored, as they are for the checkbox, click and keyboard (v3.0+). |
@@ -297,7 +297,7 @@ Access these methods via the `apiRef` prop.
 | `getAllColumns()` | `GridColDef[]` | Get all defined columns. |
 | `getAggregationResult()` | `Record<string, unknown> \| null` | Get current aggregation results (`null` without an `aggregationModel`, and in pivot mode). Live in a parent's `useLayoutEffect` on mount and current after every update (v3.0+; before, it was installed in a passive effect). The same holds for `getAggregationModel()` and `getGroupedExportRows()`. |
 | `getAggregationModel()` | `GridAggregationModel \| null` | Get the active aggregation configuration. |
-| `getAllFilteredRows()` | `GridRowModel[]` | Get every row that passes the filter, sorted, regardless of pagination, including pinned rows. Under row grouping and tree data it returns the data rows (no group rows) in hierarchy order with every group expanded, ordered like the screen (also when sorting by the hierarchy column; v3.0+). With tree data and a filter, ancestors shown only to give a match its context are left out: the result is the set select-all and the aggregation footer act on (v3.0+). Use for full-dataset exports. |
+| `getAllFilteredRows()` | `R[]` | Get every row that passes the filter, sorted, regardless of pagination, including pinned rows. Under row grouping and tree data it returns the data rows (no group rows) in hierarchy order with every group expanded, ordered like the screen (also when sorting by the hierarchy column; v3.0+). With tree data and a filter, ancestors shown only to give a match its context are left out: the result is the set select-all and the aggregation footer act on (v3.0+). Use for full-dataset exports. |
 | `getGroupedExportRows()` | `GridGroupedExportRow[] \| null` | Get a flat ordered list reflecting the active row-grouping tree (group-header, leaf, subtotal, grand-total), sorted and filtered like the screen. Collapsed groups are included with their rows, and subtotals are computed over each group's exported rows. Group-header and subtotal entries carry `groupLabel`, the label the grid shows (v3.0+). Returns `null` when row grouping is not active. |
 | `copySelectedRows()` | `Promise<void>` | Copy every selected row that passes the filter (other pages, collapsed groups and pinned rows included) as TSV, with the visible columns in screen order. Resolves without writing when no selected row is found; rejects when the clipboard write fails. |
 
@@ -476,6 +476,10 @@ const apiRef = useGridApiRef();
 // Then call methods imperiously
 apiRef.current.scrollToIndexes({ rowIndex: 0 });
 apiRef.current.setFilterModel({ items: [] });
+
+// Typed row getters (v3.0.1+)
+const invoiceApi = useGridApiRef<Invoice>();
+const invoice = invoiceApi.current.getRow(42); // Invoice | null
 ```
 
 See the [Imperative API (`GridApi`)](#%EF%B8%8F-imperative-api-gridapi) table above for the full method list.

package/docs/components/column-resize.md

@@ -3,7 +3,7 @@
 OpenGridX supports dynamic column resizing, allowing users to adjust the width of any column on the fly for better visibility of data. This is facilitated by the `ColumnResizeHandle`, an internal component (not exported) that `<Header />` renders invisibly on the edge of each resizable column header.
 
 ## 📑 Overview
-- **Where the handle is**: on the right edge of each resizable column header. Right-pinned columns are anchored to the right edge of the grid and grow leftwards, so their handle is on their **left** edge, and the edge you grab follows the pointer.
+- **Where the handle is**: on the right edge of each resizable column header. Right-pinned columns are anchored to the right edge of the grid and grow leftwards, so their handle is on their **left** edge, and the edge you grab follows the pointer. The handle is an 8px strip just inside the column, against that edge, and all of it can be grabbed (v3.0.1+; before, the neighbouring header cell clipped half of it).
 - **Mouse, touch and pen**: the handle uses pointer events with pointer capture, so a resize keeps following the pointer outside the header and works on tablets and phones.
 - **Keyboard**: with a column header focused, **Alt+ArrowRight** / **Alt+ArrowLeft** widen / narrow the column by 10px (hold **Shift** for 50px). The handle is a `role="separator"` that reports the width in `aria-valuenow` (and `aria-valuemin` / `aria-valuemax`).
 - **Constraints**: `minWidth` and `maxWidth` from your `GridColDef` apply. Without `minWidth` a column can be narrowed to 50px; a column that is already narrower (a 30px icon column) is never snapped up to 50px. Without `maxWidth` there is no upper limit.

package/docs/components/datagrid.md

@@ -25,7 +25,7 @@ function MyGrid() {
 | `rows` | `R[]` | — | **Required.** The dataset to display (`[]` when a `dataSource` supplies the rows). |
 | `columns` | `GridColDef<R>[]` | — | **Required.** Column definitions. |
 | `getRowId` | `(row: R) => GridRowId` | `row.id` | Unique ID for each row. Only keys the grid's store; row objects are never copied or given an `id` (v3.0+). Duplicate ids keep the first row and log a development warning. |
-| `height` | `number \| string` | `undefined` | Height of the grid container. |
+| `height` | `number \| string` | `undefined` | Height of the grid. Without it the grid fills its container (v3.0.1+); the container needs a bounded height for virtualization. See [Virtualization](../features/virtualization.md#the-grid-needs-a-bounded-height). |
 | `loading` | `boolean` | `false` | Displays a loading skeleton/shimmer. |
 | `density` | `'compact' \| 'standard' \| 'comfortable'` | `'standard'` | Row height preset: compact = 32 px, standard = `rowHeight`, comfortable = 72 px. Inside a `DataGridThemeProvider`, the theme's `grid.rowHeightCompact` / `rowHeightStandard` / `rowHeightComfortable` replace these defaults (an explicit `rowHeight` still wins for standard). |
 | `checkboxSelection` | `boolean` | `false` | Enable row checkboxes. |

package/docs/customization/theming.md

@@ -46,7 +46,7 @@ How the provider builds the variables (v3.0+):
 - **Toolbar tokens follow the grid surface.** Unless you set `toolbar.*`, the toolbar uses the header background, header text and grid border colours.
 - **Row and header heights reach the layout.** `grid.rowHeightStandard` / `grid.headerHeight` (and `rowHeightCompact` / `rowHeightComfortable` with `density`) are read by the grid itself, which virtualizes from them. They must be pixel values (`'36px'` or `'36'`); other units are ignored. The `rowHeight` / `headerHeight` props win over the theme.
 
-> **Sizing:** the wrapper `div` (`.ogx-theme-provider`) is a normal auto-height block. If the grid uses `height="100%"`, pass `style={{ height: '100%' }}` (or a `className` that sets a height) to the provider too. Otherwise the wrapper grows to fit every row and row virtualization is effectively off. See [Virtualization → The grid needs a bounded height](../features/virtualization.md#the-grid-needs-a-bounded-height).
+> **Sizing:** the wrapper `div` (`.ogx-theme-provider`) is a normal auto-height block. A grid without a `height` prop (or with `height="100%"`) fills its parent, which here is the wrapper, so inside a bounded container pass `style={{ height: '100%' }}` (or a `className` that sets a height) to the provider too. Otherwise the wrapper grows to fit every row and row virtualization is effectively off. See [Virtualization → The grid needs a bounded height](../features/virtualization.md#the-grid-needs-a-bounded-height).
 
 ---
 

package/docs/features/list-view.md

@@ -78,7 +78,7 @@ List view pages exactly like the grid view: with `pagination`, one page of the (
 
 `onRowsScrollEnd` fires when the list is scrolled to within 100px of its bottom, so the [infinite scroll](./infinite-scroll.md) pattern works in list view too. As in the grid view, it fires once per arrival: it fires again only after the list leaves that zone or the row count changes (for example, when the next page has loaded).
 
-The list view is **not virtualized**: it renders every row it shows (one page with `pagination`, otherwise all rows). Use pagination for large datasets. `slots.footer` is rendered below the list (in place of its pagination controls); the aggregation footer row is not shown in list view.
+The list view is **not virtualized**: it renders every row it shows (one page with `pagination`, otherwise all rows). Use pagination for large datasets: rendering tens of thousands of cards freezes the page, and in development the grid warns when the list view renders more than 2,000 items (v3.0.1+). `slots.footer` is rendered below the list (in place of its pagination controls); the aggregation footer row is not shown in list view.
 
 ## ♿ Accessibility
 

package/docs/features/pdf-export.md

@@ -10,6 +10,14 @@ Generate a styled PDF report from grid data using `exportToPdf()`.
 npm install jspdf jspdf-autotable
 ```
 
+> **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
+> await exportToPdf(rows, columns, { fileName: 'invoices', font: { name: 'NotoSans', data: notoSansBase64 } });
+> ```
+
+> **Large datasets:** PDF generation runs on the main thread, and time and file size grow with every row: 50,000 grouped rows took 10–16 s (the page is unresponsive meanwhile) and produced a file of about 120 MB. For more than a few thousand rows, export CSV (`exportToCsv`) or `.xlsx` (`exportToExcelAdvanced`) instead, or export a filtered subset.
+
 ## Basic Usage
 
 ```tsx
@@ -134,6 +142,14 @@ System columns (`__check__`, `__actions__`) and spacer columns (`isSpacer: true`
 
 ## Troubleshooting
 
+**`₹` or other characters print as `?`**
+
+Pass the `font` option with a Unicode TrueType font. See [Non-Latin text](#non-latin-text-and-unicode-fonts).
+
+**Export is slow or the file is huge**
+
+PDF is not suited to tens of thousands of rows (see Installation above). Use CSV or `.xlsx` for large exports.
+
 **Error: "exportToPdf requires 'jspdf' and 'jspdf-autotable'"**
 
 Run: `npm install jspdf jspdf-autotable`

package/docs/features/pinning.md

@@ -20,6 +20,7 @@ Columns can be pinned to the left or right edges of the grid. Pinned columns rem
 
 ### Order and widths
 - Pinned columns render in the order of `pinnedColumns.left` / `pinnedColumns.right`, not in column order. Pinning from the column menu appends the column to the end of its side, so it lands next to the scrolling columns.
+- When the columns are narrower than the grid, right-pinned columns sit at the grid's right edge, and the free space is between the scrolling columns and them (v3.0.1+).
 - A pinned column is sized exactly as it would be unpinned: numbers, percentages, `flex` and `'auto'` all apply, clamped to `minWidth` / `maxWidth`. The sticky offsets use those widths, so pinned columns never overlap.
 
 ### Column Configuration

package/docs/features/virtualization.md

@@ -53,37 +53,39 @@ Without the stylesheet the viewport does not scroll, so the grid renders every r
 
 Virtualization renders as many rows as fit in the grid's viewport. If the grid's container has no bounded height, the viewport grows to fit **every** row, so every row is rendered. Nothing errors; the grid just stops virtualizing.
 
-The most common cause is a flex child that is missing `min-height: 0`. A flex item defaults to `min-height: auto`, which lets it grow to its content:
+**Without a `height` prop the grid fills its container** (since 3.0.1): its root gets `height: 100%` and, as a flex item, `flex: 1 1 auto; min-height: 0`. So it fills a sized block parent, or the free space of a flex column, and virtualizes. In a container with no definite height, `100%` resolves to `auto` and the grid grows to fit its rows, exactly as before. Passing `height` (a number or any CSS length) sets the height instead; `autoHeight` always grows to fit every row.
+
+The most common cause of an unbounded container is a flex child that is missing `min-height: 0`. A flex item defaults to `min-height: auto`, which lets it grow to its content:
 
 ```tsx
-// ❌ Grows to fit all rows — virtualization is effectively off
+// ❌ The wrapper grows to fit all rows — virtualization is effectively off
 <div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
   <div style={{ flex: 1 }}>
-    <DataGrid rows={rows} columns={columns} height="100%" />
+    <DataGrid rows={rows} columns={columns} />
   </div>
 </div>
 
 // ✅ Bounded — only visible rows render
 <div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
   <div style={{ flex: 1, minHeight: 0 }}>
-    <DataGrid rows={rows} columns={columns} height="100%" />
+    <DataGrid rows={rows} columns={columns} />
   </div>
 </div>
 ```
 
-`height="100%"` only helps if every ancestor up to a fixed-height element also has a definite height.
+Every flex (or grid) item between the grid and the element with a fixed height (`100vh`, `600px`, …) needs `min-height: 0`. The grid itself can also be the flex item: `<div style={{ display: 'flex', flexDirection: 'column', height: 600 }}><Toolbar /><DataGrid … /></div>` gives the grid the space left after the toolbar.
 
-**`DataGridThemeProvider` counts as an ancestor.** It renders a plain `<div class="ogx-theme-provider">` around the grid, and that wrapper is auto-height like any other `div`. When you use `height="100%"` inside it, give the wrapper a height as well:
+**`DataGridThemeProvider` counts as an ancestor.** It renders a plain `<div class="ogx-theme-provider">` around the grid, and that wrapper is auto-height like any other `div`. Inside a bounded container, give the wrapper a height as well:
 
 ```tsx
 <div style={{ flex: 1, minHeight: 0 }}>
   <DataGridThemeProvider theme={theme} style={{ height: '100%' }}>
-    <DataGrid rows={rows} columns={columns} height="100%" />
+    <DataGrid rows={rows} columns={columns} />
   </DataGridThemeProvider>
 </div>
 ```
 
-In development builds the grid logs a `console.warn` when it detects that it is rendering every row of a dataset larger than 200 rows because its viewport is unbounded.
+In development builds the grid logs a `console.warn` when it is rendering every row of a dataset larger than 200 rows and its viewport is at least as tall as those rows, that is, when its container really is unbounded. The warning names the fixes above.
 
 Pagination can hide this problem, because a paginated grid only has one page of rows to render. Row grouping switches pagination off (see below), so an unbounded container that looked fine with pagination can freeze the tab once grouping is enabled.
 
@@ -205,7 +207,7 @@ When using detail panels, row heights become variable. The grid automatically:
 
 ## Virtualization with Grouping/Tree Data
 
-Grouped and tree rows go through the same virtualizer as flat rows. Expanding a group of any size adds its rows to the virtual row list, not to the DOM: in a bounded container, expanding a 25,000-row group renders ~20 DOM rows (verified in Chromium by `DataGrid.virtualization.browser.test.tsx`).
+Grouped and tree rows go through the same virtualizer as flat rows. Expanding a group of any size adds its rows to the virtual row list, not to the DOM: in a bounded container, expanding a 25,000-row group renders ~20 DOM rows (verified in Chromium, Firefox and WebKit by `DataGrid.virtualization.browser.test.tsx`).
 
 ```tsx
 // Tree data with virtualization

package/docs/migration/v2-to-v3.md

@@ -53,6 +53,8 @@ import '@opencorestack/opengridx/styles';
 
 Without it the grid is unstyled and its viewport has no bounded height, so **every row renders** (virtualization is effectively off). If your v2 app looked fine, you already have this import. In development, 3.0.0 logs a warning when the stylesheet is not loaded.
 
+> **3.0.1 note — height.** Without a `height` prop the grid now fills its container (root class `ogx--fill`: `height: 100%`, and as a flex item `flex: 1 1 auto; min-height: 0`). In 3.0.0 the root was auto-height, so inside a bounded flex layout it grew to fit every row. The container still needs a bounded height (a definite height, or `min-height: 0` on every flex / grid ancestor up to the sized one); in an auto-height container the grid still grows to fit. An explicit `height`, `style.height` or `autoHeight` is never stretched. The unbounded-container dev warning is only logged when the viewport really is as tall as its rows.
+
 ### Know the size limit
 
 A single scrolling grid tops out at about 645,000 rows at the default 52px row height in Chromium (the browser's maximum element height). Above that, use pagination or a `dataSource`. The grid logs a dev warning when content is taller than browsers can scroll.
@@ -427,6 +429,8 @@ Pruning applies when the grid owns the rows: no `dataSource`, client pagination
 
 **Fix it:** call the setter and let your change callback update controlled state; remove duplicate `setState` calls.
 
+> **3.0.1 note — typed row getters.** `useGridApiRef<MyRow>()` returns a `GridApi<MyRow>` whose `getRow`, `getAllRows`, `getVisibleRows` and `getAllFilteredRows` return `MyRow`, so the casts v2 needed can go. `useGridApiRef()` without a type argument and `DataGridProps.apiRef` with an untyped ref still compile.
+
 ---
 
 ## 11. Editing
@@ -714,6 +718,8 @@ Keep `getRows` stable (`useCallback` or module scope) if you do not want a refet
 | Sticky header and pinned rows | `.ogx__pinned-rows--top` / `--bottom` were sticky | wrapped in `div.ogx__sticky-top` / `div.ogx__sticky-bottom` (see [§24](#24-dom-and-css-class-changes)) |
 | z-index of sticky body system cells | 4 / 5 / 11 | 12; header drag / expand cells have no inline z-index |
 | Returning from list view | scroll reset | scroll position restored |
+| Right-pinned columns when columns are narrower than the grid | followed the last unpinned column | at the grid's right edge (3.0.1; free space sits before the right-pinned section) |
+| No `height` prop | auto height (3.0.0) | fills the container, `ogx--fill` (3.0.1; see [Before you start](#import-the-stylesheet)) |
 
 **Who is affected:** apps with `onRowsScrollEnd` loaders that relied on repeated firing, apps with custom z-index or sticky CSS, and apps whose pinned columns were pinned out of column order.
 
@@ -751,6 +757,7 @@ export function Pinned({ rows, columns }: { rows: GridRowModel[]; columns: GridC
 | Click on the resize handle without moving | resized / sorted | nothing |
 | Resize events | mouse events on `document` | pointer events with capture on the handle (touch and pen work) |
 | Right-pinned column resize | right edge | left edge (`ogx-column-resize-handle--start`); drag left to widen |
+| Resize handle position | straddled the cell border (`right: -4px`); half was clipped, 3–4px grabbable | inside its own header cell against the resizing edge (`right: 0` / `left: 0`), all 8px grabbable (3.0.1) |
 | `dragstart` data types | `text/plain` | `application/x-ogx-row` / `application/x-ogx-column` plus `text/plain` |
 | Toolbar, pivot and standalone panels | portal mounted in render | mounted one layout effect later (invisible to users; matters for tests) |
 
@@ -967,6 +974,8 @@ CSS: `.ogx-col-group-row` no longer has `overflow: hidden`; new `ogx-col-group-c
 | Tree data and grouping | no expand control | expand chevron and depth indent (`.ogx-list-view__expand`) |
 | Summary and paging with a `dataSource` | loaded rows | server total |
 | `onRowsScrollEnd` | never fired | fires once per arrival at the bottom, like the grid view |
+| Large lists | not virtualized | still not virtualized; 3.0.1 warns in development above 2,000 rendered items — use pagination |
+| Tab in Firefox | — | lands on the focused row, not the rows container (3.0.1, `tabIndex={-1}` on `.ogx-list-view__rows`) |
 
 ---
 
@@ -1002,6 +1011,7 @@ CSS: `.ogx-col-group-row` no longer has `overflow: hidden`; new `ogx-col-group-c
 | `ogx__row--group-footer` | subtotal rows in `'footer'` position |
 | `ogx__cell-image` | default `<img>` for `type: 'image'` |
 | `ogx-column-resize-handle--start` | resize handle on the left edge (right-pinned columns) |
+| `ogx--fill` (3.0.1) | grid root when no `height`, `style.height` or `autoHeight` is set |
 | `ogx-col-group-cell--pinned`, `ogx-col-group-cell--pinned-left`, `ogx-col-group-cell--pinned-right` | pinned column-group cells |
 | `ogx-filter__hidden-note`, `ogx-filter__value-multiselect` | filter panel |
 | `ogx-list-view__expand`, `ogx-list-view__loading` | list view |
@@ -1019,7 +1029,8 @@ CSS: `.ogx-col-group-row` no longer has `overflow: hidden`; new `ogx-col-group-c
 | `.ogx-global-search--expanded` | shows the input border while expanded and unfocused; the primary border and focus shadow moved to `:focus-within` |
 | `.ogx__cell--focused`, `.ogx__header-cell--focused`, `.ogx__header-cell--focus-visible` | outline colour reads `--ogx-grid-cell-focus-border` (falls back to `--ogx-color-primary`) |
 | `.ogx__header-cell--drag-over` | background `--ogx-color-primary-light` (was the undefined `--ogx-color-blue-50`) |
-| `.ogx-column-resize-handle` | `touch-action: none`; a `:focus-visible` line colour |
+| `.ogx-column-resize-handle` | `touch-action: none`; a `:focus-visible` line colour; 3.0.1: `right: 0` (was `-4px`), `justify-content: flex-end`; `--start` is `left: 0`, `flex-start` |
+| `.ogx__header-cell--pinned-right-first`, `.ogx__cell--pinned-right-first`, `.ogx__aggregation-cell--pinned-right-first`, first right-pinned `.ogx-col-group-cell` (3.0.1) | `margin-left: auto`; `.ogx__content` width is `max(100%, <total>px)` when right-pinned columns exist |
 | `.ogx-list-view__row` | `:focus-visible` outline (rows are focusable) |
 | `.ogx-toolbar` and its buttons / chips, `.ogx-global-search`, scrollbars, filter-panel delete button | read the `--ogx-toolbar-*`, `--ogx-scrollbar-*` and `--ogx-overlay-item-danger-*` variables the theme provider sets (the filter-panel delete button used `--ogx-toolbar-btn-danger-*`); fallbacks match the v2 colours except the danger-button hover |
 

package/docs/roadmap.md

@@ -90,7 +90,7 @@ This document tracks the current status of features in `OpenGridX` and outlines
 - `slots.footer`, `slots.noRowsOverlay` and `slots.loadingOverlay` are rendered (they were typed but ignored).
 - New `onRowDoubleClick`; `ColumnVisibilityPanel` exported; `exportToExcelAdvanced` accepts `groupedRows`.
 - Dev-mode warnings for an unbounded grid container and for `pagination` with row grouping.
-- Real-browser test project (Vitest browser mode + Playwright/Chromium), `npm run test:browser`; the npm publish workflow now runs unit and browser tests before publishing.
+- Real-browser test project (Vitest browser mode + Playwright; Chromium, Firefox and WebKit), `npm run test:browser`; the npm publish workflow now runs unit and browser tests before publishing.
 - Already shipped, previously listed as upcoming: npm publishing (since 0.1.0), native PDF export (v1.2.1), GitHub Pages deployment.
 
 ### Library Hardening *(completed 2026-09-02)*

package/lib/components/Cell/Cell.css

@@ -58,6 +58,10 @@
 .ogx__cell--pinned-right {
   border-left: 1px solid var(--ogx-grid-border-color);
 }
+/* When the columns are narrower than the grid, the free space goes before the right-pinned section. */
+.ogx__cell--pinned-right-first {
+  margin-left: auto;
+}
 .ogx:not(.ogx--row-spanning) .ogx__row:hover .ogx__cell--pinned-left,
 .ogx:not(.ogx--row-spanning) .ogx__row:hover .ogx__cell--pinned-right {
   background-color: var(--ogx-grid-row-hover-background);

package/lib/components/ColumnResizeHandle/ColumnResizeHandle.css

@@ -1,14 +1,15 @@
 .ogx-column-resize-handle {
   position: absolute;
   top: 0;
-  right: -4px;
+  /* Inside the header cell: the cell clips overflow, so a handle straddling the border lost its outer half. */
+  right: 0;
   width: 8px;
   height: 100%;
   cursor: col-resize;
   z-index: 10;
   display: flex;
   align-items: center;
-  justify-content: center;
+  justify-content: flex-end;
   user-select: none;
   /* Touch and pen drags resize the column instead of scrolling the grid. */
   touch-action: none;
@@ -16,7 +17,8 @@
 /* Right-pinned columns grow leftwards: their handle sits on the left edge. */
 .ogx-column-resize-handle--start {
   right: auto;
-  left: -4px;
+  left: 0;
+  justify-content: flex-start;
 }
 .ogx-column-resize-handle:focus-visible .ogx-column-resize-handle__line {
   background: var(--ogx-color-primary);

package/lib/components/DataGrid/DataGrid.css

@@ -88,6 +88,13 @@
   justify-content: center;
   z-index: var(--ogx-z-index-modal);
 }
+/* No height prop: fill the container, as a block child of a sized box (height: 100%) or as a
+   flex item (flex: 1 with min-height: 0). In an auto-height parent 100% resolves to auto. */
+.ogx--fill {
+  height: 100%;
+  flex: 1 1 auto;
+  min-height: 0;
+}
 .ogx--auto-height {
   height: auto;
 }
@@ -274,6 +281,7 @@
   box-shadow: inset 10px 0 8px -8px rgba(0, 0, 0, 0.1);
 }
 .ogx__aggregation-cell--pinned-right-first {
+  margin-left: auto;
   overflow: visible;
 }
 .ogx__aggregation-cell--pinned-right-first::before {

package/lib/components/DataGrid/DataGrid.tsx

@@ -595,6 +595,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         pinnedRowsIgnored: isHierarchyEnabled && Boolean(pinnedRows?.top?.length || pinnedRows?.bottom?.length),
         scrollHeight: virtualization.totalHeight,
         listViewWithoutColumn: listViewRequested && !listViewColumn,
+        listViewRowCount: listView && listViewColumn ? allRenderableRows.length : 0,
     });
 
     const { allSelected, someSelected } = rowSelection;
@@ -660,7 +661,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
     return (
         <div
             ref={containerRef}
-            className={['ogx', className, autoHeight && 'ogx--auto-height', hasRowSpanning && 'ogx--row-spanning', listView && 'ogx--list-view'].filter(Boolean).join(' ')}
+            className={['ogx', className, autoHeight && 'ogx--auto-height', !autoHeight && height === undefined && style?.height === undefined && 'ogx--fill', hasRowSpanning && 'ogx--row-spanning', listView && 'ogx--list-view'].filter(Boolean).join(' ')}
             style={{
                 ...style,
                 height: height ?? style?.height,
@@ -755,7 +756,10 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
                     <div
                         className="ogx__content"
                         style={{
-                            width: virtualization.totalWidth
+                            // With right-pinned columns the content spans at least the viewport, so they sit at its right edge.
+                            width: effectivePinnedColumns?.right?.length
+                                ? `max(100%, ${virtualization.totalWidth}px)`
+                                : virtualization.totalWidth
                         }}
                         role="presentation"
                     >

package/lib/components/DataGrid/GridListView.tsx

@@ -202,7 +202,8 @@ export function GridListView<R extends GridRowModel>({
                 </span>
             </div>
 
-            <div className="ogx-list-view__rows" onScroll={handleScroll} onKeyDown={handleKeyDown} ref={rowsRef}>
+            {/* tabIndex -1: Firefox otherwise makes this scroll container a Tab stop of its own; the rows carry the roving tab stop. */}
+            <div className="ogx-list-view__rows" tabIndex={-1} onScroll={handleScroll} onKeyDown={handleKeyDown} ref={rowsRef}>
                 {allRenderableRows.length === 0 && loading ? (
                     // The grid's live region announces loading; the list shows no "No Data" meanwhile.
                     <div className="ogx-list-view__loading">

package/lib/components/Header/Header.css

@@ -148,6 +148,9 @@
 .ogx__header-cell--pinned-left {
   box-shadow: var(--ogx-grid-pinned-left-shadow, 4px 0 12px -4px rgba(0, 0, 0, 0.05)); 
 }
+.ogx__header-cell--pinned-right-first {
+  margin-left: auto;
+}
 .ogx__header-cell--pinned-right {
   box-shadow: var(--ogx-grid-pinned-right-shadow, -4px 0 12px -4px rgba(0, 0, 0, 0.05));
 }

package/lib/components/Header/Header.tsx

@@ -263,7 +263,7 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
                                 aria-hidden="true"
                             />
                         )}
-                        {cells.map(cell => {
+                        {cells.map((cell, cellIndex) => {
                             const pinnedClass = cell.pinned ? ` ogx-col-group-cell--pinned ogx-col-group-cell--pinned-${cell.pinned}` : '';
                             const style: React.CSSProperties = {
                                 width: cell.width,
@@ -277,6 +277,8 @@ export function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps
                             } else if (cell.pinned === 'right') {
                                 style.position = 'sticky';
                                 style.right = pinnedPositions[cell.fields[cell.fields.length - 1]];
+                                // Free space goes before the right-pinned section, as in the column header row.
+                                if (cells[cellIndex - 1]?.pinned !== 'right') style.marginLeft = 'auto';
                             }
                             if (!cell.isGroup) {
                                 return (

package/lib/hooks/core/gridApiPlaceholder.ts

@@ -1,4 +1,4 @@
-import type { GridApi } from '../../types';
+import type { GridApi, GridRowModel, GridValidRowModel } from '../../types';
 
 const noop = () => {};
 
@@ -7,7 +7,7 @@ const noop = () => {};
  * `apiRef.current` is never null (its type says it is not) before the grid has mounted;
  * the grid replaces it with the live API when it mounts.
  */
-export function createGridApiPlaceholder(): GridApi {
+export function createGridApiPlaceholder<R extends GridValidRowModel = GridRowModel>(): GridApi<R> {
     return {
         getRow: () => null,
         getAllRows: () => [],

package/lib/hooks/core/useGridApiRef.ts

@@ -1,6 +1,6 @@
 import { useRef, useState } from 'react';
 import type { MutableRefObject } from 'react';
-import type { GridApi } from '../../types';
+import type { GridApi, GridRowModel, GridValidRowModel } from '../../types';
 import { createGridApiPlaceholder } from './gridApiPlaceholder';
 
 /**
@@ -15,8 +15,11 @@ import { createGridApiPlaceholder } from './gridApiPlaceholder';
  * which matches `DataGridProps.apiRef` under both @types/react 18 and 19. Left to inference,
  * React 19's types emit `RefObject<GridApi>`, which React 18's types treat as read-only and
  * nullable, so `apiRef={useGridApiRef()}` failed to type-check on React 18.
+ *
+ * Pass your row type to have the row getters typed: `useGridApiRef<Invoice>().current.getRow(id)`
+ * returns `Invoice | null`.
  */
-export function useGridApiRef(): MutableRefObject<GridApi> {
-    const [placeholder] = useState(createGridApiPlaceholder);
-    return useRef<GridApi>(placeholder);
+export function useGridApiRef<R extends GridValidRowModel = GridRowModel>(): MutableRefObject<GridApi<R>> {
+    const [placeholder] = useState(createGridApiPlaceholder<R>);
+    return useRef<GridApi<R>>(placeholder);
 }

package/lib/hooks/core/useGridDevWarnings.ts

@@ -14,11 +14,16 @@ export interface UseGridDevWarningsParams {
     scrollHeight?: number;
     /** `listView` is set but `listViewColumn` is not, so the grid view is shown. */
     listViewWithoutColumn?: boolean;
+    /** Number of items the list view renders (0 when the list view is not shown). It does not virtualize. */
+    listViewRowCount?: number;
 }
 
 // Below this many rows, rendering everything is harmless, so an unbounded container is not worth a warning.
 const UNBOUNDED_WARN_THRESHOLD = 200;
 
+/** The list view renders every item; above this many the page slows down noticeably. */
+export const LIST_VIEW_WARN_THRESHOLD = 2000;
+
 /**
  * Browsers cap element heights (Firefox at about 17.9M px, Chromium and Safari at about 33.5M px):
  * rows laid out below the cap cannot be scrolled to.
@@ -26,12 +31,22 @@ const UNBOUNDED_WARN_THRESHOLD = 200;
 export const MAX_SCROLLABLE_HEIGHT = 17_800_000;
 
 export function useGridDevWarnings(params: UseGridDevWarningsParams): void {
-    const { paginationRequested, isRowGrouping, autoHeight, viewportHeight, renderedRowCount, totalRowCount, pinnedRowsIgnored = false, scrollHeight = 0, listViewWithoutColumn = false } = params;
+    const { paginationRequested, isRowGrouping, autoHeight, viewportHeight, renderedRowCount, totalRowCount, pinnedRowsIgnored = false, scrollHeight = 0, listViewWithoutColumn = false, listViewRowCount = 0 } = params;
     const warnedPaginationRef = useRef(false);
     const warnedUnboundedRef = useRef(false);
     const warnedPinnedRowsRef = useRef(false);
     const warnedHeightRef = useRef(false);
     const warnedListViewRef = useRef(false);
+    const warnedListViewSizeRef = useRef(false);
+
+    useEffect(() => {
+        if (process.env.NODE_ENV === 'production' || warnedListViewSizeRef.current || listViewRowCount <= LIST_VIEW_WARN_THRESHOLD) return;
+        warnedListViewSizeRef.current = true;
+        console.warn(
+            `[OpenGridX] The list view is rendering all ${listViewRowCount} items: it does not virtualize. ` +
+            'Above a few thousand items use `pagination`, server-side loading, or the grid view. See docs/features/list-view.md.'
+        );
+    }, [listViewRowCount]);
 
     useEffect(() => {
         if (process.env.NODE_ENV === 'production' || warnedListViewRef.current || !listViewWithoutColumn) return;
@@ -74,15 +89,18 @@ export function useGridDevWarnings(params: UseGridDevWarningsParams): void {
 
     useEffect(() => {
         if (process.env.NODE_ENV === 'production' || warnedUnboundedRef.current || autoHeight) return;
-        if (viewportHeight > 0 && totalRowCount > UNBOUNDED_WARN_THRESHOLD && renderedRowCount >= totalRowCount) {
+        // Really unbounded: every row is rendered and the viewport is at least as tall as the rows, so it never scrolls.
+        if (viewportHeight > 0 && totalRowCount > UNBOUNDED_WARN_THRESHOLD && renderedRowCount >= totalRowCount && viewportHeight >= scrollHeight) {
             warnedUnboundedRef.current = true;
             console.warn(
                 `[OpenGridX] The grid viewport is ${Math.round(viewportHeight)}px tall and is rendering all ${totalRowCount} rows, ` +
-                'so row virtualization is effectively off. The grid container has no bounded height: it grows to fit its ' +
-                'content. Give it a fixed height, or if it is a flex child add `min-height: 0`. See docs/features/virtualization.md.'
+                'so row virtualization is effectively off: the grid fills its container, and the container grows to fit every row. ' +
+                'Give the container a definite height (for example `height: 600px` or `100vh`). If the container, or any ancestor ' +
+                'up to the sized one, is a flex or grid item, add `min-height: 0` to it. Alternatively pass a `height` prop, ' +
+                'or `autoHeight` if rendering every row is intended. See docs/features/virtualization.md.'
             );
         }
-    }, [autoHeight, viewportHeight, renderedRowCount, totalRowCount]);
+    }, [autoHeight, viewportHeight, renderedRowCount, totalRowCount, scrollHeight]);
 }
 
 /**

package/lib/types/index.ts

@@ -912,8 +912,11 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
   /** Callback fired when scrolling reaches the bottom of the grid viewport. */
   onRowsScrollEnd?: (params: GridRowScrollEndParams) => void;
 
-  /** Advanced: Reactive reference to the internal API for imperative control. */
-  apiRef?: React.MutableRefObject<GridApi>;
+  /**
+   * Advanced: reactive reference to the internal API for imperative control. Pass
+   * `useGridApiRef<MyRow>()` to have the row getters typed as `MyRow`; a plain `useGridApiRef()` also works.
+   */
+  apiRef?: React.MutableRefObject<GridApi<R>> | React.MutableRefObject<GridApi>;
 
   /** Custom components to replace internal grid parts. */
   slots?: {
@@ -1052,18 +1055,22 @@ export type GridDetailPanelHeight = number | 'auto';
  * The Imperative API for interacting with the DataGrid.
  * Access this via the `apiRef` prop or a ref passed to the component.
  */
-export interface GridApi {
+/**
+ * The imperative grid API. `R` types the row getters (`getRow`, `getAllRows`, `getVisibleRows`,
+ * `getAllFilteredRows`); it defaults to `GridRowModel`, so `GridApi` alone keeps working.
+ */
+export interface GridApi<R extends GridValidRowModel = GridRowModel> {
   /**
    * Returns the row model with the given ID.
    * @param id The row unique ID.
    */
-  getRow: (id: GridRowId) => GridRowModel | null;
+  getRow: (id: GridRowId) => R | null;
   /** Returns all rows currently loaded into the grid. */
-  getAllRows: () => GridRowModel[];
+  getAllRows: () => R[];
   /** Returns all rows currently visible after filtering and sorting. */
-  getVisibleRows: () => GridRowModel[];
+  getVisibleRows: () => R[];
   /** Returns all filtered and sorted rows, ignoring pagination. Use this for full-dataset exports. */
-  getAllFilteredRows: () => GridRowModel[];
+  getAllFilteredRows: () => R[];
   /**
    * Returns an ordered flat list of `GridGroupedExportRow` entries that mirrors the
    * on-screen grouping tree: group-headers, leaf rows, per-group subtotals, and a