Insight API

import {
  Insight,
  clearPersistedChart,
  version,
} from '@chartbuddy.io/embed';

Constructor

const insight = new Insight(target, options?);

target

CSS selector string or HTMLElement.

options

Option	Type	Default	Description
chartData	object	—	Partial or full chart config
instanceId	string	random UUID	Stable id for getInsights() / persist. Must be unique on the page — duplicates throw.
editable	boolean	false	Start in editor mode
editSession	'toggle' | 'locked'	'toggle'	'locked' = always edit (no Done / morph chrome). Implies edit boot.
persist	boolean	false	Persist to localStorage
host	object	—	Host chrome hooks — see Host overrides
assetBase	string	—	Only for multi-file loader; ignore with single-file

Instance

Member	Description
ready	Promise — resolves when mounted
mode	'view' | 'edit'
editSession	'toggle' | 'locked'
chart	Engine chart instance
instanceId	Stable id for this mount
setChartData(cd)	Merge a full or partial config and redraw (chartType optional)
setData(seriesData)	Refresh only the data grid — keeps type and formatting
update(patch?)	Partial patch + redraw; no argument = redraw only
getChartData()	Full cd snapshot
on(event, handler)	Subscribe to ready | mode | change (returns unsubscribe)
off(event, handler)	Remove a handler
isDirty()	true when the chart changed since boot / last Done
getRevision()	Monotonic edit counter
toPngBlob() / toPngBase64()	PNG without a Save dialog (agent-friendly)
downloadPng()	Download PNG (human Save dialog)
exportConfig()	Download current chartData as JSON
enterEditMode()	View → edit (no-op when editSession: 'locked')
exitEditMode()	Edit → view (no-op when locked; checkpoints when persist: true)
focus()	Focus the insight
destroy()	Tear down

Host overrides

Optional options.host hooks for embedding inside your own chrome:

Hook	Description
getToolbarPlacement()	Where the formatting toolbar lives: 'widget' (default embed edit — morph rail), 'float', or 'dock'.
getToolbarContainer()	Mount point for the toolbar (selector or element). Ignored when placement is 'widget' (modules mount in the morph).
positionToolbar(toolbar, target)	Float-only XY override. Ignored for 'dock' / 'widget'.
getPopupContainer()	Where portaled menus mount (selector or element). Default: document.body. Use your dialog root when the editor sits in a high-z overlay.
startDragging(event)	Forward chart-background drag to host window chrome.

new Insight('#chart', {
  editable: true,
  editSession: 'locked',
  host: {
    getToolbarPlacement: () => ({ mode: 'dock', side: 'right' }),
    getToolbarContainer: () => '#my-toolbar-rail',
    getPopupContainer: () => '#my-dialog',
  },
});

Partial updates

await insight.ready;

// Data only — Chart.js-shaped
insight.setData([
  ['', 'Q1', 'Q2'],
  ['Revenue', 100, 120],
]);

// Any partial patch
insight.update({ title: { text: 'FY26' } });

// Redraw without changing config
insight.update();

// setChartData also accepts partials — chartType is not required
insight.setChartData({ seriesData: [/* … */] });

Events

insight.on('ready', () => { /* booted */ });
insight.on('mode', (mode) => { /* 'view' | 'edit' */ });
insight.on('change', (cd) => { /* after meaningful edits */ });

insight.isDirty();     // since boot / last Done checkpoint
insight.getRevision(); // increments on every meaningful change

change fires after programmatic setChartData / setData / update, live edits in edit mode, and Done.

Validation

new Insight({ chartData }), setChartData, setData, and update validate input at the API boundary:

Input	Behaviour
Unknown chartType (e.g. bubbleChart3D)	Throws (with a did-you-mean hint)
Wrong field type / enum / range	Throws (lists every path)
Foreign option bag (pie + bar: {…})	Throws
Ragged seriesData (unequal row lengths)	Warns, still accepts
Duplicate instanceId on the page	Throws
Unknown keys	Always allowed (forward-compatible)

Throws are ChartDataValidationError, which carries the problems as structured data — and the same checks are callable directly, so you can validate before you mount. See Validation.

import { validateChartData } from '@chartbuddy.io/embed';

const { valid, errors } = validateChartData(candidate);
if (!valid) console.log(errors[0].path, errors[0].code, errors[0].suggestion);

PNG / export

await insight.ready;
const png = await insight.toPngBase64(); // default background #ffffff
await insight.downloadPng();
insight.exportConfig();

PNG download and drag-to-slide are also available from the view-mode hover ball.