Themes in code

The properties cover colors, typography, shapes, density and the component themes. For the rest of a ThemeData (a field the properties do not know, a value computed from others, a theme that already exists in Dart), the starter has three ways in code: customizers that change every theme, beans that replace a theme, and the MaterialThemes bean that has the result.

Why

Properties are the place for what a designer changes; some things are code: an extensions entry of your own, a pageTransitionsTheme per platform, a ThemeData shared with an app that is not built on Spring. A customizer keeps that code in one bean that runs on every theme, so the themes of the properties, of a profile and of a download all get it.

ThemeCustomizer

A bean that implements ThemeCustomizer changes every ThemeData made from the properties, when it is first made, in @Order:

import 'package:material_ui/material_ui.dart';
import 'package:spring_boot_starter_flutter_material/spring_boot_starter_flutter_material.dart';

// Every chip is a stadium, whatever the theme.
@Component()
class RoundedChips implements ThemeCustomizer {
  @override
  ThemeData customize(ThemeData theme, SpringThemeData spring) =>
      theme.copyWith(
        chipTheme: theme.chipTheme.copyWith(shape: const StadiumBorder()),
      );
}

spring is the theme as read from the properties: its name, its palette, spacing and tokens, for a value computed from them.

Replacing a theme

A ThemeData bean named theme replaces the made light theme, one named darkTheme the dark one. The customizers still run on them:

@Configuration()
class Themes {
  @Bean(name: 'theme')
  ThemeData theme() => ThemeData(colorSchemeSeed: Colors.teal);
}

Order

A theme is made once, when it is first shown (or asked of the MaterialThemes bean), in this order:

  1. From the properties: the ThemeData of the theme, its palette, text styles and components (SpringThemeData.toMaterial()).
  2. Or the replacing bean: for the theme named light, a ThemeData bean named theme; for dark, one named darkTheme. The properties of that theme are then not made into a ThemeData; the theme as read still gives SpringTheme.of(context) its values.
  3. The customizers, every ThemeCustomizer bean, each on the result of the one before, in @Order (lower first; without an order, after the ordered ones).
  4. Kept by the MaterialThemes bean for that theme. A theme loaded at run time is a new theme as read, and is made again from step 1.
// Runs first: other customizers see its extension.
@Component()
@Order(0)
class BrandExtension implements ThemeCustomizer {
  @override
  ThemeData customize(ThemeData theme, SpringThemeData spring) =>
      theme.copyWith(
        extensions: [
          ...theme.extensions.values,
          BrandColors(accent: spring.role('tertiary')),
        ],
      );
}

// Runs after it.
@Component()
@Order(10)
class DesktopTransitions implements ThemeCustomizer {
  @override
  ThemeData customize(ThemeData theme, SpringThemeData spring) =>
      theme.copyWith(
        pageTransitionsTheme: const PageTransitionsTheme(
          builders: {
            TargetPlatform.macOS: FadeForwardsPageTransitionsBuilder(),
            TargetPlatform.windows: FadeForwardsPageTransitionsBuilder(),
          },
        ),
      );
}

BrandColors is a ThemeExtension of the app. Keep the extensions already there (theme.extensions.values): one of them is the SpringThemeExtension that code with only the ThemeData reads the rest of the theme from.

A replacing bean replaces only the theme of that name: a theme ocean that extends: light is made from the properties, and with system-light: ocean the theme bean is not shown.

The MaterialThemes bean

MaterialThemes (the bean materialThemes) has every theme of the application as a ThemeData, customized: theme(name) gives one, themes the themes as read. The MaterialApp the starter builds shows these; a part of the UI in another theme, or a MaterialApp of your own, takes them from the bean:

class ThemePreview extends SpringStatelessWidget<(MaterialThemes,)> {
  const ThemePreview({required this.name, super.key});

  final String name;

  @override
  Widget build(BuildContext context) {
    final (themes,) = beans;
    return Theme(data: themes.theme(name), child: const PreviewCard());
  }
}

Outside a widget, MaterialThemes.of(applicationContext) finds the bean (or, in a context without the starter's auto-configuration, makes the themes without customizers).

SpringThemeData.toMaterial() is the theme as Material's ThemeData without the customizers.

Tests

A test that reads themes by hand passes Material's design to them:

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

final themes = SpringThemes(
  {'seed-color': 'teal', 'components.card.elevation': '2'},
  designs: const ThemeDesigns(
    all: [MaterialThemeDesign()],
    appType: 'material',
  ),
);
expect(themes.data('light').toMaterial().cardTheme.elevation, 2);

A widget test of the whole app (SpringApplicationWidget(application: () => springApplication)) needs nothing more: the generated application has the starter's beans and its design.

In Spring (Java)

Spring has no themes. The customizers follow Spring Boot's customizer beans (WebServerFactoryCustomizer, Jackson2ObjectMapperBuilderCustomizer): the starter makes the object, every customizer bean changes it, and a bean of the application replaces it.

See also