@visulima/tui 1.0.0-alpha.4 → 1.0.0-alpha.5

package/dist/react/hooks.d.ts

@@ -1,238 +0,0 @@
-import type { Context, RefObject } from "react";
-import type { InputParser, MouseEvent, TuiApp } from "../core/index.d.ts";
-import type { LayoutNode } from "./layout.d.ts";
-export interface TuiContextProps {
-    app: TuiApp;
-    input: InputParser;
-    writeStderr: (text: string) => void;
-    writeStdout: (text: string) => void;
-}
-export declare const TuiContext: Context<TuiContextProps | null>;
-export interface Key {
-    backspace: boolean;
-    ctrl: boolean;
-    delete: boolean;
-    downArrow: boolean;
-    end: boolean;
-    escape: boolean;
-    home: boolean;
-    leftArrow: boolean;
-    meta: boolean;
-    pageDown: boolean;
-    pageUp: boolean;
-    return: boolean;
-    rightArrow: boolean;
-    shift: boolean;
-    tab: boolean;
-    upArrow: boolean;
-}
-export type InputHandler = (input: string, key: Key) => void;
-/**
- * Subscribes to keyboard input. Uses a stable ref so the effect runs
- * exactly once (on mount) regardless of how often the component re-renders.
- * Always invokes the latest handler passed by the caller.
- */
-export declare const useInput: (handler: InputHandler) => void;
-export interface UsePasteOptions {
-    /**
-     * Enable or disable capturing pasted text.
-     * Useful when multiple components use usePaste and only one should be active.
-     * @default true
-     */
-    isActive?: boolean;
-}
-export type PasteHandler = (text: string) => void;
-/**
- * Subscribe to bracketed paste events.
- *
- * `usePaste` and `useInput` can be used together. Paste content is delivered
- * through this hook and not forwarded to useInput while at least one paste
- * listener is active.
- */
-export declare const usePaste: (handler: PasteHandler, options?: UsePasteOptions) => void;
-/**
- * Raw access to the TuiContext — app instance + input parser.
- * Useful for advanced integrations (e.g. DevTools, custom hooks).
- */
-export declare const useTuiContext: () => TuiContextProps;
-/**
- * Access app controls. Returns { exit } for Ink compatibility.
- * exit() triggers a clean shutdown (restores terminal, stops input, exits process).
- */
-export declare const useApp: () => {
-    exit: () => void;
-    quit: () => void;
-};
-/**
- * Returns current terminal dimensions and re-renders on resize (SIGWINCH).
- * Ink-compatible: const { columns, rows } = useWindowSize()
- */
-export declare const useWindowSize: () => {
-    columns: number;
-    rows: number;
-};
-/**
- * Write to stdout without disturbing the TUI.
- * Ink-compatible: const { write, stdout } = useStdout()
- * Output is buffered while the alternate screen is active and flushed on exit.
- */
-export declare const useStdout: () => {
-    stdout: NodeJS.WriteStream & {
-        fd: 1;
-    };
-    write: (text: string) => void;
-};
-/**
- * Write to stderr without disturbing the TUI.
- * Ink-compatible: const { write, stderr } = useStderr()
- * Output is buffered while the alternate screen is active and flushed on exit.
- */
-export declare const useStderr: () => {
-    stderr: NodeJS.WriteStream & {
-        fd: 2;
-    };
-    write: (text: string) => void;
-};
-/**
- * Access raw stdin stream and raw mode controls.
- * Ink-compatible: const { stdin, setRawMode, isRawModeSupported } = useStdin()
- */
-export declare const useStdin: () => {
-    isRawModeSupported: boolean;
-    setRawMode: (value: boolean) => void;
-    stdin: NodeJS.ReadStream & {
-        fd: 0;
-    };
-};
-/**
- * Measure the dimensions of a Box element.
- * Returns { width, height } after layout has been calculated.
- * Returns { width: 0, height: 0 } when called during render (before layout).
- * Ink-compatible: measureElement(ref.current)
- */
-export declare const measureElement: (node: LayoutNode | null) => {
-    height: number;
-    width: number;
-};
-export interface BoxMetrics {
-    readonly height: number;
-    readonly left: number;
-    readonly top: number;
-    readonly width: number;
-}
-export interface UseBoxMetricsResult extends BoxMetrics {
-    readonly hasMeasured: boolean;
-}
-/**
- * Returns the current layout metrics for a Box ref, updating on every render
- * and on terminal resize.
- * Ink-compatible: const { width, height, left, top, hasMeasured } = useBoxMetrics(ref)
- */
-export declare const useBoxMetrics: (ref: RefObject<LayoutNode | null>) => UseBoxMetricsResult;
-/**
- * Returns whether a screen reader is enabled.
- * Stub: always returns false — no screen reader support.
- * Ink-compatible: const isEnabled = useIsScreenReaderEnabled()
- */
-export declare const useIsScreenReaderEnabled: () => boolean;
-/**
- * Returns cursor positioning controls.
- * Stub: the native renderer hides the cursor during rendering (alternate screen).
- * setCursorPosition is a no-op — provided for Ink API compatibility only.
- * Ink-compatible: const { setCursorPosition } = useCursor()
- */
-export declare const useCursor: () => {
-    setCursorPosition: (position: {
-        x: number;
-        y: number;
-    } | undefined) => void;
-};
-/**
- * Scroll state for a fixed-height viewport over variable-height content.
- *
- * Usage:
- *   const scroll = useScrollable({ viewportHeight: 20, contentHeight: totalRows })
- *
- *   &lt;Box height={20}>
- *     &lt;Box marginTop={-scroll.offset}>
- *       {items}
- *     &lt;/Box>
- *   &lt;/Box>
- *
- * contentHeight can be updated as content grows. The offset is automatically
- * clamped so it never scrolls past the end.
- *
- * scrollToBottom() is idempotent — safe to call on every new message append.
- */
-export interface UseScrollableOptions {
-    /** Total height of the content in rows — update as content grows */
-    contentHeight: number;
-    /** Height of the visible window in rows */
-    viewportHeight: number;
-}
-export interface UseScrollableResult {
-    /** True when already at the bottom */
-    atBottom: boolean;
-    /** True when already at the top */
-    atTop: boolean;
-    /** Current scroll offset in rows (0 = top) */
-    offset: number;
-    /** Scroll down N rows */
-    scrollBy: (n: number) => void;
-    /** Scroll down one row */
-    scrollDown: () => void;
-    /** Jump to the very bottom */
-    scrollToBottom: () => void;
-    /** Jump to the very top */
-    scrollToTop: () => void;
-    /** Scroll up one row */
-    scrollUp: () => void;
-}
-export declare const useScrollable: ({ contentHeight, viewportHeight }: UseScrollableOptions) => UseScrollableResult;
-export type MouseHandler = (event: MouseEvent) => void;
-/**
- * Subscribe to mouse events. Requires mouse tracking to be enabled (it is by
- * default — TerminalGuard enables SGR 1006 mouse tracking on start).
- *
- * Usage:
- *   useMouse((event) => {
- *     if (event.button === 'left') { ... }
- *     if (event.button === 'scrollUp') { ... }
- *     // event: { x, y, button, shift, ctrl, meta }
- *   })
- *
- * button values: 'left' | 'right' | 'middle' | 'scrollUp' | 'scrollDown'
- */
-export declare const useMouse: (handler: MouseHandler) => void;
-export interface UseTextInputOptions {
-    /** Initial value (default: '') */
-    initialValue?: string;
-    /** When false, the hook ignores all input (default: true) */
-    isActive?: boolean;
-    /** Called on every keystroke with the new value */
-    onChange?: (value: string) => void;
-    /** Called when the user presses Enter */
-    onSubmit?: (value: string) => void;
-}
-export interface UseTextInputResult {
-    /** Clear the input */
-    clear: () => void;
-    /** Cursor position (0 = before first char, value.length = after last char) */
-    cursor: number;
-    /** Set value programmatically */
-    setValue: (value: string) => void;
-    /** Current text value */
-    value: string;
-}
-/**
- * Managed text input with cursor, backspace, delete, left/right navigation,
- * home/end, bracketed paste, and submit on Enter.
- *
- * Usage:
- *   const { value, cursor } = useTextInput({ onSubmit: (v) => console.log(v) })
- *   &lt;Text>{value.slice(0, cursor)}&lt;Text inverse> &lt;/Text>{value.slice(cursor)}&lt;/Text>
- *
- * Renders a block cursor by inverting the character at cursor position.
- * When cursor is at end, renders a trailing space as the cursor block.
- */
-export declare const useTextInput: ({ initialValue, isActive, onChange, onSubmit }?: UseTextInputOptions) => UseTextInputResult;

package/dist/react/layout.d.ts

@@ -1,33 +0,0 @@
-import Yoga from "yoga-layout";
-type YogaNode = ReturnType<typeof Yoga.Node.create>;
-export declare class LayoutNode {
-    yogaNode: YogaNode;
-    children: LayoutNode[];
-    parent: LayoutNode | null;
-    private _destroyed;
-    _hidden: boolean;
-    transform?: (s: string, index: number) => string;
-    private _text?;
-    fg: number;
-    bg: number;
-    styles: number;
-    _style?: any;
-    set text(value: string | undefined);
-    get text(): string | undefined;
-    constructor();
-    insertChild(child: LayoutNode, index: number): void;
-    remove(): void;
-    removeChild(child: LayoutNode): void;
-    /**
-     * Free this node's Yoga allocation. Called via detachDeletedInstance
-     * in the reconciler after React has permanently removed this node.
-     *
-     * Does NOT recurse — React calls detachDeletedInstance on every node
-     * in a deleted subtree individually, so each node frees only itself.
-     * The _destroyed guard prevents double-free if free() is also called.
-     */
-    destroy(): void;
-    calculateLayout(width: number, height: number): void;
-    getLayout(): ReturnType<YogaNode["getComputedLayout"]>;
-}
-export {};

package/dist/react/react.d.ts

@@ -1,57 +0,0 @@
-import React from "react";
-import type { InlineOptions } from "../core/index.d.ts";
-import { InputParser, TuiApp } from "../core/index.d.ts";
-/** @internal */
-export declare const _Box: React.FC<Record<string, any>>;
-/** @internal */
-export declare const _Text: React.FC<Record<string, any>>;
-/** @internal */
-export declare const _Spacer: React.FC;
-/** Ink-compat render options */
-export interface RenderOptions {
-    /** Ignored — the native renderer is always concurrent */
-    concurrent?: boolean;
-    /** Ignored */
-    debug?: boolean;
-    /** Ignored — Ctrl+C always exits */
-    exitOnCtrlC?: boolean;
-    /** Ignored */
-    incrementalRendering?: boolean;
-    /** Target frames per second for the render loop. Default: 60 */
-    maxFps?: number;
-    /** Ignored — the native renderer always patches console */
-    patchConsole?: boolean;
-}
-/** Return value of render() — Ink-compatible instance handle */
-export interface Instance {
-    /** Internal: direct app access */
-    app: TuiApp;
-    /** Internal: input parser */
-    input: InputParser;
-    rerender: (element: React.ReactElement) => void;
-    unmount: () => void;
-    waitUntilExit: () => Promise<void>;
-}
-export declare function render(element: React.ReactElement, options?: RenderOptions): Instance;
-export interface InlineInstance {
-    /** Unmount the React tree and stop the render loop */
-    unmount: () => void;
-    /** Resolves when the loop exits */
-    waitUntilExit: () => Promise<void>;
-}
-/**
- * Render a React element inline — no alternate screen. The UI appears
- * directly below the current shell prompt and stays in terminal scrollback
- * on exit (or is destroyed if `onExit: 'destroy'` is set).
- *
- * The root Box is sized to `cols × rows`. Use `useInput` and `useApp`
- * exactly as in a full-screen render.
- * @example
- * ```tsx
- * const { waitUntilExit } = renderInline(<Picker />, { rows: 12, onExit: 'destroy' })
- * await waitUntilExit()
- * ```
- */
-export declare function renderInline(element: React.ReactElement, options?: InlineOptions & {
-    maxFps?: number;
-}): InlineInstance;

package/dist/react/reconciler.d.ts

@@ -1,4 +0,0 @@
-import ReactReconciler from "react-reconciler";
-export declare let onAfterCommit: (() => void) | null;
-export declare function setOnAfterCommit(function_: (() => void) | null): void;
-export declare const TuiReconciler: ReturnType<typeof ReactReconciler>;

package/dist/react/render-to-string.d.ts

@@ -1,21 +0,0 @@
-import React from "react";
-export interface RenderToStringOptions {
-    /** Width of the virtual terminal in columns. @default 80 */
-    columns?: number;
-    /** Height of the virtual terminal in rows. @default 24 */
-    rows?: number;
-}
-/**
- * Render a React element to a plain string synchronously.
- * No TTY, no stdin, no alternate screen — pure layout + buffer read-back.
- *
- * Useful for testing, documentation generation, and any scenario where
- * you need rendered output as a string without a live terminal.
- *
- * Notes:
- * - Terminal hooks (useInput, useApp, useStdin, useStdout, useStderr,
- *   useFocus, useFocusManager) return safe no-op defaults — they do not throw.
- * - useEffect callbacks run but state updates they trigger do not affect output.
- * - useLayoutEffect callbacks fire synchronously and DO affect output.
- */
-export declare function renderToString(element: React.ReactElement, options?: RenderToStringOptions): string;

package/dist/react/renderer.d.ts

@@ -1,2 +0,0 @@
-import type { LayoutNode } from "./layout.d.ts";
-export declare function renderTreeToBuffer(root: LayoutNode, buffer: Uint32Array, cols: number, rows: number): void;

package/dist/react/scene.d.ts

@@ -1,3 +0,0 @@
-export * from "./layout.d.ts";
-export * from "./renderer.d.ts";
-export * from "./styles.d.ts";

package/dist/react/static.d.ts

@@ -1,39 +0,0 @@
-import type { ReactNode } from "react";
-import React from "react";
-export type StaticProps<T> = {
-    /**
-     * Render function called for each item. Must assign a unique `key` to the
-     * root element returned.
-     */
-    readonly children: (item: T, index: number) => ReactNode;
-    /**
-     * Array of items to render. Only newly-added items are rendered into the layout —
-     * previously rendered items are frozen (never re-rendered or cleared).
-     * Ideal for streaming output: completed tasks, log lines, test results.
-     */
-    readonly items: T[];
-    /**
-     * Optional styles for the static container Box.
-     */
-    readonly style?: Record<string, unknown>;
-};
-/**
- * `&lt;Static>` permanently renders its output above the dynamic UI.
- *
- * Items are rendered once and frozen — they are never re-rendered or cleared.
- * New items appended to `items` are rendered incrementally and accumulate
- * in the layout above the dynamic content.
- *
- * Matches the Ink `&lt;Static>` API exactly.
- * @example
- * ```tsx
- * <Static items={completedTasks}>
- *   {task => (
- *     <Box key={task.id}>
- *       <Text color="green">✔ {task.title}</Text>
- *     </Box>
- *   )}
- * </Static>
- * ```
- */
-export declare function Static<T>({ children: renderItem, items, style }: StaticProps<T>): React.ReactElement;

package/dist/react/styles.d.ts

@@ -1,83 +0,0 @@
-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

@@ -1,20 +0,0 @@
-/** 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/keys.d.ts

@@ -1,89 +0,0 @@
-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

@@ -1,35 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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>;