@cel-tui/core 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cel-tui/core",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Core framework engine for cel-tui — primitives, layout, rendering, input",
   "type": "module",
   "module": "src/index.ts",
@@ -34,7 +34,7 @@
     "layout"
   ],
   "dependencies": {
-    "@cel-tui/types": "0.3.0",
+    "@cel-tui/types": "0.4.1",
     "get-east-asian-width": "^1.5.0"
   },
   "peerDependencies": {

package/src/cel.ts

@@ -1,4 +1,9 @@
-import type { Node, Theme } from "@cel-tui/types";
+import type {
+  Node,
+  TextInputNode,
+  TextInputProps,
+  Theme,
+} from "@cel-tui/types";
 import { CellBuffer } from "./cell-buffer.js";
 import { emitBuffer, emitDiff, defaultTheme } from "./emitter.js";
 import {
@@ -8,7 +13,7 @@ import {
   collectKeyPressHandlers,
   collectFocusable,
 } from "./hit-test.js";
-import { parseKey, isEditingKey } from "./keys.js";
+import { decodeKeyEvents, isEditingKey, type KeyInput } from "./keys.js";
 import { layout, type LayoutNode } from "./layout.js";
 import {
   paint,
@@ -26,10 +31,18 @@ import {
   type EditState,
 } from "./text-edit.js";
 import type { Terminal } from "./terminal.js";
-import { visibleWidth } from "./width.js";
+import { getMaxScrollOffset, getScrollStep } from "./scroll.js";
 
 type RenderFn = () => Node | Node[];
 
+type TerminalCursorState =
+  | { visible: false }
+  | {
+      visible: true;
+      x: number;
+      y: number;
+    };
+
 let terminal: Terminal | null = null;
 let activeTheme: Theme = defaultTheme;
 let renderFn: RenderFn | null = null;
@@ -60,6 +73,9 @@ const uncontrolledScrollOffsets = new Map<string, number>();
 /** Nodes whose props were stamped with scrollOffset during the last paint. */
 let stampedScrollNodes: { node: Node; key: string }[] = [];
 
+/** The cursor state currently expected on the terminal. */
+let lastTerminalCursor: TerminalCursorState | null = { visible: false };
+
 function doRender(): void {
   renderScheduled = false;
   if (!renderFn || !terminal) return;
@@ -105,43 +121,38 @@ function doRender(): void {
   unstampUncontrolledFocus();
   unstampUncontrolledScroll();
 
+  const nextCursor = getDesiredTerminalCursor();
+
   // Emit to terminal — differential when possible
   if (prevBuffer) {
-    const output = emitDiff(prevBuffer, currentBuffer, activeTheme);
+    const output = emitDiff(prevBuffer, currentBuffer, activeTheme, {
+      cursor: nextCursor,
+      previousCursor: lastTerminalCursor,
+    });
     if (output.length > 0) terminal.write(output);
   } else {
-    const output = emitBuffer(currentBuffer, activeTheme);
+    const output = emitBuffer(currentBuffer, activeTheme, {
+      cursor: nextCursor,
+      previousCursor: lastTerminalCursor,
+    });
     terminal.write(output);
   }
 
-  // Position the native terminal cursor at the focused TextInput's cursor.
-  // This gives us a blinking cursor for free (terminal-managed blink).
-  positionTerminalCursor();
+  lastTerminalCursor = nextCursor;
 }
 
 /**
- * After each render, show the native terminal cursor at the focused
- * TextInput's cursor position (gives blinking for free). When no
- * TextInput is focused, hide the cursor.
+ * Resolve the final terminal cursor state for the current frame.
+ * The cursor is shown only for a focused TextInput whose cursor is visible
+ * within the clipped viewport.
  */
-function positionTerminalCursor(): void {
-  if (!terminal) return;
-
-  // Find focused TextInput in the layout tree (check stamped state during
-  // render — we need to check controlled focus in the current layouts)
+function getDesiredTerminalCursor(): TerminalCursorState {
   const focusedTI = findFocusedTextInputLayout();
-  if (focusedTI) {
-    const props = focusedTI.node
-      .props as import("@cel-tui/types").TextInputProps;
-    const pos = getTextInputCursorScreenPos(props, focusedTI.rect);
-    if (pos) {
-      // CUP: move cursor to (row, col) — 1-indexed
-      terminal.write(`\x1b[${pos.y + 1};${pos.x + 1}H`);
-      terminal.showCursor();
-      return;
-    }
-  }
-  terminal.hideCursor();
+  if (!focusedTI) return { visible: false };
+
+  const props = focusedTI.node.props as import("@cel-tui/types").TextInputProps;
+  const pos = getTextInputCursorScreenPos(props, focusedTI.rect);
+  return pos ? { visible: true, x: pos.x, y: pos.y } : { visible: false };
 }
 
 /**
@@ -189,25 +200,49 @@ const SGR_MOUSE_RE = /\x1b\[<(\d+);(\d+);(\d+)([Mm])/g;
 // need to remember the offset we already dispatched via onScroll.
 let batchScrollOffsets: Map<object, number> | null = null;
 
+// Tracks the focused TextInput's latest edit state during a batched keyboard
+// chunk. The layout tree does not re-render until the next tick, so subsequent
+// keys in the same chunk must see the updated value/cursor immediately.
+let batchTextInputEdits: Map<TextInputProps, EditState> | null = null;
+
 function handleInput(data: string): void {
-  // Terminals may batch multiple mouse events into one data chunk.
-  // Scan for all SGR mouse sequences and handle each one.
   SGR_MOUSE_RE.lastIndex = 0;
-  let match = SGR_MOUSE_RE.exec(data);
-  if (match) {
-    batchScrollOffsets = new Map();
+  batchTextInputEdits = new Map();
+
+  let lastIndex = 0;
+
+  try {
+    let match = SGR_MOUSE_RE.exec(data);
     while (match) {
+      if (match.index > lastIndex) {
+        handleKeyChunk(data.slice(lastIndex, match.index));
+      }
+
+      if (batchScrollOffsets === null) {
+        batchScrollOffsets = new Map();
+      }
+
       const mouse = parseSgrMatch(match);
       if (mouse) handleMouseEvent(mouse);
+
+      lastIndex = match.index + match[0].length;
       match = SGR_MOUSE_RE.exec(data);
     }
+
+    if (lastIndex < data.length) {
+      handleKeyChunk(data.slice(lastIndex));
+    }
+  } finally {
     batchScrollOffsets = null;
-    return;
+    batchTextInputEdits = null;
   }
+}
 
-  // Keyboard input
-  const key = parseKey(data);
-  handleKeyEvent(key, data);
+function handleKeyChunk(data: string): void {
+  if (data.length === 0) return;
+  for (const key of decodeKeyEvents(data)) {
+    handleKeyEvent(key);
+  }
 }
 
 interface MouseEvent {
@@ -453,49 +488,6 @@ function changeFocus(target: LayoutNode | null): void {
   }
 }
 
-/**
- * Compute the maximum scroll offset for a scrollable container or TextInput.
- * Returns 0 if content fits within the viewport.
- */
-function getMaxScrollOffset(target: LayoutNode): number {
-  const { rect, children } = target;
-
-  // TextInput: compute content height from wrapped text value
-  if (target.node.type === "textinput") {
-    const w = rect.width;
-    const value = target.node.props.value;
-    let lineCount = 0;
-    for (const rawLine of value.split("\n")) {
-      const lw = visibleWidth(rawLine);
-      lineCount += w > 0 && lw > w ? Math.ceil(lw / w) : 1;
-    }
-    return Math.max(0, lineCount - rect.height);
-  }
-
-  const isVertical = target.node.type === "vstack";
-  const props = target.node.type !== "text" ? target.node.props : null;
-  const padX = (props as any)?.padding?.x ?? 0;
-  const padY = (props as any)?.padding?.y ?? 0;
-
-  if (isVertical) {
-    let contentHeight = 0;
-    for (const child of children) {
-      const childBottom = child.rect.y + child.rect.height - rect.y;
-      if (childBottom > contentHeight) contentHeight = childBottom;
-    }
-    // Viewport is the inner height (minus bottom padding)
-    // Content starts at padY, so contentHeight includes top padding offset
-    return Math.max(0, contentHeight + padY - rect.height);
-  } else {
-    let contentWidth = 0;
-    for (const child of children) {
-      const childRight = child.rect.x + child.rect.width - rect.x;
-      if (childRight > contentWidth) contentWidth = childRight;
-    }
-    return Math.max(0, contentWidth + padX - rect.width);
-  }
-}
-
 /**
  * Resolve the current scroll offset for a layout node.
  * Checks controlled (props.scrollOffset), then uncontrolled (path-based map).
@@ -539,7 +531,8 @@ function handleMouseEvent(event: MouseEvent): void {
     if (event.type === "scroll-up" || event.type === "scroll-down") {
       const target = findScrollTarget(path);
       if (target) {
-        const delta = event.type === "scroll-up" ? -1 : 1;
+        const step = getScrollStep(target);
+        const delta = event.type === "scroll-up" ? -step : step;
         const maxOffset = getMaxScrollOffset(target);
 
         if (target.node.type === "textinput") {
@@ -608,7 +601,18 @@ function findClickFocusTarget(path: LayoutNode[]): LayoutNode | null {
   return null;
 }
 
-function handleKeyEvent(key: string, rawData?: string): void {
+function getTextInputEditState(props: TextInputProps): EditState {
+  const batched = batchTextInputEdits?.get(props);
+  if (batched) return batched;
+  return {
+    value: props.value,
+    cursor: getTextInputCursor(props),
+  };
+}
+
+function handleKeyEvent(event: KeyInput): void {
+  const { key, text } = event;
+
   // --- Focus traversal keys ---
 
   // Tab / Shift+Tab: cycle through focusable elements
@@ -682,12 +686,10 @@ function handleKeyEvent(key: string, rawData?: string): void {
   }
 
   // --- TextInput key routing ---
-  // Find the focused TextInput (if any) to route editing keys
   const focusedInput = findFocusedTextInput();
 
   if (focusedInput) {
-    const props = focusedInput.node
-      .props as import("@cel-tui/types").TextInputProps;
+    const props = focusedInput.node.props as TextInputProps;
 
     // onKeyPress fires before editing — return false prevents the default action
     if (props.onKeyPress) {
@@ -698,12 +700,12 @@ function handleKeyEvent(key: string, rawData?: string): void {
       }
     }
 
-    // Editing keys are consumed by TextInput
-    if (isEditingKey(key)) {
-      const cursor = getTextInputCursor(props);
-      const editState: EditState = { value: props.value, cursor };
-      let newState: EditState | null = null;
+    let newState: EditState | null = null;
+    const editState = getTextInputEditState(props);
 
+    if (text !== undefined) {
+      newState = insertChar(editState, text);
+    } else if (isEditingKey(key)) {
       switch (key) {
         case "backspace":
           newState = deleteBackward(editState);
@@ -719,8 +721,7 @@ function handleKeyEvent(key: string, rawData?: string): void {
         case "end":
           {
             const tiPadX =
-              (focusedInput.node as import("@cel-tui/types").TextInputNode)
-                .props.padding?.x ?? 0;
+              (focusedInput.node as TextInputNode).props.padding?.x ?? 0;
             const contentWidth = Math.max(
               0,
               focusedInput.rect.width - tiPadX * 2,
@@ -745,24 +746,17 @@ function handleKeyEvent(key: string, rawData?: string): void {
         case "plus":
           newState = insertChar(editState, "+");
           break;
-        default:
-          // Single printable character — use raw data to preserve case
-          if (key.length === 1 && rawData && rawData.length === 1) {
-            newState = insertChar(editState, rawData);
-          } else if (key.length === 1) {
-            newState = insertChar(editState, key);
-          }
-          break;
       }
+    }
 
-      if (newState && newState !== editState) {
-        setTextInputCursor(props, newState.cursor);
-        if (newState.value !== editState.value) {
-          props.onChange(newState.value);
-        }
-        cel.render();
-        return;
+    if (newState && newState !== editState) {
+      batchTextInputEdits?.set(props, newState);
+      setTextInputCursor(props, newState.cursor);
+      if (newState.value !== editState.value) {
+        props.onChange(newState.value);
       }
+      cel.render();
+      return;
     }
   }
 
@@ -890,6 +884,7 @@ export const cel = {
   init(term: Terminal, options?: { theme?: Theme }): void {
     terminal = term;
     activeTheme = options?.theme ?? defaultTheme;
+    lastTerminalCursor = { visible: false };
     terminal.start(handleInput, () => cel.render());
   },
 
@@ -935,6 +930,7 @@ export const cel = {
     stampedNode = null;
     uncontrolledScrollOffsets.clear();
     stampedScrollNodes = [];
+    lastTerminalCursor = { visible: false };
     activeTheme = defaultTheme;
   },
 

package/src/emitter.ts

@@ -100,8 +100,61 @@ function hasStyle(cell: Cell): boolean {
 const SYNC_START = "\x1b[?2026h";
 const SYNC_END = "\x1b[?2026l";
 const CURSOR_HOME = "\x1b[H";
+const HIDE_CURSOR = "\x1b[?25l";
+const SHOW_CURSOR = "\x1b[?25h";
+const SAVE_CURSOR = "\x1b7";
+const RESTORE_CURSOR = "\x1b8";
 const RESET = "\x1b[0m";
 
+type CursorState =
+  | { visible: false }
+  | {
+      visible: true;
+      x: number;
+      y: number;
+    };
+
+interface EmitOptions {
+  cursor?: CursorState;
+  previousCursor?: CursorState | null;
+}
+
+function sameVisibleCursor(
+  a: CursorState | null | undefined,
+  b: CursorState | null | undefined,
+): boolean {
+  return (
+    a?.visible === true && b?.visible === true && a.x === b.x && a.y === b.y
+  );
+}
+
+function getCursorControls(
+  options: EmitOptions | undefined,
+  hasPaintOutput: boolean,
+): { prefix: string; suffix: string } {
+  const cursor = options?.cursor ?? { visible: false };
+  const previous = options?.previousCursor ?? null;
+
+  if (sameVisibleCursor(cursor, previous)) {
+    return hasPaintOutput
+      ? { prefix: SAVE_CURSOR, suffix: RESTORE_CURSOR }
+      : { prefix: "", suffix: "" };
+  }
+
+  if (cursor.visible) {
+    return {
+      prefix: "",
+      suffix:
+        `\x1b[${cursor.y + 1};${cursor.x + 1}H` +
+        (previous?.visible === true ? "" : SHOW_CURSOR),
+    };
+  }
+
+  return previous?.visible === true
+    ? { prefix: "", suffix: HIDE_CURSOR }
+    : { prefix: "", suffix: "" };
+}
+
 /**
  * Emit a full cell buffer as an ANSI string for terminal output.
  *
@@ -114,13 +167,16 @@ const RESET = "\x1b[0m";
  *
  * @param buf - The cell buffer to render.
  * @param theme - Color theme mapping. Defaults to the ANSI 16 theme.
+ * @param options - Optional terminal cursor state to apply before the synchronized output ends.
  * @returns A complete ANSI string ready to write to the terminal.
  */
 export function emitBuffer(
   buf: CellBuffer,
   theme: Theme = defaultTheme,
+  options?: EmitOptions,
 ): string {
-  let out = SYNC_START + CURSOR_HOME;
+  const cursorControls = getCursorControls(options, true);
+  let out = SYNC_START + cursorControls.prefix + CURSOR_HOME;
 
   let lastStyle: Cell | null = null;
 
@@ -153,7 +209,7 @@ export function emitBuffer(
     out += RESET;
   }
 
-  out += SYNC_END;
+  out += cursorControls.suffix + SYNC_END;
   return out;
 }
 
@@ -167,18 +223,21 @@ export function emitBuffer(
  * @param prev - The previous buffer.
  * @param next - The new buffer.
  * @param theme - Color theme mapping. Defaults to the ANSI 16 theme.
+ * @param options - Optional terminal cursor state to apply before the synchronized output ends.
  * @returns An ANSI string with only the changed cells.
  */
 export function emitDiff(
   prev: CellBuffer,
   next: CellBuffer,
   theme: Theme = defaultTheme,
+  options?: EmitOptions,
 ): string {
-  let out = SYNC_START;
-
   const changes = prev.diff(next);
+  const cursorControls = getCursorControls(options, changes.length > 0);
+  let out = SYNC_START + cursorControls.prefix;
+
   if (changes.length === 0) {
-    return out + SYNC_END;
+    return out + cursorControls.suffix + SYNC_END;
   }
 
   let lastStyle: Cell | null = null;
@@ -222,6 +281,6 @@ export function emitDiff(
     out += RESET;
   }
 
-  out += SYNC_END;
+  out += cursorControls.suffix + SYNC_END;
   return out;
 }