@tooee/commands 0.2.4 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -5
- package/dist/build-context.d.ts +32 -0
- package/dist/build-context.d.ts.map +1 -0
- package/dist/build-context.js +44 -0
- package/dist/build-context.js.map +1 -0
- package/dist/command-store.d.ts +19 -19
- package/dist/command-store.d.ts.map +1 -1
- package/dist/command-store.js +191 -148
- package/dist/command-store.js.map +1 -1
- package/dist/context.d.ts +16 -16
- package/dist/context.d.ts.map +1 -1
- package/dist/context.js +112 -107
- package/dist/context.js.map +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js.map +1 -1
- package/dist/match.d.ts +1 -1
- package/dist/match.d.ts.map +1 -1
- package/dist/match.js +14 -8
- package/dist/match.js.map +1 -1
- package/dist/mode.d.ts +4 -4
- package/dist/mode.d.ts.map +1 -1
- package/dist/mode.js +14 -14
- package/dist/mode.js.map +1 -1
- package/dist/parse.d.ts +1 -1
- package/dist/parse.d.ts.map +1 -1
- package/dist/parse.js +19 -18
- package/dist/parse.js.map +1 -1
- package/dist/sequence.d.ts +6 -5
- package/dist/sequence.d.ts.map +1 -1
- package/dist/sequence.js +31 -20
- package/dist/sequence.js.map +1 -1
- package/dist/types.d.ts +18 -10
- package/dist/types.d.ts.map +1 -1
- package/dist/use-actions.d.ts +1 -1
- package/dist/use-actions.d.ts.map +1 -1
- package/dist/use-actions.js +22 -12
- package/dist/use-actions.js.map +1 -1
- package/dist/use-command.d.ts +1 -1
- package/dist/use-command.d.ts.map +1 -1
- package/dist/use-command.js +21 -12
- package/dist/use-command.js.map +1 -1
- package/package.json +1 -1
- package/src/build-context.ts +65 -0
- package/src/command-store.ts +366 -290
- package/src/context.tsx +298 -284
- package/src/index.ts +17 -16
- package/src/match.ts +23 -11
- package/src/mode.tsx +37 -41
- package/src/parse.ts +48 -46
- package/src/sequence.ts +88 -66
- package/src/types.ts +69 -57
- package/src/use-actions.ts +46 -35
- package/src/use-command.ts +44 -33
package/src/types.ts
CHANGED
|
@@ -1,14 +1,13 @@
|
|
|
1
|
-
import type { Mode } from "./mode.js"
|
|
1
|
+
import type { Mode } from "./mode.js";
|
|
2
2
|
|
|
3
|
-
export interface
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
commands: { invoke: (id: string) => void; list: () => Command[] }
|
|
7
|
-
exit: () => void
|
|
3
|
+
export interface CommandCommands {
|
|
4
|
+
invoke: (id: string) => void;
|
|
5
|
+
list: () => Command[];
|
|
8
6
|
}
|
|
9
7
|
|
|
10
8
|
/**
|
|
11
|
-
* The context handed to command handlers.
|
|
9
|
+
* The context handed to command handlers. The core fields below are always
|
|
10
|
+
* provided by the command provider. Domain packages contribute additional typed
|
|
12
11
|
* fields via module augmentation (the mechanism the shell already uses for
|
|
13
12
|
* `overlay` and `toast`):
|
|
14
13
|
*
|
|
@@ -19,44 +18,57 @@ export interface CommandContextBase {
|
|
|
19
18
|
* }
|
|
20
19
|
* }
|
|
21
20
|
* ```
|
|
21
|
+
*
|
|
22
|
+
* Augmented fields are contributed at runtime by context sources
|
|
23
|
+
* (`useCommandContextSource`), so an augmenting package is responsible for
|
|
24
|
+
* mounting its provider. The core fields are declared here directly: the
|
|
25
|
+
* interface is still open for merging, but it is no longer an empty declaration
|
|
26
|
+
* that only inherits its own members.
|
|
22
27
|
*/
|
|
23
|
-
|
|
24
|
-
|
|
28
|
+
export interface CommandContext {
|
|
29
|
+
mode: Mode;
|
|
30
|
+
setMode: (mode: Mode) => void;
|
|
31
|
+
commands: CommandCommands;
|
|
32
|
+
exit: () => void;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** The subset of `CommandContext` the provider itself always supplies. */
|
|
36
|
+
export type CommandContextBase = Pick<CommandContext, "mode" | "setMode" | "commands" | "exit">;
|
|
25
37
|
|
|
26
|
-
export type CommandHandler = (ctx: CommandContext) => void | Promise<void
|
|
27
|
-
export type CommandWhen = (ctx: CommandContext) => boolean
|
|
38
|
+
export type CommandHandler = (ctx: CommandContext) => void | Promise<void>;
|
|
39
|
+
export type CommandWhen = (ctx: CommandContext) => boolean;
|
|
28
40
|
|
|
29
41
|
export interface Command {
|
|
30
|
-
id: string
|
|
31
|
-
title: string
|
|
32
|
-
handler: CommandHandler
|
|
33
|
-
defaultHotkey?: string
|
|
34
|
-
modes?: Mode[]
|
|
35
|
-
when?: CommandWhen
|
|
36
|
-
category?: string
|
|
37
|
-
group?: string
|
|
38
|
-
icon?: string
|
|
39
|
-
hidden?: boolean
|
|
42
|
+
id: string;
|
|
43
|
+
title: string;
|
|
44
|
+
handler: CommandHandler;
|
|
45
|
+
defaultHotkey?: string;
|
|
46
|
+
modes?: Mode[];
|
|
47
|
+
when?: CommandWhen;
|
|
48
|
+
category?: string;
|
|
49
|
+
group?: string;
|
|
50
|
+
icon?: string;
|
|
51
|
+
hidden?: boolean;
|
|
40
52
|
}
|
|
41
53
|
|
|
42
54
|
export interface ParsedHotkey {
|
|
43
|
-
steps: ParsedStep[]
|
|
55
|
+
steps: ParsedStep[];
|
|
44
56
|
}
|
|
45
57
|
|
|
46
58
|
export interface ParsedStep {
|
|
47
|
-
key: string
|
|
48
|
-
ctrl: boolean
|
|
49
|
-
meta: boolean
|
|
50
|
-
shift: boolean
|
|
51
|
-
option: boolean
|
|
59
|
+
key: string;
|
|
60
|
+
ctrl: boolean;
|
|
61
|
+
meta: boolean;
|
|
62
|
+
shift: boolean;
|
|
63
|
+
option: boolean;
|
|
52
64
|
/** Super/Windows/Cmd-as-super modifier. Optional for back-compat. */
|
|
53
|
-
super?: boolean
|
|
65
|
+
super?: boolean;
|
|
54
66
|
}
|
|
55
67
|
|
|
56
68
|
export interface CommandRegistry {
|
|
57
|
-
commands: Map<string, Command
|
|
58
|
-
register: (command: Command) => () => void
|
|
59
|
-
invoke: (id: string) => void
|
|
69
|
+
commands: Map<string, Command>;
|
|
70
|
+
register: (command: Command) => () => void;
|
|
71
|
+
invoke: (id: string) => void;
|
|
60
72
|
}
|
|
61
73
|
|
|
62
74
|
/**
|
|
@@ -65,7 +77,7 @@ export interface CommandRegistry {
|
|
|
65
77
|
* (including the root app) — even for keys it does not handle.
|
|
66
78
|
* - `passive`: never becomes the keyboard owner; purely visual.
|
|
67
79
|
*/
|
|
68
|
-
export type CommandSurfaceRole = "modal" | "passive"
|
|
80
|
+
export type CommandSurfaceRole = "modal" | "passive";
|
|
69
81
|
|
|
70
82
|
/**
|
|
71
83
|
* A command surface is an interaction surface that can own keyboard input.
|
|
@@ -75,52 +87,52 @@ export type CommandSurfaceRole = "modal" | "passive"
|
|
|
75
87
|
* an overlay without leaking mode/command state into the parent.
|
|
76
88
|
*/
|
|
77
89
|
export interface CommandSurfaceEntry {
|
|
78
|
-
id: string
|
|
79
|
-
role: CommandSurfaceRole
|
|
90
|
+
id: string;
|
|
91
|
+
role: CommandSurfaceRole;
|
|
80
92
|
/** Nesting depth (root children are depth 0; the first overlay surface is 1). */
|
|
81
|
-
depth: number
|
|
93
|
+
depth: number;
|
|
82
94
|
/** Monotonic registration order, used to break depth ties. */
|
|
83
|
-
order: number
|
|
84
|
-
registry: CommandRegistry
|
|
95
|
+
order: number;
|
|
96
|
+
registry: CommandRegistry;
|
|
85
97
|
/** Reads this surface's current local mode. */
|
|
86
|
-
getMode: () => Mode
|
|
98
|
+
getMode: () => Mode;
|
|
87
99
|
/** Builds the command context handed to this surface's command handlers. */
|
|
88
|
-
buildCtx: () => CommandContext
|
|
100
|
+
buildCtx: () => CommandContext;
|
|
89
101
|
}
|
|
90
102
|
|
|
91
103
|
export interface ActiveCommandSurface {
|
|
92
|
-
id: string
|
|
93
|
-
role: CommandSurfaceRole
|
|
104
|
+
id: string;
|
|
105
|
+
role: CommandSurfaceRole;
|
|
94
106
|
/**
|
|
95
107
|
* Commands registered on this surface (reactive). Enables surface-aware
|
|
96
108
|
* which-key/help/palette consumers.
|
|
97
109
|
*/
|
|
98
|
-
commands: readonly Command[]
|
|
110
|
+
commands: readonly Command[];
|
|
99
111
|
}
|
|
100
112
|
|
|
101
113
|
export interface CommandGroup {
|
|
102
|
-
id: string
|
|
103
|
-
title: string
|
|
104
|
-
prefix: string
|
|
105
|
-
description?: string
|
|
106
|
-
icon?: string
|
|
107
|
-
order?: number
|
|
114
|
+
id: string;
|
|
115
|
+
title: string;
|
|
116
|
+
prefix: string;
|
|
117
|
+
description?: string;
|
|
118
|
+
icon?: string;
|
|
119
|
+
order?: number;
|
|
108
120
|
}
|
|
109
121
|
|
|
110
122
|
export interface RegisteredCommandGroup extends CommandGroup {
|
|
111
|
-
prefixKey: string
|
|
123
|
+
prefixKey: string;
|
|
112
124
|
}
|
|
113
125
|
|
|
114
126
|
export interface CommandSequenceCandidate {
|
|
115
|
-
command: Command
|
|
116
|
-
hotkey: string
|
|
117
|
-
steps: ParsedStep[]
|
|
118
|
-
remainingSteps: ParsedStep[]
|
|
119
|
-
nextStep: ParsedStep
|
|
120
|
-
group?: CommandGroup
|
|
127
|
+
command: Command;
|
|
128
|
+
hotkey: string;
|
|
129
|
+
steps: ParsedStep[];
|
|
130
|
+
remainingSteps: ParsedStep[];
|
|
131
|
+
nextStep: ParsedStep;
|
|
132
|
+
group?: CommandGroup;
|
|
121
133
|
}
|
|
122
134
|
|
|
123
135
|
export interface CommandSequenceState {
|
|
124
|
-
prefix: ParsedStep[]
|
|
125
|
-
candidates: CommandSequenceCandidate[]
|
|
136
|
+
prefix: ParsedStep[];
|
|
137
|
+
candidates: CommandSequenceCandidate[];
|
|
126
138
|
}
|
package/src/use-actions.ts
CHANGED
|
@@ -1,25 +1,25 @@
|
|
|
1
|
-
import { useEffect, useMemo, useRef } from "react"
|
|
2
|
-
import { useSurfaceRegistry } from "./context.js"
|
|
3
|
-
import type { Command, CommandHandler, CommandWhen } from "./types.js"
|
|
4
|
-
import type { Mode } from "./mode.js"
|
|
1
|
+
import { useEffect, useMemo, useRef } from "react";
|
|
2
|
+
import { useSurfaceRegistry } from "./context.js";
|
|
3
|
+
import type { Command, CommandHandler, CommandWhen } from "./types.js";
|
|
4
|
+
import type { Mode } from "./mode.js";
|
|
5
5
|
|
|
6
6
|
export interface ActionDefinition {
|
|
7
|
-
id: string
|
|
8
|
-
title: string
|
|
9
|
-
hotkey?: string
|
|
10
|
-
modes?: Mode[]
|
|
11
|
-
handler: CommandHandler
|
|
12
|
-
when?: CommandWhen
|
|
13
|
-
category?: string
|
|
14
|
-
group?: string
|
|
15
|
-
icon?: string
|
|
16
|
-
hidden?: boolean
|
|
7
|
+
id: string;
|
|
8
|
+
title: string;
|
|
9
|
+
hotkey?: string;
|
|
10
|
+
modes?: Mode[];
|
|
11
|
+
handler: CommandHandler;
|
|
12
|
+
when?: CommandWhen;
|
|
13
|
+
category?: string;
|
|
14
|
+
group?: string;
|
|
15
|
+
icon?: string;
|
|
16
|
+
hidden?: boolean;
|
|
17
17
|
}
|
|
18
18
|
|
|
19
|
-
export function useActions(actions: ActionDefinition[] | undefined): void {
|
|
20
|
-
const registry = useSurfaceRegistry()
|
|
21
|
-
const actionsRef = useRef(actions)
|
|
22
|
-
actionsRef.current = actions
|
|
19
|
+
export const useActions = function useActions(actions: ActionDefinition[] | undefined): void {
|
|
20
|
+
const registry = useSurfaceRegistry();
|
|
21
|
+
const actionsRef = useRef(actions);
|
|
22
|
+
actionsRef.current = actions;
|
|
23
23
|
|
|
24
24
|
const key = useMemo(
|
|
25
25
|
() =>
|
|
@@ -32,32 +32,43 @@ export function useActions(actions: ActionDefinition[] | undefined): void {
|
|
|
32
32
|
)
|
|
33
33
|
.join(",") ?? "",
|
|
34
34
|
[actions],
|
|
35
|
-
)
|
|
35
|
+
);
|
|
36
36
|
|
|
37
37
|
useEffect(() => {
|
|
38
|
-
const current = actionsRef
|
|
39
|
-
if (!current || current.length === 0)
|
|
38
|
+
const { current } = actionsRef;
|
|
39
|
+
if (!current || current.length === 0) {
|
|
40
|
+
return () => void 0;
|
|
41
|
+
}
|
|
40
42
|
|
|
41
43
|
const unregisters = current.map((action, i) => {
|
|
42
44
|
const command: Command = {
|
|
43
|
-
id: action.id,
|
|
44
|
-
title: action.title,
|
|
45
|
-
defaultHotkey: action.hotkey,
|
|
46
|
-
modes: action.modes,
|
|
47
|
-
handler: (ctx) => actionsRef.current?.[i]?.handler(ctx),
|
|
48
|
-
when: action.when ? (ctx) => actionsRef.current?.[i]?.when?.(ctx) ?? false : undefined,
|
|
49
45
|
category: action.category,
|
|
46
|
+
defaultHotkey: action.hotkey,
|
|
50
47
|
group: action.group,
|
|
51
|
-
|
|
48
|
+
handler: async (ctx) => {
|
|
49
|
+
// A stale index (the action list shrank between registration and
|
|
50
|
+
// dispatch) is a no-op, so the missing-action path just returns. The
|
|
51
|
+
// body runs synchronously up to the call, preserving dispatch timing.
|
|
52
|
+
const currentAction = actionsRef.current?.[i];
|
|
53
|
+
if (currentAction === undefined) {
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
56
|
+
await currentAction.handler(ctx);
|
|
57
|
+
},
|
|
52
58
|
hidden: action.hidden,
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
59
|
+
icon: action.icon,
|
|
60
|
+
id: action.id,
|
|
61
|
+
modes: action.modes,
|
|
62
|
+
title: action.title,
|
|
63
|
+
when: action.when ? (ctx) => actionsRef.current?.[i]?.when?.(ctx) ?? false : undefined,
|
|
64
|
+
};
|
|
65
|
+
return registry.register(command);
|
|
66
|
+
});
|
|
56
67
|
|
|
57
68
|
return () => {
|
|
58
69
|
for (const unregister of unregisters) {
|
|
59
|
-
unregister()
|
|
70
|
+
unregister();
|
|
60
71
|
}
|
|
61
|
-
}
|
|
62
|
-
}, [key, registry])
|
|
63
|
-
}
|
|
72
|
+
};
|
|
73
|
+
}, [key, registry]);
|
|
74
|
+
};
|
package/src/use-command.ts
CHANGED
|
@@ -1,57 +1,68 @@
|
|
|
1
|
-
import { useEffect, useRef } from "react"
|
|
2
|
-
import type { Command, CommandHandler, CommandWhen } from "./types.js"
|
|
3
|
-
import type { Mode } from "./mode.js"
|
|
4
|
-
import { useSurfaceRegistry } from "./context.js"
|
|
1
|
+
import { useEffect, useRef } from "react";
|
|
2
|
+
import type { Command, CommandHandler, CommandWhen } from "./types.js";
|
|
3
|
+
import type { Mode } from "./mode.js";
|
|
4
|
+
import { useSurfaceRegistry } from "./context.js";
|
|
5
5
|
|
|
6
6
|
export interface UseCommandOptions {
|
|
7
|
-
id: string
|
|
8
|
-
title: string
|
|
9
|
-
handler: CommandHandler
|
|
10
|
-
hotkey?: string
|
|
11
|
-
modes?: Mode[]
|
|
12
|
-
category?: string
|
|
13
|
-
group?: string
|
|
14
|
-
icon?: string
|
|
15
|
-
when?: CommandWhen
|
|
16
|
-
hidden?: boolean
|
|
7
|
+
id: string;
|
|
8
|
+
title: string;
|
|
9
|
+
handler: CommandHandler;
|
|
10
|
+
hotkey?: string;
|
|
11
|
+
modes?: Mode[];
|
|
12
|
+
category?: string;
|
|
13
|
+
group?: string;
|
|
14
|
+
icon?: string;
|
|
15
|
+
when?: CommandWhen;
|
|
16
|
+
hidden?: boolean;
|
|
17
17
|
/**
|
|
18
18
|
* Register the command (default true). `false` unregisters it entirely — it
|
|
19
19
|
* cannot be invoked and never appears in the palette or which-key. Use this
|
|
20
20
|
* for genuinely disabled features; use `when` for context-dependent ones.
|
|
21
21
|
*/
|
|
22
|
-
enabled?: boolean
|
|
22
|
+
enabled?: boolean;
|
|
23
23
|
}
|
|
24
24
|
|
|
25
|
-
export function useCommand(options: UseCommandOptions): void {
|
|
26
|
-
const registry = useSurfaceRegistry()
|
|
27
|
-
const optionsRef = useRef(options)
|
|
28
|
-
optionsRef.current = options
|
|
25
|
+
export const useCommand = function useCommand(options: UseCommandOptions): void {
|
|
26
|
+
const registry = useSurfaceRegistry();
|
|
27
|
+
const optionsRef = useRef(options);
|
|
28
|
+
optionsRef.current = options;
|
|
29
29
|
|
|
30
30
|
// Key on the modes CONTENT, not the array identity: callers pass inline
|
|
31
31
|
// array literals, and with a subscribable registry an identity-keyed effect
|
|
32
32
|
// would re-register on every render — re-notifying the subscriber that
|
|
33
33
|
// caused the render (an infinite update loop for components that both
|
|
34
34
|
// register and observe commands, e.g. the command palette provider).
|
|
35
|
-
const modesKey = options.modes?.join("|") ?? ""
|
|
35
|
+
const modesKey = options.modes?.join("|") ?? "";
|
|
36
36
|
|
|
37
37
|
useEffect(() => {
|
|
38
|
-
if (options.enabled === false)
|
|
38
|
+
if (options.enabled === false) {
|
|
39
|
+
return () => void 0;
|
|
40
|
+
}
|
|
39
41
|
|
|
40
42
|
const command: Command = {
|
|
41
|
-
|
|
42
|
-
title: options.title,
|
|
43
|
-
handler: (...args: Parameters<Command["handler"]>) => optionsRef.current.handler(...args),
|
|
43
|
+
category: options.category,
|
|
44
44
|
defaultHotkey: options.hotkey,
|
|
45
|
+
group: options.group,
|
|
46
|
+
handler: (...args: Parameters<Command["handler"]>): void | Promise<void> =>
|
|
47
|
+
optionsRef.current.handler(...args),
|
|
48
|
+
hidden: options.hidden,
|
|
49
|
+
icon: options.icon,
|
|
50
|
+
id: options.id,
|
|
45
51
|
// Read through the ref: the effect is keyed on modesKey (content), and
|
|
46
52
|
// the ref holds the same-render options when the effect runs.
|
|
47
53
|
modes: optionsRef.current.modes,
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
54
|
+
title: options.title,
|
|
55
|
+
when: optionsRef.current.when
|
|
56
|
+
? (ctx) => {
|
|
57
|
+
const { when } = optionsRef.current;
|
|
58
|
+
if (!when) {
|
|
59
|
+
return false;
|
|
60
|
+
}
|
|
61
|
+
return when(ctx);
|
|
62
|
+
}
|
|
63
|
+
: undefined,
|
|
64
|
+
};
|
|
65
|
+
return registry.register(command);
|
|
55
66
|
}, [
|
|
56
67
|
options.id,
|
|
57
68
|
options.title,
|
|
@@ -63,5 +74,5 @@ export function useCommand(options: UseCommandOptions): void {
|
|
|
63
74
|
options.hidden,
|
|
64
75
|
options.enabled,
|
|
65
76
|
registry,
|
|
66
|
-
])
|
|
67
|
-
}
|
|
77
|
+
]);
|
|
78
|
+
};
|