electrum

Electrum

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

How to use Electrum

To include and configure Electrum in a JavaScript project, simply npm install electrum. Then:

import Electrum as 'electrum';

var Radium = /* ...provide a reference to the Radium library... */
var Lydia  = /* ...provide a reference to the Lydia.js library... */

var E = new Electrum (Radium, Lydia);

var Component = E.createClass ({...});

// or

var E = new Electrum ();
E.use (Radium);
E.use (Lydia);

var Component = E.createClass ({...});

// or

var Component = new Electrum ()
  .use (Radium)
  .use (Lydia)
  .createClass ({...});

Create React components with E.createClass({...}) instead of React.createClass({...}). Electrum takes care of extending the provided object, for instance to include a call to Radium.wrap(), etc.

When several wrappers are applied (as in the example above), then they will be applied right to left:

var E = new Electrum (Radium, Lydia);
var C = E.createClass ({});

is thus equivalent to:

var C = React.createClass (Radium.wrap (Lydia.wrap ({})));

Wrappers

The wrappers must conform to the following interface:

var Wrapper = {
  wrap: obj => obj,                // mandatory: wrap function
  getElectrumApi: () => {/*API*/}  // optional: get Electrum API implementation
  getElectrumBus: () => {/*Bus*/}  // optional: get Electrum Bus implementation
};

Providing external services

Electrum provides access to external services which are useful when implementing React components:

• The Electrum API provides:
  • Read services to get the text, value, style and state associated with a component;
  • Write services to change the value and state of a component as a result of a direct user action on the component.
• The Electrum Bus provides:
  • A method to dispatch user actions to the backend.
  • A method to notify the backend when data changes.

At least one wrapper should provide an implementation of the Electrum API and one should provide an implementation of the Electrum Bus.

Interface for the Electrum API

getState: function (obj, what) {},
setState: function (obj, ...states) {},
getStyle: function (obj) {},
getText:  function (obj) {},
getValue: function (obj) {},
setValue: function (obj, value, ...states) {}

Interface for the Electrum bus

dispatch: function (obj, message) {},
notify:   function (obj, value, ...states) {}

What will Electrum do, besides createClass?

This is not yet implemented in version 0.3.x

Electrum provides an entry point to the style objects used in conjunction with Radium. Themes are broken down into distinct axes:

• Palette → color, gradients, filters, etc.
• Typography → fonts, spacing, padding, etc.
• Shape → corners, geometric properties, spacing, padding, etc.
• Animation → transitions, timings, etc.

These collection of partial styles and constants can be accessed through the palette, typo, shape and animation Electrum properties.

Example (don't take it too seriously, though):

var boxStyles = [
  E.palette.colors.box.background,
  E.typo.title,
  {
    height: E.shape.defaultBarHeight,
    opacity: 0.8,
    ':hover': {
      height: E.shape.defaultBarHeight * 1.2,
      opacity: 1.0,
      transition: { height: E.animation.open, opacity: E.animation.pop }
    }
  }
];

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.