check method

Future<DesignAlignmentReport> check(
  1. BuildContext context, {
  2. Future<T?> runAsync<T>(
    1. Future<T> work()
    )?,
})

Checks every button, select, stepper, segmented control, group of choices and tab bar under context (on screen, under a repaint boundary), when the screen is at least from wide. A test passes its tester's runAsync (reading pixels takes real time); null reads them directly.

Implementation

Future<DesignAlignmentReport> check(
  BuildContext context, {
  Future<T?> Function<T>(Future<T> Function() work)? runAsync,
}) async {
  final found = <String>[
    for (final MapEntry(key: kind, value: limit) in limits.entries)
      if (isToDoReason(limit.reason))
        'a limit for ${kind.plural}: "${limit.reason}" is a to-do, not a '
            'reason',
  ];
  final root = context.findRenderObject();
  final screen = MediaQuery.maybeSizeOf(context)?.width;
  if (root == null || (screen != null && screen < from)) {
    return DesignAlignmentReport(look, found);
  }
  final marked = _markedFaces(context);
  final anchors = _anchorBoxes(context);
  final finder = _DrawnReader(null, null, marked);
  final items =
      <
        ({
          RenderBox box,
          RenderBox? control,
          List<RenderBox> held,
          DesignWidthKind kind,
        })
      >[];
  final controls = <RenderBox>[];
  void visit(RenderObject node) {
    if (node is RenderBox && node.hasSize && _isControl(node)) {
      // A modal barrier (a tap outside a dialog closes it) takes taps and
      // may be named ('Dismiss'), but it is the screen round the dialog,
      // no button: no width to hold.
      if (_isBarrier(node)) return;
      controls.add(node);
      final kind =
          _kindOf(node, anchors) ??
          (_wrappedWords(node) == null ? null : DesignWidthKind.button);
      if (kind != null) {
        items.add((box: node, control: node, held: [node], kind: kind));
      }
      return;
    }
    // Two or more controls side by side: a segmented control or a
    // stepper, measured whole.
    final held = <RenderBox>[];
    var groups = 0;
    _visitShown(node, (child) {
      final under = [
        for (final c
            in child is RenderBox && child.hasSize && _isControl(child)
                ? [child]
                : finder._controlsUnder(child))
          if (!_isBarrier(c)) c,
      ];
      if (under.isNotEmpty) groups++;
      held.addAll(under);
    });
    if (node is RenderBox &&
        node.hasSize &&
        groups >= 2 &&
        DesignRowCheck._sideBySide(held)) {
      final kind = _groupKind(finder, node, held);
      if (kind != null) {
        items.add((box: node, control: null, held: held, kind: kind));
        return;
      }
    }
    _visitShown(node, visit);
  }

  visit(root);
  final readers = <RenderRepaintBoundary, _RowReader>{};
  Future<_RowReader?> readerFor(RenderObject node) async {
    final boundary = _drawnIn(node);
    if (boundary == null) return null;
    if (readers[boundary] case final r?) return r;
    final pixels = await DrawnPixels.read(boundary, pixelRatio, runAsync);
    return readers[boundary] = _RowReader(_drawn, boundary, pixels, marked);
  }

  final rtl = Directionality.maybeOf(context) == TextDirection.rtl;
  for (var i = 0; i < items.length; i++) {
    final item = items[i];
    final reader = await readerFor(item.box);
    if (reader == null) continue;
    if (item.control case final control?
        when _isListRow(
          reader,
          control,
          controls,
          rtl,
          select: item.kind == DesignWidthKind.select,
        )) {
      continue;
    }
    if (item.kind == DesignWidthKind.choiceGroup ||
        item.kind == DesignWidthKind.tabBar) {
      final tabs = item.kind == DesignWidthKind.tabBar;
      final m = _itemsWidth(reader, item.held, tabs: tabs);
      if (m == null) {
        // Choices with no face each of their own (a navigation bar's
        // destinations): each read on its own.
        if (!tabs) {
          for (final c in item.held) {
            if (_kindOf(c, anchors) case final kind?) {
              items.add((box: c, control: c, held: [c], kind: kind));
            }
          }
        }
        continue;
      }
      final limit = limits[item.kind]?.maxWidth ?? maxWidth;
      final allowed = math.max(m.room, limit);
      if (m.laid.width <= allowed + tolerance ||
          m.drawn.width <= allowed + tolerance) {
        continue;
      }
      final what = tabs ? 'tab' : 'choice';
      found.add(
        '${_kindName(item.kind, item.held.first)}: '
        '${_px(m.laid.width)} px wide as laid out, ${_px(m.drawn.width)} as '
        "drawn; its ${m.count} ${what}s' content and padding take "
        '${_px(m.content)}, ${_px(m.room)} with ${_px(_itemRoom)} a $what '
        'and the gaps (at most ${_px(limit)} from ${_px(from)} wide)',
      );
      continue;
    }
    // A button whose words wrap: narrower than its content, whatever its
    // width.
    if (item.control case final control?
        when item.kind == DesignWidthKind.button ||
            item.kind == DesignWidthKind.select) {
      if (_wrappedWords(control) case final p?) {
        final line = p.getFullHeightForCaret(const TextPosition(offset: 0));
        final lines = line > 0 ? (p.size.height / line).round() : 2;
        found.add(
          '${_kindName(item.kind, control)}: its words wrap onto $lines '
          'lines in ${_px(p.size.width)} px; on one line they take '
          '${_px(p.getMaxIntrinsicWidth(double.infinity))} (from '
          '${_px(from)} wide ${item.kind.plural} keep their words on one '
          'line)',
        );
        continue;
      }
    }
    final face = item.control == null
        ? _groupFace(reader, item.box, item.held)
        : reader._face(item.control!);
    if (face == null) continue;
    // A group's content is at least its controls' own, side by side (a
    // face painted behind them holds none of it).
    final own = item.control != null
        ? null
        : item.held.fold<double?>(0, (sum, c) {
            final w = _contentWidth(c, c.size.height);
            return sum == null || w == null ? null : sum + w;
          });
    final faceWidth = _contentWidth(face.box, face.box.size.height);
    final natural = faceWidth == null && own == null
        ? null
        : math.max(faceWidth ?? 0, own ?? 0);
    final limit = limits[item.kind]?.maxWidth ?? maxWidth;
    final allowed = math.max(natural ?? 0, limit);
    if (face.rect.width <= allowed + tolerance) continue;
    final drawn = marked.contains(face.box)
        ? face.rect
        : reader._outline(
                face.rect,
                item.control ?? item.box,
                face.read ? null : face.box,
                null,
              ) ??
              face.rect;
    if (drawn.width <= allowed + tolerance) continue;
    final takes = natural == null
        ? ''
        : '; its content and padding take ${_px(natural)}';
    found.add(
      '${_kindName(item.kind, item.control ?? item.box)}: '
      '${_px(face.rect.width)} px wide as laid out, ${_px(drawn.width)} as '
      'drawn$takes (at most ${_px(limit)} from ${_px(from)} wide)',
    );
  }
  return DesignAlignmentReport(look, found);
}