@xp266/dshtui 0.1.0

package/src/ui/input/use-composer.ts

@@ -0,0 +1,495 @@
+import { useInput, usePaste } from 'ink'
+import { isKeyConsumed } from '../key-arbiter.ts'
+import { useEffect, useRef, useState } from 'react'
+import { isMouseResidue } from '../../terminal/mouse.ts'
+import { colToCharIndex } from '../../core/text.ts'
+import { moveCaretLine } from '../../core/composer-layout.ts'
+import { editBackspace, editCursorLeft, editCursorRight, editCursorWordLeft, editCursorWordRight, editDelete, editDeleteWordLeft, editDeleteWordRight, editInsert } from '../../core/edit.ts'
+import type { EditState } from '../../core/edit.ts'
+import { buildPasteFields, expandComposerValue, insertClipboardImage, insertFieldSpec, reconcileComposerFields } from './composer-fields.ts'
+import type { ComposerFieldMap, ComposerSubmission } from './composer-fields.ts'
+import { sanitizePastedText } from '../../core/paste.ts'
+import { readClipboardImage, readClipboardImageUris, readClipboardText } from '../../terminal/clipboard.ts'
+import { claimPaste } from './composer-paste.ts'
+import { handleComposerKeyBindings } from './composer-keys.ts'
+import { setComposerInserter } from './composer-bus.ts'
+import { COMMANDS, filterHintEntries, literalHintArgs } from './commands.ts'
+import type { CommandHintItem } from './commands.ts'
+
+export interface ComposerState {
+  value: string
+  cursor: number
+  hintOpen: boolean
+  commandIndex: number
+  api: ComposerApi
+}
+
+export interface ComposerApi {
+  moveLineBy(delta: -1 | 1): void
+  placeCursor(charIndex: number): void
+  selectHint(absoluteIndex: number): void
+  confirmHint(): void
+  hintMove(delta: -1 | 1): void
+  hintClickAt(absoluteIndex: number): void
+  hintPick(absoluteIndex: number): void
+}
+
+function opensHint(text: string): boolean {
+  return text.startsWith('/') && !/\s/.test(text)
+}
+
+const UNDO_LIMIT = 200
+
+export function useComposer(
+  onSend: (submission: ComposerSubmission) => void,
+  interactive: boolean,
+  contentWidth: number,
+  onCycleMode?: () => void,
+  entries?: readonly CommandHintItem[],
+  listCommandArgs?: (name: string) => Promise<string[]>,
+): ComposerState {
+  const [value, setValue] = useState('')
+  const [cursor, setCursor] = useState(0)
+  const [hintOpen, setHintOpen] = useState(false)
+  const [commandIndex, setCommandIndex] = useState(0)
+  const valueRef = useRef('')
+  const cursorRef = useRef(0)
+  const hintOpenRef = useRef(false)
+  const commandIndexRef = useRef(0)
+  const widthRef = useRef(contentWidth)
+  const entriesRef = useRef<readonly CommandHintItem[] | undefined>(entries)
+  const listCommandArgsRef = useRef(listCommandArgs)
+  const interactiveRef = useRef(interactive)
+  const fieldsRef = useRef<ComposerFieldMap>(new Map())
+  widthRef.current = contentWidth
+  entriesRef.current = entries
+  listCommandArgsRef.current = listCommandArgs
+  interactiveRef.current = interactive
+  valueRef.current = value
+  cursorRef.current = cursor
+  hintOpenRef.current = hintOpen
+  commandIndexRef.current = commandIndex
+  const visibleFor = (text: string) => filterHintEntries(entriesRef.current ?? COMMANDS, text)
+  const undoStackRef = useRef<EditState[]>([])
+  const redoStackRef = useRef<EditState[]>([])
+  const pushUndoSnapshot = (): void => {
+    resetHistoryBrowse()
+    undoStackRef.current.push({ value: valueRef.current, cursor: cursorRef.current })
+    if (undoStackRef.current.length > UNDO_LIMIT) undoStackRef.current.shift()
+    redoStackRef.current.length = 0
+  }
+  const applySnapshot = (next: EditState): void => {
+    valueRef.current = next.value
+    cursorRef.current = next.cursor
+    setValue(next.value)
+    setCursor(next.cursor)
+    reconcileComposerFields(next.value, fieldsRef.current)
+  }
+  const applyEdit = (next: EditState | null): void => {
+    if (next === null) return
+    pushUndoSnapshot()
+    applySnapshot(next)
+  }
+  const undoEdit = (): void => {
+    const snapshot = undoStackRef.current.pop()
+    if (snapshot === undefined) return
+    redoStackRef.current.push({ value: valueRef.current, cursor: cursorRef.current })
+    if (redoStackRef.current.length > UNDO_LIMIT) redoStackRef.current.shift()
+    applySnapshot(snapshot)
+    refreshHint()
+  }
+  const redoEdit = (): void => {
+    const snapshot = redoStackRef.current.pop()
+    if (snapshot === undefined) return
+    undoStackRef.current.push({ value: valueRef.current, cursor: cursorRef.current })
+    if (undoStackRef.current.length > UNDO_LIMIT) undoStackRef.current.shift()
+    applySnapshot(snapshot)
+    refreshHint()
+  }
+  const HISTORY_LIMIT = 50
+  const historyRef = useRef<string[]>([])
+  const historyIndexRef = useRef(-1)
+  const historyDraftRef = useRef<EditState | null>(null)
+  const resetHistoryBrowse = (): void => {
+    historyIndexRef.current = -1
+    historyDraftRef.current = null
+  }
+  const historyOlder = (): void => {
+    const history = historyRef.current
+    if (history.length === 0) return
+    if (historyIndexRef.current === -1) {
+      historyDraftRef.current = { value: valueRef.current, cursor: cursorRef.current }
+      historyIndexRef.current = 0
+    } else if (historyIndexRef.current >= history.length - 1) {
+      return
+    } else {
+      historyIndexRef.current += 1
+    }
+    const entry = history[history.length - 1 - historyIndexRef.current]!
+    applySnapshot({ value: entry, cursor: entry.length })
+    closeHint()
+  }
+  const historyNewer = (): void => {
+    if (historyIndexRef.current === -1) return
+    if (historyIndexRef.current === 0) {
+      const draft = historyDraftRef.current
+      resetHistoryBrowse()
+      applySnapshot(draft ?? { value: '', cursor: 0 })
+      closeHint()
+      return
+    }
+    historyIndexRef.current -= 1
+    const entry = historyRef.current[historyRef.current.length - 1 - historyIndexRef.current]!
+    applySnapshot({ value: entry, cursor: entry.length })
+    closeHint()
+  }
+  const recordHistoryEntry = (text: string): void => {
+    resetHistoryBrowse()
+    if (text === '') return
+    const history = historyRef.current
+    if (history[history.length - 1] === text) return
+    history.push(text)
+    if (history.length > HISTORY_LIMIT) history.shift()
+  }
+  const closeHint = (): void => {
+    setHintOpen(false)
+    hintOpenRef.current = false
+    setCommandIndex(0)
+    commandIndexRef.current = 0
+  }
+  const openHint = (): void => {
+    setHintOpen(true)
+    hintOpenRef.current = true
+    setCommandIndex(0)
+    commandIndexRef.current = 0
+  }
+  const refreshHint = (): void => {
+    if (opensHint(valueRef.current)) openHint()
+    else closeHint()
+  }
+  const applyEditAndRefreshHint = (next: { value: string; cursor: number } | null): boolean => {
+    if (next === null) return false
+    applyEdit(next)
+    refreshHint()
+    return true
+  }
+  const apiRef = useRef<ComposerApi>({
+    moveLineBy(delta) {
+      const next = moveCaretLine(valueRef.current, cursorRef.current, widthRef.current, delta)
+      cursorRef.current = next
+      setCursor(next)
+    },
+    placeCursor(charIndex) {
+      const clamped = Math.max(0, Math.min(charIndex, valueRef.current.length))
+      cursorRef.current = clamped
+      setCursor(clamped)
+    },
+    selectHint(absoluteIndex) {
+      const commands = visibleFor(valueRef.current)
+      const clamped = Math.max(0, Math.min(absoluteIndex, commands.length - 1))
+      commandIndexRef.current = clamped
+      setCommandIndex(clamped)
+    },
+    confirmHint() {
+      const commands = visibleFor(valueRef.current)
+      if (commands.length === 0) return
+      const command = commands[Math.min(commandIndexRef.current, commands.length - 1)]?.command
+      if (command === undefined) return
+      const completed = `${command} `
+      pushUndoSnapshot()
+      valueRef.current = completed
+      cursorRef.current = completed.length
+      setValue(completed)
+      setCursor(completed.length)
+      closeHint()
+    },
+    hintMove(delta) {
+      const commands = visibleFor(valueRef.current)
+      if (commands.length === 0) return
+      const next = (commandIndexRef.current + delta + commands.length) % commands.length
+      commandIndexRef.current = next
+      setCommandIndex(next)
+    },
+    hintClickAt(absoluteIndex) {
+      if (!hintOpenRef.current) return
+      if (absoluteIndex === commandIndexRef.current) {
+        apiRef.current.confirmHint()
+        return
+      }
+      apiRef.current.selectHint(absoluteIndex)
+    },
+    hintPick(absoluteIndex) {
+      if (!hintOpenRef.current) return
+      apiRef.current.selectHint(absoluteIndex)
+      apiRef.current.confirmHint()
+    },
+  })
+  const insertPaste = (normalized: string): void => {
+    const sanitized = sanitizePastedText(normalized)
+    if (sanitized === '') return
+    const { value: current, cursor: at } = { value: valueRef.current, cursor: cursorRef.current }
+    const inserted = buildPasteFields(sanitized, fieldsRef.current)
+    applyEdit(editInsert({ value: current, cursor: at }, inserted))
+    refreshHint()
+  }
+  const upgradeFirstImageGroupFromClipboard = async (): Promise<void> => {
+    const entries = [...fieldsRef.current.entries()]
+    const imageFields = entries.filter(([, field]) => field.kind === 'image')
+    if (imageFields.length !== 1) return
+    const [, field] = imageFields[0]!
+    const pathCount = (field.images ?? []).filter(image => image.kind === 'path').length
+    if (pathCount !== 1) return
+    try {
+      const uris = await readClipboardImageUris()
+      if (uris.length > 1) field.images = uris.map(path => ({ kind: 'path' as const, path }))
+    } catch {
+      // Clipboard URI lists are best-effort; a single pasted path stays as-is.
+    }
+  }
+  const pasteFromClipboard = async (allowText: boolean): Promise<void> => {
+    try {
+      const image = await readClipboardImage()
+      if (image !== undefined) {
+        insertPaste(insertClipboardImage(image, fieldsRef.current))
+        return
+      }
+      if (!allowText) return
+      const text = await readClipboardText()
+      if (text !== undefined && text !== '') insertPaste(text.replace(/\r\n?/g, '\n'))
+    } catch {
+      // A clipboard backend failure is ignored: the paste simply does not insert.
+    }
+  }
+  usePaste(text => {
+    if (!interactive) return
+    const normalized = text.replace(/\r\n?/g, '\n')
+    if (normalized === '') {
+      void pasteFromClipboard(true)
+      return
+    }
+    void (async () => {
+      const claimed = claimPaste(normalized, cursorRef.current)
+      insertPaste(claimed === undefined ? normalized : claimed.insert)
+      if (claimed === undefined) void upgradeFirstImageGroupFromClipboard()
+    })()
+  }, { isActive: interactive })
+  const insertText = (text: string): void => {
+    applyEdit(editInsert({ value: valueRef.current, cursor: cursorRef.current }, text))
+  }
+  useEffect(() => {
+    setComposerInserter(spec => {
+      if (!interactiveRef.current) return false
+      if (spec.field !== undefined) {
+        const char = insertFieldSpec(spec.field, fieldsRef.current)
+        applyEdit(editInsert({ value: valueRef.current, cursor: cursorRef.current }, char))
+        refreshHint()
+        return true
+      }
+      if (spec.text !== undefined && spec.text !== '') {
+        applyEdit(editInsert({ value: valueRef.current, cursor: cursorRef.current }, sanitizePastedText(spec.text)))
+        refreshHint()
+        return true
+      }
+      return false
+    })
+    return () => setComposerInserter(undefined)
+  }, [])
+  const completeCommandArg = (): void => {
+    const v = valueRef.current
+    const match = /^(\/\S+)(?:\s+(\S*))?(?:\s+(.*\S))?\s*$/.exec(v)
+    if (match === null) return
+    const commandToken = match[1]!
+    const entry = entriesRef.current?.find(candidate => candidate.command === commandToken)
+    if (entry === undefined) return
+    const currentArg = match[2] ?? ''
+    const rest = match[3]
+    void (async () => {
+      let candidates: string[] = []
+      try {
+        candidates = await listCommandArgsRef.current?.(entry.command.slice(1)) ?? []
+      } catch {
+        // An argument provider failure abandons the completion quietly.
+        return
+      }
+      if (candidates.length === 0) candidates = literalHintArgs(entry.hint)
+      if (candidates.length === 0) return
+      const exactIndex = candidates.indexOf(currentArg)
+      let next: string
+      if (exactIndex >= 0) {
+        next = candidates[(exactIndex + 1) % candidates.length]!
+      } else {
+        next = candidates.find(candidate => candidate.startsWith(currentArg)) ?? candidates[0]!
+      }
+      const completed = `${commandToken} ${next}${rest === undefined ? '' : ` ${rest}`}`
+      pushUndoSnapshot()
+      valueRef.current = completed
+      cursorRef.current = completed.length
+      setValue(completed)
+      setCursor(completed.length)
+      closeHint()
+    })()
+  }
+  useInput((input, key) => {
+    if (!interactive || isKeyConsumed()) return
+    if (handleComposerKeyBindings(input, key)) {
+      return
+    }
+    if (input === '\n') {
+      insertText('\n')
+      return
+    }
+    const v = valueRef.current
+    const c = cursorRef.current
+    const commands = visibleFor(v)
+    const showHint = hintOpenRef.current && commands.length > 0
+    if (key.return && !key.shift && showHint) {
+      const selected = commands[Math.min(commandIndexRef.current, commands.length - 1)]
+      const exactArgless = selected !== undefined && selected.hint === undefined && v === selected.command
+      if (!exactArgless) {
+        apiRef.current.confirmHint()
+        return
+      }
+    }
+    if (key.escape && showHint) {
+      closeHint()
+      return
+    }
+    if (key.tab) {
+      if (!v.startsWith('/')) {
+        onCycleMode?.()
+        return
+      }
+      const lastChar = v.length > 0 ? v[v.length - 1] : undefined
+      const completable = c === v.length && lastChar !== undefined && !/\s/.test(lastChar)
+      const trailingCommand = c === v.length && /^(\/\S+)\s+$/.test(v)
+      const exactCommand = entriesRef.current?.some(entry => entry.command === v) ?? false
+      if (completable && exactCommand) {
+        completeCommandArg()
+        return
+      }
+      if (showHint) {
+        apiRef.current.confirmHint()
+        return
+      }
+      if (completable || trailingCommand) {
+        completeCommandArg()
+      }
+      return
+    }
+    if (key.upArrow && showHint) {
+      const next = (commandIndexRef.current - 1 + commands.length) % commands.length
+      commandIndexRef.current = next
+      setCommandIndex(next)
+      return
+    }
+    if (key.downArrow && showHint) {
+      const next = (commandIndexRef.current + 1) % commands.length
+      commandIndexRef.current = next
+      setCommandIndex(next)
+      return
+    }
+    if (key.return && !key.shift) {
+      const submission = expandComposerValue(v, fieldsRef.current)
+      if (submission.text !== '' || submission.images.length > 0) onSend(submission)
+      recordHistoryEntry(submission.text)
+      fieldsRef.current = new Map()
+      valueRef.current = ''
+      cursorRef.current = 0
+      setValue('')
+      setCursor(0)
+      undoStackRef.current.length = 0
+      redoStackRef.current.length = 0
+      closeHint()
+      return
+    }
+    if (key.return) {
+      insertText('\n')
+      return
+    }
+    if (key.ctrl && input === 'v') {
+      void pasteFromClipboard(true)
+      return
+    }
+    if (key.ctrl && input === 'z') {
+      if (key.shift) redoEdit()
+      else undoEdit()
+      return
+    }
+    if (key.ctrl && input === 'y') {
+      redoEdit()
+      return
+    }
+    if (key.meta && key.backspace && applyEditAndRefreshHint(editDeleteWordLeft({ value: v, cursor: c }))) {
+      return
+    }
+    if (key.meta && key.delete && applyEditAndRefreshHint(editDeleteWordRight({ value: v, cursor: c }))) {
+      return
+    }
+    if (key.meta && key.leftArrow && c > 0) {
+      const moved = editCursorWordLeft({ value: v, cursor: c })
+      cursorRef.current = moved.cursor
+      setCursor(moved.cursor)
+      return
+    }
+    if (key.meta && key.rightArrow && c < v.length) {
+      const moved = editCursorWordRight({ value: v, cursor: c })
+      cursorRef.current = moved.cursor
+      setCursor(moved.cursor)
+      return
+    }
+    if (key.backspace && applyEditAndRefreshHint(editBackspace({ value: v, cursor: c }))) {
+      return
+    }
+    if (key.delete && applyEditAndRefreshHint(editDelete({ value: v, cursor: c }))) {
+      return
+    }
+    if (key.leftArrow && c > 0) {
+      const moved = editCursorLeft({ value: v, cursor: c })
+      cursorRef.current = moved.cursor
+      setCursor(moved.cursor)
+      return
+    }
+    if (key.rightArrow && c < v.length) {
+      const moved = editCursorRight({ value: v, cursor: c })
+      cursorRef.current = moved.cursor
+      setCursor(moved.cursor)
+      return
+    }
+    if (key.upArrow) {
+      const moved = moveCaretLine(v, c, contentWidth, -1)
+      if (moved !== c) {
+        cursorRef.current = moved
+        setCursor(moved)
+      } else {
+        historyOlder()
+      }
+      return
+    }
+    if (key.downArrow) {
+      const moved = moveCaretLine(v, c, contentWidth, 1)
+      if (moved !== c) {
+        cursorRef.current = moved
+        setCursor(moved)
+      } else {
+        historyNewer()
+      }
+      return
+    }
+    if (key.home) {
+      cursorRef.current = 0
+      setCursor(0)
+      return
+    }
+    if (key.end) {
+      cursorRef.current = v.length
+      setCursor(v.length)
+      return
+    }
+    if (input && !key.ctrl && !key.meta && !isMouseResidue(input)) {
+      if (/[\u0000-\u001f\u007f]/.test(input)) return
+      applyEditAndRefreshHint(editInsert({ value: v, cursor: c }, input))
+      return
+    }
+  })
+  return { value, cursor, hintOpen, commandIndex, api: apiRef.current }
+}

package/src/ui/key-arbiter.ts

@@ -0,0 +1,37 @@
+/**
+ * Key-event suppression for ink's broadcast-based useInput.
+ *
+ * ink delivers every stdin chunk to every useInput subscriber, and delivery
+ * order follows subscription order: KeymapGate (chrome key contributions,
+ * mounted as the first child) -> message list -> composer -> panels ->
+ * dialog -> the App shell. A participant that must win over the later ones
+ * marks the current event consumed; later participants skip it.
+ *
+ * The consumed flag is scoped to one stdin chunk. KeymapGate bumps the
+ * generation from its own stdin data listener, so even several synchronous
+ * writes (as tests do) each get a fresh generation and no flag leaks across
+ * events.
+ */
+let generation = 0
+let consumedAtGeneration = -1
+
+/** Start a new key-event generation; called once per stdin chunk. */
+export function beginKeyEvent(): void {
+  generation += 1
+}
+
+/** Chrome key contributions consumed the event; later participants must skip it. */
+export function markKeymapConsumed(): void {
+  consumedAtGeneration = generation
+}
+
+/** True when the chrome key chain consumed the current key event. */
+export function isKeyConsumed(): boolean {
+  return consumedAtGeneration === generation
+}
+
+/** Test helper. */
+export function resetKeyEvents(): void {
+  generation = 0
+  consumedAtGeneration = -1
+}

package/src/ui/keymap.ts

@@ -0,0 +1,15 @@
+import { keyedRegistry } from '../kernel/registry.ts'
+import type { KeyBindingContribution, TuiKey } from '../contract/index.ts'
+
+const bindings = keyedRegistry<KeyBindingContribution>()
+
+export function registerKeyBinding(contribution: KeyBindingContribution): () => void {
+  return bindings.register(contribution.id, contribution, { order: contribution.order })
+}
+
+export function handleKeyContributions(input: string, key: TuiKey): boolean {
+  for (const contribution of bindings.values()) {
+    if (contribution.handle(input, key) === true) return true
+  }
+  return false
+}

package/src/ui/layout-service.ts

@@ -0,0 +1,77 @@
+import { CHROME_FRAME_ROWS, MESSAGE_INPUT_GAP_ROWS, SCROLLBAR_COL_FROM_EDGE, SCROLLBAR_GAP_COLS, CHROME_MARGIN_X, hintBlockTop } from '../core/metrics.ts'
+import { HINT_INPUT_GAP_ROWS } from '../core/metrics.ts'
+
+/**
+ * Single source of truth for the shell's derived geometry. Every consumer
+ * (App layout, pointer handlers, panels, message scrollbar) derives its
+ * region from these helpers instead of repeating the formulas, so changing
+ * the chrome skeleton only touches this file.
+ */
+
+export interface ShellGeometry {
+  columns: number
+  rows: number
+  /** Full height of the input block (frame rows + content rows). */
+  inputHeight: number
+  /** Height of the message area. */
+  messageHeight: number
+  /** Height of the active interaction panel body, when a panel owns the bottom. */
+  panelHeight: number | null
+}
+
+export function inputContentTop(rows: number, inputHeight: number): number {
+  return rows - inputHeight
+}
+
+/** Inclusive bottom row of the input's editable content area. */
+export function inputContentBottom(rows: number, inputHeight: number): number {
+  return inputContentTop(rows, inputHeight) + inputHeight - CHROME_FRAME_ROWS
+}
+
+export function inputContentContains(y: number, rows: number, inputHeight: number): boolean {
+  return y >= inputContentTop(rows, inputHeight) && y <= inputContentBottom(rows, inputHeight)
+}
+
+export function messageHeightOf(rows: number, inputHeight: number): number {
+  return Math.max(1, rows - inputHeight - MESSAGE_INPUT_GAP_ROWS)
+}
+
+/** Inclusive row span of the active interaction panel (message bottom .. above the status line). */
+export function panelSpan(geometry: ShellGeometry): { top: number; bottom: number } {
+  return { top: geometry.messageHeight, bottom: geometry.rows - 2 }
+}
+
+export function panelContains(y: number, geometry: ShellGeometry): boolean {
+  const span = panelSpan(geometry)
+  return y >= span.top && y <= span.bottom
+}
+
+/** Anchor row where a panel of `bodyRows` lines must start to sit above the status line. */
+export function panelAnchorRow(rows: number, bodyRows: number): number {
+  return rows - 2 - bodyRows
+}
+
+export interface HintSpan {
+  top: number
+  bottom: number
+}
+
+export function hintSpan(rows: number, inputHeight: number, visibleCount: number, dialogOpen: boolean): HintSpan | null {
+  if (dialogOpen || visibleCount <= 0) return null
+  const top = hintBlockTop(rows, inputHeight, visibleCount)
+  const bottom = rows - inputHeight - MESSAGE_INPUT_GAP_ROWS - HINT_INPUT_GAP_ROWS
+  return { top, bottom }
+}
+
+export function hintContains(y: number, rows: number, inputHeight: number, visibleCount: number, dialogOpen: boolean): boolean {
+  const span = hintSpan(rows, inputHeight, visibleCount, dialogOpen)
+  return span !== null && y >= span.top && y <= span.bottom
+}
+
+export function scrollbarColumn(columns: number): number {
+  return columns - SCROLLBAR_COL_FROM_EDGE
+}
+
+export function messageBackgroundWidth(width: number): number {
+  return width - CHROME_MARGIN_X - SCROLLBAR_COL_FROM_EDGE - SCROLLBAR_GAP_COLS
+}