Add 'auto' to ColorSchemeOverride, deprecate 'unspecified'

Summary:
NOTE: 👋🏻 **This is an RFC**, additional and separate to the previous 2 diffs. Looking for feedback :)

Proposes an API tweak to `Appearance.setColorScheme()` to make it more idiomatic/understandable.

- Aligns with the CSS `color-scheme` property vocabulary, where `auto` means "defer to the system preference". Replaces the ambiguous `unspecified` (now deprecated), which gave no indication of the resulting behaviour.

See also:
- History of this API + return type narrowing in D102527387.
- Extended docs + diagram in react/react-native-website#5060.

**Alternative names considered**

- `'reset'` - Implies reversing a change, not deferring to system
- `'inherit'` -  Weak — CSS inherit is element→parent, not app→OS

Changelog:
[General][Deprecated] - `Appearance.setColorScheme('unspecified')` is deprecated, use `'auto'` instead.

Differential Revision: D103841988

Author: huntie

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

@@ -11,7 +11,11 @@ import {NativeEventSubscription} from '../EventEmitter/RCTNativeAppEventEmitter'
 
 type ColorSchemeName = 'light' | 'dark';
 
-type ColorSchemeOverride = ColorSchemeName | 'unspecified';
+type ColorSchemeOverride =
+  | ColorSchemeName
+  | 'auto'
+  /** @deprecated Use 'auto' instead */
+  | 'unspecified';
 
 export namespace Appearance {
   type AppearancePreferences = {
@@ -36,8 +40,8 @@ export namespace Appearance {
 
   /**
    * Force the application to always adopt a light or dark interface style. Pass
-   * `'unspecified'` to reset and follow the system default (removes any
-   * override). This does not affect the system UI, only the application.
+   * `'auto'` to reset and follow the system default (removes any override).
+   * This does not affect the system UI, only the application.
    */
   export function setColorScheme(scheme: ColorSchemeOverride): void;
 

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

@@ -107,8 +107,8 @@ export function getColorScheme(): ColorSchemeName | null {
 
 /**
  * Force the application to always adopt a light or dark interface style. Pass
- * `'unspecified'` to reset and follow the system default (removes any
- * override). This does not affect the system UI, only the application.
+ * `'auto'` to reset and follow the system default (removes any override).
+ * This does not affect the system UI, only the application.
  */
 export function setColorScheme(colorScheme: ColorSchemeOverride): void {
   const state = getState();
@@ -117,7 +117,7 @@ export function setColorScheme(colorScheme: ColorSchemeOverride): void {
     NativeAppearance.setColorScheme(colorScheme);
     state.appearance = {
       colorScheme:
-        colorScheme === 'unspecified'
+        colorScheme === 'auto' || colorScheme === 'unspecified'
           ? NativeAppearance.getColorScheme()
           : colorScheme,
     };

packages/react-native/React/Base/RCTConvert.mm

@@ -494,6 +494,7 @@ + (UIKeyboardType)UIKeyboardType:(id)json RCT_DYNAMIC
 RCT_ENUM_CONVERTER(
     UIUserInterfaceStyle,
     (@{
+      @"auto" : @(UIUserInterfaceStyleUnspecified),
       @"unspecified" : @(UIUserInterfaceStyleUnspecified),
       @"light" : @(UIUserInterfaceStyleLight),
       @"dark" : @(UIUserInterfaceStyleDark),

packages/react-native/ReactAndroid/src/main/java/com/facebook/react/modules/appearance/AppearanceModule.kt

@@ -87,6 +87,7 @@ constructor(
       when (style) {
         "dark" -> AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)
         "light" -> AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO)
+        "auto",
         "unspecified" ->
             AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM)
       }

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<<04955f1605996352fa3f3a3fc86ba937>>
+ * @generated SignedSource<<eeffa8d1c270f98debd70024251b4a1a>>
  *
  * This file was generated by scripts/js-api/build-types/index.js.
  */
@@ -1859,7 +1859,7 @@ declare namespace CodegenTypes {
 }
 declare type ColorListenerCallback = (value: ColorValue) => unknown
 declare type ColorSchemeName = "dark" | "light"
-declare type ColorSchemeOverride = "dark" | "light" | "unspecified"
+declare type ColorSchemeOverride = "auto" | "dark" | "light" | "unspecified"
 declare type ColorValue = ____ColorValue_Internal
 declare type ComponentProvider = () => React.ComponentType<any>
 declare type ComponentProviderInstrumentationHook = (
@@ -6073,7 +6073,7 @@ export {
   AppState, // 12012be5
   AppStateEvent, // 80f034c3
   AppStateStatus, // 447e5ef2
-  Appearance, // 0e9bf4fe
+  Appearance, // 83e9641a
   AutoCapitalize, // c0e857a0
   BackHandler, // f139fc69
   BackPressEventName, // 4620fb76

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

@@ -14,7 +14,7 @@ import * as TurboModuleRegistry from '../../../../Libraries/TurboModule/TurboMod
 
 export type ColorSchemeName = 'light' | 'dark';
 
-export type ColorSchemeOverride = 'light' | 'dark' | 'unspecified';
+export type ColorSchemeOverride = 'light' | 'dark' | 'auto' | 'unspecified';
 
 export type AppearancePreferences = {
   colorScheme: ColorSchemeName,

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

@@ -136,8 +136,8 @@ const ColorShowcase = (props: {themeName: string}) => (
 
 const ToggleNativeAppearance = () => {
   const [nativeColorScheme, setNativeColorScheme] = useState<
-    ColorSchemeName | 'unspecified',
-  >('unspecified');
+    ColorSchemeName | 'auto',
+  >('auto');
   const colorScheme = useColorScheme();
 
   useEffect(() => {
@@ -156,10 +156,7 @@ const ToggleNativeAppearance = () => {
         title="Set to dark"
         onPress={() => setNativeColorScheme('dark')}
       />
-      <Button
-        title="Unset"
-        onPress={() => setNativeColorScheme('unspecified')}
-      />
+      <Button title="Auto" onPress={() => setNativeColorScheme('auto')} />
     </View>
   );
 };