or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

application-framework.mdindex.mdlayout-restoration.mdmime-rendering.mdservice-tokens.mdshell-management.mdstatus-management.mdurl-routing.mdutility-functions.md
tile.json

tessl/npm-jupyterlab--application

JupyterLab application framework providing the core application class, shell management, plugin system, layout restoration, and routing capabilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@jupyterlab/application@4.4.x

To install, run

npx @tessl/cli install tessl/npm-jupyterlab--application@4.4.0

index.mddocs/

JupyterLab Application

JupyterLab Application provides the core application framework for JupyterLab, serving as the architectural foundation for building extensible, plugin-based notebook environments. It includes the main application class, shell management system, layout restoration capabilities, URL routing, and a comprehensive plugin infrastructure that enables the modular JupyterLab ecosystem.

Package Information

  • Package Name: @jupyterlab/application
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @jupyterlab/application

Core Imports

import { 
  JupyterLab, 
  JupyterFrontEnd, 
  LabShell, 
  ILabShell,
  LayoutRestorer,
  ILayoutRestorer,
  Router,
  IRouter
} from "@jupyterlab/application";

For CommonJS:

const { 
  JupyterLab, 
  JupyterFrontEnd, 
  LabShell,
  LayoutRestorer,
  Router 
} = require("@jupyterlab/application");

Basic Usage

import { JupyterLab, LabShell } from "@jupyterlab/application";

// Create a JupyterLab application
const lab = new JupyterLab({
  shell: new LabShell()
});

// Register plugins
lab.registerPlugin({
  id: 'my-plugin',
  autoStart: true,
  activate: (app) => {
    console.log('Plugin activated!');
  }
});

// Start the application
lab.start().then(() => {
  console.log('JupyterLab started successfully');
});

Architecture

The JupyterLab Application framework is built around several key architectural components:

  • Application Layer: JupyterLab class extends the abstract JupyterFrontEnd base class, providing plugin management and application lifecycle
  • Shell System: LabShell implements the ILabShell interface, managing UI layout with multiple areas (main, left, right, top, bottom, header, menu, down)
  • Plugin System: Service token-based dependency injection with JupyterFrontEndPlugin type for extensibility
  • Layout Management: LayoutRestorer provides persistent layout state across application sessions
  • Routing System: Router handles URL-based navigation and command routing
  • Status Management: LabStatus tracks application busy/dirty states with reactive signals
  • Service Architecture: Token-based services enable loose coupling and testability

Capabilities

Application Framework

Core application management including the main JupyterLab class, abstract base classes, and plugin system for building extensible notebook applications.

class JupyterLab extends JupyterFrontEnd<ILabShell> {
  constructor(options?: JupyterLab.IOptions);
  readonly name: string;
  readonly namespace: string;
  readonly version: string;
  readonly status: LabStatus;
  readonly info: JupyterLab.IInfo;
  readonly paths: JupyterFrontEnd.IPaths;
  readonly allPluginsActivated: Promise<void>;
}

abstract class JupyterFrontEnd<T extends JupyterFrontEnd.IShell = JupyterFrontEnd.IShell, U extends string = 'desktop' | 'mobile'> extends Application<T> {
  constructor(options: JupyterFrontEnd.IOptions<T>);
  abstract readonly name: string;
  abstract readonly namespace: string;
  abstract readonly version: string;
  readonly commandLinker: CommandLinker;
  readonly contextMenu: ContextMenuSvg;
  readonly docRegistry: DocumentRegistry;
  readonly restored: Promise<void>;
  readonly serviceManager: ServiceManager.IManager;
  format: U;
  readonly formatChanged: ISignal<this, U>;
}

type JupyterFrontEndPlugin<T, U extends JupyterFrontEnd.IShell = JupyterFrontEnd.IShell, V extends string = 'desktop' | 'mobile'> = IPlugin<JupyterFrontEnd<U, V>, T>;

Application Framework

Shell Management

UI shell system providing multi-area layout management, widget placement, tab navigation, and responsive design with collapsible sidebars.

interface ILabShell extends LabShell {
  // Implemented by LabShell class
}

class LabShell extends Widget implements JupyterFrontEnd.IShell {
  constructor(options?: ILabShell.IOptions);
  readonly activeChanged: ISignal<this, ILabShell.IChangedArgs>;
  readonly currentChanged: ISignal<this, ILabShell.IChangedArgs>;
  readonly layoutModified: ISignal<this, void>;
  readonly activeWidget: Widget | null;
  readonly currentWidget: Widget | null;
  add(widget: Widget, area?: ILabShell.Area, options?: DocumentRegistry.IOpenOptions): void;
  activateById(id: string): void;
  collapseLeft(): void;
  collapseRight(): void;
  saveLayout(): ILabShell.ILayout;
}

type ILabShell.Area = 'main' | 'header' | 'top' | 'menu' | 'left' | 'right' | 'bottom' | 'down';

Shell Management

Layout Restoration

Persistent layout state management for saving and restoring widget arrangements, positions, and application state across sessions.

interface ILayoutRestorer extends IRestorer {
  readonly restored: Promise<void>;
  add(widget: Widget, name: string): void;
  restore<T extends Widget>(tracker: WidgetTracker<T>, options: IRestorer.IOptions<T>): Promise<any>;
}

class LayoutRestorer implements ILayoutRestorer {
  constructor(options: LayoutRestorer.IOptions);
  readonly isDeferred: boolean;
  readonly restored: Promise<void>;
  add(widget: Widget, name: string): void;
  fetch(): Promise<ILabShell.ILayout>;
  restore(tracker: WidgetTracker, options: IRestorer.IOptions<Widget>): Promise<any>;
  save(layout: ILabShell.ILayout): Promise<void>;
}

Layout Restoration

URL Routing

URL-based navigation system with pattern matching, command mapping, and programmatic route handling for single-page application behavior.

interface IRouter {
  readonly base: string;
  readonly commands: CommandRegistry;
  readonly current: IRouter.ILocation;
  readonly routed: ISignal<IRouter, IRouter.ILocation>;
  readonly stop: Token<void>;
  navigate(path: string, options?: IRouter.INavOptions): void;
  register(options: IRouter.IRegisterOptions): IDisposable;
  reload(): void;
  route(): Promise<void>;
}

class Router implements IRouter {
  constructor(options: Router.IOptions);
  readonly base: string;
  readonly commands: CommandRegistry;
  navigate(path: string, options?: IRouter.INavOptions): void;
  register(options: IRouter.IRegisterOptions): IDisposable;
  reload(): void;
  route(): Promise<void>;
}

URL Routing

Service Tokens

Dependency injection tokens for service-based architecture, enabling loose coupling and extensibility in the plugin system.

const IConnectionLost: Token<IConnectionLost>;
const ILabStatus: Token<ILabStatus>;
const IRouter: Token<IRouter>;
const ILayoutRestorer: Token<ILayoutRestorer>;
const IMimeDocumentTracker: Token<IMimeDocumentTracker>;
const ITreePathUpdater: Token<ITreePathUpdater>;

type IConnectionLost = (
  manager: ServiceManager.IManager,
  err: ServerConnection.NetworkError,
  translator?: ITranslator
) => Promise<void>;

interface ILabStatus {
  readonly busySignal: ISignal<JupyterFrontEnd<any, any>, boolean>;
  readonly dirtySignal: ISignal<JupyterFrontEnd<any, any>, boolean>;
  readonly isBusy: boolean;
  readonly isDirty: boolean;
  setBusy(): IDisposable;
  setDirty(): IDisposable;
}

Service Tokens

Status Management

Application state tracking for busy and dirty states with reactive signals, supporting UI feedback for long-running operations and unsaved changes.

class LabStatus implements ILabStatus {
  constructor(app: JupyterFrontEnd<any, any>);
  readonly busySignal: ISignal<JupyterFrontEnd, boolean>;
  readonly dirtySignal: ISignal<JupyterFrontEnd, boolean>;
  readonly isBusy: boolean;
  readonly isDirty: boolean;
  setBusy(): IDisposable;
  setDirty(): IDisposable;
}

Status Management

MIME Rendering

Plugin creation utilities for MIME type rendering extensions, enabling support for custom content types and document formats.

interface IMimeDocumentTracker extends IWidgetTracker<MimeDocument> {}

function createRendermimePlugins(
  extensions: IRenderMime.IExtensionModule[]
): JupyterFrontEndPlugin<void | IMimeDocumentTracker, any, any>[];

function createRendermimePlugin(
  tracker: WidgetTracker<MimeDocument>,
  item: IRenderMime.IExtension
): JupyterFrontEndPlugin<void>;

MIME Rendering

Utility Functions

Helper functions for semantic command management, connection lost handling, and tree path updates for enhanced application functionality.

function addSemanticCommand(options: ISemanticCommandOptions): void;

interface ISemanticCommandOptions {
  id: string;
  commands: CommandRegistry;
  shell: JupyterFrontEnd.IShell;
  semanticCommands: SemanticCommand | SemanticCommand[];
  default?: ISemanticCommandDefault;
  overrides?: Omit<CommandRegistry.ICommandOptions, 'execute'>;
  trans?: TranslationBundle;
}

function ConnectionLost(
  manager: ServiceManager.IManager,
  err: ServerConnection.NetworkError,
  translator?: ITranslator
): Promise<void>;

type ITreePathUpdater = (treePath: string) => void;

Utility Functions

Types

Core Application Types

namespace JupyterLab {
  interface IOptions {
    shell?: ILabShell;
    serviceManager?: ServiceManager.IManager;
    paths?: Partial<JupyterFrontEnd.IPaths>;
    disabled?: { patterns?: string[]; matches?: string[] };
    deferred?: { patterns?: string[]; matches?: string[] };
    mimeExtensions?: IRenderMime.IExtensionModule[];
    linkHandler?: ILinkHandler;
  }

  interface IInfo {
    readonly devMode: boolean;
    readonly isConnected: boolean;
    readonly deferred: { patterns?: string[]; matches?: string[] } | null;
    readonly disabled: { patterns?: string[]; matches?: string[] } | null;
  }
}

namespace JupyterFrontEnd {
  interface IOptions<T extends IShell> {
    shell: T;
    commandLinker?: CommandLinker;
    docRegistry?: DocumentRegistry;
    restored?: Promise<void>;
    serviceManager?: ServiceManager.IManager;
    contextMenuRenderer?: IRenderer;
  }

  interface IShell {
    readonly activeChanged: ISignal<this, IChangedArgs>;
    readonly currentChanged: ISignal<this, IChangedArgs>;
    readonly activeWidget: Widget | null;
    readonly currentWidget: Widget | null;
    activateById(id: string): void;
    add(widget: Widget, area?: string, options?: any): void;
    widgets(area?: string): IterableIterator<Widget>;
  }

  interface IPaths {
    readonly urls: {
      readonly base: string;
      readonly notFound?: string;
      readonly app: string;
      readonly static: string;
      readonly settings: string;
      readonly themes: string;
      readonly doc: string;
      readonly translations: string;
      readonly hubHost?: string;
      readonly hubPrefix?: string;
      readonly hubUser?: string;
      readonly hubServerName?: string;
    };
    readonly directories: {
      readonly appDir: string;
      readonly themesDir: string;
      readonly userSettingsDir: string;
      readonly schemasDir: string;
      readonly workspacesDir: string;
    };
  }
}

Shell Layout Types

namespace ILabShell {
  interface IOptions {
    hiddenMode?: DockPanel.Mode;
    waitForRestore?: boolean;
  }

  interface ILayout {
    readonly fresh?: boolean;
    readonly mainArea: IMainArea | null;
    readonly downArea: IDownArea | null;
    readonly leftArea: ISideArea | null;
    readonly rightArea: ISideArea | null;
    readonly topArea: ITopArea | null;
    readonly relativeSizes: number[] | null;
    mode?: DockPanel.Mode;
    leftCollapsed: boolean;
    rightCollapsed: boolean;
  }

  interface IChangedArgs {
    readonly oldValue: Widget | null;
    readonly newValue: Widget | null;
  }

  interface ICurrentPathChangedArgs {
    readonly oldValue: string;
    readonly newValue: string;
  }
}

Router Types

namespace IRouter {
  interface ILocation extends ReadonlyPartialJSONObject {
    hash: string;
    path: string;
    request: string;
    search?: string;
  }

  interface INavOptions {
    hard?: boolean;
    skipRouting?: boolean;
  }

  interface IRegisterOptions {
    command: string;
    pattern: RegExp;
    rank?: number;
  }
}