Introduce minimap section headers, a la Xcode

[dgileadi]

This addresses #74843. It adds section headers to the minimap, sourced from region markers and MARK: comments:

MARK: comments behave the same way as they do in Xcode's minimap—if the comment contains a hyphen before the header text then it displays a horizontal separator line above the section header.

This PR adds three settings to control the appearance of the section headers, or to turn them off:

Feedback, testing and code fixes are very welcome!

[andyjeffries]

I've downloaded this and the patch works absolutely lovely with plain Ruby files:

I don't know if this is a problem with the patch though or the CraigMaslowski.erb extension, but it doesn't work for either comment style in .html.erb files:

[dgileadi]

I don't know if this is a problem with the patch though or the CraigMaslowski.erb extension, but it doesn't work for either comment style in .html.erb files:

It seems to be a problem with the extension. The code for detecting section headers uses the region markers and comment markers from the language configuration file. That extension's language configuration file defines /* and */ for its block comments, as well as // for its single line comments. If you make a comment using that style, you'll see the section header:

[andyjeffries]

Thanks @dgileadi , I've raised an issue craigmaslowski/vscode-erb#5 in the extension repo.

[andyjeffries]

That extension is deprecated (but I still had it installed and thought VS Code). Just as a follow up, I'm actually using Shopify's Ruby LSP extension and iit's working perfectly. Hopefully soon this can be merged...

[andyjeffries]

Hey @alexdima is there anything we can do as the community to help get this merged in and released? Thanks.

[alexdima]

Thank you, this looks amazing!

The problem is that this is not implemented in a performant manner, so I can't accept this in the current shape. We need that the view is very fast in rendering a frame, or in reacting to a change event. The goal is to have the event reaction time + rendering time of the entire editor be under 10ms, to leave some browser slack time and allow for 60FPS.

The problem with the proposed change is that there are heavy computations done during view event handling/during rendering. These are easy to spot by looking for the compute calls which pass in the entire file. These will grind rendering to a halt for a very large file (100k lines, etc). The computation, by calling tokenizeIfCheap with incrementing line numbers, will also basically trigger synchronous tokenization of the entire buffer. tokenizeIfCheap will tokenize a line if the previous line is tokenized.

For similar problems, we have taken a different approach. For example, for detecting links in the editor, we have a link contribution which reacts to change events with a debounce pattern (so not every file change triggers a recomputation). The actual computation of detecting links is then done on a web worker, and the results are then collected and transformed into decorations which are set on the text model. The decorations are stored in a bunch of efficient interval trees which allows updating them while typing efficiently and also allows for querying them efficiently based on reading patterns (decorations that go in the overview ruler are stored in a different tree than those that don't, because the overview ruler always fetches them all, while the others are usually fetched for the viewport).

I would also recommend that here we implement this using pattern:

• we would have a piece of code (probably in editor/contrib) which reacts to when an editor gets set a new text model or to when the text model changes in a debounced way.
• it then can scan for these markers either on the UI thread with a time cap or on the web worker.
• once it has computed the locations, it sets decorations with those ranges on the text model
• the decorations need a new field to indicate the extra special minimap rendering
• at each frame, the minimap reads decorations from the text model and renders them as possible
• in the rendering code, we need to be as minimalistic as possible to repaint only when necessary, etc.

[dgileadi]

Thanks for the feedback, @alexdima. Your recommended changes are probably best implemented by someone familiar with the vscode code base (and of course with dedicated vscode development time). In the mean time, could you point me to the code in vscode that implements the link detection? That would help me better understand how more efficient section header detection could work.

[alexdima]

Sure

• here is the UI side of things:

  vscode/src/vs/editor/contrib/links/browser/links.ts

  Line 34 in 58558c0

  export class LinkDetector extends Disposable implements IEditorContribution {

• and here is the code that runs on a worker:

  vscode/src/vs/editor/common/languages/linkComputer.ts

  Line 171 in 8ab34a9

  export class LinkComputer {

The link computation might appear a bit too complex because it goes through the language feature registry because there's vscode API for extensions to contribute link providers. Maybe a simpler example is the UnicodeHighlighter:

• the UI side:

  vscode/src/vs/editor/contrib/unicodeHighlighter/browser/unicodeHighlighter.ts

  Line 38 in 8ab34a9

  export class UnicodeHighlighter extends Disposable implements IEditorContribution {

• the worker side:

  vscode/src/vs/editor/common/services/editorSimpleWorker.ts

  Lines 396 to 402 in 8ab34a9

  	public async computeUnicodeHighlights(url: string, options: UnicodeHighlighterOptions, range?: IRange): Promise<IUnicodeHighlightsResult> {
  	const model = this._getModel(url);
  	if (!model) {
  	return { ranges: [], hasMore: false, ambiguousCharacterCount: 0, invisibleCharacterCount: 0, nonBasicAsciiCharacterCount: 0 };
  	}
  	return UnicodeTextModelHighlighter.computeUnicodeHighlights(model, options, range);
  	}

[dgileadi]

Okay @alexdima I think I've implemented what you suggested. Let me know what you think. Thanks!

[pouyakary]

@andyjeffries you're very welcome, and yes! while this @dgileadi has made an exceptional job on this; your championing also counts. Thank you very much for this!

@dgileadi, again! Thanks a lot! I too really wished to have this!

[dgileadi]

Thanks @alexdima for your attention and helpful changes!

[alexdima]

Thank you! Excellent PR!

I did one small conceptual tweak where we now parse all mark headers and then eliminate the ones not in comments on the UI side, where we have good tokenization information available.

[pouyakary]

@dgileadi I just wanted to thank you and also @alexdima, @andyjeffries, and @sandy081. I wished for this feature to exist for so many years and finally having it means the world to me. Thank you so much for all the efforts ❤️, I just opened vscode and got the update and it made my day.

[detzt]

Such a pleasant surprise to see this after updating VSCode. I didn't even know I wanted this, but now I already feel how it improves my life. Thank you ❤️

[NHUJI]

This is a feature I've been dreaming of! I've added MARK to my codebase before as a way to manually differentiate between codes, and now it's actually useful!❤️