@alaarab/ogrid-mcp 2.14.2 → 2.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/bundled-docs/features/xlsx-import.mdx +124 -0
  2. package/package.json +7 -2
package/bundled-docs/features/xlsx-import.mdx ADDED
@@ -0,0 +1,124 @@
1
+ ---
2
+ sidebar_position: 16
3
+ title: XLSX Import
4
+ description: Drop an .xlsx file into a fully featured OGrid — with multi-sheet tabs, formulas, and cell references on by default
5
+ ---
6
+
7
+
8
+ # XLSX Import
9
+
10
+ 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.
11
+
12
+ Two packages ship this:
13
+
14
+ | Package | When to use |
15
+ |---|---|
16
+ | [`@alaarab/ogrid-react-xlsx`](https://www.npmjs.com/package/@alaarab/ogrid-react-xlsx) | React apps with a bundler (Vite, Next.js, Webpack, etc.). |
17
+ | [`@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. |
18
+
19
+ Both expose the same component surface — `XlsxWorkbookGrid`, `XlsxGrid`, and an imperative `mount()` helper.
20
+
21
+ ## React (with a bundler)
22
+
23
+ ```bash
24
+ npm i @alaarab/ogrid-react-xlsx
25
+ ```
26
+
27
+ <Tabs groupId="entry">
28
+ <TabItem value="workbook" label="Full workbook" default>
29
+
30
+ ```tsx
31
+
32
+ function Preview({ file }: { file: Blob }) {
33
+ return <XlsxWorkbookGrid blob={file} height={520} />;
34
+ }
35
+ ```
36
+
37
+ </TabItem>
38
+ <TabItem value="single" label="Single sheet">
39
+
40
+ ```tsx
41
+
42
+ function SingleSheet({ file }: { file: Blob }) {
43
+ const [wb, setWb] = useState<ExcelJS.Workbook | null>(null);
44
+ useEffect(() => { workbookFromBlob(file).then(setWb); }, [file]);
45
+ if (!wb) return null;
46
+ return <XlsxGrid workbook={wb} sheetName="Summary" density="compact" />;
47
+ }
48
+ ```
49
+
50
+ </TabItem>
51
+ </Tabs>
52
+
53
+ ### `XlsxWorkbookGrid` props
54
+
55
+ | Prop | Type | Default | Description |
56
+ |---|---|---|---|
57
+ | `blob` | `Blob` | — | The raw `.xlsx`/CSV/TSV file. Parsed inside the component. Use this OR `workbook`. |
58
+ | `workbook` | `ExcelJS.Workbook` | — | A pre-parsed workbook. Use this OR `blob`. |
59
+ | `height` | `number \| string` | `'100%'` | Container height. |
60
+ | `initialSheet` | `string` | first sheet | Which sheet to show on mount. |
61
+ | `density` | `'compact' \| 'normal' \| 'comfortable'` | `'compact'` | Row height. |
62
+ | `onSheetChange` | `(name: string) => void` | — | Fired when the user clicks a sheet tab. |
63
+ | `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. |
64
+
65
+ ### Format support
66
+
67
+ 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.
68
+
69
+ ## Browser bundle (no bundler)
70
+
71
+ 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.
72
+
73
+ ```bash
74
+ npm i @alaarab/ogrid-react-xlsx-browser
75
+ ```
76
+
77
+ Copy the two output files into a `vendor/` directory you serve statically:
78
+
79
+ ```
80
+ vendor/
81
+ ogrid-xlsx.js
82
+ ogrid-xlsx.css
83
+ ```
84
+
85
+ Then drop this into any HTML page:
86
+
87
+ ```html
88
+ <link rel="stylesheet" href="/vendor/ogrid-xlsx.css" />
89
+ <div id="grid" style="height: 520px"></div>
90
+
91
+ <script type="module">
92
+ const { mount } = await import('/vendor/ogrid-xlsx.js');
93
+
94
+ const file = await fetch('/data/report.xlsx').then(r => r.blob());
95
+ const unmount = mount(document.getElementById('grid'), { blob: file });
96
+
97
+ // When you're done — React 19 does not auto-unmount on DOM removal:
98
+ // unmount();
99
+ </script>
100
+ ```
101
+
102
+ ### Imperative `mount()`
103
+
104
+ ```ts
105
+ mount(node: Element, opts: MountOptions): () => void
106
+ ```
107
+
108
+ 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()`.
109
+
110
+ `MountOptions` accepts the same fields as `XlsxWorkbookGrid` props (`blob` / `workbook`, `initialSheet`, `density`, `height`, `onSheetChange`, `headerRow`).
111
+
112
+ ### When to pick this over the React package
113
+
114
+ | Use the React package when | Use the browser bundle when |
115
+ |---|---|
116
+ | You already have a Vite / Webpack / Next.js build. | You're shipping into a static page, SPFx web part, or CDN drop. |
117
+ | You want tree-shaking and a single dependency graph. | You don't have (and don't want) a JS bundler. |
118
+ | You're integrating into an existing React tree. | You want one `<script type="module">` import. |
119
+
120
+ ## Related
121
+
122
+ - [Formulas](./formulas) — the engine that evaluates `=SUM(A1:A5)` cells lifted out of the workbook
123
+ - [Cell References](./cell-references) — A/B/C column headers and the name box, on by default for xlsx grids
124
+ - [CSV Export](./csv-export) — round-trip data back out of the grid
package/package.json CHANGED
@@ -1,8 +1,13 @@
1
1
  {
2
2
  "name": "@alaarab/ogrid-mcp",
3
- "version": "2.14.2",
3
+ "version": "2.15.1",
4
4
  "description": "MCP server for OGrid documentation",
5
5
  "type": "module",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "https://github.com/alaarab/ogrid.git",
9
+ "directory": "packages/mcp"
10
+ },
6
11
  "bin": {
7
12
  "ogrid-mcp": "./dist/esm/index.js"
8
13
  },
@@ -30,7 +35,7 @@
30
35
  },
31
36
  "dependencies": {
32
37
  "@modelcontextprotocol/sdk": "^1.29.0",
33
- "zod": "^4.4.2"
38
+ "zod": "^4.4.3"
34
39
  },
35
40
  "devDependencies": {
36
41
  "tsup": "^8.5.1",