@alaarab/ogrid-mcp 2.4.0

package/README.md

@@ -0,0 +1,68 @@
+# @alaarab/ogrid-mcp
+
+MCP (Model Context Protocol) server for OGrid documentation. Lets AI assistants search and retrieve OGrid docs, code examples, and API references across all supported frameworks (React, Angular, Vue, vanilla JS).
+
+## Usage
+
+### Claude Desktop
+
+Add this to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "ogrid": {
+      "command": "npx",
+      "args": ["-y", "@alaarab/ogrid-mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add ogrid -- npx -y @alaarab/ogrid-mcp
+```
+
+### Direct execution
+
+```bash
+npx @alaarab/ogrid-mcp
+```
+
+## Tools
+
+The server exposes 5 tools:
+
+| Tool | Description |
+|------|-------------|
+| `search_docs` | Search OGrid documentation by keyword. Returns matching docs with title, description, and content excerpt. |
+| `list_docs` | List available documentation pages, optionally filtered by category (`features`, `getting-started`, `guides`, `api`). |
+| `get_docs` | Get the full content of a documentation page by its path. |
+| `get_code_example` | Find code examples matching a query, optionally filtered by framework (`react`, `angular`, `vue`, `js`). |
+| `detect_version` | Detect which OGrid version and framework is installed in the user's project by reading their package.json. |
+
+## Resources
+
+| URI | Description |
+|-----|-------------|
+| `ogrid://quick-reference` | Key props, install commands, and common patterns. |
+| `ogrid://migration-guide` | Full migration guide from AG Grid to OGrid with side-by-side API mapping. |
+| `ogrid://docs/{path}` | Any documentation page by path (e.g. `ogrid://docs/features/sorting`). |
+
+## Prompts
+
+| Name | Description |
+|------|-------------|
+| `migrate-from-ag-grid` | Step-by-step guide to migrate from AG Grid to OGrid. Returns the full migration guide with instructions for the AI to analyze your AG Grid usage and provide specific migration steps. |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OGRID_DOCS_PATH` | Absolute path to the docs directory containing `.mdx`/`.md` files. | `packages/docs/docs` relative to the package install location |
+
+## How it works
+
+On startup, the server indexes all `.mdx` and `.md` files from the docs directory. It parses frontmatter (title, description), extracts fenced code blocks with framework detection, and builds a searchable in-memory index. Search results are ranked by title match, description match, content density, and category relevance.

package/bundled-docs/api/README.md

@@ -0,0 +1,94 @@
+# API Reference
+
+Complete API documentation for OGrid components, types, and interfaces.
+
+## Components
+
+- **[DataGridTable](./components-datagrid-table.mdx)** — Core data grid component that renders the table, headers, rows, and cells
+- **[ColumnHeaderFilter](./components-column-header-filter.mdx)** — Column header with sorting and filtering UI (text, multi-select, people, date)
+- **[ColumnChooser](./components-column-chooser.mdx)** — Dropdown for showing/hiding columns
+- **[PaginationControls](./components-pagination-controls.mdx)** — Pagination UI with page navigation and page size selector
+- **[StatusBar](./components-status-bar.mdx)** — Status bar with row counts and cell aggregations
+- **[SideBar](./components-sidebar.mdx)** — Collapsible sidebar with columns and filters panels
+
+## Configuration
+
+- **[OGrid Props](./ogrid-props.mdx)** — Top-level OGrid component props (client-side and server-side modes)
+- **[Column Definition](./column-def.mdx)** — Complete column definition reference (IColumnDef, IColumnGroupDef, cell editors, filters)
+- **[Grid API](./grid-api.mdx)** — Imperative grid API (IOGridApi) for programmatic control
+- **[JS API](./js-api.mdx)** — Vanilla JS API reference (OGrid class, state classes, components)
+
+## Types
+
+- **[Types Reference](./types.mdx)** — All shared TypeScript types:
+  - **Data Types:** `RowId`, `FilterValue`, `IFilters`, `IDataSource`, `IFetchParams`, `IPageResult`
+  - **Selection:** `RowSelectionMode`, `IActiveCell`, `ISelectionRange`, `IRowSelectionChangeEvent`
+  - **Editing:** `ICellEditorProps`, `ICellValueChangedEvent`, `CellEditorParams`
+  - **UI:** `IStatusBarProps`, `ISideBarDef`, `UserLike`
+  - **State:** `IGridColumnState`, `IVirtualScrollConfig`
+
+## Quick Links
+
+### Getting Started
+- [Installation](/docs/getting-started/installation)
+- [Quick Start](/docs/getting-started/quick-start)
+- [Framework Showcase](/docs/guides/framework-showcase)
+
+### Features
+- [Sorting](/docs/features/sorting)
+- [Filtering](/docs/features/filtering)
+- [Pagination](/docs/features/pagination)
+- [Row Selection](/docs/features/row-selection)
+- [Spreadsheet Selection](/docs/features/spreadsheet-selection)
+- [Editing](/docs/features/editing)
+- [Column Chooser](/docs/features/column-chooser)
+- [Server-Side Data](/docs/features/server-side-data)
+- [Virtual Scrolling](/docs/features/virtual-scrolling)
+- [Sidebar](/docs/features/sidebar)
+
+## Type Imports
+
+All types can be imported from any OGrid package:
+
+```typescript
+// React packages
+  IColumnDef,
+  IOGridApi,
+  IOGridProps,
+  IDataSource,
+  ICellEditorProps,
+  IFilters,
+  FilterValue,
+  RowId,
+} from '@alaarab/ogrid-react-radix';
+
+// Angular packages
+  IColumnDef,
+  IOGridApi,
+  IDataSource,
+} from '@alaarab/ogrid-angular-material';
+
+// Vue packages
+  IColumnDef,
+  IOGridApi,
+  IDataSource,
+} from '@alaarab/ogrid-vue-vuetify';
+
+// Vanilla JS
+  IColumnDef,
+  IDataSource,
+} from '@alaarab/ogrid-js';
+```
+
+## Framework-Specific APIs
+
+Each framework has idiomatic APIs:
+
+| Framework | Orchestration | State Hook/Service | Props Pattern |
+|-----------|---------------|-------------------|---------------|
+| **React** | `useOGrid()` hook | `useDataGridState()` | Individual props |
+| **Angular** | `OGridService` | `DataGridStateService` | Signal-based inputs |
+| **Vue** | `useOGrid()` composable | `useDataGridState()` | Individual props or `:grid-props` |
+| **Vanilla JS** | `OGrid` class | `GridState` class | Constructor options |
+
+See the [Framework Showcase](/docs/guides/framework-showcase) for detailed comparisons and examples.

package/bundled-docs/api/column-def.mdx

@@ -0,0 +1,379 @@
+---
+sidebar_position: 2
+title: Column Definition
+---
+
+# Column Definition
+
+Complete reference for column definitions, column groups, cell editors, and related types.
+
+## IColumnMeta
+
+Base metadata shared by all column definitions. These properties control how a column appears and behaves in the grid header.
+
+```typescript
+interface IColumnMeta {
+  columnId: string;
+  name: string;
+  type?: 'text' | 'numeric' | 'date' | 'boolean';
+  sortable?: boolean;
+  filterable?: IColumnFilterDef;
+  defaultVisible?: boolean;
+  required?: boolean;
+  minWidth?: number;
+  defaultWidth?: number;
+  idealWidth?: number;
+  pinned?: 'left' | 'right';
+}
+```
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `columnId` | `string` | **Required** | Unique identifier for the column. Used as the key for sorting, filtering, visibility, and state persistence. Also used as the default field name for `valueGetter` if none is provided. |
+| `name` | `string` | **Required** | Display name shown in the column header. |
+| `type` | `'text' \| 'numeric' \| 'date' \| 'boolean'` | `undefined` | Column data type. Affects alignment, default editor, default filter, and display formatting. `'numeric'` right-aligns cells; `'date'` applies date formatting and a date picker editor; `'boolean'` centers cells and uses a checkbox editor. |
+| `sortable` | `boolean` | `true` | Whether the column header is clickable for sorting. |
+| `filterable` | `IColumnFilterDef` | `undefined` | Filter configuration. When provided, a filter icon appears in the column header. See [IColumnFilterDef](#icolumnfilterdef) below. |
+| `defaultVisible` | `boolean` | `true` | Whether the column is visible by default. Columns with `defaultVisible: false` can be shown via the column chooser. |
+| `required` | `boolean` | `false` | When `true`, the column cannot be hidden via the column chooser. |
+| `minWidth` | `number` | `undefined` | Minimum column width in pixels. The column cannot be resized below this value. |
+| `defaultWidth` | `number` | `undefined` | Default column width in pixels. |
+| `idealWidth` | `number` | `undefined` | Preferred column width in pixels. Used by the grid's auto-sizing algorithm. |
+| `pinned` | `'left' \| 'right'` | `undefined` | Pin the column to the left or right edge of the grid. Pinned columns remain visible when scrolling horizontally. |
+
+## IColumnDef<T>
+
+Extends `IColumnMeta` with rendering, editing, and data access properties. The `renderCell` and `cellStyle` properties are React-specific additions; Angular and Vue packages have equivalent rendering mechanisms in their respective component APIs.
+
+```typescript
+interface IColumnDef<T> extends IColumnMeta {
+  renderCell?: (item: T) => ReactNode;
+  compare?: (a: T, b: T) => number;
+  valueGetter?: (item: T) => unknown;
+  valueFormatter?: (value: unknown, item: T) => string;
+  clipboardFormatter?: (value: unknown, item: T) => string;
+  valueParser?: (params: IValueParserParams<T>) => unknown;
+  cellStyle?: CSSProperties | ((item: T) => CSSProperties);
+  editable?: boolean | ((item: T) => boolean);
+  cellEditor?: 'text' | 'select' | 'checkbox' | 'richSelect' | 'date' | ComponentType<ICellEditorProps<T>>;
+  cellEditorPopup?: boolean;
+  cellEditorParams?: CellEditorParams;
+}
+```
+
+### Rendering
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `renderCell` | `(item: T) => ReactNode` | `undefined` | Custom cell renderer. Receives the row data and returns JSX. When not provided, the grid displays the raw value from `valueGetter` or the field matching `columnId`. |
+| `cellStyle` | `CSSProperties \| ((item: T) => CSSProperties)` | `undefined` | Custom styles applied to the cell. Can be a static style object or a function that returns styles based on the row data. |
+
+### Data Access
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `valueGetter` | `(item: T) => unknown` | `undefined` | Extracts the raw value from a row for sorting, filtering, editing, and display. When not provided, the grid reads `item[columnId]`. |
+| `valueFormatter` | `(value: unknown, item: T) => string` | `undefined` | Formats the raw value for display. Receives the value from `valueGetter` and the row data. Also used for clipboard copy when `clipboardFormatter` is not set. |
+| `clipboardFormatter` | `(value: unknown, item: T) => string` | `undefined` | Formats the raw value specifically for clipboard copy. When set, overrides `valueFormatter` for copy/paste operations. |
+| `valueParser` | `(params: IValueParserParams<T>) => unknown` | `undefined` | Parses a user-entered string back into the data type expected by your model. Used during cell editing and paste operations. |
+| `compare` | `(a: T, b: T) => number` | `undefined` | Custom sort comparator. Returns a negative number if `a` comes before `b`, positive if after, or `0` if equal. When not provided, the grid uses a default comparison on the `valueGetter` result. |
+
+### Editing
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `editable` | `boolean \| ((item: T) => boolean)` | `false` | Whether cells in this column are editable. A function allows per-row control. The grid-level `editable` prop must also be `true` for editing to work. |
+| `cellEditor` | `'text' \| 'select' \| 'checkbox' \| 'richSelect' \| 'date' \| ComponentType<ICellEditorProps<T>>` | `'text'` | The editor to use when a cell enters edit mode. Built-in editors: `'text'` (text input), `'select'` (dropdown), `'checkbox'` (toggle), `'richSelect'` (searchable dropdown), `'date'` (date picker). You can also pass a custom React component. |
+| `cellEditorPopup` | `boolean` | `false` | When `true`, the cell editor renders in a popup overlay instead of inline within the cell. |
+| `cellEditorParams` | `CellEditorParams` | `undefined` | Additional parameters passed to the cell editor. The shape depends on the editor type. See [CellEditorParams](#celleditorparams) below. |
+
+## IColumnFilterDef
+
+Configuration for column header filters.
+
+```typescript
+interface IColumnFilterDef {
+  type: 'text' | 'multiSelect' | 'people' | 'date';
+  filterField?: string;
+  optionsSource?: 'api' | 'static' | 'years';
+  options?: string[];
+  yearsCount?: number;
+}
+```
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `'text' \| 'multiSelect' \| 'people' \| 'date'` | **Required** | Filter type. `'text'` shows a text input. `'multiSelect'` shows a list of checkboxes. `'people'` shows a people picker with search. `'date'` shows a date range picker with from/to date inputs. |
+| `filterField` | `string` | `columnId` | The field name to use in the `IFilters` record. Defaults to the column's `columnId`. Useful when multiple columns filter on the same field. |
+| `optionsSource` | `'api' \| 'static' \| 'years'` | `undefined` | Where multiSelect options come from. `'static'` uses the `options` array. `'api'` calls `dataSource.fetchFilterOptions()`. `'years'` auto-generates a list of years. |
+| `options` | `string[]` | `undefined` | Static list of filter options for `optionsSource: 'static'`. |
+| `yearsCount` | `number` | `undefined` | Number of years to generate when `optionsSource: 'years'`. |
+
+### Filter Type Examples
+
+```typescript
+// Text filter
+{ columnId: 'name', name: 'Name', filterable: { type: 'text' } }
+
+// Multi-select with static options
+{
+  columnId: 'status',
+  name: 'Status',
+  filterable: {
+    type: 'multiSelect',
+    optionsSource: 'static',
+    options: ['Active', 'Inactive', 'Pending'],
+  },
+}
+
+// Multi-select with server-side options
+{
+  columnId: 'department',
+  name: 'Department',
+  filterable: { type: 'multiSelect', optionsSource: 'api' },
+}
+
+// People filter
+{
+  columnId: 'assignee',
+  name: 'Assignee',
+  filterable: { type: 'people' },
+}
+
+// Year filter
+{
+  columnId: 'year',
+  name: 'Year',
+  filterable: { type: 'multiSelect', optionsSource: 'years', yearsCount: 10 },
+}
+```
+
+## IColumnGroupDef&lt;T&gt;
+
+Defines a group of columns rendered under a shared multi-row header.
+
+```typescript
+interface IColumnGroupDef<T> {
+  headerName: string;
+  children: (IColumnGroupDef<T> | IColumnDef<T>)[];
+}
+```
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `headerName` | `string` | **Required** | Display name for the column group header. Rendered centered above its child columns. |
+| `children` | `(IColumnGroupDef<T> \| IColumnDef<T>)[]` | **Required** | Child columns or nested column groups. Groups can be nested to arbitrary depth, producing multi-row headers. |
+
+### Column Group Example
+
+```typescript
+const columns = [
+  { columnId: 'name', name: 'Name' },
+  {
+    headerName: 'Contact Info',
+    children: [
+      { columnId: 'email', name: 'Email' },
+      { columnId: 'phone', name: 'Phone' },
+    ],
+  },
+  {
+    headerName: 'Address',
+    children: [
+      { columnId: 'city', name: 'City' },
+      { columnId: 'state', name: 'State' },
+      { columnId: 'zip', name: 'ZIP' },
+    ],
+  },
+];
+```
+
+This renders as:
+
+| Name | Contact Info || Address |||
+|------|-------|-------|------|-------|-----|
+|      | Email | Phone | City | State | ZIP |
+
+## ICellEditorProps&lt;T&gt;
+
+Props received by custom cell editor components.
+
+```typescript
+interface ICellEditorProps<T> {
+  value: unknown;
+  onValueChange: (value: unknown) => void;
+  onCommit: () => void;
+  onCancel: () => void;
+  item: T;
+  column: IColumnDef<T>;
+  cellEditorParams?: CellEditorParams;
+}
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `value` | `unknown` | The current cell value. |
+| `onValueChange` | `(value: unknown) => void` | Call this to update the pending value as the user types or makes a selection. |
+| `onCommit` | `() => void` | Call this to commit the current value and exit edit mode. Typically bound to Enter or blur. |
+| `onCancel` | `() => void` | Call this to discard changes and exit edit mode. Typically bound to Escape. |
+| `item` | `T` | The full row data object. |
+| `column` | `IColumnDef<T>` | The column definition for the cell being edited. |
+| `cellEditorParams` | `CellEditorParams` | Additional parameters from the column definition's `cellEditorParams`. |
+
+### Custom Cell Editor Example
+
+```typescript
+
+function DateEditor({ value, onValueChange, onCommit, onCancel }: ICellEditorProps<MyRow>) {
+  return (
+    <input
+      type="date"
+      value={value as string}
+      onChange={(e) => onValueChange(e.target.value)}
+      onKeyDown={(e) => {
+        if (e.key === 'Enter') onCommit();
+        if (e.key === 'Escape') onCancel();
+      }}
+      onBlur={onCommit}
+      autoFocus
+    />
+  );
+}
+
+const columns = [
+  {
+    columnId: 'dueDate',
+    name: 'Due Date',
+    editable: true,
+    cellEditor: DateEditor,
+  },
+];
+```
+
+## CellEditorParams
+
+Parameters passed to built-in cell editors via the `cellEditorParams` property on a column definition. The shape varies by editor type.
+
+### Select Editor
+
+```typescript
+{
+  cellEditor: 'select',
+  cellEditorParams: {
+    values: ['Option A', 'Option B', 'Option C'],
+  },
+}
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `values` | `string[]` | List of options for the select dropdown. |
+
+### Rich Select Editor
+
+```typescript
+{
+  cellEditor: 'richSelect',
+  cellEditorParams: {
+    values: ['Active', 'Inactive', 'Pending'],
+    formatValue: (value: string) => value.toUpperCase(),
+  },
+}
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `values` | `string[]` | List of options for the searchable dropdown. |
+| `formatValue` | `(value: string) => string` | Optional function to format how each option is displayed. |
+
+## ICellValueChangedEvent&lt;T&gt;
+
+Event object passed to `onCellValueChanged` after a cell edit is committed.
+
+```typescript
+interface ICellValueChangedEvent<T> {
+  item: T;
+  columnId: string;
+  oldValue: unknown;
+  newValue: unknown;
+  rowIndex: number;
+}
+```
+
+| Name | Type | Description |
+|------|------|-------------|
+| `item` | `T` | The row data object (before the change). |
+| `columnId` | `string` | The column ID of the edited cell. |
+| `oldValue` | `unknown` | The value before editing. |
+| `newValue` | `unknown` | The value after editing. |
+| `rowIndex` | `number` | The row index of the edited cell. |
+
+## Complete Column Definition Example
+
+```typescript
+
+interface Employee {
+  id: number;
+  name: string;
+  department: string;
+  salary: number;
+  startDate: string;
+  manager: { displayName: string; email: string };
+}
+
+const columns: (IColumnDef<Employee> | IColumnGroupDef<Employee>)[] = [
+  {
+    columnId: 'name',
+    name: 'Employee Name',
+    sortable: true,
+    required: true,
+    pinned: 'left',
+    minWidth: 150,
+    filterable: { type: 'text' },
+    editable: true,
+    cellEditor: 'text',
+  },
+  {
+    headerName: 'Details',
+    children: [
+      {
+        columnId: 'department',
+        name: 'Department',
+        filterable: {
+          type: 'multiSelect',
+          optionsSource: 'static',
+          options: ['Engineering', 'Marketing', 'Sales', 'HR'],
+        },
+        editable: true,
+        cellEditor: 'richSelect',
+        cellEditorParams: { values: ['Engineering', 'Marketing', 'Sales', 'HR'] },
+      },
+      {
+        columnId: 'salary',
+        name: 'Salary',
+        type: 'numeric',
+        valueFormatter: (value) => `$${Number(value).toLocaleString()}`,
+        valueParser: ({ newValue }) => Number(String(newValue).replace(/[$,]/g, '')),
+        editable: true,
+        cellStyle: (item) => ({
+          color: item.salary > 100000 ? 'green' : undefined,
+        }),
+      },
+    ],
+  },
+  {
+    columnId: 'startDate',
+    name: 'Start Date',
+    defaultVisible: false,
+    valueFormatter: (value) => new Date(value as string).toLocaleDateString(),
+  },
+  {
+    columnId: 'manager',
+    name: 'Manager',
+    filterable: { type: 'people' },
+    valueGetter: (item) => item.manager,
+    renderCell: (item) => <span>{item.manager.displayName}</span>,
+    valueFormatter: (value) => (value as Employee['manager']).displayName,
+    editable: false,
+  },
+];
+```