excel-dnd-toolkit

A framework-independent Excel column mapper for modern browsers. Installing the package can add a small draggable tool button to the right edge of the page. Clicking the button opens the complete workbook import, column mapping, validation, transformation, generation, and download interface in an isolated modal.

The published package is compiled JavaScript. It does not require Python, Streamlit, a backend, API keys, an .env file, or a UI framework dependency.

Features

• Dynamically discovers every column in the selected source and destination worksheets.
• Supports .xlsx and legacy .xls source workbooks and .xlsx destination workbooks.
• Drag-and-drop and keyboard/click column mapping.
• Deterministic automatic heading matching.
• Adds unmatched source fields as new destination columns.
• Merges multiple name fields into one destination.
• Validates phone, email, and date values with inline corrections.
• Derives Full Name and structured address fields offline.
• Generates and downloads the mapped destination workbook in the browser.
• Uses Shadow DOM so host-application CSS cannot change the tool UI.
• Uses a fixed-position launcher and modal, so it does not change page height or layout.

Browser support

The package targets current evergreen Chrome, Edge, Firefox, and Safari. It uses modern browser standards including Custom Elements, Shadow DOM, File, Blob, structuredClone, crypto.randomUUID, and Intl.DisplayNames.

Install in Vue

npm install excel-dnd-toolkit

Add one import to the Vue application entry file, normally src/main.ts or src/main.js:

import { createApp } from "vue";
import App from "./App.vue";
import "excel-dnd-toolkit/auto";

createApp(App).mount("#app");

The floating Excel tool appears automatically on the right edge of the page. It can be dragged vertically and remembers its position in local storage.

No component registration, Vue plugin, stylesheet import, or .env configuration is required.

Controlled integration

Use the controlled API when the host application needs to open, close, reset, or remove the tool programmatically:

import { mountExcelMapper } from "excel-dnd-toolkit";

const mapper = mountExcelMapper(document.body, {
  launcherLabel: "Open customer workbook mapper",
  modalTitle: "Customer Workbook Mapper",
  onGenerated(file, fileName) {
    console.log(fileName, file.size);
  },
  onError(error) {
    console.error(error);
  }
});

mapper.open();
mapper.close();
mapper.reset();
mapper.destroy();

The same API works in React, Angular, Vue, Svelte, and plain JavaScript because it uses only browser DOM APIs.

Custom element

import { defineExcelDndTool } from "excel-dnd-toolkit";

defineExcelDndTool();

<excel-dnd-tool></excel-dnd-tool>

Events

The element dispatches composed, bubbling browser events:

• excel-mapper:mappings-change
• excel-mapper:generated
• excel-mapper:error

document.addEventListener("excel-mapper:generated", (event) => {
  const { file, fileName } = event.detail;
  console.log(file, fileName);
});

Local quality checks

pnpm install
pnpm run check
pnpm audit --prod
pnpm outdated
pnpm pack --dry-run

pnpm run check runs strict TypeScript checking, Biome analysis, unit tests with coverage thresholds, and the production package build.

Publish using an npm account

1. Confirm the final package name and fill in author, repository, and homepage in package.json.

2. Create or sign in to an account at npmjs.com.

3. Authenticate from the package directory:

   npm login
   npm whoami

4. Run the complete verification:

   pnpm run check
   pnpm audit --prod
   pnpm pack --dry-run

5. Publish the first public release:

   npm publish --access public

6. For later releases, update the version before publishing:

   npm version patch
   npm publish

Do not place npm access tokens in this repository or in a package .env file. Use npm login, the user-level npm configuration, or trusted publishing in a CI workflow.

Security and privacy

Workbook processing runs in the browser. Selected workbook contents are not uploaded by this package. Host applications should still apply their own file size policies and content-security requirements.

License

MIT. The production bundle includes SheetJS Community Edition under the Apache License 2.0; see THIRD_PARTY_NOTICES.md and LICENSES/.