@tooee/commands 0.2.4 → 0.3.1
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/context.tsx
CHANGED
|
@@ -1,14 +1,7 @@
|
|
|
1
|
-
import {
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
useCallback,
|
|
6
|
-
useEffect,
|
|
7
|
-
useMemo,
|
|
8
|
-
type ReactNode,
|
|
9
|
-
} from "react"
|
|
10
|
-
import { useKeyboard } from "@opentui/react"
|
|
11
|
-
import { useSelector } from "@xstate/store-react"
|
|
1
|
+
import { createContext, useContext, useRef, useCallback, useEffect, useMemo } from "react";
|
|
2
|
+
import type { ReactNode } from "react";
|
|
3
|
+
import { useKeyboard } from "@opentui/react";
|
|
4
|
+
import { useSelector } from "@xstate/store-react";
|
|
12
5
|
import type {
|
|
13
6
|
ActiveCommandSurface,
|
|
14
7
|
Command,
|
|
@@ -18,10 +11,10 @@ import type {
|
|
|
18
11
|
CommandSequenceState,
|
|
19
12
|
CommandSurfaceRole,
|
|
20
13
|
RegisteredCommandGroup,
|
|
21
|
-
} from "./types.js"
|
|
22
|
-
import type { Mode } from "./mode.js"
|
|
23
|
-
import { ModeProvider, useMode, useSetMode } from "./mode.js"
|
|
24
|
-
import { parseHotkey } from "./parse.js"
|
|
14
|
+
} from "./types.js";
|
|
15
|
+
import type { Mode } from "./mode.js";
|
|
16
|
+
import { ModeProvider, useMode, useSetMode } from "./mode.js";
|
|
17
|
+
import { parseHotkey } from "./parse.js";
|
|
25
18
|
import {
|
|
26
19
|
ROOT_SURFACE_ID,
|
|
27
20
|
createCommandStore,
|
|
@@ -29,30 +22,42 @@ import {
|
|
|
29
22
|
selectSequence,
|
|
30
23
|
selectSurfaceCommandMap,
|
|
31
24
|
stepsKey,
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
} from "./command-store.js"
|
|
25
|
+
} from "./command-store.js";
|
|
26
|
+
import type { CommandStore, ContextGetter, SurfaceRecord } from "./command-store.js";
|
|
27
|
+
import { buildCommandContext, commandsFromRegistry } from "./build-context.js";
|
|
36
28
|
|
|
37
29
|
interface CommandContextValue {
|
|
38
|
-
registry: CommandRegistry
|
|
39
|
-
leaderKey?: string
|
|
40
|
-
contextSources: Map<string, ContextGetter
|
|
41
|
-
groups: Map<string, RegisteredCommandGroup
|
|
30
|
+
registry: CommandRegistry;
|
|
31
|
+
leaderKey?: string;
|
|
32
|
+
contextSources: Map<string, ContextGetter>;
|
|
33
|
+
groups: Map<string, RegisteredCommandGroup>;
|
|
42
34
|
}
|
|
43
35
|
|
|
44
36
|
/** Internal provider value: the store plus the surface this subtree registers to. */
|
|
45
37
|
interface CommandStoreContextValue {
|
|
46
|
-
commandStore: CommandStore
|
|
38
|
+
commandStore: CommandStore;
|
|
47
39
|
/** The surface record `useCommand` registrations under this subtree target. */
|
|
48
|
-
surface: SurfaceRecord
|
|
49
|
-
leaderKey?: string
|
|
40
|
+
surface: SurfaceRecord;
|
|
41
|
+
leaderKey?: string;
|
|
50
42
|
}
|
|
51
43
|
|
|
52
|
-
const CommandContext = createContext<CommandStoreContextValue | null>(null)
|
|
53
|
-
const CommandSequenceContext = createContext<CommandSequenceState | null>(null)
|
|
44
|
+
const CommandContext = createContext<CommandStoreContextValue | null>(null);
|
|
45
|
+
const CommandSequenceContext = createContext<CommandSequenceState | null>(null);
|
|
54
46
|
/** Nesting depth of the nearest command surface (0 at the root app). */
|
|
55
|
-
const CommandSurfaceDepthContext = createContext(0)
|
|
47
|
+
const CommandSurfaceDepthContext = createContext(0);
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Placeholder context used before the dispatcher installs the real accessors,
|
|
51
|
+
* and by the fallback store. It has no context sources, so it carries only the
|
|
52
|
+
* core fields; dispatch never reaches it.
|
|
53
|
+
*/
|
|
54
|
+
const placeholderCommandContext = function placeholderCommandContext(mode: Mode): CommandContext {
|
|
55
|
+
return buildCommandContext({
|
|
56
|
+
commands: { invoke: () => void 0, list: () => [] },
|
|
57
|
+
mode,
|
|
58
|
+
setMode: () => void 0,
|
|
59
|
+
});
|
|
60
|
+
};
|
|
56
61
|
|
|
57
62
|
/**
|
|
58
63
|
* Fallback store for hooks that must not throw outside a CommandProvider
|
|
@@ -60,78 +65,62 @@ const CommandSurfaceDepthContext = createContext(0)
|
|
|
60
65
|
*/
|
|
61
66
|
const FALLBACK_COMMAND_STORE = createCommandStore({
|
|
62
67
|
root: {
|
|
68
|
+
buildCtx: () => placeholderCommandContext("cursor"),
|
|
63
69
|
getMode: () => "cursor",
|
|
64
|
-
// Placeholder context: augmented domain fields (overlay, view, ...) are
|
|
65
|
-
// only present where their providers run; dispatch never reaches this.
|
|
66
|
-
buildCtx: () =>
|
|
67
|
-
({
|
|
68
|
-
mode: "cursor",
|
|
69
|
-
setMode: () => {},
|
|
70
|
-
commands: { invoke: () => {}, list: () => [] },
|
|
71
|
-
exit: () => {},
|
|
72
|
-
}) as unknown as CommandContext,
|
|
73
70
|
},
|
|
74
|
-
})
|
|
71
|
+
});
|
|
75
72
|
|
|
76
73
|
export interface CommandProviderProps {
|
|
77
|
-
children: ReactNode
|
|
78
|
-
leader?: string
|
|
79
|
-
keymap?: Record<string, string
|
|
80
|
-
initialMode?: Mode
|
|
81
|
-
sequenceTimeoutMs?: number
|
|
74
|
+
children: ReactNode;
|
|
75
|
+
leader?: string;
|
|
76
|
+
keymap?: Record<string, string>;
|
|
77
|
+
initialMode?: Mode;
|
|
78
|
+
sequenceTimeoutMs?: number;
|
|
82
79
|
}
|
|
83
80
|
|
|
84
81
|
interface RootAccess {
|
|
85
|
-
|
|
86
|
-
|
|
82
|
+
buildCtx: () => CommandContext;
|
|
83
|
+
getMode: () => Mode;
|
|
87
84
|
}
|
|
88
85
|
|
|
89
|
-
export function CommandProvider({
|
|
86
|
+
export const CommandProvider = function CommandProvider({
|
|
90
87
|
children,
|
|
91
88
|
leader,
|
|
92
89
|
keymap,
|
|
93
90
|
initialMode,
|
|
94
91
|
sequenceTimeoutMs,
|
|
95
|
-
}: CommandProviderProps) {
|
|
92
|
+
}: CommandProviderProps): ReactNode {
|
|
96
93
|
// The store is created here (above the root ModeProvider) so mode changes
|
|
97
94
|
// can be routed into it as transitions; the dispatcher below installs the
|
|
98
95
|
// real root accessors before any key can dispatch.
|
|
99
96
|
const rootAccessRef = useRef<RootAccess>({
|
|
100
|
-
getMode: () => initialMode ?? "cursor",
|
|
101
97
|
// Placeholder until CommandDispatcher installs the real accessors on its
|
|
102
98
|
// first render (before any key can dispatch).
|
|
103
|
-
buildCtx: () =>
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
root: {
|
|
119
|
-
getMode: () => rootAccessRef.current.getMode(),
|
|
120
|
-
buildCtx: () => rootAccessRef.current.buildCtx(),
|
|
121
|
-
},
|
|
122
|
-
})
|
|
123
|
-
}
|
|
124
|
-
const commandStore = storeRef.current
|
|
99
|
+
buildCtx: () => placeholderCommandContext(initialMode ?? "cursor"),
|
|
100
|
+
getMode: () => initialMode ?? "cursor",
|
|
101
|
+
});
|
|
102
|
+
|
|
103
|
+
const storeRef = useRef<CommandStore | null>(null);
|
|
104
|
+
storeRef.current ??= createCommandStore({
|
|
105
|
+
keymap,
|
|
106
|
+
leader,
|
|
107
|
+
root: {
|
|
108
|
+
buildCtx: () => rootAccessRef.current.buildCtx(),
|
|
109
|
+
getMode: () => rootAccessRef.current.getMode(),
|
|
110
|
+
},
|
|
111
|
+
sequenceTimeoutMs,
|
|
112
|
+
});
|
|
113
|
+
const commandStore = storeRef.current;
|
|
125
114
|
|
|
126
115
|
// Root mode changes are transitions: reset any pending chord synchronously
|
|
127
116
|
// (this replaces the old post-render tracker-reset effect).
|
|
128
|
-
const handleModeChange = useCallback(
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
)
|
|
117
|
+
const handleModeChange = useCallback(() => {
|
|
118
|
+
commandStore.modeChanged(ROOT_SURFACE_ID);
|
|
119
|
+
}, [commandStore]);
|
|
132
120
|
|
|
133
121
|
return (
|
|
134
122
|
<ModeProvider initialMode={initialMode} onModeChange={handleModeChange}>
|
|
123
|
+
{/* oxlint-disable-next-line no-use-before-define -- dispatcher is deliberately declared below provider */}
|
|
135
124
|
<CommandDispatcher
|
|
136
125
|
commandStore={commandStore}
|
|
137
126
|
rootAccess={rootAccessRef}
|
|
@@ -140,12 +129,15 @@ export function CommandProvider({
|
|
|
140
129
|
sequenceTimeoutMs={sequenceTimeoutMs}
|
|
141
130
|
>
|
|
142
131
|
{children}
|
|
132
|
+
{/* oxlint-disable-next-line no-use-before-define -- closing dispatcher declaration is below provider */}
|
|
143
133
|
</CommandDispatcher>
|
|
144
134
|
</ModeProvider>
|
|
145
|
-
)
|
|
146
|
-
}
|
|
135
|
+
);
|
|
136
|
+
};
|
|
147
137
|
|
|
148
|
-
|
|
138
|
+
// Deferred(lint-sweep): preserve the top-down provider/dispatcher organization.
|
|
139
|
+
// oxlint-disable-next-line no-use-before-define -- provider deliberately renders its dispatcher below
|
|
140
|
+
const CommandDispatcher = function CommandDispatcher({
|
|
149
141
|
children,
|
|
150
142
|
commandStore,
|
|
151
143
|
rootAccess,
|
|
@@ -153,83 +145,84 @@ function CommandDispatcher({
|
|
|
153
145
|
keymap,
|
|
154
146
|
sequenceTimeoutMs,
|
|
155
147
|
}: {
|
|
156
|
-
children: ReactNode
|
|
157
|
-
commandStore: CommandStore
|
|
158
|
-
rootAccess: { current: RootAccess }
|
|
159
|
-
leader?: string
|
|
160
|
-
keymap?: Record<string, string
|
|
161
|
-
sequenceTimeoutMs?: number
|
|
162
|
-
}) {
|
|
163
|
-
const mode = useMode()
|
|
164
|
-
const modeRef = useRef(mode)
|
|
165
|
-
modeRef.current = mode
|
|
166
|
-
const setMode = useSetMode()
|
|
167
|
-
|
|
168
|
-
const buildCtx = useCallback(
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
}
|
|
182
|
-
return ctx as CommandContext
|
|
183
|
-
}, [commandStore, setMode])
|
|
184
|
-
|
|
185
|
-
const buildCtxRef = useRef(buildCtx)
|
|
186
|
-
buildCtxRef.current = buildCtx
|
|
148
|
+
children: ReactNode;
|
|
149
|
+
commandStore: CommandStore;
|
|
150
|
+
rootAccess: { current: RootAccess };
|
|
151
|
+
leader?: string;
|
|
152
|
+
keymap?: Record<string, string>;
|
|
153
|
+
sequenceTimeoutMs?: number;
|
|
154
|
+
}): ReactNode {
|
|
155
|
+
const mode = useMode();
|
|
156
|
+
const modeRef = useRef(mode);
|
|
157
|
+
modeRef.current = mode;
|
|
158
|
+
const setMode = useSetMode();
|
|
159
|
+
|
|
160
|
+
const buildCtx = useCallback(
|
|
161
|
+
(): CommandContext =>
|
|
162
|
+
buildCommandContext({
|
|
163
|
+
commands: commandsFromRegistry(commandStore.registryFor(commandStore.rootRecord)),
|
|
164
|
+
contributions: commandStore.store.getSnapshot().context.contextSources.values(),
|
|
165
|
+
mode: modeRef.current,
|
|
166
|
+
setMode,
|
|
167
|
+
}),
|
|
168
|
+
[commandStore, setMode],
|
|
169
|
+
);
|
|
170
|
+
|
|
171
|
+
const buildCtxRef = useRef(buildCtx);
|
|
172
|
+
buildCtxRef.current = buildCtx;
|
|
187
173
|
|
|
188
174
|
// Install the live root accessors and config (ref writes, same pattern as
|
|
189
175
|
// the previous modeRef mirrors; leader/keymap are read per dispatch).
|
|
190
|
-
rootAccess.current.getMode = () => modeRef.current
|
|
191
|
-
rootAccess.current.buildCtx = () => buildCtxRef.current()
|
|
192
|
-
commandStore.setConfig({
|
|
176
|
+
rootAccess.current.getMode = () => modeRef.current;
|
|
177
|
+
rootAccess.current.buildCtx = () => buildCtxRef.current();
|
|
178
|
+
commandStore.setConfig({ keymap, leader, sequenceTimeoutMs });
|
|
193
179
|
|
|
194
180
|
useKeyboard((event) => {
|
|
195
|
-
if (event.defaultPrevented)
|
|
196
|
-
|
|
181
|
+
if (event.defaultPrevented) {
|
|
182
|
+
return;
|
|
183
|
+
}
|
|
184
|
+
const result = commandStore.key(event);
|
|
197
185
|
if (result.handled) {
|
|
198
|
-
event.preventDefault()
|
|
199
|
-
result.invoke?.()
|
|
186
|
+
event.preventDefault();
|
|
187
|
+
result.invoke?.();
|
|
200
188
|
}
|
|
201
|
-
})
|
|
189
|
+
});
|
|
202
190
|
|
|
203
191
|
// Clear the store's key buffer and pending timeout on dispatcher unmount so
|
|
204
192
|
// the timer cannot fire after the tree is gone.
|
|
205
|
-
useEffect(
|
|
193
|
+
useEffect(
|
|
194
|
+
() => () => {
|
|
195
|
+
commandStore.dispose();
|
|
196
|
+
},
|
|
197
|
+
[commandStore],
|
|
198
|
+
);
|
|
206
199
|
|
|
207
|
-
const sequenceState = useSelector(commandStore.store, (s) => selectSequence(s.context))
|
|
200
|
+
const sequenceState = useSelector(commandStore.store, (s) => selectSequence(s.context));
|
|
208
201
|
|
|
209
202
|
const ctxValue = useMemo<CommandStoreContextValue>(
|
|
210
203
|
() => ({
|
|
211
204
|
commandStore,
|
|
212
|
-
surface: commandStore.rootRecord,
|
|
213
205
|
leaderKey: leader,
|
|
206
|
+
surface: commandStore.rootRecord,
|
|
214
207
|
}),
|
|
215
208
|
[commandStore, leader],
|
|
216
|
-
)
|
|
209
|
+
);
|
|
217
210
|
|
|
218
211
|
return (
|
|
219
212
|
<CommandContext.Provider value={ctxValue}>
|
|
220
213
|
<CommandSequenceContext value={sequenceState}>{children}</CommandSequenceContext>
|
|
221
214
|
</CommandContext.Provider>
|
|
222
|
-
)
|
|
223
|
-
}
|
|
215
|
+
);
|
|
216
|
+
};
|
|
224
217
|
|
|
225
218
|
export interface CommandSurfaceProviderProps {
|
|
226
|
-
children: ReactNode
|
|
219
|
+
children: ReactNode;
|
|
227
220
|
/** Stable id for the surface (typically the overlay id). */
|
|
228
|
-
id: string
|
|
221
|
+
id: string;
|
|
229
222
|
/** Interaction role (default "modal"). */
|
|
230
|
-
role?: CommandSurfaceRole
|
|
223
|
+
role?: CommandSurfaceRole;
|
|
231
224
|
/** Initial local mode for this surface (default "cursor"). */
|
|
232
|
-
initialMode?: Mode
|
|
225
|
+
initialMode?: Mode;
|
|
233
226
|
}
|
|
234
227
|
|
|
235
228
|
/**
|
|
@@ -240,75 +233,75 @@ export interface CommandSurfaceProviderProps {
|
|
|
240
233
|
* While a `modal` surface is topmost it owns keyboard input and suspends the
|
|
241
234
|
* parent app's commands; a `passive` surface never becomes the keyboard owner.
|
|
242
235
|
*/
|
|
243
|
-
export function CommandSurfaceProvider({
|
|
236
|
+
export const CommandSurfaceProvider = function CommandSurfaceProvider({
|
|
244
237
|
children,
|
|
245
238
|
id,
|
|
246
239
|
role = "modal",
|
|
247
240
|
initialMode = "cursor",
|
|
248
|
-
}: CommandSurfaceProviderProps) {
|
|
249
|
-
const parent = useContext(CommandContext)
|
|
241
|
+
}: CommandSurfaceProviderProps): ReactNode {
|
|
242
|
+
const parent = useContext(CommandContext);
|
|
250
243
|
if (!parent) {
|
|
251
|
-
throw new Error("CommandSurfaceProvider must be used within a CommandProvider")
|
|
244
|
+
throw new Error("CommandSurfaceProvider must be used within a CommandProvider");
|
|
252
245
|
}
|
|
253
|
-
const { commandStore } = parent
|
|
246
|
+
const { commandStore } = parent;
|
|
254
247
|
|
|
255
248
|
// Surface-local mode changes are transitions too (F-08): a mid-chord mode
|
|
256
249
|
// switch on a modal surface resets the pending sequence.
|
|
257
|
-
const handleModeChange = useCallback(() =>
|
|
250
|
+
const handleModeChange = useCallback(() => {
|
|
251
|
+
commandStore.modeChanged(id);
|
|
252
|
+
}, [commandStore, id]);
|
|
258
253
|
|
|
259
254
|
return (
|
|
260
255
|
<ModeProvider initialMode={initialMode} onModeChange={handleModeChange}>
|
|
256
|
+
{/* Deferred(lint-sweep): preserve top-down provider/wrapper organization. */}
|
|
257
|
+
{/* oxlint-disable-next-line no-use-before-define -- inner surface is deliberately declared below */}
|
|
261
258
|
<CommandSurfaceInner id={id} role={role}>
|
|
262
259
|
{children}
|
|
260
|
+
{/* oxlint-disable-next-line no-use-before-define -- closing inner surface declaration is below provider */}
|
|
263
261
|
</CommandSurfaceInner>
|
|
264
262
|
</ModeProvider>
|
|
265
|
-
)
|
|
266
|
-
}
|
|
263
|
+
);
|
|
264
|
+
};
|
|
267
265
|
|
|
268
|
-
function CommandSurfaceInner({
|
|
266
|
+
const CommandSurfaceInner = function CommandSurfaceInner({
|
|
269
267
|
children,
|
|
270
268
|
id,
|
|
271
269
|
role,
|
|
272
270
|
}: {
|
|
273
|
-
children: ReactNode
|
|
274
|
-
id: string
|
|
275
|
-
role: CommandSurfaceRole
|
|
276
|
-
}) {
|
|
277
|
-
const parent = useContext(CommandContext)
|
|
271
|
+
children: ReactNode;
|
|
272
|
+
id: string;
|
|
273
|
+
role: CommandSurfaceRole;
|
|
274
|
+
}): ReactNode {
|
|
275
|
+
const parent = useContext(CommandContext);
|
|
278
276
|
if (!parent) {
|
|
279
|
-
throw new Error("CommandSurfaceProvider must be used within a CommandProvider")
|
|
277
|
+
throw new Error("CommandSurfaceProvider must be used within a CommandProvider");
|
|
280
278
|
}
|
|
281
|
-
const { commandStore } = parent
|
|
279
|
+
const { commandStore } = parent;
|
|
282
280
|
|
|
283
|
-
const parentDepth = useContext(CommandSurfaceDepthContext)
|
|
284
|
-
const depth = parentDepth + 1
|
|
281
|
+
const parentDepth = useContext(CommandSurfaceDepthContext);
|
|
282
|
+
const depth = parentDepth + 1;
|
|
285
283
|
|
|
286
|
-
const mode = useMode()
|
|
287
|
-
const setMode = useSetMode()
|
|
288
|
-
const modeRef = useRef(mode)
|
|
289
|
-
modeRef.current = mode
|
|
284
|
+
const mode = useMode();
|
|
285
|
+
const setMode = useSetMode();
|
|
286
|
+
const modeRef = useRef(mode);
|
|
287
|
+
modeRef.current = mode;
|
|
290
288
|
|
|
291
289
|
const buildCtx = useCallback((): CommandContext => {
|
|
292
|
-
|
|
293
|
-
|
|
290
|
+
// Deferred(lint-sweep): replace this lifecycle ref with an API that models render-time initialization.
|
|
291
|
+
// oxlint-disable-next-line typescript/no-non-null-assertion, no-use-before-define -- initialized lifecycle ref intentionally captured by closure
|
|
292
|
+
const registry = commandStore.registryFor(recordRef.current!);
|
|
293
|
+
return buildCommandContext({
|
|
294
|
+
commands: commandsFromRegistry(registry),
|
|
295
|
+
contributions: commandStore.store.getSnapshot().context.contextSources.values(),
|
|
294
296
|
mode: modeRef.current,
|
|
295
297
|
setMode,
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
list: () => Array.from(registry.commands.values()),
|
|
299
|
-
},
|
|
300
|
-
exit: () => {},
|
|
301
|
-
}
|
|
302
|
-
for (const getter of commandStore.store.getSnapshot().context.contextSources.values()) {
|
|
303
|
-
Object.assign(ctx, getter())
|
|
304
|
-
}
|
|
305
|
-
return ctx as CommandContext
|
|
306
|
-
}, [commandStore, setMode])
|
|
298
|
+
});
|
|
299
|
+
}, [commandStore, setMode]);
|
|
307
300
|
|
|
308
|
-
const buildCtxRef = useRef(buildCtx)
|
|
309
|
-
buildCtxRef.current = buildCtx
|
|
301
|
+
const buildCtxRef = useRef(buildCtx);
|
|
302
|
+
buildCtxRef.current = buildCtx;
|
|
310
303
|
|
|
311
|
-
const recordRef = useRef<SurfaceRecord | null>(null)
|
|
304
|
+
const recordRef = useRef<SurfaceRecord | null>(null);
|
|
312
305
|
if (
|
|
313
306
|
recordRef.current === null ||
|
|
314
307
|
recordRef.current.id !== id ||
|
|
@@ -316,28 +309,28 @@ function CommandSurfaceInner({
|
|
|
316
309
|
recordRef.current.depth !== depth
|
|
317
310
|
) {
|
|
318
311
|
recordRef.current = {
|
|
319
|
-
|
|
320
|
-
role,
|
|
312
|
+
buildCtx: () => buildCtxRef.current(),
|
|
321
313
|
depth,
|
|
322
|
-
order: 0,
|
|
323
314
|
getMode: () => modeRef.current,
|
|
324
|
-
|
|
325
|
-
|
|
315
|
+
id,
|
|
316
|
+
order: 0,
|
|
317
|
+
role,
|
|
318
|
+
};
|
|
326
319
|
}
|
|
327
|
-
const record = recordRef.current
|
|
320
|
+
const record = recordRef.current;
|
|
328
321
|
|
|
329
322
|
// Mount/unmount registration is a keep-effect: it synchronizes the React
|
|
330
323
|
// tree with the store's surface stack.
|
|
331
|
-
useEffect(() => commandStore.pushSurface(record), [commandStore, record])
|
|
324
|
+
useEffect(() => commandStore.pushSurface(record), [commandStore, record]);
|
|
332
325
|
|
|
333
326
|
const ctxValue = useMemo<CommandStoreContextValue>(
|
|
334
327
|
() => ({
|
|
335
328
|
commandStore,
|
|
336
|
-
surface: record,
|
|
337
329
|
leaderKey: parent.leaderKey,
|
|
330
|
+
surface: record,
|
|
338
331
|
}),
|
|
339
332
|
[commandStore, record, parent.leaderKey],
|
|
340
|
-
)
|
|
333
|
+
);
|
|
341
334
|
|
|
342
335
|
return (
|
|
343
336
|
<CommandContext.Provider value={ctxValue}>
|
|
@@ -345,45 +338,48 @@ function CommandSurfaceInner({
|
|
|
345
338
|
{children}
|
|
346
339
|
</CommandSurfaceDepthContext.Provider>
|
|
347
340
|
</CommandContext.Provider>
|
|
348
|
-
)
|
|
349
|
-
}
|
|
350
|
-
|
|
351
|
-
export
|
|
352
|
-
|
|
341
|
+
);
|
|
342
|
+
};
|
|
343
|
+
|
|
344
|
+
export const useCommandContext = function useCommandContext(): {
|
|
345
|
+
commands: Command[];
|
|
346
|
+
invoke: (id: string) => void;
|
|
347
|
+
} {
|
|
348
|
+
const ctx = useContext(CommandContext);
|
|
353
349
|
if (!ctx) {
|
|
354
|
-
throw new Error("useCommandContext must be used within a CommandProvider")
|
|
350
|
+
throw new Error("useCommandContext must be used within a CommandProvider");
|
|
355
351
|
}
|
|
356
|
-
const { commandStore, surface } = ctx
|
|
352
|
+
const { commandStore, surface } = ctx;
|
|
357
353
|
|
|
358
354
|
// Reactive: consumers re-render when a command registers or unregisters on
|
|
359
355
|
// this surface (the per-surface map is identity-stable otherwise).
|
|
360
356
|
const commandMap = useSelector(commandStore.store, (s) =>
|
|
361
357
|
selectSurfaceCommandMap(s.context, surface.id),
|
|
362
|
-
)
|
|
363
|
-
const registry = commandStore.registryFor(surface)
|
|
358
|
+
);
|
|
359
|
+
const registry = commandStore.registryFor(surface);
|
|
364
360
|
|
|
365
361
|
return useMemo(
|
|
366
362
|
() => ({
|
|
367
|
-
commands: commandMap ?
|
|
363
|
+
commands: commandMap ? [...commandMap.values()] : [],
|
|
368
364
|
invoke: registry.invoke,
|
|
369
365
|
}),
|
|
370
366
|
[commandMap, registry],
|
|
371
|
-
)
|
|
372
|
-
}
|
|
367
|
+
);
|
|
368
|
+
};
|
|
373
369
|
|
|
374
370
|
/**
|
|
375
371
|
* Builds the live command context of the nearest surface — the same value
|
|
376
372
|
* command handlers receive. For callers that must hand a context to something
|
|
377
373
|
* outside the dispatch path (e.g. a context-menu entry resolver).
|
|
378
374
|
*/
|
|
379
|
-
export function useBuildCommandContext(): () => CommandContext {
|
|
380
|
-
const ctx = useContext(CommandContext)
|
|
375
|
+
export const useBuildCommandContext = function useBuildCommandContext(): () => CommandContext {
|
|
376
|
+
const ctx = useContext(CommandContext);
|
|
381
377
|
if (!ctx) {
|
|
382
|
-
throw new Error("useBuildCommandContext must be used within a CommandProvider")
|
|
378
|
+
throw new Error("useBuildCommandContext must be used within a CommandProvider");
|
|
383
379
|
}
|
|
384
|
-
const { surface } = ctx
|
|
385
|
-
return useCallback(() => surface.buildCtx(), [surface])
|
|
386
|
-
}
|
|
380
|
+
const { surface } = ctx;
|
|
381
|
+
return useCallback(() => surface.buildCtx(), [surface]);
|
|
382
|
+
};
|
|
387
383
|
|
|
388
384
|
/**
|
|
389
385
|
* Internal: the stable registry facade for the nearest surface, without
|
|
@@ -391,41 +387,46 @@ export function useBuildCommandContext(): () => CommandContext {
|
|
|
391
387
|
* only need the facade; subscribing them would re-render every command host
|
|
392
388
|
* on unrelated group/context-source registrations.
|
|
393
389
|
*/
|
|
394
|
-
export function useSurfaceRegistry(): CommandRegistry {
|
|
395
|
-
const ctx = useContext(CommandContext)
|
|
390
|
+
export const useSurfaceRegistry = function useSurfaceRegistry(): CommandRegistry {
|
|
391
|
+
const ctx = useContext(CommandContext);
|
|
396
392
|
if (!ctx) {
|
|
397
|
-
throw new Error("useCommandRegistry must be used within a CommandProvider")
|
|
393
|
+
throw new Error("useCommandRegistry must be used within a CommandProvider");
|
|
398
394
|
}
|
|
399
|
-
return ctx.commandStore.registryFor(ctx.surface)
|
|
400
|
-
}
|
|
395
|
+
return ctx.commandStore.registryFor(ctx.surface);
|
|
396
|
+
};
|
|
401
397
|
|
|
402
|
-
export function useCommandRegistry(): CommandContextValue {
|
|
403
|
-
const ctx = useContext(CommandContext)
|
|
398
|
+
export const useCommandRegistry = function useCommandRegistry(): CommandContextValue {
|
|
399
|
+
const ctx = useContext(CommandContext);
|
|
404
400
|
if (!ctx) {
|
|
405
|
-
throw new Error("useCommandRegistry must be used within a CommandProvider")
|
|
401
|
+
throw new Error("useCommandRegistry must be used within a CommandProvider");
|
|
406
402
|
}
|
|
407
|
-
const { commandStore, surface, leaderKey } = ctx
|
|
403
|
+
const { commandStore, surface, leaderKey } = ctx;
|
|
408
404
|
|
|
409
405
|
// Subscribe to the slices so captured maps stay current across renders (the
|
|
410
406
|
// maps are immutable snapshots now, not shared mutable maps).
|
|
411
|
-
const groups = useSelector(commandStore.store, (s) => s.context.groups)
|
|
412
|
-
const contextSources = useSelector(commandStore.store, (s) => s.context.contextSources)
|
|
413
|
-
const registry = commandStore.registryFor(surface)
|
|
407
|
+
const groups = useSelector(commandStore.store, (s) => s.context.groups);
|
|
408
|
+
const contextSources = useSelector(commandStore.store, (s) => s.context.contextSources);
|
|
409
|
+
const registry = commandStore.registryFor(surface);
|
|
414
410
|
|
|
415
411
|
return useMemo(
|
|
416
412
|
() => ({
|
|
417
|
-
registry
|
|
418
|
-
|
|
413
|
+
// Deferred(lint-sweep): expose readonly store maps through an immutable registry API.
|
|
414
|
+
// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- compatibility facade preserves the existing mutable Map API
|
|
419
415
|
contextSources: contextSources as Map<string, ContextGetter>,
|
|
416
|
+
// Deferred(lint-sweep): expose readonly store maps through an immutable registry API.
|
|
417
|
+
// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- compatibility facade preserves the existing mutable Map API
|
|
420
418
|
groups: groups as Map<string, RegisteredCommandGroup>,
|
|
419
|
+
leaderKey,
|
|
420
|
+
registry,
|
|
421
421
|
}),
|
|
422
422
|
[registry, leaderKey, contextSources, groups],
|
|
423
|
-
)
|
|
424
|
-
}
|
|
423
|
+
);
|
|
424
|
+
};
|
|
425
425
|
|
|
426
|
-
export
|
|
427
|
-
|
|
428
|
-
|
|
426
|
+
export const useCommandSequenceState =
|
|
427
|
+
function useCommandSequenceState(): CommandSequenceState | null {
|
|
428
|
+
return useContext(CommandSequenceContext);
|
|
429
|
+
};
|
|
429
430
|
|
|
430
431
|
/**
|
|
431
432
|
* Id of the command surface this subtree registers commands to: the nearest
|
|
@@ -433,89 +434,96 @@ export function useCommandSequenceState(): CommandSequenceState | null {
|
|
|
433
434
|
* root. Compare against `useActiveCommandSurface()` to tell whether another
|
|
434
435
|
* modal surface currently owns keyboard input above this subtree.
|
|
435
436
|
*/
|
|
436
|
-
export function useCommandSurfaceId(): string {
|
|
437
|
-
const ctx = useContext(CommandContext)
|
|
437
|
+
export const useCommandSurfaceId = function useCommandSurfaceId(): string {
|
|
438
|
+
const ctx = useContext(CommandContext);
|
|
438
439
|
if (!ctx) {
|
|
439
|
-
throw new Error("useCommandSurfaceId must be used within a CommandProvider")
|
|
440
|
+
throw new Error("useCommandSurfaceId must be used within a CommandProvider");
|
|
440
441
|
}
|
|
441
|
-
return ctx.surface.id
|
|
442
|
-
}
|
|
442
|
+
return ctx.surface.id;
|
|
443
|
+
};
|
|
443
444
|
|
|
444
445
|
/**
|
|
445
446
|
* Metadata for the topmost modal command surface, or null when the root app is
|
|
446
447
|
* the active surface. Intended for which-key/help to read shortcuts from the
|
|
447
448
|
* active interaction surface. `commands` is reactive (F-13).
|
|
448
449
|
*/
|
|
449
|
-
export
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
const
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
450
|
+
export const useActiveCommandSurface =
|
|
451
|
+
function useActiveCommandSurface(): ActiveCommandSurface | null {
|
|
452
|
+
const ctx = useContext(CommandContext);
|
|
453
|
+
const { store } = ctx?.commandStore ?? FALLBACK_COMMAND_STORE;
|
|
454
|
+
|
|
455
|
+
const record = useSelector(store, (s) => selectActiveModalSurface(s.context));
|
|
456
|
+
const commandMap = useSelector(store, (s) => {
|
|
457
|
+
const active = selectActiveModalSurface(s.context);
|
|
458
|
+
return active ? selectSurfaceCommandMap(s.context, active.id) : undefined;
|
|
459
|
+
});
|
|
460
|
+
|
|
461
|
+
return useMemo(() => {
|
|
462
|
+
if (!record) {
|
|
463
|
+
return null;
|
|
464
|
+
}
|
|
465
|
+
return {
|
|
466
|
+
commands: commandMap ? [...commandMap.values()] : [],
|
|
467
|
+
id: record.id,
|
|
468
|
+
// Deferred(lint-sweep): model selector records with the public surface-role type.
|
|
469
|
+
// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- selector record is trusted store data
|
|
470
|
+
role: record.role as CommandSurfaceRole,
|
|
471
|
+
};
|
|
472
|
+
}, [record, commandMap]);
|
|
473
|
+
};
|
|
468
474
|
|
|
469
475
|
/**
|
|
470
476
|
* Commands registered on a surface (reactive). Defaults to the active modal
|
|
471
477
|
* surface, falling back to the root surface when none is active.
|
|
472
478
|
*/
|
|
473
|
-
export
|
|
474
|
-
|
|
475
|
-
|
|
479
|
+
export const useSurfaceCommands = function useSurfaceCommands(
|
|
480
|
+
surfaceId?: string,
|
|
481
|
+
): readonly Command[] {
|
|
482
|
+
const ctx = useContext(CommandContext);
|
|
483
|
+
const { store } = ctx?.commandStore ?? FALLBACK_COMMAND_STORE;
|
|
476
484
|
|
|
477
485
|
const commandMap = useSelector(store, (s) => {
|
|
478
|
-
const id = surfaceId ?? selectActiveModalSurface(s.context)?.id ?? ROOT_SURFACE_ID
|
|
479
|
-
return selectSurfaceCommandMap(s.context, id)
|
|
480
|
-
})
|
|
486
|
+
const id = surfaceId ?? selectActiveModalSurface(s.context)?.id ?? ROOT_SURFACE_ID;
|
|
487
|
+
return selectSurfaceCommandMap(s.context, id);
|
|
488
|
+
});
|
|
481
489
|
|
|
482
|
-
return useMemo(() => (commandMap ?
|
|
483
|
-
}
|
|
490
|
+
return useMemo(() => (commandMap ? [...commandMap.values()] : []), [commandMap]);
|
|
491
|
+
};
|
|
484
492
|
|
|
485
493
|
/**
|
|
486
494
|
* Advanced/internal — subject to change. The command store instance backing
|
|
487
495
|
* this provider tree, for bridges that must reach the dispatch machinery
|
|
488
496
|
* (e.g. the shell's overlay-replacement sequence reset).
|
|
489
497
|
*/
|
|
490
|
-
export function useCommandStore(): CommandStore {
|
|
491
|
-
const ctx = useContext(CommandContext)
|
|
498
|
+
export const useCommandStore = function useCommandStore(): CommandStore {
|
|
499
|
+
const ctx = useContext(CommandContext);
|
|
492
500
|
if (!ctx) {
|
|
493
|
-
throw new Error("useCommandStore must be used within a CommandProvider")
|
|
501
|
+
throw new Error("useCommandStore must be used within a CommandProvider");
|
|
494
502
|
}
|
|
495
|
-
return ctx.commandStore
|
|
496
|
-
}
|
|
503
|
+
return ctx.commandStore;
|
|
504
|
+
};
|
|
497
505
|
|
|
498
|
-
export function useCommandGroup(group: CommandGroup): void {
|
|
499
|
-
const ctx = useContext(CommandContext)
|
|
506
|
+
export const useCommandGroup = function useCommandGroup(group: CommandGroup): void {
|
|
507
|
+
const ctx = useContext(CommandContext);
|
|
500
508
|
if (!ctx) {
|
|
501
|
-
throw new Error("useCommandGroup must be used within a CommandProvider")
|
|
509
|
+
throw new Error("useCommandGroup must be used within a CommandProvider");
|
|
502
510
|
}
|
|
503
511
|
|
|
504
|
-
const groupRef = useRef(group)
|
|
505
|
-
groupRef.current = group
|
|
506
|
-
const { commandStore, leaderKey } = ctx
|
|
512
|
+
const groupRef = useRef(group);
|
|
513
|
+
groupRef.current = group;
|
|
514
|
+
const { commandStore, leaderKey } = ctx;
|
|
507
515
|
|
|
508
516
|
useEffect(() => {
|
|
509
|
-
const parsed = parseHotkey(groupRef.current.prefix, leaderKey)
|
|
517
|
+
const parsed = parseHotkey(groupRef.current.prefix, leaderKey);
|
|
510
518
|
const registered: RegisteredCommandGroup = {
|
|
511
519
|
...groupRef.current,
|
|
512
520
|
prefixKey: stepsKey(parsed.steps),
|
|
513
|
-
}
|
|
514
|
-
commandStore.store.trigger.groupRegistered({ group: registered })
|
|
521
|
+
};
|
|
522
|
+
commandStore.store.trigger.groupRegistered({ group: registered });
|
|
515
523
|
return () => {
|
|
516
524
|
// Unregistration is identity-guarded in the store transition (R-05).
|
|
517
|
-
commandStore.store.trigger.groupUnregistered({ group: registered })
|
|
518
|
-
}
|
|
525
|
+
commandStore.store.trigger.groupUnregistered({ group: registered });
|
|
526
|
+
};
|
|
519
527
|
}, [
|
|
520
528
|
group.id,
|
|
521
529
|
group.prefix,
|
|
@@ -525,42 +533,48 @@ export function useCommandGroup(group: CommandGroup): void {
|
|
|
525
533
|
group.order,
|
|
526
534
|
commandStore,
|
|
527
535
|
leaderKey,
|
|
528
|
-
])
|
|
529
|
-
}
|
|
536
|
+
]);
|
|
537
|
+
};
|
|
530
538
|
|
|
531
|
-
let nextContextSourceId = 0
|
|
539
|
+
let nextContextSourceId = 0;
|
|
532
540
|
|
|
533
|
-
export
|
|
534
|
-
|
|
541
|
+
export const useProvideCommandContext = function useProvideCommandContext(
|
|
542
|
+
getter: () => Partial<CommandContext>,
|
|
543
|
+
): void {
|
|
544
|
+
const ctx = useContext(CommandContext);
|
|
535
545
|
if (!ctx) {
|
|
536
|
-
throw new Error("useProvideCommandContext must be used within a CommandProvider")
|
|
546
|
+
throw new Error("useProvideCommandContext must be used within a CommandProvider");
|
|
537
547
|
}
|
|
538
548
|
|
|
539
|
-
const idRef = useRef<string | null>(null)
|
|
549
|
+
const idRef = useRef<string | null>(null);
|
|
540
550
|
if (idRef.current === null) {
|
|
541
|
-
idRef.current = `ctx-${nextContextSourceId
|
|
551
|
+
idRef.current = `ctx-${nextContextSourceId}`;
|
|
552
|
+
nextContextSourceId += 1;
|
|
542
553
|
}
|
|
543
554
|
|
|
544
|
-
const getterRef = useRef(getter)
|
|
545
|
-
getterRef.current = getter
|
|
555
|
+
const getterRef = useRef(getter);
|
|
556
|
+
getterRef.current = getter;
|
|
546
557
|
|
|
547
|
-
const { commandStore } = ctx
|
|
558
|
+
const { commandStore } = ctx;
|
|
548
559
|
|
|
549
560
|
useEffect(() => {
|
|
550
|
-
|
|
561
|
+
// Deferred(lint-sweep): replace nullable ref bookkeeping with an API that returns the initialized id.
|
|
562
|
+
// oxlint-disable-next-line typescript/no-non-null-assertion -- idRef is initialized in the render immediately above
|
|
563
|
+
const id = idRef.current!;
|
|
551
564
|
commandStore.store.trigger.contextSourceRegistered({
|
|
552
|
-
id,
|
|
553
565
|
getter: () => getterRef.current(),
|
|
554
|
-
|
|
566
|
+
id,
|
|
567
|
+
});
|
|
555
568
|
return () => {
|
|
556
|
-
commandStore.store.trigger.contextSourceUnregistered({ id })
|
|
557
|
-
}
|
|
558
|
-
}, [commandStore])
|
|
559
|
-
}
|
|
560
|
-
|
|
561
|
-
export
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
):
|
|
565
|
-
|
|
566
|
-
}
|
|
569
|
+
commandStore.store.trigger.contextSourceUnregistered({ id });
|
|
570
|
+
};
|
|
571
|
+
}, [commandStore]);
|
|
572
|
+
};
|
|
573
|
+
|
|
574
|
+
export const useProvideCommandContextKey = function useProvideCommandContextKey<
|
|
575
|
+
K extends keyof CommandContext,
|
|
576
|
+
>(key: K, getter: () => CommandContext[K]): void {
|
|
577
|
+
// Deferred(lint-sweep): provide a typed augmentation builder instead of asserting computed keys.
|
|
578
|
+
// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- computed key is constrained by K
|
|
579
|
+
useProvideCommandContext(() => ({ [key]: getter() }));
|
|
580
|
+
};
|