@visulima/tui 0.0.1 → 1.0.0-alpha.2

package/dist/react/styles.d.ts

@@ -0,0 +1,83 @@
+import Yoga from "yoga-layout";
+type YogaNode = ReturnType<typeof Yoga.Node.create>;
+export declare const NAMED_COLORS: Record<string, number>;
+/**
+ * Resolve a color value to an ANSI 256-color index.
+ * Accepts: number (pass-through), string name ("green"), hex ("#FF8800"),
+ * rgb() ("rgb(255,136,0)"), ansi256() ("ansi256(42)"), or undefined (→ 255 = terminal default).
+ */
+export declare function resolveColor(color: number | string | undefined): number;
+export type Styles = {
+    alignContent?: "flex-start" | "flex-end" | "center" | "stretch" | "space-between" | "space-around";
+    alignItems?: "flex-start" | "center" | "flex-end" | "stretch" | "baseline";
+    alignSelf?: "flex-start" | "center" | "flex-end" | "auto" | "stretch" | "baseline";
+    aspectRatio?: number;
+    backgroundColor?: number | string;
+    bg?: number | string;
+    bold?: boolean;
+    borderBottom?: boolean;
+    borderBottomColor?: number | string;
+    borderColor?: number | string;
+    borderLeft?: boolean;
+    borderLeftColor?: number | string;
+    borderRight?: boolean;
+    borderRightColor?: number | string;
+    borderStyle?: "single" | "double" | "round" | "bold" | "singleDouble" | "doubleSingle" | "classic";
+    borderTop?: boolean;
+    borderTopColor?: number | string;
+    bottom?: number | string;
+    color?: number | string;
+    columnGap?: number;
+    dim?: boolean;
+    display?: "flex" | "none";
+    fg?: number | string;
+    flexBasis?: number | string;
+    flexDirection?: "row" | "column" | "row-reverse" | "column-reverse";
+    flexGrow?: number;
+    flexShrink?: number;
+    flexWrap?: "nowrap" | "wrap" | "wrap-reverse";
+    gap?: number;
+    height?: number | string;
+    /** Internal flag for sticky header alternate nodes */
+    internalStickyAlternate?: boolean;
+    inverse?: boolean;
+    italic?: boolean;
+    justifyContent?: "flex-start" | "flex-end" | "space-between" | "space-around" | "space-evenly" | "center";
+    left?: number | string;
+    margin?: number;
+    marginBottom?: number;
+    marginLeft?: number;
+    marginRight?: number;
+    marginTop?: number;
+    marginX?: number;
+    marginY?: number;
+    maxHeight?: number | string;
+    maxWidth?: number | string;
+    minHeight?: number | string;
+    minWidth?: number | string;
+    overflow?: "hidden" | "scroll" | "visible";
+    overflowX?: "hidden" | "scroll" | "visible";
+    overflowY?: "hidden" | "scroll" | "visible";
+    padding?: number;
+    paddingBottom?: number;
+    paddingLeft?: number;
+    paddingRight?: number;
+    paddingTop?: number;
+    paddingX?: number;
+    paddingY?: number;
+    position?: "absolute" | "relative" | "static";
+    right?: number | string;
+    rowGap?: number;
+    scrollbar?: boolean;
+    scrollbarThumbColor?: string;
+    scrollLeft?: number;
+    scrollTop?: number;
+    sticky?: boolean;
+    strikethrough?: boolean;
+    styles?: number;
+    top?: number | string;
+    underline?: boolean;
+    width?: number | string;
+};
+export declare const applyStyles: (node: YogaNode, style?: Styles, currentStyle?: Styles) => void;
+export {};

package/dist/react/text-width.d.ts

@@ -0,0 +1,20 @@
+/** Display width of a single Unicode code point (at least 1 cell). */
+export declare function getCodePointWidth(char: string): number;
+/** Display width of a full string (sums grapheme widths). */
+export declare function getStringWidth(text: string): number;
+/**
+ * Count wrapped visual rows for a single hard line (no '\n') at a fixed width.
+ *
+ * - Widths are measured in terminal cells, not UTF-16 code units.
+ * - Wide chars (CJK/emoji) consume 2 cells.
+ * - Empty lines still occupy one visual row.
+ */
+export declare function countWrappedRowsForLine(line: string, width: number): number;
+/**
+ * Measure the max visual line width and wrapped height of a text block.
+ * Returns widths/heights in terminal cells/rows.
+ */
+export declare function measureTextBlock(text: string, wrapWidth: number): {
+    maxLineWidth: number;
+    wrappedRows: number;
+};

package/dist/testing/index.d.ts

@@ -0,0 +1,144 @@
+import type { ReactElement } from "react";
+import type { RenderOptions } from "../ink/render.d.ts";
+import type { KeySender } from "./keys.d.ts";
+import { createKeySender, KEY } from "./keys.d.ts";
+import type { Screen } from "./screen.d.ts";
+import { createScreen } from "./screen.d.ts";
+import type { WaitForOptions } from "./wait-for.d.ts";
+import { waitFor } from "./wait-for.d.ts";
+export type TestInstanceStdout = {
+    /**
+     * All rendered frames captured from stdout.
+     */
+    readonly frames: ReadonlyArray<string>;
+    /**
+     * Returns the most recently rendered frame, or `undefined` if no frames have been written.
+     */
+    lastFrame: () => string | undefined;
+    /**
+     * Write data to the mock stdout stream (used internally by the renderer).
+     */
+    write: (frame: string) => boolean;
+};
+export type TestInstanceStderr = {
+    /**
+     * All rendered frames captured from stderr.
+     */
+    readonly frames: ReadonlyArray<string>;
+    /**
+     * Returns the most recently rendered frame, or `undefined` if no frames have been written.
+     */
+    lastFrame: () => string | undefined;
+    /**
+     * Write data to the mock stderr stream (used internally by the renderer).
+     */
+    write: (frame: string) => boolean;
+};
+export type TestInstanceStdin = {
+    /**
+     * Whether the stdin is a TTY.
+     */
+    readonly isTTY: boolean;
+    /**
+     * Simulate user input by writing data to stdin.
+     */
+    write: (data: string) => boolean;
+};
+export type TestInstance = {
+    /**
+     * Unmount the app and clean up resources.
+     */
+    cleanup: () => void;
+    /**
+     * Wait for pending React renders to flush (two microtick delay).
+     */
+    flush: () => Promise<void>;
+    /**
+     * All rendered frames captured from stdout (shorthand for `stdout.frames`).
+     */
+    readonly frames: ReadonlyArray<string>;
+    /**
+     * Keyboard input helpers for simulating key presses.
+     */
+    keys: KeySender;
+    /**
+     * Returns the most recently rendered frame from stdout (shorthand for `stdout.lastFrame()`).
+     */
+    lastFrame: () => string | undefined;
+    /**
+     * Replace the previous root node with a new one or update props.
+     */
+    rerender: (node: ReactElement) => void;
+    /**
+     * Screen query helpers for inspecting rendered output with ANSI stripping.
+     */
+    screen: Screen;
+    /**
+     * Mock stderr stream with frame capture.
+     */
+    stderr: TestInstanceStderr;
+    /**
+     * Mock stdin stream for simulating user input.
+     */
+    stdin: TestInstanceStdin;
+    /**
+     * Mock stdout stream with frame capture.
+     */
+    stdout: TestInstanceStdout;
+    /**
+     * Manually unmount the whole app.
+     */
+    unmount: () => void;
+    /**
+     * Wait for a condition to be met by polling.
+     *
+     * If `condition` is a string, waits until the screen contains it.
+     * If `condition` is a function, waits until it stops throwing.
+     */
+    waitFor: (condition: (() => void) | string, options?: WaitForOptions) => Promise<void>;
+};
+export type TestRenderOptions = {
+    /**
+     * Terminal column width for the mock stdout/stderr streams.
+     * @default 100
+     */
+    columns?: number;
+    /**
+     * Additional render options passed through to the underlying render function.
+     */
+    options?: Omit<RenderOptions, "debug" | "exitOnCtrlC" | "patchConsole" | "stderr" | "stdin" | "stdout">;
+};
+/**
+ * Render a React element for testing, capturing output in mock streams.
+ *
+ * Returns an object with methods to inspect rendered output, simulate input,
+ * and control the component lifecycle.
+ * @example
+ * ```tsx
+ * import { render } from "@visulima/tui/test";
+ * import { Text } from "@visulima/tui";
+ *
+ * const { lastFrame } = render(<Text>Hello</Text>);
+ * console.log(lastFrame()); // "Hello"
+ * ```
+ */
+declare const testRender: (node: ReactElement, testOptions?: TestRenderOptions) => TestInstance;
+/**
+ * Unmount and clean up all rendered test instances.
+ *
+ * Call this in your test teardown (e.g., `afterEach`) to ensure
+ * no test instances leak between tests.
+ * @example
+ * ```ts
+ * import { cleanup } from "@visulima/tui/test";
+ *
+ * afterEach(() => {
+ *     cleanup();
+ * });
+ * ```
+ */
+declare const cleanup: () => void;
+export { cleanup, createKeySender, createScreen, KEY, testRender as render, waitFor };
+export type { KeyName, KeySender } from "./keys.d.ts";
+export type { Screen } from "./screen.d.ts";
+export type { WaitForOptions } from "./wait-for.d.ts";

package/dist/testing/index.js

@@ -0,0 +1,260 @@
+import { createRequire as __cjs_createRequire } from "node:module";
+
+const __cjs_require = __cjs_createRequire(import.meta.url);
+
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+
+const __cjs_getBuiltinModule = (module) => {
+    // Check if we're in Node.js and version supports getBuiltinModule
+    if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+        const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+        // Node.js 20.16.0+ and 22.3.0+
+        if (major > 22 || (major === 22 && minor >= 3) || (major === 20 && minor >= 16)) {
+            return __cjs_getProcess.getBuiltinModule(module);
+        }
+    }
+    // Fallback to createRequire
+    return __cjs_require(module);
+};
+
+const EventEmitter = __cjs_getBuiltinModule("node:events");
+import render from '../packem_shared/render-BAwdjfki.js';
+import { strip } from '@visulima/ansi';
+
+const KEY = {
+  backspace: "",
+  ctrlC: "",
+  delete: "\x1B[3~",
+  down: "\x1B[B",
+  end: "\x1B[F",
+  escape: "\x1B",
+  home: "\x1B[H",
+  left: "\x1B[D",
+  pageDown: "\x1B[6~",
+  pageUp: "\x1B[5~",
+  return: "\r",
+  right: "\x1B[C",
+  space: " ",
+  tab: "	",
+  up: "\x1B[A"
+};
+const createKeySender = (write) => ({
+  backspace: () => write(KEY.backspace),
+  delete: () => write(KEY.delete),
+  down: () => write(KEY.down),
+  end: () => write(KEY.end),
+  enter: () => write(KEY.return),
+  escape: () => write(KEY.escape),
+  home: () => write(KEY.home),
+  left: () => write(KEY.left),
+  pageDown: () => write(KEY.pageDown),
+  pageUp: () => write(KEY.pageUp),
+  press(char) {
+    write(char);
+  },
+  raw: write,
+  right: () => write(KEY.right),
+  space: () => write(KEY.space),
+  tab: () => write(KEY.tab),
+  type(text) {
+    for (const char of text) {
+      write(char);
+    }
+  },
+  up: () => write(KEY.up)
+});
+
+const createScreen = (lastFrame, allFrames) => {
+  const clean = (s) => s ? strip(s) : "";
+  return {
+    contains(text) {
+      return this.text().includes(text);
+    },
+    frames() {
+      return allFrames.map((f) => strip(f));
+    },
+    line(n) {
+      return this.text().split("\n")[n] ?? "";
+    },
+    lines() {
+      return this.text().split("\n").filter((l) => l.trim() !== "");
+    },
+    matches(pattern) {
+      return pattern.test(this.text());
+    },
+    rawFrames() {
+      return [...allFrames];
+    },
+    rawText() {
+      return lastFrame() ?? "";
+    },
+    text() {
+      return clean(lastFrame());
+    }
+  };
+};
+
+const waitFor = async (condition, screenText, options = {}) => {
+  const timeout = options.timeout ?? 3e3;
+  const interval = options.interval ?? 50;
+  const start = Date.now();
+  let lastError;
+  const check = () => {
+    if (typeof condition === "string") {
+      const current = screenText();
+      if (!current.includes(condition)) {
+        throw new Error(`Timed out waiting for text: "${condition}"
+
+Screen content:
+${current}`);
+      }
+    } else {
+      condition();
+    }
+  };
+  while (Date.now() - start < timeout) {
+    try {
+      check();
+      return;
+    } catch (error) {
+      lastError = error;
+    }
+    await new Promise((resolve) => {
+      setTimeout(resolve, interval);
+    });
+  }
+  try {
+    check();
+    return;
+  } catch (error) {
+    lastError = error;
+  }
+  throw lastError ?? new Error("waitFor timed out");
+};
+
+class Stdout extends EventEmitter {
+  columns;
+  _lastFrame;
+  _frames = [];
+  constructor(columns = 100) {
+    super();
+    this.columns = columns;
+  }
+  get frames() {
+    return this._frames;
+  }
+  lastFrame() {
+    return this._lastFrame;
+  }
+  write = (frame) => {
+    this._frames.push(frame);
+    this._lastFrame = frame;
+    return true;
+  };
+}
+class Stderr extends EventEmitter {
+  columns;
+  _lastFrame;
+  _frames = [];
+  constructor(columns = 100) {
+    super();
+    this.columns = columns;
+  }
+  get frames() {
+    return this._frames;
+  }
+  lastFrame() {
+    return this._lastFrame;
+  }
+  write = (frame) => {
+    this._frames.push(frame);
+    this._lastFrame = frame;
+    return true;
+  };
+}
+class Stdin extends EventEmitter {
+  isTTY = true;
+  pendingData;
+  write = (data) => {
+    this.pendingData = data;
+    this.emit("readable");
+    this.emit("data", data);
+    return true;
+  };
+  read() {
+    const { pendingData } = this;
+    this.pendingData = void 0;
+    return pendingData;
+  }
+  setEncoding() {
+    return this;
+  }
+  setRawMode() {
+    return this;
+  }
+  resume() {
+    return this;
+  }
+  pause() {
+    return this;
+  }
+  ref() {
+    return this;
+  }
+  unref() {
+    return this;
+  }
+}
+const instances = [];
+const testRender = (node, testOptions = {}) => {
+  const { columns, options: renderOptions } = testOptions;
+  const stdout = new Stdout(columns);
+  const stderr = new Stderr(columns);
+  const stdin = new Stdin();
+  const instance = render(node, {
+    debug: true,
+    exitOnCtrlC: false,
+    patchConsole: false,
+    stderr,
+    stdin,
+    stdout,
+    ...renderOptions
+  });
+  instances.push(instance);
+  const screen = createScreen(() => stdout.lastFrame(), stdout.frames);
+  const keys = createKeySender((data) => stdin.write(data));
+  const flush = async () => {
+    await new Promise((resolve) => {
+      setTimeout(resolve, 0);
+    });
+    await new Promise((resolve) => {
+      setTimeout(resolve, 0);
+    });
+  };
+  return {
+    cleanup: instance.cleanup,
+    flush,
+    get frames() {
+      return stdout.frames;
+    },
+    keys,
+    lastFrame: () => stdout.lastFrame(),
+    rerender: instance.rerender,
+    screen,
+    stderr,
+    stdin,
+    stdout,
+    unmount: instance.unmount,
+    async waitFor(condition, options) {
+      await waitFor(condition, () => screen.text(), options);
+    }
+  };
+};
+const cleanup = () => {
+  for (const instance of instances) {
+    instance.cleanup();
+  }
+  instances.length = 0;
+};
+
+export { KEY, cleanup, createKeySender, createScreen, testRender as render, waitFor };

package/dist/testing/keys.d.ts

@@ -0,0 +1,89 @@
+export declare const KEY: {
+    readonly backspace: "";
+    readonly ctrlC: "\u0003";
+    readonly delete: "\u001B[3~";
+    readonly down: "\u001B[B";
+    readonly end: "\u001B[F";
+    readonly escape: "\u001B";
+    readonly home: "\u001B[H";
+    readonly left: "\u001B[D";
+    readonly pageDown: "\u001B[6~";
+    readonly pageUp: "\u001B[5~";
+    readonly return: "\r";
+    readonly right: "\u001B[C";
+    readonly space: " ";
+    readonly tab: "\t";
+    readonly up: "\u001B[A";
+};
+export type KeyName = keyof typeof KEY;
+export interface KeySender {
+    /**
+     * Simulate pressing the backspace key.
+     */
+    backspace: () => void;
+    /**
+     * Simulate pressing the delete key.
+     */
+    delete: () => void;
+    /**
+     * Simulate pressing the down arrow key.
+     */
+    down: () => void;
+    /**
+     * Simulate pressing the end key.
+     */
+    end: () => void;
+    /**
+     * Simulate pressing the enter/return key.
+     */
+    enter: () => void;
+    /**
+     * Simulate pressing the escape key.
+     */
+    escape: () => void;
+    /**
+     * Simulate pressing the home key.
+     */
+    home: () => void;
+    /**
+     * Simulate pressing the left arrow key.
+     */
+    left: () => void;
+    /**
+     * Simulate pressing the page down key.
+     */
+    pageDown: () => void;
+    /**
+     * Simulate pressing the page up key.
+     */
+    pageUp: () => void;
+    /**
+     * Send a single character as a key press.
+     */
+    press: (char: string) => void;
+    /**
+     * Send arbitrary raw data to stdin.
+     */
+    raw: (data: string) => void;
+    /**
+     * Simulate pressing the right arrow key.
+     */
+    right: () => void;
+    /**
+     * Simulate pressing the space key.
+     */
+    space: () => void;
+    /**
+     * Simulate pressing the tab key.
+     */
+    tab: () => void;
+    /**
+     * Type a string character by character.
+     */
+    type: (text: string) => void;
+    /**
+     * Simulate pressing the up arrow key.
+     */
+    up: () => void;
+}
+export declare const createKeySender: (write: (data: string) => void) => KeySender;

package/dist/testing/screen.d.ts

@@ -0,0 +1,35 @@
+export interface Screen {
+    /**
+     * Check if the current screen output contains the given text (ANSI-stripped).
+     */
+    contains: (text: string) => boolean;
+    /**
+     * Get all captured frames with ANSI codes stripped.
+     */
+    frames: () => string[];
+    /**
+     * Get a specific line by zero-based index from the current screen output.
+     */
+    line: (n: number) => string;
+    /**
+     * Get all non-empty lines from the current screen output.
+     */
+    lines: () => string[];
+    /**
+     * Check if the current screen output matches the given pattern (ANSI-stripped).
+     */
+    matches: (pattern: RegExp) => boolean;
+    /**
+     * Get all captured frames with ANSI codes preserved.
+     */
+    rawFrames: () => string[];
+    /**
+     * Get the last rendered frame with ANSI codes preserved.
+     */
+    rawText: () => string;
+    /**
+     * Get the last rendered frame with ANSI codes stripped.
+     */
+    text: () => string;
+}
+export declare const createScreen: (lastFrame: () => string | undefined, allFrames: ReadonlyArray<string>) => Screen;

package/dist/testing/wait-for.d.ts

@@ -0,0 +1,21 @@
+export interface WaitForOptions {
+    /**
+     * Polling interval in milliseconds.
+     * @default 50
+     */
+    interval?: number;
+    /**
+     * Maximum time to wait in milliseconds before throwing.
+     * @default 3000
+     */
+    timeout?: number;
+}
+/**
+ * Wait for a condition to be met by polling at a regular interval.
+ *
+ * If `condition` is a string, waits until `screenText()` contains it.
+ * If `condition` is a function, waits until it stops throwing.
+ *
+ * @throws The last error encountered if the timeout is reached.
+ */
+export declare const waitFor: (condition: (() => void) | string, screenText: () => string, options?: WaitForOptions) => Promise<void>;