From 000755e4c16d6a17fd26105924c33d2b4c7a8df7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fr=C3=A9d=C3=A9ric=20Collonval?= Date: Sun, 12 Nov 2023 17:25:28 +0100 Subject: [PATCH] Update example --- README.md | 3 +- toparea-text-widget/.copier-answers.yml | 15 ++++--- toparea-text-widget/.gitignore | 4 +- toparea-text-widget/.prettierignore | 2 +- toparea-text-widget/.yarnrc.yml | 2 - toparea-text-widget/README.md | 44 +++++++++++++++++-- toparea-text-widget/install.json | 4 +- .../__init__.py | 4 +- toparea-text-widget/package.json | 30 +++++++------ toparea-text-widget/pyproject.toml | 21 ++++----- toparea-text-widget/setup.py | 2 +- toparea-text-widget/src/index.ts | 12 +++-- toparea-text-widget/ui-tests/package.json | 4 +- ...b_toparea_text.spec.ts => toparea.spec.ts} | 0 toparea-text-widget/ui-tests/yarn.lock | 0 15 files changed, 98 insertions(+), 49 deletions(-) rename toparea-text-widget/{jupyterlab_toparea_text => jupyterlab_examples_toparea}/__init__.py (77%) rename toparea-text-widget/ui-tests/tests/{jupyterlab_toparea_text.spec.ts => toparea.spec.ts} (100%) create mode 100644 toparea-text-widget/ui-tests/yarn.lock diff --git a/README.md b/README.md index 78f72ad8..ee6e9ac7 100644 --- a/README.md +++ b/README.md @@ -227,7 +227,7 @@ Add user interface to edit cell or notebook metadata. [![Metadata Form](metadata-form/preview.gif)](metadata-form) -## [MIME Renderer](mimerenderer) +### [MIME Renderer](mimerenderer) Add a MIME renderer for mp4 content to the application. @@ -279,7 +279,6 @@ Add a new button to the notebook toolbar. A very simple example that adds a basic text widget to the top area. See [related video.](https://www.youtube.com/watch?v=mqotG1MkHa4). This example is part of the [Extension Dual Compatibility Guide](https://jupyterlab.readthedocs.io/en/latest/extension_dual_compatibility.html). -You can find details about this example on that page. [![Top Area Text Widget](toparea-text-widget/preview.jpg)](toparea-text-widget) diff --git a/toparea-text-widget/.copier-answers.yml b/toparea-text-widget/.copier-answers.yml index da53f571..3bb40024 100644 --- a/toparea-text-widget/.copier-answers.yml +++ b/toparea-text-widget/.copier-answers.yml @@ -1,14 +1,19 @@ # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY -_commit: v4.0.9 +_commit: v4.2.4 _src_path: https://github.com/jupyterlab/extension-template author_email: '' -author_name: '' +author_name: Project Jupyter Contributors +data_format: string +file_extension: '' has_binder: true has_settings: false kind: frontend -labextension_name: jupyterlab-toparea-text +labextension_name: '@jupyterlab-examples/toparea' +mimetype: '' +mimetype_name: '' project_short_description: A JupyterLab extension to add text in the top area. -python_name: jupyterlab_toparea_text -repository: '' +python_name: jupyterlab_examples_toparea +repository: https://github.com/jupyterlab/extension-examples test: false +viewer_name: '' diff --git a/toparea-text-widget/.gitignore b/toparea-text-widget/.gitignore index 8b9a6a8e..b7fccf13 100644 --- a/toparea-text-widget/.gitignore +++ b/toparea-text-widget/.gitignore @@ -7,9 +7,9 @@ node_modules/ *.egg-info/ .ipynb_checkpoints *.tsbuildinfo -jupyterlab_toparea_text/labextension +jupyterlab_examples_toparea/labextension # Version file is handled by hatchling -jupyterlab_toparea_text/_version.py +jupyterlab_examples_toparea/_version.py # Created by https://www.gitignore.io/api/python # Edit at https://www.gitignore.io/?templates=python diff --git a/toparea-text-widget/.prettierignore b/toparea-text-widget/.prettierignore index 1205a899..1f176908 100644 --- a/toparea-text-widget/.prettierignore +++ b/toparea-text-widget/.prettierignore @@ -3,4 +3,4 @@ node_modules **/lib **/package.json !/package.json -jupyterlab_toparea_text +jupyterlab_examples_toparea diff --git a/toparea-text-widget/.yarnrc.yml b/toparea-text-widget/.yarnrc.yml index fe1125f5..3186f3f0 100644 --- a/toparea-text-widget/.yarnrc.yml +++ b/toparea-text-widget/.yarnrc.yml @@ -1,3 +1 @@ -enableImmutableInstalls: false - nodeLinker: node-modules diff --git a/toparea-text-widget/README.md b/toparea-text-widget/README.md index b0b77a56..fb3035c6 100644 --- a/toparea-text-widget/README.md +++ b/toparea-text-widget/README.md @@ -1,5 +1,41 @@ -# Top Area Text Widget (jupyterlab_toparea_text) +# Top area widget (cross compatible extension) -A very simple example that adds a basic text widget to the top area. See [related video](https://www.youtube.com/watch?v=mqotG1MkHa4). -This example is part of the [Extension Dual Compatibility Guide](https://jupyterlab.readthedocs.io/en/latest/extension_dual_compatibility.html). -You can find details about this example on that page. +This example defines an extension that adds a single self-contained text widget +to the top bar of the UI. + +![preview](./preview.jpg) + +## Jupyter Notebook / JupyterLab compatibility + +As Jupyter Notebook 7+ is built with components from JupyterLab, and since +both use the same building blocks, that means your extension can work +on both (or any other frontend built with JupyterLab components) with +little or no modification depending on its design. + +This extension doesn't need to do anything at all to be compatible +with both JupyterLab and Notebook 7+ (both apps have a top area that can hold the +widget, so it will be visible in both JupyterLab and Notebook 7+ upon install and +after launch). This will be the case if your extension only uses features +that both applications have. + +## Adding a widget to the top area + +You can add a widget to the top area by calling the following +method of the application shell: + +```ts +// src/index.ts#L34-L34 + +app.shell.add(widget, 'top', { rank: 1000 }); +``` + +The _rank_ is used to order the widget within the top area. + +## Where to Go Next + +If your extension is using features that are not common to both interfaces, +special steps needs to be taken. You can have a look at the [Shout button example](../shout-button-message) +that uses a feature available in JupyterLab but not in Notebook 7+. + +You can have more information about this in the +[Extension Dual Compatibility Guide](https://jupyterlab.readthedocs.io/en/latest/extension_dual_compatibility.html). diff --git a/toparea-text-widget/install.json b/toparea-text-widget/install.json index 3489bbba..c228f499 100644 --- a/toparea-text-widget/install.json +++ b/toparea-text-widget/install.json @@ -1,5 +1,5 @@ { "packageManager": "python", - "packageName": "jupyterlab_toparea_text", - "uninstallInstructions": "Use your Python package manager (pip, conda, etc.) to uninstall the package jupyterlab_toparea_text" + "packageName": "jupyterlab_examples_toparea", + "uninstallInstructions": "Use your Python package manager (pip, conda, etc.) to uninstall the package jupyterlab_examples_toparea" } diff --git a/toparea-text-widget/jupyterlab_toparea_text/__init__.py b/toparea-text-widget/jupyterlab_examples_toparea/__init__.py similarity index 77% rename from toparea-text-widget/jupyterlab_toparea_text/__init__.py rename to toparea-text-widget/jupyterlab_examples_toparea/__init__.py index d22242b5..a31f262d 100644 --- a/toparea-text-widget/jupyterlab_toparea_text/__init__.py +++ b/toparea-text-widget/jupyterlab_examples_toparea/__init__.py @@ -5,12 +5,12 @@ # in editable mode with pip. It is highly recommended to install # the package from a stable release or in editable mode: https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs import warnings - warnings.warn("Importing 'jupyterlab_toparea_text' outside a proper installation.") + warnings.warn("Importing 'jupyterlab_examples_toparea' outside a proper installation.") __version__ = "dev" def _jupyter_labextension_paths(): return [{ "src": "labextension", - "dest": "jupyterlab-toparea-text" + "dest": "@jupyterlab-examples/toparea" }] diff --git a/toparea-text-widget/package.json b/toparea-text-widget/package.json index 1eaa0097..b3cb21c8 100644 --- a/toparea-text-widget/package.json +++ b/toparea-text-widget/package.json @@ -1,5 +1,5 @@ { - "name": "jupyterlab-toparea-text", + "name": "@jupyterlab-examples/toparea", "version": "0.1.0", "description": "A JupyterLab extension to add text in the top area.", "keywords": [ @@ -7,15 +7,12 @@ "jupyterlab", "jupyterlab-extension" ], - "homepage": "", + "homepage": "https://github.com/jupyterlab/extension-examples", "bugs": { - "url": "/issues" + "url": "https://github.com/jupyterlab/extension-examples/issues" }, "license": "BSD-3-Clause", - "author": { - "name": "My Name", - "email": "my@name.org" - }, + "author": "Project Jupyter Contributors", "files": [ "lib/**/*.{d.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf}", "style/**/*.{css,js,eot,gif,html,jpg,json,png,svg,woff2,ttf}" @@ -25,7 +22,7 @@ "style": "style/index.css", "repository": { "type": "git", - "url": ".git" + "url": "https://github.com/jupyterlab/extension-examples.git" }, "scripts": { "build": "jlpm build:lib && jlpm build:labextension:dev", @@ -37,7 +34,7 @@ "clean": "jlpm clean:lib", "clean:lib": "rimraf lib tsconfig.tsbuildinfo", "clean:lintcache": "rimraf .eslintcache .stylelintcache", - "clean:labextension": "rimraf jupyterlab_toparea_text/labextension jupyterlab_toparea_text/_version.py", + "clean:labextension": "rimraf jupyterlab_examples_toparea/labextension jupyterlab_examples_toparea/_version.py", "clean:all": "jlpm clean:lib && jlpm clean:labextension && jlpm clean:lintcache", "eslint": "jlpm eslint:check --fix", "eslint:check": "eslint . --cache --ext .ts,.tsx", @@ -62,20 +59,22 @@ "@jupyterlab/builder": "^4.0.0", "@types/json-schema": "^7.0.11", "@types/react": "^18.0.26", - "@typescript-eslint/eslint-plugin": "^5.55.0", - "@typescript-eslint/parser": "^5.55.0", + "@types/react-addons-linked-state-mixin": "^0.14.22", + "@typescript-eslint/eslint-plugin": "^6.1.0", + "@typescript-eslint/parser": "^6.1.0", "css-loader": "^6.7.1", "eslint": "^8.36.0", "eslint-config-prettier": "^8.8.0", "eslint-plugin-prettier": "^5.0.0", "npm-run-all": "^4.1.5", "prettier": "^3.0.0", - "rimraf": "^4.4.1", + "rimraf": "^5.0.1", "source-map-loader": "^1.0.2", "style-loader": "^3.3.1", "stylelint": "^15.10.1", "stylelint-config-recommended": "^13.0.0", "stylelint-config-standard": "^34.0.0", + "stylelint-csstree-validator": "^3.0.0", "stylelint-prettier": "^4.0.0", "typescript": "~5.0.2", "yjs": "^13.5.0" @@ -90,7 +89,7 @@ }, "jupyterlab": { "extension": true, - "outputDir": "jupyterlab_toparea_text/labextension" + "outputDir": "jupyterlab_examples_toparea/labextension" }, "eslintIgnore": [ "node_modules", @@ -175,8 +174,13 @@ "stylelint-config-standard", "stylelint-prettier/recommended" ], + "plugins": [ + "stylelint-csstree-validator" + ], "rules": { + "csstree/validator": true, "property-no-vendor-prefix": null, + "selector-class-pattern": "^([a-z][A-z\\d]*)(-[A-z\\d]+)*$", "selector-no-vendor-prefix": null, "value-no-vendor-prefix": null } diff --git a/toparea-text-widget/pyproject.toml b/toparea-text-widget/pyproject.toml index 700ab88a..9a2b92ea 100644 --- a/toparea-text-widget/pyproject.toml +++ b/toparea-text-widget/pyproject.toml @@ -1,9 +1,9 @@ [build-system] -requires = ["hatchling>=1.5.0", "jupyterlab>=4.0.0,<5", "hatch-nodejs-version"] +requires = ["hatchling>=1.5.0", "jupyterlab>=4.0.0,<5", "hatch-nodejs-version>=0.3.2"] build-backend = "hatchling.build" [project] -name = "jupyterlab_toparea_text" +name = "jupyterlab_examples_toparea" readme = "README.md" license = {text = "BSD-3-Clause License"} requires-python = ">=3.8" @@ -20,6 +20,7 @@ classifiers = [ "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", ] dependencies = [ ] @@ -32,24 +33,24 @@ source = "nodejs" fields = ["description", "authors", "urls"] [tool.hatch.build.targets.sdist] -artifacts = ["jupyterlab_toparea_text/labextension"] +artifacts = ["jupyterlab_examples_toparea/labextension"] exclude = [".github", "binder"] [tool.hatch.build.targets.wheel.shared-data] -"jupyterlab_toparea_text/labextension" = "share/jupyter/labextensions/jupyterlab-toparea-text" -"install.json" = "share/jupyter/labextensions/jupyterlab-toparea-text/install.json" +"jupyterlab_examples_toparea/labextension" = "share/jupyter/labextensions/@jupyterlab-examples/toparea" +"install.json" = "share/jupyter/labextensions/@jupyterlab-examples/toparea/install.json" [tool.hatch.build.hooks.version] -path = "jupyterlab_toparea_text/_version.py" +path = "jupyterlab_examples_toparea/_version.py" [tool.hatch.build.hooks.jupyter-builder] dependencies = ["hatch-jupyter-builder>=0.5"] build-function = "hatch_jupyter_builder.npm_builder" ensured-targets = [ - "jupyterlab_toparea_text/labextension/static/style.js", - "jupyterlab_toparea_text/labextension/package.json", + "jupyterlab_examples_toparea/labextension/static/style.js", + "jupyterlab_examples_toparea/labextension/package.json", ] -skip-if-exists = ["jupyterlab_toparea_text/labextension/static/style.js"] +skip-if-exists = ["jupyterlab_examples_toparea/labextension/static/style.js"] [tool.hatch.build.hooks.jupyter-builder.build-kwargs] build_cmd = "build:prod" @@ -59,7 +60,7 @@ npm = ["jlpm"] build_cmd = "install:extension" npm = ["jlpm"] source_dir = "src" -build_dir = "jupyterlab_toparea_text/labextension" +build_dir = "jupyterlab_examples_toparea/labextension" [tool.jupyter-releaser.options] version_cmd = "hatch version" diff --git a/toparea-text-widget/setup.py b/toparea-text-widget/setup.py index bea23374..aefdf20d 100644 --- a/toparea-text-widget/setup.py +++ b/toparea-text-widget/setup.py @@ -1 +1 @@ -__import__('setuptools').setup() +__import__("setuptools").setup() diff --git a/toparea-text-widget/src/index.ts b/toparea-text-widget/src/index.ts index 9b9435d8..09b1036d 100644 --- a/toparea-text-widget/src/index.ts +++ b/toparea-text-widget/src/index.ts @@ -10,21 +10,27 @@ import { Widget } from '@lumino/widgets'; const TOP_AREA_CSS_CLASS = 'jp-TopAreaText'; /** - * Initialization data for the jupyterlab-toparea-text extension. + * Initialization data for the @jupyterlab-examples/toparea extension. */ const plugin: JupyterFrontEndPlugin = { - id: 'jupyterlab-toparea-text:plugin', + id: '@jupyterlab-examples/toparea:plugin', description: 'A JupyterLab extension to add text in the top area.', autoStart: true, activate: (app: JupyterFrontEnd) => { - console.log('JupyterLab extension jupyterlab-toparea-text is activated!'); + console.log( + 'JupyterLab extension @jupyterlab-examples/toparea is activated!' + ); + // Create the HTML content of the widget const node = document.createElement('div'); node.textContent = 'Hello World'; + // Create the widget const widget = new Widget({ node }); widget.id = DOMUtils.createDomID(); widget.addClass(TOP_AREA_CSS_CLASS); + + // Add the widget to the top area app.shell.add(widget, 'top', { rank: 1000 }); } }; diff --git a/toparea-text-widget/ui-tests/package.json b/toparea-text-widget/ui-tests/package.json index 336f35fe..947cd072 100644 --- a/toparea-text-widget/ui-tests/package.json +++ b/toparea-text-widget/ui-tests/package.json @@ -1,7 +1,7 @@ { - "name": "jupyterlab_toparea_text-ui-tests", + "name": "jupyterlab_examples_toparea-ui-tests", "version": "1.0.0", - "description": "JupyterLab jupyterlab_toparea_text Integration Tests", + "description": "JupyterLab jupyterlab_examples_toparea Integration Tests", "private": true, "scripts": { "start": "jupyter lab --config jupyter_server_test_config.py", diff --git a/toparea-text-widget/ui-tests/tests/jupyterlab_toparea_text.spec.ts b/toparea-text-widget/ui-tests/tests/toparea.spec.ts similarity index 100% rename from toparea-text-widget/ui-tests/tests/jupyterlab_toparea_text.spec.ts rename to toparea-text-widget/ui-tests/tests/toparea.spec.ts diff --git a/toparea-text-widget/ui-tests/yarn.lock b/toparea-text-widget/ui-tests/yarn.lock new file mode 100644 index 00000000..e69de29b