From 29dce4da09d25b7cadc69349f804946e2ca4c95e Mon Sep 17 00:00:00 2001
From: Alec Marcus <18580335+alecmarcus@users.noreply.github.com>
Date: Mon, 9 Oct 2023 11:49:38 -0700
Subject: [PATCH] Update StyleSheet documentation (#39990)

Summary:
The current comments explaining the various StyleSheet methods and are misleading, often referencing the removed `StyleSheetRegistry` and old behavior related to it.

## Changelog:

Per https://github.com/facebook/react-native-website/pull/3872/files, updates comments to reflect the fact that the `StyleSheetRegistry` has been removed.

[INTERNAL] [REMOVED] - Removed comment references to `StyleSheetRegistry` and style sheet `ID`s

Pull Request resolved: https://github.com/facebook/react-native/pull/39990

Test Plan: `console.log(StyleSheet.create({ testClass: { color: "red" } }))` outputs `{ testClass: { color: "red" } }`

Reviewed By: NickGerleman

Differential Revision: D50076737

Pulled By: javache

fbshipit-source-id: edc3c9f63f9963c17b1a2c1a898badf1b87183e4
---
 .../Libraries/StyleSheet/StyleSheet.d.ts      | 21 +-----------
 .../Libraries/StyleSheet/StyleSheet.js        | 33 +++----------------
 2 files changed, 6 insertions(+), 48 deletions(-)

diff --git a/packages/react-native/Libraries/StyleSheet/StyleSheet.d.ts b/packages/react-native/Libraries/StyleSheet/StyleSheet.d.ts
index 914791c058d..6d9fda4dac2 100644
--- a/packages/react-native/Libraries/StyleSheet/StyleSheet.d.ts
+++ b/packages/react-native/Libraries/StyleSheet/StyleSheet.d.ts
@@ -32,7 +32,7 @@ export namespace StyleSheet {
   type NamedStyles<T> = {[P in keyof T]: ViewStyle | TextStyle | ImageStyle};
 
   /**
-   * Creates a StyleSheet style reference from the given object.
+   * An identity function for creating style sheets.
    */
   export function create<T extends NamedStyles<T> | NamedStyles<any>>(
     // The extra & NamedStyles<any> here helps Typescript catch typos: e.g.,
@@ -49,14 +49,6 @@ export namespace StyleSheet {
 
   /**
    * Flattens an array of style objects, into one aggregated style object.
-   * Alternatively, this method can be used to lookup IDs, returned by
-   * StyleSheet.register.
-   *
-   * > **NOTE**: Exercise caution as abusing this can tax you in terms of
-   * > optimizations.
-   * >
-   * > IDs enable optimizations through the bridge and memory in general. Referring
-   * > to style objects directly will deprive you of these optimizations.
    *
    * Example:
    * ```
@@ -74,17 +66,6 @@ export namespace StyleSheet {
    * StyleSheet.flatten([styles.listItem, styles.selectedListItem])
    * // returns { flex: 1, fontSize: 16, color: 'green' }
    * ```
-   * Alternative use:
-   * ```
-   * StyleSheet.flatten(styles.listItem);
-   * // return { flex: 1, fontSize: 16, color: 'white' }
-   * // Simply styles.listItem would return its ID (number)
-   * ```
-   * This method internally uses `StyleSheetRegistry.getStyleByID(style)`
-   * to resolve style objects represented by IDs. Thus, an array of style
-   * objects (instances of StyleSheet.create), are individually resolved to,
-   * their respective objects, merged as one and then returned. This also explains
-   * the alternative use.
    */
   export function flatten<T>(
     style?: StyleProp<T>,
diff --git a/packages/react-native/Libraries/StyleSheet/StyleSheet.js b/packages/react-native/Libraries/StyleSheet/StyleSheet.js
index e18594ad3e5..7a9f4659cf4 100644
--- a/packages/react-native/Libraries/StyleSheet/StyleSheet.js
+++ b/packages/react-native/Libraries/StyleSheet/StyleSheet.js
@@ -212,16 +212,12 @@ if (__DEV__) {
  * Code quality:
  *
  *  - By moving styles away from the render function, you're making the code
- *  easier to understand.
+ *    easier to understand.
  *  - Naming the styles is a good way to add meaning to the low level components
- *  in the render function.
+ *  in the render function, and encourage reuse.
+ *  - In most IDEs, using `StyleSheet.create()` will offer static type checking
+ *  and suggestions to help you write valid styles.
  *
- * Performance:
- *
- *  - Making a stylesheet from a style object makes it possible to refer to it
- * by ID instead of creating a new style object every time.
- *  - It also allows to send the style only once through the bridge. All
- * subsequent uses are going to refer an id (not implemented yet).
  */
 module.exports = {
   /**
@@ -285,14 +281,6 @@ module.exports = {
 
   /**
    * Flattens an array of style objects, into one aggregated style object.
-   * Alternatively, this method can be used to lookup IDs, returned by
-   * StyleSheet.register.
-   *
-   * > **NOTE**: Exercise caution as abusing this can tax you in terms of
-   * > optimizations.
-   * >
-   * > IDs enable optimizations through the bridge and memory in general. Referring
-   * > to style objects directly will deprive you of these optimizations.
    *
    * Example:
    * ```
@@ -310,17 +298,6 @@ module.exports = {
    * StyleSheet.flatten([styles.listItem, styles.selectedListItem])
    * // returns { flex: 1, fontSize: 16, color: 'green' }
    * ```
-   * Alternative use:
-   * ```
-   * StyleSheet.flatten(styles.listItem);
-   * // return { flex: 1, fontSize: 16, color: 'white' }
-   * // Simply styles.listItem would return its ID (number)
-   * ```
-   * This method internally uses `StyleSheetRegistry.getStyleByID(style)`
-   * to resolve style objects represented by IDs. Thus, an array of style
-   * objects (instances of StyleSheet.create), are individually resolved to,
-   * their respective objects, merged as one and then returned. This also explains
-   * the alternative use.
    */
   flatten,
 
@@ -361,7 +338,7 @@ module.exports = {
   },
 
   /**
-   * Creates a StyleSheet style reference from the given object.
+   * An identity function for creating style sheets.
    */
   // $FlowFixMe[unsupported-variance-annotation]
   create<+S: ____Styles_Internal>(obj: S): $ReadOnly<S> {