react-native-navigation-mode 1.1.0 → 1.1.1

package/README.md

@@ -32,58 +32,12 @@
   </table>
 </div>
 
----
-
-## 🤔 Why This Library?
-
-Android devices can use different navigation modes, but detecting which one is active has been a major pain point for React Native developers. Most existing solutions rely on unreliable workarounds:
-
-### ❌ Common Bad Approaches
-
-- **Screen dimension calculations** - Breaks on different screen sizes and orientations
-- **Safe area inset guessing** - Inconsistent across devices and Android versions
-- **Margin-based detection** - Fragile and depends on UI layout changes
-- **Manual device databases** - Impossible to maintain for all Android devices
-
-### ✅ This Library's Solution
-
-This library uses **official Android APIs** to directly query the system's navigation configuration:
-
-- **`config_navBarInteractionMode`** - The actual system resource Android uses internally
-- **Settings.Secure provider** - Fallback method for reliable detection
-- **Zero guesswork** - No calculations, no assumptions, just direct system queries
-
-### 🚀 Critical for Edge-to-Edge Mode
-
-With Android 15 enforcing edge-to-edge display for apps targeting API 35 and Google mandating this for Play Store updates starting August 31, 2025, proper navigation detection is now **essential**:
+------
 
-- **Edge-to-edge enforcement** - Android 16 will remove the opt-out entirely
-- **Expo SDK 53+** - New projects use edge-to-edge by default
-- **React Native 0.79+** - Built-in support for 16KB page size and edge-to-edge
-- **Safe area management** - Critical for preventing content overlap with system bars (especially noticeable in 3-button navigation mode).
-
-### Real-World Impact
-
-```typescript
-// Before: Unreliable dimension-based guessing
-const isGesture = screenHeight === windowHeight; // 😢 Breaks easily
-
-// After: Direct system detection  
-const isGesture = await isGestureNavigation(); // 🎯 Always accurate
-```
-
-**Perfect for:**
-
-- 🎨 Adaptive UI layouts based on navigation type
-- 📱 Bottom sheet positioning and safe areas
-- 🧭 Navigation-aware component design
-- 🔄 Edge-to-edge layout compatibility
-- 📊 Analytics and user experience tracking
-
-## ✨ Features
+## ✨ Key Features
 
 - 🎯 **Direct Native Detection** - No hacky workarounds or dimension-based guessing
-- ⚡ **Turbo Module** - Built with the latest React Native architecture
+- ⚡ **Turbo Module** - Built for React Native New Architecture
 - 🔄 **Real-time Detection** - Accurate navigation mode identification
 - 📏 **Navigation Bar Height** - Get exact navigation bar height in dp for precise UI calculations
 - 📱 **Cross Platform** - Android detection + iOS compatibility
@@ -92,7 +46,9 @@ const isGesture = await isGestureNavigation(); // 🎯 Always accurate
 - 🛡️ **TypeScript** - Full type safety out of the box
 - ↕️ **Edge To Edge Support** - Full support for `react-native-edge-to-edge`
 
-## Installation
+## 🚀 Quick Start
+
+### Installation
 
 Using yarn:
 
@@ -106,124 +62,250 @@ Using npm:
 npm install react-native-navigation-mode
 ```
 
-### For React Native CLI
+> **Note:** Auto-linking should handle setup automatically for all newer RN versions.
 
-Auto-linking handles setup automatically for React Native 0.60+.
+---
 
-## Usage
+### Basic Usage
 
-### Quick Check
+```tsx
+import { useNavigationMode } from 'react-native-navigation-mode';
 
-```typescript
-import { isGestureNavigation } from 'react-native-navigation-mode';
+export default function App() {
+  const { navigationMode, loading, error } = useNavigationMode();
 
-// Simple boolean check
-const isGesture = await isGestureNavigation();
-console.log('Gesture navigation:', isGesture); // true/false
+  if (loading) return (<Text>Detecting navigation mode...</Text>);
+  if (error) return (<Text>Error: {error.message}</Text>);
+
+  return (
+    <View>
+      <Text>Navigation Type: {navigationMode?.type}</Text>
+      <Text>Gesture Navigation: {navigationMode?.isGestureNavigation ? 'Yes' : 'No'}</Text>
+      <Text>Navigation Bar Height: {navigationMode?.navigationBarHeight}dp</Text>
+    </View>
+  );
+}
 ```
 
-### Detailed Information
+---
+
+## 🔧 API Reference
+
+### React Hook (Recommended)
+
+#### `useNavigationMode(): { navigationMode, loading, error }`
+
+- Returned property types:
+
+| Property      | Type                           | Description                                                  |
+| ------------- | ------------------------------ | ------------------------------------------------------------ |
+| navigatioMode | `NavigationModeInfo` or `null` | All properties mentioned in [NavigationModeInfo](#navigationmodeinfo). |
+| loading       | `boolean`                      | Indicates if navigation mode info is being fetched.          |
+| error         | `Error`                        | Typescript error object containing the cause of the error.   |
+
+The easiest way to detect navigation mode with loading and error states.
+
+```tsx
+import { useNavigationMode } from 'react-native-navigation-mode';
+
+function MyComponent() {
+  const { navigationMode, loading, error } = useNavigationMode();
+  
+  if (loading) return <Text>Loading...</Text>;
+  if (error) return <Text>Error: {error.message}</Text>;
+  
+  return (
+    <View>
+      <Text>Navigation Type: {navigationMode?.type}</Text>
+      <Text>Is Gesture: {navigationMode?.isGestureNavigation ? 'Yes' : 'No'}</Text>
+      <Text>Bar Height: {navigationMode?.navigationBarHeight}dp</Text>
+    </View>
+  );
+}
+```
+
+### Functions
+
+#### `getNavigationMode(): Promise<`[NavigationModeInfo](#navigationmodeinfo)`>`
+
+Returns comprehensive navigation mode information.
 
 ```typescript
 import { getNavigationMode } from 'react-native-navigation-mode';
 
-// Get comprehensive navigation info
 const navInfo = await getNavigationMode();
 console.log('Navigation type:', navInfo.type); // '3_button', '2_button', 'gesture', or 'unknown'
 ```
 
-### Navigation Bar Height
+#### `isGestureNavigation(): Promise<boolean>`
+
+Quick check if device is using gesture navigation.
+
+```typescript
+import { isGestureNavigation } from 'react-native-navigation-mode';
+
+const isGesture = await isGestureNavigation();
+console.log('Gesture navigation:', isGesture); // true/false
+```
+
+#### `getNavigationBarHeight(): Promise<number>`
+
+Returns the navigation bar height in density-independent pixels (dp).
 
 ```typescript
 import { getNavigationBarHeight } from 'react-native-navigation-mode';
 
-// Get navigation bar height in dp
 const height = await getNavigationBarHeight();
 console.log('Navigation bar height:', height); // number (dp)
 ```
 
-### React Hook (Recommended)
+### Types
 
-```typescript
-import React from 'react';
-import { View, Text } from 'react-native';
-import { useNavigationMode } from 'react-native-navigation-mode';
+#### `NavigationModeInfo`
 
-export default function NavigationInfo() {
-  const { navigationMode, loading, error } = useNavigationMode();
+| Property            | Type                                                        | Description                                               |
+| ------------------- | ----------------------------------------------------------- | --------------------------------------------------------- |
+| type                | `'3_button'` or `'2_button'` or `'gesture'` or  `'unknown'` | 4 possible Android navigation modes that can be detected. |
+| isGestureNavigation | `boolean`                                                   | Whether gesture navigation is active.                     |
+| interactionMode     | `number` or `undefined`                                     | See [Navigation Mode Values](#navigation-mode-values)     |
+| navigationBarHeight | `number` or `undefined`                                     | Navigation bar height in density-independent pixels (dp). |
 
-  if (loading) return <Text>Detecting navigation mode...</Text>;
-  if (error) return <Text>Error: {error.message}</Text>;
+### Navigation Mode Values
+
+| Android Mode | Type       | Description                                         |
+| ------------ | ---------- | --------------------------------------------------- |
+| 0            | `3_button` | Traditional Android navigation (Back, Home, Recent) |
+| 1            | `2_button` | Two-button navigation (Back, Home)                  |
+| 2            | `gesture`  | Full gesture navigation                             |
+| -1           | `unknown`  | Could not determine navigation mode                 |
+
+---
+
+## 💡 Usage Examples
+
+### Adaptive UI Layout
+
+```tsx
+import { useNavigationMode } from 'react-native-navigation-mode';
+
+export default function AdaptiveUI() {
+  const { navigationMode } = useNavigationMode();
 
   return (
-    <View>
-      <Text>Navigation Type: {navigationMode?.type}</Text>
-      <Text>Gesture Navigation: {navigationMode?.isGestureNavigation ? 'Yes' : 'No'}</Text>
+    <View 
+      style={{
+        // paddingBottom using real navigation bar height
+        paddingBottom: navigationMode?.navigationBarHeight || 0,
+      }}>
+      {/* Your content */}
     </View>
   );
 }
 ```
 
-### Conditional UI Rendering
+### Conditional Rendering
 
-```typescript
-import React from 'react';
-import { View } from 'react-native';
+```tsx
 import { useNavigationMode } from 'react-native-navigation-mode';
 
-export default function AdaptiveUI() {
+export default function ConditionalUI() {
   const { navigationMode } = useNavigationMode();
 
   return (
-    <View 
-      style={{
-        paddingBottom: navigationMode?.navigationBarHeight
-      }}
-    >
-      {/* Your content */}
+    <View>
+      {navigationMode?.isGestureNavigation && (
+        <Text>Swipe gestures are available!</Text>
+      )}
+      
+      {navigationMode?.type === '3_button' && (
+        <Text>Traditional navigation buttons detected</Text>
+      )}
     </View>
   );
 }
 ```
 
-## API Reference
+### Manual Detection
 
-### Functions
+```typescript
+import { 
+  getNavigationMode, 
+  isGestureNavigation, 
+  getNavigationBarHeight 
+} from 'react-native-navigation-mode';
+
+const checkNavigation = async () => {
+  // Get all info at once
+  const navInfo = await getNavigationMode();
+  
+  // Or get specific info
+  const isGesture = await isGestureNavigation();
+  const barHeight = await getNavigationBarHeight();
+  
+  console.log('Navigation info:', navInfo);
+  console.log('Is gesture:', isGesture);
+  console.log('Bar height:', barHeight);
+};
+```
 
-#### `getNavigationMode(): Promise<NavigationModeInfo>`
+---
 
-Returns comprehensive navigation mode information.
+## 🤔 Why This Library?
 
-#### `isGestureNavigation(): Promise<boolean>`
+Android devices can use different navigation modes, but detecting which one is active has been a major pain point for React Native developers. Most existing solutions rely on unreliable workarounds:
 
-Quick check if device is using gesture navigation.
+### ❌ Common Bad Approaches
 
-#### `getNavigationBarHeight(): Promise<number>`
+- **Screen dimension calculations** - Breaks on different screen sizes and orientations
+- **Safe area inset guessing** - Inconsistent across devices and Android versions
+- **Margin-based detection** - Fragile and depends on UI layout changes
+- **Manual device databases** - Impossible to maintain for all Android devices
 
-Returns the navigation bar height in density-independent pixels (dp).
+### ✅ This Library's Solution
 
-### Hooks
+This library uses **official Android APIs** to directly query the system's navigation configuration:
 
-#### `useNavigationMode(): { navigationMode, loading, error }`
+- **`config_navBarInteractionMode`** - The actual system resource Android uses internally
+- **Settings.Secure provider** - Fallback method for reliable detection
+- **WindowInsets API** - Accurate navigation bar height detection
+- **Zero guesswork** - No calculations, no assumptions, just direct system queries
 
-React hook for navigation mode detection with loading and error states.
+### 🚀 Critical for Edge-to-Edge Mode
 
-### Types
+With Android 15 enforcing edge-to-edge display for apps targeting API 35 and Google mandating this for Play Store updates starting August 31, 2025, proper navigation detection is now **essential**:
 
-#### `NavigationModeInfo`
+- **Edge-to-edge enforcement** - Android 16 will remove the opt-out entirely
+- **Expo SDK 53+** - New projects use edge-to-edge by default
+- **React Native 0.79+** - Built-in support for 16KB page size and edge-to-edge
+- **Safe area management** - Critical for preventing content overlap with system bars
 
-| Property            | Type                                              | Description                                   |
-| ------------------- | ------------------------------------------------- | --------------------------------------------- |
-| type                | `'3_button' | '2_button' | 'gesture' | 'unknown'` | Navigation mode type                          |
-| isGestureNavigation | `boolean`                                         | Whether gesture navigation is active          |
-| interactionMode     | `number | undefined`                              | Raw Android interaction mode (0, 1, 2, or -1) |
-| navigationBarHeight | `number | undefined`                              | Navigation bar height in dp                   |
+### Real-World Impact
 
-## Platform Support
+```typescript
+// Before: Unreliable dimension-based guessing
+const isGesture = screenHeight === windowHeight; // 😢 Breaks easily
 
-| Platform | Support | Notes |
-|----------|---------|-------|
-| Android  | ✅ Full | Detects all navigation modes and navigation bar height via native Android APIs |
+// After: Direct system detection  
+const isGesture = await isGestureNavigation(); // 🎯 Always accurate
+```
+
+**Perfect for:**
+
+- 🎨 Adaptive UI layouts based on navigation type
+- 📱 Bottom sheet positioning and safe areas
+- 🧭 Navigation-aware component design
+- 🔄 Edge-to-edge layout compatibility
+- 📊 Analytics and user experience tracking
+
+---
+
+## 🛠️ Technical Details
+
+### Platform Support
+
+| Platform | Support      | Notes                                                        |
+| -------- | ------------ | ------------------------------------------------------------ |
+| Android  | ✅ Full       | Detects all navigation modes and navigation bar height via native Android APIs |
 | iOS      | ✅ Compatible | Always returns `gesture` and `navigationBarHeight: 0` (iOS uses gesture navigation) |
 
 ### Android Compatibility
@@ -234,51 +316,51 @@ React hook for navigation mode detection with loading and error states.
 - **API 30+** - WindowInsets-based navigation bar height detection
 - **API 24-29** - Resource-based navigation bar height fallback
 
-## How It Works
+### How It Works
 
 The library uses multiple detection methods for maximum accuracy:
 
 1. **`config_navBarInteractionMode`** - Official Android configuration (API 29+)
 2. **Settings Provider** - Checks `navigation_mode` system setting
-3. **Navigation Bar Detection** - Validates navigation bar presence
-4. **Hardware Key Detection** - Fallback for older devices
-
-### Navigation Mode Values
-
-| Android Mode | Type | Description |
-|--------------|------|-------------|
-| 0 | `3_button` | Traditional Android navigation (Back, Home, Recent) |
-| 1 | `2_button` | Two-button navigation (Back, Home) |
-| 2 | `gesture` | Full gesture navigation |
-| -1 | `unknown` | Could not determine navigation mode |
+3. **WindowInsets API** - Accurate navigation bar height detection (API 30+)
+4. **Resource-based fallback** - Navigation bar height for older devices
 
-## Notes
+### Performance Notes
 
-1. 1. 🍎 **iOS Behavior** - iOS always returns `isGestureNavigation: true` and `navigationBarHeight: 0` since iOS doesn't have Android-style navigation bars
+1. 🍎 **iOS Behavior** - iOS always returns `isGestureNavigation: true` and `navigationBarHeight: 0` since iOS doesn't have Android-style navigation bars
 2. ⚡ **Performance** - Turbo module ensures minimal performance impact
 3. 🔄 **Real-time** - Navigation mode is detected at call time, reflecting current device settings
 
-## Troubleshooting
+---
+
+## 🐛 Troubleshooting
 
 ### Common Issues
 
 **"TurboModuleRegistry.getEnforcing(...) is not a function"**
+
 - Ensure you're using React Native 0.68+ with new architecture enabled
 - For older RN versions, the module will fallback gracefully
 
-**Always returns 'unknown' on Android**
+**Always returns `'unknown'` on Android**
+
 - Check if your device/emulator supports the navigation mode APIs
 - Some custom ROMs may not expose standard Android navigation settings
 
-## Contributing
+**Navigation bar height returns `0`**
+
+- This is normal on devices without navigation bars (some tablets)
+- On older Android versions, fallback detection may not work on all devices
+
+## 🤝 Contributing
 
 See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
 
-## License
+## 📄 License
 
 MIT
 
-## Support the project
+## 💖 Support the Project
 
 <p align="center" valign="center">
   <a href="https://liberapay.com/FutureJJ/donate">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-navigation-mode",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Detect Android navigation mode (3-button, 2-button, or gesture)",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",