feat: introducing new hover focus options for editor.action.showHover (#196891)

* fix: revert and optimize showHover action behavior

* feat: update focus option for controlling hover focus behavior

* polishing the code, extracting an enum, doing a check on the focus argument

* refactoring the code

* Refactor default value to use ShowOrFocusHoverArgument enum

* misc: renaming the enums to more accurately reflect their behavior

---------

Co-authored-by: Aiday Marlen Kyzy <[email protected]>

Author: idootop

src/vs/editor/contrib/hover/browser/hover.ts

@@ -371,6 +371,12 @@ export class ModesHoverController extends Disposable implements IEditorContribut
 	}
 }
 
+enum HoverFocusBehavior {
+	NoAutoFocus = 'noAutoFocus',
+	FocusIfVisible = 'focusIfVisible',
+	AutoFocusImmediately = 'autoFocusImmediately'
+}
+
 class ShowOrFocusHoverAction extends EditorAction {
 
 	constructor() {
@@ -381,8 +387,7 @@ class ShowOrFocusHoverAction extends EditorAction {
 				comment: [
 					'Label for action that will trigger the showing/focusing of a hover in the editor.',
 					'If the hover is not visible, it will show the hover.',
-					'This allows for users to show the hover without using the mouse.',
-					'If the hover is already visible, it will take focus.'
+					'This allows for users to show the hover without using the mouse.'
 				]
 			}, "Show or Focus Hover"),
 			metadata: {
@@ -393,9 +398,14 @@ class ShowOrFocusHoverAction extends EditorAction {
 						type: 'object',
 						properties: {
 							'focus': {
-								description: 'Controls if when triggered with the keyboard, the hover should take focus immediately.',
-								type: 'boolean',
-								default: false
+								description: 'Controls if and when the hover should take focus upon being triggered by this action.',
+								enum: [HoverFocusBehavior.NoAutoFocus, HoverFocusBehavior.FocusIfVisible, HoverFocusBehavior.AutoFocusImmediately],
+								enumDescriptions: [
+									nls.localize('showOrFocusHover.focus.noAutoFocus', 'The hover will not automatically take focus.'),
+									nls.localize('showOrFocusHover.focus.focusIfVisible', 'The hover will take focus only if it is already visible.'),
+									nls.localize('showOrFocusHover.focus.autoFocusImmediately', 'The hover will automatically take focus when it appears.'),
+								],
+								default: HoverFocusBehavior.FocusIfVisible,
 							}
 						},
 					}
@@ -419,14 +429,31 @@ class ShowOrFocusHoverAction extends EditorAction {
 		if (!controller) {
 			return;
 		}
-		const position = editor.getPosition();
-		const range = new Range(position.lineNumber, position.column, position.lineNumber, position.column);
-		const focus = editor.getOption(EditorOption.accessibilitySupport) === AccessibilitySupport.Enabled || !!args?.focus;
+
+		const focusArgument = args?.focus;
+		let focusOption = HoverFocusBehavior.FocusIfVisible;
+		if (focusArgument in HoverFocusBehavior) {
+			focusOption = focusArgument;
+		} else if (typeof focusArgument === 'boolean' && focusArgument) {
+			focusOption = HoverFocusBehavior.AutoFocusImmediately;
+		}
+
+		const showContentHover = (focus: boolean) => {
+			const position = editor.getPosition();
+			const range = new Range(position.lineNumber, position.column, position.lineNumber, position.column);
+			controller.showContentHover(range, HoverStartMode.Immediate, HoverStartSource.Keyboard, focus);
+		};
+
+		const accessibilitySupportEnabled = editor.getOption(EditorOption.accessibilitySupport) === AccessibilitySupport.Enabled;
 
 		if (controller.isHoverVisible) {
-			controller.focus();
+			if (focusOption !== HoverFocusBehavior.NoAutoFocus) {
+				controller.focus();
+			} else {
+				showContentHover(accessibilitySupportEnabled);
+			}
 		} else {
-			controller.showContentHover(range, HoverStartMode.Immediate, HoverStartSource.Keyboard, focus);
+			showContentHover(accessibilitySupportEnabled || focusOption === HoverFocusBehavior.AutoFocusImmediately);
 		}
 	}
 }