@xincli/opentui-core 0.4.6

package/src/syntax-style.ts

@@ -0,0 +1,274 @@
+import { RGBA, parseColor, type ColorInput } from "./lib/RGBA.js"
+import { resolveRenderLib, type RenderLib, type SyntaxStyleHandle } from "./zig.js"
+import { createTextAttributes } from "./utils.js"
+
+export interface StyleDefinition {
+  fg?: RGBA
+  bg?: RGBA
+  bold?: boolean
+  italic?: boolean
+  underline?: boolean
+  dim?: boolean
+}
+
+export interface StyleDefinitionInput {
+  fg?: ColorInput
+  bg?: ColorInput
+  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: SyntaxStyleHandle
+  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: SyntaxStyleHandle) {
+    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, StyleDefinitionInput>): 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: StyleDefinitionInput): number {
+    this.guard()
+
+    const attributes = createTextAttributes({
+      bold: style.bold,
+      italic: style.italic,
+      underline: style.underline,
+      dim: style.dim,
+    })
+
+    const fg = style.fg ? parseColor(style.fg) : null
+    const bg = style.bg ? parseColor(style.bg) : null
+    const id = this.lib.syntaxStyleRegister(this.stylePtr, name, fg, bg, attributes)
+
+    this.nameCache.set(name, id)
+    this.styleDefs.set(name, { ...style, fg: fg ?? undefined, bg: bg ?? undefined })
+
+    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(): SyntaxStyleHandle {
+    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()
+
+    if (Object.prototype.hasOwnProperty.call(this.styleDefs, name)) {
+      return undefined
+    }
+
+    const style = this.styleDefs.get(name)
+    if (style) return style
+
+    if (name.includes(".")) {
+      const baseName = name.split(".")[0]
+      if (Object.prototype.hasOwnProperty.call(this.styleDefs, baseName)) {
+        return undefined
+      }
+      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,219 @@
+# Testing Utilities
+
+Test utilities for opentui terminal UI testing.
+
+## Test Renderer
+
+```ts
+import { createTestRenderer } from "@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)
+```
+
+## Terminal Capabilities
+
+```ts
+import { createTerminalCapabilities, setRendererCapabilities } from "@opentui/core/testing"
+
+const capabilities = createTerminalCapabilities({ kitty_keyboard: true })
+setRendererCapabilities(renderer, { notifications: true })
+```
+
+## Mock Keyboard Input
+
+```ts
+import { createMockKeys, KeyCodes } from "@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 "@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 "@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 "@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 "@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)
+})
+```