@react-x11/components 0.1.0 → 0.2.1

package/src/table/rows.ts

@@ -0,0 +1,275 @@
+// The row and column model: everything a table decides before it draws.
+//
+// Pure, and deliberately so — the way `../tree/rows.ts` is. Which rows are
+// shown in what order, what a cell's raw value is, how two rows compare, and
+// how many pixels each column gets are all answerable with no display, and
+// they are where the subtle table bugs live. The component only draws the
+// answer, and the tests assert on the answer directly.
+
+import type { ReactNode } from 'react';
+
+/** What a row is keyed by. Numbers are allowed because a row often comes
+ *  from a database, and stringifying an id is a chance to lose one. */
+export type TableRowId = string | number;
+
+/** One row of the current view: the app's row object, its resolved id, and
+ *  its position **in sorted order** — the order everything else counts in. */
+export interface TableRow<Row> {
+  id: TableRowId;
+  row: Row;
+  index: number;
+}
+
+/** A row, plus what only the render knows about it. */
+export interface TableRowState<Row> extends TableRow<Row> {
+  selected: boolean;
+  /**
+   * The ink the row is painted in. Handed over by name because **colour does
+   * not cascade into a drawing**: an `<Icon>` or a `<canvas mono>` takes its
+   * colour from its own style, so a glyph inside a cell on the selected row
+   * has to be told. The `<text>` in a default cell needs nothing — text
+   * inherits.
+   */
+  color: string;
+}
+
+/** What `column.render` and `styles.cell` are told. `selected` and `column`
+ *  are the two fields core's `<Table>` passed, kept under the same names. */
+export interface TableCellState<Row> extends TableRowState<Row> {
+  column: TableColumn<Row>;
+}
+
+/** The sort descriptor. Core's shape, verbatim: `column` names a column id.
+ *  `null` is "unsorted" — reachable through the controlled prop; the header
+ *  click cycle is asc ↔ desc and never emits it. */
+export interface TableSort {
+  column: string;
+  direction: 'asc' | 'desc';
+}
+
+/** What `column.renderHeader` and `styles.headerCell` are told. */
+export interface TableHeaderCellState<Row> {
+  column: TableColumn<Row>;
+  /** The table's current sort — this column's when `sort.column` matches. */
+  sort: TableSort | null;
+  /** The width the column resolved to this layout, in pixels. */
+  resolvedWidth: number;
+}
+
+/**
+ * One column. `id`, `label`, `width`, `align`, `value` and `render` are
+ * core's `TableColumn`, kept compatible; the rest is this component's.
+ *
+ * Sizing: `flex` makes the column share the viewport width left over after
+ * the fixed columns; `width` alone makes it fixed. **A column declaring
+ * neither is `flex: 1` with a 120px floor** — so a table with no sizing
+ * config fills its box instead of parking dead space beside fixed-120
+ * columns. A user resize converts the column to fixed at the dragged width.
+ */
+export interface TableColumn<Row = any> {
+  id: string;
+  /** The header caption. Defaults to the id. */
+  label?: string;
+  /** Fixed width, in pixels. Ignored when `flex` is set. */
+  width?: number;
+  /** Share of the leftover viewport width, by weight. */
+  flex?: number;
+  /** The narrowest the column may go — flex resolution and user resize both
+   *  respect it. Defaults to 40 (core's resize floor); 120 for a column with
+   *  neither `width` nor `flex`. */
+  minWidth?: number;
+  /** Logical, so bidi is the layout's problem and never the app's: `'end'`
+   *  is the edge the row finishes at — where a column of figures lines up —
+   *  and under RTL that is the left edge without anyone saying so. Core
+   *  said `'left' | 'right'`; the successor says what it always meant. */
+  align?: 'start' | 'center' | 'end';
+  /** Whether the header click sorts on this column. Default true. */
+  sortable?: boolean;
+  /** The cell's raw value: feeds the default cell text **and** the sort.
+   *  Defaults to `row[id]`. */
+  value?: (row: Row) => unknown;
+  /** The sort order, given the whole rows. Defaults to a natural comparison
+   *  over `value()` — numbers numerically, everything else as text. */
+  compare?: (a: Row, b: Row) => number;
+  /** The cell, replaced entirely. The state says whether the cell is on the
+   *  selected row — that row is a filled bar, and a colour picked against
+   *  the resting background is unreadable on it. */
+  render?: (row: Row, state: TableCellState<Row>) => ReactNode;
+  /** The header cell's content — the caption and the sort mark's place. The
+   *  header *box* stays the table's: it carries the width, the sort click
+   *  and the resize grip beside it. */
+  renderHeader?: (state: TableHeaderCellState<Row>) => ReactNode;
+}
+
+/** A cell's raw value: `column.value`, or the property named by the id. */
+export function columnValue<Row>(row: Row, column: TableColumn<Row>): unknown {
+  return column.value
+    ? column.value(row)
+    : (row as Record<string, unknown>)[column.id];
+}
+
+/** Core's comparator, verbatim: numbers numerically, everything else as
+ *  text, with `null`/`undefined` sorting as the empty string. */
+export function defaultCompare(a: unknown, b: unknown): number {
+  if (typeof a === 'number' && typeof b === 'number') return a - b;
+  return String(a ?? '').localeCompare(String(b ?? ''));
+}
+
+/**
+ * The id accessor with its default filled in — and its failure made loud.
+ *
+ * A row without an id cannot be selected, keyed, or measured, and rendering
+ * it anyway fails somewhere far away (a React key warning, a selection that
+ * silently never matches). The remedial throw here is the Calendar's
+ * precedent: name the fix, not just the fault.
+ */
+export function resolveGetId<Row>(
+  getId: ((row: Row) => TableRowId) | undefined,
+): (row: Row, index: number) => TableRowId {
+  return (row: Row, index: number): TableRowId => {
+    const id = getId
+      ? getId(row)
+      : ((row as { id?: TableRowId }).id as TableRowId);
+    if (id === undefined || id === null) {
+      throw new TypeError(
+        `<Table> row ${index} has no id — every row needs one. ` +
+          'Give rows an `id` field, or pass `getId` to read your own key.',
+      );
+    }
+    return id;
+  };
+}
+
+/**
+ * The rows in display order: ids resolved, sort applied.
+ *
+ * `sort` and *applying* the sort are separate on purpose (see the PRD's
+ * "Sort ownership, split in two"): pass `presorted` when the rows already
+ * arrive in display order — a server sorted them — and the descriptor only
+ * drives the header indicator. The sort is stable, so rows that compare
+ * equal keep the order the app gave them.
+ */
+export function orderRows<Row>(
+  rows: readonly Row[],
+  columns: readonly TableColumn<Row>[],
+  getId: (row: Row, index: number) => TableRowId,
+  sort: TableSort | null,
+  presorted: boolean,
+): TableRow<Row>[] {
+  const entries = rows.map((row, index) => ({
+    id: getId(row, index),
+    row,
+    index,
+  }));
+  const column =
+    sort && !presorted ? columns.find((c) => c.id === sort.column) : undefined;
+  if (sort && column) {
+    const sign = sort.direction === 'desc' ? -1 : 1;
+    const compare =
+      column.compare ??
+      ((a: Row, b: Row) =>
+        defaultCompare(columnValue(a, column), columnValue(b, column)));
+    entries.sort((a, b) => sign * compare(a.row, b.row));
+    entries.forEach((entry, index) => {
+      entry.index = index;
+    });
+  }
+  return entries;
+}
+
+/** Core's resize floor, and the sized-column default for `minWidth`. */
+export const MIN_COLUMN = 40;
+/** What a column with neither `width` nor `flex` will not shrink below —
+ *  core's fixed default, carried forward as a floor. */
+export const UNSIZED_MIN = 120;
+
+/** The pixels every column resolved to, in column order, plus their sum —
+ *  the content width, and what the header row is sized to. */
+export interface ResolvedWidths {
+  widths: number[];
+  total: number;
+}
+
+/**
+ * Columns resolve to pixels **once, at the table level** — the one problem
+ * no browser table library has, because HTML's table layout algorithm does
+ * not exist here, and per-row flex must not decide column widths (each row
+ * would negotiate its own grid).
+ *
+ * Fixed columns take their width; a user resize overrides anything; flex
+ * columns share `max(0, viewport − Σfixed)` by weight, floored at their
+ * `minWidth`. When nothing fits — the viewport is smaller than the floors —
+ * every flex column sits at its floor and the body scrolls horizontally.
+ * Before the first layout the viewport is 0, which lands in the same branch.
+ */
+export function resolveWidths<Row>(
+  columns: readonly TableColumn<Row>[],
+  user: Readonly<Record<string, number>>,
+  viewport: number,
+): ResolvedWidths {
+  const widths = new Array<number>(columns.length).fill(0);
+  interface FlexEntry {
+    at: number;
+    weight: number;
+    min: number;
+  }
+  let flex: FlexEntry[] = [];
+  let fixedSum = 0;
+  columns.forEach((column, at) => {
+    const resized = user[column.id];
+    if (resized !== undefined) {
+      widths[at] = resized;
+      fixedSum += resized;
+      return;
+    }
+    if (column.flex === undefined && column.width !== undefined) {
+      widths[at] = column.width;
+      fixedSum += column.width;
+      return;
+    }
+    const unsized = column.flex === undefined && column.width === undefined;
+    flex.push({
+      at,
+      weight: column.flex ?? 1,
+      min: column.minWidth ?? (unsized ? UNSIZED_MIN : MIN_COLUMN),
+    });
+  });
+
+  if (flex.length) {
+    let pool = Math.max(0, viewport - fixedSum);
+    // Distribute, clamping to floors: a column whose share lands under its
+    // floor takes the floor and leaves the pool, and the rest re-share what
+    // is left. Terminates because every pass either clamps someone or
+    // distributes and stops.
+    for (;;) {
+      const minSum = flex.reduce((sum, f) => sum + f.min, 0);
+      if (pool <= minSum) {
+        for (const f of flex) widths[f.at] = f.min;
+        break;
+      }
+      const weightSum = flex.reduce((sum, f) => sum + f.weight, 0);
+      const clamped = flex.filter((f) => (pool * f.weight) / weightSum < f.min);
+      if (!clamped.length) {
+        // Cumulative rounding, so the integer widths sum to the pool exactly
+        // and the table's edge meets the viewport's rather than drifting a
+        // pixel per column.
+        let acc = 0;
+        let assigned = 0;
+        for (const f of flex) {
+          acc += (pool * f.weight) / weightSum;
+          const w = Math.round(acc) - assigned;
+          assigned += w;
+          widths[f.at] = w;
+        }
+        break;
+      }
+      for (const f of clamped) {
+        widths[f.at] = f.min;
+        pool -= f.min;
+      }
+      flex = flex.filter((f) => !clamped.includes(f));
+    }
+  }
+
+  return { widths, total: widths.reduce((sum, w) => sum + w, 0) };
+}

package/src/terminal/backends.ts

@@ -0,0 +1,242 @@
+// One table, three terminals, and the reason `<Terminal>` has a nice API at
+// all.
+//
+// Every terminal emulator that can be embedded takes the same three things —
+// a window to draw into, a font, a colour scheme — and spells all three
+// differently. xterm wants X resources, urxvt wants an Xft font string,
+// alacritty wants TOML on the command line. That asymmetry is the *only*
+// difference between the backends, so it lives here and the component never
+// mentions a binary by name.
+//
+// Pure functions over a plain description: no spawning, no probing, nothing
+// async. `test/terminal.test.ts` asserts the argv of all three without a
+// terminal installed anywhere, which is the point.
+
+/**
+ * Which terminal to use.
+ *
+ * The first three are emulators this package *embeds* — a real xterm, urxvt
+ * or alacritty drawing into a `<foreign>`. `'vt'` is the one it *is*: a pty
+ * and a pure-JS emulator core rendered as a native element, which needs no
+ * program installed and is the only backend `write()` can work on.
+ *
+ * `'auto'` takes the first embeddable emulator that is installed and falls
+ * back to `'vt'`. That order — rather than vt first — is deliberate: an
+ * external emulator is battle-tested, and a user who installed one expressed
+ * a preference. Moving vt to the front is a later, deliberate decision.
+ */
+export type TerminalBackendName =
+  'auto' | 'xterm' | 'urxvt' | 'alacritty' | 'vt';
+
+/**
+ * The colours a terminal is asked to use.
+ *
+ * `<Terminal>` fills these from the react-x11 theme by default, which is what
+ * makes an embedded terminal look like part of the app rather than a hole
+ * punched in it.
+ */
+export interface TerminalColors {
+  background?: string;
+  foreground?: string;
+  /** The block/bar the terminal draws at the caret. */
+  cursor?: string;
+  /**
+   * ANSI 0–15, in the usual order (black, red, green, yellow, blue, magenta,
+   * cyan, white, then the eight bright ones). A shorter array sets what it
+   * has. Not every backend can take these from the command line — see
+   * `palette` on the backend.
+   */
+  palette?: readonly string[];
+}
+
+/** Everything the argv builders read. */
+export interface TerminalLaunch {
+  /** The `<foreign>` container to draw into. */
+  windowId: number;
+  /** argv of the program to run. Empty means the user's shell. */
+  command?: readonly string[];
+  title?: string;
+  fontFamily?: string;
+  fontSize?: number;
+  /** Lines of scrollback. */
+  scrollback?: number;
+  colors?: TerminalColors;
+}
+
+export interface TerminalBackend {
+  name: Exclude<TerminalBackendName, 'auto'>;
+  /** Binaries to look for, in order. */
+  binaries: readonly string[];
+  /** Whether `colors.palette` reaches this backend from the command line. */
+  palette: boolean;
+  args(launch: TerminalLaunch): string[];
+}
+
+/** The ANSI names alacritty's TOML uses, in palette-index order. */
+const ANSI_NAMES = [
+  'black',
+  'red',
+  'green',
+  'yellow',
+  'blue',
+  'magenta',
+  'cyan',
+  'white',
+] as const;
+
+const DEFAULT_FAMILY = 'monospace';
+const DEFAULT_SIZE = 12;
+
+/**
+ * xterm.
+ *
+ * `-into` is the oldest and most reliable of the three embed flags — it
+ * predates XEmbed and does plain reparenting, which is exactly what
+ * `<foreign>`'s adopt path handles. `-b 0` drops the inner border, because a
+ * pane in an application should not have a margin the application did not ask
+ * for.
+ *
+ * Everything xterm cannot say as a flag it says as an X resource, which is
+ * how the ANSI palette gets set: `-xrm 'XTerm*color4: #…'` is a per-invocation
+ * resource and does not touch the user's database.
+ */
+export const xterm: TerminalBackend = {
+  name: 'xterm',
+  binaries: ['xterm'],
+  palette: true,
+  args(launch) {
+    const args = ['-into', String(launch.windowId), '-b', '0'];
+    if (launch.title) args.push('-T', launch.title);
+
+    // `-fa` is what switches xterm to Xft at all; without it `-fs` is ignored
+    // and the bitmap font stays. So asking for either means passing both.
+    if (launch.fontFamily || launch.fontSize) {
+      args.push('-fa', launch.fontFamily ?? DEFAULT_FAMILY);
+      args.push('-fs', String(launch.fontSize ?? DEFAULT_SIZE));
+    }
+    if (launch.scrollback != null) args.push('-sl', String(launch.scrollback));
+
+    const colors = launch.colors ?? {};
+    if (colors.background) args.push('-bg', colors.background);
+    if (colors.foreground) args.push('-fg', colors.foreground);
+    if (colors.cursor) args.push('-cr', colors.cursor);
+    for (const [index, color] of (colors.palette ?? []).entries()) {
+      if (index > 15 || !color) continue;
+      args.push('-xrm', `XTerm*color${index}: ${color}`);
+    }
+
+    // `-e` consumes the rest of the line, so it is last and nothing may be
+    // appended after this point.
+    if (launch.command?.length) args.push('-e', ...launch.command);
+    return args;
+  },
+};
+
+/**
+ * rxvt-unicode.
+ *
+ * `-embed` rather than `-into`, and a single Xft font string rather than a
+ * family and a size. The ANSI palette is reachable only through the X
+ * resource database, which is the user's and not ours to write, so
+ * `palette: false` — `<Terminal>` still themes the background, foreground and
+ * cursor, which is most of what makes it look integrated.
+ */
+export const urxvt: TerminalBackend = {
+  name: 'urxvt',
+  binaries: ['urxvt', 'rxvt-unicode'],
+  palette: false,
+  args(launch) {
+    const args = ['-embed', String(launch.windowId)];
+    if (launch.title) args.push('-title', launch.title);
+    if (launch.fontFamily || launch.fontSize) {
+      const family = launch.fontFamily ?? DEFAULT_FAMILY;
+      const size = launch.fontSize ?? DEFAULT_SIZE;
+      args.push('-fn', `xft:${family}:size=${size}`);
+    }
+    if (launch.scrollback != null) args.push('-sl', String(launch.scrollback));
+
+    const colors = launch.colors ?? {};
+    if (colors.background) args.push('-bg', colors.background);
+    if (colors.foreground) args.push('-fg', colors.foreground);
+    if (colors.cursor) args.push('-cr', colors.cursor);
+
+    if (launch.command?.length) args.push('-e', ...launch.command);
+    return args;
+  },
+};
+
+/**
+ * alacritty.
+ *
+ * Configuration is a file, and `-o` is the escape hatch: one TOML assignment
+ * per flag, applied over whatever the user's own config says. TOML means
+ * strings are quoted *inside the argument value* — `font.normal.family="Fira
+ * Code"` — which costs nothing here because each `-o` is its own argv element
+ * and no shell ever sees it.
+ */
+export const alacritty: TerminalBackend = {
+  name: 'alacritty',
+  binaries: ['alacritty'],
+  palette: true,
+  args(launch) {
+    const args = ['--embed', String(launch.windowId)];
+    if (launch.title) args.push('--title', launch.title);
+
+    const set = (key: string, value: string): void => {
+      args.push('-o', `${key}=${value}`);
+    };
+    if (launch.fontFamily) set('font.normal.family', quote(launch.fontFamily));
+    if (launch.fontSize != null) set('font.size', String(launch.fontSize));
+    if (launch.scrollback != null) {
+      set('scrolling.history', String(launch.scrollback));
+    }
+
+    const colors = launch.colors ?? {};
+    if (colors.background)
+      set('colors.primary.background', quote(colors.background));
+    if (colors.foreground)
+      set('colors.primary.foreground', quote(colors.foreground));
+    if (colors.cursor) set('colors.cursor.cursor', quote(colors.cursor));
+    for (const [index, color] of (colors.palette ?? []).entries()) {
+      if (index > 15 || !color) continue;
+      const group = index < 8 ? 'normal' : 'bright';
+      set(`colors.${group}.${ANSI_NAMES[index % 8]}`, quote(color));
+    }
+
+    if (launch.command?.length) args.push('-e', ...launch.command);
+    return args;
+  },
+};
+
+/** A TOML string. Colours and font names have no quotes or backslashes in
+ *  practice, but a family typed by a user is a user's string. */
+function quote(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Auto-detection order, and it is deliberately not "nicest first".
+ *
+ * xterm's `-into` is the embed path with the fewest surprises and is on
+ * almost every machine that has X at all; alacritty's `--embed` is newer and
+ * its window is a winit window with its own ideas about focus. An app that
+ * prefers a different one says so — `backend="alacritty"` is one prop.
+ */
+export const TERMINAL_BACKENDS: readonly TerminalBackend[] = [
+  xterm,
+  urxvt,
+  alacritty,
+];
+
+/**
+ * The *embeddable* backends a `backend` prop selects. `'auto'` is all of
+ * them, in order; `'vt'` is none of them, because nothing is spawned — the
+ * component takes that branch before it ever asks this.
+ */
+export function backendsFor(
+  name: TerminalBackendName,
+): readonly TerminalBackend[] {
+  if (name === 'auto') return TERMINAL_BACKENDS;
+  const found = TERMINAL_BACKENDS.filter((b) => b.name === name);
+  return found;
+}

package/src/terminal/hx.ts

@@ -0,0 +1,51 @@
+// `React.createElement`, typed against react-x11's host elements.
+//
+// The library writes `h(...)` rather than JSX — a convention inherited from
+// core, and worth keeping so moving code between the two repos stays a
+// rename. But `React.createElement`'s own overloads are `@types/react`'s, and
+// they describe the DOM: a `<box onKeyDown>` handler is checked against
+// React's `KeyboardEvent`, not react-x11's, and the whole props object is
+// measured against `DOMAttributes`. Everything interesting fails.
+//
+// So the element name is looked up in react-x11's own element table instead.
+// `hx('box', …)` gets `<box>`'s real props — `ev.keysym` on a key handler,
+// `onDraw` on a `<canvas>` — and `hx('div', …)` is an error, which is the
+// same guarantee the JSX namespace gives `examples/` and `test/types/`.
+import React from 'react';
+import type { Key, ReactElement, ReactNode } from 'react';
+import type { ReactX11Elements, Theme } from 'react-x11';
+
+/** The host elements, by name. */
+export type Host = ReactX11Elements;
+
+/**
+ * What every element takes on top of its own props.
+ *
+ * `theme` is honoured by **every** node — `Node.theme` merges `props.theme`
+ * over the inherited palette, whatever the kind — but react-x11's element
+ * declarations only put it on `<window>`. A widget re-declares the theme it
+ * read from context onto its own root so that `$token` values still resolve
+ * inside a `<popup>`, which is a separate window and does not inherit the
+ * trigger's node tree. So the prop is real; only the declaration is narrow.
+ */
+interface CommonProps {
+  key?: Key;
+  /** `Theme` is listed alongside the record because it is an interface, and
+   *  an interface has no implicit index signature — so the palette `useTheme`
+   *  hands back is not assignable to the record react-x11 declares. */
+  theme?: Theme | Record<string, string | number>;
+}
+
+export function hx<K extends keyof Host>(
+  type: K,
+  // `theme` is dropped from the element's own props before the merge:
+  // `<window>` and `<popup>` already declare it, narrower, and intersecting
+  // the two would demand a value satisfying both.
+  props?: (Omit<Host[K], 'theme'> & CommonProps) | null,
+  ...children: ReactNode[]
+): ReactElement {
+  // The cast is the whole point of the wrapper: `createElement`'s string
+  // overload insists on DOM props, and the signature above has already
+  // checked these against the element that will actually receive them.
+  return React.createElement(type as string, props as never, ...children);
+}