chrome-devtools-frontend 1.0.1515796 → 1.0.1515988

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

@@ -38,6 +38,10 @@ const UIStrings = {
    * @description Text for the include annotations option.
    */
   includeAnnotations: 'Include annotations',
+  /**
+   * @description Text for the compression option.
+   */
+  shouldCompress: 'Compress with gzip',
   /**
    * @description Text for the save trace button
    */
@@ -52,6 +56,7 @@ export interface ExportTraceOptionsData {
     includeScriptContent: boolean,
     includeSourceMaps: boolean,
     addModifications: boolean,
+    shouldCompress: boolean,
   }) => Promise<void>;
   buttonEnabled: boolean;
 }
@@ -63,6 +68,7 @@ export interface ExportTraceOptionsState {
   includeAnnotations: boolean;
   includeScriptContent: boolean;
   includeSourceMaps: boolean;
+  shouldCompress: boolean;
   displayAnnotationsCheckbox?: boolean;
   displayScriptContentCheckbox?: boolean;
   displaySourceMapsCheckbox?: boolean;
@@ -72,22 +78,26 @@ export class ExportTraceOptions extends HTMLElement {
   readonly #shadow = this.attachShadow({mode: 'open'});
   #data: ExportTraceOptionsData|null = null;
 
-  readonly #includeAnnotationsSettingString: string = 'export-performance-trace-include-annotations';
-  readonly #includeScriptContentSettingString: string = 'export-performance-trace-include-scripts';
-  readonly #includeSourceMapsSettingString: string = 'export-performance-trace-include-sourcemaps';
+  static readonly #includeAnnotationsSettingString: string = 'export-performance-trace-include-annotations';
+  static readonly #includeScriptContentSettingString: string = 'export-performance-trace-include-scripts';
+  static readonly #includeSourceMapsSettingString: string = 'export-performance-trace-include-sourcemaps';
+  static readonly #shouldCompressSettingString: string = 'export-performance-trace-should-compress';
 
   #includeAnnotationsSetting: Common.Settings.Setting<boolean> = Common.Settings.Settings.instance().createSetting(
-      this.#includeAnnotationsSettingString, true, Common.Settings.SettingStorageType.SESSION);
+      ExportTraceOptions.#includeAnnotationsSettingString, true, Common.Settings.SettingStorageType.SESSION);
   #includeScriptContentSetting: Common.Settings.Setting<boolean> = Common.Settings.Settings.instance().createSetting(
-      this.#includeScriptContentSettingString, false, Common.Settings.SettingStorageType.SESSION);
+      ExportTraceOptions.#includeScriptContentSettingString, false, Common.Settings.SettingStorageType.SESSION);
   #includeSourceMapsSetting: Common.Settings.Setting<boolean> = Common.Settings.Settings.instance().createSetting(
-      this.#includeSourceMapsSettingString, false, Common.Settings.SettingStorageType.SESSION);
+      ExportTraceOptions.#includeSourceMapsSettingString, false, Common.Settings.SettingStorageType.SESSION);
+  #shouldCompressSetting: Common.Settings.Setting<boolean> = Common.Settings.Settings.instance().createSetting(
+      ExportTraceOptions.#shouldCompressSettingString, true, Common.Settings.SettingStorageType.SYNCED);
 
   #state: ExportTraceOptionsState = {
     dialogState: Dialogs.Dialog.DialogState.COLLAPSED,
     includeAnnotations: this.#includeAnnotationsSetting.get(),
     includeScriptContent: this.#includeScriptContentSetting.get(),
     includeSourceMaps: this.#includeSourceMapsSetting.get(),
+    shouldCompress: this.#shouldCompressSetting.get(),
   };
 
   #includeAnnotationsCheckbox = UI.UIUtils.CheckboxLabel.create(
@@ -102,6 +112,10 @@ export class ExportTraceOptions extends HTMLElement {
       /* title*/ i18nString(UIStrings.includeSourcemap), /* checked*/ this.#state.includeSourceMaps,
       /* subtitle*/ undefined,
       /* jslogContext*/ 'timeline.export-trace-options.source-maps-checkbox');
+  #shouldCompressCheckbox = UI.UIUtils.CheckboxLabel.create(
+      /* title*/ i18nString(UIStrings.shouldCompress), /* checked*/ this.#state.shouldCompress,
+      /* subtitle*/ undefined,
+      /* jslogContext*/ 'timeline.export-trace-options.should-compress-checkbox');
 
   set data(data: ExportTraceOptionsData) {
     this.#data = data;
@@ -113,18 +127,23 @@ export class ExportTraceOptions extends HTMLElement {
     this.#includeAnnotationsSetting.set(state.includeAnnotations);
     this.#includeScriptContentSetting.set(state.includeScriptContent);
     this.#includeSourceMapsSetting.set(state.includeSourceMaps);
+    this.#shouldCompressSetting.set(state.shouldCompress);
 
     this.#scheduleRender();
   }
 
-  updateContentVisibility(annotationsExist: boolean): void {
+  get state(): Readonly<ExportTraceOptionsState> {
+    return this.#state;
+  }
+
+  updateContentVisibility(options: {annotationsExist: boolean}): void {
     const showIncludeScriptContentCheckbox =
         Root.Runtime.experiments.isEnabled(Root.Runtime.ExperimentName.TIMELINE_ENHANCED_TRACES);
     const showIncludeSourceMapCheckbox =
         Root.Runtime.experiments.isEnabled(Root.Runtime.ExperimentName.TIMELINE_COMPILED_SOURCES);
 
     const newState = Object.assign({}, this.#state, {
-      displayAnnotationsCheckbox: annotationsExist,
+      displayAnnotationsCheckbox: options.annotationsExist,
       displayScriptContentCheckbox: showIncludeScriptContentCheckbox,
       displaySourceMapsCheckbox: showIncludeSourceMapCheckbox
     });
@@ -158,6 +177,10 @@ export class ExportTraceOptions extends HTMLElement {
         newState.includeSourceMaps = checked;
         break;
       }
+      case this.#shouldCompressCheckbox: {
+        newState.shouldCompress = checked;
+        break;
+      }
     }
 
     this.state = newState;
@@ -189,10 +212,6 @@ export class ExportTraceOptions extends HTMLElement {
       throw new Error('Export trace options dialog render was not scheduled');
     }
 
-    const emptyDialog =
-        !(this.#state.displayAnnotationsCheckbox || this.#state.displayScriptContentCheckbox ||
-          this.#state.displaySourceMapsCheckbox);
-
     // clang-format off
     const output = html`
       <style>${exportTraceOptionsStyles}</style>
@@ -208,7 +227,7 @@ export class ExportTraceOptions extends HTMLElement {
           horizontalAlignment: Dialogs.Dialog.DialogHorizontalAlignment.AUTO,
           closeButton: false,
           dialogTitle: i18nString(UIStrings.exportTraceOptionsDialogTitle),
-          state: emptyDialog ? Dialogs.Dialog.DialogState.DISABLED : this.#state.dialogState,
+          state: this.#state.dialogState,
         } as Dialogs.ButtonDialog.ButtonDialogData}>
         <div class='export-trace-options-content'>
           ${this.#state.displayAnnotationsCheckbox ? this.#renderCheckbox(this.#includeAnnotationsCheckbox,
@@ -218,6 +237,7 @@ export class ExportTraceOptions extends HTMLElement {
             i18nString(UIStrings.includeScriptContent), this.#state.includeScriptContent): ''}
           ${this.#state.displayScriptContentCheckbox && this.#state.displaySourceMapsCheckbox ? this.#renderCheckbox(
             this.#includeSourceMapsCheckbox, i18nString(UIStrings.includeSourcemap), this.#state.includeSourceMaps): ''}
+          ${this.#renderCheckbox(this.#shouldCompressCheckbox, i18nString(UIStrings.shouldCompress), this.#state.shouldCompress)}
           <div class='export-trace-options-row'><div class='export-trace-blank'></div><devtools-button
                   class="setup-button"
                   @click=${this.#onExportClick.bind(this)}
@@ -235,14 +255,7 @@ export class ExportTraceOptions extends HTMLElement {
   }
 
   async #onButtonDialogClick(): Promise<void> {
-    // Handles button dialog click. Either expands dialog with options or
-    // directly exports if no options available.
-    if (!(this.#state.displayAnnotationsCheckbox || this.#state.displayScriptContentCheckbox ||
-          this.#state.displaySourceMapsCheckbox)) {
-      void this.#onExportCallback();
-    } else {
-      this.state = Object.assign({}, this.#state, {dialogState: Dialogs.Dialog.DialogState.EXPANDED});
-    }
+    this.state = Object.assign({}, this.#state, {dialogState: Dialogs.Dialog.DialogState.EXPANDED});
   }
 
   async #onExportCallback(): Promise<void> {
@@ -250,7 +263,9 @@ export class ExportTraceOptions extends HTMLElement {
     await this.#data?.onExport({
       includeScriptContent: this.#state.includeScriptContent,
       includeSourceMaps: this.#state.includeSourceMaps,
-      addModifications: this.#state.includeAnnotations
+      // Note: this also includes track configuration ...
+      addModifications: this.#state.includeAnnotations,
+      shouldCompress: this.#state.shouldCompress,
     });
 
     Host.userMetrics.actionTaken(Host.UserMetrics.Action.PerfPanelTraceExported);

package/front_end/panels/timeline/components/insights/BaseInsightComponent.ts

@@ -175,20 +175,24 @@ export abstract class BaseInsightComponent<T extends InsightModel> extends HTMLE
   }
 
   #dispatchInsightToggle(): void {
+    if (!this.data.insightSetKey || !this.model) {
+      // Shouldn't happen, but needed to satisfy TS.
+      return;
+    }
+
+    const focus = UI.Context.Context.instance().flavor(AIAssistance.AgentFocus);
     if (this.#selected) {
       this.dispatchEvent(new SidebarInsight.InsightDeactivated());
 
       // Clear agent (but only if currently focused on an insight).
-      const focus = UI.Context.Context.instance().flavor(AIAssistance.AgentFocus);
-      if (focus && focus.data.type === 'insight') {
-        UI.Context.Context.instance().setFlavor(AIAssistance.AgentFocus, null);
+      if (focus) {
+        UI.Context.Context.instance().setFlavor(AIAssistance.AgentFocus, focus.withInsight(null));
       }
       return;
     }
 
-    if (!this.data.insightSetKey || !this.model) {
-      // Shouldn't happen, but needed to satisfy TS.
-      return;
+    if (focus) {
+      UI.Context.Context.instance().setFlavor(AIAssistance.AgentFocus, focus.withInsight(this.model));
     }
 
     this.sharedTableState.selectedRowEl?.classList.remove('selected');
@@ -359,7 +363,13 @@ export abstract class BaseInsightComponent<T extends InsightModel> extends HTMLE
       return;
     }
 
-    UI.Context.Context.instance().setFlavor(AIAssistance.AgentFocus, this.#agentFocus);
+    let focus = UI.Context.Context.instance().flavor(AIAssistance.AgentFocus);
+    if (focus) {
+      focus = focus.withInsight(this.model);
+    } else {
+      focus = this.#agentFocus;
+    }
+    UI.Context.Context.instance().setFlavor(AIAssistance.AgentFocus, focus);
 
     // Trigger the AI Assistance panel to open.
     const action = UI.ActionRegistry.ActionRegistry.instance().getAction(actionId);

package/front_end/third_party/axe-core/README.chromium

@@ -4,6 +4,7 @@ URL: https://github.com/dequelabs/axe-core/
 Version: N/A
 Date: 2017-07-24
 Revision: d02dba3223fefe525438330e40b5da5de81eeeb5
+Update Mechanism: Manual
 License: MPL-2.0
 License File: LICENSE
 Security Critical: no

package/front_end/third_party/codemirror/README.chromium

@@ -3,6 +3,7 @@ Short Name: CodeMirror
 URL: https://github.com/codemirror/CodeMirror/
 Version: 5.61.0
 Revision: eac70bb1a31a08201e5705c788cd72e6283958f0
+Update Mechanism: Manual
 License: MIT
 License File: package/LICENSE
 Security Critical: no

package/front_end/third_party/codemirror.next/README.chromium

@@ -2,6 +2,7 @@ Name: CodeMirror 6
 Short Name: CodeMirror.next
 URL: https://github.com/codemirror/CodeMirror.next/
 Version: 0.19.0
+Update Mechanism: Manual
 License: MIT
 License File: LICENSE
 Security Critical: no

package/front_end/third_party/csp_evaluator/README.chromium

@@ -2,6 +2,7 @@ Name: CSP Evaluator Core Library, a tool that allows developers to check if a Co
 Short Name: csp_evaluator
 URL: https://www.npmjs.com/package/csp_evaluator
 Version: 1.1.1
+Update Mechanism: Manual
 License: Apache-2.0
 License File: package/LICENSE
 Security Critical: no

package/front_end/third_party/diff/README.chromium

@@ -3,6 +3,7 @@ Short Name: diff-match-patch
 URL: https://github.com/google/diff-match-patch/tree/master/javascript
 Version: 5.60.0
 Revision: 0ae308daa77aeddb089cd6b7b0a443fca026266e
+Update Mechanism: Manual
 License: Apache-2.0
 License File: LICENSE
 Security Critical: no

package/front_end/third_party/i18n/README.chromium

@@ -3,6 +3,7 @@ Short Name: i18n
 URL: https://github.com/GoogleChrome/lighthouse
 Version: 15dad3944c2754a9e147fef9ef99934169e2ca08
 Revision: 15dad3944c2754a9e147fef9ef99934169e2ca08
+Update Mechanism: Manual
 License: Apache-2.0
 License File: LICENSE
 Security Critical: no

package/front_end/third_party/intl-messageformat/README.chromium

@@ -3,6 +3,7 @@ Short Name: intl-messageformat
 URL: https://github.com/formatjs/formatjs
 Version: 9.8.0
 Revision: 51a665ca0a7c6129c0c93b6b7837603a8e31caa4
+Update Mechanism: Manual
 License: BSD-3-Clause
 License File: LICENSE
 Security Critical: no

package/front_end/third_party/json5/README.chromium

@@ -3,6 +3,7 @@ Short Name: json5
 URL: https://github.com/json5/json5
 Version: 2.2.3
 Revision: de344f0
+Update Mechanism: Manual
 License: MIT
 License File: LICENSE
 Shipped: yes

package/front_end/third_party/legacy-javascript/README.chromium

@@ -3,6 +3,7 @@ Short Name: legacy-javascript
 URL: https://github.com/GoogleChrome/lighthouse/tree/main/core/lib/legacy-javascript
 Version: 0.0.1
 Revision: 410adb1220ca0d36c317f64cdbc652b798561413
+Update Mechanism: Manual
 License: Apache-2.0
 License File: LICENSE
 Security Critical: no

package/front_end/third_party/lighthouse/README.chromium

@@ -2,6 +2,7 @@ Name: Lighthouse
 Short Name: lighthouse
 Version: 12.8.2
 Revision: 8dc40bb0e13a71b1c58aaf891810ac9360b86ac9
+Update Mechanism: Manual
 URL: https://github.com/GoogleChrome/lighthouse
 License: Apache-2.0
 License File: LICENSE

package/front_end/third_party/lit/README.chromium

@@ -3,6 +3,7 @@ Short Name: lit
 URL: https://github.com/lit/lit
 Version: 2.4.1
 Revision: 02c28397c612845ffab9e22af08eecc869f8ce47
+Update Mechanism: Manual
 License: BSD-3-Clause
 License File: LICENSE
 Security Critical: no

package/front_end/third_party/marked/README.chromium

@@ -3,6 +3,7 @@ Short Name: marked
 URL: https://github.com/markedjs/marked
 Version: 13.0.1
 Revision: aaee616d54e82295d61a61aa26192416c2547ac4
+Update Mechanism: Manual
 License: BSD-3-Clause, MIT
 License File: LICENSE
 Security Critical: no

package/front_end/third_party/puppeteer-replay/README.chromium

@@ -5,6 +5,7 @@ Version: 3.1.3
 License: Apache-2.0
 License File: package/LICENSE
 Revision: 8be2fd240bbe6da6fbf031164b24f5057350f175
+Update Mechanism: Manual
 Security Critical: no
 Shipped: yes
 

package/front_end/third_party/third-party-web/README.chromium

@@ -3,6 +3,7 @@ Short Name: third-party-web
 URL: https://github.com/patrickhulce/third-party-web
 Version: 0.26.2
 Revision: d60863a2ea913ed26ae0446296a0cb1cc6c71291
+Update Mechanism: Manual
 License: MIT
 License File: LICENSE
 Security Critical: no

package/front_end/third_party/vscode.web-custom-data/README.chromium

@@ -5,6 +5,7 @@ Version: 0.5.2
 License: MIT
 License File: package/LICENSE.md
 Revision: 79f0e53d9ade00eb00eda53016edb637a809ec1f
+Update Mechanism: Manual
 Security Critical: no
 Shipped: yes
 

package/front_end/third_party/wasmparser/README.chromium

@@ -3,6 +3,7 @@ Short Name: wasmparser
 URL: https://github.com/wasdk/wasmparser
 Version: 5.4.0
 Revision: e0a3281fdd678e6e3d5624b6d939bdf7c3d215ad
+Update Mechanism: Manual
 License: Apache-2.0
 License File: package/LICENSE
 Security Critical: no

package/front_end/third_party/web-vitals/README.chromium

@@ -5,6 +5,7 @@ Version: 4.2.4
 License: Apache-2.0
 License File: package/LICENSE
 Revision: 3d2b3dc8576cc003618952fa39902fab764a53e2
+Update Mechanism: Manual
 Security Critical: no
 Shipped: yes
 

package/front_end/ui/components/tooltips/Tooltip.ts

@@ -162,12 +162,14 @@ export interface TooltipProperties {
  * @property variant - reflects the `"variant"` attribute.
  * @property padding - reflects the `"padding"` attribute.
  * @property useClick - reflects the `"click"` attribute.
+ * @property verticalDistanceIncrease - reflexts the `"vertical-distance-increase"` attribute.
  * @attribute id - Id of the tooltip. Used for searching an anchor element with aria-describedby.
  * @attribute hover-delay - Hover length in ms before the tooltip is shown and hidden.
  * @attribute variant - Variant of the tooltip, `"simple"` for strings only, inverted background,
  *                 `"rich"` for interactive content, background according to theme's surface.
  * @attribute padding - Which padding to use, defaults to `"small"`. Use `"large"` for richer content.
  * @attribute use-click - If present, the tooltip will be shown on click instead of on hover.
+ * @attribute vertical-distance-increase - The tooltip is moved vertically this many pixels further away from its anchor.
  * @attribute use-hotkey - If present, the tooltip will be shown on hover but not when receiving focus.
  *                    Requires a hotkey to open when fosed (Alt-down). When `"use-click"` is present
  *                    as well, use-click takes precedence.
@@ -244,6 +246,14 @@ export class Tooltip extends HTMLElement {
     this.#updateJslog();
   }
 
+  get verticalDistanceIncrease(): number {
+    return this.hasAttribute('vertical-distance-increase') ? Number(this.getAttribute('vertical-distance-increase')) :
+                                                             0;
+  }
+  set verticalDistanceIncrease(increase: number) {
+    this.setAttribute('vertical-distance-increase', increase.toString());
+  }
+
   get anchor(): HTMLElement|null {
     return this.#anchor;
   }
@@ -387,7 +397,13 @@ export class Tooltip extends HTMLElement {
         proposedRectForRichTooltip({inspectorViewRect, anchorRect, currentPopoverRect}) :
         proposedRectForSimpleTooltip({inspectorViewRect, anchorRect, currentPopoverRect});
     this.style.left = `${proposedPopoverRect.left}px`;
-    this.style.top = `${proposedPopoverRect.top}px`;
+
+    // If the tooltip is above its anchor, we need to decrease the tooltip's
+    // y-coordinate to increase the distance between tooltip and anchor.
+    // If the tooltip is below its anchor, we add to the tooltip's y-coord.
+    const actualVerticalOffset =
+        anchorRect.top < proposedPopoverRect.top ? this.verticalDistanceIncrease : -this.verticalDistanceIncrease;
+    this.style.top = `${proposedPopoverRect.top + actualVerticalOffset}px`;
     this.style.visibility = 'visible';
     requestAnimationFrame(this.#positionPopover);
   };

package/front_end/ui/legacy/ContextMenu.ts

@@ -743,7 +743,7 @@ export class ContextMenu extends SubMenu {
 
     this.pendingTargets = [];
 
-    this.innerShow();
+    this.#show();
   }
 
   /**
@@ -780,7 +780,7 @@ export class ContextMenu extends SubMenu {
     }
   }
 
-  private innerShow(): void {
+  #show(): void {
     if (!this.eventTarget) {
       return;
     }

package/front_end/ui/legacy/GlassPane.ts

@@ -28,6 +28,7 @@ export class GlassPane {
   constructor(jslog?: string) {
     this.#widget = new Widget({jslog, useShadowDom: true});
     this.#widget.markAsRoot();
+    this.#widget.onDetach = this.#onDetach.bind(this);
     this.element = this.#widget.element;
     this.contentElement = this.#widget.contentElement;
 
@@ -124,15 +125,18 @@ export class GlassPane {
     if (!this.isShowing()) {
       return;
     }
-    panes.delete(this);
-    this.element.ownerDocument.body.removeEventListener('mousedown', this.onMouseDownBound, true);
-    this.element.ownerDocument.body.removeEventListener('pointerdown', this.onMouseDownBound, true);
     this.#widget.detach();
     if (this.#onHideCallback) {
       this.#onHideCallback();
     }
   }
 
+  #onDetach(): void {
+    panes.delete(this);
+    this.element.ownerDocument.body.removeEventListener('mousedown', this.onMouseDownBound, true);
+    this.element.ownerDocument.body.removeEventListener('pointerdown', this.onMouseDownBound, true);
+  }
+
   private onMouseDown(event: Event): void {
     if (!this.onClickOutsideCallback) {
       return;

package/front_end/ui/legacy/ProgressIndicator.ts

@@ -33,44 +33,57 @@ export class ProgressIndicator extends HTMLElement implements Common.Progress.Pr
     // using the 'no-stop-button' attribute on the element.
     if (!this.hasAttribute('no-stop-button')) {
       this.#stopButton = this.#contentElement.createChild('button', 'progress-indicator-shadow-stop-button');
-      this.#stopButton.addEventListener('click', this.cancel.bind(this));
+      this.#stopButton.addEventListener('click', () => {
+        this.canceled = true;
+      });
     }
   }
 
-  done(): void {
-    if (this.#isDone) {
+  set done(done: boolean) {
+    if (this.#isDone === done) {
       return;
     }
-    this.#isDone = true;
-    this.remove();
+    this.#isDone = done;
+    if (done) {
+      this.remove();
+    }
+  }
+
+  get done(): boolean {
+    return this.#isDone;
   }
 
-  cancel(): void {
-    this.#isCanceled = true;
+  set canceled(value: boolean) {
+    this.#isCanceled = value;
   }
 
-  isCanceled(): boolean {
+  get canceled(): boolean {
     return this.#isCanceled;
   }
 
-  setTitle(title: string): void {
+  override set title(title: string) {
     this.#labelElement.textContent = title;
   }
 
-  setTotalWork(totalWork: number): void {
+  override get title(): string {
+    return this.#labelElement.textContent ?? '';
+  }
+
+  set totalWork(totalWork: number) {
     this.#progressElement.max = totalWork;
   }
 
-  setWorked(worked: number, title?: string): void {
+  get totalWork(): number {
+    return this.#progressElement.max;
+  }
+
+  set worked(worked: number) {
     this.#worked = worked;
     this.#progressElement.value = worked;
-    if (title) {
-      this.setTitle(title);
-    }
   }
 
-  incrementWorked(worked?: number): void {
-    this.setWorked(this.#worked + (worked || 1));
+  get worked(): number {
+    return this.#worked;
   }
 }
 

package/front_end/ui/legacy/TabbedPane.ts

@@ -242,7 +242,7 @@ export class TabbedPane extends Common.ObjectWrapper.eventMixin<EventTypes, type
 
     const focused = this.hasFocus();
     for (let i = 0; i < ids.length; ++i) {
-      this.innerCloseTab(ids[i], userGesture);
+      this.#closeTab(ids[i], userGesture);
     }
     this.requestUpdate();
     if (this.tabsHistory.length) {
@@ -253,7 +253,7 @@ export class TabbedPane extends Common.ObjectWrapper.eventMixin<EventTypes, type
     }
   }
 
-  private innerCloseTab(id: string, userGesture?: boolean): true|undefined {
+  #closeTab(id: string, userGesture?: boolean): true|undefined {
     const tab = this.tabsById.get(id);
     if (!tab) {
       return;

package/front_end/ui/legacy/Treeoutline.ts

@@ -1618,8 +1618,8 @@ function getTreeNodes(nodeList: NodeList|Node[]): HTMLLIElement[] {
 
 /**
  * A tree element that can be used as progressive enhancement over a <ul> element. A `template` IDL attribute allows
- * additionally to insert the <ul> into a <template>, avoiding rendering anything into light DOM. The <ul> itself will
- * be cloned into shadow DOM and rendered there.
+ * additionally to insert the <ul> into a <template>, avoiding rendering anything into light DOM, which is recommended.
+ * The <ul> itself will be cloned into shadow DOM and rendered there.
  *
  * ## Usage ##
  *
@@ -1663,12 +1663,17 @@ function getTreeNodes(nodeList: NodeList|Node[]): HTMLLIElement[] {
  *
  * ## Event Handling ##
  *
+ * This section is only relevant if NOT using the `template`.
+ *
  * Since config elements are cloned into the shadow DOM, it's not possible to directly attach event listeners to the
- * children of config elements. Instead, the `HTMLElementWithLightDOMTemplate.on` directive should be used as a wrapper:
+ * children of config elements. Instead, the `UI.UIUtils.InterceptBindingDirective` directive needs to be used as a
+ * wrapper:
  * ```
- * <li role="treeitem">
+ * const on = Lit.Directive.directive(UI.UIUtils.InterceptBindingDirective);
+ *
+ * html`<li role="treeitem">
  *   <button @click=${on(clickHandler)}>click me</button>
- * </li>
+ * </li>`
  * ```
  *
  * @property template Define the tree contents