chore: add jsdoc and types

src/store/keycodes.js

@@ -16,6 +16,10 @@ const keycodePickerTabLayout = {
   special: [...quantum, ...settings, ...media]
 };
 
+/**
+ * Validates the os keyboard layout and if not valid returns a default of 'keymap_us'.
+ * @returns {string}
+ */
 function getOSKeyboardLayout() {
   let osKeyboardLayout = store.getters['app/osKeyboardLayout'];
   if (isUndefined(osKeyboardLayout) || !keymapExtras[osKeyboardLayout]) {
@@ -33,10 +37,16 @@ function isANSI() {
   return keymapExtras[getOSKeyboardLayout()].isANSI;
 }
 
+/**
+ * Remap keycodes to their Locale equivalent for the OS layout.
+ * @param {Object} keycodeLUT
+ * @param {KeycodeDefinition|KeycodeLabel|WidthPlaceholder} keycodeObject
+ * @returns {KeycodeDefinition|WidthPlaceholder|KeycodeLabel}
+ */
 function toLocaleKeycode(keycodeLUT, keycodeObject) {
   console.assert(!isUndefined(keycodeLUT));
   if (!keycodeObject.name || !keycodeObject.code) {
-    // Not an object describing a keyboard key; return as is
+    // Not a KeycodeDefinition; return as is
     return keycodeObject;
   }
   if (keycodeLUT[keycodeObject.code]) {
@@ -48,6 +58,15 @@ function toLocaleKeycode(keycodeLUT, keycodeObject) {
   }
 }
 
+/**
+ * Used to dynamically generate the tab data for they keycode
+ * display. This UI is customized based on the OS keyboard layout
+ * selected.
+ *
+ * @param {string} osKeyboardLayout
+ * @param {boolean} isSteno
+ * @returns {Array.<KeycodeDefinition|KeycodeLabel|WidthPlaceholder}
+ */
 function generateKeycodes(osKeyboardLayout, isSteno = false) {
   store.commit('app/setIso', !isANSI());
   const keycodes = [
@@ -63,6 +82,15 @@ function generateKeycodes(osKeyboardLayout, isSteno = false) {
   );
 }
 
+/**
+ * Counts the number of potential matches in each keycode array.
+ * The keycode arrays represent the source data used to render the keycodes
+ * display. This count is used to give hints of matches per tab in the UI.
+ *
+ * @param {string} filter
+ * @param {Array.<KeycodeDefinition|KeycodeLabel|WidthPlaceholder>} collection of keycode objects
+ * @returns
+ */
 function countMatches(filter, collection) {
   filter = filter.toUpperCase();
   return collection.reduce((matchCount, { code, name, title }) => {
@@ -79,7 +107,14 @@ function countMatches(filter, collection) {
   }, 0);
 }
 
+/**
+ * Use Options style for now.
+ */
 export const useKeycodesStore = defineStore('keycodes', {
+  /**
+   *
+   * @returns {KeycodeStoreState}
+   */
   state: () => ({
     keycodes: [
       ...keycodePickerTabLayout.ANSI_ISO,
@@ -136,3 +171,48 @@ export const useKeycodesStore = defineStore('keycodes', {
     }
   }
 });
+
+/**
+ * @typedef {Object} KeycodeLabel - used to label groups of keycodes
+ * @property {string} label - Label name
+ * @property {'label'} width - always the special indicator 'label'
+ * @property {boolean} group - group following keycodes under this
+ * @property {string} icon - font-awesome icon to display
+ * @property {string} iconClass - css class to apply
+ */
+
+/**
+ * @typedef {Object} WidthPlaceholder - used for spacing
+ * @property {number} width - width in Key Units * 1000. e.g. 1U = 1000, 2U = 2000.
+ */
+
+/**
+ * @typedef {Object} KeycodeDefinition - metadata about a keycode
+ * @property {string} name - UI display label for the keycode
+ * @property {string} code - QMK keycode defintion
+ * @property {boolean} keys - javascript keypress id. Used by keyboard handler
+ * @property {number} width - width in Key Units * 1000. e.g. 1U = 1000, 2U = 2000.
+ * @property {'text'|'layer'|'container'|'layer-container'} type
+ * @property {number} layer
+ * @property {string} title - help text for hover
+ */
+
+/**
+ * @typedef {{}
+ *  & Record<'ISO/JIS', number>
+ *  & Record<'ANSI', number>
+ *  & Record<'Quantum', number>
+ *  & Record<'KeyboardSettings', number>
+ *  & Record<'AppMediaMouse', number>
+ * } SearchCounters
+ *
+ */
+
+/**
+ * @typedef {Object} KeycodeStoreState
+ * @property {Array.<KeycodeDefinition|KeycodeLabel|WidthPlaceholder>} keycodes - active keycodes
+ * @property {string} searchFilter - currently search filter
+ * @property {SearchCounters} searchCounters - count of matching keycodes per tab
+ * @property {boolean} steno - is steno tab active
+ * @property {'ANSI'|'ISO/JIS'|'AppMediaMouse'|'Quantum'|'Steno'|'KeyboardSettings'} active - active tab
+ */