@blotch/angular-lynx-native 22.2.5 → 22.2.6

package/README.md

@@ -19,6 +19,8 @@ Both are one full-screen `LynxView` running `main.lynx.bundle`; Angular Router d
 
 Both send the same global props, which the runtime's services read: `platform`, `theme` (again whenever the phone switches between light and dark), `appLocale` (the phone's language as a BCP 47 tag), `isNotchScreen`, the safe-area insets `safeAreaTop`, `safeAreaBottom`, `safeAreaLeft` and `safeAreaRight`, `osVersion` (which Lynx leaves out of the main thread's `SystemInfo`), and the accessibility settings `reduceMotion`, `reduceTransparency` (iOS only) and `increaseContrast`, again whenever the user changes one. Android 12 and later also send `dynamicColors`, the wallpaper's Material 3 color roles in light and dark (`DynamicColors.kt`), again when the user changes their wallpaper or colors. Lynx Explorer sends `theme` and `isNotchScreen` too, but no `appLocale`, `osVersion` or accessibility settings. See [`templates/android/README.md`](templates/android/README.md) for the Android shell's details.
 
+Both register the native modules the runtime's services call, which Lynx Explorer doesn't have: `AngularLynxWebAuth` (`WebAuthModule.swift`, `WebAuthModule.kt`) opens `LynxWebAuthSession`'s sign-in page, in `ASWebAuthenticationSession` on iOS and a Custom Tab on Android, and returns the URL it redirects to. Android also has `AngularLynxShell`, for the back button.
+
 Both link Lynx's XElement library, which holds `<input>`, `<textarea>`, `<overlay>`, `<svg>`, `<blur-view>`, `<viewpager>`, `<refresh>`, the `<scroll-coordinator>` family, `<webview>` and `<video>`. Lynx's core doesn't include these, and a host that doesn't register them renders nothing for those tags (on Android, nothing after them either). XElement's AnimaX and Markdown elements are left out: the runtime doesn't support them. On iOS, `<blur-view>` is XElement's with more of UIKit in it (`App/BlurView.swift`): a `blur-material` attribute for UIKit's adaptive blur materials, which the glass components draw their design before iOS 26 on (Lynx's blur-view has only the styles from before iOS 13); Liquid Glass that materializes, dissolves and eases between effects inside a `glass-container`, where Lynx's sets its effect at once; and a `glass-effect-id` attribute that pairs two glass shapes across a change so one morphs into the other (`App/GlassTransitions.swift`).
 
 |                  | iOS                                                  | Android                                                  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blotch/angular-lynx-native",
-  "version": "22.2.5",
+  "version": "22.2.6",
   "description": "Builds AngularLynx apps into iOS and Android binaries",
   "homepage": "https://github.com/Blotch-Smart-Frames/AngularLynx#readme",
   "bugs": {

package/templates/android/README.md

@@ -34,6 +34,10 @@ Build commands and outputs (no flavors, so the names are fixed):
 
 Back is off by default, so it leaves the app like any root screen. The runtime turns it on while the Router has history by calling `NativeModules.AngularLynxShell.setBackHandlerEnabled(true)`, and off again on the first screen (`LynxBackButton` in `packages/runtime/src/lib/router/lynx-back-button.ts`, which `provideRouter()` starts; the call goes through the background thread, where `NativeModules` lives). While it's on, a back press sends the global event `angularLynxBack` instead, which the runtime turns into `Location.back()`. The app has to say beforehand because Android decides synchronously, at the start of the gesture, whether an app handles back (predictive back animates differently). Layer 6's `native/back-button.yaml` checks both ends.
 
+## Web sign-in
+
+`NativeModules.AngularLynxWebAuth.start(request, callback)` (`WebAuthModule.kt`, behind the runtime's `LynxWebAuthSession`) opens `request.url` in a Custom Tab (`androidx.browser`). The page's redirect to `request.callbackScheme` comes back as a deep link: the activity is `singleTask`, so the intent reaches the open one in `onNewIntent`, which hands the URL to the callback, and starting it closes the Custom Tab above it. That's why the scheme has to be in the app's `deepLinkSchemes`. Android says nothing when a Custom Tab is closed, so the activity resuming with a session still open, after having gone behind the tab, means the person canceled. iOS's `WebAuthModule.swift` reports the same results through `ASWebAuthenticationSession`.
+
 ## Global props
 
 `MainActivity.globalProps()` sends what the runtime reads and Lynx has no API for (see the package README), again on every configuration change and accessibility setting change.
@@ -47,6 +51,7 @@ Back is off by default, so it leaves the app like any root screen. The runtime t
 Pinned in `app/build.gradle.kts`, `build.gradle.kts` and `gradle/wrapper/gradle-wrapper.properties`:
 
 - Lynx 4.1.0 and PrimJS 4.1.1 (Maven Central), Fresco 2.3.0 (the version Lynx's image service is built against), OkHttp 4.12.
+- `androidx.browser` 1.8.0, for the Custom Tabs `WebAuthModule` opens sign-in pages in.
 - Lynx's XElement 4.1.0 (`<input>`, `<textarea>`, `<overlay>`, `<svg>`, `<blur-view>`, `<viewpager>`, `<refresh>`, the `<scroll-coordinator>` family, `<webview>`, `<video>`), without its AnimaX and Markdown modules, which the runtime doesn't support. `MainActivity` registers the elements with `XElementBehaviors`. XElement depends on appcompat and material 1.0.0, whose vectordrawable libraries share a namespace that AGP 9 rejects, so appcompat 1.7.1 and material 1.12.0 are pinned.
 - AGP 9.4.1 with its built-in Kotlin, Gradle 9.6.1 (AGP 9.4's minimum), JDK 17 or newer.
 - `compileSdk` and `targetSdk` 36, `minSdk` 24. Google Play raises its target API requirement every August; bump `targetSdk` with it.

package/templates/android/app/build.gradle.kts

@@ -118,6 +118,8 @@ android {
 dependencies {
     implementation("androidx.activity:activity-ktx:1.10.1")
     implementation("androidx.core:core-ktx:1.16.0")
+    // Custom Tabs, which WebAuthModule opens sign-in pages in.
+    implementation("androidx.browser:browser:1.8.0")
 
     // The Lynx engine, its JavaScript runtime (PrimJS) and its JS SDK.
     implementation("org.lynxsdk.lynx:lynx:$lynxVersion")

package/templates/android/app/src/main/java/dev/angularlynx/shell/MainActivity.kt

@@ -1,9 +1,12 @@
 package dev.angularlynx.shell
 
 import android.app.UiModeManager
+import android.content.ActivityNotFoundException
+import android.content.Intent
 import android.content.res.Configuration
 import android.database.ContentObserver
 import android.graphics.drawable.ColorDrawable
+import android.net.Uri
 import android.os.Build
 import android.os.Bundle
 import android.os.Handler
@@ -15,6 +18,7 @@ import android.widget.FrameLayout
 import androidx.activity.ComponentActivity
 import androidx.activity.OnBackPressedCallback
 import androidx.activity.enableEdgeToEdge
+import androidx.browser.customtabs.CustomTabsIntent
 import androidx.core.graphics.Insets
 import androidx.core.os.ConfigurationCompat
 import androidx.core.view.ViewCompat
@@ -31,7 +35,7 @@ import com.lynx.xelement.XElementBehaviors
  * The whole app: one full-screen LynxView running the Angular app. Angular
  * Router navigates inside it, so there is no native navigation stack.
  */
-class MainActivity : ComponentActivity(), ShellModule.Host {
+class MainActivity : ComponentActivity(), ShellModule.Host, WebAuthModule.Host {
     private lateinit var lynxView: LynxView
 
     // The system bar and cutout insets, and whether the screen has a cutout,
@@ -57,6 +61,13 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
         }
     }
 
+    // The open sign-in (see WebAuthModule): the scheme its page returns to,
+    // who to tell, and whether the app has gone behind the Custom Tab yet.
+    private class WebAuthSession(val scheme: String, val done: (WebAuthModule.Result) -> Unit) {
+        var opened = false
+    }
+    private var webAuthSession: WebAuthSession? = null
+
     override fun onCreate(savedInstanceState: Bundle?) {
         // Android 15+ always draws apps edge to edge; opting in on older
         // versions too keeps the layout the same everywhere.
@@ -70,6 +81,7 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
             setEnableGenericResourceFetcher(LynxBooleanOption.TRUE)
             setGenericResourceFetcher(AssetGenericResourceFetcher(this@MainActivity))
             registerModule(ShellModule.NAME, ShellModule::class.java, this@MainActivity)
+            registerModule(WebAuthModule.NAME, WebAuthModule::class.java, this@MainActivity)
             // Lynx's core has no <input>, <overlay>, <svg>, <blur-view> etc.;
             // these come from XElement (see app/build.gradle.kts). Lynx
             // Explorer registers them the same way.
@@ -136,6 +148,33 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
         backHandler.isEnabled = enabled
     }
 
+    override fun startWebAuthSession(url: Uri, callbackScheme: String, done: (WebAuthModule.Result) -> Unit) {
+        if (webAuthSession != null) {
+            done(WebAuthModule.Result.Failed("A sign-in is already open."))
+            return
+        }
+        val session = WebAuthSession(callbackScheme.lowercase(), done)
+        webAuthSession = session
+        try {
+            CustomTabsIntent.Builder().build().launchUrl(this, url)
+        } catch (_: ActivityNotFoundException) {
+            webAuthSession = null
+            done(WebAuthModule.Result.Failed("No browser can open the sign-in page."))
+        }
+    }
+
+    // The page's redirect to the callback scheme. The activity is singleTask,
+    // so the deep link comes back to this one, which closes the Custom Tab
+    // above it. It arrives before onResume, which then finds no session open.
+    override fun onNewIntent(intent: Intent) {
+        super.onNewIntent(intent)
+        val url = intent.data ?: return
+        val session = webAuthSession ?: return
+        if (url.scheme?.lowercase() != session.scheme) return
+        webAuthSession = null
+        session.done(WebAuthModule.Result.Returned(url.toString()))
+    }
+
     // The manifest's configChanges keeps the activity, and the running app,
     // through a dark mode switch, so the new theme is sent from here. A
     // language change still restarts the activity, which sends the new
@@ -212,10 +251,17 @@ class MainActivity : ComponentActivity(), ShellModule.Host {
     override fun onResume() {
         super.onResume()
         lynxView.onEnterForeground()
+        // Back from a Custom Tab without its redirect: the person closed it.
+        // Android says nothing else when a Custom Tab closes.
+        webAuthSession?.takeIf { it.opened }?.let {
+            webAuthSession = null
+            it.done(WebAuthModule.Result.Canceled)
+        }
     }
 
     override fun onPause() {
         lynxView.onEnterBackground()
+        webAuthSession?.opened = true
         super.onPause()
     }
 

package/templates/android/app/src/main/java/dev/angularlynx/shell/WebAuthModule.kt

@@ -0,0 +1,77 @@
+package dev.angularlynx.shell
+
+import android.content.Context
+import android.net.Uri
+import android.os.Handler
+import android.os.Looper
+import com.lynx.jsbridge.LynxMethod
+import com.lynx.jsbridge.LynxModule
+import com.lynx.react.bridge.Callback
+import com.lynx.react.bridge.JavaOnlyMap
+import com.lynx.react.bridge.ReadableMap
+
+/**
+ * The native module behind the runtime's `LynxWebAuthSession`, which calls it
+ * as `NativeModules.AngularLynxWebAuth` (from the background thread, where
+ * NativeModules lives).
+ *
+ * Lynx has no popups or redirects, so a sign-in page can't run inside the
+ * app. The activity opens it in a Custom Tab instead, and the page's redirect
+ * to the callback scheme comes back to it as a deep link, which is why the
+ * scheme has to be one of the app's `deepLinkSchemes`.
+ */
+class WebAuthModule(context: Context, param: Any?) : LynxModule(context, param) {
+    private val host = param as Host
+    private val main = Handler(Looper.getMainLooper())
+
+    interface Host {
+        /**
+         * Opens [url] and calls [done] once with the URL the page redirected
+         * to on [callbackScheme], or with why it didn't.
+         */
+        fun startWebAuthSession(url: Uri, callbackScheme: String, done: (Result) -> Unit)
+    }
+
+    /** How a session ended: the URL the page returned to, or why it didn't. */
+    sealed interface Result {
+        data class Returned(val url: String) : Result
+        data object Canceled : Result
+        data class Failed(val message: String) : Result
+    }
+
+    /**
+     * Calls back once with `{ url }` or `{ error, message }`, where `error` is
+     * `canceled` or `failed`, as the iOS module does.
+     */
+    @LynxMethod
+    fun start(request: ReadableMap, callback: Callback) {
+        val url = request.getString("url", "")
+        val scheme = request.getString("callbackScheme", "")
+        if (url.isEmpty() || scheme.isEmpty()) {
+            callback.invoke(failed("The sign-in needs a URL and a callback scheme."))
+            return
+        }
+        // Lynx calls modules off the main thread, and the activity starts the
+        // Custom Tab.
+        main.post {
+            host.startWebAuthSession(Uri.parse(url), scheme) { result ->
+                callback.invoke(
+                    when (result) {
+                        is Result.Returned -> JavaOnlyMap.from(mapOf("url" to result.url))
+                        Result.Canceled -> JavaOnlyMap.from(
+                            mapOf("error" to "canceled", "message" to "The sign-in was canceled."),
+                        )
+                        is Result.Failed -> failed(result.message)
+                    },
+                )
+            }
+        }
+    }
+
+    private fun failed(message: String) =
+        JavaOnlyMap.from(mapOf("error" to "failed", "message" to message))
+
+    companion object {
+        const val NAME = "AngularLynxWebAuth"
+    }
+}

package/templates/ios/App/LynxViewController.swift

@@ -13,8 +13,11 @@ final class LynxViewController: UIViewController {
 
     let fetcher = BundleResourceFetcher.shared
     let screenSize = UIScreen.main.bounds.size
+    // The shell's native modules, which the runtime's services call.
+    let config = LynxConfig(provider: LynxEnv.sharedInstance().config.templateProvider)
+    config.register(WebAuthModule.self)
     let lynxView = LynxView { builder in
-      builder.config = LynxConfig(provider: LynxEnv.sharedInstance().config.templateProvider)
+      builder.config = config
       builder.screenSize = screenSize
       builder.fontScale = 1.0
       builder.enableGenericResourceFetcher = .true

package/templates/ios/App/WebAuthModule.swift

@@ -0,0 +1,95 @@
+import AuthenticationServices
+import Lynx
+import UIKit
+
+/// The native module behind the runtime's `LynxWebAuthSession`, which calls it
+/// as `NativeModules.AngularLynxWebAuth` (from the background thread, where
+/// NativeModules lives).
+///
+/// Lynx has no popups or redirects, so a sign-in page can't run inside the
+/// app. ASWebAuthenticationSession opens it in Safari's sign-in sheet instead,
+/// asking the person first, and ends when the page redirects to the callback
+/// scheme. The scheme needn't be registered in Info.plist: the session catches
+/// the redirect itself, so no other app can.
+final class WebAuthModule: NSObject, LynxModule, ASWebAuthenticationPresentationContextProviding {
+  static var name: String { "AngularLynxWebAuth" }
+
+  static var methodLookup: [String: String] {
+    ["start": NSStringFromSelector(#selector(start(_:callback:)))]
+  }
+
+  /// The open session. Held until it ends: ASWebAuthenticationSession closes
+  /// its sheet when released.
+  private var session: ASWebAuthenticationSession?
+
+  override init() {
+    super.init()
+  }
+
+  // Swift can't import an optional initializer as optional, so Lynx's
+  // initWithParam: is required here. Registered without a param, the module
+  // ignores it.
+  init(param: Any) {
+    super.init()
+  }
+
+  /// Opens `request.url` and calls back once with `{ url }`, the URL the page
+  /// redirected to, or `{ error, message }`, where `error` is `canceled` or
+  /// `failed`.
+  @objc func start(_ request: [String: Any], callback: @escaping LynxCallbackBlock) {
+    // Lynx calls modules off the main thread, and the session presents UI.
+    DispatchQueue.main.async {
+      self.open(request, callback)
+    }
+  }
+
+  private func open(_ request: [String: Any], _ callback: @escaping LynxCallbackBlock) {
+    let fail = { (message: String) in callback(["error": "failed", "message": message]) }
+    guard session == nil else {
+      fail("A sign-in is already open.")
+      return
+    }
+    guard let address = request["url"] as? String, let url = URL(string: address),
+      let scheme = request["callbackScheme"] as? String, !scheme.isEmpty
+    else {
+      fail("The sign-in needs a URL and a callback scheme.")
+      return
+    }
+
+    let completion: ASWebAuthenticationSession.CompletionHandler = { [weak self] url, error in
+      self?.session = nil
+      if let url {
+        callback(["url": url.absoluteString])
+      } else if let error = error as? ASWebAuthenticationSessionError,
+        error.code == .canceledLogin
+      {
+        callback(["error": "canceled", "message": "The sign-in was canceled."])
+      } else {
+        fail(error?.localizedDescription ?? "The sign-in page could not be opened.")
+      }
+    }
+    let session: ASWebAuthenticationSession
+    if #available(iOS 17.4, *) {
+      session = ASWebAuthenticationSession(
+        url: url, callback: .customScheme(scheme), completionHandler: completion)
+    } else {
+      session = ASWebAuthenticationSession(
+        url: url, callbackURLScheme: scheme, completionHandler: completion)
+    }
+    session.presentationContextProvider = self
+    session.prefersEphemeralWebBrowserSession = (request["ephemeral"] as? Bool) ?? false
+    self.session = session
+    if !session.start() {
+      self.session = nil
+      fail("The sign-in page could not be opened.")
+    }
+  }
+
+  /// The sheet opens over the app's window.
+  func presentationAnchor(for session: ASWebAuthenticationSession) -> ASPresentationAnchor {
+    UIApplication.shared.connectedScenes
+      .compactMap { $0 as? UIWindowScene }
+      .flatMap(\.windows)
+      .first(where: \.isKeyWindow) ?? ASPresentationAnchor()
+  }
+}