Improve example

clap-button-message/.copier-answers.yml

@@ -1,15 +1,20 @@
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
-_commit: v4.1.0
+_commit: v4.2.4
 _src_path: https://github.com/jupyterlab/extension-template
-author_email: [email protected]
-author_name: My Name
+author_email: ''
+author_name: Project Jupyter Contributors
+data_format: string
+file_extension: ''
 has_binder: false
 has_settings: false
 kind: frontend
-labextension_name: clap_button
+labextension_name: '@jupyterlab-examples/clap-button'
+mimetype: ''
+mimetype_name: ''
 project_short_description: Adds a clap button to the status bar (JupyterLab) or top
     area (Jupyter Notebook 7)
-python_name: clap_button
-repository: ''
-test: false
+python_name: jupyterlab_examples_shout_button
+repository: https://github.com/jupyterlab/extension-examples
+test: true
+viewer_name: ''
 

clap-button-message/.gitignore

@@ -7,9 +7,13 @@ node_modules/
 *.egg-info/
 .ipynb_checkpoints
 *.tsbuildinfo
-clap_button/labextension
+jupyterlab_examples_shout_button/labextension
 # Version file is handled by hatchling
-clap_button/_version.py
+jupyterlab_examples_shout_button/_version.py
+
+# Integration tests
+ui-tests/test-results/
+ui-tests/playwright-report/
 
 # Created by https://www.gitignore.io/api/python
 # Edit at https://www.gitignore.io/?templates=python

clap-button-message/.prettierignore

@@ -3,4 +3,4 @@ node_modules
 **/lib
 **/package.json
 !/package.json
-clap_button
+jupyterlab_examples_shout_button

clap-button-message/.yarnrc.yml

@@ -1,3 +1 @@
-enableImmutableInstalls: false
-
 nodeLinker: node-modules

clap-button-message/README.md

@@ -1,8 +1,81 @@
-# Dual Compatibility Clap Button (clap_button_message)
-
-This example shows an alternate method for achieving dual compatibility: Make an
-extension that is compatible with both JupyterLab and Jupyter Notebook by exporting
-multiple plugins and using "required" features to select different behaviors. Adds a clap button to
-the top area (in JupyterLab) or the right sidebar (Jupyter Notebook). This example is part
-of the [Extension Dual Compatibility Guide](https://jupyterlab.readthedocs.io/en/latest/extension_dual_compatibility.html).
-Read more about this example on that page.
+# Clap Button (cross compatible extension)
+
+This example defines an extension that adds a button that if clicked will
+display an alert to the user. In JupyterLab the button in added in the top
+area (next to the main menu) and in Jupyter Notebook v7+ the button is added to the rights sidebar.
+
+![preview in Notebook v7+](./preview.png)
+
+We strongly advice to look to those examples before diving into this one:
+
+- [widgets](../widgets): The basic DOM Jupyter component.
+- [Simple compatibility example](../toparea-text-widget): Extension working without modification in both Notebook and JupyterLab.
+- [Conditional compatibility example](../shout-button-message): Extension that has
+  a part conditionned on feature specific to JupyterLab.
+
+## 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.
+
+In this example, you will define two different plugins that require
+different tokens to have a custom behavior depending on the frontend used.
+
+## Require tokens
+
+For JupyterLab you can require the specific
+token `ILabShell`.
+
+```ts
+// src/index.ts#L48-L53
+
+const pluginJupyterLab: JupyterFrontEndPlugin<void> = {
+  id: '@jupyterlab-examples/clap-button:pluginLab',
+  description: 'Adds a clap button to the top area JupyterLab',
+  autoStart: true,
+  requires: [ILabShell],
+  activate: (app: JupyterFrontEnd, labShell: ILabShell) => {
+```
+
+And for Jupyter Notebook, you can require the specific token `INotebookShell`.
+
+```ts
+// src/index.ts#L68-L73
+
+const pluginJupyterNotebook: JupyterFrontEndPlugin<void> = {
+  id: '@jupyterlab-examples/clap-button:pluginNotebook',
+  description: 'Adds a clap button to the right sidebar of Jupyter Notebook 7',
+  autoStart: true,
+  requires: [INotebookShell],
+  activate: (app: JupyterFrontEnd, notebookShell: INotebookShell) => {
+```
+
+In the two plugins, the `activate` method will receive as
+second argument the shell token. It is fine to not used
+a required token as here the goal is to allow the application
+to figure out if the plugin should be activated or not.
+
+## Export multiple plugins
+
+If your extension is defining multiple plugin, you have to
+return as default export of your extension package an array
+of plugins. In this example:
+
+```ts
+// src/index.ts#L88-L93
+
+const plugins: JupyterFrontEndPlugin<void>[] = [
+  pluginJupyterLab,
+  pluginJupyterNotebook
+];
+
+export default plugins;
+```
+
+## Where to Go Next
+
+You can have more information about making extension compatible with
+multiple applications in the
+[Extension Dual Compatibility Guide](https://jupyterlab.readthedocs.io/en/latest/extension_dual_compatibility.html).

clap-button-message/install.json

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

clap-button-message/clap_button/__init__.py → clap-button-message/jupyterlab_examples_shout_button/__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 'clap_button' outside a proper installation.")
+    warnings.warn("Importing 'jupyterlab_examples_shout_button' outside a proper installation.")
     __version__ = "dev"
 
 
 def _jupyter_labextension_paths():
     return [{
         "src": "labextension",
-        "dest": "clap_button"
+        "dest": "@jupyterlab-examples/clap-button"
     }]

clap-button-message/package.json

@@ -1,21 +1,18 @@
 {
-    "name": "clap_button",
+    "name": "@jupyterlab-examples/clap-button",
     "version": "0.1.0",
     "description": "Adds a clap button to the top area (JupyterLab) or right area (Jupyter Notebook 7)",
     "keywords": [
         "jupyter",
         "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": "[email protected]"
-    },
+    "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 clap_button/labextension clap_button/_version.py",
+        "clean:labextension": "rimraf jupyterlab_examples_shout_button/labextension jupyterlab_examples_shout_button/_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",
@@ -54,13 +51,16 @@
         "watch:labextension": "jupyter labextension watch ."
     },
     "dependencies": {
-        "@jupyter-notebook/application": "^7.0.2",
-        "@jupyterlab/application": "^4.0.4"
+        "@jupyter-notebook/application": "^7.0.0",
+        "@jupyterlab/application": "^4.0.0",
+        "@lumino/messaging": "^2.0.0",
+        "@lumino/widgets": "^2.0.0"
     },
     "devDependencies": {
         "@jupyterlab/builder": "^4.0.0",
         "@types/json-schema": "^7.0.11",
         "@types/react": "^18.0.26",
+        "@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",
@@ -75,6 +75,7 @@
         "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"
@@ -89,13 +90,16 @@
     },
     "jupyterlab": {
         "extension": true,
-        "outputDir": "clap_button/labextension"
+        "outputDir": "jupyterlab_examples_shout_button/labextension"
     },
     "eslintIgnore": [
         "node_modules",
         "dist",
         "coverage",
-        "**/*.d.ts"
+        "**/*.d.ts",
+        "tests",
+        "**/__tests__",
+        "ui-tests"
     ],
     "eslintConfig": {
         "extends": [
@@ -171,8 +175,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
         }

clap-button-message/pyproject.toml

@@ -1,11 +1,11 @@
 [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 = "clap_button"
+name = "jupyterlab_examples_shout_button"
 readme = "README.md"
-license = { file = "LICENSE" }
+license = { text = "BSD-3-Clause License" }
 requires-python = ">=3.8"
 classifiers = [
     "Framework :: Jupyter",
@@ -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 = ["clap_button/labextension"]
+artifacts = ["jupyterlab_examples_shout_button/labextension"]
 exclude = [".github", "binder"]
 
 [tool.hatch.build.targets.wheel.shared-data]
-"clap_button/labextension" = "share/jupyter/labextensions/clap_button"
-"install.json" = "share/jupyter/labextensions/clap_button/install.json"
+"jupyterlab_examples_shout_button/labextension" = "share/jupyter/labextensions/@jupyterlab-examples/clap-button"
+"install.json" = "share/jupyter/labextensions/@jupyterlab-examples/clap-button/install.json"
 
 [tool.hatch.build.hooks.version]
-path = "clap_button/_version.py"
+path = "jupyterlab_examples_shout_button/_version.py"
 
 [tool.hatch.build.hooks.jupyter-builder]
 dependencies = ["hatch-jupyter-builder>=0.5"]
 build-function = "hatch_jupyter_builder.npm_builder"
 ensured-targets = [
-    "clap_button/labextension/static/style.js",
-    "clap_button/labextension/package.json",
+    "jupyterlab_examples_shout_button/labextension/static/style.js",
+    "jupyterlab_examples_shout_button/labextension/package.json",
 ]
-skip-if-exists = ["clap_button/labextension/static/style.js"]
+skip-if-exists = ["jupyterlab_examples_shout_button/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 = "clap_button/labextension"
+build_dir = "jupyterlab_examples_shout_button/labextension"
 
 [tool.jupyter-releaser.options]
 version_cmd = "hatch version"

clap-button-message/setup.py

@@ -1 +1 @@
-__import__('setuptools').setup()
+__import__("setuptools").setup()