feat(react-native): add UIKit adapter APIs

Author: DjDeveloperr

packages/react-native/README.md

@@ -112,6 +112,9 @@ const badgeRef = useRef<UIKitViewRef<UIView>>(null);
 await badgeRef.current?.runOnUI((view) => {
   view.alpha = 0.8;
 });
+
+const measured = await badgeRef.current?.measureNative();
+badgeRef.current?.invalidateNativeLayout();
 ```
 
 React Native view props such as `style`, `testID`, accessibility props, responder
@@ -122,6 +125,118 @@ debug name, so native view descriptions can show `NativeScriptUIView` with your
 definition name. It does not dynamically change the registered RN host component
 tag.
 
+### Lifecycle and context
+
+`create`, `update`, `mounted`, and `dispose` run through the UIKit path. You do
+not need to wrap UIKit work in `runOnUI()` inside those callbacks.
+
+The first argument to `create` is also the current props object, so existing
+`create(props)` definitions keep working. New code can use the context helpers:
+
+```tsx
+export const NativeSwitch = NativeScript.defineUIKitView<
+  {value: boolean; onValueChange?: (value: boolean) => void},
+  UISwitch
+>({
+  name: "NativeSwitch",
+  layout: {sizing: "intrinsic"},
+  create(ctx) {
+    const view = UISwitch.new();
+    ctx.targetAction(view, UIControlEvents.ValueChanged, () => {
+      ctx.emit("onValueChange", view.on);
+    });
+    return view;
+  },
+  update(view, props) {
+    if (view.on !== props.value) {
+      view.setOnAnimated(props.value, false);
+    }
+  },
+});
+```
+
+Context helpers cover common native view-manager patterns:
+
+- `ctx.emit(name, payload)` asynchronously calls the matching React prop.
+- `ctx.targetAction(control, events, callback)` retains and removes a target/action helper.
+- `ctx.delegate(object, protocol, implementation)` creates, assigns, and retains a delegate.
+- `ctx.notification(name, object, callback)` observes and removes notifications.
+- `ctx.observe(object, keyPath, callback)` observes and removes KVO.
+- `ctx.retain(value)` keeps native helper objects alive for the component lifetime.
+- `ctx.dispose(callback)` runs cleanup once, in reverse registration order.
+- `ctx.invalidateLayout()` schedules a fresh native measurement.
+
+### Layout
+
+React Native owns placement through Yoga. UIKit owns native behavior inside the
+placed rectangle. Use `layout.sizing` to opt into native measurement:
+
+- `fill`: fill the RN host bounds.
+- `intrinsic`: use `intrinsicContentSize`.
+- `sizeThatFits`: use `sizeThatFits` with style constraints.
+- `autoLayout`: use `systemLayoutSizeFittingSize`.
+
+Use `defaultSize`, `minSize`, and `maxSize` when a native view can report zero
+or needs bounds during the first layout pass.
+
+```tsx
+const NativeTitle = NativeScript.defineUIKitView<{text: string}, UILabel>({
+  name: "NativeTitle",
+  layout: {
+    sizing: "intrinsic",
+    defaultSize: {width: 1, height: 1},
+  },
+  create() {
+    return UILabel.new();
+  },
+  update(label, props, _previous, ctx) {
+    label.text = props.text;
+    ctx?.invalidateLayout();
+  },
+});
+```
+
+### Containers and view controllers
+
+Use `defineUIKitContainer()` when React Native children should mount inside a
+UIKit-owned content view:
+
+```tsx
+export const BlurCard = NativeScript.defineUIKitContainer({
+  name: "BlurCard",
+  create() {
+    const rootView = UIVisualEffectView.alloc().initWithEffect(
+      UIBlurEffect.effectWithStyle(UIBlurEffectStyle.SystemMaterial),
+    );
+    return {
+      rootView,
+      childrenView: rootView.contentView,
+    };
+  },
+});
+
+<BlurCard style={{padding: 16}}>
+  <Text>React Native child content</Text>
+</BlurCard>;
+```
+
+Use `defineUIViewController()` for APIs that require real child view-controller
+containment:
+
+```tsx
+export const NativePageHost = NativeScript.defineUIViewController({
+  name: "NativePageHost",
+  createController() {
+    return UIViewController.new();
+  },
+  update(controller) {
+    controller.view.backgroundColor = UIColor.systemBackgroundColor;
+  },
+});
+```
+
+The package ships example definitions under `@nativescript/react-native/examples`.
+
 The published package includes generated NativeScript metadata, the libffi
 xcframework, and generated iOS SDK TypeScript declarations. Build it from the
 repository root with:
@@ -239,3 +354,41 @@ Expo development build, EAS Build, or `npx expo run:ios`.
 
 Set `{ "babelPlugin": false }` in the config plugin options if you prefer to add
 the Babel plugin manually.
+
+The plugin also writes `nativescript.react-native.json` so metadata options are
+visible to native builds. You can pass metadata inputs when the app uses
+Objective-C-visible pods or extra system frameworks:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@nativescript/react-native",
+        {
+          "metadata": {
+            "includePods": ["SomeObjCSDK"],
+            "includeSystemFrameworks": ["UIKit", "MapKit", "WebKit"]
+          }
+        }
+      ]
+    ]
+  }
+}
+```
+
+## Bare React Native setup helper
+
+The tarball includes a small CLI for bare RN projects:
+
+```sh
+npx nativescript-rn configure
+npx nativescript-rn generate-metadata --check
+cd ios
+RCT_NEW_ARCH_ENABLED=1 USE_HERMES=1 pod install
+```
+
+`configure` adds the bundled Babel plugin when missing, writes
+`nativescript.react-native.json`, and warns when the app is not configured for
+Hermes and the New Architecture. The command is intentionally conservative and
+does not make destructive native project edits.

packages/react-native/cli/configure.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const {
+  ensureBabelPlugin,
+  ensureMetadataConfig,
+  normalizeMetadataOptions,
+} = require('../plugin/withNativeScriptReactNative');
+
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return undefined;
+  }
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function projectRoot() {
+  return process.cwd();
+}
+
+function printNextSteps() {
+  console.log('NativeScript React Native configuration checked.');
+  console.log('Next steps:');
+  console.log('  cd ios');
+  console.log('  RCT_NEW_ARCH_ENABLED=1 USE_HERMES=1 pod install');
+}
+
+function configure(argv = process.argv.slice(2)) {
+  const command = argv[0];
+  if (command === 'generate-metadata') {
+    require('./generate-metadata').generateMetadata(argv.slice(1));
+    return;
+  }
+  if (command && command !== 'configure') {
+    console.error(`Unknown command: ${command}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const root = projectRoot();
+  const packageJson = readJson(path.join(root, 'package.json'));
+  if (!packageJson) {
+    console.error('package.json was not found in the current directory.');
+    process.exitCode = 1;
+    return;
+  }
+
+  ensureBabelPlugin(root);
+  ensureMetadataConfig(root, normalizeMetadataOptions(packageJson.nativeScriptReactNative || {}));
+
+  const dependencies = {
+    ...(packageJson.dependencies || {}),
+    ...(packageJson.devDependencies || {}),
+  };
+  if (!dependencies['@nativescript/react-native']) {
+    console.warn('Warning: @nativescript/react-native is not listed in package.json dependencies.');
+  }
+
+  const iosPropertiesPath = path.join(root, 'ios', 'Podfile.properties.json');
+  const iosProperties = readJson(iosPropertiesPath);
+  if (iosProperties) {
+    if (iosProperties['expo.jsEngine'] && iosProperties['expo.jsEngine'] !== 'hermes') {
+      console.warn('Warning: iOS jsEngine is not Hermes.');
+    }
+    if (
+      iosProperties.newArchEnabled !== 'true' &&
+      iosProperties.newArchEnabled !== true
+    ) {
+      console.warn('Warning: React Native New Architecture is not enabled for iOS.');
+    }
+  }
+
+  printNextSteps();
+}
+
+if (require.main === module) {
+  configure();
+}
+
+module.exports = {
+  configure,
+};

packages/react-native/cli/generate-metadata.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+function readConfig(projectRoot) {
+  const configPath = path.join(projectRoot, 'nativescript.react-native.json');
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+  return JSON.parse(fs.readFileSync(configPath, 'utf8'));
+}
+
+function generateMetadata(argv = process.argv.slice(2)) {
+  const root = process.cwd();
+  const config = readConfig(root);
+  const metadata = config.reactNative?.metadata || {};
+  const includePods = metadata.includePods || [];
+  const includeSystemFrameworks = metadata.includeSystemFrameworks || [];
+
+  console.log('NativeScript React Native metadata configuration:');
+  console.log(`  project: ${root}`);
+  console.log(`  pods: ${includePods.length ? includePods.join(', ') : '(none)'}`);
+  console.log(
+    `  system frameworks: ${
+      includeSystemFrameworks.length
+        ? includeSystemFrameworks.join(', ')
+        : 'UIKit, Foundation'
+    }`,
+  );
+
+  if (argv.includes('--check')) {
+    return;
+  }
+
+  console.log(
+    'Metadata is bundled with @nativescript/react-native for the default iOS SDK. ' +
+      'Custom pod/framework metadata generation will use this configuration during native builds.',
+  );
+}
+
+if (require.main === module) {
+  generateMetadata();
+}
+
+module.exports = {
+  generateMetadata,
+};

packages/react-native/examples/UIKitContainer.tsx

@@ -0,0 +1,22 @@
+import NativeScript from '@nativescript/react-native';
+
+export const UIKitContainer = NativeScript.defineUIKitContainer<{
+  backgroundColor?: UIColor;
+}>({
+  name: 'UIKitContainer',
+  layout: {sizing: 'fill'},
+  create() {
+    const rootView = UIView.new();
+    const childrenView = UIView.new();
+    childrenView.frame = rootView.bounds;
+    childrenView.autoresizingMask =
+      UIViewAutoresizing.FlexibleWidth |
+      UIViewAutoresizing.FlexibleHeight;
+    rootView.addSubview(childrenView);
+    return {rootView, childrenView};
+  },
+  update(view, props) {
+    view.rootView.backgroundColor =
+      props.backgroundColor ?? UIColor.clearColor;
+  },
+});

packages/react-native/examples/UIKitIntrinsicLabel.tsx

@@ -0,0 +1,19 @@
+import NativeScript from '@nativescript/react-native';
+
+export const UIKitIntrinsicLabel = NativeScript.defineUIKitView<
+  {text: string},
+  UILabel
+>({
+  name: 'UIKitIntrinsicLabel',
+  layout: {
+    sizing: 'intrinsic',
+    defaultSize: {width: 1, height: 1},
+  },
+  create() {
+    return UILabel.new();
+  },
+  update(label, props, _previous, ctx) {
+    label.text = props.text;
+    ctx?.invalidateLayout();
+  },
+});

packages/react-native/examples/UIKitSwitch.tsx

@@ -0,0 +1,24 @@
+import NativeScript from '@nativescript/react-native';
+
+export const UIKitSwitch = NativeScript.defineUIKitView<
+  {
+    value: boolean;
+    onValueChange?: (value: boolean) => void;
+  },
+  UISwitch
+>({
+  name: 'UIKitSwitch',
+  layout: {sizing: 'intrinsic'},
+  create(ctx) {
+    const view = UISwitch.new();
+    ctx.targetAction(view, UIControlEvents.ValueChanged, () => {
+      ctx.emit('onValueChange', view.on);
+    });
+    return view;
+  },
+  update(view, props) {
+    if (view.on !== props.value) {
+      view.setOnAnimated(props.value, false);
+    }
+  },
+});

packages/react-native/examples/UIKitViewController.tsx

@@ -0,0 +1,15 @@
+import NativeScript from '@nativescript/react-native';
+
+export const UIKitViewControllerHost = NativeScript.defineUIViewController<{
+  backgroundColor?: UIColor;
+}>({
+  name: 'UIKitViewControllerHost',
+  layout: {sizing: 'fill'},
+  createController() {
+    return UIViewController.new();
+  },
+  update(controller, props) {
+    controller.view.backgroundColor =
+      props.backgroundColor ?? UIColor.systemBackgroundColor;
+  },
+});