devtools-tracing 1.0.0

package/lib/front_end/core/common/Revealer.ts

@@ -0,0 +1,192 @@
+// Copyright 2014 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as i18n from '../i18n/i18n.js';
+import type * as Platform from '../platform/platform.js';
+
+const UIStrings = {
+  /**
+   * @description The UI destination when right clicking an item that can be revealed
+   */
+  elementsPanel: 'Elements panel',
+  /**
+   * @description The UI destination when right clicking an item that can be revealed
+   */
+  stylesSidebar: 'styles sidebar',
+  /**
+   * @description The UI destination when right clicking an item that can be revealed
+   */
+  changesDrawer: 'Changes drawer',
+  /**
+   * @description The UI destination when right clicking an item that can be revealed
+   */
+  issuesView: 'Issues view',
+  /**
+   * @description The UI destination when right clicking an item that can be revealed
+   */
+  networkPanel: 'Network panel',
+  /**
+   * @description The UI destination when right clicking an item that can be revealed
+   */
+  applicationPanel: 'Application panel',
+  /**
+   * @description The UI destination when right clicking an item that can be revealed
+   */
+  securityPanel: 'Security panel',
+  /**
+   * @description The UI destination when right clicking an item that can be revealed
+   */
+  sourcesPanel: 'Sources panel',
+  /**
+   * @description The UI destination when right clicking an item that can be revealed
+   */
+  timelinePanel: 'Performance panel',
+  /**
+   * @description The UI destination when right clicking an item that can be revealed
+   */
+  memoryInspectorPanel: 'Memory inspector panel',
+  /**
+   * @description The UI destination when revealing loaded resources through the Developer Resources Panel
+   */
+  developerResourcesPanel: 'Developer Resources panel',
+  /**
+   * @description The UI destination when revealing loaded resources through the Animations panel
+   */
+  animationsPanel: 'Animations panel',
+} as const;
+const str_ = i18n.i18n.registerUIStrings('core/common/Revealer.ts', UIStrings);
+const i18nLazyString = i18n.i18n.getLazilyComputedLocalizedString.bind(undefined, str_);
+
+/**
+ * Interface for global revealers, which are entities responsible for
+ * dealing with revealing certain types of objects. For example, the
+ * Sources panel will register a revealer for `UISourceCode` objects,
+ * which will ensure that its visible in an editor tab.
+ */
+export interface Revealer<T> {
+  reveal(revealable: T, omitFocus?: boolean): Promise<void>;
+}
+
+let revealerRegistry: RevealerRegistry|undefined;
+
+/**
+ * Registration for revealers, which deals with keeping a list of all possible
+ * revealers, lazily instantiating them as necessary and invoking their `reveal`
+ * methods depending on the _context types_ they were registered for.
+ *
+ * @see Revealer
+ */
+export class RevealerRegistry {
+  private readonly registeredRevealers: Array<RevealerRegistration<unknown>> = [];
+
+  /**
+   * Yields the singleton instance, creating it on-demand when necessary.
+   *
+   * @returns the singleton instance.
+   */
+  static instance(): RevealerRegistry {
+    if (revealerRegistry === undefined) {
+      revealerRegistry = new RevealerRegistry();
+    }
+    return revealerRegistry;
+  }
+
+  /**
+   * Clears the singleton instance (if any).
+   */
+  static removeInstance(): void {
+    revealerRegistry = undefined;
+  }
+
+  /**
+   * Register a new `Revealer` as described by the `registration`.
+   *
+   * @param registration the description.
+   */
+  register(registration: RevealerRegistration<unknown>): void {
+    this.registeredRevealers.push(registration);
+  }
+
+  /**
+   * Reveals the `revealable`.
+   *
+   * @param revealable the object to reveal.
+   * @param omitFocus whether to omit focusing on the presentation of `revealable` afterwards.
+   */
+  async reveal(revealable: unknown, omitFocus: boolean): Promise<void> {
+    const revealers = await Promise.all(
+        this.getApplicableRegisteredRevealers(revealable).map(registration => registration.loadRevealer()));
+    if (revealers.length < 1) {
+      throw new Error(`No revealers found for ${revealable}`);
+    }
+    if (revealers.length > 1) {
+      throw new Error(`Conflicting reveals found for ${revealable}`);
+    }
+    return await revealers[0].reveal(revealable, omitFocus);
+  }
+
+  getApplicableRegisteredRevealers(revealable: unknown): Array<RevealerRegistration<unknown>> {
+    return this.registeredRevealers.filter(registration => {
+      for (const contextType of registration.contextTypes()) {
+        if (revealable instanceof contextType) {
+          return true;
+        }
+      }
+      return false;
+    });
+  }
+}
+
+export function revealDestination(revealable: unknown): string|null {
+  const revealers = RevealerRegistry.instance().getApplicableRegisteredRevealers(revealable);
+  for (const {destination} of revealers) {
+    if (destination) {
+      return destination();
+    }
+  }
+  return null;
+}
+
+/**
+ * Register a new `Revealer` as described by the `registration` on the singleton
+ * {@link RevealerRegistry} instance.
+ *
+ * @param registration the description.
+ */
+export function registerRevealer<T>(registration: RevealerRegistration<T>): void {
+  RevealerRegistry.instance().register(registration);
+}
+
+/**
+ * Reveals the `revealable` via the singleton {@link RevealerRegistry} instance.
+ *
+ * @param revealable the object to reveal.
+ * @param omitFocus whether to omit focusing on the presentation of `revealable` afterwards.
+ */
+export async function reveal(revealable: unknown, omitFocus = false): Promise<void> {
+  await RevealerRegistry.instance().reveal(revealable, omitFocus);
+}
+
+export interface RevealerRegistration<T> {
+  contextTypes: () => Array<abstract new(...any: any[]) => T>;
+  loadRevealer: () => Promise<Revealer<T>>;
+  destination?: RevealerDestination;
+}
+
+export const RevealerDestination = {
+  DEVELOPER_RESOURCES_PANEL: i18nLazyString(UIStrings.developerResourcesPanel),
+  ELEMENTS_PANEL: i18nLazyString(UIStrings.elementsPanel),
+  STYLES_SIDEBAR: i18nLazyString(UIStrings.stylesSidebar),
+  CHANGES_DRAWER: i18nLazyString(UIStrings.changesDrawer),
+  ISSUES_VIEW: i18nLazyString(UIStrings.issuesView),
+  NETWORK_PANEL: i18nLazyString(UIStrings.networkPanel),
+  TIMELINE_PANEL: i18nLazyString(UIStrings.timelinePanel),
+  APPLICATION_PANEL: i18nLazyString(UIStrings.applicationPanel),
+  SOURCES_PANEL: i18nLazyString(UIStrings.sourcesPanel),
+  SECURITY_PANEL: i18nLazyString(UIStrings.securityPanel),
+  MEMORY_INSPECTOR_PANEL: i18nLazyString(UIStrings.memoryInspectorPanel),
+  ANIMATIONS_PANEL: i18nLazyString(UIStrings.animationsPanel),
+};
+
+export type RevealerDestination = () => Platform.UIString.LocalizedString;

package/lib/front_end/core/common/Runnable.ts

@@ -0,0 +1,41 @@
+// Copyright 2019 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+export interface Runnable {
+  run(): Promise<void>;
+}
+
+type LateInitializationLoader = () => Promise<Runnable>;
+export interface LateInitializableRunnableSetting {
+  id: string;
+  loadRunnable: LateInitializationLoader;
+}
+
+const registeredLateInitializationRunnables = new Map<string, LateInitializationLoader>();
+
+export function registerLateInitializationRunnable(setting: LateInitializableRunnableSetting): void {
+  const {id, loadRunnable} = setting;
+  if (registeredLateInitializationRunnables.has(id)) {
+    throw new Error(`Duplicate late Initializable runnable id '${id}'`);
+  }
+  registeredLateInitializationRunnables.set(id, loadRunnable);
+}
+
+export function maybeRemoveLateInitializationRunnable(runnableId: string): boolean {
+  return registeredLateInitializationRunnables.delete(runnableId);
+}
+
+export function lateInitializationRunnables(): LateInitializationLoader[] {
+  return [...registeredLateInitializationRunnables.values()];
+}
+
+const registeredEarlyInitializationRunnables: Array<() => Runnable> = [];
+
+export function registerEarlyInitializationRunnable(runnable: () => Runnable): void {
+  registeredEarlyInitializationRunnables.push(runnable);
+}
+
+export function earlyInitializationRunnables(): Array<() => Runnable> {
+  return registeredEarlyInitializationRunnables;
+}

package/lib/front_end/core/common/SegmentedRange.ts

@@ -0,0 +1,87 @@
+// Copyright 2016 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as Platform from '../platform/platform.js';
+
+export class Segment<T> {
+  begin: number;
+  end: number;
+  data: T;
+
+  constructor(begin: number, end: number, data: T) {
+    if (begin > end) {
+      throw new Error('Invalid segment');
+    }
+    this.begin = begin;
+    this.end = end;
+    this.data = data;
+  }
+
+  intersects(that: Segment<T>): boolean {
+    return this.begin < that.end && that.begin < this.end;
+  }
+}
+
+export class SegmentedRange<T> {
+  #segments: Array<Segment<T>>;
+  readonly #mergeCallback: ((arg0: Segment<T>, arg1: Segment<T>) => Segment<T>| null)|undefined;
+
+  constructor(mergeCallback?: ((arg0: Segment<T>, arg1: Segment<T>) => Segment<T>| null)) {
+    this.#segments = [];
+    this.#mergeCallback = mergeCallback;
+  }
+
+  append(newSegment: Segment<T>): void {
+    // 1. Find the proper insertion point for new segment
+    let startIndex = Platform.ArrayUtilities.lowerBound(this.#segments, newSegment, (a, b) => a.begin - b.begin);
+    let endIndex = startIndex;
+    let merged: (Segment<T>|null)|null = null;
+    if (startIndex > 0) {
+      // 2. Try mering the preceding segment
+      const precedingSegment = this.#segments[startIndex - 1];
+      merged = this.tryMerge(precedingSegment, newSegment);
+      if (merged) {
+        --startIndex;
+        newSegment = merged;
+      } else if (this.#segments[startIndex - 1].end >= newSegment.begin) {
+        // 2a. If merge failed and segments overlap, adjust preceding segment.
+        // If an old segment entirely contains new one, split it in two.
+        if (newSegment.end < precedingSegment.end) {
+          this.#segments.splice(
+              startIndex, 0, new Segment<T>(newSegment.end, precedingSegment.end, precedingSegment.data));
+        }
+        precedingSegment.end = newSegment.begin;
+      }
+    }
+    // 3. Consume all segments that are entirely covered by the new one.
+    while (endIndex < this.#segments.length && this.#segments[endIndex].end <= newSegment.end) {
+      ++endIndex;
+    }
+    // 4. Merge or adjust the succeeding segment if it overlaps.
+    if (endIndex < this.#segments.length) {
+      merged = this.tryMerge(newSegment, this.#segments[endIndex]);
+      if (merged) {
+        endIndex++;
+        newSegment = merged;
+      } else if (newSegment.intersects(this.#segments[endIndex])) {
+        this.#segments[endIndex].begin = newSegment.end;
+      }
+    }
+    this.#segments.splice(startIndex, endIndex - startIndex, newSegment);
+  }
+
+  segments(): Array<Segment<T>> {
+    return this.#segments;
+  }
+
+  private tryMerge(first: Segment<T>, second: Segment<T>): Segment<T>|null {
+    const merged = this.#mergeCallback && this.#mergeCallback(first, second);
+    if (!merged) {
+      return null;
+    }
+    merged.begin = first.begin;
+    merged.end = Math.max(first.end, second.end);
+    return merged;
+  }
+}

package/lib/front_end/core/common/SettingRegistration.ts

@@ -0,0 +1,339 @@
+// Copyright 2020 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import * as i18n from '../i18n/i18n.js';
+import type * as Platform from '../platform/platform.js';
+import * as Root from '../root/root.js';
+
+import type {SettingStorageType} from './Settings.js';
+
+const UIStrings = {
+  /**
+   * @description Title of the Elements Panel
+   */
+  elements: 'Elements',
+  /**
+   * @description Text for DevTools AI
+   */
+  ai: 'AI',
+  /**
+   * @description Text for DevTools appearance
+   */
+  appearance: 'Appearance',
+  /**
+   * @description Name of the Sources panel
+   */
+  sources: 'Sources',
+  /**
+   * @description Title of the Network tool
+   */
+  network: 'Network',
+  /**
+   * @description Text for the performance of something
+   */
+  performance: 'Performance',
+  /**
+   * @description Title of the Console tool
+   */
+  console: 'Console',
+  /**
+   * @description A title of the 'Persistence' setting category
+   */
+  persistence: 'Persistence',
+  /**
+   * @description Text that refers to the debugger
+   */
+  debugger: 'Debugger',
+  /**
+   * @description Text describing global shortcuts and settings that are available throughout the DevTools
+   */
+  global: 'Global',
+  /**
+   * @description Title of the Rendering tool
+   */
+  rendering: 'Rendering',
+  /**
+   * @description Title of a section on CSS Grid tooling
+   */
+  grid: 'Grid',
+  /**
+   * @description Text for the mobile platform, as opposed to desktop
+   */
+  mobile: 'Mobile',
+  /**
+   * @description Text for the memory of the page
+   */
+  memory: 'Memory',
+  /**
+   * @description Text for the extension of the page
+   */
+  extension: 'Extension',
+  /**
+   * @description Text for the adorner of the page
+   */
+  adorner: 'Adorner',
+  /**
+   * @description Header for the "Account" section in the settings UI. The "Account"
+   * section allows users see their signed in account and configure which DevTools data is synced via Chrome Sync.
+   */
+  account: 'Account',
+  /**
+   * @description Text for the privacy section of the page.
+   */
+  privacy: 'Privacy',
+} as const;
+const str_ = i18n.i18n.registerUIStrings('core/common/SettingRegistration.ts', UIStrings);
+const i18nString = i18n.i18n.getLocalizedString.bind(undefined, str_);
+let registeredSettings: SettingRegistration[] = [];
+const settingNameSet = new Set<string>();
+
+export function registerSettingExtension(registration: SettingRegistration): void {
+  const settingName = registration.settingName;
+  if (settingNameSet.has(settingName)) {
+    throw new Error(`Duplicate setting name '${settingName}'`);
+  }
+  settingNameSet.add(settingName);
+  registeredSettings.push(registration);
+}
+
+export function getRegisteredSettings(): SettingRegistration[] {
+  return registeredSettings.filter(setting => Root.Runtime.Runtime.isDescriptorEnabled(setting));
+}
+
+export function registerSettingsForTest(settings: SettingRegistration[], forceReset = false): void {
+  if (registeredSettings.length === 0 || forceReset) {
+    registeredSettings = settings;
+    settingNameSet.clear();
+    for (const setting of settings) {
+      const settingName = setting.settingName;
+      if (settingNameSet.has(settingName)) {
+        throw new Error(`Duplicate setting name '${settingName}'`);
+      }
+      settingNameSet.add(settingName);
+    }
+  }
+}
+
+export function resetSettings(): void {
+  registeredSettings = [];
+  settingNameSet.clear();
+}
+
+export function maybeRemoveSettingExtension(settingName: string): boolean {
+  const settingIndex = registeredSettings.findIndex(setting => setting.settingName === settingName);
+  if (settingIndex < 0 || !settingNameSet.delete(settingName)) {
+    return false;
+  }
+  registeredSettings.splice(settingIndex, 1);
+  return true;
+}
+
+export const enum SettingCategory {
+  NONE = '',  // `NONE` must be a falsy value. Legacy code uses if-checks for the category.
+  ELEMENTS = 'ELEMENTS',
+  AI = 'AI',
+  APPEARANCE = 'APPEARANCE',
+  SOURCES = 'SOURCES',
+  NETWORK = 'NETWORK',
+  PERFORMANCE = 'PERFORMANCE',
+  CONSOLE = 'CONSOLE',
+  PERSISTENCE = 'PERSISTENCE',
+  DEBUGGER = 'DEBUGGER',
+  GLOBAL = 'GLOBAL',
+  RENDERING = 'RENDERING',
+  GRID = 'GRID',
+  MOBILE = 'MOBILE',
+  EMULATION = 'EMULATION',
+  MEMORY = 'MEMORY',
+  EXTENSIONS = 'EXTENSIONS',
+  ADORNER = 'ADORNER',
+  ACCOUNT = 'ACCOUNT',
+  PRIVACY = 'PRIVACY',
+}
+
+export function getLocalizedSettingsCategory(category: SettingCategory): Platform.UIString.LocalizedString {
+  switch (category) {
+    case SettingCategory.ELEMENTS:
+      return i18nString(UIStrings.elements);
+    case SettingCategory.AI:
+      return i18nString(UIStrings.ai);
+    case SettingCategory.APPEARANCE:
+      return i18nString(UIStrings.appearance);
+    case SettingCategory.SOURCES:
+      return i18nString(UIStrings.sources);
+    case SettingCategory.NETWORK:
+      return i18nString(UIStrings.network);
+    case SettingCategory.PERFORMANCE:
+      return i18nString(UIStrings.performance);
+    case SettingCategory.CONSOLE:
+      return i18nString(UIStrings.console);
+    case SettingCategory.PERSISTENCE:
+      return i18nString(UIStrings.persistence);
+    case SettingCategory.DEBUGGER:
+      return i18nString(UIStrings.debugger);
+    case SettingCategory.GLOBAL:
+      return i18nString(UIStrings.global);
+    case SettingCategory.RENDERING:
+      return i18nString(UIStrings.rendering);
+    case SettingCategory.GRID:
+      return i18nString(UIStrings.grid);
+    case SettingCategory.MOBILE:
+      return i18nString(UIStrings.mobile);
+    case SettingCategory.EMULATION:
+      return i18nString(UIStrings.console);
+    case SettingCategory.MEMORY:
+      return i18nString(UIStrings.memory);
+    case SettingCategory.EXTENSIONS:
+      return i18nString(UIStrings.extension);
+    case SettingCategory.ADORNER:
+      return i18nString(UIStrings.adorner);
+    case SettingCategory.NONE:
+      return i18n.i18n.lockedString('');
+    case SettingCategory.ACCOUNT:
+      return i18nString(UIStrings.account);
+    case SettingCategory.PRIVACY:
+      return i18nString(UIStrings.privacy);
+  }
+}
+
+export const enum SettingType {
+  ARRAY = 'array',
+  REGEX = 'regex',
+  ENUM = 'enum',
+  BOOLEAN = 'boolean',
+}
+
+export interface RegExpSettingItem {
+  /**
+   * A regular expression matched against URLs for ignore listing.
+   */
+  pattern: string;
+  /**
+   * If true, ignore this rule.
+   */
+  disabled?: boolean;
+  /**
+   * When a rule is disabled due to requesting through a script's context menu
+   * that it no longer be ignore listed, this field is set to the URL of that
+   * script, so that if the user requests through the same context menu to
+   * enable ignore listing, the rule can be reenabled.
+   */
+  disabledForUrl?: Platform.DevToolsPath.UrlString;
+}
+
+export interface SettingRegistration {
+  /**
+   * The category with which the setting is displayed in the UI.
+   */
+  category?: SettingCategory;
+  /**
+   * Used to sort on screen the settings that belong to the same category.
+   */
+  order?: number;
+  /**
+   * The title with which the setting is shown on screen.
+   */
+  title?: () => Platform.UIString.LocalizedString;
+  /**
+   * The identifier of the setting.
+   */
+  settingName: string;
+  /**
+   * Determines how the possible values of the setting are expressed.
+   *
+   * - If the setting can only be enabled and disabled use BOOLEAN
+   * - If the setting has a list of possible values use ENUM
+   * - If each setting value is a set of objects use ARRAY
+   * - If the setting value is a regular expression use REGEX
+   */
+  settingType: SettingType;
+  /**
+   * The value set by default to the setting.
+   */
+  defaultValue: unknown;
+  /**
+   * Words used to find a setting in the Command Menu.
+   */
+  tags?: Array<() => Platform.UIString.LocalizedString>;
+  /**
+   * The possible values the setting can have, each with a description composed of a title and an optional text.
+   */
+  options?: SettingExtensionOption[];
+  /**
+   * Whether DevTools must be reloaded for a change in the setting to take effect.
+   */
+  reloadRequired?: boolean;
+  /**
+   * Determines if the setting value is stored in the global, local or session storage.
+   */
+  storageType?: SettingStorageType;
+  /**
+   * A condition that, when present in the queryParamsObject of Runtime, constraints the value
+   * of the setting to be changed only if the user set it.
+   */
+  userActionCondition?: string;
+  /**
+   * The name of the experiment a setting is associated with. Enabling and disabling the declared
+   * experiment will enable and disable the setting respectively.
+   */
+  experiment?: Root.Runtime.ExperimentName;
+  /**
+   * A condition is a function that will make the setting available if it
+   * returns true, and not available, otherwise. Make sure that objects you
+   * access from inside the condition function are ready at the time when the
+   * setting conditions are checked.
+   */
+  condition?: Root.Runtime.Condition;
+
+  /**
+   * A function that returns true if the setting should be disabled, along with
+   * the reason why.
+   */
+  disabledCondition?: (config?: Root.Runtime.HostConfig) => DisabledConditionResult;
+
+  /**
+   * If a setting is deprecated, define this notice to show an appropriate warning according to the `warning` property.
+   * If `disabled` is set, the setting will be disabled in the settings UI. In that case, `experiment` optionally can be
+   * set to link to an experiment (by experiment name). The information icon in the settings UI can then be clicked to
+   * jump to the experiment. If a setting is not disabled, the experiment entry will be ignored.
+   */
+  deprecationNotice?: {disabled: boolean, warning: () => Platform.UIString.LocalizedString, experiment?: string};
+
+  /**
+   * Optional information to learn more about the setting. If provided, a `(?)` icon will show next to the setting
+   * in the Settings panel with a link to learn more, and the `tooltip` will be presented to the user when hovering
+   * the `(?)` icon.
+   */
+  learnMore?: LearnMore;
+}
+
+/**
+ * Metadata to learn more about a setting. The `url` will be used to construct
+ * a `(?)` icon link and the `tooltip` will be shown when hovering the icon.
+ */
+export interface LearnMore {
+  tooltip: () => Platform.UIString.LocalizedString;
+  url?: Platform.DevToolsPath.UrlString;
+}
+
+interface LocalizedSettingExtensionOption {
+  value: boolean|string;
+  title: () => Platform.UIString.LocalizedString;
+  text?: () => Platform.UIString.LocalizedString;
+  raw?: false;
+}
+interface RawSettingExtensionOption {
+  value: boolean|string;
+  title: () => Platform.UIString.LocalizedString;
+  /**
+   * Text used to describe the option. Must be localized if 'raw' is false.
+   */
+  text?: string;
+  raw: true;
+}
+export type SettingExtensionOption = LocalizedSettingExtensionOption|RawSettingExtensionOption;
+export type DisabledConditionResult = {
+  disabled: true,
+  reasons: Platform.UIString.LocalizedString[],
+}|{disabled: false};