react-x11 1.2.0 → 2.0.0

package/src/extensions.js

@@ -0,0 +1,45 @@
+// Asking the server for an extension, once per connection.
+//
+// `X.require` caches the extension object only once its reply lands, so two
+// callers in the same tick both put a QueryExtension on the wire and one of
+// the answers is thrown away. That did not matter while each extension had a
+// single caller that awaited it in turn. It does now: the startup probes run
+// concurrently, and both the compositing watch and the XSETTINGS watch want
+// XFixes at the same moment.
+//
+// So the promise is memoized, not the result — a second caller arriving
+// while the first is still in flight subscribes to it instead of asking
+// again. Keyed per connection, and null (an extension the server does not
+// have) is cached like any other answer: it is a real reply, and re-asking
+// would put the same question back on the wire every time.
+const tables = new WeakMap();
+
+/**
+ * The extension object for `name` on this connection, or null when the
+ * server does not have it (or the connection cannot answer).
+ *
+ * @param {object} app the ntk App
+ * @param {string} name node-x11's extension name, e.g. 'fixes'
+ * @returns {Promise<object|null>}
+ */
+export function requireExtension(app, name) {
+  const X = app?.X;
+  if (!X || typeof X.require !== 'function') return Promise.resolve(null);
+  let table = tables.get(X);
+  if (!table) {
+    table = new Map();
+    tables.set(X, table);
+  }
+  let pending = table.get(name);
+  if (!pending) {
+    pending = new Promise((resolve) => {
+      try {
+        X.require(name, (err, ext) => resolve(err || !ext ? null : ext));
+      } catch {
+        resolve(null);
+      }
+    });
+    table.set(name, pending);
+  }
+  return pending;
+}

package/src/filedialog.js

@@ -0,0 +1,375 @@
+// Open, save, and pick a folder — through whatever this machine actually has.
+//
+// There is no one answer, so this is a ladder, tried in order:
+//
+//   1. **the portal** — `org.freedesktop.portal.FileChooser` over D-Bus. The
+//      real desktop dialog, with the user's bookmarks and recent files, drawn
+//      by GTK or KDE in another process. What a Linux desktop should get.
+//   2. **`osascript`** — macOS with no portal, which is every XQuartz install
+//      that has not gone out of its way. `choose file` is `NSOpenPanel`, so
+//      the user gets the dialog they know.
+//   3. **the built-in dialog** — a file browser drawn by react-x11 itself.
+//      Reached over ssh, under a bare `startx`, in a container: everywhere
+//      there is a display and nothing else. See `components/FileDialog.js`;
+//      it needs a React tree, so `useFileDialog()` has it and the bare
+//      functions here do not.
+//
+// The ladder is the whole design. A file dialog that only works on a full
+// GNOME session would be useless to the person running this over ssh from a
+// laptop, which is the case react-x11 exists for.
+//
+// ## What each rung cannot do
+//
+// - **The portal never embeds.** The dialog is a top-level window in another
+//   process; all you get is logical parenting, through `parent_window`. That
+//   is `transientFor` by another name, and it is why these calls want a window
+//   to point at.
+// - **macOS has no cross-process transient-for at all.** XQuartz windows are
+//   `NSWindow`s owned by X11.app, and `addChildWindow` is same-process only.
+//   So the panel appears over the app but is not attached to it. Application
+//   modality still works, because the caller is awaiting the promise.
+// - **The built-in dialog is ours**, so it is the only rung that can be
+//   modal-and-parented properly — and the only one that has never seen the
+//   user's bookmarks.
+
+import {
+  NoPortalError,
+  PORTAL_NAME,
+  PortalCancelledError,
+  RESPONSE_CANCELLED,
+  RESPONSE_OK,
+  hasService,
+  parentWindowHandle,
+  pathBytes,
+  portalRequest,
+  variant,
+} from './portal.js';
+import { sessionBus } from './bus.js';
+import { windowIdOf } from './windowid.js';
+
+const FILE_CHOOSER = 'org.freedesktop.portal.FileChooser';
+
+/**
+ * Nothing on this machine can show a file dialog, and nothing here can draw
+ * one either.
+ *
+ * Only the bare functions throw this — `useFileDialog()` has a tree to draw
+ * in, so it never runs out of rungs. It is a **typed** rejection because it is
+ * a fallback signal, not a crash: a caller that has its own UI branches on it.
+ */
+export class NoFileDialogError extends Error {
+  constructor(cause) {
+    super(
+      'react-x11: no file dialog is available — there is no ' +
+        'xdg-desktop-portal on the bus, and this is not macOS. Use ' +
+        'useFileDialog() instead, which draws one, or supply `backend`.',
+      { cause },
+    );
+    this.name = 'NoFileDialogError';
+  }
+}
+
+export { PortalCancelledError };
+
+// --------------------------------------------------------------------------
+// Options, in one shape, translated per backend
+// --------------------------------------------------------------------------
+
+/**
+ * `[{ name: 'Images', extensions: ['png', 'jpg'] }]` → the portal's
+ * `a(sa(us))`: a list of (label, [(type, pattern)]) where type 0 is a glob and
+ * 1 is a MIME type.
+ *
+ * Extensions are turned into globs here rather than asking callers for
+ * `*.png`, because every other file-dialog API in the world takes extensions
+ * and the glob is a portal implementation detail.
+ */
+function portalFilters(filters) {
+  return filters.map((f) => [
+    f.name ?? '',
+    [
+      ...(f.extensions ?? []).map((ext) => [
+        0,
+        `*.${String(ext).replace(/^[.*]*\.?/, '')}`,
+      ]),
+      ...(f.mimeTypes ?? []).map((type) => [1, type]),
+    ],
+  ]);
+}
+
+async function portalOptions(opts, { save, directory }) {
+  const options = {};
+  if (opts.acceptLabel) options.accept_label = opts.acceptLabel;
+  if (opts.multiple && !save) options.multiple = true;
+  if (directory) options.directory = true;
+  if (opts.modal !== false) options.modal = true;
+  if (opts.filters?.length) {
+    options.filters = await variant('a(sa(us))', portalFilters(opts.filters));
+  }
+  // Paths are NUL-terminated byte arrays here, not strings. A string marshals
+  // as `s` and the backend ignores it without saying so.
+  if (opts.defaultFolder)
+    options.current_folder = pathBytes(opts.defaultFolder);
+  if (save && opts.defaultName) options.current_name = opts.defaultName;
+  if (save && opts.defaultPath)
+    options.current_file = pathBytes(opts.defaultPath);
+  return options;
+}
+
+/** `file:///a/b%20c` → `/a/b c`. Anything not a file: URI is dropped. */
+async function urisToPaths(uris) {
+  const { fileURLToPath } = await import('node:url');
+  const out = [];
+  for (const uri of uris ?? []) {
+    if (typeof uri !== 'string') continue;
+    try {
+      if (uri.startsWith('file://')) out.push(fileURLToPath(uri));
+      else if (uri.startsWith('/')) out.push(uri);
+    } catch {
+      // a URI we cannot turn into a path is not one the caller can open
+    }
+  }
+  return out;
+}
+
+// --------------------------------------------------------------------------
+// Rung 1: the portal
+// --------------------------------------------------------------------------
+
+async function portalDialog(kind, opts, ref) {
+  const member = kind === 'save' ? 'SaveFile' : 'OpenFile';
+  const { response, results } = await portalRequest(ref, {
+    iface: FILE_CHOOSER,
+    member,
+    parentWindow: parentWindowHandle(windowIdOf(opts.parentWindow)),
+    title: opts.title ?? defaultTitle(kind),
+    options: await portalOptions(opts, {
+      save: kind === 'save',
+      directory: kind === 'folder',
+    }),
+    signal: opts.signal,
+  });
+  if (response !== RESPONSE_OK) throw new PortalCancelledError(response);
+  return urisToPaths(results?.uris);
+}
+
+// --------------------------------------------------------------------------
+// Rung 2: osascript, on macOS
+// --------------------------------------------------------------------------
+
+/** AppleScript string literal. */
+const as = (s) => `"${String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+/**
+ * The AppleScript for one dialog, as `-e` lines.
+ *
+ * Every branch normalises to newline-separated POSIX paths, so the caller
+ * parses one shape. `choose file` hands back an alias and `choose file name` a
+ * file reference that need not exist yet; `POSIX path of` works on both.
+ */
+export function osascriptLines(kind, opts = {}) {
+  const title = opts.title ?? defaultTitle(kind);
+  const parts = [];
+
+  if (kind === 'save') {
+    parts.push(`set theFiles to choose file name with prompt ${as(title)}`);
+    if (opts.defaultName) parts.push(`default name ${as(opts.defaultName)}`);
+    if (opts.defaultFolder) {
+      parts.push(`default location POSIX file ${as(opts.defaultFolder)}`);
+    }
+  } else if (kind === 'folder') {
+    parts.push(`set theFiles to choose folder with prompt ${as(title)}`);
+    if (opts.defaultFolder) {
+      parts.push(`default location POSIX file ${as(opts.defaultFolder)}`);
+    }
+    // `with …` flags go last: AppleScript is tolerant about the order of
+    // labelled parameters and conventional about this one, and the failure
+    // mode of getting it wrong is a syntax error at the far end of a pipe
+    // where nobody is looking.
+    if (opts.multiple) parts.push('with multiple selections allowed');
+  } else {
+    parts.push(`set theFiles to choose file with prompt ${as(title)}`);
+    // Extensions map exactly; MIME types do not, and guessing a UTI wrong
+    // hides the user's file with no way to get at it. So MIME-only filters
+    // mean no type restriction here rather than the wrong one — noted in
+    // docs/filedialog.md as the one place the backends genuinely differ.
+    const extensions = (opts.filters ?? [])
+      .flatMap((f) => f.extensions ?? [])
+      .map((e) => String(e).replace(/^[.*]*\.?/, ''))
+      .filter(Boolean);
+    if (extensions.length) {
+      parts.push(`of type {${[...new Set(extensions)].map(as).join(', ')}}`);
+    }
+    if (opts.defaultFolder) {
+      parts.push(`default location POSIX file ${as(opts.defaultFolder)}`);
+    }
+    if (opts.multiple) parts.push('with multiple selections allowed');
+  }
+
+  return [
+    parts.join(' '),
+    'if class of theFiles is not list then set theFiles to {theFiles}',
+    'set out to ""',
+    'repeat with f in theFiles',
+    'set out to out & POSIX path of f & linefeed',
+    'end repeat',
+    'return out',
+  ].flatMap((line) => ['-e', line]);
+}
+
+async function osascriptDialog(kind, opts) {
+  const { execFile } = await import('node:child_process');
+  const args = osascriptLines(kind, opts);
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      'osascript',
+      args,
+      { encoding: 'utf8' },
+      (error, stdout, stderr) => {
+        if (error) {
+          if (error.code === 'ENOENT') {
+            return reject(new NoFileDialogError(error));
+          }
+          // AppleScript reports a cancel as -128, which is an ordinary
+          // outcome and must not read as a failure.
+          if (/-128/.test(stderr) || /User canceled/i.test(stderr)) {
+            return reject(new PortalCancelledError(RESPONSE_CANCELLED));
+          }
+          return reject(
+            new Error(
+              `react-x11: the macOS file dialog failed — ${stderr.trim() || error.message}`,
+              { cause: error },
+            ),
+          );
+        }
+        resolve(
+          stdout
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean),
+        );
+      },
+    );
+    // An abort has to reach the panel; killing osascript closes it.
+    opts.signal?.addEventListener('abort', () => child.kill(), { once: true });
+  });
+}
+
+// --------------------------------------------------------------------------
+// Choosing a rung
+// --------------------------------------------------------------------------
+
+function defaultTitle(kind) {
+  return kind === 'save'
+    ? 'Save file'
+    : kind === 'folder'
+      ? 'Select folder'
+      : 'Open file';
+}
+
+/**
+ * Which rung this machine lands on, without showing anything.
+ *
+ * Useful for a menu that wants to say "Open…" versus "Open (built-in)…", and
+ * for the tests. It acquires a bus ref and releases it, so it is cheap to call
+ * but not free — cache it if it is on a render path.
+ *
+ * @returns {Promise<'portal'|'osascript'|'builtin'>}
+ */
+export async function fileDialogBackend() {
+  const ref = await sessionBus();
+  if (ref) {
+    try {
+      if (await hasService(PORTAL_NAME, ref)) return 'portal';
+    } finally {
+      await ref.release();
+    }
+  }
+  if (process.platform === 'darwin') return 'osascript';
+  return 'builtin';
+}
+
+/**
+ * Run one dialog on the best rung that is not the built-in one.
+ *
+ * Split out so `useFileDialog()` can try exactly this and fall through to its
+ * own dialog, without duplicating the ladder or the option translation.
+ */
+export async function runNativeDialog(kind, opts = {}) {
+  if (opts.backend === 'builtin') throw new NoFileDialogError();
+
+  const wantPortal = !opts.backend || opts.backend === 'portal';
+  if (wantPortal) {
+    const ref = await sessionBus();
+    if (ref) {
+      try {
+        if (await hasService(PORTAL_NAME, ref)) {
+          return await portalDialog(kind, opts, ref);
+        }
+      } finally {
+        await ref.release();
+      }
+    }
+    if (opts.backend === 'portal') {
+      throw new NoPortalError('no xdg-desktop-portal on the session bus');
+    }
+  }
+
+  const wantOsascript = !opts.backend || opts.backend === 'osascript';
+  if (wantOsascript && (process.platform === 'darwin' || opts.backend)) {
+    return await osascriptDialog(kind, opts);
+  }
+
+  throw new NoFileDialogError();
+}
+
+/**
+ * Ask for one or more existing files.
+ *
+ * ```js
+ * const files = await openFile({ multiple: true, filters: [
+ *   { name: 'Images', extensions: ['png', 'jpg'] },
+ * ]});
+ * if (!files) return;              // cancelled
+ * ```
+ *
+ * Resolves to **absolute paths**, or `null` when the user cancelled —
+ * cancelling is an ordinary outcome and should not need a `try`. Rejects with
+ * {@link NoFileDialogError} when there is no portal and no `osascript`, which
+ * is the signal to draw your own; {@link useFileDialog} does that for you.
+ *
+ * @returns {Promise<string[] | null>}
+ */
+export function openFile(options) {
+  return cancellable('open', options);
+}
+
+/**
+ * Ask where to write a file. Resolves to one **absolute path** — which need
+ * not exist yet — or `null` when the user cancelled.
+ *
+ * @returns {Promise<string | null>}
+ */
+export async function saveFile(options) {
+  const paths = await cancellable('save', options);
+  return paths ? (paths[0] ?? null) : null;
+}
+
+/**
+ * Ask for a directory. Resolves to absolute paths, or `null` when cancelled.
+ *
+ * @returns {Promise<string[] | null>}
+ */
+export function selectFolder(options) {
+  return cancellable('folder', options);
+}
+
+/** Cancellation is an answer, not an error. Everything else propagates. */
+async function cancellable(kind, options = {}) {
+  try {
+    return await runNativeDialog(kind, options);
+  } catch (err) {
+    if (err instanceof PortalCancelledError) return null;
+    throw err;
+  }
+}

package/src/filedialoghooks.js

@@ -0,0 +1,132 @@
+// `useFileDialog()` — the file dialog with the bottom rung attached.
+//
+// The bare `openFile()` in `filedialog.js` can reach the portal and
+// `osascript`, and rejects with `NoFileDialogError` when there is neither,
+// because a function has nowhere to draw. A component does: this hook mounts
+// the built-in browser on the connection the tree is already using, so the
+// ladder never runs out and an app never needs a `catch` that renders a
+// second dialog of its own.
+//
+// ## Why a second root rather than an element to render
+//
+// The obvious alternative is `const { open, dialog } = useFileDialog()` with
+// `{dialog}` rendered somewhere — which is a documentation step for every app
+// author, forever, and one that fails silently when forgotten: `open()` would
+// resolve to nothing with no clue why.
+//
+// A file dialog is a **top-level window** on every other rung, so it is one
+// here too: `createRoot({ app })` borrows the tree's own X connection (it
+// never closes a borrowed one) and renders a real, window-manager-placed,
+// `transientFor` dialog. Nothing to render, nothing to forget, and the same
+// window on all three rungs.
+
+import { useCallback, useMemo } from 'react';
+import React from 'react';
+
+import { FileDialog } from './components/FileDialog.js';
+import { useTheme } from './components/theme.js';
+import { NoFileDialogError, runNativeDialog } from './filedialog.js';
+import { PortalCancelledError } from './portal.js';
+import { useApp } from './appcontext.js';
+import { createRoot } from './Reconciler.js';
+import { useTopLevelWindow, windowIdOf } from './windowid.js';
+
+/**
+ * Show the built-in dialog on its own root, and resolve with what the user
+ * chose. The root is torn down before the promise settles, so a caller that
+ * opens a second dialog in the `.then()` never has two on screen.
+ */
+async function showBuiltin(app, theme, props) {
+  const root = await createRoot({ app });
+  try {
+    return await new Promise((resolve) => {
+      // `<FileDialog>` renders a `<window>`, and a window may only be a root
+      // child or nested in another window — so the palette travels as a prop
+      // and the dialog installs the provider *inside* its own window. Wrapping
+      // it here in `<ThemeProvider>` would put a `<box>` between the root and
+      // the window, which throws.
+      root.render(
+        React.createElement(FileDialog, { ...props, theme, onDone: resolve }),
+      );
+    });
+  } finally {
+    await root.unmount();
+  }
+}
+
+/**
+ * File dialogs, on the best rung this machine has.
+ *
+ * ```jsx
+ * const { openFile, saveFile } = useFileDialog();
+ *
+ * const open = async () => {
+ *   const files = await openFile({ filters: [{ name: 'Text', extensions: ['txt', 'md'] }] });
+ *   if (files) load(files[0]);         // null means the user cancelled
+ * };
+ *
+ * <MenuBar menus={[{ label: 'File', items: [{ label: 'Open…', onSelect: open }] }]} />
+ * ```
+ *
+ * **No arguments needed.** The dialog is parented to the window this
+ * component is in — `transientFor` for the built-in one, `parent_window` for
+ * the portal — worked out at the moment it opens rather than asked for.
+ * `parentWindow` remains as the override for a tree with several top-level
+ * windows, where inference has to guess and says so.
+ *
+ * Every call resolves to `null` when the user cancels. That is an ordinary
+ * outcome, not an exception, on all three rungs.
+ */
+export function useFileDialog(defaults = {}) {
+  const app = useApp();
+  const theme = useTheme();
+  // The window this component is in, resolved when a dialog actually opens —
+  // by which time it is mounted and has an XID. So a parented dialog costs
+  // the app nothing, and `parentWindow` is left as the override for a tree
+  // with several top-level windows. See `useTopLevelWindow`.
+  const owner = useTopLevelWindow();
+
+  const run = useCallback(
+    async (kind, options = {}) => {
+      const opts = { parentWindow: owner, ...defaults, ...options };
+      try {
+        return await runNativeDialog(kind, opts);
+      } catch (err) {
+        if (err instanceof PortalCancelledError) return null;
+        if (!(err instanceof NoFileDialogError)) throw err;
+        // The bottom rung. Reached over ssh, under startx, in a container —
+        // and on any machine whose portal went away between calls.
+        return showBuiltin(app, theme, {
+          kind,
+          title: opts.title,
+          startFolder: opts.defaultFolder,
+          defaultName: opts.defaultName,
+          filters: opts.filters ?? [],
+          multiple: !!opts.multiple && kind !== 'save',
+          acceptLabel: opts.acceptLabel,
+          parentWindow: windowIdOf(opts.parentWindow) ?? undefined,
+        });
+      }
+    },
+    // `defaults` is deliberately not a dependency: an app writes it inline, so
+    // a new object every render would rebuild these callbacks every render and
+    // defeat the memo below. It is read through the closure at call time,
+    // which is when its values are actually wanted.
+    [app, theme, owner],
+  );
+
+  return useMemo(
+    () => ({
+      /** @returns {Promise<string[] | null>} absolute paths, or null if cancelled */
+      openFile: (options) => run('open', options),
+      /** @returns {Promise<string | null>} one absolute path, or null if cancelled */
+      saveFile: async (options) => {
+        const paths = await run('save', options);
+        return paths ? (paths[0] ?? null) : null;
+      },
+      /** @returns {Promise<string[] | null>} absolute paths, or null if cancelled */
+      selectFolder: (options) => run('folder', options),
+    }),
+    [run],
+  );
+}

package/src/fonthooks.js

@@ -0,0 +1,64 @@
+// `useFont()` — a font file, from a component.
+//
+// The imperative half lives in `fonts.js` and is where the reasoning is. The
+// hook is thin on purpose: `loadFont` is already idempotent per app and
+// file, so the memo here saves a map lookup rather than a file read, and a
+// component that re-renders sixty times a second still parses nothing.
+//
+// It reads `useApp()` rather than taking the connection, since a component
+// three levels down has one and does not have the app.
+
+import { useMemo } from 'react';
+
+import { useApp } from './appcontext.js';
+import { loadFont } from './fonts.js';
+
+/**
+ * The font in `source`, registered and ready to draw with.
+ *
+ * ```jsx
+ * const { family } = useFont(fontPath);
+ *
+ * <text style={{ fontFamily: family, fontSize: 32 }}>Handgloves</text>;
+ * ```
+ *
+ * `font` is ntk's `Font` — `metrics(size)`, `variationAxes`, `hasGlyph(cp)` —
+ * and `family` is the name to put in `fontFamily`, read off the file rather
+ * than invented here. See {@link loadFont} for what that name is and when it
+ * is scoped.
+ *
+ * **Returns null when `source` is null**, so a picker can call it before
+ * anything is picked without a branch around the hook:
+ *
+ * ```jsx
+ * const picked = useFont(path); // path may be null
+ * <text style={{ fontFamily: picked?.family }}>{sample}</text>;
+ * ```
+ *
+ * The file is read on the render that first names it, and never again: the
+ * face is cached in the connection's font manager, which is also where a
+ * `openFont`/`loadFont` call outside the tree would find it.
+ *
+ * **A file that cannot be read throws during render**, which is an error
+ * boundary's business — right for a font the app ships and wrong for one a
+ * user just picked in a dialog, where the app wants to say so in its own UI.
+ * Call `loadFont(app, path)` in the handler that picked it for that case, and
+ * catch there.
+ *
+ * @param {string|Uint8Array|Buffer|null} [source] path, or the file's bytes
+ * @param {{ family?: string, weight?: number|string, style?: string,
+ *   postscriptName?: string }} [opts]
+ */
+export function useFont(source, opts) {
+  const app = useApp();
+  // The options are folded into the memo key rather than listed as
+  // dependencies: an inline `{ family: 'preview' }` is a fresh object every
+  // render and would defeat the memo on identity alone.
+  const key = `${opts?.family ?? ''}|${opts?.weight ?? ''}|${opts?.style ?? ''}|${
+    opts?.postscriptName ?? ''
+  }`;
+  return useMemo(
+    () => (source == null ? null : loadFont(app, source, opts)),
+    [app, source, key],
+  );
+}