0
# Shell Management
1

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

4
## Capabilities
5

6
### LabShell Class
7

8
Main shell implementation providing multi-area widget management with sophisticated layout controls and responsive behavior.
9

10
```typescript { .api }
11
/**
12
 * JupyterLab application shell implementation with multi-area layout management
13
 */
14
class LabShell extends Widget implements JupyterFrontEnd.IShell {
15
  constructor(options?: ILabShell.IOptions);
16
  
17
  // Event Signals
18
  /** Signal emitted when the active widget changes */
19
  readonly activeChanged: ISignal<this, ILabShell.IChangedArgs>;
20
  
21
  /** Signal emitted when the current widget changes */
22
  readonly currentChanged: ISignal<this, ILabShell.IChangedArgs>;
23
  
24
  /** Signal emitted when the current path changes */
25
  readonly currentPathChanged: ISignal<this, ILabShell.ICurrentPathChangedArgs>;
26
  
27
  /** Signal emitted when the layout is modified */
28
  readonly layoutModified: ISignal<this, void>;
29
  
30
  /** Signal emitted when the dock panel mode changes */
31
  readonly modeChanged: ISignal<this, DockPanel.Mode>;
32
  
33
  /** Signal emitted when add button is requested */
34
  readonly addRequested: ISignal<DockPanel, TabBar<Widget>>;
35
  
36
  // State Properties
37
  /** The currently active widget */
38
  readonly activeWidget: Widget | null;
39
  
40
  /** The current widget in focus */
41
  readonly currentWidget: Widget | null;
42
  
43
  /** The current file path */
44
  readonly currentPath: string | null | undefined;
45
  
46
  /** Whether the add button is enabled */
47
  addButtonEnabled: boolean;
48
  
49
  /** Whether the left sidebar is collapsed */
50
  readonly leftCollapsed: boolean;
51
  
52
  /** Whether the right sidebar is collapsed */
53
  readonly rightCollapsed: boolean;
54
  
55
  /** Whether presentation mode is active */
56
  presentationMode: boolean;
57
  
58
  /** The current dock panel mode */
59
  mode: DockPanel.Mode;
60
  
61
  /** Promise that resolves when shell layout is restored */
62
  readonly restored: Promise<ILabShell.ILayout>;
63
  
64
  /** Translation bundle for internationalization */
65
  translator: ITranslator;
66
  
67
  /** User customized layout configuration */
68
  readonly userLayout: ILabShell.IUserLayout;
69
  
70
  // Widget Management Methods
71
  /**
72
   * Activate a widget by its ID
73
   * @param id - Widget ID to activate
74
   */
75
  activateById(id: string): void;
76
  
77
  /**
78
   * Activate a specific shell area
79
   * @param area - Area to activate
80
   */
81
  activateArea(area?: ILabShell.Area): void;
82
  
83
  /**
84
   * Add a widget to the shell
85
   * @param widget - Widget to add
86
   * @param area - Area to place the widget (defaults to 'main')
87
   * @param options - Options for opening the widget
88
   */
89
  add(widget: Widget, area?: ILabShell.Area, options?: DocumentRegistry.IOpenOptions): void;
90
  
91
  /**
92
   * Move a widget to a different area
93
   * @param widget - Widget to move
94
   * @param area - Target area
95
   * @param mode - Optional dock panel mode
96
   */
97
  move(widget: Widget, area: ILabShell.Area, mode?: DockPanel.Mode): void;
98
  
99
  // Tab Navigation Methods
100
  /** Activate the next tab in the current tab bar */
101
  activateNextTab(): void;
102
  
103
  /** Activate the previous tab in the current tab bar */
104
  activatePreviousTab(): void;
105
  
106
  /** Activate the next tab bar */
107
  activateNextTabBar(): void;
108
  
109
  /** Activate the previous tab bar */
110
  activatePreviousTabBar(): void;
111
  
112
  // Layout Management Methods
113
  /** Collapse the left sidebar */
114
  collapseLeft(): void;
115
  
116
  /** Collapse the right sidebar */
117
  collapseRight(): void;
118
  
119
  /** Expand the left sidebar */
120
  expandLeft(): void;
121
  
122
  /** Expand the right sidebar */
123
  expandRight(): void;
124
  
125
  /** Close all widgets */
126
  closeAll(): void;
127
  
128
  // Visibility Control Methods
129
  /**
130
   * Check if a side tab bar is visible
131
   * @param side - Side to check ('left' or 'right')
132
   * @returns True if visible
133
   */
134
  isSideTabBarVisible(side: 'left' | 'right'): boolean;
135
  
136
  /** Check if top area is visible in simple mode */
137
  isTopInSimpleModeVisible(): boolean;
138
  
139
  /**
140
   * Toggle side tab bar visibility
141
   * @param side - Side to toggle ('left' or 'right')
142
   */
143
  toggleSideTabBarVisibility(side: 'right' | 'left'): void;
144
  
145
  /** Toggle top area visibility in simple mode */
146
  toggleTopInSimpleModeVisibility(): void;
147
  
148
  // State Management Methods
149
  /**
150
   * Check if an area is empty
151
   * @param area - Area to check
152
   * @returns True if area is empty
153
   */
154
  isEmpty(area: ILabShell.Area): boolean;
155
  
156
  /**
157
   * Restore the shell layout
158
   * @param mode - Dock panel mode
159
   * @param layoutRestorer - Layout restorer instance
160
   * @param configuration - Optional configuration
161
   */
162
  restoreLayout(
163
    mode: DockPanel.Mode,
164
    layoutRestorer: LayoutRestorer,
165
    configuration?: any
166
  ): Promise<void>;
167
  
168
  /**
169
   * Save the current layout
170
   * @returns Current layout state
171
   */
172
  saveLayout(): ILabShell.ILayout;
173
  
174
  /**
175
   * Update shell configuration
176
   * @param config - Partial configuration to update
177
   */
178
  updateConfig(config: Partial<ILabShell.IConfig>): void;
179
  
180
  /**
181
   * Iterate over widgets in a specific area
182
   * @param area - Area to iterate (optional, iterates all if not specified)
183
   * @returns Iterator of widgets
184
   */
185
  widgets(area?: ILabShell.Area): IterableIterator<Widget>;
186
  
187
  /**
188
   * Dispose the shell
189
   */
190
  dispose(): void;
191
}
192
```
193

194
**Usage Examples:**
195

196
```typescript
197
import { LabShell, ILabShell } from "@jupyterlab/application";
198
import { Widget } from "@lumino/widgets";
199

200
// Create a shell
201
const shell = new LabShell();
202

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

208
shell.add(widget1, 'main');
209

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

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

219
// Layout management
220
shell.collapseLeft();
221
shell.expandRight();
222

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

227
// Save and restore layout
228
const layout = shell.saveLayout();
229
console.log('Saved layout:', layout);
230
```
231

232
### Shell Areas
233

234
The shell provides multiple predefined areas for widget placement with specific behaviors and layouts.
235

236
```typescript { .api }
237
/**
238
 * Available shell areas for widget placement
239
 */
240
type ILabShell.Area = 
241
  | 'main'    // Central content area with tabbed interface
242
  | 'header'  // Top header area for global controls
243
  | 'top'     // Top panel area above main content
244
  | 'menu'    // Menu bar area
245
  | 'left'    // Left sidebar for panels and tools
246
  | 'right'   // Right sidebar for panels and tools
247
  | 'bottom'  // Bottom panel area below main content
248
  | 'down';   // Down area for secondary content
249
```
250

251
### Shell Configuration
252

253
Configuration options for customizing shell behavior and appearance.
254

255
```typescript { .api }
256
/**
257
 * Shell configuration interface
258
 */
259
interface ILabShell.IConfig {
260
  /** Whether to hide tabs when only one tab is present */
261
  hideSingleDocumentTabs?: boolean;
262
  
263
  /** Default dock panel mode */
264
  defaultMode?: DockPanel.Mode;
265
  
266
  /** Whether to show add button on tab bars */
267
  showAddButton?: boolean;
268
  
269
  /**
270
   * The method for hiding widgets in the dock panel.
271
   * The default is `display`.
272
   * Using `scale` will often increase performance as most browsers will not trigger style computation
273
   * for the transform action.
274
   * `contentVisibility` is only available in Chromium-based browsers.
275
   */
276
  hiddenMode: 'display' | 'scale' | 'contentVisibility';
277
}
278

279
/**
280
 * Shell constructor options
281
 */
282
interface ILabShell.IOptions {
283
  /** Hidden mode for dock panels */
284
  hiddenMode?: DockPanel.Mode;
285
  /** 
286
   * Whether the layout should wait to be restored before adding widgets or not.
287
   * Defaults to true
288
   */
289
  waitForRestore?: boolean;
290
}
291
```
292

293
### Layout System
294

295
Complete layout description and management for the shell's multi-area system.
296

297
```typescript { .api }
298
/**
299
 * Complete shell layout description
300
 */
301
interface ILabShell.ILayout {
302
  /** Indicates whether fetched session restore data was actually retrieved from the state database or whether it is a fresh blank slate */
303
  readonly fresh?: boolean;
304
  
305
  /** The main area of the user interface */
306
  readonly mainArea: ILabShell.IMainArea | null;
307
  
308
  /** The down area of the user interface */
309
  readonly downArea: ILabShell.IDownArea | null;
310
  
311
  /** The left area of the user interface */
312
  readonly leftArea: ILabShell.ISideArea | null;
313
  
314
  /** The right area of the user interface */
315
  readonly rightArea: ILabShell.ISideArea | null;
316
  
317
  /** The top area of the user interface */
318
  readonly topArea: ILabShell.ITopArea | null;
319
  
320
  /** The relatives sizes of the areas of the user interface */
321
  readonly relativeSizes: number[] | null;
322
  
323
  /** Current dock panel mode */
324
  mode?: DockPanel.Mode;
325
  
326
  /** Whether left sidebar is collapsed */
327
  leftCollapsed: boolean;
328
  
329
  /** Whether right sidebar is collapsed */
330
  rightCollapsed: boolean;
331
}
332

333
/**
334
 * Main area layout specification
335
 */
336
interface ILabShell.IMainArea {
337
  /** The current widget that has application focus */
338
  readonly currentWidget: Widget | null;
339
  
340
  /** The contents of the main application dock panel */
341
  readonly dock: DockLayout.ILayoutConfig | null;
342
}
343

344
/**
345
 * Side area layout specification
346
 */
347
interface ILabShell.ISideArea {
348
  /** Whether the sidebar is collapsed */
349
  readonly collapsed: boolean;
350
  
351
  /** The current widget that has side area focus */
352
  readonly currentWidget: Widget | null;
353
  
354
  /** A flag denoting whether the side tab bar is visible */
355
  readonly visible: boolean;
356
  
357
  /** The collection of widgets held by the sidebar */
358
  readonly widgets: Array<Widget> | null;
359
  
360
  /** The collection of widgets states held by the sidebar */
361
  readonly widgetStates: {
362
    [id: string]: {
363
      /** Vertical sizes of the widgets */
364
      readonly sizes: Array<number> | null;
365
      /** Expansion states of the widgets */
366
      readonly expansionStates: Array<boolean> | null;
367
    };
368
  };
369
}
370

371
/**
372
 * Top area layout specification
373
 */
374
interface ILabShell.ITopArea {
375
  /** Top area visibility in simple mode */
376
  readonly simpleVisibility: boolean;
377
}
378

379
/**
380
 * Down area layout specification
381
 */
382
interface ILabShell.IDownArea {
383
  /** The current widget that has down area focus */
384
  readonly currentWidget: Widget | null;
385
  
386
  /** The collection of widgets held by the panel */
387
  readonly widgets: Array<Widget> | null;
388
  
389
  /** Vertical relative size of the down area. The main area will take the rest of the height */
390
  readonly size: number | null;
391
}
392
```
393

394
### Widget Positioning
395

396
System for specifying where and how widgets should be placed within the shell.
397

398
```typescript { .api }
399
/**
400
 * Widget position specification for adding widgets
401
 */
402
interface ILabShell.IWidgetPosition {
403
  /** Widget area */
404
  area?: ILabShell.Area;
405
  
406
  /** Widget opening options */
407
  options?: DocumentRegistry.IOpenOptions;
408
}
409

410
/**
411
 * Widget with deferred addition to shell
412
 */
413
interface ILabShell.IDelayedWidget extends ILabShell.IWidgetPosition {
414
  /** Widget to add */
415
  widget: Widget;
416
}
417

418
/**
419
 * User layout customization mapping
420
 */
421
interface ILabShell.IUserLayout {
422
  /** Widget customized position */
423
  [k: string]: ILabShell.IWidgetPosition;
424
}
425
```
426

427
### Event Interfaces
428

429
Type definitions for shell event arguments providing detailed change information.
430

431
```typescript { .api }
432
/**
433
 * Arguments for widget change events (alias for FocusTracker.IChangedArgs)
434
 */
435
type ILabShell.IChangedArgs = FocusTracker.IChangedArgs<Widget>;
436

437
/**
438
 * Arguments for current path change events
439
 */
440
interface ILabShell.ICurrentPathChangedArgs {
441
  /** The old value of the tree path, not including '/tree'. */
442
  readonly oldValue: string;
443
  
444
  /** The new value of the tree path, not including '/tree'. */
445
  readonly newValue: string;
446
}
447
```
448

449
### Service Interface
450

451
The ILabShell service token for dependency injection in plugins.
452

453
```typescript { .api }
454
/**
455
 * JupyterLab shell interface (implemented by LabShell)
456
 */
457
interface ILabShell extends LabShell {
458
  // All LabShell methods and properties are available
459
}
460

461
/**
462
 * Service token for JupyterLab shell
463
 */
464
const ILabShell: Token<ILabShell>;
465
```
466

467
**Usage Examples:**
468

469
```typescript
470
import { ILabShell } from "@jupyterlab/application";
471
import { JupyterFrontEndPlugin } from "@jupyterlab/application";
472

473
// Using ILabShell in a plugin
474
const plugin: JupyterFrontEndPlugin<void> = {
475
  id: 'my-shell-plugin',
476
  autoStart: true,
477
  requires: [ILabShell],
478
  activate: (app, shell: ILabShell) => {
479
    // Use shell in plugin
480
    shell.currentChanged.connect(() => {
481
      console.log('Current widget changed');
482
    });
483
    
484
    // Add a widget
485
    const widget = new Widget();
486
    widget.id = 'my-plugin-widget';
487
    shell.add(widget, 'left');
488
  }
489
};
490
```
491

492
## Types
493

494
### Layout Area Configuration
495

496
```typescript { .api }
497
/**
498
 * Area configuration type (alias for DockLayout.AreaConfig)
499
 */
500
type ILabShell.AreaConfig = DockLayout.AreaConfig;
501
```