chrome-devtools-frontend 1.0.1596260 → 1.0.1596535

package/front_end/panels/timeline/components/CWVMetrics.ts

@@ -0,0 +1,339 @@
+// Copyright 2026 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as i18n from '../../../core/i18n/i18n.js';
+import * as Platform from '../../../core/platform/platform.js';
+import * as CrUXManager from '../../../models/crux-manager/crux-manager.js';
+import * as Trace from '../../../models/trace/trace.js';
+import * as Buttons from '../../../ui/components/buttons/buttons.js';
+import * as UI from '../../../ui/legacy/legacy.js';
+import * as Lit from '../../../ui/lit/lit.js';
+import * as VisualLogging from '../../../ui/visual_logging/visual_logging.js';
+
+import cwvMetricsStyles from './cwvMetrics.css.js';
+import {md} from './insights/Helpers.js';
+import * as Insights from './insights/insights.js';
+import {isFieldWorseThanLocal, NumberWithUnit} from './Utils.js';
+
+const {html} = Lit.StaticHtml;
+
+const UIStrings = {
+  /**
+   * @description title used for a metric value to tell the user about its score classification
+   * @example {INP} PH1
+   * @example {1.2s} PH2
+   * @example {poor} PH3
+   */
+  metricScore: '{PH1}: {PH2} {PH3} score',
+  /**
+   * @description title used for a metric value to tell the user that the data is unavailable
+   * @example {INP} PH1
+   */
+  metricScoreUnavailable: '{PH1}: unavailable',
+  /**
+   * @description Label denoting that metrics were observed in the field, from real use data (CrUX). Also denotes if from URL or Origin dataset.
+   * @example {URL} PH1
+   */
+  fieldScoreLabel: 'Field ({PH1})',
+  /**
+   * @description Label for an option that selects the page's specific URL as opposed to it's entire origin/domain.
+   */
+  urlOption: 'URL',
+  /**
+   * @description Label for an option that selects the page's entire origin/domain as opposed to it's specific URL.
+   */
+  originOption: 'Origin',
+  /**
+   * @description Title for button that closes a warning popup.
+   */
+  dismissTitle: 'Dismiss',
+  /**
+   * @description Title shown in a warning dialog when field metrics (collected from real users) is worse than the locally observed metrics.
+   */
+  fieldMismatchTitle: 'Field & local metrics mismatch',
+  /**
+   * @description Text shown in a warning dialog when field metrics (collected from real users) is worse than the locally observed metrics.
+   * Asks user to use features such as throttling and device emulation.
+   */
+  fieldMismatchNotice:
+      'There are many reasons why local and field metrics [may not match](https://web.dev/articles/lab-and-field-data-differences). ' +
+      'Adjust [throttling settings and device emulation](https://developer.chrome.com/docs/devtools/device-mode) to analyze traces more similar to the average user\'s environment.',
+} as const;
+
+const str_ = i18n.i18n.registerUIStrings('panels/timeline/components/CWVMetrics.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+
+interface LocalMetrics {
+  lcp: {value: Trace.Types.Timing.Micro, event: Trace.Types.Events.AnyLargestContentfulPaintCandidate}|null;
+  cls: {value: number, worstClusterEvent: Trace.Types.Events.Event|null};
+  inp: {value: Trace.Types.Timing.Micro, event: Trace.Types.Events.SyntheticInteractionPair}|null;
+}
+
+function getLocalMetrics(parsedTrace: Trace.TraceModel.ParsedTrace|null, insightSetKey: string|null): LocalMetrics|
+    null {
+  if (!parsedTrace || !insightSetKey) {
+    return null;
+  }
+
+  const insightSet = parsedTrace.insights?.get(insightSetKey);
+  if (!insightSet) {
+    return null;
+  }
+
+  const lcp = Trace.Insights.Common.getLCP(insightSet);
+  const cls = Trace.Insights.Common.getCLS(insightSet);
+  const inp = Trace.Insights.Common.getINP(insightSet);
+
+  return {lcp, cls, inp};
+}
+
+export function getFieldMetrics(parsedTrace: Trace.TraceModel.ParsedTrace|null, insightSetKey: string|null):
+    Trace.Insights.Common.CrUXFieldMetricResults|null {
+  if (!parsedTrace || !parsedTrace.metadata?.cruxFieldData || !insightSetKey) {
+    return null;
+  }
+
+  const insightSet = parsedTrace.insights?.get(insightSetKey);
+  if (!insightSet) {
+    return null;
+  }
+
+  let scope: CrUXManager.Scope|null = null;
+  try {
+    scope = CrUXManager.CrUXManager.instance().getSelectedScope();
+  } catch {
+    // test environment
+  }
+
+  const fieldMetricsResults =
+      Trace.Insights.Common.getFieldMetricsForInsightSet(insightSet, parsedTrace.metadata, scope);
+  if (!fieldMetricsResults) {
+    return null;
+  }
+
+  return fieldMetricsResults;
+}
+
+interface MetricsViewInput {
+  parsedTrace: Trace.TraceModel.ParsedTrace|null;
+  insightSetKey: string|null;
+  didDismissFieldMismatchNotice: boolean;
+  onDismisFieldMismatchNotice: () => void;
+  onClickMetric: (traceEvent: Trace.Types.Events.Event) => void;
+}
+
+type MetricsView = (input: MetricsViewInput, output: undefined, target: HTMLElement) => void;
+
+const CWV_METRICS_VIEW: MetricsView = (input, _output, target) => {
+  const {
+    parsedTrace,
+    insightSetKey,
+    didDismissFieldMismatchNotice,
+    onDismisFieldMismatchNotice,
+    onClickMetric,
+  } = input;
+
+  const local = getLocalMetrics(parsedTrace, insightSetKey);
+  const field = getFieldMetrics(parsedTrace, insightSetKey);
+
+  const localValues = {
+    lcp: local?.lcp?.value !== undefined ? Trace.Helpers.Timing.microToMilli(local?.lcp.value) : undefined,
+    inp: local?.inp?.value !== undefined ? Trace.Helpers.Timing.microToMilli(local?.inp.value) : undefined,
+  };
+  const fieldValues = field && {
+    lcp: field.lcp?.value !== undefined ? Trace.Helpers.Timing.microToMilli(field.lcp.value) : undefined,
+    inp: field.inp?.value !== undefined ? Trace.Helpers.Timing.microToMilli(field.inp.value) : undefined,
+  };
+  const showFieldMismatchNotice =
+      !didDismissFieldMismatchNotice && !!fieldValues && isFieldWorseThanLocal(localValues, fieldValues);
+
+  function renderMetricValue(
+      metric: 'LCP'|'CLS'|'INP', value: number|null, relevantEvent: Trace.Types.Events.Event|null): Lit.LitTemplate {
+    let valueText: string;
+    let valueDisplay: HTMLElement|string;
+    let classification;
+    if (value === null) {
+      valueText = valueDisplay = '-';
+      classification = Trace.Handlers.ModelHandlers.PageLoadMetrics.ScoreClassification.UNCLASSIFIED;
+    } else if (metric === 'LCP') {
+      const micros = value as Trace.Types.Timing.Micro;
+      const {text, element} = NumberWithUnit.formatMicroSecondsAsSeconds(micros);
+      valueText = text;
+      valueDisplay = element;
+      classification =
+          Trace.Handlers.ModelHandlers.PageLoadMetrics.scoreClassificationForLargestContentfulPaint(micros);
+    } else if (metric === 'CLS') {
+      valueText = valueDisplay = value ? value.toFixed(2) : '0';
+      classification = Trace.Handlers.ModelHandlers.LayoutShifts.scoreClassificationForLayoutShift(value);
+    } else if (metric === 'INP') {
+      const micros = value as Trace.Types.Timing.Micro;
+      const {text, element} = NumberWithUnit.formatMicroSecondsAsMillisFixed(micros);
+      valueText = text;
+      valueDisplay = element;
+      classification =
+          Trace.Handlers.ModelHandlers.UserInteractions.scoreClassificationForInteractionToNextPaint(micros);
+    } else {
+      Platform.TypeScriptUtilities.assertNever(metric, `Unexpected metric ${metric}`);
+    }
+
+    // NOTE: it is deliberate to use the same value for the title and
+    // aria-label; the aria-label is used to give more context to
+    // screen-readers, and the title is to aid users who may not know what
+    // the red/orange/green classification is, or those who are unable to
+    // easily distinguish the visual colour differences.
+    // clang-format off
+    const title = value !== null ?
+      i18nString(UIStrings.metricScore, {PH1: metric, PH2: valueText, PH3: classification}) :
+      i18nString(UIStrings.metricScoreUnavailable, {PH1: metric});
+
+    return html`
+      <button class="metric"
+        @click=${relevantEvent ? onClickMetric.bind(relevantEvent) : null}
+        title=${title}
+        aria-label=${title}
+      >
+        <div class="metric-value metric-value-${classification}">${valueDisplay}</div>
+      </button>
+    `;
+    // clang-format on
+  }
+
+  const lcpEl = renderMetricValue('LCP', local?.lcp?.value ?? null, local?.lcp?.event ?? null);
+  const inpEl = renderMetricValue('INP', local?.inp?.value ?? null, local?.inp?.event ?? null);
+  const clsEl = renderMetricValue('CLS', local?.cls?.value ?? null, local?.cls?.worstClusterEvent ?? null);
+
+  const localMetricsTemplateResult = html`
+    <div class="metrics-row">
+      <span>${lcpEl}</span>
+      <span>${inpEl}</span>
+      <span>${clsEl}</span>
+      <span class="row-label">Local</span>
+    </div>
+    <span class="row-border"></span>
+  `;
+
+  let fieldMetricsTemplateResult;
+  if (field) {
+    const {lcp, inp, cls} = field;
+
+    const lcpEl = renderMetricValue('LCP', lcp?.value ?? null, null);
+    const inpEl = renderMetricValue('INP', inp?.value ?? null, null);
+    const clsEl = renderMetricValue('CLS', cls?.value ?? null, null);
+
+    let scope = i18nString(UIStrings.originOption);
+    if (lcp?.pageScope === 'url' || inp?.pageScope === 'url') {
+      scope = i18nString(UIStrings.urlOption);
+    }
+
+    // clang-format off
+    fieldMetricsTemplateResult = html`
+      <div class="metrics-row">
+        <span>${lcpEl}</span>
+        <span>${inpEl}</span>
+        <span>${clsEl}</span>
+        <span class="row-label">${i18nString(UIStrings.fieldScoreLabel, {PH1: scope})}</span>
+      </div>
+      <span class="row-border"></span>
+    `;
+    // clang-format on
+  }
+
+  let fieldIsDifferentEl;
+  if (showFieldMismatchNotice) {
+    // clang-format off
+    fieldIsDifferentEl = html`
+      <div class="field-mismatch-notice" jslog=${VisualLogging.section('timeline.insights.field-mismatch')}>
+        <h3>${i18nString(UIStrings.fieldMismatchTitle)}</h3>
+        <devtools-button
+          title=${i18nString(UIStrings.dismissTitle)}
+          .iconName=${'cross'}
+          .variant=${Buttons.Button.Variant.ICON}
+          .jslogContext=${'timeline.insights.dismiss-field-mismatch'}
+          @click=${onDismisFieldMismatchNotice}
+        ></devtools-button>
+        <div class="field-mismatch-notice__body">${md(i18nString(UIStrings.fieldMismatchNotice))}</div>
+      </div>
+    `;
+    // clang-format on
+  }
+
+  const classes = {metrics: true, 'metrics--field': Boolean(fieldMetricsTemplateResult)};
+  const metricsTableEl = html`<div class=${Lit.Directives.classMap(classes)}>
+    <div class="metrics-row">
+      <span class="metric-label">LCP</span>
+      <span class="metric-label">INP</span>
+      <span class="metric-label">CLS</span>
+      <span class="row-label"></span>
+    </div>
+    ${localMetricsTemplateResult}
+    ${fieldMetricsTemplateResult}
+  </div>`;
+
+  Lit.render(
+      html`
+    <style>${cwvMetricsStyles}</style>
+    ${metricsTableEl}
+    ${fieldIsDifferentEl}
+  `,
+      target);
+};
+
+export interface CWVMetricsData {
+  insightSetKey: Trace.Types.Events.NavigationId|null;
+  parsedTrace: Trace.TraceModel.ParsedTrace|null;
+}
+
+export class CWVMetrics extends UI.Widget.Widget {
+  #view: MetricsView;
+  #data: CWVMetricsData = {
+    insightSetKey: null,
+    parsedTrace: null,
+  };
+
+  #didDismissFieldMismatchNotice = false;
+
+  constructor(element?: HTMLElement, view: MetricsView = CWV_METRICS_VIEW) {
+    super(element, {useShadowDom: true});
+    this.#view = view;
+  }
+
+  set data(data: CWVMetricsData) {
+    this.#data = data;
+    this.requestUpdate();
+  }
+
+  #onClickMetric(traceEvent: Trace.Types.Events.Event): void {
+    this.element.dispatchEvent(new Insights.EventRef.EventReferenceClick(traceEvent));
+  }
+
+  #onDismisFieldMismatchNotice(): void {
+    this.#didDismissFieldMismatchNotice = true;
+    this.requestUpdate();
+  }
+
+  override performUpdate(): void {
+    const {
+      parsedTrace,
+      insightSetKey,
+    } = this.#data;
+
+    if (!parsedTrace?.insights || !insightSetKey || !(parsedTrace.insights instanceof Map)) {
+      return;
+    }
+
+    const insightSet = parsedTrace.insights.get(insightSetKey);
+    if (!insightSet) {
+      return;
+    }
+
+    const input: MetricsViewInput = {
+      parsedTrace,
+      insightSetKey,
+      didDismissFieldMismatchNotice: this.#didDismissFieldMismatchNotice,
+      onDismisFieldMismatchNotice: this.#onDismisFieldMismatchNotice.bind(this),
+      onClickMetric: this.#onClickMetric.bind(this),
+    };
+    this.#view(input, undefined, this.contentElement);
+  }
+}

package/front_end/panels/timeline/components/Sidebar.ts

@@ -163,6 +163,14 @@ export class SidebarWidget extends UI.Widget.VBox {
     }
   }
 
+  openInsightsTab(): void {
+    this.#tabbedPane.selectTab(SidebarTabs.INSIGHTS);
+  }
+
+  setActiveInsightSet(insightSetKey: string): void {
+    this.#insightsView.setActiveInsightSet(insightSetKey);
+  }
+
   /**
    * True if the sidebar has been visible at least one time. This is persisted
    * to the user settings so it persists across sessions. This is used because
@@ -213,6 +221,15 @@ class InsightsView extends UI.Widget.VBox {
       });
     }
   }
+
+  setActiveInsightSet(insightSetKey: string): void {
+    const widget = this.#component.getWidget();
+    if (!widget) {
+      return;
+    }
+
+    widget.setActiveInsightSet(insightSetKey);
+  }
 }
 
 class AnnotationsView extends UI.Widget.VBox {

package/front_end/panels/timeline/components/SidebarInsightsTab.ts

@@ -200,6 +200,16 @@ export class SidebarInsightsTab extends UI.Widget.Widget {
     this.requestUpdate();
   }
 
+  setActiveInsightSet(insightSetKey: string): void {
+    if (this.#parsedTrace?.insights) {
+      const insightSet = this.#parsedTrace.insights.get(insightSetKey);
+      if (insightSet) {
+        this.#selectedInsightSet = insightSet;
+        this.requestUpdate();
+      }
+    }
+  }
+
   #onInsightSetToggled(insightSet: Trace.Insights.Types.InsightSet): void {
     this.#selectedInsightSet = this.#selectedInsightSet === insightSet ? null : insightSet;
     // Update the active insight set.