react-x11 2.51.1 → 2.53.0

package/docs/ecosystem/layout.md

@@ -0,0 +1,206 @@
+# Layout and positioning
+
+Layout itself is yoga's job — see [styling](../styling.md). The two packages
+here cover what yoga does not: placing a popup relative to a trigger across
+screen edges, and rendering a long list without a node per row. Both are the
+_core_ half of a library whose React wrapper is DOM-bound; the core is
+published separately so non-DOM hosts can use it.
+
+## `@floating-ui/core` {#floating-ui}
+
+**Adapter, ~35 lines (a platform object).** @floating-ui/core@1.8.0.
+
+Floating UI's positioning engine without DOM code. Hand `computePosition` a
+`platform` object — `getElementRects`, `getDimensions`, `getClippingRect`,
+`isRTL` — and get the full middleware pipeline (`offset`, `flip`, `shift`,
+`size`, `arrow`, `autoPlacement`, `hide`) and its placement vocabulary.
+
+As in the built-in `anchorRect()`, a drawn node's `node.abs` rect plus the
+window's screen origin is the reference rect in screen coordinates,
+`screenOf(node)` gives the clipping rect, and the popup-to-be is just
+`{width, height}`. The result's `{x, y, placement}` drops straight into
+`<popup x y>`.
+
+```jsx
+import { computePosition, offset, flip, shift } from '@floating-ui/core';
+
+// The screen a node is on. Same three lines the built-in anchorRect uses;
+// it is not exported from the package, so keep a copy.
+function screenOf(node) {
+  const app = node?.app;
+  const screen = (app?.display ?? app?.X?.display)?.screen?.[0];
+  return screen?.pixel_width ? screen : null;
+}
+
+// reference = a drawn node (post-layout); floating = the popup's {width, height}
+function screenRectOf(node) {
+  const win = node.root?.window;
+  const origin = win?._screenOrigin ?? { x: win?.x ?? 0, y: win?.y ?? 0 };
+  return {
+    x: origin.x + node.abs.x,
+    y: origin.y + node.abs.y,
+    width: node.abs.width,
+    height: node.abs.height,
+  };
+}
+
+const platform = {
+  getElementRects: ({ reference, floating }) => ({
+    reference: screenRectOf(reference),
+    floating: { x: 0, y: 0, width: floating.width, height: floating.height },
+  }),
+  getDimensions: (el) => el.abs ?? el, // node or plain {width, height}
+  getClippingRect: ({ element }) => {
+    const s = screenOf(element?.node ?? element);
+    return s
+      ? { x: 0, y: 0, width: s.pixel_width, height: s.pixel_height }
+      : { x: 0, y: 0, width: Infinity, height: Infinity };
+  },
+  isElement: () => true,
+  isRTL: () => false,
+};
+
+const { x, y, placement } = await computePosition(
+  triggerNode, // from a ref on the trigger <box>
+  { width: 200, height: 150, node: triggerNode },
+  {
+    placement: 'bottom-start',
+    middleware: [offset(4), flip(), shift({ padding: 8 })],
+    platform,
+  },
+);
+// -> <popup x={x} y={y}> ; placement tells you which side won
+```
+
+Over `anchorRect` this adds middleware composition (`shift` with padding,
+`size` to clamp long menus, `arrow`) and alignment fallback — `flip` with
+`crossAxis: 'alignment'` switches `bottom-start` to `bottom-end` when that
+fits. `anchorRect`'s `placement`, `align` and `offset` options map 1:1 onto
+`placement` plus the `offset()` middleware.
+
+- `computePosition` is async — `await` it, though this platform is
+  synchronous.
+- `getClippingRect` above is screen 0's full rect, the same single-monitor
+  simplification as `screenOf`. On a dual-head X display, popups clamp to
+  the bounding box of both monitors.
+- **`@floating-ui/dom` and `@floating-ui/react` are not usable** (DOM
+  platform and DOM interactions). Only `core` and its `@floating-ui/utils`
+  dependency belong in an X11 app.
+- Safe-polygon hover lives in `@floating-ui/react`'s DOM-bound `useHover`,
+  not in `core`; keep react-x11's built-in one.
+
+## `@tanstack/virtual-core` {#tanstack-virtual}
+
+**Adapter, ~40 lines.** @tanstack/virtual-core@3.17.7.
+
+The engine behind `useVirtualizer`: from a count, an `estimateSize`, the
+viewport rect and the scroll offset it computes the visible items
+(`getVirtualItems()`), the total size (`getTotalSize()`), and offsets for
+`scrollToIndex`. Every DOM touchpoint is a constructor option.
+
+**Do not import `@tanstack/react-virtual`.** Its first line is
+`import { flushSync } from "react-dom"`: without react-dom it fails to
+resolve; _with_ it, it silently flushes into the wrong reconciler
+([silent failures](../ecosystem.md#silent-failures)). The hook below is
+everything the React wrapper adds.
+
+Three seams wire to a scrolling `<box>`:
+
+- `observeElementRect` → `<box onViewport>`, which fires from layout
+  with `{width, height, contentWidth, contentHeight}` — including before any
+  scroll, which is what a list needs on mount;
+- `observeElementOffset` → `<box onScroll>` (`scrollY`);
+- `scrollToFn` → `ref.scrollTo(offset)`.
+
+`getScrollElement()` must return something with
+`scrollHeight`/`clientHeight` (virtual-core duck-types Element vs Window
+with `'scrollHeight' in el`); a getter shim over the node's
+`contentHeight`/`abs.height` satisfies it.
+
+```jsx
+import React from 'react';
+import { Virtualizer } from '@tanstack/virtual-core';
+
+function useX11Virtualizer({ count, estimateSize, overscan = 2 }) {
+  const ref = React.useRef(null);
+  const obs = React.useRef({});
+  const [, rerender] = React.useReducer((n) => n + 1, 0);
+  const [element] = React.useState(() => ({
+    // element-shaped view of the node
+    get scrollHeight() {
+      return ref.current?.contentHeight ?? 0;
+    },
+    get clientHeight() {
+      return ref.current?.abs.height ?? 0;
+    },
+    get scrollWidth() {
+      return ref.current?.contentWidth ?? 0;
+    },
+    get clientWidth() {
+      return ref.current?.abs.width ?? 0;
+    },
+  }));
+  const [v] = React.useState(
+    () =>
+      new Virtualizer({
+        count,
+        estimateSize,
+        overscan,
+        getScrollElement: () => (ref.current ? element : null),
+        observeElementRect: (_i, cb) => {
+          obs.current.rect = cb;
+        },
+        observeElementOffset: (_i, cb) => {
+          obs.current.offset = cb;
+          cb(0, false);
+        },
+        scrollToFn: (offset) => ref.current?.scrollTo(offset),
+        onChange: () => rerender(),
+      }),
+  );
+  v.setOptions({ ...v.options, count, onChange: () => rerender() });
+  React.useEffect(() => v._didMount(), []);
+  React.useEffect(() => v._willUpdate());
+  return {
+    virtualizer: v,
+    scrollProps: {
+      ref,
+      onViewport: (r) => obs.current.rect?.(r),
+      onScroll: (s) => obs.current.offset?.(s.scrollY, true),
+    },
+  };
+}
+```
+
+```jsx
+function BigList() {
+  const { virtualizer, scrollProps } = useX11Virtualizer({
+    count: 10000,
+    estimateSize: () => 24,
+  });
+  return (
+    <box {...scrollProps} style={{ flexGrow: 1, overflow: 'scroll' }}>
+      <box style={{ height: virtualizer.getTotalSize() }}>
+        {virtualizer.getVirtualItems().map((item) => (
+          <text
+            key={item.key}
+            style={{ position: 'absolute', top: item.start, height: item.size }}
+          >
+            {`row ${item.index}`}
+          </text>
+        ))}
+      </box>
+    </box>
+  );
+}
+```
+
+- **First paint shows zero rows.** Layout runs on the frame clock after the
+  mount commit, `onViewport` reports a tick later, and the list fills in on
+  the next frame. Fine interactively; tests must tick a few times.
+- `estimateSize` is the only measurement; `measureElement` is built on
+  `ResizeObserver` and `getBoundingClientRect`. For variable-height rows
+  pass exact sizes: `estimateSize: (i) => heights[i]`.
+- `_didMount`/`_willUpdate` are underscored but are the documented pattern
+  for custom adapters — the official React, Vue and Svelte adapters call
+  exactly these.

package/docs/ecosystem/routing.md

@@ -0,0 +1,135 @@
+# Routing
+
+There is no URL bar and no `history` object, so both routers here run on
+their first-party in-memory location. What does not survive is `<Link>`,
+which renders an `<a>` host in both; navigate from a `<box onClick>`
+instead. These libraries give you matching, not a back stack — build stack
+or tab navigation on top if you need it.
+
+## wouter {#wouter}
+
+**Out of the box — with `wouter/memory-location`.** wouter@3.10.0.
+
+A 2 kB router: `<Router>`, `<Route>`, `<Switch>`, `useLocation`, pattern
+params, and a pluggable location hook with a non-browser one shipped.
+
+```jsx
+import React from 'react';
+import { createRoot } from 'react-x11';
+import { Router, Route, Switch } from 'wouter';
+import { memoryLocation } from 'wouter/memory-location';
+
+const { hook, navigate } = memoryLocation({ path: '/' });
+
+// the react-x11 replacement for <Link>
+const NavText = ({ href, children }) => (
+  <box style={{ height: 20 }} onClick={() => navigate(href)}>
+    <text style={{ color: '#08c' }}>{children}</text>
+  </box>
+);
+
+const App = () => (
+  <window width={400} height={300} title="routed">
+    <box style={{ flexGrow: 1, flexDirection: 'column' }}>
+      <Router hook={hook}>
+        <box style={{ flexDirection: 'row', gap: 8, height: 20 }}>
+          <NavText href="/">home</NavText>
+          <NavText href="/about">about</NavText>
+        </box>
+        <Switch>
+          <Route path="/">
+            <text>home page</text>
+          </Route>
+          <Route path="/about">
+            <text>about page</text>
+          </Route>
+          <Route>
+            <text>not found</text>
+          </Route>
+        </Switch>
+      </Router>
+    </box>
+  </window>
+);
+
+(await createRoot()).render(<App />);
+```
+
+- **Always mount the memory hook at the top.** A `<Route>` outside a
+  `<Router hook={...}>` falls back to `useBrowserLocation` and crashes
+  immediately with `ReferenceError: location is not defined`.
+- **`<Link>` does not work**: it renders an `<a>`. `<Link asChild>` avoids
+  the `<a>` but does not navigate, because its click guard checks
+  `event.button !== 0` and react-x11's `MouseEvent.button` is the X button
+  number, `1` for left.
+- `useLocation()[1]` is the same `navigate` from inside components; the
+  module-level one is handier with a single router.
+- `useHashLocation` and `useBrowserLocation` are browser-only. Everything
+  else — matching, params, nesting, `useRoute` — is pure.
+- `memoryLocation({ record: true })` keeps a `history` array, which is the
+  raw material for a back stack and handy to assert on in tests.
+
+## react-router {#react-router}
+
+**Out of the box — `MemoryRouter`, and none of the DOM components.**
+react-router 7.18.2.
+
+The router core — `useRoutes`, `useNavigate`, `useParams`, `useLocation`,
+loaders, actions — is DOM-free. Import from `react-router`, not
+`react-router-dom`, whose browser entry points are what fails.
+
+```jsx
+import React from 'react';
+import { createRoot } from 'react-x11';
+import {
+  MemoryRouter,
+  Routes,
+  Route,
+  useNavigate,
+  useLocation,
+} from 'react-router';
+
+function Home() {
+  const navigate = useNavigate();
+  return (
+    <box style={{ flexDirection: 'column' }}>
+      <text>home page</text>
+      <box style={{ height: 20 }} onClick={() => navigate('/about')}>
+        <text>go to about</text>
+      </box>
+    </box>
+  );
+}
+
+function About() {
+  const loc = useLocation();
+  return <text>{`about page (${loc.pathname})`}</text>;
+}
+
+(await createRoot()).render(
+  <window width={300} height={200} title="routed">
+    <box style={{ flexGrow: 1 }}>
+      <MemoryRouter initialEntries={['/']}>
+        <Routes>
+          <Route path="/" element={<Home />} />
+          <Route path="/about" element={<About />} />
+          <Route path="*" element={<text>not found</text>} />
+        </Routes>
+      </MemoryRouter>
+    </box>
+  </window>,
+);
+```
+
+- **`BrowserRouter` and `HashRouter` fail** — `createBrowserHistory` needs
+  `window.history`. The error is
+  `react-x11: uncaught error ReferenceError: document is not defined` at
+  `getUrlBasedHistory`; `render()` does not throw, react-x11 logs it and the
+  window count stays 0.
+- **`<Link>`, `<NavLink>` and `<Form>` all render `<a>`/`<form>` hosts** and
+  cannot work. Use `useNavigate()` on a `<box onClick>`.
+- A `<Link>` with a bare string child hits the raw-text error before the
+  element error: `react-x11: raw text "go" must be wrapped in a <text>
+element`. Both are in the
+  [register](../ecosystem.md#render-time).
+- Without loaders and actions, wouter is the much smaller dependency.

package/docs/ecosystem/state.md

@@ -0,0 +1,344 @@
+# State management
+
+Every store here subscribes through React's own `useSyncExternalStore` and
+never touches a host environment. Their out-of-React surface matters more in
+a desktop app than on the web: an X event callback, an ntk timer or a D-Bus
+signal handler can write to the store directly, and every subscribed
+component under every `<window>` re-renders.
+
+Versions are the ones tested; newer releases in the same major are expected
+to behave the same.
+
+## zustand {#zustand}
+
+**Out of the box.** zustand@5.0.14.
+
+A small store: `create((set) => ({...}))` returns a hook that components
+call with a selector, and `useStore.getState()` / `useStore.subscribe()`
+work outside React. The default recommendation for app state.
+
+```jsx
+import React from 'react';
+import { createRoot } from 'react-x11';
+import { create } from 'zustand';
+
+const useStore = create((set) => ({
+  n: 0,
+  inc: () => set((s) => ({ n: s.n + 1 })),
+}));
+
+function App() {
+  const n = useStore((s) => s.n);
+  return (
+    <window width={200} height={100} title="counter">
+      <box style={{ padding: 8 }} onClick={() => useStore.getState().inc()}>
+        <text>count: {n}</text>
+      </box>
+    </window>
+  );
+}
+
+(await createRoot()).render(<App />);
+```
+
+The store is module-level, so several windows share it.
+
+- `zustand/middleware`'s `persist` defaults to `localStorage`; pass a
+  `storage` backed by `node:fs` (`createJSONStorage(() => fileStorage)`).
+- `zustand/traditional` (`createWithEqualityFn`) also works; the
+  shallow-compare helper is pure.
+
+## jotai {#jotai}
+
+**Out of the box.** jotai@2.20.2.
+
+Atomic state: `atom(initial)` defines a unit, `useAtom`/`useAtomValue`/
+`useSetAtom` read and write it, and derived atoms recompute from their
+dependencies. In a desktop app use an explicit store: create it at startup,
+hand it to `<Provider>`, and let X event handlers or background work call
+`store.set(...)`. One store shared by several `<window>` trees keeps them in
+sync.
+
+```jsx
+import React from 'react';
+import { createRoot } from 'react-x11';
+import { atom, createStore, Provider, useAtomValue } from 'jotai';
+
+const countAtom = atom(0);
+const doubledAtom = atom((get) => get(countAtom) * 2);
+const store = createStore();
+
+function App() {
+  const doubled = useAtomValue(doubledAtom);
+  return (
+    <window width={200} height={100} title="jotai">
+      <text>doubled: {doubled}</text>
+    </window>
+  );
+}
+
+(await createRoot()).render(
+  <Provider store={store}>
+    <App />
+  </Provider>,
+);
+setInterval(() => store.set(countAtom, (n) => n + 1), 1000);
+```
+
+- `jotai/utils`' `atomWithStorage` defaults to `localStorage`; supply a
+  custom storage (sync or async).
+- Async atoms suspend; wrap consumers in `<React.Suspense>` (react-x11
+  renders fallbacks like any React 19 host) or use `loadable()`.
+
+## valtio {#valtio}
+
+**Out of the box.** valtio@2.3.2.
+
+Proxy-based state: `proxy(obj)` returns an object you mutate directly;
+`useSnapshot(state)` returns an immutable snapshot and re-renders only when
+the properties read change. Mutation from anywhere suits X event handlers
+and ntk callbacks; `subscribe(state, cb)` pushes state into non-React things
+— a selection onto the clipboard, a window title set imperatively.
+
+```jsx
+import React from 'react';
+import { createRoot } from 'react-x11';
+import { proxy, useSnapshot } from 'valtio';
+
+const state = proxy({ n: 0, log: [] });
+
+function App() {
+  const snap = useSnapshot(state);
+  return (
+    <window width={220} height={120} title="valtio">
+      <box
+        style={{ padding: 8 }}
+        onClick={() => {
+          state.n += 1;
+          state.log.push(Date.now());
+        }}
+      >
+        <text>clicked {snap.n} times</text>
+      </box>
+    </window>
+  );
+}
+
+(await createRoot()).render(<App />);
+```
+
+- Valtio 2 no longer deep-clones snapshots in dev the way v1 did; read the
+  v2 migration notes if you port v1 examples.
+- `valtio/utils`' `devtools()` targets the Redux DevTools browser extension
+  and is a no-op here.
+
+## XState {#xstate}
+
+**Out of the box.** xstate@5.32.5, @xstate/react@6.1.0.
+
+`createMachine` describes states, events, guards and actions;
+`createActor` interprets one; `@xstate/react` provides `useMachine`,
+`useActor`, `useActorRef` and `useSelector`. Statecharts suit desktop
+chrome: drag-resize, modal and focus flows, a connection lifecycle
+(`connecting → connected → retrying`), cancellable jobs. An actor started at
+app level can outlive any single `<window>` and drive several.
+
+```jsx
+import React from 'react';
+import { createRoot } from 'react-x11';
+import { createMachine, createActor } from 'xstate';
+import { useSelector } from '@xstate/react';
+
+const toggle = createMachine({
+  id: 'toggle',
+  initial: 'off',
+  states: {
+    off: { on: { TOGGLE: 'on' } },
+    on: { on: { TOGGLE: 'off' } },
+  },
+});
+const actor = createActor(toggle).start();
+
+function App() {
+  const value = useSelector(actor, (s) => s.value);
+  return (
+    <window width={220} height={120} title="xstate">
+      <box
+        style={{ padding: 8 }}
+        onClick={() => actor.send({ type: 'TOGGLE' })}
+      >
+        <text>state: {value}</text>
+      </box>
+    </window>
+  );
+}
+
+(await createRoot()).render(<App />);
+```
+
+- `useMachine(machine)` inside a component gives a component-scoped actor;
+  the external actor above is better for machines shared across windows.
+- `@statelyai/inspect` connects over WebSocket to Stately's editor, which
+  works from Node; the iframe inspector expects a browser.
+
+## Redux {#redux}
+
+**Out of the box — pin `react-redux@>=9`.** react-redux@9.3.0,
+@reduxjs/toolkit@2.12.0, redux@5.0.1.
+
+react-redux 9 no longer imports `react-dom`/`react-native` for
+`unstable_batchedUpdates` and subscribes through `useSyncExternalStore`, so
+it needs no shim. redux core and RTK, listener and observable middleware
+included, are pure JS.
+
+```jsx
+import React from 'react';
+import { createRoot } from 'react-x11';
+import { configureStore, createSlice } from '@reduxjs/toolkit';
+import { Provider, useSelector, useDispatch } from 'react-redux';
+
+const counter = createSlice({
+  name: 'counter',
+  initialState: { n: 0 },
+  reducers: {
+    inc: (s) => {
+      s.n += 1;
+    }, // immer draft — mutation is fine
+  },
+});
+const store = configureStore({ reducer: { counter: counter.reducer } });
+
+function Counter() {
+  const n = useSelector((s) => s.counter.n);
+  const dispatch = useDispatch();
+  return (
+    <box style={{ padding: 8 }} onClick={() => dispatch(counter.actions.inc())}>
+      <text>count: {n}</text>
+    </box>
+  );
+}
+
+(await createRoot()).render(
+  <Provider store={store}>
+    <window width={220} height={120} title="redux">
+      <Counter />
+    </window>
+  </Provider>,
+);
+```
+
+- **The version pin is the one thing you must know.** react-redux 8 imports
+  `react-dom` unconditionally: npm refuses it with `ERESOLVE` on React 19,
+  and behind `--legacy-peer-deps` the app fails at startup with
+  `Cannot find module 'react-dom'`. Both are in the
+  [negative-results register](../ecosystem.md#install-and-import-time).
+- RTK's `devTools: true` (the default) looks for the Redux DevTools
+  extension global and is harmless when absent; `@redux-devtools/cli` is a
+  remote devtools server if you want inspection.
+- RTK Query works, but `setupListeners()` wires
+  `window.addEventListener('focus'|'online')`, absent under Node. Pass
+  `setupListeners(dispatch, customHandler)` a handler wired to
+  `<window onFocus>`, as in the
+  [TanStack Query adapter](data-fetching.md#tanstack-query).
+
+## Immer {#immer}
+
+**Out of the box.** immer@11.1.15.
+
+`produce(base, recipe)` runs a mutating recipe against a Proxy draft and
+returns a structurally-shared immutable result; curried `produce(recipe)` is
+a drop-in `setState` updater. It is already inside `@reduxjs/toolkit`'s
+`createSlice` reducers and available as zustand middleware
+(`zustand/middleware/immer`).
+
+```jsx
+import React from 'react';
+import { createRoot } from 'react-x11';
+import { produce } from 'immer';
+
+function App() {
+  const [state, setState] = React.useState({
+    items: [{ label: 'a', done: false }],
+  });
+  const toggle = (i) =>
+    setState(
+      produce((draft) => {
+        draft.items[i].done = !draft.items[i].done;
+      }),
+    );
+  return (
+    <window width={260} height={160} title="todo">
+      {state.items.map((it, i) => (
+        <box key={it.label} style={{ padding: 4 }} onClick={() => toggle(i)}>
+          <text>
+            {it.done ? '[x] ' : '[ ] '}
+            {it.label}
+          </text>
+        </box>
+      ))}
+    </window>
+  );
+}
+
+(await createRoot()).render(<App />);
+```
+
+Useful directly with `useState`/`useReducer` for the nested state desktop
+apps accumulate — tree views, multi-pane layouts.
+
+## MobX {#mobx}
+
+**Adapter — no code, but `react-dom` must be installed.** mobx@6.16.1,
+mobx-react-lite@4.1.1.
+
+Observable state via `makeAutoObservable`/`observable`; `mobx-react-lite`'s
+`observer()` re-renders a component when the observables it dereferences
+change. mobx core is pure JS.
+
+**Every build of mobx-react-lite does
+`import { unstable_batchedUpdates } from "react-dom"`** at module load, to
+install React's batcher as mobx's reaction scheduler. Without react-dom the
+app fails at startup with `Cannot find module 'react-dom'`.
+
+The fix is `npm install react-dom`. Its top-level entry is Node-safe (the
+one SSR uses), react-x11 never renders through it, and React 19's
+`unstable_batchedUpdates` batches correctly for any renderer. With it
+present, `observer` subscribes through `use-sync-external-store` and
+mutations from X event handlers or timers re-render the tree.
+
+```jsx
+// prerequisite: npm install react-dom  (satisfies mobx-react-lite's import;
+// react-x11 does not render through it)
+import React from 'react';
+import { createRoot } from 'react-x11';
+import { makeAutoObservable, runInAction } from 'mobx';
+import { observer } from 'mobx-react-lite';
+
+const store = makeAutoObservable({ n: 0 });
+
+const App = observer(function App() {
+  return (
+    <window width={220} height={120} title="mobx">
+      <box
+        style={{ padding: 8 }}
+        onClick={() =>
+          runInAction(() => {
+            store.n += 1;
+          })
+        }
+      >
+        <text>count: {store.n}</text>
+      </box>
+    </window>
+  );
+});
+
+(await createRoot()).render(<App />);
+```
+
+- Without react-dom the failure is at import time, not render time, and the
+  require stack names mobx-react-lite.
+- `mobx-react` layers on mobx-react-lite, so the same applies. Prefer
+  `-lite`.
+- Do not import from `react-dom` yourself; it is a compatibility shim here,
+  nothing more.