@silvery/ui 0.3.0

package/src/components/CommandPalette.tsx

@@ -0,0 +1,186 @@
+/**
+ * CommandPalette Component
+ *
+ * A filterable command list with keyboard navigation. Takes an array of
+ * commands with name, description, and optional shortcut. Users can type
+ * to filter and navigate with arrow keys / j/k.
+ *
+ * Usage:
+ * ```tsx
+ * const commands = [
+ *   { name: "Save", description: "Save current file", shortcut: "Ctrl+S" },
+ *   { name: "Quit", description: "Exit application", shortcut: "Ctrl+Q" },
+ *   { name: "Help", description: "Show help" },
+ * ]
+ *
+ * <CommandPalette
+ *   commands={commands}
+ *   onSelect={(cmd) => exec(cmd.name)}
+ *   placeholder="Type a command..."
+ * />
+ * ```
+ */
+import React, { useCallback, useMemo, useState } from "react"
+import { useInput } from "@silvery/react/hooks/useInput"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface CommandItem {
+  /** Command display name */
+  name: string
+  /** Command description */
+  description?: string
+  /** Keyboard shortcut hint */
+  shortcut?: string
+}
+
+export interface CommandPaletteProps {
+  /** Available commands */
+  commands: CommandItem[]
+  /** Called when a command is selected (Enter) */
+  onSelect?: (command: CommandItem) => void
+  /** Called when the palette is dismissed (Escape) */
+  onClose?: () => void
+  /** Placeholder text for the filter input (default: "Search commands...") */
+  placeholder?: string
+  /** Max visible results (default: 10) */
+  maxVisible?: number
+  /** Whether this component captures input (default: true) */
+  isActive?: boolean
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Case-insensitive fuzzy match: all query characters appear in order. */
+function fuzzyMatch(query: string, text: string): boolean {
+  const lower = text.toLowerCase()
+  const q = query.toLowerCase()
+  let qi = 0
+  for (let i = 0; i < lower.length && qi < q.length; i++) {
+    if (lower[i] === q[qi]) qi++
+  }
+  return qi === q.length
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Filterable command palette with keyboard navigation.
+ *
+ * Type to filter commands by name, navigate with Up/Down or j/k,
+ * confirm with Enter, dismiss with Escape.
+ */
+export function CommandPalette({
+  commands,
+  onSelect,
+  onClose,
+  placeholder = "Search commands...",
+  maxVisible = 10,
+  isActive = true,
+}: CommandPaletteProps): React.ReactElement {
+  const [query, setQuery] = useState("")
+  const [selectedIndex, setSelectedIndex] = useState(0)
+
+  const filtered = useMemo(() => {
+    if (!query) return commands
+    return commands.filter(
+      (cmd) => fuzzyMatch(query, cmd.name) || (cmd.description && fuzzyMatch(query, cmd.description)),
+    )
+  }, [commands, query])
+
+  const visible = filtered.slice(0, maxVisible)
+
+  const clampIndex = useCallback((idx: number) => Math.max(0, Math.min(idx, filtered.length - 1)), [filtered.length])
+
+  useInput(
+    (input, key) => {
+      // Navigation
+      if (key.upArrow) {
+        setSelectedIndex((prev) => clampIndex(prev - 1))
+        return
+      }
+      if (key.downArrow) {
+        setSelectedIndex((prev) => clampIndex(prev + 1))
+        return
+      }
+
+      // Select
+      if (key.return) {
+        const cmd = filtered[selectedIndex]
+        if (cmd) onSelect?.(cmd)
+        return
+      }
+
+      // Dismiss
+      if (key.escape) {
+        onClose?.()
+        return
+      }
+
+      // Backspace
+      if (key.backspace || key.delete) {
+        setQuery((prev) => {
+          const next = prev.slice(0, -1)
+          setSelectedIndex(0)
+          return next
+        })
+        return
+      }
+
+      // Printable character
+      if (input && input >= " " && !key.ctrl && !key.meta) {
+        setQuery((prev) => {
+          setSelectedIndex(0)
+          return prev + input
+        })
+      }
+    },
+    { isActive },
+  )
+
+  return (
+    <Box flexDirection="column" borderStyle="single" borderColor="$border" backgroundColor="$surface-bg" paddingX={1}>
+      {/* Search input */}
+      <Box>
+        <Text color="$primary" bold>
+          {">"}{" "}
+        </Text>
+        <Text>{query || <Text color="$disabledfg">{placeholder}</Text>}</Text>
+      </Box>
+      <Box>
+        <Text color="$border">{"─".repeat(30)}</Text>
+      </Box>
+      {/* Results */}
+      {visible.length === 0 ? (
+        <Text color="$disabledfg">No matching commands</Text>
+      ) : (
+        visible.map((cmd, i) => {
+          const isSelected = i === selectedIndex
+          return (
+            <Box key={cmd.name} gap={1}>
+              <Text inverse={isSelected} color={isSelected ? "$primary" : "$fg"}>
+                {isSelected ? ">" : " "} {cmd.name}
+              </Text>
+              {cmd.description && <Text color="$muted">{cmd.description}</Text>}
+              {cmd.shortcut && (
+                <Text color="$disabledfg" bold>
+                  {cmd.shortcut}
+                </Text>
+              )}
+            </Box>
+          )
+        })
+      )}
+      {/* Status */}
+      {filtered.length > maxVisible && <Text color="$disabledfg">{filtered.length - maxVisible} more...</Text>}
+    </Box>
+  )
+}

package/src/components/Console.tsx

@@ -0,0 +1,79 @@
+import type { ConsoleEntry, PatchedConsole } from "@silvery/term/ansi"
+import type { ReactElement, ReactNode } from "react"
+import { useConsole } from "@silvery/react/hooks/useConsole"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+interface ConsoleProps {
+  /** The patched console to render entries from */
+  console: PatchedConsole
+
+  /** Optional render function for custom entry rendering */
+  children?: (entry: ConsoleEntry, index: number) => ReactNode
+}
+
+/**
+ * Format console entry args into a string.
+ * Joins args with spaces, handling objects via JSON.stringify.
+ */
+function formatArgs(args: unknown[]): string {
+  return args
+    .map((arg) => {
+      if (typeof arg === "string") return arg
+      if (typeof arg === "number" || typeof arg === "boolean") {
+        return String(arg)
+      }
+      if (arg === null) return "null"
+      if (arg === undefined) return "undefined"
+      try {
+        return JSON.stringify(arg)
+      } catch {
+        return String(arg)
+      }
+    })
+    .join(" ")
+}
+
+/**
+ * Renders captured console output from a PatchedConsole.
+ *
+ * Uses useConsole hook to subscribe to entries and re-renders when new
+ * entries arrive. Supports custom rendering via children render prop.
+ *
+ * @example Default rendering
+ * ```tsx
+ * import { Console } from '@silvery/react'
+ * import { patchConsole } from '@silvery/chalk'
+ *
+ * using patched = patchConsole(console)
+ * <Console console={patched} />
+ * ```
+ *
+ * @example Custom rendering
+ * ```tsx
+ * <Console console={patched}>
+ *   {(entry, i) => (
+ *     <Text key={i} color={entry.stream === 'stderr' ? 'yellow' : 'green'}>
+ *       [{entry.method}] {entry.args.join(' ')}
+ *     </Text>
+ *   )}
+ * </Console>
+ * ```
+ */
+export function Console({ console: patched, children }: ConsoleProps): ReactElement {
+  const entries = useConsole(patched)
+
+  return (
+    <Box flexDirection="column">
+      {entries.map((entry, i) =>
+        children ? (
+          children(entry, i)
+        ) : (
+          <Text key={i} color={entry.stream === "stderr" ? "red" : undefined}>
+            {formatArgs(entry.args)}
+          </Text>
+        ),
+      )}
+    </Box>
+  )
+}

package/src/components/CursorLine.tsx

@@ -0,0 +1,71 @@
+/**
+ * CursorLine Component
+ *
+ * Renders a single line of text with a visible cursor at a split point.
+ * Extracts the duplicated cursor-rendering pattern found across km-tui
+ * (inline edit, input box, search bar, etc.) into a reusable primitive.
+ *
+ * Usage:
+ * ```tsx
+ * <CursorLine beforeCursor="hel" afterCursor="lo world" />
+ * <CursorLine beforeCursor="full text" afterCursor="" />
+ * <CursorLine beforeCursor="" afterCursor="start" cursorStyle="underline" />
+ * ```
+ */
+import React from "react"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface CursorLineProps {
+  /** Text before the cursor position */
+  beforeCursor: string
+  /** Text after the cursor position (first char gets cursor highlight) */
+  afterCursor: string
+  /** Text color */
+  color?: string
+  /** Whether to show the cursor (default: true) */
+  showCursor?: boolean
+  /** Cursor style: 'block' (inverse) or 'underline' (default: block) */
+  cursorStyle?: "block" | "underline"
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Renders a single line with a visible cursor character.
+ *
+ * The cursor character is `afterCursor[0]` (or a space when afterCursor is
+ * empty, indicating the cursor is at the end of the text). The character is
+ * rendered with inverse video (block) or underline styling.
+ */
+export function CursorLine({
+  beforeCursor,
+  afterCursor,
+  color,
+  showCursor = true,
+  cursorStyle = "block",
+}: CursorLineProps): React.ReactElement {
+  if (!showCursor)
+    return (
+      <Text color={color}>
+        {beforeCursor}
+        {afterCursor}
+      </Text>
+    )
+
+  const cursorChar = afterCursor[0] ?? " "
+  const rest = afterCursor.slice(1)
+
+  return (
+    <Text color={color}>
+      {beforeCursor}
+      {cursorStyle === "block" ? <Text inverse>{cursorChar}</Text> : <Text underline>{cursorChar}</Text>}
+      {rest}
+    </Text>
+  )
+}

package/src/components/Divider.tsx

@@ -0,0 +1,67 @@
+/**
+ * Divider Component
+ *
+ * A horizontal separator line with optional centered title.
+ *
+ * Usage:
+ * ```tsx
+ * <Divider />
+ * <Divider title="Section" />
+ * <Divider char="=" width={40} />
+ * ```
+ */
+import React from "react"
+import { useContentRect } from "@silvery/react/hooks/useLayout"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface DividerProps {
+  /** Character to repeat (default: "─") */
+  char?: string
+  /** Title text centered in divider */
+  title?: string
+  /** Width (default: 100% via useContentRect) */
+  width?: number
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_CHAR = "─"
+const DEFAULT_WIDTH = 40
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export function Divider({ char = DEFAULT_CHAR, title, width: widthProp }: DividerProps): React.ReactElement {
+  const { width: contentWidth } = useContentRect()
+  const totalWidth = widthProp ?? (contentWidth > 0 ? contentWidth : DEFAULT_WIDTH)
+
+  if (!title) {
+    return (
+      <Box>
+        <Text dimColor>{char.repeat(totalWidth)}</Text>
+      </Box>
+    )
+  }
+
+  // Title with surrounding lines: "───── Title ─────"
+  const titleWithPad = ` ${title} `
+  const remaining = Math.max(0, totalWidth - titleWithPad.length)
+  const leftLen = Math.floor(remaining / 2)
+  const rightLen = remaining - leftLen
+
+  return (
+    <Box>
+      <Text dimColor>{char.repeat(leftLen)}</Text>
+      <Text bold>{titleWithPad}</Text>
+      <Text dimColor>{char.repeat(rightLen)}</Text>
+    </Box>
+  )
+}

package/src/components/EditContextDisplay.tsx

@@ -0,0 +1,164 @@
+/**
+ * EditContextDisplay Component
+ *
+ * Pure rendering component for multi-line text display with scrolling.
+ * Consumes the output of useEditContext (value + cursor position) and
+ * handles word wrapping, viewport scrolling, and cursor highlighting.
+ *
+ * Unlike TextArea, this component has NO input handling — the command
+ * system handles all input via useEditContext's EditTarget. This is the
+ * rendering half of the edit context pattern.
+ *
+ * Usage:
+ * ```tsx
+ * const { value, cursor } = useEditContext({ ... })
+ * const { width } = useContentRect()
+ *
+ * <EditContextDisplay
+ *   value={value}
+ *   cursor={cursor}
+ *   height={10}
+ *   wrapWidth={width}
+ * />
+ * ```
+ *
+ * Scroll logic extracted from TextArea.tsx — same clampScroll pattern
+ * that keeps cursor visible within the viewport.
+ */
+import React, { useMemo, useRef } from "react"
+import { cursorToRowCol, getWrappedLines } from "@silvery/tea/text-cursor"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface EditContextDisplayProps {
+  /** Current text value (from useEditContext) */
+  value: string
+  /** Cursor position as character offset (from useEditContext) */
+  cursor: number
+  /** Visible height in rows. When omitted, renders all lines (no scrolling). */
+  height?: number
+  /** Width for word wrapping. When omitted, renders without wrapping. */
+  wrapWidth?: number
+  /** Cursor style: 'block' (inverse) or 'underline' */
+  cursorStyle?: "block" | "underline"
+  /** Placeholder text when value is empty */
+  placeholder?: string
+  /** Whether to show the cursor (default: true) */
+  showCursor?: boolean
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Ensure scroll offset keeps the cursor row visible within the viewport. */
+function clampScroll(cursorRow: number, currentScroll: number, viewportHeight: number): number {
+  if (viewportHeight <= 0) return 0
+  let scroll = currentScroll
+  if (cursorRow < scroll) {
+    scroll = cursorRow
+  }
+  if (cursorRow >= scroll + viewportHeight) {
+    scroll = cursorRow - viewportHeight + 1
+  }
+  return Math.max(0, scroll)
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export function EditContextDisplay({
+  value,
+  cursor,
+  height,
+  wrapWidth,
+  cursorStyle = "block",
+  placeholder = "",
+  showCursor = true,
+}: EditContextDisplayProps): React.ReactElement {
+  // Scroll offset persists across renders via ref. No useState needed because
+  // every cursor/value change triggers a re-render from the parent (props change),
+  // and we compute the new scroll synchronously during that render.
+  const scrollRef = useRef(0)
+
+  // Effective wrap width: use provided wrapWidth, or a large value for no wrapping
+  const effectiveWrapWidth = wrapWidth != null && wrapWidth > 0 ? wrapWidth : 10000
+
+  // Clamp cursor to valid range
+  const clampedCursor = Math.min(Math.max(0, cursor), value.length)
+
+  // Compute wrapped lines and cursor position
+  const wrappedLines = useMemo(() => getWrappedLines(value, effectiveWrapWidth), [value, effectiveWrapWidth])
+
+  const { row: cursorRow, col: cursorCol } = useMemo(
+    () => cursorToRowCol(value, clampedCursor, effectiveWrapWidth),
+    [value, clampedCursor, effectiveWrapWidth],
+  )
+
+  // Update scroll offset to keep cursor visible (ref-only, no state)
+  const hasViewport = height != null && height > 0
+  if (hasViewport) {
+    scrollRef.current = clampScroll(cursorRow, scrollRef.current, height)
+  }
+
+  // =========================================================================
+  // Placeholder
+  // =========================================================================
+
+  if (!value && placeholder) {
+    if (hasViewport) {
+      return (
+        <Box flexDirection="column" height={height} justifyContent="center" alignItems="center">
+          <Text dimColor>{placeholder}</Text>
+        </Box>
+      )
+    }
+    return (
+      <Box flexDirection="column">
+        <Text dimColor>{placeholder}</Text>
+      </Box>
+    )
+  }
+
+  // =========================================================================
+  // Determine visible lines
+  // =========================================================================
+
+  const currentScroll = hasViewport ? scrollRef.current : 0
+  const visibleLines = hasViewport ? wrappedLines.slice(currentScroll, currentScroll + height) : wrappedLines
+
+  // =========================================================================
+  // Render
+  // =========================================================================
+
+  return (
+    <Box key={currentScroll} flexDirection="column" height={hasViewport ? height : undefined}>
+      {visibleLines.map((wl, i) => {
+        const absoluteRow = currentScroll + i
+        const isCursorRow = absoluteRow === cursorRow && showCursor
+
+        if (!isCursorRow) {
+          return <Text key={absoluteRow}>{wl.line || " "}</Text>
+        }
+
+        // Render line with cursor highlight
+        const beforeCursorText = wl.line.slice(0, cursorCol)
+        const atCursor = wl.line[cursorCol] ?? " "
+        const afterCursorText = wl.line.slice(cursorCol + 1)
+
+        return (
+          <Text key={absoluteRow}>
+            {beforeCursorText}
+            {cursorStyle === "block" ? <Text inverse>{atCursor}</Text> : <Text underline>{atCursor}</Text>}
+            {afterCursorText}
+          </Text>
+        )
+      })}
+    </Box>
+  )
+}