nastech-tui 0.0.1

package/packages/nastech-ink/src/ink/hit-test.ts

@@ -0,0 +1,224 @@
+import type { DOMElement } from './dom.js'
+import { ClickEvent } from './events/click-event.js'
+import type { EventHandlerProps } from './events/event-handlers.js'
+import { MouseEvent } from './events/mouse-event.js'
+import { nodeCache } from './node-cache.js'
+
+function hitTestAbsoluteDescendants(node: DOMElement, col: number, row: number): DOMElement | null {
+  for (let i = node.childNodes.length - 1; i >= 0; i--) {
+    const child = node.childNodes[i]!
+
+    if (child.nodeName === '#text') {
+      continue
+    }
+
+    if (!nodeCache.get(child)) {
+      continue
+    }
+
+    if (child.style.position === 'absolute') {
+      const hit = hitTest(child, col, row)
+
+      if (hit) {
+        return hit
+      }
+    }
+
+    const nestedHit = hitTestAbsoluteDescendants(child, col, row)
+
+    if (nestedHit) {
+      return nestedHit
+    }
+  }
+
+  return null
+}
+
+/**
+ * Find the deepest DOM element whose rendered rect contains (col, row).
+ *
+ * Uses the nodeCache populated by renderNodeToOutput — rects are in screen
+ * coordinates with all offsets (including scrollTop translation) already
+ * applied. Children are traversed in reverse so later siblings (painted on
+ * top) win. Nodes not in nodeCache (not rendered this frame, or lacking a
+ * yogaNode) are skipped along with their subtrees.
+ *
+ * Returns the hit node even if it has no onClick — dispatchClick walks up
+ * via parentNode to find handlers.
+ */
+export function hitTest(node: DOMElement, col: number, row: number): DOMElement | null {
+  const rect = nodeCache.get(node)
+
+  if (!rect) {
+    return null
+  }
+
+  const inside = col >= rect.x && col < rect.x + rect.width && row >= rect.y && row < rect.y + rect.height
+
+  if (!inside) {
+    return hitTestAbsoluteDescendants(node, col, row)
+  }
+
+  // Later siblings paint on top; reversed traversal returns topmost hit.
+  for (let i = node.childNodes.length - 1; i >= 0; i--) {
+    const child = node.childNodes[i]!
+
+    if (child.nodeName === '#text') {
+      continue
+    }
+
+    const hit = hitTest(child, col, row)
+
+    if (hit) {
+      return hit
+    }
+  }
+
+  return node
+}
+
+/**
+ * Hit-test the root at (col, row) and bubble a ClickEvent from the deepest
+ * containing node up through parentNode. Only nodes with an onClick handler
+ * fire. Stops when a handler calls stopImmediatePropagation(). Returns
+ * true if at least one onClick handler fired.
+ */
+export function dispatchClick(root: DOMElement, col: number, row: number, cellIsBlank = false): boolean {
+  let target: DOMElement | undefined = hitTest(root, col, row) ?? undefined
+
+  if (!target) {
+    return false
+  }
+
+  // Click-to-focus: find the closest focusable ancestor and focus it.
+  // root is always ink-root, which owns the FocusManager.
+  if (root.focusManager) {
+    let focusTarget: DOMElement | undefined = target
+
+    while (focusTarget) {
+      if (typeof focusTarget.attributes['tabIndex'] === 'number') {
+        root.focusManager.handleClickFocus(focusTarget)
+
+        break
+      }
+
+      focusTarget = focusTarget.parentNode
+    }
+  }
+
+  const event = new ClickEvent(col, row, cellIsBlank)
+  let handled = false
+
+  while (target) {
+    const handler = target._eventHandlers?.onClick as ((event: ClickEvent) => void) | undefined
+
+    if (handler) {
+      handled = true
+      const rect = nodeCache.get(target)
+
+      if (rect) {
+        event.localCol = col - rect.x
+        event.localRow = row - rect.y
+      }
+
+      handler(event)
+
+      if (event.didStopImmediatePropagation()) {
+        return true
+      }
+    }
+
+    target = target.parentNode
+  }
+
+  return handled
+}
+
+type MouseHandler = 'onMouseDown' | 'onMouseUp' | 'onMouseDrag'
+
+export function dispatchMouse(
+  root: DOMElement,
+  col: number,
+  row: number,
+  handlerName: MouseHandler,
+  button: number,
+  cellIsBlank = false,
+  target?: DOMElement
+): DOMElement | undefined {
+  let node: DOMElement | undefined = target ?? hitTest(root, col, row) ?? undefined
+
+  if (!node) {
+    return undefined
+  }
+
+  const event = new MouseEvent(col, row, cellIsBlank, button)
+  let handled: DOMElement | undefined
+
+  while (node) {
+    const handler = node._eventHandlers?.[handlerName] as ((event: MouseEvent) => void) | undefined
+
+    if (handler) {
+      handled ??= node
+      const rect = nodeCache.get(node)
+
+      if (rect) {
+        event.localCol = col - rect.x
+        event.localRow = row - rect.y
+      }
+
+      handler(event)
+
+      if (event.didStopImmediatePropagation()) {
+        return handled
+      }
+    }
+
+    node = node.parentNode
+  }
+
+  return handled
+}
+
+/**
+ * Fire onMouseEnter/onMouseLeave as the pointer moves. Like DOM
+ * mouseenter/mouseleave: does NOT bubble — moving between children does
+ * not re-fire on the parent. Walks up from the hit node collecting every
+ * ancestor with a hover handler; diffs against the previous hovered set;
+ * fires leave on the nodes exited, enter on the nodes entered.
+ *
+ * Mutates `hovered` in place so the caller (App instance) can hold it
+ * across calls. Clears the set when the hit is null (cursor moved into a
+ * non-rendered gap or off the root rect).
+ */
+export function dispatchHover(root: DOMElement, col: number, row: number, hovered: Set<DOMElement>): void {
+  const next = new Set<DOMElement>()
+  let node: DOMElement | undefined = hitTest(root, col, row) ?? undefined
+
+  while (node) {
+    const h = node._eventHandlers as EventHandlerProps | undefined
+
+    if (h?.onMouseEnter || h?.onMouseLeave) {
+      next.add(node)
+    }
+
+    node = node.parentNode
+  }
+
+  for (const old of hovered) {
+    if (!next.has(old)) {
+      hovered.delete(old)
+
+      // Skip handlers on detached nodes (removed between mouse events)
+      if (old.parentNode) {
+        ;(old._eventHandlers as EventHandlerProps | undefined)?.onMouseLeave?.()
+      }
+    }
+  }
+
+  for (const n of next) {
+    if (!hovered.has(n)) {
+      hovered.add(n)
+      ;(n._eventHandlers as EventHandlerProps | undefined)?.onMouseEnter?.()
+    }
+  }
+}

package/packages/nastech-ink/src/ink/hooks/use-animation-frame.ts

@@ -0,0 +1,62 @@
+import { useContext, useEffect, useState } from 'react'
+
+import { ClockContext } from '../components/ClockContext.js'
+import type { DOMElement } from '../dom.js'
+
+import { useTerminalViewport } from './use-terminal-viewport.js'
+
+/**
+ * Hook for synchronized animations that pause when offscreen.
+ *
+ * Returns a ref to attach to the animated element and the current animation time.
+ * All instances share the same clock, so animations stay in sync.
+ * The clock only runs when at least one keepAlive subscriber exists.
+ *
+ * Pass `null` to pause — unsubscribes from the clock so no ticks fire.
+ * Time freezes at the last value and resumes from the current clock time
+ * when a number is passed again.
+ *
+ * @param intervalMs - How often to update, or null to pause
+ * @returns [ref, time] - Ref to attach to element, elapsed time in ms
+ *
+ * @example
+ * function Spinner() {
+ *   const [ref, time] = useAnimationFrame(120)
+ *   const frame = Math.floor(time / 120) % FRAMES.length
+ *   return <Box ref={ref}>{FRAMES[frame]}</Box>
+ * }
+ *
+ * The clock automatically slows when the terminal is blurred,
+ * so consumers don't need to handle focus state.
+ */
+export function useAnimationFrame(
+  intervalMs: number | null = 16
+): [ref: (element: DOMElement | null) => void, time: number] {
+  const clock = useContext(ClockContext)
+  const [viewportRef, { isVisible }] = useTerminalViewport()
+  const [time, setTime] = useState(() => clock?.now() ?? 0)
+
+  const active = isVisible && intervalMs !== null
+
+  useEffect(() => {
+    if (!clock || !active) {
+      return
+    }
+
+    let lastUpdate = clock.now()
+
+    const onChange = (): void => {
+      const now = clock.now()
+
+      if (now - lastUpdate >= intervalMs!) {
+        lastUpdate = now
+        setTime(now)
+      }
+    }
+
+    // keepAlive: true — visible animations drive the clock
+    return clock.subscribe(onChange, true)
+  }, [clock, intervalMs, active])
+
+  return [viewportRef, time]
+}

package/packages/nastech-ink/src/ink/hooks/use-app.ts

@@ -0,0 +1,9 @@
+import { useContext } from 'react'
+
+import AppContext from '../components/AppContext.js'
+
+/**
+ * `useApp` is a React hook, which exposes a method to manually exit the app (unmount).
+ */
+const useApp = () => useContext(AppContext)
+export default useApp

package/packages/nastech-ink/src/ink/hooks/use-cursor-advance.ts

@@ -0,0 +1,33 @@
+import { useContext } from 'react'
+
+import CursorAdvanceContext, { type CursorAdvanceNotifier } from '../components/CursorAdvanceContext.js'
+
+/**
+ * Returns a function that notifies Ink the physical terminal cursor was
+ * advanced out-of-band (e.g. by a direct stdout.write from the
+ * TextInput fast-echo bypass).
+ *
+ * Calling the returned function updates two pieces of Ink state:
+ *
+ *   - `displayCursor` — the cached parked-cursor position log-update
+ *     uses as the relative-move basis for the next frame. Skipped on
+ *     alt-screen, where every frame's CSI H resets the cursor anyway.
+ *
+ *   - The active `cursorDeclaration` — the target the cursor parks at
+ *     after every frame. Bumped on BOTH main- and alt-screen, because
+ *     onRender's alt-screen park branch emits an absolute CUP from
+ *     this value and a stale declaration there is still visibly wrong.
+ *     The next React commit that publishes a fresh declaration
+ *     supersedes the bump.
+ *
+ * The caller is responsible for the stdout write itself; this hook
+ * only reports the resulting cursor delta. Pass `dx` and optional
+ * `dy` in terminal cells (positive = moved right/down, negative =
+ * moved left/up).
+ *
+ * If the host isn't an Ink render root (test stubs, non-Ink renderer)
+ * the returned callback is a safe no-op.
+ */
+export function useCursorAdvance(): CursorAdvanceNotifier {
+  return useContext(CursorAdvanceContext)
+}

package/packages/nastech-ink/src/ink/hooks/use-declared-cursor.ts

@@ -0,0 +1,75 @@
+import { useCallback, useContext, useLayoutEffect, useRef } from 'react'
+
+import CursorDeclarationContext from '../components/CursorDeclarationContext.js'
+import type { DOMElement } from '../dom.js'
+
+/**
+ * Declares where the terminal cursor should be parked after each frame.
+ *
+ * Terminal emulators render IME preedit text at the physical cursor
+ * position, and screen readers / screen magnifiers track the native
+ * cursor — so parking it at the text input's caret makes CJK input
+ * appear inline and lets accessibility tools follow the input.
+ *
+ * Returns a ref callback to attach to the Box that contains the input.
+ * The declared (line, column) is interpreted relative to that Box's
+ * nodeCache rect (populated by renderNodeToOutput).
+ *
+ * Timing: Both ref attach and useLayoutEffect fire in React's layout
+ * phase — after resetAfterCommit calls scheduleRender. scheduleRender
+ * defers onRender via queueMicrotask, so onRender runs AFTER layout
+ * effects commit and reads the fresh declaration on the first frame
+ * (no one-keystroke lag). Test env uses onImmediateRender (synchronous,
+ * no microtask), so tests compensate by calling ink.onRender()
+ * explicitly after render.
+ */
+export function useDeclaredCursor({
+  line,
+  column,
+  active
+}: {
+  line: number
+  column: number
+  active: boolean
+}): (element: DOMElement | null) => void {
+  const setCursorDeclaration = useContext(CursorDeclarationContext)
+  const nodeRef = useRef<DOMElement | null>(null)
+
+  const setNode = useCallback((node: DOMElement | null) => {
+    nodeRef.current = node
+  }, [])
+
+  // When active, set unconditionally. When inactive, clear conditionally
+  // (only if the currently-declared node is ours). The node-identity check
+  // handles two hazards:
+  //   1. A memo()ized active instance elsewhere (e.g. the search input in
+  //      a memo'd Footer) doesn't re-render this commit — an inactive
+  //      instance re-rendering here must not clobber it.
+  //   2. Sibling handoff (menu focus moving between list items) — when
+  //      focus moves opposite to sibling order, the newly-inactive item's
+  //      effect runs AFTER the newly-active item's set. Without the node
+  //      check it would clobber.
+  // No dep array: must re-declare every commit so the active instance
+  // re-claims the declaration after another instance's unmount-cleanup or
+  // sibling handoff nulls it.
+  useLayoutEffect(() => {
+    const node = nodeRef.current
+
+    if (active && node) {
+      setCursorDeclaration({ relativeX: column, relativeY: line, node })
+    } else {
+      setCursorDeclaration(null, node)
+    }
+  })
+
+  // Clear on unmount (conditionally — another instance may own by then).
+  // Separate effect with empty deps so cleanup only fires once — not on
+  // every line/column change, which would transiently null between commits.
+  useLayoutEffect(() => {
+    return () => {
+      setCursorDeclaration(null, nodeRef.current)
+    }
+  }, [setCursorDeclaration])
+
+  return setNode
+}

package/packages/nastech-ink/src/ink/hooks/use-external-process.ts

@@ -0,0 +1,27 @@
+import { useCallback } from 'react'
+
+import instances from '../instances.js'
+
+export type RunExternalProcess = () => Promise<void>
+
+export async function withInkSuspended(run: RunExternalProcess): Promise<void> {
+  const ink = instances.get(process.stdout)
+
+  if (!ink) {
+    await run()
+
+    return
+  }
+
+  ink.enterAlternateScreen()
+
+  try {
+    await run()
+  } finally {
+    ink.exitAlternateScreen()
+  }
+}
+
+export function useExternalProcess(): (run: RunExternalProcess) => Promise<void> {
+  return useCallback((run: RunExternalProcess) => withInkSuspended(run), [])
+}

package/packages/nastech-ink/src/ink/hooks/use-input.ts

@@ -0,0 +1,95 @@
+import { useEffect, useLayoutEffect } from 'react'
+import { useEventCallback } from 'usehooks-ts'
+
+import type { InputEvent, Key } from '../events/input-event.js'
+
+import useStdin from './use-stdin.js'
+
+type Handler = (input: string, key: Key, event: InputEvent) => void
+
+type Options = {
+  /**
+   * Enable or disable capturing of user input.
+   * Useful when there are multiple useInput hooks used at once to avoid handling the same input several times.
+   *
+   * @default true
+   */
+  isActive?: boolean
+}
+
+/**
+ * This hook is used for handling user input.
+ * It's a more convenient alternative to using `StdinContext` and listening to `data` events.
+ * The callback you pass to `useInput` is called for each character when user enters any input.
+ * However, if user pastes text and it's more than one character, the callback will be called only once and the whole string will be passed as `input`.
+ *
+ * ```
+ * import {useInput} from 'ink';
+ *
+ * const UserInput = () => {
+ *   useInput((input, key) => {
+ *     if (input === 'q') {
+ *       // Exit program
+ *     }
+ *
+ *     if (key.leftArrow) {
+ *       // Left arrow key pressed
+ *     }
+ *   });
+ *
+ *   return …
+ * };
+ * ```
+ */
+const useInput = (inputHandler: Handler, options: Options = {}) => {
+  const { setRawMode, exitOnCtrlC, inputEmitter } = useStdin()
+
+  // useLayoutEffect (not useEffect) so that raw mode is enabled synchronously
+  // during React's commit phase, before render() returns. With useEffect, raw
+  // mode setup is deferred to the next event loop tick via React's scheduler,
+  // leaving the terminal in cooked mode — keystrokes echo and the cursor is
+  // visible until the effect fires.
+  useLayoutEffect(() => {
+    if (options.isActive === false) {
+      return
+    }
+
+    setRawMode(true)
+
+    return () => {
+      setRawMode(false)
+    }
+  }, [options.isActive, setRawMode])
+
+  // Register the listener once on mount so its slot in the EventEmitter's
+  // listener array is stable. If isActive were in the effect's deps, the
+  // listener would re-append on false→true, moving it behind listeners
+  // that registered while it was inactive — breaking
+  // stopImmediatePropagation() ordering. useEventCallback keeps the
+  // reference stable while reading latest isActive/inputHandler from
+  // closure (it syncs via useLayoutEffect, so it's compiler-safe).
+  const handleData = useEventCallback((event: InputEvent) => {
+    if (options.isActive === false) {
+      return
+    }
+
+    const { input, key } = event
+
+    // If app is not supposed to exit on Ctrl+C, then let input listener handle it
+    // Note: discreteUpdates is called at the App level when emitting events,
+    // so all listeners are already within a high-priority update context.
+    if (!(input === 'c' && key.ctrl) || !exitOnCtrlC) {
+      inputHandler(input, key, event)
+    }
+  })
+
+  useEffect(() => {
+    inputEmitter?.on('input', handleData)
+
+    return () => {
+      inputEmitter?.removeListener('input', handleData)
+    }
+  }, [inputEmitter, handleData])
+}
+
+export default useInput

package/packages/nastech-ink/src/ink/hooks/use-interval.ts

@@ -0,0 +1,71 @@
+import { useContext, useEffect, useRef, useState } from 'react'
+
+import { ClockContext } from '../components/ClockContext.js'
+
+/**
+ * Returns the clock time, updating at the given interval.
+ * Subscribes as non-keepAlive — won't keep the clock alive on its own,
+ * but updates whenever a keepAlive subscriber (e.g. the spinner)
+ * is driving the clock.
+ *
+ * Use this to drive pure time-based computations (shimmer position,
+ * frame index) from the shared clock.
+ */
+export function useAnimationTimer(intervalMs: number): number {
+  const clock = useContext(ClockContext)
+  const [time, setTime] = useState(() => clock?.now() ?? 0)
+
+  useEffect(() => {
+    if (!clock) {
+      return
+    }
+
+    let lastUpdate = clock.now()
+
+    const onChange = (): void => {
+      const now = clock.now()
+
+      if (now - lastUpdate >= intervalMs) {
+        lastUpdate = now
+        setTime(now)
+      }
+    }
+
+    return clock.subscribe(onChange, false)
+  }, [clock, intervalMs])
+
+  return time
+}
+
+/**
+ * Interval hook backed by the shared Clock.
+ *
+ * Unlike `useInterval` from `usehooks-ts` (which creates its own setInterval),
+ * this piggybacks on the single shared clock so all timers consolidate into
+ * one wake-up. Pass `null` for intervalMs to pause.
+ */
+export function useInterval(callback: () => void, intervalMs: number | null): void {
+  const callbackRef = useRef(callback)
+  callbackRef.current = callback
+
+  const clock = useContext(ClockContext)
+
+  useEffect(() => {
+    if (!clock || intervalMs === null) {
+      return
+    }
+
+    let lastUpdate = clock.now()
+
+    const onChange = (): void => {
+      const now = clock.now()
+
+      if (now - lastUpdate >= intervalMs) {
+        lastUpdate = now
+        callbackRef.current()
+      }
+    }
+
+    return clock.subscribe(onChange, false)
+  }, [clock, intervalMs])
+}

package/packages/nastech-ink/src/ink/hooks/use-search-highlight.ts

@@ -0,0 +1,56 @@
+import { useContext, useMemo } from 'react'
+
+import StdinContext from '../components/StdinContext.js'
+import type { DOMElement } from '../dom.js'
+import instances from '../instances.js'
+import type { MatchPosition } from '../render-to-screen.js'
+
+/**
+ * Set the search highlight query on the Ink instance. Non-empty → all
+ * visible occurrences are inverted on the next frame (SGR 7, screen-buffer
+ * overlay, same damage machinery as selection). Empty → clears.
+ *
+ * This is a screen-space highlight — it matches the RENDERED text, not the
+ * source message text. Works for anything visible (bash output, file paths,
+ * error messages) regardless of where it came from in the message tree. A
+ * query that matched in source but got truncated/ellipsized in rendering
+ * won't highlight; that's acceptable — we highlight what you see.
+ */
+export function useSearchHighlight(): {
+  setQuery: (query: string) => void
+  /** Paint an existing DOM subtree (from the MAIN tree) to a fresh
+   *  Screen at its natural height, scan. Element-relative positions
+   *  (row 0 = element top). Zero context duplication — the element
+   *  IS the one built with all real providers. */
+  scanElement: (el: DOMElement) => MatchPosition[]
+  /** Position-based CURRENT highlight. Every frame writes yellow at
+   *  positions[currentIdx] + rowOffset. The scan-highlight (inverse on
+   *  all matches) still runs — this overlays on top. rowOffset tracks
+   *  scroll; positions stay stable (message-relative). null clears. */
+  setPositions: (
+    state: {
+      positions: MatchPosition[]
+      rowOffset: number
+      currentIdx: number
+    } | null
+  ) => void
+} {
+  useContext(StdinContext) // anchor to App subtree for hook rules
+  const ink = instances.get(process.stdout)
+
+  return useMemo(() => {
+    if (!ink) {
+      return {
+        setQuery: () => {},
+        scanElement: () => [],
+        setPositions: () => {}
+      }
+    }
+
+    return {
+      setQuery: (query: string) => ink.setSearchHighlight(query),
+      scanElement: (el: DOMElement) => ink.scanElementSubtree(el),
+      setPositions: state => ink.setSearchPositions(state)
+    }
+  }, [ink])
+}