validateTheme function

List<Diagnostic> validateTheme(
  1. Object? json, {
  2. String at = '/theme',
  3. Breakpoints? breakpoints,
})

Checks a theme's JSON (the site manifest's theme, at at): its keys, its colors (#AARRGGBB or another color's name), its text styles (as TextStyle, their from and color names against the theme itself) and its media rules (conditions as a node's, patches of colors and text styles).

Implementation

List<Diagnostic> validateTheme(Object? json, {String at = '/theme', Breakpoints? breakpoints}) {
  final r = Reporter();
  final m = readMap(json);
  if (json == null) return r.out;
  if (m == null) {
    r.add(Codes.invalidTheme, at, 'A theme is an object: {"colors": {"ink": "#FF111111"}, "textStyles": {"body": {...}}}.');
    return r.out;
  }
  final theme = ThemeTokens.fromJson(m);
  final values = ValueChecker(r, theme: theme);
  void body(Json m, String at, {required bool patch}) {
    for (final e in m.entries) {
      final p = pointer(at, e.key);
      if (!themeKeys.contains(e.key) || (patch && (e.key == 'media' || e.key == 'dark' || e.key == 'mode'))) {
        r.add(Codes.invalidTheme, p, 'A theme has no "${e.key}". It takes: ${themeKeys.join(', ')}.',
            suggestion: nearest(e.key, themeKeys));
        continue;
      }
      if (e.value == null) continue;
      switch (e.key) {
        case 'mode':
          if (ThemeMode.tryParse(e.value) == null) {
            r.add(Codes.invalidTheme, p,
                '"mode" is "system" (the device\'s setting), "light" or "dark" (Flutter\'s ThemeMode), got ${describe(e.value)}. '
                'A setThemeMode action changes it while the site runs.',
                suggestion: e.value is String ? nearest(e.value as String, [for (final m in ThemeMode.values) m.name]) : null);
          }
        case 'colors':
          final colors = readMap(e.value);
          if (colors == null) {
            r.add(Codes.invalidTheme, p, '"colors" maps names to colors: {"ink": "#FF111111"}.');
            continue;
          }
          for (final c in colors.entries) {
            values.check(PropTypes.color, c.value, pointer(p, c.key));
          }
          for (final c in colors.entries) {
            if (!ThemeTokens.roleNames.contains(c.key)) continue;
            final top = patch ? null : m[c.key];
            r.add(Codes.themeRoleInColors, pointer(p, c.key),
                '"${c.key}" is a colour role (Flutter\'s ColorScheme): write it at the top of the theme, not in "colors", or controls do not use it. '
                '${top == null ? 'Move it: "${c.key}": ${jsonEncode(c.value)}.' : 'The theme already has a top-level "${c.key}"; remove this one.'} '
                'A role may name a colour: "${c.key}": "<colour name>".',
                suggestion: c.key);
          }
        case 'textStyles':
          final styles = readMap(e.value);
          if (styles == null) {
            r.add(Codes.invalidTheme, p, '"textStyles" maps names to text styles: {"body": {"fontSize": 16}}.');
            continue;
          }
          for (final s in styles.entries) {
            if (s.value is! Map) {
              r.add(Codes.invalidTheme, pointer(p, s.key), 'A theme text style is a TextStyle object, got ${describe(s.value)}.');
              continue;
            }
            values.check(PropTypes.textStyle, s.value, pointer(p, s.key));
          }
        case 'dark':
          final d = readMap(e.value);
          if (d == null) {
            r.add(Codes.invalidTheme, p, '"dark" holds the colors that differ in dark mode: {"colors": {...}}.');
          } else {
            body(d, p, patch: true);
          }
        case 'media':
          final list = readList(e.value);
          if (list == null) {
            r.add(Codes.invalidTheme, p, '"media" is a list of rules: [{"minWidth": 1024, "patch": {"textStyles": {...}}}].');
            continue;
          }
          for (var i = 0; i < list.length; i++) {
            final rule = readMap(list[i]);
            final rp = pointer(p, i);
            if (rule == null || !rule.keys.any(MediaRule.conditionKeys.contains)) {
              r.add(Codes.invalidMedia, rp, 'A theme media rule is {"minWidth"|"maxWidth"|"orientation": ..., "patch": {...}}.');
              continue;
            }
            final names = MediaRule.fromJson(rule)!.unknownNames(breakpoints ?? Breakpoints.defaults);
            if (names.isNotEmpty) {
              r.add(Codes.unknownBreakpoint, rp, 'No breakpoint ${names.map((n) => '"$n"').join(', ')}.');
            }
            for (final k in rule.keys) {
              if (k != 'patch' && !MediaRule.conditionKeys.contains(k)) {
                r.add(Codes.invalidMedia, pointer(rp, k), 'A media rule has no "$k".', suggestion: nearest(k, [...MediaRule.conditionKeys, 'patch']));
              }
            }
            final patch = readMap(rule['patch']);
            if (patch == null) {
              r.add(Codes.invalidMedia, pointer(rp, 'patch'), 'Add "patch": the theme\'s fields at those sizes ({"textStyles": {"display": {"fontSize": 40}}}).');
            } else {
              // A patch's text style changes some fields of the theme's.
              final checked = <String, Object?>{...patch};
              final ts = readMap(patch['textStyles']);
              if (ts != null) {
                checked['textStyles'] = <String, Object?>{
                  for (final s in ts.entries) s.key: s.value is Map ? ({...readMap(s.value)!}..remove('from')) : s.value,
                };
              }
              body(checked, pointer(rp, 'patch'), patch: true);
            }
          }
        case 'spacing' || 'radii' || 'sizes' || 'durations':
          final scale = readMap(e.value);
          if (scale == null) {
            r.add(Codes.invalidTheme, p, '"${e.key}" maps names to numbers: {"sm": 8, "md": 16}.');
            continue;
          }
          for (final v in scale.entries) {
            final n = readDouble(v.value);
            if (n == null || n < 0) {
              r.add(Codes.invalidTheme, pointer(p, v.key),
                  '"${e.key}" values are numbers >= 0${e.key == 'durations' ? ' (milliseconds)' : ''}, got ${describe(v.value)}.');
            }
          }
        case 'shadows':
          final scale = readMap(e.value);
          if (scale == null) {
            r.add(Codes.invalidTheme, p, '"shadows" maps names to lists of shadows: {"level1": [{"type": "dropShadow", ...}]}.');
            continue;
          }
          for (final v in scale.entries) {
            values.checkDef(DecorationFields.effects, v.value, pointer(p, v.key));
          }
        case 'curves':
          final scale = readMap(e.value);
          if (scale == null) {
            r.add(Codes.invalidTheme, p, '"curves" maps names to curves: {"standard": "easeInOut"}.');
            continue;
          }
          final curves = [for (final c in AnimationCurve.values) c.name];
          for (final v in scale.entries) {
            if (!curves.contains(v.value)) {
              r.add(Codes.invalidTheme, pointer(p, v.key), 'A curve is one of Flutter\'s Curves: ${curves.join(', ')}; got ${describe(v.value)}.',
                  suggestion: v.value is String ? nearest(v.value as String, curves) : null);
            }
          }
        default:
          final def = switch (e.key) {
            'fontFamily' || 'titleFontFamily' => const PropType.string(),
            'radius' || 'buttonRadius' => const PropType.number(),
            _ => PropTypes.color,
          };
          values.check(def, e.value, p);
      }
    }
  }

  body(m, at, patch: false);
  return r.out;
}