@visulima/tui 0.0.1 → 1.0.0-alpha.2

package/dist/ink/hooks/use-console-capture.d.ts

@@ -0,0 +1,43 @@
+export type ConsoleLevel = "debug" | "error" | "info" | "log" | "warn";
+export type ConsoleEntry = {
+    readonly id: number;
+    readonly level: ConsoleLevel;
+    readonly message: string;
+    readonly timestamp: number;
+};
+export type UseConsoleCaptureOptions = {
+    /**
+     * Which console levels to capture.
+     * @default ["log", "info", "warn", "error", "debug"]
+     */
+    readonly filter?: ReadonlyArray<ConsoleLevel>;
+    /**
+     * Enable or disable capture.
+     * @default true
+     */
+    readonly isActive?: boolean;
+    /**
+     * Maximum number of entries to keep in the buffer.
+     * @default 200
+     */
+    readonly maxEntries?: number;
+};
+export type UseConsoleCaptureResult = {
+    /** Clear all captured entries. */
+    readonly clear: () => void;
+    /** Captured console entries (newest last). */
+    readonly entries: ReadonlyArray<ConsoleEntry>;
+};
+/**
+ * Hook that captures console output into a React state buffer.
+ *
+ * **Note:** Only one active `useConsoleCapture` instance should exist at a time.
+ * The `ConsoleOverlay` component uses this hook internally — do not use both
+ * simultaneously unless the hook instance has `isActive: false`.
+ *
+ * ```tsx
+ * const { entries, clear } = useConsoleCapture({ maxEntries: 100 });
+ * ```
+ */
+declare const useConsoleCapture: (options?: UseConsoleCaptureOptions) => UseConsoleCaptureResult;
+export default useConsoleCapture;

package/dist/ink/hooks/use-cursor.d.ts

@@ -0,0 +1,12 @@
+import type { CursorPosition } from "../log-update.d.ts";
+/**
+ * A React hook that returns methods to control the terminal cursor position.
+ *
+ * Setting a cursor position makes the cursor visible at the specified coordinates (relative to the Ink output origin). This is useful for IME (Input Method Editor) support, where the composing character is displayed at the cursor location.
+ *
+ * Pass `undefined` to hide the cursor.
+ */
+declare const useCursor: () => {
+    setCursorPosition: (position: CursorPosition | undefined) => void;
+};
+export default useCursor;

package/dist/ink/hooks/use-focus-manager.d.ts

@@ -0,0 +1,42 @@
+import type { Props } from '../components/FocusContext.d.ts';
+type Output = {
+    /**
+     * The ID of the currently focused component, or `undefined` if no component is focused.
+     * @example
+     * ```tsx
+     * import {Text, useFocusManager} from 'ink';
+     *
+     * const Example = () => {
+     * const {activeId} = useFocusManager();
+     *
+     * return <Text>Focused: {activeId ?? 'none'}</Text>;
+     * };
+     * ```
+     */
+    activeId: Props["activeId"];
+    /**
+     * Disable focus management for all components. The currently active component (if there's one) will lose its focus.
+     */
+    disableFocus: Props["disableFocus"];
+    /**
+     * Enable focus management for all components.
+     */
+    enableFocus: Props["enableFocus"];
+    /**
+     * Switch focus to the element with provided `id`. If there's no element with that `id`, focus is not changed.
+     */
+    focus: Props["focus"];
+    /**
+     * Switch focus to the next focusable component. If there's no active component right now, focus will be given to the first focusable component. If the active component is the last in the list of focusable components, focus will be switched to the first focusable component.
+     */
+    focusNext: Props["focusNext"];
+    /**
+     * Switch focus to the previous focusable component. If there's no active component right now, focus will be given to the first focusable component. If the active component is the first in the list of focusable components, focus will be switched to the last focusable component.
+     */
+    focusPrevious: Props["focusPrevious"];
+};
+/**
+ * A React hook that returns methods to enable or disable focus management for all components or manually switch focus to the next or previous components.
+ */
+declare const useFocusManager: () => Output;
+export default useFocusManager;

package/dist/ink/hooks/use-focus.d.ts

@@ -0,0 +1,30 @@
+type Input = {
+    /**
+     * Auto-focus this component if there's no active (focused) component right now.
+     */
+    autoFocus?: boolean;
+    /**
+     * Assign an ID to this component, so it can be programmatically focused with `focus(id)`.
+     */
+    id?: string;
+    /**
+     * Enable or disable this component's focus, while still maintaining its position in the list of focusable components.
+     */
+    isActive?: boolean;
+};
+type Output = {
+    /**
+     * Allows focusing a specific element with the provided `id`.
+     */
+    focus: (id: string) => void;
+    /**
+     * Determines whether this component is focused.
+     */
+    isFocused: boolean;
+};
+/**
+ * A React hook that returns focus state and focus controls for the current component.
+ * A component that uses the `useFocus` hook becomes "focusable" to Ink, so when the user presses <kbd>Tab</kbd>, Ink will switch focus to this component. If there are multiple components that execute the `useFocus` hook, focus will be given to them in the order in which these components are rendered.
+ */
+declare const useFocus: ({ autoFocus, id: customId, isActive }?: Input) => Output;
+export default useFocus;

package/dist/ink/hooks/use-input.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Handy information about a key that was pressed.
+ */
+export type Key = {
+    /**
+     * Backspace key was pressed.
+     */
+    backspace: boolean;
+    /**
+     * Caps Lock is active.
+     *
+     * Only available with kitty keyboard protocol.
+     */
+    capsLock: boolean;
+    /**
+     * Ctrl key was pressed.
+     */
+    ctrl: boolean;
+    /**
+     * Delete key was pressed.
+     */
+    delete: boolean;
+    /**
+     * Down arrow key was pressed.
+     */
+    downArrow: boolean;
+    /**
+     * End key was pressed.
+     */
+    end: boolean;
+    /**
+     * Escape key was pressed.
+     */
+    escape: boolean;
+    /**
+     * Event type for key events.
+     *
+     * Only available with kitty keyboard protocol.
+     */
+    eventType?: "press" | "repeat" | "release";
+    /**
+     * Home key was pressed.
+     */
+    home: boolean;
+    /**
+     * Hyper key was pressed.
+     *
+     * Only available with kitty keyboard protocol.
+     */
+    hyper: boolean;
+    /**
+     * Left arrow key was pressed.
+     */
+    leftArrow: boolean;
+    /**
+     * [Meta key](https://en.wikipedia.org/wiki/Meta_key) was pressed.
+     */
+    meta: boolean;
+    /**
+     * Num Lock is active.
+     *
+     * Only available with kitty keyboard protocol.
+     */
+    numLock: boolean;
+    /**
+     * Page Down key was pressed.
+     */
+    pageDown: boolean;
+    /**
+     * Page Up key was pressed.
+     */
+    pageUp: boolean;
+    /**
+     * Return (Enter) key was pressed.
+     */
+    return: boolean;
+    /**
+     * Right arrow key was pressed.
+     */
+    rightArrow: boolean;
+    /**
+     * Shift key was pressed.
+     */
+    shift: boolean;
+    /**
+     * Super key (Cmd on Mac, Win on Windows) was pressed.
+     *
+     * Only available with kitty keyboard protocol.
+     */
+    super: boolean;
+    /**
+     * Tab key was pressed.
+     */
+    tab: boolean;
+    /**
+     * Up arrow key was pressed.
+     */
+    upArrow: boolean;
+};
+type Handler = (input: string, key: Key) => void;
+type Options = {
+    /**
+     * Enable IME (Input Method Editor) composition buffering for Vietnamese, Chinese,
+     * Japanese, Korean, and other non-ASCII input methods.
+     * @default true
+     */
+    imeEnabled?: boolean;
+    /**
+     * Timeout in milliseconds to wait before flushing IME composition buffer.
+     * @default 50
+     */
+    imeTimeout?: number;
+    /**
+     * Enable or disable capturing of user input. Useful when there are multiple `useInput` hooks used at once to avoid handling the same input several times.
+     * @default true
+     */
+    isActive?: boolean;
+};
+/**
+ * A React hook that returns `void` and handles user input.
+ * It's a more convenient alternative to using `StdinContext` and listening for
+ * `data` events. The callback you pass to `useInput` is called for typed
+ * characters and key events.
+ *
+ * Bracketed paste payloads belong to `usePaste`. If no `usePaste` handler is
+ * active, Ink still forwards bracketed paste text to `useInput` for backward
+ * compatibility, but that fallback is deprecated and will be removed in the next
+ * major version.
+ *
+ * ```
+ * import {useInput} from 'ink';
+ *
+ * const UserInput = () => {
+ * useInput((input, key) => {
+ * if (input === 'q') {
+ * // Exit program
+ * }
+ *
+ * if (key.leftArrow) {
+ * // Left arrow key pressed
+ * }
+ * });
+ *
+ * return …
+ * };
+ * ```
+ */
+declare const useInput: (inputHandler: Handler, options?: Options) => void;
+export default useInput;

package/dist/ink/hooks/use-is-screen-reader-enabled.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A React hook that returns whether a screen reader is enabled.
+ * This is useful when you want to render different output for screen readers.
+ */
+declare const useIsScreenReaderEnabled: () => boolean;
+export default useIsScreenReaderEnabled;

package/dist/ink/hooks/use-key-bindings.d.ts

@@ -0,0 +1,61 @@
+/**
+ * A single key binding definition.
+ */
+export type KeyBinding = {
+    /** Human-readable description shown in Help. */
+    readonly description: string;
+    /**
+     * Whether this binding is active.
+     *
+     * @default true
+     */
+    readonly enabled?: boolean;
+    /** Optional group name for organizing in the Help component's full mode. */
+    readonly group?: string;
+    /**
+     * Key(s) that trigger this binding.
+     *
+     * A string can be:
+     * - A single character: `"q"`, `"a"`, `" "` (space)
+     * - A `Key` boolean field name: `"return"`, `"escape"`, `"upArrow"`, `"leftArrow"`, etc.
+     * - A modifier combo: `"ctrl+c"`, `"meta+s"` (modifier + character)
+     *
+     * Provide an array to match multiple keys for the same action.
+     */
+    readonly key: string | readonly string[];
+};
+/**
+ * A binding paired with its handler function.
+ */
+export type KeyBindingHandler = {
+    readonly binding: KeyBinding;
+    readonly handler: () => void;
+};
+type UseKeyBindingsOptions = {
+    /**
+     * Whether keyboard input is captured.
+     *
+     * @default true
+     */
+    readonly isActive?: boolean;
+};
+type UseKeyBindingsResult = {
+    /** The enabled bindings, suitable for passing to the Help component. */
+    readonly bindings: readonly KeyBinding[];
+};
+/**
+ * Declarative keybinding hook. Registers multiple key bindings with handlers
+ * and returns the enabled bindings for display in a Help component.
+ *
+ * ```tsx
+ * const { bindings } = useKeyBindings([
+ *   { binding: { key: "q", description: "Quit" }, handler: () => exit() },
+ *   { binding: { key: ["upArrow", "k"], description: "Move up" }, handler: () => moveUp() },
+ *   { binding: { key: "ctrl+s", description: "Save" }, handler: () => save() },
+ * ]);
+ *
+ * <Help bindings={bindings} />
+ * ```
+ */
+export default function useKeyBindings(handlers: readonly KeyBindingHandler[], options?: UseKeyBindingsOptions): UseKeyBindingsResult;
+export {};

package/dist/ink/hooks/use-linked-scroll.d.ts

@@ -0,0 +1,41 @@
+import type { RefObject } from "react";
+import type { ScrollViewRef } from "../components/scroll/ScrollView.d.ts";
+export type UseLinkedScrollReturn = {
+    /**
+     * Callback to pass to ScrollView's `onScroll` prop.
+     * Broadcasts the scroll position to all linked instances.
+     */
+    onScroll: (scrollOffset: number) => void;
+    /**
+     * Ref to attach to the ScrollView component.
+     * Used internally to call `scrollTo()` when other instances scroll.
+     */
+    ref: RefObject<ScrollViewRef | null>;
+};
+export type LinkedScrollGroup = {
+    /**
+     * Hook that returns a ref and onScroll callback for linking a ScrollView
+     * to this group. Call once per ScrollView instance.
+     */
+    useLinkedScroll: () => UseLinkedScrollReturn;
+};
+/**
+ * Creates a linked scroll group that synchronizes scroll position
+ * across multiple ScrollView instances.
+ * @example
+ * ```tsx
+ * const group = createLinkedScrollGroup();
+ *
+ * const PanelA = () => {
+ *     const { ref, onScroll } = group.useLinkedScroll();
+ *     return <ScrollView ref={ref} onScroll={onScroll}>...</ScrollView>;
+ * };
+ *
+ * const PanelB = () => {
+ *     const { ref, onScroll } = group.useLinkedScroll();
+ *     return <ScrollView ref={ref} onScroll={onScroll}>...</ScrollView>;
+ * };
+ * ```
+ */
+declare const createLinkedScrollGroup: () => LinkedScrollGroup;
+export default createLinkedScrollGroup;

package/dist/ink/hooks/use-paste.d.ts

@@ -0,0 +1,44 @@
+type Options = {
+    /**
+     * Enable or disable the paste handler. Useful when multiple components use `usePaste` and only one should be active at a time.
+     * @default true
+     */
+    isActive?: boolean;
+};
+/**
+ * A React hook that calls `handler` whenever the user pastes text in the
+ * terminal. Bracketed paste mode (`\x1b[?2004h`) is automatically enabled while
+ * the hook is active, so pasted text arrives as a single string rather than being
+ * misinterpreted as individual key presses.
+ *
+ * `usePaste` is the dedicated API for paste blobs. `usePaste` and `useInput` can
+ * be used together in the same component; they operate on separate event
+ * channels, so paste content is never forwarded to `useInput` handlers while a
+ * `usePaste` handler is active.
+ *
+ * If no `usePaste` handler is active, Ink still forwards bracketed paste text to
+ * `useInput` for backward compatibility. That fallback is deprecated and will be
+ * removed in the next major version.
+ *
+ * ```
+ * import {useInput, usePaste} from 'ink';
+ *
+ * const MyInput = () => {
+ *   useInput((input, key) => {
+ *     // Only receives typed characters and key events, not pasted text.
+ *     if (key.return) {
+ *       // Submit
+ *     }
+ *   });
+ *
+ *   usePaste((text) => {
+ *     // Receives the full pasted string, including newlines.
+ *     console.log('Pasted:', text);
+ *   });
+ *
+ *   return …
+ * };
+ * ```
+ */
+declare const usePaste: (handler: (text: string) => void, options?: Options) => void;
+export default usePaste;

package/dist/ink/hooks/use-scroll-acceleration.d.ts

@@ -0,0 +1,47 @@
+export type UseScrollAccelerationOptions = {
+    /**
+     * Velocity multiplier per rapid scroll event.
+     * @default 1.5
+     */
+    readonly acceleration?: number;
+    /**
+     * Velocity decay factor per tick (0-1). Lower = faster stop.
+     * @default 0.92
+     */
+    readonly decayRate?: number;
+    /**
+     * Enable or disable acceleration.
+     * @default true
+     */
+    readonly isActive?: boolean;
+    /**
+     * Maximum velocity in lines per tick.
+     * @default 20
+     */
+    readonly maxVelocity?: number;
+    /**
+     * Callback invoked with the scroll delta (signed integer lines) on each tick.
+     */
+    readonly onScroll?: (delta: number) => void;
+};
+export type UseScrollAccelerationResult = {
+    /** Handle a discrete scroll event (from mouse wheel or keyboard). */
+    readonly handleScroll: (direction: "down" | "up") => void;
+    /** Whether momentum is still active (coasting after last input). */
+    readonly isCoasting: boolean;
+    /** Current velocity (positive = down, negative = up). */
+    readonly velocity: number;
+};
+/**
+ * Hook providing scroll acceleration with momentum physics.
+ *
+ * ```tsx
+ * const { handleScroll } = useScrollAcceleration({
+ *     onScroll: (delta) => scrollViewRef.current?.scrollBy(delta),
+ * });
+ *
+ * useMouseAction(); // call handleScroll("up") or handleScroll("down") on scroll events
+ * ```
+ */
+declare const useScrollAcceleration: (options?: UseScrollAccelerationOptions) => UseScrollAccelerationResult;
+export default useScrollAcceleration;

package/dist/ink/hooks/use-scroll-input.d.ts

@@ -0,0 +1,34 @@
+export type UseScrollInputOptions = {
+    /**
+     * Returns the current viewport height in lines. Called on each key event
+     * so the value is always fresh (avoids stale-closure issues with refs).
+     */
+    getViewportHeight: () => number;
+    /**
+     * Enable or disable scroll input handling.
+     * @default true
+     */
+    isActive?: boolean;
+    /**
+     * Scroll by a relative delta (in lines).
+     */
+    scrollBy: (delta: number) => void;
+    /**
+     * Jump to the bottom of the content.
+     */
+    scrollToBottom: () => void;
+    /**
+     * Jump to the top of the content.
+     */
+    scrollToTop: () => void;
+    /**
+     * Enable vim-style keybindings (j/k/g/G/u/d).
+     * @default false
+     */
+    vimBindings?: boolean;
+};
+export type UseScrollInputReturn = {
+    isFocused: boolean;
+};
+declare const useScrollInput: (options: UseScrollInputOptions) => UseScrollInputReturn;
+export default useScrollInput;

package/dist/ink/hooks/use-stderr.d.ts

@@ -0,0 +1,6 @@
+import type { Props } from "../components/StderrContext.d.ts";
+/**
+ * A React hook that returns the stderr stream.
+ */
+declare const useStderr: () => Props;
+export default useStderr;

package/dist/ink/hooks/use-stdin.d.ts

@@ -0,0 +1,7 @@
+import type { Props, PublicProps } from "../components/StdinContext.d.ts";
+/**
+ * A React hook that returns the stdin stream and stdin-related utilities.
+ */
+declare const useStdin: () => PublicProps;
+export declare const useStdinContext: () => Props;
+export default useStdin;

package/dist/ink/hooks/use-stdout.d.ts

@@ -0,0 +1,6 @@
+import type { Props } from "../components/StdoutContext.d.ts";
+/**
+ * A React hook that returns the stdout stream where Ink renders your app.
+ */
+declare const useStdout: () => Props;
+export default useStdout;

package/dist/ink/hooks/use-stopwatch.d.ts

@@ -0,0 +1,40 @@
+export type UseStopwatchOptions = {
+    /**
+     * Whether to start counting immediately.
+     *
+     * @default false
+     */
+    readonly autoStart?: boolean;
+    /**
+     * Tick interval in milliseconds.
+     *
+     * @default 1000
+     */
+    readonly interval?: number;
+};
+export type UseStopwatchResult = {
+    /** Milliseconds elapsed since start (or last reset). */
+    readonly elapsed: number;
+    /** Whether the stopwatch is currently running. */
+    readonly isRunning: boolean;
+    /** Capture the current elapsed time as a lap. Returns the elapsed value. */
+    readonly lap: () => number;
+    /** Accumulated lap times. */
+    readonly laps: readonly number[];
+    /** Reset elapsed to 0, clear laps, and stop the stopwatch. */
+    readonly reset: () => void;
+    /** Start counting. */
+    readonly start: () => void;
+    /** Pause counting. */
+    readonly stop: () => void;
+    /** Toggle between running and stopped. */
+    readonly toggle: () => void;
+};
+/**
+ * A count-up stopwatch hook built on `useAnimation`.
+ *
+ * ```tsx
+ * const { elapsed, isRunning, start, stop, reset, lap, laps } = useStopwatch();
+ * ```
+ */
+export default function useStopwatch(options?: UseStopwatchOptions): UseStopwatchResult;

package/dist/ink/hooks/use-terminal-palette.d.ts

@@ -0,0 +1,19 @@
+import type { TerminalPalette } from "../terminal-palette.d.ts";
+export type UseTerminalPaletteResult = {
+    readonly isLoading: boolean;
+    readonly isSupported: boolean;
+    readonly palette: Partial<TerminalPalette> | null;
+};
+/**
+ * Hook that queries the terminal for its current color palette.
+ * Returns the detected palette colors or null if not yet loaded.
+ *
+ * ```tsx
+ * const { palette, isLoading } = useTerminalPalette();
+ * if (palette?.background) {
+ *     console.log("Terminal background:", palette.background);
+ * }
+ * ```
+ */
+declare const useTerminalPalette: () => UseTerminalPaletteResult;
+export default useTerminalPalette;

package/dist/ink/hooks/use-text-buffer.d.ts

@@ -0,0 +1,42 @@
+export type CursorPosition = {
+    readonly col: number;
+    readonly line: number;
+};
+export type TextBufferState = {
+    readonly anchor: CursorPosition | null;
+    readonly cursor: CursorPosition;
+    readonly lines: ReadonlyArray<string>;
+};
+export type UseTextBufferResult = {
+    readonly anchor: CursorPosition | null;
+    readonly clearSelection: () => void;
+    readonly cursor: CursorPosition;
+    readonly deleteBack: () => void;
+    readonly deleteForward: () => void;
+    readonly deleteLine: () => void;
+    readonly deleteSelection: () => void;
+    readonly deleteToLineEnd: () => void;
+    readonly deleteToLineStart: () => void;
+    readonly deleteWord: () => void;
+    readonly getSelectedText: () => string;
+    readonly hasSelection: () => boolean;
+    readonly insert: (text: string) => void;
+    readonly lines: ReadonlyArray<string>;
+    readonly moveCursor: (direction: "down" | "left" | "right" | "up", selecting?: boolean) => void;
+    readonly moveToEnd: (selecting?: boolean) => void;
+    readonly moveToLineEnd: (selecting?: boolean) => void;
+    readonly moveToLineStart: (selecting?: boolean) => void;
+    readonly moveToStart: (selecting?: boolean) => void;
+    readonly newline: () => void;
+    readonly redo: () => void;
+    readonly replaceSelection: (text: string) => void;
+    readonly selectAll: () => void;
+    readonly setValue: (value: string) => void;
+    readonly undo: () => void;
+    readonly value: string;
+};
+/**
+ * Hook managing a multi-line text buffer with cursor, selection, and undo/redo.
+ */
+declare const useTextBuffer: (initialValue?: string) => UseTextBufferResult;
+export default useTextBuffer;