item-selection

Manage multi-<select> style selections in arrays.

Usage

Demo - Demo source code

import itemSelection from 'item-selection'

const sourceList = [ 'a', 'b', 'c', 'd' ]

let selection = itemSelection(sourceList)

// Methods behave similarly to selection operations in a <select multiple>, or
// eg. your average file manager:

selection = selection.select(0) // like clicking
selection.get() // ['a']
selection = selection.selectRange(2) // like shift+clicking
selection.get() // ['a', 'b', 'c']
selection = selection.selectToggle(1) // like ctrl+clicking
selection.get() // ['a', 'c']

An itemSelection is immutable by default, i.e. it returns a new selection object. Use import itemSelection from 'item-selection/mutable' if you want to mutate the current selection object instead.

API

selection = itemSelection(sourceList)

Creates a new selection manager object.

All mutation methods return a new selection manager object by default. If you want to mutate and reuse the same object, use import itemSelection from 'item-selection/mutable'.

selection = selection.select(index)

Creates a selection with just the item at the given index selected. Akin to clicking an item in a <select multiple> element.

If you want to add an item to the selection, use selection.add(index) instead.

Also sets the initial range index to index.

selection = selection.deselect(index)

Deselects the item at index.

selection = selection.selectToggle(index)

Selects or deselects the item at index. Akin to Ctrl+clicking.

Also sets the initial range index to index if a new item was selected. Otherwise, unsets the initial range index.

selection = selection.selectRange(start, end)

Selects the given range. Inclusive. (NB: That's different from what Array.slice does!)

selection = selection.selectRange(index)

Selects a range based on the initial range index and the index. Akin to Shift+clicking. Previously selected items that fall outside the range will be deselected.

If the initial range index was not set using select(index) or selectToggle(index), selectRange only selects the given index.

selection = selection.selectAll()

Adds all items to the selection.

selection = selection.add(index)

Adds the item at index to the selection.

Also sets the initial range index to index.

selection = selection.remove(index)

Removes the item at index from the selection.

selection = selection.clear()

Deselect all items.

selectedItems = selection.get()

Get an array of the selected items.

selectedIndices = selection.getIndices()

Get an array of the selected indices.

selection = selection.set(indices)

Set a custom array of selected indices.

Licence

MIT