tinky-keypress 0.1.0

package/README.ja-JP.md

@@ -0,0 +1,112 @@
+# tinky-keypress
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
+
+> [Tinky](https://github.com/ByteLandTechnology/tinky) アプリケーションのための堅牢なキープレス処理と入力解析。
+
+このパッケージは、ターミナルユーザーインターフェースにおける標準入力 (stdin) を管理するための専用コンテキストとフックシステムを提供します。特殊キー、修飾キー、モダンなターミナルプロトコルを含む、生の ANSI エスケープシーケンス解析の複雑さを処理します。
+
+## 特徴
+
+- **簡単な統合**: ドロップインで使用できるコンテキストプロバイダー (`KeypressProvider`) とフック (`useKeypress`)。
+- **包括的な解析**: 標準キー、ファンクションキー (F1-F12)、ナビゲーションキーなどをサポート。
+- **修飾キーのサポート**: Control、Alt/Meta、Shift 修飾キーをサポート。
+- **高度なプロトコル**: Kitty キーボードプロトコルのオプションサポート。
+- **マウスとクリップボード**: マウスイベントのフィルタリングと OSC 52 ペーストシーケンスのサポートを内蔵。
+- **型安全性**: TypeScript で記述されており、完全な型定義を提供します。
+
+## インストール
+
+```bash
+npm install tinky-keypress
+# または
+yarn add tinky-keypress
+# または
+pnpm add tinky-keypress
+# または
+bun add tinky-keypress
+```
+
+## 使用方法
+
+アプリケーションのルートを `KeypressProvider` でラップし、任意の子コンポーネントで `useKeypress` を使用します。
+
+```tsx
+import React, { useState } from "react";
+import { render, Text } from "tinky";
+import { KeypressProvider, useKeypress } from "tinky-keypress";
+
+function App() {
+  const [lastEvent, setLastEvent] = useState<string>("キーを押してください...");
+
+  useKeypress(
+    (key) => {
+      const parts = [key.name];
+      if (key.ctrl) parts.push("Ctrl");
+      if (key.meta) parts.push("Alt");
+      if (key.shift) parts.push("Shift");
+
+      setLastEvent(
+        `検出: ${parts.join("+")} (シーケンス: ${JSON.stringify(key.sequence)})`,
+      );
+
+      if (key.name === "q" && !key.ctrl) {
+        process.exit(0);
+      }
+    },
+    { isActive: true },
+  );
+
+  return <Text>{lastEvent}</Text>;
+}
+
+const instance = render(
+  <KeypressProvider>
+    <App />
+  </KeypressProvider>,
+);
+```
+
+## API
+
+### `<KeypressProvider />`
+
+`process.stdin` をリッスンするトップレベルのプロバイダー。
+
+| プロパティ      | 型          | デフォルト値 | 説明                                                                                     |
+| --------------- | ----------- | ------------ | ---------------------------------------------------------------------------------------- |
+| `children`      | `ReactNode` | N/A          | キープレスフックを使用できる子コンポーネント。                                           |
+| `kittyProtocol` | `boolean`   | `false`      | Kitty キーボードプロトコルのサポートを有効にします（ターミナルがサポートしている場合）。 |
+
+### `useKeypress(handler, options)`
+
+キープレスイベントを購読するためのフック。
+
+```typescript
+useKeypress(
+  handler: (key: Key) => void,
+  options: { isActive: boolean }
+): void
+```
+
+- **handler**: キープレスが発生したときに呼び出される関数。
+- **options.isActive**: リスナーを有効にするかどうか（フォーカス管理に便利です）。
+
+### `Key` インターフェース
+
+ハンドラーに渡されるイベントオブジェクト：
+
+```typescript
+interface Key {
+  name: string; // キーの名前 (例: 'a', 'enter', 'escape', 'up')
+  ctrl: boolean; // Control キーが押されているかどうか
+  meta: boolean; // Alt/Meta キーが押されているかどうか
+  shift: boolean; // Shift キーが押されているかどうか
+  insertable: boolean; // キーが表示可能な文字を生成するかどうか
+  sequence: string; // 受信した生の ANSI シーケンス
+}
+```
+
+## ライセンス
+
+Apache-2.0

package/README.md

@@ -0,0 +1,112 @@
+# tinky-keypress
+
+[简体中文](./README.zh-CN.md) | [日本語](./README.ja-JP.md)
+
+> Robust keypress handling and input parsing for [Tinky](https://github.com/ByteLandTechnology/tinky) applications.
+
+This package provides a dedicated context and hooks system for managing standard input (stdin) in terminal user interfaces. It handles the complexity of parsing raw ANSI escape sequences, including special keys, modifiers, and modern terminal protocols.
+
+## Features
+
+- **Easy Integration**: Drop-in context provider (`KeypressProvider`) and hook (`useKeypress`).
+- **Comprehensive Parsing**: Supports standard keys, function keys (F1-F12), navigation keys, and more.
+- **Modifier Support**: Handles Control, Alt/Meta, and Shift modifiers.
+- **Advanced Protocols**: Optional support for the Kitty Keyboard Protocol.
+- **Mouse & Clipboard**: Built-in filtering for mouse events and support for OSC 52 paste sequences.
+- **Type-Safe**: Written in TypeScript with complete type definitions.
+
+## Installation
+
+```bash
+npm install tinky-keypress
+# or
+yarn add tinky-keypress
+# or
+pnpm add tinky-keypress
+# or
+bun add tinky-keypress
+```
+
+## Usage
+
+Wrap your application root with `KeypressProvider` and use `useKeypress` in any child component.
+
+```tsx
+import React, { useState } from "react";
+import { render, Text } from "tinky";
+import { KeypressProvider, useKeypress } from "tinky-keypress";
+
+function App() {
+  const [lastEvent, setLastEvent] = useState<string>("Press any key...");
+
+  useKeypress(
+    (key) => {
+      const parts = [key.name];
+      if (key.ctrl) parts.push("Ctrl");
+      if (key.meta) parts.push("Alt");
+      if (key.shift) parts.push("Shift");
+
+      setLastEvent(
+        `Detected: ${parts.join("+")} (Sequence: ${JSON.stringify(key.sequence)})`,
+      );
+
+      if (key.name === "q" && !key.ctrl) {
+        process.exit(0);
+      }
+    },
+    { isActive: true },
+  );
+
+  return <Text>{lastEvent}</Text>;
+}
+
+const instance = render(
+  <KeypressProvider>
+    <App />
+  </KeypressProvider>,
+);
+```
+
+## API
+
+### `<KeypressProvider />`
+
+The top-level provider that listens to `process.stdin`.
+
+| Prop            | Type        | Default | Description                                                                    |
+| --------------- | ----------- | ------- | ------------------------------------------------------------------------------ |
+| `children`      | `ReactNode` | N/A     | Child components that can use keypress hooks.                                  |
+| `kittyProtocol` | `boolean`   | `false` | Enable support for the Kitty keyboard protocol (if supported by the terminal). |
+
+### `useKeypress(handler, options)`
+
+Hook to subscribe to keypress events.
+
+```typescript
+useKeypress(
+  handler: (key: Key) => void,
+  options: { isActive: boolean }
+): void
+```
+
+- **handler**: Function called whenever a keypress occurs.
+- **options.isActive**: Boolean to enable or disable the listener (useful for focus management).
+
+### `Key` Interface
+
+The event object passed to the handler:
+
+```typescript
+interface Key {
+  name: string; // The name of the key (e.g., 'a', 'enter', 'escape', 'up')
+  ctrl: boolean; // Whether the Control key is pressed
+  meta: boolean; // Whether the Alt/Meta key is pressed
+  shift: boolean; // Whether the Shift key is pressed
+  insertable: boolean; // Whether the key produces a printable character
+  sequence: string; // The raw ANSI sequence received
+}
+```
+
+## License
+
+Apache-2.0

package/README.zh-CN.md

@@ -0,0 +1,112 @@
+# tinky-keypress
+
+[English](./README.md) | [日本語](./README.ja-JP.md)
+
+> 为 [Tinky](https://github.com/ByteLandTechnology/tinky) 应用提供强大的按键处理和输入解析功能。
+
+本软件包提供了一套专用的 Context 和 Hooks 系统，用于管理终端用户界面中的标准输入 (stdin)。它处理了解析原始 ANSI 转义序列的复杂性，支持特殊键、修饰键以及现代终端协议。
+
+## 功能特性
+
+- **易于集成**：即插即用的 Context 提供者 (`KeypressProvider`) 和 Hook (`useKeypress`)。
+- **全面解析**：支持标准键、功能键 (F1-F12)、导航键等。
+- **修饰键支持**：支持 Control、Alt/Meta 和 Shift 修饰键。
+- **高级协议**：可选支持 Kitty 键盘协议。
+- **鼠标与剪贴板**：内置鼠标事件过滤和 OSC 52 粘贴序列支持。
+- **类型安全**：使用 TypeScript 编写，提供完整的类型定义。
+
+## 安装
+
+```bash
+npm install tinky-keypress
+# 或
+yarn add tinky-keypress
+# 或
+pnpm add tinky-keypress
+# 或
+bun add tinky-keypress
+```
+
+## 使用方法
+
+使用 `KeypressProvider` 包裹应用根组件，并在任何子组件中使用 `useKeypress`。
+
+```tsx
+import React, { useState } from "react";
+import { render, Text } from "tinky";
+import { KeypressProvider, useKeypress } from "tinky-keypress";
+
+function App() {
+  const [lastEvent, setLastEvent] = useState<string>("请按任意键...");
+
+  useKeypress(
+    (key) => {
+      const parts = [key.name];
+      if (key.ctrl) parts.push("Ctrl");
+      if (key.meta) parts.push("Alt");
+      if (key.shift) parts.push("Shift");
+
+      setLastEvent(
+        `检测到: ${parts.join("+")} (序列: ${JSON.stringify(key.sequence)})`,
+      );
+
+      if (key.name === "q" && !key.ctrl) {
+        process.exit(0);
+      }
+    },
+    { isActive: true },
+  );
+
+  return <Text>{lastEvent}</Text>;
+}
+
+const instance = render(
+  <KeypressProvider>
+    <App />
+  </KeypressProvider>,
+);
+```
+
+## API
+
+### `<KeypressProvider />`
+
+监听 `process.stdin` 的顶层 Provider。
+
+| 属性            | 类型        | 默认值  | 描述                                      |
+| --------------- | ----------- | ------- | ----------------------------------------- |
+| `children`      | `ReactNode` | N/A     | 可以使用按键 Hooks 的子组件。             |
+| `kittyProtocol` | `boolean`   | `false` | 启用 Kitty 键盘协议支持（如果终端支持）。 |
+
+### `useKeypress(handler, options)`
+
+订阅按键事件的 Hook。
+
+```typescript
+useKeypress(
+  handler: (key: Key) => void,
+  options: { isActive: boolean }
+): void
+```
+
+- **handler**: 当发生按键时调用的函数。
+- **options.isActive**: 是否启用监听器（可用于焦点管理）。
+
+### `Key` 接口
+
+传递给处理程序的事件对象：
+
+```typescript
+interface Key {
+  name: string; // 按键名称 (例如 'a', 'enter', 'escape', 'up')
+  ctrl: boolean; // 是否按下了 Control 键
+  meta: boolean; // 是否按下了 Alt/Meta 键
+  shift: boolean; // 是否按下了 Shift 键
+  insertable: boolean; // 该按键是否产生可打印字符
+  sequence: string; // 接收到的原始 ANSI 序列
+}
+```
+
+## 许可证
+
+Apache-2.0

package/lib/contexts/KeypressContext.d.ts

@@ -0,0 +1,48 @@
+/** Timeout for waiting for a return after a backslash to detect escaped newlines */
+export declare const BACKSLASH_ENTER_TIMEOUT = 5;
+/** Timeout for waiting for more characters in an escape sequence */
+export declare const ESC_TIMEOUT = 50;
+/** Timeout for waiting for paste end sequence */
+export declare const PASTE_TIMEOUT = 30000;
+/** Timeout for discriminating between a fast return key and a pasted newline */
+export declare const FAST_RETURN_TIMEOUT = 30;
+/** Focus event sequences */
+export declare const FOCUS_IN = "\u001B[I";
+export declare const FOCUS_OUT = "\u001B[O";
+/**
+ * Represents a parsed key press event.
+ */
+export interface Key {
+    name: string;
+    ctrl: boolean;
+    meta: boolean;
+    shift: boolean;
+    insertable: boolean;
+    sequence: string;
+}
+/**
+ * Handler function type for keypress events.
+ */
+export type KeypressHandler = (key: Key) => void;
+export interface KeypressContextValue {
+    subscribe: (handler: KeypressHandler) => void;
+    unsubscribe: (handler: KeypressHandler) => void;
+}
+/**
+ * Hook to access the Keypress context.
+ * Allows components to subscribe and unsubscribe to keypress events.
+ *
+ * @returns The Keypress context value containing subscribe and unsubscribe methods.
+ * @throws Error if used outside of a KeypressProvider.
+ */
+export declare function useKeypressContext(): KeypressContextValue;
+/**
+ * Provider component for the Keypress context.
+ * Manages stdin data listening and parsing, and broadcasts key events to subscribers.
+ */
+export declare function KeypressProvider({ children, kittyProtocol, }: {
+    /** Child components */
+    children: React.ReactNode;
+    /** Whether Kitty keyboard protocol is enabled (from useTermcap) */
+    kittyProtocol?: boolean;
+}): import("react/jsx-runtime").JSX.Element;

package/lib/contexts/KeypressContext.js

@@ -0,0 +1,714 @@
+"use strict";
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FOCUS_OUT = exports.FOCUS_IN = exports.FAST_RETURN_TIMEOUT = exports.PASTE_TIMEOUT = exports.ESC_TIMEOUT = exports.BACKSLASH_ENTER_TIMEOUT = void 0;
+exports.useKeypressContext = useKeypressContext;
+exports.KeypressProvider = KeypressProvider;
+var jsx_runtime_1 = require("react/jsx-runtime");
+/* eslint-disable no-control-regex */
+var react_1 = require("react");
+var tinky_1 = require("tinky");
+// ESC character constant (escape key)
+var ESC = "\x1b";
+// Simple check for mouse escape sequences to filter them out
+// SGR format: ESC [ < ... m/M
+// X11 format: ESC [ M ...
+function isMouseSequence(sequence) {
+    if (!sequence.startsWith(ESC))
+        return false;
+    // SGR mouse: ESC [ < number ; number ; number m/M
+    if (/^\x1b\[<\d+;\d+;\d+[mM]$/.test(sequence))
+        return true;
+    // X11 mouse: ESC [ M followed by 3 chars
+    if (/^\x1b\[M[\s\S]{3}$/.test(sequence))
+        return true;
+    return false;
+}
+/** Timeout for waiting for a return after a backslash to detect escaped newlines */
+exports.BACKSLASH_ENTER_TIMEOUT = 5;
+/** Timeout for waiting for more characters in an escape sequence */
+exports.ESC_TIMEOUT = 50;
+/** Timeout for waiting for paste end sequence */
+exports.PASTE_TIMEOUT = 30000;
+/** Timeout for discriminating between a fast return key and a pasted newline */
+exports.FAST_RETURN_TIMEOUT = 30;
+/** Focus event sequences */
+exports.FOCUS_IN = "\x1b[I";
+exports.FOCUS_OUT = "\x1b[O";
+// Parse the key itself
+var KEY_INFO_MAP = {
+    "[200~": { name: "paste-start" },
+    "[201~": { name: "paste-end" },
+    "[[A": { name: "f1" },
+    "[[B": { name: "f2" },
+    "[[C": { name: "f3" },
+    "[[D": { name: "f4" },
+    "[[E": { name: "f5" },
+    "[1~": { name: "home" },
+    "[2~": { name: "insert" },
+    "[3~": { name: "delete" },
+    "[4~": { name: "end" },
+    "[5~": { name: "pageup" },
+    "[6~": { name: "pagedown" },
+    "[7~": { name: "home" },
+    "[8~": { name: "end" },
+    "[11~": { name: "f1" },
+    "[12~": { name: "f2" },
+    "[13~": { name: "f3" },
+    "[14~": { name: "f4" },
+    "[15~": { name: "f5" },
+    "[17~": { name: "f6" },
+    "[18~": { name: "f7" },
+    "[19~": { name: "f8" },
+    "[20~": { name: "f9" },
+    "[21~": { name: "f10" },
+    "[23~": { name: "f11" },
+    "[24~": { name: "f12" },
+    "[A": { name: "up" },
+    "[B": { name: "down" },
+    "[C": { name: "right" },
+    "[D": { name: "left" },
+    "[E": { name: "clear" },
+    "[F": { name: "end" },
+    "[H": { name: "home" },
+    "[P": { name: "f1" },
+    "[Q": { name: "f2" },
+    "[R": { name: "f3" },
+    "[S": { name: "f4" },
+    OA: { name: "up" },
+    OB: { name: "down" },
+    OC: { name: "right" },
+    OD: { name: "left" },
+    OE: { name: "clear" },
+    OF: { name: "end" },
+    OH: { name: "home" },
+    OP: { name: "f1" },
+    OQ: { name: "f2" },
+    OR: { name: "f3" },
+    OS: { name: "f4" },
+    "[[5~": { name: "pageup" },
+    "[[6~": { name: "pagedown" },
+    "[9u": { name: "tab" },
+    "[13u": { name: "return" },
+    "[27u": { name: "escape" },
+    "[32u": { name: "space" },
+    "[127u": { name: "backspace" },
+    "[57414u": { name: "return" }, // Numpad Enter
+    "[a": { name: "up", shift: true },
+    "[b": { name: "down", shift: true },
+    "[c": { name: "right", shift: true },
+    "[d": { name: "left", shift: true },
+    "[e": { name: "clear", shift: true },
+    "[2$": { name: "insert", shift: true },
+    "[3$": { name: "delete", shift: true },
+    "[5$": { name: "pageup", shift: true },
+    "[6$": { name: "pagedown", shift: true },
+    "[7$": { name: "home", shift: true },
+    "[8$": { name: "end", shift: true },
+    "[Z": { name: "tab", shift: true },
+    Oa: { name: "up", ctrl: true },
+    Ob: { name: "down", ctrl: true },
+    Oc: { name: "right", ctrl: true },
+    Od: { name: "left", ctrl: true },
+    Oe: { name: "clear", ctrl: true },
+    "[2^": { name: "insert", ctrl: true },
+    "[3^": { name: "delete", ctrl: true },
+    "[5^": { name: "pageup", ctrl: true },
+    "[6^": { name: "pagedown", ctrl: true },
+    "[7^": { name: "home", ctrl: true },
+    "[8^": { name: "end", ctrl: true },
+};
+var kUTF16SurrogateThreshold = 0x10000; // 2 ** 16
+function charLengthAt(str, i) {
+    if (str.length <= i) {
+        // Pretend to move to the right. This is necessary to autocomplete while
+        // moving to the right.
+        return 1;
+    }
+    var code = str.codePointAt(i);
+    return code !== undefined && code >= kUTF16SurrogateThreshold ? 2 : 1;
+}
+var MAC_ALT_KEY_CHARACTER_MAP = {
+    "\u222B": "b", // "∫" back one word
+    "\u0192": "f", // "ƒ" forward one word
+    "\u00B5": "m", // "µ" toggle markup view
+};
+function nonKeyboardEventFilter(keypressHandler) {
+    return function (key) {
+        if (!isMouseSequence(key.sequence) &&
+            key.sequence !== exports.FOCUS_IN &&
+            key.sequence !== exports.FOCUS_OUT) {
+            keypressHandler(key);
+        }
+    };
+}
+/**
+ * Converts return keys pressed quickly after other keys into plain
+ * insertable return characters.
+ *
+ * This is to accommodate older terminals that paste text without bracketing.
+ */
+function bufferFastReturn(keypressHandler) {
+    var lastKeyTime = 0;
+    return function (key) {
+        var now = Date.now();
+        if (key.name === "return" && now - lastKeyTime <= exports.FAST_RETURN_TIMEOUT) {
+            keypressHandler(__assign(__assign({}, key), { name: "return", sequence: "\r", insertable: true }));
+        }
+        else {
+            keypressHandler(key);
+        }
+        lastKeyTime = now;
+    };
+}
+/**
+ * Buffers "/" keys to see if they are followed return.
+ * Will flush the buffer if no data is received for DRAG_COMPLETION_TIMEOUT_MS
+ * or when a null key is received.
+ */
+function bufferBackslashEnter(keypressHandler) {
+    var bufferer = (function () {
+        var key, timeoutId, nextKey;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!true) return [3 /*break*/, 3];
+                    return [4 /*yield*/];
+                case 1:
+                    key = _a.sent();
+                    if (key == null) {
+                        return [3 /*break*/, 0];
+                    }
+                    else if (key.sequence !== "\\") {
+                        keypressHandler(key);
+                        return [3 /*break*/, 0];
+                    }
+                    timeoutId = setTimeout(function () { return bufferer.next(null); }, exports.BACKSLASH_ENTER_TIMEOUT);
+                    return [4 /*yield*/];
+                case 2:
+                    nextKey = _a.sent();
+                    clearTimeout(timeoutId);
+                    if (nextKey === null) {
+                        keypressHandler(key);
+                    }
+                    else if (nextKey.name === "return") {
+                        keypressHandler(__assign(__assign({}, nextKey), { shift: true, sequence: "\r" }));
+                    }
+                    else {
+                        keypressHandler(key);
+                        keypressHandler(nextKey);
+                    }
+                    return [3 /*break*/, 0];
+                case 3: return [2 /*return*/];
+            }
+        });
+    })();
+    bufferer.next(); // prime the generator so it starts listening.
+    return function (key) { return bufferer.next(key); };
+}
+/**
+ * Buffers paste events between paste-start and paste-end sequences.
+ * Will flush the buffer if no data is received for PASTE_TIMEOUT ms or
+ * when a null key is received.
+ */
+function bufferPaste(keypressHandler) {
+    var bufferer = (function () {
+        var key, buffer, timeoutId;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    if (!true) return [3 /*break*/, 5];
+                    return [4 /*yield*/];
+                case 1:
+                    key = _a.sent();
+                    if (key === null) {
+                        return [3 /*break*/, 0];
+                    }
+                    else if (key.name !== "paste-start") {
+                        keypressHandler(key);
+                        return [3 /*break*/, 0];
+                    }
+                    buffer = "";
+                    _a.label = 2;
+                case 2:
+                    if (!true) return [3 /*break*/, 4];
+                    timeoutId = setTimeout(function () { return bufferer.next(null); }, exports.PASTE_TIMEOUT);
+                    return [4 /*yield*/];
+                case 3:
+                    key = _a.sent();
+                    clearTimeout(timeoutId);
+                    if (key === null) {
+                        // Paste timeout occurred - data may be truncated
+                        return [3 /*break*/, 4];
+                    }
+                    if (key.name === "paste-end") {
+                        return [3 /*break*/, 4];
+                    }
+                    buffer += key.sequence;
+                    return [3 /*break*/, 2];
+                case 4:
+                    if (buffer.length > 0) {
+                        keypressHandler({
+                            name: "paste",
+                            ctrl: false,
+                            meta: false,
+                            shift: false,
+                            insertable: true,
+                            sequence: buffer,
+                        });
+                    }
+                    return [3 /*break*/, 0];
+                case 5: return [2 /*return*/];
+            }
+        });
+    })();
+    bufferer.next(); // prime the generator so it starts listening.
+    return function (key) { return bufferer.next(key); };
+}
+/**
+ * Turns raw data strings into keypress events sent to the provided handler.
+ * Buffers escape sequences until a full sequence is received or
+ * until a timeout occurs.
+ */
+function createDataListener(keypressHandler) {
+    var parser = emitKeys(keypressHandler);
+    parser.next(); // prime the generator so it starts listening.
+    var timeoutId;
+    return function (data) {
+        var e_1, _a;
+        clearTimeout(timeoutId);
+        try {
+            for (var data_1 = __values(data), data_1_1 = data_1.next(); !data_1_1.done; data_1_1 = data_1.next()) {
+                var char = data_1_1.value;
+                parser.next(char);
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (data_1_1 && !data_1_1.done && (_a = data_1.return)) _a.call(data_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        if (data.length !== 0) {
+            timeoutId = setTimeout(function () { return parser.next(""); }, exports.ESC_TIMEOUT);
+        }
+    };
+}
+/**
+ * Translates raw keypress characters into key events.
+ * Buffers escape sequences until a full sequence is received or
+ * until an empty string is sent to indicate a timeout.
+ */
+function emitKeys(keypressHandler) {
+    var ch, sequence, escaped, name, ctrl, meta, shift, code, insertable, modifier, buffer, next, afterEsc, match, base64Data, decoded, cmdStart, cmd, match, keyInfo, codeNumber;
+    var _a, _b, _c, _d;
+    return __generator(this, function (_e) {
+        switch (_e.label) {
+            case 0:
+                if (!true) return [3 /*break*/, 41];
+                return [4 /*yield*/];
+            case 1:
+                ch = _e.sent();
+                sequence = ch;
+                escaped = false;
+                name = undefined;
+                ctrl = false;
+                meta = false;
+                shift = false;
+                code = undefined;
+                insertable = false;
+                if (!(ch === ESC)) return [3 /*break*/, 4];
+                escaped = true;
+                return [4 /*yield*/];
+            case 2:
+                ch = _e.sent();
+                sequence += ch;
+                if (!(ch === ESC)) return [3 /*break*/, 4];
+                return [4 /*yield*/];
+            case 3:
+                ch = _e.sent();
+                sequence += ch;
+                _e.label = 4;
+            case 4:
+                if (!(escaped && (ch === "O" || ch === "[" || ch === "]"))) return [3 /*break*/, 39];
+                // ANSI escape sequence
+                code = ch;
+                modifier = 0;
+                if (!(ch === "]")) return [3 /*break*/, 11];
+                buffer = "";
+                _e.label = 5;
+            case 5:
+                if (!true) return [3 /*break*/, 10];
+                return [4 /*yield*/];
+            case 6:
+                next = _e.sent();
+                if (!(next === "" || next === "\u0007")) return [3 /*break*/, 7];
+                return [3 /*break*/, 10];
+            case 7:
+                if (!(next === ESC)) return [3 /*break*/, 9];
+                return [4 /*yield*/];
+            case 8:
+                afterEsc = _e.sent();
+                if (afterEsc === "" || afterEsc === "\\") {
+                    return [3 /*break*/, 10];
+                }
+                buffer += next + afterEsc;
+                return [3 /*break*/, 5];
+            case 9:
+                buffer += next;
+                return [3 /*break*/, 5];
+            case 10:
+                match = /^52;[cp];(.*)$/.exec(buffer);
+                if (match) {
+                    try {
+                        base64Data = match[1];
+                        decoded = Buffer.from(base64Data, "base64").toString("utf-8");
+                        keypressHandler({
+                            name: "paste",
+                            ctrl: false,
+                            meta: false,
+                            shift: false,
+                            insertable: true,
+                            sequence: decoded,
+                        });
+                    }
+                    catch (_f) {
+                        // Ignore error
+                    }
+                }
+                return [3 /*break*/, 0]; // resume main loop
+            case 11:
+                if (!(ch === "O")) return [3 /*break*/, 15];
+                return [4 /*yield*/];
+            case 12:
+                // ESC O letter
+                // ESC O modifier letter
+                ch = _e.sent();
+                sequence += ch;
+                if (!(ch >= "0" && ch <= "9")) return [3 /*break*/, 14];
+                modifier = parseInt(ch, 10) - 1;
+                return [4 /*yield*/];
+            case 13:
+                ch = _e.sent();
+                sequence += ch;
+                _e.label = 14;
+            case 14:
+                code += ch;
+                return [3 /*break*/, 38];
+            case 15:
+                if (!(ch === "[")) return [3 /*break*/, 38];
+                return [4 /*yield*/];
+            case 16:
+                // ESC [ letter
+                // ESC [ modifier letter
+                // ESC [ [ modifier letter
+                // ESC [ [ num char
+                ch = _e.sent();
+                sequence += ch;
+                if (!(ch === "[")) return [3 /*break*/, 18];
+                // \x1b[[A
+                //      ^--- escape codes might have a second bracket
+                code += ch;
+                return [4 /*yield*/];
+            case 17:
+                ch = _e.sent();
+                sequence += ch;
+                _e.label = 18;
+            case 18:
+                cmdStart = sequence.length - 1;
+                _e.label = 19;
+            case 19:
+                if (!(ch >= "0" && ch <= "9")) return [3 /*break*/, 21];
+                return [4 /*yield*/];
+            case 20:
+                ch = _e.sent();
+                sequence += ch;
+                return [3 /*break*/, 19];
+            case 21:
+                if (!(ch === ";")) return [3 /*break*/, 28];
+                _e.label = 22;
+            case 22:
+                if (!(ch === ";")) return [3 /*break*/, 27];
+                return [4 /*yield*/];
+            case 23:
+                ch = _e.sent();
+                sequence += ch;
+                _e.label = 24;
+            case 24:
+                if (!(ch >= "0" && ch <= "9")) return [3 /*break*/, 26];
+                return [4 /*yield*/];
+            case 25:
+                ch = _e.sent();
+                sequence += ch;
+                return [3 /*break*/, 24];
+            case 26: return [3 /*break*/, 22];
+            case 27: return [3 /*break*/, 37];
+            case 28:
+                if (!(ch === "<")) return [3 /*break*/, 33];
+                return [4 /*yield*/];
+            case 29:
+                // SGR mouse mode
+                ch = _e.sent();
+                sequence += ch;
+                _e.label = 30;
+            case 30:
+                if (!(ch === "" || ch === ";" || (ch >= "0" && ch <= "9"))) return [3 /*break*/, 32];
+                return [4 /*yield*/];
+            case 31:
+                ch = _e.sent();
+                sequence += ch;
+                return [3 /*break*/, 30];
+            case 32: return [3 /*break*/, 37];
+            case 33:
+                if (!(ch === "M")) return [3 /*break*/, 37];
+                return [4 /*yield*/];
+            case 34:
+                // X11 mouse mode
+                // three characters after 'M'
+                ch = _e.sent();
+                sequence += ch;
+                return [4 /*yield*/];
+            case 35:
+                ch = _e.sent();
+                sequence += ch;
+                return [4 /*yield*/];
+            case 36:
+                ch = _e.sent();
+                sequence += ch;
+                _e.label = 37;
+            case 37:
+                cmd = sequence.slice(cmdStart);
+                match = void 0;
+                if ((match = /^(\d+)(?:;(\d+))?(?:;(\d+))?([~^$u])$/.exec(cmd))) {
+                    if (match[1] === "27" && match[3] && match[4] === "~") {
+                        // modifyOtherKeys format: CSI 27 ; modifier ; key ~
+                        // Treat as CSI u: key + 'u'
+                        code += match[3] + "u";
+                        modifier = parseInt((_a = match[2]) !== null && _a !== void 0 ? _a : "1", 10) - 1;
+                    }
+                    else {
+                        code += match[1] + match[4];
+                        // Defaults to '1' if no modifier exists, resulting in a 0 modifier value
+                        modifier = parseInt((_b = match[2]) !== null && _b !== void 0 ? _b : "1", 10) - 1;
+                    }
+                }
+                else if ((match = /^(\d+)?(?:;(\d+))?([A-Za-z])$/.exec(cmd))) {
+                    code += match[3];
+                    modifier = parseInt((_d = (_c = match[2]) !== null && _c !== void 0 ? _c : match[1]) !== null && _d !== void 0 ? _d : "1", 10) - 1;
+                }
+                else {
+                    code += cmd;
+                }
+                _e.label = 38;
+            case 38:
+                // Parse the key modifier
+                ctrl = !!(modifier & 4);
+                meta = !!(modifier & 10); // use 10 to catch both alt (2) and meta (8).
+                shift = !!(modifier & 1);
+                keyInfo = KEY_INFO_MAP[code];
+                if (keyInfo) {
+                    name = keyInfo.name;
+                    if (keyInfo.shift) {
+                        shift = true;
+                    }
+                    if (keyInfo.ctrl) {
+                        ctrl = true;
+                    }
+                    if (name === "space" && !ctrl && !meta) {
+                        sequence = " ";
+                        insertable = true;
+                    }
+                }
+                else {
+                    name = "undefined";
+                    if ((ctrl || meta) && (code.endsWith("u") || code.endsWith("~"))) {
+                        codeNumber = parseInt(code.slice(1, -1), 10);
+                        if (codeNumber >= "a".charCodeAt(0) &&
+                            codeNumber <= "z".charCodeAt(0)) {
+                            name = String.fromCharCode(codeNumber);
+                        }
+                    }
+                }
+                return [3 /*break*/, 40];
+            case 39:
+                if (ch === "\r") {
+                    // carriage return
+                    name = "return";
+                    meta = escaped;
+                }
+                else if (ch === "\n") {
+                    // Enter, should have been called linefeed
+                    name = "enter";
+                    meta = escaped;
+                }
+                else if (ch === "\t") {
+                    // tab
+                    name = "tab";
+                    meta = escaped;
+                }
+                else if (ch === "\b" || ch === "\x7f") {
+                    // backspace or ctrl+h
+                    name = "backspace";
+                    meta = escaped;
+                }
+                else if (ch === ESC) {
+                    // escape key
+                    name = "escape";
+                    meta = escaped;
+                }
+                else if (ch === " ") {
+                    name = "space";
+                    meta = escaped;
+                    insertable = true;
+                }
+                else if (!escaped && ch <= "\x1a") {
+                    // ctrl+letter
+                    name = String.fromCharCode(ch.charCodeAt(0) + "a".charCodeAt(0) - 1);
+                    ctrl = true;
+                }
+                else if (/^[0-9A-Za-z]$/.exec(ch) !== null) {
+                    // Letter, number, shift+letter
+                    name = ch.toLowerCase();
+                    shift = /^[A-Z]$/.exec(ch) !== null;
+                    meta = escaped;
+                    insertable = true;
+                }
+                else if (MAC_ALT_KEY_CHARACTER_MAP[ch] && process.platform === "darwin") {
+                    name = MAC_ALT_KEY_CHARACTER_MAP[ch];
+                    meta = true;
+                }
+                else if (sequence === "".concat(ESC).concat(ESC)) {
+                    // Double escape
+                    name = "escape";
+                    meta = true;
+                    // Emit first escape key here, then continue processing
+                    keypressHandler({
+                        name: "escape",
+                        ctrl: ctrl,
+                        meta: meta,
+                        shift: shift,
+                        insertable: false,
+                        sequence: ESC,
+                    });
+                }
+                else if (escaped) {
+                    // Escape sequence timeout
+                    name = ch.length ? undefined : "escape";
+                    meta = true;
+                }
+                else {
+                    // Any other character is considered printable.
+                    insertable = true;
+                }
+                _e.label = 40;
+            case 40:
+                if ((sequence.length !== 0 && (name !== undefined || escaped)) ||
+                    charLengthAt(sequence, 0) === sequence.length) {
+                    keypressHandler({
+                        name: name || "",
+                        ctrl: ctrl,
+                        meta: meta,
+                        shift: shift,
+                        insertable: insertable,
+                        sequence: sequence,
+                    });
+                }
+                return [3 /*break*/, 0];
+            case 41: return [2 /*return*/];
+        }
+    });
+}
+var KeypressContext = (0, react_1.createContext)(undefined);
+/**
+ * Hook to access the Keypress context.
+ * Allows components to subscribe and unsubscribe to keypress events.
+ *
+ * @returns The Keypress context value containing subscribe and unsubscribe methods.
+ * @throws Error if used outside of a KeypressProvider.
+ */
+function useKeypressContext() {
+    var context = (0, react_1.useContext)(KeypressContext);
+    if (!context) {
+        throw new Error("useKeypressContext must be used within a KeypressProvider");
+    }
+    return context;
+}
+/**
+ * Provider component for the Keypress context.
+ * Manages stdin data listening and parsing, and broadcasts key events to subscribers.
+ */
+function KeypressProvider(_a) {
+    var children = _a.children, _b = _a.kittyProtocol, kittyProtocol = _b === void 0 ? false : _b;
+    var stdin = (0, tinky_1.useStdin)().stdin;
+    var subscribers = (0, react_1.useRef)(new Set()).current;
+    var subscribe = (0, react_1.useCallback)(function (handler) { return subscribers.add(handler); }, [subscribers]);
+    var unsubscribe = (0, react_1.useCallback)(function (handler) { return subscribers.delete(handler); }, [subscribers]);
+    var broadcast = (0, react_1.useCallback)(function (key) { return subscribers.forEach(function (handler) { return handler(key); }); }, [subscribers]);
+    (0, react_1.useEffect)(function () {
+        process.stdin.setEncoding("utf8"); // Make data events emit strings
+        var processor = nonKeyboardEventFilter(broadcast);
+        if (!kittyProtocol) {
+            processor = bufferFastReturn(processor);
+        }
+        processor = bufferBackslashEnter(processor);
+        processor = bufferPaste(processor);
+        var dataListener = createDataListener(processor);
+        if (!stdin)
+            return;
+        var stdinStream = stdin;
+        stdinStream.on("data", dataListener);
+        return function () {
+            stdinStream.removeListener("data", dataListener);
+        };
+    }, [stdin, broadcast]);
+    return ((0, jsx_runtime_1.jsx)(KeypressContext.Provider, { value: { subscribe: subscribe, unsubscribe: unsubscribe }, children: children }));
+}

package/lib/hooks/use-keypress.d.ts

@@ -0,0 +1,12 @@
+import type { KeypressHandler, Key } from "../contexts/KeypressContext.js";
+export type { Key };
+/**
+ * A hook that listens for keypress events from stdin.
+ *
+ * @param onKeypress - The callback function to execute on each keypress.
+ * @param options - Options to control the hook's behavior.
+ * @param options.isActive - Whether the hook should be actively listening for input.
+ */
+export declare function useKeypress(onKeypress: KeypressHandler, { isActive }: {
+    isActive: boolean;
+}): void;

package/lib/hooks/use-keypress.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useKeypress = useKeypress;
+var react_1 = require("react");
+var KeypressContext_js_1 = require("../contexts/KeypressContext.js");
+/**
+ * A hook that listens for keypress events from stdin.
+ *
+ * @param onKeypress - The callback function to execute on each keypress.
+ * @param options - Options to control the hook's behavior.
+ * @param options.isActive - Whether the hook should be actively listening for input.
+ */
+function useKeypress(onKeypress, _a) {
+    var isActive = _a.isActive;
+    var _b = (0, KeypressContext_js_1.useKeypressContext)(), subscribe = _b.subscribe, unsubscribe = _b.unsubscribe;
+    (0, react_1.useEffect)(function () {
+        if (!isActive) {
+            return;
+        }
+        subscribe(onKeypress);
+        return function () {
+            unsubscribe(onKeypress);
+        };
+    }, [isActive, onKeypress, subscribe, unsubscribe]);
+}

package/lib/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Keypress Context and Provider
+ */
+export { KeypressProvider, useKeypressContext, BACKSLASH_ENTER_TIMEOUT, ESC_TIMEOUT, PASTE_TIMEOUT, FAST_RETURN_TIMEOUT, FOCUS_IN, FOCUS_OUT, type Key, type KeypressHandler, type KeypressContextValue, } from "./contexts/KeypressContext.js";
+/**
+ * Keypress hook
+ */
+export { useKeypress } from "./hooks/use-keypress.js";

package/lib/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useKeypress = exports.FOCUS_OUT = exports.FOCUS_IN = exports.FAST_RETURN_TIMEOUT = exports.PASTE_TIMEOUT = exports.ESC_TIMEOUT = exports.BACKSLASH_ENTER_TIMEOUT = exports.useKeypressContext = exports.KeypressProvider = void 0;
+/**
+ * Keypress Context and Provider
+ */
+var KeypressContext_js_1 = require("./contexts/KeypressContext.js");
+Object.defineProperty(exports, "KeypressProvider", { enumerable: true, get: function () { return KeypressContext_js_1.KeypressProvider; } });
+Object.defineProperty(exports, "useKeypressContext", { enumerable: true, get: function () { return KeypressContext_js_1.useKeypressContext; } });
+Object.defineProperty(exports, "BACKSLASH_ENTER_TIMEOUT", { enumerable: true, get: function () { return KeypressContext_js_1.BACKSLASH_ENTER_TIMEOUT; } });
+Object.defineProperty(exports, "ESC_TIMEOUT", { enumerable: true, get: function () { return KeypressContext_js_1.ESC_TIMEOUT; } });
+Object.defineProperty(exports, "PASTE_TIMEOUT", { enumerable: true, get: function () { return KeypressContext_js_1.PASTE_TIMEOUT; } });
+Object.defineProperty(exports, "FAST_RETURN_TIMEOUT", { enumerable: true, get: function () { return KeypressContext_js_1.FAST_RETURN_TIMEOUT; } });
+Object.defineProperty(exports, "FOCUS_IN", { enumerable: true, get: function () { return KeypressContext_js_1.FOCUS_IN; } });
+Object.defineProperty(exports, "FOCUS_OUT", { enumerable: true, get: function () { return KeypressContext_js_1.FOCUS_OUT; } });
+/**
+ * Keypress hook
+ */
+var use_keypress_js_1 = require("./hooks/use-keypress.js");
+Object.defineProperty(exports, "useKeypress", { enumerable: true, get: function () { return use_keypress_js_1.useKeypress; } });

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "tinky-keypress",
+  "version": "0.1.0",
+  "description": "Keypress handling context and hooks for Tinky",
+  "keywords": [
+    "tinky",
+    "react",
+    "cli",
+    "terminal",
+    "keypress",
+    "input",
+    "keyboard",
+    "stdin",
+    "tui"
+  ],
+  "homepage": "https://github.com/ByteLandTechnology/tinky-keypress#readme",
+  "bugs": {
+    "url": "https://github.com/ByteLandTechnology/tinky-keypress/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ByteLandTechnology/tinky-keypress.git"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "ByteLandTechnology"
+  },
+  "type": "module",
+  "main": "./lib/index.js",
+  "scripts": {
+    "test": "bun test",
+    "build": "tsc && npm run docs",
+    "lint": "eslint src tests",
+    "prepublish": "npm run build",
+    "prepare": "husky",
+    "docs": "typedoc --plugin typedoc-plugin-markdown --disableSources --out docs/api && prettier --write docs/api"
+  },
+  "peerDependencies": {
+    "tinky": "^1.1.2"
+  },
+  "files": [
+    "./bin/*",
+    "./lib/*"
+  ],
+  "typings": "./lib/index.d.ts",
+  "devDependencies": {
+    "@commitlint/cli": "^20.3.0",
+    "@commitlint/config-conventional": "^20.3.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.0",
+    "@semantic-release/npm": "^13.1.3",
+    "@types/bun": "^1.3.6",
+    "eslint": "^9.39.2",
+    "eslint-plugin-react": "^7.37.5",
+    "husky": "^9.1.7",
+    "jiti": "^2.6.1",
+    "lint-staged": "^16.2.7",
+    "prettier": "^3.7.4",
+    "typedoc": "^0.28.16",
+    "typedoc-plugin-markdown": "^4.9.0",
+    "typescript-eslint": "^8.53.0"
+  },
+  "commitlint": {
+    "extends": [
+      "@commitlint/config-conventional"
+    ]
+  },
+  "lint-staged": {
+    "*.{js,ts,jsx,tsx,json,md,yaml,yml}": "prettier --write"
+  }
+}