@visulima/tui 0.0.1 → 1.0.0-alpha.2

package/dist/packem_shared/wrapOrTruncateStyledLine-DN3Nogoc.js

@@ -0,0 +1,147 @@
+import { S as StyledLine, d as styledLineWidth, i as inkCharacterWidth } from './measure-text-DItZYotK.js';
+
+const truncateStyledLine = (line, columns, position = "end") => {
+  if (columns < 1) {
+    return new StyledLine();
+  }
+  const textWidth = styledLineWidth(line);
+  if (textWidth <= columns) {
+    return line;
+  }
+  const ellipsis = new StyledLine();
+  ellipsis.pushChar("…", 0);
+  if (columns === 1) {
+    return ellipsis;
+  }
+  if (position === "start") {
+    let width = 0;
+    let startIndex = line.length;
+    for (let i = line.length - 1; i >= 0; i--) {
+      width += inkCharacterWidth(line.getValue(i));
+      if (width > columns - 1) {
+        break;
+      }
+      startIndex = i;
+    }
+    return ellipsis.combine(line.slice(startIndex));
+  }
+  if (position === "middle") {
+    const leftWidth = Math.ceil(columns / 2);
+    const rightWidth = columns - leftWidth;
+    let leftEnd = 0;
+    let w2 = 0;
+    for (let i = 0; i < line.length; i++) {
+      const cw = inkCharacterWidth(line.getValue(i));
+      if (w2 + cw > leftWidth - 1) {
+        break;
+      }
+      w2 += cw;
+      leftEnd = i + 1;
+    }
+    let rightStart = line.length;
+    w2 = 0;
+    for (let i = line.length - 1; i >= 0; i--) {
+      w2 += inkCharacterWidth(line.getValue(i));
+      if (w2 > rightWidth) {
+        break;
+      }
+      rightStart = i;
+    }
+    return line.slice(0, leftEnd).combine(ellipsis, line.slice(rightStart));
+  }
+  let endIndex = 0;
+  let w = 0;
+  for (let i = 0; i < line.length; i++) {
+    const cw = inkCharacterWidth(line.getValue(i));
+    if (w + cw > columns - 1) {
+      break;
+    }
+    w += cw;
+    endIndex = i + 1;
+  }
+  return line.slice(0, endIndex).combine(ellipsis);
+};
+const wrapStyledLine = (line, columns) => {
+  const rows = [];
+  let currentRowStart = 0;
+  let currentRowWidth = 0;
+  let isAtStartOfLogicalLine = true;
+  let i = 0;
+  while (i < line.length) {
+    const firstValue = line.getValue(i);
+    if (firstValue === "\n") {
+      rows.push(line.slice(currentRowStart, i));
+      currentRowStart = i + 1;
+      currentRowWidth = 0;
+      isAtStartOfLogicalLine = true;
+      i++;
+      continue;
+    }
+    let j = i;
+    let wordWidth = 0;
+    if (firstValue === " ") {
+      wordWidth = inkCharacterWidth(" ");
+      j = i + 1;
+    } else {
+      while (j < line.length && line.getValue(j) !== " " && line.getValue(j) !== "\n") {
+        wordWidth += inkCharacterWidth(line.getValue(j));
+        j++;
+      }
+    }
+    if (currentRowWidth + wordWidth > columns && currentRowWidth > 0) {
+      if (firstValue === " " && !isAtStartOfLogicalLine && !line.hasStyles(i)) {
+        i = j;
+        continue;
+      }
+      let trimEnd = i;
+      while (trimEnd > currentRowStart && line.getValue(trimEnd - 1) === " " && !line.hasStyles(trimEnd - 1)) {
+        trimEnd--;
+      }
+      rows.push(line.slice(currentRowStart, trimEnd));
+      currentRowStart = i;
+      currentRowWidth = 0;
+      continue;
+    }
+    if (currentRowWidth === 0 && wordWidth > columns) {
+      let k = i;
+      let chunkWidth = 0;
+      while (k < j) {
+        const cw = inkCharacterWidth(line.getValue(k));
+        if (chunkWidth + cw > columns && chunkWidth > 0) {
+          rows.push(line.slice(currentRowStart, k));
+          currentRowStart = k;
+          chunkWidth = 0;
+        }
+        chunkWidth += cw;
+        k++;
+      }
+      currentRowWidth = chunkWidth;
+      i = j;
+      isAtStartOfLogicalLine = false;
+    } else {
+      currentRowWidth += wordWidth;
+      i = j;
+      if (firstValue !== " ") {
+        isAtStartOfLogicalLine = false;
+      }
+    }
+  }
+  if (currentRowStart < line.length || rows.length === 0) {
+    rows.push(line.slice(currentRowStart));
+  }
+  return rows;
+};
+const wrapOrTruncateStyledLine = (line, maxWidth, textWrap = "wrap") => {
+  if (textWrap.startsWith("truncate")) {
+    let position = "end";
+    if (textWrap === "truncate-middle") {
+      position = "middle";
+    } else if (textWrap === "truncate-start") {
+      position = "start";
+    }
+    return [truncateStyledLine(line, maxWidth, position)];
+  }
+  return wrapStyledLine(line, maxWidth);
+};
+
+export { wrapOrTruncateStyledLine };

package/dist/react/devtools.d.ts

@@ -0,0 +1,27 @@
+/**
+ * DevTools — optional development overlay for TUI apps.
+ *
+ * Wraps your app and renders a HUD in the bottom-right corner.
+ * Render rate is measured from actual render events (not a timer guess).
+ *
+ * Usage:
+ *   import { DevTools } from '@visulima/tui/react'
+ *
+ *   render(
+ *     <DevTools>
+ *       <MyApp />
+ *     </DevTools>
+ *   )
+ *
+ * Props:
+ *   enabled?   boolean   — show/hide without removing from tree (default: true)
+ *
+ * Future slots: render count, memory usage, custom metrics via props.
+ */
+import React from "react";
+export interface DevToolsProps {
+    children: React.ReactNode;
+    /** Show/hide the HUD without unmounting (default: true) */
+    enabled?: boolean;
+}
+export declare const DevTools: ({ children, enabled }: DevToolsProps) => React.ReactElement;

package/dist/react/focus.d.ts

@@ -0,0 +1,39 @@
+import type { Context } from "react";
+import React from "react";
+export type FocusContextProps = {
+    activate: (id: string) => void;
+    activeId: string | undefined;
+    add: (id: string, options: {
+        autoFocus: boolean;
+    }) => void;
+    deactivate: (id: string) => void;
+    disableFocus: () => void;
+    enableFocus: () => void;
+    focus: (id: string) => void;
+    focusNext: () => void;
+    focusPrevious: () => void;
+    remove: (id: string) => void;
+};
+export declare const FocusContext: Context<FocusContextProps>;
+export declare const FocusProvider: React.FC<{
+    children: React.ReactNode;
+}>;
+export type UseFocusOptions = {
+    autoFocus?: boolean;
+    id?: string;
+    isActive?: boolean;
+};
+export type UseFocusResult = {
+    focus: (id: string) => void;
+    isFocused: boolean;
+};
+export declare const useFocus: ({ autoFocus, id: customId, isActive }?: UseFocusOptions) => UseFocusResult;
+export type UseFocusManagerResult = {
+    activeId: string | undefined;
+    disableFocus: () => void;
+    enableFocus: () => void;
+    focus: (id: string) => void;
+    focusNext: () => void;
+    focusPrevious: () => void;
+};
+export declare const useFocusManager: () => UseFocusManagerResult;

package/dist/react/hooks.d.ts

@@ -0,0 +1,238 @@
+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/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./devtools.d.ts";
+export * from "./focus.d.ts";
+export * from "./hooks.d.ts";
+export type { InlineInstance, Instance, RenderOptions } from "./react/react.d.ts";
+export { render, renderInline } from "./react/react.d.ts";
+export * from "./render-to-string.d.ts";
+export * from "./scene.d.ts";
+export * from "./static.d.ts";

package/dist/react/index.js

@@ -0,0 +1,9 @@
+export { DevTools } from '../packem_shared/DevTools-aMPIsaHx.js';
+export { FocusContext, FocusProvider, useFocus, useFocusManager } from '../packem_shared/FocusContext-D5wFxSRz.js';
+export { TuiContext, measureElement, useApp, useBoxMetrics, useCursor, useInput, useIsScreenReaderEnabled, useMouse, usePaste, useScrollable, useStderr, useStdin, useStdout, useTextInput, useTuiContext, useWindowSize } from '../packem_shared/TuiContext-CqEjMyXd.js';
+export { render, renderInline } from '../packem_shared/render-Bpjhf0lD.js';
+export { renderToString } from '../packem_shared/renderToString-Cfg55DRD.js';
+export { Static } from '../packem_shared/Static-xmD9giJj.js';
+export { LayoutNode } from '../packem_shared/LayoutNode-Cjnsodiy.js';
+export { NAMED_COLORS, applyStyles, resolveColor } from '../packem_shared/NAMED_COLORS-a4QBvb5r.js';
+export { renderTreeToBuffer } from '../packem_shared/renderTreeToBuffer-D3mo7M7m.js';

package/dist/react/layout.d.ts

@@ -0,0 +1,35 @@
+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"]>;
+    /** @deprecated use destroy() */
+    free(): void;
+}
+export {};

package/dist/react/react.d.ts

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

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

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

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

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

package/dist/react/static.d.ts

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