@silvery/ui 0.3.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@silvery/ui",
+  "version": "0.3.0",
+  "description": "Component library for silvery — Box, Text, ScrollView, VirtualList, and more",
+  "license": "MIT",
+  "author": "Bjørn Stabell <bjorn@stabell.org>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beorn/silvery.git",
+    "directory": "packages/ui"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./cli": {
+      "types": "./src/cli/index.ts",
+      "import": "./src/cli/index.ts"
+    },
+    "./react": {
+      "types": "./src/react/index.ts",
+      "import": "./src/react/index.ts"
+    },
+    "./wrappers": {
+      "types": "./src/wrappers/index.ts",
+      "import": "./src/wrappers/index.ts"
+    },
+    "./ansi": {
+      "types": "./src/ansi/index.ts",
+      "import": "./src/ansi/index.ts"
+    },
+    "./utils": {
+      "types": "./src/utils/index.ts",
+      "import": "./src/utils/index.ts"
+    },
+    "./progress": {
+      "types": "./src/progress/index.ts",
+      "import": "./src/progress/index.ts"
+    },
+    "./display": {
+      "types": "./src/display/index.ts",
+      "import": "./src/display/index.ts"
+    },
+    "./input": {
+      "types": "./src/input/index.ts",
+      "import": "./src/input/index.ts"
+    },
+    "./animation": {
+      "types": "./src/animation/index.ts",
+      "import": "./src/animation/index.ts"
+    },
+    "./*": {
+      "types": "./src/*",
+      "import": "./src/*"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@silvery/react": "workspace:*",
+    "@silvery/theme": "workspace:*"
+  }
+}

package/src/animation/easing.ts

@@ -0,0 +1,38 @@
+/**
+ * Easing Functions
+ *
+ * Maps time progress (0-1) to value progress (0-1) for smooth animations.
+ * Includes common presets and a resolver for name-or-function usage.
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Easing function: maps time progress (0-1) to value progress (0-1) */
+export type EasingFn = (t: number) => number
+
+// ============================================================================
+// Presets
+// ============================================================================
+
+export const easings = {
+  linear: (t: number) => t,
+  ease: (t: number) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+  easeIn: (t: number) => t * t,
+  easeOut: (t: number) => t * (2 - t),
+  easeInOut: (t: number) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+  easeInCubic: (t: number) => t * t * t,
+  easeOutCubic: (t: number) => --t * t * t + 1,
+} as const satisfies Record<string, EasingFn>
+
+export type EasingName = keyof typeof easings
+
+// ============================================================================
+// Resolver
+// ============================================================================
+
+/** Resolve an easing — accepts a name string or a custom function. */
+export function resolveEasing(easing: EasingName | EasingFn): EasingFn {
+  return typeof easing === "function" ? easing : easings[easing]
+}

package/src/animation/index.ts

@@ -0,0 +1,18 @@
+/**
+ * Animation Utilities
+ *
+ * Hooks and helpers for smooth terminal UI animations at ~30fps.
+ */
+
+// Easing
+export { easings, resolveEasing } from "./easing"
+export type { EasingFn, EasingName } from "./easing"
+
+// Hooks
+export { useAnimation } from "./useAnimation"
+export type { UseAnimationOptions, UseAnimationResult } from "./useAnimation"
+export { useTransition } from "./useTransition"
+export type { UseTransitionOptions } from "./useTransition"
+export { useInterval } from "./useInterval"
+export { useTimeout } from "./useTimeout"
+export { useLatest } from "./useLatest"

package/src/animation/useAnimation.ts

@@ -0,0 +1,143 @@
+/**
+ * useAnimation - Animate a value from 0 to 1 over a duration.
+ *
+ * Drives a single animation cycle with configurable easing, delay,
+ * and completion callback. Targets ~30fps (33ms interval) since
+ * terminals don't benefit from higher refresh rates.
+ */
+
+import { useState, useEffect, useRef, useCallback } from "react"
+import { resolveEasing, type EasingName, type EasingFn } from "./easing"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface UseAnimationOptions {
+  /** Duration in milliseconds */
+  duration: number
+  /** Easing function or preset name */
+  easing?: EasingName | EasingFn
+  /** Delay before starting (ms) */
+  delay?: number
+  /** Called when animation completes */
+  onComplete?: () => void
+  /** Whether to run the animation (default: true) */
+  enabled?: boolean
+}
+
+export interface UseAnimationResult {
+  /** Current progress value (0 to 1, eased) */
+  value: number
+  /** Whether the animation is still running */
+  isAnimating: boolean
+  /** Reset and replay the animation */
+  reset: () => void
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** ~30fps tick interval for terminal animations */
+const TICK_MS = 33
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Animate a value from 0 to 1 over a duration with easing.
+ *
+ * @example
+ * ```tsx
+ * function FadeIn({ children }) {
+ *   const { value } = useAnimation({ duration: 300, easing: "easeOut" })
+ *   return <Text dimColor={value < 1}>{children}</Text>
+ * }
+ * ```
+ */
+export function useAnimation(options: UseAnimationOptions): UseAnimationResult {
+  const { duration, easing = "linear", delay = 0, onComplete, enabled = true } = options
+
+  const [value, setValue] = useState(0)
+  const [isAnimating, setIsAnimating] = useState(false)
+
+  const startTimeRef = useRef(0)
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null)
+  const onCompleteRef = useRef(onComplete)
+  onCompleteRef.current = onComplete
+
+  // Epoch bumps on each reset to invalidate stale intervals
+  const epochRef = useRef(0)
+
+  const easingFn = resolveEasing(easing)
+
+  const stopInterval = useCallback(() => {
+    if (intervalRef.current !== null) {
+      clearInterval(intervalRef.current)
+      intervalRef.current = null
+    }
+  }, [])
+
+  const startAnimation = useCallback(() => {
+    stopInterval()
+    epochRef.current++
+    const epoch = epochRef.current
+
+    setValue(0)
+    setIsAnimating(true)
+
+    const begin = () => {
+      // Guard against stale starts after a reset
+      if (epochRef.current !== epoch) return
+
+      startTimeRef.current = performance.now()
+
+      intervalRef.current = setInterval(() => {
+        // Guard against stale ticks after a reset
+        if (epochRef.current !== epoch) return
+
+        const elapsed = performance.now() - startTimeRef.current
+        const raw = Math.min(elapsed / duration, 1)
+        const eased = easingFn(raw)
+
+        setValue(eased)
+
+        if (raw >= 1) {
+          stopInterval()
+          setIsAnimating(false)
+          onCompleteRef.current?.()
+        }
+      }, TICK_MS)
+    }
+
+    if (delay > 0) {
+      setTimeout(() => begin(), delay)
+    } else {
+      begin()
+    }
+  }, [duration, delay, easingFn, stopInterval])
+
+  // Start on mount (if enabled)
+  useEffect(() => {
+    if (!enabled) {
+      stopInterval()
+      setValue(0)
+      setIsAnimating(false)
+      return
+    }
+
+    startAnimation()
+
+    return () => {
+      stopInterval()
+    }
+  }, [enabled, startAnimation, stopInterval])
+
+  const reset = useCallback(() => {
+    startAnimation()
+  }, [startAnimation])
+
+  return { value, isAnimating, reset }
+}

package/src/animation/useInterval.ts

@@ -0,0 +1,39 @@
+/**
+ * useInterval - Run a callback on a fixed interval.
+ *
+ * Uses Dan Abramov's ref pattern to avoid stale closures.
+ * The callback is NOT called on mount — only on subsequent ticks.
+ */
+
+import { useEffect, useRef } from "react"
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Run a callback on a fixed interval.
+ *
+ * The callback is NOT called on mount — only on ticks after the interval
+ * elapses. Uses a ref for the callback to avoid stale closures.
+ *
+ * @param callback - Function to call on each tick
+ * @param ms - Interval in milliseconds
+ * @param enabled - Whether the interval is active (default: true)
+ */
+export function useInterval(callback: () => void, ms: number, enabled = true): void {
+  const callbackRef = useRef(callback)
+  callbackRef.current = callback
+
+  useEffect(() => {
+    if (!enabled) return
+
+    const id = setInterval(() => {
+      callbackRef.current()
+    }, ms)
+
+    return () => {
+      clearInterval(id)
+    }
+  }, [ms, enabled])
+}

package/src/animation/useLatest.ts

@@ -0,0 +1,35 @@
+/**
+ * useLatest - Always-current ref to a value.
+ *
+ * The classic React pattern for avoiding stale closures in callbacks,
+ * timers, and effects. Returns a ref whose `.current` is always the
+ * latest value — safe to read from any async context.
+ *
+ * ```tsx
+ * const countRef = useLatest(count)
+ * useInterval(() => {
+ *   console.log(countRef.current) // always fresh
+ * }, 1000)
+ * ```
+ */
+
+import { useRef } from "react"
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Returns a ref that always holds the latest value.
+ *
+ * Useful when a callback needs access to current state/props without
+ * re-creating the callback (which would reset timers, event listeners, etc).
+ *
+ * @param value - The value to track
+ * @returns A ref whose `.current` is always `value`
+ */
+export function useLatest<T>(value: T): { readonly current: T } {
+  const ref = useRef(value)
+  ref.current = value
+  return ref
+}

package/src/animation/useTimeout.ts

@@ -0,0 +1,65 @@
+/**
+ * useTimeout - Run a callback after a delay.
+ *
+ * Uses a ref for the callback to avoid stale closures (Dan Abramov pattern).
+ * The timer resets when `ms` or `enabled` changes. When `enabled` becomes false,
+ * the timer is cleared. Returns a `reset` function to restart the timer.
+ *
+ * Unlike useInterval, this fires exactly once per enable/reset cycle.
+ */
+
+import { useCallback, useEffect, useRef } from "react"
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Run a callback after a delay.
+ *
+ * The callback fires once after `ms` milliseconds. The timer resets when
+ * `ms` or `enabled` changes. Returns `{ reset, clear }` for manual control.
+ *
+ * @param callback - Function to call when the timer fires
+ * @param ms - Delay in milliseconds
+ * @param enabled - Whether the timer is active (default: true)
+ */
+export function useTimeout(callback: () => void, ms: number, enabled = true): { reset: () => void; clear: () => void } {
+  const callbackRef = useRef(callback)
+  callbackRef.current = callback
+
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  const clear = useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current)
+      timerRef.current = null
+    }
+  }, [])
+
+  const reset = useCallback(() => {
+    clear()
+    if (enabled) {
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null
+        callbackRef.current()
+      }, ms)
+    }
+  }, [ms, enabled, clear])
+
+  useEffect(() => {
+    if (!enabled) {
+      clear()
+      return
+    }
+
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null
+      callbackRef.current()
+    }, ms)
+
+    return clear
+  }, [ms, enabled, clear])
+
+  return { reset, clear }
+}

package/src/animation/useTransition.ts

@@ -0,0 +1,110 @@
+/**
+ * useTransition - Smoothly interpolate between numeric values.
+ *
+ * When the target value changes, animates from the current value toward
+ * the new target. If the target changes mid-animation, restarts from
+ * the current interpolated position. Targets ~30fps.
+ */
+
+import { useState, useEffect, useRef } from "react"
+import { resolveEasing, type EasingName, type EasingFn } from "./easing"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface UseTransitionOptions {
+  /** Duration in milliseconds (default: 300) */
+  duration?: number
+  /** Easing function or preset name (default: "easeOut") */
+  easing?: EasingName | EasingFn
+}
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/** ~30fps tick interval for terminal animations */
+const TICK_MS = 33
+
+// ============================================================================
+// Hook
+// ============================================================================
+
+/**
+ * Smoothly interpolate when the target value changes.
+ *
+ * Returns the current interpolated value. On the first render, returns
+ * the target value immediately (no animation). Subsequent changes
+ * animate from the previous value to the new target.
+ *
+ * @example
+ * ```tsx
+ * function ScrollOffset({ target }) {
+ *   const smooth = useTransition(target, { duration: 200, easing: "easeOut" })
+ *   return <Box marginTop={Math.round(smooth)}>...</Box>
+ * }
+ * ```
+ */
+export function useTransition(targetValue: number, options?: UseTransitionOptions): number {
+  const { duration = 300, easing = "easeOut" } = options ?? {}
+
+  const [currentValue, setCurrentValue] = useState(targetValue)
+
+  const fromRef = useRef(targetValue)
+  const toRef = useRef(targetValue)
+  const startTimeRef = useRef(0)
+  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null)
+  const isFirstRef = useRef(true)
+
+  const easingFn = resolveEasing(easing)
+
+  useEffect(() => {
+    // On first render, snap to target without animation
+    if (isFirstRef.current) {
+      isFirstRef.current = false
+      return
+    }
+
+    // If target hasn't changed, nothing to do
+    if (targetValue === toRef.current) return
+
+    // Start from wherever we currently are
+    fromRef.current = currentValue
+    toRef.current = targetValue
+    startTimeRef.current = performance.now()
+
+    // Clear any existing interval
+    if (intervalRef.current !== null) {
+      clearInterval(intervalRef.current)
+    }
+
+    intervalRef.current = setInterval(() => {
+      const elapsed = performance.now() - startTimeRef.current
+      const raw = Math.min(elapsed / duration, 1)
+      const eased = easingFn(raw)
+      const interpolated = fromRef.current + (toRef.current - fromRef.current) * eased
+
+      setCurrentValue(interpolated)
+
+      if (raw >= 1) {
+        // Snap to exact target and stop
+        setCurrentValue(toRef.current)
+        if (intervalRef.current !== null) {
+          clearInterval(intervalRef.current)
+          intervalRef.current = null
+        }
+      }
+    }, TICK_MS)
+
+    return () => {
+      if (intervalRef.current !== null) {
+        clearInterval(intervalRef.current)
+        intervalRef.current = null
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [targetValue, duration, easingFn])
+
+  return currentValue
+}

package/src/animation.ts

@@ -0,0 +1,24 @@
+/**
+ * silvery/animation -- Smooth terminal UI animations at ~30fps.
+ *
+ * ```tsx
+ * import { useAnimation, easings } from '@silvery/ui/animation'
+ *
+ * function FadeIn() {
+ *   const { value } = useAnimation({ duration: 300, easing: "easeOut" })
+ *   return <Text dimColor={value < 1}>Hello</Text>
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { easings, resolveEasing, useAnimation, useInterval, useTimeout, useLatest } from "./animation/index"
+export { useTransition as useAnimatedTransition } from "./animation/index"
+export type {
+  EasingFn,
+  EasingName,
+  UseAnimationOptions,
+  UseAnimationResult,
+  UseTransitionOptions,
+} from "./animation/index"

package/src/ansi/index.ts

@@ -0,0 +1,43 @@
+/**
+ * ANSI terminal control utilities
+ *
+ * @example
+ * ```ts
+ * import {
+ *   CURSOR_HIDE,
+ *   CURSOR_SHOW,
+ *   CLEAR_LINE,
+ *   write,
+ *   isTTY,
+ * } from "@silvery/ui/ansi";
+ *
+ * if (isTTY()) {
+ *   write(CURSOR_HIDE);
+ *   // ... do work ...
+ *   write(CURSOR_SHOW);
+ * }
+ * ```
+ */
+
+// Re-export all from cli/ansi.ts
+export {
+  // Cursor control
+  CURSOR_HIDE,
+  CURSOR_SHOW,
+  CURSOR_TO_START,
+  CURSOR_SAVE,
+  CURSOR_RESTORE,
+  cursorUp,
+  cursorDown,
+  // Line/screen clearing
+  CLEAR_LINE,
+  CLEAR_LINE_END,
+  CLEAR_SCREEN,
+  // Writing utilities
+  write,
+  writeLine,
+  withCursor,
+  // Terminal detection
+  isTTY,
+  getTerminalWidth,
+} from "../cli/ansi"