@visulima/tui 1.0.0-alpha.9 → 1.0.1

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

@@ -0,0 +1,41 @@
+type Options = {
+  /**
+  * Time between ticks in milliseconds.
+  * @default 100
+  */
+  readonly interval?: number;
+  /**
+  * Whether the animation is running. When set to `false`, the animation stops.
+  * When toggled back to `true`, all values reset to `0`.
+  * @default true
+  */
+  readonly isActive?: boolean;
+};
+type AnimationResult = {
+  /**
+  * Time in milliseconds since the previous rendered tick. Accounts for throttled renders.
+  * Useful for physics-based or velocity-driven motion: `position += speed * delta`.
+  */
+  readonly delta: number;
+  /**
+  * Discrete counter that increments by 1 each interval.
+  * Useful for indexed sequences like spinner frames.
+  */
+  readonly frame: number;
+  /**
+  * Resets `frame`, `time`, and `delta` to `0` and restarts timing from the current moment.
+  * Useful for one-shot animations triggered by events.
+  */
+  readonly reset: () => void;
+  /**
+  * Total elapsed time in milliseconds since the animation started or was last reset.
+  * Useful for continuous math-based animations like sine waves: `Math.sin(time / 1000 * Math.PI * 2)`.
+  */
+  readonly time: number;
+};
+/**
+* A React hook that drives animations. Returns a frame counter, elapsed time, frame delta, and a reset function.
+* All animations share a single timer internally, so multiple animated components consolidate into one render cycle.
+*/
+declare function useAnimation(options?: Options): AnimationResult;
+export { AnimationResult, useAnimation as default, useAnimation };

package/dist/ink/hooks/use-animation.js

@@ -0,0 +1 @@
+import{useContext as S,useState as A,useRef as o,useCallback as D,useLayoutEffect as M}from"react";import{e as E}from"../../packem_shared/animation-context-DW3p-vpk.js";const p=100,F=2147483647,m={delta:0,frame:0,time:0};function R(i){const{interval:x=p,isActive:t=!0}=i??{},e=L(x),{renderThrottleMs:s,subscribe:l}=S(E),[r,I]=A(0),[C,v]=A(m),a=o(0),c=o(0),b=o({isActive:t,resetKey:r,safeInterval:e}),f=b.current,K=t&&(e!==f.safeInterval||!f.isActive||r!==f.resetKey),d=D(()=>{I(n=>n+1)},[]);return M(()=>{if(!t)return;v(m);let n=0;const{startTime:h,unsubscribe:T}=l(u=>{if(s>0&&u<a.current)return;const y=u-n,k=u-c.current;c.current=u,a.current=u+s,v({delta:k,frame:Math.floor(y/e),time:y})},e);return n=h,c.current=h,a.current=n+s,T},[e,t,l,s,r]),M(()=>{b.current={isActive:t,resetKey:r,safeInterval:e}},[t,e,r]),K?{...m,reset:d}:{...C,reset:d}}function L(i){return Number.isFinite(i)?Math.min(F,Math.max(1,i)):p}export{R as default,R as useAnimation};

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

@@ -0,0 +1,38 @@
+import 'react';
+type Props = {
+  /**
+  * Exit (unmount) the whole Ink app.
+  *
+  * - `exit()` — resolves `waitUntilExit()` with `undefined`.
+  * - `exit(new Error('…'))` — rejects `waitUntilExit()` with the error.
+  * - `exit(value)` — resolves `waitUntilExit()` with `value`.
+  */
+  readonly exit: (errorOrResult?: Error | unknown) => void;
+  /**
+  * Returns a promise that settles after pending render output is flushed to stdout.
+  * @example
+  * ```jsx
+  * import {useEffect} from 'react';
+  * import {useApp} from '@visulima/tui/hooks/use-app';
+  
+  const Example = () => {
+  const {waitUntilRenderFlush} = useApp();
+  
+  useEffect(() => {
+  void (async () => {
+  await waitUntilRenderFlush();
+  runNextCommand();
+  })();
+  }, [waitUntilRenderFlush]);
+  
+  return …;
+  };
+  ```
+  */
+  readonly waitUntilRenderFlush: () => Promise<void>;
+};
+/**
+* A React hook that returns app lifecycle methods like `exit()` and `waitUntilRenderFlush()`.
+*/
+declare const useApp: () => Props;
+export { type Props as AppProps, useApp as default, useApp };

package/dist/ink/hooks/use-app.js

@@ -0,0 +1 @@
+import{useContext as t}from"react";import{t as o}from"../../packem_shared/app-context-BVpKlG1z.js";const r=()=>t(o);export{r as default,r as useApp};

package/dist/ink/hooks/use-box-metrics.d.ts

@@ -0,0 +1,66 @@
+import { RefObject } from 'react';
+import { D as DOMElement } from "../../packem_shared/dom.d-B4kXbaVY.js";
+import 'yoga-layout';
+import "../../packem_shared/cursor-helpers.d-BONB9tky.js";
+import '@visulima/colorize';
+import 'cli-boxes';
+import "../../packem_shared/styles.d-cMo36xQz.js";
+import 'type-fest';
+/**
+* Metrics of a box element.
+*
+* All positions are relative to the element's parent.
+*/
+type BoxMetrics = {
+  /**
+  * Element height.
+  */
+  readonly height: number;
+  /**
+  * Distance from the left edge of the parent.
+  */
+  readonly left: number;
+  /**
+  * Distance from the top edge of the parent.
+  */
+  readonly top: number;
+  /**
+  * Element width.
+  */
+  readonly width: number;
+};
+type UseBoxMetricsResult = BoxMetrics & {
+  /**
+  * Whether the currently tracked element has been measured in the latest layout pass.
+  */
+  readonly hasMeasured: boolean;
+};
+/**
+* A React hook that returns the current layout metrics for a tracked box element.
+* It updates when layout changes (for example terminal resize, sibling/content changes, or position changes).
+*
+* The hook returns `{width: 0, height: 0, left: 0, top: 0}` until the first layout pass completes. It also returns zeros when the tracked ref is detached.
+*
+* Use `hasMeasured` to detect when the currently tracked element has been measured.
+* @example
+* ```tsx
+import {useRef} from 'react';
+import {Box} from '@visulima/tui/components/box';
+import {Text} from '@visulima/tui/components/text';
+import {useBoxMetrics} from '@visulima/tui/hooks/use-box-metrics';
+
+const Example = () => {
+const ref = useRef(null);
+const {width, height, left, top, hasMeasured} = useBoxMetrics(ref);
+return (
+<Box ref={ref}>
+<Text>
+{hasMeasured ? `${width}x${height} at ${left},${top}` : 'Measuring...'}
+</Text>
+</Box>
+);
+};
+```
+*/
+declare const useBoxMetrics: (ref: RefObject<DOMElement | null>) => UseBoxMetricsResult;
+export { BoxMetrics, UseBoxMetricsResult, useBoxMetrics as default, useBoxMetrics };

package/dist/ink/hooks/use-box-metrics.js

@@ -0,0 +1 @@
+import{useState as n,useCallback as h,useEffect as u,useMemo as p}from"react";import{a as l}from"../../packem_shared/dom-rphpG0kf.js";const i={height:0,left:0,top:0,width:0},d=t=>{if(t)return t.parentNode?d(t.parentNode):t.nodeName==="ink-root"?t:void 0},N=t=>{const[o,c]=n(i),[a,f]=n(!1),s=h(()=>{const e=t.current?.yogaNode?.getComputedLayout()??i;c(r=>r.width!==e.width||r.height!==e.height||r.left!==e.left||r.top!==e.top?e:r),f(!!t.current)},[t]);return u(s),u(()=>{const e=d(t.current);if(e)return l(e,s)}),p(()=>({...o,hasMeasured:a}),[o,a])};export{N as default,N as useBoxMetrics};

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

@@ -0,0 +1,30 @@
+import { C as ClipboardTarget } from "../../packem_shared/clipboard.d-D6lZTQ21.js";
+import 'node:stream';
+type UseClipboardOptions = {
+  /**
+  * The clipboard target to write to.
+  * @default "c"
+  */
+  readonly target?: ClipboardTarget;
+};
+type UseClipboardResult = {
+  /**
+  * Copy text to the system clipboard.
+  * No-op if the terminal does not support OSC 52.
+  */
+  readonly copy: (text: string) => void;
+  /**
+  * Whether the current terminal supports OSC 52 clipboard operations.
+  */
+  readonly isSupported: boolean;
+};
+/**
+* Hook that provides clipboard write access via OSC 52.
+*
+* ```tsx
+* const { copy, isSupported } = useClipboard();
+* copy("Hello, clipboard!");
+* ```
+*/
+declare const useClipboard: (options?: UseClipboardOptions) => UseClipboardResult;
+export { UseClipboardOptions, UseClipboardResult, useClipboard as default, useClipboard };

package/dist/ink/hooks/use-clipboard.js

@@ -0,0 +1 @@
+import{useMemo as e,useCallback as a}from"react";import{isOsc52Supported as c,writeOsc52 as i}from"../../packem_shared/clearOsc52-BUpnQOav.js";import m from"./use-stdout.js";const n=(p={})=>{const{target:r="c"}=p,{stdout:o}=m(),t=e(()=>c(),[]),s=a(u=>{!t||!o||i(o,u,r)},[t,o,r]);return e(()=>({copy:s,isSupported:t}),[s,t])};export{n as default,n as useClipboard};

package/dist/ink/hooks/use-color-blindness.d.ts

@@ -0,0 +1,33 @@
+import { C as ColorBlindnessType, a as ColorMatrix } from "../../packem_shared/color-matrix.d-DSXLsB64.js";
+type UseColorBlindnessOptions = {
+  /**
+  * Use compensation mode (shift colors to distinguishable range)
+  * instead of simulation mode (show how colors appear to affected users).
+  * Not available for achromatopsia.
+  * @default false
+  */
+  readonly compensate?: boolean;
+  /**
+  * Type of color vision deficiency to simulate or compensate for.
+  * @default "none"
+  */
+  readonly mode?: ColorBlindnessType | "none";
+};
+type UseColorBlindnessResult = {
+  /** Whether a transform is active (mode is not "none"). */
+  readonly isActive: boolean;
+  /** The active color matrix. */
+  readonly matrix: ColorMatrix;
+  /** Transform a hex color string through the active matrix. */
+  readonly transformColor: (hex: string) => string;
+};
+/**
+* Hook for color blindness simulation and compensation.
+*
+* ```tsx
+* const { transformColor } = useColorBlindness({ mode: "deuteranopia" });
+* <Text color={transformColor("#ff0000")}>This text</Text>
+* ```
+*/
+declare const useColorBlindness: (options?: UseColorBlindnessOptions) => UseColorBlindnessResult;
+export { UseColorBlindnessOptions, UseColorBlindnessResult, useColorBlindness as default, useColorBlindness };

package/dist/ink/hooks/use-color-blindness.js

@@ -0,0 +1 @@
+import{useMemo as a,useCallback as i}from"react";import{IDENTITY_MATRIX as l,COLOR_BLINDNESS_COMPENSATION as I,COLOR_BLINDNESS_SIMULATION as N,transformHexColor as C}from"../../packem_shared/COLOR_BLINDNESS_COMPENSATION-Ilnoyeqc.js";const f=(m={})=>{const{compensate:n=!1,mode:o="none"}=m,e=a(()=>o==="none"?l:n&&o!=="achromatopsia"?I[o]:N[o],[o,n]),r=o!=="none",s=i(t=>r?C(t,e):t,[r,e]);return a(()=>({isActive:r,matrix:e,transformColor:s}),[r,e,s])};export{f as default,f as useColorBlindness};

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

@@ -0,0 +1,43 @@
+type ConsoleLevel = "debug" | "error" | "info" | "log" | "warn";
+type ConsoleEntry = {
+  readonly id: number;
+  readonly level: ConsoleLevel;
+  readonly message: string;
+  readonly timestamp: number;
+};
+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;
+};
+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 { ConsoleEntry, ConsoleLevel, UseConsoleCaptureOptions, UseConsoleCaptureResult, useConsoleCapture as default, useConsoleCapture };

package/dist/ink/hooks/use-console-capture.js

@@ -0,0 +1 @@
+import{useState as w,useRef as x,useMemo as g,useEffect as A,useCallback as C}from"react";const c=["log","info","warn","error","debug"],b=(p={})=>{const{filter:n=c,isActive:a=!0,maxEntries:s=200}=p,[i,u]=w([]),y=x(0),d=Array.isArray(n)?n.toSorted().join(","):"",l=g(()=>n,[d]);A(()=>{if(!a)return;const r={},S=new Set(l);for(const e of c)S.has(e)&&(r[e]=console[e],console[e]=(...m)=>{r[e]?.apply(console,m);const h=m.map(t=>{if(typeof t=="string")return t;try{return JSON.stringify(t)}catch{return String(t)}}).join(" ");u(t=>{const v={id:++y.current,level:e,message:h,timestamp:Date.now()},o=[...t,v];return o.length>s?o.slice(-s):o})});return()=>{for(const e of c)r[e]&&(console[e]=r[e])}},[a,s,l]);const f=C(()=>{u([])},[]);return g(()=>({clear:f,entries:i}),[f,i])};export{b as default,b as useConsoleCapture};

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

@@ -0,0 +1,13 @@
+import 'node:stream';
+import { a as CursorPosition } from "../../packem_shared/cursor-helpers.d-BONB9tky.js";
+/**
+* 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 { useCursor as default, useCursor };

package/dist/ink/hooks/use-cursor.js

@@ -0,0 +1 @@
+import{useContext as e,useRef as u,useCallback as i,useInsertionEffect as n}from"react";import{o as c}from"../../packem_shared/cursor-context-CFviBqPX.js";const a=()=>{const o=e(c),r=u(void 0),s=i(t=>{r.current=t},[]);return n(()=>(o.setCursorPosition(r.current),()=>{o.setCursorPosition(void 0)})),{setCursorPosition:s}};export{a as default,a as useCursor};

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

@@ -0,0 +1,57 @@
+import 'react';
+type Props = {
+  readonly activate: (id: string) => void;
+  readonly activeId?: string;
+  readonly add: (id: string, options: {
+    autoFocus: boolean;
+  }) => void;
+  readonly deactivate: (id: string) => void;
+  readonly disableFocus: () => void;
+  readonly enableFocus: () => void;
+  readonly focus: (id: string) => void;
+  readonly focusNext: () => void;
+  readonly focusPrevious: () => void;
+  readonly remove: (id: string) => void;
+};
+type Output = {
+  /**
+  * The ID of the currently focused component, or `undefined` if no component is focused.
+  * @example
+  * ```tsx
+  * import {Text} from '@visulima/tui/components/text';
+  * import {useFocusManager} from '@visulima/tui/hooks/use-focus-manager';
+  *
+  * 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 { useFocusManager as default, useFocusManager };

package/dist/ink/hooks/use-focus-manager.js

@@ -0,0 +1 @@
+import{useContext as s}from"react";import{o as e}from"../../packem_shared/focus-context-CsT69klR.js";const t=()=>{const o=s(e);return{activeId:o.activeId,disableFocus:o.disableFocus,enableFocus:o.enableFocus,focus:o.focus,focusNext:o.focusNext,focusPrevious:o.focusPrevious}};export{t as default,t as useFocusManager};

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

@@ -0,0 +1,34 @@
+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 { useFocus as default, useFocus };

package/dist/ink/hooks/use-focus.js

@@ -0,0 +1 @@
+import{useContext as p,useMemo as l,useEffect as t}from"react";import{o as v}from"../../packem_shared/focus-context-CsT69klR.js";import F from"./use-stdin.js";const R=({autoFocus:s=!1,id:a,isActive:o=!0}={})=>{const{isRawModeSupported:r,setRawMode:u}=F(),{activate:c,activeId:i,add:d,deactivate:f,focus:m,remove:n}=p(v),e=l(()=>a??Math.random().toString().slice(2,7),[a]);return t(()=>(d(e,{autoFocus:s}),()=>{n(e)}),[e,s]),t(()=>{o?c(e):f(e)},[o,e]),t(()=>{if(!(!r||!o))return u(!0),()=>{u(!1)}},[o]),{focus:m,isFocused:!!e&&i===e}};export{R as default,R as useFocus};

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

@@ -0,0 +1,68 @@
+type ValidationResult = string | undefined;
+type FieldValidator<V> = (value: V, values: Readonly<Record<string, unknown>>) => ValidationResult;
+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>;
+};
+type FormSchema = Readonly<Record<string, FieldConfig<never>>>;
+type FormValues<S extends Readonly<Record<string, FieldConfig>>> = { [K in keyof S]: S[K] extends FieldConfig<infer V> ? V : never };
+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>;
+};
+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 { FieldConfig, FieldValidator, FormSchema, FormValues, UseFormOptions, UseFormResult, ValidationResult, useForm as default, useForm };

package/dist/ink/hooks/use-form.js

@@ -0,0 +1 @@
+import{useMemo as x,useState as f,useRef as C,useCallback as c}from"react";const F=a=>{const r={};for(const u of Object.keys(a))r[u]=a[u].initialValue;return r},K=a=>{const{fields:r,onSubmit:u}=a,l=x(()=>F(r),[r]),[d,m]=f(l),[g,b]=f({}),[h,y]=f({}),[j,k]=f(!1),n=C(d);n.current=d;const i=c((e,s,t=n.current)=>r[e]?.validate?.(s,t),[r]),p=c((e,s)=>{const t={...n.current,[e]:s};n.current=t,m(t);const o=i(e,s,t);b(v=>{if(o===void 0){const S={...v};return delete S[e],S}return{...v,[e]:o}})},[i]),O=c((e,s=!0)=>{y(t=>({...t,[e]:s}))},[]),V=c(()=>{m(l),b({}),y({})},[l]),w=c(async()=>{const e={},s={};for(const t of Object.keys(r)){s[t]=!0;const o=i(t,n.current[t]);o!==void 0&&(e[t]=o)}if(b(e),y(s),Object.keys(e).length>0)return!1;try{return k(!0),await u?.(n.current),!0}finally{k(!1)}},[r,i,u]);return{errors:g,isSubmitting:j,reset:V,setTouched:O,setValue:p,submit:w,touched:h,values:d}};export{K as default,K as useForm};

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

@@ -0,0 +1,37 @@
+import { Key } from "./use-input.js";
+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;
+};
+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 { HotkeyDescriptor, UseHotkeyOptions, useHotkey as default, useHotkey };

package/dist/ink/hooks/use-hotkey.js

@@ -0,0 +1 @@
+import{useCallback as c}from"react";import n from"./use-input.js";const i=new Set(["backspace","delete","downArrow","end","escape","home","leftArrow","pageDown","pageUp","return","rightArrow","tab","upArrow"]),l=r=>{const t=r.split("+").map(a=>a.trim()).filter(a=>a.length>0),e={};for(const a of t){const s=a.toLowerCase();switch(s){case"alt":case"cmd":case"meta":{e.meta=!0;break}case"control":case"ctrl":{e.ctrl=!0;break}case"shift":{e.shift=!0;break}default:if(i.has(s))e.name=s;else switch(s){case"down":{e.name="downArrow";break}case"enter":{e.name="return";break}case"esc":{e.name="escape";break}case"left":{e.name="leftArrow";break}case"right":{e.name="rightArrow";break}case"up":{e.name="upArrow";break}default:e.input=a}}}return e},m=(r,t,e)=>r.ctrl!==void 0&&r.ctrl!==e.ctrl||r.shift!==void 0&&r.shift!==e.shift||r.meta!==void 0&&r.meta!==e.meta?!1:r.name!==void 0?!!e[r.name]:r.input!==void 0?t===r.input:!1,p=(r,t,e)=>{const a=typeof r=="string"?l(r):r;n(c((s,o)=>{m(a,s,o)&&t()},[r,t]),{isActive:e?.isActive??!0})};export{p as default,p as useHotkey};

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

@@ -0,0 +1,149 @@
+/**
+* Handy information about a key that was pressed.
+*/
+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 '@visulima/tui/hooks/use-input';
+*
+* 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 { Key, useInput as default, useInput };