@arbocollab/arbo-xlsx-mapping 0.0.2-alpha.2 โ†’ 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.
@@ -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
- Browser-only spreadsheet mapping UI for TESSR task-upload files.
4
-
5
- ## Installation
6
-
7
- ~~~bash
8
- npm install @arbocollab/arbo-xlsx-mapping@beta
9
- ~~~
10
-
11
- ## Usage
12
-
13
- ~~~ts
14
- import { createXlsxMappingInstance } from '@arbocollab/arbo-xlsx-mapping'
15
- import '@arbocollab/arbo-xlsx-mapping/style.css'
16
-
17
- const instance = createXlsxMappingInstance()
18
- instance.mount(document.querySelector('#xlsx-mapping'))
19
-
20
- // Call instance.unmount() when the host removes the container.
21
- ~~~
22
-
23
- The application runs in the browser. Uploaded spreadsheets are not sent to a
24
- backend.
25
-
26
- When the user exports a workbook, the host receives a postMessage event:
27
-
28
- ~~~ts
29
- {
30
- type: 'TOOLBOX_EXPORT_DATA',
31
- file: Blob,
32
- fileName: 'export.xlsx',
33
- }
34
- ~~~
35
-
36
- The production bundle also includes index.umd.js for direct browser-script
37
- loading. It exposes window.ArboXlsxMapping.
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.