@cel-tui/core 0.1.0

package/src/cel.ts

@@ -0,0 +1,716 @@
+import type { Node } from "@cel-tui/types";
+import { CellBuffer } from "./cell-buffer.js";
+import { emitBuffer, emitDiff } from "./emitter.js";
+import {
+  hitTest,
+  findClickHandler,
+  findScrollTarget,
+  findKeyPressHandler,
+  collectFocusable,
+} from "./hit-test.js";
+import { parseKey, isEditingKey, normalizeKey } from "./keys.js";
+import { layout, type LayoutNode } from "./layout.js";
+import {
+  paint,
+  getTextInputCursor,
+  setTextInputCursor,
+  getTextInputScroll,
+  setTextInputScroll,
+  getContainerScroll,
+  setContainerScroll,
+} from "./paint.js";
+import {
+  insertChar,
+  deleteBackward,
+  deleteForward,
+  moveCursor,
+  type EditState,
+} from "./text-edit.js";
+import type { Terminal } from "./terminal.js";
+import { visibleWidth } from "./width.js";
+
+type RenderFn = () => Node | Node[];
+
+let terminal: Terminal | null = null;
+let renderFn: RenderFn | null = null;
+let renderScheduled = false;
+let prevBuffer: CellBuffer | null = null;
+let currentBuffer: CellBuffer | null = null;
+let currentLayouts: LayoutNode[] = [];
+let lastFocusedIndex = -1;
+
+/**
+ * Framework-tracked focus index for uncontrolled focus.
+ * Points into the `collectFocusable()` list of the topmost layer.
+ * -1 means no uncontrolled element is focused.
+ */
+let frameworkFocusIndex = -1;
+
+/** The node whose props were stamped with `focused: true` during the last paint. */
+let stampedNode: LayoutNode | null = null;
+
+function doRender(): void {
+  renderScheduled = false;
+  if (!renderFn || !terminal) return;
+
+  const width = terminal.columns;
+  const height = terminal.rows;
+
+  // Create or resize buffer
+  const isResize =
+    currentBuffer !== null &&
+    (currentBuffer.width !== width || currentBuffer.height !== height);
+  const isFirstRender = currentBuffer === null;
+
+  if (isFirstRender || isResize) {
+    prevBuffer = null;
+    currentBuffer = new CellBuffer(width, height);
+  } else {
+    prevBuffer = currentBuffer;
+    currentBuffer = new CellBuffer(width, height);
+  }
+
+  // Get the tree from the render function
+  const tree = renderFn();
+  const layers = Array.isArray(tree) ? tree : [tree];
+
+  // Layout each layer
+  currentLayouts = [];
+  for (const layer of layers) {
+    const layoutTree = layout(layer, width, height);
+    currentLayouts.push(layoutTree);
+  }
+
+  // Stamp uncontrolled focus before painting so focusStyle and cursor work
+  stampUncontrolledFocus();
+
+  // Paint each layer into the buffer
+  for (const layoutTree of currentLayouts) {
+    paint(layoutTree, currentBuffer);
+  }
+
+  // Unstamp after paint so input handlers see clean props
+  unstampUncontrolledFocus();
+
+  // Emit to terminal — differential when possible
+  if (prevBuffer) {
+    const output = emitDiff(prevBuffer, currentBuffer);
+    if (output.length > 0) terminal.write(output);
+  } else {
+    const output = emitBuffer(currentBuffer);
+    terminal.write(output);
+  }
+}
+
+// --- Input handling ---
+
+// Regex for a single SGR mouse event (non-anchored, for scanning batched input)
+const SGR_MOUSE_RE = /\x1b\[<(\d+);(\d+);(\d+)([Mm])/g;
+
+// Tracks accumulated scroll offsets during a batch of mouse events.
+// Controlled scroll reads scrollOffset from props, which doesn't update until
+// re-render. Within a single data chunk containing multiple scroll events, we
+// need to remember the offset we already dispatched via onScroll.
+let batchScrollOffsets: Map<object, number> | 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();
+    while (match) {
+      const mouse = parseSgrMatch(match);
+      if (mouse) handleMouseEvent(mouse);
+      match = SGR_MOUSE_RE.exec(data);
+    }
+    batchScrollOffsets = null;
+    return;
+  }
+
+  // Keyboard input
+  const key = parseKey(data);
+  handleKeyEvent(key, data);
+}
+
+interface MouseEvent {
+  type: "click" | "scroll-up" | "scroll-down";
+  x: number;
+  y: number;
+}
+
+/**
+ * Parse a single SGR mouse event from a RegExp match.
+ * Returns a MouseEvent for scroll and click events, null for unhandled buttons.
+ */
+function parseSgrMatch(match: RegExpExecArray): MouseEvent | null {
+  const cb = parseInt(match[1]!, 10);
+  const x = parseInt(match[2]!, 10) - 1; // 1-indexed → 0-indexed
+  const y = parseInt(match[3]!, 10) - 1;
+  const isRelease = match[4] === "m";
+
+  // Scroll up (cb=64) / scroll down (cb=65)
+  if (cb === 64) return { type: "scroll-up", x, y };
+  if (cb === 65) return { type: "scroll-down", x, y };
+
+  // Button click (cb=0 for left button, release event)
+  if (cb === 0 && isRelease) return { type: "click", x, y };
+
+  return null;
+}
+
+/**
+ * Check if a focusable element uses controlled focus (explicit `focused` prop).
+ */
+function isControlledFocus(ln: LayoutNode): boolean {
+  const node = ln.node;
+  if (node.type === "textinput") return node.props.focused !== undefined;
+  if (node.type === "vstack" || node.type === "hstack")
+    return node.props.focused !== undefined;
+  return false;
+}
+
+/**
+ * Find the currently focused element across all layers.
+ * Checks controlled focus (`focused: true` in props) first,
+ * then falls back to framework-tracked uncontrolled focus.
+ */
+function findFocusedElement(): LayoutNode | null {
+  // Controlled: scan tree for focused: true
+  for (let i = currentLayouts.length - 1; i >= 0; i--) {
+    const found = findFocusedInTree(currentLayouts[i]!);
+    if (found) return found;
+  }
+  // Uncontrolled: check framework-tracked index
+  if (frameworkFocusIndex >= 0) {
+    const topLayer = currentLayouts[currentLayouts.length - 1];
+    if (topLayer) {
+      const focusables = collectFocusable(topLayer);
+      if (frameworkFocusIndex < focusables.length) {
+        return focusables[frameworkFocusIndex]!;
+      }
+    }
+    // Index out of bounds (tree changed) — clear
+    frameworkFocusIndex = -1;
+  }
+  return null;
+}
+
+/**
+ * Stamp `focused: true` on the framework-tracked focused node's props
+ * before painting, so that paint/focusStyle/cursor rendering picks it up.
+ * Only stamps if no controlled element is already focused.
+ * Must be followed by {@link unstampUncontrolledFocus} after paint.
+ */
+function stampUncontrolledFocus(): void {
+  stampedNode = null;
+  if (frameworkFocusIndex < 0) return;
+
+  // Don't stamp if a controlled element owns focus
+  for (let i = currentLayouts.length - 1; i >= 0; i--) {
+    if (findFocusedInTree(currentLayouts[i]!)) {
+      frameworkFocusIndex = -1;
+      return;
+    }
+  }
+
+  const topLayer = currentLayouts[currentLayouts.length - 1];
+  if (!topLayer) return;
+  const focusables = collectFocusable(topLayer);
+  if (frameworkFocusIndex >= focusables.length) {
+    frameworkFocusIndex = -1;
+    return;
+  }
+  const target = focusables[frameworkFocusIndex]!;
+  const node = target.node;
+  if (
+    node.type === "textinput" ||
+    node.type === "vstack" ||
+    node.type === "hstack"
+  ) {
+    (node.props as any).focused = true;
+    stampedNode = target;
+  }
+}
+
+/**
+ * Remove the `focused: true` stamp set by {@link stampUncontrolledFocus}.
+ * Called after paint so input handlers see the original props and can
+ * correctly distinguish controlled from uncontrolled elements.
+ */
+function unstampUncontrolledFocus(): void {
+  if (!stampedNode) return;
+  const node = stampedNode.node;
+  if (
+    node.type === "textinput" ||
+    node.type === "vstack" ||
+    node.type === "hstack"
+  ) {
+    delete (node.props as any).focused;
+  }
+  stampedNode = null;
+}
+
+/**
+ * Blur the currently focused element and focus a new one.
+ * Manages both controlled (via onFocus/onBlur callbacks) and
+ * uncontrolled (via frameworkFocusIndex) focus.
+ */
+function changeFocus(target: LayoutNode | null): void {
+  const current = findFocusedElement();
+
+  // Blur current — save position for Tab/Shift+Tab continuity
+  if (current && current !== target) {
+    const topLayer = currentLayouts[currentLayouts.length - 1];
+    if (topLayer) {
+      const focusables = collectFocusable(topLayer);
+      let idx = focusables.indexOf(current);
+      if (idx === -1)
+        idx = focusables.findIndex((f) => f.node === current.node);
+      lastFocusedIndex = idx;
+    }
+    // Always clear framework tracking on blur
+    frameworkFocusIndex = -1;
+    const props =
+      current.node.type === "textinput"
+        ? current.node.props
+        : current.node.type !== "text"
+          ? current.node.props
+          : null;
+    if (props && "onBlur" in props && props.onBlur) {
+      props.onBlur();
+    }
+  }
+
+  // Focus new target — clear saved position
+  if (target && target !== current) {
+    lastFocusedIndex = -1;
+    // Set or clear framework tracking based on controlled/uncontrolled
+    if (!isControlledFocus(target)) {
+      const topLayer = currentLayouts[currentLayouts.length - 1];
+      if (topLayer) {
+        const focusables = collectFocusable(topLayer);
+        frameworkFocusIndex = focusables.indexOf(target);
+      }
+    } else {
+      frameworkFocusIndex = -1;
+    }
+    const props =
+      target.node.type === "textinput"
+        ? target.node.props
+        : target.node.type !== "text"
+          ? target.node.props
+          : null;
+    if (props && "onFocus" in props && props.onFocus) {
+      props.onFocus();
+    }
+  }
+}
+
+/**
+ * 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";
+
+  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;
+    }
+    return Math.max(0, contentHeight - 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);
+  }
+}
+
+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);
+    if (path.length === 0) continue;
+
+    if (event.type === "click") {
+      // Find and focus the focusable element at click position
+      const focusable = findClickFocusTarget(path);
+      if (focusable) {
+        changeFocus(focusable);
+      }
+
+      const click = findClickHandler(path);
+      if (click) {
+        click.handler();
+      }
+      cel.render();
+      return;
+    }
+
+    if (event.type === "scroll-up" || event.type === "scroll-down") {
+      const target = findScrollTarget(path);
+      if (target) {
+        const delta = event.type === "scroll-up" ? -1 : 1;
+        const maxOffset = getMaxScrollOffset(target);
+
+        if (target.node.type === "textinput") {
+          // TextInput scroll is always framework-managed
+          const tiProps = target.node.props;
+          const current = getTextInputScroll(tiProps);
+          const clamped = Math.max(0, Math.min(maxOffset, current + delta));
+          setTextInputScroll(tiProps, clamped);
+          cel.render();
+        } else {
+          const props = target.node.type !== "text" ? target.node.props : null;
+          if (props && "onScroll" in props) {
+            if (props.onScroll) {
+              // Controlled scroll: notify app.
+              // Use batch accumulator if available (multiple events in one chunk),
+              // otherwise read from props.
+              const baseOffset =
+                batchScrollOffsets?.get(props) ??
+                (props as any).scrollOffset ??
+                0;
+              const newOffset = Math.max(
+                0,
+                Math.min(maxOffset, baseOffset + delta),
+              );
+              batchScrollOffsets?.set(props, newOffset);
+              props.onScroll(newOffset);
+            } else {
+              // Uncontrolled scroll: framework manages state
+              const current = getContainerScroll(props);
+              const clamped = Math.max(0, Math.min(maxOffset, current + delta));
+              setContainerScroll(props, clamped);
+            }
+            cel.render();
+          }
+        }
+      }
+      return;
+    }
+  }
+}
+
+/**
+ * Find the nearest focusable element in a hit path (for mouse click focusing).
+ */
+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]!;
+    }
+  }
+  return null;
+}
+
+function handleKeyEvent(key: string, rawData?: string): void {
+  // --- Focus traversal keys ---
+
+  // Tab / Shift+Tab: cycle through focusable elements
+  // Skip focus traversal when a TextInput is focused — Tab is an editing key
+  // that inserts \t. The user must Escape first, then Tab to traverse.
+  if (key === "tab" || key === "shift+tab") {
+    const focusedTI = findFocusedTextInput();
+    if (focusedTI) {
+      // Fall through to TextInput key routing below
+    } else {
+      const topLayer = currentLayouts[currentLayouts.length - 1];
+      if (!topLayer) return;
+      const focusables = collectFocusable(topLayer);
+      if (focusables.length === 0) return;
+
+      const current = findFocusedElement();
+      let currentIdx = current ? focusables.indexOf(current) : -1;
+
+      // If current not found in focusables list, search by identity
+      if (currentIdx === -1 && current) {
+        currentIdx = focusables.findIndex((f) => f.node === current.node);
+      }
+
+      // If still not found, use the last focused element's position
+      // so Tab/Shift+Tab continues from where focus was lost (e.g. after Escape)
+      if (
+        currentIdx === -1 &&
+        lastFocusedIndex >= 0 &&
+        lastFocusedIndex < focusables.length
+      ) {
+        currentIdx = lastFocusedIndex;
+      }
+
+      let nextIdx: number;
+      if (key === "tab") {
+        nextIdx = currentIdx === -1 ? 0 : (currentIdx + 1) % focusables.length;
+      } else {
+        nextIdx =
+          currentIdx === -1
+            ? focusables.length - 1
+            : (currentIdx - 1 + focusables.length) % focusables.length;
+      }
+
+      changeFocus(focusables[nextIdx]!);
+      cel.render();
+      return;
+    } // end: not a focused TextInput
+  }
+
+  // Escape: unfocus current element
+  if (key === "escape") {
+    const current = findFocusedElement();
+    if (current) {
+      changeFocus(null);
+      cel.render();
+      return;
+    }
+  }
+
+  // Enter: activate focused clickable container
+  if (key === "enter") {
+    const current = findFocusedElement();
+    if (current && current.node.type !== "textinput") {
+      const props = current.node.type !== "text" ? current.node.props : null;
+      if (props?.onClick) {
+        props.onClick();
+        cel.render();
+        return;
+      }
+    }
+  }
+
+  // --- 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;
+
+    // Check submitKey
+    const submitKey = normalizeKey(props.submitKey ?? "enter");
+    if (key === submitKey && props.onSubmit) {
+      props.onSubmit();
+      cel.render();
+      return;
+    }
+
+    // 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;
+
+      switch (key) {
+        case "backspace":
+          newState = deleteBackward(editState);
+          break;
+        case "delete":
+          newState = deleteForward(editState);
+          break;
+        case "left":
+        case "right":
+        case "up":
+        case "down":
+        case "home":
+        case "end":
+          newState = moveCursor(
+            editState,
+            key as "left" | "right" | "up" | "down" | "home" | "end",
+            focusedInput.rect.width,
+          );
+          break;
+        case "enter":
+          newState = insertChar(editState, "\n");
+          break;
+        case "tab":
+          newState = insertChar(editState, "\t");
+          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;
+      }
+    }
+  }
+
+  // Key not consumed by TextInput — bubble up from focused element
+  const focused = findFocusedElement();
+  if (focused) {
+    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();
+          return;
+        }
+      }
+    }
+  }
+
+  // No focused element — try root onKeyPress on topmost layer
+  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);
+      cel.render();
+      return;
+    }
+  }
+}
+
+/**
+ * Build the path from root to a target node (depth-first search).
+ * Returns the path array [root, ..., target] or null if not found.
+ */
+function findPathTo(root: LayoutNode, target: LayoutNode): LayoutNode[] | null {
+  if (root === target || root.node === target.node) return [root];
+  for (const child of root.children) {
+    const childPath = findPathTo(child, target);
+    if (childPath) return [root, ...childPath];
+  }
+  return null;
+}
+
+function findFocusedTextInput(): LayoutNode | null {
+  const focused = findFocusedElement();
+  return focused && focused.node.type === "textinput" ? focused : null;
+}
+
+function findFocusedInTree(ln: LayoutNode): LayoutNode | null {
+  if (ln.node.type === "textinput" && ln.node.props.focused) {
+    return ln;
+  }
+  if (
+    (ln.node.type === "vstack" || ln.node.type === "hstack") &&
+    ln.node.props.focused
+  ) {
+    return ln;
+  }
+  for (const child of ln.children) {
+    const found = findFocusedInTree(child);
+    if (found) return found;
+  }
+  return null;
+}
+
+// --- Public API ---
+
+/**
+ * cel-tui framework entrypoint.
+ *
+ * The framework is stateless — it renders whatever tree the render function
+ * returns. State management is fully external. Use any approach you like
+ * (plain variables, classes, libraries) and call {@link cel.render} when
+ * state changes.
+ *
+ * @example
+ * ```ts
+ * import { cel, VStack, Text, ProcessTerminal } from "@cel-tui/core";
+ *
+ * cel.init(new ProcessTerminal());
+ * cel.viewport(() =>
+ *   VStack({ height: "100%" }, [
+ *     Text("Hello, world!", { bold: true }),
+ *   ])
+ * );
+ * ```
+ */
+export const cel = {
+  /**
+   * Initialize the framework with a terminal implementation.
+   * Must be called before {@link cel.viewport}.
+   *
+   * @param term - Terminal to render to (ProcessTerminal or MockTerminal).
+   */
+  init(term: Terminal): void {
+    terminal = term;
+    terminal.start(handleInput, () => cel.render());
+  },
+
+  /**
+   * Set the render function that returns the UI tree.
+   * Triggers the first render automatically.
+   *
+   * @param fn - A function that returns the current UI tree.
+   */
+  viewport(fn: RenderFn): void {
+    renderFn = fn;
+    cel.render();
+  },
+
+  /**
+   * Request a re-render. Call this after state changes.
+   *
+   * Batched via `process.nextTick()` — multiple calls within the same
+   * tick produce a single render.
+   */
+  render(): void {
+    if (renderScheduled) return;
+    renderScheduled = true;
+    process.nextTick(doRender);
+  },
+
+  /**
+   * Stop the framework and restore terminal state.
+   */
+  stop(): void {
+    terminal?.stop();
+    terminal = null;
+    renderFn = null;
+    prevBuffer = null;
+    currentBuffer = null;
+    currentLayouts = [];
+    renderScheduled = false;
+    lastFocusedIndex = -1;
+    frameworkFocusIndex = -1;
+    stampedNode = null;
+  },
+
+  /** @internal */
+  _getBuffer(): CellBuffer | null {
+    return currentBuffer;
+  },
+};