Add interface to extension (#35)

* Add interface to extension

* Update readme and lite scripts

* Update nx stuff

* Remove caching

* Add error dialog

* Add additional command instructions to readme

* Restructure host

* Improve error messages

* Implement suggestions

Author: gjmooney

README.md

@@ -38,24 +38,22 @@ npm install jupyter-iframe-commands-host
 2. Import and use the `CommandBridge`:
 
 ```typescript
-import { CommandBridge } from 'jupyter-iframe-commands-host';
+import { createBridge } from 'jupyter-iframe-commands-host';
 
 // Initialize the bridge with your iframe ID
-const bridge = new CommandBridge({
-  iframeId: 'your-jupyter-iframe-id'
-});
+const commandBridge = createBridge({ iframeId: 'your-jupyter-iframe-id' });
 
 // Execute JupyterLab commands
 // Example: Toggle the left sidebar
-await bridge.commandBridge.execute('application:toggle-left-area');
+await commandBridge.execute('application:toggle-left-area');
 
 // Example: Change the theme
-await bridge.commandBridge.execute('apputils:change-theme', {
+await commandBridge.execute('apputils:change-theme', {
   theme: 'JupyterLab Dark'
 });
 
 // List available JupyterLab commands
-const commands = await bridge.commandBridge.listCommands();
+const commands = await commandBridge.listCommands();
 console.log(commands);
 ```
 
@@ -121,6 +119,15 @@ Examples of commands with arguments:
 > [!TIP]
 > For reference JupyterLab defines a list of default commands here: https://jupyterlab.readthedocs.io/en/latest/user/commands.html#commands-list
 
+### Adding Additional Commands
+
+This package utilizes a bridge mechanism to transmit commands from the host to the extension running in Jupyter. To expand functionality beyond what's currently offered, you can develop a custom extension that defines new commands. If this custom extension is installed within the same Jupyter environment as the `jupyter-iframe-commands` extension, those commands will become available.
+
+For further information please consult the Jupyter documentation:
+
+- Creating an extension: https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html
+- Adding commands to the command registry: https://jupyterlab.readthedocs.io/en/stable/extension/extension_points.html#commands
+
 ## Demos
 
 ### Local Demo
@@ -152,6 +159,9 @@ To run the demo on a Jupyter Lite instance:
 3. Build and start the demo app:
 
 ```bash
+# Build the lite assets
+jlpm build:lite
+
 # Build the demo
 jlpm build:ghpages
 
@@ -183,10 +193,12 @@ The `jlpm` command is JupyterLab's pinned version of
 # Change directory to the jupyter-iframe-commands directory
 # Install package in development mode
 pip install -e "."
+# Install dependencies
+jlpm install
+# Build extension Typescript source after making changes
+jlpm build
 # Link your development version of the extension with JupyterLab
 jupyter labextension develop . --overwrite
-# Rebuild extension Typescript source after making changes
-jlpm build
 ```
 
 You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.

demo/example.ipynb

@@ -65,7 +65,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.1"
+   "version": "3.12.8"
   }
  },
  "nbformat": 4,

demo/index.html

@@ -24,11 +24,11 @@ <h1>%VITE_TITLE% Demo</h1>
         </button>
         <div class="mode-toggle">
           <label>
-            <input type="radio" name="mode" value="lab" checked>
+            <input type="radio" name="mode" value="lab" checked />
             <span>JupyterLab</span>
           </label>
           <label>
-            <input type="radio" name="mode" value="notebook">
+            <input type="radio" name="mode" value="notebook" />
             <span>Jupyter Notebook</span>
           </label>
         </div>

demo/package.json

@@ -5,8 +5,9 @@
   "type": "module",
   "scripts": {
     "dev": "VITE_DEMO_SRC='./lite/index.html' VITE_TITLE='Lite' vite",
-    "build": "tsc && vite build --base=./",
+    "build": "tsc && VITE_DEMO_SRC='http://localhost:8888' VITE_TITLE='Local' vite build --base=./",
     "build:ghpages": "tsc && VITE_DEMO_SRC='./lite/index.html' VITE_TITLE='Lite' vite build --base=./",
+    "build:lite": "jupyter lite build --contents ../README.md --contents ./example.ipynb --output-dir ./public/lite",
     "preview": "VITE_DEMO_SRC='./lite/index.html' VITE_TITLE='Lite' vite preview",
     "start:lab": "jupyter lab --config jupyter_server_config.py",
     "start:lite": "jlpm dev",

demo/src/main.js

@@ -1,9 +1,17 @@
 /* eslint-disable @typescript-eslint/quotes */
 /* eslint-disable no-undef */
-import { CommandBridge } from 'jupyter-iframe-commands-host';
+import { createBridge } from 'jupyter-iframe-commands-host';
 
-const commandBridge = new CommandBridge({ iframeId: 'jupyterlab' })
-  .commandBridge;
+const commandBridge = createBridge({ iframeId: 'jupyterlab' });
+
+const submitCommand = async (command, args) => {
+  try {
+    await commandBridge.execute(command, args ? JSON.parse(args) : {});
+  } catch (e) {
+    document.getElementById('error-dialog').innerHTML = `<code>${e}</code>`;
+    errorDialog.showModal();
+  }
+};
 
 // Create and append dialogs to the document
 const instructionsDialog = document.createElement('dialog');
@@ -12,7 +20,7 @@ instructionsDialog.innerHTML = `
     <div>
       <h2 style="margin-top: 0;">Instructions</h2>
       <p>To use this demo simply enter a command in the command input and any arguments for that command in the args input.</p>
-      <p>Click the <code style="background-color: lightsteelblue;">List Commands</code> button to see a list of available commands.</p>
+      <p>Click the <code style="background-color: lightsteelblue;">List Available Commands</code> button to see a list of available commands.</p>
       <div style="display: flex; gap: 0.4rem; flex-direction: column; text-align: left; font-size: 0.9rem;">
         <p style="font-weight: bold; padding: 0;">Some commands are listed here for convenience:</p>
         <div class="command-example">
@@ -69,16 +77,28 @@ listCommandsDialog.innerHTML = `
   </form>
 `;
 
+const errorDialog = document.createElement('dialog');
+errorDialog.innerHTML = `
+  <form method="dialog">
+    <h2 style="margin: 0; color: #ED4337;">⚠ Error</h2>
+    <div id="error-dialog"></div>
+    <div class="dialog-buttons">
+      <button value="close">Close</button>
+    </div>
+  </form>
+`;
+
 document.body.appendChild(instructionsDialog);
 document.body.appendChild(listCommandsDialog);
+document.body.appendChild(errorDialog);
 
 document.getElementById('instructions').addEventListener('click', () => {
   instructionsDialog.showModal();
 });
 
 document
   .getElementById('command-select-submit')
-  .addEventListener('click', e => {
+  .addEventListener('click', async e => {
     e.preventDefault();
     const select = document.getElementById('command-select');
     let command = select.value;
@@ -89,7 +109,7 @@ document
         args = `{"theme": "${command}"}`;
         command = 'apputils:change-theme';
       }
-      commandBridge.execute(command, args ? JSON.parse(args) : {});
+      await submitCommand(command, args);
     }
     instructionsDialog.close();
   });
@@ -103,15 +123,16 @@ document.getElementById('list-commands').addEventListener('click', async () => {
   listCommandsDialog.showModal();
 });
 
-document.getElementById('commands').addEventListener('submit', e => {
+document.getElementById('commands').addEventListener('submit', async e => {
   e.preventDefault();
   const command = document.querySelector('input[name="command"]').value;
 
   // Single quotes cause an error
   const args = document
     .querySelector('input[name="args"]')
     .value.replace(/'/g, '"');
-  commandBridge.execute(command, args ? JSON.parse(args) : {});
+
+  await submitCommand(command, args);
 });
 
 // Handle mode toggle

nx.json

@@ -20,7 +20,6 @@
   ],
   "scripts": {
     "build": "lerna run build",
-    "build:lite": "jupyter lite build --contents README.md --output-dir demo/public/lite",
     "build:prod": "lerna run build:prod",
     "clean": "lerna run clean",
     "clean:all": "lerna run clean:all",

package.json

@@ -54,7 +54,8 @@
   },
   "dependencies": {
     "@jupyterlab/application": "^4.3.2",
-    "@jupyterlab/settingregistry": "^4.3.2"
+    "@jupyterlab/settingregistry": "^4.3.2",
+    "@lumino/coreutils": "^2.2.0"
   },
   "devDependencies": {
     "@jupyterlab/builder": "^4.3.2"

packages/extension/package.json

@@ -8,6 +8,7 @@ import {
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
 import { expose, windowEndpoint } from 'comlink';
+import { ICommandBridgeRemote } from './interface';
 
 /**
  * A plugin to expose an API for interacting with JupyterLab from a parent page.
@@ -42,9 +43,9 @@ const plugin: JupyterFrontEndPlugin<void> = {
         });
     }
 
-    const api = {
-      execute(command: string, args: ReadonlyPartialJSONObject) {
-        commands.execute(command, args);
+    const api: ICommandBridgeRemote = {
+      async execute(command: string, args: ReadonlyPartialJSONObject) {
+        await commands.execute(command, args);
       },
       listCommands() {
         return commands.listCommands();
@@ -57,3 +58,4 @@ const plugin: JupyterFrontEndPlugin<void> = {
 };
 
 export default plugin;
+export * from './interface';

packages/extension/src/index.ts

@@ -0,0 +1,23 @@
+import { ReadonlyPartialJSONObject } from '@lumino/coreutils';
+
+/**
+ * Represents a remote command bridge interface.
+ *
+ * This interface provides a standardized way to interact with a Jupyter environment contained in an iframe.
+ */
+export interface ICommandBridgeRemote {
+  /**
+   * Executes a command with the given arguments.
+   *
+   * @param command - The name of the command to execute.
+   * @param args - An object containing arguments for the command.
+   */
+  execute(command: string, args: ReadonlyPartialJSONObject): void;
+
+  /**
+   * Lists all available commands.
+   *
+   * @returns An array of strings representing the names of all available commands.
+   */
+  listCommands(): string[];
+}