Cue Animations

// Padding / EdgeInsets
.all(16)              not EdgeInsets.all(16)
.only(top: 8)         not EdgeInsets.only(top: 8)
.symmetric(h: 16)     not EdgeInsets.symmetric(horizontal: 16)
.fromLTRB(...)        not EdgeInsets.fromLTRB(...)

// BorderRadius
.circular(12)         not BorderRadius.circular(12)
.vertical(top: .circular(16))   not BorderRadius.vertical(...)

// Alignment
.topLeft / .center / .bottomRight   not Alignment.topLeft

// MainAxisAlignment / CrossAxisAlignment / MainAxisSize
.center / .spaceBetween / .min      not MainAxisAlignment.center

// BoxFit / Clip / TextOverflow
.cover / .antiAlias / .fade         not BoxFit.cover

// Colors
Colors.transparent / Colors.white   (unchanged — no shorthand available)

// One-shot entrance when widget mounts
// Supports: repeat, reverseOnRepeat, repeatCount, onEnd
Cue.onMount(
  motion: .smooth(),
  repeat: false,               // loop the animation
  reverseOnRepeat: false,      // ping-pong when looping
  repeatCount: 3,              // finite loop count (null = infinite)
  onEnd: (forward) { ... },   // fires on completion in either direction
  acts: [...],
  child: child,
)

// Toggled by a boolean — forward on true, reverse on false
Cue.onToggle(toggled: isExpanded, motion: .smooth(), child: child)

// Restarts forward every time value changes
Cue.onChange(value: currentTab, motion: .smooth(), fromCurrentValue: true, child: child)

// Driven by pointer hover
Cue.onHover(motion: .interactive(), child: child)

// Driven by focus
Cue.onFocus(motion: .smooth(), child: child)

// Scrubbed continuously as the widget travels through the viewport (parallax-style).
// Progress = 0 when leading edge enters bottom of viewport, 1 when it reaches the top.
// Prefer non-overshoot motions (.smooth, .linear, .easeOut) — springs with bounce
// look jarring when scrubbed.
Cue.onScroll(child: child)

// Plays once when widget scrolls into view; stays complete. Does NOT reverse on scroll-out.
// Until revealed it scrubs like onScroll; once visible it plays forward with its motion.
// Use enabled: false to skip the animation and jump to completed state.
Cue.onScrollVisible(enabled: true, child: child)

// Scrubbed by external progress (e.g. drag)
Cue.onProgress(progress: dragNotifier, child: child)

// Index-based (page carousels, staggered lists)
// Works with CuePageController, CueTabController, CueIndexController
Cue.indexed(controller: cuePageController, index: index, child: child)

// Fully imperative
Cue(controller: myController, child: child)

Cue.onMount(motion: .smooth(), debugLabel: 'HeroCard', child: child)

// Multiple acts, same child — compose freely
Actor(
  delay: 60.ms,
  acts: [
    .fadeIn(),
    .slideY(from: 0.15),
    .scale(from: 0.96),
  ],
  child: child,
)

// Extension shorthand for single child — skips explicit Actor
child.act([.fadeIn(), .slideUp()])

// Inline inside Cue (single animated child)
Cue.onMount(
  motion: .smooth(),
  acts: [.fadeIn(), .slideY(from: 0.2)],
  child: child,
)

.scale(from: 0.9)       // → 1.0 (identity)
.scale(to: 1.05)        // from 1.0 (identity) →
.slideY(from: 0.15)     // → 0.0 (identity)
.blur(from: 8)          // → 0.0 (identity, i.e. sharp)
.padding(to: .symmetric(vertical: 12))  // from zero →

// CORRECT — one Cue coordinates the whole entrance
Cue.onMount(
  motion: .smooth(),
  child: Column(
    children: [
      Actor(acts: [.fadeIn(), .slideY(from: 0.12)], child: title),
      Actor(delay: 60.ms, acts: [.fadeIn(), .slideY(from: 0.12)], child: subtitle),
      Actor(delay: 120.ms, acts: [.fadeIn(), .slideY(from: 0.12)], child: button),
    ],
  ),
)

// WRONG — three separate triggers for the same scene
Cue.onMount(acts: [.fadeIn()], child: title)
Cue.onMount(acts: [.fadeIn()], child: subtitle)   // ✗
Cue.onMount(acts: [.fadeIn()], child: button)     // ✗

Cue(motion: .smooth())          ← default for all Actors below
  Actor(motion: .gentle())      ← default for all acts on this Actor
    Act(motion: .snappy())      ← overrides for this specific act only

// reverse uses the same .smooth() motion — implicit
Cue.onToggle(toggled: isOpen, motion: .smooth(), child: child)

// reverse uses a different motion — explicit override
Cue.onToggle(toggled: isOpen, motion: .smooth(), reverseMotion: .snappy(), child: child)

// same rule on Actor
Actor(motion: .bouncy(), reverseMotion: .linear(160.ms), acts: [...], child: child)

Cue.onMount(
  motion: .smooth(),           // scene default
  child: Column(children: [
    Actor(
      acts: [.fadeIn(), .slideY(from: 0.15)],  // both use .smooth()
      child: title,
    ),
    Actor(
      motion: .gentle(),       // overrides .smooth() for this Actor
      acts: [
        .scale(from: 0.95),    // uses .gentle()
        .fadeIn(motion: .snappy()),  // overrides .gentle() for fadeIn only
      ],
      child: card,
    ),
  ]),
)

Actor(
  delay: 80.ms,              // Actor-level delay
  acts: [
    .fadeIn(),               // starts at 80 ms
    .slideY(from: 0.15, delay: 40.ms),  // starts at 80 + 40 = 120 ms
  ],
  child: child,
)

.smooth()       // fast, clean, no overshoot — best default
.snappy()       // near-instant micro-interactions
.bouncy()       // visible overshoot for emphasis
.gentle()       // slower, softer
.wobbly()       // exaggerated, playful
.interactive()  // responsive drag/hover feel
.spatial()      // layout movement
.effect()       // decorative property changes

// Fixed-duration timing when physics isn't appropriate
.linear(250.ms)
.easeIn(300.ms)
.easeOut(300.ms)
.easeInOut(300.ms)
.curved(400.ms, curve: Curves.easeInOut)

// Special variants
CueMotion.none          // zero-duration, resolves instantly — use when a CueMotion
                        // is required by the API but no animation is wanted
.threshold(200.ms, breakpoint: 0.5)
                        // stays at the start value, then snaps instantly to the end
                        // when progress crosses breakpoint (0→1 fraction).
                        // no interpolation — useful for visibility toggles that must
                        // align precisely with another ongoing animation.

.scale(from: 0.9)              // uniform scale
.zoomIn() / .zoomOut()
.rotate(to: 180)               // visual-only rotation in degrees (transform, no layout impact — prefer this)
.rotateLayout(to: 1, unit: .quarterTurns)  // rotates AND recomputes layout — use only when layout must shift
.rotate3D(to: Rotation3D(x: 15), perspective: 0.001)
.flipX() / .flipY()
.translate(to: Offset(0, 24))  // pixel translation
.translateX(from: -20) / .translateY(from: 20)
.translateFromGlobal(offset: rect.topLeft)   // translate from a global screen position
.translateFromGlobalRect(rect)               // translate from the center of a global rect
.translateFromGlobalKey(key)                 // translate from a widget identified by GlobalKey
.slide(from: Offset(0, 2))     // fractional offset (relative to widget size)
.slideX() / .slideY() / .slideUp() / .slideDown()
.slideFromLeading() / .slideFromTrailing()
.stretch(to: Stretch(x: 1.2, y: 0.8))       // scale axes independently
.skew(to: Skew(x: 0.3))                     // skew transformation
.transform(to: Matrix4.rotationZ(0.3))       // raw Matrix4 (from defaults to identity)
.parallax(slide: 0.3, axis: .horizontal)     // scrub-linked parallax slide

.opacity(from: 0, to: 1)
.fadeIn() / .fadeOut()
.blur(from: 8) / .focus() / .unfocus()
.backdropBlur(to: 8)
.colorTint(from: Colors.white60, to: Colors.black)

// NSize constructors used by sizedClip and sizedBox:
// NSize(w: 200, h: 100)   — explicit width and height
// NSize.width(200)       — fixed width, height follows child
// NSize.height(100)      — fixed height, width follows child
// NSize.square(48)       — equal width and height
// NSize.size(Size(...))  — from a Size object
// NSize.childSize        — both axes follow child (no constraint)
// double.infinity → resolves to parent's max constraint

.sizedBox(width: .tween(40, double.infinity), height: .tween(40, 56))
.sizedClip(from: NSize.square(24), to: NSize.height(68))
.sizedClip(from: NSize.size(rect.size), to: NSize.width(240))
.fractionalSize(widthFactor: .tween(0.2, 1.0), heightFactor: .fixed(0.5))
.padding(to: .symmetric(vertical: 12))
.align(from: .bottomCenter, to: .bottomLeft)
.clipHeight(fromFactor: 0.3) / .clipWidth() / .clip() / .circularClip()

.sizedBox(
  width: .tween(80, double.infinity),  // expands to fill
  height: .fixed(40),                  // height stays constant
)
.sizedBox(width: .tween(100, 300))     // only width animates

.fractionalSize(
  widthFactor: .tween(0.2, 1.0),
  heightFactor: .fixed(0.5),
  alignment: .fixed(.center),
)

.decorate(
  color: .tween(Colors.transparent, Colors.white),
  borderRadius: .tween(.circular(0), .circular(16)),
  border: .fixed(Border.all(color: Colors.blue)),
  boxShadow: .tween(
    [BoxShadow(blurRadius: 0)],
    [BoxShadow(blurRadius: 8, offset: Offset(0, 4))],
  ),
  gradient: .tween(fromGradient, toGradient),
)

// Preferred for card-only animations
CardActor(
  elevation: .tween(1, 8),
  color: .tween(Colors.white, Colors.blue.shade50),
  borderRadius: .tween(.circular(8), .circular(24)),
  shadowColor: .fixed(Colors.black),
  margin: .tween(.zero, .all(8)),
  child: child,
)

// Inside an Actor alongside other acts
Actor(
  acts: [
    CardAct(elevation: .fixed(2), borderRadius: .tween(.circular(8), .circular(24))),
    .scale(from: 0.95),
  ],
  child: child,
)

Stack(
  children: [
    PositionedActor(
      from: .fill(),                           // fills the stack
      to: .fromSTEB(20, 250, 20, 24),          // shrinks to specific insets
      child: myWidget,
    ),
    PositionedActor.keyframed(
      frames: .fractional([...]),
      relativeTo: stackSize,
      child: myWidget,
    ),
  ],
)

DecoratedBoxActor(
  color: .tween(Colors.grey.shade100, Colors.blue.shade50),
  borderRadius: .tween(.circular(8), .circular(32)),
  shape: .circle,
  child: SizedBox.square(dimension: 48),
)

PaintActor(
  painter: myCustomPainter,   // receives CueAnimation<double> to drive paint
  child: child,
)

// Animate along a custom Path — optional autoRotate to face direction of travel
PathMotionAct(
  path: myPath,          // a Path() with a single continuous metric
  autoRotate: true,      // rotate widget to face path direction
  alignment: .center,    // pivot/anchor point
)

// textStyle — animates between two complete TextStyle values
.textStyle(
  from: TextStyle(fontSize: 14, color: Colors.grey),
  to: TextStyle(fontSize: 22, color: Colors.black, fontWeight: .bold),
)
// iconTheme — animates icon properties
.iconTheme(from: IconThemeData(size: 24), to: IconThemeData(size: 20))

PositionedActor(from: .fill(), to: .fromSTEB(20, 250, 20, 24), child: child)
PositionedActor.keyframed(frames: .fractional([...]), relativeTo: size, child: child)

// TweenActor — animate any value with a builder (does not need to be inside Actor)
TweenActor<double>(
  from: 0,
  to: 1,
  motion: .smooth(),
  builder: (context, animation) {
    return FadeTransition(opacity: animation, child: child);
  },
)

ScaleAct.keyframed(
  frames: Keyframes([
    .key(0.92),
    .key(1.06, motion: .bouncy()),
    .key(1.0),
  ], motion: .smooth()),
)

TranslateAct.keyframed(
  frames: .fractional([
    .key(const Offset(0, 24), at: 0.0),
    .key(const Offset(0, -8), at: 0.7),
    .key(Offset.zero, at: 1.0),
  ], duration: 450.ms),
)

// ScaleAct with fractional keyframes (used for custom switch squish)
ScaleAct.keyframed(
  frames: .fractional([
    .key(1.1, at: 0.4),
    .key(1.1, at: 0.6),
    .key(1.0, at: 1.0),
  ]),
)

// Mirror: same animation plays in reverse
.fadeIn(reverse: .mirror(delay: 40.ms))

// To: reverse targets a different value
.scale(to: 1.06, reverse: .to(0.98))

// None: reverse does nothing
.zoomIn(reverse: .none())

// Different motion for forward vs reverse on Cue/Actor
Cue.onToggle(
  toggled: isOpen,
  motion: .smooth(),
  reverseMotion: .snappy(),
  child: child,
)

Actor(
  motion: .smooth(),
  reverseMotion: .linear(160.ms),
  delay: 80.ms,
  reverseDelay: 20.ms,
  acts: [...],
  child: child,
)