Compost API reference

Coordinates: Continuous and categorical coordinates

When specifying coordinates in Compost, you do so using a value from your domain rather than using a value in pixels. A value can be either categorical (such as a political party or a country) or a continuous (such as an exchange rate or a year).

When specifying a location using a continuous value, you specify just a number. When using a categorical value, Compost associates a whole area to each category and so you need to give a category together with a number specifying a location within this area. The following are valid ways of specifying a Coord:

// A continuous value such as exchange rate
let v1 = 1.52

// A continuous value such as a number of MPs
let v2 = 152

// Leftmost corner of an area associated with categorical value
let v3 = ["Labour", 0]

// Middle of an area associated with categorical value
let v4 = ["Labour", 0.5]

In other words, Coord can be either a number or an array of two elements containing a string (the name of the category) and a number (between 0 and 1).

When you want to specify a location on a chart, you need an x and y coordinate. A Point in the following documentation refers to an array of two Coord elements, one for x and one for y coordinate. The following gives some examples of valid points:

// A pair of continuous values
let p1 = [ 3.14, Math.sin(3.14) ]

// A point with categorical X and continuous Y
let p2 = [ ["Labour", 0.5], 152 ]

// A list specifying a several points on a line
let l1 = [ [0, Math.sin(0)], [1.57, Math.sin(1.57)],
  [3.14, Math.sin(3.14)], [4.71, Math.sin(4.71)]  ]

// A list specifying four corners of a rectangle
let s1 = [ [["Labour", 0], 0], [["Labour", 0], 152],
  [["Labour", 1], 152], [["Labour", 1], 0] ]

Scales: Categorical and continuous

s.continuousfloat * float -> Scale

Creates a continuous scale that can contain value in the specified range

s.categoricalstring[] -> Scale

Creates a categorical scale that can contain categorical values specified in the given array of strings

Compost primitives: Basic shapes

c.textCoord * Coord * string * ?string * ?float -> Shape

Draws a text specified as the third parameter at a given x and y coordinates specified by the first two parameters. The last two optional parameters specify alignment (baseline, hanging, middle, start, end, center) and rotation in radians.

c.bubbleCoord * Coord * float * float -> Shape

Creates a bubble (point) at a specified x and y coordinates. The last two parameters specify the width and height of the bubble in pixels.

c.shapePoint[] -> Shape

Creates a filled shape. The shape is specified as an array of points (see the section on coordinates).

c.linePoint[] -> Shape

Creates a line drawn using the current stroke color. The line is specified as an array of points (see the section on coordinates)

c.columnstring * float -> Shape

Creates a filled rectangle for use in a column chart. This is a shorthand for c.shape. It creates a rectangle that fills the whole area for a given categorical value and has a specified height.

c.barfloat * string -> Shape

Creates a filled rectangle for use in a bar chart. This is a shorthand for c.shape. It creates a rectangle that fills the whole area for a given categorical value and has a specified width.

Compost primitives: Specifying visual properties

c.fillColorstring * Shape -> Shape

Sets the fill color to be used for all shapes drawn using c.shape in the given shape.

c.strokeColorstring * Shape -> Shape

Sets the line color to be used for all lines drawn using c.line in the given shape.

c.fontstring * string * Shape -> Shape

Sets the font and text color to be used for all text occurring in the given shape.

Compost primitives: Transforming scales

c.nestCoord * Coord * Coord * Coord * Shape -> Shape

Creates a shape that occupies an explicitly specified space using the four coordinates as left and right X value and top and bottom Y values. Inside this explicitly specified space, the nested shape is drawn, using its own scales.

c.nestXCoord * Coord * Shape -> Shape

Same as above, but this primitive only overrides the X scale of the nested shape while the Y scale is left unchanged and can be shared with other shapes.

c.nestYCoord * Coord * Shape -> Shape

Same as above, but this primitive only overrides the Y scale of the nested shape while the X scale is left unchanged and can be shared with other shapes.

c.scaleScale * Scale * Shape -> Shape

Override the automatically inferred scale with an explicitly specified one. You can use this to define a custom minimal and maximal value. To create scales use s.continuous or s.categorical.

c.scaleXScale * Shape -> Shape

Override the automatically inferred X scale (as above).

c.scaleYScale * Shape -> Shape

Override the automatically inferred Y scale (as above).

c.paddingfloat * float * float * float * Shape -> Shape

Adds a padding around the given shape. The padding is specified as top, right, bottom, left. This will subtract the padding from the available space and draw the nested shape into the smaller space.

Compost primitives: Combining shapes and axes

c.overlayShape[] -> Shape

Compose a given array of shapes by drawing them all in the same chart area. This calculates the scale of all nested shapes and those are then automatically aligned based on their coordinates.

c.axesstring * Shape -> Shape

Draw axes around a given shape. The string parameter can be any string containing the words left, right, bottom and/or top, for example using space as a separator.

Compost primitives: Rendering charts and interactivity

c.renderstring * Shape -> unit

Render a given chart on a HTML element specified by a given ID. When called, Compost will get the width and height of the element and render a chart using this as the size.

c.onHandlers * Shape -> Shape

Specify event handlers for events that occur in the specified shape. The first parameter is a JavaScript object with fields representing individual handlers. The supported handlers are mousedown, mouseup, mousemove, click, touchstart, touchmove. Those are called with x and y coordinates of the event. You can also specify touchend and mouseleave handlers, but those do not get coordinates of the event. For example of how to specify handlers, see the You draw it demo.

c.svgfloat * float * Shape -> Html

Render the given shape and build an object representing the chart as an HTML <svg> element. The first two arguments specify the desired width and height of the SVG element in pixels. This operation is useful if you want to create an interactive chart using c.interactive and want to add some custom HTML elements using c.html.

c.htmlstring * obj * (Html | string)[] -> Html

Creates a HTML element that can be returned as a result of the rendering function in c.interactive. The API is inspired by HyperAcript. The first element is a tag name, followed by an object that specifies element properties (value of type string) and event handlers (value of type function). The third parameter is an array of children, which can be either text or other HTML elements.

c.interactivestring * State * (State -> Event -> State) * ((Event -> unit) -> State -> (Html | Shape)) -> unit

Create an interactive chart using a given HTML element ID. For an example of how this works, see the You draw it demo. This is based on the Elm architecture (also known Model-View-Update). The last three parameters specify the initial state, an update function (given a state and an event, produce a new state) and a view function (given a function to trigger an event and a current state, produce a shape).

Learn more about Compost