Snapshot

.github/labeler.yml

@@ -443,3 +443,11 @@ pkg:vega:
   - any-glob-to-any-file:
     - packages/vega5-extension/**/*
     - packages/vega5-extension/*
+
+pkg:workspaces:
+- changed-files:
+  - any-glob-to-any-file:
+    - packages/workspaces/**/*
+    - packages/workspaces/*
+    - packages/workspaces-extension/**/*
+    - packages/workspaces-extension/*

.github/workflows/linuxjs-tests.yml

@@ -61,6 +61,7 @@ jobs:
             js-translation,
             js-ui-components,
             js-vega5-extension,
+            js-workspaces,
           ]
       fail-fast: false
     runs-on: ubuntu-22.04

.licenserc.yaml

@@ -14,6 +14,7 @@ header:
     - '**/*.svg'
     - '**/*.yml'
     - '**/*.yaml'
+    - '**/*.jupyterlab-workspace'
     - '**/build'
     - '**/lib'
     - '**/node_modules'

buildutils/src/ensure-repo.ts

@@ -282,7 +282,8 @@ const SKIP_CSS: Dict<string[]> = {
     '@jupyterlab/tooltip-extension',
     '@jupyterlab/translation-extension',
     '@jupyterlab/ui-components-extension',
-    '@jupyterlab/vega5-extension'
+    '@jupyterlab/vega5-extension',
+    '@jupyterlab/workspaces-extension'
   ],
   '@jupyterlab/notebook': ['@jupyterlab/application'],
   '@jupyterlab/rendermime-interfaces': ['@lumino/widgets'],

dev_mode/package.json

@@ -118,6 +118,8 @@
     "@jupyterlab/ui-components": "~4.2.0-alpha.1",
     "@jupyterlab/ui-components-extension": "~4.2.0-alpha.1",
     "@jupyterlab/vega5-extension": "~4.2.0-alpha.1",
+    "@jupyterlab/workspaces": "~4.2.0-alpha.1",
+    "@jupyterlab/workspaces-extension": "~4.2.0-alpha.1",
     "@lezer/common": "^1.0.0",
     "@lezer/highlight": "^1.0.0",
     "@lumino/algorithm": "^2.0.0",
@@ -189,7 +191,8 @@
     "@jupyterlab/tooltip-extension": "~4.2.0-alpha.1",
     "@jupyterlab/translation-extension": "~4.2.0-alpha.1",
     "@jupyterlab/ui-components-extension": "~4.2.0-alpha.1",
-    "@jupyterlab/vega5-extension": "~4.2.0-alpha.1"
+    "@jupyterlab/vega5-extension": "~4.2.0-alpha.1",
+    "@jupyterlab/workspaces-extension": "~4.2.0-alpha.1"
   },
   "devDependencies": {
     "@jupyterlab/builder": "^4.2.0-alpha.1",
@@ -265,7 +268,8 @@
       "@jupyterlab/toc-extension": "",
       "@jupyterlab/tooltip-extension": "",
       "@jupyterlab/translation-extension": "",
-      "@jupyterlab/ui-components-extension": ""
+      "@jupyterlab/ui-components-extension": "",
+      "@jupyterlab/workspaces-extension": ""
     },
     "mimeExtensions": {
       "@jupyterlab/javascript-extension": "",
@@ -321,6 +325,7 @@
       "@jupyterlab/tooltip",
       "@jupyterlab/translation",
       "@jupyterlab/ui-components",
+      "@jupyterlab/workspaces",
       "@lezer/common",
       "@lezer/highlight",
       "@lumino/algorithm",
@@ -441,6 +446,8 @@
       "@jupyterlab/ui-components": "../packages/ui-components",
       "@jupyterlab/ui-components-extension": "../packages/ui-components-extension",
       "@jupyterlab/vega5-extension": "../packages/vega5-extension",
+      "@jupyterlab/workspaces": "../packages/workspaces",
+      "@jupyterlab/workspaces-extension": "../packages/workspaces-extension",
       "@jupyterlab/builder": "../builder",
       "@jupyterlab/buildutils": "../buildutils",
       "@jupyterlab/template": "../buildutils/template",

dev_mode/style.js

@@ -45,3 +45,4 @@ import '@jupyterlab/tooltip-extension/style/index.js';
 import '@jupyterlab/translation-extension/style/index.js';
 import '@jupyterlab/ui-components-extension/style/index.js';
 import '@jupyterlab/vega5-extension/style/index.js';
+import '@jupyterlab/workspaces-extension/style/index.js';

docs/source/getting_started/starting.rst

@@ -27,7 +27,7 @@ Example:
 
 You may access JupyterLab by entering the notebook server's :ref:`URL <urls>`
 into the browser. JupyterLab sessions always reside in a
-:ref:`workspace <url-workspaces-ui>`. The default workspace is the main ``/lab`` URL:
+:ref:`workspace <workspaces>`. The default workspace is the main ``/lab`` URL:
 
 .. code-block:: none
 
@@ -37,7 +37,7 @@ Like the classic notebook,
 JupyterLab provides a way for users to copy URLs that
 :ref:`open a specific notebook or file <url-tree>`. Additionally,
 JupyterLab URLs are an advanced part of the user interface that allows for
-managing :ref:`workspaces <url-workspaces-ui>`. To learn more about URLs in
+managing :ref:`workspaces <url-workspaces>`. To learn more about URLs in
 Jupyterlab, visit :ref:`urls`.
 
 JupyterLab runs on top of Jupyter Server, so see the `security

docs/source/user/directories.rst

@@ -300,6 +300,8 @@ the default values given by extensions, as well as the default overrides from
 the :ref:`overrides.json <overridesjson>` file in the application's settings
 directory.
 
+.. _workspaces-directory:
+
 JupyterLab Workspaces Directory
 -------------------------------
 
@@ -315,4 +317,4 @@ environments. The location can be modified using the
 ``JUPYTERLAB_WORKSPACES_DIR`` environment variable.
 
 These files can be imported and exported to create default "profiles", using
-the :ref:`workspace command line tool <url-workspaces-cli>`.
+the :ref:`workspace command line tool <workspaces-cli>`.

docs/source/user/index.md

@@ -20,6 +20,7 @@ file_formats
 debugger
 toc
 extensions
+workspaces
 jupyterhub
 export
 language

docs/source/user/interface.rst

@@ -23,11 +23,12 @@ cell tools inspector <notebook>`, and the :ref:`tabs list <tabs>`.
    :class: jp-screenshot
    :alt: A screenshot of the default JupyterLab interface. The main work area is in the middle. There is also a left sidebar and a top menu bar.
 
-JupyterLab sessions always reside in a :ref:`workspace <url-workspaces-ui>`.
+JupyterLab sessions always reside in a :ref:`workspace <workspaces>`.
 Workspaces contain the state of JupyterLab: the files that are currently open,
 the layout of the application areas and tabs, etc.
 Workspaces can be saved on the server with
-:ref:`named workspace URLs <url-workspaces-ui>`.
+:ref:`named workspace URLs <url-workspaces>` or
+:ref:`using workspace commands <workspaces-gui>` available in the menu and sidebar.
 To learn more about URLs in Jupyterlab, visit :ref:`urls`.
 
 

docs/source/user/urls.rst

@@ -70,10 +70,10 @@ using ``#cell-id=<cell-id>`` Fragment Identification Syntax.
     The ``cell-id`` fragment locator is not part of a formal Jupyter standard and subject to change.
     To leave feedback, please comment in the discussion: `nbformat#317 <https://github.com/jupyter/nbformat/issues/317>`_.
 
-.. _url-workspaces-ui:
+.. _url-workspaces:
 
-Managing Workspaces (UI)
-------------------------
+Managing Workspaces (URL)
+-------------------------
 
 JupyterLab sessions always reside in a workspace. Workspaces contain the state
 of JupyterLab: the files that are currently open, the layout of the application
@@ -168,86 +168,3 @@ To reset the contents of the default workspace and load a notebook:
 .. code-block:: none
 
   http(s)://<server:port>/<lab-location>/lab/tree/path/to/notebook.ipynb?reset
-
-.. _url-workspaces-cli:
-
-Managing Workspaces (CLI)
--------------------------
-
-JupyterLab provides a command-line interface for workspace ``import`` and
-``export``:
-
-.. code-block:: bash
-
-  $ # Exports the default JupyterLab workspace
-  $ jupyter lab workspaces export
-  {"data": {}, "metadata": {"id": "/lab"}}
-  $
-  $ # Exports the workspaces named `foo`
-  $ jupyter lab workspaces export foo
-  {"data": {}, "metadata": {"id": "/lab/workspaces/foo"}}
-  $
-  $ # Exports the workspace named `foo` into a file called `file_name.json`
-  $ jupyter lab workspaces export foo > file_name.json
-  $
-  $ # Imports the workspace file `file_name.json`.
-  $ jupyter lab workspaces import file_name.json
-  Saved workspace: <workspaces-directory>/labworkspacesfoo-54d5.jupyterlab-workspace
-
-The ``export`` functionality is as friendly as possible: if a workspace does not
-exist, it will still generate an empty workspace for export.
-
-The ``import`` functionality validates the structure of the workspace file and
-validates the ``id`` field in the workspace ``metadata`` to make sure its URL is
-compatible with either the ``workspaces_url`` configuration or the ``page_url``
-configuration to verify that it is a correctly named workspace or it is the
-default workspace.
-
-
-Workspace File Format
----------------------
-
-A workspace file in a JSON file with a specific spec.
-
-
-There are two top level keys requires, `data`, and `metadata`.
-
-The `metadata` must be a mapping with an `id`
-key that has the same value as the ID of the workspace. This should also be the relative URL path to access the workspace,
-like `/lab/workspaces/foo`.
-
-The `data` key maps to the initial state of the `IStateDB`. Many plugins look in the State DB for the configuration.
-Also any plugins that register with the `ILayoutRestorer` will look up all keys in the State DB
-that start with the `namespace` of their tracker before the first `:`. The values of these keys should have a `data`
-attribute that maps.
-
-For example, if your workspace looks like this:
-
-.. code-block:: json
-
-  {
-    "data": {
-      "application-mimedocuments:package.json:JSON": {
-        "data": { "path": "package.json", "factory": "JSON" }
-      }
-    }
-  }
-
-It will run the `docmanager:open` with the `{ "path": "package.json", "factory": "JSON" }` args, because the `application-mimedocuments` tracker is registered with the `docmanager:open` command, like this:
-
-
-.. code-block:: typescript
-
-  const namespace = 'application-mimedocuments';
-  const tracker = new WidgetTracker<MimeDocument>({ namespace });
-  void restorer.restore(tracker, {
-    command: 'docmanager:open',
-    args: widget => ({
-      path: widget.context.path,
-      factory: Private.factoryNameProperty.get(widget)
-    }),
-    name: widget =>
-      `${widget.context.path}:${Private.factoryNameProperty.get(widget)}`
-  });
-
-Note the part of the data key after the first `:` (`package.json:JSON`) is dropped and is irrelevant.

docs/source/user/workspaces.rst

@@ -0,0 +1,115 @@
+.. Copyright (c) Jupyter Development Team.
+.. Distributed under the terms of the Modified BSD License.
+
+.. _workspaces:
+
+Workspaces
+==========
+
+A JupyterLab Workspace defines the layout and state of the user interface such as the position of files, notebooks, sidebars, and open/closed state of the panels.
+
+Workspaces can be managed in three ways:
+
+- :ref:`via Graphical User Interface <workspaces-gui>`
+- :ref:`via Command Line Interface <workspaces-cli>`
+- :ref:`via URL schema and parameters <url-workspaces>`
+
+.. _workspaces-gui:
+
+Managing Workspaces (GUI)
+-------------------------
+
+A number of commands is available to manage workspaces from the main menu, sidebar, and command palette:
+
+- `create-new`, `clone`, `rename`, `reset`, and `delete` act on the workspaces stored by on the server in :ref:`the dedicated location <workspaces-directory>`.
+- `save`, `save as`, `import`, and `export` can load and store the workspace to/from the file system (contained within the Jupyter root directory); `save` will save the workspace to the most recently saved file.
+
+In the sidebar the current workspace is indicated with check mark (✓). A different workspace can be opened by clicking on the corresponding sidebar item. Opening context menu (right click) over the workspace item in the sidebar will present actions available for management of that workspace:
+
+.. image:: ../images/workspaces-sidebar.png
+   :align: center
+   :class: jp-screenshot
+   :alt: The context menu opened over workspaces sidebar
+
+.. _workspaces-cli:
+
+Managing Workspaces (CLI)
+-------------------------
+
+JupyterLab provides a command-line interface for workspace ``import`` and
+``export``:
+
+.. code-block:: bash
+
+  $ # Exports the default JupyterLab workspace
+  $ jupyter lab workspaces export
+  {"data": {}, "metadata": {"id": "/lab"}}
+  $
+  $ # Exports the workspaces named `foo`
+  $ jupyter lab workspaces export foo
+  {"data": {}, "metadata": {"id": "/lab/workspaces/foo"}}
+  $
+  $ # Exports the workspace named `foo` into a file called `file_name.json`
+  $ jupyter lab workspaces export foo > file_name.json
+  $
+  $ # Imports the workspace file `file_name.json`.
+  $ jupyter lab workspaces import file_name.json
+  Saved workspace: <workspaces-directory>/labworkspacesfoo-54d5.jupyterlab-workspace
+
+The ``export`` functionality is as friendly as possible: if a workspace does not
+exist, it will still generate an empty workspace for export.
+
+The ``import`` functionality validates the structure of the workspace file and
+validates the ``id`` field in the workspace ``metadata`` to make sure its URL is
+compatible with either the ``workspaces_url`` configuration or the ``page_url``
+configuration to verify that it is a correctly named workspace or it is the
+default workspace.
+
+
+Workspace File Format
+---------------------
+
+A workspace file in a JSON file with a specific spec.
+
+
+There are two top level keys requires, `data`, and `metadata`.
+
+The `metadata` must be a mapping with an `id`
+key that has the same value as the ID of the workspace. This should also be the relative URL path to access the workspace,
+like `/lab/workspaces/foo`. Additionally, `metadata` may contain `created` and `last_modified` fields with date and time creation and most recent modification, respectively. The date and time are encoded using ISO 8601 format.
+
+The `data` key maps to the initial state of the ``IStateDB``. Many plugins look in the State DB for the configuration.
+Also any plugins that register with the ``ILayoutRestorer`` will look up all keys in the State DB
+that start with the `namespace` of their tracker before the first ``:``. The values of these keys should have a `data`
+attribute that maps.
+
+For example, if your workspace looks like this:
+
+.. code-block:: json
+
+  {
+    "data": {
+      "application-mimedocuments:package.json:JSON": {
+        "data": { "path": "package.json", "factory": "JSON" }
+      }
+    }
+  }
+
+It will run the `docmanager:open` with the ``{ "path": "package.json", "factory": "JSON" }`` args, because the `application-mimedocuments` tracker is registered with the `docmanager:open` command, like this:
+
+
+.. code-block:: typescript
+
+  const namespace = 'application-mimedocuments';
+  const tracker = new WidgetTracker<MimeDocument>({ namespace });
+  void restorer.restore(tracker, {
+    command: 'docmanager:open',
+    args: widget => ({
+      path: widget.context.path,
+      factory: Private.factoryNameProperty.get(widget)
+    }),
+    name: widget =>
+      `${widget.context.path}:${Private.factoryNameProperty.get(widget)}`
+  });
+
+Note the part of the data key after the first ``:`` (``package.json:JSON``) is dropped and is irrelevant.