@csvbox/adapter

Shared core logic for csvbox's framework adapters — the embed protocol every framework wrapper (React, Vue 2, Vue 3, Angular) delegates to instead of duplicating it: import-URL construction, the postMessage init/event protocol, modal open/close lifecycle, and event metadata parsing.

Plain JS, no build step, no type ceremony — one file (index.js), small functions, read top to bottom. Type declarations live alongside it in index.d.ts.

Contents

• index.js — the module. Every exported function below lives here.
• index.d.ts — TypeScript declarations for the same exports.
• package.json — name @csvbox/adapter, main/types pointing at the two files above.

API

• DEFAULT_DOMAIN — "app.csvbox.io", the default embed host.
• HOLDER_STYLE / IFRAME_STYLE — the holder/iframe CSS values for the full-viewport fixed overlay (z-index: 2147483647, etc.), as plain JS style objects.
• buildImportUrl(config, framework, libraryVersion) — builds the embed URL: domain (with optional customDomain/dataLocation prefixing), library-version, framework, preventRedirect, language, theme, env query params.
• generateUuid() — generates the per-instance correlation token used to match incoming postMessage events to the right button instance.
• buildInitPayload(user, dynamicColumns, options, uniqueToken) — builds the { customer, columns, options, unique_token } object posted into the iframe once it loads.
• createModalLifecycle() — returns { markReady(), requestOpen(), markClosed() }, a small state machine for the deferred-open behavior: if openModal() is requested before the iframe has finished loading, it's queued and fired once markReady() is called from the iframe's onload. DOM creation and the actual postMessage/display-toggle calls are the caller's responsibility — this only tracks state.
• classifyStructuredMessage(data, expectedToken) — classifies an incoming structured { type, data } message, gated on data.data.unique_token === expectedToken. Returns null if unrecognized or the token doesn't match, otherwise { type, metadata?, success? } for one of: data-on-submit, data-push-status, csvbox-modal-hidden, csvbox-upload-successful, csvbox-upload-failed.
• classifyLegacyMessage(data) — classifies a legacy bare-string message ('mainModalHidden', 'uploadSuccessful', 'uploadFailed'), sent/accepted with no token check. Kept separate from the structured classifier since not every consumer speaks this protocol.
• parseSubmitMetadata(eventData) — parses data-on-submit metadata.
• parseImportMetadata(eventData) — parses data-push-status success metadata, including reconstructing per-row objects from the importer's column-index arrays + headers (_dynamic_data / _virtual_data / _unmapped_data), with dropdown-label remapping (dropdown_display_labels_mappings) when present. data-push-status failure isn't parsed at all — pass data.data straight through.

Modal lifecycle behavior: reset-on-close

createModalLifecycle()'s markClosed() resets all internal state (isModalShown, isIframeLoaded, shouldOpenOnReady) back to pristine, not just the "shown" flag. Callers are expected to pair this with actually destroying the iframe/holder DOM and nulling the reference on close, so that the next openModal() call — gated on !iframe, unconditionally, not just under a lazy flag — creates a completely fresh iframe: fresh embed URL load, fresh generateUuid() token.

This means every reopen does a full iframe reload rather than an instant visibility toggle. That's deliberate: the hosted importer app doesn't re-run whatever validation produced its first-load state (e.g. an invalid-license error) when it's simply re-shown via a stale, already-loaded session — only a genuinely fresh load forces it through that path again. Verified with a standalone HTML file, no framework or adapter code involved at all, that this is the importer's own behavior, not something any adapter package causes or can intercept (it happens inside a cross-origin iframe).

If you're wiring a new consumer against this module: call markReady() from the iframe's onload, call requestOpen() whenever you want to open (showing the modal only if it returns true), and call markClosed() plus destroy the iframe/holder whenever a close signal comes in — mainModalHidden / csvbox-modal-hidden via the classifiers above.