1 | import * as React from "react";
|
2 | import { AbstractComponent2, Props } from "@blueprintjs/core";
|
3 | import { ICreateNewItem, IListItemsProps } from "../../common";
|
4 | export declare type QueryListProps<T> = IQueryListProps<T>;
|
5 | /** @deprecated use QueryListProps */
|
6 | export interface IQueryListProps<T> extends IListItemsProps<T> {
|
7 | /**
|
8 | * Initial active item, useful if the parent component is controlling its selectedItem but
|
9 | * not activeItem.
|
10 | */
|
11 | initialActiveItem?: T;
|
12 | /**
|
13 | * Callback invoked when user presses a key, after processing `QueryList`'s own key events
|
14 | * (up/down to navigate active item). This callback is passed to `renderer` and (along with
|
15 | * `onKeyUp`) can be attached to arbitrary content elements to support keyboard selection.
|
16 | */
|
17 | onKeyDown?: React.KeyboardEventHandler<HTMLElement>;
|
18 | /**
|
19 | * Callback invoked when user releases a key, after processing `QueryList`'s own key events
|
20 | * (enter to select active item). This callback is passed to `renderer` and (along with
|
21 | * `onKeyDown`) can be attached to arbitrary content elements to support keyboard selection.
|
22 | */
|
23 | onKeyUp?: React.KeyboardEventHandler<HTMLElement>;
|
24 | /**
|
25 | * Customize rendering of the component.
|
26 | * Receives an object with props that should be applied to elements as necessary.
|
27 | */
|
28 | renderer: (listProps: IQueryListRendererProps<T>) => JSX.Element;
|
29 | /**
|
30 | * Whether the list is disabled.
|
31 | *
|
32 | * @default false
|
33 | */
|
34 | disabled?: boolean;
|
35 | }
|
36 | /**
|
37 | * An object describing how to render a `QueryList`.
|
38 | * A `QueryList` `renderer` receives this object as its sole argument.
|
39 | */
|
40 | export interface IQueryListRendererProps<T>// Omit `createNewItem`, because it's used strictly for internal tracking.
|
41 | extends Pick<IQueryListState<T>, "activeItem" | "filteredItems" | "query">, Props {
|
42 | /**
|
43 | * Selection handler that should be invoked when a new item has been chosen,
|
44 | * perhaps because the user clicked it.
|
45 | */
|
46 | handleItemSelect: (item: T, event?: React.SyntheticEvent<HTMLElement>) => void;
|
47 | /**
|
48 | * Handler that should be invoked when the user pastes one or more values.
|
49 | *
|
50 | * This callback will use `itemPredicate` with `exactMatch=true` to find a
|
51 | * subset of `items` exactly matching the pasted `values` provided, then it
|
52 | * will invoke `onItemsPaste` with those found items. Each pasted value that
|
53 | * does not exactly match an item will be ignored.
|
54 | *
|
55 | * If creating items is enabled (by providing both `createNewItemFromQuery`
|
56 | * and `createNewItemRenderer`), then pasted values that do not exactly
|
57 | * match an existing item will emit a new item as created via
|
58 | * `createNewItemFromQuery`.
|
59 | *
|
60 | * If `itemPredicate` returns multiple matching items for a particular query
|
61 | * in `queries`, then only the first matching item will be emitted.
|
62 | */
|
63 | handlePaste: (queries: string[]) => void;
|
64 | /**
|
65 | * Keyboard handler for up/down arrow keys to shift the active item.
|
66 | * Attach this handler to any element that should support this interaction.
|
67 | */
|
68 | handleKeyDown: React.KeyboardEventHandler<HTMLElement>;
|
69 | /**
|
70 | * Keyboard handler for enter key to select the active item.
|
71 | * Attach this handler to any element that should support this interaction.
|
72 | */
|
73 | handleKeyUp: React.KeyboardEventHandler<HTMLElement>;
|
74 | /**
|
75 | * Change handler for query string. Attach this to an input element to allow
|
76 | * `QueryList` to control the query.
|
77 | */
|
78 | handleQueryChange: React.ChangeEventHandler<HTMLInputElement>;
|
79 | /** Rendered elements returned from `itemListRenderer` prop. */
|
80 | itemList: React.ReactNode;
|
81 | }
|
82 | export interface IQueryListState<T> {
|
83 | /** The currently focused item (for keyboard interactions). */
|
84 | activeItem: T | ICreateNewItem | null;
|
85 | /**
|
86 | * The item returned from `createNewItemFromQuery(this.state.query)`, cached
|
87 | * to avoid continuous reinstantions within `isCreateItemRendered`, where
|
88 | * this element will be used to hide the "Create Item" option if its value
|
89 | * matches the current `query`.
|
90 | */
|
91 | createNewItem: T | undefined;
|
92 | /** The original `items` array filtered by `itemListPredicate` or `itemPredicate`. */
|
93 | filteredItems: T[];
|
94 | /** The current query string. */
|
95 | query: string;
|
96 | }
|
97 | export declare class QueryList<T> extends AbstractComponent2<QueryListProps<T>, IQueryListState<T>> {
|
98 | static displayName: string;
|
99 | static defaultProps: {
|
100 | disabled: boolean;
|
101 | resetOnQuery: boolean;
|
102 | };
|
103 | static ofType<U>(): new (props: QueryListProps<U>) => QueryList<U>;
|
104 | private itemsParentRef?;
|
105 | private refHandlers;
|
106 | /**
|
107 | * Flag indicating that we should check whether selected item is in viewport
|
108 | * after rendering, typically because of keyboard change. Set to `true` when
|
109 | * manipulating state in a way that may cause active item to scroll away.
|
110 | */
|
111 | private shouldCheckActiveItemInViewport;
|
112 | /**
|
113 | * The item that we expect to be the next selected active item (based on click
|
114 | * or key interactions). When scrollToActiveItem = false, used to detect if
|
115 | * an unexpected external change to the active item has been made.
|
116 | */
|
117 | private expectedNextActiveItem;
|
118 | /**
|
119 | * Flag which is set to true while in between an ENTER "keydown" event and its
|
120 | * corresponding "keyup" event.
|
121 | *
|
122 | * When entering text via an IME (https://en.wikipedia.org/wiki/Input_method),
|
123 | * the ENTER key is pressed to confirm the character(s) to be input from a list
|
124 | * of options. The operating system intercepts the ENTER "keydown" event and
|
125 | * prevents it from propagating to the application, but "keyup" is still
|
126 | * fired, triggering a spurious event which this component does not expect.
|
127 | *
|
128 | * To work around this quirk, we keep track of "real" key presses by setting
|
129 | * this flag in handleKeyDown.
|
130 | */
|
131 | private isEnterKeyPressed;
|
132 | constructor(props: QueryListProps<T>, context?: any);
|
133 | render(): JSX.Element;
|
134 | componentDidUpdate(prevProps: QueryListProps<T>): void;
|
135 | scrollActiveItemIntoView(): void;
|
136 | setQuery(query: string, resetActiveItem?: boolean | undefined, props?: Readonly<QueryListProps<T>> & Readonly<{
|
137 | children?: React.ReactNode;
|
138 | }>): void;
|
139 | setActiveItem(activeItem: T | ICreateNewItem | null): void;
|
140 | /** default `itemListRenderer` implementation */
|
141 | private renderItemList;
|
142 | /** wrapper around `itemRenderer` to inject props */
|
143 | private renderItem;
|
144 | private renderCreateItemMenuItem;
|
145 | private getActiveElement;
|
146 | private getActiveIndex;
|
147 | private getItemsParentPadding;
|
148 | private handleItemCreate;
|
149 | private handleItemSelect;
|
150 | private handlePaste;
|
151 | private handleKeyDown;
|
152 | private handleKeyUp;
|
153 | private handleInputQueryChange;
|
154 | /**
|
155 | * Get the next enabled item, moving in the given direction from the start
|
156 | * index. A `null` return value means no suitable item was found.
|
157 | *
|
158 | * @param direction amount to move in each iteration, typically +/-1
|
159 | * @param startIndex item to start iteration
|
160 | */
|
161 | private getNextActiveItem;
|
162 | private isCreateItemRendered;
|
163 | private isCreateItemFirst;
|
164 | private canCreateItems;
|
165 | private wouldCreatedItemMatchSomeExistingItem;
|
166 | private maybeResetQuery;
|
167 | }
|
168 | /**
|
169 | * Get the next enabled item, moving in the given direction from the start
|
170 | * index. A `null` return value means no suitable item was found.
|
171 | *
|
172 | * @param items the list of items
|
173 | * @param itemDisabled callback to determine if a given item is disabled
|
174 | * @param direction amount to move in each iteration, typically +/-1
|
175 | * @param startIndex which index to begin moving from
|
176 | */
|
177 | export declare function getFirstEnabledItem<T>(items: T[], itemDisabled?: keyof T | ((item: T, index: number) => boolean), direction?: number, startIndex?: number): T | ICreateNewItem | null;
|