@alaarab/ogrid-mcp 2.4.0

package/bundled-docs/guides/mcp.mdx

@@ -0,0 +1,172 @@
+---
+title: AI Integration (MCP)
+description: Connect Claude, Cursor, and other AI assistants to OGrid documentation and your running grid.
+sidebar_position: 1
+---
+
+# AI Integration (MCP)
+
+`@alaarab/ogrid-mcp` is a standalone [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that gives AI assistants full access to OGrid documentation across all frameworks. It also includes a **live testing bridge** that lets the AI read and control a running OGrid instance in real time.
+
+## Installation
+
+The MCP server is published as `@alaarab/ogrid-mcp` and requires no configuration — docs are bundled into the package.
+
+```bash
+npm install -g @alaarab/ogrid-mcp
+# or use npx directly (no install needed)
+npx @alaarab/ogrid-mcp
+```
+
+---
+
+## Connect to your AI assistant
+
+### Claude Code
+
+```bash
+claude mcp add ogrid -- npx -y @alaarab/ogrid-mcp
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "ogrid": {
+      "command": "npx",
+      "args": ["-y", "@alaarab/ogrid-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings:
+
+```json
+{
+  "ogrid": {
+    "command": "npx",
+    "args": ["-y", "@alaarab/ogrid-mcp"]
+  }
+}
+```
+
+---
+
+## What your AI can do
+
+Once connected, the AI assistant has access to the full OGrid documentation for all frameworks. Example prompts:
+
+```
+Show me how to set up server-side pagination in React
+How do I pin columns in Angular Material?
+What's the difference between multiSelect and text filters?
+How do I use the formula engine?
+Help me migrate from AG Grid to OGrid
+```
+
+---
+
+## MCP tools
+
+### `search_docs`
+
+Full-text search across all OGrid documentation.
+
+```
+search_docs query="server-side data" framework="react"
+```
+
+Parameters:
+- `query` (required) — search terms
+- `framework` (optional) — filter to `react`, `angular`, `vue`, or `js`
+- `category` (optional) — filter to `features`, `getting-started`, `guides`, or `api`
+
+### `list_docs`
+
+Browse available documentation pages by category.
+
+```
+list_docs category="features"
+```
+
+### `get_docs`
+
+Read a full documentation page by path.
+
+```
+get_docs path="features/filtering"
+```
+
+### `get_code_example`
+
+Extract code snippets from a documentation page, optionally filtered by framework.
+
+```
+get_code_example path="features/editing" framework="angular"
+```
+
+### `detect_version`
+
+Detect which OGrid packages are installed in the user's project by reading their `package.json`.
+
+```
+detect_version path="/path/to/project"
+```
+
+---
+
+## MCP resources
+
+Resources can be read directly by the AI assistant without calling a tool.
+
+| Resource | Description |
+|----------|-------------|
+| `ogrid://quick-reference` | Key API overview — props, column definitions, IOGridApi, filter types |
+| `ogrid://docs/{path}` | Any documentation page by path (e.g. `ogrid://docs/features/filtering`) |
+| `ogrid://migration-guide` | Step-by-step guide for migrating from AG Grid to OGrid |
+
+---
+
+## MCP prompts
+
+### `migrate-from-ag-grid`
+
+Guides the AI through an AG Grid → OGrid migration. Provide your existing AG Grid code and the AI will produce equivalent OGrid code with explanations.
+
+---
+
+## Live testing bridge
+
+For real-time AI-assisted development, the MCP server includes a bridge that connects to a running OGrid instance. This lets the AI:
+
+- Read the current grid state (rows, columns, pagination, filters, sort)
+- Update cell values
+- Apply or clear filters
+- Change sort order
+- Navigate pages
+
+See the **[MCP Live Testing Bridge](./mcp-live-testing)** guide for full setup instructions.
+
+```bash
+# Start with bridge enabled
+npx @alaarab/ogrid-mcp --bridge
+
+# Or with a custom port
+OGRID_BRIDGE_PORT=7890 npx @alaarab/ogrid-mcp
+```
+
+---
+
+## Version
+
+The MCP server is published separately from the grid packages and versioned independently. Check the installed version:
+
+```bash
+npx @alaarab/ogrid-mcp --version
+```

package/bundled-docs/guides/migration-from-ag-grid.mdx

@@ -0,0 +1,223 @@
+---
+sidebar_position: 4
+title: Migration from AG Grid
+description: Side-by-side mapping from AG Grid to OGrid with equivalent APIs, props, and features.
+---
+
+# Migration from AG Grid
+
+AG Grid is the industry standard for React data grids -- but its most useful features (range selection, clipboard, context menu, fill handle, status bar) are locked behind a $999/developer/year enterprise license. OGrid delivers all of these features under the MIT license, with zero cost, a smaller bundle, and a more React-idiomatic API.
+
+This guide maps every major AG Grid concept to its OGrid equivalent, so you can migrate systematically.
+
+## Installation
+
+```bash
+# Remove AG Grid
+npm uninstall ag-grid-react ag-grid-community ag-grid-enterprise
+
+# Install OGrid (pick your UI framework)
+npm install @alaarab/ogrid-react-radix          # Radix (lightweight, no framework dep)
+npm install @alaarab/ogrid-react-fluent   # Fluent UI v9
+npm install @alaarab/ogrid-react-material # Material UI v7
+```
+
+## Component Mapping
+
+AG Grid uses a single `<AgGridReact>` component. OGrid uses `<OGrid>` with the same pattern:
+
+```tsx
+// AG Grid
+
+<AgGridReact
+  columnDefs={columnDefs}
+  rowData={rowData}
+  getRowId={(params) => params.data.id}
+/>
+
+// OGrid
+
+<OGrid
+  columns={columns}
+  data={data}
+  getRowId={(item) => item.id}
+/>
+```
+
+## Column Definition Mapping
+
+| AG Grid (`colDef`) | OGrid (`IColumnDef`) | Notes |
+|---|---|---|
+| `field` | `columnId` | OGrid uses `columnId` as both the field key and unique identifier |
+| `headerName` | `name` | Display name in the column header |
+| `sortable: true` | `sortable: true` | Identical |
+| `filter: true` | `filterable: { type: 'text' }` | OGrid uses a typed filter config object |
+| `filter: 'agSetColumnFilter'` | `filterable: { type: 'multiSelect' }` | Multi-select filter with checkboxes |
+| `cellRenderer` | `renderCell` | `(item) => ReactNode` instead of `(params) => ReactNode` |
+| `valueGetter` | `valueGetter` | `(item) => unknown` instead of `(params) => unknown` |
+| `valueFormatter` | `valueFormatter` | `(value, item) => string` instead of `(params) => string` |
+| `editable: true` | `editable: true` | Also supports `(item) => boolean` for per-row |
+| `cellEditor: 'agSelectCellEditor'` | `cellEditor: 'select'` | Built-in select editor |
+| `cellEditor: 'agRichSelectCellEditor'` | `cellEditor: 'richSelect'` | Searchable dropdown |
+| `cellEditorParams` | `cellEditorParams` | Same concept -- `{ values: [...] }` |
+| `cellEditorPopup: true` | `cellEditorPopup: true` | Identical |
+| `pinned: 'left'` | `pinned: 'left'` | Also supports `'right'` |
+| `width` | `defaultWidth` | Initial column width |
+| `minWidth` | `minWidth` | Minimum column width |
+| `hide: true` | `defaultVisible: false` | Column hidden by default |
+| `cellStyle` | `cellStyle` | Static object or `(item) => CSSProperties` |
+
+### Column Definition Example
+
+```tsx
+// AG Grid
+const columnDefs = [
+  { field: 'name', headerName: 'Name', sortable: true, filter: true },
+  { field: 'status', headerName: 'Status', filter: 'agSetColumnFilter',
+    cellEditor: 'agSelectCellEditor', editable: true,
+    cellEditorParams: { values: ['Active', 'Inactive'] } },
+  { field: 'amount', headerName: 'Amount', valueFormatter: (p) => `$${p.value}` },
+];
+
+// OGrid
+const columns = [
+  { columnId: 'name', name: 'Name', sortable: true, filterable: { type: 'text' } },
+  { columnId: 'status', name: 'Status', filterable: { type: 'multiSelect' },
+    cellEditor: 'select', editable: true,
+    cellEditorParams: { values: ['Active', 'Inactive'] } },
+  { columnId: 'amount', name: 'Amount', type: 'numeric',
+    valueFormatter: (value) => `$${value}` },
+];
+```
+
+## Grid Options Mapping
+
+| AG Grid (`gridOptions`) | OGrid (`IOGridProps`) | Notes |
+|---|---|---|
+| `pagination: true` | Built-in, always available | Pagination is always included |
+| `paginationPageSize: 25` | `defaultPageSize={25}` | Or controlled: `pageSize` + `onPageSizeChange` |
+| `rowSelection: 'multiple'` | `rowSelection="multiple"` | Also `'single'` or `'none'` |
+| `suppressRowClickSelection` | -- | OGrid uses checkbox column for selection |
+| `rowData` | `data` | Client-side data array |
+| `datasource` / `serverSideDatasource` | `dataSource` | `IDataSource<T>` with `fetchPage()` |
+| `onSortChanged` | `onSortChange` | Controlled sort callback |
+| `onFilterChanged` | `onFiltersChange` | Controlled filter callback |
+| `onCellValueChanged` | `onCellValueChanged` | Same concept, different event shape |
+| `defaultColDef.editable` | `editable` | Grid-level toggle |
+| `statusBar` | `statusBar` | `true` or `IStatusBarProps` |
+| `sideBar` | `sideBar` | `true` or `ISideBarDef` |
+| `domLayout: 'autoHeight'` | `layoutMode="content"` | Grid sizes to content |
+
+## API Mapping
+
+AG Grid exposes an imperative API via `gridApi`. OGrid uses a ref:
+
+```tsx
+// AG Grid
+const gridRef = useRef();
+gridRef.current.api.setRowData(newData);
+gridRef.current.api.getSelectedRows();
+gridRef.current.api.exportDataAsCsv();
+
+// OGrid
+
+const gridRef = useRef<IOGridApi<MyRow>>(null);
+gridRef.current?.setRowData(newData);
+gridRef.current?.getSelectedRows();
+exportToCsv(items, columns); // standalone utility function
+```
+
+| AG Grid API | OGrid API | Notes |
+|---|---|---|
+| `api.setRowData(data)` | `gridRef.current.setRowData(data)` | Client-side only |
+| `api.getSelectedRows()` | `gridRef.current.getSelectedRows()` | Returns `RowId[]` |
+| `api.selectAll()` | `gridRef.current.selectAll()` | Select all rows |
+| `api.deselectAll()` | `gridRef.current.deselectAll()` | Deselect all rows |
+| `api.setFilterModel(model)` | `gridRef.current.setFilterModel(filters)` | Uses `IFilters` type |
+| `api.exportDataAsCsv()` | `exportToCsv(items, columns)` | Standalone utility, not on ref |
+| `api.getColumnState()` | `gridRef.current.getColumnState()` | Returns `IGridColumnState` |
+| `api.applyColumnState(state)` | `gridRef.current.applyColumnState(state)` | Bulk restore |
+| `api.setLoading(true)` | `gridRef.current.setLoading(true)` | Show loading overlay |
+
+## Enterprise Features -- Now Free
+
+These features require an AG Grid Enterprise license ($999/dev/year). In OGrid, they are all included for free under the MIT license.
+
+| Feature | AG Grid | OGrid |
+|---------|---------|-------|
+| Cell Range Selection | Enterprise | `cellSelection` (default `true`) |
+| Clipboard (Copy/Paste) | Enterprise | Built-in (Ctrl+C / Ctrl+V) |
+| Fill Handle | Enterprise | Built-in (drag corner of selection) |
+| Context Menu | Enterprise | Built-in (right-click any cell) |
+| Status Bar | Enterprise | `statusBar={true}` |
+| Column State Persistence | Enterprise | `getColumnState()` / `applyColumnState()` |
+| Undo/Redo | Enterprise | Built-in (Ctrl+Z / Ctrl+Y) |
+| Rich Select Editor | Enterprise | `cellEditor: 'richSelect'` |
+
+## Server-Side Data Source
+
+```tsx
+// AG Grid (server-side row model)
+const datasource = {
+  getRows: (params) => {
+    fetch(`/api/data?start=${params.request.startRow}`)
+      .then(res => res.json())
+      .then(data => params.success({ rowData: data.rows, rowCount: data.total }));
+  }
+};
+
+// OGrid
+const dataSource: IDataSource<MyRow> = {
+  fetchPage: async ({ page, pageSize, sort, filters }) => {
+    const res = await fetch(
+      `/api/data?page=${page}&size=${pageSize}&sort=${sort?.field}&dir=${sort?.direction}`
+    );
+    const json = await res.json();
+    return { items: json.rows, totalCount: json.total };
+  },
+};
+
+<OGrid columns={columns} dataSource={dataSource} getRowId={(item) => item.id} />
+```
+
+## Column Groups
+
+```tsx
+// AG Grid
+const columnDefs = [
+  {
+    headerName: 'Contact Info',
+    children: [
+      { field: 'email', headerName: 'Email' },
+      { field: 'phone', headerName: 'Phone' },
+    ],
+  },
+];
+
+// OGrid
+const columns = [
+  {
+    headerName: 'Contact Info',
+    children: [
+      { columnId: 'email', name: 'Email' },
+      { columnId: 'phone', name: 'Phone' },
+    ],
+  },
+];
+```
+
+Column groups in OGrid render as multi-row headers, exactly like AG Grid.
+
+## Step-by-Step Migration
+
+1. **Install OGrid** and remove AG Grid packages.
+2. **Rename column definitions:** `field` to `columnId`, `headerName` to `name`, `cellRenderer` to `renderCell`, `filter: true` to `filterable: { type: 'text' }`.
+3. **Replace `<AgGridReact>`** with `<OGrid>`. Rename `rowData` to `data`, `columnDefs` to `columns`.
+4. **Update API usage:** Replace `gridRef.current.api.*` with `gridRef.current.*`. Move `exportDataAsCsv` to the standalone `exportToCsv` function.
+5. **Remove Enterprise license.** Delete AG Grid license keys and `LicenseManager.setLicenseKey()` calls.
+6. **Remove AG Grid CSS imports.** OGrid handles its own styling through your UI framework's theme.
+7. **Test.** OGrid's API is intentionally similar to AG Grid's, so most migrations are mechanical find-and-replace operations.
+
+:::tip
+OGrid works with the same React patterns as AG Grid (controlled/uncontrolled state, refs for imperative API, column definitions as plain objects). The migration is primarily a prop rename exercise, not an architecture change.
+:::

package/bundled-docs/guides/theming.mdx

@@ -0,0 +1,211 @@
+---
+sidebar_position: 3
+title: Theming & CSS Variables
+description: Customize OGrid's appearance with CSS variables, framework themes, and per-cell styles.
+---
+
+# Theming & CSS Variables
+
+OGrid is designed to inherit your application's design system. Each UI package integrates with its framework's theming mechanism, and the core grid exposes CSS variables and props for fine-grained control.
+
+## CSS Variables
+
+OGrid exposes CSS custom properties that you can override to change the grid's appearance globally or per-instance.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--ogrid-selection` | `#217346` | Cell selection highlight color (active cell border, range background) |
+
+Override globally:
+
+```css
+:root {
+  --ogrid-selection: #0066cc;
+}
+```
+
+Or scope it to a specific grid instance using the `className` prop:
+
+```css
+.my-grid {
+  --ogrid-selection: #8b5cf6;
+}
+```
+
+```tsx
+<OGrid className="my-grid" columns={columns} data={data} getRowId={(item) => item.id} />
+```
+
+## Framework Theming
+
+Each UI package inherits styles from its framework's theme system. OGrid does not fight your theme -- it builds on top of it.
+
+### Radix UI (`@alaarab/ogrid-react-radix`)
+
+Radix is the lightest implementation. It uses CSS Modules (`.module.scss`) for all grid styles. Override styles with standard CSS specificity or by targeting the grid's class names.
+
+### Fluent UI (`@alaarab/ogrid-react-fluent`)
+
+The Fluent implementation renders with Fluent UI v9 components, which inherit from `FluentProvider`. Wrap your app in a `FluentProvider` with your theme:
+
+```tsx
+
+function App() {
+  return (
+    <FluentProvider theme={webLightTheme}>
+      <OGrid columns={columns} data={data} getRowId={(item) => item.id} />
+    </FluentProvider>
+  );
+}
+```
+
+Fluent also uses CSS Modules for grid-specific styles (cell selection, fill handle, etc.).
+
+### Material UI (`@alaarab/ogrid-react-material`)
+
+The Material implementation renders with MUI v7 components, which inherit from `ThemeProvider`. Wrap your app in a `ThemeProvider` with your theme:
+
+```tsx
+
+const theme = createTheme({
+  palette: {
+    primary: { main: '#1976d2' },
+  },
+});
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <OGrid columns={columns} data={data} getRowId={(item) => item.id} />
+    </ThemeProvider>
+  );
+}
+```
+
+Material uses CSS-in-JS (inline styles) for grid-specific styling rather than CSS Modules.
+
+## Layout Mode
+
+The `layoutMode` prop controls how the grid sizes itself:
+
+| Mode | Behavior |
+|------|----------|
+| `'fill'` (default) | Grid stretches to fill its parent container. The parent must have a defined height. |
+| `'content'` | Grid sizes itself based on content. Width fits columns; height fits rows. |
+
+```tsx
+{/* Fill parent container */}
+<div style={{ height: 600 }}>
+  <OGrid layoutMode="fill" columns={columns} data={data} getRowId={(item) => item.id} />
+</div>
+
+{/* Size to content */}
+<OGrid layoutMode="content" columns={columns} data={data} getRowId={(item) => item.id} />
+```
+
+:::tip
+When using `layoutMode="fill"`, make sure the grid's parent has a defined height (explicit px/vh/%, or flex layout). Without it, the grid will collapse to zero height.
+:::
+
+## Suppress Horizontal Scroll
+
+To prevent horizontal scrolling (useful when all columns fit the viewport), set `suppressHorizontalScroll`:
+
+```tsx
+<OGrid suppressHorizontalScroll columns={columns} data={data} getRowId={(item) => item.id} />
+```
+
+This sets `overflow-x: hidden` on the grid's scroll container.
+
+## Per-Cell Styles
+
+Use `cellStyle` on a column definition to apply inline styles to individual cells. It accepts a static style object or a function for conditional styling:
+
+### Static Style
+
+```tsx
+const columns = [
+  {
+    columnId: 'amount',
+    name: 'Amount',
+    type: 'numeric' as const,
+    cellStyle: { fontWeight: 600 },
+  },
+];
+```
+
+### Dynamic Style (Per-Row)
+
+```tsx
+const columns = [
+  {
+    columnId: 'status',
+    name: 'Status',
+    cellStyle: (item) => ({
+      color: item.status === 'Active' ? '#16a34a' : '#dc2626',
+      fontWeight: 600,
+    }),
+  },
+];
+```
+
+## Numeric Column Alignment
+
+Set `type: 'numeric'` on a column to right-align cell content automatically:
+
+```tsx
+{
+  columnId: 'price',
+  name: 'Price',
+  type: 'numeric',
+  valueFormatter: (value) => `$${Number(value).toFixed(2)}`,
+}
+```
+
+## Custom Wrapper Class
+
+The `className` prop adds a CSS class to the grid's outermost wrapper element. Use it for scoped styling:
+
+```tsx
+<OGrid className="dashboard-grid" columns={columns} data={data} getRowId={(item) => item.id} />
+```
+
+```css
+.dashboard-grid {
+  border: 1px solid #e5e7eb;
+  border-radius: 8px;
+  overflow: hidden;
+}
+```
+
+## Column Width Control
+
+Control column widths through the column definition:
+
+| Prop | Description |
+|------|-------------|
+| `minWidth` | Minimum column width in pixels |
+| `defaultWidth` | Initial column width in pixels |
+| `idealWidth` | Preferred width (used for auto-sizing) |
+
+```tsx
+{
+  columnId: 'description',
+  name: 'Description',
+  minWidth: 150,
+  defaultWidth: 300,
+}
+```
+
+Users can resize columns by dragging the column border. Listen for resize events with `onColumnResized`:
+
+```tsx
+<OGrid
+  columns={columns}
+  data={data}
+  getRowId={(item) => item.id}
+  onColumnResized={(columnId, width) => {
+    localStorage.setItem(`col-width-${columnId}`, String(width));
+  }}
+/>
+```

package/dist/esm/bridge-client.d.ts

@@ -0,0 +1,87 @@
+/**
+ * OGrid MCP Bridge Client
+ *
+ * Include this in your dev app to connect a running OGrid instance to the
+ * MCP bridge server, enabling AI assistants (Claude, Cursor, etc.) to read
+ * grid state and send test commands in real time.
+ *
+ * Usage (React):
+ *   import { connectGridToBridge } from '@alaarab/ogrid-mcp/bridge-client';
+ *
+ *   useEffect(() => {
+ *     const bridge = connectGridToBridge({
+ *       gridId: 'my-grid',
+ *       getData: () => filteredRows,       // current displayed data
+ *       getColumns: () => columns,
+ *       api: gridApiRef.current,           // IOGridApi (for filter/sort/page commands)
+ *       onCellUpdate: (rowIndex, columnId, value) => {
+ *         setData(prev => prev.map((row, i) =>
+ *           i === rowIndex ? { ...row, [columnId]: value } : row
+ *         ));
+ *       },
+ *     });
+ *     return () => bridge.disconnect();
+ *   }, []);
+ *
+ * This module contains NO Node.js-specific imports — safe to bundle in browsers.
+ */
+interface BridgeColumnInfo {
+    columnId: string;
+    headerName?: string;
+    type?: string;
+}
+interface BridgeCommand {
+    id: string;
+    type: 'update_cell' | 'set_filter' | 'clear_filters' | 'set_sort' | 'go_to_page';
+    payload: Record<string, unknown>;
+}
+/** Minimal subset of IOGridApi used by the bridge. */
+interface BridgeGridApi {
+    updateSort?: (model: Array<{
+        columnId: string;
+        direction: 'asc' | 'desc';
+    }>) => void;
+    updateFilter?: (columnId: string, value: unknown) => void;
+    clearFilters?: () => void;
+    goToPage?: (page: number) => void;
+    getSelectedRows?: () => unknown[];
+}
+interface ConnectGridOptions {
+    /** Unique identifier for this grid instance (shown in list_grids). */
+    gridId: string;
+    /** Returns the currently displayed rows. Called on every state push. */
+    getData: () => unknown[];
+    /** Returns the current column definitions. */
+    getColumns: () => BridgeColumnInfo[];
+    /** Current pagination state. */
+    getPagination?: () => {
+        page: number;
+        pageSize: number;
+        totalCount: number;
+        pageCount: number;
+    };
+    /** Returns the current sort model. Called on every state push. */
+    getSort?: () => Array<{
+        columnId: string;
+        direction: 'asc' | 'desc';
+    }>;
+    /** Returns the current filter model. Called on every state push. */
+    getFilters?: () => Record<string, unknown>;
+    /** IOGridApi reference for filter/sort/page commands. */
+    api?: BridgeGridApi;
+    /** Called when the AI sends an update_cell command. */
+    onCellUpdate?: (rowIndex: number, columnId: string, value: unknown) => void;
+    /** Bridge server URL (default: http://localhost:7890). */
+    bridgeUrl?: string;
+    /** How often to push state and poll commands (ms, default: 500). */
+    pollIntervalMs?: number;
+}
+interface BridgeConnection {
+    /** Stop polling and disconnect. */
+    disconnect: () => void;
+    /** Manually push current state immediately. */
+    push: () => Promise<void>;
+}
+declare function connectGridToBridge(options: ConnectGridOptions): BridgeConnection;
+
+export { type BridgeColumnInfo, type BridgeCommand, type BridgeConnection, type BridgeGridApi, type ConnectGridOptions, connectGridToBridge };