@effect-tui/react 0.9.3 → 0.10.1

package/src/motion/brands.ts

@@ -0,0 +1,10 @@
+/**
+ * Brand Symbols for MotionValue type detection.
+ * Separated to avoid circular dependency issues.
+ */
+
+/** Brand Symbol for safer MotionValue detection */
+export const MOTION_VALUE_BRAND = Symbol.for("effect-tui/MotionValue")
+
+/** Brand Symbol for safer ColorMotionValue detection */
+export const COLOR_MOTION_VALUE_BRAND = Symbol.for("effect-tui/ColorMotionValue")

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

@@ -2,16 +2,22 @@
  * ColorMotionValue - animates RGBA colors using 4 internal numeric springs.
  */
 
+import { COLOR_MOTION_VALUE_BRAND } from "./brands.js"
 import { type ColorInput, parseColor, type RGBA } from "./color.js"
 import { EventEmitter } from "./event-emitter.js"
 import { MotionValue } from "./motion-value.js"
 import type { SpringOptions } from "./types.js"
 
+export { COLOR_MOTION_VALUE_BRAND } from "./brands.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> {
+	/** @internal Brand for safe type detection */
+	readonly [COLOR_MOTION_VALUE_BRAND] = true
+
 	private rMv: MotionValue<number>
 	private gMv: MotionValue<number>
 	private bMv: MotionValue<number>

package/src/motion/hooks.ts

@@ -2,7 +2,7 @@
  * React hooks for spring animations.
  */
 
-import { useCallback, useEffect, useRef } from "react"
+import { useCallback, useEffect, useRef, useState } from "react"
 import { useRenderer } from "../renderer.js"
 import type { ColorInput } from "./color.js"
 import { ColorMotionValue } from "./color-motion-value.js"
@@ -211,13 +211,18 @@ export function useColorMotionValue(initial: ColorInput): ColorMotionValue {
 /**
  * Create a spring-animated color. Accepts hex, rgb(), hsl(), or {r,g,b} object.
  *
+ * Returns a MotionValue - best for <canvas draw={...}> where you read in callbacks.
+ * For JSX props, use useColorSpringState instead.
+ *
  * @example
  * const [colorMv, setColor] = useColorSpring("#ff0000", { visualDuration: 0.5 })
  * setColor("#00ff00")  // Spring to green
- * setColor("hsl(240, 100%, 50%)")  // Spring to blue
  *
- * // In draw callback
- * const { r, g, b } = colorMv.get()
+ * // In canvas draw callback
+ * <canvas draw={(ctx) => {
+ *   const { r, g, b } = colorMv.get()
+ *   ctx.fill(0, 0, 10, 5, "█", { fg: Colors.rgb(r, g, b) })
+ * }} />
  */
 export function useColorSpring(
 	initial: ColorInput,
@@ -243,3 +248,44 @@ export function useColorSpring(
 
 	return [mv, set]
 }
+
+/**
+ * Like useColorSpring, but returns React state that updates during animation.
+ * Use this when you need spring values in JSX props.
+ *
+ * For <canvas draw={...}> callbacks, use useColorSpring instead (better perf).
+ *
+ * @example
+ * const [color, setColor] = useColorSpringState("#ff0000", { visualDuration: 0.5 })
+ * setColor("#00ff00")  // Spring to green
+ *
+ * // In JSX - React re-renders as the spring animates
+ * <box bg={Colors.rgb(color.r, color.g, color.b)}>
+ *   <text>Hello</text>
+ * </box>
+ */
+export function useColorSpringState(
+	initial: ColorInput,
+	options?: SpringOptions,
+): [{ r: number; g: number; b: number; a: number }, (color: ColorInput) => void] {
+	const mv = useColorMotionValue(initial)
+	const [value, setValue] = useState(() => mv.get())
+	const optionsRef = useRef(options)
+	optionsRef.current = options
+
+	// Subscribe to spring changes and update React state
+	useEffect(() => {
+		return mv._subscribeChannels(() => {
+			setValue(mv.get())
+		})
+	}, [mv])
+
+	const set = useCallback(
+		(color: ColorInput) => {
+			mv.set(color, optionsRef.current)
+		},
+		[mv],
+	)
+
+	return [value, set]
+}

package/src/motion/index.ts

@@ -5,10 +5,13 @@ export { useAnimationFrame } from "./frame.js"
 export type { ColorInput, MotionValue, RGBA, SpringOptions } from "./motion-value.js"
 export {
 	// Color springs
+	COLOR_MOTION_VALUE_BRAND,
 	ColorMotionValue,
+	MOTION_VALUE_BRAND,
 	motionValue,
 	useColorMotionValue,
 	useColorSpring,
+	useColorSpringState,
 	useMotionValue,
 	useMotionValueEvent,
 	useSpring,

package/src/motion/motion-value.ts

@@ -3,11 +3,14 @@
  * Inspired by framer-motion's MotionValue.
  */
 
+import { MOTION_VALUE_BRAND } from "./brands.js"
 import { EventEmitter } from "./event-emitter.js"
 import { subscribeFrame } from "./frame.js"
 import { createSpringResolver, springFromVisualDuration } from "./spring-math.js"
 import { DEFAULT_SPRING_OPTIONS, type SpringOptions } from "./types.js"
 
+export { MOTION_VALUE_BRAND } from "./brands.js"
+
 /** Create a MotionValue. Factory function like Motion's motionValue(). */
 export function motionValue<T>(initial: T): MotionValue<T> {
 	return new MotionValue(initial)
@@ -17,6 +20,9 @@ export function motionValue<T>(initial: T): MotionValue<T> {
  * MotionValue tracks a value and its velocity, supporting spring animations.
  */
 export class MotionValue<T = number> extends EventEmitter<T> {
+	/** @internal Brand for safe type detection */
+	readonly [MOTION_VALUE_BRAND] = true
+
 	private current: T
 	private target: T
 	private velocity = 0
@@ -124,11 +130,12 @@ export class MotionValue<T = number> extends EventEmitter<T> {
 }
 
 export type { ColorInput, RGBA } from "./color.js"
-export { ColorMotionValue } from "./color-motion-value.js"
+export { COLOR_MOTION_VALUE_BRAND, ColorMotionValue } from "./color-motion-value.js"
 export type { EventName, Subscriber } from "./event-emitter.js"
 export {
 	useColorMotionValue,
 	useColorSpring,
+	useColorSpringState,
 	useMotionValue,
 	useMotionValueEvent,
 	useSpring,

package/src/motion/use-sequence.ts

@@ -1,17 +1,51 @@
 // useSequence - Timed discrete state sequences (motion.dev-style keyframes)
 // For animating through discrete values like emojis, strings, or any non-numeric state
 
-import { useEffect, useState } from "react"
+import { useCallback, useEffect, useRef, useState } from "react"
 
 export interface SequenceOptions<T> {
 	/** Array of values to animate through */
 	keyframes: T[]
-	/** Position of each keyframe as 0-1 fraction (must match keyframes length) */
-	times: number[]
+	/** Position of each keyframe as 0-1 fraction (defaults to evenly spaced) */
+	times?: number[]
 	/** Total duration in milliseconds */
 	duration: number
+	/** Initial delay before starting (ms) */
+	delay?: number
 	/** Start automatically (default: true) */
 	autoPlay?: boolean
+	/** Change this value to replay the sequence */
+	playKey?: unknown
+	/** Optional callback when the sequence finishes */
+	onComplete?: () => void
+	/** Optional callback for each keyframe change */
+	onUpdate?: (value: T, index: number) => void
+}
+
+function clamp01(value: number) {
+	if (!Number.isFinite(value)) return 0
+	if (value < 0) return 0
+	if (value > 1) return 1
+	return value
+}
+
+function resolveTimes(count: number, times?: number[]): number[] {
+	if (count <= 0) return []
+	if (!times || times.length !== count) {
+		if (count === 1) return [0]
+		const step = 1 / (count - 1)
+		return Array.from({ length: count }, (_, i) => i * step)
+	}
+
+	const resolved = new Array<number>(count)
+	let prev = 0
+	resolved[0] = 0
+	for (let i = 1; i < count; i++) {
+		const next = Math.max(prev, clamp01(times[i] ?? 0))
+		resolved[i] = next
+		prev = next
+	}
+	return resolved
 }
 
 /**
@@ -30,22 +64,88 @@ export interface SequenceOptions<T> {
  * ```
  */
 export function useSequence<T>(options: SequenceOptions<T>): T {
-	const { keyframes, times, duration, autoPlay = true } = options
+	const { keyframes, autoPlay = true, playKey } = options
 	const [index, setIndex] = useState(0)
+	const optionsRef = useRef(options)
+	optionsRef.current = options
+	const timersRef = useRef<NodeJS.Timeout[]>([])
+	const runIdRef = useRef(0)
+	const prevPlayKeyRef = useRef<unknown>(playKey)
+	const hasInitializedRef = useRef(false)
 
-	useEffect(() => {
-		if (!autoPlay || keyframes.length <= 1) return
+	const clearTimers = useCallback(() => {
+		for (const timer of timersRef.current) {
+			clearTimeout(timer)
+		}
+		timersRef.current = []
+	}, [])
+
+	const play = useCallback(() => {
+		const { keyframes, times, duration, delay = 0, onComplete, onUpdate } = optionsRef.current
+		clearTimers()
+		runIdRef.current += 1
+		const runId = runIdRef.current
+
+		if (keyframes.length === 0) return
+
+		setIndex((prev) => (prev === 0 ? prev : 0))
+		onUpdate?.(keyframes[0], 0)
+
+		if (keyframes.length === 1) {
+			onComplete?.()
+			return
+		}
 
-		const timers: NodeJS.Timeout[] = []
+		const resolvedTimes = resolveTimes(keyframes.length, times)
+		const durationMs = Number.isFinite(duration) ? Math.max(0, duration) : 0
+		const delayMs = Number.isFinite(delay) ? Math.max(0, delay) : 0
 
-		// Schedule each keyframe transition
 		for (let i = 1; i < keyframes.length; i++) {
-			const delayMs = times[i]! * duration
-			timers.push(setTimeout(() => setIndex(i), delayMs))
+			const targetDelay = delayMs + resolvedTimes[i]! * durationMs
+			const timer = setTimeout(() => {
+				if (runId !== runIdRef.current) return
+				setIndex(i)
+				onUpdate?.(keyframes[i]!, i)
+				if (i === keyframes.length - 1) {
+					onComplete?.()
+				}
+			}, targetDelay)
+			timersRef.current.push(timer)
+		}
+	}, [clearTimers])
+
+	// Handle autoPlay on initial mount
+	useEffect(() => {
+		if (hasInitializedRef.current) return
+		hasInitializedRef.current = true
+		if (autoPlay) {
+			play()
 		}
+		return () => clearTimers()
+	}, [autoPlay, play, clearTimers])
 
-		return () => timers.forEach(clearTimeout)
-	}, [keyframes, times, duration, autoPlay])
+	// Handle playKey changes - ALWAYS replay regardless of autoPlay
+	useEffect(() => {
+		if (playKey !== prevPlayKeyRef.current) {
+			prevPlayKeyRef.current = playKey
+			play()
+		}
+	}, [playKey, play])
+
+	useEffect(() => {
+		return () => clearTimers()
+	}, [clearTimers])
+
+	useEffect(() => {
+		if (keyframes.length === 0) return
+		if (index >= keyframes.length) {
+			setIndex(keyframes.length - 1)
+		}
+	}, [index, keyframes.length])
 
-	return keyframes[index]!
+	if (keyframes.length === 0) {
+		return undefined as T
+	}
+	const safeIndex = Math.min(index, keyframes.length - 1)
+	return keyframes[safeIndex]!
 }

package/src/reconciler/types.ts

@@ -132,6 +132,26 @@ export interface CommonProps {
 	/** Maximum height - natural size won't exceed this */
 	maxHeight?: number
 
-	/** Index signature for Record<string, unknown> compatibility */
+	/**
+	 * Called after layout with the element's final dimensions.
+	 * Fires only when size changes (deduplicated).
+	 *
+	 * @example
+	 * ```tsx
+	 * const [size, setSize] = useState({ width: 0, height: 0 })
+	 * <vstack greedy onLayout={setSize}>
+	 *   <text>Width: {size.width}</text>
+	 * </vstack>
+	 * ```
+	 */
+	onLayout?: (size: { width: number; height: number; x: number; y: number }) => void
+
+	/** React key prop for list reconciliation */
+	key?: string | number
+
+	/**
+	 * Index signature for Record<string, unknown> compatibility.
+	 * TODO: Remove this and properly type all props to catch typos like "grow" instead of "greedy"
+	 */
 	[key: string]: unknown
 }