@effect-tui/react 0.1.0-alpha.1

package/src/inline/index.tsx

@@ -0,0 +1,181 @@
+// Inline task visualization with Layer-based dependency injection
+// Usage:
+//   import { task, InlineRendererLive } from "@effect-tui/react/inline"
+//   const program = Effect.gen(function* () {
+//     yield* task("Fetch user", fetchUser)
+//     yield* task("Process data", processData)
+//   }).pipe(Effect.provide(InlineRendererLive))
+//   Effect.runPromise(program)
+
+import { Context, Effect, Either, Layer } from "effect"
+import { Colors } from "@effect-tui/core"
+import { createRenderer, createRoot } from "../renderer.js"
+
+// Spinner frames
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const
+
+type TaskStatus = "pending" | "running" | "success" | "failure"
+
+interface TaskEntry {
+  label: string
+  status: TaskStatus
+}
+
+interface TaskListProps {
+  tasks: TaskEntry[]
+  spinnerIndex: number
+}
+
+function TaskList({ tasks, spinnerIndex }: TaskListProps) {
+  return (
+    <vstack>
+      {tasks.map((task, i) => {
+        const icon =
+          task.status === "running"
+            ? SPINNER[spinnerIndex % SPINNER.length]
+            : task.status === "success"
+              ? "✓"
+              : task.status === "failure"
+                ? "✗"
+                : "○"
+
+        const color =
+          task.status === "running"
+            ? Colors.brightYellow
+            : task.status === "success"
+              ? Colors.brightGreen
+              : task.status === "failure"
+                ? Colors.brightRed
+                : Colors.gray(10)
+
+        return (
+          <hstack key={i} spacing={1}>
+            <text bold fg={color}>
+              {icon}
+            </text>
+            <text fg={task.status === "pending" ? Colors.gray(10) : undefined}>{task.label}</text>
+          </hstack>
+        )
+      })}
+    </vstack>
+  )
+}
+
+export interface TaskOptions<A> {
+  /** Format the result to append to the label on success */
+  formatResult?: (result: A) => string
+}
+
+// Service definition
+export interface InlineRenderer {
+  /**
+   * Wrap an effect with inline progress visualization.
+   * Shows a spinner while running, checkmark on success, X on failure.
+   */
+  readonly task: <A, E, R>(
+    label: string,
+    effect: Effect.Effect<A, E, R>,
+    options?: TaskOptions<A>,
+  ) => Effect.Effect<A, E, R>
+}
+
+export const InlineRenderer = Context.GenericTag<InlineRenderer>("@effect-tui/react/InlineRenderer")
+
+// Create the live layer
+export const InlineRendererLive: Layer.Layer<InlineRenderer> = Layer.scoped(
+  InlineRenderer,
+  Effect.gen(function* () {
+    // Create renderer in inline mode
+    const renderer = createRenderer({ mode: "inline" })
+    const root = createRoot(renderer)
+
+    // Session state - accumulate all tasks
+    const tasks: TaskEntry[] = []
+    let spinnerIndex = 0
+    let intervalId: ReturnType<typeof setInterval> | null = null
+
+    const render = () => {
+      root.render(<TaskList tasks={[...tasks]} spinnerIndex={spinnerIndex} />)
+    }
+
+    const startSpinner = (label: string) => {
+      tasks.push({ label, status: "running" })
+      spinnerIndex = 0
+      render()
+
+      intervalId = setInterval(() => {
+        spinnerIndex = (spinnerIndex + 1) % SPINNER.length
+        render()
+      }, 80)
+    }
+
+    const stopSpinner = (status: "success" | "failure", labelSuffix?: string) => {
+      if (intervalId) {
+        clearInterval(intervalId)
+        intervalId = null
+      }
+      // Update last task status
+      if (tasks.length > 0) {
+        tasks[tasks.length - 1].status = status
+        if (labelSuffix) {
+          tasks[tasks.length - 1].label += labelSuffix
+        }
+        render()
+      }
+    }
+
+    // Cleanup on scope close
+    yield* Effect.addFinalizer(() =>
+      Effect.sync(() => {
+        if (intervalId) clearInterval(intervalId)
+        root.unmount()
+      }),
+    )
+
+    return InlineRenderer.of({
+      task: <A, E, R>(
+        label: string,
+        effect: Effect.Effect<A, E, R>,
+        options?: TaskOptions<A>,
+      ): Effect.Effect<A, E, R> =>
+        Effect.gen(function* () {
+          startSpinner(label)
+
+          const result = yield* effect.pipe(Effect.either)
+
+          if (Either.isRight(result)) {
+            const suffix = options?.formatResult ? ` → ${options.formatResult(result.right)}` : ""
+            stopSpinner("success", suffix)
+            yield* Effect.sleep(50)
+            return result.right
+          } else {
+            stopSpinner("failure")
+            yield* Effect.sleep(50)
+            return yield* Effect.fail(result.left)
+          }
+        }),
+    })
+  }),
+)
+
+/**
+ * Wrap an effect with inline progress visualization.
+ * Requires InlineRendererLive layer to be provided.
+ *
+ * @example
+ * ```ts
+ * const program = Effect.gen(function* () {
+ *   const user = yield* task("Fetch user", fetchUser, {
+ *     formatResult: (u) => u.name
+ *   })
+ *   yield* task("Send email", sendEmail(user))
+ * }).pipe(Effect.provide(InlineRendererLive))
+ *
+ * Effect.runPromise(program)
+ * ```
+ */
+export const task = <A, E, R>(
+  label: string,
+  effect: Effect.Effect<A, E, R>,
+  options?: TaskOptions<A>,
+): Effect.Effect<A, E, R | InlineRenderer> => Effect.flatMap(InlineRenderer, (r) => r.task(label, effect, options))

package/src/jsx.ts

@@ -0,0 +1,3 @@
+// JSX types are provided via jsxImportSource: "@effect-tui/react"
+// See jsx-runtime.ts at package root for the JSX namespace definition
+export {}

package/src/motion/color-motion-value.ts

@@ -0,0 +1,90 @@
+/**
+ * ColorMotionValue - animates RGBA colors using 4 internal numeric springs.
+ */
+
+import { parseColor, type RGBA, type ColorInput } from "./color.js"
+import { EventEmitter } from "./event-emitter.js"
+import { MotionValue } from "./motion-value.js"
+import type { SpringOptions } from "./types.js"
+
+/**
+ * ColorMotionValue animates RGBA colors using 4 internal numeric springs.
+ * Each channel (r, g, b, a) is animated independently with the same spring config.
+ */
+export class ColorMotionValue extends EventEmitter<RGBA> {
+  private rMv: MotionValue<number>
+  private gMv: MotionValue<number>
+  private bMv: MotionValue<number>
+  private aMv: MotionValue<number>
+
+  constructor(initial: ColorInput) {
+    super()
+    const rgba = parseColor(initial)
+    this.rMv = new MotionValue(rgba.r)
+    this.gMv = new MotionValue(rgba.g)
+    this.bMv = new MotionValue(rgba.b)
+    this.aMv = new MotionValue(rgba.a)
+  }
+
+  /** Get current RGBA value */
+  get(): RGBA {
+    return {
+      r: Math.round(Math.max(0, Math.min(255, this.rMv.get()))),
+      g: Math.round(Math.max(0, Math.min(255, this.gMv.get()))),
+      b: Math.round(Math.max(0, Math.min(255, this.bMv.get()))),
+      a: Math.max(0, Math.min(1, this.aMv.get())),
+    }
+  }
+
+  /** Set color immediately (no animation) */
+  jump(color: ColorInput) {
+    const rgba = parseColor(color)
+    this.rMv.jump(rgba.r)
+    this.gMv.jump(rgba.g)
+    this.bMv.jump(rgba.b)
+    this.aMv.jump(rgba.a)
+    this.notify("change", this.get())
+  }
+
+  /** Set target color and animate with spring */
+  set(color: ColorInput, options?: SpringOptions) {
+    const rgba = parseColor(color)
+    this.rMv.set(rgba.r, options)
+    this.gMv.set(rgba.g, options)
+    this.bMv.set(rgba.b, options)
+    this.aMv.set(rgba.a, options)
+  }
+
+  /** Check if any channel is animating */
+  isAnimating(): boolean {
+    return this.rMv.isAnimating() || this.gMv.isAnimating() || this.bMv.isAnimating() || this.aMv.isAnimating()
+  }
+
+  /** Stop all channel animations */
+  stop() {
+    this.rMv.stop()
+    this.gMv.stop()
+    this.bMv.stop()
+    this.aMv.stop()
+  }
+
+  /** Destroy and clean up */
+  destroy() {
+    this.rMv.destroy()
+    this.gMv.destroy()
+    this.bMv.destroy()
+    this.aMv.destroy()
+    this.clearSubscribers()
+  }
+
+  /** Subscribe internal motion values to a callback (used by hooks) */
+  _subscribeChannels(callback: () => void): () => void {
+    const unsubs = [
+      this.rMv.on("change", callback),
+      this.gMv.on("change", callback),
+      this.bMv.on("change", callback),
+      this.aMv.on("change", callback),
+    ]
+    return () => unsubs.forEach((u) => u())
+  }
+}

package/src/motion/color.test.ts

@@ -0,0 +1,115 @@
+import { describe, it, expect } from "vitest"
+import { parseColor, isColorInput } from "./color.js"
+
+describe("parseColor", () => {
+  describe("hex", () => {
+    it("parses 6-digit hex", () => {
+      expect(parseColor("#ff0000")).toEqual({ r: 255, g: 0, b: 0, a: 1 })
+      expect(parseColor("#00ff00")).toEqual({ r: 0, g: 255, b: 0, a: 1 })
+      expect(parseColor("#0000ff")).toEqual({ r: 0, g: 0, b: 255, a: 1 })
+    })
+
+    it("parses 3-digit hex shorthand", () => {
+      expect(parseColor("#f00")).toEqual({ r: 255, g: 0, b: 0, a: 1 })
+      expect(parseColor("#0f0")).toEqual({ r: 0, g: 255, b: 0, a: 1 })
+      expect(parseColor("#00f")).toEqual({ r: 0, g: 0, b: 255, a: 1 })
+    })
+
+    it("parses 8-digit hex with alpha", () => {
+      expect(parseColor("#ff000080")).toEqual({ r: 255, g: 0, b: 0, a: 128 / 255 })
+      expect(parseColor("#00ff00ff")).toEqual({ r: 0, g: 255, b: 0, a: 1 })
+    })
+
+    it("handles case insensitivity", () => {
+      expect(parseColor("#FF0000")).toEqual({ r: 255, g: 0, b: 0, a: 1 })
+      expect(parseColor("#AbCdEf")).toEqual({ r: 171, g: 205, b: 239, a: 1 })
+    })
+  })
+
+  describe("rgb/rgba", () => {
+    it("parses rgb()", () => {
+      expect(parseColor("rgb(255, 0, 0)")).toEqual({ r: 255, g: 0, b: 0, a: 1 })
+      expect(parseColor("rgb(0, 255, 0)")).toEqual({ r: 0, g: 255, b: 0, a: 1 })
+    })
+
+    it("parses rgba()", () => {
+      expect(parseColor("rgba(255, 0, 0, 0.5)")).toEqual({ r: 255, g: 0, b: 0, a: 0.5 })
+      expect(parseColor("rgba(0, 255, 0, 1)")).toEqual({ r: 0, g: 255, b: 0, a: 1 })
+    })
+
+    it("handles spaces", () => {
+      expect(parseColor("rgb( 255 , 0 , 0 )")).toEqual({ r: 255, g: 0, b: 0, a: 1 })
+    })
+  })
+
+  describe("hsl/hsla", () => {
+    it("parses hsl()", () => {
+      // Red: hsl(0, 100%, 50%)
+      const red = parseColor("hsl(0, 100%, 50%)")
+      expect(red.r).toBe(255)
+      expect(red.g).toBe(0)
+      expect(red.b).toBe(0)
+
+      // Green: hsl(120, 100%, 50%)
+      const green = parseColor("hsl(120, 100%, 50%)")
+      expect(green.r).toBe(0)
+      expect(green.g).toBe(255)
+      expect(green.b).toBe(0)
+
+      // Blue: hsl(240, 100%, 50%)
+      const blue = parseColor("hsl(240, 100%, 50%)")
+      expect(blue.r).toBe(0)
+      expect(blue.g).toBe(0)
+      expect(blue.b).toBe(255)
+    })
+
+    it("parses hsla() with alpha", () => {
+      const result = parseColor("hsla(0, 100%, 50%, 0.5)")
+      expect(result.r).toBe(255)
+      expect(result.a).toBe(0.5)
+    })
+  })
+
+  describe("object", () => {
+    it("passes through RGB object", () => {
+      expect(parseColor({ r: 100, g: 150, b: 200 })).toEqual({ r: 100, g: 150, b: 200, a: 1 })
+    })
+
+    it("passes through RGBA object", () => {
+      expect(parseColor({ r: 100, g: 150, b: 200, a: 0.5 })).toEqual({ r: 100, g: 150, b: 200, a: 0.5 })
+    })
+  })
+
+  describe("invalid input", () => {
+    it("returns black for unknown format", () => {
+      expect(parseColor("invalid")).toEqual({ r: 0, g: 0, b: 0, a: 1 })
+      expect(parseColor("red")).toEqual({ r: 0, g: 0, b: 0, a: 1 }) // Named colors not supported
+    })
+  })
+})
+
+describe("isColorInput", () => {
+  it("returns true for hex strings", () => {
+    expect(isColorInput("#ff0000")).toBe(true)
+    expect(isColorInput("#f00")).toBe(true)
+  })
+
+  it("returns true for rgb/hsl strings", () => {
+    expect(isColorInput("rgb(255, 0, 0)")).toBe(true)
+    expect(isColorInput("hsl(0, 100%, 50%)")).toBe(true)
+  })
+
+  it("returns true for RGB objects", () => {
+    expect(isColorInput({ r: 255, g: 0, b: 0 })).toBe(true)
+    expect(isColorInput({ r: 255, g: 0, b: 0, a: 1 })).toBe(true)
+  })
+
+  it("returns false for numbers", () => {
+    expect(isColorInput(123)).toBe(false)
+  })
+
+  it("returns false for invalid strings", () => {
+    expect(isColorInput("hello")).toBe(false)
+    expect(isColorInput("red")).toBe(false)
+  })
+})

package/src/motion/color.ts

@@ -0,0 +1,191 @@
+// Color parsing for spring animations
+// Motion-compatible: hex, rgb(), rgba(), hsl(), hsla(), RGB object
+
+export type RGBA = { r: number; g: number; b: number; a: number }
+export type ColorInput = string | RGBA | { r: number; g: number; b: number }
+
+/**
+ * Parse any supported color format to RGBA.
+ * Supports:
+ * - Hex: "#ff0000", "#f00", "#ff0000ff"
+ * - RGB: "rgb(255, 0, 0)", "rgba(255, 0, 0, 0.5)"
+ * - HSL: "hsl(0, 100%, 50%)", "hsla(0, 100%, 50%, 0.5)"
+ * - Object: { r: 255, g: 0, b: 0 } or { r: 255, g: 0, b: 0, a: 1 }
+ */
+export function parseColor(input: ColorInput): RGBA {
+  if (typeof input === "object") {
+    return {
+      r: input.r,
+      g: input.g,
+      b: input.b,
+      a: "a" in input ? input.a : 1,
+    }
+  }
+
+  const str = input.trim().toLowerCase()
+
+  // Hex: #rgb, #rrggbb, #rrggbbaa
+  if (str.startsWith("#")) {
+    return parseHex(str)
+  }
+
+  // rgb(r, g, b) or rgba(r, g, b, a)
+  if (str.startsWith("rgb")) {
+    return parseRgb(str)
+  }
+
+  // hsl(h, s%, l%) or hsla(h, s%, l%, a)
+  if (str.startsWith("hsl")) {
+    return parseHsl(str)
+  }
+
+  // Unknown format, return black
+  return { r: 0, g: 0, b: 0, a: 1 }
+}
+
+function parseHex(hex: string): RGBA {
+  const h = hex.slice(1)
+
+  if (h.length === 3) {
+    // #rgb -> #rrggbb
+    return {
+      r: parseInt(h[0] + h[0], 16),
+      g: parseInt(h[1] + h[1], 16),
+      b: parseInt(h[2] + h[2], 16),
+      a: 1,
+    }
+  }
+
+  if (h.length === 4) {
+    // #rgba -> #rrggbbaa
+    return {
+      r: parseInt(h[0] + h[0], 16),
+      g: parseInt(h[1] + h[1], 16),
+      b: parseInt(h[2] + h[2], 16),
+      a: parseInt(h[3] + h[3], 16) / 255,
+    }
+  }
+
+  if (h.length === 6) {
+    return {
+      r: parseInt(h.slice(0, 2), 16),
+      g: parseInt(h.slice(2, 4), 16),
+      b: parseInt(h.slice(4, 6), 16),
+      a: 1,
+    }
+  }
+
+  if (h.length === 8) {
+    return {
+      r: parseInt(h.slice(0, 2), 16),
+      g: parseInt(h.slice(2, 4), 16),
+      b: parseInt(h.slice(4, 6), 16),
+      a: parseInt(h.slice(6, 8), 16) / 255,
+    }
+  }
+
+  return { r: 0, g: 0, b: 0, a: 1 }
+}
+
+function parseRgb(str: string): RGBA {
+  // rgb(255, 0, 0) or rgba(255, 0, 0, 0.5)
+  // Also supports spaces: rgb(255 0 0) and rgb(255 0 0 / 0.5)
+  const match = str.match(/rgba?\(\s*(\d+)\s*[,\s]\s*(\d+)\s*[,\s]\s*(\d+)\s*(?:[,/]\s*([\d.]+))?\s*\)/)
+  if (match) {
+    return {
+      r: clamp255(parseInt(match[1], 10)),
+      g: clamp255(parseInt(match[2], 10)),
+      b: clamp255(parseInt(match[3], 10)),
+      a: match[4] ? clamp1(parseFloat(match[4])) : 1,
+    }
+  }
+  return { r: 0, g: 0, b: 0, a: 1 }
+}
+
+function parseHsl(str: string): RGBA {
+  // hsl(0, 100%, 50%) or hsla(0, 100%, 50%, 0.5)
+  const match = str.match(/hsla?\(\s*(\d+)\s*[,\s]\s*([\d.]+)%?\s*[,\s]\s*([\d.]+)%?\s*(?:[,/]\s*([\d.]+))?\s*\)/)
+  if (match) {
+    const h = parseFloat(match[1])
+    const s = parseFloat(match[2])
+    const l = parseFloat(match[3])
+    const a = match[4] ? clamp1(parseFloat(match[4])) : 1
+    return hslToRgb(h, s, l, a)
+  }
+  return { r: 0, g: 0, b: 0, a: 1 }
+}
+
+/**
+ * Convert HSL to RGBA.
+ * h: 0-360, s: 0-100, l: 0-100, a: 0-1
+ */
+export function hslToRgb(h: number, s: number, l: number, a: number): RGBA {
+  // Normalize
+  h = ((h % 360) + 360) % 360
+  s = clamp1(s / 100)
+  l = clamp1(l / 100)
+
+  const c = (1 - Math.abs(2 * l - 1)) * s
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
+  const m = l - c / 2
+
+  let r = 0
+  let g = 0
+  let b = 0
+
+  if (h < 60) {
+    r = c
+    g = x
+    b = 0
+  } else if (h < 120) {
+    r = x
+    g = c
+    b = 0
+  } else if (h < 180) {
+    r = 0
+    g = c
+    b = x
+  } else if (h < 240) {
+    r = 0
+    g = x
+    b = c
+  } else if (h < 300) {
+    r = x
+    g = 0
+    b = c
+  } else {
+    r = c
+    g = 0
+    b = x
+  }
+
+  return {
+    r: Math.round((r + m) * 255),
+    g: Math.round((g + m) * 255),
+    b: Math.round((b + m) * 255),
+    a,
+  }
+}
+
+function clamp255(n: number): number {
+  return Math.max(0, Math.min(255, Math.round(n)))
+}
+
+function clamp1(n: number): number {
+  return Math.max(0, Math.min(1, n))
+}
+
+/**
+ * Check if a value looks like a color input.
+ */
+export function isColorInput(value: unknown): value is ColorInput {
+  if (typeof value === "string") {
+    const s = value.trim().toLowerCase()
+    return s.startsWith("#") || s.startsWith("rgb") || s.startsWith("hsl")
+  }
+  if (typeof value === "object" && value !== null) {
+    const obj = value as Record<string, unknown>
+    return typeof obj.r === "number" && typeof obj.g === "number" && typeof obj.b === "number"
+  }
+  return false
+}

package/src/motion/event-emitter.ts

@@ -0,0 +1,35 @@
+/**
+ * Simple event emitter base class for MotionValue and ColorMotionValue.
+ */
+
+export type EventName = "change" | "animationStart" | "animationComplete"
+export type Subscriber<T> = (value: T) => void
+
+/**
+ * Base class providing event subscription functionality.
+ */
+export abstract class EventEmitter<T = unknown> {
+  protected subscribers = new Map<EventName, Set<Subscriber<any>>>()
+
+  /** Subscribe to events */
+  on<E extends EventName>(event: E, callback: Subscriber<E extends "change" ? T : void>): () => void {
+    if (!this.subscribers.has(event)) {
+      this.subscribers.set(event, new Set())
+    }
+    this.subscribers.get(event)?.add(callback)
+    return () => this.subscribers.get(event)?.delete(callback)
+  }
+
+  /** Notify all subscribers of an event */
+  protected notify(event: EventName, value?: unknown) {
+    const subs = this.subscribers.get(event)
+    if (subs) {
+      for (const cb of subs) cb(value)
+    }
+  }
+
+  /** Clear all subscriptions */
+  protected clearSubscribers() {
+    this.subscribers.clear()
+  }
+}

package/src/motion/frame.ts

@@ -0,0 +1,59 @@
+// setTimeout-based frame loop for Node/TUI (no requestAnimationFrame)
+
+import { useEffect, useRef } from "react"
+import { DEFAULT_FPS } from "../constants.js"
+
+type FrameCallback = (time: number, delta: number) => void
+
+const subscribers = new Set<FrameCallback>()
+let timer: ReturnType<typeof setTimeout> | null = null
+let lastTime = 0
+const FRAME_MS = 1000 / DEFAULT_FPS
+
+function tick() {
+  const now = Date.now()
+  const delta = lastTime ? now - lastTime : FRAME_MS
+  lastTime = now
+
+  for (const cb of subscribers) {
+    cb(now, delta)
+  }
+
+  if (subscribers.size > 0) {
+    timer = setTimeout(tick, FRAME_MS)
+  } else {
+    timer = null
+    lastTime = 0
+  }
+}
+
+export function subscribeFrame(callback: FrameCallback): () => void {
+  subscribers.add(callback)
+  if (!timer) {
+    lastTime = Date.now()
+    timer = setTimeout(tick, FRAME_MS)
+  }
+  return () => {
+    subscribers.delete(callback)
+    if (subscribers.size === 0 && timer) {
+      clearTimeout(timer)
+      timer = null
+      lastTime = 0
+    }
+  }
+}
+
+/**
+ * Hook that calls callback on every animation frame.
+ * Similar to Motion's useAnimationFrame.
+ */
+export function useAnimationFrame(callback: FrameCallback) {
+  const callbackRef = useRef(callback)
+  callbackRef.current = callback
+
+  useEffect(() => {
+    return subscribeFrame((time, delta) => {
+      callbackRef.current(time, delta)
+    })
+  }, [])
+}