refactor: 大规模迁移原有组件到 ink 包内

packages/@ant/ink/src/hooks/useDoublePress.ts

@@ -0,0 +1,62 @@
+// Creates a function that calls one function on the first call and another
+// function on the second call within a certain timeout
+
+import { useCallback, useEffect, useRef } from 'react'
+
+export const DOUBLE_PRESS_TIMEOUT_MS = 800
+
+export function useDoublePress(
+  setPending: (pending: boolean) => void,
+  onDoublePress: () => void,
+  onFirstPress?: () => void,
+): () => void {
+  const lastPressRef = useRef<number>(0)
+  const timeoutRef = useRef<NodeJS.Timeout | undefined>(undefined)
+
+  const clearTimeoutSafe = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current)
+      timeoutRef.current = undefined
+    }
+  }, [])
+
+  // Cleanup timeout on unmount
+  useEffect(() => {
+    return () => {
+      clearTimeoutSafe()
+    }
+  }, [clearTimeoutSafe])
+
+  return useCallback(() => {
+    const now = Date.now()
+    const timeSinceLastPress = now - lastPressRef.current
+    const isDoublePress =
+      timeSinceLastPress <= DOUBLE_PRESS_TIMEOUT_MS &&
+      timeoutRef.current !== undefined
+
+    if (isDoublePress) {
+      // Double press detected
+      clearTimeoutSafe()
+      setPending(false)
+      onDoublePress()
+    } else {
+      // First press
+      onFirstPress?.()
+      setPending(true)
+
+      // Clear any existing timeout and set new one
+      clearTimeoutSafe()
+      timeoutRef.current = setTimeout(
+        (setPending, timeoutRef) => {
+          setPending(false)
+          timeoutRef.current = undefined
+        },
+        DOUBLE_PRESS_TIMEOUT_MS,
+        setPending,
+        timeoutRef,
+      )
+    }
+
+    lastPressRef.current = now
+  }, [setPending, onDoublePress, onFirstPress, clearTimeoutSafe])
+}

packages/@ant/ink/src/hooks/useMinDisplayTime.ts

@@ -0,0 +1,35 @@
+import { useEffect, useRef, useState } from 'react'
+
+/**
+ * Throttles a value so each distinct value stays visible for at least `minMs`.
+ * Prevents fast-cycling progress text from flickering past before it's readable.
+ *
+ * Unlike debounce (wait for quiet) or throttle (limit rate), this guarantees
+ * each value gets its minimum screen time before being replaced.
+ */
+export function useMinDisplayTime<T>(value: T, minMs: number): T {
+  const [displayed, setDisplayed] = useState(value)
+  const lastShownAtRef = useRef(0)
+
+  useEffect(() => {
+    const elapsed = Date.now() - lastShownAtRef.current
+    if (elapsed >= minMs) {
+      lastShownAtRef.current = Date.now()
+      setDisplayed(value)
+      return
+    }
+    const timer = setTimeout(
+      (shownAtRef, setFn, v) => {
+        shownAtRef.current = Date.now()
+        setFn(v)
+      },
+      minMs - elapsed,
+      lastShownAtRef,
+      setDisplayed,
+      value,
+    )
+    return () => clearTimeout(timer)
+  }, [value, minMs])
+
+  return displayed
+}

packages/@ant/ink/src/hooks/useTimeout.ts

@@ -0,0 +1,14 @@
+import { useEffect, useState } from 'react'
+
+export function useTimeout(delay: number, resetTrigger?: number): boolean {
+  const [isElapsed, setIsElapsed] = useState(false)
+
+  useEffect(() => {
+    setIsElapsed(false)
+    const timer = setTimeout(setIsElapsed, delay, true)
+
+    return () => clearTimeout(timer)
+  }, [delay, resetTrigger])
+
+  return isElapsed
+}

packages/@ant/ink/src/index.ts

@@ -49,6 +49,10 @@ export {
   matchesKeystroke,
   matchesBinding,
 } from './keybindings/match.js'
+export {
+  KeybindingSetup,
+  type KeybindingSetupProps,
+} from './keybindings/KeybindingSetup.js'
 export type {
   ParsedBinding,
   ParsedKeystroke,
@@ -56,6 +60,9 @@ export type {
   KeybindingBlock,
   Chord,
   KeybindingAction,
+  KeybindingWarningType,
+  KeybindingWarning,
+  KeybindingsLoadResult,
 } from './keybindings/types.js'
 
 // ============================================================
@@ -130,6 +137,10 @@ export { useAnimationFrame } from './hooks/use-animation-frame.js'
 export { useAnimationTimer, useInterval } from './hooks/use-interval.js'
 export { useSelection, useHasSelection } from './hooks/use-selection.js'
 export { default as useStdin } from './hooks/use-stdin.js'
+export { useTerminalSize } from './hooks/useTerminalSize.js'
+export { useTimeout } from './hooks/useTimeout.js'
+export { useMinDisplayTime } from './hooks/useMinDisplayTime.js'
+export { useDoublePress, DOUBLE_PRESS_TIMEOUT_MS } from './hooks/useDoublePress.js'
 export { useTabStatus, type TabStatusKind } from './hooks/use-tab-status.js'
 export { useTerminalFocus } from './hooks/use-terminal-focus.js'
 export { useTerminalTitle } from './hooks/use-terminal-title.js'
@@ -149,11 +160,12 @@ export {
 } from './theme/ThemeProvider.js'
 export { default as Box } from './theme/ThemedBox.js'
 export type { Props as BoxProps } from './theme/ThemedBox.js'
-export { default as Text } from './theme/ThemedText.js'
+export { default as Text, TextHoverColorContext } from './theme/ThemedText.js'
 export type { Props as TextProps } from './theme/ThemedText.js'
 export { color } from './theme/color.js'
 
 // Theme sub-components
+export { SearchBox } from './theme/SearchBox.js'
 export { Dialog } from './theme/Dialog.js'
 export { Divider } from './theme/Divider.js'
 export { FuzzyPicker } from './theme/FuzzyPicker.js'
@@ -163,6 +175,6 @@ export { Pane } from './theme/Pane.js'
 export { ProgressBar } from './theme/ProgressBar.js'
 export { Ratchet } from './theme/Ratchet.js'
 export { StatusIcon } from './theme/StatusIcon.js'
-export { Tabs } from './theme/Tabs.js'
+export { Tabs, Tab, useTabsWidth, useTabHeaderFocus } from './theme/Tabs.js'
 export { Byline } from './theme/Byline.js'
 export { KeyboardShortcutHint } from './theme/KeyboardShortcutHint.js'

packages/@ant/ink/src/keybindings/KeybindingSetup.tsx

@@ -0,0 +1,320 @@
+/**
+ * Generic keybinding setup component for integrating KeybindingProvider into an app.
+ *
+ * Provides chord state management, a ChordInterceptor, and the KeybindingProvider
+ * wrapper. App-specific dependencies (binding loading, change subscription,
+ * warning display, debug logging) are injected via props.
+ */
+import React, { useCallback, useEffect, useRef, useState } from 'react'
+import type { InputEvent } from '../core/events/input-event.js'
+// ChordInterceptor intentionally uses useInput to intercept all keystrokes before
+// other handlers process them - this is required for chord sequence support
+// eslint-disable-next-line custom-rules/prefer-use-keybindings
+import useInput, { type Key } from '../hooks/use-input.js'
+import { KeybindingProvider } from './KeybindingContext.js'
+import { resolveKeyWithChordState } from './resolver.js'
+import type {
+  KeybindingContextName,
+  KeybindingsLoadResult,
+  ParsedBinding,
+  ParsedKeystroke,
+  KeybindingWarning,
+} from './types.js'
+
+/**
+ * Timeout for chord sequences in milliseconds.
+ * If the user doesn't complete the chord within this time, it's cancelled.
+ */
+const CHORD_TIMEOUT_MS = 1000
+
+export type KeybindingSetupProps = {
+  children: React.ReactNode
+
+  /** Load bindings synchronously for initial render */
+  loadBindings: () => KeybindingsLoadResult
+
+  /** Subscribe to binding changes; return an unsubscribe function */
+  subscribeToChanges: (
+    callback: (result: KeybindingsLoadResult) => void,
+  ) => () => void
+
+  /** Initialize any file watcher (idempotent). Called once on mount. */
+  initWatcher?: () => void | Promise<void>
+
+  /** Optional callback when warnings are emitted (initial load or reload) */
+  onWarnings?: (warnings: KeybindingWarning[], isReload: boolean) => void
+
+  /** Optional debug logger */
+  onDebugLog?: (message: string) => void
+}
+
+export function KeybindingSetup({
+  children,
+  loadBindings,
+  subscribeToChanges,
+  initWatcher,
+  onWarnings,
+  onDebugLog,
+}: KeybindingSetupProps): React.ReactNode {
+  // Load bindings synchronously for initial render
+  const [loadResult, setLoadResult] = useState<KeybindingsLoadResult>(() => {
+    const result = loadBindings()
+    onDebugLog?.(
+      `[keybindings] KeybindingSetup initialized with ${result.bindings.length} bindings, ${result.warnings.length} warnings`,
+    )
+    return result
+  })
+
+  const { bindings, warnings } = loadResult
+
+  // Track if this is a reload (not initial load)
+  const [isReload, setIsReload] = useState(false)
+
+  // Notify about warnings
+  useEffect(() => {
+    onWarnings?.(warnings, isReload)
+  }, [warnings, isReload, onWarnings])
+
+  // Chord state management - use ref for immediate access, state for re-renders
+  const pendingChordRef = useRef<ParsedKeystroke[] | null>(null)
+  const [pendingChord, setPendingChordState] = useState<
+    ParsedKeystroke[] | null
+  >(null)
+  const chordTimeoutRef = useRef<NodeJS.Timeout | null>(null)
+
+  // Handler registry for action callbacks (used by ChordInterceptor to invoke handlers)
+  const handlerRegistryRef = useRef(
+    new Map<
+      string,
+      Set<{
+        action: string
+        context: KeybindingContextName
+        handler: () => void
+      }>
+    >(),
+  )
+
+  // Active context tracking for keybinding priority resolution
+  const activeContextsRef = useRef<Set<KeybindingContextName>>(new Set())
+
+  const registerActiveContext = useCallback(
+    (context: KeybindingContextName) => {
+      activeContextsRef.current.add(context)
+    },
+    [],
+  )
+
+  const unregisterActiveContext = useCallback(
+    (context: KeybindingContextName) => {
+      activeContextsRef.current.delete(context)
+    },
+    [],
+  )
+
+  // Clear chord timeout when component unmounts or chord changes
+  const clearChordTimeout = useCallback(() => {
+    if (chordTimeoutRef.current) {
+      clearTimeout(chordTimeoutRef.current)
+      chordTimeoutRef.current = null
+    }
+  }, [])
+
+  // Wrapper for setPendingChord that manages timeout and syncs ref+state
+  const setPendingChord = useCallback(
+    (pending: ParsedKeystroke[] | null) => {
+      clearChordTimeout()
+
+      if (pending !== null) {
+        // Set timeout to cancel chord if not completed
+        chordTimeoutRef.current = setTimeout(
+          (pendingChordRef, setPendingChordState) => {
+            onDebugLog?.('[keybindings] Chord timeout - cancelling')
+            pendingChordRef.current = null
+            setPendingChordState(null)
+          },
+          CHORD_TIMEOUT_MS,
+          pendingChordRef,
+          setPendingChordState,
+        )
+      }
+
+      // Update ref immediately for synchronous access in resolve()
+      pendingChordRef.current = pending
+      // Update state to trigger re-renders for UI updates
+      setPendingChordState(pending)
+    },
+    [clearChordTimeout, onDebugLog],
+  )
+
+  useEffect(() => {
+    // Initialize file watcher (idempotent - only runs once)
+    void initWatcher?.()
+
+    // Subscribe to changes
+    const unsubscribe = subscribeToChanges(result => {
+      // Any callback invocation is a reload since initial load happens
+      // synchronously in useState, not via this subscription
+      setIsReload(true)
+
+      setLoadResult(result)
+      onDebugLog?.(
+        `[keybindings] Reloaded: ${result.bindings.length} bindings, ${result.warnings.length} warnings`,
+      )
+    })
+
+    return () => {
+      unsubscribe()
+      clearChordTimeout()
+    }
+  }, [subscribeToChanges, initWatcher, clearChordTimeout, onDebugLog])
+
+  return (
+    <KeybindingProvider
+      bindings={bindings}
+      pendingChordRef={pendingChordRef}
+      pendingChord={pendingChord}
+      setPendingChord={setPendingChord}
+      activeContexts={activeContextsRef.current}
+      registerActiveContext={registerActiveContext}
+      unregisterActiveContext={unregisterActiveContext}
+      handlerRegistryRef={handlerRegistryRef}
+    >
+      <ChordInterceptor
+        bindings={bindings}
+        pendingChordRef={pendingChordRef}
+        setPendingChord={setPendingChord}
+        activeContexts={activeContextsRef.current}
+        handlerRegistryRef={handlerRegistryRef}
+      />
+      {children}
+    </KeybindingProvider>
+  )
+}
+
+/**
+ * Global chord interceptor that registers useInput FIRST (before children).
+ *
+ * This component intercepts keystrokes that are part of chord sequences and
+ * stops propagation before other handlers (like PromptInput) can see them.
+ *
+ * Without this, the second key of a chord (e.g., 'r' in "ctrl+c r") would be
+ * captured by PromptInput and added to the input field before the keybinding
+ * system could recognize it as completing a chord.
+ */
+type HandlerRegistration = {
+  action: string
+  context: KeybindingContextName
+  handler: () => void
+}
+
+function ChordInterceptor({
+  bindings,
+  pendingChordRef,
+  setPendingChord,
+  activeContexts,
+  handlerRegistryRef,
+}: {
+  bindings: ParsedBinding[]
+  pendingChordRef: React.RefObject<ParsedKeystroke[] | null>
+  setPendingChord: (pending: ParsedKeystroke[] | null) => void
+  activeContexts: Set<KeybindingContextName>
+  handlerRegistryRef: React.RefObject<Map<string, Set<HandlerRegistration>>>
+}): null {
+  const handleInput = useCallback(
+    (input: string, key: Key, event: InputEvent) => {
+      // Wheel events can never start chord sequences — scroll:lineUp/Down are
+      // single-key bindings handled by per-component useKeybindings hooks, not
+      // here. Skip the registry scan. Mid-chord wheel still falls through so
+      // scrolling cancels the pending chord like any other non-matching key.
+      if ((key.wheelUp || key.wheelDown) && pendingChordRef.current === null) {
+        return
+      }
+
+      // Build context list from registered handlers + activeContexts + Global
+      const registry = handlerRegistryRef.current
+      const handlerContexts = new Set<KeybindingContextName>()
+      if (registry) {
+        for (const handlers of registry.values()) {
+          for (const registration of handlers) {
+            handlerContexts.add(registration.context)
+          }
+        }
+      }
+      const contexts: KeybindingContextName[] = [
+        ...handlerContexts,
+        ...activeContexts,
+        'Global',
+      ]
+
+      // Track whether we're completing a chord (pending was non-null)
+      const wasInChord = pendingChordRef.current !== null
+
+      // Check if this keystroke is part of a chord sequence
+      const result = resolveKeyWithChordState(
+        input,
+        key,
+        contexts,
+        bindings,
+        pendingChordRef.current,
+      )
+
+      switch (result.type) {
+        case 'chord_started':
+          // This key starts a chord - store pending state and stop propagation
+          setPendingChord(result.pending)
+          event.stopImmediatePropagation()
+          break
+
+        case 'match': {
+          // Clear pending state
+          setPendingChord(null)
+
+          // Only invoke handlers and stop propagation for chord completions
+          // (multi-keystroke sequences). Single-keystroke matches should propagate
+          // to per-hook handlers to avoid interfering with other input handling.
+          if (wasInChord) {
+            const contextsSet = new Set(contexts)
+            if (registry) {
+              const handlers = registry.get(result.action)
+              if (handlers && handlers.size > 0) {
+                for (const registration of handlers) {
+                  if (contextsSet.has(registration.context)) {
+                    registration.handler()
+                    event.stopImmediatePropagation()
+                    break
+                  }
+                }
+              }
+            }
+          }
+          break
+        }
+
+        case 'chord_cancelled':
+          setPendingChord(null)
+          event.stopImmediatePropagation()
+          break
+
+        case 'unbound':
+          setPendingChord(null)
+          event.stopImmediatePropagation()
+          break
+
+        case 'none':
+          // No chord involvement - let other handlers process
+          break
+      }
+    },
+    [
+      bindings,
+      pendingChordRef,
+      setPendingChord,
+      activeContexts,
+      handlerRegistryRef,
+    ],
+  )
+
+  useInput(handleInput)
+
+  return null
+}

packages/@ant/ink/src/keybindings/types.ts

@@ -21,3 +21,34 @@ export type KeybindingBlock = {
 }
 export type Chord = ParsedKeystroke[]
 export type KeybindingAction = string
+
+/**
+ * Types of validation issues that can occur with keybindings.
+ */
+export type KeybindingWarningType =
+  | 'parse_error'
+  | 'duplicate'
+  | 'reserved'
+  | 'invalid_context'
+  | 'invalid_action'
+
+/**
+ * A warning or error about a keybinding configuration issue.
+ */
+export type KeybindingWarning = {
+  type: KeybindingWarningType
+  severity: 'error' | 'warning'
+  message: string
+  key?: string
+  context?: string
+  action?: string
+  suggestion?: string
+}
+
+/**
+ * Result of loading keybindings, including any validation warnings.
+ */
+export type KeybindingsLoadResult = {
+  bindings: ParsedBinding[]
+  warnings: KeybindingWarning[]
+}