devtools/client/fronts/css-properties.js

   1 /* This Source Code Form is subject to the terms of the Mozilla Public
   2  * License, v. 2.0. If a copy of the MPL was not distributed with this
   3  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   4
   5 "use strict";
   6
   7 const {
   8   FrontClassWithSpec,
   9   registerFront,
  10 } = require("resource://devtools/shared/protocol.js");
  11 const {
  12   cssPropertiesSpec,
  13 } = require("resource://devtools/shared/specs/css-properties.js");
  14
  15 loader.lazyRequireGetter(
  16   this,
  17   "cssColors",
  18   "resource://devtools/shared/css/color-db.js",
  19   true
  20 );
  21 loader.lazyRequireGetter(
  22   this,
  23   "CSS_TYPES",
  24   "resource://devtools/shared/css/constants.js",
  25   true
  26 );
  27 loader.lazyRequireGetter(
  28   this,
  29   "isCssVariable",
  30   "resource://devtools/shared/inspector/css-logic.js",
  31   true
  32 );
  33
  34 /**
  35  * The CssProperties front provides a mechanism to have a one-time asynchronous
  36  * load of a CSS properties database. This is then fed into the CssProperties
  37  * interface that provides synchronous methods for finding out what CSS
  38  * properties the current server supports.
  39  */
  40 class CssPropertiesFront extends FrontClassWithSpec(cssPropertiesSpec) {
  41   constructor(client, targetFront) {
  42     super(client, targetFront);
  43
  44     // Attribute name from which to retrieve the actorID out of the target actor's form
  45     this.formAttributeName = "cssPropertiesActor";
  46   }
  47
  48   async initialize() {
  49     const db = await super.getCSSDatabase();
  50     this.cssProperties = new CssProperties(normalizeCssData(db));
  51   }
  52
  53   destroy() {
  54     this.cssProperties = null;
  55     super.destroy();
  56   }
  57 }
  58
  59 /**
  60  * Ask questions to a CSS database. This class does not care how the database
  61  * gets loaded in, only the questions that you can ask to it.
  62  * Prototype functions are bound to 'this' so they can be passed around as helper
  63  * functions.
  64  *
  65  * @param {Object} db
  66  *                 A database of CSS properties
  67  * @param {Object} inheritedList
  68  *                 The key is the property name, the value is whether or not
  69  *                 that property is inherited.
  70  */
  71 function CssProperties(db) {
  72   this.properties = db.properties;
  73
  74   this.isKnown = this.isKnown.bind(this);
  75   this.isInherited = this.isInherited.bind(this);
  76   this.supportsType = this.supportsType.bind(this);
  77 }
  78
  79 CssProperties.prototype = {
  80   /**
  81    * Checks to see if the property is known by the browser. This function has
  82    * `this` already bound so that it can be passed around by reference.
  83    *
  84    * @param {String} property The property name to be checked.
  85    * @return {Boolean}
  86    */
  87   isKnown(property) {
  88     // Custom Property Names (aka CSS Variables) are case-sensitive; do not lowercase.
  89     property = property.startsWith("--") ? property : property.toLowerCase();
  90     return !!this.properties[property] || isCssVariable(property);
  91   },
  92
  93   /**
  94    * Checks to see if the property is an inherited one.
  95    *
  96    * @param {String} property The property name to be checked.
  97    * @return {Boolean}
  98    */
  99   isInherited(property) {
 100     return this.properties[property]?.isInherited;
 101   },
 102
 103   /**
 104    * Checks if the property supports the given CSS type.
 105    *
 106    * @param {String} property The property to be checked.
 107    * @param {String} type One of the values from InspectorPropertyType.
 108    * @return {Boolean}
 109    */
 110   supportsType(property, type) {
 111     const id = CSS_TYPES[type];
 112     return (
 113       this.properties[property] &&
 114       (this.properties[property].supports.includes(type) ||
 115         this.properties[property].supports.includes(id))
 116     );
 117   },
 118
 119   /**
 120    * Gets the CSS values for a given property name.
 121    *
 122    * @param {String} property The property to use.
 123    * @return {Array} An array of strings.
 124    */
 125   getValues(property) {
 126     return this.properties[property] ? this.properties[property].values : [];
 127   },
 128
 129   /**
 130    * Gets the CSS property names.
 131    *
 132    * @return {Array} An array of strings.
 133    */
 134   getNames() {
 135     return Object.keys(this.properties);
 136   },
 137
 138   /**
 139    * Return a list of subproperties for the given property.  If |name|
 140    * does not name a valid property, an empty array is returned.  If
 141    * the property is not a shorthand property, then array containing
 142    * just the property itself is returned.
 143    *
 144    * @param {String} name The property to query
 145    * @return {Array} An array of subproperty names.
 146    */
 147   getSubproperties(name) {
 148     // Custom Property Names (aka CSS Variables) are case-sensitive; do not lowercase.
 149     name = name.startsWith("--") ? name : name.toLowerCase();
 150     if (this.isKnown(name)) {
 151       if (this.properties[name] && this.properties[name].subproperties) {
 152         return this.properties[name].subproperties;
 153       }
 154       return [name];
 155     }
 156     return [];
 157   },
 158 };
 159
 160 /**
 161  * Even if the target has the cssProperties actor, the returned data may not be in the
 162  * same shape or have all of the data we need. This normalizes the data and fills in
 163  * any missing information like color values.
 164  *
 165  * @return {Object} The normalized CSS database.
 166  */
 167 function normalizeCssData(db) {
 168   // If there is a `from` attributes, it means that it comes from RDP
 169   // and it is not the client `generateCssProperties()` object passed by tests.
 170   if (typeof db.from == "string") {
 171     // This is where to put backward compat tweaks here to support old runtimes.
 172   }
 173
 174   reattachCssColorValues(db);
 175
 176   return db;
 177 }
 178
 179 /**
 180  * Color values are omitted to save on space. Add them back here.
 181  * @param {Object} The CSS database.
 182  */
 183 function reattachCssColorValues(db) {
 184   if (db.properties.color.values[0] === "COLOR") {
 185     const colors = Object.keys(cssColors);
 186
 187     for (const name in db.properties) {
 188       const property = db.properties[name];
 189       // "values" can be undefined if {name} was not found in CSS_PROPERTIES_DB.
 190       if (property.values && property.values[0] === "COLOR") {
 191         property.values.shift();
 192         property.values = property.values.concat(colors).sort();
 193       }
 194     }
 195   }
 196 }
 197
 198 module.exports = {
 199   CssPropertiesFront,
 200   CssProperties,
 201   normalizeCssData,
 202 };
 203 registerFront(CssPropertiesFront);