0
# Lumino Commands
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: @lumino/commands
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @lumino/commands`
10

11
## Core Imports
12

13
```typescript
14
import { CommandRegistry } from "@lumino/commands";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { CommandRegistry } = require("@lumino/commands");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { CommandRegistry } from "@lumino/commands";
27
import { IDisposable } from "@lumino/disposable";
28

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

32
// Add a command
33
const disposable: IDisposable = registry.addCommand("save-file", {
34
  execute: (args) => {
35
    console.log("Saving file:", args.filename || "untitled");
36
    return Promise.resolve();
37
  },
38
  label: "Save File",
39
  caption: "Save the current file",
40
  isEnabled: () => true,
41
  isVisible: () => true
42
});
43

44
// Add a key binding
45
registry.addKeyBinding({
46
  keys: ["Ctrl S"],
47
  selector: "body",
48
  command: "save-file"
49
});
50

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

54
// Clean up
55
disposable.dispose();
56
```
57

58
## Architecture
59

60
Lumino Commands is built around several key components:
61

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

68
## Capabilities
69

70
### Command Management
71

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

74
```typescript { .api }
75
class CommandRegistry {
76
  constructor();
77
  
78
  listCommands(): string[];
79
  hasCommand(id: string): boolean;
80
  addCommand(id: string, options: CommandRegistry.ICommandOptions): IDisposable;
81
  notifyCommandChanged(id?: string): void;
82
  execute(id: string, args?: ReadonlyPartialJSONObject): Promise<any>;
83
}
84

85
interface ICommandOptions {
86
  execute: CommandFunc<any | Promise<any>>;
87
  describedBy?: Partial<Description> | CommandFunc<Partial<Description> | Promise<Partial<Description>>>;
88
  label?: string | CommandFunc<string>;
89
  mnemonic?: number | CommandFunc<number>;
90
  icon?: VirtualElement.IRenderer | undefined | CommandFunc<VirtualElement.IRenderer | undefined>;
91
  iconClass?: string | CommandFunc<string>;
92
  iconLabel?: string | CommandFunc<string>;
93
  caption?: string | CommandFunc<string>;
94
  usage?: string | CommandFunc<string>;
95
  className?: string | CommandFunc<string>;
96
  dataset?: Dataset | CommandFunc<Dataset>;
97
  isEnabled?: CommandFunc<boolean>;
98
  isToggled?: CommandFunc<boolean>;
99
  isToggleable?: boolean;
100
  isVisible?: CommandFunc<boolean>;
101
}
102
```
103

104
[Command Management](./command-management.md)
105

106
### Key Binding System
107

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

110
```typescript { .api }
111
interface IKeyBindingOptions {
112
  keys: string[];
113
  selector: string;
114
  command: string;
115
  args?: ReadonlyPartialJSONObject;
116
  winKeys?: string[];
117
  macKeys?: string[];
118
  linuxKeys?: string[];
119
  preventDefault?: boolean;
120
}
121

122
class CommandRegistry {
123
  get keyBindings(): ReadonlyArray<CommandRegistry.IKeyBinding>;
124
  addKeyBinding(options: CommandRegistry.IKeyBindingOptions): IDisposable;
125
  processKeydownEvent(event: KeyboardEvent): void;
126
  holdKeyBindingExecution(event: KeyboardEvent, permission: Promise<boolean>): void;
127
  processKeyupEvent(event: KeyboardEvent): void;
128
}
129
```
130

131
[Key Binding System](./key-binding-system.md)
132

133
### Command Metadata
134

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

137
```typescript { .api }
138
class CommandRegistry {
139
  describedBy(id: string, args?: ReadonlyPartialJSONObject): Promise<CommandRegistry.Description>;
140
  label(id: string, args?: ReadonlyPartialJSONObject): string;
141
  mnemonic(id: string, args?: ReadonlyPartialJSONObject): number;
142
  icon(id: string, args?: ReadonlyPartialJSONObject): VirtualElement.IRenderer | undefined;
143
  iconClass(id: string, args?: ReadonlyPartialJSONObject): string;
144
  iconLabel(id: string, args?: ReadonlyPartialJSONObject): string;
145
  caption(id: string, args?: ReadonlyPartialJSONObject): string;
146
  usage(id: string, args?: ReadonlyPartialJSONObject): string;
147
  className(id: string, args?: ReadonlyPartialJSONObject): string;
148
  dataset(id: string, args?: ReadonlyPartialJSONObject): CommandRegistry.Dataset;
149
  isEnabled(id: string, args?: ReadonlyPartialJSONObject): boolean;
150
  isToggled(id: string, args?: ReadonlyPartialJSONObject): boolean;
151
  isToggleable(id: string, args?: ReadonlyJSONObject): boolean;
152
  isVisible(id: string, args?: ReadonlyPartialJSONObject): boolean;
153
}
154
```
155

156
[Command Metadata](./command-metadata.md)
157

158
## Signals
159

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

162
```typescript { .api }
163
class CommandRegistry {
164
  get commandChanged(): ISignal<this, CommandRegistry.ICommandChangedArgs>;
165
  get commandExecuted(): ISignal<this, CommandRegistry.ICommandExecutedArgs>;
166
  get keyBindingChanged(): ISignal<this, CommandRegistry.IKeyBindingChangedArgs>;
167
}
168

169
interface ICommandChangedArgs {
170
  readonly id: string | undefined;
171
  readonly type: 'added' | 'removed' | 'changed' | 'many-changed';
172
}
173

174
interface ICommandExecutedArgs {
175
  readonly id: string;
176
  readonly args: ReadonlyPartialJSONObject;
177
  readonly result: Promise<any>;
178
}
179

180
interface IKeyBindingChangedArgs {
181
  readonly binding: IKeyBinding;
182
  readonly type: 'added' | 'removed';
183
}
184
```
185

186
## Core Types
187

188
```typescript { .api }
189
// Core @lumino/commands types
190
type CommandFunc<T> = (args: ReadonlyPartialJSONObject) => T;
191
type Dataset = { readonly [key: string]: string };
192
type Description = { args: ReadonlyJSONObject | null };
193

194
interface IKeyBinding {
195
  readonly keys: ReadonlyArray<string>;
196
  readonly selector: string;
197
  readonly command: string;
198
  readonly args: ReadonlyPartialJSONObject;
199
  readonly preventDefault?: boolean;
200
}
201

202
interface IKeystrokeParts {
203
  cmd: boolean;
204
  ctrl: boolean;
205
  alt: boolean;
206
  shift: boolean;
207
  key: string;
208
}
209

210
// External types from @lumino dependencies
211
interface IDisposable {
212
  readonly isDisposed: boolean;
213
  dispose(): void;
214
}
215

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

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

228
// From @lumino/virtualdom
229
namespace VirtualElement {
230
  interface IRenderer {
231
    render(host?: HTMLElement, options?: any): void;
232
  }
233
}
234
```
235

236
## Static Utilities
237

238
```typescript { .api }
239
namespace CommandRegistry {
240
  function parseKeystroke(keystroke: string): IKeystrokeParts;
241
  function normalizeKeystroke(keystroke: string): string;
242
  function normalizeKeys(options: IKeyBindingOptions): string[];
243
  function formatKeystroke(keystroke: string | readonly string[]): string;
244
  function isModifierKeyPressed(event: KeyboardEvent): boolean;
245
  function keystrokeForKeydownEvent(event: KeyboardEvent): string;
246
}
247
```