README.md

@d3-composer/svg

Example

import { select } from 'd3';
import { chart, layer, line, scatter } from '@d3-composer/svg';

const svg = chart(
  select('#chart'),
  { width: 600, height: 400, responsive: true }
);
lines(svg, { /* ... */ });

function lines(selection, options) {
  const { data, xScale, yScale } = options;

  const values = series => series.values;
  const x = d => xScale(d.x);
  const y = d => yScale(d.y);

  line(
    series(layer(selection, 'lines'), { data }),
    { data: values, x, y }
  );
  scatter(
    series(layer(selection, 'scatter'), { data }),
    { data: values, x, y }
  );
}

API

# chart(selection[, options])

SVG chart wrapper with sizing and responsive options.

Options:

• width - svg width or "design" width for responsive
• height - svg height or "design" height for responsive
• [responsive] - Use responsive container and viewBox

const svg = chart(select('svg'), { width: 400, height: 300 });

const responsive = chart(
  select('div'), 
  { width: 400, height: 300, responsive: true }
); 

# layout(selection, grid, callback)

Create layer functions that are laid out for each area of the grid. Callback should have the form (layers) => void, where layers is a layer function for creating grid items by index and contains a layer function for each area of the grid. Each layer function has the form ([id], [options]) => selection. By default id is set to the area name, but when adding multiple layers for a single area, it's recommended to explicitly set id. Options can include the layer margin, inset from the grid area bounds, style, and class.

import { template } from '@d3-composer/grid';
import { layout } from '@d3-composer/svg';

const grid = template(`"title" 50 "chart" auto / auto`);

layout(selection, grid, layers => {
  // Layout by area name
  const title_layer = layers.title();
  const chart_a_layer = layers.chart('a');
  const chart_b_layer = layers.chart('b', { margin: [0, 0, 10 0] });
  const x_axis_layer = layers.x_axis({ margin: [10, 0, 0, 0] })

  // Layout by location (left-to-right, top-to-bottom)
  const x = layers();
  const y = layers('y');
  const z = layers({ margin: 20 });
});

# layer(selection, id)

Create or select an existing g layer for the given id.

# series(selection, options)

Create separate series layers and pass series values through to charts

Options:

• data - Array of series data
• [key]
• [style] - Style string, object, or function for series
• [class] - Class string or function for series

const data = [
  [{ x: 0, y: 0 }, ...],
  [{ x: 0, y: 100}, ...]
];

line(
  series(selection, { data }),
  { x: d => xScale(d.x), y: d => yScale(d.y) }
);

# stack(selection, options)

Create a stacked set of layers

Options:

• data - Array of layer data
• direction - 'vertical' or 'horizontal' stack direction
• size - Size value or function for layers
• [key]
• [style] - Style string, object, or function for layers
• [class] - Class string or function for layers

# vstack(selection, options)

Stack helper with direction = 'vertical'

# hstack(selection, options)

Stack helper with direction = 'horizontal'

# line(selection, options)

Live Example

A line chart for drawing an x,y line

Options:

• data - {x,y} data
• x - x-value accessor
• y - y-value accessor
• [curve] - See d3-shape
• [defined] - Check if point is defined, breaking line if not
• [style] - Style string, object, or function for line
• [class] - Class string or function for line
• [transition] - An instance of d3.transition() (see d3-transition)
• [interpolate] - An interpolation function for update and exit, such as d3-interpolate-path

// x,y
line(selection, { data, x: d => xScale(d.year), y: d => yScale(d.result) })

// curve
line(selection, { curve: d3.curveCardinal() });

// style
line(selection, { style: { stroke: d => d.color } });

// class
line(selection, { class: d => d.class });

// transition
line(selection, { transition: d3.transition().duration(1000) })

// interpolate
line(selection, { interpolate: d3.interpolatePath })

# bars(selection, options)

A flexible bars chart component that can be used to create ordinal, histogram, horizontal, and stacked bars charts.

Options:

• data - {x,y} or {x0,x1,y} or {x0,x1,y0,y1} data
• [x] - x-accessor (set left-side of bar, width or x1 needs to also be defined)
• [x0] - x0-accessor
• [x1] - x1-accessor (set right-side of bar)
• [y] - y-accessor (set top of bar, height or y0 needs to also be defined)
• [y0] - y0-accessor (set bottom of bar)
• [y1] - y1-accessor
• [width] - bar width accessor
• [height] - bar height accssor
• [key] - key for identifying bars
• [style] - Style string, object, or function for bar
• [class] - Class string or function for bar
• [transition] - An instance of d3.transition() (see d3-transition)

// scale
bars(selection, {
  data,
  x: d => xScale(d.x),
  width: xScale.bandwidth(), 
  y: d => yScale(d.y),
  y0: yScale(0)
});

# scatter(selection, options)

Scatter chart for placing path at x,y positions.

Options:

• path - String or function that returns a d for path. (e.g. d3.symbol().size(50).type(d3.symbolCircle))
• data - {x,y} data
• x - x-value accessor
• y - y-value accessor
• [key]
• [style] - Style string, object, or function for path
• [class] - Class string or function for path
• [transition] - An instance of d3.transition() (see d3-transition)

# area(selection, options)

Area chart for drawing {x,y}, {x,y0,y1}, or {x0,x1,y0,y1} series data.

Options:

• data - {x,y} or {x0,x1,y} or {x0,x1,y0,y1} data
• [x] - x-accessor (sets x0 and x1 to this value)
• [x0] - x0-accessor
• [x1] - x1-accessor (set right-side of bar)
• [y0] - y0-accessor (set bottom of bar)
• [y1] - y1-accessor
• [curve] - See d3-shape
• [defined] - Check if point is defined, breaking line if not
• [style] - Style string, object, or function for line
• [class] - Class string or function for line
• [transition] - An instance of d3.transition() (see d3-transition)
• [interpolate] - An interpolation function for update and exit, such as d3-interpolate-path

# labels(selection, options)

Labels chart for placing text labels at x,y positions.

Options:

• text - Accessor for getting text value
• data - {x,y} data
• x - x-value accessor
• y - y-value accessor
• [transform] - Transform string or function to apply to each label relative to x,y point
• [anchor = 'start'] - x-value of text origin ('start', 'middle', or 'end')
• [baseline = 'hanging'] - y-value of text origin ('hanging', 'middle', or 'baseline'), see dominant-baseline
• [key]
• [style] - Style string, object, or function for path
• [class] - Class string or function for path
• [transition] - An instance of d3.transition() (see d3-transition)

# axisTop(selection, options)

A top-oriented axis component that wraps d3-axis.

Options (see d3-axis for details):

• [scale] or [xScale]
• [style] - Style string, object, or function for axis
• [domainStyle] - Style string, object, or function for axis domain path
• [tickStyle] - Style string, object, or function for axis ticks
• [labelStyle] - Style string, object, or function for axis labels
• [class] - Class string or function for axis
• [transition] - An instance of d3.transition() (see d3-transition)
• [ticks] - tick count or interval. To set specifier, use tickArguments
• [tickArguments], [tickValues], [tickFormat], [tickSize], [tickSizeInner], [tickSizeOuter], [tickPadding]

# axisRight(selection, options)

Right-oriented axis.

• [scale] or [yScale]
• (see #axisTop for remaining options)

# axisBottom(selection, options)

Bottom-oriented axis.

• [scale] or [xScale]
• (see #axisTop for remaining options)

# axisLeft(selection, options)

Left-oriented axis.

• [scale] or [yScale]
• (see #axisTop for remaining options)

# text(selection, options)

A text component for adding and laying out text.

Options:

• text - Text value
• [anchor] - x-value of origin ('start', 'middle', or 'end')
• [baseline] - y-value of origin ('hanging', 'middle', or 'baseline'), see dominant-baseline
• [justify = 'start'] - x-value of container placement ('start', 'center', 'end')
• [align = 'start'] - y-value of container placement ('start', 'center', 'end')
• [style] - Style string, object, or function for text
• [class] - Class string or function for text
• [rotation] - Rotate text by given angle (e.g. -90deg)
• [transform] - Manually transform text

# legend(selection, options)

A legend component with paths and labels

Options:

• path - d string or function to pass to path
• data - legend data for labels and other functions
• [text] - Accessor for legend text (default is d => d)
• [size = 50] - Set width and height of legend based on symbol sizing
• [width] - Width of path area
• [height] - Height of legend group
• [groupStyle] - Style string, object, or function for item group
• [groupClass] - Class string or function for item group
• [pathStyle] - Style string, object, or function for item path
• [labelStyle] - Style string, object, or function for item label

# gridlines(selection, options)

Gridlines component

Options:

• xScale - d3-scale for x-value
• yScale - d3-scale for y-value
• [xGrid = true] - Show x gridlines (vertical)
• [yGrid = true] - Show y gridlines (horizontal)
• [style] - Style string, object, or function for line
• [class] - Class string or function for line
• [transition] - An instance of d3.transition() (see d3-transition)

# symbolLine

Symbol type for line symbol.

import { symbol } from 'd3';
import { symbolLine } from '@d3-composer/svg';

symbol().size(50).type(symbolLine);

# measure(selection)

Helper for measure the size of a selection.

# interpolatePath(selection, path[, interpolate])

Interpolate d for path with attrTween, if interpolate is provided, otherwise set d attr. path should be a d path string or function. interpolate is an interpolate function taking (previous d, next d), such as d3-interpolate-path.

# translateXY(x, y)

Create translate function for given x and y accessors

const { x, y } = options;
const translate = translateXY(x, y);

selection.attr('transform', translate);