feat: keyboard support for input area

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 optional depenency `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):
@@ -27,6 +30,10 @@ to install dependencies:
 npm ci
 ```
 
+_**Note:** If CMake is not available on the device, the optional dependency `faiss-node` will fail to install but
+will not prevent the application from installing. However, if you wish to use RAG, you'll need to install CMake and
+re-run `npm ci`._
+
 ## Development
 
 ### Start a Server
@@ -90,6 +97,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` is an optional dependency and 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:

package.json

@@ -28,13 +28,15 @@
     "@xenova/transformers": "^2.17.2",
     "bliss-svg-builder": "^0.1.0-alpha.10",
     "express": "^4.19.2",
-    "faiss-node": "^0.5.1",
     "htm": "^3.1.1",
     "ollama": "^0.5.8",
     "preact": "^10.23.2",
     "sass": "^1.77.8 ",
     "serve-static": "^1.15.0"
   },
+  "optionalDependencies": {
+    "faiss-node": "^0.5.1"
+  },
   "devDependencies": {
     "@babel/preset-env": "^7.25.4",
     "@eslint/eslintrc": "^3.1.0",

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,7 +14,7 @@ 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 } from "./GlobalUtils";
 import "./ContentBmwEncoding.scss";
 
 export const INPUT_AREA_ID = "bmw-encoding-area";   // better way?
@@ -66,6 +66,36 @@ function generateMarkupArray (payloadArray: Array<EncodingType>, caretPos: numbe
   });
 }
 
+export function moveCursor (positionChange = 1) {
+  positionChange = Math.round(positionChange);
+
+  // 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);
+}
+
+function handleKeyDown(event: KeyboardEvent) {
+  if (event.key === "ArrowLeft" || event.key === "ArrowDown") {
+    decrementCursor();
+  }
+
+  if (event.key === "ArrowRight" || event.key === "ArrowUp") {
+    incrementCursor();
+  }
+}
+
 export function ContentBmwEncoding (props: ContentBmwEncodingProps): VNode {
   const { id, options } = props;
   const { columnStart, columnSpan, rowStart, rowSpan } = options;
@@ -76,7 +106,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
 };