chrome-devtools-frontend 1.0.1545096 → 1.0.1547147

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

@@ -1,242 +0,0 @@
-# Creating components
-
-A component is created by extending `HTMLElement`. The name of the component should match the filename. The component should be exported by the file.
-
-```ts
-// ElementBreadcrumbs.ts
-export class ElementBreadcrumbs extends HTMLElement {
-}
-```
-
-## Where to put components
-
-If the component is for a specific panel, and not expected to be re-usable, it should be created within the panel's folder, within a sub-directory of `components`:
-
-```
-front_end/panels/elements/components/ElementsBreadcrumbs.ts
-```
-
-If a component is designed to be re-usable, it should live in `front_end/ui/components`, in its own folder. That folder also contains an entrypoint, along with files for the component's definition.
-
-```
-front_end/ui/components/button/button.ts // entrypoint
-front_end/ui/components/button/Button.ts // component definition
-```
-
-## Defining and naming a component
-
-All custom elements **must** contain a hyphen. Use `devtools-` as the prefix.  Use `customElements.define` to define the component and register it with the browser:
-
-```ts
-customElements.define('devtools-elements-breadcrumbs', ElementsBreadcrumbs);
-```
-
-And finally we tell TypeScript that this component exists:
-
-```ts
-declare global {
-  interface HTMLElementTagNameMap {
-    'devtools-elements-breadcrumbs': ElementsBreadcrumbs;
-  }
-}
-```
-
-By doing this, TypeScript understands that `document.querySelector('devtools-elements-breadcrumbs')` returns an `ElementsBreadcrumbs` instance.
-
-We use lit-analyzer in a lint state to verify that component definitions are imported where the component is used.
-
-## Creating a shadow root
-
-Each component gets its own Shadow Root to ensure that styles and events that occur within it are encapsulated and do not leak out:
-
-```ts
-export class ElementsBreadcrumbs extends HTMLElement {
-  readonly #shadow = this.attachShadow({mode: 'open'});
-}
-```
-
-> We set the mode to `open` so it's open to inspection via DevTools. [See this MDN explainer](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/mode) for more details.
-
-## Rendering a component
-
-Each component defines a `#render` method which is responsible for invoking LitHtml and having the component render HTML into the DOM.
-
-> The `#` symbol indicates a [private class method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields).
-
-The `#render` method calls `LitHtml.render`, building up a template with `LitHtml.html`:
-
-```ts
-LitHtml.render(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
-// clang-format off
-LitHtml.render(...)
-// clang-format on
-```
-
-## Scheduled and batched rendering
-
-To have your component render, you could manually call `this.#render()`. However, if you were to have multiple updates to a component (perhaps some values it's passed get changed), we want to avoid having multiple renders where possible and instead batch them.
-
-We can use the `ScheduledRender` helper (`front_end/ui/components/helpers/scheduled-render.ts`) to achieve this. Rather than call `this.#render()` directly, you instead call the scheduler:
-
-```ts
-void ComponentHelpers.ScheduledRender.scheduleRender(this, this.#render);
-```
-
-> `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 {
-  readonly #shadow = this.attachShadow({mode: 'open'});
-
-  #render(): void {
-    LitHtml.render(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 {
-  readonly #shadow = this.attachShadow({mode: 'open'});
-
-  connectedCallback(): void {
-    void ComponentHelpers.ScheduledRender.scheduleRender(this, this.#render);
-  }
-
-  #render(): void {
-    LitHtml.render(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.#render);
-  }
-}
-```
-
-## 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, import the module defining it and render within the call to `LitHtml.html`:
-
-```ts
-// Within some component
-LitHtml.render(html`
-  <devtools-elements-breadcrumbs></devtools-elements-breadcrumbs>
-`, 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(html`
-  <devtools-elements-breadcrumbs .data=${{
-    selectedNode: node,
-    crumbs: [...],
-  }}>
-  </devtools-elements-breadcrumbs>
-`, this.#shadow, {host: this});
-```
-
-## 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.#render);
-  }
-
-  set selectedNode(selectedNode: ElementsBreadcrumbsData['selectedNode']) {
-    this.#selectedNode = selectedNode;
-    void ComponentHelpers.ScheduledRender.scheduleRender(this, this.#render);
-  }
-}
-```
-
-Rendering this component within another Lit component would now be done like so:
-
-```ts
-// Within some component
-LitHtml.render(html`
-  <devtools-elements-breadcrumbs .crumbs=${[...]} .selectedNode=${node}>
-  </devtools-elements-breadcrumbs>
-`, 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/docs/building-ui-documentation/README.md

@@ -1,23 +0,0 @@
-# Building UI elements in DevTools
-
-This is the documentation containing all the information you need to be able to build UI in DevTools and get familiar with our front-end stack.
-
-Note that this documentation is a work in progress as it is migrated from the [original Google Doc](https://docs.google.com/document/d/1Gwd-w7LoW1qnWu3uku438-MQ82m4AinKDIdy9z3fl3Q/edit?resourcekey=0-vxHqiKAvfJ4JAOj4bZ4EFA#). crbug.com/1344124 tracks this work.
-
-## Table of Contents
-
-1. [Creating components](./CreatingComponents.md)
-1. [Styling components](./StylingComponents.md)
-1. [Component performance](./ComponentPerformance.md)
-1. [Testing components](./TestingComponents.md)
-1. [Components and events](./ComponentEvents.md)
-
-## FAQs
-
-> Wasn't this a google doc before?
-
-Yes. The original version of this documentation was a publicly accessible Google Doc. However, keeping the documentation apart from the code was a challenge, along with the fact that Docs aren't the best for dealing with lots of code. That motivated the change to move the documentation into the repository, hopefully helping it keep up to date and still remaining public.
-
-> What should I do if I want to make a change?
-
-Please send a CL and ask jacktfranklin@ to review it. If you're not sure on the change, feel free to ping jacktfranklin@ to discuss.

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

@@ -1,66 +0,0 @@
-# Styling Components
-
-Components are styled by a CSS file that is co-located next to the TypeScript source file. The only difference in file name is the extension and that for CSS files, the first letter is lowercase:
-
-```
-- ElementsBreadcrumbs.ts
-- elementsBreadcrumbs.css
-```
-
-To import this file you use a regular `import` statement, and import the filename with `.js` appended:
-
-```ts
-import elementsBreadcrumbsStyles from './elementsBreadcrumbs.css.js';
-```
-
-As part of the build tool step, each CSS file is converted into a JS file that exports a `CSSInJS` string.
-
-## `BUILD.gn` changes
-
-Use the `generate_css` action (`scripts/build/ninja/generate_css.gni`) to declare stylesheets:
-
-```gn
-import("scripts/build/ninja/generate_css.gni") // Edit path correctly: this must be relative
-
-generate_css("css_files") {
-  sources = [ "elementsBreadcrumbs.css"]
-}
-```
-
-And then add `:css_files` as a dependency to the `devtools_entrypoint`:
-
-```gn
-devtools_entrypoint("bundle") {
-  deps = [  ":css_files" ,  "..."]
-}
-```
-
-## Using the stylesheet
-
-Importing the stylesheet is not enough to have it apply to the component's ShadowDOM, it must be inserted into
-a `<style>` tag in the template. The `#render` method is the best place for this:
-
-```ts
-#render() {
-  render(html`
-    <style>${elementsBreadcrumbsStyles}</style>
-    ...
-    `, this.#shadow, {host: this});
-}
-```
-
-## Tips for writing CSS.
-
-Use `:host` to style the component itself. By default elements are `display: inline`. Often it can be useful to set `display: block`.
-
-Remember to use theme colors (`var(--sys-color-on-surface)`) when styling elements to ensure consistency across DevTools.
-
-If you want your component to have its colors configurable by users, consider defining `--override` variables. In your component's CSS, you would have something like:
-
-```css
-:host {
-  color: var(--override-custom-color, var(--sys-color-on-surface));
-}
-```
-
-This allows someone to define that `--override-custom-color` variable, but also ensures if it isn't defined that the default `color-text-primary` will be used. **Be careful with this!** We try to ensure consistent colors across DevTools; so most of the time you shouldn't allow configurable colors and should use the correct theme variables.

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

@@ -1,111 +0,0 @@
-# Testing components
-
-One of the main ways that we test our components is with thorough unit tests. In these tests we render the component into the page, and query the DOM to assert that the component behaves and outputs the HTML as we expect.
-
-## Initialising a component in a unit test
-
-Within a unit test, you can create the component by initialising it and calling any methods on it to set data:
-
-```ts
-it('outputs the user name onto the screen', async () => {
-  const component = new DummyComponent();
-  component.data = {name: 'Jack' /* whatever data the component needs */}
-})
-```
-
-Now we have a component, we need to render it into the page. You can use the `renderElementIntoDOM` helper method, which is defined in `test/unittests/front_end/helpers/DOMHelpers.js`. It is recommended to use this helper because it will automatically remove the component from the page after the test is done. It is important that the DOM is cleaned after each test to ensure that tests don't inadvertently change the behaviour of future tests.
-
-```ts
-import {
-  renderElementIntoDOM,
-  // adjust this path as required depending on the location of your test file
-} from '../../helpers/DOMHelpers.js';
-
-it('outputs the user name onto the screen', async () => {
-  const component = new DummyComponent();
-  component.data = {name: 'Jack' /* whatever data the component needs */}
-  renderElementIntoDOM(component)
-})
-```
-
-## Waiting for the component to render
-
-If your component is implemented using the scheduled renderer, you will need to wait for the render to be complete before continuing with the test. Otherwise you may try to query the DOM before the component has finished rendering.
-
-```ts
-import * as RenderCoordinator from '../../../../../front_end/ui/components/render_coordinator/render_coordinator.js';
-
-it('outputs the user name onto the screen', async () => {
-  const component = new DummyComponent();
-  component.data = {name: 'Jack' /* whatever data the component needs */}
-  renderElementIntoDOM(component);
-  await RenderCoordinator.done(); // Ensure the component is rendered onto the page.
-})
-```
-
-## Querying the component
-
-Most of our components use the [shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM) to render their content. Therefore when querying the contents of the component in a test we need to query the contents of its shadow DOM.
-
-The shadow DOM for a component can be accessed via `component.shadowRoot`. In TypeScript, this is typed as `ShadowRoot | null`. We therefore have another helper in `DOMHelpers.js` that can check that the shadow root is available, and fail the test otherwise. This will also satisfy TypeScript that the shadow root is present, and avoids you having to continually guard against it being `null`:
-
-```ts
-it('outputs the user name onto the screen', async () => {
-  const component = new DummyComponent();
-  component.data = {name: 'Jack' /* whatever data the component needs */}
-  renderElementIntoDOM(component);
-  await RenderCoordinator.done();
-  assert.isNotNull(component.shadowRoot); // Check that the Shadow Root exists.
-})
-```
-
-Now we are ready to query the DOM and make assertions! You can use the regular DOM APIs such as `querySelector` / `querySelectorAll`:
-
-```ts
-it('outputs the user name onto the screen', async () => {
-  const component = new DummyComponent();
-  component.data = {name: 'Jack' /* whatever data the component needs */}
-  renderElementIntoDOM(component);
-  await RenderCoordinator.done();
-  assert.isNotNull(component.shadowRoot);
-  const name = component.shadowRoot.querySelector<HTMLElement>('span.name');
-})
-```
-
-Note that by default TypeScript will type the result as `Element|null`. Sometimes it is useful to tell TypeScript more specifically what type of element you are expecting, as not all APIs (such as `textContent`) are available on the `Element` type.
-
-## Ensuring queries returned elements
-
-Any DOM querying API could return back `null` if the element was not found. You can use the `assert.instanceOf` method from Chai to ensure that if the element was not found, the test fails. This also satisfies TypeScript and (much like with the shadow root check earlier) avoids you having to continually code against the element not being found.
-
-
-```ts
-it('outputs the user name onto the screen', async () => {
-  const component = new DummyComponent();
-  component.data = {name: 'Jack' /* whatever data the component needs */}
-  renderElementIntoDOM(component);
-  await RenderCoordinator.done();
-  assert.isNotNull(component.shadowRoot);
-  const name = component.shadowRoot.querySelector<HTMLElement>('span.name');
-  assert.instanceOf(name, HTMLSpanElement);
-})
-```
-
-## Asserting on the contents
-
-Now we have an element that exists, we can query for its contents and assert against them:
-
-```ts
-it('outputs the user name onto the screen', async () => {
-  const component = new DummyComponent();
-  component.data = {name: 'Jack' /* whatever data the component needs */}
-  renderElementIntoDOM(component);
-  await RenderCoordinator.done();
-  assert.isNotNull(component.shadowRoot);
-  const name = component.shadowRoot.querySelector<HTMLElement>('span.name');
-  assert.instanceOf(name, HTMLSpanElement);
-  assert.strictEqual(name.innerText, 'Jack');
-})
-```
-
-And with that, our basic unit test is written.

package/front_end/ui/components/docs/component_docs.ts

@@ -1,24 +0,0 @@
-// Copyright 2020 The Chromium Authors
-// Use of this source code is governed by a BSD-style license that can be
-// found in the LICENSE file.
-
-// Ensure all image variables are defined in the component docs.
-import '../../../Images/Images.js';
-
-import * as CreateBreadcrumbs from './create_breadcrumbs.js';
-
-CreateBreadcrumbs.init();
-
-// This can be used by tests to hide the UI elements that are part of the component docs interface.
-// E.g., this is useful for screenshot tests.
-window.addEventListener('hidecomponentdocsui', () => {
-  for (const node of document.querySelectorAll<HTMLElement>('.component-docs-ui')) {
-    node.style.display = 'none';
-  }
-});
-
-window.addEventListener('showcomponentdocsui', () => {
-  for (const node of document.querySelectorAll<HTMLElement>('.component-docs-ui')) {
-    node.style.display = '';
-  }
-});

package/front_end/ui/components/docs/component_docs_styles.css

@@ -1,53 +0,0 @@
-/*
- * Copyright 2021 The Chromium Authors
- * Use of this source code is governed by a BSD-style license that can be
- * found in the LICENSE file.
- */
-
-@import url('https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,100..900;1,100..900&display=swap');
-
-body {
-  margin: 0;
-  padding: 0;
-}
-
-#index-page h1 {
-  text-align: left;
-  border-bottom: 1px solid var(--sys-color-divider);
-  padding: 10px;
-  width: 100%;
-  margin-bottom: 10px;
-}
-
-.components-list {
-  display: flex;
-  flex-wrap: wrap;
-  list-style: none;
-  margin: 0;
-  padding: 10px;
-}
-
-.components-list li {
-  width: 20%;
-  min-width: 150px;
-  max-width: 300px;
-  margin: 0 12px 12px 0;
-}
-
-.components-list a {
-  display: block;
-  font-size: 14px;
-  padding: 10px;
-}
-
-.components-list a:link,
-.components-list a:visited {
-  text-transform: capitalize;
-  color: var(--sys-color-primary);
-  text-decoration: none;
-  box-shadow: var(--drop-shadow);
-}
-
-.components-list a:hover {
-  box-shadow: var(--drop-shadow-depth-3);
-}

package/front_end/ui/components/docs/create_breadcrumbs.ts

@@ -1,44 +0,0 @@
-// Copyright 2020 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 Lit from '../../lit/lit.js';
-
-const {html} = Lit;
-
-export function init(): void {
-  const container = document.createElement('ul');
-  // clang-format off
-  // eslint-disable-next-line @devtools/no-a-tags-in-lit
-  Lit.render(html`
-
-  <style>
-    .docs-breadcrumbs {
-      display: flex;
-      list-style: none;
-      position: fixed;
-      background: rgb(255 255 255 / .8);
-      padding: 5px;
-      bottom: 0;
-      left: 10px;
-      width: 300px;
-    }
-
-    .docs-breadcrumbs li a {
-      display: block;
-      padding: 10px;
-      font-size: 16px;
-    }
-
-    .docs-breadcrumbs span {
-      font-size: 20px;
-    }
-  </style>
-
-  <ul class="docs-breadcrumbs component-docs-ui">
-    <li><a href="/">Index</a></li>
-    <li><a href=".">All component examples</a></li>
-  </ul>`, container);
-  // clang-format on
-
-  document.body.appendChild(container);
-}

package/front_end/ui/components/docs/slider/basic.html

@@ -1,20 +0,0 @@
-<!--
-  Copyright 2024 The Chromium Authors
-  Use of this source code is governed by a BSD-style license that can be
-  found in the LICENSE file.
--->
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width" />
-    <title>Basic Slider example</title>
-  </head>
-  <body>
-
-    <div id="container">
-    </div>
-
-    <script type="module" src="./basic.js"></script>
-  </body>
-</html>

package/front_end/ui/components/docs/switch/basic.html

@@ -1,20 +0,0 @@
-<!--
-  Copyright 2024 The Chromium Authors
-  Use of this source code is governed by a BSD-style license that can be
-  found in the LICENSE file.
--->
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width" />
-    <title>Basic Switch example</title>
-  </head>
-  <body>
-
-    <div id="container">
-    </div>
-
-    <script type="module" src="./basic.js"></script>
-  </body>
-</html>