[select] itemListRenderer

packages/select/src/common/index.ts

@@ -0,0 +1,13 @@
+/*
+ * Copyright 2018 Palantir Technologies, Inc. All rights reserved.
+ *
+ * Licensed under the terms of the LICENSE file distributed with this project.
+ */
+
+import * as Classes from "./classes";
+export { Classes };
+
+export * from "./itemListRenderer";
+export * from "./itemRenderer";
+export * from "./listItemsProps";
+export * from "./predicate";

packages/select/src/common/itemListRenderer.ts

@@ -0,0 +1,65 @@
+/*
+ * 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.
+     *
+     * Use `renderFilteredItems()` utility function from this library to
+     * map each item in this array through `renderItem`, with support for
+     * optional `noResults` and `initialContent` states.
+     */
+    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;
+
+/**
+ * `ItemListRenderer` helper method for rendering each item in `filteredItems`,
+ * with optional support for `noResults` (when filtered items is empty)
+ * and `initialContent` (when query is empty).
+ */
+export function 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;
+}

packages/select/src/common/listItemsProps.ts

@@ -0,0 +1,73 @@
+/*
+* Copyright 2018 Palantir Technologies, Inc. All rights reserved.
+*
+* Licensed under the terms of the LICENSE file distributed with this project.
+*/
+
+import { IProps } from "@blueprintjs/core";
+import { ItemListRenderer } from "./itemListRenderer";
+import { ItemRenderer } from "./itemRenderer";
+import { ItemListPredicate, ItemPredicate } from "./predicate";
+
+/** Reusable generic props for a component that operates on a filterable, selectable list of `items`. */
+export interface IListItemsProps<T> extends IProps {
+    /** Array of items in the list. */
+    items: T[];
+
+    /**
+     * Customize querying of entire `items` array. Return new list of items.
+     * This method can reorder, add, or remove items at will.
+     * (Supports filter algorithms that operate on the entire set, rather than individual items.)
+     *
+     * If `itemPredicate` is also defined, this prop takes priority and the other will be ignored.
+     */
+    itemListPredicate?: ItemListPredicate<T>;
+
+    /**
+     * Customize querying of individual items. Return `true` to keep the item, `false` to hide.
+     * 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.
+     *
+     * This prop is ignored if `itemListPredicate` is also defined.
+     */
+    itemPredicate?: ItemPredicate<T>;
+
+    /**
+     * Custom renderer for an item in the dropdown list. Receives a boolean indicating whether
+     * this item is active (selected by keyboard arrows) and an `onClick` event handler that
+     * should be attached to the returned element.
+     */
+    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 there are no items that match the predicate 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 `itemListRenderer` 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 `itemListRenderer` is supplied.
+     */
+    noResults?: React.ReactNode;
+
+    /**
+     * Callback invoked when an item from the list is selected,
+     * typically by clicking or pressing `enter` key.
+     */
+    onItemSelect: (item: T, event?: React.SyntheticEvent<HTMLElement>) => void;
+}

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

@@ -15,23 +15,14 @@ import {
     InputGroup,
     IOverlayableProps,
     IOverlayProps,
-    Menu,
     Overlay,
     Utils,
 } from "@blueprintjs/core";
 
-import * as Classes from "../../common/classes";
-import { IListItemsProps, IQueryListRendererProps, QueryList } from "../query-list/queryList";
+import { Classes, IListItemsProps } from "../../common";
+import { 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,12 +81,13 @@ 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}
                 activeItem={this.state.activeItem}
+                initialContent={initialContent}
                 onActiveItemChange={this.handleActiveItemChange}
                 onItemSelect={this.handleItemSelect}
                 query={this.state.query}
@@ -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 });