Merge pull request #41 from jobara/feat/keyboard-support-input-area

feat: keyboard support for input area

Author: klown

README.md

@@ -12,6 +12,9 @@ The front end of the project is built with [Preact](https://preactjs.com/).
 To work on the project, you need to install [NodeJS and NPM](https://nodejs.org/en/download/)
 for your operating system.
 
+_**Note:** If you'd like to make use of RAG (optional), you'll also need to ensure that [CMake](http://cmake.org)
+is installed. CMake is required for installing `faiss` which is pulled in by the dependency `faiss-node`._
+
 Then, clone the project from GitHub. [Create a fork](https://help.github.com/en/github/getting-started-with-github/fork-a-repo)
 with your GitHub account, then enter the following in your command line
 (make sure to replace `your-username` with your username):
@@ -51,7 +54,7 @@ The website will be available at [http://localhost:3000](http://localhost:3000).
 
 RAG (Retrieval-Augmented Generation) is an AI technique designed to enhance the accuracy of generative models by
 incorporating factual knowledge from external sources. It requires loading factual knowledge into a vector store
-that will be quried to provide relevant information to the language model as a context.
+that will be queried to provide relevant information to the language model as a context.
 
 By default, the use of RAG is turned off in the system. The `enableRag` flag is set to `false` by default in the
 [config/config.ts](./config/config.ts).
@@ -90,6 +93,12 @@ Follow these steps to complete a one-time setup to enable RAG in the system:
 
    Follow the instruction in the [Start a Server](./README.md#start-a-server) section.
 
+#### Troubleshooting
+
+In order to use RAG, `fais-node` must be installed. `faise-node` requires that [CMake](https://cmake.org/)
+be installed on the machine first. If this has not been done, install CMake and re-run the application install
+steps.
+
 ### Lint
 
 To lint the source code, run:

src/client/CommandCursorBackward.ts

@@ -12,7 +12,7 @@
 import { VNode } from "preact";
 import { html } from "htm/preact";
 import { BlissSymbol } from "./BlissSymbol";
-import { changeEncodingContents } from "./GlobalData";
+import { decrementCursor } from "./ContentBmwEncoding";
 import { BlissSymbolInfoType, LayoutInfoType } from "./index.d";
 import { generateGridStyle, speak } from "./GlobalUtils";
 
@@ -33,15 +33,7 @@ export function CommandCursorBackward (props: CommandCursorBackwardProps): VNode
   const gridStyles = generateGridStyle(columnStart, columnSpan, rowStart, rowSpan);
 
   const cellClicked = (): void => {
-    // Move the caret position back one.  Note that the new caretPosition can
-    // equal -1 indicating that the caret is before the first symbol in the
-    // `payloads` array.  But, it cannot be less than -1.
-    if (changeEncodingContents.value.caretPosition > -1) {
-      changeEncodingContents.value = {
-        payloads: changeEncodingContents.value.payloads,
-        caretPosition: changeEncodingContents.value.caretPosition - 1
-      };
-    }
+    decrementCursor();
     speak(label);
   };
 

src/client/CommandCursorForward.ts

@@ -12,7 +12,7 @@
 import { VNode } from "preact";
 import { html } from "htm/preact";
 import { BlissSymbol } from "./BlissSymbol";
-import { changeEncodingContents } from "./GlobalData";
+import { incrementCursor } from "./ContentBmwEncoding";
 import { BlissSymbolInfoType, LayoutInfoType } from "./index.d";
 import { generateGridStyle, speak } from "./GlobalUtils";
 
@@ -33,12 +33,7 @@ export function CommandCursorForward (props: CommandCursorForwardProps): VNode {
   const gridStyles = generateGridStyle(columnStart, columnSpan, rowStart, rowSpan);
 
   const cellClicked = (): void => {
-    if (changeEncodingContents.value.caretPosition < changeEncodingContents.value.payloads.length - 1) {
-      changeEncodingContents.value = {
-        payloads: changeEncodingContents.value.payloads,
-        caretPosition: changeEncodingContents.value.caretPosition + 1
-      };
-    }
+    incrementCursor();
     speak(label);
   };
 

src/client/ContentBmwEncoding.test.ts

@@ -12,7 +12,7 @@
 import { render, screen } from "@testing-library/preact";
 import "@testing-library/jest-dom";
 import { html } from "htm/preact";
-import { ContentBmwEncoding } from "./ContentBmwEncoding";
+import { ContentBmwEncoding} from "./ContentBmwEncoding";
 import { initAdaptivePaletteGlobals } from "./GlobalData";
 
 test("The BMW Encoding content area is rendered correctly", async (): Promise<void> => {

src/client/ContentBmwEncoding.ts

@@ -14,11 +14,13 @@ import { html } from "htm/preact";
 import { BlissSymbol } from "./BlissSymbol";
 import { changeEncodingContents } from "./GlobalData";
 import { ContentBmwEncodingType, EncodingType } from "./index.d";
-import { generateGridStyle } from "./GlobalUtils";
+import { generateGridStyle, clamp, speak } from "./GlobalUtils";
 import "./ContentBmwEncoding.scss";
 
 export const INPUT_AREA_ID = "bmw-encoding-area";   // better way?
 
+const isApplePlatform = navigator.platform.startsWith("Mac") || navigator.platform.startsWith("iPhone") || navigator.platform.startsWith("iPad");
+
 type ContentBmwEncodingProps = {
   id: string,
   options: ContentBmwEncodingType
@@ -66,6 +68,64 @@ function generateMarkupArray (payloadArray: Array<EncodingType>, caretPos: numbe
   });
 }
 
+function moveCursor (positionChange: number = 1) {
+  // Note: the new caretPosition can equal -1 indicating that the caret is before the
+  // first symbol in the `payloads` array.  But, it cannot be less than -1.
+  const newPosition = clamp(changeEncodingContents.value.caretPosition + positionChange, -1, changeEncodingContents.value.payloads.length - 1);
+  changeEncodingContents.value = {
+    payloads: changeEncodingContents.value.payloads,
+    caretPosition: newPosition
+  };
+};
+
+export function incrementCursor () {
+  moveCursor(1);
+}
+
+export function decrementCursor () {
+  moveCursor(-1);
+}
+
+export function moveCursorToHome () {
+  moveCursor(Number.NEGATIVE_INFINITY);
+};
+
+export function moveCursorToEnd () {
+  moveCursor(Number.POSITIVE_INFINITY);
+};
+
+function handleKeyDown(event: KeyboardEvent) {
+  if ((!(isApplePlatform && event.metaKey) && event.key === "ArrowLeft") || event.key === "ArrowDown") {
+    decrementCursor();
+    speak("backward");
+  }
+
+  if ((!(isApplePlatform && event.metaKey) && event.key === "ArrowRight") || event.key === "ArrowUp") {
+    incrementCursor();
+    speak("forward");
+  }
+
+  if (
+    event.key === "Home" ||
+    (event.ctrlKey && event.key === "a") ||
+    (isApplePlatform && event.metaKey && event.key === "ArrowLeft")
+  ) {
+    event.preventDefault();
+    moveCursorToHome();
+    speak("move cursor to start");
+  }
+
+  if (
+    event.key === "End" ||
+    (event.ctrlKey && event.key === "e") ||
+    (isApplePlatform && event.metaKey && event.key === "ArrowRight")
+  ) {
+    event.preventDefault();
+    moveCursorToEnd();
+    speak("move cursor to end");
+  }
+}
+
 export function ContentBmwEncoding (props: ContentBmwEncodingProps): VNode {
   const { id, options } = props;
   const { columnStart, columnSpan, rowStart, rowSpan } = options;
@@ -76,7 +136,15 @@ export function ContentBmwEncoding (props: ContentBmwEncodingProps): VNode {
   );
 
   return html`
-    <div id="${id}" class="bmwEncodingArea" role="textbox" aria-label="Input Area" aria-readonly="true" style="${gridStyles}">
+    <div
+      id="${id}"
+      class="bmwEncodingArea"
+      role="textbox"
+      aria-label="Input Area"
+      aria-readonly="true"
+      style="${gridStyles}"
+      tabindex="0"
+      onKeyDown=${handleKeyDown}>
       ${contentsMarkupArray}
     </div>
   `;

src/client/GlobalUtils.test.ts

@@ -9,12 +9,24 @@
  * https://github.com/inclusive-design/adaptive-palette/blob/main/LICENSE
  */
 
-import { generateGridStyle } from "./GlobalUtils";
+import { generateGridStyle, clamp } from "./GlobalUtils";
 
 describe("Test global utility functions", (): void => {
 
   test("Test generateGridStyle()", (): void => {
     expect(generateGridStyle(2, 1, 3, 2)).toBe("grid-column: 2 / span 1;grid-row: 3 / span 2;");
     expect(generateGridStyle(undefined, undefined, undefined, undefined)).toBe("grid-column: undefined / span undefined;grid-row: undefined / span undefined;");
   });
+
+  test("Test clamp function where value is below min", (): void => {
+    expect(clamp(-1, 0, 1)).toBe(0);
+  });
+
+  test("Test clamp function where value is above max", (): void => {
+    expect(clamp(2, 0, 1)).toBe(1);
+  });
+
+  test("Test clamp function where value is in range", (): void => {
+    expect(clamp(1, 0, 2)).toBe(1);
+  });
 });

src/client/GlobalUtils.ts

@@ -102,9 +102,26 @@ function insertWordAtCaret (wordToAdd: SymbolEncodingType, symbolSet: SymbolEnco
   return newSymbolSet;
 }
 
+/**
+ * Returns the inputted value constrained to the `min` and `max` values.
+ * The returned value will:
+ *  - `min` if `value` was less than `min`
+ *  - `max` if the `value` was greater than `max`
+ *  - `value` if it fell within the `min` `max` range.
+ *
+ * @param {number} value - The value to evaluate
+ * @param {number} min - The minimum value to be returned
+ * @param {number} max - The maximum value to be returned
+ * @returns {number} - The constrained value
+ */
+function clamp (value: number, min: number, max: number) {
+  return Math.min(Math.max(value, min), max);
+}
+
 export {
   generateGridStyle,
   speak,
   loadPaletteFromJsonFile,
-  insertWordAtCaret
+  insertWordAtCaret,
+  clamp
 };

src/client/index.js

@@ -13,6 +13,7 @@ import { html } from "htm/preact";
 import { initAdaptivePaletteGlobals, adaptivePaletteGlobals } from "./GlobalData";
 import { loadPaletteFromJsonFile, speak } from "./GlobalUtils";
 import { goBackImpl } from "./CommandGoBackCell";
+import { INPUT_AREA_ID } from "./ContentBmwEncoding";
 import "./index.scss";
 
 // Initialize any globals used elsewhere in the code.
@@ -54,15 +55,16 @@ window.addEventListener("keydown", (event) => {
   }
 });
 
+const textInputTypes = [
+  "date", "datetime-local", "email", "month", "number", "password", "search",
+  "tel", "text", "time", "url", "week"
+];
+
 function elementAllowsTextEntry (element) {
-  return (
-    (element.type === "text") || (element.type === "email") ||
-    (element.type === "month") || (element.type === "number") ||
-    (element.type === "password") || (element.type === "search") ||
-    (element.type === "tel") || (element.type === "url") ||
-    (element.type === "week") ||
-    (element instanceof HTMLTextAreaElement) ||
-    (element instanceof HTMLSelectElement) ||
-    (element.getAttribute("role") === "textbox")
+  return element.id !== INPUT_AREA_ID && (
+    textInputTypes.includes(element.type) ||
+    element instanceof HTMLTextAreaElement ||
+    element instanceof HTMLSelectElement ||
+    element.getAttribute("role") === "textbox"
   );
 }