1 | import { ReadonlyJSONObject } from '@phosphor/coreutils';
|
2 | import { CommandRegistry } from '@phosphor/commands';
|
3 | import { Message } from '@phosphor/messaging';
|
4 | import { ElementDataset, VirtualElement, h } from '@phosphor/virtualdom';
|
5 | import { Widget } from './widget';
|
6 | /**
|
7 | * A widget which displays command items as a searchable palette.
|
8 | */
|
9 | export declare class CommandPalette extends Widget {
|
10 | /**
|
11 | * Construct a new command palette.
|
12 | *
|
13 | * @param options - The options for initializing the palette.
|
14 | */
|
15 | constructor(options: CommandPalette.IOptions);
|
16 | /**
|
17 | * Dispose of the resources held by the widget.
|
18 | */
|
19 | dispose(): void;
|
20 | /**
|
21 | * The command registry used by the command palette.
|
22 | */
|
23 | readonly commands: CommandRegistry;
|
24 | /**
|
25 | * The renderer used by the command palette.
|
26 | */
|
27 | readonly renderer: CommandPalette.IRenderer;
|
28 | /**
|
29 | * The command palette search node.
|
30 | *
|
31 | * #### Notes
|
32 | * This is the node which contains the search-related elements.
|
33 | */
|
34 | readonly searchNode: HTMLDivElement;
|
35 | /**
|
36 | * The command palette input node.
|
37 | *
|
38 | * #### Notes
|
39 | * This is the actual input node for the search area.
|
40 | */
|
41 | readonly inputNode: HTMLInputElement;
|
42 | /**
|
43 | * The command palette content node.
|
44 | *
|
45 | * #### Notes
|
46 | * This is the node which holds the command item nodes.
|
47 | *
|
48 | * Modifying this node directly can lead to undefined behavior.
|
49 | */
|
50 | readonly contentNode: HTMLUListElement;
|
51 | /**
|
52 | * A read-only array of the command items in the palette.
|
53 | */
|
54 | readonly items: ReadonlyArray<CommandPalette.IItem>;
|
55 | /**
|
56 | * Add a command item to the command palette.
|
57 | *
|
58 | * @param options - The options for creating the command item.
|
59 | *
|
60 | * @returns The command item added to the palette.
|
61 | */
|
62 | addItem(options: CommandPalette.IItemOptions): CommandPalette.IItem;
|
63 | /**
|
64 | * Remove an item from the command palette.
|
65 | *
|
66 | * @param item - The item to remove from the palette.
|
67 | *
|
68 | * #### Notes
|
69 | * This is a no-op if the item is not in the palette.
|
70 | */
|
71 | removeItem(item: CommandPalette.IItem): void;
|
72 | /**
|
73 | * Remove the item at a given index from the command palette.
|
74 | *
|
75 | * @param index - The index of the item to remove.
|
76 | *
|
77 | * #### Notes
|
78 | * This is a no-op if the index is out of range.
|
79 | */
|
80 | removeItemAt(index: number): void;
|
81 | /**
|
82 | * Remove all items from the command palette.
|
83 | */
|
84 | clearItems(): void;
|
85 | /**
|
86 | * Clear the search results and schedule an update.
|
87 | *
|
88 | * #### Notes
|
89 | * This should be called whenever the search results of the palette
|
90 | * should be updated.
|
91 | *
|
92 | * This is typically called automatically by the palette as needed,
|
93 | * but can be called manually if the input text is programatically
|
94 | * changed.
|
95 | *
|
96 | * The rendered results are updated asynchronously.
|
97 | */
|
98 | refresh(): void;
|
99 | /**
|
100 | * Handle the DOM events for the command palette.
|
101 | *
|
102 | * @param event - The DOM event sent to the command palette.
|
103 | *
|
104 | * #### Notes
|
105 | * This method implements the DOM `EventListener` interface and is
|
106 | * called in response to events on the command palette's DOM node.
|
107 | * It should not be called directly by user code.
|
108 | */
|
109 | handleEvent(event: Event): void;
|
110 | /**
|
111 | * A message handler invoked on a `'before-attach'` message.
|
112 | */
|
113 | protected onBeforeAttach(msg: Message): void;
|
114 | /**
|
115 | * A message handler invoked on an `'after-detach'` message.
|
116 | */
|
117 | protected onAfterDetach(msg: Message): void;
|
118 | /**
|
119 | * A message handler invoked on an `'activate-request'` message.
|
120 | */
|
121 | protected onActivateRequest(msg: Message): void;
|
122 | /**
|
123 | * A message handler invoked on an `'update-request'` message.
|
124 | */
|
125 | protected onUpdateRequest(msg: Message): void;
|
126 | /**
|
127 | * Handle the `'click'` event for the command palette.
|
128 | */
|
129 | private _evtClick;
|
130 | /**
|
131 | * Handle the `'keydown'` event for the command palette.
|
132 | */
|
133 | private _evtKeyDown;
|
134 | /**
|
135 | * Activate the next enabled command item.
|
136 | */
|
137 | private _activateNextItem;
|
138 | /**
|
139 | * Activate the previous enabled command item.
|
140 | */
|
141 | private _activatePreviousItem;
|
142 | /**
|
143 | * Execute the command item at the given index, if possible.
|
144 | */
|
145 | private _execute;
|
146 | /**
|
147 | * Toggle the focused modifier based on the input node focus state.
|
148 | */
|
149 | private _toggleFocused;
|
150 | /**
|
151 | * A signal handler for generic command changes.
|
152 | */
|
153 | private _onGenericChange;
|
154 | private _activeIndex;
|
155 | private _items;
|
156 | private _results;
|
157 | }
|
158 | /**
|
159 | * The namespace for the `CommandPalette` class statics.
|
160 | */
|
161 | export declare namespace CommandPalette {
|
162 | /**
|
163 | * An options object for creating a command palette.
|
164 | */
|
165 | interface IOptions {
|
166 | /**
|
167 | * The command registry for use with the command palette.
|
168 | */
|
169 | commands: CommandRegistry;
|
170 | /**
|
171 | * A custom renderer for use with the command palette.
|
172 | *
|
173 | * The default is a shared renderer instance.
|
174 | */
|
175 | renderer?: IRenderer;
|
176 | }
|
177 | /**
|
178 | * An options object for creating a command item.
|
179 | */
|
180 | interface IItemOptions {
|
181 | /**
|
182 | * The category for the item.
|
183 | */
|
184 | category: string;
|
185 | /**
|
186 | * The command to execute when the item is triggered.
|
187 | */
|
188 | command: string;
|
189 | /**
|
190 | * The arguments for the command.
|
191 | *
|
192 | * The default value is an empty object.
|
193 | */
|
194 | args?: ReadonlyJSONObject;
|
195 | /**
|
196 | * The rank for the command item.
|
197 | *
|
198 | * The rank is used as a tie-breaker when ordering command items
|
199 | * for display. Items are sorted in the following order:
|
200 | * 1. Text match (lower is better)
|
201 | * 2. Category (locale order)
|
202 | * 3. Rank (lower is better)
|
203 | * 4. Label (locale order)
|
204 | *
|
205 | * The default rank is `Infinity`.
|
206 | */
|
207 | rank?: number;
|
208 | }
|
209 | /**
|
210 | * An object which represents an item in a command palette.
|
211 | *
|
212 | * #### Notes
|
213 | * Item objects are created automatically by a command palette.
|
214 | */
|
215 | interface IItem {
|
216 | /**
|
217 | * The command to execute when the item is triggered.
|
218 | */
|
219 | readonly command: string;
|
220 | /**
|
221 | * The arguments for the command.
|
222 | */
|
223 | readonly args: ReadonlyJSONObject;
|
224 | /**
|
225 | * The category for the command item.
|
226 | */
|
227 | readonly category: string;
|
228 | /**
|
229 | * The rank for the command item.
|
230 | */
|
231 | readonly rank: number;
|
232 | /**
|
233 | * The display label for the command item.
|
234 | */
|
235 | readonly label: string;
|
236 | /**
|
237 | * The display caption for the command item.
|
238 | */
|
239 | readonly caption: string;
|
240 | /**
|
241 | * The icon class for the command item.
|
242 | */
|
243 | readonly iconClass: string;
|
244 | /**
|
245 | * The icon label for the command item.
|
246 | */
|
247 | readonly iconLabel: string;
|
248 | /**
|
249 | * The extra class name for the command item.
|
250 | */
|
251 | readonly className: string;
|
252 | /**
|
253 | * The dataset for the command item.
|
254 | */
|
255 | readonly dataset: CommandRegistry.Dataset;
|
256 | /**
|
257 | * Whether the command item is enabled.
|
258 | */
|
259 | readonly isEnabled: boolean;
|
260 | /**
|
261 | * Whether the command item is toggled.
|
262 | */
|
263 | readonly isToggled: boolean;
|
264 | /**
|
265 | * Whether the command item is visible.
|
266 | */
|
267 | readonly isVisible: boolean;
|
268 | /**
|
269 | * The key binding for the command item.
|
270 | */
|
271 | readonly keyBinding: CommandRegistry.IKeyBinding | null;
|
272 | }
|
273 | /**
|
274 | * The render data for a command palette header.
|
275 | */
|
276 | interface IHeaderRenderData {
|
277 | /**
|
278 | * The category of the header.
|
279 | */
|
280 | readonly category: string;
|
281 | /**
|
282 | * The indices of the matched characters in the category.
|
283 | */
|
284 | readonly indices: ReadonlyArray<number> | null;
|
285 | }
|
286 | /**
|
287 | * The render data for a command palette item.
|
288 | */
|
289 | interface IItemRenderData {
|
290 | /**
|
291 | * The command palette item to render.
|
292 | */
|
293 | readonly item: IItem;
|
294 | /**
|
295 | * The indices of the matched characters in the label.
|
296 | */
|
297 | readonly indices: ReadonlyArray<number> | null;
|
298 | /**
|
299 | * Whether the item is the active item.
|
300 | */
|
301 | readonly active: boolean;
|
302 | }
|
303 | /**
|
304 | * The render data for a command palette empty message.
|
305 | */
|
306 | interface IEmptyMessageRenderData {
|
307 | /**
|
308 | * The query which failed to match any commands.
|
309 | */
|
310 | query: string;
|
311 | }
|
312 | /**
|
313 | * A renderer for use with a command palette.
|
314 | */
|
315 | interface IRenderer {
|
316 | /**
|
317 | * Render the virtual element for a command palette header.
|
318 | *
|
319 | * @param data - The data to use for rendering the header.
|
320 | *
|
321 | * @returns A virtual element representing the header.
|
322 | */
|
323 | renderHeader(data: IHeaderRenderData): VirtualElement;
|
324 | /**
|
325 | * Render the virtual element for a command palette item.
|
326 | *
|
327 | * @param data - The data to use for rendering the item.
|
328 | *
|
329 | * @returns A virtual element representing the item.
|
330 | *
|
331 | * #### Notes
|
332 | * The command palette will not render invisible items.
|
333 | */
|
334 | renderItem(data: IItemRenderData): VirtualElement;
|
335 | /**
|
336 | * Render the empty results message for a command palette.
|
337 | *
|
338 | * @param data - The data to use for rendering the message.
|
339 | *
|
340 | * @returns A virtual element representing the message.
|
341 | */
|
342 | renderEmptyMessage(data: IEmptyMessageRenderData): VirtualElement;
|
343 | }
|
344 | /**
|
345 | * The default implementation of `IRenderer`.
|
346 | */
|
347 | class Renderer implements IRenderer {
|
348 | /**
|
349 | * Render the virtual element for a command palette header.
|
350 | *
|
351 | * @param data - The data to use for rendering the header.
|
352 | *
|
353 | * @returns A virtual element representing the header.
|
354 | */
|
355 | renderHeader(data: IHeaderRenderData): VirtualElement;
|
356 | /**
|
357 | * Render the virtual element for a command palette item.
|
358 | *
|
359 | * @param data - The data to use for rendering the item.
|
360 | *
|
361 | * @returns A virtual element representing the item.
|
362 | */
|
363 | renderItem(data: IItemRenderData): VirtualElement;
|
364 | /**
|
365 | * Render the empty results message for a command palette.
|
366 | *
|
367 | * @param data - The data to use for rendering the message.
|
368 | *
|
369 | * @returns A virtual element representing the message.
|
370 | */
|
371 | renderEmptyMessage(data: IEmptyMessageRenderData): VirtualElement;
|
372 | /**
|
373 | * Render the icon for a command palette item.
|
374 | *
|
375 | * @param data - The data to use for rendering the icon.
|
376 | *
|
377 | * @returns A virtual element representing the icon.
|
378 | */
|
379 | renderItemIcon(data: IItemRenderData): VirtualElement;
|
380 | /**
|
381 | * Render the content for a command palette item.
|
382 | *
|
383 | * @param data - The data to use for rendering the content.
|
384 | *
|
385 | * @returns A virtual element representing the content.
|
386 | */
|
387 | renderItemContent(data: IItemRenderData): VirtualElement;
|
388 | /**
|
389 | * Render the label for a command palette item.
|
390 | *
|
391 | * @param data - The data to use for rendering the label.
|
392 | *
|
393 | * @returns A virtual element representing the label.
|
394 | */
|
395 | renderItemLabel(data: IItemRenderData): VirtualElement;
|
396 | /**
|
397 | * Render the caption for a command palette item.
|
398 | *
|
399 | * @param data - The data to use for rendering the caption.
|
400 | *
|
401 | * @returns A virtual element representing the caption.
|
402 | */
|
403 | renderItemCaption(data: IItemRenderData): VirtualElement;
|
404 | /**
|
405 | * Render the shortcut for a command palette item.
|
406 | *
|
407 | * @param data - The data to use for rendering the shortcut.
|
408 | *
|
409 | * @returns A virtual element representing the shortcut.
|
410 | */
|
411 | renderItemShortcut(data: IItemRenderData): VirtualElement;
|
412 | /**
|
413 | * Create the class name for the command palette item.
|
414 | *
|
415 | * @param data - The data to use for the class name.
|
416 | *
|
417 | * @returns The full class name for the command palette item.
|
418 | */
|
419 | createItemClass(data: IItemRenderData): string;
|
420 | /**
|
421 | * Create the dataset for the command palette item.
|
422 | *
|
423 | * @param data - The data to use for creating the dataset.
|
424 | *
|
425 | * @returns The dataset for the command palette item.
|
426 | */
|
427 | createItemDataset(data: IItemRenderData): ElementDataset;
|
428 | /**
|
429 | * Create the class name for the command item icon.
|
430 | *
|
431 | * @param data - The data to use for the class name.
|
432 | *
|
433 | * @returns The full class name for the item icon.
|
434 | */
|
435 | createIconClass(data: IItemRenderData): string;
|
436 | /**
|
437 | * Create the render content for the header node.
|
438 | *
|
439 | * @param data - The data to use for the header content.
|
440 | *
|
441 | * @returns The content to add to the header node.
|
442 | */
|
443 | formatHeader(data: IHeaderRenderData): h.Child;
|
444 | /**
|
445 | * Create the render content for the empty message node.
|
446 | *
|
447 | * @param data - The data to use for the empty message content.
|
448 | *
|
449 | * @returns The content to add to the empty message node.
|
450 | */
|
451 | formatEmptyMessage(data: IEmptyMessageRenderData): h.Child;
|
452 | /**
|
453 | * Create the render content for the item shortcut node.
|
454 | *
|
455 | * @param data - The data to use for the shortcut content.
|
456 | *
|
457 | * @returns The content to add to the shortcut node.
|
458 | */
|
459 | formatItemShortcut(data: IItemRenderData): h.Child;
|
460 | /**
|
461 | * Create the render content for the item label node.
|
462 | *
|
463 | * @param data - The data to use for the label content.
|
464 | *
|
465 | * @returns The content to add to the label node.
|
466 | */
|
467 | formatItemLabel(data: IItemRenderData): h.Child;
|
468 | /**
|
469 | * Create the render content for the item caption node.
|
470 | *
|
471 | * @param data - The data to use for the caption content.
|
472 | *
|
473 | * @returns The content to add to the caption node.
|
474 | */
|
475 | formatItemCaption(data: IItemRenderData): h.Child;
|
476 | }
|
477 | /**
|
478 | * The default `Renderer` instance.
|
479 | */
|
480 | const defaultRenderer: Renderer;
|
481 | }
|