Govern

A component-based state management tool for React.

Try it out in React Armory's live editor!

Govern is based around the concept of renderless components, i.e. components without a render function.

Renderless components are great for managing application state. For example, you can use them to implement re-usable form controllers, authentication logic, or even a JSON API interface. And best of all, they can be composed and re-used.

Another state management tool?

The React ecosystem already has Redux and setState. So why do we need Govern too?

Govern doesn't replace Redux or setState, but embraces and complements them.

Where Redux is great at managing global state like fetched data, Govern is great at managing control state -- for example, selected items, pagination, or search queries.

And where React's setState method is great for simple cases like animations, it still ties state to the DOM. With Govern's renderless components, you can use the same setState API to store state wherever you'd like.

When should I use Govern?

Storing form state without losing it between route changes
Re-usable components that don't render anything
Business logic that doesn't belong in a global store

When should I use Redux?

Storing data received from the server
Business logic that is completely independent of the DOM tree
When time-travelling is a requirement

When should I use React component state?

Animated components
Managing interactions with the DOM
Pop-out menus, tooltips, etc.

Getting started

Govern is split into two packages:

The govern package can be used with any view library
The react-govern package helps you connect Govern components with React components

npm install --save govern react-govern

A simple Govern component

If you've used React, Govern's renderless components will feel familiar. They have lifecycle methods, a constructor that receives props, and can call this.setState().

Govern components have two main differences from React components:

They don't output React elements. Instead of an render() method, they have an output() method that returns a plain JavaScript object.
Handler methods must be bound using the this.bindActions() method instead of JavaScript's Function.prototype.bind().

For example, here is a Govern component that could be used to manage a single input's state:

import Govern from 'govern'

class Model extends Govern.StatefulComponent {
  constructor(props) {
    super(props)

    // Set the initial value of the form field
    this.state = {
      value: props.defaultValue || '',
    }

    // This binds the class's `change` method as a handler function
    this.actions = this.bindActions(
      'change'
    )
  }

  change(newValue) {
    this.setState({
      value: newValue,
    })
  }

  output() {
    return {
      change: this.actions.change,
      value: this.state.value,
    }
  }
}

Using Govern components

controlledBy(governComponent)

Once you have a Govern component, you can attach an instance to a React component with the controlledBy decorator function. Its signature is:

controlledBy: (component: GovernComponent) => (component: ReactComponent) => ReactComponent

If you've used Redux before, controlledBy will be familiar; it is a lot like connect. It accepts a Govern Component as an argument, and returns another function that can be used to create stateful React components.

The return React component's props will be passed to your Govern component, and the Govern component's output will be passed to the wrapped React component.

For example:

import { controlledBy } from 'react-govern'

const EmailForm = (model) =>
  <label>
    E-mail:
    <input
      value={model.value}
      onChange={e => model.change(e.targe.value)}
    />
  </label>

// Create a stateful React component from a stateful Govern component
// and a stateless React component.
const ControlledEmailForm = controlledBy(Model)(EmailForm)

ReactDOM.render(
  // The props for `ControlledEmailForm` will be passed to the Model
  // Govern component.
  //
  // The output of Model wil then be used as the props of <EmailForm>.
  <ControlledEmailForm defaultValue='[email protected]' />,
  document.getElementById('app')
)

You can also use controlledBy with the ESNext decorator syntax:

@controlledBy(Model)
class EmailForm extends React.Component {
  render() {
    <label>
      E-mail:
      <input
        value={this.props.value}
        onChange={e => this.props.change(e.target.value)}
      />
    </label>
  }
}

While controlledBy is the simplest way of using a Govern component, there can be times when it doesn't give you enough... control (ba-dum-tsh). And that's why Govern gives you options.

`createController(component, initialProps)`

Unlike React components, Govern components can be instantiated manually. You won't often need to do this, but the option is there.

To instantiate a Govern component, you use the createController method. This returns a Controller object; i.e. an object that wraps your component instance, and can be used to interact with your component instance.

createController: (component: GovernComponent, initialProps: object) => Controller

For example, if you wanted to create an instance of the above Model component, you would do the following:

import { createController } from 'govern'

let modelController = createController(Model, { defaultValue: '[email protected]' })

You can then interact with the component through the returned controller's get(), set(...), subscribe(...) and destroy() methods:

// `[email protected]`
modelController.get().value

// `no`
modelController.set({ value: 'no' })
modelController.get().value

Once you have a Controller object, you can use <Subscribe> to access its output in a React component. This React component will use the controller's subscribe method to request notification of any changes to its output. It then feeds each new output to the render function.

For example, you could re-implement the above form using createController and <Subscribe>, but with the form's state stored outside the form component:

import { Subscribe } from 'react-govern'

const EmailForm = ({ controller }) =>
  <Subscribe to={controller} render={model =>
    <label>
      E-mail:
      <input
        value={model.value}
        onChange={e => model.change(e.targe.value)}
      />
    </label>
  } />

const controller = createController(Model, {
  initialProps: '[email protected]'
})

ReactDOM.render(
  <EmailForm controller={controller} />,
  document.getElementById('app')
)

Composing components

The best part about having state in components, is that you can compose those components to make bigger components.

As Govern components aren't tied to the DOM, Govern's approach to composition is a little different than React. Instead of nesting components with JSX and elements, Govern allows you to create parallel and sequential components.

Parallel composition

When you have multiple independent components that share the same inputs, you can use an object to indicate that you'd like a new component that nests the output of each child component.

For example, you could create a LoginFormModel by composing a number of the Model components from the previous examples:

const LoginFormModel = {
  email: Model,
  password: Model
}

let controller = createController(LoginFormModel, { defaultValue: '' })
let output = controller.get()

// you can set the value of "email" without affecting the value of "password"
output.email.change('[email protected]')

// returns '[email protected]'
controller.get().email.value

// returns an empty string
controller.get().password.value

Note: if you're using TypeScript, you can wrap the object in Govern.parallel() to get proper typings.

Sequence composition

Sometimes, you'll want to use the output of one component as the input for another component.

For example, you may want to use the output of the above model component as the input for a "LoginEndpoint" component:

class LoginEndpoint extends Govern.StatefulComponent {
  constructor(props) {
    super(props)

    this.state = {
      status: 'ready',
      error: null,
    }
    this.actions = this.bindActions(
      'start',
      'handleSuccess',
      'handleFailure',
    )
  }

  start() {
    this.setState({
      status: 'busy',
    })

    postToAPI(URL, {
      email: this.props.email.value,
      password: this.props.password.value,
    }).then(
      this.actions.handleSuccess,
      this.actions.handleFailure,
    )
  }

  handleSuccess() {
    this.setState({
      status: 'complete',
    })
  }

  handleFailure(error) {
    this.setState({
      status: 'error',
      error: error,
    })
  }

  output() {
    return {
      start: this.actions.start,
      ...this.state,
      ...this.props,
    }
  }
}

// An array indicates that props will flow from the output of one component
// to the input of the next component.
const Login = [
  LoginFormModel,
  LoginEndpoint,
]

let controller = createController(Login, { defaultValue: '' })
let output = controller.get()

output.email.set('[email protected]')
output.password.set('kangaroo')
output.start()

// returns 'busy'
output.get().status

Note: if you're using TypeScript, you can wrap the array in Govern.sequence() to get proper typings.

Stateless function components

In practice, you'll sometimes find that the output of one component is not exactly what you need. Luckily, Govern also supports React-style stateless function components; they just return props instead of elements.

For example, you could use a stateless function component along with parallel/sequence components to create a merge higher-order component to merge the output of a controller with its input props:

function defaultMergeFn(props, output) {
  return Object.assign({}, props, output)
}

function merge(governComponent, mergeFn=defaultMergeFn) {
  return [
    {
      props: props => props,
      output: governComponent,
    },
    ({ props, output }) => mergeFn(props, output)
  ]
}

This higher-order govern component (or HoG) is so useful that it actually comes with Govern. You can access it at Govern.merge().

Component Lifecycle

As Govern components are not mounted/unmounted from the DOM, their lifecycle is a little different from the React component lifecycle.

`constructor(props)`

The constructor is called when a Controller isntance is instantiated.

Perform any initialization here, including:

creating actions with bindActions
setting an initial value of this.state
addings event handlers to stores, etc.

Note that Govern components do not receive context, so you'll need to pass any required data in via props.

`componentWillReceiveProps(nextProps)`

This is identical to the React lifecycle method.

`componentWillBeDestroyed()`

Called when a component will be be destroyed. Use this in the same way that you'd use React's componentWillUnmount() lifecycle method.

Component Instance API

`this.bindActions(...methodNames)`

This function accepts a list of methods names from your class, and returns an object containing action functions; i.e. functions that are bound to the component instance, and whose changes are wrapped in a transaction. It should be used in the constructor; conventionally, you'll assign its output to this.actions.

Generally speaking, you'll want to create actions for any methods which call setState, or cause side-effects (such as changing the component's input props).

Usage

class Model extends Govern.StatefulComponent {
  constructor(props) {
    super(props)

    // This binds the class's `change` and `save` methods as handler functions
    this.actions = this.bindActions(
      'change',
      'save'
    )
  }

  change(newValue) {
    this.setState({
      value: newValue,
    })
  }

  save() {
    this.props.onSave(this.state)
  }
}

`this.setState(changes)`

Usage is mostly identical to React's setState, but with two main differences:

It is executed synchronously, so it doesn't accept an on-complete callback
It doesn't yet accept a reducer function (pull requests are welcome!)

Controller API

Controller objects have the following API:

interface Controller<Input, Output> {
  // Return the result of `output()`
  get(): Output,

  // Set the current input props
  set(newProps: I): void,

  // Clean up the component instance
  destroy(): void,

  // Allows you to subscribe to changes, or notification of the start/end of
  // a group of changes (i.e. the start/end of an action).
  //
  // You can pass `null` for callbacks which you don't need.
  subscribe(
    onChange?: (output: Output) => void,
    onTransactionStart?: () => void,
    onTransactionEnd?: (confirm: () => void) => void,
    onDestroy?: () => void,
  ): UnsubscribeCallback,
}

felipecodes / govern Goto Github PK

govern's Introduction

govern's People

Contributors

Recommend Projects

Recommend Topics

Recommend Org