[konstmar]

What is this?

Android Dynamic Widget colors can now be a { day, night } pair: one color for the light system theme and one for the dark. Until now a color was a single string or an AndroidDynamicColors role, and the only way to change colors with the theme was to branch on env.colorScheme, which runs the widget's JavaScript again on every theme change.

Pairs work wherever a color string does: style colors, component color props, chart mark colors and foregroundStyleScale, and arc gradientColors. backgroundImage takes a pair of whole gradients.

This is the color-pair half of #319. The app color scheme mapped onto GlanceTheme comes in a separate PR.

How does it work?

<VoltraAndroid.Column style={{ backgroundColor: { day: '#ffffff', night: '#1c1b1f' } }}>
  <VoltraAndroid.Text style={{ color: { day: '#1c1b1f', night: '#e6e1e5' } }}>Inbox</VoltraAndroid.Text>
</VoltraAndroid.Column>

The pair travels through the payload unchanged, and the native side picks the side to show:

• On Android 12+, a pair becomes Glance's day/night color provider. The launcher gets both colors and swaps them itself on a theme change, even when the app isn't running.
• Below Android 12, and for anything drawn into a bitmap (gradients, arcs, custom-font text, charts), the side is picked when the widget is composed. A theme change needs a native recomposition, but no JavaScript.
• Each side takes any literal color, alpha included. Role tokens aren't allowed inside a pair, and an invalid pair is dropped as a whole, so the property falls back to its default.

Differences from #319:

• The keys are { day, night } instead of { light, dark }, as agreed with the maintainer.
• Scaffold backgroundColor, the Text color prop and chart colors also take pairs. The Text color prop is now applied, and it wins over the style's color.
• An unparsable hex, RGB or HSL side logs two warnings instead of one.

Why is this useful?

Widget authors can give a widget colors for both themes without branching on env.colorScheme. On Android 12+ the colors stay right after a theme change even when the app isn't running.

Refs #319

[konstmar]

Emulator evidence

Test layout: the AndroidClientDemoWidget Dynamic Widget on the home screen has a Row with one demo per kind of pair:

Demo	Day	Night
Style pair card (background / text)	#fff3c4 / #5d4037	#1a237e / #ffe082
Text color prop pair	#c62828	#80cbc4
backgroundImage gradient pair	#ff8f00 → #ffee58	#311b92 → #00bfa5
Arc gradientColors pairs	#ef6c00 → #6a1b9a	#80deea → #f48fb1

Colors were sampled from screencaps by counting pixels within a channel delta of 12 of each expected color. The widget shows its render time, which tells a launcher-side swap apart from a recomposition.

Build: a debug APK of the example app from this branch @ 2bfeef6 (arm64-v8a), with Metro serving the widget bundle.

Android 15 emulator, API 35 (AVD Pixel_9)

Step	Result	Render time
Light, app running	every demo on its day side, no night pixels	5:06:00 PM
Dark, app running	every demo on its night side, no day pixels	5:07:25 PM
Light again	same pixel counts as the first light run	5:07:56 PM
App process killed, then dark	card and prop pair switch to night; gradient and arc keep day	5:07:56 PM, unchanged

With no app process and no new render, the launcher swaps the plain pair colors itself. The gradient and arc are bitmaps, so they keep the side they were drawn with until the widget recomposes.

Android 7.0 emulator, API 24 (AVD Medium_Phone_2)

Step	Result	Render time
Light, app running	every demo on its day side, no night pixels	5:32:25 PM
Dark, app running	every demo on its night side, no day pixels	5:34:05 PM
Light again	same pixel counts as the first light run	5:34:46 PM
App process killed, then light	every pair keeps night	5:35:21 PM, unchanged
Widget refresh	every demo back on its day side	5:47:43 PM

Below Android 12 the side is picked when the widget is composed, so a theme change needs a recomposition. Refreshing the widget recomposes it, and it picks the side from the new theme. That a recomposition alone is enough, with no JavaScript render, is covered by the API 26 test in StyleModifiersTest.

Charts aren't placed in the demo widget, so they are covered by the ChartBitmapRendererTest pixel tests only.

Steps:

1. Start Metro from example/ on port 8104.
2. Build ./gradlew :app:assembleDebug -PreactNativeArchitectures=arm64-v8a -PreactNativeDevServerPort=8104 and adb install -r it.
3. Flip the theme:
   • API 35: adb shell cmd uimode night yes|no
   • API 24, which has no cmd uimode: adb shell service call uimode 4 i32 2 for night, i32 1 for day
4. With the app backgrounded, kill its process: adb shell am kill <package> on API 35, adb shell run-as <package> kill <pid> on API 24.
5. After each step, press HOME, then adb exec-out screencap -p.

Unit tests: pnpm test:kotlin (670 tests), pnpm test, pnpm typecheck (including the type tests), pnpm lint and pnpm format:kotlin:check pass, and so do the pre-push test-js/test-kotlin hooks.