[select] itemListRenderer

packages/select/src/common/itemListRenderer.ts

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2017 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the terms of the LICENSE file distributed with this project.
+ */
+
+/**
+ * An object describing how to render the list of items.
+ * An `itemListRenderer` receives this object as its sole argument.
+ */
+export interface IItemListRendererProps<T> {
+    /**
+     * Array of items filtered by `itemListPredicate` or `itemPredicate`.
+     * See `items` for the full list of items.
+     */
+    filteredItems: T[];
+
+    /**
+     * Array of all items in the list.
+     *  See `filteredItems` for a filtered array based on `query` and predicate props.
+     */
+    items: T[];
+
+    /**
+     * The current query string.
+     */
+    query: string;
+
+    /**
+     * A ref handler that should be attached to the parent HTML element of the menu items.
+     * This is required for the active item to scroll into view automatically.
+     */
+    itemsParentRef: (ref: HTMLElement | null) => void;
+
+    /**
+     * Call this function to render an item.
+     * This retrieves the modifiers for the item and delegates actual rendering
+     * to the owner component's `itemRenderer` prop.
+     */
+    renderItem: (item: T, index?: number) => JSX.Element | null;
+}
+
+/** Type alias for a function that renders the list of items. */
+export type ItemListRenderer<T> = (itemListProps: IItemListRendererProps<T>) => JSX.Element;

packages/select/src/components/omnibar/omnibar.tsx

@@ -15,7 +15,6 @@ import {
     InputGroup,
     IOverlayableProps,
     IOverlayProps,
-    Menu,
     Overlay,
     Utils,
 } from "@blueprintjs/core";
@@ -24,14 +23,6 @@ import * as Classes from "../../common/classes";
 import { IListItemsProps, IQueryListRendererProps, QueryList } from "../query-list/queryList";
 
 export interface IOmnibarProps<T> extends IListItemsProps<T> {
-    /**
-     * React child to render when query is empty.
-     */
-    initialContent?: React.ReactChild;
-
-    /** React child to render when filtering items returns zero results. */
-    noResults?: React.ReactChild;
-
     /**
      * Props to spread to `InputGroup`. All props are supported except `ref` (use `inputRef` instead).
      * If you want to control the filter input, you can pass `value` and `onChange` here
@@ -90,11 +81,12 @@ export class Omnibar<T> extends React.PureComponent<IOmnibarProps<T>, IOmnibarSt
 
     public render() {
         // omit props specific to this component, spread the rest.
-        const { initialContent, isOpen, inputProps, noResults, overlayProps, ...restProps } = this.props;
+        const { initialContent = null, isOpen, inputProps, overlayProps, ...restProps } = this.props;
 
         return (
             <this.TypedQueryList
                 {...restProps}
+                initialContent={initialContent}
                 activeItem={this.state.activeItem}
                 onActiveItemChange={this.handleActiveItemChange}
                 onItemSelect={this.handleItemSelect}
@@ -138,34 +130,12 @@ export class Omnibar<T> extends React.PureComponent<IOmnibarProps<T>, IOmnibarSt
                         {...inputProps}
                         onChange={this.handleQueryChange}
                     />
-                    {this.maybeRenderMenu(listProps)}
+                    {listProps.itemList}
                 </div>
             </Overlay>
         );
     };
 
-    private renderItems({ items, renderItem }: IQueryListRendererProps<T>) {
-        const renderedItems = items.map(renderItem).filter(item => item != null);
-        return renderedItems.length > 0 ? renderedItems : this.props.noResults;
-    }
-
-    private maybeRenderMenu(listProps: IQueryListRendererProps<T>) {
-        const { initialContent } = this.props;
-        let menuChildren: any;
-
-        if (!this.isQueryEmpty()) {
-            menuChildren = this.renderItems(listProps);
-        } else if (initialContent != null) {
-            menuChildren = initialContent;
-        }
-
-        if (menuChildren != null) {
-            return <Menu ulRef={listProps.itemsParentRef}>{menuChildren}</Menu>;
-        }
-
-        return undefined;
-    }
-
     private isQueryEmpty = () => this.state.query.length === 0;
 
     private handleActiveItemChange = (activeItem?: T) => this.setState({ activeItem });

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

@@ -6,7 +6,8 @@
 
 import * as React from "react";
 
-import { IProps, Keys, Utils } from "@blueprintjs/core";
+import { IProps, Keys, Menu, Utils } from "@blueprintjs/core";
+import { IItemListRendererProps, ItemListRenderer } from "../../common/itemListRenderer";
 import { IItemModifiers, ItemRenderer } from "../../common/itemRenderer";
 import { ItemListPredicate, ItemPredicate } from "../../common/predicate";
 
@@ -20,7 +21,7 @@ export interface IListItemsProps<T> extends IProps {
      * This method can reorder, add, or remove items at will.
      * (Supports filter algorithms that operate on the entire set, rather than individual items.)
      *
-     * If defined with `itemPredicate`, this prop takes priority and the other will be ignored.
+     * If `itemPredicate` is also defined, this prop takes priority and the other will be ignored.
      */
     itemListPredicate?: ItemListPredicate<T>;
 
@@ -29,7 +30,7 @@ export interface IListItemsProps<T> extends IProps {
      * This method will be invoked once for each item, so it should be performant. For more complex
      * queries, use `itemListPredicate` to operate once on the entire array.
      *
-     * If defined with `itemListPredicate`, this prop will be ignored.
+     * This prop is ignored if `itemListPredicate` is also defined.
      */
     itemPredicate?: ItemPredicate<T>;
 
@@ -40,6 +41,32 @@ export interface IListItemsProps<T> extends IProps {
      */
     itemRenderer: ItemRenderer<T>;
 
+    /**
+     * Custom renderer for the contents of the dropdown.
+     *
+     * The default implementation invokes `itemRenderer` for each item that passes the predicate
+     * and wraps them all in a `Menu` element. If the query is empty then `initialContent` is returned,
+     * and if all items are filtered away then `noResults` is returned.
+     */
+    itemListRenderer?: ItemListRenderer<T>;
+
+    /**
+     * React content to render when query is empty.
+     * If omitted, all items will be rendered (or result of `itemListPredicate` with empty query).
+     * If explicit `null`, nothing will be rendered when query is empty.
+     *
+     * This prop is ignored if a custom `menuRenderer` is supplied.
+     */
+    initialContent?: React.ReactNode | null;
+
+    /**
+     * React content to render when filtering items returns zero results.
+     * If omitted, nothing will be rendered in this case.
+     *
+     * This prop is ignored if a custom `menuRenderer` is supplied.
+     */
+    noResults?: React.ReactNode;
+
     /**
      * Callback invoked when an item from the list is selected,
      * typically by clicking or pressing `enter` key.
@@ -89,8 +116,16 @@ export interface IQueryListProps<T> extends IListItemsProps<T> {
     query: string;
 }
 
-/** Interface for object passed to `QueryList` `renderer` function. */
+/**
+ * An object describing how to render a `QueryList`.
+ * A `QueryList` `renderer` receives this object as its sole argument.
+ */
 export interface IQueryListRendererProps<T> extends IProps {
+    /**
+     * Array of items filtered by `itemListPredicate` or `itemPredicate`.
+     */
+    filteredItems: T[];
+
     /**
      * Selection handler that should be invoked when a new item has been chosen,
      * perhaps because the user clicked it.
@@ -109,29 +144,10 @@ export interface IQueryListRendererProps<T> extends IProps {
      */
     handleKeyUp: React.KeyboardEventHandler<HTMLElement>;
 
-    /**
-     * Call this function to render an `item`.
-     * `QueryList` will retrieve modifiers for the item and delegate to `itemRenderer` prop for the actual rendering.
-     * The second parameter `index` is optional here; if provided, it will be passed through `itemRenderer` props.
-     */
-    renderItem: (item: T, index?: number) => JSX.Element | null;
-
-    /**
-     * Array of all (unfiltered) items in the list.
-     * See `filteredItems` for a filtered array based on `query`.
-     */
-    items: T[];
-
-    /**
-     * A ref handler that should be applied to the HTML element that contains the rendererd items.
-     * This is required for the `QueryList` to scroll the active item into view automatically.
-     */
-    itemsParentRef: (ref: HTMLElement | null) => void;
+    /** Rendered elements returned from `menuRenderer` prop. */
+    itemList: React.ReactNode;
 
-    /**
-     * Controlled query string. Attach an `onChange` handler to the relevant
-     * element to control this prop from your application's state.
-     */
+    /** The current query string. */
     query: string;
 }
 
@@ -146,6 +162,22 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         return QueryList as new (props: IQueryListProps<T>) => QueryList<T>;
     }
 
+    /**
+     * Helper method for rendering `props.filteredItems`, with optional support for `noResults`
+     * (when filtered items is empty) and `initialContent` (when query is empty).
+     */
+    public static renderFilteredItems(
+        props: IItemListRendererProps<any>,
+        noResults?: React.ReactNode,
+        initialContent?: React.ReactNode | null,
+    ): React.ReactNode {
+        if (props.query.length === 0 && initialContent !== undefined) {
+            return initialContent;
+        }
+        const items = props.filteredItems.map(props.renderItem).filter(item => item != null);
+        return items.length > 0 ? items : noResults;
+    }
+
     private itemsParentRef?: HTMLElement | null;
     private refHandlers = {
         itemsParent: (ref: HTMLElement | null) => (this.itemsParentRef = ref),
@@ -158,16 +190,22 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
     private shouldCheckActiveItemInViewport: boolean = false;
 
     public render() {
-        const { className, items, renderer, query } = this.props;
+        const { className, items, renderer, query, itemListRenderer = this.defaultMenuRenderer } = this.props;
+        const { filteredItems } = this.state;
         return renderer({
             className,
+            filteredItems,
             handleItemSelect: this.handleItemSelect,
             handleKeyDown: this.handleKeyDown,
             handleKeyUp: this.handleKeyUp,
-            items,
-            itemsParentRef: this.refHandlers.itemsParent,
+            itemList: itemListRenderer({
+                filteredItems,
+                items,
+                itemsParentRef: this.refHandlers.itemsParent,
+                query,
+                renderItem: this.renderItem,
+            }),
             query,
-            renderItem: this.renderItem,
         });
     }
 
@@ -231,6 +269,28 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         }
     }
 
+    private defaultMenuRenderer = (listProps: IItemListRendererProps<T>) => {
+        const { initialContent, noResults } = this.props;
+        const menuContent = QueryList.renderFilteredItems(listProps, noResults, initialContent);
+        return <Menu ulRef={listProps.itemsParentRef}>{menuContent}</Menu>;
+    };
+
+    private renderItem = (item: T, index?: number) => {
+        const { activeItem, query } = this.props;
+        const matchesPredicate = this.state.filteredItems.indexOf(item) >= 0;
+        const modifiers: IItemModifiers = {
+            active: activeItem === item,
+            disabled: false,
+            matchesPredicate,
+        };
+        return this.props.itemRenderer(item, {
+            handleClick: e => this.handleItemSelect(item, e),
+            index,
+            modifiers,
+            query,
+        });
+    };
+
     private getActiveElement() {
         if (this.itemsParentRef != null) {
             return this.itemsParentRef.children.item(this.getActiveIndex()) as HTMLElement;
@@ -295,24 +355,6 @@ export class QueryList<T> extends React.Component<IQueryListProps<T>, IQueryList
         const nextActiveIndex = Utils.clamp(this.getActiveIndex() + direction, 0, maxIndex);
         Utils.safeInvoke(this.props.onActiveItemChange, filteredItems[nextActiveIndex]);
     }
-
-    private renderItem = (item: T, index?: number) => {
-        const { activeItem, itemListPredicate, itemPredicate = () => true, query } = this.props;
-        const matchesPredicate = Utils.isFunction(itemListPredicate)
-            ? this.state.filteredItems.indexOf(item) >= 0
-            : itemPredicate(query, item, index);
-        const modifiers: IItemModifiers = {
-            active: activeItem === item,
-            disabled: false,
-            matchesPredicate,
-        };
-        return this.props.itemRenderer(item, {
-            handleClick: e => this.handleItemSelect(item, e),
-            index,
-            modifiers,
-            query,
-        });
-    };
 }
 
 function pxToNumber(value: string | null) {