@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/guides/custom-cell-editors.mdx

@@ -0,0 +1,201 @@
+---
+sidebar_position: 2
+title: Custom Cell Editors
+description: Build custom inline and popup cell editors for OGrid columns.
+---
+
+# Custom Cell Editors
+
+OGrid includes built-in editors for common types (`text`, `select`, `checkbox`, `richSelect`, `date`), but you can create fully custom editors for any use case. A custom editor is a React component that receives the cell value, update callbacks, and optional params.
+
+## The ICellEditorProps Interface
+
+Every custom editor receives these props:
+
+```tsx
+interface ICellEditorProps<T> {
+  value: unknown;                           // Current cell value
+  onValueChange: (value: unknown) => void;  // Update the value as user types
+  onCommit: () => void;                     // Save and close
+  onCancel: () => void;                     // Discard and close
+  item: T;                                  // The full row data
+  column: IColumnDef<T>;                    // The column definition
+  cellEditorParams?: CellEditorParams;      // Extra config from the column def
+}
+```
+
+## Popup Editor Example
+
+A popup editor renders in a floating overlay above the cell. This is ideal for editors that need more space than an inline cell -- like a textarea, a date picker, or a color picker.
+
+### Step 1: Create the Editor Component
+
+```tsx
+
+interface NoteItem {
+  id: string;
+  title: string;
+  notes: string;
+}
+
+function NotesEditor({ value, onValueChange, onCommit, onCancel }: ICellEditorProps<NoteItem>) {
+  return (
+    <div style={{ padding: 12, width: 300 }}>
+      <textarea
+        autoFocus
+        rows={5}
+        value={String(value ?? '')}
+        onChange={(e) => onValueChange(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === 'Escape') onCancel();
+        }}
+        style={{ width: '100%', resize: 'vertical', fontFamily: 'inherit', fontSize: 14 }}
+      />
+      <div style={{ display: 'flex', gap: 8, marginTop: 8, justifyContent: 'flex-end' }}>
+        <button onClick={onCancel}>Cancel</button>
+        <button onClick={onCommit}>Save</button>
+      </div>
+    </div>
+  );
+}
+```
+
+### Step 2: Wire It Up in the Column Definition
+
+Set `cellEditor` to your component and `cellEditorPopup: true` to render it in a floating overlay:
+
+```tsx
+
+const columns: IColumnDef<NoteItem>[] = [
+  { columnId: 'title', name: 'Title', editable: true },
+  {
+    columnId: 'notes',
+    name: 'Notes',
+    editable: true,
+    cellEditor: NotesEditor,
+    cellEditorPopup: true,
+  },
+];
+```
+
+### Step 3: Enable Editing on the Grid
+
+```tsx
+<OGrid
+  columns={columns}
+  data={items}
+  getRowId={(item) => item.id}
+  editable
+  onCellValueChanged={(event) => {
+    console.log(`${event.columnId} changed from`, event.oldValue, 'to', event.newValue);
+  }}
+/>
+```
+
+When a user double-clicks the Notes cell (or presses Enter on it), the `NotesEditor` appears in a popup. Clicking Save calls `onCommit`, which writes the value back to the grid and fires `onCellValueChanged`.
+
+## Inline Editor Example
+
+Without `cellEditorPopup`, the editor replaces the cell content inline. This is the default behavior and works well for small inputs:
+
+```tsx
+function ColorEditor({ value, onValueChange, onCommit, onCancel }: ICellEditorProps<any>) {
+  return (
+    <input
+      type="color"
+      autoFocus
+      value={String(value ?? '#000000')}
+      onChange={(e) => onValueChange(e.target.value)}
+      onBlur={onCommit}
+      onKeyDown={(e) => {
+        if (e.key === 'Escape') onCancel();
+        if (e.key === 'Enter') onCommit();
+      }}
+    />
+  );
+}
+
+const columns = [
+  {
+    columnId: 'color',
+    name: 'Color',
+    editable: true,
+    cellEditor: ColorEditor,
+    // No cellEditorPopup -- renders inline
+  },
+];
+```
+
+## Using cellEditorParams
+
+Pass extra configuration to your editor through `cellEditorParams`. This keeps your editor component reusable across columns:
+
+```tsx
+function RatingEditor({ value, onValueChange, onCommit, cellEditorParams }: ICellEditorProps<any>) {
+  const maxStars = (cellEditorParams?.maxStars as number) ?? 5;
+
+  return (
+    <div style={{ display: 'flex', gap: 4 }}>
+      {Array.from({ length: maxStars }, (_, i) => (
+        <button
+          key={i}
+          onClick={() => {
+            onValueChange(i + 1);
+            // Auto-commit after selection
+            setTimeout(onCommit, 0);
+          }}
+          style={{
+            background: 'none',
+            border: 'none',
+            cursor: 'pointer',
+            fontSize: 18,
+            opacity: (value as number) >= i + 1 ? 1 : 0.3,
+          }}
+        >
+          *
+        </button>
+      ))}
+    </div>
+  );
+}
+
+const columns = [
+  {
+    columnId: 'rating',
+    name: 'Rating',
+    editable: true,
+    cellEditor: RatingEditor,
+    cellEditorParams: { maxStars: 10 },
+  },
+];
+```
+
+:::tip
+The `cellEditorParams` object is passed through as-is. You can put any serializable configuration there -- select options, validation rules, format strings, API endpoints, or anything your editor needs.
+:::
+
+## Built-in Editors
+
+Before building a custom editor, check if a built-in one fits your needs:
+
+| `cellEditor` | Description | `cellEditorParams` |
+|---|---|---|
+| `'text'` | Standard text input (default) | -- |
+| `'select'` | Dropdown select | `{ values: ['Option A', 'Option B'] }` |
+| `'checkbox'` | Boolean toggle | -- |
+| `'richSelect'` | Searchable dropdown with keyboard navigation | `{ values: [...], formatValue: (v) => string }` |
+| `'date'` | Native date picker (`<input type="date">`) | -- |
+
+## Conditional Editability
+
+Use a function for `editable` to control which rows allow editing:
+
+```tsx
+{
+  columnId: 'status',
+  name: 'Status',
+  editable: (item) => item.status !== 'locked',
+  cellEditor: 'select',
+  cellEditorParams: { values: ['Draft', 'Review', 'Published'] },
+}
+```

package/bundled-docs/guides/framework-showcase.mdx

@@ -0,0 +1,200 @@
+---
+sidebar_position: 5
+title: Framework Showcase
+description: See OGrid in action with React, Angular, Vue, and Vanilla JS — 8 UI implementations, one API
+---
+
+
+# Framework Showcase
+
+OGrid renders with your design system's native components. Same API, same features — different look and feel. Every grid below is **fully interactive**: sort, filter, edit, select cells, copy/paste, and undo/redo.
+
+---
+
+## React
+
+Three design-system implementations, all sharing the same hooks and headless logic from `@alaarab/ogrid-react`.
+
+### Radix UI <small>(Default)</small>
+
+The lightest option — Radix primitives are bundled with zero peer dependencies beyond React.
+
+```bash
+npm install @alaarab/ogrid-react-radix
+```
+
+<ShowcaseRadixDemo />
+
+### Fluent UI
+
+Microsoft's Fluent UI v9 components. Best for **Microsoft 365 and SharePoint** projects.
+
+```bash
+npm install @alaarab/ogrid-react-fluent @fluentui/react-components
+```
+
+<ShowcaseFluentDemo />
+
+### Material UI
+
+Google's Material Design via MUI v7. Best for apps already on **Material Design**.
+
+```bash
+npm install @alaarab/ogrid-react-material @mui/material @emotion/react @emotion/styled
+```
+
+<ShowcaseMaterialDemo />
+
+---
+
+## Angular
+
+Signals-based reactivity with standalone components. Zone-less by default, no NgModule boilerplate. All three packages share the same services from `@alaarab/ogrid-angular`.
+
+### Radix (Angular CDK) <small>(Default)</small>
+
+The lightest option — Angular CDK for overlays with zero heavy UI framework dependencies.
+
+```bash
+npm install @alaarab/ogrid-angular-radix @angular/cdk
+```
+
+```typescript
+
+@Component({
+  standalone: true,
+  imports: [OGridComponent],
+  template: `<ogrid [props]="gridProps" />`
+})
+export class GridComponent {
+  gridProps = { columns, data, getRowId: (row) => row.id, defaultPageSize: 10 };
+}
+```
+
+<div style={{ marginTop: '0.75rem' }}>
+</div>
+
+### Angular Material
+
+Angular Material v21 components. Best for projects already using **Material Design**.
+
+```bash
+npm install @alaarab/ogrid-angular-material @angular/material @angular/cdk
+```
+
+```typescript
+// Same API — just change the import
+```
+
+### PrimeNG
+
+PrimeNG v21 components for teams already using the PrimeFaces ecosystem.
+
+```bash
+npm install @alaarab/ogrid-angular-primeng primeng
+```
+
+```typescript
+// Same API — just change the import
+```
+
+---
+
+## Vue
+
+Composition API composables using `ref()` and `computed()`. All three packages share the same composables from `@alaarab/ogrid-vue`.
+
+### Radix (Headless UI) <small>(Default)</small>
+
+The lightest option — Headless UI Vue components are bundled with zero peer dependencies beyond Vue.
+
+```bash
+npm install @alaarab/ogrid-vue-radix
+```
+
+```vue
+<script setup lang="ts">
+
+const gridProps = { columns, data, getRowId: (row) => row.id, defaultPageSize: 10 };
+</script>
+
+<template>
+  <OGrid :gridProps="gridProps" />
+</template>
+```
+
+<div style={{ marginTop: '0.75rem' }}>
+</div>
+
+### Vuetify
+
+Vuetify 3 components. Best for projects already using **Vuetify and Material Design**.
+
+```bash
+npm install @alaarab/ogrid-vue-vuetify vuetify
+```
+
+```vue
+<script setup lang="ts">
+// Same API — just change the import
+</script>
+```
+
+### PrimeVue
+
+PrimeVue 4 components for teams already using the PrimeFaces ecosystem.
+
+```bash
+npm install @alaarab/ogrid-vue-primevue primevue
+```
+
+```vue
+<script setup lang="ts">
+// Same API — just change the import
+</script>
+```
+
+---
+
+## Vanilla JS / TypeScript
+
+No framework, no virtual DOM. A class-based imperative API that renders directly to the DOM with a built-in CSS theme supporting light and dark mode.
+
+```bash
+npm install @alaarab/ogrid-js
+```
+
+<VanillaJSDemo />
+
+---
+
+## At a Glance
+
+| Framework | Design Systems | Reactivity |
+|-----------|---------------|------------|
+| **React** 17–19 | Radix *(default, bundled)* · Fluent UI v9 · MUI v7 | Hooks |
+| **Angular** 21 | Radix (CDK) *(default)* · Angular Material · PrimeNG | Signals |
+| **Vue** 3.3+ | Radix (Headless UI) *(default, bundled)* · Vuetify 3 · PrimeVue 4 | Composition API |
+| **Vanilla JS/TS** | Built-in CSS theme *(zero deps)* | EventEmitter |
+
+All 10 packages share the same **headless core** (`@alaarab/ogrid-core`) and pass the same **2,135 tests**. Switching design systems is a matter of changing imports.
+
+## Choosing a Package
+
+- **Starting fresh with React?** → **Radix** — lightest weight, zero peer deps, full feature parity.
+- **Microsoft ecosystem?** → **Fluent** — native look in Teams, SharePoint, Outlook.
+- **Already using MUI?** → **Material** — matches your existing theme and components.
+- **Starting fresh with Angular?** → **Radix (CDK)** — lightest weight with Angular CDK for overlays.
+- **Already using Angular Material?** → **Angular Material** — matches your existing theme.
+- **Already using PrimeNG?** → **PrimeNG** — integrates with PrimeFaces ecosystem.
+- **Starting fresh with Vue?** → **Radix (Headless UI)** — lightest weight, zero peer deps, Composition API.
+- **Already using Vuetify?** → **Vuetify** — matches your existing theme and components.
+- **Already using PrimeVue?** → **PrimeVue** — integrates with PrimeFaces ecosystem.
+- **No framework?** → **Vanilla JS** — works anywhere, class-based API, CSS-only theming.
+
+## Related
+
+- [Installation](../getting-started/installation) — install instructions for all packages
+- [Quick Start](../getting-started/quick-start) — build your first grid
+- [Theming Guide](./theming) — customize colors and styling
+- [Vanilla JS Guide](../getting-started/vanilla-js) — full JS API documentation

package/bundled-docs/guides/mcp-live-testing.mdx

@@ -0,0 +1,291 @@
+---
+title: MCP Live Testing Bridge
+description: Connect AI assistants (Claude, Cursor) to a running OGrid instance for real-time testing and inspection.
+---
+
+
+# MCP Live Testing Bridge
+
+The `@alaarab/ogrid-mcp` package includes a **live testing bridge** that lets AI assistants connected via MCP read your grid's current state, update cell values, apply filters, and navigate pages — all in real time while your dev app is running.
+
+## How it works
+
+```
+Claude (MCP client)
+    │ MCP tools
+    ▼
+ogrid-mcp (stdio process + HTTP bridge on :7890)
+    │ HTTP polling every 500ms
+    ▼
+Your dev app (localhost:3001)
+    └── connectGridToBridge() — pushes state + handles commands
+```
+
+The bridge is **opt-in** and **dev-only** — it only runs when you explicitly start the MCP server with the `--bridge` flag or `OGRID_BRIDGE_PORT` env var.
+
+---
+
+## Quick start
+
+### 1. Start the MCP server with bridge enabled
+
+```bash
+# Option A: use --bridge flag (port 7890)
+npx @alaarab/ogrid-mcp --bridge
+
+# Option B: use env var (custom port)
+OGRID_BRIDGE_PORT=7890 npx @alaarab/ogrid-mcp
+
+# Claude Desktop / claude mcp add
+claude mcp add ogrid -- npx -y @alaarab/ogrid-mcp --bridge
+```
+
+### 2. Connect your dev app
+
+<Tabs groupId="framework">
+<TabItem value="react" label="React">
+
+```tsx
+
+export function MyGrid() {
+  const [data, setData] = useState(myRows);
+  const apiRef = useRef<IOGridApi | null>(null);
+
+  useEffect(() => {
+    // Only connect in development
+    if (process.env.NODE_ENV !== 'development') return;
+
+    const bridge = connectGridToBridge({
+      gridId: 'my-grid',
+      getData: () => data,
+      getColumns: () => columns,
+      api: apiRef.current ?? undefined,
+      // Handle update_cell commands from Claude
+      onCellUpdate: (rowIndex, columnId, value) => {
+        setData(prev =>
+          prev.map((row, i) => i === rowIndex ? { ...row, [columnId]: value } : row)
+        );
+      },
+    });
+
+    return () => bridge.disconnect();
+  }, [data]);
+
+  return <OGrid ref={apiRef} data={data} columns={columns} />;
+}
+```
+
+</TabItem>
+<TabItem value="angular" label="Angular">
+
+```typescript
+
+@Component({ /* ... */ })
+export class MyGridComponent implements OnInit, OnDestroy {
+  data = myRows;
+  columns = myColumns;
+  service = new OGridService();
+  private bridge?: BridgeConnection;
+
+  ngOnInit() {
+    if (!isDevMode()) return;
+    this.bridge = connectGridToBridge({
+      gridId: 'my-grid',
+      getData: () => this.data,
+      getColumns: () => this.columns,
+      onCellUpdate: (rowIndex, columnId, value) => {
+        this.data = this.data.map((row, i) =>
+          i === rowIndex ? { ...row, [columnId]: value } : row
+        );
+      },
+    });
+  }
+
+  ngOnDestroy() {
+    this.bridge?.disconnect();
+  }
+}
+```
+
+</TabItem>
+<TabItem value="vue" label="Vue">
+
+```vue
+<script setup lang="ts">
+
+const data = ref(myRows);
+let bridge: ReturnType<typeof connectGridToBridge> | null = null;
+
+onMounted(() => {
+  if (import.meta.env.DEV) {
+    bridge = connectGridToBridge({
+      gridId: 'my-grid',
+      getData: () => data.value,
+      getColumns: () => columns,
+      onCellUpdate: (rowIndex, columnId, value) => {
+        data.value = data.value.map((row, i) =>
+          i === rowIndex ? { ...row, [columnId]: value } : row
+        );
+      },
+    });
+  }
+});
+
+onUnmounted(() => bridge?.disconnect());
+</script>
+```
+
+</TabItem>
+<TabItem value="js" label="Vanilla JS">
+
+```js
+
+const grid = new OGrid(container, { data: myRows, columns });
+
+// Only in development
+if (location.hostname === 'localhost') {
+  const bridge = connectGridToBridge({
+    gridId: 'my-grid',
+    getData: () => grid.getApi().getData(),
+    getColumns: () => columns,
+    onCellUpdate: (rowIndex, columnId, value) => {
+      // Update your data source and refresh
+      myRows[rowIndex][columnId] = value;
+      grid.getApi().refresh();
+    },
+  });
+}
+```
+
+</TabItem>
+</Tabs>
+
+---
+
+## MCP tools
+
+Once connected, these tools are available to your AI assistant:
+
+### `list_grids`
+
+Lists all OGrid instances currently connected to the bridge.
+
+```
+> list_grids
+
+2 connected grid(s):
+
+**my-grid**
+  Rows: 50 displayed / 1247 total
+  Page: 1 / 25 (50 per page)
+  Columns: id, name, email, department, salary
+  Active filters: 0
+  Last seen: 0s ago
+```
+
+### `get_grid_state`
+
+Returns the current state of a grid: columns, pagination, sort, filters, selection, and optionally the row data.
+
+```
+> get_grid_state gridId="my-grid" includeData=true maxRows=5
+
+# Grid: my-grid
+Last seen: 0s ago
+
+## Pagination
+Page 1 of 25 | 50 rows displayed | 1247 total
+
+## Columns (5)
+id (numeric), name (text), email (text), department (text), salary (numeric)
+
+## Sort
+salary desc
+
+## Data (first 5 of 50 rows)
+[
+  { "id": 1, "name": "Alice", "salary": 120000 },
+  ...
+]
+```
+
+### `send_grid_command`
+
+Sends a command to a connected grid and waits for the result.
+
+**Update a cell:**
+```
+> send_grid_command gridId="my-grid" type="update_cell"
+    payload={ "rowIndex": 0, "columnId": "salary", "value": 130000 }
+
+✅ Command executed successfully
+Type: update_cell
+Payload: {"rowIndex":0,"columnId":"salary","value":130000}
+```
+
+**Apply a filter:**
+```
+> send_grid_command gridId="my-grid" type="set_filter"
+    payload={ "columnId": "department", "value": "Engineering" }
+```
+
+**Clear all filters:**
+```
+> send_grid_command gridId="my-grid" type="clear_filters" payload={}
+```
+
+**Change sort:**
+```
+> send_grid_command gridId="my-grid" type="set_sort"
+    payload={ "sortModel": [{ "columnId": "name", "direction": "asc" }] }
+```
+
+**Navigate to page:**
+```
+> send_grid_command gridId="my-grid" type="go_to_page" payload={ "page": 3 }
+```
+
+---
+
+## connectGridToBridge() options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `gridId` | `string` | Unique ID shown in `list_grids` |
+| `getData` | `() => unknown[]` | Returns current displayed rows |
+| `getColumns` | `() => BridgeColumnInfo[]` | Returns current columns |
+| `getPagination` | `() => { page, pageSize, totalCount, pageCount }` | (optional) Pagination state |
+| `api` | `BridgeGridApi` | (optional) Grid API for filter/sort/page commands |
+| `onCellUpdate` | `(rowIndex, columnId, value) => void` | (optional) Handle `update_cell` commands |
+| `bridgeUrl` | `string` | Bridge URL (default: `http://localhost:7890`) |
+| `pollIntervalMs` | `number` | Poll frequency in ms (default: `500`) |
+
+---
+
+## Example AI testing session
+
+Here's what a typical Claude testing session looks like with the bridge active:
+
+```
+Me: The salary column seems wrong. Can you check?
+
+Claude: Let me look at the current grid state.
+[calls get_grid_state gridId="employees" includeData=true maxRows=10]
+
+The grid shows salary values like "120" instead of "120000".
+It looks like the values are being divided by 1000 somewhere.
+
+Let me update a cell to verify:
+[calls send_grid_command type="update_cell" payload={rowIndex:0, columnId:"salary", value:120000}]
+✅ Done. Now let me re-read to confirm:
+[calls get_grid_state]
+
+The update worked. Row 0 now shows 120000. The issue is in your
+valueGetter — it's dividing by 1000. Here's the fix: ...
+```
+
+---
+
+## Security note
+
+The bridge server only listens on `127.0.0.1` (localhost) and is designed for local development only. **Never run with `--bridge` in production.** The bridge has no authentication — anyone on localhost can read your grid data and send commands.