Expose text boundary combiner class (#112085)

Author: chunhtai

packages/flutter/lib/src/painting/text_painter.dart

@@ -1129,12 +1129,6 @@ class TextPainter {
   /// {@endtemplate}
   TextRange getWordBoundary(TextPosition position) {
     assert(_debugAssertTextLayoutIsValid);
-    // TODO(chunhtai): remove this workaround once ui.Paragraph.getWordBoundary
-    // can handle caret position.
-    // https://github.com/flutter/flutter/issues/111751.
-    if (position.affinity == TextAffinity.upstream) {
-      position = TextPosition(offset: position.offset - 1);
-    }
     return _paragraph!.getWordBoundary(position);
   }
 

packages/flutter/lib/src/services/text_boundary.dart

@@ -38,6 +38,18 @@ abstract class TextBoundary {
       end: getTrailingTextBoundaryAt(position).offset,
     );
   }
+
+  /// Gets the boundary by calling the left-hand side and pipe the result to
+  /// right-hand side.
+  ///
+  /// Combining two text boundaries can be useful if one wants to ignore certain
+  /// text before finding the text boundary. For example, use
+  /// [WhitespaceBoundary] + [WordBoundary] to ignores any white space before
+  /// finding word boundary if the input position happens to be a whitespace
+  /// character.
+  TextBoundary operator +(TextBoundary other) {
+    return _ExpandedTextBoundary(inner: other, outer: this);
+  }
 }
 
 /// A text boundary that uses characters as logical boundaries.
@@ -110,7 +122,7 @@ class CharacterBoundary extends TextBoundary {
 /// This class uses [UAX #29](https://unicode.org/reports/tr29/) defined word
 /// boundaries to calculate its logical boundaries.
 class WordBoundary extends TextBoundary {
-  /// Creates a [CharacterBoundary] with the text and layout information.
+  /// Creates a [WordBoundary] with the text and layout information.
   const WordBoundary(this._textLayout);
 
   final TextLayoutMetrics _textLayout;
@@ -122,21 +134,27 @@ class WordBoundary extends TextBoundary {
       affinity: TextAffinity.downstream,  // ignore: avoid_redundant_argument_values
     );
   }
+
   @override
   TextPosition getTrailingTextBoundaryAt(TextPosition position) {
     return TextPosition(
       offset: _textLayout.getWordBoundary(position).end,
       affinity: TextAffinity.upstream,
     );
   }
+
+  @override
+  TextRange getTextBoundaryAt(TextPosition position) {
+    return _textLayout.getWordBoundary(position);
+  }
 }
 
 /// A text boundary that uses line breaks as logical boundaries.
 ///
 /// The input [TextPosition]s will be interpreted as caret locations if
 /// [TextLayoutMetrics.getLineAtOffset] is text-affinity-aware.
 class LineBreak extends TextBoundary {
-  /// Creates a [CharacterBoundary] with the text and layout information.
+  /// Creates a [LineBreak] with the text and layout information.
   const LineBreak(this._textLayout);
 
   final TextLayoutMetrics _textLayout;
@@ -155,14 +173,19 @@ class LineBreak extends TextBoundary {
       affinity: TextAffinity.upstream,
     );
   }
+
+  @override
+  TextRange getTextBoundaryAt(TextPosition position) {
+    return _textLayout.getLineAtOffset(position);
+  }
 }
 
 /// A text boundary that uses the entire document as logical boundary.
 ///
 /// The document boundary is unique and is a constant function of the input
 /// position.
 class DocumentBoundary extends TextBoundary {
-  /// Creates a [CharacterBoundary] with the text
+  /// Creates a [DocumentBoundary] with the text
   const DocumentBoundary(this._text);
 
   final String _text;
@@ -177,3 +200,149 @@ class DocumentBoundary extends TextBoundary {
     );
   }
 }
+
+/// A text boundary that uses the first non-whitespace character as the logical
+/// boundary.
+///
+/// This text boundary uses [TextLayoutMetrics.isWhitespace] to identify white
+/// spaces, this includes newline characters from ASCII and separators from the
+/// [unicode separator category](https://en.wikipedia.org/wiki/Whitespace_character).
+class WhitespaceBoundary extends TextBoundary {
+  /// Creates a [WhitespaceBoundary] with the text.
+  const WhitespaceBoundary(this._text);
+
+  final String _text;
+
+  @override
+  TextPosition getLeadingTextBoundaryAt(TextPosition position) {
+    // Handles outside of string end.
+    if (position.offset > _text.length || (position.offset == _text.length  && position.affinity == TextAffinity.downstream)) {
+      position = TextPosition(offset: _text.length, affinity: TextAffinity.upstream);
+    }
+    // Handles outside of string start.
+    if (position.offset <= 0) {
+      return const TextPosition(offset: 0);
+    }
+    int index = position.offset;
+    if (position.affinity == TextAffinity.downstream && !TextLayoutMetrics.isWhitespace(_text.codeUnitAt(index))) {
+      return position;
+    }
+
+    while ((index -= 1) >= 0) {
+      if (!TextLayoutMetrics.isWhitespace(_text.codeUnitAt(index))) {
+        return TextPosition(offset: index + 1, affinity: TextAffinity.upstream);
+      }
+    }
+    return const TextPosition(offset: 0);
+  }
+
+  @override
+  TextPosition getTrailingTextBoundaryAt(TextPosition position) {
+    // Handles outside of right bound.
+    if (position.offset >= _text.length) {
+      return TextPosition(offset: _text.length, affinity: TextAffinity.upstream);
+    }
+    // Handles outside of left bound.
+    if (position.offset < 0 || (position.offset == 0 && position.affinity == TextAffinity.upstream)) {
+      position = const TextPosition(offset: 0);
+    }
+
+    int index = position.offset;
+    if (position.affinity == TextAffinity.upstream && !TextLayoutMetrics.isWhitespace(_text.codeUnitAt(index - 1))) {
+      return position;
+    }
+
+    for (; index < _text.length; index += 1) {
+      if (!TextLayoutMetrics.isWhitespace(_text.codeUnitAt(index))) {
+        return TextPosition(offset: index);
+      }
+    }
+    return TextPosition(offset: _text.length, affinity: TextAffinity.upstream);
+  }
+}
+
+/// Gets the boundary by calling the [outer] and pipe the result to
+/// [inner].
+class _ExpandedTextBoundary extends TextBoundary {
+  /// Creates a [_ExpandedTextBoundary] with inner and outter boundaries
+  const _ExpandedTextBoundary({required this.inner, required this.outer});
+
+  /// The inner boundary to call with the result from [outer].
+  final TextBoundary inner;
+
+  /// The outer boundary to call with the input position.
+  ///
+  /// The result is piped to the [inner] before returning to the caller.
+  final TextBoundary outer;
+
+  @override
+  TextPosition getLeadingTextBoundaryAt(TextPosition position) {
+    return inner.getLeadingTextBoundaryAt(
+      outer.getLeadingTextBoundaryAt(position),
+    );
+  }
+
+  @override
+  TextPosition getTrailingTextBoundaryAt(TextPosition position) {
+    return inner.getTrailingTextBoundaryAt(
+      outer.getTrailingTextBoundaryAt(position),
+    );
+  }
+}
+
+/// A text boundary that will push input text position forward or backward
+/// one affinity
+///
+/// To push a text position forward one affinity unit, this proxy converts
+/// affinity to downstream if it is upstream; otherwise it increase the offset
+/// by one with its affinity sets to upstream. For example,
+/// `TextPosition(1, upstream)` becomes `TextPosition(1, downstream)`,
+/// `TextPosition(4, downstream)` becomes `TextPosition(5, upstream)`.
+///
+/// See also:
+/// * [PushTextPosition.forward], a text boundary to push the input position
+///   forward.
+/// * [PushTextPosition.backward], a text boundary to push the input position
+///   backward.
+class PushTextPosition extends TextBoundary {
+  const PushTextPosition._(this._forward);
+
+  /// A text boundary that pushes the input position forward.
+  static const TextBoundary forward = PushTextPosition._(true);
+
+  /// A text boundary that pushes the input position backward.
+  static const TextBoundary backward = PushTextPosition._(false);
+
+  /// Whether to push the input position forward or backward.
+  final bool _forward;
+
+  TextPosition _calculateTargetPosition(TextPosition position) {
+    if (_forward) {
+      switch(position.affinity) {
+        case TextAffinity.upstream:
+          return TextPosition(offset: position.offset);
+        case TextAffinity.downstream:
+          return position = TextPosition(
+            offset: position.offset + 1,
+            affinity: TextAffinity.upstream,
+          );
+      }
+    } else {
+      switch(position.affinity) {
+        case TextAffinity.upstream:
+          return position = TextPosition(offset: position.offset - 1);
+        case TextAffinity.downstream:
+          return TextPosition(
+            offset: position.offset,
+            affinity: TextAffinity.upstream,
+          );
+      }
+    }
+  }
+
+  @override
+  TextPosition getLeadingTextBoundaryAt(TextPosition position) => _calculateTargetPosition(position);
+
+  @override
+  TextPosition getTrailingTextBoundaryAt(TextPosition position) => _calculateTargetPosition(position);
+}