1 | import * as React from 'react';
|
2 |
|
3 | export interface CreateFilterOptionsConfig<T> {
|
4 | ignoreAccents?: boolean;
|
5 | ignoreCase?: boolean;
|
6 | limit?: number;
|
7 | matchFrom?: 'any' | 'start';
|
8 | stringify?: (option: T) => string;
|
9 | trim?: boolean;
|
10 | }
|
11 |
|
12 | export interface FilterOptionsState<T> {
|
13 | inputValue: string;
|
14 | getOptionLabel: (option: T) => string;
|
15 | }
|
16 |
|
17 | export function createFilterOptions<T>(
|
18 | config?: CreateFilterOptionsConfig<T>
|
19 | ): (options: T[], state: FilterOptionsState<T>) => T[];
|
20 |
|
21 | export type AutocompleteFreeSoloValueMapping<FreeSolo> = FreeSolo extends true ? string : never;
|
22 |
|
23 | export type Value<T, Multiple, DisableClearable, FreeSolo> = Multiple extends undefined | false
|
24 | ? DisableClearable extends true
|
25 | ? NonNullable<T | AutocompleteFreeSoloValueMapping<FreeSolo>>
|
26 | : T | null | AutocompleteFreeSoloValueMapping<FreeSolo>
|
27 | : Array<T | AutocompleteFreeSoloValueMapping<FreeSolo>>;
|
28 |
|
29 | export interface UseAutocompleteProps<
|
30 | T,
|
31 | Multiple extends boolean | undefined,
|
32 | DisableClearable extends boolean | undefined,
|
33 | FreeSolo extends boolean | undefined
|
34 | > {
|
35 | /**
|
36 | * If `true`, the portion of the selected suggestion that has not been typed by the user,
|
37 | * known as the completion string, appears inline after the input cursor in the textbox.
|
38 | * The inline completion string is visually highlighted and has a selected state.
|
39 | */
|
40 | autoComplete?: boolean;
|
41 | /**
|
42 | * If `true`, the first option is automatically highlighted.
|
43 | */
|
44 | autoHighlight?: boolean;
|
45 | /**
|
46 | * If `true`, the selected option becomes the value of the input
|
47 | * when the Autocomplete loses focus unless the user chooses
|
48 | * a different option or changes the character string in the input.
|
49 | */
|
50 | autoSelect?: boolean;
|
51 | /**
|
52 | * Control if the input should be blurred when an option is selected:
|
53 | *
|
54 | * - `false` the input is not blurred.
|
55 | * - `true` the input is always blurred.
|
56 | * - `touch` the input is blurred after a touch event.
|
57 | * - `mouse` the input is blurred after a mouse event.
|
58 | */
|
59 | blurOnSelect?: 'touch' | 'mouse' | true | false;
|
60 | /**
|
61 | * If `true`, the input's text will be cleared on blur if no value is selected.
|
62 | *
|
63 | * Set to `true` if you want to help the user enter a new value.
|
64 | * Set to `false` if you want to help the user resume his search.
|
65 | */
|
66 | clearOnBlur?: boolean;
|
67 | /**
|
68 | * If `true`, clear all values when the user presses escape and the popup is closed.
|
69 | */
|
70 | clearOnEscape?: boolean;
|
71 | /**
|
72 | * The component name that is using this hook. Used for warnings.
|
73 | */
|
74 | componentName?: string;
|
75 | /**
|
76 | * If `true`, the popup will ignore the blur event if the input is filled.
|
77 | * You can inspect the popup markup with your browser tools.
|
78 | * Consider this option when you need to customize the component.
|
79 | */
|
80 | debug?: boolean;
|
81 | /**
|
82 | * If `true`, the input can't be cleared.
|
83 | */
|
84 | disableClearable?: DisableClearable;
|
85 | /**
|
86 | * If `true`, the popup won't close when a value is selected.
|
87 | */
|
88 | disableCloseOnSelect?: boolean;
|
89 | /**
|
90 | * If `true`, will allow focus on disabled items.
|
91 | */
|
92 | disabledItemsFocusable?: boolean;
|
93 | /**
|
94 | * If `true`, the list box in the popup will not wrap focus.
|
95 | */
|
96 | disableListWrap?: boolean;
|
97 | /**
|
98 | * A filter function that determines the options that are eligible.
|
99 | *
|
100 | * @param {T[]} options The options to render.
|
101 | * @param {object} state The state of the component.
|
102 | * @returns {T[]}
|
103 | */
|
104 | filterOptions?: (options: T[], state: FilterOptionsState<T>) => T[];
|
105 | /**
|
106 | * If `true`, hide the selected options from the list box.
|
107 | */
|
108 | filterSelectedOptions?: boolean;
|
109 | /**
|
110 | * If `true`, the Autocomplete is free solo, meaning that the user input is not bound to provided options.
|
111 | */
|
112 | freeSolo?: FreeSolo;
|
113 | /**
|
114 | * Used to determine the disabled state for a given option.
|
115 | *
|
116 | * @param {T} option The option to test.
|
117 | * @returns {boolean}
|
118 | */
|
119 | getOptionDisabled?: (option: T) => boolean;
|
120 | /**
|
121 | * Used to determine the string value for a given option.
|
122 | * It's used to fill the input (and the list box options if `renderOption` is not provided).
|
123 | *
|
124 | * @param {T} option
|
125 | * @returns {string}
|
126 | */
|
127 | getOptionLabel?: (option: T) => string;
|
128 | /**
|
129 | * Used to determine if an option is selected, considering the current value.
|
130 | * Uses strict equality by default.
|
131 | *
|
132 | * @param {T} option The option to test.
|
133 | * @param {T} value The value to test against.
|
134 | * @returns {boolean}
|
135 | */
|
136 | getOptionSelected?: (option: T, value: T) => boolean;
|
137 | /**
|
138 | * If provided, the options will be grouped under the returned string.
|
139 | * The groupBy value is also used as the text for group headings when `renderGroup` is not provided.
|
140 | *
|
141 | * @param {T} options The options to group.
|
142 | * @returns {string}
|
143 | */
|
144 | groupBy?: (option: T) => string;
|
145 | /**
|
146 | * If `true`, the component handles the "Home" and "End" keys when the popup is open.
|
147 | * It should move focus to the first option and last option, respectively.
|
148 | */
|
149 | handleHomeEndKeys?: boolean;
|
150 | /**
|
151 | * This prop is used to help implement the accessibility logic.
|
152 | * If you don't provide this prop. It falls back to a randomly generated id.
|
153 | */
|
154 | id?: string;
|
155 | /**
|
156 | * If `true`, the highlight can move to the input.
|
157 | */
|
158 | includeInputInList?: boolean;
|
159 | /**
|
160 | * The input value.
|
161 | */
|
162 | inputValue?: string;
|
163 | /**
|
164 | * Callback fired when the popup requests to be closed.
|
165 | * Use in controlled mode (see open).
|
166 | *
|
167 | * @param {object} event The event source of the callback.
|
168 | * @param {string} reason Can be: `"toggleInput"`, `"escape"`, `"select-option"`, `"blur"`.
|
169 | */
|
170 | onClose?: (event: React.ChangeEvent<{}>, reason: AutocompleteCloseReason) => void;
|
171 | /**
|
172 | * Callback fired when the input value changes.
|
173 | *
|
174 | * @param {object} event The event source of the callback.
|
175 | * @param {string} value The new value of the text input.
|
176 | * @param {string} reason Can be: `"input"` (user input), `"reset"` (programmatic change), `"clear"`.
|
177 | */
|
178 | onInputChange?: (
|
179 | event: React.ChangeEvent<{}>,
|
180 | value: string,
|
181 | reason: AutocompleteInputChangeReason
|
182 | ) => void;
|
183 | /**
|
184 | * Callback fired when the popup requests to be opened.
|
185 | * Use in controlled mode (see open).
|
186 | *
|
187 | * @param {object} event The event source of the callback.
|
188 | */
|
189 | onOpen?: (event: React.ChangeEvent<{}>) => void;
|
190 | /**
|
191 | * Callback fired when the highlight option changes.
|
192 | *
|
193 | * @param {object} event The event source of the callback.
|
194 | * @param {T} option The highlighted option.
|
195 | * @param {string} reason Can be: `"keyboard"`, `"auto"`, `"mouse"`.
|
196 | */
|
197 | onHighlightChange?: (
|
198 | event: React.ChangeEvent<{}>,
|
199 | option: T | null,
|
200 | reason: AutocompleteHighlightChangeReason
|
201 | ) => void;
|
202 | /**
|
203 | * Control the popup` open state.
|
204 | */
|
205 | open?: boolean;
|
206 | /**
|
207 | * If `true`, the popup will open on input focus.
|
208 | */
|
209 | openOnFocus?: boolean;
|
210 | /**
|
211 | * Array of options.
|
212 | */
|
213 | options: T[];
|
214 | /**
|
215 | * If `true`, the input's text will be selected on focus.
|
216 | * It helps the user clear the selected value.
|
217 | */
|
218 | selectOnFocus?: boolean;
|
219 | /**
|
220 | * If `true`, `value` must be an array and the menu will support multiple selections.
|
221 | */
|
222 | multiple?: Multiple;
|
223 | /**
|
224 | * The value of the autocomplete.
|
225 | *
|
226 | * The value must have reference equality with the option in order to be selected.
|
227 | * You can customize the equality behavior with the `getOptionSelected` prop.
|
228 | */
|
229 | value?: Value<T, Multiple, DisableClearable, FreeSolo>;
|
230 | /**
|
231 | * The default input value. Use when the component is not controlled.
|
232 | */
|
233 | defaultValue?: Value<T, Multiple, DisableClearable, FreeSolo>;
|
234 | /**
|
235 | * Callback fired when the value changes.
|
236 | *
|
237 | * @param {object} event The event source of the callback.
|
238 | * @param {T|T[]} value The new value of the component.
|
239 | * @param {string} reason One of "create-option", "select-option", "remove-option", "blur" or "clear".
|
240 | */
|
241 | onChange?: (
|
242 | event: React.ChangeEvent<{}>,
|
243 | value: Value<T, Multiple, DisableClearable, FreeSolo>,
|
244 | reason: AutocompleteChangeReason,
|
245 | details?: AutocompleteChangeDetails<T>
|
246 | ) => void;
|
247 | }
|
248 |
|
249 | export type AutocompleteHighlightChangeReason = 'keyboard' | 'mouse' | 'auto';
|
250 |
|
251 | export type AutocompleteChangeReason =
|
252 | | 'create-option'
|
253 | | 'select-option'
|
254 | | 'remove-option'
|
255 | | 'clear'
|
256 | | 'blur';
|
257 | export interface AutocompleteChangeDetails<T = string> {
|
258 | option: T;
|
259 | }
|
260 | export type AutocompleteCloseReason = 'toggleInput' | 'escape' | 'select-option' | 'blur';
|
261 | export type AutocompleteInputChangeReason = 'input' | 'reset' | 'clear';
|
262 |
|
263 | export default function useAutocomplete<
|
264 | T,
|
265 | Multiple extends boolean | undefined = undefined,
|
266 | DisableClearable extends boolean | undefined = undefined,
|
267 | FreeSolo extends boolean | undefined = undefined
|
268 | >(
|
269 | props: UseAutocompleteProps<T, Multiple, DisableClearable, FreeSolo>
|
270 | ): {
|
271 | getRootProps: () => {};
|
272 | getInputProps: () => {};
|
273 | getInputLabelProps: () => {};
|
274 | getClearProps: () => {};
|
275 | getPopupIndicatorProps: () => {};
|
276 | getTagProps: ({ index }: { index: number }) => {};
|
277 | getListboxProps: () => {};
|
278 | getOptionProps: ({ option, index }: { option: T; index: number }) => {};
|
279 | id: string;
|
280 | inputValue: string;
|
281 | value: Value<T, Multiple, DisableClearable, FreeSolo>;
|
282 | dirty: boolean;
|
283 | popupOpen: boolean;
|
284 | focused: boolean;
|
285 | anchorEl: null | HTMLElement;
|
286 | setAnchorEl: () => void;
|
287 | focusedTag: number;
|
288 | groupedOptions: T[];
|
289 | };
|