EIDOS JavaScript Bindings

A lightweight, reactive JavaScript library for embedding and controlling EIDOS visualizations in web applications. Built with Valtio for natural object mutations and AJV for comprehensive schema validation.

Features

- 🚀 Natural API: Mutate EIDOS specs using standard JavaScript object assignment
- ⚡ Reactive Updates: Changes automatically propagate to the renderer via JSON patches
- 🔍 Schema Validation: Comprehensive validation using AJV with detailed error messages
- 🎯 Framework Agnostic: Works with React, Vue, Svelte, and vanilla JavaScript
- 📦 Lightweight: Small bundle size with efficient reactivity
- 🔒 Type Safe: Full TypeScript support

Quick Start

$3

``bash
npm install @oceanum/eidos
`

$3

`tsx
import { EidosProvider, useEidosSpec } from "@oceanum/eidos";

// Define your EIDOS specification
const initialSpec = {
version: "0.9",
id: "my-app",
name: "My Visualization",
root: {
id: "root",
nodeType: "world",
children: [],
},
data: [],
};

function App() {
return (
initialSpec={initialSpec}
options={{
renderer: "https://render.eidos.oceanum.io",
eventListener: (event) => console.log("Event:", event),
}}
>


);
}

// In any child component
function YourComponent() {
const spec = useEidosSpec();

const addLayer = () => {
// Mutate spec directly - changes propagate automatically to iframe
spec.root.children.push({
id: "new-layer",
nodeType: "worldlayer",
layerType: "track",
});
};

return Add Layer;
}
`

$3

`javascript
import { render } from "@oceanum/eidos";

// Define your EIDOS specification
const spec = {
version: "0.9",
id: "my-app",
name: "My Visualization",
root: {
id: "root",
nodeType: "world",
children: [],
},
data: [],
};

// Render in a container element
const container = document.getElementById("eidos-container");
const result = await render(container, spec, {
renderer: "https://render.eidos.oceanum.io",
eventListener: (event) => {
console.log("Received event:", event);
},
});

// Mutate the spec naturally - changes propagate automatically
result.spec.name = "Updated Visualization";
result.spec.root.children.push({
id: "layer-1",
nodeType: "worldlayer",
layerType: "track",
});

// Clean up when done
result.destroy();
`

Advanced Usage

$3

The React Context API allows you to easily manage multiple EIDOS instances in the same application. Each EidosProvider creates its own isolated context with its own iframe and spec.

Option 1: Multiple Providers (Recommended)

`tsx
import { EidosProvider, useEidosSpec } from "@oceanum/eidos";

function App() {
return (


function ChartControls() {
const spec = useEidosSpec(); // Gets chartSpec from nearest provider
// Completely isolated from MapControls
const updateData = () => {
spec.data[0].dataSpec = newData;
};
return Update Data;
}
`

Option 2: Low-Level Render API

For more control, use the render() function directly:

`tsx
import { render } from "@oceanum/eidos";
import { useEffect, useRef, useState } from "react";

function MultiInstance() {
const container1 = useRef(null);
const container2 = useRef(null);
const [specs, setSpecs] = useState({ map: null, chart: null });

useEffect(() => {
const init = async () => {
const map = await render(container1.current, mapSpec, { renderer: EIDOS_URL });
const chart = await render(container2.current, chartSpec, { renderer: EIDOS_URL });

setSpecs({ map: map.spec, chart: chart.spec });

return () => {
map.destroy();
chart.destroy();
};
};

init();
}, []);

const updateMap = () => {
if (specs.map) {
specs.map.root.viewState.zoom += 1;
}
};

return (