@jupyterlite/terminal 0.2.1 → 1.0.0

package/README.md

@@ -46,6 +46,17 @@ Then build a new JupyterLite site:
 jupyter lite build
 ```
 
+## Version compatibility
+
+Each `jupyterlite-terminal` release is built against a specific version of `cockle`. If you need to
+include imports from both `jupyterlite-terminal` and `cockle`, such as if you are implementing
+`cockle` external commands, you should ensure that you are using the correct version combination.
+
+| `jupyterlite-terminal` | `cockle` | `jupyterlite-core` |
+| ---------------------- | -------- | ------------------ |
+| 1.0.0                  | 1.0.0    | >= 0.6, < 0.7      |
+| 0.2.2                  | 0.1.3    | >= 0.6, < 0.7      |
+
 ## Contributing
 
 ### Development install

package/lib/client.d.ts

@@ -17,10 +17,15 @@ export declare class LiteTerminalAPIClient implements ILiteTerminalAPIClient {
     readonly serverSettings: ServerConnection.ISettings;
     startNew(options?: Terminal.ITerminal.IOptions): Promise<Terminal.IModel>;
     listRunning(): Promise<Terminal.IModel[]>;
+    registerAlias(key: string, value: string): void;
+    registerEnvironmentVariable(key: string, value: string | undefined): void;
     registerExternalCommand(options: IExternalCommand.IOptions): void;
     shutdown(name: string): Promise<void>;
+    themeChange(isDarkMode?: boolean): void;
     private get _models();
     private _nextAvailableName;
+    private _aliases?;
+    private _environment?;
     private _browsingContextId?;
     private _externalCommands;
     private _shellManager;

package/lib/client.js

@@ -39,6 +39,9 @@ export class LiteTerminalAPIClient {
             baseUrl,
             wasmBaseUrl: URLExt.join(baseUrl, 'extensions/@jupyterlite/terminal/static/wasm/'),
             browsingContextId: this._browsingContextId,
+            aliases: this._aliases,
+            environment: this._environment,
+            externalCommands: this._externalCommands,
             shellId: name,
             shellManager: this._shellManager,
             outputCallback: text => {
@@ -48,9 +51,6 @@ export class LiteTerminalAPIClient {
             }
         });
         this._shells.set(name, shell);
-        for (const externalCommand of this._externalCommands) {
-            shell.registerExternalCommand(externalCommand);
-        }
         // Hook to connect socket to shell.
         const hook = async (shell, socket) => {
             shell.socket = socket;
@@ -89,6 +89,18 @@ export class LiteTerminalAPIClient {
     async listRunning() {
         return this._models;
     }
+    registerAlias(key, value) {
+        if (this._aliases === undefined) {
+            this._aliases = {};
+        }
+        this._aliases[key] = value;
+    }
+    registerEnvironmentVariable(key, value) {
+        if (this._environment === undefined) {
+            this._environment = {};
+        }
+        this._environment[key] = value;
+    }
     registerExternalCommand(options) {
         this._externalCommands.push(options);
     }
@@ -102,6 +114,13 @@ export class LiteTerminalAPIClient {
             shell.dispose();
         }
     }
+    themeChange(isDarkMode) {
+        for (const shell of this._shells.values()) {
+            // Can pass isDarkMode when cockle is released with PR #232.
+            //shell.themeChange(isDarkMode);
+            shell.themeChange();
+        }
+    }
     get _models() {
         return Array.from(this._shells.keys(), name => {
             return { name };

package/lib/index.js

@@ -1,7 +1,9 @@
 // Copyright (c) Jupyter Development Team.
 // Distributed under the terms of the Modified BSD License.
-import { ITerminalManager, ServerConnection, IServerSettings, TerminalManager } from '@jupyterlab/services';
+import { IThemeManager } from '@jupyterlab/apputils';
+import { IServerSettings, ITerminalManager, ServerConnection, TerminalManager } from '@jupyterlab/services';
 import { IServiceWorkerManager } from '@jupyterlite/server';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
 import { WebSocket } from 'mock-socket';
 import { LiteTerminalAPIClient } from './client';
 import { ILiteTerminalAPIClient } from './tokens';
@@ -60,10 +62,43 @@ const terminalServiceWorkerPlugin = {
         }
     }
 };
+const terminalThemeChangePlugin = {
+    id: '@jupyterlite/terminal:theme-change',
+    autoStart: true,
+    requires: [ILiteTerminalAPIClient, ISettingRegistry],
+    optional: [IThemeManager],
+    activate: (_, liteTerminalAPIClient, settingRegistry, themeManager) => {
+        // Cache latest terminal theme so can identify if it has changed.
+        let terminalTheme;
+        themeManager === null || themeManager === void 0 ? void 0 : themeManager.themeChanged.connect(async (_, changedArgs) => {
+            // An overall Lab theme change only affects terminals if the terminaTheme is 'inherit'.
+            if (terminalTheme === 'inherit') {
+                const isDarkMode = !themeManager.isLight(changedArgs.newValue);
+                liteTerminalAPIClient.themeChange(isDarkMode);
+            }
+        });
+        // There is no signal for a terminal theme change, so use settings change.
+        settingRegistry
+            .load('@jupyterlab/terminal-extension:plugin')
+            .then(setting => {
+            terminalTheme = setting.composite.theme;
+            setting.changed.connect(() => {
+                // This signal is fired for any change to the terminal settings, not just the theme.
+                // Hence compare with the cached terminalTheme to identify if it has changed.
+                const newTerminalTheme = setting.composite.theme;
+                if (newTerminalTheme !== terminalTheme) {
+                    liteTerminalAPIClient.themeChange();
+                    terminalTheme = newTerminalTheme;
+                }
+            });
+        });
+    }
+};
 export default [
     terminalClientPlugin,
     terminalManagerPlugin,
-    terminalServiceWorkerPlugin
+    terminalServiceWorkerPlugin,
+    terminalThemeChangePlugin
 ];
 // Export ILiteTerminalAPIClient so that other extensions can register external commands.
 export { ILiteTerminalAPIClient };

package/lib/tokens.d.ts

@@ -11,8 +11,23 @@ export interface ILiteTerminalAPIClient extends Terminal.ITerminalAPIClient {
      * Function that handles stdin requests received from service worker.
      */
     handleStdin(request: IStdinRequest): Promise<IStdinReply>;
+    /**
+     * Register an alias that will be available in all terminals.
+     * If the key has already been registered, it will be overwritten.
+     */
+    registerAlias(key: string, value: string): void;
+    /**
+     * Register an environment variable that will be available in all terminals.
+     * If the key has already been registered, it will be overwritten.
+     * A key with an undefined value will be deleted if already registered.
+     */
+    registerEnvironmentVariable(key: string, value: string | undefined): void;
     /**
      * Register an external command that will be available in all terminals.
      */
     registerExternalCommand(options: IExternalCommand.IOptions): void;
+    /**
+     * Inform all terminals that the theme has changed so that they can react to it if they wish.
+     */
+    themeChange(isDarkMode?: boolean): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jupyterlite/terminal",
-    "version": "0.2.1",
+    "version": "1.0.0",
     "description": "A terminal for JupyterLite",
     "keywords": [
         "jupyter",
@@ -59,9 +59,11 @@
         "watch:labextension": "jupyter labextension watch ."
     },
     "dependencies": {
+        "@jupyterlab/apputils": "^4.5.3",
         "@jupyterlab/coreutils": "^6.4.3",
         "@jupyterlab/services": "^7.4.3",
-        "@jupyterlite/cockle": "^0.1.1",
+        "@jupyterlab/settingregistry": "^4.4.3",
+        "@jupyterlite/cockle": "^1.0.0",
         "@jupyterlite/contents": "^0.6.0",
         "@jupyterlite/server": "^0.6.0",
         "@lumino/coreutils": "^2.2.0",
@@ -74,8 +76,8 @@
         "@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",
+        "@typescript-eslint/eslint-plugin": "^7.16.1",
+        "@typescript-eslint/parser": "^7.16.1",
         "css-loader": "^6.7.1",
         "eslint": "^8.36.0",
         "eslint-config-prettier": "^8.8.0",
@@ -92,7 +94,7 @@
         "stylelint-csstree-validator": "^3.0.0",
         "stylelint-prettier": "^4.0.0",
         "ts-loader": "^9.5.2",
-        "typescript": "~5.0.2",
+        "typescript": "~5.7.0",
         "webpack": "^5.87.0",
         "webpack-cli": "^5.1.4",
         "yjs": "^13.5.0"
@@ -112,6 +114,14 @@
         "extension": true,
         "outputDir": "jupyterlite_terminal/labextension",
         "sharedPackages": {
+            "@jupyterlab/apputils": {
+                "bundled": false,
+                "singleton": true
+            },
+            "@jupyterlab/settingregistry": {
+                "bundled": false,
+                "singleton": true
+            },
             "@jupyterlite/contents": {
                 "bundled": false,
                 "singleton": true

package/src/client.ts

@@ -60,6 +60,9 @@ export class LiteTerminalAPIClient implements ILiteTerminalAPIClient {
         'extensions/@jupyterlite/terminal/static/wasm/'
       ),
       browsingContextId: this._browsingContextId,
+      aliases: this._aliases,
+      environment: this._environment,
+      externalCommands: this._externalCommands,
       shellId: name,
       shellManager: this._shellManager,
       outputCallback: text => {
@@ -69,10 +72,6 @@ export class LiteTerminalAPIClient implements ILiteTerminalAPIClient {
     });
     this._shells.set(name, shell);
 
-    for (const externalCommand of this._externalCommands) {
-      shell.registerExternalCommand(externalCommand);
-    }
-
     // Hook to connect socket to shell.
     const hook = async (
       shell: Shell,
@@ -121,6 +120,20 @@ export class LiteTerminalAPIClient implements ILiteTerminalAPIClient {
     return this._models;
   }
 
+  registerAlias(key: string, value: string): void {
+    if (this._aliases === undefined) {
+      this._aliases = {};
+    }
+    this._aliases[key] = value;
+  }
+
+  registerEnvironmentVariable(key: string, value: string | undefined): void {
+    if (this._environment === undefined) {
+      this._environment = {};
+    }
+    this._environment[key] = value;
+  }
+
   registerExternalCommand(options: IExternalCommand.IOptions): void {
     this._externalCommands.push(options);
   }
@@ -135,6 +148,15 @@ export class LiteTerminalAPIClient implements ILiteTerminalAPIClient {
     }
   }
 
+  themeChange(isDarkMode?: boolean): void {
+    for (const shell of this._shells.values()) {
+      // Can pass isDarkMode when cockle is released with PR #232.
+      //shell.themeChange(isDarkMode);
+
+      shell.themeChange();
+    }
+  }
+
   private get _models(): Terminal.IModel[] {
     return Array.from(this._shells.keys(), name => {
       return { name };
@@ -150,6 +172,8 @@ export class LiteTerminalAPIClient implements ILiteTerminalAPIClient {
     }
   }
 
+  private _aliases?: { [key: string]: string };
+  private _environment?: { [key: string]: string | undefined };
   private _browsingContextId?: string;
   private _externalCommands: IExternalCommand.IOptions[] = [];
   private _shellManager: IShellManager;

package/src/index.ts

@@ -5,15 +5,17 @@ import {
   JupyterFrontEnd,
   JupyterFrontEndPlugin
 } from '@jupyterlab/application';
+import { IThemeManager } from '@jupyterlab/apputils';
 import {
+  IServerSettings,
   ITerminalManager,
+  ServerConnection,
   ServiceManagerPlugin,
   Terminal,
-  ServerConnection,
-  IServerSettings,
   TerminalManager
 } from '@jupyterlab/services';
 import { IServiceWorkerManager } from '@jupyterlite/server';
+import { ISettingRegistry } from '@jupyterlab/settingregistry';
 
 import { WebSocket } from 'mock-socket';
 
@@ -94,10 +96,52 @@ const terminalServiceWorkerPlugin: JupyterFrontEndPlugin<void> = {
   }
 };
 
+const terminalThemeChangePlugin: JupyterFrontEndPlugin<void> = {
+  id: '@jupyterlite/terminal:theme-change',
+  autoStart: true,
+  requires: [ILiteTerminalAPIClient, ISettingRegistry],
+  optional: [IThemeManager],
+  activate: (
+    _: JupyterFrontEnd,
+    liteTerminalAPIClient: ILiteTerminalAPIClient,
+    settingRegistry: ISettingRegistry,
+    themeManager?: IThemeManager
+  ): void => {
+    // Cache latest terminal theme so can identify if it has changed.
+    let terminalTheme: string | undefined;
+
+    themeManager?.themeChanged.connect(async (_, changedArgs) => {
+      // An overall Lab theme change only affects terminals if the terminaTheme is 'inherit'.
+      if (terminalTheme === 'inherit') {
+        const isDarkMode = !themeManager.isLight(changedArgs.newValue);
+        liteTerminalAPIClient.themeChange(isDarkMode);
+      }
+    });
+
+    // There is no signal for a terminal theme change, so use settings change.
+    settingRegistry
+      .load('@jupyterlab/terminal-extension:plugin')
+      .then(setting => {
+        terminalTheme = setting.composite.theme as string;
+
+        setting.changed.connect(() => {
+          // This signal is fired for any change to the terminal settings, not just the theme.
+          // Hence compare with the cached terminalTheme to identify if it has changed.
+          const newTerminalTheme = setting.composite.theme as string;
+          if (newTerminalTheme !== terminalTheme) {
+            liteTerminalAPIClient.themeChange();
+            terminalTheme = newTerminalTheme;
+          }
+        });
+      });
+  }
+};
+
 export default [
   terminalClientPlugin,
   terminalManagerPlugin,
-  terminalServiceWorkerPlugin
+  terminalServiceWorkerPlugin,
+  terminalThemeChangePlugin
 ];
 
 // Export ILiteTerminalAPIClient so that other extensions can register external commands.

package/src/tokens.ts

@@ -21,8 +21,26 @@ export interface ILiteTerminalAPIClient extends Terminal.ITerminalAPIClient {
    */
   handleStdin(request: IStdinRequest): Promise<IStdinReply>;
 
+  /**
+   * Register an alias that will be available in all terminals.
+   * If the key has already been registered, it will be overwritten.
+   */
+  registerAlias(key: string, value: string): void;
+
+  /**
+   * Register an environment variable that will be available in all terminals.
+   * If the key has already been registered, it will be overwritten.
+   * A key with an undefined value will be deleted if already registered.
+   */
+  registerEnvironmentVariable(key: string, value: string | undefined): void;
+
   /**
    * Register an external command that will be available in all terminals.
    */
   registerExternalCommand(options: IExternalCommand.IOptions): void;
+
+  /**
+   * Inform all terminals that the theme has changed so that they can react to it if they wish.
+   */
+  themeChange(isDarkMode?: boolean): void;
 }