electrum-field

Electrum Field

The electrum-field module handles state associated with form fields and is used by electrum.

Manipulating field states

A field can have multiple states associated with it:

• A state describing whether the field is enabled or read-only.
• A state describing the position of the cursor or the selection.
• etc.

Each state is represented as a simple object.

Fingerprint

The fingerprint of a state is built by concatenating the sorted names of the state's properties (property id is not included in the computation of the fingerprint).

import {FieldStates} from 'electrum-field';

const state = {
  id: '1234',
  begin: 12,
  end: 23
};

expect (FieldStates.fingerprint (state)).to.equal ('begin,end');

FieldStates

The states are managed by class FieldStates, which maintains a read-only array of simple state objects. An instance of FieldStates is immutable.

To create a FieldStates instance, use one of the static methods:

• FieldStates.create () → creates an empty states collection.
• FieldStates.from (s1, s2, ...) → create a states collection based on the provided states s1, s2, etc.

To manipulate a FieldStates instance:

• add (state) → adds or updates the state based; matching with any existing states is based on the fingerprint.
• remove (state) → removes the state.
• find (state) → returns the immutable state (if it is found) or undefined otherwise.
• get () → returns an immutable array of immutable states, as they are stored in the FieldStates instance.

Methods remove() and find() accept either a simple object (the values of the fields are not used in the comparison) or a fingerprint to specify the state.

Methods add() and remove() return a new instance of FieldStates if the state changes; otherwise, they just return the same instance.

Note: states are considered to be equal if they respond true to shallow equality. Since states should be simple objects where all properties are just value types, a shallow comparison is enough.