@cel-tui/core 0.1.0

package/src/keys.ts

@@ -0,0 +1,147 @@
+/**
+ * Parse raw terminal input data into a normalized key string.
+ *
+ * Handles:
+ * - Printable ASCII characters
+ * - Control characters (Ctrl+A through Ctrl+Z)
+ * - Special keys (Enter, Escape, Tab, Backspace, Delete)
+ * - Arrow keys, Home, End, Page Up/Down
+ * - CSI sequences
+ *
+ * @param data - Raw terminal input string.
+ * @returns Normalized key string (e.g., `"ctrl+s"`, `"escape"`, `"up"`).
+ */
+export function parseKey(data: string): string {
+  // CSI sequences: ESC [ ...
+  if (data.startsWith("\x1b[")) {
+    return parseCsiSequence(data);
+  }
+
+  // Single escape
+  if (data === "\x1b") return "escape";
+
+  // Control characters
+  if (data.length === 1) {
+    const code = data.charCodeAt(0);
+
+    // Ctrl+A (0x01) through Ctrl+Z (0x1a), excluding special ones
+    if (code >= 1 && code <= 26) {
+      const letter = String.fromCharCode(code + 96); // 1→a, 2→b, etc.
+      // Special cases
+      if (code === 9) return "tab"; // Ctrl+I = Tab
+      if (code === 13) return "enter"; // Ctrl+M = Enter
+      return `ctrl+${letter}`;
+    }
+
+    // Backspace
+    if (code === 127) return "backspace";
+
+    // Printable ASCII
+    if (code >= 32 && code <= 126) return data.toLowerCase();
+  }
+
+  // Multi-byte (e.g., UTF-8) — return as-is lowercase
+  return data.toLowerCase();
+}
+
+function parseCsiSequence(data: string): string {
+  const seq = data.slice(2); // Remove ESC [
+
+  switch (seq) {
+    case "A":
+      return "up";
+    case "B":
+      return "down";
+    case "C":
+      return "right";
+    case "D":
+      return "left";
+    case "H":
+      return "home";
+    case "F":
+      return "end";
+    case "Z":
+      return "shift+tab";
+    case "3~":
+      return "delete";
+    case "5~":
+      return "pageup";
+    case "6~":
+      return "pagedown";
+  }
+
+  // Function keys
+  const fnMatch = seq.match(/^(\d+)~$/);
+  if (fnMatch) {
+    const num = parseInt(fnMatch[1]!, 10);
+    const fnMap: Record<number, string> = {
+      11: "f1",
+      12: "f2",
+      13: "f3",
+      14: "f4",
+      15: "f5",
+      17: "f6",
+      18: "f7",
+      19: "f8",
+      20: "f9",
+      21: "f10",
+      23: "f11",
+      24: "f12",
+    };
+    if (fnMap[num]) return fnMap[num]!;
+  }
+
+  // Unknown CSI sequence
+  return `unknown:${data}`;
+}
+
+/**
+ * Normalize a key string to canonical format.
+ *
+ * Lowercases everything and reorders modifiers to the canonical
+ * order: `ctrl+alt+shift+<key>`.
+ *
+ * @param key - Key string to normalize.
+ * @returns Normalized key string.
+ */
+export function normalizeKey(key: string): string {
+  const parts = key.toLowerCase().split("+");
+  if (parts.length <= 1) return key.toLowerCase();
+
+  const base = parts[parts.length - 1]!;
+  const mods = parts.slice(0, -1);
+
+  // Canonical order: ctrl, alt, shift
+  const ordered: string[] = [];
+  if (mods.includes("ctrl")) ordered.push("ctrl");
+  if (mods.includes("alt")) ordered.push("alt");
+  if (mods.includes("shift")) ordered.push("shift");
+
+  return [...ordered, base].join("+");
+}
+
+/**
+ * Check if a parsed key is a text-editing key that TextInput should consume.
+ * Modifier combos (ctrl+s, alt+x) are NOT editing keys and should bubble.
+ */
+export function isEditingKey(key: string): boolean {
+  // Single printable characters
+  if (key.length === 1) return true;
+
+  // Navigation and editing keys consumed by TextInput
+  const editingKeys = new Set([
+    "enter",
+    "backspace",
+    "delete",
+    "tab",
+    "up",
+    "down",
+    "left",
+    "right",
+    "home",
+    "end",
+    "space",
+  ]);
+
+  return editingKeys.has(key);
+}

package/src/layout.ts

@@ -0,0 +1,422 @@
+import type { Node, ContainerProps, SizeValue } from "@cel-tui/types";
+import { visibleWidth } from "./width.js";
+
+/**
+ * A rectangle in absolute screen coordinates.
+ */
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * A node in the layout tree with computed position and size.
+ */
+export interface LayoutNode {
+  /** The original UI node. */
+  node: Node;
+  /** Computed absolute screen rect. */
+  rect: Rect;
+  /** Laid-out children (empty for leaf nodes). */
+  children: LayoutNode[];
+}
+
+// --- Helpers ---
+
+function resolveSizeValue(
+  value: SizeValue | undefined,
+  parentSize: number,
+): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "number") return value;
+  const match = value.match(/^(\d+(?:\.\d+)?)%$/);
+  if (match) return Math.floor((parentSize * parseFloat(match[1]!)) / 100);
+  return undefined;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+function getProps(node: Node): ContainerProps | null {
+  if (node.type === "text") return null;
+  return node.props;
+}
+
+// --- Intrinsic size computation ---
+
+/**
+ * Compute intrinsic main-axis size for a node (before layout).
+ * Used by the parent to determine how much space to allocate.
+ */
+function intrinsicMainSize(
+  node: Node,
+  isVertical: boolean,
+  crossSize: number,
+): number {
+  if (node.type === "text") {
+    if (isVertical) {
+      // Height = number of lines
+      if (node.content.length === 0) return 1;
+      const lines = node.content.split("\n");
+      if (node.props.wrap === "word") {
+        let total = 0;
+        for (const line of lines) {
+          total += Math.max(
+            1,
+            Math.ceil(visibleWidth(line) / Math.max(1, crossSize)),
+          );
+        }
+        return total;
+      }
+      return lines.length;
+    }
+    // Width (intrinsic)
+    if (node.props.repeat === "fill") return 0;
+    const lines = node.content.split("\n");
+    let maxW = 0;
+    for (const line of lines) {
+      const w = visibleWidth(line);
+      if (w > maxW) maxW = w;
+    }
+    if (typeof node.props.repeat === "number") maxW *= node.props.repeat;
+    return maxW;
+  }
+
+  if (node.type === "textinput") {
+    if (isVertical) {
+      const val = node.props.value || "";
+      if (val.length === 0) return 1;
+      const lines = val.split("\n");
+      let total = 0;
+      for (const line of lines) {
+        total += Math.max(
+          1,
+          Math.ceil(visibleWidth(line) / Math.max(1, crossSize)),
+        );
+      }
+      return total;
+    }
+    return 0;
+  }
+
+  // Container: compute intrinsic size along the requested axis.
+  // If the requested axis matches the container's main axis, sum children + gaps.
+  // If it's the cross axis, take the max of children on that axis.
+  const props = node.props;
+  const gap = props.gap ?? 0;
+  const containerIsVertical = node.type === "vstack";
+  const axisMatchesMain = isVertical === containerIsVertical;
+
+  const padMain = isVertical
+    ? (props.padding?.y ?? 0) * 2
+    : (props.padding?.x ?? 0) * 2;
+  const padCross = isVertical
+    ? (props.padding?.x ?? 0) * 2
+    : (props.padding?.y ?? 0) * 2;
+  const innerCross = Math.max(0, crossSize - padCross);
+
+  if (axisMatchesMain) {
+    // Sum children along the main axis + gaps
+    let total = 0;
+    for (let i = 0; i < node.children.length; i++) {
+      const child = node.children[i]!;
+      const cProps = getProps(child);
+
+      let childMain: number;
+      if (isVertical) {
+        childMain =
+          resolveSizeValue(cProps?.height, 0) ??
+          intrinsicMainSize(child, true, innerCross);
+      } else {
+        childMain =
+          resolveSizeValue(cProps?.width, 0) ??
+          intrinsicMainSize(child, false, innerCross);
+      }
+      total += childMain;
+      if (i < node.children.length - 1) total += gap;
+    }
+    return total + padMain;
+  }
+
+  // Cross axis: max of children on the requested axis
+  let maxSize = 0;
+  for (const child of node.children) {
+    const cProps = getProps(child);
+
+    let childSize: number;
+    if (isVertical) {
+      childSize =
+        resolveSizeValue(cProps?.height, 0) ??
+        intrinsicMainSize(child, true, innerCross);
+    } else {
+      childSize =
+        resolveSizeValue(cProps?.width, 0) ??
+        intrinsicMainSize(child, false, innerCross);
+    }
+    if (childSize > maxSize) maxSize = childSize;
+  }
+  return maxSize + padMain;
+}
+
+// --- Largest remainder rounding ---
+
+function largestRemainder(fractions: number[], total: number): number[] {
+  const floored = fractions.map(Math.floor);
+  let remainder = total - floored.reduce((a, b) => a + b, 0);
+
+  const indices = fractions
+    .map((v, i) => ({ i, frac: v - Math.floor(v) }))
+    .sort((a, b) => b.frac - a.frac);
+
+  for (const { i } of indices) {
+    if (remainder <= 0) break;
+    floored[i]!++;
+    remainder--;
+  }
+
+  return floored;
+}
+
+// --- Main layout ---
+
+/**
+ * Compute the layout for a UI tree.
+ *
+ * @param root - The root UI node.
+ * @param availWidth - Available width (typically terminal columns).
+ * @param availHeight - Available height (typically terminal rows).
+ * @returns Layout tree with computed rects.
+ */
+export function layout(
+  root: Node,
+  availWidth: number,
+  availHeight: number,
+): LayoutNode {
+  // Resolve root's own size against the viewport
+  const rootProps = getProps(root);
+  const rootW = resolveSizeValue(rootProps?.width, availWidth) ?? availWidth;
+  const rootH = resolveSizeValue(rootProps?.height, availHeight) ?? availHeight;
+  return layoutNode(root, 0, 0, rootW, rootH);
+}
+
+/**
+ * Layout a node within the given available space.
+ * Resolves the node's own explicit size (if any) against available space,
+ * then lays out children within that.
+ */
+function layoutNode(
+  node: Node,
+  x: number,
+  y: number,
+  availWidth: number,
+  availHeight: number,
+): LayoutNode {
+  // Resolve own dimensions: explicit size wins, otherwise fill available.
+  // Note: for children, the parent has already resolved sizing and passes
+  // the result as availWidth/availHeight. We only re-resolve for the root
+  // node (where available space = viewport, not pre-resolved).
+  const width = availWidth;
+  const height = availHeight;
+  const rect: Rect = { x, y, width, height };
+
+  // Leaf nodes
+  if (node.type === "text" || node.type === "textinput") {
+    return { node, rect, children: [] };
+  }
+
+  // Container nodes
+  const props = node.props;
+  const isVertical = node.type === "vstack";
+  const children = node.children;
+
+  if (children.length === 0) {
+    return { node, rect, children: [] };
+  }
+
+  // Padding
+  const padX = props.padding?.x ?? 0;
+  const padY = props.padding?.y ?? 0;
+  const innerX = x + padX;
+  const innerY = y + padY;
+  const innerW = Math.max(0, width - padX * 2);
+  const innerH = Math.max(0, height - padY * 2);
+
+  // Gap
+  const gap = props.gap ?? 0;
+  const totalGap = gap * (children.length - 1);
+  const mainAvail = (isVertical ? innerH : innerW) - totalGap;
+
+  // --- Measure phase: compute each child's main-axis and cross-axis size ---
+  type ChildInfo = {
+    node: Node;
+    mainSize: number;
+    crossSize: number;
+    flex: number;
+  };
+  const infos: ChildInfo[] = [];
+  let fixedMain = 0;
+  let totalFlex = 0;
+  const align = props.alignItems ?? "stretch";
+  const useIntrinsicCross = align !== "stretch";
+
+  for (const child of children) {
+    const cProps = getProps(child);
+    const flex = cProps?.flex ?? 0;
+
+    if (flex > 0) {
+      totalFlex += flex;
+      // Cross-axis: explicit size, or intrinsic if not stretch, or fill
+      let cross: number;
+      if (isVertical) {
+        cross =
+          resolveSizeValue(cProps?.width, innerW) ??
+          (useIntrinsicCross
+            ? intrinsicMainSize(child, false, innerH)
+            : innerW);
+      } else {
+        cross =
+          resolveSizeValue(cProps?.height, innerH) ??
+          (useIntrinsicCross ? intrinsicMainSize(child, true, innerW) : innerH);
+      }
+      infos.push({ node: child, mainSize: 0, crossSize: cross, flex });
+    } else {
+      // Main-axis: explicit → percentage → intrinsic
+      let main: number;
+      let cross: number;
+      if (isVertical) {
+        main =
+          resolveSizeValue(cProps?.height, innerH) ??
+          intrinsicMainSize(child, true, innerW);
+        cross =
+          resolveSizeValue(cProps?.width, innerW) ??
+          (useIntrinsicCross
+            ? intrinsicMainSize(child, false, innerH)
+            : innerW);
+      } else {
+        main =
+          resolveSizeValue(cProps?.width, innerW) ??
+          intrinsicMainSize(child, false, innerH);
+        cross =
+          resolveSizeValue(cProps?.height, innerH) ??
+          (useIntrinsicCross ? intrinsicMainSize(child, true, innerW) : innerH);
+      }
+
+      // Apply constraints
+      if (cProps) {
+        const minMain = isVertical
+          ? (cProps.minHeight ?? 0)
+          : (cProps.minWidth ?? 0);
+        const maxMain = isVertical
+          ? (cProps.maxHeight ?? Infinity)
+          : (cProps.maxWidth ?? Infinity);
+        main = clamp(main, minMain, maxMain);
+      }
+
+      fixedMain += main;
+      infos.push({ node: child, mainSize: main, crossSize: cross, flex });
+    }
+  }
+
+  // --- Flex distribution ---
+  const flexSpace = Math.max(0, mainAvail - fixedMain);
+
+  if (totalFlex > 0) {
+    const flexInfos = infos.filter((c) => c.flex > 0);
+    const rawSizes = flexInfos.map((c) => (c.flex / totalFlex) * flexSpace);
+    const rounded = largestRemainder(rawSizes, flexSpace);
+
+    for (let i = 0; i < flexInfos.length; i++) {
+      let size = rounded[i]!;
+      const cProps = getProps(flexInfos[i]!.node);
+      if (cProps) {
+        const minMain = isVertical
+          ? (cProps.minHeight ?? 0)
+          : (cProps.minWidth ?? 0);
+        const maxMain = isVertical
+          ? (cProps.maxHeight ?? Infinity)
+          : (cProps.maxWidth ?? Infinity);
+        size = clamp(size, minMain, maxMain);
+      }
+      flexInfos[i]!.mainSize = size;
+    }
+  }
+
+  // --- Position phase ---
+
+  // Compute total main-axis content size (children + gaps)
+  const totalChildMain = infos.reduce((sum, c) => sum + c.mainSize, 0);
+  const totalContent = totalChildMain + totalGap;
+  const mainInner = isVertical ? innerH : innerW;
+  const crossInner = isVertical ? innerW : innerH;
+  const remainingMain = Math.max(0, mainInner - totalContent);
+
+  // justifyContent: compute main-axis starting offset and per-gap extra space
+  const justify = props.justifyContent ?? "start";
+  let mainStart = 0;
+  let betweenGaps: number[] | null = null;
+
+  if (justify === "end") {
+    mainStart = remainingMain;
+  } else if (justify === "center") {
+    mainStart = Math.floor(remainingMain / 2);
+  } else if (justify === "space-between" && infos.length > 1) {
+    // Distribute remaining space into gaps between children
+    const gapCount = infos.length - 1;
+    const rawGaps = Array.from(
+      { length: gapCount },
+      () => remainingMain / gapCount,
+    );
+    betweenGaps = largestRemainder(rawGaps, remainingMain);
+  }
+
+  const layoutChildren: LayoutNode[] = [];
+  let mainOffset = mainStart;
+
+  for (let i = 0; i < infos.length; i++) {
+    const info = infos[i]!;
+
+    // Cross-axis alignment
+    let crossOffset = 0;
+    if (align === "center") {
+      crossOffset = Math.floor((crossInner - info.crossSize) / 2);
+    } else if (align === "end") {
+      crossOffset = crossInner - info.crossSize;
+    }
+    // "start" and "stretch" keep crossOffset = 0
+
+    const childX = isVertical ? innerX + crossOffset : innerX + mainOffset;
+    const childY = isVertical ? innerY + mainOffset : innerY + crossOffset;
+    const childW = isVertical ? info.crossSize : info.mainSize;
+    const childH = isVertical ? info.mainSize : info.crossSize;
+
+    layoutChildren.push(layoutNode(info.node, childX, childY, childW, childH));
+
+    mainOffset += info.mainSize;
+    if (i < infos.length - 1) {
+      mainOffset += gap;
+      if (betweenGaps) {
+        mainOffset += betweenGaps[i]!;
+      }
+    }
+  }
+
+  // --- Intrinsic container sizing ---
+  // If no explicit main-axis size, shrink to fit children
+  const hasExplicitMain = isVertical
+    ? props.height !== undefined || props.flex !== undefined
+    : props.width !== undefined || props.flex !== undefined;
+
+  if (!hasExplicitMain) {
+    const contentMain = mainOffset + (isVertical ? padY * 2 : padX * 2);
+    if (isVertical) {
+      rect.height = contentMain;
+    } else {
+      rect.width = contentMain;
+    }
+  }
+
+  return { node, rect, children: layoutChildren };
+}