0
# Layout System
1

2
The Lumino Widgets layout system provides flexible layout managers for organizing widgets with different arrangement patterns. These layout classes extend the base `Layout` class to provide specific arrangement algorithms including linear layouts, grids, splits, stacks, and single-widget containers.
3

4
## Capabilities
5

6
### BoxLayout
7

8
A layout that arranges widgets in a single row or column with flexible sizing and alignment options.
9

10
```typescript { .api }
11
/**
12
 * A layout that arranges widgets in a single row or column.
13
 * Provides flexible box-model layout with stretch factors and size constraints.
14
 */
15
class BoxLayout extends Layout {
16
  /**
17
   * Construct a new box layout.
18
   * @param options - The options for initializing the box layout
19
   */
20
  constructor(options?: BoxLayout.IOptions);
21

22
  /** The layout direction for the box layout */
23
  direction: BoxLayout.Direction;
24

25
  /** The content alignment for the box layout */
26
  alignment: BoxLayout.Alignment;
27

28
  /** The inter-element spacing for the box layout */
29
  spacing: number;
30

31
  /** Dispose of the layout and its resources */
32
  dispose(): void;
33

34
  /** Get an iterator over the widgets in the layout */
35
  widgets(): IterableIterator<Widget>;
36

37
  /** Insert a widget into the layout at the specified index */
38
  insertWidget(index: number, widget: Widget): void;
39

40
  /** Remove a widget from the layout */
41
  removeWidget(widget: Widget): void;
42
}
43

44
namespace BoxLayout {
45
  /**
46
   * Options for initializing a box layout.
47
   */
48
  interface IOptions {
49
    /** The layout direction (default: 'top-to-bottom') */
50
    direction?: Direction;
51
    
52
    /** The content alignment (default: 'start') */
53
    alignment?: Alignment;
54
    
55
    /** The inter-element spacing (default: 4) */
56
    spacing?: number;
57
  }
58

59
  /**
60
   * The available layout directions.
61
   */
62
  type Direction = 'left-to-right' | 'right-to-left' | 'top-to-bottom' | 'bottom-to-top';
63

64
  /**
65
   * The available content alignments.
66
   */
67
  type Alignment = 'start' | 'center' | 'end' | 'justify';
68
}
69

70
/**
71
 * Functions for managing box layout widget properties.
72
 */
73
namespace BoxLayout {
74
  /**
75
   * Get the size basis for a widget.
76
   * @param widget - The widget of interest
77
   * @returns The size basis for the widget
78
   */
79
  function getSizeBasis(widget: Widget): number;
80

81
  /**
82
   * Set the size basis for a widget.
83
   * @param widget - The widget of interest
84
   * @param value - The value for the size basis
85
   */
86
  function setSizeBasis(widget: Widget, value: number): void;
87

88
  /**
89
   * Get the stretch factor for a widget.
90
   * @param widget - The widget of interest
91
   * @returns The stretch factor for the widget
92
   */
93
  function getStretch(widget: Widget): number;
94

95
  /**
96
   * Set the stretch factor for a widget.
97
   * @param widget - The widget of interest
98
   * @param value - The value for the stretch factor
99
   */
100
  function setStretch(widget: Widget, value: number): void;
101
}
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
import { Widget, BoxLayout } from "@lumino/widgets";
108

109
// Create horizontal box layout
110
const layout = new BoxLayout({
111
  direction: 'left-to-right',
112
  alignment: 'center',
113
  spacing: 8
114
});
115

116
// Add widgets with different stretch factors
117
const widget1 = new Widget();
118
const widget2 = new Widget();
119
const widget3 = new Widget();
120

121
layout.insertWidget(0, widget1);
122
layout.insertWidget(1, widget2);
123
layout.insertWidget(2, widget3);
124

125
// Configure sizing
126
BoxLayout.setStretch(widget1, 0);      // Fixed size
127
BoxLayout.setStretch(widget2, 1);      // Flexible
128
BoxLayout.setStretch(widget3, 2);      // More flexible
129

130
BoxLayout.setSizeBasis(widget1, 100);  // Minimum 100px
131
```
132

133
### BoxEngine and BoxSizer
134

135
Low-level box layout calculation utilities for custom layout implementations.
136

137
```typescript { .api }
138
/**
139
 * A sizer object for use with box engine algorithms.
140
 * Manages size constraints and calculations for individual items.
141
 */
142
class BoxSizer {
143
  constructor();
144

145
  /** The minimum size for the sizer */
146
  minSize: number;
147

148
  /** The maximum size for the sizer */
149
  maxSize: number;
150

151
  /** The current size for the sizer */
152
  size: number;
153

154
  /** The size hint for the sizer */
155
  sizeHint: number;
156

157
  /** The stretch factor for the sizer */
158
  stretch: number;
159
}
160

161
/**
162
 * Namespace containing box layout calculation algorithms.
163
 */
164
namespace BoxEngine {
165
  /**
166
   * Calculate the optimal layout for a sequence of box sizers.
167
   * @param sizers - The sizers to layout
168
   * @param space - The available layout space
169
   * @returns The delta between the available space and used space
170
   */
171
  function calc(sizers: BoxSizer[], space: number): number;
172

173
  /**
174
   * Adjust the size of a sizer by a delta amount.
175
   * @param sizers - The sizers being managed
176
   * @param index - The index of the sizer to grow
177
   * @param delta - The amount to adjust the sizer
178
   */
179
  function adjust(sizers: BoxSizer[], index: number, delta: number): void;
180
}
181
```
182

183
### GridLayout
184

185
A layout that arranges widgets in a structured grid with configurable rows, columns, and spanning.
186

187
```typescript { .api }
188
/**
189
 * A layout that arranges widgets in a grid.
190
 * Provides precise control over widget placement with row/column spanning.
191
 */
192
class GridLayout extends Layout {
193
  /**
194
   * Construct a new grid layout.
195
   * @param options - The options for initializing the grid layout
196
   */
197
  constructor(options?: GridLayout.IOptions);
198

199
  /** The number of rows in the grid (read-only) */
200
  readonly rowCount: number;
201

202
  /** The number of columns in the grid (read-only) */
203
  readonly columnCount: number;
204

205
  /** The row spacing for the grid */
206
  rowSpacing: number;
207

208
  /** The column spacing for the grid */
209
  columnSpacing: number;
210

211
  /** Dispose of the layout and its resources */
212
  dispose(): void;
213

214
  /** Get an iterator over the widgets in the layout */
215
  widgets(): IterableIterator<Widget>;
216

217
  /** Add a widget to the next available cell in the grid */
218
  addWidget(widget: Widget): void;
219

220
  /** Remove a widget from the grid */
221
  removeWidget(widget: Widget): void;
222
}
223

224
namespace GridLayout {
225
  /**
226
   * Options for initializing a grid layout.
227
   */
228
  interface IOptions {
229
    /** The number of rows in the grid (default: 1) */
230
    rowCount?: number;
231
    
232
    /** The number of columns in the grid (default: 1) */
233
    columnCount?: number;
234
    
235
    /** The row spacing for the grid (default: 4) */
236
    rowSpacing?: number;
237
    
238
    /** The column spacing for the grid (default: 4) */
239
    columnSpacing?: number;
240
  }
241
}
242

243
/**
244
 * Functions for managing grid layout widget properties.
245
 */
246
namespace GridLayout {
247
  /**
248
   * Get the row index for a widget.
249
   * @param widget - The widget of interest
250
   * @returns The row index for the widget
251
   */
252
  function getRow(widget: Widget): number;
253

254
  /**
255
   * Set the row index for a widget.
256
   * @param widget - The widget of interest
257
   * @param value - The desired row index
258
   */
259
  function setRow(widget: Widget, value: number): void;
260

261
  /**
262
   * Get the column index for a widget.
263
   * @param widget - The widget of interest
264
   * @returns The column index for the widget
265
   */
266
  function getColumn(widget: Widget): number;
267

268
  /**
269
   * Set the column index for a widget.
270
   * @param widget - The widget of interest
271
   * @param value - The desired column index
272
   */
273
  function setColumn(widget: Widget, value: number): void;
274

275
  /**
276
   * Get the row span for a widget.
277
   * @param widget - The widget of interest
278
   * @returns The row span for the widget
279
   */
280
  function getRowSpan(widget: Widget): number;
281

282
  /**
283
   * Set the row span for a widget.
284
   * @param widget - The widget of interest
285
   * @param value - The desired row span
286
   */
287
  function setRowSpan(widget: Widget, value: number): void;
288

289
  /**
290
   * Get the column span for a widget.
291
   * @param widget - The widget of interest
292
   * @returns The column span for the widget
293
   */
294
  function getColumnSpan(widget: Widget): number;
295

296
  /**
297
   * Set the column span for a widget.
298
   * @param widget - The widget of interest
299
   * @param value - The desired column span
300
   */
301
  function setColumnSpan(widget: Widget, value: number): void;
302
}
303
```
304

305
**Usage Examples:**
306

307
```typescript
308
import { Widget, GridLayout } from "@lumino/widgets";
309

310
// Create 3x3 grid layout
311
const layout = new GridLayout({
312
  rowCount: 3,
313
  columnCount: 3,
314
  rowSpacing: 8,
315
  columnSpacing: 8
316
});
317

318
// Add widget with specific positioning
319
const headerWidget = new Widget();
320
layout.addWidget(headerWidget);
321
GridLayout.setRow(headerWidget, 0);
322
GridLayout.setColumn(headerWidget, 0);
323
GridLayout.setColumnSpan(headerWidget, 3); // Spans all columns
324

325
// Add sidebar widget
326
const sidebarWidget = new Widget();
327
layout.addWidget(sidebarWidget);
328
GridLayout.setRow(sidebarWidget, 1);
329
GridLayout.setColumn(sidebarWidget, 0);
330
GridLayout.setRowSpan(sidebarWidget, 2); // Spans 2 rows
331

332
// Add main content widget
333
const mainWidget = new Widget();
334
layout.addWidget(mainWidget);
335
GridLayout.setRow(mainWidget, 1);
336
GridLayout.setColumn(mainWidget, 1);
337
GridLayout.setRowSpan(mainWidget, 1);
338
GridLayout.setColumnSpan(mainWidget, 2);
339
```
340

341
### SplitLayout
342

343
A layout that arranges widgets into resizable sections separated by handles.
344

345
```typescript { .api }
346
/**
347
 * A layout that arranges widgets into resizable sections.
348
 * Provides user-resizable panes with split handles between them.
349
 */
350
class SplitLayout extends Layout {
351
  /**
352
   * Construct a new split layout.
353
   * @param options - The options for initializing the split layout
354
   */
355
  constructor(options: SplitLayout.IOptions);
356

357
  /** The renderer for the split layout (read-only) */
358
  readonly renderer: SplitLayout.IRenderer;
359

360
  /** The orientation of the split layout */
361
  orientation: SplitLayout.Orientation;
362

363
  /** The content alignment for the split layout */
364
  alignment: SplitLayout.Alignment;
365

366
  /** The inter-element spacing for the split layout */
367
  spacing: number;
368

369
  /** The split handles managed by the layout (read-only) */
370
  readonly handles: ReadonlyArray<HTMLDivElement>;
371

372
  /** Dispose of the layout and its resources */
373
  dispose(): void;
374

375
  /** Get an iterator over the widgets in the layout */
376
  widgets(): IterableIterator<Widget>;
377

378
  /** Get the absolute sizes of the widgets in the layout */
379
  absoluteSizes(): number[];
380

381
  /** Get the relative sizes of the widgets in the layout */
382
  relativeSizes(): number[];
383

384
  /**
385
   * Set the relative sizes for the widgets in the layout.
386
   * @param sizes - The relative sizes for the widgets
387
   * @param update - Whether to update the layout immediately
388
   */
389
  setRelativeSizes(sizes: number[], update?: boolean): void;
390

391
  /**
392
   * Move a split handle to the given position.
393
   * @param index - The index of the handle to move
394
   * @param position - The desired position of the handle
395
   */
396
  moveHandle(index: number, position: number): void;
397
}
398

399
namespace SplitLayout {
400
  /**
401
   * Options for initializing a split layout.
402
   */
403
  interface IOptions {
404
    /** The renderer for creating split handles */
405
    renderer: IRenderer;
406
    
407
    /** The orientation of the split layout (default: 'horizontal') */
408
    orientation?: Orientation;
409
    
410
    /** The content alignment (default: 'start') */
411
    alignment?: Alignment;
412
    
413
    /** The inter-element spacing (default: 4) */
414
    spacing?: number;
415
  }
416

417
  /**
418
   * The available orientations for a split layout.
419
   */
420
  type Orientation = 'horizontal' | 'vertical';
421

422
  /**
423
   * The available alignments for a split layout.
424
   */
425
  type Alignment = 'start' | 'center' | 'end' | 'justify';
426

427
  /**
428
   * An object which renders the visual parts of a split layout.
429
   */
430
  interface IRenderer {
431
    /**
432
     * Create a new split handle for use by a split layout.
433
     * @returns A new split handle element
434
     */
435
    createHandle(): HTMLDivElement;
436
  }
437
}
438

439
/**
440
 * Functions for managing split layout widget properties.
441
 */
442
namespace SplitLayout {
443
  /**
444
   * Get the stretch factor for a widget.
445
   * @param widget - The widget of interest
446
   * @returns The stretch factor for the widget
447
   */
448
  function getStretch(widget: Widget): number;
449

450
  /**
451
   * Set the stretch factor for a widget.
452
   * @param widget - The widget of interest
453
   * @param value - The value for the stretch factor
454
   */
455
  function setStretch(widget: Widget, value: number): void;
456
}
457
```
458

459
**Usage Examples:**
460

461
```typescript
462
import { Widget, SplitLayout } from "@lumino/widgets";
463

464
// Custom renderer for split handles
465
const renderer: SplitLayout.IRenderer = {
466
  createHandle(): HTMLDivElement {
467
    const handle = document.createElement('div');
468
    handle.className = 'split-handle';
469
    return handle;
470
  }
471
};
472

473
// Create vertical split layout
474
const layout = new SplitLayout({
475
  renderer,
476
  orientation: 'vertical',
477
  spacing: 4
478
});
479

480
// Add widgets with different stretch factors
481
const topWidget = new Widget();
482
const bottomWidget = new Widget();
483

484
layout.insertWidget(0, topWidget);
485
layout.insertWidget(1, bottomWidget);
486

487
SplitLayout.setStretch(topWidget, 1);
488
SplitLayout.setStretch(bottomWidget, 2);
489

490
// Set initial proportions (30% top, 70% bottom)
491
layout.setRelativeSizes([0.3, 0.7]);
492
```
493

494
### StackedLayout
495

496
A layout that shows only one widget at a time from a stack of widgets.
497

498
```typescript { .api }
499
/**
500
 * A layout that shows only one widget at a time.
501
 * Manages a stack of widgets where only the current widget is visible.
502
 */
503
class StackedLayout extends Layout {
504
  /**
505
   * Construct a new stacked layout.
506
   */
507
  constructor();
508

509
  /** The method for hiding inactive widgets */
510
  hiddenMode: Widget.HiddenMode;
511

512
  /** Dispose of the layout and its resources */
513
  dispose(): void;
514

515
  /** Get an iterator over the widgets in the layout */
516
  widgets(): IterableIterator<Widget>;
517

518
  /** Add a widget to the end of the layout */
519
  addWidget(widget: Widget): void;
520

521
  /** Insert a widget at the specified index */
522
  insertWidget(index: number, widget: Widget): void;
523

524
  /** Remove a widget from the layout */
525
  removeWidget(widget: Widget): void;
526
}
527
```
528

529
**Usage Examples:**
530

531
```typescript
532
import { Widget, StackedLayout } from "@lumino/widgets";
533

534
// Create stacked layout
535
const layout = new StackedLayout();
536
layout.hiddenMode = Widget.HiddenMode.Display;
537

538
// Add multiple widgets (only one visible at a time)
539
const page1 = new Widget();
540
const page2 = new Widget();
541
const page3 = new Widget();
542

543
layout.addWidget(page1);  // Visible by default
544
layout.addWidget(page2);  // Hidden
545
layout.addWidget(page3);  // Hidden
546

547
// Switch visible widget by showing/hiding
548
page1.hide();
549
page2.show(); // Now page2 is visible
550
```
551

552
### SingletonLayout
553

554
A layout that contains at most one child widget, sized to fill the entire layout area.
555

556
```typescript { .api }
557
/**
558
 * A layout that contains at most one child widget.
559
 * The child widget is resized to fill the entire layout area.
560
 */
561
class SingletonLayout extends Layout {
562
  /**
563
   * Construct a new singleton layout.
564
   */
565
  constructor();
566

567
  /** The child widget, or null if the layout is empty */
568
  widget: Widget | null;
569

570
  /** Dispose of the layout and its resources */
571
  dispose(): void;
572

573
  /** Get an iterator over the widgets in the layout */
574
  widgets(): IterableIterator<Widget>;
575
}
576
```
577

578
**Usage Examples:**
579

580
```typescript
581
import { Widget, SingletonLayout, Panel } from "@lumino/widgets";
582

583
// Create panel with singleton layout
584
const panel = new Panel();
585
panel.layout = new SingletonLayout();
586

587
// Add a widget (replaces any existing widget)
588
const contentWidget = new Widget();
589
contentWidget.node.textContent = 'Full-size content';
590
panel.addWidget(contentWidget);
591

592
// The widget automatically fills the entire panel area
593
console.log(panel.layout.widget === contentWidget); // true
594
```
595

596
### PanelLayout
597

598
A simple layout that arranges widgets in a basic panel structure.
599

600
```typescript { .api }
601
/**
602
 * A layout that arranges widgets in a simple panel.
603
 * Widgets are positioned absolutely and must be manually positioned.
604
 */
605
class PanelLayout extends Layout {
606
  /**
607
   * Construct a new panel layout.
608
   */
609
  constructor();
610

611
  /** Dispose of the layout and its resources */
612
  dispose(): void;
613

614
  /** Get an iterator over the widgets in the layout */
615
  widgets(): IterableIterator<Widget>;
616

617
  /** Add a widget to the end of the layout */
618
  addWidget(widget: Widget): void;
619

620
  /** Insert a widget at the specified index */
621
  insertWidget(index: number, widget: Widget): void;
622

623
  /** Remove a widget from the layout */
624
  removeWidget(widget: Widget): void;
625

626
  /** Remove the widget at the specified index */
627
  removeWidgetAt(index: number): void;
628
}
629
```
630

631
**Usage Examples:**
632

633
```typescript
634
import { Widget, PanelLayout } from "@lumino/widgets";
635

636
// Create custom panel with manual positioning
637
const layout = new PanelLayout();
638

639
// Add widgets that need custom positioning
640
const widget1 = new Widget();
641
const widget2 = new Widget();
642

643
layout.addWidget(widget1);
644
layout.addWidget(widget2);
645

646
// Position widgets manually using CSS
647
widget1.node.style.position = 'absolute';
648
widget1.node.style.top = '10px';
649
widget1.node.style.left = '10px';
650
widget1.node.style.width = '200px';
651
widget1.node.style.height = '100px';
652

653
widget2.node.style.position = 'absolute';
654
widget2.node.style.top = '50px';
655
widget2.node.style.left = '50px';
656
widget2.node.style.width = '300px';
657
widget2.node.style.height = '150px';
658
```
659

660
### AccordionLayout
661

662
A layout that arranges widgets in a collapsible accordion structure with title bars.
663

664
```typescript { .api }
665
/**
666
 * A layout that arranges widgets in a collapsible accordion structure.
667
 * Each widget gets a title bar that can be clicked to expand/collapse the section.
668
 */
669
class AccordionLayout extends SplitLayout {
670
  /**
671
   * Construct a new accordion layout.
672
   * @param options - The options for initializing the accordion layout
673
   */
674
  constructor(options?: AccordionLayout.IOptions);
675

676
  /** The renderer for the accordion layout (read-only) */
677
  readonly renderer: AccordionLayout.IRenderer;
678

679
  /** The accordion section titles (read-only) */
680
  readonly titles: ReadonlyArray<HTMLElement>;
681

682
  /** The space allocated for section titles */
683
  titleSpace: number;
684

685
  /** A signal emitted when expansion is toggled */
686
  readonly expansionToggled: ISignal<this, number>;
687

688
  /**
689
   * Collapse an accordion section.
690
   * @param index - The index of the section to collapse
691
   */
692
  collapse(index: number): void;
693

694
  /**
695
   * Expand an accordion section.
696
   * @param index - The index of the section to expand
697
   */
698
  expand(index: number): void;
699

700
  /**
701
   * Test whether an accordion section is expanded.
702
   * @param index - The index of the section
703
   * @returns Whether the section is expanded
704
   */
705
  isExpanded(index: number): boolean;
706
}
707

708
namespace AccordionLayout {
709
  /**
710
   * Options for initializing an accordion layout.
711
   */
712
  interface IOptions extends SplitLayout.IOptions {
713
    /** The renderer for creating accordion elements */
714
    renderer?: IRenderer;
715
    
716
    /** The space allocated for titles (default: 22) */
717
    titleSpace?: number;
718
    
719
    /** The orientation of the accordion (default: 'vertical') */
720
    orientation?: Orientation;
721
  }
722

723
  /** Type alias for accordion orientations */
724
  type Orientation = SplitLayout.Orientation;
725

726
  /**
727
   * An object which renders the visual parts of an accordion layout.
728
   */
729
  interface IRenderer {
730
    /**
731
     * Create a section title element for an accordion section.
732
     * @param data - The render data for the section
733
     * @returns The section title element
734
     */
735
    createSectionTitle(data: IRenderData<Widget>): HTMLElement;
736
  }
737

738
  /**
739
   * The render data for an accordion section.
740
   */
741
  interface IRenderData<T> {
742
    /** The title for the section */
743
    title: Title<T>;
744
    
745
    /** Whether the section is current */
746
    current: boolean;
747
    
748
    /** The z-index for the section */
749
    zIndex: number;
750
  }
751

752
  /**
753
   * Default accordion layout renderer implementation.
754
   */
755
  class Renderer implements IRenderer {
756
    createSectionTitle(data: IRenderData<Widget>): HTMLElement;
757
  }
758
}
759
```
760

761
### DockLayout
762

763
A layout that provides a flexible docking interface for complex window management.
764

765
```typescript { .api }
766
/**
767
 * A layout that provides a flexible docking interface.
768
 * Supports tabbed interfaces, split panes, and drag-and-drop widget management.
769
 */
770
class DockLayout extends Layout {
771
  /**
772
   * Construct a new dock layout.
773
   * @param options - The options for initializing the dock layout
774
   */
775
  constructor(options: DockLayout.IOptions);
776

777
  /** The renderer for the dock layout (read-only) */
778
  readonly renderer: DockLayout.IRenderer;
779

780
  /** The inter-element spacing for the dock layout */
781
  spacing: number;
782

783
  /** Whether the dock layout is empty (read-only) */
784
  readonly isEmpty: boolean;
785

786
  /** Get an iterator over the widgets in the dock layout */
787
  *widgets(): IterableIterator<Widget>;
788

789
  /** Get an iterator over the selected widgets in the dock layout */
790
  *selectedWidgets(): IterableIterator<Widget>;
791

792
  /** Get an iterator over the tab bars in the dock layout */
793
  *tabBars(): IterableIterator<TabBar<Widget>>;
794

795
  /** Get an iterator over the split handles in the dock layout */
796
  *handles(): IterableIterator<HTMLDivElement>;
797

798
  /**
799
   * Add a widget to the dock layout.
800
   * @param widget - The widget to add
801
   * @param options - The options for adding the widget
802
   */
803
  addWidget(widget: Widget, options?: DockLayout.IAddOptions): void;
804

805
  /**
806
   * Remove a widget from the dock layout.
807
   * @param widget - The widget to remove
808
   */
809
  removeWidget(widget: Widget): void;
810

811
  /**
812
   * Find the tab bar which contains the given widget.
813
   * @param widget - The widget of interest
814
   * @returns The tab bar containing the widget, or null
815
   */
816
  tabBarForWidget(widget: Widget): TabBar<Widget> | null;
817

818
  /**
819
   * Save the current layout configuration.
820
   * @returns The current layout configuration
821
   */
822
  saveLayout(): DockLayout.ILayoutConfig;
823

824
  /**
825
   * Restore a previously saved layout configuration.
826
   * @param config - The layout configuration to restore
827
   */
828
  restoreLayout(config: DockLayout.ILayoutConfig): void;
829
}
830

831
namespace DockLayout {
832
  /**
833
   * Options for initializing a dock layout.
834
   */
835
  interface IOptions {
836
    /** The renderer for creating dock layout elements */
837
    renderer: IRenderer;
838
    
839
    /** The spacing between dock elements (default: 4) */
840
    spacing?: number;
841
  }
842

843
  /**
844
   * The available insertion modes for adding widgets.
845
   */
846
  type InsertMode = 
847
    | 'tab-after' 
848
    | 'tab-before' 
849
    | 'split-top' 
850
    | 'split-left' 
851
    | 'split-right' 
852
    | 'split-bottom';
853

854
  /**
855
   * Options for adding a widget to the dock layout.
856
   */
857
  interface IAddOptions {
858
    /** The insertion mode for the widget */
859
    mode: InsertMode;
860
    
861
    /** The reference widget for the insertion */
862
    ref?: Widget;
863
  }
864

865
  /**
866
   * An object which represents a saved layout configuration.
867
   */
868
  interface ILayoutConfig {
869
    /** The main layout area configuration */
870
    main: AreaConfig | null;
871
  }
872

873
  /**
874
   * An object which represents a layout area configuration.
875
   */
876
  interface AreaConfig {
877
    /** The type of the area ('tab-area' | 'split-area') */
878
    type: string;
879
    
880
    /** The orientation for split areas */
881
    orientation?: 'horizontal' | 'vertical';
882
    
883
    /** The sizes of child areas */
884
    sizes?: number[];
885
    
886
    /** The child areas */
887
    children?: AreaConfig[];
888
    
889
    /** The widgets in tab areas */
890
    widgets?: Widget[];
891
    
892
    /** The current index for tab areas */
893
    currentIndex?: number;
894
  }
895

896
  /**
897
   * An object which renders the visual parts of a dock layout.
898
   */
899
  interface IRenderer {
900
    /**
901
     * Create a new tab bar for use by a dock layout.
902
     * @param document - The document context for the tab bar
903
     * @returns A new tab bar widget
904
     */
905
    createTabBar(document?: Document | ShadowRoot): TabBar<Widget>;
906

907
    /**
908
     * Create a new split handle for use by a dock layout.
909
     * @returns A new split handle element
910
     */
911
    createHandle(): HTMLDivElement;
912
  }
913
}
914
```