@xincli/opentui-core 0.4.6

package/src/renderables/__tests__/renderable-test-utils.ts

@@ -0,0 +1,60 @@
+import { TextareaRenderable } from "../Textarea.js"
+import { type TestRenderer } from "../../testing/test-renderer.js"
+import { type TextareaOptions } from "../Textarea.js"
+import type { DiffRenderable } from "../Diff.js"
+import type { CodeRenderable } from "../Code.js"
+import type { MockTreeSitterClient } from "../../testing/mock-tree-sitter-client.js"
+import type { ManualClock } from "../../testing/manual-clock.js"
+
+export async function createTextareaRenderable(
+  renderer: TestRenderer,
+  renderOnce: () => Promise<void>,
+  options: TextareaOptions,
+): Promise<{ textarea: TextareaRenderable; root: any }> {
+  const textareaRenderable = new TextareaRenderable(renderer, { left: 0, top: 0, ...options })
+  renderer.root.add(textareaRenderable)
+  await renderOnce()
+
+  return { textarea: textareaRenderable, root: renderer.root }
+}
+
+// Settle Diff highlighting deterministically. Each iteration:
+// 1. Render twice — the first render may trigger Diff.requestRebuild via microtask
+//    (runs during renderOnce's internal awaits), which calls requestRender while
+//    rendering=true, setting immediateRerenderRequested. The resulting re-render
+//    is scheduled via clock.setTimeout (ManualClock), so needs a second renderOnce.
+// 2. Resolve all pending highlights (proper signal via mock)
+// 3. Await Code.highlightingDone on both sides (proper signal from Code)
+// Loop exits when mock has no more pending requests (state-based, not count-based).
+export async function settleDiffHighlighting(
+  diff: DiffRenderable,
+  client: MockTreeSitterClient,
+  render: () => Promise<void>,
+) {
+  const MAX = 15
+  for (let i = 0; i < MAX; i++) {
+    await render()
+    await render()
+    if (!client.isHighlighting()) break
+    client.resolveAllHighlightOnce()
+    const left: CodeRenderable | null = (diff as any).leftCodeRenderable
+    const right: CodeRenderable | null = (diff as any).rightCodeRenderable
+    if (left) await left.highlightingDone
+    if (right) await right.highlightingDone
+  }
+}
+
+// Simulate the passage of time by advancing a ManualClock and rendering frames.
+// Useful for testing animations, scroll momentum, and other time-dependent behavior.
+export async function simulateFrames(
+  clock: ManualClock,
+  renderOnce: () => Promise<void>,
+  ms: number,
+  frameInterval: number = 50,
+): Promise<void> {
+  const frames = Math.ceil(ms / frameInterval)
+  for (let i = 0; i < frames; i++) {
+    clock.advance(frameInterval)
+    await renderOnce()
+  }
+}

package/src/renderables/composition/README.md

@@ -0,0 +1,8 @@
+# Composition Exploration
+
+This is a simple exploration of how to compose renderables into a tree.
+
+It's not react and not reactive, it's just a way to compose renderables
+and mount them into a parent container.
+
+It's a work in progress and not in any way meant to be a replacement for react.

package/src/renderables/composition/VRenderable.ts

@@ -0,0 +1,32 @@
+import { Renderable, type RenderableOptions } from "../../Renderable.js"
+import type { OptimizedBuffer } from "../../buffer.js"
+import type { RenderContext } from "../../types.js"
+
+export interface VRenderableOptions extends RenderableOptions<VRenderable> {
+  render?: (
+    this: VRenderable | VRenderableOptions,
+    buffer: OptimizedBuffer,
+    deltaTime: number,
+    renderable: VRenderable,
+  ) => void
+}
+
+/**
+ * A generic renderable that accepts a custom render function as a prop.
+ * This allows functional constructs to specify custom rendering behavior
+ * without needing to subclass Renderable.
+ */
+export class VRenderable extends Renderable {
+  private options: VRenderableOptions
+
+  constructor(ctx: RenderContext, options: VRenderableOptions) {
+    super(ctx, options)
+    this.options = options
+  }
+
+  protected renderSelf(buffer: OptimizedBuffer, deltaTime: number): void {
+    if (this.options.render) {
+      this.options.render.call(this.options, buffer, deltaTime, this)
+    }
+  }
+}

package/src/renderables/composition/constructs.ts

@@ -0,0 +1,127 @@
+import {
+  ASCIIFontRenderable,
+  BoxRenderable,
+  CodeRenderable,
+  InputRenderable,
+  ScrollBoxRenderable,
+  SelectRenderable,
+  TabSelectRenderable,
+  TextRenderable,
+  VRenderable,
+  FrameBufferRenderable,
+  type ASCIIFontOptions,
+  type BoxOptions,
+  type CodeOptions,
+  type TextOptions,
+  type VRenderableOptions,
+  type InputRenderableOptions,
+  type ScrollBoxOptions,
+  type SelectRenderableOptions,
+  type TabSelectRenderableOptions,
+  type FrameBufferOptions,
+} from "..//index.js"
+import { TextNodeRenderable, type TextNodeOptions } from "../TextNode.js"
+import { h, type VChild } from "./vnode.js"
+import { TextAttributes } from "../../types.js"
+import type { RGBA } from "../../lib/RGBA.js"
+
+export function Generic(props?: VRenderableOptions, ...children: VChild[]) {
+  return h(VRenderable, props || {}, ...children)
+}
+
+export function Box(props?: BoxOptions, ...children: VChild[]) {
+  return h(BoxRenderable, props || {}, ...children)
+}
+
+export function Text(props?: TextOptions & { content?: any }, ...children: VChild[] | TextNodeRenderable[]) {
+  return h(TextRenderable, props || {}, ...(children as VChild[]))
+}
+
+export function ASCIIFont(props?: ASCIIFontOptions, ...children: VChild[]) {
+  return h(ASCIIFontRenderable, props || {}, ...children)
+}
+
+export function Input(props?: InputRenderableOptions, ...children: VChild[]) {
+  return h(InputRenderable, props || {}, ...children)
+}
+
+export function Select(props?: SelectRenderableOptions, ...children: VChild[]) {
+  return h(SelectRenderable, props || {}, ...children)
+}
+
+export function TabSelect(props?: TabSelectRenderableOptions, ...children: VChild[]) {
+  return h(TabSelectRenderable, props || {}, ...children)
+}
+
+export function FrameBuffer(props: FrameBufferOptions, ...children: VChild[]) {
+  return h(FrameBufferRenderable, props, ...children)
+}
+
+export function Code(props: CodeOptions, ...children: VChild[]) {
+  return h(CodeRenderable, props, ...children)
+}
+
+export function ScrollBox(props?: ScrollBoxOptions, ...children: VChild[]) {
+  return h(ScrollBoxRenderable, props || {}, ...children)
+}
+
+interface StyledTextProps extends Omit<TextNodeOptions, "attributes"> {
+  attributes?: number
+}
+
+function StyledText(props?: StyledTextProps, ...children: (string | TextNodeRenderable)[]): TextNodeRenderable {
+  const styledProps = props as StyledTextProps
+  const textNodeOptions: TextNodeOptions = {
+    ...styledProps,
+    attributes: styledProps?.attributes ?? 0,
+  }
+
+  const textNode = new TextNodeRenderable(textNodeOptions)
+
+  for (const child of children) {
+    textNode.add(child)
+  }
+
+  return textNode
+}
+
+// Text styling convenience functions - these create TextNodeRenderable instances that can be nested and stacked
+export const vstyles = {
+  // Basic text styles
+  bold: (...children: (string | TextNodeRenderable)[]) => StyledText({ attributes: TextAttributes.BOLD }, ...children),
+  italic: (...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ attributes: TextAttributes.ITALIC }, ...children),
+  underline: (...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ attributes: TextAttributes.UNDERLINE }, ...children),
+  dim: (...children: (string | TextNodeRenderable)[]) => StyledText({ attributes: TextAttributes.DIM }, ...children),
+  blink: (...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ attributes: TextAttributes.BLINK }, ...children),
+  inverse: (...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ attributes: TextAttributes.INVERSE }, ...children),
+  hidden: (...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ attributes: TextAttributes.HIDDEN }, ...children),
+  strikethrough: (...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ attributes: TextAttributes.STRIKETHROUGH }, ...children),
+
+  // Combined styles
+  boldItalic: (...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ attributes: TextAttributes.BOLD | TextAttributes.ITALIC }, ...children),
+  boldUnderline: (...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ attributes: TextAttributes.BOLD | TextAttributes.UNDERLINE }, ...children),
+  italicUnderline: (...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ attributes: TextAttributes.ITALIC | TextAttributes.UNDERLINE }, ...children),
+  boldItalicUnderline: (...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ attributes: TextAttributes.BOLD | TextAttributes.ITALIC | TextAttributes.UNDERLINE }, ...children),
+
+  // Color helpers
+  color: (color: string | RGBA, ...children: (string | TextNodeRenderable)[]) => StyledText({ fg: color }, ...children),
+  bgColor: (bgColor: string | RGBA, ...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ bg: bgColor }, ...children),
+  fg: (color: string | RGBA, ...children: (string | TextNodeRenderable)[]) => StyledText({ fg: color }, ...children),
+  bg: (bgColor: string | RGBA, ...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ bg: bgColor }, ...children),
+
+  // Custom styling function
+  styled: (attributes: number = 0, ...children: (string | TextNodeRenderable)[]) =>
+    StyledText({ attributes }, ...children),
+}

package/src/renderables/composition/vnode.ts

@@ -0,0 +1,277 @@
+import { isRenderable, Renderable, type RenderableOptions } from "../../Renderable.js"
+import type { RenderContext } from "../../types.js"
+import util from "node:util"
+
+export type VChild = VNode | Renderable | VChild[] | null | undefined | false
+
+export interface PendingCall {
+  method: string
+  args: any[]
+  isProperty?: boolean
+}
+
+const BrandedVNode: unique symbol = Symbol.for("@opentui/core/VNode")
+
+export interface VNode<P = any, C = VChild[]> {
+  [BrandedVNode]: true
+  type: Construct<P>
+  props?: P
+  children?: C
+  __delegateMap?: Record<string, string>
+  __pendingCalls?: PendingCall[]
+}
+
+// Type that represents a VNode with Renderable methods available for chaining
+export type ProxiedVNode<TCtor extends RenderableConstructor<any>> = VNode<
+  TCtor extends RenderableConstructor<infer P> ? P : any
+> & {
+  [K in keyof InstanceType<TCtor>]: InstanceType<TCtor>[K] extends (...args: infer Args) => any
+    ? (...args: Args) => ProxiedVNode<TCtor>
+    : InstanceType<TCtor>[K]
+}
+
+export interface RenderableConstructor<P extends RenderableOptions<any> = RenderableOptions<any>> {
+  new (ctx: RenderContext, options: P): Renderable
+}
+
+export type FunctionalConstruct<P = any> = (props: P, children?: VChild[]) => VNode
+
+export type Construct<P = any> =
+  | RenderableConstructor<P extends RenderableOptions<any> ? P : never>
+  | FunctionalConstruct<P>
+
+function isRenderableConstructor<P extends RenderableOptions<any> = RenderableOptions<any>>(
+  value: any,
+): value is RenderableConstructor<P> {
+  return typeof value === "function" && value.prototype && Renderable.prototype.isPrototypeOf(value.prototype)
+}
+
+function flattenChildren(children: VChild[]): VChild[] {
+  const result: VChild[] = []
+  for (const child of children) {
+    if (Array.isArray(child)) {
+      result.push(...flattenChildren(child))
+    } else if (child !== null && child !== undefined && child !== false) {
+      result.push(child)
+    }
+  }
+  return result
+}
+
+// Overloads for proper typing
+export function h<TCtor extends RenderableConstructor<any>>(
+  type: TCtor,
+  props?: TCtor extends RenderableConstructor<infer P> ? P : never,
+  ...children: VChild[]
+): ProxiedVNode<TCtor>
+export function h<P>(type: FunctionalConstruct<P>, props?: P, ...children: VChild[]): VNode<P>
+export function h<P>(type: Construct<P>, props?: P, ...children: VChild[]): VNode<P> | ProxiedVNode<any>
+export function h<P>(type: Construct<P>, props?: P, ...children: VChild[]): any {
+  if (typeof type !== "function") {
+    throw new TypeError("h() received an invalid vnode type")
+  }
+
+  const vnode: VNode<P> = {
+    [BrandedVNode]: true,
+    type,
+    props,
+    children: flattenChildren(children),
+    __pendingCalls: [],
+  }
+
+  if (isRenderableConstructor(type)) {
+    return new Proxy(vnode, {
+      get(target, prop, receiver) {
+        // Return VNode properties directly
+        if (prop in target) {
+          return Reflect.get(target, prop, receiver)
+        }
+
+        if (typeof prop === "string") {
+          const prototype = type.prototype
+          const hasMethod =
+            prototype &&
+            (typeof prototype[prop] === "function" ||
+              Object.getOwnPropertyDescriptor(prototype, prop) ||
+              Object.getOwnPropertyDescriptor(Object.getPrototypeOf(prototype), prop))
+
+          if (hasMethod) {
+            return (...args: any[]) => {
+              target.__pendingCalls = target.__pendingCalls || []
+              target.__pendingCalls.push({ method: prop, args })
+              return target
+            }
+          }
+        }
+
+        return Reflect.get(target, prop, receiver)
+      },
+
+      set(target, prop, value, receiver) {
+        if (typeof prop === "string" && isRenderableConstructor(type)) {
+          const prototype = type.prototype
+          const descriptor =
+            Object.getOwnPropertyDescriptor(prototype, prop) ||
+            Object.getOwnPropertyDescriptor(Object.getPrototypeOf(prototype), prop)
+
+          if (descriptor && descriptor.set) {
+            target.__pendingCalls = target.__pendingCalls || []
+            target.__pendingCalls.push({ method: prop, args: [value], isProperty: true })
+            return true
+          }
+        }
+
+        return Reflect.set(target, prop, value, receiver)
+      },
+    })
+  }
+
+  return vnode
+}
+
+export function isVNode(node: any): node is VNode {
+  return node && node[BrandedVNode]
+}
+
+export function maybeMakeRenderable(
+  ctx: RenderContext,
+  node: Renderable | VNode<any, any[]> | unknown,
+): Renderable | null {
+  if (isRenderable(node)) return node
+  if (isVNode(node)) return instantiate(ctx, node)
+  if (process.env.NODE_ENV !== "production") {
+    console.warn("maybeMakeRenderable received an invalid node", util.inspect(node, { depth: 2 }))
+  }
+  return null
+}
+
+export function wrapWithDelegates<T extends InstanceType<RenderableConstructor>>(
+  instance: T,
+  delegateMap: Record<string, string> | undefined,
+): T {
+  if (!delegateMap || Object.keys(delegateMap).length === 0) return instance
+
+  const getDescendant = (id: string): Renderable | undefined => {
+    return (instance as Renderable).findDescendantById(id)
+  }
+
+  const proxy = new Proxy(instance as any, {
+    get(target, prop, receiver) {
+      if (typeof prop === "string" && delegateMap[prop]) {
+        const host = getDescendant(delegateMap[prop])
+        if (host) {
+          const value = (host as any)[prop]
+          if (typeof value === "function") {
+            return value.bind(host)
+          }
+          return value
+        }
+      }
+      return Reflect.get(target, prop, receiver)
+    },
+    set(target, prop, value, receiver) {
+      if (typeof prop === "string" && delegateMap[prop]) {
+        const host = getDescendant(delegateMap[prop])
+        if (host) {
+          return Reflect.set(host as any, prop, value)
+        }
+      }
+      return Reflect.set(target, prop, value, receiver)
+    },
+  })
+  return proxy
+}
+
+export type InstantiateFn<NodeType extends VNode | Renderable> = Renderable & { __node?: NodeType }
+
+export function instantiate<NodeType extends VNode | Renderable>(
+  ctx: RenderContext,
+  node: NodeType,
+): InstantiateFn<NodeType> {
+  if (isRenderable(node)) return node
+
+  if (!node || typeof node !== "object") {
+    throw new TypeError("mount() received an invalid vnode")
+  }
+
+  const vnode = node as VNode
+  const { type, props } = vnode
+  const children = flattenChildren(vnode.children || [])
+  const delegateMap = (vnode as any).__delegateMap as Record<string, string> | undefined
+
+  if (isRenderableConstructor(type)) {
+    const instance = new type(ctx, (props || {}) as any)
+
+    for (const child of children) {
+      if (isRenderable(child)) {
+        instance.add(child)
+      } else {
+        const mounted = instantiate(ctx, child as NodeType)
+        instance.add(mounted)
+      }
+    }
+
+    const delegatedInstance = wrapWithDelegates(instance, delegateMap)
+
+    const pendingCalls = (vnode as any).__pendingCalls as PendingCall[] | undefined
+    if (pendingCalls) {
+      for (const call of pendingCalls) {
+        if (call.isProperty) {
+          ;(delegatedInstance as any)[call.method] = call.args[0]
+        } else {
+          ;(delegatedInstance as any)[call.method].apply(delegatedInstance, call.args)
+        }
+      }
+    }
+
+    return delegatedInstance
+  }
+
+  // Functional construct: resolve to a concrete vnode and mount it
+  const resolved = (type as FunctionalConstruct)(props || ({} as any), children)
+  const inst = instantiate(ctx, resolved)
+
+  return wrapWithDelegates(inst, delegateMap) as InstantiateFn<NodeType>
+}
+
+export type DelegateMap<T> = Partial<Record<keyof T, string>>
+
+export type ValidateShape<Given, AllowedKeys> = {
+  [K in keyof Given]: K extends keyof AllowedKeys ? NonNullable<Given[K]> : never
+}
+
+type InferNode<T> = T extends InstantiateFn<infer U> ? U : never
+
+export function delegate<
+  Factory extends InstantiateFn<any>,
+  InnerNode extends InferNode<Factory>,
+  TargetMap extends Record<keyof InnerNode, string>,
+  const Mapping extends Partial<TargetMap>,
+>(mapping: ValidateShape<Mapping, TargetMap>, vnode: Factory): Renderable
+
+export function delegate<
+  ConstructorType extends RenderableConstructor<any>,
+  TargetMap extends Record<keyof InstanceType<ConstructorType>, string>,
+  const Mapping extends Partial<TargetMap>,
+>(mapping: ValidateShape<Mapping, TargetMap>, vnode: ProxiedVNode<ConstructorType>): ProxiedVNode<ConstructorType>
+
+export function delegate<
+  ConstructorType extends RenderableConstructor<any>,
+  const Mapping extends DelegateMap<InstanceType<ConstructorType>>,
+>(mapping: ValidateShape<Mapping, string>, vnode: VNode & { type: ConstructorType }): VNode
+
+/**
+ * Controlled delegation that routes selected properties/methods
+ * to a descendant renderable identified by ID.
+ */
+export function delegate<NodeType extends VNode | Renderable | InstantiateFn<any>>(
+  mapping: Record<string, string>,
+  vnode: NodeType,
+): VNode | Renderable {
+  if (isRenderable(vnode)) {
+    return wrapWithDelegates(vnode, mapping)
+  }
+  if (!vnode || typeof vnode !== "object") return vnode
+  vnode.__delegateMap = { ...(vnode.__delegateMap || {}), ...mapping }
+  return vnode
+}

package/src/renderables/index.ts

@@ -0,0 +1,23 @@
+export * from "./ASCIIFont.js"
+export * from "./Box.js"
+export * from "./Code.js"
+export * from "./composition/constructs.js"
+export * from "./composition/VRenderable.js"
+export * from "./composition/vnode.js"
+export * from "./Diff.js"
+export * from "./EditBufferRenderable.js"
+export * from "./FrameBuffer.js"
+export * from "./Input.js"
+export * from "./LineNumberRenderable.js"
+export * from "./Markdown.js"
+export * from "./ScrollBar.js"
+export * from "./ScrollBox.js"
+export * from "./Select.js"
+export * from "./Slider.js"
+export * from "./TextTable.js"
+export * from "./TabSelect.js"
+export * from "./Text.js"
+export * from "./TimeToFirstDraw.js"
+export * from "./TextBufferRenderable.js"
+export * from "./TextNode.js"
+export * from "./Textarea.js"

package/src/renderables/markdown-parser.ts

@@ -0,0 +1,79 @@
+import { Lexer, type MarkedToken } from "marked"
+
+export interface ParseState {
+  content: string
+  tokens: MarkedToken[]
+  stableTokenCount?: number
+}
+
+/**
+ * Incrementally parse markdown, reusing unchanged tokens from previous parse.
+ * Compares token.raw at each offset - matching tokens keep same object reference.
+ */
+export function parseMarkdownIncremental(
+  newContent: string,
+  prevState: ParseState | null,
+  trailingUnstable: number = 2,
+): ParseState {
+  if (!prevState || prevState.tokens.length === 0) {
+    try {
+      const tokens = Lexer.lex(newContent, { gfm: true }) as MarkedToken[]
+      return {
+        content: newContent,
+        tokens,
+        stableTokenCount: Math.max(0, tokens.length - trailingUnstable),
+      }
+    } catch {
+      return { content: newContent, tokens: [], stableTokenCount: 0 }
+    }
+  }
+
+  // Find how many tokens from start are unchanged
+  let offset = 0
+  let reuseCount = 0
+
+  for (const token of prevState.tokens) {
+    const tokenLength = token.raw.length
+    if (offset + tokenLength <= newContent.length && newContent.startsWith(token.raw, offset)) {
+      reuseCount++
+      offset += tokenLength
+    } else {
+      break
+    }
+  }
+
+  // Keep last N tokens unstable (e.g. "# Hello" might become "# Hello World")
+  reuseCount = Math.max(0, reuseCount - trailingUnstable)
+
+  offset = 0
+  for (let i = 0; i < reuseCount; i++) {
+    offset += prevState.tokens[i].raw.length
+  }
+
+  const stableTokens = prevState.tokens.slice(0, reuseCount)
+  const remainingContent = newContent.slice(offset)
+
+  if (!remainingContent) {
+    return {
+      content: newContent,
+      tokens: stableTokens,
+      stableTokenCount: stableTokens.length,
+    }
+  }
+
+  try {
+    const newTokens = Lexer.lex(remainingContent, { gfm: true }) as MarkedToken[]
+    return {
+      content: newContent,
+      tokens: [...stableTokens, ...newTokens],
+      stableTokenCount: trailingUnstable === 0 ? stableTokens.length + newTokens.length : stableTokens.length,
+    }
+  } catch {
+    try {
+      const fullTokens = Lexer.lex(newContent, { gfm: true }) as MarkedToken[]
+      return { content: newContent, tokens: fullTokens, stableTokenCount: 0 }
+    } catch {
+      return { content: newContent, tokens: [], stableTokenCount: 0 }
+    }
+  }
+}