@silvery/ui 0.3.0

package/src/progress/tasks.ts

@@ -0,0 +1,216 @@
+/**
+ * Fluent sequential task builder
+ *
+ * @deprecated Use `steps()` from `@silvery/ui/progress` instead.
+ *
+ * @example
+ * ```typescript
+ * // OLD (deprecated):
+ * import { tasks } from "@silvery/ui/progress";
+ * const results = await tasks()
+ *   .add("Loading", loadModules)
+ *   .add("Processing", processData)
+ *   .run({ clear: true });
+ *
+ * // NEW:
+ * import { steps } from "@silvery/ui/progress";
+ * const results = await steps({
+ *   loadModules,
+ *   processData,
+ * }).run({ clear: true });
+ * ```
+ */
+
+import type { ProgressInfo } from "../types.js"
+import { MultiProgress, type TaskHandle } from "../cli/multi-progress"
+
+// Node.js globals for yielding to event loop
+declare function setImmediate(callback: (value?: unknown) => void): unknown
+declare function setTimeout(callback: (value?: unknown) => void, ms: number): unknown
+
+/** Phase labels for common operations */
+const PHASE_LABELS: Record<string, string> = {
+  // Repo loading phases
+  discover: "Discovering files",
+  parse: "Parsing markdown",
+  apply: "Applying changes",
+  resolve: "Resolving links",
+  materialize: "Evaluating rules",
+  // Board building
+  board: "Building view",
+  // Legacy/alternative names
+  reading: "Reading events",
+  applying: "Applying events",
+  rules: "Evaluating rules",
+  scanning: "Scanning files",
+  reconciling: "Reconciling changes",
+}
+
+/** Task definition */
+interface TaskDef<T = unknown> {
+  title: string
+  work: () => T | PromiseLike<T> | Generator<ProgressInfo, T, unknown>
+}
+
+/** Options for run() */
+export interface RunOptions {
+  /** Clear progress display after completion (default: false) */
+  clear?: boolean
+}
+
+export interface TaskBuilder {
+  /**
+   * Add a task to the sequence
+   * @param title - Display title
+   * @param work - Function, async function, or generator
+   */
+  add<T>(title: string, work: () => T | PromiseLike<T> | Generator<ProgressInfo, T, unknown>): TaskBuilder
+
+  /**
+   * Run all tasks in sequence
+   * @param options - Run options
+   * @returns Results keyed by task title
+   */
+  run(options?: RunOptions): Promise<Record<string, unknown>>
+}
+
+/**
+ * Create a sequential task builder
+ *
+ * @returns TaskBuilder with add() and run() methods
+ */
+export function tasks(): TaskBuilder {
+  const taskList: TaskDef[] = []
+
+  const builder: TaskBuilder = {
+    add<T>(title: string, work: () => T | PromiseLike<T> | Generator<ProgressInfo, T, unknown>): TaskBuilder {
+      taskList.push({ title, work })
+      return builder
+    },
+
+    async run(options?: RunOptions): Promise<Record<string, unknown>> {
+      const multi = new MultiProgress()
+      const handles = new Map<string, TaskHandle>()
+      const results: Record<string, unknown> = {}
+
+      // Register all tasks upfront (shows pending state)
+      for (const task of taskList) {
+        handles.set(task.title, multi.add(task.title, { type: "spinner" }))
+      }
+
+      multi.start()
+
+      try {
+        for (const task of taskList) {
+          const handle = handles.get(task.title)!
+
+          // Force render before potentially blocking operation
+          await new Promise((resolve) => setImmediate(resolve))
+
+          const result = task.work()
+
+          if (isGenerator(result)) {
+            // Generator: parent stays static, phases animate underneath
+            results[task.title] = await runGenerator(result, handle, task.title, multi)
+          } else if (isPromiseLike(result)) {
+            handle.start()
+            results[task.title] = await result
+            handle.complete()
+          } else {
+            handle.start()
+            results[task.title] = result
+            handle.complete()
+          }
+        }
+      } finally {
+        multi.stop(options?.clear ?? false)
+      }
+
+      return results
+    },
+  }
+
+  return builder
+}
+
+/**
+ * Run a generator task with progress updates
+ * Parent task stays visible while sub-phases are indented below
+ */
+async function runGenerator<T>(
+  gen: Generator<ProgressInfo, T, unknown>,
+  parentHandle: TaskHandle,
+  baseTitle: string,
+  multi: MultiProgress,
+): Promise<T> {
+  let result = gen.next()
+  let currentPhase: string | undefined
+  let currentPhaseHandle: TaskHandle | null = null
+  let lastInsertId = parentHandle.id // Insert phases after parent (then after each other)
+  let phaseStartTime = Date.now()
+  const taskStartTime = Date.now()
+
+  while (!result.done) {
+    const info = result.value
+    const phase = info.phase ?? ""
+
+    // When phase changes, complete current phase and start new one (indented)
+    if (phase && phase !== currentPhase) {
+      if (currentPhaseHandle && currentPhase) {
+        // Complete previous phase with timing
+        const elapsed = Date.now() - phaseStartTime
+        const prevLabel = PHASE_LABELS[currentPhase] ?? currentPhase
+        currentPhaseHandle.complete(`${prevLabel} (${elapsed}ms)`)
+      }
+
+      // Start new phase line (indented under parent, inserted after last phase)
+      currentPhase = phase
+      phaseStartTime = Date.now()
+      const phaseLabel = PHASE_LABELS[phase] ?? phase
+      currentPhaseHandle = multi.add(phaseLabel, {
+        type: "spinner",
+        indent: 1,
+        insertAfter: lastInsertId,
+      })
+      lastInsertId = currentPhaseHandle.id
+      currentPhaseHandle.start()
+    }
+
+    // Update progress count on current phase line
+    if (currentPhaseHandle && info.total && info.total > 0) {
+      const phaseLabel = PHASE_LABELS[phase] ?? phase
+      currentPhaseHandle.setTitle(`${phaseLabel} (${info.current}/${info.total})`)
+    }
+
+    // Yield to event loop for animation
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    result = gen.next()
+  }
+
+  // Complete final phase
+  if (currentPhaseHandle && currentPhase) {
+    const elapsed = Date.now() - phaseStartTime
+    const finalLabel = PHASE_LABELS[currentPhase] ?? currentPhase
+    currentPhaseHandle.complete(`${finalLabel} (${elapsed}ms)`)
+  }
+
+  // Complete parent task with total timing
+  const totalElapsed = Date.now() - taskStartTime
+  parentHandle.complete(`${baseTitle} (${totalElapsed}ms)`)
+
+  return result.value
+}
+
+function isGenerator(value: unknown): value is Generator<ProgressInfo, unknown, unknown> {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    typeof (value as Generator).next === "function" &&
+    typeof (value as Generator).throw === "function"
+  )
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return value !== null && typeof value === "object" && typeof (value as PromiseLike<unknown>).then === "function"
+}

package/src/react/ProgressBar.tsx

@@ -0,0 +1,146 @@
+/**
+ * React ProgressBar component for silvery/Ink TUI apps
+ */
+
+import React, { useState, useEffect, useRef } from "react"
+import type { ProgressBarProps } from "../types.js"
+import { getETA, DEFAULT_ETA_BUFFER_SIZE, type ETASample } from "../utils/eta"
+
+/**
+ * Progress bar component for React TUI apps
+ *
+ * @example
+ * ```tsx
+ * import { ProgressBar } from "@silvery/ui/react";
+ *
+ * function DownloadProgress({ current, total }) {
+ *   return (
+ *     <ProgressBar
+ *       value={current}
+ *       total={total}
+ *       showPercentage
+ *       showETA
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export function ProgressBar({
+  value,
+  total,
+  width = 40,
+  showPercentage = true,
+  showETA = false,
+  label,
+  color = "cyan",
+}: ProgressBarProps): React.ReactElement {
+  // ETA calculation state
+  const [eta, setEta] = useState<string>("--:--")
+  const etaBuffer = useRef<ETASample[]>([])
+
+  // Update ETA buffer when value changes
+  useEffect(() => {
+    const now = Date.now()
+    etaBuffer.current.push({ time: now, value })
+
+    if (etaBuffer.current.length > DEFAULT_ETA_BUFFER_SIZE) {
+      etaBuffer.current.shift()
+    }
+
+    // Calculate ETA using shared utility
+    const result = getETA(etaBuffer.current, value, total)
+    setEta(result.formatted)
+  }, [value, total])
+
+  const percent = total > 0 ? value / total : 0
+  const percentDisplay = `${Math.round(percent * 100)}%`
+
+  const filledWidth = Math.round(width * percent)
+  const emptyWidth = width - filledWidth
+
+  const bar = "█".repeat(filledWidth) + "░".repeat(emptyWidth)
+
+  // Build the display parts
+  const parts: string[] = []
+
+  if (label) {
+    parts.push(label)
+  }
+
+  parts.push(`[${bar}]`)
+
+  if (showPercentage) {
+    parts.push(percentDisplay.padStart(4))
+  }
+
+  if (showETA) {
+    parts.push(`ETA: ${eta}`)
+  }
+
+  return (
+    <span data-progressx-bar data-color={color} data-percent={percent}>
+      {parts.join(" ")}
+    </span>
+  )
+}
+
+/**
+ * Hook for progress bar state management
+ *
+ * @example
+ * ```tsx
+ * function MyProgress() {
+ *   const { value, total, update, increment, eta, percent } = useProgressBar(100);
+ *
+ *   useEffect(() => {
+ *     const timer = setInterval(() => increment(), 100);
+ *     return () => clearInterval(timer);
+ *   }, []);
+ *
+ *   return <Text>{percent}% - ETA: {eta}</Text>;
+ * }
+ * ```
+ */
+export function useProgressBar(initialTotal: number) {
+  const [value, setValue] = useState(0)
+  const [total, setTotal] = useState(initialTotal)
+  const etaBuffer = useRef<ETASample[]>([])
+  const [eta, setEta] = useState<string>("--:--")
+
+  const update = (newValue: number) => {
+    setValue(newValue)
+
+    // Update ETA buffer
+    const now = Date.now()
+    etaBuffer.current.push({ time: now, value: newValue })
+    if (etaBuffer.current.length > DEFAULT_ETA_BUFFER_SIZE) {
+      etaBuffer.current.shift()
+    }
+
+    // Calculate ETA using shared utility
+    const result = getETA(etaBuffer.current, newValue, total)
+    setEta(result.formatted)
+  }
+
+  const increment = (amount = 1) => update(value + amount)
+
+  const reset = (newTotal?: number) => {
+    setValue(0)
+    if (newTotal !== undefined) setTotal(newTotal)
+    etaBuffer.current = []
+    setEta("--:--")
+  }
+
+  const percent = total > 0 ? Math.round((value / total) * 100) : 0
+
+  return {
+    value,
+    total,
+    percent,
+    eta,
+    update,
+    increment,
+    reset,
+    setTotal,
+  }
+}

package/src/react/Spinner.tsx

@@ -0,0 +1,74 @@
+/**
+ * React Spinner component for silvery/Ink TUI apps
+ */
+
+import React, { useState, useEffect } from "react"
+import type { SpinnerProps, SpinnerStyle } from "../types.js"
+import { SPINNER_FRAMES, SPINNER_INTERVALS } from "../cli/spinner"
+
+/**
+ * Animated spinner component for React TUI apps
+ *
+ * @example
+ * ```tsx
+ * import { Spinner } from "@silvery/ui/react";
+ *
+ * function LoadingView() {
+ *   return <Spinner label="Loading..." />;
+ * }
+ *
+ * // With style
+ * <Spinner label="Processing..." style="arc" color="yellow" />
+ * ```
+ */
+export function Spinner({ label, style = "dots", color = "cyan" }: SpinnerProps): React.ReactElement {
+  const [frameIndex, setFrameIndex] = useState(0)
+  const frames = SPINNER_FRAMES[style]
+  const interval = SPINNER_INTERVALS[style]
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setFrameIndex((i) => (i + 1) % frames.length)
+    }, interval)
+
+    return () => clearInterval(timer)
+  }, [frames.length, interval])
+
+  const frame = frames[frameIndex]
+
+  // Note: In a real silvery app, you'd use <Text color={color}> etc.
+  // This is a generic React component that can be styled by the consumer
+  return (
+    <span data-progressx-spinner data-color={color}>
+      {frame}
+      {label && <span> {label}</span>}
+    </span>
+  )
+}
+
+/**
+ * Hook for using spinner state in custom components
+ *
+ * @example
+ * ```tsx
+ * function CustomSpinner() {
+ *   const frame = useSpinnerFrame("dots");
+ *   return <Text color="cyan">{frame}</Text>;
+ * }
+ * ```
+ */
+export function useSpinnerFrame(style: SpinnerStyle = "dots"): string {
+  const [frameIndex, setFrameIndex] = useState(0)
+  const frames = SPINNER_FRAMES[style]
+  const interval = SPINNER_INTERVALS[style]
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setFrameIndex((i) => (i + 1) % frames.length)
+    }, interval)
+
+    return () => clearInterval(timer)
+  }, [frames.length, interval])
+
+  return frames[frameIndex]!
+}

package/src/react/Tasks.tsx

@@ -0,0 +1,144 @@
+/**
+ * React Tasks component - listr2-style task list for TUI apps
+ */
+
+import React from "react"
+import type { TaskProps, TaskStatus } from "../types.js"
+import { useSpinnerFrame } from "./Spinner"
+
+/** Status icons for tasks */
+const STATUS_ICONS: Record<TaskStatus, string> = {
+  pending: "○",
+  running: "", // Will use spinner
+  completed: "✔",
+  failed: "✖",
+  skipped: "⊘",
+}
+
+/** Status colors */
+const STATUS_COLORS: Record<TaskStatus, string> = {
+  pending: "gray",
+  running: "cyan",
+  completed: "green",
+  failed: "red",
+  skipped: "yellow",
+}
+
+/**
+ * Single task component
+ *
+ * @example
+ * ```tsx
+ * <Task title="Downloading files" status="running">
+ *   <ProgressBar value={50} total={100} />
+ * </Task>
+ * ```
+ */
+export function Task({ title, status, children }: TaskProps): React.ReactElement {
+  const spinnerFrame = useSpinnerFrame("dots")
+  const icon = status === "running" ? spinnerFrame : STATUS_ICONS[status]
+  const color = STATUS_COLORS[status]
+
+  return (
+    <div data-progressx-task data-status={status} data-color={color}>
+      <span data-icon>{icon}</span>
+      <span data-title> {title}</span>
+      {children != null ? <div data-children>{children as React.ReactNode}</div> : null}
+    </div>
+  )
+}
+
+/**
+ * Container for multiple tasks
+ *
+ * @example
+ * ```tsx
+ * <Tasks>
+ *   <Task title="Scanning files" status="completed" />
+ *   <Task title="Processing" status="running">
+ *     <ProgressBar value={current} total={total} />
+ *   </Task>
+ *   <Task title="Cleanup" status="pending" />
+ * </Tasks>
+ * ```
+ */
+export function Tasks({ children }: { children: React.ReactNode }): React.ReactElement {
+  return <div data-progressx-tasks>{children}</div>
+}
+
+/**
+ * Hook for managing task state
+ *
+ * @example
+ * ```tsx
+ * function MyTasks() {
+ *   const { tasks, start, complete, fail, updateProgress } = useTasks([
+ *     { id: 'scan', title: 'Scanning' },
+ *     { id: 'process', title: 'Processing' },
+ *   ]);
+ *
+ *   useEffect(() => {
+ *     start('scan');
+ *     doScan().then(() => {
+ *       complete('scan');
+ *       start('process');
+ *     });
+ *   }, []);
+ *
+ *   return (
+ *     <Tasks>
+ *       {tasks.map(t => <Task key={t.id} title={t.title} status={t.status} />)}
+ *     </Tasks>
+ *   );
+ * }
+ * ```
+ */
+export function useTasks(initialTasks: Array<{ id: string; title: string }>) {
+  const [tasks, setTasks] = React.useState<
+    Array<{
+      id: string
+      title: string
+      status: TaskStatus
+      progress?: { current: number; total: number }
+    }>
+  >(
+    initialTasks.map((t) => ({
+      ...t,
+      status: "pending" as TaskStatus,
+    })),
+  )
+
+  const updateTask = (
+    id: string,
+    updates: Partial<{
+      status: TaskStatus
+      title: string
+      progress: { current: number; total: number }
+    }>,
+  ) => {
+    setTasks((prev) => prev.map((t) => (t.id === id ? { ...t, ...updates } : t)))
+  }
+
+  const start = (id: string) => updateTask(id, { status: "running" })
+  const complete = (id: string, title?: string) => updateTask(id, { status: "completed", ...(title && { title }) })
+  const fail = (id: string, title?: string) => updateTask(id, { status: "failed", ...(title && { title }) })
+  const skip = (id: string, title?: string) => updateTask(id, { status: "skipped", ...(title && { title }) })
+  const updateProgress = (id: string, progress: { current: number; total: number }) => updateTask(id, { progress })
+
+  const getTask = (id: string) => tasks.find((t) => t.id === id)
+  const allCompleted = tasks.every((t) => t.status === "completed" || t.status === "skipped")
+  const hasFailed = tasks.some((t) => t.status === "failed")
+
+  return {
+    tasks,
+    start,
+    complete,
+    fail,
+    skip,
+    updateProgress,
+    updateTask,
+    getTask,
+    allCompleted,
+    hasFailed,
+  }
+}