chrome-devtools-frontend 1.0.1732697 → 1.0.1735750
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/rules/tests/test-view-and-presenter-isolation.md +4 -4
- package/.agents/rules/ui-and-widgets/ui-declarative-tree-and-prompt-patterns.md +61 -0
- package/.agents/rules/ui-and-widgets/ui-lit-declarative-templates-and-directives.md +11 -7
- package/.agents/rules/ui-and-widgets/ui-modern-component-and-encapsulation-standards.md +13 -4
- package/.agents/rules/ui-and-widgets/ui-pure-view-and-presenter-separation.md +31 -2
- package/.agents/rules/ui-and-widgets/ui-reactive-widget-update-lifecycle.md +23 -4
- package/.agents/rules/ui-and-widgets/ui-widget-dom-and-listener-lifecycle.md +34 -3
- package/.agents/skills/code-review/SKILL.md +26 -0
- package/.agents/skills/ui-eng-vision-local-lit-renderer/SKILL.md +27 -1
- package/.agents/skills/ui-eng-vision-orchestrator/SKILL.md +100 -0
- package/.agents/skills/ui-eng-vision-test-scaffolder/SKILL.md +16 -0
- package/.agents/skills/ui-eng-vision-widget-promoter/SKILL.md +13 -2
- package/.agents/skills/ui-widgets/SKILL.md +25 -25
- package/DIR_METADATA +2 -1
- package/docs/ui_engineering.md +24 -0
- package/front_end/core/host/AidaClientTypes.ts +5 -1
- package/front_end/core/host/AidaGcaTranslation.ts +29 -1
- package/front_end/core/platform/browser/HostRuntime.ts +5 -1
- package/front_end/core/sdk/CPUThrottlingManager.ts +3 -0
- package/front_end/core/sdk/EnhancedTracesParser.ts +8 -4
- package/front_end/core/sdk/PreloadingModel.ts +30 -13
- package/front_end/design_system_tokens.css +5 -0
- package/front_end/entrypoints/formatter_worker/ScopeParser.ts +4 -2
- package/front_end/generated/InspectorBackendCommands.ts +5 -5
- package/front_end/generated/SupportedCSSProperties.ts +6 -0
- package/front_end/generated/protocol.ts +30 -7
- package/front_end/models/ai_assistance/AiAgent2.ts +4 -1
- package/front_end/models/ai_assistance/AiConversation.ts +1 -0
- package/front_end/models/ai_assistance/ChangeManager.ts +3 -1
- package/front_end/models/ai_assistance/DOMHelpers.ts +114 -2
- package/front_end/models/ai_assistance/ExtensionScope.ts +22 -24
- package/front_end/models/ai_assistance/agents/AiAgent.ts +65 -6
- package/front_end/models/ai_assistance/agents/StylingAgent.snapshot.txt +2 -1
- package/front_end/models/ai_assistance/skills/lighthouse.md +1 -1
- package/front_end/models/comment_manager/CD4ABridge.ts +12 -2
- package/front_end/models/comment_manager/CommentManager.ts +24 -4
- package/front_end/models/javascript_metadata/NativeFunctions.ts +40 -0
- package/front_end/models/project_settings/ProjectSettingsModel.ts +1 -1
- package/front_end/models/trace/insights/DuplicatedJavaScript.ts +1 -2
- package/front_end/models/trace/types/TraceEvents.ts +21 -22
- package/front_end/models/web_mcp/WebMCPModel.ts +1 -1
- package/front_end/panels/ai_assistance/AiAssistancePanel.ts +35 -17
- package/front_end/panels/ai_assistance/components/ChatMessage.ts +9 -1
- package/front_end/panels/ai_assistance/components/chatMessage.css +1 -1
- package/front_end/panels/ai_assistance/components/exploreWidget.css +1 -1
- package/front_end/panels/application/backgroundServiceView.css +2 -2
- package/front_end/panels/application/deviceBoundSessionsView.css +1 -1
- package/front_end/panels/application/frameDetailsReportView.css +0 -4
- package/front_end/panels/application/preloading/components/PreloadingString.ts +7 -0
- package/front_end/panels/application/resourcesPanel.css +0 -4
- package/front_end/panels/browser_debugger/XHRBreakpointsSidebarPane.ts +346 -286
- package/front_end/panels/comments/CommentsPane.ts +12 -7
- package/front_end/panels/comments/commentsPane.css +16 -2
- package/front_end/panels/common/CommentsOverlayWidget.ts +17 -11
- package/front_end/panels/common/CommentsStatusBarPill.ts +12 -5
- package/front_end/panels/common/commentsOverlay.css +7 -1
- package/front_end/panels/common/commentsStatusBarPill.css +30 -0
- package/front_end/panels/console/consoleView.css +1 -1
- package/front_end/panels/elements/DOMTreeWidget.ts +28 -9
- package/front_end/panels/elements/components/cssPropertyDocsView.css +1 -1
- package/front_end/panels/elements/components/elementsBreadcrumbs.css +2 -2
- package/front_end/panels/elements/components/stylePropertyEditor.css +1 -5
- package/front_end/panels/elements/domTreeWidget.css +6 -1
- package/front_end/panels/elements/layoutPane.css +2 -2
- package/front_end/panels/elements/metricsSidebarPane.css +1 -1
- package/front_end/panels/elements/platformFontsWidget.css +1 -1
- package/front_end/panels/elements/stylesSidebarPane.css +3 -12
- package/front_end/panels/emulation/deviceModeView.css +1 -1
- package/front_end/panels/explain/components/consoleInsight.css +3 -3
- package/front_end/panels/issues/issuesTree.css +4 -28
- package/front_end/panels/lighthouse/LighthousePanel.ts +16 -1
- package/front_end/panels/linear_memory_inspector/components/LinearMemoryHighlightChipList.ts +10 -6
- package/front_end/panels/linear_memory_inspector/components/linearMemoryHighlightChipList.css +1 -26
- package/front_end/panels/media/TickingFlameChart.ts +20 -3
- package/front_end/panels/media/playerListView.css +3 -4
- package/front_end/panels/media/playerMessagesView.css +1 -1
- package/front_end/panels/mobile_throttling/ThrottlingSettingsTab.ts +24 -5
- package/front_end/panels/network/networkTimingTable.css +1 -5
- package/front_end/panels/profiler/ProfileFlameChartDataProvider.ts +114 -18
- package/front_end/panels/protocol_monitor/JSONEditor.css +1 -1
- package/front_end/panels/recorder/recorderPanel.css +3 -3
- package/front_end/panels/recorder/stepEditor.css +1 -1
- package/front_end/panels/search/searchResultsPane.css +1 -1
- package/front_end/panels/security/mainView.css +1 -1
- package/front_end/panels/sensors/locationsSettingsTab.css +1 -1
- package/front_end/panels/settings/AISettingsTab.ts +1 -0
- package/front_end/panels/settings/EditFileSystemView.ts +159 -104
- package/front_end/panels/settings/editFileSystemView.css +30 -4
- package/front_end/panels/sources/CallStackSidebarPane.ts +339 -221
- package/front_end/panels/sources/NavigatorView.ts +208 -50
- package/front_end/panels/sources/ThreadsSidebarPane.ts +8 -4
- package/front_end/panels/sources/breakpointsView.css +1 -1
- package/front_end/panels/sources/callStackSidebarPane.css +4 -0
- package/front_end/panels/sources/components/HeadersView.css +2 -2
- package/front_end/panels/timeline/CountersGraph.ts +0 -4
- package/front_end/panels/timeline/TimelinePanel.ts +37 -13
- package/front_end/panels/timeline/TimelineUIUtils.ts +1 -1
- package/front_end/panels/timeline/components/DetailsView.ts +2 -1
- package/front_end/panels/timeline/components/metricCard.css +2 -2
- package/front_end/panels/timeline/timelineFlameChartView.css +1 -1
- package/front_end/panels/timeline/timelineMiniMap.css +1 -1
- package/front_end/panels/web_audio/WebAudioModel.ts +14 -5
- package/front_end/panels/web_audio/WebAudioView.ts +34 -1
- package/front_end/panels/web_audio/webAudio.css +17 -3
- package/front_end/panels/webauthn/WebauthnPane.ts +13 -14
- package/front_end/panels/webauthn/webauthnPane.css +3 -5
- package/front_end/panels/whats_new/ReleaseNoteText.ts +19 -1
- package/front_end/panels/whats_new/ReleaseNoteView.ts +15 -1
- package/front_end/panels/whats_new/releaseNoteView.css +49 -0
- package/front_end/third_party/chromium/README.chromium +1 -1
- package/front_end/third_party/puppeteer-replay/README.chromium +9 -1
- package/front_end/third_party/puppeteer-replay/package/lib/main.d.ts +2 -2
- package/front_end/ui/comments/CommentOverlayManager.ts +34 -18
- package/front_end/ui/components/icon_button/FileSourceIcon.ts +6 -0
- package/front_end/ui/components/markdown_view/codeBlock.css +1 -1
- package/front_end/ui/components/markdown_view/markdownView.css +1 -5
- package/front_end/ui/components/panel_introduction_steps/panelIntroductionSteps.css +7 -5
- package/front_end/ui/components/suggestion_input/suggestionInput.css +2 -2
- package/front_end/ui/components/switch/switch.css +2 -1
- package/front_end/ui/components/text_editor/AiCodeGenerationTeaser.ts +14 -2
- package/front_end/ui/legacy/DockController.ts +16 -3
- package/front_end/ui/legacy/TabbedPane.ts +1 -1
- package/front_end/ui/legacy/Treeoutline.ts +2 -2
- package/front_end/ui/legacy/components/inline_editor/bezierEditor.css +13 -5
- package/front_end/ui/legacy/components/perf_ui/chartViewport.css +2 -2
- package/front_end/ui/legacy/components/perf_ui/filmStripView.css +2 -2
- package/front_end/ui/legacy/components/quick_open/filteredListWidget.css +5 -4
- package/front_end/ui/legacy/components/source_frame/imageView.css +1 -1
- package/front_end/ui/legacy/inspectorCommon.css +3 -2
- package/front_end/ui/legacy/listWidget.css +1 -19
- package/front_end/ui/legacy/reportView.css +1 -1
- package/front_end/ui/legacy/searchableView.css +2 -1
- package/front_end/ui/legacy/suggestBox.css +2 -1
- package/front_end/ui/legacy/tabbedPane.css +1 -1
- package/front_end/ui/visual_logging/KnownContextValues.ts +4 -0
- package/package.json +1 -1
|
@@ -4,11 +4,11 @@ rubric: testing
|
|
|
4
4
|
severity: should_fix
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
**Rule.** Test presenters via createViewFunctionStub and test pure view functions directly without piercing internal DOM structures
|
|
8
|
-
- **Look for**: Presenter tests instantiating full DOM trees and querying shadow/child DOM selectors to simulate clicks when the widget accepts a `view` function,
|
|
9
|
-
- **Do not flag**: Legacy widgets that have not yet separated their template rendering into a standalone `DEFAULT_VIEW` function. Pre-existing mounted widget tests in `*.test.ts` when migrating a widget to `DEFAULT_VIEW` (keep existing end-to-end presenter + `DEFAULT_VIEW` + child-widget wiring tests intact; `createViewFunctionStub` tests may be added for new presenter logic, not used to delete existing DOM wiring coverage).
|
|
7
|
+
**Rule.** Test presenters via createViewFunctionStub, encapsulate legacy DOM/tree inspection in test helpers, and test pure view functions directly without piercing internal DOM structures
|
|
8
|
+
- **Look for**: Presenter tests instantiating full DOM trees and querying shadow/child DOM selectors to simulate clicks when the widget accepts a `view` function, view tests instantiating full presenters just to test template markup, or pre-migration unit test suites added for a legacy widget (`UI.TreeOutline`, `DataGrid`, `UI.ListControl`, `UI.ListWidget`) that scatter direct internal structure queries (`.scriptsTree`, `.rootElement()`, internal shadow-DOM selectors) across individual `it()` blocks instead of isolating them in small local test helpers (`dumpTree()`, `findTreeItem()`, `activateRow()`), or that omit `assertScreenshot(...)` visual baselines when the underlying legacy widget implementation is scheduled to be replaced.
|
|
9
|
+
- **Do not flag**: Legacy widgets that have not yet separated their template rendering into a standalone `DEFAULT_VIEW` function. Pre-existing mounted widget tests in `*.test.ts` when migrating a widget to `DEFAULT_VIEW` (keep existing end-to-end presenter + `DEFAULT_VIEW` + child-widget wiring tests intact; `createViewFunctionStub` tests may be added for new presenter logic, not used to delete existing DOM wiring coverage). Isolated presenter unit tests using `createViewFunctionStub` do not require screenshot assertions.
|
|
10
10
|
|
|
11
|
-
**Why.** In DevTools' MVP (`UI.Widget` + `DEFAULT_VIEW`) architecture, presenter tests should follow the view stubbing conventions documented in [`docs/ui_engineering.md`](../../../docs/ui_engineering.md) by stubbing the view function with `createViewFunctionStub(Presenter)` and asserting on `await view.nextInput`, while view rendering tests should invoke `DEFAULT_VIEW(input, output, target)` directly or use screenshot assertions.
|
|
11
|
+
**Why.** In DevTools' MVP (`UI.Widget` + `DEFAULT_VIEW`) architecture, presenter tests should follow the view stubbing conventions documented in [`docs/ui_engineering.md`](../../../docs/ui_engineering.md) by stubbing the view function with `createViewFunctionStub(Presenter)` and asserting on `await view.nextInput`, while view rendering tests should invoke `DEFAULT_VIEW(input, output, target)` directly or use screenshot assertions. When scaffolding tests ahead of replacing legacy widgets like `TreeOutline` or `ListControl`, routing DOM inspection through small local test helpers ensures the subsequent component swap only updates the helper definitions rather than dozens of tests, and `assertScreenshot` tests ensure visual parity independent of internal widget DOM changes.
|
|
12
12
|
|
|
13
13
|
## Examples
|
|
14
14
|
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: devtools/ui-and-widgets/ui-declarative-tree-and-prompt-patterns
|
|
3
|
+
rubric: design
|
|
4
|
+
severity: should_fix
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
**Rule.** Use declarative <devtools-tree> and persistent <devtools-prompt ?editing> (wrapped in a child widget inside tree rows) without widening ui/legacy Treeoutline contracts
|
|
8
|
+
- **Look for**: Panel or widget migrations modifying `front_end/ui/legacy/Treeoutline.ts` (`TreeViewElement` or `TreeViewTreeElement`) to accommodate legacy `TreeOutline` patterns—such as exporting `TreeViewTreeElement`, overriding `title` or `titleAsText()`, adding custom `.leading-icons` or `.trailing-icons` cloning hooks, or renaming `getInternalTreeOutlineForTest()` or `flushPendingUpdatesForTesting()` into public APIs—or leaving public `TreeOutline` getters (such as `get scriptsTree()`) on migrated presenters instead of rendering icons, labels, tooltips, and trailing actions inline inside `<li role="treeitem">` within `<devtools-tree .template=${html`<ul role="tree">...</ul>`}>` (`import '../../ui/kit/kit.js'`) and driving state via `?selected`, `?open`, `@select`, and `@expand`; duplicating `class="tree-element-title"` on inner `<span>` elements inside `<li role="treeitem">` (`TreeViewTreeElement.titleElement` already has `.tree-element-title`, causing rules like `.is-ignore-listed .tree-element-title { opacity: 40% }` to compound), or rendering an empty trailing-icons container instead of `nothing` when a row has no trailing actions; imperatively swapping `<devtools-prompt>` or `UI.InplaceEditor.startEditing` elements in and out of the DOM, subclassing `TreeElement` just to host prompt titles, keeping `UI.UIUtils.markBeingEdited` or `isBeingEdited` DOM markers on fully declarative widgets instead of presenter editing state, or setting a duplicate `aria-label` on an inner `<devtools-prompt>` when the enclosing `<li role="treeitem" aria-label=...>` already provides the accessible name; rendering `<devtools-prompt ?editing=${...}>` directly inside a `<devtools-tree>` `<li role="treeitem">` template instead of hosting it inside a small child `UI.Widget` via `${widget(RowPromptWidget, {...})}` (`<devtools-tree>` clones `<template>` nodes into shadow DOM and `TreeViewTreeElement.refresh()` re-clones and refocuses the `<li>` on any light-DOM mutation, immediately blurring and cancelling the active prompt when `?editing` toggles); or custom elements inside `<devtools-tree>` rows whose state updates via JS properties (`.data`) without overriding `cloneNode(deep)` to copy that state and reflecting dynamic state via a DOM attribute (such as `data-badge=${...}`) so `<devtools-tree>`'s `MutationObserver` refreshes the shadow clone.
|
|
9
|
+
- **Do not flag**: Unit tests or `front_end/legacy_test_runner/**` helpers calling `getInternalTreeOutlineForTest()` or `flushPendingUpdatesForTesting()` on `<devtools-tree>` for test inspection or synchronization. Explicitly scoped intermediate CLs (`Bug: <id>`) in a multi-CL migration that introduce persistent `<devtools-prompt ?editing>` on plain `UI.TreeOutline.TreeElement` rows (temporarily retaining `UI.UIUtils.markBeingEdited`) ahead of replacing `TreeOutline` with `<devtools-tree>`.
|
|
10
|
+
|
|
11
|
+
**Why.** Preserving `<devtools-tree>`'s declarative contract (`?selected`, `?open`, `@select`, `@expand`) prevents leaking legacy imperative `TreeOutline` internals across module boundaries. Keeping `<devtools-prompt ?editing>` persistently mounted in the template avoids disruptive DOM swapping and focus loss, while isolating editable prompts inside a child `UI.Widget` within `<devtools-tree>` prevents `MutationObserver` light-DOM re-clones from refocusing the `<li>` and blurring the active input. Omitting redundant `aria-label`s on inner prompts preserves accessible tree names without duplicate screen-reader announcements.
|
|
12
|
+
|
|
13
|
+
## Examples
|
|
14
|
+
|
|
15
|
+
Bad:
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
// Exposing legacy TreeOutline getters and rendering prompt directly in tree row
|
|
19
|
+
export class MyTreeView extends UI.Widget.VBox {
|
|
20
|
+
get scriptsTree(): UI.TreeOutline.TreeOutline {
|
|
21
|
+
return this.#tree;
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
const DEFAULT_VIEW = (input: ViewInput, _output: undefined, target: HTMLElement): void => {
|
|
26
|
+
render(html`
|
|
27
|
+
<devtools-tree .template=${html`
|
|
28
|
+
<ul role="tree">
|
|
29
|
+
<li role="treeitem" aria-label=${input.label}>
|
|
30
|
+
<span class="tree-element-title">
|
|
31
|
+
<devtools-prompt
|
|
32
|
+
aria-label=${input.label}
|
|
33
|
+
value=${input.title}
|
|
34
|
+
?editing=${input.isEditing}>
|
|
35
|
+
${input.title}
|
|
36
|
+
</devtools-prompt>
|
|
37
|
+
</span>
|
|
38
|
+
</li>
|
|
39
|
+
</ul>
|
|
40
|
+
`}></devtools-tree>
|
|
41
|
+
`, target);
|
|
42
|
+
};
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Good:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
const {widget} = UI.Widget;
|
|
49
|
+
|
|
50
|
+
const DEFAULT_VIEW = (input: ViewInput, _output: undefined, target: HTMLElement): void => {
|
|
51
|
+
render(html`
|
|
52
|
+
<devtools-tree autofocus .template=${html`
|
|
53
|
+
<ul role="tree">
|
|
54
|
+
<li role="treeitem" ?selected=${input.isSelected} ?open=${input.isOpen} aria-label=${input.label}>
|
|
55
|
+
${widget(RowPromptWidget, {title: input.title, isEditing: input.isEditing})}
|
|
56
|
+
</li>
|
|
57
|
+
</ul>
|
|
58
|
+
`}></devtools-tree>
|
|
59
|
+
`, target);
|
|
60
|
+
};
|
|
61
|
+
```
|
|
@@ -4,20 +4,22 @@ rubric: design
|
|
|
4
4
|
severity: should_fix
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
**Rule.** Use Lit.nothing, repeat with keys, classMap/styleMap, and ifDefined in single-pass declarative templates instead of imperative DOM mutations
|
|
8
|
-
- **Look for**: Ternary branches returning `''` or `undefined` in `html` templates instead of `Lit.nothing`, unkeyed `.map()` on dynamic stateful lists instead of `repeat()`, `ifDefined` omissions on optional attributes, multiple `Lit.render()` calls mutating the same container, `Lit.*` namespace calls instead of direct `{Directives, html, nothing, render}` imports from `ui/lit/lit.js`, `useShadowDom: true` in new or migrated `UI.Widget` constructors instead of `useShadowDom: 'pure'` (which makes `this.contentElement` the `ShadowRoot` directly without an extra inner `<div class="widget">` wrapper), `super(..., {classes: [...]})` / `super(..., {jslog: ...})` in `UI.Widget` constructors instead of passing `{container: {classes: [...], attributes: {jslog: ...}}}` as the third argument to every `render(template, target, {container: {classes: [...]}})` branch in the view function (with `useShadowDom: 'pure'` when shadow DOM is used), imperative `element.classList.add(...)`, `element.setAttribute(...)`, or `UI.ARIAUtils.*(element)` calls on a container element (`this.contentElement`, `this.element`, or a detached `HTMLDivElement`) that is rendered via `render(template, element)` instead of passing `{container: {classes: [...], attributes: {...}}}` as the third argument to `render(...)`, or `@SomeEvent` on `<devtools-widget>` when the child class does not use `eventMixin` on `UI.Widget` (no `dispatchDOMEvent`), when the listener is placed on an ancestor element (the `CustomEvent` does not bubble), or when the handler reads `event.data` instead of `event.detail`.
|
|
9
|
-
- **Do not flag**: Static arrays of primitive labels where item identity never reorders. Omitting Lit's `live()` directive on `<devtools-checkbox>` (`UI.UIUtils.CheckboxLabel`) `.checked` bindings (`live()` breaks `CheckboxLabel`'s host `checked` attribute synchronization when toggled externally), listening to `ObjectWrapper` events via Lit `@SomeEvent=${handler}` bindings on a `<devtools-widget>` whose class uses `Common.ObjectWrapper.eventMixin` on `UI.Widget` (`eventMixin` dispatches `new CustomEvent(type, {detail: data})` on `widget.element`, and Lit preserves the case of `@SomeEvent` from the template string),
|
|
7
|
+
**Rule.** Use Lit.nothing, repeat with keys, classMap/styleMap, ?hidden, autofocus, and ifDefined in single-pass declarative templates instead of imperative DOM mutations
|
|
8
|
+
- **Look for**: Ternary branches returning `''` or `undefined` in `html` templates instead of `Lit.nothing`, unkeyed `.map()` on dynamic stateful lists instead of `repeat()`, `ifDefined` omissions on optional attributes, multiple `Lit.render()` calls mutating the same container, `Lit.*` namespace calls instead of direct `{Directives, html, nothing, render}` imports from `ui/lit/lit.js`, `useShadowDom: true` in new or migrated `UI.Widget` constructors instead of `useShadowDom: 'pure'` (which makes `this.contentElement` the `ShadowRoot` directly without an extra inner `<div class="widget">` wrapper), `super(..., {classes: [...]})` / `super(..., {jslog: ...})` in `UI.Widget` constructors instead of passing `{container: {classes: [...], attributes: {jslog: ...}}}` as the third argument to every `render(template, target, {container: {classes: [...]}})` branch in the view function (with `useShadowDom: 'pure'` when shadow DOM is used), imperative `element.classList.add(...)`, `element.setAttribute(...)`, or `UI.ARIAUtils.*(element)` calls on a container element (`this.contentElement`, `this.element`, or a detached `HTMLDivElement`) that is rendered via `render(template, element)` instead of passing `{container: {classes: [...], attributes: {...}}}` as the third argument to `render(...)`, combining a `.hidden` CSS class (`class="... hidden"`, `classMap({hidden: ...})`, or `classList.toggle('hidden', ...)`) with the HTML `?hidden` attribute, or toggling `.hidden` via `classMap` when `?hidden=${...}` suffices (prefer `?hidden=${...}` exclusively; `inspectorCommon.css` already provides `[hidden] { display: none !important; }`), overriding `focus(): void` on a `UI.Widget`, calling `this.setDefaultFocusedElement(...)` or `this.setDefaultFocusedChild(...)` imperatively, or plumbing a `ref(...)` focus callback through `ViewOutput` merely to focus a default child element or widget when declarative `autofocus` or `?autofocus=${...}` in `DEFAULT_VIEW` suffices (`UI.Widget.prototype.focus()` natively queries `[autofocus]` via `getDefaultFocusedElement()`; ensure at most one element has `autofocus` in any render state), or `@SomeEvent` on `<devtools-widget>` when the child class does not use `eventMixin` on `UI.Widget` (no `dispatchDOMEvent`), when the listener is placed on an ancestor element (the `CustomEvent` does not bubble), or when the handler reads `event.data` instead of `event.detail`.
|
|
9
|
+
- **Do not flag**: Static arrays of primitive labels where item identity never reorders. Omitting Lit's `live()` directive on `<devtools-checkbox>` (`UI.UIUtils.CheckboxLabel`) `.checked` bindings (`live()` breaks `CheckboxLabel`'s host `checked` attribute synchronization when toggled externally), listening to `ObjectWrapper` events via Lit `@SomeEvent=${handler}` bindings on a `<devtools-widget>` whose class uses `Common.ObjectWrapper.eventMixin` on `UI.Widget` (`eventMixin` dispatches `new CustomEvent(type, {detail: data})` on `widget.element`, and Lit preserves the case of `@SomeEvent` from the template string), interpolating boolean values directly inside Lit text/`<td>` positions (Lit renders booleans as `'true'`/`'false'`), `override focus()` methods that perform dynamic focus restoration beyond focusing a single `[autofocus]` target (such as restoring text editor selection/coordinates or delegating to legacy sub-views), or newlines and indentation spaces between expressions and child elements in multi-line `html` templates (DevTools' custom `html` tag in `front_end/ui/lit/strip-whitespace.ts` strips `\n\s*` outside of `<...>` tags at runtime, so multi-line formatting does not introduce whitespace text nodes).
|
|
10
10
|
|
|
11
|
-
**Why.** Mutating DOM elements via `appendChild`, `classList.toggle`, or `innerHTML` alongside Lit templates,
|
|
11
|
+
**Why.** Mutating DOM elements via `appendChild`, `classList.toggle`, or `innerHTML` alongside Lit templates, returning `''`/`null` instead of `Lit.nothing` in conditional branches, or combining `.hidden` classes with `?hidden` attributes corrupts part tracking and creates redundant style rules. Using declarative `autofocus` leverages `UI.Widget`'s built-in focus delegation without imperative wiring or manual `ref` plumbing through `ViewOutput`.
|
|
12
12
|
|
|
13
13
|
## Examples
|
|
14
14
|
|
|
15
15
|
Bad:
|
|
16
16
|
|
|
17
17
|
```ts
|
|
18
|
+
// String-interpolated classes, empty string ternary fallback, .hidden class + ?hidden, and ref focus plumbing
|
|
18
19
|
html`
|
|
19
|
-
<div class="item ${isActive ? 'active' : ''}" title=${
|
|
20
|
+
<div class="item ${isActive ? 'active' : ''} ${classMap({hidden: !isVisible})}" ?hidden=${!isVisible} title=${maybeTitle || ''}>
|
|
20
21
|
${showIcon ? html`<devtools-icon name="info"></devtools-icon>` : ''}
|
|
22
|
+
<button ${ref(el => { if (el) output.focus = () => el.focus(); })}>Click</button>
|
|
21
23
|
</div>
|
|
22
24
|
`
|
|
23
25
|
```
|
|
@@ -25,9 +27,11 @@ html`
|
|
|
25
27
|
Good:
|
|
26
28
|
|
|
27
29
|
```ts
|
|
30
|
+
// Using classMap, ifDefined, nothing sentinel, ?hidden attribute exclusively, and autofocus
|
|
28
31
|
html`
|
|
29
|
-
<div class=${classMap({item: true, active: isActive})} title=${ifDefined(maybeTitle)}>
|
|
30
|
-
${showIcon ? html`<devtools-icon name="info"></devtools-icon>` :
|
|
32
|
+
<div class=${classMap({item: true, active: isActive})} ?hidden=${!isVisible} title=${ifDefined(maybeTitle)}>
|
|
33
|
+
${showIcon ? html`<devtools-icon name="info"></devtools-icon>` : nothing}
|
|
34
|
+
<button autofocus>Click</button>
|
|
31
35
|
</div>
|
|
32
36
|
`
|
|
33
37
|
```
|
|
@@ -4,11 +4,11 @@ rubric: design
|
|
|
4
4
|
severity: should_fix
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
**Rule.** Use modern DevTools UI primitives (`devtools-button`, `devtools-data-grid`, `devtools-icon`, `devtools-link`, `devtools-list`, `devtools-
|
|
8
|
-
- **Look for**: `UI.Fragment.build`, legacy `DataGridImpl`, `extends LitElement`, `Link.create(...)` or `UI.XLink.XLink.create(...)` inside Lit view functions (use `<devtools-link>` instead), `UI.ListWidget.ListWidget` / `UI.ListWidget.Delegate` in newly migrated views or passed via `ViewInput` to `WrapperWidget` with `DocumentFragment` item/editor adapters (prefer `<devtools-list>` with `<devtools-prompt>`, an inline editor row, or `UI.Dialog.Dialog`, or encapsulate `ListWidget` inside the view layer behind pure `ViewInput` data and callbacks), imperative `UI.TabbedPane.TabbedPane` or `StackLocation` passed via `ViewInput` instead of declarative `<devtools-tabbed-pane>` / `<devtools-stack-pane>` in the view, `private ` keyword instead of `#` in new UI classes, `<devtools-*>` tags in Lit templates without importing the corresponding component module entrypoint (e.g. `import * as Buttons from '../../ui/components/buttons/buttons.js'`), or formatting dates or timestamps with `toLocaleString()` inside sortable `<devtools-data-grid>` cells without a numeric/ISO sort value (sorts alphabetically instead of chronologically; use `toISOString()` or a numeric sort value).
|
|
9
|
-
- **Do not flag**: Overriding inherited `protected` lifecycle methods on framework base classes (e.g. extending `UI.Widget.Widget`).
|
|
7
|
+
**Rule.** Use modern DevTools UI primitives (`devtools-button`, `devtools-data-grid`, `devtools-icon`, `devtools-link`, `devtools-list`, `devtools-prompt`, `devtools-stack-pane`, `devtools-tabbed-pane`, `devtools-tree`), #private fields, and module entrypoint imports
|
|
8
|
+
- **Look for**: `UI.Fragment.build`, legacy `DataGridImpl`, `extends LitElement`, `Link.create(...)` or `UI.XLink.XLink.create(...)` inside Lit view functions (use `<devtools-link>` instead), `UI.ListWidget.ListWidget` / `UI.ListWidget.Delegate` in newly migrated views or passed via `ViewInput` to `WrapperWidget` with `DocumentFragment` item/editor adapters (prefer `<devtools-list>` with `<devtools-prompt>`, an inline editor row, or `UI.Dialog.Dialog`, or encapsulate `ListWidget` inside the view layer behind pure `ViewInput` data and callbacks), legacy `UI.TreeOutline.TreeOutline` / `TreeOutlineInShadow`, `extends UI.TreeOutline.TreeElement` subclasses, `UI.ListControl.ListControl`, or `UI.InplaceEditor` in newly authored UI or in CLs claiming to complete a UI Eng Vision migration (`Fixed: <id>`) (noting that ESLint `@devtools/no-imperative-dom-api` does not flag `extends UI.TreeOutline.TreeElement` subclasses or `UI.ListControl`), migrated `UI.Widget` subclasses with `DEFAULT_VIEW` whose constructor omits `element?: HTMLElement` as its first parameter (`constructor(element?: HTMLElement, ..., view: View = DEFAULT_VIEW)` so the widget can be instantiated via `${widget(MyWidget, ...)}`), or omits `static override readonly INJECT` when requesting `Universe`-managed dependencies, imperative `UI.TabbedPane.TabbedPane` or `StackLocation` passed via `ViewInput` instead of declarative `<devtools-tabbed-pane>` / `<devtools-stack-pane>` in the view, `private ` keyword instead of `#` in new UI classes, `<devtools-*>` tags in Lit templates without importing the corresponding component module entrypoint (e.g. `import * as Buttons from '../../ui/components/buttons/buttons.js'`), or formatting dates or timestamps with `toLocaleString()` inside sortable `<devtools-data-grid>` cells without a numeric/ISO sort value (sorts alphabetically instead of chronologically; use `toISOString()` or a numeric sort value).
|
|
9
|
+
- **Do not flag**: Overriding inherited `protected` lifecycle methods on framework base classes (e.g. extending `UI.Widget.Widget`). Explicitly scoped intermediate CLs (`Bug: <id>`, not `Fixed: <id>`) in a multi-CL migration that refactor presenter/item state in place while deferring `<devtools-tree>` or `UI.ListControl` replacement to a follow-up CL.
|
|
10
10
|
|
|
11
|
-
**Why.** Legacy `UI.Fragment`, `DataGridImpl`, `LitElement`, `new Icon()`, `Link.create()`, `UI.XLink.XLink.create()`, `UI.ListWidget.ListWidget`, imperative `UI.TabbedPane.TabbedPane` / `StackLocation`, and TypeScript `private` fields are superseded by standard `<devtools-*>` custom elements (imported via module entrypoints such as `import * as Buttons from '../../ui/components/buttons/buttons.js'` so custom tags register at runtime) and ECMAScript `#private` fields.
|
|
11
|
+
**Why.** Legacy `UI.Fragment`, `DataGridImpl`, `LitElement`, `new Icon()`, `Link.create()`, `UI.XLink.XLink.create()`, `UI.TreeOutline`, `UI.ListControl`, `UI.InplaceEditor`, `UI.ListWidget.ListWidget`, imperative `UI.TabbedPane.TabbedPane` / `StackLocation`, and TypeScript `private` fields are superseded by standard `<devtools-*>` custom elements (imported via module entrypoints such as `import * as Buttons from '../../ui/components/buttons/buttons.js'` so custom tags register at runtime) and ECMAScript `#private` fields. Migrated widgets must expose the standard MVP constructor signature (`element?: HTMLElement, ..., view: View = DEFAULT_VIEW`) and declare `static override readonly INJECT` for dependency injection.
|
|
12
12
|
|
|
13
13
|
## Examples
|
|
14
14
|
|
|
@@ -18,6 +18,7 @@ Bad:
|
|
|
18
18
|
import type * as Buttons from '../../ui/components/buttons/buttons.js';
|
|
19
19
|
export class MyView extends UI.Widget.VBox {
|
|
20
20
|
private grid = new DataGrid.DataGrid.DataGridImpl({...});
|
|
21
|
+
private tree = new UI.TreeOutline.TreeOutlineInShadow();
|
|
21
22
|
}
|
|
22
23
|
```
|
|
23
24
|
|
|
@@ -26,7 +27,15 @@ Good:
|
|
|
26
27
|
```ts
|
|
27
28
|
import * as Buttons from '../../ui/components/buttons/buttons.js';
|
|
28
29
|
import * as DataGrid from '../../ui/legacy/components/data_grid/data_grid.js';
|
|
30
|
+
import '../../ui/kit/kit.js';
|
|
31
|
+
|
|
29
32
|
export class MyView extends UI.Widget.VBox {
|
|
30
33
|
#items: Item[] = [];
|
|
34
|
+
#view: View;
|
|
35
|
+
|
|
36
|
+
constructor(element?: HTMLElement, view: View = DEFAULT_VIEW) {
|
|
37
|
+
super(element);
|
|
38
|
+
this.#view = view;
|
|
39
|
+
}
|
|
31
40
|
}
|
|
32
41
|
```
|
|
@@ -5,10 +5,10 @@ severity: should_fix
|
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
**Rule.** Keep UI.Widget view functions pure and stateless by computing presentation data in presenters and passing decoupled ViewInput data structures
|
|
8
|
-
- **Look for**: `DEFAULT_VIEW` or view helper functions calling `Common.Settings.Settings.instance()`, `UI.Context.Context.instance()`, `SDK.TargetManager.TargetManager.instance()`, `Host.*`, or mutating model or `input.*` state in place; `ViewInput` interfaces carrying pre-created DOM `Element`/`HTMLElement` nodes or `UI.Widget` instances (`ListWidget`, `TabbedPane`, `Linkifier` elements); presenters calling `DEFAULT_VIEW(...)` or auxiliary `*_VIEW(...)` constants directly instead of injecting `view: View = DEFAULT_VIEW` via the constructor (`this.#view(...)`) and exporting `ViewInput` and `View`; or Lit migrations that delete existing standalone/class DOM helper functions and inline their logic into `performUpdate()` or `DEFAULT_VIEW` instead of converting them in place to return `LitTemplate` (or `Promise<LitTemplate|null>`).
|
|
8
|
+
- **Look for**: `DEFAULT_VIEW` or view helper functions calling `Common.Settings.Settings.instance()`, `UI.Context.Context.instance()`, `SDK.TargetManager.TargetManager.instance()`, `Host.*`, or mutating model or `input.*` state in place; `ViewInput` interfaces carrying pre-created DOM `Element`/`HTMLElement` nodes or `UI.Widget` instances (`ListWidget`, `TabbedPane`, `Linkifier` elements); presenters calling `DEFAULT_VIEW(...)` or auxiliary `*_VIEW(...)` constants directly instead of injecting `view: View = DEFAULT_VIEW` via the constructor (`this.#view(...)`) and exporting `ViewInput` and `View`; one-time lazy model/workspace initialization guards (`if (!this.#initialized) { ... }`) inside `performUpdate()` (side-effecting initialization belongs in `wasShown()`, keeping `performUpdate()` a pure projection of presenter state into `this.#view(...)`); or Lit migrations that delete existing standalone/class DOM helper functions and inline their logic into `performUpdate()` or `DEFAULT_VIEW` instead of converting them in place to return `LitTemplate` (or `Promise<LitTemplate|null>`).
|
|
9
9
|
- **Do not flag**: Legacy `UI.Widget` subclasses that have not yet migrated to a `DEFAULT_VIEW` function, or passing read-only `Protocol.*`, `SDK.*`, or `Models.*` objects in `ViewInput` when the view only reads properties/getters from them or forwards them to child widgets/linkifiers without mutating model state or calling side-effecting `SDK` methods.
|
|
10
10
|
|
|
11
|
-
**Why.** In DevTools' MVP architecture, `DEFAULT_VIEW` functions must be pure projections of `ViewInput` to Lit templates. Querying SDK models, reading global settings, mutating presenter state, or calling host/clipboard APIs inside the view couples rendering to global state and breaks isolated view testing.
|
|
11
|
+
**Why.** In DevTools' MVP architecture, `DEFAULT_VIEW` functions must be pure projections of `ViewInput` to Lit templates. Querying SDK models, reading global settings, mutating presenter state, performing one-time initialization inside `performUpdate()`, or calling host/clipboard APIs inside the view couples rendering to global state and breaks isolated view testing.
|
|
12
12
|
|
|
13
13
|
## Examples
|
|
14
14
|
|
|
@@ -29,3 +29,32 @@ export const DEFAULT_VIEW = (input: ViewInput, _output: ViewOutput, target: HTML
|
|
|
29
29
|
Lit.render(html`${input.sortedItems.map(item => html`<div>${item.name}</div>`)}`, target);
|
|
30
30
|
};
|
|
31
31
|
```
|
|
32
|
+
|
|
33
|
+
Bad:
|
|
34
|
+
|
|
35
|
+
```ts
|
|
36
|
+
override performUpdate(): void {
|
|
37
|
+
if (!this.#initialized) {
|
|
38
|
+
this.#initialized = true;
|
|
39
|
+
this.#initializeFromWorkspace(); // Side-effecting initialization in performUpdate
|
|
40
|
+
}
|
|
41
|
+
this.#view(this.#viewInput, undefined, this.contentElement);
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Good:
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
override wasShown(): void {
|
|
49
|
+
super.wasShown();
|
|
50
|
+
if (!this.#initialized) {
|
|
51
|
+
this.#initialized = true;
|
|
52
|
+
this.#initializeFromWorkspace();
|
|
53
|
+
}
|
|
54
|
+
this.requestUpdate();
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
override performUpdate(): void {
|
|
58
|
+
this.#view(this.#viewInput, undefined, this.contentElement);
|
|
59
|
+
}
|
|
60
|
+
```
|
|
@@ -4,11 +4,11 @@ rubric: design
|
|
|
4
4
|
severity: should_fix
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
**Rule.** Schedule widget re-renders asynchronously via this.requestUpdate() and guard property setters with equality checks
|
|
8
|
-
- **Look for**: Widget property setters calling `this.performUpdate()` or `this.#view(...)` directly, setters calling `this.requestUpdate()` without checking `if (this.#prop === value) return;`, monolithic `set data(...)` object setters on `UI.Widget` subclasses instead of individual property setters,
|
|
9
|
-
- **Do not flag**: Internal test helpers or synchronous initialization paths explicitly documented as requiring immediate flush. Synchronous `this.performUpdate()` calls in a constructor when the constructor or methods callable before `wasShown()` depend on `ViewOutput`, `widgetRef`, or `ref` fields populated by the initial render.
|
|
7
|
+
**Rule.** Schedule widget re-renders asynchronously via this.requestUpdate(), avoid synchronous performUpdate() in presenter methods, and guard property setters with equality checks
|
|
8
|
+
- **Look for**: Widget property setters calling `this.performUpdate()` or `this.#view(...)` directly, setters calling `this.requestUpdate()` without checking `if (this.#prop === value) return;`, monolithic `set data(...)` object setters on `UI.Widget` subclasses instead of individual property setters, synchronous `this.performUpdate()` calls inside a `UI.Widget` `constructor()` (creates DOM and reads `UI.Context` before the widget is attached or visible; use `this.requestUpdate()` or `wasShown()` instead), synchronous `this.performUpdate()` calls in presenter methods, event handlers, selection/expansion/rename handlers, or helper nodes when scheduling an asynchronous `this.requestUpdate()` suffices (callers and tests should `await widget.updateComplete` when inspecting post-render DOM), custom `#renderView()` or `#render()` methods on `UI.Widget` subclasses that invoke `this.#view(...)` directly bypassing `override performUpdate()` and `this.requestUpdate()`, or view-layer refresh methods on presenter or presenter-node classes (such as `updateTrailingIcons()`, `updateIcon()`, `updateTreeElement()`) that push visual updates imperatively instead of mutating pure presenter state and calling `this.requestUpdate()` so `DEFAULT_VIEW` computes icons, badges, and tooltips declaratively.
|
|
9
|
+
- **Do not flag**: Internal test helpers, `legacy_test_runner` helpers, or synchronous initialization paths explicitly documented as requiring immediate flush. Synchronous `this.performUpdate()` calls in a constructor when the constructor or methods callable before `wasShown()` depend on `ViewOutput`, `widgetRef`, or `ref` fields populated by the initial render. `UI.Panel.Panel` or `UI.Dialog.Dialog` subclasses where `requestUpdate()` is unavailable and calling `performUpdate()` is required. Popover or tooltip widgets instantiated inside `setTimeout` or before element bounds measurement where synchronous DOM rendering is necessary before measuring dimensions.
|
|
10
10
|
|
|
11
|
-
**Why.** Calling `this.performUpdate()` or invoking `this.#view(...)` synchronously inside property setters causes redundant synchronous DOM renders when multiple
|
|
11
|
+
**Why.** Calling `this.performUpdate()` or invoking `this.#view(...)` synchronously inside property setters, presenter event handlers, or helper methods causes redundant synchronous DOM renders and layout thrashing when multiple pieces of state change in the same tick. Presenter methods and setters should mutate state, short-circuit if unchanged, and schedule re-rendering asynchronously via `this.requestUpdate()`. Presenter nodes must not retain imperative view-refresh methods; all visual representations should be derived declaratively in the view function.
|
|
12
12
|
|
|
13
13
|
## Examples
|
|
14
14
|
|
|
@@ -19,6 +19,17 @@ set items(items: Item[]) {
|
|
|
19
19
|
this.#items = items;
|
|
20
20
|
this.performUpdate();
|
|
21
21
|
}
|
|
22
|
+
|
|
23
|
+
selectNode(node: MyNode): void {
|
|
24
|
+
this.#selectedNode = node;
|
|
25
|
+
this.performUpdate(); // Synchronous render in presenter method
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
updateTrailingIcons(): void {
|
|
29
|
+
// Imperative view-layer helper on presenter node
|
|
30
|
+
this.#trailingIcons = [renderIcon()];
|
|
31
|
+
this.performUpdate();
|
|
32
|
+
}
|
|
22
33
|
```
|
|
23
34
|
|
|
24
35
|
Good:
|
|
@@ -31,4 +42,12 @@ set items(items: Item[]) {
|
|
|
31
42
|
this.#items = items;
|
|
32
43
|
this.requestUpdate();
|
|
33
44
|
}
|
|
45
|
+
|
|
46
|
+
selectNode(node: MyNode): void {
|
|
47
|
+
if (this.#selectedNode === node) {
|
|
48
|
+
return;
|
|
49
|
+
}
|
|
50
|
+
this.#selectedNode = node;
|
|
51
|
+
this.requestUpdate();
|
|
52
|
+
}
|
|
34
53
|
```
|
|
@@ -4,11 +4,11 @@ rubric: correctness
|
|
|
4
4
|
severity: blocking
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
**Rule.** Attach listeners to external models and managers in wasShown and detach them symmetrically in willHide
|
|
8
|
-
- **Look for**: `addEventListener`, `addModelListener`, or `addChangeListener` on singletons, models, or settings inside `UI.Widget` constructors or `wasShown()` without a matching `remove*` call in `willHide()` using the same function reference, scheduled or asynchronous `performUpdate()` methods on `SDKModelObserver` widgets that access or re-register a model without checking that `this.#model` is still active after `modelRemoved()` has run, or calling `removeChildren()` on a DOM or `TreeOutline` container that hosts imperatively mounted `UI.Widget` children without first detaching them (`this.detachChildWidgets()` or `UI.Widget.Widget.get(el)?.detach()`).
|
|
7
|
+
**Rule.** Attach listeners to external models and managers in wasShown and detach them symmetrically in willHide without wiping populated UI state on re-show
|
|
8
|
+
- **Look for**: `addEventListener`, `addModelListener`, or `addChangeListener` on singletons, models, or settings inside `UI.Widget` constructors or `wasShown()` without a matching `remove*` call in `willHide()` using the same function reference, `wasShown()` or subscription implementations that unconditionally `reset()` or wipe already-populated presenter UI state (such as expanded tree folders, selection, or filter state) when a hidden widget is shown again instead of initializing once and incrementally reconciling model/workspace/setting changes that occurred while hidden, scheduled or asynchronous `performUpdate()` methods on `SDKModelObserver` widgets that access or re-register a model without checking that `this.#model` is still active after `modelRemoved()` has run, or calling `removeChildren()` on a DOM or `TreeOutline` container that hosts imperatively mounted `UI.Widget` children without first detaching them (`this.detachChildWidgets()` or `UI.Widget.Widget.get(el)?.detach()`).
|
|
9
9
|
- **Do not flag**: Listeners attached to the widget's own internal DOM elements (`this.contentElement`), which are garbage-collected together with the widget. Model or target listeners on background recording/overview widgets (such as `NetworkOverview`) that must continuously record events while the widget is hidden or collapsed (especially when rendering is already gated on `this.isShowing()`), or pre-existing constructor listeners untouched by a DOM-to-Lit view migration.
|
|
10
10
|
|
|
11
|
-
**Why.** Subscribing to long-lived SDK `TargetManager`, `Settings`, or model events in a widget's constructor without unsubscribing in `willHide()` (or `onDetach()` / `onunbind()`) causes hidden panels to process background updates and leaks detached widget instances.
|
|
11
|
+
**Why.** Subscribing to long-lived SDK `TargetManager`, `Settings`, or model events in a widget's constructor without unsubscribing in `willHide()` (or `onDetach()` / `onunbind()`) causes hidden panels to process background updates and leaks detached widget instances. Conversely, unconditionally resetting presenter state on `wasShown()` destroys expanded tree nodes and user selections whenever the user switches away and back to the tab.
|
|
12
12
|
|
|
13
13
|
## Examples
|
|
14
14
|
|
|
@@ -36,3 +36,34 @@ override willHide(): void {
|
|
|
36
36
|
SDK.DOMModel.DOMModel, SDK.DOMModel.Events.DocumentUpdated, this.#onUpdate, this);
|
|
37
37
|
}
|
|
38
38
|
```
|
|
39
|
+
|
|
40
|
+
Bad:
|
|
41
|
+
|
|
42
|
+
```ts
|
|
43
|
+
override wasShown(): void {
|
|
44
|
+
super.wasShown();
|
|
45
|
+
this.#reset(); // Destroys open folders and selection every time tab is shown!
|
|
46
|
+
this.#subscribe();
|
|
47
|
+
this.requestUpdate();
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Good:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
override wasShown(): void {
|
|
55
|
+
super.wasShown();
|
|
56
|
+
if (!this.#initialized) {
|
|
57
|
+
this.#initialized = true;
|
|
58
|
+
this.#populateInitialState();
|
|
59
|
+
} else {
|
|
60
|
+
this.#reconcileState(); // Incrementally updates changes that occurred while hidden
|
|
61
|
+
}
|
|
62
|
+
this.#subscribe();
|
|
63
|
+
this.requestUpdate();
|
|
64
|
+
}
|
|
65
|
+
override willHide(): void {
|
|
66
|
+
super.willHide();
|
|
67
|
+
this.#unsubscribe();
|
|
68
|
+
}
|
|
69
|
+
```
|
|
@@ -129,6 +129,13 @@ findings):
|
|
|
129
129
|
scenario.
|
|
130
130
|
- **Fail fast:** Throw or assert when a required value is missing. Don't let
|
|
131
131
|
the test time out later.
|
|
132
|
+
- **Pre-migration tests for legacy widgets:** When reviewing tests added ahead of
|
|
133
|
+
replacing a legacy widget (`TreeOutline`, `DataGrid`, `ListControl`,
|
|
134
|
+
`ListWidget`), check that DOM/tree inspection is encapsulated in local test
|
|
135
|
+
helpers (`dumpTree()`, `findTreeItem()`, `activateRow()`) rather than
|
|
136
|
+
repeated across every `it()` block, and ask for `assertScreenshot(...)` golden
|
|
137
|
+
tests so visual regressions are caught independently of the legacy widget
|
|
138
|
+
implementation.
|
|
132
139
|
|
|
133
140
|
## 6. Test hygiene and cleanup
|
|
134
141
|
|
|
@@ -165,6 +172,25 @@ findings):
|
|
|
165
172
|
characters.
|
|
166
173
|
- For migrations and stacked series, list the legacy tests or files covered,
|
|
167
174
|
and number the series (for example, `(13/16)`).
|
|
175
|
+
- **UI Eng Vision migration completeness & `Fixed:` vs `Bug:`**: Flag
|
|
176
|
+
`Fixed: <id>` on UI Eng Vision migration CLs when core violations remain in
|
|
177
|
+
the target file: legacy `UI.TreeOutline` or `extends UI.TreeOutline.TreeElement`
|
|
178
|
+
subclasses, `UI.ListControl`, `UI.ListWidget`, `UI.InplaceEditor`, non-MVP
|
|
179
|
+
constructors (missing `element?: HTMLElement` or injectable `view = DEFAULT_VIEW`),
|
|
180
|
+
missing `static override readonly INJECT` for Universe dependencies, custom
|
|
181
|
+
`#renderView()` helpers bypassing `override performUpdate()` +
|
|
182
|
+
`this.requestUpdate()`, constructor-bound model/setting listeners instead of
|
|
183
|
+
non-destructive `wasShown()`/`willHide()` subscriptions, synchronous
|
|
184
|
+
`this.performUpdate()` calls in presenter methods, or TypeScript `private`
|
|
185
|
+
fields not required by `legacy_test_runner`/`blink/web_tests`. Note
|
|
186
|
+
explicitly that a clean `@devtools/no-imperative-dom-api` lint pass does
|
|
187
|
+
**not** prove completeness because ESLint misses `TreeElement` subclasses and
|
|
188
|
+
`UI.ListControl`. Intermediate CLs in a multi-CL migration must use
|
|
189
|
+
`Bug: <id>`, reserving `Fixed: <id>` for the final CL.
|
|
190
|
+
- **Component contract preservation**: Flag feature or panel migrations that
|
|
191
|
+
widen `front_end/ui/legacy/` component contracts (such as exporting internal
|
|
192
|
+
classes or turning `*ForTest()` or `*ForTesting()` methods on `Treeoutline.ts`
|
|
193
|
+
into public APIs).
|
|
168
194
|
- Disabled tests reference a bug.
|
|
169
195
|
- Presubmit, lint, and format pass. See `devtools-verification`.
|
|
170
196
|
|
|
@@ -114,6 +114,33 @@ existing element containers.
|
|
|
114
114
|
* **Accessibility Preservation**: Convert custom accessibility
|
|
115
115
|
instrumentation (like `ARIAUtils.markAsAlert()`) to native ARIA
|
|
116
116
|
attributes in the template (e.g., `role="alert"`, `aria-live="polite"`).
|
|
117
|
+
* **Visibility (`?hidden` Attribute Only)**: Use `?hidden=${...}`
|
|
118
|
+
exclusively to toggle visibility in templates. Never combine a `.hidden`
|
|
119
|
+
CSS class (`classMap({hidden: ...})` or `classList.toggle('hidden', ...)`)
|
|
120
|
+
with `?hidden` (`inspectorCommon.css` already defines
|
|
121
|
+
`[hidden] { display: none !important; }`).
|
|
122
|
+
* **Declarative Default Focus (`autofocus` / `?autofocus`)**: Prefer
|
|
123
|
+
marking the default focused element with `autofocus` or `?autofocus=${...}`
|
|
124
|
+
in the template instead of collecting elements via `ref(...)` and plumbing
|
|
125
|
+
focus callbacks through `ViewOutput`. `UI.Widget.prototype.focus()`
|
|
126
|
+
queries `[autofocus]` automatically via `getDefaultFocusedElement()`.
|
|
127
|
+
* **`<devtools-tree>` & Persistent `<devtools-prompt ?editing>` Patterns**:
|
|
128
|
+
When rendering `<devtools-tree .template=${html`<ul role="tree">...</ul>`}>`:
|
|
129
|
+
- Preserve `front_end/ui/legacy/Treeoutline.ts` contracts without
|
|
130
|
+
widening internal classes or exposing `TreeOutline` getters on the
|
|
131
|
+
presenter.
|
|
132
|
+
- Drive selection and expansion declaratively via `?selected`, `?open`,
|
|
133
|
+
`@select`, and `@expand`.
|
|
134
|
+
- Do not duplicate `aria-label` on inner prompts when the enclosing
|
|
135
|
+
`<li role="treeitem">` already labels the row, do not duplicate
|
|
136
|
+
`class="tree-element-title"` on inner spans (which compounds opacity
|
|
137
|
+
rules), and return `nothing` for trailing icons when none exist.
|
|
138
|
+
- Host editable `<devtools-prompt ?editing>` rows in a child `UI.Widget`
|
|
139
|
+
(`${widget(RowPromptWidget, {...})}`) so `<devtools-tree>`'s
|
|
140
|
+
`MutationObserver` does not re-clone the row and blur the active input.
|
|
141
|
+
- Ensure custom elements with state passed via JS properties (`.data`)
|
|
142
|
+
override `cloneNode(deep)` and reflect dynamic state via DOM
|
|
143
|
+
attributes so shadow clones stay updated.
|
|
117
144
|
|
|
118
145
|
11. **Render Templates Syntax & Code Movement**:
|
|
119
146
|
|
|
@@ -238,4 +265,3 @@ existing element containers.
|
|
|
238
265
|
5. ❓ **Split Views**: Does `<devtools-split-view>` have `flex: auto; height: 100%;` CSS and reuse existing split settings?
|
|
239
266
|
6. ❓ **String Audit**: Did I verify that any removed `UIStrings` weren't from accidentally dropped UI branches?
|
|
240
267
|
7. ❓ **Build**: Does the code compile and do visual tests pass with 0% diff?
|
|
241
|
-
|
|
@@ -207,3 +207,103 @@ The plan you generate **MUST** follow this structure:
|
|
|
207
207
|
1. Promote view classes to modern `UI.Widget` classes, hook up
|
|
208
208
|
`performUpdate()` delegates, export the default view layout, and clean
|
|
209
209
|
up legacy wrappers.
|
|
210
|
+
|
|
211
|
+
--------------------------------------------------------------------------------
|
|
212
|
+
|
|
213
|
+
## 3. Incremental Multi-CL Playbook for Complex Tree & List Widgets (`UI.TreeOutline` → `<devtools-tree>`)
|
|
214
|
+
|
|
215
|
+
For complex widgets with deeply nested item hierarchies, custom tree element
|
|
216
|
+
subclasses, or inline editing (such as `NavigatorView` or `SearchResultsPane`),
|
|
217
|
+
monolithic migrations introduce high review friction and regression risk.
|
|
218
|
+
Decompose the work into a 4-phase sequence of small, self-contained CLs
|
|
219
|
+
(~50–250 lines of diff each):
|
|
220
|
+
|
|
221
|
+
### Phase 0: Safety Net, Cleanup & Latent Bug Fixes (Independent CLs)
|
|
222
|
+
1. **Dead-Code Removal**: Remove dead helper methods, unused getters, and
|
|
223
|
+
obsolete container references in an initial standalone CL.
|
|
224
|
+
2. **Implementation-Decoupled Tests**: Add structural and interaction unit
|
|
225
|
+
tests whose DOM assertions route through small local test helpers
|
|
226
|
+
(`dumpTree()`, `findTreeItem()`, `activateRow()`, `openContextMenuOnRow()`)
|
|
227
|
+
rather than scattering direct tree-outline element queries across tests.
|
|
228
|
+
3. **Screenshot Baselines**: Add `assertScreenshot(...)` golden tests covering
|
|
229
|
+
critical visual states (grouping modes, icons/badges, selection, dimmed
|
|
230
|
+
items) to establish baselines that catch visual regressions independently of
|
|
231
|
+
the underlying widget engine.
|
|
232
|
+
4. **Targeted Bug Fixes**: If test scaffolding uncovers latent bugs in existing
|
|
233
|
+
logic, fix them in dedicated bugfix CLs before refactoring.
|
|
234
|
+
|
|
235
|
+
### Phase 1: Decouple Custom Item Subclasses One Concern per CL (`Bug: <id>`)
|
|
236
|
+
1. **Sorting & Comparators**: Move sorting functions from item elements to
|
|
237
|
+
presenter data nodes.
|
|
238
|
+
2. **Row Event Handlers**: Move row event handlers (hover, context menu, drag,
|
|
239
|
+
rename triggers) to presenter methods.
|
|
240
|
+
3. **Icon & Action Templates**: Convert imperative leading/trailing icons,
|
|
241
|
+
badges, and action buttons into module-level Lit template helpers, removing
|
|
242
|
+
view-layer refresh methods (`updateTrailingIcons()`, `updateIcon()`) from
|
|
243
|
+
presenter nodes once state moves to `DEFAULT_VIEW`.
|
|
244
|
+
4. **State Tracking in Presenter**: Track selection, expansion (`WeakSet`), and
|
|
245
|
+
lazy population in the presenter via tree events rather than overriding
|
|
246
|
+
`TreeElement.onpopulate()` or `onselect()`.
|
|
247
|
+
5. **Remove Custom Subclasses**: Delete custom `TreeElement` subclasses one
|
|
248
|
+
class per CL, using plain `UI.TreeOutline.TreeElement` instances paired with
|
|
249
|
+
a `WeakMap<TreeElement, Node>` bridge and computing presenter node state
|
|
250
|
+
(`title`, `tooltip`, badges) independently of `TreeElement` creation.
|
|
251
|
+
|
|
252
|
+
### Phase 2: Persistent `<devtools-prompt>` & `<devtools-tree>` Swap (`Bug: <id>`)
|
|
253
|
+
1. **Persistent `<devtools-prompt ?editing>`**: Migrate inline renaming or
|
|
254
|
+
editing (`UI.InplaceEditor`) to a persistent `<devtools-prompt ?editing>` in
|
|
255
|
+
its own CL, updating E2E tests waiting on `.being-edited` to wait on
|
|
256
|
+
`devtools-prompt[editing]`.
|
|
257
|
+
2. **Test-Helper Prep CL**: If `front_end/legacy_test_runner/**` or
|
|
258
|
+
`blink_web_tests` walk internal tree elements, update test helpers to flush
|
|
259
|
+
`innerView.performUpdate()` and `flushPendingUpdatesForTesting()` after
|
|
260
|
+
expanding nodes.
|
|
261
|
+
3. **`<devtools-tree>` Swap**: Replace `TreeOutlineInShadow` with
|
|
262
|
+
`<devtools-tree autofocus>` in `DEFAULT_VIEW` without widening
|
|
263
|
+
`front_end/ui/legacy/Treeoutline.ts` contracts. Host editable
|
|
264
|
+
`<devtools-prompt ?editing>` rows in a child `UI.Widget` (`${widget(...)}`)
|
|
265
|
+
so `<devtools-tree>`'s light-DOM `MutationObserver` does not re-clone the
|
|
266
|
+
row and blur the active input. Use asynchronous `this.requestUpdate()` across
|
|
267
|
+
all presenter methods and remove
|
|
268
|
+
`/* eslint-disable @devtools/no-imperative-dom-api */`.
|
|
269
|
+
|
|
270
|
+
### Phase 3: Pure Lifecycle, `INJECT` DI & Final Polish (`Fixed: <id>` on Final CL Only)
|
|
271
|
+
1. **Non-Destructive Lifecycle**: Move model, workspace, and setting
|
|
272
|
+
subscriptions from `constructor()` into `wasShown()` / `willHide()`,
|
|
273
|
+
reconciling incremental changes that occurred while hidden rather than
|
|
274
|
+
calling `reset()` and wiping open folders or selection on every re-show.
|
|
275
|
+
2. **Universe Dependency Injection**: Add `static override readonly INJECT` and
|
|
276
|
+
the standard MVP constructor `(element?: HTMLElement, [...]: WidgetDependencies, view: View = DEFAULT_VIEW)`.
|
|
277
|
+
3. **Private Fields & Completeness**: Convert remaining TypeScript `private`
|
|
278
|
+
members to `#private` (after verifying they are not reflectively accessed in
|
|
279
|
+
`legacy_test_runner` or `blink/web_tests`), and mark `Fixed: <id>` on this
|
|
280
|
+
final CL.
|
|
281
|
+
|
|
282
|
+
--------------------------------------------------------------------------------
|
|
283
|
+
|
|
284
|
+
## 4. Definition of Done & `Bug:` vs `Fixed:` Completeness Gate
|
|
285
|
+
|
|
286
|
+
> [!WARNING]
|
|
287
|
+
> A clean `@devtools/no-imperative-dom-api` ESLint run does **NOT** prove a UI
|
|
288
|
+
> Eng Vision migration is complete. The linter does not flag `extends UI.TreeOutline.TreeElement` subclasses or `UI.ListControl`.
|
|
289
|
+
|
|
290
|
+
Before closing a UI Eng Vision migration issue with `Fixed: <id>`, verify every
|
|
291
|
+
requirement below. If any item remains incomplete, use `Bug: <id>` and address
|
|
292
|
+
it in a follow-up CL:
|
|
293
|
+
|
|
294
|
+
1. **No Legacy Widgets**: Zero references to `UI.TreeOutline`, `TreeElement`
|
|
295
|
+
subclasses, `UI.ListControl`, `UI.ListWidget`, or `UI.InplaceEditor`.
|
|
296
|
+
2. **Standard MVP Constructor**: Constructor accepts `element?: HTMLElement` as
|
|
297
|
+
its first parameter, resolves dependencies via `static override readonly INJECT`,
|
|
298
|
+
and accepts an injectable `view: View = DEFAULT_VIEW`.
|
|
299
|
+
3. **Widget Update Lifecycle**: Renders exclusively via `override performUpdate(): void`
|
|
300
|
+
and `this.requestUpdate()` (no custom `#renderView()` bypasses or synchronous
|
|
301
|
+
`performUpdate()` calls in presenter methods).
|
|
302
|
+
4. **Non-Destructive Listener Lifecycle**: External model and setting
|
|
303
|
+
listeners are attached in `wasShown()` and detached symmetrically in
|
|
304
|
+
`willHide()`, preserving populated UI state across hide/show cycles.
|
|
305
|
+
5. **Declarative Primitives**: Uses `<devtools-tree>`, `<devtools-list>`,
|
|
306
|
+
persistent `<devtools-prompt ?editing>`, `?hidden=${...}` exclusively
|
|
307
|
+
(without `.hidden` classes), and declarative `autofocus` for default focus.
|
|
308
|
+
6. **ES Private Fields**: Uses ECMAScript `#private` fields and methods for all
|
|
309
|
+
internal members not accessed by `legacy_test_runner` or `blink/web_tests`.
|
|
@@ -55,6 +55,22 @@ logical regressions are introduced during modernization.
|
|
|
55
55
|
});
|
|
56
56
|
```
|
|
57
57
|
|
|
58
|
+
* **Implementation-Decoupled Helpers & Screenshot Baselines Before Replacing Legacy Widgets**:
|
|
59
|
+
When scaffolding unit tests ahead of replacing a legacy widget engine
|
|
60
|
+
(`TreeOutline`, `DataGrid`, `ListControl`, `ListWidget`):
|
|
61
|
+
* **Encapsulate DOM Inspection in Local Helpers**: Route tree, row,
|
|
62
|
+
and element queries through small local helper functions (`dumpTree()`,
|
|
63
|
+
`findTreeItem()`, `activateRow()`, `openContextMenuOnRow()`) rather
|
|
64
|
+
than scattering direct internal widget queries across every `it()`
|
|
65
|
+
block. When the legacy widget is subsequently swapped for
|
|
66
|
+
`<devtools-tree>` or `<devtools-data-grid>`, only the helper
|
|
67
|
+
implementations change while dozens of tests remain untouched.
|
|
68
|
+
* **Mandatory Visual Regression Coverage**: Always add
|
|
69
|
+
`assertScreenshot(...)` golden tests covering critical visual
|
|
70
|
+
states (grouping modes, icons/badges, dimmed/dirty states). Unit
|
|
71
|
+
tests often inspect internal state that changes during migration;
|
|
72
|
+
screenshot goldens ensure the user-visible UI remains identical.
|
|
73
|
+
|
|
58
74
|
4. **Wait for confirmation**:
|
|
59
75
|
|
|
60
76
|
* Wait for an explicit confirmation from the user (or Parent Orchestrator Agent) before proceeding to the next step.
|
|
@@ -78,6 +78,15 @@ clean `UI.Widget` classes that use native update rendering delegates.
|
|
|
78
78
|
* Inspect instantiator files (e.g., `ApplicationPanelSidebar.ts`) and
|
|
79
79
|
decouple any direct accesses to `.element`.
|
|
80
80
|
|
|
81
|
+
4. **Verify Full MVP Architecture Completeness**:
|
|
82
|
+
* Ensure the constructor accepts `element?: HTMLElement` as its first parameter and `view: View = DEFAULT_VIEW` as its last parameter.
|
|
83
|
+
* If `Universe` dependencies are used, declare `static override readonly INJECT = [...] as const;` and receive them as constructor parameter #2.
|
|
84
|
+
* If shadow DOM is needed, use `super(element, {useShadowDom: 'pure'})` (never legacy `useShadowDom: true`).
|
|
85
|
+
* Trigger initial renders and external subscriptions in `wasShown()`, detaching them symmetrically in `willHide()`. Reconcile state incrementally rather than wiping populated presenter state via `reset()` on every re-show.
|
|
86
|
+
* Use `this.requestUpdate()` across all presenter methods and setters; avoid synchronous `this.performUpdate()` calls or custom `#renderView()` methods.
|
|
87
|
+
* Use declarative `autofocus` for default focus targets rather than imperative `focus()` overrides or `ViewOutput` focus closures.
|
|
88
|
+
* Verify that no legacy `UI.TreeOutline`, `extends UI.TreeOutline.TreeElement` subclasses, `UI.ListControl`, `UI.ListWidget`, or `UI.InplaceEditor` remain before marking `Fixed: <id>`. If any remain, use `Bug: <id>`.
|
|
89
|
+
|
|
81
90
|
--------------------------------------------------------------------------------
|
|
82
91
|
|
|
83
92
|
## 2. Safety & Verification Rules
|
|
@@ -92,5 +101,7 @@ clean `UI.Widget` classes that use native update rendering delegates.
|
|
|
92
101
|
*Before reporting back or committing, re-read the instructions and verify:*
|
|
93
102
|
1. ❓ **Decoupling**: Did I remove all direct `.element` or `.contentElement` couplings from instantiator files?
|
|
94
103
|
2. ❓ **Inheritance**: Does the class now cleanly inherit from `UI.Widget` or its variants?
|
|
95
|
-
3. ❓ **Injectability**: Is the view
|
|
96
|
-
4. ❓ **
|
|
104
|
+
3. ❓ **Injectability & Dependencies**: Is the constructor signature `(element?: HTMLElement, [...]: WidgetDependencies, view: View = DEFAULT_VIEW)` with `static override readonly INJECT`?
|
|
105
|
+
4. ❓ **Lifecycle & Reactivity**: Does presenter code call `this.requestUpdate()` asynchronously (no synchronous `performUpdate()`), with non-destructive `wasShown()`/`willHide()` subscriptions?
|
|
106
|
+
5. ❓ **No Legacy Controls**: Are all `TreeOutline`/`TreeElement` subclasses, `ListControl`, and `InplaceEditor` instances eliminated before using `Fixed: <id>`?
|
|
107
|
+
6. ❓ **Build**: Does the code compile and do tests pass?
|