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
```