Quick box improvements for multi-step inputs

[chrmarti]

Continuing #48116. Mockups #45589.

[chrmarti]

#50050 shows several attempts to draft the API for multi-step inputs, each accompanied with a simple example of asking the user for three inputs:

1. A resource group (to create an App Service in).
2. A name for the App Service.
3. A runtime for the App Service.

Some challenges we need to solve in order to implement the mockups in #45589:

• No flicker in the UI, also when, e.g. step 3 first needs to fetch the list of available picks based on the choice in step 1.
• Cancellability while the user provides input and between inputs (e.g., while additional data is fetched).
• Dynamic steps and custom actions, e.g., step 1 can have a toolbar item for creating a new resource group. For that an additional step to input the name of the new resource group needs to be added dynamically.
• The UI allows the user to navigate back to the previous inputs.
• We should consider what it means for an input sequence to be suspended and later resumed.

What makes it difficult to weave this into the existing API of showQuickPick and showInputBox:

• 'Navigate back' and 'custom action': The two functions only support two possible outcomes in their return types: Input is provided or it is cancelled. Introducing additional outcomes requires expanding the return types or having an additional way of receiving the outcome.
• Connecting multiple input steps requires some kind of context that is passed either as an option to the existing API or as an implicit state to the implementation behind the existing API.

[chrmarti]

Adding additional outcomes like 'back to previous step' and custom actions like 'create resource group' to the existing API has proven to be difficult without jeopardizing its simplicity. So our current thinking is that we need to introduce new API to handle these and other advanced cases (e.g., dynamically updating the list of items) we haven't discussed yet.

The new API will provide the basic operations needed to build not only multi-step input flows, but also dynamic updating of the items list and other currently not foreseen scenarios.

• A draft of this API is shown in Take 3 of the API exploration.
• A simple multi-step example is shown in Take 3 of the examples.
• A more elaborate multi-step example with back navigation and custom actions is shown in Take 10 of the examples.

The additional flexibility comes at the price of extensions having to write more code to implement useful behavior. At the same time we are keeping the existing API simple as it is and we are not introducing new API that tries to anticipate future use cases beyond the basic operations these will be made of. It will also be easy to add more of these basic operations later.

[eamodio]

A couple of quick first thoughts.

Instead of using toolbarItems with events, why not use Commands -- not that you would define their placement in the QuickInput, but you could change toolbarItems to be commands and then any commands added with icons would be added as toolbar buttons, and others would be added under a ... menu. I feel like that would be a bit more consistent with other APIs and UI structures.

What is onDidAccept? Is it for accepting text input that isn't in the pick list?
I also don't yet understand what enabled & busy are for.

Some other nit picks:

• pickMany -> multiselect

I would also love it if there was an API affordance to expose the ability the file picker has, which is to use the right-arrow to perform an action on a pick item. I go through some gymnastics in GitLens to offer a similar ability - although I can't use right-arrow without a modifier otherwise you couldn't move the cursor in the input box.

[d-akara]

I was asked to provide input here in reference to closed issue #35993
However, I think the scope of the other issue is far beyond what is being talked about here?

I want the ability to build a custom command palette for vscode with the same capabilities of the command palette which I built for Eclipse.

You can see an example of the capabilities in the Eclipse palette here Commander, a next-gen command palette for Eclipse

Probably what I actually need is a webview that can be positioned like a quick picker that allows handling of keyboard events and access to the list of all commands and their names, descriptions etc.

[chrmarti]

@eamodio Thanks for the feedback:

• I'll look into using commands, that would indeed make it more consistent.
• onDidAccept is for accepting text in the input box (although it can also be interpreted as pick the current item in the list, that is up to the extension), onDidSelectItem (was: onDidPickItem) is for selecting an item in the list.
• enabled: false would prevent the user from interacting with the input UI (e.g., between two steps of a multi-step input).
• busy: true would show a progress indicator (e.g., while loading additional items).
• I'm renaming pickMany to canSelectMany which is consistent with canSelectMany in the OpenDialogOptions.

@dakaraphi Thanks for the feedback, to reply to your feature requests in #35993:

• Capture keyboard input events from input field and handle in extension

onDidTextChange gives the text changes.

• Change list content on handling of input events

items can be updated in response to changes in the text field.

• Add columns to list content

This is not within the scope of this change. We would probably need additional use cases to better understand the requirements of the community with this before we add API.

• Handle some level of rendering of content
  • Provide indication of markers to be applied on a row
  • Provide character indices or information for highlighting matched characters

Highlighting of characters in list items is not part of the proposed API yet, but will need to be added in some way to match the capabilities of the existing showQuickPick API.

[chrmarti]

PR #50402 shows an updated version of the API draft. Still not using commands, that needs more thought on whether it fits this use case.

[d-akara]

@chrmarti The existing API's aren't adequate to support the features I would like to implement.

onDidTextChange gives the text changes.

I need actual key events. Some keys will have special functions.

I think one way to conceive of my features at a high level would be something like a VIM like experience for a command palette.

If you haven't looked at my Eclipse extension I linked above, the features are both quite extensive and nuanced to provide a set of capabilities not found else where the goal is providing a UI paradigm that exceeds the speed execution of hot keys for applications with many commands.

I think a quick look at the animated images of the Eclipse extension would maybe give you the context as to whether you would consider providing the API's that would make it possible.

This is why I'm am somewhat reconsidering asking for specific API's, but I'm thinking the more realistic approach would be if a web view could be provided that would open and dismiss like a quick picker so that I could fully implement all of the functionality directly.

[chrmarti]

@dakaraphi I agree, the new API won't cover all your requirements. It's still good to understand what you are aiming for.

[d-akara]

@chrmarti thx, so where do I go from here? Should this be a separate issue? Should the original be reopened?

[chrmarti]

The API currently leaves handling of Esc or any other way of cancellation to the extension. The API tries to be generic in such a way that you need to implement 'multi-step input' on top of it.

[eamodio]

So the input steps that say "Press Enter to confirm or Esapce to cancel" won't do anything unless the author handles Esc?

[chrmarti]

Escape will hide it and fire onDidHide, that part cannot be overridden for consistency. Enter will fire onDidAccept, but it will not hide the input UI, so it is up to the extension to either hide it or continue with other inputs.

[eamodio]

Ah, got it -- thanks

[DanTup]

Is there any way to easily include an optional step? Eg. in Flutter we have a "new project" command which prompts you for a few things - a project name, location, etc.. Some people want to add additional steps for some optional values (which programming language, etc.) but it would make the simple flow more complicated.

I'm not sure how it'd fit into the UI, but if there was some way to allow the user a way to go to advance settings without adding another step in. I'm not sure you could really do it without adding buttons along the bottom or something (eg. a "create" button that just creates and an "advanced options" button that goes to the optional step), but I thought it worth asking in case you'd thought about it :-)

[chrmarti]

@DanTup Yes, that is possible, the first screenshot in #49340 (comment) shows a custom action in the top right that adds a fourth step.

Note that the proposed API doesn't deal with steps beyond allowing you to tell it which step out of what number of steps you are in. I'm writing an example showing how that can be used to build multi-step input flows, but that will not be part of the API.

[DanTup]

@chrmarti Aha, I misunderstood what that + was. Sounds good, thanks!

[chrmarti]

Good progress on the implementation. There is the multi-step example based on this new API: https://github.com/Microsoft/vscode-extension-samples/tree/chrmarti/quickinputsample/quickinput-sample

The API is still proposed, now would be a good time to check if it will suit your needs. Thanks!

[raix]

@chrmarti One issue I ran into while looking at #50712 is the ability to define an async callback for generating selection items (part of the list might be sync and other part might be async result).

In the concrete example having a way to respond with a validation message or items to select from. (The top item generated from the input and the rest would be result from a server request based on the input)

In the git create branch pr. the idea is to show the branch name after whitespaces are replaced with eg. "_" as the first item to select. The rest of the items would be loaded from services like github/jira/vsts to create branches based on existing tasks/issues. Part of this pr. is also to validate that the branch name follow git flow conventions or user defined conventions - so the ability to show a validation message is still important.

But I ran into limitation of the quickinput api (although I can see that it should totally be possible in the actual ui implementaion)

[chrmarti]

@raix You can update the list of items while the picker is already shown (just assign a new array to items). While fetching new items remotely you can also turn on a progress indicator (set busy to true) to give a hint that the list will be updated. One current limitation is that the list does not have a message area to show a validation message.

[raix]

@chrmarti Ok, sounds good - I'll take a closer look.
Would be nice with the ability to validate the input (like in the regular input component)

[chrmarti]

Closing as this is implemented as proposed API.

[chrmarti]

Collecting feedback in #53327.