react-nitro-renderer 0.0.0-stage → 0.0.1-alpha.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Margelo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Package.swift

@@ -0,0 +1,104 @@
+// swift-tools-version: 6.4
+
+import Foundation
+import PackageDescription
+
+let name = "ReactNitroRenderer"
+let generated = "nitrogen/generated"
+let nitroDependencies: [Target.Dependency] = [
+  .product(name: "NitroModules", package: "nitro-core"),
+  .product(name: "Yoga", package: "react-nitro-yoga"),
+]
+let cxxSettings: [CXXSetting] = [
+  .define("DEBUG", .when(configuration: .debug)),
+  .define("NDEBUG", .when(configuration: .release)),
+  .disableWarning("nullability-extension"),
+]
+let swiftSources = ["Sources/ReactNitroRenderer", "\(generated)/apple/swift"]
+let bridgeSources = [
+  "c++", "ReactNitroRenderer-Swift-Cxx-Bridge.cpp", "ReactNitroRendererAutolinking.cpp",
+]
+
+// Bare-host integration. Nitrogen generates the bindings; this manifest owns the targets.
+let package = Package(
+  name: name,
+  platforms: [.iOS(.v16), .macOS(.v13)],
+  products: [
+    .library(name: name, targets: ["\(name)Cxx", name, "\(name)SwiftBridge"])
+  ],
+  dependencies: [
+    .package(path: "../nitro-core"),
+    .package(path: "../react-nitro-yoga"),
+  ],
+  targets: [
+    .target(
+      name: "\(name)Cxx",
+      dependencies: nitroDependencies,
+      path: "\(generated)/shared/c++",
+      exclude: ["include"],
+      publicHeadersPath: "include",
+      cxxSettings: cxxSettings
+    ),
+    .target(
+      name: "\(name)AppleCxx",
+      dependencies: [.target(name: "\(name)Cxx")] + nitroDependencies,
+      path: "\(generated)/apple/\(name)AppleCxx",
+      cxxSettings: cxxSettings
+    ),
+    .target(
+      name: name,
+      dependencies: [.target(name: "\(name)AppleCxx")] + nitroDependencies,
+      path: ".",
+      exclude: excludes(in: ".", keeping: swiftSources),
+      sources: swiftSources,
+      cxxSettings: cxxSettings,
+      swiftSettings: [
+        // UIKit implementations run synchronously on the host's main thread.
+        .swiftLanguageMode(.v5),
+        .unsafeFlags(["-strict-concurrency=minimal"]),
+        .enableUpcomingFeature("InternalImportsByDefault"),
+        .enableUpcomingFeature("MemberImportVisibility"),
+        .interoperabilityMode(.Cxx),
+        .unsafeFlags(["-Xfrontend", "-clang-header-expose-decls=has-expose-attr-or-stdlib"]),
+        .unsafeFlags([
+          "-Xfrontend", "-clang-header-expose-module",
+          "-Xfrontend", "NitroModules=NitroModules-Swift.h",
+        ]),
+      ]
+    ),
+    .target(
+      name: "\(name)SwiftBridge",
+      dependencies: [.target(name: name), .target(name: "\(name)AppleCxx")] + nitroDependencies,
+      path: "\(generated)/apple",
+      exclude: excludes(in: "\(generated)/apple", keeping: bridgeSources) + ["c++/include"],
+      sources: bridgeSources,
+      publicHeadersPath: "c++/include",
+      cxxSettings: cxxSettings + [
+        .unsafeFlags(["-I${GENERATED_MODULEMAP_DIR}", "-fno-modules"])
+      ]
+    ),
+  ],
+  cxxLanguageStandard: .cxx20
+)
+
+func excludes(in path: String, keeping sources: [String]) -> [String] {
+  var parents: Set<String> = [""]
+  for source in sources {
+    var components = source.split(separator: "/").dropLast()
+    while !components.isEmpty {
+      parents.insert(components.joined(separator: "/"))
+      components = components.dropLast()
+    }
+  }
+  let root = URL(fileURLWithPath: Context.packageDirectory).appendingPathComponent(path)
+  return parents.sorted().flatMap { parent in
+    let entries =
+      (try? FileManager.default.contentsOfDirectory(
+        atPath: root.appendingPathComponent(parent).path)) ?? []
+    return entries.sorted().compactMap { entry in
+      let entryPath = parent.isEmpty ? entry : "\(parent)/\(entry)"
+      return entry.hasPrefix(".") || sources.contains(entryPath) || parents.contains(entryPath)
+        ? nil : entryPath
+    }
+  }
+}

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# React Nitro Renderer
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Install JavaScript dependencies from the repository root with `bun install`.
+
+The JavaScript package exports React components such as `View` and `Text`, rendering
+functions, and `registerApp`. For a standard app, register the root component:
+
+```tsx
+import { registerApp } from 'react-nitro-renderer'
+import { App } from './App'
+
+registerApp(App)
+```
+
+The renderer initializes runtime globals before loading its rendering dependencies.
+`registerApp` creates a native window and renders the component for each scene.
+
+For custom window setup, use `Application`, `ViewController`, `Window` and
+`WindowScene`. Register the root callback with `Application.registerRoot`, then
+create the view controller and window:
+
+```tsx
+import { Application, renderRoot, ViewController, Window } from "react-nitro-renderer";
+
+Application.registerRoot((scene) => {
+  const viewController = new ViewController();
+  renderRoot(<App />, viewController);
+  return new Window(scene, viewController);
+});
+```
+
+React roots provide `useSafeAreaInsets()`, which subscribes to the closest
+view controller's root view and returns its insets in points:
+
+```tsx
+function App() {
+  const insets = useSafeAreaInsets();
+  return (
+    <View layout={{ flex: 1, paddingTop: insets.top, paddingBottom: insets.bottom }}>
+      <Text>Inside the safe area</Text>
+    </View>
+  );
+}
+```
+
+The hook is exported from `react-nitro-renderer` and throws outside a React
+Nitro root. Every native view exposes `safeAreaInsets`, including `viewController.view`.
+Insets are relative to that view's bounds, so a view entirely inside its parent's
+safe area reports zero. The controller's
+`addOnSafeAreaInsetsChangedListener(listener)` observes its root view. Call
+`remove()` on the returned subscription when it is no longer needed.
+
+Scale and translation are flat style props:
+
+```tsx
+<View style={{ scale: 1.2, scaleX: 1.5, translateX: 20 }} />
+```
+
+`scale` defaults to `1` and sets all three axes. `scaleX`, `scaleY`, and `scaleZ`
+override their respective axes. Scaling preserves
+translation and does not change Yoga layout dimensions. Native view refs expose
+`setScale(x, y, z)` and a readonly `scale` value with `x`, `y`, and `z` fields.
+
+On iOS, exact zero scale values are applied as `0.00001` to avoid a UIKit/Core
+Animation bug that can make a view disappear immediately during an exit animation.
+This applies to all scale style props and `setScale`; the `scale` getter returns
+the applied values. Other finite scale values are preserved. Use `opacity: 0`
+when the view must be fully transparent.
+
+Public reports describe [zero-scale transform interpolation failures](https://stackoverflow.com/questions/25964224/cgaffinetransformscale-not-working-with-zero-scale)
+and [immediate disappearance when animating to zero](https://stackoverflow.com/questions/75793513/uiview-animation-downscale-instantly-hides-the-view).
+
+## Native renderer
+
+The Swift package exposes the `ReactNitroRenderer` library and depends on the
+local `../nitro-core` and `../react-nitro-yoga` packages. The core package builds
+native sources copied from the pinned `nitro-core` dependency installed by `bun install`.
+Add Swift sources under
+`Sources/ReactNitroRenderer/` and use `import NitroModules` to access
+Nitro's Swift types. C++ interoperability is enabled for Nitro's C++-backed types.
+
+`Package.swift` owns the standalone host targets. Nitrogen generates their
+bindings from specs configured with `"environment": "bare"`:
+
+- `ReactNitroRendererCxx`: `nitrogen/generated/shared/c++`.
+- `ReactNitroRendererAppleCxx`: the generated C++ bridge declarations.
+- `ReactNitroRenderer`: handwritten Swift and `nitrogen/generated/apple/swift`.
+- `ReactNitroRendererSwiftBridge`: `nitrogen/generated/apple/c++`, the generated bridge implementation, and the public autolinking API.
+
+The `ReactNitroRenderer` product includes both the Swift module and its C++ wrappers.
+Generated Swift imports `ReactNitroRendererAppleCxx` explicitly. Regenerate
+bindings with `bun run specs` after changing specs or updating Nitrogen.
+
+Register the generated HybridObject classes before using their JavaScript classes:
+
+```cpp
+#include <ReactNitroRenderer/ReactNitroRendererAutolinking.hpp>
+
+margelo::nitro::renderer::registerHybridClasses();
+```
+
+Build the Swift package from this directory:
+
+```bash
+swift build
+```
+
+Use Swift 6.4's default Swift Build backend (or Xcode). The C++ wrappers use its
+`GENERATED_MODULEMAP_DIR` to include Swift's generated header after the C++ types
+it references; importing that header as an isolated Clang module loses those types.
+
+Generate native bindings from the TypeScript specs with `bun run specs`.

package/Sources/ReactNitroRenderer/Animations/AnimationCurve+toUIAnimationCurve.swift

@@ -0,0 +1,31 @@
+internal import UIKit
+
+extension AnimationCurve {
+  init(_ uiAnimationCurve: UIView.AnimationCurve) {
+    switch uiAnimationCurve {
+    case .linear:
+      self = .linear
+    case .easeIn:
+      self = .easein
+    case .easeOut:
+      self = .easeout
+    case .easeInOut:
+      self = .easeinout
+    @unknown default:
+      preconditionFailure("Unknown animation curve: \(uiAnimationCurve.rawValue)")
+    }
+  }
+
+  func toUIAnimationCurve() -> UIView.AnimationCurve {
+    switch self {
+    case .linear:
+      return .linear
+    case .easein:
+      return .easeIn
+    case .easeout:
+      return .easeOut
+    case .easeinout:
+      return .easeInOut
+    }
+  }
+}

package/Sources/ReactNitroRenderer/Animations/HybridAnimator.swift

@@ -0,0 +1,36 @@
+//
+//  HybridAnimator.swift
+//  ReactNitroRenderer
+//
+//  Created by Hanno Gödecke on 21.10.2026.
+//
+
+internal import NitroModules
+import UIKit
+
+class HybridAnimator : HybridAnimatorSpec {
+  var animator: UIViewPropertyAnimator
+  
+  init(animator: UIViewPropertyAnimator) throws {
+    self.animator = animator
+    try super.init()
+  }
+  
+  func startAnimation(afterDelay: Double?) throws {
+    guard let delay = afterDelay else {
+      animator.startAnimation()
+      return
+    }
+    animator.startAnimation(afterDelay: delay)
+  }
+  
+  func pauseAnimation() throws {
+    animator.pauseAnimation()
+  }
+  
+  func stopAnimation(withoutFinishing: Bool?) throws {
+    animator.stopAnimation(withoutFinishing ?? false)
+  }
+  
+  
+}

package/Sources/ReactNitroRenderer/Animations/View+Animations.swift

@@ -0,0 +1,39 @@
+//
+//  View+animations.swift
+//  ReactNitroRenderer
+//
+//  Created by Hanno Gödecke on 21.10.2026.
+//
+
+import UIKit
+public import NitroModules
+internal import NitroModulesCxx
+
+public extension View where Self: HybridViewSpec {
+  func animate(duration: Double, curve: AnimationCurve, animations: any NitroModules.Callback<(), Void>) throws -> any HybridAnimatorSpec {
+    let uiCurve = curve.toUIAnimationCurve()
+    let animator = UIViewPropertyAnimator(duration: duration, curve: uiCurve) {
+      do {
+        try animations.callSync()
+      } catch {
+        let cppError = error.toCpp()
+        margelo.nitro.GlobalErrorHandler.reportError(.UICallback, cppError)
+      }
+    }
+    
+    return try HybridAnimator(animator: animator)
+  }
+  
+  func animateSpring(duration: Double, dampingRatio: Double, animations: any NitroModules.Callback<(), Void>) throws -> any HybridAnimatorSpec {
+    let animator = UIViewPropertyAnimator(duration: duration, dampingRatio: dampingRatio) {
+      do {
+        try animations.callSync()
+      } catch {
+        let cppError = error.toCpp()
+        margelo.nitro.GlobalErrorHandler.reportError(.UICallback, cppError)
+      }
+    }
+    
+    return try HybridAnimator(animator: animator)
+  }
+}

package/Sources/ReactNitroRenderer/Components/HybridLabel.swift

@@ -0,0 +1,89 @@
+internal import NitroModules
+internal import UIKit
+internal import yoga
+
+final class HybridLabel: HybridLabelSpec {
+  typealias AllowedChildrenType = Never
+
+  let view: LabelView
+  let yogaNode: YGNode
+  var parentReference: (any HybridViewSpec)?
+
+  override init() throws {
+    let label = LabelView()
+    view = label
+    
+    yogaNode = YGNode(measure: { width, widthMode, height, heightMode in
+      let availableWidth = widthMode == .undefined
+        ? CGFloat.greatestFiniteMagnitude
+        : CGFloat(width)
+      let availableHeight = heightMode == .undefined
+        ? CGFloat.greatestFiniteMagnitude
+        : CGFloat(height)
+      let availableSize = CGSize(width: availableWidth, height: availableHeight)
+      let measuredSize = label.sizeThatFits(availableSize)
+      var measuredWidth = Float(measuredSize.width)
+      var measuredHeight = Float(measuredSize.height)
+
+      if widthMode == .exactly {
+        measuredWidth = width
+      } else if widthMode == .atMost {
+        measuredWidth = min(measuredWidth, width)
+      }
+
+      if heightMode == .exactly {
+        measuredHeight = height
+      } else if heightMode == .atMost {
+        measuredHeight = min(measuredHeight, height)
+      }
+
+      return YGSize(width: measuredWidth, height: measuredHeight)
+    })
+    try super.init()
+  }
+
+  func setFrame(frame: Frame) throws {
+    // setFrame gets called when we are done calculating the layout
+    // For the text content we have to consider any insets, which we are applying here
+    let top = contentInset(for: .top)
+    let left = contentInset(for: .left)
+    let bottom = contentInset(for: .bottom)
+    let right = contentInset(for: .right)
+    view.contentInsets = UIEdgeInsets(top: top, left: left, bottom: bottom, right: right)
+    view.bounds.size = CGSize(width: frame.width, height: frame.height)
+    view.center = CGPoint(x: frame.x + frame.width / 2,
+                          y: frame.y + frame.height / 2)
+  }
+
+  private func contentInset(for edge: YGEdge) -> CGFloat {
+    let border = YGNodeLayoutGetBorder(yogaNode.ref, edge)
+    let padding = YGNodeLayoutGetPadding(yogaNode.ref, edge)
+    let inset = border + padding
+    return CGFloat(inset)
+  }
+  
+  var text: String? {
+    get {
+      return view.text
+    }
+    set {
+      guard view.text != newValue else { return }
+      view.text = newValue
+      YGNodeMarkDirty(yogaNode.ref)
+    }
+  }
+}
+
+final class LabelView: UILabel {
+  var contentInsets: UIEdgeInsets = .zero {
+    didSet {
+      guard contentInsets != oldValue else { return }
+      setNeedsDisplay()
+    }
+  }
+
+  override func drawText(in rect: CGRect) {
+    let contentRect = rect.inset(by: contentInsets)
+    super.drawText(in: contentRect)
+  }
+}

package/Sources/ReactNitroRenderer/Components/HybridScrollView.swift

@@ -0,0 +1,21 @@
+//
+//  HybridScrollView.swift
+//  ReactNitroRenderer
+//
+//  Created by Hanno Gödecke on 29.09.2026.
+//
+// .contentSize is set by HybridScrollViewContent
+
+import Foundation
+import UIKit
+import yoga
+import NitroModules
+
+final class HybridScrollView: HybridScrollViewSpec {
+  typealias AllowedChildrenType = any ScrollViewContent
+
+  let view = UIScrollView();
+
+  let yogaNode: YGNode = YGNode()
+  var parentReference: (any HybridViewSpec)?
+}

package/Sources/ReactNitroRenderer/Components/HybridScrollViewContent.swift

@@ -0,0 +1,36 @@
+//
+//  HybridScrollViewContent.swift
+//  ReactNitroRenderer
+//
+//  Created by Hanno Gödecke on 29.09.2026.
+//
+//  This is expected to be the one and only child of HybridScrollView.
+//  It will contain all the ScrollView's content, and will report its size
+//  to the UIScrollView as contentSize. This is what makes it scroll, as the
+//  content size will be larger than the UIScrollView's bounds.
+//
+
+
+import UIKit
+import yoga
+import NitroModules
+
+protocol ScrollViewContent: View {}
+
+final class HybridScrollViewContent: HybridScrollViewContentSpec, ScrollViewContent {
+  typealias AllowedChildrenType = any View
+
+  let view = UIView()
+  let yogaNode = YGNode()
+  var parentReference: (any HybridViewSpec)?
+
+  func setFrame(frame: Frame) throws {
+    guard let parent, let scrollView = parent.view as? UIScrollView else {
+      throw RuntimeError("<ScrollViewContent> must be the direct and only child of <ScrollView>!")
+    }
+    view.bounds.size = CGSize(width: frame.width, height: frame.height)
+    view.center = CGPoint(x: frame.x + frame.width / 2,
+                          y: frame.y + frame.height / 2)
+    scrollView.contentSize = view.bounds.size
+  }
+}

package/Sources/ReactNitroRenderer/Components/HybridView.swift

@@ -0,0 +1,22 @@
+internal import NitroModules
+internal import UIKit
+
+final class HybridView: HybridViewSpec {
+  typealias AllowedChildrenType = any View
+
+  let yogaNode = YGNode()
+  var parentReference: (any HybridViewSpec)?
+  
+  let view: UIView
+  
+  override convenience init() throws {
+    let view = UIView()
+    self.init(view: view)
+  }
+  
+  init(view: UIView) {
+    self.view = view
+    // The generated base initializer is empty. Wrapping this UIKit object cannot fail.
+    try! super.init()
+  }
+}