0
# Panel Widgets
1

2
Panel widgets combine layout managers with widget collections to provide common UI patterns. These high-level containers handle both the arrangement and management of child widgets, offering complete solutions for building complex user interfaces with tabs, splits, docking, accordions, and other organizational patterns.
3

4
## Capabilities
5

6
### Panel
7

8
The base panel class that provides a foundation for all other panel widgets.
9

10
```typescript { .api }
11
/**
12
 * A simple widget that acts as a base class for other panels.
13
 * Provides basic child widget management with a customizable layout.
14
 */
15
class Panel extends Widget {
16
  /**
17
   * Construct a new panel.
18
   * @param options - The options for initializing the panel
19
   */
20
  constructor(options?: Panel.IOptions);
21

22
  /** The child widgets in the panel (read-only) */
23
  readonly widgets: ReadonlyArray<Widget>;
24

25
  /** Add a child widget to the end of the panel */
26
  addWidget(widget: Widget): void;
27

28
  /** Insert a child widget at the specified index */
29
  insertWidget(index: number, widget: Widget): void;
30
}
31

32
namespace Panel {
33
  /**
34
   * Options for initializing a panel.
35
   */
36
  interface IOptions extends Widget.IOptions {
37
    /** A custom layout for the panel (default: PanelLayout) */
38
    layout?: PanelLayout;
39
  }
40
}
41
```
42

43
### BoxPanel
44

45
A panel that arranges child widgets in a single row or column with flexible sizing.
46

47
```typescript { .api }
48
/**
49
 * A panel that arranges widgets in a single row or column.
50
 * Combines the BoxLayout with Panel for easy linear arrangements.
51
 */
52
class BoxPanel extends Panel {
53
  /**
54
   * Construct a new box panel.
55
   * @param options - The options for initializing the box panel
56
   */
57
  constructor(options?: BoxPanel.IOptions);
58

59
  /** The layout direction for the box panel */
60
  direction: BoxPanel.Direction;
61

62
  /** The content alignment for the box panel */
63
  alignment: BoxPanel.Alignment;
64

65
  /** The inter-element spacing for the box panel */
66
  spacing: number;
67

68
  /** The child widgets in the panel (read-only) */
69
  readonly widgets: ReadonlyArray<Widget>;
70

71
  /** Add a child widget to the end of the panel */
72
  addWidget(widget: Widget): void;
73

74
  /** Insert a child widget at the specified index */
75
  insertWidget(index: number, widget: Widget): void;
76
}
77

78
namespace BoxPanel {
79
  /**
80
   * Options for initializing a box panel.
81
   */
82
  interface IOptions extends Panel.IOptions {
83
    /** The layout direction (default: 'top-to-bottom') */
84
    direction?: Direction;
85
    
86
    /** The content alignment (default: 'start') */
87
    alignment?: Alignment;
88
    
89
    /** The inter-element spacing (default: 4) */
90
    spacing?: number;
91
    
92
    /** A custom box layout for the panel */
93
    layout?: BoxLayout;
94
  }
95

96
  /** Type alias for box layout directions */
97
  type Direction = BoxLayout.Direction;
98

99
  /** Type alias for box layout alignments */
100
  type Alignment = BoxLayout.Alignment;
101
}
102

103
/**
104
 * Functions for managing box panel widget properties.
105
 */
106
namespace BoxPanel {
107
  /**
108
   * Get the size basis for a widget in a box panel.
109
   * @param widget - The widget of interest
110
   * @returns The size basis for the widget
111
   */
112
  function getSizeBasis(widget: Widget): number;
113

114
  /**
115
   * Set the size basis for a widget in a box panel.
116
   * @param widget - The widget of interest
117
   * @param value - The value for the size basis
118
   */
119
  function setSizeBasis(widget: Widget, value: number): void;
120

121
  /**
122
   * Get the stretch factor for a widget in a box panel.
123
   * @param widget - The widget of interest
124
   * @returns The stretch factor for the widget
125
   */
126
  function getStretch(widget: Widget): number;
127

128
  /**
129
   * Set the stretch factor for a widget in a box panel.
130
   * @param widget - The widget of interest
131
   * @param value - The value for the stretch factor
132
   */
133
  function setStretch(widget: Widget, value: number): void;
134
}
135
```
136

137
**Usage Examples:**
138

139
```typescript
140
import { Widget, BoxPanel } from "@lumino/widgets";
141

142
// Create horizontal toolbar
143
const toolbar = new BoxPanel({
144
  direction: 'left-to-right',
145
  spacing: 4
146
});
147

148
const button1 = new Widget();
149
const button2 = new Widget();
150
const spacer = new Widget();
151

152
toolbar.addWidget(button1);
153
toolbar.addWidget(spacer);
154
toolbar.addWidget(button2);
155

156
// Make spacer flexible to push button2 to the right
157
BoxPanel.setStretch(button1, 0);
158
BoxPanel.setStretch(spacer, 1);
159
BoxPanel.setStretch(button2, 0);
160
```
161

162
### SplitPanel
163

164
A panel that arranges widgets into resizable sections with split handles.
165

166
```typescript { .api }
167
/**
168
 * A panel that arranges widgets into resizable sections.
169
 * Provides user-resizable panes with interactive split handles.
170
 */
171
class SplitPanel extends Panel {
172
  /**
173
   * Construct a new split panel.
174
   * @param options - The options for initializing the split panel
175
   */
176
  constructor(options?: SplitPanel.IOptions);
177

178
  /** The orientation of the split panel */
179
  orientation: SplitPanel.Orientation;
180

181
  /** The content alignment for the split panel */
182
  alignment: SplitPanel.Alignment;
183

184
  /** The inter-element spacing for the split panel */
185
  spacing: number;
186

187
  /** The renderer for the split panel (read-only) */
188
  readonly renderer: SplitPanel.IRenderer;
189

190
  /** The split handles managed by the panel (read-only) */
191
  readonly handles: ReadonlyArray<HTMLDivElement>;
192

193
  /** A signal emitted when a split handle is moved */
194
  readonly handleMoved: ISignal<this, void>;
195

196
  /** Dispose of the panel and its resources */
197
  dispose(): void;
198

199
  /** Get the relative sizes of the widgets in the panel */
200
  relativeSizes(): number[];
201

202
  /**
203
   * Set the relative sizes for the widgets in the panel.
204
   * @param sizes - The relative sizes for the widgets
205
   * @param update - Whether to update the layout immediately
206
   */
207
  setRelativeSizes(sizes: number[], update?: boolean): void;
208

209
  /** Handle DOM events for the panel */
210
  handleEvent(event: Event): void;
211

212
  /** Release the mouse grab for the split handles */
213
  releaseMouse(): void;
214
}
215

216
namespace SplitPanel {
217
  /**
218
   * Options for initializing a split panel.
219
   */
220
  interface IOptions extends Panel.IOptions {
221
    /** The renderer for creating split handles */
222
    renderer?: IRenderer;
223
    
224
    /** The orientation of the split panel (default: 'horizontal') */
225
    orientation?: Orientation;
226
    
227
    /** The content alignment (default: 'start') */
228
    alignment?: Alignment;
229
    
230
    /** The inter-element spacing (default: 4) */
231
    spacing?: number;
232
    
233
    /** A custom split layout for the panel */
234
    layout?: SplitLayout;
235
  }
236

237
  /** Type alias for split layout orientations */
238
  type Orientation = SplitLayout.Orientation;
239

240
  /** Type alias for split layout alignments */
241
  type Alignment = SplitLayout.Alignment;
242

243
  /** Type alias for split layout renderer interface */
244
  type IRenderer = SplitLayout.IRenderer;
245

246
  /**
247
   * Default renderer implementation for split panels.
248
   */
249
  class Renderer implements IRenderer {
250
    /**
251
     * Create a new split handle for use by a split panel.
252
     * @returns A new split handle element
253
     */
254
    createHandle(): HTMLDivElement;
255
  }
256
}
257

258
/**
259
 * Functions for managing split panel widget properties.
260
 */
261
namespace SplitPanel {
262
  /**
263
   * Get the stretch factor for a widget in a split panel.
264
   * @param widget - The widget of interest
265
   * @returns The stretch factor for the widget
266
   */
267
  function getStretch(widget: Widget): number;
268

269
  /**
270
   * Set the stretch factor for a widget in a split panel.
271
   * @param widget - The widget of interest
272
   * @param value - The value for the stretch factor
273
   */
274
  function setStretch(widget: Widget, value: number): void;
275
}
276
```
277

278
**Usage Examples:**
279

280
```typescript
281
import { Widget, SplitPanel } from "@lumino/widgets";
282

283
// Create vertical split panel
284
const splitPanel = new SplitPanel({
285
  orientation: 'vertical',
286
  spacing: 1
287
});
288

289
const topPane = new Widget();
290
const bottomPane = new Widget();
291

292
splitPanel.addWidget(topPane);
293
splitPanel.addWidget(bottomPane);
294

295
// Set initial sizes (60% top, 40% bottom)
296
splitPanel.setRelativeSizes([0.6, 0.4]);
297

298
// Listen for handle moves
299
splitPanel.handleMoved.connect(() => {
300
  console.log('Split sizes changed:', splitPanel.relativeSizes());
301
});
302
```
303

304
### StackedPanel
305

306
A panel that shows only one child widget at a time from a stack.
307

308
```typescript { .api }
309
/**
310
 * A panel that shows only one of its child widgets at a time.
311
 * Provides navigation between multiple content areas.
312
 */
313
class StackedPanel extends Panel {
314
  /**
315
   * Construct a new stacked panel.
316
   * @param options - The options for initializing the stacked panel
317
   */
318
  constructor(options?: StackedPanel.IOptions);
319

320
  /** The index of the current widget, or -1 if no widget is current */
321
  currentIndex: number;
322

323
  /** The current widget, or null if no widget is current */
324
  currentWidget: Widget | null;
325

326
  /** The child widgets in the panel (read-only) */
327
  readonly widgets: ReadonlyArray<Widget>;
328

329
  /** The method for hiding inactive widgets */
330
  hiddenMode: Widget.HiddenMode;
331

332
  /** A signal emitted when the current widget changes */
333
  readonly currentChanged: ISignal<this, StackedPanel.ICurrentChangedArgs>;
334

335
  /** A signal emitted when a widget is removed from the panel */
336
  readonly widgetRemoved: ISignal<this, Widget>;
337

338
  /** Add a child widget to the end of the panel */
339
  addWidget(widget: Widget): void;
340

341
  /** Insert a child widget at the specified index */
342
  insertWidget(index: number, widget: Widget): void;
343
}
344

345
namespace StackedPanel {
346
  /**
347
   * Options for initializing a stacked panel.
348
   */
349
  interface IOptions extends Panel.IOptions {
350
    /** A custom stacked layout for the panel */
351
    layout?: StackedLayout;
352
  }
353

354
  /**
355
   * The arguments for the current changed signal.
356
   */
357
  interface ICurrentChangedArgs {
358
    /** The previous index, or -1 if no previous widget */
359
    previousIndex: number;
360
    
361
    /** The previous widget, or null if no previous widget */
362
    previousWidget: Widget | null;
363
    
364
    /** The current index, or -1 if no current widget */
365
    currentIndex: number;
366
    
367
    /** The current widget, or null if no current widget */
368
    currentWidget: Widget | null;
369
  }
370
}
371
```
372

373
**Usage Examples:**
374

375
```typescript
376
import { Widget, StackedPanel } from "@lumino/widgets";
377

378
// Create stacked panel for multi-page content
379
const stackedPanel = new StackedPanel();
380

381
const welcomePage = new Widget();
382
const settingsPage = new Widget();
383
const aboutPage = new Widget();
384

385
stackedPanel.addWidget(welcomePage);   // Index 0, becomes current
386
stackedPanel.addWidget(settingsPage);  // Index 1, hidden
387
stackedPanel.addWidget(aboutPage);     // Index 2, hidden
388

389
// Switch to settings page
390
stackedPanel.currentIndex = 1;
391

392
// Listen for page changes
393
stackedPanel.currentChanged.connect((sender, args) => {
394
  console.log(`Switched from page ${args.previousIndex} to ${args.currentIndex}`);
395
});
396
```
397

398
### AccordionPanel
399

400
A panel that arranges widgets as collapsible accordion sections.
401

402
```typescript { .api }
403
/**
404
 * A panel that arranges widgets as collapsible accordion sections.
405
 * Each widget gets a title bar that can be clicked to expand/collapse the section.
406
 */
407
class AccordionPanel extends Panel {
408
  /**
409
   * Construct a new accordion panel.
410
   * @param options - The options for initializing the accordion panel
411
   */
412
  constructor(options?: AccordionPanel.IOptions);
413

414
  /** The renderer for the accordion panel (read-only) */
415
  readonly renderer: AccordionPanel.IRenderer;
416

417
  /** The accordion section titles (read-only) */
418
  readonly titles: ReadonlyArray<Title<Widget>>;
419

420
  /** The orientation of the accordion panel */
421
  orientation: AccordionPanel.Orientation;
422

423
  /** The spacing between accordion sections */
424
  spacing: number;
425

426
  /** The space allocated for section titles */
427
  titleSpace: number;
428

429
  /** The child widgets in the panel (read-only) */
430
  readonly widgets: ReadonlyArray<Widget>;
431

432
  /** Add a child widget to the end of the panel */
433
  addWidget(widget: Widget): void;
434

435
  /** Insert a child widget at the specified index */
436
  insertWidget(index: number, widget: Widget): void;
437

438
  /**
439
   * Collapse an accordion section.
440
   * @param widget - The widget to collapse
441
   * @returns Whether the operation was successful
442
   */
443
  collapse(widget: Widget): boolean;
444

445
  /**
446
   * Expand an accordion section.
447
   * @param widget - The widget to expand
448
   * @returns Whether the operation was successful
449
   */
450
  expand(widget: Widget): boolean;
451

452
  /**
453
   * Test whether an accordion section is expanded.
454
   * @param widget - The widget of interest
455
   * @returns Whether the section is expanded
456
   */
457
  isExpanded(widget: Widget): boolean;
458
}
459

460
namespace AccordionPanel {
461
  /**
462
   * Options for initializing an accordion panel.
463
   */
464
  interface IOptions extends Panel.IOptions {
465
    /** The renderer for creating accordion elements */
466
    renderer?: IRenderer;
467
    
468
    /** The orientation of the accordion (default: 'vertical') */
469
    orientation?: Orientation;
470
    
471
    /** The spacing between sections (default: 4) */
472
    spacing?: number;
473
    
474
    /** The space allocated for titles (default: 22) */
475
    titleSpace?: number;
476
    
477
    /** A custom accordion layout for the panel */
478
    layout?: AccordionLayout;
479
  }
480

481
  /** Type alias for accordion orientations */
482
  type Orientation = AccordionLayout.Orientation;
483

484
  /** Type alias for accordion renderer interface */
485
  type IRenderer = AccordionLayout.IRenderer;
486

487
  /**
488
   * Default renderer implementation for accordion panels.
489
   */
490
  class Renderer implements IRenderer {
491
    /**
492
     * Create a section title element for an accordion.
493
     * @param data - The render data for the section
494
     * @returns The section title element
495
     */
496
    createSectionTitle(data: AccordionLayout.IRenderData<Widget>): HTMLElement;
497
  }
498
}
499

500
/**
501
 * Functions for managing accordion expansion state.
502
 */
503
namespace AccordionPanel {
504
  /**
505
   * Get the expanded state for a widget in an accordion panel.
506
   * @param widget - The widget of interest
507
   * @returns Whether the widget is expanded
508
   */
509
  function getExpanded(widget: Widget): boolean;
510

511
  /**
512
   * Set the expanded state for a widget in an accordion panel.
513
   * @param widget - The widget of interest
514
   * @param value - Whether the widget should be expanded
515
   */
516
  function setExpanded(widget: Widget, value: boolean): void;
517
}
518
```
519

520
**Usage Examples:**
521

522
```typescript
523
import { Widget, AccordionPanel } from "@lumino/widgets";
524

525
// Create accordion panel
526
const accordion = new AccordionPanel({
527
  orientation: 'vertical',
528
  titleSpace: 30
529
});
530

531
// Create sections with titles
532
const generalSection = new Widget();
533
generalSection.title.label = 'General Settings';
534
generalSection.title.iconClass = 'fa fa-cog';
535

536
const advancedSection = new Widget();
537
advancedSection.title.label = 'Advanced Settings';
538
advancedSection.title.iconClass = 'fa fa-wrench';
539

540
accordion.addWidget(generalSection);
541
accordion.addWidget(advancedSection);
542

543
// Control expansion
544
accordion.expand(generalSection);    // Expand first section
545
accordion.collapse(advancedSection); // Collapse second section
546

547
// Check state
548
console.log('General expanded:', accordion.isExpanded(generalSection));
549
```
550

551
### DockPanel
552

553
A sophisticated panel that provides a flexible docking interface for complex layouts.
554

555
```typescript { .api }
556
/**
557
 * A panel that arranges widgets in a flexible docking interface.
558
 * Supports tabbed interfaces, split panes, and drag-and-drop widget management.
559
 */
560
class DockPanel extends Panel {
561
  /**
562
   * Construct a new dock panel.
563
   * @param options - The options for initializing the dock panel
564
   */
565
  constructor(options?: DockPanel.IOptions);
566

567
  /** The renderer for the dock panel (read-only) */
568
  readonly renderer: DockPanel.IRenderer;
569

570
  /** The inter-element spacing for the dock panel */
571
  spacing: number;
572

573
  /** The mode for the dock panel */
574
  mode: DockPanel.Mode;
575

576
  /** Whether the tabs are movable by the user */
577
  tabsMovable: boolean;
578

579
  /** Whether the tabs are constrained to their source dock area */
580
  tabsConstrained: boolean;
581

582
  /** Whether the add button is enabled for the dock panel */
583
  addButtonEnabled: boolean;
584

585
  /** Whether the dock panel is empty (read-only) */
586
  readonly isEmpty: boolean;
587

588
  /** The widgets in the dock panel (read-only) */
589
  readonly widgets: ReadonlyArray<Widget>;
590

591
  /** The selected widgets in the dock panel (read-only) */
592
  readonly selectedWidgets: ReadonlyArray<Widget>;
593

594
  /** The tab bars in the dock panel (read-only) */
595
  readonly tabBars: ReadonlyArray<TabBar<Widget>>;
596

597
  /** The split handles in the dock panel (read-only) */
598
  readonly handles: ReadonlyArray<HTMLDivElement>;
599

600
  /** The overlay for the dock panel (read-only) */
601
  readonly overlay: DockPanel.IOverlay;
602

603
  /** A signal emitted when the layout configuration changes */
604
  readonly layoutModified: ISignal<this, void>;
605

606
  /** A signal emitted when the add button is clicked */
607
  readonly addRequested: ISignal<this, TabBar<Widget>>;
608

609
  /** Save the current layout configuration */
610
  saveLayout(): DockPanel.ILayoutConfig;
611

612
  /**
613
   * Restore a previously saved layout configuration.
614
   * @param config - The layout configuration to restore
615
   */
616
  restoreLayout(config: DockPanel.ILayoutConfig): void;
617

618
  /**
619
   * Add a widget to the dock panel.
620
   * @param widget - The widget to add
621
   * @param options - The options for adding the widget
622
   */
623
  addWidget(widget: Widget, options?: DockPanel.IAddOptions): void;
624

625
  /**
626
   * Activate a widget in the dock panel.
627
   * @param widget - The widget to activate
628
   */
629
  activateWidget(widget: Widget): void;
630

631
  /**
632
   * Select a widget in the dock panel.
633
   * @param widget - The widget to select
634
   */
635
  selectWidget(widget: Widget): void;
636

637
  /** Handle DOM events for the dock panel */
638
  handleEvent(event: Event): void;
639
}
640

641
namespace DockPanel {
642
  /**
643
   * Options for initializing a dock panel.
644
   */
645
  interface IOptions extends Panel.IOptions {
646
    /** The renderer for creating dock panel elements */
647
    renderer?: IRenderer;
648
    
649
    /** The spacing between dock elements (default: 4) */
650
    spacing?: number;
651
    
652
    /** The mode for the dock panel (default: 'multiple-document') */
653
    mode?: Mode;
654
    
655
    /** Whether tabs are movable (default: true) */
656
    tabsMovable?: boolean;
657
    
658
    /** Whether tabs are constrained (default: false) */
659
    tabsConstrained?: boolean;
660
    
661
    /** Whether add button is enabled (default: false) */
662
    addButtonEnabled?: boolean;
663
  }
664

665
  /**
666
   * The available modes for a dock panel.
667
   */
668
  enum Mode {
669
    /** Multiple document interface mode */
670
    'multiple-document',
671
    
672
    /** Single document interface mode */
673
    'single-document'
674
  }
675

676
  /** Type alias for dock layout renderer interface */
677
  type IRenderer = DockLayout.IRenderer;
678

679
  /** Type alias for dock layout add options */
680
  type IAddOptions = DockLayout.IAddOptions;
681

682
  /** Type alias for dock layout configuration */
683
  type ILayoutConfig = DockLayout.ILayoutConfig;
684

685
  /**
686
   * An object which provides overlay functionality for dock panels.
687
   */
688
  interface IOverlay {
689
    /** The DOM node for the overlay */
690
    readonly node: HTMLDivElement;
691

692
    /** Show the overlay with the specified geometry */
693
    show(geo: IOverlayGeometry): void;
694

695
    /** Hide the overlay after the specified delay */
696
    hide(delay: number): void;
697
  }
698

699
  /**
700
   * An object which describes overlay geometry.
701
   */
702
  interface IOverlayGeometry {
703
    /** The top coordinate in pixels */
704
    top: number;
705

706
    /** The left coordinate in pixels */
707
    left: number;
708

709
    /** The width in pixels */
710
    width: number;
711

712
    /** The height in pixels */
713
    height: number;
714
  }
715
}
716

717
/**
718
 * Functions for managing dock panel tab behavior.
719
 */
720
namespace DockPanel {
721
  /**
722
   * Get the tabs movable state for a widget in a dock panel.
723
   * @param widget - The widget of interest
724
   * @returns Whether the widget's tab is movable
725
   */
726
  function getTabsMovable(widget: Widget): boolean;
727

728
  /**
729
   * Set the tabs movable state for a widget in a dock panel.
730
   * @param widget - The widget of interest
731
   * @param value - Whether the widget's tab should be movable
732
   */
733
  function setTabsMovable(widget: Widget, value: boolean): void;
734
}
735
```
736

737
**Usage Examples:**
738

739
```typescript
740
import { Widget, DockPanel } from "@lumino/widgets";
741

742
// Create dock panel
743
const dockPanel = new DockPanel({
744
  mode: DockPanel.Mode['multiple-document'],
745
  spacing: 4
746
});
747

748
// Create widgets to dock
749
const editor1 = new Widget();
750
editor1.title.label = 'File 1';
751
editor1.title.closable = true;
752

753
const editor2 = new Widget();
754
editor2.title.label = 'File 2';
755
editor2.title.closable = true;
756

757
const sidebar = new Widget();
758
sidebar.title.label = 'Explorer';
759

760
// Add widgets with different docking modes
761
dockPanel.addWidget(editor1); // First widget goes to main area
762
dockPanel.addWidget(editor2, { mode: 'tab-after', ref: editor1 }); // Tab with editor1
763
dockPanel.addWidget(sidebar, { mode: 'split-left', ref: editor1 }); // Split to left
764

765
// Save and restore layout
766
const config = dockPanel.saveLayout();
767
// ... later ...
768
dockPanel.restoreLayout(config);
769

770
// Listen for layout changes
771
dockPanel.layoutModified.connect(() => {
772
  console.log('Dock layout modified');
773
});
774
```
775

776
### TabPanel
777

778
A panel that combines a tab bar with a stacked panel for tabbed interface.
779

780
```typescript { .api }
781
/**
782
 * A widget that combines a TabBar and a StackedPanel.
783
 * Provides a complete tabbed interface with tab navigation and content areas.
784
 */
785
class TabPanel extends Panel {
786
  /**
787
   * Construct a new tab panel.
788
   * @param options - The options for initializing the tab panel
789
   */
790
  constructor(options?: TabPanel.IOptions);
791

792
  /** The index of the current widget, or -1 if no widget is current */
793
  currentIndex: number;
794

795
  /** The current widget, or null if no widget is current */
796
  readonly currentWidget: Widget | null;
797

798
  /** Whether the tabs are movable by the user */
799
  tabsMovable: boolean;
800

801
  /** Whether the add button is enabled for the tab bar */
802
  addButtonEnabled: boolean;
803

804
  /** The placement of the tab bar relative to the content */
805
  tabPlacement: TabPanel.TabPlacement;
806

807
  /** The tab bar for the panel (read-only) */
808
  readonly tabBar: TabBar<Widget>;
809

810
  /** The stacked panel for the content (read-only) */
811
  readonly stackedPanel: StackedPanel;
812

813
  /** The widgets in the panel (read-only) */
814
  readonly widgets: ReadonlyArray<Widget>;
815

816
  /** A signal emitted when the current widget changes */
817
  readonly currentChanged: ISignal<this, TabPanel.ICurrentChangedArgs>;
818

819
  /** A signal emitted when the add button is clicked */
820
  readonly addRequested: ISignal<this, TabBar<Widget>>;
821

822
  /** Add a child widget to the end of the panel */
823
  addWidget(widget: Widget): void;
824

825
  /** Insert a child widget at the specified index */
826
  insertWidget(index: number, widget: Widget): void;
827
}
828

829
namespace TabPanel {
830
  /**
831
   * Options for initializing a tab panel.
832
   */
833
  interface IOptions extends Panel.IOptions {
834
    /** The document context for the tab panel */
835
    document?: Document | ShadowRoot;
836
    
837
    /** Whether tabs are movable (default: false) */
838
    tabsMovable?: boolean;
839
    
840
    /** Whether add button is enabled (default: false) */
841
    addButtonEnabled?: boolean;
842
    
843
    /** The tab placement (default: 'top') */
844
    tabPlacement?: TabPlacement;
845
    
846
    /** The renderer for creating tab elements */
847
    renderer?: TabBar.IRenderer<Widget>;
848
  }
849

850
  /**
851
   * The available tab placements for a tab panel.
852
   */
853
  type TabPlacement = 'top' | 'left' | 'right' | 'bottom';
854

855
  /**
856
   * The arguments for the current changed signal.
857
   */
858
  interface ICurrentChangedArgs {
859
    /** The previous index, or -1 if no previous widget */
860
    previousIndex: number;
861
    
862
    /** The previous widget, or null if no previous widget */
863
    previousWidget: Widget | null;
864
    
865
    /** The current index, or -1 if no current widget */
866
    currentIndex: number;
867
    
868
    /** The current widget, or null if no current widget */
869
    currentWidget: Widget | null;
870
  }
871
}
872
```
873

874
**Usage Examples:**
875

876
```typescript
877
import { Widget, TabPanel } from "@lumino/widgets";
878

879
// Create tab panel
880
const tabPanel = new TabPanel({
881
  tabPlacement: 'top',
882
  tabsMovable: true,
883
  addButtonEnabled: true
884
});
885

886
// Add tabs
887
const tab1 = new Widget();
888
tab1.title.label = 'Welcome';
889
tab1.title.iconClass = 'fa fa-home';
890

891
const tab2 = new Widget();
892
tab2.title.label = 'Settings';
893
tab2.title.closable = true;
894

895
tabPanel.addWidget(tab1);
896
tabPanel.addWidget(tab2);
897

898
// Switch tabs programmatically
899
tabPanel.currentIndex = 1;
900

901
// Listen for tab changes
902
tabPanel.currentChanged.connect((sender, args) => {
903
  console.log(`Switched to tab: ${args.currentWidget?.title.label}`);
904
});
905

906
// Handle add button clicks
907
tabPanel.addRequested.connect(() => {
908
  const newTab = new Widget();
909
  newTab.title.label = `Tab ${tabPanel.widgets.length + 1}`;
910
  tabPanel.addWidget(newTab);
911
});
912
```