DEV: Add experimental registerCustomCategorySectionLinkPrefix api (#21656)

This commit adds the experimental `registerCustomCategorySectionLinkPrefix` client side
plugin API that allows themes or plugins to override the prefix of a
category section link.

This is marked experimental because we might be introducing a core
feature where category icons are supported. This is currently use as a
bridge for the https://github.com/discourse/discourse-category-icons
theme component.

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

@@ -106,6 +106,7 @@ import { addSectionLink as addCustomCommunitySectionLink } from "discourse/lib/s
 import { addSidebarSection } from "discourse/lib/sidebar/custom-sections";
 import {
   registerCustomCategoryLockIcon,
+  registerCustomCategorySectionLinkPrefix,
   registerCustomCountable as registerUserCategorySectionLinkCountable,
 } from "discourse/lib/sidebar/user/categories-section/category-section-link";
 import { REFRESH_COUNTS_APP_EVENT_NAME as REFRESH_USER_SIDEBAR_CATEGORIES_SECTION_COUNTS_APP_EVENT_NAME } from "discourse/components/sidebar/user/categories-section";
@@ -1924,6 +1925,45 @@ class PluginApi {
     return registerCustomCategoryLockIcon(icon);
   }
 
+  /**
+   * EXPERIMENTAL. Do not use.
+   * Register a custom prefix for a sidebar category section link.
+   *
+   * Example:
+   *
+   * ```
+   * api.registerCustomCategorySectionLinkPrefix({
+   *   categoryId: category.id,
+   *   prefixType: "icon",
+   *   prefixValue: "wrench",
+   *   prefixColor: "FF0000"
+   * })
+   * ```
+   *
+   * @params {Object} arg - An object
+   * @params {string} arg.categoryId - The id of the category
+   * @params {string} arg.prefixType - The type of prefix to use. Can be "icon", "image", "text" or "span".
+   * @params {string} arg.prefixValue - The value of the prefix to use.
+   *                                    For "icon", pass in the name of a FontAwesome 5 icon.
+   *                                    For "image", pass in the src of the image.
+   *                                    For "text", pass in the text to display.
+   *                                    For "span", pass in an array containing two hex color values. Example: `[FF0000, 000000]`.
+   * @params {string} arg.prefixColor - The color of the prefix to use. Example: "FF0000".
+   */
+  registerCustomCategorySectionLinkPrefix({
+    categoryId,
+    prefixType,
+    prefixValue,
+    prefixColor,
+  }) {
+    registerCustomCategorySectionLinkPrefix({
+      categoryId,
+      prefixType,
+      prefixValue,
+      prefixColor,
+    });
+  }
+
   /**
    * EXPERIMENTAL. Do not use.
    * Triggers a refresh of the counts for all category section links under the categories section for a logged in user.

app/assets/javascripts/discourse/app/lib/sidebar/user/categories-section/category-section-link.js

@@ -82,6 +82,29 @@ export function resetCustomCategoryLockIcon() {
   customCategoryLockIcon = null;
 }
 
+let customCategoryPrefixes = {};
+
+export function registerCustomCategorySectionLinkPrefix({
+  categoryId,
+  prefixValue,
+  prefixType,
+  prefixColor,
+}) {
+  customCategoryPrefixes[categoryId] = {
+    prefixValue,
+    prefixType,
+    prefixColor,
+  };
+}
+
+export function resetCustomCategorySectionLinkPrefix() {
+  for (let key in customCategoryPrefixes) {
+    if (customCategoryPrefixes.hasOwnProperty(key)) {
+      delete customCategoryPrefixes[key];
+    }
+  }
+}
+
 export default class CategorySectionLink {
   @tracked activeCountable;
 
@@ -166,10 +189,17 @@ export default class CategorySectionLink {
   }
 
   get prefixType() {
-    return "span";
+    return customCategoryPrefixes[this.category.id]?.prefixType || "span";
   }
 
   get prefixValue() {
+    const customPrefixValue =
+      customCategoryPrefixes[this.category.id]?.prefixValue;
+
+    if (customPrefixValue) {
+      return customPrefixValue;
+    }
+
     if (this.category.parentCategory?.color) {
       return [this.category.parentCategory?.color, this.category.color];
     } else {
@@ -178,7 +208,10 @@ export default class CategorySectionLink {
   }
 
   get prefixColor() {
-    return this.category.color;
+    return (
+      customCategoryPrefixes[this.category.id]?.prefixColor ||
+      this.category.color
+    );
   }
 
   get prefixBadge() {

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

@@ -12,6 +12,7 @@ import { PLUGIN_API_VERSION, withPluginApi } from "discourse/lib/plugin-api";
 import Site from "discourse/models/site";
 import {
   resetCustomCategoryLockIcon,
+  resetCustomCategorySectionLinkPrefix,
   resetCustomCountables,
 } from "discourse/lib/sidebar/user/categories-section/category-section-link";
 import { UNREAD_LIST_DESTINATION } from "discourse/controllers/preferences/sidebar";
@@ -779,4 +780,44 @@ acceptance("Sidebar - Plugin API", function (needs) {
       resetCustomCategoryLockIcon();
     }
   });
+
+  test("Customizing the prefix used in a category section link for a particular category", async function (assert) {
+    try {
+      return await withPluginApi(PLUGIN_API_VERSION, async (api) => {
+        const categories = Site.current().categories;
+        const category1 = categories[0];
+        category1.read_restricted = true;
+
+        updateCurrentUser({
+          sidebar_category_ids: [category1.id],
+        });
+
+        api.registerCustomCategorySectionLinkPrefix({
+          categoryId: category1.id,
+          prefixType: "icon",
+          prefixValue: "wrench",
+          prefixColor: "FF0000", // rgb(255, 0, 0)
+        });
+
+        await visit("/");
+
+        assert.ok(
+          exists(
+            `.sidebar-section-link[data-category-id="${category1.id}"] .prefix-icon.d-icon-wrench`
+          ),
+          "wrench icon is displayed for the section link's prefix icon"
+        );
+
+        assert.strictEqual(
+          query(
+            `.sidebar-section-link[data-category-id="${category1.id}"] .sidebar-section-link-prefix`
+          ).style.color,
+          "rgb(255, 0, 0)",
+          "section link's prefix icon has the right color"
+        );
+      });
+    } finally {
+      resetCustomCategorySectionLinkPrefix();
+    }
+  });
 });