Update docs about complex character support (#66582)

Simple docs fix for characters.

packages/flutter/lib/src/cupertino/text_field.dart

@@ -482,32 +482,7 @@ class CupertinoTextField extends StatefulWidget {
   /// Whitespace characters (e.g. newline, space, tab) are included in the
   /// character count.
   ///
-  /// ## Limitations
-  ///
-  /// The CupertinoTextField does not currently count Unicode grapheme clusters
-  /// (i.e. characters visible to the user), it counts Unicode scalar values,
-  /// which leaves out a number of useful possible characters (like many emoji
-  /// and composed characters), so this will be inaccurate in the presence of
-  /// those characters. If you expect to encounter these kinds of characters, be
-  /// generous in the maxLength used.
-  ///
-  /// For instance, the character "ö" can be represented as '\u{006F}\u{0308}',
-  /// which is the letter "o" followed by a composed diaeresis "¨", or it can
-  /// be represented as '\u{00F6}', which is the Unicode scalar value "LATIN
-  /// SMALL LETTER O WITH DIAERESIS". In the first case, the text field will
-  /// count two characters, and the second case will be counted as one
-  /// character, even though the user can see no difference in the input.
-  ///
-  /// Similarly, some emoji are represented by multiple scalar values. The
-  /// Unicode "THUMBS UP SIGN + MEDIUM SKIN TONE MODIFIER", "👍🏽", should be
-  /// counted as a single character, but because it is a combination of two
-  /// Unicode scalar values, '\u{1F44D}\u{1F3FD}', it is counted as two
-  /// characters.
-  ///
-  /// See also:
-  ///
-  ///  * [LengthLimitingTextInputFormatter] for more information on how it
-  ///    counts characters, and how it may differ from the intuitive meaning.
+  /// {@macro flutter.services.lengthLimitingTextInputFormatter.maxLength}
   final int? maxLength;
 
   /// If true, prevents the field from allowing more than [maxLength]

packages/flutter/lib/src/material/text_field.dart

@@ -578,32 +578,7 @@ class TextField extends StatefulWidget {
   /// to the [decoration]'s [InputDecoration.errorStyle] when the limit is
   /// exceeded.
   ///
-  /// ## Limitations
-  ///
-  /// The text field does not currently count Unicode grapheme clusters (i.e.
-  /// characters visible to the user), it counts Unicode scalar values, which
-  /// leaves out a number of useful possible characters (like many emoji and
-  /// composed characters), so this will be inaccurate in the presence of those
-  /// characters. If you expect to encounter these kinds of characters, be
-  /// generous in the maxLength used.
-  ///
-  /// For instance, the character "ö" can be represented as '\u{006F}\u{0308}',
-  /// which is the letter "o" followed by a composed diaeresis "¨", or it can
-  /// be represented as '\u{00F6}', which is the Unicode scalar value "LATIN
-  /// SMALL LETTER O WITH DIAERESIS". In the first case, the text field will
-  /// count two characters, and the second case will be counted as one
-  /// character, even though the user can see no difference in the input.
-  ///
-  /// Similarly, some emoji are represented by multiple scalar values. The
-  /// Unicode "THUMBS UP SIGN + MEDIUM SKIN TONE MODIFIER", "👍🏽", should be
-  /// counted as a single character, but because it is a combination of two
-  /// Unicode scalar values, '\u{1F44D}\u{1F3FD}', it is counted as two
-  /// characters.
-  ///
-  /// See also:
-  ///
-  ///  * [LengthLimitingTextInputFormatter] for more information on how it
-  ///    counts characters, and how it may differ from the intuitive meaning.
+  /// {@macro flutter.services.lengthLimitingTextInputFormatter.maxLength}
   final int maxLength;
 
   /// If true, prevents the field from allowing more than [maxLength]

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

@@ -316,31 +316,33 @@ class LengthLimitingTextInputFormatter extends TextInputFormatter {
   LengthLimitingTextInputFormatter(this.maxLength)
     : assert(maxLength == null || maxLength == -1 || maxLength > 0);
 
-  /// The limit on the number of characters (i.e. Unicode scalar values) this formatter
+  /// The limit on the number of user-perceived characters that this formatter
   /// will allow.
   ///
   /// The value must be null or greater than zero. If it is null or -1, then no
   /// limit is enforced.
   ///
-  /// This formatter does not currently count Unicode grapheme clusters (i.e.
-  /// characters visible to the user), it counts Unicode scalar values, which leaves
-  /// out a number of useful possible characters (like many emoji and composed
-  /// characters), so this will be inaccurate in the presence of those
-  /// characters. If you expect to encounter these kinds of characters, be
-  /// generous in the maxLength used.
+  /// {@template flutter.services.lengthLimitingTextInputFormatter.maxLength}
+  /// ## Characters
+  ///
+  /// For a specific definition of what is considered a character, see the
+  /// [characters](https://pub.dev/packages/characters) package on Pub, which is
+  /// what Flutter uses to delineate characters. In general, even complex
+  /// characters like surrogate pairs and extended grapheme clusters are
+  /// correctly interpreted by Flutter as each being a single user-perceived
+  /// character.
   ///
   /// For instance, the character "ö" can be represented as '\u{006F}\u{0308}',
   /// which is the letter "o" followed by a composed diaeresis "¨", or it can
   /// be represented as '\u{00F6}', which is the Unicode scalar value "LATIN
-  /// SMALL LETTER O WITH DIAERESIS". In the first case, the text field will
-  /// count two characters, and the second case will be counted as one
-  /// character, even though the user can see no difference in the input.
+  /// SMALL LETTER O WITH DIAERESIS". It will be counted as a single character
+  /// in both cases.
   ///
   /// Similarly, some emoji are represented by multiple scalar values. The
-  /// Unicode "THUMBS UP SIGN + MEDIUM SKIN TONE MODIFIER", "👍🏽", should be
-  /// counted as a single character, but because it is a combination of two
-  /// Unicode scalar values, '\u{1F44D}\u{1F3FD}', it is counted as two
-  /// characters.
+  /// Unicode "THUMBS UP SIGN + MEDIUM SKIN TONE MODIFIER", "👍🏽"is counted as
+  /// a single character, even though it is a combination of two Unicode scalar
+  /// values, '\u{1F44D}\u{1F3FD}'.
+  /// {@endtemplate}
   ///
   /// ### Composing text behaviors
   ///
@@ -352,7 +354,8 @@ class LengthLimitingTextInputFormatter extends TextInputFormatter {
   /// composing is not allowed.
   final int? maxLength;
 
-  /// Truncate the given TextEditingValue to maxLength characters.
+  /// Truncate the given TextEditingValue to maxLength user-perceived
+  /// characters.
   ///
   /// See also:
   ///  * [Dart's characters package](https://pub.dev/packages/characters).