yourchoice-redux

Redux wrapper for yourchoice.

Installing

With npm

npm install yourchoice-redux --save

Since yourchoice-redux is a frontend module, you will need a module bundler like webpack or browserify.

Caution: Yourchoice Redux uses Symbol.iterator which is not yet supported by all environments. You can polyfill it with core-js

if (!window.Symbol) {
  require('core-js/es6/symbol')
}

Usage

Reducer

YourChoice Redux provides a reducer with a standard signature (state, action) => nextState.

import {createStore, combineReducers} from 'redux'

import {reducer as yourchoiceReducer} from 'yourchoice-redux'

// connect to store
const store = createStore(combineReducers({
    // ... other reducers
    yourchoice: yourchoiceReducer
}))

Bind to selection

bindToSelection returns an object that contains the yourchoice actions and selectors bound to a specific selection.

import {bindToSelection} from 'yourchoice-redux'

// bind yourchoice to specific selection name
// if the selectionName is omitted it defaults to 'selection'
const mySelection = bindToSelection('my-selection');
/*
returns {
    actions: {
        setItems,
        rangeTo,
        remove,
        ...
    },
    selectors: {
        getSelection,
        getChangedSelection,
        ...
    }
}
*/

Selectors

Selectors need to be given the substate the reducer acts on.

export {
    getItems: (state) => mySelection.selectors.getItems(state.yourchoice)
}

Examples

Simple use case

import {createStore, combineReducers} from 'redux'
import {bindToSelection, reducer as yourchoiceReducer} from 'yourchoice-redux'
const selection = bindToSelection()

// connect to store
const store = createStore(combineReducers({
    // ... other reducers
    yourchoice: yourchoiceReducer
}))

// connect to ReactComponent
const mapStateToProps = (state) => {
  return {
    myList: selection.selectors.getItems(state.yourchoice),
    mySelection: selection.selectors.getSelection(state.yourchoice)
  }
}

// dipatch actions
store.dispatch(selection.actions.setItems([1, 2, 5, 8]))
store.dispatch(selection.actions.replace(2))

Bind more than one selection

// add global reducer to store at mountpoint yourchoice (see above)

// get action creators and selectors bound to selection name 'users'
const userSelection = bindToSelection('users');

...
store.dispatch(userSelection.actions.setItems(userList));
store.dispatch(userSelection.actions.replace('user-id-1'));
...
// get selector
const getSelectedUsers = (state) => userSelection.selectors.getSelection(state.yourchoice)

// get action creators and selectors bound to selection name 'teams'
const teamSelection = bindToSelection('teams');
...

API

• reducer(state, action)
• bindToSelection(selectionName)
• action creator: rangeTo(toItem)
• action creator: remove(itemsToRemove)
• action creator: removeAll()
• action creator: replace(item)
• action creator: setItems(selectableItems)
• action creator: setSelection(selectedItems)
• action creator: toggle(item)
• selector: getChangedSelection(state)
• selector: getChangedDeselection(state)
• selector: getItems(state)
• selector: getSelection(state)

type BoundAPI = { actions: ActionCreators; selectors: Selectors; };

type ActionCreators = { rangeTo: (item: Item) => Action; remove: (items: Item[]) => Action; removeAll: () => Action; replace: (item: Item) => Action; setItems: (items: Item[]) => Action; setSelection: (items: Item[]) => Action; toggle: (item: Item) => Action; };

type Selectors = { getChangedSelection: (state: State) => Item[]; getChangedDeselection: (state: State) => Item[]; getItems: (state: State) => Item[]; getSelection: (state: State) => Item[]; };

`bindToSelection` returns an object containing all the following action creators and selectors, bound to the given selection name.

<h3 id="_action_rangeTo">action creator: rangeTo</h3>
```javascript
rangeTo(item: Item): Action

Selects a range of items usally starting from the previously toggled or replaced item and ending at the given item. This is equivalent to a shift+click by the user in a file manager.

The selectableItems can be any javascript iterable. This enables yourchoice to operate on any data structure. Native data types such as Array or Map implement the iterable protocol.

This action is usually dispatched initially before any selection is performed. This action should be called in order to update the state when selectable items have been added or removed. For example, if some of the currently selected items are not present in the given selectableItems anymore, then these items will be automatically removed from the current selection.

Consider using a store middleware or saga to do this.

Returns an array containing the currently selected items.

<h3 id="_selector_getChangedSelection">selector: getChangedSelection</h3>
```javascript
getChangedSelection(state: State): Item[]

Returns an array containing those items that have been added to the selection by the directly preceding operation. E.g. calling this after a call to rangeTo() will return all the items that have been added to the selection by this operation.