Recompose: Update documentation to include examples.

Created on 4 Apr 2017 · 15Comments · Source: acdlite/recompose

There's an overall ticket for documentation with some larger goals, but I think that one or two examples per component / function can go a long way for the least amount of work.

Creating this issue for myself so I know where to focus, but I can update it as other pull requests are merged in.

I also included checklists on working with type annotations. I'm still figuring out how to use recompose with either Flow or TypeScript, so help would be appreciated there.

Higher-order components

[x] mapProps()
[ ] withProps()
[ ] withPropsOnChange()
[x] withHandlers()
[ ] defaultProps()
[ ] renameProp()
[ ] renameProps()
[x] flattenProp()
[x] withState()
[ ] withReducer()
[ ] branch()
[x] renderComponent()
[x] renderNothing()
[ ] shouldUpdate()
[ ] pure()
[x] onlyUpdateForKeys()
[x] onlyUpdateForPropTypes()
[ ] withContext()
[ ] getContext()
[ ] lifecycle()
[ ] toClass()

Static property helpers

[ ] setStatic()
[ ] setPropTypes()
[ ] setDisplayName()

Utilities

[ ] compose()
[ ] getDisplayName()
[ ] wrapDisplayName()
[ ] shallowEqual()
[ ] isClassComponent()
[ ] createEagerElement()
[ ] createEagerFactory()
[ ] createSink()
[x] componentFromProp()
[x] nest()
[ ] hoistStatics()

Observable utilities

[x] componentFromStream()
[x] mapPropsStream()
[ ] createEventHandler()
[x] setObservableConfig()

TypeScript

[ ] usage and limitations
[ ] compose()
[ ] type hinting with generics

TypeScript

[ ] usage and limitations
[ ] compose()
[ ] type hinting with generics

Source

threehams

👍17 ❤4

Most helpful comment

@threehams I'm have a full length (~45min) course being released this month all about Recompose and Higher Order Components. I had to generate various examples in order to teach the concepts. Please feel free to link to, get inspiration from, migrate to plunkr, or steal my examples.

They are here: https://github.com/timkindberg/egghead-recompose

The folders are named the same as the lessons in my course.

I'd recommend plunkr, here's a bin with recompose already set up for one of my lesson examples: https://plnkr.co/edit/VN8Ez0E5g6gXjo9uPUJT?p=preview

timkindberg on 4 Apr 2017

👍3

All 15 comments

For flow typings more information here

istarkov on 4 Apr 2017

They are here: https://github.com/timkindberg/egghead-recompose

The folders are named the same as the lessons in my course.

I'd recommend plunkr, here's a bin with recompose already set up for one of my lesson examples: https://plnkr.co/edit/VN8Ez0E5g6gXjo9uPUJT?p=preview

timkindberg on 4 Apr 2017

👍3

I should mention that all of my examples are already written in a plunkr-friendly manner, mainly in how I destructure my imports into consts instead of using 'import'.

timkindberg on 4 Apr 2017

@istarkov Thanks, I've been using both recompose and Flow at work, but haven't been able to look too in-depth yet (I use TypeScript for side projects). I'll see if I can make some basic docs based on that thread.
@timkindberg Fantastic! I've been looking for more real-world examples to add, since they explain both syntax and usage guidelines at the same time; I especially like the mapProps example where you filter users.

threehams on 4 Apr 2017

Working on this again. It's hard to find a balance between overly complicated real-world examples and overly generic theoretical ones.

threehams on 16 Apr 2017

It'd be nice for the withHandlers docs to inform the user that calling state handling functions from a handler's props will lead to the state being updated but the view not rendering the current state correctly. withStateHandlers works as expected.

mfeineis on 27 Jul 2017

@mfeineis I don't understand what do you mean. Can you provide some example?

wuct on 31 Jul 2017

@wuct I had a situation where the state would be handled as expected but React wouldn't update the view until after the next state update but even then it would always be one step behind the present state that could be observed via the React Dev Tools. When I use withStateHandlers instead it works just fine - maybe it's a bug?

Edit 1: [email protected], [email protected]

import React from 'react';
import ReactDOM from 'react-dom';
import { compose, mapProps, withState, withHandlers } from 'recompose';

const toggleSelection = ({ setSelectedItems }) => (event, item) => {
    event.preventDefault();

    setSelectedItems(old => {
        const selection = new Set(old);

        if (selection.has(item.id)) {
            selection.delete(item.id);
        } else {
            selection.add(item.id);
        }

        return selection;
    });
};

const enhance = compose(
    mapProps(({ items }) => ({ items })),
    withState('selectedItemsLookup', 'setSelectedItems', new Set()),
    withHandlers({
        toggleSelection,
    }),
);

const Enhanced = enhance(({ items, toggleSelection }) => (
    <ul>
        {items.map(item => (
            <li key={item.id}>
                <label>
                    <input type="checkbox" onClick={e => toggleSelection(e, item)}/>
                    <span>{item.name}</span>
                </label>
            </li>
        ))}
    </ul>
));

ReactDOM.render(<Enhanced items={[{ id: 'item1', name: 'Item 1' }, { id: 'item2', name: 'Item 2' }]}/>, document.getElementById('root'));

mfeineis on 31 Jul 2017

@mfeineis Your code works fine except that you should not call preventDefault(). You can find the reason here and here is a working version jsfiddle of your code.

wuct on 31 Jul 2017

@wuct thx for the heads up. Seems about right, sorry didn't see that issue. As I said I'm using withStateHandlers now and it's doing the job just fine.

mfeineis on 31 Jul 2017

@mfeineis I'm glad to hear that ;)

wuct on 2 Aug 2017

@threehams If you still on this I recently got merged PR with lifecycle example