@alaarab/ogrid-mcp 2.14.2 → 2.15.0
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.
|
@@ -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
|