@webview-native-ui/engine 1.0.1 → 1.0.2

package/ios/Sources/WebViewNativeUIControls/Components/NativeUIVerticalSearch.swift

@@ -0,0 +1,117 @@
+import Combine
+import SwiftUI
+import UIKit
+
+@available(iOS 26.0, *)
+final class NativeUIVerticalSearchModel: ObservableObject {
+    @Published private(set) var configuration: NativeUISearch
+    @Published var text: String
+    @Published var presented: Bool
+    @Published var focused: Bool
+    private weak var railView: UIView?
+    private let activate: (String) -> Void
+    private let changed: (String, NativeUISearchPhase, String, Bool, Int) -> Int
+    private let inputDelegate = NativeUISearchInputDelegate()
+    private var editingSequence = 0
+    private var valueVersion: Int
+
+    init(_ configuration: NativeUISearch, in railView: UIView,
+         activate: @escaping (String) -> Void,
+         changed: @escaping (String, NativeUISearchPhase, String, Bool, Int) -> Int) {
+        self.configuration = configuration
+        self.railView = railView
+        self.activate = activate
+        self.changed = changed
+        text = configuration.value
+        presented = configuration.available && configuration.active
+        focused = configuration.focused
+        valueVersion = configuration.valueVersion
+        inputDelegate.clear = { [weak self] in self?.emit(.clear) }
+    }
+
+    var ownsKeyboardChrome: Bool { presented && (focused || textField?.isFirstResponder == true) }
+
+    private var textField: UISearchTextField? {
+        func find(_ view: UIView) -> UISearchTextField? {
+            guard !view.isHidden, view.alpha > 0.01 else { return nil }
+            if let field = view as? UISearchTextField { return field }
+            for child in view.subviews {
+                if let field = find(child) { return field }
+            }
+            return nil
+        }
+        return railView.flatMap(find)
+    }
+
+    func apply(_ next: NativeUISearch) {
+        let previous = configuration
+        configuration = next
+        if next.valueVersion != valueVersion || next.editSequence >= editingSequence {
+            valueVersion = next.valueVersion
+            text = next.value
+        }
+        presented = next.available && next.active
+        // The first Web acknowledgement still carries the old focus state.
+        if !next.active { focused = false } else if previous.focused != next.focused { focused = next.focused }
+    }
+
+    func input(_ value: String) {
+        text = value
+        emit(.input)
+    }
+
+    func present(_ value: Bool) {
+        presented = value
+        if value != configuration.active {
+            activate(value ? configuration.trigger.id : configuration.closeId)
+        }
+    }
+
+    func focus(_ value: Bool) {
+        focused = value
+        emit(value ? .focus : .blur)
+    }
+
+    func commit() { emit(.commit) }
+
+    func configureField() {
+        guard let field = textField else { return }
+        field.accessibilityIdentifier = configuration.id
+        field.accessibilityLabel = configuration.field.accessibilityLabel
+        field.isEnabled = !configuration.disabled
+        field.autocapitalizationType = .none
+        field.autocorrectionType = .no
+        field.spellCheckingType = .no
+        field.clearButtonMode = .always
+        if field.delegate !== inputDelegate {
+            inputDelegate.original = field.delegate
+            field.delegate = inputDelegate
+        }
+    }
+
+    private func emit(_ phase: NativeUISearchPhase) {
+        editingSequence = changed(configuration.id, phase, text,
+                                  textField?.markedTextRange != nil, valueVersion)
+    }
+}
+
+@available(iOS 26.0, *)
+struct NativeUIVerticalSearchModifier: ViewModifier {
+    @ObservedObject var model: NativeUIVerticalSearchModel
+    @FocusState private var focused: Bool
+
+    @ViewBuilder func body(content: Content) -> some View {
+        if model.configuration.available {
+            content
+                .searchable(text: Binding(get: { model.text }, set: model.input),
+                            isPresented: Binding(get: { model.presented }, set: model.present),
+                            placement: .toolbar, prompt: Text(model.configuration.placeholder))
+                .searchToolbarBehavior(.minimize)
+                .searchPresentationToolbarBehavior(.avoidHidingContent)
+                .searchFocused($focused)
+                .onSubmit(of: .search, model.commit)
+                .onChange(of: focused) { _, value in model.focus(value) }
+                .onChange(of: model.focused) { _, value in focused = value }
+        } else { content }
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Extensions/NativeUI.swift

@@ -0,0 +1,180 @@
+import WebViewNativeUIEngine
+import SwiftUI
+import UIKit
+
+/// Experimental API: registration interfaces and behavior may change in future releases.
+/// App-local SwiftUI renderers. Register once before enabling the shell from JavaScript.
+@MainActor public enum NativeUI {
+    private static var renderers: [String: (String, NativeUIActions, NativeUIContext) throws -> AnyView] = [:]
+
+    /// The name must match defineNativeUI in the application's TypeScript source.
+    public static func register<Props: Decodable, Content: View>(
+        _ name: String, @ViewBuilder content: @escaping (Props, NativeUIActions) -> Content
+    ) throws {
+        try register(name) { (props: Props, actions: NativeUIActions, _: NativeUIContext) in
+            content(props, actions)
+        }
+    }
+
+    /// Receives source geometry and presentation state on every accepted snapshot.
+    public static func register<Props: Decodable, Content: View>(
+        _ name: String, @ViewBuilder content: @escaping (Props, NativeUIActions, NativeUIContext) -> Content
+    ) throws {
+        guard !name.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty, renderers[name] == nil else {
+            throw NativeUIError.duplicateRegistration
+        }
+        renderers[name] = { json, actions, context in
+            let props = try JSONDecoder().decode(Props.self, from: Data(json.utf8))
+            return AnyView(content(props, actions, context))
+        }
+    }
+
+    static var names: [String] { renderers.keys.sorted() }
+
+    static func content(_ data: NativeUIExtensionContent, actions: NativeUIActions, context: NativeUIContext) throws -> AnyView {
+        guard let renderer = renderers[data.name] else { throw NativeUIError.unavailable }
+        return try renderer(data.props, actions, context)
+    }
+}
+
+/// Read-only metadata for a projected Web source. Shell still owns its placement.
+public struct NativeUIContext {
+    public enum Placement: String { case element, tabAccessory = "tab-accessory" }
+
+    /// Opaque identity stable for this source's current lifetime; not its HTML id.
+    public let sourceID: String
+    /// getBoundingClientRect(), in CSS pixels relative to the Web viewport.
+    public let sourceFrame: CGRect
+    /// The same source rectangle in WKWebView-local UIKit points, not screen coordinates.
+    public let sourceFrameInWebView: CGRect
+    /// CSS viewport width used to convert the snapshot into native coordinates.
+    public let viewportWidth: CGFloat
+    /// UIKit points per CSS pixel. This is not the device's pixel density.
+    public let pointsPerCSSPixel: CGFloat
+    public let placement: Placement
+    public let colorScheme: ColorScheme
+    public let layoutDirection: LayoutDirection
+
+    init(node: NativeUIControl, viewportWidth: CGFloat, pointsPerCSSPixel: CGFloat) {
+        sourceID = node.id
+        sourceFrame = node.frame.rect
+        sourceFrameInWebView = node.frame.rect.applying(
+            CGAffineTransform(scaleX: pointsPerCSSPixel, y: pointsPerCSSPixel))
+        self.viewportWidth = viewportWidth
+        self.pointsPerCSSPixel = pointsPerCSSPixel
+        placement = node.extensionContent?.tabBarId == nil ? .element : .tabAccessory
+        colorScheme = node.dark ? .dark : .light
+        layoutDirection = node.rtl ? .rightToLeft : .leftToRight
+    }
+}
+
+public enum NativeUIError: Error {
+    case duplicateRegistration, unavailable, rejected, timedOut
+}
+
+/// Completion means the original Web element received its click, not that the
+/// application's asynchronous work triggered by that click has finished.
+@MainActor public struct NativeUIActions {
+    let dispatch: (String) async throws -> Void
+    /// Names of currently visible, enabled DOM targets supplied by the reader.
+    public let availableNames: Set<String>
+
+    init(availableNames: Set<String> = [], dispatch: @escaping (String) async throws -> Void) {
+        self.availableNames = availableNames
+        self.dispatch = dispatch
+    }
+
+    public func isAvailable(_ name: String) -> Bool { availableNames.contains(name) }
+
+    public func activate(_ name: String) async throws {
+        try Task.checkCancellation()
+        try await dispatch(name)
+    }
+}
+
+struct NativeUIExtensionContent: Decodable, Equatable {
+    let name: String
+    let props: String
+    let actions: [String: String]
+    let tabBarId: String?
+
+    var isValid: Bool {
+        !name.isEmpty && props.utf8.count <= 262144 && actions.count <= 30 &&
+            actions.allSatisfy { !$0.key.isEmpty && !$0.value.isEmpty } &&
+            (tabBarId.map { !$0.isEmpty } ?? true) &&
+            (try? JSONSerialization.jsonObject(with: Data(props.utf8))) is [String: Any]
+    }
+}
+
+/// Owns pending native -> Web calls independently of the View's lifetime.
+@MainActor final class NativeUIExtensionActions {
+    private struct Pending {
+        let owner: String
+        let continuation: CheckedContinuation<Void, Error>
+        let deadline: DispatchWorkItem
+    }
+    private var pending: [String: Pending] = [:]
+
+    func perform(owner: String, timeout: TimeInterval = 4, send: (String) -> Void) async throws {
+        let request = UUID().uuidString
+        try await withTaskCancellationHandler {
+            try Task.checkCancellation()
+            try await withCheckedThrowingContinuation { continuation in
+                let deadline = DispatchWorkItem { [weak self] in self?.finish(request, error: NativeUIError.timedOut) }
+                pending[request] = Pending(owner: owner, continuation: continuation, deadline: deadline)
+                DispatchQueue.main.asyncAfter(deadline: .now() + timeout, execute: deadline)
+                send(request)
+            }
+        } onCancel: {
+            Task { @MainActor [weak self] in self?.finish(request, error: CancellationError()) }
+        }
+    }
+
+    func finish(_ request: String, error: Error? = nil) {
+        guard let call = pending.removeValue(forKey: request) else { return }
+        call.deadline.cancel()
+        if let error { call.continuation.resume(throwing: error) } else { call.continuation.resume() }
+    }
+
+    func cancel(owner: String? = nil) {
+        for (request, call) in pending where owner == nil || call.owner == owner {
+            finish(request, error: NativeUIError.unavailable)
+        }
+    }
+}
+
+/// Normal UIViewController containment keeps SwiftUI appearance and teardown intact.
+@MainActor final class NativeUIExtensionController {
+    let controller: UIHostingController<AnyView>
+    let view: NativeUIClippedView
+
+    init(content: AnyView, owner: UIViewController) {
+        controller = UIHostingController(rootView: content)
+        view = NativeUIClippedView(content: controller.view)
+        controller.view.backgroundColor = .clear
+        if #available(iOS 16.4, *) { controller.safeAreaRegions = [] }
+        owner.addChild(controller)
+        // Capacitor can use WKWebView as its controller's root view. A sibling
+        // shell surface is outside that controller's containment hierarchy.
+        owner.view.addSubview(view)
+        controller.didMove(toParent: owner)
+    }
+
+    func update(_ content: AnyView) { controller.rootView = content }
+    func place(_ frame: CGRect, clip: CGRect? = nil) { view.place(frame, clip: clip) }
+    func detach(duration: TimeInterval) {
+        controller.willMove(toParent: nil)
+        NativeUICrossfade.retire(view, duration: duration)
+        controller.removeFromParent()
+    }
+}
+
+@available(iOS 26.0, *)
+struct NativeUIExtensionAccessory: ViewModifier {
+    let content: AnyView?
+    func body(content base: Content) -> some View {
+        if #available(iOS 26.1, *) {
+            base.tabViewBottomAccessory(isEnabled: content != nil) { content }
+        } else { base }
+    }
+}

package/ios/Sources/WebViewNativeUIControls/Extensions/NativeUIRendering.swift

@@ -0,0 +1,38 @@
+import UIKit
+
+/// Image returned by the TypeScript read context's image() helper.
+public struct NativeUIImage: Decodable {
+    public let data: String
+    public let width: Double
+    public let height: Double
+    public let template: Bool
+
+    public init(data: String, width: Double, height: Double, template: Bool = false) {
+        self.data = data
+        self.width = width
+        self.height = height
+        self.template = template
+    }
+}
+
+/// Conversion primitives shared by standard controls and app-local extensions.
+public enum NativeUIRendering {
+    /// Decodes base64 PNG artwork at its declared CSS size. Returns nil for invalid data.
+    public static func image(_ image: NativeUIImage) -> UIImage? {
+        guard image.width.isFinite, image.height.isFinite, image.width > 0, image.height > 0,
+              let bytes = Data(base64Encoded: image.data), let raw = UIImage(data: bytes), let cg = raw.cgImage else { return nil }
+        return UIImage(cgImage: cg, scale: CGFloat(cg.width) / image.width, orientation: .up)
+            .withRenderingMode(image.template ? .alwaysTemplate : .alwaysOriginal)
+    }
+
+    /// Converts computed rgb()/rgba() colors used by standard readers. Other CSS formats use the fallback.
+    public static func color(_ css: String?, fallback: UIColor = .label) -> UIColor {
+        guard let css, css.hasPrefix("rgb(") || css.hasPrefix("rgba("), !css.contains("%") else { return fallback }
+        let numbers = css.components(separatedBy: CharacterSet(charactersIn: "0123456789.-").inverted).compactMap(Double.init)
+        guard numbers.count == 3 || numbers.count == 4, numbers.allSatisfy(\.isFinite) else { return fallback }
+        return UIColor(red: min(255, max(0, numbers[0])) / 255,
+                       green: min(255, max(0, numbers[1])) / 255,
+                       blue: min(255, max(0, numbers[2])) / 255,
+                       alpha: numbers.count == 4 ? min(1, max(0, numbers[3])) : 1)
+    }
+}