add aliases search array and display best matches for aliases to user

README.md

@@ -134,6 +134,7 @@ const c = new CommandPal({
   placeholder: "Custom placeholder text...", //  Changes placeholder text of input
   debugOuput: false, // if true report debugging info to console
   hideButton: false, // if true, do not generate mobile button
+  displayHints: false,  // if true, aliases are displayed as command hints
   commands: [
     // Commands go here
   ]
@@ -166,12 +167,16 @@ c.subscribe("closed", (e) => { console.log("closed", { e }); });
   name: "Open Messages",
   // Required name of command (displayed)
   description: "View all messages in inbox",
+  // Other names for the command that can be hints for the user
+  aliases: [ "View", "See" ],
   // Shortcut of command
   shortcut: "ctrl+3",
   // Callback function of the command to execute
   handler: (e) => {
     // DO SOMETHING
-  }
+  },
+  orderedCommands: false, // set true if command array is ordered/weighted
+                          // see below on Order of Matched Items
   // Child commands which can be executed
   children: [...]
 },
@@ -247,6 +252,70 @@ Which allows you to style a specific instance.
   #mypal .mobile-button  { top: 30px; bottom: auto;}
 ```
 
+#### Aliases and Hints
+
+The aliases property is included by the fuzzy search. So searching for
+terms in the aliases array always works. Matches in the aliases array
+are weighted twice that of the name or description fields. However
+setting the `displayHints` option for `CommandPal` to `true` displays
+the best matching alias next to the command.
+
+For example suppose the `Open Messages` command has aliases of `See`
+and `View`. Typing `se` will display `Open Messages (See)` indicating
+that you should use the `Open Messages` command to see your messages.
+It helps explain what's being matched and why `Open Messages` is
+displayed when `see` is typed.  Similarly typing `vi` will produce
+`Open Messages (View)` in the command list. If you were to type `v`
+you would start with `Open Messages (View)` then typing `e` would
+result in `Open Messages (See)`. By default `displayHints` is
+disabled.
+
+The fuse.js fuzzy matcher returns match info. This indicates where it
+found matches to the search input.  This information is used to select
+the top hint to display to the user. For each match in the aliases
+array, the score is the count of the number of matching characters
+with a little extra weight given to matches at the beginning of the
+alias. If two terms have the same weight, the term more to the left in
+the array is chosen. To get the best use from this, order your terms
+putting the most used terms first in the array. This scoring method is
+a work in progress and may change in the future.
+
+Also keep your aliases short when possible. Don't include terms in the
+alias that are already in the command. This helps prevent skewing of
+the scores (due to the same term being matched multiple times). It also
+keeps the command text size down making it more readable.
+Aliases in non-Latin languages should work.
+
+### Order of Matched Items
+
+There are two ways to sort the matched items. You can use the score
+returned by the fuse.js fuzzy-search library. In many fuzzy searches,
+when the scores show that the confidence in the match is not high, you
+can nudge it to return a better order.
+
+To do that with command-pal, you should order your commands from most
+used/likely choice to worst/least used. Then set: `orderedCommands:
+true` when calling CommandPal.
+
+To allow you to nudge the results, the sort function for fuse.js is
+replaced.  The new sort function establishes a threshold for a high
+confidence match. If the match is high confidence, the function sorts
+the results using the score from fuse.js. If the confidence is lower,
+all results that fall in a given range get bucketed together. The sort
+function sorts the results to the order of its entry in the command
+array.
+
+E.G. In the commands array: `cat` is 10th and `car` is 15th. If the
+current search term returns scores for `cat` and `car` that are close
+to each other, cat(10) will sort before car(15). This will happen even
+if `car` has a better score than `cat`. If you reverse the positions
+of `cat` and `car` in the array, they will sort in the opposite
+direction.
+
+The algorithm is simple. But it does allow you, the developer, to
+nudge the order of the results in the direction you want. See the code
+for the current values used in the algorithm.
+
 ## Local Development
 
 To develop on `command-pal` simply clone, install and run

package.json

@@ -39,7 +39,7 @@
     "typescript": "^4.9.5"
   },
   "dependencies": {
-    "fuse.js": "^5.2.3",
+    "fuse.js": "^6.6.2",
     "hotkeys-js": "^3.7.6",
     "micro-pubsub": "1.0.0"
   }

src/App.svelte

@@ -19,13 +19,47 @@
   export let placeholderText: string;
   export let hideButton: boolean;;
   export let paletteId: string;
+  export let displayHints: boolean;
+  export let debugOutput: boolean;
+  export let orderedCommands: boolean;
+
+  // re: space '(' alphanumeric_word_char
+  //            "0 or more word_char space/tab and -" ')'
+  //            end of line
+  // Note: this should be the unicode equivalent of the Latin regexp:
+  //    / \(\w[\s\w-]*\)$/
+  let hintRegexp = / \([ \u0000-\u0019\u0021-\uFFFF_-]+\)$/u;
 
   const optionsFuse = {
     isCaseSensitive: false,
     shouldSort: true,
-    keys: ["name", "description"]
+    keys: ["name", "description", {name: "aliases", weight: 2}],
+    includeScore: true,
+    includeMatches: true,
   };
 
+  if ( orderedCommands ) {
+    optionsFuse.sortFn = function(a, b) {
+      const belowThreshold = a.score < 0.009 || b.score < 0.009;
+      const scoresAreEqual = a.score === b.score;
+      const scoresClose = Math.abs(a.score - b.score) < 0.05;
+
+      if (belowThreshold) {
+        return a.score < b.score ? -1 : 1;
+      } else if (scoresClose) {
+        return a.idx < b.idx ? -1 : 1;
+      } else if (scoresAreEqual) {
+        return a.idx < b.idx ? -1 : 1;
+      } else {
+        return a.score < b.score ? -1 : 1;
+      }
+    }
+    if (debugOutput) console.log('Using commands weighted sort');
+
+  } else {
+    if (debugOutput) console.log("Using fuse.js's score for sorting");
+  }
+
   let showModal = false;
   let searchField;
   let loadingChildren = false;
@@ -114,15 +148,106 @@
     }
   }
 
+  function removeHints(items) {
+    if (! displayHints ) return;
+    items.map( (i) => { if ( i.hinted ) {
+      i.name = i.name.replace(hintRegexp, '');
+      i.hinted = false
+    }})
+  }
+
+  /** append best aliases match to command object's name */
+  function hintMatch(search_result) {
+    /**
+     * Accepts an array of 2 element arrays. These are the start/stop
+     * that matched the search term for the current match. A metric
+     * is calculated from these. Larger values indicate better matches.
+     *
+     * @param {array} indexList - list of 2 element lists
+     * 
+     * For each index_list use the [start, end] range to calculate a
+     * score. [0,*] indicates first char of term matched. It counts
+     * for an additional 0.5 points. Each multi character match [6,7]
+     * (2 chars) counts for 2.5 points/char. All numbers are magic
+     * weighting factors that seem to work. Formula and number may
+     * change.
+    */
+    let match_metric = (indices) => ( indices.map(
+      range => range[0] == 0 ?
+	((range[1] - range[0])
+	 * 2.5) + 1.5 :
+	((range[1] - range[0]) * 2.5) + 1
+     ).reduce((sum, val) => sum+val))
+
+    const e = search_result.matches.filter(
+      i => i.key === "aliases").sort((a,b) => {
+	let a_mm = match_metric(a.indices)
+	let b_mm = match_metric(b.indices)
+
+	// a higher match_metric is assigned to a term that is a
+	// better match for the search.
+	// Sort by higher match_metric. If match_metrics are equal,
+	// sort the one with the lower index in the aliases array
+	// first. (Put the best choice aliases first.)
+	//    1 - sort b before a; -1 sort a before b.
+	// note: a.refIndex can never equal b.refIndex
+	return a_mm == b_mm ?
+      	  (a.refIndex < b.refIndex ? -1 : 1) :
+          ( a_mm > b_mm? -1 : 1)
+      })
+
+    let item = search_result.item
+    let hinted = !!item.hinted
+    if ( e.length ) {
+      /* add hints */
+      const hint = ` (${e[0].value})`
+      if (! hinted) {
+	item.name += hint
+      } else {
+	item.name = item.name.replace(hintRegexp, hint)
+      }
+      item.hinted = true
+    } else {
+      if (item.hinted) {
+	/* remove previous hints */
+	item.name = item.name.replace(hintRegexp, '')
+	item.hinted = false
+      }
+    }
+    if (debugOutput) {
+      console.group("CommandPal " + item.name);
+      console.debug('score', search_result.score)
+      console.debug('index', search_result.refIndex)
+      console.debug('weight', item.weight)
+      console.debug('hints', e.length)
+      console.table(search_result.matches.filter( (i) => {
+	if (i.key === "aliases") {
+	  i.metric = match_metric(i.indices);
+	  return true;
+	}
+	return false;
+      }))
+      console.groupEnd();
+    }
+    return item
+  }
+
   function onTextChange(e) {
     const text = e.detail;
     dispatch("textChanged", text);
     selectedIndex = 0;
+
+    const processResult = displayHints ? hintMatch: (i) => i.item
+
     if (!text) {
       itemsFiltered = items;
+      removeHints(itemsFiltered);
     } else {
       const fuseResult = fuse.search(text);
-      itemsFiltered = fuseResult.map(i => i.item);
+      if (debugOutput && displayHints) console.groupCollapsed(
+        "CommandPal search: " + text)
+      itemsFiltered = fuseResult.map(processResult);
+      if (debugOutput && displayHints) console.groupEnd()
     }
   }
 
@@ -133,6 +258,7 @@
     }
     dispatch("closed");
     selectedIndex = 0;
+    removeHints(inputData);
     setItems(inputData);
     showModal = false;
     if ( ! focusedElement ) {

src/main.js

@@ -19,6 +19,9 @@ class CommandPal {
         placeholderText: this.options.placeholder || "What are you looking for?",
         hotkeysGlobal: this.options.hotkeysGlobal || false,
         hideButton: this.options.hideButton || false,
+        displayHints: this.options.displayHints || false,
+        orderedCommands: this.options.orderedCommands || false,
+        debugOutput: this.options.debugOutput || false,
       },
     });
     const ctx = this;