Create a workspaces GUI

[RafalSkolasinski]

Jupyterlab's documentation only explain how to manage workspaces via URLs and CLI.

Are there any plans to provide some GUI for those? At least create new one and list / choose / delete existing ones?

[afshin]

Hi @RafalSkolasinski. We want a workspaces GUI of some sort in JupyterLab. And your suggestion of just a list to begin with is similar to conversations we've had about where to start.

I'd be happy to mentor anyone who wants to work on this feature. I've labeled the issue as help wanted.

[ibdafna]

I'm keen to chip in. Where do we start?

[afshin]

@ibdafna Great!

I would start by making a feature branch in your fork and creating a workspaceui-extension as a new extension that you model off of running-extension and workspaceui modeled off of running.

CC: @tgeorgeux @ellisonbg if you know (or are) someone who would like to work on the user experience of this UI, let's connect them with Itay. For now, I think a list of sessions is the right place to start.

[Madhu94]

@ibdafna Did you get started on this ? I was wondering if I could pick it up.

[RafalSkolasinski]

Is anyone working on this right now?

[ibdafna]

Firstly - apologies for not noticing the comments earlier. I started working on this, progress not as quick as I would have wanted. @Madhu94 happy for any help on this! Give me a couple of weeks and I'll post a WIP PR.

[tzuni]

Also interested in chipping in on this or at least watching eagerly from the sidelines!

[Madhu94]

@ibdafna Sorry, I missed the replies to my question. Still interested in picking this up if you haven't or helping to push this along if you have.

[Madhu94]

As an update, in case anyone's interested, I've also started working on a workspaces extension in userland. I'm facing minor blocks(like #7785). I'll update once I'm done.

[afshin]

@Madhu94, awesome! I'm glad you are taking this up!

[allefeld]

quoting myself from #7876 "interface to manage workspaces":

Under the URL /lab/workspaces without an appended workspace name, an interface to manage workspaces should be shown. that is:

• a list of existing workspaces, click opens it
• for each existing workspace, options to delete, rename, clone
• option to create a new workspace, either empty or as a clone of the default workspace.

[afshin]

@allefeld I would say a good way to start is to just add a command to the command palette and probably a menu item but not to tie it to a specific URL yet. URLs are a place in a user interface we should be very conservative about because they are one of the last things that change and they can be very long-lasting.

Since this is a user interface for managing workspaces, simply launching it the way we'd launch any other extension (i.e. from the command palette or menu or launcher) seems like the right way to invoke it. I'm not 100% opposed to the URL being used this way, but it's not where I would begin.

[allefeld]

@afshin, I thought it would be the logical way to do it, but I understand.

[isabela-pf]

FYI, I'm starting to work on a potential experience and UI for this. I'll post mockups as I make progress.

Between the helpful comment from @allefeld and JupyterLab docs, I think I have a good idea of what functionality and use cases are needed, but more input in that area is always useful since I've rarely used workspaces myself.

[isabela-pf]

I’ve been making my way through each of the interactions needed for this feature and it’s turning into a lot to post together, so I’m going to break it up. This comment will be about the potential placement of a workspace UI in either the sidebar or the launcher.

Since it was recommended in the sidebar on this thread, I’ll start there. I don’t think workspace management makes sense in the command palette since the command palette schema is more of a collection of actions and things you can do while workspaces are really just the set up of a Lab experience. I put it in the Open Tabs section for now because workspaces will change what tabs are open, but I am worried it might be easily missed here.

I think the best option for placement of a workspace management UI is actually in the launcher. Since workspaces change the URL, open files, and arrangement of tabs, the launcher seems like the place I’d expect such a large visual change to happen.

As it is currently, I think the launcher needs some work (which I’m working on in the background based on multiple issues), but this design would match with current launcher expectations.

Right now I’m tentatively using this modified version of Material Design’s dashboard icon to represent workspaces. I’ve given it only a little thought, so if anyone has feedback on it feel free to share. If anyone wants to use it, let me know and I'll get you an SVG since GitHub doesn't support them in comments.

[blink1073]

Hi @isabela-pf, thanks for digging in to this! I have two concerns:

• The number of workspaces can get large (we create auto-workspaces when we detect another browser tab with the same url)
• We need to be able to delete workspaces

[allefeld]

I think the best option for placement of a workspace management UI is actually in the launcher. Since workspaces change the URL, open files, and arrangement of tabs, the launcher seems like the place I’d expect such a large visual change to happen.

@isabela-pf I understand your reasoning, but I'm not sure I agree. Everything else in the launcher adds something to the current workspace, so having items there change the entire workspace would be surprising.

I'm not sure what I would recommend instead, but one option would be a modal dialogue. A large box that covers most but not all of the viewport, and with the current workspace in the background dimmed or blurred.

What would creating / selecting a workspace do? Replace the one in the current tab, or create a new tab?

[jasongrout]

Everything else in the launcher adds something to the current workspace

To be more precise, everything in the launcher replaces that same launcher tab with exactly one activity.

so having items there change the entire workspace would be surprising.

I agree.

[isabela-pf]

Thanks for the great feedback! I’ll have to think more about where a workspace UI fits. For now I have mockups of some of the other interactions that are not influenced by that UI placement choices. I think these interactions make sense as dialogs regardless of UI placement, though that could change in the right context.

To create a new workspace, it seems to me like all that is needed is the workspace name. This dialog makes it so that setting up a workspace stays quick, but is more explicit about workspaces generating URLs. I still have filler brackets in this mockup because I haven’t looked into what invalid characters there might be for a workspace name. Creating a new workspace this way would create a workspace based on what the user has open, just as workspaces do now.

This error in the existing dialog design can also be used for other workspace naming errors (like in renaming a workspace).

One of the key things I think this UI will need is a context menu with these items ordered first to last:, rename workspace, clone workspace, export workspace, reset workspace, and delete workspace.

I haven’t made the rename workspace flow yet because I had some questions about how that would work. I’ve grouped all these questions in the comment below.

Cloning a workspace should look a lot like creating a new workspace because a cloned workspace is still a new workspace. The only changes here are in the text. Cloned workspaces have default suggested name of [existingworkspace]clone (numbered as necessary), but leave the text highlighted so it can easily be named before it is actually cloned.

Deleting a workspace seems like it might have an extra confirmation so that users don’t do it by accident. I have a confirm deletion dialog here, but I want to know the frequency of deletion and/or how irritating it is to delete a workspace by accident to make that choice. This is the same for resetting workspaces.

Let me know if this was helpful for starting to get a feel for how these features might need to interact with a user.

[isabela-pf]

I found myself having a couple of questions I haven’t been able to find answers to myself, so I’m listing them here.

1. Can you currently rename a workspace? I’m not finding it in the docs. If you currently can, what does renaming a workspace do to the URL? Does it create a new URL accordingly? If it creates a new one, is the old one still there or auto-deleted?

2. I have a few questions about what is needed to import a workspace. It looks like importing is mostly about pointing JupyterLab at the appropriate JSON file, so could this be done with the browser’s default file browsing interface? It also looks like it pulls the workspace name and creates the URL from that file name by default, so I don’t think this needs its own unique interactions other than an error dialog notifying of a failed import (like this).

3. What kinds of warnings might happen when opening a workspace? I haven’t triggered anything except for having a dialog that warns me I have the same file open in multiple workspaces. Are there any other errors that should be accounted for like lost file paths?

4. Is it common to delete and reset workspaces? Is is a big loss if done by accident? The frequency and severity of consequence will help decide if confirmation dialogs for both is going to be necessary or an annoying extra click.

[blink1073]

Here are the operations we support from the browser client:

jupyterlab/packages/services/src/workspace/index.ts

Line 42 in e7317f2

async fetch(id: string): Promise<Workspace.IWorkspace> {

.

There are also options from the command line:

$ jupyter lab workspace --help
Import or export a JupyterLab workspace

There are two sub-commands for export or import of workspaces. This app
    should not otherwise do any work.

Subcommands
-----------

Subcommands are launched as `jupyter cmd [args]`. For information on using
subcommand 'cmd', do: `jupyter cmd -h`.

export
import
...

1. The URL reflects the name of the JSON file on disk. You can find the location from the command line:

$ jupyter lab paths
Application directory:   /Users/stslve/miniconda/share/jupyter/lab
User Settings directory: /Users/stslve/.jupyter/lab/user-settings
Workspaces directory: /Users/stslve/.jupyter/lab/workspaces

2. The file locations in the file browser are scoped by the --NotebookApp.notebook_dir argument to the server application.

3. We try to re-hydrate all items in the workspace. It is up to the re-hydration logic of each plugin what it does. For documents, if the document is not found on disk it fails silently and does not open any panel for that document.

4. Do don't have any method to delete a workspace (though it could be added to both the UI and the CLI). We support the ?reset URL query parameter to get a clean slate workspace. If you browse to a workspace and add the ?reset parameter then that workspace is cleared.

[mdealencar]

While this feature is not implemented, the code below will create a clickable list of existing workspaces reverse-sorted by modification time.

A notebook in the default workspace with this code (optionally with the extension epi2me-labs/jupyterlab-autorun-cells) works as a makeshift GUI for workspaces.

from pathlib import Path
from datetime import datetime
from IPython.display import display, Markdown

workspaces = []
for f in (Path.home() / '.jupyter/lab/workspaces').glob("*.jupyterlab-workspace"):
    *handle, _ = f.stem.split("-")
    workspaces.append((datetime.fromtimestamp(f.stat().st_mtime), "-".join(handle)))
workspaces.sort(reverse=True)
display(Markdown("\n".join([f"- [{wk}](/lab/workspaces/{wk}) ({date.isoformat(' ', timespec='minutes')})" for date, wk in workspaces])))

[qrdlgit]

Did this issue go dormant or has it been moved elsewhere? I found myself pulled in by workspaces because of the save option, but now I'm at a loss of what to do after a system reboot on recovering it.

Trying different lab/workspaces/ urls did not work. Just said couldn't open the file.

now I'm running into weird issues with jupyterlab losing connection and the only way to fix it seems to be deleting workspaces. https://stackoverflow.com/questions/70361265/server-connection-error-with-conda-and-jupyter-lab

[krassowski]

I wonder if something that the earlier discussion has overlooked would be the presentation of the workspaces themselves. I've just checked and this is the list of workspace identifiers I have:

[
    "auto-0",
    "auto-1",
    "auto-2",
    "auto-3",
    "auto-4",
    "auto-5",
    "auto-6",
    "auto-7",
    "auto-8",
    "auto-9",
    "auto-A",
    "auto-a",
    "auto-b",
    "auto-B",
   // [...]
    "auto-W",
    "auto-w",
    "auto-x",
    "auto-X",
    "auto-y",
    "auto-Y",
    "auto-z",
    "auto-Z",
    "bar",
    "default",
    "/lab",
    "/lab/workspaces/auto-0",
    "/lab/workspaces/auto-1",
    "/lab/workspaces/auto-2",
   // [..]
    "/lab/workspaces/auto-x",
    "/lab/workspaces/auto-y",
    "/lab/workspaces/auto-Y",
    "/lab/workspaces/auto-z",
    "/lab/workspaces/auto-Z"
]

Even if I had a switcher widget, I would not know to which workspace I want to switch. However, there is a lot of useful metadata that we cold use for descriptors, e.g.

• "Last modified X minutes ago",
• "Created on 2023-01-02"
• "A workspace with 2 notebook and 3 files"
• "Simple mode workspace"
• we could even create an dynamic SVG tile which represents the layout

Here is the contents of an example workspace that we can easily access:

{
    "data": {
        "layout-restorer:data": {
            "main": {
                "dock": {
                    "type": "tab-area",
                    "currentIndex": 0,
                    "widgets": [
                        "notebook:Untitled56.ipynb"
                    ]
                },
                "current": "notebook:Untitled56.ipynb"
            },
            "down": {
                "size": 0,
                "widgets": []
            },
            "left": {
                "collapsed": false,
                "visible": true,
                "current": "filebrowser",
                "widgets": [
                    "filebrowser",
                    "running-sessions",
                    "extensionmanager.main-view"
                ],
                "widgetStates": {
                    "jp-running-sessions": {
                        "sizes": [
                            0.25,
                            0.25,
                            0.25,
                            0.25
                        ],
                        "expansionStates": [
                            false,
                            false,
                            false,
                            false
                        ]
                    },
                    "extensionmanager.main-view": {
                        "sizes": [
                            0.3333333333333333,
                            0.3333333333333333,
                            0.3333333333333333
                        ],
                        "expansionStates": [
                            false,
                            false,
                            false
                        ]
                    }
                }
            },
            "right": {
                "collapsed": true,
                "visible": true,
                "widgets": [
                    "jp-property-inspector",
                    "@jupyterlab/toc:plugin",
                    "debugger-sidebar"
                ],
                "widgetStates": {
                    "jp-debugger-sidebar": {
                        "sizes": [
                            0.2,
                            0.2,
                            0.2,
                            0.2,
                            0.2
                        ],
                        "expansionStates": [
                            false,
                            false,
                            false,
                            false,
                            false
                        ]
                    }
                }
            },
            "relativeSizes": [
                0.07538946314456518,
                0.9246105368554348,
                0
            ],
            "top": {
                "simpleVisibility": true
            }
        },
        "notebook:Untitled56.ipynb": {
            "data": {
                "path": "Untitled56.ipynb",
                "factory": "Notebook"
            }
        }
    },
    "metadata": {
        "id": "auto-0",
        "last_modified": "2023-12-01T10:11:25.037295+00:00",
        "created": "2023-12-01T10:11:25.037295+00:00"
    }
}

[isabela-pf]

I’m adding to this issue again because @krassowski may be working on this soon. I come bearing a new set of proposals is meant to build on the discussion above (from years ago, I know, such is open source time) and recommend UI for workspaces that requires minimal new design. As always, feedback is welcome.

I’ve included all the workspace commands I’m aware of from the docs because I find it’s usually easier to plan for taking up the most space and remove items if we don’t find them necessary. If you think some of these commands should not be in the UI as a first pass (or at all) that’s also good to know. These proposals will hold up even if commands are removed from the list shown in the mockups.

I’ve divided proposals by the area of JupyterLab they’d show up in.

Menu items

We could add workspace commands under the File Menu since they do contribute to the set of files open in a JupyterLab.

or

Pros

• Adds workspaces in an inconspicuous but standard area of JupyterLab’s UI.
• Adds workspaces next to other file controls, one of the main things that workspaces also interacts with.

Cons

• Takes up space in already full menus.
• Depending on how many controls are implemented or if they are all collapsed under a Workspaces section, these extra items can run the menu out of the browser window easily.
• We may need other UI to select which workspace some of these commands would apply to (ie. clone which workspace; delete which workspace).

Running side bar

Early on in this issue I proposed an option that put workspaces alongside kernels in the left sidebar. This is updated from that previous proposal. They are still in their own section, but the options available are pared down and the new styling is shown.

Pros

• Adds workspaces to an area that has a flexible amount of space for long lists and allows for collapsing/expanding sections
• Adds workspaces next to other open file controls, one of the main things that workspaces also interacts with.
• Shows which workspace(s?) are active and makes it clear which ones are being operated on via the context menu.

Cons

• This did not seem to get positive feedback last time it was proposed. (At that time, though, collapsible sections were not an option.)

Command palette

No matter what direction we go with, I believe adding workspace commands into JupyterLab’s UI should also show those commands in the command palette. However, it could be an option to only show workspace commands in the command palette and nowhere else.

Pros

• The command palette holds all commands in one place; adding commands preserves the expectation that the command palette is comprehensive.
• Because the command palette filters by search, the space of adding workspace commands is not an issue.

Cons

• It may be harder to discover these controls if they only appear in the command palette.
• We may need other UI to select which workspace some of these commands would apply to (ie. clone which workspace; delete which workspace).

Other notes

Deletion and resetting (or overwriting) other files in JupyterLab leads to a dialog to check that the high-consequence action is intended.

For workspace files, I think we should consider doing the same.

However, even though a workspace file is being deleted, I would consider the stakes to be lower for the kind of information a workspace file saves. I could be convinced that a deletion confirmation dialog is not necessary if someone has good reasoning against it.

[krassowski]

Thank you @isabela-pf! I'm thinking that maybe Workspaces submenu could fit better under the "View" or "Tabs" menu with the rationale being that for user changing/closing/resetting a workspace changes the arrangement/layout/open tabs. What do you think?

[krassowski]

Right now I’m tentatively using this modified version of Material Design’s dashboard icon to represent workspaces. I’ve given it only a little thought, so if anyone has feedback on it feel free to share. If anyone wants to use it, let me know and I'll get you an SVG since GitHub doesn't support them in comments.

I think that the link expired, do you still have the SVG asset somewhere? No worried if not, I can recreate it otherwise.

[rraadd88]

Looking forward to this feature, so I searched for the icon.
Perhaps, this is what you are looking for: https://fonts.google.com/icons?selected=Material+Icons:dashboard:&icon.query=dashboard

[krassowski]

Some thoughts/questions, first on the menu:

• should "Rename Workspace..." in global menu mean the same as "Save Current Workspace As..." or should it first show the list of workspaces to choose which to rename?
  • if it should act on the "current" workspace it appears a bit redundant with "clone"
• what about "Delete Workspace" in here too? Should we even allow deleting the current workspace?

In sidebar:

• should "Delete Workspace" be in the context menu or an icon shown on hover to be consistent with all other sidebar entries? We can use a different icon than the default "x":
  
• should or should we not have "Delete All" button in the sidebar?

[krassowski]

I'm finding "click on workspace in sidebar to open" to be somewhat odd experience in practice:

• a) when I click I either see:
  • if all files are saved I see the loading screen and then the layout changes without confirmation - all expected, but if I mis-clicked a slightly distracting because it takes half a second to few seconds (depending on how large the loaded workspace is)
  • if any file is not saved I see browser confirmation dialog "There are unsaved changes do you want to proceed [Cancel] [Reload]"
• b) this means that the workspace list itself may be no longer shown (sidebar may be collapsed or the list itself may be collapsed, or a different sidebar may be shown)

For (a) I wonder if we should have a custom confirmation dialog when opening a workspace from a sidebar which would always show up. It could have more useful options like "[Cancel] [Save All and Continue]"

For (b) I would consider if we should modify the layout after loading to open the workspaces sidebar if the workspace was opened from the sidebar.

[krassowski]

Another question: what should we do with the existing "Save Workspace" and "Save Current Workspace As..." menu entries/commands? These act pretty similar to "Export" command (they write to disk rather than to API) but have slightly different semantic than "Export".

I think we can tuck them into the "Workspaces" submenu just above import/export.

[krassowski]

It is technically possible to remove the default workspace. Should it be disallowed?

Of note a workspace which is deleted, including the default will automatically regenerate when visiting the linked URL.

[isabela-pf]

Thanks for collecting all these questions, @krassowski! Please let me know if I miss something in trying to answer them.

I do know I owe you more answers to other comments on here, but I didn't want the fact that I didn't have them all answered to block the ones I did. So I will return for the rest! Thank you for your patience.

• “View” and “Tabs” were my next two most likely picks for putting workspaces in the menu when I was exploring possibilities. I don’t think they are bad options. My rationale for not choosing “View” was that it is made of menu items that would change the way things open in JupyterLab would be displayed, but not the content open itself (roughly half of what workspaces do). My rationale for not choosing “Tabs” was that it currently holds menu items to navigate what’s already open and nothing else. I won’t block people from putting workspace menu items there if that’s the decision, just clarifying my thought process in case it helps.
• @rraadd88 has the right link! Thank you very much for digging that up!
• As for the behavior of renaming a workspace from the menu, my instinct is actually to follow the existing renaming file experience (a file is selected via the active tab and a dialog appears to rename that file when prompted). So I think you make a good point that, in many ways, this may operate the same as a Save As. I think it can be redundant with cloning, but I included cloning because it is listed as its own feature in the docs and the goal in this was to give UI to existing features. I think I could be convinced to not have cloning if people agree it seems clear.
• As for deleting workspaces, my rationale was the same as including cloning: it’s representing a feature that already exists. If there’s a technical reason deleting the current workspace can’t happen then it makes sense to have that option inactive for a selected workspace. But I would think users might still need a way to delete other workspaces. Is this question only applying to the menus? Because I believe files can be deleted from the file browser, but not from the File menu and that is a pattern I’m happy to follow with workspaces.
• In the sidebar, I was thinking of deletion being in the context menu like it is for the file browser. However, you are right that the other sections in the Running sidebar do have buttons to close/shut down inline. Because a shut down kernel and closed tab can be reopened but a deleted workspace cannot be restored, I would consider them different behaviors and liken it more to the permanence of the file browser where users need to delete via context menu. But I do think it’s wise generally to try and match the surrounding UI, so I’m really glad you asked and pointed this out.
• As for an equivalent Delete All in the running sidebar, I do like the idea to match the surrounding sidebar but I’m not sure how high stakes such a button would be. Because I don’t think users can batch delete workspaces from the JupyterLab Ui any other way and I’ve been told workspaces can overflow, this might be very useful (if warned with a dialog before deleting all those files in one go). But because it is a more permanent thing to delete versus close a tab or shut down a kernel, I could also see this being dangerous. I’m extra open to insight from workspace users on this one.

[isabela-pf]

Responding to the next questions!

I'm finding "click on workspace in sidebar to open" to be somewhat odd experience in practice:

I think this feedback makes sense. I will say I do not think we need to be able to manage workspaces through both the menu and sidebar as long as all the controls are available. If it makes more sense to work with the menus only, that is perfectly fine from my point of view. You provide some good ideas to workaround it, but ultimately if we can make it simpler by having less UI I’d support that.

I think we can tuck them ["Save Workspace" and "Save Current Workspace As..."] into the "Workspaces" submenu just above import/export.

I think this works. Putting all workspace things together makes sense to me. I am trying to think if there’s a way to combine the commands, but you make a good point they do not do quite the same thing.

It is technically possible to remove the default workspace. Should it be disallowed?

Since it regenerates, I think it runs the risk of being confusing to delete it but never have it disappear from the list. This makes me think it shouldn’t be deletable, only resettable.

[JasonWeill]

I like the idea of deleting the default workspace, but with a special alert: if you delete the default workspace, a new one will be created. Functionally, this would be the same as resetting the default workspace, but some users may prefer the delete UI.