From 65f854678293c2942bebe076ac1a3b51f49645ab Mon Sep 17 00:00:00 2001
From: mister-ben <1676039+mister-ben@users.noreply.github.com>
Date: Wed, 14 Aug 2024 21:00:01 +0200
Subject: [PATCH] fix(types): ensure toggleClass's second arg is optional
 (#8829)

## Description
Generated types are mangled for `Component.toggleClass()`, because tsc
doesn't understand `~` namespaces. The second arg is then not marked as
optional.

## Specific Changes proposed
Refactor JSDoc

## Requirements Checklist
- [x] Feature implemented / Bug fixed
- [ ] If necessary, more likely in a feature request than a bug fix
- [ ] Change has been verified in an actual browser (Chrome, Firefox,
IE)
  - [ ] Unit Tests updated or fixed
  - [ ] Docs/guides updated
- [ ] Example created ([starter template on
JSBin](https://codepen.io/gkatsev/pen/GwZegv?editors=1000#0))
- [x] Has no DOM changes which impact accessiblilty or trigger warnings
(e.g. Chrome issues tab)
  - [x] Has no changes to JSDoc which cause `npm run docs:api` to error
- [ ] Reviewed by Two Core Contributors
---
 src/js/component.js | 6 +++---
 src/js/utils/dom.js | 9 +++++----
 2 files changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/js/component.js b/src/js/component.js
index 4340eed558..1b86498f7b 100644
--- a/src/js/component.js
+++ b/src/js/component.js
@@ -983,10 +983,10 @@ class Component {
    * - `classToToggle` gets removed when {@link Component#hasClass} would return true.
    *
    * @param  {string} classToToggle
-   *         The class to add or remove based on (@link Component#hasClass}
+   *         The class to add or remove. Passed to DOMTokenList's toggle()
    *
-   * @param  {boolean|Dom~predicate} [predicate]
-   *         An {@link Dom~predicate} function or a boolean
+   * @param  {boolean|Dom.PredicateCallback} [predicate]
+   *         A boolean or function that returns a boolean. Passed to DOMTokenList's toggle().
    */
   toggleClass(classToToggle, predicate) {
     Dom.toggleClass(this.el_, classToToggle, predicate);
diff --git a/src/js/utils/dom.js b/src/js/utils/dom.js
index 095825e7c5..0505850064 100644
--- a/src/js/utils/dom.js
+++ b/src/js/utils/dom.js
@@ -262,7 +262,7 @@ export function removeClass(element, ...classesToRemove) {
 /**
  * The callback definition for toggleClass.
  *
- * @callback module:dom~PredicateCallback
+ * @callback PredicateCallback
  * @param    {Element} element
  *           The DOM element of the Component.
  *
@@ -271,8 +271,9 @@ export function removeClass(element, ...classesToRemove) {
  *
  * @return   {boolean|undefined}
  *           If `true` is returned, the `classToToggle` will be added to the
- *           `element`. If `false`, the `classToToggle` will be removed from
- *           the `element`. If `undefined`, the callback will be ignored.
+ *           `element`, but not removed. If `false`, the `classToToggle` will be removed from
+ *           the `element`, but not added. If `undefined`, the callback will be ignored.
+ *
  */
 
 /**
@@ -285,7 +286,7 @@ export function removeClass(element, ...classesToRemove) {
  * @param  {string} classToToggle
  *         The class that should be toggled.
  *
- * @param  {boolean|module:dom~PredicateCallback} [predicate]
+ * @param  {boolean|PredicateCallback} [predicate]
  *         See the return value for {@link module:dom~PredicateCallback}
  *
  * @return {Element}