Align nullable types across Appearance API (#56687)

Summary:
Pull Request resolved: #56687

Simplify and align nullable values in the `Appearance` API.

| API | Flow / Strict TS API | Manual `.d.ts` |
|---|---|---|
| `getColorScheme()` | `ColorSchemeName | null` (narrowed) | `ColorSchemeName | null` |
| `useColorScheme()` | `ColorSchemeName | null` (narrowed) | `ColorSchemeName | null` (fixed) |

At the native spec level, nullability is removed entirely — the module always returns a valid color scheme, and the module-level `?Spec` already covers the "module absent" case.

Changelog:
[General][Breaking] - Fix return type of `useColorScheme()` hook (now  `ColorSchemeName | null`)
- Release Crew note: This is a net fix/extension of D102527387

Reviewed By: cipolleschi

Differential Revision: D103865622

fbshipit-source-id: a6391cfd86a634ea660734735614169d0601a830

Author: huntie

packages/react-native/Libraries/Utilities/Appearance.d.ts

@@ -15,7 +15,7 @@ type ColorSchemeOverride = ColorSchemeName | 'unspecified';
 
 export namespace Appearance {
   type AppearancePreferences = {
-    colorScheme: ColorSchemeName;
+    colorScheme: ColorSchemeName | null;
   };
 
   type AppearanceListener = (preferences: AppearancePreferences) => void;
@@ -32,7 +32,7 @@ export namespace Appearance {
    * - `null` will only be returned if the native Appearance module is
    *   unavailable (out of tree platforms).
    */
-  export function getColorScheme(): ColorSchemeName | null | undefined;
+  export function getColorScheme(): ColorSchemeName | null;
 
   /**
    * Force the application to always adopt a light or dark interface style. Pass
@@ -54,5 +54,9 @@ export namespace Appearance {
 /**
  * Returns the active color scheme (`'light'` or `'dark'`). Automatically
  * re-renders the component when the color scheme changes.
+ *
+ * Notes:
+ * - `null` will only be returned if the native Appearance module is unavailable
+ *   (out of tree platforms).
  */
-export function useColorScheme(): ColorSchemeName;
+export function useColorScheme(): ColorSchemeName | null;

packages/react-native/Libraries/Utilities/Appearance.js

@@ -10,7 +10,7 @@
 
 import type {EventSubscription} from '../vendor/emitter/EventEmitter';
 import type {
-  AppearancePreferences,
+  AppearancePreferences as NativeAppearancePreferences,
   ColorSchemeName,
   ColorSchemeOverride,
 } from './NativeAppearance';
@@ -19,10 +19,14 @@ import typeof INativeAppearance from './NativeAppearance';
 import NativeEventEmitter from '../EventEmitter/NativeEventEmitter';
 import EventEmitter from '../vendor/emitter/EventEmitter';
 
-export type {AppearancePreferences, ColorSchemeName, ColorSchemeOverride};
+export type {ColorSchemeName, ColorSchemeOverride};
+
+export type AppearancePreferences = {
+  colorScheme: ColorSchemeName | null,
+};
 
 type Appearance = {
-  colorScheme: ?ColorSchemeName,
+  colorScheme: ColorSchemeName | null,
 };
 
 let lazyState: ?{
@@ -60,7 +64,7 @@ function getState(): NonNullable<typeof lazyState> {
       eventEmitter,
     };
     new NativeEventEmitter<{
-      appearanceChanged: [AppearancePreferences],
+      appearanceChanged: [NativeAppearancePreferences],
     }>(NativeAppearance).addListener('appearanceChanged', newAppearance => {
       state.appearance = {
         colorScheme: newAppearance.colorScheme,
@@ -84,7 +88,7 @@ function getState(): NonNullable<typeof lazyState> {
  * - `null` will only be returned if the native Appearance module is unavailable
  *   (out of tree platforms).
  */
-export function getColorScheme(): ?ColorSchemeName {
+export function getColorScheme(): ColorSchemeName | null {
   let colorScheme = null;
   const state = getState();
   const {NativeAppearance} = state;
@@ -114,7 +118,7 @@ export function setColorScheme(colorScheme: ColorSchemeOverride): void {
     state.appearance = {
       colorScheme:
         colorScheme === 'unspecified'
-          ? (NativeAppearance.getColorScheme() ?? null)
+          ? NativeAppearance.getColorScheme()
           : colorScheme,
     };
   }
@@ -126,7 +130,7 @@ export function setColorScheme(colorScheme: ColorSchemeOverride): void {
  * or a call to `setColorScheme()`.
  */
 export function addChangeListener(
-  listener: ({colorScheme: ?ColorSchemeName}) => void,
+  listener: (preferences: AppearancePreferences) => void,
 ): EventSubscription {
   const {eventEmitter} = getState();
   return eventEmitter.addListener('change', listener);

packages/react-native/Libraries/Utilities/useColorScheme.js

@@ -28,6 +28,6 @@ const subscribe = (onStoreChange: () => void) => {
  * - `null` will only be returned if the native Appearance module is unavailable
  *   (out of tree platforms).
  */
-export default function useColorScheme(): ?ColorSchemeName {
+export default function useColorScheme(): ColorSchemeName | null {
   return useSyncExternalStore(subscribe, getColorScheme);
 }

packages/react-native/ReactNativeApi.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  *
- * @generated SignedSource<<4950f1efd16fed02b526f83325c8351d>>
+ * @generated SignedSource<<04955f1605996352fa3f3a3fc86ba937>>
  *
  * This file was generated by scripts/js-api/build-types/index.js.
  */
@@ -1218,7 +1218,7 @@ declare type ActivityIndicatorProps = Readonly<
 >
 declare type add = typeof add
 declare function addChangeListener(
-  listener: ($$PARAM_0$$: { colorScheme: ColorSchemeName | undefined }) => void,
+  listener: (preferences: AppearancePreferences) => void,
 ): EventSubscription
 declare class Alert {
   static alert(
@@ -1629,13 +1629,13 @@ declare namespace Appearance {
     getColorScheme,
     setColorScheme,
     addChangeListener,
-    AppearancePreferences,
     ColorSchemeName,
     ColorSchemeOverride,
+    AppearancePreferences,
   }
 }
 declare type AppearancePreferences = {
-  colorScheme?: ColorSchemeName
+  colorScheme: ColorSchemeName | null
 }
 declare type AppParameters = {
   initialProps: {
@@ -2468,7 +2468,7 @@ declare function get_2<T extends TurboModule>(
   name: string,
 ): null | T | undefined
 declare function getAppKeys(): ReadonlyArray<string>
-declare function getColorScheme(): ColorSchemeName | null | undefined
+declare function getColorScheme(): ColorSchemeName | null
 declare function getEnforcing<T extends TurboModule>(name: string): T
 declare function getRegistry(): Registry
 declare function getRunnable(appKey: string): null | Runnable | undefined
@@ -5738,7 +5738,7 @@ declare function useAnimatedValueXY(
   },
   config?: Animated.AnimatedConfig | null | undefined,
 ): Animated.ValueXY
-declare function useColorScheme(): ColorSchemeName | null | undefined
+declare function useColorScheme(): ColorSchemeName | null
 declare function usePressability(
   config: null | PressabilityConfig | undefined,
 ): null | PressabilityEventHandlers
@@ -6073,7 +6073,7 @@ export {
   AppState, // 12012be5
   AppStateEvent, // 80f034c3
   AppStateStatus, // 447e5ef2
-  Appearance, // df9545f9
+  Appearance, // 0e9bf4fe
   AutoCapitalize, // c0e857a0
   BackHandler, // f139fc69
   BackPressEventName, // 4620fb76
@@ -6339,7 +6339,7 @@ export {
   useAnimatedColor, // e3511f81
   useAnimatedValue, // b18adb63
   useAnimatedValueXY, // c7ee2332
-  useColorScheme, // 29a517d5
+  useColorScheme, // d585efdb
   usePressability, // b4e21b46
   useWindowDimensions, // bb4b683f
 }

packages/react-native/src/private/specs_DEPRECATED/modules/NativeAppearance.js

@@ -17,11 +17,11 @@ export type ColorSchemeName = 'light' | 'dark';
 export type ColorSchemeOverride = 'light' | 'dark' | 'unspecified';
 
 export type AppearancePreferences = {
-  colorScheme?: ?ColorSchemeName,
+  colorScheme: ColorSchemeName,
 };
 
 export interface Spec extends TurboModule {
-  +getColorScheme: () => ?ColorSchemeName;
+  +getColorScheme: () => ColorSchemeName;
   +setColorScheme: (colorScheme: ColorSchemeOverride) => void;
 
   // RCTEventEmitter

packages/rn-tester/js/examples/Appearance/AppearanceExample.js

@@ -24,7 +24,7 @@ function ColorSchemeSubscription() {
 
   useEffect(() => {
     const subscription = Appearance.addChangeListener(
-      ({colorScheme: newColorScheme}: {colorScheme: ?ColorSchemeName}) => {
+      ({colorScheme: newColorScheme}) => {
         setColorScheme(newColorScheme);
       },
     );

scripts/cxx-api/api-snapshots/ReactAppleDebugCxx.api

@@ -2653,7 +2653,7 @@ protocol NativeAppStateSpec : public NSObjectRCTBridgeModule, public RCTTurboMod
 }
 
 protocol NativeAppearanceSpec : public NSObjectRCTBridgeModule, public RCTTurboModule {
-  public virtual NSString* _Nullable getColorScheme();
+  public virtual NSString* getColorScheme();
   public virtual void addListener:(NSString* eventName);
   public virtual void removeListeners:(double count);
   public virtual void setColorScheme:(NSString* colorScheme);

scripts/cxx-api/api-snapshots/ReactAppleReleaseCxx.api

@@ -2653,7 +2653,7 @@ protocol NativeAppStateSpec : public NSObjectRCTBridgeModule, public RCTTurboMod
 }
 
 protocol NativeAppearanceSpec : public NSObjectRCTBridgeModule, public RCTTurboModule {
-  public virtual NSString* _Nullable getColorScheme();
+  public virtual NSString* getColorScheme();
   public virtual void addListener:(NSString* eventName);
   public virtual void removeListeners:(double count);
   public virtual void setColorScheme:(NSString* colorScheme);