added webCompat as a docs page

duckduckgo · Sep 18, 2023 · a5dc2a4 · a5dc2a4
1 parent 12aa34b
commit a5dc2a4
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 12 deletions.
diff --git a/src/features/web-compat.js b/src/features/web-compat.js
@@ -1,20 +1,26 @@
-import ContentFeature from '../content-feature.js'
-
 /**
- * Fixes incorrect sizing value for outerHeight and outerWidth
+ * @module Web Compat
+ *
+ * @description
+ *
+ * A suite of individual 'fixes'
+ *
+ * - {@link default.windowSizingFix Window Sizing Fix}
+ * - {@link default.navigatorCredentialsFix Navigator Credentials Fix}
+ * - {@link default.safariObjectFix Safari Object Fix}
+ * - {@link default.notificationFix Notification Fix}
+ * - {@link default.messageHandlersFix Message Handlers Fix}
+ * - {@link default.notificationFix Notification Fix}
+ * - {@link default.permissionsFix Permissions Fix}
+ *
  */
-function windowSizingFix () {
-    if (window.outerHeight !== 0 && window.outerWidth !== 0) {
-        return
-    }
-    window.outerHeight = window.innerHeight
-    window.outerWidth = window.innerWidth
-}
+
+import ContentFeature from '../content-feature.js'
 
 export default class WebCompat extends ContentFeature {
     init () {
         if (this.getFeatureSettingEnabled('windowSizing')) {
-            windowSizingFix()
+            this.windowSizingFix()
         }
         if (this.getFeatureSettingEnabled('navigatorCredentials')) {
             this.navigatorCredentialsFix()
@@ -34,6 +40,17 @@ export default class WebCompat extends ContentFeature {
         }
     }
 
+    /**
+     * Fixes incorrect sizing value for outerHeight and outerWidth
+     */
+    windowSizingFix () {
+        if (window.outerHeight !== 0 && window.outerWidth !== 0) {
+            return
+        }
+        window.outerHeight = window.innerHeight
+        window.outerWidth = window.innerWidth
+    }
+
     /**
      * Notification fix for adding missing API for Android WebView.
      */
@@ -186,9 +203,27 @@ export default class WebCompat extends ContentFeature {
 
     /**
      * Support for proxying `window.webkit.messageHandlers`
+     *
+     * This was added to fix breakage in situations where sites
+     * see `window.webkit` and then assume their own handlers would be present.
+     *
+     * For example, it fixes when a site tries to do the following:
+     *
+     * ```javascript
+     * if (window.webkit) {
+     *    window.webkit.messageHandlers.myHandler.postMessage({})
+     *    //                            ^^^^^^^^^ when this is absent, postMessage throws
+     * }
+     * ```
+     *
+     * **Remote Config:**
+     *
+     * This feature needs to be configured to allow some known
+     * methods (ones we add) to pass though (using Reflect) whilst polyfilling others,
+     * see {@link "Webcompat Settings Schema".WebCompatSettings.messageHandlers}
      */
     messageHandlersFix () {
-        /** @type {import('../types//webcompat-settings').WebCompatSettings['messageHandlers']} */
+        /** @type {import('../types/webcompat-settings').WebCompatSettings['messageHandlers']} */
         const settings = this.getFeatureSetting('messageHandlers')
 
         // Do nothing if `messageHandlers` is absent

diff --git a/typedoc.json b/typedoc.json
@@ -12,6 +12,7 @@
         "src/features/duckplayer/thumbnails.js",
         "src/features/duckplayer/video-overlay.js",
         "src/features/harmful-apis.js",
+        "src/features/web-compat.js",
         "packages/messaging",
         "packages/messaging/schema.js",
         "packages/messaging/native.js",