d3fc-element

Custom HTML elements that make it easier to create responsive D3 visualisations using CSS that integrate easily with other UI frameworks (e.g. React, Angular).

Main D3FC package

Installation

npm install @d3fc/d3fc-element

Polyfills

This package requires the Custom Elements (v1 i.e. customElements.define & no extending built-ins) and CustomEvent support. If you are targeting a browser which does not support these APIs, the following polyfills can be used -

• CustomEvent
• Custom Elements

API Reference

• <d3fc-svg>
• <d3fc-canvas>
• <d3fc-group>

<d3fc-svg> <d3fc-canvas>

These elements provide a nested svg or canvas element as a rendering surface for D3 visualisations. Use CSS to size the element and its pixel dimensions will be automatically propagated through to the nested element.

Rendering is internally a three-phase process which is automatically aligned to animation frames, measure, resize (if required) and draw. The resize and draw phases emit similarly named events to allow rendering code to be called.

The split is required to allow the measuring logic to be performed across all surfaces in the document before any rendering takes place. This prevents layout thrashing by preventing interleaving of DOM reads (which occur in measure) with DOM writes (which should occur in draw).

<d3fc-svg id="x-axis" style="width: 10vw; height: 6vw"></d3fc-svg>

const xScale = d3.scaleLinear()
  .domain([0, 10]);

const xAxis = d3.axisBottom(xScale);

const xAxisContainer = d3.select('#x-axis')
  .on('measure', (event) => {
    const { width } = event.detail;
    xScale.range([0, width]);
  })
  .on('draw', (event) => {
    d3.select(event.currentTarget)
      .select('svg')
      .call(xAxis);
  });

// Now that the event handlers are added, request a redraw
xAxisContainer.node()
  .requestRedraw();

// Some time later...
setTimeout(() => {
  // ...a change requiring a redraw occurs...
  xScale.domain([0, 5]);
  // ...so we request a redraw of the element.
  xAxisContainer.node()
    .requestRedraw();
}, 1000);

# surface.requestRedraw()

Enqueues a redraw to occur on the next animation frame, only if there isn't already one pending. If one is already pending, this call is ignored.

It should be noted that requestRedraw is asynchronous. It does not directly invoke the draw event so any errors thrown in the event handler can not be caught.

# surface.useDevicePixelRatio()

Available as the property useDevicePixelRatio or the attribute use-device-pixel-ratio. Controls whether the surface dimensions are multiplied by the devicePixelDepth if available.

# canvas.setWebGlViewport()

Note d3fc-svg does not support this property.

Available as the property setWebglViewport or the attribute set-webgl-viewport. Controls whether the surface dimensions are additionally set on the WebGL context viewport.

<d3fc-group>

An element with no visual representation that is designed to group related rendering surfaces (<d3fc-svg>/<d3fc-canvas>). Its core purpose is to multi-cast group.requestRedraw calls to descendant surfaces and to provide an aggregate draw event. It additionally provides helpers to allow auto-resizing of descendant surfaces in response to window resize events.

<d3fc-group id="chart" auto-resize style="display: flex; height: 40vw; width: 60vw; flex-direction: column">
  <h1 style="text-align: center">
    A Cartesian Chart
  </h1>
  <div style="flex: 1; display: flex; flex-direction: row">
    <d3fc-svg id="plot-area" style="flex: 1"></d3fc-svg>
    <d3fc-svg id="y-axis" style="width: 5em"></d3fc-svg>
  </div>
  <div style="height: 3em; display: flex; flex-direction: row">
    <d3fc-svg id="x-axis" style="flex: 1; margin-right: 5em"></d3fc-svg>
  </div>
</d3fc-group>

# group.autoResize = autoResize

Available as the property autoResize or the attribute auto-resize. If true, listens to window resize events and automatically invokes group.requestRedraw.

# group.requestRedraw()

Equivalent to invoking surface.requestRedraw on all descendant group or surface elements. The order of events emitted on this and descendent groups or surfaces is guaranteed to be in document order (even if a redraw request on one of those elements occurs before or after this call).

Events

The following custom DOM events are emitted by the elements -

• measure - indicates that the element has been measured. Typically the measure event is used to set the range on scales or apply transforms.
• draw - indicates that the element requires drawing. Typically the draw event is used to render components or perform any bespoke data-joins.

The following properties are available under the detail property on the event (not available for <d3fc-group>) -

• width - the width of the surface in pixels.
• height - the height of the surface in pixels.
• resized - flag indicating whether the element has resized since the last draw.

N.B. it is safe to immediately invoke surface.requestRedraw from event handlers if you wish to create an animation. The redraw will be scheduled for the subsequent animation frame.