chrome-devtools-frontend 1.0.1519267 → 1.0.1520535

package/docs/ui_engineering.md

@@ -212,3 +212,1014 @@ setMockConnectionResponseHandler('CSS.getHeaders', () => ({}));
 const presenter = new Presenter();
 presenter.doSomething();
 ```
+
+# Migrating Widgets and other "legacy" components
+
+This section provides a series of examples for migrating from imperative DOM manipulation to a declarative approach using lit-html templates.
+
+## Setting `className` on `this.element`
+
+Instead of setting `className` directly on `this.element`, define the component's structure declaratively using a lit-html template.
+
+**Before:**
+```typescript
+class SomeWidget extends UI.Widget.Widget {
+          constructor() {
+            super();
+            this.element.className = 'some-class';
+          }
+      }
+```
+
+**After:**
+```typescript
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div class="some-class"></div>`,
+    target, {host: input});
+};
+```
+
+## Appending a new element
+
+Instead of using `appendChild` with `document.createElement`, define the new element within a lit-html template.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.contentElement.appendChild(document.createElement('div'));
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <div></div>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Setting multiple attributes and `textContent`
+
+Combine setting `className`, attributes, and `textContent` into a single declarative lit-html template.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.contentElement.className = 'some-class';
+    this.contentElement.setAttribute('aria-label', 'some-label');
+    this.contentElement.textContent = 'some-text';
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div class="some-class" aria-label="some-label">some-text</div>`,
+    target, {host: input});
+};
+```
+
+## Creating a child, adding a class, and adding an event listener
+
+Use a lit-html template to create the element, set multiple classes, and attach event listeners declaratively.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.container = this.contentElement.createChild('div', 'some-class');
+    this.container.classList.add('container');
+    this.container.addEventListener('click', this.onClick.bind(this));
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <div class="some-class container" @click=${this.onClick.bind(this)}></div>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Setting inline styles
+
+Set inline styles directly within the lit-html template using the `style` attribute.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.contentElement.style.width = '100%';
+    this.contentElement.style.marginLeft = '10px';
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div style="width:100%; margin-left:10px"></div>`,
+    target, {host: input});
+};
+```
+
+## Creating and appending a styled element
+
+Replace `document.createElement`, setting `className`, and `appendChild` with a declarative lit-html template.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const div = document.createElement('div');
+    div.className = 'some-class';
+    this.contentElement.appendChild(div);
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <div class="some-class"></div>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Creating a child with text content
+
+Define the element and its text content directly within a lit-html template.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.contentElement.createChild('span', 'some-class').textContent = 'some-text';
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <span class="some-class">some-text</span>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `UI.Toolbar.ToolbarFilter`
+
+Replace the imperative creation of a `ToolbarFilter` with the declarative `<devtools-toolbar-input>` component.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const toolbar = this.contentElement.createChild('devtools-toolbar');
+    const filterInput = new UI.Toolbar.ToolbarFilter('some-placeholder', 0.5, 1, undefined, this.complete.bind(this), false, 'some-filter');
+    filterInput.addEventListener(UI.Toolbar.ToolbarInput.Event.TEXT_CHANGED, this.onFilterChanged.bind(this));
+    filterInput.element.classList.add('completions');
+    filterInput.element.setAttribute('aria-hidden', 'true');
+    toolbar.appendToolbarItem(filterInput);
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-toolbar>
+        <devtools-toolbar-input class="completions" type="filter" placeholder="some-placeholder"
+            list="completions" id="some-filter" aria-hidden="true"
+            @change=${this.onFilterChanged.bind(this)} style="flex-grow:0.5; flex-shrink:1">
+          <datalist id="completions">${this.complete.bind(this)}</datalist>
+        </devtools-toolbar-input>
+      </devtools-toolbar>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `UI.Toolbar.ToolbarInput`
+
+Replace the imperative creation of a `ToolbarInput` with the declarative `<devtools-toolbar-input>` component.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const toolbar = this.contentElement.createChild('devtools-toolbar');
+    const filterInput = new UI.Toolbar.ToolbarInput('some-placeholder', 'accessible-placeholder', 0.5, 1);
+    toolbar.appendToolbarItem(filterInput);
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-toolbar>
+        <devtools-toolbar-input type="text" placeholder="some-placeholder"
+            aria-label="accessible-placeholder" style="flex-grow:0.5; flex-shrink:1"></devtools-toolbar-input>
+      </devtools-toolbar>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `Adorners.Adorner.Adorner`
+
+Replace the imperative creation of an `Adorner` with the declarative `<devtools-adorner>` component.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const adornerContent = document.createElement('span');
+    adornerContent.innerHTML = '<div style="font-size: 12px;">💫</div>';
+    const adorner = new Adorners.Adorner.Adorner();
+    adorner.classList.add('fix-perf-icon');
+    adorner.data = {
+      name: i18nString(UIStrings.fixMe),
+      content: adornerContent,
+      jslogContext: 'fix-perf',
+    };
+    this.contentElement.appendChild(adorner);
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-adorner class="fix-perf-icon" aria-label=${i18nString(UIStrings.fixMe)}
+          jslog=${VisualLogging.adorner('fix-perf')}>
+        <span><div style="font-size: 12px;">💫</div></span>
+      </devtools-adorner>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `UI.Toolbar.ToolbarButton`
+
+Replace the imperative creation of a `ToolbarButton` with the declarative `<devtools-button>` component.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const toolbar = this.contentElement.createChild('devtools-toolbar');
+    const editButton = new UI.Toolbar.ToolbarButton(i18nString(UIStrings.editName), 'edit', undefined, 'edit-name');
+    editButton.addEventListener(UI.Toolbar.ToolbarButton.Events.CLICK, this.onClick.bind(this));
+    toolbar.appendToolbarItem(editButton);
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-toolbar>
+        <devtools-button title=${i18nString(UIStrings.editName)} @click=${this.onClick.bind(this)}
+            .variant=${Buttons.Button.Variant.TOOLBAR} .iconName=${'edit'}
+            .jslogContext=${'edit-name'}></devtools-button>
+      </devtools-toolbar>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating various HTML elements with multiple properties
+
+Replace imperative creation of standard HTML elements like `<a>`, `<img>`, and `<input>` with their declarative equivalents in a lit-html template, setting their properties as attributes.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const input = document.createElement('input');
+    input.type = 'text';
+    input.placeholder = 'some-placeholder';
+    input.value = 'some-value';
+    input.disabled = !this.enabled;
+    input.checked = true
+    this.contentElement.append(input);
+
+    const anchor = document.createElement('a');
+    anchor.href = 'https://www.google.com';
+    anchor.innerText = 'some-text';
+    anchor.dataset.someKey = 'some-value';
+    anchor.role = 'some-role';
+    this.contentElement.insertBefore(anchor, input);
+
+    const img = document.createElement('img');
+    img.src = 'https://www.google.com/some-image.png';
+    img.alt = 'some-alt';
+    img.draggable = true;
+    img.height = 100;
+    img.hidden = 'hidden';
+    img.href = 'https://www.google.com';
+    img.id = 'some-id';
+    img.name = 'some-name';
+    img.rel = 'some-rel';
+    img.scope = 'some-scope';
+
+    input.insertAdjacentElement('beforebegin', img);
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <a href="https://www.google.com" data-some-key="some-value" role="some-role">some-text</a>
+      <img src="https://www.google.com/some-image.png" alt="some-alt" draggable="true" height="100"
+          hidden="hidden" href="https://www.google.com" id="some-id" name="some-name" rel="some-rel"
+          scope="some-scope"></img>
+      <input type="text" placeholder="some-placeholder" value="some-value"
+          ?disabled=${!this.enabled} checked>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `UI.UIUtils` helpers
+
+Replace `UI.UIUtils` helper functions like `createLabel` and `createTextButton` with their declarative component counterparts like `<label>` and `<devtools-button>`.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const select = document.createElement('select');
+    select.add(UI.UIUtils.createOption('Option 1', '1', 'option-1'));
+    this.contentElement.appendChild(UI.UIUtils.createLabel('Some label:', 'some-label', select));
+    this.contentElement.appendChild(UI.UIUtils.createTextButton('Some button', onClick, {
+      className: 'some-class',
+      jslogContext: 'some-button',
+      variant: Buttons.Button.Variant.PRIMARY,
+      title: i18nString(UIStrings.someTitle),
+      iconName: 'some-icon'
+    }));
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <label class="some-label">Some label:
+        <select>
+          <option value="1" jslog=${VisualLogging.dropDown('1').track({click: true})}>Option 1</option>
+        </select>
+      </label>
+      <devtools-button class="some-class" title=${i18nString(UIStrings.someTitle)} @click=${onClick}
+          .jslogContext=${'some-button'} .variant=${Buttons.Button.Variant.PRIMARY}>Some button</devtools-button>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `UI.UIUtils.createTextChild`
+
+Instead of using `createTextChild`, include the text directly inside the element in the lit-html template.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    UI.UIUtils.createTextChild(this.contentElement.createChild('div', 'some-class'), 'some-text');
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <div class="some-class">some-text</div>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `Buttons.Button.Button` with ARIA and Tooltip helpers
+
+Replace the imperative creation of a `Button` and subsequent modifications with ARIA and Tooltip helpers with a single declarative `<devtools-button>` component, setting properties like `role` and `title`.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.button = new Buttons.Button.Button();
+    this.button.data = {
+      jslogContext: 'some-button',
+      variant: Buttons.Button.Variant.PRIMARY,
+      title: i18nString(UIStrings.someTitle),
+    };
+    UI.ARIAUtils.markAsPresentation(this.button);
+    UI.Tooltip.Tooltip.install(this.button, i18nString(UIStrings.someTooltip));
+  }
+}
+```
+
+**After:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.button = html`
+    <devtools-button role="presentation" title=${i18nString(UIStrings.someTooltip)}
+        .data=${{
+      jslogContext: 'some-button',
+      variant: Buttons.Button.Variant.PRIMARY,
+      title: i18nString(UIStrings.someTitle),
+    }}
+    ></devtools-button>`;
+  }
+}
+```
+
+## Migrating `IconButton.Icon.Icon`
+
+Replace the imperative `Icon` creation with the declarative `<devtools-icon>` component.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const icon = new IconButton.Icon.Icon();
+    icon.data = {iconName: 'checkmark', color: 'var(--icon-checkmark-green)', width: '14px', height: '14px'};
+    this.contentElement.appendChild(icon);
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-icon name="checkmark"
+          style="color:var(--icon-checkmark-green); width:14px; height:14px"></devtools-icon>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating Checkboxes
+
+Replace various imperative checkbox creation methods with the declarative `<devtools-checkbox>` component. For settings-backed checkboxes, use the `bindToSetting` directive.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.contentElement.appendChild(UI.UIUtils.CheckboxLabel.create(
+          i18nString(UIStrings.someTitle), true, i18nString(UIStrings.someTooltip),
+          undefined, 'some-checkbox', true));
+    this.contentElement.appendChild(UI.UIUtils.CheckboxLabel.create());
+    this.contentElement.appendChild(UI.UIUtils.CheckboxLabel.createWithStringLiteral(
+        ':hover', undefined, undefined, 'some-other-checkbox'));
+
+    const toolbar = this.contentElement.createChild('devtools-toolbar');
+    toolbar.appendToolbarItem(new UI.Toolbar.ToolbarCheckbox(
+        i18nString(UIStrings.someToolbarTitle), i18nString(UIStrings.someToolbarTooltip),
+        this.someToolbarCheckboxClicked.bind(this), 'some-toolbar-checkbox'));
+    toolbar.appendToolbarItem(new UI.Toolbar.ToolbarSettingCheckbox(
+        this.someSetting, i18nString(UIStrings.someToolbarTooltip), i18nString(UIStrings.alternateToolbarTitle)));
+    toolbar.appendToolbarItem(new UI.Toolbar.ToolbarSettingCheckbox(this.someOtherSetting));
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-checkbox class="small" checked>${i18nString(UIStrings.someTitle)}</devtools-checkbox>
+      <devtools-checkbox></devtools-checkbox>
+      <devtools-checkbox class="small">:hover</devtools-checkbox>
+      <devtools-toolbar>
+        <devtools-checkbox title=${i18nString(UIStrings.someToolbarTooltip)}
+            @click=${this.someToolbarCheckboxClicked.bind(this)}
+            .jslogContext=${'some-toolbar-checkbox'}>${i18nString(UIStrings.someToolbarTitle)}</devtools-checkbox>
+        <devtools-checkbox title=${i18nString(UIStrings.someToolbarTooltip)}
+            ${bindToSetting(this.someSetting)}>${i18nString(UIStrings.alternateToolbarTitle)}</devtools-checkbox>
+        <devtools-checkbox ${bindToSetting(this.someOtherSetting)}>${this.someOtherSetting.title()}</devtools-checkbox>
+      </devtools-toolbar>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `iframe` creation
+
+Replace `document.createElement('iframe')` and `setAttribute` calls with a declarative `<iframe>` tag in a lit-html template.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const iframe = document.createElement('iframe');
+    iframe.setAttribute('sandbox', '');
+    iframe.tabIndex = -1;
+    this.contentElement.appendChild(iframe);
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <iframe sandbox tabindex="-1"></iframe>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `UI.UIUtils.createInput`
+
+Replace the `createInput` helper with a standard `<input>` element in a lit-html template.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.contentElement.appendChild(UI.UIUtils.createInput('add-source-map', 'text', 'url'));
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <input class="harmony-input add-source-map" spellcheck="false" type="text"
+          jslog=${VisualLogging.textField('url').track({keydown: 'Enter', change: true})}>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `SortableDataGrid`, `ViewportDataGrid`, `DataGridImpl`
+
+Replace the imperative `SortableDataGrid`, `ViewportDataGrid`, or `DataGridImpl` with the declarative `<devtools-data-grid>` component. Columns are defined using `<th>` elements inside a `<table>`.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.#columns = [
+      {
+        id: 'node-id',
+        title: i18nString(UIStrings.element),
+        sortable: true,
+        weight: 50,
+        align: undefined,
+      },
+      {
+        id: 'declaration',
+        title: i18nString(UIStrings.declaration),
+      },
+      {
+        id: 'source-url',
+        title: i18nString(UIStrings.source),
+        sortable: false,
+        weight: 100,
+        align: DataGrid.DataGrid.Align.RIGHT,
+      },
+    ];
+
+    this.#dataGrid = new DataGrid.SortableDataGrid.SortableDataGrid({
+      displayName: i18nString(UIStrings.someTitle),
+      columns: this.#columns,
+      deleteCallback: undefined,
+      refreshCallback: undefined,
+    });
+    this.#dataGrid.setStriped(true);
+    this.#dataGrid.addEventListener(
+        DataGrid.DataGrid.Events.SORTING_CHANGED, this.#sortMediaQueryDataGrid.bind(this));
+
+    this.#dataGrid.asWidget().show(this.element);
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-data-grid name=${i18nString(UIStrings.someTitle)} striped
+          @sort=${this.#sortMediaQueryDataGrid.bind(this)}>
+        <table>
+          <tr>
+            <th id="node-id" weight="50" sortable>${i18nString(UIStrings.element)}</th>
+            <th id="declaration">${i18nString(UIStrings.declaration)}</th>
+            <th id="source-url" weight="100" align="right">${i18nString(UIStrings.source)}</th>
+          </tr>
+        </table>
+      </devtools-data-grid>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `DataGridNode.createCell`
+
+The `createCell` method in a `DataGridNode` can be refactored to return a lit-html template for the cell's content, making it declarative.
+
+**Before:**
+```typescript
+
+class ElementNode extends DataGrid.SortableDataGrid.SortableDataGridNode<ElementNode> {
+  override createCell(columnId: string): HTMLElement {
+    const cell = this.createTD(columnId);
+    cell.classList.add('node-id');
+    cell.createChild('span', 'node-id-text').textContent = this.data.id;
+    return cell;
+  }
+}
+```
+
+**After:**
+```typescript
+
+class ElementNode extends DataGrid.SortableDataGrid.SortableDataGridNode<ElementNode> {
+  override createCell(columnId: string): HTMLElement {
+    const cell = this.createTD(columnId);
+    render(html`
+      <td class="node-id">
+        <span class="node-id-text">${this.data.id}</span>
+      </td>`, cell);
+    return cell;
+  }
+}
+```
+
+## Migrating `SplitWidget`
+
+Replace the imperative `SplitWidget` with the declarative `<devtools-split-view>` component. Nested widgets can be rendered using `<devtools-widget>`.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.#splitWidget = new UI.SplitWidget.SplitWidget(this.vertical, false, undefined, 200);
+    this.#splitWidget.show(this.element);
+
+    this.#mainContainer = new UI.SplitWidget.SplitWidget(true, true);
+    this.#resultsContainer = new UI.Widget.EmptyWidget();
+    this.#elementContainer = new DetailsView();
+
+    this.#mainContainer.setMainWidget(this.#resultsContainer);
+    this.#mainContainer.setSidebarWidget(this.#elementContainer);
+    this.#mainContainer.setVertical(false);
+    this.#mainContainer.setSecondIsSidebar(this.dockedLeft);
+
+    this.#sideBar = new SidebarPanel();
+    this.#sideBar.setMinimumSize(100, 25);
+    this.#splitWidget.setSidebarWidget(this.#sideBar);
+    this.#splitWidget.setMainWidget(this.#mainContainer);
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-split-view direction=${this.vertical ? 'column' : 'row'} sidebar-position="first"
+          sidebar-initial-size="200">
+        <devtools-widget slot="sidebar" .widgetConfig=${widgetConfig(SidebarPanel,
+            {minimumSize: {width: 100, height: 25}})}></devtools-widget>
+        <devtools-split-view direction="column" sidebar-position="second" slot="main"
+            direction="row" sidebar-position="$this.dockedLeft ? 'second' : 'first'}">
+          <devtools-widget slot="main" .widgetConfig=${widgetConfig(UI.Widget.EmptyWidget)}></devtools-widget>
+          <devtools-widget slot="sidebar" .widgetConfig=${widgetConfig(DetailsView)}></devtools-widget>
+        </devtools-split-view>
+      </devtools-split-view>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `UI.Fragment`
+
+Replace `UI.Fragment.Fragment.build` with a standard lit-html template. To get a reference to an element, use the `ref` directive.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const contrastFragment = UI.Fragment.Fragment.build`
+      <div class="contrast-container-in-grid" $="contrast-container-element">
+        <span class="contrast-preview">Aa</span>
+        <span>${contrastRatioString}</span>
+      </div>`;
+    this.contentElement.appendChild(contrastFragment.element());
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, output, target) => {
+  render(html`
+    <div>
+      <div class="contrast-container-in-grid" ${ref(e => { output.contrastContainerElement = e; })}>
+        <span class="contrast-preview">Aa</span>
+        <span>${contrastRatioString}</span>
+      </div>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `UI.ARIAUtils` helpers
+
+Replace calls to `UI.ARIAUtils` helper functions with the corresponding ARIA attributes directly in the lit-html template.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    this.button = this.contentElement.createChild('button');
+    UI.ARIAUtils.markAsMenuButton(this.button);
+    const tree = this.contentElement.createChild('ul');
+    UI.ARIAUtils.markAsTree(tree);
+    UI.ARIAUtils.markAsTreeitem(tree.createChild('li'));
+    const alert = this.contentElement.createChild('span');
+    alert.textContent = 'Alert';
+    UI.ARIAUtils.markAsAlert(alert);
+    const slider = this.contentElement.createChild('input');
+    UI.ARIAUtils.markAsSlider(slider, 10);
+
+    UI.ARIAUtils.setDescription(this.button, 'Some button');
+    UI.ARIAUtils.setInvalid(slider, this.valid);
+
+    const progress = this.contentElement.createChild('div');
+    UI.ARIAUtils.markAsProgressBar(progress);
+    UI.ARIAUtils.setProgressBarValue(progress, 0.5, '50% done');
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <button role="button" aria-haspopup="true" aria-description="Some button"></button>
+      <ul role="tree">
+        <li role="treeitem"></li>
+      </ul>
+      <span role="alert" aria-live="polite">Alert</span>
+      <input role="slider" aria-valuemin="10" aria-valuemax="100" aria-invalid=${this.valid}>
+      <div role="progressbar" aria-valuemin="0" aria-valuemax="100" aria-valuenow="0.5"
+          aria-valuetext="50% done"></div>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `EmptyWidget`
+
+Replace the imperative `EmptyWidget` with a declarative `<devtools-widget>` and configure it with `widgetConfig` to render an `EmptyWidget`.
+
+**Before:**
+```typescript
+
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const widget = new UI.EmptyWidget.EmptyWidget(i18nString(UIStrings.nothingToSeeHere), this.explanation);
+    widget.link = 'http://www.google.com';
+    widget.show(this.element);
+  }
+}
+```
+
+**After:**
+```typescript
+
+
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-widget .widgetConfig=${widgetConfig(UI.EmptyWidget.EmptyWidget,{
+          header: i18nString(UIStrings.nothingToSeeHere), text: this.explanation,
+          link: 'http://www.google.com',})}></devtools-widget>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `TextPrompt`
+
+Replace imperative `TextPrompt` creation with the declarative `<devtools-prompt>` component, providing completions via `<datalist>`.
+
+**Before:**
+```typescript
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const prompt = new UI.TextPrompt.TextPrompt();
+    prompt.initialize(async (expression, prefix) => {
+      const options = ['completion1', 'completion2'];
+      return options.filter(opt => opt.startsWith(prefix)).map(text => ({text}));
+    });
+    const promptElement = this.contentElement.createChild('span');
+    prompt.attach(promptElement);
+  }
+}
+```
+
+**After:**
+```typescript
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <datalist id="my-completions">
+        <option>completion1</option>
+        <option>completion2</option>
+      </datalist>
+      <devtools-prompt completions="my-completions" editing></devtools-prompt>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `TreeOutline`
+
+Replace imperative `TreeOutline` and `TreeElement` creation with the declarative `<devtools-tree>` component.
+
+**Before:**
+```typescript
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const tree = new UI.TreeOutline.TreeOutlineInShadow();
+    this.contentElement.appendChild(tree.element);
+
+    const root = tree.rootElement();
+    const node1 = new UI.TreeOutline.TreeElement('Node 1');
+    root.appendChild(node1);
+
+    const node2 = new UI.TreeOutline.TreeElement('Node 2', true);
+    root.appendChild(node2);
+
+    const child1 = new UI.TreeOutline.TreeElement('Child 1');
+    node2.appendChild(child1);
+  }
+}
+```
+
+**After:**
+```typescript
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-tree .template=${html`
+        <ul role="tree">
+          <li role="treeitem">Node 1</li>
+          <li role="treeitem">
+            Node 2
+            <ul role="group" hidden>
+              <li role="treeitem">Child 1</li>
+            </ul>
+          </li>
+        </ul>
+      `}></devtools-tree>
+    </div>`,
+    target, {host: input});
+};
+```