@tooee/commands 0.7.3 → 0.9.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 +26 -1
- package/dist/build-context.d.ts +3 -12
- package/dist/build-context.d.ts.map +1 -1
- package/dist/build-context.js +6 -17
- package/dist/build-context.js.map +1 -1
- package/dist/command-store-wrapper.d.ts +28 -0
- package/dist/command-store-wrapper.d.ts.map +1 -0
- package/dist/command-store-wrapper.js +115 -0
- package/dist/command-store-wrapper.js.map +1 -0
- package/dist/command-store.d.ts +2 -65
- package/dist/command-store.d.ts.map +1 -1
- package/dist/command-store.js +1 -345
- package/dist/command-store.js.map +1 -1
- package/dist/context.d.ts +5 -4
- package/dist/context.d.ts.map +1 -1
- package/dist/context.js +55 -50
- package/dist/context.js.map +1 -1
- package/dist/hooks/use-latest.d.ts +4 -0
- package/dist/hooks/use-latest.d.ts.map +1 -0
- package/dist/hooks/use-latest.js +8 -0
- package/dist/hooks/use-latest.js.map +1 -0
- package/dist/hooks/use-lazy-ref.d.ts +4 -0
- package/dist/hooks/use-lazy-ref.d.ts.map +1 -0
- package/dist/hooks/use-lazy-ref.js +8 -0
- package/dist/hooks/use-lazy-ref.js.map +1 -0
- package/dist/index.d.ts +7 -7
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -4
- package/dist/index.js.map +1 -1
- package/dist/key-dispatch.d.ts +24 -0
- package/dist/key-dispatch.d.ts.map +1 -0
- package/dist/key-dispatch.js +159 -0
- package/dist/key-dispatch.js.map +1 -0
- package/dist/parse.js +10 -10
- package/dist/parse.js.map +1 -1
- package/dist/public-contract.typecheck.d.ts +2 -0
- package/dist/public-contract.typecheck.d.ts.map +1 -0
- package/dist/public-contract.typecheck.js +7 -0
- package/dist/public-contract.typecheck.js.map +1 -0
- package/dist/store.d.ts +9 -0
- package/dist/store.d.ts.map +1 -0
- package/dist/store.js +5 -0
- package/dist/store.js.map +1 -0
- package/dist/types.d.ts +6 -5
- package/dist/types.d.ts.map +1 -1
- package/dist/use-actions.d.ts.map +1 -1
- package/dist/use-actions.js +3 -1
- package/dist/use-actions.js.map +1 -1
- package/dist/use-command.d.ts.map +1 -1
- package/dist/use-command.js +3 -1
- package/dist/use-command.js.map +1 -1
- package/package.json +8 -1
- package/src/build-context.ts +7 -18
- package/src/command-store-wrapper.ts +149 -0
- package/src/command-store.ts +1 -491
- package/src/context.tsx +73 -65
- package/src/hooks/use-latest.ts +9 -0
- package/src/hooks/use-lazy-ref.ts +9 -0
- package/src/index.ts +7 -22
- package/src/key-dispatch.ts +272 -0
- package/src/parse.ts +10 -10
- package/src/public-contract.typecheck.ts +7 -0
- package/src/store.ts +12 -0
- package/src/types.ts +6 -5
- package/src/use-actions.ts +3 -1
- package/src/use-command.ts +3 -1
package/src/context.tsx
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { createContext, useContext,
|
|
1
|
+
import { createContext, useContext, useCallback, useEffect, useMemo } from "react";
|
|
2
2
|
import type { ReactNode } from "react";
|
|
3
3
|
import { useKeyboard } from "@opentui/react";
|
|
4
4
|
import { useSelector } from "@xstate/store-react";
|
|
@@ -17,21 +17,24 @@ import { ModeProvider, useMode, useSetMode } from "./mode.js";
|
|
|
17
17
|
import { parseHotkey } from "./parse.js";
|
|
18
18
|
import {
|
|
19
19
|
ROOT_SURFACE_ID,
|
|
20
|
-
createCommandStore,
|
|
21
20
|
selectActivePanelSurface,
|
|
22
21
|
selectKeyboardOwnerSurface,
|
|
23
22
|
selectSequence,
|
|
24
23
|
selectSurfaceCommandMap,
|
|
25
24
|
stepsKey,
|
|
26
25
|
} from "./command-store.js";
|
|
27
|
-
import type {
|
|
26
|
+
import type { ContextGetter, SurfaceRecord } from "./command-store.js";
|
|
27
|
+
import { createCommandStore } from "./command-store-wrapper.js";
|
|
28
|
+
import type { CommandStore } from "./command-store-wrapper.js";
|
|
28
29
|
import { buildCommandContext, commandsFromRegistry } from "./build-context.js";
|
|
30
|
+
import { useLatest } from "./hooks/use-latest.js";
|
|
31
|
+
import { useLazyRef } from "./hooks/use-lazy-ref.js";
|
|
29
32
|
|
|
30
33
|
interface CommandContextValue {
|
|
31
34
|
registry: CommandRegistry;
|
|
32
35
|
leaderKey?: string;
|
|
33
|
-
contextSources:
|
|
34
|
-
groups:
|
|
36
|
+
contextSources: ReadonlyMap<string, ContextGetter>;
|
|
37
|
+
groups: ReadonlyMap<string, RegisteredCommandGroup>;
|
|
35
38
|
}
|
|
36
39
|
|
|
37
40
|
/** Internal provider value: the store plus the surface this subtree registers to. */
|
|
@@ -54,9 +57,16 @@ const CommandSurfaceDepthContext = createContext(0);
|
|
|
54
57
|
*/
|
|
55
58
|
const placeholderCommandContext = function placeholderCommandContext(mode: Mode): CommandContext {
|
|
56
59
|
return buildCommandContext({
|
|
57
|
-
commands: {
|
|
60
|
+
commands: {
|
|
61
|
+
invoke: () => {
|
|
62
|
+
// Placeholder: no dispatcher is mounted yet.
|
|
63
|
+
},
|
|
64
|
+
list: () => [],
|
|
65
|
+
},
|
|
58
66
|
mode,
|
|
59
|
-
setMode: () =>
|
|
67
|
+
setMode: () => {
|
|
68
|
+
// Placeholder: no dispatcher is mounted yet.
|
|
69
|
+
},
|
|
60
70
|
});
|
|
61
71
|
};
|
|
62
72
|
|
|
@@ -94,23 +104,24 @@ export const CommandProvider = function CommandProvider({
|
|
|
94
104
|
// The store is created here (above the root ModeProvider) so mode changes
|
|
95
105
|
// can be routed into it as transitions; the dispatcher below installs the
|
|
96
106
|
// real root accessors before any key can dispatch.
|
|
97
|
-
const rootAccessRef =
|
|
107
|
+
const rootAccessRef = useLazyRef<RootAccess>(() => ({
|
|
98
108
|
// Placeholder until CommandDispatcher installs the real accessors on its
|
|
99
109
|
// first render (before any key can dispatch).
|
|
100
110
|
buildCtx: () => placeholderCommandContext(initialMode ?? "cursor"),
|
|
101
111
|
getMode: () => initialMode ?? "cursor",
|
|
102
|
-
});
|
|
103
|
-
|
|
104
|
-
const storeRef =
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
112
|
+
}));
|
|
113
|
+
|
|
114
|
+
const storeRef = useLazyRef(() =>
|
|
115
|
+
createCommandStore({
|
|
116
|
+
keymap,
|
|
117
|
+
leader,
|
|
118
|
+
root: {
|
|
119
|
+
buildCtx: () => rootAccessRef.current.buildCtx(),
|
|
120
|
+
getMode: () => rootAccessRef.current.getMode(),
|
|
121
|
+
},
|
|
122
|
+
sequenceTimeoutMs,
|
|
123
|
+
}),
|
|
124
|
+
);
|
|
114
125
|
const commandStore = storeRef.current;
|
|
115
126
|
|
|
116
127
|
// Root mode changes are transitions: reset any pending chord synchronously
|
|
@@ -136,7 +147,7 @@ export const CommandProvider = function CommandProvider({
|
|
|
136
147
|
);
|
|
137
148
|
};
|
|
138
149
|
|
|
139
|
-
//
|
|
150
|
+
// preserve the top-down provider/dispatcher organization.
|
|
140
151
|
// oxlint-disable-next-line no-use-before-define -- provider deliberately renders its dispatcher below
|
|
141
152
|
const CommandDispatcher = function CommandDispatcher({
|
|
142
153
|
children,
|
|
@@ -154,8 +165,7 @@ const CommandDispatcher = function CommandDispatcher({
|
|
|
154
165
|
sequenceTimeoutMs?: number;
|
|
155
166
|
}): ReactNode {
|
|
156
167
|
const mode = useMode();
|
|
157
|
-
const modeRef =
|
|
158
|
-
modeRef.current = mode;
|
|
168
|
+
const modeRef = useLatest(mode);
|
|
159
169
|
const setMode = useSetMode();
|
|
160
170
|
|
|
161
171
|
const buildCtx = useCallback(
|
|
@@ -166,11 +176,10 @@ const CommandDispatcher = function CommandDispatcher({
|
|
|
166
176
|
mode: modeRef.current,
|
|
167
177
|
setMode,
|
|
168
178
|
}),
|
|
169
|
-
[commandStore, setMode],
|
|
179
|
+
[commandStore, modeRef, setMode],
|
|
170
180
|
);
|
|
171
181
|
|
|
172
|
-
const buildCtxRef =
|
|
173
|
-
buildCtxRef.current = buildCtx;
|
|
182
|
+
const buildCtxRef = useLatest(buildCtx);
|
|
174
183
|
|
|
175
184
|
// Install the live root accessors and config (ref writes, same pattern as
|
|
176
185
|
// the previous modeRef mirrors; leader/keymap are read per dispatch).
|
|
@@ -261,7 +270,7 @@ export const CommandSurfaceProvider = function CommandSurfaceProvider({
|
|
|
261
270
|
|
|
262
271
|
return (
|
|
263
272
|
<ModeProvider initialMode={initialMode} onModeChange={handleModeChange}>
|
|
264
|
-
{/*
|
|
273
|
+
{/* preserve top-down provider/wrapper organization. */}
|
|
265
274
|
{/* oxlint-disable-next-line no-use-before-define -- inner surface is deliberately declared below */}
|
|
266
275
|
<CommandSurfaceInner id={id} role={role} groupId={groupId}>
|
|
267
276
|
{children}
|
|
@@ -293,27 +302,32 @@ const CommandSurfaceInner = function CommandSurfaceInner({
|
|
|
293
302
|
|
|
294
303
|
const mode = useMode();
|
|
295
304
|
const setMode = useSetMode();
|
|
296
|
-
const modeRef =
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
305
|
+
const modeRef = useLatest(mode);
|
|
306
|
+
|
|
307
|
+
const recordRef = useLazyRef<SurfaceRecord>(() => ({
|
|
308
|
+
// oxlint-disable-next-line no-use-before-define -- buildCtxRef is initialized before this callback can run
|
|
309
|
+
buildCtx: () => buildCtxRef.current(),
|
|
310
|
+
depth,
|
|
311
|
+
getMode: () => modeRef.current,
|
|
312
|
+
groupId,
|
|
313
|
+
id,
|
|
314
|
+
order: 0,
|
|
315
|
+
role,
|
|
316
|
+
}));
|
|
317
|
+
|
|
318
|
+
const buildCtx = (): CommandContext => {
|
|
319
|
+
const registry = commandStore.registryFor(recordRef.current);
|
|
303
320
|
return buildCommandContext({
|
|
304
321
|
commands: commandsFromRegistry(registry),
|
|
305
322
|
contributions: commandStore.store.getSnapshot().context.contextSources.values(),
|
|
306
323
|
mode: modeRef.current,
|
|
307
324
|
setMode,
|
|
308
325
|
});
|
|
309
|
-
}
|
|
326
|
+
};
|
|
310
327
|
|
|
311
|
-
const buildCtxRef =
|
|
312
|
-
buildCtxRef.current = buildCtx;
|
|
328
|
+
const buildCtxRef = useLatest(buildCtx);
|
|
313
329
|
|
|
314
|
-
const recordRef = useRef<SurfaceRecord | null>(null);
|
|
315
330
|
if (
|
|
316
|
-
recordRef.current === null ||
|
|
317
331
|
recordRef.current.id !== id ||
|
|
318
332
|
recordRef.current.role !== role ||
|
|
319
333
|
recordRef.current.depth !== depth ||
|
|
@@ -353,13 +367,13 @@ const CommandSurfaceInner = function CommandSurfaceInner({
|
|
|
353
367
|
);
|
|
354
368
|
};
|
|
355
369
|
|
|
356
|
-
export const
|
|
370
|
+
export const useSurfaceInvoke = function useSurfaceInvoke(): {
|
|
357
371
|
commands: Command[];
|
|
358
372
|
invoke: (id: string) => void;
|
|
359
373
|
} {
|
|
360
374
|
const ctx = useContext(CommandContext);
|
|
361
375
|
if (!ctx) {
|
|
362
|
-
throw new Error("
|
|
376
|
+
throw new Error("useSurfaceInvoke must be used within a CommandProvider");
|
|
363
377
|
}
|
|
364
378
|
const { commandStore, surface } = ctx;
|
|
365
379
|
|
|
@@ -402,7 +416,7 @@ export const useBuildCommandContext = function useBuildCommandContext(): () => C
|
|
|
402
416
|
export const useSurfaceRegistry = function useSurfaceRegistry(): CommandRegistry {
|
|
403
417
|
const ctx = useContext(CommandContext);
|
|
404
418
|
if (!ctx) {
|
|
405
|
-
throw new Error("
|
|
419
|
+
throw new Error("useSurfaceRegistry must be used within a CommandProvider");
|
|
406
420
|
}
|
|
407
421
|
return ctx.commandStore.registryFor(ctx.surface);
|
|
408
422
|
};
|
|
@@ -422,12 +436,8 @@ export const useCommandRegistry = function useCommandRegistry(): CommandContextV
|
|
|
422
436
|
|
|
423
437
|
return useMemo(
|
|
424
438
|
() => ({
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
contextSources: contextSources as Map<string, ContextGetter>,
|
|
428
|
-
// Deferred(lint-sweep): expose readonly store maps through an immutable registry API.
|
|
429
|
-
// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- compatibility facade preserves the existing mutable Map API
|
|
430
|
-
groups: groups as Map<string, RegisteredCommandGroup>,
|
|
439
|
+
contextSources,
|
|
440
|
+
groups,
|
|
431
441
|
leaderKey,
|
|
432
442
|
registry,
|
|
433
443
|
}),
|
|
@@ -473,15 +483,16 @@ export const useActiveCommandSurface =
|
|
|
473
483
|
});
|
|
474
484
|
|
|
475
485
|
return useMemo(() => {
|
|
476
|
-
|
|
486
|
+
// The keyboard owner is always a modal or panel surface: the root record
|
|
487
|
+
// never comes out of `selectKeyboardOwnerSurface`. The guard lets the type
|
|
488
|
+
// say so instead of asserting it.
|
|
489
|
+
if (!record || record.role === "root") {
|
|
477
490
|
return null;
|
|
478
491
|
}
|
|
479
492
|
return {
|
|
480
493
|
commands: commandMap ? [...commandMap.values()] : [],
|
|
481
494
|
id: record.id,
|
|
482
|
-
|
|
483
|
-
// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- selector record is trusted store data
|
|
484
|
-
role: record.role as CommandSurfaceRole,
|
|
495
|
+
role: record.role,
|
|
485
496
|
};
|
|
486
497
|
}, [record, commandMap]);
|
|
487
498
|
};
|
|
@@ -596,8 +607,7 @@ export const useCommandGroup = function useCommandGroup(group: CommandGroup): vo
|
|
|
596
607
|
throw new Error("useCommandGroup must be used within a CommandProvider");
|
|
597
608
|
}
|
|
598
609
|
|
|
599
|
-
const groupRef =
|
|
600
|
-
groupRef.current = group;
|
|
610
|
+
const groupRef = useLatest(group);
|
|
601
611
|
const { commandStore, leaderKey } = ctx;
|
|
602
612
|
|
|
603
613
|
useEffect(() => {
|
|
@@ -618,6 +628,7 @@ export const useCommandGroup = function useCommandGroup(group: CommandGroup): vo
|
|
|
618
628
|
group.description,
|
|
619
629
|
group.icon,
|
|
620
630
|
group.order,
|
|
631
|
+
groupRef,
|
|
621
632
|
commandStore,
|
|
622
633
|
leaderKey,
|
|
623
634
|
]);
|
|
@@ -633,21 +644,18 @@ export const useProvideCommandContext = function useProvideCommandContext(
|
|
|
633
644
|
throw new Error("useProvideCommandContext must be used within a CommandProvider");
|
|
634
645
|
}
|
|
635
646
|
|
|
636
|
-
const idRef =
|
|
637
|
-
|
|
638
|
-
idRef.current = `ctx-${nextContextSourceId}`;
|
|
647
|
+
const idRef = useLazyRef(() => {
|
|
648
|
+
const id = `ctx-${nextContextSourceId}`;
|
|
639
649
|
nextContextSourceId += 1;
|
|
640
|
-
|
|
650
|
+
return id;
|
|
651
|
+
});
|
|
641
652
|
|
|
642
|
-
const getterRef =
|
|
643
|
-
getterRef.current = getter;
|
|
653
|
+
const getterRef = useLatest(getter);
|
|
644
654
|
|
|
645
655
|
const { commandStore } = ctx;
|
|
646
656
|
|
|
647
657
|
useEffect(() => {
|
|
648
|
-
|
|
649
|
-
// oxlint-disable-next-line typescript/no-non-null-assertion -- idRef is initialized in the render immediately above
|
|
650
|
-
const id = idRef.current!;
|
|
658
|
+
const id = idRef.current;
|
|
651
659
|
commandStore.store.trigger.contextSourceRegistered({
|
|
652
660
|
getter: () => getterRef.current(),
|
|
653
661
|
id,
|
|
@@ -655,13 +663,13 @@ export const useProvideCommandContext = function useProvideCommandContext(
|
|
|
655
663
|
return () => {
|
|
656
664
|
commandStore.store.trigger.contextSourceUnregistered({ id });
|
|
657
665
|
};
|
|
658
|
-
}, [commandStore]);
|
|
666
|
+
}, [commandStore, getterRef, idRef]);
|
|
659
667
|
};
|
|
660
668
|
|
|
661
669
|
export const useProvideCommandContextKey = function useProvideCommandContextKey<
|
|
662
670
|
K extends keyof CommandContext,
|
|
663
671
|
>(key: K, getter: () => CommandContext[K]): void {
|
|
664
|
-
//
|
|
672
|
+
// provide a typed augmentation builder instead of asserting computed keys.
|
|
665
673
|
// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- computed key is constrained by K
|
|
666
674
|
useProvideCommandContext(() => ({ [key]: getter() }));
|
|
667
675
|
};
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { useRef } from "react";
|
|
2
|
+
import type { RefObject } from "react";
|
|
3
|
+
|
|
4
|
+
/** Returns a stable ref whose current value is refreshed during every render. */
|
|
5
|
+
export const useLatest = function useLatest<T>(value: T): RefObject<T> {
|
|
6
|
+
const ref = useRef(value);
|
|
7
|
+
ref.current = value;
|
|
8
|
+
return ref;
|
|
9
|
+
};
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
import { useRef } from "react";
|
|
2
|
+
import type { RefObject } from "react";
|
|
3
|
+
|
|
4
|
+
/** Returns a stable ref initialized by calling `init` only on the first render. */
|
|
5
|
+
export const useLazyRef = function useLazyRef<T>(init: () => T): RefObject<T> {
|
|
6
|
+
const container = useRef<RefObject<T> | null>(null);
|
|
7
|
+
container.current ??= { current: init() };
|
|
8
|
+
return container.current;
|
|
9
|
+
};
|
package/src/index.ts
CHANGED
|
@@ -16,25 +16,17 @@ export type {
|
|
|
16
16
|
RegisteredCommandGroup,
|
|
17
17
|
} from "./types.js";
|
|
18
18
|
export type { Mode } from "./mode.js";
|
|
19
|
-
export {
|
|
20
|
-
export type { ModeProviderProps } from "./mode.js";
|
|
19
|
+
export { useMode, useSetMode } from "./mode.js";
|
|
21
20
|
export { parseHotkey } from "./parse.js";
|
|
22
21
|
export { matchStep } from "./match.js";
|
|
23
22
|
export { ScreenScopeProvider, useScreenScope } from "./screen-focus.js";
|
|
24
23
|
export type { ScreenScopeState } from "./screen-focus.js";
|
|
25
|
-
export { DEFAULT_SEQUENCE_TIMEOUT_MS, SequenceTracker } from "./sequence.js";
|
|
26
|
-
export type {
|
|
27
|
-
SequenceFeedResult,
|
|
28
|
-
SequencePendingMatch,
|
|
29
|
-
SequenceTrackerOptions,
|
|
30
|
-
} from "./sequence.js";
|
|
31
24
|
export {
|
|
32
25
|
CommandProvider,
|
|
33
26
|
CommandSurfaceProvider,
|
|
34
27
|
useActiveCommandSurface,
|
|
35
28
|
useEffectiveCommands,
|
|
36
29
|
useBuildCommandContext,
|
|
37
|
-
useCommandContext,
|
|
38
30
|
useCommandGroup,
|
|
39
31
|
useCommandRegistry,
|
|
40
32
|
useCommandSequenceState,
|
|
@@ -43,28 +35,19 @@ export {
|
|
|
43
35
|
useProvideCommandContext,
|
|
44
36
|
useProvideCommandContextKey,
|
|
45
37
|
useSurfaceCommands,
|
|
38
|
+
useSurfaceInvoke,
|
|
46
39
|
} from "./context.js";
|
|
47
40
|
export {
|
|
48
41
|
ROOT_SURFACE_ID,
|
|
49
|
-
|
|
42
|
+
formatStepKey,
|
|
50
43
|
selectActiveModalSurface,
|
|
51
44
|
selectActivePanelSurface,
|
|
52
|
-
selectGroups,
|
|
53
45
|
selectKeyboardOwnerSurface,
|
|
54
46
|
selectSequence,
|
|
55
|
-
selectSurfaceCommandMap,
|
|
56
47
|
selectSurfaceCommands,
|
|
57
48
|
} from "./command-store.js";
|
|
58
|
-
export type {
|
|
59
|
-
|
|
60
|
-
CommandStoreConfig,
|
|
61
|
-
CommandStoreContext,
|
|
62
|
-
CommandStoreInstance,
|
|
63
|
-
ContextGetter,
|
|
64
|
-
CreateCommandStoreOptions,
|
|
65
|
-
KeyDispatchResult,
|
|
66
|
-
SurfaceRecord,
|
|
67
|
-
} from "./command-store.js";
|
|
49
|
+
export type { CommandStoreContext, SurfaceRecord } from "./command-store.js";
|
|
50
|
+
export type { CommandStore, CommandStoreConfig } from "./command-store-wrapper.js";
|
|
68
51
|
export type {
|
|
69
52
|
CommandProviderProps,
|
|
70
53
|
CommandSurfaceProviderProps,
|
|
@@ -74,3 +57,5 @@ export { useCommand } from "./use-command.js";
|
|
|
74
57
|
export type { UseCommandOptions } from "./use-command.js";
|
|
75
58
|
export { useActions } from "./use-actions.js";
|
|
76
59
|
export type { ActionDefinition } from "./use-actions.js";
|
|
60
|
+
export { useLatest } from "./hooks/use-latest.js";
|
|
61
|
+
export { useLazyRef } from "./hooks/use-lazy-ref.js";
|
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
import type { KeyEvent } from "@opentui/core";
|
|
2
|
+
import type { Mode } from "./mode.js";
|
|
3
|
+
import { matchStep } from "./match.js";
|
|
4
|
+
import { parseHotkey } from "./parse.js";
|
|
5
|
+
import {
|
|
6
|
+
ROOT_SURFACE_ID,
|
|
7
|
+
selectActiveModalSurface,
|
|
8
|
+
selectActivePanelSurface,
|
|
9
|
+
stepsKey,
|
|
10
|
+
} from "./command-store.js";
|
|
11
|
+
import type { CommandStoreContext, CommandStoreInstance, SurfaceRecord } from "./command-store.js";
|
|
12
|
+
import {
|
|
13
|
+
DEFAULT_SEQUENCE_TIMEOUT_MS,
|
|
14
|
+
findPendingMatch,
|
|
15
|
+
matchesBuffer,
|
|
16
|
+
pruneBuffer,
|
|
17
|
+
} from "./sequence.js";
|
|
18
|
+
import type { Command, CommandContext, CommandSequenceState, ParsedHotkey } from "./types.js";
|
|
19
|
+
|
|
20
|
+
const DEFAULT_MODES: Mode[] = ["cursor"];
|
|
21
|
+
|
|
22
|
+
export interface KeyDispatchResult {
|
|
23
|
+
handled: boolean;
|
|
24
|
+
invoke?: () => void;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export interface KeyDispatchConfig {
|
|
28
|
+
leader?: string;
|
|
29
|
+
keymap?: Record<string, string>;
|
|
30
|
+
sequenceTimeoutMs?: number;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
interface HotkeyCandidates {
|
|
34
|
+
singleStep: { command: Command; parsed: ParsedHotkey }[];
|
|
35
|
+
multiStep: { command: Command; hotkey: string; parsed: ParsedHotkey }[];
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
type SurfaceDispatch =
|
|
39
|
+
| { outcome: "invoke"; invoke: () => void }
|
|
40
|
+
| { outcome: "pending" }
|
|
41
|
+
| { outcome: "miss" };
|
|
42
|
+
|
|
43
|
+
interface DispatchState {
|
|
44
|
+
buffer: readonly KeyEvent[];
|
|
45
|
+
sequenceOwnerId: string | null;
|
|
46
|
+
timer: ReturnType<typeof setTimeout> | null;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
interface DispatchEnvironment {
|
|
50
|
+
getConfig: () => KeyDispatchConfig;
|
|
51
|
+
rootRecord: SurfaceRecord;
|
|
52
|
+
store: CommandStoreInstance;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
const collectCandidates = function collectCandidates(
|
|
56
|
+
commands: ReadonlyMap<string, Command> | undefined,
|
|
57
|
+
currentMode: Mode,
|
|
58
|
+
cmdCtx: CommandContext,
|
|
59
|
+
config: KeyDispatchConfig,
|
|
60
|
+
getParsedHotkey: (hotkey: string) => ParsedHotkey,
|
|
61
|
+
): HotkeyCandidates {
|
|
62
|
+
const singleStep: HotkeyCandidates["singleStep"] = [];
|
|
63
|
+
const multiStep: HotkeyCandidates["multiStep"] = [];
|
|
64
|
+
|
|
65
|
+
for (const command of commands?.values() ?? []) {
|
|
66
|
+
const commandModes = command.modes ?? DEFAULT_MODES;
|
|
67
|
+
if (!commandModes.includes(currentMode) || (command.when && !command.when(cmdCtx))) {
|
|
68
|
+
continue;
|
|
69
|
+
}
|
|
70
|
+
const hotkey = config.keymap?.[command.id] ?? command.defaultHotkey;
|
|
71
|
+
if (hotkey === undefined || hotkey === "") {
|
|
72
|
+
continue;
|
|
73
|
+
}
|
|
74
|
+
const parsed = getParsedHotkey(hotkey);
|
|
75
|
+
if (parsed.steps.length === 0) {
|
|
76
|
+
continue;
|
|
77
|
+
}
|
|
78
|
+
if (parsed.steps.length === 1) {
|
|
79
|
+
singleStep.push({ command, parsed });
|
|
80
|
+
} else {
|
|
81
|
+
multiStep.push({ command, hotkey, parsed });
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
return { multiStep, singleStep };
|
|
85
|
+
};
|
|
86
|
+
|
|
87
|
+
const runSurface = function runSurface(
|
|
88
|
+
record: SurfaceRecord,
|
|
89
|
+
event: KeyEvent,
|
|
90
|
+
ctx: CommandStoreContext,
|
|
91
|
+
state: DispatchState,
|
|
92
|
+
environment: DispatchEnvironment,
|
|
93
|
+
getParsedHotkey: (hotkey: string) => ParsedHotkey,
|
|
94
|
+
armTimer: () => void,
|
|
95
|
+
clearBufferAndTimer: () => void,
|
|
96
|
+
): SurfaceDispatch {
|
|
97
|
+
const cmdCtx = record.buildCtx();
|
|
98
|
+
const candidates = collectCandidates(
|
|
99
|
+
ctx.commandsBySurface.get(record.id),
|
|
100
|
+
record.getMode(),
|
|
101
|
+
cmdCtx,
|
|
102
|
+
environment.getConfig(),
|
|
103
|
+
getParsedHotkey,
|
|
104
|
+
);
|
|
105
|
+
|
|
106
|
+
if (candidates.multiStep.length > 0) {
|
|
107
|
+
const hotkeys = candidates.multiStep.map((candidate) => candidate.parsed);
|
|
108
|
+
state.buffer = [...state.buffer, event];
|
|
109
|
+
armTimer();
|
|
110
|
+
|
|
111
|
+
const matchedIndex = hotkeys.findIndex((hotkey) => matchesBuffer(state.buffer, hotkey));
|
|
112
|
+
if (matchedIndex !== -1) {
|
|
113
|
+
clearBufferAndTimer();
|
|
114
|
+
environment.store.trigger.sequenceReset();
|
|
115
|
+
const matched = candidates.multiStep[matchedIndex].command;
|
|
116
|
+
return {
|
|
117
|
+
invoke: (): void => {
|
|
118
|
+
void matched.handler(cmdCtx);
|
|
119
|
+
},
|
|
120
|
+
outcome: "invoke",
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
state.buffer = pruneBuffer(state.buffer, hotkeys);
|
|
125
|
+
const pending = findPendingMatch(state.buffer, hotkeys);
|
|
126
|
+
if (pending) {
|
|
127
|
+
const firstCandidate = candidates.multiStep[pending.indexes[0]];
|
|
128
|
+
const sequence: CommandSequenceState = {
|
|
129
|
+
candidates: pending.indexes
|
|
130
|
+
.map((index) => candidates.multiStep[index])
|
|
131
|
+
.filter(({ command }) => command.hidden !== true)
|
|
132
|
+
.map(({ command, hotkey, parsed }) => ({
|
|
133
|
+
command,
|
|
134
|
+
group: ctx.groups.get(stepsKey(parsed.steps.slice(0, pending.prefixLength + 1))),
|
|
135
|
+
hotkey,
|
|
136
|
+
nextStep: parsed.steps[pending.prefixLength],
|
|
137
|
+
remainingSteps: parsed.steps.slice(pending.prefixLength),
|
|
138
|
+
steps: parsed.steps,
|
|
139
|
+
})),
|
|
140
|
+
prefix: firstCandidate.parsed.steps.slice(0, pending.prefixLength),
|
|
141
|
+
};
|
|
142
|
+
environment.store.trigger.sequencePending({ state: sequence });
|
|
143
|
+
return { outcome: "pending" };
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
clearBufferAndTimer();
|
|
147
|
+
environment.store.trigger.sequenceReset();
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
for (const { command, parsed } of candidates.singleStep) {
|
|
151
|
+
if (matchStep(event, parsed.steps[0])) {
|
|
152
|
+
environment.store.trigger.sequenceReset();
|
|
153
|
+
return {
|
|
154
|
+
invoke: (): void => {
|
|
155
|
+
void command.handler(cmdCtx);
|
|
156
|
+
},
|
|
157
|
+
outcome: "invoke",
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
clearBufferAndTimer();
|
|
163
|
+
environment.store.trigger.sequenceReset();
|
|
164
|
+
return { outcome: "miss" };
|
|
165
|
+
};
|
|
166
|
+
|
|
167
|
+
const finishDispatch = function finishDispatch(
|
|
168
|
+
dispatch: SurfaceDispatch,
|
|
169
|
+
ownerId: string,
|
|
170
|
+
state: DispatchState,
|
|
171
|
+
): KeyDispatchResult {
|
|
172
|
+
if (dispatch.outcome === "pending") {
|
|
173
|
+
state.sequenceOwnerId = ownerId;
|
|
174
|
+
return { handled: true };
|
|
175
|
+
}
|
|
176
|
+
state.sequenceOwnerId = null;
|
|
177
|
+
return dispatch.outcome === "invoke"
|
|
178
|
+
? { handled: true, invoke: dispatch.invoke }
|
|
179
|
+
: { handled: false };
|
|
180
|
+
};
|
|
181
|
+
|
|
182
|
+
export interface KeyDispatcher {
|
|
183
|
+
dispose: () => void;
|
|
184
|
+
key: (event: KeyEvent) => KeyDispatchResult;
|
|
185
|
+
reset: () => void;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
export const createKeyDispatcher = function createKeyDispatcher(
|
|
189
|
+
environment: DispatchEnvironment,
|
|
190
|
+
): KeyDispatcher {
|
|
191
|
+
const state: DispatchState = { buffer: [], sequenceOwnerId: null, timer: null };
|
|
192
|
+
const parseCache = new Map<string, ParsedHotkey>();
|
|
193
|
+
|
|
194
|
+
const clearTimer = (): void => {
|
|
195
|
+
if (state.timer !== null) {
|
|
196
|
+
clearTimeout(state.timer);
|
|
197
|
+
state.timer = null;
|
|
198
|
+
}
|
|
199
|
+
};
|
|
200
|
+
const clearBufferAndTimer = (): void => {
|
|
201
|
+
state.buffer = [];
|
|
202
|
+
state.sequenceOwnerId = null;
|
|
203
|
+
clearTimer();
|
|
204
|
+
};
|
|
205
|
+
const reset = (): void => {
|
|
206
|
+
clearBufferAndTimer();
|
|
207
|
+
environment.store.trigger.sequenceReset();
|
|
208
|
+
};
|
|
209
|
+
const armTimer = (): void => {
|
|
210
|
+
clearTimer();
|
|
211
|
+
state.timer = setTimeout(
|
|
212
|
+
reset,
|
|
213
|
+
environment.getConfig().sequenceTimeoutMs ?? DEFAULT_SEQUENCE_TIMEOUT_MS,
|
|
214
|
+
);
|
|
215
|
+
};
|
|
216
|
+
const getParsedHotkey = (hotkey: string): ParsedHotkey => {
|
|
217
|
+
const { leader } = environment.getConfig();
|
|
218
|
+
const cacheKey = `${hotkey}:${leader ?? ""}`;
|
|
219
|
+
let parsed = parseCache.get(cacheKey);
|
|
220
|
+
if (!parsed) {
|
|
221
|
+
parsed = parseHotkey(hotkey, leader);
|
|
222
|
+
parseCache.set(cacheKey, parsed);
|
|
223
|
+
}
|
|
224
|
+
return parsed;
|
|
225
|
+
};
|
|
226
|
+
const dispatchTo = (
|
|
227
|
+
record: SurfaceRecord,
|
|
228
|
+
event: KeyEvent,
|
|
229
|
+
ctx: CommandStoreContext,
|
|
230
|
+
): SurfaceDispatch =>
|
|
231
|
+
runSurface(
|
|
232
|
+
record,
|
|
233
|
+
event,
|
|
234
|
+
ctx,
|
|
235
|
+
state,
|
|
236
|
+
environment,
|
|
237
|
+
getParsedHotkey,
|
|
238
|
+
armTimer,
|
|
239
|
+
clearBufferAndTimer,
|
|
240
|
+
);
|
|
241
|
+
const finish = (dispatch: SurfaceDispatch, ownerId: string): KeyDispatchResult =>
|
|
242
|
+
finishDispatch(dispatch, ownerId, state);
|
|
243
|
+
|
|
244
|
+
const key = (event: KeyEvent): KeyDispatchResult => {
|
|
245
|
+
const ctx = environment.store.getSnapshot().context;
|
|
246
|
+
if (state.buffer.length > 0 && state.sequenceOwnerId !== null) {
|
|
247
|
+
const owner =
|
|
248
|
+
state.sequenceOwnerId === ROOT_SURFACE_ID
|
|
249
|
+
? environment.rootRecord
|
|
250
|
+
: (ctx.surfaces.find((record) => record.id === state.sequenceOwnerId) ?? null);
|
|
251
|
+
if (owner) {
|
|
252
|
+
return finish(dispatchTo(owner, event, ctx), state.sequenceOwnerId);
|
|
253
|
+
}
|
|
254
|
+
clearBufferAndTimer();
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
const modal = selectActiveModalSurface(ctx);
|
|
258
|
+
if (modal) {
|
|
259
|
+
return finish(dispatchTo(modal, event, ctx), modal.id);
|
|
260
|
+
}
|
|
261
|
+
const panel = selectActivePanelSurface(ctx);
|
|
262
|
+
if (panel) {
|
|
263
|
+
const dispatch = dispatchTo(panel, event, ctx);
|
|
264
|
+
if (dispatch.outcome !== "miss" || panel.getMode() === "insert") {
|
|
265
|
+
return finish(dispatch, panel.id);
|
|
266
|
+
}
|
|
267
|
+
}
|
|
268
|
+
return finish(dispatchTo(environment.rootRecord, event, ctx), ROOT_SURFACE_ID);
|
|
269
|
+
};
|
|
270
|
+
|
|
271
|
+
return { dispose: clearBufferAndTimer, key, reset };
|
|
272
|
+
};
|
package/src/parse.ts
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
import type { ParsedHotkey, ParsedStep } from "./types.js";
|
|
2
2
|
|
|
3
|
-
const KEY_ALIASES:
|
|
4
|
-
backspace
|
|
5
|
-
cr
|
|
6
|
-
del
|
|
7
|
-
enter
|
|
8
|
-
esc
|
|
9
|
-
plus
|
|
10
|
-
tab
|
|
11
|
-
|
|
3
|
+
const KEY_ALIASES: ReadonlyMap<string, string> = new Map([
|
|
4
|
+
["backspace", "backspace"],
|
|
5
|
+
["cr", "return"],
|
|
6
|
+
["del", "delete"],
|
|
7
|
+
["enter", "return"],
|
|
8
|
+
["esc", "escape"],
|
|
9
|
+
["plus", "+"],
|
|
10
|
+
["tab", "tab"],
|
|
11
|
+
]);
|
|
12
12
|
|
|
13
13
|
const normalizeKey = function normalizeKey(key: string): string {
|
|
14
14
|
const lower = key.toLowerCase();
|
|
15
|
-
return KEY_ALIASES
|
|
15
|
+
return KEY_ALIASES.get(lower) ?? lower;
|
|
16
16
|
};
|
|
17
17
|
|
|
18
18
|
const warned = new Set<string>();
|