Document settings methods (#1219)

* Document settings methods

* Update injected/src/content-feature.js

Author: jonathanKingston

injected/src/content-feature.js

@@ -146,6 +146,26 @@ export default class ContentFeature {
 
     /**
      * Return a specific setting from the feature settings
+     * If the "settings" key within the config has a "domains" key, it will be used to override the settings.
+     * This uses JSONPatch to apply the patches to settings before getting the setting value.
+     * For example.com getFeatureSettings('val') will return 1:
+     * ```json
+     *  {
+     *      "settings": {
+     *         "domains": [
+     *             {
+     *                "domain": "example.com",
+     *                "patchSettings": [
+     *                    { "op": "replace", "path": "/val", "value": 1 }
+     *                ]
+     *             }
+     *         ]
+     *      }
+     *  }
+     * ```
+     * "domain" can either be a string or an array of strings.
+
+     * For boolean states you should consider using getFeatureSettingEnabled.
      * @param {string} featureKeyName
      * @param {string} [featureName]
      * @returns {any}
@@ -184,6 +204,23 @@ export default class ContentFeature {
     /**
      * For simple boolean settings, return true if the setting is 'enabled'
      * For objects, verify the 'state' field is 'enabled'.
+     * This allows for future forwards compatibility with more complex settings if required.
+     * For example:
+     * ```json
+     * {
+     *    "toggle": "enabled"
+     * }
+     * ```
+     * Could become later (without breaking changes):
+     * ```json
+     * {
+     *   "toggle": {
+     *       "state": "enabled",
+     *       "someOtherKey": 1
+     *   }
+     * }
+     * ```
+     * This also supports domain overrides as per `getFeatureSetting`.
      * @param {string} featureKeyName
      * @param {string} [featureName]
      * @returns {boolean}
@@ -198,8 +235,10 @@ export default class ContentFeature {
 
     /**
      * Given a config key, interpret the value as a list of domain overrides, and return the elements that match the current page
+     * Consider using patchSettings instead as per `getFeatureSetting`.
      * @param {string} featureKeyName
      * @return {any[]}
+     * @private
      */
     matchDomainFeatureSetting(featureKeyName) {
         const domain = this.#args?.site.domain;

injected/src/features/element-hiding.js

@@ -320,10 +320,12 @@ export default class ElementHiding extends ContentFeature {
 
         // determine whether strict hide rules should be injected as a style tag
         if (shouldInjectStyleTag) {
+            // @ts-expect-error: Accessing private method
             shouldInjectStyleTag = this.matchDomainFeatureSetting('styleTagExceptions').length === 0;
         }
 
         // collect all matching rules for domain
+        // @ts-expect-error: Accessing private method
         const activeDomainRules = this.matchDomainFeatureSetting('domains').flatMap((item) => item.rules);
 
         const overrideRules = activeDomainRules.filter((rule) => {

injected/src/features/navigator-interface.js

@@ -3,6 +3,7 @@ import ContentFeature from '../content-feature';
 
 export default class NavigatorInterface extends ContentFeature {
     load(args) {
+        // @ts-expect-error: Accessing private method
         if (this.matchDomainFeatureSetting('privilegedDomains').length) {
             this.injectNavigatorInterface(args);
         }