Turbo Native Modules - Documentation ported from reactwg (facebook#4283)

* [NA] Turbo Native Modules: add docs

* feat: Add New Architecture Appendix

Port of https://github.com/reactwg/react-native-new-architecture/blob/main/docs/appendix.md

* fix: update codegen docs with current CLI

* docs: improve turbo native modules file layout

* docs: Add syntax highlighing comments for diffs

Made to look similar to Github diffs

* docs: Add Fabric Native Modules placeholders

* TM: Android: Add video of built app

* TM: Sidebar simpler labels

* TM: Fix internal links

* TM: fix links + add codegen notes

* TM: fix language linter issues

* TM: Add iOS documentation

Add mp4 + webm videos

Add css tweaks

* Fix: first round of feedback

* fix: lint error

* TM: Consolidate appendix into a single table

* chore: fix links

* chore: fixup final round of feedback

* TNM: add code example file paths

* Fix empty spaces

* import TurboModule as type

* Fix punctuation

* Fix linter

* Fix sidebar and titles

* Split pod install from output

* put back extract library

---------

Co-authored-by: Riccardo Cipolleschi <[email protected]>
Co-authored-by: Riccardo Cipolleschi <[email protected]>

Author: blakef

docs/_turbo-native-modules-components.jsx

@@ -0,0 +1,11 @@
+import React from "react";
+import IOSContent from "./turbo-native-modules-ios.md";
+import AndroidContent from "./turbo-native-modules-android.md";
+
+export function TurboNativeModulesIOS() {
+  return <IOSContent />;
+}
+
+export function TurboNativeModulesAndroid() {
+  return <AndroidContent />;
+}

docs/appendix.md

@@ -0,0 +1,36 @@
+# Appendix
+
+## I. Terminology
+
+- **Spec** - TypeScript or Flow code that describes the API for a Turbo Native Module or Fabric Native component. Used by **Codegen** to generate boilerplate code.
+
+- **Turbo Native Modules** - Native libraries that have no User Interface (UI) for the user. Examples would be persistent storage, notifications, network events. These are accessible to your JavaScript application code as functions and objects.
+- **Fabric Native Component** - Native platform views that are available to your application JavaScript code through React Components.
+
+- **Legacy Native Components** - Components which are running on the old React Native architecture.
+- **Legacy Native Modules** - Modules which are running on the old React Native architecture.
+
+## II. Codegen Typings
+
+You may use the following table as a reference for which types are supported and what they map to in each platform:
+
+| Flow                                                                       | TypeScript                                          | Flow Nullable Support                                   | TypeScript Nullable Support                          | Android (Java)                       | iOS (ObjC)                                                     |
+| -------------------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------ | -------------------------------------------------------------- |
+| `string`                                                                   | `string`                                            | `?string`                                               | <code>string &#124; null</code>                      | `string`                             | `NSString`                                                     |
+| `boolean`                                                                  | `boolean`                                           | `?boolean`                                              | <code>boolean &#124; null</code>                     | `Boolean`                            | `NSNumber`                                                     |
+| Object Literal<br /><code>&#123;&#124; foo: string, ...&#124;&#125;</code> | <code>&#123; foo: string, ...&#125; as const</code> | <code>?&#123;&#124; foo: string, ...&#124;&#125;</code> | <code>?&#123; foo: string, ...&#125; as const</code> | \-                                   | \-                                                             |
+| Object [[1](#notes)]                                                       | Object [[1](#notes)]                                | `?Object`                                               | <code>Object &#124; null</code>                      | `ReadableMap`                        | `@` (untyped dictionary)                                       |
+| <code>Array&lt;T&gt;</code>                                                | <code>Array&lt;T&gt;</code>                         | <code>?Array&lt;T&gt;</code>                            | <code>Array&lt;T&gt; &#124; null</code>              | `ReadableArray`                      | `NSArray` (or `RCTConvertVecToArray` when used inside objects) |
+| `Function`                                                                 | `Function`                                          | `?Function`                                             | <code>Function &#124; null</code>                    | \-                                   | \-                                                             |
+| <code>Promise&lt;T&gt;</code>                                              | <code>Promise&lt;T&gt;</code>                       | <code>?Promise&lt;T&gt;</code>                          | <code>Promise&lt;T&gt; &#124; null</code>            | `com.facebook.react.bridge.Promise`  | `RCTPromiseResolve` and `RCTPromiseRejectBlock`                |
+| Type Unions<br /><code>'SUCCESS'&#124;'FAIL'</code>                        | Type Unions<br /><code>'SUCCESS'&#124;'FAIL'</code> | Only as callbacks                                       |                                                      | \-                                   | \-                                                             |
+| Callbacks<br />`() =>`                                                     | Callbacks<br />`() =>`                              | Yes                                                     |                                                      | `com.facebook.react.bridge.Callback` | `RCTResponseSenderBlock`                                       |
+| `number`                                                                   | `number`                                            | No                                                      |                                                      | `double`                             | `NSNumber`                                                     |
+
+### Notes:
+
+<b>[1]</b> We strongly recommend using Object literals intead of Objects.
+
+:::info
+You may also find it useful to refer to the JavaScript specifications for the core modules in React Native. These are located inside the `Libraries/` directory in the React Native repository.
+:::

docs/fabric-native-modules-android.md

@@ -0,0 +1,10 @@
+---
+id: fabric-native-modules-android
+title: 'Fabric Native Modules: Android'
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';
+
+:::caution
+This is work-in-progress... 👷
+:::

docs/fabric-native-modules-ios.md

@@ -0,0 +1,10 @@
+---
+id: fabric-native-modules-ios
+title: 'Fabric Native Modules: iOS'
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';
+
+:::caution
+This is work-in-progress... 👷
+:::

docs/fabric-native-modules.md

@@ -0,0 +1,10 @@
+---
+id: fabric-native-modules-introduction
+title: 'Fabric Native Modules'
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';
+
+:::caution
+This is work-in-progress... 👷
+:::

docs/native-platforms.md

@@ -0,0 +1,36 @@
+---
+id: native-platform
+title: Native Platform
+---
+
+import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';
+
+Your application may need access to platform features that aren’t directly available from React Native or one of the hundreds of [third-party libraries](https://reactnative.directory/) maintained by the community. Maybe you want to reuse some existing Objective-C, Swift, Java, Kotlin or C++ code from the JavaScript runtime. Whatever your reason, React Native exposes a powerful set of API to connect your native code to your JavaScript application code.
+
+This guide introduces:
+
+- **Turbo Native Modules:** native libraries that have no User Interface (UI) for the user. Examples would be persistent storage, notifications, network events. These are accessible to your user as JavaScript functions and objects.
+- **Fabric Native Component:** native platform views, widgets and controllers that are available to your application's JavaScript code through React Components.
+
+:::note
+You might have previously been familiar with:
+
+- [Legacy Native Modules](./legacy/native-modules-intro);
+- [Legacy Native Components](./legacy/native-components-android);
+
+These are our deprecated native module and component API. You can still use many of these legacy libraries with the New Architecture thanks to our interop layers. You should consider:
+
+- using alternative libraries,
+- upgrading to newer library versions that have first-class support for the New Architecture, or
+- port these libraries yourself to Turbo Native Modules or Fabric Native Components.
+
+:::
+
+1. Turbo Native Modules
+   - [Introduction](turbo-native-modules.md)
+   - [Android](turbo-native-modules-android.md)
+   - [iOS](turbo-native-modules-ios.md)
+2. Fabric Native Components
+   - [Introduction](fabric-native-modules.md)
+   - [Android](fabric-native-modules-android.md)
+   - [iOS](fabric-native-modules-ios.md)

docs/the-new-architecture/codegen-cli.md

@@ -2,36 +2,38 @@
 
 Calling Gradle or manually calling a script might be hard to remember and it requires a lot of cerimony.
 
-To simplify it, we created a CLI tool that can help you running those tasks: the **Codegen** cli.
-
-```shell
-npx react-native codegen [--path path] [--platform string] [--outputPath path]
+To simplify it, we created a CLI tool that can help you running those tasks: the **Codegen** cli. This command runs [react-native-codegen](https://www.npmjs.com/package/react-native-codegen) for your project. The following options are available:
+
+```sh
+npx @react-native-community/cli codegen --help
+Usage: rnc-cli codegen [options]
+
+Options:
+  --verbose            Increase logging verbosity
+  --path <path>        Path to the React Native project root. (default: "/Users/MyUsername/projects/my-app")
+  --platform <string>  Target platform. Supported values: "android", "ios", "all". (default: "all")
+  --outputPath <path>  Path where generated artifacts will be output to.
+  -h, --help           display help for command
 ```
 
-This command runs [react-native-codegen](https://www.npmjs.com/package/react-native-codegen) for your project. The following options are available:
-
-- `--path` - Path to `package.json`. The default path is the current working directory.
-- `--platform` - Target platform. Supported values: `android`, `ios`, `all`. The default value is `all`.
-- `--outputPath` - Output path. The default value is the value defined in `codegenConfig.outputDir`.
-
 ## Examples
 
 - Read `package.json` from the current working directory, generate code based on its codegenConfig.
 
 ```shell
-npx react-native codegen
+npx @react-native-codegen/cli codegen
 ```
 
 - Read `package.json` from the current working directory, generate iOS code in the location defined in the codegenConfig.
 
 ```shell
-npx react-native codegen --platform ios
+npx @react-native-codegen/cli codegen --platform ios
 ```
 
 - Read `package.json` from `third-party/some-library`, generate Android code in `third-party/some-library/android/generated`.
 
 ```shell
-npx react-native codegen \
+npx @react-native-codegen/cli codegen \
     --path third-party/some-library \
     --platform android \
     --outputPath third-party/some-library/android/generated

docs/the-new-architecture/pure-cxx-modules.md

@@ -1,4 +1,4 @@
-# Pure C++ Turbo Native Modules
+# Cross-Platform Native Modules (C++)
 
 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';
 

docs/the-new-architecture/using-codegen.md

@@ -132,13 +132,20 @@ This structure has been generated by using the value `all` for the `codegenConfi
 
 **Codegen** for iOS relies on some Node scripts that are invoked during the build process. The scripts are located in the `SampleApp/node_modules/react-native/scripts/` folder.
 
-The main script is the `generate-Codegen-artifacts.js` script. To invoke the script, you can run this command from the root folder of your app:
+The main script is the `generate-codegen-artifacts.js` script. To invoke the script, you can run this command from the root folder of your app:
 
 ```bash
-node node_modules/react-native/scripts/generate-Codegen-artifacts.js \
-    --path <path/to/your/app> \
-    --outputPath <an/output/path> \
-    --targetPlatform <android | ios>
+node node_modules/react-native/scripts/generate-codegen-artifacts.js
+
+Usage: generate-codegen-artifacts.js -p [path to app] -t [target platform] -o [output path]
+
+Options:
+      --help            Show help                                      [boolean]
+      --version         Show version number                            [boolean]
+  -p, --path            Path to the React Native project root.        [required]
+  -t, --targetPlatform  Target platform. Supported values: "android", "ios",
+                        "all".                                        [required]
+  -o, --outputPath      Path where generated artifacts will be output to.
 ```
 
 where:
@@ -152,7 +159,7 @@ where:
 Running the script with these arguments:
 
 ```shell
-node node_modules/react-native/scripts/generate-Codegen-artifacts.js \
+node node_modules/react-native/scripts/generate-codegen-artifacts.js \
     --path . \
     --outputPath ios/ \
     --targetPlatform ios