@applicaster/zapp-react-native-utils 15.0.0-rc.11 → 15.0.0-rc.111

package/appUtils/accessibilityManager/__tests__/utils.test.ts

@@ -0,0 +1,360 @@
+jest.mock("../../../logger", () => {
+  const mockLogError = jest.fn();
+
+  return {
+    createLogger: jest.fn(() => ({
+      log_error: mockLogError,
+    })),
+    __mockLogError: mockLogError, // Export for test access
+  };
+});
+
+import { calculateReadingTime } from "../utils";
+// @ts-ignore - Access the mock
+import { __mockLogError } from "../../../logger";
+
+describe("calculateReadingTime", () => {
+  // Default parameters for reference
+  const DEFAULT_WPM = 140;
+  const DEFAULT_MIN_PAUSE = 500;
+  const DEFAULT_DELAY = 700;
+
+  beforeEach(() => {
+    (__mockLogError as jest.Mock).mockClear();
+  });
+
+  describe("Type Safety", () => {
+    it("should accept and process string input", () => {
+      const result = calculateReadingTime("Hello world");
+      expect(result).toBeGreaterThan(0);
+      expect(__mockLogError).not.toHaveBeenCalled();
+    });
+
+    it("should accept and process number input", () => {
+      const result = calculateReadingTime(12345);
+      expect(result).toBeGreaterThan(0);
+      expect(__mockLogError).not.toHaveBeenCalled();
+    });
+
+    it("should return 0 and log error for null", () => {
+      expect(calculateReadingTime(null as any)).toBe(0);
+
+      expect(__mockLogError).toHaveBeenCalledWith(
+        "Invalid text input for reading time calculation got: null"
+      );
+    });
+
+    it("should return 0 and log error for undefined", () => {
+      expect(calculateReadingTime(undefined as any)).toBe(0);
+
+      expect(__mockLogError).toHaveBeenCalledWith(
+        "Invalid text input for reading time calculation got: undefined"
+      );
+    });
+
+    it("should return 0 and log error for boolean", () => {
+      calculateReadingTime(true as any);
+
+      expect(__mockLogError).toHaveBeenCalledWith(
+        "Invalid text input for reading time calculation got: true"
+      );
+
+      (__mockLogError as jest.Mock).mockClear();
+
+      calculateReadingTime(false as any);
+
+      expect(__mockLogError).toHaveBeenCalledWith(
+        "Invalid text input for reading time calculation got: false"
+      );
+    });
+
+    it("should return 0 and log error for object", () => {
+      const obj = { text: "hello" };
+      calculateReadingTime(obj as any);
+
+      expect(__mockLogError).toHaveBeenCalledWith(
+        `Invalid text input for reading time calculation got: ${obj}`
+      );
+    });
+
+    it("should return 0 and log error for array", () => {
+      const arr = [1, 2, 3];
+      calculateReadingTime(arr as any);
+
+      expect(__mockLogError).toHaveBeenCalledWith(
+        `Invalid text input for reading time calculation got: ${arr}`
+      );
+    });
+
+    it("should return 0 and log error for function", () => {
+      const fn = () => "text";
+      calculateReadingTime(fn as any);
+      expect(__mockLogError).toHaveBeenCalled();
+
+      expect((__mockLogError as jest.Mock).mock.calls[0][0]).toContain(
+        "Invalid text input for reading time calculation got:"
+      );
+    });
+
+    it("should return 0 and log error for symbol", () => {
+      const sym = Symbol("test");
+      calculateReadingTime(sym as any);
+      expect(__mockLogError).toHaveBeenCalled();
+
+      expect((__mockLogError as jest.Mock).mock.calls[0][0]).toBe(
+        `Invalid text input for reading time calculation got: ${String(sym)}`
+      );
+    });
+  });
+
+  describe("Empty and Whitespace Handling", () => {
+    it("should return 0 for empty string", () => {
+      expect(calculateReadingTime("")).toBe(0);
+    });
+
+    it("should return 0 for whitespace-only string", () => {
+      expect(calculateReadingTime("   ")).toBe(0);
+      expect(calculateReadingTime("\n")).toBe(0);
+      expect(calculateReadingTime("\t")).toBe(0);
+      expect(calculateReadingTime("  \n\t  ")).toBe(0);
+    });
+
+    it("should handle leading and trailing whitespace", () => {
+      const withWhitespace = calculateReadingTime("  hello  ");
+      const withoutWhitespace = calculateReadingTime("hello");
+      expect(withWhitespace).toBe(withoutWhitespace);
+    });
+  });
+
+  describe("Number Input Handling", () => {
+    it("should convert number 0 to string and process", () => {
+      const result = calculateReadingTime(0);
+      // "0" is one word
+      expect(result).toBeGreaterThan(0);
+    });
+
+    it("should convert positive numbers to string", () => {
+      const result = calculateReadingTime(123);
+      // "123" is one word
+      expect(result).toBeGreaterThan(0);
+    });
+
+    it("should convert negative numbers to string", () => {
+      const result = calculateReadingTime(-456);
+      // "-456" is processed as words
+      expect(result).toBeGreaterThan(0);
+    });
+
+    it("should convert decimal numbers to string", () => {
+      const result = calculateReadingTime(3.14);
+      // "3.14" is processed as words
+      expect(result).toBeGreaterThan(0);
+    });
+
+    it("should handle NaN", () => {
+      const result = calculateReadingTime(NaN);
+      // NaN is typeof "number", so it converts to "NaN" string
+      expect(result).toBeGreaterThan(0);
+    });
+
+    it("should handle Infinity", () => {
+      const result = calculateReadingTime(Infinity);
+      // Infinity is typeof "number", converts to "Infinity" string
+      expect(result).toBeGreaterThan(0);
+    });
+  });
+
+  describe("Word Counting", () => {
+    it("should count single word", () => {
+      const result = calculateReadingTime("Hello");
+
+      const expectedTime = Math.max(
+        DEFAULT_MIN_PAUSE,
+        (1 / DEFAULT_WPM) * 60 * 1000
+      );
+
+      expect(result).toBe(expectedTime + DEFAULT_DELAY);
+    });
+
+    it("should count multiple words separated by spaces", () => {
+      const result = calculateReadingTime("Hello world test");
+
+      // 3 words
+      const expectedTime = Math.max(
+        DEFAULT_MIN_PAUSE,
+        (3 / DEFAULT_WPM) * 60 * 1000
+      );
+
+      expect(result).toBe(expectedTime + DEFAULT_DELAY);
+    });
+
+    it("should handle words with punctuation", () => {
+      const result = calculateReadingTime("Hello, world! How are you?");
+      // Should split on punctuation and count words
+      expect(result).toBeGreaterThan(DEFAULT_MIN_PAUSE + DEFAULT_DELAY);
+    });
+
+    it("should handle alphanumeric boundaries", () => {
+      const result = calculateReadingTime("test123abc");
+      // Should split on alphanumeric boundaries
+      expect(result).toBeGreaterThan(DEFAULT_MIN_PAUSE + DEFAULT_DELAY);
+    });
+
+    it("should handle long text", () => {
+      const longText = "word ".repeat(200); // 200 words
+      const result = calculateReadingTime(longText);
+      const expectedTime = (200 / DEFAULT_WPM) * 60 * 1000 + DEFAULT_DELAY;
+      expect(result).toBeCloseTo(expectedTime, -1); // Within 10ms
+    });
+  });
+
+  describe("Minimum Pause", () => {
+    it("should return minimum pause + delay for very short text", () => {
+      const result = calculateReadingTime("Hi");
+      // 1 word, calculation would be less than minimum pause
+      expect(result).toBe(DEFAULT_MIN_PAUSE + DEFAULT_DELAY);
+    });
+
+    it("should respect custom minimum pause", () => {
+      const customMinPause = 1000;
+      const result = calculateReadingTime("Hi", DEFAULT_WPM, customMinPause);
+      expect(result).toBeGreaterThanOrEqual(customMinPause);
+    });
+
+    it("should exceed minimum pause for longer text", () => {
+      const longText = "word ".repeat(50); // 50 words
+      const result = calculateReadingTime(longText);
+      const calculatedTime = (50 / DEFAULT_WPM) * 60 * 1000;
+      expect(result).toBe(calculatedTime + DEFAULT_DELAY);
+      expect(result).toBeGreaterThan(DEFAULT_MIN_PAUSE + DEFAULT_DELAY);
+    });
+  });
+
+  describe("Custom Parameters", () => {
+    it("should respect custom words per minute", () => {
+      const text = "word ".repeat(140); // 140 words
+      const fastReading = calculateReadingTime(text, 280); // 2x speed
+      const normalReading = calculateReadingTime(text, 140); // normal speed
+
+      // Faster reading should take less time
+      expect(fastReading).toBeLessThan(normalReading);
+    });
+
+    it("should respect custom announcement delay", () => {
+      const text = "Hello world";
+
+      const shortDelay = calculateReadingTime(
+        text,
+        DEFAULT_WPM,
+        DEFAULT_MIN_PAUSE,
+        100
+      );
+
+      const longDelay = calculateReadingTime(
+        text,
+        DEFAULT_WPM,
+        DEFAULT_MIN_PAUSE,
+        1000
+      );
+
+      expect(longDelay - shortDelay).toBe(900);
+    });
+
+    it("should work with all custom parameters", () => {
+      const result = calculateReadingTime("test", 200, 1000, 500);
+      expect(result).toBeGreaterThanOrEqual(1500); // minimum pause + delay
+    });
+  });
+
+  describe("Real-world Use Cases", () => {
+    it("should handle accessibility announcement text", () => {
+      const announcement = "New message from John Doe";
+      const result = calculateReadingTime(announcement);
+      expect(result).toBeGreaterThan(0);
+      expect(result).toBeLessThan(10000); // Less than 10 seconds
+    });
+
+    it("should handle button labels", () => {
+      const label = "Submit";
+      const result = calculateReadingTime(label);
+      expect(result).toBe(DEFAULT_MIN_PAUSE + DEFAULT_DELAY);
+    });
+
+    it("should handle form error messages", () => {
+      const error = "Please enter a valid email address";
+      const result = calculateReadingTime(error);
+      expect(result).toBeGreaterThan(DEFAULT_MIN_PAUSE);
+    });
+
+    it("should handle article titles", () => {
+      const title = "Breaking News: Major Update Released";
+      const result = calculateReadingTime(title);
+      expect(result).toBeGreaterThan(DEFAULT_MIN_PAUSE + DEFAULT_DELAY);
+    });
+
+    it("should handle notification text", () => {
+      const notification = "You have 3 new messages";
+      const result = calculateReadingTime(notification);
+      expect(result).toBeGreaterThan(0);
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle text with special characters", () => {
+      const result = calculateReadingTime("@#$%^&*()");
+      expect(result).toBeGreaterThanOrEqual(0);
+    });
+
+    it("should handle text with emojis", () => {
+      const result = calculateReadingTime("Hello 👋 World 🌍");
+      expect(result).toBeGreaterThan(0);
+    });
+
+    it("should handle text with newlines", () => {
+      const result = calculateReadingTime("Line 1\nLine 2\nLine 3");
+      expect(result).toBeGreaterThan(0);
+    });
+
+    it("should handle mixed alphanumeric text", () => {
+      const result = calculateReadingTime(
+        "Version 1.2.3 released on 2024-01-01"
+      );
+
+      expect(result).toBeGreaterThan(0);
+    });
+
+    it("should handle very large numbers", () => {
+      const result = calculateReadingTime(Number.MAX_SAFE_INTEGER);
+      expect(result).toBeGreaterThan(0);
+    });
+
+    it("should return consistent results for same input", () => {
+      const text = "Consistent test";
+      const result1 = calculateReadingTime(text);
+      const result2 = calculateReadingTime(text);
+      const result3 = calculateReadingTime(text);
+
+      expect(result1).toBe(result2);
+      expect(result2).toBe(result3);
+    });
+  });
+
+  describe("Performance Characteristics", () => {
+    it("should handle empty input efficiently", () => {
+      const start = Date.now();
+      calculateReadingTime("");
+      const duration = Date.now() - start;
+
+      expect(duration).toBeLessThan(10); // Should be nearly instant
+    });
+
+    it("should handle large text efficiently", () => {
+      const largeText = "word ".repeat(10000);
+      const start = Date.now();
+      calculateReadingTime(largeText);
+      const duration = Date.now() - start;
+
+      expect(duration).toBeLessThan(100); // Should complete in less than 100ms
+    });
+  });
+});

package/appUtils/accessibilityManager/const.ts

@@ -31,6 +31,10 @@ export const BUTTON_ACCESSIBILITY_KEYS = {
       hint: "accessibility_close_mini_hint",
     },
   },
+  back_to_live: {
+    label: "back_to_live_label",
+    hint: "",
+  },
   maximize: {
     label: "accessibility_maximize_label",
     hint: "accessibility_maximize_hint",

package/appUtils/accessibilityManager/hooks.ts

@@ -23,19 +23,6 @@ export const useAccessibilityManager = (
     }
   }, [pluginConfiguration, accessibilityManager]);
 
-  useEffect(() => {
-    const subscription = accessibilityManager.getStateAsObservable().subscribe({
-      next: () => {
-        // TODO: handle accessibility states
-        // screenReaderEnabled: false
-        // reduceMotionEnabled: false
-        // boldTextEnabled: false
-      },
-    });
-
-    return () => subscription.unsubscribe();
-  }, [accessibilityManager]);
-
   return accessibilityManager;
 };
 
@@ -72,3 +59,23 @@ export const useAnnouncementActive = (
 
   return isActive;
 };
+
+export const useAccessibilityState = (
+  pluginConfiguration: Record<string, any> = {}
+) => {
+  const accessibilityManager = useAccessibilityManager(pluginConfiguration);
+
+  const [state, setState] = useState<AccessibilityState>(
+    accessibilityManager.getState()
+  );
+
+  useEffect(() => {
+    const subscription = accessibilityManager
+      .getStateAsObservable()
+      .subscribe(setState);
+
+    return () => subscription.unsubscribe();
+  }, [accessibilityManager]);
+
+  return state;
+};

package/appUtils/accessibilityManager/index.ts

@@ -36,7 +36,20 @@ export class AccessibilityManager {
     false
   );
 
-  private constructor() {}
+  private constructor() {
+    this.ttsManager
+      .getScreenReaderEnabledAsObservable()
+      .subscribe((enabled) => {
+        const state = this.state$.getValue();
+
+        if (state.screenReaderEnabled !== enabled) {
+          this.state$.next({
+            ...state,
+            screenReaderEnabled: enabled,
+          });
+        }
+      });
+  }
 
   public static getInstance(): AccessibilityManager {
     if (!AccessibilityManager._instance) {
@@ -92,8 +105,15 @@ export class AccessibilityManager {
   /**
    * Adds a heading to the queue, headings will be read before the next text
    * Each heading will be read once and removed from the queue
+   * Does nothing if screen reader is not enabled
    */
   public addHeading(heading: string) {
+    const state = this.state$.getValue();
+
+    if (!state.screenReaderEnabled) {
+      return;
+    }
+
     if (!this.pendingFocusId) {
       this.pendingFocusId = Date.now().toString();
     }
@@ -108,6 +128,7 @@ export class AccessibilityManager {
    *
    * Implements a delay mechanism to reduce noise during rapid navigation.
    * Only the most recent announcement will be read after the delay period.
+   * Does nothing if screen reader is not enabled
    */
   public readText({
     text,
@@ -116,6 +137,12 @@ export class AccessibilityManager {
     text: string;
     keyOfLocalizedText?: string;
   }) {
+    const state = this.state$.getValue();
+
+    if (!state.screenReaderEnabled) {
+      return;
+    }
+
     let textToRead = text;
 
     if (keyOfLocalizedText) {

package/appUtils/accessibilityManager/utils.ts

@@ -1,24 +1,75 @@
+import { createLogger } from "../../logger";
+
+const { log_error } = createLogger({
+  category: "AccessibilityManager",
+  subsystem: "AppUtils",
+});
+
 /**
  * Calculates the reading time for a given text based on word count
- * @param text - The text to calculate the reading time for
- * @param wordsPerMinute - Words per minute reading speed (default: 160)
+ * @param text - The text to calculate the reading time for (string or number)
+ * @param wordsPerMinute - Words per minute reading speed (default: 140)
  * @param minimumPause - Minimum pause time in milliseconds (default: 500)
  * @param announcementDelay - Additional delay for announcement in milliseconds (default: 700)
  * @returns The reading time in milliseconds
  */
 export function calculateReadingTime(
-  text: string,
+  text: string | number,
   wordsPerMinute: number = 140,
   minimumPause: number = 500,
   announcementDelay: number = 700
 ): number {
-  const words = text
-    .trim()
+  if (typeof text !== "string" && typeof text !== "number") {
+    log_error(
+      `Invalid text input for reading time calculation got: ${
+        typeof text === "symbol" ? String(text) : text
+      }`
+    );
+
+    return 0;
+  }
+
+  const trimmed = typeof text === "number" ? String(text) : text.trim();
+
+  if (!trimmed) {
+    return 0;
+  }
+
+  const words = trimmed
     .split(/(?<=\d)(?=[a-zA-Z])|(?<=[a-zA-Z])(?=\d)|[^\w\s]+|\s+/)
     .filter(Boolean).length;
 
-  return (
-    Math.max(minimumPause, (words / wordsPerMinute) * 60 * 1000) +
-    announcementDelay
+  // Count spaces - multiple consecutive spaces add extra pause time
+  const spaceMatches: string[] = trimmed.match(/\s+/g) || [];
+
+  const totalSpaces = spaceMatches.reduce(
+    (sum: number, match: string) => sum + match.length,
+    0
   );
+
+  const extraSpaces = Math.max(0, totalSpaces - (words - 1)); // words-1 is normal spacing
+
+  // Heuristic: punctuation increases TTS duration beyond word-based WPM.
+  // Commas typically introduce short pauses, sentence terminators longer ones.
+  const commaCount = (trimmed.match(/,/g) || []).length;
+  const semicolonCount = (trimmed.match(/;/g) || []).length;
+  const colonCount = (trimmed.match(/:/g) || []).length;
+  const dashCount = (trimmed.match(/\u2013|\u2014|-/g) || []).length; // – — -
+  const sentenceEndCount = (trimmed.match(/[.!?](?!\d)/g) || []).length;
+
+  const commaPauseMs = 220; // short prosody pause for ","
+  const midPauseMs = 260; // for ";", ":", dashes
+  const sentenceEndPauseMs = 420; // for ".", "!", "?"
+  const extraSpacePauseMs = 50; // per extra space beyond normal spacing
+
+  const punctuationPause =
+    commaCount * commaPauseMs +
+    (semicolonCount + colonCount + dashCount) * midPauseMs +
+    sentenceEndCount * sentenceEndPauseMs +
+    extraSpaces * extraSpacePauseMs;
+
+  const baseByWordsMs = (words / wordsPerMinute) * 60 * 1000;
+  const estimatedMs = Math.max(minimumPause, baseByWordsMs + punctuationPause);
+
+  return estimatedMs + announcementDelay;
 }

package/appUtils/contextKeysManager/__tests__/getKeys/failure.test.ts

@@ -1,7 +1,12 @@
+import { NativeModules } from "react-native";
 import { ContextKeysManager } from "../..";
 
 describe("Context Keys Manager - getKeys", () => {
-  it("returns null if all keys are invalid", async () => {
+  beforeEach(() => {
+    delete NativeModules.ContextResolverBridge;
+  });
+
+  it("returns null if all keys are invalid 1", async () => {
     // setup
     const keys = [null];
 
@@ -24,7 +29,7 @@ describe("Context Keys Manager - getKeys", () => {
     expect(getKey.mock.calls).toEqual([[null]]);
   });
 
-  it("returns null if all keys are invalid", async () => {
+  it("returns null if all keys are invalid 2", async () => {
     // setup
     const keys = [null, undefined];
 

package/appUtils/contextKeysManager/__tests__/getKeys/success.test.ts

@@ -1,6 +1,11 @@
+import { NativeModules } from "react-native";
 import { ContextKeysManager } from "../..";
 
 describe("Context Keys Manager - getKeys", () => {
+  beforeEach(() => {
+    delete NativeModules.ContextResolverBridge;
+  });
+
   it("returns value if found by getKey", async () => {
     // setup
     const keys = ["namespace.key"];
@@ -165,4 +170,47 @@ describe("Context Keys Manager - getKeys", () => {
     expect(getKey).toHaveBeenCalledTimes(2);
     expect(getKey.mock.calls).toEqual([[keys[0]], [keys[1]]]);
   });
+
+  it("returns values from native bridge when available", async () => {
+    // setup
+    const keys = ["namespace.key1", "namespace.key2"];
+
+    const contextObj = [
+      { key: keys[0], required: true },
+      { key: keys[1], required: false },
+    ];
+
+    const resolved = {
+      [keys[0]]: "value1",
+      [keys[1]]: "value2",
+    };
+
+    const reactNative = require("react-native");
+
+    const bridgeMock = {
+      resolveContextKeys: jest.fn().mockResolvedValue(resolved),
+    };
+
+    reactNative.__setContextResolverBridgeMock(bridgeMock);
+
+    const contextManager = new ContextKeysManager({});
+    const getKey = jest.spyOn(contextManager, "getKey");
+
+    // run
+    const result = await contextManager.getKeys(keys, contextObj);
+
+    // verify
+    const map = new Map();
+    map.set(keys[0], "value1");
+    map.set(keys[1], "value2");
+
+    expect(result).toEqual(map);
+
+    expect(bridgeMock.resolveContextKeys).toHaveBeenCalledWith({
+      [keys[0]]: true,
+      [keys[1]]: false,
+    });
+
+    expect(getKey).not.toHaveBeenCalled();
+  });
 });