chrome-devtools-frontend 1.0.1025175 → 1.0.1026673

package/front_end/ui/components/docs/building-ui-documentation/CreatingComponents.md

@@ -78,9 +78,11 @@ Each component defines a `#render` method which is responsible for invoking LitH
 The `#render` method calls `LitHtml.render`, building up a template with `LitHtml.html`:
 
 ```ts
-LitHtml.render(LitHtml.html``, this.#shadow, {host: this});
+LitHtml.render(LitHtml.html`<p>hello world!</p>`, this.#shadow, {host: this});
 ```
 
+The third argument (`{host: this}`) tells LitHtml to automatically bind event listeners to the component. This can save you some painful debugging where event listeners do not have the right `this` reference; so we enforce the use of `{host: this}` via a custom ESLint rule.
+
 There is unfortunately a [clang-format bug](crbug.com/1079231) which makes its auto-formatting of LitHtml templates very unreadable, so we usually disable clang-format round the call:
 
 ```ts
@@ -110,3 +112,172 @@ void ComponentHelpers.ScheduledRender.scheduleRender(this, this.#boundRender);
 ```
 
 > `scheduleRender` returns a promise; we use the `void` keyword to instruct TypeScript that we are purposefully not using `await` to wait for the promise to resolve. When scheduling a render it's most common to "fire and forget".
+
+To summarise, most components start off life looking like:
+
+```ts
+export class ElementsBreadcrumbs extends HTMLElement {
+  static readonly litTagName = LitHtml.literal`devtools-chrome-link`;
+  readonly #shadow = this.attachShadow({mode: 'open'});
+  readonly #boundRender = this.#render.bind(this);
+
+  #render(): void {
+    LitHtml.render(LitHtml.html``, this.#shadow, {host:this});
+  }
+}
+```
+
+## Triggering a render
+
+One of the most important aspects to understand about our component system is that **rendering does not happen automatically**.
+
+To ensure we trigger a render once the component is added to the DOM, we can define [`connectedCallback`](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#:~:text=lifecycle.%20For%20example%2C-,connectedCallback,-is%20invoked%20each):
+
+```ts
+export class ElementsBreadcrumbs extends HTMLElement {
+  static readonly litTagName = LitHtml.literal`devtools-chrome-link`;
+  readonly #shadow = this.attachShadow({mode: 'open'});
+  readonly #boundRender = this.#render.bind(this);
+
+  connectedCallback(): void {
+    void ComponentHelpers.ScheduledRender.scheduleRender(this, this.#boundRender);
+  }
+
+  #render(): void {
+    LitHtml.render(LitHtml.html``, this.#shadow, {host:this});
+  }
+}
+```
+
+## Passing data into a component
+
+Most of our components will require data that is passed into them. For example, `ElementsBreadcrumbs` takes in an array of `DOMNode` objects.
+
+To provide a component some data, we define a `data` setter. This setter takes an object with any data the component requires. This object should have a TypeScript interface defined for it:
+
+```ts
+export interface ElementsBreadcrumbsData {
+  selectedNode: DOMNode|null;
+  crumbs: DOMNode[];
+}
+
+export class ElementsBreadcrumbs extends HTMLElement {
+  // ...
+  #crumbs: DOMNode[] = [];
+  #selectedNode: DOMNode|null = null;
+
+  set data(data: ElementsBreadcrumbsData) {
+    this.#crumbs = data.crumbs;
+    this.#selectedNode = data.selectedNode;
+    void ComponentHelpers.ScheduledRender.scheduleRender(this, this.#boundRender);
+  }
+}
+```
+
+## Rendering components
+
+Now we know how to create components that can take data, let's render them!
+
+### From a DevTools Widget
+
+If you are rendering a component from the DevTools widget system, you should instantiate the component, pass any `data` to it, and then append it into the DOM:
+
+```ts
+// Within a Widget
+const breadcrumbs = new ElementsBreadcrumbs();
+breadcrumbs.data = {selectedNode: node, crumbs: [...]};
+this.appendChild(breadcrumbs);
+```
+
+### From another component
+
+If you are rendering a component from within another component, render it within the call to `LitHtml.html` and use the static `litTagName` property:
+
+```ts
+// Within some component
+LitHtml.render(LitHtml.html`
+  <${ElementsBreadcrumbs.litTagName}></${ElementsBreadcrumbs>
+`, this.#shadow, {host: this});
+```
+
+To pass data, we use [LitHtml's dot syntax](https://lit.dev/docs/templates/expressions/#property-expressions) to set the `data` property (and invoke our `set data` setter):
+
+```ts
+// Within some component
+LitHtml.render(LitHtml.html`
+  <${ElementsBreadcrumbs.litTagName} .data=${{
+    selectedNode: node,
+    crumbs: [...],
+  }}>
+  </${ElementsBreadcrumbs>
+`, this.#shadow, {host: this});
+```
+
+To enforce some type safety, we also use TypeScript's `as` keyword to force the compiler to type-check the `data` object against the interface:
+
+```ts
+// Within some component
+LitHtml.render(LitHtml.html`
+  <${ElementsBreadcrumbs.litTagName} .data=${{
+    selectedNode: node,
+    crumbs: [...],
+  } as ElementsBreadcrumbsData}>
+  </${ElementsBreadcrumbs>
+`, this.#shadow, {host: this});
+```
+
+This type-checking requirement is enforced by an ESLint rule.
+
+## Performance concerns with data passing
+
+The approach of `set data(data)` was chosen because:
+
+1. It requires few lines of code.
+2. It provides some form of type safety via the `as FooData` check.
+3. At the time we didn't have a solution for scheduled and batched renders, and didn't want multiple setters to trigger multiple unnecessary renders.
+
+However, using `set data(data)` does come with some negative performance costs:
+
+1. LitHtml will always think the value has changed, because it's an object. If a component renders twice with `.data=${{name: 'Jack'}}`, Lit will think that the value has changed because it's a new object, even though we can see it's holding the same data.
+2. This approach causes these objects to be created (and subsequently garbage collected) on/after each render.
+
+For most components in DevTools, these trade-offs are acceptable, and we prefer the type-safety of `set data` and take the usually imperceivable performance hit. However, in rare circumstances, this performance hit is noticeable. A good example of this is in Performance Insights, where we have to constantly re-render components as the user scrolls through their performance timeline. We noticed that this caused a large amount of garbage collection from all the objects being created per-render and then immediately disposed.
+
+For these situations, we can instead move to an approach where we set properties individually. We still define the interface as before, and then define an individual setter for each property:
+
+```ts
+interface ElementsBreadcrumbsData {
+  selectedNode: DOMNode|null;
+  crumbs: DOMNode[];
+}
+
+class ElementsBreadcrumbs extends HTMLElement {
+  #crumbs: DOMNode[] = [];
+  #selectedNode: DOMNode|null = null;
+
+  set crumbs(crumbs: ElementsBreadcrumbsData['crumbs']) {
+    this.#crumbs = crumbs;
+    void ComponentHelpers.ScheduledRender.scheduleRender(this, this.#boundRender);
+  }
+
+  set selectedNode(selectedNode: ElementsBreadcrumbsData['selectedNode']) {
+    this.#selectedNode = selectedNode;
+    void ComponentHelpers.ScheduledRender.scheduleRender(this, this.#boundRender);
+  }
+}
+```
+
+Rendering this component within another Lit component would now be done like so:
+
+```ts
+// Within some component
+LitHtml.render(LitHtml.html`
+  <${ElementsBreadcrumbs.litTagName} .crumbs=${[...]} .selectedNode=${node}>
+  </${ElementsBreadcrumbs>
+`, this.#shadow, {host: this});
+```
+
+This solution is more performant, but less type-safe as TypeScript has no means of checking those values. This is something we may rectify using the `as` pattern, but for now it's preferred to use the `set data` method by default.
+
+
+

package/front_end/ui/components/text_editor/TextEditor.ts

@@ -105,6 +105,9 @@ export class TextEditor extends HTMLElement {
   connectedCallback(): void {
     if (!this.#activeEditor) {
       this.#createEditor();
+    } else {
+      this.#activeEditor.scrollDOM.scrollTop = this.#lastScrollPos.top;
+      this.#activeEditor.scrollDOM.scrollLeft = this.#lastScrollPos.left;
     }
   }
 

package/front_end/ui/legacy/components/data_grid/dataGrid.css

@@ -25,7 +25,8 @@
   bottom: 0;
   left: 0;
   right: 0;
-  overflow: scroll;
+  overflow-x: hidden;
+  overflow-y: overlay;
   transform: translateZ(0);
   background-color: var(--color-background);
 }

package/front_end/ui/legacy/components/object_ui/ObjectPropertiesSection.ts

@@ -1124,7 +1124,7 @@ export class ObjectPropertyTreeElement extends UI.TreeOutline.TreeElement {
     if (this.property.webIdl?.applicable) {
       const icon = new IconButton.Icon.Icon();
       icon.data = {
-        iconName: 'elements_panel_icon',
+        iconName: 'star_outline',
         color: 'var(--color-text-secondary)',
         width: '16px',
         height: '16px',
@@ -1140,7 +1140,8 @@ export class ObjectPropertyTreeElement extends UI.TreeOutline.TreeElement {
       `;
     } else {
       container = UI.Fragment.html`
-        <span class='name-and-value'>${adorner}${this.nameElement}: ${this.valueElement}</span>
+        <span class='name-and-value'>${adorner}${this.nameElement}<span class='separator'>: </span>${
+          this.valueElement}</span>
       `;
     }
 

package/front_end/ui/legacy/components/object_ui/objectPropertiesSection.css

@@ -74,7 +74,12 @@
   overflow: hidden;
   line-height: 16px;
   display: flex;
-  white-space: break-spaces;
+  white-space: nowrap;
+}
+
+.name-and-value .separator {
+  white-space: pre;
+  flex-shrink: 0;
 }
 
 .editing-sub-part .name-and-value {

package/front_end/ui/legacy/components/utils/JSPresentationUtils.ts

@@ -70,7 +70,7 @@ function populateContextMenu(link: Element, event: Event): void {
   const uiLocation = Linkifier.uiLocation(link);
   if (uiLocation &&
       Bindings.IgnoreListManager.IgnoreListManager.instance().canIgnoreListUISourceCode(uiLocation.uiSourceCode)) {
-    if (Bindings.IgnoreListManager.IgnoreListManager.instance().isIgnoreListedUISourceCode(uiLocation.uiSourceCode)) {
+    if (Bindings.IgnoreListManager.IgnoreListManager.instance().isUserIgnoreListedURL(uiLocation.uiSourceCode.url())) {
       contextMenu.debugSection().appendItem(
           i18nString(UIStrings.removeFromIgnore),
           () => Bindings.IgnoreListManager.IgnoreListManager.instance().unIgnoreListUISourceCode(
@@ -127,8 +127,8 @@ export function buildStackTraceRows(
         // TODO(crbug.com/1183325): fix race condition with uiLocation still being null here
         const uiLocation = Linkifier.uiLocation(link);
         if (uiLocation &&
-            Bindings.IgnoreListManager.IgnoreListManager.instance().isIgnoreListedUISourceCode(
-                uiLocation.uiSourceCode)) {
+            Bindings.IgnoreListManager.IgnoreListManager.instance().isUserIgnoreListedURL(
+                uiLocation.uiSourceCode.url())) {
           ignoreListHide = true;
         }
         // Linkifier is using a workaround with the 'zero width space' (\u200b).
@@ -175,7 +175,8 @@ function updateHiddenRows(
     if ('link' in row && row.link) {
       const uiLocation = Linkifier.uiLocation(row.link);
       if (uiLocation &&
-          Bindings.IgnoreListManager.IgnoreListManager.instance().isIgnoreListedUISourceCode(uiLocation.uiSourceCode)) {
+          Bindings.IgnoreListManager.IgnoreListManager.instance().isUserIgnoreListedURL(
+              uiLocation.uiSourceCode.url())) {
         row.ignoreListHide = true;
       }
       if (row.rowCountHide || row.ignoreListHide) {

package/package.json

@@ -55,5 +55,5 @@
     "unittest": "scripts/test/run_unittests.py --no-text-coverage",
     "watch": "vpython third_party/node/node.py --output scripts/watch_build.js"
   },
-  "version": "1.0.1025175"
+  "version": "1.0.1026673"
 }