pythonnative 0.40.0__cp313-cp313-win_amd64.whl

pythonnative/native/ios/Sources/PythonNativeKit/Components/PNOverlayManagers.swift

@@ -0,0 +1,243 @@
+import UIKit
+
+/// `Modal`: a hidden on-tree placeholder whose children mount into a
+/// presented `UIViewController` while `visible` is true.
+public final class PNModalManager: PNComponentManager {
+    final class Presentation {
+        let controller: UIViewController
+        let content: UIView
+        init(controller: UIViewController, content: UIView) {
+            self.controller = controller
+            self.content = content
+        }
+    }
+
+    public override func makeView(props: [String: Any]) -> UIView {
+        let placeholder = UIView(frame: .zero)
+        placeholder.isHidden = true
+        return placeholder
+    }
+
+    public override func apply(view: UIView, props: [String: Any], initial: Bool) {
+        guard let state = PNViewState.existing(for: view) else { return }
+        let visible = PNProps.bool(PNProps.value(state.props, "visible")) ?? false
+        let presented = state.extras["modal"] is Presentation
+        if visible, !presented {
+            present(view, state)
+        } else if !visible, presented {
+            dismiss(view, state, emit: true)
+        }
+    }
+
+    public override func teardown(view: UIView) {
+        if let state = PNViewState.existing(for: view), state.extras["modal"] is Presentation {
+            dismiss(view, state, emit: false)
+        }
+    }
+
+    public override func childContainer(for view: UIView) -> UIView {
+        guard let state = PNViewState.existing(for: view), let modal = state.extras["modal"] as? Presentation else {
+            return view
+        }
+        return modal.content
+    }
+
+    public override func insertChild(parent: UIView, child: UIView, index: Int) {
+        if let state = PNViewState.existing(for: parent), !(state.extras["modal"] is Presentation) {
+            var pending = (state.extras["pending_children"] as? [UIView]) ?? []
+            pending.removeAll { $0 === child }
+            pending.insert(child, at: max(0, min(index, pending.count)))
+            state.extras["pending_children"] = pending
+            return
+        }
+        super.insertChild(parent: parent, child: child, index: index)
+    }
+
+    public override func removeChild(parent: UIView, child: UIView) {
+        super.removeChild(parent: parent, child: child)
+        if let state = PNViewState.existing(for: parent), var pending = state.extras["pending_children"] as? [UIView] {
+            pending.removeAll { $0 === child }
+            state.extras["pending_children"] = pending
+        }
+    }
+
+    public override func setFrame(view: UIView, x: Double, y: Double, w: Double, h: Double) {}
+
+    public override func measure(view: UIView, maxW: CGFloat, maxH: CGFloat) -> CGSize { .zero }
+
+    private func present(_ placeholder: UIView, _ state: PNViewState) {
+        let props = state.props
+        let controller = PNModalViewController()
+        controller.onDismissed = { [weak placeholder] in
+            guard let placeholder = placeholder, let state = PNViewState.existing(for: placeholder),
+                  state.extras["modal"] is Presentation
+            else { return }
+            state.extras.removeValue(forKey: "modal")
+            PNEvents.emit(placeholder, "on_dismiss")
+            PNEvents.emitIfWired(placeholder, "on_request_close")
+        }
+        let style = PNProps.string(PNProps.value(props, "presentation_style")) ?? "page_sheet"
+        let isOverlay = style == "overlay" || PNProps.bool(PNProps.value(props, "transparent")) == true
+        let content = UIView(frame: controller.view.bounds)
+        content.backgroundColor = isOverlay ? .clear : PNColor.parse(PNProps.value(props, "background_color")) ?? .systemBackground
+        content.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        controller.view.addSubview(content)
+        controller.view.backgroundColor = isOverlay ? UIColor.black.withAlphaComponent(0.4) : content.backgroundColor
+        switch isOverlay ? "overlay" : style {
+        case "full_screen": controller.modalPresentationStyle = .fullScreen
+        case "form_sheet": controller.modalPresentationStyle = .formSheet
+        case "overlay": controller.modalPresentationStyle = .overCurrentContext
+        default: controller.modalPresentationStyle = .pageSheet
+        }
+        switch PNProps.string(PNProps.value(props, "animation_type")) ?? PNProps.string(PNProps.value(props, "animation")) {
+        case "fade": controller.modalTransitionStyle = .crossDissolve
+        case "flip": controller.modalTransitionStyle = .flipHorizontal
+        default: controller.modalTransitionStyle = .coverVertical
+        }
+        if !isOverlay, PNProps.bool(PNProps.value(props, "dismiss_on_backdrop")) == false {
+            controller.isModalInPresentation = true
+        }
+        let presentation = Presentation(controller: controller, content: content)
+        state.extras["modal"] = presentation
+        for child in (state.extras.removeValue(forKey: "pending_children") as? [UIView]) ?? [] {
+            child.translatesAutoresizingMaskIntoConstraints = true
+            content.addSubview(child)
+        }
+        let animated = PNProps.string(PNProps.value(props, "animation_type")) != "none"
+        guard let top = PNWindow.topViewController() else {
+            state.extras.removeValue(forKey: "modal")
+            return
+        }
+        top.present(controller, animated: animated) { [weak placeholder] in
+            if let placeholder = placeholder { PNEvents.emit(placeholder, "on_show") }
+        }
+    }
+
+    private func dismiss(_ placeholder: UIView, _ state: PNViewState, emit: Bool) {
+        guard let modal = state.extras.removeValue(forKey: "modal") as? Presentation else { return }
+        (modal.controller as? PNModalViewController)?.onDismissed = nil
+        let animated = PNProps.string(PNProps.value(state.props, "animation_type")) != "none"
+        modal.controller.dismiss(animated: animated)
+        if emit { PNEvents.emit(placeholder, "on_dismiss") }
+    }
+}
+
+/// Reports interactive dismissal (sheet swipe) back to the manager.
+final class PNModalViewController: UIViewController {
+    var onDismissed: (() -> Void)?
+
+    override func viewDidDisappear(_ animated: Bool) {
+        super.viewDidDisappear(animated)
+        if isBeingDismissed || presentingViewController == nil {
+            onDismissed?()
+        }
+    }
+}
+
+/// Overlay view that only claims touches landing on one of its subviews.
+final class PNPortalView: UIView {
+    override func point(inside point: CGPoint, with event: UIEvent?) -> Bool {
+        for sub in subviews where !sub.isHidden && sub.alpha > 0.01 && sub.isUserInteractionEnabled {
+            if sub.frame.contains(point) { return true }
+        }
+        return false
+    }
+}
+
+/// `Portal`: floats children over the screen in a top-level overlay that
+/// mirrors the screen host's root frame.
+public final class PNPortalManager: PNComponentManager {
+    public override func makeView(props: [String: Any]) -> UIView {
+        let overlay = PNPortalView(frame: .zero)
+        overlay.backgroundColor = .clear
+        return overlay
+    }
+
+    public override func apply(view: UIView, props: [String: Any], initial: Bool) {
+        PNViewStyler.applyCommon(view, props)
+        if !initial { ensureAttached(view) }
+    }
+
+    public override func insertChild(parent: UIView, child: UIView, index: Int) {
+        ensureAttached(parent)
+        super.insertChild(parent: parent, child: child, index: index)
+    }
+
+    public override func setFrame(view: UIView, x: Double, y: Double, w: Double, h: Double) {}
+
+    public override func measure(view: UIView, maxW: CGFloat, maxH: CGFloat) -> CGSize { .zero }
+
+    private func ensureAttached(_ overlay: UIView) {
+        guard let host = PNWindow.topViewController()?.view else { return }
+        if overlay.superview === host {
+            if host.subviews.last !== overlay {
+                host.bringSubviewToFront(overlay)
+            }
+            syncFrame(overlay, host: host)
+            return
+        }
+        overlay.removeFromSuperview()
+        host.addSubview(overlay)
+        syncFrame(overlay, host: host)
+    }
+
+    static func rootFrame(in host: UIView) -> CGRect {
+        let bounds = host.bounds
+        let insets = host.safeAreaInsets
+        let w = max(0, bounds.width - insets.left - insets.right)
+        let h = max(0, bounds.height - insets.top)
+        return CGRect(x: insets.left, y: insets.top, width: w, height: h)
+    }
+
+    private func syncFrame(_ overlay: UIView, host: UIView) {
+        overlay.frame = PNPortalManager.rootFrame(in: host)
+        overlay.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+    }
+}
+
+/// Process-wide status bar state consulted by `PNViewController`.
+public enum PNStatusBarState {
+    public static var hidden = false
+    public static var style: UIStatusBarStyle = .default
+    public static var animation: UIStatusBarAnimation = .fade
+
+    static func refresh() {
+        var controller = PNWindow.keyWindow()?.rootViewController
+        if let nav = controller as? UINavigationController { controller = nav.topViewController }
+        controller?.setNeedsStatusBarAppearanceUpdate()
+    }
+}
+
+/// `StatusBar`: a global side effect (hidden / style), no on-screen view.
+public final class PNStatusBarManager: PNComponentManager {
+    public override func makeView(props: [String: Any]) -> UIView {
+        let placeholder = UIView(frame: .zero)
+        placeholder.isHidden = true
+        return placeholder
+    }
+
+    public override func apply(view: UIView, props: [String: Any], initial: Bool) {
+        if let hidden = PNProps.bool(PNProps.value(props, "hidden")) {
+            PNStatusBarState.hidden = hidden
+        }
+        if let style = PNProps.string(PNProps.value(props, "bar_style")) {
+            switch style {
+            case "light", "light_content": PNStatusBarState.style = .lightContent
+            case "dark", "dark_content": PNStatusBarState.style = .darkContent
+            default: PNStatusBarState.style = .default
+            }
+        }
+        if let animation = PNProps.string(PNProps.value(props, "animation")) {
+            switch animation {
+            case "slide": PNStatusBarState.animation = .slide
+            case "none": PNStatusBarState.animation = .none
+            default: PNStatusBarState.animation = .fade
+            }
+        }
+        PNStatusBarState.refresh()
+    }
+
+    public override func setFrame(view: UIView, x: Double, y: Double, w: Double, h: Double) {}
+
+    public override func measure(view: UIView, maxW: CGFloat, maxH: CGFloat) -> CGSize { .zero }
+}

pythonnative/native/ios/Sources/PythonNativeKit/Components/PNPressableManager.swift

@@ -0,0 +1,114 @@
+import UIKit
+
+/// `Pressable`: a touchable container with press feedback.
+///
+/// A zero-duration long-press recognizer tracks the raw touch for
+/// `on_press_in` / `on_press_out` and the pressed-opacity feedback; a tap
+/// recognizer fires `on_press` and a standard long press fires
+/// `on_long_press`. Hit slop and pointer events come from
+/// `PNContainerView`, so hit testing is entirely UIKit's.
+public final class PNPressableManager: PNComponentManager {
+    public override func makeView(props: [String: Any]) -> UIView {
+        let view = PNContainerView(frame: .zero)
+        view.isUserInteractionEnabled = true
+        return view
+    }
+
+    public override func createView(tag: Int64, props: [String: Any]) -> UIView {
+        let view = super.createView(tag: tag, props: props)
+        let handler = PNPressHandler(view: view)
+        PNViewState.existing(for: view)?.retained.append(handler)
+        handler.install()
+        return view
+    }
+
+    public override func apply(view: UIView, props: [String: Any], initial: Bool) {
+        PNViewStyler.applyCommon(view, props)
+        if PNProps.has(props, "disabled") {
+            view.isUserInteractionEnabled = !(PNProps.bool(PNProps.value(props, "disabled")) ?? false)
+        }
+        if PNProps.has(props, "disabled") {
+            view.isUserInteractionEnabled = !(PNProps.bool(PNProps.value(props, "disabled")) ?? false)
+        }
+        if let delay = PNProps.double(PNProps.value(props, "delay_long_press")),
+           let handler = PNViewState.existing(for: view)?.retained.compactMap({ $0 as? PNPressHandler }).first
+        {
+            handler.longPress.minimumPressDuration = max(0.05, delay / 1000)
+        }
+    }
+}
+
+/// Owns the three press recognizers of one Pressable.
+final class PNPressHandler: NSObject, UIGestureRecognizerDelegate {
+    private weak var view: UIView?
+    let tap = UITapGestureRecognizer()
+    let longPress = UILongPressGestureRecognizer()
+    let touch = UILongPressGestureRecognizer()
+
+    init(view: UIView) {
+        self.view = view
+        super.init()
+    }
+
+    func install() {
+        guard let view = view else { return }
+        touch.minimumPressDuration = 0
+        tap.addTarget(self, action: #selector(onTap(_:)))
+        longPress.addTarget(self, action: #selector(onLongPress(_:)))
+        touch.addTarget(self, action: #selector(onTouch(_:)))
+        for recognizer in [tap, longPress, touch] {
+            recognizer.cancelsTouchesInView = false
+            recognizer.delegate = self
+            view.addGestureRecognizer(recognizer)
+        }
+    }
+
+    private var merged: [String: Any] {
+        view.flatMap { PNViewState.existing(for: $0)?.props } ?? [:]
+    }
+
+    @objc private func onTap(_ recognizer: UITapGestureRecognizer) {
+        guard let view = view, recognizer.state == .ended else { return }
+        PNEvents.emit(view, "on_press")
+    }
+
+    @objc private func onLongPress(_ recognizer: UILongPressGestureRecognizer) {
+        guard let view = view, recognizer.state == .began else { return }
+        PNEvents.emit(view, "on_long_press")
+    }
+
+    @objc private func onTouch(_ recognizer: UILongPressGestureRecognizer) {
+        guard let view = view else { return }
+        switch recognizer.state {
+        case .began:
+            feedback(pressed: true)
+            PNEvents.emit(view, "on_press_in")
+        case .ended, .cancelled, .failed:
+            feedback(pressed: false)
+            PNEvents.emit(view, "on_press_out")
+        default:
+            break
+        }
+    }
+
+    private func feedback(pressed: Bool) {
+        guard let view = view else { return }
+        let props = merged
+        let target: CGFloat
+        let duration: TimeInterval
+        if pressed {
+            target = CGFloat(PNProps.double(PNProps.value(props, "pressed_opacity")) ?? 0.6)
+            duration = 0.05
+        } else {
+            target = CGFloat(PNProps.double(PNProps.value(props, "opacity")) ?? 1)
+            duration = 0.1
+        }
+        UIView.animate(withDuration: duration) { view.alpha = target }
+    }
+
+    // Press recognizers recognize alongside everything, including the
+    // declarative `gestures` recognizers and a parent scroll view's pan.
+    func gestureRecognizer(_ gestureRecognizer: UIGestureRecognizer, shouldRecognizeSimultaneouslyWith other: UIGestureRecognizer) -> Bool {
+        true
+    }
+}

pythonnative/native/ios/Sources/PythonNativeKit/Components/PNScreenStackManager.swift

@@ -0,0 +1,107 @@
+import UIKit
+
+private final class PNLogicalScreen: UIView {
+    private var lastSize = CGSize.zero
+    override func layoutSubviews() {
+        super.layoutSubviews()
+        if bounds.size != lastSize {
+            lastSize = bounds.size
+            PNLayout.containerDidLayout()
+        }
+    }
+}
+
+public final class PNScreenManager: PNComponentManager {
+    public override func makeView(props: [String: Any]) -> UIView { PNLogicalScreen(frame: .zero) }
+    public override func apply(view: UIView, props: [String: Any], initial: Bool) {
+        if let controller = view.next as? UIViewController {
+            HostModule.applyOptions(PNViewState.existing(for: view)?.props ?? props, to: controller)
+        }
+    }
+    // UIKit owns the controller's content rectangle, including its navigation bar.
+    public override func setFrame(view: UIView, x: Double, y: Double, w: Double, h: Double) {}
+}
+
+private final class PNLogicalStack: UIView, UINavigationControllerDelegate {
+    let navigation = UINavigationController()
+    var controllers: [Int64: UIViewController] = [:]
+    var order: [Int64] = []
+    var applying = false
+    var scheduled = false
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        navigation.delegate = self
+        addSubview(navigation.view)
+    }
+    required init?(coder: NSCoder) { fatalError("init(coder:) is unavailable") }
+    override func didMoveToWindow() {
+        super.didMoveToWindow()
+        guard window != nil, navigation.parent == nil else { return }
+        var responder: UIResponder? = superview
+        while let current = responder {
+            if let parent = current as? UIViewController {
+                parent.addChild(navigation)
+                navigation.didMove(toParent: parent)
+                parent.navigationController?.setNavigationBarHidden(true, animated: false)
+                break
+            }
+            responder = current.next
+        }
+    }
+    override func layoutSubviews() {
+        super.layoutSubviews()
+        navigation.view.frame = bounds
+    }
+    func schedule() {
+        guard !scheduled else { return }
+        scheduled = true
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            self.scheduled = false
+            self.applying = true
+            self.navigation.setViewControllers(self.order.compactMap { self.controllers[$0] }, animated: false)
+            if let tag = self.order.last, let state = PNViewRegistry.shared.view(for: tag).flatMap({ PNViewState.existing(for: $0) }),
+               let controller = self.controllers[tag] { HostModule.applyOptions(state.props, to: controller) }
+            self.applying = false
+        }
+    }
+    func navigationController(_ navigationController: UINavigationController, didShow viewController: UIViewController, animated: Bool) {
+        if !applying && navigation.viewControllers.count < order.count {
+            PNEvents.emit(self, "on_native_back", [order.count - navigation.viewControllers.count])
+        }
+    }
+}
+
+/// Native screen presentation without importing or remounting App.
+public final class PNScreenStackManager: PNComponentManager {
+    public override func makeView(props: [String: Any]) -> UIView { PNLogicalStack(frame: .zero) }
+    public override func insertChild(parent: UIView, child: UIView, index: Int) {
+        guard let stack = parent as? PNLogicalStack, let state = PNViewState.existing(for: child) else { return }
+        let controller = stack.controllers[state.tag] ?? UIViewController()
+        controller.edgesForExtendedLayout = []
+        controller.view = child
+        controller.title = state.props["title"] as? String
+        stack.controllers[state.tag] = controller
+        stack.order.removeAll { $0 == state.tag }
+        stack.order.insert(state.tag, at: min(index, stack.order.count))
+        stack.schedule()
+    }
+    public override func removeChild(parent: UIView, child: UIView) {
+        guard let stack = parent as? PNLogicalStack, let state = PNViewState.existing(for: child) else { return }
+        stack.order.removeAll { $0 == state.tag }
+        stack.controllers.removeValue(forKey: state.tag)
+        stack.schedule()
+    }
+    public override func command(view: UIView, name: String, args: [String: Any]) -> Any? {
+        if name == "restore_stack", let stack = view as? PNLogicalStack { stack.schedule() }
+        return nil
+    }
+    public override func teardown(view: UIView) {
+        guard let stack = view as? PNLogicalStack else { return }
+        stack.navigation.willMove(toParent: nil)
+        stack.navigation.view.removeFromSuperview()
+        stack.navigation.removeFromParent()
+        stack.controllers.removeAll()
+        stack.navigation.delegate = nil
+    }
+}

pythonnative/native/ios/Sources/PythonNativeKit/Components/PNScrollViewManager.swift

@@ -0,0 +1,197 @@
+import UIKit
+
+/// `ScrollView`: a `UIScrollView` wrapping one layout-engine-sized child.
+///
+/// Scroll offsets are reported through `on_scroll` with
+/// `{"x", "y", "extent", "range", "content_width", "content_height"}`.
+/// Commands: `scroll_to_offset`, `scroll_to_end`, `get_scroll_offset`,
+/// `flash_scroll_indicators`.
+public final class PNScrollViewManager: PNComponentManager {
+    public override func makeView(props: [String: Any]) -> UIView {
+        let scroll = UIScrollView(frame: .zero)
+        scroll.contentInsetAdjustmentBehavior = .never
+        return scroll
+    }
+
+    public override func createView(tag: Int64, props: [String: Any]) -> UIView {
+        let view = super.createView(tag: tag, props: props)
+        if let scroll = view as? UIScrollView {
+            let delegate = PNScrollDelegate()
+            scroll.delegate = delegate
+            PNViewState.existing(for: scroll)?.retained.append(delegate)
+        }
+        return view
+    }
+
+    public override func apply(view: UIView, props: [String: Any], initial: Bool) {
+        guard let scroll = view as? UIScrollView else { return }
+        PNViewStyler.applyCommon(scroll, props)
+        if PNProps.has(props, "refresh_control") {
+            applyRefresh(scroll, PNProps.value(props, "refresh_control"))
+        }
+        if PNProps.has(props, "shows_scroll_indicator") {
+            let visible = PNProps.bool(PNProps.value(props, "shows_scroll_indicator")) ?? true
+            scroll.showsVerticalScrollIndicator = visible
+            scroll.showsHorizontalScrollIndicator = visible
+        }
+        if PNProps.has(props, "paging_enabled") {
+            scroll.isPagingEnabled = PNProps.bool(PNProps.value(props, "paging_enabled")) ?? false
+        }
+        if PNProps.has(props, "bounces") {
+            scroll.bounces = PNProps.bool(PNProps.value(props, "bounces")) ?? true
+        }
+        if PNProps.has(props, "scroll_enabled") {
+            scroll.isScrollEnabled = PNProps.bool(PNProps.value(props, "scroll_enabled")) ?? true
+        }
+        if PNProps.has(props, "horizontal") {
+            let horizontal = PNProps.bool(PNProps.value(props, "horizontal")) ?? false
+            scroll.alwaysBounceHorizontal = horizontal
+            scroll.alwaysBounceVertical = !horizontal && scroll.refreshControl != nil
+        }
+        if let mode = PNProps.string(PNProps.value(props, "keyboard_dismiss_mode")) {
+            switch mode {
+            case "on_drag": scroll.keyboardDismissMode = .onDrag
+            case "interactive": scroll.keyboardDismissMode = .interactive
+            default: scroll.keyboardDismissMode = .none
+            }
+        }
+        if PNProps.has(props, "content_inset") {
+            let inset = PNProps.dict(PNProps.value(props, "content_inset")) ?? [:]
+            scroll.contentInset = UIEdgeInsets(
+                top: CGFloat(PNProps.double(inset["top"]) ?? 0), left: CGFloat(PNProps.double(inset["left"]) ?? 0),
+                bottom: CGFloat(PNProps.double(inset["bottom"]) ?? 0), right: CGFloat(PNProps.double(inset["right"]) ?? 0)
+            )
+        }
+        if PNProps.has(props, "scroll_indicator_insets") {
+            let inset = PNProps.dict(PNProps.value(props, "scroll_indicator_insets")) ?? [:]
+            let insets = UIEdgeInsets(
+                top: CGFloat(PNProps.double(inset["top"]) ?? 0), left: CGFloat(PNProps.double(inset["left"]) ?? 0),
+                bottom: CGFloat(PNProps.double(inset["bottom"]) ?? 0), right: CGFloat(PNProps.double(inset["right"]) ?? 0)
+            )
+            scroll.verticalScrollIndicatorInsets = insets
+            scroll.horizontalScrollIndicatorInsets = insets
+        }
+        if PNProps.has(props, "scroll_event_throttle") {
+            PNViewState.existing(for: scroll)?.extras["throttle"] = PNProps.double(PNProps.value(props, "scroll_event_throttle")) ?? 0
+        }
+    }
+
+    public override func command(view: UIView, name: String, args: [String: Any]) -> Any? {
+        guard let scroll = view as? UIScrollView else { return nil }
+        let animated = PNProps.bool(args["animated"]) ?? true
+        switch name {
+        case "scroll_to_offset":
+            let x = CGFloat(PNProps.finite(args["x"]))
+            let y = CGFloat(PNProps.finite(args["y"]))
+            scroll.setContentOffset(CGPoint(x: x, y: y), animated: animated)
+        case "scroll_to_end":
+            let content = scroll.contentSize
+            let bounds = scroll.bounds.size
+            let targetY = max(0, content.height - bounds.height)
+            let targetX = max(0, content.width - bounds.width)
+            let horizontal = content.width > bounds.width && content.height <= bounds.height
+            scroll.setContentOffset(horizontal ? CGPoint(x: targetX, y: 0) : CGPoint(x: 0, y: targetY), animated: animated)
+        case "get_scroll_offset":
+            return ["x": Double(scroll.contentOffset.x), "y": Double(scroll.contentOffset.y)]
+        case "flash_scroll_indicators":
+            scroll.flashScrollIndicators()
+        default:
+            break
+        }
+        return nil
+    }
+
+    // MARK: - Refresh control
+
+    private func applyRefresh(_ scroll: UIScrollView, _ spec: Any?) {
+        guard let spec = spec else {
+            if let existing = scroll.refreshControl {
+                existing.endRefreshing()
+                scroll.refreshControl = nil
+                scroll.alwaysBounceVertical = false
+            }
+            return
+        }
+        let control: UIRefreshControl
+        if let existing = scroll.refreshControl {
+            control = existing
+        } else {
+            control = UIRefreshControl()
+            scroll.refreshControl = control
+            // Content that fits its bounds never engages the pan gesture
+            // without this, making the refresh control unreachable.
+            scroll.alwaysBounceVertical = true
+            let target = PNActionTarget { [weak scroll] in
+                guard let scroll = scroll else { return }
+                PNEvents.emit(scroll, "on_refresh")
+            }
+            control.addTarget(target, action: #selector(PNActionTarget.fire(_:forEvent:)), for: .valueChanged)
+            PNViewState.existing(for: scroll)?.retained.append(target)
+        }
+        let dict = spec as? [String: Any] ?? [:]
+        if let color = PNColor.parse(PNProps.value(dict, "tint_color") ?? PNProps.value(dict, "color")) {
+            control.tintColor = color
+        }
+        if let title = PNProps.string(PNProps.value(dict, "title")) {
+            control.attributedTitle = NSAttributedString(string: title)
+        }
+        if PNProps.bool(dict["refreshing"]) == true {
+            if !control.isRefreshing { control.beginRefreshing() }
+        } else if control.isRefreshing {
+            control.endRefreshing()
+        }
+    }
+}
+
+/// Shared scroll payload builder.
+enum PNScrollPayload {
+    static func make(_ scroll: UIScrollView) -> [String: Any] {
+        let offset = scroll.contentOffset
+        let bounds = scroll.bounds.size
+        let content = scroll.contentSize
+        let horizontal = content.width > bounds.width && content.height <= bounds.height
+        return [
+            "x": Double(offset.x),
+            "y": Double(offset.y),
+            "extent": Double(horizontal ? bounds.width : bounds.height),
+            "range": Double(horizontal ? content.width : content.height),
+            "content_width": Double(content.width),
+            "content_height": Double(content.height),
+            "width": Double(bounds.width),
+            "height": Double(bounds.height),
+        ]
+    }
+}
+
+/// Forwards `UIScrollViewDelegate` callbacks to Python events.
+final class PNScrollDelegate: NSObject, UIScrollViewDelegate {
+    private var lastEmit: TimeInterval = 0
+
+    func scrollViewDidScroll(_ scrollView: UIScrollView) {
+        guard let state = PNViewState.existing(for: scrollView), state.hasEvent("on_scroll") else { return }
+        let throttle = (state.extras["throttle"] as? Double ?? 0) / 1000
+        let now = CACurrentMediaTime()
+        if throttle > 0, now - lastEmit < throttle, scrollView.isDragging || scrollView.isDecelerating { return }
+        lastEmit = now
+        PNEvents.emit(scrollView, "on_scroll", [PNScrollPayload.make(scrollView)])
+    }
+
+    func scrollViewWillBeginDragging(_ scrollView: UIScrollView) {
+        PNEvents.emitIfWired(scrollView, "on_scroll_begin_drag", [PNScrollPayload.make(scrollView)])
+    }
+
+    func scrollViewDidEndDragging(_ scrollView: UIScrollView, willDecelerate decelerate: Bool) {
+        PNEvents.emitIfWired(scrollView, "on_scroll_end_drag", [PNScrollPayload.make(scrollView)])
+        if !decelerate {
+            PNEvents.emitIfWired(scrollView, "on_momentum_scroll_end", [PNScrollPayload.make(scrollView)])
+        }
+    }
+
+    func scrollViewDidEndDecelerating(_ scrollView: UIScrollView) {
+        PNEvents.emitIfWired(scrollView, "on_momentum_scroll_end", [PNScrollPayload.make(scrollView)])
+    }
+
+    func scrollViewDidEndScrollingAnimation(_ scrollView: UIScrollView) {
+        PNEvents.emitIfWired(scrollView, "on_scroll", [PNScrollPayload.make(scrollView)])
+    }
+}