react-x11 1.2.0 → 2.0.0

package/src/components/anchor.js

@@ -1,121 +1,153 @@
-// Popup geometry: where to put a <popup> anchored to a drawn node, and
-// how big to make it around a measured label.
+// Popup geometry, the React half: the hooks a widget hangs a `<popup>` off
+// a node with, and the measurement a menu sizes itself around.
+//
+// The placement math itself is core (`src/anchor.js`), because a `<popup>`
+// that sizes itself from its content places itself from the same functions
+// — see the note there.
 
-import { useCallback } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
 
-/** The X screen the node's window lives on, if reachable (the smoke-test
- *  mock app has no screen geometry — callers must cope with null). */
-export function screenOf(node) {
-  const app = node?.app;
-  const screen = (app?.display ?? app?.X?.display)?.screen?.[0];
-  return screen?.pixel_width ? screen : null;
-}
+export {
+  anchorArea,
+  anchorOffscreen,
+  anchorRect,
+  centerRect,
+  screenRect,
+  subRect,
+} from '../anchor.js';
+
+import { anchorOffscreen, anchorRect } from '../anchor.js';
 
 /**
- * Where to put a `<popup>` anchored to a drawn node, in **screen**
- * coordinates: the owner window's position plus the node's laid-out rect.
- *
- * `placement` is a preference, not a promise — a menu near the bottom of
- * the screen flips above its trigger rather than opening off-screen, and
- * the result is clamped into the screen either way. The chosen side comes
- * back as `placement` so the caller can style accordingly.
+ * useAnchor(ref) — stable `measure(options)` returning `anchorRect` for the
+ * referenced node. The anchoring math `Select` used to inline, shared with
+ * `Tooltip` and anything else that hangs a `<popup>` off a drawn node.
  */
-export function anchorRect(node, options = {}) {
-  if (!node?.abs) return null;
-  const {
-    placement = 'bottom',
-    align = 'start',
-    offset = 2,
-    width = node.abs.width,
-    height = 0,
-  } = options;
-
-  const win = node.root?.window;
-  const ax = (win?.x ?? 0) + node.abs.x;
-  const ay = (win?.y ?? 0) + node.abs.y;
-  const aw = node.abs.width;
-  const ah = node.abs.height;
-
-  const screen = screenOf(node);
-  const sw = screen?.pixel_width;
-  const sh = screen?.pixel_height;
-
-  const alignAlong = (start, size, extent) =>
-    align === 'center'
-      ? start + (size - extent) / 2
-      : align === 'end'
-        ? start + size - extent
-        : start;
-
-  let side = placement;
-  let x;
-  let y;
-
-  if (side === 'bottom' || side === 'top') {
-    const below = ay + ah + offset;
-    const above = ay - height - offset;
-    if (side === 'bottom' && sh != null && below + height > sh && above >= 0) {
-      side = 'top';
-    } else if (
-      side === 'top' &&
-      above < 0 &&
-      (sh == null || below + height <= sh)
-    ) {
-      side = 'bottom';
-    }
-    y = side === 'bottom' ? below : above;
-    x = alignAlong(ax, aw, width);
-  } else {
-    const after = ax + aw + offset;
-    const before = ax - width - offset;
-    if (side === 'right' && sw != null && after + width > sw && before >= 0) {
-      side = 'left';
-    } else if (
-      side === 'left' &&
-      before < 0 &&
-      (sw == null || after + width <= sw)
-    ) {
-      side = 'right';
-    }
-    x = side === 'right' ? after : before;
-    y = alignAlong(ay, ah, height);
-  }
-
-  if (sw != null) x = Math.max(0, Math.min(x, sw - width));
-  if (sh != null && height) y = Math.max(0, Math.min(y, sh - height));
+export function useAnchor(ref) {
+  return useCallback((options) => anchorRect(ref.current, options), [ref]);
+}
 
-  return { x: Math.round(x), y: Math.round(y), width, height, placement: side };
+function sameAnchorRect(a, b) {
+  return (
+    a === b ||
+    (a != null &&
+      b != null &&
+      a.x === b.x &&
+      a.y === b.y &&
+      a.width === b.width &&
+      a.height === b.height &&
+      a.placement === b.placement)
+  );
 }
 
 /**
- * Where to put a `<popup>` of this size **centred over the owner window**,
- * in screen coordinates, clamped into the screen. A dialog is anchored to
- * the window rather than to a widget, which is the one placement
- * `anchorRect` cannot express.
+ * useAnchorTracking(ref, active, getOptions, setRect, onOutOfView) — keeps a
+ * popup's `anchorRect` live for as long as `active`, instead of the one-shot
+ * measure every caller used to take at open time. A trigger inside a
+ * scrolled viewport, one whose own layout moves it (a neighbouring field
+ * wrapping to a second line), or an owner window nudged by the window
+ * manager or a script all leave a popup that was only ever measured once
+ * hanging over stale ground.
+ *
+ * Subscribes to the anchoring node's owner window (`WindowNode.onAnchorChange`,
+ * `nodes.js`) rather than polling: that fires exactly on the events which
+ * can actually move the rect — a layout pass and a fresh `_screenOrigin` —
+ * so a still trigger costs nothing and a moved one is caught the same frame.
+ * `getOptions` is read fresh through a ref on every notification, so callers
+ * do not need to memoize it; returning a falsy value skips that tick (the
+ * ref not being ready yet, say). `setRect` only runs when the measured rect
+ * actually differs, so it will not re-render (or re-`ConfigureWindow` the
+ * popup) for a change that turned out not to move anything.
+ *
+ * A popup is a real X window, not a web element clipped by its ancestors'
+ * overflow — following a trigger that has scrolled out of view would leave
+ * it floating over content it no longer belongs to, detached from anything
+ * the user can see it points at. So once the trigger is entirely past a
+ * clipping ancestor's own bounds or past the owner window itself
+ * (`Node._offscreen()`, the same check paint culling uses), tracking calls
+ * `onOutOfView` instead of measuring — closing the popup, or hiding it, is
+ * the caller's call — and does not resume until re-opened. With no
+ * `onOutOfView` this just stops updating rather than snapping to a rect
+ * that no longer means anything.
+ *
+ * With an `at` in the options that test is about **the sub-rect**, not the
+ * node: an editor scrolls its own text, so the caret leaves the viewport
+ * long before the editor does, and a completion popup that waited for the
+ * whole editor to scroll away would hang over the middle of a document it
+ * had stopped pointing into.
  */
-export function centerRect(node, { width, height }) {
-  if (!node) return null;
-  const win = node.root?.window;
-  const ww = win?.width ?? width;
-  const wh = win?.height ?? height;
-  let x = (win?.x ?? 0) + (ww - width) / 2;
-  let y = (win?.y ?? 0) + (wh - height) / 2;
-
-  const screen = screenOf(node);
-  if (screen) {
-    x = Math.max(0, Math.min(x, screen.pixel_width - width));
-    y = Math.max(0, Math.min(y, screen.pixel_height - height));
-  }
-  return { x: Math.round(x), y: Math.round(y), width, height };
+export function useAnchorTracking(
+  ref,
+  active,
+  getOptions,
+  setRect,
+  onOutOfView,
+) {
+  const measure = useAnchor(ref);
+  const getOptionsRef = useRef(getOptions);
+  getOptionsRef.current = getOptions;
+  const onOutOfViewRef = useRef(onOutOfView);
+  onOutOfViewRef.current = onOutOfView;
+  // Read during render, and read again inside the notification, because the
+  // two do not happen in that order. Closing a popup sets its rect to null
+  // and the *commit* destroys its window — and destroying a window is a
+  // layout pass, which notifies from inside the commit, before React gets
+  // to the effect cleanup that would have unsubscribed. A subscription that
+  // only knew the `active` of the render it was made in would answer that
+  // notification by measuring a fresh rect for the popup just closed, and
+  // hand back a second window in place of the one that went away.
+  const activeRef = useRef(active);
+  activeRef.current = active;
+
+  useEffect(() => {
+    if (!active) return undefined;
+    const root = ref.current?.root;
+    if (!root?.onAnchorChange) return undefined;
+    return root.onAnchorChange(() => {
+      if (!activeRef.current) return;
+      const node = ref.current;
+      // the options before the view test, because `at` is in them: what has
+      // to still be visible is the rect the popup points at
+      const options = getOptionsRef.current();
+      if (!options) return;
+      if (anchorOffscreen(node, options.at)) {
+        onOutOfViewRef.current?.();
+        return;
+      }
+      const next = measure(options);
+      if (!next) return;
+      setRect((prev) => (sameAnchorRect(prev, next) ? prev : next));
+    });
+  }, [active, ref, measure, setRect]);
 }
 
 /**
- * useAnchor(ref) — stable `measure(options)` returning `anchorRect` for the
- * referenced node. The anchoring math `Select` used to inline, shared with
- * `Tooltip` and anything else that hangs a `<popup>` off a drawn node.
+ * useDismissOnWindowBlur(ref, active, onDismiss) — shut a popup when the
+ * **window** it belongs to loses focus.
+ *
+ * A node's `onBlur` does not fire for this, deliberately: a window losing
+ * focus leaves the node inside it focused and merely stops it looking
+ * active, so the trigger a menu closes on never hears anything. What is left
+ * is a menu still open over an application the user has switched away from
+ * — and, for the ones that grab, still holding the pointer grab that came
+ * with it, so the first click anywhere goes to dismissing it.
+ *
+ * The window manager's own focus, then, rather than anything in the tree:
+ * `WindowNode.onWindowFocusChange` (nodes.js), which the event manager
+ * notifies from the same place it suspends the caret.
  */
-export function useAnchor(ref) {
-  return useCallback((options) => anchorRect(ref.current, options), [ref]);
+export function useDismissOnWindowBlur(ref, active, onDismiss) {
+  const onDismissRef = useRef(onDismiss);
+  onDismissRef.current = onDismiss;
+
+  useEffect(() => {
+    if (!active) return undefined;
+    const root = ref.current?.root;
+    if (!root?.onWindowFocusChange) return undefined;
+    return root.onWindowFocusChange((focused) => {
+      if (!focused) onDismissRef.current?.();
+    });
+  }, [active, ref]);
 }
 
 /** Measured size of a single-line label, for sizing a popup around it.
@@ -126,12 +158,27 @@ export function measureLabel(node, text, style) {
   if (!fonts?.layout) {
     return { width: String(text).length * size * 0.55, height: size * 1.4 };
   }
+  // Measured at the size the glyphs are actually rasterized — the logical
+  // size times the display scale — then divided back, so the logical answer
+  // carries the true metrics. Measuring at the logical size and trusting
+  // linearity is off by the accumulated per-glyph rounding, which is
+  // exactly the kind of error that turns into an ellipsis on the longest
+  // label in the menu (src/scale.js).
+  const s = node?.scale ?? 1;
   const layout = fonts.layout(String(text), {
-    family: style?.family ?? 'sans-serif',
-    size,
+    // The face **this node inherits**, not the literal `sans-serif`: the
+    // labels these popups are sized around name no family of their own, so
+    // the one they are drawn in is the palette's. Measuring in a different
+    // face is measuring the wrong label — a menu sized in sans-serif for a
+    // row that paints in a wider mono is a menu whose own options wrap.
+    family: style?.family ?? node?.inheritedTextStyle?.family ?? 'sans-serif',
+    size: size * s,
     weight: style?.weight ?? 'normal',
+    // dropping this would measure a different face from the one drawn, and
+    // the popup sized here would be the wrong width for its own label
+    variations: style?.variations,
   });
-  return { width: layout.width, height: layout.height };
+  return { width: layout.width / s, height: layout.height / s };
 }
 
 export const DEFAULT_LABEL_SIZE = 13;

package/src/components/change.js

@@ -0,0 +1,34 @@
+// The change event the value widgets hand their `onChange`.
+//
+// One signature across the library: `<textinput>` and `<textarea>` pass a
+// synthetic event, and so do `Checkbox`, `Switch`, `RadioGroup`, `Select`
+// and `Slider`. That is what lets `onChange={formik.handleChange}` be wired
+// to any of them without a per-widget adapter — a form library reads the
+// field out of `ev.target`, and it now finds one there whatever it is
+// attached to.
+//
+// The line is `name`: a widget that takes one is a form field and reports an
+// event. `Tabs`, `Table` and the menus are not form fields and keep
+// their plain callbacks.
+//
+// `target` is a plain descriptor rather than a node, which is the one place
+// this differs from the host elements. A widget is a composition of nodes
+// with no single element holding its value, so there is nothing honest to
+// point at — and `{ type, name, value, checked }` is exactly the shape
+// formik's `handleChange` and react-hook-form's event reader destructure.
+// `type` is what tells them a checkbox from a text field, which is why it is
+// set even though nothing in react-x11 reads it.
+//
+// There is no `preventDefault` — the value has already changed by the time
+// the handler runs, so there would be nothing to prevent.
+
+/**
+ * @param {string} type - `'checkbox'`, `'radio'`, `'select-one'`, `'range'`…
+ * @param {string|undefined} name - the widget's `name` prop
+ * @param {unknown} value - the value the widget just moved to
+ */
+export function changeEvent(type, name, value) {
+  const target = { type, name, value };
+  if (type === 'checkbox') target.checked = Boolean(value);
+  return { type: 'change', target, currentTarget: target, name, value };
+}

package/src/components/dnd.js

@@ -0,0 +1,103 @@
+// useDropTarget — the convenience layer over the drop-target host props
+// (`dropAccept`, `onDragEnter/Leave/Over`, `onDrop`; see src/dnd.js), the
+// same two-layer shape as anchorRect/useAnchor. The hook adds what a
+// component wants and the host props deliberately do not: render state.
+// The common "highlight the dropzone" case needs neither — a
+// `':drag-over'` style block does it with no state at all — so reach for
+// this only when the render itself changes (an "isOver" hint label,
+// disabling other controls mid-drag).
+
+import { useState } from 'react';
+import { matchAccept } from '../dnd.js';
+
+/**
+ * const { dropProps, isOver, isAccepted } = useDropTarget({
+ *   accept: ['files'],
+ *   onDrop: (e) => setFiles(e.files),
+ * });
+ * return <box {...dropProps} style={s.zone} />;
+ *
+ * `accept` here maps to the `dropAccept` host prop — inside a hook named
+ * useDropTarget the shorter word is unambiguous, and it is the name
+ * react-dropzone users expect. `onDrop`'s return value is passed through,
+ * so an async handler keeps holding XdndFinished (up to the watchdog).
+ */
+export function useDropTarget(options = {}) {
+  const { accept, onDrop, onDragOver, onDragEnter, onDragLeave } = options;
+  // null: no drag over this node; otherwise whether the offer matches
+  const [drag, setDrag] = useState(null);
+  const dropProps = {
+    dropAccept: accept,
+    onDragEnter: (ev) => {
+      setDrag({ accepted: matchAccept(accept ?? null, ev.types) });
+      onDragEnter?.(ev);
+    },
+    onDragLeave: (ev) => {
+      setDrag(null);
+      onDragLeave?.(ev);
+    },
+    onDragOver,
+    onDrop: (ev) => {
+      setDrag(null);
+      return onDrop?.(ev);
+    },
+  };
+  return {
+    dropProps,
+    isOver: drag != null,
+    isAccepted: Boolean(drag?.accepted),
+  };
+}
+
+/**
+ * useDragSource — the source-side twin. Spread `dragProps` on the node to
+ * drag; the hook adds render state (`isDragging`, the pointer `position` in
+ * screen coordinates) so a component can dim itself, show a hint, or render
+ * a drag preview. The preview is deliberately userland — a `<popup
+ * dragPreview>` following `position` is a live React tree, which is more
+ * than a DOM `setDragImage` bitmap ever was; the `dragPreview` prop is what
+ * keeps the router from seeing the popup as the window under the pointer.
+ *
+ *   const { dragProps, isDragging, position } = useDragSource({
+ *     data: {
+ *       'text/uri-list': () => toUriList(item),   // thunk: resolved lazily
+ *       'application/x-myapp-item': item,         // live for in-app drops
+ *     },
+ *     actions: ['copy', 'move'],
+ *     onDragEnd: (e) => { if (e.action === 'move') remove(item.id); },
+ *   });
+ *   return (
+ *     <>
+ *       <box {...dragProps} style={{ ':dragging': { backgroundColor: '$textMuted' } }} />
+ *       {isDragging && (
+ *         <popup dragPreview x={position.x + 12} y={position.y + 12}>
+ *           <Chip label={item.name} />
+ *         </popup>
+ *       )}
+ *     </>
+ *   );
+ */
+export function useDragSource(options = {}) {
+  const { data, actions, onDragStart, onDrag, onDragEnd } = options;
+  const [drag, setDrag] = useState(null);
+  const dragProps = {
+    draggable: true,
+    dragData: data,
+    dragActions: actions,
+    onDragStart: (ev) => {
+      onDragStart?.(ev);
+      if (!ev.defaultPrevented) {
+        setDrag({ x: ev.screenX, y: ev.screenY, accepted: false });
+      }
+    },
+    onDrag: (ev) => {
+      setDrag({ x: ev.screenX, y: ev.screenY, accepted: ev.accepted });
+      onDrag?.(ev);
+    },
+    onDragEnd: (ev) => {
+      setDrag(null);
+      onDragEnd?.(ev);
+    },
+  };
+  return { dragProps, isDragging: drag != null, position: drag };
+}

package/src/components/index.js

@@ -2,10 +2,21 @@
 // modules here are grouped by widget, with the shared plumbing in
 // theme.js (palette + control props), anchor.js (popup geometry),
 // typeahead.js and keys.js.
-export { ThemeProvider, SelectThemeProvider } from './theme.js';
-export { anchorRect, centerRect, useAnchor } from './anchor.js';
+export { ThemeProvider, useDirection, useTheme } from './theme.js';
+export {
+  anchorArea,
+  anchorRect,
+  centerRect,
+  screenRect,
+  useAnchor,
+  useAnchorTracking,
+} from './anchor.js';
+export { useDropTarget, useDragSource } from './dnd.js';
+export { Icon, icons, iconNames, iconSize } from './Icon.js';
 export { Button } from './Button.js';
+export { PasswordInput } from './PasswordInput.js';
 export { Dialog } from './Dialog.js';
+export { FileDialog } from './FileDialog.js';
 export { Checkbox } from './Checkbox.js';
 export { Radio, RadioGroup } from './Radio.js';
 export { Switch } from './Switch.js';
@@ -14,4 +25,6 @@ export { Slider } from './Slider.js';
 export { Tooltip } from './Tooltip.js';
 export { ContextMenu, MenuBar } from './Menu.js';
 export { Select } from './Select.js';
-export { Canvas3D } from './Canvas3D.js';
+export { Tabs } from './Tabs.js';
+export { Table } from './Table.js';
+export { SplitPane } from './SplitPane.js';

package/src/components/keys.js

@@ -1,21 +1,18 @@
 // X11 keysyms used by the widget keyboard handlers.
-
-export const XK_RETURN = 0xff0d;
-
-export const XK_ESCAPE = 0xff1b;
-
-export const XK_HOME = 0xff50;
-
-export const XK_LEFT = 0xff51;
-
-export const XK_UP = 0xff52;
-
-export const XK_RIGHT = 0xff53;
-
-export const XK_DOWN = 0xff54;
-
-export const XK_PAGE_UP = 0xff55;
-
-export const XK_PAGE_DOWN = 0xff56;
-
-export const XK_END = 0xff57;
+//
+// The names live in `src/keysyms.js`, published as `react-x11/keysyms`, so
+// app code, the widgets and `fireEvent.key` in `react-x11/test` all name a
+// key the same way. This module stays as the widgets' import path.
+
+export {
+  XK_RETURN,
+  XK_ESCAPE,
+  XK_HOME,
+  XK_LEFT,
+  XK_UP,
+  XK_RIGHT,
+  XK_DOWN,
+  XK_PAGE_UP,
+  XK_PAGE_DOWN,
+  XK_END,
+} from '../keysyms.js';