r3bl-ts-utils/build/tui-node-keyboard/use-node-keypress.d.ts

The `r3bl-ts-utils` package is a set of useful TypeScript functions and classes that can be used in Node.js and browser environments. They are inspired by Kotlin stdlib, and Rust to write code as expressions rather than statements, colorized text, powerfu

import { Option } from "../lang-utils/rust-lang-utils";
import { IsActive, NodeJsListenerFn, SetState } from "../tui-core";
import { ReadlineKey } from "./readline-config";
export declare type KeypressType = {
    input: string;
    key: ReadlineKey;
};
export declare type KeypressOptionType = Option<KeypressType>;
export declare type KeypressOptionSetterType = SetState<KeypressOptionType>;
/**
 * This hook provides access to Node.js readline keypress events. If Node.js is running in a
 * terminal (process.stdin.isTTY = true) then it will set Node.js process.stdin to raw mode.
 *
 * Please take a look at useEventEmitter hook for a more generic implementation of this pattern.
 *
 * Update React state from external event sources:
 * Please refer to the two commits listed below for more information on how the hook "binds" the
 * two disparate worlds of Node.js process.stdin's keypress events, and the React function
 * component that ends up using this hook to get async events that are generated by an end user
 * who's typing in a terminal.
 *
 * More information on this:
 * http://developerlife.com/2021/10/19/react-hooks-redux-typescript-handbook/#custom-hooks
 * https://github.com/r3bl-org/r3bl-ts-utils/commit/a3248540ea325d3896ee56a84d003f15529169cd
 * https://github.com/r3bl-org/r3bl-ts-utils/commit/1f3cbb2b4988f44c6ea48233db1730e10f18dc60
 * https://stackoverflow.com/questions/53898810/executing-async-code-on-update-of-state-with-react-hooks
 *
 * More information on Node.js readline keypress events:
 * https://nodejs.org/api/readline.html#readlineemitkeypresseventsstream-interface
 * https://www.npmjs.com/package/keypress
 * https://nodejs.org/api/readline.html#tty-keybindings
 */
export declare const useNodeKeypress: (fun: HandleNodeKeypressFn, options?: IsActive) => KeypressOptionType;
/** Note this function signature can't be changed, this is defined by Node.js. */
export declare type HandleNodeKeypressFn = (input: string, key: ReadlineKey) => void;
/**
 * Node.js process.stdin "raw mode" is true means that every single keypress event will be fired as
 * it's typed by the user. false means that one will be fired at the very end after they hit enter.
 * When Node.js detects that it is being run with a text terminal ("TTY") attached `isTTY` will be
 * true.
 *
 * When readline.emitKeypressEvents(process.stdin) is called, Node.js starts emitting "keypress"
 * events on stdin readable stream. In order to stop this, all the listeners must be removed and
 * pause must be called on the stdin stream.
 *
 * More info:
 * https://www.cs.unb.ca/~bremner/teaching/cs2613/books/nodejs-api/tty/
 * https://nodejs.org/api/tty.html#readstreamistty
 *
 * @return {boolean} false means that `fun` was not attached to stdin. true means that it was
 * and raw mode was switched on.
 */
export declare const attachToReadlineKeypress: (setKeypress?: KeypressOptionSetterType | undefined) => NodeJsListenerFn | undefined;
export declare const detachFromReadlineKeypress: (listener: NodeJsListenerFn) => void;