expo-rotation-module 1.0.0 → 1.0.2

package/README.md

@@ -1,77 +1,173 @@
 # expo-rotation-module
 
-An Expo native module that controls the Android system rotation settings (ACCELEROMETER_ROTATION and USER_ROTATION).
+A small Expo native module that lets an Android app read and control the system rotation settings (ACCELEROMETER_ROTATION and USER_ROTATION) and request the `WRITE_SETTINGS` permission.
 
-## Overview
-This package exposes a small API to check and request the WRITE_SETTINGS permission and to read/set the global rotation mode. This module is Android-only; iOS and web are no-ops.
+This module exposes a tiny JS/TS API and includes Android and iOS native source. The runtime behavior is Android-only; iOS/web are no-ops.
 
-## Install (local development with pnpm)
+---
 
-From the module repo:
+## Usage
 
-- `pnpm install`
-- (optional) `pnpm build` — runs the expo-module build scripts
+### Install
 
-From your Expo app project:
+- From your app project (local development):
+  - `pnpm add ../path/to/expo-rotation-module` (or use a published package: `pnpm add expo-rotation-module`)
 
-- Add the module locally: `pnpm add ../expo-rotation-module` (or `pnpm add file:../expo-rotation-module`)
-- IMPORTANT: Add the plugin to your app config so the permission is injected during prebuild:
+- IMPORTANT: add the config plugin to your app config so the permission is injected during `prebuild`.
 
-  In `app.json` or `app.config.js` add the following to your `expo.plugins` array:
+  In `app.json` or `app.config.js` add the package name to `expo.plugins`:
 
   ```json
-  "plugins": [
-    "expo-rotation-module"
-  ]
+  {
+    "expo": {
+      "plugins": [
+        "expo-rotation-module"
+      ]
+    }
+  }
   ```
 
-- Run `npx expo prebuild` to apply the config plugin and update `AndroidManifest.xml`.
-- Rebuild the Android app (use EAS dev client or Android Studio):
-  - Recommended: `pnpm add expo-dev-client` then `eas build --profile development --platform android` and run with `expo start --dev-client`.
+  - The plugin is implemented in `plugin/index.js` and will insert the `WRITE_SETTINGS` permission into your `AndroidManifest.xml` during `expo prebuild`.
+
+- Apply native changes and build the app:
+  - `npx expo prebuild` (or `expo run:android` which runs prebuild automatically)
+  - Rebuild/install the app on device/emulator (use a custom dev client or a standalone build for WRITE_SETTINGS tests — Expo Go is not suitable).
 
-## API
+### API
 
-Import functions:
+Import the module in JS/TS:
 
 ```ts
-import Rotation, { canWrite, requestWritePermission, getRotationState, setRotationState } from 'expo-rotation-module';
+import Rotation, {
+  canWrite,
+  requestWritePermission,
+  getRotationState,
+  setRotationState,
+  getPackageName,
+} from 'expo-rotation-module';
 ```
 
-- `canWrite(): Promise<boolean>` — true if WRITE_SETTINGS is granted (Android M+), otherwise true on older OS.
-- `requestWritePermission(): void` — opens Settings where the user can grant WRITE_SETTINGS.
-- `getRotationState(): Promise<'AUTOROTATE'|'PORTRAIT'|'LANDSCAPE'>` — reads current rotation state.
-- `setRotationState(state): Promise<void>` — sets rotation. Rejects with an Error object that may include a `.code` property.
+- `canWrite(): Promise<boolean>` — returns true if the app has `WRITE_SETTINGS` granted (Android M+). Returns `true` on older OS versions.
+- `requestWritePermission(): void` — opens the Android Settings screen where the user can grant the permission for your app.
+- `getRotationState(): Promise<'AUTOROTATE'|'PORTRAIT'|'LANDSCAPE'>` — reads the current global rotation state. The module reports the coarse axis (PORTRAIT or LANDSCAPE); within those axes the system sensor still allows regular or inverted orientations when auto-rotate is off.
+- `setRotationState(state): Promise<void>` — sets the rotation state. Rejects with an Error that may contain a `code` property (e.g. `E_PERMISSION`).
+- `getPackageName(): Promise<string>` — returns the package name the native module is using (useful for diagnostics).
 
-Error codes on the Error object (if available): `E_PERMISSION`, `E_INVALID_STATE`, `E_SET_ROTATION`, `E_GET_ROTATION`, `E_NO_MODULE`.
+All functions are Android-only. On non-Android platforms the functions are no-ops or return safe defaults.
 
-## Example
+### Example
 
 ```ts
-import * as Rotation from 'expo-rotation-module';
+import Rotation from 'expo-rotation-module';
 
-async function example() {
-  if (!(await Rotation.canWrite())) {
+async function ensureAndSet() {
+  const hasPermission = await Rotation.canWrite();
+  if (!hasPermission) {
+    // Opens Settings where the user can grant WRITE_SETTINGS for your app
     Rotation.requestWritePermission();
     return;
   }
 
-  try {
-    await Rotation.setRotationState('PORTRAIT');
-  } catch (e: any) {
-    if (e.code === 'E_PERMISSION') {
-      console.warn('Permission missing');
-    }
-  }
+  await Rotation.setRotationState('PORTRAIT');
 }
 ```
 
-## Plugin
-The package contains `plugin/index.js` that injects `android.permission.WRITE_SETTINGS` into the host app's AndroidManifest during `expo prebuild`.
+### Troubleshooting
 
-## Package id and Android settings
-The Android package/namespace used within module sources is `ktsierra.expo.rotationmodule`.
+- WRITE_SETTINGS switch is greyed out in the Settings screen:
+  - Ensure your app has the `WRITE_SETTINGS` permission declared in the manifest. The config plugin adds this when you run `expo prebuild`.
+  - Do not test this inside Expo Go — the Settings screen will target the Expo Go package. Build a custom dev client or standalone build.
+  - Confirm the package name by calling `Rotation.getPackageName()` and check device logs for the `Opening WRITE_SETTINGS for package: <pkg>` message.
 
-## Contributing & tests
-If you want CI or tests added (TS checks, build smoke tests), I can add a GitHub Actions workflow that runs `pnpm install` and `pnpm build`.
+- ESLint/type errors in consuming projects:
+  - Ensure your app can resolve the package. For local linking with pnpm workspaces, `pnpm install` in the app and a restart of the editor/TS server is sometimes required.
 
 ---
+
+## Development
+
+This section explains how to develop, test and publish this module.
+
+### Repo layout (important files)
+
+- `src/` — TypeScript JS wrapper and types.
+- `android/` — Android native sources (Kotlin) and Gradle files.
+- `ios/` — iOS native sources (Swift) and podspec.
+- `plugin/` — config plugin that injects the `WRITE_SETTINGS` permission.
+- `app.plugin.js` — plugin entry point for Expo to discover the config plugin.
+- `index.js` — package entry that re-exports the JS wrapper.
+- `package.json` — package metadata, scripts and publish config.
+
+### Local development
+
+1. Install dependencies in the module repo:
+   - `pnpm install`
+
+2. Make changes to `src/` or native code.
+
+3. Build/prepare artifacts (some scripts expect `tsc`/expo-module-scripts):
+   - `pnpm run prepare` (runs `expo-module prepare`) or `pnpm run build` (if you prefer).
+
+4. Test in an app:
+   - Create or use an example app. From the app root:
+     - Add the local package: `pnpm add ../path/to/expo-rotation-module` (or `pnpm add file:...`)
+     - Ensure `app.json` includes the plugin (see Usage).
+     - Run `npx expo prebuild` and verify `android/app/src/main/AndroidManifest.xml` contains `<uses-permission android:name="android.permission.WRITE_SETTINGS" />`.
+     - Build and run the app on device/emulator (`expo run:android` or a dev client build).
+
+5. Faster iteration (optional):
+   - Instead of building the package, map Metro to the module `src` in the app `metro.config.js` during development:
+     ```js
+     // example: app/metro.config.js
+     const path = require('path');
+     module.exports = {
+       resolver: {
+         extraNodeModules: {
+           'expo-rotation-module': path.resolve(__dirname, '../path/to/expo-rotation-module/src'),
+         },
+       },
+       watchFolders: [path.resolve(__dirname, '..')],
+     };
+     ```
+   - This lets the app load the TypeScript source directly without rebuilding the package on every change.
+
+### Publishing
+
+We publish the source package (native sources included). Before publishing, ensure:
+
+- `package.json` fields are correct (`name`, `version`, `main`, `types`, `files`).
+- `devDependencies` contains `typescript` so `expo-module prepare` runs in CI.
+- The plugin and native sources are included in the published package (use the `files` array in `package.json` to control this).
+
+Manual publish (local):
+
+1. Prepare the package locally:
+   - `pnpm install`
+   - `pnpm run prepare`
+
+2. Create a tarball to test what will be published:
+   - `npm pack`
+   - Install the tarball into a test app: `pnpm add ../expo-rotation-module-<version>.tgz`
+   - Run `npx expo prebuild` in the test app to confirm the plugin and native sources are applied.
+
+3. Publish:
+   - If your environment has an npm automation token configured in CI, run `npm publish --access public` from the package root.
+   - If `prepublishOnly` scripts fail in your environment, you can publish with scripts ignored after preparing locally:
+     - `npm publish --access public --ignore-scripts`
+
+### Continuous Integration / GitHub Actions
+
+- Recommended CI flow:
+  - `pnpm install --frozen-lockfile`
+  - `pnpm run prepare` (ensure `typescript` is installed in `devDependencies` so `tsc` is available)
+  - Run tests/lint (optional)
+  - Bump version, push tags
+  - Authenticate to npm (use an automation token or GitHub OIDC if your npm org supports trusted publishers)
+  - `npm publish --access public` or `pnpm publish --access public`
+
+- Example workflow (summary):
+  - Checkout, setup Node + pnpm, `pnpm install`, run `pnpm run prepare`, bump version, publish.
+
+---
+
+If you find anything missing or unclear (examples, API signatures, or CI details) open an issue or submit a PR. Contributions welcome.

package/android/src/main/java/ktsierra/expo/rotationmodule/ExpoRotationModule.kt

@@ -2,11 +2,13 @@ package ktsierra.expo.rotationmodule
 
 import android.app.Activity
 import android.content.ContentResolver
+import android.content.Context
 import android.content.Intent
 import android.net.Uri
 import android.os.Build
 import android.provider.Settings
 import android.util.Log
+import android.content.pm.ActivityInfo
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
 
@@ -16,6 +18,10 @@ class ExpoRotationModule : Module() {
     const val TAG = "ExpoRotationModule"
   }
 
+  private var orientationListener: android.view.OrientationEventListener? = null
+  private var desiredAxis: String? = null
+  private var lastWrittenRotation: Int = -1
+
   override fun definition() = ModuleDefinition {
     Name(NAME)
 
@@ -34,6 +40,20 @@ class ExpoRotationModule : Module() {
       }
     }
 
+    // Expose helpers (optional)
+    Function("startOrientationListener") {
+      val ctx = appContext.activityProvider?.currentActivity ?: appContext.reactContext!!
+      startOrientationListener(ctx)
+      return@Function null
+    }
+
+    Function("stopOrientationListener") {
+      orientationListener?.disable()
+      orientationListener = null
+      desiredAxis = null
+      return@Function null
+    }
+
     Function("requestWritePermission") {
       try {
         val activity: Activity? = appContext.activityProvider?.currentActivity
@@ -86,9 +106,8 @@ class ExpoRotationModule : Module() {
             0
           }
           return@AsyncFunction when (rotation) {
-            0 -> "PORTRAIT"
-            1 -> "LANDSCAPE"
-            3 -> "LANDSCAPE"
+            0, 2 -> "PORTRAIT"
+            1, 3 -> "LANDSCAPE"
             else -> "PORTRAIT"
           }
         }
@@ -104,23 +123,36 @@ class ExpoRotationModule : Module() {
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M && !Settings.System.canWrite(ctx)) {
           throw Exception("E_PERMISSION: WRITE_SETTINGS not granted")
         }
-        val resolver: ContentResolver = ctx.contentResolver
+
         when (state) {
           "AUTOROTATE" -> {
+            // Restore system auto-rotate
+            val resolver: ContentResolver = ctx.contentResolver
             Settings.System.putInt(resolver, Settings.System.ACCELEROMETER_ROTATION, 1)
+            // unregister listener if present
+            orientationListener?.disable()
+            orientationListener = null
+            desiredAxis = null
+            lastWrittenRotation = -1
           }
           "PORTRAIT" -> {
+            // disable system auto-rotate and enable axis-lock with sensor flips on portrait axis
+            val resolver: ContentResolver = ctx.contentResolver
             Settings.System.putInt(resolver, Settings.System.ACCELEROMETER_ROTATION, 0)
-            Settings.System.putInt(resolver, Settings.System.USER_ROTATION, 0)
+            desiredAxis = "PORTRAIT"
+            startOrientationListener(ctx)
           }
           "LANDSCAPE" -> {
+            val resolver: ContentResolver = ctx.contentResolver
             Settings.System.putInt(resolver, Settings.System.ACCELEROMETER_ROTATION, 0)
-            Settings.System.putInt(resolver, Settings.System.USER_ROTATION, 1)
+            desiredAxis = "LANDSCAPE"
+            startOrientationListener(ctx)
           }
           else -> {
             throw Exception("E_INVALID_STATE: Invalid rotation state: $state")
           }
         }
+
         return@AsyncFunction null
       } catch (e: Exception) {
         Log.e(TAG, "setRotationState error", e)
@@ -128,4 +160,51 @@ class ExpoRotationModule : Module() {
       }
     }
   }
+
+  private fun startOrientationListener(ctx: Context) {
+    // If listener already exists, do nothing
+    if (orientationListener != null) return
+
+    orientationListener = object : android.view.OrientationEventListener(ctx) {
+      override fun onOrientationChanged(orientation: Int) {
+        // orientation: 0..359 degrees, or ORIENTATION_UNKNOWN (-1)
+        if (orientation == android.view.OrientationEventListener.ORIENTATION_UNKNOWN) return
+        // Normalize to one of the 4 Android rotations: 0, 90, 180, 270
+        val rot = when {
+          orientation in 315..359 || orientation in 0..44 -> 0
+          orientation in 45..134 -> 1
+          orientation in 135..224 -> 2
+          else -> 3
+        }
+
+        try {
+          val resolver: ContentResolver = ctx.contentResolver
+          // desiredAxis controls whether we want portrait or landscape axis.
+          when (desiredAxis) {
+            "PORTRAIT" -> {
+              // We want 0 or 2 depending on angle
+              val target = if (rot == 2) 2 else 0
+              if (lastWrittenRotation != target) {
+                Settings.System.putInt(resolver, Settings.System.USER_ROTATION, target)
+                lastWrittenRotation = target
+              }
+            }
+            "LANDSCAPE" -> {
+              // We want 1 or 3 depending on angle
+              val target = if (rot == 1) 3 else if (rot == 3) 1 else if (rot == 2) 1 else 3
+              // swapped mapping: 90 -> 3, 270 -> 1, fallback 180->1, 0->3
+              if (lastWrittenRotation != target) {
+                Settings.System.putInt(resolver, Settings.System.USER_ROTATION, target)
+                lastWrittenRotation = target
+              }
+            }
+          }
+        } catch (e: Exception) {
+          Log.e(TAG, "orientation listener write error", e)
+        }
+      }
+    }
+
+    orientationListener?.enable()
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-rotation-module",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Screen Orientation Native Module",
   "main": "index.js",
   "types": "src/index.d.ts",

package/src/index.d.ts

@@ -1,4 +1,4 @@
-export type RotationState = "AUTOROTATE" | "PORTRAIT" | "LANDSCAPE";
+export type RotationState = 'AUTOROTATE' | 'PORTRAIT' | 'LANDSCAPE';
 
 export function canWrite(): Promise<boolean>;
 export function requestWritePermission(): void;