CssStyleApplier updates (#2145)

* Update internal structure of _styleData

* Rename parameter

* Rename

* Add docs

ext/js/dom/sandbox/css-style-applier.js

@@ -21,11 +21,17 @@
  */
 class CssStyleApplier {
     /**
+     * A CSS rule.
      * @typedef {object} CssRule
      * @property {string} selectors A CSS selector string representing one or more selectors.
-     * @property {[string, string][]} styles A list of CSS property and value pairs.
-     * @property {string} styles[][0] The CSS property.
-     * @property {string} styles[][1] The CSS value.
+     * @property {CssDeclaration[]} styles A list of CSS property and value pairs.
+     */
+
+    /**
+     * A single CSS property declaration.
+     * @typedef {object} CssDeclaration
+     * @property {string} property A CSS property's name, using kebab-case.
+     * @property {string} value The property's value.
      */
 
     /**
@@ -54,14 +60,24 @@ class CssStyleApplier {
      * Loads the data file for use.
      */
     async prepare() {
-        let styleData;
+        let rawData;
         try {
-            styleData = await this._fetchJsonAsset(this._styleDataUrl);
+            rawData = await this._fetchJsonAsset(this._styleDataUrl);
         } catch (e) {
             console.error(e);
         }
-        if (Array.isArray(styleData)) {
-            this._styleData = styleData;
+        const styleData = this._styleData;
+        styleData.length = 0;
+        for (const {selectors, styles} of rawData) {
+            const selectors2 = selectors.join(',');
+            const styles2 = [];
+            for (const [property, value] of styles) {
+                styles2.push({property, value});
+            }
+            styleData.push({
+                selectors: selectors2,
+                styles: styles2
+            });
         }
     }
 
@@ -76,8 +92,8 @@ class CssStyleApplier {
             const className = element.getAttribute('class');
             if (className.length === 0) { continue; }
             let cssTextNew = '';
-            for (const {selectorText, styles} of this._getCandidateCssRulesForClass(className)) {
-                if (!element.matches(selectorText)) { continue; }
+            for (const {selectors, styles} of this._getCandidateCssRulesForClass(className)) {
+                if (!element.matches(selectors)) { continue; }
                 cssTextNew += this._getCssText(styles);
             }
             cssTextNew += element.style.cssText;
@@ -95,6 +111,12 @@ class CssStyleApplier {
 
     // Private
 
+    /**
+     * Fetches and parses a JSON file.
+     * @param {string} url The URL to the file.
+     * @returns {Promise<*>} A JSON object.
+     * @throws {Error} An error is thrown if the fetch fails.
+     */
     async _fetchJsonAsset(url) {
         const response = await fetch(url, {
             method: 'GET',
@@ -124,37 +146,52 @@ class CssStyleApplier {
 
         const classList = this._getTokens(className);
         for (const {selectors, styles} of this._styleData) {
-            const selectorText = selectors.join(',');
-            if (!this._selectorMatches(selectorText, classList)) { continue; }
-            rules.push({selectorText, styles});
+            if (!this._selectorMightMatch(selectors, classList)) { continue; }
+            rules.push({selectors, styles});
         }
 
         return rules;
     }
 
+    /**
+     * Converts an array of CSS rules to a CSS string.
+     * @param {CssRule[]} styles An array of CSS rules.
+     * @returns {string} The CSS string.
+     */
     _getCssText(styles) {
         let cssText = '';
-        for (const [property, value] of styles) {
+        for (const {property, value} of styles) {
             cssText += `${property}:${value};`;
         }
         return cssText;
     }
 
-    _selectorMatches(selectorText, classList) {
+    /**
+     * Checks whether or not a CSS string might match at least one class in a list.
+     * @param {string} selectors A CSS selector string.
+     * @param {string[]} classList An array of CSS classes.
+     * @returns {boolean} `true` if the selector string might match one of the classes in `classList`, false otherwise.
+     */
+    _selectorMightMatch(selectors, classList) {
         const pattern = this._patternClassNameCharacter;
         for (const item of classList) {
             const prefixedItem = `.${item}`;
             let start = 0;
             while (true) {
-                const index = selectorText.indexOf(prefixedItem, start);
+                const index = selectors.indexOf(prefixedItem, start);
                 if (index < 0) { break; }
                 start = index + prefixedItem.length;
-                if (start >= selectorText.length || !pattern.test(selectorText[start])) { return true; }
+                if (start >= selectors.length || !pattern.test(selectors[start])) { return true; }
             }
         }
         return false;
     }
 
+    /**
+     * Gets the whitespace-delimited tokens from a string.
+     * @param {string} tokenListString The string to parse.
+     * @returns {string[]} An array of tokens.
+     */
     _getTokens(tokenListString) {
         let start = 0;
         const pattern = this._patternHtmlWhitespace;