react-native-nitro-modules 0.22.1 → 0.24.0

package/src/views/HybridView.ts

@@ -9,29 +9,107 @@ export interface ViewPlatformSpec {
 }
 
 /**
- * Represents a Nitro `HybridView` which is implemented in a native language
- * like Swift or Kotlin.
+ * Represents props for a Hybrid View.
+ * Such props are implemented on the native side, and can be
+ * set from JS using React props.
+ * @example
+ * ```ts
+ * // Definition:
+ * type Direction = 'horizontal' | 'vertical'
+ * interface ScrollViewProps extends HybridViewProps {
+ *   direction: Direction
+ * }
+ * export type ScrollView = HybridView<ScrollViewProps>
  *
- * `HybridViews`s use the Nitro Tunnel for efficient, low-overhead JS <-> Native communication.
+ * // in React:
+ * function App() {
+ *   return <HybridScrollView direction="vertical" />
+ * }
+ * ```
+ */
+export interface HybridViewProps {
+  /* no default props */
+}
+
+/**
+ * Represents methods for a Hybrid View.
+ * Such methods are implemented on the native side, and can be
+ * called from JS using the `hybridRef`.
+ * @example
+ * ```ts
+ * // Definition:
+ * interface ScrollViewProps extends HybridViewProps { … }
+ * interface ScrollViewMethods extends HybridViewMethods {
+ *   scrollTo(y: number): void
+ * }
+ * export type ScrollView = HybridView<ScrollViewProps, ScrollViewMethods>
  *
- * All `HybridViews`s have a C++ Fabric View base with a backing Shadow Node.
+ * // in React:
+ * function App() {
+ *   const ref = useRef<ScrollView>(null)
+ *   useLayoutEffect(() => {
+ *     ref.current.scrollTo(400)
+ *   }, [])
+ *   return <HybridScrollView hybridRef={ref} />
+ * }
+ * ```
+ */
+export interface HybridViewMethods {}
+
+/**
+ * The type of a {@linkcode DefaultHybridViewProps.hybridRef hybridRef}.
+ * @example
+ * ```ts
+ * // declaration:
+ * interface ScrollViewProps extends HybridViewProps { … }
+ * interface ScrollViewMethods extends HybridViewMethods {
+ *   scrollTo(y: number): void
+ * }
+ * export type ScrollView = HybridView<ScrollViewProps, ScrollViewMethods>
+ * export type ScrollViewRef = HybridRef<ScrollViewProps, ScrollViewMethods>
  *
- * - TypeScript Properties (`name: Type`) will be React Props
- * - TypeScript Methods (`name(): Type`) will be Ref Methods
+ * // in react:
+ * function App() {
+ *   const ref = useRef<ScrollViewRef>(null)
+ *   useLayoutEffect(() => {
+ *     ref.current.scrollTo(400)
+ *   }, [])
+ *   return <ScrollView hybridRef={ref} />
+ * }
+ * ```
+ */
+export type HybridRef<
+  Props extends HybridViewProps,
+  Methods extends HybridViewMethods = {},
+> = HybridObject & Props & Methods
+
+/**
+ * This interface acts as a tag for Hybrid Views so nitrogen detects them.
+ */
+interface HybridViewTag extends HybridObject {}
+
+/**
+ * Represents a Nitro Hybrid View.
+ *
+ * The Hybrid View's implementation is in native iOS or Android, and is backed
+ * by a {@linkcode HybridObject}.
+ *
+ * Each view has {@linkcode HybridViewProps}, and can optionally also
+ * have custom {@linkcode HybridViewMethods}.
+ *
+ * Properties can be set using React props, and methods can be called after obtaining
+ * a reference to the {@linkcode HybridObject} via {@linkcode DefaultHybridViewProps.hybridRef hybridRef}.
  *
+ * The view can be rendered in React (Native).
  * @example
- * ```tsx
- * export interface Camera extends HybridView {
- *   zoom: number
- *   flash: boolean
- *   takePhoto(): Image
- * }
+ * ```ts
+ * interface ScrollViewProps extends HybridViewProps { … }
+ * interface ScrollViewMethods extends HybridViewMethods { … }
+ * export type ScrollView = HybridView<ScrollViewProps, ScrollViewMethods>
  * ```
  */
-export interface HybridView<
+export type HybridView<
+  Props extends HybridViewProps,
+  Methods extends HybridViewMethods = {},
   Platforms extends ViewPlatformSpec = { ios: 'swift'; android: 'kotlin' },
-> extends HybridObject<Platforms> {
-  /* empty interface for now */
-}
-
-export * from './getHostComponent'
+> = HybridViewTag & HybridObject<Platforms> & Props & Methods

package/src/views/getHostComponent.ts

@@ -1,6 +1,11 @@
-import { Platform, type HostComponent } from 'react-native'
+import { Platform, type HostComponent, type ViewProps } from 'react-native'
 // @ts-expect-error this unfortunately isn't typed or default-exported.
 import * as NativeComponentRegistry from 'react-native/Libraries/NativeComponent/NativeComponentRegistry'
+import type {
+  HybridView,
+  HybridViewMethods,
+  HybridViewProps,
+} from './HybridView'
 
 export interface ViewConfig<Props> {
   uiViewClassName: string
@@ -11,16 +16,73 @@ export interface ViewConfig<Props> {
 }
 
 /**
- * Finds and returns a native view (aka {@linkcode HostComponent}) via the given {@linkcode name}.
+ * Represents all default props a Nitro HybridView has.
  */
-export function getHostComponent<Props>(
+interface DefaultHybridViewProps<RefType> extends ViewProps {
+  /**
+   * A `ref` to the {@linkcode HybridObject} this Hybrid View is rendering.
+   *
+   * The `hybridRef` property expects a stable Ref object received from `useRef` or `createRef`.
+   * @example
+   * ```jsx
+   * function App() {
+   *   return (
+   *     <HybridScrollView
+   *       hybridRef={{ f: (ref) => {
+   *         ref.current.scrollTo(400)
+   *       }
+   *     />
+   *   )
+   * }
+   * ```
+   */
+  hybridRef?: (ref: RefType) => void
+}
+
+// Due to a React limitation, functions cannot be passed to native directly
+// because RN converts them to booleans (`true`). Nitro knows this and just
+// wraps functions as objects - the original function is stored in `f`.
+type WrapFunctionsInObjects<Props> = {
+  [K in keyof Props]: Props[K] extends Function
+    ? { f: Props[K] }
+    : Props[K] extends Function | undefined
+      ? { f: Props[K] }
+      : Props[K]
+}
+
+/**
+ * Represents a React Native view, implemented as a Nitro View, with the given props and methods.
+ *
+ * @note Every React Native view has a {@linkcode DefaultHybridViewProps.hybridRef hybridRef} which can be used to gain access
+ *       to the underlying Nitro {@linkcode HybridView}.
+ * @note Every function/callback is wrapped as a `{ f: … }` object.
+ * @note Every method can be called on the Ref. Including setting properties directly.
+ */
+export type ReactNativeView<
+  Props extends HybridViewProps,
+  Methods extends HybridViewMethods,
+> = HostComponent<
+  WrapFunctionsInObjects<
+    DefaultHybridViewProps<HybridView<Props, Methods>> & Props
+  >
+>
+
+/**
+ * Finds and returns a native view (aka "HostComponent") via the given {@linkcode name}.
+ *
+ * The view is bridged to a native Hybrid Object using Nitro Views.
+ */
+export function getHostComponent<
+  Props extends HybridViewProps,
+  Methods extends HybridViewMethods,
+>(
   name: string,
   getViewConfig: () => ViewConfig<Props>
-): HostComponent<Props> {
+): ReactNativeView<Props, Methods> {
   if (NativeComponentRegistry == null) {
     throw new Error(
       `NativeComponentRegistry is not available on ${Platform.OS}!`
     )
   }
-  return NativeComponentRegistry.get<Props>(name, getViewConfig)
+  return NativeComponentRegistry.get(name, getViewConfig)
 }

package/cpp/utils/OwningLock.hpp

@@ -1,56 +0,0 @@
-//
-//  OwningLock.hpp
-//  Nitro
-//
-//  Created by Marc Rousavy on 30.07.24.
-//
-
-#pragma once
-
-namespace margelo::nitro {
-template <typename T>
-class BorrowingReference;
-}
-
-#include "BorrowingReference.hpp"
-#include <cstddef>
-#include <mutex>
-
-namespace margelo::nitro {
-
-/**
- * An `OwningLock<T>` is a RAII instance that locks the given caller thread guaranteed safe access
- * to a `BorrowingReference<T>`.
- * The `BorrowingReference<T>` cannot be deleted while an `OwningLock<T>` of it is alive.
- *
- * This is useful in JSI, because Hermes runs garbage collection on a separate Thread,
- * and the separate Thread can delete an `BorrowingReference<T>` while it's still in use.
- * The `OwningLock<T>` prevents exactly this problem by blocking the GC destructor until
- * the `OwningLock<T>` is released.
- *
- * To create an `OwningLock<T>`, simply call `lock()` on an `BorrowingReference<T>`.
- */
-template <typename T>
-class OwningLock final {
-private:
-  explicit OwningLock(const BorrowingReference<T>& reference) : _reference(reference) {
-    _reference._state->mutex.lock();
-  }
-
-public:
-  ~OwningLock() {
-    _reference._state->mutex.unlock();
-  }
-
-  OwningLock() = delete;
-  OwningLock(const OwningLock&) = delete;
-  OwningLock(OwningLock&&) = delete;
-
-private:
-  BorrowingReference<T> _reference;
-
-private:
-  friend class BorrowingReference<T>;
-};
-
-} // namespace margelo::nitro