@data-ui/network

demo at williaster.github.io/data-ui

Overview

This package exports declarative react <Network /> implemented with @vx which can be used to render network.

Usage

See the demo at williaster.github.io/data-ui for more example outputs.

Components

Check out the example source code and PropTable tabs in the Storybook williaster.github.io/data-ui for more!

<Network />

The Network component renders the network visualization. It takes the following props:

Name | Type | Default | Description ------------ | ------------- | ------- | ---- ariaLabel | PropTypes.string.isRequired | - | Accessibility label for the svg children | PropTypes.node.isRequired | - | Child series, reference lines, defs, or other valid svg children className | PropTypes.string | - | Optional className to add to the svg graph | PropTypes.shape({nodes: PropTypes.array, links: PropTypes.array }) | - | A valid graph structure with nodes and links. height | PropTypes.number.isRequired | - | Height of the svg including top/bottom margin width | PropTypes.number.isRequired | - | Width of the svg including left/right margin margin | PropTypes.shape({ top: PropTypes.number, right: PropTypes.number, bottom: PropTypes.number, left: PropTypes.number }) | { top: 16, right: 16, bottom: 16, left: 16 } | Chart margin onMouseMove | PropTypes.func | null | func({ data, id, event, index }), passed to a NodeComponent onMouseLeave | PropTypes.func | null | func({ data, id, event, index }), passed to a NodeComponent onMouseEnter | PropTypes.func | null | func({ data, id, event, index }), passed to a NodeComponent onClick | PropTypes.func | null | func({ data, id, event, index }), passed to a NodeComponent waitingForLayoutLabel | PropTypes.string | 'Computing layout...' | Placeholder message when the layout algorithm is running scaleToFit | PropTypes.bool | true | A flag to indiate if the computed x and y from layout algorithms will be scaled to fit for the graph width and height. If it is false, the perserveAspectRatio won't be used. It is useful when the layout algorithms handle the scale-to-fit functionality. preserveAspectRatio | PropTypes.bool | true | A flag to indiate if the aspect ratio will be preserved when scaling the layout to fit for the width and height of the component. renderLink | PropTypes.func | Link | Customized Link Renderer for an link object renderNode | PropTypes.func | Node | Customized Node Renderer for an node object layout | PropTypes.object | atlasForce | Customized layout object created by an Layout Class

Layout Class

Users can creat their own layout algorithm class and pass the object created by the class to the network visualization. For a layout class, it must implement the following functions:

Function | Parameters | Description -------------- | -------- | ---------------- setGraph | graph: graphShape | Assign a graph to the object getGraph | | return the graph layout | { callback: function } | Layout the graph and call the callback function with the layouted graph as the input parameter. setAnimated | isAnimated: bool | Render the graph layout process with animated transition isAnimated | | Return the animated status clear | | Post-process used to clear any states, such as clear all the callback functions setBoundingBox | { width: number, height: number, margin: marginShape } | set width, height, and margin for the layout algorithm.

Tooltips

Tooltips are controlled with the renderTooltip function passed to <Network />. This function takes an object with the shape { event, index, id, data } as input and is expected to return the inner contents of the tooltip (not the tooltip container!) as shown above. If this function returns a falsy value, a tooltip will not be rendered.

Under the covers this will wrap the <Network /> component in the exported <WithTooltip /> HOC, which wraps the svg in a <div /> and handles the positioning and rendering of an HTML-based tooltip with the contents returned by renderTooltip(). This tooltip is aware of the bounds of its container and should position itself "smartly".

Customization

If you'd like more customizability over tooltip rendering you can do either of the following:

1. Roll your own tooltip positioning logic and pass onMouseMove and onMouseLeave functions to <Network />. These functions are triggered with the signature described below upon appropriate trigger.

2. Wrap <Network /> with <WithTooltip /> yourself, which accepts props for additional customization:

Name | Type | Default | Description ------------ | ------------- | ------- | ---- children | PropTypes.func or PropTypes.object | - | Child function (to call) or element (to clone) with onMouseMove, onMouseLeave, and tooltipData props className | PropTypes.string | - | Class name to add to the <div> container wrapper renderTooltip | PropTypes.func.isRequired | - | Renders the contents of the tooltip, signature of ({ event, data, datum, color }) => node. If this function returns a falsy value, a tooltip will not be rendered. styles | PropTypes.object | {} | Styles to add to the <div> container wrapper TooltipComponent | PropTypes.func or PropTypes.object | @vx's TooltipWithBounds | Component (not instance) to use as the tooltip container component. It is passed top and left numbers for positioning tooltipProps | PropTypes.object | - | Props that are passed to TooltipComponent tooltipTimeout | PropTypes.number | 200 | Timeout in ms for the tooltip to hide upon calling onMouseLeave

Note that to correctly position a tooltip, the <WithTooltip /> onMouseMove function minimally requires an event OR coords object of the form { x: Number, y: Number }. If coords is specified it takes precedent over any position computed from the event. See function signatures below for more.

Functions and Function Signatures

<Network /> supports onMouseEnter, onMouseMove, onMouseLeave, and onClick event handlers. These functions are passed to the renderNode components with the following signatures:

onMouseLeave(event);
allOtherFunc({ event, index, id, data: node, coords] });

coords is an object of the form { x: Number, y: Number }. XYChart passes x and y only if snapTooltipToDataX or snapTooltipToDataY are true, respectively.

Programmatically triggering tooltips

<Network /> exposes hooks to manually trigger any of these handlers with the eventTriggerRefs prop. Similar to React refs, this prop is a callback function that is called by <Network /> after mounting. The callback receives an object as input, with keys corresponding to the event type names and respective handlers as values: eventTriggerRefs({ click, mouseenter, mousemove, mouseleave }). The ref handlers have the same signatures as defined above.

Note that snapTooltipToData* props will still apply (i.e., coords will be passed in the event signature) when events are triggered this way.

Roadmap

• more layout algorithms
• dragging interaction enabled