Document methods

Closes simonwep#170

packages/vanilla/README.md

@@ -90,7 +90,7 @@ text-selection, add the following to the container where all your selectables ar
 }
 ```
 
-### Usage
+### Configuration
 
 ```ts
 const selection = new SelectionArea({
@@ -179,13 +179,31 @@ const selection = new SelectionArea({
 
 Use the `on(event, cb)` and `off(event, cb)` functions to bind / unbind event-listener.
 
-| Event | Description |
-| ----- | ----------- | 
-| `beforestart` | The user tapped one of the areas within the specified boundaries. Return `false` to cancel selection immediatly.  |
-| `beforedrag` | Same as `beforestart` but _before_ the user starts selecting by dragging the mouse. Can be used to conditionally allow a selection by dragging. Return `false` to cancel the selection. |
-| `start` | Selection started, here you can decide if you want to keep your previously selected elements. | 
-| `move` | Selection is active, user is moving the pointer around. |
-| `stop` | Selection has stopped. |
+
+| Event         | Description                                                                                                                                                                             |
+|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 
+| `beforestart` | The user tapped one of the areas within the specified boundaries. Return `false` to cancel selection immediatly.                                                                        |
+| `beforedrag`  | Same as `beforestart` but _before_ the user starts selecting by dragging the mouse. Can be used to conditionally allow a selection by dragging. Return `false` to cancel the selection. |
+| `start`       | Selection started, here you can decide if you want to keep your previously selected elements.                                                                                           | 
+| `move`        | Selection is active, user is moving the pointer around.                                                                                                                                 |
+| `stop`        | Selection has stopped.                                                                                                                                                                  |
+
+### Functions
+
+| Function                                                        | Description                                                                                                    |
+|-----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
+| `trigger(evt: MouseEvent / TouchEvent, silent = true): void`    | Manually trigger a selection.                                                                                  |
+| `resolveSelectables(): void`                                    | Updates the list of selectables, useful if new elements have been added during a selection.                    |
+| `clearSelection(includeStored = true): void`                    | Clears the selection, pass `false` to keep previously selected elements.                                       |
+| `getSelection(): Element[]`                                     | Returns currently selected element. Use it in the `stop` event to collect selected elements.                   |
+| `getSelectionArea(): HTMLElement`                               | Returns the selection area element.                                                                            |
+| `cancel(keepEvent = false): void`                               | Cancel the currently active selection, pass true to trigger the `stop` event afterwards.                       |
+| `destroy(): void`                                               | Destroy the `SelectionArea`-instance, removes all event-listeners and the selection-area element from the DOM. |
+| `disable(): void`                                               | Disables the selection-area temporarily.                                                                       |
+| `enable(): void`                                                | Enables the selection-area.                                                                                    |
+| `select(query: SelectAllSelectors, quiet = false): Element[]`   | Manually select elements, if `quiet` is set to `true` this will not fire the `move` & `stop` event.            |                                                                                                    
+| `deselect(query: SelectAllSelectors, quiet = false): Element[]` | Manually deselect elements, if `quiet` is set to `true` this will not fire the `move` & `stop` event.          |
+
 
 ### Example
 
@@ -228,12 +246,12 @@ Every event comes with the following properties:
     selection: SelectionArea // Current instance
     event: TouchEvent | MouseEvent | null // TouchEvent, MouseEvent or `null` if triggered manually
     store: {
-        touched: Array<Element> // Touched elements
-        selected: Array<Element> // Elements from the currently active selection (each click, drag counts as a single "selection") 
-        stored: Array<Element> // Elements currently selected (in total, not just an instant)
+        touched: Element[] // Touched elements
+        selected: Element[] // Elements from the currently active selection (each click, drag counts as a single "selection") 
+        stored: Element[] // Elements currently selected (in total, not just an instant)
         changed: {
-            added: Array<Element> // Added elements since last change
-            removed: Array<Element> // Removed elements since last change
+            added: Element[] // Added elements since last change
+            removed: Element[] // Removed elements since last change
         }
     }
 }

packages/vanilla/src/index.ts

@@ -33,7 +33,7 @@ export default class SelectionArea extends EventTarget<SelectionEvents> {
     // Target container (element) and boundary (cached)
     private _targetElement?: Element;
     private _targetRect?: DOMRect;
-    private _selectables: Array<Element> = [];
+    private _selectables: Element[] = [];
     private _latestElement?: Element;
 
     // Caches the position of the selection-area
@@ -657,11 +657,11 @@ export default class SelectionArea extends EventTarget<SelectionEvents> {
 
     /**
      * Clear the elements which where saved by 'keepSelection()'.
-     * @param store If the store should also get cleared
+     * @param includeStored If the store should also get cleared
      */
-    clearSelection(store = true): void {
+    clearSelection(includeStored = true): void {
         this._selection = {
-            stored: store ? [] : this._selection.stored,
+            stored: includeStored ? [] : this._selection.stored,
             selected: [],
             touched: [],
             changed: {
@@ -674,7 +674,7 @@ export default class SelectionArea extends EventTarget<SelectionEvents> {
     /**
      * @returns {Array} Selected elements
      */
-    getSelection(): Array<Element> {
+    getSelection(): Element[] {
         return this._selection.stored;
     }
 
@@ -687,7 +687,7 @@ export default class SelectionArea extends EventTarget<SelectionEvents> {
 
     /**
      * Cancel the current selection process.
-     * @param keepEvent {boolean} true to fire the onStop listener after cancel.
+     * @param keepEvent {boolean} true to fire a stop event after cancel.
      */
     cancel(keepEvent = false): void {
         this._onTapStop(null, !keepEvent);
@@ -712,7 +712,7 @@ export default class SelectionArea extends EventTarget<SelectionEvents> {
      * @param query - CSS Query, can be an array of queries
      * @param quiet - If this should not trigger the move event
      */
-    select(query: SelectAllSelectors, quiet = false): Array<Element> {
+    select(query: SelectAllSelectors, quiet = false): Element[] {
         const {changed, selected, stored} = this._selection;
         const elements = selectAll(query, this._options.document).filter(el =>
             !selected.includes(el) &&

packages/vanilla/src/types.ts

@@ -1,22 +1,22 @@
 import type SelectionArea from '@vanilla/index';
 import type {Intersection} from './utils';
 
-export type Quantify<T> = ReadonlyArray<T> | T;
+export type Quantify<T> = Readonly<T[]> | T;
 
 export interface ScrollEvent extends MouseEvent {
     deltaY: number;
     deltaX: number;
 }
 
 export interface ChangedElements {
-    added: Array<Element>;
-    removed: Array<Element>;
+    added: Element[];
+    removed: Element[];
 }
 
 export interface SelectionStore {
-    touched: Array<Element>;
-    stored: Array<Element>;
-    selected: Array<Element>;
+    touched: Element[];
+    stored: Element[];
+    selected: Element[];
     changed: ChangedElements;
 }
 

packages/vanilla/src/utils/events.ts

@@ -4,16 +4,16 @@ type Method = 'addEventListener' | 'removeEventListener';
 type AnyFunction = (...arg: any) => any;
 
 export type EventBindingArgs = [
-        EventTarget | Array<EventTarget>,
-        string | Array<string>,
+        EventTarget | EventTarget[],
+        string | string[],
     AnyFunction,
     Record<string, unknown>?
 ];
 
 interface EventBinding {
     (
-        elements: EventTarget | Array<EventTarget>,
-        events: string | Array<string>,
+        elements: EventTarget | EventTarget[],
+        events: string | string[],
         fn: AnyFunction,
         options?: Record<string, unknown>
     ): EventBindingArgs;
@@ -22,8 +22,8 @@ interface EventBinding {
 /* eslint-disable prefer-rest-params */
 function eventListener(method: Method): EventBinding {
     return (
-        items: EventTarget | Array<EventTarget>,
-        events: string | Array<string>,
+        items: EventTarget | EventTarget[],
+        events: string | string[],
         fn: AnyFunction, options = {}
     ): EventBindingArgs => {
 
@@ -92,8 +92,8 @@ export const simplifyEvent = (evt: any): {
  * @param evt The event object.
  * @return [String] event path.
  */
-export function eventPath(evt: any): Array<EventTarget> {
-    let path: Array<EventTarget> = evt.path || (evt.composedPath && evt.composedPath());
+export function eventPath(evt: any): EventTarget[] {
+    let path: EventTarget[] = evt.path || (evt.composedPath && evt.composedPath());
     if (path) {
         return path;
     }

packages/vanilla/src/utils/selectAll.ts

@@ -6,7 +6,7 @@ export type SelectAllSelectors = readonly (string | Element)[] | string | Elemen
  * @param doc
  * @returns {Array} Array of DOM-Nodes.
  */
-export function selectAll(selector: SelectAllSelectors, doc: Document = document): Array<Element> {
+export function selectAll(selector: SelectAllSelectors, doc: Document = document): Element[] {
     const list = !Array.isArray(selector) ? [selector] : selector;
 
     const nodes = [];