@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/features/performance.mdx

@@ -0,0 +1,433 @@
+---
+sidebar_position: 20
+title: Performance
+description: Automatic CSS containment, opt-in Web Worker sort/filter, and column virtualization for large datasets
+---
+
+
+# Performance
+
+OGrid is built with performance as a first-class concern. Three complementary features cover the main bottlenecks in large data grids:
+
+| Feature | Opt-in? | Benefit |
+|---------|---------|---------|
+| **CSS Containment** | No (automatic) | Isolates cell layout and paint — prevents off-screen style recalculation |
+| **Column Virtualization** | Yes | Renders only visible columns — scales to hundreds of columns |
+| **Web Worker Sort/Filter** | Yes | Offloads sort and filter work to a background thread — keeps the UI thread free |
+
+For row virtualization (rendering only visible rows), see [Virtual Scrolling](./virtual-scrolling).
+
+---
+
+## CSS Containment (Automatic)
+
+OGrid applies CSS containment automatically to every grid cell — no configuration needed.
+
+```css
+/* Applied automatically to every body cell */
+td.ogrid-cell {
+  contain: content;        /* isolate layout + paint + style */
+}
+
+/* Pinned columns use position: sticky — containment is relaxed to avoid conflicts */
+td.ogrid-cell[data-pinned] {
+  contain: none;
+}
+```
+
+The browser uses `contain: content` to skip layout and paint work for cells that are not visible in the viewport. Combined with `content-visibility: auto` on non-virtualized rows, the browser can skip off-screen row layout entirely:
+
+```css
+/* Non-virtualized rows: browser skips layout for off-screen rows */
+tr[data-row]:not([data-virtual-scroll]) {
+  content-visibility: auto;
+}
+```
+
+The `data-virtual-scroll` attribute on the `<table>` element gates this behavior — when row virtualization is active, spacer rows already handle positioning, so `content-visibility` is not applied.
+
+**You do not need to configure anything.** These rules are included in the default stylesheet for every framework package.
+
+---
+
+## Web Worker Sort/Filter (Opt-in)
+
+Enable background thread sorting and filtering by setting `workerSort: true` on the grid:
+
+```tsx
+<OGrid
+  columns={columns}
+  data={data}
+  getRowId={(r) => r.id}
+  workerSort={true}
+/>
+```
+
+When enabled, sort and filter operations run in an inline Web Worker (created from a `Blob` URL) instead of on the main thread. The UI remains fully interactive while the worker processes the data.
+
+### Quick Example
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+interface Row {
+  id: number;
+  name: string;
+  revenue: number;
+  region: string;
+}
+
+const columns: IColumnDef<Row>[] = [
+  { columnId: 'id', name: 'ID', type: 'numeric' },
+  { columnId: 'name', name: 'Name', sortable: true },
+  { columnId: 'revenue', name: 'Revenue', type: 'numeric', sortable: true },
+  { columnId: 'region', name: 'Region', sortable: true },
+];
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}
+      data={largeDataset}    // e.g. 50,000 rows
+      getRowId={(r) => r.id}
+      workerSort={true}
+      statusBar
+    />
+  );
+}
+```
+
+:::tip Switching UI libraries
+The `OGrid` component has the same props across all React UI packages. To switch, just change the import:
+
+- **Radix** (lightweight, default): `from '@alaarab/ogrid-react-radix'`
+- **Fluent UI** (Microsoft 365 / SPFx): `from '@alaarab/ogrid-react-fluent'` — wrap in `<FluentProvider>`
+- **Material UI** (MUI v7): `from '@alaarab/ogrid-react-material'` — wrap in `<ThemeProvider>`
+:::
+
+  </TabItem>
+  <TabItem value="angular" label="Angular">
+
+```typescript
+
+interface Row {
+  id: number;
+  name: string;
+  revenue: number;
+  region: string;
+}
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `<ogrid [props]="gridProps" />`
+})
+export class GridComponent {
+  gridProps = {
+    columns: [
+      { columnId: 'id', name: 'ID', type: 'numeric' },
+      { columnId: 'name', name: 'Name', sortable: true },
+      { columnId: 'revenue', name: 'Revenue', type: 'numeric', sortable: true },
+      { columnId: 'region', name: 'Region', sortable: true },
+    ] as IColumnDef<Row>[],
+    data: largeDataset,   // e.g. 50,000 rows
+    getRowId: (item: Row) => item.id,
+    workerSort: true,
+    statusBar: true,
+  };
+}
+```
+
+:::tip Switching UI libraries
+Same component API across Angular packages. To switch, just change the import:
+
+- **Radix (CDK)**: `from '@alaarab/ogrid-angular-radix'` *(default, lightweight)*
+- **Angular Material**: `from '@alaarab/ogrid-angular-material'`
+- **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
+
+All components are standalone — no NgModule required.
+:::
+
+  </TabItem>
+  <TabItem value="vue" label="Vue">
+
+```vue
+<script setup lang="ts">
+
+interface Row {
+  id: number;
+  name: string;
+  revenue: number;
+  region: string;
+}
+
+const columns: IColumnDef<Row>[] = [
+  { columnId: 'id', name: 'ID', type: 'numeric' },
+  { columnId: 'name', name: 'Name', sortable: true },
+  { columnId: 'revenue', name: 'Revenue', type: 'numeric', sortable: true },
+  { columnId: 'region', name: 'Region', sortable: true },
+];
+
+const gridProps = {
+  columns,
+  data: largeDataset,   // e.g. 50,000 rows
+  getRowId: (item: Row) => item.id,
+  workerSort: true,
+  statusBar: true,
+};
+</script>
+
+<template>
+  <OGrid :gridProps="gridProps" />
+</template>
+```
+
+:::tip Switching UI libraries
+Same component API across Vue packages. To switch, just change the import:
+
+- **Radix (Headless UI)**: `from '@alaarab/ogrid-vue-radix'` *(default, lightweight)*
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'` — wrap in `<v-app>` for theming
+- **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
+:::
+
+  </TabItem>
+  <TabItem value="js" label="Vanilla JS">
+
+```js
+
+const grid = new OGrid(document.getElementById('grid'), {
+  columns: [
+    { columnId: 'id', name: 'ID', type: 'numeric' },
+    { columnId: 'name', name: 'Name', sortable: true },
+    { columnId: 'revenue', name: 'Revenue', type: 'numeric', sortable: true },
+    { columnId: 'region', name: 'Region', sortable: true },
+  ],
+  data: largeDataset,   // e.g. 50,000 rows
+  getRowId: (r) => r.id,
+  workerSort: true,
+  statusBar: true,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+### `'auto'` Mode
+
+Set `workerSort: 'auto'` to let the grid decide. The worker is used only when the dataset exceeds **5,000 rows**; smaller datasets use synchronous processing:
+
+```tsx
+<OGrid
+  workerSort="auto"
+  // ...
+/>
+```
+
+This is the safest choice if you do not know the data size ahead of time.
+
+### How It Works
+
+1. Before sorting or filtering, the grid extracts a flat value matrix from the row data.
+2. The matrix is transferred to an inline `Blob` Web Worker via `postMessage`.
+3. The worker performs the sort and filter computation and returns the sorted/filtered row indices.
+4. The grid uses those indices to re-render the visible rows — no data is copied back, only indices.
+
+The worker is created once and reused for subsequent sort/filter operations in the same grid instance.
+
+### Automatic Fallback
+
+The worker is bypassed automatically in situations where it cannot run:
+
+| Situation | Behavior |
+|-----------|----------|
+| Custom `compare` function on a column | Falls back to synchronous sort (custom functions cannot cross the worker boundary) |
+| `people` filter type | Falls back to synchronous filter (requires rich object comparison) |
+| `Worker` API unavailable (e.g. old browser or sandboxed iframe) | Falls back to synchronous processing silently |
+
+The fallback is transparent — the grid sorts and filters correctly in all cases.
+
+### Content Security Policy (CSP)
+
+The worker is created from an inline `Blob` URL. If your application enforces a `Content-Security-Policy` header, you must allow `blob:` in the `worker-src` directive:
+
+```
+Content-Security-Policy: worker-src 'self' blob:;
+```
+
+Without this directive, the browser will block the worker and the grid will fall back to synchronous processing automatically.
+
+:::caution
+If your CSP does not permit `blob:` and you require worker-based processing, contact your security team about the CSP configuration before enabling `workerSort`.
+:::
+
+---
+
+## Combining All Three Features
+
+Row virtualization, column virtualization, and worker sort/filter are fully compatible and can be enabled together for maximum throughput on very wide, very tall datasets:
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}      // e.g. 100 columns
+      data={data}            // e.g. 100,000 rows
+      getRowId={(r) => r.id}
+      virtualScroll={{
+        enabled: true,       // row virtualization: renders ~30 rows instead of 100,000
+        rowHeight: 36,
+        overscan: 5,
+        columns: true,       // column virtualization: renders only visible columns
+        columnOverscan: 2,
+      }}
+      workerSort={true}      // keeps the UI thread free during sort/filter
+      statusBar
+    />
+  );
+}
+```
+
+:::tip Switching UI libraries
+The `OGrid` component has the same props across all React UI packages. To switch, just change the import:
+
+- **Radix** (lightweight, default): `from '@alaarab/ogrid-react-radix'`
+- **Fluent UI** (Microsoft 365 / SPFx): `from '@alaarab/ogrid-react-fluent'` — wrap in `<FluentProvider>`
+- **Material UI** (MUI v7): `from '@alaarab/ogrid-react-material'` — wrap in `<ThemeProvider>`
+:::
+
+  </TabItem>
+  <TabItem value="angular" label="Angular">
+
+```typescript
+gridProps = {
+  columns,           // e.g. 100 columns
+  data: largeData,   // e.g. 100,000 rows
+  getRowId: (item: Row) => item.id,
+  virtualScroll: {
+    enabled: true,
+    rowHeight: 36,
+    overscan: 5,
+    columns: true,
+    columnOverscan: 2,
+  },
+  workerSort: true,
+  statusBar: true,
+};
+```
+
+:::tip Switching UI libraries
+Same component API across Angular packages. To switch, just change the import:
+
+- **Radix (CDK)**: `from '@alaarab/ogrid-angular-radix'` *(default, lightweight)*
+- **Angular Material**: `from '@alaarab/ogrid-angular-material'`
+- **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
+
+All components are standalone — no NgModule required.
+:::
+
+  </TabItem>
+  <TabItem value="vue" label="Vue">
+
+```vue
+<script setup lang="ts">
+const gridProps = {
+  columns,          // e.g. 100 columns
+  data: largeData,  // e.g. 100,000 rows
+  getRowId: (item: Row) => item.id,
+  virtualScroll: {
+    enabled: true,
+    rowHeight: 36,
+    overscan: 5,
+    columns: true,
+    columnOverscan: 2,
+  },
+  workerSort: true,
+  statusBar: true,
+};
+</script>
+
+<template>
+  <OGrid :gridProps="gridProps" />
+</template>
+```
+
+:::tip Switching UI libraries
+Same component API across Vue packages. To switch, just change the import:
+
+- **Radix (Headless UI)**: `from '@alaarab/ogrid-vue-radix'` *(default, lightweight)*
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'` — wrap in `<v-app>` for theming
+- **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
+:::
+
+  </TabItem>
+  <TabItem value="js" label="Vanilla JS">
+
+```js
+
+const grid = new OGrid(document.getElementById('grid'), {
+  columns,           // e.g. 100 columns
+  data: largeData,   // e.g. 100,000 rows
+  getRowId: (r) => r.id,
+  virtualScroll: {
+    enabled: true,
+    rowHeight: 36,
+    overscan: 5,
+    columns: true,
+    columnOverscan: 2,
+  },
+  workerSort: true,
+  statusBar: true,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+---
+
+## Props Reference
+
+### `workerSort`
+
+| Value | Behavior |
+|-------|----------|
+| `false` (default) | Synchronous sort/filter on the main thread |
+| `true` | Always use Web Worker for sort and filter |
+| `'auto'` | Use Web Worker only when `data.length > 5000` |
+
+### `virtualScroll` (Performance Fields)
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `columns` | `boolean` | `false` | Enable column virtualization alongside row virtualization |
+| `columnOverscan` | `number` | `2` | Extra columns rendered beyond the visible horizontal range on each side |
+
+For the full `virtualScroll` props table, see [Virtual Scrolling — Props Reference](./virtual-scrolling#props-reference).
+
+---
+
+## When to Use Each Feature
+
+| Dataset Size | Recommendation |
+|---|---|
+| < 1,000 rows, < 20 columns | No performance features needed. CSS containment applies automatically. |
+| 1,000 – 10,000 rows | Enable row virtualization (`virtualScroll: { enabled: true, rowHeight: 36 }`). |
+| > 10,000 rows | Row virtualization + `workerSort: 'auto'` or `workerSort: true`. |
+| > 30 columns with horizontal scroll | Add `columns: true` to the `virtualScroll` config. |
+| All of the above | Combine all three: row + column virtualization and `workerSort: true`. |
+
+---
+
+## Related
+
+- [Virtual Scrolling](./virtual-scrolling) -- row virtualization, programmatic scrolling, and the full `virtualScroll` API
+- [Sorting](./sorting) -- configure sortable columns and custom comparators
+- [Filtering](./filtering) -- filter types and server-side filtering
+- [Server-Side Data](./server-side-data) -- move sort and filter to the server entirely
+- [Column Pinning](./column-pinning) -- pinned columns always render regardless of column virtualization

package/bundled-docs/features/row-selection.mdx

@@ -0,0 +1,256 @@
+---
+sidebar_position: 7
+title: Row Selection
+description: Single and multi-row selection with checkboxes, keyboard support, and imperative API.
+---
+
+
+# Row Selection
+
+Select entire rows with checkboxes (multiple mode) or radio-button-style selection (single mode). Access selected rows programmatically via the grid API ref.
+
+## Live Demo
+
+<RowSelectionDemo />
+
+:::tip Framework-Specific Styling
+The live demo above shows **React Radix UI** styling (lightweight default). To see how row selection looks in your framework's design system, click the framework buttons above the demo to open online demo:
+- **React** — Radix UI checkboxes
+- **Angular** — Angular Material checkboxes
+- **Vue** — Vuetify checkboxes
+- **JS** — Vanilla JS default theme
+
+Each framework renders with its native checkbox components, so the styling matches your design system.
+:::
+
+## Quick Example
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+function App() {
+  const gridRef = useRef<IOGridApi<Person>>(null);
+
+  const handleExport = () => {
+    const selectedIds = gridRef.current?.getSelectedRows() ?? [];
+    console.log('Selected:', selectedIds);
+  };
+
+  return (
+    <>
+      <button onClick={handleExport}>Export Selected</button>
+      <OGrid
+        ref={gridRef}
+        columns={columns}
+        data={people}
+        getRowId={(item) => item.id}
+        rowSelection="multiple"
+        onSelectionChange={(event) => {
+          console.log(`${event.selectedItems.length} rows selected`);
+        }}
+      />
+    </>
+  );
+}
+```
+
+:::tip Switching UI libraries
+The `OGrid` component has the same props across all React UI packages. To switch, just change the import:
+
+- **Radix** (lightweight, default): `from '@alaarab/ogrid-react-radix'`
+- **Fluent UI** (Microsoft 365 / SPFx): `from '@alaarab/ogrid-react-fluent'` — wrap in `<FluentProvider>`
+- **Material UI** (MUI v7): `from '@alaarab/ogrid-react-material'` — wrap in `<ThemeProvider>`
+:::
+
+  </TabItem>
+  <TabItem value="angular" label="Angular">
+
+```typescript
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `
+    <button (click)="handleExport()">Export Selected</button>
+    <ogrid [props]="gridProps" />
+  `
+})
+export class GridComponent {
+  constructor(private gridService: OGridService) {}
+
+  handleExport() {
+    const selectedIds = this.gridService.getSelectedRows();
+    console.log('Selected:', selectedIds);
+  }
+
+  gridProps = {
+    columns,
+    data: people,
+    getRowId: (item: Person) => item.id,
+    rowSelection: 'multiple' as const,
+    onSelectionChange: (event: any) => {
+      console.log(`${event.selectedItems.length} rows selected`);
+    },
+  };
+}
+```
+
+:::tip Switching UI libraries
+Same component API across Angular packages. To switch, just change the import:
+
+- **Radix (CDK)**: `from '@alaarab/ogrid-angular-radix'` *(default, lightweight)*
+- **Angular Material**: `from '@alaarab/ogrid-angular-material'`
+- **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
+
+All components are standalone — no NgModule required.
+:::
+
+  </TabItem>
+  <TabItem value="vue" label="Vue">
+
+```vue
+<script setup lang="ts">
+
+const gridProps = {
+  columns,
+  data: people,
+  getRowId: (item) => item.id,
+  rowSelection: 'multiple',
+  onSelectionChange: (event) => {
+    console.log(`${event.selectedItems.length} rows selected`);
+  },
+};
+</script>
+
+<template>
+  <OGrid :gridProps="gridProps" />
+</template>
+```
+
+:::tip Switching UI libraries
+Same component API across Vue packages. To switch, just change the import:
+
+- **Radix (Headless UI)**: `from '@alaarab/ogrid-vue-radix'` *(default, lightweight)*
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'` — wrap in `<v-app>` for theming
+- **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
+:::
+
+  </TabItem>
+  <TabItem value="js" label="Vanilla JS">
+
+```js
+
+const grid = new OGrid(document.getElementById('grid'), {
+  columns: columns,
+  data: people,
+  getRowId: (item) => item.id,
+  rowSelection: 'multiple',
+});
+
+grid.on('selectionChange', ({ selectedRows }) => {
+  console.log(`${selectedRows.length} rows selected`);
+});
+
+// Programmatic access
+document.getElementById('export-btn').addEventListener('click', () => {
+  const selected = grid.api.getSelectedRows();
+  console.log('Selected:', selected);
+});
+```
+
+  </TabItem>
+</Tabs>
+
+## How It Works
+
+Set `rowSelection` on the `OGrid` component to enable row selection:
+
+| Mode | Behavior |
+|------|----------|
+| `'none'` | No row selection (default). |
+| `'single'` | One row at a time. Clicking a row selects it and deselects the previous. |
+| `'multiple'` | Checkbox column appears. Click checkboxes to toggle. Shift+click for range select. Header checkbox toggles all. |
+
+:::info Row Selection vs Cell Selection
+**Row selection** (this page) selects entire rows using checkboxes. The header checkbox selects or deselects **all rows** at once.
+
+This is separate from **cell selection** ([Spreadsheet Selection](./spreadsheet-selection)), which selects individual cells using click/drag. Cell selection's **Ctrl+A** shortcut selects all **cells** in the grid, not rows.
+
+You can use both features together -- row selection and cell selection are independent.
+:::
+
+### Multiple Selection
+
+In `'multiple'` mode, a checkbox column is prepended to the grid:
+
+- Click a checkbox to toggle that row.
+- Click the header checkbox to select or deselect all visible rows.
+- Hold **Shift** and click a checkbox to select a range of rows from the last clicked row.
+
+### Controlled Mode
+
+For full control, pass `selectedRows` and `onSelectionChange`:
+
+```tsx
+function App() {
+  const [selectedRows, setSelectedRows] = useState<Set<RowId>>(new Set());
+
+  return (
+    <OGrid
+      columns={columns}
+      data={people}
+      getRowId={(item) => item.id}
+      rowSelection="multiple"
+      selectedRows={selectedRows}
+      onSelectionChange={(event) => {
+        setSelectedRows(new Set(event.selectedRowIds));
+      }}
+    />
+  );
+}
+```
+
+### Imperative API
+
+Use the grid ref to programmatically control selection:
+
+```tsx
+const gridRef = useRef<IOGridApi<Person>>(null);
+
+// Get selected row IDs
+gridRef.current?.getSelectedRows();
+
+// Set selection programmatically
+gridRef.current?.setSelectedRows([1, 2, 3]);
+
+// Select all rows (row selection, not cells)
+gridRef.current?.selectAll();
+
+// Deselect all rows
+gridRef.current?.deselectAll();
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `rowSelection` | `'none' \| 'single' \| 'multiple'` | `'none'` | Row selection mode. |
+| `selectedRows` | `Set<RowId>` | -- | Controlled set of selected row IDs. |
+| `onSelectionChange` | `(event: IRowSelectionChangeEvent<T>) => void` | -- | Called when selection changes. Event contains `selectedRowIds` and `selectedItems`. |
+
+## API Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getSelectedRows` | `() => RowId[]` | Returns currently selected row IDs. |
+| `setSelectedRows` | `(rowIds: RowId[]) => void` | Sets selected rows programmatically. |
+| `selectAll` | `() => void` | Selects all rows. |
+| `deselectAll` | `() => void` | Deselects all rows. |
+
+## Related
+
+- [Spreadsheet Selection](./spreadsheet-selection) -- cell-level selection
+- [Sorting](./sorting) -- sort rows before selection
+- [Filtering](./filtering) -- filter rows before selection