DEV: Add API bridge for custom hamburger menu links to sidebar (#17742)

The old hamburger menu widget was customizable via the
`api.decorateWidget("hamburger-menu:generalLinks")` plugin API. As the
hamburger menu is going to be replaced by the sidebar dropdown, we need
a way to smoothly transit plugins and theme components to the new
sidebar. This commit makes a best effort attempt to bridge
`api.decorateWidget` with `api.addCommunitySectionLink`. If an error is
encountered, a deprecation notice is logged.

app/assets/javascripts/discourse/app/lib/plugin-api.js

@@ -1,3 +1,4 @@
+import I18n from "I18n";
 import ComposerEditor, {
   addComposerUploadHandler,
   addComposerUploadMarkdownResolver,
@@ -478,6 +479,30 @@ class PluginApi {
    *
    **/
   decorateWidget(name, fn) {
+    if (name === "hamburger-menu:generalLinks") {
+      const siteSettings = this.container.lookup("site-settings:main");
+
+      if (siteSettings.enable_experimental_sidebar_hamburger) {
+        try {
+          const { route, label, rawLabel, className } = fn();
+          const textContent = rawLabel || I18n.t(label);
+
+          this.addCommunitySectionLink({
+            name: className || textContent.replace(/\s+/g, "-").toLowerCase(),
+            route,
+            title: textContent,
+            text: textContent,
+          });
+        } catch {
+          deprecated(
+            `Usage of \`api.decorateWidget('hamburger-menu:generalLinks')\` is incompatible with the \`enable_experimental_sidebar_hamburger\` site setting. Please use \`api.addCommunitySectionLink\` instead.`
+          );
+        }
+
+        return;
+      }
+    }
+
     decorateWidget(name, fn);
   }
 

app/assets/javascripts/discourse/tests/acceptance/sidebar-plugin-api-test.js

@@ -1,4 +1,5 @@
 import { test } from "qunit";
+import I18n from "I18n";
 
 import { click, visit } from "@ember/test-helpers";
 import {
@@ -419,4 +420,75 @@ acceptance("Sidebar - Plugin API", function (needs) {
       "displays no links"
     );
   });
+
+  test("API bridge for decorating hamburger-menu widget with generalLinks", async function (assert) {
+    withPluginApi("1.3.0", (api) => {
+      api.decorateWidget("hamburger-menu:generalLinks", () => {
+        return {
+          route: "discovery.latest",
+          label: "filters.latest.title",
+        };
+      });
+
+      api.decorateWidget("hamburger-menu:generalLinks", () => {
+        return {
+          route: "discovery.unread",
+          rawLabel: "my unreads",
+        };
+      });
+
+      api.decorateWidget("hamburger-menu:generalLinks", () => {
+        return {
+          route: "discovery.top",
+          rawLabel: "my top",
+          className: "my-custom-top",
+        };
+      });
+    });
+
+    await visit("/");
+
+    const customlatestSectionLink = query(
+      ".sidebar-section-community .sidebar-section-link-latest"
+    );
+
+    assert.ok(
+      customlatestSectionLink,
+      "adds custom latest section link to community section"
+    );
+
+    assert.strictEqual(
+      customlatestSectionLink.textContent.trim(),
+      I18n.t("filters.latest.title"),
+      "displays the right text for custom latest section link"
+    );
+
+    await click(
+      ".sidebar-section-community .sidebar-more-section-links-details-summary"
+    );
+
+    const customUnreadSectionLink = query(
+      ".sidebar-section-community .sidebar-section-link-my-unreads"
+    );
+
+    assert.ok(
+      customUnreadSectionLink,
+      "adds custom unread section link to community section"
+    );
+
+    assert.strictEqual(
+      customUnreadSectionLink.textContent.trim(),
+      "my unreads",
+      "displays the right text for custom unread section link"
+    );
+
+    const customTopSectionLInk = query(
+      ".sidebar-section-community .sidebar-section-link-my-custom-top"
+    );
+
+    assert.ok(
+      customTopSectionLInk,
+      "adds custom top section link to community section with right link class"
+    );
+  });
 });