@alaarab/ogrid-mcp 2.5.4 → 2.5.8

package/bundled-docs/api/js-api.mdx

@@ -6,7 +6,7 @@ description: Full API reference for @alaarab/ogrid-js
 
 # Vanilla JS API
 
-Complete reference for `@alaarab/ogrid-js` — the framework-free data grid.
+Complete reference for `@alaarab/ogrid-js`  -  the framework-free data grid.
 
 ## OGrid Class
 
@@ -29,7 +29,7 @@ const grid = new OGrid(container, options);
 | `grid.api` | The imperative API object (see [API Methods](#api-methods) below). |
 | `grid.on(event, handler)` | Subscribe to a grid event. Returns `void`. |
 | `grid.off(event, handler)` | Unsubscribe from a grid event. |
-| `grid.destroy()` | Tear down the grid — removes DOM, listeners, and ResizeObservers. |
+| `grid.destroy()` | Tear down the grid  -  removes DOM, listeners, and ResizeObservers. |
 
 ---
 
@@ -43,8 +43,8 @@ All configuration is passed to the constructor.
 |--------|------|---------|-------------|
 | `columns` | `(IColumnDef<T> \| IColumnGroupDef<T>)[]` | **required** | Column definitions. |
 | `getRowId` | `(item: T) => RowId` | **required** | Returns a unique `string \| number` per row. |
-| `data` | `T[]` | — | Client-side data. Mutually exclusive with `dataSource`. |
-| `dataSource` | `IDataSource<T>` | — | Server-side data source. Mutually exclusive with `data`. |
+| `data` | `T[]` |  -  | Client-side data. Mutually exclusive with `dataSource`. |
+| `dataSource` | `IDataSource<T>` |  -  | Server-side data source. Mutually exclusive with `data`. |
 
 ### Pagination & Sorting
 
@@ -52,8 +52,8 @@ All configuration is passed to the constructor.
 |--------|------|---------|-------------|
 | `page` | `number` | `1` | Initial page (1-based). |
 | `pageSize` | `number` | `20` | Rows per page. |
-| `sort` | `{ field: string; direction: 'asc' \| 'desc' }` | — | Initial sort state. |
-| `filters` | `IFilters` | — | Initial filter state. |
+| `sort` | `{ field: string; direction: 'asc' \| 'desc' }` |  -  | Initial sort state. |
+| `filters` | `IFilters` |  -  | Initial filter state. |
 
 ### Interaction
 
@@ -61,9 +61,9 @@ All configuration is passed to the constructor.
 |--------|------|---------|-------------|
 | `editable` | `boolean` | `false` | Enable inline cell editing. |
 | `cellSelection` | `boolean` | `false` | Enable spreadsheet-style cell/range selection. |
-| `rowSelection` | `'single' \| 'multiple'` | — | Row checkbox selection mode. |
-| `selectedRows` | `Set<RowId>` | — | Controlled selected row IDs. |
-| `pinnedColumns` | `Record<string, 'left' \| 'right'>` | — | Pin columns to left/right edges. |
+| `rowSelection` | `'single' \| 'multiple'` |  -  | Row checkbox selection mode. |
+| `selectedRows` | `Set<RowId>` |  -  | Controlled selected row IDs. |
+| `pinnedColumns` | `Record<string, 'left' \| 'right'>` |  -  | Pin columns to left/right edges. |
 | `visibleColumns` | `Set<string>` | all | Initially visible column IDs. |
 
 ### Layout
@@ -72,9 +72,9 @@ All configuration is passed to the constructor.
 |--------|------|---------|-------------|
 | `layoutMode` | `'fill' \| 'content'` | `'fill'` | `'fill'` stretches to container; `'content'` sizes to data. |
 | `suppressHorizontalScroll` | `boolean` | `false` | Prevent horizontal scrollbar. |
-| `sideBar` | `boolean \| ISideBarDef` | — | Show sidebar with columns/filters panels. |
+| `sideBar` | `boolean \| ISideBarDef` |  -  | Show sidebar with columns/filters panels. |
 | `emptyMessage` | `string` | `'No data'` | Custom empty state text. |
-| `aria-label` | `string` | — | Accessible label for the grid. |
+| `aria-label` | `string` |  -  | Accessible label for the grid. |
 
 ### Callbacks
 
@@ -173,11 +173,11 @@ The JS package extends the core `IColumnDef<T>` with DOM-aware fields:
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `renderCell` | `(cell: HTMLTableCellElement, item: T, value: unknown) => void` | Custom cell renderer — mutate the `<td>` DOM directly. |
+| `renderCell` | `(cell: HTMLTableCellElement, item: T, value: unknown) => void` | Custom cell renderer  -  mutate the `<td>` DOM directly. |
 | `cellStyle` | `Partial<CSSStyleDeclaration>` | Inline styles applied to each cell. |
 | `cellEditor` | `string \| (container: HTMLElement, params: object) => { getValue: () => unknown; destroy: () => void }` | Built-in editor name (`'text'`, `'select'`, `'richSelect'`, `'checkbox'`, `'date'`) or a factory function for custom editors. |
 
-All other `IColumnDef` fields (`columnId`, `name`, `sortable`, `filterable`, `type`, `editable`, `valueFormatter`, `valueGetter`, `valueParser`, `minWidth`, `defaultWidth`, `idealWidth`, `pinned`, `required`, `defaultVisible`) are identical to the React version — see [Column Definitions](./column-def).
+All other `IColumnDef` fields (`columnId`, `name`, `sortable`, `filterable`, `type`, `editable`, `valueFormatter`, `valueGetter`, `valueParser`, `minWidth`, `defaultWidth`, `idealWidth`, `pinned`, `required`, `defaultVisible`) are identical to the React version  -  see [Column Definitions](./column-def).
 
 ---
 

package/bundled-docs/api/types.mdx

@@ -308,7 +308,7 @@ interface IFetchParams {
 | `page` | `number` | Current page number (1-indexed). |
 | `pageSize` | `number` | Number of items per page. |
 | `sort` | `{ field, direction }` | Active sort (field name + direction). Omit if no sort. |
-| `filters` | `IFilters` | Active filters (field → FilterValue). |
+| `filters` | `IFilters` | Active filters (field  to  FilterValue). |
 
 ### IPageResult<T>
 
@@ -537,9 +537,9 @@ interface IGridColumnState {
 | `visibleColumns` | `string[]` | Array of visible column IDs. |
 | `sort` | `{ field, direction }` | Active sort (field name + direction). |
 | `columnOrder` | `string[]` | Column display order (array of column IDs). |
-| `columnWidths` | `Record<string, number>` | Column widths in pixels (column ID → width). |
-| `filters` | `IFilters` | Active filters (field → FilterValue). |
-| `pinnedColumns` | `Record<string, 'left' \| 'right'>` | Pinned columns (column ID → position). |
+| `columnWidths` | `Record<string, number>` | Column widths in pixels (column ID  to  width). |
+| `filters` | `IFilters` | Active filters (field  to  FilterValue). |
+| `pinnedColumns` | `Record<string, 'left' \| 'right'>` | Pinned columns (column ID  to  position). |
 
 ### Usage Example
 

package/bundled-docs/features/column-chooser.mdx

@@ -64,8 +64,8 @@ function App() {
 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>`
+- **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>
@@ -119,7 +119,7 @@ Same component API across Angular packages. To switch, just change the import:
 - **Angular Material**: `from '@alaarab/ogrid-angular-material'`
 - **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
 
-All components are standalone — no NgModule required.
+All components are standalone  -  no NgModule required.
 :::
 
   </TabItem>
@@ -169,7 +169,7 @@ const gridProps = {
 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
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'`  -  wrap in `<v-app>` for theming
 - **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
 :::
 

package/bundled-docs/features/column-groups.mdx

@@ -74,8 +74,8 @@ function App() {
 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>`
+- **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>
@@ -125,7 +125,7 @@ Same component API across Angular packages. To switch, just change the import:
 - **Angular Material**: `from '@alaarab/ogrid-angular-material'`
 - **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
 
-All components are standalone — no NgModule required.
+All components are standalone  -  no NgModule required.
 :::
 
   </TabItem>
@@ -173,7 +173,7 @@ const gridProps = {
 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
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'`  -  wrap in `<v-app>` for theming
 - **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
 :::
 

package/bundled-docs/features/column-pinning.mdx

@@ -67,8 +67,8 @@ function App() {
 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>`
+- **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>
@@ -108,7 +108,7 @@ Same component API across Angular packages. To switch, just change the import:
 - **Angular Material**: `from '@alaarab/ogrid-angular-material'`
 - **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
 
-All components are standalone — no NgModule required.
+All components are standalone  -  no NgModule required.
 :::
 
   </TabItem>
@@ -146,7 +146,7 @@ const gridProps = {
 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
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'`  -  wrap in `<v-app>` for theming
 - **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
 :::
 
@@ -235,7 +235,7 @@ const gridRef = useRef<IOGridApi<Row>>(null);
 
 // Save pin state (e.g. to localStorage)
 const state = gridRef.current.getColumnState();
-// state.pinnedColumns → { name: 'left' }
+// state.pinnedColumns  to  { name: 'left' }
 localStorage.setItem('gridState', JSON.stringify(state));
 
 // Restore pin state on mount

package/bundled-docs/features/column-reordering.mdx

@@ -59,8 +59,8 @@ function App() {
 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>`
+- **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>
@@ -99,7 +99,7 @@ Same component API across Angular packages. To switch, just change the import:
 - **Angular Material**: `from '@alaarab/ogrid-angular-material'`
 - **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
 
-All components are standalone — no NgModule required.
+All components are standalone  -  no NgModule required.
 :::
 
   </TabItem>
@@ -136,7 +136,7 @@ const gridProps = {
 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
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'`  -  wrap in `<v-app>` for theming
 - **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
 :::
 
@@ -322,7 +322,7 @@ gridRef.current.setColumnOrder(['department', 'name', 'email', 'salary', 'status
 
 // Save and restore via column state
 const state = gridRef.current.getColumnState();
-// state.columnOrder → ['name', 'department', 'email', 'salary', 'status']
+// state.columnOrder  to  ['name', 'department', 'email', 'salary', 'status']
 localStorage.setItem('gridState', JSON.stringify(state));
 
 // Restore on mount

package/bundled-docs/features/column-types.mdx

@@ -1,7 +1,7 @@
 ---
 sidebar_position: 12.5
 title: Column Types
-description: Built-in column types for common data patterns — text, numeric, date, and boolean.
+description: Built-in column types for common data patterns  -  text, numeric, date, and boolean.
 ---
 
 
@@ -16,7 +16,7 @@ OGrid provides built-in column types that automatically configure alignment, dis
 | `'text'` | Left (default) | Text input | Text search | `String()` |
 | `'numeric'` | Right | Text input | Text search | `String()` |
 | `'date'` | Left | Date picker | Date range (from/to) | `toLocaleDateString()` |
-| `'boolean'` | Center | Checkbox | — | `True` / `False` |
+| `'boolean'` | Center | Checkbox |  -  | `True` / `False` |
 
 ## Quick Example
 
@@ -62,8 +62,8 @@ function App() {
 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>`
+- **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>
@@ -93,7 +93,7 @@ Same component API across Angular packages. To switch, just change the import:
 - **Angular Material**: `from '@alaarab/ogrid-angular-material'`
 - **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
 
-All components are standalone — no NgModule required.
+All components are standalone  -  no NgModule required.
 :::
 
   </TabItem>
@@ -119,7 +119,7 @@ const gridProps = {
 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
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'`  -  wrap in `<v-app>` for theming
 - **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
 :::
 
@@ -146,7 +146,7 @@ Setting `type: 'date'` provides:
 - **Display**: Values are automatically formatted via `toLocaleDateString()` (unless you provide a custom `valueFormatter` or `renderCell`).
 - **Sorting**: Dates are compared chronologically via `Date.getTime()`, not alphabetically.
 - **Cell editor**: Uses `<input type="date">` (native browser date picker) by default.
-- **Filter**: When `filterable: { type: 'date' }` is set, the column header filter shows **From** and **To** date inputs. Both are optional — you can filter by "after", "before", or a range.
+- **Filter**: When `filterable: { type: 'date' }` is set, the column header filter shows **From** and **To** date inputs. Both are optional  -  you can filter by "after", "before", or a range.
 
 ### Date Filter Values
 

package/bundled-docs/features/context-menu.mdx

@@ -50,8 +50,8 @@ function App() {
 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>`
+- **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>
@@ -89,7 +89,7 @@ Same component API across Angular packages. To switch, just change the import:
 - **Angular Material**: `from '@alaarab/ogrid-angular-material'`
 - **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
 
-All components are standalone — no NgModule required.
+All components are standalone  -  no NgModule required.
 :::
 
   </TabItem>
@@ -125,7 +125,7 @@ const gridProps = {
 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
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'`  -  wrap in `<v-app>` for theming
 - **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
 :::
 

package/bundled-docs/features/csv-export.mdx

@@ -47,8 +47,8 @@ function ExportButton({ data, columns }: { data: Row[]; columns: IColumnDef<Row>
 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>`
+- **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>
@@ -87,7 +87,7 @@ Same component API across Angular packages. To switch, just change the import:
 - **Angular Material**: `from '@alaarab/ogrid-angular-material'`
 - **PrimeNG**: `from '@alaarab/ogrid-angular-primeng'`
 
-All components are standalone — no NgModule required.
+All components are standalone  -  no NgModule required.
 :::
 
   </TabItem>
@@ -122,7 +122,7 @@ function handleExport() {
 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
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'`  -  wrap in `<v-app>` for theming
 - **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
 :::
 

package/bundled-docs/features/editing.mdx

@@ -7,17 +7,17 @@ description: Inline editing, clipboard operations, fill handle, and undo/redo
 
 # Editing & Clipboard
 
-OGrid supports inline cell editing, clipboard copy/paste, drag-to-fill, and undo/redo -- all working together through `onCellValueChanged` and `valueParser`.
-
-## Live Demo
+Double-click a cell to edit it. Hit Enter to save, Escape to cancel. It feels like a spreadsheet because it's built to work like one — with clipboard paste, drag-to-fill, and full undo/redo out of the box.
 
 <CellEditingDemo />
 
 :::tip Try it in your framework
-The demo above uses Radix UI for styling. To see this feature with your framework's design system (Fluent UI, Material UI, Vuetify, PrimeNG, etc.), click **"Open in online demo"** below the demo.
+The demo above uses Radix UI for styling. Each framework renders editors with its native components — dropdowns, date pickers, and inputs that match your design system.
 :::
 
-## Quick Example
+## Get started in 5 minutes
+
+Here's a realistic setup: an employee table with text, dropdown, and numeric columns — including validation that rejects bad salary values before they're saved.
 
 <Tabs groupId="framework">
   <TabItem value="react" label="React" default>
@@ -50,7 +50,7 @@ const columns = [
     type: 'numeric',
     valueParser: ({ newValue }) => {
       const num = Number(newValue);
-      return isNaN(num) || num < 0 ? undefined : num; // reject invalid
+      return isNaN(num) || num < 0 ? undefined : num; // undefined = reject
     },
     valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
   },
@@ -79,11 +79,11 @@ function App() {
 ```
 
 :::tip Switching UI libraries
-The `OGrid` component has the same props across all React UI packages. To switch, just change the import:
+Same props across all React packages — 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>`
+- **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>
@@ -128,7 +128,7 @@ export class GridComponent {
 ```
 
 :::tip Switching UI libraries
-Same component API across Angular packages. To switch, just change the import:
+Same component API across Angular packages. Change the import:
 
 - **Radix (CDK)**: `from '@alaarab/ogrid-angular-radix'` *(default, lightweight)*
 - **Angular Material**: `from '@alaarab/ogrid-angular-material'`
@@ -180,10 +180,10 @@ const gridProps = {
 ```
 
 :::tip Switching UI libraries
-Same component API across Vue packages. To switch, just change the import:
+Same API across Vue packages. 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
+- **Vuetify**: `from '@alaarab/ogrid-vue-vuetify'`  -  wrap in `<v-app>` for theming
 - **PrimeVue**: `from '@alaarab/ogrid-vue-primevue'`
 :::
 
@@ -229,7 +229,6 @@ const grid = new OGrid(document.getElementById('grid'), {
   editable: true,
 });
 
-// Listen for cell edits
 grid.on('cellValueChanged', (event) => {
   console.log(`${event.columnId} changed to ${event.newValue}`);
 });
@@ -238,22 +237,28 @@ grid.on('cellValueChanged', (event) => {
   </TabItem>
 </Tabs>
 
-This single setup gives you inline editing, clipboard paste, fill handle, and full undo/redo.
+That single setup gives you inline editing, clipboard paste, fill handle, and full undo/redo.
+
+## Editing a cell
+
+Double-click or press **F2** to open the editor. When you're done:
 
-## Inline Editing
+- **Enter** — saves and moves focus down
+- **Tab** — saves and moves focus right
+- **Escape** — cancels, restores the original value
 
-Double-click or press **F2** to edit. **Enter** commits and moves down, **Tab** commits and moves right, **Escape** cancels.
+### Which editor should I use?
 
-### Built-in Editors
+| `cellEditor` | When to use it |
+|--------------|----------------|
+| `'text'` (default) | Freeform text — names, notes, anything open-ended |
+| `'select'` | Small, fixed list where the user picks exactly one value |
+| `'richSelect'` | Longer list with keyboard search — much nicer UX than a plain dropdown |
+| `'checkbox'` | Boolean toggle — renders as a checkbox, commits on click |
 
-| `cellEditor` | Description |
-|--------------|-------------|
-| `'text'` (default) | Standard text input |
-| `'select'` | Dropdown from `cellEditorParams.values` |
-| `'checkbox'` | Toggle boolean |
-| `'richSelect'` | Searchable dropdown with keyboard nav |
+### Searchable dropdown (richSelect)
 
-### Rich Select
+When your list gets longer than about 8 items, switch to `richSelect`. It adds a search box and full keyboard navigation:
 
 ```tsx
 {
@@ -261,21 +266,25 @@ Double-click or press **F2** to edit. **Enter** commits and moves down, **Tab**
   editable: true,
   cellEditor: 'richSelect',
   cellEditorParams: {
-    values: ['Engineering', 'Design', 'Marketing', 'Sales'],
-    formatValue: (v) => `Dept: ${v}`,
+    values: ['Engineering', 'Design', 'Marketing', 'Sales', 'Legal', 'Finance'],
+    formatValue: (v) => `Dept: ${v}`,  // optional display formatting
   },
 }
 ```
 
-### Per-Row Editability
+### Lock specific rows from editing
+
+Use a function for `editable` to make it conditional:
 
 ```tsx
 { columnId: 'name', editable: (item) => item.status !== 'locked' }
 ```
 
-### Custom Editor
+The cell still renders normally — it just won't open an editor when you click it.
+
+### Custom editor (popup)
 
-Pass a component to `cellEditor`. Use `cellEditorPopup: true` for a popover:
+For date pickers, color pickers, or any custom UI, pass your own component. Set `cellEditorPopup: true` to render it in a floating popover instead of inline:
 
 ```tsx
 function DateEditor({ value, onValueChange, onCommit, onCancel }: ICellEditorProps<Task>) {
@@ -297,12 +306,15 @@ function DateEditor({ value, onValueChange, onCommit, onCancel }: ICellEditorPro
 { columnId: 'dueDate', editable: true, cellEditor: DateEditor, cellEditorPopup: true }
 ```
 
-### Value Parsing
+### Validating input with `valueParser`
 
-`valueParser` validates input for editing, paste, fill, and delete. Return `undefined` to reject:
+`valueParser` runs on every edit, paste, fill, and delete. Return `undefined` to silently reject the value — the cell snaps back to its previous state:
 
 ```tsx
-{ columnId: 'age', editable: true, type: 'numeric',
+{
+  columnId: 'age',
+  editable: true,
+  type: 'numeric',
   valueParser: ({ newValue }) => {
     const num = Number(newValue);
     return isNaN(num) || num < 0 || num > 150 ? undefined : num;
@@ -310,68 +322,66 @@ function DateEditor({ value, onValueChange, onCommit, onCancel }: ICellEditorPro
 }
 ```
 
+:::tip Pro tip
+`valueParser` is your single source of truth for validation — it runs on inline edits, clipboard paste, fill handle, and delete. You don't need separate logic for each.
+:::
+
 ## Clipboard
 
 <ClipboardDemo />
 
-Standard keyboard shortcuts on selected cells:
+Standard shortcuts work on any selection — no configuration needed:
 
 | Key | Action | Requires `editable` |
 |-----|--------|-------------------|
-| Ctrl+C (Cmd+C) | Copy as tab-delimited text | No |
-| Ctrl+V (Cmd+V) | Paste into cells | Yes |
-| Ctrl+X (Cmd+X) | Cut (copy + clear) | Yes |
+| Ctrl+C / Cmd+C | Copy as tab-separated text | No |
+| Ctrl+V / Cmd+V | Paste into cells | Yes |
+| Ctrl+X / Cmd+X | Cut (copy then clear) | Yes |
 | Delete / Backspace | Clear selected cells | Yes |
 
-- **Copy** uses `valueFormatter` so copied values match the display.
-- **Paste** calls `valueParser` on each value and fires `onCellValueChanged` per cell.
+Copy respects `valueFormatter` — what you see is what you get in the clipboard. Paste calls `valueParser` on each value, so bad data is rejected before it lands in your rows.
 
-## Fill Handle
+## Fill handle
 
 <FillHandleDemo />
 
-A small square at the bottom-right of the selection. Drag it down to fill cells with the source value (like Excel).
+The small square in the bottom-right corner of a selection — drag it down to fill cells. Works exactly like Excel. Each filled cell goes through `valueParser`, so validation still applies.
 
-- Requires `editable={true}` and `cellSelection={true}` (default).
-- Calls `valueParser` per cell -- return `undefined` to skip.
-- Each filled cell fires `onCellValueChanged`.
-- Uses `requestAnimationFrame` for smooth drag performance.
+:::tip Pro tip
+Select a range of cells before dragging the fill handle to populate multiple columns at once. The fill handle uses `requestAnimationFrame` internally, so it stays smooth even on large selections.
+:::
 
 ## Undo / Redo
 
-The `useUndoRedo` hook tracks edit history (including paste, fill, and delete). See the quick example above.
-
-| Hook Input | Type | Description |
-|------------|------|-------------|
-| `data` | `T[]` | Current data array |
-| `setData` | `(data: T[]) => void` | State setter |
-| `getRowId` | `(item: T) => RowId` | Row identifier |
+The `useUndoRedo` hook (React) tracks everything: inline edits, paste, fill, and delete. Ctrl+Z / Ctrl+Y work out of the box, and you can wire up buttons too:
 
-| Hook Output | Type | Description |
-|-------------|------|-------------|
-| `handleCellValueChanged` | `(event) => void` | Wraps edits onto the undo stack |
-| `undo` / `redo` | `() => void` | Revert / re-apply |
-| `canUndo` / `canRedo` | `boolean` | Stack status |
+```tsx
+const { handleCellValueChanged, undo, redo, canUndo, canRedo } = useUndoRedo({
+  data,
+  setData,
+  getRowId: (item) => item.id,
+});
+```
 
-**Shortcuts:** Ctrl+Z (undo), Ctrl+Y (redo). Also available in the right-click [context menu](./context-menu).
+Pass `handleCellValueChanged` as `onCellValueChanged` — it intercepts changes and pushes them onto the undo stack before updating your state. Undo/redo are also available in the right-click [context menu](./context-menu).
 
-## Props Summary
+## Props reference
 
 | Prop | Type | Description |
 |------|------|-------------|
 | `editable` | `boolean` | Enable editing grid-wide (on `OGrid`) |
-| `editable` | `boolean \| (item: T) => boolean` | Per-column/row (on `IColumnDef`) |
-| `cellEditor` | `'text' \| 'select' \| 'checkbox' \| 'richSelect' \| ComponentType` | Editor type |
-| `cellEditorPopup` | `boolean` | Render custom editor in a popover |
+| `editable` | `boolean \| (item: T) => boolean` | Per-column/row editability (on `IColumnDef`) |
+| `cellEditor` | `'text' \| 'select' \| 'checkbox' \| 'richSelect' \| ComponentType` | Editor to use |
+| `cellEditorPopup` | `boolean` | Render editor in a floating popover |
 | `cellEditorParams` | `CellEditorParams` | Editor parameters (e.g., `{ values: [...] }`) |
-| `valueParser` | `(params) => unknown` | Validate on edit/paste/fill/delete. Return `undefined` to reject. |
-| `valueFormatter` | `(value, item) => string` | Format display & copy output |
-| `onCellValueChanged` | `(event) => void` | Fired after any cell value change |
+| `valueParser` | `(params) => unknown` | Validate/transform on edit, paste, fill, delete. Return `undefined` to reject. |
+| `valueFormatter` | `(value, item) => string` | Format value for display and clipboard copy |
+| `onCellValueChanged` | `(event) => void` | Fires after any cell value change |
 | `onUndo` / `onRedo` | `() => void` | Undo/redo callbacks |
 | `canUndo` / `canRedo` | `boolean` | Enable/disable undo/redo in context menu |
 
-## Related
+## Next steps
 
-- [Spreadsheet Selection](./spreadsheet-selection) -- select cells for editing
-- [Context Menu](./context-menu) -- right-click menu with undo/redo
-- [Custom Cell Editors](../guides/custom-cell-editors) -- advanced editor guide
+- [Spreadsheet Selection](./spreadsheet-selection) — select ranges before editing or pasting
+- [Context Menu](./context-menu) — right-click to undo, copy, and more
+- [Formulas](./formulas) — formula-aware editing with `=SUM(A1:A5)` syntax