yourchoice-redux

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)

common types used in API specification

```javascript type State = any; type Item = any; type Action = any; ```

reducer

```javascript reducer(state: State, action: Action): State ``` Standard signature reducer, which can be added anywhere in your reducer hierarchy.

bindToSelection

```javascript bindToSelection(selectionName: string = 'selection'): BoundAPI

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.

action creator: remove

```javascript remove(items: Item[]): Action ``` Removes the given `items` from the current selection.

action creator: removeAll

```javascript removeAll(): Action ``` Removes all items from the current selection.

action creator: replace

```javascript replace(item: Item): Action ``` Replaces the current selection with the given `item`. Also defines this item as the starting point for a subsequent [`rangeTo()`](#actionsrangeto--action) selection. This is equivalent to a simple click by the user in a file manager.

action creator: setItems

```javascript setItems(selectableItems: Item[]): Action; ``` Changes the current set of items that can be selected/deselected.

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.

action creator: setSelection

```javascript setSelection(selectedItems: Item[]): Action ``` Replaces the current selection with the given `items`.

action creator: toggle

```javascript toggle(item: Item): Action ``` Adds or removes the given `item` to/from the selection. Other currently selected items are not affected. Also defines this item as the starting point for a subsequent [`rangeTo()`](#actionsrangeto--action) selection if it is added to the selection. This is equivalent to an alt+click (cmd+click) by the user in a file manager.

selector: getItems

```javascript getItems(state: State): Item[] ``` Returns an array containing all selectable items.

selector: getSelection

```javascript getSelection(state: State): Item[]

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.

selector: getChangedDeselection

```javascript getChangedDeselection(state: State): Item[] ``` Returns an array containing those items that have been removed from the selection by the directly preceding operation. E.g. calling this after a call to [`rangeTo()`](#actionsrangeto--action) will return all the items that have been removed from the selection by this operation.