From 35fcffde1bf5acefea87d70dca5e4ab3349f872d Mon Sep 17 00:00:00 2001
From: Sascha Greuel <github@1-2.dev>
Date: Fri, 1 May 2026 10:30:03 +0200
Subject: [PATCH] Add extension point for custom stored Font Awesome icons

Allow FontAwesomeIcon to resolve non-native stored icon strings through a new StoredIconResolving event. This keeps native `name;solid` icon strings unchanged while giving packages a package-safe way to provide custom IFontAwesomeIcon implementations for extended descriptors.

Also extend the FontAwesome picker callback contract with optional stored value and preview HTML arguments, and update IconFormField and trophy badge preview handling to use those optional values when provided.
---
 .../templates/shared_iconFormField.tpl        | 29 ++++++---
 ts/WoltLabSuite/Core/Acp/Ui/Trophy/Badge.ts   | 25 +++++--
 ts/WoltLabSuite/Core/Ui/Style/FontAwesome.ts  |  6 +-
 .../WoltLabSuite/Core/Acp/Ui/Trophy/Badge.js  | 22 +++++--
 .../WoltLabSuite/Core/Ui/Style/FontAwesome.js |  4 +-
 .../event/style/StoredIconResolving.class.php | 24 +++++++
 .../system/style/FontAwesomeIcon.class.php    | 65 +++++++++++++++----
 7 files changed, 142 insertions(+), 33 deletions(-)
 create mode 100644 wcfsetup/install/files/lib/event/style/StoredIconResolving.class.php

diff --git a/com.woltlab.wcf/templates/shared_iconFormField.tpl b/com.woltlab.wcf/templates/shared_iconFormField.tpl
index 656071753fb..6c8f03a21bc 100644
--- a/com.woltlab.wcf/templates/shared_iconFormField.tpl
+++ b/com.woltlab.wcf/templates/shared_iconFormField.tpl
@@ -13,34 +13,43 @@
 	{if $__iconFormFieldIncludeJavaScript}
 		{include file='shared_fontAwesomeJavaScript'}
 	{/if}
-	
+
 	<script data-relocate="true">
 		require(['WoltLabSuite/Core/Ui/Style/FontAwesome'], (UiStyleFontAwesome) => {
 			const iconContainer = document.getElementById('{unsafe:$field->getPrefixedId()|encodeJS}_icon');
 			const input = document.getElementById('{unsafe:$field->getPrefixedId()|encodeJS}');
 			const buttonRemoveIcon = document.getElementById('{unsafe:$field->getPrefixedId()|encodeJS}_removeIcon');
-			
-			const callback = (iconName, forceSolid) => {
-				input.value = `${ iconName };${ forceSolid }`;
 
+			const renderNativePreview = (iconName, forceSolid) => {
 				let icon = iconContainer.querySelector("fa-icon");
-				if (icon) {
-					icon.setIcon(iconName, forceSolid);
-				} else {
+				if (!icon || icon.parentElement !== iconContainer || iconContainer.childElementCount !== 1) {
+					iconContainer.replaceChildren();
+
 					icon = document.createElement("fa-icon");
 					icon.size = 64;
-					icon.setIcon(iconName, forceSolid);
 					iconContainer.append(icon);
 				}
 
+				icon.setIcon(iconName, forceSolid);
+			};
+
+			const callback = (iconName, forceSolid, value, previewHtml) => {
+				input.value = typeof value === 'string' ? value : `${ iconName };${ forceSolid }`;
+
+				if (typeof previewHtml === 'string') {
+					iconContainer.innerHTML = previewHtml;
+				} else {
+					renderNativePreview(iconName, forceSolid);
+				}
+
 				buttonRemoveIcon.hidden = false;
 			};
-			
+
 			const button = document.getElementById('{unsafe:$field->getPrefixedId()|encodeJS}_openIconDialog');
 			button.addEventListener('click', () => UiStyleFontAwesome.open(callback));
 			buttonRemoveIcon.addEventListener("click", () => {
 				input.value = "";
-				iconContainer.querySelector("fa-icon")?.remove();
+				iconContainer.replaceChildren();
 
 				buttonRemoveIcon.hidden = true;
 			});
diff --git a/ts/WoltLabSuite/Core/Acp/Ui/Trophy/Badge.ts b/ts/WoltLabSuite/Core/Acp/Ui/Trophy/Badge.ts
index cd0d97435cb..dc0d56b9cf7 100644
--- a/ts/WoltLabSuite/Core/Acp/Ui/Trophy/Badge.ts
+++ b/ts/WoltLabSuite/Core/Acp/Ui/Trophy/Badge.ts
@@ -13,16 +13,33 @@ import DomUtil from "../../../Dom/Util";
 
 const badgeContainer = document.getElementById("badgeContainer")!;
 const previewWrapper = badgeContainer.querySelector(".trophyIcon") as HTMLElement;
-const previewIcon = previewWrapper.querySelector("fa-icon")!;
+
+function renderNativePreview(icon: string, forceSolid: boolean): void {
+  let previewIcon = previewWrapper.querySelector("fa-icon");
+  if (!(previewIcon instanceof HTMLElement) || previewIcon.parentElement !== previewWrapper) {
+    previewWrapper.replaceChildren();
+
+    previewIcon = document.createElement("fa-icon");
+    previewIcon.size = 64;
+    previewWrapper.append(previewIcon);
+  }
+
+  previewIcon.setIcon(icon, forceSolid);
+}
 
 function setupChangeIcon(): void {
   const button = badgeContainer.querySelector('.trophyIconEditButton[data-value="icon"]') as HTMLButtonElement;
   const input = badgeContainer.querySelector('input[name="iconName"]') as HTMLInputElement;
 
   button.addEventListener("click", () => {
-    openFontAwesomePicker((icon, forceSolid) => {
-      previewIcon.setIcon(icon, forceSolid);
-      input.value = `${icon};${String(forceSolid)}`;
+    openFontAwesomePicker((icon, forceSolid, value, previewHtml) => {
+      input.value = value ?? `${icon};${String(forceSolid)}`;
+
+      if (typeof previewHtml === "string") {
+        previewWrapper.innerHTML = previewHtml;
+      } else {
+        renderNativePreview(icon, forceSolid);
+      }
     });
   });
 }
diff --git a/ts/WoltLabSuite/Core/Ui/Style/FontAwesome.ts b/ts/WoltLabSuite/Core/Ui/Style/FontAwesome.ts
index d87d35d4626..010656f60ff 100644
--- a/ts/WoltLabSuite/Core/Ui/Style/FontAwesome.ts
+++ b/ts/WoltLabSuite/Core/Ui/Style/FontAwesome.ts
@@ -11,7 +11,7 @@ import { getPhrase } from "WoltLabSuite/Core/Language";
 import UiItemListFilter from "../ItemList/Filter";
 import { dialogFactory } from "WoltLabSuite/Core/Component/Dialog";
 
-type CallbackSelect = (icon: string, forceSolid: boolean) => void;
+type CallbackSelect = (icon: string, forceSolid: boolean, value?: string, previewHtml?: string) => void;
 type IconData = { icon: string; forceSolid: boolean };
 
 function createIconList(): HTMLElement {
@@ -92,7 +92,9 @@ function setupListeners(): void {
 
 /**
  * Shows the FontAwesome selection dialog, supplied callback will be
- * invoked with the selection icon's name as the only argument.
+ * invoked with the selected icon's native data. Replacement
+ * implementations may pass an explicit stored value and preview html
+ * for non-native icons.
  */
 export function open(callback: CallbackSelect): void {
   const dialog = dialogFactory().fromElement(getContent()).asConfirmation();
diff --git a/wcfsetup/install/files/js/WoltLabSuite/Core/Acp/Ui/Trophy/Badge.js b/wcfsetup/install/files/js/WoltLabSuite/Core/Acp/Ui/Trophy/Badge.js
index 27cc00b101f..4f7e047bd07 100644
--- a/wcfsetup/install/files/js/WoltLabSuite/Core/Acp/Ui/Trophy/Badge.js
+++ b/wcfsetup/install/files/js/WoltLabSuite/Core/Acp/Ui/Trophy/Badge.js
@@ -14,14 +14,28 @@ define(["require", "exports", "tslib", "../../../Ui/Style/FontAwesome", "../../.
     Util_1 = tslib_1.__importDefault(Util_1);
     const badgeContainer = document.getElementById("badgeContainer");
     const previewWrapper = badgeContainer.querySelector(".trophyIcon");
-    const previewIcon = previewWrapper.querySelector("fa-icon");
+    function renderNativePreview(icon, forceSolid) {
+        let previewIcon = previewWrapper.querySelector("fa-icon");
+        if (!(previewIcon instanceof HTMLElement) || previewIcon.parentElement !== previewWrapper) {
+            previewWrapper.replaceChildren();
+            previewIcon = document.createElement("fa-icon");
+            previewIcon.size = 64;
+            previewWrapper.append(previewIcon);
+        }
+        previewIcon.setIcon(icon, forceSolid);
+    }
     function setupChangeIcon() {
         const button = badgeContainer.querySelector('.trophyIconEditButton[data-value="icon"]');
         const input = badgeContainer.querySelector('input[name="iconName"]');
         button.addEventListener("click", () => {
-            (0, FontAwesome_1.open)((icon, forceSolid) => {
-                previewIcon.setIcon(icon, forceSolid);
-                input.value = `${icon};${String(forceSolid)}`;
+            (0, FontAwesome_1.open)((icon, forceSolid, value, previewHtml) => {
+                input.value = value ?? `${icon};${String(forceSolid)}`;
+                if (typeof previewHtml === "string") {
+                    previewWrapper.innerHTML = previewHtml;
+                }
+                else {
+                    renderNativePreview(icon, forceSolid);
+                }
             });
         });
     }
diff --git a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Style/FontAwesome.js b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Style/FontAwesome.js
index 76f7d0ba805..705a8c2596c 100644
--- a/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Style/FontAwesome.js
+++ b/wcfsetup/install/files/js/WoltLabSuite/Core/Ui/Style/FontAwesome.js
@@ -74,7 +74,9 @@ define(["require", "exports", "tslib", "WoltLabSuite/Core/Language", "../ItemLis
     }
     /**
      * Shows the FontAwesome selection dialog, supplied callback will be
-     * invoked with the selection icon's name as the only argument.
+     * invoked with the selected icon's native data. Replacement
+     * implementations may pass an explicit stored value and preview html
+     * for non-native icons.
      */
     function open(callback) {
         const dialog = (0, Dialog_1.dialogFactory)().fromElement(getContent()).asConfirmation();
diff --git a/wcfsetup/install/files/lib/event/style/StoredIconResolving.class.php b/wcfsetup/install/files/lib/event/style/StoredIconResolving.class.php
new file mode 100644
index 00000000000..c8981113eeb
--- /dev/null
+++ b/wcfsetup/install/files/lib/event/style/StoredIconResolving.class.php
@@ -0,0 +1,24 @@
+<?php
+
+namespace wcf\event\style;
+
+use wcf\event\IPsr14Event;
+use wcf\system\style\IFontAwesomeIcon;
+
+/**
+ * Resolves a stored icon string to a renderable icon instance.
+ *
+ * @author      Sascha Greuel
+ * @copyright   2001-2026 WoltLab GmbH
+ * @license     GNU Lesser General Public License <http://opensource.org/licenses/lgpl-license.php>
+ * @since       6.2
+ */
+final class StoredIconResolving implements IPsr14Event
+{
+    public ?IFontAwesomeIcon $icon = null;
+
+    public function __construct(
+        public readonly string $iconData
+    ) {
+    }
+}
diff --git a/wcfsetup/install/files/lib/system/style/FontAwesomeIcon.class.php b/wcfsetup/install/files/lib/system/style/FontAwesomeIcon.class.php
index b37d3fa1650..9433ab557ed 100644
--- a/wcfsetup/install/files/lib/system/style/FontAwesomeIcon.class.php
+++ b/wcfsetup/install/files/lib/system/style/FontAwesomeIcon.class.php
@@ -2,6 +2,8 @@
 
 namespace wcf\system\style;
 
+use wcf\event\style\StoredIconResolving;
+use wcf\system\event\EventHandler;
 use wcf\system\style\exception\InvalidIconFormat;
 use wcf\system\style\exception\InvalidIconSize;
 use wcf\system\style\exception\UnknownIcon;
@@ -28,9 +30,13 @@ final class FontAwesomeIcon implements IFontAwesomeIcon, \Stringable
 
     private function __construct(
         private readonly string $name,
-        private readonly bool $forceSolid
+        private readonly bool $forceSolid,
+        private readonly ?string $iconData = null,
+        private readonly ?IFontAwesomeIcon $icon = null
     ) {
-        self::validateName($name);
+        if ($this->icon === null) {
+            self::validateName($name);
+        }
     }
 
     /**
@@ -39,6 +45,10 @@ private function __construct(
      */
     public function __toString(): string
     {
+        if ($this->iconData !== null) {
+            return $this->iconData;
+        }
+
         return \sprintf(
             "%s;%s",
             $this->name,
@@ -55,6 +65,10 @@ public function toHtml(int $size = 16): string
             throw new InvalidIconSize($size);
         }
 
+        if ($this->icon !== null) {
+            return $this->icon->toHtml($size);
+        }
+
         if ($this->forceSolid) {
             return \sprintf(
                 '<fa-icon size="%d" name="%s" solid></fa-icon>',
@@ -79,18 +93,21 @@ public function toHtml(int $size = 16): string
      */
     public static function fromString(string $iconData): self
     {
-        if (!\str_contains($iconData, ';')) {
-            throw new InvalidIconFormat();
+        $icon = self::parseIconData($iconData);
+        if ($icon !== null && self::isValidName($icon['name'])) {
+            return self::fromValues($icon['name'], $icon['forceSolid']);
         }
 
-        [$name, $solid] = \explode(';', $iconData, 2);
-        if ($solid !== 'true' && $solid !== 'false') {
-            throw new InvalidIconFormat();
+        $resolvedIcon = self::resolveStoredIcon($iconData);
+        if ($resolvedIcon !== null) {
+            return new self('question', true, $iconData, $resolvedIcon);
         }
 
-        $forceSolid = $solid === 'true';
+        if ($icon === null) {
+            throw new InvalidIconFormat();
+        }
 
-        return self::fromValues($name, $forceSolid);
+        return self::fromValues($icon['name'], $icon['forceSolid']);
     }
 
     public static function fromValues(string $name, bool $forceSolid = false): self
@@ -99,17 +116,41 @@ public static function fromValues(string $name, bool $forceSolid = false): self
     }
 
     public static function isValidString(string $iconData): bool
+    {
+        $icon = self::parseIconData($iconData);
+        if ($icon !== null && self::isValidName($icon['name'])) {
+            return true;
+        }
+
+        return self::resolveStoredIcon($iconData) !== null;
+    }
+
+    /**
+     * @return ?array{name: string, forceSolid: bool}
+     */
+    private static function parseIconData(string $iconData): ?array
     {
         if (!\str_contains($iconData, ';')) {
-            return false;
+            return null;
         }
 
         [$name, $solid] = \explode(';', $iconData, 2);
         if ($solid !== 'true' && $solid !== 'false') {
-            return false;
+            return null;
         }
 
-        return self::isValidName($name);
+        return [
+            'name' => $name,
+            'forceSolid' => $solid === 'true',
+        ];
+    }
+
+    private static function resolveStoredIcon(string $iconData): ?IFontAwesomeIcon
+    {
+        $event = new StoredIconResolving($iconData);
+        EventHandler::getInstance()->fire($event);
+
+        return $event->icon;
     }
 
     public static function isValidName(string $name): bool