Skip to content

feat(ios): place a UIKit close button in the iPhone Duo side rail - #1010

Closed
maxlapides wants to merge 5 commits into
lodev09:mainfrom
maxlapides:mlapides/mobile-1955-duo-side-rail
Closed

maxlapides wants to merge 5 commits into
lodev09:mainfrom
maxlapides:mlapides/mobile-1955-duo-side-rail

Conversation

@maxlapides

@maxlapides maxlapides commented Nov 7, 2026 •

Copy link
Copy Markdown
Contributor

Summary

On the iPhone Duo's folded cover screen, a sheet runs under the side rail with the camera, clock and wifi. System sheets put their close button in the rail, and below the clock at tall detents. A custom close button drawn in React Native had no way to get there.

This adds closeButton (iOS 27.1+), a close button that UIKit owns:

  • closeButton shows a UIBarButtonItem, and UIKit places it in the rail the way it places a system sheet's close button. UIKit also moves it when the rail changes.
  • closeButtonOptions.icon takes the name of an image in the app's asset catalog or of an SF Symbol, drawn as a template in the button's tint. closeButtonOptions.label sets its accessibility label.
  • onCloseButtonPress reports presses. The sheet stays presented, so the app dismisses it.
  • onCloseButtonVisibilityChange reports { visible } when the button starts or stops showing, so the app can draw its own close button while it's hidden, like on the unfolded screen. It starts hidden, fires only on a change, and doesn't fire mid-drag.
  • Navigator sheets get sheetCloseButtonPress and sheetCloseButtonVisibilityChange.

UIKit only moves bar items into a vertical bar from a navigation bar, and a sheet presented by True Sheet has none. So the sheet's controller adds a child navigation controller with an empty root view, hosted in a view above the content. The React Native content isn't moved into it. The host lets every touch through except the bar's items, and gives accessibility only those items. This needs the sheet's own view controller, which is why it lives in True Sheet rather than in a separate package.

True Sheet doesn't report the rail's geometry. A sheet that reaches the rail gets its width as a left or right safe-area inset, which react-native-safe-area-context already reports inside a sheet, so the docs pad content with its SafeAreaView. This replaces this PR's earlier onVerticalBarChange event. The approach builds on Aonan Li's exploration of a navigation-controller close button, credited as co-author.

The SideRailSheet example (Map screen → "Side Rail") uses closeButton with a custom icon and pads with SafeAreaView. The foldables ("Side Rail"), configuration, events, types and navigation docs, the truesheet-usage skill and the changelog are updated.

Known limitations:

  • When a sheet mounts as it presents, the app's own close button can show for a moment before onCloseButtonVisibilityChange reports the rail's button. The docs say so.
  • If UIKit ever lays the navigation bar out horizontally, the button hides and reports visible: false until the sheet settles or presents again. I couldn't reach that state on the simulator.
  • In an app that React Native lays out right to left, SafeAreaView pads the side away from the rail, because React Native treats left and right padding as start and end there. The docs show a useSafeAreaInsets workaround. The button itself is in the rail either way.

Type of Change

  • Bug fix
  • New feature
  • Breaking change
  • Documentation update

Test Plan

iPhone Duo simulator (iOS 27.2), bare example, cover screen:

  • Half detent: the button is in the rail beside the header. Full detent: it's below the clock and wifi, in about the same place as the system New Contact sheet's close button.
  • onCloseButtonVisibilityChange: present → one {visible: true} and the example hides its own ✕; unfold → {visible: false} and the ✕ shows; fold → {visible: true}; drags between detents → no events; re-present in the same posture → no event, button in the rail; present unfolded after a folded presentation → {visible: false}.
  • Pressing the button calls onCloseButtonPress, and the example dismisses.
  • With the button showing, a full-width content button gets taps in the content and in the rail column below the button.
  • A child sheet with closeButton gets its own button and events. The parent sends nothing while the child is up, even when the posture changes, and reports the current value once the child dismisses.
  • A sheet without closeButton shows nothing in the rail.
  • SafeAreaView edges={['left', 'right']} in the header and content keeps them clear of the rail on the cover screen, and adds nothing unfolded. With UIKit right to left and React Native left to right it pads the rail side; with both right to left it pads the other side (see limitations), and the documented useSafeAreaInsets workaround fixes the header.
  • From the previous round, with the button setup code unchanged since: an SF Symbol (chevron.down) and an asset-catalog image whose name isn't an SF Symbol both render tinted; turning closeButton off and on and changing the icon and label while presented update the button and its accessibility label; the accessibility tree has one close button, not UIKit's sheet-sized bar container.

Also:

  • yarn typecheck, yarn lint, Prettier, clang-format and yarn test (177) pass. The iOS example builds.
  • Android: the bare example builds (assembleDebug) with the regenerated codegen. The new props are no-ops on Android; not run on a device.

Not covered: a physical Duo, an iOS 27.1 runtime, a growing Live Activity, VoiceOver touch exploration, navigator sheets at runtime, reusing a recycled native view on the device (resetting its remembered visibility is checked against the source only).

Screenshots / Videos

iPhone Duo simulator (iOS 27.2). The first three are on the cover screen; the system sheet is the reference for the close button's position. The example uses a custom chevron.down icon.

System New Contact Half detent Full detent Unfolded
System New Contact sheet Half detent, close button in the side rail Full detent, close button below the clock Unfolded, the app draws its own close button

Checklist

  • I tested on iOS
  • I tested on Android
  • I tested on Web
  • I updated the documentation (if needed)
  • I added a changelog entry (if needed)

On the Duo's folded cover screen a sheet runs under the side rail, and system
sheets move their close button into the rail column, below the camera and clock
when the sheet is tall. Custom controls had no way to follow.

onVerticalBarChange (iOS 27.2+) reports the sheet's edge that holds the vertical
bar, in the sheet's React Native layout direction, how far the bar reaches in,
and the start, top and width where bar items go, from the sheet's top-start
corner. The controller reads UIKit's vertical bar trait and bar layout regions,
skipping drags, swipes, dismissals and stacked-behind passes. The host maps it
to the sheet's layout direction, drops duplicates and reports again on every
presentation. Navigator sheets get sheetVerticalBarChange.

Adds a Side Rail example sheet, docs and consumer skill updates.
@vercel

vercel Bot commented Nov 7, 2026

Copy link
Copy Markdown

@maxlapides is attempting to deploy a commit to the lodev09 Team on Vercel.

A member of the Team first needs to authorize it.

@maxlapides
maxlapides marked this pull request as ready for review November 7, 2026 02:12
@maxlapides
maxlapides marked this pull request as draft November 7, 2026 03:22
@lodev09

lodev09 commented Nov 7, 2026

Copy link
Copy Markdown
Owner

@maxlapides I don't think truesheet should be responsible for reporting this event. Isn't there any other package you can use for this?

Replace the reported bar geometry with a close button that UIKit owns. `closeButton` puts a
UIBarButtonItem in a hidden navigation controller hosted above the sheet's content, so UIKit
moves it into the vertical bar like a system sheet's, and moves it when the rail changes.
`closeButtonOptions` sets an asset catalog or SF Symbol icon and the accessibility label, and
`onCloseButtonPress` reports presses.

The host passes content touches through, and exposes only the bar's items to accessibility.
`onVerticalBarChange` now reports the rail's edge and inset for padding and whether the button
shows, so apps draw their own close button elsewhere. It needs the iOS 27.1 SDK and runtime.

Co-authored-by: Aonan Li <ali@brex.com>
@maxlapides maxlapides changed the title feat(ios): report the iPhone Duo side rail with onVerticalBarChange feat(ios): place a UIKit close button in the iPhone Duo side rail Nov 7, 2026
True Sheet no longer reports the iPhone Duo side rail. A sheet that reaches the rail gets its
width as a left or right safe-area inset, which react-native-safe-area-context already reports
inside a sheet, so `onVerticalBarChange` and `sheetVerticalBarChange` are removed and the docs
pad content with its `SafeAreaView`.

`onCloseButtonVisibilityChange` (navigator: `sheetCloseButtonVisibilityChange`) now reports
`{ visible }` when the UIKit close button starts or stops showing in the rail, so apps can draw
their own close button while it's hidden. It starts hidden and fires only on a change. A host
that Fabric recycles for a new mount forgets the last value, so the new mount isn't told about
a button from the previous one.

The Foldables guide notes that in an app React Native lays out right to left, `SafeAreaView`
pads the side away from the rail, and shows a `useSafeAreaInsets` workaround.
@maxlapides

Copy link
Copy Markdown
Contributor Author

@lodev09 Fair point, True Sheet shouldn't report the rail. I've removed onVerticalBarChange, and the docs now pad with its SafeAreaView.

But there is still one thing that I think we could use inside of True Sheet: closeButton, a native close button that UIKit places in the side rail the way it does for system sheets like New Contact, with a custom icon from the asset catalog or SF Symbols. I couldn't find a way to do that from outside True Sheet. UIKit only moves bar items into the rail from a navigation controller, and the sheet's view controller and its accessibility elements belong to True Sheet. You could think of it as native sheet chrome, like grabber. The only event left is onCloseButtonVisibilityChange, which reports True Sheet's own button, so an app can show its own close button where there's no rail, like on the unfolded screen. What do you think?

@maxlapides
maxlapides marked this pull request as ready for review November 10, 2026 21:05
@lodev09

lodev09 commented Nov 13, 2026

Copy link
Copy Markdown
Owner

@maxlapides Looking into this, I think we could properly support navigation bar as a separate component instead of doing a hidden navigation bar workaround for the close button. I did a POC #757 for a navigation bar before and scrapped it due to complexity -- I might revisit and create a separate component for it.

Closing this for now.

@lodev09 lodev09 closed this Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants