@silvery/ui 0.3.0

package/src/canvas/index.ts

@@ -0,0 +1,169 @@
+/**
+ * Canvas Entry Point
+ *
+ * Provides a browser-friendly API for rendering silvery components to HTML5 Canvas.
+ * This module sets up the canvas adapter and provides render functions.
+ *
+ * @example
+ * ```tsx
+ * import { renderToCanvas, Box, Text, useContentRect } from '@silvery/ui/canvas';
+ *
+ * function App() {
+ *   const { width, height } = useContentRect();
+ *   return (
+ *     <Box flexDirection="column">
+ *       <Text>Canvas size: {width}px × {height}px</Text>
+ *     </Box>
+ *   );
+ * }
+ *
+ * const canvas = document.getElementById('canvas');
+ * renderToCanvas(<App />, canvas);
+ * ```
+ */
+
+import type { ReactElement } from "react"
+import {
+  type CanvasAdapterConfig,
+  CanvasRenderBuffer,
+  createCanvasAdapter,
+} from "@silvery/term/adapters/canvas-adapter"
+import { createBrowserRenderer, initBrowserRenderer, renderOnce } from "@silvery/term/browser-renderer"
+import type { RenderBuffer } from "@silvery/term/render-adapter"
+
+// Re-export components and hooks for convenience
+export { Box, type BoxProps } from "@silvery/react/components/Box"
+export { Text, type TextProps } from "@silvery/react/components/Text"
+export { useContentRect, useScreenRect } from "@silvery/react/hooks/useLayout"
+export { useApp } from "@silvery/react/hooks/useApp"
+
+// Re-export adapter utilities
+export {
+  createCanvasAdapter,
+  CanvasRenderBuffer,
+  type CanvasAdapterConfig,
+} from "@silvery/term/adapters/canvas-adapter"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface CanvasRenderOptions extends CanvasAdapterConfig {
+  /** Width of the canvas (default: canvas.width) */
+  width?: number
+  /** Height of the canvas (default: canvas.height) */
+  height?: number
+}
+
+export interface CanvasInstance {
+  /** Re-render with a new element */
+  rerender: (element: ReactElement) => void
+  /** Unmount and clean up */
+  unmount: () => void
+  /** Dispose (alias for unmount) — enables `using` */
+  [Symbol.dispose](): void
+  /** Get the current buffer */
+  getBuffer: () => RenderBuffer | null
+  /** Force a re-render */
+  refresh: () => void
+}
+
+// ============================================================================
+// Initialization
+// ============================================================================
+
+const canvasAdapterFactory = {
+  createAdapter: (config: CanvasAdapterConfig) => createCanvasAdapter(config),
+}
+
+/**
+ * Initialize the canvas rendering system.
+ * Called automatically by renderToCanvas, but can be called manually.
+ */
+export function initCanvasRenderer(config: CanvasAdapterConfig = {}): void {
+  initBrowserRenderer(canvasAdapterFactory, config)
+}
+
+// ============================================================================
+// Render Functions
+// ============================================================================
+
+/**
+ * Render a React element to an HTML5 Canvas.
+ *
+ * @param element - React element to render
+ * @param canvas - Target canvas element
+ * @param options - Render options (font size, colors, etc.)
+ * @returns CanvasInstance for controlling the render
+ *
+ * @example
+ * ```tsx
+ * const canvas = document.getElementById('canvas');
+ * const instance = renderToCanvas(<App />, canvas, { fontSize: 16 });
+ *
+ * // Later: update the component
+ * instance.rerender(<App newProps />);
+ *
+ * // Clean up
+ * instance.unmount();
+ * ```
+ */
+export function renderToCanvas(
+  element: ReactElement,
+  canvas: HTMLCanvasElement,
+  options: CanvasRenderOptions = {},
+): CanvasInstance {
+  initCanvasRenderer(options)
+
+  const pixelWidth = options.width ?? canvas.width
+  const pixelHeight = options.height ?? canvas.height
+
+  // Ensure canvas dimensions match
+  if (canvas.width !== pixelWidth) canvas.width = pixelWidth
+  if (canvas.height !== pixelHeight) canvas.height = pixelHeight
+
+  // Convert pixel dimensions to cell dimensions for the layout engine.
+  // The layout engine operates in cell units (columns x rows), not pixels.
+  const fontSize = options.fontSize ?? 14
+  const lineHeightMultiplier = options.lineHeight ?? 1.2
+  const charWidth = fontSize * 0.6
+  const lineHeight = fontSize * lineHeightMultiplier
+  const cols = Math.floor(pixelWidth / charWidth)
+  const rows = Math.floor(pixelHeight / lineHeight)
+
+  return createBrowserRenderer<CanvasRenderBuffer>(element, cols, rows, (buffer) => {
+    const ctx = canvas.getContext("2d")
+    if (ctx) {
+      ctx.drawImage(buffer.canvas, 0, 0)
+    }
+  })
+}
+
+/**
+ * Render a React element to a canvas and return the buffer.
+ * One-shot render without ongoing updates.
+ *
+ * @param element - React element to render
+ * @param width - Canvas width in pixels
+ * @param height - Canvas height in pixels
+ * @param options - Render options
+ * @returns The rendered buffer
+ */
+export function renderCanvasOnce(
+  element: ReactElement,
+  width: number,
+  height: number,
+  options: CanvasAdapterConfig = {},
+): CanvasRenderBuffer {
+  initCanvasRenderer(options)
+
+  // Convert pixel dimensions to cell dimensions for the layout engine
+  const fontSize = options.fontSize ?? 14
+  const lineHeightMultiplier = options.lineHeight ?? 1.2
+  const charWidth = fontSize * 0.6
+  const lineHeight = fontSize * lineHeightMultiplier
+  const cols = Math.floor(width / charWidth)
+  const rows = Math.floor(height / lineHeight)
+
+  return renderOnce<CanvasRenderBuffer>(element, cols, rows)
+}

package/src/cli/ansi.ts

@@ -0,0 +1,85 @@
+/**
+ * ANSI escape code utilities for terminal control
+ */
+
+/** Hide the cursor */
+export const CURSOR_HIDE = "\x1b[?25l"
+
+/** Show the cursor */
+export const CURSOR_SHOW = "\x1b[?25h"
+
+/** Move cursor to beginning of line */
+export const CURSOR_TO_START = "\r"
+
+/** Clear from cursor to end of line */
+export const CLEAR_LINE_END = "\x1b[K"
+
+/** Clear entire line */
+export const CLEAR_LINE = "\x1b[2K"
+
+/** Clear screen and move to top-left */
+export const CLEAR_SCREEN = "\x1b[2J\x1b[H"
+
+/** Move cursor up N lines */
+export const cursorUp = (n: number = 1): string => `\x1b[${n}A`
+
+/** Move cursor down N lines */
+export const cursorDown = (n: number = 1): string => `\x1b[${n}B`
+
+/** Save cursor position */
+export const CURSOR_SAVE = "\x1b[s"
+
+/** Restore cursor position */
+export const CURSOR_RESTORE = "\x1b[u"
+
+/**
+ * Write to stream with proper handling
+ */
+export function write(text: string, stream: NodeJS.WriteStream = process.stdout): void {
+  stream.write(text)
+}
+
+/**
+ * Clear the current line and write new text
+ */
+export function writeLine(text: string, stream: NodeJS.WriteStream = process.stdout): void {
+  stream.write(`${CURSOR_TO_START}${text}${CLEAR_LINE_END}`)
+}
+
+/**
+ * Wrap a function to handle cursor visibility
+ * Hides cursor on start, shows on completion/error
+ */
+export function withCursor<T>(fn: () => T | Promise<T>, stream: NodeJS.WriteStream = process.stdout): Promise<T> {
+  stream.write(CURSOR_HIDE)
+
+  const restore = () => stream.write(CURSOR_SHOW)
+
+  try {
+    const result = fn()
+    if (result instanceof Promise) {
+      return result.finally(restore)
+    }
+    restore()
+    return Promise.resolve(result)
+  } catch (error) {
+    restore()
+    throw error
+  }
+}
+
+/**
+ * Check if stream is a TTY (supports ANSI codes)
+ * Also respects FORCE_TTY environment variable for testing
+ */
+export function isTTY(stream: NodeJS.WriteStream = process.stdout): boolean {
+  if (process.env.FORCE_TTY === "1") return true
+  return stream.isTTY ?? false
+}
+
+/**
+ * Get terminal width
+ */
+export function getTerminalWidth(stream: NodeJS.WriteStream = process.stdout): number {
+  return stream.columns ?? 80
+}

package/src/cli/index.ts

@@ -0,0 +1,39 @@
+/**
+ * CLI progress indicators - direct stdout usage (no React)
+ *
+ * @example
+ * ```ts
+ * import { Spinner, ProgressBar, MultiProgress } from "@silvery/ui/cli";
+ *
+ * // Quick spinner
+ * const stop = Spinner.start("Loading...");
+ * await work();
+ * stop();
+ *
+ * // Spinner with result
+ * const spinner = new Spinner("Processing...");
+ * spinner.start();
+ * spinner.succeed("Done!");
+ *
+ * // Progress bar
+ * const bar = new ProgressBar({ total: 100 });
+ * bar.start();
+ * bar.update(50);
+ * bar.stop();
+ *
+ * // Multiple tasks
+ * const multi = new MultiProgress();
+ * const task1 = multi.add("Download", { type: "bar", total: 100 });
+ * const task2 = multi.add("Process", { type: "spinner" });
+ * multi.start();
+ * task1.start();
+ * task1.update(50);
+ * task1.complete();
+ * multi.stop();
+ * ```
+ */
+
+export { Spinner, SPINNER_FRAMES, createSpinner, type CallableSpinner } from "./spinner"
+export { ProgressBar } from "./progress-bar"
+export { MultiProgress, type TaskHandle } from "./multi-progress"
+export * from "./ansi"

package/src/cli/multi-progress.ts

@@ -0,0 +1,340 @@
+/**
+ * MultiProgress - Container for managing multiple concurrent progress indicators
+ */
+
+import chalk from "chalk"
+import type { SpinnerStyle, TaskStatus } from "../types.js"
+import { CURSOR_HIDE, CURSOR_SHOW, CLEAR_LINE, cursorUp, write, isTTY } from "./ansi"
+import { Spinner, SPINNER_FRAMES } from "./spinner"
+import { ProgressBar } from "./progress-bar"
+
+/** Status icons */
+const STATUS_ICONS: Record<TaskStatus, string> = {
+  pending: chalk.gray("○"),
+  running: "", // Will be replaced with spinner frame
+  completed: chalk.green("✔"),
+  failed: chalk.red("✖"),
+  skipped: chalk.yellow("⊘"),
+}
+
+/** Task configuration */
+interface TaskConfig {
+  title: string
+  type: "spinner" | "bar" | "group"
+  status: TaskStatus
+  total?: number
+  current?: number
+  spinnerStyle?: SpinnerStyle
+  indent?: number
+}
+
+/** Internal task state */
+interface TaskState extends TaskConfig {
+  id: string
+  /** Completion time in ms (shown dimmed after title on completion) */
+  completionTime?: number
+}
+
+/**
+ * MultiProgress - Manage multiple concurrent progress indicators
+ *
+ * @example
+ * ```ts
+ * const multi = new MultiProgress();
+ *
+ * const download = multi.add("Downloading files", { type: "bar", total: 100 });
+ * const process = multi.add("Processing", { type: "spinner" });
+ *
+ * download.start();
+ * download.update(50);
+ * download.complete();
+ *
+ * process.start();
+ * process.complete();
+ *
+ * multi.stop();
+ * ```
+ */
+export class MultiProgress {
+  private tasks: Map<string, TaskState> = new Map()
+  private taskOrder: string[] = []
+  private stream: NodeJS.WriteStream
+  private isActive = false
+  private timer: ReturnType<typeof setInterval> | null = null
+  private frameIndex = 0
+  private renderedLines = 0
+
+  constructor(stream: NodeJS.WriteStream = process.stdout) {
+    this.stream = stream
+  }
+
+  /**
+   * Add a new task
+   * @param insertAfter - ID of task to insert after (for hierarchical display)
+   */
+  add(
+    title: string,
+    options: {
+      type?: "spinner" | "bar" | "group"
+      total?: number
+      spinnerStyle?: SpinnerStyle
+      indent?: number
+      insertAfter?: string
+    } = {},
+  ): TaskHandle {
+    const id = `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+
+    const task: TaskState = {
+      id,
+      title,
+      type: options.type ?? "spinner",
+      status: "pending",
+      total: options.total,
+      current: 0,
+      spinnerStyle: options.spinnerStyle ?? "dots",
+      indent: options.indent ?? 0,
+    }
+
+    this.tasks.set(id, task)
+
+    // Insert after specified task, or append to end
+    if (options.insertAfter) {
+      const afterIndex = this.taskOrder.indexOf(options.insertAfter)
+      if (afterIndex >= 0) {
+        this.taskOrder.splice(afterIndex + 1, 0, id)
+      } else {
+        this.taskOrder.push(id)
+      }
+    } else {
+      this.taskOrder.push(id)
+    }
+
+    if (this.isActive) {
+      this.render()
+    }
+
+    return new TaskHandle(this, id)
+  }
+
+  /**
+   * Start the multi-progress display
+   */
+  start(): this {
+    if (this.isActive) {
+      return this
+    }
+
+    this.isActive = true
+
+    if (isTTY(this.stream)) {
+      write(CURSOR_HIDE, this.stream)
+    }
+
+    this.render()
+
+    // Start animation timer
+    this.timer = setInterval(() => {
+      this.frameIndex = (this.frameIndex + 1) % 10
+      this.render()
+    }, 80)
+
+    return this
+  }
+
+  /**
+   * Dispose the multi-progress display (calls stop)
+   */
+  [Symbol.dispose](): void {
+    this.stop()
+  }
+
+  /**
+   * Stop the multi-progress display
+   * @param clear - If true, clear all task lines from terminal
+   */
+  stop(clear = false): this {
+    if (!this.isActive) {
+      return this
+    }
+
+    this.isActive = false
+
+    if (this.timer) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+
+    if (clear && isTTY(this.stream)) {
+      // Clear all rendered lines
+      if (this.renderedLines > 0) {
+        write(cursorUp(this.renderedLines), this.stream)
+        for (let i = 0; i < this.renderedLines; i++) {
+          write(`${CLEAR_LINE}\n`, this.stream)
+        }
+        write(cursorUp(this.renderedLines), this.stream)
+      }
+    } else {
+      // Final render
+      this.render()
+      write("\n", this.stream)
+    }
+
+    if (isTTY(this.stream)) {
+      write(CURSOR_SHOW, this.stream)
+    }
+
+    return this
+  }
+
+  /** @internal Update task state */
+  _updateTask(id: string, updates: Partial<TaskState>): void {
+    const task = this.tasks.get(id)
+    if (task) {
+      Object.assign(task, updates)
+      // Only render immediately for status changes (complete/fail/etc.)
+      // Progress updates (current/total) are debounced by the 80ms animation timer
+      if (this.isActive && updates.status) {
+        this.render()
+      }
+    }
+  }
+
+  /** @internal Get task state */
+  _getTask(id: string): TaskState | undefined {
+    return this.tasks.get(id)
+  }
+
+  private render(): void {
+    if (!isTTY(this.stream)) {
+      return
+    }
+
+    // Move cursor up to clear previous render
+    if (this.renderedLines > 0) {
+      write(cursorUp(this.renderedLines), this.stream)
+    }
+
+    const lines: string[] = []
+
+    for (const id of this.taskOrder) {
+      const task = this.tasks.get(id)
+      if (!task) continue
+
+      let icon: string
+      if (task.status === "running") {
+        if (task.type === "group") {
+          // Groups don't animate - keep pending icon while running
+          icon = STATUS_ICONS.pending
+        } else {
+          const frames = SPINNER_FRAMES[task.spinnerStyle ?? "dots"]
+          icon = chalk.cyan(frames[this.frameIndex % frames.length])
+        }
+      } else {
+        icon = STATUS_ICONS[task.status]
+      }
+
+      const indent = "  ".repeat(task.indent ?? 0)
+      let line = `${indent}${icon} ${task.title}`
+
+      // Add progress bar for bar type
+      if (task.type === "bar" && task.total && task.total > 0) {
+        const percent = task.current! / task.total
+        const barWidth = 20
+        const filled = Math.round(barWidth * percent)
+        const empty = barWidth - filled
+        const bar = chalk.cyan("█".repeat(filled)) + chalk.gray("░".repeat(empty))
+        line += ` ${bar} ${Math.round(percent * 100)}%`
+      }
+
+      // Add completion time in dimmed text
+      if (task.status === "completed" && task.completionTime !== undefined) {
+        line += chalk.dim(` ${task.completionTime}ms`)
+      }
+
+      lines.push(line)
+    }
+
+    // Clear and write each line
+    for (const line of lines) {
+      write(`${CLEAR_LINE}${line}\n`, this.stream)
+    }
+
+    this.renderedLines = lines.length
+  }
+}
+
+/**
+ * Handle for controlling an individual task
+ */
+class TaskHandle {
+  constructor(
+    private multi: MultiProgress,
+    private _id: string,
+  ) {}
+
+  /** Get task ID (for insertAfter) */
+  get id(): string {
+    return this._id
+  }
+
+  /** Start the task (set status to running) */
+  start(): this {
+    this.multi._updateTask(this._id, { status: "running" })
+    return this
+  }
+
+  /** Update progress (for bar type) */
+  update(current: number): this {
+    this.multi._updateTask(this._id, { current })
+    return this
+  }
+
+  /** Mark task as completed */
+  complete(titleOrTime?: string | number): this {
+    const updates: Partial<TaskState> = { status: "completed" }
+    if (typeof titleOrTime === "number") {
+      // Numeric = completion time in ms (preserves current title)
+      updates.completionTime = titleOrTime
+    } else if (titleOrTime) {
+      // String = new title (legacy behavior)
+      updates.title = titleOrTime
+    }
+    this.multi._updateTask(this._id, updates)
+    return this
+  }
+
+  /** Mark task as failed */
+  fail(title?: string): this {
+    const updates: Partial<TaskState> = { status: "failed" }
+    if (title) updates.title = title
+    this.multi._updateTask(this._id, updates)
+    return this
+  }
+
+  /** Mark task as skipped */
+  skip(title?: string): this {
+    const updates: Partial<TaskState> = { status: "skipped" }
+    if (title) updates.title = title
+    this.multi._updateTask(this._id, updates)
+    return this
+  }
+
+  /** Update task title */
+  setTitle(title: string): this {
+    this.multi._updateTask(this._id, { title })
+    return this
+  }
+
+  /** Change task type (e.g., from spinner to group when sub-steps are added) */
+  setType(type: "spinner" | "bar" | "group"): this {
+    this.multi._updateTask(this._id, { type })
+    return this
+  }
+
+  /** Get current status */
+  get status(): TaskStatus {
+    return this.multi._getTask(this._id)?.status ?? "pending"
+  }
+}
+
+export type { TaskHandle }