From 44c14e5ad0c851ce66adee324529733ff6ea5828 Mon Sep 17 00:00:00 2001
From: Adi Dahiya <adahiya@palantir.com>
Date: Tue, 17 May 2022 13:29:53 -0400
Subject: [PATCH] [select] feat: new Select2 component uses Popover2 (#5306)

---
 packages/docs-app/src/common/filmSelect.tsx   |   6 +-
 .../select-examples/selectExample.tsx         |   1 +
 packages/select/karma.conf.js                 |   1 -
 packages/select/package.json                  |   1 +
 packages/select/src/components/index.ts       |   1 +
 .../select/src/components/select/_select.scss |   3 +-
 .../src/components/select/select-component.md | 279 +----------------
 .../select/src/components/select/select.tsx   |   1 +
 .../select/src/components/select/select2.md   | 294 ++++++++++++++++++
 .../select/src/components/select/select2.tsx  | 255 +++++++++++++++
 packages/select/src/index.md                  |  13 +-
 packages/select/test/index.ts                 |   1 +
 packages/select/test/isotest.js               |   9 +-
 packages/select/test/select2Tests.tsx         | 123 ++++++++
 packages/select/test/selectTests.tsx          |  16 +-
 15 files changed, 722 insertions(+), 282 deletions(-)
 create mode 100644 packages/select/src/components/select/select2.md
 create mode 100644 packages/select/src/components/select/select2.tsx
 create mode 100644 packages/select/test/select2Tests.tsx

diff --git a/packages/docs-app/src/common/filmSelect.tsx b/packages/docs-app/src/common/filmSelect.tsx
index 6421a08c40..b97d987f3a 100644
--- a/packages/docs-app/src/common/filmSelect.tsx
+++ b/packages/docs-app/src/common/filmSelect.tsx
@@ -17,7 +17,7 @@
 import * as React from "react";
 
 import { Button, MenuItem } from "@blueprintjs/core";
-import { Select, SelectProps } from "@blueprintjs/select";
+import { Select2, Select2Props } from "@blueprintjs/select";
 
 import {
     areFilmsEqual,
@@ -30,10 +30,10 @@ import {
     TOP_100_FILMS,
 } from "./films";
 
-const FilmSelect = Select.ofType<IFilm>();
+const FilmSelect = Select2.ofType<IFilm>();
 
 type Props = Omit<
-    SelectProps<IFilm>,
+    Select2Props<IFilm>,
     | "createNewItemFromQuery"
     | "createNewItemRenderer"
     | "items"
diff --git a/packages/docs-app/src/examples/select-examples/selectExample.tsx b/packages/docs-app/src/examples/select-examples/selectExample.tsx
index 0c4f62d92a..9b9d977409 100644
--- a/packages/docs-app/src/examples/select-examples/selectExample.tsx
+++ b/packages/docs-app/src/examples/select-examples/selectExample.tsx
@@ -38,6 +38,7 @@ export interface ISelectExampleState {
     matchTargetWidth: false;
 }
 
+/** Technically a Select2 example, since FilmSelect uses Select2. */
 export class SelectExample extends React.PureComponent<IExampleProps, ISelectExampleState> {
     public state: ISelectExampleState = {
         allowCreate: false,
diff --git a/packages/select/karma.conf.js b/packages/select/karma.conf.js
index c46c44bbae..84c3e0b538 100644
--- a/packages/select/karma.conf.js
+++ b/packages/select/karma.conf.js
@@ -6,7 +6,6 @@ const { createKarmaConfig } = require("@blueprintjs/karma-build-scripts");
 
 module.exports = function (config) {
     const baseConfig = createKarmaConfig({
-        coverage: false,
         dirname: __dirname,
     });
     config.set(baseConfig);
diff --git a/packages/select/package.json b/packages/select/package.json
index 3f52684a8f..737ee72c5f 100644
--- a/packages/select/package.json
+++ b/packages/select/package.json
@@ -36,6 +36,7 @@
     },
     "dependencies": {
         "@blueprintjs/core": "^4.3.2",
+        "@blueprintjs/popover2": "^1.2.2",
         "classnames": "^2.2",
         "tslib": "~2.3.1"
     },
diff --git a/packages/select/src/components/index.ts b/packages/select/src/components/index.ts
index d5bcf0b20c..743b61dc88 100644
--- a/packages/select/src/components/index.ts
+++ b/packages/select/src/components/index.ts
@@ -18,4 +18,5 @@ export * from "./omnibar/omnibar";
 export * from "./query-list/queryList";
 export * from "./select/multiSelect";
 export * from "./select/select";
+export * from "./select/select2";
 export * from "./select/suggest";
diff --git a/packages/select/src/components/select/_select.scss b/packages/select/src/components/select/_select.scss
index e33c312bc0..d6386636a3 100644
--- a/packages/select/src/components/select/_select.scss
+++ b/packages/select/src/components/select/_select.scss
@@ -16,7 +16,8 @@ $select-popover-max-width: $pt-grid-size * 40 !default;
     }
   }
 
-  .#{$ns}-popover-content {
+  .#{$ns}-popover-content,
+  .#{$ns}-popover2-content {
     // use padding on container rather than margin on input group
     // because top margin leaves some empty space with no background color.
     padding: $pt-grid-size * 0.5;
diff --git a/packages/select/src/components/select/select-component.md b/packages/select/src/components/select/select-component.md
index 92e9d0513c..e3ff6f8f89 100644
--- a/packages/select/src/components/select/select-component.md
+++ b/packages/select/src/components/select/select-component.md
@@ -1,276 +1,27 @@
 @# Select
 
-Use `Select<T>` for choosing one item from a list. The component's children will be wrapped in a [`Popover`](#core/components/popover) that contains the list and an optional `InputGroup` to filter it. Provide a predicate to customize the filtering algorithm. The value of a `Select<T>` (the currently chosen item) is uncontrolled: listen to changes with `onItemSelect`.
+<div class="@ns-callout @ns-intent-danger @ns-icon-error">
+    <h4 class="@ns-heading">
 
-<div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
-    <h4 class="@ns-heading">Disabling a Select</h4>
+Deprecated: use [Select2](#select/select2)
 
-Disabling the component requires setting the `disabled` prop to `true`
-and separately disabling the component's children as appropriate (because `Select` accepts arbitrary children).
+</h4>
 
-For example, `<Select ... disabled={true}><Button ... disabled={true} /></Select>`
+This component is **deprecated since @blueprintjs/select v4.3.0** in favor of the new
+Select2 component, which uses Popover2 instead of Popover under the hood.
+You should migrate to the new API which will become the standard in Blueprint v5.
 
 </div>
 
-@reactExample SelectExample
+The `Select<T>` component renders a UI to choose one item from a list. Its children are wrapped in a
+[`Popover`](#core/components/popover) that contains the list and an optional `InputGroup` to filter it.
+You may provide a predicate to customize the filtering algorithm. The value of a `Select<T>`
+(the currently chosen item) is uncontrolled: listen to changes with `onItemSelect`.
 
-```tsx
-import { Button, MenuItem } from "@blueprintjs/core";
-import { Select } from "@blueprintjs/select";
-import * as Films from "./films";
+The API for this component is nearly identical to that of Select2, except for a slight change in
+`popoverProps` and the wrapper element(s) rendered around its children.
+Refer to the [Select2 documentation](#select/select2) for full API details.
 
-// Select<T> is a generic component to work with your data types.
-// In TypeScript, you must first obtain a non-generic reference:
-const FilmSelect = Select.ofType<Films.Film>();
-
-ReactDOM.render(
-    <FilmSelect
-        items={Films.items}
-        itemPredicate={Films.itemPredicate}
-        itemRenderer={Films.itemRenderer}
-        noResults={<MenuItem disabled={true} text="No results." />}
-        onItemSelect={...}
-    >
-        {/* children become the popover target; render value here */}
-        <Button text={Films.items[0].title} rightIcon="double-caret-vertical" />
-    </FilmSelect>,
-    document.querySelector("#root")
-);
-```
-
-In TypeScript, `Select<T>` is a _generic component_ so you must define a local type that specifies `<T>`, the type of one item in `items`. The props on this local type will now operate on your data type (speak your language) so you can easily define handlers without transformation steps, but most props are required as a result. The static `Select.ofType<T>()` method is available to streamline this process. (Note that this has no effect on JavaScript usage: the `Select` export is a perfectly valid React component class.)
-
-@## Querying
-
-Supply a predicate to automatically query items based on the `InputGroup` value. Use `itemPredicate` to filter each item individually; this is great for lightweight searches. Use `itemListPredicate` to query the entire array in one go, and even reorder it, such as with [fuzz-aldrin-plus](https://github.com/jeancroy/fuzz-aldrin-plus). The array of filtered items is cached internally by `QueryList` state and only recomputed when `query` or `items`-related props change.
-
-Omitting both `itemPredicate` and `itemListPredicate` props will cause the component to always render all `items`. It will not hide the `InputGroup`; use the `filterable` prop for that. In this case, you can implement your own filtering and simply change the `items` prop.
-
-The **@blueprintjs/select** package exports `ItemPredicate<T>` and `ItemListPredicate<T>` type aliases to simplify the process of implementing these functions.
-See the code sample in [Item Renderer API](#select/select-component.item-renderer) below for usage.
-
-@### Non-ideal states
-
-If the query returns no results or `items` is empty, then `noResults` will be rendered in place of the usual list. You also have the option to provide `initialContent`, which will render in place of the item list if the query is empty.
-
-@## Custom menu
-
-By default, `Select` renders the displayed items in a [`Menu`](#core/components/menu). This behavior can be overridden by providing the `itemListRenderer` prop, giving you full control over the layout of the items. For example, you can group items under a common heading, or render large data sets using [react-virtualized](https://github.com/bvaughn/react-virtualized).
-
-Note that the non-ideal states of `noResults` and `initialContent` are specific to the default renderer. If you provide the `itemListRenderer` prop, these props will be ignored.
-
-See the code sample in [Item List Renderer API](#select/select-component.item-list-renderer) below for usage.
-
-@## Controlled usage
-
-The input value can be controlled with the `query` and `onQueryChange` props. _Do not use `inputProps` for this;_ the component ignores `inputProps.value` and `inputProps.onChange` in favor of `query` and `onQueryChange` (as noted in the prop documentation).
-
-The focused item (for keyboard interactions) can be controlled with the `activeItem` and `onActiveItemChange` props.
-
-```tsx
-<FilmSelect
-    items={myFilter(ALL_ITEMS, this.state.myQuery)}
-    itemRenderer={...}
-    onItemSelect={...}
-    // controlled active item
-    activeItem={this.state.myActiveItem}
-    onActiveItemChange={this.handleActiveItemChange}
-    // controlled query
-    query={this.state.myQuery}
-    onQueryChange={this.handleQueryChange}
-/>
-```
-
-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
-
-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 {
-    return {
-        rank: /* ... */,
-        title,
-        year: /* ... */,
-    };
-}
-
-function renderCreateFilmOption(
-    query: string,
-    active: boolean,
-    handleClick: React.MouseEventHandler<HTMLElement>,
-) {
-    return (
-        <MenuItem
-            icon="add"
-            text={`Create "${query}"`}
-            selected={active}
-            onClick={handleClick}
-            shouldDismissPopover={false}
-        />
-    )
-}
-
-ReactDOM.render(
-    <FilmSelect
-        createNewItemFromQuery={createFilm}
-        createNewItemRenderer={renderCreateFilmOption}
-        items={Films.items}
-        itemPredicate={Films.itemPredicate}
-        itemRenderer={Films.itemRenderer}
-        noResults={<MenuItem disabled={true} text="No results." />}
-        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
+@## Props interface
 
 @interface ISelectProps
-
-@### Item renderer
-
-`Select`'s `itemRenderer` will be called for each item and receives the item and a props object containing data specific
-to rendering this item in this frame. The renderer is called for all items, so don't forget to respect
-`modifiers.matchesPredicate` to hide items that don't match the predicate. Also, don't forget to define a `key` for each item, or face React's console wrath!
-
-```tsx
-import { Classes, MenuItem } from "@blueprintjs/core";
-import { ItemRenderer, ItemPredicate, Select } from "@blueprintjs/select";
-
-const FilmSelect = Select.ofType<Film>();
-
-const filterFilm: ItemPredicate<IFilm> = (query, film) => {
-    return film.title.toLowerCase().indexOf(query.toLowerCase()) >= 0;
-};
-
-const renderFilm: ItemRenderer<Film> = (film, { handleClick, handleFocus, modifiers }) => {
-    if (!modifiers.matchesPredicate) {
-        return null;
-    }
-    return (
-        <MenuItem
-            selected={modifiers.active}
-            key={film.title}
-            label={film.year}
-            onClick={handleClick}
-            onFocus={handleFocus}
-            text={film.title}
-        />
-    );
-};
-
-<FilmSelect itemPredicate={filterFilm} itemRenderer={renderFilm} items={...} onItemSelect={...} />
-```
-
-@interface IItemRendererProps
-
-@### Item list renderer
-
-If provided, the `itemListRenderer` prop will be called to render the contents of the dropdown menu. It has access to the items, the current query, and a `renderItem` callback for rendering a single item. A ref handler (`itemsParentRef`) is given as well; it should be attached to the parent element of the rendered menu items so that the currently selected item can be scrolled into view automatically.
-
-```tsx
-import { ItemListRenderer } from "@blueprintjs/select";
-
-const renderMenu: ItemListRenderer<Film> = ({ items, itemsParentRef, query, renderItem }) => {
-    const renderedItems = items.map(renderItem).filter(item => item != null);
-    return (
-        <Menu ulRef={itemsParentRef}>
-            <MenuItem
-                disabled={true}
-                text={`Found ${renderedItems.length} items matching "${query}"`}
-            />
-            {renderedItems}
-        </Menu>
-    );
-};
-
-<FilmSelect
-    itemListRenderer={renderMenu}
-    itemPredicate={filterFilm}
-    itemRenderer={renderFilm}
-    items={...}
-    onItemSelect={...}
-/>
-```
-
-@interface IItemListRendererProps
diff --git a/packages/select/src/components/select/select.tsx b/packages/select/src/components/select/select.tsx
index ec626ab2f9..9e939e8e3d 100644
--- a/packages/select/src/components/select/select.tsx
+++ b/packages/select/src/components/select/select.tsx
@@ -280,6 +280,7 @@ export class Select<T> extends AbstractPureComponent2<SelectProps<T>, ISelectSta
     private handlePopoverClosing = (node: HTMLElement) => {
         // restore focus to saved element.
         // timeout allows popover to begin closing and remove focus handlers beforehand.
+        /* istanbul ignore next */
         this.requestAnimationFrame(() => {
             if (this.previousFocusedElement !== undefined) {
                 this.previousFocusedElement.focus();
diff --git a/packages/select/src/components/select/select2.md b/packages/select/src/components/select/select2.md
new file mode 100644
index 0000000000..748bbe4e12
--- /dev/null
+++ b/packages/select/src/components/select/select2.md
@@ -0,0 +1,294 @@
+---
+tag: new
+---
+
+@# Select2
+
+<div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
+    <h4 class="@ns-heading">
+
+Migrating from [Select](#select/select-component)?
+
+</h4>
+
+Select2 is a replacement for Select and will replace it in Blueprint core v5.
+You are encouraged to use this new API now to ease the transition to the next major version of Blueprint.
+See the [migration guide](https://github.com/palantir/blueprint/wiki/Select2,-Suggest2,-MultiSelect2-migration)
+on the wiki.
+
+</div>
+
+Use `Select2<T>` for choosing one item from a list. The component's children will be wrapped in a [`Popover2`](#popover2-package/popover2) that contains the list and an optional `InputGroup` to filter it. Provide a predicate to customize the filtering algorithm. The value of a `Select2<T>` (the currently chosen item) is uncontrolled: listen to changes with `onItemSelect`.
+
+<div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
+    <h4 class="@ns-heading">Disabling a Select2</h4>
+
+Disabling the component requires setting the `disabled` prop to `true`
+and separately disabling the component's children as appropriate (because `Select2` accepts arbitrary children).
+
+For example, `<Select2 ... disabled={true}><Button ... disabled={true} /></Select2>`
+
+</div>
+
+@reactExample SelectExample
+
+```tsx
+import { Button, MenuItem } from "@blueprintjs/core";
+import { Select2 } from "@blueprintjs/select";
+import * as Films from "./films";
+
+// Select2<T> is a generic component to work with your data types.
+// In TypeScript, you must first obtain a non-generic reference:
+const FilmSelect = Select2.ofType<Films.Film>();
+
+ReactDOM.render(
+    <FilmSelect
+        items={Films.items}
+        itemPredicate={Films.itemPredicate}
+        itemRenderer={Films.itemRenderer}
+        noResults={<MenuItem disabled={true} text="No results." />}
+        onItemSelect={...}
+    >
+        {/* children become the popover target; render value here */}
+        <Button text={Films.items[0].title} rightIcon="double-caret-vertical" />
+    </FilmSelect>,
+    document.querySelector("#root")
+);
+```
+
+In TypeScript, `Select2<T>` is a _generic component_ so you must define a local type that specifies `<T>`, the type of one item in `items`. The props on this local type will now operate on your data type (speak your language) so you can easily define handlers without transformation steps, but most props are required as a result. The static `Select2.ofType<T>()` method is available to streamline this process. (Note that this has no effect on JavaScript usage: the `Select2` export is a perfectly valid React component class.)
+
+@## Querying
+
+Supply a predicate to automatically query items based on the `InputGroup` value. Use `itemPredicate` to filter each item individually; this is great for lightweight searches. Use `itemListPredicate` to query the entire array in one go, and even reorder it, such as with [fuzz-aldrin-plus](https://github.com/jeancroy/fuzz-aldrin-plus). The array of filtered items is cached internally by `QueryList` state and only recomputed when `query` or `items`-related props change.
+
+Omitting both `itemPredicate` and `itemListPredicate` props will cause the component to always render all `items`. It will not hide the `InputGroup`; use the `filterable` prop for that. In this case, you can implement your own filtering and simply change the `items` prop.
+
+The **@blueprintjs/select** package exports `ItemPredicate<T>` and `ItemListPredicate<T>` type aliases to simplify the process of implementing these functions.
+See the code sample in [Item Renderer API](#select/select2.item-renderer) below for usage.
+
+@### Non-ideal states
+
+If the query returns no results or `items` is empty, then `noResults` will be rendered in place of the usual list. You also have the option to provide `initialContent`, which will render in place of the item list if the query is empty.
+
+@## Custom menu
+
+By default, `Select2` renders the displayed items in a [`Menu`](#core/components/menu). This behavior can be overridden by providing the `itemListRenderer` prop, giving you full control over the layout of the items. For example, you can group items under a common heading, or render large data sets using [react-virtualized](https://github.com/bvaughn/react-virtualized).
+
+Note that the non-ideal states of `noResults` and `initialContent` are specific to the default renderer. If you provide the `itemListRenderer` prop, these props will be ignored.
+
+See the code sample in [Item List Renderer API](#select/select2.item-list-renderer) below for usage.
+
+@## Controlled usage
+
+The input value can be controlled with the `query` and `onQueryChange` props. _Do not use `inputProps` for this;_ the component ignores `inputProps.value` and `inputProps.onChange` in favor of `query` and `onQueryChange` (as noted in the prop documentation).
+
+The focused item (for keyboard interactions) can be controlled with the `activeItem` and `onActiveItemChange` props.
+
+```tsx
+<FilmSelect
+    items={myFilter(ALL_ITEMS, this.state.myQuery)}
+    itemRenderer={...}
+    onItemSelect={...}
+    // controlled active item
+    activeItem={this.state.myActiveItem}
+    onActiveItemChange={this.handleActiveItemChange}
+    // controlled query
+    query={this.state.myQuery}
+    onQueryChange={this.handleQueryChange}
+/>
+```
+
+This controlled usage allows you to implement all sorts of advanced behavior on
+top of the basic `Select2` 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/select2.controlling-the-active-item) in the "Creating new items" section below.
+</div>
+
+@## Creating 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 `Select2` 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 {
+    return {
+        rank: /* ... */,
+        title,
+        year: /* ... */,
+    };
+}
+
+function renderCreateFilmOption(
+    query: string,
+    active: boolean,
+    handleClick: React.MouseEventHandler<HTMLElement>,
+) {
+    return (
+        <MenuItem
+            icon="add"
+            text={`Create "${query}"`}
+            selected={active}
+            onClick={handleClick}
+            shouldDismissPopover={false}
+        />
+    )
+}
+
+ReactDOM.render(
+    <FilmSelect
+        createNewItemFromQuery={createFilm}
+        createNewItemRenderer={renderCreateFilmOption}
+        items={Films.items}
+        itemPredicate={Films.itemPredicate}
+        itemRenderer={Films.itemRenderer}
+        noResults={<MenuItem disabled={true} text="No results." />}
+        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")
+);
+```
+
+@## Props interface
+
+@interface Select2Props
+
+@### Item renderer
+
+`Select2`'s `itemRenderer` will be called for each item and receives the item and a props object containing data specific
+to rendering this item in this frame. The renderer is called for all items, so don't forget to respect
+`modifiers.matchesPredicate` to hide items that don't match the predicate. Also, don't forget to define a `key` for each item, or face React's console wrath!
+
+```tsx
+import { Classes, MenuItem } from "@blueprintjs/core";
+import { ItemRenderer, ItemPredicate, Select2 } from "@blueprintjs/select";
+
+const FilmSelect = Select2.ofType<Film>();
+
+const filterFilm: ItemPredicate<IFilm> = (query, film) => {
+    return film.title.toLowerCase().indexOf(query.toLowerCase()) >= 0;
+};
+
+const renderFilm: ItemRenderer<Film> = (film, { handleClick, handleFocus, modifiers }) => {
+    if (!modifiers.matchesPredicate) {
+        return null;
+    }
+    return (
+        <MenuItem
+            selected={modifiers.active}
+            key={film.title}
+            label={film.year}
+            onClick={handleClick}
+            onFocus={handleFocus}
+            text={film.title}
+        />
+    );
+};
+
+<FilmSelect itemPredicate={filterFilm} itemRenderer={renderFilm} items={...} onItemSelect={...} />
+```
+
+@interface IItemRendererProps
+
+@### Item list renderer
+
+If provided, the `itemListRenderer` prop will be called to render the contents of the dropdown menu. It has access to the items, the current query, and a `renderItem` callback for rendering a single item. A ref handler (`itemsParentRef`) is given as well; it should be attached to the parent element of the rendered menu items so that the currently selected item can be scrolled into view automatically.
+
+```tsx
+import { ItemListRenderer } from "@blueprintjs/select";
+
+const renderMenu: ItemListRenderer<Film> = ({ items, itemsParentRef, query, renderItem }) => {
+    const renderedItems = items.map(renderItem).filter(item => item != null);
+    return (
+        <Menu ulRef={itemsParentRef}>
+            <MenuItem
+                disabled={true}
+                text={`Found ${renderedItems.length} items matching "${query}"`}
+            />
+            {renderedItems}
+        </Menu>
+    );
+};
+
+<FilmSelect
+    itemListRenderer={renderMenu}
+    itemPredicate={filterFilm}
+    itemRenderer={renderFilm}
+    items={...}
+    onItemSelect={...}
+/>
+```
+
+@interface IItemListRendererProps
diff --git a/packages/select/src/components/select/select2.tsx b/packages/select/src/components/select/select2.tsx
new file mode 100644
index 0000000000..d9f7725f7a
--- /dev/null
+++ b/packages/select/src/components/select/select2.tsx
@@ -0,0 +1,255 @@
+/*
+ * Copyright 2022 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** @fileoverview "V2" variant of Select which uses Popover2 instead of Popover */
+
+import classNames from "classnames";
+import * as React from "react";
+
+import {
+    AbstractPureComponent2,
+    Button,
+    DISPLAYNAME_PREFIX,
+    InputGroup,
+    InputGroupProps2,
+    IRef,
+    Keys,
+    Position,
+    refHandler,
+    setRef,
+} from "@blueprintjs/core";
+import { Popover2, Popover2Props } from "@blueprintjs/popover2";
+
+import { Classes, IListItemsProps } from "../../common";
+import { IQueryListRendererProps, QueryList } from "../query-list/queryList";
+
+export interface Select2Props<T> extends IListItemsProps<T> {
+    children?: React.ReactNode;
+
+    /**
+     * Whether the component should take up the full width of its container.
+     * This overrides `popoverProps.fill`. You also have to ensure that the child
+     * component has `fill` set to `true` or is styled appropriately.
+     */
+    fill?: boolean;
+
+    /**
+     * Whether the dropdown list can be filtered.
+     * Disabling this option will remove the `InputGroup` and ignore `inputProps`.
+     *
+     * @default true
+     */
+    filterable?: boolean;
+
+    /**
+     * Whether the component is non-interactive.
+     * If true, the list's item renderer will not be called.
+     * Note that you'll also need to disable the component's children, if appropriate.
+     *
+     * @default false
+     */
+    disabled?: boolean;
+
+    /**
+     * Props to spread to the query `InputGroup`. Use `query` and
+     * `onQueryChange` instead of `inputProps.value` and `inputProps.onChange`
+     * to control this input.
+     */
+    inputProps?: InputGroupProps2;
+
+    /** Props to spread to `Popover2`. Note that `content` cannot be changed. */
+    popoverProps?: Partial<Omit<Popover2Props, "content">>;
+
+    /**
+     * Whether the active item should be reset to the first matching item _when
+     * the popover closes_. The query will also be reset to the empty string.
+     *
+     * @default false
+     */
+    resetOnClose?: boolean;
+}
+
+export interface Select2State {
+    isOpen: boolean;
+}
+
+export class Select2<T> extends AbstractPureComponent2<Select2Props<T>, Select2State> {
+    public static displayName = `${DISPLAYNAME_PREFIX}.Select2`;
+
+    public static ofType<U>() {
+        return Select2 as new (props: Select2Props<U>) => Select2<U>;
+    }
+
+    public state: Select2State = { isOpen: false };
+
+    private TypedQueryList = QueryList.ofType<T>();
+
+    public inputElement: HTMLInputElement | null = null;
+
+    private queryList: QueryList<T> | null = null;
+
+    private previousFocusedElement: HTMLElement | undefined;
+
+    private handleInputRef: IRef<HTMLInputElement> = refHandler(this, "inputElement", this.props.inputProps?.inputRef);
+
+    private handleQueryListRef = (ref: QueryList<T> | null) => (this.queryList = ref);
+
+    public render() {
+        // omit props specific to this component, spread the rest.
+        const { filterable, inputProps, popoverProps, ...restProps } = this.props;
+
+        return (
+            <this.TypedQueryList
+                {...restProps}
+                onItemSelect={this.handleItemSelect}
+                ref={this.handleQueryListRef}
+                renderer={this.renderQueryList}
+            />
+        );
+    }
+
+    public componentDidUpdate(prevProps: Select2Props<T>, prevState: Select2State) {
+        if (prevProps.inputProps?.inputRef !== this.props.inputProps?.inputRef) {
+            setRef(prevProps.inputProps?.inputRef, null);
+            this.handleInputRef = refHandler(this, "inputElement", this.props.inputProps?.inputRef);
+            setRef(this.props.inputProps?.inputRef, this.inputElement);
+        }
+
+        if (this.state.isOpen && !prevState.isOpen && this.queryList != null) {
+            this.queryList.scrollActiveItemIntoView();
+        }
+    }
+
+    private renderQueryList = (listProps: IQueryListRendererProps<T>) => {
+        // not using defaultProps cuz they're hard to type with generics (can't use <T> on static members)
+        const { fill, filterable = true, disabled = false, inputProps = {}, popoverProps = {} } = this.props;
+
+        if (fill) {
+            popoverProps.fill = true;
+        }
+
+        const input = (
+            <InputGroup
+                leftIcon="search"
+                placeholder="Filter..."
+                rightElement={this.maybeRenderClearButton(listProps.query)}
+                {...inputProps}
+                inputRef={this.handleInputRef}
+                onChange={listProps.handleQueryChange}
+                value={listProps.query}
+            />
+        );
+
+        const { handleKeyDown, handleKeyUp } = listProps;
+        return (
+            <Popover2
+                autoFocus={false}
+                enforceFocus={false}
+                isOpen={this.state.isOpen}
+                disabled={disabled}
+                position={Position.BOTTOM_LEFT}
+                {...popoverProps}
+                className={classNames(listProps.className, popoverProps.className)}
+                content={
+                    <div onKeyDown={handleKeyDown} onKeyUp={handleKeyUp}>
+                        {filterable ? input : undefined}
+                        {listProps.itemList}
+                    </div>
+                }
+                onInteraction={this.handlePopoverInteraction}
+                popoverClassName={classNames(Classes.SELECT_POPOVER, popoverProps.popoverClassName)}
+                onOpening={this.handlePopoverOpening}
+                onOpened={this.handlePopoverOpened}
+                onClosing={this.handlePopoverClosing}
+            >
+                <div
+                    onKeyDown={this.state.isOpen ? handleKeyDown : this.handleTargetKeyDown}
+                    onKeyUp={this.state.isOpen ? handleKeyUp : undefined}
+                >
+                    {this.props.children}
+                </div>
+            </Popover2>
+        );
+    };
+
+    private maybeRenderClearButton(query: string) {
+        return query.length > 0 ? <Button icon="cross" minimal={true} onClick={this.resetQuery} /> : undefined;
+    }
+
+    private handleTargetKeyDown = (event: React.KeyboardEvent<HTMLElement>) => {
+        // open popover when arrow key pressed on target while closed
+        // HACKHACK: https://github.com/palantir/blueprint/issues/4165
+        // eslint-disable-next-line deprecation/deprecation
+        if (event.which === Keys.ARROW_UP || event.which === Keys.ARROW_DOWN) {
+            event.preventDefault();
+            this.setState({ isOpen: true });
+        }
+    };
+
+    private handleItemSelect = (item: T, event?: React.SyntheticEvent<HTMLElement>) => {
+        this.setState({ isOpen: false });
+        this.props.onItemSelect?.(item, event);
+    };
+
+    private handlePopoverInteraction = (isOpen: boolean, event?: React.SyntheticEvent<HTMLElement>) => {
+        this.setState({ isOpen });
+        this.props.popoverProps?.onInteraction?.(isOpen, event);
+    };
+
+    private handlePopoverOpening = (node: HTMLElement) => {
+        // save currently focused element before popover steals focus, so we can restore it when closing.
+        this.previousFocusedElement = document.activeElement as HTMLElement;
+
+        if (this.props.resetOnClose) {
+            this.resetQuery();
+        }
+
+        this.props.popoverProps?.onOpening?.(node);
+    };
+
+    private handlePopoverOpened = (node: HTMLElement) => {
+        // scroll active item into view after popover transition completes and all dimensions are stable.
+        if (this.queryList != null) {
+            this.queryList.scrollActiveItemIntoView();
+        }
+
+        this.requestAnimationFrame(() => {
+            const { inputProps = {} } = this.props;
+            // autofocus is enabled by default
+            if (inputProps.autoFocus !== false) {
+                this.inputElement?.focus();
+            }
+        });
+
+        this.props.popoverProps?.onOpened?.(node);
+    };
+
+    private handlePopoverClosing = (node: HTMLElement) => {
+        // restore focus to saved element.
+        // timeout allows popover to begin closing and remove focus handlers beforehand.
+        /* istanbul ignore next */
+        this.requestAnimationFrame(() => {
+            if (this.previousFocusedElement !== undefined) {
+                this.previousFocusedElement.focus();
+                this.previousFocusedElement = undefined;
+            }
+        });
+
+        this.props.popoverProps?.onClosing?.(node);
+    };
+
+    private resetQuery = () => this.queryList && this.queryList.setQuery("", true);
+}
diff --git a/packages/select/src/index.md b/packages/select/src/index.md
index ebd4739c30..99a9c09c23 100644
--- a/packages/select/src/index.md
+++ b/packages/select/src/index.md
@@ -6,15 +6,17 @@ reference: select
 
 The **@blueprintjs/select** NPM package provides React components related to selecting items from a list:
 
-- [`Select`](#select/select-component) for selecting items in a list.
+- [Select](#select/select-component) for selecting items in a list (DEPRECATED).
 
-- [`Suggest`](#select/suggest) for selecting items in a list, from a text input.
+- [Select2](#select/select2) replacement for Select, uses Popover2 instead of Popover under the hood.
 
-- [`MultiSelect`](#select/multi-select) for selecting multiple items in a list.
+- [Suggest](#select/suggest) for selecting items in a list, from a text input.
 
-- [`Omnibar`](#select/omnibar), a macOS spotlight-style typeahead component.
+- [MultiSelect](#select/multi-select) for selecting multiple items in a list.
 
-- [`QueryList`](#select/query-list), a higher-order component that provides interactions between a query string and a list of items.
+- [Omnibar](#select/omnibar), a macOS spotlight-style typeahead component.
+
+- [QueryList](#select/query-list), a higher-order component that provides interactions between a query string and a list of items.
 
 Make sure to review the [getting started docs for installation info](#blueprint/getting-started).
 
@@ -23,6 +25,7 @@ npm install --save @blueprintjs/select
 ```
 
 @page select-component
+@page select2
 @page suggest
 @page multi-select
 @page omnibar
diff --git a/packages/select/test/index.ts b/packages/select/test/index.ts
index b4887f0bcb..50f4aef4d0 100644
--- a/packages/select/test/index.ts
+++ b/packages/select/test/index.ts
@@ -10,4 +10,5 @@ import "./omnibarTests";
 import "./queryListTests";
 import "./renderFilteredItemsTests";
 import "./selectTests";
+import "./select2Tests";
 import "./suggestTests";
diff --git a/packages/select/test/isotest.js b/packages/select/test/isotest.js
index 5296767d3d..5a817806a6 100644
--- a/packages/select/test/isotest.js
+++ b/packages/select/test/isotest.js
@@ -15,8 +15,9 @@
 
 // @ts-check
 require("@blueprintjs/test-commons/bootstrap");
+
 const { generateIsomorphicTests } = require("@blueprintjs/test-commons");
-const React = require("react");
+
 const Select = require("../lib/cjs");
 
 describe("Select isomorphic rendering", () => {
@@ -32,14 +33,14 @@ describe("Select isomorphic rendering", () => {
         Select: {
             props: { items: [] },
         },
+        Select2: {
+            props: { items: [] },
+        },
         Suggest: {
             props: { items: [] },
         },
         Omnibar: {
             props: { items: [], isOpen: true, overlayProps: { usePortal: false } },
         },
-        QueryList: {
-            skip: true,
-        },
     });
 });
diff --git a/packages/select/test/select2Tests.tsx b/packages/select/test/select2Tests.tsx
new file mode 100644
index 0000000000..13912bca72
--- /dev/null
+++ b/packages/select/test/select2Tests.tsx
@@ -0,0 +1,123 @@
+/*
+ * Copyright 2022 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { assert } from "chai";
+import { mount } from "enzyme";
+import * as React from "react";
+import * as sinon from "sinon";
+
+import { InputGroup, Keys } from "@blueprintjs/core";
+import { Popover2 } from "@blueprintjs/popover2";
+
+import { IFilm, renderFilm, TOP_100_FILMS } from "../../docs-app/src/common/films";
+import { IItemRendererProps, Select2, Select2Props, Select2State } from "../src";
+import { selectComponentSuite } from "./selectComponentSuite";
+
+describe("<Select2>", () => {
+    const FilmSelect = Select2.ofType<IFilm>();
+    const defaultProps = {
+        items: TOP_100_FILMS,
+        popoverProps: { isOpen: true, usePortal: false },
+        query: "",
+    };
+    let handlers: {
+        itemPredicate: sinon.SinonSpy<[string, IFilm], boolean>;
+        itemRenderer: sinon.SinonSpy<[IFilm, IItemRendererProps], JSX.Element | null>;
+        onItemSelect: sinon.SinonSpy;
+    };
+
+    beforeEach(() => {
+        handlers = {
+            itemPredicate: sinon.spy(filterByYear),
+            itemRenderer: sinon.spy(renderFilm),
+            onItemSelect: sinon.spy(),
+        };
+    });
+
+    selectComponentSuite<Select2Props<IFilm>, Select2State>(props =>
+        mount(<Select2 {...props} popoverProps={{ isOpen: true, usePortal: false }} />),
+    );
+
+    it("renders a Popover2 around children that contains InputGroup and items", () => {
+        const wrapper = select();
+        assert.lengthOf(wrapper.find(InputGroup), 1, "should render InputGroup");
+        assert.lengthOf(wrapper.find(Popover2), 1, "should render Popover2");
+    });
+
+    it("filterable=false hides InputGroup", () => {
+        const wrapper = select({ filterable: false });
+        assert.lengthOf(wrapper.find(InputGroup), 0, "should not render InputGroup");
+        assert.lengthOf(wrapper.find(Popover2), 1, "should render Popover2");
+    });
+
+    it("disabled=true disables Popover2", () => {
+        const wrapper = select({ disabled: true });
+        assert.strictEqual(wrapper.find(Popover2).prop("disabled"), true);
+    });
+
+    it("disabled=true doesn't call itemRenderer", () => {
+        select({ disabled: true });
+        assert.equal(handlers.itemRenderer.callCount, 0);
+    });
+
+    it("disabled=false calls itemRenderer", () => {
+        select({ disabled: false });
+        assert.equal(handlers.itemRenderer.callCount, 100);
+    });
+
+    it("inputProps value and onChange are ignored", () => {
+        const inputProps = { value: "nailed it", onChange: sinon.spy() };
+        const input = select({ inputProps }).find("input");
+        assert.notEqual(input.prop("onChange"), inputProps.onChange);
+        assert.notEqual(input.prop("value"), inputProps.value);
+    });
+
+    it("Popover2 can be controlled with popoverProps", () => {
+        // Select defines its own onOpening so this ensures that the passthrough happens
+        const onOpening = sinon.spy();
+        const modifiers = {}; // our own instance
+        const wrapper = select({ popoverProps: { onOpening, modifiers } });
+        wrapper.find("[data-testid='target-button']").simulate("click");
+        assert.strictEqual(wrapper.find(Popover2).prop("modifiers"), modifiers);
+        assert.isTrue(onOpening.calledOnce);
+    });
+
+    // TODO(adahiya): move into selectComponentSuite, generalize for Suggest & MultiSelect
+    it("opens Popover2 when arrow key pressed on target while closed", () => {
+        const wrapper = select({ popoverProps: { usePortal: false } });
+        // should be closed to start
+        assert.strictEqual(wrapper.find(Popover2).prop("isOpen"), false);
+        wrapper.find("[data-testid='target-button']").simulate("keydown", { which: Keys.ARROW_DOWN });
+        // ...then open after key down
+        assert.strictEqual(wrapper.find(Popover2).prop("isOpen"), true);
+    });
+
+    function select(props: Partial<Select2Props<IFilm>> = {}, query?: string) {
+        const wrapper = mount(
+            <FilmSelect {...defaultProps} {...handlers} {...props}>
+                <button data-testid="target-button">Target</button>
+            </FilmSelect>,
+        );
+        if (query !== undefined) {
+            wrapper.setState({ query });
+        }
+        return wrapper;
+    }
+});
+
+function filterByYear(query: string, film: IFilm) {
+    return query === "" || film.year.toString() === query;
+}
diff --git a/packages/select/test/selectTests.tsx b/packages/select/test/selectTests.tsx
index 721a163747..4bae9c129f 100644
--- a/packages/select/test/selectTests.tsx
+++ b/packages/select/test/selectTests.tsx
@@ -19,7 +19,7 @@ import { mount } from "enzyme";
 import * as React from "react";
 import * as sinon from "sinon";
 
-import { InputGroup, Popover } from "@blueprintjs/core";
+import { InputGroup, Keys, Popover } from "@blueprintjs/core";
 
 import { IFilm, renderFilm, TOP_100_FILMS } from "../../docs-app/src/common/films";
 import { IItemRendererProps, ISelectProps, ISelectState, Select } from "../src";
@@ -92,18 +92,26 @@ describe("<Select>", () => {
         const onOpening = sinon.spy();
         const modifiers = {}; // our own instance
         const wrapper = select({ popoverProps: { onOpening, modifiers } });
-        wrapper.find("article").simulate("click");
+        wrapper.find("[data-testid='target-button']").simulate("click");
         /* eslint-disable-next-line deprecation/deprecation */
         assert.strictEqual(wrapper.find(Popover).prop("modifiers"), modifiers);
         assert.isTrue(onOpening.calledOnce);
     });
 
-    it("returns focus to focusable target after popover closed");
+    // TODO(adahiya): move into selectComponentSuite, generalize for Suggest & MultiSelect
+    it("opens popover when arrow key pressed on target while closed", () => {
+        const wrapper = select({ popoverProps: { usePortal: false } });
+        // should be closed to start
+        assert.strictEqual(wrapper.find(Popover).prop("isOpen"), false);
+        wrapper.find("[data-testid='target-button']").simulate("keydown", { which: Keys.ARROW_DOWN });
+        // ...then open after key down
+        assert.strictEqual(wrapper.find(Popover).prop("isOpen"), true);
+    });
 
     function select(props: Partial<ISelectProps<IFilm>> = {}, query?: string) {
         const wrapper = mount(
             <FilmSelect {...defaultProps} {...handlers} {...props}>
-                <article />
+                <button data-testid="target-button">Target</button>
             </FilmSelect>,
         );
         if (query !== undefined) {