React-politic NPM

React-Politic

Observable aware provider pattern component for React.

This component was designed with Politic and RxJS in mind, but can be used with anything that implements the ES Observable Proposal.

Getting Started

Provider Component

Provide stateful and stateless observables which can be consumed by "connected" descendant components (even nested inside non-connected components). Non-observable values are also possible. They are available, but not subscribable.

<Provider someObservableState={state} someStatelessObervable={event} value={"Hello"}>
    <ConnectedComponent1/>
    <VanillaComponent>
        <ConnectedComponent2/>
    </VanillaComponent>
</Provider>

The Provider component itself does not render to the DOM. Only its children will be rendered.

Connected Components

Use the connected(...) utility to turn a component into a connected component.

Several utility methods will be attached to your component, giving it access to the provided properties.

import { connected } from "react-politic";

class Thing extends Component {
    componentWillMount() {
        // Connected components have some extra utility methods for subscribing to observables, with and without state.
        // These methods all return subscriptions which can be used to cancel subscriptions, but that's not usually
        // necessary. The subscriptions will be cancelled automatically when the component unmounts.
        const subscription1 = this.connect('someStatelessObservable', value => { /* handle the event. */ });
        const subscription2 = this.connectState('someObservableState', { map: state => { /* return some part of the state. */ }, alias: 'foo' });
        const subscription3 = this.connectDomEvent(domElement, 'someEvent', e => { /* handle the DOM event */ }, false);
        
        // You can also just close all connections at once.
        this.disconnect();
        
        // Access all provided properties, including things that aren't observable.
        this.provided.value; // "Hello"
        
        // If the "liftProvided" option is set, then all/selected keys will be attached to the component instance (only
        // if the instance key is undefined).
        this.value; // "Hello"
    }
    
    render() {
        // The this.connectState() method sets a property in the component's state, and subscribes to changes so that
        // the state gets updated when the provided observable's state changes.
        return <div>{this.state.foo}</div>;
    }
}

export default connected(Thing, { liftProvided: true })

All utility methods can be called anywhere setState(...) can be called, and also in the constructor, but it's generally best to connect in the componentWillMount() method, because automatic disconnection occurs in the componentWillUnmount() method.

Function: `connected(component[, options])`

component Component - React component to extend. This cannot be a Stateless Functional Component (SFC)!
options Object - Options map. Default: {}
- liftProvided Boolean|String[] - Boolean True will lift all provided keys which are undefined on the component instance. An array of strings will only lift the named keys. Default: false
Returns: ConnectedComponent - Your component, extended with provider bindings.

TypeDef: ConnectedComponent

This is not a single class. The connected(...) method returns an extended version of the Component, and those extensions are referred to as connected components.

Property: `component.provided` Object

Reference to the properties attached to ancestor <Provider> components.

Method: `component.connect(name, callback)`

Subscribe a callback to a provided Observable. The callback will be called whenever the observable is updated.

name String - The name of the <Provider> property containing the observable value.
callback Function - A function which accepts the observable value.
Returns: Subscription - A subscription which can be cancelled.

This method should generally be called in a component's componentWillMount() method, because the connection will automatically be canceled when the component will un-mount.

Method: `component.connectState(name[, options])`

Subscribe the component to a provided StateObservable. The state of the observable will be immediately attached to the component's state object under the observable's name, and all changes to the state will update the component's state.

name String - The name of the <Provider> property containing the observable value, and the name of the component state property which will contain the observable's state.
options Object - Options map. Default: {}
- map Function - A function which accepts the state value and transform it before it is attached to the component's state. Default: state => state
- alias String - The name of the component state property which will contain the observable's state. Default: name
Returns: Subscription - A subscription which can be cancelled.

This method should generally be called in a component's componentWillMount() method, because the connection will automatically be canceled when the component will un-mount.

Method: `component.connectDomEvent(domElement, name, callback[, useCapture])`

Subscribe to a DOM event.

domElement DOMElement - The DOM element to which a listener will be attached.
name String - The event name.
callback Function - A function which will be called when the DOM event is triggered.
useCapture Boolean - True to handle the event on capture (root -> child), or false to handle on bubble (child -> root).
Returns: Subscription - A subscription which can be cancelled.

This method should generally be called in a component's componentWillMount() method, because the connection will automatically be canceled when the component will un-mount.

Method: `component.disconnect()`

Close all connections created by the connect(...), connectState(...), and connectDomEvent(...) methods.

TypeDef: StateObservable

A StateObservable is an extension of the ES Observable Proposal with a state property which contains the last value emitted by the observable. Politic's Store is an example of an observable with state.