Merge pull request #5 from SimformSolutionsPvtLtd/feature/UNT-T38911_unify_haptics_api

feat(UNT-T38911): Unify haptic API with awaitable playback, cross-platform checks, and doc updates

Author: mukesh-simform

README.md

@@ -48,8 +48,8 @@ Import and use the library in your React Native app:
 ```jsx
 import { HapticPatterns } from 'react-native-haptic-patterns';
 
-// Check haptic support (iOS only)
-await HapticPatterns.checkHapticSupportForIOS();
+// Check haptic support
+await HapticPatterns.checkForHapticSupport();
 
 // Play a simple haptic pattern
 await HapticPatterns.playHapticPattern(200); // Vibrate for 200ms
@@ -69,17 +69,22 @@ await HapticPatterns.playRecordedPattern(recordedEvents);
 
 ## Methods
 
-### checkHapticSupportForIOS
+### checkForHapticSupport
 
 ```ts
-checkHapticSupportForIOS(): Promise<boolean>
+checkForHapticSupport(): Promise<boolean>
 ```
 
-Checks if the device supports haptic feedback (iOS only).
+Checks if the device supports haptic feedback.
+
+Platform behavior:
+
+- **Android:** Always returns `true` as Android devices support haptic feedback through the Vibration API.
+- **iOS:** Queries the device's Core Haptics capabilities to determine if haptic feedback is supported.
 
 Returns:
 
-- A Promise that returns true if haptics are supported, false otherwise
+- A Promise that resolves to `true` if haptics are supported, `false` otherwise.
 
 ---
 
@@ -144,7 +149,7 @@ Platform behavior:
 
 Returns:
 
-- A Promise that resolves when the pattern has started playing.
+- A Promise that resolves when the entire pattern has finished playing.
 
 ## Examples
 

example/src/App.tsx

@@ -15,6 +15,7 @@ export default function App() {
   const [isRecording, setIsRecording] = useState(false);
   const [recordedEvents, setRecordedEvents] = useState<RecordedEvent[]>([]);
   const [hasRecording, setHasRecording] = useState(false);
+  const [isPlayingPattern, setIsPlayingPattern] = useState(false);
   const recordingStartTime = useRef<number | null>(null);
   const recordingTimeout = useRef<any>(null);
 
@@ -130,45 +131,59 @@ export default function App() {
 
   return (
     <View style={styles.container}>
-      <TouchableOpacity
-        onPressIn={() => {
-          HapticPatterns.playHapticPattern(maxPlayBackTime);
-          if (isRecording) recordPress();
-        }}
-        onPressOut={() => {
-          HapticPatterns.stopHapticPattern();
-          if (isRecording) recordRelease();
-        }}
-        style={[styles.button, isRecording && styles.recordingActive]}>
-        <Text>
-          {Strings.pressToVibrate}
-          {isRecording ? ` (${Strings.recording})` : ''}
-        </Text>
-      </TouchableOpacity>
-
-      <TouchableOpacity
-        onPress={isRecording ? stopRecording : startRecording}
-        style={[styles.button, isRecording && styles.recordingButton]}>
-        <Text>
-          {isRecording ? Strings.stopRecording : Strings.recordPattern}
-        </Text>
-      </TouchableOpacity>
-
-      <TouchableOpacity
-        onPress={() => {
-          if (recordedEvents.length) {
-            HapticPatterns.playRecordedPattern(recordedEvents);
-          }
-        }}
-        style={[styles.button, !hasRecording && styles.disabledButton]}
-        disabled={!hasRecording}>
-        <Text>{Strings.playRecordedPattern}</Text>
-      </TouchableOpacity>
-
-      {hasRecording && (
-        <TouchableOpacity onPress={resetRecording} style={styles.button}>
-          <Text>{Strings.resetRecording}</Text>
-        </TouchableOpacity>
+      {isPlayingPattern ? (
+        <View style={styles.playingMessage}>
+          <Text style={styles.playingText}>Playing recorded pattern...</Text>
+        </View>
+      ) : (
+        <>
+          <TouchableOpacity
+            onPressIn={() => {
+              HapticPatterns.playHapticPattern(maxPlayBackTime);
+              if (isRecording) recordPress();
+            }}
+            onPressOut={() => {
+              HapticPatterns.stopHapticPattern();
+              if (isRecording) recordRelease();
+            }}
+            style={[styles.button, isRecording && styles.recordingActive]}>
+            <Text>
+              {Strings.pressToVibrate}
+              {isRecording ? ` (${Strings.recording})` : ''}
+            </Text>
+          </TouchableOpacity>
+
+          <TouchableOpacity
+            onPress={isRecording ? stopRecording : startRecording}
+            style={[styles.button, isRecording && styles.recordingButton]}>
+            <Text>
+              {isRecording ? Strings.stopRecording : Strings.recordPattern}
+            </Text>
+          </TouchableOpacity>
+
+          {hasRecording && (
+            <TouchableOpacity
+              onPress={() => {
+                setIsPlayingPattern(true);
+                HapticPatterns.playRecordedPattern(recordedEvents).then(() => {
+                  setIsPlayingPattern(false);
+                });
+              }}
+              style={[styles.button, isRecording && styles.disabledButton]}
+              disabled={isRecording}>
+              <Text>{Strings.playRecordedPattern}</Text>
+            </TouchableOpacity>
+          )}
+
+          {hasRecording && (
+            <TouchableOpacity
+              onPress={resetRecording}
+              style={[styles.button, isRecording && styles.disabledButton]}
+              disabled={isRecording}>
+              <Text>{Strings.resetRecording}</Text>
+            </TouchableOpacity>
+          )}
+        </>
       )}
     </View>
   );
@@ -193,7 +208,7 @@ const styles = StyleSheet.create({
   },
   disabledButton: {
     backgroundColor: '#cccccc',
-    opacity: 0.7,
+    opacity: 0.25,
   },
   box: {
     width: 60,
@@ -204,4 +219,15 @@ const styles = StyleSheet.create({
     borderWidth: 2,
     borderColor: '#ff6b6b',
   },
+  playingMessage: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 20,
+  },
+  playingText: {
+    fontSize: 18,
+    fontWeight: 'bold',
+    color: '#333',
+    textAlign: 'center',
+  },
 });

src/haptic-patterns/HapticPatterns.android.ts

@@ -19,6 +19,15 @@ export const playHapticPattern = (
   Vibration.vibrate(vibrationDuration ?? DEFAULT_VIBRATION_DURATION_IN_MS);
 };
 
+/**
+ * Checks if the device supports haptic feedback
+ * @returns {Promise<boolean>} - Always returns true as Android devices support haptics.
+ */
+export const checkForHapticSupport = async (): Promise<boolean> => {
+  // On Android, the haptic support is always available
+  return true;
+};
+
 /**
  * Stops any ongoing haptic vibration.
  */
@@ -30,8 +39,9 @@ export const stopHapticPattern = () => {
  * Plays a recorded haptic pattern based on an array of recorded events.
  *
  * @param {RecordedEventType[]} recordedEvents - Array of recorded haptic events to play as a pattern.
+ * @returns {Promise<void>} Resolves when the entire vibration pattern has finished playing.
  */
-export const playRecordedPattern = (recordedEvents: RecordedEventType[]) => {
+export const playRecordedPattern = async (recordedEvents: RecordedEventType[]): Promise<void> => {
   if (recordedEvents.length === 0) {
     return;
   }
@@ -66,5 +76,16 @@ export const playRecordedPattern = (recordedEvents: RecordedEventType[]) => {
     }
   }
 
+  // Calculate total pattern duration
+  const totalDuration = androidPattern.reduce((sum, duration) => sum + duration, 0);
+
+  // Start the vibration pattern
   Vibration.vibrate(androidPattern);
+
+  // Return a promise that resolves after the pattern completes
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      resolve();
+    }, totalDuration);
+  });
 };

src/haptic-patterns/HapticPatterns.ios.ts

@@ -30,18 +30,17 @@ const HapticEngine: HapticEngineModuleType = NativeModules.HapticEngine
     );
 
 /**
- * Checks if the device supports haptic feedback (iOS only).
- * @async
+ * Checks if the device supports haptic feedback.
  * @returns {Promise<boolean>} returns true if haptics are supported, false otherwise
  */
-export const checkHapticSupportForIOS = async (): Promise<boolean> => {
+export const checkForHapticSupport = async (): Promise<boolean> => {
   const capabilities = await HapticEngine.getDeviceCapabilities();
 
   return capabilities.supportsHaptics;
 };
 
 /**
- * Helper function to initialize the HapticEngine, create a player, and play the pattern (iOS only).
+ * Helper function to initialize the HapticEngine, create a player, and play the pattern.
  * @async
  * @param {HapticPatternType} pattern - The haptic pattern to play.
  * @returns {Promise<void>}
@@ -56,7 +55,7 @@ export const playHapticPattern = async (
   // vibrationDuration will be in milliseconds
   vibrationDuration: number
 ) => {
-  const isSupported = await checkHapticSupportForIOS();
+  const isSupported = await checkForHapticSupport();
   if (!isSupported) {
     throw new Error('Device does not support haptics');
   }
@@ -92,7 +91,7 @@ export const playHapticPattern = async (
  * @throws {Error} If the device does not support haptics or stopping fails.
  */
 export const stopHapticPattern = async () => {
-  const isSupported = await checkHapticSupportForIOS();
+  const isSupported = await checkForHapticSupport();
   if (!isSupported) {
     throw new Error('Device does not support haptics');
   }
@@ -108,13 +107,13 @@ export const stopHapticPattern = async () => {
  *
  * @async
  * @param {RecordedEventType[]} recordedEvents - An array of recorded haptic events, each with startTime, endTime, and isPause properties.
- * @returns {Promise<void>} Resolves when the haptic pattern has finished playing or if no events are provided.
+ * @returns {Promise<void>} Resolves when the entire haptic pattern has finished playing or if no events are provided.
  * @throws {Error} If playing the pattern fails.
  */
 export const playRecordedPattern = async (
   recordedEvents: RecordedEventType[]
 ) => {
-  const isSupported = await checkHapticSupportForIOS();
+  const isSupported = await checkForHapticSupport();
   if (!isSupported) {
     throw new Error('Device does not support haptics');
   }
@@ -171,9 +170,19 @@ export const playRecordedPattern = async (
     }
   });
 
+  // Calculate total pattern duration in milliseconds
+  const totalDurationMs = time * 1000;
+
   try {
     await initializeAndPlayHapticPattern({ hapticEvents });
+
+    // Return a promise that resolves after the pattern completes
+    return new Promise<void>(resolve => {
+      setTimeout(() => {
+        resolve();
+      }, totalDurationMs);
+    });
   } catch (error) {
-    console.error('Failed to play pattern', error);
+    throw error;
   }
 };

src/haptic-patterns/HapticPatternsTypes.ts

@@ -98,3 +98,10 @@ export type HapticEngineModuleType = {
   ): Promise<boolean>;
   stop(): Promise<boolean>;
 };
+
+export interface HapticPatternsModuleType {
+  checkForHapticSupport: () => Promise<boolean>;
+  playHapticPattern: (vibrationDuration: number) => void;
+  stopHapticPattern: () => Promise<void>;
+  playRecordedPattern: (recordedEvents: RecordedEventType[]) => Promise<void>;
+}

src/haptic-patterns/index.ts

@@ -1,4 +1,6 @@
-const HapticPatterns = require('./HapticPatterns');
+import type { HapticPatternsModuleType } from './HapticPatternsTypes';
+
+const HapticPatterns: HapticPatternsModuleType = require('./HapticPatterns');
 
 export * from './HapticPatternsTypes';
 export default HapticPatterns;