From b7daabf98dd1dea2ba9393bc8fa70f187979faf7 Mon Sep 17 00:00:00 2001 From: David Vacca Date: Tue, 27 Jan 2026 13:36:23 -0800 Subject: [PATCH 1/5] Add KDoc documentation to UIManagerType.kt Summary: Added comprehensive KDoc documentation to the UIManagerType annotation class and its companion object constants. This improves code readability and provides better IDE support for developers working with UIManager types. The documentation explains: - The purpose of the annotation (distinguishing between legacy and Fabric UIManager) - Each constant (DEFAULT, LEGACY, FABRIC) and their use cases - Deprecation notes for the DEFAULT constant changelog: [internal] internal Reviewed By: cortinico Differential Revision: D91553347 --- .../react/uimanager/common/UIManagerType.kt | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/common/UIManagerType.kt b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/common/UIManagerType.kt index 912d8c68f7fd69..bc20c931c1bd05 100644 --- a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/common/UIManagerType.kt +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/common/UIManagerType.kt @@ -9,16 +9,38 @@ package com.facebook.react.uimanager.common import androidx.annotation.IntDef +/** + * Annotation class that defines the type of UIManager being used in React Native. + * + * This annotation is used to distinguish between the legacy UIManager implementation and the newer + * Fabric renderer. It helps ensure type safety when working with UIManager-related code by + * restricting values to the defined constants. + * + * @see UIManagerType.LEGACY for legacy (Paper) UIManager + * @see UIManagerType.FABRIC for Fabric renderer + */ @Retention(AnnotationRetention.SOURCE) @Suppress("DEPRECATION") @IntDef(UIManagerType.DEFAULT, UIManagerType.LEGACY, UIManagerType.FABRIC) public annotation class UIManagerType { public companion object { + /** + * Default UIManager type. Equivalent to [LEGACY]. + * + * @deprecated Use [LEGACY] instead. + */ @Deprecated( "UIManagerType.DEFAULT will be deleted in the next release of React Native. Use [LEGACY] instead." ) public const val DEFAULT: Int = 1 + + /** Represents the legacy (Paper) UIManager implementation. */ public const val LEGACY: Int = 1 + + /** + * Represents the Fabric renderer, React Native's new rendering system that provides improved + * performance and better integration with the host platform. + */ public const val FABRIC: Int = 2 } } From ce3721a46a1596bc5c5e919ca7fc5885893aadac Mon Sep 17 00:00:00 2001 From: David Vacca Date: Tue, 27 Jan 2026 13:36:23 -0800 Subject: [PATCH 2/5] Add KDoc documentation to ViewUtil.kt Summary: Added KDoc documentation to the ViewUtil object and its NO_SURFACE_ID constant. The existing function documentation was already present. The documentation explains: - The purpose of the ViewUtil object (utilities for determining UIManager type) - The NO_SURFACE_ID constant and its usage as a placeholder for legacy UIManager changelog: [internal] internal Reviewed By: cortinico Differential Revision: D91553498 --- .../facebook/react/uimanager/common/ViewUtil.kt | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/common/ViewUtil.kt b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/common/ViewUtil.kt index 22bcb86a2ad250..22d34f6c63fb4b 100644 --- a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/common/ViewUtil.kt +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/common/ViewUtil.kt @@ -9,8 +9,23 @@ package com.facebook.react.uimanager.common import android.view.View +/** + * Utility object providing helper methods for working with React Native views. + * + * This object contains utilities for determining which UIManager (Legacy/Paper or Fabric) a view + * belongs to, based on view tags and surface IDs. These utilities are essential for routing events + * and operations to the correct UIManager implementation. + * + * @see UIManagerType + */ public object ViewUtil { + /** + * Constant representing the absence of a surface ID. + * + * This value (-1) is used as a placeholder when no surface ID is available, typically indicating + * that the view or event originated from the legacy (Paper) UIManager rather than Fabric. + */ public const val NO_SURFACE_ID: Int = -1 /** From b9bd344d8716caa6106d11abd3ceb35a43309338 Mon Sep 17 00:00:00 2001 From: David Vacca Date: Tue, 27 Jan 2026 13:36:23 -0800 Subject: [PATCH 3/5] Add KDoc documentation to BackgroundSize.kt Summary: Added comprehensive KDoc documentation to BackgroundSize.kt classes and methods: - BackgroundSizeLengthPercentage: Documented class purpose, properties (x, y), and methods (isXAuto, isYAuto, parse) - BackgroundSize sealed class: Documented the sealed class hierarchy and LengthPercentageAuto subclass - Companion object parse methods: Added parameter and return documentation This improves code readability and provides better IDE support for developers. changelog: [internal] internal Reviewed By: lenaic Differential Revision: D91554301 --- .../react/uimanager/style/BackgroundSize.kt | 50 +++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundSize.kt b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundSize.kt index f476c24baf57b6..aaeaa4d4e855de 100644 --- a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundSize.kt +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundSize.kt @@ -12,15 +12,44 @@ import com.facebook.react.bridge.ReadableMap import com.facebook.react.bridge.ReadableType import com.facebook.react.uimanager.LengthPercentage +/** + * Represents a background size value with horizontal (x) and vertical (y) length/percentage + * components. + * + * This class handles CSS-like background-size values where each dimension can be a length, + * percentage, or "auto". A null value for x or y indicates "auto" sizing for that dimension. + * + * @property x The horizontal size component, or null for "auto" + * @property y The vertical size component, or null for "auto" + */ internal class BackgroundSizeLengthPercentage( public val x: LengthPercentage?, public val y: LengthPercentage?, ) { + /** + * Checks if the horizontal dimension is set to auto. + * + * @return true if x is null (auto), false otherwise + */ public fun isXAuto(): Boolean = x == null + /** + * Checks if the vertical dimension is set to auto. + * + * @return true if y is null (auto), false otherwise + */ public fun isYAuto(): Boolean = y == null public companion object { + /** + * Parses a ReadableMap into a BackgroundSizeLengthPercentage. + * + * The map should contain "x" and/or "y" keys with values that are either numbers (treated as + * points), percentage strings (e.g., "50%"), or "auto". + * + * @param backgroundSizeMap The map containing x and y size values + * @return A BackgroundSizeLengthPercentage instance, or null if the map is null + */ public fun parse(backgroundSizeMap: ReadableMap?): BackgroundSizeLengthPercentage? { if (backgroundSizeMap == null) return null @@ -78,11 +107,32 @@ internal class BackgroundSizeLengthPercentage( } } +/** + * Sealed class representing CSS background-size property values. + * + * This class models the different ways a background size can be specified in CSS, currently + * supporting length/percentage/auto values for both dimensions. + * + * @see BackgroundSizeLengthPercentage + */ internal sealed class BackgroundSize { + /** + * Represents a background size specified using length, percentage, or auto values. + * + * @property lengthPercentage The parsed size values for x and y dimensions + */ public class LengthPercentageAuto(public val lengthPercentage: BackgroundSizeLengthPercentage) : BackgroundSize() public companion object { + /** + * Parses a Dynamic value into a BackgroundSize. + * + * Currently supports map values containing x/y dimensions. + * + * @param backgroundSizeValue The dynamic value to parse + * @return A BackgroundSize instance, or null if parsing fails + */ public fun parse(backgroundSizeValue: Dynamic?): BackgroundSize? { if (backgroundSizeValue == null) return null From 45267f0ef42a7de0f20b62a5140a9c64273f64fb Mon Sep 17 00:00:00 2001 From: David Vacca Date: Tue, 27 Jan 2026 13:36:23 -0800 Subject: [PATCH 4/5] Add KDoc documentation to BackgroundPosition.kt Summary: Added KDoc documentation to BackgroundPosition.kt: - Class documentation explaining its purpose for CSS-like background positioning - Property documentation for top, left, right, bottom offset values - Parse method documentation with parameter and return descriptions changelog: [internal] internal Reviewed By: lenaic Differential Revision: D91554341 --- .../uimanager/style/BackgroundPosition.kt | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundPosition.kt b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundPosition.kt index 3febece11f8dec..a414fad9fe1cdd 100644 --- a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundPosition.kt +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundPosition.kt @@ -11,6 +11,17 @@ import com.facebook.react.bridge.ReadableMap import com.facebook.react.bridge.ReadableType import com.facebook.react.uimanager.LengthPercentage +/** + * Represents the position of a background image within its container. + * + * This class models CSS-like background-position values, allowing specification of offsets from any + * edge (top, left, right, bottom). Each offset can be a length or percentage value. + * + * @property top Offset from the top edge, or null if not specified + * @property left Offset from the left edge, or null if not specified + * @property right Offset from the right edge, or null if not specified + * @property bottom Offset from the bottom edge, or null if not specified + */ internal class BackgroundPosition( public val top: LengthPercentage?, public val left: LengthPercentage?, @@ -18,6 +29,15 @@ internal class BackgroundPosition( public val bottom: LengthPercentage?, ) { public companion object { + /** + * Parses a ReadableMap into a BackgroundPosition. + * + * The map may contain "top", "left", "right", and/or "bottom" keys with length or percentage + * values. + * + * @param backgroundPositionMap The map containing position values + * @return A BackgroundPosition instance, or null if the map is null + */ public fun parse(backgroundPositionMap: ReadableMap?): BackgroundPosition? { if (backgroundPositionMap == null) return null From 6dde9037ebff3cf45d5ae0afe01dfe8b915daf55 Mon Sep 17 00:00:00 2001 From: David Vacca Date: Tue, 27 Jan 2026 13:36:23 -0800 Subject: [PATCH 5/5] Add KDoc documentation to BackgroundRepeat.kt Summary: Added KDoc documentation to BackgroundRepeat.kt: - BackgroundRepeatKeyword enum: Documented each repeat behavior (Repeat, Space, Round, NoRepeat) - BackgroundRepeat class: Documented class purpose and x/y properties - Parse method: Added parameter and return documentation changelog: [internal] internal Reviewed By: cortinico Differential Revision: D91554444 --- .../react/uimanager/style/BackgroundRepeat.kt | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundRepeat.kt b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundRepeat.kt index 3ca757ed9ec145..511ed929fbb634 100644 --- a/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundRepeat.kt +++ b/packages/react-native/ReactAndroid/src/main/java/com/facebook/react/uimanager/style/BackgroundRepeat.kt @@ -10,18 +10,45 @@ package com.facebook.react.uimanager.style import com.facebook.react.bridge.ReadableMap import com.facebook.react.bridge.ReadableType +/** + * Enum representing the possible repeat behavior keywords for background images. + * + * These values correspond to CSS background-repeat keywords. + */ internal enum class BackgroundRepeatKeyword { + /** The image is repeated as much as needed to cover the background area. */ Repeat, + /** The image is repeated as much as possible without clipping, with space distributed evenly. */ Space, + /** The image is repeated as much as possible without clipping, scaling to fit evenly. */ Round, + /** The image is not repeated and only shown once. */ NoRepeat, } +/** + * Represents the background repeat behavior for both horizontal and vertical axes. + * + * This class models the CSS background-repeat property, specifying how background images should be + * repeated in each direction. + * + * @property x The repeat behavior for the horizontal axis + * @property y The repeat behavior for the vertical axis + */ internal class BackgroundRepeat( public val x: BackgroundRepeatKeyword, public val y: BackgroundRepeatKeyword, ) { public companion object { + /** + * Parses a ReadableMap into a BackgroundRepeat. + * + * The map should contain "x" and/or "y" keys with string values matching the + * BackgroundRepeatKeyword values. Missing values default to Repeat. + * + * @param backgroundRepeatMap The map containing repeat values + * @return A BackgroundRepeat instance, or null if the map is null + */ public fun parse(backgroundRepeatMap: ReadableMap?): BackgroundRepeat? { if (backgroundRepeatMap == null) return null