From 6668d078e3f673ab36554e074b0fe5c4be186773 Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyangl@palantir.com>
Date: Mon, 21 Jan 2019 12:40:20 -0500
Subject: [PATCH 01/30] Add option to create new item

---
 .../select-examples/multiSelectExample.tsx    | 29 ++++++++++
 .../src/components/query-list/queryList.tsx   | 10 +++-
 .../src/components/select/multiSelect.tsx     | 53 +++++++++++++++++--
 3 files changed, 87 insertions(+), 5 deletions(-)

diff --git a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
index 54e45770a9..1c8f961786 100644
--- a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
@@ -23,6 +23,7 @@ export interface IMultiSelectExampleState {
     popoverMinimal: boolean;
     resetOnSelect: boolean;
     tagMinimal: boolean;
+    allowCreate: boolean;
 }
 
 export class MultiSelectExample extends React.PureComponent<IExampleProps, IMultiSelectExampleState> {
@@ -34,6 +35,7 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
         popoverMinimal: true,
         resetOnSelect: true,
         tagMinimal: false,
+        allowCreate: false,
     };
 
     private handleKeyDownChange = this.handleSwitchChange("openOnKeyDown");
@@ -42,6 +44,7 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
     private handleTagMinimalChange = this.handleSwitchChange("tagMinimal");
     private handleIntentChange = this.handleSwitchChange("intent");
     private handleInitialContentChange = this.handleSwitchChange("hasInitialContent");
+    private handleAllowCreateChange = this.handleSwitchChange("allowCreate");
 
     public render() {
         const { films, hasInitialContent, tagMinimal, popoverMinimal, ...flags } = this.state;
@@ -50,6 +53,9 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
             minimal: tagMinimal,
         });
 
+        const maybeCreateItemFromQuery = this.state.allowCreate ? this.handleCreateFilmFromQuery : undefined;
+        const maybeCreateItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
+
         const initialContent = this.state.hasInitialContent ? (
             <MenuItem disabled={true} text={`${TOP_100_FILMS.length} items loaded.`} />
         ) : (
@@ -72,6 +78,8 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
                     tagRenderer={this.renderTag}
                     tagInputProps={{ tagProps: getTagProps, onRemove: this.handleTagRemove, rightElement: clearButton }}
                     selectedItems={this.state.films}
+                    createItemFromQuery={maybeCreateItemFromQuery}
+                    createItemRenderer={maybeCreateItemRenderer}
                 />
             </Example>
         );
@@ -96,6 +104,11 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
                     checked={this.state.hasInitialContent}
                     onChange={this.handleInitialContentChange}
                 />
+                <Switch
+                    label="Allow creating new items"
+                    checked={this.state.allowCreate}
+                    onChange={this.handleAllowCreateChange}
+                />
                 <H5>Tag props</H5>
                 <Switch
                     label="Minimal tag style"
@@ -137,6 +150,14 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
         );
     };
 
+    private renderCreateFilmOption = (query: string) => (
+        <MenuItem
+            icon={"add"}
+            text={`Create "${query}"`}
+            shouldDismissPopover={false}
+        />
+    );
+
     private handleTagRemove = (_tag: string, index: number) => {
         this.deselectFilm(index);
     };
@@ -173,4 +194,12 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
     }
 
     private handleClear = () => this.setState({ films: [] });
+
+    private handleCreateFilmFromQuery(query: string): IFilm {
+        return {
+            title: query,
+            year: new Date().getFullYear(),
+            rank: 100 + Math.floor(Math.random() * 100 + 1),
+        };
+    }
 }
diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index c76432f2f4..d274ae5940 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -29,6 +29,11 @@ export interface IQueryListProps<T> extends IListItemsProps<T> {
      * Receives an object with props that should be applied to elements as necessary.
      */
     renderer: (listProps: IQueryListRendererProps<T>) => JSX.Element;
+
+    /**
+     * Any additional view rendered at the end of the query list.
+     */
+    additionalElementRenderer?: (query: string) => JSX.Element;
 }
 
 /**
@@ -216,9 +221,10 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
 
     /** default `itemListRenderer` implementation */
     private renderItemList = (listProps: IItemListRendererProps<T>) => {
-        const { initialContent, noResults } = this.props;
+        const { initialContent, noResults, additionalElementRenderer } = this.props;
         const menuContent = renderFilteredItems(listProps, noResults, initialContent);
-        return <Menu ulRef={listProps.itemsParentRef}>{menuContent}</Menu>;
+        const additionalElement = Utils.safeInvoke(additionalElementRenderer, this.state.query);
+        return <Menu ulRef={listProps.itemsParentRef}>{menuContent}{additionalElement}</Menu>;
     };
 
     /** wrapper around `itemRenderer` to inject props */
diff --git a/packages/select/src/components/select/multiSelect.tsx b/packages/select/src/components/select/multiSelect.tsx
index d9e3a0195a..a333aa0cbf 100644
--- a/packages/select/src/components/select/multiSelect.tsx
+++ b/packages/select/src/components/select/multiSelect.tsx
@@ -43,6 +43,20 @@ export interface IMultiSelectProps<T> extends IListItemsProps<T> {
 
     /** Custom renderer to transform an item into tag content. */
     tagRenderer: (item: T) => React.ReactNode;
+
+    /**
+     * If provided, allows new items to be created with the current query string in `MultiSelect`.
+     * This is invoked when user interaction causes a new item to be created, either by pressing the `enter` key or
+     * by clicking on the "Create Item" option. It transforms a query string into an item type.
+     */
+    createItemFromQuery?: (query: string) => T;
+
+    /**
+     * Custom renderer to transform the current query string into a selectable "Create Item" option.
+     * If `noResults` is also defined, this props takes priority and the other will be ignored.
+     * Ignored if `createItemFromQuery` is omitted.
+     */
+    createItemRenderer?: (query: string) => JSX.Element;
 }
 
 export interface IMultiSelectState {
@@ -78,21 +92,42 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
 
     public render() {
         // omit props specific to this component, spread the rest.
-        const { openOnKeyDown, popoverProps, tagInputProps, ...restProps } = this.props;
-
+        // omit noResults if createItemFromQuery and createItemRenderer are both supplied
+        const {
+            createItemFromQuery,
+            createItemRenderer,
+            noResults,
+            openOnKeyDown,
+            popoverProps,
+            tagInputProps,
+            ...restProps
+        } = this.props;
+        const creatable = createItemFromQuery != null;
+        const maybeNoResults = (creatable && createItemRenderer) ? undefined : noResults;
         return (
             <this.TypedQueryList
                 {...restProps}
+                noResults={maybeNoResults}
                 onItemSelect={this.handleItemSelect}
                 onQueryChange={this.handleQueryChange}
                 ref={this.refHandlers.queryList}
                 renderer={this.renderQueryList}
+                additionalElementRenderer={creatable ? createItemRenderer : undefined}
             />
         );
     }
 
     private renderQueryList = (listProps: IQueryListRendererProps<T>) => {
-        const { tagInputProps = {}, popoverProps = {}, selectedItems = [], placeholder } = this.props;
+        const {
+            popoverProps = {},
+            selectedItems = [],
+            placeholder,
+            createItemFromQuery,
+        } = this.props;
+        const tagInputProps: Partial<ITagInputProps> & object = {
+            onAdd: createItemFromQuery != null ? this.handleItemCreate : undefined,
+            ...this.props.tagInputProps,
+        };
         const { handleKeyDown, handleKeyUp } = listProps;
 
         return (
@@ -136,6 +171,18 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
         Utils.safeInvoke(this.props.onItemSelect, item, evt);
     };
 
+    private handleItemCreate = (queries: string[]) => {
+        const { createItemFromQuery } = this.props;
+        if (createItemFromQuery == null) {
+            return;
+        }
+
+        queries.forEach(query => {
+            const item = createItemFromQuery(query);
+            Utils.safeInvoke(this.props.onItemSelect, item, undefined);
+        });
+    }
+
     private handleQueryChange = (query: string, evt?: React.ChangeEvent<HTMLInputElement>) => {
         this.setState({ isOpen: query.length > 0 || !this.props.openOnKeyDown });
         Utils.safeInvoke(this.props.onQueryChange, query, evt);

From 3fcd3435ba6f99b6b8f6bb9380bd77183c803b13 Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyangl@palantir.com>
Date: Mon, 21 Jan 2019 13:10:09 -0500
Subject: [PATCH 02/30] Properly clear input on item click

---
 .../select-examples/multiSelectExample.tsx     |  3 ++-
 .../src/components/query-list/queryList.tsx    |  2 +-
 .../src/components/select/multiSelect.tsx      | 18 ++++++++++++++----
 3 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
index 1c8f961786..54e6ec75b6 100644
--- a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
@@ -150,10 +150,11 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
         );
     };
 
-    private renderCreateFilmOption = (query: string) => (
+    private renderCreateFilmOption = (query: string, handleClick: React.MouseEventHandler<HTMLElement>) => (
         <MenuItem
             icon={"add"}
             text={`Create "${query}"`}
+            onClick={handleClick}
             shouldDismissPopover={false}
         />
     );
diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index d274ae5940..ef2a9dec8c 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -33,7 +33,7 @@ export interface IQueryListProps<T> extends IListItemsProps<T> {
     /**
      * Any additional view rendered at the end of the query list.
      */
-    additionalElementRenderer?: (query: string) => JSX.Element;
+    additionalElementRenderer?: (query: string) => JSX.Element | undefined;
 }
 
 /**
diff --git a/packages/select/src/components/select/multiSelect.tsx b/packages/select/src/components/select/multiSelect.tsx
index a333aa0cbf..579d597c5c 100644
--- a/packages/select/src/components/select/multiSelect.tsx
+++ b/packages/select/src/components/select/multiSelect.tsx
@@ -56,7 +56,7 @@ export interface IMultiSelectProps<T> extends IListItemsProps<T> {
      * If `noResults` is also defined, this props takes priority and the other will be ignored.
      * Ignored if `createItemFromQuery` is omitted.
      */
-    createItemRenderer?: (query: string) => JSX.Element;
+    createItemRenderer?: (query: string, handleClick: React.MouseEventHandler<HTMLElement>) => JSX.Element;
 }
 
 export interface IMultiSelectState {
@@ -112,7 +112,7 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
                 onQueryChange={this.handleQueryChange}
                 ref={this.refHandlers.queryList}
                 renderer={this.renderQueryList}
-                additionalElementRenderer={creatable ? createItemRenderer : undefined}
+                additionalElementRenderer={creatable ? this.renderCreateItemMenuItem : undefined}
             />
         );
     }
@@ -164,6 +164,13 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
         );
     };
 
+    private renderCreateItemMenuItem = (query: string) => {
+        const handleClick: React.MouseEventHandler<HTMLElement> = (evt) => {
+            this.handleItemCreate([query], evt);
+        }
+        return Utils.safeInvoke(this.props.createItemRenderer, query, handleClick);
+    }
+
     private handleItemSelect = (item: T, evt?: React.SyntheticEvent<HTMLElement>) => {
         if (this.input != null) {
             this.input.focus();
@@ -171,7 +178,7 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
         Utils.safeInvoke(this.props.onItemSelect, item, evt);
     };
 
-    private handleItemCreate = (queries: string[]) => {
+    private handleItemCreate = (queries: string[], evt?: React.SyntheticEvent<HTMLElement>) => {
         const { createItemFromQuery } = this.props;
         if (createItemFromQuery == null) {
             return;
@@ -179,8 +186,9 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
 
         queries.forEach(query => {
             const item = createItemFromQuery(query);
-            Utils.safeInvoke(this.props.onItemSelect, item, undefined);
+            Utils.safeInvoke(this.props.onItemSelect, item, evt);
         });
+        this.resetQuery();
     }
 
     private handleQueryChange = (query: string, evt?: React.ChangeEvent<HTMLInputElement>) => {
@@ -232,4 +240,6 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
             }
         };
     };
+
+    private resetQuery = () => this.queryList && this.queryList.setQuery("", true);
 }

From b42418f6b6a65e778f65e728c7ac6364abfa1abf Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyangl@palantir.com>
Date: Mon, 21 Jan 2019 14:17:35 -0500
Subject: [PATCH 03/30] Move props to queryList

---
 packages/select/src/common/listItemsProps.ts  | 12 ++++
 .../src/components/query-list/queryList.tsx   | 39 ++++++++----
 .../src/components/select/multiSelect.tsx     | 62 +------------------
 3 files changed, 42 insertions(+), 71 deletions(-)

diff --git a/packages/select/src/common/listItemsProps.ts b/packages/select/src/common/listItemsProps.ts
index 43cf53b951..c81d9d604b 100644
--- a/packages/select/src/common/listItemsProps.ts
+++ b/packages/select/src/common/listItemsProps.ts
@@ -98,6 +98,18 @@ export interface IListItemsProps<T> extends IProps {
      */
     onQueryChange?: (query: string, event?: React.ChangeEvent<HTMLInputElement>) => void;
 
+    /**
+     * If provided, allows new items to be created with the current query string.
+     * This is invoked when user interaction causes a new item to be created, either by pressing the `enter` key or
+     * by clicking on the "Create Item" option. It transforms a query string into an item type.
+     */
+    createItemFromQuery?: (query: string) => T;
+
+    /**
+     * Custom renderer to transform the current query string into a selectable "Create Item" option.
+     */
+    createItemRenderer?: (query: string, handleClick: React.MouseEventHandler<HTMLElement>) => JSX.Element | undefined;
+
     /**
      * Whether the active item should be reset to the first matching item _every
      * time the query changes_ (via prop or by user input).
diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index ef2a9dec8c..c43702d304 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -29,11 +29,6 @@ export interface IQueryListProps<T> extends IListItemsProps<T> {
      * Receives an object with props that should be applied to elements as necessary.
      */
     renderer: (listProps: IQueryListRendererProps<T>) => JSX.Element;
-
-    /**
-     * Any additional view rendered at the end of the query list.
-     */
-    additionalElementRenderer?: (query: string) => JSX.Element | undefined;
 }
 
 /**
@@ -221,10 +216,13 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
 
     /** default `itemListRenderer` implementation */
     private renderItemList = (listProps: IItemListRendererProps<T>) => {
-        const { initialContent, noResults, additionalElementRenderer } = this.props;
-        const menuContent = renderFilteredItems(listProps, noResults, initialContent);
-        const additionalElement = Utils.safeInvoke(additionalElementRenderer, this.state.query);
-        return <Menu ulRef={listProps.itemsParentRef}>{menuContent}{additionalElement}</Menu>;
+        const { initialContent, noResults, createItemFromQuery, createItemRenderer } = this.props;
+
+        // omit noResults if createItemFromQuery and createItemRenderer are both supplied
+        const maybeNoResults = (createItemFromQuery && createItemRenderer) ? undefined : noResults;
+        const menuContent = renderFilteredItems(listProps, maybeNoResults, initialContent);
+        const createItemView = this.renderCreateItemMenuItem(this.state.query);
+        return <Menu ulRef={listProps.itemsParentRef}>{menuContent}{createItemView}</Menu>;
     };
 
     /** wrapper around `itemRenderer` to inject props */
@@ -244,6 +242,13 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         });
     };
 
+    private renderCreateItemMenuItem = (query: string) => {
+        const handleClick: React.MouseEventHandler<HTMLElement> = (evt) => {
+            this.handleItemCreate(query, evt);
+        }
+        return Utils.safeInvoke(this.props.createItemRenderer, query, handleClick);
+    }
+
     private getActiveElement() {
         if (this.itemsParentRef != null) {
             return this.itemsParentRef.children.item(this.getActiveIndex()) as HTMLElement;
@@ -266,6 +271,14 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         };
     }
 
+    private handleItemCreate = (query: string, evt?: React.SyntheticEvent<HTMLElement>) => {
+        const item = Utils.safeInvoke(this.props.createItemFromQuery, query);
+        if (item != null) {
+            Utils.safeInvoke(this.props.onItemSelect, item, evt);
+            this.setQuery("", true);
+        }
+    }
+
     private handleItemSelect = (item: T, event?: React.SyntheticEvent<HTMLElement>) => {
         this.setActiveItem(item);
         Utils.safeInvoke(this.props.onItemSelect, item, event);
@@ -292,9 +305,13 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         // using keyup for enter to play nice with Button's keyboard clicking.
         // if we were to process enter on keydown, then Button would click itself on keyup
         // and the popvoer would re-open out of our control :(.
-        if (event.keyCode === Keys.ENTER && activeItem != null) {
+        if (event.keyCode === Keys.ENTER) {
             event.preventDefault();
-            this.handleItemSelect(activeItem, event);
+            if (activeItem == null) {
+                this.handleItemCreate(this.state.query, event);
+            } else {
+                this.handleItemSelect(activeItem, event);
+            }
         }
         Utils.safeInvoke(onKeyUp, event);
     };
diff --git a/packages/select/src/components/select/multiSelect.tsx b/packages/select/src/components/select/multiSelect.tsx
index 579d597c5c..11e9271402 100644
--- a/packages/select/src/components/select/multiSelect.tsx
+++ b/packages/select/src/components/select/multiSelect.tsx
@@ -43,20 +43,6 @@ export interface IMultiSelectProps<T> extends IListItemsProps<T> {
 
     /** Custom renderer to transform an item into tag content. */
     tagRenderer: (item: T) => React.ReactNode;
-
-    /**
-     * If provided, allows new items to be created with the current query string in `MultiSelect`.
-     * This is invoked when user interaction causes a new item to be created, either by pressing the `enter` key or
-     * by clicking on the "Create Item" option. It transforms a query string into an item type.
-     */
-    createItemFromQuery?: (query: string) => T;
-
-    /**
-     * Custom renderer to transform the current query string into a selectable "Create Item" option.
-     * If `noResults` is also defined, this props takes priority and the other will be ignored.
-     * Ignored if `createItemFromQuery` is omitted.
-     */
-    createItemRenderer?: (query: string, handleClick: React.MouseEventHandler<HTMLElement>) => JSX.Element;
 }
 
 export interface IMultiSelectState {
@@ -92,42 +78,20 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
 
     public render() {
         // omit props specific to this component, spread the rest.
-        // omit noResults if createItemFromQuery and createItemRenderer are both supplied
-        const {
-            createItemFromQuery,
-            createItemRenderer,
-            noResults,
-            openOnKeyDown,
-            popoverProps,
-            tagInputProps,
-            ...restProps
-        } = this.props;
-        const creatable = createItemFromQuery != null;
-        const maybeNoResults = (creatable && createItemRenderer) ? undefined : noResults;
+        const { openOnKeyDown, popoverProps, tagInputProps, ...restProps } = this.props;
         return (
             <this.TypedQueryList
                 {...restProps}
-                noResults={maybeNoResults}
                 onItemSelect={this.handleItemSelect}
                 onQueryChange={this.handleQueryChange}
                 ref={this.refHandlers.queryList}
                 renderer={this.renderQueryList}
-                additionalElementRenderer={creatable ? this.renderCreateItemMenuItem : undefined}
             />
         );
     }
 
     private renderQueryList = (listProps: IQueryListRendererProps<T>) => {
-        const {
-            popoverProps = {},
-            selectedItems = [],
-            placeholder,
-            createItemFromQuery,
-        } = this.props;
-        const tagInputProps: Partial<ITagInputProps> & object = {
-            onAdd: createItemFromQuery != null ? this.handleItemCreate : undefined,
-            ...this.props.tagInputProps,
-        };
+        const { tagInputProps = {}, popoverProps = {}, selectedItems = [], placeholder } = this.props;
         const { handleKeyDown, handleKeyUp } = listProps;
 
         return (
@@ -164,13 +128,6 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
         );
     };
 
-    private renderCreateItemMenuItem = (query: string) => {
-        const handleClick: React.MouseEventHandler<HTMLElement> = (evt) => {
-            this.handleItemCreate([query], evt);
-        }
-        return Utils.safeInvoke(this.props.createItemRenderer, query, handleClick);
-    }
-
     private handleItemSelect = (item: T, evt?: React.SyntheticEvent<HTMLElement>) => {
         if (this.input != null) {
             this.input.focus();
@@ -178,19 +135,6 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
         Utils.safeInvoke(this.props.onItemSelect, item, evt);
     };
 
-    private handleItemCreate = (queries: string[], evt?: React.SyntheticEvent<HTMLElement>) => {
-        const { createItemFromQuery } = this.props;
-        if (createItemFromQuery == null) {
-            return;
-        }
-
-        queries.forEach(query => {
-            const item = createItemFromQuery(query);
-            Utils.safeInvoke(this.props.onItemSelect, item, evt);
-        });
-        this.resetQuery();
-    }
-
     private handleQueryChange = (query: string, evt?: React.ChangeEvent<HTMLInputElement>) => {
         this.setState({ isOpen: query.length > 0 || !this.props.openOnKeyDown });
         Utils.safeInvoke(this.props.onQueryChange, query, evt);
@@ -240,6 +184,4 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
             }
         };
     };
-
-    private resetQuery = () => this.queryList && this.queryList.setQuery("", true);
 }

From 2548a01f0636765497003a3942c1177ea961d1cf Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyangl@palantir.com>
Date: Mon, 21 Jan 2019 15:20:14 -0500
Subject: [PATCH 04/30] Lint and test

---
 .../src/examples/select-examples/films.tsx    |  8 +++++
 .../select-examples/multiSelectExample.tsx    | 19 ++----------
 .../src/components/query-list/queryList.tsx   | 22 +++++++++-----
 packages/select/test/selectComponentSuite.tsx | 30 +++++++++++++++++++
 4 files changed, 55 insertions(+), 24 deletions(-)

diff --git a/packages/docs-app/src/examples/select-examples/films.tsx b/packages/docs-app/src/examples/select-examples/films.tsx
index a92fd3dafc..71f77c0055 100644
--- a/packages/docs-app/src/examples/select-examples/films.tsx
+++ b/packages/docs-app/src/examples/select-examples/films.tsx
@@ -182,3 +182,11 @@ export const filmSelectProps = {
     itemRenderer: renderFilm,
     items: TOP_100_FILMS,
 };
+
+export function createFilm(title: string): IFilm {
+    return {
+        title,
+        year: new Date().getFullYear(),
+        rank: 100 + Math.floor(Math.random() * 100 + 1),
+    };
+}
diff --git a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
index 54e6ec75b6..266d5ec3d8 100644
--- a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
@@ -9,7 +9,7 @@ import * as React from "react";
 import { Button, H5, Intent, ITagProps, MenuItem, Switch } from "@blueprintjs/core";
 import { Example, IExampleProps } from "@blueprintjs/docs-theme";
 import { ItemRenderer, MultiSelect } from "@blueprintjs/select";
-import { filmSelectProps, IFilm, TOP_100_FILMS } from "./films";
+import { createFilm, filmSelectProps, IFilm, TOP_100_FILMS } from "./films";
 
 const FilmMultiSelect = MultiSelect.ofType<IFilm>();
 
@@ -53,7 +53,7 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
             minimal: tagMinimal,
         });
 
-        const maybeCreateItemFromQuery = this.state.allowCreate ? this.handleCreateFilmFromQuery : undefined;
+        const maybeCreateItemFromQuery = this.state.allowCreate ? createFilm : undefined;
         const maybeCreateItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
 
         const initialContent = this.state.hasInitialContent ? (
@@ -151,12 +151,7 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
     };
 
     private renderCreateFilmOption = (query: string, handleClick: React.MouseEventHandler<HTMLElement>) => (
-        <MenuItem
-            icon={"add"}
-            text={`Create "${query}"`}
-            onClick={handleClick}
-            shouldDismissPopover={false}
-        />
+        <MenuItem icon="add" text={`Create "${query}"`} onClick={handleClick} shouldDismissPopover={false} />
     );
 
     private handleTagRemove = (_tag: string, index: number) => {
@@ -195,12 +190,4 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
     }
 
     private handleClear = () => this.setState({ films: [] });
-
-    private handleCreateFilmFromQuery(query: string): IFilm {
-        return {
-            title: query,
-            year: new Date().getFullYear(),
-            rank: 100 + Math.floor(Math.random() * 100 + 1),
-        };
-    }
 }
diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index c43702d304..45e2b31e6b 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -218,11 +218,17 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     private renderItemList = (listProps: IItemListRendererProps<T>) => {
         const { initialContent, noResults, createItemFromQuery, createItemRenderer } = this.props;
 
-        // omit noResults if createItemFromQuery and createItemRenderer are both supplied
-        const maybeNoResults = (createItemFromQuery && createItemRenderer) ? undefined : noResults;
+        // omit noResults if createItemFromQuery and createItemRenderer are both supplied, and query is not empty
+        const maybeNoResults =
+            createItemFromQuery && createItemRenderer && this.state.query !== "" ? undefined : noResults;
         const menuContent = renderFilteredItems(listProps, maybeNoResults, initialContent);
-        const createItemView = this.renderCreateItemMenuItem(this.state.query);
-        return <Menu ulRef={listProps.itemsParentRef}>{menuContent}{createItemView}</Menu>;
+        const createItemView = this.state.query !== "" ? this.renderCreateItemMenuItem(this.state.query) : null;
+        return (
+            <Menu ulRef={listProps.itemsParentRef}>
+                {menuContent}
+                {createItemView}
+            </Menu>
+        );
     };
 
     /** wrapper around `itemRenderer` to inject props */
@@ -243,11 +249,11 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     };
 
     private renderCreateItemMenuItem = (query: string) => {
-        const handleClick: React.MouseEventHandler<HTMLElement> = (evt) => {
+        const handleClick: React.MouseEventHandler<HTMLElement> = evt => {
             this.handleItemCreate(query, evt);
-        }
+        };
         return Utils.safeInvoke(this.props.createItemRenderer, query, handleClick);
-    }
+    };
 
     private getActiveElement() {
         if (this.itemsParentRef != null) {
@@ -277,7 +283,7 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
             Utils.safeInvoke(this.props.onItemSelect, item, evt);
             this.setQuery("", true);
         }
-    }
+    };
 
     private handleItemSelect = (item: T, event?: React.SyntheticEvent<HTMLElement>) => {
         this.setActiveItem(item);
diff --git a/packages/select/test/selectComponentSuite.tsx b/packages/select/test/selectComponentSuite.tsx
index ec6fc82abc..0e453e6e26 100644
--- a/packages/select/test/selectComponentSuite.tsx
+++ b/packages/select/test/selectComponentSuite.tsx
@@ -119,4 +119,34 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             assert.equal(testProps.onItemSelect.lastCall.args[0], activeItem);
         });
     });
+
+    describe("create", () => {
+        const testCreateProps = {
+            ...testProps,
+            createItemFromQuery: sinon.spy(),
+            createItemRenderer: () => <textarea />,
+        };
+
+        it("renders create item if filtering returns empty list", () => {
+            const wrapper = render({
+                ...testCreateProps,
+                items: [],
+                noResults: <address />,
+                query: "non-existent film name",
+            });
+            assert.lengthOf(wrapper.find("address"), 0, "should not find noResults");
+            assert.lengthOf(wrapper.find(`textarea`), 1, "should find createItem");
+        });
+
+        it("enter invokes createItemFromQuery", () => {
+            const wrapper = render({
+                ...testCreateProps,
+                items: [],
+                noResults: <address />,
+                query: "non-existent film name",
+            });
+            findInput(wrapper).simulate("keyup", { keyCode: Keys.ENTER });
+            assert.equal(testCreateProps.createItemFromQuery.args[0][0], "non-existent film name");
+        });
+    });
 }

From bccb5e2ff63d679f41ba330e45f9e2b8c379a0b3 Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyangl@palantir.com>
Date: Mon, 21 Jan 2019 15:42:37 -0500
Subject: [PATCH 05/30] Lint and docs

---
 .../src/examples/select-examples/films.tsx     |  2 +-
 .../select-examples/multiSelectExample.tsx     | 11 +++++------
 .../examples/select-examples/selectExample.tsx | 18 +++++++++++++++++-
 .../src/components/select/multi-select.md      |  2 +-
 .../src/components/select/multiSelect.tsx      |  1 +
 .../src/components/select/select-component.md  |  6 ++++++
 6 files changed, 31 insertions(+), 9 deletions(-)

diff --git a/packages/docs-app/src/examples/select-examples/films.tsx b/packages/docs-app/src/examples/select-examples/films.tsx
index 71f77c0055..8d61095cbe 100644
--- a/packages/docs-app/src/examples/select-examples/films.tsx
+++ b/packages/docs-app/src/examples/select-examples/films.tsx
@@ -185,8 +185,8 @@ export const filmSelectProps = {
 
 export function createFilm(title: string): IFilm {
     return {
+        rank: 100 + Math.floor(Math.random() * 100 + 1),
         title,
         year: new Date().getFullYear(),
-        rank: 100 + Math.floor(Math.random() * 100 + 1),
     };
 }
diff --git a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
index 266d5ec3d8..fce9e009b3 100644
--- a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
@@ -19,15 +19,16 @@ export interface IMultiSelectExampleState {
     films: IFilm[];
     hasInitialContent: boolean;
     intent: boolean;
+    allowCreate: boolean;
     openOnKeyDown: boolean;
     popoverMinimal: boolean;
     resetOnSelect: boolean;
     tagMinimal: boolean;
-    allowCreate: boolean;
 }
 
 export class MultiSelectExample extends React.PureComponent<IExampleProps, IMultiSelectExampleState> {
     public state: IMultiSelectExampleState = {
+        allowCreate: false,
         films: [],
         hasInitialContent: false,
         intent: false,
@@ -35,7 +36,6 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
         popoverMinimal: true,
         resetOnSelect: true,
         tagMinimal: false,
-        allowCreate: false,
     };
 
     private handleKeyDownChange = this.handleSwitchChange("openOnKeyDown");
@@ -53,15 +53,14 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
             minimal: tagMinimal,
         });
 
-        const maybeCreateItemFromQuery = this.state.allowCreate ? createFilm : undefined;
-        const maybeCreateItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
-
         const initialContent = this.state.hasInitialContent ? (
             <MenuItem disabled={true} text={`${TOP_100_FILMS.length} items loaded.`} />
         ) : (
             // explicit undefined (not null) for default behavior (show full list)
             undefined
         );
+        const maybeCreateItemFromQuery = this.state.allowCreate ? createFilm : undefined;
+        const maybeCreateItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
 
         const clearButton = films.length > 0 ? <Button icon="cross" minimal={true} onClick={this.handleClear} /> : null;
 
@@ -105,7 +104,7 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
                     onChange={this.handleInitialContentChange}
                 />
                 <Switch
-                    label="Allow creating new items"
+                    label="Allow creating new films"
                     checked={this.state.allowCreate}
                     onChange={this.handleAllowCreateChange}
                 />
diff --git a/packages/docs-app/src/examples/select-examples/selectExample.tsx b/packages/docs-app/src/examples/select-examples/selectExample.tsx
index 352723b0f4..9a81a1651d 100644
--- a/packages/docs-app/src/examples/select-examples/selectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/selectExample.tsx
@@ -9,11 +9,12 @@ import * as React from "react";
 import { Button, H5, MenuItem, Switch } from "@blueprintjs/core";
 import { Example, IExampleProps } from "@blueprintjs/docs-theme";
 import { Select } from "@blueprintjs/select";
-import { filmSelectProps, IFilm, TOP_100_FILMS } from "./films";
+import { createFilm, filmSelectProps, IFilm, TOP_100_FILMS } from "./films";
 
 const FilmSelect = Select.ofType<IFilm>();
 
 export interface ISelectExampleState {
+    allowCreate: boolean;
     film: IFilm;
     filterable: boolean;
     hasInitialContent: boolean;
@@ -27,6 +28,7 @@ export interface ISelectExampleState {
 
 export class SelectExample extends React.PureComponent<IExampleProps, ISelectExampleState> {
     public state: ISelectExampleState = {
+        allowCreate: false,
         disableItems: false,
         disabled: false,
         film: TOP_100_FILMS[0],
@@ -38,6 +40,7 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
         resetOnSelect: false,
     };
 
+    private handleAllowCreateChange = this.handleSwitchChange("allowCreate");
     private handleDisabledChange = this.handleSwitchChange("disabled");
     private handleFilterableChange = this.handleSwitchChange("filterable");
     private handleInitialContentChange = this.handleSwitchChange("hasInitialContent");
@@ -55,12 +58,16 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
         ) : (
             undefined
         );
+        const maybeCreateItemFromQuery = this.state.allowCreate ? createFilm : undefined;
+        const maybeCreateItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
 
         return (
             <Example options={this.renderOptions()} {...this.props}>
                 <FilmSelect
                     {...filmSelectProps}
                     {...flags}
+                    createItemFromQuery={maybeCreateItemFromQuery}
+                    createItemRenderer={maybeCreateItemRenderer}
                     disabled={disabled}
                     itemDisabled={this.isItemDisabled}
                     initialContent={initialContent}
@@ -110,6 +117,11 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
                     checked={this.state.disableItems}
                     onChange={this.handleItemDisabledChange}
                 />
+                <Switch
+                    label="Allow creating new items"
+                    checked={this.state.allowCreate}
+                    onChange={this.handleAllowCreateChange}
+                />
                 <H5>Popover props</H5>
                 <Switch
                     label="Minimal popover style"
@@ -120,6 +132,10 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
         );
     }
 
+    private renderCreateFilmOption = (query: string, handleClick: React.MouseEventHandler<HTMLElement>) => (
+        <MenuItem icon="add" text={`Create "${query}"`} onClick={handleClick} shouldDismissPopover={false} />
+    );
+
     private handleValueChange = (film: IFilm) => this.setState({ film });
 
     private handleSwitchChange(prop: keyof ISelectExampleState) {
diff --git a/packages/select/src/components/select/multi-select.md b/packages/select/src/components/select/multi-select.md
index 9ad17ee706..68405835a0 100644
--- a/packages/select/src/components/select/multi-select.md
+++ b/packages/select/src/components/select/multi-select.md
@@ -4,7 +4,7 @@ Use `MultiSelect<T>` for choosing multiple items in a list. The component render
 
 <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
     <h4 class="@ns-heading">Generic components and custom filtering</h4>
-    For more information on controlled usage, generic components and custom filtering, visit the documentation for [`Select<T>`](#select/select-component).
+    For more information on controlled usage, generic components, creating new items, and custom filtering, visit the documentation for [`Select<T>`](#select/select-component).
 </div>
 
 @reactExample MultiSelectExample
diff --git a/packages/select/src/components/select/multiSelect.tsx b/packages/select/src/components/select/multiSelect.tsx
index 11e9271402..d9e3a0195a 100644
--- a/packages/select/src/components/select/multiSelect.tsx
+++ b/packages/select/src/components/select/multiSelect.tsx
@@ -79,6 +79,7 @@ export class MultiSelect<T> extends React.PureComponent<IMultiSelectProps<T>, IM
     public render() {
         // omit props specific to this component, spread the rest.
         const { openOnKeyDown, popoverProps, tagInputProps, ...restProps } = this.props;
+
         return (
             <this.TypedQueryList
                 {...restProps}
diff --git a/packages/select/src/components/select/select-component.md b/packages/select/src/components/select/select-component.md
index d6a05f364b..4d9fb166c5 100644
--- a/packages/select/src/components/select/select-component.md
+++ b/packages/select/src/components/select/select-component.md
@@ -82,6 +82,12 @@ This controlled usage allows you to implement all sorts of advanced behavior on
 top of the basic `Select` interactions, such as windowed filtering for large
 data sets.
 
+@## Creating new items
+
+Use the `createItemFromQuery` prop to allow `Select<T>` to create new items. `createItemFromQuery` specifies how to turn a
+user-entered query string into an item of type `<T>` that `Select` understands. You should also provide the `createItemRenderer`
+prop to render a custom `MenuItem` to indicate that users can create new items.
+
 @## JavaScript API
 
 @interface ISelectProps

From 684919c308f5569e0fdb66bcd9d65a2f7aae752f Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyang.li.95@gmail.com>
Date: Wed, 6 Feb 2019 20:11:06 +0800
Subject: [PATCH 06/30] Properly handle keyboard events with create item

---
 .../select-examples/multiSelectExample.tsx    |  14 ++-
 .../select-examples/selectExample.tsx         |  14 ++-
 .../select/src/common/itemListRenderer.ts     |  12 +-
 packages/select/src/common/listItemsProps.ts  |  12 +-
 .../src/components/query-list/queryList.tsx   | 103 +++++++++++++-----
 5 files changed, 121 insertions(+), 34 deletions(-)

diff --git a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
index fce9e009b3..c830b56e91 100644
--- a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
@@ -149,8 +149,18 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
         );
     };
 
-    private renderCreateFilmOption = (query: string, handleClick: React.MouseEventHandler<HTMLElement>) => (
-        <MenuItem icon="add" text={`Create "${query}"`} onClick={handleClick} shouldDismissPopover={false} />
+    private renderCreateFilmOption = (
+        query: string,
+        active: boolean,
+        handleClick: React.MouseEventHandler<HTMLElement>,
+    ) => (
+        <MenuItem
+            icon="add"
+            text={`Create "${query}"`}
+            active={active}
+            onClick={handleClick}
+            shouldDismissPopover={false}
+        />
     );
 
     private handleTagRemove = (_tag: string, index: number) => {
diff --git a/packages/docs-app/src/examples/select-examples/selectExample.tsx b/packages/docs-app/src/examples/select-examples/selectExample.tsx
index 9a81a1651d..2339879d6a 100644
--- a/packages/docs-app/src/examples/select-examples/selectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/selectExample.tsx
@@ -132,8 +132,18 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
         );
     }
 
-    private renderCreateFilmOption = (query: string, handleClick: React.MouseEventHandler<HTMLElement>) => (
-        <MenuItem icon="add" text={`Create "${query}"`} onClick={handleClick} shouldDismissPopover={false} />
+    private renderCreateFilmOption = (
+        query: string,
+        active: boolean,
+        handleClick: React.MouseEventHandler<HTMLElement>,
+    ) => (
+        <MenuItem
+            icon="add"
+            text={`Create "${query}"`}
+            active={active}
+            onClick={handleClick}
+            shouldDismissPopover={false}
+        />
     );
 
     private handleValueChange = (film: IFilm) => this.setState({ film });
diff --git a/packages/select/src/common/itemListRenderer.ts b/packages/select/src/common/itemListRenderer.ts
index 38a40b4650..21ef1921ee 100644
--- a/packages/select/src/common/itemListRenderer.ts
+++ b/packages/select/src/common/itemListRenderer.ts
@@ -4,13 +4,23 @@
  * Licensed under the terms of the LICENSE file distributed with this project.
  */
 
+export enum QueryListActiveItemType {
+    CREATE = "create",
+    ITEM = "item",
+}
+
+export interface IQueryListActiveItem<T> {
+    type: QueryListActiveItemType;
+    item: T | null;
+}
+
 /**
  * An object describing how to render the list of items.
  * An `itemListRenderer` receives this object as its sole argument.
  */
 export interface IItemListRendererProps<T> {
     /** The currently focused item (for keyboard interactions). */
-    activeItem: T | null;
+    activeItem: IQueryListActiveItem<T> | null;
 
     /**
      * Array of items filtered by `itemListPredicate` or `itemPredicate`.
diff --git a/packages/select/src/common/listItemsProps.ts b/packages/select/src/common/listItemsProps.ts
index c81d9d604b..2f4acbe8d3 100644
--- a/packages/select/src/common/listItemsProps.ts
+++ b/packages/select/src/common/listItemsProps.ts
@@ -5,7 +5,7 @@
 */
 
 import { IProps } from "@blueprintjs/core";
-import { ItemListRenderer } from "./itemListRenderer";
+import { IQueryListActiveItem, ItemListRenderer } from "./itemListRenderer";
 import { ItemRenderer } from "./itemRenderer";
 import { ItemListPredicate, ItemPredicate } from "./predicate";
 
@@ -17,7 +17,7 @@ export interface IListItemsProps<T> extends IProps {
      * uncontrolled (managed by the component's state). Use `onActiveItemChange`
      * to listen for updates.
      */
-    activeItem?: T | null;
+    activeItem?: IQueryListActiveItem<T> | null;
 
     /** Array of items in the list. */
     items: T[];
@@ -85,7 +85,7 @@ export interface IListItemsProps<T> extends IProps {
      * in the list, selecting an item makes it active, and changing the query may reset it to
      * the first item in the list if it no longer matches the filter.
      */
-    onActiveItemChange?: (activeItem: T | null) => void;
+    onActiveItemChange?: (activeItem: IQueryListActiveItem<T> | null) => void;
 
     /**
      * Callback invoked when an item from the list is selected,
@@ -108,7 +108,11 @@ export interface IListItemsProps<T> extends IProps {
     /**
      * Custom renderer to transform the current query string into a selectable "Create Item" option.
      */
-    createItemRenderer?: (query: string, handleClick: React.MouseEventHandler<HTMLElement>) => JSX.Element | undefined;
+    createItemRenderer?: (
+        query: string,
+        active: boolean,
+        handleClick: React.MouseEventHandler<HTMLElement>,
+    ) => JSX.Element | undefined;
 
     /**
      * Whether the active item should be reset to the first matching item _every
diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index 45e2b31e6b..8f3cc65c07 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -7,7 +7,14 @@
 import * as React from "react";
 
 import { DISPLAYNAME_PREFIX, IProps, Keys, Menu, Utils } from "@blueprintjs/core";
-import { IItemListRendererProps, IItemModifiers, IListItemsProps, renderFilteredItems } from "../../common";
+import {
+    IItemListRendererProps,
+    IItemModifiers,
+    IListItemsProps,
+    IQueryListActiveItem,
+    QueryListActiveItemType,
+    renderFilteredItems,
+} from "../../common";
 
 export interface IQueryListProps<T> extends IListItemsProps<T> {
     /**
@@ -66,7 +73,7 @@ export interface IQueryListRendererProps<T> extends IQueryListState<T>, IProps {
 
 export interface IQueryListState<T> {
     /** The currently focused item (for keyboard interactions). */
-    activeItem: T | null;
+    activeItem: IQueryListActiveItem<T> | null;
 
     /** The original `items` array filtered by `itemListPredicate` or `itemPredicate`. */
     filteredItems: T[];
@@ -103,13 +110,17 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
      * or key interactions). When scrollToActiveItem = false, used to detect if
      * an unexpected external change to the active item has been made.
      */
-    private expectedNextActiveItem: T | null = null;
+    private expectedNextActiveItem: IQueryListActiveItem<T> | null = null;
 
     public constructor(props: IQueryListProps<T>, context?: any) {
         super(props, context);
         const { query = "" } = this.props;
         const filteredItems = getFilteredItems(query, this.props);
-        this.state = { activeItem: getFirstEnabledItem(filteredItems, this.props.itemDisabled), filteredItems, query };
+        this.state = {
+            activeItem: getFirstEnabledItem(filteredItems, this.props.itemDisabled),
+            filteredItems,
+            query,
+        };
     }
 
     public render() {
@@ -204,10 +215,9 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
 
         // always reset active item if it's now filtered or disabled
         const activeIndex = this.getActiveIndex(filteredItems);
+        const maybeActiveItem = this.state.activeItem ? this.state.activeItem.item : null;
         const shouldUpdateActiveItem =
-            resetActiveItem ||
-            activeIndex < 0 ||
-            isItemDisabled(this.state.activeItem, activeIndex, props.itemDisabled);
+            resetActiveItem || activeIndex < 0 || isItemDisabled(maybeActiveItem, activeIndex, props.itemDisabled);
 
         if (hasQueryChanged && shouldUpdateActiveItem) {
             this.setActiveItem(getFirstEnabledItem(filteredItems, props.itemDisabled));
@@ -216,13 +226,12 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
 
     /** default `itemListRenderer` implementation */
     private renderItemList = (listProps: IItemListRendererProps<T>) => {
-        const { initialContent, noResults, createItemFromQuery, createItemRenderer } = this.props;
+        const { initialContent, noResults } = this.props;
 
         // omit noResults if createItemFromQuery and createItemRenderer are both supplied, and query is not empty
-        const maybeNoResults =
-            createItemFromQuery && createItemRenderer && this.state.query !== "" ? undefined : noResults;
+        const maybeNoResults = this.isCreateItemRendered() ? null : noResults;
         const menuContent = renderFilteredItems(listProps, maybeNoResults, initialContent);
-        const createItemView = this.state.query !== "" ? this.renderCreateItemMenuItem(this.state.query) : null;
+        const createItemView = this.isCreateItemRendered() ? this.renderCreateItemMenuItem(this.state.query) : null;
         return (
             <Menu ulRef={listProps.itemsParentRef}>
                 {menuContent}
@@ -236,7 +245,7 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         const { activeItem, query } = this.state;
         const matchesPredicate = this.state.filteredItems.indexOf(item) >= 0;
         const modifiers: IItemModifiers = {
-            active: activeItem === item,
+            active: activeItem ? activeItem.type === QueryListActiveItemType.ITEM && activeItem.item === item : false,
             disabled: isItemDisabled(item, index, this.props.itemDisabled),
             matchesPredicate,
         };
@@ -252,20 +261,34 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         const handleClick: React.MouseEventHandler<HTMLElement> = evt => {
             this.handleItemCreate(query, evt);
         };
-        return Utils.safeInvoke(this.props.createItemRenderer, query, handleClick);
+        return Utils.safeInvoke(
+            this.props.createItemRenderer,
+            query,
+            this.state.activeItem ? this.state.activeItem.type === QueryListActiveItemType.CREATE : false,
+            handleClick,
+        );
     };
 
     private getActiveElement() {
         if (this.itemsParentRef != null) {
-            return this.itemsParentRef.children.item(this.getActiveIndex()) as HTMLElement;
+            if (this.state.activeItem && this.state.activeItem.type === QueryListActiveItemType.CREATE) {
+                // "Create" is active
+                return this.itemsParentRef.children.item(this.state.filteredItems.length) as HTMLElement;
+            } else {
+                const activeIndex = this.getActiveIndex();
+                return this.itemsParentRef.children.item(activeIndex) as HTMLElement;
+            }
         }
         return undefined;
     }
 
     private getActiveIndex(items = this.state.filteredItems) {
         const { activeItem } = this.state;
+        if (activeItem == null || activeItem.type === QueryListActiveItemType.CREATE || activeItem.item == null) {
+            return -1;
+        }
         // NOTE: this operation is O(n) so it should be avoided in render(). safe for events though.
-        return activeItem == null ? -1 : items.indexOf(activeItem);
+        return items.indexOf(activeItem.item);
     }
 
     private getItemsParentPadding() {
@@ -286,7 +309,10 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     };
 
     private handleItemSelect = (item: T, event?: React.SyntheticEvent<HTMLElement>) => {
-        this.setActiveItem(item);
+        this.setActiveItem({
+            item,
+            type: QueryListActiveItemType.ITEM,
+        });
         Utils.safeInvoke(this.props.onItemSelect, item, event);
         if (this.props.resetOnSelect) {
             this.setQuery("", true);
@@ -313,10 +339,10 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         // and the popvoer would re-open out of our control :(.
         if (event.keyCode === Keys.ENTER) {
             event.preventDefault();
-            if (activeItem == null) {
+            if (activeItem == null || activeItem.type === QueryListActiveItemType.CREATE || activeItem.item == null) {
                 this.handleItemCreate(this.state.query, event);
             } else {
-                this.handleItemSelect(activeItem, event);
+                this.handleItemSelect(activeItem.item, event);
             }
         }
         Utils.safeInvoke(onKeyUp, event);
@@ -333,11 +359,32 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
      * index. An `undefined` return value means no suitable item was found.
      * @param direction amount to move in each iteration, typically +/-1
      */
-    private getNextActiveItem(direction: number, startIndex = this.getActiveIndex()): T | null {
-        return getFirstEnabledItem(this.state.filteredItems, this.props.itemDisabled, direction, startIndex);
+    private getNextActiveItem(direction: number, startIndex = this.getActiveIndex()): IQueryListActiveItem<T> | null {
+        if (this.isCreateItemRendered()) {
+            const reachedCreate =
+                (startIndex === 0 && direction === -1) ||
+                (startIndex === this.state.filteredItems.length - 1 && direction === 1);
+            if (reachedCreate) {
+                return {
+                    item: null,
+                    type: QueryListActiveItemType.CREATE,
+                };
+            }
+        }
+
+        const firstEnabledItem = getFirstEnabledItem(
+            this.state.filteredItems,
+            this.props.itemDisabled,
+            direction,
+            startIndex,
+        );
+        if (firstEnabledItem != null) {
+            return firstEnabledItem;
+        }
+        return null;
     }
 
-    private setActiveItem(activeItem: T | null) {
+    private setActiveItem(activeItem: IQueryListActiveItem<T> | null) {
         this.expectedNextActiveItem = activeItem;
         if (this.props.activeItem === undefined) {
             // indicate that the active item may need to be scrolled into view after update.
@@ -346,6 +393,10 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         }
         Utils.safeInvoke(this.props.onActiveItemChange, activeItem);
     }
+
+    private isCreateItemRendered(): boolean {
+        return (this.props.createItemFromQuery && this.props.createItemRenderer && this.state.query !== "") || false;
+    }
 }
 
 function pxToNumber(value: string | null) {
@@ -394,18 +445,20 @@ export function getFirstEnabledItem<T>(
     itemDisabled?: keyof T | ((item: T, index: number) => boolean),
     direction = 1,
     startIndex = items.length - 1,
-): T | null {
+): IQueryListActiveItem<T> | null {
     if (items.length === 0) {
         return null;
     }
     // remember where we started to prevent an infinite loop
     let index = startIndex;
-    const maxIndex = items.length - 1;
     do {
         // find first non-disabled item
-        index = wrapNumber(index + direction, 0, maxIndex);
+        index = wrapNumber(index + direction, 0, items.length - 1);
         if (!isItemDisabled(items[index], index, itemDisabled)) {
-            return items[index];
+            return {
+                item: items[index],
+                type: QueryListActiveItemType.ITEM,
+            };
         }
     } while (index !== startIndex);
     return null;

From 6964bbb62fa67c1db7ae2a22102c37571845f372 Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyang.li.95@gmail.com>
Date: Wed, 6 Feb 2019 20:23:25 +0800
Subject: [PATCH 07/30] Minor cleanup

---
 .../src/components/query-list/queryList.tsx   | 21 +++++++------------
 1 file changed, 8 insertions(+), 13 deletions(-)

diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index d34e4d0996..e609fe62d6 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -257,7 +257,11 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         const { activeItem, query } = this.state;
         const matchesPredicate = this.state.filteredItems.indexOf(item) >= 0;
         const modifiers: IItemModifiers = {
-            active: executeItemsEqual(this.props.itemsEqual, activeItem && activeItem.type === QueryListActiveItemType.ITEM ? activeItem.item : undefined, item),
+            active: executeItemsEqual(
+                this.props.itemsEqual,
+                activeItem && activeItem.type === QueryListActiveItemType.ITEM ? activeItem.item : undefined,
+                item,
+            ),
             disabled: isItemDisabled(item, index, this.props.itemDisabled),
             matchesPredicate,
         };
@@ -388,17 +392,7 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
                 };
             }
         }
-
-        const firstEnabledItem = getFirstEnabledItem(
-            this.state.filteredItems,
-            this.props.itemDisabled,
-            direction,
-            startIndex,
-        );
-        if (firstEnabledItem != null) {
-            return firstEnabledItem;
-        }
-        return null;
+        return getFirstEnabledItem(this.state.filteredItems, this.props.itemDisabled, direction, startIndex);
     }
 
     private setActiveItem(activeItem: IQueryListActiveItem<T> | null) {
@@ -468,9 +462,10 @@ export function getFirstEnabledItem<T>(
     }
     // remember where we started to prevent an infinite loop
     let index = startIndex;
+    const maxIndex = items.length - 1;
     do {
         // find first non-disabled item
-        index = wrapNumber(index + direction, 0, items.length - 1);
+        index = wrapNumber(index + direction, 0, maxIndex);
         if (!isItemDisabled(items[index], index, itemDisabled)) {
             return {
                 item: items[index],

From 4596f78569b38e77f235a6742145e44716a74c27 Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyang.li.95@gmail.com>
Date: Wed, 6 Feb 2019 20:32:33 +0800
Subject: [PATCH 08/30] Factor out getActiveItem

---
 packages/select/src/common/itemListRenderer.ts   |  7 +++++++
 .../src/components/query-list/queryList.tsx      | 16 +++++-----------
 2 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/packages/select/src/common/itemListRenderer.ts b/packages/select/src/common/itemListRenderer.ts
index 84e89288dd..3bf9944408 100644
--- a/packages/select/src/common/itemListRenderer.ts
+++ b/packages/select/src/common/itemListRenderer.ts
@@ -14,6 +14,13 @@ export interface IQueryListActiveItem<T> {
     item: T | null;
 }
 
+export function getActiveItem<T>(activeItem: IQueryListActiveItem<T> | null | undefined): T | null {
+    if (activeItem && activeItem.type === QueryListActiveItemType.ITEM) {
+        return activeItem.item;
+    }
+    return null;
+}
+
 /**
  * An object describing how to render the list of items.
  * An `itemListRenderer` receives this object as its sole argument.
diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index e609fe62d6..2ea18802a8 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -9,6 +9,7 @@ import * as React from "react";
 import { DISPLAYNAME_PREFIX, IProps, Keys, Menu, Utils } from "@blueprintjs/core";
 import {
     executeItemsEqual,
+    getActiveItem,
     IItemListRendererProps,
     IItemModifiers,
     IListItemsProps,
@@ -177,8 +178,8 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         const scrollToActiveItem = this.props.scrollToActiveItem !== false;
         const externalChangeToActiveItem = !executeItemsEqual(
             this.props.itemsEqual,
-            this.expectedNextActiveItem ? this.expectedNextActiveItem.item : null,
-            this.props.activeItem ? this.props.activeItem.item : null,
+            getActiveItem(this.expectedNextActiveItem),
+            getActiveItem(this.props.activeItem),
         );
         this.expectedNextActiveItem = null;
 
@@ -223,13 +224,10 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
 
         // always reset active item if it's now filtered or disabled
         const activeIndex = this.getActiveIndex(filteredItems);
-        const maybeActiveItem = this.state.activeItem ? this.state.activeItem.item : null;
         const shouldUpdateActiveItem =
             resetActiveItem ||
             activeIndex < 0 ||
-            // non-null assertion is safe because activeItem exists and was found in filteredItems
-            // (guaranteed because activeIndex >=0 here)
-            isItemDisabled(maybeActiveItem, activeIndex, props.itemDisabled);
+            isItemDisabled(getActiveItem(this.state.activeItem), activeIndex, props.itemDisabled);
 
         if (hasQueryChanged && shouldUpdateActiveItem) {
             this.setActiveItem(getFirstEnabledItem(filteredItems, props.itemDisabled));
@@ -257,11 +255,7 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         const { activeItem, query } = this.state;
         const matchesPredicate = this.state.filteredItems.indexOf(item) >= 0;
         const modifiers: IItemModifiers = {
-            active: executeItemsEqual(
-                this.props.itemsEqual,
-                activeItem && activeItem.type === QueryListActiveItemType.ITEM ? activeItem.item : undefined,
-                item,
-            ),
+            active: executeItemsEqual(this.props.itemsEqual, getActiveItem(activeItem), item),
             disabled: isItemDisabled(item, index, this.props.itemDisabled),
             matchesPredicate,
         };

From 01a1538676984f19014202aedc372495875f73ab Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyangl@palantir.com>
Date: Wed, 20 Feb 2019 13:13:18 -0500
Subject: [PATCH 09/30] createItem => createNewItem

---
 .../src/examples/select-examples/multiSelectExample.tsx   | 8 ++++----
 .../src/examples/select-examples/selectExample.tsx        | 8 ++++----
 packages/select/src/common/listItemsProps.ts              | 4 ++--
 packages/select/src/components/query-list/queryList.tsx   | 8 ++++----
 packages/select/src/components/select/select-component.md | 4 ++--
 packages/select/test/selectComponentSuite.tsx             | 8 ++++----
 6 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
index c830b56e91..57c746b915 100644
--- a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
@@ -59,8 +59,8 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
             // explicit undefined (not null) for default behavior (show full list)
             undefined
         );
-        const maybeCreateItemFromQuery = this.state.allowCreate ? createFilm : undefined;
-        const maybeCreateItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
+        const maybeCreateNewItemFromQuery = this.state.allowCreate ? createFilm : undefined;
+        const maybeCreateNewItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
 
         const clearButton = films.length > 0 ? <Button icon="cross" minimal={true} onClick={this.handleClear} /> : null;
 
@@ -77,8 +77,8 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
                     tagRenderer={this.renderTag}
                     tagInputProps={{ tagProps: getTagProps, onRemove: this.handleTagRemove, rightElement: clearButton }}
                     selectedItems={this.state.films}
-                    createItemFromQuery={maybeCreateItemFromQuery}
-                    createItemRenderer={maybeCreateItemRenderer}
+                    createNewItemFromQuery={maybeCreateNewItemFromQuery}
+                    createNewItemRenderer={maybeCreateNewItemRenderer}
                 />
             </Example>
         );
diff --git a/packages/docs-app/src/examples/select-examples/selectExample.tsx b/packages/docs-app/src/examples/select-examples/selectExample.tsx
index 2339879d6a..51f121f642 100644
--- a/packages/docs-app/src/examples/select-examples/selectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/selectExample.tsx
@@ -58,16 +58,16 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
         ) : (
             undefined
         );
-        const maybeCreateItemFromQuery = this.state.allowCreate ? createFilm : undefined;
-        const maybeCreateItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
+        const maybeCreateNewItemFromQuery = this.state.allowCreate ? createFilm : undefined;
+        const maybeCreateNewItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
 
         return (
             <Example options={this.renderOptions()} {...this.props}>
                 <FilmSelect
                     {...filmSelectProps}
                     {...flags}
-                    createItemFromQuery={maybeCreateItemFromQuery}
-                    createItemRenderer={maybeCreateItemRenderer}
+                    createNewItemFromQuery={maybeCreateNewItemFromQuery}
+                    createNewItemRenderer={maybeCreateNewItemRenderer}
                     disabled={disabled}
                     itemDisabled={this.isItemDisabled}
                     initialContent={initialContent}
diff --git a/packages/select/src/common/listItemsProps.ts b/packages/select/src/common/listItemsProps.ts
index c0cf6b28b9..0c562a717a 100644
--- a/packages/select/src/common/listItemsProps.ts
+++ b/packages/select/src/common/listItemsProps.ts
@@ -129,12 +129,12 @@ export interface IListItemsProps<T> extends IProps {
      * This is invoked when user interaction causes a new item to be created, either by pressing the `enter` key or
      * by clicking on the "Create Item" option. It transforms a query string into an item type.
      */
-    createItemFromQuery?: (query: string) => T;
+    createNewItemFromQuery?: (query: string) => T;
 
     /**
      * Custom renderer to transform the current query string into a selectable "Create Item" option.
      */
-    createItemRenderer?: (
+    createNewItemRenderer?: (
         query: string,
         active: boolean,
         handleClick: React.MouseEventHandler<HTMLElement>,
diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index 2ea18802a8..80079a0711 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -238,7 +238,7 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     private renderItemList = (listProps: IItemListRendererProps<T>) => {
         const { initialContent, noResults } = this.props;
 
-        // omit noResults if createItemFromQuery and createItemRenderer are both supplied, and query is not empty
+        // omit noResults if createNewItemFromQuery and createNewItemRenderer are both supplied, and query is not empty
         const maybeNoResults = this.isCreateItemRendered() ? null : noResults;
         const menuContent = renderFilteredItems(listProps, maybeNoResults, initialContent);
         const createItemView = this.isCreateItemRendered() ? this.renderCreateItemMenuItem(this.state.query) : null;
@@ -272,7 +272,7 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
             this.handleItemCreate(query, evt);
         };
         return Utils.safeInvoke(
-            this.props.createItemRenderer,
+            this.props.createNewItemRenderer,
             query,
             this.state.activeItem ? this.state.activeItem.type === QueryListActiveItemType.CREATE : false,
             handleClick,
@@ -316,7 +316,7 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     }
 
     private handleItemCreate = (query: string, evt?: React.SyntheticEvent<HTMLElement>) => {
-        const item = Utils.safeInvoke(this.props.createItemFromQuery, query);
+        const item = Utils.safeInvoke(this.props.createNewItemFromQuery, query);
         if (item != null) {
             Utils.safeInvoke(this.props.onItemSelect, item, evt);
             this.setQuery("", true);
@@ -400,7 +400,7 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     }
 
     private isCreateItemRendered(): boolean {
-        return (this.props.createItemFromQuery && this.props.createItemRenderer && this.state.query !== "") || false;
+        return !!(this.props.createNewItemFromQuery && this.props.createNewItemRenderer && this.state.query !== "");
     }
 }
 
diff --git a/packages/select/src/components/select/select-component.md b/packages/select/src/components/select/select-component.md
index d83422e9fd..5962cfe9a0 100644
--- a/packages/select/src/components/select/select-component.md
+++ b/packages/select/src/components/select/select-component.md
@@ -84,8 +84,8 @@ data sets.
 
 @## Creating new items
 
-Use the `createItemFromQuery` prop to allow `Select<T>` to create new items. `createItemFromQuery` specifies how to turn a
-user-entered query string into an item of type `<T>` that `Select` understands. You should also provide the `createItemRenderer`
+Use the `createNewItemFromQuery` prop to allow `Select<T>` to create new items. `createNewItemFromQuery` specifies how to turn a
+user-entered query string into an item of type `<T>` that `Select` understands. You should also provide the `createNewItemRenderer`
 prop to render a custom `MenuItem` to indicate that users can create new items.
 
 @## JavaScript API
diff --git a/packages/select/test/selectComponentSuite.tsx b/packages/select/test/selectComponentSuite.tsx
index 0e453e6e26..5c289d5afd 100644
--- a/packages/select/test/selectComponentSuite.tsx
+++ b/packages/select/test/selectComponentSuite.tsx
@@ -123,8 +123,8 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
     describe("create", () => {
         const testCreateProps = {
             ...testProps,
-            createItemFromQuery: sinon.spy(),
-            createItemRenderer: () => <textarea />,
+            createNewItemFromQuery: sinon.spy(),
+            createNewItemRenderer: () => <textarea />,
         };
 
         it("renders create item if filtering returns empty list", () => {
@@ -138,7 +138,7 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             assert.lengthOf(wrapper.find(`textarea`), 1, "should find createItem");
         });
 
-        it("enter invokes createItemFromQuery", () => {
+        it("enter invokes createNewItemFromQuery", () => {
             const wrapper = render({
                 ...testCreateProps,
                 items: [],
@@ -146,7 +146,7 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
                 query: "non-existent film name",
             });
             findInput(wrapper).simulate("keyup", { keyCode: Keys.ENTER });
-            assert.equal(testCreateProps.createItemFromQuery.args[0][0], "non-existent film name");
+            assert.equal(testCreateProps.createNewItemFromQuery.args[0][0], "non-existent film name");
         });
     });
 }

From d99d57062e5d92b874095cce7c6e053bcde9d329 Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyangl@palantir.com>
Date: Wed, 20 Feb 2019 13:25:53 -0500
Subject: [PATCH 10/30] Fix existing tests

---
 packages/select/test/queryListTests.tsx       | 33 ++++++++++++++-----
 .../select/test/renderFilteredItemsTests.tsx  |  7 ++--
 packages/select/test/selectComponentSuite.tsx | 14 ++++----
 3 files changed, 37 insertions(+), 17 deletions(-)

diff --git a/packages/select/test/queryListTests.tsx b/packages/select/test/queryListTests.tsx
index bff202fe01..6719435837 100644
--- a/packages/select/test/queryListTests.tsx
+++ b/packages/select/test/queryListTests.tsx
@@ -9,7 +9,7 @@ import * as React from "react";
 import * as sinon from "sinon";
 
 // this is an awkward import across the monorepo, but we'd rather not introduce a cyclical dependency or create another package
-import { IQueryListProps } from "@blueprintjs/select";
+import { IQueryListProps, QueryListActiveItemType } from "@blueprintjs/select";
 import { IFilm, renderFilm, TOP_100_FILMS } from "../../docs-app/src/examples/select-examples/films";
 import { IQueryListRendererProps, IQueryListState, ItemListPredicate, ItemListRenderer, QueryList } from "../src/index";
 
@@ -87,7 +87,14 @@ describe("<QueryList>", () => {
 
         it("ensure onActiveItemChange is not called with undefined and empty list", () => {
             const myItem = { title: "Toy Story 3", year: 2010, rank: 1 };
-            const filmQueryList = mount(<FilmQueryList {...testProps} items={[myItem]} activeItem={myItem} query="" />);
+            const filmQueryList = mount(
+                <FilmQueryList
+                    {...testProps}
+                    items={[myItem]}
+                    activeItem={{ type: QueryListActiveItemType.ITEM, item: myItem }}
+                    query=""
+                />,
+            );
             filmQueryList.setState({ query: "query" });
             filmQueryList.setState({ activeItem: undefined });
             assert.equal(testProps.onActiveItemChange.callCount, 0);
@@ -97,7 +104,10 @@ describe("<QueryList>", () => {
             const myItem = { title: "Toy Story 3", year: 2010, rank: 1 };
             const props: IQueryListProps<IFilm> = {
                 ...testProps,
-                activeItem: myItem,
+                activeItem: {
+                    item: myItem,
+                    type: QueryListActiveItemType.ITEM,
+                },
                 items: [myItem],
                 query: "",
             };
@@ -113,12 +123,14 @@ describe("<QueryList>", () => {
                 query: "abc",
             };
             const filmQueryList: FilmQueryListWrapper = mount(<FilmQueryList {...props} />);
-            assert.deepEqual(filmQueryList.state().activeItem, TOP_100_FILMS[0]);
+            assert.isNotNull(filmQueryList.state().activeItem);
+            assert.deepEqual(filmQueryList.state().activeItem!.item, TOP_100_FILMS[0]);
             filmQueryList.setProps({
                 items: [TOP_100_FILMS[1]],
                 query: "123",
             });
-            assert.deepEqual(filmQueryList.state().activeItem, TOP_100_FILMS[1]);
+            assert.isNotNull(filmQueryList.state().activeItem);
+            assert.deepEqual(filmQueryList.state().activeItem!.item, TOP_100_FILMS[1]);
         });
     });
 
@@ -132,17 +144,22 @@ describe("<QueryList>", () => {
                 query: "123",
             };
             const filmQueryList: FilmQueryListWrapper = mount(<FilmQueryList {...props} />);
-            assert(filmQueryList.state().activeItem === TOP_100_FILMS[11]);
+            assert.isNotNull(filmQueryList.state().activeItem);
+            assert(filmQueryList.state().activeItem!.item === TOP_100_FILMS[11]);
         });
 
         it("initializes to controlled activeItem prop (non-null)", () => {
             const props: IQueryListProps<IFilm> = {
                 ...testProps,
                 // List is not filtered, and item at index 11 is explicitly chosen as activeItem
-                activeItem: TOP_100_FILMS[11],
+                activeItem: {
+                    item: TOP_100_FILMS[11],
+                    type: QueryListActiveItemType.ITEM,
+                },
             };
             const filmQueryList: FilmQueryListWrapper = mount(<FilmQueryList {...props} />);
-            assert(filmQueryList.state().activeItem === TOP_100_FILMS[11]);
+            assert.isNotNull(filmQueryList.state().activeItem);
+            assert(filmQueryList.state().activeItem!.item === TOP_100_FILMS[11]);
         });
 
         it("initializes to controlled activeItem prop (null)", () => {
diff --git a/packages/select/test/renderFilteredItemsTests.tsx b/packages/select/test/renderFilteredItemsTests.tsx
index ca2b27fead..00d5a21cf8 100644
--- a/packages/select/test/renderFilteredItemsTests.tsx
+++ b/packages/select/test/renderFilteredItemsTests.tsx
@@ -7,11 +7,14 @@
 import { assert } from "chai";
 import React from "react";
 import sinon from "sinon";
-import { IItemListRendererProps, renderFilteredItems } from "../src";
+import { IItemListRendererProps, QueryListActiveItemType, renderFilteredItems } from "../src";
 
 describe("renderFilteredItems()", () => {
     const PROPS: IItemListRendererProps<string> = {
-        activeItem: "one",
+        activeItem: {
+            item: "one",
+            type: QueryListActiveItemType.ITEM,
+        },
         filteredItems: ["one"],
         items: ["one", "two", "three"],
         itemsParentRef: sinon.stub(),
diff --git a/packages/select/test/selectComponentSuite.tsx b/packages/select/test/selectComponentSuite.tsx
index 5c289d5afd..1dd9ed6f6f 100644
--- a/packages/select/test/selectComponentSuite.tsx
+++ b/packages/select/test/selectComponentSuite.tsx
@@ -61,7 +61,7 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
                 .at(4)
                 .simulate("click");
             assert.strictEqual(testProps.onItemSelect.args[0][0].rank, 6, "onItemSelect");
-            assert.strictEqual(testProps.onActiveItemChange.args[0][0].rank, 6, "onActiveItemChange");
+            assert.strictEqual(testProps.onActiveItemChange.args[0][0].item.rank, 6, "onActiveItemChange");
         });
 
         it("clicking item resets state when resetOnSelect=true", () => {
@@ -69,7 +69,7 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             findItems(wrapper)
                 .at(3)
                 .simulate("click");
-            const ranks = testProps.onActiveItemChange.args.map(args => (args[0] as IFilm).rank);
+            const ranks = testProps.onActiveItemChange.args.map(args => (args[0].item as IFilm).rank);
             // clicking changes to 5, then resets to 1
             assert.deepEqual(ranks, [5, 1]);
             assert.strictEqual(testProps.onQueryChange.lastCall.args[0], "");
@@ -86,14 +86,14 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             const wrapper = render({ ...testProps, query: "19", resetOnQuery: true });
             // more specific query picks the first item.
             wrapper.setProps({ query: "199" });
-            assert.strictEqual(testProps.onActiveItemChange.lastCall.args[0].rank, 1);
+            assert.strictEqual(testProps.onActiveItemChange.lastCall.args[0].item.rank, 1);
         });
 
         it("querying resets active item if it does not match", () => {
             const wrapper = render({ ...testProps, query: "19", resetOnQuery: false });
             // a different query altogether invalidates the previous active item, so QL chooses the first.
             wrapper.setProps({ query: "Forrest" });
-            assert.strictEqual(testProps.onActiveItemChange.lastCall.args[0].title, "Forrest Gump");
+            assert.strictEqual(testProps.onActiveItemChange.lastCall.args[0].item.title, "Forrest Gump");
         });
     });
 
@@ -103,19 +103,19 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             findInput(wrapper)
                 .simulate("keydown", { keyCode: Keys.ARROW_DOWN })
                 .simulate("keydown", { keyCode: Keys.ARROW_DOWN });
-            assert.equal((testProps.onActiveItemChange.lastCall.args[0] as IFilm).rank, 3);
+            assert.equal((testProps.onActiveItemChange.lastCall.args[0].item as IFilm).rank, 3);
         });
 
         it("arrow up invokes onActiveItemChange with previous filtered item", () => {
             const wrapper = render(testProps);
             findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_UP });
-            assert.equal((testProps.onActiveItemChange.lastCall.args[0] as IFilm).rank, 20);
+            assert.equal((testProps.onActiveItemChange.lastCall.args[0].item as IFilm).rank, 20);
         });
 
         it("enter invokes onItemSelect with active item", () => {
             const wrapper = render(testProps);
             findInput(wrapper).simulate("keyup", { keyCode: Keys.ENTER });
-            const activeItem = testProps.onActiveItemChange.lastCall.args[0];
+            const activeItem = testProps.onActiveItemChange.lastCall.args[0].item;
             assert.equal(testProps.onItemSelect.lastCall.args[0], activeItem);
         });
     });

From 6b676d5e86ed0cc4000811c85b7a4485c4d2f116 Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyangl@palantir.com>
Date: Wed, 20 Feb 2019 13:40:48 -0500
Subject: [PATCH 11/30] Use real item list in filtering test

---
 packages/select/test/selectComponentSuite.tsx | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/select/test/selectComponentSuite.tsx b/packages/select/test/selectComponentSuite.tsx
index 1dd9ed6f6f..7fb773acd5 100644
--- a/packages/select/test/selectComponentSuite.tsx
+++ b/packages/select/test/selectComponentSuite.tsx
@@ -130,7 +130,6 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
         it("renders create item if filtering returns empty list", () => {
             const wrapper = render({
                 ...testCreateProps,
-                items: [],
                 noResults: <address />,
                 query: "non-existent film name",
             });

From 2aa4b5456fcd1135d6ad9074b675caada9cc1877 Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyangl@palantir.com>
Date: Wed, 20 Feb 2019 13:46:01 -0500
Subject: [PATCH 12/30] More type-safe active item getter

---
 packages/select/test/queryListTests.tsx | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/packages/select/test/queryListTests.tsx b/packages/select/test/queryListTests.tsx
index 6719435837..f6ab7049c9 100644
--- a/packages/select/test/queryListTests.tsx
+++ b/packages/select/test/queryListTests.tsx
@@ -11,7 +11,14 @@ import * as sinon from "sinon";
 // this is an awkward import across the monorepo, but we'd rather not introduce a cyclical dependency or create another package
 import { IQueryListProps, QueryListActiveItemType } from "@blueprintjs/select";
 import { IFilm, renderFilm, TOP_100_FILMS } from "../../docs-app/src/examples/select-examples/films";
-import { IQueryListRendererProps, IQueryListState, ItemListPredicate, ItemListRenderer, QueryList } from "../src/index";
+import {
+    getActiveItem,
+    IQueryListRendererProps,
+    IQueryListState,
+    ItemListPredicate,
+    ItemListRenderer,
+    QueryList,
+} from "../src/index";
 
 type FilmQueryListWrapper = ReactWrapper<IQueryListProps<IFilm>, IQueryListState<IFilm>>;
 
@@ -124,13 +131,13 @@ describe("<QueryList>", () => {
             };
             const filmQueryList: FilmQueryListWrapper = mount(<FilmQueryList {...props} />);
             assert.isNotNull(filmQueryList.state().activeItem);
-            assert.deepEqual(filmQueryList.state().activeItem!.item, TOP_100_FILMS[0]);
+            assert.deepEqual(getActiveItem(filmQueryList.state().activeItem), TOP_100_FILMS[0]);
             filmQueryList.setProps({
                 items: [TOP_100_FILMS[1]],
                 query: "123",
             });
             assert.isNotNull(filmQueryList.state().activeItem);
-            assert.deepEqual(filmQueryList.state().activeItem!.item, TOP_100_FILMS[1]);
+            assert.deepEqual(getActiveItem(filmQueryList.state().activeItem), TOP_100_FILMS[1]);
         });
     });
 
@@ -145,7 +152,7 @@ describe("<QueryList>", () => {
             };
             const filmQueryList: FilmQueryListWrapper = mount(<FilmQueryList {...props} />);
             assert.isNotNull(filmQueryList.state().activeItem);
-            assert(filmQueryList.state().activeItem!.item === TOP_100_FILMS[11]);
+            assert(getActiveItem(filmQueryList.state().activeItem) === TOP_100_FILMS[11]);
         });
 
         it("initializes to controlled activeItem prop (non-null)", () => {
@@ -159,7 +166,7 @@ describe("<QueryList>", () => {
             };
             const filmQueryList: FilmQueryListWrapper = mount(<FilmQueryList {...props} />);
             assert.isNotNull(filmQueryList.state().activeItem);
-            assert(filmQueryList.state().activeItem!.item === TOP_100_FILMS[11]);
+            assert(getActiveItem(filmQueryList.state().activeItem) === TOP_100_FILMS[11]);
         });
 
         it("initializes to controlled activeItem prop (null)", () => {

From 321cd03db5f69cf02e816b10c2a07d438ebfba90 Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyangl@palantir.com>
Date: Wed, 20 Feb 2019 14:07:09 -0500
Subject: [PATCH 13/30] Add tests for interacting with create item

---
 packages/select/test/selectComponentSuite.tsx | 59 +++++++++++++++++--
 1 file changed, 55 insertions(+), 4 deletions(-)

diff --git a/packages/select/test/selectComponentSuite.tsx b/packages/select/test/selectComponentSuite.tsx
index 7fb773acd5..0143ca10e4 100644
--- a/packages/select/test/selectComponentSuite.tsx
+++ b/packages/select/test/selectComponentSuite.tsx
@@ -10,7 +10,7 @@ import { ReactWrapper } from "enzyme";
 import * as React from "react";
 import * as sinon from "sinon";
 import { filterFilm, IFilm, renderFilm, TOP_100_FILMS } from "../../docs-app/src/examples/select-examples/films";
-import { IListItemsProps } from "../src/index";
+import { IListItemsProps, IQueryListActiveItem, QueryListActiveItemType } from "../src/index";
 
 export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
     render: (props: IListItemsProps<IFilm>) => ReactWrapper<P, S>,
@@ -125,12 +125,29 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             ...testProps,
             createNewItemFromQuery: sinon.spy(),
             createNewItemRenderer: () => <textarea />,
+            noResults: <address />,
         };
 
+        it("doesn't render create item if input is empty", () => {
+            const wrapper = render({
+                ...testCreateProps,
+                query: "",
+            });
+            assert.lengthOf(wrapper.find(`textarea`), 0, "should not find createItem");
+        });
+
+        it("renders create item if input is not empty", () => {
+            const wrapper = render({
+                ...testCreateProps,
+                query: TOP_100_FILMS[0].title,
+            });
+            assert.lengthOf(wrapper.find("address"), 0, "should not find noResults");
+            assert.lengthOf(wrapper.find(`textarea`), 1, "should find createItem");
+        });
+
         it("renders create item if filtering returns empty list", () => {
             const wrapper = render({
                 ...testCreateProps,
-                noResults: <address />,
                 query: "non-existent film name",
             });
             assert.lengthOf(wrapper.find("address"), 0, "should not find noResults");
@@ -140,12 +157,46 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
         it("enter invokes createNewItemFromQuery", () => {
             const wrapper = render({
                 ...testCreateProps,
-                items: [],
-                noResults: <address />,
                 query: "non-existent film name",
             });
             findInput(wrapper).simulate("keyup", { keyCode: Keys.ENTER });
             assert.equal(testCreateProps.createNewItemFromQuery.args[0][0], "non-existent film name");
         });
+
+        it("when create item is rendered, arrow down invokes onActiveItemChange with CREATE", () => {
+            const wrapper = render({
+                ...testCreateProps,
+                query: TOP_100_FILMS[0].title,
+            });
+            findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_DOWN });
+            assert.equal(
+                (testProps.onActiveItemChange.lastCall.args[0] as IQueryListActiveItem<IFilm>).type,
+                QueryListActiveItemType.CREATE,
+            );
+            findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_DOWN });
+            assert.equal(
+                (testProps.onActiveItemChange.lastCall.args[0] as IQueryListActiveItem<IFilm>).type,
+                QueryListActiveItemType.ITEM,
+            );
+            assert.equal((testProps.onActiveItemChange.lastCall.args[0].item as IFilm).rank, TOP_100_FILMS[0].rank);
+        });
+
+        it("when create item is rendered, arrow up invokes onActiveItemChange with CREATE", () => {
+            const wrapper = render({
+                ...testCreateProps,
+                query: TOP_100_FILMS[0].title,
+            });
+            findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_UP });
+            assert.equal(
+                (testProps.onActiveItemChange.lastCall.args[0] as IQueryListActiveItem<IFilm>).type,
+                QueryListActiveItemType.CREATE,
+            );
+            findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_UP });
+            assert.equal(
+                (testProps.onActiveItemChange.lastCall.args[0] as IQueryListActiveItem<IFilm>).type,
+                QueryListActiveItemType.ITEM,
+            );
+            assert.equal((testProps.onActiveItemChange.lastCall.args[0].item as IFilm).rank, TOP_100_FILMS[0].rank);
+        });
     });
 }

From 4c47f0300bdae3e2d745a3aaf8ab177fe3731985 Mon Sep 17 00:00:00 2001
From: Shuyang Li <shuyangl@palantir.com>
Date: Wed, 20 Feb 2019 14:28:26 -0500
Subject: [PATCH 14/30] Add docs for creating items

---
 .../src/components/select/select-component.md | 35 +++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/packages/select/src/components/select/select-component.md b/packages/select/src/components/select/select-component.md
index 5962cfe9a0..c701d13308 100644
--- a/packages/select/src/components/select/select-component.md
+++ b/packages/select/src/components/select/select-component.md
@@ -88,6 +88,41 @@ Use the `createNewItemFromQuery` prop to allow `Select<T>` to create new items.
 user-entered query string into an item of type `<T>` that `Select` understands. You should also provide the `createNewItemRenderer`
 prop to render a custom `MenuItem` to indicate that users can create new items.
 
+```tsx
+function createFilm(title: string): IFilm {
+    return {
+        rank: /* ... */,
+        title,
+        year: /* ... */,
+    };
+}
+
+function renderCreateFilmOption(query: string, active: boolean, handleClick: React.MouseEventHandler<HTMLElement>) {
+    return (
+        <MenuItem
+            icon="add"
+            text={`Create "${query}"`}
+            active={active}
+            onClick={handleClick}
+            shouldDismissPopover={false}
+        />
+    )
+}
+
+ReactDOM.render(
+    <FilmSelect
+        items={Films.items}
+        itemPredicate={Films.itemPredicate}
+        itemRenderer={Films.itemRenderer}
+        noResults={<MenuItem disabled={true} text="No results." />}
+        createNewItemFromQuery={createFilm}
+        createNewItemRenderer={renderCreateFilmOption}
+        onItemSelect={...}
+    />,
+    document.querySelector("#root")
+);
+```
+
 @## JavaScript API
 
 @interface ISelectProps

From f54513f197787ae7eec22b2f7c955a2263d0eb6f Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Tue, 26 Feb 2019 11:55:28 -0800
Subject: [PATCH 15/30] Try a non-breaking API that adds a new generic type C

---
 .../select/src/common/itemListRenderer.ts     | 40 +++++++----
 packages/select/src/common/listItemsProps.ts  | 69 +++++++++++++++----
 .../src/components/query-list/queryList.tsx   | 16 +++--
 3 files changed, 92 insertions(+), 33 deletions(-)

diff --git a/packages/select/src/common/itemListRenderer.ts b/packages/select/src/common/itemListRenderer.ts
index 3bf9944408..79dfb41ef4 100644
--- a/packages/select/src/common/itemListRenderer.ts
+++ b/packages/select/src/common/itemListRenderer.ts
@@ -1,36 +1,46 @@
+/*!
+ * Copyright 2018 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the terms of the LICENSE file distributed with this project.
+ */
+
+import { IListItemsCreateNewItem } from "./listItemsProps";
+
 /*
  * Copyright 2017 Palantir Technologies, Inc. All rights reserved.
  *
  * Licensed under the terms of the LICENSE file distributed with this project.
  */
 
-export enum QueryListActiveItemType {
-    CREATE = "create",
-    ITEM = "item",
-}
+// export enum QueryListActiveItemType {
+//     CREATE = "create",
+//     ITEM = "item",
+// }
 
-export interface IQueryListActiveItem<T> {
-    type: QueryListActiveItemType;
-    item: T | null;
-}
+// export interface IQueryListActiveItem<T> {
+//     type: QueryListActiveItemType;
+//     item: T | null;
+// }
 
-export function getActiveItem<T>(activeItem: IQueryListActiveItem<T> | null | undefined): T | null {
-    if (activeItem && activeItem.type === QueryListActiveItemType.ITEM) {
-        return activeItem.item;
-    }
-    return null;
+// TODO (clewis): Make sure this works with the "Create Item" option.
+export function getActiveItem<T, C = IListItemsCreateNewItem>(activeItem: T | C | null | undefined): T | C | null {
+    // if (activeItem && activeItem.type === QueryListActiveItemType.ITEM) {
+    //     return activeItem.item;
+    // }
+    // return null;
+    return activeItem === undefined ? null : activeItem;
 }
 
 /**
  * An object describing how to render the list of items.
  * An `itemListRenderer` receives this object as its sole argument.
  */
-export interface IItemListRendererProps<T> {
+export interface IItemListRendererProps<T, C = IListItemsCreateNewItem> {
     /**
      * The currently focused item (for keyboard interactions), or `null` to
      * indicate that no item is active.
      */
-    activeItem: IQueryListActiveItem<T> | null;
+    activeItem: T | C | null;
 
     /**
      * Array of items filtered by `itemListPredicate` or `itemPredicate`.
diff --git a/packages/select/src/common/listItemsProps.ts b/packages/select/src/common/listItemsProps.ts
index 0c562a717a..eba278e54b 100644
--- a/packages/select/src/common/listItemsProps.ts
+++ b/packages/select/src/common/listItemsProps.ts
@@ -1,11 +1,11 @@
 /*
-* Copyright 2018 Palantir Technologies, Inc. All rights reserved.
-*
-* Licensed under the terms of the LICENSE file distributed with this project.
-*/
+ * Copyright 2018 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the terms of the LICENSE file distributed with this project.
+ */
 
 import { IProps, Utils } from "@blueprintjs/core";
-import { IQueryListActiveItem, ItemListRenderer } from "./itemListRenderer";
+import { ItemListRenderer } from "./itemListRenderer";
 import { ItemRenderer } from "./itemRenderer";
 import { ItemListPredicate, ItemPredicate } from "./predicate";
 
@@ -20,15 +20,44 @@ export type ItemsEqualComparator<T> = (itemA: T, itemB: T) => boolean;
  */
 export type ItemsEqualProp<T> = ItemsEqualComparator<T> | keyof T;
 
+/**
+ * The default type of the "Create Item" option. If this is incompatible with
+ * your custom type `T`, feel free to override this in `IListItemsProps` with a
+ * custom type `C` of your choosing.
+ */
+export interface IListItemsCreateNewItem {
+    type: "create";
+    value: null;
+}
+
 /** Reusable generic props for a component that operates on a filterable, selectable list of `items`. */
-export interface IListItemsProps<T> extends IProps {
+export interface IListItemsProps<T, C = IListItemsCreateNewItem> extends IProps {
     /**
      * The currently focused item for keyboard interactions, or `null` to
      * indicate that no item is active. If omitted or `undefined`, this prop will be
      * uncontrolled (managed by the component's state). Use `onActiveItemChange`
      * to listen for updates.
      */
-    activeItem?: IQueryListActiveItem<T> | null;
+    activeItem?: T | C | null;
+
+    /**
+     * Whether the specified item is the "Create item" option. This is necessary
+     * because the "Create Item" option can have a custom type `C`. You should
+     * provide this function only if you've overridden the default type for the
+     * "Create Item" option (`IListItemsCreateNewItem`); otherwise, an
+     * acceptable default implementation will be used.
+     */
+    isCreateNewItem?: (item: T | C | null) => boolean;
+
+    // /**
+    //  * Whether the "Create Item" option is currently active.
+    //  *
+    //  * _Note:_ This was introduced as a separate prop from `activeItem` to avoid
+    //  * breaking the existing API. It may be resolved into `activeItem` in a
+    //  * future major release. At present, it is the responsibility of the caller
+    //  * to coordinate these two props as needed.
+    //  */
+    // isCreateNewItemActive: boolean;
 
     /** Array of items in the list. */
     items: T[];
@@ -111,7 +140,19 @@ export interface IListItemsProps<T> extends IProps {
      * in the list, selecting an item makes it active, and changing the query may reset it to
      * the first item in the list if it no longer matches the filter.
      */
-    onActiveItemChange?: (activeItem: IQueryListActiveItem<T> | null) => void;
+    onActiveItemChange?: (activeItem: T | C | null) => void;
+
+    // /**
+    //  * Invoked when user interaction should change the active status of the
+    //  * "Create Item" option, assuming it is rendered.
+    //  *
+    //  * _Note:_ This was introduced as a separate callback from
+    //  * `onActiveItemChange` to avoid breaking the existing API. It may be
+    //  * resolved into `onActiveItemChange` in a future major release. At present,
+    //  * it is the responsibility of the caller to coordinate these two callbacks
+    //  * as needed.
+    //  */
+    // onCreateNewItemActiveChange?: () => void;
 
     /**
      * Callback invoked when an item from the list is selected,
@@ -125,14 +166,18 @@ export interface IListItemsProps<T> extends IProps {
     onQueryChange?: (query: string, event?: React.ChangeEvent<HTMLInputElement>) => void;
 
     /**
-     * If provided, allows new items to be created with the current query string.
-     * This is invoked when user interaction causes a new item to be created, either by pressing the `enter` key or
-     * by clicking on the "Create Item" option. It transforms a query string into an item type.
+     * If provided, allows new items to be created using the current query
+     * string. This is invoked when user interaction causes a new item to be
+     * created, either by pressing the `Enter` key or by clicking on the "Create
+     * Item" option. It transforms a query string into an item type.
      */
     createNewItemFromQuery?: (query: string) => T;
 
     /**
-     * Custom renderer to transform the current query string into a selectable "Create Item" option.
+     * Custom renderer to transform the current query string into a selectable
+     * "Create Item" option. If this function is provided, a "Create Item"
+     * option will be rendered at the end of the list of items. If this function
+     * is not provided, a "Create Item" option will not be displayed.
      */
     createNewItemRenderer?: (
         query: string,
diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index 80079a0711..f72b4b100e 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -12,9 +12,10 @@ import {
     getActiveItem,
     IItemListRendererProps,
     IItemModifiers,
+    IListItemsCreateNewItem,
+    // IQueryListActiveItem,
+    // QueryListActiveItemType,
     IListItemsProps,
-    IQueryListActiveItem,
-    QueryListActiveItemType,
     renderFilteredItems,
 } from "../../common";
 
@@ -73,9 +74,9 @@ export interface IQueryListRendererProps<T> extends IQueryListState<T>, IProps {
     itemList: React.ReactNode;
 }
 
-export interface IQueryListState<T> {
+export interface IQueryListState<T, C = IListItemsCreateNewItem> {
     /** The currently focused item (for keyboard interactions). */
-    activeItem: IQueryListActiveItem<T> | null;
+    activeItem: T | C | null;
 
     /** The original `items` array filtered by `itemListPredicate` or `itemPredicate`. */
     filteredItems: T[];
@@ -84,7 +85,10 @@ export interface IQueryListState<T> {
     query: string;
 }
 
-export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryListState<T>> {
+export class QueryList<T, C = IListItemsCreateNewItem> extends React.Component<
+    IQueryListProps<T>,
+    IQueryListState<T, C>
+> {
     public static displayName = `${DISPLAYNAME_PREFIX}.QueryList`;
 
     public static defaultProps = {
@@ -112,7 +116,7 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
      * or key interactions). When scrollToActiveItem = false, used to detect if
      * an unexpected external change to the active item has been made.
      */
-    private expectedNextActiveItem: IQueryListActiveItem<T> | null = null;
+    private expectedNextActiveItem: T | C | null = null;
 
     public constructor(props: IQueryListProps<T>, context?: any) {
         super(props, context);

From cde4086f0cf7340eda5682e0f28a9ab3b9d8806f Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Tue, 26 Feb 2019 12:28:25 -0800
Subject: [PATCH 16/30] Actually, just create a reserved type with a __brand,
 and incorporate throughout

---
 packages/select/src/common/index.ts           |  1 +
 .../select/src/common/itemListRenderer.ts     | 31 +---------
 packages/select/src/common/listItemsProps.ts  | 48 ++-------------
 packages/select/src/common/listItemsUtils.ts  | 27 +++++++++
 .../src/components/query-list/queryList.tsx   | 59 +++++++------------
 5 files changed, 57 insertions(+), 109 deletions(-)
 create mode 100644 packages/select/src/common/listItemsUtils.ts

diff --git a/packages/select/src/common/index.ts b/packages/select/src/common/index.ts
index dfd076af8d..e989e9a114 100644
--- a/packages/select/src/common/index.ts
+++ b/packages/select/src/common/index.ts
@@ -10,4 +10,5 @@ export { Classes };
 export * from "./itemListRenderer";
 export * from "./itemRenderer";
 export * from "./listItemsProps";
+export * from "./listItemsUtils";
 export * from "./predicate";
diff --git a/packages/select/src/common/itemListRenderer.ts b/packages/select/src/common/itemListRenderer.ts
index 79dfb41ef4..07ed04c5c7 100644
--- a/packages/select/src/common/itemListRenderer.ts
+++ b/packages/select/src/common/itemListRenderer.ts
@@ -4,43 +4,18 @@
  * Licensed under the terms of the LICENSE file distributed with this project.
  */
 
-import { IListItemsCreateNewItem } from "./listItemsProps";
-
-/*
- * Copyright 2017 Palantir Technologies, Inc. All rights reserved.
- *
- * Licensed under the terms of the LICENSE file distributed with this project.
- */
-
-// export enum QueryListActiveItemType {
-//     CREATE = "create",
-//     ITEM = "item",
-// }
-
-// export interface IQueryListActiveItem<T> {
-//     type: QueryListActiveItemType;
-//     item: T | null;
-// }
-
-// TODO (clewis): Make sure this works with the "Create Item" option.
-export function getActiveItem<T, C = IListItemsCreateNewItem>(activeItem: T | C | null | undefined): T | C | null {
-    // if (activeItem && activeItem.type === QueryListActiveItemType.ITEM) {
-    //     return activeItem.item;
-    // }
-    // return null;
-    return activeItem === undefined ? null : activeItem;
-}
+import { ICreateNewItem } from "./listItemsUtils";
 
 /**
  * An object describing how to render the list of items.
  * An `itemListRenderer` receives this object as its sole argument.
  */
-export interface IItemListRendererProps<T, C = IListItemsCreateNewItem> {
+export interface IItemListRendererProps<T> {
     /**
      * The currently focused item (for keyboard interactions), or `null` to
      * indicate that no item is active.
      */
-    activeItem: T | C | null;
+    activeItem: T | ICreateNewItem | null;
 
     /**
      * Array of items filtered by `itemListPredicate` or `itemPredicate`.
diff --git a/packages/select/src/common/listItemsProps.ts b/packages/select/src/common/listItemsProps.ts
index eba278e54b..c9acd52ff6 100644
--- a/packages/select/src/common/listItemsProps.ts
+++ b/packages/select/src/common/listItemsProps.ts
@@ -7,6 +7,7 @@
 import { IProps, Utils } from "@blueprintjs/core";
 import { ItemListRenderer } from "./itemListRenderer";
 import { ItemRenderer } from "./itemRenderer";
+import { ICreateNewItem } from "./listItemsUtils";
 import { ItemListPredicate, ItemPredicate } from "./predicate";
 
 /**
@@ -20,44 +21,15 @@ export type ItemsEqualComparator<T> = (itemA: T, itemB: T) => boolean;
  */
 export type ItemsEqualProp<T> = ItemsEqualComparator<T> | keyof T;
 
-/**
- * The default type of the "Create Item" option. If this is incompatible with
- * your custom type `T`, feel free to override this in `IListItemsProps` with a
- * custom type `C` of your choosing.
- */
-export interface IListItemsCreateNewItem {
-    type: "create";
-    value: null;
-}
-
 /** Reusable generic props for a component that operates on a filterable, selectable list of `items`. */
-export interface IListItemsProps<T, C = IListItemsCreateNewItem> extends IProps {
+export interface IListItemsProps<T> extends IProps {
     /**
      * The currently focused item for keyboard interactions, or `null` to
      * indicate that no item is active. If omitted or `undefined`, this prop will be
      * uncontrolled (managed by the component's state). Use `onActiveItemChange`
      * to listen for updates.
      */
-    activeItem?: T | C | null;
-
-    /**
-     * Whether the specified item is the "Create item" option. This is necessary
-     * because the "Create Item" option can have a custom type `C`. You should
-     * provide this function only if you've overridden the default type for the
-     * "Create Item" option (`IListItemsCreateNewItem`); otherwise, an
-     * acceptable default implementation will be used.
-     */
-    isCreateNewItem?: (item: T | C | null) => boolean;
-
-    // /**
-    //  * Whether the "Create Item" option is currently active.
-    //  *
-    //  * _Note:_ This was introduced as a separate prop from `activeItem` to avoid
-    //  * breaking the existing API. It may be resolved into `activeItem` in a
-    //  * future major release. At present, it is the responsibility of the caller
-    //  * to coordinate these two props as needed.
-    //  */
-    // isCreateNewItemActive: boolean;
+    activeItem?: T | ICreateNewItem | null;
 
     /** Array of items in the list. */
     items: T[];
@@ -140,19 +112,7 @@ export interface IListItemsProps<T, C = IListItemsCreateNewItem> extends IProps
      * in the list, selecting an item makes it active, and changing the query may reset it to
      * the first item in the list if it no longer matches the filter.
      */
-    onActiveItemChange?: (activeItem: T | C | null) => void;
-
-    // /**
-    //  * Invoked when user interaction should change the active status of the
-    //  * "Create Item" option, assuming it is rendered.
-    //  *
-    //  * _Note:_ This was introduced as a separate callback from
-    //  * `onActiveItemChange` to avoid breaking the existing API. It may be
-    //  * resolved into `onActiveItemChange` in a future major release. At present,
-    //  * it is the responsibility of the caller to coordinate these two callbacks
-    //  * as needed.
-    //  */
-    // onCreateNewItemActiveChange?: () => void;
+    onActiveItemChange?: (activeItem: T | ICreateNewItem | null) => void;
 
     /**
      * Callback invoked when an item from the list is selected,
diff --git a/packages/select/src/common/listItemsUtils.ts b/packages/select/src/common/listItemsUtils.ts
new file mode 100644
index 0000000000..67d1e3ea7f
--- /dev/null
+++ b/packages/select/src/common/listItemsUtils.ts
@@ -0,0 +1,27 @@
+/*!
+ * Copyright 2018 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the terms of the LICENSE file distributed with this project.
+ */
+
+const CREATE_NEW_ITEM_BRAND = "blueprint-create-item";
+
+/** The reserved type of the "Create Item" option in item lists. */
+export interface ICreateNewItem {
+    __blueprintBrand: typeof CREATE_NEW_ITEM_BRAND;
+}
+
+export function getCreateNewItem(): ICreateNewItem {
+    return { __blueprintBrand: CREATE_NEW_ITEM_BRAND };
+}
+
+export function isCreateNewItem<T>(item: T | ICreateNewItem | null | undefined): item is ICreateNewItem {
+    return item != null && (item as ICreateNewItem).__blueprintBrand === CREATE_NEW_ITEM_BRAND;
+}
+
+export function getActiveItem<T>(activeItem: T | ICreateNewItem | null | undefined): T | null {
+    if (activeItem != null && !isCreateNewItem(activeItem)) {
+        return activeItem;
+    }
+    return null;
+}
diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index f72b4b100e..e9b0e1ecb3 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -10,12 +10,12 @@ import { DISPLAYNAME_PREFIX, IProps, Keys, Menu, Utils } from "@blueprintjs/core
 import {
     executeItemsEqual,
     getActiveItem,
+    getCreateNewItem,
+    ICreateNewItem,
     IItemListRendererProps,
     IItemModifiers,
-    IListItemsCreateNewItem,
-    // IQueryListActiveItem,
-    // QueryListActiveItemType,
     IListItemsProps,
+    isCreateNewItem,
     renderFilteredItems,
 } from "../../common";
 
@@ -74,9 +74,9 @@ export interface IQueryListRendererProps<T> extends IQueryListState<T>, IProps {
     itemList: React.ReactNode;
 }
 
-export interface IQueryListState<T, C = IListItemsCreateNewItem> {
+export interface IQueryListState<T> {
     /** The currently focused item (for keyboard interactions). */
-    activeItem: T | C | null;
+    activeItem: T | ICreateNewItem | null;
 
     /** The original `items` array filtered by `itemListPredicate` or `itemPredicate`. */
     filteredItems: T[];
@@ -85,10 +85,7 @@ export interface IQueryListState<T, C = IListItemsCreateNewItem> {
     query: string;
 }
 
-export class QueryList<T, C = IListItemsCreateNewItem> extends React.Component<
-    IQueryListProps<T>,
-    IQueryListState<T, C>
-> {
+export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryListState<T>> {
     public static displayName = `${DISPLAYNAME_PREFIX}.QueryList`;
 
     public static defaultProps = {
@@ -116,7 +113,7 @@ export class QueryList<T, C = IListItemsCreateNewItem> extends React.Component<
      * or key interactions). When scrollToActiveItem = false, used to detect if
      * an unexpected external change to the active item has been made.
      */
-    private expectedNextActiveItem: T | C | null = null;
+    private expectedNextActiveItem: T | ICreateNewItem | null = null;
 
     public constructor(props: IQueryListProps<T>, context?: any) {
         super(props, context);
@@ -272,21 +269,18 @@ export class QueryList<T, C = IListItemsCreateNewItem> extends React.Component<
     };
 
     private renderCreateItemMenuItem = (query: string) => {
+        const { activeItem } = this.state;
         const handleClick: React.MouseEventHandler<HTMLElement> = evt => {
             this.handleItemCreate(query, evt);
         };
-        return Utils.safeInvoke(
-            this.props.createNewItemRenderer,
-            query,
-            this.state.activeItem ? this.state.activeItem.type === QueryListActiveItemType.CREATE : false,
-            handleClick,
-        );
+        const isActive = isCreateNewItem(activeItem);
+        return Utils.safeInvoke(this.props.createNewItemRenderer, query, isActive, handleClick);
     };
 
     private getActiveElement() {
+        const { activeItem } = this.state;
         if (this.itemsParentRef != null) {
-            if (this.state.activeItem && this.state.activeItem.type === QueryListActiveItemType.CREATE) {
-                // "Create" is active
+            if (isCreateNewItem(activeItem)) {
                 return this.itemsParentRef.children.item(this.state.filteredItems.length) as HTMLElement;
             } else {
                 const activeIndex = this.getActiveIndex();
@@ -298,12 +292,12 @@ export class QueryList<T, C = IListItemsCreateNewItem> extends React.Component<
 
     private getActiveIndex(items = this.state.filteredItems) {
         const { activeItem } = this.state;
-        if (activeItem == null || activeItem.type === QueryListActiveItemType.CREATE || activeItem.item == null) {
+        if (activeItem == null || isCreateNewItem(activeItem)) {
             return -1;
         }
         // NOTE: this operation is O(n) so it should be avoided in render(). safe for events though.
         for (let i = 0; i < items.length; ++i) {
-            if (executeItemsEqual(this.props.itemsEqual, items[i], activeItem.item)) {
+            if (executeItemsEqual(this.props.itemsEqual, items[i], activeItem)) {
                 return i;
             }
         }
@@ -328,10 +322,7 @@ export class QueryList<T, C = IListItemsCreateNewItem> extends React.Component<
     };
 
     private handleItemSelect = (item: T, event?: React.SyntheticEvent<HTMLElement>) => {
-        this.setActiveItem({
-            item,
-            type: QueryListActiveItemType.ITEM,
-        });
+        this.setActiveItem(item);
         Utils.safeInvoke(this.props.onItemSelect, item, event);
         if (this.props.resetOnSelect) {
             this.setQuery("", true);
@@ -358,10 +349,10 @@ export class QueryList<T, C = IListItemsCreateNewItem> extends React.Component<
         // and the popvoer would re-open out of our control :(.
         if (event.keyCode === Keys.ENTER) {
             event.preventDefault();
-            if (activeItem == null || activeItem.type === QueryListActiveItemType.CREATE || activeItem.item == null) {
+            if (activeItem == null || isCreateNewItem(activeItem)) {
                 this.handleItemCreate(this.state.query, event);
             } else {
-                this.handleItemSelect(activeItem.item, event);
+                this.handleItemSelect(activeItem, event);
             }
         }
         Utils.safeInvoke(onKeyUp, event);
@@ -378,22 +369,19 @@ export class QueryList<T, C = IListItemsCreateNewItem> extends React.Component<
      * index. A `null` return value means no suitable item was found.
      * @param direction amount to move in each iteration, typically +/-1
      */
-    private getNextActiveItem(direction: number, startIndex = this.getActiveIndex()): IQueryListActiveItem<T> | null {
+    private getNextActiveItem(direction: number, startIndex = this.getActiveIndex()): T | ICreateNewItem | null {
         if (this.isCreateItemRendered()) {
             const reachedCreate =
                 (startIndex === 0 && direction === -1) ||
                 (startIndex === this.state.filteredItems.length - 1 && direction === 1);
             if (reachedCreate) {
-                return {
-                    item: null,
-                    type: QueryListActiveItemType.CREATE,
-                };
+                return getCreateNewItem();
             }
         }
         return getFirstEnabledItem(this.state.filteredItems, this.props.itemDisabled, direction, startIndex);
     }
 
-    private setActiveItem(activeItem: IQueryListActiveItem<T> | null) {
+    private setActiveItem(activeItem: T | ICreateNewItem | null) {
         this.expectedNextActiveItem = activeItem;
         if (this.props.activeItem === undefined) {
             // indicate that the active item may need to be scrolled into view after update.
@@ -454,7 +442,7 @@ export function getFirstEnabledItem<T>(
     itemDisabled?: keyof T | ((item: T, index: number) => boolean),
     direction = 1,
     startIndex = items.length - 1,
-): IQueryListActiveItem<T> | null {
+): T | ICreateNewItem | null {
     if (items.length === 0) {
         return null;
     }
@@ -465,10 +453,7 @@ export function getFirstEnabledItem<T>(
         // find first non-disabled item
         index = wrapNumber(index + direction, 0, maxIndex);
         if (!isItemDisabled(items[index], index, itemDisabled)) {
-            return {
-                item: items[index],
-                type: QueryListActiveItemType.ITEM,
-            };
+            return items[index];
         }
     } while (index !== startIndex);
     return null;

From 4ea4706070e3f973ebdeb1292fdd0b78f03afe39 Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Tue, 26 Feb 2019 12:51:07 -0800
Subject: [PATCH 17/30] Update examples

---
 .../src/examples/select-examples/films.tsx    | 14 ++++++++
 .../select-examples/multiSelectExample.tsx    | 30 +++++------------
 .../select-examples/omnibarExample.tsx        | 33 ++++++++++++++-----
 .../select-examples/selectExample.tsx         | 22 +++----------
 .../select-examples/suggestExample.tsx        | 18 ++++++++--
 5 files changed, 67 insertions(+), 50 deletions(-)

diff --git a/packages/docs-app/src/examples/select-examples/films.tsx b/packages/docs-app/src/examples/select-examples/films.tsx
index 8d61095cbe..e91aaad97c 100644
--- a/packages/docs-app/src/examples/select-examples/films.tsx
+++ b/packages/docs-app/src/examples/select-examples/films.tsx
@@ -138,6 +138,20 @@ export const renderFilm: ItemRenderer<IFilm> = (film, { handleClick, modifiers,
     );
 };
 
+export const renderCreateFilmOption = (
+    query: string,
+    active: boolean,
+    handleClick: React.MouseEventHandler<HTMLElement>,
+) => (
+    <MenuItem
+        icon="add"
+        text={`Create "${query}"`}
+        active={active}
+        onClick={handleClick}
+        shouldDismissPopover={false}
+    />
+);
+
 export const filterFilm: ItemPredicate<IFilm> = (query, film) => {
     return `${film.rank}. ${film.title.toLowerCase()} ${film.year}`.indexOf(query.toLowerCase()) >= 0;
 };
diff --git a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
index 57c746b915..7724f0a9e7 100644
--- a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
@@ -9,17 +9,17 @@ import * as React from "react";
 import { Button, H5, Intent, ITagProps, MenuItem, Switch } from "@blueprintjs/core";
 import { Example, IExampleProps } from "@blueprintjs/docs-theme";
 import { ItemRenderer, MultiSelect } from "@blueprintjs/select";
-import { createFilm, filmSelectProps, IFilm, TOP_100_FILMS } from "./films";
+import { createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
 
 const FilmMultiSelect = MultiSelect.ofType<IFilm>();
 
 const INTENTS = [Intent.NONE, Intent.PRIMARY, Intent.SUCCESS, Intent.DANGER, Intent.WARNING];
 
 export interface IMultiSelectExampleState {
+    allowCreate: boolean;
     films: IFilm[];
     hasInitialContent: boolean;
     intent: boolean;
-    allowCreate: boolean;
     openOnKeyDown: boolean;
     popoverMinimal: boolean;
     resetOnSelect: boolean;
@@ -38,16 +38,16 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
         tagMinimal: false,
     };
 
+    private handleAllowCreateChange = this.handleSwitchChange("allowCreate");
     private handleKeyDownChange = this.handleSwitchChange("openOnKeyDown");
     private handleResetChange = this.handleSwitchChange("resetOnSelect");
     private handlePopoverMinimalChange = this.handleSwitchChange("popoverMinimal");
     private handleTagMinimalChange = this.handleSwitchChange("tagMinimal");
     private handleIntentChange = this.handleSwitchChange("intent");
     private handleInitialContentChange = this.handleSwitchChange("hasInitialContent");
-    private handleAllowCreateChange = this.handleSwitchChange("allowCreate");
 
     public render() {
-        const { films, hasInitialContent, tagMinimal, popoverMinimal, ...flags } = this.state;
+        const { allowCreate, films, hasInitialContent, tagMinimal, popoverMinimal, ...flags } = this.state;
         const getTagProps = (_value: string, index: number): ITagProps => ({
             intent: this.state.intent ? INTENTS[index % INTENTS.length] : Intent.NONE,
             minimal: tagMinimal,
@@ -59,8 +59,8 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
             // explicit undefined (not null) for default behavior (show full list)
             undefined
         );
-        const maybeCreateNewItemFromQuery = this.state.allowCreate ? createFilm : undefined;
-        const maybeCreateNewItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
+        const maybeCreateNewItemFromQuery = allowCreate ? createFilm : undefined;
+        const maybeCreateNewItemRenderer = allowCreate ? renderCreateFilmOption : null;
 
         const clearButton = films.length > 0 ? <Button icon="cross" minimal={true} onClick={this.handleClear} /> : null;
 
@@ -69,6 +69,8 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
                 <FilmMultiSelect
                     {...filmSelectProps}
                     {...flags}
+                    createNewItemFromQuery={maybeCreateNewItemFromQuery}
+                    createNewItemRenderer={maybeCreateNewItemRenderer}
                     initialContent={initialContent}
                     itemRenderer={this.renderFilm}
                     noResults={<MenuItem disabled={true} text="No results." />}
@@ -77,8 +79,6 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
                     tagRenderer={this.renderTag}
                     tagInputProps={{ tagProps: getTagProps, onRemove: this.handleTagRemove, rightElement: clearButton }}
                     selectedItems={this.state.films}
-                    createNewItemFromQuery={maybeCreateNewItemFromQuery}
-                    createNewItemRenderer={maybeCreateNewItemRenderer}
                 />
             </Example>
         );
@@ -149,20 +149,6 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
         );
     };
 
-    private renderCreateFilmOption = (
-        query: string,
-        active: boolean,
-        handleClick: React.MouseEventHandler<HTMLElement>,
-    ) => (
-        <MenuItem
-            icon="add"
-            text={`Create "${query}"`}
-            active={active}
-            onClick={handleClick}
-            shouldDismissPopover={false}
-        />
-    );
-
     private handleTagRemove = (_tag: string, index: number) => {
         this.deselectFilm(index);
     };
diff --git a/packages/docs-app/src/examples/select-examples/omnibarExample.tsx b/packages/docs-app/src/examples/select-examples/omnibarExample.tsx
index 828144e87e..cb78cc3614 100644
--- a/packages/docs-app/src/examples/select-examples/omnibarExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/omnibarExample.tsx
@@ -20,11 +20,12 @@ import {
 } from "@blueprintjs/core";
 import { Example, handleBooleanChange, IExampleProps } from "@blueprintjs/docs-theme";
 import { Omnibar } from "@blueprintjs/select";
-import { filmSelectProps, IFilm } from "./films";
+import { createFilm, filmSelectProps, IFilm, renderCreateFilmOption } from "./films";
 
 const FilmOmnibar = Omnibar.ofType<IFilm>();
 
 export interface IOmnibarExampleState {
+    allowCreate: boolean;
     isOpen: boolean;
     resetOnSelect: boolean;
 }
@@ -32,10 +33,12 @@ export interface IOmnibarExampleState {
 @HotkeysTarget
 export class OmnibarExample extends React.PureComponent<IExampleProps, IOmnibarExampleState> {
     public state: IOmnibarExampleState = {
+        allowCreate: false,
         isOpen: false,
         resetOnSelect: true,
     };
 
+    private handleAllowCreateChange = handleBooleanChange(allowCreate => this.setState({ allowCreate }));
     private handleResetChange = handleBooleanChange(resetOnSelect => this.setState({ resetOnSelect }));
 
     private toaster: Toaster;
@@ -59,15 +62,13 @@ export class OmnibarExample extends React.PureComponent<IExampleProps, IOmnibarE
     }
 
     public render() {
-        const options = (
-            <>
-                <H5>Props</H5>
-                <Switch label="Reset on select" checked={this.state.resetOnSelect} onChange={this.handleResetChange} />
-            </>
-        );
+        const { allowCreate } = this.state;
+
+        const maybeCreateNewItemFromQuery = allowCreate ? createFilm : undefined;
+        const maybeCreateNewItemRenderer = allowCreate ? renderCreateFilmOption : null;
 
         return (
-            <Example options={options} {...this.props}>
+            <Example options={this.renderOptions()} {...this.props}>
                 <span>
                     <Button text="Click to show Omnibar" onClick={this.handleClick} />
                     {" or press "}
@@ -77,6 +78,8 @@ export class OmnibarExample extends React.PureComponent<IExampleProps, IOmnibarE
                 <FilmOmnibar
                     {...filmSelectProps}
                     {...this.state}
+                    createNewItemFromQuery={maybeCreateNewItemFromQuery}
+                    createNewItemRenderer={maybeCreateNewItemRenderer}
                     noResults={<MenuItem disabled={true} text="No results." />}
                     onItemSelect={this.handleItemSelect}
                     onClose={this.handleClose}
@@ -86,6 +89,20 @@ export class OmnibarExample extends React.PureComponent<IExampleProps, IOmnibarE
         );
     }
 
+    protected renderOptions() {
+        return (
+            <>
+                <H5>Props</H5>
+                <Switch label="Reset on select" checked={this.state.resetOnSelect} onChange={this.handleResetChange} />
+                <Switch
+                    label="Allow creating new films"
+                    checked={this.state.allowCreate}
+                    onChange={this.handleAllowCreateChange}
+                />
+            </>
+        );
+    }
+
     private handleClick = (_event: React.MouseEvent<HTMLElement>) => {
         this.setState({ isOpen: true });
     };
diff --git a/packages/docs-app/src/examples/select-examples/selectExample.tsx b/packages/docs-app/src/examples/select-examples/selectExample.tsx
index 51f121f642..6836fe4942 100644
--- a/packages/docs-app/src/examples/select-examples/selectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/selectExample.tsx
@@ -9,7 +9,7 @@ import * as React from "react";
 import { Button, H5, MenuItem, Switch } from "@blueprintjs/core";
 import { Example, IExampleProps } from "@blueprintjs/docs-theme";
 import { Select } from "@blueprintjs/select";
-import { createFilm, filmSelectProps, IFilm, TOP_100_FILMS } from "./films";
+import { createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
 
 const FilmSelect = Select.ofType<IFilm>();
 
@@ -51,15 +51,15 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
     private handleResetOnSelectChange = this.handleSwitchChange("resetOnSelect");
 
     public render() {
-        const { disabled, disableItems, film, minimal, ...flags } = this.state;
+        const { allowCreate, disabled, disableItems, film, minimal, ...flags } = this.state;
 
         const initialContent = this.state.hasInitialContent ? (
             <MenuItem disabled={true} text={`${TOP_100_FILMS.length} items loaded.`} />
         ) : (
             undefined
         );
-        const maybeCreateNewItemFromQuery = this.state.allowCreate ? createFilm : undefined;
-        const maybeCreateNewItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
+        const maybeCreateNewItemFromQuery = allowCreate ? createFilm : undefined;
+        const maybeCreateNewItemRenderer = allowCreate ? renderCreateFilmOption : null;
 
         return (
             <Example options={this.renderOptions()} {...this.props}>
@@ -132,20 +132,6 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
         );
     }
 
-    private renderCreateFilmOption = (
-        query: string,
-        active: boolean,
-        handleClick: React.MouseEventHandler<HTMLElement>,
-    ) => (
-        <MenuItem
-            icon="add"
-            text={`Create "${query}"`}
-            active={active}
-            onClick={handleClick}
-            shouldDismissPopover={false}
-        />
-    );
-
     private handleValueChange = (film: IFilm) => this.setState({ film });
 
     private handleSwitchChange(prop: keyof ISelectExampleState) {
diff --git a/packages/docs-app/src/examples/select-examples/suggestExample.tsx b/packages/docs-app/src/examples/select-examples/suggestExample.tsx
index 1ac95c9984..281c4b692a 100644
--- a/packages/docs-app/src/examples/select-examples/suggestExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/suggestExample.tsx
@@ -9,11 +9,12 @@ import * as React from "react";
 import { H5, MenuItem, Switch } from "@blueprintjs/core";
 import { Example, IExampleProps } from "@blueprintjs/docs-theme";
 import { Suggest } from "@blueprintjs/select";
-import { filmSelectProps, IFilm, TOP_100_FILMS } from "./films";
+import { createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
 
 const FilmSuggest = Suggest.ofType<IFilm>();
 
 export interface ISuggestExampleState {
+    allowCreate: boolean;
     closeOnSelect: boolean;
     film: IFilm;
     minimal: boolean;
@@ -25,6 +26,7 @@ export interface ISuggestExampleState {
 
 export class SuggestExample extends React.PureComponent<IExampleProps, ISuggestExampleState> {
     public state: ISuggestExampleState = {
+        allowCreate: false,
         closeOnSelect: true,
         film: TOP_100_FILMS[0],
         minimal: true,
@@ -34,6 +36,7 @@ export class SuggestExample extends React.PureComponent<IExampleProps, ISuggestE
         resetOnSelect: false,
     };
 
+    private handleAllowCreateChange = this.handleSwitchChange("allowCreate");
     private handleCloseOnSelectChange = this.handleSwitchChange("closeOnSelect");
     private handleOpenOnKeyDownChange = this.handleSwitchChange("openOnKeyDown");
     private handleMinimalChange = this.handleSwitchChange("minimal");
@@ -42,12 +45,18 @@ export class SuggestExample extends React.PureComponent<IExampleProps, ISuggestE
     private handleResetOnSelectChange = this.handleSwitchChange("resetOnSelect");
 
     public render() {
-        const { film, minimal, ...flags } = this.state;
+        const { allowCreate, film, minimal, ...flags } = this.state;
+
+        const maybeCreateNewItemFromQuery = allowCreate ? createFilm : undefined;
+        const maybeCreateNewItemRenderer = allowCreate ? renderCreateFilmOption : null;
+
         return (
             <Example options={this.renderOptions()} {...this.props}>
                 <FilmSuggest
                     {...filmSelectProps}
                     {...flags}
+                    createNewItemFromQuery={maybeCreateNewItemFromQuery}
+                    createNewItemRenderer={maybeCreateNewItemRenderer}
                     inputValueRenderer={this.renderInputValue}
                     noResults={<MenuItem disabled={true} text="No results." />}
                     onItemSelect={this.handleValueChange}
@@ -86,6 +95,11 @@ export class SuggestExample extends React.PureComponent<IExampleProps, ISuggestE
                     checked={this.state.resetOnSelect}
                     onChange={this.handleResetOnSelectChange}
                 />
+                <Switch
+                    label="Allow creating new items"
+                    checked={this.state.allowCreate}
+                    onChange={this.handleAllowCreateChange}
+                />
                 <H5>Popover props</H5>
                 <Switch
                     label="Minimal popover style"

From f86db4833b03e727c4d3d0575bda412fdc9e0527 Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Tue, 26 Feb 2019 13:23:25 -0800
Subject: [PATCH 18/30] Update tests

---
 packages/select/test/queryListTests.tsx       | 21 ++-------
 .../select/test/renderFilteredItemsTests.tsx  |  7 +--
 packages/select/test/selectComponentSuite.tsx | 45 +++++++------------
 3 files changed, 23 insertions(+), 50 deletions(-)

diff --git a/packages/select/test/queryListTests.tsx b/packages/select/test/queryListTests.tsx
index f6ab7049c9..f4e38c72d9 100644
--- a/packages/select/test/queryListTests.tsx
+++ b/packages/select/test/queryListTests.tsx
@@ -9,7 +9,7 @@ import * as React from "react";
 import * as sinon from "sinon";
 
 // this is an awkward import across the monorepo, but we'd rather not introduce a cyclical dependency or create another package
-import { IQueryListProps, QueryListActiveItemType } from "@blueprintjs/select";
+import { IQueryListProps } from "@blueprintjs/select";
 import { IFilm, renderFilm, TOP_100_FILMS } from "../../docs-app/src/examples/select-examples/films";
 import {
     getActiveItem,
@@ -94,14 +94,7 @@ describe("<QueryList>", () => {
 
         it("ensure onActiveItemChange is not called with undefined and empty list", () => {
             const myItem = { title: "Toy Story 3", year: 2010, rank: 1 };
-            const filmQueryList = mount(
-                <FilmQueryList
-                    {...testProps}
-                    items={[myItem]}
-                    activeItem={{ type: QueryListActiveItemType.ITEM, item: myItem }}
-                    query=""
-                />,
-            );
+            const filmQueryList = mount(<FilmQueryList {...testProps} items={[myItem]} activeItem={myItem} query="" />);
             filmQueryList.setState({ query: "query" });
             filmQueryList.setState({ activeItem: undefined });
             assert.equal(testProps.onActiveItemChange.callCount, 0);
@@ -111,10 +104,7 @@ describe("<QueryList>", () => {
             const myItem = { title: "Toy Story 3", year: 2010, rank: 1 };
             const props: IQueryListProps<IFilm> = {
                 ...testProps,
-                activeItem: {
-                    item: myItem,
-                    type: QueryListActiveItemType.ITEM,
-                },
+                activeItem: myItem,
                 items: [myItem],
                 query: "",
             };
@@ -159,10 +149,7 @@ describe("<QueryList>", () => {
             const props: IQueryListProps<IFilm> = {
                 ...testProps,
                 // List is not filtered, and item at index 11 is explicitly chosen as activeItem
-                activeItem: {
-                    item: TOP_100_FILMS[11],
-                    type: QueryListActiveItemType.ITEM,
-                },
+                activeItem: TOP_100_FILMS[11],
             };
             const filmQueryList: FilmQueryListWrapper = mount(<FilmQueryList {...props} />);
             assert.isNotNull(filmQueryList.state().activeItem);
diff --git a/packages/select/test/renderFilteredItemsTests.tsx b/packages/select/test/renderFilteredItemsTests.tsx
index 00d5a21cf8..ca2b27fead 100644
--- a/packages/select/test/renderFilteredItemsTests.tsx
+++ b/packages/select/test/renderFilteredItemsTests.tsx
@@ -7,14 +7,11 @@
 import { assert } from "chai";
 import React from "react";
 import sinon from "sinon";
-import { IItemListRendererProps, QueryListActiveItemType, renderFilteredItems } from "../src";
+import { IItemListRendererProps, renderFilteredItems } from "../src";
 
 describe("renderFilteredItems()", () => {
     const PROPS: IItemListRendererProps<string> = {
-        activeItem: {
-            item: "one",
-            type: QueryListActiveItemType.ITEM,
-        },
+        activeItem: "one",
         filteredItems: ["one"],
         items: ["one", "two", "three"],
         itemsParentRef: sinon.stub(),
diff --git a/packages/select/test/selectComponentSuite.tsx b/packages/select/test/selectComponentSuite.tsx
index 0143ca10e4..f3797ffa5d 100644
--- a/packages/select/test/selectComponentSuite.tsx
+++ b/packages/select/test/selectComponentSuite.tsx
@@ -10,7 +10,8 @@ import { ReactWrapper } from "enzyme";
 import * as React from "react";
 import * as sinon from "sinon";
 import { filterFilm, IFilm, renderFilm, TOP_100_FILMS } from "../../docs-app/src/examples/select-examples/films";
-import { IListItemsProps, IQueryListActiveItem, QueryListActiveItemType } from "../src/index";
+import { isCreateNewItem } from "../lib/esm";
+import { IListItemsProps } from "../src/index";
 
 export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
     render: (props: IListItemsProps<IFilm>) => ReactWrapper<P, S>,
@@ -61,7 +62,7 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
                 .at(4)
                 .simulate("click");
             assert.strictEqual(testProps.onItemSelect.args[0][0].rank, 6, "onItemSelect");
-            assert.strictEqual(testProps.onActiveItemChange.args[0][0].item.rank, 6, "onActiveItemChange");
+            assert.strictEqual(testProps.onActiveItemChange.args[0][0].rank, 6, "onActiveItemChange");
         });
 
         it("clicking item resets state when resetOnSelect=true", () => {
@@ -69,7 +70,7 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             findItems(wrapper)
                 .at(3)
                 .simulate("click");
-            const ranks = testProps.onActiveItemChange.args.map(args => (args[0].item as IFilm).rank);
+            const ranks = testProps.onActiveItemChange.args.map(args => (args[0] as IFilm).rank);
             // clicking changes to 5, then resets to 1
             assert.deepEqual(ranks, [5, 1]);
             assert.strictEqual(testProps.onQueryChange.lastCall.args[0], "");
@@ -86,14 +87,14 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             const wrapper = render({ ...testProps, query: "19", resetOnQuery: true });
             // more specific query picks the first item.
             wrapper.setProps({ query: "199" });
-            assert.strictEqual(testProps.onActiveItemChange.lastCall.args[0].item.rank, 1);
+            assert.strictEqual(testProps.onActiveItemChange.lastCall.args[0].rank, 1);
         });
 
         it("querying resets active item if it does not match", () => {
             const wrapper = render({ ...testProps, query: "19", resetOnQuery: false });
             // a different query altogether invalidates the previous active item, so QL chooses the first.
             wrapper.setProps({ query: "Forrest" });
-            assert.strictEqual(testProps.onActiveItemChange.lastCall.args[0].item.title, "Forrest Gump");
+            assert.strictEqual(testProps.onActiveItemChange.lastCall.args[0].title, "Forrest Gump");
         });
     });
 
@@ -103,19 +104,19 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             findInput(wrapper)
                 .simulate("keydown", { keyCode: Keys.ARROW_DOWN })
                 .simulate("keydown", { keyCode: Keys.ARROW_DOWN });
-            assert.equal((testProps.onActiveItemChange.lastCall.args[0].item as IFilm).rank, 3);
+            assert.equal((testProps.onActiveItemChange.lastCall.args[0] as IFilm).rank, 3);
         });
 
         it("arrow up invokes onActiveItemChange with previous filtered item", () => {
             const wrapper = render(testProps);
             findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_UP });
-            assert.equal((testProps.onActiveItemChange.lastCall.args[0].item as IFilm).rank, 20);
+            assert.equal((testProps.onActiveItemChange.lastCall.args[0] as IFilm).rank, 20);
         });
 
         it("enter invokes onItemSelect with active item", () => {
             const wrapper = render(testProps);
             findInput(wrapper).simulate("keyup", { keyCode: Keys.ENTER });
-            const activeItem = testProps.onActiveItemChange.lastCall.args[0].item;
+            const activeItem = testProps.onActiveItemChange.lastCall.args[0];
             assert.equal(testProps.onItemSelect.lastCall.args[0], activeItem);
         });
     });
@@ -163,40 +164,28 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             assert.equal(testCreateProps.createNewItemFromQuery.args[0][0], "non-existent film name");
         });
 
-        it("when create item is rendered, arrow down invokes onActiveItemChange with CREATE", () => {
+        it("when create item is rendered, arrow down invokes onActiveItemChange with an `ICreateNewItem`", () => {
             const wrapper = render({
                 ...testCreateProps,
                 query: TOP_100_FILMS[0].title,
             });
             findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_DOWN });
-            assert.equal(
-                (testProps.onActiveItemChange.lastCall.args[0] as IQueryListActiveItem<IFilm>).type,
-                QueryListActiveItemType.CREATE,
-            );
+            assert.isTrue(isCreateNewItem(testProps.onActiveItemChange.lastCall.args[0]));
             findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_DOWN });
-            assert.equal(
-                (testProps.onActiveItemChange.lastCall.args[0] as IQueryListActiveItem<IFilm>).type,
-                QueryListActiveItemType.ITEM,
-            );
-            assert.equal((testProps.onActiveItemChange.lastCall.args[0].item as IFilm).rank, TOP_100_FILMS[0].rank);
+            assert.isFalse(isCreateNewItem(testProps.onActiveItemChange.lastCall.args[0]));
+            assert.equal((testProps.onActiveItemChange.lastCall.args[0] as IFilm).rank, TOP_100_FILMS[0].rank);
         });
 
-        it("when create item is rendered, arrow up invokes onActiveItemChange with CREATE", () => {
+        it("when create item is rendered, arrow up invokes onActiveItemChange with an `ICreateNewItem`", () => {
             const wrapper = render({
                 ...testCreateProps,
                 query: TOP_100_FILMS[0].title,
             });
             findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_UP });
-            assert.equal(
-                (testProps.onActiveItemChange.lastCall.args[0] as IQueryListActiveItem<IFilm>).type,
-                QueryListActiveItemType.CREATE,
-            );
+            assert.isTrue(isCreateNewItem(testProps.onActiveItemChange.lastCall.args[0]));
             findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_UP });
-            assert.equal(
-                (testProps.onActiveItemChange.lastCall.args[0] as IQueryListActiveItem<IFilm>).type,
-                QueryListActiveItemType.ITEM,
-            );
-            assert.equal((testProps.onActiveItemChange.lastCall.args[0].item as IFilm).rank, TOP_100_FILMS[0].rank);
+            assert.isFalse(isCreateNewItem(testProps.onActiveItemChange.lastCall.args[0]));
+            assert.equal((testProps.onActiveItemChange.lastCall.args[0] as IFilm).rank, TOP_100_FILMS[0].rank);
         });
     });
 }

From dfbcedd3548829806245b2616d8cc52eb955d86d Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Tue, 26 Feb 2019 13:23:35 -0800
Subject: [PATCH 19/30] Update function comments

---
 packages/select/src/common/listItemsUtils.ts | 29 +++++++++++++-------
 1 file changed, 19 insertions(+), 10 deletions(-)

diff --git a/packages/select/src/common/listItemsUtils.ts b/packages/select/src/common/listItemsUtils.ts
index 67d1e3ea7f..5bbe8f26da 100644
--- a/packages/select/src/common/listItemsUtils.ts
+++ b/packages/select/src/common/listItemsUtils.ts
@@ -4,24 +4,33 @@
  * Licensed under the terms of the LICENSE file distributed with this project.
  */
 
-const CREATE_NEW_ITEM_BRAND = "blueprint-create-item";
-
-/** The reserved type of the "Create Item" option in item lists. */
+/**
+ * The reserved type of the "Create Item" option in item lists. This is intended
+ * not to conflict with any custom item type `T` that might be used in  item
+ * list.
+ */
 export interface ICreateNewItem {
-    __blueprintBrand: typeof CREATE_NEW_ITEM_BRAND;
+    __blueprintBrand: "blueprint-create-item";
 }
 
+/** Returns an instance of a "Create Item" object. */
 export function getCreateNewItem(): ICreateNewItem {
-    return { __blueprintBrand: CREATE_NEW_ITEM_BRAND };
+    return { __blueprintBrand: "blueprint-create-item" };
 }
 
+/**
+ * Type guard returning `true` if the provided item (e.g. the current
+ * `activeItem`) is a "Create Item" option.
+ */
 export function isCreateNewItem<T>(item: T | ICreateNewItem | null | undefined): item is ICreateNewItem {
-    return item != null && (item as ICreateNewItem).__blueprintBrand === CREATE_NEW_ITEM_BRAND;
+    return item != null && (item as ICreateNewItem).__blueprintBrand === "blueprint-create-item";
 }
 
+/**
+ * Returns the type of the the current active item. This will be a no-op unless
+ * the `activeItem` is `undefined` or a "Create Item" option, in which case
+ * `null` will be returned instead.
+ */
 export function getActiveItem<T>(activeItem: T | ICreateNewItem | null | undefined): T | null {
-    if (activeItem != null && !isCreateNewItem(activeItem)) {
-        return activeItem;
-    }
-    return null;
+    return activeItem == null || isCreateNewItem(activeItem) ? null : activeItem;
 }

From 16b9fe57796e184af98a0c56fe662b9708d86242 Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Tue, 26 Feb 2019 13:36:31 -0800
Subject: [PATCH 20/30] Avoid breaking the API, fix tests

---
 packages/select/src/common/listItemsProps.ts    | 17 +++++++++++++----
 .../src/components/query-list/queryList.tsx     |  7 ++++++-
 packages/select/test/selectComponentSuite.tsx   | 13 +++++++------
 3 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/packages/select/src/common/listItemsProps.ts b/packages/select/src/common/listItemsProps.ts
index c9acd52ff6..06b460f182 100644
--- a/packages/select/src/common/listItemsProps.ts
+++ b/packages/select/src/common/listItemsProps.ts
@@ -108,11 +108,20 @@ export interface IListItemsProps<T> extends IProps {
     noResults?: React.ReactNode;
 
     /**
-     * Invoked when user interaction should change the active item: arrow keys move it up/down
-     * in the list, selecting an item makes it active, and changing the query may reset it to
-     * the first item in the list if it no longer matches the filter.
+     * Invoked when user interaction should change the active item: arrow keys
+     * move it up/down in the list, selecting an item makes it active, and
+     * changing the query may reset it to the first item in the list if it no
+     * longer matches the filter.
+     *
+     * If the "Create Item" option is displayed and currently active, then
+     * `isCreateNewItem` will be `true` and `activeItem` will be `null`. In this
+     * case, you should provide a valid "Create Item" object to the `activeItem`
+     * _prop_ in order for the "Create Item" option to appear as active.
+     *
+     * __Note:__ You can instantiate a "Create Item" object using the
+     * `getCreateNewItem()` utility exported from this package.
      */
-    onActiveItemChange?: (activeItem: T | ICreateNewItem | null) => void;
+    onActiveItemChange?: (activeItem: T | null, isCreateNewItem: boolean) => void;
 
     /**
      * Callback invoked when an item from the list is selected,
diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index e9b0e1ecb3..45faf6785f 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -388,7 +388,12 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
             this.shouldCheckActiveItemInViewport = true;
             this.setState({ activeItem });
         }
-        Utils.safeInvoke(this.props.onActiveItemChange, activeItem);
+
+        if (isCreateNewItem(activeItem)) {
+            Utils.safeInvoke(this.props.onActiveItemChange, null, true);
+        } else {
+            Utils.safeInvoke(this.props.onActiveItemChange, activeItem, false);
+        }
     }
 
     private isCreateItemRendered(): boolean {
diff --git a/packages/select/test/selectComponentSuite.tsx b/packages/select/test/selectComponentSuite.tsx
index f3797ffa5d..c2b12ee2aa 100644
--- a/packages/select/test/selectComponentSuite.tsx
+++ b/packages/select/test/selectComponentSuite.tsx
@@ -10,7 +10,6 @@ import { ReactWrapper } from "enzyme";
 import * as React from "react";
 import * as sinon from "sinon";
 import { filterFilm, IFilm, renderFilm, TOP_100_FILMS } from "../../docs-app/src/examples/select-examples/films";
-import { isCreateNewItem } from "../lib/esm";
 import { IListItemsProps } from "../src/index";
 
 export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
@@ -164,16 +163,17 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             assert.equal(testCreateProps.createNewItemFromQuery.args[0][0], "non-existent film name");
         });
 
-        it("when create item is rendered, arrow down invokes onActiveItemChange with an `ICreateNewItem`", () => {
+        it("when create item is rendered, arrow down invokes onActiveItemChange with activeItem=null and isCreateNewItem=true", () => {
             const wrapper = render({
                 ...testCreateProps,
                 query: TOP_100_FILMS[0].title,
             });
             findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_DOWN });
-            assert.isTrue(isCreateNewItem(testProps.onActiveItemChange.lastCall.args[0]));
+            assert.equal(testProps.onActiveItemChange.lastCall.args[0], null);
+            assert.equal(testProps.onActiveItemChange.lastCall.args[1], true);
             findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_DOWN });
-            assert.isFalse(isCreateNewItem(testProps.onActiveItemChange.lastCall.args[0]));
             assert.equal((testProps.onActiveItemChange.lastCall.args[0] as IFilm).rank, TOP_100_FILMS[0].rank);
+            assert.equal(testProps.onActiveItemChange.lastCall.args[1], false);
         });
 
         it("when create item is rendered, arrow up invokes onActiveItemChange with an `ICreateNewItem`", () => {
@@ -182,10 +182,11 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
                 query: TOP_100_FILMS[0].title,
             });
             findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_UP });
-            assert.isTrue(isCreateNewItem(testProps.onActiveItemChange.lastCall.args[0]));
+            assert.equal(testProps.onActiveItemChange.lastCall.args[0], null);
+            assert.equal(testProps.onActiveItemChange.lastCall.args[1], true);
             findInput(wrapper).simulate("keydown", { keyCode: Keys.ARROW_UP });
-            assert.isFalse(isCreateNewItem(testProps.onActiveItemChange.lastCall.args[0]));
             assert.equal((testProps.onActiveItemChange.lastCall.args[0] as IFilm).rank, TOP_100_FILMS[0].rank);
+            assert.equal(testProps.onActiveItemChange.lastCall.args[1], false);
         });
     });
 }

From d1fd4fed13d135112edea9d5aa2428da861199b5 Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Tue, 26 Feb 2019 15:43:17 -0800
Subject: [PATCH 21/30] Update docs

---
 .../src/components/select/select-component.md | 86 +++++++++++++++++--
 1 file changed, 80 insertions(+), 6 deletions(-)

diff --git a/packages/select/src/components/select/select-component.md b/packages/select/src/components/select/select-component.md
index c701d13308..05b6b549dd 100644
--- a/packages/select/src/components/select/select-component.md
+++ b/packages/select/src/components/select/select-component.md
@@ -82,11 +82,29 @@ This controlled usage allows you to implement all sorts of advanced behavior on
 top of the basic `Select` interactions, such as windowed filtering for large
 data sets.
 
+<div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
+    To control the active item when a "Create Item" option is present, See [Controlling the active item](#select/select-component.controlling-the-active-item) in the "Creating new items" section below.
+</div>
+
 @## Creating new items
 
-Use the `createNewItemFromQuery` prop to allow `Select<T>` to create new items. `createNewItemFromQuery` specifies how to turn a
-user-entered query string into an item of type `<T>` that `Select` understands. You should also provide the `createNewItemRenderer`
-prop to render a custom `MenuItem` to indicate that users can create new items.
+If you wish, you can allow users to select a brand new item that doesn't appear
+in the list, based on the current query string. Use `createNewItemFromQuery` and
+`createNewItemRenderer` to enable this:
+- `createNewItemFromQuery`: Specifies how to convert a user-entered query string
+into an item of type `<T>` that `Select` understands.
+- `createNewItemRenderer`: Renders a custom "Create Item" element that will be
+shown at the bottom of the list. When selected via click or `Enter`, this element
+will invoke `onItemSelect` with the item returned from `createNewItemFromQuery`.
+
+<div class="@ns-callout @ns-intent-warning @ns-icon-info-sign">
+    <h4 class="@ns-heading">Avoiding type conflicts</h4>
+    The "Create Item" option is represented by the reserved type `ICreateNewItem`
+    exported from this package. It is exceedingly unlikely but technically possible
+    for your custom type `<T>` to conflict with this type. If your type conflicts,
+    you may see unexpected behavior; to resolve, consider changing the schema for
+    your items.
+</div>
 
 ```tsx
 function createFilm(title: string): IFilm {
@@ -97,7 +115,11 @@ function createFilm(title: string): IFilm {
     };
 }
 
-function renderCreateFilmOption(query: string, active: boolean, handleClick: React.MouseEventHandler<HTMLElement>) {
+function renderCreateFilmOption(
+    query: string,
+    active: boolean,
+    handleClick: React.MouseEventHandler<HTMLElement>,
+) {
     return (
         <MenuItem
             icon="add"
@@ -111,18 +133,70 @@ function renderCreateFilmOption(query: string, active: boolean, handleClick: Rea
 
 ReactDOM.render(
     <FilmSelect
+        createNewItemFromQuery={createFilm}
+        createNewItemRenderer={renderCreateFilmOption}
         items={Films.items}
         itemPredicate={Films.itemPredicate}
         itemRenderer={Films.itemRenderer}
         noResults={<MenuItem disabled={true} text="No results." />}
-        createNewItemFromQuery={createFilm}
-        createNewItemRenderer={renderCreateFilmOption}
         onItemSelect={...}
     />,
     document.querySelector("#root")
 );
 ```
 
+@### Controlling the active item
+
+Controlling the active item is slightly more involved when the "Create Item"
+option is present. At a high level, the process works the same way as before:
+control the `activeItem` value and listen for updates via `onActiveItemChange`.
+However, some special handling is required.
+
+When the "Create Item" option is present, the callback will emit
+`activeItem=null` and `isCreateNewItem=true`:
+
+```tsx
+onActiveItemChange(null, true);
+```
+
+You can then make the "Create Item" option active by passing the result of
+`getCreateNewItem()` to the `activeItem` prop (the `getCreateNewItem` function
+is exported from this package):
+
+```tsx
+activeItem={isCreateNewItemActive ? getCreateNewItem() : activeItem}
+```
+
+Altogether, the code might look something like this:
+
+```tsx
+const currentActiveItem: Film | ICreateNewItem | null;
+const isCreateNewItemActive: Film | ICreateNewItem | null;
+
+function handleActiveItemChange(
+    activeItem: Film | ICreateNewItem | null,
+    isCreateNewItem: boolean,
+) {
+    currentActiveItem = activeItem;
+    isCreateNewItemActive = isCreateNewItem;
+}
+
+function getActiveItem() {
+    return isCreateNewItemActive ? getCreateNewItem() : currentActiveItem;
+}
+
+ReactDOM.render(
+    <FilmSelect
+        {...} // Other required props (see previous examples).
+        activeItem={getActiveItem()}
+        createNewItemFromQuery={...}
+        createNewItemRenderer={...}
+        onActiveItemChange={handleActiveItemChange}
+    />,
+    document.querySelector("#root")
+);
+```
+
 @## JavaScript API
 
 @interface ISelectProps

From 2925fec20b5364cf0be187cd54efa5626221c043 Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Tue, 26 Feb 2019 15:47:17 -0800
Subject: [PATCH 22/30] Make the brand even more specific, and add a
 deep-comparison check

---
 packages/select/src/common/listItemsUtils.ts | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/packages/select/src/common/listItemsUtils.ts b/packages/select/src/common/listItemsUtils.ts
index 5bbe8f26da..c00de3e850 100644
--- a/packages/select/src/common/listItemsUtils.ts
+++ b/packages/select/src/common/listItemsUtils.ts
@@ -10,12 +10,12 @@
  * list.
  */
 export interface ICreateNewItem {
-    __blueprintBrand: "blueprint-create-item";
+    __blueprintCreateNewItemBrand: "blueprint-create-new-item";
 }
 
 /** Returns an instance of a "Create Item" object. */
 export function getCreateNewItem(): ICreateNewItem {
-    return { __blueprintBrand: "blueprint-create-item" };
+    return { __blueprintCreateNewItemBrand: "blueprint-create-new-item" };
 }
 
 /**
@@ -23,7 +23,17 @@ export function getCreateNewItem(): ICreateNewItem {
  * `activeItem`) is a "Create Item" option.
  */
 export function isCreateNewItem<T>(item: T | ICreateNewItem | null | undefined): item is ICreateNewItem {
-    return item != null && (item as ICreateNewItem).__blueprintBrand === "blueprint-create-item";
+    if (item == null) {
+        return false;
+    }
+
+    // see if the provided item exactly matches the `ICreateNewItem` object,
+    // with no superfluous keys.
+    const keys = Object.keys(item);
+    if (keys.length !== 1 || keys[0] !== "__blueprintCreateNewItemBrand") {
+        return false;
+    }
+    return (item as ICreateNewItem).__blueprintCreateNewItemBrand === "blueprint-create-new-item";
 }
 
 /**

From 3e6d62ffb7b33eea3757451c482da1d9c5491980 Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Tue, 26 Feb 2019 15:49:05 -0800
Subject: [PATCH 23/30] Fix unintentional code changes

---
 .../select/src/common/itemListRenderer.ts     |  2 +-
 packages/select/test/queryListTests.tsx       | 21 +++++--------------
 2 files changed, 6 insertions(+), 17 deletions(-)

diff --git a/packages/select/src/common/itemListRenderer.ts b/packages/select/src/common/itemListRenderer.ts
index 07ed04c5c7..79d5083ea5 100644
--- a/packages/select/src/common/itemListRenderer.ts
+++ b/packages/select/src/common/itemListRenderer.ts
@@ -1,5 +1,5 @@
 /*!
- * Copyright 2018 Palantir Technologies, Inc. All rights reserved.
+ * Copyright 2017 Palantir Technologies, Inc. All rights reserved.
  *
  * Licensed under the terms of the LICENSE file distributed with this project.
  */
diff --git a/packages/select/test/queryListTests.tsx b/packages/select/test/queryListTests.tsx
index f4e38c72d9..bff202fe01 100644
--- a/packages/select/test/queryListTests.tsx
+++ b/packages/select/test/queryListTests.tsx
@@ -11,14 +11,7 @@ import * as sinon from "sinon";
 // this is an awkward import across the monorepo, but we'd rather not introduce a cyclical dependency or create another package
 import { IQueryListProps } from "@blueprintjs/select";
 import { IFilm, renderFilm, TOP_100_FILMS } from "../../docs-app/src/examples/select-examples/films";
-import {
-    getActiveItem,
-    IQueryListRendererProps,
-    IQueryListState,
-    ItemListPredicate,
-    ItemListRenderer,
-    QueryList,
-} from "../src/index";
+import { IQueryListRendererProps, IQueryListState, ItemListPredicate, ItemListRenderer, QueryList } from "../src/index";
 
 type FilmQueryListWrapper = ReactWrapper<IQueryListProps<IFilm>, IQueryListState<IFilm>>;
 
@@ -120,14 +113,12 @@ describe("<QueryList>", () => {
                 query: "abc",
             };
             const filmQueryList: FilmQueryListWrapper = mount(<FilmQueryList {...props} />);
-            assert.isNotNull(filmQueryList.state().activeItem);
-            assert.deepEqual(getActiveItem(filmQueryList.state().activeItem), TOP_100_FILMS[0]);
+            assert.deepEqual(filmQueryList.state().activeItem, TOP_100_FILMS[0]);
             filmQueryList.setProps({
                 items: [TOP_100_FILMS[1]],
                 query: "123",
             });
-            assert.isNotNull(filmQueryList.state().activeItem);
-            assert.deepEqual(getActiveItem(filmQueryList.state().activeItem), TOP_100_FILMS[1]);
+            assert.deepEqual(filmQueryList.state().activeItem, TOP_100_FILMS[1]);
         });
     });
 
@@ -141,8 +132,7 @@ describe("<QueryList>", () => {
                 query: "123",
             };
             const filmQueryList: FilmQueryListWrapper = mount(<FilmQueryList {...props} />);
-            assert.isNotNull(filmQueryList.state().activeItem);
-            assert(getActiveItem(filmQueryList.state().activeItem) === TOP_100_FILMS[11]);
+            assert(filmQueryList.state().activeItem === TOP_100_FILMS[11]);
         });
 
         it("initializes to controlled activeItem prop (non-null)", () => {
@@ -152,8 +142,7 @@ describe("<QueryList>", () => {
                 activeItem: TOP_100_FILMS[11],
             };
             const filmQueryList: FilmQueryListWrapper = mount(<FilmQueryList {...props} />);
-            assert.isNotNull(filmQueryList.state().activeItem);
-            assert(getActiveItem(filmQueryList.state().activeItem) === TOP_100_FILMS[11]);
+            assert(filmQueryList.state().activeItem === TOP_100_FILMS[11]);
         });
 
         it("initializes to controlled activeItem prop (null)", () => {

From 015e06fed0f788eea36582c05c0bf717344d0fcb Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Tue, 26 Feb 2019 16:08:38 -0800
Subject: [PATCH 24/30] Fix lint in unrelated files?

---
 packages/docs-app/src/components/resources.tsx | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/docs-app/src/components/resources.tsx b/packages/docs-app/src/components/resources.tsx
index bd7b09d753..0ee6f284b1 100644
--- a/packages/docs-app/src/components/resources.tsx
+++ b/packages/docs-app/src/components/resources.tsx
@@ -18,11 +18,15 @@ const RESOURCES: IResourceProps[] = [
 export const Resources: React.SFC = () => (
     <>
         <div className="blueprint-resources">
-            {RESOURCES.map(resource => <ResourceCard key={resource.fileName} {...resource} />)}
+            {RESOURCES.map(resource => (
+                <ResourceCard key={resource.fileName} {...resource} />
+            ))}
         </div>
         <Callout title="Missing fonts?" intent="warning">
             Download Apple's San Francisco font directly from the source:{" "}
-            <a href="https://developer.apple.com/fonts/" target="_blank" rel="noopener noreferrer">https://developer.apple.com/fonts/</a>
+            <a href="https://developer.apple.com/fonts/" target="_blank" rel="noopener noreferrer">
+                https://developer.apple.com/fonts/
+            </a>
         </Callout>
     </>
 );

From 6ecdfa080049bdc6669ee60a7cff91ad33fe9f10 Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Wed, 27 Feb 2019 10:52:14 -0800
Subject: [PATCH 25/30] Respond to @adidahiya CR

---
 packages/select/src/common/listItemsProps.ts | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/packages/select/src/common/listItemsProps.ts b/packages/select/src/common/listItemsProps.ts
index 06b460f182..555ebe7580 100644
--- a/packages/select/src/common/listItemsProps.ts
+++ b/packages/select/src/common/listItemsProps.ts
@@ -115,10 +115,11 @@ export interface IListItemsProps<T> extends IProps {
      *
      * If the "Create Item" option is displayed and currently active, then
      * `isCreateNewItem` will be `true` and `activeItem` will be `null`. In this
-     * case, you should provide a valid "Create Item" object to the `activeItem`
-     * _prop_ in order for the "Create Item" option to appear as active.
+     * case, you should provide a valid `ICreateNewItem` object to the
+     * `activeItem` _prop_ in order for the "Create Item" option to appear as
+     * active.
      *
-     * __Note:__ You can instantiate a "Create Item" object using the
+     * __Note:__ You can instantiate a `ICreateNewItem` object using the
      * `getCreateNewItem()` utility exported from this package.
      */
     onActiveItemChange?: (activeItem: T | null, isCreateNewItem: boolean) => void;

From 631b86e90f859d2674d731475dbd000bb2989fad Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Wed, 27 Feb 2019 19:48:02 -0800
Subject: [PATCH 26/30] Fix examples: Add created item to list of items (to
 enable deselection)

---
 .../src/examples/select-examples/films.tsx    |  5 +++
 .../select-examples/multiSelectExample.tsx    | 43 +++++++++++++++++--
 .../select-examples/omnibarExample.tsx        |  3 +-
 .../select-examples/selectExample.tsx         |  3 +-
 .../select-examples/suggestExample.tsx        |  3 +-
 5 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/packages/docs-app/src/examples/select-examples/films.tsx b/packages/docs-app/src/examples/select-examples/films.tsx
index e91aaad97c..14439fbbcc 100644
--- a/packages/docs-app/src/examples/select-examples/films.tsx
+++ b/packages/docs-app/src/examples/select-examples/films.tsx
@@ -204,3 +204,8 @@ export function createFilm(title: string): IFilm {
         year: new Date().getFullYear(),
     };
 }
+
+export function areFilmsEqual(filmA: IFilm, filmB: IFilm) {
+    // Compare only the titles (ignoring case) just for simplicity.
+    return filmA.title.toLowerCase() === filmB.title.toLowerCase();
+}
diff --git a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
index 7724f0a9e7..14a35f3579 100644
--- a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
@@ -9,7 +9,7 @@ import * as React from "react";
 import { Button, H5, Intent, ITagProps, MenuItem, Switch } from "@blueprintjs/core";
 import { Example, IExampleProps } from "@blueprintjs/docs-theme";
 import { ItemRenderer, MultiSelect } from "@blueprintjs/select";
-import { createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
+import { areFilmsEqual, createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
 
 const FilmMultiSelect = MultiSelect.ofType<IFilm>();
 
@@ -17,9 +17,11 @@ const INTENTS = [Intent.NONE, Intent.PRIMARY, Intent.SUCCESS, Intent.DANGER, Int
 
 export interface IMultiSelectExampleState {
     allowCreate: boolean;
+    createdItems: IFilm[];
     films: IFilm[];
     hasInitialContent: boolean;
     intent: boolean;
+    items: IFilm[];
     openOnKeyDown: boolean;
     popoverMinimal: boolean;
     resetOnSelect: boolean;
@@ -29,9 +31,11 @@ export interface IMultiSelectExampleState {
 export class MultiSelectExample extends React.PureComponent<IExampleProps, IMultiSelectExampleState> {
     public state: IMultiSelectExampleState = {
         allowCreate: false,
+        createdItems: [],
         films: [],
         hasInitialContent: false,
         intent: false,
+        items: filmSelectProps.items,
         openOnKeyDown: false,
         popoverMinimal: true,
         resetOnSelect: true,
@@ -73,6 +77,7 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
                     createNewItemRenderer={maybeCreateNewItemRenderer}
                     initialContent={initialContent}
                     itemRenderer={this.renderFilm}
+                    itemsEqual={areFilmsEqual}
                     noResults={<MenuItem disabled={true} text="No results." />}
                     onItemSelect={this.handleFilmSelect}
                     popoverProps={{ minimal: popoverMinimal }}
@@ -162,11 +167,31 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
     }
 
     private selectFilm(film: IFilm) {
-        this.setState({ films: [...this.state.films, film] });
+        const { createdItems, films, items } = this.state;
+        const isNewlyCreatedItem = !this.arrayContainsFilm(items, film);
+        this.setState({
+            createdItems: isNewlyCreatedItem ? this.addFilmToArray(createdItems, film) : 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: !this.arrayContainsFilm(films, film) ? [...films, film] : films,
+            // Add a created film to `items` so that the film can be deselected.
+            items: isNewlyCreatedItem ? this.addFilmToArray(items, film) : items,
+        });
     }
 
     private deselectFilm(index: number) {
-        this.setState({ films: this.state.films.filter((_film, i) => i !== index) });
+        const { createdItems, films, items } = this.state;
+
+        const film = films[index];
+        const wasItemCreatedByUser = this.arrayContainsFilm(createdItems, film);
+
+        // Delete the item if the user manually created it.
+        this.setState({
+            createdItems: wasItemCreatedByUser ? this.deleteFilmFromArray(createdItems, film) : createdItems,
+            films: films.filter((_film, i) => i !== index),
+            items: wasItemCreatedByUser ? this.deleteFilmFromArray(items, film) : items,
+        });
     }
 
     private handleFilmSelect = (film: IFilm) => {
@@ -185,4 +210,16 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
     }
 
     private handleClear = () => this.setState({ films: [] });
+
+    private arrayContainsFilm(films: IFilm[], filmToFind: IFilm): boolean {
+        return films.find(f => f.title === filmToFind.title) !== undefined;
+    }
+
+    private addFilmToArray(films: IFilm[], filmToAdd: IFilm) {
+        return [...films, filmToAdd];
+    }
+
+    private deleteFilmFromArray(films: IFilm[], filmToDelete: IFilm) {
+        return films.filter(film => film !== filmToDelete);
+    }
 }
diff --git a/packages/docs-app/src/examples/select-examples/omnibarExample.tsx b/packages/docs-app/src/examples/select-examples/omnibarExample.tsx
index cb78cc3614..59ba8944ae 100644
--- a/packages/docs-app/src/examples/select-examples/omnibarExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/omnibarExample.tsx
@@ -20,7 +20,7 @@ import {
 } from "@blueprintjs/core";
 import { Example, handleBooleanChange, IExampleProps } from "@blueprintjs/docs-theme";
 import { Omnibar } from "@blueprintjs/select";
-import { createFilm, filmSelectProps, IFilm, renderCreateFilmOption } from "./films";
+import { areFilmsEqual, createFilm, filmSelectProps, IFilm, renderCreateFilmOption } from "./films";
 
 const FilmOmnibar = Omnibar.ofType<IFilm>();
 
@@ -80,6 +80,7 @@ export class OmnibarExample extends React.PureComponent<IExampleProps, IOmnibarE
                     {...this.state}
                     createNewItemFromQuery={maybeCreateNewItemFromQuery}
                     createNewItemRenderer={maybeCreateNewItemRenderer}
+                    itemsEqual={areFilmsEqual}
                     noResults={<MenuItem disabled={true} text="No results." />}
                     onItemSelect={this.handleItemSelect}
                     onClose={this.handleClose}
diff --git a/packages/docs-app/src/examples/select-examples/selectExample.tsx b/packages/docs-app/src/examples/select-examples/selectExample.tsx
index 6836fe4942..f684a7e08a 100644
--- a/packages/docs-app/src/examples/select-examples/selectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/selectExample.tsx
@@ -9,7 +9,7 @@ import * as React from "react";
 import { Button, H5, MenuItem, Switch } from "@blueprintjs/core";
 import { Example, IExampleProps } from "@blueprintjs/docs-theme";
 import { Select } from "@blueprintjs/select";
-import { createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
+import { areFilmsEqual, createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
 
 const FilmSelect = Select.ofType<IFilm>();
 
@@ -70,6 +70,7 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
                     createNewItemRenderer={maybeCreateNewItemRenderer}
                     disabled={disabled}
                     itemDisabled={this.isItemDisabled}
+                    itemsEqual={areFilmsEqual}
                     initialContent={initialContent}
                     noResults={<MenuItem disabled={true} text="No results." />}
                     onItemSelect={this.handleValueChange}
diff --git a/packages/docs-app/src/examples/select-examples/suggestExample.tsx b/packages/docs-app/src/examples/select-examples/suggestExample.tsx
index 281c4b692a..e909caf4bd 100644
--- a/packages/docs-app/src/examples/select-examples/suggestExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/suggestExample.tsx
@@ -9,7 +9,7 @@ import * as React from "react";
 import { H5, MenuItem, Switch } from "@blueprintjs/core";
 import { Example, IExampleProps } from "@blueprintjs/docs-theme";
 import { Suggest } from "@blueprintjs/select";
-import { createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
+import { areFilmsEqual, createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
 
 const FilmSuggest = Suggest.ofType<IFilm>();
 
@@ -58,6 +58,7 @@ export class SuggestExample extends React.PureComponent<IExampleProps, ISuggestE
                     createNewItemFromQuery={maybeCreateNewItemFromQuery}
                     createNewItemRenderer={maybeCreateNewItemRenderer}
                     inputValueRenderer={this.renderInputValue}
+                    itemsEqual={areFilmsEqual}
                     noResults={<MenuItem disabled={true} text="No results." />}
                     onItemSelect={this.handleValueChange}
                     popoverProps={{ minimal }}

From 3e020edf195506ae83d84de39c7f6ea1f3cee2e1 Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Wed, 27 Feb 2019 19:48:34 -0800
Subject: [PATCH 27/30] Hide 'Create item' option if query already appears in
 items

e.g. if the user has already created an item that matches
the current query, or if the query exactly matches an item
from the existing list
---
 .../src/components/query-list/queryList.tsx   | 50 ++++++++++++++++---
 1 file changed, 42 insertions(+), 8 deletions(-)

diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index 45faf6785f..a4910c9bf1 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -45,7 +45,9 @@ export interface IQueryListProps<T> extends IListItemsProps<T> {
  * An object describing how to render a `QueryList`.
  * A `QueryList` `renderer` receives this object as its sole argument.
  */
-export interface IQueryListRendererProps<T> extends IQueryListState<T>, IProps {
+export interface IQueryListRendererProps<T>  // Omit `createNewItem`, because it's used strictly for internal tracking.
+    extends Pick<IQueryListState<T>, "activeItem" | "filteredItems" | "query">,
+        IProps {
     /**
      * Selection handler that should be invoked when a new item has been chosen,
      * perhaps because the user clicked it.
@@ -78,6 +80,14 @@ export interface IQueryListState<T> {
     /** The currently focused item (for keyboard interactions). */
     activeItem: T | ICreateNewItem | null;
 
+    /**
+     * The item returned from `createNewItemFromQuery(this.state.query)`, cached
+     * to avoid continuous reinstantions within `isCreateItemRendered`, where
+     * this element will be used to hide the "Create Item" option if its value
+     * matches the current `query`.
+     */
+    createNewItem: T | undefined;
+
     /** The original `items` array filtered by `itemListPredicate` or `itemPredicate`. */
     filteredItems: T[];
 
@@ -117,13 +127,17 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
 
     public constructor(props: IQueryListProps<T>, context?: any) {
         super(props, context);
-        const { query = "" } = this.props;
-        const filteredItems = getFilteredItems(query, this.props);
+
+        const { query = "" } = props;
+        const createNewItem = Utils.safeInvoke(props.createNewItemFromQuery, query);
+        const filteredItems = getFilteredItems(query, props);
+
         this.state = {
             activeItem:
                 this.props.activeItem !== undefined
                     ? this.props.activeItem
-                    : getFirstEnabledItem(filteredItems, this.props.itemDisabled),
+                    : getFirstEnabledItem(filteredItems, props.itemDisabled),
+            createNewItem,
             filteredItems,
             query,
         };
@@ -131,15 +145,16 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
 
     public render() {
         const { className, items, renderer, itemListRenderer = this.renderItemList } = this.props;
+        const { createNewItem, ...spreadableState } = this.state;
         return renderer({
-            ...this.state,
+            ...spreadableState,
             className,
             handleItemSelect: this.handleItemSelect,
             handleKeyDown: this.handleKeyDown,
             handleKeyUp: this.handleKeyUp,
             handleQueryChange: this.handleQueryChange,
             itemList: itemListRenderer({
-                ...this.state,
+                ...spreadableState,
                 items,
                 itemsParentRef: this.refHandlers.itemsParent,
                 renderItem: this.renderItem,
@@ -214,6 +229,8 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     }
 
     public setQuery(query: string, resetActiveItem = this.props.resetOnQuery, props = this.props) {
+        const { createNewItemFromQuery } = props;
+
         this.shouldCheckActiveItemInViewport = true;
         const hasQueryChanged = query !== this.state.query;
         if (hasQueryChanged) {
@@ -221,7 +238,9 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         }
 
         const filteredItems = getFilteredItems(query, props);
-        this.setState({ filteredItems, query });
+        const createNewItem =
+            createNewItemFromQuery != null && query !== "" ? createNewItemFromQuery(query) : undefined;
+        this.setState({ createNewItem, filteredItems, query });
 
         // always reset active item if it's now filtered or disabled
         const activeIndex = this.getActiveIndex(filteredItems);
@@ -314,6 +333,8 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     }
 
     private handleItemCreate = (query: string, evt?: React.SyntheticEvent<HTMLElement>) => {
+        // we keep a cached createNewItem in state, but might as well recompute
+        // the result just to be sure it's perfectly in sync with the query.
         const item = Utils.safeInvoke(this.props.createNewItemFromQuery, query);
         if (item != null) {
             Utils.safeInvoke(this.props.onItemSelect, item, evt);
@@ -397,7 +418,20 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     }
 
     private isCreateItemRendered(): boolean {
-        return !!(this.props.createNewItemFromQuery && this.props.createNewItemRenderer && this.state.query !== "");
+        const { createNewItemFromQuery } = this.props;
+        return (
+            createNewItemFromQuery != null &&
+            this.props.createNewItemRenderer != null &&
+            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
+            // existing item is much clearer.
+            !this.wouldCreatedItemMatchSomeExistingItem()
+        );
+    }
+
+    private wouldCreatedItemMatchSomeExistingItem() {
+        return this.props.items.some(item => executeItemsEqual(this.props.itemsEqual, item, this.state.createNewItem));
     }
 }
 

From f126a9d0cee1c0f67557d34d8b60e3c4825b1fa5 Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Wed, 27 Feb 2019 20:15:37 -0800
Subject: [PATCH 28/30] Write tests

---
 packages/select/test/selectComponentSuite.tsx | 57 +++++++++++++++++--
 1 file changed, 51 insertions(+), 6 deletions(-)

diff --git a/packages/select/test/selectComponentSuite.tsx b/packages/select/test/selectComponentSuite.tsx
index c2b12ee2aa..631fbe7717 100644
--- a/packages/select/test/selectComponentSuite.tsx
+++ b/packages/select/test/selectComponentSuite.tsx
@@ -9,7 +9,14 @@ import { assert } from "chai";
 import { ReactWrapper } from "enzyme";
 import * as React from "react";
 import * as sinon from "sinon";
-import { filterFilm, IFilm, renderFilm, TOP_100_FILMS } from "../../docs-app/src/examples/select-examples/films";
+import {
+    areFilmsEqual,
+    createFilm,
+    filterFilm,
+    IFilm,
+    renderFilm,
+    TOP_100_FILMS,
+} from "../../docs-app/src/examples/select-examples/films";
 import { IListItemsProps } from "../src/index";
 
 export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
@@ -21,6 +28,7 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
         itemPredicate: filterFilm,
         itemRenderer: sinon.spy(renderFilm),
         items: TOP_100_FILMS.slice(0, 20),
+        itemsEqual: areFilmsEqual,
         onActiveItemChange: sinon.spy(),
         onItemSelect: sinon.spy(),
         onQueryChange: sinon.spy(),
@@ -128,21 +136,38 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             noResults: <address />,
         };
 
+        beforeEach(() => {
+            testCreateProps.createNewItemFromQuery.resetHistory();
+        });
+
         it("doesn't render create item if input is empty", () => {
             const wrapper = render({
                 ...testCreateProps,
                 query: "",
             });
-            assert.lengthOf(wrapper.find(`textarea`), 0, "should not find createItem");
+            assert.lengthOf(findCreateItem(wrapper), 0, "should not find createItem");
         });
 
-        it("renders create item if input is not empty", () => {
+        it("doesn't render create item if query is non-empty and matches one of the items", () => {
+            const EXISTING_FILM_TITLE = TOP_100_FILMS[0].title;
             const wrapper = render({
                 ...testCreateProps,
-                query: TOP_100_FILMS[0].title,
+                // We need this callback to return a real item this time, and we
+                // don't need to spy on it.
+                createNewItemFromQuery: createFilm,
+                query: EXISTING_FILM_TITLE,
+            });
+            assert.lengthOf(wrapper.find("address"), 0, "should not find noResults");
+            assert.lengthOf(findCreateItem(wrapper), 0, "should not find createItem");
+        });
+
+        it("renders create item if query is not empty and doesn't match any items exactly", () => {
+            const wrapper = render({
+                ...testCreateProps,
+                query: TOP_100_FILMS[0].title + " a few extra chars",
             });
             assert.lengthOf(wrapper.find("address"), 0, "should not find noResults");
-            assert.lengthOf(wrapper.find(`textarea`), 1, "should find createItem");
+            assert.lengthOf(findCreateItem(wrapper), 1, "should find createItem");
         });
 
         it("renders create item if filtering returns empty list", () => {
@@ -151,7 +176,7 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
                 query: "non-existent film name",
             });
             assert.lengthOf(wrapper.find("address"), 0, "should not find noResults");
-            assert.lengthOf(wrapper.find(`textarea`), 1, "should find createItem");
+            assert.lengthOf(findCreateItem(wrapper), 1, "should find createItem");
         });
 
         it("enter invokes createNewItemFromQuery", () => {
@@ -188,5 +213,25 @@ export function selectComponentSuite<P extends IListItemsProps<IFilm>, S>(
             assert.equal((testProps.onActiveItemChange.lastCall.args[0] as IFilm).rank, TOP_100_FILMS[0].rank);
             assert.equal(testProps.onActiveItemChange.lastCall.args[1], false);
         });
+
+        it("when create item is rendered, updating the query to exactly match one of the items hides the create item", () => {
+            const wrapper = render({
+                ...testCreateProps,
+                // Again, we need this callback to return a real item this time.
+                createNewItemFromQuery: createFilm,
+                query: "non-empty, non-matching initial value",
+            });
+
+            assert.lengthOf(findCreateItem(wrapper), 1, "should find createItem");
+
+            const EXISTING_FILM_TITLE = TOP_100_FILMS[0].title;
+            findInput(wrapper).simulate("change", { target: { value: EXISTING_FILM_TITLE } });
+
+            assert.lengthOf(findCreateItem(wrapper), 0, "should not find createItem");
+        });
     });
+
+    function findCreateItem(wrapper: ReactWrapper<P, S>) {
+        return wrapper.find("textarea");
+    }
 }

From 1f7b3bbe0f85b6916f94dc81b88c7e52a7bad4d8 Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Thu, 28 Feb 2019 10:49:30 -0800
Subject: [PATCH 29/30] Share created-item logic in Select and Suggest
 components too

---
 .../src/examples/select-examples/films.tsx    | 39 +++++++++++++
 .../select-examples/multiSelectExample.tsx    | 56 +++++++++++--------
 .../select-examples/selectExample.tsx         | 34 ++++++++++-
 .../select-examples/suggestExample.tsx        | 34 ++++++++++-
 4 files changed, 136 insertions(+), 27 deletions(-)

diff --git a/packages/docs-app/src/examples/select-examples/films.tsx b/packages/docs-app/src/examples/select-examples/films.tsx
index 14439fbbcc..04723365f2 100644
--- a/packages/docs-app/src/examples/select-examples/films.tsx
+++ b/packages/docs-app/src/examples/select-examples/films.tsx
@@ -209,3 +209,42 @@ export function areFilmsEqual(filmA: IFilm, filmB: IFilm) {
     // Compare only the titles (ignoring case) just for simplicity.
     return filmA.title.toLowerCase() === filmB.title.toLowerCase();
 }
+
+export function arrayContainsFilm(films: IFilm[], filmToFind: IFilm): boolean {
+    return films.some((film: IFilm) => film.title === filmToFind.title);
+}
+
+export function addFilmToArray(films: IFilm[], filmToAdd: IFilm) {
+    return [...films, filmToAdd];
+}
+
+export function deleteFilmFromArray(films: IFilm[], filmToDelete: IFilm) {
+    return films.filter(film => film !== filmToDelete);
+}
+
+export function maybeAddCreatedFilmToArrays(
+    items: IFilm[],
+    createdItems: IFilm[],
+    film: IFilm,
+): { createdItems: IFilm[]; items: IFilm[] } {
+    const isNewlyCreatedItem = !arrayContainsFilm(items, film);
+    return {
+        createdItems: isNewlyCreatedItem ? addFilmToArray(createdItems, film) : createdItems,
+        // Add a created film to `items` so that the film can be deselected.
+        items: isNewlyCreatedItem ? addFilmToArray(items, film) : items,
+    };
+}
+
+export function maybeDeleteCreatedFilmFromArrays(
+    items: IFilm[],
+    createdItems: IFilm[],
+    film: IFilm,
+): { createdItems: IFilm[]; items: IFilm[] } {
+    const wasItemCreatedByUser = arrayContainsFilm(createdItems, film);
+
+    // Delete the item if the user manually created it.
+    return {
+        createdItems: wasItemCreatedByUser ? deleteFilmFromArray(createdItems, film) : createdItems,
+        items: wasItemCreatedByUser ? deleteFilmFromArray(items, film) : items,
+    };
+}
diff --git a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
index 14a35f3579..8f138d3cb7 100644
--- a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx
@@ -9,7 +9,17 @@ import * as React from "react";
 import { Button, H5, Intent, ITagProps, MenuItem, Switch } from "@blueprintjs/core";
 import { Example, IExampleProps } from "@blueprintjs/docs-theme";
 import { ItemRenderer, MultiSelect } from "@blueprintjs/select";
-import { areFilmsEqual, createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
+import {
+    areFilmsEqual,
+    arrayContainsFilm,
+    createFilm,
+    filmSelectProps,
+    IFilm,
+    maybeAddCreatedFilmToArrays,
+    maybeDeleteCreatedFilmFromArrays,
+    renderCreateFilmOption,
+    TOP_100_FILMS,
+} from "./films";
 
 const FilmMultiSelect = MultiSelect.ofType<IFilm>();
 
@@ -78,6 +88,9 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
                     initialContent={initialContent}
                     itemRenderer={this.renderFilm}
                     itemsEqual={areFilmsEqual}
+                    // 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}
                     popoverProps={{ minimal: popoverMinimal }}
@@ -167,30 +180,39 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
     }
 
     private selectFilm(film: IFilm) {
-        const { createdItems, films, items } = this.state;
-        const isNewlyCreatedItem = !this.arrayContainsFilm(items, film);
+        const { films } = this.state;
+
+        const { createdItems: nextCreatedItems, items: nextItems } = maybeAddCreatedFilmToArrays(
+            this.state.items,
+            this.state.createdItems,
+            film,
+        );
+
         this.setState({
-            createdItems: isNewlyCreatedItem ? this.addFilmToArray(createdItems, film) : createdItems,
+            createdItems: nextCreatedItems,
             // 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: !this.arrayContainsFilm(films, film) ? [...films, film] : films,
-            // Add a created film to `items` so that the film can be deselected.
-            items: isNewlyCreatedItem ? this.addFilmToArray(items, film) : items,
+            films: !arrayContainsFilm(films, film) ? [...films, film] : films,
+            items: nextItems,
         });
     }
 
     private deselectFilm(index: number) {
-        const { createdItems, films, items } = this.state;
+        const { films } = this.state;
 
         const film = films[index];
-        const wasItemCreatedByUser = this.arrayContainsFilm(createdItems, film);
+        const { createdItems: nextCreatedItems, items: nextItems } = maybeDeleteCreatedFilmFromArrays(
+            this.state.items,
+            this.state.createdItems,
+            film,
+        );
 
         // Delete the item if the user manually created it.
         this.setState({
-            createdItems: wasItemCreatedByUser ? this.deleteFilmFromArray(createdItems, film) : createdItems,
+            createdItems: nextCreatedItems,
             films: films.filter((_film, i) => i !== index),
-            items: wasItemCreatedByUser ? this.deleteFilmFromArray(items, film) : items,
+            items: nextItems,
         });
     }
 
@@ -210,16 +232,4 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
     }
 
     private handleClear = () => this.setState({ films: [] });
-
-    private arrayContainsFilm(films: IFilm[], filmToFind: IFilm): boolean {
-        return films.find(f => f.title === filmToFind.title) !== undefined;
-    }
-
-    private addFilmToArray(films: IFilm[], filmToAdd: IFilm) {
-        return [...films, filmToAdd];
-    }
-
-    private deleteFilmFromArray(films: IFilm[], filmToDelete: IFilm) {
-        return films.filter(film => film !== filmToDelete);
-    }
 }
diff --git a/packages/docs-app/src/examples/select-examples/selectExample.tsx b/packages/docs-app/src/examples/select-examples/selectExample.tsx
index f684a7e08a..9e4a774bea 100644
--- a/packages/docs-app/src/examples/select-examples/selectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/selectExample.tsx
@@ -9,15 +9,26 @@ import * as React from "react";
 import { Button, H5, MenuItem, Switch } from "@blueprintjs/core";
 import { Example, IExampleProps } from "@blueprintjs/docs-theme";
 import { Select } from "@blueprintjs/select";
-import { areFilmsEqual, createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
+import {
+    areFilmsEqual,
+    createFilm,
+    filmSelectProps,
+    IFilm,
+    maybeAddCreatedFilmToArrays,
+    maybeDeleteCreatedFilmFromArrays,
+    renderCreateFilmOption,
+    TOP_100_FILMS,
+} from "./films";
 
 const FilmSelect = Select.ofType<IFilm>();
 
 export interface ISelectExampleState {
     allowCreate: boolean;
+    createdItems: IFilm[];
     film: IFilm;
     filterable: boolean;
     hasInitialContent: boolean;
+    items: IFilm[];
     minimal: boolean;
     resetOnClose: boolean;
     resetOnQuery: boolean;
@@ -29,11 +40,13 @@ export interface ISelectExampleState {
 export class SelectExample extends React.PureComponent<IExampleProps, ISelectExampleState> {
     public state: ISelectExampleState = {
         allowCreate: false,
+        createdItems: [],
         disableItems: false,
         disabled: false,
         film: TOP_100_FILMS[0],
         filterable: true,
         hasInitialContent: false,
+        items: filmSelectProps.items,
         minimal: false,
         resetOnClose: false,
         resetOnQuery: true,
@@ -71,6 +84,9 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
                     disabled={disabled}
                     itemDisabled={this.isItemDisabled}
                     itemsEqual={areFilmsEqual}
+                    // we may customize the default filmSelectProps.items by
+                    // adding newly created items to the list, so pass our own
+                    items={this.state.items}
                     initialContent={initialContent}
                     noResults={<MenuItem disabled={true} text="No results." />}
                     onItemSelect={this.handleValueChange}
@@ -133,7 +149,21 @@ export class SelectExample extends React.PureComponent<IExampleProps, ISelectExa
         );
     }
 
-    private handleValueChange = (film: IFilm) => this.setState({ film });
+    private handleValueChange = (film: IFilm) => {
+        // Delete the old film from the list if it was newly created.
+        const { createdItems, items } = maybeDeleteCreatedFilmFromArrays(
+            this.state.items,
+            this.state.createdItems,
+            this.state.film,
+        );
+        // Add the new film to the list if it is newly created.
+        const { createdItems: nextCreatedItems, items: nextItems } = maybeAddCreatedFilmToArrays(
+            items,
+            createdItems,
+            film,
+        );
+        this.setState({ createdItems: nextCreatedItems, film, items: nextItems });
+    };
 
     private handleSwitchChange(prop: keyof ISelectExampleState) {
         return (event: React.FormEvent<HTMLInputElement>) => {
diff --git a/packages/docs-app/src/examples/select-examples/suggestExample.tsx b/packages/docs-app/src/examples/select-examples/suggestExample.tsx
index e909caf4bd..b8a8a8f2bc 100644
--- a/packages/docs-app/src/examples/select-examples/suggestExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/suggestExample.tsx
@@ -9,14 +9,25 @@ import * as React from "react";
 import { H5, MenuItem, Switch } from "@blueprintjs/core";
 import { Example, IExampleProps } from "@blueprintjs/docs-theme";
 import { Suggest } from "@blueprintjs/select";
-import { areFilmsEqual, createFilm, filmSelectProps, IFilm, renderCreateFilmOption, TOP_100_FILMS } from "./films";
+import {
+    areFilmsEqual,
+    createFilm,
+    filmSelectProps,
+    IFilm,
+    maybeAddCreatedFilmToArrays,
+    maybeDeleteCreatedFilmFromArrays,
+    renderCreateFilmOption,
+    TOP_100_FILMS,
+} from "./films";
 
 const FilmSuggest = Suggest.ofType<IFilm>();
 
 export interface ISuggestExampleState {
     allowCreate: boolean;
     closeOnSelect: boolean;
+    createdItems: IFilm[];
     film: IFilm;
+    items: IFilm[];
     minimal: boolean;
     openOnKeyDown: boolean;
     resetOnClose: boolean;
@@ -28,7 +39,9 @@ export class SuggestExample extends React.PureComponent<IExampleProps, ISuggestE
     public state: ISuggestExampleState = {
         allowCreate: false,
         closeOnSelect: true,
+        createdItems: [],
         film: TOP_100_FILMS[0],
+        items: filmSelectProps.items,
         minimal: true,
         openOnKeyDown: false,
         resetOnClose: false,
@@ -59,6 +72,9 @@ export class SuggestExample extends React.PureComponent<IExampleProps, ISuggestE
                     createNewItemRenderer={maybeCreateNewItemRenderer}
                     inputValueRenderer={this.renderInputValue}
                     itemsEqual={areFilmsEqual}
+                    // 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.handleValueChange}
                     popoverProps={{ minimal }}
@@ -113,7 +129,21 @@ export class SuggestExample extends React.PureComponent<IExampleProps, ISuggestE
 
     private renderInputValue = (film: IFilm) => film.title;
 
-    private handleValueChange = (film: IFilm) => this.setState({ film });
+    private handleValueChange = (film: IFilm) => {
+        // delete the old film from the list if it was newly created
+        const { createdItems, items } = maybeDeleteCreatedFilmFromArrays(
+            this.state.items,
+            this.state.createdItems,
+            this.state.film,
+        );
+        // add the new film to the list if it is newly created
+        const { createdItems: nextCreatedItems, items: nextItems } = maybeAddCreatedFilmToArrays(
+            items,
+            createdItems,
+            film,
+        );
+        this.setState({ createdItems: nextCreatedItems, film, items: nextItems });
+    };
 
     private handleSwitchChange(prop: keyof ISuggestExampleState) {
         return (event: React.FormEvent<HTMLInputElement>) => {

From b9e363f499e962663790e78f9709997aa025a379 Mon Sep 17 00:00:00 2001
From: Chris Lewis <clewis@palantir.com>
Date: Thu, 28 Feb 2019 10:50:35 -0800
Subject: [PATCH 30/30] Small optimization: compare created item to
 filteredItems, not items

---
 packages/select/src/components/query-list/queryList.tsx | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/packages/select/src/components/query-list/queryList.tsx b/packages/select/src/components/query-list/queryList.tsx
index a4910c9bf1..cf4397b615 100644
--- a/packages/select/src/components/query-list/queryList.tsx
+++ b/packages/select/src/components/query-list/queryList.tsx
@@ -431,7 +431,11 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     }
 
     private wouldCreatedItemMatchSomeExistingItem() {
-        return this.props.items.some(item => executeItemsEqual(this.props.itemsEqual, item, this.state.createNewItem));
+        // search only the filtered items, not the full items list, because we
+        // only need to check items that match the current query.
+        return this.state.filteredItems.some(item =>
+            executeItemsEqual(this.props.itemsEqual, item, this.state.createNewItem),
+        );
     }
 }