@silvery/ui 0.3.0

package/src/components/Skeleton.tsx

@@ -0,0 +1,87 @@
+/**
+ * Skeleton Component
+ *
+ * Loading placeholder with configurable dimensions and shape.
+ * Renders a block of placeholder characters to indicate content
+ * that is loading or not yet available.
+ *
+ * Usage:
+ * ```tsx
+ * <Skeleton width={20} />
+ * <Skeleton width={30} height={3} />
+ * <Skeleton width={10} shape="circle" />
+ * ```
+ */
+import React from "react"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface SkeletonProps {
+  /** Width in columns (default: 20) */
+  width?: number
+  /** Height in rows (default: 1) */
+  height?: number
+  /** Placeholder character (default: "░") */
+  char?: string
+  /** Shape hint: "line" for single-line, "block" for multi-line (default: auto from height) */
+  shape?: "line" | "block" | "circle"
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_WIDTH = 20
+const DEFAULT_CHAR = "░"
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Loading placeholder skeleton.
+ *
+ * Renders a dimmed block of placeholder characters. Use `width` and `height`
+ * to match the expected content dimensions. The `circle` shape renders
+ * a shorter, centered row for avatar-style placeholders.
+ */
+export function Skeleton({
+  width = DEFAULT_WIDTH,
+  height: heightProp,
+  char = DEFAULT_CHAR,
+  shape,
+}: SkeletonProps): React.ReactElement {
+  const resolvedShape = shape ?? (heightProp && heightProp > 1 ? "block" : "line")
+  const height = heightProp ?? (resolvedShape === "circle" ? 1 : 1)
+
+  if (resolvedShape === "circle") {
+    // Render a centered shorter line to suggest a circular avatar
+    const circleWidth = Math.min(width, 6)
+    const pad = Math.max(0, Math.floor((width - circleWidth) / 2))
+    return (
+      <Box>
+        <Text color="$muted">
+          {" ".repeat(pad)}
+          {char.repeat(circleWidth)}
+        </Text>
+      </Box>
+    )
+  }
+
+  const line = char.repeat(width)
+  const rows = Array.from({ length: height }, (_, i) => i)
+
+  return (
+    <Box flexDirection="column">
+      {rows.map((i) => (
+        <Text key={i} color="$muted">
+          {line}
+        </Text>
+      ))}
+    </Box>
+  )
+}

package/src/components/Spinner.tsx

@@ -0,0 +1,64 @@
+/**
+ * Spinner Component
+ *
+ * An animated loading spinner with multiple built-in styles.
+ *
+ * Usage:
+ * ```tsx
+ * <Spinner />
+ * <Spinner type="arc" label="Loading..." />
+ * <Spinner type="bounce" interval={120} />
+ * ```
+ */
+import React, { useEffect, useState } from "react"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface SpinnerProps {
+  /** Spinner style preset */
+  type?: "dots" | "line" | "arc" | "bounce"
+  /** Label text shown after spinner */
+  label?: string
+  /** Animation interval in ms (default: 80) */
+  interval?: number
+}
+
+// =============================================================================
+// Frame Sequences
+// =============================================================================
+
+const FRAMES: Record<NonNullable<SpinnerProps["type"]>, readonly string[]> = {
+  dots: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+  line: ["|", "/", "—", "\\"],
+  arc: ["◜", "◠", "◝", "◞", "◡", "◟"],
+  bounce: ["⠁", "⠂", "⠄", "⡀", "⢀", "⠠", "⠐", "⠈"],
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export function Spinner({ type = "dots", label, interval = 80 }: SpinnerProps): React.ReactElement {
+  const [frameIndex, setFrameIndex] = useState(0)
+  const frames = FRAMES[type]
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setFrameIndex((prev) => (prev + 1) % frames.length)
+    }, interval)
+
+    return () => clearInterval(timer)
+  }, [frames.length, interval])
+
+  const frame = frames[frameIndex % frames.length]!
+
+  return (
+    <Text>
+      {frame}
+      {label ? ` ${label}` : ""}
+    </Text>
+  )
+}

package/src/components/SplitView.tsx

@@ -0,0 +1,199 @@
+/**
+ * SplitView - Recursive binary-tree pane tiling component.
+ *
+ * Renders a layout tree of split panes using flexbox. Each leaf renders
+ * via renderPane(id). Splits divide space according to ratio (0-1,
+ * proportion given to first child).
+ *
+ * Horizontal splits use flexDirection="row", vertical splits use
+ * flexDirection="column". Each pane gets a border with optional title
+ * and focus highlight.
+ */
+
+import React from "react"
+import type { LayoutNode } from "@silvery/term/pane-manager"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type { LayoutNode }
+
+export interface SplitViewProps {
+  /** Layout tree describing the split arrangement */
+  layout: LayoutNode
+  /** Render function for each leaf pane */
+  renderPane: (id: string) => React.ReactNode
+  /** Optional: ID of the focused pane (for border highlighting) */
+  focusedPaneId?: string
+  /** Optional: show borders around panes (default: true) */
+  showBorders?: boolean
+  /** Optional: border style for focused pane */
+  focusedBorderColor?: string
+  /** Optional: border style for unfocused panes */
+  unfocusedBorderColor?: string
+  /** Optional: render pane title in border */
+  renderPaneTitle?: (id: string) => string
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const MIN_PANE_WIDTH = 20
+const MIN_PANE_HEIGHT = 5
+const DEFAULT_FOCUSED_COLOR = "green"
+const DEFAULT_UNFOCUSED_COLOR = "gray"
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * SplitView renders a binary tree of panes.
+ *
+ * Each leaf renders via `renderPane(id)`. Splits divide space
+ * according to `ratio` (0-1, proportion given to first child).
+ */
+export function SplitView(props: SplitViewProps): React.ReactElement {
+  const {
+    layout,
+    renderPane,
+    focusedPaneId,
+    showBorders = true,
+    focusedBorderColor = DEFAULT_FOCUSED_COLOR,
+    unfocusedBorderColor = DEFAULT_UNFOCUSED_COLOR,
+    renderPaneTitle,
+  } = props
+
+  return (
+    <Box flexGrow={1} flexDirection="column">
+      <LayoutNodeView
+        node={layout}
+        renderPane={renderPane}
+        focusedPaneId={focusedPaneId}
+        showBorders={showBorders}
+        focusedBorderColor={focusedBorderColor}
+        unfocusedBorderColor={unfocusedBorderColor}
+        renderPaneTitle={renderPaneTitle}
+      />
+    </Box>
+  )
+}
+
+// ============================================================================
+// Internal Components
+// ============================================================================
+
+interface LayoutNodeViewProps {
+  node: LayoutNode
+  renderPane: (id: string) => React.ReactNode
+  focusedPaneId?: string
+  showBorders: boolean
+  focusedBorderColor: string
+  unfocusedBorderColor: string
+  renderPaneTitle?: (id: string) => string
+}
+
+function LayoutNodeView(props: LayoutNodeViewProps): React.ReactElement {
+  const { node, renderPane, focusedPaneId, showBorders, focusedBorderColor, unfocusedBorderColor, renderPaneTitle } =
+    props
+
+  if (node.type === "leaf") {
+    return (
+      <LeafPane
+        id={node.id}
+        renderPane={renderPane}
+        isFocused={focusedPaneId === node.id}
+        showBorders={showBorders}
+        focusedBorderColor={focusedBorderColor}
+        unfocusedBorderColor={unfocusedBorderColor}
+        title={renderPaneTitle?.(node.id)}
+      />
+    )
+  }
+
+  // Split node: render two children with flex proportions
+  // Use integer flex values to express the ratio without floating point issues.
+  // ratio=0.5 => flexGrow 50:50, ratio=0.3 => flexGrow 30:70, etc.
+  const firstFlex = Math.round(node.ratio * 100)
+  const secondFlex = 100 - firstFlex
+
+  return (
+    <Box flexGrow={1} flexDirection={node.direction === "horizontal" ? "row" : "column"}>
+      <Box
+        flexGrow={firstFlex}
+        flexShrink={1}
+        minWidth={node.direction === "horizontal" ? MIN_PANE_WIDTH : undefined}
+        minHeight={node.direction === "vertical" ? MIN_PANE_HEIGHT : undefined}
+      >
+        <LayoutNodeView
+          node={node.first}
+          renderPane={renderPane}
+          focusedPaneId={focusedPaneId}
+          showBorders={showBorders}
+          focusedBorderColor={focusedBorderColor}
+          unfocusedBorderColor={unfocusedBorderColor}
+          renderPaneTitle={renderPaneTitle}
+        />
+      </Box>
+      <Box
+        flexGrow={secondFlex}
+        flexShrink={1}
+        minWidth={node.direction === "horizontal" ? MIN_PANE_WIDTH : undefined}
+        minHeight={node.direction === "vertical" ? MIN_PANE_HEIGHT : undefined}
+      >
+        <LayoutNodeView
+          node={node.second}
+          renderPane={renderPane}
+          focusedPaneId={focusedPaneId}
+          showBorders={showBorders}
+          focusedBorderColor={focusedBorderColor}
+          unfocusedBorderColor={unfocusedBorderColor}
+          renderPaneTitle={renderPaneTitle}
+        />
+      </Box>
+    </Box>
+  )
+}
+
+interface LeafPaneProps {
+  id: string
+  renderPane: (id: string) => React.ReactNode
+  isFocused: boolean
+  showBorders: boolean
+  focusedBorderColor: string
+  unfocusedBorderColor: string
+  title?: string
+}
+
+function LeafPane(props: LeafPaneProps): React.ReactElement {
+  const { id, renderPane, isFocused, showBorders, focusedBorderColor, unfocusedBorderColor, title } = props
+
+  if (!showBorders) {
+    return (
+      <Box flexGrow={1} testID={`pane-${id}`}>
+        {renderPane(id)}
+      </Box>
+    )
+  }
+
+  return (
+    <Box
+      flexGrow={1}
+      borderStyle="single"
+      borderColor={isFocused ? focusedBorderColor : unfocusedBorderColor}
+      testID={`pane-${id}`}
+      flexDirection="column"
+    >
+      {title != null && (
+        <Box>
+          <Text color={isFocused ? focusedBorderColor : unfocusedBorderColor}>{title}</Text>
+        </Box>
+      )}
+      <Box flexGrow={1}>{renderPane(id)}</Box>
+    </Box>
+  )
+}

package/src/components/Table.tsx

@@ -0,0 +1,139 @@
+/**
+ * Table Component
+ *
+ * A data table with headers and column alignment.
+ *
+ * Usage:
+ * ```tsx
+ * <Table
+ *   columns={[
+ *     { header: "Name", key: "name" },
+ *     { header: "Age", key: "age", align: "right" },
+ *   ]}
+ *   data={[
+ *     { name: "Alice", age: 30 },
+ *     { name: "Bob", age: 25 },
+ *   ]}
+ * />
+ * ```
+ */
+import React from "react"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TableColumn {
+  header: string
+  /** Key to extract from data row, or index for array data */
+  key?: string
+  /** Column width (auto if omitted) */
+  width?: number
+  /** Text alignment */
+  align?: "left" | "right" | "center"
+}
+
+export interface TableProps {
+  /** Column definitions */
+  columns: TableColumn[]
+  /** Data rows — array of objects or arrays */
+  data: Array<Record<string, unknown> | unknown[]>
+  /** Show header row (default: true) */
+  showHeader?: boolean
+  /** Border between columns (default: " │ ") */
+  separator?: string
+  /** Header style */
+  headerBold?: boolean
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function getCellValue(row: Record<string, unknown> | unknown[], col: TableColumn, colIndex: number): string {
+  if (Array.isArray(row)) {
+    const val = row[colIndex]
+    return val == null ? "" : String(val)
+  }
+  if (col.key) {
+    const val = row[col.key]
+    return val == null ? "" : String(val)
+  }
+  return ""
+}
+
+function alignText(text: string, width: number, align: "left" | "right" | "center" = "left"): string {
+  if (text.length >= width) return text.slice(0, width)
+
+  const pad = width - text.length
+
+  switch (align) {
+    case "right":
+      return " ".repeat(pad) + text
+    case "center": {
+      const leftPad = Math.floor(pad / 2)
+      const rightPad = pad - leftPad
+      return " ".repeat(leftPad) + text + " ".repeat(rightPad)
+    }
+    default:
+      return text + " ".repeat(pad)
+  }
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export function Table({
+  columns,
+  data,
+  showHeader = true,
+  separator = " │ ",
+  headerBold = true,
+}: TableProps): React.ReactElement {
+  // Calculate column widths
+  const colWidths = columns.map((col, colIndex) => {
+    if (col.width) return col.width
+
+    let maxWidth = col.header.length
+    for (const row of data) {
+      const cellText = getCellValue(row, col, colIndex)
+      maxWidth = Math.max(maxWidth, cellText.length)
+    }
+    return maxWidth
+  })
+
+  // Build header row
+  const headerCells = columns.map((col, i) => alignText(col.header, colWidths[i]!, col.align))
+  const headerLine = headerCells.join(separator)
+
+  // Build separator line
+  const separatorLine = colWidths.map((w) => "─".repeat(w)).join(separator.replace(/[^│]/g, "─").replace(/│/g, "┼"))
+
+  // Build data rows
+  const dataRows = data.map((row) => {
+    const cells = columns.map((col, i) => {
+      const value = getCellValue(row, col, i)
+      return alignText(value, colWidths[i]!, col.align)
+    })
+    return cells.join(separator)
+  })
+
+  return (
+    <Box flexDirection="column">
+      {showHeader && (
+        <>
+          <Text bold={headerBold} dimColor>
+            {headerLine}
+          </Text>
+          <Text dimColor>{separatorLine}</Text>
+        </>
+      )}
+      {dataRows.map((row, i) => (
+        <Text key={i}>{row}</Text>
+      ))}
+    </Box>
+  )
+}

package/src/components/Tabs.tsx

@@ -0,0 +1,203 @@
+/**
+ * Tabs Component
+ *
+ * Tab bar with keyboard navigation and panel content switching.
+ * Uses compound component pattern: Tabs > TabList + TabPanel.
+ *
+ * Usage:
+ * ```tsx
+ * <Tabs defaultValue="general">
+ *   <TabList>
+ *     <Tab value="general">General</Tab>
+ *     <Tab value="advanced">Advanced</Tab>
+ *     <Tab value="about">About</Tab>
+ *   </TabList>
+ *   <TabPanel value="general">
+ *     <Text>General settings...</Text>
+ *   </TabPanel>
+ *   <TabPanel value="advanced">
+ *     <Text>Advanced settings...</Text>
+ *   </TabPanel>
+ *   <TabPanel value="about">
+ *     <Text>About this app...</Text>
+ *   </TabPanel>
+ * </Tabs>
+ * ```
+ */
+import React, { createContext, useCallback, useContext, 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 TabsProps {
+  /** Default active tab value (uncontrolled) */
+  defaultValue?: string
+  /** Controlled active tab value */
+  value?: string
+  /** Called when the active tab changes */
+  onChange?: (value: string) => void
+  /** Whether tab input is active (default: true) */
+  isActive?: boolean
+  /** Tab children (TabList + TabPanel components) */
+  children: React.ReactNode
+}
+
+export interface TabListProps {
+  /** Tab children */
+  children: React.ReactNode
+}
+
+export interface TabProps {
+  /** Unique tab identifier */
+  value: string
+  /** Tab label children */
+  children: React.ReactNode
+}
+
+export interface TabPanelProps {
+  /** Tab value this panel corresponds to */
+  value: string
+  /** Panel content */
+  children: React.ReactNode
+}
+
+// =============================================================================
+// Context
+// =============================================================================
+
+interface TabsContextValue {
+  activeValue: string
+  setActiveValue: (value: string) => void
+  tabValues: string[]
+  registerTab: (value: string) => void
+}
+
+const TabsContext = createContext<TabsContextValue>({
+  activeValue: "",
+  setActiveValue: () => {},
+  tabValues: [],
+  registerTab: () => {},
+})
+
+function useTabsContext(): TabsContextValue {
+  return useContext(TabsContext)
+}
+
+// =============================================================================
+// Components
+// =============================================================================
+
+/**
+ * Root tabs container. Provides context for TabList, Tab, and TabPanel.
+ *
+ * Supports controlled (`value` + `onChange`) and uncontrolled (`defaultValue`) modes.
+ * Navigate tabs with Left/Right arrow keys when the TabList is active.
+ */
+export function Tabs({
+  defaultValue,
+  value: controlledValue,
+  onChange,
+  isActive = true,
+  children,
+}: TabsProps): React.ReactElement {
+  const isControlled = controlledValue !== undefined
+  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue ?? "")
+  const [tabValues, setTabValues] = useState<string[]>([])
+
+  const activeValue = isControlled ? controlledValue : uncontrolledValue
+
+  const setActiveValue = useCallback(
+    (val: string) => {
+      if (!isControlled) setUncontrolledValue(val)
+      onChange?.(val)
+    },
+    [isControlled, onChange],
+  )
+
+  const registerTab = useCallback((val: string) => {
+    setTabValues((prev) => (prev.includes(val) ? prev : [...prev, val]))
+  }, [])
+
+  // Keyboard navigation between tabs
+  useInput(
+    (_input, key) => {
+      if (tabValues.length === 0) return
+
+      const currentIdx = tabValues.indexOf(activeValue)
+      if (currentIdx < 0) return
+
+      if (key.rightArrow || _input === "l") {
+        const next = (currentIdx + 1) % tabValues.length
+        setActiveValue(tabValues[next]!)
+        return
+      }
+
+      if (key.leftArrow || _input === "h") {
+        const next = (currentIdx - 1 + tabValues.length) % tabValues.length
+        setActiveValue(tabValues[next]!)
+        return
+      }
+    },
+    { isActive },
+  )
+
+  return (
+    <TabsContext.Provider value={{ activeValue, setActiveValue, tabValues, registerTab }}>
+      <Box flexDirection="column">{children}</Box>
+    </TabsContext.Provider>
+  )
+}
+
+/**
+ * Horizontal tab bar container.
+ *
+ * Renders Tab children in a horizontal row with gap spacing.
+ */
+export function TabList({ children }: TabListProps): React.ReactElement {
+  return (
+    <Box flexDirection="row" gap={1} borderBottom borderColor="$border">
+      {children}
+    </Box>
+  )
+}
+
+/**
+ * Individual tab trigger.
+ *
+ * Renders the tab label with active/inactive styling. Active tab is bold
+ * with `$primary` color; inactive tabs use `$muted`.
+ */
+export function Tab({ value, children }: TabProps): React.ReactElement {
+  const { activeValue, registerTab } = useTabsContext()
+  const isActive = activeValue === value
+
+  // Register this tab's value for keyboard navigation
+  React.useEffect(() => {
+    registerTab(value)
+  }, [value, registerTab])
+
+  return (
+    <Box>
+      <Text color={isActive ? "$primary" : "$muted"} bold={isActive} underline={isActive}>
+        {children}
+      </Text>
+    </Box>
+  )
+}
+
+/**
+ * Tab panel content container.
+ *
+ * Only renders its children when the corresponding tab is active.
+ */
+export function TabPanel({ value, children }: TabPanelProps): React.ReactElement | null {
+  const { activeValue } = useTabsContext()
+
+  if (activeValue !== value) return null
+
+  return <Box flexDirection="column">{children}</Box>
+}