@alaarab/ogrid-mcp 2.14.1 → 2.15.0

package/bundled-docs/api/components-sidebar.mdx

@@ -18,7 +18,7 @@ A collapsible sidebar panel that provides quick access to column visibility cont
 ```
 
 :::tip
-The `SideBar` component is framework-agnostic and uses inline styles. All React UI packages (Radix, Fluent, Material) use the same `SideBar` from `@alaarab/ogrid-react`.
+The `SideBar` component is framework-agnostic and uses inline styles. All React UI packages (Radix, Fluent) use the same `SideBar` from `@alaarab/ogrid-react`.
 :::
 
 </TabItem>

package/bundled-docs/api/headless-hooks.mdx

@@ -10,7 +10,7 @@ OGrid 2.9 ships seven framework-native hooks that expose grid logic without
 imposing any chrome. Pair `useHeadlessGrid` with the spreadsheet hooks to
 add inline edit, range selection, fill handle, clipboard, undo/redo, and
 keyboard navigation to your own table markup (shadcn `<Table>`, plain HTML,
-Material `<DataGrid>`, anything).
+Fluent `<DataGrid>`, anything).
 
 All seven hooks ship as React hooks:
 

package/bundled-docs/features/premium-inputs.mdx

@@ -18,7 +18,7 @@ OGrid's premium inputs are optional cell editor components distributed in a sepa
 npm install @alaarab/ogrid-react-inputs
 ```
 
-Works with any OGrid React UI package (Radix, Fluent, Material).
+Works with any OGrid React UI package (Radix, Fluent).
 
   </TabItem>
 </Tabs>
@@ -213,7 +213,7 @@ OGrid includes built-in cell editors out of the box. The premium input packages
 
 | | Default (built-in) | Premium (add-on packages) |
 |---|---|---|
-| **Package** | Included in all OGrid packages | `@alaarab/ogrid-{react,angular,vue,js}-inputs` |
+| **Package** | Included in all OGrid packages | `@alaarab/ogrid-react-inputs` |
 | **Editors** | Text, Select, Rich Select, Checkbox, Date (inline) | DatePicker, Rating, ColorPicker, Slider, Tags |
 | **Bundle cost** | Zero (built-in) | Only added when you `npm install` the package |
 

package/bundled-docs/features/xlsx-import.mdx

@@ -0,0 +1,124 @@
+---
+sidebar_position: 16
+title: XLSX Import
+description: Drop an .xlsx file into a fully featured OGrid — with multi-sheet tabs, formulas, and cell references on by default
+---
+
+
+# XLSX Import
+
+Render any `.xlsx`, CSV, or TSV blob as a fully featured OGrid. Multi-sheet workbooks get tabbed navigation, formulas evaluate live, and Excel-style cell references (A1, B2…) are on by default.
+
+Two packages ship this:
+
+| Package | When to use |
+|---|---|
+| [`@alaarab/ogrid-react-xlsx`](https://www.npmjs.com/package/@alaarab/ogrid-react-xlsx) | React apps with a bundler (Vite, Next.js, Webpack, etc.). |
+| [`@alaarab/ogrid-react-xlsx-browser`](https://www.npmjs.com/package/@alaarab/ogrid-react-xlsx-browser) | Static HTML pages, SharePoint Framework drops, or any no-bundler context. One self-contained ESM file. |
+
+Both expose the same component surface — `XlsxWorkbookGrid`, `XlsxGrid`, and an imperative `mount()` helper.
+
+## React (with a bundler)
+
+```bash
+npm i @alaarab/ogrid-react-xlsx
+```
+
+<Tabs groupId="entry">
+  <TabItem value="workbook" label="Full workbook" default>
+
+```tsx
+
+function Preview({ file }: { file: Blob }) {
+  return <XlsxWorkbookGrid blob={file} height={520} />;
+}
+```
+
+  </TabItem>
+  <TabItem value="single" label="Single sheet">
+
+```tsx
+
+function SingleSheet({ file }: { file: Blob }) {
+  const [wb, setWb] = useState<ExcelJS.Workbook | null>(null);
+  useEffect(() => { workbookFromBlob(file).then(setWb); }, [file]);
+  if (!wb) return null;
+  return <XlsxGrid workbook={wb} sheetName="Summary" density="compact" />;
+}
+```
+
+  </TabItem>
+</Tabs>
+
+### `XlsxWorkbookGrid` props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `blob` | `Blob` | — | The raw `.xlsx`/CSV/TSV file. Parsed inside the component. Use this OR `workbook`. |
+| `workbook` | `ExcelJS.Workbook` | — | A pre-parsed workbook. Use this OR `blob`. |
+| `height` | `number \| string` | `'100%'` | Container height. |
+| `initialSheet` | `string` | first sheet | Which sheet to show on mount. |
+| `density` | `'compact' \| 'normal' \| 'comfortable'` | `'compact'` | Row height. |
+| `onSheetChange` | `(name: string) => void` | — | Fired when the user clicks a sheet tab. |
+| `headerRow` | `'auto' \| 'header' \| 'none'` | `'auto'` | Whether to promote row 1 to the header. `'auto'` detects strings-only top rows; `'header'` forces it; `'none'` uses A/B/C letters. |
+
+### Format support
+
+ExcelJS-backed: `.xlsx`, `.csv`, `.tsv`. The `xlsx` package on npm (SheetJS) is currently stuck at the vulnerable 0.18.5, so support for `.xls`, `.xlsm`, `.xlsb`, and `.ods` was dropped in 2.12.0. See CHANGELOG for the swap rationale.
+
+## Browser bundle (no bundler)
+
+For SharePoint Framework, static HTML, or any page that can't (or won't) run a JS bundler, install `@alaarab/ogrid-react-xlsx-browser`. It's a single ESM file — `dist/ogrid-xlsx.js` — with React, ReactDOM, ExcelJS, and every `@alaarab/ogrid-*` dep inlined. ~1.5MB minified, gzipped well by any HTTP server.
+
+```bash
+npm i @alaarab/ogrid-react-xlsx-browser
+```
+
+Copy the two output files into a `vendor/` directory you serve statically:
+
+```
+vendor/
+  ogrid-xlsx.js
+  ogrid-xlsx.css
+```
+
+Then drop this into any HTML page:
+
+```html
+<link rel="stylesheet" href="/vendor/ogrid-xlsx.css" />
+<div id="grid" style="height: 520px"></div>
+
+<script type="module">
+  const { mount } = await import('/vendor/ogrid-xlsx.js');
+
+  const file = await fetch('/data/report.xlsx').then(r => r.blob());
+  const unmount = mount(document.getElementById('grid'), { blob: file });
+
+  // When you're done — React 19 does not auto-unmount on DOM removal:
+  // unmount();
+</script>
+```
+
+### Imperative `mount()`
+
+```ts
+mount(node: Element, opts: MountOptions): () => void
+```
+
+Returns an unmount function. Always call it before removing the host node — React 19 won't clean up event listeners or state if you just `node.remove()`.
+
+`MountOptions` accepts the same fields as `XlsxWorkbookGrid` props (`blob` / `workbook`, `initialSheet`, `density`, `height`, `onSheetChange`, `headerRow`).
+
+### When to pick this over the React package
+
+| Use the React package when | Use the browser bundle when |
+|---|---|
+| You already have a Vite / Webpack / Next.js build. | You're shipping into a static page, SPFx web part, or CDN drop. |
+| You want tree-shaking and a single dependency graph. | You don't have (and don't want) a JS bundler. |
+| You're integrating into an existing React tree. | You want one `<script type="module">` import. |
+
+## Related
+
+- [Formulas](./formulas) — the engine that evaluates `=SUM(A1:A5)` cells lifted out of the workbook
+- [Cell References](./cell-references) — A/B/C column headers and the name box, on by default for xlsx grids
+- [CSV Export](./csv-export) — round-trip data back out of the grid

package/bundled-docs/getting-started/headless-or-component.mdx

@@ -15,7 +15,7 @@ fits the page you're building — you can mix them in the same app.
 | **What you write** | One JSX element | A handful of hook calls + your own `<table>` markup |
 | **Time to first working grid** | ~5 lines | ~50-100 lines |
 | **Customization ceiling** | High (theme tokens, slots) | Unlimited (you draw the chrome) |
-| **Design-system fit** | Inherits via theme presets (shadcn, Fluent, Material) | Native — uses your chrome primitives directly |
+| **Design-system fit** | Inherits via theme presets (shadcn, Fluent) | Native — uses your chrome primitives directly |
 | **Spreadsheet features** | Built-in | Composable from hooks |
 | **Best for** | Standard list pages, admin tables, dashboards | Pages where chrome integration matters more than save-time |
 
@@ -23,7 +23,7 @@ fits the page you're building — you can mix them in the same app.
 
 - You want a complete grid in one element. Sort, filter, paginate, edit,
   range select, fill handle, copy/paste, undo, keyboard nav — all wired.
-- The default chrome (via your chosen UI variant — Radix / Fluent / Material)
+- The default chrome (via your chosen UI variant — Radix / Fluent)
   is close enough to your design system that a theme preset (`preset-shadcn.css`)
   can bridge the rest.
 - You're prototyping or building admin pages where shipping fast matters
@@ -42,8 +42,7 @@ const columns = [
 ## Use `useHeadlessGrid` + the spreadsheet hooks when…
 
 - You want OGrid's logic but rendered with your own table chrome
-  (shadcn `<Table>`, Fluent `<DataGrid>`, Material `<TableRow>`, plain HTML —
-  anything).
+  (shadcn `<Table>`, Fluent `<DataGrid>`, plain HTML — anything).
 - The chrome integration is non-negotiable: a specific design system,
   custom row layouts, embedded widgets in cells, or shared `<TableRow>`
   components from the rest of the app.

package/bundled-docs/guides/mcp.mdx

@@ -90,7 +90,7 @@ search_docs query="server-side data" framework="react"
 
 Parameters:
 - `query` (required) — what you're looking for
-- `framework` (optional) — `react`, `angular`, `vue`, or `js`
+- `framework` (optional) — `react`
 - `category` (optional) — `features`, `getting-started`, `guides`, or `api`
 
 ### `list_docs`
@@ -114,7 +114,7 @@ get_docs path="features/filtering"
 Pull code snippets from a doc page, optionally filtered by framework.
 
 ```
-get_code_example path="features/editing" framework="angular"
+get_code_example path="features/editing" framework="react"
 ```
 
 ### `detect_version`

package/dist/esm/index.js

@@ -93,6 +93,21 @@ function parseDocFile(filePath, docsDir2) {
     codeBlocks
   };
 }
+function countOccurrences(haystack, needle, cap) {
+  if (!needle) return 0;
+  let idx = 0;
+  let count = 0;
+  while (count < cap) {
+    idx = haystack.indexOf(needle, idx);
+    if (idx === -1) break;
+    count++;
+    idx += needle.length;
+  }
+  return count;
+}
+function tokenize(queryLower) {
+  return queryLower.split(/\s+/).filter((t) => t.length > 1);
+}
 function scoreEntry(entry, queryLower) {
   let score = 0;
   const titleLower = entry.title.toLowerCase();
@@ -108,15 +123,18 @@ function scoreEntry(entry, queryLower) {
   }
   if (contentLower.includes(queryLower)) {
     score += 10;
-    let idx = 0;
-    let count = 0;
-    while (count < 10) {
-      idx = contentLower.indexOf(queryLower, idx);
-      if (idx === -1) break;
-      count++;
-      idx += queryLower.length;
+    score += countOccurrences(contentLower, queryLower, 10) * 2;
+  }
+  const tokens = tokenize(queryLower);
+  if (tokens.length > 1) {
+    for (const token of tokens) {
+      if (titleLower.includes(token)) score += 25;
+      if (descLower.includes(token)) score += 12;
+      if (contentLower.includes(token)) {
+        score += 3;
+        score += countOccurrences(contentLower, token, 5);
+      }
     }
-    score += count * 2;
   }
   if (entry.category === "features") score += 3;
   if (entry.category === "getting-started") score += 2;
@@ -125,9 +143,20 @@ function scoreEntry(entry, queryLower) {
 function scoreCodeBlock(entry, block, queryLower, framework) {
   let score = 0;
   if (framework && block.framework !== framework) return -1;
-  if (entry.title.toLowerCase().includes(queryLower)) score += 50;
-  if (entry.description.toLowerCase().includes(queryLower)) score += 25;
-  if (block.code.toLowerCase().includes(queryLower)) score += 30;
+  const titleLower = entry.title.toLowerCase();
+  const descLower = entry.description.toLowerCase();
+  const codeLower = block.code.toLowerCase();
+  if (titleLower.includes(queryLower)) score += 50;
+  if (descLower.includes(queryLower)) score += 25;
+  if (codeLower.includes(queryLower)) score += 30;
+  const tokens = tokenize(queryLower);
+  if (tokens.length > 1) {
+    for (const token of tokens) {
+      if (titleLower.includes(token)) score += 12;
+      if (descLower.includes(token)) score += 6;
+      if (codeLower.includes(token)) score += 8;
+    }
+  }
   return score;
 }
 function loadDocsIndex(docsDir2) {
@@ -215,15 +244,19 @@ function fromResourcePath(resourcePath, index2) {
   return index2.getByPath(resourcePath + ".mdx") ?? index2.getByPath(resourcePath + ".md") ?? index2.getByPath(resourcePath);
 }
 function createOGridMcpServer(index2, bridge) {
-  const server2 = new McpServer({
-    name: "ogrid-docs",
-    version: "2.3.0",
-    instructions: `OGrid documentation server. OGrid is a lightweight, headless data grid for React (Radix and Fluent UI implementations).
+  const server2 = new McpServer(
+    {
+      name: "ogrid-docs",
+      version: "2.3.0"
+    },
+    {
+      instructions: `OGrid documentation server. OGrid is a lightweight, headless data grid for React (Radix and Fluent UI implementations).
 
 Tools: search_docs (keyword search), list_docs (browse by category), get_docs (full page), get_code_example (code snippets), detect_version (detect OGrid version in your project).
 Resources: ogrid://quick-reference (key API overview), ogrid://docs/{path} (any doc page by path).
 Categories: features, getting-started, guides, api.`
-  });
+    }
+  );
   server2.tool(
     "search_docs",
     "Search OGrid documentation by keyword. Returns matching docs with title, description, and content excerpt.",
@@ -440,12 +473,14 @@ Tip: use \`get_code_example\` with framework="${result.framework}" or \`search_d
         {
           uri: uri.href,
           mimeType: "text/markdown",
+          // Source of truth: docs/api/ogrid-props.mdx + docs/api/column-def.mdx.
+          // Keep this in sync when those API references change.
           text: [
             "# OGrid Quick Reference",
             "",
             "## Install",
             "```bash",
-            "# React (choose one)",
+            "# React (choose one UI variant)",
             "npm install @alaarab/ogrid-react-radix",
             "npm install @alaarab/ogrid-react-fluent",
             "```",
@@ -453,34 +488,38 @@ Tip: use \`get_code_example\` with framework="${result.framework}" or \`search_d
             "## Core Props (IOGridProps)",
             "| Prop | Type | Description |",
             "|------|------|-------------|",
-            "| `data` | `T[]` | Client-side row data |",
-            "| `columns` | `IColumnDef<T>[]` | Column definitions |",
-            "| `dataSource` | `IDataSource<T>` | Server-side data source |",
-            "| `pagination` | `boolean \\| number` | Enable pagination (number = page size) |",
-            '| `rowSelection` | `"single" \\| "multiple"` | Row selection mode |',
+            "| `data` | `T[]` | Client-side row data (mutually exclusive with `dataSource`) |",
+            "| `dataSource` | `IDataSource<T>` | Server-side data source (mutually exclusive with `data`) |",
+            "| `columns` | `(IColumnDef<T> \\| IColumnGroupDef<T>)[]` | Column definitions (and optional groups) |",
+            "| `getRowId` | `(item: T) => RowId` | **Required.** Stable unique id for each row |",
+            "| `defaultPageSize` | `number` | Initial page size in uncontrolled mode (default 25) |",
+            "| `pageSizeOptions` | `number[]` | Options shown in the page-size dropdown |",
+            '| `rowSelection` | `"none" \\| "single" \\| "multiple"` | Row selection mode |',
+            "| `editable` | `boolean` | Enable inline cell editing globally |",
             "| `formulas` | `boolean` | Enable formula engine (=SUM, =IF, etc.) |",
             "| `cellReferences` | `boolean` | Excel-style A1 column headers + name box |",
             '| `workerSort` | `boolean \\| "auto"` | Web Worker sort/filter |',
             '| `columnChooser` | `boolean \\| "toolbar" \\| "sidebar"` | Column visibility control |',
             "| `sideBar` | `boolean \\| ISideBarDef` | Sidebar panel |",
             "| `toolbar` | `ReactNode` | Custom toolbar content |",
-            "| `onRowSelectionChanged` | `(rows: T[]) => void` | Row selection callback |",
-            "| `onCellValueChanged` | `(e: ICellValueChangedEvent) => void` | Cell edit callback |",
+            "| `onSelectionChange` | `(e: IRowSelectionChangeEvent<T>) => void` | Row selection callback |",
+            "| `onCellValueChanged` | `(e: ICellValueChangedEvent<T>) => void` | Cell edit callback |",
             "",
             "## IColumnDef Key Fields",
             "| Field | Type | Description |",
             "|-------|------|-------------|",
-            "| `columnId` | `string` | Unique column ID (maps to data key) |",
-            "| `headerName` | `string` | Column header label |",
+            "| `columnId` | `string` | Unique column id (maps to the data key) |",
+            "| `name` | `string` | Column header label |",
             '| `type` | `"text" \\| "numeric" \\| "date" \\| "boolean"` | Data type |',
-            '| `filter` | `"none" \\| "text" \\| "multiSelect" \\| "date"` | Filter type |',
-            "| `editable` | `boolean \\| (row) => boolean` | Enable inline editing |",
-            "| `width` | `number` | Column width in px |",
-            '| `pinned` | `"left" \\| "right"` | Pin column |',
-            "| `sortable` | `boolean` | Enable sorting |",
-            "| `hidden` | `boolean` | Hide column by default |",
-            "| `valueGetter` | `(row: T) => unknown` | Custom value extractor |",
-            "| `renderCell` | `(value, row) => ReactNode` | Custom cell renderer (React) |",
+            "| `filterable` | `IColumnFilterDef` | Filter config; omit to make the column not filterable |",
+            "| `editable` | `boolean \\| ((item: T) => boolean)` | Enable inline editing |",
+            "| `sortable` | `boolean` | Enable sorting (default true) |",
+            "| `defaultWidth` | `number` | Default column width in pixels |",
+            '| `pinned` | `"left" \\| "right"` | Pin column to an edge |',
+            "| `defaultVisible` | `boolean` | Show column by default (false = hidden, toggle via chooser) |",
+            '| `cellEditor` | `"text" \\| "select" \\| "checkbox" \\| "richSelect" \\| "date" \\| ComponentType` | Cell editor |',
+            "| `valueGetter` | `(item: T) => unknown` | Custom value extractor |",
+            "| `renderCell` | `(item: T) => ReactNode` | Custom cell renderer |",
             "",
             "## Common Patterns",
             "",
@@ -488,27 +527,27 @@ Tip: use \`get_code_example\` with framework="${result.framework}" or \`search_d
             "```tsx",
             'import { OGrid } from "@alaarab/ogrid-react-radix";',
             "const columns = [",
-            '  { columnId: "name", headerName: "Name", type: "text", filter: "text" },',
-            '  { columnId: "age",  headerName: "Age",  type: "numeric", sortable: true },',
+            '  { columnId: "name", name: "Name", type: "text", filterable: { type: "text" } },',
+            '  { columnId: "age",  name: "Age",  type: "numeric", sortable: true },',
             "];",
-            "<OGrid data={rows} columns={columns} pagination={50} />",
+            "<OGrid data={rows} columns={columns} getRowId={(r) => r.id} defaultPageSize={50} />",
             "```",
             "",
             "### Server-side data",
             "```tsx",
             "const dataSource = {",
-            "  fetchPage: async ({ page, pageSize, sortModel, filterModel }) => {",
-            "    const res = await fetch(`/api/data?page=${page}&size=${pageSize}`);",
+            "  fetchPage: async ({ page, pageSize, sort, filters, signal }) => {",
+            "    const res = await fetch(`/api/data?page=${page}&size=${pageSize}`, { signal });",
             "    const json = await res.json();",
-            "    return { rows: json.data, totalCount: json.total };",
-            "  }",
+            "    return { items: json.data, totalCount: json.total };",
+            "  },",
             "};",
-            "<OGrid dataSource={dataSource} columns={columns} pagination={50} />",
+            "<OGrid dataSource={dataSource} columns={columns} getRowId={(r) => r.id} defaultPageSize={50} />",
             "```",
             "",
             "### Formula support",
             "```tsx",
-            "<OGrid data={rows} columns={columns} formulas cellReferences />",
+            "<OGrid data={rows} columns={columns} getRowId={(r) => r.id} formulas cellReferences />",
             '// Users can type =SUM(A1:C3), =IF(A1>0,"yes","no"), etc.',
             "```"
           ].join("\n")
@@ -742,7 +781,7 @@ _${state.rowCount - limit} more rows not shown. Increase maxRows to see more._`)
       {
         gridId: z.string().describe("Grid ID as registered by connectGridToBridge()"),
         type: z.enum(["update_cell", "set_filter", "clear_filters", "set_sort", "go_to_page"]).describe("Command type"),
-        payload: z.record(z.unknown()).describe("Command-specific payload (see tool description for fields per type)"),
+        payload: z.record(z.string(), z.unknown()).describe("Command-specific payload (see tool description for fields per type)"),
         timeoutMs: z.number().int().min(100).max(3e4).optional().describe("How long to wait for the app to execute the command (default: 5000ms)")
       },
       async ({ gridId, type, payload, timeoutMs }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alaarab/ogrid-mcp",
-  "version": "2.14.1",
+  "version": "2.15.0",
   "description": "MCP server for OGrid documentation",
   "type": "module",
   "bin": {
@@ -25,6 +25,7 @@
     "prebuild": "node scripts/bundle-docs.mjs",
     "build": "tsup",
     "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "bun test --preload ../../bun-test.setup.ts"
   },
   "dependencies": {