lighthouse 10.0.2-dev.20230305 → 10.0.2-dev.20230307

package/report/renderer/details-renderer.js

@@ -24,22 +24,26 @@
 /** @typedef {LH.FormattedIcu<LH.Audit.Details.TableItem>} TableItem */
 /** @typedef {LH.FormattedIcu<LH.Audit.Details.ItemValue>} TableItemValue */
 /** @typedef {LH.FormattedIcu<LH.Audit.Details.TableColumnHeading>} TableColumnHeading */
+/** @typedef {LH.FormattedIcu<LH.Audit.Details.Table | LH.Audit.Details.Opportunity>} TableLike */
 
 import {Util} from '../../shared/util.js';
 import {CriticalRequestChainRenderer} from './crc-details-renderer.js';
 import {ElementScreenshotRenderer} from './element-screenshot-renderer.js';
 import {Globals} from './report-globals.js';
+import {ReportUtils} from './report-utils.js';
 
 const URL_PREFIXES = ['http://', 'https://', 'data:'];
+const SUMMABLE_VALUETYPES = ['bytes', 'numeric', 'ms', 'timespanMs'];
 
 export class DetailsRenderer {
   /**
    * @param {DOM} dom
-   * @param {{fullPageScreenshot?: LH.Result.FullPageScreenshot}} [options]
+   * @param {{fullPageScreenshot?: LH.Result.FullPageScreenshot, entities?: LH.Result.Entities}} [options]
    */
   constructor(dom, options = {}) {
     this._dom = dom;
     this._fullPageScreenshot = options.fullPageScreenshot;
+    this._entities = options.entities;
   }
 
   /**
@@ -376,7 +380,110 @@ export class DetailsRenderer {
   }
 
   /**
-   * @param {{headings: TableColumnHeading[], items: TableItem[]}} details
+   * Adorn a table row element with entity chips based on [data-entity] attribute.
+   * @param {HTMLTableRowElement} rowEl
+   */
+  _adornEntityGroupRow(rowEl) {
+    const entityName = rowEl.dataset.entity;
+    if (!entityName) return;
+    const matchedEntity = this._entities?.find(e => e.name === entityName);
+    if (!matchedEntity) return;
+
+    const firstTdEl = this._dom.find('td', rowEl);
+
+    if (matchedEntity.category) {
+      const categoryChipEl = this._dom.createElement('span');
+      categoryChipEl.classList.add('lh-audit__adorn');
+      categoryChipEl.textContent = matchedEntity.category;
+      firstTdEl.append(' ', categoryChipEl);
+    }
+
+    if (matchedEntity.isFirstParty) {
+      const firstPartyChipEl = this._dom.createElement('span');
+      firstPartyChipEl.classList.add('lh-audit__adorn', 'lh-audit__adorn1p');
+      firstPartyChipEl.textContent = Globals.strings.firstPartyChipLabel;
+      firstTdEl.append(' ', firstPartyChipEl);
+    }
+
+    if (matchedEntity.homepage) {
+      const entityLinkEl = this._dom.createElement('a');
+      entityLinkEl.href = matchedEntity.homepage;
+      entityLinkEl.target = '_blank';
+      entityLinkEl.title = Globals.strings.openInANewTabTooltip;
+      entityLinkEl.classList.add('lh-report-icon--external');
+      firstTdEl.append(' ', entityLinkEl);
+    }
+  }
+
+  /**
+   * Renders an entity-grouped row.
+   * @param {TableItem} item
+   * @param {LH.Audit.Details.TableColumnHeading[]} headings
+   */
+  _renderEntityGroupRow(item, headings) {
+    const entityColumnHeading = {...headings[0]};
+    // In subitem-situations (unused-javascript), ensure Entity name is not rendered as code, etc.
+    entityColumnHeading.valueType = 'text';
+    const groupedRowHeadings = [entityColumnHeading, ...headings.slice(1)];
+    const fragment = this._dom.createFragment();
+    fragment.append(this._renderTableRow(item, groupedRowHeadings));
+    this._dom.find('tr', fragment).classList.add('lh-row--group');
+    return fragment;
+  }
+
+  /**
+   * Returns an array of entity-grouped TableItems to use as the top-level rows in
+   * an grouped table. Each table item returned represents a unique entity, with every
+   * applicable key that can be grouped as a property. Optionally, supported columns are
+   * summed by entity, and sorted by specified keys.
+   * @param {TableLike} details
+   * @return {TableItem[]}
+   */
+  _getEntityGroupItems(details) {
+    const {items, headings, sortedBy} = details;
+    // Exclude entity-grouped audits and results without entity classification.
+    // Eg. Third-party Summary comes entity-grouped.
+    if (!items.length || details.isEntityGrouped || !items.some(item => item.entity)) {
+      return [];
+    }
+
+    const skippedColumns = new Set(details.skipSumming || []);
+    /** @type {string[]} */
+    const summableColumns = [];
+    for (const heading of headings) {
+      if (!heading.key || skippedColumns.has(heading.key)) continue;
+      if (SUMMABLE_VALUETYPES.includes(heading.valueType)) {
+        summableColumns.push(heading.key);
+      }
+    }
+
+    // Grab the first column's key to group by entity
+    const firstColumnKey = headings[0].key;
+    if (!firstColumnKey) return [];
+
+    /** @type {Map<string | undefined, TableItem>} */
+    const byEntity = new Map();
+    for (const item of items) {
+      const entityName = typeof item.entity === 'string' ? item.entity : undefined;
+      const groupedItem = byEntity.get(entityName) || {
+        [firstColumnKey]: entityName || Globals.strings.unattributable,
+        entity: entityName,
+      };
+      for (const key of summableColumns) {
+        groupedItem[key] = Number(groupedItem[key] || 0) + Number(item[key] || 0);
+      }
+      byEntity.set(entityName, groupedItem);
+    }
+
+    const result = [...byEntity.values()];
+    if (sortedBy) {
+      result.sort(ReportUtils.getTableItemSortComparator(sortedBy));
+    }
+    return result;
+  }
+
+  /**
+   * @param {TableLike} details
    * @return {Element}
    */
   _renderTable(details) {
@@ -394,29 +501,45 @@ export class DetailsRenderer {
       this._dom.createChildOf(theadTrElem, 'th', classes).append(labelEl);
     }
 
+    const entityItems = this._getEntityGroupItems(details);
     const tbodyElem = this._dom.createChildOf(tableElem, 'tbody');
-    let even = true;
-    for (const item of details.items) {
-      const rowsFragment = this._renderTableRowsFromItem(item, details.headings);
-
-      // The attribute item.entity could be a string (entity-classification), or
-      // a LinkValue for ThirdPartySummary audit.
-      let entityName;
-      if (typeof item.entity === 'object' && item.entity.type === 'link') {
-        entityName = item.entity.text;
-      } else if (typeof item.entity === 'string') {
-        entityName = item.entity;
+    if (entityItems.length) {
+      for (const entityItem of entityItems) {
+        const entityName = typeof entityItem.entity === 'string' ? entityItem.entity : undefined;
+        const entityGroupFragment = this._renderEntityGroupRow(entityItem, details.headings);
+        // Render all the items that match the heading row
+        for (const item of details.items.filter((item) => item.entity === entityName)) {
+          entityGroupFragment.append(this._renderTableRowsFromItem(item, details.headings));
+        }
+        const rowEls = this._dom.findAll('tr', entityGroupFragment);
+        if (entityName && rowEls.length) {
+          rowEls.forEach(row => row.dataset.entity = entityName);
+          this._adornEntityGroupRow(rowEls[0]);
+        }
+        tbodyElem.append(entityGroupFragment);
       }
-
-      for (const rowEl of this._dom.findAll('tr', rowsFragment)) {
-        // For zebra styling.
-        rowEl.classList.add(even ? 'lh-row--even' : 'lh-row--odd');
-        if (entityName && !rowEl.classList.contains('lh-sub-item-row')) {
-          rowEl.dataset.entity = entityName;
+    } else {
+      let even = true;
+      for (const item of details.items) {
+        const rowsFragment = this._renderTableRowsFromItem(item, details.headings);
+        const rowEls = this._dom.findAll('tr', rowsFragment);
+        const firstRowEl = rowEls[0];
+        if (typeof item.entity === 'string') {
+          firstRowEl.dataset.entity = item.entity;
+        }
+        if (details.isEntityGrouped && item.entity) {
+          // If the audit is already grouped, consider first row as a heading row.
+          firstRowEl.classList.add('lh-row--group');
+          this._adornEntityGroupRow(firstRowEl);
+        } else {
+          for (const rowEl of rowEls) {
+            // For zebra styling (same shade for a row and its sub-rows).
+            rowEl.classList.add(even ? 'lh-row--even' : 'lh-row--odd');
+          }
         }
+        even = !even;
+        tbodyElem.append(rowsFragment);
       }
-      even = !even;
-      tbodyElem.append(rowsFragment);
     }
 
     return tableElem;

package/report/renderer/report-renderer.js

@@ -268,6 +268,7 @@ export class ReportRenderer {
 
     const detailsRenderer = new DetailsRenderer(this._dom, {
       fullPageScreenshot: report.fullPageScreenshot ?? undefined,
+      entities: report.entities,
     });
 
     const categoryRenderer = new CategoryRenderer(this._dom, detailsRenderer);

package/report/renderer/report-ui-features.js

@@ -244,9 +244,11 @@ export class ReportUIFeatures {
 
     tablesWithUrls.forEach((tableEl) => {
       const rowEls = getTableRows(tableEl);
-      const primaryRowEls = rowEls.filter(rowEl => !rowEl.classList.contains('lh-sub-item-row'));
-      const thirdPartyRowEls = this._getThirdPartyRows(
-        primaryRowEls, Util.getFinalDisplayedUrl(this.json));
+      const nonSubItemRows = rowEls.filter(rowEl => !rowEl.classList.contains('lh-sub-item-row'));
+      const thirdPartyRowEls = this._getThirdPartyRows(nonSubItemRows,
+        Util.getFinalDisplayedUrl(this.json));
+      // Entity-grouped tables don't have zebra lines.
+      const hasZebraStyle = rowEls.some(rowEl => rowEl.classList.contains('lh-row--even'));
 
       // create input box
       const filterTemplate = this._dom.createComponent('3pFilter');
@@ -255,16 +257,19 @@ export class ReportUIFeatures {
       filterInput.addEventListener('change', e => {
         const shouldHideThirdParty = e.target instanceof HTMLInputElement && !e.target.checked;
         let even = true;
-        let rowEl = primaryRowEls[0];
+        let rowEl = nonSubItemRows[0];
         while (rowEl) {
           const shouldHide = shouldHideThirdParty && thirdPartyRowEls.includes(rowEl);
 
           // Iterate subsequent associated sub item rows.
           do {
             rowEl.classList.toggle('lh-row--hidden', shouldHide);
-            // Adjust for zebra styling.
-            rowEl.classList.toggle('lh-row--even', !shouldHide && even);
-            rowEl.classList.toggle('lh-row--odd', !shouldHide && !even);
+
+            if (hasZebraStyle) {
+              // Adjust for zebra styling.
+              rowEl.classList.toggle('lh-row--even', !shouldHide && even);
+              rowEl.classList.toggle('lh-row--odd', !shouldHide && !even);
+            }
 
             rowEl = /** @type {HTMLElement} */ (rowEl.nextElementSibling);
           } while (rowEl && rowEl.classList.contains('lh-sub-item-row'));
@@ -273,12 +278,16 @@ export class ReportUIFeatures {
         }
       });
 
+      // thirdPartyRowEls contains both heading and item rows.
+      // Filter out heading rows to get third party resource count.
+      const thirdPartyResourceCount = thirdPartyRowEls.filter(
+        rowEl => !rowEl.classList.contains('lh-row--group')).length;
       this._dom.find('.lh-3p-filter-count', filterTemplate).textContent =
-          `${thirdPartyRowEls.length}`;
+        `${thirdPartyResourceCount}`;
       this._dom.find('.lh-3p-ui-string', filterTemplate).textContent =
           Globals.strings.thirdPartyResourcesLabel;
 
-      const allThirdParty = thirdPartyRowEls.length === primaryRowEls.length;
+      const allThirdParty = thirdPartyRowEls.length === nonSubItemRows.length;
       const allFirstParty = !thirdPartyRowEls.length;
 
       // If all or none of the rows are 3rd party, hide the control.

package/report/renderer/report-utils.d.ts

@@ -13,15 +13,21 @@ export class ReportUtils {
      * Given an audit's details, identify and return a URL locator function that
      * can be called later with an `item` to extract the URL of it.
      * @param {LH.FormattedIcu<LH.Audit.Details.TableColumnHeading[]>} headings
-     * @return {{(item: LH.FormattedIcu<LH.Audit.Details.TableItem>): string|undefined}=}
+     * @return {((item: LH.FormattedIcu<LH.Audit.Details.TableItem>) => string|undefined)=}
      */
     static getUrlLocatorFn(headings: LH.FormattedIcu<LH.Audit.Details.TableColumnHeading[]>): ((item: LH.FormattedIcu<LH.Audit.Details.TableItem>) => string | undefined) | undefined;
     /**
      * Mark TableItems/OpportunityItems with entity names.
-     * @param {LH.Result.Entities|undefined} entities
-     * @param {import('../../types/lhr/audit-result').Result} audit
+     * @param {LH.Result.Entities} entities
+     * @param {LH.FormattedIcu<LH.Audit.Details.Opportunity|LH.Audit.Details.Table>} details
      */
-    static classifyEntities(entities: LH.Result.Entities | undefined, audit: import('../../types/lhr/audit-result').Result): void;
+    static classifyEntities(entities: LH.Result.Entities, details: LH.FormattedIcu<LH.Audit.Details.Opportunity | LH.Audit.Details.Table>): void;
+    /**
+     * Returns a comparator created from the supplied list of keys
+     * @param {Array<string>} sortedBy
+     * @return {((a: LH.Audit.Details.TableItem, b: LH.Audit.Details.TableItem) => number)}
+     */
+    static getTableItemSortComparator(sortedBy: Array<string>): (a: LH.Audit.Details.TableItem, b: LH.Audit.Details.TableItem) => number;
     /**
      * @param {LH.Result['configSettings']} settings
      * @return {!{deviceEmulation: string, screenEmulation?: string, networkThrottling: string, cpuThrottling: string, summary: string}}
@@ -125,5 +131,8 @@ export namespace UIStrings {
     const collapseView: string;
     const runtimeSlow4g: string;
     const runtimeCustom: string;
+    const firstPartyChipLabel: string;
+    const openInANewTabTooltip: string;
+    const unattributable: string;
 }
 //# sourceMappingURL=report-utils.d.ts.map

package/report/renderer/report-utils.js

@@ -27,7 +27,13 @@ class ReportUtils {
 
     for (const audit of Object.values(clone.audits)) {
       // Attach table/opportunity items with entity information.
-      ReportUtils.classifyEntities(clone.entities, audit);
+      if (audit.details) {
+        if (audit.details.type === 'opportunity' || audit.details.type === 'table') {
+          if (!audit.details.isEntityGrouped && clone.entities) {
+            ReportUtils.classifyEntities(clone.entities, audit.details);
+          }
+        }
+      }
     }
 
     // For convenience, smoosh all AuditResults into their auditRef (which has just weight & group)
@@ -79,7 +85,7 @@ class ReportUtils {
    * Given an audit's details, identify and return a URL locator function that
    * can be called later with an `item` to extract the URL of it.
    * @param {LH.FormattedIcu<LH.Audit.Details.TableColumnHeading[]>} headings
-   * @return {{(item: LH.FormattedIcu<LH.Audit.Details.TableItem>): string|undefined}=}
+   * @return {((item: LH.FormattedIcu<LH.Audit.Details.TableItem>) => string|undefined)=}
    */
   static getUrlLocatorFn(headings) {
     // The most common type, valueType=url.
@@ -109,17 +115,12 @@ class ReportUtils {
 
   /**
    * Mark TableItems/OpportunityItems with entity names.
-   * @param {LH.Result.Entities|undefined} entities
-   * @param {import('../../types/lhr/audit-result').Result} audit
+   * @param {LH.Result.Entities} entities
+   * @param {LH.FormattedIcu<LH.Audit.Details.Opportunity|LH.Audit.Details.Table>} details
    */
-  static classifyEntities(entities, audit) {
-    if (!entities) return;
-    if (audit.details?.type !== 'opportunity' && audit.details?.type !== 'table') {
-      return;
-    }
-
+  static classifyEntities(entities, details) {
     // If details.items are already marked with entity attribute during an audit, nothing to do here.
-    const {items, headings} = audit.details;
+    const {items, headings} = details;
     if (!items.length || items.some(item => item.entity)) return;
 
     // Identify a URL-locator function that we could call against each item to get its URL.
@@ -142,6 +143,30 @@ class ReportUtils {
     }
   }
 
+  /**
+   * Returns a comparator created from the supplied list of keys
+   * @param {Array<string>} sortedBy
+   * @return {((a: LH.Audit.Details.TableItem, b: LH.Audit.Details.TableItem) => number)}
+   */
+  static getTableItemSortComparator(sortedBy) {
+    return (a, b) => {
+      for (const key of sortedBy) {
+        const aVal = a[key];
+        const bVal = b[key];
+        if (typeof aVal !== typeof bVal || !['number', 'string'].includes(typeof aVal)) {
+          console.warn(`Warning: Attempting to sort unsupported value type: ${key}.`);
+        }
+        if (typeof aVal === 'number' && typeof bVal === 'number' && aVal !== bVal) {
+          return bVal - aVal;
+        }
+        if (typeof aVal === 'string' && typeof bVal === 'string' && aVal !== bVal) {
+          return aVal.localeCompare(bVal);
+        }
+      }
+      return 0;
+    };
+  }
+
   /**
    * @param {LH.Result['configSettings']} settings
    * @return {!{deviceEmulation: string, screenEmulation?: string, networkThrottling: string, cpuThrottling: string, summary: string}}
@@ -440,6 +465,13 @@ const UIStrings = {
   runtimeSlow4g: 'Slow 4G throttling',
   /** Label indicating that Lighthouse throttled the page using custom throttling settings. */
   runtimeCustom: 'Custom throttling',
+
+  /** This label is for a decorative chip that is included in a table row. The label indicates that the entity/company name in the row belongs to the first-party (or "1st-party"). First-party label is used to identify resources that are directly controlled by the owner of the web page. */
+  firstPartyChipLabel: '1st party',
+  /** Descriptive explanation in a tooltip form for a link to be opened in a new tab of the browser. */
+  openInANewTabTooltip: 'Open in a new tab',
+  /** Generic category name for all resources that could not be attributed to a 1st or 3rd party entity. */
+  unattributable: 'Unattributable',
 };
 
 export {

package/shared/localization/locales/en-US.json

@@ -3047,6 +3047,9 @@
   "report/renderer/report-utils.js | expandView": {
     "message": "Expand view"
   },
+  "report/renderer/report-utils.js | firstPartyChipLabel": {
+    "message": "1st party"
+  },
   "report/renderer/report-utils.js | footerIssue": {
     "message": "File an issue"
   },
@@ -3065,6 +3068,9 @@
   "report/renderer/report-utils.js | notApplicableAuditsGroupTitle": {
     "message": "Not applicable"
   },
+  "report/renderer/report-utils.js | openInANewTabTooltip": {
+    "message": "Open in a new tab"
+  },
   "report/renderer/report-utils.js | opportunityResourceColumnLabel": {
     "message": "Opportunity"
   },
@@ -3143,6 +3149,9 @@
   "report/renderer/report-utils.js | toplevelWarningsMessage": {
     "message": "There were issues affecting this run of Lighthouse:"
   },
+  "report/renderer/report-utils.js | unattributable": {
+    "message": "Unattributable"
+  },
   "report/renderer/report-utils.js | varianceDisclaimer": {
     "message": "Values are estimated and may vary. The [performance score is calculated](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring/) directly from these metrics."
   },

package/shared/localization/locales/en-XL.json

@@ -3047,6 +3047,9 @@
   "report/renderer/report-utils.js | expandView": {
     "message": "Êx́p̂án̂d́ v̂íêẃ"
   },
+  "report/renderer/report-utils.js | firstPartyChipLabel": {
+    "message": "1ŝt́ p̂ár̂t́ŷ"
+  },
   "report/renderer/report-utils.js | footerIssue": {
     "message": "F̂íl̂é âń îśŝúê"
   },
@@ -3065,6 +3068,9 @@
   "report/renderer/report-utils.js | notApplicableAuditsGroupTitle": {
     "message": "N̂ót̂ áp̂ṕl̂íĉáb̂ĺê"
   },
+  "report/renderer/report-utils.js | openInANewTabTooltip": {
+    "message": "Ôṕêń îń â ńêẃ t̂áb̂"
+  },
   "report/renderer/report-utils.js | opportunityResourceColumnLabel": {
     "message": "Ôṕp̂ór̂t́ûńît́ŷ"
   },
@@ -3143,6 +3149,9 @@
   "report/renderer/report-utils.js | toplevelWarningsMessage": {
     "message": "T̂h́êŕê ẃêŕê íŝśûéŝ áf̂f́êćt̂ín̂ǵ t̂h́îś r̂ún̂ óf̂ Ĺîǵĥt́ĥóûśê:"
   },
+  "report/renderer/report-utils.js | unattributable": {
+    "message": "Ûńât́t̂ŕîb́ût́âb́l̂é"
+  },
   "report/renderer/report-utils.js | varianceDisclaimer": {
     "message": "V̂ál̂úêś âŕê éŝt́îḿât́êd́ âńd̂ ḿâý v̂ár̂ý. T̂h́ê [ṕêŕf̂ór̂ḿâńĉé ŝćôŕê íŝ ćâĺĉúl̂át̂éd̂](https://developer.chrome.com/docs/lighthouse/performance/performance-scoring/) d́îŕêćt̂ĺŷ f́r̂óm̂ t́ĥéŝé m̂ét̂ŕîćŝ."
   },

package/types/lhr/audit-details.d.ts

@@ -69,6 +69,15 @@ declare module Details {
     headings: TableColumnHeading[];
     items: OpportunityItem[];
     debugData?: DebugData;
+    /**
+     * Columns to sort the items by, during grouping.
+     * If omitted, entity groups will be sorted by the audit ordering vs. the new totals.
+     */
+    sortedBy?: Array<string>;
+    /** Will be true if the table is already grouped by entities. */
+    isEntityGrouped?: boolean;
+    /** Column keys to skip summing. If omitted, all column types supported are summed. */
+    skipSumming?: Array<string>;
   }
 
   interface Screenshot {
@@ -96,6 +105,15 @@ declare module Details {
       wastedBytes?: number;
     };
     debugData?: DebugData;
+    /**
+     * Columns to sort the items by, during grouping.
+     * If omitted, entity groups will be sorted by the audit ordering vs. the new totals.
+     */
+    sortedBy?: Array<string>;
+    /** Will be true if the table is already grouped by entities. */
+    isEntityGrouped?: boolean;
+    /** Column keys to skip summing. If omitted, all column types supported are summed. */
+    skipSumming?: Array<string>;
   }
 
   /** A table item for rows that are nested within a top-level TableItem (row). */