@react-x11/components 0.1.0 → 0.2.0

package/src/markdown/spans.ts

@@ -0,0 +1,143 @@
+// Inline AST → the styled runs `<richtext>` renders. Pure: all the colour
+// and font decisions arrive in `InlineStyles`, which `index.ts` derives
+// from the theme once per render.
+import type { InlineNode } from './ast.js';
+import type { TextRun } from '../richtext/node.js';
+
+/** The resolved look of inline text, for one block. */
+export interface InlineStyles {
+  family: string;
+  monoFamily: string;
+  size: number;
+  weight?: number | 'normal' | 'bold';
+  style?: 'normal' | 'italic';
+  color: string;
+  linkColor: string;
+  codeColor: string;
+  codeBg: string;
+}
+
+interface WalkState {
+  bold: boolean;
+  italic: boolean;
+  code: boolean;
+  del: boolean;
+  href: string | null | undefined; // undefined: not in a link
+}
+
+/** Flatten an inline tree to runs. Nested emphasis composes; a code span
+ *  inside a link keeps the chip and gains the underline, like HTML. */
+export function runsOf(nodes: InlineNode[], s: InlineStyles): TextRun[] {
+  const out: TextRun[] = [];
+  walk(
+    nodes,
+    s,
+    { bold: false, italic: false, code: false, del: false, href: undefined },
+    out,
+  );
+  return out;
+}
+
+function walk(
+  nodes: InlineNode[],
+  s: InlineStyles,
+  st: WalkState,
+  out: TextRun[],
+): void {
+  for (const node of nodes) {
+    switch (node.type) {
+      case 'text':
+        pushRun(node.text, s, st, out);
+        break;
+      case 'code':
+        walk(
+          [{ type: 'text', text: node.text }],
+          s,
+          { ...st, code: true },
+          out,
+        );
+        break;
+      case 'strong':
+        walk(node.children, s, { ...st, bold: true }, out);
+        break;
+      case 'em':
+        walk(node.children, s, { ...st, italic: true }, out);
+        break;
+      case 'del':
+        walk(node.children, s, { ...st, del: true }, out);
+        break;
+      case 'link':
+        walk(node.children, s, { ...st, href: node.href }, out);
+        break;
+      case 'break':
+        pushRun('\n', s, st, out);
+        break;
+      case 'component':
+        // reserved for MDX; until a renderer maps the name, its children
+        // are ordinary content rather than a hole in the document
+        walk(node.children, s, st, out);
+        break;
+    }
+  }
+}
+
+function pushRun(
+  text: string,
+  s: InlineStyles,
+  st: WalkState,
+  out: TextRun[],
+): void {
+  if (text.length === 0) return;
+  const inLink = st.href !== undefined;
+  const color = st.code ? s.codeColor : inLink ? s.linkColor : s.color;
+  const run: TextRun = {
+    text,
+    family: st.code ? s.monoFamily : s.family,
+    size: st.code ? Math.round(s.size * 0.9) : s.size,
+    weight: st.bold ? 700 : s.weight,
+    style: st.italic ? 'italic' : s.style,
+    color,
+  };
+  if (st.code) run.bg = s.codeBg;
+  if (inLink) {
+    run.underline = s.linkColor;
+    run.href = st.href ?? null;
+  }
+  if (st.del) run.strike = color;
+  const prev = out[out.length - 1];
+  if (prev && sameStyle(prev, run)) prev.text += text;
+  else out.push(run);
+}
+
+function sameStyle(a: TextRun, b: TextRun): boolean {
+  return (
+    a.family === b.family &&
+    a.size === b.size &&
+    a.weight === b.weight &&
+    a.style === b.style &&
+    a.color === b.color &&
+    a.bg === b.bg &&
+    a.underline === b.underline &&
+    a.strike === b.strike &&
+    a.href === b.href
+  );
+}
+
+/** The plain text of an inline tree — table column sizing wants it. */
+export function plainTextOf(nodes: InlineNode[]): string {
+  let out = '';
+  for (const node of nodes) {
+    switch (node.type) {
+      case 'text':
+      case 'code':
+        out += node.text;
+        break;
+      case 'break':
+        out += '\n';
+        break;
+      default:
+        out += plainTextOf(node.children);
+    }
+  }
+  return out;
+}

package/src/media-player/backends.ts

@@ -0,0 +1,155 @@
+// Two players, one table — the media-player half of what `../terminal/
+// backends.ts` does for emulators.
+//
+// A backend is an argv builder plus a way to open its control channel. Both
+// halves belong together because they agree on one thing the component never
+// sees: the socket path is passed on the command line and connected to
+// afterwards, and the flag that names it is different in each player.
+//
+// The argv builders are pure and synchronous, so `test/media-player.test.ts`
+// asserts every flag without mpv or VLC installed anywhere.
+import type { ProcessHost } from '../embed/index.js';
+import type { PlayerControl, PlayerEvents } from './control.js';
+import { connectMpv } from './mpv.js';
+import { connectVlc } from './vlc.js';
+
+/** Which player to embed. `'auto'` takes the first one installed. */
+export type MediaBackendName = 'auto' | 'mpv' | 'vlc';
+
+/** Everything the argv builders read. */
+export interface MediaLaunch {
+  /** The `<foreign>` container to draw into. */
+  windowId: number;
+  /** A path or a URL. Omitted starts the player idle. */
+  src?: string;
+  /** Where the player should create its control socket. */
+  controlPath: string;
+  autoPlay?: boolean;
+  /** 0–1. */
+  volume?: number;
+  muted?: boolean;
+  /** `'16:9'`, `'4:3'` — the player letterboxes inside the element's rect. */
+  aspectRatio?: string;
+  loop?: boolean;
+  /** The player's *own* on-screen controls. Off by default: they are the one
+   *  part of the surface that will not match the app around it. */
+  osd?: boolean;
+  /** Appended verbatim, before the source. The escape hatch for the long
+   *  tail of player options this package will never wrap. */
+  extraArgs?: readonly string[];
+}
+
+export interface MediaBackend {
+  name: Exclude<MediaBackendName, 'auto'>;
+  binaries: readonly string[];
+  /** Whether `onProgress` can fire under this backend. */
+  reportsProgress: boolean;
+  args(launch: MediaLaunch): string[];
+  connect(
+    host: ProcessHost,
+    controlPath: string,
+    events: PlayerEvents,
+    launch: MediaLaunch,
+  ): Promise<PlayerControl>;
+}
+
+/**
+ * mpv.
+ *
+ * `--wid` is plain reparenting — mpv sets no `_XEMBED_INFO` — which is
+ * exactly the case `<foreign>`'s adopt path handles. `--idle=yes` keeps the
+ * process alive with nothing loaded, so a player with no `src` yet is still a
+ * window that can be given one later, and `--no-terminal` keeps it off a
+ * stdio it was never given.
+ */
+export const mpv: MediaBackend = {
+  name: 'mpv',
+  binaries: ['mpv'],
+  reportsProgress: true,
+  args(launch) {
+    const args = [
+      `--wid=${launch.windowId}`,
+      `--input-ipc-server=${launch.controlPath}`,
+      '--idle=yes',
+      '--no-terminal',
+    ];
+    // The on-screen controller is mpv's own chrome. Off unless asked for,
+    // because it is drawn by mpv and cannot follow the app's theme.
+    args.push(launch.osd ? '--osc=yes' : '--no-osc');
+    if (launch.autoPlay === false) args.push('--pause=yes');
+    if (launch.volume != null) {
+      args.push(`--volume=${Math.round(clampUnit(launch.volume) * 100)}`);
+    }
+    if (launch.muted) args.push('--mute=yes');
+    if (launch.aspectRatio) {
+      args.push(`--video-aspect-override=${launch.aspectRatio}`);
+    }
+    if (launch.loop) args.push('--loop-file=inf');
+    if (launch.extraArgs?.length) args.push(...launch.extraArgs);
+    // `--` so a file called `--version` is a file.
+    if (launch.src) args.push('--', launch.src);
+    return args;
+  },
+  connect(host, controlPath, events) {
+    return connectMpv(host, controlPath, events);
+  },
+};
+
+/**
+ * VLC.
+ *
+ * `--drawable-xid` is the X11 video output's embed option. `--intf dummy`
+ * suppresses the full interface — the video output still creates its window,
+ * which is the one being embedded — and `--extraintf rc` adds the control
+ * socket. See `./vlc.ts` for why that socket is written to and not read.
+ */
+export const vlc: MediaBackend = {
+  name: 'vlc',
+  binaries: ['vlc'],
+  reportsProgress: false,
+  args(launch) {
+    const args = [
+      `--drawable-xid=${launch.windowId}`,
+      '--intf',
+      'dummy',
+      '--extraintf',
+      'rc',
+      `--rc-unix=${launch.controlPath}`,
+      '--no-video-title-show',
+    ];
+    if (!launch.osd) args.push('--no-osd');
+    if (launch.autoPlay === false) args.push('--start-paused');
+    if (launch.aspectRatio) args.push(`--aspect-ratio=${launch.aspectRatio}`);
+    if (launch.loop) args.push('--loop');
+    if (launch.extraArgs?.length) args.push(...launch.extraArgs);
+    if (launch.src) args.push('--', launch.src);
+    return args;
+  },
+  connect(host, controlPath, events, launch) {
+    return connectVlc(host, controlPath, events, {
+      paused: launch.autoPlay === false,
+    });
+  },
+};
+
+function clampUnit(value: number): number {
+  if (!Number.isFinite(value)) return 1;
+  return Math.min(1, Math.max(0, value));
+}
+
+/**
+ * Auto-detection order.
+ *
+ * mpv first, and not only because it is lighter: it is the one whose control
+ * channel reports position back, so `onProgress` works on a machine that has
+ * both. An app that would rather have VLC says `backend="vlc"`.
+ */
+export const MEDIA_BACKENDS: readonly MediaBackend[] = [mpv, vlc];
+
+/** The backends a `backend` prop selects. `'auto'` is all of them, in order. */
+export function mediaBackendsFor(
+  name: MediaBackendName,
+): readonly MediaBackend[] {
+  if (name === 'auto') return MEDIA_BACKENDS;
+  return MEDIA_BACKENDS.filter((b) => b.name === name);
+}

package/src/media-player/control.ts

@@ -0,0 +1,70 @@
+// What a media player can be told, and what it can say back.
+//
+// Two backends implement this and they are not equals, which is the honest
+// shape of the problem rather than a gap to paper over: mpv has a JSON IPC
+// socket that reports properties as they change, so `onProgress` is real
+// events; VLC's rc interface is a line-oriented console whose replies are
+// unlabelled text, so this package writes to it and does not parse it —
+// play/pause/seek/volume work, position does not. `reportsProgress` is how a
+// caller finds that out without knowing which binary was picked.
+
+/** What the player tells the component. */
+export interface PlayerEvents {
+  onProgress?: (info: { position: number; duration: number }) => void;
+  onPlayingChange?: (playing: boolean) => void;
+  onEnded?: () => void;
+  /** The control channel failed. The video may well still be playing. */
+  onError?: (err: Error) => void;
+}
+
+/** What the component tells the player. */
+export interface PlayerControl {
+  /** Replace what is playing, without restarting the process. */
+  load(src: string): void;
+  setPaused(paused: boolean): void;
+  /** Absolute position, in seconds. */
+  seek(seconds: number): void;
+  /** 0–1. Scaled to whatever the backend's own range is. */
+  setVolume(volume: number): void;
+  setMuted(muted: boolean): void;
+  stop(): void;
+  /** Whether `onProgress` will ever fire. False for VLC — see the file
+   *  comment. */
+  readonly reportsProgress: boolean;
+  dispose(): void;
+}
+
+/**
+ * `chunk => lines`, keeping the partial one.
+ *
+ * Both control protocols are newline-delimited and both arrive over a stream
+ * socket, so a message can be split across two reads and two messages can
+ * arrive in one. Shared rather than written twice because getting this wrong
+ * shows up as an occasional dropped event, which is the hardest kind of bug to
+ * see in a progress bar.
+ */
+export function lineReader(
+  onLine: (line: string) => void,
+): (chunk: string) => void {
+  let buffer = '';
+  return (chunk: string) => {
+    buffer += chunk;
+    let index = buffer.indexOf('\n');
+    while (index !== -1) {
+      const line = buffer.slice(0, index).replace(/\r$/, '');
+      buffer = buffer.slice(index + 1);
+      if (line) onLine(line);
+      index = buffer.indexOf('\n');
+    }
+    // A runaway peer must not become a runaway allocation: nothing either
+    // protocol sends is anywhere near this long, so a buffer this size means
+    // the stream is not what we think it is.
+    if (buffer.length > 1_000_000) buffer = '';
+  };
+}
+
+/** Clamp to 0–1 and reject the values a slider bound to bad state produces. */
+export function unitRange(value: number): number {
+  if (!Number.isFinite(value)) return 1;
+  return Math.min(1, Math.max(0, value));
+}

package/src/media-player/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);
+}