lighthouse 9.6.7 → 10.0.0

package/report/generator/tsconfig.json

@@ -1,8 +1,6 @@
 {
   "extends": "../../tsconfig-base.json",
   "compilerOptions": {
-    "outDir": "../../.tmp/tsbuildinfo/report/generator",
-
     // Limit defs to base JS and DOM (for URL: https://github.com/DefinitelyTyped/DefinitelyTyped/issues/34960).
     "lib": ["es2020", "dom"],
     // Only include `@types/node` from node_modules/.
@@ -13,5 +11,6 @@
   ],
   "include": [
     "**/*.js",
+    "../../esm-utils.js",
   ],
 }

package/report/renderer/api.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @param {LH.Result} lhr
+ * @param {LH.Renderer.Options} opts
+ * @return {HTMLElement}
+ */
+export function renderReport(lhr: LH.Result, opts?: LH.Renderer.Options): HTMLElement;
+/**
+ * @param {LH.ReportResult.Category} category
+ * @param {Parameters<CategoryRenderer['renderCategoryScore']>[2]=} options
+ * @return {DocumentFragment}
+ */
+export function renderCategoryScore(category: LH.ReportResult.Category, options?: [category: import("../types/report-result.js").default.Category, groupDefinitions: Record<string, import("../../types/lhr/lhr.js").default.ReportGroup>, options?: {
+    gatherMode: import("../../types/lhr/lhr.js").default.GatherMode;
+    omitLabel?: boolean | undefined;
+    onPageAnchorRendered?: ((link: HTMLAnchorElement) => void) | undefined;
+} | undefined][2] | undefined): DocumentFragment;
+/**
+ * @param {Blob} blob
+ * @param {string} filename
+ */
+export function saveFile(blob: Blob, filename: string): void;
+/**
+ * @param {string} markdownText
+ * @return {Element}
+ */
+export function convertMarkdownCodeSnippets(markdownText: string): Element;
+/**
+ * @return {DocumentFragment}
+ */
+export function createStylesElement(): DocumentFragment;
+//# sourceMappingURL=api.d.ts.map

package/report/renderer/api.js

@@ -3,8 +3,6 @@
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
  * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
  */
-'use strict';
-
 
 import {DOM} from '../renderer/dom.js';
 import {ReportRenderer} from '../renderer/report-renderer.js';

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

@@ -0,0 +1,176 @@
+export class CategoryRenderer {
+    /**
+     * @param {DOM} dom
+     * @param {DetailsRenderer} detailsRenderer
+     */
+    constructor(dom: DOM, detailsRenderer: DetailsRenderer);
+    /** @type {DOM} */
+    dom: DOM;
+    /** @type {DetailsRenderer} */
+    detailsRenderer: DetailsRenderer;
+    /**
+     * Display info per top-level clump. Define on class to avoid race with Util init.
+     */
+    get _clumpTitles(): {
+        warning: string;
+        manual: string;
+        passed: string;
+        notApplicable: string;
+    };
+    /**
+     * @param {LH.ReportResult.AuditRef} audit
+     * @return {Element}
+     */
+    renderAudit(audit: LH.ReportResult.AuditRef): Element;
+    /**
+     * Populate an DOM tree with audit details. Used by renderAudit and renderOpportunity
+     * @param {LH.ReportResult.AuditRef} audit
+     * @param {DocumentFragment} component
+     * @return {!Element}
+     */
+    populateAuditValues(audit: LH.ReportResult.AuditRef, component: DocumentFragment): Element;
+    /**
+     * Inject the final screenshot next to the score gauge of the first category (likely Performance)
+     * @param {HTMLElement} categoriesEl
+     * @param {LH.ReportResult['audits']} audits
+     * @param {Element} scoreScaleEl
+     */
+    injectFinalScreenshot(categoriesEl: HTMLElement, audits: LH.ReportResult['audits'], scoreScaleEl: Element): null | undefined;
+    /**
+     * @return {Element}
+     */
+    _createChevron(): Element;
+    /**
+     * @param {Element} element DOM node to populate with values.
+     * @param {number|null} score
+     * @param {string} scoreDisplayMode
+     * @return {!Element}
+     */
+    _setRatingClass(element: Element, score: number | null, scoreDisplayMode: string): Element;
+    /**
+     * @param {LH.ReportResult.Category} category
+     * @param {Record<string, LH.Result.ReportGroup>} groupDefinitions
+     * @param {{gatherMode: LH.Result.GatherMode}=} options
+     * @return {DocumentFragment}
+     */
+    renderCategoryHeader(category: LH.ReportResult.Category, groupDefinitions: Record<string, LH.Result.ReportGroup>, options?: {
+        gatherMode: LH.Result.GatherMode;
+    } | undefined): DocumentFragment;
+    /**
+     * Renders the group container for a group of audits. Individual audit elements can be added
+     * directly to the returned element.
+     * @param {LH.Result.ReportGroup} group
+     * @return {[Element, Element | null]}
+     */
+    renderAuditGroup(group: LH.Result.ReportGroup): [Element, Element | null];
+    /**
+     * Takes an array of auditRefs, groups them if requested, then returns an
+     * array of audit and audit-group elements.
+     * @param {Array<LH.ReportResult.AuditRef>} auditRefs
+     * @param {Object<string, LH.Result.ReportGroup>} groupDefinitions
+     * @return {Array<Element>}
+     */
+    _renderGroupedAudits(auditRefs: Array<LH.ReportResult.AuditRef>, groupDefinitions: {
+        [x: string]: LH.Result.ReportGroup;
+    }): Array<Element>;
+    /**
+     * Take a set of audits, group them if they have groups, then render in a top-level
+     * clump that can't be expanded/collapsed.
+     * @param {Array<LH.ReportResult.AuditRef>} auditRefs
+     * @param {Object<string, LH.Result.ReportGroup>} groupDefinitions
+     * @return {Element}
+     */
+    renderUnexpandableClump(auditRefs: Array<LH.ReportResult.AuditRef>, groupDefinitions: {
+        [x: string]: LH.Result.ReportGroup;
+    }): Element;
+    /**
+     * Take a set of audits and render in a top-level, expandable clump that starts
+     * in a collapsed state.
+     * @param {Exclude<TopLevelClumpId, 'failed'>} clumpId
+     * @param {{auditRefs: Array<LH.ReportResult.AuditRef>, description?: string}} clumpOpts
+     * @return {!Element}
+     */
+    renderClump(clumpId: Exclude<TopLevelClumpId, 'failed'>, { auditRefs, description }: {
+        auditRefs: Array<LH.ReportResult.AuditRef>;
+        description?: string;
+    }): Element;
+    /**
+     * @param {LH.ReportResult.Category} category
+     * @param {Record<string, LH.Result.ReportGroup>} groupDefinitions
+     * @param {{gatherMode: LH.Result.GatherMode, omitLabel?: boolean, onPageAnchorRendered?: (link: HTMLAnchorElement) => void}=} options
+     * @return {DocumentFragment}
+     */
+    renderCategoryScore(category: LH.ReportResult.Category, groupDefinitions: Record<string, LH.Result.ReportGroup>, options?: {
+        gatherMode: LH.Result.GatherMode;
+        omitLabel?: boolean | undefined;
+        onPageAnchorRendered?: ((link: HTMLAnchorElement) => void) | undefined;
+    } | undefined): DocumentFragment;
+    /**
+     * @param {LH.ReportResult.Category} category
+     * @param {Record<string, LH.Result.ReportGroup>} groupDefinitions
+     * @return {DocumentFragment}
+     */
+    renderScoreGauge(category: LH.ReportResult.Category, groupDefinitions: Record<string, LH.Result.ReportGroup>): DocumentFragment;
+    /**
+     * @param {LH.ReportResult.Category} category
+     * @return {DocumentFragment}
+     */
+    renderCategoryFraction(category: LH.ReportResult.Category): DocumentFragment;
+    /**
+     * Returns true if an LH category has any non-"notApplicable" audits.
+     * @param {LH.ReportResult.Category} category
+     * @return {boolean}
+     */
+    hasApplicableAudits(category: LH.ReportResult.Category): boolean;
+    /**
+     * Define the score arc of the gauge
+     * Credit to xgad for the original technique: https://codepen.io/xgad/post/svg-radial-progress-meters
+     * @param {SVGCircleElement} arcElem
+     * @param {number} percent
+     */
+    _setGaugeArc(arcElem: SVGCircleElement, percent: number): void;
+    /**
+     * @param {LH.ReportResult.AuditRef} audit
+     * @return {boolean}
+     */
+    _auditHasWarning(audit: LH.ReportResult.AuditRef): boolean;
+    /**
+     * Returns the id of the top-level clump to put this audit in.
+     * @param {LH.ReportResult.AuditRef} auditRef
+     * @return {TopLevelClumpId}
+     */
+    _getClumpIdForAuditRef(auditRef: LH.ReportResult.AuditRef): TopLevelClumpId;
+    /**
+     * Renders a set of top level sections (clumps), under a status of failed, warning,
+     * manual, passed, or notApplicable. The result ends up something like:
+     *
+     * failed clump
+     *   ├── audit 1 (w/o group)
+     *   ├── audit 2 (w/o group)
+     *   ├── audit group
+     *   |  ├── audit 3
+     *   |  └── audit 4
+     *   └── audit group
+     *      ├── audit 5
+     *      └── audit 6
+     * other clump (e.g. 'manual')
+     *   ├── audit 1
+     *   ├── audit 2
+     *   ├── …
+     *   ⋮
+     * @param {LH.ReportResult.Category} category
+     * @param {Object<string, LH.Result.ReportGroup>=} groupDefinitions
+     * @param {{gatherMode: LH.Result.GatherMode}=} options
+     * @return {Element}
+     */
+    render(category: LH.ReportResult.Category, groupDefinitions?: {
+        [x: string]: LH.Result.ReportGroup;
+    } | undefined, options?: {
+        gatherMode: LH.Result.GatherMode;
+    } | undefined): Element;
+}
+export type DOM = import('./dom.js').DOM;
+export type ReportRenderer = import('./report-renderer.js').ReportRenderer;
+export type DetailsRenderer = import('./details-renderer.js').DetailsRenderer;
+export type TopLevelClumpId = 'failed' | 'warning' | 'manual' | 'passed' | 'notApplicable';
+//# sourceMappingURL=category-renderer.d.ts.map

package/report/renderer/category-renderer.js

@@ -14,14 +14,14 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-'use strict';
 
 /** @typedef {import('./dom.js').DOM} DOM */
 /** @typedef {import('./report-renderer.js').ReportRenderer} ReportRenderer */
 /** @typedef {import('./details-renderer.js').DetailsRenderer} DetailsRenderer */
 /** @typedef {'failed'|'warning'|'manual'|'passed'|'notApplicable'} TopLevelClumpId */
 
-import {Util} from './util.js';
+import {ReportUtils} from './report-utils.js';
+import {Globals} from './report-globals.js';
 
 export class CategoryRenderer {
   /**
@@ -40,10 +40,10 @@ export class CategoryRenderer {
    */
   get _clumpTitles() {
     return {
-      warning: Util.i18n.strings.warningAuditsGroupTitle,
-      manual: Util.i18n.strings.manualAuditsGroupTitle,
-      passed: Util.i18n.strings.passedAuditsGroupTitle,
-      notApplicable: Util.i18n.strings.notApplicableAuditsGroupTitle,
+      warning: Globals.strings.warningAuditsGroupTitle,
+      manual: Globals.strings.manualAuditsGroupTitle,
+      passed: Globals.strings.passedAuditsGroupTitle,
+      notApplicable: Globals.strings.notApplicableAuditsGroupTitle,
     };
   }
 
@@ -63,7 +63,7 @@ export class CategoryRenderer {
    * @return {!Element}
    */
   populateAuditValues(audit, component) {
-    const strings = Util.i18n.strings;
+    const strings = Globals.strings;
     const auditEl = this.dom.find('.lh-audit', component);
     auditEl.id = audit.result.id;
     const scoreDisplayMode = audit.result.scoreDisplayMode;
@@ -73,9 +73,9 @@ export class CategoryRenderer {
     }
 
     const titleEl = this.dom.find('.lh-audit__title', auditEl);
-    titleEl.appendChild(this.dom.convertMarkdownCodeSnippets(audit.result.title));
+    titleEl.append(this.dom.convertMarkdownCodeSnippets(audit.result.title));
     const descEl = this.dom.find('.lh-audit__description', auditEl);
-    descEl.appendChild(this.dom.convertMarkdownLinkSnippets(audit.result.description));
+    descEl.append(this.dom.convertMarkdownLinkSnippets(audit.result.description));
 
     for (const relevantMetric of audit.relevantMetrics || []) {
       const adornEl = this.dom.createChildOf(descEl, 'span', 'lh-audit__adorn');
@@ -85,19 +85,16 @@ export class CategoryRenderer {
 
     if (audit.stackPacks) {
       audit.stackPacks.forEach(pack => {
-        const packElm = this.dom.createElement('div');
-        packElm.classList.add('lh-audit__stackpack');
-
-        const packElmImg = this.dom.createElement('img');
-        packElmImg.classList.add('lh-audit__stackpack__img');
+        const packElmImg = this.dom.createElement('img', 'lh-audit__stackpack__img');
         packElmImg.src = pack.iconDataURL;
         packElmImg.alt = pack.title;
-        packElm.appendChild(packElmImg);
 
-        packElm.appendChild(this.dom.convertMarkdownLinkSnippets(pack.description));
+        const snippets = this.dom.convertMarkdownLinkSnippets(pack.description);
+        const packElm = this.dom.createElement('div', 'lh-audit__stackpack');
+        packElm.append(packElmImg, snippets);
 
         this.dom.find('.lh-audit__stackpacks', auditEl)
-          .appendChild(packElm);
+          .append(packElm);
       });
     }
 
@@ -106,12 +103,12 @@ export class CategoryRenderer {
       const elem = this.detailsRenderer.render(audit.result.details);
       if (elem) {
         elem.classList.add('lh-details');
-        header.appendChild(elem);
+        header.append(elem);
       }
     }
 
     // Add chevron SVG to the end of the summary
-    this.dom.find('.lh-chevron-container', auditEl).appendChild(this._createChevron());
+    this.dom.find('.lh-chevron-container', auditEl).append(this._createChevron());
     this._setRatingClass(auditEl, audit.result.score, scoreDisplayMode);
 
     if (audit.result.scoreDisplayMode === 'error') {
@@ -133,7 +130,7 @@ export class CategoryRenderer {
     const warningsEl = this.dom.createChildOf(summaryEl, 'div', 'lh-warnings');
     this.dom.createChildOf(warningsEl, 'span').textContent = strings.warningHeader;
     if (warnings.length === 1) {
-      warningsEl.appendChild(this.dom.createTextNode(warnings.join('')));
+      warningsEl.append(this.dom.createTextNode(warnings.join('')));
     } else {
       const warningsUl = this.dom.createChildOf(warningsEl, 'ul');
       for (const warning of warnings) {
@@ -189,7 +186,7 @@ export class CategoryRenderer {
    * @return {!Element}
    */
   _setRatingClass(element, score, scoreDisplayMode) {
-    const rating = Util.calculateRating(score, scoreDisplayMode);
+    const rating = ReportUtils.calculateRating(score, scoreDisplayMode);
     element.classList.add(`lh-audit--${scoreDisplayMode.toLowerCase()}`);
     if (scoreDisplayMode !== 'informative') {
       element.classList.add(`lh-audit--${rating}`);
@@ -208,11 +205,11 @@ export class CategoryRenderer {
 
     const gaugeContainerEl = this.dom.find('.lh-score__gauge', component);
     const gaugeEl = this.renderCategoryScore(category, groupDefinitions, options);
-    gaugeContainerEl.appendChild(gaugeEl);
+    gaugeContainerEl.append(gaugeEl);
 
     if (category.description) {
       const descEl = this.dom.convertMarkdownLinkSnippets(category.description);
-      this.dom.find('.lh-category-header__description', component).appendChild(descEl);
+      this.dom.find('.lh-category-header__description', component).append(descEl);
     }
 
     return component;
@@ -231,13 +228,13 @@ export class CategoryRenderer {
 
     this.dom.createChildOf(auditGroupHeader, 'span', 'lh-audit-group__title')
       .textContent = group.title;
-    groupEl.appendChild(auditGroupHeader);
+    groupEl.append(auditGroupHeader);
 
     let footerEl = null;
     if (group.description) {
       footerEl = this.dom.convertMarkdownLinkSnippets(group.description);
       footerEl.classList.add('lh-audit-group__description', 'lh-audit-group__footer');
-      groupEl.appendChild(footerEl);
+      groupEl.append(footerEl);
     }
 
     return [groupEl, footerEl];
@@ -301,7 +298,7 @@ export class CategoryRenderer {
   renderUnexpandableClump(auditRefs, groupDefinitions) {
     const clumpElement = this.dom.createElement('div');
     const elements = this._renderGroupedAudits(auditRefs, groupDefinitions);
-    elements.forEach(elem => clumpElement.appendChild(elem));
+    elements.forEach(elem => clumpElement.append(elem));
     return clumpElement;
   }
 
@@ -335,11 +332,11 @@ export class CategoryRenderer {
     if (description) {
       const descriptionEl = this.dom.convertMarkdownLinkSnippets(description);
       descriptionEl.classList.add('lh-audit-group__description', 'lh-audit-group__footer');
-      el.appendChild(descriptionEl);
+      el.append(descriptionEl);
     }
 
-    this.dom.find('.lh-clump-toggletext--show', el).textContent = Util.i18n.strings.show;
-    this.dom.find('.lh-clump-toggletext--hide', el).textContent = Util.i18n.strings.hide;
+    this.dom.find('.lh-clump-toggletext--show', el).textContent = Globals.strings.show;
+    this.dom.find('.lh-clump-toggletext--hide', el).textContent = Globals.strings.hide;
 
     clumpElement.classList.add(`lh-clump--${clumpId.toLowerCase()}`);
     return el;
@@ -353,7 +350,7 @@ export class CategoryRenderer {
    */
   renderCategoryScore(category, groupDefinitions, options) {
     let categoryScore;
-    if (options && Util.shouldDisplayAsFraction(options.gatherMode)) {
+    if (options && ReportUtils.shouldDisplayAsFraction(options.gatherMode)) {
       categoryScore = this.renderCategoryFraction(category);
     } else {
       categoryScore = this.renderScoreGauge(category, groupDefinitions);
@@ -381,7 +378,7 @@ export class CategoryRenderer {
     const tmpl = this.dom.createComponent('gauge');
     const wrapper = this.dom.find('a.lh-gauge__wrapper', tmpl);
 
-    if (Util.isPluginCategory(category.id)) {
+    if (ReportUtils.isPluginCategory(category.id)) {
       wrapper.classList.add('lh-gauge__wrapper--plugin');
     }
 
@@ -397,16 +394,16 @@ export class CategoryRenderer {
     percentageEl.textContent = scoreOutOf100.toString();
     if (category.score === null) {
       percentageEl.textContent = '?';
-      percentageEl.title = Util.i18n.strings.errorLabel;
+      percentageEl.title = Globals.strings.errorLabel;
     }
 
     // Render a numerical score if the category has applicable audits, or no audits whatsoever.
     if (category.auditRefs.length === 0 || this.hasApplicableAudits(category)) {
-      wrapper.classList.add(`lh-gauge__wrapper--${Util.calculateRating(category.score)}`);
+      wrapper.classList.add(`lh-gauge__wrapper--${ReportUtils.calculateRating(category.score)}`);
     } else {
       wrapper.classList.add(`lh-gauge__wrapper--not-applicable`);
       percentageEl.textContent = '-';
-      percentageEl.title = Util.i18n.strings.notApplicableAuditsGroupTitle;
+      percentageEl.title = Globals.strings.notApplicableAuditsGroupTitle;
     }
 
     this.dom.find('.lh-gauge__label', tmpl).textContent = category.title;
@@ -421,15 +418,16 @@ export class CategoryRenderer {
     const tmpl = this.dom.createComponent('fraction');
     const wrapper = this.dom.find('a.lh-fraction__wrapper', tmpl);
 
-    const {numPassed, numPassableAudits, totalWeight} = Util.calculateCategoryFraction(category);
+    const {numPassed, numPassableAudits, totalWeight} =
+      ReportUtils.calculateCategoryFraction(category);
 
     const fraction = numPassed / numPassableAudits;
     const content = this.dom.find('.lh-fraction__content', tmpl);
     const text = this.dom.createElement('span');
     text.textContent = `${numPassed}/${numPassableAudits}`;
-    content.appendChild(text);
+    content.append(text);
 
-    let rating = Util.calculateRating(fraction);
+    let rating = ReportUtils.calculateRating(fraction);
 
     // If none of the available audits can affect the score, a rating isn't useful.
     // The flow report should display the fraction with neutral icon and coloring in this case.
@@ -494,7 +492,7 @@ export class CategoryRenderer {
       return scoreDisplayMode;
     }
 
-    if (Util.showAsPassed(auditRef.result)) {
+    if (ReportUtils.showAsPassed(auditRef.result)) {
       if (this._auditHasWarning(auditRef)) {
         return 'warning';
       } else {
@@ -531,7 +529,7 @@ export class CategoryRenderer {
   render(category, groupDefinitions = {}, options) {
     const element = this.dom.createElement('div', 'lh-category');
     element.id = category.id;
-    element.appendChild(this.renderCategoryHeader(category, groupDefinitions, options));
+    element.append(this.renderCategoryHeader(category, groupDefinitions, options));
 
     // Top level clumps for audits, in order they will appear in the report.
     /** @type {Map<TopLevelClumpId, Array<LH.ReportResult.AuditRef>>} */
@@ -564,13 +562,13 @@ export class CategoryRenderer {
       if (clumpId === 'failed') {
         const clumpElem = this.renderUnexpandableClump(auditRefs, groupDefinitions);
         clumpElem.classList.add(`lh-clump--failed`);
-        element.appendChild(clumpElem);
+        element.append(clumpElem);
         continue;
       }
 
       const description = clumpId === 'manual' ? category.manualDescription : undefined;
       const clumpElem = this.renderClump(clumpId, {auditRefs, description});
-      element.appendChild(clumpElem);
+      element.append(clumpElem);
     }
 
     return element;

package/report/renderer/components.d.ts

@@ -0,0 +1,10 @@
+/** @typedef {'3pFilter'|'audit'|'categoryHeader'|'chevron'|'clump'|'crc'|'crcChain'|'elementScreenshot'|'footer'|'fraction'|'gauge'|'gaugePwa'|'heading'|'metric'|'opportunity'|'opportunityHeader'|'scorescale'|'scoresWrapper'|'snippet'|'snippetContent'|'snippetHeader'|'snippetLine'|'styles'|'topbar'|'warningsToplevel'} ComponentName */
+/**
+ * @param {DOM} dom
+ * @param {ComponentName} componentName
+ * @return {DocumentFragment}
+ */
+export function createComponent(dom: DOM, componentName: ComponentName): DocumentFragment;
+export type DOM = import('./dom.js').DOM;
+export type ComponentName = '3pFilter' | 'audit' | 'categoryHeader' | 'chevron' | 'clump' | 'crc' | 'crcChain' | 'elementScreenshot' | 'footer' | 'fraction' | 'gauge' | 'gaugePwa' | 'heading' | 'metric' | 'opportunity' | 'opportunityHeader' | 'scorescale' | 'scoresWrapper' | 'snippet' | 'snippetContent' | 'snippetHeader' | 'snippetLine' | 'styles' | 'topbar' | 'warningsToplevel';
+//# sourceMappingURL=components.d.ts.map