REFACTOR: add jsdoc to DHContextMenu class

daggerheart.mjs

@@ -124,7 +124,7 @@ Hooks.once('init', () => {
     CONFIG.Token.rulerClass = placeables.DhTokenRuler;
 
     CONFIG.ui.resources = applications.ui.DhFearTracker;
-    CONFIG.ux.ContextMenu = applications.ux.ContextMenu;
+    CONFIG.ux.ContextMenu = applications.ux.DHContextMenu;
     CONFIG.ux.TooltipManager = documents.DhTooltipManager;
 
     game.socket.on(`system.${SYSTEM.id}`, socketRegistration.handleSocketEvent);

module/applications/ux/_module.mjs

@@ -1,2 +1,2 @@
 export { default as FilterMenu } from './filter-menu.mjs';
-export { default as ContextMenu } from './contextMenu.mjs';
+export { default as DHContextMenu } from './contextMenu.mjs';

module/applications/ux/contextMenu.mjs

@@ -1,4 +1,63 @@
-export default class DhContextMenu extends foundry.applications.ux.ContextMenu.implementation {
+/**
+ * @typedef ContextMenuEntry
+ * @property {string} name                              The context menu label. Can be localized.
+ * @property {string} [icon]                            A string containing an HTML icon element for the menu item.
+ * @property {string} [classes]                         Additional CSS classes to apply to this menu item.
+ * @property {string} [group]                           An identifier for a group this entry belongs to.
+ * @property {ContextMenuJQueryCallback} callback       The function to call when the menu item is clicked.
+ * @property {ContextMenuCondition|boolean} [condition] A function to call or boolean value to determine if this entry
+ *                                                      appears in the menu.
+ */
+
+/**
+ * @callback ContextMenuCondition
+ * @param {jQuery|HTMLElement} html                     The element of the context menu entry.
+ * @returns {boolean}                                   Whether the entry should be rendered in the context menu.
+ */
+
+/**
+ * @callback ContextMenuCallback
+ * @param {HTMLElement} target                          The element that the context menu has been triggered for.
+ * @returns {unknown}
+ */
+
+/**
+ * @callback ContextMenuJQueryCallback
+ * @param {HTMLElement|jQuery} target                   The element that the context menu has been triggered for. Will
+ *                                                      either be a jQuery object or an HTMLElement instance, depending
+ *                                                      on how the ContextMenu was configured.
+ * @returns {unknown}
+ */
+
+/**
+ * @typedef ContextMenuOptions
+ * @property {string} [eventName="contextmenu"] Optionally override the triggering event which can spawn the menu. If
+ *                                              the menu is using fixed positioning, this event must be a MouseEvent.
+ * @property {ContextMenuCallback} [onOpen]     A function to call when the context menu is opened.
+ * @property {ContextMenuCallback} [onClose]    A function to call when the context menu is closed.
+ * @property {boolean} [fixed=false]            If true, the context menu is given a fixed position rather than being
+ *                                              injected into the target.
+ * @property {boolean} [jQuery=true]            If true, callbacks will be passed jQuery objects instead of HTMLElement
+ *                                              instances.
+ */
+
+/**
+ * @typedef ContextMenuRenderOptions
+ * @property {Event} [event]           The event that triggered the context menu opening.
+ * @property {boolean} [animate=true]  Animate the context menu opening.
+ */
+
+/**
+ * A subclass of ContextMenu.
+ * @extends {foundry.applications.ux.ContextMenu}
+ */
+export default class DHContextMenu extends foundry.applications.ux.ContextMenu {
+    /**
+     * @param {HTMLElement|jQuery} container - The HTML element that contains the context menu targets.
+     * @param {string} selector - A CSS selector which activates the context menu.
+     * @param {ContextMenuEntry[]} menuItems - An Array of entries to display in the menu
+     * @param {ContextMenuOptions} [options] - Additional options to configure the context menu.
+     */
     constructor(container, selector, menuItems, options) {
         super(container, selector, menuItems, options);
 
@@ -6,12 +65,21 @@ export default class DhContextMenu extends foundry.applications.ux.ContextMenu.i
         this.#jQuery = options.jQuery;
     }
 
+    /**
+     * Whether to pass jQuery objects or HTMLElement instances to callback.
+     * @type {boolean}
+     */
     #jQuery;
 
+    /**@inheritdoc */
     activateListeners(menu) {
         menu.addEventListener('click', this.#onClickItem.bind(this));
     }
 
+    /**
+     * Handle click events on context menu items.
+     * @param {PointerEvent} event      The click event
+     */
     #onClickItem(event) {
         event.preventDefault();
         event.stopPropagation();
@@ -22,6 +90,12 @@ export default class DhContextMenu extends foundry.applications.ux.ContextMenu.i
         this.close();
     }
 
+    /* -------------------------------------------- */
+
+    /**
+     * Trigger a context menu event in response to a normal click on a additional options button.
+     * @param {PointerEvent} event
+     */
     static triggerContextMenu(event) {
         event.preventDefault();
         event.stopPropagation();

module/applications/ux/filter-menu.mjs

@@ -197,10 +197,12 @@ export default class FilterMenu extends foundry.applications.ux.ContextMenu {
             }
         }));
 
+        const sort = arr => game.i18n.sortObjects(arr, 'name');
+
         return [
-            ...game.i18n.sortObjects(typesFilters, 'name'),
+            ...sort(typesFilters, 'name'),
-            ...game.i18n.sortObjects(burdenFilter, 'name'),
+            ...sort(burdenFilter, 'name'),
-            ...game.i18n.sortObjects(damageTypeFilter, 'name')
+            ...sort(damageTypeFilter, 'name')
         ];
     }