@capgo/capacitor-screen-orientation 8.1.21 → 8.3.0

package/README.md

@@ -20,10 +20,29 @@ 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
+- 📖 **iPhone Duo and Android foldables**: flat, book, or tabletop, hinge angle, which display is showing, and where iPhone Duo puts the tab bar
 - 🌐 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.
 
+## iPhone Duo
+
+iPhone Duo (iOS 27.1 or later) is a foldable iPhone. The same fold calls used on Android report it:
+
+| Pose | `posture` | Hinge |
+| --- | --- | --- |
+| Open flat, or closed on the outer display | `flat` | `180` open, `0` closed |
+| Held half-open like a book | `book` | vertical hinge, about `20`–`160` |
+| Propped half-open like a laptop | `tabletop` | horizontal hinge |
+
+Closed on the cover screen, the iPhone Duo simulator reports the outer display and a hinge at 0°:
+
+<img src="screenshots/ios-iphone-duo.webp" width="300" alt="iPhone Duo simulator closed on the cover screen, reporting flat, outer display, hinge 0 degrees">
+
+`activeDisplay` is `inner` on the large folding screen and `outer` on the cover screen. `getReservedRegions()` returns the fold (`division`) and anything covering the glass, such as the camera (`occlusion`). `getBarPlacement()` says whether iOS moved the tab bar to the side, and how wide that bar is.
+
+A regular iPhone, and iOS before 27.1, stays `flat` with no hinge angle. Android foldables report posture and hinge angle the same way. Rear display and dual-screen modes stay on Android.
+
 ## Documentation
 
 The most complete doc is available here: https://capgo.app/docs/plugins/screen-orientation/
@@ -131,6 +150,12 @@ await ScreenOrientation.stopOrientationTracking();
 
 // Remove listener
 await listener.remove();
+
+// iPhone Duo and Android foldables. Flat on phones that do not fold.
+const { posture, activeDisplay } = await ScreenOrientation.getFoldState();
+const { angle, status } = await ScreenOrientation.getHingeAngle();
+const { verticalBarEdge, inset } = await ScreenOrientation.getBarPlacement();
+const { widthClass } = await ScreenOrientation.getSizeClass();
 ```
 
 ## API
@@ -143,7 +168,17 @@ await listener.remove();
 * [`startOrientationTracking(...)`](#startorientationtracking)
 * [`stopOrientationTracking()`](#stoporientationtracking)
 * [`isOrientationLocked()`](#isorientationlocked)
+* [`isDeviceFoldable()`](#isdevicefoldable)
+* [`getFoldState()`](#getfoldstate)
+* [`getHingeAngle()`](#gethingeangle)
+* [`getReservedRegions()`](#getreservedregions)
+* [`getBarPlacement()`](#getbarplacement)
+* [`setVerticalBarBehavior(...)`](#setverticalbarbehavior)
+* [`getSizeClass()`](#getsizeclass)
 * [`addListener('screenOrientationChange', ...)`](#addlistenerscreenorientationchange-)
+* [`addListener('foldStateChange', ...)`](#addlistenerfoldstatechange-)
+* [`addListener('hingeAngleChange', ...)`](#addlistenerhingeanglechange-)
+* [`addListener('sizeClassChange', ...)`](#addlistenersizeclasschange-)
 * [`removeAllListeners()`](#removealllisteners)
 * [`getPluginVersion()`](#getpluginversion)
 * [Interfaces](#interfaces)
@@ -275,26 +310,207 @@ 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, on Android phones that do not fold, and on iOS except iPhone Duo (iOS 27.1 or later).
+
+**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
+
+--------------------
+
+
+### getReservedRegions()
+
+```typescript
+getReservedRegions() => Promise<{ regions: ReservedRegion[]; }>
+```
+
+Read the fold and anything covering the screen.
+
+iPhone Duo reports the fold, the vertical status bar area, and the under-display camera.
+Resolves to an empty list on Android, web, and iOS before 27.1.
+
+**Returns:** <code>Promise&lt;{ regions: ReservedRegion[]; }&gt;</code>
+
+**Since:** 8.2.0
+
+--------------------
+
+
+### getBarPlacement()
+
+```typescript
+getBarPlacement() => Promise<BarPlacement>
+```
+
+Read where iPhone Duo puts native tab bars and toolbars.
+
+`verticalBarEdge` is `null` when bars stay horizontal, and always on Android and web.
+
+**Returns:** <code>Promise&lt;<a href="#barplacement">BarPlacement</a>&gt;</code>
+
+**Since:** 8.2.0
+
+--------------------
+
+
+### setVerticalBarBehavior(...)
+
+```typescript
+setVerticalBarBehavior(options: { behavior: 'automatic' | 'disabled'; }) => Promise<{ applied: boolean; }>
+```
+
+Choose whether iPhone Duo may move this app's bars to the side.
+
+Resolves to `{ applied: false }` unless the app's bridge view controller opts in.
+Android and web always resolve to `{ applied: false }`.
+
+| Param         | Type                                                  | Description                                                              |
+| ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------ |
+| **`options`** | <code>{ behavior: 'automatic' \| 'disabled'; }</code> | `automatic` lets the system move bars. `disabled` keeps them horizontal. |
+
+**Returns:** <code>Promise&lt;{ applied: boolean; }&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> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+--------------------
+
+
+### addListener('foldStateChange', ...)
+
+```typescript
+addListener(eventName: 'foldStateChange', listenerFunc: (state: FoldState) => void) => Promise<PluginListenerHandle>
+```
+
+Listen for fold changes.
 
-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.
+On a foldable this also fires when the device rotates, because the hinge
+bounds rotate with the window.
 
-| 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. |
+| 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.
+On iOS this fires on iPhone Duo (iOS 27.1 or later). Never fires on web.
+
+| 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 +589,103 @@ 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, and iOS before 27.1, resolve to a flat state.
+iPhone Duo reports `book`, `tabletop`, or `flat`, and which display is in front.
+
+| 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 |
+| **`activeDisplay`**    | <code>'inner' \| 'outer'</code>                                            | Which display is showing the app on iPhone Duo. Omitted on Android, web, and iOS before 27.1.                       | 8.2.0 |
+| **`hingeMargins`**     | <code>{ top: number; right: number; bottom: number; left: number; }</code> | Space the system keeps clear around the fold, in CSS pixels. iPhone Duo reports 20 on each side of a vertical fold. | 8.2.0 |
+| **`cameraBounds`**     | <code>FoldBounds[]</code>                                                  | Areas covering the display, such as the iPhone Duo camera. Omitted when there are none.                             | 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 |
+| **`status`** | <code>'closed' \| 'partiallyOpen' \| 'fullyOpen' \| null</code> | How far open iPhone Duo is, as the system sees it. `null` on Android and web. | 8.2.0 |
+
+
+#### ReservedRegion
+
+A region the system reserves on iPhone Duo.
+
+`division` is the fold. `occlusion` is something covering the display, such as the camera.
+
+| Prop           | Type                                                                       | Description                                                                | Since |
+| -------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ----- |
+| **`kind`**     | <code>'division' \| 'occlusion'</code>                                     | What the region is.                                                        | 8.2.0 |
+| **`isActive`** | <code>boolean</code>                                                       | Whether the region applies right now. An inactive division is a flat fold. | 8.2.0 |
+| **`x`**        | <code>number</code>                                                        | Left edge, in CSS pixels.                                                  | 8.2.0 |
+| **`y`**        | <code>number</code>                                                        | Top edge, in CSS pixels.                                                   | 8.2.0 |
+| **`width`**    | <code>number</code>                                                        | Width in CSS pixels.                                                       | 8.2.0 |
+| **`height`**   | <code>number</code>                                                        | Height in CSS pixels.                                                      | 8.2.0 |
+| **`margins`**  | <code>{ top: number; right: number; bottom: number; left: number; }</code> | Space to keep clear around the region, in CSS pixels.                      | 8.2.0 |
+
+
+#### BarPlacement
+
+Where iPhone Duo places native bars.
+
+| Prop                  | Type                                         | Description                                                                           | Since |
+| --------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------- | ----- |
+| **`verticalBarEdge`** | <code>'leading' \| 'trailing' \| null</code> | The edge the system moves tab bars and toolbars to. `null` when they stay horizontal. | 8.2.0 |
+| **`inset`**           | <code>number</code>                          | How much room the vertical bar takes, in points. `0` when bars stay horizontal.       | 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 +709,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"