@silvery/ui 0.3.0

package/src/components/ModalDialog.tsx

@@ -0,0 +1,179 @@
+/**
+ * ModalDialog Component
+ *
+ * Reusable modal dialog with consistent styling: double border, title bar,
+ * optional footer, and solid background that covers board content.
+ *
+ * Moved from km-tui shared-components to silvery for reuse across apps.
+ *
+ * Usage:
+ * ```tsx
+ * <ModalDialog title="Settings" width={60} footer="ESC to close">
+ *   <Text>Dialog content here</Text>
+ * </ModalDialog>
+ *
+ * <ModalDialog title="Help" hotkey="?" titleRight={<Text>1/3</Text>}>
+ *   <Text>Help content</Text>
+ * </ModalDialog>
+ * ```
+ */
+import React from "react"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ModalDialogProps {
+  /** Border color (default: $border). Cyan is reserved for text input focus rings. */
+  borderColor?: string
+  /** Dialog title (rendered bold in titleColor or borderColor) */
+  title?: string
+  /** Title color override (default: $primary). Separate from border for independent styling. */
+  titleColor?: string
+  /** Title alignment (default: center) */
+  titleAlign?: "center" | "flex-start" | "flex-end"
+  /** Toggle hotkey character (e.g., "?" for help). Renders [X] prefix in title. */
+  hotkey?: string
+  /** Content to render on the right side of the title bar (e.g., hotkey indicator, match count) */
+  titleRight?: React.ReactNode
+  /** Dialog width */
+  width?: number
+  /** Dialog height (optional, omit for auto-height) */
+  height?: number
+  /** Footer hint text (rendered dimColor at bottom) */
+  footer?: React.ReactNode
+  /** Footer alignment (default: center) */
+  footerAlign?: "center" | "flex-start" | "flex-end"
+  /** Called when ESC is pressed (optional convenience handler) */
+  onClose?: () => void
+  /** Whether to create a focus scope (default: true, for future focus system integration) */
+  focusScope?: boolean
+  /** Dialog children */
+  children: React.ReactNode
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Format a dialog title with a hotkey prefix.
+ *
+ * If the hotkey letter appears in the title (case-insensitive), highlights it inline:
+ *   hotkey="D", title="Details" -> [D]etails
+ * If the hotkey is not found in the title, prepends it:
+ *   hotkey="?", title="Help" -> [?] Help
+ *
+ * Brackets are dim, the hotkey letter is bold/bright.
+ */
+export function formatTitleWithHotkey(title: string, hotkey: string, color?: string): React.ReactElement {
+  const idx = title.toLowerCase().indexOf(hotkey.toLowerCase())
+  if (idx >= 0 && hotkey.length === 1 && hotkey.toLowerCase() !== hotkey.toUpperCase()) {
+    // Letter found in title — highlight it inline: prefix + [X] + rest
+    const before = title.slice(0, idx)
+    const matched = title[idx]
+    const after = title.slice(idx + 1)
+    return (
+      <Text color={color} bold>
+        {before}
+        <Text dimColor bold={false}>
+          [
+        </Text>
+        <Text bold>{matched}</Text>
+        <Text dimColor bold={false}>
+          ]
+        </Text>
+        {after}
+      </Text>
+    )
+  }
+  // Hotkey not in title (or symbol) — prepend [X] Title
+  return (
+    <Text color={color} bold>
+      <Text dimColor bold={false}>
+        [
+      </Text>
+      <Text bold>{hotkey}</Text>
+      <Text dimColor bold={false}>
+        ]
+      </Text>{" "}
+      {title}
+    </Text>
+  )
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Reusable modal dialog with consistent styling.
+ *
+ * Features:
+ * - Solid raised background (covers board content)
+ * - Double border (configurable color). Cyan reserved for focus rings.
+ * - Horizontal padding (2), vertical padding (1)
+ * - Title: bold, colored, with spacer below
+ * - Footer: centered, dimColor, with spacer above
+ */
+export function ModalDialog({
+  borderColor = "$border",
+  title,
+  titleColor,
+  titleAlign = "center",
+  hotkey,
+  titleRight,
+  width,
+  height,
+  footer,
+  footerAlign = "center",
+  onClose: _onClose,
+  focusScope: _focusScope = true,
+  children,
+}: ModalDialogProps): React.ReactElement {
+  const effectiveTitleColor = titleColor ?? "$primary"
+  // When titleRight is provided, use space-between layout for the title bar
+  const effectiveTitleAlign = titleRight ? "space-between" : titleAlign
+
+  return (
+    <Box
+      flexDirection="column"
+      width={width}
+      height={height}
+      borderStyle="double"
+      borderColor={borderColor}
+      backgroundColor={"$surface-bg"}
+      paddingX={2}
+      paddingY={1}
+    >
+      {title && (
+        <Box flexShrink={0} flexDirection="column">
+          <Box justifyContent={effectiveTitleAlign}>
+            {hotkey ? (
+              formatTitleWithHotkey(title, hotkey, effectiveTitleColor)
+            ) : (
+              <Text color={effectiveTitleColor} bold>
+                {title}
+              </Text>
+            )}
+            {titleRight}
+          </Box>
+          <Text> </Text>
+        </Box>
+      )}
+      {/* Content area - flexGrow pushes footer to bottom, overflow hidden prevents title displacement */}
+      <Box flexDirection="column" flexGrow={1} overflow="hidden">
+        {children}
+      </Box>
+      {/* Footer with spacer line above */}
+      {footer && (
+        <>
+          <Text> </Text>
+          <Box justifyContent={footerAlign}>{typeof footer === "string" ? <Text dimColor>{footer}</Text> : footer}</Box>
+        </>
+      )}
+    </Box>
+  )
+}

package/src/components/PickerDialog.tsx

@@ -0,0 +1,208 @@
+/**
+ * PickerDialog Component
+ *
+ * Generic search-and-select dialog combining ModalDialog + text input + scrolling
+ * result list. Handles keyboard routing: arrows for selection, Enter to confirm,
+ * Esc to cancel, printable chars for filtering.
+ *
+ * Uses useReadline internally for full readline editing (kill ring, word movement).
+ *
+ * Usage:
+ * ```tsx
+ * <PickerDialog
+ *   title="Search"
+ *   items={filteredResults}
+ *   renderItem={(item, selected) => (
+ *     <Text inverse={selected}>{item.name}</Text>
+ *   )}
+ *   keyExtractor={(item) => item.id}
+ *   onSelect={(item) => navigateTo(item)}
+ *   onCancel={() => closeDialog()}
+ *   onChange={(query) => setFilter(query)}
+ *   placeholder="Type to search..."
+ * />
+ * ```
+ */
+import React, { useCallback, useRef, useState } from "react"
+import { useInput } from "@silvery/react/hooks/useInput"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+import { CursorLine } from "./CursorLine"
+import { ModalDialog } from "./ModalDialog"
+import { PickerList } from "./PickerList"
+import { useReadline } from "./useReadline"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface PickerDialogProps<T> {
+  /** Dialog title */
+  title: string
+  /** Placeholder text when input is empty */
+  placeholder?: string
+  /** Items to display in the result list */
+  items: T[]
+  /** Render function for each item. `selected` is true for the highlighted item. */
+  renderItem: (item: T, selected: boolean) => React.ReactNode
+  /** Unique key for each item */
+  keyExtractor: (item: T) => string
+  /** Called when an item is confirmed (Enter) */
+  onSelect: (item: T) => void
+  /** Called when the dialog is cancelled (Esc) */
+  onCancel: () => void
+  /** Called when the input text changes (for filtering) */
+  onChange?: (query: string) => void
+  /** Initial input value */
+  initialValue?: string
+  /** Message when items list is empty */
+  emptyMessage?: string
+  /** Maximum visible items before scrolling (default: 10) */
+  maxVisible?: number
+  /** Dialog width */
+  width?: number
+  /** Dialog height (auto-sized if omitted) */
+  height?: number
+  /** Footer content */
+  footer?: React.ReactNode
+  /** Input prompt prefix (e.g., "/ " or "All > ") */
+  prompt?: string
+  /** Prompt color */
+  promptColor?: string
+  /** Whether the input is active (default: true) */
+  isActive?: boolean
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Generic search-and-select dialog.
+ *
+ * Keyboard routing:
+ * - Printable chars, Ctrl shortcuts: readline text editing
+ * - Up/Down arrows: navigate result list
+ * - PgUp/PgDn: scroll by page
+ * - Enter: confirm selected item
+ * - Esc: cancel dialog
+ */
+export function PickerDialog<T>({
+  title,
+  placeholder,
+  items,
+  renderItem,
+  keyExtractor,
+  onSelect,
+  onCancel,
+  onChange,
+  initialValue = "",
+  emptyMessage = "No items",
+  maxVisible = 10,
+  width,
+  height,
+  footer,
+  prompt,
+  promptColor,
+  isActive = true,
+}: PickerDialogProps<T>): React.ReactElement {
+  const [selectedIndex, setSelectedIndex] = useState(0)
+
+  // Refs for stable callbacks in useInput closures
+  const onSelectRef = useRef(onSelect)
+  onSelectRef.current = onSelect
+  const onCancelRef = useRef(onCancel)
+  onCancelRef.current = onCancel
+  const itemsRef = useRef(items)
+  itemsRef.current = items
+  const selectedIndexRef = useRef(selectedIndex)
+  selectedIndexRef.current = selectedIndex
+
+  // Readline hook for text editing (kill ring, word movement, etc.)
+  const readline = useReadline({
+    initialValue,
+    onChange: useCallback(
+      (value: string) => {
+        onChange?.(value)
+        setSelectedIndex(0)
+      },
+      [onChange],
+    ),
+    isActive,
+    handleEnter: false, // We handle Enter for item selection
+    handleEscape: false, // We handle Esc for cancel
+    handleVerticalArrows: false, // We handle Up/Down for list navigation
+  })
+
+  const clampedIndex = items.length > 0 ? Math.min(selectedIndex, items.length - 1) : 0
+  if (clampedIndex !== selectedIndex) {
+    setSelectedIndex(clampedIndex)
+  }
+
+  // Effective max visible for page navigation step size
+  const effectiveMaxVisible = Math.min(maxVisible, items.length)
+
+  // Navigation handler (separate from readline text editing)
+  useInput(
+    (_input, key) => {
+      if (key.escape) {
+        onCancelRef.current()
+        return
+      }
+      if (key.return) {
+        const currentItems = itemsRef.current
+        const idx = selectedIndexRef.current
+        const item = currentItems[Math.min(idx, currentItems.length - 1)]
+        if (item) onSelectRef.current(item)
+        return
+      }
+      if (key.upArrow) {
+        setSelectedIndex((i) => Math.max(0, i - 1))
+        return
+      }
+      if (key.downArrow) {
+        setSelectedIndex((i) => Math.min(i + 1, Math.max(0, itemsRef.current.length - 1)))
+        return
+      }
+      if (key.pageUp) {
+        setSelectedIndex((i) => Math.max(0, i - effectiveMaxVisible))
+        return
+      }
+      if (key.pageDown) {
+        setSelectedIndex((i) => Math.min(i + effectiveMaxVisible, Math.max(0, itemsRef.current.length - 1)))
+        return
+      }
+    },
+    { isActive },
+  )
+
+  // Show placeholder when input is empty
+  const showPlaceholder = !readline.value && placeholder
+
+  return (
+    <ModalDialog title={title} width={width} height={height} footer={footer}>
+      {/* Search input */}
+      <Box flexShrink={0} flexDirection="column">
+        <Box>
+          {prompt && <Text color={promptColor}>{prompt}</Text>}
+          {showPlaceholder ? (
+            <Text dimColor>{placeholder}</Text>
+          ) : (
+            <CursorLine beforeCursor={readline.beforeCursor} afterCursor={readline.afterCursor} showCursor={isActive} />
+          )}
+        </Box>
+        <Text dimColor>{"─".repeat(40)}</Text>
+      </Box>
+
+      {/* Result list (delegated to PickerList) */}
+      <PickerList
+        items={items}
+        selectedIndex={clampedIndex}
+        renderItem={renderItem}
+        keyExtractor={keyExtractor}
+        emptyMessage={emptyMessage}
+        maxVisible={maxVisible}
+      />
+    </ModalDialog>
+  )
+}

package/src/components/PickerList.tsx

@@ -0,0 +1,93 @@
+/**
+ * PickerList Component
+ *
+ * Standalone scrolling result list with selection highlighting. Extracted from
+ * PickerDialog so it can be composed independently by callers that manage their
+ * own input (e.g., km-tui command-system dialogs).
+ *
+ * Handles:
+ * - Scroll offset calculation (centers selected item in view)
+ * - Visible items slicing
+ * - Empty state rendering
+ * - Item rendering via renderItem callback
+ *
+ * Does NOT handle:
+ * - Keyboard navigation (caller manages selectedIndex)
+ * - Input/search (caller's responsibility)
+ *
+ * Usage:
+ * ```tsx
+ * <PickerList
+ *   items={filteredResults}
+ *   selectedIndex={selected}
+ *   renderItem={(item, sel) => <Text inverse={sel}>{item.name}</Text>}
+ *   keyExtractor={(item) => item.id}
+ * />
+ * ```
+ */
+import React from "react"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface PickerListProps<T> {
+  /** Items to display */
+  items: T[]
+  /** Currently selected index (caller-managed) */
+  selectedIndex: number
+  /** Render function for each item. `selected` is true for the highlighted item. */
+  renderItem: (item: T, selected: boolean) => React.ReactNode
+  /** Unique key for each item */
+  keyExtractor: (item: T) => string
+  /** Message when items list is empty (default: "No items") */
+  emptyMessage?: string
+  /** Maximum visible items before scrolling (default: 10) */
+  maxVisible?: number
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Scrolling result list with selection highlighting.
+ *
+ * Centers the selected item in the visible window. When there are fewer items
+ * than maxVisible, all items are shown without scrolling.
+ */
+export function PickerList<T>({
+  items,
+  selectedIndex,
+  renderItem,
+  keyExtractor,
+  emptyMessage = "No items",
+  maxVisible = 10,
+}: PickerListProps<T>): React.ReactElement {
+  const clampedIndex = items.length > 0 ? Math.min(selectedIndex, items.length - 1) : 0
+  const effectiveMaxVisible = Math.min(maxVisible, items.length)
+
+  // Scroll offset: center the selected item in the visible window
+  const scrollOffset =
+    items.length > effectiveMaxVisible
+      ? Math.max(0, Math.min(clampedIndex - Math.floor(effectiveMaxVisible / 2), items.length - effectiveMaxVisible))
+      : 0
+
+  const visibleItems = items.slice(scrollOffset, scrollOffset + effectiveMaxVisible)
+
+  return (
+    <Box flexDirection="column" flexGrow={1} flexShrink={1} overflow="hidden">
+      {items.length === 0 ? (
+        <Text dimColor>{emptyMessage}</Text>
+      ) : (
+        visibleItems.map((item, i) => {
+          const actualIndex = scrollOffset + i
+          const isSelected = actualIndex === clampedIndex
+          return <React.Fragment key={keyExtractor(item)}>{renderItem(item, isSelected)}</React.Fragment>
+        })
+      )}
+    </Box>
+  )
+}

package/src/components/ProgressBar.tsx

@@ -0,0 +1,126 @@
+/**
+ * ProgressBar Component
+ *
+ * A terminal progress bar with determinate and indeterminate modes.
+ *
+ * Usage:
+ * ```tsx
+ * <ProgressBar value={0.5} />
+ * <ProgressBar value={0.75} color="green" label="Downloading..." />
+ * <ProgressBar />  // indeterminate (animated)
+ * ```
+ */
+import React, { useEffect, useState } 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 ProgressBarProps {
+  /** Progress value 0-1 (omit for indeterminate) */
+  value?: number
+  /** Width in columns (default: uses available width via useContentRect) */
+  width?: number
+  /** Fill character (default: "█") */
+  fillChar?: string
+  /** Empty character (default: "░") */
+  emptyChar?: string
+  /** Show percentage label (default: true for determinate) */
+  showPercentage?: boolean
+  /** Label text */
+  label?: string
+  /** Color of the filled portion */
+  color?: string
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_FILL = "█"
+const DEFAULT_EMPTY = "░"
+const DEFAULT_WIDTH = 30
+const INDETERMINATE_BLOCK_SIZE = 4
+const INDETERMINATE_INTERVAL = 100
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export function ProgressBar({
+  value,
+  width: widthProp,
+  fillChar = DEFAULT_FILL,
+  emptyChar = DEFAULT_EMPTY,
+  showPercentage,
+  label,
+  color,
+}: ProgressBarProps): React.ReactElement {
+  const { width: contentWidth } = useContentRect()
+  const [bouncePos, setBouncePos] = useState(0)
+  const [bounceDir, setBounceDir] = useState(1)
+
+  const isDeterminate = value !== undefined
+  const showPct = showPercentage ?? isDeterminate
+
+  // Calculate available bar width
+  const labelWidth = label ? label.length + 1 : 0
+  const pctWidth = showPct ? 5 : 0 // " 100%"
+  const availableWidth = widthProp ?? (contentWidth > 0 ? contentWidth : DEFAULT_WIDTH)
+  const barWidth = Math.max(1, availableWidth - labelWidth - pctWidth)
+
+  // Indeterminate animation
+  useEffect(() => {
+    if (isDeterminate) return
+
+    const timer = setInterval(() => {
+      setBouncePos((prev) => {
+        const maxPos = barWidth - INDETERMINATE_BLOCK_SIZE
+        if (maxPos <= 0) return 0
+
+        const next = prev + bounceDir
+        if (next >= maxPos) {
+          setBounceDir(-1)
+          return maxPos
+        }
+        if (next <= 0) {
+          setBounceDir(1)
+          return 0
+        }
+        return next
+      })
+    }, INDETERMINATE_INTERVAL)
+
+    return () => clearInterval(timer)
+  }, [isDeterminate, barWidth, bounceDir])
+
+  let filledPart: string
+  let emptyPart: string
+
+  if (isDeterminate) {
+    const clamped = Math.max(0, Math.min(1, value))
+    const filled = Math.round(clamped * barWidth)
+    filledPart = fillChar.repeat(filled)
+    emptyPart = emptyChar.repeat(barWidth - filled)
+  } else {
+    // Indeterminate: sliding block
+    const blockSize = Math.min(INDETERMINATE_BLOCK_SIZE, barWidth)
+    const pos = Math.max(0, Math.min(bouncePos, barWidth - blockSize))
+    filledPart = emptyChar.repeat(pos) + fillChar.repeat(blockSize)
+    emptyPart = emptyChar.repeat(barWidth - pos - blockSize)
+  }
+
+  const pct = isDeterminate ? Math.round(Math.max(0, Math.min(1, value)) * 100) : 0
+
+  return (
+    <Box>
+      {label && <Text>{label} </Text>}
+      <Text color={color}>{filledPart}</Text>
+      <Text dimColor>{emptyPart}</Text>
+      {showPct && <Text> {pct}%</Text>}
+    </Box>
+  )
+}

package/src/components/Screen.tsx

@@ -0,0 +1,78 @@
+/**
+ * Screen - Fullscreen root component.
+ *
+ * Claims the full terminal dimensions for flexbox layout. This is the
+ * declarative equivalent of the implicit fullscreen mode from run()/createApp().
+ *
+ * @example
+ * ```tsx
+ * <Screen>
+ *   <Sidebar />
+ *   <MainContent />
+ *   <StatusBar />
+ * </Screen>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Fullscreen + scrollable region (log viewer, dashboard)
+ * <Screen>
+ *   <Sidebar />
+ *   <VirtualView items={logs} renderItem={...} />
+ *   <StatusBar />
+ * </Screen>
+ * ```
+ */
+
+import { useState, useEffect, type ReactNode, type ReactElement } from "react"
+import { Box } from "@silvery/react/components/Box"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ScreenProps {
+  /** Children to render in the fullscreen area */
+  children: ReactNode
+  /** Flex direction for layout. Default: "column" (screens are typically vertical) */
+  flexDirection?: "row" | "column" | "row-reverse" | "column-reverse"
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function getTermDims(): { width: number; height: number } {
+  return {
+    width: process.stdout.columns ?? 80,
+    height: process.stdout.rows ?? 24,
+  }
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Fullscreen root component.
+ *
+ * Provides a Box that fills the entire terminal. Tracks terminal resize
+ * events to stay in sync with the actual terminal dimensions.
+ */
+export function Screen({ children, flexDirection = "column" }: ScreenProps): ReactElement {
+  const [dims, setDims] = useState(getTermDims)
+
+  useEffect(() => {
+    const onResize = () => setDims(getTermDims())
+    process.stdout.on("resize", onResize)
+    return () => {
+      process.stdout.off("resize", onResize)
+    }
+  }, [])
+
+  return (
+    <Box width={dims.width} height={dims.height} flexDirection={flexDirection}>
+      {children}
+    </Box>
+  )
+}