Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,8 +103,8 @@ or moving an ancestor does not trigger a measurement. On iOS, same-frame deliver
Readiness indicates a completed measurement, not a
universal first-frame guarantee.

The [performance guide](https://appandflow.github.io/react-native-reserved-regions/docs/performance)
explains provider placement and optional readiness gating.
The [Usage guide](https://appandflow.github.io/react-native-reserved-regions/docs/usage#wait-before-rendering)
shows how to wait for the first measurement before rendering content.

## Development

Expand Down
59 changes: 31 additions & 28 deletions website/docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,95 +3,98 @@ title: API reference
description: Provider, hook, and documented region types.
---

All public exports come from `react-native-reserved-regions`.
Import all exports from `react-native-reserved-regions`.

## ReservedRegionsProvider

Wrap the view you want to measure with `ReservedRegionsProvider`. It accepts React Native `ViewProps` and a ref to its native view.

```ts
function ReservedRegionsProvider(
props: ViewProps & { ref?: React.Ref<React.ComponentRef<typeof View>> },
props: ViewProps & {
ref?: React.Ref<React.ComponentRef<typeof View>>;
},
): React.JSX.Element;
```

A native view that supplies active reserved regions to descendants. It accepts React Native `ViewProps` and a `ref` to the native view, which you can use like a `View` ref, for example to call `measure`. Give it explicit dimensions or a layout style such as `flex: 1` so there is an area to measure.

Each provider maintains its own measurements. A nested provider replaces the context for its descendants.
Use the ref to call native view methods such as `measure`.

## ReservedRegionsGate

Wrap content with `ReservedRegionsGate` to mount it after the nearest provider completes its first measurement, including an empty result.

```ts
function ReservedRegionsGate(props: { children?: React.ReactNode }): React.ReactNode;
```

Renders `null` until the nearest provider has completed its first measurement,
then renders `children`, including for an empty result. It adds no native view and
does not suspend. Throws outside a provider, like `useReservedRegionsReady()`.
Keep the measured view mounted and sized outside the gate. See
[performance and first render](./performance.md) for placement and tradeoffs.
The gate adds no native view and does not use Suspense. Using it outside a provider throws an error.

See [Usage](./usage.md#wait-before-rendering) for an example.

## useReservedRegions

```ts
function useReservedRegions(): readonly ReservedRegion[];
```

Returns regions from the nearest provider, initially `[]`. Throws if there is no provider. The list has no guaranteed stable IDs or ordering. Treat both the array and its values as read-only.
Returns the regions from the nearest provider. Before the first measurement, it returns an empty array.

Treat the array and its values as read-only. Regions have no stable IDs or guaranteed order.

Calling the hook outside a provider throws an error.

## useReservedRegionsReady

```ts
function useReservedRegionsReady(): boolean;
```

Returns whether the nearest provider has reported its first measurement. Initially `false`, then `true` even when the measured region array is empty. Regions and readiness update together. It stays true for that provider's lifetime and resets for a newly mounted provider. Throws if there is no provider.
Returns `false` while the first measurement is pending and `true` when it completes, including when no regions are found.

Readiness does not indicate hardware support or guarantee first-visible-frame timing. An unsupported platform reports a known empty result. A provider without laid-out bounds remains pending; Android also waits for its first WindowManager result when a synchronous query is unavailable.
Readiness and regions update together. Readiness stays `true` until the provider unmounts. A new provider starts pending.

Calling the hook outside a provider throws an error.

## ReservedRegionFrame

Describes a region’s position and size.

```ts
/** Bounds in logical points relative to the nearest provider. Not clipped to the provider. */
type ReservedRegionFrame = Readonly<{
/** Horizontal distance from the provider's left edge. */
x: number;
/** Vertical distance from the provider's top edge. */
y: number;
/** Horizontal extent; can be zero for a vertical fold. */
width: number;
/** Vertical extent; can be zero for a horizontal fold. */
height: number;
}>;
```

A frame can extend past the provider's edges. Read [coordinate spaces](./coordinates.md) to get the visible part and for interaction-margin behavior.
`x` and `y` are measured from the provider’s left and top edges. `width` and `height` describe the region’s size.

See [Understanding regions](./coordinates.md) for units, zero-width or zero-height divisions, and frames that extend outside the provider.

## ReservedRegion

```ts
/** An active area reserved by the display or supported system UI. */
type ReservedRegion =
| Readonly<{
/** A seam, hinge, or fold dividing the usable display. */
kind: 'division';
/** Bounds in the provider's coordinate space. */
frame: ReservedRegionFrame;
/** True when content underneath this division is hidden. */
occludesContent: boolean;
}>
| Readonly<{
/** A reserved area where content is hidden, such as a cutout. */
kind: 'occlusion';
/** Bounds in the provider's coordinate space. */
frame: ReservedRegionFrame;
}>;
```

`kind` is a string-literal discriminant, not a runtime enum. `occludesContent` exists only on divisions: it distinguishes a visible fold from an occluding hinge. Occlusion regions already express hidden content and do not carry the boolean.
A division represents a fold or hinge. Use `occludesContent` to check whether content is hidden within its frame.

An occlusion represents an area where content is hidden. It has no `occludesContent` property.

Check `kind` before accessing properties specific to a region type.

```ts
function hidesContent(region: ReservedRegion): boolean {
return region.kind === 'occlusion' || region.occludesContent;
}
```

Currently iOS divisions always have `occludesContent: false`. Android derives it from `FoldingFeature.OcclusionType.FULL`. See [platform behavior](./platforms.md).
89 changes: 63 additions & 26 deletions website/docs/coordinates.md
Original file line number Diff line number Diff line change
@@ -1,45 +1,86 @@
---
title: Coordinate spaces
title: Understanding regions
description: Scope measurements to a screen, panel, or nested provider.
---

Every `frame` is expressed in **logical points relative to the nearest provider's top-left corner**. On Android, physical pixel measurements are converted to density-independent units before reaching JavaScript.
## What is a region?

| Field | Meaning |
| -------- | ------------------------------------------------ |
| `x` | Horizontal offset from the provider's left edge. |
| `y` | Vertical offset from the provider's top edge. |
| `width` | Horizontal extent of the region. |
| `height` | Vertical extent of the region. |
A region describes a part of the display that affects where you place content. The library reports two types: **divisions** and **occlusions**.

These are provider coordinates, not screen coordinates. A provider can occupy a whole screen or a smaller view.
### Divisions

## A provider inside a panel
A division marks a fold in a flexible screen or a hinge between two screens. Divisions are reported as `kind: 'division'`.

```tsx
<View style={{ flex: 1, padding: 24 }}>
<ReservedRegionsProvider style={{ flex: 1 }}>
<PanelContent />
</ReservedRegionsProvider>
</View>
Use `occludesContent` to check whether content is hidden in that area:

- `false`: content remains visible across the division.
- `true`: content is hidden within the division’s frame.

A division can have zero width or height. Keep these regions when calculating your layout; they still mark a boundary in the display.

Example of a fold that leaves content visible, using illustrative values:

```ts
{
kind: 'division',
occludesContent: false,
frame: { x: 400, y: 0, width: 0, height: 800 },
}
```

### Occlusions

An occlusion marks an area where content is hidden, such as a camera cutout or space reserved by the system.

Occlusions are reported as `kind: 'occlusion'`. They have no `occludesContent` flag because they already represent hidden content.

Example of a camera cutout, using illustrative values:

```ts
{
kind: 'occlusion',
frame: { x: 20, y: 20, width: 30, height: 30 },
}
```

`PanelContent` receives measurements relative to the inset provider. Do not subtract the surrounding padding a second time. If you render an absolute-positioned overlay, place it inside that provider so the overlay and region share an origin. Frames can extend past the provider, so wrap overlays in an absolute-fill `View` with `overflow: 'hidden'` to keep them within its bounds.
### Position and size

The provider is the view your app measures. Both region types include a `frame` describing their position and size relative to that view.

## Native geometry
```ts
const frame = {
x: 120,
y: 0,
width: 20,
height: 800,
};
```

A provider receives the regions that intersect its bounds. Regions outside the provider are omitted. Each included region keeps its full frame, not only the part inside the provider, so a frame can have a negative `x` or `y` or extend past the provider's width or height. A fold that spans the window keeps its full length even when the provider covers only part of it. A fold can have zero width or height and still be meaningful; do not discard line-shaped regions.
- `x`: distance from the provider’s left edge.
- `y`: distance from the provider’s top edge.
- `width` and `height`: the region’s size.

On Android, the library translates window-relative folding features and cutouts into provider coordinates. On iOS, UIKit performs the view-scoped query and the library forwards the returned frames. UIKit frames can include interaction margins around an obstruction, so they should not be interpreted as exact physical hardware outlines. See [Apple's reserved regions overview](https://developer.apple.com/videos/play/tech-talks/111463/).
All values use logical points. On Android, the library converts physical pixels to density-independent units.

To work with only the visible part, intersect a frame with the provider's size, for example from the provider's `onLayout`:
## Frames can extend outside the provider

The library includes regions that overlap the provider and returns their full frames. A frame can start outside the provider or extend past its edges.

For example, `y: -10` places the region’s top edge 10 points above the provider.

```ts
{ x: 0, y: -10, width: 20, height: 100 }
```

To draw only the part inside the provider, use `overflow: 'hidden'` on the overlay container. You can also calculate that portion using the provider’s size from `onLayout`.

```ts
import type { ReservedRegionFrame } from 'react-native-reserved-regions';

function visiblePart(frame: ReservedRegionFrame, provider: { width: number; height: number }): ReservedRegionFrame {
const x = Math.max(0, frame.x);
const y = Math.max(0, frame.y);

return {
x,
y,
Expand All @@ -49,8 +90,4 @@ function visiblePart(frame: ReservedRegionFrame, provider: { width: number; heig
}
```

The native platforms have different geometry sources. Avoid assuming identical rectangles for similarly shaped hardware across iOS and Android.

## Inspect the difference

The [example app](./example.md) lets you switch between a full-screen provider, a provider inset by 24 points, and a smaller content box. It displays the provider bounds, region frames, and safe area insets together.
On iOS, a frame may include extra space around an obstruction for touch interactions. It may be larger than the obstruction itself.
61 changes: 26 additions & 35 deletions website/docs/example.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,19 @@ title: Run the example
description: Compare full-screen and inset providers on a native device.
---

The repository includes a React Native `0.88.0-rc.1` app that imports the local library source. It includes `react-native-safe-area-context` to compare safe area insets and reserved region frames.
The example imports the local library source and displays reserved regions alongside safe area measurements.

## Install and launch

Use the Node.js and pnpm versions declared by the repository, along with the native tooling required by the example's React Native version.
Use the Node.js and pnpm versions declared in the repository. Set up Xcode for iOS or Android Studio for Android.

```sh
git clone https://github.com/appandflow/react-native-reserved-regions.git
cd react-native-reserved-regions
pnpm install
```

For iOS, install the example's Ruby and CocoaPods dependencies:
For iOS, install the Ruby and CocoaPods dependencies:

```sh
cd example
Expand All @@ -31,53 +31,44 @@ Start Metro:
pnpm --filter react-native-reserved-regions-example start
```

In another terminal at the repository root, launch a platform:
From another terminal at the repository root, launch iOS or Android:

```sh
pnpm --filter react-native-reserved-regions-example ios
# or
pnpm --filter react-native-reserved-regions-example android
```

Build with Xcode containing the iOS 27.1 SDK or later, and run on iOS 27.1 or later to inspect UIKit reserved regions. A build made with an older SDK has these features compiled out, even when installed on a newer runtime. The example adopts `UISceneDelegate` for the RN release candidate's iOS 27 compatibility; see [React Native issue #58606](https://github.com/react/react-native/issues/58606).
See [Getting Started](./installation.md) for platform requirements.

## Inspect provider bounds
## View the measurements

The bottom controls change the measured view:
| Color | Measurement |
| ------------ | --------------- |
| Blue | Provider bounds |
| Dashed green | Safe area edges |
| Orange | Divisions |
| Purple | Occlusions |

| Mode | Provider bounds |
| ----------- | --------------------------------------------------------------------------------------- |
| Full screen | Fills the root view. |
| Shift 40 | Fills the root view, moved 40 points right without changing its size. |
| Inset 24 | Insets top, left, and right by 24 points; leaves 100 points at the bottom for controls. |
| Content box | Uses the same side and bottom insets, with the top at 180 points. |
Zero-width or zero-height divisions are drawn as two-point lines so they remain visible. The text shows their original measurements.

Both providers occupy the blue rectangle. The dashed green outline marks safe area edges. Orange overlays show divisions; purple overlays show occlusions. A zero-width or zero-height division is drawn as a two-point line so it remains visible, while the text displays its native measurement.
The app displays Pending until measurement completes, then Ready. The example displays the regions reported by your device.

Move between modes to inspect how coordinates change and which regions overlap the provider. The displayed data comes from the native platform; the example does not inject mock regions.
## Change the provider bounds

## Folds and cutouts
| Mode | Layout |
| ----------- | ------------------------------------------------------------------------ |
| Full screen | Fills the root view |
| Shift 40 | Moves 40 points right without changing size |
| Inset 24 | Adds 24-point top and side insets, leaving 100 points below for controls |
| Content box | Uses the same side and bottom insets, with the top at 180 points |

On Android, use a foldable emulator profile and change its posture to exercise WindowManager features. Android also offers simulated display cutouts in Developer options. Available features depend on the selected device profile and system image.
Switch modes to compare which regions intersect the provider and how their coordinates change.

On iOS, use the supported simulator controls or a physical device to change the active display or posture. An outer-display screenshot alone does not establish fold-transition support.
## Test folds and cutouts

[Android: test display cutouts](https://developer.android.com/develop/ui/compose/system/test-cutouts) · [Android emulator controls](https://developer.android.com/studio/run/emulator)

## Library checks
On Android, use a foldable emulator profile and fold or unfold the device. Simulated cutouts are available in Developer options. Available features depend on the device profile and system image.

From the repository root:
On iOS, use supported simulator controls or fold or unfold the device.

```sh
pnpm run format:check
pnpm run lint
pnpm run typecheck
pnpm test
pnpm run build
```

## Measurement status

The example displays Pending until the first measurement, then Ready even when
there are no active regions. Compare these states with the overlays rather than
treating an empty array as evidence that measurement finished.
[Android: test display cutouts](https://developer.android.com/develop/ui/compose/system/test-cutouts) · [Android emulator controls](https://developer.android.com/studio/run/emulator)
Loading
Loading