electrum

Electrum

Electrum simplifies framework-agnostic declaration of React components. It is used internally by Epsitec SA to bridge the gap with its Xcraft toolchain and with its Lydia framework.

Where does the name Electrum come from?

Electrum is an alloy of gold and silver used to produce ancient Lydian coinage.

The first metal coins ever made, were of Electrum and date back to the end of the 7th century, beginning of the 6th century BC.

THIS IS WORK IN PROGRESS

The implementation of electrum is being modified radically.
Please wait until version has stabilized.

Linking components with their state

Let's say we want to display an article which contains the content and information about the author. The article data might be represented like this:

{ "article":
  { "content":
    { "title": "About typography"
    , "text": "Lorem ipsum..."
    , "date": "2015-12-02" }
  , "author":
    { "name": "John"
    , "mail": "[e-mail]" } } }

This can be loaded into a store instance. The "article" node will be passed as state to the <Article> component:

// In this example, the article is the root component
const state = store.select ('article');
return <Article state={state}/>;

The <Article> can be implemented as a stateless function component:

import E from 'electrum';
function Article (props) {
  return (
    <div>
      <Content {...E.link (props, 'content')} />
      <Author {...E.link (props, 'author')} />
    </div>
  );
}

Reading state

Components will very often need to read values from the store. To make life easier for the developer, electrum provides a read() method, which takes the props of the component and the id of the value to read:

import E from 'electrum';
function Content (props) {
  return (
    <div>
      <h1>{E.read (props, 'title')}</h1>
      <p>{E.read (props, 'text')}</p>
    </div>
  );
}

Managing styles with Radium

We decided to use radium as the way to go to inject styles into components. By using the E instance provided by import Electrum from 'electrum'), components are automatically configured to use radium when wrapped like this:

import Electrum from 'electrum';
import _Button from './Button.component.js';
import _Button$styles from './Button.styles.js';
export const Button = Electrum.wrap ('Button', _Button, {styles: _Button$styles});

Wrapping and automatic component extensions

Electrum.wrap() returns a new component class, which will be treated as a pure component by React:

• shouldComponentUpdate(nextProps, nextState) → pure component.
  The test is based on a shallow comparison of the properties and of the state (if any).

It injects some additional functionality:

• link(id) → shorthand for Electrum.link(this.props, id).
• read(id) → shorthand for Electrum.read(this.props, id).
• theme → shorthand for this.props.theme.
• styles → resolves the styles based on rules implemented by Style.

The component is also extended by Radium which will flatten styles arrays injected in child components, and handle the state required to handle browser states such as :hover.

One more trick Electrum.wrap() does is that it ensures that event handler methods (e.g. onChange or handleClick) get properly bound to the component instance. Therefore, event handlers can be passed to React in a natural way:

render () {
  return <div onClick={this.handleClick}>Click me</div>;
}

whereas normally, you would have to write this:

render () {
  return <div onClick={this.handleClick.bind (this)}>Click me</div>;
}

or do the binding manually in the constructor:

constructor () {
  super ();
  this.handleClick = this.handleClick.bind (this);
}
render () {
  return <div onClick={this.handleClick}>Click me</div>;
}

Electrum's autobinding looks for methods starting with on or handle and using camel case (such as onClick); other methods won't be automatically bound to this.

See also the explanation on autobinding on the React blog.

Sending events to the bus

Electrum can use a bus to dispatch messages/commands and notify changes. The bus interface looks like this:

{
  dispatch (props, message) {}
  notify (props, value, ...states) {}
}

Bus configuration

A bus can be attached with Electrum.useBus(bus).

Event forwarding

The default Electrum instance is configured to use electrum-events, which injects various event handlers into the wrapped components:

• onChange
• onKeyDown, onKeyUp, onKeyPress
• onFocus

Note: if the component provides its own event handlers, they will be called by the injected methods.

Events will automatically be sent to the bus, if one has been configured (see Electrum.use). The EventHandlers class in electrum-events is in charge of the event forwarding. It will provide the value and the states associated with the underlying component, usually by reading the DOM:

• value ← event.target.value
• states ← {begin:0, end:10} for text fields

Custom value or states

When the defaults are not meaningful (e.g. for a checkbox, where the value does not exist per se), the component can provide the value (method getValue()) or the states (method getStates()):

class MyCheckbox extends React.Component {
  render () {
    return <input type='checkbox' /* ... */ />;
  }
  getValue (target) {
    // The value will be 'on' or 'off', depending on the checked state
    // of the target DOM node:
    return target.checked ? 'on' : 'off';
  }
}

Automating component wrapping

The easiest way to get all components of a module wrapped is to use the electrum-require-components module.

See electrum-require-components.

Install electrum-require-components

npm install electrum-require-components --save-dev

Configure your package

Edit package.json to add a script that can be invoked with npm run regen in order to regenerate the source file all.js which includes, wraps and exports all components.

"scripts": {
  ...
  "regen": "electrum-require-components --wrap ./src components .component.js all.js"
}

Export all wrapped components

To export all components found in your module, use:

export * from './all.js';

Tracing

Electrum includes basic tracing functionality, which might come in handy when live debugging wrapped components.

shouldComponentUpdate()

Whenever React calls a wrapped component's shouldComponentUpdate(), Electrum will call the corresponding logging function:

import E from 'electrum';
E.configureLog ('shouldComponentUpdate', (component, nextProps, nextState, result) => { /* ... */ });

The arguments are:

• component → component instance.
• nextProps → next properties, as provided to shouldComponentUpdate.
• nextState → next state, as provided to shouldComponentUpdate.
• result → result of the call to shouldComponentUpdate, where true means that the component should be rendered.

States and fingerprints

Components may need to represent their internal state as a collection of simple state objects:

const fieldSelection = { from: 12, to: 17 };     // 'from,to'
const listSelection  = { first: 5, active: 8 };  // 'active,first'

These state objects have fingerprints which are based on their sorted property names ('from,to', 'active,first'). It does not include the optional id property.

FieldStates class

The FieldStates class maintains an internal array of state objects. It is implemented in electrum-field and made available by electrum as a convenience.

Query the field states

• FieldStates.fingerprint (state) → the fingerprint of a state object.
• find (fingerprint) → the first state object which matches the specified fingerprint, or undefined if none can be found.
• get () → an immutable array of immutable state objects.

Update the field states

The instances are immutable. All methods which modify the internal array of state objects will return a new instance (or the unchanged instance if the update was a no-op). The original instance is never modified.

• add (state) → a new instance where the internal array of states has been updated by adding or replacing a state; matching is done based on the state's fingerprint.
• add (state1, state2, ...) → same as add() called multiple times.
• remove (fingerprint) → a new instance where the internal array of states has been updated by removing the first state matching the specified fingerprint.