@jupyterlab/application 4.0.0-alpha.19 → 4.0.0-alpha.20

package/src/status.ts

@@ -0,0 +1,93 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { DisposableDelegate, IDisposable } from '@lumino/disposable';
+import { ISignal, Signal } from '@lumino/signaling';
+import { JupyterFrontEnd } from './frontend';
+import { ILabStatus } from './tokens';
+
+/**
+ * The application status signals and flags class.
+ */
+export class LabStatus implements ILabStatus {
+  /**
+   * Construct a new  status object.
+   */
+  constructor(app: JupyterFrontEnd<any, any>) {
+    this._busySignal = new Signal(app);
+    this._dirtySignal = new Signal(app);
+  }
+
+  /**
+   * Returns a signal for when application changes its busy status.
+   */
+  get busySignal(): ISignal<JupyterFrontEnd, boolean> {
+    return this._busySignal;
+  }
+
+  /**
+   * Returns a signal for when application changes its dirty status.
+   */
+  get dirtySignal(): ISignal<JupyterFrontEnd, boolean> {
+    return this._dirtySignal;
+  }
+
+  /**
+   * Whether the application is busy.
+   */
+  get isBusy(): boolean {
+    return this._busyCount > 0;
+  }
+
+  /**
+   * Whether the application is dirty.
+   */
+  get isDirty(): boolean {
+    return this._dirtyCount > 0;
+  }
+
+  /**
+   * Set the application state to dirty.
+   *
+   * @returns A disposable used to clear the dirty state for the caller.
+   */
+  setDirty(): IDisposable {
+    const oldDirty = this.isDirty;
+    this._dirtyCount++;
+    if (this.isDirty !== oldDirty) {
+      this._dirtySignal.emit(this.isDirty);
+    }
+    return new DisposableDelegate(() => {
+      const oldDirty = this.isDirty;
+      this._dirtyCount = Math.max(0, this._dirtyCount - 1);
+      if (this.isDirty !== oldDirty) {
+        this._dirtySignal.emit(this.isDirty);
+      }
+    });
+  }
+
+  /**
+   * Set the application state to busy.
+   *
+   * @returns A disposable used to clear the busy state for the caller.
+   */
+  setBusy(): IDisposable {
+    const oldBusy = this.isBusy;
+    this._busyCount++;
+    if (this.isBusy !== oldBusy) {
+      this._busySignal.emit(this.isBusy);
+    }
+    return new DisposableDelegate(() => {
+      const oldBusy = this.isBusy;
+      this._busyCount--;
+      if (this.isBusy !== oldBusy) {
+        this._busySignal.emit(this.isBusy);
+      }
+    });
+  }
+
+  private _busyCount = 0;
+  private _busySignal: Signal<JupyterFrontEnd, boolean>;
+  private _dirtyCount = 0;
+  private _dirtySignal: Signal<JupyterFrontEnd, boolean>;
+}

package/src/tokens.ts

@@ -0,0 +1,220 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { ServerConnection, ServiceManager } from '@jupyterlab/services';
+import { ITranslator } from '@jupyterlab/translation';
+import { CommandRegistry } from '@lumino/commands';
+import { ReadonlyPartialJSONObject, Token } from '@lumino/coreutils';
+import { IDisposable } from '@lumino/disposable';
+import { ISignal } from '@lumino/signaling';
+import { JupyterFrontEnd } from '.';
+
+/**
+ * A token for which a plugin can provide to respond to connection failures
+ * to the application server.
+ */
+export const IConnectionLost = new Token<IConnectionLost>(
+  '@jupyterlab/apputils:IConnectionLost'
+);
+
+/**
+ * A function that handles a connection to the server being lost.
+ *
+ * #### Notes
+ * The default implementation shows a simple dialog upon connection
+ * failures, but it may be overridden by extensions to perform other
+ * actions.
+ */
+export type IConnectionLost = (
+  manager: ServiceManager.IManager,
+  err: ServerConnection.NetworkError,
+  translator?: ITranslator
+) => Promise<void>;
+
+/**
+ * The application status token.
+ */
+export const ILabStatus = new Token<ILabStatus>(
+  '@jupyterlab/application:ILabStatus'
+);
+
+/**
+ * An interface for JupyterLab-like application status functionality.
+ */
+export interface ILabStatus {
+  /**
+   * A signal for when application changes its busy status.
+   */
+  readonly busySignal: ISignal<JupyterFrontEnd<any, any>, boolean>;
+
+  /**
+   * A signal for when application changes its dirty status.
+   */
+  readonly dirtySignal: ISignal<JupyterFrontEnd<any, any>, boolean>;
+
+  /**
+   * Whether the application is busy.
+   */
+  readonly isBusy: boolean;
+
+  /**
+   * Whether the application is dirty.
+   */
+  readonly isDirty: boolean;
+
+  /**
+   * Set the application state to busy.
+   *
+   * @returns A disposable used to clear the busy state for the caller.
+   */
+  setBusy(): IDisposable;
+
+  /**
+   * Set the application state to dirty.
+   *
+   * @returns A disposable used to clear the dirty state for the caller.
+   */
+  setDirty(): IDisposable;
+}
+
+/**
+ * The URL Router token.
+ */
+export const IRouter = new Token<IRouter>('@jupyterlab/application:IRouter');
+
+/**
+ * A static class that routes URLs within the application.
+ */
+export interface IRouter {
+  /**
+   * The base URL for the router.
+   */
+  readonly base: string;
+
+  /**
+   * The command registry used by the router.
+   */
+  readonly commands: CommandRegistry;
+
+  /**
+   * The parsed current URL of the application.
+   */
+  readonly current: IRouter.ILocation;
+
+  /**
+   * A signal emitted when the router routes a route.
+   */
+  readonly routed: ISignal<IRouter, IRouter.ILocation>;
+
+  /**
+   * If a matching rule's command resolves with the `stop` token during routing,
+   * no further matches will execute.
+   */
+  readonly stop: Token<void>;
+
+  /**
+   * Navigate to a new path within the application.
+   *
+   * @param path - The new path or empty string if redirecting to root.
+   *
+   * @param options - The navigation options.
+   */
+  navigate(path: string, options?: IRouter.INavOptions): void;
+
+  /**
+   * Register a rule that maps a path pattern to a command.
+   *
+   * @param options - The route registration options.
+   *
+   * @returns A disposable that removes the registered rule from the router.
+   */
+  register(options: IRouter.IRegisterOptions): IDisposable;
+
+  /**
+   * Cause a hard reload of the document.
+   */
+  reload(): void;
+
+  /**
+   * Route a specific path to an action.
+   *
+   * @param url - The URL string that will be routed.
+   *
+   * #### Notes
+   * If a pattern is matched, its command will be invoked with arguments that
+   * match the `IRouter.ILocation` interface.
+   */
+  route(url: string): void;
+}
+
+/**
+ * A namespace for the `IRouter` specification.
+ */
+export namespace IRouter {
+  /**
+   * The parsed location currently being routed.
+   */
+  export interface ILocation extends ReadonlyPartialJSONObject {
+    /**
+     * The location hash.
+     */
+    hash: string;
+
+    /**
+     * The path that matched a routing pattern.
+     */
+    path: string;
+
+    /**
+     * The request being routed with the router `base` omitted.
+     *
+     * #### Notes
+     * This field includes the query string and hash, if they exist.
+     */
+    request: string;
+
+    /**
+     * The search element, including leading question mark (`'?'`), if any,
+     * of the path.
+     */
+    search?: string;
+  }
+
+  /**
+   * The options passed into a navigation request.
+   */
+  export interface INavOptions {
+    /**
+     * Whether the navigation should be hard URL change instead of an HTML
+     * history API change.
+     */
+    hard?: boolean;
+
+    /**
+     * Should the routing stage be skipped when navigating? This will simply rewrite the URL
+     * and push the new state to the history API, no routing commands will be triggered.
+     */
+    skipRouting?: boolean;
+  }
+
+  /**
+   * The specification for registering a route with the router.
+   */
+  export interface IRegisterOptions {
+    /**
+     * The command string that will be invoked upon matching.
+     */
+    command: string;
+
+    /**
+     * The regular expression that will be matched against URLs.
+     */
+    pattern: RegExp;
+
+    /**
+     * The rank order of the registered rule. A lower rank denotes a higher
+     * priority. The default rank is `100`.
+     */
+    rank?: number;
+  }
+}

package/src/treepathupdater.ts

@@ -0,0 +1,20 @@
+/* -----------------------------------------------------------------------------
+| Copyright (c) Jupyter Development Team.
+| Distributed under the terms of the Modified BSD License.
+|----------------------------------------------------------------------------*/
+
+import { Token } from '@lumino/coreutils';
+
+/**
+ * The tree path updater token.
+ */
+export const ITreePathUpdater = new Token<ITreePathUpdater>(
+  '@jupyterlab/application:ITreePathUpdater'
+);
+
+/**
+ * A function to call to update the tree path.
+ */
+export interface ITreePathUpdater {
+  (treePath: string): void;
+}

package/src/utils.ts

@@ -0,0 +1,153 @@
+/*
+ * Copyright (c) Jupyter Development Team.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+import { SemanticCommand } from '@jupyterlab/apputils';
+import { TranslationBundle } from '@jupyterlab/translation';
+import { CommandRegistry } from '@lumino/commands';
+import { JupyterFrontEnd } from './frontend';
+
+export interface ISemanticCommandDefault {
+  /**
+   * Default command to execute if no command is enabled
+   */
+  execute?: string;
+  /**
+   * Default command label
+   */
+  label?: string;
+  /**
+   * Default command caption
+   */
+  caption?: string;
+  /**
+   * Whether the default command is enabled.
+   */
+  isEnabled?: boolean;
+  /**
+   * Whether the default command is toggled.
+   */
+  isToggled?: boolean;
+  /**
+   * Whether the default command is visible.
+   */
+  isVisible?: boolean;
+}
+
+/**
+ * Create the command options from the given semantic commands list
+ * and the given default values.
+ *
+ * @param app Jupyter Application
+ * @param semanticCommands Single semantic command  or a list of commands
+ * @param defaultValues Default values
+ * @param trans Translation bundle
+ * @returns Command options
+ */
+export function createSemanticCommand(
+  app: JupyterFrontEnd,
+  semanticCommands: SemanticCommand | SemanticCommand[],
+  defaultValues: ISemanticCommandDefault,
+  trans: TranslationBundle
+): CommandRegistry.ICommandOptions {
+  const { commands, shell } = app;
+  const commandList = Array.isArray(semanticCommands)
+    ? semanticCommands
+    : [semanticCommands];
+
+  return {
+    label: concatenateTexts('label'),
+    caption: concatenateTexts('caption'),
+    isEnabled: () => {
+      const isEnabled = reduceAttribute('isEnabled');
+      return (
+        (isEnabled.length > 0 &&
+          !isEnabled.some(enabled => enabled === false)) ||
+        (defaultValues.isEnabled ?? false)
+      );
+    },
+    isToggled: () => {
+      const isToggled = reduceAttribute('isToggled');
+      return (
+        isToggled.some(enabled => enabled === true) ||
+        (defaultValues.isToggled ?? false)
+      );
+    },
+    isVisible: () => {
+      const isVisible = reduceAttribute('isVisible');
+      return (
+        (isVisible.length > 0 &&
+          !isVisible.some(visible => visible === false)) ||
+        (defaultValues.isVisible ?? true)
+      );
+    },
+    execute: async () => {
+      const widget = shell.currentWidget;
+      const commandIds = commandList.map(cmd =>
+        widget !== null ? cmd.getActiveCommandId(widget) : null
+      );
+      const toExecute = commandIds.filter(
+        commandId => commandId !== null && commands.isEnabled(commandId)
+      );
+
+      let result: any = null;
+      if (toExecute.length > 0) {
+        for (const commandId of toExecute) {
+          result = await commands.execute(commandId!);
+          if (typeof result === 'boolean' && result === false) {
+            // If a command returns a boolean, assume it is the execution success status
+            // So break if it is false.
+            break;
+          }
+        }
+      } else if (defaultValues.execute) {
+        result = await commands.execute(defaultValues.execute);
+      }
+      return result;
+    }
+  };
+
+  function reduceAttribute(
+    attribute: keyof CommandRegistry.ICommandOptions
+  ): any[] {
+    const widget = shell.currentWidget;
+    const commandIds = commandList.map(cmd =>
+      widget !== null ? cmd.getActiveCommandId(widget) : null
+    );
+    const attributes = commandIds
+      .filter(commandId => commandId !== null)
+      .map(commandId => commands[attribute](commandId!));
+    return attributes;
+  }
+
+  function concatenateTexts(
+    attribute: 'label' | 'caption'
+  ): string | CommandRegistry.CommandFunc<string> | undefined {
+    return () => {
+      const texts = (reduceAttribute(attribute) as string[]).map(
+        (text, textIndex) =>
+          attribute == 'caption' && textIndex > 0
+            ? text.toLocaleLowerCase()
+            : text
+      );
+
+      switch (texts.length) {
+        case 0:
+          return defaultValues[attribute] ?? '';
+        case 1:
+          return texts[0];
+        default: {
+          const hasEllipsis = texts.some(l => /…$/.test(l));
+          const main = texts
+            .slice(undefined, -1)
+            .map(l => l.replace(/…$/, ''))
+            .join(', ');
+          const end =
+            texts.slice(-1)[0].replace(/…$/, '') + (hasEllipsis ? '…' : '');
+          return trans.__('%1 and %2', main, end);
+        }
+      }
+    };
+  }
+}