@tooee/commands 0.3.2 → 0.4.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.
@@ -0,0 +1,43 @@
1
+ import { createContext, useContext, useMemo } from "react";
2
+ import type { ReactNode } from "react";
3
+
4
+ /**
5
+ * Screen-scope focus: "is my enclosing region live?".
6
+ *
7
+ * This is the shared, router-agnostic half of screen focus. It composes
8
+ * hierarchically (AND with the parent scope) so nested live regions behave
9
+ * sensibly — a panel inside an inactive panel is itself dark. The default is
10
+ * `true` ("no enclosing focus scope"), so a subtree with no scope provider above
11
+ * it is considered live and `@tooee/router`'s `useScreenEffect` runs as before.
12
+ *
13
+ * `@tooee/panels` wraps each panel's children in a `ScreenScopeProvider` keyed on
14
+ * the panel's active state; `@tooee/router` reads this scope and ANDs it with the
15
+ * route-chain leaf flag so effects in an inactive panel pause. Keeping the scope
16
+ * context here (rather than in the router) lets panels compose with route focus
17
+ * without depending on the router package.
18
+ */
19
+ export interface ScreenScopeState {
20
+ isFocused: boolean;
21
+ }
22
+
23
+ const ScreenScopeContext = createContext<ScreenScopeState>({ isFocused: true });
24
+
25
+ export const ScreenScopeProvider = function ScreenScopeProvider({
26
+ active,
27
+ children,
28
+ }: {
29
+ active: boolean;
30
+ children: ReactNode;
31
+ }): ReactNode {
32
+ const parent = useContext(ScreenScopeContext);
33
+ const value = useMemo<ScreenScopeState>(
34
+ () => ({ isFocused: parent.isFocused && active }),
35
+ [parent.isFocused, active],
36
+ );
37
+ return <ScreenScopeContext value={value}>{children}</ScreenScopeContext>;
38
+ };
39
+
40
+ /** The current screen scope (hierarchical AND of all enclosing scopes). */
41
+ export const useScreenScope = function useScreenScope(): ScreenScopeState {
42
+ return useContext(ScreenScopeContext);
43
+ };
package/src/types.ts CHANGED
@@ -75,9 +75,15 @@ export interface CommandRegistry {
75
75
  * Interaction role of a command surface.
76
76
  * - `modal`: owns keyboard input while topmost and suspends every lower surface
77
77
  * (including the root app) — even for keys it does not handle.
78
+ * - `panel`: a peer surface that owns keyboard input only while it is its
79
+ * group's active panel. Unlike `modal`, an active panel does NOT swallow
80
+ * unhandled keys: keys it neither matches nor holds a pending chord for fall
81
+ * through to the enclosing surface (see the command-store arbitration docs).
82
+ * Panel surfaces never win via stack depth/order — only their group's active
83
+ * id selects them.
78
84
  * - `passive`: never becomes the keyboard owner; purely visual.
79
85
  */
80
- export type CommandSurfaceRole = "modal" | "passive";
86
+ export type CommandSurfaceRole = "modal" | "panel" | "passive";
81
87
 
82
88
  /**
83
89
  * A command surface is an interaction surface that can own keyboard input.
@@ -93,6 +99,12 @@ export interface CommandSurfaceEntry {
93
99
  depth: number;
94
100
  /** Monotonic registration order, used to break depth ties. */
95
101
  order: number;
102
+ /**
103
+ * For `panel` surfaces: the id of the panel group this surface belongs to.
104
+ * Arbitration selects a panel surface only when its group's active id equals
105
+ * this surface's id. Unused by other roles.
106
+ */
107
+ groupId?: string;
96
108
  registry: CommandRegistry;
97
109
  /** Reads this surface's current local mode. */
98
110
  getMode: () => Mode;