From aa905f638bbea694cde78fc7b386647bdcc4ac8c Mon Sep 17 00:00:00 2001
From: Stalgia Grigg <stalgia@bocoup.com>
Date: Wed, 11 Dec 2024 08:57:12 -0800
Subject: [PATCH] JSDoc example for translatePlatformKeys, rename
 translatePlatformKey

---
 test/tests/toolbar_toolbar.js      | 12 ++++----
 test/util/translatePlatformKey.js  | 26 -----------------
 test/util/translatePlatformKeys.js | 45 ++++++++++++++++++++++++++++++
 3 files changed, 52 insertions(+), 31 deletions(-)
 delete mode 100644 test/util/translatePlatformKey.js
 create mode 100644 test/util/translatePlatformKeys.js

diff --git a/test/tests/toolbar_toolbar.js b/test/tests/toolbar_toolbar.js
index 1e1ad4b44..76b21b1d2 100644
--- a/test/tests/toolbar_toolbar.js
+++ b/test/tests/toolbar_toolbar.js
@@ -7,7 +7,7 @@ const assertAttributeValues = require('../util/assertAttributeValues');
 const assertRovingTabindex = require('../util/assertRovingTabindex');
 const assertHasFocus = require('../util/assertHasFocus');
 const assertAttributeCanBeToggled = require('../util/assertAttributeCanBeToggled');
-const translatePlatformKey = require('../util/translatePlatformKey');
+const translatePlatformKey = require('../util/translatePlatformKeys');
 
 const exampleFile = 'content/patterns/toolbar/examples/toolbar.html';
 
@@ -1116,8 +1116,9 @@ ariaTest(
   'toolbar-button-enter-or-space',
   async (t) => {
     let textarea = await t.context.session.findElement(By.css('textarea'));
-    let modifierKey = translatePlatformKey(Key.CONTROL);
-    await textarea.sendKeys(Key.chord(...modifierKey, 'a'));
+    let selectAllKeys = translatePlatformKey([Key.CONTROL, 'a']);
+    let selectAllChord = Key.chord(...selectAllKeys);
+    await textarea.sendKeys(selectAllChord);
     let originalText = await textarea.getAttribute('value');
 
     const buttons = await t.context.queryElements(
@@ -1208,8 +1209,9 @@ ariaTest(
   'toolbar-button-enter-or-space',
   async (t) => {
     let textarea = await t.context.session.findElement(By.css('textarea'));
-    let modifierKey = translatePlatformKey(Key.CONTROL);
-    await textarea.sendKeys(Key.chord(...modifierKey, 'a'));
+    let selectAllKeys = translatePlatformKey([Key.CONTROL, 'a']);
+    let selectAllChord = Key.chord(...selectAllKeys);
+    await textarea.sendKeys(selectAllChord);
     let originalText = await textarea.getAttribute('value');
 
     const buttons = await t.context.queryElements(
diff --git a/test/util/translatePlatformKey.js b/test/util/translatePlatformKey.js
deleted file mode 100644
index 692727892..000000000
--- a/test/util/translatePlatformKey.js
+++ /dev/null
@@ -1,26 +0,0 @@
-const { Key } = require('selenium-webdriver');
-const isMacOS = require('./isMacOS');
-
-const MAC_KEY_MAPPINGS = {
-  [Key.CONTROL]: Key.META,
-};
-
-/**
- * Translates a key or key combination for the current OS
- *
- * @param {string|string[]} keys - The key(s) to translate
- * @returns {string[]} - The translated key(s) as a flat array ready for spreading
- */
-function translatePlatformKey(keys) {
-  const keyArray = Array.isArray(keys) ? keys : [keys];
-  if (!isMacOS()) {
-    return keyArray;
-  }
-
-  return keyArray.reduce((acc, key) => {
-    const mappedKey = MAC_KEY_MAPPINGS[key] || key;
-    return acc.concat(mappedKey);
-  }, []);
-}
-
-module.exports = translatePlatformKey;
diff --git a/test/util/translatePlatformKeys.js b/test/util/translatePlatformKeys.js
new file mode 100644
index 000000000..333e0a1fc
--- /dev/null
+++ b/test/util/translatePlatformKeys.js
@@ -0,0 +1,45 @@
+const { Key } = require('selenium-webdriver');
+const isMacOS = require('./isMacOS');
+
+const MAC_KEY_MAPPINGS = {
+  [Key.CONTROL]: Key.META,
+};
+
+/**
+ * Translates a key or key combination for the current OS
+ *
+ * @param {string|string[]} keys - The key(s) to translate
+ * @returns {string[]} - The translated key(s) as a flat array ready for spreading
+ *
+ * @example
+ * // On macOS, translates CONTROL to META (Command key)
+ * translatePlatformKey(Key.CONTROL)
+ * // Returns: [Key.META]
+ *
+ * // On non-macOS systems, returns key unchanged
+ * translatePlatformKey(Key.CONTROL)
+ * // Returns: [Key.CONTROL]
+ *
+ * // Works with arrays of keys for key combinations
+ * translatePlatformKey([Key.CONTROL, 'a'])
+ * // Returns on macOS: [Key.META, 'a']
+ * // Returns on Windows/Linux: [Key.CONTROL, 'a']
+ *
+ * // Usage with Selenium WebDriver:
+ * const selectAllKeys = translatePlatformKey([Key.CONTROL, 'a']);
+ * const selectAllChord = Key.chord(...selectAllKeys);
+ * await element.sendKeys(selectAllChord);
+ */
+function translatePlatformKeys(keys) {
+  const keyArray = Array.isArray(keys) ? keys : [keys];
+  if (!isMacOS()) {
+    return keyArray;
+  }
+
+  return keyArray.reduce((acc, key) => {
+    const mappedKey = MAC_KEY_MAPPINGS[key] || key;
+    return acc.concat(mappedKey);
+  }, []);
+}
+
+module.exports = translatePlatformKeys;