@echelon-framework/embed

Lightweight embed script for mounting Echelon components in legacy apps. Zero dependencies, framework-agnostic, ~3KB.

Installation

npm install @echelon-framework/embed

Quick Start (Legacy App)

<!-- Load + auto-configure -->
<script src="https://echelon.company.com/embed.js" data-host="https://echelon.company.com"></script>

<!-- Mount by component ID (not URL) -->
<echelon-embed component="frm_abc123" data='{"clientId":"CLI-001"}'> </echelon-embed>

<!-- Listen for events -->
<script>
  document.querySelector('echelon-embed').addEventListener('echelon-event', (e) => {
    if (e.detail.type === 'submit') {
      saveToLegacySystem(e.detail.payload);
    }
  });
</script>

Programmatic API

import { EchelonEmbed } from '@echelon-framework/embed';

// Initialize once
EchelonEmbed.init({ host: 'https://echelon.company.com' });

// Mount component
const instance = await EchelonEmbed.mount('#container', {
  componentId: 'frm_abc123',
  data: { clientId: 'CLI-001' },
  onEvent: (event) => console.log(event.type, event.payload),
  onReady: (contract) => console.log('requires:', contract.requires),
  onError: (error) => console.error(error.message),
});

// Update data without reload
EchelonEmbed.update('frm_abc123', { clientId: 'CLI-002' });

// Fetch contract (requires/emits) before mounting
const contract = await EchelonEmbed.fetchContract('frm_abc123');

// Cleanup
instance.destroy();
EchelonEmbed.destroyAll();

Features

• iframe + postMessage bridge — full CSS/JS isolation from legacy app
• Contract validation — auto-validates requires before mounting, warns on missing data
• Auto-resize — iframe height adapts to content (ResizeObserver)
• Custom Element — <echelon-embed> works in any framework (React, Vue, jQuery, plain HTML)
• Update without reload — EchelonEmbed.update(id, newData) sends data via postMessage
• Auto-init — data-host attribute on script tag configures automatically

PostMessage Protocol

| Direction | Type | Description | | ---------------- | ------------------ | ----------------------------------- | | legacy → echelon | echelon:init | Send initial data | | legacy → echelon | echelon:update | Update data | | echelon → legacy | echelon:ready | Component loaded | | echelon → legacy | echelon:event | Event (submit, change, cancel) | | echelon → legacy | echelon:resize | Auto-resize iframe height | | echelon → legacy | echelon:contract | Component contract (requires/emits) |

Host Bridge (Echelon App Side)

import { initEmbedHostBridge, emitToParent } from '@echelon-framework/embed/host-bridge';

initEmbedHostBridge({
  onInit: (componentId, data) => {
    /* parent sent initial data */
  },
  onUpdate: (componentId, data) => {
    /* parent updated data */
  },
});

// Send event to parent (legacy app)
emitToParent('submit', { clientId: 'CLI-001', name: 'Acme' });

Component Registry

import {
  registerEmbeddableComponent,
  registerFormsFromStore,
} from '@echelon-framework/embed/registry';

// Auto-register all forms
registerFormsFromStore(formStore.all());

// Manual registration
registerEmbeddableComponent({
  componentId: 'fx-spot-form',
  type: 'form',
  storeId: 'fx-spot-form',
  title: 'FX Spot Transaction',
  requires: [{ name: 'clientData', type: 'object', required: true }],
  emits: [{ event: 'submit', description: 'Transaction submitted' }],
});

License

BUSL-1.1