Background

Today, document highlights/occurrences has special support for when a developer's cursor is over a keyword.

For example, let's say you had your cursor /*$*/ in the following code.

if (foo()) {
  // ...
}
else if (bar()) {
  // ...
}
else/*$*/ {
  // ...
}

TypeScript is able to provide what's called "document highlights" (formerly called "occurrences") for the editor to highlight as visual clues. Typically, these keywords will be displayed with a lighter background/foreground in the editor, and the highlights we provide in the above case are denoted with [|these range markers|].

[|if|] (foo()) {
  // ...
}
[|else if|] (bar()) {
  // ...
}
[|else|] {
  // ...
}

Yes, the else if is specially highlighted together!

It would be great if find-all-references worked similarly. Editors often has key bindings for iterating through the current set of document highlights (on VS Code this is Go to Next Symbol Highlight - for Windows, the keybinding is F7 and Shift+F7, and in VS, it's Ctrl+Shift+Up/Down); however, these keyboard shortcuts are pretty undiscoverable. Document highlights are a subtle enough hint that users may not even know they exist. So find-all-references has the potential to be a nice delighter for a more-often-used action.

What Would it Support?

I don't know the full list of things document highlights currently supports; however, from what I do know, here's a list of what I think would be useful, ranked loosely by utility.

• return keywords in a specific function scope
• throw keywords in a specific function or try block scope
• break and continue keywords in a specific loop construct, switch statement, or labeled statement
• await keywords in a specific function scope
• yield keywords in a specific function scope
• export keywords in a module or namespace
• case and default clauses in a switch statement
• Chained if/else branches
• import keywords in a module or namespace
• Accessibility modifiers in a class (e.g. public, private, protected, readonly)

Specifics

Many of these are already implemented in document highights/occurrences. The only place I could think that these might differ is whether find-all-references would include the "owning" node in many of these contexts.

For example, today, find-all-references on a case keyword in a switch highlights all of the following:

• All the other case clause keywords
• The default keyword for the default clause
• The switch keyword itself
• All of the corresponding break statements

So in the following document highlights request

innerLabel: {
  outerLabel: switch (a) {
    case 0:
      break innerLabel;
    /*$*/case 1:
      break outerLabel;
    default:
      break;
  }
}

you would get

innerLabel: {
  outerLabel: [|switch|] (a) {
    [|case|] 0:
      [|break|] innerLabel;
    [|case|] 1:
      break outerLabel;
    [|default|]:
      [|break|];
  }
}

So should find-all-references on that case actually return all of those? Or should it provide only the other case clauses?