Lex.js

Lex - A micro-framework for building search bars.

This class is an EventEmitter and exposes the following events:

• on('token start', () => {}) when the user begins to create or edit a token.
• on('token end', () => {}) when the user finishes creating or editing a token.
• on('token action', (tokenIdx, actionVkey, newModel, newUnboxedModel, oldActionVal) => {}) when the user triggers a token action.
• on('query changed', (newModel, oldModel, newUnboxedModel, oldUnboxedModel, nextTokenStarted) => {}) when query model changes.
• on('suggestions changed', (newModel, oldModel, newUnboxedModel, oldUnboxedModel) => {}) when suggestion model changes.
• on('validity changed', (newValidity, oldValidity) => {}) when validity of an active builder changes.

Extends EventEmitter

// Instantiate a new instance of lex and bind it to the page.
const lex = new Lex(language);
lex.render(document.getElementById('lex-container'));

// Override default builder/assistant associations
const lex = new Lex(language);
lex.registerBuilder(ValueState, MyCustomOptionBuilder);

import { Lex } from 'lex';
Lex.from('field', ValueState, {
  name: 'Choose a field to search',
  options:[
    new ValueStateValue('Name', {type: 'string'}),
    new ValueStateValue('Income', {type: 'number'})
  ]
}).to(...).to(...) // to() has the same signature as from()

A factory for a State, which can be used to produce instances from the provided configuration object.Also a builder for chaining this StateTemplate to children, creating a DAG of StateTemplates which describes your search language.

Describes a particular state in a state machine (DAG) which represents the interactive build process for a token. The state machine implied by a tree of States will be traversed one state at a time (parent to child) by the user as they interact with its visual representation, resulting in a sequence of state values which constitute a valid "token" within your search language.

This class is meant to be extended to implement new state types.

State supports a notion of boxed/unboxed values, where the internal representation of the value is richer than the String version supplied by the user. Override boxValue and unboxValue to utilize this functionality. By default, the internal representation and the user-supplied one are the same (a string), and no overriding is necessary.

Values should not be Arrays, but can be objects (Arrays interfere with internal multi-value handling).

this.value always accepts/returns a boxed value. Where desired, the boxed and unboxed versions of the value can be identical.

States support an archive for values, in order to facilitate multi- value entry. Valid values may be pushed onto the archive, making room for a new value entry to take place. The top archived value may also be moved back to replace the current value.

This class is an EventEmitter, exposing the following events:

• on('value changed', (newVal, oldVal) => {}) when the internal value changes.
• on('value archived', () => {}) when a value is archived.
• on('value unarchived', () => {}) when a value is archived.
• on('preview value changed', (newVal, oldVal) => {}) when the internal preview value changes.
• on('unboxed value change attempted', (newUnboxedVal, oldUnboxedVal)) when a user attempts to change the unboxed value. If it cannot be boxed, it may not trigger value changed.

Extends EventEmitter

class MyCustomState extends State {
  constructor (config) {
    super(config);
    const {myCustomOption} = config;
    // do something with myCustomOption
  }

  boxValue (userVal) {
    // userVal is what a user might type to supply a value to this state
    // TODO implement transform into richer internal representation
  }

  unboxValue (internalRepresentation) {
    // TODO return a string representation of the richer internal representation.
  }
}

An abstract superclass for a Component which can be used to construct a portion of a Token.

Subclasses generally implement renderInteractive and focus.

Extends Component

// See OptionBuilder for an example implementation.

focus () {
  if (this.textInput) this.textInput.focus();
}

renderInteractive (props, {valid, readOnly}) {
 return (
   <input
      ref={(input) => { this.textInput = input; }}
      type="text"
      disabled={readOnly}
      className={valid ? 'token-input' : 'token-input invalid'}
   />
  );
}

Richer interaction areas for building values.

These have no read-only mode, and are utilized as "drop-downs" to provide additional interactivity and visualization as users.

Subclasses generally implement delegateEvent, renderInteractive and focus.

Extends Builder

// See OptionAssistant for an example implementation.

Convenient builders for constructing transition functions.

// Transition to this child state if the parent option key is 'is', 'is like' or 'equals'
TransitionFactory.valueKeyIs('is', 'is like', 'equals')

// Transition to this child state if the parent option key is not 'between'
TransitionFactory.valueKeyIsNot('between')

TransitionFactory.valueMetaCompare({type: 'string'})

A state representing the selection of a value from a list of suggested values. Intended to facilitate both simple cases (such as selecting from a list of predefined options) and advanced ones (such as selecting from a list of dynamically updating suggestions).

By default, this state (and any extending classes) can be visually represented by ValueBuilder and ValueAssistant.

This class is an EventEmitter and exposes the following events (in addition to State's events):

• on('fetching suggestions', () => {}) when a fetch for suggestions is triggered.
• on('fetching suggestions finished', (err) => {}) when a fetch for suggestions is finished, regardless of whether or not the suggestions changed. err may be defined if something went wrong.
• on('suggestions changed', (newSuggestions, oldSuggestions) => {}) when the internal list of suggestions changes.
• on('typed text changed', (newText, oldText) => {}) when a user types text into the associated Builder.

Extends State

A rich value, which might be an object (such as a Date) or a basic type, along with associated metadata.

This state supports the selection of a relation from a list of options.

Extends ValueState

This state supports the selection of a text relation from a list of options.

Extends RelationState

This state supports the selection of a numeric relation from a list of options.

Extends RelationState

This state supports the selection of a datetime relation from a list of options.

Extends RelationState

This state supports the entry of a String value, with possible auto-complete.

Extends ValueState

This state supports the entry of a Number value, with possible auto-complete.

Extends ValueState

This state supports the entry of a (stringified) Number value, with possible auto-complete.

Extends ValueState

This state supports the entry of a Date/Time value, with support for a custom acceptable format.

Extends State

A non-interactive state providing a mechanism to add a textual label between two other builders.

By default, this state (and any extending classes) can be visually represented by LabelBuilder.

Extends State

A visual interaction mechanism for supplying values to a ValueState. By default, this is registered as the Builder for ValueStates.

Extends Builder

lex.registerBuilder(ValueState, ValueBuilder)

A visual representation of a LabelState

Extends Builder

lex.registerBuilder(LabelState, LabelBuilder)

A visual representation of a TerminalState

Extends Builder

lex.registerBuilder(TerminalState, TerminalBuilder)

A visual interaction mechanism for supplying values to an DateTimeEntryState. By default, this is registered as the Builder for DateTimeEntryStates.

Extends Builder

lex.registerBuilder(DateTimeEntryState, DateTimeEntryBuilder)

A visual interaction mechanism for supplying values to a ValueState. By default, this is registered as the Assistant for ValueStates.

Extends Assistant

lex.registerAssistant(ValueState, ValueAssistant)

A visual interaction mechanism for supplying values to an DateTimeEntryState. By default, this is registered as the Assistant for DatetimeEntryStates.

Extends Assistant

lex.registerAssistant(DateTimeEntryState, DateTimeEntryAssistant)

A factory for an Action, which can be used to produce instances from the provided configuration object.

A concrete Action, presented as a button only on completed Tokens, which allows users to interact with Tokens in some way. Each Action has its own internal value, and can only affect its own internal value.

Extends EventEmitter

A non-interactive, invisible state providing a mechanism for simulating an "optionally terminal" state. For example, an ValueState where certain values terminate the machine, but others do not.

Extends State

An EnumEntryStateValue represents an Enumeration value, with a string name and a numerical index.

Extends ValueStateValue

This state supports the entry of an enum Value, a string associated with a number, with possible auto-complete config.enums should be supplied as an array of EnumEntryStateValues. For example, the enum value "hello"->1 would be represented as new EnumEntryStateValue(1, 'hello').

Extends ValueState

An TokenSuggestionStateValue represents an TokenSuggestionState value, with regexp pattern(s) and a function producing a full Token value which would be suggested if a regexp is matched.

Extends ValueStateValue

This state supports the suggestion of entire token values, with possible auto-complete.

Extends ValueState

Interactions for Tokens.

Subclasses generally implement render, onClick.

Extends Component

Called just before a component, such as this Builder or an Assistant, requests a transition. This is useful, for example, when an Assistant wants to trigger a transition but needs its associated Builder to commit a typed value to state.unboxedValue first.

Call from a subclass to request the state machine for the containing token to attempt transition.

Call from a subclass to request an immediate cancelling of the current state machine, and the creation of a brand new token.

Call from a subclass to request the state machine for the containing token to attempt archive a value.

Call from a subclass to request the state machine for the containing token to attempt unarchiving a value.

Call from a subclass to request the state machine for the containing token to attempt removal of a specific value from the archive.

Call from a subclass to request the state machine for the containing token to attempt removal of all values from the archive.

Call from a subclass to request the state machine for the containing token to attempt replacement of a specific archived value.

Call from a subclass to request the state machine for the containing token to attempt rewind.

Call from a subclass to request the state machine for the containing token to attempt rewind to this builder

Call from a subclass to inform containing components that this component has received focus. Since "focus" is not necessarily a literal concept (and could be triggered by a button press, or some other interaction), this is an artificial bubbling mechanism.

Call from a subclass to inform containing components that this Builder is cancelling input.

Call from a subclass to inform containing components that this component has been blurred. Since "focus" is not necessarily a literal concept (and could be triggered by a button press, or some other interaction), this is an artificial bubbling mechanism.