uiLints function

List<EditDiagnostic> uiLints(
  1. LayoutDocument document, {
  2. Iterable<String>? ids,
  3. GlyphCoverage? hasGlyph,
})

Lints document (or only the nodes ids): empty_button, dead_control and low_contrast warnings, and with hasGlyph, missing_glyph.

Implementation

List<EditDiagnostic> uiLints(LayoutDocument document, {Iterable<String>? ids, GlyphCoverage? hasGlyph}) {
  final out = <EditDiagnostic>[];
  for (final id in ids ?? document.nodes.keys) {
    final n = document[id];
    if (n == null) continue;
    final json = n.toJson();
    final type = n.type;
    final at = editPointer('/nodes', id);
    // Characters the font cannot draw.
    if (hasGlyph != null && type == 'text') {
      final props = readMap(json['props']);
      final text = readString(props?['text']) ?? '';
      final family = readString(readMap(props?['style'])?['fontFamily']);
      final missing = <int>{
        for (final r in text.runes)
          if (r > 0x7E && r != 0xA0 && !(r >= 0x2000 && r <= 0x200F) && !hasGlyph(family, r)) r,
      };
      if (missing.isNotEmpty) {
        final chars = missing.map((r) => '"${String.fromCharCode(r)}" (U+${r.toRadixString(16).toUpperCase().padLeft(4, '0')})').join(', ');
        final icons = {for (final r in missing) if (symbolIcons[r] case final String i) String.fromCharCode(r): i};
        out.add(EditDiagnostic.of(EditCodes.missingGlyph, -1,
            '"$id" has characters the font cannot draw: $chars; they show as empty boxes. Use an icon node instead '
            '(a row of text, icon, text)${icons.isEmpty ? '' : ': ${[for (final e in icons.entries) '${e.key} is {"type": "icon", "props": {"icon": "${e.value}"}}'].join('; ')}'}, '
            'or write it in words.',
            path: editPointer(editPointer(at, 'props'), 'text'), nodeId: id));
      }
    }
    // A tap target with nothing in it.
    if (_tappable(json) && n.childIds.isEmpty && const {'box', 'row', 'column', 'stack', 'wrap'}.contains(type)) {
      final label = '{"op": "set", "id": "${id}Label", "parent": "$id", "node": {"type": "text", "layout": {"width": {"hug": 120}, '
          '"height": {"hug": 20}}, "props": {"text": "...", "style": {"fontSize": 15, "fontWeight": 600, "color": "#FFFFFFFF"}}}}';
      out.add(EditDiagnostic.of(EditCodes.emptyButton, -1,
          '"$id" reacts to a tap but shows nothing: a $type with no children has no label. ${type == 'box' ? 'A box takes no children: set "$id" again as a row (same layout, decoration and actions, '
              '"props": {"mainAxisAlignment": "center", "crossAxisAlignment": "center"}), then add its label: ' : 'Add its label: '}'
          '$label. Or use a filledButton with "label".',
          path: at, nodeId: id));
    }
    // A button that does nothing: no reaction, not disabled (a mock-up's
    // Start and Pause, plan_progress@claude-haiku-5-5).
    // A component counts when it is a button by name and fires a press (a
    // list row or chip may be shown only, with no reaction).
    final pressEvent = type.endsWith('Button') ? n.spec?.events.where((e) => e.key == 'onPressed').firstOrNull?.key : null;
    if ((_buttons.contains(type) || pressEvent != null) &&
        (readList(json['actions']) ?? const []).isEmpty &&
        readMap(json['props'])?['enabled'] != false &&
        !(readMap(json['bind'])?.containsKey('props.enabled') ?? false) &&
        !_insideTappable(document, id)) {
      final trigger = pressEvent == null ? '{"type": "click"}' : '{"type": "event", "event": "$pressEvent"}';
      out.add(EditDiagnostic.of(EditCodes.deadControl, -1,
          '"$id" ($type) does nothing when pressed: it has no reaction. Give it what it does: "actions": [{"trigger": $trigger, '
          '"actions": [{"type": "setVariable", ...}]}] (a variable the UI reads: a step, a running flag), or "enabled": false '
          'while it should not be pressed.',
          path: editPointer(at, 'actions'), nodeId: id));
    }
    // Text in the color of what is behind it.
    if (type == 'text') {
      final bind = readMap(json['bind']) ?? const {};
      if (bind.keys.any((k) => k == 'props.style.color' || k == 'props.style' || k == 'props.text.color')) continue;
      final style = readMap(readMap(json['props'])?['style']);
      final color = _color(style?['color']);
      final bg = _background(document, id);
      if (bg == null) continue;
      final fg = color ?? 0xFF000000;
      final ratio = _contrast(fg, bg.$2);
      if (ratio < 1.6) {
        out.add(EditDiagnostic.of(EditCodes.lowContrast, -1,
            '${color == null ? '"$id" has no text color: it draws in the default (near black)' : '"$id" is drawn in ${_hex(fg)}'} over '
            '${_hex(bg.$2)} (the fill of "${bg.$1}"): contrast ${ratio.toStringAsFixed(2)}:1, it is not readable. Set "props": {"style": '
            '{"color": "${_hex(_luminance(bg.$2) > 0.4 ? 0xFF111827 : 0xFFFFFFFF)}"}}.',
            path: editPointer(editPointer(editPointer(at, 'props'), 'style'), 'color'), nodeId: id));
      }
    }
  }
  return out;
}