@apexnative/navigation 0.0.0-stage → 1.0.0-alpha.0

package/ios/Animations/Interpolators/ANNCurve.mm

@@ -0,0 +1,301 @@
+#import "ANNCurve.h"
+#import "ANNInterpolationOptions.h"
+#import "ANNTrack.h"
+#import <React/RCTLog.h>
+#import <cmath>
+
+// The spring's defaults, also for a `mass`, `damping` or `stiffness` not above 0.
+static const double ANNSpringMass = 3;
+static const double ANNSpringDamping = 500;
+static const double ANNSpringStiffness = 200;
+
+// The number of steps of the `fastOutSlowIn` table: 201 values.
+static const int ANNFastOutSlowInSteps = 200;
+
+// One coordinate of the cubic Bézier from 0 to 1 with the control values `a` and `b`, at its parameter `s`.
+static double ANNBezier(double s, double a, double b) {
+    double r = 1 - s;
+    return 3 * r * r * s * a + 3 * r * s * s * b + s * s * s;
+}
+
+// The table, computed once by our own code: the curve's y at x = i/200, the parameter found by bisection, rounded to 4
+// decimals.
+static const double *ANNFastOutSlowInTable(void) {
+    static double table[ANNFastOutSlowInSteps + 1];
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      for (int i = 0; i <= ANNFastOutSlowInSteps; i++) {
+          double x = (double)i / ANNFastOutSlowInSteps;
+          double low = 0;
+          double high = 1;
+          for (int step = 0; step < 60; step++) {
+              double middle = (low + high) / 2;
+              if (ANNBezier(middle, 0.4, 0.2) < x) {
+                  low = middle;
+              } else {
+                  high = middle;
+              }
+          }
+          double y = ANNBezier((low + high) / 2, 0, 1);
+          table[i] = std::round(y * 10000) / 10000;
+      }
+    });
+    return table;
+}
+
+double ANNFastOutSlowIn(double p) {
+    if (p <= 0) {
+        return 0;
+    }
+    if (p >= 1) {
+        return 1;
+    }
+    const double *table = ANNFastOutSlowInTable();
+    double position = p * ANNFastOutSlowInSteps;
+    int index = MIN((int)position, ANNFastOutSlowInSteps - 1);
+    double weight = position - index;
+    return table[index] + weight * (table[index + 1] - table[index]);
+}
+
+static ANNCurveType ANNCurveTypeNamed(NSString *name) {
+    static NSDictionary<NSString *, NSNumber *> *types;
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      types = @{
+          @"linear" : @(ANNCurveTypeLinear),
+          @"accelerate" : @(ANNCurveTypeAccelerate),
+          @"decelerate" : @(ANNCurveTypeDecelerate),
+          @"accelerateDecelerate" : @(ANNCurveTypeAccelerateDecelerate),
+          @"decelerateAccelerate" : @(ANNCurveTypeDecelerateAccelerate),
+          @"fastOutSlowIn" : @(ANNCurveTypeFastOutSlowIn),
+          @"overshoot" : @(ANNCurveTypeOvershoot),
+          @"spring" : @(ANNCurveTypeSpring),
+      };
+    });
+    NSNumber *type = name ? types[name] : nil;
+    return type ? (ANNCurveType)type.integerValue : ANNCurveTypeLinear;
+}
+
+@implementation ANNCurve {
+    double _factor;
+    double _tension;
+    // The spring: its damping ζ = c / 2m (critical at most without `allowsOverdamping`), its own frequency ω₀ = √(k/m),
+    // the start velocity and the property's duration in seconds.
+    double _zeta;
+    double _omega;
+    double _velocity;
+    NSTimeInterval _duration;
+}
+
++ (instancetype)curveWithOptions:(ANNInterpolationOptions *)options
+                        duration:(NSTimeInterval)duration {
+    ANNCurveType type = ANNCurveTypeNamed([options.type withDefault:nil]);
+    return [[self alloc] initWithType:type
+                               factor:[options.factor withDefault:1]
+                              tension:[options.tension withDefault:1]
+                                 mass:[options.mass withDefault:ANNSpringMass]
+                              damping:[options.damping withDefault:ANNSpringDamping]
+                            stiffness:[options.stiffness withDefault:ANNSpringStiffness]
+                    allowsOverdamping:[options.allowsOverdamping withDefault:NO]
+                      initialVelocity:[options.initialVelocity withDefault:0]
+                             duration:duration];
+}
+
++ (instancetype)linear {
+    return [[self alloc] initWithType:ANNCurveTypeLinear
+                               factor:1
+                              tension:1
+                                 mass:ANNSpringMass
+                              damping:ANNSpringDamping
+                            stiffness:ANNSpringStiffness
+                    allowsOverdamping:NO
+                      initialVelocity:0
+                             duration:0];
+}
+
+- (instancetype)initWithType:(ANNCurveType)type
+                      factor:(double)factor
+                     tension:(double)tension
+                        mass:(double)mass
+                     damping:(double)damping
+                   stiffness:(double)stiffness
+           allowsOverdamping:(BOOL)allowsOverdamping
+             initialVelocity:(double)initialVelocity
+                    duration:(NSTimeInterval)duration {
+    if (self = [super init]) {
+        _type = type;
+        _factor = factor;
+        _tension = tension;
+        double m = mass > 0 ? mass : ANNSpringMass;
+        double c = damping > 0 ? damping : ANNSpringDamping;
+        double k = stiffness > 0 ? stiffness : ANNSpringStiffness;
+        _omega = std::sqrt(k / m);
+        _zeta = c / (2 * m);
+        // Without `allowsOverdamping` a damping above the critical one counts as critical: the spring comes as fast as
+        // it can without swinging, it doesn't crawl.
+        if (!allowsOverdamping && _zeta > _omega) {
+            _zeta = _omega;
+        }
+        _velocity = initialVelocity;
+        _duration = duration > 0 ? duration : 0;
+        if (type == ANNCurveTypeFastOutSlowIn) {
+            ANNFastOutSlowInTable();
+        }
+    }
+    return self;
+}
+
+- (double)valueAt:(double)p {
+    switch (_type) {
+        case ANNCurveTypeLinear:
+            return p;
+        case ANNCurveTypeAccelerate:
+            return std::pow(p, 2 * _factor);
+        case ANNCurveTypeDecelerate:
+            return 1 - std::pow(1 - p, 2 * _factor);
+        case ANNCurveTypeAccelerateDecelerate:
+            // Slow at both ends, the mirror of `decelerateAccelerate`.
+            return p < 0.5 ? 4 * p * p * p : 1 - 4 * (1 - p) * (1 - p) * (1 - p);
+        case ANNCurveTypeDecelerateAccelerate: {
+            // Fast at both ends, no speed in the middle, f(0) = 0 and f(1) = 1.
+            double d = p - 0.5;
+            return 0.5 + 4 * d * d * d;
+        }
+        case ANNCurveTypeFastOutSlowIn:
+            return ANNFastOutSlowIn(p);
+        case ANNCurveTypeOvershoot: {
+            double r = p - 1;
+            return 1 + r * r * ((_tension + 1) * r + _tension);
+        }
+        case ANNCurveTypeSpring:
+            return [self springAt:p];
+    }
+    return p;
+}
+
+// The mass on a spring with damping: m·x″ + c·x′ + k·x = 0, x(0) = −1, x′(0) = `initialVelocity`, f = 1 + x(t), with t
+// = p × the property's duration in seconds.
+- (double)springAt:(double)p {
+    double t = p * _duration;
+    double zeta = _zeta;
+    double omega = _omega;
+    double velocity = _velocity;
+    double x;
+    if (std::fabs(zeta - omega) < 1e-9) {
+        x = std::exp(-zeta * t) * (-1 + (velocity - zeta) * t);
+    } else if (zeta < omega) {
+        double damped = std::sqrt(omega * omega - zeta * zeta);
+        x = std::exp(-zeta * t) *
+            (-std::cos(damped * t) + (velocity - zeta) / damped * std::sin(damped * t));
+    } else {
+        double damped = std::sqrt(zeta * zeta - omega * omega);
+        x = std::exp(-zeta * t) *
+            (-std::cosh(damped * t) + (velocity - zeta) / damped * std::sinh(damped * t));
+    }
+    return 1 + x;
+}
+
+@end
+
+#if DEBUG
+
+// The vectors shared with the Android tests: f at p = 0,25, 0,5, 0,75, computed outside this code from the formulas of
+// the curves.
+typedef struct {
+    const char *name;
+    ANNCurveType type;
+    double factor, tension, mass, damping, stiffness;
+    BOOL overdamping;
+    double velocity, duration;
+    double expected[3];
+} ANNCurveVector;
+
+static const ANNCurveVector ANNCurveVectors[] = {
+    {"linear", ANNCurveTypeLinear, 1, 1, 3, 500, 200, NO, 0, 0, {0.25, 0.5, 0.75}},
+    {"accelerate", ANNCurveTypeAccelerate, 1, 1, 3, 500, 200, NO, 0, 0, {0.0625, 0.25, 0.5625}},
+    {"accelerate 1.5", ANNCurveTypeAccelerate, 1.5, 1, 3, 500, 200, NO, 0, 0,
+     {0.015625, 0.125, 0.421875}},
+    {"decelerate", ANNCurveTypeDecelerate, 1, 1, 3, 500, 200, NO, 0, 0, {0.4375, 0.75, 0.9375}},
+    {"decelerate 2", ANNCurveTypeDecelerate, 2, 1, 3, 500, 200, NO, 0, 0,
+     {0.683594, 0.9375, 0.996094}},
+    {"accelerateDecelerate", ANNCurveTypeAccelerateDecelerate, 1, 1, 3, 500, 200, NO, 0, 0,
+     {0.0625, 0.5, 0.9375}},
+    {"decelerateAccelerate", ANNCurveTypeDecelerateAccelerate, 1, 1, 3, 500, 200, NO, 0, 0,
+     {0.4375, 0.5, 0.5625}},
+    {"fastOutSlowIn", ANNCurveTypeFastOutSlowIn, 1, 1, 3, 500, 200, NO, 0, 0,
+     {0.2366, 0.7756, 0.9594}},
+    {"overshoot", ANNCurveTypeOvershoot, 1, 1, 3, 500, 200, NO, 0, 0, {0.71875, 1, 1.03125}},
+    {"overshoot 2", ANNCurveTypeOvershoot, 1, 2, 3, 500, 200, NO, 0, 0,
+     {0.859375, 1.125, 1.078125}},
+    {"spring defaults 300 ms", ANNCurveTypeSpring, 1, 1, 3, 500, 200, NO, 0, 0.3,
+     {0.125992, 0.346297, 0.548116}},
+    {"spring 1/10/200 1 s", ANNCurveTypeSpring, 1, 1, 1, 10, 200, NO, 0, 1,
+     {1.300436, 0.912287, 1.024911}},
+    {"spring 1/40/100 overdamped 0.5 s", ANNCurveTypeSpring, 1, 1, 1, 40, 100, YES, 0, 0.5,
+     {0.230010, 0.448647, 0.605567}},
+    {"spring 0/-1/0 300 ms", ANNCurveTypeSpring, 1, 1, 0, -1, 0, NO, 0, 0.3,
+     {0.125992, 0.346297, 0.548116}},
+    {"spring velocity 5 300 ms", ANNCurveTypeSpring, 1, 1, 3, 500, 200, NO, 5, 0.3,
+     {0.329266, 0.566672, 0.727301}},
+};
+
+static void ANNExpect(const char *what, double value, double expected, double tolerance) {
+    if (!(std::fabs(value - expected) <= tolerance)) {
+        RCTLogWarn(@"[ApexNavigation] curve self-check: %s gave %.6f, expected %.6f", what, value,
+                   expected);
+    }
+}
+
+void ANNCurveSelfCheck(void) {
+    static dispatch_once_t once;
+    dispatch_once(&once, ^{
+      const double points[] = {0.25, 0.5, 0.75};
+      for (const ANNCurveVector &vector : ANNCurveVectors) {
+          ANNCurve *curve = [[ANNCurve alloc] initWithType:vector.type
+                                                    factor:vector.factor
+                                                   tension:vector.tension
+                                                      mass:vector.mass
+                                                   damping:vector.damping
+                                                 stiffness:vector.stiffness
+                                         allowsOverdamping:vector.overdamping
+                                           initialVelocity:vector.velocity
+                                                  duration:vector.duration];
+          for (int i = 0; i < 3; i++) {
+              ANNExpect(vector.name, [curve valueAt:points[i]], vector.expected[i], 1e-6);
+          }
+      }
+      // The table between its values, and against the Bézier as a sanity check only.
+      ANNExpect("fastOutSlowIn at 0.123", ANNFastOutSlowIn(0.123), 0.041440, 1e-6);
+      ANNExpect("fastOutSlowIn against the Bezier at 0.123", ANNFastOutSlowIn(0.123), 0.041397,
+                1e-4);
+      // The timeline: the delay holds `from`, the end is exactly `to`, `duration` 0 is `to` once the delay passed.
+      ANNCurve *spring = [[ANNCurve alloc] initWithType:ANNCurveTypeSpring
+                                                 factor:1
+                                                tension:1
+                                                   mass:3
+                                                damping:500
+                                              stiffness:200
+                                      allowsOverdamping:NO
+                                        initialVelocity:0
+                                               duration:0.3];
+      ANNTrack *track = [[ANNTrack alloc] initWithFrom:10
+                                                    to:20
+                                              duration:0.3
+                                                 delay:0.1
+                                                 curve:spring];
+      ANNExpect("track in its delay", [track valueAt:0.05], 10, 0);
+      ANNExpect("track at its start", [track valueAt:0.1], 10, 0);
+      ANNExpect("track in its middle", [track valueAt:0.25], 10 + 10 * 0.346297, 1e-5);
+      ANNExpect("track at its end", [track valueAt:0.4], 20, 0);
+      ANNExpect("track after its end", [track valueAt:5], 20, 0);
+      ANNTrack *instant = [[ANNTrack alloc] initWithFrom:1
+                                                      to:0
+                                                duration:0
+                                                   delay:0.2
+                                                   curve:[ANNCurve linear]];
+      ANNExpect("track of duration 0 in its delay", [instant valueAt:0.1], 1, 0);
+      ANNExpect("track of duration 0 after its delay", [instant valueAt:0.2], 0, 0);
+    });
+}
+
+#endif

package/ios/Animations/Interpolators/ANNInterpolate.h

@@ -0,0 +1,69 @@
+#import <QuartzCore/QuartzCore.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+// The interpolation of values: from + f·(to − from) per component, where f is the share of the way a track gives
+// (`ANNTrack fractionAt:`); exactly `from` at f = 0 and exactly `to` at f = 1, whatever the floating point would give.
+// iOS never interpolates colors: a shared element flies as pictures.
+
+/// A number.
+static inline CGFloat ANNInterpolateNumber(CGFloat from, CGFloat to, double f) {
+    if (f == 0) {
+        return from;
+    }
+    if (f == 1) {
+        return to;
+    }
+    return from + (CGFloat)f * (to - from);
+}
+
+/// A point: x and y apart.
+static inline CGPoint ANNInterpolatePoint(CGPoint from, CGPoint to, double f) {
+    return CGPointMake(ANNInterpolateNumber(from.x, to.x, f),
+                       ANNInterpolateNumber(from.y, to.y, f));
+}
+
+/// A size: width and height apart.
+static inline CGSize ANNInterpolateSize(CGSize from, CGSize to, double f) {
+    return CGSizeMake(ANNInterpolateNumber(from.width, to.width, f),
+                      ANNInterpolateNumber(from.height, to.height, f));
+}
+
+/// A rectangle: its origin and its size.
+static inline CGRect ANNInterpolateRect(CGRect from, CGRect to, double f) {
+    CGPoint origin = ANNInterpolatePoint(from.origin, to.origin, f);
+    CGSize size = ANNInterpolateSize(from.size, to.size, f);
+    return CGRectMake(origin.x, origin.y, size.width, size.height);
+}
+
+/// A 4×4 transform, element by element (a shared element with a `transform` style, as iOS does it now).
+static inline CATransform3D ANNInterpolateTransform(CATransform3D from, CATransform3D to,
+                                                    double f) {
+    if (f == 0) {
+        return from;
+    }
+    if (f == 1) {
+        return to;
+    }
+    CATransform3D t;
+    t.m11 = ANNInterpolateNumber(from.m11, to.m11, f);
+    t.m12 = ANNInterpolateNumber(from.m12, to.m12, f);
+    t.m13 = ANNInterpolateNumber(from.m13, to.m13, f);
+    t.m14 = ANNInterpolateNumber(from.m14, to.m14, f);
+    t.m21 = ANNInterpolateNumber(from.m21, to.m21, f);
+    t.m22 = ANNInterpolateNumber(from.m22, to.m22, f);
+    t.m23 = ANNInterpolateNumber(from.m23, to.m23, f);
+    t.m24 = ANNInterpolateNumber(from.m24, to.m24, f);
+    t.m31 = ANNInterpolateNumber(from.m31, to.m31, f);
+    t.m32 = ANNInterpolateNumber(from.m32, to.m32, f);
+    t.m33 = ANNInterpolateNumber(from.m33, to.m33, f);
+    t.m34 = ANNInterpolateNumber(from.m34, to.m34, f);
+    t.m41 = ANNInterpolateNumber(from.m41, to.m41, f);
+    t.m42 = ANNInterpolateNumber(from.m42, to.m42, f);
+    t.m43 = ANNInterpolateNumber(from.m43, to.m43, f);
+    t.m44 = ANNInterpolateNumber(from.m44, to.m44, f);
+    return t;
+}
+
+NS_ASSUME_NONNULL_END

package/ios/Animations/Interpolators/ANNTrack.h

@@ -0,0 +1,52 @@
+#import "ANNCurve.h"
+#import "Double.h"
+#import <Foundation/Foundation.h>
+
+@class ANNInterpolationOptions;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The timeline of one animated value: its own duration, delay and curve. The progress is p = (t − delay) / duration;
+/// during the delay the value holds `from`, from the end on it holds exactly `to`, and a duration of 0 is `to` once the
+/// delay passed (design 19). Times in seconds from the start of the transition. Pure, immutable.
+@interface ANNTrack : NSObject
+
+- (instancetype)initWithFrom:(double)from
+                          to:(double)to
+                    duration:(NSTimeInterval)duration
+                       delay:(NSTimeInterval)delay
+                       curve:(ANNCurve *)curve NS_DESIGNATED_INITIALIZER;
+
+/// A track of the timing options of the core (`duration`, `startDelay` in milliseconds; 300 and 0 when unset) between
+/// `from` and `to`.
++ (instancetype)trackFrom:(double)from
+                       to:(double)to
+           durationMillis:(nullable Double *)duration
+              delayMillis:(nullable Double *)delay
+            interpolation:(nullable ANNInterpolationOptions *)interpolation;
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+@property(nonatomic, readonly) double from;
+@property(nonatomic, readonly) double to;
+@property(nonatomic, readonly) NSTimeInterval duration;
+@property(nonatomic, readonly) NSTimeInterval delay;
+
+/// The time the track holds its end from: delay + duration.
+@property(nonatomic, readonly) NSTimeInterval endTime;
+
+/// The share of the way at `time`: exactly 0 before and at the start, exactly 1 from the end on, the curve between.
+- (double)fractionAt:(NSTimeInterval)time;
+
+/// The value at `time`: `from` + f(p)·(`to` − `from`), exactly `from` before the start and exactly `to` from the end
+/// on.
+- (double)valueAt:(NSTimeInterval)time;
+
+@end
+
+/// A duration or a delay of the options in seconds: milliseconds, `fallback` when unset (the reader keeps only finite
+/// values not below 0).
+FOUNDATION_EXPORT NSTimeInterval ANNSecondsOf(Double *_Nullable millis, NSTimeInterval fallback);
+
+NS_ASSUME_NONNULL_END

package/ios/Animations/Interpolators/ANNTrack.mm

@@ -0,0 +1,77 @@
+#import "ANNTrack.h"
+#import "ANNAnimationRules.h"
+#import "ANNInterpolationOptions.h"
+
+NSTimeInterval ANNSecondsOf(Double *millis, NSTimeInterval fallback) {
+    if (!millis.hasValue) {
+        return fallback;
+    }
+    double value = [millis get];
+    return value >= 0 && isfinite(value) ? value / 1000.0 : fallback;
+}
+
+@implementation ANNTrack {
+    ANNCurve *_curve;
+}
+
+- (instancetype)initWithFrom:(double)from
+                          to:(double)to
+                    duration:(NSTimeInterval)duration
+                       delay:(NSTimeInterval)delay
+                       curve:(ANNCurve *)curve {
+    if (self = [super init]) {
+        _from = from;
+        _to = to;
+        _duration = duration > 0 ? duration : 0;
+        _delay = delay > 0 ? delay : 0;
+        _curve = curve;
+    }
+    return self;
+}
+
++ (instancetype)trackFrom:(double)from
+                       to:(double)to
+           durationMillis:(Double *)duration
+              delayMillis:(Double *)delay
+            interpolation:(ANNInterpolationOptions *)interpolation {
+    NSTimeInterval seconds = ANNSecondsOf(duration, ANNAnimationDefaultDuration);
+    return [[self alloc] initWithFrom:from
+                                   to:to
+                             duration:seconds
+                                delay:ANNSecondsOf(delay, 0)
+                                curve:[ANNCurve curveWithOptions:interpolation duration:seconds]];
+}
+
+- (NSTimeInterval)endTime {
+    return _delay + _duration;
+}
+
+- (double)fractionAt:(NSTimeInterval)time {
+    if (time < _delay) {
+        return 0;
+    }
+    if (_duration <= 0 || time >= _delay + _duration) {
+        return 1;
+    }
+    double p = (time - _delay) / _duration;
+    if (p <= 0) {
+        return 0;
+    }
+    return [_curve valueAt:p];
+}
+
+- (double)valueAt:(NSTimeInterval)time {
+    if (time < _delay) {
+        return _from;
+    }
+    if (_duration <= 0 || time >= _delay + _duration) {
+        return _to;
+    }
+    double p = (time - _delay) / _duration;
+    if (p <= 0) {
+        return _from;
+    }
+    return _from + [_curve valueAt:p] * (_to - _from);
+}
+
+@end

package/ios/Animations/Interpolators/ANNViewTracks.h

@@ -0,0 +1,57 @@
+#import "ANNFrameDriver.h"
+#import <UIKit/UIKit.h>
+
+@class ANNElementTransitionOptions;
+@class ANNViewAnimationOptions;
+
+NS_ASSUME_NONNULL_BEGIN
+
+/// The perspective of the tilts `rotationX` and `rotationY` on iOS: the distance d of m34 = −1/d, in points, that React
+/// Native's calibration gives Android's default camera (1280 / (screen scale × √5)).
+FOUNDATION_EXPORT CGFloat ANNCameraDistance(void);
+
+/// The animated properties of one view: a side of a screen, of the root or of the snapshot, an element, or the fade of
+/// a screen. The properties are independent, as on Android: the scale and the rotations go about the view's center (its
+/// anchor), the tilts with the perspective of `ANNCameraDistance`, and the translation (`translationX/Y`, or `x − x₀`,
+/// `y − y₀`) comes last, neither scaled nor rotated. One order on both platforms (React Native's): scale, `rotationX`,
+/// `rotationY`, `rotation` (clockwise, degrees), the perspective, the translation.
+///
+/// A missing end is the view's value when the tracks are made: `x`, `y` its place in its parent (from its layer's
+/// position and bounds, never its frame), the translations 0, `alpha` its alpha before any hide, the scales 1, the
+/// rotations 0. Each frame writes only what plays: `alpha` only with an `alpha` track, `layer.transform` only when a
+/// property of the transform plays; with `translationX` and `x` on one side the translation wins. The frame is never
+/// changed (React keeps the layout). `restore` puts back the alpha and the transform as they were read.
+@interface ANNViewTracks : NSObject <ANNFrameClient>
+
+/// The playing properties of `side` on `view`. `alphaBefore`: the view's alpha before the core hid it for the
+/// transition (the arriving screen), else its alpha now; it is also what `restore` puts back.
+- (instancetype)initWithView:(UIView *)view
+                        side:(ANNViewAnimationOptions *)side
+                 alphaBefore:(CGFloat)alphaBefore;
+
+/// The playing properties of an element (`elementTransitions[]`): appearing from `from` to the view's value,
+/// disappearing from it to `to`, or both ends given.
+- (instancetype)initWithView:(UIView *)view element:(ANNElementTransitionOptions *)element;
+
+/// A linear fade of `view`'s alpha (a dismissed popover with nothing to play); `restore` puts back `alphaBefore`.
+- (instancetype)initWithView:(UIView *)view
+                    fadeFrom:(CGFloat)from
+                          to:(CGFloat)to
+                    duration:(NSTimeInterval)duration
+                 alphaBefore:(CGFloat)alphaBefore;
+
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+@property(nonatomic, readonly) UIView *view;
+
+/// At least one property plays.
+@property(nonatomic, readonly) BOOL hasTracks;
+
+/// An `alpha` track plays: without one the view keeps the alpha it has (the arriving screen gets its own back at the
+/// start).
+@property(nonatomic, readonly) BOOL animatesAlpha;
+
+@end
+
+NS_ASSUME_NONNULL_END