chrome-devtools-frontend 1.0.1023618 → 1.0.1024166

package/front_end/panels/timeline/TimelineDetailsView.ts

@@ -10,14 +10,14 @@ import * as Components from '../../ui/legacy/components/utils/utils.js';
 import * as UI from '../../ui/legacy/legacy.js';
 
 import {EventsTimelineTreeView} from './EventsTimelineTreeView.js';
-import type {PerformanceModel} from './PerformanceModel.js';
-import {Events} from './PerformanceModel.js';
+
+import {Events, type PerformanceModel} from './PerformanceModel.js';
 import {TimelineLayersView} from './TimelineLayersView.js';
 import {TimelinePaintProfilerView} from './TimelinePaintProfilerView.js';
-import type {TimelineModeViewDelegate} from './TimelinePanel.js';
-import {TimelineSelection} from './TimelinePanel.js';
-import type {TimelineTreeView} from './TimelineTreeView.js';
-import {BottomUpTimelineTreeView, CallTreeTimelineTreeView} from './TimelineTreeView.js';
+
+import {TimelineSelection, type TimelineModeViewDelegate} from './TimelinePanel.js';
+
+import {BottomUpTimelineTreeView, CallTreeTimelineTreeView, type TimelineTreeView} from './TimelineTreeView.js';
 import {TimelineDetailsContentHelper, TimelineUIUtils} from './TimelineUIUtils.js';
 
 const UIStrings = {

package/front_end/panels/timeline/TimelineEventOverview.ts

@@ -37,9 +37,9 @@ import * as UI from '../../ui/legacy/legacy.js';
 import * as Coverage from '../coverage/coverage.js';
 import * as Protocol from '../../generated/protocol.js';
 
-import type {PerformanceModel} from './PerformanceModel.js';
-import type {EventDispatchTypeDescriptor, TimelineCategory} from './TimelineUIUtils.js';
-import {TimelineUIUtils} from './TimelineUIUtils.js';
+import {type PerformanceModel} from './PerformanceModel.js';
+
+import {TimelineUIUtils, type EventDispatchTypeDescriptor, type TimelineCategory} from './TimelineUIUtils.js';
 
 const UIStrings = {
   /**

package/front_end/panels/timeline/TimelineFlameChartDataProvider.ts

@@ -42,11 +42,11 @@ import * as ThemeSupport from '../../ui/legacy/theme_support/theme_support.js';
 
 import timelineFlamechartPopoverStyles from './timelineFlamechartPopover.css.js';
 
-import type {PerformanceModel} from './PerformanceModel.js';
+import {type PerformanceModel} from './PerformanceModel.js';
 import {FlameChartStyle, Selection, TimelineFlameChartMarker} from './TimelineFlameChartView.js';
 import {TimelineSelection} from './TimelinePanel.js';
-import type {TimelineCategory} from './TimelineUIUtils.js';
-import {TimelineUIUtils, assignLayoutShiftsToClusters} from './TimelineUIUtils.js';
+
+import {TimelineUIUtils, assignLayoutShiftsToClusters, type TimelineCategory} from './TimelineUIUtils.js';
 
 const UIStrings = {
   /**

package/front_end/panels/timeline/TimelineFlameChartNetworkDataProvider.ts

@@ -15,7 +15,7 @@ import * as UI from '../../ui/legacy/legacy.js';
 import * as ThemeSupport from '../../ui/legacy/theme_support/theme_support.js';
 import * as Protocol from '../../generated/protocol.js';
 
-import type {PerformanceModel} from './PerformanceModel.js';
+import {type PerformanceModel} from './PerformanceModel.js';
 import {FlameChartStyle, Selection} from './TimelineFlameChartView.js';
 import {TimelineSelection} from './TimelinePanel.js';
 import {TimelineUIUtils} from './TimelineUIUtils.js';

package/front_end/panels/timeline/TimelineFlameChartView.ts

@@ -13,8 +13,8 @@ import * as PerfUI from '../../ui/legacy/components/perf_ui/perf_ui.js';
 import * as UI from '../../ui/legacy/legacy.js';
 
 import {CountersGraph} from './CountersGraph.js';
-import type {PerformanceModel, WindowChangedEvent} from './PerformanceModel.js';
-import {Events as PerformanceModelEvents} from './PerformanceModel.js';
+
+import {Events as PerformanceModelEvents, type PerformanceModel, type WindowChangedEvent} from './PerformanceModel.js';
 import {TimelineDetailsView} from './TimelineDetailsView.js';
 import {TimelineRegExp} from './TimelineFilters.js';
 import {
@@ -22,11 +22,11 @@ import {
   TimelineFlameChartDataProvider,
 } from './TimelineFlameChartDataProvider.js';
 import {TimelineFlameChartNetworkDataProvider} from './TimelineFlameChartNetworkDataProvider.js';
-import type {TimelineModeViewDelegate} from './TimelinePanel.js';
-import {TimelineSelection} from './TimelinePanel.js';
+
+import {TimelineSelection, type TimelineModeViewDelegate} from './TimelinePanel.js';
 import {AggregatedTimelineTreeView} from './TimelineTreeView.js';
-import type {TimelineMarkerStyle} from './TimelineUIUtils.js';
-import {TimelineUIUtils} from './TimelineUIUtils.js';
+
+import {TimelineUIUtils, type TimelineMarkerStyle} from './TimelineUIUtils.js';
 import {WebVitalsIntegrator} from './WebVitalsTimelineUtils.js';
 
 const UIStrings = {

package/front_end/panels/timeline/TimelineHistoryManager.ts

@@ -9,7 +9,7 @@ import * as UI from '../../ui/legacy/legacy.js';
 
 import timelineHistoryManagerStyles from './timelineHistoryManager.css.js';
 
-import type {PerformanceModel} from './PerformanceModel.js';
+import {type PerformanceModel} from './PerformanceModel.js';
 import {
   TimelineEventOverviewCPUActivity,
   TimelineEventOverviewNetwork,

package/front_end/panels/timeline/TimelinePanel.ts

@@ -52,11 +52,10 @@ import timelineStatusDialogStyles from './timelineStatusDialog.css.js';
 import type * as Coverage from '../coverage/coverage.js';
 import * as MobileThrottling from '../mobile_throttling/mobile_throttling.js';
 
-import type {WindowChangedEvent} from './PerformanceModel.js';
-import {Events, PerformanceModel} from './PerformanceModel.js';
-import type {Client} from './TimelineController.js';
-import {TimelineController} from './TimelineController.js';
-import type {TimelineEventOverview} from './TimelineEventOverview.js';
+import {Events, PerformanceModel, type WindowChangedEvent} from './PerformanceModel.js';
+
+import {TimelineController, type Client} from './TimelineController.js';
+
 import {
   TimelineEventOverviewCoverage,
   TimelineEventOverviewCPUActivity,
@@ -65,6 +64,7 @@ import {
   TimelineEventOverviewNetwork,
   TimelineEventOverviewResponsiveness,
   TimelineFilmStripOverview,
+  type TimelineEventOverview,
 } from './TimelineEventOverview.js';
 import {TimelineFlameChartView} from './TimelineFlameChartView.js';
 import {TimelineHistoryManager} from './TimelineHistoryManager.js';

package/front_end/panels/timeline/TimelineTreeView.ts

@@ -12,9 +12,9 @@ import * as DataGrid from '../../ui/legacy/components/data_grid/data_grid.js';
 import * as Components from '../../ui/legacy/components/utils/utils.js';
 import * as UI from '../../ui/legacy/legacy.js';
 
-import type {PerformanceModel} from './PerformanceModel.js';
+import {type PerformanceModel} from './PerformanceModel.js';
 import {TimelineRegExp} from './TimelineFilters.js';
-import type {TimelineSelection} from './TimelinePanel.js';
+import {type TimelineSelection} from './TimelinePanel.js';
 import {TimelineUIUtils} from './TimelineUIUtils.js';
 
 const UIStrings = {

package/front_end/panels/timeline/UIDevtoolsController.ts

@@ -30,8 +30,7 @@
 
 import type * as SDK from '../../core/sdk/sdk.js';
 
-import type {Client} from './TimelineController.js';
-import {TimelineController} from './TimelineController.js';
+import {TimelineController, type Client} from './TimelineController.js';
 import {TimelineUIUtils} from './TimelineUIUtils.js';
 import {UIDevtoolsUtils} from './UIDevtoolsUtils.js';
 

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

@@ -6,8 +6,15 @@ import * as Host from '../../../core/host/host.js';
 import type * as LitHtml from '../../../ui/lit-html/lit-html.js';
 import * as i18n from '../../../core/i18n/i18n.js';
 
-import type {Event, Marker, Timebox, WebVitalsTimeline} from './WebVitalsTimeline.js';
-import {assertInstanceOf, LONG_TASK_THRESHOLD, MarkerType} from './WebVitalsTimeline.js';
+import {
+  assertInstanceOf,
+  LONG_TASK_THRESHOLD,
+  MarkerType,
+  type Event,
+  type Marker,
+  type Timebox,
+  type WebVitalsTimeline,
+} from './WebVitalsTimeline.js';
 
 type GetMarkerTypeCallback = (event: Event) => MarkerType;
 type GetMarkerOverlayCallback = (marker: Marker) => LitHtml.TemplateResult;

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

@@ -11,7 +11,7 @@ import * as LitHtml from '../../../ui/lit-html/lit-html.js';
 const coordinator = Coordinator.RenderCoordinator.RenderCoordinator.instance();
 
 import {WebVitalsEventLane, WebVitalsTimeboxLane} from './WebVitalsLane.js';
-import type {WebVitalsTooltip} from './WebVitalsTooltip.js';
+import {type WebVitalsTooltip} from './WebVitalsTooltip.js';
 
 const UIStrings = {
   /**

package/front_end/panels/web_audio/graph_visualizer/EdgeView.ts

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import type {NodeParamConnectionData, NodesConnectionData} from './GraphStyle.js';
+import {type NodeParamConnectionData, type NodesConnectionData} from './GraphStyle.js';
 import {generateInputPortId, generateOutputPortId, generateParamPortId} from './NodeView.js';
 
 // A class that represents an edge of a graph, including node-to-node connection,

package/front_end/panels/web_audio/graph_visualizer/GraphView.ts

@@ -6,9 +6,15 @@ import * as Common from '../../../core/common/common.js';
 import * as Platform from '../../../core/platform/platform.js';
 
 import {EdgeTypes, EdgeView, generateEdgePortIdsByData} from './EdgeView.js';
-import type {
-  NodeCreationData, NodeParamConnectionData, NodeParamDisconnectionData, NodesConnectionData, NodesDisconnectionData,
-  NodesDisconnectionDataWithDestination, ParamCreationData} from './GraphStyle.js';
+import {
+  type NodeCreationData,
+  type NodeParamConnectionData,
+  type NodeParamDisconnectionData,
+  type NodesConnectionData,
+  type NodesDisconnectionData,
+  type NodesDisconnectionDataWithDestination,
+  type ParamCreationData,
+} from './GraphStyle.js';
 import {NodeLabelGenerator, NodeView} from './NodeView.js';
 
 // A class that tracks all the nodes and edges of an audio graph.

package/front_end/panels/web_audio/graph_visualizer/NodeRendererUtility.ts

@@ -2,7 +2,6 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
-import type {Point, Size} from './GraphStyle.js';
 import {
   AudioParamRadius,
   InputPortRadius,
@@ -10,6 +9,8 @@ import {
   TotalInputPortHeight,
   TotalOutputPortHeight,
   TotalParamPortHeight,
+  type Point,
+  type Size,
 } from './GraphStyle.js';
 
 /**

package/front_end/panels/web_audio/graph_visualizer/NodeView.ts

@@ -4,7 +4,6 @@
 
 import * as UI from '../../../ui/legacy/legacy.js';
 
-import type {NodeCreationData, NodeLayout, Port} from './GraphStyle.js';
 import {
   BottomPaddingWithoutParam,
   BottomPaddingWithParam,
@@ -17,6 +16,9 @@ import {
   TotalInputPortHeight,
   TotalOutputPortHeight,
   TotalParamPortHeight,
+  type NodeCreationData,
+  type NodeLayout,
+  type Port,
 } from './GraphStyle.js';
 import {calculateInputPortXY, calculateOutputPortXY, calculateParamPortXY} from './NodeRendererUtility.js';
 

package/front_end/third_party/.clang-format

@@ -1 +1 @@
-DisableFormat: true
+DisableFormat: true

package/front_end/third_party/i18n/localized-string-set.ts

@@ -2,7 +2,7 @@
 // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
 // Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
 
-import type {LocalizedMessages, UIStrings} from './i18n-impl.js';
+import {type LocalizedMessages, type UIStrings} from './i18n-impl.js';
 
 import * as IntlMessageFormat from '../intl-messageformat/intl-messageformat.js';
 

package/front_end/ui/components/buttons/Button.ts

@@ -17,7 +17,16 @@ declare global {
 export const enum Variant {
   PRIMARY = 'primary',
   SECONDARY = 'secondary',
+  // This is a bit confusing: the TOOLBAR variant is the historical variant
+  // that has been used when adding toolbar icons to legacy DevTools toolbars.
+  // In July 2022 we began work on the new unified toolbar, which will first be
+  // built for Performance Insights and then rolled out across the panels. Once
+  // that work is done, we can remove these two variants and revert back to
+  // having one.
+  // We need to differentiate because the unified toolbar icons are 16px in
+  // size, not 18px (which the toolbar small icons are).
   TOOLBAR = 'toolbar',
+  UNIFIED_TOOLBAR_2022 = 'unified_toolbar_2022',
   ROUND = 'round',
 }
 
@@ -60,6 +69,12 @@ export type ButtonData = {
   type?: ButtonType,
   value?: string,
   title?: string,
+}|{
+  variant: Variant.UNIFIED_TOOLBAR_2022,
+  iconUrl: string,
+  disabled?: boolean,
+  active?: boolean,
+  title?: string,
 };
 
 interface ButtonElementInternals extends ElementInternals {
@@ -100,10 +115,19 @@ export class Button extends HTMLElement {
   set data(data: ButtonData) {
     this.#props.variant = data.variant;
     this.#props.iconUrl = data.iconUrl;
-    this.#props.size = data.size || Size.MEDIUM;
+    this.#props.size = Size.MEDIUM;
+
+    if ('size' in data && data.size) {
+      this.#props.size = data.size;
+    }
+
     this.#props.active = Boolean(data.active);
-    this.#props.spinner = Boolean(data.spinner);
-    this.#props.type = data.type || 'button';
+    this.#props.spinner = Boolean('spinner' in data ? data.spinner : false);
+
+    this.#props.type = 'button';
+    if ('type' in data && data.type) {
+      this.#props.type = data.type;
+    }
     this.#setDisabledProperty(data.disabled || false);
     this.#props.title = data.title;
     void ComponentHelpers.ScheduledRender.scheduleRender(this, this.#boundRender);
@@ -192,7 +216,7 @@ export class Button extends HTMLElement {
     if (!this.#props.variant) {
       throw new Error('Button requires a variant to be defined');
     }
-    if (this.#props.variant === Variant.TOOLBAR) {
+    if (this.#props.variant === Variant.TOOLBAR || this.#props.variant === Variant.UNIFIED_TOOLBAR_2022) {
       if (!this.#props.iconUrl) {
         throw new Error('Toolbar button requires an icon');
       }
@@ -211,7 +235,8 @@ export class Button extends HTMLElement {
     const classes = {
       primary: this.#props.variant === Variant.PRIMARY,
       secondary: this.#props.variant === Variant.SECONDARY,
-      toolbar: this.#props.variant === Variant.TOOLBAR,
+      toolbar: this.#props.variant === Variant.TOOLBAR || this.#props.variant === Variant.UNIFIED_TOOLBAR_2022,
+      'unified-toolbar-2022': this.#props.variant === Variant.UNIFIED_TOOLBAR_2022,
       round: this.#props.variant === Variant.ROUND,
       'text-with-icon': Boolean(this.#props.iconUrl) && !this.#isEmpty,
       'only-icon': Boolean(this.#props.iconUrl) && this.#isEmpty,

package/front_end/ui/components/buttons/button.css

@@ -85,6 +85,15 @@ button.toolbar.small {
   width: 18px;
 }
 
+button.unified-toolbar-2022 {
+  /* These buttons are always 16px in dimension, and don't have different
+   * sizes, hence the lack of a size class above and the use of important! to
+   * ensure no sizing classes accidentally interfere.
+   */
+  height: 16px !important; /* stylelint-disable-line declaration-no-important */
+  width: 16px !important;/* stylelint-disable-line declaration-no-important */
+}
+
 button.round.small {
   height: 24px;
   width: 24px;
@@ -199,6 +208,13 @@ button.round devtools-icon {
   --icon-color: var(--color-text-secondary);
 }
 
+button.unified-toolbar-2022 devtools-icon {
+  width: 16px;
+  height: 16px;
+
+  --icon-color: var(--color-text-secondary);
+}
+
 button.primary devtools-icon {
   --icon-color: var(--color-background);
 }

package/front_end/ui/components/data_grid/DataGrid.ts

@@ -15,7 +15,7 @@ import {BodyCellFocusedEvent, ColumnHeaderClickEvent, ContextMenuHeaderResetClic
 const coordinator = Coordinator.RenderCoordinator.RenderCoordinator.instance();
 
 import {addColumnVisibilityCheckboxes, addSortableColumnItems} from './DataGridContextMenuUtils.js';
-import type {CellPosition, Column, Row, SortState} from './DataGridUtils.js';
+
 import {
   calculateColumnWidthPercentageFromWeighting,
   calculateFirstFocusableCell,
@@ -24,6 +24,10 @@ import {
   handleArrowKeyNavigation,
   renderCellValue,
   SortDirection,
+  type CellPosition,
+  type Column,
+  type Row,
+  type SortState,
 } from './DataGridUtils.js';
 
 import * as i18n from '../../../core/i18n/i18n.js';

package/front_end/ui/components/data_grid/DataGridContextMenuUtils.ts

@@ -3,9 +3,9 @@
 // found in the LICENSE file.
 import type * as UI from '../../legacy/legacy.js';
 
-import type {DataGrid} from './DataGrid.js';
+import {type DataGrid} from './DataGrid.js';
 import {ContextMenuColumnSortClickEvent} from './DataGridEvents.js';
-import type {Column} from './DataGridUtils.js';
+import {type Column} from './DataGridUtils.js';
 
 function toggleColumnVisibility(dataGrid: DataGrid, column: Column): void {
   const newVisibility = !column.visible;

package/front_end/ui/components/data_grid/DataGridController.ts

@@ -5,11 +5,18 @@
 import * as LitHtml from '../../../ui/lit-html/lit-html.js';
 import * as ComponentHelpers from '../helpers/helpers.js';
 import type * as TextUtils from '../../../models/text_utils/text_utils.js';
-import type {SortState, Column, Row} from './DataGridUtils.js';
-import {SortDirection, getRowEntryForColumnId, getStringifiedCellValues} from './DataGridUtils.js';
-import type {DataGridData, DataGridContextMenusConfiguration} from './DataGrid.js';
-import type {ContextMenuColumnSortClickEvent, ColumnHeaderClickEvent} from './DataGridEvents.js';
-import {DataGrid} from './DataGrid.js';
+
+import {
+  SortDirection,
+  getRowEntryForColumnId,
+  getStringifiedCellValues,
+  type SortState,
+  type Column,
+  type Row,
+} from './DataGridUtils.js';
+
+import {type ContextMenuColumnSortClickEvent, type ColumnHeaderClickEvent} from './DataGridEvents.js';
+import {DataGrid, type DataGridData, type DataGridContextMenusConfiguration} from './DataGrid.js';
 import dataGridControllerStyles from './dataGridController.css.js';
 
 export interface DataGridControllerData {

package/front_end/ui/components/data_grid/DataGridControllerIntegrator.ts

@@ -3,8 +3,7 @@
 // found in the LICENSE file.
 
 import * as UI from '../../legacy/legacy.js';
-import {DataGridController} from './DataGridController.js';
-import type {DataGridControllerData} from './DataGridController.js';
+import {DataGridController, type DataGridControllerData} from './DataGridController.js';
 
 export class DataGridControllerIntegrator extends UI.Widget.VBox {
   readonly dataGrid: DataGridController;

package/front_end/ui/components/data_grid/DataGridEvents.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2021 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
-import type {Cell, Column, Row} from './DataGridUtils.js';
+import {type Cell, type Column, type Row} from './DataGridUtils.js';
 
 export class ColumnHeaderClickEvent extends Event {
   static readonly eventName = 'columnheaderclick';

package/front_end/ui/components/data_grid/DataGridRenderers.ts

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 import * as LitHtml from '../../../ui/lit-html/lit-html.js';
-import type {CellValue} from './DataGridUtils.js';
+import {type CellValue} from './DataGridUtils.js';
 
 export const primitiveRenderer = (value: CellValue): LitHtml.TemplateResult => {
   return LitHtml.html`${value}`;

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

@@ -0,0 +1,112 @@
+# 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
+
+A component should be given a `static readonly litTagName` property, which defines its name:
+
+```ts
+// ElementBreadcrumbs.ts
+export class ElementBreadcrumbs extends HTMLElement {
+  static readonly litTagName = LitHtml.literal`devtools-elements-breadcrumbs`;
+}
+```
+
+> Remember that all custom elements **must** contain a hyphen. Prefer `devtools-` as the prefix by default.
+
+We then use the `ComponentHelpers` module (`front_end/ui/components/helpers`) to define the component and register it with the browser:
+
+```ts
+ComponentHelpers.CustomElements.defineComponent('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 have a custom ESLint rule that ensures that the tag name is used consistently in all the locations where it is required.
+
+## 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 {
+  static readonly litTagName = LitHtml.literal`devtools-elements-breadcrumbs`;
+  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(LitHtml.html``, this.#shadow, {host: this});
+```
+
+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. First, bind the `#render` method of your component, to ensure it's always bound to the component instance's scope:
+
+```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);
+}
+```
+
+Then, rather than call `this.#render()` directly, you instead call the scheduler:
+
+```ts
+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".

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

@@ -0,0 +1,19 @@
+# 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)
+
+## 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/button/basic.html

@@ -35,6 +35,15 @@
         padding: 0px 5px;
         height: 23px;
       }
+      #unified-toolbar {
+        background-color: var(--color-background);
+        display: flex;
+        flex-direction: row;
+        align-items: center;
+        border-bottom: 1px solid var(--color-details-hairline);
+        padding: 5px 6px;
+        height: 26px;
+      }
       .separator {
         background-color: var(--color-details-hairline);
         width: 1px;
@@ -50,6 +59,8 @@
     </div>
     <div id="small-toolbar">
     </div>
+    <div id="unified-toolbar">
+    </div>
     <form onsubmit="event.preventDefault(); alert('submitted');" id="form">
       <input name="field" placeholder="Enter smth" />
     </form>

package/front_end/ui/components/docs/button/basic.ts

@@ -299,6 +299,13 @@ for (let i = 0; i < 6; i++) {
   }
 }
 
+const unifiedToolbarButton = new Buttons.Button.Button();
+unifiedToolbarButton.data = {
+  variant: Buttons.Button.Variant.UNIFIED_TOOLBAR_2022,
+  iconUrl: testIcon,
+};
+document.querySelector('#unified-toolbar')?.appendChild(unifiedToolbarButton);
+
 // Submit Button
 const submitButton = new Buttons.Button.Button();
 submitButton.data = {

package/front_end/ui/components/icon_button/IconButton.ts

@@ -5,11 +5,9 @@
 import * as ComponentHelpers from '../../components/helpers/helpers.js';
 import * as LitHtml from '../../lit-html/lit-html.js';
 
-import {Icon} from './Icon.js';
+import {Icon, type IconData} from './Icon.js';
 import iconButtonStyles from './iconButton.css.js';
 
-import type {IconData} from './Icon.js';
-
 export interface IconWithTextData {
   iconName: string;
   iconColor?: string;