Web Component API

ScopeView also provides Web Components with headers, legends, controls, tables and pinned details. They consume the same documents as the headless factories, with additional UI and state APIs.

Use this page to look up the shared API. For a working example with copyable source, open metric charts, trace timelines or flame graphs.

Register and mount

import '@scopedb/scopeview/register';
import { requests } from './chart.js';

const chart = document.createElement('scope-chart');
chart.theme = 'system';
chart.document = requests;
document.querySelector('#chart')!.append(chart);

requests is defined in getting started. Registration is browser-only. To register individual families, import defineScopeChart, defineScopeTrace or defineScopeFlame from /element and call the corresponding function.

Tag	Document	Reference
scope-chart	ChartDocumentInput	Metric charts
scope-trace	TraceDocument	Trace timeline
scope-flame	ProfileDocument	Flame graph

A child <script type="application/json"> can supply a declarative document. Property assignment takes precedence. The getter returns a copied, normalized document.

Common properties and methods

Member	Behavior
document	Set data and reset local view state; invalid input displays an error
updateDocument(input, { preserveViewState: true })	Refresh data while retaining compatible state
configure(ui)	Patch host UI; replace nested objects/arrays; preserve document and view state
theme	Mode shortcut (default 'light') or strict theme object; mode reflects to the attribute
loading	Show the loading state and suspend the rendered view
error	Host error string; set null to clear it
refresh()	Refresh after inherited style changes
viewState	Get or restore a copied portable view state
controls	Snapshot of available actions, labels and disabled/expanded states
performAction(action)	Perform an enabled action; return whether it was accepted
scene, diagnostics	Current rendering model/counters, or null without an active runtime
linkedHighlight	Passive host-projected cross-chart emphasis

configure works before or after document assignment, and its settings persist when data is replaced. Unknown keys or invalid values throw without changing the UI, document or state. Use document for a deliberate reset, or updateDocument for a refresh of the same logical source.

Loading and host errors are separate from the document. Clear them when data is ready:

chart.loading = true;
chart.error = null;
// After the application obtains a valid snapshot:
chart.document = requests;
chart.loading = false;

Remove the element with chart.remove() on unmount. Disconnect releases buffers and listeners; reconnect creates a runtime for the retained document.

Disclosure options

Set component UI with configure. Documents contain only plot settings:

chart.configure({
  axes: 'minimal',
  header: false,
  toolbar: { actions: ['inspect', 'toggle-data'], attribution: false }
});

The options reference lists accepted values and defaults. Use component UI for headers, tooltips, tables, toolbars, legends, axes and pinned details. Metric options and trace/profile options remain in the document. Styling covers host size and themes.

document.options.interactive controls input; trace/profile document.options.rowHeight controls row height. To patch plot options while keeping state:

const document = chart.document!;
chart.updateDocument({ ...document, options: { ...document.options, interactive: false } },
  { preserveViewState: true });

Events

Events bubble and cross Shadow DOM. ScopeView element listeners are typed by /element.

chart.addEventListener('scope-select', (event) => {
  if (event.detail.pinned) console.log(event.detail.rows);
  console.log(event.detail.context);
});
chart.addEventListener('scope-error', (event) => {
  console.error(event.detail.message);
});

scope-inspect and scope-select details include context, using the same serializable source context as headless callbacks. It contains a snapshotId, exact original values and field or hierarchy information for the displayed snapshot, and is null when the reading is cleared. Existing detail fields remain available, and trace/profile elements infer their corresponding context types.

For every family, scope-select describes the persistent selection: its key and context are null and pinned is false when keyboard navigation or dismissal clears selection, even while scope-inspect reports a transient reading. When data is replaced, preserved selections emit updated context after the replacement paints, and removed or cleared selections emit null. Track inspection events rather than treating scope-ready, which also fires after repainting, as a selection invalidation signal.

Event	Detail
scope-ready	Rendered visualization and row/node counts; may fire after repaint
scope-error	{ message }
scope-inspect, scope-select	Family, key, pin state and copied original sources
scope-controls-change	{ controls }
scope-view-state-change	{ state, reason }
scope-visibility-change	Metric hidden-series names
scope-viewport-change	Trace/profile { start, end, scrollOffset }
scope-collapse-change	Trace/profile { collapsed }

Metric inspection uses rows and rowIndices, with time/provenance where available. Trace/profile inspection uses typed sources. Dismissal sends a null key and empty sources. scope-ready is not a one-time mount event; use { once: true } for an initial action.

Custom toolbar

Place controls in slot="toolbar" to replace the built-in toolbar:

<scope-trace id="trace">
  <nav slot="toolbar" aria-label="Chart controls"></nav>
</scope-trace>

Read controls, render a button per action, and call performAction(action) when clicked. Listen for scope-controls-change to update labels and disabled/expanded states. Keep buttons keyed by action so refreshing their state preserves focus. The live component examples show a complete implementation in their index.html tab.

Family	Actions
All	inspect, toggle-data
Metric	show-all
Trace/profile	zoom-in, zoom-out, reset-view, toggle-collapse

toolbar.actions filters displayed controls in the standard order. It does not disable keyboard shortcuts or programmatic actions; use document.options.interactive or the host dataTable switch for that. Slotted controls stay inside the chart's interaction boundary and preserve current readings.

Hierarchy navigation

Trace and profile components add viewport, collapsed, toggleNode(id), focusNode(id, { pin? }) and resetViewport(). Call focus/viewport actions after the chart is ready and measured. The viewport stores normalized horizontal fractions and CSS-pixel vertical scroll. Collapsing hides descendants without changing source weights or durations.

For persistence, linked charts and controlled metric time ranges, see view state and coordination.