@silvery/ui 0.3.0

package/src/wrappers/with-progress.ts

@@ -0,0 +1,250 @@
+/**
+ * withProgress - Wrap callback-based progress functions
+ *
+ * @deprecated Use `steps()` from `@silvery/ui/progress` instead.
+ *
+ * @example
+ * ```typescript
+ * // OLD (deprecated):
+ * import { withProgress } from "@silvery/ui/wrappers";
+ * const result = await withProgress(
+ *   (onProgress) => manager.syncFromFs(onProgress),
+ *   { phases: SYNC_PHASES }
+ * );
+ *
+ * // NEW:
+ * import { steps } from "@silvery/ui/progress";
+ * const results = await steps({ syncFiles: () => manager.syncFromFs() }).run();
+ * ```
+ */
+
+import type { ProgressInfo, ProgressCallback, WithProgressOptions } from "../types.js"
+import { ProgressBar } from "../cli/progress-bar"
+import { Spinner } from "../cli/spinner"
+import { CURSOR_HIDE, CURSOR_SHOW, write, isTTY } from "../cli/ansi"
+
+// Declare timer globals (not exposed by bun-types)
+declare function setTimeout(callback: () => void, ms: number): unknown
+declare function clearTimeout(id: unknown): void
+
+// Timer type - opaque handle, we only store and clear it
+type TimerId = unknown
+
+/**
+ * Wrap a function that takes a progress callback
+ *
+ * @example
+ * ```ts
+ * // Wrap existing km sync API
+ * const result = await withProgress(
+ *   (onProgress) => manager.syncFromFs(onProgress),
+ *   {
+ *     phases: {
+ *       scanning: "Scanning files",
+ *       reconciling: "Reconciling changes",
+ *       rules: "Evaluating rules"
+ *     }
+ *   }
+ * );
+ *
+ * // Simple usage without phases
+ * await withProgress((onProgress) => rebuildState(onProgress));
+ *
+ * // With custom format
+ * await withProgress(
+ *   (p) => processFiles(p),
+ *   { format: ":phase :bar :percent" }
+ * );
+ *
+ * // Show loading immediately (showAfter: 0) or after delay
+ * await withProgress(
+ *   (p) => slowOperation(p),
+ *   { showAfter: 1000, initialMessage: "Loading..." }
+ * );
+ * ```
+ */
+export async function withProgress<T>(
+  fn: (onProgress: ProgressCallback) => T | Promise<T>,
+  options: WithProgressOptions = {},
+): Promise<T> {
+  const stream = process.stdout
+  const isTty = isTTY(stream)
+
+  // Determine format
+  const format =
+    options.format ?? (options.phases ? ":phase [:bar] :current/:total" : "[:bar] :current/:total :percent")
+
+  const bar = new ProgressBar({
+    format,
+    phases: options.phases ?? {},
+    hideCursor: true,
+  })
+
+  let lastPhase: string | null = null
+  let started = false
+
+  // Initial spinner (shown before progress starts)
+  const showAfter = options.showAfter ?? 1000
+  const initialMessage = options.initialMessage ?? "Loading..."
+  let spinner: Spinner | null = null
+  let spinnerTimerId: TimerId | null = null
+
+  // Hide cursor
+  if (isTty) {
+    write(CURSOR_HIDE, stream)
+  }
+
+  // Schedule initial spinner if configured
+  if (isTty && showAfter >= 0) {
+    spinnerTimerId = setTimeout(() => {
+      if (!started) {
+        spinner = new Spinner({ text: initialMessage })
+        spinner.start()
+      }
+    }, showAfter)
+  }
+
+  const onProgress: ProgressCallback = (info: ProgressInfo) => {
+    // Stop initial spinner if it was shown
+    if (spinner) {
+      spinner.stop()
+      spinner = null
+    }
+    if (spinnerTimerId !== null) {
+      clearTimeout(spinnerTimerId)
+      spinnerTimerId = null
+    }
+
+    // Handle phase transitions
+    if (info.phase && info.phase !== lastPhase) {
+      if (lastPhase !== null && isTty) {
+        // Print newline before switching phases
+        write("\n", stream)
+      }
+      lastPhase = info.phase
+
+      // Start or update bar with new phase
+      if (!started) {
+        bar.start(info.current, info.total)
+        started = true
+      }
+      bar.setPhase(info.phase, { current: info.current, total: info.total })
+    } else {
+      if (!started) {
+        bar.start(info.current, info.total)
+        started = true
+      }
+      bar.update(info.current)
+    }
+  }
+
+  try {
+    const result = await fn(onProgress)
+
+    // Clean up spinner if still pending
+    if (spinnerTimerId !== null) {
+      clearTimeout(spinnerTimerId)
+    }
+    // Note: spinner may be set by setTimeout callback - TS can't track this
+    const pendingSpinner = spinner as unknown as Spinner | null
+    if (pendingSpinner) {
+      pendingSpinner.stop()
+    }
+
+    // Stop and show cursor
+    if (started) {
+      bar.stop(options.clearOnComplete)
+    }
+    if (isTty) {
+      write(CURSOR_SHOW, stream)
+    }
+
+    return result
+  } catch (error) {
+    // Clean up spinner
+    if (spinnerTimerId !== null) {
+      clearTimeout(spinnerTimerId)
+    }
+    // Note: spinner may be set by setTimeout callback - TS can't track this
+    const errorSpinner = spinner as unknown as Spinner | null
+    if (errorSpinner) {
+      errorSpinner.stop()
+    }
+
+    // Restore cursor on error
+    if (started) {
+      bar.stop()
+    }
+    if (isTty) {
+      write(CURSOR_SHOW, stream)
+    }
+    throw error
+  }
+}
+
+/**
+ * Create a progress callback that can be passed to existing APIs
+ * Returns [callback, complete] tuple
+ *
+ * @example
+ * ```ts
+ * const [onProgress, complete] = createProgressCallback({
+ *   phases: { scanning: "Scanning", reconciling: "Reconciling" }
+ * });
+ *
+ * const result = await manager.syncFromFs(onProgress);
+ * complete();
+ * ```
+ */
+export function createProgressCallback(options: WithProgressOptions = {}): [ProgressCallback, () => void] {
+  const stream = process.stdout
+  const isTty = isTTY(stream)
+
+  const format =
+    options.format ?? (options.phases ? ":phase [:bar] :current/:total" : "[:bar] :current/:total :percent")
+
+  const bar = new ProgressBar({
+    format,
+    phases: options.phases ?? {},
+    hideCursor: true,
+  })
+
+  let lastPhase: string | null = null
+  let started = false
+
+  if (isTty) {
+    write(CURSOR_HIDE, stream)
+  }
+
+  const callback: ProgressCallback = (info: ProgressInfo) => {
+    if (info.phase && info.phase !== lastPhase) {
+      if (lastPhase !== null && isTty) {
+        write("\n", stream)
+      }
+      lastPhase = info.phase
+
+      if (!started) {
+        bar.start(info.current, info.total)
+        started = true
+      }
+      bar.setPhase(info.phase, { current: info.current, total: info.total })
+    } else {
+      if (!started) {
+        bar.start(info.current, info.total)
+        started = true
+      }
+      bar.update(info.current)
+    }
+  }
+
+  const complete = () => {
+    if (started) {
+      bar.stop(options.clearOnComplete)
+    }
+    if (isTty) {
+      write(CURSOR_SHOW, stream)
+    }
+  }
+
+  return [callback, complete]
+}

package/src/wrappers/with-select.ts

@@ -0,0 +1,194 @@
+/**
+ * withSelect - Interactive CLI selection list
+ */
+
+import chalk from "chalk"
+import type { SelectOption, WithSelectOptions } from "../types.js"
+import { CURSOR_HIDE, CURSOR_SHOW, CURSOR_TO_START, CLEAR_LINE_END, cursorUp, write, isTTY } from "../cli/ansi"
+
+/**
+ * Display an interactive selection list in the terminal
+ *
+ * @example
+ * ```ts
+ * // Simple usage
+ * const color = await withSelect("Choose a color:", [
+ *   { label: "Red", value: "red" },
+ *   { label: "Green", value: "green" },
+ *   { label: "Blue", value: "blue" },
+ * ]);
+ *
+ * // With options
+ * const result = await withSelect(
+ *   "Select item:",
+ *   options,
+ *   { initial: 2, maxVisible: 5 }
+ * );
+ * ```
+ */
+export async function withSelect<T>(
+  prompt: string,
+  options: SelectOption<T>[],
+  selectOptions: WithSelectOptions = {},
+): Promise<T> {
+  const { initial = 0, maxVisible = 10 } = selectOptions
+  const stream = process.stdout
+  const stdin = process.stdin
+
+  if (!isTTY(stream) || !stdin.isTTY) {
+    // Non-interactive mode: return first option or initial
+    return options[initial]?.value ?? options[0]!.value
+  }
+
+  return new Promise((resolve, reject) => {
+    let highlightIndex = Math.min(Math.max(0, initial), options.length - 1)
+    let linesRendered = 0
+
+    // Enable raw mode for character-by-character input
+    stdin.setRawMode(true)
+    stdin.resume()
+    stdin.setEncoding("utf8")
+
+    // Hide cursor
+    write(CURSOR_HIDE, stream)
+
+    function render() {
+      // Clear previously rendered lines
+      if (linesRendered > 0) {
+        write(cursorUp(linesRendered), stream)
+      }
+
+      // Calculate scroll window
+      const scrollOffset = Math.max(
+        0,
+        Math.min(highlightIndex - Math.floor(maxVisible / 2), options.length - maxVisible),
+      )
+      const visibleCount = Math.min(maxVisible, options.length)
+      const visibleOptions = options.slice(scrollOffset, scrollOffset + visibleCount)
+      const hasMoreAbove = scrollOffset > 0
+      const hasMoreBelow = scrollOffset + visibleCount < options.length
+
+      // Render prompt
+      write(`${CURSOR_TO_START}${chalk.bold(prompt)}${CLEAR_LINE_END}\n`, stream)
+
+      let lines = 1
+
+      // Render scroll indicator (above)
+      if (hasMoreAbove) {
+        write(`${CURSOR_TO_START}  ${chalk.dim("...")}${CLEAR_LINE_END}\n`, stream)
+        lines++
+      }
+
+      // Render options
+      for (let i = 0; i < visibleOptions.length; i++) {
+        const option = visibleOptions[i]
+        const actualIndex = scrollOffset + i
+        const isHighlighted = actualIndex === highlightIndex
+
+        const indicator = isHighlighted ? chalk.cyan(">") : " "
+        const label = isHighlighted ? chalk.cyan(option!.label) : option!.label
+
+        write(`${CURSOR_TO_START}${indicator} ${label}${CLEAR_LINE_END}\n`, stream)
+        lines++
+      }
+
+      // Render scroll indicator (below)
+      if (hasMoreBelow) {
+        write(`${CURSOR_TO_START}  ${chalk.dim("...")}${CLEAR_LINE_END}\n`, stream)
+        lines++
+      }
+
+      linesRendered = lines
+    }
+
+    function cleanup() {
+      stdin.setRawMode(false)
+      stdin.pause()
+      stdin.removeListener("data", onKeypress)
+      write(CURSOR_SHOW, stream)
+    }
+
+    function onKeypress(key: string) {
+      // Handle key sequences
+      const keyCode = key.charCodeAt(0)
+
+      // Ctrl+C
+      if (key === "\x03") {
+        cleanup()
+        reject(new Error("User cancelled"))
+        return
+      }
+
+      // Enter/Return
+      if (key === "\r" || key === "\n") {
+        cleanup()
+        resolve(options[highlightIndex]!.value)
+        return
+      }
+
+      // Escape
+      if (key === "\x1b" && key.length === 1) {
+        cleanup()
+        reject(new Error("User cancelled"))
+        return
+      }
+
+      // Arrow keys (escape sequences)
+      if (key.startsWith("\x1b[")) {
+        const code = key.slice(2)
+        if (code === "A") {
+          // Up arrow
+          highlightIndex = Math.max(0, highlightIndex - 1)
+          render()
+        } else if (code === "B") {
+          // Down arrow
+          highlightIndex = Math.min(options.length - 1, highlightIndex + 1)
+          render()
+        }
+        return
+      }
+
+      // j/k vim keys
+      if (key === "j" || key === "J") {
+        highlightIndex = Math.min(options.length - 1, highlightIndex + 1)
+        render()
+        return
+      }
+      if (key === "k" || key === "K") {
+        highlightIndex = Math.max(0, highlightIndex - 1)
+        render()
+        return
+      }
+
+      // Space to select (optional alternative to Enter)
+      if (key === " ") {
+        cleanup()
+        resolve(options[highlightIndex]!.value)
+        return
+      }
+    }
+
+    stdin.on("data", onKeypress)
+    render()
+  })
+}
+
+/**
+ * Create a reusable select instance for multiple selections
+ *
+ * @example
+ * ```ts
+ * const select = createSelect({
+ *   maxVisible: 5,
+ * });
+ *
+ * const first = await select("Choose first:", options1);
+ * const second = await select("Choose second:", options2);
+ * ```
+ */
+export function createSelect(
+  defaultOptions: WithSelectOptions = {},
+): <T>(prompt: string, options: SelectOption<T>[], overrides?: WithSelectOptions) => Promise<T> {
+  return <T>(prompt: string, options: SelectOption<T>[], overrides: WithSelectOptions = {}) =>
+    withSelect(prompt, options, { ...defaultOptions, ...overrides })
+}

package/src/wrappers/with-spinner.ts

@@ -0,0 +1,108 @@
+/**
+ * withSpinner - Wrap promises with an animated spinner
+ */
+
+import type { WithSpinnerOptions } from "../types.js"
+import { Spinner } from "../cli/spinner"
+
+/**
+ * Wrap a promise with an animated spinner
+ *
+ * @example
+ * ```ts
+ * // Simple usage
+ * const data = await withSpinner(fetchData(), "Loading data...");
+ *
+ * // With options
+ * const result = await withSpinner(
+ *   processFiles(),
+ *   "Processing...",
+ *   { style: "arc", clearOnComplete: true }
+ * );
+ *
+ * // With dynamic text
+ * const result = await withSpinner(
+ *   longOperation(),
+ *   (elapsed) => `Processing... (${elapsed}s)`
+ * );
+ * ```
+ */
+export async function withSpinner<T>(
+  promise: Promise<T> | (() => T | Promise<T>),
+  text: string | ((elapsedSeconds: number) => string),
+  options: WithSpinnerOptions = {},
+): Promise<T> {
+  const spinner = new Spinner({
+    text: typeof text === "string" ? text : text(0),
+    style: options.style,
+    color: options.color,
+  })
+
+  let timer: ReturnType<typeof setInterval> | null = null
+  const startTime = Date.now()
+
+  spinner.start()
+
+  // Update text if dynamic
+  if (typeof text === "function") {
+    timer = setInterval(() => {
+      const elapsed = Math.floor((Date.now() - startTime) / 1000)
+      spinner.currentText = text(elapsed)
+    }, 1000)
+  }
+
+  try {
+    const result = await (typeof promise === "function" ? promise() : promise)
+
+    if (timer) clearInterval(timer)
+
+    if (options.clearOnComplete) {
+      spinner.stop()
+    } else {
+      spinner.succeed()
+    }
+
+    return result
+  } catch (error) {
+    if (timer) clearInterval(timer)
+    spinner.fail(error instanceof Error ? error.message : "Failed")
+    throw error
+  }
+}
+
+/**
+ * Attach a spinner to a promise for manual control
+ * Returns [result, spinner] tuple for custom control
+ *
+ * @example
+ * ```ts
+ * const [promise, spinner] = attachSpinner(fetchData(), "Loading...");
+ * spinner.text = "Still loading...";
+ * const result = await promise;
+ * spinner.succeed("Loaded!");
+ * ```
+ */
+export function attachSpinner<T>(
+  promise: Promise<T>,
+  text: string,
+  options: WithSpinnerOptions = {},
+): [Promise<T>, Spinner] {
+  const spinner = new Spinner({
+    text,
+    style: options.style,
+    color: options.color,
+  })
+
+  spinner.start()
+
+  async function wrapPromise(): Promise<T> {
+    try {
+      return await promise
+    } catch (error) {
+      spinner.fail(error instanceof Error ? error.message : "Failed")
+      throw error
+    }
+  }
+
+  return [wrapPromise(), spinner]
+}