list-node-hooks v0.1.0

list-node-hooks

npm install list-node-hooks --save

A React list component that allows you to manipulate dom-nodes on transitions

Overview

When will this be usefull? Well, for animation purposes for instance. It might not be a good idea to manipulate dom-nodes outside of React (anti-pattern), but sometimes you have choose simplicity over correctness and be pragmatic.

This higher order component figures out how it's children change over time, and passes the corresponding dom-nodes to the 'hooks' you've provided.

Basic usage

import listNodeHooks from 'list-node-hooks';
import React, { Component } from 'react';

const hooks = {
    listMount(nodes) {
        // do something with these nodes...
    }
};

// decorate a class
@listNodeHooks(hooks)
class List extends Component {
    render() {
        return (
            <div>
                {this.props.children}
            </div>
        );
    }
}

// or shortcut
const List = listNodeHooks(hooks)('div');

class App extends Component {

    state = {
        items: [
            { id: 1, text: 'item1' },
            { id: 2, text: 'item2' },
            { id: 3, text: 'item3' },
            { id: 4, text: 'item4' }
        ]
    };

    render() {
        return (
            <List>
                { this.state.items.map(({ id, text }) => <div key={id}>{text}</div>) }
            </List>
        );
    }
}

API

listNodeHooks(hooks: Object): (Component | Element | string): Component

Typical decorator pattern.

'hooks' is an object with certain functions that will be called by the decorated component. (See 'Hooks' for the specs). It will return a function that wraps a Component, Element or string.

Usage:

// es6
const Enhanced = listNodeHooks({})(Component);

// es7
@listNodeHooks({})

Hooks

listMount(nodes: Node[])

Will be called after the List has mounted (componentDidMount) or when it receives new children after the instance method 'flush' has been called.

listOrder({ node: Node, x: Int, y: Int, w: Int, h: Int}[])

Will be called after the order of the children has changed. 'x', 'y', 'w', 'h' represent the amount of pixels left, top, width and height has changed since the node's last position. Cool for animation!

itemsAdd(nodes: Node[])

Will be called when chilren are added to the list.

itemsDelete(nodes: Node[], cb: Function)

Will be called when chilren are deleted. The callback must be called after DOM manipulation in order for the list component to know that the elements are ready to be unmounted.

itemsChange(nodes: Node[])

Will be called when props of children changed.

Instance.flush(cb: Function, ?hook: string = 'itemsDelete')

Enables you to delete all children in the list without unmouting. By default the hook 'itemsDelete' will be called, unless you provide a custom hook for it.

Example:

import listNodeHooks from 'list-node-hooks';
import React, { Component } from 'react';

const hooks = {
    itemsFlush(nodes, cb) {
        // do something with these nodes...

        // invoke callback to continue unmouting
        cb();
    }
};

const List = listNodeHooks(hooks)('div');

class App extends Component {

    state = {
        items: [
            { id: 1, text: 'item1' },
            { id: 2, text: 'item2' },
            { id: 3, text: 'item3' },
            { id: 4, text: 'item4' }
        ]
    };

    _flush = () => this.list.flush(() => {
        // do something here, like fetching new data
    }, 'itemsFlush')

    render() {
        return (
            <div>
                <button onClick={this._flush}>Flush</button>
                <List ref={c => this.list = c}>
                    { this.state.items.map(({ id, text }) => <div key={id}>{text}</div>) }
                </List>
            </div>
        );
    }
}

Example

clone this repo, and:

npm install && npm run example