Improve the statusbar indicator

[krassowski]

Follow up on #78:

• clean up the code: use associative arrays, document interfaces, etc
• add sensible icons
• implement per-connection LSP features configuration
• rework the pop-up, adding three-four buttons like:
  • "Restart LSP connections/reconnect" (after an internet connection issues for users working remotely, i.e. JupyterHub/binder), - not sure if this is needed as we are pooling to renew the connection constantly anyway
  • "Pause the LSP functionality, my laptop battery is dead and the node_modules indexing is driving my CPU crazy!"
  • "Show me the full config, please!"
• when listing virtual documents which stuck (could not be initialized), make their identifiers hyperlinks to the position in the notebook where they are defined (so upon click: scroll to the position + highlight the first line) to make it easier to understand
• distinguish missing servers from unresponsive servers (see the REST endpoint from Add server status endpoint #81)

[bollwyvl]

Really awesome stuff! I'll take a closer look at the nuts and bolts when I get a chance.

Some things that jump out at me:

• to make it look more like the other status indicators,
  • maybe put the doc count in the status bar to the left of the icon
• when there are multiple languages, maybe either
  • stacking them vertically in the popup
  • or have each of the lang names be an independent button (+1)
• haven't checked the code, but if possible, the pause/restart (and everything else it does) should be commands, e.g "stop all language servers" that also appear in the command palette
  • we will likely also wish to show them on the menu bar, because it's possible to hide the status bar
• i should investigate getting the servers into the lab "running" sidebar, but I haven't looked at that API in a while
• I'll work on the icon treatment soon.
  • We can have it work like a progress bar, that starts as an outline and then fills up. I think color is too much except perhaps for a Real Bad error
• the icon could indicate the total state of your language server experience...
  • none tried, all unready, some unready, all ready
    • if none available, probably just hide
  • ...while the language names would indicate the state of each language
    • opacity 0.125, 0.5, 1.0, and/or
    • italic, normal, bold
    • (+1) reuse the style from the diagnostics, e.g
    • warning, error, info, write

[bollwyvl]

Also, here's another icon treatment without any derivatie branding, kinda shouting out the NASA worm and Star Wars:

(also derived from fira code)

[krassowski]

Also, we need to check if the virtual document/connection is still open, as when opening a notebook initially it has "plain" mimetype and only after kernel is loaded it changes (thus we get two virtual documents - the plain one sticks up there for some time and due to my policy of not destroying websockets/virtual documents immediately to keep overhead low for users having interspersed python and R cells - which would end up in a disaster once they start refactoring). Here is the problem captured:

.

Re icons and design stuff: all great ideas; i would go for two indicators as you suggest - one for overall LSP condition and second one for the LSP features - those could be two icons + some text; those could even have separate pop-ups/click actions. Stacking languages vertically in the pop-up is certainly a good idea.

Do you think that someone from the core JupyterLab team would be interested to take a look at what we are doing in here and provide some guidance?

[bollwyvl]

Also, we need to check if the virtual document/connection is still open, as when opening a notebook initially it has "plain" mimetype and only after kernel is loaded it changes (thus we get two virtual documents - the plain one sticks up there for some time and due to my policy of not destroying websockets/virtual documents immediately to keep overhead low for users having interspersed python and R cells - which would end up in a disaster once they start refactoring).

To the earlier point, I think we just want zero to one websocket per language, which opens when asked for and stays open until closed explicitly, with the server staying up even after browser closing, similar to how kernels work. Here is the problem captured:

[image: Screenshot from 2019-10-31 13-39-49] <https://user-images.githubusercontent.com/5832902/67953302-c359c180-fbe6-11e9-828f-61e07cfda394.png> . Re icons and design stuff: all great ideas; i would go for two indicators as you suggest - one for overall LSP condition and second one for the LSP features - those could be two icons + some text; those could even have separate pop-ups/click actions.

I think one number, one icon, and the language words are about all the real estate we can take... And that's a lot. It's going to end up like the old notebook toolbar down there, if everyone takes that much, so we have to deliver a lot of value. We could even cut down on words with language icons: there are some consistent language icons coming down the pipe on some other work, though, so it's probably best to stick with words for now.

Do you think that someone from the core JupyterLab team would be interested to take a look at what we are doing in here and provide some guidance?

For what it's worth, I have commit rights over there, and a fair number of contributions in. The steps in #76 are what I consider the bare minimum before we should even propose the work to the broader developer community (e.g warm up the JEP). At that point, we could likely get it added to the lab org, which would be good marketing. Luckily, in this community, code wins: if it looks like core, is documented, tested, extensible, and generally useful to the whole range of users, there's no reason we shouldn't be able to get it in. The biggest strike against it is the undesirable externality of requiring more things we can't control (language servers) but there's many developer years locked up in all those servers that the jupyter community won't have the time to reproduce: if you can't beat them, integrate them! This work would almost certainly have to land at a major release, and it is unlikely we will be able to have this be bullet-proof, production ready by 2.0 (dec-jan). We could start maintaining/testing a branch against the lab 2.0 branch, but again, that won't be in anyone's hands for some time. So continuing to mature the code as an extension is a very good path indeed.

…

[krassowski]

Current design for the popover

I was thinking about listing connections grouped by LSP servers (this usually makes sense) like this:

---------------------------------------------
| **LSP Servers**                           |
|-------------------------------------------|
|  > Installed/Available (8)                |
|  v Running (2)                            |
|     Python (pyls)               [cog] [o] |
|     - x.ipynb (NB)                    [o] |
|     - %%timeit (cell)                 [o] |
|     R (languageserver)          [cog] [o] |
|     - x.ipynb (NB)                    [o] |
|  v Missing (1)                            |
|      Latex                            [?] |
|-------------------------------------------|
|  a longer status message                  |
--------------------------------------------------------------------------------------
| [LSP icon] 2 connected, 1 missing [o] |                           (stausbar)
--------------------------------------------------------------------------------------

where:

• [o] is a status indicator (green - all ok; yellow/red - some problem, hover over to learn more)
• [cog] is a cog icon which opens settings tab, scrolled down to the specific language server settings
• %%timeit cell links to a cell from which an independent "virtual" document was extracted
• [?] is a help button directing to our docs about the server installation/specs creation
• the headers are collapsible/expandable; Available shows autodetected + configured servers as returned by the /lsp endpoint - they will have a cog icon as well (despite of them not being active).
• the server names displayed in parentheses are links to the repositories if available in URL field of spec

In addition, specific features will be able to:

1. display temporary messages in a shared area
2. add custom statusbar indicators

For example:

                              ------------------------------
                              | Diagnostics/linter popover |
--------------------------------------------------------------------------------------
| [LSP icon] 3 connected [o]  |  1 error, 2 warnings  |   Renamed X to Y in two places
--------------------------------------------------------------------------------------

where

• error and warnings words would be replaced by subtle and less space-hungry icons
• the "renamed" message would go away in a few seconds
• the diagnostics popover would list the messages and locations (clickable) + offer quick fixes if supported by the server OR there would be no popover, and it would just open/focus a panel with such a functionality

having the linters messages summary in the status bar makes sense:

• it is a relatively common thing in other IDEs
• we do not have a unified gutter in notebooks, so we cannot realy display an "overall" icon fixed on the very top of the gutter as PyCharm does

[bollwyvl]

Looking good, thanks for taking the time to make some ASCII art! It's very therapeutic.

My general guidance (with an eye towards getting this into lab) is we should try:

• to make everything look and work like lab to the extent possible,

  • reusing the existing visual atoms when possible
  • a pattern I detest is the block-the-world dialogs, but that's just me. I also don't particularly like blueprint (size, react, p******r), but it's in there, and we should use that wherever we can to help us achieve consistent UI components.

• to think about making things more (keyboard) accessible

Specifics:

popovers:
I don't feel like popovers are used widely in lab, nor are the very accessible. they are also hard to test, because they end up attached to the root. anything more than a single line, or anything with more than one click surface should probably end up in a (dismissable) sidebar.

running:
If we can get our servers into lab's Running tab, that would be best, even if it doesn't provide all the bells and whistles... but that feature landed only recently.

status bar:
Again, we can't take that much of the status bar real estate, or they have to be broken up and individually disable-able. At most, we could show that there are error/warnings, and delegate the rest to dedicated views. A diagnostic overview would be great, i could totally see having it sidebar'd while doing a tricky refactor in several documents. It should not be in the same view as the language server status, though, as if everything is working, you won't care at all about language servers, just your code.

gutters:
i guess i don't understand what a "global" gutter is. I added gutters over on lintotype... I can bring that functionality over, if desired. It's just css and html, so we can do whatever the heck we want with it.

packaging:
I think a lot of these things are starting to look like individual packages that all communicate through the ILanguageServerManager interface over phosphor signals/messages. So from what I'm seeing, in addition to the initial ones:

• language-server-status
  • adds view launchable with a command
  • (optionally) controls status bar
  • (optionally) contributes to Running sidebar
• language-server-diagnostics
  • adds summary view launchable with a command
  • (optionally) controls status bar for diagnostics
• language-server-gutters
  • can install itself into ls-fileditor and ls-notebook
• language-server-config

installation:
Installing all these piddly little packages sounds annoying. We can have a language-servers-kitchen-sink that can install everything, but I think we'll make enough wrong choices that it will be worth leaving as many pieces of UI as we can open to re-interpretation.

[krassowski]

Subjective (counter)points:

• I tried to minimize the space taken by the statusbar items in this new design ;) I concur though that making them disable-able is desired.
• running tab - maybe, in addition to the popover (as you have mentioned, the statusbar is sometimes hidden + it is my intention to only show the servers relevant to the opened notebook/file in the status bar popover - it would be also good to have a place where everything is shown)
• let's have the popover and more verbose items for now while it is under heavy development and still fragile - the easier to get debugging cues from the users the better!
• gutters: I know that bringing gutters to code mirror is not so difficult. I meant that we cannot (easily) to this thingy (see the icon in the top right) in notebook:
  
  
• packages - sure, we should (but it feels a daunting task to refactor); I have more detailed thoughts on that, but let's keep this issue focused on the statusbar/interface
• popovers: the very language (mode) picker for file editor in statusbar uses popover. The kernel picker uses the annoying, obstructive dialog window; if we get to choose which JupyterLab-y thing to use I am for the former. Popovers are also used for go-to-line and for spaces/tabs.
• popovers: what I get and can agree is that we want to offer another way of accessing this info AND that this is the maximal complexity we can get.
• the panels have their annoyances too - for one, the left panel takes away the file browser which I need so often when working on larger projects; I agree that a panel (on the right side, preferably) for advanced diagnostics display is the right thing to do.

I will add more thoughts as they come, this is what I got in the lunch break. Please continue adding your constructive criticism, this is much needed (even when I disagree)!

[krassowski]

@ellisonbg, @tgeorgeux - I've tried to do some ASCII design for JupyterLab-LSP statusbar. We have some interesting discussion here - if you are interested in chiming in you are more than welcome!

[bollwyvl]

gutters: I know that bringing gutters to code mirror is not so difficult. I meant that we cannot (easily) to this thingy (see the icon in the top right) in notebook:

Here's a self-contained, awful example, which nonetheless could be implemented (much better) in react... or d3... or...

packages

My point about all the APIs and interfaces and packages is, if someone wanted to make jupyterlab-lsp-notebook-gutter, what API would they need to get all the diagnostic/current token positions in the concrete document, offer a useful hover message, and jump to that position, without having to dig through (presently) around 6k lines of code. Or, if it's important enough to add to notebook (i'd probably agree it is) how would we get it added to NotebookPanel properly, and then become a consumer of it.

I'm not suggesting a full refactor of everything (well, I am, eventually on #76), merely starting new features (like #98) as new packages if they will have worth to a downstream.

popovers: the very language (mode) picker for file editor in statusbar uses popover.

Ha, despite working in lab most of the time (at least on certain projects), because I don't use the status bar, I didn't know that! I'm just saying, it is hard to test them, and they are completely unreachable with the keyboard. Anyhoo... in the language picker case, it is like a traditional menu (you pick a thing from many, it goes away). The ascii mockup has multi-level, collapsible tree control of potentially tens of items, and a number of icons close to the edge of the box.

kernel picker uses the annoying, obstructive dialog window;

I know, right?

I agree that a panel (on the right side, preferably)

That (finally) got promoted to a user-level choice (right click -> switch sidebar side). also in the screenshot above!

this is the maximal complexity we can get.

there's always something we won't have thought of that will make it worse.

[krassowski]

Another use case for quick "disable lsp for this document" button (in addition to slow node indexing): I get to work with some scripts written years ago which are full of yellow/red underlines due to the use of python2, two spaces for indent and other things from before pep8.