Radium Constraints

Radium Constraints introduces the power of constraint-based layout to React. Declare simple relationships between your visual components and let the constraint solver generate the optimum layout.

Radium Constraints handles DOM and SVG elements and is the perfect alternative to manual layout when building SVG data visualizations. Radium Constraints is the bedrock for exciting new enhancements to Victory.

Pre-alpha

This library is still incubating and is not yet ready for production use. See the roadmap for what's left to do before 1.0.0.

Usage

First, ensure all components using Radium Constraints are wrapped in the top-level <ConstraintLayout> component:

import ConstraintLayout from "radium-constraints";

<ConstraintLayout>
  ...other components
</ConstraintLayout>

Next, add a <Superview> component. A <Superview> is a collection of "subviews" whose layouts relate to each other and their parent. A <Superview> typically encapsulates one large visual component, like a single chart.

Superviews require the following props:

• name: for identification. We'll remove this requirement in future versions.
• container which element the superview should use as a container (i.e. div for DOM and g for SVG).
• width: the initial width of the superview.
• height: the initial height of the superview.
• style (optional) custom styles to apply to the container node.

Here's how to set up a <Superview>:

import ConstraintLayout, { Superview } from "radium-constraints";

<ConstraintLayout>
  <Superview
    name="tutorial"
    container="div"
    width={400}
    height={500}
    style={{
      background: "red"
    }}
  >
    ...subview components
  </Superview>
</ConstraintLayout>

Finally, add subviews to your <Superview>! You can create subviews in two ways. The first, AutoDOM and AutoSVG, automatically map the bounding box of the subview to the appropriate DOM styles/SVG attributes. AutoDOM uses the bounding box to absolutely position the element. AutoSVG maps the bounding box to attributes like x, y, x1, y1, cx, cy, r, etc. on a per-element basis.

If you need more control over the usage of the bounding box in components, you can create a custom subview using the <Subview> higher-order component. <Subview> provides layout props (width, height, top, left, bottom, right) that you can map to DOM attributes or style props.

Both of these methods use <Subview> under the covers, and they require the same props:

• name: the name of the subview. Allows other subviews to constrain themselves to this subview.
• intrinsicWidth: the minimum width of the component before application of constraints.
• intrinsicHeight: the minimum height of the component before application of constraints.
• constraints: a set of constraints for this subview.

Building constraints uses a fluent DSL in the style of Chai assertions. Some constraint examples:

// These two constraints center the subview in the <Superview>.
constrain.subview("demo").centerX.to.equal.superview.centerX
constrain.subview("demo").centerY.to.equal.superview.centerY

// This prevents this subview from overlapping with
// another subview named "other".
constrain.subview("demo").left
  .to.be.greaterThanOrEqualTo.subview("other").right

// This prevents this subview from overflowing
// the superview's right edge.
constrain.subview("demo").right
  .to.be.lessThanOrEqualTo.superview.right

Here's an example of a custom component using <Subview>:

class Rectangle extends Component {
  static propTypes = {
    layout: PropTypes.shape({
      top: PropTypes.number,
      right: PropTypes.number,
      bottom: PropTypes.number,
      left: PropTypes.number
    })
  };

  render() {
    return (
      <div style={{
        position: "absolute",
        top: this.props.layout.top || 0,
        left: this.props.layout.left || 0
        width: this.props.layout.width || 0,
        height: this.props.layout.height || 0
      }}
      >
        <p>Demo time!</p>
      </div>
    );
  }
}

export default Subview(Rectangle);

Here's how to use AutoDOM components:

import ConstraintLayout, { Superview, AutoDOM } from "radium-constraints";

<ConstraintLayout>
  <Superview
    name="tutorial"
    container="div"
    width={400}
    height={500}
    style={{
      background: "red"
    }}
  >
    <AutoDOM.div
      name="tutorialSubview"
      intrinsicWidth={50}
      intrinsicHeight={50}
      constraints={[
        constrain.subview("tutorialSubview").centerX
          .to.equal.superview.centerX,
        constrain.subview("tutorialSubview").centerY
          .to.equal.superview.centerY
      ]}
    >
      This is a subview
    </AutoDOM.div>
  </Superview>
</ConstraintLayout>

When using AutoSVG components, make sure to pass "g" instead of "div" to the <Superview>'s container prop.

Demo

There are more complex examples on the demo page. Check out the code in app.jsx.

Installation

• Clone this repo
• npm install and then ./node_modules/.bin/builder run hot will load a webpack dev server at localhost:3000.

If you want to type builder instead of ./node_modules/.bin/builder, please update your shell to include ./node_modules/.bin in PATH like:

export PATH="${PATH}:./node_modules/.bin"

Caveats

React Constraints uses an asynchronous layout engine running on a pool of WebWorkers. This prevents layout calculations from bogging down the main thread and allows the library to be a good citizen in any page/app. Therefore, browsers using this library must support WebWorkers.

Resolving and incrementally adding/removing constraints are cheap enough to run in 60fps for most cases. However, the initial layout calculations on first load are the most expensive, and you may notice a slight delay in layout (although this does not block the main thread). We're working on a build tool that will pre-calculate initial layouts and feed them into your components to prevent this.

Browser support

This library's browser support aligns with React's browser support minus IE 8 and 9 (neither support Web Workers.) The library requires no polyfills for its supported environments.

We may investigate integrating a sham Web Worker for IE 9 support.

Roadmap

In order of priority:

• Remove dependency on autolayout.js in favor of a simple wrapper around the Kiwi constraint solver.
• Support SVG path elements in AutoSVG.
• Create build tool to pre-calculate initial layouts.
• Decide on an animation strategy (requires support for removing constraints).
• Allow for self-referential subviews in the constraint props array without using the subview string.