From 356df4d3d76a31a3909d61766074bfe8fc958952 Mon Sep 17 00:00:00 2001
From: David Wheatley <hi@davwheat.dev>
Date: Sun, 9 May 2021 01:56:34 +0000
Subject: [PATCH] Add deprecation warning when `$.tooltip` is used outside of
 the Tooltip component

---
 js/src/common/components/Tooltip.tsx | 18 +++++++++++-------
 js/src/common/index.js               | 15 +++++++++++++++
 2 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/js/src/common/components/Tooltip.tsx b/js/src/common/components/Tooltip.tsx
index 953ca7c4a44..10468fcee9e 100644
--- a/js/src/common/components/Tooltip.tsx
+++ b/js/src/common/components/Tooltip.tsx
@@ -136,12 +136,16 @@ export default class Tooltip extends Component<TooltipAttrs> {
     } = this.attrs;
 
     // https://getbootstrap.com/docs/3.3/javascript/#tooltips-options
-    this.$().tooltip({
-      html,
-      delay,
-      placement: position,
-      // Fancy "hack" to assemble the trigger string
-      trigger: classList('hover', [showOnFocus && 'focus']) as TooltipCreationOptions['trigger'],
-    });
+    this.$().tooltip(
+      {
+        html,
+        delay,
+        placement: position,
+        // Fancy "hack" to assemble the trigger string
+        trigger: classList('hover', [showOnFocus && 'focus']) as TooltipCreationOptions['trigger'],
+      },
+      // @ts-expect-error We don't want this arg to be part of the public API. It only exists to prevent deprecation warnings when using `$.tooltip` in this component.
+      'DANGEROUS_tooltip_jquery_fn_deprecation_exempt'
+    );
   }
 }
diff --git a/js/src/common/index.js b/js/src/common/index.js
index c2d576780ed..b26d8d6c858 100644
--- a/js/src/common/index.js
+++ b/js/src/common/index.js
@@ -25,3 +25,18 @@ import * as Extend from './extend/index';
 export { Extend };
 
 import './utils/arrayFlatPolyfill';
+
+const tooltipGen = $.fn.tooltip;
+
+// Remove in a future version of Flarum.
+$.fn.tooltip = function (options, caller) {
+  // Show a warning when `$.tooltip` is used outside of the Tooltip component.
+  // This functionality is deprecated and should not be used.
+  if (['DANGEROUS_tooltip_jquery_fn_deprecation_exempt'].includes(caller)) {
+    console.warn(
+      "Calling `$.tooltip` is now deprecated. Please use the `<Tooltip>` component exposed by flarum/core instead. `$.tooltip` may be removed in a future version of Flarum.\n\nIf this component doesn't meet your requirements, please open an issue: https://github.com/flarum/core/issues/new?assignees=davwheat&labels=type/bug,needs-verification&template=bug-report.md&title=Tooltip%20component%20unsuitable%20for%20use%20case"
+    );
+  }
+
+  tooltipGen.bind(this)(options);
+};