react-x11 2.16.0 → 2.17.0

package/src/windowid.js

@@ -8,6 +8,7 @@
 import { useCallback, useMemo } from 'react';
 
 import { useAppOrNull } from './appcontext.js';
+import { canEmbed } from './embedding.js';
 
 /**
  * The XID of the X11 window a ref points at, or `null` if there is not one
@@ -62,6 +63,71 @@ export function windowOf(target) {
   return null;
 }
 
+/**
+ * The handle **another process** embeds to show this window, or `null` if
+ * this backend cannot hand one out.
+ *
+ * `<window embeddable>` is how a window says "created, not shown; somebody
+ * else will place me" — the guest half of embedding, on every backend. This
+ * is the number that goes with it, and it is deliberately not `windowIdOf`:
+ * on X11 the two are the same, and everywhere else they are not.
+ *
+ * - **X11** — the window's XID. The same number in every process on the
+ *   display, which is why one function answered both questions there and
+ *   why nobody noticed they were two questions.
+ * - **Windows** — a **composition surface handle**, already valid in the
+ *   host process. A window cannot be embedded here at all: a composition
+ *   target stops presenting the moment its window becomes a child, measured
+ *   in docs/windows-embedding.md. So what crosses is the buffer, and the
+ *   host binds it to a visual of its own instead of reparenting. The host is
+ *   the parent process by default — `createRoot({ win32: { paneHostPid } })`
+ *   when it is not.
+ * - **Anything else** — `null`. Not an error: it is the capability, and the
+ *   honest answer for a backend with no way to be a guest.
+ *
+ * The handle is a number to be passed out of band, exactly as an XID is —
+ * argv, an environment variable, a message on a pipe. What the host does
+ * with it is the host's business and differs per platform; what an app
+ * writes to *get* it does not.
+ *
+ * ```jsx
+ * const guest = useRef(null);
+ * useEffect(() => {
+ *   const handle = windowHandleOf(guest);
+ *   if (handle !== null) process.send?.({ type: 'embed-me', handle });
+ * }, []);
+ * return <window ref={guest} embeddable />;
+ * ```
+ */
+export function windowHandleOf(target) {
+  const wnd = windowOf(target);
+  if (!wnd) return null;
+  // A backend that publishes something other than its window says so with a
+  // method, because only it knows what that something is.
+  if (typeof wnd.embedHandle === 'function') return wnd.embedHandle();
+  // …and where windows themselves are embeddable, the window id is it. The
+  // same question `<foreign>` asks before it builds a socket, so the two
+  // halves of embedding cannot disagree about whether this one works.
+  if (canEmbed(wnd.app ?? null)) return windowIdOf(wnd);
+  return null;
+}
+
+/**
+ * `windowHandleOf` bound to a ref: a **getter**, stable across renders — the
+ * shape `useWindowId` has, and for the same reason. A window is not realized
+ * on the render that declares it, so a value read then would be null on the
+ * render that matters.
+ *
+ * ```js
+ * const handle = useWindowHandle(guestRef);
+ * // …later, in an effect, once the tree is mounted:
+ * const forTheHost = handle();
+ * ```
+ */
+export function useWindowHandle(ref) {
+  return useCallback(() => windowHandleOf(ref), [ref]);
+}
+
 /**
  * `windowIdOf` bound to a ref: returns a **getter**, stable across renders,
  * the same shape `useAnchor` has. It is a getter rather than the id itself
@@ -105,8 +171,54 @@ export function topLevelWindows(app) {
   );
 }
 
+/**
+ * The root-level `<popup>`s this connection is currently rendering — the
+ * half `topLevelWindows()` leaves out, in the order they were added.
+ *
+ * Only interesting when there are no top-level windows at all: a menu-bar
+ * app whose whole UI is a popover a tray click opens has no `<window>` for
+ * anything to belong to, and the popup *is* the top of that tree
+ * (`useTopLevelWindow`). With a window in the tree these stay out of it, for
+ * the reason they are out of `topLevelWindows()` — override-redirect is
+ * never what a dialog should be transient for.
+ */
+function rootLevelPopups(app) {
+  if (!app) return [];
+  return (app._rootChildren ?? []).filter(
+    (node) => node?.isWindow && node.isPopup && node.window?.id,
+  );
+}
+
 let warnedAboutAmbiguity = false;
 
+/**
+ * One of several candidates, on the inference `useTopLevelWindow` documents:
+ * one is exact, uniquely focused wins, and anything else is the most
+ * recently opened plus a development warning that says so.
+ */
+function pickOwner(candidates, what) {
+  if (candidates.length <= 1) return candidates[0] ?? null;
+
+  const focused = candidates.filter((w) => w.events?.windowFocused);
+  if (focused.length === 1) return focused[0];
+
+  // Nothing separates them. `windowFocused` also defaults to true on an
+  // ntk too old to report focus changes, so "all of them" is the same
+  // answer as "none of them" and both land here.
+  if (process.env.NODE_ENV !== 'production' && !warnedAboutAmbiguity) {
+    warnedAboutAmbiguity = true;
+    console.warn(
+      `react-x11: this tree has ${candidates.length} ${what}, none of them ` +
+        'uniquely focused, so the owner window is a guess (the most ' +
+        'recently opened). Pass the window explicitly to be exact:\n' +
+        '  const win = useRef(null);\n' +
+        '  const { openFile } = useFileDialog({ parentWindow: win });\n' +
+        '  return <window ref={win}>…</window>;',
+    );
+  }
+  return candidates[candidates.length - 1];
+}
+
 /**
  * The window a component belongs to, resolved when it is read.
  *
@@ -134,6 +246,13 @@ let warnedAboutAmbiguity = false;
  * - several with nothing to separate them: the most recently opened, and a
  *   development warning naming `parentWindow` as the way to be exact. A
  *   guess that says it is guessing beats a guess that does not.
+ * - **no top-level window at all: the root-level `<popup>` that has the
+ *   keyboard.** A menu-bar app is a tray item and a popover, and nothing
+ *   else — there is no `<window>` for a shortcut, a file dialog or the
+ *   global menu to belong to, and answering `null` made every one of them
+ *   quietly do nothing (issue #616). A `grabKeyboard` popup is where the
+ *   keys are by construction, so it is preferred over one that is merely
+ *   up; among equals the same focus/most-recent inference applies.
  *
  * Returns a **ref-like object** rather than a number: the window is not
  * realized on the first render, so a value read then would be `null` on the
@@ -146,27 +265,16 @@ export function useTopLevelWindow() {
     () => ({
       get current() {
         const windows = topLevelWindows(app);
-        if (windows.length <= 1) return windows[0] ?? null;
-
-        const focused = windows.filter((w) => w.events?.windowFocused);
-        if (focused.length === 1) return focused[0];
+        if (windows.length) return pickOwner(windows, 'top-level windows');
 
-        // Nothing separates them. `windowFocused` also defaults to true on an
-        // ntk too old to report focus changes, so "all of them" is the same
-        // answer as "none of them" and both land here.
-        if (process.env.NODE_ENV !== 'production' && !warnedAboutAmbiguity) {
-          warnedAboutAmbiguity = true;
-          console.warn(
-            `react-x11: this tree has ${windows.length} top-level windows and ` +
-              'none of them is uniquely focused, so the owner window is a ' +
-              'guess (the most recently opened). Pass the window explicitly ' +
-              'to be exact:\n' +
-              '  const win = useRef(null);\n' +
-              '  const { openFile } = useFileDialog({ parentWindow: win });\n' +
-              '  return <window ref={win}>…</window>;',
-          );
-        }
-        return windows[windows.length - 1];
+        // A popup-only tree — the tray popover. Not reached while the app
+        // has a window, so nothing that already worked changes shape.
+        const popups = rootLevelPopups(app);
+        const keyboard = popups.filter((node) => node.props?.grabKeyboard);
+        return pickOwner(
+          keyboard.length ? keyboard : popups,
+          'root-level popups and no window at all',
+        );
       },
     }),
     [app],