react-x11 0.0.1 → 1.2.0

package/src/components/Tooltip.js

@@ -0,0 +1,146 @@
+// Widget components built purely on the host primitives — no reconciler
+// support needed. Plain createElement (no JSX) so the library stays
+// build-step-free for consumers.
+
+import React, { useEffect, useRef, useState } from 'react';
+import { useTheme } from './theme.js';
+import {
+  DEFAULT_LABEL_SIZE,
+  measureLabel,
+  movingToward,
+  SAFE_HOVER_DELAY,
+  screenPoint,
+  useAnchor,
+} from './anchor.js';
+
+const h = React.createElement;
+
+const TOOLTIP_PADDING_X = 8;
+
+const TOOLTIP_PADDING_Y = 4;
+
+/**
+ * <Tooltip label placement delay>…</Tooltip> — a hover hint in a `<popup>`,
+ * so it can extend past the owner window's bounds.
+ *
+ * Wraps its children in a row box that carries the hover handlers and the
+ * anchor ref. Shows after `delay` ms of hover, hides immediately on leave
+ * (and on mousedown — a tooltip lingering over a menu you just opened is
+ * the classic annoyance). `placement` flips automatically near a screen
+ * edge, via the same `useAnchor` math `Select` uses.
+ *
+ * The popup is sized from the measured label, since a `<popup>` is a real
+ * X window and needs its size up front rather than after layout.
+ */
+export function Tooltip({
+  label,
+  children,
+  placement = 'top',
+  delay = 500,
+  fontSize = DEFAULT_LABEL_SIZE,
+  ...boxProps
+}) {
+  const theme = useTheme();
+  const ref = useRef(null);
+  const measureAnchor = useAnchor(ref);
+  const [rect, setRect] = useState(null);
+  const timer = useRef(null);
+
+  const cancel = () => {
+    if (timer.current) {
+      clearTimeout(timer.current);
+      timer.current = null;
+    }
+  };
+  const hide = () => {
+    cancel();
+    setRect(null);
+  };
+
+  // safe-polygon hover (docs/components.md): leaving the trigger *toward*
+  // the tooltip keeps it up, so a tooltip with content in it can be
+  // reached instead of vanishing the moment the pointer moves
+  const apex = useRef(null);
+  const hideSoon = () => {
+    cancel();
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      setRect(null);
+    }, SAFE_HOVER_DELAY);
+  };
+  const onMouseMove = (ev) => {
+    apex.current = screenPoint(ev) ?? apex.current;
+  };
+  const onMouseLeave = (ev) => {
+    if (rect && movingToward(screenPoint(ev), apex.current, rect)) hideSoon();
+    else hide();
+  };
+
+  // a pending timer must not outlive the component
+  useEffect(() => cancel, []);
+
+  const show = () => {
+    const node = ref.current;
+    if (!node || !label) return;
+    const text = measureLabel(node, label, { size: fontSize });
+    const width = Math.ceil(text.width) + TOOLTIP_PADDING_X * 2 + 2;
+    const height = Math.ceil(text.height) + TOOLTIP_PADDING_Y * 2 + 2;
+    const next = measureAnchor({ placement, align: 'center', width, height });
+    if (next) setRect(next);
+  };
+
+  const onMouseEnter = () => {
+    cancel();
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      show();
+    }, delay);
+  };
+
+  return h(
+    'box',
+    {
+      ref,
+      flexDirection: 'row',
+      alignItems: 'center',
+      onMouseEnter,
+      onMouseMove,
+      onMouseLeave,
+      onMouseDown: hide,
+      ...boxProps,
+    },
+    children,
+    rect &&
+      h(
+        'popup',
+        {
+          x: rect.x,
+          y: rect.y,
+          width: rect.width,
+          height: rect.height,
+          windowType: 'tooltip',
+          backgroundColor: theme.text,
+        },
+        h(
+          'box',
+          {
+            // the pointer reaching the tooltip keeps it up; leaving it
+            // dismisses, as if the trigger had been left
+            onMouseEnter: cancel,
+            onMouseLeave: hide,
+            flexGrow: 1,
+            borderWidth: 1,
+            borderColor: theme.text,
+            borderRadius: 3,
+            backgroundColor: theme.text,
+            justifyContent: 'center',
+            paddingLeft: TOOLTIP_PADDING_X,
+            paddingRight: TOOLTIP_PADDING_X,
+          },
+          h('text', { color: theme.background, fontSize }, label),
+        ),
+      ),
+  );
+}
+
+// --- menus ------------------------------------------------------------------

package/src/components/anchor.js

@@ -0,0 +1,211 @@
+// Popup geometry: where to put a <popup> anchored to a drawn node, and
+// how big to make it around a measured label.
+
+import { useCallback } 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;
+}
+
+/**
+ * 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.
+ */
+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));
+
+  return { x: Math.round(x), y: Math.round(y), width, height, placement: side };
+}
+
+/**
+ * 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.
+ */
+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 };
+}
+
+/**
+ * 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 useAnchor(ref) {
+  return useCallback((options) => anchorRect(ref.current, options), [ref]);
+}
+
+/** Measured size of a single-line label, for sizing a popup around it.
+ *  Falls back to a rough estimate where no font stack is available. */
+export function measureLabel(node, text, style) {
+  const fonts = node?.app?.fonts;
+  const size = style?.size ?? DEFAULT_LABEL_SIZE;
+  if (!fonts?.layout) {
+    return { width: String(text).length * size * 0.55, height: size * 1.4 };
+  }
+  const layout = fonts.layout(String(text), {
+    family: style?.family ?? 'sans-serif',
+    size,
+    weight: style?.weight ?? 'normal',
+  });
+  return { width: layout.width, height: layout.height };
+}
+
+export const DEFAULT_LABEL_SIZE = 13;
+
+/** How long a hover change is held back while the pointer crosses the
+ *  polygon — long enough to be forgiving, short enough not to feel stuck. */
+export const SAFE_HOVER_DELAY = 320;
+
+/**
+ * "Safe polygon" hover, after
+ * [floating-ui](https://floating-ui.com/docs/usehover#safepolygon).
+ *
+ * A submenu opens to the side of its parent row, so reaching it means
+ * moving the pointer *diagonally* across the rows in between — and those
+ * rows would each take the hover and close the submenu being aimed at. The
+ * fix is to treat the triangle between where the pointer was and the near
+ * edge of the child surface as "still hovering the parent": while the
+ * pointer is inside it, hover changes are held back.
+ *
+ * `apex` is where the pointer was while it was still over the parent (its
+ * exit point, near enough), `rect` the child popup — both in **screen**
+ * coordinates, because parent and child are different X windows.
+ */
+export function movingToward(point, apex, rect, buffer = 8) {
+  if (!point || !apex || !rect?.width) return false;
+  return pointInPolygon(point, safePolygon(apex, rect, buffer));
+}
+
+/** The triangle from `apex` to the child's near edge, grown by `buffer`. */
+export function safePolygon(apex, rect, buffer = 8) {
+  const left = rect.x;
+  const right = rect.x + rect.width;
+  const top = rect.y;
+  const bottom = rect.y + rect.height;
+
+  // the edge the pointer has to cross to reach the child
+  let a;
+  let b;
+  if (apex.x <= left) {
+    a = { x: left, y: top - buffer };
+    b = { x: left, y: bottom + buffer };
+  } else if (apex.x >= right) {
+    a = { x: right, y: top - buffer };
+    b = { x: right, y: bottom + buffer };
+  } else if (apex.y <= top) {
+    a = { x: left - buffer, y: top };
+    b = { x: right + buffer, y: top };
+  } else {
+    a = { x: left - buffer, y: bottom };
+    b = { x: right + buffer, y: bottom };
+  }
+  return [apex, a, b];
+}
+
+/** Ray casting; the polygon is a triangle here but the test is general. */
+export function pointInPolygon(point, polygon) {
+  let inside = false;
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i++) {
+    const pi = polygon[i];
+    const pj = polygon[j];
+    const straddles = pi.y > point.y !== pj.y > point.y;
+    if (
+      straddles &&
+      point.x < ((pj.x - pi.x) * (point.y - pi.y)) / (pj.y - pi.y) + pi.x
+    ) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}
+
+/** Pointer position of an event in screen coordinates, or null. */
+export function screenPoint(ev) {
+  const native = ev?.nativeEvent;
+  if (native?.rootx == null || native?.rooty == null) return null;
+  return { x: native.rootx, y: native.rooty };
+}

package/src/components/index.js

@@ -0,0 +1,17 @@
+// Public widget components. Split out of a single components.js; the
+// 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 { Button } from './Button.js';
+export { Dialog } from './Dialog.js';
+export { Checkbox } from './Checkbox.js';
+export { Radio, RadioGroup } from './Radio.js';
+export { Switch } from './Switch.js';
+export { ProgressBar } from './ProgressBar.js';
+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';

package/src/components/keys.js

@@ -0,0 +1,21 @@
+// 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;

package/src/components/theme.js

@@ -0,0 +1,66 @@
+// Widget components built purely on the host primitives — no reconciler
+// support needed. Plain createElement (no JSX) so the library stays
+// build-step-free for consumers.
+
+import React, { useContext, useState } from 'react';
+import { XK_RETURN } from './keys.js';
+
+const h = React.createElement;
+
+const DefaultTheme = {
+  border: '#b2bec3',
+  borderActive: '#2980b9',
+  background: 'white',
+  text: '#2d3436',
+  dim: '#7f8c8d',
+  hoverBackground: '#2980b9',
+  hoverText: 'white',
+  accent: '#2980b9',
+  accentHover: '#1f6693',
+  accentText: 'white',
+  surfaceHover: '#f1f2f6',
+  track: '#dfe6e9',
+};
+
+const ThemeContext = React.createContext(DefaultTheme);
+
+/** Themes all widgets; partial palettes merge over the defaults. */
+export const ThemeProvider = ThemeContext.Provider;
+
+export const SelectThemeProvider = ThemeContext.Provider; // back-compat alias
+
+export function useTheme() {
+  const theme = useContext(ThemeContext);
+  return theme === DefaultTheme ? theme : { ...DefaultTheme, ...theme };
+}
+
+/** Shared interactive-control plumbing: hover/focus state plus the box
+ * props wiring them, click + Space/Enter activation. */
+export function useControl(disabled, onActivate) {
+  const [hover, setHover] = useState(false);
+  const [focused, setFocused] = useState(false);
+  const props = disabled
+    ? {}
+    : {
+        focusable: true,
+        cursor: 'pointer',
+        onMouseEnter: () => setHover(true),
+        onMouseLeave: () => setHover(false),
+        onFocus: () => setFocused(true),
+        onBlur: () => setFocused(false),
+        onClick: () => onActivate?.(),
+        onKeyDown: (ev) => {
+          if (ev.codepoint === 32 || ev.keysym === XK_RETURN) onActivate?.();
+        },
+      };
+  return { hover: hover && !disabled, focused: focused && !disabled, props };
+}
+
+/** String/number children become a <text>; elements pass through. */
+export function labelContent(children, textProps) {
+  return React.Children.map(children, (child) =>
+    typeof child === 'string' || typeof child === 'number'
+      ? h('text', textProps, child)
+      : child,
+  );
+}

package/src/components/typeahead.js

@@ -0,0 +1,56 @@
+// Type-ahead matching shared by Select and the menus.
+
+import { useCallback, useRef } from 'react';
+
+export const TYPE_AHEAD_TIMEOUT = 700;
+
+/**
+ * Type-ahead: typing letters jumps to the entry whose label starts with
+ * them. Shared by `Select` and the menus.
+ *
+ * Keystrokes within `timeout` accumulate into one query, so "ca" finds
+ * Carrot rather than jumping to Apple then Carrot. Two behaviours the
+ * platform conventions call for:
+ *
+ * - a growing query searches from the *current* entry, so refining a
+ *   prefix keeps you on it while it still matches;
+ * - repeating one letter ("c", "c", "c") cycles through the entries
+ *   starting with it instead of sticking on the first.
+ *
+ * Returns the matching index, or -1.
+ */
+export function useTypeAhead(timeout = TYPE_AHEAD_TIMEOUT) {
+  const state = useRef({ text: '', at: 0 });
+  return useCallback(
+    (char, items, current, labelOf, selectable) => {
+      if (!char || char.length !== 1) return -1;
+      const now = Date.now();
+      const s = state.current;
+      s.text = now - s.at > timeout ? char : s.text + char;
+      s.at = now;
+
+      const query = s.text.toLowerCase();
+      const cycling = query.length > 1 && /^(.)\1+$/.test(query);
+      const needle = cycling ? query[0] : query;
+      const from =
+        cycling || query.length === 1 ? (current ?? -1) + 1 : (current ?? 0);
+
+      const n = items.length;
+      for (let k = 0; k < n; k++) {
+        const i = (((from + k) % n) + n) % n;
+        const item = items[i];
+        if (selectable && !selectable(item)) continue;
+        const label = String(labelOf(item) ?? '').toLowerCase();
+        if (label.startsWith(needle)) return i;
+      }
+      return -1;
+    },
+    [timeout],
+  );
+}
+
+/** A printable character usable for type-ahead. Space is excluded: it
+ *  activates the focused entry everywhere in this widget set. */
+export function typeAheadChar(ev) {
+  return ev.key && ev.key.length === 1 && ev.codepoint > 32 ? ev.key : null;
+}