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

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

@@ -1,30 +0,0 @@
-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-form.d.ts

@@ -1,70 +0,0 @@
-export type ValidationResult = string | undefined;
-export type FieldValidator<V> = (value: V, values: Readonly<Record<string, unknown>>) => ValidationResult;
-export type FieldConfig<V = unknown> = {
-    /**
-     * Initial value.
-     */
-    readonly initialValue: V;
-    /**
-     * Optional validator. Return a string to indicate an error; return
-     * `undefined` for valid.
-     */
-    readonly validate?: FieldValidator<V>;
-};
-export type FormSchema = Readonly<Record<string, FieldConfig<never>>>;
-export type FormValues<S extends Readonly<Record<string, FieldConfig>>> = {
-    [K in keyof S]: S[K] extends FieldConfig<infer V> ? V : never;
-};
-export type UseFormOptions<S extends Readonly<Record<string, FieldConfig>>> = {
-    /**
-     * Field declarations.
-     */
-    readonly fields: S;
-    /**
-     * Called on submit if all fields validate.
-     */
-    readonly onSubmit?: (values: FormValues<S>) => void | Promise<void>;
-};
-export type UseFormResult<S extends Readonly<Record<string, FieldConfig>>> = {
-    /**
-     * Map of fieldName -> validation error (if any).
-     */
-    readonly errors: Readonly<Partial<Record<keyof S, string>>>;
-    /**
-     * True while the last `submit()` is in-flight.
-     */
-    readonly isSubmitting: boolean;
-    /**
-     * Reset all fields back to their initial values and clear errors / touched.
-     */
-    readonly reset: () => void;
-    /**
-     * Mark a field as touched. Useful on blur.
-     */
-    readonly setTouched: <K extends keyof S>(name: K, touched?: boolean) => void;
-    /**
-     * Update a single field.
-     */
-    readonly setValue: <K extends keyof S>(name: K, value: FormValues<S>[K]) => void;
-    /**
-     * Trigger validation and call the `onSubmit` option. Returns true if
-     * submission succeeded (all fields valid).
-     */
-    readonly submit: () => Promise<boolean>;
-    /**
-     * Map of fieldName -> boolean. Field is considered touched after the
-     * first `setTouched(name)` or `submit()` invocation.
-     */
-    readonly touched: Readonly<Partial<Record<keyof S, boolean>>>;
-    /**
-     * Current values.
-     */
-    readonly values: FormValues<S>;
-};
-/**
- * Minimal headless form state machine. Tracks values, touched state, errors,
- * and submission in-flight. Pair with `&lt;Form />` for default layout, or wire
- * up your own inputs directly.
- */
-declare const useForm: <S extends Readonly<Record<string, FieldConfig>>>(options: UseFormOptions<S>) => UseFormResult<S>;
-export default useForm;

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

@@ -1,37 +0,0 @@
-import type { Key } from "./use-input.d.ts";
-export type HotkeyDescriptor = {
-    /**
-     * Whether Ctrl must be held.
-     */
-    readonly ctrl?: boolean;
-    /**
-     * Character(s) to match after modifiers, e.g. `"s"`, `"?"`, `"k"`.
-     * Ignored if `name` is set.
-     */
-    readonly input?: string;
-    /**
-     * Whether Meta must be held.
-     */
-    readonly meta?: boolean;
-    /**
-     * Named special key, e.g. `"escape"`, `"return"`, `"tab"`, `"upArrow"`.
-     */
-    readonly name?: keyof Key;
-    /**
-     * Whether Shift must be held.
-     */
-    readonly shift?: boolean;
-};
-export type UseHotkeyOptions = {
-    /**
-     * Disable the binding while keeping the component rendered.
-     * @default true
-     */
-    readonly isActive?: boolean;
-};
-/**
- * Bind a keyboard shortcut to a callback. Accepts either a short string
- * (`"ctrl+s"`, `"?"`, `"escape"`) or a structured descriptor.
- */
-declare const useHotkey: (shortcut: HotkeyDescriptor | string, callback: () => void, options?: UseHotkeyOptions) => void;
-export default useHotkey;

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

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

@@ -1,25 +0,0 @@
-export type UseIntervalOptions = {
-    /**
-     * When false, the timer is paused. Flipping back to true restarts it.
-     * @default true
-     */
-    readonly isActive?: boolean;
-};
-export type UseIntervalResult = {
-    /**
-     * Cancel the currently-running timer. The hook effect will reschedule on
-     * the next re-render if `isActive` remains true.
-     */
-    readonly clear: () => void;
-};
-/**
- * A React hook that invokes `callback` every `interval` ms. The callback
- * reference is captured in a ref so it always sees the latest closure; only
- * `interval` and `isActive` cause the timer to be rebuilt.
- * @param callback Invoked on every tick. Latest closure is captured in a ref.
- * @param interval Tick period in milliseconds. Invalid values pause the timer.
- * @param options Optional `isActive` flag to pause without unmounting.
- * @returns A stable object with a `clear()` method to cancel on demand.
- */
-declare const useInterval: (callback: () => void, interval: number, options?: UseIntervalOptions) => UseIntervalResult;
-export default useInterval;

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

@@ -1,6 +0,0 @@
-/**
- * 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

@@ -1,59 +0,0 @@
-/**
- * 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 | ReadonlyArray<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: ReadonlyArray<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() },
- * ]);
- *
- * &lt;Help bindings={bindings} />
- * ```
- */
-export default function useKeyBindings(handlers: ReadonlyArray<KeyBindingHandler>, options?: UseKeyBindingsOptions): UseKeyBindingsResult;
-export {};

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

@@ -1,26 +0,0 @@
-export type KeyChordStep = string;
-export type UseKeyChordOptions = {
-    /**
-     * Disable the chord while keeping the component rendered.
-     * @default true
-     */
-    readonly isActive?: boolean;
-    /**
-     * Milliseconds of silence after which the partial chord resets.
-     * @default 1000
-     */
-    readonly resetAfter?: number;
-};
-/**
- * Invoke `callback` when the user types the given sequence of keys in order
- * (like Vim's `g d` or Emacs's `C-x C-s`). The chord resets automatically
- * after `resetAfter` ms of silence.
- * @param sequence Ordered list of chord steps. Each step is compared against
- * a canonical key token (e.g. `"g"`, `"space"`, `"ctrl+s"`).
- * @param callback Invoked exactly once per successful chord match. Latest
- * reference is captured in a ref.
- * @param options Optional `isActive` flag and `resetAfter` silence timeout.
- * @returns `void` — chord detection is wired up via `useInput` internally.
- */
-declare const useKeyChord: (sequence: ReadonlyArray<KeyChordStep>, callback: () => void, options?: UseKeyChordOptions) => void;
-export default useKeyChord;

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

@@ -1,41 +0,0 @@
-import type { RefObject } from "react";
-import type { ScrollViewRef } from "../components/scroll/scroll-view.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

@@ -1,44 +0,0 @@
-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-persistent-state.d.ts

@@ -1,56 +0,0 @@
-export type PersistentStorage = {
-    /**
-     * Return the persisted JSON-encoded string for `key`, or `undefined` if
-     * nothing has been stored yet.
-     */
-    readonly read: (key: string) => string | undefined;
-    /**
-     * Persist `value` (a JSON-encoded string) for `key`. Errors are swallowed
-     * by the hook so the UI keeps working in read-only environments.
-     */
-    readonly write: (key: string, value: string) => void;
-};
-export type UsePersistentStateOptions = {
-    /**
-     * Namespace used by the default file storage. Separates keys across
-     * independent applications sharing the user's home directory.
-     * @default "tui"
-     */
-    readonly namespace?: string;
-    /**
-     * Custom storage backend. When omitted, the default is a file on disk at
-     * `~/.cache/visulima-tui/<namespace>.json`.
-     */
-    readonly storage?: PersistentStorage;
-};
-/**
- * In-memory storage shared across all hook instances that use it. Useful in
- * tests and in environments without file access.
- */
-export declare const createMemoryStorage: () => PersistentStorage;
-/**
- * Default file-backed storage. Reads/writes a single JSON object per
- * namespace, keyed by `key`. The directory is created on first write and
- * updates use a temp-file + rename to avoid partial writes if the process
- * crashes mid-write. Errors are forwarded to `process.stderr.write` so they
- * are visible without crashing the UI.
- */
-export declare const createFileStorage: (namespace: string) => PersistentStorage;
-/**
- * `useState` that persists its value through the configured `storage`
- * backend (file on disk by default). Behaves identically to `useState` at
- * the call-site; the writes happen synchronously after each update.
- *
- * **Lifecycle note:** the storage backend (resolved from `options.storage`
- * or a fresh `createFileStorage(namespace)`) is captured once on mount and
- * never replaced. Mutating `options.storage` on subsequent renders has no
- * effect — remount the hook (e.g. via a `key` prop) if you need to swap
- * backends at runtime.
- * @param key Unique identifier within the backend namespace.
- * @param initialValue Value used when the backend has no entry for `key`.
- * @param options Optional storage backend + namespace overrides.
- * @returns A `[value, setValue]` tuple. Writes flush synchronously after
- * the React state update.
- */
-declare const usePersistentState: <T>(key: string, initialValue: T, options?: UsePersistentStateOptions) => readonly [T, (value: T | ((previous: T) => T)) => void];
-export default usePersistentState;

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

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

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

@@ -1,6 +0,0 @@
-import type { Props } from "../components/stderr-context.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

@@ -1,7 +0,0 @@
-import type { Props, PublicProps } from "../components/stdin-context.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

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