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