Widget Foundation

/**
 * The base class of the lumino widget hierarchy.
 * Provides lifecycle management, DOM integration, and event handling.
 */
class Widget {
  /**
   * Construct a new widget.
   * @param options - The options for initializing the widget
   */
  constructor(options?: Widget.IOptions);

  /** The widget's DOM node (read-only) */
  readonly node: HTMLElement;

  /** Whether the widget has been disposed (read-only) */
  readonly isDisposed: boolean;

  /** Whether the widget is attached to the DOM (read-only) */
  readonly isAttached: boolean;

  /** Whether the widget is explicitly hidden (read-only) */
  readonly isHidden: boolean;

  /** Whether the widget is visible (read-only) */
  readonly isVisible: boolean;

  /** The title object for the widget (read-only) */
  readonly title: Title<Widget>;

  /** The ID of the widget's DOM node */
  id: string;

  /** The dataset for the widget's DOM node (read-only) */
  readonly dataset: DOMStringMap;

  /** The method for hiding the widget */
  hiddenMode: Widget.HiddenMode;

  /** The parent widget, or null if no parent */
  parent: Widget | null;

  /** The layout for the widget, or null if no layout */
  layout: Layout | null;

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

  /** Get an iterator over the widget's children */
  children(): IterableIterator<Widget>;

  /** Test whether the widget contains another widget */
  contains(widget: Widget): boolean;

  /** Test whether the widget has a CSS class */
  hasClass(name: string): boolean;

  /** Add a CSS class to the widget */
  addClass(name: string): void;

  /** Remove a CSS class from the widget */
  removeClass(name: string): void;

  /** Toggle a CSS class on the widget */
  toggleClass(name: string, force?: boolean): boolean;

  /** Post an update request message to the widget */
  update(): void;

  /** Post a fit request message to the widget */
  fit(): void;

  /** Post an activate request message to the widget */
  activate(): void;

  /** Send a close request message to the widget */
  close(): void;

  /** Show the widget */
  show(): void;

  /** Hide the widget */
  hide(): void;

  /** Set the hidden state of the widget */
  setHidden(hidden: boolean): void;

  /** Test whether a widget flag is set */
  testFlag(flag: Widget.Flag): boolean;

  /** Set a widget flag */
  setFlag(flag: Widget.Flag): void;

  /** Clear a widget flag */
  clearFlag(flag: Widget.Flag): void;

  /** Process a message sent to the widget */
  processMessage(msg: Message): void;

  /** A signal emitted when the widget is disposed */
  readonly disposed: ISignal<this, void>;
}

namespace Widget {
  /**
   * Options for initializing a widget.
   */
  interface IOptions {
    /** The DOM node to use for the widget (optional, creates div if not provided) */
    node?: HTMLElement;
    
    /** The HTML tag name for creating the widget's DOM node (if node not provided) */
    tag?: keyof HTMLElementTagNameMap;
  }

  /**
   * An enum of widget hidden modes.
   */
  enum HiddenMode {
    /** Hide using CSS display: none */
    Display = 0,
    
    /** Hide using CSS transform: scale(0) */
    Scale = 1,
    
    /** Hide using CSS content-visibility: hidden */
    ContentVisibility = 2
  }

  /**
   * An enum of widget state flags.
   */
  enum Flag {
    /** The widget has been disposed */
    IsDisposed = 0x1,
    
    /** The widget is attached to the DOM */
    IsAttached = 0x2,
    
    /** The widget is explicitly hidden */
    IsHidden = 0x4,
    
    /** The widget is visible (deprecated) */
    IsVisible = 0x8,
    
    /** The widget disallows layout changes */
    DisallowLayout = 0x10
  }

  /**
   * A message class for resize messages.
   */
  class ResizeMessage {
    constructor(width: number, height: number);
    readonly width: number;
    readonly height: number;
  }

  /**
   * A message class for child widget messages.
   */
  class ChildMessage {
    constructor(type: string, child: Widget);
    readonly child: Widget;
  }

  /**
   * Predefined widget messages.
   */
  namespace Msg {
    const BeforeShow: Message;
    const AfterShow: Message;
    const BeforeHide: Message;
    const AfterHide: Message;
    const BeforeAttach: Message;
    const AfterAttach: Message;
    const BeforeDetach: Message;
    const AfterDetach: Message;
    const ParentChanged: Message;
    const UpdateRequest: Message;
    const FitRequest: Message;
    const ActivateRequest: Message;
    const CloseRequest: Message;
  }
}

/**
 * Static methods for widget management.
 */
namespace Widget {
  /**
   * Attach a widget to a host DOM element.
   * @param widget - The widget to attach
   * @param host - The host DOM element
   * @param ref - Optional reference element for insertion point
   */
  function attach(widget: Widget, host: HTMLElement, ref?: HTMLElement | null): void;

  /**
   * Detach a widget from its host DOM element.
   * @param widget - The widget to detach
   */
  function detach(widget: Widget): void;
}

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

// Create a simple widget
const widget = new Widget();
widget.addClass('my-widget');
widget.node.textContent = 'Hello, World!';

// Create with custom DOM node
const customNode = document.createElement('section');
const customWidget = new Widget({ node: customNode });

// Widget lifecycle
Widget.attach(widget, document.body);
widget.show();
widget.update();
widget.fit();

// Handle disposal
widget.disposed.connect(() => {
  console.log('Widget disposed');
});
widget.dispose();

/**
 * An object which holds data related to an object's title.
 * Provides metadata for widgets displayed in containers like tabs and menus.
 */
class Title<T> {
  /**
   * Construct a new title.
   * @param options - The options for initializing the title
   */
  constructor(options: Title.IOptions<T>);

  /** The object that owns the title (read-only) */
  readonly owner: T;

  /** The label text for the title */
  label: string;

  /** The mnemonic index for the label */
  mnemonic: number;

  /** The icon renderer for the title */
  icon: VirtualElement.IRenderer | undefined;

  /** The icon class name for the title */
  iconClass: string;

  /** The icon label for the title */
  iconLabel: string;

  /** The caption for the title */
  caption: string;

  /** The extra class name for the title */
  className: string;

  /** Whether the title is closable */
  closable: boolean;

  /** The dataset for the title */
  dataset: Title.Dataset;

  /** Whether the title has been disposed (read-only) */
  readonly isDisposed: boolean;

  /** Dispose of the title */
  dispose(): void;

  /** A signal emitted when the title state changes */
  readonly changed: ISignal<this, void>;
}

namespace Title {
  /**
   * Options for initializing a title.
   */
  interface IOptions<T> {
    /** The object that owns the title */
    owner: T;
    
    /** The label for the title (default: empty string) */
    label?: string;
    
    /** The mnemonic index for the label (default: -1) */
    mnemonic?: number;
    
    /** The icon renderer for the title */
    icon?: VirtualElement.IRenderer;
    
    /** The icon class name for the title (default: empty string) */
    iconClass?: string;
    
    /** The icon label for the title (default: empty string) */
    iconLabel?: string;
    
    /** The caption for the title (default: empty string) */
    caption?: string;
    
    /** The extra class name for the title (default: empty string) */
    className?: string;
    
    /** Whether the title is closable (default: false) */
    closable?: boolean;
    
    /** The dataset for the title */
    dataset?: Dataset;
  }

  /**
   * A type alias for a data attribute dataset.
   */
  type Dataset = { readonly [key: string]: string };
}

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

// Create widget with custom title
const widget = new Widget();
widget.title.label = 'My Document';
widget.title.caption = 'Important document';
widget.title.closable = true;
widget.title.iconClass = 'fa fa-file';

// Listen for title changes
widget.title.changed.connect(() => {
  console.log('Title changed:', widget.title.label);
});

// Custom title with dataset
widget.title.dataset = {
  'document-id': '12345',
  'document-type': 'text'
};

/**
 * Abstract base class for widget layouts.
 * Manages the arrangement and sizing of child widgets within a container.
 */
abstract class Layout implements Iterable<Widget>, IDisposable {
  /**
   * Construct a new layout.
   * @param options - The options for initializing the layout
   */
  constructor(options?: Layout.IOptions);

  /** The parent widget of the layout, or null */
  parent: Widget | null;

  /** The fit policy for the layout */
  fitPolicy: Layout.FitPolicy;

  /** Whether the layout has been disposed (read-only) */
  readonly isDisposed: boolean;

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

  /** Get an iterator over the widgets in the layout */
  abstract [Symbol.iterator](): IterableIterator<Widget>;

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

  /** Process a message sent to the parent widget */
  processParentMessage(msg: Message): void;

  /** Initialize the layout (called when attached to parent) */
  protected init(): void;

  /** Attach a widget to the layout at the specified index */
  protected abstract attachWidget(index: number, widget: Widget): void;

  /** Move a widget from one index to another in the layout */
  protected abstract moveWidget(fromIndex: number, toIndex: number, widget: Widget): void;

  /** Detach a widget from the layout at the specified index */
  protected abstract detachWidget(index: number, widget: Widget): void;

  /** Handle before-show messages */
  protected onBeforeShow(msg: Message): void;

  /** Handle before-attach messages */
  protected onBeforeAttach(msg: Message): void;

  /** Handle after-attach messages */
  protected onAfterAttach(msg: Message): void;

  /** Handle before-detach messages */
  protected onBeforeDetach(msg: Message): void;

  /** Handle after-detach messages */
  protected onAfterDetach(msg: Message): void;

  /** Handle resize messages */
  protected onResize(msg: Widget.ResizeMessage): void;

  /** Handle update-request messages */
  protected onUpdateRequest(msg: Message): void;

  /** Handle fit-request messages */
  protected onFitRequest(msg: Message): void;

  /** Handle child-shown messages */
  protected onChildShown(msg: Widget.ChildMessage): void;

  /** Handle child-hidden messages */
  protected onChildHidden(msg: Widget.ChildMessage): void;
}

namespace Layout {
  /**
   * Options for initializing a layout.
   */
  interface IOptions {
    /** The fit policy for the layout (default: 'set-no-constraint') */
    fitPolicy?: FitPolicy;
  }

  /**
   * The available fit policies for a layout.
   */
  type FitPolicy = 'set-no-constraint' | 'set-min-size';

  /**
   * The available horizontal alignments for a widget.
   */
  type HorizontalAlignment = 'left' | 'center' | 'right';

  /**
   * The available vertical alignments for a widget.
   */
  type VerticalAlignment = 'top' | 'center' | 'bottom';

  /**
   * Get the horizontal alignment for a widget.
   * @param widget - The widget of interest
   * @returns The horizontal alignment for the widget
   */
  function getHorizontalAlignment(widget: Widget): HorizontalAlignment;

  /**
   * Set the horizontal alignment for a widget.
   * @param widget - The widget of interest
   * @param value - The desired horizontal alignment
   */
  function setHorizontalAlignment(widget: Widget, value: HorizontalAlignment): void;

  /**
   * Get the vertical alignment for a widget.
   * @param widget - The widget of interest
   * @returns The vertical alignment for the widget
   */
  function getVerticalAlignment(widget: Widget): VerticalAlignment;

  /**
   * Set the vertical alignment for a widget.
   * @param widget - The widget of interest
   * @param value - The desired vertical alignment
   */
  function setVerticalAlignment(widget: Widget, value: VerticalAlignment): void;
}

/**
 * A layout item that manages a widget in a layout.
 * Handles sizing constraints and positioning for widgets.
 */
class LayoutItem {
  /**
   * Construct a new layout item.
   * @param widget - The widget to manage
   */
  constructor(widget: Widget);

  /** The widget managed by this layout item (read-only) */
  readonly widget: Widget;

  /** The computed minimum width for the widget (read-only) */
  readonly minWidth: number;

  /** The computed minimum height for the widget (read-only) */
  readonly minHeight: number;

  /** The computed maximum width for the widget (read-only) */
  readonly maxWidth: number;

  /** The computed maximum height for the widget (read-only) */
  readonly maxHeight: number;

  /** Whether the layout item has been disposed (read-only) */
  readonly isDisposed: boolean;

  /** Whether the managed widget is hidden (read-only) */
  readonly isHidden: boolean;

  /** Whether the managed widget is visible (read-only) */
  readonly isVisible: boolean;

  /** Whether the managed widget is attached (read-only) */
  readonly isAttached: boolean;

  /** Dispose of the layout item */
  dispose(): void;

  /** Fit the managed widget to its content */
  fit(): void;

  /**
   * Update the position and size of the managed widget.
   * @param left - The left position in pixels
   * @param top - The top position in pixels  
   * @param width - The width in pixels
   * @param height - The height in pixels
   */
  update(left: number, top: number, width: number, height: number): void;
}

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

// Custom layout implementation
class CustomLayout extends Layout {
  private _items: LayoutItem[] = [];

  dispose(): void {
    // Dispose all layout items
    this._items.forEach(item => item.dispose());
    this._items.length = 0;
    super.dispose();
  }

  *widgets(): IterableIterator<Widget> {
    for (const item of this._items) {
      yield item.widget;
    }
  }

  protected attachWidget(index: number, widget: Widget): void {
    const item = new LayoutItem(widget);
    this._items.splice(index, 0, item);
  }

  protected moveWidget(fromIndex: number, toIndex: number, widget: Widget): void {
    const item = this._items.splice(fromIndex, 1)[0];
    this._items.splice(toIndex, 0, item);
  }

  protected detachWidget(index: number, widget: Widget): void {
    const item = this._items.splice(index, 1)[0];
    item.dispose();
  }

  protected onUpdateRequest(msg: Message): void {
    // Position widgets using layout items
    this._items.forEach((item, index) => {
      const x = index * 100;
      const y = 0;
      item.update(x, y, 100, 100);
    });
  }
}