fix: breaking change in Search component - renaming of state property (#3212)

* fix: breaking change in search component's public api

* fix: add setter

* feat: add deprecation warning helper

This reduces bundle size as a result of deprecation warning in our JS, as well as maintaining a consistent format across warnings.

* feat: fire deprecation warning on usage of `Search.state`

* chore: use consistent deprecation warning across core

* fix: `/pull` not `/issue`

* chore: format

js/src/common/Store.ts

@@ -1,6 +1,6 @@
 import app from '../common/app';
 import { FlarumRequestOptions } from './Application';
-import fireDebugWarning from './helpers/fireDebugWarning';
+import { fireDeprecationWarning } from './helpers/fireDebugWarning';
 import Model, { ModelData, SavedModelData } from './Model';
 
 export interface MetaInformation {
@@ -123,11 +123,7 @@ export default class Store {
     if (!this.models[data.type]) {
       if (!allowUnregistered) {
         setTimeout(() =>
-          fireDebugWarning(
-            `[Flarum 2.0 Deprecation] Cannot push object of type \`${data.type}\`, as that type has not yet been registered in the store. This will throw an error in Flarum 2.0 and later.
-
-For more information, see https://github.com/flarum/core/pull/3206.`
-          )
+          fireDeprecationWarning(`Pushing object of type \`${data.type}\` not allowed, as type not yet registered in the store.`, '3206')
         );
       }
 

js/src/common/helpers/fireDebugWarning.ts

@@ -16,3 +16,21 @@ export default function fireDebugWarning(...args: Parameters<typeof console.warn
 
   console.warn(...args);
 }
+
+/**
+ * Fire a Flarum deprecation warning which is shown in the JS console.
+ *
+ * These warnings are only shown when the forum is in debug mode, and the function exists to
+ * reduce bundle size caused by multiple warnings across our JavaScript.
+ *
+ * @param message The message to display. (Short, but sweet, please!)
+ * @param githubId The PR or Issue ID with more info in relation to this change.
+ * @param [removedFrom] The version in which this feature will be completely removed. (default: 2.0)
+ * @param [repo] The repo which the issue or PR is located in. (default: flarum/core)
+ *
+ * @see {@link fireDebugWarning}
+ */
+export function fireDeprecationWarning(message: string, githubId: string, removedFrom: string = '2.0', repo: string = 'flarum/core'): void {
+  // GitHub auto-redirects between `/pull` and `/issues` for us, so using `/pull` saves 2 bytes!
+  fireDebugWarning(`[Flarum ${removedFrom} Deprecation] ${message}\n\nSee: https://github.com/${repo}/pull/${githubId}`);
+}

js/src/common/utils/evented.js

@@ -1,15 +1,14 @@
+import { fireDeprecationWarning } from '../helpers/fireDebugWarning';
+
+const deprecatedNotice = 'The `evented` util is deprecated and no longer supported.';
+const deprecationIssueId = '2547';
+
 /**
  * The `evented` mixin provides methods allowing an object to trigger events,
  * running externally registered event handlers.
  *
  * @deprecated v1.2, to be removed in v2.0
  */
-
-import fireDebugWarning from '../helpers/fireDebugWarning';
-
-const deprecatedNotice =
-  'The `evented` util is deprecated and will be removed in Flarum 2.0. For more info, please see https://github.com/flarum/core/issues/2547';
-
 export default {
   /**
    * Arrays of registered event handlers, grouped by the event name.
@@ -27,7 +26,7 @@ export default {
    * @protected
    */
   getHandlers(event) {
-    fireDebugWarning(deprecatedNotice);
+    fireDeprecationWarning(deprecatedNotice, deprecationIssueId);
 
     this.handlers = this.handlers || {};
 
@@ -44,7 +43,7 @@ export default {
    * @public
    */
   trigger(event, ...args) {
-    fireDebugWarning(deprecatedNotice);
+    fireDeprecationWarning(deprecatedNotice, deprecationIssueId);
 
     this.getHandlers(event).forEach((handler) => handler.apply(this, args));
   },
@@ -56,7 +55,7 @@ export default {
    * @param {function} handler The function to handle the event.
    */
   on(event, handler) {
-    fireDebugWarning(deprecatedNotice);
+    fireDeprecationWarning(deprecatedNotice, deprecationIssueId);
 
     this.getHandlers(event).push(handler);
   },
@@ -69,7 +68,7 @@ export default {
    * @param {function} handler The function to handle the event.
    */
   one(event, handler) {
-    fireDebugWarning(deprecatedNotice);
+    fireDeprecationWarning(deprecatedNotice, deprecationIssueId);
 
     const wrapper = function () {
       handler.apply(this, arguments);
@@ -87,7 +86,7 @@ export default {
    * @param {function} handler The function that handles the event.
    */
   off(event, handler) {
-    fireDebugWarning(deprecatedNotice);
+    fireDeprecationWarning(deprecatedNotice, deprecationIssueId);
 
     const handlers = this.getHandlers(event);
     const index = handlers.indexOf(handler);

js/src/forum/components/Search.tsx

@@ -9,8 +9,8 @@ import icon from '../../common/helpers/icon';
 import SearchState from '../states/SearchState';
 import DiscussionsSearchSource from './DiscussionsSearchSource';
 import UsersSearchSource from './UsersSearchSource';
+import { fireDeprecationWarning } from '../../common/helpers/fireDebugWarning';
 import type Mithril from 'mithril';
-import Model from '../../common/Model';
 
 /**
  * The `SearchSource` interface defines a section of search results in the
@@ -53,14 +53,33 @@ export interface SearchAttrs extends ComponentAttrs {
  *
  * - state: SearchState instance.
  */
-export default class Search<T extends SearchAttrs = SearchAttrs> extends Component<T> {
+export default class Search<T extends SearchAttrs = SearchAttrs> extends Component<T, SearchState> {
   /**
    * The minimum query length before sources are searched.
    */
   protected static MIN_SEARCH_LEN = 3;
 
+  /**
+   * The instance of `SearchState` for this component.
+   */
   protected searchState!: SearchState;
 
+  /**
+   * The instance of `SearchState` for this component.
+   *
+   * @deprecated Replace with`this.searchState` instead.
+   */
+  // TODO: [Flarum 2.0] Remove this.
+  // @ts-expect-error This is a get accessor, while superclass defines this as a property. This is needed to prevent breaking changes, however.
+  protected get state() {
+    fireDeprecationWarning('`state` property of the Search component is deprecated', '3212');
+    return this.searchState;
+  }
+  protected set state(state: SearchState) {
+    fireDeprecationWarning('`state` property of the Search component is deprecated', '3212');
+    this.searchState = state;
+  }
+
   /**
    * Whether or not the search input has focus.
    */