html-react-parser 0.10.5 → 0.13.0

package/README.md

@@ -106,11 +106,11 @@ parse(
 
 The `replace` callback allows you to swap an element with another React element.
 
-The first argument is an object with the same output as [htmlparser2](https://github.com/fb55/htmlparser2)'s [domhandler](https://github.com/fb55/domhandler#example):
+The first argument is an object with the same output as [htmlparser2](https://github.com/fb55/htmlparser2/tree/v3.10.1)'s [domhandler](https://github.com/fb55/domhandler#example):
 
 ```js
 parse('<br>', {
-  replace: function(domNode) {
+  replace: function (domNode) {
     console.dir(domNode, { depth: null });
   }
 });
@@ -224,6 +224,60 @@ parse('<br>', {
 });
 ```
 
+### htmlparser2
+
+This library passes the following options to [htmlparser2](https://github.com/fb55/htmlparser2/tree/v3.10.1) on the server-side:
+
+```js
+{
+  decodeEntities: true,
+  lowerCaseAttributeNames: false
+}
+```
+
+By passing your own options, the default library options will be **replaced** (not merged).
+
+As a result, to enable `decodeEntities` and `xmlMode`, you need to do the following:
+
+```js
+parse('<p /><p />', {
+  htmlparser2: {
+    decodeEntities: true,
+    xmlMode: true
+  }
+});
+```
+
+See [htmlparser2 options](https://github.com/fb55/htmlparser2/wiki/Parser-options).
+
+> **Warning**: By overriding htmlparser2 options, there's a chance of breaking universal rendering. Do this at your own risk.
+
+### trim
+
+Normally, whitespace is preserved:
+
+```js
+parse('<br>\n'); // [React.createElement('br'), '\n']
+```
+
+By enabling the `trim` option, whitespace text nodes will be skipped:
+
+```js
+parse('<br>\n', { trim: true }); // React.createElement('br')
+```
+
+This addresses the warning:
+
+```
+Warning: validateDOMNesting(...): Whitespace text nodes cannot appear as a child of <table>. Make sure you don't have any extra whitespace between tags on each line of your source code.
+```
+
+However, this option may strip out intentional whitespace:
+
+```js
+parse('<p> </p>', { trim: true }); // React.createElement('p')
+```
+
 ## FAQ
 
 #### Is this library XSS safe?
@@ -250,6 +304,41 @@ Check if your arguments are valid. Also, see ["Does this library sanitize invali
 
 Yes, this library supports server-side rendering on Node.js. See [demo](https://repl.it/@remarkablemark/html-react-parser-SSR).
 
+#### Why are my elements nested incorrectly?
+
+Make sure your [HTML markup is valid](https://validator.w3.org/). The HTML to DOM parsing will be affected if you're using self-closing syntax (`/>`) on non-void elements:
+
+```js
+parse('<div /><div />'); // returns single element instead of array of elements
+```
+
+See [#158](https://github.com/remarkablemark/html-react-parser/issues/158).
+
+#### I get "Warning: validateDOMNesting(...): Whitespace text nodes cannot appear as a child of table."
+
+Enable the [trim](https://github.com/remarkablemark/html-react-parser#trim) option. See [#155](https://github.com/remarkablemark/html-react-parser/issues/155).
+
+#### Don't change case of tags.
+
+Tags are lowercased by default. To prevent that from happening, pass the [htmlparser2 option](https://github.com/remarkablemark/html-react-parser#htmlparser2):
+
+```js
+const options = {
+  htmlparser2: {
+    lowerCaseTags: false
+  }
+};
+parse('<CustomElement>', options); // React.createElement('CustomElement')
+```
+
+> **Warning**: By preserving case-sensitivity of the tags, you may get rendering warnings like:
+>
+> ```
+> Warning: <CustomElement> is using incorrect casing. Use PascalCase for React components, or lowercase for HTML elements.
+> ```
+
+See [#62](https://github.com/remarkablemark/html-react-parser/issues/62) and [example](https://repl.it/@remarkablemark/html-react-parser-62).
+
 ## Benchmarks
 
 ```sh
@@ -297,6 +386,7 @@ Support this project with your organization. Your logo will show up here with a
 
 ## Support
 
+- [GitHub Sponsors](https://b.remarkabl.org/github-sponsors)
 - [Patreon](https://b.remarkabl.org/patreon)
 - [Open Collective](https://b.remarkabl.org/open-collective-html-react-parser)
 - [Ko-fi](https://b.remarkabl.org/ko-fi)

package/dist/html-react-parser.js

@@ -1124,6 +1124,8 @@
     var replaceElement;
     var props;
     var children;
+    var data;
+    var trim = options.trim;
 
     for (var i = 0, len = nodes.length; i < len; i++) {
       node = nodes[i];
@@ -1133,7 +1135,7 @@
         replaceElement = options.replace(node);
 
         if (isValidElement(replaceElement)) {
-          // specify a "key" prop if element has siblings
+          // set "key" prop for sibling elements
           // https://fb.me/react-warning-keys
           if (len > 1) {
             replaceElement = cloneElement(replaceElement, {
@@ -1146,45 +1148,54 @@
       }
 
       if (node.type === 'text') {
-        result.push(node.data);
+        // if trim option is enabled, skip whitespace text nodes
+        if (trim) {
+          data = node.data.trim();
+          if (data) {
+            result.push(node.data);
+          }
+        } else {
+          result.push(node.data);
+        }
         continue;
       }
 
       props = node.attribs;
       if (!shouldPassAttributesUnaltered(node)) {
-        // update values
         props = attributesToProps_1(node.attribs);
       }
 
       children = null;
 
-      // node type for <script> is "script"
-      // node type for <style> is "style"
-      if (node.type === 'script' || node.type === 'style') {
-        // prevent text in <script> or <style> from being escaped
-        // https://facebook.github.io/react/tips/dangerously-set-inner-html.html
-        if (node.children[0]) {
-          props.dangerouslySetInnerHTML = {
-            __html: node.children[0].data
-          };
-        }
-      } else if (node.type === 'tag') {
-        // setting textarea value in children is an antipattern in React
-        // https://reactjs.org/docs/forms.html#the-textarea-tag
-        if (node.name === 'textarea' && node.children[0]) {
-          props.defaultValue = node.children[0].data;
-
-          // continue recursion of creating React elements (if applicable)
-        } else if (node.children && node.children.length) {
-          children = domToReact(node.children, options);
-        }
+      switch (node.type) {
+        case 'script':
+        case 'style':
+          // prevent text in <script> or <style> from being escaped
+          // https://reactjs.org/docs/dom-elements.html#dangerouslysetinnerhtml
+          if (node.children[0]) {
+            props.dangerouslySetInnerHTML = {
+              __html: node.children[0].data
+            };
+          }
+          break;
+
+        case 'tag':
+          // setting textarea value in children is an antipattern in React
+          // https://reactjs.org/docs/forms.html#the-textarea-tag
+          if (node.name === 'textarea' && node.children[0]) {
+            props.defaultValue = node.children[0].data;
+          } else if (node.children && node.children.length) {
+            // continue recursion of creating React elements (if applicable)
+            children = domToReact(node.children, options);
+          }
+          break;
 
         // skip all other cases (e.g., comment)
-      } else {
-        continue;
+        default:
+          continue;
       }
 
-      // specify a "key" prop if element has siblings
+      // set "key" prop for sibling elements
       // https://fb.me/react-warning-keys
       if (len > 1) {
         props.key = i;
@@ -1197,6 +1208,8 @@
   }
 
   /**
+   * Determines whether attributes should be altered or not.
+   *
    * @param {React.ReactElement} node
    * @return {Boolean}
    */
@@ -1428,13 +1441,24 @@
   var isIE9 = utilities$1.isIE(9);
   var isIE$1 = isIE9 || utilities$1.isIE();
 
+  // falls back to `parseFromString` if `createHTMLDocument` cannot be used
+  var parseFromDocument = function () {
+    throw new Error(
+      'This browser does not support `document.implementation.createHTMLDocument`'
+    );
+  };
+
+  var parseFromString = function () {
+    throw new Error(
+      'This browser does not support `DOMParser.prototype.parseFromString`'
+    );
+  };
+
   /**
    * DOMParser (performance: slow).
    *
    * @see https://developer.mozilla.org/docs/Web/API/DOMParser#Parsing_an_SVG_or_HTML_document
    */
-  var parseFromString;
-
   if (typeof window.DOMParser === 'function') {
     var domParser = new window.DOMParser();
 
@@ -1449,7 +1473,7 @@
      * @param  {string} [tagName] - The element to render the HTML (with 'body' as fallback).
      * @return {HTMLDocument}
      */
-    parseFromString = function domStringParser(html, tagName) {
+    parseFromString = function (html, tagName) {
       if (tagName) {
         html = '<' + tagName + '>' + html + '</' + tagName + '>';
       }
@@ -1461,6 +1485,8 @@
 
       return domParser.parseFromString(html, mimeType);
     };
+
+    parseFromDocument = parseFromString;
   }
 
   /**
@@ -1468,13 +1494,11 @@
    *
    * @see https://developer.mozilla.org/docs/Web/API/DOMImplementation/createHTMLDocument
    */
-  var parseFromDocument;
-
-  if (typeof document.implementation === 'object') {
+  if (document.implementation) {
     // title parameter is required in IE
     // https://msdn.microsoft.com/en-us/library/ff975457(v=vs.85).aspx
     var doc = document.implementation.createHTMLDocument(
-      isIE$1 ? 'HTML_DOM_PARSER_TITLE' : undefined
+      isIE$1 ? 'html-dom-parser' : undefined
     );
 
     /**
@@ -1484,7 +1508,7 @@
      * @param  {string} [tagName] - The element to render the HTML (with 'body' as fallback).
      * @return {HTMLDocument}
      */
-    parseFromDocument = function createHTMLDocument(html, tagName) {
+    parseFromDocument = function (html, tagName) {
       if (tagName) {
         doc.documentElement.getElementsByTagName(tagName)[0].innerHTML = html;
         return doc;
@@ -1507,8 +1531,8 @@
    *
    * @see https://developer.mozilla.org/docs/Web/HTML/Element/template
    */
-  var parseFromTemplate;
   var template = document.createElement('template');
+  var parseFromTemplate;
 
   if (template.content) {
     /**
@@ -1517,15 +1541,12 @@
      * @param  {string} html - The HTML string.
      * @return {NodeList}
      */
-    parseFromTemplate = function templateParser(html) {
+    parseFromTemplate = function (html) {
       template.innerHTML = html;
       return template.content.childNodes;
     };
   }
 
-  // fallback document parser
-  var parseWithFallback = parseFromDocument || parseFromString;
-
   /**
    * Parses HTML string to DOM nodes.
    *
@@ -1546,42 +1567,35 @@
 
     switch (firstTagName) {
       case HTML:
-        if (parseFromString) {
-          doc = parseFromString(html);
-
-          // the created document may come with filler head/body elements,
-          // so make sure to remove them if they don't actually exist
-          if (!HEAD_TAG_REGEX.test(html)) {
-            element = doc.getElementsByTagName(HEAD)[0];
-            if (element) {
-              element.parentNode.removeChild(element);
-            }
+        doc = parseFromString(html);
+
+        // the created document may come with filler head/body elements,
+        // so make sure to remove them if they don't actually exist
+        if (!HEAD_TAG_REGEX.test(html)) {
+          element = doc.getElementsByTagName(HEAD)[0];
+          if (element) {
+            element.parentNode.removeChild(element);
           }
+        }
 
-          if (!BODY_TAG_REGEX.test(html)) {
-            element = doc.getElementsByTagName(BODY)[0];
-            if (element) {
-              element.parentNode.removeChild(element);
-            }
+        if (!BODY_TAG_REGEX.test(html)) {
+          element = doc.getElementsByTagName(BODY)[0];
+          if (element) {
+            element.parentNode.removeChild(element);
           }
-
-          return doc.getElementsByTagName(HTML);
         }
-        break;
+
+        return doc.getElementsByTagName(HTML);
 
       case HEAD:
       case BODY:
-        if (parseWithFallback) {
-          elements = parseWithFallback(html).getElementsByTagName(firstTagName);
+        elements = parseFromDocument(html).getElementsByTagName(firstTagName);
 
-          // account for possibility of sibling
-          if (BODY_TAG_REGEX.test(html) && HEAD_TAG_REGEX.test(html)) {
-            return elements[0].parentNode.childNodes;
-          }
-
-          return elements;
+        // if there's a sibling element, then return both elements
+        if (BODY_TAG_REGEX.test(html) && HEAD_TAG_REGEX.test(html)) {
+          return elements[0].parentNode.childNodes;
         }
-        break;
+        return elements;
 
       // low-level tag or text
       default:
@@ -1589,15 +1603,9 @@
           return parseFromTemplate(html);
         }
 
-        if (parseWithFallback) {
-          return parseWithFallback(html, BODY).getElementsByTagName(BODY)[0]
-            .childNodes;
-        }
-
-        break;
+        return parseFromDocument(html, BODY).getElementsByTagName(BODY)[0]
+          .childNodes;
     }
-
-    return [];
   }
 
   var domparser_1 = domparser;
@@ -1641,19 +1649,31 @@
 
   var htmlToDomClient = parseDOM;
 
+  // decode HTML entities by default for `htmlparser2`
+  var domParserOptions = { decodeEntities: true, lowerCaseAttributeNames: false };
+
   /**
    * Converts HTML string to React elements.
    *
-   * @param  {String}   html                    - The HTML string to parse to React.
-   * @param  {Object}   [options]               - The parser options.
-   * @param  {Function} [options.replace]       - The replace method.
-   * @return {JSX.Element|JSX.Element[]|String} - Returns React element(s), string, or empty array.
+   * @param  {String}   html                    - HTML string.
+   * @param  {Object}   [options]               - Parser options.
+   * @param  {Object}   [options.htmlparser2]   - htmlparser2 options.
+   * @param  {Object}   [options.library]       - Library for React, Preact, etc.
+   * @param  {Function} [options.replace]       - Replace method.
+   * @return {JSX.Element|JSX.Element[]|String} - React element(s), empty array, or string.
    */
   function HTMLReactParser(html, options) {
     if (typeof html !== 'string') {
       throw new TypeError('First argument must be a string');
     }
-    return domToReact_1(htmlToDomClient(html), options);
+    if (html === '') {
+      return [];
+    }
+    options = options || {};
+    return domToReact_1(
+      htmlToDomClient(html, options.htmlparser2 || domParserOptions),
+      options
+    );
   }
 
   HTMLReactParser.domToReact = domToReact_1;
@@ -1661,8 +1681,8 @@
 
   // support CommonJS and ES Modules
   var htmlReactParser = HTMLReactParser;
-  var default_1 = HTMLReactParser;
-  htmlReactParser.default = default_1;
+  var _default = HTMLReactParser;
+  htmlReactParser.default = _default;
 
   return htmlReactParser;