Layout System

/**
 * A layout that arranges widgets in a single row or column.
 * Provides flexible box-model layout with stretch factors and size constraints.
 */
class BoxLayout extends Layout {
  /**
   * Construct a new box layout.
   * @param options - The options for initializing the box layout
   */
  constructor(options?: BoxLayout.IOptions);

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

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

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

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

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

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

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

namespace BoxLayout {
  /**
   * Options for initializing a box layout.
   */
  interface IOptions {
    /** The layout direction (default: 'top-to-bottom') */
    direction?: Direction;
    
    /** The content alignment (default: 'start') */
    alignment?: Alignment;
    
    /** The inter-element spacing (default: 4) */
    spacing?: number;
  }

  /**
   * The available layout directions.
   */
  type Direction = 'left-to-right' | 'right-to-left' | 'top-to-bottom' | 'bottom-to-top';

  /**
   * The available content alignments.
   */
  type Alignment = 'start' | 'center' | 'end' | 'justify';
}

/**
 * Functions for managing box layout widget properties.
 */
namespace BoxLayout {
  /**
   * Get the size basis for a widget.
   * @param widget - The widget of interest
   * @returns The size basis for the widget
   */
  function getSizeBasis(widget: Widget): number;

  /**
   * Set the size basis for a widget.
   * @param widget - The widget of interest
   * @param value - The value for the size basis
   */
  function setSizeBasis(widget: Widget, value: number): void;

  /**
   * Get the stretch factor for a widget.
   * @param widget - The widget of interest
   * @returns The stretch factor for the widget
   */
  function getStretch(widget: Widget): number;

  /**
   * Set the stretch factor for a widget.
   * @param widget - The widget of interest
   * @param value - The value for the stretch factor
   */
  function setStretch(widget: Widget, value: number): void;
}

import { Widget, BoxLayout } from "@lumino/widgets";

// Create horizontal box layout
const layout = new BoxLayout({
  direction: 'left-to-right',
  alignment: 'center',
  spacing: 8
});

// Add widgets with different stretch factors
const widget1 = new Widget();
const widget2 = new Widget();
const widget3 = new Widget();

layout.insertWidget(0, widget1);
layout.insertWidget(1, widget2);
layout.insertWidget(2, widget3);

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

BoxLayout.setSizeBasis(widget1, 100);  // Minimum 100px

/**
 * A sizer object for use with box engine algorithms.
 * Manages size constraints and calculations for individual items.
 */
class BoxSizer {
  constructor();

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

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

  /** The current size for the sizer */
  size: number;

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

  /** The stretch factor for the sizer */
  stretch: number;
}

/**
 * Namespace containing box layout calculation algorithms.
 */
namespace BoxEngine {
  /**
   * Calculate the optimal layout for a sequence of box sizers.
   * @param sizers - The sizers to layout
   * @param space - The available layout space
   * @returns The delta between the available space and used space
   */
  function calc(sizers: BoxSizer[], space: number): number;

  /**
   * Adjust the size of a sizer by a delta amount.
   * @param sizers - The sizers being managed
   * @param index - The index of the sizer to grow
   * @param delta - The amount to adjust the sizer
   */
  function adjust(sizers: BoxSizer[], index: number, delta: number): void;
}

/**
 * A layout that arranges widgets in a grid.
 * Provides precise control over widget placement with row/column spanning.
 */
class GridLayout extends Layout {
  /**
   * Construct a new grid layout.
   * @param options - The options for initializing the grid layout
   */
  constructor(options?: GridLayout.IOptions);

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

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

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

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

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

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

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

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

namespace GridLayout {
  /**
   * Options for initializing a grid layout.
   */
  interface IOptions {
    /** The number of rows in the grid (default: 1) */
    rowCount?: number;
    
    /** The number of columns in the grid (default: 1) */
    columnCount?: number;
    
    /** The row spacing for the grid (default: 4) */
    rowSpacing?: number;
    
    /** The column spacing for the grid (default: 4) */
    columnSpacing?: number;
  }
}

/**
 * Functions for managing grid layout widget properties.
 */
namespace GridLayout {
  /**
   * Get the row index for a widget.
   * @param widget - The widget of interest
   * @returns The row index for the widget
   */
  function getRow(widget: Widget): number;

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

  /**
   * Get the column index for a widget.
   * @param widget - The widget of interest
   * @returns The column index for the widget
   */
  function getColumn(widget: Widget): number;

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

  /**
   * Get the row span for a widget.
   * @param widget - The widget of interest
   * @returns The row span for the widget
   */
  function getRowSpan(widget: Widget): number;

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

  /**
   * Get the column span for a widget.
   * @param widget - The widget of interest
   * @returns The column span for the widget
   */
  function getColumnSpan(widget: Widget): number;

  /**
   * Set the column span for a widget.
   * @param widget - The widget of interest
   * @param value - The desired column span
   */
  function setColumnSpan(widget: Widget, value: number): void;
}

import { Widget, GridLayout } from "@lumino/widgets";

// Create 3x3 grid layout
const layout = new GridLayout({
  rowCount: 3,
  columnCount: 3,
  rowSpacing: 8,
  columnSpacing: 8
});

// Add widget with specific positioning
const headerWidget = new Widget();
layout.addWidget(headerWidget);
GridLayout.setRow(headerWidget, 0);
GridLayout.setColumn(headerWidget, 0);
GridLayout.setColumnSpan(headerWidget, 3); // Spans all columns

// Add sidebar widget
const sidebarWidget = new Widget();
layout.addWidget(sidebarWidget);
GridLayout.setRow(sidebarWidget, 1);
GridLayout.setColumn(sidebarWidget, 0);
GridLayout.setRowSpan(sidebarWidget, 2); // Spans 2 rows

// Add main content widget
const mainWidget = new Widget();
layout.addWidget(mainWidget);
GridLayout.setRow(mainWidget, 1);
GridLayout.setColumn(mainWidget, 1);
GridLayout.setRowSpan(mainWidget, 1);
GridLayout.setColumnSpan(mainWidget, 2);

/**
 * A layout that arranges widgets into resizable sections.
 * Provides user-resizable panes with split handles between them.
 */
class SplitLayout extends Layout {
  /**
   * Construct a new split layout.
   * @param options - The options for initializing the split layout
   */
  constructor(options: SplitLayout.IOptions);

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

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

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

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

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

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

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

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

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

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

  /**
   * Move a split handle to the given position.
   * @param index - The index of the handle to move
   * @param position - The desired position of the handle
   */
  moveHandle(index: number, position: number): void;
}

namespace SplitLayout {
  /**
   * Options for initializing a split layout.
   */
  interface IOptions {
    /** The renderer for creating split handles */
    renderer: IRenderer;
    
    /** The orientation of the split layout (default: 'horizontal') */
    orientation?: Orientation;
    
    /** The content alignment (default: 'start') */
    alignment?: Alignment;
    
    /** The inter-element spacing (default: 4) */
    spacing?: number;
  }

  /**
   * The available orientations for a split layout.
   */
  type Orientation = 'horizontal' | 'vertical';

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

  /**
   * An object which renders the visual parts of a split layout.
   */
  interface IRenderer {
    /**
     * Create a new split handle for use by a split layout.
     * @returns A new split handle element
     */
    createHandle(): HTMLDivElement;
  }
}

/**
 * Functions for managing split layout widget properties.
 */
namespace SplitLayout {
  /**
   * Get the stretch factor for a widget.
   * @param widget - The widget of interest
   * @returns The stretch factor for the widget
   */
  function getStretch(widget: Widget): number;

  /**
   * Set the stretch factor for a widget.
   * @param widget - The widget of interest
   * @param value - The value for the stretch factor
   */
  function setStretch(widget: Widget, value: number): void;
}

import { Widget, SplitLayout } from "@lumino/widgets";

// Custom renderer for split handles
const renderer: SplitLayout.IRenderer = {
  createHandle(): HTMLDivElement {
    const handle = document.createElement('div');
    handle.className = 'split-handle';
    return handle;
  }
};

// Create vertical split layout
const layout = new SplitLayout({
  renderer,
  orientation: 'vertical',
  spacing: 4
});

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

layout.insertWidget(0, topWidget);
layout.insertWidget(1, bottomWidget);

SplitLayout.setStretch(topWidget, 1);
SplitLayout.setStretch(bottomWidget, 2);

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

/**
 * A layout that shows only one widget at a time.
 * Manages a stack of widgets where only the current widget is visible.
 */
class StackedLayout extends Layout {
  /**
   * Construct a new stacked layout.
   */
  constructor();

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

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

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

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

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

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

import { Widget, StackedLayout } from "@lumino/widgets";

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

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

layout.addWidget(page1);  // Visible by default
layout.addWidget(page2);  // Hidden
layout.addWidget(page3);  // Hidden

// Switch visible widget by showing/hiding
page1.hide();
page2.show(); // Now page2 is visible

/**
 * A layout that contains at most one child widget.
 * The child widget is resized to fill the entire layout area.
 */
class SingletonLayout extends Layout {
  /**
   * Construct a new singleton layout.
   */
  constructor();

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

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

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

import { Widget, SingletonLayout, Panel } from "@lumino/widgets";

// Create panel with singleton layout
const panel = new Panel();
panel.layout = new SingletonLayout();

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

// The widget automatically fills the entire panel area
console.log(panel.layout.widget === contentWidget); // true

/**
 * A layout that arranges widgets in a simple panel.
 * Widgets are positioned absolutely and must be manually positioned.
 */
class PanelLayout extends Layout {
  /**
   * Construct a new panel layout.
   */
  constructor();

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

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

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

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

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

  /** Remove the widget at the specified index */
  removeWidgetAt(index: number): void;
}

import { Widget, PanelLayout } from "@lumino/widgets";

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

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

layout.addWidget(widget1);
layout.addWidget(widget2);

// Position widgets manually using CSS
widget1.node.style.position = 'absolute';
widget1.node.style.top = '10px';
widget1.node.style.left = '10px';
widget1.node.style.width = '200px';
widget1.node.style.height = '100px';

widget2.node.style.position = 'absolute';
widget2.node.style.top = '50px';
widget2.node.style.left = '50px';
widget2.node.style.width = '300px';
widget2.node.style.height = '150px';

/**
 * A layout that arranges widgets in a collapsible accordion structure.
 * Each widget gets a title bar that can be clicked to expand/collapse the section.
 */
class AccordionLayout extends SplitLayout {
  /**
   * Construct a new accordion layout.
   * @param options - The options for initializing the accordion layout
   */
  constructor(options?: AccordionLayout.IOptions);

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

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

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

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

  /**
   * Collapse an accordion section.
   * @param index - The index of the section to collapse
   */
  collapse(index: number): void;

  /**
   * Expand an accordion section.
   * @param index - The index of the section to expand
   */
  expand(index: number): void;

  /**
   * Test whether an accordion section is expanded.
   * @param index - The index of the section
   * @returns Whether the section is expanded
   */
  isExpanded(index: number): boolean;
}

namespace AccordionLayout {
  /**
   * Options for initializing an accordion layout.
   */
  interface IOptions extends SplitLayout.IOptions {
    /** The renderer for creating accordion elements */
    renderer?: IRenderer;
    
    /** The space allocated for titles (default: 22) */
    titleSpace?: number;
    
    /** The orientation of the accordion (default: 'vertical') */
    orientation?: Orientation;
  }

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

  /**
   * An object which renders the visual parts of an accordion layout.
   */
  interface IRenderer {
    /**
     * Create a section title element for an accordion section.
     * @param data - The render data for the section
     * @returns The section title element
     */
    createSectionTitle(data: IRenderData<Widget>): HTMLElement;
  }

  /**
   * The render data for an accordion section.
   */
  interface IRenderData<T> {
    /** The title for the section */
    title: Title<T>;
    
    /** Whether the section is current */
    current: boolean;
    
    /** The z-index for the section */
    zIndex: number;
  }

  /**
   * Default accordion layout renderer implementation.
   */
  class Renderer implements IRenderer {
    createSectionTitle(data: IRenderData<Widget>): HTMLElement;
  }
}

/**
 * A layout that provides a flexible docking interface.
 * Supports tabbed interfaces, split panes, and drag-and-drop widget management.
 */
class DockLayout extends Layout {
  /**
   * Construct a new dock layout.
   * @param options - The options for initializing the dock layout
   */
  constructor(options: DockLayout.IOptions);

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

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

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

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

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

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

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

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

  /**
   * Remove a widget from the dock layout.
   * @param widget - The widget to remove
   */
  removeWidget(widget: Widget): void;

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

  /**
   * Save the current layout configuration.
   * @returns The current layout configuration
   */
  saveLayout(): DockLayout.ILayoutConfig;

  /**
   * Restore a previously saved layout configuration.
   * @param config - The layout configuration to restore
   */
  restoreLayout(config: DockLayout.ILayoutConfig): void;
}

namespace DockLayout {
  /**
   * Options for initializing a dock layout.
   */
  interface IOptions {
    /** The renderer for creating dock layout elements */
    renderer: IRenderer;
    
    /** The spacing between dock elements (default: 4) */
    spacing?: number;
  }

  /**
   * The available insertion modes for adding widgets.
   */
  type InsertMode = 
    | 'tab-after' 
    | 'tab-before' 
    | 'split-top' 
    | 'split-left' 
    | 'split-right' 
    | 'split-bottom';

  /**
   * Options for adding a widget to the dock layout.
   */
  interface IAddOptions {
    /** The insertion mode for the widget */
    mode: InsertMode;
    
    /** The reference widget for the insertion */
    ref?: Widget;
  }

  /**
   * An object which represents a saved layout configuration.
   */
  interface ILayoutConfig {
    /** The main layout area configuration */
    main: AreaConfig | null;
  }

  /**
   * An object which represents a layout area configuration.
   */
  interface AreaConfig {
    /** The type of the area ('tab-area' | 'split-area') */
    type: string;
    
    /** The orientation for split areas */
    orientation?: 'horizontal' | 'vertical';
    
    /** The sizes of child areas */
    sizes?: number[];
    
    /** The child areas */
    children?: AreaConfig[];
    
    /** The widgets in tab areas */
    widgets?: Widget[];
    
    /** The current index for tab areas */
    currentIndex?: number;
  }

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

    /**
     * Create a new split handle for use by a dock layout.
     * @returns A new split handle element
     */
    createHandle(): HTMLDivElement;
  }
}