@silvery/ui 0.3.0

package/src/cli/progress-bar.ts

@@ -0,0 +1,222 @@
+/**
+ * CLI ProgressBar - Determinate progress indicator with ETA
+ */
+
+import chalk from "chalk"
+import type { ProgressBarOptions } from "../types.js"
+import { CURSOR_HIDE, CURSOR_SHOW, CURSOR_TO_START, CLEAR_LINE_END, write, isTTY, getTerminalWidth } from "./ansi"
+import { calculateETA, formatETA, DEFAULT_ETA_BUFFER_SIZE, type ETASample } from "../utils/eta"
+
+/** Default format string */
+const DEFAULT_FORMAT = ":bar :percent | :current/:total | ETA: :eta"
+
+/**
+ * ProgressBar class for CLI progress indication
+ *
+ * @example
+ * ```ts
+ * const bar = new ProgressBar({ total: 100 });
+ * bar.start();
+ * for (let i = 0; i <= 100; i++) {
+ *   await doWork();
+ *   bar.update(i);
+ * }
+ * bar.stop();
+ * ```
+ */
+export class ProgressBar {
+  private total: number
+  private format: string
+  private width: number
+  private complete: string
+  private incomplete: string
+  private stream: NodeJS.WriteStream
+  private hideCursor: boolean
+  private phases: Record<string, string>
+
+  private current = 0
+  private phase: string | null = null
+  private startTime: number | null = null
+  private isActive = false
+
+  // ETA smoothing - track last N update times
+  private etaBuffer: ETASample[] = []
+
+  constructor(options: ProgressBarOptions = {}) {
+    this.total = options.total ?? 100
+    this.format = options.format ?? DEFAULT_FORMAT
+    this.width = options.width ?? 40
+    this.complete = options.complete ?? "█"
+    this.incomplete = options.incomplete ?? "░"
+    this.stream = options.stream ?? process.stdout
+    this.hideCursor = options.hideCursor ?? true
+    this.phases = options.phases ?? {}
+  }
+
+  /**
+   * Start the progress bar
+   */
+  start(initialValue = 0, initialTotal?: number): this {
+    if (initialTotal !== undefined) {
+      this.total = initialTotal
+    }
+
+    this.current = initialValue
+    this.startTime = Date.now()
+    this.isActive = true
+    this.etaBuffer = [{ time: this.startTime, value: initialValue }]
+
+    if (this.hideCursor && isTTY(this.stream)) {
+      write(CURSOR_HIDE, this.stream)
+    }
+
+    this.render()
+    return this
+  }
+
+  /**
+   * Update progress value
+   */
+  update(value: number, tokens?: Record<string, string | number>): this {
+    this.current = Math.min(value, this.total)
+
+    // Update ETA buffer
+    const now = Date.now()
+    this.etaBuffer.push({ time: now, value: this.current })
+    if (this.etaBuffer.length > DEFAULT_ETA_BUFFER_SIZE) {
+      this.etaBuffer.shift()
+    }
+
+    if (this.isActive) {
+      this.render(tokens)
+    }
+
+    return this
+  }
+
+  /**
+   * Increment progress by amount (default: 1)
+   */
+  increment(amount = 1, tokens?: Record<string, string | number>): this {
+    return this.update(this.current + amount, tokens)
+  }
+
+  /**
+   * Set the current phase (for multi-phase progress)
+   */
+  setPhase(phaseName: string, options?: { current?: number; total?: number }): this {
+    this.phase = phaseName
+
+    if (options?.total !== undefined) {
+      this.total = options.total
+    }
+    if (options?.current !== undefined) {
+      this.current = options.current
+      // Reset ETA buffer on phase change
+      this.etaBuffer = [{ time: Date.now(), value: this.current }]
+    }
+
+    if (this.isActive) {
+      this.render()
+    }
+
+    return this
+  }
+
+  /**
+   * Stop the progress bar
+   */
+  stop(clear = false): this {
+    if (!this.isActive) {
+      return this
+    }
+
+    this.isActive = false
+
+    if (clear && isTTY(this.stream)) {
+      write(`${CURSOR_TO_START}${CLEAR_LINE_END}`, this.stream)
+    } else {
+      write("\n", this.stream)
+    }
+
+    if (this.hideCursor && isTTY(this.stream)) {
+      write(CURSOR_SHOW, this.stream)
+    }
+
+    return this
+  }
+
+  /** Get ETA in seconds using smoothed rate */
+  private getETASeconds(): number | null {
+    return calculateETA(this.etaBuffer, this.current, this.total)
+  }
+
+  /**
+   * Render the progress bar
+   */
+  private render(tokens?: Record<string, string | number>): void {
+    const percent = this.total > 0 ? this.current / this.total : 0
+    const eta = this.getETASeconds()
+
+    // Build the bar
+    const completeLength = Math.round(this.width * percent)
+    const incompleteLength = this.width - completeLength
+    const bar = this.complete.repeat(completeLength) + this.incomplete.repeat(incompleteLength)
+
+    // Get phase display name
+    const phaseDisplay = this.phase ? (this.phases[this.phase] ?? this.phase) : ""
+
+    // Calculate rate
+    const elapsed = this.startTime ? (Date.now() - this.startTime) / 1000 : 0
+    const rate = elapsed > 0 ? this.current / elapsed : 0
+
+    // Replace tokens in format string
+    let output = this.format
+      .replace(":bar", chalk.cyan(bar))
+      .replace(":percent", `${Math.round(percent * 100)}%`.padStart(4))
+      .replace(":current", String(this.current))
+      .replace(":total", String(this.total))
+      .replace(":eta", formatETA(eta))
+      .replace(":elapsed", formatETA(elapsed))
+      .replace(":rate", rate.toFixed(1))
+      .replace(":phase", chalk.dim(phaseDisplay))
+
+    // Replace custom tokens
+    if (tokens) {
+      for (const [key, value] of Object.entries(tokens)) {
+        output = output.replace(`:${key}`, String(value))
+      }
+    }
+
+    // Truncate to terminal width
+    const termWidth = getTerminalWidth(this.stream)
+    if (output.length > termWidth) {
+      output = output.slice(0, termWidth - 1)
+    }
+
+    if (isTTY(this.stream)) {
+      write(`${CURSOR_TO_START}${output}${CLEAR_LINE_END}`, this.stream)
+    }
+  }
+
+  /**
+   * Get current progress ratio (0-1)
+   */
+  get ratio(): number {
+    return this.total > 0 ? this.current / this.total : 0
+  }
+
+  /**
+   * Get current progress percentage (0-100)
+   */
+  get percentage(): number {
+    return Math.round(this.ratio * 100)
+  }
+
+  /**
+   * Dispose the progress bar (calls stop)
+   */
+  [Symbol.dispose](): void {
+    this.stop()
+  }
+}

package/src/cli/spinner.ts

@@ -0,0 +1,275 @@
+/**
+ * CLI Spinner - Animated indeterminate progress indicator
+ */
+
+import chalk from "chalk"
+import type { SpinnerOptions, SpinnerStyle } from "../types.js"
+import { CURSOR_HIDE, CURSOR_SHOW, CURSOR_TO_START, CLEAR_LINE_END, write, isTTY } from "./ansi"
+
+/** Spinner animation frames by style */
+export const SPINNER_FRAMES: Record<SpinnerStyle, string[]> = {
+  dots: ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
+  line: ["-", "\\", "|", "/"],
+  arc: ["◜", "◠", "◝", "◞", "◡", "◟"],
+  bounce: ["⠁", "⠂", "⠄", "⠂"],
+  pulse: ["█", "▓", "▒", "░", "▒", "▓"],
+}
+
+/** Default intervals for each style (ms) */
+export const SPINNER_INTERVALS: Record<SpinnerStyle, number> = {
+  dots: 80,
+  line: 120,
+  arc: 100,
+  bounce: 120,
+  pulse: 100,
+}
+
+/**
+ * Spinner class for CLI progress indication
+ *
+ * @example
+ * ```ts
+ * const spinner = new Spinner("Loading...");
+ * spinner.start();
+ * await doWork();
+ * spinner.succeed("Done!");
+ * ```
+ */
+export class Spinner {
+  private text: string
+  private style: SpinnerStyle
+  private color: string
+  private stream: NodeJS.WriteStream
+  private hideCursor: boolean
+  private interval: number
+
+  private frameIndex = 0
+  private timer: ReturnType<typeof setInterval> | null = null
+  private isSpinning = false
+
+  constructor(textOrOptions?: string | SpinnerOptions) {
+    const options: SpinnerOptions = typeof textOrOptions === "string" ? { text: textOrOptions } : (textOrOptions ?? {})
+
+    this.text = options.text ?? ""
+    this.style = options.style ?? "dots"
+    this.color = options.color ?? "cyan"
+    this.stream = options.stream ?? process.stdout
+    this.hideCursor = options.hideCursor ?? true
+    this.interval = options.interval ?? SPINNER_INTERVALS[this.style]
+  }
+
+  /** Get current spinner text */
+  get currentText(): string {
+    return this.text
+  }
+
+  /** Set spinner text (updates immediately if spinning) */
+  set currentText(value: string) {
+    this.text = value
+    if (this.isSpinning) {
+      this.render()
+    }
+  }
+
+  /** Check if spinner is currently active */
+  get spinning(): boolean {
+    return this.isSpinning
+  }
+
+  /**
+   * Start the spinner animation
+   */
+  start(text?: string): this {
+    if (text !== undefined) {
+      this.text = text
+    }
+
+    if (this.isSpinning) {
+      return this
+    }
+
+    this.isSpinning = true
+    this.frameIndex = 0
+
+    if (this.hideCursor && isTTY(this.stream)) {
+      write(CURSOR_HIDE, this.stream)
+    }
+
+    this.render()
+    this.timer = setInterval(() => {
+      this.frameIndex = (this.frameIndex + 1) % SPINNER_FRAMES[this.style].length
+      this.render()
+    }, this.interval)
+
+    return this
+  }
+
+  /**
+   * Stop the spinner
+   */
+  stop(): this {
+    if (!this.isSpinning) {
+      return this
+    }
+
+    this.isSpinning = false
+
+    if (this.timer) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+
+    this.clear()
+
+    if (this.hideCursor && isTTY(this.stream)) {
+      write(CURSOR_SHOW, this.stream)
+    }
+
+    return this
+  }
+
+  /**
+   * Stop with success message (green checkmark)
+   */
+  succeed(text?: string): this {
+    return this.stopWithSymbol(chalk.green("✔"), text ?? this.text)
+  }
+
+  /**
+   * Stop with failure message (red X)
+   */
+  fail(text?: string): this {
+    return this.stopWithSymbol(chalk.red("✖"), text ?? this.text)
+  }
+
+  /**
+   * Stop with warning message (yellow warning)
+   */
+  warn(text?: string): this {
+    return this.stopWithSymbol(chalk.yellow("⚠"), text ?? this.text)
+  }
+
+  /**
+   * Stop with info message (blue info)
+   */
+  info(text?: string): this {
+    return this.stopWithSymbol(chalk.blue("ℹ"), text ?? this.text)
+  }
+
+  /**
+   * Clear the spinner line
+   */
+  clear(): this {
+    if (isTTY(this.stream)) {
+      write(`${CURSOR_TO_START}${CLEAR_LINE_END}`, this.stream)
+    }
+    return this
+  }
+
+  private render(): void {
+    const frame = SPINNER_FRAMES[this.style][this.frameIndex]
+    const colorFn = (chalk as unknown as Record<string, (s: string) => string>)[this.color]
+    const coloredFrame = colorFn ? colorFn(frame!) : frame!
+    const output = this.text ? `${coloredFrame} ${this.text}` : coloredFrame
+
+    if (isTTY(this.stream)) {
+      write(`${CURSOR_TO_START}${output}${CLEAR_LINE_END}`, this.stream)
+    }
+  }
+
+  private stopWithSymbol(symbol: string, text: string): this {
+    this.stop()
+    write(`${symbol} ${text}\n`, this.stream)
+    return this
+  }
+
+  /**
+   * Dispose the spinner (calls stop)
+   */
+  [Symbol.dispose](): void {
+    this.stop()
+  }
+
+  /**
+   * Static helper to quickly start a spinner
+   * Returns a stop function
+   *
+   * @example
+   * ```ts
+   * const stop = Spinner.start("Loading...");
+   * await doWork();
+   * stop();
+   * ```
+   */
+  static start(textOrOptions?: string | SpinnerOptions): () => void {
+    const spinner = new Spinner(textOrOptions)
+    spinner.start()
+    return () => spinner.stop()
+  }
+}
+
+/**
+ * Callable spinner interface - call with text to show/update
+ *
+ * @example
+ * ```ts
+ * {
+ *   using spinner = createSpinner({ style: "dots" });
+ *   spinner("Loading...");  // Shows spinner with text
+ *   spinner("Still loading...");  // Updates text
+ * } // Auto-stops via Symbol.dispose
+ * ```
+ */
+export interface CallableSpinner extends Disposable {
+  /** Call with text to show/update the spinner */
+  (text: string): void
+  /** Stop the spinner */
+  stop(): void
+  /** Stop with success message (green checkmark) */
+  succeed(text?: string): void
+  /** Stop with failure message (red X) */
+  fail(text?: string): void
+  /** Stop with warning message (yellow warning) */
+  warn(text?: string): void
+  /** Stop with info message (blue info) */
+  info(text?: string): void
+}
+
+/**
+ * Create a callable, disposable spinner
+ *
+ * The spinner is lazy - it won't show anything until you call it with text.
+ * Use with `using` for automatic cleanup:
+ *
+ * @example
+ * ```ts
+ * {
+ *   using spinner = createSpinner({ style: "dots" });
+ *   // Nothing visible yet
+ *
+ *   spinner("Loading repo...");  // Now shows spinner
+ *   spinner("Applying events...");  // Updates text
+ * } // Auto-stops via Symbol.dispose
+ * ```
+ */
+export function createSpinner(options?: SpinnerOptions): CallableSpinner {
+  const spinner = new Spinner({ ...options, text: "" })
+
+  const callable = ((text: string) => {
+    // Always restart if not spinning (handles initial call and after succeed/fail/etc)
+    if (!spinner.spinning) {
+      spinner.start(text)
+    } else {
+      spinner.currentText = text
+    }
+  }) as CallableSpinner
+
+  callable.stop = () => spinner.stop()
+  callable.succeed = (text) => spinner.succeed(text)
+  callable.fail = (text) => spinner.fail(text)
+  callable.warn = (text) => spinner.warn(text)
+  callable.info = (text) => spinner.info(text)
+  callable[Symbol.dispose] = () => spinner.stop()
+
+  return callable
+}

package/src/components/Badge.tsx

@@ -0,0 +1,54 @@
+/**
+ * Badge Component
+ *
+ * A small inline label for status display.
+ *
+ * Usage:
+ * ```tsx
+ * <Badge label="Active" variant="success" />
+ * <Badge label="Warning" variant="warning" />
+ * <Badge label="Custom" color="magenta" />
+ * ```
+ */
+import React from "react"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface BadgeProps {
+  /** Badge text */
+  label: string
+  /** Color variant */
+  variant?: "default" | "primary" | "success" | "warning" | "error"
+  /** Custom color (overrides variant) */
+  color?: string
+}
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+const VARIANT_COLORS: Record<NonNullable<BadgeProps["variant"]>, string> = {
+  default: "$fg",
+  primary: "$primary",
+  success: "$success",
+  warning: "$warning",
+  error: "$error",
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+export function Badge({ label, variant = "default", color }: BadgeProps): React.ReactElement {
+  const resolvedColor = color ?? VARIANT_COLORS[variant]
+
+  return (
+    <Text color={resolvedColor} bold>
+      {" "}
+      {label}{" "}
+    </Text>
+  )
+}

package/src/components/Breadcrumb.tsx

@@ -0,0 +1,72 @@
+/**
+ * Breadcrumb Component
+ *
+ * Navigation breadcrumb trail with configurable separators.
+ * Highlights the last item as the current/active page.
+ *
+ * Usage:
+ * ```tsx
+ * <Breadcrumb
+ *   items={[
+ *     { label: "Home" },
+ *     { label: "Settings" },
+ *     { label: "Profile" },
+ *   ]}
+ *   separator=">"
+ * />
+ * // Renders: Home > Settings > Profile
+ * ```
+ */
+import React from "react"
+import { Box } from "@silvery/react/components/Box"
+import { Text } from "@silvery/react/components/Text"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface BreadcrumbItem {
+  /** Display label */
+  label: string
+}
+
+export interface BreadcrumbProps {
+  /** Breadcrumb items (left to right) */
+  items: BreadcrumbItem[]
+  /** Separator character between items (default: "/") */
+  separator?: string
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Horizontal breadcrumb trail.
+ *
+ * Renders items separated by a configurable separator character.
+ * The last item is rendered in bold `$fg` as the current location;
+ * preceding items are rendered in `$muted`.
+ */
+export function Breadcrumb({ items, separator = "/" }: BreadcrumbProps): React.ReactElement {
+  if (items.length === 0) {
+    return <Box />
+  }
+
+  return (
+    <Box>
+      {items.map((item, i) => {
+        const isLast = i === items.length - 1
+
+        return (
+          <React.Fragment key={i}>
+            {i > 0 && <Text color="$disabledfg"> {separator} </Text>}
+            <Text color={isLast ? "$fg" : "$muted"} bold={isLast}>
+              {item.label}
+            </Text>
+          </React.Fragment>
+        )
+      })}
+    </Box>
+  )
+}

package/src/components/Button.tsx

@@ -0,0 +1,73 @@
+/**
+ * Button Component
+ *
+ * A focusable button control. Integrates with the silvery focus system
+ * and responds to Enter or Space key to activate.
+ *
+ * Usage:
+ * ```tsx
+ * <Button label="Save" onPress={() => save()} />
+ * <Button label="Cancel" onPress={() => close()} color="red" />
+ *
+ * // With explicit active control (bypasses focus system)
+ * <Button label="OK" onPress={confirm} isActive={hasFocus} />
+ * ```
+ */
+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 ButtonProps {
+  /** Button label */
+  label: string
+  /** Called when activated (Enter or Space) */
+  onPress: () => void
+  /** Whether input is active (default: from focus system) */
+  isActive?: boolean
+  /** Test ID for focus system */
+  testID?: string
+  /** Button color */
+  color?: string
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Focusable button control.
+ *
+ * Renders `[ label ]` with inverse styling when focused. Activates on
+ * Enter or Space key press.
+ */
+export function Button({ label, onPress, isActive, testID, color }: ButtonProps): React.ReactElement {
+  const { focused } = useFocusable()
+
+  // isActive prop overrides focus state (same pattern as TextInput)
+  const active = isActive ?? focused
+
+  useInput(
+    (_input, key) => {
+      if (key.return || (_input === " " && !key.ctrl && !key.meta && !key.shift)) {
+        onPress()
+      }
+    },
+    { isActive: active },
+  )
+
+  return (
+    <Box focusable testID={testID}>
+      <Text color={color} inverse={active}>
+        {"[ "}
+        {label}
+        {" ]"}
+      </Text>
+    </Box>
+  )
+}