docs: initial props demo docs & demos (#298)

* docs: clear documentation on initial properties from native to RN

* feat(demo): demonstrate initial props from native to root RN component

* docs: changes after self-CR

Author: artus9033

apps/AndroidApp/app/src/main/java/com/callstack/brownfield/android/example/MainActivity.kt

@@ -2,6 +2,7 @@ package com.callstack.brownfield.android.example
 
 import android.content.Intent
 import android.content.res.Configuration
+import android.os.Build
 import android.os.Bundle
 import android.widget.Toast
 import androidx.activity.compose.setContent
@@ -129,6 +130,15 @@ fun ReactNativeView(
                 ReactNativeFragmentArgNames.ARG_MODULE_NAME,
                 ReactNativeConstants.MAIN_MODULE_NAME
             )
+            putBundle(
+                ReactNativeFragmentArgNames.ARG_LAUNCH_OPTIONS,
+                Bundle().apply {
+                    putString(
+                        "nativeOsVersionLabel",
+                        "Android ${Build.VERSION.RELEASE}"
+                    )
+                }
+            )
         }
     )
 }

apps/AppleApp/Brownfield Apple App/components/ContentView.swift

@@ -23,7 +23,13 @@ struct ContentView: View {
 
                 MessagesView()
 
-                ReactNativeView(moduleName: "main")
+                ReactNativeView(
+                    moduleName: "main",
+                    initialProperties: [
+                        "nativeOsVersionLabel":
+                            "\(UIDevice.current.systemName) \(UIDevice.current.systemVersion)"
+                    ]
+                )
                     .navigationBarHidden(true)
                     .clipShape(RoundedRectangle(cornerRadius: 16))
                     .background(Color(UIColor.systemBackground))

apps/ExpoApp54/RNApp.tsx

@@ -4,11 +4,24 @@ import BrownfieldNavigation from '@callstack/brownfield-navigation';
 
 import Counter from './components/counter';
 
-export default function RNApp() {
+type RNAppProps = {
+  nativeOsVersionLabel?: string;
+};
+
+export default function RNApp({ nativeOsVersionLabel }: RNAppProps) {
   return (
     <SafeAreaView style={styles.container}>
       <Text style={styles.title}>Expo React Native Brownfield</Text>
 
+      {nativeOsVersionLabel ? (
+        <Text
+          style={styles.nativeOsVersionLabel}
+          accessibilityLabel="Native OS version"
+        >
+          {nativeOsVersionLabel}
+        </Text>
+      ) : null}
+
       <View style={styles.content}>
         <Counter />
 
@@ -36,6 +49,12 @@ const styles = StyleSheet.create({
     fontWeight: 'bold',
     textAlign: 'center',
   },
+  nativeOsVersionLabel: {
+    fontSize: 11,
+    opacity: 0.75,
+    textAlign: 'center',
+    marginTop: 4,
+  },
   content: {
     flex: 1,
     justifyContent: 'center',

apps/ExpoApp55/RNApp.tsx

@@ -4,11 +4,24 @@ import BrownfieldNavigation from '@callstack/brownfield-navigation';
 
 import Counter from './src/components/counter';
 
-export default function RNApp() {
+type RNAppProps = {
+  nativeOsVersionLabel?: string;
+};
+
+export default function RNApp({ nativeOsVersionLabel }: RNAppProps) {
   return (
     <SafeAreaView style={styles.container}>
       <Text style={styles.title}>Expo React Native Brownfield</Text>
 
+      {nativeOsVersionLabel ? (
+        <Text
+          style={styles.nativeOsVersionLabel}
+          accessibilityLabel="Native OS version"
+        >
+          {nativeOsVersionLabel}
+        </Text>
+      ) : null}
+
       <View style={styles.content}>
         <Counter />
 
@@ -36,6 +49,12 @@ const styles = StyleSheet.create({
     fontWeight: 'bold',
     textAlign: 'center',
   },
+  nativeOsVersionLabel: {
+    fontSize: 11,
+    opacity: 0.75,
+    textAlign: 'center',
+    marginTop: 4,
+  },
   content: {
     flex: 1,
     justifyContent: 'center',

apps/RNApp/src/App.tsx

@@ -2,15 +2,22 @@ import '../BrownfieldStore.brownie';
 
 import { NavigationContainer } from '@react-navigation/native';
 
-import { Stack } from './navigation/RootStack';
 import { HomeScreen } from './HomeScreen';
+import { NativeOsVersionLabelContext } from './nativeHostContext';
+import { Stack } from './navigation/RootStack';
+
+type AppProps = {
+  nativeOsVersionLabel?: string;
+};
 
-export default function App() {
+export default function App({ nativeOsVersionLabel }: AppProps) {
   return (
-    <NavigationContainer>
-      <Stack.Navigator>
-        <Stack.Screen name="Home" component={HomeScreen} />
-      </Stack.Navigator>
-    </NavigationContainer>
+    <NativeOsVersionLabelContext.Provider value={nativeOsVersionLabel}>
+      <NavigationContainer>
+        <Stack.Navigator>
+          <Stack.Screen name="Home" component={HomeScreen} />
+        </Stack.Navigator>
+      </NavigationContainer>
+    </NativeOsVersionLabelContext.Provider>
   );
 }

apps/RNApp/src/HomeScreen.tsx

@@ -15,6 +15,7 @@ import BrownfieldNavigation from '@callstack/brownfield-navigation';
 import { getRandomTheme } from './utils';
 import type { RootStackParamList } from './navigation/RootStack';
 import Counter from './components/counter';
+import { useNativeOsVersionLabel } from './nativeHostContext';
 
 interface Message {
   id: string;
@@ -71,6 +72,7 @@ export function HomeScreen({
   navigation,
   route,
 }: NativeStackScreenProps<RootStackParamList, 'Home'>) {
+  const nativeOsVersionLabel = useNativeOsVersionLabel();
   const colors = route.params?.theme ? route.params.theme : getRandomTheme();
   const [messages, setMessages] = useState<Message[]>([]);
   const flatListRef = useRef<FlatList<Message>>(null);
@@ -122,6 +124,15 @@ export function HomeScreen({
         React Native Screen
       </Text>
 
+      {nativeOsVersionLabel ? (
+        <Text
+          style={[styles.nativeOsVersionLabel, { color: colors.secondary }]}
+          accessibilityLabel="Native OS version"
+        >
+          {nativeOsVersionLabel}
+        </Text>
+      ) : null}
+
       <Counter colors={colors} />
 
       <View style={styles.messageSection}>
@@ -199,6 +210,12 @@ const styles = StyleSheet.create({
     fontWeight: 'bold',
     marginBottom: 8,
   },
+  nativeOsVersionLabel: {
+    fontSize: 11,
+    opacity: 0.85,
+    marginBottom: 4,
+    textAlign: 'center',
+  },
   messageSection: {
     flex: 1,
     width: '100%',

apps/RNApp/src/nativeHostContext.tsx

@@ -0,0 +1,9 @@
+import { createContext, useContext } from 'react';
+
+export const NativeOsVersionLabelContext = createContext<string | undefined>(
+  undefined
+);
+
+export function useNativeOsVersionLabel(): string | undefined {
+  return useContext(NativeOsVersionLabelContext);
+}

docs/docs/docs/api-reference/react-native-brownfield/java.mdx

@@ -64,7 +64,10 @@ A function used to initialize a React Native Brownfield singleton. Keep in mind
 
 > `*` - From the marked fields, exactly one must be specified, excluding the others. See examples below.
 
-**Available options:**
+> [!Note]
+> The `options` map for `initialize` is unrelated to the initial props passed to the root component. For passing in initial props, use the [`launchOptions` argument of `createView`](#createview).
+
+**Available `options` entries:**
 
 - `useDeveloperSupport`: `Boolean` - Flag to use dev support.
 - `packages`: `List<ReactPackage>` - List of your React Native Native modules.
@@ -167,6 +170,8 @@ Creates a React Native view with a given module name. It automatically uses an i
 
 Returns: `FrameLayout` - A view containing the React Native component.
 
+Root initial props can be passed through the `launchOptions` argument. That `Bundle` is forwarded as the root view's initial properties - the same concept as [initial props on `ReactRootView`](https://reactnative.dev/docs/communication-android#passing-properties-from-native-to-react-native).
+
 **Examples:**
 
 ```java

docs/docs/docs/api-reference/react-native-brownfield/kotlin.mdx

@@ -47,7 +47,10 @@ A function used to initialize a React Native Brownfield singleton. Keep in mind
 
 > `*` - From the marked fields, exactly one must be specified, excluding the others. See examples below.
 
-**Available options:**
+> [!Note]
+> The `options` map for `initialize` is unrelated to the initial props passed to the root component. For passing in initial props, use the [`launchOptions` argument of `createView`](#createview).
+
+**Available `options` entries:**
 
 - `useDeveloperSupport`: `Boolean` - Flag to use dev support.
 - `packages`: `List<ReactPackage>` - List of your React Native Native modules.
@@ -146,6 +149,8 @@ Creates a React Native view with a given module name. It automatically uses an i
 
 Returns: `FrameLayout` - A view containing the React Native component.
 
+Root initial props can be passed through the `launchOptions` argument. That `Bundle` is forwarded as the root view's initial properties - the same concept as [initial props on `ReactRootView`](https://reactnative.dev/docs/communication-android#passing-properties-from-native-to-react-native).
+
 **Examples:**
 
 ```kotlin

docs/docs/docs/api-reference/react-native-brownfield/objective-c.mdx

@@ -69,6 +69,8 @@ Creates a React Native view for the specified module name.
 | `initialProps`  | No       | `NSDictionary` | Initial properties to be passed to React Native component.  |
 | `launchOptions` | No       | `NSDictionary` | Launch options, typically passed from AppDelegate.          |
 
+Root initial props can be passed through the `initialProps` argument. That `NSDictionary` is forwarded as the root view's initial properties - the same concept as [initial props on `RCTRootView`](https://reactnative.dev/docs/communication-ios#passing-properties-from-native-to-react-native).
+
 **Examples:**
 
 ```objc