Test: Hover Verbosity Proposed API

[aiday-mar]

Refs: #195394

• anyOS @mjbvz
• anyOS @jrieken
• anyOS @benibenj

Complexity: 4

Create Issue

---

This iteration we have made it possible to show additional information in the hover on a user request. The feature request stems from the TS team which would like to show expanded type information. In the following example, when we currently hover on foo we see the following information const foo: FooType. The TS team would like to show string | number on hover expansion instead.

type FooType = string | number
const foo: FooType = 1

To this effect, we have developed a new Proposed API which allows extensions to provide expanded hover results. More specifically we have created a new type called the VerboseHover which extends from the standard Hover and contains two fields canIncreaseVerbosity and canDecreaseVerbosity which specify if the verbosity of the current hover can be increased/decreased.

export class VerboseHover extends Hover {
  /**
  * Can increase the verbosity of the hover
  */
  canIncreaseVerbosity?: boolean;
  
  /**
  * Can decrease the verbosity of the hover
  */
  canDecreaseVerbosity?: boolean;
  
  /**
  * Creates a new hover object.
  *
  * @param contents The contents of the hover.
  * @param range The range to which the hover applies.
  */
  constructor(contents: MarkdownString | MarkedString | Array<MarkdownString | MarkedString>, range?: Range, canIncreaseVerbosity?: boolean, canDecreaseVerbosity?: boolean);
}

This information is used to render +/- icons in the hover if it is expandable/retractable. We have also introduced a new signature for the method provideHover which contains an additional parameter HoverContext.

provideHover(document: TextDocument, position: Position, token: CancellationToken, context?: HoverContext): ProviderResult<VerboseHover>;

This parameter has two fields action and previousHover which signal that the user would like to increase or decrease the verbosity of the previousHover. It is to be used by extension authors to provide expanded/contracted hovers.

Testing:

To test please do the following:

1. Inspect the file vscode.proposed.editorHoverVerbosityLevel.d.ts which contains the proposed API. Make sure the API makes sense. Let me know if there is anything unclear in the description or the API structure.
2. Create a test extension and in the package.json file, under enabledApiProposals place the string editorHoverVerbosityLevel. Pull the proposed API with npx @vscode/dts dev.
3. Register a hover provider which returns verbose hovers. You may use the following scaffolding:

context.subscriptions.push(vscode.languages.registerHoverProvider({ scheme: 'file' }, {
  provideHover(document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken, context?: vscode.HoverContext): vscode.ProviderResult<vscode.VerboseHover>{
	  // logic
  },
}));

4. Fill in the //logic placeholder above with code which checks the context parameter to determine the level of the hover to return. Here is an example of some code. The following logic registers a hover provider which returns an expandable verbose hover on the first 100 lines of the editor. The hover can be expanded up to three levels. Make sure to create a verbose hover which can expand to at least 2 levels for the following testing points.

const firstMarkdown = new vscode.MarkdownString().appendCodeblock('type Res = Foo | Bar', 'typescript');
const secondMarkdown = new vscode.MarkdownString().appendCodeblock([
  'type Res = interface Foo {',
  '	foo: Foo1;',
  '} | interface Bar {',
  '	bar: Bar1;',
  '}'
].join('\n'), 'typescript');
const thirdMarkdown = new vscode.MarkdownString().appendCodeblock([
  'type Res = interface Foo {',
  '	foo: interface Foo1 {',
  '		foo1: string;',
  '	};',
  '} | interface Bar {',
  '	bar: interface Bar1 {',
  '		bar1: string;',
  '	};',
  '}'
].join('\n'), 'typescript');
	
const allContents = [
  [firstMarkdown],
  [secondMarkdown],
  [thirdMarkdown]
];
let level = 0;

context.subscriptions.push(vscode.languages.registerHoverProvider({ scheme: 'file' }, {
  provideHover(document: vscode.TextDocument, position: vscode.Position, token: vscode.CancellationToken, context?: vscode.HoverContext): vscode.ProviderResult<vscode.VerboseHover>{
	  if (context) {
		  level += ((context.action === vscode.HoverVerbosityAction.Increase) ? 1: -1);
	  }
	  const range = new vscode.Range(1, 100, 100, 100);
	  const contents: vscode.MarkdownString[] = allContents[level];
	  return {
		  contents,
		  range,
		  canIncreaseVerbosity: level < allContents.length - 1,
		  canDecreaseVerbosity: level > 0
	  }
  },
}));

5. Run the extension, activate it.
6. Trigger the verbose hover, the hover UI should be similar to:

7. Click on the + and - icon and verify that the hover updates with the expected markdown content.
8. Focus on an expandable hover part. Verify that the keybindings cmd+k cmd+p/cmd+k cmd+m (on macos) or ctrl+k ctrl+p/ctrl+k ctrl+m (on windows) respectively increase and decrease the hover verbosity level.
9. Generally verify that the UI/UX interaction is smooth and nothing unexpected happens.

Thank you for testing!

[mjbvz]

Removing my assignment in the list since it's breaking our tooling but I still plan on testing it along with the 2 other auto assigned testers

[jrieken]

👏 @aiday-mar and @hediet This works really well!

[aiday-mar]

Thanks!