chrome-devtools-frontend 1.0.1733843 → 1.0.1736236
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 +27 -0
- package/.agents/skills/devtools-uistrings/SKILL.md +147 -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 +8 -1
- package/docs/cookbook/localization.md +1 -1
- package/docs/ui_engineering.md +24 -0
- package/eslint.config.mjs +0 -1
- package/front_end/application_tokens.css +1 -1
- package/front_end/core/host/AidaClient.ts +147 -202
- package/front_end/core/host/AidaClientTypes.ts +9 -0
- package/front_end/core/host/AidaErrors.ts +416 -0
- package/front_end/core/host/AidaGcaTranslation.ts +11 -0
- package/front_end/core/host/InspectorFrontendHostAPI.ts +9 -2
- package/front_end/core/host/UserMetrics.ts +25 -0
- package/front_end/core/host/UserMetricsEnums.ts +25 -0
- package/front_end/core/host/host.ts +3 -1
- package/front_end/core/i18n/collect-ui-strings.js +20 -0
- package/front_end/core/root/Runtime.ts +12 -0
- package/front_end/core/sdk/CPUThrottlingManager.ts +3 -0
- package/front_end/core/sdk/EnhancedTracesParser.ts +8 -4
- package/front_end/core/sdk/NetworkManager.ts +0 -6
- package/front_end/core/sdk/OverlayModel.ts +0 -6
- package/front_end/core/sdk/PreloadingModel.ts +30 -13
- package/front_end/core/sdk/PrivateVerificationTokensModel.ts +0 -18
- package/front_end/core/sdk/RehydratingConnection.ts +5 -2
- package/front_end/core/sdk/ResourceTreeModel.ts +0 -42
- package/front_end/core/sdk/ScreenCaptureModel.ts +0 -84
- package/front_end/core/sdk/ServiceWorkerCacheModel.ts +0 -15
- package/front_end/core/sdk/StorageBucketsModel.ts +0 -15
- package/front_end/devtools_compatibility.js +57 -2
- package/front_end/entrypoints/formatter_worker/ScopeParser.ts +4 -2
- package/front_end/entrypoints/inspector_main/RenderingOptions.ts +203 -127
- package/front_end/entrypoints/inspector_main/renderingOptions.css +5 -0
- package/front_end/entrypoints/node_app/app/NodeMain.ts +0 -9
- package/front_end/entrypoints/node_app/app/nodeConnectionsPanel.css +0 -22
- package/front_end/generated/InspectorBackendCommands.ts +1 -1
- package/front_end/generated/SupportedCSSProperties.ts +0 -136
- package/front_end/generated/protocol-proxy-api.d.ts +231 -231
- package/front_end/generated/protocol.ts +1 -0
- package/front_end/models/ai_assistance/AiAgent2.ts +4 -1
- package/front_end/models/ai_assistance/ChangeManager.ts +3 -1
- package/front_end/models/ai_assistance/DOMHelpers.ts +118 -3
- package/front_end/models/ai_assistance/ExtensionScope.ts +31 -24
- package/front_end/models/ai_assistance/agents/AiAgent.ts +6 -0
- package/front_end/models/ai_assistance/agents/PerformanceAgent.snapshot.txt +13 -13
- package/front_end/models/ai_assistance/agents/PerformanceAgent.ts +1 -1
- package/front_end/models/ai_assistance/ai_assistance.ts +2 -0
- package/front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.snapshot.txt +18 -8
- package/front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.ts +2 -2
- package/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.snapshot.txt +103 -81
- package/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.ts +15 -203
- package/front_end/models/ai_assistance/injected.ts +6 -1
- package/front_end/models/ai_assistance/skills/lighthouse.md +1 -1
- package/front_end/models/ai_assistance/skills/styling.md +8 -10
- package/front_end/models/ai_assistance/tools/GetTraceEventByKey.ts +1 -1
- package/front_end/models/ai_assistance/tools/SetElementStyles.ts +288 -0
- package/front_end/models/ai_assistance/tools/Tool.ts +1 -0
- package/front_end/models/ai_assistance/tools/ToolRegistry.ts +3 -0
- package/front_end/models/bindings/ResourceScriptMapping.ts +64 -16
- 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 +41 -1
- package/front_end/models/project_settings/ProjectSettingsModel.ts +1 -1
- package/front_end/models/trace/handlers/FlowsHandler.ts +10 -0
- package/front_end/models/trace/handlers/SamplesHandler.ts +3 -2
- package/front_end/models/trace/handlers/ScriptsHandler.ts +25 -26
- package/front_end/models/trace/helpers/TreeHelpers.ts +4 -0
- package/front_end/models/trace/insights/DuplicatedJavaScript.ts +1 -2
- package/front_end/models/trace/types/TraceEvents.ts +21 -22
- package/front_end/panels/ai_assistance/components/ChatMessage.ts +9 -1
- package/front_end/panels/ai_assistance/components/chatInput.css +4 -4
- package/front_end/panels/animation/AnimationTimeline.ts +3 -3
- package/front_end/panels/animation/animationTimeline.css +6 -4
- package/front_end/panels/application/IndexedDBModel.ts +0 -15
- package/front_end/panels/application/appManifestView.css +2 -5
- package/front_end/panels/application/components/backForwardCacheView.css +1 -5
- package/front_end/panels/application/components/serviceWorkerRouterView.css +2 -2
- package/front_end/panels/application/preloading/components/PreloadingString.ts +7 -0
- 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 +16 -10
- 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/consolePrompt.css +0 -12
- package/front_end/panels/console/consoleView.css +2 -2
- package/front_end/panels/developer_resources/developerResourcesView.css +4 -3
- package/front_end/panels/elements/DOMTreeWidget.ts +29 -9
- package/front_end/panels/elements/StylePropertyTreeElement.ts +2 -1
- package/front_end/panels/elements/components/CSSHintDetailsView.ts +12 -5
- package/front_end/panels/elements/components/cssVariableValueView.css +1 -1
- package/front_end/panels/elements/components/elementsBreadcrumbs.css +2 -2
- package/front_end/panels/elements/domTreeWidget.css +6 -1
- package/front_end/panels/elements/elementsPanel.css +0 -6
- package/front_end/panels/elements/layoutPane.css +1 -1
- 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 +0 -10
- package/front_end/panels/emulation/deviceModeView.css +6 -7
- package/front_end/panels/explain/components/consoleInsight.css +4 -4
- package/front_end/panels/issues/issuesTree.css +1 -26
- package/front_end/panels/lighthouse/lighthouseStartView.css +2 -2
- package/front_end/panels/linear_memory_inspector/components/linearMemoryInspector.css +1 -1
- package/front_end/panels/media/TickingFlameChart.ts +20 -3
- package/front_end/panels/media/playerMessagesView.css +2 -2
- package/front_end/panels/mobile_throttling/ThrottlingSettingsTab.ts +24 -5
- package/front_end/panels/mobile_throttling/throttlingSettingsTab.css +1 -6
- package/front_end/panels/network/networkLogView.css +2 -2
- package/front_end/panels/network/networkTimingTable.css +1 -1
- package/front_end/panels/performance_monitor/performanceMonitor.css +0 -4
- package/front_end/panels/protocol_monitor/JSONEditor.css +1 -1
- package/front_end/panels/protocol_monitor/JSONEditor.ts +4 -2
- package/front_end/panels/recorder/recorderPanel.css +3 -3
- package/front_end/panels/recorder/recordingListView.css +1 -1
- package/front_end/panels/screencast/screencastView.css +1 -1
- package/front_end/panels/search/searchResultsPane.css +1 -1
- package/front_end/panels/security/SecurityModel.ts +0 -6
- package/front_end/panels/security/SecurityPanel.ts +120 -108
- package/front_end/panels/security/originView.css +1 -1
- package/front_end/panels/sensors/locationsSettingsTab.css +3 -3
- package/front_end/panels/settings/EditFileSystemView.ts +159 -104
- package/front_end/panels/settings/editFileSystemView.css +30 -4
- package/front_end/panels/settings/emulation/devicesSettingsTab.css +0 -52
- package/front_end/panels/settings/settingsScreen.css +0 -7
- package/front_end/panels/sources/CallStackSidebarPane.ts +339 -221
- package/front_end/panels/sources/NavigatorView.ts +95 -8
- package/front_end/panels/sources/ThreadsSidebarPane.ts +8 -4
- package/front_end/panels/sources/breakpointsView.css +1 -3
- package/front_end/panels/sources/callStackSidebarPane.css +4 -0
- package/front_end/panels/sources/components/HeadersView.ts +15 -2
- package/front_end/panels/sources/watchExpressionsSidebarPane.css +0 -1
- package/front_end/panels/timeline/CountersGraph.ts +0 -4
- package/front_end/panels/timeline/TimelineLoader.ts +16 -6
- package/front_end/panels/timeline/TimelinePanel.ts +20 -12
- 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/cwvMetrics.css +1 -1
- package/front_end/panels/timeline/components/metricCard.css +1 -1
- package/front_end/panels/timeline/components/sidebarAnnotationsTab.css +4 -4
- package/front_end/panels/timeline/timelineFlameChartView.css +1 -1
- package/front_end/panels/webauthn/WebauthnPane.ts +13 -14
- package/front_end/panels/webauthn/webauthnPane.css +1 -1
- package/front_end/third_party/chromium/README.chromium +1 -1
- 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/input/textInput.css +1 -1
- package/front_end/ui/components/panel_introduction_steps/panelIntroductionSteps.css +6 -4
- package/front_end/ui/components/suggestion_input/suggestionInput.css +2 -2
- package/front_end/ui/components/text_editor/AiCodeGenerationTeaser.ts +14 -2
- package/front_end/ui/legacy/DockController.ts +17 -4
- package/front_end/ui/legacy/Treeoutline.ts +2 -2
- package/front_end/ui/legacy/UIUtils.ts +148 -10
- package/front_end/ui/legacy/components/inline_editor/bezierEditor.css +3 -2
- 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/perf_ui/pieChart.css +1 -1
- 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/components/utils/TargetDetachedDialog.ts +0 -3
- package/front_end/ui/legacy/components/utils/imagePreview.css +1 -1
- package/front_end/ui/legacy/inspectorCommon.css +1 -14
- package/front_end/ui/legacy/inspectorDrawerTabbedPane.css +3 -2
- package/front_end/ui/legacy/listWidget.css +0 -18
- package/front_end/ui/legacy/theme_support/ThemeSupport.ts +44 -9
- package/front_end/ui/lit/strip-whitespace.ts +1 -1
- package/front_end/ui/visual_logging/KnownContextValues.ts +1 -0
- package/package.json +3 -3
- package/front_end/generated/Deprecation.ts +0 -471
- package/front_end/panels/accessibility/axBreadcrumbs.css +0 -155
- package/front_end/panels/network/requestHeadersTree.css +0 -226
- package/front_end/panels/recorder/startView.css +0 -38
- package/front_end/panels/security/ipProtectionView.css +0 -141
- package/front_end/ui/legacy/components/inline_editor/animationNameSwatch.css +0 -27
|
@@ -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
|
+
```
|
|
@@ -42,6 +42,7 @@ Load the skill or `.agents/rules/` files that match what the diff touches, and a
|
|
|
42
42
|
| Ported Chromium web tests (`web_tests/http/tests/devtools`) | `migrate-chromium-test` |
|
|
43
43
|
| Flaky or disabled tests, or `it.skip` / `it.skipOnPlatforms` | `fix-tests` |
|
|
44
44
|
| Rendering user-controlled strings (URLs, names, console text) | `devtools-unicode-escaping` |
|
|
45
|
+
| Adding or modifying `UIStrings` or `@description` / `@example` L10n comments | `devtools-uistrings` |
|
|
45
46
|
| `front_end/models/*`, `BUILD.gn`, `devtools_grd_files.gni`, entrypoints | `devtools-model-management` |
|
|
46
47
|
| Reviewing foundation, models, and build configs (`front_end/(core|models|entrypoints|generated)/**`, `BUILD.gn`, `*.gni`) | `.agents/rules/models-and-core/*.md` |
|
|
47
48
|
| Merging modules or consolidating `BUILD.gn` | `merging-devtools-module` |
|
|
@@ -129,6 +130,13 @@ findings):
|
|
|
129
130
|
scenario.
|
|
130
131
|
- **Fail fast:** Throw or assert when a required value is missing. Don't let
|
|
131
132
|
the test time out later.
|
|
133
|
+
- **Pre-migration tests for legacy widgets:** When reviewing tests added ahead of
|
|
134
|
+
replacing a legacy widget (`TreeOutline`, `DataGrid`, `ListControl`,
|
|
135
|
+
`ListWidget`), check that DOM/tree inspection is encapsulated in local test
|
|
136
|
+
helpers (`dumpTree()`, `findTreeItem()`, `activateRow()`) rather than
|
|
137
|
+
repeated across every `it()` block, and ask for `assertScreenshot(...)` golden
|
|
138
|
+
tests so visual regressions are caught independently of the legacy widget
|
|
139
|
+
implementation.
|
|
132
140
|
|
|
133
141
|
## 6. Test hygiene and cleanup
|
|
134
142
|
|
|
@@ -165,6 +173,25 @@ findings):
|
|
|
165
173
|
characters.
|
|
166
174
|
- For migrations and stacked series, list the legacy tests or files covered,
|
|
167
175
|
and number the series (for example, `(13/16)`).
|
|
176
|
+
- **UI Eng Vision migration completeness & `Fixed:` vs `Bug:`**: Flag
|
|
177
|
+
`Fixed: <id>` on UI Eng Vision migration CLs when core violations remain in
|
|
178
|
+
the target file: legacy `UI.TreeOutline` or `extends UI.TreeOutline.TreeElement`
|
|
179
|
+
subclasses, `UI.ListControl`, `UI.ListWidget`, `UI.InplaceEditor`, non-MVP
|
|
180
|
+
constructors (missing `element?: HTMLElement` or injectable `view = DEFAULT_VIEW`),
|
|
181
|
+
missing `static override readonly INJECT` for Universe dependencies, custom
|
|
182
|
+
`#renderView()` helpers bypassing `override performUpdate()` +
|
|
183
|
+
`this.requestUpdate()`, constructor-bound model/setting listeners instead of
|
|
184
|
+
non-destructive `wasShown()`/`willHide()` subscriptions, synchronous
|
|
185
|
+
`this.performUpdate()` calls in presenter methods, or TypeScript `private`
|
|
186
|
+
fields not required by `legacy_test_runner`/`blink/web_tests`. Note
|
|
187
|
+
explicitly that a clean `@devtools/no-imperative-dom-api` lint pass does
|
|
188
|
+
**not** prove completeness because ESLint misses `TreeElement` subclasses and
|
|
189
|
+
`UI.ListControl`. Intermediate CLs in a multi-CL migration must use
|
|
190
|
+
`Bug: <id>`, reserving `Fixed: <id>` for the final CL.
|
|
191
|
+
- **Component contract preservation**: Flag feature or panel migrations that
|
|
192
|
+
widen `front_end/ui/legacy/` component contracts (such as exporting internal
|
|
193
|
+
classes or turning `*ForTest()` or `*ForTesting()` methods on `Treeoutline.ts`
|
|
194
|
+
into public APIs).
|
|
168
195
|
- Disabled tests reference a bug.
|
|
169
196
|
- Presubmit, lint, and format pass. See `devtools-verification`.
|
|
170
197
|
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: devtools-uistrings
|
|
3
|
+
description: >-
|
|
4
|
+
Reviews added or modified UIStrings and localization (@description / @example)
|
|
5
|
+
comments in Chrome DevTools for UX writing style, inline backtick locking,
|
|
6
|
+
sentence case, UI glossary terminology, translator context, and sibling string
|
|
7
|
+
consistency beyond what ESLint and check-strings.js enforce. Use when a CL or
|
|
8
|
+
local diff adds or edits UIStrings or i18n calls in front_end/. Don't use for
|
|
9
|
+
syntax rules already enforced by l10n ESLint rules or for unlocalized locked
|
|
10
|
+
strings.
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Reviewing DevTools `UIStrings` and Localization Comments
|
|
14
|
+
|
|
15
|
+
Apply these checks when a diff adds or modifies `const UIStrings = { ... }`
|
|
16
|
+
entries or their JSDoc comments in `front_end/`.
|
|
17
|
+
|
|
18
|
+
## 1. Do Not Flag
|
|
19
|
+
|
|
20
|
+
- **Already enforced by ESLint (`scripts/eslint_rules/lib/l10n-*.ts`):** Do not
|
|
21
|
+
comment on curly apostrophes (`’`) vs. straight quotes (`"`) inside
|
|
22
|
+
`UIStrings` values, Unicode ellipses (`…`) vs. `...`, uppercase `URL`,
|
|
23
|
+
negative contractions (`don’t`, `can’t`, `isn’t`, etc.), single- vs.
|
|
24
|
+
multi-sentence trailing periods, whole-phrase backtick locking, or unused keys
|
|
25
|
+
in regular `*.ts` files.
|
|
26
|
+
- **Already enforced by `third_party/i18n/check-strings.js`:** Do not comment
|
|
27
|
+
on missing/empty `@description` tags, missing `@example` tags for `{PH1}`
|
|
28
|
+
placeholders, unclosed backticks, malformed Markdown links, or `\n` literals.
|
|
29
|
+
- **Exempt strings:** Do not flag `UIStringsNotTranslate`,
|
|
30
|
+
`i18n.i18n.lockedString(...)`, or pre-existing `UIStrings` entries that were
|
|
31
|
+
not modified (including verbatim moves during a refactor).
|
|
32
|
+
- **Non-issues:** Do not nitpick minor `@description` lead-in wording variations
|
|
33
|
+
that are equally clear to translators (e.g., `Tooltip text for…` vs. `Tooltip
|
|
34
|
+
for…`), and do not force synonym swaps where grammar or spec precision breaks
|
|
35
|
+
(e.g., `a suitable Cross-Origin Resource Policy` where `a fit …` is
|
|
36
|
+
ungrammatical, or RFC terms like `additional parameters`).
|
|
37
|
+
|
|
38
|
+
## 2. Shared Capitalization & DevTools UI Terminology
|
|
39
|
+
|
|
40
|
+
Apply these rules consistently in both `UIStrings` values and `@description`
|
|
41
|
+
comments:
|
|
42
|
+
|
|
43
|
+
- **Sentence case:** Capitalize only the first word, proper nouns, product
|
|
44
|
+
names (`Chrome DevTools`), acronyms, backtick-locked spec terms (e.g.,
|
|
45
|
+
`` '`Trusted Type` violations' ``), and web platform APIs / worker types
|
|
46
|
+
(`Background Fetch API`, `Service Worker` / `Service Workers`, `Web Worker` /
|
|
47
|
+
`Web Workers`).
|
|
48
|
+
- **Panels vs. features/concepts:**
|
|
49
|
+
- Capitalize user-facing panel names (`Console`, `Network`, `Elements`,
|
|
50
|
+
`Sources`, `Performance`, `Memory`, `Application`, `Security`,
|
|
51
|
+
`Lighthouse`, `Recorder`, `Issues`). For multi-word panel or tab names,
|
|
52
|
+
capitalize only the first word (`Developer resources panel`, `Memory
|
|
53
|
+
inspector panel`, `Remote devices tab`). When paired with a noun, keep the
|
|
54
|
+
second word lowercase (`Console panel`, `Console sidebar`, `Memory panel`).
|
|
55
|
+
- Map internal folder or class names to user-facing panel names (`profiler` ->
|
|
56
|
+
`Memory panel`, `Timeline UIUtils` -> `Performance panel`,
|
|
57
|
+
`linear_memory_inspector` -> `Memory inspector panel`).
|
|
58
|
+
- Keep feature, view, tool, and concept names **lowercase** unless starting a
|
|
59
|
+
sentence (`conditional breakpoint`, `command menu`, `quick open`, `heap
|
|
60
|
+
profiler`, `heap snapshot view`, `allocation sampling`, `isolate selector`,
|
|
61
|
+
`summary view`, `console message`, `network log`).
|
|
62
|
+
- **UI glossary & platform terms:** Use `panel`, `tab`, `drawer`, `sidebar`,
|
|
63
|
+
`table` (or `datagrid`), `action bar`, and `status bar`; never call a tab,
|
|
64
|
+
sidebar, or section a `pane`. Prefer `JavaScript modules` over `ES modules`,
|
|
65
|
+
and write `top level` with a space when used as a noun (`The top level of
|
|
66
|
+
JavaScript modules`).
|
|
67
|
+
|
|
68
|
+
## 3. User-Facing String Values
|
|
69
|
+
|
|
70
|
+
- **Prefer short, everyday synonyms (when grammatical and spec-accurate):**
|
|
71
|
+
- `preserve` -> `keep` | `additional` -> `more` | `prevent` -> `stop`
|
|
72
|
+
- `submit` -> `send` | `modification` -> `change` | `create` -> `add` |
|
|
73
|
+
`suitable` -> `fit`
|
|
74
|
+
- `receive` -> `get` in general prose (e.g., `get the reports`), **except**
|
|
75
|
+
keep `receive` / `received` for network or worker data/message reception
|
|
76
|
+
(e.g., `receive data while cached`, `received a message from a
|
|
77
|
+
SharedWorker`).
|
|
78
|
+
- **Cut filler, politeness & banned branding:** Remove `please`, `sorry`,
|
|
79
|
+
`very`, `strongly`, `there is` / `there are`, marketing adjectives
|
|
80
|
+
(`seamless`, `awesome`, `fast`, `quick`), and `"Powered by AI"` (use neutral
|
|
81
|
+
action labels such as `'Understand this message'`).
|
|
82
|
+
- **Inline backtick-locking (`\`...\``):** Wrap embedded technical tokens (CSS
|
|
83
|
+
properties, values, and media features like `` `print` ``, `` `screen` ``,
|
|
84
|
+
`` `prefers-color-scheme` ``; HTTP headers like `` `Alt-Svc` ``; HTML
|
|
85
|
+
attributes; and JS APIs like `` `console.clear()` ``) in backticks so
|
|
86
|
+
translators do not translate them. Keep spec capitalization inside backticks
|
|
87
|
+
while using sentence case outside (`` '`Trusted Type` violations' ``).
|
|
88
|
+
- **Articles, positive contractions, symbols & actionability:** Avoid fragile
|
|
89
|
+
`a` / `an` articles before `{PH1}` placeholders or initialisms (`HTTP`, `XHR`)
|
|
90
|
+
when shorter article-free phrasing works. Use natural positive contractions
|
|
91
|
+
not checked by ESLint (`it’s`, `you’re`, `we’re`, `that’s`, with curly `’`),
|
|
92
|
+
and use prime (`′`) and double prime (`″`) for measurements or coordinates.
|
|
93
|
+
State how to recover in error messages (e.g., `Shorten filename to 64
|
|
94
|
+
characters or less` instead of `Invalid filename`).
|
|
95
|
+
|
|
96
|
+
## 4. Localization Comments (`@description` & `@example`)
|
|
97
|
+
|
|
98
|
+
- **Explain UI role and concrete sub-location, never repeat the string:**
|
|
99
|
+
Inspect where `UIStrings.<key>` is called and name the UI element type (button
|
|
100
|
+
label, tooltip, column header, checkbox label, context menu item,
|
|
101
|
+
`aria-label`, status text) and concrete panel/sub-view location instead of
|
|
102
|
+
echoing the message text. Keep specific sub-locations such as `in the summary
|
|
103
|
+
view of the Performance panel` rather than collapsing them to `in the
|
|
104
|
+
Performance panel`.
|
|
105
|
+
- **No internal code or protocol names:** Do not reference C++ identifiers, CDP
|
|
106
|
+
enum names, or class names in `@description` comments. Describe the
|
|
107
|
+
user-visible state instead.
|
|
108
|
+
- **Verify `@example` values against the call site:** Check what
|
|
109
|
+
`i18nString(UIStrings.<key>, {PH1: ...})` passes at runtime (especially
|
|
110
|
+
whether units like `%` or `ms` are already formatted inside `{PH1}` vs.
|
|
111
|
+
outside in the template, e.g., `@example {12.34%} PH2`) and use realistic
|
|
112
|
+
runtime values rather than type names like `{string}`. Do not ask for
|
|
113
|
+
`@example` tags on ICU plural count variables.
|
|
114
|
+
- **Comment formatting:** Use straight apostrophes (`'`) and straight quotes
|
|
115
|
+
(`"`) in code comments (even when `UIStrings` uses curly `’`), and end every
|
|
116
|
+
`@description` with a period (`.`).
|
|
117
|
+
|
|
118
|
+
```ts
|
|
119
|
+
// Bad: repeats the string, uses internal/legacy names, unlocked token, vague example
|
|
120
|
+
/**
|
|
121
|
+
* @description Text for preserve log checkbox in Timeline UIUtils Pane
|
|
122
|
+
* @example {string} PH1
|
|
123
|
+
*/
|
|
124
|
+
preserveLog: 'Please preserve additional print log entries in {PH1}',
|
|
125
|
+
|
|
126
|
+
// Good: role + sub-location, sentence case, locked token, realistic example
|
|
127
|
+
/**
|
|
128
|
+
* @description Checkbox label in the summary view of the Performance panel to
|
|
129
|
+
* keep log entries across page loads.
|
|
130
|
+
* @example {https://example.com} PH1
|
|
131
|
+
*/
|
|
132
|
+
keepLog: 'Keep more `print` log entries for {PH1}',
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## 5. Neighbor, Module & Linter-Gap Consistency
|
|
136
|
+
|
|
137
|
+
- **Adjacent `UIStrings` & `-meta.ts` alignment:** Compare added or edited
|
|
138
|
+
entries against neighboring entries in the same `UIStrings` block and
|
|
139
|
+
companion `-meta.ts` file so panel names, feature casing, inline backticks,
|
|
140
|
+
and separators (`or` vs. `/`) stay consistent across sibling strings.
|
|
141
|
+
- **Quoted label renames:** When a CL renames a setting or button label (e.g.,
|
|
142
|
+
`Preserve log` -> `Keep log`), check sibling files in the same module for
|
|
143
|
+
explanatory `UIStrings` that quote the old label (e.g., `` '`console.clear()`
|
|
144
|
+
was prevented due to \'Keep log\'' ``) and update them together.
|
|
145
|
+
- **Unused keys in linter-exempt files:** `l10n-no-unused-message` skips
|
|
146
|
+
`ModuleUIStrings.ts` and `models/trace/insights/*.ts`; flag orphaned keys
|
|
147
|
+
left behind in those files when their last caller is removed.
|
|
@@ -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
|
-
|