@react-x11/components 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@react-x11/components",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Components for react-x11 that do not belong in the core package",
   "keywords": [
     "react",
@@ -22,45 +22,199 @@
     "node": ">=20.19"
   },
   "files": [
+    "dist",
     "src"
   ],
   "sideEffects": false,
-  "types": "./src/index.d.ts",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./src/index.d.ts",
-      "default": "./src/index.js"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
-    "./sparkline": {
-      "types": "./src/sparkline/index.d.ts",
-      "default": "./src/sparkline/index.js"
+    "./ansi": {
+      "types": "./dist/ansi/index.d.ts",
+      "default": "./dist/ansi/index.js"
+    },
+    "./calendar": {
+      "types": "./dist/calendar/index.d.ts",
+      "default": "./dist/calendar/index.js"
+    },
+    "./charts": {
+      "types": "./dist/charts/index.d.ts",
+      "default": "./dist/charts/index.js"
+    },
+    "./code": {
+      "types": "./dist/code/index.d.ts",
+      "default": "./dist/code/index.js"
+    },
+    "./code-editor": {
+      "types": "./dist/code-editor/index.d.ts",
+      "default": "./dist/code-editor/index.js"
+    },
+    "./code-language": {
+      "types": "./dist/code-language/index.d.ts",
+      "default": "./dist/code-language/index.js"
+    },
+    "./codeblock": {
+      "types": "./dist/codeblock/index.d.ts",
+      "default": "./dist/codeblock/index.js"
+    },
+    "./color-picker": {
+      "types": "./dist/color-picker/index.d.ts",
+      "default": "./dist/color-picker/index.js"
+    },
+    "./desktop-calendar": {
+      "types": "./dist/desktop-calendar/index.d.ts",
+      "default": "./dist/desktop-calendar/index.js"
+    },
+    "./embed": {
+      "types": "./dist/embed/index.d.ts",
+      "default": "./dist/embed/index.js"
+    },
+    "./flow": {
+      "types": "./dist/flow/index.d.ts",
+      "default": "./dist/flow/index.js"
+    },
+    "./formula": {
+      "types": "./dist/formula/index.d.ts",
+      "default": "./dist/formula/index.js"
+    },
+    "./html": {
+      "types": "./dist/html/index.d.ts",
+      "default": "./dist/html/index.js"
+    },
+    "./markdown": {
+      "types": "./dist/markdown/index.d.ts",
+      "default": "./dist/markdown/index.js"
+    },
+    "./media-player": {
+      "types": "./dist/media-player/index.d.ts",
+      "default": "./dist/media-player/index.js"
+    },
+    "./richtext": {
+      "types": "./dist/richtext/index.d.ts",
+      "default": "./dist/richtext/index.js"
+    },
+    "./table": {
+      "types": "./dist/table/index.d.ts",
+      "default": "./dist/table/index.js"
+    },
+    "./terminal": {
+      "types": "./dist/terminal/index.d.ts",
+      "default": "./dist/terminal/index.js"
+    },
+    "./terminal-output": {
+      "types": "./dist/terminal-output/index.d.ts",
+      "default": "./dist/terminal-output/index.js"
+    },
+    "./three": {
+      "types": "./dist/three/index.d.ts",
+      "default": "./dist/three/index.js"
+    },
+    "./three/jsx-runtime": {
+      "types": "./dist/three/jsx-runtime.d.ts",
+      "default": "./dist/three/jsx-runtime.js"
+    },
+    "./three/jsx-dev-runtime": {
+      "types": "./dist/three/jsx-dev-runtime.d.ts",
+      "default": "./dist/three/jsx-dev-runtime.js"
+    },
+    "./timeline": {
+      "types": "./dist/timeline/index.d.ts",
+      "default": "./dist/timeline/index.js"
+    },
+    "./tray-host": {
+      "types": "./dist/tray-host/index.d.ts",
+      "default": "./dist/tray-host/index.js"
+    },
+    "./tree": {
+      "types": "./dist/tree/index.d.ts",
+      "default": "./dist/tree/index.js"
     },
     "./package.json": "./package.json"
   },
   "scripts": {
-    "test": "node --test",
+    "prebuild": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "pretest": "npm run build",
+    "test": "tsx --test test/*.test.ts",
+    "pretypecheck": "npm run build",
     "typecheck": "tsc -p tsconfig.json",
     "lint": "eslint .",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "check:package": "node scripts/check-package.mjs",
-    "examples:sparkline": "tsx examples/sparkline.jsx"
+    "check:package": "tsx scripts/check-package.ts",
+    "docs": "npm --prefix website start",
+    "docs:build": "npm --prefix website run build",
+    "examples:calendar": "tsx examples/calendar.tsx",
+    "examples:charts": "tsx examples/charts.tsx",
+    "examples:code": "tsx examples/code.tsx",
+    "examples:color-picker": "tsx examples/color-picker.tsx",
+    "examples:code-editor": "tsx examples/code-editor.tsx",
+    "examples:flow": "tsx examples/flow.tsx",
+    "examples:flow-stress": "tsx examples/flow-stress.tsx",
+    "examples:formula": "tsx examples/formula.tsx",
+    "examples:html": "tsx examples/html.tsx",
+    "examples:markdown": "tsx examples/markdown.tsx",
+    "examples:media-player": "tsx examples/media-player.tsx",
+    "examples:table": "tsx examples/table.tsx",
+    "examples:terminal": "tsx examples/terminal.tsx",
+    "examples:terminal-output": "tsx examples/terminal-output.tsx",
+    "examples:terminal-vt": "tsx examples/terminal-vt.tsx",
+    "examples:terminal-ssh": "tsx examples/terminal-ssh.tsx",
+    "examples:three": "tsx examples/three.tsx",
+    "examples:three-effects": "tsx examples/three-effects.tsx",
+    "examples:timeline": "tsx examples/timeline.tsx",
+    "examples:tray-host": "tsx examples/tray-host.tsx",
+    "examples:tree": "tsx examples/tree.tsx",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "css-select": "^7.0.0",
+    "domhandler": "^6.0.0",
+    "domutils": "^4.0.0",
+    "htmlparser2": "^12.0.0",
+    "react-reconciler": "^0.33.0"
   },
   "peerDependencies": {
+    "@lezer/highlight": "^1.0.0",
+    "@lydell/node-pty": "^1.0.0",
+    "node-pty": "^1.0.0",
     "react": "^19.0.0",
     "react-x11": "^2.0.0"
   },
+  "peerDependenciesMeta": {
+    "@lezer/highlight": {
+      "optional": true
+    },
+    "@lydell/node-pty": {
+      "optional": true
+    },
+    "node-pty": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@eslint/js": "^9.32.0",
+    "@lydell/node-pty": "^1.2.0-beta.15",
+    "@types/node": "^26.2.0",
     "@types/react": "^19.2.17",
     "esbuild": "^0.28.1",
     "eslint": "^9.32.0",
-    "eslint-plugin-react": "^7.37.5",
     "globals": "^17.8.0",
     "prettier": "^3.6.0",
     "react": "^19.2.8",
-    "react-x11": "github:sidorares/react-x11#master",
+    "react-x11": "^2.0.0",
     "tsx": "^4.23.1",
     "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "optionalDependencies": {
+    "@xterm/headless": "^6.0.0",
+    "ical.js": "^2.2.1",
+    "katex": "^0.18.4"
   }
 }

package/src/ansi/cast.ts

@@ -0,0 +1,159 @@
+// asciinema recordings, read.
+//
+// A cast is the standard interchange format for "I ran this in a pty and kept
+// it", so a static renderer that cannot open one is a static renderer that
+// asks every user to write the same twenty lines. Both published versions are
+// read: v2 is JSON Lines (a header object, then `[time, kind, data]` events),
+// v1 is one JSON document with relative delays.
+//
+// **This is a reader, not a player.** `castOutput(cast, { until })` gives the
+// bytes up to a moment and `parseAnsi` turns those into a document; scheduling
+// the moments is the app's, because a component with a timer inside it never
+// settles in a screenshot test. See the PRD.
+
+/** The recording's own metadata: the grid it was made at, and its title. */
+export interface AnsiCastHeader {
+  version: number;
+  width: number;
+  height: number;
+  title?: string;
+  /** Unix seconds, when the recording says. */
+  timestamp?: number;
+  env?: Readonly<Record<string, string>>;
+}
+
+/** One recorded event. `'o'` is output — the only kind that has pixels. */
+export interface AnsiCastEvent {
+  /** Seconds from the start of the recording. Absolute, v1's deltas
+   *  included: a reader should not have to know which version it opened. */
+  readonly time: number;
+  readonly kind: 'o' | 'i' | 'r' | 'm' | string;
+  readonly data: string;
+}
+
+export interface AnsiCast {
+  readonly header: AnsiCastHeader;
+  readonly events: readonly AnsiCastEvent[];
+}
+
+/** What `parseCast` refuses. Its own type so an app can tell "not a cast"
+ *  from a read error, which is the only distinction a caller acts on. */
+export class CastFormatError extends Error {
+  constructor(message: string) {
+    super(`@react-x11/components: ${message}`);
+    this.name = 'CastFormatError';
+  }
+}
+
+function headerOf(value: unknown): AnsiCastHeader {
+  const raw = (value ?? {}) as Record<string, unknown>;
+  const num = (v: unknown, dflt: number): number =>
+    typeof v === 'number' && Number.isFinite(v) ? v : dflt;
+  const header: AnsiCastHeader = {
+    version: num(raw.version, 2),
+    width: Math.max(1, num(raw.width, 80)),
+    height: Math.max(1, num(raw.height, 24)),
+  };
+  if (typeof raw.title === 'string') header.title = raw.title;
+  if (typeof raw.timestamp === 'number') header.timestamp = raw.timestamp;
+  if (raw.env && typeof raw.env === 'object') {
+    header.env = raw.env as Record<string, string>;
+  }
+  return header;
+}
+
+/**
+ * Read a recording.
+ *
+ * A malformed *event* line is skipped rather than fatal — a recording still
+ * being written has a partial last line, and refusing the whole file over it
+ * is the wrong trade. A missing or unreadable *header* throws, because
+ * without one there is no recording to read.
+ */
+export function parseCast(text: string): AnsiCast {
+  const trimmed = text.trim();
+  if (!trimmed) throw new CastFormatError('the recording is empty');
+
+  // v1 is one JSON document, so it is exactly the case where parsing the
+  // whole file succeeds. A v2 file is several JSON values and does not.
+  let whole: unknown;
+  try {
+    whole = JSON.parse(trimmed);
+  } catch {
+    whole = undefined;
+  }
+  if (whole && typeof whole === 'object') {
+    const raw = whole as Record<string, unknown>;
+    if (Array.isArray(raw.stdout)) {
+      const header = headerOf(raw);
+      const events: AnsiCastEvent[] = [];
+      let time = 0;
+      for (const entry of raw.stdout) {
+        if (!Array.isArray(entry) || entry.length < 2) continue;
+        const [delay, data] = entry as [unknown, unknown];
+        if (typeof delay !== 'number' || typeof data !== 'string') continue;
+        // v1 records the gap since the previous event; every consumer wants
+        // the moment, so the conversion happens here rather than in each one.
+        time += delay;
+        events.push({ time, kind: 'o', data });
+      }
+      return { header: { ...header, version: 1 }, events };
+    }
+    // A v2 file whose recording is empty: a header and nothing after it.
+    return { header: headerOf(raw), events: [] };
+  }
+
+  const lines = trimmed.split('\n');
+  let header: AnsiCastHeader | null = null;
+  const events: AnsiCastEvent[] = [];
+  for (const line of lines) {
+    const source = line.trim();
+    if (!source) continue;
+    let value: unknown;
+    try {
+      value = JSON.parse(source);
+    } catch {
+      continue;
+    }
+    if (!header) {
+      if (Array.isArray(value)) {
+        throw new CastFormatError(
+          'the recording starts with an event rather than a header — ' +
+            'this does not look like an asciinema cast',
+        );
+      }
+      header = headerOf(value);
+      continue;
+    }
+    if (!Array.isArray(value) || value.length < 3) continue;
+    const [time, kind, data] = value as [unknown, unknown, unknown];
+    if (typeof time !== 'number' || typeof data !== 'string') continue;
+    events.push({ time, kind: typeof kind === 'string' ? kind : 'o', data });
+  }
+  if (!header) {
+    throw new CastFormatError('the recording has no header line');
+  }
+  return { header, events };
+}
+
+/**
+ * The recorded output, concatenated — what a terminal received.
+ *
+ * `until` is a moment in seconds: pass it to render the session as it looked
+ * then, which with a slider in the app is a scrubber and without one is a
+ * still. Input, resize and marker events are left out, because only output
+ * has pixels.
+ */
+export function castOutput(
+  cast: AnsiCast,
+  options: { until?: number } = {},
+): string {
+  const until = options.until ?? Infinity;
+  let out = '';
+  for (const event of cast.events) {
+    if (event.kind !== 'o') continue;
+    if (event.time > until) break;
+    out += event.data;
+  }
+  return out;
+}

package/src/ansi/index.ts

@@ -0,0 +1,53 @@
+// A captured terminal session, as a document — the parser under
+// `<TerminalOutput>`, and useful on its own.
+//
+// ```ts
+// import { parseAnsi } from '@react-x11/components/ansi';
+//
+// const doc = parseAnsi(await readFile('build.log'));
+// doc.lines.map((line) => line.text); // the text, escapes resolved away
+// doc.needsScreen;                    // did these bytes want a grid?
+// doc.dropped;                        // what could not be honoured
+// ```
+//
+// **A shared module, not a component.** Nothing here registers an element,
+// renders anything, or does any work at import time; there is no optional
+// dependency and no `@xterm/headless`. It has a subpath of its own because
+// "turn a log into styled text" is a thing to want without a terminal
+// anywhere near it — colouring a build log inside a `<Markdown>` document,
+// say, or stripping escapes before a diff.
+//
+// `docs/prd-terminal-output.md` is the design record: why a log is a document
+// rather than a grid, and what that model can and cannot represent.
+export { parseAnsi, stripAnsi, AnsiState } from './parse.js';
+export type {
+  AnsiDocument,
+  AnsiInput,
+  AnsiLine,
+  AnsiSpan,
+  ParseAnsiOptions,
+} from './parse.js';
+
+export { PLAIN, Style, ansiColor, rgbColor, param, ABSENT } from './sgr.js';
+export type { AnsiAttrs, AnsiColor, AnsiUnderline } from './sgr.js';
+
+export {
+  ANSI_16,
+  ansiPalette,
+  cssColor,
+  mixRgb,
+  parseCssColor,
+  resolveAnsiColors,
+} from './palette.js';
+export type {
+  AnsiColorAttrs,
+  AnsiPalette,
+  AnsiPaletteOptions,
+  ResolvedAnsiColors,
+  Rgb,
+} from './palette.js';
+
+export { CastFormatError, castOutput, parseCast } from './cast.js';
+export type { AnsiCast, AnsiCastEvent, AnsiCastHeader } from './cast.js';
+
+export { Utf8Decoder } from './utf8.js';

package/src/ansi/palette.ts

@@ -0,0 +1,226 @@
+// The palette, and what a span's two colours resolve to. Pure — no theme, no
+// element, no React — so every rule below is asserted directly.
+//
+// This is the second half of the "colour is intent, not pixels" split the
+// parser makes: `./sgr.ts` records that a program asked for ANSI 2, and this
+// is where a palette decides which pixels that is. Keeping them apart is what
+// lets one parsed capture render against a light theme and a dark one.
+//
+// **`../terminal/vt/colors.ts` is the other copy of the ANSI table**, and the
+// two are deliberately not shared today: that one is a component's internals,
+// and a shared module may not reach into a component. The phase-2 promotion in
+// `docs/prd-terminal-output.md` moves the cell grid out to a shared module,
+// and the merge direction is *this* file — the grid renderer depends on the
+// ANSI colour model, never the reverse.
+import type { AnsiColor } from './sgr.js';
+
+/** A colour as a packed `0xRRGGBB`, the way the arithmetic below wants it. */
+export type Rgb = number;
+
+/**
+ * The standard 16 — xterm's own defaults, which is what an application's
+ * colour choices were made against.
+ */
+export const ANSI_16: readonly Rgb[] = [
+  0x000000, 0xcd0000, 0x00cd00, 0xcdcd00, 0x0000ee, 0xcd00cd, 0x00cdcd,
+  0xe5e5e5, 0x7f7f7f, 0xff0000, 0x00ff00, 0xffff00, 0x5c5cff, 0xff00ff,
+  0x00ffff, 0xffffff,
+];
+
+export interface AnsiPalette {
+  /** 256 entries: the 16 ANSI, the 6×6×6 cube, the 24 greys. */
+  readonly colors: Int32Array;
+  readonly foreground: Rgb;
+  readonly background: Rgb;
+  /** Bold promotes ANSI 0–7 to 8–15, which is how most colour schemes were
+   *  designed to be read. */
+  readonly brightBold: boolean;
+}
+
+export interface AnsiPaletteOptions {
+  /** The default ink. A CSS colour; anything unparseable keeps the default
+   *  rather than painting something arbitrary. */
+  foreground?: string;
+  background?: string;
+  /** ANSI 0–15, sparse — an entry left out keeps the standard colour. */
+  palette?: readonly (string | undefined)[];
+  /** Default true. */
+  brightBold?: boolean;
+}
+
+/** The names a terminal colour prop plausibly carries. Not CSS's whole list. */
+const NAMED: Readonly<Record<string, Rgb>> = {
+  black: 0x000000,
+  white: 0xffffff,
+  red: 0xff0000,
+  green: 0x008000,
+  blue: 0x0000ff,
+  yellow: 0xffff00,
+  cyan: 0x00ffff,
+  magenta: 0xff00ff,
+  gray: 0x808080,
+  grey: 0x808080,
+};
+
+/**
+ * `#rgb`, `#rrggbb`, `rgb(…)` and the handful of names above.
+ *
+ * `null` for anything else, and every caller keeps its default rather than
+ * guessing — a theme token that did not resolve should look like the theme,
+ * not like black.
+ */
+export function parseCssColor(value: string | undefined): Rgb | null {
+  if (!value) return null;
+  const text = value.trim().toLowerCase();
+  if (text.startsWith('#')) {
+    const hex = text.slice(1);
+    if (hex.length === 3 || hex.length === 4) {
+      const r = Number.parseInt(hex[0]! + hex[0]!, 16);
+      const g = Number.parseInt(hex[1]! + hex[1]!, 16);
+      const b = Number.parseInt(hex[2]! + hex[2]!, 16);
+      if (Number.isNaN(r + g + b)) return null;
+      return (r << 16) | (g << 8) | b;
+    }
+    if (hex.length === 6 || hex.length === 8) {
+      const n = Number.parseInt(hex.slice(0, 6), 16);
+      return Number.isNaN(n) ? null : n;
+    }
+    return null;
+  }
+  const fn = /^rgba?\(([^)]+)\)$/.exec(text);
+  if (fn) {
+    const parts = fn[1]!.split(/[\s,/]+/).filter(Boolean);
+    if (parts.length < 3) return null;
+    const channel = (part: string): number => {
+      const n = part.endsWith('%')
+        ? (Number.parseFloat(part) * 255) / 100
+        : Number.parseFloat(part);
+      return Number.isFinite(n)
+        ? Math.max(0, Math.min(255, Math.round(n)))
+        : -1;
+    };
+    const r = channel(parts[0]!);
+    const g = channel(parts[1]!);
+    const b = channel(parts[2]!);
+    if (r < 0 || g < 0 || b < 0) return null;
+    return (r << 16) | (g << 8) | b;
+  }
+  return NAMED[text] ?? null;
+}
+
+/** `#rrggbb`, which is what a `<richtext>` run takes. */
+export function cssColor(rgb: Rgb): string {
+  return `#${(rgb & 0xffffff).toString(16).padStart(6, '0')}`;
+}
+
+/** Mix towards `b`, `t` in 0..1 — what `dim` uses. */
+export function mixRgb(a: Rgb, b: Rgb, t: number): Rgb {
+  const lerp = (shift: number): number => {
+    const av = (a >> shift) & 0xff;
+    const bv = (b >> shift) & 0xff;
+    return Math.round(av + (bv - av) * t);
+  };
+  return (lerp(16) << 16) | (lerp(8) << 8) | lerp(0);
+}
+
+/**
+ * The 256-colour palette.
+ *
+ * 0–15 come from `palette` where it has an entry and from the standard set
+ * where it does not; 16–231 are the 6×6×6 cube and 232–255 the 24 greys, both
+ * fixed by the protocol rather than by taste.
+ */
+export function ansiPalette(options: AnsiPaletteOptions = {}): AnsiPalette {
+  const colors = new Int32Array(256);
+  for (let i = 0; i < 16; i++) {
+    colors[i] = parseCssColor(options.palette?.[i]) ?? ANSI_16[i]!;
+  }
+  const cube = [0, 95, 135, 175, 215, 255];
+  for (let i = 0; i < 216; i++) {
+    const r = cube[Math.floor(i / 36) % 6]!;
+    const g = cube[Math.floor(i / 6) % 6]!;
+    const b = cube[i % 6]!;
+    colors[16 + i] = (r << 16) | (g << 8) | b;
+  }
+  for (let i = 0; i < 24; i++) {
+    const v = 8 + i * 10;
+    colors[232 + i] = (v << 16) | (v << 8) | v;
+  }
+  return {
+    colors,
+    foreground: parseCssColor(options.foreground) ?? 0xe6e6e6,
+    background: parseCssColor(options.background) ?? 0x101014,
+    brightBold: options.brightBold ?? true,
+  };
+}
+
+/** What a span is actually painted in. */
+export interface ResolvedAnsiColors {
+  fg: string;
+  /**
+   * Absent means "whatever is behind" — the page, the block's own fill.
+   *
+   * The distinction is the whole reason a log can sit inside a document: text
+   * in the default background must not paint a rectangle, or every line
+   * becomes an opaque strip and the block stops being part of the page.
+   */
+  bg?: string;
+}
+
+/** The attribute slice the resolution reads — the six fields of an
+ *  `AnsiAttrs` that can change a colour, and nothing else. */
+export interface AnsiColorAttrs {
+  readonly fg?: AnsiColor;
+  readonly bg?: AnsiColor;
+  readonly bold?: boolean;
+  readonly dim?: boolean;
+  readonly inverse?: boolean;
+  readonly conceal?: boolean;
+}
+
+function rgbOf(color: AnsiColor, palette: AnsiPalette): Rgb {
+  return color.kind === 'rgb'
+    ? color.value & 0xffffff
+    : palette.colors[Math.max(0, Math.min(255, color.index))]!;
+}
+
+/**
+ * A span's two colours, after every transform that can change them.
+ *
+ * The order is the one every terminal agrees on, and it is the same order
+ * `../terminal/vt/colors.ts` applies to a live cell — bright-bold, dim,
+ * inverse, conceal — so a capture and the program that produced it look the
+ * same in one window.
+ */
+export function resolveAnsiColors(
+  attrs: AnsiColorAttrs,
+  palette: AnsiPalette,
+): ResolvedAnsiColors {
+  const fgColor = attrs.fg;
+  const bgColor = attrs.bg;
+  let fg = fgColor ? rgbOf(fgColor, palette) : palette.foreground;
+  let bg = bgColor ? rgbOf(bgColor, palette) : palette.background;
+  /** Nothing has claimed the background yet, so the surface keeps it. */
+  let bare = bgColor === undefined;
+
+  if (
+    attrs.bold &&
+    palette.brightBold &&
+    fgColor?.kind === 'ansi' &&
+    fgColor.index < 8
+  ) {
+    fg = palette.colors[fgColor.index + 8]!;
+  }
+  if (attrs.dim) fg = mixRgb(fg, bg, 0.5);
+  if (attrs.inverse) {
+    const swap = fg;
+    fg = bg;
+    bg = swap;
+    // An inverted run paints its background even when neither colour was set:
+    // that is the entire visible effect of SGR 7.
+    bare = false;
+  }
+  if (attrs.conceal) fg = bg;
+
+  return bare ? { fg: cssColor(fg) } : { fg: cssColor(fg), bg: cssColor(bg) };
+}