Specialized Features

/**
 * A utility for tracking focus state within a collection of widgets.
 * Monitors focus changes and maintains current/active widget state.
 */
class FocusTracker<T> implements IDisposable {
  /**
   * Construct a new focus tracker.
   */
  constructor();

  /** The currently focused widget, or null if no widget has focus */
  readonly currentWidget: T | null;

  /** The most recently active widget, or null if no widget has been active */
  readonly activeWidget: T | null;

  /** The widgets being tracked by the focus tracker (read-only) */
  readonly widgets: ReadonlyArray<T>;

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

  /** A signal emitted when the current widget changes */
  readonly currentChanged: ISignal<this, FocusTracker.ICurrentChangedArgs<T>>;

  /** A signal emitted when the active widget changes */
  readonly activeChanged: ISignal<this, FocusTracker.IActiveChangedArgs<T>>;

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

  /**
   * Add a widget to the focus tracker.
   * @param widget - The widget to add to the tracker
   */
  add(widget: T): void;

  /**
   * Remove a widget from the focus tracker.
   * @param widget - The widget to remove from the tracker
   */
  remove(widget: T): void;

  /**
   * Test whether the focus tracker contains a specific widget.
   * @param widget - The widget to test
   * @returns Whether the widget is being tracked
   */
  has(widget: T): boolean;

  /**
   * Get the focus number for a widget.
   * @param widget - The widget of interest
   * @returns The focus number for the widget
   */
  focusNumber(widget: T): number;

  /**
   * Handle DOM events for the focus tracker.
   * @param event - The DOM event to handle
   */
  handleEvent(event: Event): void;
}

namespace FocusTracker {
  /**
   * The arguments object for the current changed signal.
   */
  interface ICurrentChangedArgs<T> {
    /** The old value for the current widget */
    oldValue: T | null;
    
    /** The new value for the current widget */
    newValue: T | null;
  }

  /**
   * The arguments object for the active changed signal.
   */
  interface IActiveChangedArgs<T> {
    /** The old value for the active widget */
    oldValue: T | null;
    
    /** The new value for the active widget */
    newValue: T | null;
  }
}

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

// Create focus tracker
const focusTracker = new FocusTracker<Widget>();

// Create widgets to track
const widget1 = new Widget();
const widget2 = new Widget();
const widget3 = new Widget();

// Add widgets to tracker
focusTracker.add(widget1);
focusTracker.add(widget2);
focusTracker.add(widget3);

// Listen for focus changes
focusTracker.currentChanged.connect((sender, args) => {
  console.log('Current widget changed:', {
    old: args.oldValue?.title.label,
    new: args.newValue?.title.label
  });
});

focusTracker.activeChanged.connect((sender, args) => {
  console.log('Active widget changed:', {
    old: args.oldValue?.title.label,
    new: args.newValue?.title.label
  });
});

// Check current state
console.log('Current widget:', focusTracker.currentWidget?.title.label);
console.log('Active widget:', focusTracker.activeWidget?.title.label);

// Clean up when done
focusTracker.dispose();

/**
 * A context menu widget for displaying contextual actions.
 * Provides right-click menus with command integration and target-specific items.
 */
class ContextMenu {
  /**
   * Construct a new context menu.
   * @param options - The options for initializing the context menu
   */
  constructor(options: ContextMenu.IOptions);

  /** The menu for the context menu (read-only) */
  readonly menu: Menu;

  /** The renderer for the context menu (read-only) */
  readonly renderer: ContextMenu.IRenderer;


  /**
   * Add an item to the context menu.
   * @param options - The options for creating the item
   * @returns The context menu item that was added
   */
  addItem(options: ContextMenu.IItemOptions): ContextMenu.IItem;

  /**
   * Remove an item from the context menu.
   * @param item - The item to remove
   */
  removeItem(item: ContextMenu.IItem): void;

  /** Remove all items from the context menu */
  clearItems(): void;

  /**
   * Open the context menu at the current mouse position.
   * @param event - The mouse or keyboard event that triggered the menu
   * @returns Whether the menu was opened successfully
   */
  open(event: MouseEvent | KeyboardEvent): boolean;
}

namespace ContextMenu {
  /**
   * Options for initializing a context menu.
   */
  interface IOptions {
    /** The command registry to use for the context menu */
    commands: CommandRegistry;
    
    /** The renderer for creating context menu elements */
    renderer?: IRenderer;
  }

  /**
   * An object which represents an item in a context menu.
   */
  interface IItem {
    /** The rank for the item (lower ranks appear first) */
    rank: number;
    
    /** The CSS selector for matching target elements */
    selector: string;
    
    /** The command identifier for the item */
    command: string;
    
    /** The arguments for the command */
    args?: any;
  }

  /**
   * Options for creating a context menu item.
   */
  interface IItemOptions {
    /** The command identifier for the item */
    command: string;
    
    /** The CSS selector for matching target elements (default: '*') */
    selector?: string;
    
    /** The rank for the item (default: Infinity) */
    rank?: number;
    
    /** The arguments for the command (optional) */
    args?: any;
  }

  /**
   * An object which renders a context menu.
   */
  interface IRenderer {
    /** The renderer for the underlying menu */
    readonly menu: Menu.IRenderer;
  }

  /**
   * Default context menu renderer implementation.
   */
  class Renderer implements IRenderer {
    /** The menu renderer for the context menu */
    readonly menu: Menu.IRenderer;
  }
}

import { ContextMenu } from "@lumino/widgets";
import { CommandRegistry } from "@lumino/commands";

// Create command registry
const commands = new CommandRegistry();

// Add commands
commands.addCommand('edit:cut', {
  label: 'Cut',
  iconClass: 'fa fa-cut',
  execute: () => console.log('Cut executed')
});

commands.addCommand('edit:copy', {
  label: 'Copy',
  iconClass: 'fa fa-copy',
  execute: () => console.log('Copy executed')
});

commands.addCommand('edit:paste', {
  label: 'Paste',
  iconClass: 'fa fa-paste',
  execute: () => console.log('Paste executed')
});

// Create context menu
const contextMenu = new ContextMenu({ commands });

// Add items for text inputs
contextMenu.addItem({
  command: 'edit:cut',
  selector: 'input[type="text"], textarea',
  rank: 1
});

contextMenu.addItem({
  command: 'edit:copy',
  selector: 'input[type="text"], textarea',
  rank: 2
});

contextMenu.addItem({
  command: 'edit:paste',
  selector: 'input[type="text"], textarea',
  rank: 3
});

// Add global items
contextMenu.addItem({
  command: 'edit:copy',
  selector: '*',
  rank: 100
});

// Listen for context menu events
document.addEventListener('contextmenu', (event) => {
  event.preventDefault();
  contextMenu.open(event);
});

/**
 * A widget that displays menu items for user selection.
 * Provides hierarchical menus with keyboard navigation, mnemonics, and submenus.
 */
class Menu extends Widget {
  /**
   * Construct a new menu.
   * @param options - The options for initializing the menu
   */
  constructor(options: Menu.IOptions);

  /** The command registry for the menu (read-only) */
  readonly commands: CommandRegistry;

  /** The renderer for the menu (read-only) */
  readonly renderer: Menu.IRenderer;

  /** The child menu for this menu (read-only) */
  readonly childMenu: Menu | null;

  /** The parent menu for this menu (read-only) */
  readonly parentMenu: Menu | null;

  /** The root menu for this menu (read-only) */
  readonly rootMenu: Menu;

  /** The leaf menu for this menu (read-only) */
  readonly leafMenu: Menu;

  /** The menu items (read-only) */
  readonly items: ReadonlyArray<Menu.IItem>;

  /** The active menu item, or null if no item is active */
  activeItem: Menu.IItem | null;

  /** The index of the active menu item, or -1 if no item is active */
  activeIndex: number;

  /** The content node for the menu (read-only) */
  readonly contentNode: HTMLUListElement;

  /** A signal emitted when the menu is about to close */
  readonly aboutToClose: ISignal<this, void>;

  /** A signal emitted when a menu is requested */
  readonly menuRequested: ISignal<this, 'next' | 'previous'>;

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

  /**
   * Add an item to the end of the menu.
   * @param options - The options for creating the item
   * @returns The menu item that was added
   */
  addItem(options: Menu.IItemOptions): Menu.IItem;

  /**
   * Insert an item at the specified index.
   * @param index - The index at which to insert the item
   * @param options - The options for creating the item
   * @returns The menu item that was inserted
   */
  insertItem(index: number, options: Menu.IItemOptions): Menu.IItem;

  /**
   * Remove an item from the menu.
   * @param item - The item to remove
   */
  removeItem(item: Menu.IItem): void;

  /**
   * Remove the item at the specified index.
   * @param index - The index of the item to remove
   */
  removeItemAt(index: number): void;

  /** Remove all items from the menu */
  clearItems(): void;

  /**
   * Open the menu at the specified location.
   * @param x - The client X coordinate for the menu
   * @param y - The client Y coordinate for the menu
   * @param options - Additional options for opening the menu
   * @returns Whether the menu was successfully opened
   */
  open(x: number, y: number, options?: Menu.IOpenOptions): boolean;

  /**
   * Show the menu as a popup at the specified location.
   * @param x - The client X coordinate for the menu
   * @param y - The client Y coordinate for the menu
   */
  popup(x: number, y: number): void;

  /** Handle DOM events for the menu */
  handleEvent(event: Event): void;

  /** Activate the next menu item */
  activateNextItem(): void;

  /** Activate the previous menu item */
  activatePreviousItem(): void;

  /** Trigger the active menu item */
  triggerActiveItem(): void;
}

namespace Menu {
  /**
   * Options for initializing a menu.
   */
  interface IOptions extends Widget.IOptions {
    /** The command registry to use for the menu */
    commands: CommandRegistry;
    
    /** The renderer for creating menu elements */
    renderer?: IRenderer;
  }

  /**
   * An object which represents an item in a menu.
   */
  interface IItem {
    /** The command identifier for the item */
    readonly command: string;
    
    /** The arguments for the command */
    readonly args: any;
    
    /** The submenu for the item, or null if no submenu */
    readonly submenu: Menu | null;
    
    /** The type of the menu item */
    readonly type: ItemType;
    
    /** The display label for the item */
    readonly label: string;
    
    /** The mnemonic index for the label */
    readonly mnemonic: number;
    
    /** The icon renderer for the item */
    readonly icon: VirtualElement.IRenderer | undefined;
    
    /** The icon class name for the item */
    readonly iconClass: string;
    
    /** The icon label for the item */
    readonly iconLabel: string;
    
    /** The caption for the item */
    readonly caption: string;
    
    /** The extra class name for the item */
    readonly className: string;
    
    /** The dataset for the item */
    readonly dataset: { readonly [key: string]: string };
    
    /** Whether the item is enabled */
    readonly isEnabled: boolean;
    
    /** Whether the item is toggled */
    readonly isToggled: boolean;
    
    /** Whether the item is visible */
    readonly isVisible: boolean;
    
    /** The key binding for the item, or null if no key binding */
    readonly keyBinding: CommandRegistry.IKeyBinding | null;
  }

  /**
   * Options for creating a menu item.
   */
  interface IItemOptions {
    /** The command identifier for the item (required for command items) */
    command?: string;
    
    /** The arguments for the command (optional) */
    args?: any;
    
    /** The submenu for the item (required for submenu items) */
    submenu?: Menu;
    
    /** The type of the menu item (default: 'command') */
    type?: ItemType;
  }

  /**
   * The available item types for menu items.
   */
  type ItemType = 'command' | 'submenu' | 'separator';

  /**
   * Options for opening a menu.
   */
  interface IOpenOptions {
    /** Whether to force the X coordinate */
    forceX?: boolean;
    
    /** Whether to force the Y coordinate */
    forceY?: boolean;
  }

  /**
   * An object which renders the visual parts of a menu.
   */
  interface IRenderer {
    /**
     * Create an item node for a menu item.
     * @param data - The render data for the item
     * @returns The item node for the menu item
     */
    createItemNode(data: IRenderData): HTMLLIElement;

    /**
     * Update an existing item node to reflect current state.
     * @param node - The item node to update
     * @param data - The render data for the item
     */
    updateItemNode(node: HTMLLIElement, data: IRenderData): void;

    /**
     * Create an icon node for a menu item.
     * @param data - The render data for the item
     * @returns The icon node for the menu item
     */
    createIconNode(data: IRenderData): HTMLSpanElement;

    /**
     * Update an existing icon node to reflect current state.
     * @param node - The icon node to update
     * @param data - The render data for the item
     */
    updateIconNode(node: HTMLSpanElement, data: IRenderData): void;

    /**
     * Create a label node for a menu item.
     * @param data - The render data for the item
     * @returns The label node for the menu item
     */
    createLabelNode(data: IRenderData): HTMLSpanElement;

    /**
     * Update an existing label node to reflect current state.
     * @param node - The label node to update
     * @param data - The render data for the item
     */
    updateLabelNode(node: HTMLSpanElement, data: IRenderData): void;

    /**
     * Create a submenu icon node for a menu item.
     * @param data - The render data for the item
     * @returns The submenu icon node for the menu item
     */
    createSubmenuIconNode(data: IRenderData): HTMLSpanElement;

    /**
     * Update an existing submenu icon node to reflect current state.
     * @param node - The submenu icon node to update
     * @param data - The render data for the item
     */
    updateSubmenuIconNode(node: HTMLSpanElement, data: IRenderData): void;

    /**
     * Create a shortcut node for a menu item.
     * @param data - The render data for the item
     * @returns The shortcut node for the menu item
     */
    createShortcutNode(data: IRenderData): HTMLSpanElement;

    /**
     * Update an existing shortcut node to reflect current state.
     * @param node - The shortcut node to update
     * @param data - The render data for the item
     */
    updateShortcutNode(node: HTMLSpanElement, data: IRenderData): void;
  }

  /**
   * The render data for a menu item.
   */
  interface IRenderData {
    /** The menu item being rendered */
    item: IItem;
    
    /** Whether the item is active */
    active: boolean;
    
    /** Whether the item is collapsed (for submenus) */
    collapsed: boolean;
  }

  /**
   * Default menu renderer implementation.
   */
  class Renderer implements IRenderer {
    createItemNode(data: IRenderData): HTMLLIElement;
    updateItemNode(node: HTMLLIElement, data: IRenderData): void;
    createIconNode(data: IRenderData): HTMLSpanElement;
    updateIconNode(node: HTMLSpanElement, data: IRenderData): void;
    createLabelNode(data: IRenderData): HTMLSpanElement;
    updateLabelNode(node: HTMLSpanElement, data: IRenderData): void;
    createSubmenuIconNode(data: IRenderData): HTMLSpanElement;
    updateSubmenuIconNode(node: HTMLSpanElement, data: IRenderData): void;
    createShortcutNode(data: IRenderData): HTMLSpanElement;
    updateShortcutNode(node: HTMLSpanElement, data: IRenderData): void;
  }
}

import { Menu } from "@lumino/widgets";
import { CommandRegistry } from "@lumino/commands";

// Create command registry and commands
const commands = new CommandRegistry();

commands.addCommand('file:new', {
  label: 'New File',
  iconClass: 'fa fa-file',
  execute: () => console.log('Creating new file')
});

commands.addCommand('file:open', {
  label: 'Open File...',
  iconClass: 'fa fa-folder-open',
  execute: () => console.log('Opening file dialog')
});

commands.addCommand('edit:undo', {
  label: 'Undo',
  iconClass: 'fa fa-undo',
  execute: () => console.log('Undoing last action')
});

// Create main menu
const fileMenu = new Menu({ commands });

// Add menu items
fileMenu.addItem({ command: 'file:new' });
fileMenu.addItem({ command: 'file:open' });
fileMenu.addItem({ type: 'separator' });

// Create submenu
const recentMenu = new Menu({ commands });
recentMenu.addItem({ command: 'file:open', args: { path: '/path/to/file1.txt' } });
recentMenu.addItem({ command: 'file:open', args: { path: '/path/to/file2.txt' } });

// Add submenu to main menu
fileMenu.addItem({
  type: 'submenu',
  submenu: recentMenu
});
recentMenu.title.label = 'Open Recent';

// Open menu at specific coordinates
fileMenu.open(100, 200);

// Or show as popup (centers on screen)
fileMenu.popup(event.clientX, event.clientY);