text: Add proportionalLetterSpacing

To confirm that [TextStyle.letterSpacing] is taken literally as
logical pixels, as its dartdoc suggests it is, I rendered the text
"||" with an extreme [TextStyle.letterSpacing] value of 40. Then it
was easy to see that the letter spacing -- the horizontal distance
between the two "|" characters -- wasn't changing as I adjusted the
text-size slider in my iPhone settings.

In the tests, the `textScaleFactors` list is copied from
emoji_reaction_test. Perhaps there's a convenient place to define it
centrally.

Author: chrisbobbe

lib/widgets/text.dart

@@ -280,3 +280,22 @@ FontWeight clampVariableFontWeight(double wght) {
 /// font's own custom-defined "wght" axis. But it's a great guess,
 /// at least without knowledge of the particular font.
 double wghtFromFontWeight(FontWeight fontWeight) => fontWeight.value.toDouble();
+
+/// A [TextStyle.letterSpacing] value from a given proportion of the font size.
+///
+/// Returns [baseFontSize] scaled by the ambient [MediaQueryData.textScaler],
+/// multiplied by [proportion] (e.g., 0.01).
+///
+/// Using [MediaQueryData.textScaler] ensures that [proportion] is still
+/// respected when the device font size setting is adjusted.
+/// To opt out of this behavior, pass [TextScaler.noScaling] or some other value
+/// for [textScaler].
+double proportionalLetterSpacing(
+  BuildContext context,
+  double proportion, {
+  required double baseFontSize,
+  TextScaler? textScaler,
+}) {
+  final effectiveTextScaler = textScaler ?? MediaQuery.textScalerOf(context);
+  return effectiveTextScaler.scale(baseFontSize) * proportion;
+}

test/widgets/text_test.dart

@@ -1,4 +1,3 @@
-
 import 'package:checks/checks.dart';
 import 'package:flutter/material.dart';
 import 'package:flutter_test/flutter_test.dart';
@@ -207,4 +206,65 @@ void main() {
     check(clampVariableFontWeight(999))  .equals(FontWeight.w900);
     check(clampVariableFontWeight(1000)) .equals(FontWeight.w900);
   });
+
+  group('proportionalLetterSpacing', () {
+    Future<void> testLetterSpacing(
+      String description, {
+      required double Function(BuildContext context) getValue,
+      double? ambientTextScaleFactor,
+      required double expected,
+    }) async {
+      testWidgets(description, (WidgetTester tester) async {
+        if (ambientTextScaleFactor != null) {
+          tester.platformDispatcher.textScaleFactorTestValue = ambientTextScaleFactor;
+          addTearDown(tester.platformDispatcher.clearTextScaleFactorTestValue);
+        }
+        await tester.pumpWidget(
+          MaterialApp(
+            home: Builder(builder: (context) => Text('',
+              style: TextStyle(letterSpacing: getValue(context))))));
+
+        final TextStyle? style = tester.widget<Text>(find.byType(Text)).style;
+        final actualLetterSpacing = style!.letterSpacing!;
+        check((actualLetterSpacing - expected).abs()).isLessThan(0.0001);
+      });
+    }
+
+    // From trying the options on an iPhone 13 Pro running iOS 16.6.1:
+    const textScaleFactors = <double>[
+      0.8235, // smallest
+      1,
+      1.3529, // largest without using the "Larger Accessibility Sizes" setting
+      3.1176, // largest
+    ];
+
+    testLetterSpacing('smoke 1',
+      getValue: (context) => proportionalLetterSpacing(context, 0.01, baseFontSize: 14),
+      expected: 0.14);
+
+    testLetterSpacing('smoke 2',
+      getValue: (context) => proportionalLetterSpacing(context, 0.02, baseFontSize: 16),
+      expected: 0.32);
+
+    for (final textScaleFactor in textScaleFactors) {
+      testLetterSpacing('ambient text scale factor $textScaleFactor, no override',
+        ambientTextScaleFactor: textScaleFactor,
+        getValue: (context) => proportionalLetterSpacing(context, 0.01, baseFontSize: 14),
+        expected: 0.14 * textScaleFactor);
+
+      testLetterSpacing('ambient text scale factor $textScaleFactor, override with no scaling',
+        ambientTextScaleFactor: textScaleFactor,
+        getValue: (context) => proportionalLetterSpacing(context,
+          0.01, baseFontSize: 14, textScaler: TextScaler.noScaling),
+        expected: 0.14);
+
+      final clampingTextScaler = TextScaler.linear(textScaleFactor)
+        .clamp(minScaleFactor: 0.9, maxScaleFactor: 1.1);
+      testLetterSpacing('ambient text scale factor $textScaleFactor, override with clamping',
+        ambientTextScaleFactor: textScaleFactor,
+        getValue: (context) => proportionalLetterSpacing(context,
+          0.01, baseFontSize: 14, textScaler: clampingTextScaler),
+        expected: clampingTextScaler.scale(14) * 0.01);
+    }
+  });
 }