Add 'auto' to ColorSchemeOverride, deprecate 'unspecified'#56696
Open
huntie wants to merge 3 commits intofacebook:mainfrom
Open
Add 'auto' to ColorSchemeOverride, deprecate 'unspecified'#56696huntie wants to merge 3 commits intofacebook:mainfrom
huntie wants to merge 3 commits intofacebook:mainfrom
Conversation
Summary:
Removes `'unspecified'` from the return type of `Appearance.getColorScheme()` and `useColorScheme()`, splitting the setter input into a separate `ColorSchemeOverride` type. This resolves a longstanding misalignment between what native returns and what the types promise.
**Motivation**
`'unspecified'` is only meaningful as an input to `setColorScheme()` — neither iOS nor Android ever returns it from `getColorScheme()`. When `setColorScheme('unspecified')` is called, the JS layer re-queries the native module and caches the resolved system value.
After this change:
- `Appearance.getColorScheme()` returns `'light' | 'dark'` (no longer `'unspecified'`)
- `Appearance.setColorScheme()` receives `'light' | 'dark' | 'unspecified'`
Paired with docs updates:
- facebook/react-native-website#5060
- facebook/react-native-website#5069
**History of this API**
- The TurboModule spec originally typed these methods as plain `string` because codegen didn't support union types (T52919652).
- When support landed, D63681874 upgraded to `ColorSchemeName = 'light' | 'dark' | 'unspecified'` — a type-level cleanup that inadvertently widened return types to include `'unspecified'`, a value native never returns. This caused `$FlowFixMe` suppressions across downstream callers.
- D80705652 later aligned the `.d.ts` and fixed a bug where `setColorScheme('unspecified')` threw an incorrect invariant.
Changelog:
[General][Breaking] - `useColorScheme()` no longer returns `'unspecified'` (this was always the case, but is a breaking type change)
Reviewed By: cipolleschi
Differential Revision: D102527387
Summary: 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: [Internal] - This is a net fix/extension of D102527387 Differential Revision: D103865622
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 facebook/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
meta-cla
Bot
added
the
CLA Signed
|
@huntie has exported this pull request. If you are a Meta employee, you can view the originating Diff in D103841988. |
|
Warning JavaScript API change detected This PR commits an update to
This change was flagged as: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.color-schemeproperty vocabulary, whereautomeans "defer to the system preference".unspecified(now deprecated), which gave no indication of the resulting behaviour.See also:
Alternative names considered
'reset'- Implies reversing a change, not deferring to system'inherit'- Weak — CSS inherit is element→parent, not app→OSChangelog:
[General][Deprecated] -
Appearance.setColorScheme('unspecified')is deprecated, use'auto'instead.Differential Revision: D103841988