@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/features/keyboard-navigation.mdx

@@ -0,0 +1,236 @@
+---
+sidebar_position: 17
+title: Keyboard Navigation
+description: Full keyboard support for navigating, editing, selecting, and operating on cells
+---
+
+
+# Keyboard Navigation
+
+OGrid supports comprehensive keyboard navigation for moving between cells, editing values, selecting ranges, and performing clipboard and undo operations -- all without touching the mouse.
+
+## Live Demo
+
+<KeyboardNavigationDemo />
+
+:::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.
+:::
+
+## Quick Example
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}
+      data={data}
+      getRowId={(r) => r.id}
+      editable
+    />
+  );
+}
+```
+
+:::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: `<ogrid [props]="gridProps" />`
+})
+export class GridComponent {
+  gridProps = {
+    columns: columns,
+    data: data,
+    getRowId: (r: Row) => r.id,
+    editable: 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,
+  data,
+  getRowId: (r) => r.id,
+  editable: 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: columns,
+  data: data,
+  getRowId: (r) => r.id,
+  editable: true,
+});
+
+// Click any cell to make it active, then use keyboard to navigate
+```
+
+  </TabItem>
+</Tabs>
+
+Click any cell to make it the active cell, then use the keyboard to navigate and edit.
+
+## Navigation
+
+| Key | Action |
+|---|---|
+| Arrow Up / Down / Left / Right | Move active cell in that direction |
+| Ctrl+Arrow | Jump to the edge of the current data region (Excel-style) |
+| Tab | Move to the next cell (left to right, then next row) |
+| Shift+Tab | Move to the previous cell |
+| Home | Move to the first column in the current row |
+| End | Move to the last column in the current row |
+| Ctrl+Home | Move to the first cell in the grid (top-left) |
+| Ctrl+End | Move to the last cell in the grid (bottom-right) |
+| Page Down | Move down by one page of rows |
+| Page Up | Move up by one page of rows |
+
+## Cell Selection
+
+| Key | Action |
+|---|---|
+| Click | Set active cell |
+| Shift+Arrow | Extend selection range from the active cell |
+| Ctrl+Shift+Arrow | Extend selection to the edge of the current data region |
+| Shift+Click | Select range from active cell to clicked cell |
+| Ctrl+A | Select all **cells** in the grid (for copy/paste/fill operations, not row selection) |
+
+The selection range is highlighted with a green border. The active cell remains visually distinct within the range.
+
+:::info Cell Selection vs Row Selection
+Ctrl+A selects all **cells** in the grid for spreadsheet operations (copy/paste/fill). This is different from row selection, where the header checkbox selects all **rows** for bulk operations. See [Row Selection](./row-selection) and [Spreadsheet Selection](./spreadsheet-selection) for details.
+:::
+
+### Ctrl+Arrow (Data Region Jump)
+
+Ctrl+Arrow navigates the same way Excel does:
+
+- **Non-empty cell → non-empty neighbor**: Jumps to the last non-empty cell before a gap (empty cell) or the grid edge.
+- **Non-empty cell → empty neighbor**: Skips over the empty cells and lands on the next non-empty cell, or the grid edge if all remaining cells are empty.
+- **Empty cell**: Jumps to the next non-empty cell in that direction, or the grid edge.
+
+Combine with **Shift** to extend the selection range to the same target.
+
+## Editing
+
+| Key | Action |
+|---|---|
+| Enter | Start editing the active cell; press again to commit and move down |
+| F2 | Start editing the active cell (cursor at end of text) |
+| Escape | Cancel editing and revert to the original value |
+| Delete / Backspace | Clear the contents of selected cells |
+| Any printable character | Start editing and replace cell content with the typed character |
+
+When a cell is in edit mode:
+- **Enter** commits the value and moves the active cell down.
+- **Tab** commits the value and moves the active cell right.
+- **Escape** discards the edit and returns to navigation mode.
+- Arrow keys move the cursor within the editor (they do not navigate between cells while editing).
+
+## Clipboard
+
+| Key | Action |
+|---|---|
+| Ctrl+C | Copy selected cells to clipboard (tab-separated) |
+| Ctrl+X | Cut selected cells (copy + clear originals) |
+| Ctrl+V | Paste clipboard contents starting at the active cell |
+
+Copied data uses tab-separated format compatible with Excel and Google Sheets. Multi-cell selections copy the entire rectangular range.
+
+## Undo / Redo
+
+| Key | Action |
+|---|---|
+| Ctrl+Z | Undo the last cell edit |
+| Ctrl+Y | Redo the last undone edit |
+
+Undo/redo requires the `onUndo`, `onRedo`, `canUndo`, and `canRedo` props to be wired up (typically via the `useUndoRedo` hook).
+
+## How It Works
+
+Keyboard navigation is handled by the `useKeyboardNavigation` hook in core, which is automatically wired into the grid when `cellSelection` is enabled (the default). The hook listens for `keydown` events on the grid wrapper element and translates them into active cell movements, selection range changes, or editing actions.
+
+### Disabling Cell Selection
+
+Set `cellSelection={false}` to disable keyboard-driven cell navigation, selection, clipboard, and context menu. The grid becomes a read-only display table.
+
+```tsx
+<OGrid
+  columns={columns}
+  data={data}
+  getRowId={(r) => r.id}
+  cellSelection={false}
+/>
+```
+
+### macOS
+
+On macOS, Ctrl is replaced by the Command key for all shortcuts (Cmd+C, Cmd+V, Cmd+Z, etc.). The grid detects the platform automatically.
+
+## Props Reference
+
+| Type | Field | Description |
+|---|---|---|
+| `IOGridProps<T>` | `cellSelection` | `boolean` -- enable/disable keyboard navigation and selection (default `true`) |
+| `IOGridProps<T>` | `editable` | `boolean` -- enable cell editing via keyboard |
+| `IOGridProps<T>` | `onUndo` | Callback for Ctrl+Z |
+| `IOGridProps<T>` | `onRedo` | Callback for Ctrl+Y |
+| `IOGridProps<T>` | `canUndo` | `boolean` -- whether undo is available |
+| `IOGridProps<T>` | `canRedo` | `boolean` -- whether redo is available |
+
+## Related
+
+- [Context Menu](./context-menu) -- right-click menu mirrors keyboard shortcuts
+- [Status Bar](./status-bar) -- shows aggregations for keyboard-selected ranges
+- [Column Pinning](./column-pinning) -- navigation works seamlessly across pinned and scrollable columns

package/bundled-docs/features/pagination.mdx

@@ -0,0 +1,245 @@
+---
+sidebar_position: 3
+title: Pagination
+description: Built-in pagination with configurable page sizes for client-side and server-side data.
+---
+
+
+# Pagination
+
+OGrid includes a built-in pagination bar with page navigation buttons, page size selector, and a row count summary. It works seamlessly with both client-side data arrays and server-side data sources.
+
+## Live Demo
+
+<PaginationDemo />
+
+:::tip Framework-Specific Styling
+The live demo above shows **React Radix UI** styling (lightweight default). To see how pagination controls look in your framework's design system, click the framework buttons above the demo to open online demo. Each framework renders with its native button and dropdown components, so the styling matches your design system.
+:::
+
+## Quick Example
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+const columns = [
+  { columnId: 'name', name: 'Name' },
+  { columnId: 'email', name: 'Email' },
+  { columnId: 'department', name: 'Department' },
+  {
+    columnId: 'salary',
+    name: 'Salary',
+    type: 'numeric' as const,
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+];
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}
+      data={people}
+      getRowId={(item) => item.id}
+      defaultPageSize={5}
+      pageSizeOptions={[5, 10, 25, 50]}
+      entityLabelPlural="people"
+    />
+  );
+}
+```
+
+:::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: `<ogrid [props]="gridProps" />`
+})
+export class GridComponent {
+  gridProps = {
+    columns: [
+      { columnId: 'name', name: 'Name' },
+      { columnId: 'email', name: 'Email' },
+      { columnId: 'department', name: 'Department' },
+      {
+        columnId: 'salary', name: 'Salary', type: 'numeric',
+        valueFormatter: (v: unknown) => `$${Number(v).toLocaleString()}`,
+      },
+    ] as IColumnDef<Person>[],
+    data: people,
+    getRowId: (item: Person) => item.id,
+    defaultPageSize: 5,
+    pageSizeOptions: [5, 10, 25, 50],
+    entityLabelPlural: 'people',
+  };
+}
+```
+
+:::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 columns: IColumnDef<Person>[] = [
+  { columnId: 'name', name: 'Name' },
+  { columnId: 'email', name: 'Email' },
+  { columnId: 'department', name: 'Department' },
+  {
+    columnId: 'salary', name: 'Salary', type: 'numeric',
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+];
+
+const gridProps = {
+  columns,
+  data: people,
+  getRowId: (item) => item.id,
+  defaultPageSize: 5,
+  pageSizeOptions: [5, 10, 25, 50],
+  entityLabelPlural: 'people',
+};
+</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: 'name', name: 'Name' },
+    { columnId: 'email', name: 'Email' },
+    { columnId: 'department', name: 'Department' },
+    {
+      columnId: 'salary',
+      name: 'Salary',
+      type: 'numeric',
+      valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+    },
+  ],
+  data: people,
+  getRowId: (item) => item.id,
+  pageSize: 5,
+  pageSizeOptions: [5, 10, 25, 50],
+  entityLabelPlural: 'people',
+});
+```
+
+  </TabItem>
+</Tabs>
+
+## How It Works
+
+Pagination is automatic. When your data exceeds the page size, the pagination bar appears at the bottom of the grid with:
+
+- **Previous / Next** buttons
+- **Page number** indicator ("Page 1 of 5")
+- **Page size selector** (dropdown to change rows per page)
+- **Row count summary** ("Showing 1-25 of 120 projects")
+
+### Client-Side Pagination
+
+When you pass a `data` array, OGrid slices it automatically based on the current page and page size. Sorting and filtering are applied before slicing.
+
+### Server-Side Pagination
+
+When you pass a `dataSource`, the grid calls `fetchPage()` with `page` and `pageSize` parameters. Your server returns only the rows for that page along with a `totalCount`:
+
+```tsx
+const dataSource: IDataSource<Project> = {
+  fetchPage: async ({ page, pageSize, sort, filters }) => {
+    const res = await fetch(`/api/projects?page=${page}&pageSize=${pageSize}`);
+    const json = await res.json();
+    return { items: json.data, totalCount: json.total };
+  },
+};
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}
+      dataSource={dataSource}
+      getRowId={(item) => item.id}
+      defaultPageSize={50}
+      entityLabelPlural="projects"
+    />
+  );
+}
+```
+
+### Controlled Pagination
+
+For full control over page state (e.g., URL-synced pagination), pass `page`, `pageSize`, `onPageChange`, and `onPageSizeChange`:
+
+```tsx
+function App() {
+  const [page, setPage] = useState(1);
+  const [pageSize, setPageSize] = useState(25);
+
+  return (
+    <OGrid
+      columns={columns}
+      data={items}
+      getRowId={(item) => item.id}
+      page={page}
+      pageSize={pageSize}
+      onPageChange={setPage}
+      onPageSizeChange={setPageSize}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `defaultPageSize` | `number` | `25` | Initial page size (uncontrolled mode). |
+| `pageSizeOptions` | `number[]` | `[10, 25, 50, 100]` | Options shown in the page size dropdown. If the active page size isn't in the list, it's auto-inserted. |
+| `page` | `number` | -- | Current page number (controlled mode, 1-indexed). |
+| `pageSize` | `number` | -- | Rows per page (controlled mode). |
+| `onPageChange` | `(page: number) => void` | -- | Called when page changes. |
+| `onPageSizeChange` | `(size: number) => void` | -- | Called when page size changes. |
+| `entityLabelPlural` | `string` | `'items'` | Label used in the row count summary (e.g., "Showing 1-25 of 100 **projects**"). |
+
+## Related
+
+- [Sorting](./sorting) -- sort results before pagination
+- [Filtering](./filtering) -- filter results before pagination