Shell Management

/**
 * JupyterLab application shell implementation with multi-area layout management
 */
class LabShell extends Widget implements JupyterFrontEnd.IShell {
  constructor(options?: ILabShell.IOptions);
  
  // Event Signals
  /** Signal emitted when the active widget changes */
  readonly activeChanged: ISignal<this, ILabShell.IChangedArgs>;
  
  /** Signal emitted when the current widget changes */
  readonly currentChanged: ISignal<this, ILabShell.IChangedArgs>;
  
  /** Signal emitted when the current path changes */
  readonly currentPathChanged: ISignal<this, ILabShell.ICurrentPathChangedArgs>;
  
  /** Signal emitted when the layout is modified */
  readonly layoutModified: ISignal<this, void>;
  
  /** Signal emitted when the dock panel mode changes */
  readonly modeChanged: ISignal<this, DockPanel.Mode>;
  
  /** Signal emitted when add button is requested */
  readonly addRequested: ISignal<DockPanel, TabBar<Widget>>;
  
  // State Properties
  /** The currently active widget */
  readonly activeWidget: Widget | null;
  
  /** The current widget in focus */
  readonly currentWidget: Widget | null;
  
  /** The current file path */
  readonly currentPath: string | null | undefined;
  
  /** Whether the add button is enabled */
  addButtonEnabled: boolean;
  
  /** Whether the left sidebar is collapsed */
  readonly leftCollapsed: boolean;
  
  /** Whether the right sidebar is collapsed */
  readonly rightCollapsed: boolean;
  
  /** Whether presentation mode is active */
  presentationMode: boolean;
  
  /** The current dock panel mode */
  mode: DockPanel.Mode;
  
  /** Promise that resolves when shell layout is restored */
  readonly restored: Promise<ILabShell.ILayout>;
  
  /** Translation bundle for internationalization */
  translator: ITranslator;
  
  /** User customized layout configuration */
  readonly userLayout: ILabShell.IUserLayout;
  
  // Widget Management Methods
  /**
   * Activate a widget by its ID
   * @param id - Widget ID to activate
   */
  activateById(id: string): void;
  
  /**
   * Activate a specific shell area
   * @param area - Area to activate
   */
  activateArea(area?: ILabShell.Area): void;
  
  /**
   * Add a widget to the shell
   * @param widget - Widget to add
   * @param area - Area to place the widget (defaults to 'main')
   * @param options - Options for opening the widget
   */
  add(widget: Widget, area?: ILabShell.Area, options?: DocumentRegistry.IOpenOptions): void;
  
  /**
   * Move a widget to a different area
   * @param widget - Widget to move
   * @param area - Target area
   * @param mode - Optional dock panel mode
   */
  move(widget: Widget, area: ILabShell.Area, mode?: DockPanel.Mode): void;
  
  // Tab Navigation Methods
  /** Activate the next tab in the current tab bar */
  activateNextTab(): void;
  
  /** Activate the previous tab in the current tab bar */
  activatePreviousTab(): void;
  
  /** Activate the next tab bar */
  activateNextTabBar(): void;
  
  /** Activate the previous tab bar */
  activatePreviousTabBar(): void;
  
  // Layout Management Methods
  /** Collapse the left sidebar */
  collapseLeft(): void;
  
  /** Collapse the right sidebar */
  collapseRight(): void;
  
  /** Expand the left sidebar */
  expandLeft(): void;
  
  /** Expand the right sidebar */
  expandRight(): void;
  
  /** Close all widgets */
  closeAll(): void;
  
  // Visibility Control Methods
  /**
   * Check if a side tab bar is visible
   * @param side - Side to check ('left' or 'right')
   * @returns True if visible
   */
  isSideTabBarVisible(side: 'left' | 'right'): boolean;
  
  /** Check if top area is visible in simple mode */
  isTopInSimpleModeVisible(): boolean;
  
  /**
   * Toggle side tab bar visibility
   * @param side - Side to toggle ('left' or 'right')
   */
  toggleSideTabBarVisibility(side: 'right' | 'left'): void;
  
  /** Toggle top area visibility in simple mode */
  toggleTopInSimpleModeVisibility(): void;
  
  // State Management Methods
  /**
   * Check if an area is empty
   * @param area - Area to check
   * @returns True if area is empty
   */
  isEmpty(area: ILabShell.Area): boolean;
  
  /**
   * Restore the shell layout
   * @param mode - Dock panel mode
   * @param layoutRestorer - Layout restorer instance
   * @param configuration - Optional configuration
   */
  restoreLayout(
    mode: DockPanel.Mode,
    layoutRestorer: LayoutRestorer,
    configuration?: any
  ): Promise<void>;
  
  /**
   * Save the current layout
   * @returns Current layout state
   */
  saveLayout(): ILabShell.ILayout;
  
  /**
   * Update shell configuration
   * @param config - Partial configuration to update
   */
  updateConfig(config: Partial<ILabShell.IConfig>): void;
  
  /**
   * Iterate over widgets in a specific area
   * @param area - Area to iterate (optional, iterates all if not specified)
   * @returns Iterator of widgets
   */
  widgets(area?: ILabShell.Area): IterableIterator<Widget>;
  
  /**
   * Dispose the shell
   */
  dispose(): void;
}

import { LabShell, ILabShell } from "@jupyterlab/application";
import { Widget } from "@lumino/widgets";

// Create a shell
const shell = new LabShell();

// Create and add widgets
const widget1 = new Widget();
widget1.id = 'widget-1';
widget1.title.label = 'My Widget';

shell.add(widget1, 'main');

// Listen to shell events
shell.currentChanged.connect((shell, args) => {
  console.log('Current widget changed:', args.newValue?.title.label);
});

// Navigate between areas
shell.activateArea('left');
shell.activateById('widget-1');

// Layout management
shell.collapseLeft();
shell.expandRight();

// Check states
console.log('Is main area empty?', shell.isEmpty('main'));
console.log('Current widget:', shell.currentWidget?.title.label);

// Save and restore layout
const layout = shell.saveLayout();
console.log('Saved layout:', layout);

/**
 * Available shell areas for widget placement
 */
type ILabShell.Area = 
  | 'main'    // Central content area with tabbed interface
  | 'header'  // Top header area for global controls
  | 'top'     // Top panel area above main content
  | 'menu'    // Menu bar area
  | 'left'    // Left sidebar for panels and tools
  | 'right'   // Right sidebar for panels and tools
  | 'bottom'  // Bottom panel area below main content
  | 'down';   // Down area for secondary content

/**
 * Shell configuration interface
 */
interface ILabShell.IConfig {
  /** Whether to hide tabs when only one tab is present */
  hideSingleDocumentTabs?: boolean;
  
  /** Default dock panel mode */
  defaultMode?: DockPanel.Mode;
  
  /** Whether to show add button on tab bars */
  showAddButton?: boolean;
  
  /**
   * The method for hiding widgets in the dock panel.
   * The default is `display`.
   * Using `scale` will often increase performance as most browsers will not trigger style computation
   * for the transform action.
   * `contentVisibility` is only available in Chromium-based browsers.
   */
  hiddenMode: 'display' | 'scale' | 'contentVisibility';
}

/**
 * Shell constructor options
 */
interface ILabShell.IOptions {
  /** Hidden mode for dock panels */
  hiddenMode?: DockPanel.Mode;
  /** 
   * Whether the layout should wait to be restored before adding widgets or not.
   * Defaults to true
   */
  waitForRestore?: boolean;
}

/**
 * Complete shell layout description
 */
interface ILabShell.ILayout {
  /** Indicates whether fetched session restore data was actually retrieved from the state database or whether it is a fresh blank slate */
  readonly fresh?: boolean;
  
  /** The main area of the user interface */
  readonly mainArea: ILabShell.IMainArea | null;
  
  /** The down area of the user interface */
  readonly downArea: ILabShell.IDownArea | null;
  
  /** The left area of the user interface */
  readonly leftArea: ILabShell.ISideArea | null;
  
  /** The right area of the user interface */
  readonly rightArea: ILabShell.ISideArea | null;
  
  /** The top area of the user interface */
  readonly topArea: ILabShell.ITopArea | null;
  
  /** The relatives sizes of the areas of the user interface */
  readonly relativeSizes: number[] | null;
  
  /** Current dock panel mode */
  mode?: DockPanel.Mode;
  
  /** Whether left sidebar is collapsed */
  leftCollapsed: boolean;
  
  /** Whether right sidebar is collapsed */
  rightCollapsed: boolean;
}

/**
 * Main area layout specification
 */
interface ILabShell.IMainArea {
  /** The current widget that has application focus */
  readonly currentWidget: Widget | null;
  
  /** The contents of the main application dock panel */
  readonly dock: DockLayout.ILayoutConfig | null;
}

/**
 * Side area layout specification
 */
interface ILabShell.ISideArea {
  /** Whether the sidebar is collapsed */
  readonly collapsed: boolean;
  
  /** The current widget that has side area focus */
  readonly currentWidget: Widget | null;
  
  /** A flag denoting whether the side tab bar is visible */
  readonly visible: boolean;
  
  /** The collection of widgets held by the sidebar */
  readonly widgets: Array<Widget> | null;
  
  /** The collection of widgets states held by the sidebar */
  readonly widgetStates: {
    [id: string]: {
      /** Vertical sizes of the widgets */
      readonly sizes: Array<number> | null;
      /** Expansion states of the widgets */
      readonly expansionStates: Array<boolean> | null;
    };
  };
}

/**
 * Top area layout specification
 */
interface ILabShell.ITopArea {
  /** Top area visibility in simple mode */
  readonly simpleVisibility: boolean;
}

/**
 * Down area layout specification
 */
interface ILabShell.IDownArea {
  /** The current widget that has down area focus */
  readonly currentWidget: Widget | null;
  
  /** The collection of widgets held by the panel */
  readonly widgets: Array<Widget> | null;
  
  /** Vertical relative size of the down area. The main area will take the rest of the height */
  readonly size: number | null;
}

/**
 * Widget position specification for adding widgets
 */
interface ILabShell.IWidgetPosition {
  /** Widget area */
  area?: ILabShell.Area;
  
  /** Widget opening options */
  options?: DocumentRegistry.IOpenOptions;
}

/**
 * Widget with deferred addition to shell
 */
interface ILabShell.IDelayedWidget extends ILabShell.IWidgetPosition {
  /** Widget to add */
  widget: Widget;
}

/**
 * User layout customization mapping
 */
interface ILabShell.IUserLayout {
  /** Widget customized position */
  [k: string]: ILabShell.IWidgetPosition;
}

/**
 * Arguments for widget change events (alias for FocusTracker.IChangedArgs)
 */
type ILabShell.IChangedArgs = FocusTracker.IChangedArgs<Widget>;

/**
 * Arguments for current path change events
 */
interface ILabShell.ICurrentPathChangedArgs {
  /** The old value of the tree path, not including '/tree'. */
  readonly oldValue: string;
  
  /** The new value of the tree path, not including '/tree'. */
  readonly newValue: string;
}

/**
 * JupyterLab shell interface (implemented by LabShell)
 */
interface ILabShell extends LabShell {
  // All LabShell methods and properties are available
}

/**
 * Service token for JupyterLab shell
 */
const ILabShell: Token<ILabShell>;

import { ILabShell } from "@jupyterlab/application";
import { JupyterFrontEndPlugin } from "@jupyterlab/application";

// Using ILabShell in a plugin
const plugin: JupyterFrontEndPlugin<void> = {
  id: 'my-shell-plugin',
  autoStart: true,
  requires: [ILabShell],
  activate: (app, shell: ILabShell) => {
    // Use shell in plugin
    shell.currentChanged.connect(() => {
      console.log('Current widget changed');
    });
    
    // Add a widget
    const widget = new Widget();
    widget.id = 'my-plugin-widget';
    shell.add(widget, 'left');
  }
};

/**
 * Area configuration type (alias for DockLayout.AreaConfig)
 */
type ILabShell.AreaConfig = DockLayout.AreaConfig;