Merge pull request #682 from tneotia/feature/selectable-text

Add support for selectable text via SelectableText.rich

Author: erickok

README.md

@@ -34,6 +34,8 @@ A Flutter widget for rendering HTML and CSS as Flutter widgets.
 - [API Reference](#api-reference)
 
   - [Constructors](#constructors)
+  
+    - [Selectable Text](#selectable-text) 
 
   - [Parameters Table](#parameters)
 
@@ -143,14 +145,30 @@ For a full example, see [here](https://github.com/Sub6Resources/flutter_html/tre
 
 Below, you will find brief descriptions of the parameters the`Html` widget accepts and some code snippets to help you use this package.
 
-## Constructors:
+### Constructors:
 
 The package currently has two different constructors - `Html()` and `Html.fromDom()`. 
 
 The `Html()` constructor is for those who would like to directly pass HTML from the source to the package to be rendered. 
 
 If you would like to modify or sanitize the HTML before rendering it, then `Html.fromDom()` is for you - you can convert the HTML string to a `Document` and use its methods to modify the HTML as you wish. Then, you can directly pass the modified `Document` to the package. This eliminates the need to parse the modified `Document` back to a string, pass to `Html()`, and convert back to a `Document`, thus cutting down on load times.
 
+#### Selectable Text
+
+The package also has two constructors for selectable text support - `SelectableHtml()` and `SelectableHtml.fromDom()`.
+
+The difference between the two is the same as noted above.
+
+Please note: Due to Flutter [#38474](https://github.com/flutter/flutter/issues/38474), selectable text support is significantly watered down compared to the standard non-selectable version of the widget. The changes are as follows:
+
+1. The list of tags that can be rendered is significantly reduced. Key omissions include no support for images/video/audio, table, and ul/ol.
+
+2. No support for `customRender`, `customImageRender`, `onImageError`, `onImageTap`, `onMathError`, and `navigationDelegateForIframe`. (Support for `customRender` may be added in the future).
+
+3. Styling support is significantly reduced. Only text-related styling works (e.g. bold or italic), while container related styling (e.g. borders or padding/margin) do not work.
+
+Once the above issue is resolved, the aforementioned compromises will go away. Currently the `SelectableText.rich()` constructor does not support `WidgetSpan`s, resulting in the feature losses above.
+
 ### Parameters: 
 
 |  Parameters  |   Description   |
@@ -170,7 +188,9 @@ If you would like to modify or sanitize the HTML before rendering it, then `Html
 
 ### Getters:
 
-Currently the only getter is `Html.tags`. This provides a list of all the tags the package renders. The main use case is to assist in blacklisting elements using `tagsList`. See an [example](#example-usage---tagslist---excluding-tags) below.
+1. `Html.tags`. This provides a list of all the tags the package renders. The main use case is to assist in excluding elements using `tagsList`. See an [example](#example-usage---tagslist---excluding-tags) below.
+
+2. `SelectableHtml.tags`. This provides a list of all the tags that can be rendered in selectable mode.
 
 ### Data:
 
@@ -419,7 +439,7 @@ A list of elements the `Html` widget should render. The list should contain the
 #### Example Usage - tagsList - Excluding Tags:
 You may have instances where you can choose between two different types of HTML tags to display the same content. In the example below, the `<video>` and `<iframe>` elements are going to display the same content.
 
-The `blacklistedElements` parameter allows you to change which element is rendered. Iframes can be advantageous because they allow parallel loading - Flutter just has to wait for the webview to be initialized before rendering the page, possibly cutting down on load time. Video can be advantageous because it provides a 100% native experience with Flutter widgets, but it may take more time to render the page. You may know that Flutter webview is a little janky in its current state on Android, so using `blacklistedElements` and a simple condition, you can get the best of both worlds - choose the video widget to render on Android and the iframe webview to render on iOS.
+The `tagsList` parameter allows you to change which element is rendered. Iframes can be advantageous because they allow parallel loading - Flutter just has to wait for the webview to be initialized before rendering the page, possibly cutting down on load time. Video can be advantageous because it provides a 100% native experience with Flutter widgets, but it may take more time to render the page. You may know that Flutter webview is a little janky in its current state on Android, so using `tagsList` and a simple condition, you can get the best of both worlds - choose the video widget to render on Android and the iframe webview to render on iOS.
 
 ```dart
 Widget html = Html(

lib/flutter_html.dart

@@ -11,28 +11,15 @@ import 'package:webview_flutter/webview_flutter.dart';
 
 //export render context api
 export 'package:flutter_html/html_parser.dart';
-//export render context api
-export 'package:flutter_html/html_parser.dart';
-//export image render api
-export 'package:flutter_html/image_render.dart';
-//export image render api
 export 'package:flutter_html/image_render.dart';
+//export src for advanced custom render uses (e.g. casting context.tree)
 export 'package:flutter_html/src/anchor.dart';
-export 'package:flutter_html/src/anchor.dart';
-export 'package:flutter_html/src/interactable_element.dart';
 export 'package:flutter_html/src/interactable_element.dart';
-//export src for advanced custom render uses (e.g. casting context.tree)
-export 'package:flutter_html/src/layout_element.dart';
-//export src for advanced custom render uses (e.g. casting context.tree)
 export 'package:flutter_html/src/layout_element.dart';
 export 'package:flutter_html/src/replaced_element.dart';
-export 'package:flutter_html/src/replaced_element.dart';
-export 'package:flutter_html/src/styled_element.dart';
 export 'package:flutter_html/src/styled_element.dart';
 //export style api
 export 'package:flutter_html/style.dart';
-//export style api
-export 'package:flutter_html/style.dart';
 
 class Html extends StatelessWidget {
   /// The `Html` widget takes HTML as input and displays a RichText
@@ -172,6 +159,7 @@ class Html extends StatelessWidget {
         onImageError: onImageError,
         onMathError: onMathError,
         shrinkWrap: shrinkWrap,
+        selectable: false,
         style: style,
         customRender: customRender,
         imageRenders: {}
@@ -183,3 +171,105 @@ class Html extends StatelessWidget {
     );
   }
 }
+
+class SelectableHtml extends StatelessWidget {
+  /// The `SelectableHtml` widget takes HTML as input and displays a RichText
+  /// tree of the parsed HTML content (which is selectable)
+  ///
+  /// **Attributes**
+  /// **data** *required* takes in a String of HTML data (required only for `Html` constructor).
+  /// **document** *required* takes in a Document of HTML data (required only for `Html.fromDom` constructor).
+  ///
+  /// **onLinkTap** This function is called whenever a link (`<a href>`)
+  /// is tapped.
+  ///
+  /// **tagsList** Tag names in this array will be the only tags rendered. By default all tags that support selectable content are rendered.
+  ///
+  /// **style** Pass in the style information for the Html here.
+  /// See [its wiki page](https://github.com/Sub6Resources/flutter_html/wiki/Style) for more info.
+  ///
+  /// **PLEASE NOTE**
+  ///
+  /// There are a few caveats due to Flutter [#38474](https://github.com/flutter/flutter/issues/38474):
+  ///
+  /// 1. The list of tags that can be rendered is significantly reduced.
+  /// Key omissions include no support for images/video/audio, table, and ul/ol because they all require widgets and `WidgetSpan`s.
+  ///
+  /// 2. No support for `customRender`, `customImageRender`, `onImageError`, `onImageTap`, `onMathError`, and `navigationDelegateForIframe`.
+  ///
+  /// 3. Styling support is significantly reduced. Only text-related styling works
+  /// (e.g. bold or italic), while container related styling (e.g. borders or padding/margin)
+  /// do not work because we can't use the `ContainerSpan` class (it needs an enclosing `WidgetSpan`).
+
+  SelectableHtml({
+    Key? key,
+    required this.data,
+    this.onLinkTap,
+    this.onCssParseError,
+    this.shrinkWrap = false,
+    this.style = const {},
+    this.tagsList = const [],
+  }) : document = null,
+        super(key: key);
+
+  SelectableHtml.fromDom({
+    Key? key,
+    required this.document,
+    this.onLinkTap,
+    this.onCssParseError,
+    this.shrinkWrap = false,
+    this.style = const {},
+    this.tagsList = const [],
+  }) : data = null,
+        super(key: key);
+
+  /// The HTML data passed to the widget as a String
+  final String? data;
+
+  /// The HTML data passed to the widget as a pre-processed [dom.Document]
+  final dom.Document? document;
+
+  /// A function that defines what to do when a link is tapped
+  final OnTap? onLinkTap;
+
+  /// A function that defines what to do when CSS fails to parse
+  final OnCssParseError? onCssParseError;
+
+  /// A parameter that should be set when the HTML widget is expected to be
+  /// flexible
+  final bool shrinkWrap;
+
+  /// A list of HTML tags that defines what elements are not rendered
+  final List<String> tagsList;
+
+  /// An API that allows you to override the default style for any HTML element
+  final Map<String, Style> style;
+
+  static List<String> get tags => new List<String>.from(SELECTABLE_ELEMENTS);
+
+  @override
+  Widget build(BuildContext context) {
+    final dom.Document doc = data != null ? HtmlParser.parseHTML(data!) : document!;
+    final double? width = shrinkWrap ? null : MediaQuery.of(context).size.width;
+
+    return Container(
+      width: width,
+      child: HtmlParser(
+        key: null,
+        htmlData: doc,
+        onLinkTap: onLinkTap,
+        onImageTap: null,
+        onCssParseError: onCssParseError,
+        onImageError: null,
+        onMathError: null,
+        shrinkWrap: shrinkWrap,
+        selectable: true,
+        style: style,
+        customRender: {},
+        imageRenders: defaultImageRenders,
+        tagsList: tagsList.isEmpty ? SelectableHtml.tags : tagsList,
+        navigationDelegateForIframe: null,
+      ),
+    );
+  }
+}

lib/html_parser.dart

@@ -49,6 +49,7 @@ class HtmlParser extends StatelessWidget {
   final ImageErrorListener? onImageError;
   final OnMathError? onMathError;
   final bool shrinkWrap;
+  final bool selectable;
 
   final Map<String, Style> style;
   final Map<String, CustomRender> customRender;
@@ -66,6 +67,7 @@ class HtmlParser extends StatelessWidget {
     required this.onImageError,
     required this.onMathError,
     required this.shrinkWrap,
+    required this.selectable,
     required this.style,
     required this.customRender,
     required this.imageRenders,
@@ -104,6 +106,19 @@ class HtmlParser extends StatelessWidget {
     // using textScaleFactor = 1.0 (which is the default). This ensures the correct
     // scaling is used, but relies on https://github.com/flutter/flutter/pull/59711
     // to wrap everything when larger accessibility fonts are used.
+    if (selectable) {
+      return StyledText.selectable(
+        textSpan: parsedTree as TextSpan,
+        style: cleanedTree.style,
+        textScaleFactor: MediaQuery.of(context).textScaleFactor,
+        renderContext: RenderContext(
+          buildContext: context,
+          parser: this,
+          tree: cleanedTree,
+          style: Style.fromTextStyle(Theme.of(context).textTheme.bodyText2!),
+        ),
+      );
+    }
     return StyledText(
       textSpan: parsedTree,
       style: cleanedTree.style,
@@ -321,6 +336,25 @@ class HtmlParser extends StatelessWidget {
 
     //Return the correct InlineSpan based on the element type.
     if (tree.style.display == Display.BLOCK && tree.children.isNotEmpty) {
+      if (newContext.parser.selectable) {
+        return TextSpan(
+          style: newContext.style.generateTextStyle(),
+          children: tree.children
+              .expandIndexed((i, childTree) => [
+            if (childTree.style.display == Display.BLOCK &&
+                i > 0 &&
+                tree.children[i - 1] is ReplacedElement)
+              TextSpan(text: "\n"),
+            parseTree(newContext, childTree),
+            if (i != tree.children.length - 1 &&
+                childTree.style.display == Display.BLOCK &&
+                childTree.element?.localName != "html" &&
+                childTree.element?.localName != "body")
+              TextSpan(text: "\n"),
+          ])
+              .toList(),
+        );
+      }
       return WidgetSpan(
         child: ContainerSpan(
           key: AnchorKey.of(key, tree),
@@ -1001,17 +1035,39 @@ class StyledText extends StatelessWidget {
   final double textScaleFactor;
   final RenderContext renderContext;
   final AnchorKey? key;
+  final bool _selectable;
 
   const StyledText({
     required this.textSpan,
     required this.style,
     this.textScaleFactor = 1.0,
     required this.renderContext,
     this.key,
-  }) : super(key: key);
+  }) : _selectable = false,
+        super(key: key);
+
+  const StyledText.selectable({
+    required TextSpan textSpan,
+    required this.style,
+    this.textScaleFactor = 1.0,
+    required this.renderContext,
+    this.key,
+  }) : textSpan = textSpan,
+        _selectable = true,
+        super(key: key);
 
   @override
   Widget build(BuildContext context) {
+    if (_selectable) {
+      return SelectableText.rich(
+        textSpan as TextSpan,
+        style: style.generateTextStyle(),
+        textAlign: style.textAlign,
+        textDirection: style.direction,
+        textScaleFactor: textScaleFactor,
+        maxLines: style.maxLines,
+      );
+    }
     return SizedBox(
       width: consumeExpandedBlock(style.display, renderContext),
       child: Text.rich(

lib/src/html_elements.dart

@@ -135,6 +135,69 @@ const TABLE_CELL_ELEMENTS = ["th", "td"];
 
 const TABLE_DEFINITION_ELEMENTS = ["col", "colgroup"];
 
+const SELECTABLE_ELEMENTS = [
+  "br",
+  "a",
+  "article",
+  "aside",
+  "blockquote",
+  "body",
+  "center",
+  "dd",
+  "div",
+  "dl",
+  "dt",
+  "figcaption",
+  "figure",
+  "footer",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "header",
+  "hr",
+  "html",
+  "main",
+  "nav",
+  "noscript",
+  "p",
+  "pre",
+  "section",
+  "summary",
+  "abbr",
+  "acronym",
+  "address",
+  "b",
+  "bdi",
+  "bdo",
+  "big",
+  "cite",
+  "code",
+  "data",
+  "del",
+  "dfn",
+  "em",
+  "font",
+  "i",
+  "ins",
+  "kbd",
+  "mark",
+  "q",
+  "s",
+  "samp",
+  "small",
+  "span",
+  "strike",
+  "strong",
+  "time",
+  "tt",
+  "u",
+  "var",
+  "wbr",
+];
+
 /**
   Here is a list of elements with planned support:
     a         - i [x]