Themes in code

What the cupertino.* properties do not cover is changed in code: by customizers, by a bean that replaces the themes, and through the CupertinoThemes bean, which has the result.

Why

The properties cover what a theme usually changes. Some changes are not values: a color computed from two roles, a value that depends on the theme's name, a setting for every theme at once. A customizer does them in Dart and keeps the rest in YAML. A replacing bean is for an app that has its CupertinoThemeData in code already and wants the rest of the starter.

CupertinoThemeCustomizer

A bean that implements CupertinoThemeCustomizer changes every CupertinoThemeData after it is made from the properties:

import 'package:cupertino_ui/cupertino_ui.dart';
import 'package:spring_boot_starter_flutter_cupertino/spring_boot_starter_flutter_cupertino.dart';

// Bar backgrounds follow the theme's surface color.
@Component()
class SurfaceBars implements CupertinoThemeCustomizer {
  @override
  CupertinoThemeData customize(
    CupertinoThemeData theme,
    SpringThemeData spring,
  ) => theme.copyWith(barBackgroundColor: spring.colorScheme.surface);
}

theme is the Cupertino theme so far; spring is the theme as read from the properties: its name, palette, text styles and tokens. A customizer returns the theme changed, usually with copyWith.

// Every theme themes CupertinoSwitch too, without writing
// cupertino.apply-theme-to-all in each theme.
@Component()
class ThemeForAll implements CupertinoThemeCustomizer {
  @override
  CupertinoThemeData customize(
    CupertinoThemeData theme,
    SpringThemeData spring,
  ) => theme.copyWith(applyThemeToAll: true);
}

The order

  1. The theme is made from the properties (SpringThemeData.toCupertino()), or it is the application's CupertinoThemeData bean, when there is one.
  2. Every customizer runs on it, in @Order (lowest first; without @Order, after those with one). Each gets the theme the one before returned.
  3. The result is kept for that theme as read. The next time the theme is asked for, the customizers do not run again; they run again only when the theme is read again (a theme loaded at run time, see Themes from properties).
@Order(1)
@Component()
class BrandPrimary implements CupertinoThemeCustomizer {
  @override
  CupertinoThemeData customize(CupertinoThemeData theme, SpringThemeData spring) =>
      theme.copyWith(primaryColor: spring.tokenColor('brand.accent'));
}

@Order(2)
@Component()
class ContrastOnPrimary implements CupertinoThemeCustomizer {
  @override
  CupertinoThemeData customize(CupertinoThemeData theme, SpringThemeData spring) =>
      theme.copyWith(primaryContrastingColor: spring.colorScheme.onPrimary);
}

Replacing the themes

A CupertinoThemeData bean of the application replaces the themes made from the properties: every theme is that one, the light and the dark one alike. The customizers still run on it, so they can still make it depend on the theme shown.

@Configuration()
class Themes {
  @Bean()
  CupertinoThemeData cupertinoTheme() =>
      const CupertinoThemeData(primaryColor: CupertinoColors.systemTeal);
}

The rest of the theme still comes from the properties: the palette and text styles of SpringTheme.of(context), the background, the page transitions.

The CupertinoThemes bean

CupertinoThemes (the bean cupertinoThemes) has every theme as a CupertinoThemeData, customized: theme(name) gives one, themes the themes as read (SpringThemes). The CupertinoApp the starter builds shows the theme picked; a preview of every theme takes them from the bean:

class ThemePreviews extends SpringStatelessWidget<(CupertinoThemes,)> {
  const ThemePreviews({super.key});

  @override
  Widget build(BuildContext context) {
    final (cupertino,) = beans;
    return Row(
      children: [
        for (final name in cupertino.themes.names)
          CupertinoTheme(
            data: cupertino.theme(name),
            child: ThemeCard(name),
          ),
      ],
    );
  }
}
Of CupertinoThemes What it gives
theme(name) Theme name as a CupertinoThemeData, customized; an unknown name throws an ArgumentError
cupertino(spring) A SpringThemeData as a CupertinoThemeData, customized
themes The themes as read from the properties
customizers The customizers, in order
CupertinoThemes.of(applicationContext) The bean, or, in a context without the starter's auto-configuration (a test), the themes made Cupertino without customizers

SpringTheme.of(context).toCupertino() is the theme shown as made from the properties, without the customizers; CupertinoTheme.of(context) is the one the app shows.

Tests

A test that reads themes by hand names the design:

import 'package:spring_boot_starter_flutter/theme_design.dart';
import 'package:spring_boot_starter_flutter_cupertino/spring_boot_starter_flutter_cupertino.dart';

final themes = SpringThemes(
  const {'cupertino.primary-color': '#00897B'},
  designs: const ThemeDesigns(
    all: [CupertinoThemeDesign()],
    appType: 'cupertino',
  ),
);
expect(
  themes.data('light').toCupertino().primaryColor,
  const Color(0xFF00897B),
);

A customizer is tested the same way, through CupertinoThemes:

final cupertino = CupertinoThemes(themes, customizers: [ThemeForAll()]);
expect(cupertino.theme('light').applyThemeToAll, isTrue);

A widget test of the generated application needs nothing more: its springApplication has the starter's beans and its design.

In Spring (Java)

Spring has no themes. The customizers follow Spring Boot's customizer beans, such as Jackson2ObjectMapperBuilderCustomizer: the starter makes the object, every customizer changes it in @Order, and a bean of the application replaces what the starter would make.

See also