[Select] Create-able Select components

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 {
+        rank: 100 + Math.floor(Math.random() * 100 + 1),
+        title,
+        year: new Date().getFullYear(),
+    };
+}

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>();
 
@@ -19,6 +19,7 @@ export interface IMultiSelectExampleState {
     films: IFilm[];
     hasInitialContent: boolean;
     intent: boolean;
+    allowCreate: boolean;
     openOnKeyDown: boolean;
     popoverMinimal: boolean;
     resetOnSelect: boolean;
@@ -27,6 +28,7 @@ export interface IMultiSelectExampleState {
 
 export class MultiSelectExample extends React.PureComponent<IExampleProps, IMultiSelectExampleState> {
     public state: IMultiSelectExampleState = {
+        allowCreate: false,
         films: [],
         hasInitialContent: false,
         intent: false,
@@ -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;
@@ -56,6 +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 clearButton = films.length > 0 ? <Button icon="cross" minimal={true} onClick={this.handleClear} /> : null;
 
@@ -72,6 +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}
+                    createNewItemFromQuery={maybeCreateNewItemFromQuery}
+                    createNewItemRenderer={maybeCreateNewItemRenderer}
                 />
             </Example>
         );
@@ -96,6 +103,11 @@ export class MultiSelectExample extends React.PureComponent<IExampleProps, IMult
                     checked={this.state.hasInitialContent}
                     onChange={this.handleInitialContentChange}
                 />
+                <Switch
+                    label="Allow creating new films"
+                    checked={this.state.allowCreate}
+                    onChange={this.handleAllowCreateChange}
+                />
                 <H5>Tag props</H5>
                 <Switch
                     label="Minimal tag style"
@@ -137,6 +149,20 @@ 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);
     };

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 maybeCreateNewItemFromQuery = this.state.allowCreate ? createFilm : undefined;
+        const maybeCreateNewItemRenderer = this.state.allowCreate ? this.renderCreateFilmOption : null;
 
         return (
             <Example options={this.renderOptions()} {...this.props}>
                 <FilmSelect
                     {...filmSelectProps}
                     {...flags}
+                    createNewItemFromQuery={maybeCreateNewItemFromQuery}
+                    createNewItemRenderer={maybeCreateNewItemRenderer}
                     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,20 @@ 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) {

packages/select/src/common/itemListRenderer.ts

@@ -4,6 +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;
+}
+
+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.
@@ -13,7 +30,7 @@ export interface IItemListRendererProps<T> {
      * The currently focused item (for keyboard interactions), or `null` to
      * indicate that no item is active.
      */
-    activeItem: T | null;
+    activeItem: IQueryListActiveItem<T> | null;
 
     /**
      * Array of items filtered by `itemListPredicate` or `itemPredicate`.

packages/select/src/common/listItemsProps.ts

@@ -5,7 +5,7 @@
 */
 
 import { IProps, Utils } from "@blueprintjs/core";
-import { ItemListRenderer } from "./itemListRenderer";
+import { IQueryListActiveItem, ItemListRenderer } from "./itemListRenderer";
 import { ItemRenderer } from "./itemRenderer";
 import { ItemListPredicate, ItemPredicate } from "./predicate";
 
@@ -28,7 +28,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[];
@@ -111,7 +111,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,
@@ -124,6 +124,22 @@ 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.
+     */
+    createNewItemFromQuery?: (query: string) => T;
+
+    /**
+     * Custom renderer to transform the current query string into a selectable "Create Item" option.
+     */
+    createNewItemRenderer?: (
+        query: string,
+        active: boolean,
+        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).