@tooee/overlays 0.1.20 → 0.1.21

package/dist/index.d.ts

@@ -1,3 +1,5 @@
-export { OverlayContext, OverlayControllerContext, OverlayStateContext, useOverlay, useOverlayState, useCurrentOverlay, useHasOverlay, } from "./overlay-context.js";
+export { OverlayContext, OverlayControllerContext, OverlayStateContext, useOverlay, useOverlayState, useCurrentOverlay, useHasOverlay, useHasModalOverlay, } from "./overlay-context.js";
 export type { OverlayContextValue, OverlayId, OverlayCloseReason, OverlayOpenOptions, OverlayRole, OverlayRenderArgs, OverlayRenderer, OverlayHandle, OverlayController, OverlayState, } from "./overlay-context.js";
+export { createOverlayStore, selectHasOverlay, selectIsOpen, selectStack, selectStackIds, selectTop, } from "./overlay-store.js";
+export type { OverlayClosedEmit, OverlayRecord, OverlayStore, OverlayStoreContext, } from "./overlay-store.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,GACd,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EACV,mBAAmB,EACnB,SAAS,EACT,kBAAkB,EAClB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,cAAc,EACd,SAAS,GACV,MAAM,oBAAoB,CAAA;AAC3B,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,mBAAmB,GACpB,MAAM,oBAAoB,CAAA"}

package/dist/index.js

@@ -1,2 +1,3 @@
-export { OverlayContext, OverlayControllerContext, OverlayStateContext, useOverlay, useOverlayState, useCurrentOverlay, useHasOverlay, } from "./overlay-context.js";
+export { OverlayContext, OverlayControllerContext, OverlayStateContext, useOverlay, useOverlayState, useCurrentOverlay, useHasOverlay, useHasModalOverlay, } from "./overlay-context.js";
+export { createOverlayStore, selectHasOverlay, selectIsOpen, selectStack, selectStackIds, selectTop, } from "./overlay-store.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,GACd,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACnB,MAAM,sBAAsB,CAAA;AAa7B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,cAAc,EACd,SAAS,GACV,MAAM,oBAAoB,CAAA"}

package/dist/overlay-context.d.ts

@@ -52,6 +52,13 @@ export interface OverlayController {
 export interface OverlayState {
     current: ReactNode | null;
     hasOverlay: boolean;
+    /**
+     * True when any overlay other than a passive owned surface is open. Passive
+     * surfaces (e.g. the which-key hint) render for visuals only and never own
+     * input, so they don't count. Use this for guards that should stand down
+     * while a modal overlay is up but keep working under passive hints.
+     */
+    hasModalOverlay: boolean;
     stack: OverlayId[];
 }
 export interface OverlayContextValue {
@@ -66,5 +73,6 @@ export declare const OverlayContext: import("react").Context<OverlayContextValue
 export declare function useOverlay(): OverlayController;
 export declare function useOverlayState(): OverlayState;
 export declare function useHasOverlay(): boolean;
+export declare function useHasModalOverlay(): boolean;
 export declare function useCurrentOverlay(): ReactNode | null;
 //# sourceMappingURL=overlay-context.d.ts.map

package/dist/overlay-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlay-context.d.ts","sourceRoot":"","sources":["../src/overlay-context.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"overlay-context.d.ts","sourceRoot":"","sources":["../src/overlay-context.tsx"],"names":[],"mappings":"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"}

package/dist/overlay-context.js

@@ -12,6 +12,7 @@ const defaultController = {
 const defaultState = {
     current: null,
     hasOverlay: false,
+    hasModalOverlay: false,
     stack: [],
 };
 export const OverlayControllerContext = createContext(defaultController);
@@ -33,6 +34,9 @@ export function useOverlayState() {
 export function useHasOverlay() {
     return useContext(OverlayStateContext).hasOverlay;
 }
+export function useHasModalOverlay() {
+    return useContext(OverlayStateContext).hasModalOverlay;
+}
 export function useCurrentOverlay() {
     return useContext(OverlayStateContext).current;
 }

package/dist/overlay-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"overlay-context.js","sourceRoot":"","sources":["../src/overlay-context.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAkFjD,WAAW;AAEX,MAAM,iBAAiB,GAAsB;IAC3C,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;IACzD,MAAM,EAAE,GAAG,EAAE,GAAE,CAAC;IAChB,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC;IAClB,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK;IACnB,KAAK,EAAE,IAAI;CACZ,CAAA;AAED,MAAM,YAAY,GAAiB;IACjC,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,KAAK;IACjB,KAAK,EAAE,EAAE;CACV,CAAA;AAED,MAAM,CAAC,MAAM,wBAAwB,GAAG,aAAa,CAAoB,iBAAiB,CAAC,CAAA;AAC3F,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAe,YAAY,CAAC,CAAA;AAE5E,mFAAmF;AACnF,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAsB;IAC/D,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,KAAK;CAClB,CAAC,CAAA;AAEF,QAAQ;AAER,MAAM,UAAU,UAAU;IACxB,OAAO,UAAU,CAAC,wBAAwB,CAAC,CAAA;AAC7C,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAA;AACxC,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAC,UAAU,CAAA;AACnD,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAC,OAAO,CAAA;AAChD,CAAC"}
+{"version":3,"file":"overlay-context.js","sourceRoot":"","sources":["../src/overlay-context.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA;AAyFjD,WAAW;AAEX,MAAM,iBAAiB,GAAsB;IAC3C,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;IACzD,MAAM,EAAE,GAAG,EAAE,GAAE,CAAC;IAChB,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,QAAQ,EAAE,GAAG,EAAE,GAAE,CAAC;IAClB,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK;IACnB,KAAK,EAAE,IAAI;CACZ,CAAA;AAED,MAAM,YAAY,GAAiB;IACjC,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,KAAK;IACjB,eAAe,EAAE,KAAK;IACtB,KAAK,EAAE,EAAE;CACV,CAAA;AAED,MAAM,CAAC,MAAM,wBAAwB,GAAG,aAAa,CAAoB,iBAAiB,CAAC,CAAA;AAC3F,MAAM,CAAC,MAAM,mBAAmB,GAAG,aAAa,CAAe,YAAY,CAAC,CAAA;AAE5E,mFAAmF;AACnF,MAAM,CAAC,MAAM,cAAc,GAAG,aAAa,CAAsB;IAC/D,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,KAAK;CAClB,CAAC,CAAA;AAEF,QAAQ;AAER,MAAM,UAAU,UAAU;IACxB,OAAO,UAAU,CAAC,wBAAwB,CAAC,CAAA;AAC7C,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAA;AACxC,CAAC;AAED,MAAM,UAAU,aAAa;IAC3B,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAC,UAAU,CAAA;AACnD,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAC,eAAe,CAAA;AACxD,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,CAAC,mBAAmB,CAAC,CAAC,OAAO,CAAA;AAChD,CAAC"}

package/dist/overlay-store.d.ts

@@ -0,0 +1,72 @@
+import type { OverlayCloseReason, OverlayId, OverlayOpenOptions, OverlayRenderer } from "./overlay-context.js";
+/**
+ * An overlay stack entry as tracked by the store. `prevMode` is the host mode
+ * captured at open time (mode itself stays outside this package — see the
+ * shell's OverlayProvider, which owns all mode side effects).
+ */
+export interface OverlayRecord<TPayload = unknown> {
+    id: OverlayId;
+    render: OverlayRenderer<TPayload>;
+    payload: TPayload;
+    options: OverlayOpenOptions;
+    prevMode: string;
+}
+export interface OverlayStoreContext {
+    stack: readonly OverlayRecord[];
+}
+/**
+ * Emitted when a record leaves the stack (close, closeTop, or same-id
+ * replacement). Lifecycle side effects (onClose callbacks, mode restoration,
+ * sequence-reset bridges) are performed by the adapter subscribed via
+ * `store.on("closed", ...)`; transitions stay pure.
+ */
+export interface OverlayClosedEmit {
+    record: OverlayRecord;
+    reason: OverlayCloseReason;
+    /**
+     * Legacy mode restoration decision, computed in the transition (it needs
+     * stack state): `record.prevMode` when the record is non-ownCommands,
+     * `restoreMode !== false`, AND it was the topmost non-ownCommands entry
+     * (closing a buried legacy overlay must not clobber the mode set by the one
+     * above it — R-04); otherwise null. Same-id replacement displacement never
+     * restores (the successor takes over).
+     */
+    restoreModeTo: string | null;
+}
+/**
+ * Event payload map, passed explicitly as a `createStore` generic
+ * (@xstate/store v4 removed the `emits` config; event/emitted types come from
+ * generics or `schemas`). Both maps here are deliberately CLOSED — no index
+ * signatures — so unknown `store.trigger.*` / `store.send` / `store.on` /
+ * `enqueue.emit.*` event names are compile errors (pinned by
+ * `overlay-store.typecheck.ts`). The v4 `schemas.emitted` alternative was
+ * evaluated and rejected: it gives the same strictness while adding runtime
+ * schema objects this store does not need.
+ */
+export type OverlayStoreEvents = {
+    opened: {
+        record: OverlayRecord;
+    };
+    updated: {
+        id: OverlayId;
+        next: unknown | ((prev: unknown) => unknown);
+    };
+    closed: {
+        id: OverlayId;
+        reason: OverlayCloseReason;
+    };
+    closedTop: {
+        reason: OverlayCloseReason;
+    };
+};
+export declare function createOverlayStore(): import("@xstate/store").Store<OverlayStoreContext, OverlayStoreEvents, OverlayClosedEmit & {
+    type: "closed";
+}>;
+export type OverlayStore = ReturnType<typeof createOverlayStore>;
+export declare function selectStack(ctx: OverlayStoreContext): readonly OverlayRecord[];
+export declare function selectTop(ctx: OverlayStoreContext): OverlayRecord | null;
+export declare function selectHasOverlay(ctx: OverlayStoreContext): boolean;
+export declare function selectIsOpen(ctx: OverlayStoreContext, id: OverlayId): boolean;
+/** Fresh array; prefer selectStack identity + memo in render paths. */
+export declare function selectStackIds(ctx: OverlayStoreContext): readonly OverlayId[];
+//# sourceMappingURL=overlay-store.d.ts.map

package/dist/overlay-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-store.d.ts","sourceRoot":"","sources":["../src/overlay-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAClB,SAAS,EACT,kBAAkB,EAClB,eAAe,EAChB,MAAM,sBAAsB,CAAA;AAE7B;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,QAAQ,GAAG,OAAO;IAC/C,EAAE,EAAE,SAAS,CAAA;IACb,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAA;IACjC,OAAO,EAAE,QAAQ,CAAA;IACjB,OAAO,EAAE,kBAAkB,CAAA;IAC3B,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAA;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,aAAa,CAAA;IACrB,MAAM,EAAE,kBAAkB,CAAA;IAC1B;;;;;;;OAOG;IACH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAC7B;AAgBD;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE;QAAE,MAAM,EAAE,aAAa,CAAA;KAAE,CAAA;IACjC,OAAO,EAAE;QAAE,EAAE,EAAE,SAAS,CAAC;QAAC,IAAI,EAAE,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,CAAA;KAAE,CAAA;IACxE,MAAM,EAAE;QAAE,EAAE,EAAE,SAAS,CAAC;QAAC,MAAM,EAAE,kBAAkB,CAAA;KAAE,CAAA;IACrD,SAAS,EAAE;QAAE,MAAM,EAAE,kBAAkB,CAAA;KAAE,CAAA;CAC1C,CAAA;AAOD,wBAAgB,kBAAkB;;GAmDjC;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAA;AAIhE,wBAAgB,WAAW,CAAC,GAAG,EAAE,mBAAmB,GAAG,SAAS,aAAa,EAAE,CAE9E;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,mBAAmB,GAAG,aAAa,GAAG,IAAI,CAExE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAElE;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,mBAAmB,EAAE,EAAE,EAAE,SAAS,GAAG,OAAO,CAE7E;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAAC,GAAG,EAAE,mBAAmB,GAAG,SAAS,SAAS,EAAE,CAE7E"}

package/dist/overlay-store.js

@@ -0,0 +1,84 @@
+import { createStore } from "@xstate/store";
+/**
+ * Owned command surfaces keep their mode local; the host mode was never
+ * mutated on open, so there is nothing to restore. For legacy entries, only
+ * the topmost non-ownCommands overlay owns the host mode.
+ */
+function restoreModeDecision(stack, record) {
+    if (record.options.ownCommands || record.options.restoreMode === false)
+        return null;
+    const topLegacy = stack.findLast((entry) => !entry.options.ownCommands);
+    return topLegacy === record ? record.prevMode : null;
+}
+export function createOverlayStore() {
+    return createStore({
+        context: { stack: [] },
+        on: {
+            opened: (ctx, event, enqueue) => {
+                // Replacing an existing same-id entry closes it: consumers release
+                // open-state (e.g. a picker's isOpen) via the contract's "replaced"
+                // reason instead of the entry being silently filtered away.
+                const displaced = ctx.stack.find((entry) => entry.id === event.record.id);
+                if (displaced) {
+                    enqueue.emit.closed({ record: displaced, reason: "replaced", restoreModeTo: null });
+                }
+                const filtered = displaced
+                    ? ctx.stack.filter((entry) => entry.id !== event.record.id)
+                    : ctx.stack;
+                return { stack: [...filtered, event.record] };
+            },
+            updated: (ctx, event) => {
+                const idx = ctx.stack.findIndex((entry) => entry.id === event.id);
+                if (idx === -1)
+                    return ctx;
+                const record = ctx.stack[idx];
+                const payload = typeof event.next === "function"
+                    ? event.next(record.payload)
+                    : event.next;
+                const stack = [...ctx.stack];
+                stack[idx] = { ...record, payload };
+                return { stack };
+            },
+            closed: (ctx, event, enqueue) => {
+                const record = ctx.stack.find((entry) => entry.id === event.id);
+                if (!record)
+                    return ctx;
+                enqueue.emit.closed({
+                    record,
+                    reason: event.reason,
+                    restoreModeTo: restoreModeDecision(ctx.stack, record),
+                });
+                return { stack: ctx.stack.filter((entry) => entry !== record) };
+            },
+            closedTop: (ctx, event, enqueue) => {
+                if (ctx.stack.length === 0)
+                    return ctx;
+                const record = ctx.stack[ctx.stack.length - 1];
+                enqueue.emit.closed({
+                    record,
+                    reason: event.reason,
+                    restoreModeTo: restoreModeDecision(ctx.stack, record),
+                });
+                return { stack: ctx.stack.slice(0, -1) };
+            },
+        },
+    });
+}
+// --- Selectors ---------------------------------------------------------------
+export function selectStack(ctx) {
+    return ctx.stack;
+}
+export function selectTop(ctx) {
+    return ctx.stack.length > 0 ? ctx.stack[ctx.stack.length - 1] : null;
+}
+export function selectHasOverlay(ctx) {
+    return ctx.stack.length > 0;
+}
+export function selectIsOpen(ctx, id) {
+    return ctx.stack.some((entry) => entry.id === id);
+}
+/** Fresh array; prefer selectStack identity + memo in render paths. */
+export function selectStackIds(ctx) {
+    return ctx.stack.map((entry) => entry.id);
+}
+//# sourceMappingURL=overlay-store.js.map

package/dist/overlay-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-store.js","sourceRoot":"","sources":["../src/overlay-store.ts"],"names":[],"mappings":"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"}

package/dist/overlay-store.typecheck.d.ts

@@ -0,0 +1,2 @@
+export declare function overlayStoreTypeChecks(): void;
+//# sourceMappingURL=overlay-store.typecheck.d.ts.map

package/dist/overlay-store.typecheck.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-store.typecheck.d.ts","sourceRoot":"","sources":["../src/overlay-store.typecheck.ts"],"names":[],"mappings":"AAoBA,wBAAgB,sBAAsB,IAAI,IAAI,CA4B7C"}

package/dist/overlay-store.typecheck.js

@@ -0,0 +1,29 @@
+import { createOverlayStore } from "./overlay-store.js";
+// Never called; exists only to be typechecked.
+export function overlayStoreTypeChecks() {
+    const store = createOverlayStore();
+    // --- Valid usage must compile -------------------------------------------
+    store.trigger.opened({ record });
+    store.trigger.updated({ id: "x", next: null });
+    store.trigger.closed({ id: "x", reason });
+    store.trigger.closedTop({ reason });
+    store.send({ type: "closedTop", reason });
+    store.on("closed", (emitted) => {
+        const _reason = emitted.reason;
+        const _restoreModeTo = emitted.restoreModeTo;
+        const _record = emitted.record;
+    });
+    // --- Unknown event names must NOT compile --------------------------------
+    // @ts-expect-error unknown trigger event name
+    store.trigger.bogusEvent({});
+    // @ts-expect-error unknown send event type
+    store.send({ type: "bogusEvent" });
+    // @ts-expect-error unknown emitted event name
+    store.on("bogusEmit", () => { });
+    // --- Wrong payloads must NOT compile --------------------------------------
+    // @ts-expect-error reason must be an OverlayCloseReason
+    store.trigger.closedTop({ reason: 42 });
+    // @ts-expect-error record is required
+    store.trigger.opened({});
+}
+//# sourceMappingURL=overlay-store.typecheck.js.map

package/dist/overlay-store.typecheck.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-store.typecheck.js","sourceRoot":"","sources":["../src/overlay-store.typecheck.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,kBAAkB,EAAsB,MAAM,oBAAoB,CAAA;AAK3E,+CAA+C;AAC/C,MAAM,UAAU,sBAAsB;IACpC,MAAM,KAAK,GAAG,kBAAkB,EAAE,CAAA;IAElC,2EAA2E;IAC3E,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;IAChC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC9C,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAA;IACzC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;IACnC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,CAAA;IACzC,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,OAAO,GAAuB,OAAO,CAAC,MAAM,CAAA;QAClD,MAAM,cAAc,GAAkB,OAAO,CAAC,aAAa,CAAA;QAC3D,MAAM,OAAO,GAAkB,OAAO,CAAC,MAAM,CAAA;IAC/C,CAAC,CAAC,CAAA;IAEF,4EAA4E;IAC5E,8CAA8C;IAC9C,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IAC5B,2CAA2C;IAC3C,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAA;IAClC,8CAA8C;IAC9C,KAAK,CAAC,EAAE,CAAC,WAAW,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;IAE/B,6EAA6E;IAC7E,wDAAwD;IACxD,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAA;IACvC,sCAAsC;IACtC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tooee/overlays",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Overlay stack management for Tooee",
   "keywords": [
     "cli",
@@ -33,6 +33,9 @@
   "scripts": {
     "typecheck": "tsc --noEmit"
   },
+  "dependencies": {
+    "@xstate/store": "^4"
+  },
   "devDependencies": {
     "@types/bun": "^1.3.10",
     "@types/react": "^19.2.14",

package/src/index.ts

@@ -6,6 +6,7 @@ export {
   useOverlayState,
   useCurrentOverlay,
   useHasOverlay,
+  useHasModalOverlay,
 } from "./overlay-context.js"
 export type {
   OverlayContextValue,
@@ -19,3 +20,17 @@ export type {
   OverlayController,
   OverlayState,
 } from "./overlay-context.js"
+export {
+  createOverlayStore,
+  selectHasOverlay,
+  selectIsOpen,
+  selectStack,
+  selectStackIds,
+  selectTop,
+} from "./overlay-store.js"
+export type {
+  OverlayClosedEmit,
+  OverlayRecord,
+  OverlayStore,
+  OverlayStoreContext,
+} from "./overlay-store.js"

package/src/overlay-context.tsx

@@ -69,6 +69,13 @@ export interface OverlayController {
 export interface OverlayState {
   current: ReactNode | null
   hasOverlay: boolean
+  /**
+   * True when any overlay other than a passive owned surface is open. Passive
+   * surfaces (e.g. the which-key hint) render for visuals only and never own
+   * input, so they don't count. Use this for guards that should stand down
+   * while a modal overlay is up but keep working under passive hints.
+   */
+  hasModalOverlay: boolean
   stack: OverlayId[]
 }
 
@@ -95,6 +102,7 @@ const defaultController: OverlayController = {
 const defaultState: OverlayState = {
   current: null,
   hasOverlay: false,
+  hasModalOverlay: false,
   stack: [],
 }
 
@@ -123,6 +131,10 @@ export function useHasOverlay(): boolean {
   return useContext(OverlayStateContext).hasOverlay
 }
 
+export function useHasModalOverlay(): boolean {
+  return useContext(OverlayStateContext).hasModalOverlay
+}
+
 export function useCurrentOverlay(): ReactNode | null {
   return useContext(OverlayStateContext).current
 }

package/src/overlay-store.ts

@@ -0,0 +1,158 @@
+import { createStore } from "@xstate/store"
+import type {
+  OverlayCloseReason,
+  OverlayId,
+  OverlayOpenOptions,
+  OverlayRenderer,
+} from "./overlay-context.js"
+
+/**
+ * An overlay stack entry as tracked by the store. `prevMode` is the host mode
+ * captured at open time (mode itself stays outside this package — see the
+ * shell's OverlayProvider, which owns all mode side effects).
+ */
+export interface OverlayRecord<TPayload = unknown> {
+  id: OverlayId
+  render: OverlayRenderer<TPayload>
+  payload: TPayload
+  options: OverlayOpenOptions
+  prevMode: string
+}
+
+export interface OverlayStoreContext {
+  stack: readonly OverlayRecord[]
+}
+
+/**
+ * Emitted when a record leaves the stack (close, closeTop, or same-id
+ * replacement). Lifecycle side effects (onClose callbacks, mode restoration,
+ * sequence-reset bridges) are performed by the adapter subscribed via
+ * `store.on("closed", ...)`; transitions stay pure.
+ */
+export interface OverlayClosedEmit {
+  record: OverlayRecord
+  reason: OverlayCloseReason
+  /**
+   * Legacy mode restoration decision, computed in the transition (it needs
+   * stack state): `record.prevMode` when the record is non-ownCommands,
+   * `restoreMode !== false`, AND it was the topmost non-ownCommands entry
+   * (closing a buried legacy overlay must not clobber the mode set by the one
+   * above it — R-04); otherwise null. Same-id replacement displacement never
+   * restores (the successor takes over).
+   */
+  restoreModeTo: string | null
+}
+
+/**
+ * Owned command surfaces keep their mode local; the host mode was never
+ * mutated on open, so there is nothing to restore. For legacy entries, only
+ * the topmost non-ownCommands overlay owns the host mode.
+ */
+function restoreModeDecision(
+  stack: readonly OverlayRecord[],
+  record: OverlayRecord,
+): string | null {
+  if (record.options.ownCommands || record.options.restoreMode === false) return null
+  const topLegacy = stack.findLast((entry) => !entry.options.ownCommands)
+  return topLegacy === record ? record.prevMode : null
+}
+
+/**
+ * Event payload map, passed explicitly as a `createStore` generic
+ * (@xstate/store v4 removed the `emits` config; event/emitted types come from
+ * generics or `schemas`). Both maps here are deliberately CLOSED — no index
+ * signatures — so unknown `store.trigger.*` / `store.send` / `store.on` /
+ * `enqueue.emit.*` event names are compile errors (pinned by
+ * `overlay-store.typecheck.ts`). The v4 `schemas.emitted` alternative was
+ * evaluated and rejected: it gives the same strictness while adding runtime
+ * schema objects this store does not need.
+ */
+export type OverlayStoreEvents = {
+  opened: { record: OverlayRecord }
+  updated: { id: OverlayId; next: unknown | ((prev: unknown) => unknown) }
+  closed: { id: OverlayId; reason: OverlayCloseReason }
+  closedTop: { reason: OverlayCloseReason }
+}
+
+/** Emitted payload map (see OverlayStoreEvents docs — deliberately closed). */
+type OverlayStoreEmitted = {
+  closed: OverlayClosedEmit
+}
+
+export function createOverlayStore() {
+  return createStore<OverlayStoreContext, OverlayStoreEvents, OverlayStoreEmitted>({
+    context: { stack: [] },
+    on: {
+      opened: (ctx, event, enqueue) => {
+        // Replacing an existing same-id entry closes it: consumers release
+        // open-state (e.g. a picker's isOpen) via the contract's "replaced"
+        // reason instead of the entry being silently filtered away.
+        const displaced = ctx.stack.find((entry) => entry.id === event.record.id)
+        if (displaced) {
+          enqueue.emit.closed({ record: displaced, reason: "replaced", restoreModeTo: null })
+        }
+        const filtered = displaced
+          ? ctx.stack.filter((entry) => entry.id !== event.record.id)
+          : ctx.stack
+        return { stack: [...filtered, event.record] }
+      },
+      updated: (ctx, event) => {
+        const idx = ctx.stack.findIndex((entry) => entry.id === event.id)
+        if (idx === -1) return ctx
+        const record = ctx.stack[idx]!
+        const payload =
+          typeof event.next === "function"
+            ? (event.next as (prev: unknown) => unknown)(record.payload)
+            : event.next
+        const stack = [...ctx.stack]
+        stack[idx] = { ...record, payload }
+        return { stack }
+      },
+      closed: (ctx, event, enqueue) => {
+        const record = ctx.stack.find((entry) => entry.id === event.id)
+        if (!record) return ctx
+        enqueue.emit.closed({
+          record,
+          reason: event.reason,
+          restoreModeTo: restoreModeDecision(ctx.stack, record),
+        })
+        return { stack: ctx.stack.filter((entry) => entry !== record) }
+      },
+      closedTop: (ctx, event, enqueue) => {
+        if (ctx.stack.length === 0) return ctx
+        const record = ctx.stack[ctx.stack.length - 1]!
+        enqueue.emit.closed({
+          record,
+          reason: event.reason,
+          restoreModeTo: restoreModeDecision(ctx.stack, record),
+        })
+        return { stack: ctx.stack.slice(0, -1) }
+      },
+    },
+  })
+}
+
+export type OverlayStore = ReturnType<typeof createOverlayStore>
+
+// --- Selectors ---------------------------------------------------------------
+
+export function selectStack(ctx: OverlayStoreContext): readonly OverlayRecord[] {
+  return ctx.stack
+}
+
+export function selectTop(ctx: OverlayStoreContext): OverlayRecord | null {
+  return ctx.stack.length > 0 ? ctx.stack[ctx.stack.length - 1]! : null
+}
+
+export function selectHasOverlay(ctx: OverlayStoreContext): boolean {
+  return ctx.stack.length > 0
+}
+
+export function selectIsOpen(ctx: OverlayStoreContext, id: OverlayId): boolean {
+  return ctx.stack.some((entry) => entry.id === id)
+}
+
+/** Fresh array; prefer selectStack identity + memo in render paths. */
+export function selectStackIds(ctx: OverlayStoreContext): readonly OverlayId[] {
+  return ctx.stack.map((entry) => entry.id)
+}

package/src/overlay-store.typecheck.ts

@@ -0,0 +1,49 @@
+/**
+ * Compile-time regression tests for the overlay store's event typing. This
+ * module has no runtime behaviour and is never imported; it exists so that
+ * `tsc -b` (which only checks `src/`) fails if the store's typing is ever
+ * loosened.
+ *
+ * The store's event/emitted payload maps (`OverlayStoreEvents`, the emitted
+ * map inside `overlay-store.ts`) are deliberately CLOSED — no index
+ * signatures. That makes unknown `store.trigger.*`, `store.send`,
+ * `store.on(...)`, and `enqueue.emit.*` event names compile errors. If one of
+ * the `@ts-expect-error` lines below starts compiling, the maps have been
+ * widened (e.g. an index signature was added); fix the maps, not this file.
+ */
+import type { OverlayCloseReason } from "./overlay-context.js"
+import { createOverlayStore, type OverlayRecord } from "./overlay-store.js"
+
+declare const record: OverlayRecord
+declare const reason: OverlayCloseReason
+
+// Never called; exists only to be typechecked.
+export function overlayStoreTypeChecks(): void {
+  const store = createOverlayStore()
+
+  // --- Valid usage must compile -------------------------------------------
+  store.trigger.opened({ record })
+  store.trigger.updated({ id: "x", next: null })
+  store.trigger.closed({ id: "x", reason })
+  store.trigger.closedTop({ reason })
+  store.send({ type: "closedTop", reason })
+  store.on("closed", (emitted) => {
+    const _reason: OverlayCloseReason = emitted.reason
+    const _restoreModeTo: string | null = emitted.restoreModeTo
+    const _record: OverlayRecord = emitted.record
+  })
+
+  // --- Unknown event names must NOT compile --------------------------------
+  // @ts-expect-error unknown trigger event name
+  store.trigger.bogusEvent({})
+  // @ts-expect-error unknown send event type
+  store.send({ type: "bogusEvent" })
+  // @ts-expect-error unknown emitted event name
+  store.on("bogusEmit", () => {})
+
+  // --- Wrong payloads must NOT compile --------------------------------------
+  // @ts-expect-error reason must be an OverlayCloseReason
+  store.trigger.closedTop({ reason: 42 })
+  // @ts-expect-error record is required
+  store.trigger.opened({})
+}