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

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

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

@@ -0,0 +1,25 @@
+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-key-bindings.d.ts

@@ -6,7 +6,6 @@ export type KeyBinding = {
     readonly description: string;
     /**
      * Whether this binding is active.
-     *
      * @default true
      */
     readonly enabled?: boolean;
@@ -22,7 +21,7 @@ export type KeyBinding = {
      *
      * Provide an array to match multiple keys for the same action.
      */
-    readonly key: string | readonly string[];
+    readonly key: string | ReadonlyArray<string>;
 };
 /**
  * A binding paired with its handler function.
@@ -34,14 +33,13 @@ export type KeyBindingHandler = {
 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[];
+    readonly bindings: ReadonlyArray<KeyBinding>;
 };
 /**
  * Declarative keybinding hook. Registers multiple key bindings with handlers
@@ -54,8 +52,8 @@ type UseKeyBindingsResult = {
  *   { binding: { key: "ctrl+s", description: "Save" }, handler: () => save() },
  * ]);
  *
- * <Help bindings={bindings} />
+ * &lt;Help bindings={bindings} />
  * ```
  */
-export default function useKeyBindings(handlers: readonly KeyBindingHandler[], options?: UseKeyBindingsOptions): UseKeyBindingsResult;
+export default function useKeyBindings(handlers: ReadonlyArray<KeyBindingHandler>, options?: UseKeyBindingsOptions): UseKeyBindingsResult;
 export {};

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

@@ -0,0 +1,26 @@
+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,5 +1,5 @@
 import type { RefObject } from "react";
-import type { ScrollViewRef } from "../components/scroll/ScrollView.d.ts";
+import type { ScrollViewRef } from "../components/scroll/scroll-view.d.ts";
 export type UseLinkedScrollReturn = {
     /**
      * Callback to pass to ScrollView's `onScroll` prop.

package/dist/ink/hooks/use-persistent-state.d.ts

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

@@ -1,4 +1,4 @@
-import type { Props } from "../components/StderrContext.d.ts";
+import type { Props } from "../components/stderr-context.d.ts";
 /**
  * A React hook that returns the stderr stream.
  */

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

@@ -1,4 +1,4 @@
-import type { Props, PublicProps } from "../components/StdinContext.d.ts";
+import type { Props, PublicProps } from "../components/stdin-context.d.ts";
 /**
  * A React hook that returns the stdin stream and stdin-related utilities.
  */

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

@@ -1,4 +1,4 @@
-import type { Props } from "../components/StdoutContext.d.ts";
+import type { Props } from "../components/stdout-context.d.ts";
 /**
  * A React hook that returns the stdout stream where Ink renders your app.
  */

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

@@ -1,13 +1,11 @@
 export type UseStopwatchOptions = {
     /**
      * Whether to start counting immediately.
-     *
      * @default false
      */
     readonly autoStart?: boolean;
     /**
      * Tick interval in milliseconds.
-     *
      * @default 1000
      */
     readonly interval?: number;
@@ -20,7 +18,7 @@ export type UseStopwatchResult = {
     /** Capture the current elapsed time as a lap. Returns the elapsed value. */
     readonly lap: () => number;
     /** Accumulated lap times. */
-    readonly laps: readonly number[];
+    readonly laps: ReadonlyArray<number>;
     /** Reset elapsed to 0, clear laps, and stop the stopwatch. */
     readonly reset: () => void;
     /** Start counting. */

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

@@ -0,0 +1,24 @@
+export type UseTimeoutOptions = {
+    /**
+     * When false, the timer never starts. Flipping to true restarts it.
+     * @default true
+     */
+    readonly isActive?: boolean;
+};
+export type UseTimeoutResult = {
+    /**
+     * Cancel the pending timer (no-op if already fired or never scheduled).
+     */
+    readonly cancel: () => void;
+    /**
+     * Restart the timer from now with the current delay.
+     */
+    readonly reset: () => void;
+};
+/**
+ * A React hook that fires `callback` once after `delay` ms. Changing `delay`
+ * or toggling `isActive` reschedules the timer from zero. Call `reset()` to
+ * restart on demand.
+ */
+declare const useTimeout: (callback: () => void, delay: number, options?: UseTimeoutOptions) => UseTimeoutResult;
+export default useTimeout;

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

@@ -1,7 +1,6 @@
 export type UseTimerOptions = {
     /**
      * Whether to start the timer immediately.
-     *
      * @default false
      */
     readonly autoStart?: boolean;
@@ -11,7 +10,6 @@ export type UseTimerOptions = {
     readonly duration: number;
     /**
      * Tick interval in milliseconds.
-     *
      * @default 1000
      */
     readonly interval?: number;