@visulima/tui 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/react/index.d.ts

@@ -1,8 +1,519 @@
-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";
+import React, { Context, RefObject, ReactNode } from 'react';
+import { M as MouseEvent, T as TuiApp, c as InputParser, a as InlineOptions } from "../packem_shared/input.d-CgxV2e8U.js";
+import Yoga from 'yoga-layout';
+import 'tseep';
+interface DevToolsProps {
+  children: React.ReactNode;
+  /** Show/hide the HUD without unmounting (default: true) */
+  enabled?: boolean;
+}
+declare const DevTools: ({
+  children,
+  enabled
+}: DevToolsProps) => React.ReactElement;
+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;
+};
+declare const FocusContext: Context<FocusContextProps>;
+declare const FocusProvider: React.FC<{
+  children: React.ReactNode;
+}>;
+type UseFocusOptions = {
+  autoFocus?: boolean;
+  id?: string;
+  isActive?: boolean;
+};
+type UseFocusResult = {
+  focus: (id: string) => void;
+  isFocused: boolean;
+};
+declare const useFocus: ({
+  autoFocus,
+  id: customId,
+  isActive
+}?: UseFocusOptions) => UseFocusResult;
+type UseFocusManagerResult = {
+  activeId: string | undefined;
+  disableFocus: () => void;
+  enableFocus: () => void;
+  focus: (id: string) => void;
+  focusNext: () => void;
+  focusPrevious: () => void;
+};
+declare const useFocusManager: () => UseFocusManagerResult;
+type YogaNode$1 = ReturnType<typeof Yoga.Node.create>;
+declare class LayoutNode {
+  yogaNode: YogaNode$1;
+  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$1["getComputedLayout"]>;
+}
+interface TuiContextProps {
+  app: TuiApp;
+  input: InputParser;
+  writeStderr: (text: string) => void;
+  writeStdout: (text: string) => void;
+}
+declare const TuiContext: Context<TuiContextProps | null>;
+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;
+}
+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.
+*/
+declare const useInput: (handler: InputHandler) => void;
+interface UsePasteOptions {
+  /**
+  * Enable or disable capturing pasted text.
+  * Useful when multiple components use usePaste and only one should be active.
+  * @default true
+  */
+  isActive?: boolean;
+}
+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.
+*/
+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).
+*/
+declare const useTuiContext: () => TuiContextProps;
+/**
+* Access app controls. Returns { exit } for Ink compatibility.
+* exit() triggers a clean shutdown (restores terminal, stops input, exits process).
+*/
+declare const useApp: () => {
+  exit: () => void;
+  quit: () => void;
+};
+/**
+* Returns current terminal dimensions and re-renders on resize (SIGWINCH).
+* Ink-compatible: const { columns, rows } = useWindowSize()
+*/
+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.
+*/
+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.
+*/
+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()
+*/
+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)
+*/
+declare const measureElement: (node: LayoutNode | null) => {
+  height: number;
+  width: number;
+};
+interface BoxMetrics {
+  readonly height: number;
+  readonly left: number;
+  readonly top: number;
+  readonly width: number;
+}
+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)
+*/
+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()
+*/
+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()
+*/
+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.
+*/
+interface UseScrollableOptions {
+  /** Total height of the content in rows — update as content grows */
+  contentHeight: number;
+  /** Height of the visible window in rows */
+  viewportHeight: number;
+}
+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;
+}
+declare const useScrollable: ({
+  contentHeight,
+  viewportHeight
+}: UseScrollableOptions) => UseScrollableResult;
+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'
+*/
+declare const useMouse: (handler: MouseHandler) => void;
+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;
+}
+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.
+*/
+declare const useTextInput: ({
+  initialValue,
+  isActive,
+  onChange,
+  onSubmit
+}?: UseTextInputOptions) => UseTextInputResult;
+/** Ink-compat render options */
+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 */
+interface Instance {
+  /** Internal: direct app access */
+  app: TuiApp;
+  /** Internal: input parser */
+  input: InputParser;
+  rerender: (element: React.ReactElement) => void;
+  unmount: () => void;
+  waitUntilExit: () => Promise<void>;
+}
+declare function render(element: React.ReactElement, options?: RenderOptions): Instance;
+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()
+* ```
+*/
+declare function renderInline(element: React.ReactElement, options?: InlineOptions & {
+  maxFps?: number;
+}): InlineInstance;
+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.
+*/
+declare function renderToString(element: React.ReactElement, options?: RenderToStringOptions): string;
+declare function renderTreeToBuffer(root: LayoutNode, buffer: Uint32Array, cols: number, rows: number): void;
+type YogaNode = ReturnType<typeof Yoga.Node.create>;
+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).
+*/
+declare function resolveColor(color: number | string | undefined): number;
+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;
+};
+declare const applyStyles: (node: YogaNode, style?: Styles, currentStyle?: Styles) => void;
+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>
+* ```
+*/
+declare function Static<T>({
+  children: renderItem,
+  items,
+  style
+}: StaticProps<T>): React.ReactElement;
+export { BoxMetrics, DevTools, DevToolsProps, FocusContext, FocusContextProps, FocusProvider, type InlineInstance, InputHandler, type Instance, Key, LayoutNode, MouseHandler, NAMED_COLORS, PasteHandler, type RenderOptions, RenderToStringOptions, Static, StaticProps, Styles, TuiContext, TuiContextProps, UseBoxMetricsResult, UseFocusManagerResult, UseFocusOptions, UseFocusResult, UsePasteOptions, UseScrollableOptions, UseScrollableResult, UseTextInputOptions, UseTextInputResult, applyStyles, measureElement, render, renderInline, renderToString, renderTreeToBuffer, resolveColor, useApp, useBoxMetrics, useCursor, useFocus, useFocusManager, useInput, useIsScreenReaderEnabled, useMouse, usePaste, useScrollable, useStderr, useStdin, useStdout, useTextInput, useTuiContext, useWindowSize };

package/dist/react/index.js

@@ -1,9 +1 @@
-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';
+import{DevTools as o}from"../packem_shared/DevTools-ClAYpMVI.js";import{FocusContext as u,FocusProvider as s,useFocus as n,useFocusManager as p}from"../packem_shared/FocusContext-Xy0cwJpO.js";import{TuiContext as d,measureElement as f,useApp as l,useBoxMetrics as m,useCursor as a,useInput as i,useIsScreenReaderEnabled as S,useMouse as c,usePaste as T,useScrollable as C,useStderr as F,useStdin as I,useStdout as M,useTextInput as v,useTuiContext as y,useWindowSize as E}from"../packem_shared/TuiContext-BoJvG3NN.js";import{render as g,renderInline as A}from"../packem_shared/render-Dh7HMhK1.js";import{renderToString as D}from"../packem_shared/renderToString-BbQiRHrd.js";import{Static as N}from"../packem_shared/Static-DLynr5pn.js";import{LayoutNode as P}from"../packem_shared/LayoutNode-B8zej4dm.js";import{NAMED_COLORS as w,applyStyles as z,resolveColor as W}from"../packem_shared/NAMED_COLORS-B9fJsYdg.js";import{renderTreeToBuffer as h}from"../packem_shared/renderTreeToBuffer-CZilzyhN.js";export{o as DevTools,u as FocusContext,s as FocusProvider,P as LayoutNode,w as NAMED_COLORS,N as Static,d as TuiContext,z as applyStyles,f as measureElement,g as render,A as renderInline,D as renderToString,h as renderTreeToBuffer,W as resolveColor,l as useApp,m as useBoxMetrics,a as useCursor,n as useFocus,p as useFocusManager,i as useInput,S as useIsScreenReaderEnabled,c as useMouse,T as usePaste,C as useScrollable,F as useStderr,I as useStdin,M as useStdout,v as useTextInput,y as useTuiContext,E as useWindowSize};