[MultiSelect] Enable pasting of multiple values (same as TagInput)

packages/core/src/components/tag-input/tagInput.tsx

@@ -15,6 +15,26 @@ import * as Utils from "../../common/utils";
 import { Icon, IconName } from "../icon/icon";
 import { ITagProps, Tag } from "../tag/tag";
 
+/**
+ * An enumeration of methods in which a `TagInput` value might have been added.
+ */
+export enum TagInputAddMethod {
+    /** Indicates that a value was added in the default fasion, via manual selection. */
+    DEFAULT = "default",
+
+    /**
+     * Indicates that a value was added when the `TagInput` lost focus. This is
+     * only possible when `addOnBlur=true`.
+     */
+    BLUR = "blur",
+
+    /**
+     * Indicates that a value was added via paste. This is only possible when
+     * `addOnPaste=true`.
+     */
+    PASTE = "paste",
+}
+
 export interface ITagInputProps extends IIntentProps, IProps {
     /**
      * If true, `onAdd` will be invoked when the input loses focus.
@@ -74,7 +94,7 @@ export interface ITagInputProps extends IIntentProps, IProps {
      * returns `false`. This is useful if the provided `value` is somehow invalid and should
      * not be added as a tag.
      */
-    onAdd?: (values: string[]) => boolean | void;
+    onAdd?: (values: string[], method: TagInputAddMethod) => boolean | void;
 
     /**
      * Callback invoked when new tags are added or removed. Receives the updated list of `values`:
@@ -260,10 +280,10 @@ export class TagInput extends AbstractPureComponent<ITagInputProps, ITagInputSta
         );
     }
 
-    private addTags = (value: string) => {
+    private addTags = (value: string, method: TagInputAddMethod = TagInputAddMethod.DEFAULT) => {
         const { inputValue, onAdd, onChange, values } = this.props;
         const newValues = this.getValues(value);
-        let shouldClearInput = Utils.safeInvoke(onAdd, newValues) !== false && inputValue === undefined;
+        let shouldClearInput = Utils.safeInvoke(onAdd, newValues, method) !== false && inputValue === undefined;
         // avoid a potentially expensive computation if this prop is omitted
         if (Utils.isFunction(onChange)) {
             shouldClearInput = onChange([...values, ...newValues]) !== false && shouldClearInput;
@@ -342,7 +362,7 @@ export class TagInput extends AbstractPureComponent<ITagInputProps, ITagInputSta
             // defer this check using rAF so activeElement will have updated.
             if (!currentTarget.contains(document.activeElement)) {
                 if (this.props.addOnBlur && this.state.inputValue !== undefined && this.state.inputValue.length > 0) {
-                    this.addTags(this.state.inputValue);
+                    this.addTags(this.state.inputValue, TagInputAddMethod.BLUR);
                 }
                 this.setState({ activeIndex: NONE, isInputFocused: false });
             }
@@ -367,7 +387,7 @@ export class TagInput extends AbstractPureComponent<ITagInputProps, ITagInputSta
         let activeIndexToEmit = activeIndex;
 
         if (event.which === Keys.ENTER && value.length > 0) {
-            this.addTags(value);
+            this.addTags(value, TagInputAddMethod.DEFAULT);
         } else if (selectionEnd === 0 && this.props.values.length > 0) {
             // cursor at beginning of input allows interaction with tags.
             // use selectionEnd to verify cursor position and no text selection.
@@ -405,7 +425,7 @@ export class TagInput extends AbstractPureComponent<ITagInputProps, ITagInputSta
         }
 
         event.preventDefault();
-        this.addTags(value);
+        this.addTags(value, TagInputAddMethod.PASTE);
     };
 
     private handleRemoveTag = (event: React.MouseEvent<HTMLSpanElement>) => {

packages/docs-app/src/examples/select-examples/films.tsx

@@ -210,6 +210,10 @@ export function areFilmsEqual(filmA: IFilm, filmB: IFilm) {
     return filmA.title.toLowerCase() === filmB.title.toLowerCase();
 }
 
+export function doesFilmEqualQuery(film: IFilm, query: string) {
+    return film.title.toLowerCase() === query.toLowerCase();
+}
+
 export function arrayContainsFilm(films: IFilm[], filmToFind: IFilm): boolean {
     return films.some((film: IFilm) => film.title === filmToFind.title);
 }

packages/docs-app/src/examples/select-examples/multiSelectExample.tsx

@@ -13,6 +13,7 @@ import {
     areFilmsEqual,
     arrayContainsFilm,
     createFilm,
+    doesFilmEqualQuery,
     filmSelectProps,
     IFilm,
     maybeAddCreatedFilmToArrays,
@@ -88,11 +89,13 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
                     initialContent={initialContent}
                     itemRenderer={this.renderFilm}
                     itemsEqual={areFilmsEqual}
+                    itemEqualsQuery={doesFilmEqualQuery}
                     // we may customize the default filmSelectProps.items by
                     // adding newly created items to the list, so pass our own
                     items={this.state.items}
                     noResults={<MenuItem disabled={true} text="No results." />}
                     onItemSelect={this.handleFilmSelect}
+                    onItemsPaste={this.handleFilmsPaste}
                     popoverProps={{ minimal: popoverMinimal }}
                     tagRenderer={this.renderTag}
                     tagInputProps={{ tagProps: getTagProps, onRemove: this.handleTagRemove, rightElement: clearButton }}
@@ -180,20 +183,29 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
     }
 
     private selectFilm(film: IFilm) {
-        const { films } = this.state;
+        this.selectFilms([film]);
+    }
 
-        const { createdItems: nextCreatedItems, items: nextItems } = maybeAddCreatedFilmToArrays(
-            this.state.items,
-            this.state.createdItems,
-            film,
-        );
+    private selectFilms(filmsToSelect: IFilm[]) {
+        const { createdItems, films, items } = this.state;
 
-        this.setState({
-            createdItems: nextCreatedItems,
+        let nextCreatedItems = createdItems.slice();
+        let nextFilms = films.slice();
+        let nextItems = items.slice();
+
+        filmsToSelect.forEach(film => {
+            const results = maybeAddCreatedFilmToArrays(nextItems, nextCreatedItems, film);
+            nextItems = results.items;
+            nextCreatedItems = results.createdItems;
             // Avoid re-creating an item that is already selected (the "Create
             // Item" option will be shown even if it matches an already selected
             // item).
-            films: !arrayContainsFilm(films, film) ? [...films, film] : films,
+            nextFilms = !arrayContainsFilm(nextFilms, film) ? [...nextFilms, film] : nextFilms;
+        });
+
+        this.setState({
+            createdItems: nextCreatedItems,
+            films: nextFilms,
             items: nextItems,
         });
     }
@@ -224,6 +236,12 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
         }
     };
 
+    private handleFilmsPaste = (films: IFilm[]) => {
+        // On paste, don't bother with deselecting already selected values, just
+        // add the new ones.
+        this.selectFilms(films);
+    };
+
     private handleSwitchChange(prop: keyof IMultiSelectExampleState) {
         return (event: React.FormEvent<HTMLInputElement>) => {
             const checked = event.currentTarget.checked;

packages/select/src/common/listItemsProps.ts

@@ -34,6 +34,13 @@ export interface IListItemsProps<T> extends IProps {
     /** Array of items in the list. */
     items: T[];
 
+    /**
+     * Whether the provided item fully matches the provided value. This is used
+     * to match pasted values to existing items, so that items can be emitted
+     * via `onItemsPaste`.
+     */
+    itemEqualsQuery?: (item: T, query: string) => boolean;
+
     /**
      * Specifies how to test if two items are equal. By default, simple strict
      * equality (`===`) is used to compare two items.
@@ -130,6 +137,11 @@ export interface IListItemsProps<T> extends IProps {
      */
     onItemSelect: (item: T, event?: React.SyntheticEvent<HTMLElement>) => void;
 
+    /**
+     * Callback invoked when multiple items are selected at once via pasting.
+     */
+    onItemsPaste?: (items: T[]) => void;
+
     /**
      * Callback invoked when the query string changes.
      */

packages/select/src/components/query-list/queryList.tsx

@@ -54,6 +54,24 @@ export interface IQueryListRendererProps<T>  // Omit `createNewItem`, because it
      */
     handleItemSelect: (item: T, event?: React.SyntheticEvent<HTMLElement>) => void;
 
+    /**
+     * Handler that should be invoked when the user pastes one or more values.
+     *
+     * This callback will use `itemEqualsQuery` to find a subset of `items`
+     * exactly matching the pasted `values` provided, then it will invoke
+     * `onItemsPaste` with those found items. Each pasted value that does not
+     * exactly match an item will be ignored.
+     *
+     * If creating items is enabled (by providing both `createNewItemFromQuery`
+     * and `createNewItemRenderer`), then pasted values that do not exactly
+     * match an existing item will emit a new item as created via
+     * `createNewItemFromQuery`.
+     *
+     * If `itemEqualsQuery` returns multiple matching items for a particular
+     * `value`, then only the first matching item will be emitted.
+     */
+    handlePaste: (values: string[]) => void;
+
     /**
      * Keyboard handler for up/down arrow keys to shift the active item.
      * Attach this handler to any element that should support this interaction.
@@ -152,6 +170,7 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
             handleItemSelect: this.handleItemSelect,
             handleKeyDown: this.handleKeyDown,
             handleKeyUp: this.handleKeyUp,
+            handlePaste: this.handlePaste,
             handleQueryChange: this.handleQueryChange,
             itemList: itemListRenderer({
                 ...spreadableState,
@@ -350,6 +369,40 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         }
     };
 
+    private handlePaste = (values: string[]) => {
+        const { createNewItemFromQuery, onItemsPaste } = this.props;
+
+        let nextActiveItem: T | undefined;
+
+        // Find an exising item that exactly matches each pasted value, or
+        // create a new item if possible. Ignore unmatched values if creating
+        // items is disabled.
+        const pastedItemsToEmit = values.reduce<T[]>((agg, value) => {
+            const equalItem = getMatchingItem(value, this.props);
+
+            if (equalItem !== undefined) {
+                nextActiveItem = equalItem;
+                agg.push(equalItem);
+            } else if (this.canCreateItems()) {
+                const newItem = Utils.safeInvoke(createNewItemFromQuery, value);
+                if (newItem !== undefined) {
+                    agg.push(newItem);
+                }
+            }
+
+            return agg;
+        }, []);
+
+        // UX nicety: update the active item if we matched with at least one
+        // existing item.
+        if (nextActiveItem !== undefined) {
+            this.setActiveItem(nextActiveItem);
+        }
+
+        // No need to update the active item.
+        Utils.safeInvoke(onItemsPaste, pastedItemsToEmit);
+    };
+
     private handleKeyDown = (event: React.KeyboardEvent<HTMLElement>) => {
         const { keyCode } = event;
         if (keyCode === Keys.ARROW_UP || keyCode === Keys.ARROW_DOWN) {
@@ -418,10 +471,8 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     }
 
     private isCreateItemRendered(): boolean {
-        const { createNewItemFromQuery } = this.props;
         return (
-            createNewItemFromQuery != null &&
-            this.props.createNewItemRenderer != null &&
+            this.canCreateItems() &&
             this.state.query !== "" &&
             // this check is unfortunately O(N) on the number of items, but
             // alas, hiding the "Create Item" option when it exactly matches an
@@ -430,6 +481,10 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         );
     }
 
+    private canCreateItems(): boolean {
+        return this.props.createNewItemFromQuery != null && this.props.createNewItemRenderer != null;
+    }
+
     private wouldCreatedItemMatchSomeExistingItem() {
         // search only the filtered items, not the full items list, because we
         // only need to check items that match the current query.
@@ -443,6 +498,19 @@ function pxToNumber(value: string | null) {
     return value == null ? 0 : parseInt(value.slice(0, -2), 10);
 }
 
+function getMatchingItem<T>(query: string, { items, itemEqualsQuery }: IQueryListProps<T>): T | undefined {
+    if (Utils.isFunction(itemEqualsQuery)) {
+        // .find() doesn't exist in ES5. Alternative: use a for loop instead of
+        // .filter() so that we can return as soon as we find the first match.
+        for (const item of items) {
+            if (itemEqualsQuery(item, query)) {
+                return item;
+            }
+        }
+    }
+    return undefined;
+}
+
 function getFilteredItems<T>(query: string, { items, itemPredicate, itemListPredicate }: IQueryListProps<T>) {
     if (Utils.isFunction(itemListPredicate)) {
         // note that implementations can reorder the items here

packages/select/src/components/select/multiSelect.tsx

@@ -14,6 +14,7 @@ import {
     Popover,
     Position,
     TagInput,
+    TagInputAddMethod,
     Utils,
 } from "@blueprintjs/core";
 import { Classes, IListItemsProps } from "../../common";
@@ -83,6 +84,7 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
             <this.TypedQueryList
                 {...restProps}
                 onItemSelect={this.handleItemSelect}
+                onItemsPaste={this.handleItemsPaste}
                 onQueryChange={this.handleQueryChange}
                 ref={this.refHandlers.queryList}
                 renderer={this.renderQueryList}
@@ -92,7 +94,13 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
 
     private renderQueryList = (listProps: IQueryListRendererProps<T>) => {
         const { tagInputProps = {}, popoverProps = {}, selectedItems = [], placeholder } = this.props;
-        const { handleKeyDown, handleKeyUp } = listProps;
+        const { handlePaste, handleKeyDown, handleKeyUp } = listProps;
+
+        const handleTagInputAdd = (values: any[], method: TagInputAddMethod) => {
+            if (method === TagInputAddMethod.PASTE) {
+                handlePaste(values);
+            }
+        };
 
         return (
             <Popover
@@ -117,6 +125,7 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
                         className={classNames(Classes.MULTISELECT, tagInputProps.className)}
                         inputRef={this.refHandlers.input}
                         inputValue={listProps.query}
+                        onAdd={handleTagInputAdd}
                         onInputChange={listProps.handleQueryChange}
                         values={selectedItems.map(this.props.tagRenderer)}
                     />
@@ -135,6 +144,10 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
         Utils.safeInvoke(this.props.onItemSelect, item, evt);
     };
 
+    private handleItemsPaste = (items: T[]) => {
+        Utils.safeInvoke(this.props.onItemsPaste, items);
+    };
+
     private handleQueryChange = (query: string, evt?: React.ChangeEvent<HTMLInputElement>) => {
         this.setState({ isOpen: query.length > 0 || !this.props.openOnKeyDown });
         Utils.safeInvoke(this.props.onQueryChange, query, evt);