DEV: Add `registerCustomCategorySectionLinkLockIcon` plugin API (#21655)

New client side plugin API that allows plugins or themes to customize
the fontawesome 5 icon used to indicate that a category is locked/read
restricted.

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

@@ -104,7 +104,10 @@ import { downloadCalendar } from "discourse/lib/download-calendar";
 import { consolePrefix } from "discourse/lib/source-identifier";
 import { addSectionLink as addCustomCommunitySectionLink } from "discourse/lib/sidebar/custom-community-section-links";
 import { addSidebarSection } from "discourse/lib/sidebar/custom-sections";
-import { registerCustomCountable as registerUserCategorySectionLinkCountable } from "discourse/lib/sidebar/user/categories-section/category-section-link";
+import {
+  registerCustomCategoryLockIcon,
+  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";
 import DiscourseURL from "discourse/lib/url";
 import { registerNotificationTypeRenderer } from "discourse/lib/notification-types-manager";
@@ -118,7 +121,7 @@ import { registerHashtagType } from "discourse/lib/hashtag-autocomplete";
 // based on Semantic Versioning 2.0.0. Please update the changelog at
 // docs/CHANGELOG-JAVASCRIPT-PLUGIN-API.md whenever you change the version
 // using the format described at https://keepachangelog.com/en/1.0.0/.
-const PLUGIN_API_VERSION = "1.6.1";
+export const PLUGIN_API_VERSION = "1.6.1";
 
 // This helper prevents us from applying the same `modifyClass` over and over in test mode.
 function canModify(klass, type, resolverName, changes) {
@@ -1912,6 +1915,15 @@ class PluginApi {
     });
   }
 
+  /**
+   * Changes the lock icon used for a sidebar category section link to indicate that a category is read restricted.
+   *
+   * @param {String} Name of a FontAwesome 5 icon
+   */
+  registerCustomCategorySectionLinkLockIcon(icon) {
+    return registerCustomCategoryLockIcon(icon);
+  }
+
   /**
    * 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

@@ -72,6 +72,16 @@ export function resetCustomCountables() {
   customCountables.length = 0;
 }
 
+let customCategoryLockIcon;
+
+export function registerCustomCategoryLockIcon(icon) {
+  customCategoryLockIcon = icon;
+}
+
+export function resetCustomCategoryLockIcon() {
+  customCategoryLockIcon = null;
+}
+
 export default class CategorySectionLink {
   @tracked activeCountable;
 
@@ -169,7 +179,7 @@ export default class CategorySectionLink {
 
   get prefixBadge() {
     if (this.category.read_restricted) {
-      return "lock";
+      return customCategoryLockIcon || "lock";
     }
   }
 

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

@@ -8,9 +8,12 @@ import {
   queryAll,
   updateCurrentUser,
 } from "discourse/tests/helpers/qunit-helpers";
-import { withPluginApi } from "discourse/lib/plugin-api";
+import { PLUGIN_API_VERSION, withPluginApi } from "discourse/lib/plugin-api";
 import Site from "discourse/models/site";
-import { resetCustomCountables } from "discourse/lib/sidebar/user/categories-section/category-section-link";
+import {
+  resetCustomCategoryLockIcon,
+  resetCustomCountables,
+} from "discourse/lib/sidebar/user/categories-section/category-section-link";
 import { UNREAD_LIST_DESTINATION } from "discourse/controllers/preferences/sidebar";
 import { bind } from "discourse-common/utils/decorators";
 
@@ -30,7 +33,7 @@ acceptance("Sidebar - Plugin API", function (needs) {
   let linkDidInsert, linkDestroy, sectionDestroy;
 
   test("Multiple header actions and links", async function (assert) {
-    withPluginApi("1.3.0", (api) => {
+    withPluginApi(PLUGIN_API_VERSION, (api) => {
       api.addSidebarSection(
         (BaseCustomSidebarSection, BaseCustomSidebarSectionLink) => {
           return class extends BaseCustomSidebarSection {
@@ -366,7 +369,7 @@ acceptance("Sidebar - Plugin API", function (needs) {
   });
 
   test("Single header action and no links", async function (assert) {
-    withPluginApi("1.3.0", (api) => {
+    withPluginApi(PLUGIN_API_VERSION, (api) => {
       api.addSidebarSection((BaseCustomSidebarSection) => {
         return class extends BaseCustomSidebarSection {
           get name() {
@@ -422,7 +425,7 @@ acceptance("Sidebar - Plugin API", function (needs) {
   });
 
   test("API bridge for decorating hamburger-menu widget with footer links", async function (assert) {
-    withPluginApi("1.3.0", (api) => {
+    withPluginApi(PLUGIN_API_VERSION, (api) => {
       api.decorateWidget("hamburger-menu:footerLinks", () => {
         return {
           route: "discovery.top",
@@ -460,7 +463,7 @@ acceptance("Sidebar - Plugin API", function (needs) {
   });
 
   test("API bridge for decorating hamburger-menu widget with general links", async function (assert) {
-    withPluginApi("1.3.0", (api) => {
+    withPluginApi(PLUGIN_API_VERSION, (api) => {
       api.decorateWidget("hamburger-menu:generalLinks", () => {
         return {
           route: "discovery.latest",
@@ -592,7 +595,7 @@ acceptance("Sidebar - Plugin API", function (needs) {
   });
 
   test("Section that is not displayed via displaySection", async function (assert) {
-    withPluginApi("1.3.0", (api) => {
+    withPluginApi(PLUGIN_API_VERSION, (api) => {
       api.addSidebarSection((BaseCustomSidebarSection) => {
         return class extends BaseCustomSidebarSection {
           get name() {
@@ -638,7 +641,7 @@ acceptance("Sidebar - Plugin API", function (needs) {
 
   test("Registering a custom countable for a section link in the user's sidebar categories section", async function (assert) {
     try {
-      return await withPluginApi("1.6.0", async (api) => {
+      return await withPluginApi(PLUGIN_API_VERSION, async (api) => {
         const categories = Site.current().categories;
         const category1 = categories[0];
         const category2 = categories[1];
@@ -749,4 +752,31 @@ acceptance("Sidebar - Plugin API", function (needs) {
       resetCustomCountables();
     }
   });
+
+  test("Customizing the icon used in a category section link to indicate that a category is read restricted", 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.registerCustomCategorySectionLinkLockIcon("wrench");
+
+        await visit("/");
+
+        assert.ok(
+          exists(
+            `.sidebar-section-link[data-category-id="${category1.id}"] .prefix-badge.d-icon-wrench`
+          ),
+          "wrench icon is displayed for the section link's prefix badge"
+        );
+      });
+    } finally {
+      resetCustomCategoryLockIcon();
+    }
+  });
 });

docs/CHANGELOG-JAVASCRIPT-PLUGIN-API.md

@@ -7,6 +7,13 @@ in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## UNRELEASED
+
+### Added
+
+- Adds `registerCustomCategorySectionLinkLockIcon` which allows plugins or themes to customize the FontAwesome 5 icon used to indicate
+  that a category is read restricted when the category is displayed in the sidebar.
+
 ## [1.6.0] - 2022-12-13
 
 ### Added