@silvery/ui 0.3.0

package/src/components/Toast.tsx

@@ -0,0 +1,216 @@
+/**
+ * Toast/Notification Component + useToast Hook
+ *
+ * Provides a toast notification system with auto-dismiss capability.
+ * `useToast()` returns `{ toast, toasts, dismiss }`. Toasts render as a
+ * vertical stack and auto-dismiss after a configurable duration.
+ *
+ * Usage:
+ * ```tsx
+ * function App() {
+ *   const { toast, toasts } = useToast()
+ *
+ *   return (
+ *     <Box flexDirection="column">
+ *       <Button label="Save" onPress={() => {
+ *         toast({ title: "Saved", variant: "success", duration: 3000 })
+ *       }} />
+ *       <ToastContainer toasts={toasts} />
+ *     </Box>
+ *   )
+ * }
+ * ```
+ */
+import React, { useCallback, useEffect, useRef, useState } from "react"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type ToastVariant = "default" | "success" | "error" | "warning" | "info"
+
+export interface ToastData {
+  /** Unique toast ID (auto-generated if not provided) */
+  id: string
+  /** Toast title text */
+  title: string
+  /** Optional description text */
+  description?: string
+  /** Visual variant (default: "default") */
+  variant: ToastVariant
+  /** Auto-dismiss duration in ms (default: 3000, 0 = no auto-dismiss) */
+  duration: number
+}
+
+export interface ToastOptions {
+  /** Toast title text */
+  title: string
+  /** Optional description text */
+  description?: string
+  /** Visual variant (default: "default") */
+  variant?: ToastVariant
+  /** Auto-dismiss duration in ms (default: 3000, 0 = no auto-dismiss) */
+  duration?: number
+}
+
+export interface UseToastResult {
+  /** Show a new toast notification */
+  toast: (options: ToastOptions) => string
+  /** Currently visible toasts */
+  toasts: ToastData[]
+  /** Dismiss a specific toast by ID */
+  dismiss: (id: string) => void
+  /** Dismiss all toasts */
+  dismissAll: () => void
+}
+
+export interface ToastContainerProps {
+  /** Toasts to render */
+  toasts: ToastData[]
+  /** Maximum visible toasts (default: 5) */
+  maxVisible?: number
+}
+
+export interface ToastItemProps {
+  /** Toast data to render */
+  toast: ToastData
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const DEFAULT_DURATION = 3000
+
+const VARIANT_COLORS: Record<ToastVariant, string> = {
+  default: "$fg",
+  success: "$success",
+  error: "$error",
+  warning: "$warning",
+  info: "$info",
+}
+
+const VARIANT_ICONS: Record<ToastVariant, string> = {
+  default: "i",
+  success: "+",
+  error: "x",
+  warning: "!",
+  info: "i",
+}
+
+// =============================================================================
+// Hook
+// =============================================================================
+
+let nextToastId = 0
+
+/**
+ * Hook for managing toast notifications.
+ *
+ * Returns a `toast()` function to create notifications, the current list
+ * of `toasts`, and `dismiss`/`dismissAll` functions for manual removal.
+ * Toasts auto-dismiss after `duration` ms (default: 3000).
+ */
+export function useToast(): UseToastResult {
+  const [toasts, setToasts] = useState<ToastData[]>([])
+  const timersRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map())
+
+  const dismiss = useCallback((id: string) => {
+    setToasts((prev) => prev.filter((t) => t.id !== id))
+    const timer = timersRef.current.get(id)
+    if (timer) {
+      clearTimeout(timer)
+      timersRef.current.delete(id)
+    }
+  }, [])
+
+  const dismissAll = useCallback(() => {
+    setToasts([])
+    for (const timer of timersRef.current.values()) {
+      clearTimeout(timer)
+    }
+    timersRef.current.clear()
+  }, [])
+
+  const toast = useCallback(
+    (options: ToastOptions): string => {
+      const id = `toast-${++nextToastId}`
+      const data: ToastData = {
+        id,
+        title: options.title,
+        description: options.description,
+        variant: options.variant ?? "default",
+        duration: options.duration ?? DEFAULT_DURATION,
+      }
+
+      setToasts((prev) => [...prev, data])
+
+      if (data.duration > 0) {
+        const timer = setTimeout(() => {
+          dismiss(id)
+        }, data.duration)
+        timersRef.current.set(id, timer)
+      }
+
+      return id
+    },
+    [dismiss],
+  )
+
+  // Cleanup timers on unmount
+  useEffect(() => {
+    const timers = timersRef.current
+    return () => {
+      for (const timer of timers.values()) {
+        clearTimeout(timer)
+      }
+      timers.clear()
+    }
+  }, [])
+
+  return { toast, toasts, dismiss, dismissAll }
+}
+
+// =============================================================================
+// Components
+// =============================================================================
+
+/**
+ * Single toast notification item.
+ *
+ * Renders a bordered box with variant-colored icon, title, and optional
+ * description text.
+ */
+export function ToastItem({ toast }: ToastItemProps): React.ReactElement {
+  const color = VARIANT_COLORS[toast.variant]
+  const icon = VARIANT_ICONS[toast.variant]
+
+  return (
+    <Box borderStyle="single" borderColor="$border" paddingX={1} backgroundColor="$surface-bg">
+      <Text color={color} bold>
+        [{icon}]
+      </Text>
+      <Text> {toast.title}</Text>
+      {toast.description && <Text color="$muted"> {toast.description}</Text>}
+    </Box>
+  )
+}
+
+/**
+ * Container that renders a stack of toast notifications.
+ *
+ * Place at the bottom of your layout to show toasts as they appear.
+ */
+export function ToastContainer({ toasts, maxVisible = 5 }: ToastContainerProps): React.ReactElement {
+  const visible = toasts.slice(-maxVisible)
+
+  return (
+    <Box flexDirection="column">
+      {visible.map((t) => (
+        <ToastItem key={t.id} toast={t} />
+      ))}
+    </Box>
+  )
+}

package/src/components/Toggle.tsx

@@ -0,0 +1,73 @@
+/**
+ * Toggle Component
+ *
+ * A focusable checkbox-style toggle control. Integrates with the silvery focus
+ * system and responds to Space key to toggle the value.
+ *
+ * Usage:
+ * ```tsx
+ * const [enabled, setEnabled] = useState(false)
+ * <Toggle value={enabled} onChange={setEnabled} label="Dark mode" />
+ *
+ * // With explicit active control (bypasses focus system)
+ * <Toggle value={on} onChange={setOn} label="Option" isActive={isEditing} />
+ * ```
+ */
+import React from "react"
+import { useFocusable } from "@silvery/react/hooks/useFocusable"
+import { useInput } from "@silvery/react/hooks/useInput"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ToggleProps {
+  /** Whether the toggle is on */
+  value: boolean
+  /** Called when value changes */
+  onChange: (value: boolean) => void
+  /** Label text */
+  label?: string
+  /** Whether input is active (default: from focus system) */
+  isActive?: boolean
+  /** Test ID for focus system */
+  testID?: string
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Focusable toggle (checkbox) control.
+ *
+ * Renders `[x]` when on, `[ ]` when off. When focused, the checkbox indicator
+ * is rendered with inverse styling for visibility.
+ */
+export function Toggle({ value, onChange, label, isActive, testID }: ToggleProps): React.ReactElement {
+  const { focused } = useFocusable()
+
+  // isActive prop overrides focus state (same pattern as TextInput)
+  const active = isActive ?? focused
+
+  useInput(
+    (_input, key) => {
+      // Space toggles the value
+      if (_input === " " && !key.ctrl && !key.meta && !key.shift) {
+        onChange(!value)
+      }
+    },
+    { isActive: active },
+  )
+
+  const indicator = value ? "[x]" : "[ ]"
+
+  return (
+    <Box focusable testID={testID}>
+      <Text inverse={active}>{indicator}</Text>
+      {label && <Text> {label}</Text>}
+    </Box>
+  )
+}

package/src/components/Tooltip.tsx

@@ -0,0 +1,60 @@
+/**
+ * Tooltip Component
+ *
+ * Shows contextual help text near the target element. In a terminal UI,
+ * the tooltip renders inline below the target since there is no floating
+ * layer. Visibility is controlled via the `show` prop.
+ *
+ * Usage:
+ * ```tsx
+ * <Tooltip content="Delete permanently" show={isFocused}>
+ *   <Button label="Delete" onPress={handleDelete} />
+ * </Tooltip>
+ *
+ * // Always visible
+ * <Tooltip content="This action cannot be undone" show>
+ *   <Text>Dangerous action</Text>
+ * </Tooltip>
+ * ```
+ */
+import React from "react"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface TooltipProps {
+  /** Tooltip text content */
+  content: string
+  /** Whether the tooltip is visible (default: false) */
+  show?: boolean
+  /** Tooltip children (target element) */
+  children: React.ReactNode
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Contextual tooltip that appears below its children.
+ *
+ * Renders inline below the target element when `show` is true.
+ * Tooltip text is rendered in `$muted` with dimColor for subtlety.
+ */
+export function Tooltip({ content, show = false, children }: TooltipProps): React.ReactElement {
+  return (
+    <Box flexDirection="column">
+      {children}
+      {show && (
+        <Box>
+          <Text color="$muted" dimColor>
+            {content}
+          </Text>
+        </Box>
+      )}
+    </Box>
+  )
+}

package/src/components/TreeView.tsx

@@ -0,0 +1,212 @@
+/**
+ * TreeView Component
+ *
+ * Expandable/collapsible hierarchical data display with keyboard navigation.
+ * Each node can have children, and the tree supports controlled or
+ * uncontrolled expansion state.
+ *
+ * Usage:
+ * ```tsx
+ * const data: TreeNode[] = [
+ *   {
+ *     id: "1",
+ *     label: "Documents",
+ *     children: [
+ *       { id: "1.1", label: "README.md" },
+ *       { id: "1.2", label: "notes.txt" },
+ *     ],
+ *   },
+ *   { id: "2", label: "config.json" },
+ * ]
+ *
+ * <TreeView data={data} renderNode={(node) => <Text>{node.label}</Text>} />
+ * ```
+ */
+import React, { useCallback, 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 TreeNode {
+  /** Unique identifier for this node */
+  id: string
+  /** Display label */
+  label: string
+  /** Child nodes (optional) */
+  children?: TreeNode[]
+}
+
+export interface TreeViewProps {
+  /** Hierarchical data to display */
+  data: TreeNode[]
+  /** Custom node renderer (default: renders label text) */
+  renderNode?: (node: TreeNode, depth: number) => React.ReactNode
+  /** Controlled: set of expanded node IDs */
+  expandedIds?: Set<string>
+  /** Called when expansion state changes */
+  onToggle?: (nodeId: string, expanded: boolean) => void
+  /** Whether nodes start expanded (default: false) */
+  defaultExpanded?: boolean
+  /** Whether this component captures input (default: true) */
+  isActive?: boolean
+  /** Indent per level in characters (default: 2) */
+  indent?: number
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Flatten tree into visible list based on expansion state. */
+function flattenTree(
+  nodes: TreeNode[],
+  expanded: Set<string>,
+  depth: number = 0,
+): Array<{ node: TreeNode; depth: number }> {
+  const result: Array<{ node: TreeNode; depth: number }> = []
+  for (const node of nodes) {
+    result.push({ node, depth })
+    if (node.children && node.children.length > 0 && expanded.has(node.id)) {
+      result.push(...flattenTree(node.children, expanded, depth + 1))
+    }
+  }
+  return result
+}
+
+/** Collect all node IDs in the tree (for defaultExpanded). */
+function collectAllIds(nodes: TreeNode[]): Set<string> {
+  const ids = new Set<string>()
+  for (const node of nodes) {
+    ids.add(node.id)
+    if (node.children) {
+      for (const id of collectAllIds(node.children)) {
+        ids.add(id)
+      }
+    }
+  }
+  return ids
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Expandable/collapsible tree view.
+ *
+ * Navigate with Up/Down (or j/k), expand/collapse with Enter or Right/Left.
+ * Branch nodes show a triangle indicator (right = collapsed, down = expanded).
+ */
+export function TreeView({
+  data,
+  renderNode,
+  expandedIds: controlledExpanded,
+  onToggle,
+  defaultExpanded = false,
+  isActive = true,
+  indent = 2,
+}: TreeViewProps): React.ReactElement {
+  const isControlled = controlledExpanded !== undefined
+
+  const [uncontrolledExpanded, setUncontrolledExpanded] = useState<Set<string>>(() =>
+    defaultExpanded ? collectAllIds(data) : new Set(),
+  )
+
+  const expanded = isControlled ? controlledExpanded : uncontrolledExpanded
+  const [cursorIndex, setCursorIndex] = useState(0)
+
+  const flatItems = flattenTree(data, expanded)
+
+  const toggleNode = useCallback(
+    (nodeId: string) => {
+      const isExpanded = expanded.has(nodeId)
+      if (!isControlled) {
+        setUncontrolledExpanded((prev) => {
+          const next = new Set(prev)
+          if (isExpanded) {
+            next.delete(nodeId)
+          } else {
+            next.add(nodeId)
+          }
+          return next
+        })
+      }
+      onToggle?.(nodeId, !isExpanded)
+    },
+    [expanded, isControlled, onToggle],
+  )
+
+  useInput(
+    (input, key) => {
+      if (flatItems.length === 0) return
+
+      // Navigate up
+      if (key.upArrow || input === "k") {
+        setCursorIndex((prev) => Math.max(0, prev - 1))
+        return
+      }
+
+      // Navigate down
+      if (key.downArrow || input === "j") {
+        setCursorIndex((prev) => Math.min(flatItems.length - 1, prev + 1))
+        return
+      }
+
+      // Expand / toggle
+      if (key.return || key.rightArrow) {
+        const item = flatItems[cursorIndex]
+        if (item?.node?.children && item.node.children.length > 0) {
+          if (!expanded.has(item.node.id)) {
+            toggleNode(item.node.id)
+          } else if (key.return) {
+            // Enter on already-expanded = collapse
+            toggleNode(item.node.id)
+          }
+        }
+        return
+      }
+
+      // Collapse
+      if (key.leftArrow) {
+        const item = flatItems[cursorIndex]
+        if (item && expanded.has(item.node.id)) {
+          toggleNode(item.node.id)
+        }
+        return
+      }
+    },
+    { isActive },
+  )
+
+  if (flatItems.length === 0) {
+    return (
+      <Box>
+        <Text color="$disabledfg">No items</Text>
+      </Box>
+    )
+  }
+
+  return (
+    <Box flexDirection="column">
+      {flatItems.map(({ node, depth }, i) => {
+        const isCursor = i === cursorIndex
+        const hasChildren = node.children && node.children.length > 0
+        const isExpanded = expanded.has(node.id)
+        const prefix = hasChildren ? (isExpanded ? "v " : "> ") : "  "
+        const padding = " ".repeat(depth * indent)
+
+        return (
+          <Text key={node.id} inverse={isCursor}>
+            {padding}
+            <Text color={hasChildren ? "$primary" : "$fg"}>{prefix}</Text>
+            {renderNode ? renderNode(node, depth) : <Text>{node.label}</Text>}
+          </Text>
+        )
+      })}
+    </Box>
+  )
+}