react-f v0.1.3

react-f

react-f is a library to help you create and compose higher-order-components in a sophisticated, though predictable manner.

You can use react-f to build your own general-purpose higher-order-components, compose and extend someone else's hoc's or use it's rudimental form handling example hoc's.

Installation

To install run

npm install --save react-f

or

yarn add react-f

react-f uses react as a peer dependency, so you also need to install react.

Usage

react-f is written in Typescript and offers all benefits of it's static typing out of the box. For the sake of simplicity the following examples will be in Javascript.

Providing values

In the most basic cases, a HOC will only provide (static) data to other component:

import React from "react"
import ReactDOM from "react-dom"
import { createHOC } from "react-f"

/*
 * Creating a new HOC
 * for this example, let's assume we want to expose a custom set of translations to your react components.
 * we want to encapsulate the logic of managing those values and deciding which translation to use in our
 * hoc, so that our presentational components are clearly seperated from this concern
 */
const I18N = createHOC({
    name: "herrmanno/I18N",
    class: class extends React.Component {

        i18n = {
            en: { greeting: "Hello" },
            de: { greeting: "Hallo" }
        }

        /*
         * This is the only method our class has to implement.
         * The return value of this function is the public API of our HOC
         * and will be exposed to all using presentational components later
         */
        getChildProps() {
            return {
                i18n: this.i18n[navigator.language] || this.i18n.en
            }
        }
    }
})

/**
 * Greeting is a presentational component.
 * It does not have a state or logic and does not know
 * how to receive the i18 prop that it desires
 */
const Greeting = (props) => (
    /*
     * You can also access the translations by extracting them from the props manually, like so:
     * {[I18N.ID]: i18nprops} = props
     * // i18nprops.i18n === {greeting: ...}
     */
    <span>{I18N.props(props).i18n.greeting} World</span>
)

/**
 * This is the 'dumb' greeting component wrapped in our HOC
 */
const I18NGreeting = I18N(/* here does hoc options go*/)(Greeting)

ReactDOM.render(<I18NGreeting />, document.body) // <span>Hello</span> or <span>Hallo</span>

Managing state

We can extend this example a litte bite. Maybe we want the user to be able to switch the language. This would be a good example of a HOC that is stateful, in order to keep the presentational component pure and simple.

import React from "react"
import ReactDOM from "react-dom"
import { createHOC } from "react-f"

/*
 * Creating a new HOC
 * this HOC is stateful, meaning it has a state property, which may change over time by calling React's setState method.
 * Anytime its state updates it will (potentionally) rerender, which causes its children to get the updated HOC's API values.
 */
const I18N = createHOC({
    name: "herrmanno/I18N",
    class: class extends React.Component {

        state = {
            i18n: {
                en: { greeting: "Hello" },
                de: { greeting: "Hallo" }
            },
            lang: "en"
        }

        getChildProps() {
            return {
                i18n: this.state.i18n[this.state.lang],
                setLanguage: (lang) => {
                    this.setState({lang})
                }
            }
        }
    }
})

/**
 * The HOC can also be applied like a decorator.
 * Watch out to call it (!) when applying it this way,
 * I18N is a function which returns the *actual* wrapper function
 */
@I18N()
class Greeter extends React.Component {
    render() {
        const { i18n, setLanguage } = I18N.props(this)
        return <div>
            <span>{i18n.greeting} World</span>
            <select onChange={e => setLanguage(e.target.value)}>
                <option value="en">English</option>
                <option value="de">Deutsch</option>
            </select>
        </div>
    }
}

ReactDOM.render(<Greeter/>, document.body) // <span>Hello</span> or <span>Hallo</span>

Examples

See the examples for real-life samples of how you could build your own higher-order components or combine the build-in ones to create powerful forms.

The build-in HOCs

The main purpose of react-f is to help you build robust higher-order components with a consistent interface that fit your needs as close as possible. For this reason it's abilities are relative low level. One of its main goals is to give you all the tools you need to create powerful components while getting out of your way. Though, react-f ships a handful of prebuild components. You are free to use these components but keep in mind that they're primarily examples on how to use react-f.