Document more migrations

Bug: 407732859
Change-Id: Ic59bf70548aa54865a50b531273581d395e1865e
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/7032119
Commit-Queue: Philip Pfaffe <[email protected]>
Reviewed-by: Danil Somsikov <[email protected]>
Reviewed-by: Benedikt Meurer <[email protected]>

Author: pfaffe

docs/ui_engineering.md

@@ -812,6 +812,165 @@ export const DEFAULT_VIEW = (input, _output, target) => {
 };
 ```
 
+## Binding an action to a button
+
+Use the `bindToAction` directive to create a button that is bound to a registered action. The button's properties (e.g., `title`, `disabled`) will be automatically updated when the action's state changes.
+
+**Before:**
+```typescript
+class SomeWidget extends UI.Widget.Widget implements UI.Toolbar.ItemsProvider {
+  constructor() {
+    super();
+    this.toolbarItemsInternal = [];
+    this.toolbarItemsInternal.push(UI.Toolbar.Toolbar.createActionButton('elements.refresh-event-listeners'));
+  }
+
+  toolbarItems(): UI.Toolbar.ToolbarItem[] {
+    return this.toolbarItemsInternal;
+  }
+}
+```
+
+**After:**
+```typescript
+export const DEFAULT_VIEW = (input, _output, target) => {
+  const {bindToAction} = UI.UIUtils;
+  render(html`
+    <div>
+      <devtools-toolbar>
+        <devtools-button ${bindToAction('elements.refresh-event-listeners')}></devtools-button>
+      </devtools-toolbar>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Binding a setting to a checkbox
+
+Use the `bindToSetting` directive to bind a boolean setting to a `<devtools-checkbox>` component.
+
+**Before:**
+```typescript
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const toolbar = this.contentElement.createChild('devtools-toolbar');
+    const showAllPropertiesSetting = Common.Settings.Settings.instance().createSetting('show-all-properties', false);
+    toolbar.appendToolbarItem(new UI.Toolbar.ToolbarSettingCheckbox(
+        showAllPropertiesSetting, i18nString(UIStrings.showAllTooltip), i18nString(UIStrings.showAll)));
+  }
+}
+```
+
+**After:**
+```typescript
+export const DEFAULT_VIEW = (input, _output, target) => {
+  const {bindToSetting} = UI.SettingsUI;
+  const showAllPropertiesSetting = Common.Settings.Settings.instance().createSetting('show-all-properties', false);
+  render(html`
+    <div>
+      <devtools-toolbar>
+        <devtools-checkbox title=${i18nString(UIStrings.showAllTooltip)} ${bindToSetting(showAllPropertiesSetting)}>
+          ${i18nString(UIStrings.showAll)}
+        </devtools-checkbox>
+      </devtools-toolbar>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating `UI.Toolbar.ToolbarComboBox`
+
+Replace the imperative creation of a `ToolbarComboBox` with a declarative `<select>` element.
+
+**Before:**
+```typescript
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const toolbar = this.contentElement.createChild('devtools-toolbar');
+    toolbar.appendToolbarItem(new UI.Toolbar.ToolbarComboBox(
+       this.someToolbarComboBoxClicked.bind(this), 'Combox',
+       'the-toolbar-combox', 'some-toolbar-combox'));
+  }
+}
+```
+
+**After:**
+```typescript
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-toolbar>
+        <select class="the-toolbar-combox" title="Combox" aria-label="Combox"
+            jslog=${VisualLogging.dropDown('some-toolbar-combox').track({change: true})}
+            @change=${this.someToolbarComboBoxClicked.bind(this)}></select>
+      </devtools-toolbar>
+    </div>`,
+    target, {host: input});
+};
+```
+
+## Migrating various Toolbar items
+
+Replace various imperative `UI.Toolbar` methods like `appendSeparator`, `appendSpacer`, and `setEnabled` with their declarative equivalents.
+
+**Before:**
+```typescript
+class SomeWidget extends UI.Widget.Widget {
+  constructor() {
+    super();
+    const toolbar = this.contentElement.createChild('devtools-toolbar');
+    toolbar.wrappable = true;
+    toolbar.appendSeparator();
+    const combo = new UI.Toolbar.ToolbarComboBox(this.onSelect.bind(this), 'aria-label', undefined, 'combo-box');
+    combo.createOption('Option 1', '1', 'option-1');
+    const option2 = document.createElement('option');
+    option2.value = '2';
+    option2.textContent = 'Option 2';
+    combo.addOption(option2);
+    toolbar.appendToolbarItem(combo);
+    toolbar.appendSpacer();
+    const button = new UI.Toolbar.ToolbarButton('Click me', 'largeicon-add');
+    button.setEnabled(false);
+    toolbar.appendToolbarItem(button);
+    const otherButton = new UI.Toolbar.ToolbarButton('Other button', 'largeicon-delete');
+    otherButton.setEnabled(this.isEnabled);
+    toolbar.appendToolbarItem(otherButton);
+    toolbar.appendToolbarItem(new UI.Toolbar.ToolbarSeparator());
+    toolbar.appendToolbarItem(new UI.Toolbar.ToolbarSeparator(false));
+    toolbar.appendToolbarItem(new UI.Toolbar.ToolbarSeparator(true));
+  }
+}
+```
+
+**After:**
+```typescript
+export const DEFAULT_VIEW = (input, _output, target) => {
+  render(html`
+    <div>
+      <devtools-toolbar wrappable>
+        <div class="toolbar-divider"></div>
+        <select title="aria-label" aria-label="aria-label"
+            jslog=${VisualLogging.dropDown('combo-box').track({change: true})}
+            @change=${this.onSelect.bind(this)}>
+          <option value="1" jslog=${VisualLogging.item('option-1').track({click: true})}>Option 1</option>
+          <option value="2">Option 2</option>
+        </select>
+        <div class="toolbar-spacer"></div>
+        <devtools-button title="Click me" .variant=${Buttons.Button.Variant.TOOLBAR}
+            .iconName=${'largeicon-add'} disabled></devtools-button>
+        <devtools-button title="Other button" ?disabled=${!this.isEnabled}
+            .variant=${Buttons.Button.Variant.TOOLBAR} .iconName=${'largeicon-delete'}></devtools-button>
+        <div class="toolbar-divider"></div>
+        <div class="toolbar-divider"></div>
+        <div class="toolbar-spacer"></div>
+      </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.