@cel-tui/core 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cel-tui/core",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Core framework engine for cel-tui — primitives, layout, rendering, input",
   "type": "module",
   "module": "src/index.ts",
@@ -14,7 +14,8 @@
   },
   "files": [
     "src/**/*.ts",
-    "!src/**/*.test.ts"
+    "!src/**/*.test.ts",
+    "!src/test-helpers.ts"
   ],
   "license": "MIT",
   "repository": {

package/src/cel.ts

@@ -1,11 +1,11 @@
-import type { Node } from "@cel-tui/types";
+import type { Node, Theme } from "@cel-tui/types";
 import { CellBuffer } from "./cell-buffer.js";
-import { emitBuffer, emitDiff } from "./emitter.js";
+import { emitBuffer, emitDiff, defaultTheme } from "./emitter.js";
 import {
   hitTest,
   findClickHandler,
   findScrollTarget,
-  findKeyPressHandler,
+  collectKeyPressHandlers,
   collectFocusable,
 } from "./hit-test.js";
 import { parseKey, isEditingKey, normalizeKey } from "./keys.js";
@@ -16,8 +16,7 @@ import {
   setTextInputCursor,
   getTextInputScroll,
   setTextInputScroll,
-  getContainerScroll,
-  setContainerScroll,
+  getTextInputCursorScreenPos,
 } from "./paint.js";
 import {
   insertChar,
@@ -32,6 +31,7 @@ import { visibleWidth } from "./width.js";
 type RenderFn = () => Node | Node[];
 
 let terminal: Terminal | null = null;
+let activeTheme: Theme = defaultTheme;
 let renderFn: RenderFn | null = null;
 let renderScheduled = false;
 let prevBuffer: CellBuffer | null = null;
@@ -49,6 +49,17 @@ let frameworkFocusIndex = -1;
 /** The node whose props were stamped with `focused: true` during the last paint. */
 let stampedNode: LayoutNode | null = null;
 
+/**
+ * Uncontrolled scroll offsets, keyed by structural tree path.
+ * The path is a string like "0/2/1" representing the DFS child indices
+ * from the layer root to the scrollable container. This survives re-renders
+ * because the structural position is the same even with new props objects.
+ */
+const uncontrolledScrollOffsets = new Map<string, number>();
+
+/** Nodes whose props were stamped with scrollOffset during the last paint. */
+let stampedScrollNodes: { node: Node; key: string }[] = [];
+
 function doRender(): void {
   renderScheduled = false;
   if (!renderFn || !terminal) return;
@@ -81,8 +92,9 @@ function doRender(): void {
     currentLayouts.push(layoutTree);
   }
 
-  // Stamp uncontrolled focus before painting so focusStyle and cursor work
+  // Stamp uncontrolled focus and scroll before painting
   stampUncontrolledFocus();
+  stampUncontrolledScroll();
 
   // Paint each layer into the buffer
   for (const layoutTree of currentLayouts) {
@@ -91,15 +103,79 @@ function doRender(): void {
 
   // Unstamp after paint so input handlers see clean props
   unstampUncontrolledFocus();
+  unstampUncontrolledScroll();
 
   // Emit to terminal — differential when possible
   if (prevBuffer) {
-    const output = emitDiff(prevBuffer, currentBuffer);
+    const output = emitDiff(prevBuffer, currentBuffer, activeTheme);
     if (output.length > 0) terminal.write(output);
   } else {
-    const output = emitBuffer(currentBuffer);
+    const output = emitBuffer(currentBuffer, activeTheme);
     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();
+}
+
+/**
+ * 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.
+ */
+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)
+  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();
+}
+
+/**
+ * Find the focused TextInput in the current layout tree.
+ * Checks controlled focus (props.focused) and uncontrolled
+ * (framework-tracked index). Returns the LayoutNode or null.
+ */
+function findFocusedTextInputLayout(): LayoutNode | null {
+  // Check controlled focus: scan all layers for TextInput with focused: true
+  for (let i = currentLayouts.length - 1; i >= 0; i--) {
+    const found = findFocusedTIInTree(currentLayouts[i]!);
+    if (found) return found;
+  }
+  // Check uncontrolled focus
+  if (frameworkFocusIndex >= 0) {
+    const topLayer = currentLayouts[currentLayouts.length - 1];
+    if (topLayer) {
+      const focusables = collectFocusable(topLayer);
+      if (frameworkFocusIndex < focusables.length) {
+        const target = focusables[frameworkFocusIndex]!;
+        if (target.node.type === "textinput") return target;
+      }
+    }
+  }
+  return null;
+}
+
+function findFocusedTIInTree(ln: LayoutNode): LayoutNode | null {
+  if (ln.node.type === "textinput" && ln.node.props.focused) return ln;
+  for (const child of ln.children) {
+    const found = findFocusedTIInTree(child);
+    if (found) return found;
+  }
+  return null;
 }
 
 // --- Input handling ---
@@ -252,6 +328,75 @@ function unstampUncontrolledFocus(): void {
   stampedNode = null;
 }
 
+/**
+ * Compute the structural tree path from a layer root to a target LayoutNode.
+ * Returns a string like "0/2/1" or null if target is not in the tree.
+ */
+function computeTreePath(root: LayoutNode, target: LayoutNode): string | null {
+  if (root === target) return "";
+  for (let i = 0; i < root.children.length; i++) {
+    const sub = computeTreePath(root.children[i]!, target);
+    if (sub !== null) return sub === "" ? String(i) : `${i}/${sub}`;
+  }
+  return null;
+}
+
+/**
+ * Get the full path key for a scrollable node, prefixed by layer index.
+ */
+function getScrollPathKey(target: LayoutNode): string | null {
+  for (let i = 0; i < currentLayouts.length; i++) {
+    const path = computeTreePath(currentLayouts[i]!, target);
+    if (path !== null) return `L${i}:${path}`;
+  }
+  return null;
+}
+
+/**
+ * Stamp `scrollOffset` on uncontrolled scrollable containers' props
+ * before painting, so paint reads the correct offset.
+ */
+function stampUncontrolledScroll(): void {
+  stampedScrollNodes = [];
+  if (uncontrolledScrollOffsets.size === 0) return;
+  for (let i = 0; i < currentLayouts.length; i++) {
+    walkAndStampScroll(currentLayouts[i]!, `L${i}:`);
+  }
+}
+
+function walkAndStampScroll(ln: LayoutNode, pathKey: string): void {
+  const node = ln.node;
+  if (node.type === "vstack" || node.type === "hstack") {
+    if (
+      node.props.overflow === "scroll" &&
+      node.props.scrollOffset === undefined &&
+      !node.props.onScroll
+    ) {
+      const offset = uncontrolledScrollOffsets.get(pathKey);
+      if (offset !== undefined && offset !== 0) {
+        (node.props as any).scrollOffset = offset;
+        stampedScrollNodes.push({ node, key: pathKey });
+      }
+    }
+  }
+  for (let i = 0; i < ln.children.length; i++) {
+    // Keys match getScrollPathKey format: "L0:" for root, "L0:2" for child 2, "L0:2/1" for grandchild
+    const childKey = pathKey.endsWith(":")
+      ? `${pathKey}${i}`
+      : `${pathKey}/${i}`;
+    walkAndStampScroll(ln.children[i]!, childKey);
+  }
+}
+
+function unstampUncontrolledScroll(): void {
+  for (const { node } of stampedScrollNodes) {
+    if (node.type === "vstack" || node.type === "hstack") {
+      delete (node.props as any).scrollOffset;
+    }
+  }
+  stampedScrollNodes = [];
+}
+
 /**
  * Blur the currently focused element and focus a new one.
  * Manages both controlled (via onFocus/onBlur callbacks) and
@@ -328,6 +473,9 @@ function getMaxScrollOffset(target: LayoutNode): number {
   }
 
   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;
@@ -335,22 +483,42 @@ function getMaxScrollOffset(target: LayoutNode): number {
       const childBottom = child.rect.y + child.rect.height - rect.y;
       if (childBottom > contentHeight) contentHeight = childBottom;
     }
-    return Math.max(0, contentHeight - rect.height);
+    // 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 - rect.width);
+    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).
+ */
+function resolveScrollOffset(ln: import("./layout.js").LayoutNode): number {
+  const node = ln.node;
+  if (node.type === "text") return 0;
+  const props = node.props;
+  if ((props as any).scrollOffset !== undefined)
+    return (props as any).scrollOffset;
+  // Check uncontrolled map
+  const pathKey = getScrollPathKey(ln);
+  if (pathKey !== null) {
+    return uncontrolledScrollOffsets.get(pathKey) ?? 0;
   }
+  return 0;
 }
 
 function handleMouseEvent(event: MouseEvent): void {
   // Hit test on topmost layer first
   for (let i = currentLayouts.length - 1; i >= 0; i--) {
     const layoutRoot = currentLayouts[i]!;
-    const path = hitTest(layoutRoot, event.x, event.y);
+    const path = hitTest(layoutRoot, event.x, event.y, resolveScrollOffset);
     if (path.length === 0) continue;
 
     if (event.type === "click") {
@@ -383,7 +551,7 @@ function handleMouseEvent(event: MouseEvent): void {
           cel.render();
         } else {
           const props = target.node.type !== "text" ? target.node.props : null;
-          if (props && "onScroll" in props) {
+          if (props && (props as any).overflow === "scroll") {
             if (props.onScroll) {
               // Controlled scroll: notify app.
               // Use batch accumulator if available (multiple events in one chunk),
@@ -397,12 +565,18 @@ function handleMouseEvent(event: MouseEvent): void {
                 Math.min(maxOffset, baseOffset + delta),
               );
               batchScrollOffsets?.set(props, newOffset);
-              props.onScroll(newOffset);
+              props.onScroll(newOffset, maxOffset);
             } else {
-              // Uncontrolled scroll: framework manages state
-              const current = getContainerScroll(props);
-              const clamped = Math.max(0, Math.min(maxOffset, current + delta));
-              setContainerScroll(props, clamped);
+              // Uncontrolled scroll: framework manages state via path key
+              const pathKey = getScrollPathKey(target);
+              if (pathKey !== null) {
+                const current = uncontrolledScrollOffsets.get(pathKey) ?? 0;
+                const clamped = Math.max(
+                  0,
+                  Math.min(maxOffset, current + delta),
+                );
+                uncontrolledScrollOffsets.set(pathKey, clamped);
+              }
             }
             cel.render();
           }
@@ -420,12 +594,11 @@ function findClickFocusTarget(path: LayoutNode[]): LayoutNode | null {
   for (let i = path.length - 1; i >= 0; i--) {
     const node = path[i]!.node;
     if (node.type === "textinput") return path[i]!;
-    if (
-      (node.type === "vstack" || node.type === "hstack") &&
-      node.props.onClick &&
-      node.props.focusable !== false
-    ) {
-      return path[i]!;
+    if (node.type === "vstack" || node.type === "hstack") {
+      const isFocusable =
+        node.props.focusable === true ||
+        (node.props.onClick != null && node.props.focusable !== false);
+      if (isFocusable) return path[i]!;
     }
   }
   return null;
@@ -539,11 +712,20 @@ function handleKeyEvent(key: string, rawData?: string): void {
         case "down":
         case "home":
         case "end":
-          newState = moveCursor(
-            editState,
-            key as "left" | "right" | "up" | "down" | "home" | "end",
-            focusedInput.rect.width,
-          );
+          {
+            const tiPadX =
+              (focusedInput.node as import("@cel-tui/types").TextInputNode)
+                .props.padding?.x ?? 0;
+            const contentWidth = Math.max(
+              0,
+              focusedInput.rect.width - tiPadX * 2,
+            );
+            newState = moveCursor(
+              editState,
+              key as "left" | "right" | "up" | "down" | "home" | "end",
+              contentWidth,
+            );
+          }
           break;
         case "enter":
           newState = insertChar(editState, "\n");
@@ -551,6 +733,12 @@ function handleKeyEvent(key: string, rawData?: string): void {
         case "tab":
           newState = insertChar(editState, "\t");
           break;
+        case "space":
+          newState = insertChar(editState, " ");
+          break;
+        case "plus":
+          newState = insertChar(editState, "+");
+          break;
         default:
           // Single printable character — use raw data to preserve case
           if (key.length === 1 && rawData && rawData.length === 1) {
@@ -578,10 +766,21 @@ function handleKeyEvent(key: string, rawData?: string): void {
     for (let i = currentLayouts.length - 1; i >= 0; i--) {
       const path = findPathTo(currentLayouts[i]!, focused);
       if (path) {
-        const handler = findKeyPressHandler(path);
-        if (handler) {
-          handler.handler(key);
-          cel.render();
+        const handlers = collectKeyPressHandlers(path);
+        if (handlers.length > 0) {
+          let consumed = false;
+          for (const h of handlers) {
+            const result = h.handler(key);
+            if (result !== false) {
+              consumed = true;
+              break;
+            }
+            // result === false → key not consumed, keep bubbling
+          }
+          // Always return — the key was offered to every handler in the
+          // focused element's path (including root). Even if all returned
+          // false, we don't retry via the unfocused fallback path.
+          if (consumed) cel.render();
           return;
         }
       }
@@ -592,9 +791,12 @@ function handleKeyEvent(key: string, rawData?: string): void {
   for (let i = currentLayouts.length - 1; i >= 0; i--) {
     const layoutRoot = currentLayouts[i]!;
     const path = [layoutRoot];
-    const handler = findKeyPressHandler(path);
-    if (handler) {
-      handler.handler(key);
+    const handlers = collectKeyPressHandlers(path);
+    if (handlers.length > 0) {
+      for (const h of handlers) {
+        const result = h.handler(key);
+        if (result !== false) break;
+      }
       cel.render();
       return;
     }
@@ -663,10 +865,16 @@ export const cel = {
    * Initialize the framework with a terminal implementation.
    * Must be called before {@link cel.viewport}.
    *
+   * Enables the Kitty keyboard protocol (level 1) via the terminal,
+   * enters raw mode, and starts mouse tracking.
+   *
    * @param term - Terminal to render to (ProcessTerminal or MockTerminal).
+   * @param options - Optional configuration.
+   * @param options.theme - Color theme mapping. Defaults to the ANSI 16 theme.
    */
-  init(term: Terminal): void {
+  init(term: Terminal, options?: { theme?: Theme }): void {
     terminal = term;
+    activeTheme = options?.theme ?? defaultTheme;
     terminal.start(handleInput, () => cel.render());
   },
 
@@ -695,6 +903,9 @@ export const cel = {
 
   /**
    * Stop the framework and restore terminal state.
+   *
+   * Pops the Kitty keyboard protocol mode, disables mouse tracking,
+   * and restores the terminal to its previous state.
    */
   stop(): void {
     terminal?.stop();
@@ -707,6 +918,9 @@ export const cel = {
     lastFocusedIndex = -1;
     frameworkFocusIndex = -1;
     stampedNode = null;
+    uncontrolledScrollOffsets.clear();
+    stampedScrollNodes = [];
+    activeTheme = defaultTheme;
   },
 
   /** @internal */

package/src/emitter.ts

@@ -1,56 +1,76 @@
-import type { Color } from "@cel-tui/types";
+import type { Color, Theme, ThemeValue } from "@cel-tui/types";
 import type { Cell } from "./cell-buffer.js";
 import { CellBuffer, EMPTY_CELL } from "./cell-buffer.js";
 
-// --- Color mapping ---
-
-const FG_CODES: Record<Color, number> = {
-  black: 30,
-  red: 31,
-  green: 32,
-  yellow: 33,
-  blue: 34,
-  magenta: 35,
-  cyan: 36,
-  white: 37,
-  brightBlack: 90,
-  brightRed: 91,
-  brightGreen: 92,
-  brightYellow: 93,
-  brightBlue: 94,
-  brightMagenta: 95,
-  brightCyan: 96,
-  brightWhite: 97,
-};
+// --- Default ANSI 16 theme ---
 
-const BG_CODES: Record<Color, number> = {
-  black: 40,
-  red: 41,
-  green: 42,
-  yellow: 43,
-  blue: 44,
-  magenta: 45,
-  cyan: 46,
-  white: 47,
-  brightBlack: 100,
-  brightRed: 101,
-  brightGreen: 102,
-  brightYellow: 103,
-  brightBlue: 104,
-  brightMagenta: 105,
-  brightCyan: 106,
-  brightWhite: 107,
+/**
+ * The default theme — maps each color slot to its matching ANSI palette
+ * index. With this theme, colors inherit the terminal's configured
+ * color scheme automatically.
+ */
+export const defaultTheme: Theme = {
+  color00: 0,
+  color01: 1,
+  color02: 2,
+  color03: 3,
+  color04: 4,
+  color05: 5,
+  color06: 6,
+  color07: 7,
+  color08: 8,
+  color09: 9,
+  color10: 10,
+  color11: 11,
+  color12: 12,
+  color13: 13,
+  color14: 14,
+  color15: 15,
 };
 
+// --- Color resolution ---
+
+/** Parse a hex color string "#rrggbb" into [r, g, b]. */
+function parseHex(hex: string): [number, number, number] {
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return [r, g, b];
+}
+
+/** Resolve a color slot to an SGR code fragment for foreground. */
+function fgSgr(color: Color, theme: Theme): string {
+  const val: ThemeValue = theme[color];
+  if (typeof val === "number") {
+    // ANSI palette index 0-15
+    return String(val < 8 ? 30 + val : 82 + val);
+  }
+  // Hex true color
+  const [r, g, b] = parseHex(val);
+  return `38;2;${r};${g};${b}`;
+}
+
+/** Resolve a color slot to an SGR code fragment for background. */
+function bgSgr(color: Color, theme: Theme): string {
+  const val: ThemeValue = theme[color];
+  if (typeof val === "number") {
+    // ANSI palette index 0-15
+    return String(val < 8 ? 40 + val : 92 + val);
+  }
+  // Hex true color
+  const [r, g, b] = parseHex(val);
+  return `48;2;${r};${g};${b}`;
+}
+
 // --- SGR generation ---
 
-function sgrForCell(cell: Cell): string {
-  const codes: number[] = [];
-  if (cell.bold) codes.push(1);
-  if (cell.italic) codes.push(3);
-  if (cell.underline) codes.push(4);
-  if (cell.fgColor) codes.push(FG_CODES[cell.fgColor]);
-  if (cell.bgColor) codes.push(BG_CODES[cell.bgColor]);
+function sgrForCell(cell: Cell, theme: Theme): string {
+  const codes: string[] = [];
+  if (cell.bold) codes.push("1");
+  if (cell.italic) codes.push("3");
+  if (cell.underline) codes.push("4");
+  if (cell.fgColor) codes.push(fgSgr(cell.fgColor, theme));
+  if (cell.bgColor) codes.push(bgSgr(cell.bgColor, theme));
   if (codes.length === 0) return "";
   return `\x1b[${codes.join(";")}m`;
 }
@@ -93,9 +113,13 @@ const RESET = "\x1b[0m";
  * only emitting SGR codes when the style changes.
  *
  * @param buf - The cell buffer to render.
+ * @param theme - Color theme mapping. Defaults to the ANSI 16 theme.
  * @returns A complete ANSI string ready to write to the terminal.
  */
-export function emitBuffer(buf: CellBuffer): string {
+export function emitBuffer(
+  buf: CellBuffer,
+  theme: Theme = defaultTheme,
+): string {
   let out = SYNC_START + CURSOR_HOME;
 
   let lastStyle: Cell | null = null;
@@ -106,13 +130,16 @@ export function emitBuffer(buf: CellBuffer): string {
     for (let x = 0; x < buf.width; x++) {
       const cell = buf.get(x, y);
 
+      // Skip continuation cells (trailing half of wide characters)
+      if (cell.char === "") continue;
+
       // Emit style change if needed
       if (lastStyle === null || !styleEquals(cell, lastStyle)) {
         // Reset before applying new style
         if (lastStyle !== null && hasStyle(lastStyle)) {
           out += RESET;
         }
-        const sgr = sgrForCell(cell);
+        const sgr = sgrForCell(cell, theme);
         if (sgr) out += sgr;
         lastStyle = cell;
       }
@@ -139,9 +166,14 @@ export function emitBuffer(buf: CellBuffer): string {
  *
  * @param prev - The previous buffer.
  * @param next - The new buffer.
+ * @param theme - Color theme mapping. Defaults to the ANSI 16 theme.
  * @returns An ANSI string with only the changed cells.
  */
-export function emitDiff(prev: CellBuffer, next: CellBuffer): string {
+export function emitDiff(
+  prev: CellBuffer,
+  next: CellBuffer,
+  theme: Theme = defaultTheme,
+): string {
   let out = SYNC_START;
 
   const changes = prev.diff(next);
@@ -156,6 +188,9 @@ export function emitDiff(prev: CellBuffer, next: CellBuffer): string {
   for (const { x, y } of changes) {
     const cell = next.get(x, y);
 
+    // Skip continuation cells (trailing half of wide characters)
+    if (cell.char === "") continue;
+
     // Position cursor if not consecutive
     if (y !== lastY || x !== lastX + 1) {
       // Reset style before repositioning
@@ -172,7 +207,7 @@ export function emitDiff(prev: CellBuffer, next: CellBuffer): string {
       if (lastStyle !== null && hasStyle(lastStyle)) {
         out += RESET;
       }
-      const sgr = sgrForCell(cell);
+      const sgr = sgrForCell(cell, theme);
       if (sgr) out += sgr;
       lastStyle = cell;
     }