`javascript
import E from 'electrum';
function Article (props) {
return (


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 an optional key of the value to read:

`javascript
import E from 'electrum';
function Content (props) {
return (


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:

`javascript
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});
`

See electrum-theme for an explanation of how style functions should be
defined. Style functions can have following signatures:

* () => ... → a parameterless style function.
* (theme) => ... → a style function, based on the theme.
* (theme, props) => ... → a style function, based on the theme and on
the component properties. The component should implement a _getter_ named
styleProps which returns a hash with the meaningful properties.

Multiple styles definitions can be exported as a _hash_ of style functions.

Component with a single style function

A component linked with a style definition consisting of a single style
function will expose following method and property:

* styles → a _styles object_ which can be set on DOM element style
properties; the styles object is compatible with Radium. It exposes a
with(s1, s2, ...) function which can be used to obtain an updated
_styles object_ into which additional styles have been merged.
* mergeStyles(s1, s2, ...) → a _hash_ containing the merged styles.

Component with a multiple style functions

A component linked with a style definition consisting of a multiple style
functions will expose following methods:

* getStyles(key) → a _styles object_ for the specified style definiton,
which can be set on DOM element style properties; the styles object is
compatible with Radium. It exposes a with(s1, s2, ...) function which
can be used to obtain an updated _styles object_ into which additional
styles have been merged.
* mergeStyles(key, s1, s2, ...) → a _hash_ containing the merged
styles for the specified style definition.

Note that the signature of the methods are different from a component
with a single style function.

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).
* link(id, overrides) → shorthand for Electrum.link(this.props, id, overrides).
* read() → shorthand for this.read('value').
* read(key) → returns named property if it exists on this.props, otherwise
calls Electrum.read(this.props, key) and reads the value from the state.
* theme → shorthand for this.props.theme.
* styles → resolves the _styles_ based on rules implemented by Styles.

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 handleFoo) get properly bound to the component
instance. Therefore, event handlers can be passed to React in a natural
way:

`javascript
render () {
return

`javascript
render () {
return

`javascript
constructor () {
super ();
this.onClick = this.onClick.bind (this);
}
render () {
return

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:

`javascript
{
dispatch (props, message, payload) {}
notify (props, source, 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 → fires notification of type _change_
* onKeyDown, onKeyUp, onKeyPress → fire notifications of
type _key-down_, _key-up_, _key-press_
* onFocus → fires notification of type _focus_
* onSelect → fires notification of type _select_

> 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:

* source ← {type, event} where _type_ is the event name
* 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()):

`javascript
class MyCheckbox extends React.Component {
render () {
return ... / />;
}
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:

`javascript
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:

`javascript
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:

`javascript
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.

$3

* 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.

$3

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.

Actions

Electrum prescribes how actions represent their specific state and
provides the Action class to inspect it:

* Action.isEnabled (state) → true if the state is enabled.
* Action.isDisabled (state) → true` if the state is disabled.