Skip to content
Closed
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
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@

### 🎉 New features

- **iOS**: Added `closeButton` for the side rail of an iPhone Duo on iOS 27.1+. UIKit places the button in the rail, like the close button of a system sheet, and `closeButtonOptions` sets its icon from the app's asset catalog or SF Symbols. `onCloseButtonPress` reports presses, and `onCloseButtonVisibilityChange` reports when the button shows and hides. Navigator sheets get them as `sheetCloseButtonPress` and `sheetCloseButtonVisibilityChange`. ([#1010](https://github.com/lodev09/react-native-true-sheet/pull/1010) by [@maxlapides](https://github.com/maxlapides))
- Added `dimBlur` to blur the content behind the sheet instead of tinting it with `dimColor`. It takes the `backgroundBlur` styles and draws the matching iOS material's tint over the blur, so the dim looks the same on every platform. `dimOpacity` sets the blur intensity. Android blurs on Android 12 and later unless the system turns window blurs off, and only tints otherwise. ([#991](https://github.com/lodev09/react-native-true-sheet/pull/991) by [@VladyslavMartynov10](https://github.com/VladyslavMartynov10) and [@lodev09](https://github.com/lodev09))

### 🐛 Bug fixes
Expand All @@ -26,6 +27,7 @@

- Add a Dim Blur section to the Dimming guide, and the `truesheet-usage` skill now covers `dimBlur`. ([#991](https://github.com/lodev09/react-native-true-sheet/pull/991) by [@lodev09](https://github.com/lodev09))
- The docs and the `truesheet-usage` skill now say that iOS 27 ignores `UIDesignRequiresCompatibility` only in apps built with the iOS 27 SDK or later. ([#1009](https://github.com/lodev09/react-native-true-sheet/pull/1009) by [@idlework](https://github.com/idlework))
- Add a Side Rail section to the Foldables guide and a Side Rail example sheet, and the `truesheet-usage` skill now covers `closeButton` and `onCloseButtonVisibilityChange`. ([#1010](https://github.com/lodev09/react-native-true-sheet/pull/1010) by [@maxlapides](https://github.com/maxlapides))

## 4.0.1

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -263,6 +263,16 @@ class TrueSheetViewManager :
// iOS-specific prop - no-op on Android
}

@ReactProp(name = "closeButton", defaultBoolean = false)
override fun setCloseButton(view: TrueSheetView, value: Boolean) {
// iOS-specific prop - no-op on Android
}

@ReactProp(name = "closeButtonOptions")
override fun setCloseButtonOptions(view: TrueSheetView, options: ReadableMap?) {
// iOS-specific prop - no-op on Android
}

@ReactProp(name = "insetAdjustment")
override fun setInsetAdjustment(view: TrueSheetView, insetAdjustment: String?) {
view.setInsetAdjustment(insetAdjustment ?: "automatic")
Expand Down
58 changes: 57 additions & 1 deletion docs/content/docs/next/guides/foldables.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,60 @@ export const App = () => {
}
```

## Side Rail

The iPhone Duo keeps a vertical side rail on one edge of the screen. A sheet that reaches it, like a sheet on the cover screen, runs under the rail and gets the rail's width as a safe-area inset. System sheets move their close button into the rail.

Set [`closeButton`](../reference/configuration#closebutton) to do the same. UIKit places the button in the rail, below the camera and clock at tall detents, and moves it when the rail changes. Pressing it calls [`onCloseButtonPress`](../reference/events#onclosebuttonpress); dismiss the sheet there. Pick its icon with [`closeButtonOptions`](../reference/configuration#closebuttonoptions).

The button only exists in the rail. [`onCloseButtonVisibilityChange`](../reference/events#onclosebuttonvisibilitychange) reports when it shows and hides, so draw your own close button while it's hidden, like on the unfolded screen. The rail is a left or right safe-area inset of the sheet, so keep content clear of it with `SafeAreaView` from [`react-native-safe-area-context`](https://github.com/AppAndFlow/react-native-safe-area-context). Inside a sheet it reads the sheet's own safe area.

```tsx {1,4,10-13,15-17,20-22}
import { SafeAreaView } from 'react-native-safe-area-context'

export const App = () => {
const [closeButtonVisible, setCloseButtonVisible] = useState(false)
const sheet = useRef<TrueSheet>(null)

return (
<TrueSheet
ref={sheet}
closeButton
closeButtonOptions={{ icon: 'brand-close' }}
onCloseButtonPress={() => sheet.current?.dismiss()}
onCloseButtonVisibilityChange={(e) => setCloseButtonVisible(e.nativeEvent.visible)}
header={
<SafeAreaView edges={['left', 'right']}>
<Header right={!closeButtonVisible && <CloseButton />} />
</SafeAreaView>
}
>
<SafeAreaView edges={['left', 'right']}>
<Content />
</SafeAreaView>
</TrueSheet>
)
}
```

In an app that React Native lays out right to left, React Native treats left and right padding as start and end, so `SafeAreaView` pads the side away from the rail. There, read the insets with `useSafeAreaInsets` under a `SafeAreaProvider` inside the sheet, and pad start and end yourself:

```tsx
const insets = useSafeAreaInsets()
const railPadding = {
paddingStart: I18nManager.isRTL ? insets.right : insets.left,
paddingEnd: I18nManager.isRTL ? insets.left : insets.right,
}
```

The icon is the name of an image in your app's asset catalog or of an SF Symbol, drawn in the button's tint at its own size. UIKit draws the button around it. With a custom icon, set a localized `label` too.

The button starts hidden and shows while the sheet presents, so a sheet that mounts as it presents can show its own close button for a moment before `onCloseButtonVisibilityChange` reports the rail's button.

:::info
Requires iOS 27.1+ and an app built with the iOS 27.1 SDK or later. On Android, web, and earlier iOS versions, no button shows and `onCloseButtonVisibilityChange` never fires.
:::

## Navigation

`foldOptions` is a screen option in the [Sheet Navigator](navigation) and the Expo Router `Sheet` layout, like any other prop.
Expand All @@ -128,6 +182,8 @@ export const App = () => {
/>
```

`closeButton` and `closeButtonOptions` are screen options too. The button doesn't go back by itself, so listen to `sheetCloseButtonPress` and call `navigation.goBack()`.

## Testing on the Simulator

Use the **iPhone Duo** simulator on iOS 27.1+.
Expand All @@ -137,5 +193,5 @@ Use the **iPhone Duo** simulator on iOS 27.1+.
3. Half-fold the device to enter tabletop. Unfold it to leave.

:::tip
The example app's **TrueSheet View** sheet uses `foldOptions` with `hingeBehavior: 'snap'`.
The example app's **TrueSheet View** sheet uses `foldOptions` with `hingeBehavior: 'snap'`, and its **Side Rail** sheet uses `closeButton` with a custom icon. Show the side rail by folding the device closed.
:::
2 changes: 2 additions & 0 deletions docs/content/docs/next/guides/navigation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -328,6 +328,8 @@ function DetailsSheet() {
| `sheetDragChange` | User is dragging |
| `sheetDragEnd` | User stopped dragging |
| `sheetPositionChange` | Position changed |
| `sheetCloseButtonVisibilityChange` | `closeButton` started or stopped showing (iOS 27.1+) |
| `sheetCloseButtonPress` | `closeButton` pressed (iOS 27.1+). Call `navigation.goBack()` here |

See [Lifecycle Events](../reference/events) for more details.

Expand Down
24 changes: 24 additions & 0 deletions docs/content/docs/next/reference/configuration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -243,6 +243,30 @@ Requires iOS 27.1+ on a foldable.
In book posture (vertical fold), iOS already docks every sheet to one panel. Use [`placement`](#placement) to pick the side.
:::

## `closeButton`

Shows a close button that UIKit places in the sheet's vertical bar, like the side rail of an iPhone Duo, the way system sheets do. Nothing is drawn where the sheet has no vertical bar, so draw your own close button while [`onCloseButtonVisibilityChange`](events#onclosebuttonvisibilitychange) reports it hidden. Pressing it calls [`onCloseButtonPress`](events#onclosebuttonpress). See [Side Rail](../guides/foldables#side-rail).

| Type | Default | 🍎 | 🤖 | 🌐 |
| - | - | - | - | - |
| `boolean` | `false` | ✅ | | |

:::info
Requires iOS 27.1+.
:::

## `closeButtonOptions`

Options for the [`closeButton`](#closebutton).

| Type | Default | 🍎 | 🤖 | 🌐 |
| - | - | - | - | - |
| [`CloseButtonOptions`](types#closebuttonoptions) | | ✅ | | |

```tsx
<TrueSheet closeButton closeButtonOptions={{ icon: 'chevron.down', label: 'Dismiss' }} />
```

## `dismissible`

If set to `false`, the sheet will prevent interactive dismissal via dragging or clicking outside of it.
Expand Down
17 changes: 17 additions & 0 deletions docs/content/docs/next/reference/events.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,23 @@ This is called when the sheet has lost focus. This happens:

Useful for pausing updates or disabling interactions.

## `onCloseButtonVisibilityChange`

:::info[iOS 27.1+ only]
Requires an app built with the iOS 27.1 SDK or later.
:::

Comes with [`CloseButtonVisibilityChangeEventPayload`](types#closebuttonvisibilitychangeeventpayload).

This is called when the [`closeButton`](configuration#closebutton) starts or stops showing in the sheet's vertical bar, like the side rail of an iPhone Duo. That happens as the sheet presents, and on fold or rotation. The button starts hidden, so this first fires when it shows. It doesn't fire while the sheet is dragged; the value updates when the sheet settles. Don't rely on its order relative to `onWillPresent` and `onDidPresent`. See [Side Rail](../guides/foldables#side-rail).

## `onCloseButtonPress`

:::info[iOS 27.1+ only]
:::

This is called when the [`closeButton`](configuration#closebutton) is pressed. The sheet stays presented, so dismiss it here.

## `onBackPress`

:::info[Android only]
Expand Down
23 changes: 23 additions & 0 deletions docs/content/docs/next/reference/types.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -159,6 +159,15 @@ Options for foldables. They apply while the device is half-open with a horizonta
| `hingeDetentIndex` | `number` | The detent that rests on the hinge in tabletop, so the sheet fills the panel below it. In any other posture the detent keeps its own value. Other detents keep their values, so the sheet can still expand past the hinge unless `hingeBehavior` keeps it below. Lower detents stay below it and higher ones above it, so the detents keep their order. | |
| `hingeBehavior` | `'none' \| 'avoid' \| 'snap'` | How the sheet treats the hinge in tabletop. `'none'` lets detents cross it. `'avoid'` caps every detent at the hinge, so the sheet never crosses it. `'snap'` is like `'avoid'`, and also moves the sheet to `hingeDetentIndex` when the device enters tabletop, then back to its previous detent when it leaves, unless the sheet was moved off the hinge in between. Detents that reach above the hinge collapse onto it, so `'avoid'` works best with one detent above the hinge. | `'none'` |

## `CloseButtonOptions`

Options for the [`closeButton`](configuration#closebutton). Requires iOS 27.1+.

| Property | Type | Description | Default |
| - | - | - | - |
| `icon` | `string` | Name of an image in the app's asset catalog, or of an SF Symbol. It's drawn in the button's tint, like a template image. | The system close icon |
| `label` | `string` | Accessibility label of the button. | The system's label, or `'Close'` with a custom `icon` |

## `ContentInsetAdjustment`

What the sheet insets the bottom of a plugged scrollable's content for. Set via [`ScrollableOptions`](#scrollableoptions).
Expand Down Expand Up @@ -311,3 +320,17 @@ How far the sheet must be swiped down from its lowest detent to dismiss.
| position | `number` | The Y position of the sheet relative to the screen. |
| detent | `number` | The detent value (0-1) for the nearest detent index. |
| realtime | `boolean` | Whether the position is a real-time value (e.g., during drag or animation tracking). When `false`, position should be animated in JS. |

## `CloseButtonVisibilityChangeEventPayload`

`Object` that comes with the [`onCloseButtonVisibilityChange`](events#onclosebuttonvisibilitychange) event.

```tsx
{
visible: true
}
```

| Property | Type | Description |
| - | - | - |
| visible | `boolean` | Whether the [`closeButton`](configuration#closebutton) is showing. It keeps its last value between presentations. Draw your own close button while it's `false`. |
100 changes: 100 additions & 0 deletions example/shared/src/components/sheets/SideRailSheet.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
import { forwardRef, useImperativeHandle, useRef, useState, type Ref } from 'react';
import { Pressable, StyleSheet, Text } from 'react-native';
import { SafeAreaView } from 'react-native-safe-area-context';
import { TrueSheet, type TrueSheetProps } from '@lodev09/react-native-true-sheet';

import { DARK, DARK_GRAY, GAP, SPACING } from '../../utils';
import { DemoContent } from '../DemoContent';

interface SideRailSheetProps extends TrueSheetProps {}

const CLOSE_SIZE = 44;

export const SideRailSheet = forwardRef((props: SideRailSheetProps, ref: Ref<TrueSheet>) => {
const { onCloseButtonVisibilityChange, ...rest } = props;
const sheetRef = useRef<TrueSheet>(null);
const [closeButtonVisible, setCloseButtonVisible] = useState(false);

useImperativeHandle<TrueSheet | null, TrueSheet | null>(ref, () => sheetRef.current);

const dismiss = () => sheetRef.current?.dismiss();

return (
<TrueSheet
ref={sheetRef}
detents={[0.5, 1]}
backgroundColor={DARK}
closeButton
closeButtonOptions={{ icon: 'chevron.down' }}
onCloseButtonPress={dismiss}
header={
// The side rail is a left or right safe-area inset of the sheet
<SafeAreaView edges={['left', 'right']} style={styles.header}>
<Text style={styles.title}>Side Rail</Text>
{!closeButtonVisible && (
<Pressable
accessibilityLabel="Close"
accessibilityRole="button"
style={styles.close}
onPress={dismiss}
>
<Text style={styles.closeText}>✕</Text>
</Pressable>
)}
</SafeAreaView>
}
onCloseButtonVisibilityChange={(e) => {
console.log('[SideRailSheet] close button', JSON.stringify(e.nativeEvent));
setCloseButtonVisible(e.nativeEvent.visible);
onCloseButtonVisibilityChange?.(e);
}}
{...rest}
>
<SafeAreaView edges={['left', 'right']} style={styles.content}>
<Text style={styles.caption}>
Close button: {closeButtonVisible ? 'in the side rail' : 'drawn by the app'}
</Text>
<DemoContent color={DARK_GRAY} />
<DemoContent color={DARK_GRAY} />
</SafeAreaView>
</TrueSheet>
);
});

const styles = StyleSheet.create({
header: {
flexDirection: 'row',
alignItems: 'center',
justifyContent: 'space-between',
padding: SPACING,
minHeight: CLOSE_SIZE + SPACING * 2,
},
title: {
color: '#fff',
fontSize: 17,
fontWeight: '600',
},
close: {
width: CLOSE_SIZE,
height: CLOSE_SIZE,
borderRadius: CLOSE_SIZE / 2,
backgroundColor: DARK_GRAY,
alignItems: 'center',
justifyContent: 'center',
},
closeText: {
color: '#fff',
fontSize: 18,
},
content: {
paddingHorizontal: SPACING,
paddingBottom: SPACING,
gap: GAP,
},
caption: {
color: '#fff',
opacity: 0.6,
},
});

SideRailSheet.displayName = 'SideRailSheet';
1 change: 1 addition & 0 deletions example/shared/src/components/sheets/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -4,4 +4,5 @@ export * from './ScrollViewSheet';
export * from './FlatListSheet';
export * from './GestureSheet';
export * from './BlankSheet';
export * from './SideRailSheet';
export * from './NavigationSheet';
4 changes: 4 additions & 0 deletions example/shared/src/screens/MapScreen.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ import {
GestureSheet,
PromptSheet,
ScrollViewSheet,
SideRailSheet,
} from '../components/sheets';

const AnimatedButton = Animated.createAnimatedComponent(TouchableOpacity);
Expand Down Expand Up @@ -102,6 +103,7 @@ const MapScreenInner = ({
const scrollViewSheet = useRef<TrueSheet>(null);
const flatListSheet = useRef<TrueSheet>(null);
const gestureSheet = useRef<TrueSheet>(null);
const sideRailSheet = useRef<TrueSheet>(null);

const [anchorLeft, setAnchorLeft] = useState(false);
const [scrollViewLoading, setScrollViewLoading] = useState(false);
Expand Down Expand Up @@ -264,6 +266,7 @@ const MapScreenInner = ({
/>
<Button text="FlatList" onPress={() => flatListSheet.current?.present()} />
</ButtonGroup>
<Button text="Side Rail" onPress={() => sideRailSheet.current?.present()} />
<Spacer />
{showExtraContent && <DemoContent text="Extra content that changes height" />}
<ButtonGroup>
Expand All @@ -286,6 +289,7 @@ const MapScreenInner = ({
<ScrollViewSheet ref={scrollViewSheet} />
<FlatListSheet ref={flatListSheet} />
<GestureSheet ref={gestureSheet} />
<SideRailSheet ref={sideRailSheet} />
</ScrollView>
</ReanimatedTrueSheet>
</View>
Expand Down
14 changes: 14 additions & 0 deletions ios/TrueSheetView.mm
Original file line number Diff line number Diff line change
Expand Up @@ -374,6 +374,11 @@ - (void)updateProps:(Props::Shared const &)props oldProps:(Props::Shared const &
_insetAdjustment = newProps.insetAdjustment;
_controller.insetAdjustment = _insetAdjustment;

_controller.closeButton = newProps.closeButton;
_controller.closeButtonIcon = RCTNSStringFromStringNilIfEmpty(newProps.closeButtonOptions.icon);
_controller.closeButtonLabel = RCTNSStringFromStringNilIfEmpty(newProps.closeButtonOptions.label);
[_controller setupCloseButton];

[self setupScrollable];
}

Expand Down Expand Up @@ -467,6 +472,7 @@ - (void)prepareForRecycle {
}

[self cancelPendingPresent];
[_controller resetCloseButtonVisibility];

_lastStateSize = CGSizeZero;
_didInitiallyPresent = NO;
Expand Down Expand Up @@ -1153,6 +1159,14 @@ - (void)applySheetPropsUpdate {
[_controller setupDraggable];
}

- (void)viewControllerDidChangeCloseButtonVisibility:(BOOL)visible {
[TrueSheetStateEvents emitCloseButtonVisibilityChange:_eventEmitter visible:visible];
}

- (void)viewControllerDidPressCloseButton {
[TrueSheetStateEvents emitCloseButtonPress:_eventEmitter];
}

- (UIViewController *)findPresentingViewController {
if (!self.window)
return nil;
Expand Down
Loading
Loading