Add inserting/replacing range to suggestion items

[mjbvz]

From microsoft/vscode#10266

Search Terms

• suggest / suggestion / complete / completions
• TSServer

Background

Currently VS Code leaves it up to each extension/language to determine how completions work. Some languages implement completions so that selecting a completion replaces the current word:

c|onsole.log
// accept suggestion for `const` for cursor at pipe character
const.log

While other languages instead opt to insert the selected completion at the current position without replacement:

c|onsole.log
// accept suggestion for `const` for cursor at pipe character
constonsole.log

With microsoft/vscode#10266, VS Code is considering adding a setting that lets users pick between using the replace vs insert behavior for suggestion

Proposal

To support this new setting, VS Code needs two ranges for each suggestion item:

• The range when in replacement mode
• The range when in insert mode

As we let the user dynamically select with type of insertion to use with a keybinding, both of these ranges need to be provided up front.

On the VS Code side, we can do a fairly reasonable job guessing at what the insert/replace range should be, but in order to be more reliable we'd need this information from the TS Server

Discussion

• Would this API proposal work for JS/TS?
• How does VS handle completions today (insert vs replace)? Is there any way to control this behavior?
• What are the cases where the insert/replace ranges would be different from what VS Code could compute itself? (bracket accessors or string literals for example) Maybe we only need to return additional range info in those cases?

/cc @minestarks @amcasey for VS
/cc @jrieken From VS Code

[amcasey]

I'm probably forgetting a case, but isn't the insertion mode range always the same as the current selection (i.e. usually empty, at the cursor)?

[amcasey]

Does the user choose between the modes per-completion invocation? If not, why not just have a flag that indicates which range is desired?

[mjbvz]

@amcasey Yes, I think that's usually the case. There are few cases however (such VS Code's jsdoc completions) where we always want to use the same range for both insert and replace. We'd have to see if there are similar cases in TS, such as around string literals or bracket completions

For VS Code, we plan on having a user setting for using insert vs replace. However we also are investigating letting users hold down a key (such as shift) when accepting a completion to instead user the other mode. That's why we need both ranges up front

[amcasey]

@mjbvz, sorry, I didn't understand your jsdoc example or what it meant for the insert and replace ranges to be the same. I was actually guessing that the insert range would always be based on editor state, rather than anything computed by the language service.

[mjbvz]

VS Code has a custom jsdoc completion provider: https://github.com/microsoft/vscode/blob/2a46387970f51b13cb22ddfb2bd4a402129f4345/extensions/typescript-language-features/src/features/jsDocCompletions.ts#L36

The completions for jsdocs always need to replace a specific range, no matter what mode the user is actually on

[Kingwl]

Related: #29270