@fairyhunter13/opentui-core 0.1.113 → 0.1.114

package/src/syntax-style.ts

@@ -0,0 +1,257 @@
+import { RGBA, parseColor, type ColorInput } from "./lib/RGBA.js"
+import { resolveRenderLib, type RenderLib } from "./zig.js"
+import { type Pointer } from "bun:ffi"
+import { createTextAttributes } from "./utils.js"
+
+export interface StyleDefinition {
+  fg?: RGBA
+  bg?: RGBA
+  bold?: boolean
+  italic?: boolean
+  underline?: boolean
+  dim?: boolean
+}
+
+export interface MergedStyle {
+  fg?: RGBA
+  bg?: RGBA
+  attributes: number
+}
+
+export interface ThemeTokenStyle {
+  scope: string[]
+  style: {
+    foreground?: ColorInput
+    background?: ColorInput
+    bold?: boolean
+    italic?: boolean
+    underline?: boolean
+    dim?: boolean
+  }
+}
+
+export function convertThemeToStyles(theme: ThemeTokenStyle[]): Record<string, StyleDefinition> {
+  const flatStyles: Record<string, StyleDefinition> = {}
+
+  for (const tokenStyle of theme) {
+    const styleDefinition: StyleDefinition = {}
+
+    if (tokenStyle.style.foreground) {
+      styleDefinition.fg = parseColor(tokenStyle.style.foreground)
+    }
+    if (tokenStyle.style.background) {
+      styleDefinition.bg = parseColor(tokenStyle.style.background)
+    }
+
+    if (tokenStyle.style.bold !== undefined) {
+      styleDefinition.bold = tokenStyle.style.bold
+    }
+    if (tokenStyle.style.italic !== undefined) {
+      styleDefinition.italic = tokenStyle.style.italic
+    }
+    if (tokenStyle.style.underline !== undefined) {
+      styleDefinition.underline = tokenStyle.style.underline
+    }
+    if (tokenStyle.style.dim !== undefined) {
+      styleDefinition.dim = tokenStyle.style.dim
+    }
+
+    // Apply the same style to all scopes
+    for (const scope of tokenStyle.scope) {
+      flatStyles[scope] = styleDefinition
+    }
+  }
+
+  return flatStyles
+}
+
+export class SyntaxStyle {
+  private lib: RenderLib
+  private stylePtr: Pointer
+  private _destroyed: boolean = false
+  private nameCache: Map<string, number> = new Map()
+  private styleDefs: Map<string, StyleDefinition> = new Map()
+  private mergedCache: Map<string, MergedStyle> = new Map()
+
+  constructor(lib: RenderLib, ptr: Pointer) {
+    this.lib = lib
+    this.stylePtr = ptr
+  }
+
+  static create(): SyntaxStyle {
+    const lib = resolveRenderLib()
+    const ptr = lib.createSyntaxStyle()
+    return new SyntaxStyle(lib, ptr)
+  }
+
+  static fromTheme(theme: ThemeTokenStyle[]): SyntaxStyle {
+    const style = SyntaxStyle.create()
+    const flatStyles = convertThemeToStyles(theme)
+
+    for (const [name, styleDef] of Object.entries(flatStyles)) {
+      style.registerStyle(name, styleDef)
+    }
+
+    return style
+  }
+
+  static fromStyles(styles: Record<string, StyleDefinition>): SyntaxStyle {
+    const style = SyntaxStyle.create()
+
+    for (const [name, styleDef] of Object.entries(styles)) {
+      style.registerStyle(name, styleDef)
+    }
+
+    return style
+  }
+
+  private guard(): void {
+    if (this._destroyed) throw new Error("NativeSyntaxStyle is destroyed")
+  }
+
+  public registerStyle(name: string, style: StyleDefinition): number {
+    this.guard()
+
+    const attributes = createTextAttributes({
+      bold: style.bold,
+      italic: style.italic,
+      underline: style.underline,
+      dim: style.dim,
+    })
+
+    const id = this.lib.syntaxStyleRegister(this.stylePtr, name, style.fg || null, style.bg || null, attributes)
+
+    this.nameCache.set(name, id)
+    this.styleDefs.set(name, style)
+
+    return id
+  }
+
+  public resolveStyleId(name: string): number | null {
+    this.guard()
+
+    // Check cache first
+    const cached = this.nameCache.get(name)
+    if (cached !== undefined) return cached
+
+    const id = this.lib.syntaxStyleResolveByName(this.stylePtr, name)
+
+    if (id !== null) {
+      this.nameCache.set(name, id)
+    }
+
+    return id
+  }
+
+  public getStyleId(name: string): number | null {
+    this.guard()
+
+    const id = this.resolveStyleId(name)
+    if (id !== null) return id
+
+    // Try base name if it's a scoped style
+    if (name.includes(".")) {
+      const baseName = name.split(".")[0]
+      return this.resolveStyleId(baseName)
+    }
+
+    return null
+  }
+
+  public get ptr(): Pointer {
+    this.guard()
+    return this.stylePtr
+  }
+
+  public getStyleCount(): number {
+    this.guard()
+    return this.lib.syntaxStyleGetStyleCount(this.stylePtr)
+  }
+
+  public clearNameCache(): void {
+    this.nameCache.clear()
+  }
+
+  public getStyle(name: string): StyleDefinition | undefined {
+    this.guard()
+
+    const style = this.styleDefs.get(name)
+    if (style) return style
+
+    if (name.includes(".")) {
+      const baseName = name.split(".")[0]
+      return this.styleDefs.get(baseName)
+    }
+
+    return undefined
+  }
+
+  public mergeStyles(...styleNames: string[]): MergedStyle {
+    this.guard()
+
+    const cacheKey = styleNames.join(":")
+    const cached = this.mergedCache.get(cacheKey)
+    if (cached) return cached
+
+    const styleDefinition: StyleDefinition = {}
+
+    for (const name of styleNames) {
+      const style = this.getStyle(name)
+
+      if (!style) continue
+
+      if (style.fg) styleDefinition.fg = style.fg
+      if (style.bg) styleDefinition.bg = style.bg
+      if (style.bold !== undefined) styleDefinition.bold = style.bold
+      if (style.italic !== undefined) styleDefinition.italic = style.italic
+      if (style.underline !== undefined) styleDefinition.underline = style.underline
+      if (style.dim !== undefined) styleDefinition.dim = style.dim
+    }
+
+    const attributes = createTextAttributes({
+      bold: styleDefinition.bold,
+      italic: styleDefinition.italic,
+      underline: styleDefinition.underline,
+      dim: styleDefinition.dim,
+    })
+
+    const merged: MergedStyle = {
+      fg: styleDefinition.fg,
+      bg: styleDefinition.bg,
+      attributes,
+    }
+
+    this.mergedCache.set(cacheKey, merged)
+
+    return merged
+  }
+
+  public clearCache(): void {
+    this.guard()
+    this.mergedCache.clear()
+  }
+
+  public getCacheSize(): number {
+    this.guard()
+    return this.mergedCache.size
+  }
+
+  public getAllStyles(): Map<string, StyleDefinition> {
+    this.guard()
+    return new Map(this.styleDefs)
+  }
+
+  public getRegisteredNames(): string[] {
+    this.guard()
+    return Array.from(this.styleDefs.keys())
+  }
+
+  public destroy(): void {
+    if (this._destroyed) return
+    this._destroyed = true
+    this.nameCache.clear()
+    this.styleDefs.clear()
+    this.mergedCache.clear()
+    this.lib.destroySyntaxStyle(this.stylePtr)
+  }
+}

package/src/testing/README.md

@@ -0,0 +1,210 @@
+# Testing Utilities
+
+Test utilities for opentui terminal UI testing.
+
+## Test Renderer
+
+```ts
+import { createTestRenderer } from "@fairyhunter13/opentui-core/testing"
+
+const { renderer, mockInput, mockMouse, renderOnce, captureCharFrame, resize } = await createTestRenderer({
+  width: 80,
+  height: 24,
+})
+
+// Render once and capture output
+await renderOnce()
+const output = captureCharFrame()
+
+// Resize terminal
+resize(100, 30)
+```
+
+## Mock Keyboard Input
+
+```ts
+import { createMockKeys, KeyCodes } from "@fairyhunter13/opentui-core/testing"
+
+const mockInput = createMockKeys(renderer)
+
+// Type text
+mockInput.typeText("hello world")
+await mockInput.typeText("hello", 10) // 10ms delay between keys
+
+// Press single keys
+mockInput.pressKey("a")
+mockInput.pressKey(KeyCodes.ENTER)
+
+// Press keys with modifiers
+mockInput.pressKey("a", { ctrl: true })
+mockInput.pressKey("f", { meta: true })
+mockInput.pressKey("z", { ctrl: true, shift: true })
+mockInput.pressKey(KeyCodes.ARROW_LEFT, { meta: true })
+
+// Press multiple keys
+mockInput.pressKeys(["h", "e", "l", "l", "o"])
+await mockInput.pressKeys(["a", "b"], 10) // with delay
+
+// Convenience methods
+mockInput.pressEnter()
+mockInput.pressEnter({ meta: true })
+mockInput.pressEscape()
+mockInput.pressTab()
+mockInput.pressBackspace()
+mockInput.pressArrow("up" | "down" | "left" | "right")
+mockInput.pressArrow("left", { meta: true })
+mockInput.pressCtrlC()
+mockInput.pasteBracketedText("paste content")
+```
+
+### KeyCodes
+
+Special keycodes available: `RETURN`, `LINEFEED`, `TAB`, `BACKSPACE`, `DELETE`, `HOME`, `END`, `ESCAPE`, `ARROW_UP`, `ARROW_DOWN`, `ARROW_LEFT`, `ARROW_RIGHT`, `F1`-`F12`
+
+### Modifiers
+
+All `pressKey()`, `pressEnter()`, `pressEscape()`, `pressTab()`, `pressBackspace()`, and `pressArrow()` methods support an optional modifiers object:
+
+```ts
+{ ctrl?: boolean; shift?: boolean; meta?: boolean }
+```
+
+## Mock Mouse Input
+
+```ts
+import { createMockMouse, MouseButtons } from "@fairyhunter13/opentui-core/testing"
+
+const mockMouse = createMockMouse(renderer)
+
+// Click
+await mockMouse.click(x, y)
+await mockMouse.click(x, y, MouseButtons.RIGHT)
+await mockMouse.click(x, y, MouseButtons.LEFT, {
+  modifiers: { ctrl: true, shift: true, alt: true },
+  delayMs: 10,
+})
+
+// Double click
+await mockMouse.doubleClick(x, y)
+
+// Press and release
+await mockMouse.pressDown(x, y, MouseButtons.MIDDLE)
+await mockMouse.release(x, y, MouseButtons.MIDDLE)
+
+// Move
+await mockMouse.moveTo(x, y)
+await mockMouse.moveTo(x, y, { modifiers: { shift: true } })
+
+// Drag
+await mockMouse.drag(startX, startY, endX, endY)
+await mockMouse.drag(startX, startY, endX, endY, MouseButtons.RIGHT, {
+  modifiers: { alt: true },
+})
+
+// Scroll
+await mockMouse.scroll(x, y, "up" | "down" | "left" | "right")
+await mockMouse.scroll(x, y, "up", { modifiers: { shift: true } })
+
+// State
+const pos = mockMouse.getCurrentPosition() // { x, y }
+const buttons = mockMouse.getPressedButtons() // MouseButton[]
+```
+
+### MouseButtons
+
+`LEFT` (0), `MIDDLE` (1), `RIGHT` (2)
+
+`WHEEL_UP` (64), `WHEEL_DOWN` (65), `WHEEL_LEFT` (66), `WHEEL_RIGHT` (67)
+
+## Spy
+
+Simple function spy for testing callbacks.
+
+```ts
+import { createSpy } from "@fairyhunter13/opentui-core/testing"
+
+const spy = createSpy()
+
+// Use as callback
+someFunction(spy)
+
+// Assertions
+spy.callCount() // number
+spy.calledWith(arg1, arg2) // boolean
+spy.calls // any[][]
+spy.reset()
+```
+
+## Test Recorder
+
+Record frames during rendering for testing or analysis.
+
+```ts
+import { TestRecorder } from "@fairyhunter13/opentui-core/testing"
+
+const { renderer, renderOnce } = await createTestRenderer({ width: 80, height: 24 })
+const recorder = new TestRecorder(renderer)
+
+// Start recording
+recorder.rec()
+
+// Add content and trigger renders
+const text = new TextRenderable(renderer, { content: "Hello" })
+renderer.root.add(text)
+await Bun.sleep(1) // Wait for automatic render from add()
+
+text.content = "World"
+await Bun.sleep(1) // Wait for automatic render from content change
+
+// Stop recording
+recorder.stop()
+
+// Access recorded frames
+const frames = recorder.recordedFrames
+console.log(`Recorded ${frames.length} frames`)
+
+frames.forEach((frame) => {
+  console.log(`Frame ${frame.frameNumber} at ${frame.timestamp}ms:`)
+  console.log(frame.frame)
+})
+
+// Clear and start new recording
+recorder.clear()
+recorder.rec()
+```
+
+### TestRecorder API
+
+- `rec()` - Start recording frames
+- `stop()` - Stop recording frames
+- `clear()` - Clear all recorded frames
+- `isRecording` - Check if currently recording
+- `recordedFrames` - Get array of recorded frames (returns a copy)
+
+### RecordedFrame
+
+Each frame contains:
+
+- `frame: string` - The captured frame content
+- `timestamp: number` - Time in milliseconds since recording started
+- `frameNumber: number` - Sequential frame number (0-indexed)
+
+## Example
+
+```ts
+import { test, expect } from "bun:test"
+import { createTestRenderer } from "@fairyhunter13/opentui-core/testing"
+
+test("button click", async () => {
+  const { renderer, mockMouse, renderOnce, captureCharFrame } = await createTestRenderer({ width: 80, height: 24 })
+
+  const clicked = createSpy()
+  const button = new Button("btn", { text: "Click me", onClick: clicked })
+
+  renderer.add(button)
+  await renderOnce()
+
+  await mockMouse.click(10, 5)
+  expect(clicked.callCount()).toBe(1)
+})
+```

package/src/testing/capture-spans.test.ts

@@ -0,0 +1,194 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test"
+import { createTestRenderer, type TestRenderer } from "./test-renderer.js"
+import { TextRenderable } from "../renderables/Text.js"
+import { BoxRenderable } from "../renderables/Box.js"
+import { TextAttributes, type CapturedFrame } from "../types.js"
+import { RGBA } from "../lib/index.js"
+
+describe("captureSpans", () => {
+  let renderer: TestRenderer
+  let renderOnce: () => Promise<void>
+  let captureSpans: () => CapturedFrame
+
+  beforeEach(async () => {
+    const setup = await createTestRenderer({ width: 40, height: 10 })
+    renderer = setup.renderer
+    renderOnce = setup.renderOnce
+    captureSpans = setup.captureSpans
+  })
+
+  afterEach(() => {
+    renderer.destroy()
+  })
+
+  test("returns correct dimensions and line count", async () => {
+    await renderOnce()
+    const data = captureSpans()
+
+    expect(data.cols).toBe(40)
+    expect(data.rows).toBe(10)
+    expect(data.lines.length).toBe(10)
+  })
+
+  test("captures text content in spans", async () => {
+    const text = new TextRenderable(renderer, { content: "Hello World" })
+    renderer.root.add(text)
+    await renderOnce()
+
+    const data = captureSpans()
+    const firstLine = data.lines[0]
+    const textContent = firstLine.spans.map((s) => s.text).join("")
+
+    expect(textContent).toContain("Hello World")
+  })
+
+  test("groups consecutive cells with same styling into single span", async () => {
+    const text = new TextRenderable(renderer, { content: "AAAA" })
+    renderer.root.add(text)
+    await renderOnce()
+
+    const data = captureSpans()
+    const firstLine = data.lines[0]
+    const aaaSpan = firstLine.spans.find((s) => s.text.includes("AAAA"))
+
+    expect(aaaSpan).toBeDefined()
+    expect(aaaSpan!.width).toBeGreaterThanOrEqual(4)
+  })
+
+  test("captures foreground color", async () => {
+    const text = new TextRenderable(renderer, {
+      content: "Red Text",
+      fg: RGBA.fromHex("#ff0000"),
+    })
+    renderer.root.add(text)
+    await renderOnce()
+
+    const data = captureSpans()
+    const firstLine = data.lines[0]
+    const redSpan = firstLine.spans.find((s) => s.text.includes("Red"))
+
+    expect(redSpan).toBeDefined()
+    expect(redSpan!.fg.r).toBe(1)
+    expect(redSpan!.fg.g).toBe(0)
+    expect(redSpan!.fg.b).toBe(0)
+  })
+
+  test("captures background color", async () => {
+    const box = new BoxRenderable(renderer, {
+      width: 10,
+      height: 3,
+      backgroundColor: RGBA.fromHex("#00ff00"),
+    })
+    renderer.root.add(box)
+    await renderOnce()
+
+    const data = captureSpans()
+    const secondLine = data.lines[1]
+    const greenSpan = secondLine.spans.find((s) => s.bg.g === 1 && s.bg.r === 0 && s.bg.b === 0)
+
+    expect(greenSpan).toBeDefined()
+  })
+
+  test("returns alpha 0 for transparent colors", async () => {
+    await renderOnce()
+
+    const data = captureSpans()
+    const firstLine = data.lines[0]
+    const transparentSpan = firstLine.spans.find((s) => s.bg.a === 0)
+
+    expect(transparentSpan).toBeDefined()
+  })
+
+  test("captures text attributes", async () => {
+    const text = new TextRenderable(renderer, {
+      content: "Styled",
+      attributes: TextAttributes.BOLD | TextAttributes.ITALIC | TextAttributes.UNDERLINE | TextAttributes.DIM,
+    })
+    renderer.root.add(text)
+    await renderOnce()
+
+    const data = captureSpans()
+    const firstLine = data.lines[0]
+    const styledSpan = firstLine.spans.find((s) => s.text.includes("Styled"))
+
+    expect(styledSpan).toBeDefined()
+    expect(styledSpan!.attributes & TextAttributes.BOLD).toBeTruthy()
+    expect(styledSpan!.attributes & TextAttributes.ITALIC).toBeTruthy()
+    expect(styledSpan!.attributes & TextAttributes.UNDERLINE).toBeTruthy()
+    expect(styledSpan!.attributes & TextAttributes.DIM).toBeTruthy()
+  })
+
+  test("includes cursor position", async () => {
+    await renderOnce()
+    const data = captureSpans()
+
+    expect(data.cursor).toEqual([expect.any(Number), expect.any(Number)])
+  })
+
+  test("splits spans when styling changes", async () => {
+    const text1 = new TextRenderable(renderer, {
+      content: "AAA",
+      fg: RGBA.fromHex("#ff0000"),
+    })
+    const text2 = new TextRenderable(renderer, {
+      content: "BBB",
+      fg: RGBA.fromHex("#00ff00"),
+    })
+    renderer.root.add(text1)
+    renderer.root.add(text2)
+    await renderOnce()
+
+    const data = captureSpans()
+    const allSpans = data.lines.flatMap((l) => l.spans)
+
+    expect(allSpans.some((s) => s.fg.r === 1 && s.fg.g === 0)).toBe(true)
+    expect(allSpans.some((s) => s.fg.g === 1 && s.fg.r === 0)).toBe(true)
+  })
+
+  test("handles box-drawing characters without crashing", async () => {
+    const text = new TextRenderable(renderer, {
+      content: "├── folder",
+    })
+    renderer.root.add(text)
+    await renderOnce()
+
+    const data = captureSpans()
+    const firstLine = data.lines[0]
+    const textContent = firstLine.spans.map((s) => s.text).join("")
+
+    expect(textContent).toContain("├── folder")
+  })
+
+  test("handles box borders without crashing", async () => {
+    const box = new BoxRenderable(renderer, {
+      width: 10,
+      height: 4,
+      border: true,
+      borderStyle: "single",
+      borderColor: RGBA.fromHex("#ffffff"),
+    })
+    renderer.root.add(box)
+    await renderOnce()
+
+    const data = captureSpans()
+    expect(data.lines.length).toBe(10)
+
+    const firstLine = data.lines[0]
+    const textContent = firstLine.spans.map((s) => s.text).join("")
+    expect(textContent.includes("┌") || textContent.includes("─")).toBe(true)
+  })
+
+  test("handles multi-width characters correctly", async () => {
+    const text = new TextRenderable(renderer, {
+      content: "A🌟B",
+    })
+    renderer.root.add(text)
+    await renderOnce()
+
+    const data = captureSpans()
+    const firstLine = data.lines[0]
+    const textContent = firstLine.spans.map((s) => s.text).join("")
+
+    expect(textContent).toContain("A🌟B")
+  })
+})