feat(react-native): name UIKit views and surface callback errors

NativeScript/ffi/shared/jsi/NativeApiJsiBridge.h

@@ -2,6 +2,7 @@ thread_local bool gDispatchNativeCallsToUI = false;
 thread_local bool gExecutingDispatchedUINativeCall = false;
 thread_local int gSynchronousNativeInvocationDepth = 0;
 thread_local int gNativeCallerThreadJsiCallbackDepth = 0;
+thread_local std::vector<std::string*> gNativeCallbackExceptionCaptureStack;
 std::atomic<int> gActiveSynchronousNativeInvocationDepth{0};
 
 class ScopedNativeApiUINativeCallDispatch final {
@@ -54,14 +55,56 @@ class ScopedNativeCallerThreadJsiCallback final {
       const ScopedNativeCallerThreadJsiCallback&) = delete;
 };
 
+class ScopedNativeCallbackExceptionCapture final {
+ public:
+  explicit ScopedNativeCallbackExceptionCapture(std::string* message)
+      : message_(message) {
+    gNativeCallbackExceptionCaptureStack.push_back(message_);
+  }
+
+  ~ScopedNativeCallbackExceptionCapture() {
+    if (!gNativeCallbackExceptionCaptureStack.empty() &&
+        gNativeCallbackExceptionCaptureStack.back() == message_) {
+      gNativeCallbackExceptionCaptureStack.pop_back();
+    }
+  }
+
+  ScopedNativeCallbackExceptionCapture(
+      const ScopedNativeCallbackExceptionCapture&) = delete;
+  ScopedNativeCallbackExceptionCapture& operator=(
+      const ScopedNativeCallbackExceptionCapture&) = delete;
+
+ private:
+  std::string* message_ = nullptr;
+};
+
+bool recordNativeCallbackException(const std::string& message) {
+  if (gNativeCallbackExceptionCaptureStack.empty()) {
+    return false;
+  }
+
+  std::string* captured = gNativeCallbackExceptionCaptureStack.back();
+  if (captured == nullptr) {
+    return false;
+  }
+
+  if (captured->empty()) {
+    *captured = message;
+  }
+  return true;
+}
+
 template <typename Invocation>
 void performNativeInvocation(Runtime& runtime,
                              const std::function<void(std::function<void()>)>&
                                  invoker,
                              Invocation&& invocation) {
   NSString* exceptionDescription = nil;
+  std::string callbackException;
   auto run = [&]() {
     ScopedNativeApiSynchronousInvocation synchronousInvocation;
+    ScopedNativeCallbackExceptionCapture callbackExceptionCapture(
+        &callbackException);
     @try {
       invocation();
     } @catch (NSException* exception) {
@@ -92,6 +135,9 @@ void performNativeInvocation(Runtime& runtime,
     [exceptionDescription release];
     throw facebook::jsi::JSError(runtime, message);
   }
+  if (!callbackException.empty()) {
+    throw facebook::jsi::JSError(runtime, callbackException);
+  }
 }
 
 enum class NativeApiSymbolKind {

NativeScript/ffi/shared/jsi/NativeApiJsiCallbacks.h

@@ -478,7 +478,9 @@ class NativeApiJsiCallback final
     }
 
     if (!error.empty()) {
-      throwNativeApiJsiCallbackException(error);
+      if (!recordNativeCallbackException(error)) {
+        throwNativeApiJsiCallbackException(error);
+      }
     }
   }
 
@@ -665,7 +667,18 @@ void nativeApiJsiCallbackTrampoline(ffi_cif*, void* ret, void* args[],
   if (callback == nullptr) {
     return;
   }
-  callback->invoke(ret, args);
+  @try {
+    callback->invoke(ret, args);
+  } @catch (NSException* exception) {
+    const char* description =
+        exception.description != nil ? exception.description.UTF8String : nullptr;
+    std::string message = description != nullptr
+                              ? description
+                              : "Objective-C exception in native JSI callback.";
+    if (!recordNativeCallbackException(message)) {
+      @throw;
+    }
+  }
 }
 
 size_t nativeSizeForType(const NativeApiJsiType& type) {

packages/react-native/README.md

@@ -47,7 +47,7 @@ type BadgeProps = {
 };
 
 export const NativeBadge = defineUIKitView<BadgeProps, UIView>({
-  displayName: "NativeBadge",
+  name: "NativeBadge",
   create() {
     const view = UIView.alloc().initWithFrame(CGRectZero);
     const label = UILabel.alloc().initWithFrame(CGRectZero);
@@ -85,7 +85,10 @@ await badgeRef.current?.runOnUI((view) => {
 React Native view props such as `style`, `testID`, accessibility props, responder
 props, and `pointerEvents` go to the host component. Your own props go to the
 UIKit definition; use `nativeProps(props)` when a plugin prop should also affect
-the RN host.
+the RN host. The `name` option is forwarded to the shared native host view as a
+debug name, so native view descriptions can show `NativeScriptUIView` with your
+definition name. It does not dynamically change the registered RN host component
+tag.
 
 The published package includes generated NativeScript metadata, the libffi
 xcframework, and generated iOS SDK TypeScript declarations. Build it from the
@@ -173,6 +176,7 @@ Expo development build, EAS Build, or `npx expo run:ios`.
    NativeScript.init();
 
    const NativeBadge = defineUIKitView<{title: string}, UIView>({
+     name: "NativeBadge",
      create() {
        const view = UIView.alloc().initWithFrame(CGRectZero);
        const label = UILabel.alloc().initWithFrame(CGRectZero);

packages/react-native/ios/Fabric/NativeScriptUIViewComponentView.mm

@@ -10,6 +10,7 @@
 
 @implementation NativeScriptUIViewComponentView {
   NativeScriptUIView* _containerView;
+  NSString* _debugName;
 }
 
 - (instancetype)initWithFrame:(CGRect)frame {
@@ -27,18 +28,42 @@ - (instancetype)initWithFrame:(CGRect)frame {
 }
 
 - (void)dealloc {
+  [_debugName release];
   [_containerView release];
   [super dealloc];
 }
 
+- (NSString*)description {
+  if (_debugName.length == 0) {
+    return [super description];
+  }
+
+  NSString* description = [super description];
+  if ([description hasSuffix:@">"]) {
+    return [[description substringToIndex:description.length - 1]
+        stringByAppendingFormat:@"; debugName = %@>", _debugName];
+  }
+  return [description stringByAppendingFormat:@" debugName = %@", _debugName];
+}
+
 - (void)updateProps:(Props::Shared const&)props oldProps:(Props::Shared const&)oldProps {
   const auto oldViewProps = std::static_pointer_cast<const NativeScriptUIViewProps>(_props);
   const auto newViewProps = std::static_pointer_cast<const NativeScriptUIViewProps>(props);
   const std::string oldNativeViewHandle = oldViewProps->nativeViewHandle;
   const std::string newNativeViewHandle = newViewProps->nativeViewHandle;
+  const std::string oldDebugName = oldViewProps->debugName;
+  const std::string newDebugName = newViewProps->debugName;
 
   [super updateProps:props oldProps:oldProps];
 
+  if (oldDebugName != newDebugName) {
+    NSString* debugName =
+        newDebugName.empty() ? nil : [NSString stringWithUTF8String:newDebugName.c_str()];
+    [_debugName release];
+    _debugName = [debugName copy];
+    _containerView.debugName = debugName;
+  }
+
   if (oldNativeViewHandle != newNativeViewHandle) {
     NSString* nativeViewHandle = newNativeViewHandle.empty()
                                      ? nil
@@ -49,6 +74,9 @@ - (void)updateProps:(Props::Shared const&)props oldProps:(Props::Shared const&)o
 
 - (void)prepareForRecycle {
   [super prepareForRecycle];
+  [_debugName release];
+  _debugName = nil;
+  _containerView.debugName = nil;
   _containerView.nativeViewHandle = nil;
 }
 

packages/react-native/ios/NativeScriptUIView.h

@@ -3,5 +3,6 @@
 @interface NativeScriptUIView : UIView
 
 @property(nonatomic, copy) NSString* nativeViewHandle;
+@property(nonatomic, copy) NSString* debugName;
 
 @end

packages/react-native/ios/NativeScriptUIView.mm

@@ -32,6 +32,7 @@ - (void)dealloc {
   [_nativeView removeFromSuperview];
   [_nativeView release];
   [_nativeViewHandle release];
+  [_debugName release];
   [super dealloc];
 }
 
@@ -46,6 +47,28 @@ - (void)setNativeViewHandle:(NSString*)nativeViewHandle {
   [self setNativeView:NativeScriptUIViewFromHandle(_nativeViewHandle)];
 }
 
+- (void)setDebugName:(NSString*)debugName {
+  if ((_debugName == debugName) || [_debugName isEqualToString:debugName]) {
+    return;
+  }
+
+  [_debugName release];
+  _debugName = [debugName copy];
+}
+
+- (NSString*)description {
+  if (_debugName.length == 0) {
+    return [super description];
+  }
+
+  NSString* description = [super description];
+  if ([description hasSuffix:@">"]) {
+    return [[description substringToIndex:description.length - 1]
+        stringByAppendingFormat:@"; debugName = %@>", _debugName];
+  }
+  return [description stringByAppendingFormat:@" debugName = %@", _debugName];
+}
+
 - (void)setNativeView:(UIView*)nativeView {
   if (_nativeView == nativeView) {
     return;

packages/react-native/ios/NativeScriptUIViewManager.mm

@@ -14,5 +14,6 @@ - (UIView*)view {
 }
 
 RCT_EXPORT_VIEW_PROPERTY(nativeViewHandle, NSString)
+RCT_EXPORT_VIEW_PROPERTY(debugName, NSString)
 
 @end

packages/react-native/src/NativeScriptUIViewNativeComponent.ts

@@ -3,6 +3,7 @@ import codegenNativeComponent from 'react-native/Libraries/Utilities/codegenNati
 
 export interface NativeProps extends ViewProps {
   nativeViewHandle?: string;
+  debugName?: string;
 }
 
 export default codegenNativeComponent<NativeProps>(

packages/react-native/src/index.d.ts

@@ -38,6 +38,21 @@ export type InstallOptions = {
 };
 
 export type UIKitViewDefinition<Props extends object, NativeView = unknown> = {
+  /**
+   * Human-readable name for this UIKit view definition. This names the JS
+   * wrapper when displayName is omitted and is forwarded to the shared native
+   * host view as a debug name. It does not change the RN host component tag.
+   */
+  name?: string;
+  /**
+   * Explicit native debug name for the shared host view. Use this when the
+   * native inspector name should differ from the JS wrapper displayName.
+   */
+  debugName?: string;
+  /**
+   * React component display name. When name/debugName are omitted, this is also
+   * used as the native debug name.
+   */
   displayName?: string;
   create: (props: Readonly<Props & ViewProps>) => NativeView;
   update?: (

packages/react-native/src/index.ts

@@ -36,6 +36,8 @@ export type InstallOptions = {
 };
 
 export type UIKitViewDefinition<Props extends object, NativeView = unknown> = {
+  name?: string;
+  debugName?: string;
   displayName?: string;
   create: (props: Readonly<Props & ViewProps>) => NativeView;
   update?: (
@@ -680,6 +682,12 @@ export function runOnUI(callback?: () => void): Promise<void> {
 export function defineUIKitView<Props extends object, NativeView = unknown>(
   definition: UIKitViewDefinition<Props, NativeView>,
 ): UIKitViewComponent<Props, NativeView> {
+  const debugName =
+    definition.debugName
+    || definition.name
+    || definition.displayName
+    || 'NativeScriptUIKitView';
+
   const Component = forwardRef<UIKitViewRef<NativeView>, Props & ViewProps>(
     function NativeScriptUIKitView(props, ref) {
       const {nativeProps, pluginProps} = splitUIKitViewProps(props, definition);
@@ -804,12 +812,13 @@ export function defineUIKitView<Props extends object, NativeView = unknown>(
       return React.createElement(NativeScriptUIViewNativeComponent, {
         ...nativeProps,
         collapsable: false,
+        debugName,
         nativeViewHandle,
       });
     },
   );
 
-  Component.displayName = definition.displayName ?? 'NativeScriptUIKitView';
+  Component.displayName = definition.displayName || definition.name || debugName;
   return Component;
 }
 

test/react-native/ffi-compat/App.tsx

@@ -625,7 +625,7 @@ const NativeScriptUIKitTestView = defineUIKitView<{
   title: string;
   tint: 'blue' | 'green';
 }>({
-  displayName: 'NativeScriptUIKitTestView',
+  name: 'NativeScriptUIKitTestView',
   create(props) {
     const view = g('UIView').alloc().initWithFrame(
       new (g('CGRect'))({
@@ -789,6 +789,10 @@ function buildReactNativeIntegrationTests(): TestCase[] {
         await NativeScript.runOnUI(() => {
           const view = (globalThis as any).__nativeScriptUIKitPlugin?.view;
           assert(view?.superview, 'JS-defined UIKit view has no host superview');
+          assert(
+            String(view.superview.description).includes('NativeScriptUIKitTestView'),
+            'JS-defined UIKit host did not expose its debug name',
+          );
           assert(view?.window, 'JS-defined UIKit view has no window');
           const label = view.viewWithTag(uikitPluginLabelTag);
           assertEqual(label.text, 'Initial UIKit title', 'initial UIKit label text');

test/runtime/runner/app/tests/Marshalling/ObjCTypesTests.js

@@ -96,6 +96,20 @@ describe(module.id, function () {
         expect(actual).toBe("simple block called");
     });
 
+    it("Block callback JS error propagates to the native caller", function () {
+        var error;
+        try {
+            TNSObjCTypes.alloc().init().methodWithSimpleBlock(function () {
+                throw new Error("block callback failed");
+            });
+        } catch (e) {
+            error = e;
+        }
+
+        expect(error).toBeDefined();
+        expect(String(error && error.message ? error.message : error)).toContain("block callback failed");
+    });
+
     it("Block releases after call", function (done) {
         const functionRef = new WeakRef(function () {
             TNSLog('simple block called');