@tooee/panels 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.
package/README.md ADDED
@@ -0,0 +1,118 @@
1
+ # @tooee/panels
2
+
3
+ First-class panels for Tooee: multiple visible regions with exactly one active,
4
+ each owning its commands, local mode, and optional chrome.
5
+
6
+ Part of the [Tooee](https://github.com/gingerhendrix/tooee) monorepo. See the main repo for documentation.
7
+
8
+ ## Model
9
+
10
+ A `PanelGroup` holds peer `Panel`s among which exactly one is active. The active
11
+ panel owns keyboard input — only its `useCommand`/`useMode` children dispatch —
12
+ and shows the active chrome. Panels stay mounted across switches, so local state,
13
+ panel-local router stacks, and per-panel mode persist. A topmost modal overlay
14
+ still suspends the whole group and returns input to the same panel on close.
15
+
16
+ Panels build on `@tooee/commands`' `"panel"` surface role: the active panel's
17
+ commands dispatch, and keys it does not handle **fall through** to the enclosing
18
+ surface in cursor/select mode, with a panel command **shadowing** a root command
19
+ of the same hotkey while active. Insert-mode panels do not fall through: typed
20
+ characters and Tab stay with the focused editor/input. See the
21
+ [`@tooee/commands` arbitration docs](../commands/README.md#command-surfaces--arbitration).
22
+
23
+ The app supplies layout (flex rows/columns); panels manage activation, command
24
+ ownership, and chrome around it — not resizing or splitting.
25
+
26
+ ## Examples
27
+
28
+ ```tsx
29
+ import { PanelGroup, Panel } from "@tooee/panels";
30
+
31
+ <box flexDirection="row" width="100%" height="100%">
32
+ <PanelGroup defaultActivePanelId="list">
33
+ <Panel id="list" title="Streams" style={{ width: 32 }}>
34
+ <StreamList /> {/* useCommand here dispatches only while "list" is active */}
35
+ </Panel>
36
+ <Panel id="detail" title="Detail" style={{ flexGrow: 1 }}>
37
+ <StreamDetail /> {/* j/k etc. dispatch only while "detail" is active */}
38
+ </Panel>
39
+ </PanelGroup>
40
+ </box>;
41
+ ```
42
+
43
+ Run any example from the repository root:
44
+
45
+ ```bash
46
+ bun examples/panels.tsx
47
+ bun examples/panels-controlled.tsx
48
+ bun examples/panels-custom-chrome.tsx
49
+ bun examples/panels-disabled.tsx
50
+ ```
51
+
52
+ - [`panels.tsx`](../../examples/panels.tsx) — complete composition with
53
+ panel-owned commands, a panel-local router, and a suspending modal.
54
+ - [`panels-controlled.tsx`](../../examples/panels-controlled.tsx) — controlled
55
+ activation, direct selection, and group state through `usePanels()`.
56
+ - [`panels-custom-chrome.tsx`](../../examples/panels-custom-chrome.tsx) —
57
+ `chrome="none"`, app-defined active cues, click activation, and
58
+ `usePanelState()`.
59
+ - [`panels-disabled.tsx`](../../examples/panels-disabled.tsx) — a disabled panel,
60
+ `switchKeys={null}`, and app-owned previous/next commands that skip it.
61
+
62
+ ## `PanelGroup`
63
+
64
+ Renders no box of its own. Owns activation (controlled or uncontrolled), Tab
65
+ cycle order (source order), activation repair, and the switch commands.
66
+
67
+ | Prop | Default | Meaning |
68
+ | ---------------------- | ---------------------------------------- | ------------------------------------------------------------------------------- |
69
+ | `id` | generated | Stable group id (fine to omit for a single group). |
70
+ | `defaultActivePanelId` | first panel | Uncontrolled initial active panel. |
71
+ | `activePanelId` | — | Controlled active panel; `null` explicitly selects none. |
72
+ | `onActivePanelChange` | — | Uncontrolled resolved changes, or controlled activation requests (non-null). |
73
+ | `switchKeys` | `{ next: "tab", previous: "shift+tab" }` | Switch hotkeys; `null` disables built-in switching. |
74
+ | `switchModes` | `["cursor", "select"]` | Modes in which the switch keys are live (so insert-mode `Tab` reaches editors). |
75
+ | `wrap` | `true` | Wrap from last to first. |
76
+ | `activateOnMouseDown` | `true` | Activate a panel on mouse-down (default chrome only). |
77
+
78
+ The `panels.next` / `panels.previous` switch commands register on every panel's
79
+ local command surface. Only the active panel's pair can dispatch or appear in
80
+ the effective palette, so sibling and nested groups cannot overwrite one
81
+ another. Their stable ids remain remappable through `keymap`.
82
+
83
+ Activation repair: when the active panel unmounts or becomes `disabled`, the
84
+ next activatable panel (else the previous, else none) takes over. A controlled
85
+ group is never repaired — a missing/disabled controlled id activates no panel.
86
+ In uncontrolled groups, `onActivePanelChange` reports the initial resolved panel,
87
+ explicit activation, switching, and repair. In controlled groups it reports a
88
+ valid activation request but does not echo prop changes. The callback remains a
89
+ non-null API: empty groups and transitions to no active panel do not emit it;
90
+ read `usePanels().activePanelId` to observe `null`.
91
+
92
+ ## `Panel`
93
+
94
+ | Prop | Default | Meaning |
95
+ | ------------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
96
+ | `id` | — | Stable id; also the panel's command-surface id. |
97
+ | `title` | — | Chrome title (rendered with a `▸` marker + `borderActive` when active); not a palette/which-key heading. |
98
+ | `disabled` | `false` | Excluded from activation/switching; renders disabled chrome, stays mounted. |
99
+ | `initialMode` | `"cursor"` | Initial local mode. |
100
+ | `chrome` | `"border"` | `"border"` renders a themed box; `"none"` renders no chrome (the app draws its own from `usePanelState()`). |
101
+ | `style` | — | Layout props forwarded to the chrome box. |
102
+
103
+ Chrome uses existing theme tokens only (`borderActive` / `border` / `borderSubtle`,
104
+ `textMuted`, `backgroundPanel`) — no new theme keys.
105
+
106
+ ## Hooks
107
+
108
+ - `usePanelState()` — `{ id, title?, isActive, activate }` for the nearest panel.
109
+ - `usePanels()` — `{ panelIds, activePanelId, activate, next, previous }` for the nearest group.
110
+ - `usePanelActive()` — `true` when inside the active panel (or when there is no enclosing panel).
111
+
112
+ ## Router composition
113
+
114
+ Panels do not depend on `@tooee/router`. A router mounted **inside** a panel is
115
+ navigated independently and keeps its stack across switches; effects on a leaf
116
+ inside an inactive panel pause (screen focus is the enclosing panel's activity
117
+ ANDed with the route-chain leaf). A router **outside** the group replaces the
118
+ whole panel composition on navigation.
@@ -0,0 +1,44 @@
1
+ import type { Mode } from "@tooee/commands";
2
+ /**
3
+ * The interface a `PanelGroup` exposes to the `Panel`s and hooks beneath it.
4
+ * `activeId` is the resolved active panel (reactive); `register`/`setDisabled`
5
+ * synchronize a panel's membership and activatable state with the group.
6
+ */
7
+ export interface PanelGroupContextValue {
8
+ groupId: string;
9
+ /** The resolved active panel id, or null when the group has no activatable panel. */
10
+ activeId: string | null;
11
+ /** All registered panel ids in registration (source) order. */
12
+ panelIds: readonly string[];
13
+ /** Activate a panel (ignored if unknown/disabled). */
14
+ activate: (panelId: string) => void;
15
+ /** Activate the next activatable panel (source order; wraps per `wrap`). */
16
+ next: () => void;
17
+ /** Activate the previous activatable panel. */
18
+ previous: () => void;
19
+ /** Register a panel; returns the unregister cleanup. Assigns registration order. */
20
+ register: (panelId: string) => () => void;
21
+ /** Update a panel's disabled (non-activatable) flag. */
22
+ setDisabled: (panelId: string, disabled: boolean) => void;
23
+ /** Whether panels should activate on mouse-down (default chrome only). */
24
+ activateOnMouseDown: boolean;
25
+ /** Whether the built-in next/previous commands are registered on each panel surface. */
26
+ switchEnabled: boolean;
27
+ /** Built-in next-panel hotkey. */
28
+ nextHotkey: string;
29
+ /** Built-in previous-panel hotkey. */
30
+ previousHotkey: string;
31
+ /** Local modes in which the built-in switch commands dispatch. */
32
+ switchModes: Mode[];
33
+ }
34
+ export declare const PanelGroupContext: import("react").Context<PanelGroupContextValue | null>;
35
+ export declare const usePanelGroupContext: () => PanelGroupContextValue;
36
+ export declare const useOptionalPanelGroupContext: () => PanelGroupContextValue | null;
37
+ export interface PanelContextValue {
38
+ id: string;
39
+ title?: string;
40
+ groupId: string;
41
+ }
42
+ export declare const PanelContext: import("react").Context<PanelContextValue | null>;
43
+ export declare const useOptionalPanelContext: () => PanelContextValue | null;
44
+ //# sourceMappingURL=context.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,4EAA4E;IAC5E,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,oFAAoF;IACpF,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,IAAI,CAAC;IAC1C,wDAAwD;IACxD,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAC1D,0EAA0E;IAC1E,mBAAmB,EAAE,OAAO,CAAC;IAC7B,wFAAwF;IACxF,aAAa,EAAE,OAAO,CAAC;IACvB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,WAAW,EAAE,IAAI,EAAE,CAAC;CACrB;AAED,eAAO,MAAM,iBAAiB,wDAAqD,CAAC;AAEpF,eAAO,MAAM,oBAAoB,QAAoC,sBAMpE,CAAC;AAEF,eAAO,MAAM,4BAA4B,QACE,sBAAsB,GAAG,IAEjE,CAAC;AAEJ,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAE1E,eAAO,MAAM,uBAAuB,QACE,iBAAiB,GAAG,IAEvD,CAAC"}
@@ -0,0 +1,17 @@
1
+ import { createContext, useContext } from "react";
2
+ export const PanelGroupContext = createContext(null);
3
+ export const usePanelGroupContext = function usePanelGroupContext() {
4
+ const ctx = useContext(PanelGroupContext);
5
+ if (!ctx) {
6
+ throw new Error("usePanelGroupContext must be used within a PanelGroup");
7
+ }
8
+ return ctx;
9
+ };
10
+ export const useOptionalPanelGroupContext = function useOptionalPanelGroupContext() {
11
+ return useContext(PanelGroupContext);
12
+ };
13
+ export const PanelContext = createContext(null);
14
+ export const useOptionalPanelContext = function useOptionalPanelContext() {
15
+ return useContext(PanelContext);
16
+ };
17
+ //# sourceMappingURL=context.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAoClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAgC,IAAI,CAAC,CAAC;AAEpF,MAAM,CAAC,MAAM,oBAAoB,GAAG,SAAS,oBAAoB;IAC/D,MAAM,GAAG,GAAG,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAC1C,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,4BAA4B,GACvC,SAAS,4BAA4B;IACnC,OAAO,UAAU,CAAC,iBAAiB,CAAC,CAAC;AACvC,CAAC,CAAC;AAQJ,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAA2B,IAAI,CAAC,CAAC;AAE1E,MAAM,CAAC,MAAM,uBAAuB,GAClC,SAAS,uBAAuB;IAC9B,OAAO,UAAU,CAAC,YAAY,CAAC,CAAC;AAClC,CAAC,CAAC"}
@@ -0,0 +1,22 @@
1
+ export interface PanelState {
2
+ id: string;
3
+ title?: string;
4
+ /** Reactive: true while this panel is its group's active panel. */
5
+ isActive: boolean;
6
+ /** Activate this panel. */
7
+ activate: () => void;
8
+ }
9
+ /** State of the nearest enclosing `Panel`. */
10
+ export declare const usePanelState: () => PanelState;
11
+ export interface PanelsControls {
12
+ panelIds: readonly string[];
13
+ activePanelId: string | null;
14
+ activate: (id: string) => void;
15
+ next: () => void;
16
+ previous: () => void;
17
+ }
18
+ /** Group-level access, usable inside or outside panels (nearest group). */
19
+ export declare const usePanels: () => PanelsControls;
20
+ /** Convenience: true when inside the active panel (or when there is no enclosing panel). */
21
+ export declare const usePanelActive: () => boolean;
22
+ //# sourceMappingURL=hooks.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,QAAQ,EAAE,OAAO,CAAC;IAClB,2BAA2B;IAC3B,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,8CAA8C;AAC9C,eAAO,MAAM,aAAa,QAA6B,UAoBtD,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,QAAQ,EAAE,MAAM,IAAI,CAAC;CACtB;AAED,2EAA2E;AAC3E,eAAO,MAAM,SAAS,QAAyB,cAO9C,CAAC;AAEF,4FAA4F;AAC5F,eAAO,MAAM,cAAc,QAA8B,OAOxD,CAAC"}
package/dist/hooks.js ADDED
@@ -0,0 +1,37 @@
1
+ import { useContext, useMemo } from "react";
2
+ import { PanelContext, useOptionalPanelGroupContext, usePanelGroupContext } from "./context.js";
3
+ /** State of the nearest enclosing `Panel`. */
4
+ export const usePanelState = function usePanelState() {
5
+ const panel = useContext(PanelContext);
6
+ const group = usePanelGroupContext();
7
+ if (!panel) {
8
+ throw new Error("usePanelState must be used within a Panel");
9
+ }
10
+ const isActive = group.activeId === panel.id;
11
+ const { activate } = group;
12
+ const { id, title } = panel;
13
+ return useMemo(() => ({
14
+ activate: () => {
15
+ activate(id);
16
+ },
17
+ id,
18
+ isActive,
19
+ title,
20
+ }), [activate, id, title, isActive]);
21
+ };
22
+ /** Group-level access, usable inside or outside panels (nearest group). */
23
+ export const usePanels = function usePanels() {
24
+ const group = usePanelGroupContext();
25
+ const { panelIds, activeId, activate, next, previous } = group;
26
+ return useMemo(() => ({ activate, activePanelId: activeId, next, panelIds, previous }), [panelIds, activeId, activate, next, previous]);
27
+ };
28
+ /** Convenience: true when inside the active panel (or when there is no enclosing panel). */
29
+ export const usePanelActive = function usePanelActive() {
30
+ const panel = useContext(PanelContext);
31
+ const group = useOptionalPanelGroupContext();
32
+ if (!panel || !group) {
33
+ return true;
34
+ }
35
+ return group.activeId === panel.id;
36
+ };
37
+ //# sourceMappingURL=hooks.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,4BAA4B,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAWhG,8CAA8C;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAG,SAAS,aAAa;IACjD,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,oBAAoB,EAAE,CAAC;IACrC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,EAAE,CAAC;IAC7C,MAAM,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAC3B,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC;IAC5B,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC;QACL,QAAQ,EAAE,GAAG,EAAE;YACb,QAAQ,CAAC,EAAE,CAAC,CAAC;QACf,CAAC;QACD,EAAE;QACF,QAAQ;QACR,KAAK;KACN,CAAC,EACF,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC,CAChC,CAAC;AACJ,CAAC,CAAC;AAUF,2EAA2E;AAC3E,MAAM,CAAC,MAAM,SAAS,GAAG,SAAS,SAAS;IACzC,MAAM,KAAK,GAAG,oBAAoB,EAAE,CAAC;IACrC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAC/D,OAAO,OAAO,CACZ,GAAG,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,aAAa,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,EACvE,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,CAC/C,CAAC;AACJ,CAAC,CAAC;AAEF,4FAA4F;AAC5F,MAAM,CAAC,MAAM,cAAc,GAAG,SAAS,cAAc;IACnD,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,4BAA4B,EAAE,CAAC;IAC7C,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,EAAE,CAAC;AACrC,CAAC,CAAC"}
@@ -0,0 +1,7 @@
1
+ export { PanelGroup } from "./panel-group.js";
2
+ export { Panel } from "./panel.js";
3
+ export type { PanelGroupProps, PanelProps, PanelSwitchKeys } from "./types.js";
4
+ export { usePanelState, usePanels, usePanelActive } from "./hooks.js";
5
+ export type { PanelState, PanelsControls } from "./hooks.js";
6
+ export type { PanelGroupContextValue, PanelContextValue } from "./context.js";
7
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACtE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,YAAY,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,4 @@
1
+ export { PanelGroup } from "./panel-group.js";
2
+ export { Panel } from "./panel.js";
3
+ export { usePanelState, usePanels, usePanelActive } from "./hooks.js";
4
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}
@@ -0,0 +1,11 @@
1
+ import type { ReactNode } from "react";
2
+ import type { PanelGroupProps } from "./types.js";
3
+ /**
4
+ * A set of peer panels among which exactly one is active. Renders no box of its
5
+ * own — layout belongs to the app. It owns activation state (controlled or
6
+ * uncontrolled), tracks panel registration order for Tab cycling, repairs
7
+ * activation when the active panel unmounts or is disabled, publishes the active
8
+ * panel to the command store, and registers the switch commands.
9
+ */
10
+ export declare const PanelGroup: ({ id, defaultActivePanelId, activePanelId, onActivePanelChange, switchKeys, switchModes, wrap, activateOnMouseDown, children, }: PanelGroupProps) => ReactNode;
11
+ //# sourceMappingURL=panel-group.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"panel-group.d.ts","sourceRoot":"","sources":["../src/panel-group.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAQvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAWlD;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,oIAUpB,eAAe,KAAG,SAiNpB,CAAC"}
@@ -0,0 +1,186 @@
1
+ import { jsx as _jsx } from "@opentui/react/jsx-runtime";
2
+ import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
3
+ import { useCommandStore } from "@tooee/commands";
4
+ import { PanelGroupContext, useOptionalPanelContext, useOptionalPanelGroupContext, } from "./context.js";
5
+ const DEFAULT_SWITCH_MODES = ["cursor", "select"];
6
+ /**
7
+ * A set of peer panels among which exactly one is active. Renders no box of its
8
+ * own — layout belongs to the app. It owns activation state (controlled or
9
+ * uncontrolled), tracks panel registration order for Tab cycling, repairs
10
+ * activation when the active panel unmounts or is disabled, publishes the active
11
+ * panel to the command store, and registers the switch commands.
12
+ */
13
+ export const PanelGroup = function PanelGroup({ id, defaultActivePanelId, activePanelId, onActivePanelChange, switchKeys, switchModes, wrap, activateOnMouseDown, children, }) {
14
+ const generatedId = useId();
15
+ const groupId = id ?? generatedId;
16
+ const commandStore = useCommandStore();
17
+ const enclosingPanel = useOptionalPanelContext();
18
+ const enclosingGroup = useOptionalPanelGroupContext();
19
+ const isInActiveAncestry = enclosingPanel === null || enclosingGroup?.activeId === enclosingPanel.id;
20
+ const isControlled = activePanelId !== undefined;
21
+ const wrapEnabled = wrap ?? true;
22
+ const [registrations, setRegistrations] = useState([]);
23
+ const orderCounterRef = useRef(0);
24
+ const [uncontrolledActive, setUncontrolledActive] = useState(defaultActivePanelId ?? null);
25
+ // Order of the last resolved active panel, so removal repair can pick the
26
+ // next-in-order (else previous) panel rather than always jumping to the first.
27
+ const lastActiveOrderRef = useRef(-1);
28
+ const register = useCallback((panelId) => {
29
+ const order = orderCounterRef.current;
30
+ orderCounterRef.current += 1;
31
+ setRegistrations((prev) => prev.some((entry) => entry.id === panelId)
32
+ ? prev
33
+ : [...prev, { disabled: false, id: panelId, order }]);
34
+ return () => {
35
+ setRegistrations((prev) => prev.filter((entry) => entry.id !== panelId));
36
+ };
37
+ }, []);
38
+ const setDisabled = useCallback((panelId, disabled) => {
39
+ setRegistrations((prev) => {
40
+ const index = prev.findIndex((entry) => entry.id === panelId);
41
+ if (index === -1 || prev[index].disabled === disabled) {
42
+ return prev;
43
+ }
44
+ const next = [...prev];
45
+ next[index] = { ...next[index], disabled };
46
+ return next;
47
+ });
48
+ }, []);
49
+ const activatable = useMemo(() => registrations.filter((entry) => !entry.disabled).sort((a, b) => a.order - b.order), [registrations]);
50
+ const requestedId = isControlled ? (activePanelId ?? null) : uncontrolledActive;
51
+ // The single source of truth for "which panel is active", derived each render
52
+ // so a Panel's chrome and hooks are never a frame behind their own registration.
53
+ const resolvedId = useMemo(() => {
54
+ if (activatable.length === 0) {
55
+ return null;
56
+ }
57
+ if (requestedId !== null && activatable.some((entry) => entry.id === requestedId)) {
58
+ return requestedId;
59
+ }
60
+ // Controlled means controlled: a missing/disabled controlled id activates no
61
+ // panel (root owns input) rather than silently repairing to a peer.
62
+ if (isControlled) {
63
+ return null;
64
+ }
65
+ const lastOrder = lastActiveOrderRef.current;
66
+ const nextAfter = activatable.find((entry) => entry.order > lastOrder);
67
+ if (nextAfter) {
68
+ return nextAfter.id;
69
+ }
70
+ const previousBefore = [...activatable].toReversed().find((entry) => entry.order < lastOrder);
71
+ return (previousBefore ?? activatable[0]).id;
72
+ }, [activatable, requestedId, isControlled]);
73
+ const activatableRef = useRef(activatable);
74
+ activatableRef.current = activatable;
75
+ const resolvedRef = useRef(resolvedId);
76
+ resolvedRef.current = resolvedId;
77
+ const onActivePanelChangeRef = useRef(onActivePanelChange);
78
+ onActivePanelChangeRef.current = onActivePanelChange;
79
+ // Publish activation to the command store and reconcile derived state.
80
+ const announcedRef = useRef(null);
81
+ useEffect(() => {
82
+ if (resolvedId === null || !isInActiveAncestry) {
83
+ commandStore.removePanelGroup(groupId);
84
+ }
85
+ else {
86
+ commandStore.activatePanel(groupId, resolvedId);
87
+ lastActiveOrderRef.current =
88
+ activatable.find((entry) => entry.id === resolvedId)?.order ?? lastActiveOrderRef.current;
89
+ if (!isControlled && resolvedId !== uncontrolledActive) {
90
+ // Keep the uncontrolled intent in step with a repair so `requestedId`
91
+ // tracks the resolved panel on subsequent renders.
92
+ setUncontrolledActive(resolvedId);
93
+ }
94
+ }
95
+ // Uncontrolled: announce resolved changes (initial select and repair). A
96
+ // controlled group announces from `activate`/`next`/`previous` instead, so
97
+ // the parent is not echoed its own prop change.
98
+ if (!isControlled && resolvedId !== announcedRef.current) {
99
+ announcedRef.current = resolvedId;
100
+ if (resolvedId !== null) {
101
+ onActivePanelChangeRef.current?.(resolvedId);
102
+ }
103
+ }
104
+ }, [
105
+ commandStore,
106
+ groupId,
107
+ resolvedId,
108
+ activatable,
109
+ isControlled,
110
+ uncontrolledActive,
111
+ isInActiveAncestry,
112
+ ]);
113
+ // Forget the group's activation when it unmounts so the store does not keep a
114
+ // stale active id for a group that no longer exists.
115
+ useEffect(() => () => {
116
+ commandStore.removePanelGroup(groupId);
117
+ }, [commandStore, groupId]);
118
+ const activate = useCallback((panelId) => {
119
+ if (!activatableRef.current.some((entry) => entry.id === panelId)) {
120
+ return;
121
+ }
122
+ if (isControlled) {
123
+ onActivePanelChangeRef.current?.(panelId);
124
+ }
125
+ else {
126
+ setUncontrolledActive(panelId);
127
+ }
128
+ }, [isControlled]);
129
+ const step = useCallback((direction) => {
130
+ const list = activatableRef.current;
131
+ if (list.length < 2) {
132
+ return;
133
+ }
134
+ const currentIndex = list.findIndex((entry) => entry.id === resolvedRef.current);
135
+ let nextIndex = currentIndex + direction;
136
+ if (nextIndex >= list.length) {
137
+ nextIndex = wrapEnabled ? 0 : currentIndex;
138
+ }
139
+ else if (nextIndex < 0) {
140
+ nextIndex = wrapEnabled ? list.length - 1 : currentIndex;
141
+ }
142
+ activate(list[nextIndex].id);
143
+ }, [activate, wrapEnabled]);
144
+ const next = useCallback(() => {
145
+ step(1);
146
+ }, [step]);
147
+ const previous = useCallback(() => {
148
+ step(-1);
149
+ }, [step]);
150
+ const switchEnabled = switchKeys !== null;
151
+ const nextHotkey = switchKeys?.next ?? "tab";
152
+ const previousHotkey = switchKeys?.previous ?? "shift+tab";
153
+ const resolvedSwitchModes = switchModes ?? DEFAULT_SWITCH_MODES;
154
+ const panelIds = useMemo(() => [...registrations].toSorted((a, b) => a.order - b.order).map((entry) => entry.id), [registrations]);
155
+ const contextValue = useMemo(() => ({
156
+ activate,
157
+ activateOnMouseDown: activateOnMouseDown ?? true,
158
+ activeId: resolvedId,
159
+ groupId,
160
+ next,
161
+ nextHotkey,
162
+ panelIds,
163
+ previous,
164
+ previousHotkey,
165
+ register,
166
+ setDisabled,
167
+ switchEnabled,
168
+ switchModes: resolvedSwitchModes,
169
+ }), [
170
+ activate,
171
+ activateOnMouseDown,
172
+ resolvedId,
173
+ groupId,
174
+ next,
175
+ nextHotkey,
176
+ panelIds,
177
+ previous,
178
+ previousHotkey,
179
+ register,
180
+ setDisabled,
181
+ switchEnabled,
182
+ resolvedSwitchModes,
183
+ ]);
184
+ return _jsx(PanelGroupContext, { value: contextValue, children: children });
185
+ };
186
+ //# sourceMappingURL=panel-group.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"panel-group.js","sourceRoot":"","sources":["../src/panel-group.tsx"],"names":[],"mappings":"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"}
@@ -0,0 +1,11 @@
1
+ import type { ReactNode } from "react";
2
+ import type { PanelProps } from "./types.js";
3
+ /**
4
+ * A visible, mounted region that owns a command surface, a local mode, and
5
+ * optional chrome. Its `useCommand`/`useMode` children register on the panel's
6
+ * surface, so they only dispatch while this panel is its group's active panel —
7
+ * the same containment property overlays have. Children stay mounted across
8
+ * activation changes (local state, panel-local router stacks, and mode persist).
9
+ */
10
+ export declare const Panel: ({ id, title, disabled, initialMode, chrome, style, children, }: PanelProps) => ReactNode;
11
+ //# sourceMappingURL=panel.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"panel.d.ts","sourceRoot":"","sources":["../src/panel.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKvC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA0B7C;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,mEAQf,UAAU,KAAG,SAoEf,CAAC"}
package/dist/panel.js ADDED
@@ -0,0 +1,66 @@
1
+ import { jsx as _jsx, jsxs as _jsxs } from "@opentui/react/jsx-runtime";
2
+ import { useCallback, useEffect, useMemo } from "react";
3
+ import { CommandSurfaceProvider, ScreenScopeProvider, useCommand } from "@tooee/commands";
4
+ import { useTheme } from "@tooee/themes";
5
+ import { PanelContext, usePanelGroupContext } from "./context.js";
6
+ const PanelSwitchCommands = function PanelSwitchCommands({ group, }) {
7
+ useCommand({
8
+ enabled: group.switchEnabled,
9
+ handler: group.next,
10
+ hotkey: group.nextHotkey,
11
+ id: "panels.next",
12
+ modes: group.switchModes,
13
+ title: "Next panel",
14
+ });
15
+ useCommand({
16
+ enabled: group.switchEnabled,
17
+ handler: group.previous,
18
+ hotkey: group.previousHotkey,
19
+ id: "panels.previous",
20
+ modes: group.switchModes,
21
+ title: "Previous panel",
22
+ });
23
+ return null;
24
+ };
25
+ /**
26
+ * A visible, mounted region that owns a command surface, a local mode, and
27
+ * optional chrome. Its `useCommand`/`useMode` children register on the panel's
28
+ * surface, so they only dispatch while this panel is its group's active panel —
29
+ * the same containment property overlays have. Children stay mounted across
30
+ * activation changes (local state, panel-local router stacks, and mode persist).
31
+ */
32
+ export const Panel = function Panel({ id, title, disabled, initialMode, chrome = "border", style, children, }) {
33
+ const group = usePanelGroupContext();
34
+ const { theme } = useTheme();
35
+ const disabledValue = disabled ?? false;
36
+ // `register`/`setDisabled`/`activate` are referentially stable; depend on them
37
+ // (not the whole group object, whose identity changes on every activation) so
38
+ // membership is registered once on mount, not re-registered on each switch.
39
+ const { register, setDisabled, activate: activatePanel, groupId, activeId } = group;
40
+ useEffect(() => register(id), [register, id]);
41
+ useEffect(() => {
42
+ setDisabled(id, disabledValue);
43
+ }, [setDisabled, id, disabledValue]);
44
+ const isActive = activeId === id && !disabledValue;
45
+ const activate = useCallback(() => {
46
+ activatePanel(id);
47
+ }, [activatePanel, id]);
48
+ const panelContext = useMemo(() => ({ groupId, id, title }), [groupId, id, title]);
49
+ const inner = (_jsx(PanelContext, { value: panelContext, children: _jsxs(CommandSurfaceProvider, { id: id, role: "panel", groupId: group.groupId, initialMode: initialMode ?? "cursor", children: [_jsx(PanelSwitchCommands, { group: group }), _jsx(ScreenScopeProvider, { active: isActive, children: children })] }) }));
50
+ if (chrome === "none") {
51
+ return inner;
52
+ }
53
+ // Chrome uses existing theme tokens only. Active: `borderActive` + a `▸`
54
+ // marker (a non-color cue). Disabled: `borderSubtle` + muted title. Inactive:
55
+ // `border` + muted title.
56
+ const activeBorder = isActive ? theme.borderActive : theme.border;
57
+ const borderColor = disabledValue ? theme.borderSubtle : activeBorder;
58
+ const titleColor = isActive ? theme.borderActive : theme.textMuted;
59
+ let displayTitle;
60
+ if (title !== undefined) {
61
+ displayTitle = isActive ? `▸ ${title}` : title;
62
+ }
63
+ const canActivateOnMouseDown = group.activateOnMouseDown && !disabledValue;
64
+ return (_jsx("box", { border: true, borderColor: borderColor, title: displayTitle, titleColor: titleColor, backgroundColor: theme.backgroundPanel, onMouseDown: canActivateOnMouseDown ? activate : undefined, style: style, children: inner }));
65
+ };
66
+ //# sourceMappingURL=panel.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"panel.js","sourceRoot":"","sources":["../src/panel.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAExD,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAIlE,MAAM,mBAAmB,GAAG,SAAS,mBAAmB,CAAC,EACvD,KAAK,GAGN;IACC,UAAU,CAAC;QACT,OAAO,EAAE,KAAK,CAAC,aAAa;QAC5B,OAAO,EAAE,KAAK,CAAC,IAAI;QACnB,MAAM,EAAE,KAAK,CAAC,UAAU;QACxB,EAAE,EAAE,aAAa;QACjB,KAAK,EAAE,KAAK,CAAC,WAAW;QACxB,KAAK,EAAE,YAAY;KACpB,CAAC,CAAC;IACH,UAAU,CAAC;QACT,OAAO,EAAE,KAAK,CAAC,aAAa;QAC5B,OAAO,EAAE,KAAK,CAAC,QAAQ;QACvB,MAAM,EAAE,KAAK,CAAC,cAAc;QAC5B,EAAE,EAAE,iBAAiB;QACrB,KAAK,EAAE,KAAK,CAAC,WAAW;QACxB,KAAK,EAAE,gBAAgB;KACxB,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,SAAS,KAAK,CAAC,EAClC,EAAE,EACF,KAAK,EACL,QAAQ,EACR,WAAW,EACX,MAAM,GAAG,QAAQ,EACjB,KAAK,EACL,QAAQ,GACG;IACX,MAAM,KAAK,GAAG,oBAAoB,EAAE,CAAC;IACrC,MAAM,EAAE,KAAK,EAAE,GAAG,QAAQ,EAAE,CAAC;IAC7B,MAAM,aAAa,GAAG,QAAQ,IAAI,KAAK,CAAC;IAExC,+EAA+E;IAC/E,8EAA8E;IAC9E,4EAA4E;IAC5E,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAEpF,SAAS,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC;IAC9C,SAAS,CAAC,GAAG,EAAE;QACb,WAAW,CAAC,EAAE,EAAE,aAAa,CAAC,CAAC;IACjC,CAAC,EAAE,CAAC,WAAW,EAAE,EAAE,EAAE,aAAa,CAAC,CAAC,CAAC;IAErC,MAAM,QAAQ,GAAG,QAAQ,KAAK,EAAE,IAAI,CAAC,aAAa,CAAC;IACnD,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE;QAChC,aAAa,CAAC,EAAE,CAAC,CAAC;IACpB,CAAC,EAAE,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC,CAAC;IAExB,MAAM,YAAY,GAAG,OAAO,CAC1B,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAC9B,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,CACrB,CAAC;IAEF,MAAM,KAAK,GAAG,CACZ,KAAC,YAAY,IAAC,KAAK,EAAE,YAAY,YAC/B,MAAC,sBAAsB,IACrB,EAAE,EAAE,EAAE,EACN,IAAI,EAAC,OAAO,EACZ,OAAO,EAAE,KAAK,CAAC,OAAO,EACtB,WAAW,EAAE,WAAW,IAAI,QAAQ,aAEpC,KAAC,mBAAmB,IAAC,KAAK,EAAE,KAAK,GAAI,EACrC,KAAC,mBAAmB,IAAC,MAAM,EAAE,QAAQ,YAAG,QAAQ,GAAuB,IAChD,GACZ,CAChB,CAAC;IAEF,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,yEAAyE;IACzE,8EAA8E;IAC9E,0BAA0B;IAC1B,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC;IAClE,MAAM,WAAW,GAAG,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC;IACtE,MAAM,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;IACnE,IAAI,YAAgC,CAAC;IACrC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;IACjD,CAAC;IACD,MAAM,sBAAsB,GAAG,KAAK,CAAC,mBAAmB,IAAI,CAAC,aAAa,CAAC;IAE3E,OAAO,CACL,cACE,MAAM,QACN,WAAW,EAAE,WAAW,EACxB,KAAK,EAAE,YAAY,EACnB,UAAU,EAAE,UAAU,EACtB,eAAe,EAAE,KAAK,CAAC,eAAe,EACtC,WAAW,EAAE,sBAAsB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,EAC1D,KAAK,EAAE,KAAK,YAEX,KAAK,GACF,CACP,CAAC;AACJ,CAAC,CAAC"}
@@ -0,0 +1,51 @@
1
+ import type { ReactNode } from "react";
2
+ import type { BoxProps } from "@opentui/react";
3
+ import type { Mode } from "@tooee/commands";
4
+ /** Switch shortcuts for a panel group. Set the whole prop to `null` to disable built-in switching. */
5
+ export interface PanelSwitchKeys {
6
+ /** Hotkey for "next panel" (default `"tab"`). */
7
+ next?: string;
8
+ /** Hotkey for "previous panel" (default `"shift+tab"`). */
9
+ previous?: string;
10
+ }
11
+ export interface PanelGroupProps {
12
+ /** Stable group id; defaults to a generated id (fine for a single group). */
13
+ id?: string;
14
+ /** Uncontrolled initial active panel. Defaults to the first registered panel. */
15
+ defaultActivePanelId?: string;
16
+ /** Controlled active panel. A string selects that panel; null explicitly selects none. */
17
+ activePanelId?: string | null;
18
+ /** Non-null uncontrolled resolved changes or controlled activation requests; never echoes props. */
19
+ onActivePanelChange?: (panelId: string) => void;
20
+ /**
21
+ * Switch shortcuts. Defaults: next `"tab"`, previous `"shift+tab"`. Set to
22
+ * `null` to disable built-in switching (apps then call `usePanels().next`).
23
+ */
24
+ switchKeys?: PanelSwitchKeys | null;
25
+ /** Modes in which switch keys are live. Default: `["cursor", "select"]`. */
26
+ switchModes?: Mode[];
27
+ /** Wrap from last to first (default true). */
28
+ wrap?: boolean;
29
+ /** Activate a panel on mouse-down inside it (default true; only with default chrome). */
30
+ activateOnMouseDown?: boolean;
31
+ children: ReactNode;
32
+ }
33
+ export interface PanelProps {
34
+ id: string;
35
+ /** Chrome title. */
36
+ title?: string;
37
+ /** Excluded from activation and switching; renders inactive/disabled chrome. */
38
+ disabled?: boolean;
39
+ /** Initial local mode (default "cursor"), as CommandSurfaceProvider today. */
40
+ initialMode?: Mode;
41
+ /**
42
+ * `"border"` (default): render a bordered box with active/inactive/disabled
43
+ * treatment. `"none"`: render no chrome; the app reads `usePanelState()` and
44
+ * renders its own (mouse activation is then the app's responsibility).
45
+ */
46
+ chrome?: "border" | "none";
47
+ /** Layout props forwarded to the chrome box (flexGrow, width, ...). */
48
+ style?: BoxProps["style"];
49
+ children: ReactNode;
50
+ }
51
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAE5C,sGAAsG;AACtG,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,0FAA0F;IAC1F,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,oGAAoG;IACpG,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD;;;OAGG;IACH,UAAU,CAAC,EAAE,eAAe,GAAG,IAAI,CAAC;IACpC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,IAAI,EAAE,CAAC;IACrB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,yFAAyF;IACzF,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,oBAAoB;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,IAAI,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC3B,uEAAuE;IACvE,KAAK,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC1B,QAAQ,EAAE,SAAS,CAAC;CACrB"}
package/dist/types.js ADDED
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}
package/package.json ADDED
@@ -0,0 +1,54 @@
1
+ {
2
+ "name": "@tooee/panels",
3
+ "version": "0.4.0",
4
+ "description": "First-class panels (peer command surfaces with activation and chrome) for Tooee",
5
+ "keywords": [
6
+ "cli",
7
+ "opentui",
8
+ "panels",
9
+ "terminal",
10
+ "tui"
11
+ ],
12
+ "homepage": "https://github.com/gingerhendrix/tooee",
13
+ "bugs": "https://github.com/gingerhendrix/tooee/issues",
14
+ "license": "MIT",
15
+ "author": "Gareth Andrew",
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "https://github.com/gingerhendrix/tooee.git",
19
+ "directory": "packages/panels"
20
+ },
21
+ "files": [
22
+ "dist",
23
+ "src"
24
+ ],
25
+ "type": "module",
26
+ "exports": {
27
+ ".": {
28
+ "import": {
29
+ "@tooee/source": "./src/index.ts",
30
+ "default": "./dist/index.js"
31
+ }
32
+ }
33
+ },
34
+ "scripts": {
35
+ "typecheck": "tsc --noEmit"
36
+ },
37
+ "dependencies": {
38
+ "@tooee/commands": "0.4.0",
39
+ "@tooee/themes": "0.4.0"
40
+ },
41
+ "devDependencies": {
42
+ "@opentui/core": "^0.4.3",
43
+ "@opentui/react": "^0.4.3",
44
+ "@tooee/router": "0.4.0",
45
+ "@types/bun": "^1.3.10",
46
+ "@types/react": "^19.2.14",
47
+ "typescript": "^5.9.3"
48
+ },
49
+ "peerDependencies": {
50
+ "@opentui/core": "^0.4.3",
51
+ "@opentui/react": "^0.4.3",
52
+ "react": "^18.0.0 || ^19.0.0"
53
+ }
54
+ }
package/src/context.ts ADDED
@@ -0,0 +1,63 @@
1
+ import { createContext, useContext } from "react";
2
+ import type { Mode } from "@tooee/commands";
3
+
4
+ /**
5
+ * The interface a `PanelGroup` exposes to the `Panel`s and hooks beneath it.
6
+ * `activeId` is the resolved active panel (reactive); `register`/`setDisabled`
7
+ * synchronize a panel's membership and activatable state with the group.
8
+ */
9
+ export interface PanelGroupContextValue {
10
+ groupId: string;
11
+ /** The resolved active panel id, or null when the group has no activatable panel. */
12
+ activeId: string | null;
13
+ /** All registered panel ids in registration (source) order. */
14
+ panelIds: readonly string[];
15
+ /** Activate a panel (ignored if unknown/disabled). */
16
+ activate: (panelId: string) => void;
17
+ /** Activate the next activatable panel (source order; wraps per `wrap`). */
18
+ next: () => void;
19
+ /** Activate the previous activatable panel. */
20
+ previous: () => void;
21
+ /** Register a panel; returns the unregister cleanup. Assigns registration order. */
22
+ register: (panelId: string) => () => void;
23
+ /** Update a panel's disabled (non-activatable) flag. */
24
+ setDisabled: (panelId: string, disabled: boolean) => void;
25
+ /** Whether panels should activate on mouse-down (default chrome only). */
26
+ activateOnMouseDown: boolean;
27
+ /** Whether the built-in next/previous commands are registered on each panel surface. */
28
+ switchEnabled: boolean;
29
+ /** Built-in next-panel hotkey. */
30
+ nextHotkey: string;
31
+ /** Built-in previous-panel hotkey. */
32
+ previousHotkey: string;
33
+ /** Local modes in which the built-in switch commands dispatch. */
34
+ switchModes: Mode[];
35
+ }
36
+
37
+ export const PanelGroupContext = createContext<PanelGroupContextValue | null>(null);
38
+
39
+ export const usePanelGroupContext = function usePanelGroupContext(): PanelGroupContextValue {
40
+ const ctx = useContext(PanelGroupContext);
41
+ if (!ctx) {
42
+ throw new Error("usePanelGroupContext must be used within a PanelGroup");
43
+ }
44
+ return ctx;
45
+ };
46
+
47
+ export const useOptionalPanelGroupContext =
48
+ function useOptionalPanelGroupContext(): PanelGroupContextValue | null {
49
+ return useContext(PanelGroupContext);
50
+ };
51
+
52
+ export interface PanelContextValue {
53
+ id: string;
54
+ title?: string;
55
+ groupId: string;
56
+ }
57
+
58
+ export const PanelContext = createContext<PanelContextValue | null>(null);
59
+
60
+ export const useOptionalPanelContext =
61
+ function useOptionalPanelContext(): PanelContextValue | null {
62
+ return useContext(PanelContext);
63
+ };
package/src/hooks.ts ADDED
@@ -0,0 +1,62 @@
1
+ import { useContext, useMemo } from "react";
2
+ import { PanelContext, useOptionalPanelGroupContext, usePanelGroupContext } from "./context.js";
3
+
4
+ export interface PanelState {
5
+ id: string;
6
+ title?: string;
7
+ /** Reactive: true while this panel is its group's active panel. */
8
+ isActive: boolean;
9
+ /** Activate this panel. */
10
+ activate: () => void;
11
+ }
12
+
13
+ /** State of the nearest enclosing `Panel`. */
14
+ export const usePanelState = function usePanelState(): PanelState {
15
+ const panel = useContext(PanelContext);
16
+ const group = usePanelGroupContext();
17
+ if (!panel) {
18
+ throw new Error("usePanelState must be used within a Panel");
19
+ }
20
+ const isActive = group.activeId === panel.id;
21
+ const { activate } = group;
22
+ const { id, title } = panel;
23
+ return useMemo<PanelState>(
24
+ () => ({
25
+ activate: () => {
26
+ activate(id);
27
+ },
28
+ id,
29
+ isActive,
30
+ title,
31
+ }),
32
+ [activate, id, title, isActive],
33
+ );
34
+ };
35
+
36
+ export interface PanelsControls {
37
+ panelIds: readonly string[];
38
+ activePanelId: string | null;
39
+ activate: (id: string) => void;
40
+ next: () => void;
41
+ previous: () => void;
42
+ }
43
+
44
+ /** Group-level access, usable inside or outside panels (nearest group). */
45
+ export const usePanels = function usePanels(): PanelsControls {
46
+ const group = usePanelGroupContext();
47
+ const { panelIds, activeId, activate, next, previous } = group;
48
+ return useMemo<PanelsControls>(
49
+ () => ({ activate, activePanelId: activeId, next, panelIds, previous }),
50
+ [panelIds, activeId, activate, next, previous],
51
+ );
52
+ };
53
+
54
+ /** Convenience: true when inside the active panel (or when there is no enclosing panel). */
55
+ export const usePanelActive = function usePanelActive(): boolean {
56
+ const panel = useContext(PanelContext);
57
+ const group = useOptionalPanelGroupContext();
58
+ if (!panel || !group) {
59
+ return true;
60
+ }
61
+ return group.activeId === panel.id;
62
+ };
package/src/index.ts ADDED
@@ -0,0 +1,6 @@
1
+ export { PanelGroup } from "./panel-group.js";
2
+ export { Panel } from "./panel.js";
3
+ export type { PanelGroupProps, PanelProps, PanelSwitchKeys } from "./types.js";
4
+ export { usePanelState, usePanels, usePanelActive } from "./hooks.js";
5
+ export type { PanelState, PanelsControls } from "./hooks.js";
6
+ export type { PanelGroupContextValue, PanelContextValue } from "./context.js";
@@ -0,0 +1,247 @@
1
+ import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
2
+ import type { ReactNode } from "react";
3
+ import { useCommandStore } from "@tooee/commands";
4
+ import {
5
+ PanelGroupContext,
6
+ useOptionalPanelContext,
7
+ useOptionalPanelGroupContext,
8
+ } from "./context.js";
9
+ import type { PanelGroupContextValue } from "./context.js";
10
+ import type { PanelGroupProps } from "./types.js";
11
+
12
+ interface Registration {
13
+ id: string;
14
+ /** Monotonic registration order = Tab-cycle order (source order in practice). */
15
+ order: number;
16
+ disabled: boolean;
17
+ }
18
+
19
+ const DEFAULT_SWITCH_MODES: PanelGroupContextValue["switchModes"] = ["cursor", "select"];
20
+
21
+ /**
22
+ * A set of peer panels among which exactly one is active. Renders no box of its
23
+ * own — layout belongs to the app. It owns activation state (controlled or
24
+ * uncontrolled), tracks panel registration order for Tab cycling, repairs
25
+ * activation when the active panel unmounts or is disabled, publishes the active
26
+ * panel to the command store, and registers the switch commands.
27
+ */
28
+ export const PanelGroup = function PanelGroup({
29
+ id,
30
+ defaultActivePanelId,
31
+ activePanelId,
32
+ onActivePanelChange,
33
+ switchKeys,
34
+ switchModes,
35
+ wrap,
36
+ activateOnMouseDown,
37
+ children,
38
+ }: PanelGroupProps): ReactNode {
39
+ const generatedId = useId();
40
+ const groupId = id ?? generatedId;
41
+ const commandStore = useCommandStore();
42
+ const enclosingPanel = useOptionalPanelContext();
43
+ const enclosingGroup = useOptionalPanelGroupContext();
44
+ const isInActiveAncestry =
45
+ enclosingPanel === null || enclosingGroup?.activeId === enclosingPanel.id;
46
+
47
+ const isControlled = activePanelId !== undefined;
48
+ const wrapEnabled = wrap ?? true;
49
+
50
+ const [registrations, setRegistrations] = useState<readonly Registration[]>([]);
51
+ const orderCounterRef = useRef(0);
52
+ const [uncontrolledActive, setUncontrolledActive] = useState<string | null>(
53
+ defaultActivePanelId ?? null,
54
+ );
55
+ // Order of the last resolved active panel, so removal repair can pick the
56
+ // next-in-order (else previous) panel rather than always jumping to the first.
57
+ const lastActiveOrderRef = useRef(-1);
58
+
59
+ const register = useCallback((panelId: string): (() => void) => {
60
+ const order = orderCounterRef.current;
61
+ orderCounterRef.current += 1;
62
+ setRegistrations((prev) =>
63
+ prev.some((entry) => entry.id === panelId)
64
+ ? prev
65
+ : [...prev, { disabled: false, id: panelId, order }],
66
+ );
67
+ return () => {
68
+ setRegistrations((prev) => prev.filter((entry) => entry.id !== panelId));
69
+ };
70
+ }, []);
71
+
72
+ const setDisabled = useCallback((panelId: string, disabled: boolean): void => {
73
+ setRegistrations((prev) => {
74
+ const index = prev.findIndex((entry) => entry.id === panelId);
75
+ if (index === -1 || prev[index].disabled === disabled) {
76
+ return prev;
77
+ }
78
+ const next = [...prev];
79
+ next[index] = { ...next[index], disabled };
80
+ return next;
81
+ });
82
+ }, []);
83
+
84
+ const activatable = useMemo(
85
+ () => registrations.filter((entry) => !entry.disabled).sort((a, b) => a.order - b.order),
86
+ [registrations],
87
+ );
88
+
89
+ const requestedId = isControlled ? (activePanelId ?? null) : uncontrolledActive;
90
+
91
+ // The single source of truth for "which panel is active", derived each render
92
+ // so a Panel's chrome and hooks are never a frame behind their own registration.
93
+ const resolvedId = useMemo<string | null>(() => {
94
+ if (activatable.length === 0) {
95
+ return null;
96
+ }
97
+ if (requestedId !== null && activatable.some((entry) => entry.id === requestedId)) {
98
+ return requestedId;
99
+ }
100
+ // Controlled means controlled: a missing/disabled controlled id activates no
101
+ // panel (root owns input) rather than silently repairing to a peer.
102
+ if (isControlled) {
103
+ return null;
104
+ }
105
+ const lastOrder = lastActiveOrderRef.current;
106
+ const nextAfter = activatable.find((entry) => entry.order > lastOrder);
107
+ if (nextAfter) {
108
+ return nextAfter.id;
109
+ }
110
+ const previousBefore = [...activatable].toReversed().find((entry) => entry.order < lastOrder);
111
+ return (previousBefore ?? activatable[0]).id;
112
+ }, [activatable, requestedId, isControlled]);
113
+
114
+ const activatableRef = useRef(activatable);
115
+ activatableRef.current = activatable;
116
+ const resolvedRef = useRef(resolvedId);
117
+ resolvedRef.current = resolvedId;
118
+ const onActivePanelChangeRef = useRef(onActivePanelChange);
119
+ onActivePanelChangeRef.current = onActivePanelChange;
120
+
121
+ // Publish activation to the command store and reconcile derived state.
122
+ const announcedRef = useRef<string | null>(null);
123
+ useEffect(() => {
124
+ if (resolvedId === null || !isInActiveAncestry) {
125
+ commandStore.removePanelGroup(groupId);
126
+ } else {
127
+ commandStore.activatePanel(groupId, resolvedId);
128
+ lastActiveOrderRef.current =
129
+ activatable.find((entry) => entry.id === resolvedId)?.order ?? lastActiveOrderRef.current;
130
+ if (!isControlled && resolvedId !== uncontrolledActive) {
131
+ // Keep the uncontrolled intent in step with a repair so `requestedId`
132
+ // tracks the resolved panel on subsequent renders.
133
+ setUncontrolledActive(resolvedId);
134
+ }
135
+ }
136
+ // Uncontrolled: announce resolved changes (initial select and repair). A
137
+ // controlled group announces from `activate`/`next`/`previous` instead, so
138
+ // the parent is not echoed its own prop change.
139
+ if (!isControlled && resolvedId !== announcedRef.current) {
140
+ announcedRef.current = resolvedId;
141
+ if (resolvedId !== null) {
142
+ onActivePanelChangeRef.current?.(resolvedId);
143
+ }
144
+ }
145
+ }, [
146
+ commandStore,
147
+ groupId,
148
+ resolvedId,
149
+ activatable,
150
+ isControlled,
151
+ uncontrolledActive,
152
+ isInActiveAncestry,
153
+ ]);
154
+
155
+ // Forget the group's activation when it unmounts so the store does not keep a
156
+ // stale active id for a group that no longer exists.
157
+ useEffect(
158
+ () => () => {
159
+ commandStore.removePanelGroup(groupId);
160
+ },
161
+ [commandStore, groupId],
162
+ );
163
+
164
+ const activate = useCallback(
165
+ (panelId: string): void => {
166
+ if (!activatableRef.current.some((entry) => entry.id === panelId)) {
167
+ return;
168
+ }
169
+ if (isControlled) {
170
+ onActivePanelChangeRef.current?.(panelId);
171
+ } else {
172
+ setUncontrolledActive(panelId);
173
+ }
174
+ },
175
+ [isControlled],
176
+ );
177
+
178
+ const step = useCallback(
179
+ (direction: 1 | -1): void => {
180
+ const list = activatableRef.current;
181
+ if (list.length < 2) {
182
+ return;
183
+ }
184
+ const currentIndex = list.findIndex((entry) => entry.id === resolvedRef.current);
185
+ let nextIndex = currentIndex + direction;
186
+ if (nextIndex >= list.length) {
187
+ nextIndex = wrapEnabled ? 0 : currentIndex;
188
+ } else if (nextIndex < 0) {
189
+ nextIndex = wrapEnabled ? list.length - 1 : currentIndex;
190
+ }
191
+ activate(list[nextIndex].id);
192
+ },
193
+ [activate, wrapEnabled],
194
+ );
195
+
196
+ const next = useCallback(() => {
197
+ step(1);
198
+ }, [step]);
199
+ const previous = useCallback(() => {
200
+ step(-1);
201
+ }, [step]);
202
+
203
+ const switchEnabled = switchKeys !== null;
204
+ const nextHotkey = switchKeys?.next ?? "tab";
205
+ const previousHotkey = switchKeys?.previous ?? "shift+tab";
206
+ const resolvedSwitchModes = switchModes ?? DEFAULT_SWITCH_MODES;
207
+
208
+ const panelIds = useMemo(
209
+ () => [...registrations].toSorted((a, b) => a.order - b.order).map((entry) => entry.id),
210
+ [registrations],
211
+ );
212
+
213
+ const contextValue = useMemo<PanelGroupContextValue>(
214
+ () => ({
215
+ activate,
216
+ activateOnMouseDown: activateOnMouseDown ?? true,
217
+ activeId: resolvedId,
218
+ groupId,
219
+ next,
220
+ nextHotkey,
221
+ panelIds,
222
+ previous,
223
+ previousHotkey,
224
+ register,
225
+ setDisabled,
226
+ switchEnabled,
227
+ switchModes: resolvedSwitchModes,
228
+ }),
229
+ [
230
+ activate,
231
+ activateOnMouseDown,
232
+ resolvedId,
233
+ groupId,
234
+ next,
235
+ nextHotkey,
236
+ panelIds,
237
+ previous,
238
+ previousHotkey,
239
+ register,
240
+ setDisabled,
241
+ switchEnabled,
242
+ resolvedSwitchModes,
243
+ ],
244
+ );
245
+
246
+ return <PanelGroupContext value={contextValue}>{children}</PanelGroupContext>;
247
+ };
package/src/panel.tsx ADDED
@@ -0,0 +1,116 @@
1
+ import { useCallback, useEffect, useMemo } from "react";
2
+ import type { ReactNode } from "react";
3
+ import { CommandSurfaceProvider, ScreenScopeProvider, useCommand } from "@tooee/commands";
4
+ import { useTheme } from "@tooee/themes";
5
+ import { PanelContext, usePanelGroupContext } from "./context.js";
6
+ import type { PanelContextValue, PanelGroupContextValue } from "./context.js";
7
+ import type { PanelProps } from "./types.js";
8
+
9
+ const PanelSwitchCommands = function PanelSwitchCommands({
10
+ group,
11
+ }: {
12
+ group: PanelGroupContextValue;
13
+ }): null {
14
+ useCommand({
15
+ enabled: group.switchEnabled,
16
+ handler: group.next,
17
+ hotkey: group.nextHotkey,
18
+ id: "panels.next",
19
+ modes: group.switchModes,
20
+ title: "Next panel",
21
+ });
22
+ useCommand({
23
+ enabled: group.switchEnabled,
24
+ handler: group.previous,
25
+ hotkey: group.previousHotkey,
26
+ id: "panels.previous",
27
+ modes: group.switchModes,
28
+ title: "Previous panel",
29
+ });
30
+ return null;
31
+ };
32
+
33
+ /**
34
+ * A visible, mounted region that owns a command surface, a local mode, and
35
+ * optional chrome. Its `useCommand`/`useMode` children register on the panel's
36
+ * surface, so they only dispatch while this panel is its group's active panel —
37
+ * the same containment property overlays have. Children stay mounted across
38
+ * activation changes (local state, panel-local router stacks, and mode persist).
39
+ */
40
+ export const Panel = function Panel({
41
+ id,
42
+ title,
43
+ disabled,
44
+ initialMode,
45
+ chrome = "border",
46
+ style,
47
+ children,
48
+ }: PanelProps): ReactNode {
49
+ const group = usePanelGroupContext();
50
+ const { theme } = useTheme();
51
+ const disabledValue = disabled ?? false;
52
+
53
+ // `register`/`setDisabled`/`activate` are referentially stable; depend on them
54
+ // (not the whole group object, whose identity changes on every activation) so
55
+ // membership is registered once on mount, not re-registered on each switch.
56
+ const { register, setDisabled, activate: activatePanel, groupId, activeId } = group;
57
+
58
+ useEffect(() => register(id), [register, id]);
59
+ useEffect(() => {
60
+ setDisabled(id, disabledValue);
61
+ }, [setDisabled, id, disabledValue]);
62
+
63
+ const isActive = activeId === id && !disabledValue;
64
+ const activate = useCallback(() => {
65
+ activatePanel(id);
66
+ }, [activatePanel, id]);
67
+
68
+ const panelContext = useMemo<PanelContextValue>(
69
+ () => ({ groupId, id, title }),
70
+ [groupId, id, title],
71
+ );
72
+
73
+ const inner = (
74
+ <PanelContext value={panelContext}>
75
+ <CommandSurfaceProvider
76
+ id={id}
77
+ role="panel"
78
+ groupId={group.groupId}
79
+ initialMode={initialMode ?? "cursor"}
80
+ >
81
+ <PanelSwitchCommands group={group} />
82
+ <ScreenScopeProvider active={isActive}>{children}</ScreenScopeProvider>
83
+ </CommandSurfaceProvider>
84
+ </PanelContext>
85
+ );
86
+
87
+ if (chrome === "none") {
88
+ return inner;
89
+ }
90
+
91
+ // Chrome uses existing theme tokens only. Active: `borderActive` + a `▸`
92
+ // marker (a non-color cue). Disabled: `borderSubtle` + muted title. Inactive:
93
+ // `border` + muted title.
94
+ const activeBorder = isActive ? theme.borderActive : theme.border;
95
+ const borderColor = disabledValue ? theme.borderSubtle : activeBorder;
96
+ const titleColor = isActive ? theme.borderActive : theme.textMuted;
97
+ let displayTitle: string | undefined;
98
+ if (title !== undefined) {
99
+ displayTitle = isActive ? `▸ ${title}` : title;
100
+ }
101
+ const canActivateOnMouseDown = group.activateOnMouseDown && !disabledValue;
102
+
103
+ return (
104
+ <box
105
+ border
106
+ borderColor={borderColor}
107
+ title={displayTitle}
108
+ titleColor={titleColor}
109
+ backgroundColor={theme.backgroundPanel}
110
+ onMouseDown={canActivateOnMouseDown ? activate : undefined}
111
+ style={style}
112
+ >
113
+ {inner}
114
+ </box>
115
+ );
116
+ };
package/src/types.ts ADDED
@@ -0,0 +1,53 @@
1
+ import type { ReactNode } from "react";
2
+ import type { BoxProps } from "@opentui/react";
3
+ import type { Mode } from "@tooee/commands";
4
+
5
+ /** Switch shortcuts for a panel group. Set the whole prop to `null` to disable built-in switching. */
6
+ export interface PanelSwitchKeys {
7
+ /** Hotkey for "next panel" (default `"tab"`). */
8
+ next?: string;
9
+ /** Hotkey for "previous panel" (default `"shift+tab"`). */
10
+ previous?: string;
11
+ }
12
+
13
+ export interface PanelGroupProps {
14
+ /** Stable group id; defaults to a generated id (fine for a single group). */
15
+ id?: string;
16
+ /** Uncontrolled initial active panel. Defaults to the first registered panel. */
17
+ defaultActivePanelId?: string;
18
+ /** Controlled active panel. A string selects that panel; null explicitly selects none. */
19
+ activePanelId?: string | null;
20
+ /** Non-null uncontrolled resolved changes or controlled activation requests; never echoes props. */
21
+ onActivePanelChange?: (panelId: string) => void;
22
+ /**
23
+ * Switch shortcuts. Defaults: next `"tab"`, previous `"shift+tab"`. Set to
24
+ * `null` to disable built-in switching (apps then call `usePanels().next`).
25
+ */
26
+ switchKeys?: PanelSwitchKeys | null;
27
+ /** Modes in which switch keys are live. Default: `["cursor", "select"]`. */
28
+ switchModes?: Mode[];
29
+ /** Wrap from last to first (default true). */
30
+ wrap?: boolean;
31
+ /** Activate a panel on mouse-down inside it (default true; only with default chrome). */
32
+ activateOnMouseDown?: boolean;
33
+ children: ReactNode;
34
+ }
35
+
36
+ export interface PanelProps {
37
+ id: string;
38
+ /** Chrome title. */
39
+ title?: string;
40
+ /** Excluded from activation and switching; renders inactive/disabled chrome. */
41
+ disabled?: boolean;
42
+ /** Initial local mode (default "cursor"), as CommandSurfaceProvider today. */
43
+ initialMode?: Mode;
44
+ /**
45
+ * `"border"` (default): render a bordered box with active/inactive/disabled
46
+ * treatment. `"none"`: render no chrome; the app reads `usePanelState()` and
47
+ * renders its own (mouse activation is then the app's responsibility).
48
+ */
49
+ chrome?: "border" | "none";
50
+ /** Layout props forwarded to the chrome box (flexGrow, width, ...). */
51
+ style?: BoxProps["style"];
52
+ children: ReactNode;
53
+ }