Yourchoice

YourChoice resembles the selection behavior of popular file managers. Pick items from a list using convenient functions like range selection. YourChoice covers the computation of the actual selection, no UI involved.

Installing

With npm

npm install yourchoice --save

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

Caution: Yourchoice uses es6/es7 features which are not supported in IE11 You can polyfill it with core-js

require('core-js/modules/es6.symbol')
require('core-js/modules/es6.array.from')
require('core-js/modules/es6.array.iterator')
require('core-js/modules/es6.object.assign')
require('core-js/modules/es7.array.includes')

Script tag

If you are the retro kind of person, you can also download the JavaScript file.

<script type="text/javascript" src="https://github.com/actano/yourchoice/raw/master/yourchoice.js"></script>

Usage

Yourchoice provides a functional interface. It is well-suited to be used in conjunction with lodash/flow or Redux. Of course, this interface can also be used in a non-functional environment. The imperative interface of yourchoice is considered deprecated.

All functions of yourchoice take an object of type State as their last argument. Some of the functions also return an updated State object. The state object is an opaque object representing the current state of yourchoice. The properties of this object are private and one should not depended upon them. In order to read properties form the state yourchoice provides accessor methods such as getSelection().

All functions exported by yourchoice are curried. That means that these functions can be partially applied with a subset of their arguments. This is particularly useful in conjunction with libraries like lodash/flow.

Example

const selectableItems = ['A', 'B', 'C', 'D', 'E']
const state = init()

newState = flow(
  setItems(selectableItems),
  replace('B'),
  rangeTo('D')
)(state)

console.log(getSelection(newState)) // ['B', 'C', 'D']

init() : State

Returns an empty state with no selection and no items that can be selected.

setItems(selectableItems, state) : State

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 function is usually called initially before any selection is performed. This function should be called in order to update the yourchoice 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.

replace(item, state) : State

Replaces the current selection with the given item. Also defines this item as the starting point for a subsequent rangeTo() selection. This is equivalent to a simple click by the user in a file manager.

toggle(item, state) : State

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() selection if it is added to the selection. This is equivalent to an alt+click (cmd+click) by the user in a file manager.

rangeTo(item, state) : State

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.

setSelection(items, state) : State

Replaces the current selection with the given items.

remove(items, state) : State

Removes the given items from the current selection.

removeAll(state) : State

Removes all items from the current selection.

getItems(state) : Array

Returns an array containing all selectable items.

getSelection(state) : Array

Returns an array containing the currently selected items.

getChangedSelection(state) : Array

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.

getChangedDeselection(state) : Array

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() will return all the items that have been removed from the selection by this operation.