From 1cc9dda76e8d7d393897402774787d5c91b492fe Mon Sep 17 00:00:00 2001 From: Joaquin Pereyra Date: Sat, 5 Jul 2025 11:49:39 -0300 Subject: [PATCH] REFACTOR: add jsdoc to DHContextMenu class --- daggerheart.mjs | 2 +- module/applications/ux/_module.mjs | 2 +- module/applications/ux/contextMenu.mjs | 76 +++++++++++++++++++++++++- module/applications/ux/filter-menu.mjs | 8 ++- 4 files changed, 82 insertions(+), 6 deletions(-) diff --git a/daggerheart.mjs b/daggerheart.mjs index 81b404d5..82c56dff 100644 --- a/daggerheart.mjs +++ b/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); diff --git a/module/applications/ux/_module.mjs b/module/applications/ux/_module.mjs index 5ec0eecf..ead918fa 100644 --- a/module/applications/ux/_module.mjs +++ b/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'; diff --git a/module/applications/ux/contextMenu.mjs b/module/applications/ux/contextMenu.mjs index f7658d42..a913c450 100644 --- a/module/applications/ux/contextMenu.mjs +++ b/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(); diff --git a/module/applications/ux/filter-menu.mjs b/module/applications/ux/filter-menu.mjs index ff2fb036..93d8bbf0 100644 --- a/module/applications/ux/filter-menu.mjs +++ b/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'), - ...game.i18n.sortObjects(burdenFilter, 'name'), - ...game.i18n.sortObjects(damageTypeFilter, 'name') + ...sort(typesFilters, 'name'), + ...sort(burdenFilter, 'name'), + ...sort(damageTypeFilter, 'name') ]; }