@silvery/term 0.3.0

package/src/pipeline/render-box.ts

@@ -0,0 +1,343 @@
+/**
+ * Box Rendering - Functions for rendering box elements to the buffer.
+ *
+ * Contains:
+ * - Box rendering (renderBox)
+ * - Border rendering (renderBorder)
+ * - Scroll indicators (renderScrollIndicators)
+ */
+
+import type { Color, Style, TerminalBuffer } from "../buffer"
+import type { BoxProps, TeaNode, Rect } from "@silvery/tea/types"
+import { getPadding } from "./helpers"
+import { getBorderChars, getBorderSize, parseColor } from "./render-helpers"
+import { renderTextLine } from "./render-text"
+import type { NodeRenderState, PipelineContext } from "./types"
+
+// ============================================================================
+// Box Rendering
+// ============================================================================
+
+/**
+ * Render a Box node.
+ */
+export function renderBox(
+  _node: TeaNode,
+  buffer: TerminalBuffer,
+  layout: Rect,
+  props: BoxProps,
+  nodeState: NodeRenderState,
+  skipBgFill = false,
+  inheritedBg?: Color | null,
+): void {
+  const { scrollOffset, clipBounds } = nodeState
+  const { x, width, height } = layout
+  // Apply scroll offset to y position
+  const y = layout.y - scrollOffset
+
+  // Skip if completely outside clip bounds
+  if (clipBounds) {
+    if (y + height <= clipBounds.top || y >= clipBounds.bottom) return
+    if (clipBounds.left !== undefined && clipBounds.right !== undefined) {
+      if (x + width <= clipBounds.left || x >= clipBounds.right) return
+    }
+  }
+
+  // Fill background if set.
+  // In incremental mode, skipBgFill=true when the box itself hasn't changed
+  // (only subtreeDirty). The cloned buffer already has the correct bg fill,
+  // and re-filling would destroy child pixels that won't be repainted.
+  if (props.backgroundColor && !skipBgFill) {
+    const bg = parseColor(props.backgroundColor)
+    // Clip background fill to bounds
+    if (clipBounds) {
+      const clippedY = Math.max(y, clipBounds.top)
+      const clippedHeight = Math.min(y + height, clipBounds.bottom) - clippedY
+      let clippedX = x
+      let clippedWidth = width
+      if (clipBounds.left !== undefined && clipBounds.right !== undefined) {
+        clippedX = Math.max(x, clipBounds.left)
+        clippedWidth = Math.min(x + width, clipBounds.right) - clippedX
+      }
+      if (clippedHeight > 0 && clippedWidth > 0) {
+        buffer.fill(clippedX, clippedY, clippedWidth, clippedHeight, { bg })
+      }
+    } else {
+      buffer.fill(x, y, width, height, { bg })
+    }
+  }
+
+  // Render border if set
+  if (props.borderStyle) {
+    renderBorder(buffer, x, y, width, height, props, clipBounds, inheritedBg)
+  }
+}
+
+// ============================================================================
+// Border Rendering
+// ============================================================================
+
+/**
+ * Render a border around a box.
+ */
+export function renderBorder(
+  buffer: TerminalBuffer,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  props: BoxProps,
+  clipBounds?: { top: number; bottom: number; left?: number; right?: number },
+  inheritedBg?: Color | null,
+): void {
+  const chars = getBorderChars(props.borderStyle ?? "single")
+  const color = props.borderColor ? parseColor(props.borderColor) : null
+  // Preserve the box's background color on border cells. Falls back to
+  // inherited bg from the nearest ancestor with backgroundColor, ensuring
+  // border cells don't punch transparent holes through parent backgrounds.
+  const bg = props.backgroundColor ? parseColor(props.backgroundColor) : (inheritedBg ?? null)
+
+  const showTop = props.borderTop !== false
+  const showBottom = props.borderBottom !== false
+  const showLeft = props.borderLeft !== false
+  const showRight = props.borderRight !== false
+
+  // Helper to check if a row is visible within clip bounds
+  const isRowVisible = (row: number): boolean => {
+    if (!clipBounds) return row >= 0 && row < buffer.height
+    return row >= clipBounds.top && row < clipBounds.bottom && row < buffer.height
+  }
+
+  // Helper to check if a column is visible within clip bounds
+  const isColVisible = (col: number): boolean => {
+    if (clipBounds?.left === undefined || clipBounds.right === undefined) return col >= 0 && col < buffer.width
+    return col >= clipBounds.left && col < clipBounds.right && col < buffer.width
+  }
+
+  // Top border
+  if (showTop && isRowVisible(y)) {
+    if (showLeft && isColVisible(x)) buffer.setCell(x, y, { char: chars.topLeft, fg: color, bg })
+    const hStart = showLeft ? x + 1 : x
+    const hEnd = showRight ? x + width - 1 : x + width
+    for (let col = hStart; col < hEnd && col < buffer.width; col++) {
+      if (isColVisible(col)) buffer.setCell(col, y, { char: chars.horizontal, fg: color, bg })
+    }
+    if (showRight && x + width - 1 < buffer.width && isColVisible(x + width - 1)) {
+      buffer.setCell(x + width - 1, y, { char: chars.topRight, fg: color, bg })
+    }
+  }
+
+  // Side borders — extend range when top/bottom borders are hidden
+  const rightVertical = chars.rightVertical ?? chars.vertical
+  const sideStart = showTop ? y + 1 : y
+  const sideEnd = showBottom ? y + height - 1 : y + height
+  for (let row = sideStart; row < sideEnd; row++) {
+    if (!isRowVisible(row)) continue
+    if (showLeft && isColVisible(x)) buffer.setCell(x, row, { char: chars.vertical, fg: color, bg })
+    if (showRight && x + width - 1 < buffer.width && isColVisible(x + width - 1)) {
+      buffer.setCell(x + width - 1, row, { char: rightVertical, fg: color, bg })
+    }
+  }
+
+  // Bottom border
+  const bottomHorizontal = chars.bottomHorizontal ?? chars.horizontal
+  const bottomY = y + height - 1
+  if (showBottom && isRowVisible(bottomY)) {
+    if (showLeft && isColVisible(x)) {
+      buffer.setCell(x, bottomY, { char: chars.bottomLeft, fg: color, bg })
+    }
+    const bStart = showLeft ? x + 1 : x
+    const bEnd = showRight ? x + width - 1 : x + width
+    for (let col = bStart; col < bEnd && col < buffer.width; col++) {
+      if (isColVisible(col)) buffer.setCell(col, bottomY, { char: bottomHorizontal, fg: color, bg })
+    }
+    if (showRight && x + width - 1 < buffer.width && isColVisible(x + width - 1)) {
+      buffer.setCell(x + width - 1, bottomY, {
+        char: chars.bottomRight,
+        fg: color,
+        bg,
+      })
+    }
+  }
+}
+
+// ============================================================================
+// Outline Rendering
+// ============================================================================
+
+/**
+ * Render an outline around a box.
+ *
+ * Unlike borders, outlines do NOT affect layout dimensions. They draw border
+ * characters that OVERLAP the content area at the node's screen rect edges.
+ * This is the CSS `outline` equivalent for terminal UI.
+ */
+export function renderOutline(
+  buffer: TerminalBuffer,
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+  props: BoxProps,
+  clipBounds?: { top: number; bottom: number; left?: number; right?: number },
+  inheritedBg?: Color | null,
+): void {
+  const chars = getBorderChars(props.outlineStyle ?? "single")
+  const color = props.outlineColor ? parseColor(props.outlineColor) : null
+  const bg = props.backgroundColor ? parseColor(props.backgroundColor) : (inheritedBg ?? null)
+  const attrs = props.outlineDimColor ? { dim: true } : {}
+
+  // Helper to check if a row is visible within clip bounds
+  const isRowVisible = (row: number): boolean => {
+    if (!clipBounds) return row >= 0 && row < buffer.height
+    return row >= clipBounds.top && row < clipBounds.bottom && row < buffer.height
+  }
+
+  // Helper to check if a column is visible within clip bounds
+  const isColVisible = (col: number): boolean => {
+    if (clipBounds?.left === undefined || clipBounds.right === undefined) return col >= 0 && col < buffer.width
+    return col >= clipBounds.left && col < clipBounds.right && col < buffer.width
+  }
+
+  const showTop = props.outlineTop !== false
+  const showBottom = props.outlineBottom !== false
+  const showLeft = props.outlineLeft !== false
+  const showRight = props.outlineRight !== false
+
+  // Top border
+  if (showTop && isRowVisible(y)) {
+    if (showLeft && isColVisible(x)) buffer.setCell(x, y, { char: chars.topLeft, fg: color, bg, attrs })
+    for (let col = x + 1; col < x + width - 1 && col < buffer.width; col++) {
+      if (isColVisible(col)) buffer.setCell(col, y, { char: chars.horizontal, fg: color, bg, attrs })
+    }
+    if (showRight && x + width - 1 < buffer.width && isColVisible(x + width - 1)) {
+      buffer.setCell(x + width - 1, y, { char: chars.topRight, fg: color, bg, attrs })
+    }
+  }
+
+  // Side borders — extend range when top/bottom are hidden
+  const outlineRightVertical = chars.rightVertical ?? chars.vertical
+  const sideStart = showTop ? y + 1 : y
+  const sideEnd = showBottom ? y + height - 1 : y + height
+  for (let row = sideStart; row < sideEnd; row++) {
+    if (!isRowVisible(row)) continue
+    if (showLeft && isColVisible(x)) buffer.setCell(x, row, { char: chars.vertical, fg: color, bg, attrs })
+    if (showRight && x + width - 1 < buffer.width && isColVisible(x + width - 1)) {
+      buffer.setCell(x + width - 1, row, { char: outlineRightVertical, fg: color, bg, attrs })
+    }
+  }
+
+  // Bottom border
+  const outlineBottomHorizontal = chars.bottomHorizontal ?? chars.horizontal
+  const bottomY = y + height - 1
+  if (showBottom && isRowVisible(bottomY)) {
+    if (showLeft && isColVisible(x)) {
+      buffer.setCell(x, bottomY, { char: chars.bottomLeft, fg: color, bg, attrs })
+    }
+    for (let col = x + 1; col < x + width - 1 && col < buffer.width; col++) {
+      if (isColVisible(col)) buffer.setCell(col, bottomY, { char: outlineBottomHorizontal, fg: color, bg, attrs })
+    }
+    if (showRight && x + width - 1 < buffer.width && isColVisible(x + width - 1)) {
+      buffer.setCell(x + width - 1, bottomY, {
+        char: chars.bottomRight,
+        fg: color,
+        bg,
+        attrs,
+      })
+    }
+  }
+}
+
+// ============================================================================
+// Scroll Indicators
+// ============================================================================
+
+/**
+ * Render scroll indicators showing hidden items above/below viewport.
+ *
+ * Two rendering modes:
+ * 1. Bordered containers: Indicators appear on the border (e.g., "───▲42───")
+ * 2. Borderless containers with overflowIndicator: Indicators appear directly
+ *    after the last visible child (not at the viewport bottom)
+ *
+ * Uses ▲N for items hidden above, ▼N for items hidden below.
+ */
+export function renderScrollIndicators(
+  _node: TeaNode,
+  buffer: TerminalBuffer,
+  layout: Rect,
+  props: BoxProps,
+  ss: NonNullable<TeaNode["scrollState"]>,
+  ctx?: PipelineContext,
+): void {
+  const border = props.borderStyle ? getBorderSize(props) : { top: 0, bottom: 0, left: 0, right: 0 }
+
+  // Inverse bar style: white text on dark background
+  const indicatorStyle: Style = {
+    fg: 15, // Bright white
+    bg: 8, // Dark gray
+    attrs: {},
+  }
+
+  // Determine if we should show indicators for borderless containers
+  const showBorderless = props.overflowIndicator === true
+
+  // Top indicator
+  if (ss.hiddenAbove > 0) {
+    const indicator = `\u25b2${ss.hiddenAbove}`
+
+    if (border.top > 0) {
+      // Bordered: render centered inverse bar on top border line
+      const contentWidth = layout.width - border.left - border.right
+      const bar = padCenter(indicator, contentWidth)
+      const x = layout.x + border.left
+      const y = layout.y
+      const maxCol = x + contentWidth
+      renderTextLine(buffer, x, y, bar, indicatorStyle, maxCol, undefined, ctx)
+    } else if (showBorderless) {
+      // Borderless: render centered inverse bar on first content row
+      const padding = getPadding(props)
+      const contentWidth = layout.width - padding.left - padding.right
+      const bar = padCenter(indicator, contentWidth)
+      const x = layout.x + padding.left
+      const y = layout.y + padding.top
+      const maxCol = x + contentWidth
+      renderTextLine(buffer, x, y, bar, indicatorStyle, maxCol, undefined, ctx)
+    }
+  }
+
+  // Bottom indicator
+  if (ss.hiddenBelow > 0) {
+    const indicator = `\u25bc${ss.hiddenBelow}`
+
+    if (border.bottom > 0) {
+      // Bordered: render centered inverse bar on bottom border line
+      const contentWidth = layout.width - border.left - border.right
+      const bar = padCenter(indicator, contentWidth)
+      const x = layout.x + border.left
+      const y = layout.y + layout.height - 1
+      const maxCol = x + contentWidth
+      renderTextLine(buffer, x, y, bar, indicatorStyle, maxCol, undefined, ctx)
+    } else if (showBorderless) {
+      // Borderless: render indicator flush to viewport bottom
+      const padding = getPadding(props)
+      const contentWidth = layout.width - padding.left - padding.right
+      const bar = padCenter(indicator, contentWidth)
+      const x = layout.x + padding.left
+      const y = layout.y + layout.height - padding.bottom - 1
+      const maxCol = x + contentWidth
+      renderTextLine(buffer, x, y, bar, indicatorStyle, maxCol, undefined, ctx)
+    }
+  }
+}
+
+/** Center text within a fixed width, padding with spaces on both sides.
+ *  Truncates from the right if text exceeds available width. */
+function padCenter(text: string, width: number): string {
+  if (width <= 0) return ""
+  if (text.length > width) return text.slice(0, width)
+  if (text.length === width) return text
+  const leftPad = Math.floor((width - text.length) / 2)
+  const rightPad = width - text.length - leftPad
+  return " ".repeat(leftPad) + text + " ".repeat(rightPad)
+}

package/src/pipeline/render-helpers.ts

@@ -0,0 +1,243 @@
+/**
+ * Render Helpers - Pure utility functions for content rendering.
+ *
+ * Contains:
+ * - Color parsing (parseColor)
+ * - Border character definitions (getBorderChars)
+ * - Style extraction (getTextStyle)
+ * - Text width utilities (getTextWidth)
+ *
+ * Re-exports layout helpers from helpers.ts:
+ * - getPadding, getBorderSize
+ */
+
+import { DEFAULT_BG, type Color, type Style, type UnderlineStyle } from "../buffer"
+import { getActiveTheme } from "@silvery/theme/state"
+import { resolveThemeColor } from "@silvery/theme/resolve"
+import type { BoxProps, TextProps } from "@silvery/tea/types"
+import { displayWidthAnsi } from "../unicode"
+import type { BorderChars, PipelineContext } from "./types"
+
+// Re-export shared layout helpers
+export { getBorderSize, getPadding } from "./helpers"
+
+// ============================================================================
+// Color Parsing
+// ============================================================================
+
+// Named colors map to 256-color indices (hoisted to module scope to avoid per-call allocation)
+const namedColors: Record<string, number> = {
+  black: 0,
+  red: 1,
+  green: 2,
+  yellow: 3,
+  blue: 4,
+  magenta: 5,
+  cyan: 6,
+  white: 7,
+  gray: 8,
+  grey: 8,
+  blackBright: 8,
+  redBright: 9,
+  greenBright: 10,
+  yellowBright: 11,
+  blueBright: 12,
+  magentaBright: 13,
+  cyanBright: 14,
+  whiteBright: 15,
+}
+
+/**
+ * Parse color string to Color type.
+ * Supports: $token (theme), named colors, hex (#rgb, #rrggbb), rgb(r,g,b)
+ */
+export function parseColor(color: string): Color {
+  // Special token: terminal's default background (SGR 49)
+  if (color === "$default") return DEFAULT_BG
+
+  // Resolve $token colors against the active theme
+  if (color.startsWith("$")) {
+    const resolved = resolveThemeColor(color, getActiveTheme())
+    if (resolved && resolved !== color) return parseColor(resolved)
+    return null
+  }
+
+  if (color in namedColors) {
+    return namedColors[color as keyof typeof namedColors]!
+  }
+
+  // Hex color
+  if (color.startsWith("#")) {
+    const hex = color.slice(1)
+    if (hex.length === 3) {
+      const r = Number.parseInt(hex[0]! + hex[0]!, 16)
+      const g = Number.parseInt(hex[1]! + hex[1]!, 16)
+      const b = Number.parseInt(hex[2]! + hex[2]!, 16)
+      return { r, g, b }
+    }
+    if (hex.length === 6) {
+      const r = Number.parseInt(hex.slice(0, 2), 16)
+      const g = Number.parseInt(hex.slice(2, 4), 16)
+      const b = Number.parseInt(hex.slice(4, 6), 16)
+      return { r, g, b }
+    }
+  }
+
+  // rgb(r,g,b)
+  const rgbMatch = color.match(/^rgb\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)$/i)
+  if (rgbMatch) {
+    return {
+      r: Number.parseInt(rgbMatch[1]!, 10),
+      g: Number.parseInt(rgbMatch[2]!, 10),
+      b: Number.parseInt(rgbMatch[3]!, 10),
+    }
+  }
+
+  // ansi256(N) — 256-color palette index (0-255)
+  const ansi256Match = color.match(/^ansi256\s*\(\s*(\d+)\s*\)$/i)
+  if (ansi256Match) {
+    return Number.parseInt(ansi256Match[1]!, 10)
+  }
+
+  return null
+}
+
+// ============================================================================
+// Border Characters
+// ============================================================================
+
+/**
+ * Border character sets by style. Hoisted to module scope to avoid
+ * re-allocating 7 objects on every call.
+ */
+const borders: Record<NonNullable<BoxProps["borderStyle"]>, BorderChars> = {
+  single: {
+    topLeft: "\u250c",
+    topRight: "\u2510",
+    bottomLeft: "\u2514",
+    bottomRight: "\u2518",
+    horizontal: "\u2500",
+    vertical: "\u2502",
+  },
+  double: {
+    topLeft: "\u2554",
+    topRight: "\u2557",
+    bottomLeft: "\u255a",
+    bottomRight: "\u255d",
+    horizontal: "\u2550",
+    vertical: "\u2551",
+  },
+  round: {
+    topLeft: "\u256d",
+    topRight: "\u256e",
+    bottomLeft: "\u2570",
+    bottomRight: "\u256f",
+    horizontal: "\u2500",
+    vertical: "\u2502",
+  },
+  bold: {
+    topLeft: "\u250f",
+    topRight: "\u2513",
+    bottomLeft: "\u2517",
+    bottomRight: "\u251b",
+    horizontal: "\u2501",
+    vertical: "\u2503",
+  },
+  singleDouble: {
+    topLeft: "\u2553",
+    topRight: "\u2556",
+    bottomLeft: "\u2559",
+    bottomRight: "\u255c",
+    horizontal: "\u2500",
+    vertical: "\u2551",
+  },
+  doubleSingle: {
+    topLeft: "\u2552",
+    topRight: "\u2555",
+    bottomLeft: "\u2558",
+    bottomRight: "\u255b",
+    horizontal: "\u2550",
+    vertical: "\u2502",
+  },
+  classic: {
+    topLeft: "+",
+    topRight: "+",
+    bottomLeft: "+",
+    bottomRight: "+",
+    horizontal: "-",
+    vertical: "|",
+  },
+}
+
+/**
+ * Get border characters for a style.
+ */
+export function getBorderChars(style: BoxProps["borderStyle"]): BorderChars {
+  if (style && typeof style === "object") {
+    // Custom border object (Ink compat): map Ink's top/bottom/left/right to
+    // silvery's horizontal/vertical format. Supports distinct chars per side.
+    const obj = style as Record<string, string>
+    const topHorizontal = obj.top ?? obj.horizontal ?? "-"
+    const leftVertical = obj.left ?? obj.vertical ?? "|"
+    return {
+      topLeft: obj.topLeft ?? "+",
+      topRight: obj.topRight ?? "+",
+      bottomLeft: obj.bottomLeft ?? "+",
+      bottomRight: obj.bottomRight ?? "+",
+      horizontal: topHorizontal,
+      vertical: leftVertical,
+      bottomHorizontal: obj.bottom && obj.bottom !== topHorizontal ? obj.bottom : undefined,
+      rightVertical: obj.right && obj.right !== leftVertical ? obj.right : undefined,
+    }
+  }
+  return borders[style ?? "single"]
+}
+
+// ============================================================================
+// Style Extraction
+// ============================================================================
+
+/**
+ * Get text style from props.
+ */
+export function getTextStyle(props: TextProps): Style {
+  // Determine underline style: underlineStyle takes precedence over underline boolean
+  let underlineStyle: UnderlineStyle | undefined
+  if (props.underlineStyle !== undefined) {
+    underlineStyle = props.underlineStyle
+  } else if (props.underline) {
+    underlineStyle = "single"
+  }
+
+  return {
+    fg: props.color ? parseColor(props.color) : null,
+    bg: props.backgroundColor ? parseColor(props.backgroundColor) : null,
+    underlineColor: props.underlineColor ? parseColor(props.underlineColor) : null,
+    attrs: {
+      bold: props.bold,
+      dim: props.dim || props.dimColor, // dimColor is Ink compatibility alias
+      italic: props.italic,
+      underline: props.underline || !!underlineStyle,
+      underlineStyle,
+      strikethrough: props.strikethrough,
+      inverse: props.inverse,
+    },
+  }
+}
+
+// ============================================================================
+// Text Width Utilities
+// ============================================================================
+
+/**
+ * Get text display width (accounting for wide characters and ANSI codes).
+ * Uses ANSI-aware width calculation to handle styled text.
+ *
+ * When a PipelineContext is provided, uses the context's measurer for
+ * terminal-capability-aware width calculation. Falls back to the module-level
+ * displayWidthAnsi (which reads the scoped measurer or default).
+ */
+export function getTextWidth(text: string, ctx?: PipelineContext): number {
+  if (ctx) return ctx.measurer.displayWidthAnsi(text)
+  return displayWidthAnsi(text)
+}