@silvery/ui 0.3.0

package/src/components.ts

@@ -0,0 +1,133 @@
+/**
+ * silvery/components -- Rich UI components beyond Ink's built-in set.
+ *
+ * ```tsx
+ * import { VirtualList, Table, SelectList, TextInput, Spinner } from '@silvery/ui/components'
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// Layout Components
+// =============================================================================
+
+export { VirtualList } from "./components/VirtualList"
+export type { VirtualListProps, VirtualListHandle } from "./components/VirtualList"
+
+export { HorizontalVirtualList } from "./components/HorizontalVirtualList"
+export type { HorizontalVirtualListProps, HorizontalVirtualListHandle } from "./components/HorizontalVirtualList"
+
+export { SplitView } from "./components/SplitView"
+export type { SplitViewProps } from "./components/SplitView"
+export type { LayoutNode as SplitLayoutNode } from "@silvery/term/pane-manager"
+export {
+  createLeaf,
+  splitPane,
+  removePane,
+  getPaneIds,
+  findAdjacentPane,
+  resizeSplit,
+  swapPanes,
+  getTabOrder as getSplitTabOrder,
+} from "@silvery/term/pane-manager"
+
+export { Fill } from "@silvery/react/components/Fill"
+export type { FillProps } from "@silvery/react/components/Fill"
+
+export { Link } from "@silvery/react/components/Link"
+export type { LinkProps } from "@silvery/react/components/Link"
+
+export { ErrorBoundary } from "./components/ErrorBoundary"
+export type { ErrorBoundaryProps } from "./components/ErrorBoundary"
+
+export { Console } from "./components/Console"
+
+// =============================================================================
+// Input Components
+// =============================================================================
+
+export { TextInput } from "./components/TextInput"
+export type { TextInputProps, TextInputHandle } from "./components/TextInput"
+
+export { TextArea } from "./components/TextArea"
+export type { TextAreaProps, TextAreaHandle, TextAreaSelection } from "./components/TextArea"
+
+export { useTextArea, clampScroll } from "./components/useTextArea"
+export type { UseTextAreaOptions, UseTextAreaResult } from "./components/useTextArea"
+
+export { EditContextDisplay } from "./components/EditContextDisplay"
+export type { EditContextDisplayProps } from "./components/EditContextDisplay"
+
+// Display Components
+export { CursorLine } from "./components/CursorLine"
+export type { CursorLineProps } from "./components/CursorLine"
+
+// Dialog Components
+export { ModalDialog, formatTitleWithHotkey } from "./components/ModalDialog"
+export type { ModalDialogProps } from "./components/ModalDialog"
+
+export { PickerDialog } from "./components/PickerDialog"
+export type { PickerDialogProps } from "./components/PickerDialog"
+
+// Focusable Controls
+export { Toggle } from "./components/Toggle"
+export type { ToggleProps } from "./components/Toggle"
+
+export { Button } from "./components/Button"
+export type { ButtonProps } from "./components/Button"
+
+export { useReadline } from "./components/useReadline"
+export type { ReadlineState, UseReadlineOptions, UseReadlineResult } from "./components/useReadline"
+
+// =============================================================================
+// Widget Components
+// =============================================================================
+
+export { Spinner } from "./components/Spinner"
+export type { SpinnerProps } from "./components/Spinner"
+
+export { ProgressBar } from "./components/ProgressBar"
+export type { ProgressBarProps } from "./components/ProgressBar"
+
+export { SelectList } from "./components/SelectList"
+export type { SelectListProps, SelectOption } from "./components/SelectList"
+
+export { Table } from "./components/Table"
+export type { TableProps, TableColumn } from "./components/Table"
+
+export { Badge } from "./components/Badge"
+export type { BadgeProps } from "./components/Badge"
+
+export { Divider } from "./components/Divider"
+export type { DividerProps } from "./components/Divider"
+
+// =============================================================================
+// Position Registry (2D Grid Virtualization)
+// =============================================================================
+
+export {
+  PositionRegistryProvider,
+  usePositionRegistry,
+  createPositionRegistry,
+} from "@silvery/react/hooks/usePositionRegistry"
+export type { PositionRegistry, ScreenRect } from "@silvery/react/hooks/usePositionRegistry"
+export { useGridPosition } from "@silvery/react/hooks/useGridPosition"
+export { GridCell } from "./components/GridCell"
+export type { GridCellProps } from "./components/GridCell"
+
+// =============================================================================
+// Scroll Utilities
+// =============================================================================
+
+export { calcEdgeBasedScrollOffset } from "@silvery/term/scroll-utils"
+
+export {
+  setScrollRegion,
+  resetScrollRegion,
+  scrollUp,
+  scrollDown,
+  moveCursor,
+  supportsScrollRegions,
+} from "@silvery/term/scroll-region"
+export type { ScrollRegionConfig } from "@silvery/term/scroll-region"

package/src/display/Table.tsx

@@ -0,0 +1,179 @@
+/**
+ * React Table component for silvery/Ink TUI apps
+ */
+
+import React from "react"
+import type { TableProps, TableColumn } from "../types.js"
+
+/**
+ * Unicode box drawing characters for borders
+ */
+const BOX = {
+  topLeft: "┌",
+  topRight: "┐",
+  bottomLeft: "└",
+  bottomRight: "┘",
+  horizontal: "─",
+  vertical: "│",
+  leftT: "├",
+  rightT: "┤",
+  topT: "┬",
+  bottomT: "┴",
+  cross: "┼",
+} as const
+
+/**
+ * Data grid display component for React TUI apps
+ *
+ * @example
+ * ```tsx
+ * import { Table } from "@silvery/ui/display";
+ *
+ * const columns = [
+ *   { key: "name", header: "Name", width: 20 },
+ *   { key: "status", header: "Status", width: 10, align: "center" },
+ *   { key: "count", header: "Count", width: 8, align: "right" },
+ * ];
+ *
+ * const data = [
+ *   { name: "Item 1", status: "active", count: 42 },
+ *   { name: "Item 2", status: "pending", count: 7 },
+ * ];
+ *
+ * function DataView() {
+ *   return <Table columns={columns} data={data} border />;
+ * }
+ * ```
+ */
+export function Table({ columns, data, border = false }: TableProps): React.ReactElement {
+  // Calculate effective column widths
+  const effectiveColumns = calculateColumnWidths(columns, data)
+
+  const lines: string[] = []
+
+  if (border) {
+    // Top border
+    lines.push(buildBorderLine(effectiveColumns, "top"))
+  }
+
+  // Header row
+  lines.push(buildDataRow(effectiveColumns, getHeaderRow(effectiveColumns), border))
+
+  if (border) {
+    // Separator after header
+    lines.push(buildBorderLine(effectiveColumns, "middle"))
+  }
+
+  // Data rows
+  for (const row of data) {
+    lines.push(buildDataRow(effectiveColumns, row, border))
+  }
+
+  if (border) {
+    // Bottom border
+    lines.push(buildBorderLine(effectiveColumns, "bottom"))
+  }
+
+  return (
+    <span data-table data-border={border}>
+      {lines.join("\n")}
+    </span>
+  )
+}
+
+/**
+ * Calculate effective column widths based on content if not specified
+ */
+function calculateColumnWidths(
+  columns: TableColumn[],
+  data: Array<Record<string, unknown>>,
+): Array<TableColumn & { effectiveWidth: number }> {
+  return columns.map((col) => {
+    if (col.width !== undefined) {
+      return { ...col, effectiveWidth: col.width }
+    }
+
+    // Calculate width from content
+    let maxWidth = col.header.length
+
+    for (const row of data) {
+      const value = String(row[col.key] ?? "")
+      maxWidth = Math.max(maxWidth, value.length)
+    }
+
+    return { ...col, effectiveWidth: maxWidth }
+  })
+}
+
+/**
+ * Create header row object from columns
+ */
+function getHeaderRow(columns: Array<TableColumn & { effectiveWidth: number }>): Record<string, unknown> {
+  const row: Record<string, unknown> = {}
+  for (const col of columns) {
+    row[col.key] = col.header
+  }
+  return row
+}
+
+/**
+ * Build a border line (top, middle, or bottom)
+ */
+function buildBorderLine(
+  columns: Array<TableColumn & { effectiveWidth: number }>,
+  position: "top" | "middle" | "bottom",
+): string {
+  const left = position === "top" ? BOX.topLeft : position === "bottom" ? BOX.bottomLeft : BOX.leftT
+  const right = position === "top" ? BOX.topRight : position === "bottom" ? BOX.bottomRight : BOX.rightT
+  const join = position === "top" ? BOX.topT : position === "bottom" ? BOX.bottomT : BOX.cross
+
+  const segments = columns.map((col) => BOX.horizontal.repeat(col.effectiveWidth + 2))
+
+  return left + segments.join(join) + right
+}
+
+/**
+ * Build a data row (header or content)
+ */
+function buildDataRow(
+  columns: Array<TableColumn & { effectiveWidth: number }>,
+  row: Record<string, unknown>,
+  border: boolean,
+): string {
+  const cells = columns.map((col) => {
+    const value = String(row[col.key] ?? "")
+    return formatCell(value, col.effectiveWidth, col.align ?? "left")
+  })
+
+  if (border) {
+    return BOX.vertical + " " + cells.join(" " + BOX.vertical + " ") + " " + BOX.vertical
+  }
+
+  return cells.join("  ")
+}
+
+/**
+ * Format a cell value with alignment and truncation
+ */
+function formatCell(value: string, width: number, align: "left" | "center" | "right"): string {
+  // Truncate if too long
+  if (value.length > width) {
+    return value.slice(0, width - 1) + "…"
+  }
+
+  // Pad according to alignment
+  const padding = width - value.length
+
+  switch (align) {
+    case "right":
+      return " ".repeat(padding) + value
+    case "center": {
+      const leftPad = Math.floor(padding / 2)
+      const rightPad = padding - leftPad
+      return " ".repeat(leftPad) + value + " ".repeat(rightPad)
+    }
+    case "left":
+    default:
+      return value + " ".repeat(padding)
+  }
+}

package/src/display/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Display components for silvery/Ink TUI apps
+ *
+ * These are read-only display components (no input handling).
+ *
+ * @example
+ * ```tsx
+ * import { Table } from "@silvery/ui/display";
+ * ```
+ */
+
+export { Table } from "./Table"
+export type { TableColumn, TableProps } from "../types.js"

package/src/hooks/useTea.ts

@@ -0,0 +1,133 @@
+/**
+ * useTea — React hook for TEA (The Elm Architecture) state machines.
+ *
+ * Like useReducer, but the reducer can return [state, effects].
+ * Effects are plain data objects executed by runners. Built-in timer
+ * runners handle delay/interval/cancel. All timers auto-cleanup on unmount.
+ *
+ * @example
+ * ```tsx
+ * import { useTea } from "silvery"
+ * import { fx } from "@silvery/tea/effects"
+ *
+ * type State = { count: number; running: boolean }
+ * type Msg = { type: "start" } | { type: "tick" } | { type: "stop" }
+ *
+ * function update(state: State, msg: Msg) {
+ *   switch (msg.type) {
+ *     case "start":
+ *       return [{ ...state, running: true }, [fx.interval(100, { type: "tick" }, "counter")]]
+ *     case "tick":
+ *       return { ...state, count: state.count + 1 }
+ *     case "stop":
+ *       return [{ ...state, running: false }, [fx.cancel("counter")]]
+ *   }
+ * }
+ *
+ * function Counter() {
+ *   const [state, send] = useTea({ count: 0, running: false }, update)
+ *   return <Text>Count: {state.count}</Text>
+ * }
+ * ```
+ */
+
+import { useCallback, useEffect, useRef, useReducer } from "react"
+import type { EffectLike, EffectRunners, TeaResult } from "@silvery/tea/tea"
+import { collect } from "@silvery/tea/tea"
+import { createTimerRunners, type TimerEffect } from "@silvery/tea/effects"
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+/**
+ * TEA state machine hook with automatic timer management.
+ *
+ * The update function can return plain state (no effects) or `[state, effects]`.
+ * Timer effects (delay, interval, cancel) are handled automatically.
+ * Additional effect runners can be provided for custom effects.
+ *
+ * All timers are cleaned up automatically on unmount.
+ *
+ * @param initialState - Initial state value
+ * @param update - Pure update function: `(state, msg) => state | [state, effects]`
+ * @param customRunners - Optional additional effect runners for non-timer effects
+ * @returns `[state, send]` tuple — send dispatches a message through the update function
+ */
+export function useTea<S, Msg, E extends EffectLike = TimerEffect<Msg>>(
+  initialState: S | (() => S),
+  update: (state: S, msg: Msg) => TeaResult<S, E>,
+  customRunners?: EffectRunners<E, Msg>,
+): [S, (msg: Msg) => void] {
+  // Create timer runners once (stable across renders)
+  const timerRef = useRef<ReturnType<typeof createTimerRunners<Msg>> | null>(null)
+  if (timerRef.current === null) {
+    timerRef.current = createTimerRunners<Msg>()
+  }
+  const { runners: timerRunners, cleanup } = timerRef.current
+
+  // Keep custom runners ref-stable
+  const customRunnersRef = useRef(customRunners)
+  customRunnersRef.current = customRunners
+
+  // Pending effects queue — effects from the reducer can't be executed
+  // during render, so we queue them and execute in a useEffect.
+  const pendingEffectsRef = useRef<E[]>([])
+
+  // Use React's useReducer for state — it integrates with React's scheduler
+  const [state, reactDispatch] = useReducer(
+    (prevState: S, msg: Msg): S => {
+      const result = update(prevState, msg)
+      const [newState, effects] = collect(result)
+      if (effects.length > 0) {
+        pendingEffectsRef.current.push(...effects)
+      }
+      return newState
+    },
+    undefined,
+    () => (typeof initialState === "function" ? (initialState as () => S)() : initialState),
+  )
+
+  // Execute effects outside of render (React rules)
+  const sendRef = useRef<(msg: Msg) => void>(() => {})
+
+  const executeEffects = useCallback(() => {
+    if (pendingEffectsRef.current.length === 0) return
+    const effects = pendingEffectsRef.current.splice(0)
+    for (const effect of effects) {
+      // Try timer runners first
+      const timerRunner = timerRunners[effect.type as keyof typeof timerRunners]
+      if (timerRunner) {
+        ;(timerRunner as (e: any, d: (msg: Msg) => void) => void)(effect, sendRef.current)
+        continue
+      }
+      // Try custom runners
+      const customRunner = customRunnersRef.current?.[effect.type as E["type"]]
+      if (customRunner) {
+        ;(customRunner as (e: any, d: (msg: Msg) => void) => void)(effect, sendRef.current)
+      }
+    }
+  }, [timerRunners])
+
+  // The send function: dispatch to React, then execute effects
+  const send = useCallback(
+    (msg: Msg) => {
+      reactDispatch(msg)
+      // Effects are queued by the reducer — execute them after React processes the update.
+      // We use queueMicrotask to ensure effects run after the reducer but before the next paint.
+      queueMicrotask(executeEffects)
+    },
+    [reactDispatch, executeEffects],
+  )
+  sendRef.current = send
+
+  // Execute any effects from the initial render
+  useEffect(() => {
+    executeEffects()
+  }, [executeEffects])
+
+  // Cleanup all timers on unmount
+  useEffect(() => cleanup, [cleanup])
+
+  return [state, send]
+}

package/src/image/Image.tsx

@@ -0,0 +1,187 @@
+/**
+ * Image Component
+ *
+ * Renders bitmap images in supported terminals using the Kitty graphics
+ * protocol (primary) or Sixel (fallback). When neither is supported,
+ * displays a text placeholder.
+ *
+ * Since terminal images are escape-sequence-based and don't fit the cell
+ * buffer model, the component reserves visual space with a Box of the
+ * requested dimensions and uses `useEffect` to write image data directly
+ * to stdout after render.
+ *
+ * @example
+ * ```tsx
+ * import { readFileSync } from "fs"
+ * import { Image } from "@silvery/react"
+ *
+ * const png = readFileSync("photo.png")
+ * <Image src={png} width={40} height={20} />
+ *
+ * // With file path
+ * <Image src="/path/to/image.png" width={40} height={20} />
+ *
+ * // Auto-detect protocol, fall back to text
+ * <Image src={png} width={40} height={20} fallback="[photo]" />
+ * ```
+ */
+
+import { readFileSync } from "node:fs"
+import { type JSX, useContext, useEffect, useMemo, useRef } from "react"
+import { StdoutContext } from "@silvery/react/context"
+import { useContentRect } from "@silvery/react/hooks/useLayout"
+import { encodeKittyImage, isKittyGraphicsSupported, deleteKittyImage } from "./kitty-graphics"
+import { isSixelSupported } from "./sixel-encoder"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ImageProtocol = "kitty" | "sixel" | "auto"
+
+export interface ImageProps {
+  /** PNG image data (Buffer) or file path (string) to a PNG file */
+  src: Buffer | string
+  /** Width in terminal columns. If omitted, uses available width from layout. */
+  width?: number
+  /** Height in terminal rows. If omitted, defaults to half the width (rough aspect ratio). */
+  height?: number
+  /** Text to display when image rendering is not supported. Default: "[image]" */
+  fallback?: string
+  /** Which protocol to use. Default: "auto" (tries Kitty, then Sixel, then fallback) */
+  protocol?: ImageProtocol
+}
+
+// ============================================================================
+// Protocol Detection
+// ============================================================================
+
+/**
+ * Determine the best available image protocol.
+ * Returns null if no image protocol is available.
+ */
+function detectProtocol(preferred: ImageProtocol): "kitty" | "sixel" | null {
+  if (preferred === "kitty") {
+    return isKittyGraphicsSupported() ? "kitty" : null
+  }
+  if (preferred === "sixel") {
+    return isSixelSupported() ? "sixel" : null
+  }
+
+  // Auto-detect: prefer Kitty, fall back to Sixel
+  if (isKittyGraphicsSupported()) return "kitty"
+  if (isSixelSupported()) return "sixel"
+  return null
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/** Incrementing image ID counter for Kitty protocol */
+let nextImageId = 1
+
+/**
+ * Renders a bitmap image in the terminal.
+ *
+ * The component operates in two phases:
+ * 1. **Layout phase**: Renders a Box that reserves the visual space
+ *    (filled with spaces so the cell buffer has the right dimensions).
+ * 2. **Effect phase**: After render, writes the image escape sequence
+ *    directly to stdout, positioned over the reserved space.
+ *
+ * When image protocols are not available, the fallback text is shown instead.
+ */
+export function Image({
+  src,
+  width: requestedWidth,
+  height: requestedHeight,
+  fallback = "[image]",
+  protocol: preferredProtocol = "auto",
+}: ImageProps): JSX.Element {
+  const contentRect = useContentRect()
+  const stdoutCtx = useContext(StdoutContext)
+  const imageIdRef = useRef<number | null>(null)
+
+  // Resolve image data
+  const pngData = useMemo(() => {
+    if (Buffer.isBuffer(src)) return src
+    // String path — read file synchronously (during render is fine for a path)
+    try {
+      return readFileSync(src)
+    } catch {
+      return null
+    }
+  }, [src])
+
+  // Determine effective dimensions
+  const effectiveWidth = requestedWidth ?? contentRect.width
+  const effectiveHeight = requestedHeight ?? Math.max(1, Math.floor(effectiveWidth / 2))
+
+  // Detect protocol support
+  const activeProtocol = useMemo(() => detectProtocol(preferredProtocol), [preferredProtocol])
+
+  // Assign a stable image ID for Kitty (for cleanup on unmount)
+  if (activeProtocol === "kitty" && imageIdRef.current == null) {
+    imageIdRef.current = nextImageId++
+  }
+
+  // Write image escape sequences after render
+  useEffect(() => {
+    if (!pngData || !stdoutCtx || !activeProtocol) return
+    if (effectiveWidth <= 0 || effectiveHeight <= 0) return
+
+    const { write } = stdoutCtx
+
+    if (activeProtocol === "kitty") {
+      const seq = encodeKittyImage(pngData, {
+        width: effectiveWidth,
+        height: effectiveHeight,
+        id: imageIdRef.current ?? undefined,
+      })
+      write(seq)
+    } else if (activeProtocol === "sixel") {
+      // For Sixel, we would need the decoded pixel data.
+      // Since we receive PNG, and decoding PNG requires a library,
+      // Sixel rendering from raw PNG is deferred. The Kitty protocol
+      // can transmit PNG directly (f=100), but Sixel cannot.
+      // For now, Sixel only works if src is already decoded pixel data.
+      // This is a known limitation noted in the module docs.
+      //
+      // If someone passes a Buffer that's already RGBA pixel data
+      // (not PNG), this would need a flag. For now, Sixel falls through
+      // to fallback when src is PNG.
+    }
+  }, [pngData, stdoutCtx, activeProtocol, effectiveWidth, effectiveHeight])
+
+  // Cleanup: delete Kitty image on unmount
+  useEffect(() => {
+    const id = imageIdRef.current
+    if (activeProtocol !== "kitty" || id == null || !stdoutCtx) return
+
+    return () => {
+      stdoutCtx.write(deleteKittyImage(id))
+    }
+  }, [activeProtocol, stdoutCtx])
+
+  // If no protocol or no image data, render fallback text
+  if (!activeProtocol || !pngData) {
+    return (
+      <silvery-box width={effectiveWidth} height={effectiveHeight}>
+        <silvery-text>{fallback}</silvery-text>
+      </silvery-box>
+    )
+  }
+
+  // Reserve visual space with an empty box.
+  // The image is drawn over this space via stdout escape sequences.
+  // Fill with spaces so the cell buffer allocates the right area.
+  const spaceLine = " ".repeat(Math.max(0, effectiveWidth))
+  const spaceContent = Array.from({ length: Math.max(0, effectiveHeight) }, () => spaceLine).join("\n")
+
+  return (
+    <silvery-box width={effectiveWidth} height={effectiveHeight}>
+      <silvery-text>{spaceContent}</silvery-text>
+    </silvery-box>
+  )
+}

package/src/image/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Image rendering support for silvery.
+ *
+ * Provides encoders for the Kitty graphics protocol and Sixel protocol,
+ * plus a React component for rendering images in terminal UIs.
+ */
+
+export { encodeKittyImage, deleteKittyImage, isKittyGraphicsSupported } from "./kitty-graphics"
+export type { KittyImageOptions } from "./kitty-graphics"
+
+export { encodeSixel, isSixelSupported } from "./sixel-encoder"
+export type { SixelImageData } from "./sixel-encoder"
+
+export { Image } from "./Image"
+export type { ImageProps } from "./Image"