@uniflowed/tui 0.0.0-alpha.18 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniflowed/tui",
-  "version": "0.0.0-alpha.18",
+  "version": "0.15.0",
   "description": "A React renderer whose host is a terminal, following OpenTUI, for the Unified Toolchain for Flow.",
   "type": "module",
   "license": "MIT",
@@ -8,12 +8,13 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ubugeeei-prod/uf.git",
-    "directory": "packages/tui"
+    "directory": "npm/tui"
   },
   "exports": {
     ".": "./index.js",
     "./capability": "./capability.js",
     "./cells": "./cells.js",
+    "./clipboard": "./clipboard.js",
     "./components": "./components.js",
     "./diff": "./diff.js",
     "./keys": "./keys.js",
@@ -30,7 +31,7 @@
     "!*.test.js"
   ],
   "dependencies": {
-    "@uniflowed/react": "0.0.0-alpha.18",
-    "react-reconciler": "^0.33.0"
+    "@uniflowed/react": "0.15.0",
+    "react-reconciler": "^0.34.0"
   }
 }

package/terminal.js

@@ -37,6 +37,7 @@ import type { Capabilities, ColorChoice, TerminalEnv } from "./capability.js";
 import { FALLBACK_COLUMNS, FALLBACK_ROWS, detectCapabilities, detectSize } from "./capability.js";
 import type { Frame } from "./cells.js";
 import { frameText } from "./cells.js";
+import { osc52Clipboard } from "./clipboard.js";
 import type { Update } from "./diff.js";
 import type { Renderer } from "./internal/host.js";
 import {
@@ -74,6 +75,17 @@ const CLEAR = "\u001b[2J\u001b[H";
  */
 const ENABLE_PASTE = "\u001b[?2004h";
 const DISABLE_PASTE = "\u001b[?2004l";
+/**
+ * Ask terminals that understand Kitty's keyboard protocol to report all keys
+ * as `CSI u`, including repeat/release event types and associated text.
+ *
+ * The flags are pushed onto the terminal's keyboard-mode stack and popped on
+ * exit, so a shell or parent program gets back whatever mode it had before.
+ * Terminals that do not implement the protocol ignore these bytes and keep
+ * sending the legacy sequences `keys.js` already decodes.
+ */
+const ENABLE_KEYBOARD_PROTOCOL = "\u001b[>27u";
+const DISABLE_KEYBOARD_PROTOCOL = "\u001b[<u";
 /**
  * Ask the terminal to report the mouse, in the four modes that answer.
  *
@@ -136,20 +148,20 @@ export type OutputStream = {
   readonly rows?: number,
   readonly isTTY?: boolean,
   /** A real `process.stdout` emits `"resize"`; a string collector does not. */
-  on?: (event: string, listener: () => mixed) => mixed,
-  off?: (event: string, listener: () => mixed) => mixed,
+  readonly on?: (event: string, listener: () => mixed) => mixed,
+  readonly off?: (event: string, listener: () => mixed) => mixed,
   ...
 };
 
 /** Anything keys arrive from; `process.stdin`. */
 export type InputStream = {
   readonly isTTY?: boolean,
-  setRawMode?: (raw: boolean) => mixed,
-  resume?: () => mixed,
-  pause?: () => mixed,
-  setEncoding?: (encoding: string) => mixed,
-  on?: (event: string, listener: (chunk: string) => mixed) => mixed,
-  off?: (event: string, listener: (chunk: string) => mixed) => mixed,
+  readonly setRawMode?: (raw: boolean) => mixed,
+  readonly resume?: () => mixed,
+  readonly pause?: () => mixed,
+  readonly setEncoding?: (encoding: string) => mixed,
+  readonly on?: (event: string, listener: (chunk: string) => mixed) => mixed,
+  readonly off?: (event: string, listener: (chunk: string) => mixed) => mixed,
   ...
 };
 
@@ -188,6 +200,14 @@ export type RenderOptions = {
    * told that this window is the one where dragging does nothing.
    */
   readonly mouse?: boolean,
+  /**
+   * Whether `useClipboard()` may ask the terminal to copy text with OSC 52.
+   *
+   * On for interactive terminals, off for redirected output, and explicitly
+   * disableable for applications that prefer to expose "copy failed" over
+   * sending a sequence a terminal policy may reject without acknowledgement.
+   */
+  readonly clipboard?: boolean,
 };
 
 /**
@@ -208,7 +228,7 @@ function deliver(renderer: Renderer, event: InputEvent): void {
 /** Mount a tree into a renderer and return the pieces both drivers need. */
 function mount(element: React.Node, renderer: Renderer) {
   const root = createRoot(renderer);
-  root.render(React.createElement(RendererContext.Provider, { value: renderer }, element));
+  root.render(<RendererContext.Provider value={renderer}>{element}</RendererContext.Provider>);
   return root;
 }
 
@@ -297,15 +317,18 @@ export function testRender(
  * that has to call `stop()`.
  */
 export function render(element: React.Node, options: RenderOptions = {}): Handle {
-  // Three casts, and the same reason for all of them: Flow's library
-  // definition for `process` describes Node's classes, and these types
-  // describe the three things this renderer actually needs — so that a test
-  // can pass a string collector, and so that a runtime whose streams are not
-  // Node's is not excluded by a type. The narrowing is checked at run time by
-  // the `!= null` guards below rather than trusted.
-  const stdout: OutputStream = options.stdout ?? (process.stdout: $FlowFixMe);
-  const stdin: InputStream = options.stdin ?? (process.stdin: $FlowFixMe);
-  const env: TerminalEnv = options.env ?? (process.env: $FlowFixMe);
+  // Two casts, and the same reason for both: Flow's library definition for
+  // `process` describes Node's classes, and these types describe the things
+  // this renderer actually needs — so that a test can pass a string collector,
+  // and so that a runtime whose streams are not Node's is not excluded by a
+  // type. A class instance is not a subtype of an object type, and an
+  // interface cannot say that `on` is an optional *method*, which is what a
+  // collector without listeners needs. The narrowing is checked at run time by
+  // the `!= null` guards below rather than trusted. `process.env` needs no
+  // cast: `TerminalEnv` is the inexact subset of it rendering reads.
+  const stdout: OutputStream = options.stdout ?? (process.stdout as $FlowFixMe);
+  const stdin: InputStream = options.stdin ?? (process.stdin as $FlowFixMe);
+  const env: TerminalEnv = options.env ?? process.env;
   const capabilities = detectCapabilities(
     options.color ?? "auto",
     stdout.isTTY === true ? "interactive" : "piped",
@@ -322,6 +345,9 @@ export function render(element: React.Node, options: RenderOptions = {}): Handle
   const size = detectSize(env, stdout);
   const mouse = (options.mouse ?? false) && interactive;
   const renderer = createRenderer(size.columns, size.rows, capabilities, mouse);
+  if ((options.clipboard ?? true) && interactive) {
+    renderer.clipboard = osc52Clipboard((chunk) => stdout.write(chunk));
+  }
 
   let stopped = false;
   let scheduled = false;
@@ -356,6 +382,7 @@ export function render(element: React.Node, options: RenderOptions = {}): Handle
       (alternateScreen ? ENTER_ALTERNATE : "") +
         HIDE_CURSOR +
         ENABLE_PASTE +
+        ENABLE_KEYBOARD_PROTOCOL +
         (mouse ? ENABLE_MOUSE : "") +
         CLEAR,
     );
@@ -392,7 +419,9 @@ export function render(element: React.Node, options: RenderOptions = {}): Handle
     if (stdin.resume != null) {
       stdin.resume();
     }
-    stdin.on("data", onData);
+    // Optional call: the calls above may have changed `stdin`, as far as Flow
+    // knows, so the `!= null` test at the top of this block no longer holds.
+    stdin.on?.("data", onData);
   }
   if (interactive && stdout.on != null) {
     stdout.on("resize", onResize);
@@ -431,6 +460,7 @@ export function render(element: React.Node, options: RenderOptions = {}): Handle
         }
         stdout.write(
           (mouse ? DISABLE_MOUSE : "") +
+            DISABLE_KEYBOARD_PROTOCOL +
             DISABLE_PASTE +
             SHOW_CURSOR +
             (alternateScreen ? LEAVE_ALTERNATE : "\n"),

package/widths.js

@@ -141,7 +141,10 @@ export function scalarWidth(code: number): number {
 export function graphemeWidth(cluster: string): number {
   let width = 0;
   let previousNarrow = false;
-  for (const character of cluster) {
+  // `new String(…)` because Flow does not let a primitive string stand for an
+  // `Iterable` (facebook/flow's tests/interface/string.js). The wrapper
+  // iterates the same code points.
+  for (const character of new String(cluster)) {
     const code = character.codePointAt(0) ?? 0;
     if (code === ZWJ) {
       previousNarrow = false;