chrome-devtools-frontend 1.0.1013367 → 1.0.1014853

package/scripts/webidl-properties/config.js

@@ -0,0 +1,345 @@
+// Copyright 2022 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/**
+ * All the specs relevant for generating the DOM pinned properties dataset.
+ * These strings represent file names. A list of all file names can be found at
+ * https://github.com/w3c/webref/tree/main/tr/idl or via the @webref/idl API.
+ *
+ * These spec names are included in the generated dataset. To keep it small,
+ * the values are bitwise or'd.
+ */
+export const SPECS = {
+  'html': 1,
+  'dom': 2,
+  'uievents': 4,
+  'pointerevents': 8,
+  'cssom': 16,
+  'wai-aria': 32
+};
+
+/**
+ * All the "global" attributes as defined in the DOM specification.
+ * Used to annotate the extracted properties from the WebIDL types.
+ */
+export const GLOBAL_ATTRIBUTES = new Set([
+  // https://html.spec.whatwg.org/multipage/dom.html#global-attributes
+  'accesskey', 'autocapitalize', 'autofocus', 'contenteditable', 'dir',      'draggable', 'enterkeyhint',
+  'hidden',    'inputmode',      'is',        'itemid',          'itemprop', 'itemref',   'itemscope',
+  'itemtype',  'lang',           'nonce',     'spellcheck',      'style',    'tabindex',  'title',
+  'translate',
+]);
+
+/**
+ * The "applicable" members for certain "states" that WebIDL types can be in.
+ * In other words, some members are "valid" only valid in certain situations:
+ * for example, with the HTML input element, the set of valid members are
+ * determined by the "type" property.
+ */
+export const APPLICABLE_MEMBERS = {
+  // https://html.spec.whatwg.org/multipage/input.html#input-type-attr-summary
+  HTMLInputElement: [
+    {
+      rule: {when: 'type', is: 'hidden'},
+      members: new Set([
+        'autocomplete',
+        'value',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'text'},
+      members: new Set([
+        'autocomplete',
+        'dirname',
+        'list',
+        'maxlength',
+        'minlength',
+        'pattern',
+        'placeholder',
+        'readonly',
+        'required',
+        'size',
+        'value',
+        'list',
+        'selectionstart',
+        'selectionend',
+        'selectiondirection',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'search'},
+      members: new Set([
+        'autocomplete',
+        'dirname',
+        'list',
+        'maxlength',
+        'minlength',
+        'pattern',
+        'placeholder',
+        'readonly',
+        'required',
+        'size',
+        'value',
+        'list',
+        'selectionstart',
+        'selectionend',
+        'selectiondirection',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'url'},
+      members: new Set([
+        'autocomplete',
+        'list',
+        'maxlength',
+        'minlength',
+        'pattern',
+        'placeholder',
+        'readonly',
+        'required',
+        'size',
+        'value',
+        'list',
+        'selectionstart',
+        'selectionend',
+        'selectiondirection',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'tel'},
+      members: new Set([
+        'autocomplete',
+        'list',
+        'maxlength',
+        'minlength',
+        'pattern',
+        'placeholder',
+        'readonly',
+        'required',
+        'size',
+        'value',
+        'list',
+        'selectionstart',
+        'selectionend',
+        'selectiondirection',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'email'},
+      members: new Set([
+        'autocomplete',
+        'list',
+        'maxlength',
+        'minlength',
+        'multiple',
+        'pattern',
+        'placeholder',
+        'readonly',
+        'required',
+        'size',
+        'value',
+        'list',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'password'},
+      members: new Set([
+        'autocomplete',
+        'maxlength',
+        'minlength',
+        'pattern',
+        'placeholder',
+        'readonly',
+        'required',
+        'size',
+        'value',
+        'selectionstart',
+        'selectionend',
+        'selectiondirection',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'date'},
+      members: new Set([
+        'autocomplete',
+        'list',
+        'max',
+        'min',
+        'readonly',
+        'required',
+        'step',
+        'value',
+        'valueasdate',
+        'valueasnumber',
+        'list',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'month'},
+      members: new Set([
+        'autocomplete',
+        'list',
+        'max',
+        'min',
+        'readonly',
+        'required',
+        'step',
+        'value',
+        'valueasdate',
+        'valueasnumber',
+        'list',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'week'},
+      members: new Set([
+        'autocomplete',
+        'list',
+        'max',
+        'min',
+        'readonly',
+        'required',
+        'step',
+        'value',
+        'valueasdate',
+        'valueasnumber',
+        'list',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'time'},
+      members: new Set([
+        'autocomplete',
+        'list',
+        'max',
+        'min',
+        'readonly',
+        'required',
+        'step',
+        'value',
+        'valueasdate',
+        'valueasnumber',
+        'list',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'datetime-local'},
+      members: new Set([
+        'autocomplete',
+        'list',
+        'max',
+        'min',
+        'readonly',
+        'required',
+        'step',
+        'value',
+        'valueasnumber',
+        'list',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'number'},
+      members: new Set([
+        'autocomplete',
+        'list',
+        'max',
+        'min',
+        'placeholder',
+        'readonly',
+        'required',
+        'step',
+        'value',
+        'valueasnumber',
+        'list',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'range'},
+      members: new Set([
+        'autocomplete',
+        'list',
+        'max',
+        'min',
+        'step',
+        'value',
+        'valueasnumber',
+        'list',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'color'},
+      members: new Set([
+        'autocomplete',
+        'list',
+        'value',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'checkbox'},
+      members: new Set([
+        'checked',
+        'required',
+        'checked',
+        'value',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'radio'},
+      members: new Set([
+        'checked',
+        'required',
+        'checked',
+        'value',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'file'},
+      members: new Set([
+        'accept',
+        'multiple',
+        'required',
+        'files',
+        'value',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'submit'},
+      members: new Set([
+        'formaction',
+        'formenctype',
+        'formmethod',
+        'formnovalidate',
+        'formtarget',
+        'value',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'image'},
+      members: new Set([
+        'alt',
+        'formaction',
+        'formenctype',
+        'formmethod',
+        'formnovalidate',
+        'formtarget',
+        'height',
+        'src',
+        'width',
+        'value',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'reset'},
+      members: new Set([
+        'value',
+      ])
+    },
+    {
+      rule: {when: 'type', is: 'button'},
+      members: new Set([
+        'value',
+      ])
+    },
+  ],
+};

package/scripts/webidl-properties/get-props.js

@@ -0,0 +1,150 @@
+// Copyright 2022 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import {APPLICABLE_MEMBERS, GLOBAL_ATTRIBUTES, SPECS} from './config.js';
+import {merge} from './util.js';
+
+/**
+ * All the members relevant for generating the DOM pinned properties dataset
+ * from WebIDL interfaces, mixins and dictionaries.
+ */
+const ACCEPTED_MEMBER_TYPES = new Set(['attribute', 'field']);
+
+/**
+ * Generates the DOM pinned properties dataset.
+ *
+ * @param {array} specs A list of specs. Each spec specifies its name and
+ * all the idl definitions it contains.
+ * @returns {object} output An object with WebIDL type names as keys and their
+ * WebIDL properties and inheritance/include chains as values.
+ */
+export function getIDLProps(specs, output = {}) {
+  for (const spec of specs) {
+    transform(spec, output);
+  }
+  return output;
+}
+
+function transform({name, idls}, output = {}) {
+  const makeEntry = () => ({
+    inheritance: null,
+    includes: [],
+    props: {},
+  });
+
+  for (const idl of idls) {
+    switch (idl.type) {
+      case 'interface':
+      case 'interface mixin':
+      case 'dictionary': {
+        output[idl.name] = output[idl.name] ?? makeEntry();
+        let props = idl.members?.filter(member => ACCEPTED_MEMBER_TYPES.has(member.type));
+        props = props?.map(member => [member.name, {specs: [name]}]);
+        merge(output[idl.name], {
+          inheritance: idl.inheritance,
+          props: Object.fromEntries(props),
+        });
+        break;
+      }
+      case 'includes': {
+        output[idl.target] = output[idl.target] ?? makeEntry();
+        merge(output[idl.target], {
+          includes: [idl.includes],
+        });
+        break;
+      }
+      case 'callback':
+      case 'callback interface':
+      case 'enum':
+      case 'typedef':
+      case 'namespace': {
+        break;
+      }
+      default: {
+        console.warn('Skipping unknown WebIDL type', idl.type);
+      }
+    }
+  }
+}
+
+/**
+ * Adds additional metadata to the DOM pinned properties dataset.
+ *
+ * Currently:
+ * - Adds a field specifying whether a member is a global attribute or not.
+ * - Adds information about which properties are "applicable" members for
+ * certain "states" their parent WebIDL type can be in, such as for the
+ * HTMLInputElement where the set of valid members are determined by the "type"
+ * property. See `APPLICABLE_MEMBERS`.
+ *
+ * @param {*} output
+ */
+export function addMetadata(output) {
+  for (const [key, value] of Object.entries(output)) {
+    for (const [name, prop] of Object.entries(value.props)) {
+      prop.global = GLOBAL_ATTRIBUTES.has(name);
+
+      const rules = APPLICABLE_MEMBERS[key];
+      if (!rules) {
+        continue;
+      }
+
+      for (const {rule, members} of rules) {
+        if (members.has(name.toLowerCase())) {
+          merge(prop, {rules: [rule]});
+        }
+      }
+
+      value.rules = rules.map(({rule}) => rule);
+    }
+  }
+  return output;
+}
+
+/**
+ * Minimizes the DOM pinned properties dataset to remove the bits of data that
+ * don't contain information. For example, empty inheritance/includes chains.
+ *
+ * This should be done right at the end, before writing into the output file, to
+ * allow for certain diagnostics (such as finding "missing types").
+ *
+ * @param {*} output
+ * @returns {object}
+ */
+export function minimize(output) {
+  for (const [key, value] of Object.entries(output)) {
+    if (!value.inheritance) {
+      // Remove empty inheritance chains.
+      delete value.inheritance;
+    }
+    if (!value.includes.length) {
+      // Remove empty include chains.
+      delete value.includes;
+    }
+    const props = Object.entries(value.props);
+    if (!props.length) {
+      // Remove empty 'prop' lists.
+      delete value.props;
+    } else {
+      for (const [, value] of props) {
+        if (!value.global) {
+          // Remove the 'global' flag if it's false.
+          delete value.global;
+        }
+        if (value.specs.length === 1 && value.specs[0] === 'html') {
+          // Remove the 'specs' list if it's just "html".
+          delete value.specs;
+        } else {
+          // Combine multiple spec names into a single value.
+          value.specs = value.specs.reduce((acc, name) => acc | SPECS[name], 0);
+        }
+      }
+    }
+    // Remove the entire entry if there's nothing left after the cleanup above.
+    if (!Object.entries(value).length) {
+      delete output[key];
+    }
+  }
+  return output;
+}

package/scripts/webidl-properties/index.js

@@ -0,0 +1,90 @@
+// Copyright 2020 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+// eslint-disable-next-line rulesdir/es_modules_import
+import idl from '@webref/idl';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as url from 'url';
+
+import {SPECS} from './config.js';
+import {addMetadata, getIDLProps, minimize} from './get-props.js';
+import {getMissingTypes} from './util.js';
+
+if (process.argv.length !== 3) {
+  throw new Error('Please provide the path to devtools-frontend');
+}
+
+const files = await idl.listAll();
+const names = Object.keys(SPECS);
+const specs = await Promise.all(names.map(name => files[name].parse().then(idls => ({name, idls}))));
+
+const output = addMetadata(getIDLProps(specs));
+
+const missing = getMissingTypes(output);
+for (const type of missing) {
+  console.warn('Found missing type:', type);
+}
+
+const frontendPath = path.resolve(process.argv[2]);
+const jsMetadataPath = path.join(frontendPath, 'front_end/models/javascript_metadata/');
+const outPath = path.join(jsMetadataPath, 'DOMPinnedProperties.ts');
+const thisPath = path.relative(frontendPath, url.fileURLToPath(import.meta.url));
+
+const stringify = object => JSON.stringify(object, null, 2);
+
+fs.writeFileSync(outPath, `
+// Copyright 2022 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+// Generated from ${thisPath}
+
+/**
+ * All the specs used when generating the DOM pinned properties dataset.
+ */
+export const SPECS = ${stringify(SPECS)};
+
+export interface DOMPinnedWebIDLProp {
+  // A flag specifying whether it's a "global" attribute.
+  global?: boolean;
+  // A bitfield of the specs in which the property is found.
+  // If missing, it implies the default spec: "html".
+  specs?: number;
+  // The "states" in which this property is "applicable".
+  rules?: Array<DOMPinnedWebIDLRule>;
+}
+
+export interface DOMPinnedWebIDLType {
+  // An inherited Type.
+  inheritance?: string;
+  // A set of Types to also include properties from.
+  includes?: Array<string>;
+  // The properties defined on this Type.
+  props?: {
+    // A property name such as "checked".
+    [PropName: string]: DOMPinnedWebIDLProp,
+  };
+  // The "states" in which only certain properties are "applicable".
+  rules?: Array<DOMPinnedWebIDLRule>;
+}
+
+export interface DOMPinnedWebIDLRule {
+  when: string;
+  is: string;
+}
+
+export interface DOMPinnedPropertiesDataset {
+  [TypeName: string]: DOMPinnedWebIDLType;
+}
+
+/**
+ * The DOM pinned properties dataset. Generated from WebIDL data parsed from
+ * the SPECS above.
+ *
+ * This is an object with WebIDL type names as keys and their WebIDL properties
+ * and inheritance/include chains as values.
+ */
+export const DOMPinnedProperties: DOMPinnedPropertiesDataset = ${stringify(minimize(output))};
+
+`);

package/scripts/webidl-properties/package.json

@@ -0,0 +1,9 @@
+{
+  "private": true,
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "start": "node index.js",
+    "test": "mocha tests.js"
+  }
+}