@lumino/widgets/types/commandpalette.d.ts

Lumino Widgets

import { ReadonlyJSONObject } from '@lumino/coreutils';
import { CommandRegistry } from '@lumino/commands';
import { Message } from '@lumino/messaging';
import { ISignal } from '@lumino/signaling';
import { ElementDataset, h, VirtualElement } from '@lumino/virtualdom';
import { Widget } from './widget';
/**
 * A widget which displays command items as a searchable palette.
 */
export declare class CommandPalette extends Widget {
    /**
     * Construct a new command palette.
     *
     * @param options - The options for initializing the palette.
     */
    constructor(options: CommandPalette.IOptions);
    /**
     * Dispose of the resources held by the widget.
     */
    dispose(): void;
    /**
     * A signal emitted when the user triggers a command item.
     *
     * #### Notes
     * This signal is emitted when an enabled item is clicked, or when
     * `Enter` is pressed while an enabled item is active. It is not
     * emitted for a header, or for a command which is executed by other
     * means, such as a key binding or a menu.
     *
     * The signal is emitted before the command is executed and before
     * the query text is cleared.
     */
    get itemTriggered(): ISignal<this, CommandPalette.IItem>;
    /**
     * The command registry used by the command palette.
     */
    readonly commands: CommandRegistry;
    /**
     * The renderer used by the command palette.
     */
    readonly renderer: CommandPalette.IRenderer;
    /**
     * The command palette search node.
     *
     * #### Notes
     * This is the node which contains the search-related elements.
     */
    get searchNode(): HTMLDivElement;
    /**
     * The command palette input node.
     *
     * #### Notes
     * This is the actual input node for the search area.
     */
    get inputNode(): HTMLInputElement;
    /**
     * The command palette content node.
     *
     * #### Notes
     * This is the node which holds the command item nodes.
     *
     * Modifying this node directly can lead to undefined behavior.
     */
    get contentNode(): HTMLUListElement;
    /**
     * A read-only array of the command items in the palette.
     */
    get items(): ReadonlyArray<CommandPalette.IItem>;
    /**
     * Add a command item to the command palette.
     *
     * @param options - The options for creating the command item.
     *
     * @returns The command item added to the palette.
     */
    addItem(options: CommandPalette.IItemOptions): CommandPalette.IItem;
    /**
     * Adds command items to the command palette.
     *
     * @param items - An array of options for creating each command item.
     *
     * @returns The command items added to the palette.
     */
    addItems(items: CommandPalette.IItemOptions[]): CommandPalette.IItem[];
    /**
     * Remove an item from the command palette.
     *
     * @param item - The item to remove from the palette.
     *
     * #### Notes
     * This is a no-op if the item is not in the palette.
     */
    removeItem(item: CommandPalette.IItem): void;
    /**
     * Remove the item at a given index from the command palette.
     *
     * @param index - The index of the item to remove.
     *
     * #### Notes
     * This is a no-op if the index is out of range.
     */
    removeItemAt(index: number): void;
    /**
     * Remove all items from the command palette.
     */
    clearItems(): void;
    /**
     * Clear the search results and schedule an update.
     *
     * #### Notes
     * This should be called whenever the search results of the palette
     * should be updated.
     *
     * This is typically called automatically by the palette as needed,
     * but can be called manually if the input text is programatically
     * changed.
     *
     * The rendered results are updated asynchronously.
     */
    refresh(): void;
    /**
     * Handle the DOM events for the command palette.
     *
     * @param event - The DOM event sent to the command palette.
     *
     * #### Notes
     * This method implements the DOM `EventListener` interface and is
     * called in response to events on the command palette's DOM node.
     * It should not be called directly by user code.
     */
    handleEvent(event: Event): void;
    /**
     * Create the search results for a query.
     *
     * @param query - The raw text of the search input.
     *
     * @returns The search results, in display order.
     *
     * #### Notes
     * The default implementation of this method returns the results of
     * `CommandPalette.search()` for the palette items.
     *
     * The palette renders every returned result, so the results should
     * not include items which are not visible. Triggering a header result
     * replaces the query with the header category.
     *
     * The results are cached until `refresh()` is called. A subclass
     * which uses external state should call `refresh()` when that state
     * changes.
     *
     * A subclass may reimplement this method as needed.
     */
    protected search(query: string): CommandPalette.SearchResult[];
    /**
     * Get the index of the result to activate for new search results.
     *
     * @param query - The raw text of the search input.
     *
     * @param results - The search results returned by `search()`.
     *
     * @returns The index of the result to activate, or `-1` for none.
     *
     * #### Notes
     * The default implementation of this method returns the index of the
     * first enabled item when the query is not empty, and `-1` otherwise.
     *
     * The returned index should refer to an enabled item result.
     *
     * A subclass may reimplement this method as needed.
     */
    protected initialActiveIndex(query: string, results: ReadonlyArray<CommandPalette.SearchResult>): number;
    /**
     * A message handler invoked on a `'before-attach'` message.
     */
    protected onBeforeAttach(msg: Message): void;
    /**
     * A message handler invoked on an `'after-detach'` message.
     */
    protected onAfterDetach(msg: Message): void;
    /**
     * A message handler invoked on an `'after-show'` message.
     */
    protected onAfterShow(msg: Message): void;
    /**
     * A message handler invoked on an `'activate-request'` message.
     */
    protected onActivateRequest(msg: Message): void;
    /**
     * A message handler invoked on an `'update-request'` message.
     */
    protected onUpdateRequest(msg: Message): void;
    /**
     * Handle the `'click'` event for the command palette.
     */
    private _evtClick;
    /**
     * Handle the `'keydown'` event for the command palette.
     */
    private _evtKeyDown;
    /**
     * Activate the next enabled command item.
     */
    private _activateNextItem;
    /**
     * Activate the previous enabled command item.
     */
    private _activatePreviousItem;
    /**
     * Execute the command item at the given index, if possible.
     */
    private _execute;
    /**
     * Toggle the focused modifier based on the input node focus state.
     */
    private _toggleFocused;
    /**
     * A signal handler for generic command changes.
     */
    private _onGenericChange;
    private _activeIndex;
    private _itemTriggered;
    private _items;
    private _results;
}
/**
 * The namespace for the `CommandPalette` class statics.
 */
export declare namespace CommandPalette {
    /**
     * An options object for creating a command palette.
     */
    interface IOptions {
        /**
         * The command registry for use with the command palette.
         */
        commands: CommandRegistry;
        /**
         * A custom renderer for use with the command palette.
         *
         * The default is a shared renderer instance.
         */
        renderer?: IRenderer;
    }
    /**
     * An options object for creating a command item.
     */
    interface IItemOptions {
        /**
         * The category for the item.
         */
        category: string;
        /**
         * The command to execute when the item is triggered.
         */
        command: string;
        /**
         * The arguments for the command.
         *
         * The default value is an empty object.
         */
        args?: ReadonlyJSONObject;
        /**
         * The rank for the command item.
         *
         * The rank is used as a tie-breaker when ordering command items
         * for display. Items are sorted in the following order:
         *   1. Text match (lower is better)
         *   2. Category (locale order)
         *   3. Rank (lower is better)
         *   4. Label (locale order)
         *
         * The default rank is `Infinity`.
         */
        rank?: number;
    }
    /**
     * An object which represents an item in a command palette.
     *
     * #### Notes
     * Item objects are created automatically by a command palette.
     */
    interface IItem {
        /**
         * The command to execute when the item is triggered.
         */
        readonly command: string;
        /**
         * The arguments for the command.
         */
        readonly args: ReadonlyJSONObject;
        /**
         * The category for the command item.
         */
        readonly category: string;
        /**
         * The rank for the command item.
         */
        readonly rank: number;
        /**
         * The display label for the command item.
         */
        readonly label: string;
        /**
         * The display caption for the command item.
         */
        readonly caption: string;
        /**
         * The icon renderer for the command item.
         */
        readonly icon: VirtualElement.IRenderer | undefined;
        /**
         * The icon class for the command item.
         */
        readonly iconClass: string;
        /**
         * The icon label for the command item.
         */
        readonly iconLabel: string;
        /**
         * The extra class name for the command item.
         */
        readonly className: string;
        /**
         * The dataset for the command item.
         */
        readonly dataset: CommandRegistry.Dataset;
        /**
         * Whether the command item is enabled.
         */
        readonly isEnabled: boolean;
        /**
         * Whether the command item is toggled.
         */
        readonly isToggled: boolean;
        /**
         * Whether the command item is toggleable.
         */
        readonly isToggleable: boolean;
        /**
         * Whether the command item is visible.
         */
        readonly isVisible: boolean;
        /**
         * The key binding for the command item.
         */
        readonly keyBinding: CommandRegistry.IKeyBinding | null;
    }
    /**
     * A search result object for a header label.
     */
    interface IHeaderResult {
        /**
         * The discriminated type of the object.
         */
        readonly type: 'header';
        /**
         * The category for the header.
         */
        readonly category: string;
        /**
         * The indices of the matched category characters.
         */
        readonly indices: ReadonlyArray<number> | null;
    }
    /**
     * A search result object for a command item.
     */
    interface IItemResult {
        /**
         * The discriminated type of the object.
         */
        readonly type: 'item';
        /**
         * The command item which was matched.
         */
        readonly item: IItem;
        /**
         * The indices of the matched label characters.
         */
        readonly indices: ReadonlyArray<number> | null;
    }
    /**
     * A type alias for a command palette search result.
     */
    type SearchResult = IHeaderResult | IItemResult;
    /**
     * The render data for a command palette header.
     */
    interface IHeaderRenderData {
        /**
         * The category of the header.
         */
        readonly category: string;
        /**
         * The indices of the matched characters in the category.
         */
        readonly indices: ReadonlyArray<number> | null;
    }
    /**
     * The render data for a command palette item.
     */
    interface IItemRenderData {
        /**
         * The command palette item to render.
         */
        readonly item: IItem;
        /**
         * The indices of the matched characters in the label.
         */
        readonly indices: ReadonlyArray<number> | null;
        /**
         * Whether the item is the active item.
         */
        readonly active: boolean;
    }
    /**
     * The render data for a command palette empty message.
     */
    interface IEmptyMessageRenderData {
        /**
         * The query which failed to match any commands.
         */
        query: string;
    }
    /**
     * A renderer for use with a command palette.
     */
    interface IRenderer {
        /**
         * Render the virtual element for a command palette header.
         *
         * @param data - The data to use for rendering the header.
         *
         * @returns A virtual element representing the header.
         */
        renderHeader(data: IHeaderRenderData): VirtualElement;
        /**
         * Render the virtual element for a command palette item.
         *
         * @param data - The data to use for rendering the item.
         *
         * @returns A virtual element representing the item.
         *
         * #### Notes
         * The command palette will not render invisible items.
         */
        renderItem(data: IItemRenderData): VirtualElement;
        /**
         * Render the empty results message for a command palette.
         *
         * @param data - The data to use for rendering the message.
         *
         * @returns A virtual element representing the message.
         */
        renderEmptyMessage(data: IEmptyMessageRenderData): VirtualElement;
    }
    /**
     * The default implementation of `IRenderer`.
     */
    class Renderer implements IRenderer {
        /**
         * Render the virtual element for a command palette header.
         *
         * @param data - The data to use for rendering the header.
         *
         * @returns A virtual element representing the header.
         */
        renderHeader(data: IHeaderRenderData): VirtualElement;
        /**
         * Render the virtual element for a command palette item.
         *
         * @param data - The data to use for rendering the item.
         *
         * @returns A virtual element representing the item.
         */
        renderItem(data: IItemRenderData): VirtualElement;
        /**
         * Render the empty results message for a command palette.
         *
         * @param data - The data to use for rendering the message.
         *
         * @returns A virtual element representing the message.
         */
        renderEmptyMessage(data: IEmptyMessageRenderData): VirtualElement;
        /**
         * Render the icon for a command palette item.
         *
         * @param data - The data to use for rendering the icon.
         *
         * @returns A virtual element representing the icon.
         */
        renderItemIcon(data: IItemRenderData): VirtualElement;
        /**
         * Render the content for a command palette item.
         *
         * @param data - The data to use for rendering the content.
         *
         * @returns A virtual element representing the content.
         */
        renderItemContent(data: IItemRenderData): VirtualElement;
        /**
         * Render the label for a command palette item.
         *
         * @param data - The data to use for rendering the label.
         *
         * @returns A virtual element representing the label.
         */
        renderItemLabel(data: IItemRenderData): VirtualElement;
        /**
         * Render the caption for a command palette item.
         *
         * @param data - The data to use for rendering the caption.
         *
         * @returns A virtual element representing the caption.
         */
        renderItemCaption(data: IItemRenderData): VirtualElement;
        /**
         * Render the shortcut for a command palette item.
         *
         * @param data - The data to use for rendering the shortcut.
         *
         * @returns A virtual element representing the shortcut.
         */
        renderItemShortcut(data: IItemRenderData): VirtualElement;
        /**
         * Create the class name for the command palette item.
         *
         * @param data - The data to use for the class name.
         *
         * @returns The full class name for the command palette item.
         */
        createItemClass(data: IItemRenderData): string;
        /**
         * Create the dataset for the command palette item.
         *
         * @param data - The data to use for creating the dataset.
         *
         * @returns The dataset for the command palette item.
         */
        createItemDataset(data: IItemRenderData): ElementDataset;
        /**
         * Create the class name for the command item icon.
         *
         * @param data - The data to use for the class name.
         *
         * @returns The full class name for the item icon.
         */
        createIconClass(data: IItemRenderData): string;
        /**
         * Create the render content for the header node.
         *
         * @param data - The data to use for the header content.
         *
         * @returns The content to add to the header node.
         */
        formatHeader(data: IHeaderRenderData): h.Child;
        /**
         * Create the render content for the empty message node.
         *
         * @param data - The data to use for the empty message content.
         *
         * @returns The content to add to the empty message node.
         */
        formatEmptyMessage(data: IEmptyMessageRenderData): h.Child;
        /**
         * Create the render content for the item shortcut node.
         *
         * @param data - The data to use for the shortcut content.
         *
         * @returns The content to add to the shortcut node.
         */
        formatItemShortcut(data: IItemRenderData): h.Child;
        /**
         * Create the render content for the item label node.
         *
         * @param data - The data to use for the label content.
         *
         * @returns The content to add to the label node.
         */
        formatItemLabel(data: IItemRenderData): h.Child;
        /**
         * Create the render content for the item caption node.
         *
         * @param data - The data to use for the caption content.
         *
         * @returns The content to add to the caption node.
         */
        formatItemCaption(data: IItemRenderData): h.Child;
    }
    /**
     * The default `Renderer` instance.
     */
    const defaultRenderer: Renderer;
    /**
     * Search an array of command items for fuzzy matches.
     *
     * @param items - The command items to search.
     *
     * @param query - The query text to match against the items.
     *
     * @returns The search results for the query.
     *
     * #### Notes
     * Items which are not visible are excluded. Whitespace in the query
     * is ignored. An empty query matches all items, ordered by category,
     * rank, and label. Otherwise, the matched items are ordered by match
     * quality.
     *
     * Each run of items which share a category is preceded by a header
     * result for that category.
     *
     * This function is used by the default implementation of the protected
     * `search()` method of a command palette. A subclass can use it to
     * compose the default results with custom results.
     */
    function search(items: ReadonlyArray<IItem>, query: string): SearchResult[];
}