react-x11 2.51.0 → 2.52.0

package/docs/ecosystem/forms.md

@@ -0,0 +1,313 @@
+# Forms and validation
+
+There is no `<form>` element here, so nothing submits itself — wire
+`handleSubmit` to a `Button`'s `onPress` or to `<textinput onSubmit>`.
+
+Everything else follows from **one signature**. Every value control in the
+library — the host elements `<textinput>` and `<textarea>`, and the widgets
+`Checkbox`, `Switch`, `RadioGroup`, `Select` and `Slider` — calls
+`onChange(ev)` with a change event carrying `ev.value`, `ev.target.value`,
+`ev.target.name` and, for a checkbox, `ev.target.checked`. That is the shape
+every DOM form library reads, so a library's handler goes straight in:
+
+```jsx
+<textinput name="host"  value={f.values.host}   onChange={f.handleChange} />
+<Checkbox  name="agree" checked={f.values.agree} onChange={f.handleChange} />
+<Select    name="size"  value={f.values.size} options={sizes} onChange={f.handleChange} />
+```
+
+No adapter, no per-widget bridge, nothing to remember about which control
+you are wiring.
+
+| library                | how it goes in                                            |
+| ---------------------- | --------------------------------------------------------- |
+| `react-hook-form`      | `{...register('host')}`, or `<Controller>` for a widget   |
+| `formik`               | `onChange={handleChange}`, `getFieldProps`, or `<Field>`  |
+| `downshift`            | `getInputProps()` spread onto a `<textinput>`             |
+| `@tanstack/react-form` | `onChange={(ev) => field.handleChange(ev.value)}` — below |
+
+Every row was established by running the library headless against this
+renderer rather than by reading its documentation: react-hook-form@7.84.0,
+formik@2.4.9, downshift@9.4.0, @tanstack/react-form@1.33.2.
+
+**The one thing to know**: a library whose field contract is
+value-in/value-out — TanStack Form is the one here — needs the value taken
+off the event, and a bare `onChange={field.handleChange}` stores the _event
+object_ as the field value with no error. See below.
+
+**Where the line falls.** A control that takes a `name` is a form field and
+reports an event. `Tabs`, `Table` and the menus are not form fields
+and keep their plain callbacks
+([components](../components.md#the-change-event-and-name)).
+
+## TanStack Form {#tanstack-form}
+
+**Out of the box.** @tanstack/react-form@1.33.2 (form-core 1.33.2).
+
+A headless, framework-agnostic form state manager: field values, dirty and
+touched tracking, sync and async validation (including Standard Schema, so
+zod/valibot/arktype plug in directly), and submission handling. Fields are
+value-in/value-out — no DOM events, no refs.
+
+The field contract is `field.state.value` + `field.handleChange(value)` —
+a **value, not an event**. react-x11's controls fire an event, so each field
+takes the value off it:
+
+```jsx
+onChange={(ev) => field.handleChange(ev.value)}
+```
+
+One expression, the same one a DOM app writes, and it is identical for a
+`<textinput>` and for a `Checkbox`.
+
+Watch for the bare form: `onChange={field.handleChange}` stores the event
+object as the field's value — no error, no warning, and validation sees an
+object where it expected a string.
+
+```jsx
+import React from 'react';
+import { useForm } from '@tanstack/react-form';
+import { Button } from 'react-x11';
+import { z } from 'zod';
+
+function ConnectForm({ connect }) {
+  const form = useForm({
+    defaultValues: { host: '', display: ':0' },
+    onSubmit: async ({ value }) => connect(value),
+  });
+  return (
+    <box style={{ flexDirection: 'column', gap: 8 }}>
+      <form.Field
+        name="host"
+        validators={{ onChange: z.string().min(3, 'too short') }}
+      >
+        {(field) => (
+          <box style={{ flexDirection: 'column' }}>
+            <textinput
+              value={field.state.value}
+              onChange={(ev) => field.handleChange(ev.value)}
+            />
+            {field.state.meta.errors.length > 0 && (
+              <text style={{ color: '#cc4444' }}>
+                {field.state.meta.errors[0].message}
+              </text>
+            )}
+          </box>
+        )}
+      </form.Field>
+      <Button label="Connect" onPress={() => form.handleSubmit()} />
+    </box>
+  );
+}
+```
+
+- No `<form>` element exists, so there is no submit-on-Enter for free. Wire
+  `form.handleSubmit()` to a button's `onPress` and/or a window-level Enter
+  key handler.
+- The **widgets** are the exception: `Checkbox`, `Switch`, `RadioGroup`,
+  `Select` and `Slider` still pass the next value first, so
+  `onChange={field.handleChange}` is right there and needs no unwrap. Only
+  the host elements `<textinput>`/`<textarea>` changed.
+- Validation errors from a zod schema are error _objects_
+  (`errors[0].message`), not strings; a plain string validator returns
+  strings. A `<text>` child must be a string, so render `.message`.
+- The package also ships SSR and Next helpers under subpaths; the root
+  import used here pulls in no react-dom.
+
+## zod {#zod}
+
+**Out of the box.** zod@4.4.3.
+
+TypeScript-first schema validation. Pure computation, no DOM, nothing
+renderer-specific — the interesting part is only where it plugs in:
+
+- **TanStack Form** — pass a schema straight into a field's
+  `validators: { onChange: z.string().min(3, 'too short') }`. Zod 4
+  implements Standard Schema, so no resolver package is needed.
+- **React Hook Form** — via `@hookform/resolvers/zod`, with either
+  `register()` or `Controller`; see below.
+- **Standalone** — validating a settings file or a config blob before
+  rendering is just `schema.safeParse(data)`.
+
+```jsx
+import { z } from 'zod';
+
+const settings = z.object({
+  display: z.string().regex(/^:\d+$/, 'DISPLAY looks like :0'),
+  scale: z.coerce.number().min(0.5).max(3).default(1),
+});
+
+function Settings({ raw }) {
+  const parsed = settings.safeParse(raw);
+  if (!parsed.success) {
+    // render the issues instead of crashing the app
+    return (
+      <box style={{ flexDirection: 'column' }}>
+        {parsed.error.issues.map((i) => (
+          <text
+            key={i.path.join('.')}
+          >{`${i.path.join('.')}: ${i.message}`}</text>
+        ))}
+      </box>
+    );
+  }
+  return <text>display {parsed.data.display}</text>;
+}
+```
+
+- Zod 4 field errors surface as issue objects; render `issue.message`, not
+  the issue itself.
+- `valibot` and `arktype` are equally viable (also Standard Schema). zod is
+  documented here because both verified form integrations used it.
+- Bundle-size arguments from the web world do not apply — an X11 app ships
+  no bundle.
+
+## React Hook Form {#react-hook-form}
+
+**Out of the box, both APIs.** react-hook-form@7.84.0 with
+@hookform/resolvers@5.5.7.
+
+RHF's headline API is uncontrolled-first: `register()` returns DOM-shaped
+props (`{name, ref, onChange(e), onBlur(e)}`) and reads `e.target.value` off
+the event. That is exactly what `<textinput>` provides, so the terse spread
+works:
+
+```jsx
+const { register, handleSubmit } = useForm({ defaultValues: { host: '' } });
+<textinput {...register('host')} />;
+```
+
+Three things had to line up, and all three now do: `name` exists as a prop,
+`onChange` receives an event whose `target.value` is the new text, and the
+`ref` RHF attaches lands on a node whose `value` is **writable** — RHF
+assigns `ref.value = ''` while registering the field, which used to throw
+`TypeError: Cannot set property value of #<TextInputNode> which has only a
+getter` from inside the commit phase and take the render down with it.
+
+Verified working through `register()`: typing updates `getValues()`,
+`handleSubmit` receives them, `setValue(name, v)` writes through the ref so
+the field redraws, and `setFocus(name)` focuses the node.
+
+One asymmetry to know about: **`reset()` updates form state but does not
+clear an uncontrolled field's text.** RHF only writes values back through
+refs on the reset path when its `isWeb` probe
+(`typeof window !== 'undefined' && window.HTMLElement && document`) passes,
+which it never does here. `setValue()` is not gated that way and does write
+through. If you need `reset()` to clear the display, make the field
+controlled — `<Controller>`, below — or assign `ref.current.value = ''`
+yourself.
+
+`<Controller>` / `useController` still works, unchanged, and is the better
+choice when you want the field controlled. `field.onChange` accepts either a
+plain value or an event, so both of these are fine:
+
+```jsx
+onChange={(ev) => field.onChange(ev.target.value)}   // explicit
+onChange={field.onChange}                            // RHF unwraps .target
+```
+
+```jsx
+import React from 'react';
+import { useForm, Controller } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { Button } from 'react-x11';
+import { z } from 'zod';
+
+const schema = z.object({
+  host: z.string().min(3, 'too short'),
+  display: z.string(),
+});
+
+function ConnectForm({ connect }) {
+  const { control, handleSubmit } = useForm({
+    defaultValues: { host: '', display: ':0' },
+    resolver: zodResolver(schema),
+    mode: 'onChange',
+  });
+  return (
+    <box style={{ flexDirection: 'column', gap: 8 }}>
+      <Controller
+        name="host"
+        control={control}
+        render={({ field, fieldState }) => (
+          <box style={{ flexDirection: 'column' }}>
+            <textinput
+              value={field.value}
+              onChange={field.onChange}
+              onBlur={field.onBlur}
+            />
+            {fieldState.error && <text>{fieldState.error.message}</text>}
+          </box>
+        )}
+      />
+      <Button label="Connect" onPress={handleSubmit(connect)} />
+    </box>
+  );
+}
+```
+
+- A `Controller` field is controlled, so its subtree re-renders on every
+  keystroke. `register()` does not, which is the same performance argument
+  RHF makes on the web — and it now applies here too.
+- `setFocus(name)` works: it calls `.focus()` on whatever the ref holds, and
+  a `<textinput>` node has one.
+- `handleSubmit` returns a function. Call it: `handleSubmit(fn)` in an
+  `onPress` is the curried form, and there is no submit event to pass.
+
+## Formik {#formik}
+
+**Out of the box.** formik@2.4.9.
+
+Formik was the clearest casualty of the old `onChange(string)` contract, and
+it failed _silently_: `handleChange` treats a string argument as its curried
+field-name form, returns a handler, and never touches state — so spreading
+`getFieldProps` onto a `<textinput>` left `values` at its initial object and
+`touched` empty, with nothing logged. That is fixed by the event, not by an
+adapter. All three of Formik's field styles now work:
+
+```jsx
+import { Formik, Field, useFormik } from 'formik';
+
+// 1. the spread
+<textinput {...formik.getFieldProps('host')} />
+
+// 2. by hand
+<textinput
+  name="host"
+  value={formik.values.host}
+  onChange={formik.handleChange}
+  onBlur={formik.handleBlur}
+/>
+
+// 3. <Field> with a render prop
+<Field name="host">
+  {({ field }) => <textinput {...field} />}
+</Field>
+```
+
+`handleChange` reads `target.name` to decide which field to write, so the
+`name` prop is not optional in any of these — that is what the synthetic
+event carries it for.
+
+The widgets need no bridge — same handler, same signature:
+
+```jsx
+<Checkbox
+  name="agree"
+  checked={formik.values.agree}
+  onChange={formik.handleChange}
+>
+  I agree
+</Checkbox>
+```
+
+`ev.target` is `{ type: 'checkbox', name, value, checked }`, which is exactly
+what `handleChange` destructures — including `type`, which is how it knows to
+take `checked` rather than `value`.
+
+- `<Formik>`'s render-prop form and `useFormik` both work; there is no
+  `<form>` element, so call `submitForm()` (or `handleSubmit()`) yourself
+  from a `Button` or from `<textinput onSubmit>`.
+- Passing a non-event object to `handleChange` — a hand-rolled fake event
+  with no `target` — still throws `TypeError: Cannot read properties of
+undefined (reading 'type')` rather than no-opping. Pass the real event.

package/docs/ecosystem/headless.md

@@ -0,0 +1,219 @@
+# Headless components
+
+"Headless" is a promise that gets broken a lot. A library that returns DOM
+prop bags — `getInputProps()`, `useButton()` — is not headless in any sense
+that helps here; it is DOM-coupled with the rendering deferred. The two
+packages below are the real thing: they own state and collections, return
+plain values, and never touch a ref.
+
+Everything else that markets itself as headless is in the
+[negative-results register](../ecosystem.md#what-does-not-work) — Headless
+UI, the Radix primitives and downshift all fail, the last one silently until
+the first keystroke.
+
+For finished widgets, react-x11 ships its own: `Button`, `Checkbox`,
+`Radio`/`RadioGroup`, `Switch`, `ProgressBar`, `Select`, `Slider`, `Tooltip`,
+`Dialog`, `MenuBar`/`ContextMenu`, `Tabs`, `Table`, `SplitPane`. See
+[components](../components.md).
+
+## react-stately {#react-stately}
+
+**Out of the box.** react-stately@3.48.0.
+
+The state-machine half of React Aria: `useListState`, `useTreeState`,
+`useTableState`, `useSelectState`, `useToggleState`, `useSliderState`,
+`useComboBoxState`, `useMenuTriggerState`, `useNumberFieldState` and about
+thirty-five more, plus the `Item`/`Section` collection API. Each hook owns
+selection, disabled-key traversal, expansion and typeahead-ready collections
+— everything a widget needs _except_ rendering and event binding, which is
+exactly the part react-x11 supplies.
+
+There is no seam to bridge: the hooks take props, return state, and never
+touch a ref. A scan of the shipped `dist/` finds no runtime reference to
+`document`, `window` or `getBoundingClientRect` in any hook, and its
+dependencies (`@internationalized/*`, `@react-types/shared`,
+`use-sync-external-store`) are DOM-free.
+
+```jsx
+import React from 'react';
+import { useListState, Item } from 'react-stately';
+
+function Picker() {
+  const state = useListState({
+    children: [
+      <Item key="alpha">Alpha</Item>,
+      <Item key="beta">Beta</Item>,
+      <Item key="gamma">Gamma</Item>,
+    ],
+    selectionMode: 'multiple',
+  });
+  const mgr = state.selectionManager;
+  return (
+    <box
+      style={{ flexDirection: 'column' }}
+      focusable
+      onKeyDown={(ev) => {
+        if (ev.key === 'ArrowDown')
+          mgr.setFocusedKey(
+            state.collection.getKeyAfter(mgr.focusedKey) ?? mgr.focusedKey,
+          );
+        if (ev.codepoint === 32) mgr.toggleSelection(mgr.focusedKey);
+      }}
+    >
+      {[...state.collection].map((item) => (
+        <box
+          key={item.key}
+          style={{ height: 20, justifyContent: 'center' }}
+          onClick={() => mgr.toggleSelection(item.key)}
+        >
+          <text>
+            {(mgr.isSelected(item.key) ? '* ' : '  ') + item.rendered}
+          </text>
+        </box>
+      ))}
+    </box>
+  );
+}
+```
+
+- **Only `react-stately` is portable.** `react-aria` (the hooks that produce
+  DOM props and bind DOM events) and `react-aria-components` are not — do not
+  follow Adobe's docs into `useListBox` or `useButton`, which return DOM prop
+  bags.
+- As of 3.48 the package is consolidated: the old `@react-stately/*` packages
+  are bundled in, with per-hook subpath exports
+  (`react-stately/useListState`) for lean imports.
+- The collection API wants `<Item>`/`<Section>` elements, or an `items` plus
+  render-function pair. It is a compile target of its own, slightly
+  ceremonious for a three-entry menu.
+- `useAsyncList` pulls in fetch-based loading state — fine under Node, but it
+  is the one hook with I/O opinions.
+- Drag-and-drop hooks (`useDraggableCollectionState`) hold state fine, but
+  everything that would _feed_ them events is DOM-side. Expect to write the
+  event plumbing.
+
+## `@tanstack/react-table` {#tanstack-table}
+
+**Out of the box.** @tanstack/react-table@9.1.2 (table-core 9.1.2,
+react-store 0.11.1).
+
+A headless table engine: column defs, row models, sorting, filtering,
+grouping, pagination, column sizing, visibility and pinning — as pure state
+plus derived row models. It renders nothing; you map `getHeaderGroups()` and
+`getRowModel().rows` to whatever the host renderer draws.
+
+v9 talks about "adapters", and the word means the framework, not the
+renderer: `@tanstack/react-table` _is_ the React adapter, wiring the
+framework-agnostic core's store to React's subscription model. react-x11 is
+React, so that adapter is already ours and there is nothing renderer-shaped
+to write. It still never touches `react-dom` or `document` at runtime —
+though v9 moves two of this page's checks, see the react-dom and `flexRender`
+bullets below. `column.getToggleSortingHandler()` still goes straight onto a
+header `onClick`.
+
+v9's API is modular where v8's was monolithic: features and row models are
+registered up front through `tableFeatures`, and the hook is `useTable`.
+
+```jsx
+import React from 'react';
+import {
+  useTable,
+  tableFeatures,
+  rowSortingFeature,
+  createCoreRowModel,
+  createSortedRowModel,
+  createColumnHelper,
+  flexRender,
+} from '@tanstack/react-table';
+
+// Registered once, outside the component. A feature that is not listed here
+// does not exist: its state slice, its column methods, its row model.
+const features = tableFeatures({
+  rowSortingFeature,
+  coreRowModel: createCoreRowModel(),
+  sortedRowModel: createSortedRowModel(),
+});
+
+const col = createColumnHelper();
+const columns = [
+  col.accessor('name', { header: 'Name' }),
+  col.accessor('port', { header: 'Port', cell: (i) => `:${i.getValue()}` }),
+];
+
+function Servers({ data }) {
+  const table = useTable({ features, columns, data });
+  return (
+    <box style={{ flexDirection: 'column' }}>
+      {table.getHeaderGroups().map((hg) => (
+        <box key={hg.id} style={{ flexDirection: 'row', height: 20 }}>
+          {hg.headers.map((h) => (
+            <box
+              key={h.id}
+              style={{ width: 120 }}
+              onClick={h.column.getToggleSortingHandler()}
+            >
+              <text>
+                {flexRender(h.column.columnDef.header, h.getContext())}
+              </text>
+            </box>
+          ))}
+        </box>
+      ))}
+      {table.getRowModel().rows.map((row) => (
+        <box key={row.id} style={{ flexDirection: 'row', height: 20 }}>
+          {row.getAllCells().map((cell) => (
+            <text key={cell.id} style={{ width: 120 }}>
+              {flexRender(cell.column.columnDef.cell, cell.getContext())}
+            </text>
+          ))}
+        </box>
+      ))}
+    </box>
+  );
+}
+```
+
+Sorting is uncontrolled here — the table's own store holds it, and the
+header click re-renders through the adapter's subscription. Pass
+`state`/`onSortingChange` as before to control it, or a selector as
+`useTable`'s second argument to subscribe a component to only some slices.
+
+The natural pairing is inside the existing `Table` component, or raw
+`<box style={{ flexDirection: 'row' }}>` rows: TanStack owns the data logic,
+react-x11 owns painting.
+
+- **`coreRowModel` is opt-in, and forgetting it fails silently.** Without
+  `coreRowModel: createCoreRowModel()` in `tableFeatures`, the table
+  constructs, headers render, and `getRowModel().rows` is `[]` — no error.
+  The official examples lean on framework presets that include it; register
+  it yourself.
+- **npm installs a `react-dom` you must not keep.** `@tanstack/react-store`
+  declares a `react-dom` _peer_ dependency, which npm 7+ auto-installs. The
+  shipped code never imports it — grep test 2 on all four `@tanstack`
+  packages finds one `"button"` in a doc comment, and this section was
+  verified with `node_modules/react-dom` deleted — but a resident react-dom
+  is exactly the [silent-failures](../ecosystem.md#silent-failures) hazard.
+  Install with `--legacy-peer-deps`, or delete it and let `npm ls react-dom`
+  stay empty.
+- **`flexRender` now returns a React element even for a plain string cell**
+  (v8 returned the string itself). Inside `<text>` that is fine — the string
+  arrives as a text chunk and paints identically — but a test or a11y walk
+  that reads a `<text>` node's `children` prop now sees an element object.
+  Read the rendered chunks, not the prop. A column def whose `cell` returns
+  DOM elements still throws the renderer's unknown-element error; return
+  strings or react-x11 elements.
+- Column _resizing_ helpers (`header.getResizeHandler`) still expect DOM
+  mouse or touch events with `clientX`, and now fall back to a
+  `document`-listener drag loop (injectable as `_contextDocument`). Simpler
+  to ignore the helper: write your own drag handling off
+  `onMouseDown`/`onMouseMove` — react-x11 events carry `x`/`y` — and call
+  `table.setColumnSizing` (needs `columnSizingFeature` registered).
+- `useTable` probes `typeof window` to pick `useLayoutEffect`; under Node it
+  gets the `useEffect` branch. That is a grep-test-3 hit of the harmless
+  kind — timing, not a feature gate — and the sorted re-render above runs
+  through it.
+- For thousands of rows, pair it with a virtualizer — see
+  [layout](layout.md#tanstack-virtual). TanStack Table will happily hand you
+  10,000 row objects and let the renderer drown.
+- State updates driven from outside a React event land one frame later than
+  the call, the same as any react-x11 update.

package/docs/ecosystem/i18n.md

@@ -0,0 +1,89 @@
+# Internationalization
+
+## i18next + react-i18next
+
+**Out of the box.** i18next@26.3.6, react-i18next@17.0.11.
+
+i18next is the de-facto JS i18n core — resources, interpolation, plurals,
+namespaces, backends — and react-i18next binds it to React with
+`useTranslation`, `<Trans>` for translations containing markup, and
+provider-driven re-render on language change.
+
+The core has no DOM in it and react-i18next renders whatever elements you
+hand it, so the whole stack runs unmodified: interpolation, count-based
+plurals, `<Trans>`, and `i18n.changeLanguage('de')` re-rendering the mounted
+tree in place. Node ships full ICU, so `Intl.NumberFormat` and
+`Intl.DateTimeFormat` formatting work too.
+
+Two react-x11-specific rules:
+
+1. **`<Trans>` component maps must use react-x11 elements.**
+   `components={{ 1: <span/> }}` throws
+   `react-x11: <span> is not allowed inside <text>` — inside a `<text>`, only
+   strings and nested `<text>` spans are legal. Use `<text style={...}/>` as
+   the wrapper.
+2. **Turn off HTML escaping.** i18next escapes interpolated values for an
+   HTML sink by default, and react-x11 draws raw glyphs, so `O'Brien` renders
+   as `O&#39;Brien`. Set `interpolation: { escapeValue: false }`.
+
+```jsx
+import React from 'react';
+import i18next from 'i18next';
+import {
+  I18nextProvider,
+  initReactI18next,
+  useTranslation,
+  Trans,
+} from 'react-i18next';
+
+const i18n = i18next.createInstance();
+await i18n.use(initReactI18next).init({
+  lng: 'en',
+  resources: {
+    en: {
+      translation: {
+        greeting: 'Hello, {{name}}!',
+        items_one: '{{count}} item',
+        items_other: '{{count}} items',
+        rich: 'Press <1>Enter</1> to save',
+      },
+    },
+  },
+  interpolation: { escapeValue: false }, // no HTML sink to escape for
+});
+
+function Status() {
+  const { t } = useTranslation();
+  return (
+    <box style={{ flexDirection: 'column' }}>
+      <text>{t('greeting', { name: 'X11' })}</text>
+      <text>{t('items', { count: 2 })}</text>
+      <text>
+        <Trans
+          i18nKey="rich"
+          components={{ 1: <text style={{ color: '#e00' }} /> }}
+        />
+      </text>
+    </box>
+  );
+}
+
+// mount under <I18nextProvider i18n={i18n}> inside your <window>;
+// i18n.changeLanguage('de') re-renders live
+```
+
+For loading translations from disk, `i18next-fs-backend` is the natural
+desktop choice; `i18next-http-backend` also works, since Node has `fetch`.
+
+## What is missing below the string
+
+These are react-x11 gaps rather than i18next ones, and they matter more than
+the library choice:
+
+- **There is no X input method.** Dead keys and the Compose key are handled
+  in the renderer ([events.md](../events.md#composition)), but there is no
+  XIM/IBus integration, so a language that needs a real input method — CJK —
+  can be _displayed_ but not typed.
+- `<Trans>` with the default `<strong>`- and `<em>`-style numbered tags in
+  translations is fine as long as every referenced component is a `<text>`
+  span. An accidental DOM tag fails loudly at render, which is the good case.