@silvery/ui 0.3.0

package/src/react/context.tsx

@@ -0,0 +1,145 @@
+/**
+ * React context for progress state management
+ */
+
+import React, { createContext, useContext, useState, useCallback } from "react"
+import type { SpinnerStyle } from "../types.js"
+import { Spinner } from "./Spinner"
+
+/** Progress context state */
+interface ProgressContextState {
+  /** Currently showing a spinner */
+  isLoading: boolean
+  /** Loading message */
+  loadingText: string
+  /** Spinner style */
+  spinnerStyle: SpinnerStyle
+
+  /** Show a spinner with message */
+  showSpinner: (text: string, style?: SpinnerStyle) => void
+  /** Hide the spinner */
+  hideSpinner: () => void
+
+  /** Progress bar state */
+  progress: { current: number; total: number } | null
+  /** Update progress */
+  updateProgress: (current: number, total?: number) => void
+  /** Clear progress */
+  clearProgress: () => void
+}
+
+const ProgressContext = createContext<ProgressContextState | null>(null)
+
+/**
+ * Progress context provider
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <ProgressProvider>
+ *       <MyApp />
+ *     </ProgressProvider>
+ *   );
+ * }
+ *
+ * function DeepComponent() {
+ *   const { showSpinner, hideSpinner } = useProgress();
+ *
+ *   const handleLoad = async () => {
+ *     showSpinner("Loading...");
+ *     await loadData();
+ *     hideSpinner();
+ *   };
+ * }
+ * ```
+ */
+export function ProgressProvider({ children }: { children: React.ReactNode }): React.ReactElement {
+  const [isLoading, setIsLoading] = useState(false)
+  const [loadingText, setLoadingText] = useState("")
+  const [spinnerStyle, setSpinnerStyle] = useState<SpinnerStyle>("dots")
+  const [progress, setProgress] = useState<{
+    current: number
+    total: number
+  } | null>(null)
+
+  const showSpinner = useCallback((text: string, style: SpinnerStyle = "dots") => {
+    setLoadingText(text)
+    setSpinnerStyle(style)
+    setIsLoading(true)
+  }, [])
+
+  const hideSpinner = useCallback(() => {
+    setIsLoading(false)
+    setLoadingText("")
+  }, [])
+
+  const updateProgress = useCallback((current: number, total?: number) => {
+    setProgress((prev) => ({
+      current,
+      total: total ?? prev?.total ?? 100,
+    }))
+  }, [])
+
+  const clearProgress = useCallback(() => {
+    setProgress(null)
+  }, [])
+
+  const value: ProgressContextState = {
+    isLoading,
+    loadingText,
+    spinnerStyle,
+    showSpinner,
+    hideSpinner,
+    progress,
+    updateProgress,
+    clearProgress,
+  }
+
+  return <ProgressContext.Provider value={value}>{children}</ProgressContext.Provider>
+}
+
+/**
+ * Hook to access progress context
+ *
+ * @example
+ * ```tsx
+ * function LoadingOverlay() {
+ *   const { isLoading, loadingText, spinnerStyle } = useProgress();
+ *
+ *   if (!isLoading) return null;
+ *
+ *   return <Spinner label={loadingText} style={spinnerStyle} />;
+ * }
+ * ```
+ */
+export function useProgress(): ProgressContextState {
+  const context = useContext(ProgressContext)
+
+  if (!context) {
+    throw new Error("useProgress must be used within a ProgressProvider")
+  }
+
+  return context
+}
+
+/**
+ * Component that renders spinner when loading
+ *
+ * @example
+ * ```tsx
+ * <ProgressProvider>
+ *   <ProgressIndicator />
+ *   <MainContent />
+ * </ProgressProvider>
+ * ```
+ */
+export function ProgressIndicator(): React.ReactElement | null {
+  const { isLoading, loadingText, spinnerStyle } = useProgress()
+
+  if (!isLoading) {
+    return null
+  }
+
+  return <Spinner label={loadingText} style={spinnerStyle} />
+}

package/src/react/index.ts

@@ -0,0 +1,30 @@
+/**
+ * React components for TUI progress indicators
+ *
+ * @example
+ * ```tsx
+ * import { Spinner, ProgressBar, Tasks, Task, useProgress } from "@silvery/ui/react";
+ *
+ * // Spinner
+ * <Spinner label="Loading..." style="dots" />
+ *
+ * // Progress bar
+ * <ProgressBar value={50} total={100} showPercentage showETA />
+ *
+ * // Task list
+ * <Tasks>
+ *   <Task title="Scanning" status="completed" />
+ *   <Task title="Processing" status="running" />
+ * </Tasks>
+ *
+ * // Context for nested components
+ * <ProgressProvider>
+ *   <App />
+ * </ProgressProvider>
+ * ```
+ */
+
+export { Spinner, useSpinnerFrame } from "./Spinner"
+export { ProgressBar, useProgressBar } from "./ProgressBar"
+export { Task, Tasks, useTasks } from "./Tasks"
+export { ProgressProvider, useProgress, ProgressIndicator } from "./context"

package/src/types.ts

@@ -0,0 +1,252 @@
+/**
+ * Core types for silvery-ui progress components
+ */
+
+/** Progress info passed to callbacks (legacy, use StepProgress for steps()) */
+export interface ProgressInfo {
+  phase?: string
+  current: number
+  total: number
+  detail?: string
+}
+
+/**
+ * Progress info yielded from step generators
+ *
+ * Yield with `label` to create/update a sub-step:
+ * ```typescript
+ * function* loadRepo() {
+ *   yield { label: "Discovering files" };
+ *   // ... do work ...
+ *   yield { label: "Parsing markdown", current: 0, total: 100 };
+ *   // ... do work ...
+ *   yield { label: "Parsing markdown", current: 100, total: 100 };
+ * }
+ * ```
+ */
+export interface StepProgress {
+  /** Display label for sub-step (changing label creates new sub-step) */
+  label?: string
+  /** Current progress count */
+  current?: number
+  /** Total count for progress display */
+  total?: number
+}
+
+/** Callback signature for progress reporting */
+export type ProgressCallback = (info: ProgressInfo) => void
+
+/** Generator that yields progress info */
+export type ProgressGenerator<T = void> = Generator<{ current: number; total: number }, T, unknown>
+
+/** Spinner animation styles */
+export type SpinnerStyle = "dots" | "line" | "arc" | "bounce" | "pulse"
+
+/** Task status for multi-task display */
+export type TaskStatus = "pending" | "running" | "completed" | "failed" | "skipped"
+
+/** Options for Spinner class */
+export interface SpinnerOptions {
+  /** Initial text to display */
+  text?: string
+  /** Animation style */
+  style?: SpinnerStyle
+  /** Spinner color (chalk color name) */
+  color?: string
+  /** Output stream (default: process.stdout) */
+  stream?: NodeJS.WriteStream
+  /** Hide cursor during spinner (default: true) */
+  hideCursor?: boolean
+  /** Animation interval in ms (default: 80) */
+  interval?: number
+}
+
+/** Options for ProgressBar class */
+export interface ProgressBarOptions {
+  /** Total value for progress calculation */
+  total?: number
+  /** Format string with placeholders: :bar :percent :current :total :eta :rate :phase */
+  format?: string
+  /** Width of the progress bar in characters (default: 40) */
+  width?: number
+  /** Character for completed portion (default: "█") */
+  complete?: string
+  /** Character for incomplete portion (default: "░") */
+  incomplete?: string
+  /** Show percentage (default: true) */
+  showPercentage?: boolean
+  /** Show ETA (default: true) */
+  showETA?: boolean
+  /** Output stream (default: process.stdout) */
+  stream?: NodeJS.WriteStream
+  /** Hide cursor during progress (default: true) */
+  hideCursor?: boolean
+  /** Phase names for multi-phase progress */
+  phases?: Record<string, string>
+}
+
+/** Options for withSpinner wrapper */
+export interface WithSpinnerOptions {
+  /** Spinner style */
+  style?: SpinnerStyle
+  /** Clear the spinner output on completion */
+  clearOnComplete?: boolean
+  /** Color for the spinner */
+  color?: string
+}
+
+/** Options for withProgress wrapper */
+export interface WithProgressOptions {
+  /** Map of phase keys to display names */
+  phases?: Record<string, string>
+  /** Format string for progress bar */
+  format?: string
+  /** Clear output on completion */
+  clearOnComplete?: boolean
+  /** Show initial loading message after this many ms (default: 1000). Set to 0 to show immediately. */
+  showAfter?: number
+  /** Initial loading message to show before progress starts (default: "Loading...") */
+  initialMessage?: string
+}
+
+/** Task state for Tasks component */
+export interface TaskState {
+  id: string
+  title: string
+  status: TaskStatus
+  progress?: { current: number; total: number }
+  error?: Error
+  children?: TaskState[]
+}
+
+/** Props for React Spinner component */
+export interface SpinnerProps {
+  /** Label text to display */
+  label?: string
+  /** Animation style */
+  style?: SpinnerStyle
+  /** Spinner color */
+  color?: string
+}
+
+/** Props for React ProgressBar component */
+export interface ProgressBarProps {
+  /** Current value */
+  value: number
+  /** Total value */
+  total: number
+  /** Width in characters */
+  width?: number
+  /** Show percentage */
+  showPercentage?: boolean
+  /** Show ETA */
+  showETA?: boolean
+  /** Label text */
+  label?: string
+  /** Color for completed portion */
+  color?: string
+}
+
+/** Props for React Task component */
+export interface TaskProps {
+  /** Task title */
+  title: string
+  /** Task status */
+  status: TaskStatus
+  /** Children (e.g., nested progress bar) */
+  children?: React.ReactNode
+}
+
+/** Props for React TextInput component */
+export interface TextInputProps {
+  /** Current input value (controlled) */
+  value: string
+  /** Called when value changes */
+  onChange: (value: string) => void
+  /** Placeholder text when empty */
+  placeholder?: string
+  /** Mask character for password input (e.g., "*") */
+  mask?: string
+  /** Autocomplete suggestions */
+  autocomplete?: string[]
+  /** Called when autocomplete suggestion is selected */
+  onAutocomplete?: (suggestion: string) => void
+  /** Called when Enter is pressed */
+  onSubmit?: (value: string) => void
+  /** Cursor position (for rendering) */
+  cursorPosition?: number
+  /** Whether input is focused */
+  focused?: boolean
+}
+
+/** Options for withTextInput CLI wrapper */
+export interface TextInputOptions {
+  /** Placeholder text shown when input is empty */
+  placeholder?: string
+  /** Mask character for password input (e.g., "*") */
+  mask?: string
+  /** Validation function - return error message or undefined if valid */
+  validate?: (value: string) => string | undefined
+  /** Autocomplete suggestions */
+  autocomplete?: string[]
+  /** Default value */
+  defaultValue?: string
+  /** Output stream (default: process.stdout) */
+  stream?: NodeJS.WriteStream
+  /** Input stream (default: process.stdin) */
+  inputStream?: NodeJS.ReadStream
+}
+
+/** Column definition for Table component */
+export interface TableColumn {
+  /** Key in data objects to display */
+  key: string
+  /** Header text */
+  header: string
+  /** Fixed column width (auto-calculated from content if not specified) */
+  width?: number
+  /** Text alignment within the column */
+  align?: "left" | "center" | "right"
+}
+
+/** Props for React Table component */
+export interface TableProps {
+  /** Column definitions */
+  columns: TableColumn[]
+  /** Data rows to display */
+  data: Array<Record<string, unknown>>
+  /** Show box borders around cells */
+  border?: boolean
+}
+
+/** Option for Select component */
+export interface SelectOption<T> {
+  /** Display text for this option */
+  label: string
+  /** Value returned when selected */
+  value: T
+}
+
+/** Props for React Select component */
+export interface SelectProps<T> {
+  /** Available options */
+  options: SelectOption<T>[]
+  /** Currently selected value */
+  value?: T
+  /** Called when selection changes */
+  onChange?: (value: T) => void
+  /** Maximum number of visible options (default: 10) */
+  maxVisible?: number
+  /** Controlled highlight index for keyboard navigation */
+  highlightIndex?: number
+  /** Called when highlight index changes */
+  onHighlightChange?: (index: number) => void
+}
+
+/** Options for withSelect CLI wrapper */
+export interface WithSelectOptions {
+  /** Initial highlighted index (default: 0) */
+  initial?: number
+  /** Maximum number of visible options (default: 10) */
+  maxVisible?: number
+}

package/src/utils/eta.ts

@@ -0,0 +1,155 @@
+/**
+ * Shared ETA calculation utilities
+ */
+
+/** Sample point for ETA calculation */
+export interface ETASample {
+  time: number
+  value: number
+}
+
+/** ETA calculation result */
+export interface ETAResult {
+  /** Estimated seconds remaining, or null if insufficient data */
+  seconds: number | null
+  /** Formatted ETA string (e.g., "1:30", "2:15:30", "--:--") */
+  formatted: string
+}
+
+/**
+ * Calculate ETA from a buffer of samples
+ *
+ * @param buffer - Array of {time, value} samples
+ * @param current - Current progress value
+ * @param total - Total target value
+ * @returns ETA in seconds (null if insufficient data)
+ *
+ * @example
+ * ```ts
+ * const buffer = [
+ *   { time: 1000, value: 0 },
+ *   { time: 2000, value: 10 },
+ * ];
+ * const eta = calculateETA(buffer, 10, 100);
+ * // eta = 9 (9 seconds remaining at 10 items/sec)
+ * ```
+ */
+export function calculateETA(buffer: ETASample[], current: number, total: number): number | null {
+  if (buffer.length < 2) {
+    return null
+  }
+
+  const first = buffer[0]!
+  const last = buffer[buffer.length - 1]!
+
+  const elapsed = (last.time - first.time) / 1000 // seconds
+  const progress = last.value - first.value
+
+  if (elapsed <= 0 || progress <= 0) {
+    return null
+  }
+
+  const rate = progress / elapsed // items per second
+  const remaining = total - current
+
+  return remaining / rate
+}
+
+/**
+ * Format ETA seconds as human-readable string
+ *
+ * @param eta - ETA in seconds (null for unknown)
+ * @returns Formatted string (e.g., "1:30", "2:15:30", "--:--", ">1d")
+ *
+ * @example
+ * ```ts
+ * formatETA(90)    // "1:30"
+ * formatETA(3665)  // "1:01:05"
+ * formatETA(null)  // "--:--"
+ * formatETA(100000) // ">1d"
+ * ```
+ */
+export function formatETA(eta: number | null): string {
+  if (eta === null || !isFinite(eta)) {
+    return "--:--"
+  }
+
+  if (eta > 86400) {
+    // > 24 hours
+    return ">1d"
+  }
+
+  const hours = Math.floor(eta / 3600)
+  const minutes = Math.floor((eta % 3600) / 60)
+  const seconds = Math.floor(eta % 60)
+
+  if (hours > 0) {
+    return `${hours}:${minutes.toString().padStart(2, "0")}:${seconds.toString().padStart(2, "0")}`
+  }
+
+  return `${minutes}:${seconds.toString().padStart(2, "0")}`
+}
+
+/**
+ * Calculate and format ETA in one call
+ *
+ * @param buffer - Array of {time, value} samples
+ * @param current - Current progress value
+ * @param total - Total target value
+ * @returns Object with seconds (number|null) and formatted string
+ */
+export function getETA(buffer: ETASample[], current: number, total: number): ETAResult {
+  const seconds = calculateETA(buffer, current, total)
+  return {
+    seconds,
+    formatted: formatETA(seconds),
+  }
+}
+
+/** Default buffer size for ETA smoothing */
+export const DEFAULT_ETA_BUFFER_SIZE = 10
+
+/**
+ * Create an ETA tracker with automatic buffer management
+ *
+ * @param bufferSize - Number of samples to keep (default: 10)
+ * @returns ETA tracker object
+ *
+ * @example
+ * ```ts
+ * const tracker = createETATracker();
+ * tracker.record(0);
+ * // ... later ...
+ * tracker.record(50);
+ * const eta = tracker.getETA(50, 100);
+ * console.log(eta.formatted); // "0:30"
+ * ```
+ */
+export function createETATracker(bufferSize = DEFAULT_ETA_BUFFER_SIZE) {
+  const buffer: ETASample[] = []
+
+  return {
+    /** Record a new sample */
+    record(value: number): void {
+      buffer.push({ time: Date.now(), value })
+      if (buffer.length > bufferSize) {
+        buffer.shift()
+      }
+    },
+
+    /** Get current ETA */
+    getETA(current: number, total: number): ETAResult {
+      return getETA(buffer, current, total)
+    },
+
+    /** Reset the buffer */
+    reset(): void {
+      buffer.length = 0
+    },
+
+    /** Get buffer for external use */
+    getBuffer(): readonly ETASample[] {
+      return buffer
+    },
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared utilities
+ */
+
+export {
+  calculateETA,
+  formatETA,
+  getETA,
+  createETATracker,
+  DEFAULT_ETA_BUFFER_SIZE,
+  type ETASample,
+  type ETAResult,
+} from "./eta"

package/src/wrappers/index.ts

@@ -0,0 +1,36 @@
+/**
+ * Progress wrappers - Adapt existing async patterns
+ *
+ * @example
+ * ```ts
+ * import {
+ *   withSpinner,
+ *   withProgress,
+ *   wrapGenerator,
+ *   wrapEmitter
+ * } from "@silvery/ui/wrappers";
+ *
+ * // Wrap any promise
+ * const data = await withSpinner(fetchData(), "Loading...");
+ *
+ * // Wrap callback-based APIs (like km sync)
+ * await withProgress(
+ *   (onProgress) => manager.syncFromFs(onProgress),
+ *   { phases: { scanning: "Scanning", reconciling: "Reconciling" } }
+ * );
+ *
+ * // Wrap generators
+ * await wrapGenerator(evaluateAllRules(), "Evaluating rules");
+ *
+ * // Track EventEmitter state
+ * wrapEmitter(manager, { events: { ready: { succeed: true } } });
+ * ```
+ */
+
+export { withSpinner, attachSpinner } from "./with-spinner"
+export { withProgress, createProgressCallback } from "./with-progress"
+export { wrapGenerator, withIterableProgress } from "./wrap-generator"
+export { wrapEmitter, waitForEvent } from "./wrap-emitter"
+export { withSelect, createSelect } from "./with-select"
+export { withTextInput, createTextInput } from "./with-text-input"
+export type { ProgressCallback, ProgressInfo, TextInputOptions } from "../types.js"