Command palette

[davep]

Implements #3021.

Key features of the PR:

• Adds a "command palette" (AKA minibuffer if you're an Emacs fan) that pops up over a Textual application.
• Adds a method of providing command sources, all of which will be searched.
• Runs the code associated with the command once a choice has been made.
• Hits from sources are gathered up async, so the completions can keep coming in as the user interacts with the system.

Current state of work in a simple test application, where there's a command source of lines of text, where a selected line will cause the text to be shown in a Textual notification. The command source is coded to pretend to be a very slow source, with noticeable pauses between each command been provided.

Screen.Recording.2023-08-29.at.10.44.11.mov

The matching in the command provider is done using Textual's (as yet undocumented) builtin "fuzzy matcher". The code for the command provided used here is:

    async def search(self, query: str) -> CommandMatches:
        """A request to hunt for commands relevant to the given user input.

        Args:
            query: The user input to be matched.
        """
        print(f"begin search(\"{query}\")")
        try:
            # Get a Textual fuzzy matcher.
            matcher = self.matcher(query)
            # For each line in the data source...
            for candidate in self.DATA:
                # Sleep some random amount of time, just so we can pretend
                # to be a slow source.
                await sleep(random() / 10)
                # If the match is above zero...
                if matcher.match(candidate):
                    # ...create a hit object and pass it back up to the
                    # command palette for use there.
                    yield CommandSourceHit(
                        # The match score -- used for sorting.
                        matcher.match(candidate),
                        # The Rich Text object for showing the command and
                        # how it matched.
                        Text.assemble(
                            Text.from_markup("[italic green]notify('[/]"),
                            matcher.highlight(candidate),
                            Text.from_markup("[italic green]')[/]")
                        ),
                        # The code to run this if this match is picked by
                        # the user.
                        partial(self.screen.notify, candidate),
                        # The original text of the command itself.
                        candidate,
                        # Some optional help text for the command; here used
                        # to help show easy access to key information about
                        # the environment.
                        "Show the selected text as a notification\n"
                        f"I think the current screen is {self.screen!r}\n"
                        f"I think the focused widget is {self.focused!r}\n"
                        f"Match score: {matcher.match(candidate):0.5f}"
                    )
        except CancelledError:
            print(f"cancelled search(\"{query}\")")
        finally:
            print(f"end search(\"{query}\")")

where self.DATA is simply a list of lines of text.

A slightly more sensible example, this time hooked up with a command source that wraps the main Textual application actions:

Screen.Recording.2023-08-29.at.10.46.51.mov

Still to do (not an exhaustive list):

• Improve and fix the fuzzy matcher.¹
• Add support to the fuzzy matcher for being given styles for highlighting.
• Add a component class to help control the styling of matched text in the hits.
• Look at a good sort order for command hits.
• Related to the above, consider support for OptionList for inserting new options in specific locations in the list.
• Add support for using the command palette in an example app or two (the code browser looks like a prime candidate).
• Finally decide how the command palette will be called upon by the user, if it should be enabled by default, and how configurable that should be by the developer.
• Add global enable/disable flag on App
• Add a reference command source for obvious commands on App.
• Unit tests.
• Snapshot tests.
• Main documentation.
• Likely a full entry in the guide.²
• Perhaps also a HOWTO on how to write your own command source.³
• Test on Windows; especially the choice of default key binding.
• Document the default key binding somewhere, so developers know how this is initially invoked.⁴
• Try a short delay before the loading indicator appears. Suggest 500ms, to prevent flicker.
• Remove the border that separates the input from the results.
• Try adding a 🔎 emoji before the input text, which aligns with the results.
• Have the highlight in the command list extend as far as possible left and right.
• Add appropriate entries to the ChangeLog.
• Update the "Released in 0.??.0" text to the release version.
• Double-check the issues with Ctrl+Space on Windows, relating to pasting from the clipboard (see comment way down below).

Footnotes

1. Actually, aside from some tweaks to the interface, I've left it as-is for the moment. I do wonder if we can improve the scoring -- perhaps scoring earlier matches over later and the like -- but I think it's fine for the moment. ↩

2. The more I think on this, the more I think it makes more sense that, initially at least, this is documented as part of the API (which it is). ↩

3. I think this should come later if it's decided it's needed. ↩

4. Going to be added by @willmcgugan before going into main; likely a main docs and blog combo. ↩

[davep]

The choice of default key binding might be questionable after all: while it has been shown to work fine on macOS and Windows, I've just noticed that, in Windows 11 under Parallels at least, if I go to paste something into a Textual application from the clipboard it causes the command palette to appear first and then the text being pasted is pasted into that -- this would suggest that the paste operation is causing the same sequence to be passed in as that generated by ctrl+space.