Merge pull request #931 from facebook/main

sync

docs/_integration-with-existing-apps-ios.md

@@ -279,7 +279,7 @@ First, we need to extends the `AppDelegate` to inherit from one of the classes p
 
 To achieve this, we have to modify the `AppDelegate.h` file and the `AppDelegate.m` files:
 
-1. Open the `AppDelegate.h` files and modify it as it follows (See the official template's [AppDelegate.h](https://github.com/react-native-community/template/blob/0.77-stable/template/ios/HelloWorld/AppDelegate.h) as reference):
+1. Open the `AppDelegate.h` files and modify it as it follows (See the official template's [AppDelegate.h](https://github.com/react-native-community/template/blob/0.76-stable/template/ios/HelloWorld/AppDelegate.h) as reference):
 
 ```diff title="AppDelegate.h changes"
 #import <UIKit/UIKit.h>
@@ -292,7 +292,7 @@ To achieve this, we have to modify the `AppDelegate.h` file and the `AppDelegate
 @end
 ```
 
-2. Open the `AppDelegate.mm` file and modify it as it follows (See the official template's [AppDelegate.mm](https://github.com/react-native-community/template/blob/0.77-stable/template/ios/HelloWorld/AppDelegate.mm) as reference
+2. Open the `AppDelegate.mm` file and modify it as it follows (See the official template's [AppDelegate.mm](https://github.com/react-native-community/template/blob/0.76-stable/template/ios/HelloWorld/AppDelegate.mm) as reference
 
 ```diff title="AppDelegate.mm"
 #import "AppDelegate.h"

docs/boxshadowvalue.md

@@ -0,0 +1,73 @@
+---
+id: boxshadowvalue
+title: BoxShadowValue Object Type
+---
+
+The `BoxShadowValue` object is taken by the [`boxShadow`](./view-style-props.md#boxshadow) style prop. It is comprised of 2-4 lengths, an optional color, and an optional `inset` boolean. These values collectively define the box shadow's color, position, size, and blurriness.
+
+## Example
+
+```js
+{
+  offsetX: 10,
+  offsetY: -3,
+  blurRadius: '15px',
+  spreadDistance: '10px',
+  color: 'red',
+  inset: true,
+}
+```
+
+## Keys and values
+
+### `offsetX`
+
+The offset on the x-axis. This can be positive or negative. A positive value indicates right and negative indicates left.
+
+| Type             | Optional |
+| ---------------- | -------- |
+| number \| string | No       |
+
+### `offsetY`
+
+The offset on the y-axis. This can be positive or negative. A positive value indicates up and negative indicates down.
+
+| Type             | Optional |
+| ---------------- | -------- |
+| number \| string | No       |
+
+### `blurRadius`
+
+Represents the radius used in the [Guassian blur](https://en.wikipedia.org/wiki/Gaussian_blur) algorithm. The larger the value the blurrier the shadow is. Only non-negative values are valid. The default is 0.
+
+| Type            | Optional |
+| --------------- | -------- |
+| numer \| string | Yes      |
+
+### `spreadDistance`
+
+How much larger or smaller the shadow grows or shrinks. A positive value will grow the shadow, a negative value will shrink the shadow.
+
+| Type            | Optional |
+| --------------- | -------- |
+| numer \| string | Yes      |
+
+### `color`
+
+The color of the shadow. The default is `black`.
+
+| Type                 | Optional |
+| -------------------- | -------- |
+| [color](./colors.md) | Yes      |
+
+### `inset`
+
+Whether the shadow is inset or not. Inset shadows will appear around the inside of the element's border box as opposed to the outside.
+
+| Type    | Optional |
+| ------- | -------- |
+| boolean | Yes      |
+
+## Used by
+
+- [`boxShadow`](./view-style-props.md#boxshadow)

docs/debugging-native-code.md

@@ -23,6 +23,47 @@ npx react-native log-ios
 
 You may also access these through Debug > Open System Log… in the iOS Simulator or by running `adb logcat "*:S" ReactNative:V ReactNativeJS:V` in a terminal while an Android app is running on a device or emulator.
 
+<details>
+<summary>**💡 Custom Native Logs**</summary>
+
+If you are writing a Native Module and want to add custom logs to your module for debugging purposes, you can use the following method:
+
+#### Android (Java/Kotlin)
+
+In your native module, use the `Log` class to add logs that can be viewed in Logcat:
+
+```java
+import android.util.Log;
+
+private void log(String message) {
+    Log.d("YourModuleName", message);
+}
+```
+
+To view these logs in Logcat, use this command, replacing `YourModuleName` with your custom tag:
+
+```shell
+adb logcat "*:S" ReactNative:V ReactNativeJS:V YourModuleName:D
+```
+
+#### iOS (Objective-C/Swift)
+
+In your native module, use `NSLog` for custom logs:
+
+```objective-c
+NSLog(@"YourModuleName: %@", message);
+```
+
+Or, in Swift:
+
+```swift
+print("YourModuleName: \(message)")
+```
+
+These logs will appear in the Xcode console when running the app.
+
+</details>
+
 ## Debugging in a Native IDE
 
 When working with native code, such as when writing native modules, you can launch the app from Android Studio or Xcode and take advantage of the native debugging features (setting up breakpoints, etc.) as you would in case of building a standard native app.

docs/dropshadowvalue.md

@@ -0,0 +1,55 @@
+---
+id: dropshadowvalue
+title: DropShadowValue Object Type
+---
+
+The `DropShadowValue` object is taken by the [`filter`](./view-style-props.md#filter) style prop for the `dropShadow` function. It is comprised of 2 or 3 lengths and an optional color. These values collectively define the drop shadow's color, position, and blurriness.
+
+## Example
+
+```js
+{
+  offsetX: 10,
+  offsetY: -3,
+  standardDeviation: '15px',
+  color: 'blue',
+}
+```
+
+## Keys and values
+
+### `offsetX`
+
+The offset on the x-axis. This can be positive or negative. A positive value indicates right and negative indicates left.
+
+| Type             | Optional |
+| ---------------- | -------- |
+| number \| string | No       |
+
+### `offsetY`
+
+The offset on the y-axis. This can be positive or negative. A positive value indicates up and negative indicates down.
+
+| Type             | Optional |
+| ---------------- | -------- |
+| number \| string | No       |
+
+### `standardDeviation`
+
+Represents the standard deviation used in the [Guassian blur](https://en.wikipedia.org/wiki/Gaussian_blur) algorithm. The larger the value the blurrier the shadow is. Only non-negative values are valid. The default is 0.
+
+| Type            | Optional |
+| --------------- | -------- |
+| numer \| string | Yes      |
+
+### `color`
+
+The color of the shadow. The default is `black`.
+
+| Type                 | Optional |
+| -------------------- | -------- |
+| [color](./colors.md) | Yes      |
+
+## Used by
+
+- [`filter`](./view-style-props.md#filter)

docs/fabric-native-components-android.md

@@ -381,7 +381,7 @@ public class ReactWebViewPackage extends BaseReactPackage {
   public ReactModuleInfoProvider getReactModuleInfoProvider() {
     return new ReactModuleInfoProvider() {
       @Override
-      public Map<String, ReactModuleInfo> get() {
+      public Map<String, ReactModuleInfo> getReactModuleInfos() {
         Map<String, ReactModuleInfo> map = new HashMap<>();
         map.put(ReactWebViewManager.REACT_CLASS, new ReactModuleInfo(
                 ReactWebViewManager.REACT_CLASS, // name

docs/fabric-native-components-ios.md

@@ -60,14 +60,12 @@ open Demo.xcworkspace
 Podfile
 ...
 Demo
-├── AppDelegate.h
-├── AppDelegate.mm
+├── AppDelegate.swift
 ...
 // highlight-start
 ├── RCTWebView.h
-├── RCTWebView.mm
+└── RCTWebView.mm
 // highlight-end
-└── main.m
 ```
 
 After creating the header file and the implementation file, you can start implementing them.

docs/hermes.md

@@ -15,7 +15,7 @@ Hermes is used by default by React Native and no additional configuration is req
 ## Bundled Hermes
 
 React Native comes with a **bundled version** of Hermes.
-We building a version of Hermes for you whenever we release a new version of React Native. This will make sure you're consuming a version of Hermes which is fully compatible with the version of React Native you're using.
+We are building a version of Hermes for you whenever we release a new version of React Native. This will make sure you're consuming a version of Hermes which is fully compatible with the version of React Native you're using.
 
 This change is fully transparent to users of React Native. You can still disable Hermes using the command described in this page.
 You can [read more about the technical implementation on this page](/architecture/bundled-hermes).

docs/images.md

@@ -173,6 +173,38 @@ In some cases you might only want to display an image if it is already in the lo
 
 See [CameraRoll](https://github.com/react-native-community/react-native-cameraroll) for an example of using local resources that are outside of `Images.xcassets`.
 
+### Drawable resources
+
+Android supports loading [drawable resources](https://developer.android.com/guide/topics/resources/drawable-resource) via the `xml` file type. This means you can use [vector drawables](https://developer.android.com/develop/ui/views/graphics/vector-drawable-resources) for rendering icons or [shape drawables](https://developer.android.com/guide/topics/resources/drawable-resource#Shape) for, well, drawing shapes! You can import and use these resource types the same as any other [static resource](#static-image-resources) or [hybrid resource](#images-from-hybrid-apps-resources). You have to specify image dimensions manually.
+
+For static drawables that live alongside your JS code, use the `require` or `import` syntax (both work the same):
+
+```tsx
+<Image
+  source={require('./img/my_icon.xml')}
+  style={{width: 40, height: 40}}
+/>
+```
+
+For drawables included in the Android drawable folder (i.e. `res/drawable`), use the resource name without the extension:
+
+```tsx
+<Image
+  source={{uri: 'my_icon'}}
+  style={{width: 40, height: 40}}
+/>
+```
+
+The one key difference between drawable resources and other image types is that the asset must be referenced at compile-time of the Android application as Android needs to run the [Android Asset Packaging Tool (AAPT)](https://developer.android.com/tools/aapt2) to package the asset. Binary XML, the file format AAPT creates, cannot be loaded over the network by Metro. If you change the directory or name of an asset, you will need to rebuild the Android application each time.
+
+#### Creating XML drawable resources
+
+Android provides comprehensive documentation on each of the supported drawable resource types in its [Drawable resources](https://developer.android.com/guide/topics/resources/drawable-resource) guide, along with examples of raw XML files. You can utilize tools from Android Studio like the [Vector Asset Studio](https://developer.android.com/studio/write/vector-asset-studio) to create vector drawables from Scalable Vector Graphic (SVG) and Adobe Photoshop Document (PSD) files.
+
+:::info
+You should try to avoid referencing other resources in the XML file you create if you want to treat your XML file as a static image resource (i.e. with an `import` or `require` statement). If you wish to utilize references to other drawables or attributes, like [color state lists](https://developer.android.com/guide/topics/resources/color-list-resource) or [dimension resources](https://developer.android.com/guide/topics/resources/more-resources#Dimension), you should include your drawable as a [hybrid resource](#images-from-hybrid-apps-resources) and import it by name.
+:::
+
 ### Best Camera Roll Image
 
 iOS saves multiple sizes for the same image in your Camera Roll, it is very important to pick the one that's as close as possible for performance reasons. You wouldn't want to use the full quality 3264x2448 image as source when displaying a 200x200 thumbnail. If there's an exact match, React Native will pick it, otherwise it's going to use the first one that's at least 50% bigger in order to avoid blur when resizing from a close size. All of this is done by default so you don't have to worry about writing the tedious (and error prone) code to do it yourself.

docs/layout-props.md

@@ -513,6 +513,16 @@ See https://developer.mozilla.org/en-US/docs/Web/CSS/bottom for more details of
 
 ---
 
+### `boxSizing`
+
+`boxSizing` defines how the element's various sizing props (`width`, `height`, `minWidth`, `minHeight`, etc.) are computed. If `boxSizing` is `border-box`, these sizes apply to the border box of the element. If it is `content-box`, they apply to the content box of the element. The default value is `border-box`. The [web documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/box-sizing) is a good source of information if you wish to learn more about how this prop works.
+
+| Type                              | Required |
+| --------------------------------- | -------- |
+| enum('border-box', 'content-box') | No       |
+
+---
+
 ### `columnGap`
 
 `columnGap` works like `column-gap` in CSS. Only pixel units are supported in React Native. See https://developer.mozilla.org/en-US/docs/Web/CSS/column-gap for more details.

docs/linking.md

@@ -13,7 +13,7 @@ In addition to `https`, you're likely also familiar with the `mailto` scheme. Wh
 
 Like using the mailto scheme, it's possible to link to other applications by using custom url schemes. For example, when you get a **Magic Link** email from Slack, the **Launch Slack** button is an anchor tag with an href that looks something like: `slack://secret/magic-login/other-secret`. Like with Slack, you can tell the operating system that you want to handle a custom scheme. When the Slack app opens, it receives the URL that was used to open it. This is often referred to as deep linking. Read more about how to [get the deep link](#get-the-deep-link) into your app.
 
-Custom URL scheme isn't the only way to open your application on mobile. You don't want to use a custom URL scheme in links in the email because then the links would be broken on desktop. Instead, you want to use a regular `https` links such as `https://www.myapp.io/records/1234546`. and on mobile you want that link open your app. Android calls it **Deep Links** (Universal Links - iOS).
+A custom URL scheme isn't the only way to open your application on mobile. For example, if you want to email someone a link to be opened on mobile, using a custom URL scheme isn't ideal because the user might open the email on a desktop, where the link wouldn't work. Instead, you should use standard `https` links, such as `https://www.myapp.io/records/1234546`. On mobile, these links can be configured to open your app. On Android, this feature is called **Deep Links**, while on iOS, it is known as **Universal Links**.
 
 ### Built-in URL Schemes
 

docs/modal.md

@@ -146,6 +146,16 @@ The `hardwareAccelerated` prop controls whether to force hardware acceleration f
 
 ---
 
+### `navigationBarTranslucent` <div class="label android">Android</div>
+
+The `navigationBarTranslucent` prop determines whether your modal should go under the system navigation bar. However, `statusBarTranslucent` also needs to be set to `true` to make navigation bar translucent.
+
+| Type | Default |
+| ---- | ------- |
+| bool | `false` |
+
+---
+
 ### `onDismiss` <div class="label ios">iOS</div>
 
 The `onDismiss` prop allows passing a function that will be called once the modal has been dismissed.

docs/shadow-props.md

@@ -218,8 +218,32 @@ export default App;
 
 # Reference
 
+There are 3 sets of shadow APIs in React Native:
+
+- `boxShadow`: A View style prop and a spec-compliant implementation of the [web style prop of the same name](https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow).
+- `dropShadow`: A specific filter function available as part of the [`filter`](./view-style-props#filter) View style prop.
+- Various `shadow` props (`shadowColor`, `shadowOffset`, `shadowOpacity`, `shadowRadius`): These map directly to their native counterparts exposed by the platform-level APIs.
+
+The difference between `dropShadow` and `boxShadow` are as follows:
+
+- `dropShadow` exists as part of `filter`, whereas `boxShadow` is a standalone style prop.
+- `dropShadow` is an alpha mask, so only pixels with a positive alpha value will "cast" a shadow. `boxShadow` will cast around the border box of the element no matter it's contents (unless it is inset).
+- `dropShadow` is only available on Android, `boxShadow` is available on iOS and Android.
+- `dropShadow` cannot be inset like `boxShadow`.
+- `dropShadow` does not have the `spreadDistance` argument like `boxShadow`.
+
+Both `boxShadow` and `dropShadow` are generally more capable than the `shadow` props. The `shadow` props, however, map to native platform-level APIs, so if you only need a straightforward shadow these props are recommended. Note that only `shadowColor` works on both Android and iOS, all other `shadow` props only work on iOS.
+
 ## Props
 
+### `boxShadow`
+
+See [View Style Props](./view-style-props#boxshadow) for documentation.
+
+### `dropShadow` <div class="label android">Android</div>
+
+See [View Style Props](./view-style-props#filter) for documentation.
+
 ### `shadowColor`
 
 Sets the drop shadow color.

docs/textinput.md

@@ -1048,6 +1048,16 @@ Set line break strategy on iOS 14+. Possible values are `none`, `standard`, `han
 | ----------------------------------------------------------- | -------- |
 | enum(`'none'`, `'standard'`, `'hangul-word'`, `'push-out'`) | `'none'` |
 
+---
+
+### `disableKeyboardShortcuts` <div class="label ios">iOS</div>
+
+If `true`, the keyboard shortcuts (undo/redo and copy buttons) are disabled. The default value is `false`.
+
+| Type |
+| ---- |
+| bool |
+
 ## Methods
 
 ### `.focus()`

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

@@ -18,15 +18,6 @@ The rest of this guide assume that you have created your application running the
 npx @react-native-community/cli@latest init SampleApp --version 0.76.0
 ```
 
-:::danger
-We are aware of some issues that are preventing pure C++ Modules to work well on Android, when developed locally in the app.
-Pure C++ modules consumed as external libraries works well on Android.
-
-These issues started from version 0.76.2 and are still persisting in version 0.76.5.
-
-We found the root cause for the issue (see [#48298](https://github.com/facebook/react-native/issues/48298) and [#48340](https://github.com/facebook/react-native/pull/48340)), and we are aiming to fix in 0.76.6.
-:::
-
 ## 1. Create the JS specs
 
 Pure C++ Turbo Native Modules are Turbo Native Modules. They need a specification file (also called spec file) so that Codegen can create the scaffolding code for us. The specification file is also what we use to access the Turbo Native Module in JS.

docs/turbo-native-modules-android.md

@@ -139,7 +139,7 @@ public class NativeLocalStoragePackage extends BaseReactPackage {
   public ReactModuleInfoProvider getReactModuleInfoProvider() {
     return new ReactModuleInfoProvider() {
       @Override
-      public Map<String, ReactModuleInfo> get() {
+      public Map<String, ReactModuleInfo> getReactModuleInfos() {
         Map<String, ReactModuleInfo> map = new HashMap<>();
         map.put(NativeLocalStorageModule.NAME, new ReactModuleInfo(
           NativeLocalStorageModule.NAME,       // name