@applicaster/zapp-react-native-utils 13.0.5 → 13.0.6-alpha.1043196035

package/appUtils/__tests__/accessibilityManager.test.ts

@@ -0,0 +1,114 @@
+import { AccessibilityManager } from "@applicaster/zapp-react-native-utils/appUtils/accessibilityManager";
+
+const mockReadText = jest.fn();
+
+jest.mock(
+  "@applicaster/zapp-react-native-utils/appUtils/platform/platformUtils",
+  () => ({
+    TTSManager: {
+      getInstance: jest.fn(() => ({
+        readText: mockReadText,
+      })),
+    },
+  })
+);
+
+describe("AccessibilityManager", () => {
+  let accessibilityManager: AccessibilityManager;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    jest.useFakeTimers();
+
+    (AccessibilityManager as any)._instance = null;
+
+    accessibilityManager = AccessibilityManager.getInstance();
+
+    accessibilityManager._resetTTSManager();
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  describe("announcement delay functionality", () => {
+    it("should delay announcements by the configured delay time", () => {
+      const testText = "Test announcement";
+
+      accessibilityManager.readText({ text: testText });
+
+      expect(mockReadText).not.toHaveBeenCalled();
+
+      jest.advanceTimersByTime(150);
+      expect(mockReadText).not.toHaveBeenCalled();
+
+      jest.advanceTimersByTime(50);
+      expect(mockReadText).toHaveBeenCalledWith(testText, undefined);
+    });
+
+    it("should cancel previous announcements when a new one is requested", () => {
+      const firstText = "First announcement";
+      const secondText = "Second announcement";
+
+      accessibilityManager.readText({ text: firstText });
+
+      jest.advanceTimersByTime(150);
+
+      accessibilityManager.readText({ text: secondText });
+
+      jest.advanceTimersByTime(200);
+
+      expect(mockReadText).toHaveBeenCalledTimes(1);
+      expect(mockReadText).toHaveBeenCalledWith(secondText, undefined);
+    });
+
+    it("should allow configuring the announcement delay", () => {
+      const customDelay = 300;
+      accessibilityManager.setAnnouncementDelay(customDelay);
+
+      expect(accessibilityManager.getAnnouncementDelay()).toBe(customDelay);
+
+      const testText = "Test announcement";
+      accessibilityManager.readText({ text: testText });
+
+      expect(mockReadText).not.toHaveBeenCalled();
+
+      jest.advanceTimersByTime(250);
+      expect(mockReadText).not.toHaveBeenCalled();
+
+      jest.advanceTimersByTime(50);
+      expect(mockReadText).toHaveBeenCalledWith(testText, undefined);
+    });
+
+    it("should cancel pending announcements when cancelPendingAnnouncement is called", () => {
+      const testText = "Test announcement";
+
+      accessibilityManager.readText({ text: testText });
+
+      accessibilityManager.cancelPendingAnnouncement();
+
+      jest.advanceTimersByTime(250);
+
+      expect(mockReadText).not.toHaveBeenCalled();
+    });
+
+    it("should handle localized text with delay", () => {
+      const localizations = {
+        test_key: "Localized text",
+      };
+
+      accessibilityManager.updateLocalizations(localizations);
+
+      accessibilityManager.readText({
+        text: "fallback",
+        keyOfLocalizedText: "test_key",
+      });
+
+      expect(mockReadText).not.toHaveBeenCalled();
+
+      jest.advanceTimersByTime(200);
+
+      expect(mockReadText).toHaveBeenCalledWith("Localized text", undefined);
+    });
+  });
+});

package/appUtils/accessibilityManager/README.md

@@ -0,0 +1,76 @@
+# Accessibility Manager - Announcement Delay Feature
+
+## Overview
+
+The Accessibility Manager now includes a delay mechanism to reduce noise during rapid navigation. This feature ensures that only elements the user actually lands on are announced, preventing excessive screen reader announcements during fast navigation.
+
+## Implementation Details
+
+### Key Features
+
+1. **Configurable Delay**: Default delay of 200ms (configurable via `setAnnouncementDelay()`)
+2. **Cancellation of Previous Announcements**: New announcements cancel pending ones
+3. **Manual Cancellation**: Ability to cancel pending announcements programmatically
+
+### New Methods
+
+#### `setAnnouncementDelay(delay: number)`
+Sets the announcement delay in milliseconds. The delay must be non-negative.
+
+```typescript
+const accessibilityManager = AccessibilityManager.getInstance();
+accessibilityManager.setAnnouncementDelay(200); // Set to 200ms
+```
+
+#### `getAnnouncementDelay(): number`
+Returns the current announcement delay setting.
+
+```typescript
+const currentDelay = accessibilityManager.getAnnouncementDelay();
+console.log(`Current delay: ${currentDelay}ms`);
+```
+
+#### `cancelPendingAnnouncement()`
+Cancels any pending announcement that hasn't been executed yet. Useful for clearing announcements when navigation is interrupted.
+
+```typescript
+// Cancel any pending announcement
+accessibilityManager.cancelPendingAnnouncement();
+```
+
+### How It Works
+
+1. When `readText()` is called, instead of immediately announcing the text, it schedules the announcement after the configured delay
+2. If `readText()` is called again before the delay expires, the previous announcement is cancelled and a new one is scheduled
+3. Only the most recent announcement will be executed after the delay period
+4. The delay applies to both regular text and localized text announcements
+
+### Example Usage
+
+```typescript
+const accessibilityManager = AccessibilityManager.getInstance();
+
+// Set a custom delay (optional)
+accessibilityManager.setAnnouncementDelay(100);
+
+// Rapid navigation scenario
+accessibilityManager.readText({ text: "Home" }); // Cancelled by next call
+accessibilityManager.readText({ text: "Settings" }); // Cancelled by next call
+accessibilityManager.readText({ text: "Profile" }); // This will be announced after delay
+
+// Only "Profile" will be announced, reducing noise
+```
+
+### Benefits
+
+- **Reduced Noise**: Prevents excessive announcements during rapid navigation
+- **Better UX**: Users only hear announcements for elements they actually focus on
+- **Configurable**: Developers can adjust the delay based on their app's needs
+- **Backward Compatible**: Existing code continues to work without changes
+
+### Default Behavior
+
+- Default delay: 200ms
+- Delay can be set to 0 to disable the feature (immediate announcements)
+- Works with both regular text and localized text keys
+- Maintains compatibility with heading queue functionality

package/appUtils/accessibilityManager/index.ts

@@ -8,8 +8,10 @@ import _ from "lodash";
 export class AccessibilityManager {
   private static _instance: AccessibilityManager | null = null;
   private headingTimeout: NodeJS.Timeout | null = null;
+  private announcementDelayTimeout: NodeJS.Timeout | null = null;
   private WORDS_PER_MINUTE = 160;
   private MINIMUM_PAUSE = 500;
+  private ANNOUNCEMENT_DELAY = 200; // 200ms delay to reduce noise during rapid navigation
   private state$ = new BehaviorSubject<AccessibilityState>({
     screenReaderEnabled: false,
     reduceMotionEnabled: false,
@@ -82,13 +84,18 @@ export class AccessibilityManager {
   /**
    * text you want to be read, if you want to use localized text pass keyOfLocalizedText instead
    * keyOfLocalizedText is the key to the localized text
+   *
+   * Implements a delay mechanism to reduce noise during rapid navigation.
+   * Only the most recent announcement will be read after the delay period.
    */
   public readText({
     text,
     keyOfLocalizedText,
+    options,
   }: {
     text: string;
     keyOfLocalizedText?: string;
+    options?: any;
   }) {
     let textToRead = text;
 
@@ -112,9 +119,28 @@ export class AccessibilityManager {
       textToRead = localizedMessage;
     }
 
+    // Clear any existing announcement delay timeout to cancel previous announcements
+    if (this.announcementDelayTimeout) {
+      clearTimeout(this.announcementDelayTimeout);
+    }
+
+    // Set a new delay timeout for this announcement
+    this.announcementDelayTimeout = setTimeout(() => {
+      this.executeAnnouncement(textToRead, keyOfLocalizedText, options);
+    }, this.ANNOUNCEMENT_DELAY);
+  }
+
+  /**
+   * Internal method to execute the actual announcement after the delay
+   */
+  private executeAnnouncement(
+    textToRead: string,
+    keyOfLocalizedText?: string,
+    options?: any
+  ) {
     if (this.headingQueue.length > 0) {
       const heading = this.headingQueue.shift()!;
-      this.ttsManager?.readText(heading);
+      this.ttsManager?.readText(heading, options);
 
       if (this.headingTimeout) {
         clearTimeout(this.headingTimeout);
@@ -123,10 +149,10 @@ export class AccessibilityManager {
       const pauseTime = this.calculateReadingTime(heading);
 
       this.headingTimeout = setTimeout(() => {
-        this.ttsManager?.readText(textToRead);
+        this.ttsManager?.readText(textToRead, options);
       }, pauseTime);
     } else {
-      this.ttsManager?.readText(textToRead);
+      this.ttsManager?.readText(textToRead, options);
     }
 
     this.announcements$.next({
@@ -143,12 +169,15 @@ export class AccessibilityManager {
 
     if (!buttonConfig) {
       return {
+        accessible: true,
         accessibilityLabel: buttonName,
         accessibilityHint: `Press button to perform action on ${buttonName}`,
         "aria-label": buttonName,
         "aria-description": `Press button to perform action on ${buttonName}`,
         accessibilityRole: "button" as AccessibilityRole,
         "aria-role": "button",
+        role: "button",
+        tabindex: 0,
       };
     }
 
@@ -162,23 +191,52 @@ export class AccessibilityManager {
       `Press button to perform action on ${buttonName}`;
 
     return {
+      accessible: true,
       accessibilityLabel: label,
       accessibilityHint: hint,
       "aria-label": label,
       "aria-description": hint,
       accessibilityRole: "button" as AccessibilityRole,
       "aria-role": "button",
+      role: "button",
+      tabindex: 0,
     };
   }
 
   public getInputAccessibilityProps(inputName: string): AccessibilityProps {
     return {
+      accessible: true,
       accessibilityLabel: inputName,
       accessibilityHint: `Enter text into ${inputName}`,
       "aria-label": inputName,
       "aria-description": `Enter text into ${inputName}`,
-      accessibilityRole: "textbox" as AccessibilityRole,
-      "aria-role": "textbox",
+      accessibilityRole: "text" as AccessibilityRole,
+      "aria-role": "text",
+      role: "text",
+      tabindex: 0,
+    };
+  }
+
+  /**
+   * Extracts accessibility props from component props and returns them as HTML attributes
+   * @param props - Component props containing accessibility properties
+   * @returns Object with accessibility HTML attributes
+   */
+  public getWebAccessibilityProps(props: any): AccessibilityProps {
+    const {
+      "aria-label": ariaLabel,
+      "aria-description": ariaDescription,
+      "aria-role": ariaRole,
+      role,
+      tabindex,
+    } = props;
+
+    return {
+      "aria-label": ariaLabel,
+      "aria-description": ariaDescription,
+      "aria-role": ariaRole,
+      role: role || ariaRole,
+      tabindex,
     };
   }
 
@@ -196,4 +254,39 @@ export class AccessibilityManager {
 
     return this.localizations[key];
   }
+
+  /**
+   * Sets the announcement delay to reduce noise during rapid navigation
+   * @param delay - Delay in milliseconds (default: 150ms)
+   */
+  public setAnnouncementDelay(delay: number) {
+    this.ANNOUNCEMENT_DELAY = Math.max(0, delay);
+  }
+
+  /**
+   * Gets the current announcement delay setting
+   * @returns Current delay in milliseconds
+   */
+  public getAnnouncementDelay(): number {
+    return this.ANNOUNCEMENT_DELAY;
+  }
+
+  /**
+   * Cancels any pending announcement that hasn't been executed yet
+   * Useful for clearing announcements when navigation is interrupted
+   */
+  public cancelPendingAnnouncement() {
+    if (this.announcementDelayTimeout) {
+      clearTimeout(this.announcementDelayTimeout);
+      this.announcementDelayTimeout = null;
+    }
+  }
+
+  /**
+   * Resets the TTSManager instance (mainly for testing purposes)
+   * @private
+   */
+  public _resetTTSManager() {
+    this.ttsManager = TTSManager.getInstance();
+  }
 }

package/appUtils/platform/platformUtils.ts

@@ -211,9 +211,14 @@ export class TTSManager {
     return this.ttsState$.asObservable();
   }
 
-  readText(text: string) {
+  readText(text: string, options: any = { skipAnnouncement: true }) {
     if (isSamsungPlatform() && window.speechSynthesis) {
       const utterance = new SpeechSynthesisUtterance(text);
+
+      if (options?.skipAnnouncement) {
+        window.speechSynthesis.cancel(); // Cancel previous speech before speaking new text
+      }
+
       window.speechSynthesis.speak(utterance);
     }
 
@@ -233,6 +238,7 @@ export class TTSManager {
           },
           parameters: {
             text,
+            clear: options?.skipAnnouncement, // Clear any pending speech before speaking new text
           },
         });
       } catch (error) {

package/index.d.ts

@@ -139,10 +139,13 @@ declare type AccessibilityState = {
 };
 
 declare type AccessibilityProps = {
+  accessible?: boolean;
   accessibilityLabel?: string;
   accessibilityHint?: string;
   "aria-label"?: string;
   "aria-description"?: string;
   accessibilityRole?: string;
   "aria-role"?: string;
+  role?: string;
+  tabindex?: number;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applicaster/zapp-react-native-utils",
-  "version": "13.0.5",
+  "version": "13.0.6-alpha.1043196035",
   "description": "Applicaster Zapp React Native utilities package",
   "main": "index.js",
   "types": "index.d.ts",
@@ -27,7 +27,7 @@
   },
   "homepage": "https://github.com/applicaster/quickbrick#readme",
   "dependencies": {
-    "@applicaster/applicaster-types": "13.0.5",
+    "@applicaster/applicaster-types": "13.0.6-alpha.1043196035",
     "buffer": "^5.2.1",
     "camelize": "^1.0.0",
     "dayjs": "^1.11.10",