Application Framework

/**
 * JupyterLab is the main application class that provides the complete JupyterLab environment
 */
class JupyterLab extends JupyterFrontEnd<ILabShell> {
  constructor(options?: JupyterLab.IOptions);
  
  /** The name of the application from PageConfig */
  readonly name: string;
  
  /** The namespace/prefix for plugins */
  readonly namespace: string;
  
  /** The version of the application from PageConfig */
  readonly version: string;
  
  /** Application status manager for busy/dirty states */
  readonly status: LabStatus;
  
  /** Application information including dev mode and connection status */
  readonly info: JupyterLab.IInfo;
  
  /** Application paths configuration for URLs and directories */
  readonly paths: JupyterFrontEnd.IPaths;
  
  /** Promise that resolves when all plugins are activated */
  readonly allPluginsActivated: Promise<void>;
  
  /** @deprecated Plugin registration errors (will be removed) */
  readonly registerPluginErrors: Array<Error>;
  
  /** @deprecated Register a plugin module (use Application.registerPlugin instead) */
  registerPluginModule(mod: JupyterLab.IPluginModule): void;
  
  /** @deprecated Register multiple plugin modules (use Application.registerPlugins instead) */
  registerPluginModules(mods: JupyterLab.IPluginModule[]): void;
}

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

// Basic JupyterLab creation
const lab = new JupyterLab();

// With custom options
const customLab = new JupyterLab({
  shell: new LabShell(),
  disabled: { patterns: ['*unwanted*'] },
  deferred: { patterns: ['*heavy-plugin*'] }
});

// Wait for all plugins to be activated
await customLab.allPluginsActivated;
console.log('All plugins are ready!');

// Check application status
console.log('App name:', customLab.name);
console.log('Version:', customLab.version);
console.log('Is dev mode:', customLab.info.devMode);

/**
 * Base Jupyter front-end application class that provides plugin support and common services
 * @template T - The shell type (defaults to JupyterFrontEnd.IShell)
 * @template U - Supported format names (defaults to 'desktop' | 'mobile')
 */
abstract class JupyterFrontEnd<
  T extends JupyterFrontEnd.IShell = JupyterFrontEnd.IShell,
  U extends string = 'desktop' | 'mobile'
> extends Application<T> {
  constructor(options: JupyterFrontEnd.IOptions<T>);
  
  /** The name of this Jupyter front-end application */
  abstract readonly name: string;
  
  /** A namespace/prefix plugins may use to denote their provenance */
  abstract readonly namespace: string;
  
  /** The version of this Jupyter front-end application */
  abstract readonly version: string;
  
  /** The command linker used by the application */
  readonly commandLinker: CommandLinker;
  
  /** The application context menu */
  readonly contextMenu: ContextMenuSvg;
  
  /** The document registry instance */
  readonly docRegistry: DocumentRegistry;
  
  /** A promise that resolves when the application is restored */
  readonly restored: Promise<void>;
  
  /** The service manager instance */
  readonly serviceManager: ServiceManager.IManager;
  
  /** The application form factor (desktop, mobile, etc.) */
  format: U;
  
  /** A signal emitted when the format changes */
  readonly formatChanged: ISignal<this, U>;
  
  /** 
   * Test whether the application is in a specific context menu hit test 
   * @param fn - Function to test DOM nodes
   * @returns The matching element or undefined
   */
  contextMenuHitTest(fn: (node: HTMLElement) => boolean): HTMLElement | undefined;
}

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

// Extending JupyterFrontEnd for a custom application
class MyNotebookApp extends JupyterFrontEnd<LabShell> {
  readonly name = 'My Notebook App';
  readonly namespace = 'myapp';
  readonly version = '1.0.0';
}

// Using the format system
const app = new MyNotebookApp({ shell: new LabShell() });
console.log('Current format:', app.format); // 'desktop'

app.format = 'mobile';
app.formatChanged.connect((sender, format) => {
  console.log('Format changed to:', format);
});

// Using context menu hit testing
const hitElement = app.contextMenuHitTest((node) => 
  node.classList.contains('my-special-element')
);

/**
 * The type for all JupyterFrontEnd application plugins
 * @template T - The type that the plugin provides upon being activated
 * @template U - The type of the application shell
 * @template V - The type that defines the application formats
 */
type JupyterFrontEndPlugin<
  T,
  U extends JupyterFrontEnd.IShell = JupyterFrontEnd.IShell,
  V extends string = 'desktop' | 'mobile'
> = IPlugin<JupyterFrontEnd<U, V>, T>;

/**
 * Application information service for runtime configuration data
 */
interface JupyterLab.IInfo {
  /** Whether the application is running in development mode */
  readonly devMode: boolean;
  
  /** Whether the application is connected to the server */
  readonly isConnected: boolean;
  
  /** Deferred plugin configuration, if any */
  readonly deferred: { patterns?: string[]; matches?: string[] } | null;
  
  /** Disabled plugin configuration, if any */
  readonly disabled: { patterns?: string[]; matches?: string[] } | null;
}

/**
 * Service token for accessing application information
 */
const IInfo: Token<JupyterLab.IInfo>;

/**
 * Interface defining URL and directory paths for the application
 */
interface JupyterFrontEnd.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;
  };
}

/**
 * Service token for accessing application paths
 */
const IPaths: Token<JupyterFrontEnd.IPaths>;

/**
 * Interface for resolving tree paths in routing
 */
interface JupyterFrontEnd.ITreeResolver {
  /** Resolve a tree path and return path information */
  resolve(path: string): Promise<JupyterFrontEnd.ITreeResolver.Paths | null>;
}

namespace JupyterFrontEnd.ITreeResolver {
  /** Result of tree path resolution */
  type Paths = {
    file: string;
    workspace: string;
  };
}

/**
 * Service token for tree path resolution
 */
const ITreeResolver: Token<JupyterFrontEnd.ITreeResolver>;

/**
 * Utility function to detect if application is in document mode
 * @param path - The current path
 * @param paths - Application paths configuration
 * @returns True if in document mode
 */
function inDocMode(path: string, paths: JupyterFrontEnd.IPaths): boolean;

namespace JupyterLab {
  interface IOptions {
    /** Custom shell instance (defaults to new LabShell()) */
    shell?: ILabShell;
    
    /** Service manager instance */
    serviceManager?: ServiceManager.IManager;
    
    /** Custom paths configuration */
    paths?: Partial<JupyterFrontEnd.IPaths>;
    
    /** Plugin patterns to disable */
    disabled?: { patterns?: string[]; matches?: string[] };
    
    /** Plugin patterns to defer loading */
    deferred?: { patterns?: string[]; matches?: string[] };
    
    /** MIME renderer extensions */
    mimeExtensions?: IRenderMime.IExtensionModule[];
    
    /** Link handler for external links */
    linkHandler?: ILinkHandler;
  }
}

namespace JupyterFrontEnd {
  interface IOptions<T extends IShell> {
    /** Shell instance (required) */
    shell: T;
    
    /** Command linker instance */
    commandLinker?: CommandLinker;
    
    /** Document registry instance */
    docRegistry?: DocumentRegistry;
    
    /** Application restored promise */
    restored?: Promise<void>;
    
    /** Service manager instance */
    serviceManager?: ServiceManager.IManager;
    
    /** Context menu renderer */
    contextMenuRenderer?: IRenderer;
  }
}

/**
 * Minimal shell interface that applications must implement
 */
interface JupyterFrontEnd.IShell {
  /** Signal emitted when the active widget changes */
  readonly activeChanged: ISignal<this, IChangedArgs>;
  
  /** Signal emitted when the current widget changes */
  readonly currentChanged: ISignal<this, IChangedArgs>;
  
  /** The currently active widget */
  readonly activeWidget: Widget | null;
  
  /** The current widget in focus */
  readonly currentWidget: Widget | null;
  
  /**
   * Activate a widget by its ID
   * @param id - Widget ID to activate
   */
  activateById(id: string): void;
  
  /**
   * Add a widget to the shell
   * @param widget - Widget to add
   * @param area - Area to add the widget to
   * @param options - Additional options
   */
  add(widget: Widget, area?: string, options?: any): void;
  
  /**
   * Iterate over widgets in a specific area
   * @param area - Area to iterate over (optional)
   * @returns Iterator of widgets
   */
  widgets(area?: string): IterableIterator<Widget>;
}

interface IChangedArgs {
  /** Previous widget value */
  readonly oldValue: Widget | null;
  
  /** New widget value */
  readonly newValue: Widget | null;
}