ui_animations_pro 0.1.0

ui_animations_pro — production-grade cinematic UI Animations framework for Flutter. Plugin-based Transitions, Composable Choreographer, Timeline Sequencer, Spring Physics Engine, Performance Monitor, [...]

Changelog

All notable changes to ui_animations_pro will be documented in this file.

The format follows Keep a Changelog and this project adheres to Semantic Versioning.

---

0.1.0 — 2026-05-07

Added — Core layer

• AnimationsPro singleton façade with initialize() / dispose() lifecycle
• AnimationsConfig — fully injectable, copyWith-friendly configuration
• AnimationsException hierarchy — 8 typed exceptions (TransitionNotFoundException, SceneNotFoundException, TimelineException, CurveException, PhysicsException, FrameBudgetExceededException, HandleDisposedException, InvalidStepException)
• MotionHandle — full playback control: play(), pause(), resume(), seek(), cancel(), restart(), dispose()
• MotionState enum — idle, playing, paused, reversing, completed, dismissed, cancelled, disposed
• MotionValue<T> — typed reactive wrapper around Animation<T> with map() transform
• AnimationEvent hierarchy — SceneStartedEvent, SceneCompletedEvent, ScenePausedEvent, SceneResumedEvent, SceneCancelledEvent, StepProgressEvent, FrameDropEvent
• AnimatableProperty enum — 22 typed properties with isExpensive / is3D extensions
• Interpolators — lerpDouble, lerpInt, lerpOffset, lerpSize, lerpColor, lerpRect, lerpLog, lerpAngle
• TweenFactory — typed Tween<T> builders including custom<T> with user-supplied lerp function
• MotionDescriptor — scene metadata carrier

Added — Choreography layer

• Scene — immutable, composable DSL: .then(), .step(), .sequence(), .parallel(), .stagger(), .delay(), .loop(), .repeat()
• Timeline — compiled, immutable snapshot of a Scene
• TimelineCompiler — recursive flatten with absolute start / end timing for all step types
• Choreographer — orchestrator: compile, acquire tickers, create MotionHandle, broadcast events, cache timelines
• 8 ChoreoStep implementations:
  • SingleStep — one transition on one target
  • SequenceStep — end-to-end sequential steps
  • ParallelStep — simultaneous steps
  • StaggerStep — progressive delay between steps
  • DelayStep — silent timeline pause
  • LoopStep — infinite loop with optional ping-pong
  • RepeatStep — N-times repeat with optional ping-pong
  • ConditionalStep — runtime predicate → ifTrue / ifFalse branch

Added — Transition layer

• TransitionPlugin abstract contract with build() / buildReverse()
• TransitionRegistry — runtime plugin map with register(), lookup(), has(), all
• 12 built-in plugins (barrel: package:ui_animations_pro/transitions.dart):
  • FadeTransitionPlugin — opacity 0→1
  • SlideTransitionPlugin — directional slide (up, down, left, right) with fractional distance
  • ScaleTransitionPlugin — scale from/to with alignment control
  • RotateTransitionPlugin — full-turn rotation
  • SpringTransitionPlugin — physics spring scale + fade combo
  • Flip3DTransitionPlugin — perspective 3D flip on X or Y axis
  • BlurTransitionPlugin — ImageFilter.blur sigma 0→max (expensive)
  • MorphTransitionPlugin — borderRadius + color interpolation
  • ParallaxTransitionPlugin — depth-offset translate
  • ShimmerTransitionPlugin — ShaderMask highlight sweep
  • RippleTransitionPlugin — expanding circular overlay (expensive)
  • LiquidTransitionPlugin — sinusoidal ClipPath wipe (expensive)

Added — Curves layer

• CurveLibrary — 15 named presets: Apple, Material 3 (emphasized / decelerate / accelerate / standard), Stripe, Linear, Vercel, Overshoot, Anticipate, AnticipateOvershoot, Elastic, Bounce, SlowStart, SlowEnd, SmoothStartEnd
• SpringCurve — Curve backed by SpringSimulation: gentle(), wobbly(), stiff(), slow(), molasses() + custom constructor
• ElasticCurve — configurable amplitude, period, and in/out/inOut modes
• BackCurve — overshoot / undershoot with BackKind (input, out, inOut)
• BezierEditor — build Cubic from 4 control points; parse CSS cubic-bezier(…) strings
• CustomCurve — delegate any double Function(double t) as a Curve

Added — Physics layer (barrel: package:ui_animations_pro/physics.dart)

• PhysicsSimulator — abstract contract: position(t), velocity(t), isDone(t)
• SpringSim — mass-spring-damper: under-damped, critically-damped, over-damped branches
• FrictionSim — exponential deceleration (fling / scroll)
• GravitySim — uniformly accelerated motion with configurable end boundary
• MagneticSim — inverse-square pull / snap towards target
• DampingPolicy — helpers: computeDamping(), isUnderdamped(), isOverdamped(), isCritical()

Added — Engine layer

• MotionEngine — headless (no UI): sampleAt(scene, ms), compile(scene), samplePhysics(sim)
• TickerProviderPool — reusable TickerProvider pool; grows dynamically beyond capacity
• FrameBudgeter — SchedulerBinding.addTimingsCallback per-frame budget monitor with onDrop callback
• PerformanceMonitor — sampled FPS Stream<double> via periodic Timer
• AnimationScheduler — limits concurrent MotionHandle count to maxConcurrent
• LifecycleObserver — WidgetsBindingObserver that pauses/resumes all active scenes on app lifecycle changes

Added — Widget layer

• MotionWidget — drop-in animated wrapper: transition, duration, curve, autoPlay, params, onCompleted
• MotionBuilder — AnimatedBuilder-style widget observing a MotionHandle
• AnimatedScene — declarative scene playback widget with autoPlay + onReady
• StaggerList — Column or Row with per-item Future.delayed stagger; supports both axes
• HeroMotion — enhanced Hero with custom flightShuttleBuilder, CurvedRectTween, and fade option
• MorphContainer — stateful AnimationController-driven DecorationTween + size interpolation
• ParallaxView — scroll-driven or pointer-driven depth layers via List<ParallaxLayer>; smooth AnimationController interpolation
• ShimmerBox — ShaderMask shimmer with 4 directions (LTR, RTL, TTB, BTT); ShimmerBox.rect factory; enabled toggle
• RevealWidget — ClipPath clip-path reveal in 6 directions: left, right, top, bottom, center, radial

Added — Route layer

• MotionPageRoute<T> — PageRouteBuilder accepting any TransitionPlugin
• SharedAxisRoute<T> — X / Y / Z shared-axis slide
• FadeThroughRoute<T> — fade-through cross-fade
• ContainerTransformRoute<T> — scale 0.85→1.0 container transform
• RouteAdapter — static push<T> helper

Added — Gesture layer

• GestureMotion — drag → progress (0.0–1.0) builder; vertical or horizontal axis; onRelease callback
• SwipeDismiss — horizontal swipe past threshold → animate out + onDismissed
• PinchZoomMotion — two-finger pinch with minScale / maxScale clamp
• PanParallax — mouse/touch hover offset with MouseRegion + AnimatedContainer smoothing
• VelocityTracker — 8-sample sliding window velocity estimator

Added — Accessibility layer

• ReduceMotionPolicy — InheritedWidget reading WidgetsBinding.accessibilityFeatures.disableAnimations; 4 behaviors: disable, crossFade, scaleDuration, ignore
• ReduceMotionPolicyData — immutable snapshot with applyTo(Duration) and shouldSimplify
• AccessibilityBridge — Semantics wrapper with label, hint, liveRegion, focusable; policy-aware reducedChild fallback
• MotionAwareBuilder — builder receiving (context, policyData, resolvedDuration)
• SemanticAnnouncer — static announce(), polite(), assertive() via SemanticsService
• AnimationAnnouncer — widget firing announcements at forward, completed, dismissed milestones

Added — Integration layer

• MotionProvider — StatefulWidget + _MotionInherited: provides MotionEngine + AnimationsConfig to the tree; MotionProvider.of(context) / maybeOf(context)
• MotionObserver — event bus: watch(tag, animation) / unwatch(tag); events broadcast Stream<MotionEvent>
• AnimationDebouncer — widget debouncing boolean active prop before forwarding to AnimationController
• Debouncer — pure Dart timer-based debounce with run(), cancel(), dispose(), isPending
• Throttler — leading-edge throttle with run(), reset()
• ThemeBridge — ThemeData adapter exposing durations, curves, colours, shadows, border radii, spacing, stagger helpers

Added — Barrels

• lib/ui_animations_pro.dart — main public barrel (all layers)
• lib/transitions.dart — 12 transition plugins
• lib/physics.dart — 5 physics simulators + policy

Added — Tests

• test/unit/animations_exception_test.dart — 8 exception types
• test/unit/motion_state_test.dart — isActive, isFinished, canResume
• test/unit/curve_library_test.dart — CurveLibrary, SpringCurve, ElasticCurve, BackCurve, BezierEditor, CustomCurve
• test/unit/physics_test.dart — SpringSim (under/critical/overdamped), FrictionSim, GravitySim, MagneticSim, DampingPolicy
• test/unit/timeline_compiler_test.dart — single, sequence, parallel, stagger, repeat, nested, startOffset, compile
• test/unit/transition_registry_test.dart — lookup, register, overwrite, isExpensive; widget tests for Fade, Slide, Scale
• test/unit/interpolators_test.dart — all Interpolators + TweenFactory + AnimatableProperty extensions
• test/unit/frame_budgeter_test.dart — FrameBudgeter, PerformanceMonitor, TickerProviderPool
• test/unit/debouncer_test.dart — Debouncer, Throttler
• test/widget/motion_widget_test.dart — MotionWidget, StaggerList, ShimmerBox, RevealWidget, MorphContainer, HeroMotion, ParallaxView
• test/widget/gesture_widget_test.dart — GestureMotion, SwipeDismiss, PinchZoomMotion, PanParallax, VelocityTracker
• test/widget/route_widget_test.dart — all 5 route types + RouteAdapter
• test/integration/scene_playback_test.dart — initialisation, Scene DSL, named registry, Choreographer, MotionHandle, MotionEngine headless

Added — Example app

• example/motion_demo/lib/main.dart — full showcase:
  • Transition grid (all 12 plugins, tap to animate)
  • Stagger list (5 items, spring, show/hide toggle)
  • Physics demo (Spring wobbly/stiff/molasses/elastic animated balls)
  • Curves demo (6 curves side-by-side progress bars)
  • Shimmer demo (skeleton loader with loading/loaded toggle)
  • Reveal demo (all 6 directions, direction picker chips)
  • Morph demo (tap to expand/collapse container)
  • Gesture demo (drag progress, pinch-zoom, pan parallax)
  • Routes demo (6 navigation buttons, each with a different route)
  • Accessibility demo (MotionAwareBuilder + AccessibilityBridge + policy display)
  • Live FPS badge in app bar

---

[Unreleased]

Planned — v0.2.0

• build_runner code generation: @Scene, @AnimateProperty, @StaggerGroup annotations
• Auto-generated SceneRegistry from annotated classes

Planned — v0.3.0

• PathAnimationEngine — animate along SVG Path with dash-offset and stroke progress
• PathFollower widget

Planned — v0.4.0

• ParticleSystem — confetti, smoke, stars, fire emitter at 60 fps stable
• ParticleEmitter widget

Planned — v0.5.0

• LottieBridge — import .lottie JSON as native Scene
• RiveBridge — import .riv as native Scene; scrubable and composable

Planned — v0.6.0

• SkeletonAutoLoader — auto-detect loading widgets; apply matched-shape shimmer automatically

Planned — v0.7.0

• LiveTimelineEditor — in-app drag-and-drop timeline editor with real-time preview and Dart code export

Planned — v0.8.0

• WebMotionExporter — export Scene as CSS animations / WAAPI keyframes for Flutter Web SEO

Planned — v1.0.0

• MotionGoldenTester — pixel-by-pixel animation frame regression testing framework
• MultiWindowSync — synchronised animations across Flutter desktop windows
• Stable API declaration; full pub.dev publication