@tooee/overlays 0.2.3 → 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.
package/src/index.ts CHANGED
@@ -2,12 +2,14 @@ export {
2
2
  OverlayContext,
3
3
  OverlayControllerContext,
4
4
  OverlayStateContext,
5
+ overlayUpdater,
6
+ overlayValue,
5
7
  useOverlay,
6
8
  useOverlayState,
7
9
  useCurrentOverlay,
8
10
  useHasOverlay,
9
11
  useHasModalOverlay,
10
- } from "./overlay-context.js"
12
+ } from "./overlay-context.js";
11
13
  export type {
12
14
  OverlayContextValue,
13
15
  OverlayId,
@@ -19,7 +21,8 @@ export type {
19
21
  OverlayHandle,
20
22
  OverlayController,
21
23
  OverlayState,
22
- } from "./overlay-context.js"
24
+ OverlayUpdate,
25
+ } from "./overlay-context.js";
23
26
  export {
24
27
  createOverlayStore,
25
28
  selectHasOverlay,
@@ -27,10 +30,15 @@ export {
27
30
  selectStack,
28
31
  selectStackIds,
29
32
  selectTop,
30
- } from "./overlay-store.js"
33
+ } from "./overlay-store.js";
31
34
  export type {
32
35
  OverlayClosedEmit,
36
+ OverlayClosedEvent,
37
+ OverlayClosedTopEvent,
38
+ OverlayOpenedEvent,
33
39
  OverlayRecord,
34
40
  OverlayStore,
35
41
  OverlayStoreContext,
36
- } from "./overlay-store.js"
42
+ OverlayStoreEvents,
43
+ OverlayUpdatedEvent,
44
+ } from "./overlay-store.js";
@@ -1,21 +1,22 @@
1
- import { createContext, useContext } from "react"
2
- import type { ReactNode } from "react"
1
+ import { createContext, useContext } from "react";
2
+ import type { ReactNode } from "react";
3
+ import type { CommandSurfaceRole, Mode } from "@tooee/commands";
3
4
 
4
5
  // Types
5
6
 
6
- export type OverlayId = string
7
+ export type OverlayId = string;
7
8
 
8
- export type OverlayCloseReason = "close" | "escape" | "replaced" | "unmounted"
9
+ export type OverlayCloseReason = "close" | "escape" | "replaced" | "unmounted";
9
10
 
10
- export type OverlayRole = "modal" | "passive"
11
+ export type OverlayRole = CommandSurfaceRole;
11
12
 
12
13
  export interface OverlayOpenOptions {
13
14
  /** Mode to set while overlay is active (default: "insert"). null = don't change mode. */
14
- mode?: string | null
15
+ mode?: Mode | null;
15
16
  /** Restore previous mode on close (default: true) */
16
- restoreMode?: boolean
17
+ restoreMode?: boolean;
17
18
  /** Allow Escape to close this overlay (default: true) */
18
- dismissOnEscape?: boolean
19
+ dismissOnEscape?: boolean;
19
20
  /**
20
21
  * Mount the overlay as an owned command surface: it gets a local command
21
22
  * registry and local mode, and (when `role` is "modal") suspends parent app
@@ -23,118 +24,147 @@ export interface OverlayOpenOptions {
23
24
  * host app's global mode. Overlay commands are registered with `useCommand`
24
25
  * inside the overlay's render, exactly like a standalone app.
25
26
  */
26
- ownCommands?: boolean
27
+ ownCommands?: boolean;
27
28
  /**
28
29
  * Interaction role for an owned command surface (default "modal"). Only
29
30
  * meaningful when `ownCommands` is true.
30
31
  */
31
- role?: OverlayRole
32
+ role?: OverlayRole;
32
33
  /** Initial local mode for an owned command surface (default "cursor"). */
33
- surfaceMode?: string
34
+ surfaceMode?: Mode;
34
35
  /** Lifecycle callback */
35
- onClose?: (reason: OverlayCloseReason) => void
36
+ onClose?: (reason: OverlayCloseReason) => void;
36
37
  }
37
38
 
39
+ /**
40
+ * An overlay payload change. The two cases are explicit because an overlay
41
+ * payload may itself be a function: `{ kind: "value" }` always replaces the
42
+ * payload, `{ kind: "updater" }` always derives it from the previous one. A
43
+ * `typeof next === "function"` check cannot tell those apart, so the caller
44
+ * chooses. Use the `overlayValue` / `overlayUpdater` helpers.
45
+ */
46
+ export type OverlayUpdate<TPayload = unknown> =
47
+ | { kind: "value"; value: TPayload }
48
+ | { kind: "updater"; update: (previous: TPayload) => TPayload };
49
+
50
+ /** Replace an overlay payload outright (safe even when the payload is a function). */
51
+ export const overlayValue = function overlayValue<TPayload>(
52
+ value: TPayload,
53
+ ): OverlayUpdate<TPayload> {
54
+ return { kind: "value", value };
55
+ };
56
+
57
+ /** Derive the next overlay payload from the previous one. */
58
+ export const overlayUpdater = function overlayUpdater<TPayload>(
59
+ update: (previous: TPayload) => TPayload,
60
+ ): OverlayUpdate<TPayload> {
61
+ return { kind: "updater", update };
62
+ };
63
+
38
64
  export interface OverlayRenderArgs<TPayload> {
39
- id: OverlayId
40
- payload: TPayload
41
- isTop: boolean
42
- close: (reason?: OverlayCloseReason) => void
43
- update: (next: TPayload | ((prev: TPayload) => TPayload)) => void
65
+ id: OverlayId;
66
+ payload: TPayload;
67
+ isTop: boolean;
68
+ close: (reason?: OverlayCloseReason) => void;
69
+ update: (next: OverlayUpdate<TPayload>) => void;
44
70
  }
45
71
 
46
- export type OverlayRenderer<TPayload> = (args: OverlayRenderArgs<TPayload>) => ReactNode
72
+ export type OverlayRenderer<TPayload> = (args: OverlayRenderArgs<TPayload>) => ReactNode;
47
73
 
48
74
  export interface OverlayHandle<TPayload> {
49
- id: OverlayId
50
- close: (reason?: OverlayCloseReason) => void
51
- update: (next: TPayload | ((prev: TPayload) => TPayload)) => void
75
+ id: OverlayId;
76
+ close: (reason?: OverlayCloseReason) => void;
77
+ update: (next: OverlayUpdate<TPayload>) => void;
52
78
  }
53
79
 
54
80
  export interface OverlayController {
55
- open<TPayload>(
81
+ open: <TPayload>(
56
82
  id: OverlayId,
57
83
  render: OverlayRenderer<TPayload>,
58
84
  payload: TPayload,
59
85
  options?: OverlayOpenOptions,
60
- ): OverlayHandle<TPayload>
61
- update<TPayload>(id: OverlayId, next: TPayload | ((prev: TPayload) => TPayload)): void
62
- show(id: OverlayId, content: ReactNode, options?: OverlayOpenOptions): void
63
- hide(id: OverlayId): void
64
- closeTop(reason?: OverlayCloseReason): void
65
- isOpen(id: OverlayId): boolean
66
- topId: OverlayId | null
86
+ ) => OverlayHandle<TPayload>;
87
+ update: <TPayload>(id: OverlayId, next: OverlayUpdate<TPayload>) => void;
88
+ show: (id: OverlayId, content: ReactNode, options?: OverlayOpenOptions) => void;
89
+ hide: (id: OverlayId) => void;
90
+ closeTop: (reason?: OverlayCloseReason) => void;
91
+ isOpen: (id: OverlayId) => boolean;
92
+ topId: OverlayId | null;
67
93
  }
68
94
 
69
95
  export interface OverlayState {
70
- current: ReactNode | null
71
- hasOverlay: boolean
96
+ current: ReactNode | null;
97
+ hasOverlay: boolean;
72
98
  /**
73
99
  * True when any overlay other than a passive owned surface is open. Passive
74
100
  * surfaces (e.g. the which-key hint) render for visuals only and never own
75
101
  * input, so they don't count. Use this for guards that should stand down
76
102
  * while a modal overlay is up but keep working under passive hints.
77
103
  */
78
- hasModalOverlay: boolean
79
- stack: OverlayId[]
104
+ hasModalOverlay: boolean;
105
+ stack: OverlayId[];
80
106
  }
81
107
 
82
108
  // Back-compat type (still exported for existing consumers)
83
109
  export interface OverlayContextValue {
84
- show: (id: string, content: ReactNode, options?: OverlayOpenOptions) => void
85
- hide: (id: string) => void
86
- current: ReactNode | null
87
- hasOverlay: boolean
110
+ show: (id: string, content: ReactNode, options?: OverlayOpenOptions) => void;
111
+ hide: (id: string) => void;
112
+ current: ReactNode | null;
113
+ hasOverlay: boolean;
88
114
  }
89
115
 
90
116
  // Contexts
91
117
 
92
118
  const defaultController: OverlayController = {
93
- open: (id) => ({ id, close: () => {}, update: () => {} }),
94
- update: () => {},
95
- show: () => {},
96
- hide: () => {},
97
- closeTop: () => {},
119
+ closeTop: () => void 0,
120
+ hide: () => void 0,
98
121
  isOpen: () => false,
122
+ open: (id) => ({
123
+ close: () => void 0,
124
+ id,
125
+ update: () => void 0,
126
+ }),
127
+ show: () => void 0,
99
128
  topId: null,
100
- }
129
+ update: () => void 0,
130
+ };
101
131
 
102
132
  const defaultState: OverlayState = {
103
133
  current: null,
104
- hasOverlay: false,
105
134
  hasModalOverlay: false,
135
+ hasOverlay: false,
106
136
  stack: [],
107
- }
137
+ };
108
138
 
109
- export const OverlayControllerContext = createContext<OverlayController>(defaultController)
110
- export const OverlayStateContext = createContext<OverlayState>(defaultState)
139
+ export const OverlayControllerContext = createContext<OverlayController>(defaultController);
140
+ export const OverlayStateContext = createContext<OverlayState>(defaultState);
111
141
 
112
142
  // Back-compat: OverlayContext that combines both (for existing provider consumers)
113
143
  export const OverlayContext = createContext<OverlayContextValue>({
114
- show: () => {},
115
- hide: () => {},
116
144
  current: null,
117
145
  hasOverlay: false,
118
- })
146
+ hide: () => void 0,
147
+ show: () => void 0,
148
+ });
119
149
 
120
150
  // Hooks
121
151
 
122
- export function useOverlay(): OverlayController {
123
- return useContext(OverlayControllerContext)
124
- }
152
+ export const useOverlay = function useOverlay(): OverlayController {
153
+ return useContext(OverlayControllerContext);
154
+ };
125
155
 
126
- export function useOverlayState(): OverlayState {
127
- return useContext(OverlayStateContext)
128
- }
156
+ export const useOverlayState = function useOverlayState(): OverlayState {
157
+ return useContext(OverlayStateContext);
158
+ };
129
159
 
130
- export function useHasOverlay(): boolean {
131
- return useContext(OverlayStateContext).hasOverlay
132
- }
160
+ export const useHasOverlay = function useHasOverlay(): boolean {
161
+ return useContext(OverlayStateContext).hasOverlay;
162
+ };
133
163
 
134
- export function useHasModalOverlay(): boolean {
135
- return useContext(OverlayStateContext).hasModalOverlay
136
- }
164
+ export const useHasModalOverlay = function useHasModalOverlay(): boolean {
165
+ return useContext(OverlayStateContext).hasModalOverlay;
166
+ };
137
167
 
138
- export function useCurrentOverlay(): ReactNode | null {
139
- return useContext(OverlayStateContext).current
140
- }
168
+ export const useCurrentOverlay = function useCurrentOverlay(): ReactNode | null {
169
+ return useContext(OverlayStateContext).current;
170
+ };
@@ -1,10 +1,12 @@
1
- import { createStore } from "@xstate/store"
1
+ import { createStore } from "@xstate/store";
2
2
  import type {
3
3
  OverlayCloseReason,
4
4
  OverlayId,
5
5
  OverlayOpenOptions,
6
6
  OverlayRenderer,
7
- } from "./overlay-context.js"
7
+ OverlayUpdate,
8
+ } from "./overlay-context.js";
9
+ import type { Mode } from "@tooee/commands";
8
10
 
9
11
  /**
10
12
  * An overlay stack entry as tracked by the store. `prevMode` is the host mode
@@ -12,15 +14,15 @@ import type {
12
14
  * shell's OverlayProvider, which owns all mode side effects).
13
15
  */
14
16
  export interface OverlayRecord<TPayload = unknown> {
15
- id: OverlayId
16
- render: OverlayRenderer<TPayload>
17
- payload: TPayload
18
- options: OverlayOpenOptions
19
- prevMode: string
17
+ id: OverlayId;
18
+ render: OverlayRenderer<TPayload>;
19
+ payload: TPayload;
20
+ options: OverlayOpenOptions;
21
+ prevMode: Mode;
20
22
  }
21
23
 
22
24
  export interface OverlayStoreContext {
23
- stack: readonly OverlayRecord[]
25
+ stack: readonly OverlayRecord[];
24
26
  }
25
27
 
26
28
  /**
@@ -30,8 +32,8 @@ export interface OverlayStoreContext {
30
32
  * `store.on("closed", ...)`; transitions stay pure.
31
33
  */
32
34
  export interface OverlayClosedEmit {
33
- record: OverlayRecord
34
- reason: OverlayCloseReason
35
+ record: OverlayRecord;
36
+ reason: OverlayCloseReason;
35
37
  /**
36
38
  * Legacy mode restoration decision, computed in the transition (it needs
37
39
  * stack state): `record.prevMode` when the record is non-ownCommands,
@@ -40,7 +42,7 @@ export interface OverlayClosedEmit {
40
42
  * above it — R-04); otherwise null. Same-id replacement displacement never
41
43
  * restores (the successor takes over).
42
44
  */
43
- restoreModeTo: string | null
45
+ restoreModeTo: Mode | null;
44
46
  }
45
47
 
46
48
  /**
@@ -48,14 +50,16 @@ export interface OverlayClosedEmit {
48
50
  * mutated on open, so there is nothing to restore. For legacy entries, only
49
51
  * the topmost non-ownCommands overlay owns the host mode.
50
52
  */
51
- function restoreModeDecision(
53
+ const restoreModeDecision = function restoreModeDecision(
52
54
  stack: readonly OverlayRecord[],
53
55
  record: OverlayRecord,
54
- ): string | null {
55
- if (record.options.ownCommands || record.options.restoreMode === false) return null
56
- const topLegacy = stack.findLast((entry) => !entry.options.ownCommands)
57
- return topLegacy === record ? record.prevMode : null
58
- }
56
+ ): Mode | null {
57
+ if (record.options.ownCommands === true || record.options.restoreMode === false) {
58
+ return null;
59
+ }
60
+ const topLegacy = stack.findLast((entry) => entry.options.ownCommands !== true);
61
+ return topLegacy === record ? record.prevMode : null;
62
+ };
59
63
 
60
64
  /**
61
65
  * Event payload map, passed explicitly as a `createStore` generic
@@ -67,92 +71,145 @@ function restoreModeDecision(
67
71
  * evaluated and rejected: it gives the same strictness while adding runtime
68
72
  * schema objects this store does not need.
69
73
  */
70
- export type OverlayStoreEvents = {
71
- opened: { record: OverlayRecord }
72
- updated: { id: OverlayId; next: unknown | ((prev: unknown) => unknown) }
73
- closed: { id: OverlayId; reason: OverlayCloseReason }
74
- closedTop: { reason: OverlayCloseReason }
74
+ export interface OverlayOpenedEvent {
75
+ record: OverlayRecord;
75
76
  }
76
77
 
77
- /** Emitted payload map (see OverlayStoreEvents docs — deliberately closed). */
78
- type OverlayStoreEmitted = {
79
- closed: OverlayClosedEmit
78
+ /**
79
+ * `next` is a discriminated `OverlayUpdate`, not `unknown | ((prev) => unknown)`:
80
+ * the old union collapsed to `unknown`, so the transition had to guess with
81
+ * `typeof next === "function"` and could not store a function-valued payload.
82
+ * The caller now states which it means.
83
+ */
84
+ export interface OverlayUpdatedEvent {
85
+ id: OverlayId;
86
+ next: OverlayUpdate;
87
+ }
88
+
89
+ export interface OverlayClosedEvent {
90
+ id: OverlayId;
91
+ reason: OverlayCloseReason;
80
92
  }
81
93
 
82
- export function createOverlayStore() {
94
+ export interface OverlayClosedTopEvent {
95
+ reason: OverlayCloseReason;
96
+ }
97
+
98
+ /**
99
+ * The two payload MAPS below must stay type aliases. XState v4 constrains them
100
+ * with `EventPayloadMap = Record<string, {} | null | undefined>`, and only an
101
+ * object-literal type alias gets TypeScript's implicit index signature — an
102
+ * `interface` is rejected by that constraint. The only way to make an interface
103
+ * satisfy it is to add an index signature, which would OPEN the map and destroy
104
+ * the closed-event-name guarantee pinned by `overlay-store.typecheck.ts`. The
105
+ * payload types themselves are interfaces (above), which is where the rule's
106
+ * intent actually applies.
107
+ */
108
+ // oxlint-disable-next-line typescript/consistent-type-definitions -- XState's EventPayloadMap constraint needs an implicit index signature; an interface cannot satisfy it without opening the map
109
+ export type OverlayStoreEvents = {
110
+ opened: OverlayOpenedEvent;
111
+ updated: OverlayUpdatedEvent;
112
+ closed: OverlayClosedEvent;
113
+ closedTop: OverlayClosedTopEvent;
114
+ };
115
+
116
+ /** Emitted payload map (see OverlayStoreEvents above — deliberately closed). */
117
+ // oxlint-disable-next-line typescript/consistent-type-definitions -- same XState EventPayloadMap constraint
118
+ type OverlayStoreEmitted = {
119
+ closed: OverlayClosedEmit;
120
+ };
121
+
122
+ export const createOverlayStore = function createOverlayStore() {
83
123
  return createStore<OverlayStoreContext, OverlayStoreEvents, OverlayStoreEmitted>({
84
124
  context: { stack: [] },
85
125
  on: {
126
+ closed: (ctx, event, enqueue) => {
127
+ const record = ctx.stack.find((entry) => entry.id === event.id);
128
+ if (!record) {
129
+ return ctx;
130
+ }
131
+ enqueue.emit.closed({
132
+ reason: event.reason,
133
+ record,
134
+ restoreModeTo: restoreModeDecision(ctx.stack, record),
135
+ });
136
+ return { stack: ctx.stack.filter((entry) => entry !== record) };
137
+ },
138
+ closedTop: (ctx, event, enqueue) => {
139
+ if (ctx.stack.length === 0) {
140
+ return ctx;
141
+ }
142
+ const record = ctx.stack.at(-1);
143
+ if (record === undefined) {
144
+ return ctx;
145
+ }
146
+ enqueue.emit.closed({
147
+ reason: event.reason,
148
+ record,
149
+ restoreModeTo: restoreModeDecision(ctx.stack, record),
150
+ });
151
+ return { stack: ctx.stack.slice(0, -1) };
152
+ },
86
153
  opened: (ctx, event, enqueue) => {
87
154
  // Replacing an existing same-id entry closes it: consumers release
88
155
  // open-state (e.g. a picker's isOpen) via the contract's "replaced"
89
156
  // reason instead of the entry being silently filtered away.
90
- const displaced = ctx.stack.find((entry) => entry.id === event.record.id)
157
+ const displaced = ctx.stack.find((entry) => entry.id === event.record.id);
91
158
  if (displaced) {
92
- enqueue.emit.closed({ record: displaced, reason: "replaced", restoreModeTo: null })
159
+ enqueue.emit.closed({ reason: "replaced", record: displaced, restoreModeTo: null });
93
160
  }
94
161
  const filtered = displaced
95
162
  ? ctx.stack.filter((entry) => entry.id !== event.record.id)
96
- : ctx.stack
97
- return { stack: [...filtered, event.record] }
163
+ : ctx.stack;
164
+ return { stack: [...filtered, event.record] };
98
165
  },
99
166
  updated: (ctx, event) => {
100
- const idx = ctx.stack.findIndex((entry) => entry.id === event.id)
101
- if (idx === -1) return ctx
102
- const record = ctx.stack[idx]!
167
+ const idx = ctx.stack.findIndex((entry) => entry.id === event.id);
168
+ if (idx === -1) {
169
+ return ctx;
170
+ }
171
+ const record = ctx.stack[idx];
172
+ if (record === undefined) {
173
+ return ctx;
174
+ }
103
175
  const payload =
104
- typeof event.next === "function"
105
- ? (event.next as (prev: unknown) => unknown)(record.payload)
106
- : event.next
107
- const stack = [...ctx.stack]
108
- stack[idx] = { ...record, payload }
109
- return { stack }
110
- },
111
- closed: (ctx, event, enqueue) => {
112
- const record = ctx.stack.find((entry) => entry.id === event.id)
113
- if (!record) return ctx
114
- enqueue.emit.closed({
115
- record,
116
- reason: event.reason,
117
- restoreModeTo: restoreModeDecision(ctx.stack, record),
118
- })
119
- return { stack: ctx.stack.filter((entry) => entry !== record) }
120
- },
121
- closedTop: (ctx, event, enqueue) => {
122
- if (ctx.stack.length === 0) return ctx
123
- const record = ctx.stack[ctx.stack.length - 1]!
124
- enqueue.emit.closed({
125
- record,
126
- reason: event.reason,
127
- restoreModeTo: restoreModeDecision(ctx.stack, record),
128
- })
129
- return { stack: ctx.stack.slice(0, -1) }
176
+ event.next.kind === "updater" ? event.next.update(record.payload) : event.next.value;
177
+ const stack = [...ctx.stack];
178
+ stack[idx] = { ...record, payload };
179
+ return { stack };
130
180
  },
131
181
  },
132
- })
133
- }
182
+ });
183
+ };
134
184
 
135
- export type OverlayStore = ReturnType<typeof createOverlayStore>
185
+ export type OverlayStore = ReturnType<typeof createOverlayStore>;
136
186
 
137
187
  // --- Selectors ---------------------------------------------------------------
138
188
 
139
- export function selectStack(ctx: OverlayStoreContext): readonly OverlayRecord[] {
140
- return ctx.stack
141
- }
189
+ export const selectStack = function selectStack(
190
+ ctx: OverlayStoreContext,
191
+ ): readonly OverlayRecord[] {
192
+ return ctx.stack;
193
+ };
142
194
 
143
- export function selectTop(ctx: OverlayStoreContext): OverlayRecord | null {
144
- return ctx.stack.length > 0 ? ctx.stack[ctx.stack.length - 1]! : null
145
- }
195
+ export const selectTop = function selectTop(ctx: OverlayStoreContext): OverlayRecord | null {
196
+ return ctx.stack.at(-1) ?? null;
197
+ };
146
198
 
147
- export function selectHasOverlay(ctx: OverlayStoreContext): boolean {
148
- return ctx.stack.length > 0
149
- }
199
+ export const selectHasOverlay = function selectHasOverlay(ctx: OverlayStoreContext): boolean {
200
+ return ctx.stack.length > 0;
201
+ };
150
202
 
151
- export function selectIsOpen(ctx: OverlayStoreContext, id: OverlayId): boolean {
152
- return ctx.stack.some((entry) => entry.id === id)
153
- }
203
+ export const selectIsOpen = function selectIsOpen(
204
+ ctx: OverlayStoreContext,
205
+ id: OverlayId,
206
+ ): boolean {
207
+ return ctx.stack.some((entry) => entry.id === id);
208
+ };
154
209
 
155
210
  /** Fresh array; prefer selectStack identity + memo in render paths. */
156
- export function selectStackIds(ctx: OverlayStoreContext): readonly OverlayId[] {
157
- return ctx.stack.map((entry) => entry.id)
158
- }
211
+ export const selectStackIds = function selectStackIds(
212
+ ctx: OverlayStoreContext,
213
+ ): readonly OverlayId[] {
214
+ return ctx.stack.map((entry) => entry.id);
215
+ };