text: Introduce TextWithLink widget

Fixes part of #1285.

In particular this handles the case we need at the moment for #667,
read receipts: a sentence with a single link in the middle of it.

Other cases noted in #1285 are for a code font; or italics; or
inserting more string fragments before and after a tagged string
(for a Markdown link in quote-and-reply).  There's also #1553
which calls for a sentence with two different links in it (to
use in an empty inbox).

Author: gnprice

lib/widgets/text.dart

@@ -1,8 +1,11 @@
 import 'dart:io';
 import 'package:collection/collection.dart';
 import 'package:flutter/foundation.dart';
+import 'package:flutter/gestures.dart';
 import 'package:flutter/material.dart';
 
+import 'theme.dart';
+
 /// An app-wide [Typography] for Zulip, customized from the Material default.
 ///
 /// Include this in the app-wide [MaterialApp.theme].
@@ -415,3 +418,102 @@ TextBaseline localizedTextBaseline(BuildContext context) {
     ScriptCategory.tall => TextBaseline.alphabetic,
   };
 }
+
+/// A text widget with an embedded link.
+///
+/// The text and link are given in [markup], in a simple HTML-like markup.
+/// The markup string must not contain arbitrary user-controlled text.
+///
+/// The portion of the text that is the link will be styled as a link,
+/// and will respond to taps by calling the [onTap] callback.
+///
+/// If the entire text is meant to be a link, there's no need for this widget;
+/// instead, use [Text] inside a [GestureDetector], with [GestureDetector.onTap]
+/// invoking [PlatformActions.launchUrl].
+///
+/// TODO(#1285): Integrate this with l10n so that the markup can be parsed
+///   from the constant translated string, with placeholders for any variables,
+///   rather than the string that results from interpolating variables.
+///   That way it'll be fine to interpolate variables with arbitrary text.
+/// TODO(#1285): Generalize this to other styling, like code font and italics.
+/// TODO(#1553): Generalize this to multiple links in one string.
+class TextWithLink extends StatefulWidget {
+  const TextWithLink({super.key, this.style, required this.onTap, required this.markup});
+
+  final TextStyle? style;
+
+  /// A callback to be called when the user taps the link.
+  ///
+  /// Consider using [PlatformActions.launchUrl] to open a web page,
+  /// or [Navigator.push] to open a page of the app.
+  final VoidCallback onTap;
+
+  /// The text to display, in a simple HTML-like markup.
+  ///
+  /// This string must contain the tags `<z-link>` and `</z-link>` as substrings,
+  /// in that order, and must contain no other `<` characters.
+  ///
+  /// In particular this means the string must not contain any arbitrary
+  /// user-controlled text, which might have '<' characters.
+  ///
+  /// The contents other than the two tags will be shown as text.
+  /// The portion between the tags will be the link.
+  //
+  // (Why the name `<z-link>`?  Well, it matches Zulip web's practice;
+  // and here's the reasoning for that name there:
+  //   https://github.com/zulip/zulip/pull/18075#discussion_r611067127
+  // )
+  final String markup;
+
+  @override
+  State<TextWithLink> createState() => _TextWithLinkState();
+}
+
+class _TextWithLinkState extends State<TextWithLink> {
+  late final GestureRecognizer _recognizer;
+
+  @override
+  void initState() {
+    super.initState();
+    _recognizer = TapGestureRecognizer()
+      ..onTap = widget.onTap;
+  }
+
+  @override
+  void dispose() {
+    _recognizer.dispose();
+    super.dispose();
+  }
+
+  static final _markupPattern = RegExp(r'^([^<]*)<z-link>([^<]*)</z-link>([^<]*)$');
+
+  @override
+  Widget build(BuildContext context) {
+    final designVariables = DesignVariables.of(context);
+
+    final match = _markupPattern.firstMatch(widget.markup);
+    final InlineSpan span;
+    if (match == null) {
+      // TODO(log): The markup text was invalid.
+      // Probably a translation (used by this widget's caller) didn't carry the
+      // syntax through correctly.
+      // This can also happen if the markup string contains user-controlled
+      // text (which is a bug) and that introduced a '<' character.
+      // Fall back to showing plain text.
+      // (It's important not to try to interpret any markup here, in case it
+      // comes buggily from user-controlled text.)
+      span = TextSpan(text: widget.markup);
+    } else {
+      span = TextSpan(text: match.group(1), children: [
+        TextSpan(text: match.group(2), recognizer: _recognizer,
+          style: TextStyle(
+            decoration: TextDecoration.underline,
+            color: designVariables.link,
+            decorationColor: designVariables.link)),
+        TextSpan(text: match.group(3)),
+      ]);
+    }
+
+    return Text.rich(span, style: widget.style);
+  }
+}

test/widgets/text_test.dart

@@ -1,6 +1,7 @@
 import 'package:checks/checks.dart';
 import 'package:collection/collection.dart';
 import 'package:flutter/material.dart';
+import 'package:flutter_checks/flutter_checks.dart';
 import 'package:flutter_test/flutter_test.dart';
 import 'package:zulip/widgets/text.dart';
 
@@ -418,4 +419,53 @@ void main() {
     // "und" is a special language code meaning undefined; see [Locale]
     testLocalizedTextBaseline(const Locale('und'), TextBaseline.alphabetic);
   });
+
+  group('TextWithLink', () {
+    testWidgets('responds correctly to taps', (tester) async {
+      int calls = 0;
+      addTearDown(testBinding.reset);
+      await tester.pumpWidget(TestZulipApp(
+        child: Center(
+          child: TextWithLink(onTap: () => calls++,
+            markup: 'asd <z-link>fgh</z-link> jkl'))));
+      await tester.pump();
+
+      final findText = find.text('asd fgh jkl', findRichText: true);
+      final center = tester.getCenter(findText);
+      final width = tester.getSize(findText).width;
+
+      // No response to tapping the words not in the link.
+      await tester.tapAt(center + Offset(-0.3 * width, 0));
+      check(calls).equals(0);
+      await tester.tapAt(center + Offset(0.3 * width, 0));
+      check(calls).equals(0);
+
+      // Tapping the word in the link calls the callback.
+      await tester.tapAt(center);
+      check(calls).equals(1);
+      await tester.tapAt(center);
+      check(calls).equals(2);
+    });
+
+    testWidgets('rejects extra tags', (tester) async {
+      final markup = '<z-link>spurious</z-link><z-link>markup</z-link>';
+      final plainText = 'spuriousmarkup';
+
+      int calls = 0;
+      addTearDown(testBinding.reset);
+      await tester.pumpWidget(TestZulipApp(
+        child: Center(
+          child: TextWithLink(onTap: () => calls++,
+            markup: markup))));
+      await tester.pump();
+
+      // The widget appears with the markup string as plain text.
+      check(find.text(plainText, findRichText: true)).findsNothing();
+      check(find.text(markup)).findsOne();
+
+      // Nothing happens on tapping it.
+      await tester.tap(find.text(markup));
+      check(calls).equals(0);
+    });
+  });
 }