@xincli/opentui-core 0.4.6

package/src/lib/clipboard.ts

@@ -0,0 +1,41 @@
+// OSC 52 clipboard support for terminal applications.
+// Delegates to native Zig implementation for ANSI sequence generation.
+
+import type { RendererHandle, RenderLib } from "../zig.js"
+
+export enum ClipboardTarget {
+  Clipboard = 0,
+  Primary = 1,
+  Select = 2,
+  Secondary = 3,
+}
+
+export class Clipboard {
+  private lib: RenderLib
+  private rendererPtr: RendererHandle
+
+  constructor(lib: RenderLib, rendererPtr: RendererHandle) {
+    this.lib = lib
+    this.rendererPtr = rendererPtr
+  }
+
+  public copyToClipboardOSC52(text: string, target: ClipboardTarget = ClipboardTarget.Clipboard): boolean {
+    if (!this.isOsc52Supported()) {
+      return false
+    }
+    const textUtf8 = this.lib.encoder.encode(text)
+    return this.lib.copyToClipboardOSC52(this.rendererPtr, target, textUtf8)
+  }
+
+  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 caps?.osc52_support !== "unsupported"
+  }
+}

package/src/lib/clock.ts

@@ -0,0 +1,35 @@
+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 {
+    if (!globalThis.performance || typeof globalThis.performance.now !== "function") {
+      throw new Error("SystemClock requires globalThis.performance.now()")
+    }
+
+    return globalThis.performance.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()
+}

package/src/lib/detect-links.test.ts

@@ -0,0 +1,98 @@
+import { test, expect, describe } from "bun:test"
+import { detectLinks } from "./detect-links.js"
+import type { TextChunk } from "../text-buffer.js"
+import type { SimpleHighlight } from "./tree-sitter/types.js"
+import { RGBA } from "./RGBA.js"
+
+function chunk(text: string): TextChunk {
+  return { __isChunk: true, text, fg: RGBA.fromInts(255, 255, 255, 255), attributes: 0 }
+}
+
+describe("detectLinks", () => {
+  test("should set link on markup.link.url chunks", () => {
+    const content = "[Click here](https://example.com)"
+    const highlights: SimpleHighlight[] = [
+      [0, 1, "markup.link"],
+      [1, 11, "markup.link.label"],
+      [11, 13, "markup.link"],
+      [13, 32, "markup.link.url"],
+      [32, 33, "markup.link"],
+    ]
+    const chunks = [chunk("["), chunk("Click here"), chunk("]("), chunk("https://example.com"), chunk(")")]
+
+    const result = detectLinks(chunks, { content, highlights })
+
+    expect(result.find((c) => c.text === "https://example.com")!.link).toEqual({ url: "https://example.com" })
+    expect(result.find((c) => c.text === "Click here")!.link).toEqual({ url: "https://example.com" })
+  })
+
+  test("should set link on string.special.url chunks", () => {
+    const content = "// see https://example.com for details"
+    const highlights: SimpleHighlight[] = [
+      [0, 38, "comment"],
+      [7, 26, "string.special.url"],
+    ]
+    const chunks = [chunk("// see "), chunk("https://example.com"), chunk(" for details")]
+
+    const result = detectLinks(chunks, { content, highlights })
+
+    expect(result.find((c) => c.text === "https://example.com")!.link).toEqual({ url: "https://example.com" })
+  })
+
+  test("should not set link on non-URL chunks", () => {
+    const content = "const x = 42"
+    const highlights: SimpleHighlight[] = [
+      [0, 5, "keyword"],
+      [6, 7, "variable"],
+      [10, 12, "number"],
+    ]
+    const chunks = [chunk("const"), chunk(" "), chunk("x"), chunk(" = "), chunk("42")]
+
+    const result = detectLinks(chunks, { content, highlights })
+
+    for (const c of result) {
+      expect(c.link).toBeUndefined()
+    }
+  })
+
+  test("should return chunks unchanged when no URL scopes exist", () => {
+    const content = "hello world"
+    const highlights: SimpleHighlight[] = [[0, 5, "keyword"]]
+    const chunks = [chunk("hello"), chunk(" world")]
+
+    const result = detectLinks(chunks, { content, highlights })
+
+    expect(result).toBe(chunks)
+  })
+
+  test("should detect links when chunks have concealed text", () => {
+    // Original content: [Click here](https://example.com)
+    // With concealment, `[` and `]` are concealed to empty strings,
+    // and `(` and `)` are concealed to empty strings.
+    // This means chunk text lengths don't match original byte offsets.
+    const content = "[Click here](https://example.com)"
+    const highlights: SimpleHighlight[] = [
+      [0, 1, "markup.link"], // [
+      [1, 11, "markup.link.label"], // Click here
+      [11, 13, "markup.link"], // ](
+      [13, 32, "markup.link.url"], // https://example.com
+      [32, 33, "markup.link"], // )
+    ]
+    // Simulate concealed chunks: `[` -> "", `](` -> " ", `)` -> ""
+    // The URL and label chunks remain unchanged.
+    const chunks = [
+      chunk(""), // concealed `[`
+      chunk("Click here"), // label, unchanged
+      chunk(" "), // concealed `](`
+      chunk("https://example.com"), // URL, unchanged
+      chunk(""), // concealed `)`
+    ]
+
+    const result = detectLinks(chunks, { content, highlights })
+
+    // The URL chunk should still get its link despite concealed offsets
+    expect(result.find((c) => c.text === "https://example.com")!.link).toEqual({ url: "https://example.com" })
+    // The label chunk should also get the link
+    expect(result.find((c) => c.text === "Click here")!.link).toEqual({ url: "https://example.com" })
+  })
+})

package/src/lib/detect-links.ts

@@ -0,0 +1,56 @@
+import type { TextChunk } from "../text-buffer.js"
+import type { SimpleHighlight } from "./tree-sitter/types.js"
+
+const URL_SCOPES = ["markup.link.url", "string.special.url"]
+
+export function detectLinks(
+  chunks: TextChunk[],
+  context: { content: string; highlights: SimpleHighlight[] },
+): TextChunk[] {
+  const content = context.content
+  const highlights = context.highlights
+
+  const ranges: Array<{ start: number; end: number; url: string }> = []
+
+  for (let i = 0; i < highlights.length; i++) {
+    const [start, end, group] = highlights[i]
+    if (!URL_SCOPES.includes(group)) continue
+
+    const url = content.slice(start, end)
+    ranges.push({ start, end, url })
+
+    for (let j = i - 1; j >= 0; j--) {
+      const [labelStart, labelEnd, prev] = highlights[j]
+      if (prev === "markup.link.label") {
+        ranges.push({ start: labelStart, end: labelEnd, url })
+        break
+      }
+      if (!prev.startsWith("markup.link")) break
+    }
+  }
+
+  if (ranges.length === 0) return chunks
+
+  // Use content.indexOf to find each chunk's position in the original content.
+  // This handles concealed text correctly because concealed chunks are either
+  // empty (length 0, skipped) or single-char replacements (length 1, skipped).
+  // Non-concealed chunks with length > 1 are exact substrings of content in order.
+  let contentPos = 0
+  for (const chunk of chunks) {
+    if (chunk.text.length <= 1) continue
+
+    const idx = content.indexOf(chunk.text, contentPos)
+    if (idx < 0) continue
+
+    for (const range of ranges) {
+      if (idx < range.end && idx + chunk.text.length > range.start) {
+        chunk.link = { url: range.url }
+        break
+      }
+    }
+
+    contentPos = idx + chunk.text.length
+  }
+
+  return chunks
+}