@cel-tui/core 0.1.0 → 0.2.0

package/src/paint.ts

@@ -104,6 +104,32 @@ function fillBackground(
   }
 }
 
+/**
+ * Compute the maximum scroll offset for a scrollable container.
+ * This is the content size minus the viewport size along the main axis.
+ */
+function computeMaxScrollOffset(ln: LayoutNode, isVertical: boolean): number {
+  const { rect, children } = ln;
+  const props = ln.node.type !== "text" ? ln.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;
+    }
+    return Math.max(0, contentHeight + padY - rect.height);
+  }
+  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);
+}
+
 function paintLayoutNode(
   ln: LayoutNode,
   buf: CellBuffer,
@@ -150,7 +176,7 @@ function paintLayoutNode(
         italic: node.props.italic ?? tiEffective.italic,
         underline: node.props.underline ?? tiEffective.underline,
       };
-      paintTextInput(tiProps, rect, clipped, buf);
+      paintTextInput(tiProps, rect, clipped, buf, tiEffective);
       break;
     }
     case "vstack":
@@ -172,10 +198,14 @@ function paintLayoutNode(
   const isContainer = node.type === "vstack" || node.type === "hstack";
   const containerProps = isContainer ? node.props : null;
   const isScrollable = containerProps?.overflow === "scroll";
-  const scrollOffset = isScrollable
-    ? (containerProps.scrollOffset ?? getContainerScroll(containerProps))
-    : 0;
   const isVertical = node.type === "vstack";
+  let scrollOffset = 0;
+  if (isScrollable) {
+    const raw = containerProps.scrollOffset ?? 0;
+    // Clamp to valid range so apps can pass large values to mean "scroll to end"
+    const maxOffset = computeMaxScrollOffset(ln, isVertical);
+    scrollOffset = Math.max(0, Math.min(raw, maxOffset));
+  }
 
   // Recurse into children, using this node's clipped rect as the clip for children
   for (const child of ln.children) {
@@ -257,7 +287,7 @@ function paintScrollbar(
       const isThumb = row >= thumbPos && row < thumbPos + thumbSize;
       buf.set(barX, absY, {
         char: isThumb ? "┃" : "│",
-        fgColor: isThumb ? "white" : "brightBlack",
+        fgColor: isThumb ? null : "color08",
         bgColor: null,
         bold: false,
         italic: false,
@@ -292,7 +322,7 @@ function paintScrollbar(
       const isThumb = col >= thumbPos && col < thumbPos + thumbSize;
       buf.set(absX, barY, {
         char: isThumb ? "━" : "─",
-        fgColor: isThumb ? "white" : "brightBlack",
+        fgColor: isThumb ? null : "color08",
         bgColor: null,
         bold: false,
         italic: false,
@@ -322,11 +352,6 @@ function makeCell(
   };
 }
 
-/**
- * Paint a single line of text into the buffer using grapheme segmentation.
- * Correctly handles wide characters (CJK, emoji) by advancing the column
- * by the grapheme's visible width.
- */
 /**
  * Paint a single line of text into the buffer using grapheme segmentation.
  * Correctly handles wide characters (CJK, emoji) by advancing the column
@@ -361,6 +386,20 @@ function paintLineGraphemes(
     if (absX + gw > clipLeft) {
       // At least partially visible in clip rect
       buf.set(absX, y, makeCell(segment, props));
+      // Write continuation markers for wide characters (2+ columns)
+      for (let w = 1; w < gw; w++) {
+        const cx = absX + w;
+        if (cx < clipRight) {
+          buf.set(cx, y, {
+            char: "",
+            fgColor: props.fgColor ?? null,
+            bgColor: props.bgColor ?? null,
+            bold: props.bold ?? false,
+            italic: props.italic ?? false,
+            underline: props.underline ?? false,
+          });
+        }
+      }
     }
     col += gw;
   }
@@ -424,32 +463,60 @@ function paintTextInput(
   rect: Rect,
   clipRect: Rect,
   buf: CellBuffer,
+  inherited: StyleProps = EMPTY_STYLE,
 ): void {
   const { x, y, width: w, height: h } = rect;
   if (w <= 0 || h <= 0) return;
 
+  // Apply padding — content is inset from the rect edges
+  const padX = props.padding?.x ?? 0;
+  const padY = props.padding?.y ?? 0;
+  const cx = x + padX;
+  const cy = y + padY;
+  const cw = Math.max(0, w - padX * 2);
+  const ch = Math.max(0, h - padY * 2);
+  if (cw <= 0 || ch <= 0) return;
+
+  // Fill the TextInput rect with background color (like containers do)
+  // so that cursor inversion and empty cells have correct colors.
+  const effectiveBg = props.bgColor ?? inherited.bgColor;
+  if (effectiveBg) {
+    fillBackground(rect, clipRect, effectiveBg, buf);
+  }
+
   const value = props.value;
   const showPlaceholder = value.length === 0 && props.placeholder;
 
   if (showPlaceholder && props.placeholder) {
-    // Paint placeholder text
+    // Paint placeholder text in padded content area, inheriting
+    // styles from the TextInput's resolved style chain
+    const contentRect: Rect = { x: cx, y: cy, width: cw, height: ch };
+    const phProps = props.placeholder.props;
+    const effectivePh = {
+      ...phProps,
+      fgColor: phProps.fgColor ?? inherited.fgColor,
+      bgColor: phProps.bgColor ?? inherited.bgColor,
+      bold: phProps.bold ?? inherited.bold,
+      italic: phProps.italic ?? inherited.italic,
+      underline: phProps.underline ?? inherited.underline,
+    };
     paintText(
       props.placeholder.content,
-      props.placeholder.props,
-      rect,
+      effectivePh,
+      contentRect,
       clipRect,
       buf,
     );
     return;
   }
 
-  // Word-wrap value (always on for TextInput)
+  // Word-wrap value (always on for TextInput) using content width
   const lines: string[] = [];
   for (const rawLine of value.split("\n")) {
-    if (visibleWidth(rawLine) <= w) {
+    if (visibleWidth(rawLine) <= cw) {
       lines.push(rawLine);
     } else {
-      wrapLine(rawLine, w, lines);
+      wrapLine(rawLine, cw, lines);
     }
   }
 
@@ -458,10 +525,10 @@ function paintTextInput(
 
   if (props.focused) {
     const cursorOffset = getTextInputCursor(props);
-    const cursorPos = offsetToWrappedPos(value, cursorOffset, w);
+    const cursorPos = offsetToWrappedPos(value, cursorOffset, cw);
     // Scroll down if cursor is below viewport
-    if (cursorPos.line >= scrollOffset + h) {
-      scrollOffset = cursorPos.line - h + 1;
+    if (cursorPos.line >= scrollOffset + ch) {
+      scrollOffset = cursorPos.line - ch + 1;
     }
     // Scroll up if cursor is above viewport
     if (cursorPos.line < scrollOffset) {
@@ -470,30 +537,46 @@ function paintTextInput(
     setTextInputScroll(props, scrollOffset);
   }
 
-  // Paint visible lines (grapheme-aware)
-  for (let row = 0; row < h; row++) {
+  // Paint visible lines (grapheme-aware) in content area
+  for (let row = 0; row < ch; row++) {
     const lineIdx = scrollOffset + row;
     if (lineIdx >= lines.length) break;
     const line = lines[lineIdx]!;
-    paintLineGraphemes(line, x, y + row, w, clipRect, props, buf);
+    paintLineGraphemes(line, cx, cy + row, cw, clipRect, props, buf);
   }
 
-  // Paint cursor if focused
+  // Paint cursor if focused — invert colors at cursor position so it's
+  // always visible regardless of terminal cursor configuration. The
+  // framework also positions the native terminal cursor here (in cel.ts)
+  // for blinking.
   if (props.focused) {
     const cursorOffset = getTextInputCursor(props);
-    const pos = offsetToWrappedPos(value, cursorOffset, w);
+    const pos = offsetToWrappedPos(value, cursorOffset, cw);
     const screenRow = pos.line - scrollOffset;
-    if (screenRow >= 0 && screenRow < h && pos.col < w) {
-      const existing = buf.get(x + pos.col, y + screenRow);
-      // Invert colors for cursor visibility
-      buf.set(x + pos.col, y + screenRow, {
-        char: existing.char === " " && !existing.bgColor ? " " : existing.char,
-        fgColor: existing.bgColor ?? "black",
-        bgColor: existing.fgColor ?? "white",
-        bold: existing.bold,
-        italic: existing.italic,
-        underline: existing.underline,
-      });
+    if (screenRow >= 0 && screenRow < ch && pos.col < cw) {
+      const absX = cx + pos.col;
+      const absY = cy + screenRow;
+      if (
+        absX >= clipRect.x &&
+        absX < clipRect.x + clipRect.width &&
+        absY >= clipRect.y &&
+        absY < clipRect.y + clipRect.height
+      ) {
+        const existing = buf.get(absX, absY);
+        // Resolve null colors against inherited style so the inversion
+        // always produces visible contrast (e.g. on bg-filled empty cells
+        // where fgColor is null).
+        const resolvedFg = existing.fgColor ?? inherited.fgColor ?? "color07";
+        const resolvedBg = existing.bgColor ?? inherited.bgColor ?? "color00";
+        buf.set(absX, absY, {
+          char: existing.char,
+          fgColor: resolvedBg,
+          bgColor: resolvedFg,
+          bold: existing.bold,
+          italic: existing.italic,
+          underline: existing.underline,
+        });
+      }
     }
   }
 }
@@ -539,21 +622,6 @@ function offsetToWrappedPos(
 
 import type { ContainerProps } from "@cel-tui/types";
 
-const containerScrolls = new WeakMap<ContainerProps, number>();
-
-/** Get the scroll offset for an uncontrolled scrollable container. */
-export function getContainerScroll(props: ContainerProps): number {
-  return containerScrolls.get(props) ?? 0;
-}
-
-/** Set the scroll offset for an uncontrolled scrollable container. */
-export function setContainerScroll(
-  props: ContainerProps,
-  scroll: number,
-): void {
-  containerScrolls.set(props, scroll);
-}
-
 /**
  * TextInput state is keyed on the `onChange` function reference, which is
  * a stable identity across re-renders (the app provides the same closure).
@@ -564,9 +632,44 @@ type OnChangeFn = (value: string) => void;
 const textInputCursors = new WeakMap<OnChangeFn, number>();
 const textInputScrolls = new WeakMap<OnChangeFn, number>();
 
+/**
+ * Compute the screen position of the cursor for a focused TextInput.
+ * Returns `{ x, y }` in 0-indexed screen coordinates, or `null` if
+ * the cursor is not visible (clipped or not focused).
+ */
+export function getTextInputCursorScreenPos(
+  props: TextInputProps,
+  rect: Rect,
+): { x: number; y: number } | null {
+  const { x, y, width: w, height: h } = rect;
+  if (w <= 0 || h <= 0) return null;
+
+  const padX = props.padding?.x ?? 0;
+  const padY = props.padding?.y ?? 0;
+  const cx = x + padX;
+  const cy = y + padY;
+  const cw = Math.max(0, w - padX * 2);
+  const ch = Math.max(0, h - padY * 2);
+  if (cw <= 0 || ch <= 0) return null;
+
+  const cursorOffset = getTextInputCursor(props);
+  const pos = offsetToWrappedPos(props.value, cursorOffset, cw);
+  const scrollOffset = getTextInputScroll(props);
+  const screenRow = pos.line - scrollOffset;
+
+  if (screenRow >= 0 && screenRow < ch && pos.col < cw) {
+    return { x: cx + pos.col, y: cy + screenRow };
+  }
+  return null;
+}
+
 /** Get the cursor offset for a TextInput (framework-managed). */
 export function getTextInputCursor(props: TextInputProps): number {
-  return textInputCursors.get(props.onChange) ?? props.value.length;
+  const stored = textInputCursors.get(props.onChange);
+  if (stored === undefined) return props.value.length;
+  // Clamp to value length — the app may have cleared or shortened the value
+  // externally (e.g. after submit) while the WeakMap still holds the old cursor.
+  return Math.min(stored, props.value.length);
 }
 
 /** Set the cursor offset for a TextInput. */

package/src/primitives/stacks.ts

@@ -34,7 +34,7 @@ export function VStack(props: ContainerProps, children: Node[]): ContainerNode {
  * HStack({ height: 1, gap: 1 }, [
  *   Text("Name", { bold: true }),
  *   VStack({ flex: 1 }, []),
- *   Text("value", { fgColor: "brightBlack" }),
+ *   Text("value", { fgColor: "color08" }),
  * ])
  */
 export function HStack(props: ContainerProps, children: Node[]): ContainerNode {

package/src/primitives/text-input.ts

@@ -34,7 +34,7 @@ import type { TextInputNode, TextInputProps } from "@cel-tui/types";
  *   onChange: handleChange,
  *   onSubmit: handleSend,
  *   submitKey: "ctrl+enter",
- *   placeholder: Text("type a message...", { fgColor: "brightBlack" }),
+ *   placeholder: Text("type a message...", { fgColor: "color08" }),
  * })
  */
 export function TextInput(props: TextInputProps): TextInputNode {

package/src/primitives/text.ts

@@ -16,7 +16,7 @@ import type { TextNode, TextProps } from "@cel-tui/types";
  *
  * @example
  * // Simple styled text
- * Text("Hello", { bold: true, fgColor: "cyan" })
+ * Text("Hello", { bold: true, fgColor: "color06" })
  *
  * // Horizontal divider
  * Text("─", { repeat: "fill" })

package/src/terminal.ts

@@ -11,7 +11,7 @@ export interface Terminal {
   get columns(): number;
   /** Terminal height in rows. */
   get rows(): number;
-  /** Enter raw mode, enable mouse tracking, hide cursor. */
+  /** Enter raw mode, enable Kitty keyboard protocol, enable mouse tracking, hide cursor. */
   start(onInput: (data: string) => void, onResize: () => void): void;
   /** Restore terminal state. */
   stop(): void;
@@ -23,6 +23,9 @@ export interface Terminal {
 
 /**
  * Real terminal using process.stdin/stdout.
+ *
+ * Enables the Kitty keyboard protocol (level 1) for unambiguous key input,
+ * SGR mouse tracking, and raw mode. All modes are restored on stop/crash.
  */
 export class ProcessTerminal implements Terminal {
   private wasRaw = false;
@@ -61,6 +64,10 @@ export class ProcessTerminal implements Terminal {
     process.stdin.on("data", onInput);
     process.stdout.on("resize", this.resizeHandler);
 
+    // Switch to alternate screen buffer (restored on exit)
+    this.write("\x1b[?1049h");
+    // Enable Kitty keyboard protocol level 1 (disambiguate) with push flag
+    this.write("\x1b[>1u");
     // Enable mouse tracking (normal mode) + SGR encoding
     this.write("\x1b[?1000h\x1b[?1006h");
     this.hideCursor();
@@ -95,7 +102,11 @@ export class ProcessTerminal implements Terminal {
 
     // Disable mouse tracking + SGR encoding
     this.write("\x1b[?1006l\x1b[?1000l");
+    // Pop Kitty keyboard protocol mode
+    this.write("\x1b[<u");
     this.showCursor();
+    // Restore main screen buffer
+    this.write("\x1b[?1049l");
 
     if (this.resizeHandler) {
       process.stdout.removeListener("resize", this.resizeHandler);

package/src/text-edit.ts

@@ -8,6 +8,37 @@ export interface EditState {
   cursor: number;
 }
 
+const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+
+/**
+ * Get the grapheme boundary before the given cursor position.
+ * Returns the start offset of the grapheme that contains or precedes
+ * the cursor, or 0 if at the beginning.
+ */
+function prevGraphemeBoundary(value: string, cursor: number): number {
+  if (cursor <= 0) return 0;
+  let lastStart = 0;
+  for (const { index, segment } of segmenter.segment(value)) {
+    const end = index + segment.length;
+    if (end >= cursor) return index;
+    lastStart = end;
+  }
+  return lastStart;
+}
+
+/**
+ * Get the grapheme boundary after the given cursor position.
+ * Returns the end offset of the grapheme that starts at or after
+ * the cursor, or value.length if at the end.
+ */
+function nextGraphemeBoundary(value: string, cursor: number): number {
+  for (const { index, segment } of segmenter.segment(value)) {
+    const end = index + segment.length;
+    if (index >= cursor) return end;
+  }
+  return value.length;
+}
+
 /**
  * Insert a character (or string) at the cursor position.
  */
@@ -20,31 +51,36 @@ export function insertChar(state: EditState, char: string): EditState {
 }
 
 /**
- * Delete the character before the cursor (Backspace).
+ * Delete the grapheme before the cursor (Backspace).
+ * Handles multi-codepoint characters (emoji, ZWJ sequences, combining marks).
  */
 export function deleteBackward(state: EditState): EditState {
   const { value, cursor } = state;
   if (cursor === 0) return state;
+  const boundary = prevGraphemeBoundary(value, cursor);
   return {
-    value: value.slice(0, cursor - 1) + value.slice(cursor),
-    cursor: cursor - 1,
+    value: value.slice(0, boundary) + value.slice(cursor),
+    cursor: boundary,
   };
 }
 
 /**
- * Delete the character after the cursor (Delete key).
+ * Delete the grapheme after the cursor (Delete key).
+ * Handles multi-codepoint characters (emoji, ZWJ sequences, combining marks).
  */
 export function deleteForward(state: EditState): EditState {
   const { value, cursor } = state;
   if (cursor >= value.length) return state;
+  const boundary = nextGraphemeBoundary(value, cursor);
   return {
-    value: value.slice(0, cursor) + value.slice(cursor + 1),
+    value: value.slice(0, cursor) + value.slice(boundary),
     cursor,
   };
 }
 
 /**
  * Move the cursor in the given direction.
+ * Left/right movement respects grapheme boundaries.
  *
  * @param state - Current edit state.
  * @param direction - Movement direction.
@@ -58,10 +94,16 @@ export function moveCursor(
   const { value, cursor } = state;
 
   switch (direction) {
-    case "left":
-      return { value, cursor: Math.max(0, cursor - 1) };
-    case "right":
-      return { value, cursor: Math.min(value.length, cursor + 1) };
+    case "left": {
+      if (cursor <= 0) return state;
+      const boundary = prevGraphemeBoundary(value, cursor);
+      return { value, cursor: boundary };
+    }
+    case "right": {
+      if (cursor >= value.length) return state;
+      const boundary = nextGraphemeBoundary(value, cursor);
+      return { value, cursor: boundary };
+    }
     case "home":
       return { value, cursor: 0 };
     case "end":
@@ -89,17 +131,6 @@ function moveVertical(
   let cursorLine = 0;
   let cursorCol = 0;
 
-  for (let i = 0; i < lines.length; i++) {
-    const lineLen = lines[i]!.length;
-    if (offset + lineLen >= cursor && cursorLine === 0 && offset <= cursor) {
-      cursorLine = i;
-      cursorCol = cursor - offset;
-    }
-    offset += lineLen + 1; // +1 for \n
-  }
-
-  // Re-scan to get correct line (the above loop has a bug for first line)
-  offset = 0;
   for (let i = 0; i < lines.length; i++) {
     const lineLen = lines[i]!.length;
     if (cursor >= offset && cursor <= offset + lineLen) {
@@ -107,7 +138,7 @@ function moveVertical(
       cursorCol = cursor - offset;
       break;
     }
-    offset += lineLen + 1;
+    offset += lineLen + 1; // +1 for \n
   }
 
   // Move line
@@ -139,26 +170,3 @@ function moveVertical(
 
   return { value, cursor: newOffset };
 }
-
-/**
- * Map a cursor offset to (line, column) in the raw text (split by \n).
- * Used for painting the cursor.
- */
-export function cursorToLineCol(
-  value: string,
-  cursor: number,
-): { line: number; col: number } {
-  const lines = value.split("\n");
-  let offset = 0;
-
-  for (let i = 0; i < lines.length; i++) {
-    const lineLen = lines[i]!.length;
-    if (cursor <= offset + lineLen) {
-      return { line: i, col: cursor - offset };
-    }
-    offset += lineLen + 1;
-  }
-
-  // Cursor at very end
-  return { line: lines.length - 1, col: lines[lines.length - 1]!.length };
-}