tessl/npm-lumino--commands

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Lumino Commands

Name: tessl/npm-lumino--commands
Author: tessl

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;
}