Published-release documentation · release compatibility

Charts, Data, and Composition Actions

Each declared action has an exact signature and its own stable link. Option tables are generated from types; behavior prose names the owning workflow and its constraints. API layers and H0–H4 catalog role tags are independent classifications. Relative action hierarchy is determined by composition, not by a tag or fixed trace depth.

createCanvas

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

createCanvas(options?: CanvasOptions): ChartProgram;

Named option contracts: CanvasOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createCanvas({ width?, height?, background?, margin?, plot? })

Create the program’s Canvas and plot bounds. Canvas options

editCanvas

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

editCanvas(options: CanvasOptions): ChartProgram;

Named option contracts: CanvasOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

editCanvas({ width?, height?, background?, margin?, plot? })

Edit Canvas properties and rematerialize connected consumers. Canvas options

fitCanvas

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

fitCanvas(options?: FitCanvasOptions): ChartProgram;

Named option contracts: FitCanvasOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

fitCanvas({ padding?, minPlotWidth?, minPlotHeight?, iterationLimit?, overflow? })

Fit an existing Full unit chart by shrinking its margins on a fixed Canvas. The action uses deterministic 0.25px probes and preserves semantic state, explicit scale ranges, guide policies, Canvas width, and Canvas height. The default overflow policy rejects an unsatisfied minimum plot atomically; overflow: "report" stores a structured result on materializationConfigs.fitting.

applyTextMetrics

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.24. See release compatibility.

applyTextMetrics(options: ApplyTextMetricsOptions): ChartProgram;

Named option contracts: ApplyTextMetricsOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

applyTextMetrics({ profile })

Apply a host-measured width profile to title, axis, legend, label, and composition layout. See Measured text layout for the exact profile format, matching rules, propagation, and executable example.

removeTextMetrics

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.24. See release compatibility.

removeTextMetrics(): ChartProgram;

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

removeTextMetrics()

Remove the active profile and rematerialize with deterministic width estimates. See Measured text layout for lifecycle and composition behavior.

applyTheme

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

applyTheme(options: ApplyThemeOptions): ChartProgram;

Named option contracts: ApplyThemeOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

applyTheme({ theme, scope? })

Use "light", "dark", or a custom partial definition such as:

program.applyTheme({
  theme: {
    base: "light",
    tokens: {
      mark: "#b91c1c",
      grid: "#d1fae5",
      fontFamily: "Inter"
    }
  }
});

Custom definitions accept these token keys: background, mark, text, strongText, mutedText, axis, axisTitle, grid, border, sizeSymbol, regressionBand, boxLine, boxMedian, referenceLine, referenceBand, gradientCenter, highlight, fontFamily, axisLabel, axisLabelFontFamily, axisTitleFontFamily, axisLabelFontSize, and axisTitleFontSize. Font sizes must be positive finite numbers; other tokens must be non-empty strings. A new theme replaces the previous request; omitted partial tokens come from the new base.

Axis label and title font tokens affect only axes, including Polar and Parallel axes. Omitted role fonts fall back to fontFamily; omitted sizes retain each axis family’s default. axisLabel overrides label color; without it, Cartesian and Polar labels use text, and Parallel labels use axis. axisTitle controls axis title color. Explicit axis styles win, even when equal to a built-in default. Active fonts are used during initial guide layout as well as later theme edits.

A unit chart defaults to scope: "self". A composition defaults to scope: "descendants", which updates its root, current nested children, and children later rebuilt by facet or repeat edits. Use scope: "self" on a composition to change only its root Canvas background.

Explicit mark, guide, title, legend block, facet header, and highlight styles take precedence. Field-driven palettes, semantic data, scales, grouping, statistics, and ordering are preserved. Font token changes recalculate text bounds and composition layout.

removeTheme

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

removeTheme(): ChartProgram;

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

removeTheme()

Remove the most recently applied theme scope on that receiver. Composition removal deletes only that composition’s frame, so a previously hidden child or ancestor theme becomes active again. Explicit local styles remain unchanged.

createData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

createData<Row extends object>(options: CreateDataOptions<Row>): ChartProgram;

Named option contracts: CreateDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createData({ id?, values })

Create one immutable named dataset. Data

reviseData

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.24. See release compatibility.

reviseData<Row extends object>(options: ReviseDataOptions<Row>): ChartProgram;

Named option contracts: ReviseDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

reviseData({ source, id, values })

Create a fresh original-data revision and atomically update its dependent chart. The original is retained; IDs and styles of existing chart owners remain stable. See Data updates.

removeData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

removeData(options: RemoveResourceOptions): ChartProgram;

Named option contracts: RemoveResourceOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

removeData({ id })

Remove one explicitly named dataset only when no mark, downstream dataset, retained recipe, or owned resource still refers to it. Context and historical trace mentions do not keep it alive. A standalone logical derived-data owner removes its current snapshot and owner record together. This Full-only action does not infer, cascade, or change graphics. Source and Derived Data

removeScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

removeScale(options: RemoveResourceOptions): ChartProgram;

Named option contracts: RemoveResourceOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

removeScale({ id })

Remove one explicitly named unused semantic scale and its resolved cache entry. Every encoding, Parallel dimension, guide, and retained authoring binding is checked first. The Full-only action does not rewire consumers or rebuild graphics. Scale Options

removeCoordinate

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

removeCoordinate(options: RemoveResourceOptions): ChartProgram;

Named option contracts: RemoveResourceOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

removeCoordinate({ id })

Remove one explicitly named unused coordinate after checking layer, guide, annotation, and retained data-space bindings. A context pointer is cleared, but no replacement coordinate is inferred. This action is Full-only. Coordinates

bindMarkData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

bindMarkData(options: BindMarkDataOptions): ChartProgram;

Named option contracts: BindMarkDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

bindMarkData({ target, data })

Atomically connect one independent mark to an existing materialized dataset. The action preflights its fields, scales, guides, labels, selections, and highlights before it rematerializes every registered consumer. Source and Derived Data

filterData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

filterData(options: FilterDataOptions): ChartProgram;

Named option contracts: FilterDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

filterData({ id, source?, field, oneOf | noneOf | predicate | range, nulls? })

Create an immutable named derived dataset using exactly one membership, comparison, or range filter. The source defaults to current data. Data

createDensityData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

createDensityData(options: DensityDataOptions): ChartProgram;

Named option contracts: DensityDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createDensityData({
  id, source?, field, groupBy?, bandwidth?, extent?, steps?,
  kernel?, normalization?, weight?, missing?, as?
})

Create immutable KDE rows on one shared inclusive sample grid. Source defaults to current data, steps to 100, bandwidth to an automatic Scott-rule estimate, kernel to "gaussian", and normalization to "unit". Data

createRegressionData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

createRegressionData(options: RegressionDataOptions): ChartProgram;

Named option contracts: RegressionDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createRegressionData({
  id, source?, x, y, groupBy?, method?, degree?, span?, robustIterations?,
  confidenceMethod?, level?, confidence?, interval?, predict?, missing?
})

Create immutable linear, polynomial, LOESS, or exponential fitted rows at observed unique x values. Linear and polynomial fits support normal or Student-t mean or prediction bounds; LOESS is line-only. Optional robustIterations (integer 0..32, default 0) adds residual reweighting; see regression for the estimator policy. Data

createRegressionStatisticsData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

createRegressionStatisticsData(options: RegressionStatisticsDataOptions): ChartProgram;

Named option contracts: RegressionStatisticsDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createRegressionStatisticsData({ id, source })

Create observation counts, intercepts, slopes, and R-squared from an explicit existing linear fit. Grouped fits retain their original grouping field and typed first-seen group order. Constant responses produce rSquared: null. Linear fit statistics

createWindowData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

createWindowData(options: WindowDataOptions): ChartProgram;

Named option contracts: WindowDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createWindowData({ id, source?, partitionBy?, sortBy?, operations, temporalUnit? })

Create an immutable derived dataset by applying ordered row-number, rank, dense-rank, cumulative-sum, lag, lead, moving-mean, or moving-sum operations within optional partitions. Moving frames support row counts or closed elapsed durations, minPeriods, and explicit nullish skipping. The calculation follows a stable sort while the output preserves source row order. Window data transforms

createTimeUnitData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

createTimeUnitData(options: TimeUnitDataOptions): ChartProgram;

Named option contracts: TimeUnitDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createTimeUnitData({ id, source?, field, temporalUnit?, unit, as?, timeZone?, weekStartsOn?, weekRule? })

Create an immutable row-preserving dataset with one UTC or IANA-zone calendar bucket timestamp, including week, or a nominal local weekday field. Omit as to use ${field}_${unit}; output-name collisions are rejected. Time-unit data transforms

createBin2DData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

createBin2DData(options: Bin2DDataOptions): ChartProgram;

Named option contracts: Bin2DDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createBin2DData({
  id, source?, x, y, bins?, extent?, includeEmpty?, members?, as?
})

Aggregate finite x/y pairs into deterministic rectangular cell bounds and counts. Reusing the logical ID creates an immutable revision and rematerializes direct visual consumers. Rectangular 2D bins

editBin2DData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

editBin2DData(options: EditBin2DDataOptions): ChartProgram;

Named option contracts: EditBin2DDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

editBin2DData({
  target?, source?, x?, y?, bins?, extent?, includeEmpty?, members?, as?,
  dependents?
})

Partially revise the current or unique logical 2D-bin owner. Omitted top-level transform options are preserved; successful edits create an immutable revision, rebind direct visual consumers, and safely release the prior revision. Rectangular 2D bins

editDerivedData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editDerivedData(options: EditDerivedDataOptions): ChartProgram;

Named option contracts: EditDerivedDataOptions.

Behavior, inference, resets, and errors: Focused core data editing.

editFilteredData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editFilteredData(options: EditFilteredDataOptions): ChartProgram;

Named option contracts: EditFilteredDataOptions.

Behavior, inference, resets, and errors: Focused core data editing.

editTimeUnitData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editTimeUnitData(options: EditTimeUnitDataOptions): ChartProgram;

Named option contracts: EditTimeUnitDataOptions.

Behavior, inference, resets, and errors: Focused core data editing.

editWindowData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editWindowData(options: EditWindowDataOptions): ChartProgram;

Named option contracts: EditWindowDataOptions.

Behavior, inference, resets, and errors: Focused core data editing.

editDensityData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editDensityData(options: EditDensityDataOptions): ChartProgram;

Named option contracts: EditDensityDataOptions.

Behavior, inference, resets, and errors: Focused core data editing.

editRegressionData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editRegressionData(options: EditRegressionDataOptions): ChartProgram;

Named option contracts: EditRegressionDataOptions.

Behavior, inference, resets, and errors: Focused core data editing.

editRegressionStatisticsData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editRegressionStatisticsData(options?: EditRegressionStatisticsDataOptions): ChartProgram;

Named option contracts: EditRegressionStatisticsDataOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

editRegressionStatisticsData({ target?, source? })

Revise a standalone statistics owner’s linear fit source and replay its consumers atomically. Omitted source preserves the current fit. Target omission requires a current or unique statistics owner. Linear fit statistics

createCoordinate

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

createCoordinate(options?: CreateCoordinateOptions): ChartProgram;

Named option contracts: CreateCoordinateOptions.

Behavior, inference, resets, and errors: Semantic resources and regression layers.

editCoordinate

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editCoordinate(options: EditCoordinateOptions): ChartProgram;

Named option contracts: EditCoordinateOptions.

Behavior, inference, resets, and errors: Semantic resources and regression layers.

createScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

createScale(options: CreateScaleOptions): ChartProgram;

Named option contracts: CreateScaleOptions.

Behavior, inference, resets, and errors: Extension and scale contracts.

editScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

editScale(options: EditScaleOptions): ChartProgram;

Named option contracts: EditScaleOptions.

Behavior, inference, resets, and errors: Extension and scale contracts.

editXScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editXScale(options: EditXScaleOptions): ChartProgram;

Named option contracts: EditXScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editYScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editYScale(options: EditYScaleOptions): ChartProgram;

Named option contracts: EditYScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editXOffsetScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editXOffsetScale(options: EditXOffsetScaleOptions): ChartProgram;

Named option contracts: EditXOffsetScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editYOffsetScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editYOffsetScale(options: EditYOffsetScaleOptions): ChartProgram;

Named option contracts: EditYOffsetScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editParallelScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editParallelScale(options: EditParallelScaleOptions): ChartProgram;

Named option contracts: EditParallelScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editThetaScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editThetaScale(options: EditThetaScaleOptions): ChartProgram;

Named option contracts: EditThetaScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editRScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editRScale(options: EditRScaleOptions): ChartProgram;

Named option contracts: EditRScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editColorScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editColorScale(options: EditColorScaleOptions): ChartProgram;

Named option contracts: EditColorScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editStrokeScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editStrokeScale(options: EditStrokeScaleOptions): ChartProgram;

Named option contracts: EditStrokeScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editSizeScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editSizeScale(options: EditSizeScaleOptions): ChartProgram;

Named option contracts: EditSizeScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editOpacityScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editOpacityScale(options: EditOpacityScaleOptions): ChartProgram;

Named option contracts: EditOpacityScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editShapeScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editShapeScale(options: EditShapeScaleOptions): ChartProgram;

Named option contracts: EditShapeScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editStrokeWidthScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editStrokeWidthScale(options: EditStrokeWidthScaleOptions): ChartProgram;

Named option contracts: EditStrokeWidthScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

editStrokeDashScale

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.24. See release compatibility.

editStrokeDashScale(options: EditStrokeDashScaleOptions): ChartProgram;

Named option contracts: EditStrokeDashScaleOptions.

Behavior, inference, resets, and errors: Focused channel scale editors.

createDerivedData

API layer: user-facing. Authoring roles: H2.

Availability: Available by v0.0.13. See release compatibility.

createDerivedData(options: CreateDerivedDataOptions): ChartProgram;

Named option contracts: CreateDerivedDataOptions.

Behavior, inference, resets, and errors: Semantic resources and regression layers.

filterMarks

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

filterMarks(options: FilterMarksOptions): ChartProgram;

Named option contracts: FilterMarksOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

filterMarks({ target?, mode?, grain?, field | channel | property, op, ...operands })

Retain matching final mark items through the shared selector grammar. Repeated filters are idempotent when equal and use explicit replace or compose mode when different. Empty results preserve the preceding scale domains. An explicit Raincloud parent ID selects raw observations by field at item grain and recomputes all enabled components. It accepts comparisons, sets, ranges, and grouped ranks; rendered channel/property selectors still require a child ID. Raincloud source filters retain the nonempty input requirements of their enabled statistical components; named-child empty filters remain supported. Data

removeMarkFilter

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

removeMarkFilter(options?: RemoveMarkFilterOptions): ChartProgram;

Named option contracts: RemoveMarkFilterOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

removeMarkFilter({ target? })

Restore a filtered mark to its canonical source, recover its prior Histogram bin policy, and retain any filtered dataset snapshot that still has downstream users. Data

removeMarkHighlight

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

removeMarkHighlight(options?: RemoveMarkSelectionOptions): ChartProgram;

Named option contracts: RemoveMarkSelectionOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

removeMarkHighlight({ selection? } = {})

Remove one highlight assignment, restore the target mark and categorical legend baseline, and retain the reusable selection. Selection lifecycle

highlightMarks

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

highlightMarks(options: HighlightMarksOptions): ChartProgram;

Named option contracts: HighlightMarksOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

highlightMarks({
  id?, target?, select?, selection?, color?, opacity?, fill?, stroke?,
  strokeWidth?, strokeDash?, shape?, size?, offset?, dimOthers?, bringToFront?
})

Select point, bar, line, area, arc, or rule items inline or reuse a stored selection, then apply mark-specific concrete emphasis, optional complement dimming, and selected-last order. Mark selection and highlighting

editCompositionLayout

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

editCompositionLayout(options: EditCompositionLayoutOptions): ChartProgram;

Named option contracts: EditCompositionLayoutOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

editCompositionLayout({ columns?, gap?, spacing?, align?, padding? })

Edit spacing, cross-axis alignment, or outer padding on an existing composition. columns changes wrapping only on a facet composition and is rejected for concat. Omitted values are preserved, child identity is unchanged, and the parent snapshot is rebuilt from retained child programs. Facet parents accept gap: {x, y} to set horizontal and vertical distances separately; both keys are required and each value must be finite and non-negative. A pair replaces both axes, while an omitted gap preserves its current form. Concat continues to require a numeric gap.

replaceCompositionChild

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

replaceCompositionChild(options: ReplaceCompositionChildOptions): ChartProgram;

Named option contracts: ReplaceCompositionChildOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

replaceCompositionChild({ target, program })

Replace one named child while preserving its slot ID and order. The replacement must already be a complete chart or composition program.

insertCompositionChild

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

insertCompositionChild(options: InsertCompositionChildOptions): ChartProgram;

Named option contracts: InsertCompositionChildOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

insertCompositionChild({ id, program, before?, after? })

Insert a complete chart or nested composition under a new stable child name. Use either before or after; omitting both appends the child.

removeCompositionChild

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

removeCompositionChild(options: RemoveCompositionChildOptions): ChartProgram;

Named option contracts: RemoveCompositionChildOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

removeCompositionChild({ target })

Remove one named concat child and rebuild layout. A concat may retain one child, but its final child cannot be removed.

reorderCompositionChildren

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

reorderCompositionChildren(options: ReorderCompositionChildrenOptions): ChartProgram;

Named option contracts: ReorderCompositionChildrenOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

reorderCompositionChildren({ order })

Provide every current concat child ID exactly once in its new order. Child program references stay unchanged while placements and snapshots are rebuilt.

facet

API layer: user-facing. Authoring roles: H0.

Availability: Available by v0.0.13. See release compatibility.

facet(options: FacetOptions): ChartProgram;

Named option contracts: FacetOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

facet({ id?, field, data?, values?, columns?, gap?, spacing?, align?, padding?, scales?, guides?, headers? })

Repeat one complete Cartesian, Polar, or Parallel chart by a field on its common row-preserving dataset ancestor. Values preserve source first appearance; scale policies can be "shared" or "independent" by supported role, including Polar theta/public r and all parallelDimensions. Layered regression data, statistical descendants, data-bound Cartesian text, attached labels, and references recompute per cell. Text needs x/y scales and a text encoding. guides: { axes: "outer" } keeps axes only on occupied outer cells, while guides: { legend: "shared" } promotes one compatible parent-owned legend at the child legend’s configured left, right, top, or bottom edge. Top and bottom promotion also preserves the child legend’s horizontal alignment; author those options with createLegend before calling facet. Promoted outside legends use the existing recipe offset from the combined panel plots. Omitted offsets clear retained axis and header text; explicit colliding offsets reject. Child Canvas dimensions and margins remain intact, and the inferred parent Canvas contains the child snapshots and the complete legend bounds. A guides.legend object declares a native parent legend against the final child-plot union using ordinary LegendOptions defaults. Existing whole/focused/block legend editors and removal accept that facet, grid or repeat parent. Declare an absent owner with editFacetGuides({ legend: {...} }); post-facet createLegend stays unit-only. Target IDs name source marks. Corners/free coordinates and block-local anchors use the union and preserve child dimensions, automatic policies and editable persistence. See parent legend creation. See Program composition.

Facet, grid and field repetition also accept gap: {x, y}. A number still applies one distance in both directions and keeps its stored form. A pair must contain exactly those two finite non-negative values; partial objects and unknown keys reject, even for one row or column. The distances separate child canvases, plots, or retained content according to the existing spacing mode. Grid still supports only canvas/plot spacing. Header clearance and final overlap checks remain active independently in both directions. The pair survives layout edits, source replay and editable persistence. See independent axis gaps.

Creation options for facet, facetGrid, and repeatCharts accept headers. Set common fontSize, fontFamily, fontWeight, color, offset, align, or labelMap, and optional row/column objects with role-specific overrides and side. Common styles are applied before role overrides. Row headers require a two-field grid; its column sides are top/bottom, while one-field facets and repeats also allow left/right column headers. The option uses the same values, layout, and precedence as editFacetHeaders; authored styles survive themes and source replay. Omitting headers preserves the default headers. With spacing: "plot", headers stay aligned to their panel plots and sit outside retained axis text and local legend ink, including outward Polar labels. Header lanes are recalculated after guide edits. The requested plot gap and child Canvas sizes remain unchanged; insufficient interior guide/header space rejects the operation.

facetGrid

API layer: user-facing. Authoring roles: H0.

Availability: Available by v0.0.13. See release compatibility.

facetGrid(options: FacetGridOptions): ChartProgram;

Named option contracts: FacetGridOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

facetGrid({ id?, data?, rows, columns, combinations?, gap?, spacing?, align?, padding?, scales?, guides?, headers? })

Repeat one supported Cartesian, Polar, or Parallel chart over two ordered categorical fields. combinations: "observed" retains the coordinates of observed pairs; "full" also creates explicit empty cells that retain their semantic layers, coordinate, header, and shared or explicit-domain local guides.

repeatCharts

API layer: user-facing. Authoring roles: H0.

Availability: Available by v0.0.13. See release compatibility.

repeatCharts(options: RepeatChartsOptions): ChartProgram;

Named option contracts: RepeatChartsOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

repeatCharts({ id?, target?, channel, fields, columns?, gap?, spacing?, align?, padding?, scales?, guides?, headers? })

Repeat one direct mark by replacing Cartesian x/y, eligible Polar theta/public r, or one { parallelDimension: field }. The repeated role is independently scaled by default; request a shared policy explicitly to use the union domain. Attached labels and statistical references owned by the target replay with it. Pie/Radar raw positional roles, derived targets, unrelated layers, and composite roles are rejected with explicit errors.

editFacetSource

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

editFacetSource(options: EditFacetSourceOptions): ChartProgram;

Named option contracts: EditFacetSourceOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

editFacetSource({ program })
editFacetSource({ action: { method, options? } })

Reapply the current facet, grid, or repeat recipe to a revised complete unit program while preserving the partition dataset ID, ordered domains, layout, scale/guide policy, headers, and parent title. All stored facet values must remain observed; create a new composition when the dataset ID, domain, or repeat field list changes. Alternatively, pass one actual unit chart-authoring action name and its options to edit the retained full-data source in the same transaction. Specify exactly one of program or action; extension primitives, materializers, and composition actions cannot be source edits.

editFacetHeaders

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

editFacetHeaders(options: EditFacetHeadersOptions): ChartProgram;

Named option contracts: EditFacetHeadersOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

editFacetHeaders({ fontSize?, fontFamily?, fontWeight?, color?, offset?, role?, labelMap?, side?, align?, rotation?, title? })

Edit the parent-owned repeated facet headers and rebuild the parent snapshot without changing child programs or facet value order. One-field facets and repeats accept all four sides with role: "column"; left/right placements reserve a measured lane beside every physical column. Row-column grids retain left/right row headers and top/bottom column headers. Role-specific title: { text: "Region" } adds one field title across the occupied plots, separately from category headers and the chart title. Initial options use headers.column.title or grid headers.row.title. A first title requires one-line text; partial edits preserve it and title: false removes it. Title style inherits its role header, with optional fontSize/fontFamily/fontWeight/color, align, rotation, offset and alongOffset overrides. Common/all titles are rejected.

editFacetScales

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

editFacetScales(options: FacetScaleResolutions): ChartProgram;

Named option contracts: FacetScaleResolutions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

editFacetScales({ x?, y?, xOffset?, yOffset?, theta?, r?, color?, stroke?, size?, shape?, opacity?, strokeDash?, parallelDimensions? })

Partially change used facet channels between "shared" and "independent". Every cell is rederived from the retained pre-facet program while field, data, value order, child IDs, layout, guides, headers, and title are preserved. Public r addresses semantic radius; parallelDimensions applies the policy separately to every Parallel dimension.

editFacetGuides

API layer: user-facing. Authoring roles: H3.

Availability: Available by v0.0.13. See release compatibility.

editFacetGuides(options: FacetGuideOptions): ChartProgram;

Named option contracts: FacetGuideOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

editFacetGuides({ axes?, legend? })

Partially change axes between "each" and "outer", or legend ownership between false and "shared". Shared legend promotion requires concretely compatible child scales and guide recipes. Polar and Parallel axes remain child-local and reject "outer".

createScatterPlot

API layer: user-facing. Authoring roles: H0.

Availability: Available by v0.0.13. See release compatibility.

createScatterPlot(options: CreateScatterPlotOptions): ChartProgram;

Named option contracts: CreateScatterPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createScatterPlot({ id?, data?, coordinate?, x, y, color?, stroke?, size?, shape?, point?, missing?, guides? })

Create a complete Cartesian point chart from required x/y fields and optional appearance encodings. Basic Charts

createTextPlot

API layer: user-facing. Authoring roles: H0.

Availability: Available by v0.0.24. See release compatibility.

createTextPlot(options: CreateTextPlotOptions): ChartProgram;

Named option contracts: CreateTextPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createTextPlot({ id?, data?, coordinate?, x, y, text, color?, style?, guides? })

Create a Cartesian data-text chart from required positions and content. Available in the full entry only. Strings name fields; constant text uses { value }. Basic Charts

createDotPlot

API layer: user-facing. Authoring roles: H0, H1.

Availability: Available by v0.0.13. See release compatibility.

createDotPlot(options: CreateDotPlotOptions): ChartProgram;

Named option contracts: CreateDotPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createDotPlot({ id?, data?, coordinate?, category, value, orientation?, summary?, point?, labels?, guides? })

Create categorical dots from raw rows by default. Set summary explicitly to mean, median, sum, min, or max to aggregate one dot per category.

createLollipopPlot

API layer: user-facing. Authoring roles: H0, H1.

Availability: Available by v0.0.13. See release compatibility.

createLollipopPlot(options: CreateLollipopPlotOptions): ChartProgram;

Named option contracts: CreateLollipopPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createLollipopPlot({ id?, data?, coordinate?, category, value, orientation?, summary?, baseline?, point?, stem?, labels?, guides? })

Create a value point and a stem to a finite baseline, which defaults to zero. The point and stem use the same source grain and quantitative scale.

createDumbbellPlot

API layer: user-facing. Authoring roles: H0, H1.

Availability: Available by v0.0.13. See release compatibility.

createDumbbellPlot(options: CreateDumbbellPlotOptions): ChartProgram;

Named option contracts: CreateDumbbellPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createDumbbellPlot({ id?, data?, coordinate?, category, start, end, orientation?, summary?, startPoint?, endPoint?, connector?, labels?, guides? })

Create named start and end points with a connector. Endpoint identity stays attached to its field and appearance when values reverse or coincide. Because two fields share the value scale, its ambiguous axis title is omitted by default. Set guides.axes.x.title for a horizontal plot or guides.axes.y.title for a vertical plot to provide one explicitly.

editEndpointPlot

API layer: user-facing. Authoring roles: H1, H3.

Availability: Available by v0.0.13. See release compatibility.

editEndpointPlot(options: EditEndpointPlotOptions): ChartProgram;

Named option contracts: EditEndpointPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

editEndpointPlot({ target?, data?, coordinate?, category?, value?, start?, end?, orientation?, summary?, baseline? })

Atomically revise the semantic roles of a Dot, Lollipop, or Dumbbell facade. Owned points, rules, labels, and summary data are replaced together while the original appearance and guide policy are retained. When a changed role or source changes an axis domain, tick samples from the previous domain are inferred again while retaining their label and line styles. Separately added statistical references retain their source endpoint, styles, and labels, recompute from the revised observations, and follow the measurement axis when orientation changes.

createECDFPlot

API layer: user-facing. Authoring roles: H0, H1.

Availability: Available by v0.0.13. See release compatibility.

createECDFPlot(options: CreateECDFPlotOptions): ChartProgram;

Named option contracts: CreateECDFPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createECDFPlot({ id?, data?, coordinate?, field, groupBy?, weight?, missing?, as?, color?, line?, labels?, guides? })

Create a right-continuous empirical cumulative distribution as an ordinary step-after line. Ties share one jump, probability is fixed to [0,1], and optional grouping controls both statistical denominators and path identity.

editECDFPlot

API layer: user-facing. Authoring roles: H1, H3.

Availability: Available by v0.0.13. See release compatibility.

editECDFPlot(options: EditECDFPlotOptions): ChartProgram;

Named option contracts: EditECDFPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

editECDFPlot({ target?, data?, coordinate?, field?, groupBy?, weight?, missing?, as?, color? })

Atomically revise an ECDF source or statistical role and rebuild its owned derived rows, path, final-series labels, and guides under the stable owner ID. Ungrouping also removes a coupled group color unless a replacement is supplied.

createIntervalPlot

API layer: user-facing. Authoring roles: H0, H1.

Availability: Available by v0.0.13. See release compatibility.

createIntervalPlot(options: CreateIntervalPlotOptions): ChartProgram;

Named option contracts: CreateIntervalPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createIntervalPlot({ id?, data?, coordinate?, x, y, xOffset?, yOffset?, groupBy?, color?, point?, errorBar?, guides? })

Create center points and matching statistical or explicit intervals from one shared dataset, coordinate, and pair of scales. The x/y interval vocabulary is the same as createErrorBar; child point and error-bar styles remain independently editable through their existing owners. When scale IDs are omitted, the complete owner uses ${id}X and ${id}Y so unrelated earlier channel scales cannot make the call order dependent.

createRegressionPlot

API layer: user-facing. Authoring roles: H0, H1.

Availability: Available by v0.0.13. See release compatibility.

createRegressionPlot(options: CreateRegressionPlotOptions): ChartProgram;

Named option contracts: CreateRegressionPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createRegressionPlot({ id?, data?, coordinate?, x, y, color?, size?, shape?, point?, groupBy?, method?, band?, line?, guides? })

Create a scatter plot with fitted regression data, a line, and optional interval bands. groupBy: false is preserved as an explicit ungrouped model request.

createLinePlot

API layer: user-facing. Authoring roles: H0.

Availability: Available by v0.0.13. See release compatibility.

createLinePlot(options: CreateLinePlotOptions): ChartProgram;

Named option contracts: CreateLinePlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createLinePlot({ id?, data?, coordinate?, x, y, color?, groupBy?, strokeDash?, line?, guides? })

Create a complete Cartesian line chart. groupBy accepts one field or a non-empty tuple, assigned before independent series color and dash. Basic Charts

Categorical x (nominal or ordinal) accepts point/band scales and raw quantitative or aggregate y. Vertices follow the x domain; absent an explicit domain, categories follow first appearance. Duplicate-category rows keep source order. Missing categories are not synthesized, and remaining observations connect across their category spacing.

createPolarScatterPlot

API layer: user-facing. Authoring roles: H0.

Availability: Available by v0.0.13. See release compatibility.

createPolarScatterPlot(options: CreatePolarScatterPlotOptions): ChartProgram;

Named option contracts: CreatePolarScatterPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createPolarScatterPlot({ id?, data?, coordinate?, theta, radius, color?, size?, shape?, point?, missing?, guides? })

Create a complete Polar point chart from required angular and radial fields. Radial position remains independent from size and constant point.radius. Polar positions

createPolarLinePlot

API layer: user-facing. Authoring roles: H0.

Availability: Available by v0.0.13. See release compatibility.

createPolarLinePlot(options: CreatePolarLinePlotOptions): ChartProgram;

Named option contracts: CreatePolarLinePlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createPolarLinePlot({ id?, data?, coordinate?, theta, radius, groupBy?, color?, strokeDash?, line?, guides? })

Create grouped Polar paths from required angular and radial fields. Paths stay open unless line.closed: true is explicit. Polar positions

createRadarPlot

API layer: user-facing. Authoring roles: H0.

Availability: Available by v0.0.13. See release compatibility.

createRadarPlot(options: CreateRadarPlotOptions): ChartProgram;

Named option contracts: CreateRadarPlotOptions.

The following call patterns are abbreviated examples; the declaration above owns the complete option set.

createRadarPlot({ id?, data?, coordinate?, category, value, groupBy?, order?, color?, strokeDash?, line?, guides? })
createRadarPlot({ id?, data?, coordinate?, wide: { fields, as? }, groupBy?, order?, color?, strokeDash?, line?, guides? })

Create closed Radar paths from validated long rows or an explicit wide-to-long Fold. Every series must contain the same ordered dimensions exactly once. Values are used as supplied; the facade does not infer normalization. Polar positions

editRadarPlot

API layer: user-facing. Authoring roles: H1, H3.

Availability: Available by v0.0.24. See release compatibility.

editRadarPlot(options: EditRadarPlotOptions): ChartProgram;