@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.
Files changed (54) hide show
  1. package/README.md +5 -5
  2. package/dist/build-context.d.ts +32 -0
  3. package/dist/build-context.d.ts.map +1 -0
  4. package/dist/build-context.js +44 -0
  5. package/dist/build-context.js.map +1 -0
  6. package/dist/command-store.d.ts +19 -19
  7. package/dist/command-store.d.ts.map +1 -1
  8. package/dist/command-store.js +191 -148
  9. package/dist/command-store.js.map +1 -1
  10. package/dist/context.d.ts +16 -16
  11. package/dist/context.d.ts.map +1 -1
  12. package/dist/context.js +112 -107
  13. package/dist/context.js.map +1 -1
  14. package/dist/index.d.ts +1 -1
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/match.d.ts +1 -1
  18. package/dist/match.d.ts.map +1 -1
  19. package/dist/match.js +14 -8
  20. package/dist/match.js.map +1 -1
  21. package/dist/mode.d.ts +4 -4
  22. package/dist/mode.d.ts.map +1 -1
  23. package/dist/mode.js +14 -14
  24. package/dist/mode.js.map +1 -1
  25. package/dist/parse.d.ts +1 -1
  26. package/dist/parse.d.ts.map +1 -1
  27. package/dist/parse.js +19 -18
  28. package/dist/parse.js.map +1 -1
  29. package/dist/sequence.d.ts +6 -5
  30. package/dist/sequence.d.ts.map +1 -1
  31. package/dist/sequence.js +31 -20
  32. package/dist/sequence.js.map +1 -1
  33. package/dist/types.d.ts +18 -10
  34. package/dist/types.d.ts.map +1 -1
  35. package/dist/use-actions.d.ts +1 -1
  36. package/dist/use-actions.d.ts.map +1 -1
  37. package/dist/use-actions.js +22 -12
  38. package/dist/use-actions.js.map +1 -1
  39. package/dist/use-command.d.ts +1 -1
  40. package/dist/use-command.d.ts.map +1 -1
  41. package/dist/use-command.js +21 -12
  42. package/dist/use-command.js.map +1 -1
  43. package/package.json +1 -1
  44. package/src/build-context.ts +65 -0
  45. package/src/command-store.ts +366 -290
  46. package/src/context.tsx +298 -284
  47. package/src/index.ts +17 -16
  48. package/src/match.ts +23 -11
  49. package/src/mode.tsx +37 -41
  50. package/src/parse.ts +48 -46
  51. package/src/sequence.ts +88 -66
  52. package/src/types.ts +69 -57
  53. package/src/use-actions.ts +46 -35
  54. package/src/use-command.ts +44 -33
package/src/context.tsx CHANGED
@@ -1,14 +1,7 @@
1
- import {
2
- createContext,
3
- useContext,
4
- useRef,
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
- type CommandStore,
33
- type ContextGetter,
34
- type SurfaceRecord,
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
- getMode: () => Mode
86
- buildCtx: () => CommandContext
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
- mode: initialMode ?? "cursor",
106
- setMode: () => {},
107
- commands: { invoke: () => {}, list: () => [] },
108
- exit: () => {},
109
- }) as unknown as CommandContext,
110
- })
111
-
112
- const storeRef = useRef<CommandStore | null>(null)
113
- if (storeRef.current === null) {
114
- storeRef.current = createCommandStore({
115
- leader,
116
- keymap,
117
- sequenceTimeoutMs,
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
- () => commandStore.modeChanged(ROOT_SURFACE_ID),
130
- [commandStore],
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
- function CommandDispatcher({
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((): CommandContext => {
169
- const registry = commandStore.registryFor(commandStore.rootRecord)
170
- const ctx: Record<string, any> = {
171
- mode: modeRef.current,
172
- setMode,
173
- commands: {
174
- invoke: (id: string) => registry.invoke(id),
175
- list: () => Array.from(registry.commands.values()),
176
- },
177
- exit: () => {},
178
- }
179
- for (const getter of commandStore.store.getSnapshot().context.contextSources.values()) {
180
- Object.assign(ctx, getter())
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({ leader, keymap, sequenceTimeoutMs })
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) return
196
- const result = commandStore.key(event)
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(() => () => commandStore.dispose(), [commandStore])
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(() => commandStore.modeChanged(id), [commandStore, id])
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
- const registry = commandStore.registryFor(recordRef.current!)
293
- const ctx: Record<string, any> = {
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
- commands: {
297
- invoke: (cmdId: string) => registry.invoke(cmdId),
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
- id,
320
- role,
312
+ buildCtx: () => buildCtxRef.current(),
321
313
  depth,
322
- order: 0,
323
314
  getMode: () => modeRef.current,
324
- buildCtx: () => buildCtxRef.current(),
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 function useCommandContext(): { commands: Command[]; invoke: (id: string) => void } {
352
- const ctx = useContext(CommandContext)
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 ? Array.from(commandMap.values()) : [],
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
- leaderKey,
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 function useCommandSequenceState(): CommandSequenceState | null {
427
- return useContext(CommandSequenceContext)
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 function useActiveCommandSurface(): ActiveCommandSurface | null {
450
- const ctx = useContext(CommandContext)
451
- const store = (ctx?.commandStore ?? FALLBACK_COMMAND_STORE).store
452
-
453
- const record = useSelector(store, (s) => selectActiveModalSurface(s.context))
454
- const commandMap = useSelector(store, (s) => {
455
- const active = selectActiveModalSurface(s.context)
456
- return active ? selectSurfaceCommandMap(s.context, active.id) : undefined
457
- })
458
-
459
- return useMemo(() => {
460
- if (!record) return null
461
- return {
462
- id: record.id,
463
- role: record.role as CommandSurfaceRole,
464
- commands: commandMap ? Array.from(commandMap.values()) : [],
465
- }
466
- }, [record, commandMap])
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 function useSurfaceCommands(surfaceId?: string): readonly Command[] {
474
- const ctx = useContext(CommandContext)
475
- const store = (ctx?.commandStore ?? FALLBACK_COMMAND_STORE).store
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 ? Array.from(commandMap.values()) : []), [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 function useProvideCommandContext(getter: () => Partial<CommandContext>): void {
534
- const ctx = useContext(CommandContext)
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
- const id = idRef.current!
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 function useProvideCommandContextKey<K extends keyof CommandContext>(
562
- key: K,
563
- getter: () => CommandContext[K],
564
- ): void {
565
- useProvideCommandContext(() => ({ [key]: getter() }) as Pick<CommandContext, K>)
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
+ };