Feature Request: Expose iOS reserved regions / fold information to Cordova web content (for iPhone Duo)
- Dominant language
- JavaScript
- Stars
- 2.2k
- Forks
- 1k
- Avg merge
- 12h 11m
- Merged PRs (30d)
- 18
Description
# Feature Request
## Motivation Behind Feature
Apple has introduced iPhone Duo, its first foldable iPhone. When the device is partially folded, the center fold becomes a **reserved region** that applications should take into account when positioning important content and interactive controls.
Apple's guidance recommends avoiding important interactive content around the fold. In iOS 27.1, UIKit provides APIs to query these regions, for example:
```swift
let regions = view.reservedRegions(kind: .division)
let frames = regions.map(\.frame)
```
Reserved regions can represent:
* `.division` — such as the fold, which divides the available display area
* `.occlusion` — such as camera regions that can cover content
* Active and inactive regions, including the ability to query inactive regions using `includeInactive`
For native UIKit or SwiftUI applications, this information can therefore be used to adapt layouts around the fold.
However, Cordova applications render their UI inside `WKWebView`, and there does not appear to be a Cordova API that exposes these native reserved-region values to the web content.
Existing mechanisms such as viewport resizing and CSS safe-area insets are useful for adapting to different screen sizes and edge insets, but they do not provide the location/state of an internal fold region.
As a result, a Cordova application cannot reliably determine whether an important control or other manually positioned content overlaps the fold without implementing its own native Cordova plugin.
Flutter is discussing the equivalent problem in `flutter/flutter#192515`, where the proposal is to expose the new iOS reserved-region information through Flutter's existing cross-platform display-feature abstraction.
## Feature Description
Would it make sense for `cordova-ios` to provide a standard way for Cordova web applications to access the reserved regions reported by iOS 27.1+?
For example, Cordova could expose enough information for JavaScript to determine:
* the type of region (`division` / `occlusion`)
* its frame relative to the Cordova WebView
* whether the region is currently active
* optionally, inactive regions when supported by the platform
I am not proposing a specific JavaScript API here. Possible approaches could include:
1. Exposing the information through a Cordova JavaScript API/event.
2. Providing a bridge that allows the WebView layer to consume the native reserved-region information.
3. If this functionality is expected to become available directly through WebKit/Web standards, documenting that Cordova will rely on that mechanism instead.
4. Determining that this is better implemented as an official or community Cordova plugin rather than directly in `cordova-ios`.
The main goal is to avoid requiring every Cordova application targeting foldable iPhones to implement its own UIKit-to-JavaScript bridge for the same platform capability.
## Expected Behavior
Cordova applications running on iPhone Duo should have a supported mechanism to determine the location of active reserved regions, particularly the fold, so that web-based layouts can keep important or interactive UI elements away from those regions.
## Current Behavior
The Cordova WebView responds to changes in its available viewport and can use safe-area information, but Cordova web content has no standard API for obtaining the native iOS reserved regions.
Therefore, applications that require fold-aware layouts need to implement a custom native plugin/bridge.
## References
* Apple Developer — ["Design for iPhone Duo"](https://developer.apple.com/jp/videos/play/tech-talks/111466/)
* Apple Developer — ["Strike a pose with adaptive layouts on iPhone Duo"](https://developer.apple.com/videos/play/tech-talks/111463/)
* Flutter proposal: https://github.com/flutter/flutter/issues/192515
## Alternatives or Workarounds
Applications can implement a custom Cordova plugin that calls `UIView.reservedRegions(kind:)` and passes the resulting frames to JavaScript.
This should work, but every fold-aware Cordova application would need to implement essentially the same native bridge. A common solution at the Cordova/WebView layer would make support more consistent and easier to maintain.
Contributor guide
Research direction
Start by reviewing cordova-ios's existing viewport-resizing and safe-area handling, then compare the UIView.reservedRegions(kind:) data described in the issue with what Cordova web content can currently receive. Define the supported JavaScript event or bridge contract for region type, WebView-relative frame, and active state; done means a tested mechanism or a documented decision to rely on WebKit or a plugin.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- ios, javascript, swift
- Domain
- frontend, mobile
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100