react-native-reserved-regions 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -13,11 +13,10 @@ Its iOS target adopts `UISceneDelegate` because the RC template currently crashe
 
 ## Installation
 
-`0.1.0-alpha.2` is the functional release candidate. Install the explicit version
-once publication is verified; until then, run the repository example.
+`0.1.0-alpha.3` is an alpha release; its API may still change.
 
 ```sh
-npm install react-native-reserved-regions@0.1.0-alpha.2
+npm install react-native-reserved-regions@0.1.0-alpha.3
 ```
 
 On iOS, install pods in your app's `ios` directory. Android links automatically through React Native autolinking.
@@ -69,6 +68,21 @@ type ReservedRegion =
 
 A division splits the available display. `occludesContent` tells you whether content under that division is hidden. An occlusion is an area where content is hidden. On iOS, division regions currently report `occludesContent: false`. The TypeScript declarations in `src/index.tsx` document every field.
 
+## Why a provider and a hook?
+
+A reserved region needs a coordinate space: the same fold has different local
+coordinates in a full-screen view and an inset panel. `ReservedRegionsProvider`
+renders the native view that defines those bounds and shares its measurements
+with descendants. `useReservedRegions()` reads the nearest provider, so several
+consumers can use the same measurements without each adding a native view. Place
+a provider around each area that needs its own coordinate space; it can replace
+an existing container `View`.
+
+[react-native-hinges](https://appandflow.github.io/react-native-hinges/docs/usage)
+exposes a hook without a provider because posture and angle do not depend on a
+child view's position or size. It observes the existing React root's hierarchy/window.
+Use both libraries when layout and animation need those separate inputs.
+
 ## Native sources
 
 - iOS queries UIKit's active `UIView` reserved division and occlusion regions on the provider view. Typed UIKit calls are guarded by the SDK version and runtime availability. Building with an SDK older than iOS 27.1 compiles out this feature. [Apple's reserved regions overview](https://developer.apple.com/videos/play/tech-talks/111463/)
@@ -96,6 +110,10 @@ Keeping the animated subtree mounted avoided this failure in the tested case;
 apps that gate its mount need to apply the patch, rebuild the native app, and
 validate it themselves.
 
+The [performance guide](https://appandflow.github.io/react-native-reserved-regions/docs/performance)
+explains provider placement and optional readiness gating. `ReservedRegionsGate`
+is included starting with `0.1.0-alpha.3`.
+
 ## Development
 
 ```sh

package/android/src/main/java/com/appandflow/reservedregions/ReservedRegionsView.kt

@@ -34,6 +34,7 @@ class ReservedRegionsView(context: Context) : ReactViewGroup(context), ViewTreeO
   private var foldingFeatures: List<FoldingFeature> = emptyList()
   private var foldingFeaturesReady = false
   private var lastRegions: List<ReservedRegion>? = null
+  private var awaitingFirstMount = true
   private var onRegionsChange: RegionsChangeHandler? = null
 
   override fun willDispatchViewUpdates(uiManager: UIManager) {}
@@ -45,13 +46,17 @@ class ReservedRegionsView(context: Context) : ReactViewGroup(context), ViewTreeO
   override fun didDispatchMountItems(uiManager: UIManager) {}
 
   override fun didMountItems(uiManager: UIManager) {
-    // Fabric installs event emitters after layout; its event beat runs before pre-draw.
-    updateRegions()
+    if (awaitingFirstMount) updateRegions()
   }
 
   override fun onAttachedToWindow() {
     super.onAttachedToWindow()
     uiManager = UIManagerHelper.getUIManagerForReactTag(UIManagerHelper.getReactContext(this), id)
+    awaitingFirstMount = true
+    // React Native's FabricMountingManager.cpp applies layout before installing a view's event
+    // emitter inside one mount batch, so onLayout cannot dispatch a synchronous event on first
+    // mount; didMountItems is the earliest point after the emitter exists and before the event
+    // beat. It runs for every mount batch in the app, so it is removed after the first delivery.
     uiManager?.addUIManagerEventListener(this)
     viewTreeObserver.addOnPreDrawListener(this)
     foldingFeatures = emptyList()
@@ -81,6 +86,11 @@ class ReservedRegionsView(context: Context) : ReactViewGroup(context), ViewTreeO
     super.onDetachedFromWindow()
   }
 
+  override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
+    super.onLayout(changed, left, top, right, bottom)
+    if (!awaitingFirstMount) updateRegions()
+  }
+
   override fun onPreDraw(): Boolean {
     updateRegions()
     return true
@@ -92,9 +102,9 @@ class ReservedRegionsView(context: Context) : ReactViewGroup(context), ViewTreeO
     invalidate()
   }
 
-  private fun updateRegions() {
-    val handler = onRegionsChange ?: return
-    if (!isAttachedToWindow || !foldingFeaturesReady || width == 0 || height == 0) return
+  private fun updateRegions(): Boolean {
+    val handler = onRegionsChange ?: return false
+    if (!isAttachedToWindow || !foldingFeaturesReady || width == 0 || height == 0) return false
 
     val windowLocation = IntArray(2)
     getLocationInWindow(windowLocation)
@@ -116,10 +126,14 @@ class ReservedRegionsView(context: Context) : ReactViewGroup(context), ViewTreeO
       }
     }
 
-    if (regions != lastRegions) {
-      lastRegions = regions
-      handler(this, regions)
+    if (regions == lastRegions) return false
+    lastRegions = regions
+    handler(this, regions)
+    if (awaitingFirstMount) {
+      awaitingFirstMount = false
+      uiManager?.removeUIManagerEventListener(this)
     }
+    return true
   }
 
   private fun clippedFrame(bounds: Rect, originX: Int, originY: Int): Rect? {

package/ios/ReservedRegionsView.mm

@@ -22,6 +22,17 @@ using namespace facebook::react;
   if (self = [super initWithFrame:frame]) {
     static const auto defaultProps = std::make_shared<const ReservedRegionsViewProps>();
     _props = defaultProps;
+#if defined(__IPHONE_27_1) && __IPHONE_OS_VERSION_MAX_ALLOWED >= __IPHONE_27_1
+    if (@available(iOS 27.1, *)) {
+      // UIKit posts no reserved-region change notification, so hinge updates schedule the re-query.
+      __weak __typeof(self) weakSelf = self;
+      UIHingeInteraction *hingeInteraction =
+          [[UIHingeInteraction alloc] initWithUpdateHandler:^(UIHingeInteraction *, UIHingeInteractionUpdate *) {
+            [weakSelf setNeedsLayout];
+          }];
+      [self addInteraction:hingeInteraction];
+    }
+#endif
   }
   return self;
 }

package/lib/module/index.js

@@ -70,4 +70,11 @@ export function useReservedRegionsReady() {
   }
   return snapshot.isReady;
 }
+
+/** Renders children after the nearest provider reports its first measurement. */
+export function ReservedRegionsGate({
+  children
+}) {
+  return useReservedRegionsReady() ? children : null;
+}
 //# sourceMappingURL=index.js.map

package/lib/module/index.js.map

@@ -1 +1 @@
-{"version":3,"names":["React","ReservedRegionsView","jsx","_jsx","ReservedRegionsContext","createContext","ReservedRegionsProvider","children","props","snapshot","setSnapshot","useState","regions","isReady","onRegionsChange","useCallback","event","nativeEvent","flatMap","region","kind","frame","occludesContent","Provider","value","useReservedRegions","useContext","Error","useReservedRegionsReady"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAAA,OAAO,KAAKA,KAAK,MAAM,OAAO;AAE9B,SAASC,mBAAmB,QAAQ,uBAAuB;;AAG3D;;AAYA;AAAA,SAAAC,GAAA,IAAAC,IAAA;AAsBA,MAAMC,sBAAsB,gBAAGJ,KAAK,CAACK,aAAa,CAAiC,IAAI,CAAC;;AAExF;AACA,OAAO,SAASC,uBAAuBA,CAAC;EAAEC,QAAQ;EAAE,GAAGC;AAAiB,CAAC,EAAqB;EAC5F,MAAM,CAACC,QAAQ,EAAEC,WAAW,CAAC,GAAGV,KAAK,CAACW,QAAQ,CAA0B;IAAEC,OAAO,EAAE,EAAE;IAAEC,OAAO,EAAE;EAAM,CAAC,CAAC;EACxG,MAAMC,eAAe,GAAGd,KAAK,CAACe,WAAW,CAAEC,KAA0C,IAAK;IACxF,MAAMJ,OAAO,GAAGI,KAAK,CAACC,WAAW,CAACL,OAAO,CAACM,OAAO,CAAEC,MAAM,IAAuB;MAC9E,IAAIA,MAAM,CAACC,IAAI,KAAK,UAAU,EAAE;QAC9B,OAAO,CAAC;UAAEA,IAAI,EAAE,UAAU;UAAEC,KAAK,EAAEF,MAAM,CAACE,KAAK;UAAEC,eAAe,EAAEH,MAAM,CAACG;QAAgB,CAAC,CAAC;MAC7F;MACA,IAAIH,MAAM,CAACC,IAAI,KAAK,WAAW,EAAE;QAC/B,OAAO,CAAC;UAAEA,IAAI,EAAE,WAAW;UAAEC,KAAK,EAAEF,MAAM,CAACE;QAAM,CAAC,CAAC;MACrD;MACA,OAAO,EAAE;IACX,CAAC,CAAC;IACFX,WAAW,CAAC;MAAEE,OAAO;MAAEC,OAAO,EAAE;IAAK,CAAC,CAAC;EACzC,CAAC,EAAE,EAAE,CAAC;EAEN,oBACEV,IAAA,CAACC,sBAAsB,CAACmB,QAAQ;IAACC,KAAK,EAAEf,QAAS;IAAAF,QAAA,eAC/CJ,IAAA,CAACF,mBAAmB;MAAA,GAAKO,KAAK;MAAEM,eAAe,EAAEA,eAAgB;MAAAP,QAAA,EAC9DA;IAAQ,CACU;EAAC,CACS,CAAC;AAEtC;;AAEA;AACA,OAAO,SAASkB,kBAAkBA,CAAA,EAA8B;EAC9D,MAAMhB,QAAQ,GAAGT,KAAK,CAAC0B,UAAU,CAACtB,sBAAsB,CAAC;EACzD,IAAIK,QAAQ,KAAK,IAAI,EAAE;IACrB,MAAM,IAAIkB,KAAK,CAAC,gEAAgE,CAAC;EACnF;EACA,OAAOlB,QAAQ,CAACG,OAAO;AACzB;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASgB,uBAAuBA,CAAA,EAAY;EACjD,MAAMnB,QAAQ,GAAGT,KAAK,CAAC0B,UAAU,CAACtB,sBAAsB,CAAC;EACzD,IAAIK,QAAQ,KAAK,IAAI,EAAE;IACrB,MAAM,IAAIkB,KAAK,CAAC,qEAAqE,CAAC;EACxF;EACA,OAAOlB,QAAQ,CAACI,OAAO;AACzB","ignoreList":[]}
+{"version":3,"names":["React","ReservedRegionsView","jsx","_jsx","ReservedRegionsContext","createContext","ReservedRegionsProvider","children","props","snapshot","setSnapshot","useState","regions","isReady","onRegionsChange","useCallback","event","nativeEvent","flatMap","region","kind","frame","occludesContent","Provider","value","useReservedRegions","useContext","Error","useReservedRegionsReady","ReservedRegionsGate"],"sourceRoot":"../../src","sources":["index.tsx"],"mappings":";;AAAA,OAAO,KAAKA,KAAK,MAAM,OAAO;AAE9B,SAASC,mBAAmB,QAAQ,uBAAuB;;AAG3D;;AAYA;AAAA,SAAAC,GAAA,IAAAC,IAAA;AAsBA,MAAMC,sBAAsB,gBAAGJ,KAAK,CAACK,aAAa,CAAiC,IAAI,CAAC;;AAExF;AACA,OAAO,SAASC,uBAAuBA,CAAC;EAAEC,QAAQ;EAAE,GAAGC;AAAiB,CAAC,EAAqB;EAC5F,MAAM,CAACC,QAAQ,EAAEC,WAAW,CAAC,GAAGV,KAAK,CAACW,QAAQ,CAA0B;IAAEC,OAAO,EAAE,EAAE;IAAEC,OAAO,EAAE;EAAM,CAAC,CAAC;EACxG,MAAMC,eAAe,GAAGd,KAAK,CAACe,WAAW,CAAEC,KAA0C,IAAK;IACxF,MAAMJ,OAAO,GAAGI,KAAK,CAACC,WAAW,CAACL,OAAO,CAACM,OAAO,CAAEC,MAAM,IAAuB;MAC9E,IAAIA,MAAM,CAACC,IAAI,KAAK,UAAU,EAAE;QAC9B,OAAO,CAAC;UAAEA,IAAI,EAAE,UAAU;UAAEC,KAAK,EAAEF,MAAM,CAACE,KAAK;UAAEC,eAAe,EAAEH,MAAM,CAACG;QAAgB,CAAC,CAAC;MAC7F;MACA,IAAIH,MAAM,CAACC,IAAI,KAAK,WAAW,EAAE;QAC/B,OAAO,CAAC;UAAEA,IAAI,EAAE,WAAW;UAAEC,KAAK,EAAEF,MAAM,CAACE;QAAM,CAAC,CAAC;MACrD;MACA,OAAO,EAAE;IACX,CAAC,CAAC;IACFX,WAAW,CAAC;MAAEE,OAAO;MAAEC,OAAO,EAAE;IAAK,CAAC,CAAC;EACzC,CAAC,EAAE,EAAE,CAAC;EAEN,oBACEV,IAAA,CAACC,sBAAsB,CAACmB,QAAQ;IAACC,KAAK,EAAEf,QAAS;IAAAF,QAAA,eAC/CJ,IAAA,CAACF,mBAAmB;MAAA,GAAKO,KAAK;MAAEM,eAAe,EAAEA,eAAgB;MAAAP,QAAA,EAC9DA;IAAQ,CACU;EAAC,CACS,CAAC;AAEtC;;AAEA;AACA,OAAO,SAASkB,kBAAkBA,CAAA,EAA8B;EAC9D,MAAMhB,QAAQ,GAAGT,KAAK,CAAC0B,UAAU,CAACtB,sBAAsB,CAAC;EACzD,IAAIK,QAAQ,KAAK,IAAI,EAAE;IACrB,MAAM,IAAIkB,KAAK,CAAC,gEAAgE,CAAC;EACnF;EACA,OAAOlB,QAAQ,CAACG,OAAO;AACzB;;AAEA;AACA;AACA;AACA;AACA,OAAO,SAASgB,uBAAuBA,CAAA,EAAY;EACjD,MAAMnB,QAAQ,GAAGT,KAAK,CAAC0B,UAAU,CAACtB,sBAAsB,CAAC;EACzD,IAAIK,QAAQ,KAAK,IAAI,EAAE;IACrB,MAAM,IAAIkB,KAAK,CAAC,qEAAqE,CAAC;EACxF;EACA,OAAOlB,QAAQ,CAACI,OAAO;AACzB;;AAEA;AACA,OAAO,SAASgB,mBAAmBA,CAAC;EAAEtB;AAAkC,CAAC,EAAmB;EAC1F,OAAOqB,uBAAuB,CAAC,CAAC,GAAGrB,QAAQ,GAAG,IAAI;AACpD","ignoreList":[]}

package/lib/typescript/src/index.d.ts

@@ -34,4 +34,6 @@ export declare function useReservedRegions(): readonly ReservedRegion[];
  * result. Remains true for that provider's lifetime; does not imply platform support.
  */
 export declare function useReservedRegionsReady(): boolean;
+/** Renders children after the nearest provider reports its first measurement. */
+export declare function ReservedRegionsGate({ children }: React.PropsWithChildren): React.ReactNode;
 //# sourceMappingURL=index.d.ts.map

package/lib/typescript/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,qFAAqF;AACrF,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,8CAA8C;IAC9C,CAAC,EAAE,MAAM,CAAC;IACV,6CAA6C;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GACtB,QAAQ,CAAC;IACP,sDAAsD;IACtD,IAAI,EAAE,UAAU,CAAC;IACjB,gEAAgE;IAChE,KAAK,EAAE,mBAAmB,CAAC;IAC3B,yDAAyD;IACzD,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC,GACF,QAAQ,CAAC;IACP,gEAAgE;IAChE,IAAI,EAAE,WAAW,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE,mBAAmB,CAAC;CAC5B,CAAC,CAAC;AASP,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAsB5F;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,IAAI,SAAS,cAAc,EAAE,CAM9D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAI9C,qFAAqF;AACrF,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC;IACzC,8CAA8C;IAC9C,CAAC,EAAE,MAAM,CAAC;IACV,6CAA6C;IAC7C,CAAC,EAAE,MAAM,CAAC;IACV,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAAC;AAEH,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GACtB,QAAQ,CAAC;IACP,sDAAsD;IACtD,IAAI,EAAE,UAAU,CAAC;IACjB,gEAAgE;IAChE,KAAK,EAAE,mBAAmB,CAAC;IAC3B,yDAAyD;IACzD,eAAe,EAAE,OAAO,CAAC;CAC1B,CAAC,GACF,QAAQ,CAAC;IACP,gEAAgE;IAChE,IAAI,EAAE,WAAW,CAAC;IAClB,iEAAiE;IACjE,KAAK,EAAE,mBAAmB,CAAC;CAC5B,CAAC,CAAC;AASP,sFAAsF;AACtF,wBAAgB,uBAAuB,CAAC,EAAE,QAAQ,EAAE,GAAG,KAAK,EAAE,EAAE,SAAS,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAsB5F;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,IAAI,SAAS,cAAc,EAAE,CAM9D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,OAAO,CAMjD;AAED,iFAAiF;AACjF,wBAAgB,mBAAmB,CAAC,EAAE,QAAQ,EAAE,EAAE,KAAK,CAAC,iBAAiB,GAAG,KAAK,CAAC,SAAS,CAE1F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-reserved-regions",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "Provider-scoped reserved display regions for React Native",
   "keywords": [
     "android",
@@ -137,6 +137,7 @@
     "lint:fix": "oxlint --fix .",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
+    "e2e:android": "node e2e/android.mjs",
     "docs:build": "pnpm --filter reserved-regions-docs build",
     "docs:start": "pnpm --filter reserved-regions-docs start"
   }

package/src/index.tsx

@@ -84,3 +84,8 @@ export function useReservedRegionsReady(): boolean {
   }
   return snapshot.isReady;
 }
+
+/** Renders children after the nearest provider reports its first measurement. */
+export function ReservedRegionsGate({ children }: React.PropsWithChildren): React.ReactNode {
+  return useReservedRegionsReady() ? children : null;
+}