@mk7s/holochart-runtime

Classes

Class	Description
Chart	A chart bound to a DOM element. Create with createChart (or newPlot). All update methods return a promise that resolves with the chart once the result is fully drawn.
WebGLUnavailableError	Thrown by createChart (and the rejection of newPlot / react / toImage) when no WebGL2 context can be created: the browser lacks WebGL2, it is disabled, or the GPU is blocklisted. cause holds the renderer's own error.

Interfaces

Interface	Description
AnimatingFrameEvent	Payload of animatingframe: the frame that starts now.
AnimationOptions	Options of Chart.animate (Plotly's animationOpts).
AnnotationEventData	Payload of clickannotation (emitted by the annotations component, E5.4).
AxisInfo	A cartesian axis as seen by traces and components.
BinsInsight	Histogram bins: [start, end) per bin and the bin's value (count, density, …).
BoxesInsight	Box plots and violins: five-number summaries per box.
CalcContext	Context for calc and extremes.
CameraAnimationOptions	Options of Chart.animateCamera.
CameraAnimationRun	What ComponentView.animateCamera gets: timing, the eased curve and the subplot.
CameraTarget	Where Chart.animateCamera moves a 3D scene's camera: Plotly's scene.camera shape, in scene units; missing vectors and components keep their current values.
CameraVector	A camera vector (eye, center, up) of CameraTarget: missing components stay.
ChartDescription	The accessible description of a chart.
ChartEvents	Event payloads by name (plan §7.5).
ChartFigureSource	What chartToJSON reads from a chart. Chart provides data, layout and config; frames, datasets and registry are read when the chart exposes them.
ChartOptions	Options for createChart that are not part of the figure.
ChartPoint	One data point in a hover, click or selection event (plan E6.1), shaped like Plotly's event points so handlers port unchanged.
ChartRegistry	-
ChartRegistryOptions	-
ChartThree	Escape hatches into three.js (plan §7.2, E8.13). renderer and scene are three.js objects; the members typed by the render package (root, overlay, viewports, subplot) are experimental like that package.
ChartToJSONOptions	Options for chartToJSON.
ColorbarSpec	A colorbar request from one trace (E5.3).
ComponentDrawContext	Context for component drawing: the solved layout and the overlay viewport.
ComponentExtremesContext	Context for ComponentModule.extremes.
ComponentLayoutContext	Context for ComponentModule.pushMargin.
ComponentModule	A layout component (plan E22.3): core's layout schema/defaults plus optional margin pushes and drawing. Axes (E3.4), legend (E5.2), title (E5.1), … are components; so are third-party watermarks or brushes.
ComponentPointerEvent	A pointer event offered to component views before the chart's own hover / zoom / selection handling (see ComponentView.handlePointer). The object is reused between events: read it during the call, don't keep it.
ComponentRenderer	-
ComponentUpdatePlan	What changed since a component view's last update.
ComponentView	-
ComputedFrame	A frame with its baseframe chain applied (the frame of animatingframe).
CrossTraceContext	Context for TraceModule.crossTraceCalc. The subplot's rect and axis lengths are current; ranges and transforms are still those of the previous layout pass (autorange needs extremes, which run after cross-trace calc), so work in linear units, not px.
CrossTraceEntry	One trace's calc as seen by TraceModule.crossTraceCalc. The calc is the one the trace's slot holds: a fresh object when the trace was recalculated this pass (calc / calcAppend), else the object the previous cross-trace pass mutated.
DescribeContext	Context for TraceModule.describe.
DescribedTable	A data table, ready for the DOM (hidden rows already capped).
DomainInfo	Where a trace in the domain category (pie, later sunburst, indicator, …) is placed: its domain.x / domain.y (or the layout.grid cell its domain.row / domain.column picked, resolved during supply-defaults) mapped onto the plot area. Domain traces have no axes: they draw into the overlay viewport, whose world units are container CSS px with a bottom-left origin, so a container point (x, y) is at world (x, viewport.size.height - y). Use fitAspect / inscribedCircle (exported by the runtime) to keep circular traces round inside the rect.
DomainLayoutContext	Context for TraceModule.crossTraceLayout: the solved figure layout.
DomainTraceEntry	One domain trace as seen by TraceModule.crossTraceLayout.
DownloadImageOptions	Options of chart.downloadImage / downloadImage(el, …).
DrawGesture	A shape-drawing gesture (E5.5): with a draw dragmode (drawline, drawopenpath, drawclosedpath, drawcircle, drawrect), a drag that starts on a cartesian subplot's plot area — and that no view took through handlePointer — is offered to component views' ComponentView.drawShape, topmost first, once per animation frame while it moves, then once more when it ends. A press without a drag stays a click. The runtime only tracks the pointer; the view previews and commits the shape (the shapes component does, with newshape).
FigureInput	A figure as passed by the user (plan ADR-001).
FigurePatch	A partial figure for Chart.update: merged into the current figure.
FrameInput	An animation frame (figure.frames[i], addFrames): trace and layout changes applied as one step, like Plotly's frames.
FrameOptions	Per-frame timing of animate.
FullSelection	A defaulted layout.selections[i] (see core's selections schema).
FxSettings	Interaction settings resolved from the defaulted figure.
GridInsight	A grid of values (heatmaps, contours, 2D histograms), z[j * nx + i].
HierarchyClickEventData	Payload of sunburstclick, treemapclick and icicleclick (M5, E13.2–E13.4; Plotly's plotly_sunburstclick, …): the clicked node and the level the click drills to, absent when it does not drill (a sunburst's root and leaves).
HoverContext	Axes and transform of the trace being queried, for converting between linear and px.
HoverPoint	A point a trace reports under the pointer.
HoverQuery	A hover query in one subplot. x/y modes ask for the points at the pointer's x (or y) — the runtime builds unified labels (x unified, y unified) from those results.
KeyboardPoint	A stop of keyboard navigation (see TraceModule.keyboardPoints): the hover point whose label it shows, and what navigation needs beyond it.
KeyboardStops	The stops of a trace: an array, or anything with a length that builds stop i on demand (a grid of many cells).
LatestQueue	See the module docs.
LayoutTween	An animated layout attribute (see ComponentView.layoutTweens).
LegendEventData	Payload of legendclick / legenddoubleclick (emitted by the legend component, E5.2).
LegendGlyph	What the legend draws for one trace (E5.2). Colors are CSS color strings.
LegendIconContext	Context for TraceModule.legendIcon.
LegendItem	One per-point legend item (M2 wave 1, see TraceModule.legendItems).
MarginPush	Room (CSS px) a component needs on each side of the plot area (legend, colorbar, automargin).
PointerEventData	Payload of hover, unhover and click.
PricesInsight	Open, high, low, close per point (candlestick, OHLC).
RegistryListing	Summary of what is registered (registry.list()).
SelectArea	A non-cartesian subplot's selection area (see ComponentView.selectArea).
SelectionEventData	Payload of selecting and selected (E6.3).
SelectionQuery	A box or lasso selection in one subplot, in the trace's linear coordinates. On a non-cartesian subplot (a SelectArea: polar) the coordinates are container px (top-left origin).
SeriesInsight	Values along a position: lines, areas, markers, bars on ordered axes.
SharesInsight	Parts of a whole: pie slices, funnel stages, category bars, hierarchy branches, sankey flows.
SubplotInfo	A cartesian subplot ('xy', 'x2y2'): one scissored 2D viewport (ADR-004, ADR-008).
SubplotMirror	A secondary view of one cartesian subplot's traces (M3 wave 2, E5.9). Each trace on the subplot gets a second TraceView from its module's plot.create, drawn into the mirror's viewport with the mirror's axes (same type, categories and range breaks as the subplot's, the mirror's ranges and length) and transform. The runtime updates the mirror views with the main views' update plans (data, style, selection), so they stay in step; set only changes transforms. Mirror views get no pointer events and are not hoverable. Traces that draw on several subplots (splom cells) are not mirrored.
SubplotMirrorOptions	Where and how a SubplotMirror draws: its viewport rect and the linear ranges of its x and y axes (the traces' own linear space, so a range slider passes the linear range of its span).
SubplotViewportOptions	A non-cartesian subplot's own viewport (M6: 3D scenes; GEO2: map projections; ADR-004), from TracePlotContext.subplotViewport / ComponentDrawContext.subplotViewport.
TemplateContext	Where template variables come from. Lookups go in this order; the first defined value wins.
TemplateModule	A named template (layout.template: 'name'), registrable with register.
TemplateOptions	Options for formatTemplate.
ToImageOptions	Options of chart.toImage / toImage(el, …) (Plotly's toImage options, plus transparent).
TraceA11y	The parts of a trace module that TraceModule.a11y loads on first use.
TraceAppend	A streaming change of one trace (E7.2): count points were added at one end by extendTraces (at: 'end') or prependTraces (at: 'start'), and trimmed points were removed from the other end by maxPoints. Retained points keep their values; their index moves by count for prepends and by -trimmed for extends. Several calls batched into one update are merged.
TraceCellRef	One cartesian subplot a multi-subplot trace draws on (M3 wave 2, E10.9; see TraceModule.cells): the ids of its axes, e.g. { xaxis: 'x2', yaxis: 'y3' }.
TraceDescription	A trace's accessible description (E17.1).
TraceExtremes	What a trace contributes to the autorange of each of its axes.
TraceModule	A trace module: core's schema/defaults contract plus the render parts (plan §4.4, E22.1). All render parts are optional, so a core-only module still validates and defaults.
TracePlotContext	Everything a trace renderer may use. A fresh context is passed to every call.
TraceRenderer	The plot part of a trace module (plan E22.1).
TraceUpdatePlan	What changed since the last update of a TraceView. Flags are cumulative downstream: calc implies plot, and plot implies style.
TraceView	A trace's live GPU objects, created by TraceRenderer.create.
TransitionOptions	How long a change animates, with which easing (layout.transition, animate options).
ValueInsight	One value, optionally against a reference (indicators).

Type Aliases

Type Alias	Description
AnimateTarget	What Chart.animate plays: null / undefined for every frame in order, a string or number for the frames of that group, a frame object, or a list of frame names and frame objects (['2007'] plays the frame named '2007'; [null] plays nothing, which with mode: 'immediate' pauses).
AttributeUpdate	Attribute-string edits: { 'marker.color': 'red', 'xaxis.range[0]': 2 }. Keys are attribute paths, so values are not typed: the escape hatch of restyle, whose array values hold one value per trace.
BaseLayout	Figure layout.
CanonicalEvent	The canonical name for an event key.
ChartEventKey	An event name, or its Plotly alias (plotly_<name>).
ChartEventName	-
ChartListener	A listener. Returning false cancels the default action of cancelable events (legendclick).
Config	Chart configuration (non-visual behavior).
DoubleClickAction	What config.doubleClick does on the plot area.
Dragmode	dragmode values. orbit / turntable are for 3D scenes and act like false in 2D. The draw modes (DrawDragmode) hand the gesture to component views (ComponentView.drawShape).
DrawDragmode	The shape-drawing dragmodes (E5.5): a drag on a cartesian subplot draws a new shape.
EasingName	Plotly's easing names (layout.transition.easing, animate's transition.easing).
Hovermode	hovermode values (Plotly semantics).
ImageFormat	Raster formats of ToImageOptions.format.
LayoutInput	A layout as FigureInput takes it by default: the base layout attributes (axes, margins, …) typed, and any other attribute (those of registered components and traces, such as legend or barmode) accepted as it is. The full bundle's Layout types those too. title takes the attributes the title component adds (subtitle, pad, …).
LayoutUpdate	Layout edits for relayout: attribute paths ('xaxis.range[0]', untyped) and whole layout attributes, typed like the layout ({ title: { text: 'Sales' } }). null resets an attribute to its default.
LegendGlyphPart	One piece of a LegendGlyph of kind 'parts': a line segment or a filled rect, in px from the glyph center (x right, y down; the glyph area is legend.itemwidth wide).
MaxPoints	maxPoints of extendTraces / prependTraces (Plotly semantics): one number for every key and trace, or per attribute string an array with one number per listed trace. The options form { maxPoints: n } (plan §7.2) is accepted too. Negative or non-numeric: no limit.
Registrable	Anything register(...) accepts. Locale modules (plan E17.6) are plotly.js's shape, so Plotly locale files register as they are.
StreamUpdate	Streaming updates: per attribute string, one array of new values per listed trace.
TraceA11yParts	What TraceModule.a11y resolves to: the parts of each trace type its chunk serves; '*' holds the parts of any other type (a 3D scene's view keys, for trace modules built on it).
TraceIndices	Which traces an update applies to: one trace index, or several.
TraceInput	A trace of any type, as a registry that does not know it accepts it: the loose default of FigureInput. Any object fits, so partial bundles, plugins and data from untyped sources (JSON, Express) work; the full bundle's Figure (@mk7s/holochart) types every built-in trace instead, and each trace package exports its own trace types (ScatterTrace, TracesBasic, …).
TraceInsight	What a trace's generated summary is about (E17.2), by kind: values along an ordered position (series), parts of a whole (shares), distributions (boxes, bins), a grid of values (grid), prices (prices) or a single value (value). Values are numbers as the trace computes them (linear for axes); the format* functions show them as the chart does.

Variables

Variable	Description
DRAW_DRAGMODES	The shape-drawing dragmodes, in Plotly's modebar order.
Fx	Plotly's Fx namespace: Fx.hover(el, [{ curveNumber, pointNumber }]), Fx.unhover(el).
fxComponent	The built-in fx component: declares the interaction layout attributes (no drawing).
fxLayoutAttributes	Layout attributes of the fx component (hover labels, hover distance, click and select modes).
MAX_TABLE_ROWS	Rows shown per hidden data table; longer data gets a "first N of M" caption.
MIN_PLOT_SIZE	Smallest plot area (CSS px) margins may shrink it to, like Plotly's minreduced{width,height}: big margins on a small figure give way instead of leaving no room for data.
registry	The shared registry used by charts that are not given one. Unlike a fresh createChartRegistry, it starts with the built-in templates and applies holochart to figures without layout.template (ADR-021).
STACK_GROUPS	Trace categories that share cross-trace calc across trace types (see TraceModule.crossTraceCalc): every trace whose module lists one of them stacks / groups with the others on its subplot.

Functions

Function	Description
accessibleText	Plotly rich text (<b>, <br>, <a href>, entities) as plain text for assistive technology: line breaks become spaces, tags are dropped, entities decoded, whitespace collapsed.
addFrames	Plotly addFrames: see Chart.addFrames.
addTraces	Plotly addTraces: see Chart.addTraces.
animate	Plotly animate: play frames by group, name or object. See Chart.animate.
animateCamera	Fly a 3D scene's camera (Holochart extension). See Chart.animateCamera.
chartToJSON	The chart's current input figure (data, layout, config, frames, datasets) encoded as JSON-safe data: JSON.stringify the result to save it, and pass it (or the string) to figureFromJSON or fromJSON to restore it. Keys the chart does not have are left out. The chart is not modified.
countText	1 point, 3 points.
createChart	Create a chart in el (plan §7.2). A chart already in el is destroyed first. The chart draws on the next microtask; await chart.ready (or any update call) to know when the frame is on screen.
createChartRegistry	Create an isolated registry. Most apps use the shared default registry; tests and apps that need different module sets side by side create their own and pass it to createChart.
createLatestQueue	Create a LatestQueue: run performs one request; deliver receives each result that is still current. A rejected run delivers nothing for that request but keeps the queue going.
dataTransform	The transform from linear coordinates to a 2D subplot viewport's world px (origin at the viewport's bottom-left, ADR-008). Each axis' scale is affine in linear space (p = l·m + b, with p measured from range[0]), so a zoom or pan is only a new transform: no buffer uploads.
defineTemplate	Shorthand for a TemplateModule.
deleteFrames	Plotly deleteFrames: see Chart.deleteFrames.
deleteTraces	-
domainRect	A domain trace's rect (plan E4.5): domain.x / domain.y fractions (y from the bottom) of the plot area, in container px. Unlike axis spans this is not rounded: circular traces center on it exactly. Reversed or out-of-range fractions are sorted and clamped to [0, 1].
downloadImage	Plotly's downloadImage: toImage and save the file as <filename>.<format> (default newplot.png). Resolves to the file name.
extendTraces	Plotly extendTraces: append points, optionally keeping a rolling window of maxPoints.
figureFromJSON	Decode a figure saved with chartToJSON (or encoded by Plotly): typed-array specs become typed arrays again, anywhere in the figure. Accepts the JSON text or the parsed value; throws on a non-object or a malformed typed-array spec.
fitAspect	The largest rect of aspect ratio aspect (width / height) centered in rect (plan E4.5: aspect-preserving fit, so pies stay circular in a wide domain).
formatAxisValue	A linear coordinate of axis as its hover label shows it (hoverformat, dates, categories, prefix / suffix), or a plain number without an axis. Non-finite values give ''.
formatPlainNumber	A number with up to 6 significant digits, without trailing zeros (1234.5, 0.000123).
formatTemplate	Fill a Plotly-syntax template (see the module docs). Formats: %{v:<d3-format>} for numbers, `%{v
fromJSON	Create a chart from a saved figure: figureFromJSON then createChart.
getChart	The live chart in el, if any.
hover	Show hover labels and emit hover programmatically (Plotly Fx.hover): points by trace and index, or a position in data units. See Chart.hover.
inscribedCircle	The circle inscribed in a rect: center (container px) and radius (plan E4.5, pie).
isDrawDragmode	Whether mode is a shape-drawing dragmode.
linearExtremes	Autorange extremes of linear coordinates (plan E3.2), for traces whose calc already linearized their data: the minimum and maximum with the px padding each needs (e.g. marker radius). With per-point padding only non-dominated points are kept, which stays small in practice, so autorange cost does not grow with the data. Non-finite values are skipped. (Core's scales also provide a data-space findExtremes(scale, values, opts) with Plotly's full option set.)
linearToPosition	Linear coordinate → selection position (inverse of positionToLinear).
listText	a, a and b, a, b and c.
moveTraces	-
newPlot	Draw a new chart in el, replacing any chart already there. Resolves after the first frame.
parseSelectionPath	Parse a selection polygon (M x,y L x,y … Z, also H / V and the relative commands for numeric axes) into linear coordinates. Each M starts a new ring; only the first ring is used (Plotly's selections are single polygons). undefined for fewer than 3 valid vertices.
polygonContains	Whether (x, y) is inside a polygon (even-odd rule; vertices as [x, y] pairs).
positionToLinear	Linear coordinate of a selection position on axis (NaN when invalid).
prependTraces	Plotly prependTraces: insert points at the start (see extendTraces).
purge	Destroy the chart in el (if any) and free everything it holds, including the note shown instead of a chart without WebGL2.
react	Update el to show a new figure efficiently (diffing), or create the chart if needed.
register	Register modules into the shared registry (plan E21.1 partial bundles):
relayout	Plotly relayout: see Chart.relayout. Takes attribute paths ('xaxis.range[0]', untyped) and whole layout attributes (typed).
restyle	Plotly restyle: see Chart.restyle. Takes attribute paths ('marker.color') whose array values hold one value per trace, so it is not typed against the traces' attributes.
selectionContains	Whether a point (linear coordinates) is inside a selection: the box for rect queries, the polygon for lasso ones. Trace modules use this in selectPoints.
selectionFromQuery	The layout selection a finished box or lasso drag makes (Plotly's newSelections): a rect with the box (an unbounded side — selectdirection h / v — spans the axis range in view) or a path with the lasso polygon, on the subplot's axes.
selectionQuery	The query a selection makes on its subplot's axes: a box for a complete rect, a lasso for a path polygon; undefined when incomplete, invalid or hidden.
selectionsOf	The visible selections of a defaulted layout.
setDefaultTemplate	Set the template the shared registry applies when layout.template is unset: a registered name, or undefined for none. Figures that set layout.template are unaffected. Apps migrating from Plotly call it once, before creating charts, to keep Plotly's look:
splitExtra	Split a hover text into the main label and the <extra> box: extra is undefined when the template has no <extra> tag (the trace name is shown), '' when the box must be hidden.
toImage	Plotly's toImage: render the chart in el — or a figure object ({ data, layout, config }), drawn offscreen without a chart on the page — to an image. Resolves to a data URL. See Chart.toImage for the options (format, width, height, scale, transparent).
traceNameText	The trace's name as plain text, or Plotly's default trace <index>.
unhover	Hide hover labels in el (Plotly Fx.unhover).
update	Plotly update: restyle and relayout in one step.