@imgly/editor-react-native 1.72.3 → 1.73.1

package/ios/Extensions/OnCreate+.swift

@@ -2,70 +2,46 @@ import Foundation
 import IMGLYEditor
 import IMGLYEngine
 
-/// An extension that provides convenience methods for `OnCreate` calls.
-extension OnCreate {
-  /// Populates the editor based on a given `config`, `sourceType` and `defaultScene`.
-  /// - Parameters:
-  ///   - settings: The `EditorSettings` containing the relevant editor information.
-  ///   - sourceType: The `EditorSourceType` defining of which type the source is.
-  ///   - defaultSource: The `URL` of the defaultScene if no `EditorSettings.source` is specified.
-  /// - Returns: An `OnCreate.Callback`.
-  @MainActor
-  public static func load(
-    _ settings: EditorSettings?,
-    _ sourceType: EditorSourceType = .scene,
-    defaultSource: URL? = nil,
-  ) -> OnCreate.Callback {
-    { engine in
-      var url: URL?
-
-      if let source = settings?.source?.source {
-        if let sourceUrl = URL(string: source), sourceUrl.scheme != nil {
-          url = sourceUrl
-        } else {
-          throw "Specified URL is not valid."
-        }
-      } else if let defaultSource {
-        url = defaultSource
-      }
-
-      if let url {
-        switch settings?.source?.type ?? sourceType {
-        case .image:
-          try await engine.scene.create(fromImage: url)
-        case .video:
-          try await engine.scene.create(fromVideo: url)
-        default:
-          try await engine.scene.load(from: url)
-        }
-      } else {
-        try await OnCreate.default(engine)
-      }
+// MARK: - React Native Source Loading
 
-      var baseURL: URL?
-      if let baseUri = settings?.baseUri {
-        if let temp = URL(string: baseUri), temp.scheme != nil {
-          baseURL = temp
-        }
-      }
-      try await Self.loadDefaultAssets(baseURL: baseURL)(engine)
+public extension OnCreate {
+  /// Loads a source from React Native editor settings.
+  ///
+  /// This helper is designed to be used as the `createScene` parameter of starter kit
+  /// `defaultOnCreate` callbacks. It resolves the source URL from settings and loads it
+  /// based on the specified source type.
+  ///
+  /// ## Example
+  /// ```swift
+  /// builder.onCreate { engine, _ in
+  ///   if let createScene = try OnCreate.loadFromSettings(settings) {
+  ///     try await DesignEditorConfiguration.defaultOnCreate(createScene: createScene)(engine)
+  ///   } else {
+  ///     try await DesignEditorConfiguration.defaultOnCreate()(engine)
+  ///   }
+  /// }
+  /// ```
+  ///
+  /// - Parameter settings: The `EditorSettings` containing the source configuration from React Native.
+  /// - Returns: An `OnCreate.Callback` that loads the source, or `nil` if no source is specified
+  ///   (allowing the starter kit's default scene to be used instead).
+  /// - Throws: If a source is specified but its URL is invalid.
+  static func loadFromSettings(
+    _ settings: EditorSettings?,
+  ) throws -> Callback? {
+    guard let source = settings?.source else { return nil }
+    guard let url = source.url else {
+      throw "Specified URL is not valid: \(source.source)"
     }
-  }
-
-  /// Loads the default assets for the asset library.
-  /// - Parameter baseURL: The base `URL` from your CDN where the assets are hosted.
-  /// - Returns: A `Callback`.
-  static func loadDefaultAssets(baseURL: URL?) -> Callback {
-    { engine in
-      let baseURI = baseURL ?? Engine.assetBaseURL
-      try await engine.addDefaultAssetSources(baseURL: baseURI)
-      try await engine.addDemoAssetSources(
-        baseURL: baseURI,
-        sceneMode: engine.scene.getMode(),
-        withUploadAssetSources: true,
-      )
-      try await engine.asset.addSource(TextAssetSource(engine: engine))
-      try engine.asset.addSource(PhotoRollAssetSource(engine: engine))
+    return { engine in
+      switch source.type {
+      case .image:
+        try await engine.scene.create(fromImage: url)
+      case .video:
+        try await engine.scene.create(fromVideo: url)
+      case .scene:
+        try await engine.scene.load(from: url)
+      }
     }
   }
 }

package/ios/IMGLYEditorModule.swift

@@ -1,6 +1,7 @@
 import UIKit
 
 /// The iOS implementation for the `@imgly/editor-react-native` React Native module.
+@MainActor
 @objc(IMGLYEditorModuleSwiftAdapter) @objcMembers public class IMGLYEditorModuleSwiftAdapter: NSObject {
   // MARK: - Typealias
 
@@ -81,7 +82,15 @@ import UIKit
       .first as? UIWindowScene {
       if let rootViewController = windowScene.windows
         .filter(\.isKeyWindow).first?.rootViewController {
-        rootViewController.present(presentationController, animated: true, completion: nil)
+        // Walk up the presentation chain to the topmost view controller.
+        // Presenting on a VC that is already presenting another VC silently
+        // no-ops in UIKit, which leaves the SDK Promise hanging forever when
+        // the host app uses react-native-screens / Expo Router / RN <Modal>.
+        var topViewController: UIViewController = rootViewController
+        while let presented = topViewController.presentedViewController {
+          topViewController = presented
+        }
+        topViewController.present(presentationController, animated: true, completion: nil)
       }
     }
   }

package/ios/Model/EditorBuilder.swift

@@ -1,8 +1,5 @@
-import IMGLYApparelEditor
-import IMGLYDesignEditor
-import IMGLYPhotoEditor
-import IMGLYPostcardEditor
-import IMGLYVideoEditor
+import IMGLYEditor
+import IMGLYEngine
 import SwiftUI
 import UIKit
 
@@ -18,60 +15,156 @@ public enum EditorBuilder {
   ///   - metadata: The metadata.
   ///   - result: The `EditorBuilderResult` used to return a result.
   /// - Returns: A `UIViewController`.
-  public typealias Builder = (
+  public typealias Builder = @MainActor (
     _ settings: EditorSettings,
     _ preset: EditorPreset?,
     _ metadata: [String: Any]?,
     _ result: @escaping EditorBuilderResult
   ) -> UIViewController
 
-  /// The default apparel editor.
-  public static func apparel() -> Builder {
-    { config, _, _, result in
-      @ViewBuilder func apparelEditor(settings _: EditorSettings, result: @escaping EditorBuilderResult) -> some View {
-        ModalApparelEditor(settings: config, result: result)
-      }
-      return UIHostingController(rootView: apparelEditor(settings: config, result: result))
-    }
-  }
-
-  /// The default postcard editor.
-  public static func postcard() -> Builder {
-    { config, _, _, result in
-      @ViewBuilder func postcardEditor(settings _: EditorSettings, result: @escaping EditorBuilderResult) -> some View {
-        ModalPostcardEditor(settings: config, result: result)
-      }
-      return UIHostingController(rootView: postcardEditor(settings: config, result: result))
-    }
-  }
-
   /// The default design editor.
   public static func design() -> Builder {
     { settings, _, _, result in
-      @ViewBuilder func designEditor(settings: EditorSettings, result: @escaping EditorBuilderResult) -> some View {
-        ModalDesignEditor(settings: settings, result: result)
-      }
-      return UIHostingController(rootView: designEditor(settings: settings, result: result))
+      UIHostingController(rootView: NavigationView {
+        Editor(engineSettings(for: settings))
+          .imgly.configuration {
+            DesignEditorConfiguration { builder in
+              builder.onCreate { engine, _ in
+                if let createScene = try OnCreate.loadFromSettings(settings) {
+                  try await DesignEditorConfiguration.defaultOnCreate(createScene: createScene)(engine)
+                } else {
+                  try await DesignEditorConfiguration.defaultOnCreate()(engine)
+                }
+              }
+              builder.onExport { engine, _, _ in
+                do {
+                  let editorResult = try await OnExport.export(engine, .pdf)
+                  result(.success(editorResult))
+                } catch {
+                  result(.failure(error))
+                }
+              }
+            }
+            ModalEditorConfiguration(result: result)
+          }
+      }.navigationViewStyle(.stack))
     }
   }
 
   /// The default photo editor.
   public static func photo() -> Builder {
     { settings, _, _, result in
-      @ViewBuilder func photoEditor(settings: EditorSettings, result: @escaping EditorBuilderResult) -> some View {
-        ModalPhotoEditor(settings: settings, result: result)
-      }
-      return UIHostingController(rootView: photoEditor(settings: settings, result: result))
+      UIHostingController(rootView: NavigationView {
+        Editor(engineSettings(for: settings))
+          .imgly.configuration {
+            PhotoEditorConfiguration { builder in
+              builder.onCreate { engine, _ in
+                if let createScene = try OnCreate.loadFromSettings(settings) {
+                  try await PhotoEditorConfiguration.defaultOnCreate(createScene: createScene)(engine)
+                } else {
+                  try await PhotoEditorConfiguration.defaultOnCreate()(engine)
+                }
+              }
+              builder.onExport { engine, _, _ in
+                do {
+                  let editorResult = try await OnExport.export(engine, .png)
+                  result(.success(editorResult))
+                } catch {
+                  result(.failure(error))
+                }
+              }
+            }
+            ModalEditorConfiguration(result: result)
+          }
+      }.navigationViewStyle(.stack))
     }
   }
 
   /// The default video editor.
   public static func video() -> Builder {
     { settings, _, _, result in
-      @ViewBuilder func videoEditor(settings: EditorSettings, result: @escaping EditorBuilderResult) -> some View {
-        ModalVideoEditor(settings: settings, result: result)
-      }
-      return UIHostingController(rootView: videoEditor(settings: settings, result: result))
+      UIHostingController(rootView: NavigationView {
+        Editor(engineSettings(for: settings))
+          .imgly.configuration {
+            VideoEditorConfiguration { builder in
+              builder.onCreate { engine, _ in
+                if let createScene = try OnCreate.loadFromSettings(settings) {
+                  try await VideoEditorConfiguration.defaultOnCreate(createScene: createScene)(engine)
+                } else {
+                  try await VideoEditorConfiguration.defaultOnCreate()(engine)
+                }
+              }
+              builder.onExport { engine, eventHandler, _ in
+                do {
+                  let editorResult = try await OnExport.exportVideo(engine, eventHandler, .mp4)
+                  result(.success(editorResult))
+                } catch {
+                  if error is CancellationError { return }
+                  result(.failure(error))
+                }
+              }
+            }
+            ModalEditorConfiguration(result: result)
+          }
+      }.navigationViewStyle(.stack))
+    }
+  }
+
+  /// The default apparel editor.
+  public static func apparel() -> Builder {
+    { settings, _, _, result in
+      UIHostingController(rootView: NavigationView {
+        Editor(engineSettings(for: settings))
+          .imgly.configuration {
+            ApparelEditorConfiguration { builder in
+              builder.onCreate { engine, _ in
+                if let createScene = try OnCreate.loadFromSettings(settings) {
+                  try await ApparelEditorConfiguration.defaultOnCreate(createScene: createScene)(engine)
+                } else {
+                  try await ApparelEditorConfiguration.defaultOnCreate()(engine)
+                }
+              }
+              builder.onExport { engine, _, _ in
+                do {
+                  let editorResult = try await OnExport.export(engine, .pdf)
+                  result(.success(editorResult))
+                } catch {
+                  result(.failure(error))
+                }
+              }
+            }
+            ModalEditorConfiguration(result: result)
+          }
+      }.navigationViewStyle(.stack))
+    }
+  }
+
+  /// The default postcard editor.
+  public static func postcard() -> Builder {
+    { settings, _, _, result in
+      UIHostingController(rootView: NavigationView {
+        Editor(engineSettings(for: settings))
+          .imgly.configuration {
+            PostcardEditorConfiguration { builder in
+              builder.onCreate { engine, _ in
+                if let createScene = try OnCreate.loadFromSettings(settings) {
+                  try await PostcardEditorConfiguration.defaultOnCreate(createScene: createScene)(engine)
+                } else {
+                  try await PostcardEditorConfiguration.defaultOnCreate()(engine)
+                }
+              }
+              builder.onExport { engine, _, _ in
+                do {
+                  let editorResult = try await OnExport.export(engine, .pdf)
+                  result(.success(editorResult))
+                } catch {
+                  result(.failure(error))
+                }
+              }
+            }
+            ModalEditorConfiguration(result: result)
+          }
+      }.navigationViewStyle(.stack))
     }
   }
 
@@ -91,14 +184,9 @@ public enum EditorBuilder {
   }
 }
 
-// MARK: - Custom
+// MARK: - Helpers
 
-/// An extension for the editor views.
 extension EditorBuilder {
-  /// The message to send if the native error has been dismissed after throwing an error.
-  private static let exportFailedMessage =
-    "Failed to initialize the editor. Please verify that the loaded license is correct."
-
   /// Generates `EngineSettings` based on an `EditorSettings`.
   /// - Parameter settings: The `EditorSettings`.
   /// - Returns: The derived `EngineSettings`.
@@ -109,185 +197,4 @@ extension EditorBuilder {
       EngineSettings(license: settings.license, userID: settings.userId)
     }
   }
-
-  /// A modal apparel editor handling native errors.
-  private struct ModalApparelEditor: View {
-    @Environment(\.dismiss) private var dismiss
-    private let settings: EditorSettings
-    private let result: EditorBuilderResult
-
-    init(settings: EditorSettings, result: @escaping EditorBuilderResult) {
-      self.settings = settings
-      self.result = result
-    }
-
-    var body: some View {
-      ModalEditor {
-        ApparelEditor(engineSettings(for: settings))
-          .imgly.onCreate { engine in
-            try await OnCreate.load(settings, defaultSource: ApparelEditor.defaultScene)(engine)
-          }
-          .imgly.onExport { engine, _ in
-            do {
-              let editorResult = try await OnExport.export(engine, .pdf)
-              result(.success(editorResult))
-            } catch {
-              result(.failure(error))
-            }
-          }
-      } onDismiss: { cancelled in
-        if cancelled {
-          result(.success(nil))
-          dismiss()
-        } else {
-          result(.failure(exportFailedMessage))
-        }
-      }
-    }
-  }
-
-  /// A modal postcard editor handling native errors.
-  private struct ModalPostcardEditor: View {
-    @Environment(\.dismiss) private var dismiss
-    private let settings: EditorSettings
-    private let result: EditorBuilderResult
-
-    init(settings: EditorSettings, result: @escaping EditorBuilderResult) {
-      self.settings = settings
-      self.result = result
-    }
-
-    var body: some View {
-      ModalEditor {
-        PostcardEditor(engineSettings(for: settings))
-          .imgly.onCreate { engine in
-            try await OnCreate.load(settings, defaultSource: PostcardEditor.defaultScene)(engine)
-          }
-          .imgly.onExport { engine, _ in
-            do {
-              let editorResult = try await OnExport.export(engine, .pdf)
-              result(.success(editorResult))
-            } catch {
-              result(.failure(error))
-            }
-          }
-      } onDismiss: { cancelled in
-        if cancelled {
-          result(.success(nil))
-          dismiss()
-        } else {
-          result(.failure(exportFailedMessage))
-        }
-      }
-    }
-  }
-
-  /// A modal design editor handling native errors.
-  private struct ModalDesignEditor: View {
-    @Environment(\.dismiss) private var dismiss
-    private let settings: EditorSettings
-    private let result: EditorBuilderResult
-
-    init(settings: EditorSettings, result: @escaping EditorBuilderResult) {
-      self.settings = settings
-      self.result = result
-    }
-
-    var body: some View {
-      ModalEditor {
-        DesignEditor(engineSettings(for: settings))
-          .imgly.onCreate { engine in
-            try await OnCreate.load(settings, defaultSource: DesignEditor.defaultScene)(engine)
-          }
-          .imgly.onExport { engine, _ in
-            do {
-              let editorResult = try await OnExport.export(engine, .pdf)
-              result(.success(editorResult))
-            } catch {
-              result(.failure(error))
-            }
-          }
-      } onDismiss: { cancelled in
-        if cancelled {
-          result(.success(nil))
-          dismiss()
-        } else {
-          result(.failure(exportFailedMessage))
-        }
-      }
-    }
-  }
-
-  /// A modal photo editor handling native errors.
-  private struct ModalPhotoEditor: View {
-    @Environment(\.dismiss) private var dismiss
-    private let settings: EditorSettings
-    private let result: EditorBuilderResult
-
-    init(settings: EditorSettings, result: @escaping EditorBuilderResult) {
-      self.settings = settings
-      self.result = result
-    }
-
-    var body: some View {
-      ModalEditor {
-        PhotoEditor(engineSettings(for: settings))
-          .imgly.onCreate { engine in
-            try await OnCreate
-              .load(settings, settings.source?.type ?? .image, defaultSource: PhotoEditor.defaultImage)(engine)
-          }
-          .imgly.onExport { engine, _ in
-            do {
-              let editorResult = try await OnExport.export(engine, .png)
-              result(.success(editorResult))
-            } catch {
-              result(.failure(error))
-            }
-          }
-      } onDismiss: { cancelled in
-        if cancelled {
-          result(.success(nil))
-          dismiss()
-        } else {
-          result(.failure(exportFailedMessage))
-        }
-      }
-    }
-  }
-
-  /// A modal video editor handling native errors.
-  private struct ModalVideoEditor: View {
-    @Environment(\.dismiss) private var dismiss
-    private let settings: EditorSettings
-    private let result: EditorBuilderResult
-
-    init(settings: EditorSettings, result: @escaping EditorBuilderResult) {
-      self.settings = settings
-      self.result = result
-    }
-
-    var body: some View {
-      ModalEditor {
-        VideoEditor(engineSettings(for: settings))
-          .imgly.onCreate { engine in
-            try await OnCreate.load(settings, defaultSource: VideoEditor.defaultScene)(engine)
-          }
-          .imgly.onExport { engine, eventHandler in
-            do {
-              let editorResult = try await OnExport.exportVideo(engine, eventHandler, .mp4)
-              result(.success(editorResult))
-            } catch {
-              result(.failure(error))
-            }
-          }
-      } onDismiss: { cancelled in
-        if cancelled {
-          result(.success(nil))
-          dismiss()
-        } else {
-          result(.failure(exportFailedMessage))
-        }
-      }
-    }
-  }
 }

package/ios/Model/ModalEditorConfiguration.swift

@@ -0,0 +1,40 @@
+import IMGLYEditor
+import SwiftUI
+
+/// An editor configuration that handles modal dismiss behavior for React Native.
+public final class ModalEditorConfiguration: EditorConfiguration {
+  private let result: EditorBuilder.EditorBuilderResult
+
+  /// Creates a modal editor configuration.
+  /// - Parameters:
+  ///   - result: The closure used to return a result to React Native.
+  ///   - customize: An optional closure to further customize the configuration.
+  public init(
+    result: @escaping EditorBuilder.EditorBuilderResult,
+    customize: (_ builder: Builder) -> Void = { _ in },
+  ) {
+    self.result = result
+    super.init(customize)
+  }
+
+  override public var navigationBar: NavigationBar.Configuration? {
+    NavigationBar.Configuration { navBuilder in
+      navBuilder.modify { [result] _, items in
+        items.replace(id: NavigationBar.Buttons.ID.closeEditor) {
+          NavigationBar.Buttons.closeEditor(
+            action: { _ in result(.success(nil)) },
+            label: { _ in SwiftUI.Label("Home", systemImage: "house") },
+          )
+        }
+      }
+    }
+  }
+
+  override public var onError: OnError.Handler? {
+    { [result] error, eventHandler, _ in
+      eventHandler.send(.showErrorAlert(error) {
+        result(.failure("Failed to initialize the editor. Please verify that the loaded license is correct."))
+      })
+    }
+  }
+}

package/ios/Model/Source.swift

@@ -5,4 +5,12 @@ public struct Source: Codable {
 
   /// The source type.
   public var type: EditorSourceType
+
+  /// The resolved source URL, or `nil` if the source string is not a valid URL with a scheme.
+  public var url: URL? {
+    guard let url = URL(string: source), url.scheme != nil else {
+      return nil
+    }
+    return url
+  }
 }

package/ios/StarterKits/Apparel/ApparelEditorConfiguration.swift

@@ -0,0 +1,46 @@
+import CoreGraphics
+import IMGLYEditor
+import IMGLYEngine
+import SwiftUI
+
+// CE.SDK Starter Kit: Apparel Editor
+//
+// This starter kit provides a complete, production-ready Apparel Editor configuration
+// with all configuration code inline and fully documented. Copy this file into your
+// project and customize it to match your needs.
+
+// MARK: - Configuration
+
+public final class ApparelEditorConfiguration: EditorConfiguration {
+  // MARK: - EditorConfiguration — Settings
+
+  /// The zoom padding for the canvas.
+  override public var zoomPadding: CGFloat? { 16 }
+
+  // MARK: - EditorConfiguration — Callbacks
+
+  /// The `onCreate` handler.
+  override public var onCreate: OnCreate.Handler? { Self.defaultOnCreateHandler }
+
+  /// The `onChanged` handler.
+  override public var onChanged: OnChanged.Handler? { Self.defaultOnChangedHandler }
+
+  /// The export handler.
+  ///
+  /// Default: Exports the scene as PDF and opens the system share sheet.
+  override public var onExport: OnExport.Handler? { Self.defaultOnExportHandler }
+
+  // MARK: - EditorConfiguration — UI Components
+
+  /// The navigation bar configuration.
+  override public var navigationBar: NavigationBar.Configuration? { Self.defaultNavigationBar }
+
+  /// The dock configuration.
+  override public var dock: Dock.Configuration? { Self.defaultDock }
+
+  /// The inspector bar configuration.
+  override public var inspectorBar: InspectorBar.Configuration? { Self.defaultInspectorBar }
+
+  /// The canvas menu configuration.
+  override public var canvasMenu: CanvasMenu.Configuration? { Self.defaultCanvasMenu }
+}

package/ios/StarterKits/Apparel/ApparelEditorStarterKit.swift

@@ -0,0 +1,30 @@
+import IMGLYEditor
+import IMGLYEngine
+import SwiftUI
+
+// MARK: - Starter Kit View
+
+struct ApparelEditorStarterKit: View {
+  // Provide `EngineSettings` with your license and an optional userId.
+  let settings = EngineSettings(
+    license: secrets.licenseKey, // Use nil for evaluation mode with watermark
+    userID: "<your unique user id>",
+  )
+
+  // highlight-starter-kit-view
+  var body: some View {
+    // highlight-starter-kit-composable
+    Editor(settings)
+      .imgly.configuration {
+        ApparelEditorConfiguration()
+      }
+    // highlight-starter-kit-composable
+  }
+  // highlight-starter-kit-view
+}
+
+// MARK: - Preview
+
+#Preview {
+  ApparelEditorStarterKit()
+}