@apexnative/navigation 1.0.0-alpha.1 → 1.0.0-alpha.2

package/cli/setup/steps/sceneDelegate.js

@@ -0,0 +1,108 @@
+// @ts-check
+'use strict';
+
+/** @typedef {import('./types').StepResult} StepResult */
+
+const HOW_TO = `Let ANNSceneDelegate take the app's scene: it moves the navigation's window into the scene and passes the
+scene's links to the app delegate. React Native starts in ANNAppDelegate, not here.
+
+  import ApexNavigation
+  import UIKit
+
+  class SceneDelegate: ANNSceneDelegate {}
+
+A scene delegate of the app's own calls ApexNavigation.attach(to:) in scene(_:willConnectTo:options:) instead, as the
+deep links guide shows.`;
+
+const SET_UP = `import ApexNavigation
+import UIKit
+
+/// ANNSceneDelegate moves the navigation's window into the app's scene and passes the scene's links to the app delegate.
+class SceneDelegate: ANNSceneDelegate {}
+`;
+
+// React Native 0.88's template, without its spaces: the scene delegate that makes React Native's factory and starts
+// it in the scene's window.
+const TEMPLATE = `import React
+import React_RCTAppDelegate
+import ReactAppDependencyProvider
+import UIKit
+
+class SceneDelegate: RCTDefaultReactNativeFactoryDelegate, UIWindowSceneDelegate {
+  var window: UIWindow?
+  var reactNativeFactory: RCTReactNativeFactory?
+
+  func scene(
+    _ scene: UIScene,
+    willConnectTo session: UISceneSession,
+    options connectionOptions: UIScene.ConnectionOptions
+  ) {
+    guard let windowScene = scene as? UIWindowScene else {
+      return
+    }
+
+    dependencyProvider = RCTAppDependencyProvider()
+    reactNativeFactory = RCTReactNativeFactory(delegate: self)
+    window = UIWindow(windowScene: windowScene)
+
+    #if DEBUG
+    let devMenuConfiguration = RCTDevMenuConfiguration(
+      devMenuEnabled: true,
+      shakeGestureEnabled: true,
+      keyboardShortcutsEnabled: true
+    )
+    reactNativeFactory?.devMenuConfiguration = devMenuConfiguration
+    #endif
+
+    reactNativeFactory?.startReactNative(
+      withModuleName: "",
+      in: window,
+      connectionOptions: connectionOptions
+    )
+  }
+
+  func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
+    RCTLinkingManager.scene(scene, openURLContexts: URLContexts)
+  }
+
+  func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
+    RCTLinkingManager.scene(scene, continue: userActivity)
+  }
+
+  override func bundleURL() -> URL? {
+    #if DEBUG
+    RCTBundleURLProvider.sharedSettings().jsBundleURL(forBundleRoot: "index")
+    #else
+    Bundle.main.url(forResource: "main", withExtension: "jsbundle")
+    #endif
+  }
+}
+`;
+
+/**
+ * The text without its spaces and the app's name, to compare with the template.
+ * @param {string} text
+ */
+function shape(text) {
+  return text.replace(/withModuleName:\s*"[^"]*"/, 'withModuleName:""').replace(/\s+/g, '');
+}
+
+/**
+ * SceneDelegate.swift of React Native 0.88 and newer: the scene delegate becomes an ANNSceneDelegate, since
+ * ANNAppDelegate starts React Native and owns the window. Only the template's file changes; one with code of the app's
+ * own is changed by hand.
+ * @param {string} text
+ * @returns {StepResult}
+ */
+function planSceneDelegate(text) {
+  if (
+    /class\s+\w+\s*:\s*ANNSceneDelegate\b/.test(text) ||
+    /\bApexNavigation\.attach\s*\(/.test(text)
+  )
+    return { status: 'done', note: 'already set up' };
+  if (shape(text) !== shape(TEMPLATE))
+    return { status: 'manual', note: 'changed by hand, see below', howTo: HOW_TO };
+  return { status: 'change', next: SET_UP, note: 'ANNSceneDelegate' };
+}
+
+module.exports = { planSceneDelegate };

package/docs-md/architecture/transitions.md

@@ -78,7 +78,7 @@ navigation.push('Person', {
 });
 ```
 
-The avatar of the row moves and grows into the photo of the profile, and the name into its larger title. The views can differ in size and style. `type` and `duration` next to `shared` change how the rest of the screen comes, `'fade'` by default.
+The avatar of the row moves and grows into the photo of the profile, and the name into its larger title. The views can differ in size and style. A pair that isn't found is skipped (the transition waits for it first); one that fails on the way is skipped with a warning in the log. Either way its views show with their screens, and the other pairs move. `type` and `duration` next to `shared` change how the rest of the screen comes, `'fade'` by default.
 
 Both platforms. (Android) The next screen waits until it is drawn, so its views are there to move into; a `type` other than a fade gives way to a fade.
 

package/docs-md/guides/deep-links.md

@@ -522,57 +522,39 @@ The launch link is read once per launch of the app, and the cases differ:
 
 ## An app with its own scene delegate
 
-(iOS) `ANNAppDelegate` gives the app's scene `ANNSceneDelegate`, which moves the navigation's window into the scene and passes the scene's links on. An app whose `Info.plist` names a scene delegate of its own does both itself. The links that launched the app come with the options of `scene(_:willConnectTo:options:)`, and they count as the launch link when they're passed on in that same call, with the window moved into the scene:
+(iOS) `ANNAppDelegate` gives the app's scene `ANNSceneDelegate`, which moves the navigation's window into the scene and passes the scene's links on: to the app delegate's methods, then to `Linking`. An app whose `Info.plist` names a scene delegate of its own, as React Native 0.88's template does, extends `ANNSceneDelegate`; a method it overrides calls `super`:
 
 ```swift
 import ApexNavigation
 import UIKit
 
-class SceneDelegate: UIResponder, UIWindowSceneDelegate {
-  var window: UIWindow?
-
-  func scene(
+class SceneDelegate: ANNSceneDelegate {
+  override func scene(
     _ scene: UIScene,
     willConnectTo session: UISceneSession,
     options connectionOptions: UIScene.ConnectionOptions
   ) {
-    guard let windowScene = scene as? UIWindowScene else { return }
-    window = ApexNavigation.attach(to: windowScene)
-    // The links that launched the app: passed on in this same
-    // call, so the first root can come from one of them.
-    for context in connectionOptions.urlContexts {
-      openLink(context.url)
-    }
-    for activity in connectionOptions.userActivities {
-      if let url = activity.webpageURL { openLink(url) }
-    }
+    // Moves the window into the scene and passes on the links
+    // that launched the app.
+    super.scene(scene, willConnectTo: session, options: connectionOptions)
+    window?.tintColor = .systemIndigo
   }
 
-  // Links while the app runs.
-  func scene(
+  override func scene(
     _ scene: UIScene,
     openURLContexts URLContexts: Set<UIOpenURLContext>
   ) {
-    for context in URLContexts {
-      openLink(context.url)
-    }
-  }
-
-  func scene(
-    _ scene: UIScene,
-    continue userActivity: NSUserActivity
-  ) {
-    if let url = userActivity.webpageURL { openLink(url) }
-  }
-
-  private func openLink(_ url: URL) {
-    let app = UIApplication.shared.delegate as? ANNAppDelegate
-    app?.dispatchDeepLinkURL(url)
+    print("Opened:", URLContexts.map(\.url))
+    super.scene(scene, openURLContexts: URLContexts)
   }
 }
 ```
 
-`ApexNavigation.attach(to:)` is `attachToWindowScene:` in Objective-C.
+`super` passes each link on with its scene: React Native 0.88 and newer take a scene's links only with it. `setup` turns the scene delegate of React Native 0.88's template into `class SceneDelegate: ANNSceneDelegate {}`.
+
+A scene delegate that extends another class calls `ApexNavigation.attach(to:)` (`attachToWindowScene:` in Objective-C) in `scene(_:willConnectTo:options:)` and passes the URLs to `dispatchDeepLinkURL(_:)` of the app delegate.
+
+A link the app dispatches itself with `dispatchDeepLinkURL(_:)`, such as the link of a push notification, comes with no scene. Where React Native's `Linking` doesn't take it from the native side (React Native 0.88 and newer, in an app with a scene delegate), the navigation hands it to `Linking` from JavaScript, as a `url` event like any other.
 
 ## Testing
 

package/docs-md/start/installation.md

@@ -136,6 +136,7 @@ In an app as the React Native template makes it, the window shows **one React vi
 | File | What setup does | Why |
 | --- | --- | --- |
 | `AppDelegate.swift` | Extends `ANNAppDelegate`. | It creates the window, puts the root of the navigation in it and starts React Native. Deep links that come before JS is ready wait for it. |
+| `SceneDelegate.swift` | Extends `ANNSceneDelegate`. React Native 0.88 and newer only: the earlier templates have no scene delegate. | The template's scene delegate would start React Native a second time. `ANNSceneDelegate` moves the navigation's window into the app's scene and passes the scene's links to the app delegate. |
 | `Info.plist` | Sets `UIViewControllerBasedStatusBarAppearance` to `true`. | Each screen sets its own status bar from its options; with `false`, only the app as a whole can. |
 
 #### JavaScript files

package/ios/Animations/ANNTransitionAnimator.mm

@@ -133,19 +133,16 @@ static void ANNUpdateRootLayoutOf(UIViewController *node) {
     _began = YES;
     _wait = nil;
     UIView *container = _context.containerView;
-    UIView *leavingRoot = [ANNElementFinder searchRootOf:_plan.fromNode];
-    UIView *arrivingRoot = [ANNElementFinder searchRootOf:_plan.toNode];
+    ANNTransitionViews *views = [[ANNTransitionViews alloc] initWithPairs:_plan.sharedElements
+                                                                 elements:_plan.elements
+                                                                 fromNode:_plan.fromNode
+                                                                   toNode:_plan.toNode];
     NSMutableArray<id<ANNFrameClient>> *clients = [NSMutableArray new];
     // The shared pairs first: their geometry and pictures are taken while the screens are still at rest.
     NSArray<ANNSharedElementFlight *> *flights =
-        [ANNSharedElementFlight flightsOf:_plan.sharedElements
-                              leavingRoot:leavingRoot
-                             arrivingRoot:arrivingRoot
-                                container:container];
+        [ANNSharedElementFlight flightsOf:_plan.sharedElements views:views container:container];
     NSArray<ANNElementTransition *> *elements =
-        [ANNElementTransition transitionsOf:_plan.elements
-                                leavingRoot:leavingRoot
-                               arrivingRoot:arrivingRoot];
+        [ANNElementTransition transitionsOf:_plan.elements views:views];
     ANNViewTracks *arrivingTracks = nil;
     ANNViewTracks *leavingTracks = nil;
     if (_plan.enter && _arriving) {
@@ -200,8 +197,13 @@ static void ANNUpdateRootLayoutOf(UIViewController *node) {
     if (leavingTracks.hasTracks) {
         [clients addObject:leavingTracks];
     }
-    [clients addObjectsFromArray:elements];
-    [clients addObjectsFromArray:flights];
+    // Each element plays on its own: one whose frame fails goes back and stops, the others and the screens go on.
+    for (ANNElementTransition *element in elements) {
+        [clients addObject:[[ANNIsolatedElement alloc] initWithClient:element name:element.name]];
+    }
+    for (ANNSharedElementFlight *flight in flights) {
+        [clients addObject:[[ANNIsolatedElement alloc] initWithClient:flight name:flight.name]];
+    }
     _clients = clients;
     if ([self tilts]) {
         [self orderInDepthIn:container flights:flights];

package/ios/Animations/ANNTransitionWait.mm

@@ -48,13 +48,12 @@ static const NSTimeInterval ANNReadyCheckDelay = 0.1;
 }
 
 - (BOOL)targetsAreFound {
-    UIView *leavingRoot = [ANNElementFinder searchRootOf:_plan.fromNode];
-    UIView *arrivingRoot = [ANNElementFinder searchRootOf:_plan.toNode];
-    return [ANNSharedElementFlight allTargetsFound:_plan.sharedElements
-                                      arrivingRoot:arrivingRoot] &&
-           [ANNElementTransition allFound:_plan.elements
-                              leavingRoot:leavingRoot
-                             arrivingRoot:arrivingRoot];
+    ANNTransitionViews *views = [[ANNTransitionViews alloc] initWithPairs:_plan.sharedElements
+                                                                 elements:_plan.elements
+                                                                 fromNode:_plan.fromNode
+                                                                   toNode:_plan.toNode];
+    return [ANNSharedElementFlight allTargetsFound:_plan.sharedElements views:views] &&
+           [ANNElementTransition allFound:_plan.elements views:views];
 }
 
 - (BOOL)isReady {

package/ios/Animations/Elements/ANNElementFinder.h

@@ -1,5 +1,10 @@
+#import "ANNFrameDriver.h"
 #import <UIKit/UIKit.h>
 
+@class ANNElementTransitionOptions;
+@class ANNSharedElementTransitionOptions;
+@class Text;
+
 NS_ASSUME_NONNULL_BEGIN
 
 /// Finds the React views of the elements of a transition by their `nativeID`: depth first, the first match, in the
@@ -21,6 +26,58 @@ NS_ASSUME_NONNULL_BEGIN
 + (nullable UIView *)viewWithNativeID:(nullable NSString *)nativeID
                                inNode:(nullable UIViewController *)node;
 
+/// The views with the `nativeID`s of `nativeIDs` in `root` and its subviews, in one walk: for each id the view
+/// `viewWithNativeID:inView:` finds; an id no view has is left out. The walk stops once every id is found.
++ (NSDictionary<NSString *, UIView *> *)viewsWithNativeIDs:(NSSet<NSString *> *)nativeIDs
+                                                    inView:(nullable UIView *)root;
+
+@end
+
+/// The views of a transition's elements in its two screens: each screen is walked once, at its first lookup, for the
+/// ids looked for there — the leaving one for the pairs' `fromId`s and the elements' ids, the arriving one for the
+/// pairs' `toId`s and the elements' ids the leaving one doesn't have. A lookup finds what
+/// `+[ANNElementFinder viewWithNativeID:inView:]` finds in that screen as it was at its walk. Main queue.
+@interface ANNTransitionViews : NSObject
+
+- (instancetype)initWithPairs:(nullable NSArray<ANNSharedElementTransitionOptions *> *)pairs
+                     elements:(nullable NSArray<ANNElementTransitionOptions *> *)elements
+                     fromNode:(nullable UIViewController *)fromNode
+                       toNode:(nullable UIViewController *)toNode NS_DESIGNATED_INITIALIZER;
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/// The React views of the screens the elements are looked for in.
+@property(nonatomic, strong, readonly, nullable) UIView *leavingRoot;
+@property(nonatomic, strong, readonly, nullable) UIView *arrivingRoot;
+
+/// The view with `nativeID` in the leaving screen; nil when none has it or the id isn't one of the transition's.
+- (nullable UIView *)leavingViewWithNativeID:(nullable NSString *)nativeID;
+
+/// The view with `nativeID` in the arriving screen; nil when none has it or the id isn't one of the transition's.
+- (nullable UIView *)arrivingViewWithNativeID:(nullable NSString *)nativeID;
+
+@end
+
+/// The `nativeID` an element's option holds; nil when it holds none (not a string, an empty one).
+FOUNDATION_EXPORT NSString *_Nullable ANNNativeIDOf(Text *_Nullable value);
+
+/// The isolation of every element of the core's transitions: `work`, a step of the element named `element` (its
+/// `nativeID`, or a pair's two), runs; an exception in it skips that element only — one line in the log
+/// (`ANNElementSkipped`), and NO — while the rest of the transition plays and its command completes.
+FOUNDATION_EXPORT BOOL ANNElementStep(NSString *element, NS_NOESCAPE dispatch_block_t work);
+
+/// The line in the log for the element named `element`, skipped for `reason`: it shows and hides with its screen.
+FOUNDATION_EXPORT void ANNElementSkipped(NSString *element, NSString *reason);
+
+/// An element's frames, each in `ANNElementStep`: after a frame that fails, the element's values go back
+/// (`-restore`), and it gets no frame more.
+@interface ANNIsolatedElement : NSObject <ANNFrameClient>
+
+- (instancetype)initWithClient:(id<ANNFrameClient>)client
+                          name:(NSString *)name NS_DESIGNATED_INITIALIZER;
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Animations/Elements/ANNElementFinder.mm

@@ -1,8 +1,58 @@
 #import "ANNElementFinder.h"
 #import "ANNAppearanceDispatcher.h"
+#import "ANNElementTransitionOptions.h"
+#import "ANNSharedElementTransitionOptions.h"
+#import "Text.h"
 #import "UIViewController+LayoutProtocol.h"
+#import <React/RCTLog.h>
 #import <React/RCTViewComponentView.h>
 
+static NSString *ANNNativeIDOfView(UIView *view) {
+    return [view isKindOfClass:RCTViewComponentView.class]
+               ? ((RCTViewComponentView *)view).nativeId
+               : nil;
+}
+
+// Depth first, as the search by one id: the first view of the walk with an id keeps it. NO once every id is found.
+static BOOL ANNCollectViews(UIView *view, NSSet<NSString *> *nativeIDs,
+                            NSMutableDictionary<NSString *, UIView *> *found) {
+    NSString *nativeID = ANNNativeIDOfView(view);
+    if (nativeID && !found[nativeID] && [nativeIDs containsObject:nativeID]) {
+        found[nativeID] = view;
+        if (found.count == nativeIDs.count) {
+            return NO;
+        }
+    }
+    for (UIView *subview in view.subviews) {
+        if (!ANNCollectViews(subview, nativeIDs, found)) {
+            return NO;
+        }
+    }
+    return YES;
+}
+
+NSString *ANNNativeIDOf(Text *value) {
+    NSString *text = [value withDefault:nil];
+    return [text isKindOfClass:NSString.class] && text.length > 0 ? text : nil;
+}
+
+void ANNElementSkipped(NSString *element, NSString *reason) {
+    RCTLogWarn(@"[ApexNavigation] the transition's element %@ is skipped, it shows and hides with "
+               @"its screen while the rest plays: %@",
+               element, reason);
+}
+
+BOOL ANNElementStep(NSString *element, NS_NOESCAPE dispatch_block_t work) {
+    @try {
+        work();
+        return YES;
+    } @catch (NSException *exception) {
+        ANNElementSkipped(element, [NSString stringWithFormat:@"%@ (%@)", exception.reason ?: @"",
+                                                              exception.name]);
+        return NO;
+    }
+}
+
 @implementation ANNElementFinder
 
 + (UIView *)searchRootOf:(UIViewController *)node {
@@ -17,8 +67,7 @@
     if (nativeID.length == 0 || !root) {
         return nil;
     }
-    if ([root isKindOfClass:RCTViewComponentView.class] &&
-        [((RCTViewComponentView *)root).nativeId isEqualToString:nativeID]) {
+    if ([ANNNativeIDOfView(root) isEqualToString:nativeID]) {
         return root;
     }
     for (UIView *subview in root.subviews) {
@@ -34,4 +83,127 @@
     return [self viewWithNativeID:nativeID inView:[self searchRootOf:node]];
 }
 
++ (NSDictionary<NSString *, UIView *> *)viewsWithNativeIDs:(NSSet<NSString *> *)nativeIDs
+                                                    inView:(UIView *)root {
+    NSMutableDictionary<NSString *, UIView *> *found = [NSMutableDictionary new];
+    if (root && nativeIDs.count > 0) {
+        ANNCollectViews(root, nativeIDs, found);
+    }
+    return found;
+}
+
+@end
+
+@implementation ANNTransitionViews {
+    NSSet<NSString *> *_leavingIDs;
+    NSSet<NSString *> *_targetIDs;
+    NSSet<NSString *> *_elementIDs;
+    NSDictionary<NSString *, UIView *> *_leavingViews;
+    NSDictionary<NSString *, UIView *> *_arrivingViews;
+}
+
+- (instancetype)initWithPairs:(NSArray<ANNSharedElementTransitionOptions *> *)pairs
+                     elements:(NSArray<ANNElementTransitionOptions *> *)elements
+                     fromNode:(UIViewController *)fromNode
+                       toNode:(UIViewController *)toNode {
+    if (self = [super init]) {
+        _leavingRoot = [ANNElementFinder searchRootOf:fromNode];
+        _arrivingRoot = [ANNElementFinder searchRootOf:toNode];
+        NSMutableSet<NSString *> *sources = [NSMutableSet new];
+        NSMutableSet<NSString *> *targets = [NSMutableSet new];
+        NSMutableSet<NSString *> *identifiers = [NSMutableSet new];
+        for (ANNSharedElementTransitionOptions *pair in pairs) {
+            NSString *fromId = ANNNativeIDOf(pair.fromId);
+            NSString *toId = ANNNativeIDOf(pair.toId);
+            if (fromId) {
+                [sources addObject:fromId];
+            }
+            if (toId) {
+                [targets addObject:toId];
+            }
+        }
+        for (ANNElementTransitionOptions *element in elements) {
+            NSString *identifier = ANNNativeIDOf(element.identifier);
+            if (identifier) {
+                [identifiers addObject:identifier];
+            }
+        }
+        [sources unionSet:identifiers];
+        _leavingIDs = sources;
+        _targetIDs = targets;
+        _elementIDs = identifiers;
+    }
+    return self;
+}
+
+- (UIView *)leavingViewWithNativeID:(NSString *)nativeID {
+    if (nativeID.length == 0) {
+        return nil;
+    }
+    if (!_leavingViews) {
+        _leavingViews = [ANNElementFinder viewsWithNativeIDs:_leavingIDs inView:_leavingRoot];
+    }
+    return _leavingViews[nativeID];
+}
+
+- (UIView *)arrivingViewWithNativeID:(NSString *)nativeID {
+    if (nativeID.length == 0) {
+        return nil;
+    }
+    if (!_arrivingViews) {
+        // An element is looked for in the arriving screen only when the leaving one doesn't have it: the walk stops
+        // sooner.
+        NSMutableSet<NSString *> *ids = [_targetIDs mutableCopy];
+        for (NSString *identifier in _elementIDs) {
+            if (![self leavingViewWithNativeID:identifier]) {
+                [ids addObject:identifier];
+            }
+        }
+        _arrivingViews = [ANNElementFinder viewsWithNativeIDs:ids inView:_arrivingRoot];
+    }
+    return _arrivingViews[nativeID];
+}
+
+@end
+
+@implementation ANNIsolatedElement {
+    id<ANNFrameClient> _client;
+    NSString *_name;
+    BOOL _failed;
+}
+
+- (instancetype)initWithClient:(id<ANNFrameClient>)client name:(NSString *)name {
+    if (self = [super init]) {
+        _client = client;
+        _name = [name copy];
+    }
+    return self;
+}
+
+#pragma mark - ANNFrameClient
+
+- (void)applyAtTime:(NSTimeInterval)time {
+    if (_failed) {
+        return;
+    }
+    id<ANNFrameClient> client = _client;
+    if (!ANNElementStep(_name, ^{
+          [client applyAtTime:time];
+        })) {
+        _failed = YES;
+        [self restore];
+    }
+}
+
+- (NSTimeInterval)endTime {
+    return _client.endTime;
+}
+
+- (void)restore {
+    id<ANNFrameClient> client = _client;
+    ANNElementStep(_name, ^{
+      [client restore];
+    });
+}
+
 @end

package/ios/Animations/Elements/ANNElementTransition.h

@@ -2,6 +2,7 @@
 #import <UIKit/UIKit.h>
 
 @class ANNElementTransitionOptions;
+@class ANNTransitionViews;
 
 NS_ASSUME_NONNULL_BEGIN
 
@@ -11,20 +12,21 @@ NS_ASSUME_NONNULL_BEGIN
 @interface ANNElementTransition : NSObject <ANNFrameClient>
 
 /// The items found: each `id` first in the leaving screen's React view, then in the arriving one; an item not found or
-/// without an animating property is left out.
+/// without an animating property is left out, and so is one whose start fails (`ANNElementStep`).
 + (NSArray<ANNElementTransition *> *)
     transitionsOf:(nullable NSArray<ANNElementTransitionOptions *> *)elements
-      leavingRoot:(nullable UIView *)leavingRoot
-     arrivingRoot:(nullable UIView *)arrivingRoot;
+            views:(ANNTransitionViews *)views;
 
 /// Every item's `id` is found in one of the two screens (the wait's test).
 + (BOOL)allFound:(nullable NSArray<ANNElementTransitionOptions *> *)elements
-     leavingRoot:(nullable UIView *)leavingRoot
-    arrivingRoot:(nullable UIView *)arrivingRoot;
+           views:(ANNTransitionViews *)views;
 
 - (instancetype)init NS_UNAVAILABLE;
 + (instancetype)new NS_UNAVAILABLE;
 
+/// The item's `id`, in quotes: its name in the log.
+@property(nonatomic, copy, readonly) NSString *name;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/Animations/Elements/ANNElementTransition.mm

@@ -7,51 +7,49 @@
     ANNViewTracks *_tracks;
 }
 
-- (instancetype)initWithTracks:(ANNViewTracks *)tracks {
+- (instancetype)initWithTracks:(ANNViewTracks *)tracks name:(NSString *)name {
     if (self = [super init]) {
         _tracks = tracks;
+        _name = [name copy];
     }
     return self;
 }
 
-+ (UIView *)viewOf:(ANNElementTransitionOptions *)element
-       leavingRoot:(UIView *)leavingRoot
-      arrivingRoot:(UIView *)arrivingRoot {
-    NSString *identifier = [element.identifier withDefault:nil];
-    if (![identifier isKindOfClass:NSString.class] || identifier.length == 0) {
-        return nil;
-    }
-    return [ANNElementFinder viewWithNativeID:identifier inView:leavingRoot]
-               ?: [ANNElementFinder viewWithNativeID:identifier inView:arrivingRoot];
++ (UIView *)viewOf:(NSString *)identifier views:(ANNTransitionViews *)views {
+    return [views leavingViewWithNativeID:identifier]
+               ?: [views arrivingViewWithNativeID:identifier];
 }
 
 + (NSArray<ANNElementTransition *> *)
     transitionsOf:(NSArray<ANNElementTransitionOptions *> *)elements
-      leavingRoot:(UIView *)leavingRoot
-     arrivingRoot:(UIView *)arrivingRoot {
+            views:(ANNTransitionViews *)views {
     NSMutableArray<ANNElementTransition *> *transitions = [NSMutableArray new];
     // One view takes one item: a second item for the same view would read the values the first one writes.
     NSHashTable<UIView *> *taken = [NSHashTable weakObjectsHashTable];
     for (ANNElementTransitionOptions *element in elements) {
-        UIView *view = [self viewOf:element leavingRoot:leavingRoot arrivingRoot:arrivingRoot];
+        NSString *identifier = ANNNativeIDOf(element.identifier);
+        UIView *view = [self viewOf:identifier views:views];
         if (!view || [taken containsObject:view]) {
             continue;
         }
-        ANNViewTracks *tracks = [[ANNViewTracks alloc] initWithView:view element:element];
-        if (!tracks.hasTracks) {
+        NSString *name = [NSString stringWithFormat:@"'%@'", identifier];
+        __block ANNViewTracks *tracks = nil;
+        if (!ANNElementStep(name, ^{
+              tracks = [[ANNViewTracks alloc] initWithView:view element:element];
+            }) ||
+            !tracks.hasTracks) {
             continue;
         }
         [taken addObject:view];
-        [transitions addObject:[[ANNElementTransition alloc] initWithTracks:tracks]];
+        [transitions addObject:[[ANNElementTransition alloc] initWithTracks:tracks name:name]];
     }
     return transitions;
 }
 
 + (BOOL)allFound:(NSArray<ANNElementTransitionOptions *> *)elements
-     leavingRoot:(UIView *)leavingRoot
-    arrivingRoot:(UIView *)arrivingRoot {
+           views:(ANNTransitionViews *)views {
     for (ANNElementTransitionOptions *element in elements) {
-        if (![self viewOf:element leavingRoot:leavingRoot arrivingRoot:arrivingRoot]) {
+        if (![self viewOf:ANNNativeIDOf(element.identifier) views:views]) {
             return NO;
         }
     }