https://github.com/goto-bus-stop/item-selection

Manage multi-`<select>` style array selection state.
https://github.com/goto-bus-stop/item-selection

collection list range selection

Last synced: 27 days ago
JSON representation

Manage multi-`<select>` style array selection state.

• Host: GitHub
• URL: https://github.com/goto-bus-stop/item-selection
• Owner: goto-bus-stop
• License: mit
• Created: 2015-11-05T09:19:26.000Z (about 9 years ago)
• Default Branch: default
• Last Pushed: 2024-04-29T04:17:39.000Z (7 months ago)
• Last Synced: 2024-10-05T16:26:04.137Z (about 1 month ago)
• Topics: collection, list, range, selection
• Language: JavaScript
• Homepage: https://goto-bus-stop.github.io/item-selection
• Size: 172 KB
• Stars: 6
• Watchers: 2
• Forks: 0
• Open Issues: 2
• Metadata Files:
  • Readme: readme.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# item-selection

Manage multi-`` style selections in arrays.

## Usage

[Demo](https://goto-bus-stop.github.io/item-selection) - [Demo source code](./example.js)

```js

import itemSelection from 'item-selection'

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

let selection = itemSelection(sourceList)

// Methods behave similarly to selection operations in a , 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 `` element.

If you want to _add_ an item to the selection, use [`selection.add(index)`](#selection--selection-addindex)

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](./LICENSE)