1 | /**
|
2 | * @license
|
3 | * Copyright 2020 Google Inc.
|
4 | *
|
5 | * Permission is hereby granted, free of charge, to any person obtaining a copy
|
6 | * of this software and associated documentation files (the "Software"), to deal
|
7 | * in the Software without restriction, including without limitation the rights
|
8 | * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
9 | * copies of the Software, and to permit persons to whom the Software is
|
10 | * furnished to do so, subject to the following conditions:
|
11 | *
|
12 | * The above copyright notice and this permission notice shall be included in
|
13 | * all copies or substantial portions of the Software.
|
14 | *
|
15 | * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16 | * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
17 | * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
18 | * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
19 | * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
20 | * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
21 | * THE SOFTWARE.
|
22 | */
|
23 | import { MDCListTextAndIndex } from './types';
|
24 | /**
|
25 | * State of a typeahead instance.
|
26 | */
|
27 | export interface TypeaheadState {
|
28 | typeaheadBuffer: string;
|
29 | currentFirstChar: string;
|
30 | sortedIndexCursor: number;
|
31 | bufferClearTimeout: number;
|
32 | }
|
33 | /**
|
34 | * Initializes a state object for typeahead. Use the same reference for calls to
|
35 | * typeahead functions.
|
36 | *
|
37 | * @return The current state of the typeahead process. Each state reference
|
38 | * represents a typeahead instance as the reference is typically mutated
|
39 | * in-place.
|
40 | */
|
41 | export declare function initState(): TypeaheadState;
|
42 | /**
|
43 | * Initializes typeahead state by indexing the current list items by primary
|
44 | * text into the sortedIndexByFirstChar data structure.
|
45 | *
|
46 | * @param listItemCount numer of items in the list
|
47 | * @param getPrimaryTextByItemIndex function that returns the primary text at a
|
48 | * given index
|
49 | *
|
50 | * @return Map that maps the first character of the primary text to the full
|
51 | * list text and it's index
|
52 | */
|
53 | export declare function initSortedIndex(listItemCount: number, getPrimaryTextByItemIndex: (index: number) => string): Map<string, MDCListTextAndIndex[]>;
|
54 | /**
|
55 | * Arguments for matchItem
|
56 | */
|
57 | export interface TypeaheadMatchItemOpts {
|
58 | focusItemAtIndex: (index: number) => void;
|
59 | nextChar: string;
|
60 | focusedItemIndex: number;
|
61 | sortedIndexByFirstChar: Map<string, MDCListTextAndIndex[]>;
|
62 | skipFocus: boolean;
|
63 | isItemAtIndexDisabled: (index: number) => boolean;
|
64 | }
|
65 | /**
|
66 | * Given the next desired character from the user, it attempts to find the next
|
67 | * list option matching the buffer. Wraps around if at the end of options.
|
68 | *
|
69 | * @param opts Options and accessors
|
70 | * - nextChar - the next character to match against items
|
71 | * - sortedIndexByFirstChar - output of `initSortedIndex(...)`
|
72 | * - focusedItemIndex - the index of the currently focused item
|
73 | * - focusItemAtIndex - function that focuses a list item at given index
|
74 | * - skipFocus - whether or not to focus the matched item
|
75 | * - isItemAtIndexDisabled - function that determines whether an item at a
|
76 | * given index is disabled
|
77 | * @param state The typeahead state instance. See `initState`.
|
78 | *
|
79 | * @return The index of the matched item, or -1 if no match.
|
80 | */
|
81 | export declare function matchItem(opts: TypeaheadMatchItemOpts, state: TypeaheadState): number;
|
82 | /**
|
83 | * Whether or not the given typeahead instaance state is currently typing.
|
84 | *
|
85 | * @param state The typeahead state instance. See `initState`.
|
86 | */
|
87 | export declare function isTypingInProgress(state: TypeaheadState): boolean;
|
88 | /**
|
89 | * Options for handleKeydown.
|
90 | */
|
91 | export interface HandleKeydownOpts {
|
92 | event: KeyboardEvent;
|
93 | isTargetListItem: boolean;
|
94 | focusItemAtIndex: (index: number) => void;
|
95 | focusedItemIndex: number;
|
96 | sortedIndexByFirstChar: Map<string, MDCListTextAndIndex[]>;
|
97 | isItemAtIndexDisabled: (index: number) => boolean;
|
98 | }
|
99 | /**
|
100 | * Clears the typeahaed buffer so that it resets item matching to the first
|
101 | * character.
|
102 | *
|
103 | * @param state The typeahead state instance. See `initState`.
|
104 | */
|
105 | export declare function clearBuffer(state: TypeaheadState): void;
|
106 | /**
|
107 | * Given a keydown event, it calculates whether or not to automatically focus a
|
108 | * list item depending on what was typed mimicing the typeahead functionality of
|
109 | * a standard <select> element that is open.
|
110 | *
|
111 | * @param opts Options and accessors
|
112 | * - event - the KeyboardEvent to handle and parse
|
113 | * - sortedIndexByFirstChar - output of `initSortedIndex(...)`
|
114 | * - focusedItemIndex - the index of the currently focused item
|
115 | * - focusItemAtIndex - function that focuses a list item at given index
|
116 | * - isItemAtFocusedIndexDisabled - whether or not the currently focused item
|
117 | * is disabled
|
118 | * - isTargetListItem - whether or not the event target is a list item
|
119 | * @param state The typeahead state instance. See `initState`.
|
120 | *
|
121 | * @returns index of the item matched by the keydown. -1 if not matched.
|
122 | */
|
123 | export declare function handleKeydown(opts: HandleKeydownOpts, state: TypeaheadState): number;
|