@silvery/ui 0.3.0

package/src/components/VirtualView.tsx

@@ -0,0 +1,221 @@
+/**
+ * VirtualView - App-managed scrolling within a Screen rectangle.
+ *
+ * A scrollable area where items mount/unmount based on scroll position,
+ * managed entirely by the app. Uses the shared useVirtualizer() engine.
+ *
+ * Unlike ScrollbackView (which uses native terminal scrollback), VirtualView
+ * keeps everything in the React tree. Items are simply unmounted when they
+ * scroll out of the viewport and remounted when they scroll back in.
+ *
+ * Trade-offs vs ScrollbackView:
+ * - Mouse events work on scrolled-off items (if you scroll back)
+ * - App controls scroll position (no snap-to-bottom issue)
+ * - Text selection requires Shift+drag (mouse tracking active)
+ * - Memory lives in the React tree, not the terminal buffer
+ *
+ * @example
+ * ```tsx
+ * <Screen>
+ *   <Header />
+ *   <VirtualView
+ *     items={logs}
+ *     height={20}
+ *     renderItem={(item, index) => <LogEntry key={item.id} data={item} />}
+ *     estimateHeight={() => 3}
+ *   />
+ *   <StatusBar />
+ * </Screen>
+ * ```
+ */
+
+import React, { forwardRef, useImperativeHandle } from "react"
+import { useVirtualizer } from "@silvery/react/hooks/useVirtualizer"
+import { Box } from "@silvery/react/components/Box"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface VirtualViewProps<T> {
+  /** Array of items to render */
+  items: T[]
+
+  /** Height of the viewport in rows */
+  height: number
+
+  /** Estimated height of each item in rows (fixed or per-index function). Default: 1 */
+  estimateHeight?: number | ((index: number) => number)
+
+  /** Render function for each item */
+  renderItem: (item: T, index: number) => React.ReactNode
+
+  /** Index to scroll to (declarative). When undefined, scroll state freezes. */
+  scrollTo?: number
+
+  /** Extra items to render beyond viewport for smooth scrolling. Default: 5 */
+  overscan?: number
+
+  /** Maximum items to render at once. Default: 100 */
+  maxRendered?: number
+
+  /** Padding from edge before scrolling (in items). Default: 2 */
+  scrollPadding?: number
+
+  /** Show overflow indicators (▲N/▼N). Default: false */
+  overflowIndicator?: boolean
+
+  /** Optional key extractor (defaults to index) */
+  keyExtractor?: (item: T, index: number) => string | number
+
+  /** Width of the viewport (optional, uses parent width if not specified) */
+  width?: number
+
+  /** Gap between items in rows. Default: 0 */
+  gap?: number
+
+  /** Render separator between items (alternative to gap) */
+  renderSeparator?: () => React.ReactNode
+
+  /** Mouse wheel handler for scrolling */
+  onWheel?: (event: { deltaY: number }) => void
+
+  /** Called when the visible range reaches near the end of the list (infinite scroll). */
+  onEndReached?: () => void
+  /** How many items from the end to trigger onEndReached. Default: 5 */
+  onEndReachedThreshold?: number
+
+  /** Content rendered after all items inside the scroll container (e.g., hidden count indicator) */
+  listFooter?: React.ReactNode
+}
+
+export interface VirtualViewHandle {
+  /** Imperatively scroll to a specific item index */
+  scrollToItem(index: number): void
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_ESTIMATE_HEIGHT = 1
+const DEFAULT_OVERSCAN = 5
+const DEFAULT_MAX_RENDERED = 100
+const DEFAULT_SCROLL_PADDING = 2
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * App-managed scrollable view with virtualization.
+ *
+ * Items mount/unmount based on scroll position within a fixed-height viewport.
+ * Scroll state management:
+ * - When scrollTo is defined: actively track and scroll to that index
+ * - When scrollTo is undefined: freeze scroll state (critical for multi-column layouts)
+ */
+function VirtualViewInner<T>(
+  {
+    items,
+    height,
+    estimateHeight = DEFAULT_ESTIMATE_HEIGHT,
+    renderItem,
+    scrollTo,
+    overscan = DEFAULT_OVERSCAN,
+    maxRendered = DEFAULT_MAX_RENDERED,
+    scrollPadding = DEFAULT_SCROLL_PADDING,
+    overflowIndicator,
+    keyExtractor,
+    width,
+    gap = 0,
+    renderSeparator,
+    onWheel,
+    onEndReached,
+    onEndReachedThreshold,
+    listFooter,
+  }: VirtualViewProps<T>,
+  ref: React.ForwardedRef<VirtualViewHandle>,
+): React.ReactElement {
+  // Convert item-based estimateHeight to index-based for useVirtualizer
+  const indexEstimate = typeof estimateHeight === "function" ? estimateHeight : estimateHeight
+
+  const { range, leadingHeight, trailingHeight, scrollOffset, scrollToItem } = useVirtualizer({
+    count: items.length,
+    estimateHeight: indexEstimate,
+    viewportHeight: height,
+    scrollTo,
+    scrollPadding,
+    overscan,
+    maxRendered,
+    gap,
+    getItemKey: keyExtractor ? (index) => keyExtractor(items[index]!, index) : undefined,
+    onEndReached,
+    onEndReachedThreshold,
+  })
+
+  // Expose scrollToItem method via ref
+  useImperativeHandle(ref, () => ({ scrollToItem }), [scrollToItem])
+
+  // Empty state
+  if (items.length === 0) {
+    return (
+      <Box flexDirection="column" height={height} width={width}>
+        {/* Empty - nothing to render */}
+      </Box>
+    )
+  }
+
+  // Get the slice of items to render
+  const { startIndex, endIndex } = range
+  const visibleItems = items.slice(startIndex, endIndex)
+
+  // Calculate scrollTo index for silvery Box overflow="scroll"
+  const hasTopPlaceholder = leadingHeight > 0
+  const currentSelectedIndex = scrollTo !== undefined ? Math.max(0, Math.min(scrollTo, items.length - 1)) : scrollOffset
+  const selectedIndexInSlice = currentSelectedIndex - startIndex
+  const isSelectedInSlice = selectedIndexInSlice >= 0 && selectedIndexInSlice < visibleItems.length
+  const scrollToIndex = hasTopPlaceholder ? selectedIndexInSlice + 1 : selectedIndexInSlice
+  const boxScrollTo = isSelectedInSlice ? Math.max(0, scrollToIndex) : undefined
+
+  return (
+    <Box
+      flexDirection="column"
+      height={height}
+      width={width}
+      overflow="scroll"
+      scrollTo={boxScrollTo}
+      overflowIndicator={overflowIndicator}
+      onWheel={onWheel}
+    >
+      {/* Leading placeholder for virtual height */}
+      {leadingHeight > 0 && <Box height={leadingHeight} flexShrink={0} />}
+
+      {/* Render visible items */}
+      {visibleItems.map((item, i) => {
+        const originalIndex = startIndex + i
+        const key = keyExtractor ? keyExtractor(item, originalIndex) : originalIndex
+        const isLast = i === visibleItems.length - 1
+
+        return (
+          <React.Fragment key={key}>
+            {renderItem(item, originalIndex)}
+            {!isLast && renderSeparator && renderSeparator()}
+            {!isLast && gap > 0 && !renderSeparator && <Box height={gap} flexShrink={0} />}
+          </React.Fragment>
+        )
+      })}
+
+      {/* Footer content (e.g., filter hidden count) */}
+      {listFooter}
+
+      {/* Trailing placeholder for virtual height */}
+      {trailingHeight > 0 && <Box height={trailingHeight} flexShrink={0} />}
+    </Box>
+  )
+}
+
+// Export with forwardRef - use type assertion for generic component
+export const VirtualView = forwardRef(VirtualViewInner) as <T>(
+  props: VirtualViewProps<T> & { ref?: React.ForwardedRef<VirtualViewHandle> },
+) => React.ReactElement

package/src/components/useReadline.ts

@@ -0,0 +1,213 @@
+/**
+ * useReadline Hook
+ *
+ * This hook lives in components/ because it's tightly coupled to TextInput.
+ * It manages readline state (cursor position, history, kill ring) that TextInput renders.
+ *
+ * Full readline-style line editing for terminal text input.
+ * Supports cursor movement, word operations, kill ring, and all standard shortcuts.
+ *
+ * Shortcuts:
+ * - Ctrl+A: Move to beginning of line
+ * - Ctrl+E: Move to end of line
+ * - Ctrl+B / Left: Move cursor left
+ * - Ctrl+F / Right: Move cursor right
+ * - Alt+B: Move cursor back one word
+ * - Alt+F: Move cursor forward one word
+ * - Ctrl+W / Alt+Backspace: Delete word backwards (adds to kill ring)
+ * - Alt+D: Delete word forwards (adds to kill ring)
+ * - Ctrl+U: Delete to beginning (adds to kill ring)
+ * - Ctrl+K: Delete to end (adds to kill ring)
+ * - Ctrl+Y: Yank (paste from kill ring)
+ * - Alt+Y: Cycle through kill ring (after Ctrl+Y)
+ * - Ctrl+T: Transpose characters
+ * - Ctrl+H / Backspace: Delete char before cursor
+ * - Ctrl+D / Delete: Delete char at cursor (or exit if empty)
+ *
+ * Note: Alt key detection requires terminal support. Some terminals send
+ * ESC followed by the key instead of a proper alt modifier.
+ */
+import { useCallback, useRef, useState } from "react"
+import { useInput } from "@silvery/react/hooks"
+import { killRing, addToKillRing, handleReadlineKey, type YankState } from "@silvery/react/hooks/readline-ops"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ReadlineState {
+  /** Current text value */
+  value: string
+  /** Cursor position (0 = before first char, value.length = after last char) */
+  cursor: number
+}
+
+export interface UseReadlineOptions {
+  /** Initial value */
+  initialValue?: string
+  /** Called when value changes */
+  onChange?: (value: string) => void
+  /** Whether input is active */
+  isActive?: boolean
+  /** Handle Enter key (default: false - let parent handle) */
+  handleEnter?: boolean
+  /** Called when Enter is pressed (requires handleEnter: true) */
+  onSubmit?: (value: string) => void
+  /** Handle Escape key (default: false - let parent handle) */
+  handleEscape?: boolean
+  /** Handle Up/Down arrows (default: false - let parent handle for history) */
+  handleVerticalArrows?: boolean
+  /** Called on Ctrl+D with empty input (default: undefined) */
+  onEOF?: () => void
+}
+
+export interface UseReadlineResult {
+  /** Current text value */
+  value: string
+  /** Cursor position */
+  cursor: number
+  /** Text before cursor (for rendering) */
+  beforeCursor: string
+  /** Text after cursor (for rendering) */
+  afterCursor: string
+  /** Clear the input */
+  clear: () => void
+  /** Set value programmatically (cursor moves to end) */
+  setValue: (value: string) => void
+  /** Set both value and cursor position */
+  setValueWithCursor: (value: string, cursor: number) => void
+  /** Kill ring contents (for debugging/display) */
+  killRing: string[]
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+export function useReadline({
+  initialValue = "",
+  onChange,
+  isActive = true,
+  handleEnter = false,
+  handleEscape = false,
+  handleVerticalArrows = false,
+  onEOF,
+  onSubmit,
+}: UseReadlineOptions = {}): UseReadlineResult {
+  const [state, setState] = useState<ReadlineState>({
+    value: initialValue,
+    cursor: initialValue.length,
+  })
+
+  // Mutable ref for synchronous reads in the event handler.
+  // Without this, rapid keypresses between React renders all read the same
+  // stale closure state and overwrite each other.
+  const stateRef = useRef<ReadlineState>({ value: initialValue, cursor: initialValue.length })
+  stateRef.current = state
+
+  const yankStateRef = useRef<YankState | null>(null)
+
+  /** Apply a ReadlineKeyResult to state */
+  const applyResult = useCallback(
+    (result: { value: string; cursor: number; yankState: YankState | null }, prevValue: string) => {
+      yankStateRef.current = result.yankState
+      if (result.value === prevValue && result.cursor === stateRef.current.cursor) return
+      const next = { value: result.value, cursor: result.cursor }
+      stateRef.current = next
+      setState(next)
+      if (result.value !== prevValue) onChange?.(result.value)
+    },
+    [onChange],
+  )
+
+  const clear = useCallback(() => {
+    const next = { value: "", cursor: 0 }
+    stateRef.current = next
+    setState(next)
+    onChange?.("")
+    yankStateRef.current = null
+  }, [onChange])
+
+  const setValue = useCallback(
+    (value: string) => {
+      const next = { value, cursor: value.length }
+      stateRef.current = next
+      setState(next)
+      onChange?.(value)
+      yankStateRef.current = null
+    },
+    [onChange],
+  )
+
+  const setValueWithCursor = useCallback(
+    (value: string, cursor: number) => {
+      const next = { value, cursor: Math.max(0, Math.min(cursor, value.length)) }
+      stateRef.current = next
+      setState(next)
+      onChange?.(value)
+      yankStateRef.current = null
+    },
+    [onChange],
+  )
+
+  useInput(
+    (input, key) => {
+      const { value, cursor } = stateRef.current
+
+      // Let parent handle Enter/Escape/vertical arrows unless explicitly enabled
+      if (key.return && !handleEnter) return
+      if (key.return && handleEnter) {
+        onSubmit?.(value)
+        return
+      }
+      if (key.escape && !handleEscape) return
+      if ((key.upArrow || key.downArrow) && !handleVerticalArrows) return
+
+      // Single-line specific: Ctrl+D on empty input = EOF
+      if (key.ctrl && input === "d" && value.length === 0) {
+        onEOF?.()
+        return
+      }
+
+      // Single-line specific: Ctrl+A/E move to beginning/end of entire text
+      if (key.ctrl && input === "a") {
+        applyResult({ value, cursor: 0, yankState: null }, value)
+        return
+      }
+      if (key.ctrl && input === "e") {
+        applyResult({ value, cursor: value.length, yankState: null }, value)
+        return
+      }
+
+      // Single-line specific: Ctrl+U/K kill to beginning/end of entire text
+      if (key.ctrl && input === "u") {
+        if (cursor === 0) return
+        addToKillRing(value.slice(0, cursor))
+        applyResult({ value: value.slice(cursor), cursor: 0, yankState: null }, value)
+        return
+      }
+      if (key.ctrl && input === "k") {
+        if (cursor >= value.length) return
+        addToKillRing(value.slice(cursor))
+        applyResult({ value: value.slice(0, cursor), cursor, yankState: null }, value)
+        return
+      }
+
+      // Shared readline operations (cursor movement, word ops, kill ring, yank, etc.)
+      const result = handleReadlineKey(input, key, value, cursor, yankStateRef.current)
+      if (result) applyResult(result, value)
+    },
+    { isActive },
+  )
+
+  return {
+    value: state.value,
+    cursor: state.cursor,
+    beforeCursor: state.value.slice(0, state.cursor),
+    afterCursor: state.value.slice(state.cursor),
+    clear,
+    setValue,
+    setValueWithCursor,
+    killRing: [...killRing],
+  }
+}