Layout system for creating complex multi-chart visualizations including faceting, layering, and dashboard-style layouts.
Core composition functions for arranging multiple visualizations.
/**
* Creates layered composition where multiple marks share the same coordinate space
* @returns CompositionNode for layering multiple visualizations
*/
spaceLayer(): CompositionNode;
/**
* Creates flexible space layout with responsive positioning
* @returns CompositionNode for flexible layouts
*/
spaceFlex(): CompositionNode;
/**
* Creates basic view composition container
* @returns CompositionNode for grouping visualizations
*/
view(): CompositionNode;Usage Examples:
// Layered composition with multiple marks
const chart = Chart({
type: "spaceLayer",
children: [
{
type: "line",
data: timeSeriesData,
encode: { x: "date", y: "value" }
},
{
type: "point",
data: eventData,
encode: { x: "date", y: "value", color: "type" }
}
]
});
// Flexible layout
const dashboard = Chart({
type: "spaceFlex",
children: [
{
type: "interval",
data: salesData,
encode: { x: "category", y: "sales" }
},
{
type: "line",
data: trendData,
encode: { x: "date", y: "trend" }
}
]
});Compositions for creating small multiples and faceted visualizations.
/**
* Creates rectangular faceting layout (small multiples)
* @returns CompositionNode for grid-based faceting
*/
facetRect(): CompositionNode;
/**
* Creates circular faceting layout
* @returns CompositionNode for radial faceting
*/
facetCircle(): CompositionNode;
/**
* Creates matrix repetition layout
* @returns CompositionNode for matrix arrangements
*/
repeatMatrix(): CompositionNode;Usage Examples:
// Small multiples with facetRect
const facetedChart = Chart({
type: "facetRect",
data: salesByRegion,
encode: {
x: "month",
y: "sales",
facet: "region"
},
children: [{
type: "line"
}]
});
// Circular faceting
const radialFacets = Chart({
type: "facetCircle",
data: categoryData,
encode: { facet: "category" },
children: [{
type: "interval",
coordinate: { type: "polar" }
}]
});Specialized compositions for geographic and spatial visualizations.
/**
* Creates geographic view composition for map-based visualizations
* @returns CompositionNode for geographic layouts
*/
geoView(): CompositionNode;
/**
* Creates geographic path composition
* @returns CompositionNode for path-based geographic visualizations
*/
geoPath(): CompositionNode;Usage Examples:
// Geographic visualization
const mapChart = Chart({
type: "geoView",
data: geographicData,
children: [{
type: "polygon",
encode: {
geometry: "coordinates",
color: "population"
}
}]
});
// Geographic path visualization
const pathChart = Chart({
type: "geoPath",
data: routeData,
children: [{
type: "line",
encode: {
geometry: "path",
color: "traffic"
}
}]
});Compositions for time-based and animated visualizations.
/**
* Creates timing keyframe composition for temporal animations
* @returns CompositionNode for keyframe-based animations
*/
timingKeyframe(): CompositionNode;Usage Examples:
// Keyframe animation
const animatedChart = Chart({
type: "timingKeyframe",
data: timeSeriesData,
encode: { x: "x", y: "y", key: "timestamp" },
children: [{
type: "point",
animate: {
enter: { type: "fadeIn", duration: 500 }
}
}]
});All compositions support common configuration methods.
interface CompositionNode {
/** Add child visualizations to the composition */
children(...children: (MarkNode | CompositionNode)[]): CompositionNode;
/** Set data for the composition */
data(data: any[]): CompositionNode;
/** Configure visual encodings */
encode(channel: string, field: string): CompositionNode;
/** Apply transforms */
transform(name: string, options?: any): CompositionNode;
/** Set coordinate system */
coordinate(type: string, options?: any): CompositionNode;
/** Configure scales */
scale(channel: string, options?: any): CompositionNode;
/** Add interactions */
interaction(type: string, options?: any): CompositionNode;
/** Apply styling */
style(options: any): CompositionNode;
/** Add layout configuration */
layout(options: LayoutOptions): CompositionNode;
/** Set title */
title(text: string | TitleOptions): CompositionNode;
}
interface LayoutOptions {
/** Layout direction */
direction?: "row" | "column";
/** Spacing between children */
spacing?: number;
/** Padding around composition */
padding?: number | [number, number, number, number];
/** Alignment of children */
align?: "start" | "center" | "end" | "stretch";
/** Justification of children */
justify?: "start" | "center" | "end" | "space-between" | "space-around";
}Compositions can be nested to create complex hierarchical layouts.
Nesting Examples:
// Complex nested layout
const dashboard = Chart({
type: "spaceFlex",
layout: { direction: "column" },
children: [
// Header row
{
type: "spaceFlex",
layout: { direction: "row" },
children: [
{
type: "interval",
data: kpiData,
encode: { x: "metric", y: "value" }
},
{
type: "gauge",
data: [{ value: 75, target: 100 }]
}
]
},
// Main content area
{
type: "spaceLayer",
children: [
{
type: "line",
data: mainData,
encode: { x: "date", y: "value" }
},
{
type: "area",
data: backgroundData,
encode: { x: "date", y: "confidence" },
style: { opacity: 0.3 }
}
]
}
]
});
// Faceted composition with nested layers
const complexFacets = Chart({
type: "facetRect",
data: multiSeriesData,
encode: { facet: "category" },
children: [{
type: "spaceLayer",
children: [
{
type: "line",
encode: { x: "date", y: "actual" }
},
{
type: "line",
encode: { x: "date", y: "forecast" },
style: { lineDash: [5, 5] }
}
]
}]
});Compositions that adapt to container size and screen dimensions.
interface ResponsiveOptions {
/** Breakpoints for different layouts */
breakpoints?: {
mobile?: number;
tablet?: number;
desktop?: number;
};
/** Layout configurations for each breakpoint */
layouts?: {
mobile?: LayoutOptions;
tablet?: LayoutOptions;
desktop?: LayoutOptions;
};
}Responsive Examples:
// Responsive dashboard layout
const responsiveDashboard = Chart({
type: "spaceFlex",
responsive: {
breakpoints: {
mobile: 576,
tablet: 768,
desktop: 1024
},
layouts: {
mobile: { direction: "column", spacing: 10 },
tablet: { direction: "row", spacing: 15 },
desktop: { direction: "row", spacing: 20 }
}
},
children: [
{ type: "interval", data: chartData1 },
{ type: "line", data: chartData2 },
{ type: "point", data: chartData3 }
]
});Event handling for composition-level interactions.
interface CompositionEvents {
/** Child added to composition */
"child:added": (child: MarkNode | CompositionNode) => void;
/** Child removed from composition */
"child:removed": (child: MarkNode | CompositionNode) => void;
/** Layout changed */
"layout:changed": (layout: LayoutOptions) => void;
/** Composition rendered */
"render:complete": () => void;
}Event Examples:
// Composition with event handling
const interactiveComposition = Chart({
type: "spaceFlex",
children: [chart1, chart2, chart3]
})
.on("child:added", (child) => {
console.log("Child added:", child);
})
.on("layout:changed", (layout) => {
console.log("Layout updated:", layout);
});