CSS Animation Playground — Go source

// Package animation is the Go twin of CosmoDev's src/lib/animation.ts (dual
// source: the web lib is TypeScript, the CLI lib is Go — kept in lock-step).
// Pure + deterministic, never panics. The table-driven tests in
// animation_test.go share vectors with src/lib/animation.test.ts so the two
// implementations are held to the same contract.
//
// The CSS cubic-bezier easing runs from P0=(0,0) to P3=(1,1) with control
// points P1=(x1,y1), P2=(x2,y2). Every exported function is total: it coerces
// non-finite inputs to 0, never panics, and always returns a finite value —
// mirroring the TS lib exactly.
package animation

import (
	"math"
	"regexp"
	"strconv"
)

// BezierCoords is the four control-point coordinates of a CSS cubic-bezier
// easing: [x1, y1, x2, y2]. It is the Go twin of TS's BezierCoords tuple.
type BezierCoords [4]float64

// EasingPresets holds the named CSS easings expressed as their cubic-bezier
// control-point coords. Mirrors EASING_PRESETS in the TS lib. Iteration order
// is not significant (Go maps are unordered) and no test depends on it.
var EasingPresets = map[string]BezierCoords{
	"linear":      {0, 0, 1, 1},
	"ease":        {0.25, 0.1, 0.25, 1},
	"ease-in":     {0.42, 0, 1, 1},
	"ease-out":    {0, 0, 0.58, 1},
	"ease-in-out": {0.42, 0, 0.58, 1},
}

// bezierPoly holds the polynomial coefficients (a, b, c) for one axis, where
// c1 and c2 are that axis's control-point coordinates.
type bezierPoly struct{ a, b, c float64 }

// bezierCoeffs computes the axis polynomial coefficients for control-point
// coords c1 and c2. Mirrors bezierCoeffs() in the TS lib.
func bezierCoeffs(c1, c2 float64) bezierPoly {
	c := 3 * c1
	b := 3*(c2-c1) - c
	a := 1 - c - b
	return bezierPoly{a: a, b: b, c: c}
}

// sample evaluates the axis polynomial: ((a·t + b)·t + c)·t.
func sample(t float64, cf bezierPoly) float64 {
	return ((cf.a*t+cf.b)*t + cf.c) * t
}

// sampleDerivative evaluates the derivative of the axis polynomial:
// (3a·t + 2b)·t + c.
func sampleDerivative(t float64, cf bezierPoly) float64 {
	return (3*cf.a*t+2*cf.b)*t + cf.c
}

// fin coerces a non-finite value to 0, mirroring the TS lib's Number.isFinite
// guard (NaN and ±Infinity → 0).
func fin(v float64) float64 {
	if math.IsNaN(v) || math.IsInf(v, 0) {
		return 0
	}
	return v
}

// CubicBezierY solves the cubic-bezier easing for output y given an animation
// progress x in [0,1] and the four control-point coords. It is the Go twin of
// cubicBezierY() in src/lib/animation.ts. It is total: non-finite inputs are
// coerced to 0, progress outside [0,1] is clamped, and the endpoints are exact
// (y(0)=0, y(1)=1). It uses Newton-Raphson (clamped, 8 iterations) and never
// panics.
func CubicBezierY(x, x1, y1, x2, y2 float64) float64 {
	// Total function: coerce non-finite progress to 0, clamp, guarantee endpoints.
	px := fin(x)
	if px <= 0 {
		return 0
	}
	if px >= 1 {
		return 1
	}

	xC := bezierCoeffs(fin(x1), fin(x2))
	yC := bezierCoeffs(fin(y1), fin(y2))

	// Newton-Raphson: find t such that x(t) = px, then read y(t).
	// px is a strong initial guess because x(t) is monotonic for valid curves.
	t := px
	for i := 0; i < 8; i++ {
		dx := sample(t, xC) - px
		if math.Abs(dx) < 1e-6 {
			break
		}
		d := sampleDerivative(t, xC)
		if math.Abs(d) < 1e-7 { // guard against division by ~0
			break
		}
		t -= dx / d
	}
	if t < 0 {
		t = 0
	} else if t > 1 {
		t = 1
	}
	return sample(t, yC)
}

// CSSBezier formats four control-point coords as a CSS cubic-bezier(...)
// string. It is the Go twin of cssBezier() in src/lib/animation.ts: each coord
// is rounded to 6 decimal places (stripping float noise and trailing zeros) and
// emitted in its shortest decimal form.
func CSSBezier(x1, y1, x2, y2 float64) string {
	return "cubic-bezier(" +
		formatCoord(x1) + "," +
		formatCoord(y1) + "," +
		formatCoord(x2) + "," +
		formatCoord(y2) + ")"
}

// formatCoord mirrors the TS cssBezier formatter: Math.round(n*1e6)/1e6 then
// String(...). The shortest fixed-point form (FormatFloat 'f' -1) matches JS
// String() for the magnitudes CSS bezier coords take and never emits an
// exponent, so the output round-trips through ParseCSSBezier's decimal regex.
func formatCoord(n float64) string {
	rounded := math.Round(n*1e6) / 1e6
	if rounded == 0 {
		rounded = 0 // normalize -0 → 0 (mirrors JS String(-0) === "0")
	}
	return strconv.FormatFloat(rounded, 'f', -1, 64)
}

// bezierRe matches a CSS cubic-bezier(x1, y1, x2, y2) string with four numeric
// coords, case-insensitively, mirroring the regex in parseCssBezier(). RE2 is
// non-backtracking but this pattern is a linear, alternation-free match, so it
// is equivalent to the JS regex.
var bezierRe = regexp.MustCompile(`(?i)^\s*cubic-bezier\(\s*(-?\d*\.?\d+)\s*,\s*(-?\d*\.?\d+)\s*,\s*(-?\d*\.?\d+)\s*,\s*(-?\d*\.?\d+)\s*\)\s*$`)

// ParseCSSBezier parses a CSS cubic-bezier(x1, y1, x2, y2) string into its four
// coords. It is the Go twin of parseCssBezier() in src/lib/animation.ts. The
// second return value is false (the null of the TS lib) for anything that isn't
// a valid cubic-bezier() — including named easings like "linear". Never panics.
func ParseCSSBezier(str string) (BezierCoords, bool) {
	m := bezierRe.FindStringSubmatch(str)
	if m == nil {
		return BezierCoords{}, false
	}
	var coords BezierCoords
	for i := 0; i < 4; i++ {
		v, err := strconv.ParseFloat(m[i+1], 64)
		if err != nil || math.IsNaN(v) || math.IsInf(v, 0) {
			return BezierCoords{}, false
		}
		coords[i] = v
	}
	return coords, true
}