@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/features/sorting.mdx

@@ -0,0 +1,241 @@
+---
+sidebar_position: 1
+title: Sorting
+description: Enable column sorting with click-to-toggle, custom comparators, and server-side support.
+---
+
+
+# Sorting
+
+Add sortable columns to your grid with a single prop. Users click a column header to cycle through ascending, descending, and unsorted states. A sort indicator arrow shows the current direction.
+
+## Live Demo
+
+<SortingDemo />
+
+:::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
+
+const columns = [
+  { columnId: 'name', name: 'Name', sortable: true },
+  { columnId: 'age', name: 'Age', sortable: true, type: 'numeric' as const },
+  { columnId: 'department', name: 'Department', sortable: true },
+  {
+    columnId: 'salary',
+    name: 'Salary',
+    sortable: true,
+    type: 'numeric' as const,
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+];
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}
+      data={people}
+      getRowId={(item) => item.id}
+      defaultPageSize={10}
+    />
+  );
+}
+```
+
+:::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', sortable: true },
+      { columnId: 'age', name: 'Age', sortable: true, type: 'numeric' },
+      { columnId: 'department', name: 'Department', sortable: true },
+      {
+        columnId: 'salary',
+        name: 'Salary',
+        sortable: true,
+        type: 'numeric',
+        valueFormatter: (v: unknown) => `$${Number(v).toLocaleString()}`,
+      },
+    ] as IColumnDef<Person>[],
+    data: people,
+    getRowId: (item: Person) => item.id,
+    defaultPageSize: 10,
+  };
+}
+```
+
+:::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', sortable: true },
+  { columnId: 'age', name: 'Age', sortable: true, type: 'numeric' },
+  { columnId: 'department', name: 'Department', sortable: true },
+  {
+    columnId: 'salary',
+    name: 'Salary',
+    sortable: true,
+    type: 'numeric',
+    valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+  },
+];
+
+const gridProps = {
+  columns,
+  data: people,
+  getRowId: (item) => item.id,
+  defaultPageSize: 10,
+};
+</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', sortable: true },
+    { columnId: 'age', name: 'Age', sortable: true, type: 'numeric' },
+    { columnId: 'department', name: 'Department', sortable: true },
+    {
+      columnId: 'salary',
+      name: 'Salary',
+      sortable: true,
+      type: 'numeric',
+      valueFormatter: (v) => `$${Number(v).toLocaleString()}`,
+    },
+  ],
+  data: people,
+  getRowId: (item) => item.id,
+  pageSize: 10,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+## How It Works
+
+Set `sortable: true` on any column definition to make it sortable. When a user clicks the column header, OGrid toggles the sort direction: unsorted, ascending, then descending.
+
+OGrid supports both **uncontrolled** and **controlled** sorting:
+
+- **Uncontrolled** -- the grid manages sort state internally. Use `defaultSortBy` and `defaultSortDirection` to set the initial sort.
+- **Controlled** -- you own the state. Pass `sort` and `onSortChange` to the grid.
+
+### Custom Comparator
+
+For columns that need custom sort logic (e.g., sorting by a nested field or special ordering), provide a `compare` function on the column definition:
+
+```tsx
+const columns = [
+  {
+    columnId: 'priority',
+    name: 'Priority',
+    sortable: true,
+    compare: (a, b) => {
+      const order = { High: 0, Medium: 1, Low: 2 };
+      return order[a.priority] - order[b.priority];
+    },
+  },
+];
+```
+
+### Server-Side Sorting
+
+When using a `dataSource`, the sort parameter is forwarded to `fetchPage()`. The grid does not sort the data itself -- your server handles it:
+
+```tsx
+const dataSource: IDataSource<Project> = {
+  fetchPage: async ({ sort, page, pageSize, filters }) => {
+    const res = await fetch(`/api/projects?sort=${sort?.field}&dir=${sort?.direction}&page=${page}`);
+    const json = await res.json();
+    return { items: json.data, totalCount: json.total };
+  },
+};
+```
+
+### Controlled Example
+
+```tsx
+function App() {
+  const [sort, setSort] = useState({ field: 'name', direction: 'asc' as const });
+
+  return (
+    <OGrid
+      columns={columns}
+      data={people}
+      getRowId={(item) => item.id}
+      sort={sort}
+      onSortChange={setSort}
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `sortable` | `boolean` | `false` | Set on `IColumnDef` to enable sorting for that column. |
+| `compare` | `(a: T, b: T) => number` | -- | Custom sort comparator on `IColumnDef`. |
+| `sort` | `{ field: string; direction: 'asc' \| 'desc' }` | -- | Controlled sort state on `OGrid`. |
+| `onSortChange` | `(sort: { field: string; direction: 'asc' \| 'desc' }) => void` | -- | Called when sort changes (controlled mode). |
+| `defaultSortBy` | `string` | -- | Initial sort column (uncontrolled mode). |
+| `defaultSortDirection` | `'asc' \| 'desc'` | `'asc'` | Initial sort direction (uncontrolled mode). |
+
+## Related
+
+- [Filtering](./filtering) -- filter rows by column values
+- [Pagination](./pagination) -- paginate sorted results

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

@@ -0,0 +1,201 @@
+---
+sidebar_position: 5
+title: Spreadsheet Selection
+description: Excel-like cell selection with active cell, range selection, and drag-to-select.
+---
+
+
+# Spreadsheet Selection
+
+OGrid provides Excel-like cell selection out of the box. Click a cell to make it active, drag or Shift+click to select a range. The active cell gets a green border, and selected ranges are highlighted with a green background.
+
+## Live Demo
+
+<SpreadsheetSelectionDemo />
+
+:::tip Framework-Specific Styling
+The live demo above shows **React Radix UI** styling (lightweight default). To see how this feature looks in your framework's design system, click the framework buttons above the demo to open online demo:
+- **React** — Radix UI styling
+- **Angular** — Angular Material styling
+- **Vue** — Vuetify styling
+- **JS** — Vanilla JS default theme
+
+Each framework renders OGrid with its native components, so the look and feel matches your design system.
+:::
+
+## Quick Example
+
+<Tabs groupId="framework">
+  <TabItem value="react" label="React" default>
+
+```tsx
+
+function App() {
+  return (
+    <OGrid
+      columns={columns}
+      data={items}
+      getRowId={(item) => item.id}
+      cellSelection  // default: true
+    />
+  );
+}
+```
+
+:::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,
+    data: items,
+    getRowId: (item: any) => item.id,
+    cellSelection: 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: items,
+  getRowId: (item) => item.id,
+  cellSelection: 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: items,
+  getRowId: (item) => item.id,
+  cellSelection: true,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+## How It Works
+
+Cell selection is **enabled by default** (`cellSelection={true}`). When active:
+
+- **Click** a cell to make it the active cell (green border).
+- **Shift+Click** another cell to select a rectangular range from the active cell to the clicked cell.
+- **Click and drag** across cells to select a range.
+- **Ctrl+A** selects all cells in the grid.
+- **Arrow keys** move the active cell. **Shift+Arrow** extends the selection range.
+
+:::info Cell Selection vs Row Selection
+**Cell selection** (this page) selects individual cells using click/drag. The **Ctrl+A** keyboard shortcut selects all **cells** in the grid for copy/paste/fill operations.
+
+This is separate from **row selection** ([Row Selection](./row-selection)), which selects entire rows using checkboxes. Row selection's header checkbox selects all **rows** at once.
+
+You can use both features together -- cell selection and row selection are independent.
+:::
+
+The selection range is represented by `ISelectionRange`:
+
+```tsx
+interface ISelectionRange {
+  startRow: number;   // row index of the anchor cell
+  startCol: number;   // column index of the anchor cell
+  endRow: number;     // row index of the end cell
+  endCol: number;     // column index of the end cell
+}
+```
+
+### Performance
+
+Drag selection is optimized with `requestAnimationFrame` and DOM attribute toggling. During a drag, React state is not updated on every mouse move -- only on mouse up. This keeps the grid responsive even with thousands of cells.
+
+### Disabling Cell Selection
+
+Pass `cellSelection={false}` to disable all spreadsheet-style selection. This also disables the fill handle, clipboard integration, and context menu cell operations:
+
+```tsx
+<OGrid
+  columns={columns}
+  data={items}
+  getRowId={(item) => item.id}
+  cellSelection={false}
+/>
+```
+
+### Selection Styling
+
+Selection colors use CSS custom properties for easy theming:
+
+```css
+--ogrid-selection: #217346;          /* Excel green, used for active cell border */
+--ogrid-selection-bg: rgba(33, 115, 70, 0.08);  /* range background */
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `cellSelection` | `boolean` | `true` | Enable or disable spreadsheet-style cell selection. |
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| Click | Select a single cell |
+| Shift+Click | Extend selection to a range |
+| Click+Drag | Select a range by dragging |
+| Arrow keys | Move active cell |
+| Shift+Arrow | Extend selection range |
+| Ctrl+A | Select all cells (for copy/paste/fill operations) |
+
+## Related
+
+- [Editing & Clipboard](./editing) -- edit, copy/paste, and fill cells
+- [Row Selection](./row-selection) -- select entire rows instead of cells

package/bundled-docs/features/status-bar.mdx

@@ -0,0 +1,205 @@
+---
+sidebar_position: 14
+title: Status Bar
+description: Row counts, selection counts, and numeric aggregations at the bottom of the grid
+---
+
+
+# Status Bar
+
+The status bar sits at the bottom of the grid and displays row counts, filter counts, selection counts, and numeric aggregations for selected cell ranges.
+
+## Live Demo
+
+<StatusBarDemo />
+
+:::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}
+      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
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `<ogrid [props]="gridProps" />`
+})
+export class GridComponent {
+  gridProps = {
+    columns: columns,
+    data: data,
+    getRowId: (r: Row) => r.id,
+    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,
+  data,
+  getRowId: (r) => r.id,
+  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: columns,
+  data: data,
+  getRowId: (r) => r.id,
+  statusBar: true,
+});
+```
+
+  </TabItem>
+</Tabs>
+
+Set `statusBar={true}` and the bar appears at the bottom showing "Rows: 150".
+
+## How It Works
+
+The status bar dynamically shows information based on the current grid state.
+
+### Basic Row Count
+
+With `statusBar={true}`, the bar always shows the total row count.
+
+```
+Rows: 150
+```
+
+### Filtered Count
+
+When filters are active and reduce the displayed rows, a "Filtered" count appears alongside the total.
+
+```
+Rows: 150  |  Filtered: 42
+```
+
+### Selected Row Count
+
+When row selection is enabled and the user selects rows, a "Selected" count appears.
+
+```
+Rows: 150  |  Selected: 5
+```
+
+### Cell Aggregations
+
+When the user selects a range of cells that includes numeric values, the status bar shows aggregation values: Sum, Avg, Min, Max, and Count.
+
+```
+Rows: 150  |  Cells: 12  |  Sum: 4800  |  Avg: 400  |  Min: 150  |  Max: 900  |  Count: 12
+```
+
+Aggregations:
+- Only appear when 2 or more cells are selected.
+- Only include cells with numeric values.
+- `Avg` is rounded to 2 decimal places.
+- Disappear when the selection is cleared.
+
+### Combining Indicators
+
+All indicators can appear simultaneously. The status bar shows whichever are relevant:
+
+```
+Rows: 1000  |  Filtered: 250  |  Selected: 3  |  Cells: 8  |  Sum: 12500  |  Avg: 1562.50  |  Min: 800  |  Max: 3200  |  Count: 8
+```
+
+## Advanced: Custom Status Bar Props
+
+For full control, pass an `IStatusBarProps` object instead of `true`.
+
+```tsx
+<OGrid
+  columns={columns}
+  data={data}
+  getRowId={(r) => r.id}
+  statusBar={{
+    totalCount: data.length,
+    filteredCount: filteredData.length,
+    selectedCount: selectedRows.size,
+    panels: ['rowCount', 'filteredRowCount', 'selectedRowCount'],
+  }}
+/>
+```
+
+## Props Reference
+
+| Type | Field | Description |
+|---|---|---|
+| `IOGridProps<T>` | `statusBar` | `boolean` or `IStatusBarProps` |
+| `IStatusBarProps` | `totalCount` | Total number of rows (unfiltered) |
+| `IStatusBarProps` | `filteredCount` | Number of rows after filtering (omit to hide) |
+| `IStatusBarProps` | `selectedCount` | Number of selected rows (omit or 0 to hide) |
+| `IStatusBarProps` | `panels` | Array of panel IDs to show: `'rowCount'`, `'filteredRowCount'`, `'selectedRowCount'` |
+| `IStatusBarProps` | `aggregation` | `{ sum, avg, min, max, count } \| null` for selected numeric cells |
+
+## Related
+
+- [CSV Export](./csv-export) -- export the data behind the counts
+- [Server-Side Data](./server-side-data) -- status bar works with server-side `totalCount`
+- [Keyboard Navigation](./keyboard-navigation) -- Shift+Arrow to select cell ranges for aggregation