or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

command-management.mdcommand-metadata.mdindex.mdkey-binding-system.md
tile.json

tessl/npm-lumino--commands

Comprehensive command registry system for managing collections of commands in desktop-like web applications

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@lumino/commands@2.3.x

To install, run

npx @tessl/cli install tessl/npm-lumino--commands@2.3.0

index.mddocs/

Lumino Commands

Lumino Commands provides a comprehensive command registry system for managing collections of commands in desktop-like web applications. It enables developers to create and organize action-based widgets such as command palettes, menus, and toolbars through a centralized CommandRegistry class.

Package Information

  • Package Name: @lumino/commands
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @lumino/commands

Core Imports

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

For CommonJS:

const { CommandRegistry } = require("@lumino/commands");

Basic Usage

import { CommandRegistry } from "@lumino/commands";
import { IDisposable } from "@lumino/disposable";

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

// Add a command
const disposable: IDisposable = registry.addCommand("save-file", {
  execute: (args) => {
    console.log("Saving file:", args.filename || "untitled");
    return Promise.resolve();
  },
  label: "Save File",
  caption: "Save the current file",
  isEnabled: () => true,
  isVisible: () => true
});

// Add a key binding
registry.addKeyBinding({
  keys: ["Ctrl S"],
  selector: "body",
  command: "save-file"
});

// Execute the command
await registry.execute("save-file", { filename: "document.txt" });

// Clean up
disposable.dispose();

Architecture

Lumino Commands is built around several key components:

  • CommandRegistry: The central registry that manages commands and key bindings
  • Command System: Commands are abstract representations of actions with metadata and execution logic
  • Key Binding System: Maps keyboard shortcuts to commands with CSS selector-based context matching
  • Signal System: Event-driven architecture using @lumino/signaling for command state changes
  • Metadata System: Rich command metadata for UI representation (labels, icons, tooltips, etc.)

Capabilities

Command Management

Core functionality for registering, managing and executing commands. Commands are the fundamental unit of functionality in the registry.

class CommandRegistry {
  constructor();
  
  listCommands(): string[];
  hasCommand(id: string): boolean;
  addCommand(id: string, options: CommandRegistry.ICommandOptions): IDisposable;
  notifyCommandChanged(id?: string): void;
  execute(id: string, args?: ReadonlyPartialJSONObject): Promise<any>;
}

interface ICommandOptions {
  execute: CommandFunc<any | Promise<any>>;
  describedBy?: Partial<Description> | CommandFunc<Partial<Description> | Promise<Partial<Description>>>;
  label?: string | CommandFunc<string>;
  mnemonic?: number | CommandFunc<number>;
  icon?: VirtualElement.IRenderer | undefined | CommandFunc<VirtualElement.IRenderer | undefined>;
  iconClass?: string | CommandFunc<string>;
  iconLabel?: string | CommandFunc<string>;
  caption?: string | CommandFunc<string>;
  usage?: string | CommandFunc<string>;
  className?: string | CommandFunc<string>;
  dataset?: Dataset | CommandFunc<Dataset>;
  isEnabled?: CommandFunc<boolean>;
  isToggled?: CommandFunc<boolean>;
  isToggleable?: boolean;
  isVisible?: CommandFunc<boolean>;
}

Command Management

Key Binding System

Advanced keyboard shortcut system with context-aware matching, chord sequences, and platform-specific key mappings.

interface IKeyBindingOptions {
  keys: string[];
  selector: string;
  command: string;
  args?: ReadonlyPartialJSONObject;
  winKeys?: string[];
  macKeys?: string[];
  linuxKeys?: string[];
  preventDefault?: boolean;
}

class CommandRegistry {
  get keyBindings(): ReadonlyArray<CommandRegistry.IKeyBinding>;
  addKeyBinding(options: CommandRegistry.IKeyBindingOptions): IDisposable;
  processKeydownEvent(event: KeyboardEvent): void;
  holdKeyBindingExecution(event: KeyboardEvent, permission: Promise<boolean>): void;
  processKeyupEvent(event: KeyboardEvent): void;
}

Key Binding System

Command Metadata

Rich metadata system for command presentation in user interfaces, including labels, icons, state management, and contextual information.

class CommandRegistry {
  describedBy(id: string, args?: ReadonlyPartialJSONObject): Promise<CommandRegistry.Description>;
  label(id: string, args?: ReadonlyPartialJSONObject): string;
  mnemonic(id: string, args?: ReadonlyPartialJSONObject): number;
  icon(id: string, args?: ReadonlyPartialJSONObject): VirtualElement.IRenderer | undefined;
  iconClass(id: string, args?: ReadonlyPartialJSONObject): string;
  iconLabel(id: string, args?: ReadonlyPartialJSONObject): string;
  caption(id: string, args?: ReadonlyPartialJSONObject): string;
  usage(id: string, args?: ReadonlyPartialJSONObject): string;
  className(id: string, args?: ReadonlyPartialJSONObject): string;
  dataset(id: string, args?: ReadonlyPartialJSONObject): CommandRegistry.Dataset;
  isEnabled(id: string, args?: ReadonlyPartialJSONObject): boolean;
  isToggled(id: string, args?: ReadonlyPartialJSONObject): boolean;
  isToggleable(id: string, args?: ReadonlyJSONObject): boolean;
  isVisible(id: string, args?: ReadonlyPartialJSONObject): boolean;
}

Command Metadata

Signals

The CommandRegistry provides reactive signals for responding to changes in command and key binding state.

class CommandRegistry {
  get commandChanged(): ISignal<this, CommandRegistry.ICommandChangedArgs>;
  get commandExecuted(): ISignal<this, CommandRegistry.ICommandExecutedArgs>;
  get keyBindingChanged(): ISignal<this, CommandRegistry.IKeyBindingChangedArgs>;
}

interface ICommandChangedArgs {
  readonly id: string | undefined;
  readonly type: 'added' | 'removed' | 'changed' | 'many-changed';
}

interface ICommandExecutedArgs {
  readonly id: string;
  readonly args: ReadonlyPartialJSONObject;
  readonly result: Promise<any>;
}

interface IKeyBindingChangedArgs {
  readonly binding: IKeyBinding;
  readonly type: 'added' | 'removed';
}

Core Types

// Core @lumino/commands types
type CommandFunc<T> = (args: ReadonlyPartialJSONObject) => T;
type Dataset = { readonly [key: string]: string };
type Description = { args: ReadonlyJSONObject | null };

interface IKeyBinding {
  readonly keys: ReadonlyArray<string>;
  readonly selector: string;
  readonly command: string;
  readonly args: ReadonlyPartialJSONObject;
  readonly preventDefault?: boolean;
}

interface IKeystrokeParts {
  cmd: boolean;
  ctrl: boolean;
  alt: boolean;
  shift: boolean;
  key: string;
}

// External types from @lumino dependencies
interface IDisposable {
  readonly isDisposed: boolean;
  dispose(): void;
}

interface ISignal<T, U> {
  connect(slot: (sender: T, args: U) => void, thisArg?: any): boolean;
  disconnect(slot: (sender: T, args: U) => void, thisArg?: any): boolean;
  emit(args: U): void;
}

// From @lumino/coreutils
type ReadonlyJSONObject = { readonly [key: string]: ReadonlyJSONValue };
type ReadonlyPartialJSONObject = { readonly [key: string]: ReadonlyJSONValue | undefined };
type ReadonlyJSONValue = null | boolean | number | string | ReadonlyJSONArray | ReadonlyJSONObject;
type ReadonlyJSONArray = readonly ReadonlyJSONValue[];

// From @lumino/virtualdom
namespace VirtualElement {
  interface IRenderer {
    render(host?: HTMLElement, options?: any): void;
  }
}

Static Utilities

namespace CommandRegistry {
  function parseKeystroke(keystroke: string): IKeystrokeParts;
  function normalizeKeystroke(keystroke: string): string;
  function normalizeKeys(options: IKeyBindingOptions): string[];
  function formatKeystroke(keystroke: string | readonly string[]): string;
  function isModifierKeyPressed(event: KeyboardEvent): boolean;
  function keystrokeForKeydownEvent(event: KeyboardEvent): string;
}