impr(caret): handle mixed language direction (@byseif21) (monkeytypegame#6695)

byseif21 · Miodec · web-flow · commit 01d8363e19e4 · 2025-09-04T12:36:59.000+02:00
### Description enhances the caret positioning logic to support mixed language directions (LTR and RTL) within words. It introduces a new hasRTLCharacters utility function to detect RTL characters in individual words, allowing the caret to adjust dynamically based on word-specific direction rather than relying solely on the language's default direction #### notes: * tested no affect to the normal single direction. * no tap mode handle included * related monkeytypegame#6694 monkeytypegame#6666 --------- Co-authored-by: Jack <jack@monkeytype.com>
diff --git a/frontend/__tests__/utils/strings.spec.ts b/frontend/__tests__/utils/strings.spec.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
 import * as Strings from "../../src/ts/utils/strings";
 
 describe("string utils", () => {
@@ -66,4 +66,239 @@ describe("string utils", () => {
       }
     );
   });
+
+  describe("hasRTLCharacters", () => {
+    it.each([
+      // LTR characters should return false
+      [false, "hello", "basic Latin text"],
+      [false, "world123", "Latin text with numbers"],
+      [false, "test!", "Latin text with punctuation"],
+      [false, "ABC", "uppercase Latin text"],
+      [false, "", "empty string"],
+      [false, "123", "numbers only"],
+      [false, "!@#$%", "punctuation and symbols only"],
+      [false, "   ", "whitespace only"],
+
+      // Common LTR scripts
+      [false, "Здравствуй", "Cyrillic text"],
+      [false, "Bonjour", "Latin with accents"],
+      [false, "Καλημέρα", "Greek text"],
+      [false, "こんにちは", "Japanese Hiragana"],
+      [false, "你好", "Chinese characters"],
+      [false, "안녕하세요", "Korean text"],
+
+      // RTL characters should return true - Arabic
+      [true, "مرحبا", "Arabic text"],
+      [true, "السلام", "Arabic phrase"],
+      [true, "العربية", "Arabic word"],
+      [true, "٠١٢٣٤٥٦٧٨٩", "Arabic-Indic digits"],
+
+      // RTL characters should return true - Hebrew
+      [true, "שלום", "Hebrew text"],
+      [true, "עברית", "Hebrew word"],
+      [true, "ברוך", "Hebrew name"],
+
+      // RTL characters should return true - Persian/Farsi
+      [true, "سلام", "Persian text"],
+      [true, "فارسی", "Persian word"],
+
+      // Mixed content (should return true if ANY RTL characters are present)
+      [true, "hello مرحبا", "mixed LTR and Arabic"],
+      [true, "123 שלום", "numbers and Hebrew"],
+      [true, "test سلام!", "Latin, Persian, and punctuation"],
+      [true, "مرحبا123", "Arabic with numbers"],
+      [true, "hello؟", "Latin with Arabic punctuation"],
+
+      // Edge cases with various Unicode ranges
+      [false, "𝕳𝖊𝖑𝖑𝖔", "mathematical bold text (LTR)"],
+      [false, "🌍🌎🌏", "emoji"],
+    ] as const)(
+      "should return %s for word '%s' (%s)",
+      (expected: boolean, word: string, _description: string) => {
+        expect(Strings.__testing.hasRTLCharacters(word)).toBe(expected);
+      }
+    );
+  });
+
+  describe("getWordDirection", () => {
+    beforeEach(() => {
+      Strings.clearWordDirectionCache();
+    });
+
+    it.each([
+      // Basic functionality - should use hasRTLCharacters result when word has core content
+      [false, "hello", false, "LTR word in LTR language"],
+      [
+        false,
+        "hello",
+        true,
+        "LTR word in RTL language (word direction overrides language)",
+      ],
+      [
+        true,
+        "مرحبا",
+        false,
+        "RTL word in LTR language (word direction overrides language)",
+      ],
+      [true, "مرحبا", true, "RTL word in RTL language"],
+
+      // Punctuation stripping behavior
+      [false, "hello!", false, "LTR word with trailing punctuation"],
+      [false, "!hello", false, "LTR word with leading punctuation"],
+      [false, "!hello!", false, "LTR word with surrounding punctuation"],
+      [true, "مرحبا؟", false, "RTL word with trailing punctuation"],
+      [true, "؟مرحبا", false, "RTL word with leading punctuation"],
+      [true, "؟مرحبا؟", false, "RTL word with surrounding punctuation"],
+
+      // Fallback to language direction for empty/neutral content
+      [false, "", false, "empty string falls back to LTR language"],
+      [true, "", true, "empty string falls back to RTL language"],
+      [false, "!!!", false, "punctuation only falls back to LTR language"],
+      [true, "!!!", true, "punctuation only falls back to RTL language"],
+      [false, "   ", false, "whitespace only falls back to LTR language"],
+      [true, "   ", true, "whitespace only falls back to RTL language"],
+
+      // Numbers behavior (numbers are neutral, follow hasRTLCharacters detection)
+      [false, "123", false, "regular digits are not RTL"],
+      [false, "123", true, "regular digits are not RTL regardless of language"],
+      [true, "١٢٣", false, "Arabic-Indic digits are detected as RTL"],
+      [true, "١٢٣", true, "Arabic-Indic digits are detected as RTL"],
+    ] as const)(
+      "should return %s for word '%s' with languageRTL=%s (%s)",
+      (
+        expected: boolean,
+        word: string,
+        languageRTL: boolean,
+        _description: string
+      ) => {
+        expect(Strings.getWordDirection(word, languageRTL)).toBe(expected);
+      }
+    );
+
+    it("should return languageRTL for undefined word", () => {
+      expect(Strings.getWordDirection(undefined, false)).toBe(false);
+      expect(Strings.getWordDirection(undefined, true)).toBe(true);
+    });
+
+    describe("caching", () => {
+      let mapGetSpy: ReturnType<typeof vi.spyOn>;
+      let mapSetSpy: ReturnType<typeof vi.spyOn>;
+      let mapClearSpy: ReturnType<typeof vi.spyOn>;
+
+      beforeEach(() => {
+        mapGetSpy = vi.spyOn(Map.prototype, "get");
+        mapSetSpy = vi.spyOn(Map.prototype, "set");
+        mapClearSpy = vi.spyOn(Map.prototype, "clear");
+      });
+
+      afterEach(() => {
+        mapGetSpy.mockRestore();
+        mapSetSpy.mockRestore();
+        mapClearSpy.mockRestore();
+      });
+
+      it("should use cache for repeated calls", () => {
+        // First call should cache the result (cache miss)
+        const result1 = Strings.getWordDirection("hello", false);
+        expect(result1).toBe(false);
+        expect(mapSetSpy).toHaveBeenCalledWith("hello", false);
+
+        // Reset spies to check second call
+        mapGetSpy.mockClear();
+        mapSetSpy.mockClear();
+
+        // Second call should use cache (cache hit)
+        const result2 = Strings.getWordDirection("hello", false);
+        expect(result2).toBe(false);
+        expect(mapGetSpy).toHaveBeenCalledWith("hello");
+        expect(mapSetSpy).not.toHaveBeenCalled(); // Should not set again
+
+        // Cache should work regardless of language direction for same word
+        mapGetSpy.mockClear();
+        mapSetSpy.mockClear();
+
+        const result3 = Strings.getWordDirection("hello", true);
+        expect(result3).toBe(false); // Still false because "hello" is LTR regardless of language
+        expect(mapGetSpy).toHaveBeenCalledWith("hello");
+        expect(mapSetSpy).not.toHaveBeenCalled(); // Should not set again
+      });
+
+      it("should cache based on core word without punctuation", () => {
+        // First call should cache the result for core "hello"
+        const result1 = Strings.getWordDirection("hello", false);
+        expect(result1).toBe(false);
+        expect(mapSetSpy).toHaveBeenCalledWith("hello", false);
+
+        mapGetSpy.mockClear();
+        mapSetSpy.mockClear();
+
+        // These should all use the same cache entry since they have the same core
+        const result2 = Strings.getWordDirection("hello!", false);
+        expect(result2).toBe(false);
+        expect(mapGetSpy).toHaveBeenCalledWith("hello");
+        expect(mapSetSpy).not.toHaveBeenCalled();
+
+        mapGetSpy.mockClear();
+        mapSetSpy.mockClear();
+
+        const result3 = Strings.getWordDirection("!hello", false);
+        expect(result3).toBe(false);
+        expect(mapGetSpy).toHaveBeenCalledWith("hello");
+        expect(mapSetSpy).not.toHaveBeenCalled();
+
+        mapGetSpy.mockClear();
+        mapSetSpy.mockClear();
+
+        const result4 = Strings.getWordDirection("!hello!", false);
+        expect(result4).toBe(false);
+        expect(mapGetSpy).toHaveBeenCalledWith("hello");
+        expect(mapSetSpy).not.toHaveBeenCalled();
+      });
+
+      it("should handle cache clearing", () => {
+        // Cache a result
+        Strings.getWordDirection("test", false);
+        expect(mapSetSpy).toHaveBeenCalledWith("test", false);
+
+        // Clear cache
+        Strings.clearWordDirectionCache();
+        expect(mapClearSpy).toHaveBeenCalled();
+
+        mapGetSpy.mockClear();
+        mapSetSpy.mockClear();
+        mapClearSpy.mockClear();
+
+        // Should work normally after cache clear (cache miss again)
+        const result = Strings.getWordDirection("test", false);
+        expect(result).toBe(false);
+        expect(mapSetSpy).toHaveBeenCalledWith("test", false);
+      });
+
+      it("should demonstrate cache miss vs cache hit behavior", () => {
+        // Test cache miss - first time seeing this word
+        const result1 = Strings.getWordDirection("unique", false);
+        expect(result1).toBe(false);
+        expect(mapGetSpy).toHaveBeenCalledWith("unique");
+        expect(mapSetSpy).toHaveBeenCalledWith("unique", false);
+
+        mapGetSpy.mockClear();
+        mapSetSpy.mockClear();
+
+        // Test cache hit - same word again
+        const result2 = Strings.getWordDirection("unique", false);
+        expect(result2).toBe(false);
+        expect(mapGetSpy).toHaveBeenCalledWith("unique");
+        expect(mapSetSpy).not.toHaveBeenCalled(); // No cache set on hit
+
+        mapGetSpy.mockClear();
+        mapSetSpy.mockClear();
+
+        // Test cache miss - different word
+        const result3 = Strings.getWordDirection("different", false);
+        expect(result3).toBe(false);
+        expect(mapGetSpy).toHaveBeenCalledWith("different");
+        expect(mapSetSpy).toHaveBeenCalledWith("different", false);
+      });
+    });
+  });
 });
diff --git a/frontend/src/ts/test/caret.ts b/frontend/src/ts/test/caret.ts
@@ -6,7 +6,7 @@ import * as TestState from "../test/test-state";
 import * as TestWords from "./test-words";
 import { prefersReducedMotion } from "../utils/misc";
 import { convertRemToPixels } from "../utils/numbers";
-import { splitIntoCharacters } from "../utils/strings";
+import { splitIntoCharacters, getWordDirection } from "../utils/strings";
 import { safeNumber } from "@monkeytype/util/numbers";
 import { subscribe } from "../observables/config-event";
 
@@ -59,19 +59,26 @@ function getTargetPositionLeft(
   currentWordNodeList: NodeListOf<HTMLElement>,
   fullWidthCaretWidth: number,
   wordLen: number,
-  inputLen: number
+  inputLen: number,
+  currentWord?: string
 ): number {
   const invisibleExtraLetters = Config.blindMode || Config.hideExtraLetters;
   let result = 0;
 
+  // use word-specific direction if available and different from language direction
+  const isWordRightToLeft = getWordDirection(
+    currentWord,
+    isLanguageRightToLeft
+  );
+
   if (Config.tapeMode === "off") {
     let positionOffsetToWord = 0;
 
     const currentLetter = currentWordNodeList[inputLen];
     const lastWordLetter = currentWordNodeList[wordLen - 1];
     const lastInputLetter = currentWordNodeList[inputLen - 1];
 
-    if (isLanguageRightToLeft) {
+    if (isWordRightToLeft) {
       if (inputLen <= wordLen && currentLetter) {
         // at word beginning in zen mode both lengths are 0, but currentLetter is defined "_"
         positionOffsetToWord =
@@ -104,13 +111,13 @@ function getTargetPositionLeft(
       $(document.querySelector("#wordsWrapper") as HTMLElement).width() ?? 0;
     const tapeMargin =
       wordsWrapperWidth *
-      (isLanguageRightToLeft
+      (isWordRightToLeft
         ? 1 - Config.tapeMargin / 100
         : Config.tapeMargin / 100);
 
     result =
       tapeMargin -
-      (fullWidthCaret && isLanguageRightToLeft ? fullWidthCaretWidth : 0);
+      (fullWidthCaret && isWordRightToLeft ? fullWidthCaretWidth : 0);
 
     if (Config.tapeMode === "word" && inputLen > 0) {
       let currentWordWidth = 0;
@@ -125,7 +132,7 @@ function getTargetPositionLeft(
       // if current letter has zero width move the caret to previous positive width letter
       if ($(currentWordNodeList[inputLen] as Element).outerWidth(true) === 0)
         currentWordWidth -= lastPositiveLetterWidth;
-      if (isLanguageRightToLeft) currentWordWidth *= -1;
+      if (isWordRightToLeft) currentWordWidth *= -1;
       result += currentWordWidth;
     }
   }
@@ -211,14 +218,21 @@ export async function updatePosition(noAnim = false): Promise<void> {
     currentWordNodeList
   );
 
+  // in zen mode, use the input content to determine word direction
+  const currentWordForDirection =
+    Config.mode === "zen"
+      ? TestInput.input.current
+      : TestWords.words.getCurrent();
+
   const letterPosLeft = getTargetPositionLeft(
     fullWidthCaret,
     isLanguageRightToLeft,
     activeWordEl,
     currentWordNodeList,
     letterWidth,
     wordLen,
-    inputLen
+    inputLen,
+    currentWordForDirection
   );
   const newLeft = letterPosLeft - (fullWidthCaret ? 0 : caretWidth / 2);
 
diff --git a/frontend/src/ts/test/pace-caret.ts b/frontend/src/ts/test/pace-caret.ts
@@ -9,6 +9,7 @@ import * as TestState from "./test-state";
 import * as ConfigEvent from "../observables/config-event";
 import { convertRemToPixels } from "../utils/numbers";
 import { getActiveFunboxes } from "./funbox/list";
+import { getWordDirection } from "../utils/strings";
 
 type Settings = {
   wpm: number;
@@ -53,12 +54,19 @@ async function resetCaretPosition(): Promise<void> {
   const currentLanguage = await JSONData.getCurrentLanguage(Config.language);
   const isLanguageRightToLeft = currentLanguage.rightToLeft;
 
+  const currentWord = TestWords.words.get(settings?.currentWordIndex ?? 0);
+
+  const isWordRightToLeft = getWordDirection(
+    currentWord,
+    isLanguageRightToLeft ?? false
+  );
+
   caret.stop(true, true).animate(
     {
       top: firstLetter.offsetTop - firstLetterHeight / 4,
       left:
         firstLetter.offsetLeft +
-        (isLanguageRightToLeft ? firstLetter.offsetWidth : 0),
+        (isWordRightToLeft ? firstLetter.offsetWidth : 0),
     },
     0,
     "linear"
@@ -231,6 +239,12 @@ export async function update(expectedStepEnd: number): Promise<void> {
       );
       const isLanguageRightToLeft = currentLanguage.rightToLeft;
 
+      const currentWord = TestWords.words.get(settings.currentWordIndex);
+
+      const isWordRightToLeft = getWordDirection(
+        currentWord,
+        isLanguageRightToLeft ?? false
+      );
       newTop =
         word.offsetTop +
         currentLetter.offsetTop -
@@ -240,13 +254,13 @@ export async function update(expectedStepEnd: number): Promise<void> {
           word.offsetLeft +
           currentLetter.offsetLeft -
           caretWidth / 2 +
-          (isLanguageRightToLeft ? currentLetterWidth : 0);
+          (isWordRightToLeft ? currentLetterWidth : 0);
       } else {
         newLeft =
           word.offsetLeft +
           currentLetter.offsetLeft -
           caretWidth / 2 +
-          (isLanguageRightToLeft ? 0 : currentLetterWidth);
+          (isWordRightToLeft ? 0 : currentLetterWidth);
       }
       caret.removeClass("hidden");
     } catch (e) {
diff --git a/frontend/src/ts/test/test-logic.ts b/frontend/src/ts/test/test-logic.ts
@@ -162,6 +162,8 @@ export function restart(options = {} as RestartOptions): void {
   };
 
   options = { ...defaultOptions, ...options };
+  Strings.clearWordDirectionCache();
+
   const animationTime = options.noAnim ? 0 : Misc.applyReducedMotion(125);
 
   const noQuit = isFunboxActive("no_quit");
diff --git a/frontend/src/ts/utils/strings.ts b/frontend/src/ts/utils/strings.ts
