@capgo/capacitor-screen-orientation 8.1.20 → 8.2.0

package/README.md

@@ -20,6 +20,7 @@ Screen orientation plugin with support for detecting true physical device orient
 - 🔒 **Detect if orientation lock is enabled** by comparing physical vs UI orientation
 - 🔄 Real-time orientation change detection
 - 🎯 Lock orientation to specific modes
+- 📖 **Foldable posture** on Android: flat, tabletop, or book, plus hinge angle and window size class
 - 🌐 Web platform support
 
 **Important Note:** This plugin can detect the physical orientation of the device using motion sensors, but it **cannot bypass the UI orientation lock**. The screen will still respect the user's orientation lock setting. This is useful for knowing how the device is physically held vs. how the UI is displayed.
@@ -131,6 +132,10 @@ await ScreenOrientation.stopOrientationTracking();
 
 // Remove listener
 await listener.remove();
+
+// Foldables: flat, tabletop, or book. Flat on phones that do not fold.
+const { posture } = await ScreenOrientation.getFoldState();
+const { widthClass } = await ScreenOrientation.getSizeClass();
 ```
 
 ## API
@@ -143,7 +148,14 @@ await listener.remove();
 * [`startOrientationTracking(...)`](#startorientationtracking)
 * [`stopOrientationTracking()`](#stoporientationtracking)
 * [`isOrientationLocked()`](#isorientationlocked)
+* [`isDeviceFoldable()`](#isdevicefoldable)
+* [`getFoldState()`](#getfoldstate)
+* [`getHingeAngle()`](#gethingeangle)
+* [`getSizeClass()`](#getsizeclass)
 * [`addListener('screenOrientationChange', ...)`](#addlistenerscreenorientationchange-)
+* [`addListener('foldStateChange', ...)`](#addlistenerfoldstatechange-)
+* [`addListener('hingeAngleChange', ...)`](#addlistenerhingeanglechange-)
+* [`addListener('sizeClassChange', ...)`](#addlistenersizeclasschange-)
 * [`removeAllListeners()`](#removealllisteners)
 * [`getPluginVersion()`](#getpluginversion)
 * [Interfaces](#interfaces)
@@ -275,26 +287,150 @@ Works on both iOS (Core Motion) and Android (Accelerometer).
 --------------------
 
 
+### isDeviceFoldable()
+
+```typescript
+isDeviceFoldable() => Promise<DeviceFoldableResult>
+```
+
+Whether this device folds, and whether it can stand half-open like a laptop.
+
+Both flags are `false` on web and iOS.
+
+**Returns:** <code>Promise&lt;<a href="#devicefoldableresult">DeviceFoldableResult</a>&gt;</code>
+
+**Since:** 8.2.0
+
+--------------------
+
+
+### getFoldState()
+
+```typescript
+getFoldState() => Promise<FoldState>
+```
+
+Read the current fold.
+
+Resolves to a flat state when the device has no fold.
+
+**Returns:** <code>Promise&lt;<a href="#foldstate">FoldState</a>&gt;</code>
+
+**Since:** 8.2.0
+
+--------------------
+
+
+### getHingeAngle()
+
+```typescript
+getHingeAngle() => Promise<HingeAngleResult>
+```
+
+Read the hinge angle in degrees.
+
+`0` is closed and `180` is flat. `angle` is `null` without a hinge sensor.
+
+**Returns:** <code>Promise&lt;<a href="#hingeangleresult">HingeAngleResult</a>&gt;</code>
+
+**Since:** 8.2.0
+
+--------------------
+
+
+### getSizeClass()
+
+```typescript
+getSizeClass() => Promise<SizeClass>
+```
+
+Read the window size classes.
+
+**Returns:** <code>Promise&lt;<a href="#sizeclass">SizeClass</a>&gt;</code>
+
+**Since:** 8.2.0
+
+--------------------
+
+
 ### addListener('screenOrientationChange', ...)
 
 ```typescript
 addListener(eventName: 'screenOrientationChange', listenerFunc: (result: ScreenOrientationResult) => void) => Promise<PluginListenerHandle>
 ```
 
-Listen for screen orientation changes.
+| Param              | Type                                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------------------ |
+| **`eventName`**    | <code>'screenOrientationChange'</code>                                                           |
+| **`listenerFunc`** | <code>(result: <a href="#screenorientationresult">ScreenOrientationResult</a>) =&gt; void</code> |
 
-Registers a listener that will be called whenever the screen orientation changes.
-If motion-based tracking is enabled, this will also fire for orientation changes
-detected by motion sensors even when orientation lock is enabled.
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
 
-| Param              | Type                                                                                             | Description                                         |
-| ------------------ | ------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
-| **`eventName`**    | <code>'screenOrientationChange'</code>                                                           | The event name. Must be 'screenOrientationChange'.  |
-| **`listenerFunc`** | <code>(result: <a href="#screenorientationresult">ScreenOrientationResult</a>) =&gt; void</code> | Callback function invoked when orientation changes. |
+--------------------
+
+
+### addListener('foldStateChange', ...)
+
+```typescript
+addListener(eventName: 'foldStateChange', listenerFunc: (state: FoldState) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for fold changes.
+
+On a foldable this also fires when the device rotates, because the hinge
+bounds rotate with the window.
+
+| Param              | Type                                                                | Description                                |
+| ------------------ | ------------------------------------------------------------------- | ------------------------------------------ |
+| **`eventName`**    | <code>'foldStateChange'</code>                                      | The event name. Must be 'foldStateChange'. |
+| **`listenerFunc`** | <code>(state: <a href="#foldstate">FoldState</a>) =&gt; void</code> | Callback invoked with the new fold state.  |
 
 **Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
 
-**Since:** 1.0.0
+**Since:** 8.2.0
+
+--------------------
+
+
+### addListener('hingeAngleChange', ...)
+
+```typescript
+addListener(eventName: 'hingeAngleChange', listenerFunc: (event: HingeAngleResult) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for hinge angle changes.
+
+On Android the hinge sensor runs only while at least one listener is registered.
+Never fires on web or iOS.
+
+| Param              | Type                                                                              | Description                                 |
+| ------------------ | --------------------------------------------------------------------------------- | ------------------------------------------- |
+| **`eventName`**    | <code>'hingeAngleChange'</code>                                                   | The event name. Must be 'hingeAngleChange'. |
+| **`listenerFunc`** | <code>(event: <a href="#hingeangleresult">HingeAngleResult</a>) =&gt; void</code> | Callback invoked with the angle in degrees. |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 8.2.0
+
+--------------------
+
+
+### addListener('sizeClassChange', ...)
+
+```typescript
+addListener(eventName: 'sizeClassChange', listenerFunc: (sizeClass: SizeClass) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for size class changes, such as unfolding, rotating, or resizing.
+
+| Param              | Type                                                                    | Description                                |
+| ------------------ | ----------------------------------------------------------------------- | ------------------------------------------ |
+| **`eventName`**    | <code>'sizeClassChange'</code>                                          | The event name. Must be 'sizeClassChange'. |
+| **`listenerFunc`** | <code>(sizeClass: <a href="#sizeclass">SizeClass</a>) =&gt; void</code> | Callback invoked with the new size class.  |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 8.2.0
 
 --------------------
 
@@ -373,6 +509,71 @@ Result returned by the isOrientationLocked() method.
 | **`uiOrientation`**       | <code><a href="#orientationtype">OrientationType</a></code> | The current UI orientation reported by the system.                                                                                                                                                                                                                                                               | 1.0.0 |
 
 
+#### DeviceFoldableResult
+
+Whether this device can fold.
+
+| Prop                   | Type                 | Description                                   | Since |
+| ---------------------- | -------------------- | --------------------------------------------- | ----- |
+| **`foldable`**         | <code>boolean</code> | Whether the device has a fold.                | 8.2.0 |
+| **`supportsTabletop`** | <code>boolean</code> | Whether it can stand half-open like a laptop. | 8.2.0 |
+
+
+#### FoldState
+
+Current fold of the window.
+
+Phones that do not fold, iOS, and web resolve to a flat state.
+
+| Prop                   | Type                                                          | Description                                                        | Since |
+| ---------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------ | ----- |
+| **`state`**            | <code><a href="#foldstatevalue">FoldStateValue</a></code>     | Posture of the fold.                                               | 8.2.0 |
+| **`isSeparating`**     | <code>boolean</code>                                          | Whether the fold splits the web view into two areas.               | 8.2.0 |
+| **`posture`**          | <code><a href="#foldposture">FoldPosture</a></code>           | How the device is held.                                            | 8.2.0 |
+| **`hingeOrientation`** | <code><a href="#hingeorientation">HingeOrientation</a></code> | Direction of the hinge. Omitted when there is no fold.             | 8.2.0 |
+| **`hingeBounds`**      | <code><a href="#foldbounds">FoldBounds</a></code>             | Position of the fold in CSS pixels. Omitted when there is no fold. | 8.2.0 |
+| **`occludedBounds`**   | <code><a href="#foldbounds">FoldBounds</a></code>             | Area the hinge covers. Present when the hinge has a physical gap.  | 8.2.0 |
+
+
+#### FoldBounds
+
+A rectangle in CSS pixels, relative to the web view.
+
+| Prop         | Type                |
+| ------------ | ------------------- |
+| **`x`**      | <code>number</code> |
+| **`y`**      | <code>number</code> |
+| **`width`**  | <code>number</code> |
+| **`height`** | <code>number</code> |
+
+
+#### HingeAngleResult
+
+Angle between the two halves of a foldable, in degrees.
+
+`0` is closed and `180` is flat. `angle` is `null` when the device has no hinge sensor.
+
+| Prop        | Type                        | Description                                                    | Since |
+| ----------- | --------------------------- | -------------------------------------------------------------- | ----- |
+| **`angle`** | <code>number \| null</code> | Hinge angle in degrees, or `null` when no sensor is available. | 8.2.0 |
+
+
+#### SizeClass
+
+Window size classes.
+
+`horizontal` and `vertical` follow Apple's compact/regular split.
+On Android and web, `regular` starts at 600 CSS pixels wide and 480 tall.
+`widthClass` and `heightClass` follow Material window size classes.
+
+| Prop              | Type                                                                        | Description                                                                                                                               | Since |
+| ----------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`horizontal`**  | <code>'compact' \| 'regular'</code>                                         | Width size class. `compact` on a phone, `regular` on the inner display of a foldable, a tablet, or a window at least 600 CSS pixels wide. | 8.2.0 |
+| **`vertical`**    | <code>'compact' \| 'regular'</code>                                         | Height size class. `regular` starts at 480 CSS pixels.                                                                                    | 8.2.0 |
+| **`widthClass`**  | <code>'compact' \| 'medium' \| 'expanded' \| 'large' \| 'extraLarge'</code> | Material window width class.                                                                                                              | 8.2.0 |
+| **`heightClass`** | <code>'compact' \| 'medium' \| 'expanded'</code>                            | Material window height class.                                                                                                             | 8.2.0 |
+
+
 #### PluginListenerHandle
 
 | Prop         | Type                                      |
@@ -396,4 +597,29 @@ Orientation lock type that can be used to lock the device orientation.
 
 <code>'any' | 'natural' | 'landscape' | 'portrait' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary'</code>
 
+
+#### FoldStateValue
+
+How open a foldable is.
+
+`closed` is reserved. A device shut onto its cover display reports `flat`.
+
+<code>'flat' | 'half-opened'</code>
+
+
+#### FoldPosture
+
+How a half-open foldable is held.
+
+`tabletop` is a horizontal hinge, like a laptop. `book` is a vertical hinge.
+
+<code>'flat' | 'tabletop' | 'book'</code>
+
+
+#### HingeOrientation
+
+Direction of the hinge relative to the window.
+
+<code>'horizontal' | 'vertical'</code>
+
 </docgen-api>

package/android/build.gradle

@@ -3,6 +3,7 @@ ext {
     androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.1'
     androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
     androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+    androidxWindowVersion = project.hasProperty('androidxWindowVersion') ? rootProject.ext.androidxWindowVersion : '1.5.1'
 }
 
 buildscript {
@@ -52,6 +53,7 @@ dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
     implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
+    implementation "androidx.window:window-java:$androidxWindowVersion"
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"

package/android/src/main/java/ee/forgr/capacitor/screenorientation/CapacitorScreenOrientationPlugin.java

@@ -7,23 +7,60 @@ import android.hardware.Sensor;
 import android.hardware.SensorEvent;
 import android.hardware.SensorEventListener;
 import android.hardware.SensorManager;
+import android.os.Build;
+import android.os.Handler;
+import android.os.Looper;
 import android.view.Surface;
 import com.getcapacitor.JSObject;
 import com.getcapacitor.Plugin;
 import com.getcapacitor.PluginCall;
 import com.getcapacitor.PluginMethod;
 import com.getcapacitor.annotation.CapacitorPlugin;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.concurrent.Executor;
+import org.json.JSONObject;
 
 @CapacitorPlugin(name = "CapacitorScreenOrientation")
 public class CapacitorScreenOrientationPlugin extends Plugin implements SensorEventListener {
 
-    private final String pluginVersion = "8.1.20";
+    private final String pluginVersion = "8.2.0";
     private int currentOrientation;
     private SensorManager sensorManager;
     private Sensor accelerometer;
     private boolean isTrackingMotion = false;
     private String currentPhysicalOrientation = "portrait-primary";
     private String lastNotifiedOrientation = null;
+    private FoldLayout foldLayout;
+    private Sensor hingeSensor;
+    private boolean hingeRegistered = false;
+    private Float lastHingeAngle = null;
+    private String lastSizeClassKey = null;
+    private final List<PluginCall> pendingHingeCalls = new ArrayList<>();
+    private final Handler mainHandler = new Handler(Looper.getMainLooper());
+    private final SensorEventListener hingeListener = new SensorEventListener() {
+        @Override
+        public void onSensorChanged(SensorEvent event) {
+            if (event.values.length == 0) {
+                return;
+            }
+            float angle = Math.max(0f, Math.min(360f, event.values[0]));
+            boolean unchanged = lastHingeAngle != null && Math.abs(lastHingeAngle - angle) < 0.5f;
+            lastHingeAngle = angle;
+            if (unchanged && pendingHingeCalls.isEmpty()) {
+                return;
+            }
+            JSObject payload = hingePayload(angle);
+            notifyListeners("hingeAngleChange", payload);
+            resolvePendingHinge(payload);
+            if (!hasListeners("hingeAngleChange")) {
+                stopHingeTracking();
+            }
+        }
+
+        @Override
+        public void onAccuracyChanged(Sensor sensor, int accuracy) {}
+    };
 
     @Override
     public void load() {
@@ -34,12 +71,26 @@ public class CapacitorScreenOrientationPlugin extends Plugin implements SensorEv
         sensorManager = (SensorManager) getActivity().getSystemService(Context.SENSOR_SERVICE);
         if (sensorManager != null) {
             accelerometer = sensorManager.getDefaultSensor(Sensor.TYPE_ACCELEROMETER);
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
+                hingeSensor = sensorManager.getDefaultSensor(Sensor.TYPE_HINGE_ANGLE);
+            }
         }
+
+        Executor executor = mainHandler::post;
+        foldLayout = new FoldLayout(getActivity(), bridge.getWebView(), executor, (state) -> {
+            notifyListeners("foldStateChange", state);
+            notifySizeClassIfChanged();
+        });
+        notifySizeClassIfChanged();
     }
 
     @Override
     protected void handleOnDestroy() {
         stopMotionTracking();
+        stopHingeTracking();
+        if (foldLayout != null) {
+            foldLayout.stop();
+        }
         super.handleOnDestroy();
     }
 
@@ -47,6 +98,8 @@ public class CapacitorScreenOrientationPlugin extends Plugin implements SensorEv
     protected void handleOnConfigurationChanged(Configuration newConfig) {
         super.handleOnConfigurationChanged(newConfig);
 
+        notifySizeClassIfChanged();
+
         // Skip system orientation changes when motion tracking is active
         // to avoid duplicate events
         if (isTrackingMotion) {
@@ -59,6 +112,79 @@ public class CapacitorScreenOrientationPlugin extends Plugin implements SensorEv
         }
     }
 
+    @PluginMethod(returnType = PluginMethod.RETURN_NONE)
+    @Override
+    public void addListener(PluginCall call) {
+        super.addListener(call);
+        String eventName = call.getString("eventName");
+        if ("hingeAngleChange".equals(eventName)) {
+            mainHandler.post(this::startHingeTracking);
+        }
+    }
+
+    @PluginMethod(returnType = PluginMethod.RETURN_NONE)
+    @Override
+    public void removeListener(PluginCall call) {
+        super.removeListener(call);
+        if (!hasListeners("hingeAngleChange")) {
+            mainHandler.post(this::stopHingeTracking);
+        }
+    }
+
+    @PluginMethod
+    @Override
+    public void removeAllListeners(PluginCall call) {
+        super.removeAllListeners(call);
+        mainHandler.post(this::stopHingeTracking);
+    }
+
+    @PluginMethod
+    public void isDeviceFoldable(PluginCall call) {
+        JSObject result = new JSObject();
+        result.put("foldable", foldLayout != null && foldLayout.isFoldable());
+        result.put("supportsTabletop", foldLayout != null && foldLayout.supportsTabletop());
+        call.resolve(result);
+    }
+
+    @PluginMethod
+    public void getFoldState(PluginCall call) {
+        call.resolve(foldLayout == null ? flatFold() : foldLayout.currentState());
+    }
+
+    @PluginMethod
+    public void getHingeAngle(PluginCall call) {
+        mainHandler.post(() -> {
+            if (hingeRegistered && lastHingeAngle != null) {
+                call.resolve(hingePayload(lastHingeAngle));
+                return;
+            }
+            if (hingeSensor == null) {
+                call.resolve(hingePayload(null));
+                return;
+            }
+            pendingHingeCalls.add(call);
+            startHingeTracking();
+            mainHandler.postDelayed(
+                () -> {
+                    if (!pendingHingeCalls.contains(call)) {
+                        return;
+                    }
+                    pendingHingeCalls.remove(call);
+                    call.resolve(hingePayload(null));
+                    if (!hasListeners("hingeAngleChange") && pendingHingeCalls.isEmpty()) {
+                        stopHingeTracking();
+                    }
+                },
+                800
+            );
+        });
+    }
+
+    @PluginMethod
+    public void getSizeClass(PluginCall call) {
+        call.resolve(currentSizeClass());
+    }
+
     @PluginMethod
     public void orientation(final PluginCall call) {
         try {
@@ -198,6 +324,68 @@ public class CapacitorScreenOrientationPlugin extends Plugin implements SensorEv
         }
     }
 
+    private JSObject currentSizeClass() {
+        if (foldLayout != null) {
+            return foldLayout.sizeClass();
+        }
+        return FoldLayout.sizeClassOf(0f, 0f);
+    }
+
+    private void notifySizeClassIfChanged() {
+        JSObject sizeClass = currentSizeClass();
+        String key = sizeClass.toString();
+        if (key.equals(lastSizeClassKey)) {
+            return;
+        }
+        lastSizeClassKey = key;
+        notifyListeners("sizeClassChange", sizeClass);
+    }
+
+    private void startHingeTracking() {
+        if (hingeRegistered || hingeSensor == null || sensorManager == null) {
+            return;
+        }
+        hingeRegistered = true;
+        sensorManager.registerListener(hingeListener, hingeSensor, SensorManager.SENSOR_DELAY_NORMAL, mainHandler);
+    }
+
+    private void stopHingeTracking() {
+        if (!hingeRegistered || sensorManager == null) {
+            return;
+        }
+        hingeRegistered = false;
+        sensorManager.unregisterListener(hingeListener);
+    }
+
+    private void resolvePendingHinge(JSObject payload) {
+        if (pendingHingeCalls.isEmpty()) {
+            return;
+        }
+        List<PluginCall> pending = new ArrayList<>(pendingHingeCalls);
+        pendingHingeCalls.clear();
+        for (PluginCall call : pending) {
+            call.resolve(payload);
+        }
+    }
+
+    private static JSObject hingePayload(Float angle) {
+        JSObject result = new JSObject();
+        if (angle == null) {
+            result.put("angle", JSONObject.NULL);
+        } else {
+            result.put("angle", angle.doubleValue());
+        }
+        return result;
+    }
+
+    private static JSObject flatFold() {
+        JSObject state = new JSObject();
+        state.put("state", "flat");
+        state.put("isSeparating", false);
+        state.put("posture", "flat");
+        return state;
+    }
+
     // Motion tracking methods
     private void startMotionTracking() {
         if (isTrackingMotion || accelerometer == null) {