@silvery/ui 0.3.0

package/src/components/TextArea.tsx

@@ -0,0 +1,264 @@
+/**
+ * TextArea Component
+ *
+ * Multi-line text input with word wrapping, scrolling, and cursor movement.
+ * Uses useContentRect for width-aware word wrapping and VirtualList-style
+ * scroll tracking to keep the cursor visible.
+ *
+ * Built on useTextArea hook — use the hook directly for custom rendering.
+ *
+ * Includes full readline-style editing: word movement, word kill, kill ring
+ * (yank/cycle), and character transpose -- shared with TextInput via readline-ops.
+ *
+ * Usage:
+ * ```tsx
+ * const [value, setValue] = useState('')
+ * <TextArea
+ *   value={value}
+ *   onChange={setValue}
+ *   onSubmit={(val) => console.log('Submitted:', val)}
+ *   height={10}
+ *   placeholder="Type here..."
+ * />
+ * ```
+ *
+ * Supported shortcuts:
+ * - Arrow keys: Move cursor (clears selection)
+ * - Shift+Arrow: Extend selection
+ * - Shift+Home/End: Select to line boundaries
+ * - Ctrl+Shift+Arrow: Word-wise selection
+ * - Ctrl+A: Select all text
+ * - Ctrl+E: End of line
+ * - Home/End: Beginning/end of line
+ * - Alt+B/F: Move by word (wraps across lines)
+ * - Ctrl+W, Alt+Backspace: Delete word backwards (kill ring)
+ * - Alt+D: Delete word forwards (kill ring)
+ * - Ctrl+K: Kill to end of line (kill ring)
+ * - Ctrl+U: Kill to beginning of line (kill ring)
+ * - Ctrl+Y: Yank (paste from kill ring)
+ * - Alt+Y: Cycle through kill ring (after Ctrl+Y)
+ * - Ctrl+T: Transpose characters
+ * - PageUp/PageDown: Scroll by viewport height
+ * - Backspace/Delete: Delete characters (or selected text)
+ * - Enter: Insert newline (replaces selection, or submit with submitKey)
+ * - Typing with selection: Replaces selected text
+ */
+import { forwardRef, useImperativeHandle } from "react"
+import { useContentRect } from "@silvery/react/hooks/useLayout"
+import { useFocusable } from "@silvery/react/hooks/useFocusable"
+import { useCursor } from "@silvery/react/hooks/useCursor"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+import { useTextArea } from "./useTextArea"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TextAreaProps {
+  /** Current value (controlled) */
+  value?: string
+  /** Initial value (uncontrolled) */
+  defaultValue?: string
+  /** Called when value changes */
+  onChange?: (value: string) => void
+  /** Called on submit (Ctrl+Enter by default, or Enter if submitKey="enter") */
+  onSubmit?: (value: string) => void
+  /** Key to trigger submit: "ctrl+enter" (default), "enter", or "meta+enter" */
+  submitKey?: "ctrl+enter" | "enter" | "meta+enter"
+  /** Placeholder text when empty */
+  placeholder?: string
+  /** Whether input is focused/active (overrides focus system) */
+  isActive?: boolean
+  /** Visible height in rows (required) */
+  height: number
+  /** Cursor style: 'block' (inverse) or 'underline' */
+  cursorStyle?: "block" | "underline"
+  /** Number of context lines to keep visible above/below cursor when scrolling (default: 1) */
+  scrollMargin?: number
+  /** When true, ignore all input and dim the text */
+  disabled?: boolean
+  /** Maximum number of characters allowed */
+  maxLength?: number
+  /** Border style (e.g., "round", "single") — wraps input in bordered Box */
+  borderStyle?: string
+  /** Border color when unfocused (default: "$border") */
+  borderColor?: string
+  /** Border color when focused (default: "$focusborder") */
+  focusBorderColor?: string
+  /** Test ID for focus system identification */
+  testID?: string
+}
+
+/** Selection range as [start, end) character offsets */
+export { type TextAreaSelection } from "./useTextArea"
+
+export interface TextAreaHandle {
+  /** Clear the input */
+  clear: () => void
+  /** Get current value */
+  getValue: () => string
+  /** Set value programmatically */
+  setValue: (value: string) => void
+  /** Get the current selection range, or null if no selection */
+  getSelection: () => import("./useTextArea").TextAreaSelection | null
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export const TextArea = forwardRef<TextAreaHandle, TextAreaProps>(function TextArea(
+  {
+    value: controlledValue,
+    defaultValue = "",
+    onChange,
+    onSubmit,
+    submitKey = "ctrl+enter",
+    placeholder = "",
+    isActive: isActiveProp,
+    height,
+    cursorStyle = "block",
+    scrollMargin = 1,
+    disabled,
+    maxLength,
+    borderStyle: borderStyleProp,
+    borderColor: borderColorProp = "$border",
+    focusBorderColor = "$focusborder",
+    testID,
+  },
+  ref,
+) {
+  // Focus system integration: prop overrides hook.
+  // When testID is set, the component participates in the focus tree and
+  // isActive derives from focus state. Without testID, default to true
+  // for backward compatibility.
+  const { focused } = useFocusable()
+  const isActive = isActiveProp ?? (testID ? focused : true)
+
+  const { width } = useContentRect()
+
+  const ta = useTextArea({
+    value: controlledValue,
+    defaultValue,
+    onChange,
+    onSubmit,
+    submitKey,
+    isActive,
+    height,
+    wrapWidth: width,
+    scrollMargin,
+    disabled,
+    maxLength,
+  })
+
+  // Imperative handle
+  useImperativeHandle(ref, () => ({
+    clear: ta.clear,
+    getValue: () => ta.value,
+    setValue: ta.setValue,
+    getSelection: ta.getSelection,
+  }))
+
+  // =========================================================================
+  // Rendering
+  // =========================================================================
+
+  // Hide hardware cursor when selection is active (cursor shown as part of selection rendering)
+  useCursor({
+    col: ta.cursorCol,
+    row: ta.visibleCursorRow,
+    visible: isActive && !disabled && !ta.selection,
+  })
+
+  const showPlaceholder = !ta.value && placeholder
+
+  const borderProps = borderStyleProp
+    ? {
+        borderStyle: borderStyleProp as any,
+        borderColor: isActive ? focusBorderColor : borderColorProp,
+        paddingX: 1 as const,
+      }
+    : {}
+
+  if (showPlaceholder) {
+    return (
+      <Box
+        focusable
+        testID={testID}
+        flexDirection="column"
+        height={height}
+        justifyContent="center"
+        alignItems="center"
+        {...borderProps}
+      >
+        <Text dimColor>{placeholder}</Text>
+      </Box>
+    )
+  }
+
+  return (
+    <Box focusable testID={testID} key={ta.scrollOffset} flexDirection="column" height={height} {...borderProps}>
+      {ta.visibleLines.map((wl, i) => {
+        const absoluteRow = ta.scrollOffset + i
+        const isCursorRow = absoluteRow === ta.cursorRow
+        const lineStart = wl.startOffset
+        const lineEnd = lineStart + wl.line.length
+
+        // Check if this line has any selection overlap
+        const hasSelectionOnLine = ta.selection && lineStart < ta.selection.end && lineEnd > ta.selection.start
+
+        if (disabled) {
+          return (
+            <Text key={absoluteRow} dimColor>
+              {wl.line || " "}
+            </Text>
+          )
+        }
+
+        if (hasSelectionOnLine) {
+          // Compute selection overlap on this line (in line-local coordinates)
+          const selStart = Math.max(0, ta.selection!.start - lineStart)
+          const selEnd = Math.min(wl.line.length, ta.selection!.end - lineStart)
+
+          const before = wl.line.slice(0, selStart)
+          const selected = wl.line.slice(selStart, selEnd)
+          const after = wl.line.slice(selEnd)
+
+          return (
+            <Text key={absoluteRow}>
+              {before}
+              <Text inverse>{selected || (selEnd === wl.line.length && isCursorRow ? " " : "")}</Text>
+              {after}
+            </Text>
+          )
+        }
+
+        if (!isCursorRow) {
+          return <Text key={absoluteRow}>{wl.line || " "}</Text>
+        }
+
+        const beforeCursor = wl.line.slice(0, ta.cursorCol)
+        const atCursor = wl.line[ta.cursorCol] ?? " "
+        const afterCursor = wl.line.slice(ta.cursorCol + 1)
+
+        // Active: plain text (real cursor handles it). Inactive: fake cursor.
+        const cursorEl = isActive ? (
+          <Text>{atCursor}</Text>
+        ) : cursorStyle === "block" ? (
+          <Text inverse>{atCursor}</Text>
+        ) : (
+          <Text underline>{atCursor}</Text>
+        )
+
+        return (
+          <Text key={absoluteRow}>
+            {beforeCursor}
+            {cursorEl}
+            {afterCursor}
+          </Text>
+        )
+      })}
+    </Box>
+  )
+})

package/src/components/TextInput.tsx

@@ -0,0 +1,240 @@
+/**
+ * TextInput Component
+ *
+ * Full readline-style single-line text input with kill ring, word movement, and
+ * all standard shortcuts. Built on useReadline hook.
+ *
+ * Usage:
+ * ```tsx
+ * const [value, setValue] = useState('')
+ * <TextInput
+ *   value={value}
+ *   onChange={setValue}
+ *   onSubmit={(val) => console.log('Submitted:', val)}
+ *   placeholder="Type here..."
+ * />
+ * ```
+ *
+ * Supported shortcuts:
+ * - Ctrl+A/E: Beginning/end of line
+ * - Ctrl+B/F, Left/Right: Move cursor
+ * - Alt+B/F: Move by word
+ * - Ctrl+W, Alt+Backspace: Delete word backwards (kill)
+ * - Alt+D: Delete word forwards (kill)
+ * - Ctrl+U/K: Delete to beginning/end (kill)
+ * - Ctrl+Y: Yank (paste)
+ * - Alt+Y: Cycle kill ring
+ * - Ctrl+T: Transpose characters
+ */
+import { useCallback, useImperativeHandle, forwardRef, useState, useEffect, useRef } from "react"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+import { useReadline } from "./useReadline"
+import { useFocusable } from "@silvery/react/hooks/useFocusable"
+import { useCursor } from "@silvery/react/hooks/useCursor"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TextInputProps {
+  /** Current value (controlled) */
+  value?: string
+  /** Initial value (uncontrolled) */
+  defaultValue?: string
+  /** Called when value changes */
+  onChange?: (value: string) => void
+  /** Called when Enter is pressed */
+  onSubmit?: (value: string) => void
+  /** Called on Ctrl+D with empty input */
+  onEOF?: () => void
+  /** Placeholder text when empty */
+  placeholder?: string
+  /** Whether input is focused/active (overrides focus system) */
+  isActive?: boolean
+  /** Prompt prefix (e.g., "$ " or "> ") */
+  prompt?: string
+  /** Prompt color */
+  promptColor?: string
+  /** Text color */
+  color?: string
+  /** Cursor style: 'block' (inverse) or 'underline' */
+  cursorStyle?: "block" | "underline"
+  /** Show underline below input */
+  showUnderline?: boolean
+  /** Underline width (default: 40) */
+  underlineWidth?: number
+  /** Mask character for passwords */
+  mask?: string
+  /** Border style (e.g., "round", "single") — wraps input in bordered Box */
+  borderStyle?: string
+  /** Border color when unfocused (default: "$border") */
+  borderColor?: string
+  /** Border color when focused (default: "$focusborder") */
+  focusBorderColor?: string
+  /** Test ID for focus system identification */
+  testID?: string
+}
+
+export interface TextInputHandle {
+  /** Clear the input */
+  clear: () => void
+  /** Get current value */
+  getValue: () => string
+  /** Set value programmatically */
+  setValue: (value: string) => void
+  /** Get kill ring contents */
+  getKillRing: () => string[]
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export const TextInput = forwardRef<TextInputHandle, TextInputProps>(function TextInput(
+  {
+    value: controlledValue,
+    defaultValue = "",
+    onChange,
+    onSubmit,
+    onEOF,
+    placeholder = "",
+    isActive: isActiveProp,
+    prompt = "",
+    promptColor = "$control",
+    color,
+    cursorStyle = "block",
+    showUnderline = false,
+    underlineWidth = 40,
+    mask,
+    borderStyle: borderStyleProp,
+    borderColor: borderColorProp = "$border",
+    focusBorderColor = "$focusborder",
+    testID,
+  },
+  ref,
+) {
+  // Focus system integration: prop overrides hook.
+  // When testID is set, the component participates in the focus tree and
+  // isActive derives from focus state. Without testID, default to true
+  // for backward compatibility.
+  const { focused } = useFocusable()
+  const isActive = isActiveProp ?? (testID ? focused : true)
+
+  // Track whether we're in controlled mode
+  const isControlled = controlledValue !== undefined
+
+  // Track value changes that originated from internal editing (keystroke → onChange).
+  // When the parent feeds back the same value via controlledValue, we skip
+  // readline.setValue() since readline already has the correct cursor position.
+  const internalChangeRef = useRef(false)
+
+  // Use readline hook
+  const readline = useReadline({
+    initialValue: isControlled ? (controlledValue ?? "") : defaultValue,
+    onChange: useCallback(
+      (newValue: string) => {
+        internalChangeRef.current = true
+        onChange?.(newValue)
+      },
+      [onChange],
+    ),
+    isActive,
+    handleEnter: !!onSubmit,
+    onSubmit,
+    onEOF,
+  })
+
+  // Sync controlled value to readline — only for external changes.
+  // Internal changes (from editing) already have correct cursor position.
+  const [lastControlledValue, setLastControlledValue] = useState(controlledValue)
+  useEffect(() => {
+    if (isControlled && controlledValue !== lastControlledValue) {
+      if (internalChangeRef.current) {
+        // Change originated from our own editing — readline already has correct state
+        internalChangeRef.current = false
+      } else {
+        // External change — sync readline (cursor goes to end)
+        readline.setValue(controlledValue ?? "")
+      }
+      setLastControlledValue(controlledValue)
+    }
+  }, [isControlled, controlledValue, lastControlledValue, readline])
+
+  // Handle Enter separately for onSubmit
+  const { value, cursor, clear, setValue, killRing } = readline
+
+  // Imperative handle for parent control
+  useImperativeHandle(ref, () => ({
+    clear,
+    getValue: () => value,
+    setValue,
+    getKillRing: () => killRing,
+  }))
+
+  // Compute display value (with optional mask)
+  const displayValue = mask ? mask.repeat(value.length) : value
+  const displayBeforeCursor = displayValue.slice(0, cursor)
+  const displayAtCursor = displayValue[cursor] ?? " "
+  const displayAfterCursor = displayValue.slice(cursor + 1)
+  const showPlaceholder = !value && placeholder
+
+  // Always show visual cursor (inverse/underline). When active, the hardware
+  // cursor is also positioned via useCursor() for terminal blink support.
+  const cursorEl =
+    cursorStyle === "underline" ? <Text underline>{displayAtCursor}</Text> : <Text inverse>{displayAtCursor}</Text>
+  useCursor({
+    col: prompt.length + displayBeforeCursor.length,
+    row: 0,
+    visible: isActive,
+  })
+
+  const inputContent = (
+    <Text color={color}>
+      {prompt && <Text color={promptColor}>{prompt}</Text>}
+      {showPlaceholder ? (
+        <>
+          {cursorStyle === "underline" ? (
+            <Text underline dimColor>
+              {placeholder[0]}
+            </Text>
+          ) : (
+            <Text inverse dimColor>
+              {placeholder[0]}
+            </Text>
+          )}
+          <Text dimColor>{placeholder.slice(1)}</Text>
+        </>
+      ) : (
+        <>
+          <Text>{displayBeforeCursor}</Text>
+          {cursorEl}
+          <Text>{displayAfterCursor}</Text>
+        </>
+      )}
+    </Text>
+  )
+
+  if (borderStyleProp) {
+    return (
+      <Box
+        focusable
+        testID={testID}
+        flexDirection="column"
+        borderStyle={borderStyleProp as any}
+        borderColor={isActive ? focusBorderColor : borderColorProp}
+        paddingX={1}
+      >
+        {inputContent}
+        {showUnderline && <Text dimColor>{"─".repeat(underlineWidth)}</Text>}
+      </Box>
+    )
+  }
+
+  return (
+    <Box focusable testID={testID} flexDirection="column">
+      {inputContent}
+      {showUnderline && <Text dimColor>{"─".repeat(underlineWidth)}</Text>}
+    </Box>
+  )
+})