@arbocollab/arbo-xlsx-mapping 0.0.2-alpha.1 โ 0.0.2-alpha.3
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.
- package/ARBO_XLSX_MAPPING_APP_LOADER.md +117 -0
- package/CHANGELOG.md +25 -0
- package/README.md +201 -37
- package/index.es.js +3448 -3414
- package/package.json +4 -2
- package/style.css +1 -1
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Using `@arbocollab/arbo-xlsx-mapping` with Arbo App Loader
|
|
2
|
+
|
|
3
|
+
This guide shows how to load the XLSX mapping package as an app-loader
|
|
4
|
+
instance. The host application owns the loader, container, runtime
|
|
5
|
+
configuration, and instance lifecycle.
|
|
6
|
+
|
|
7
|
+
## 1. Publish the package
|
|
8
|
+
|
|
9
|
+
Publish the package to npm or make the generated bundle and stylesheet
|
|
10
|
+
available through the CDN. The CDN metadata should provide:
|
|
11
|
+
|
|
12
|
+
```ts
|
|
13
|
+
{
|
|
14
|
+
script: 'https://cdn.example.com/arbo-xlsx-mapping/index.es.js',
|
|
15
|
+
style: 'https://cdn.example.com/arbo-xlsx-mapping/style.css',
|
|
16
|
+
}
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Use the `beta` tag for prereleases or `latest` for stable releases.
|
|
20
|
+
|
|
21
|
+
## 2. Load the package URL and stylesheet
|
|
22
|
+
|
|
23
|
+
The host fetches the package metadata before creating the loader configuration:
|
|
24
|
+
|
|
25
|
+
```ts
|
|
26
|
+
const xlsxConfig = await fetchCdnVersionPackage('arbo-xlsx-mapping')
|
|
27
|
+
const xlsx = JSON.parse(xlsxConfig)
|
|
28
|
+
|
|
29
|
+
const MODULES = {
|
|
30
|
+
XLSX_TOOLBOX: xlsx.script,
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const MODULE_STYLES = {
|
|
34
|
+
xlsx_toolbox: {
|
|
35
|
+
cssUrl: xlsx.style,
|
|
36
|
+
namespace: 'xlsx_toolbox',
|
|
37
|
+
scoped: false,
|
|
38
|
+
},
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
The host can preload `MODULES.XLSX_TOOLBOX` before initializing the loader.
|
|
43
|
+
|
|
44
|
+
## 3. Register the XLSX instance
|
|
45
|
+
|
|
46
|
+
Add `xlsx_toolbox` to the host loader types and register a factory that imports
|
|
47
|
+
the package dynamically:
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
const config = {
|
|
51
|
+
instances: {
|
|
52
|
+
xlsx_toolbox: () =>
|
|
53
|
+
import(/* webpackIgnore: true */ MODULES.XLSX_TOOLBOX).then((module) => {
|
|
54
|
+
const createXlsxMappingInstance =
|
|
55
|
+
module.createXlsxMappingInstance ||
|
|
56
|
+
window.ArboXlsxMapping?.createXlsxMappingInstance
|
|
57
|
+
|
|
58
|
+
if (typeof createXlsxMappingInstance !== 'function') {
|
|
59
|
+
throw new Error('XLSX mapping factory is unavailable')
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
return createXlsxMappingInstance(runtimeKeys)
|
|
63
|
+
}),
|
|
64
|
+
},
|
|
65
|
+
moduleStyles: MODULE_STYLES,
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
`runtimeKeys` contains the host configuration, such as API and asset URLs.
|
|
70
|
+
The host may store required values in `sessionStorage` before mounting.
|
|
71
|
+
|
|
72
|
+
## 4. Initialize and open the tool
|
|
73
|
+
|
|
74
|
+
Create the loader, wait until it is ready, then switch to the XLSX instance:
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
const appLoader = initAppLoader(config)
|
|
78
|
+
await appLoader.ready
|
|
79
|
+
|
|
80
|
+
await appLoader.switchInstance('xlsx_toolbox', undefined, 'popup')
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
For content mode, provide the host-owned content element and switch using the
|
|
84
|
+
host loader's content configuration.
|
|
85
|
+
|
|
86
|
+
## 5. Handle the export event
|
|
87
|
+
|
|
88
|
+
The XLSX mapping app sends the generated workbook to the host:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
window.addEventListener('message', (event) => {
|
|
92
|
+
if (event.data?.type !== 'TOOLBOX_EXPORT_DATA') return
|
|
93
|
+
if (!(event.data.file instanceof Blob)) return
|
|
94
|
+
|
|
95
|
+
const url = URL.createObjectURL(event.data.file)
|
|
96
|
+
const link = document.createElement('a')
|
|
97
|
+
link.href = url
|
|
98
|
+
link.download = event.data.fileName || 'export.xlsx'
|
|
99
|
+
link.click()
|
|
100
|
+
URL.revokeObjectURL(url)
|
|
101
|
+
})
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
The host can hide or destroy the instance through the app loader. The package
|
|
105
|
+
unmounts its React root when the loader removes the instance container; it does
|
|
106
|
+
not remove the host-owned container itself.
|
|
107
|
+
|
|
108
|
+
## Checklist
|
|
109
|
+
|
|
110
|
+
- Publish the JavaScript bundle and stylesheet.
|
|
111
|
+
- Fetch the CDN metadata for `arbo-xlsx-mapping`.
|
|
112
|
+
- Register `xlsx_toolbox` in the loader configuration.
|
|
113
|
+
- Dynamically import the package and call `createXlsxMappingInstance()`.
|
|
114
|
+
- Provide runtime keys and required session storage values.
|
|
115
|
+
- Register the package stylesheet in `moduleStyles`.
|
|
116
|
+
- Wait for `appLoader.ready` before switching instances.
|
|
117
|
+
- Handle `TOOLBOX_EXPORT_DATA` in the host application.
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@arbocollab/arbo-xlsx-mapping` are documented here.
|
|
4
|
+
|
|
5
|
+
## ๐ฆ Stable release (`latest` tag)
|
|
6
|
+
### [0.0.1] - 2026-09-18
|
|
7
|
+
- Added the initial npm package publication for onboarding and distribution setup.
|
|
8
|
+
- Published as the stable `latest` release.
|
|
9
|
+
- No product feature release was included in this version.
|
|
10
|
+
|
|
11
|
+
## ๐งช Alpha release (`beta` tag)
|
|
12
|
+
### [0.0.2-alpha.3] - 2026-09-24
|
|
13
|
+
- update README.md with proper setup and instrunctions.
|
|
14
|
+
- add CHANGELOG.md.
|
|
15
|
+
- add ARBO_XLSX_MAPPING_APP_LOADER.md for details instructions on how to mount the library onto the app.
|
|
16
|
+
- restric the origin for the post message
|
|
17
|
+
|
|
18
|
+
### [0.0.2-alpha.2] - 2026-09-23
|
|
19
|
+
- update PreviewGrid.tsx portal div and prevent it from clipped with the body.
|
|
20
|
+
|
|
21
|
+
### [0.0.2-alpha.1] - 2026-09-22
|
|
22
|
+
- fix conflict tailwind global variable when mounted package to production build.
|
|
23
|
+
|
|
24
|
+
### [0.0.2-alpha.0] - 2026-09-21
|
|
25
|
+
- Started the `0.0.2` alpha prerelease line for beta testing on npm.
|
package/README.md
CHANGED
|
@@ -1,37 +1,201 @@
|
|
|
1
|
-
# @arbocollab/arbo-xlsx-mapping
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
1
|
+
# @arbocollab/arbo-xlsx-mapping
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<strong>Browser-only spreadsheet mapping UI for TESSR task-upload files.</strong>
|
|
5
|
+
</p>
|
|
6
|
+
|
|
7
|
+
<p align="center">
|
|
8
|
+
<img src="https://img.shields.io/badge/version-0.0.2--alpha.3-blue" alt="Version">
|
|
9
|
+
<img src="https://img.shields.io/badge/react-19.1-brightgreen" alt="React 19">
|
|
10
|
+
<img src="https://img.shields.io/badge/vite-6.3-646cff" alt="Vite">
|
|
11
|
+
<img src="https://img.shields.io/badge/license-private-red" alt="License">
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
Converts a client's own spreadsheet into a TESSR task-upload `.xlsx`. All
|
|
15
|
+
processing happens in the browser โ there is no backend and spreadsheet files
|
|
16
|
+
never leave the user's machine.
|
|
17
|
+
|
|
18
|
+
## โจ Key features
|
|
19
|
+
|
|
20
|
+
| Feature | Description |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| ๐ฅ **Spreadsheet import** | Reads the client's workbook and validates supported spreadsheet input. |
|
|
23
|
+
| ๐๏ธ **Sheet and header selection** | Choose the source sheet and the row containing column headers. |
|
|
24
|
+
| ๐ **Column mapping** | Map source columns to the TESSR template with automatic matching assistance. |
|
|
25
|
+
| ๐งฉ **Column combining** | Join multiple source columns with separators or labelled blocks. |
|
|
26
|
+
| ๐จ **Formatting preservation** | Preserves bold and italic rich-text runs through import, mapping, editing, and export. |
|
|
27
|
+
| ๐ **Editable preview** | Review results in an Excel-like Glide Data Grid before export. |
|
|
28
|
+
| โฉ๏ธ **Edit history** | Undo and redo preview edits, including paste and fill operations. |
|
|
29
|
+
| ๐๏ธ **Row management** | Soft-delete and restore rows during review. |
|
|
30
|
+
| ๐พ **Mapping persistence** | Remembers mappings by the column shapes of both files. |
|
|
31
|
+
| ๐ฆ **Reusable package** | Provides ES module and production UMD bundle outputs for host applications. |
|
|
32
|
+
|
|
33
|
+
## ๐ Prerequisites
|
|
34
|
+
|
|
35
|
+
- Node.js 22.x, as pinned in `.node-version`
|
|
36
|
+
- npm
|
|
37
|
+
- A modern browser with File APIs and Blob support
|
|
38
|
+
|
|
39
|
+
## ๐ Quick start
|
|
40
|
+
|
|
41
|
+
Install dependencies and start the development server:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npm install
|
|
45
|
+
npm run dev
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Run the quality checks:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npm test
|
|
52
|
+
npm run typecheck
|
|
53
|
+
npm run build
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## ๐ฆ Package usage
|
|
57
|
+
|
|
58
|
+
Install the published package:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
npm install @arbocollab/arbo-xlsx-mapping@beta
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
The host loader can load the package dynamically, pass its runtime keys, and
|
|
65
|
+
mount it into a host-owned element:
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
const { createXlsxMappingInstance } = await import(
|
|
69
|
+
/* webpackIgnore: true */ XLSX_TOOLBOX_URL,
|
|
70
|
+
)
|
|
71
|
+
|
|
72
|
+
const host = document.querySelector<HTMLElement>('#xlsx-toolbox')
|
|
73
|
+
if (!host) throw new Error('Missing #xlsx-toolbox container')
|
|
74
|
+
|
|
75
|
+
const instance = createXlsxMappingInstance(runtimeKeys)
|
|
76
|
+
instance.mount(host)
|
|
77
|
+
|
|
78
|
+
// When the host hides or removes the application:
|
|
79
|
+
instance.unmount()
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
The adapter does not remove the host element. The host owns the container
|
|
83
|
+
lifecycle and calls `unmount()` before removing it.
|
|
84
|
+
|
|
85
|
+
For the full Arbo App Loader integration, including CDN loading, runtime keys,
|
|
86
|
+
stylesheet registration, instance switching, and export handling, see
|
|
87
|
+
[docs/ARBO_XLSX_MAPPING_APP_LOADER.md](docs/ARBO_XLSX_MAPPING_APP_LOADER.md).
|
|
88
|
+
|
|
89
|
+
When the user exports a workbook, the application sends the generated file to
|
|
90
|
+
the host with a `TOOLBOX_EXPORT_DATA` message:
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
{
|
|
94
|
+
type: 'TOOLBOX_EXPORT_DATA',
|
|
95
|
+
file: Blob,
|
|
96
|
+
fileName: 'export.xlsx',
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The production bundle also includes `index.umd.js` for direct browser-script
|
|
101
|
+
loading. It exposes:
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
window.ArboXlsxMapping.createXlsxMappingInstance
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
## ๐ Application flow
|
|
108
|
+
|
|
109
|
+
1. Upload the client's spreadsheet and the TESSR template.
|
|
110
|
+
2. Select the source sheet and header row.
|
|
111
|
+
3. Map source columns to template columns.
|
|
112
|
+
4. Review, edit, delete, restore, undo, or redo rows.
|
|
113
|
+
5. Confirm and export the task-upload workbook.
|
|
114
|
+
|
|
115
|
+
## ๐ Project structure
|
|
116
|
+
|
|
117
|
+
```text
|
|
118
|
+
src/
|
|
119
|
+
โโโ core/ Framework-free workbook and mapping logic
|
|
120
|
+
โโโ components/ui/ Hand-edited generic UI primitives
|
|
121
|
+
โโโ ui/ React application composition
|
|
122
|
+
โโโ arbo-app-instance.tsx Reusable mount/unmount adapter
|
|
123
|
+
โโโ App.tsx Application shell
|
|
124
|
+
scripts/
|
|
125
|
+
โโโ prepare-package.mjs npm package preparation
|
|
126
|
+
lib/ Generated, ignored package output
|
|
127
|
+
docs/ Architecture and research documentation
|
|
128
|
+
issues/ Work items and feature decisions
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
The core remains framework-free. `src/core/workbook.ts` is the only application
|
|
132
|
+
file that imports ExcelJS; test helpers may use it directly as well.
|
|
133
|
+
|
|
134
|
+
## ๐ ๏ธ Tech stack
|
|
135
|
+
|
|
136
|
+
| Category | Technology |
|
|
137
|
+
| --- | --- |
|
|
138
|
+
| Framework | React 19 |
|
|
139
|
+
| Language | TypeScript |
|
|
140
|
+
| Build tool | Vite 6 |
|
|
141
|
+
| Styling | Tailwind CSS 4 and hand-edited shadcn/ui primitives |
|
|
142
|
+
| Spreadsheet engine | ExcelJS |
|
|
143
|
+
| Preview grid | Glide Data Grid |
|
|
144
|
+
| Testing | Vitest |
|
|
145
|
+
|
|
146
|
+
## ๐ข Development and release process
|
|
147
|
+
|
|
148
|
+
### npm package publishing and release
|
|
149
|
+
|
|
150
|
+
For each release, first update `package.json` to a new version and update
|
|
151
|
+
[CHANGELOG.md](CHANGELOG.md). Then prepare and publish either a beta or
|
|
152
|
+
production package.
|
|
153
|
+
|
|
154
|
+
### Authentication
|
|
155
|
+
|
|
156
|
+
Never commit an npm token. Keep `npmjs.npmrc` ignored and provide `NPM_TOKEN`
|
|
157
|
+
through the shell environment:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
npm whoami --userconfig=./npmjs.npmrc
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
The account must have publish permission for the `@arbocollab` scope. Staged
|
|
164
|
+
publishing requires an npm CLI version that supports `npm stage` and a
|
|
165
|
+
stage-only token.
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
# Beta
|
|
169
|
+
npm run build:beta
|
|
170
|
+
npm run package:beta
|
|
171
|
+
npm pack ./lib --dry-run
|
|
172
|
+
npm publish ./lib --userconfig=./npmjs.npmrc --access public --tag beta
|
|
173
|
+
# Optional: use this instead of npm publish for staged publishing
|
|
174
|
+
npm stage publish ./lib --userconfig=./npmjs.npmrc --access public --tag beta
|
|
175
|
+
|
|
176
|
+
# Production
|
|
177
|
+
npm run build:production
|
|
178
|
+
npm run package:production
|
|
179
|
+
npm pack ./lib --dry-run
|
|
180
|
+
npm publish ./lib --userconfig=./npmjs.npmrc --access public --tag latest
|
|
181
|
+
# Optional: use this instead of npm publish for staged publishing
|
|
182
|
+
npm stage publish ./lib --userconfig=./npmjs.npmrc --access public --tag latest
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
Verify a published release with:
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
npm view @arbocollab/arbo-xlsx-mapping versions
|
|
189
|
+
npm view @arbocollab/arbo-xlsx-mapping dist-tags
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## ๐ Changelog
|
|
193
|
+
|
|
194
|
+
See [CHANGELOG.md](CHANGELOG.md) for the version history. The published
|
|
195
|
+
package also includes the changelog at:
|
|
196
|
+
|
|
197
|
+
<https://cdn.jsdelivr.net/npm/@arbocollab/arbo-xlsx-mapping@beta/CHANGELOG.md>
|
|
198
|
+
|
|
199
|
+
## ๐ License
|
|
200
|
+
|
|
201
|
+
Private โ internal use within the Arbo ecosystem.
|