@fairyhunter13/opentui-core 0.1.89 → 0.1.90

package/src/lib/border.ts

@@ -0,0 +1,168 @@
+import type { ColorInput } from "./RGBA.js"
+
+export interface BorderCharacters {
+  topLeft: string
+  topRight: string
+  bottomLeft: string
+  bottomRight: string
+  horizontal: string
+  vertical: string
+  topT: string
+  bottomT: string
+  leftT: string
+  rightT: string
+  cross: string
+}
+
+export type BorderStyle = "single" | "double" | "rounded" | "heavy"
+export type BorderSides = "top" | "right" | "bottom" | "left"
+
+const VALID_BORDER_STYLES: readonly BorderStyle[] = ["single", "double", "rounded", "heavy"] as const
+
+export function isValidBorderStyle(value: unknown): value is BorderStyle {
+  return typeof value === "string" && VALID_BORDER_STYLES.includes(value as BorderStyle)
+}
+
+export function parseBorderStyle(value: unknown, fallback: BorderStyle = "single"): BorderStyle {
+  if (isValidBorderStyle(value)) {
+    return value
+  }
+
+  if (value !== undefined && value !== null) {
+    console.warn(
+      `Invalid borderStyle "${value}", falling back to "${fallback}". Valid values are: ${VALID_BORDER_STYLES.join(", ")}`,
+    )
+  }
+  return fallback
+}
+
+export const BorderChars: Record<BorderStyle, BorderCharacters> = {
+  single: {
+    topLeft: "┌",
+    topRight: "┐",
+    bottomLeft: "└",
+    bottomRight: "┘",
+    horizontal: "─",
+    vertical: "│",
+    topT: "┬",
+    bottomT: "┴",
+    leftT: "├",
+    rightT: "┤",
+    cross: "┼",
+  },
+  double: {
+    topLeft: "╔",
+    topRight: "╗",
+    bottomLeft: "╚",
+    bottomRight: "╝",
+    horizontal: "═",
+    vertical: "║",
+    topT: "╦",
+    bottomT: "╩",
+    leftT: "╠",
+    rightT: "╣",
+    cross: "╬",
+  },
+  rounded: {
+    topLeft: "╭",
+    topRight: "╮",
+    bottomLeft: "╰",
+    bottomRight: "╯",
+    horizontal: "─",
+    vertical: "│",
+    topT: "┬",
+    bottomT: "┴",
+    leftT: "├",
+    rightT: "┤",
+    cross: "┼",
+  },
+  heavy: {
+    topLeft: "┏",
+    topRight: "┓",
+    bottomLeft: "┗",
+    bottomRight: "┛",
+    horizontal: "━",
+    vertical: "┃",
+    topT: "┳",
+    bottomT: "┻",
+    leftT: "┣",
+    rightT: "┫",
+    cross: "╋",
+  },
+}
+
+export interface BorderConfig {
+  borderStyle: BorderStyle
+  border: boolean | BorderSides[]
+  borderColor?: ColorInput
+  customBorderChars?: BorderCharacters
+}
+
+export interface BoxDrawOptions {
+  x: number
+  y: number
+  width: number
+  height: number
+  borderStyle: BorderStyle
+  border: boolean | BorderSides[]
+  borderColor: ColorInput
+  customBorderChars?: BorderCharacters
+  backgroundColor: ColorInput
+  shouldFill?: boolean
+  title?: string
+  titleAlignment?: "left" | "center" | "right"
+}
+
+export interface BorderSidesConfig {
+  top: boolean
+  right: boolean
+  bottom: boolean
+  left: boolean
+}
+
+export function getBorderFromSides(sides: BorderSidesConfig): boolean | BorderSides[] {
+  const result: BorderSides[] = []
+  if (sides.top) result.push("top")
+  if (sides.right) result.push("right")
+  if (sides.bottom) result.push("bottom")
+  if (sides.left) result.push("left")
+  return result.length > 0 ? result : false
+}
+
+export function getBorderSides(border: boolean | BorderSides[]): BorderSidesConfig {
+  return border === true
+    ? { top: true, right: true, bottom: true, left: true }
+    : Array.isArray(border)
+      ? {
+          top: border.includes("top"),
+          right: border.includes("right"),
+          bottom: border.includes("bottom"),
+          left: border.includes("left"),
+        }
+      : { top: false, right: false, bottom: false, left: false }
+}
+
+// Convert BorderCharacters to Uint32Array for passing to Zig
+export function borderCharsToArray(chars: BorderCharacters): Uint32Array {
+  const array = new Uint32Array(11)
+  array[0] = chars.topLeft.codePointAt(0)!
+  array[1] = chars.topRight.codePointAt(0)!
+  array[2] = chars.bottomLeft.codePointAt(0)!
+  array[3] = chars.bottomRight.codePointAt(0)!
+  array[4] = chars.horizontal.codePointAt(0)!
+  array[5] = chars.vertical.codePointAt(0)!
+  array[6] = chars.topT.codePointAt(0)!
+  array[7] = chars.bottomT.codePointAt(0)!
+  array[8] = chars.leftT.codePointAt(0)!
+  array[9] = chars.rightT.codePointAt(0)!
+  array[10] = chars.cross.codePointAt(0)!
+  return array
+}
+
+// Pre-converted border character arrays for performance
+export const BorderCharArrays: Record<BorderStyle, Uint32Array> = {
+  single: borderCharsToArray(BorderChars.single),
+  double: borderCharsToArray(BorderChars.double),
+  rounded: borderCharsToArray(BorderChars.rounded),
+  heavy: borderCharsToArray(BorderChars.heavy),
+}

package/src/lib/bunfs.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, test } from "bun:test"
+import { isBunfsPath, getBunfsRootPath } from "./bunfs.js"
+
+describe("bunfs", () => {
+  test("isBunfsPath detects $bunfs paths", () => {
+    expect(isBunfsPath("/$bunfs/root/file.wasm")).toBe(true)
+  })
+
+  test("isBunfsPath detects Windows B: paths", () => {
+    expect(isBunfsPath("B:\\~BUN\\root\\file.wasm")).toBe(true)
+    expect(isBunfsPath("B:/~BUN/root/file.wasm")).toBe(true)
+  })
+
+  test("isBunfsPath ignores regular paths", () => {
+    expect(isBunfsPath("/usr/local/bin/file")).toBe(false)
+    expect(isBunfsPath("C:/Users/file.wasm")).toBe(false)
+  })
+
+  test("getBunfsRootPath", () => {
+    const root = getBunfsRootPath()
+    if (process.platform === "win32") {
+      expect(root).toBe("B:\\~BUN\\root")
+    } else {
+      expect(root).toBe("/$bunfs/root")
+    }
+  })
+})

package/src/lib/bunfs.ts

@@ -0,0 +1,18 @@
+import { basename, join } from "node:path"
+
+export function isBunfsPath(path: string): boolean {
+  // Removed ambiguous '//' check
+  return path.includes("$bunfs") || /^B:[\\/]~BUN/i.test(path)
+}
+
+export function getBunfsRootPath(): string {
+  return process.platform === "win32" ? "B:\\~BUN\\root" : "/$bunfs/root"
+}
+
+/**
+ * Normalizes a path to the embedded root.
+ * Flattens directory structure to ensure file exists at root.
+ */
+export function normalizeBunfsPath(fileName: string): string {
+  return join(getBunfsRootPath(), basename(fileName))
+}

package/src/lib/clipboard.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it, afterEach } from "bun:test"
+import { createTestRenderer, type TestRenderer } from "../testing/test-renderer.js"
+import { ClipboardTarget, encodeOsc52Payload } from "./clipboard.js"
+import type { RenderLib } from "../zig.js"
+
+describe("clipboard", () => {
+  let renderer: TestRenderer | null = null
+
+  const enableOsc52 = (testRenderer: TestRenderer) => {
+    const lib = (testRenderer as unknown as { lib: RenderLib }).lib
+    lib.processCapabilityResponse(testRenderer.rendererPtr, "\x1bP>|kitty(0.40.1)\x1b\\")
+  }
+
+  afterEach(() => {
+    renderer?.destroy()
+    renderer = null
+  })
+
+  it("encodes payload as base64", () => {
+    const payload = encodeOsc52Payload("hello")
+    const decoded = new TextDecoder().decode(payload)
+    expect(decoded).toBe(Buffer.from("hello").toString("base64"))
+  })
+
+  it("gates clipboard writes on OSC 52 support", async () => {
+    ;({ renderer } = await createTestRenderer({ remote: true }))
+
+    expect(renderer.isOsc52Supported()).toBe(false)
+    expect(renderer.copyToClipboardOSC52("test")).toBe(false)
+    expect(renderer.clearClipboardOSC52()).toBe(false)
+
+    enableOsc52(renderer)
+
+    expect(renderer.isOsc52Supported()).toBe(true)
+    expect(renderer.copyToClipboardOSC52("test")).toBe(true)
+    expect(renderer.copyToClipboardOSC52("test", ClipboardTarget.Primary)).toBe(true)
+    expect(renderer.copyToClipboardOSC52("test", ClipboardTarget.Secondary)).toBe(true)
+    expect(renderer.copyToClipboardOSC52("test", ClipboardTarget.Query)).toBe(true)
+    expect(renderer.clearClipboardOSC52()).toBe(true)
+  })
+})

package/src/lib/clipboard.ts

@@ -0,0 +1,47 @@
+// OSC 52 clipboard support for terminal applications.
+// Delegates to native Zig implementation for ANSI sequence generation.
+
+import type { Pointer } from "bun:ffi"
+import type { RenderLib } from "../zig.js"
+
+export enum ClipboardTarget {
+  Clipboard = 0,
+  Primary = 1,
+  Secondary = 2,
+  Query = 3,
+}
+
+export function encodeOsc52Payload(text: string, encoder: TextEncoder = new TextEncoder()): Uint8Array {
+  const base64 = Buffer.from(text).toString("base64")
+  return encoder.encode(base64)
+}
+
+export class Clipboard {
+  private lib: RenderLib
+  private rendererPtr: Pointer
+
+  constructor(lib: RenderLib, rendererPtr: Pointer) {
+    this.lib = lib
+    this.rendererPtr = rendererPtr
+  }
+
+  public copyToClipboardOSC52(text: string, target: ClipboardTarget = ClipboardTarget.Clipboard): boolean {
+    if (!this.isOsc52Supported()) {
+      return false
+    }
+    const payload = encodeOsc52Payload(text, this.lib.encoder)
+    return this.lib.copyToClipboardOSC52(this.rendererPtr, target, payload)
+  }
+
+  public clearClipboardOSC52(target: ClipboardTarget = ClipboardTarget.Clipboard): boolean {
+    if (!this.isOsc52Supported()) {
+      return false
+    }
+    return this.lib.clearClipboardOSC52(this.rendererPtr, target)
+  }
+
+  public isOsc52Supported(): boolean {
+    const caps = this.lib.getTerminalCapabilities(this.rendererPtr)
+    return Boolean(caps?.osc52)
+  }
+}

package/src/lib/clock.ts

@@ -0,0 +1,31 @@
+export type TimerHandle = ReturnType<typeof globalThis.setTimeout> | number
+
+export interface Clock {
+  now(): number
+  setTimeout(fn: () => void, delayMs: number): TimerHandle
+  clearTimeout(handle: TimerHandle): void
+  setInterval(fn: () => void, delayMs: number): TimerHandle
+  clearInterval(handle: TimerHandle): void
+}
+
+export class SystemClock implements Clock {
+  public now(): number {
+    return Date.now()
+  }
+
+  public setTimeout(fn: () => void, delayMs: number): TimerHandle {
+    return globalThis.setTimeout(fn, delayMs)
+  }
+
+  public clearTimeout(handle: TimerHandle): void {
+    globalThis.clearTimeout(handle as ReturnType<typeof globalThis.setTimeout>)
+  }
+
+  public setInterval(fn: () => void, delayMs: number): TimerHandle {
+    return globalThis.setInterval(fn, delayMs)
+  }
+
+  public clearInterval(handle: TimerHandle): void {
+    globalThis.clearInterval(handle as ReturnType<typeof globalThis.setTimeout>)
+  }
+}

package/src/lib/data-paths.test.ts

@@ -0,0 +1,133 @@
+import { test, expect } from "bun:test"
+import { DataPathsManager } from "./data-paths.js"
+
+test("DataPathsManager validates appName", () => {
+  const manager = new DataPathsManager()
+
+  // Valid names should work
+  expect(() => {
+    manager.appName = "myapp"
+  }).not.toThrow()
+
+  expect(() => {
+    manager.appName = "my-app"
+  }).not.toThrow()
+
+  expect(() => {
+    manager.appName = "my_app"
+  }).not.toThrow()
+
+  expect(() => {
+    manager.appName = "MyApp123"
+  }).not.toThrow()
+
+  // Invalid names should throw
+  expect(() => {
+    manager.appName = ""
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "   "
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "app/name"
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "app\\name"
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "app<name"
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "app>name"
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = 'app"name'
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "app|name"
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "app?name"
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "app*name"
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "CON"
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "PRN"
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "app."
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "app "
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = "."
+  }).toThrow("Invalid app name")
+
+  expect(() => {
+    manager.appName = ".."
+  }).toThrow("Invalid app name")
+})
+
+test("DataPathsManager constructor uses valid default appName", () => {
+  // Should not throw when creating a new instance
+  expect(() => {
+    new DataPathsManager()
+  }).not.toThrow()
+
+  const manager = new DataPathsManager()
+  expect(manager.appName).toBe("opentui")
+})
+
+test("DataPathsManager emits paths:changed event when appName changes", async () => {
+  const manager = new DataPathsManager()
+  let eventFired = false
+  let eventPaths: any = null
+
+  manager.on("paths:changed", (paths) => {
+    eventFired = true
+    eventPaths = paths
+  })
+
+  const originalAppName = manager.appName
+  manager.appName = "test-app-event"
+
+  expect(eventFired).toBe(true)
+  expect(eventPaths).toBeDefined()
+  expect(eventPaths.globalDataPath).toContain("test-app-event")
+  expect(eventPaths.globalConfigPath).toContain("test-app-event")
+  expect(eventPaths.globalConfigFile).toContain("test-app-event")
+  expect(eventPaths.localConfigFile).toContain("test-app-event")
+})
+
+test("DataPathsManager does not emit event when appName is set to same value", () => {
+  const manager = new DataPathsManager()
+  let eventFired = false
+
+  manager.on("paths:changed", () => {
+    eventFired = true
+  })
+
+  // Set to the same value
+  manager.appName = manager.appName
+
+  expect(eventFired).toBe(false)
+})

package/src/lib/data-paths.ts

@@ -0,0 +1,109 @@
+import os from "os"
+import path from "path"
+import { EventEmitter } from "events"
+import { singleton } from "./singleton.js"
+import { env, registerEnvVar } from "./env.js"
+import { isValidDirectoryName } from "./validate-dir-name.js"
+
+// Register environment variables for XDG directories
+registerEnvVar({
+  name: "XDG_CONFIG_HOME",
+  description: "Base directory for user-specific configuration files",
+  type: "string",
+  default: "",
+})
+
+registerEnvVar({
+  name: "XDG_DATA_HOME",
+  description: "Base directory for user-specific data files",
+  type: "string",
+  default: "",
+})
+
+export interface DataPaths {
+  globalConfigPath: string
+  globalConfigFile: string
+  localConfigFile: string
+  globalDataPath: string
+}
+
+export interface DataPathsEvents {
+  "paths:changed": [paths: DataPaths]
+}
+
+export class DataPathsManager extends EventEmitter<DataPathsEvents> {
+  private _appName: string
+  private _globalConfigPath?: string
+  private _globalConfigFile?: string
+  private _localConfigFile?: string
+  private _globalDataPath?: string
+  constructor() {
+    super()
+    this._appName = "opentui"
+  }
+
+  get appName(): string {
+    return this._appName
+  }
+
+  set appName(value: string) {
+    if (!isValidDirectoryName(value)) {
+      throw new Error(`Invalid app name "${value}": must be a valid directory name`)
+    }
+    if (this._appName !== value) {
+      this._appName = value
+      this._globalConfigPath = undefined
+      this._globalConfigFile = undefined
+      this._localConfigFile = undefined
+      this._globalDataPath = undefined
+      this.emit("paths:changed", this.toObject())
+    }
+  }
+
+  get globalConfigPath(): string {
+    if (this._globalConfigPath === undefined) {
+      const homeDir = os.homedir()
+      const xdgConfigHome = env.XDG_CONFIG_HOME
+      const baseConfigDir = xdgConfigHome || path.join(homeDir, ".config")
+      this._globalConfigPath = path.join(baseConfigDir, this._appName)
+    }
+    return this._globalConfigPath
+  }
+
+  get globalConfigFile(): string {
+    if (this._globalConfigFile === undefined) {
+      this._globalConfigFile = path.join(this.globalConfigPath, "init.ts")
+    }
+    return this._globalConfigFile
+  }
+
+  get localConfigFile(): string {
+    if (this._localConfigFile === undefined) {
+      this._localConfigFile = path.join(process.cwd(), `.${this._appName}.ts`)
+    }
+    return this._localConfigFile
+  }
+
+  get globalDataPath(): string {
+    if (this._globalDataPath === undefined) {
+      const homeDir = os.homedir()
+      const xdgDataHome = env.XDG_DATA_HOME
+      const baseDataDir = xdgDataHome || path.join(homeDir, ".local/share")
+      this._globalDataPath = path.join(baseDataDir, this._appName)
+    }
+    return this._globalDataPath
+  }
+
+  toObject(): DataPaths {
+    return {
+      globalConfigPath: this.globalConfigPath,
+      globalConfigFile: this.globalConfigFile,
+      localConfigFile: this.localConfigFile,
+      globalDataPath: this.globalDataPath,
+    }
+  }
+}
+
+export function getDataPaths(): DataPathsManager {
+  return singleton("data-paths-opentui", () => new DataPathsManager())
+}

package/src/lib/debounce.ts

@@ -0,0 +1,106 @@
+/**
+ * A module-level map to store timeout IDs for all debounced functions
+ * Structure: Map<scopeId, Map<debounceId, timerId>>
+ */
+const TIMERS_MAP = new Map<string | number, Map<string | number, ReturnType<typeof setTimeout>>>()
+
+/**
+ * Debounce controller that manages debounce instances for a specific scope
+ */
+export class DebounceController {
+  constructor(private scopeId: string | number) {
+    // Initialize the scope map if it doesn't exist
+    if (!TIMERS_MAP.has(this.scopeId)) {
+      TIMERS_MAP.set(this.scopeId, new Map())
+    }
+  }
+
+  /**
+   * Debounces the provided function with the given ID
+   *
+   * @param id Unique identifier within this scope
+   * @param ms Milliseconds to wait before executing
+   * @param fn Function to execute
+   */
+  debounce<R>(id: string | number, ms: number, fn: () => Promise<R>): Promise<R> {
+    const scopeMap = TIMERS_MAP.get(this.scopeId)!
+
+    return new Promise((resolve, reject) => {
+      // Clear any existing timeout for this ID
+      if (scopeMap.has(id)) {
+        clearTimeout(scopeMap.get(id))
+      }
+
+      // Set a new timeout
+      const timerId = setTimeout(() => {
+        try {
+          resolve(fn())
+        } catch (error) {
+          reject(error)
+        }
+        scopeMap.delete(id)
+      }, ms)
+
+      // Store the new timeout ID
+      scopeMap.set(id, timerId)
+    })
+  }
+
+  /**
+   * Clear a specific debounce timer in this scope
+   *
+   * @param id The debounce ID to clear
+   */
+  clearDebounce(id: string | number): void {
+    const scopeMap = TIMERS_MAP.get(this.scopeId)
+    if (scopeMap && scopeMap.has(id)) {
+      clearTimeout(scopeMap.get(id))
+      scopeMap.delete(id)
+    }
+  }
+
+  /**
+   * Clear all debounce timers in this scope
+   */
+  clear(): void {
+    const scopeMap = TIMERS_MAP.get(this.scopeId)
+    if (scopeMap) {
+      scopeMap.forEach((timerId) => clearTimeout(timerId))
+      scopeMap.clear()
+    }
+  }
+}
+
+/**
+ * Creates a new debounce controller for a specific scope
+ *
+ * @param scopeId Unique identifier for this debounce scope
+ * @returns A DebounceController for the specified scope
+ */
+export function createDebounce(scopeId: string | number): DebounceController {
+  return new DebounceController(scopeId)
+}
+
+/**
+ * Clears all debounce timers for a specific scope
+ *
+ * @param scopeId The scope identifier
+ */
+export function clearDebounceScope(scopeId: string | number): void {
+  const scopeMap = TIMERS_MAP.get(scopeId)
+  if (scopeMap) {
+    scopeMap.forEach((timerId) => clearTimeout(timerId))
+    scopeMap.clear()
+  }
+}
+
+/**
+ * Clears all active debounce timers across all scopes
+ */
+export function clearAllDebounces(): void {
+  TIMERS_MAP.forEach((scopeMap) => {
+    scopeMap.forEach((timerId) => clearTimeout(timerId))
+    scopeMap.clear()
+  })
+  TIMERS_MAP.clear()
+}