Example for MainAreaWidget's contentHeader (#185)

* init from cookiecutter

* correct package.json to follow others

* Basic extension demonstrating mainAreaWidget's contentHeader

* update READMEs

* prettier

* no need to use innerHTML, just use textContent

* add extra notes about multiple MainAreaWidgets

* prettier

* add new extension to integration test

* Playwright UI test

* added of @fcollonval's code review suggestions

* prettier

* correct embedme (code snippet line numbers)

* Fix CI

* Make config files homogeneous with hello-world

* Fix playwright config diff

* Fix doc links (#2)

* Fix doc links

* Remove example prettier config

* Fix linter

* Fix labextension name in setup.py

* Apply suggestions from code review

Co-authored-by: Frédéric Collonval <[email protected]>

* Apply suggestions from code review: code

Co-authored-by: Frédéric Collonval <[email protected]>

Co-authored-by: Frédéric Collonval <[email protected]>

Author: fasiha

.github/workflows/main.yml

@@ -33,6 +33,7 @@ jobs:
           - toolbar-button
           - widgets
           - completer
+          - contentheader
         os: [ubuntu-latest, macos-latest, windows-latest]
 
     defaults:

README.md

@@ -7,22 +7,23 @@
 2. [Develop by Examples](#develop-by-examples)
    1. [Commands](#commands)
    2. [Command Palette](#command-palette)
-   3. [Context Menu](#context-menu)
-   4. [Custom Log Console](#custom-log-console)
-   5. [Datagrid](#datagrid)
-   6. _[Hello World](#hello-world)_
-   7. [Kernel Messaging](#kernel-messaging)
-   8. [Kernel Output](#kernel-output)
-   9. [Launcher](#launcher)
-   10. [Log Messages](#log-messages)
-   11. [Main Menu](#main-menu)
-   12. [React Widget](#react-widget)
-   13. _[Server Hello World](#server-hello-world)_
-   14. [Settings](#settings)
-   15. [Signals](#signals)
-   16. [State](#state)
-   17. [Toolbar Item](#toolbar-item)
-   18. [Widgets](#widgets)
+   3. Main Widget [Content Header](#main-widget-content-header)
+   4. [Context Menu](#context-menu)
+   5. [Custom Log Console](#custom-log-console)
+   6. [Datagrid](#datagrid)
+   7. _[Hello World](#hello-world)_
+   8. [Kernel Messaging](#kernel-messaging)
+   9. [Kernel Output](#kernel-output)
+   10. [Launcher](#launcher)
+   11. [Log Messages](#log-messages)
+   12. [Main Menu](#main-menu)
+   13. [React Widget](#react-widget)
+   14. _[Server Hello World](#server-hello-world)_
+   15. [Settings](#settings)
+   16. [Signals](#signals)
+   17. [State](#state)
+   18. [Toolbar Item](#toolbar-item)
+   19. [Widgets](#widgets)
 3. [Prerequisites](#prerequisites)
 4. [Develop and Use the Examples](#develop-and-use-the-examples)
 5. [Test the Examples](#test-the-examples)
@@ -83,6 +84,7 @@ Start with the [Hello World](hello-world) and then jump to the topic you are int
 - [Commands](commands)
 - [Command Palette](command-palette)
 - [Completer](completer)
+- Main Widget [Content Header](contentheader)
 - [Context Menu](context-menu)
 - [Custom Log Console](custom-log-console)
 - [Datagrid](datagrid)
@@ -130,6 +132,12 @@ Customize tab autocomplete data sources.
 
 [![Completer](completer/preview.png)](completer)
 
+### Main Widget [Content Header](contentheader)
+
+Put widgets at the top of a main JupyterLab area widget.
+
+[![contentHeader](contentheader/preview.gif)](contentheader)
+
 ### [Context Menu](context-menu)
 
 Add a new button to an existent context menu.

completer/README.md

@@ -27,7 +27,7 @@ The first part is contained in the `index.ts` file, the second is in `connector.
 
 ## Creating a custom DataConnector
 
-`src/customconnector.ts` defines a `CustomConnector` to generate mock autocomplete suggestions. Like the `ContextConnector` it is based on, `CustomConnector` extends _JupyterLab_'s abstract [`DataConnector`](https://jupyterlab.readthedocs.io/en/latest/api/classes/statedb.dataconnector.html) class.
+`src/customconnector.ts` defines a `CustomConnector` to generate mock autocomplete suggestions. Like the `ContextConnector` it is based on, `CustomConnector` extends _JupyterLab_'s abstract [`DataConnector`](https://jupyterlab.readthedocs.io/en/latest/api/classes/statedb.DataConnector.html) class.
 
 The only abstract method in `DataConnector` is `fetch`, which must be implemented in your `CustomConnector`.
 

contentheader/.eslintignore

@@ -0,0 +1,5 @@
+node_modules
+dist
+coverage
+**/*.d.ts
+ui-tests

contentheader/.eslintrc.js

@@ -0,0 +1,53 @@
+module.exports = {
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/eslint-recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:jsdoc/recommended',
+    'plugin:prettier/recommended',
+    'plugin:react/recommended',
+  ],
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    project: 'tsconfig.json',
+    sourceType: 'module',
+  },
+  plugins: ['@typescript-eslint', 'jsdoc'],
+  rules: {
+    '@typescript-eslint/naming-convention': [
+      'error',
+      {
+        selector: 'interface',
+        format: ['PascalCase'],
+        custom: {
+          regex: '^I[A-Z]',
+          match: true,
+        },
+      },
+    ],
+    '@typescript-eslint/no-unused-vars': ['warn', { args: 'none' }],
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/no-namespace': 'off',
+    '@typescript-eslint/no-use-before-define': 'off',
+    '@typescript-eslint/quotes': [
+      'error',
+      'single',
+      { avoidEscape: true, allowTemplateLiterals: false },
+    ],
+    curly: ['error', 'all'],
+    eqeqeq: 'error',
+    'jsdoc/require-param-type': 'off',
+    'jsdoc/require-property-type': 'off',
+    'jsdoc/require-returns-type': 'off',
+    'jsdoc/no-types': 'warn',
+    'prefer-arrow-callback': 'error',
+  },
+  settings: {
+    jsdoc: {
+      mode: 'typescript',
+    },
+    react: {
+      version: 'detect',
+    },
+  },
+};

contentheader/.gitignore

@@ -0,0 +1,6 @@
+*.bundle.*
+lib/
+node_modules/
+*.egg-info/
+.ipynb_checkpoints
+*.tsbuildinfo

contentheader/MANIFEST.in

@@ -0,0 +1,24 @@
+include LICENSE
+include *.md
+include pyproject.toml
+
+include package.json
+include install.json
+include ts*.json
+include yarn.lock
+
+graft jupyterlab_examples_contentheader/labextension
+
+# Javascript files
+graft src
+graft style
+prune **/node_modules
+prune lib
+prune binder
+
+# Patterns to exclude from any directory
+global-exclude *~
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude .git
+global-exclude .ipynb_checkpoints

contentheader/README.md

@@ -0,0 +1,96 @@
+# Main Widget Content Header
+
+> Insert a widget into the `contentHeader` section of a `MainAreaWidget`—useful for toolbars, headers, etc.
+
+![Demo: activate the extension using Command Palette to populate the time in GMT in the content header](./preview.gif)
+
+This JupyterLab example extension is intended to demo one specific feature of `MainAreaWidget`, namely, its `contentHeader` section.
+
+> As background, `MainAreaWidget` is a high-level JupyterLab widget that conventionally is used to enclose the Launcher (shown above) or a notebook editor. The `contentHeader`, in turn, is a Lumino `BoxPanel` widget positioned at the very top of this main area. This makes the `contentHeader` potentially useful to extensions needing some place to put content that the user will _always see_.
+
+In code: after you get a `MainAreaWidget`, for example via
+
+```ts
+// src/index.ts#L37-L37
+
+const main = app.shell.currentWidget;
+```
+
+you can then create a widget of interest, for example as
+
+```ts
+// src/index.ts#L40-L40
+
+const widget = new Widget();
+```
+
+before finally adding it to the JupyterLab main area's `contentHeader` real estate at its very top:
+
+```ts
+// src/index.ts#L45-L45
+
+main.contentHeader.addWidget(widget);
+```
+
+## Install
+
+First, ensure you've followed the installation instructions in the [top-level README](../README.md), e.g.:
+
+```bash
+# clone the repository
+git clone https://github.com/jupyterlab/extension-examples.git jupyterlab-extension-examples
+
+# go to the extension examples folder
+cd jupyterlab-extension-examples
+
+# create a new environment
+conda env create
+
+# activate the environment
+conda activate jupyterlab-extension-examples
+```
+
+Then build this extension and launch it — this largely follows from the instructions in the top-level [README](../README.md), except using this example instead of the `hello-world` one:
+
+```bash
+# go to the contentheader example
+cd contentheader
+
+# install the extension in editable mode
+python -m pip install -e .
+
+# install your development version of the extension with JupyterLab
+jupyter labextension develop . --overwrite
+
+# build the TypeScript source after making changes
+jlpm run build
+
+# start JupyterLab
+jupyter lab
+```
+
+## Activate
+
+As in the demo animated GIF above, once in JupyterLab
+
+1. Open the [Command Palette](https://jupyterlab.readthedocs.io/en/stable/user/commands.html) via, e.g., _View_ ➜ _Activate Command Palette_.
+2. Type in `populate` to see the command created by this extension: _Populate content header (time example)_.
+3. This will create a small header bar at the top of the main JupyterLab window that shows the current time in GMT (Greenwich Mean Time, also called UTC, Coordinated Universal Time).
+
+> Nota bene, you can _toggle_ the `contentHeader` via the _Command Palette_ ➜ _Show Header Above Content_ if you decide you don't want to see it.
+
+> Nota bene 2, the `contentHeader` and the _Show Header Above Content_ toggle apply on a _per_ `MainAreaWidget`: if you run this extension, it will show the time in the `contentHeader` of the _active_ main area, and the time will not appear in another notebook tab. This may be useful for some extension workflows and not others.
+
+## Implementation notes
+
+For full details see the body of the `execute` function in [`index.ts`](./src/index.ts), but in prose, here's what to do to make use of the `contentHeader` widget.
+
+First, get a `MainAreaWidget`. The approach used here will likely be useful for many JupyterLab use cases: `JupyterFrontEnd.shell.currentWidget` will be a `MainAreaWidget` if your extension is being activated with a classic JupyterLab window, and you can ensure that by testing for `app.shell.currentWidget instanceof MainAreaWidget`.
+
+`MainAreaWidget.contentHeader` is a "top-to-bottom" vertical [Lumino BoxPanel](https://jupyterlab.github.io/lumino/widgets/classes/boxpanel.html). You can call its `addWidget` and `insertWidget` methods to populate this space with your own custom widgets.
+
+## Background
+
+The motivation for this extension example was a question on the Jupyter Discourse, ["How to add Widget to an arbitrary HTMLElement?"](https://discourse.jupyter.org/t/how-to-add-widget-to-an-arbitrary-htmlelement/11576), where Michał Krassowski kindly recommended to create this example to remind JupyterLab developers of this feature.
+
+The feature was added in [that PR](https://github.com/jupyterlab/jupyterlab/pull/9984) which has further discussion.

contentheader/install.json

@@ -0,0 +1,5 @@
+{
+  "packageManager": "python",
+  "packageName": "jupyterlab_examples_contentheader",
+  "uninstallInstructions": "Use your Python package manager (pip, conda, etc.) to uninstall the package jupyterlab_examples_contentheader"
+}

contentheader/jupyterlab_examples_contentheader/__init__.py

@@ -0,0 +1,17 @@
+
+import json
+from pathlib import Path
+
+from ._version import __version__
+
+HERE = Path(__file__).parent.resolve()
+
+with (HERE / "labextension" / "package.json").open() as fid:
+    data = json.load(fid)
+
+def _jupyter_labextension_paths():
+    return [{
+        "src": "labextension",
+        "dest": data["name"]
+    }]
+