@jupyterlab/application 4.0.0-alpha.9 → 4.0.0-beta.0

package/src/mimerenderers.ts

@@ -0,0 +1,180 @@
+// Copyright (c) Jupyter Development Team.
+// Distributed under the terms of the Modified BSD License.
+
+import { IWidgetTracker, WidgetTracker } from '@jupyterlab/apputils';
+import {
+  DocumentRegistry,
+  MimeDocument,
+  MimeDocumentFactory
+} from '@jupyterlab/docregistry';
+import { IRenderMimeRegistry } from '@jupyterlab/rendermime';
+import { IRenderMime } from '@jupyterlab/rendermime-interfaces';
+import { ITranslator } from '@jupyterlab/translation';
+import { LabIcon } from '@jupyterlab/ui-components';
+import { Token } from '@lumino/coreutils';
+import { AttachedProperty } from '@lumino/properties';
+import { JupyterFrontEnd, JupyterFrontEndPlugin } from './index';
+import { ILayoutRestorer } from './layoutrestorer';
+
+/**
+ * A class that tracks mime documents.
+ */
+export interface IMimeDocumentTracker extends IWidgetTracker<MimeDocument> {}
+
+/**
+ * The mime document tracker token.
+ */
+export const IMimeDocumentTracker = new Token<IMimeDocumentTracker>(
+  '@jupyterlab/application:IMimeDocumentTracker'
+);
+
+/**
+ * Create rendermime plugins for rendermime extension modules.
+ */
+export function createRendermimePlugins(
+  extensions: IRenderMime.IExtensionModule[]
+): JupyterFrontEndPlugin<void | IMimeDocumentTracker, any, any>[] {
+  const plugins: JupyterFrontEndPlugin<void | IMimeDocumentTracker>[] = [];
+
+  const namespace = 'application-mimedocuments';
+  const tracker = new WidgetTracker<MimeDocument>({ namespace });
+
+  extensions.forEach(mod => {
+    let data = mod.default;
+
+    // Handle CommonJS exports.
+    if (!mod.hasOwnProperty('__esModule')) {
+      data = mod as any;
+    }
+    if (!Array.isArray(data)) {
+      data = [data] as ReadonlyArray<IRenderMime.IExtension>;
+    }
+    (data as ReadonlyArray<IRenderMime.IExtension>).forEach(item => {
+      plugins.push(createRendermimePlugin(tracker, item));
+    });
+  });
+
+  // Also add a meta-plugin handling state restoration
+  // and exposing the mime document widget tracker.
+  plugins.push({
+    id: '@jupyterlab/application:mimedocument',
+    optional: [ILayoutRestorer],
+    provides: IMimeDocumentTracker,
+    autoStart: true,
+    activate: (app: JupyterFrontEnd, restorer: ILayoutRestorer | null) => {
+      if (restorer) {
+        void restorer.restore(tracker, {
+          command: 'docmanager:open',
+          args: widget => ({
+            path: widget.context.path,
+            factory: Private.factoryNameProperty.get(widget)
+          }),
+          name: widget =>
+            `${widget.context.path}:${Private.factoryNameProperty.get(widget)}`
+        });
+      }
+      return tracker;
+    }
+  });
+
+  return plugins;
+}
+
+/**
+ * Create rendermime plugins for rendermime extension modules.
+ */
+export function createRendermimePlugin(
+  tracker: WidgetTracker<MimeDocument>,
+  item: IRenderMime.IExtension
+): JupyterFrontEndPlugin<void> {
+  return {
+    id: item.id,
+    requires: [IRenderMimeRegistry, ITranslator],
+    autoStart: true,
+    activate: (
+      app: JupyterFrontEnd,
+      rendermime: IRenderMimeRegistry,
+      translator: ITranslator
+    ) => {
+      // Add the mime renderer.
+      if (item.rank !== undefined) {
+        rendermime.addFactory(item.rendererFactory, item.rank);
+      } else {
+        rendermime.addFactory(item.rendererFactory);
+      }
+
+      // Handle the widget factory.
+      if (!item.documentWidgetFactoryOptions) {
+        return;
+      }
+
+      const registry = app.docRegistry;
+      let options: IRenderMime.IDocumentWidgetFactoryOptions[] = [];
+      if (Array.isArray(item.documentWidgetFactoryOptions)) {
+        options = item.documentWidgetFactoryOptions;
+      } else {
+        options = [
+          item.documentWidgetFactoryOptions as IRenderMime.IDocumentWidgetFactoryOptions
+        ];
+      }
+
+      if (item.fileTypes) {
+        item.fileTypes.forEach(ft => {
+          if (ft.icon) {
+            // upconvert the contents of the icon field to a proper LabIcon
+            ft = { ...ft, icon: LabIcon.resolve({ icon: ft.icon }) };
+          }
+
+          app.docRegistry.addFileType(ft as DocumentRegistry.IFileType);
+        });
+      }
+
+      options.forEach(option => {
+        const toolbarFactory = option.toolbarFactory
+          ? (w: MimeDocument) => option.toolbarFactory!(w.content.renderer)
+          : undefined;
+        const factory = new MimeDocumentFactory({
+          renderTimeout: item.renderTimeout,
+          dataType: item.dataType,
+          rendermime,
+          modelName: option.modelName,
+          name: option.name,
+          primaryFileType: registry.getFileType(option.primaryFileType),
+          fileTypes: option.fileTypes,
+          defaultFor: option.defaultFor,
+          defaultRendered: option.defaultRendered,
+          toolbarFactory,
+          translator,
+          factory: item.rendererFactory
+        });
+        registry.addWidgetFactory(factory);
+
+        factory.widgetCreated.connect((sender, widget) => {
+          Private.factoryNameProperty.set(widget, factory.name);
+          // Notify the widget tracker if restore data needs to update.
+          widget.context.pathChanged.connect(() => {
+            void tracker.save(widget);
+          });
+          void tracker.add(widget);
+        });
+      });
+    }
+  };
+}
+
+/**
+ * Private namespace for the module.
+ */
+namespace Private {
+  /**
+   * An attached property for keeping the factory name
+   * that was used to create a mimedocument.
+   */
+  export const factoryNameProperty = new AttachedProperty<
+    MimeDocument,
+    string | undefined
+  >({
+    name: 'factoryName',
+    create: () => undefined
+  });
+}

package/src/router.ts

@@ -0,0 +1,206 @@
+/* -----------------------------------------------------------------------------
+| Copyright (c) Jupyter Development Team.
+| Distributed under the terms of the Modified BSD License.
+|----------------------------------------------------------------------------*/
+
+import { URLExt } from '@jupyterlab/coreutils';
+import { CommandRegistry } from '@lumino/commands';
+import { PromiseDelegate, Token } from '@lumino/coreutils';
+import { DisposableDelegate, IDisposable } from '@lumino/disposable';
+import { ISignal, Signal } from '@lumino/signaling';
+import { IRouter } from './tokens';
+
+/**
+ * A static class that routes URLs within the application.
+ */
+export class Router implements IRouter {
+  /**
+   * Create a URL router.
+   */
+  constructor(options: Router.IOptions) {
+    this.base = options.base;
+    this.commands = options.commands;
+  }
+
+  /**
+   * The base URL for the router.
+   */
+  readonly base: string;
+
+  /**
+   * The command registry used by the router.
+   */
+  readonly commands: CommandRegistry;
+
+  /**
+   * Returns the parsed current URL of the application.
+   */
+  get current(): IRouter.ILocation {
+    const { base } = this;
+    const parsed = URLExt.parse(window.location.href);
+    const { search, hash } = parsed;
+    const path = parsed.pathname?.replace(base, '/') ?? '';
+    const request = path + search + hash;
+
+    return { hash, path, request, search };
+  }
+
+  /**
+   * A signal emitted when the router routes a route.
+   */
+  get routed(): ISignal<this, IRouter.ILocation> {
+    return this._routed;
+  }
+
+  /**
+   * If a matching rule's command resolves with the `stop` token during routing,
+   * no further matches will execute.
+   */
+  readonly stop = new Token<void>('@jupyterlab/application:Router#stop');
+
+  /**
+   * 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 {
+    const { base } = this;
+    const { history } = window;
+    const { hard } = options;
+    const old = document.location.href;
+    const url =
+      path && path.indexOf(base) === 0 ? path : URLExt.join(base, path);
+
+    if (url === old) {
+      return hard ? this.reload() : undefined;
+    }
+
+    history.pushState({}, '', url);
+
+    if (hard) {
+      return this.reload();
+    }
+
+    if (!options.skipRouting) {
+      // Because a `route()` call may still be in the stack after having received
+      // a `stop` token, wait for the next stack frame before calling `route()`.
+      requestAnimationFrame(() => {
+        void this.route();
+      });
+    }
+  }
+
+  /**
+   * Register to route 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 {
+    const { command, pattern } = options;
+    const rank = options.rank ?? 100;
+    const rules = this._rules;
+
+    rules.set(pattern, { command, rank });
+
+    return new DisposableDelegate(() => {
+      rules.delete(pattern);
+    });
+  }
+
+  /**
+   * Cause a hard reload of the document.
+   */
+  reload(): void {
+    window.location.reload();
+  }
+
+  /**
+   * Route a specific path to an action.
+   *
+   * #### Notes
+   * If a pattern is matched, its command will be invoked with arguments that
+   * match the `IRouter.ILocation` interface.
+   */
+  route(): Promise<void> {
+    const { commands, current, stop } = this;
+    const { request } = current;
+    const routed = this._routed;
+    const rules = this._rules;
+    const matches: Private.Rule[] = [];
+
+    // Collect all rules that match the URL.
+    rules.forEach((rule, pattern) => {
+      if (request?.match(pattern)) {
+        matches.push(rule);
+      }
+    });
+
+    // Order the matching rules by rank and enqueue them.
+    const queue = matches.sort((a, b) => b.rank - a.rank);
+    const done = new PromiseDelegate<void>();
+
+    // Process each enqueued command sequentially and short-circuit if a promise
+    // resolves with the `stop` token.
+    const next = async () => {
+      if (!queue.length) {
+        routed.emit(current);
+        done.resolve(undefined);
+        return;
+      }
+
+      const { command } = queue.pop()!;
+
+      try {
+        const request = this.current.request;
+        const result = await commands.execute(command, current);
+        if (result === stop) {
+          queue.length = 0;
+          console.debug(`Routing ${request} was short-circuited by ${command}`);
+        }
+      } catch (reason) {
+        console.warn(`Routing ${request} to ${command} failed`, reason);
+      }
+      void next();
+    };
+    void next();
+
+    return done.promise;
+  }
+
+  private _routed = new Signal<this, IRouter.ILocation>(this);
+  private _rules = new Map<RegExp, Private.Rule>();
+}
+
+/**
+ * A namespace for `Router` class statics.
+ */
+export namespace Router {
+  /**
+   * The options for instantiating a JupyterLab URL router.
+   */
+  export interface IOptions {
+    /**
+     * The fully qualified base URL for the router.
+     */
+    base: string;
+
+    /**
+     * The command registry used by the router.
+     */
+    commands: CommandRegistry;
+  }
+}
+
+/**
+ * A namespace for private module data.
+ */
+namespace Private {
+  /**
+   * The internal representation of a routing rule.
+   */
+  export type Rule = { command: string; rank: number };
+}