docs: present during mount guide

README.md

@@ -34,9 +34,10 @@ cd ios && pod install
 
 ## Documentation
 
+- [Example](example)
 - [Guides](https://sheet.lodev09.com/category/guides)
 - [Reference](https://sheet.lodev09.com/category/reference)
-- [Example](example)
+- [Troubleshooting]((https://sheet.lodev09.com/troubleshooting))
 
 ## Usage
 

docs/docs/guides/dimming/dimming.mdx

@@ -1,5 +1,5 @@
 ---
-title: Dimming
+title: Dimming the Background
 description: Control the bottom sheet's dimming behavior.
 keywords: [bottom sheet dimming, bottom sheet background, inline bottom sheet, maps bottom sheet]
 ---

docs/docs/guides/jest.mdx

@@ -1,5 +1,5 @@
 ---
-title: Setup Jest
+title: Testing with Jest
 description: Mocking the bottom sheet component using Jest.
 keywords: [bottom sheet jest, testing bottom sheet, mocking bottom sheet]
 ---

docs/docs/guides/onmount/onmount.mdx

@@ -0,0 +1,37 @@
+---
+title: Presenting During Mount
+description: Present the bottom sheet on mount.
+keywords: [bottom sheet on mount, bottom sheet initialIndex]
+---
+
+import onmount from './onmount.gif'
+
+Sometimes, you may want to present the sheet directly during mount. For example, you might want to present the sheet when a screen is opened through a deep link.
+
+<img alt="onmount" src={onmount} width="300"/>
+
+## How?
+
+You can do this by setting [`initialIndex`](/reference/props#initialindex) prop. It accepts the [`size`](/reference/types#sheetsize) `index` that your sheet is configured with. See [sizes](/reference/props#sizes) prop for more information.
+
+```tsx {5-6}
+const App = () => {
+  return (
+    <TrueSheet
+      sizes={['auto', '69%', 'large']}
+      initialIndex={1}
+      initialindexanimated
+    >
+      <View />
+    </TrueSheet>
+  )
+}
+```
+
+### Disabling Animation
+
+You may want to disable the present animation. To do this, simply set [`initialIndexAnimated`](/reference/props#initialindexanimated) to `false`.
+
+### Using with React Navigation
+
+Using this with [`react-navigation`](https://reactnavigation.org) can cause render issue. Check out the [troubleshooting guide](/troubleshooting#present-during-mount) for the fix 😉.

docs/docs/guides/resizing/resizing.mdx

@@ -1,5 +1,5 @@
 ---
-title: Resizing
+title: Resizing Programmatically
 description: Programmatically resize the bottom sheet and listen for size changes.
 keywords: [bottom sheet resizing, bottom sheet sizes, bottom sheet auto resizing]
 ---

docs/docs/guides/scrolling.mdx

@@ -1,5 +1,5 @@
 ---
-title: Scrolling
+title: Scrolling Content
 description: Handle scrolling content within the bottom sheet.
 keywords: [bottom sheet scrolling, bottom sheet scrollview, bottom sheet flatlist]
 ---

docs/docs/guides/stacking/stacking.mdx

@@ -1,5 +1,5 @@
 ---
-title: Stacking
+title: Stacking Sheets
 description: Guide on how to present bottom sheet on top of an existing sheet.
 keywords: [bottom sheet stacking, multiple bottom sheets, parent bottom sheet, child bottom sheet]
 ---

docs/docs/troubleshooting.mdx

@@ -0,0 +1,100 @@
+---
+sidebar_position: 6
+description: Fix common issues when using True Native Bottom Sheet.
+keywords: [bottom sheet troubleshooting, fixing bottom sheet, debugging bottom sheet]
+---
+
+# Troubleshooting
+
+## React Native Gesture Handler
+
+[`react-native-gesture-handler`](https://docs.swmansion.com/react-native-gesture-handler/docs/)
+
+On Android, [RNGH does not work](https://docs.swmansion.com/react-native-gesture-handler/docs/fundamentals/installation/#usage-with-modals-on-android) by default because modals are not located under React Native Root view in native hierarchy. To fix that, components need to be wrapped with `GestureHandlerRootView`.
+
+```tsx
+import { GestureHandlerRootView } from 'react-native-gesture-handler'
+```
+
+```tsx
+return (
+  <TrueSheet ref={sheet}>
+    <GestureHandlerRootView>
+      <View />
+    </GestureHandlerRootView>
+  </TrueSheet>
+)
+```
+
+## React Navigation
+
+[`react-navigation`](https://reactnavigation.org)
+
+### Navigation Crash
+
+On IOS, navigating to a screen from within the Sheet can cause issues. To resolve this, dismiss the sheet before navigating!
+
+Example:
+```tsx
+const sheet = useRef<TrueSheet>(null)
+
+const navigate = async () => {
+  await sheet.current?.dismiss() // wait for the sheet to dismiss ✅
+  navigation.navigate('SomeScreen') // navigate to the screen 🎉
+}
+
+return (
+  <TrueSheet ref={sheet}>
+    <Button onPress={navigate} title="Navigate to SomeScreen" />
+    <View />
+  </TrueSheet>
+)
+```
+
+### Present during Mount
+
+On iOS, when setting [`initialIndex`](/reference/props#initialindex) and enabling `initialIndexAnimated` (default is `true`) to present during mount, the presentation animation becomes weird. This happens because RNN is not yet finished when the sheet is trying to present.
+
+To solve this, you can do the following:
+
+1. Set `initialIndexAnimated` to `false`. Disables animation during mount.
+
+```tsx
+return (
+  <TrueSheet initialIndex={0} initialIndexAnimated={false}>
+    <View />
+  </TrueSheet>
+)
+```
+
+2. Wait for the screen to fully transition. See [`transitionEnd`](https://reactnavigation.org/docs/native-stack-navigator/#transitionend) event.
+
+```tsx
+const navigation = useNavigation()
+const [isScreenShown, setIsScreenShown] = useState(false)
+
+// Subscribe to the transitionEnd event ✅
+useEffect(() => {
+  const unsubscribe = navigation.addListener("transitionEnd", ({ data }) => {
+    if (!data.closing) {
+      setIsScreenShown(true)
+    }
+  })
+
+  return unsubscribe
+}, [])
+
+// Wait for the screen to finish transitioning ✅
+if (!isScreenShown) return null
+
+// Finally show the sheet 🎉
+return (
+  <TrueSheet initialIndex={0} initialIndexAnimated>
+    <View />
+  </TrueSheet>
+)
+```
+
+## Weird layout render
+
+The sheet does not have control over how React Native renders components and may lead to rendering issues. To resolve this, try to minimize the use of `flex=1` in your content styles. Instead, use fixed `height` or employ `flexGrow`, `flexBasis`, etc., to manage your layout requirements.

example/package.json

@@ -16,7 +16,7 @@
     "expo": "~51.0.17",
     "expo-build-properties": "~0.12.3",
     "react": "18.2.0",
-    "react-native": "0.74.2",
+    "react-native": "0.74.3",
     "react-native-gesture-handler": "~2.16.1",
     "react-native-maps": "1.14.0",
     "react-native-reanimated": "~3.10.1"

example/src/App.tsx

@@ -45,7 +45,7 @@ export default function App() {
         dismissible={false}
         cornerRadius={12}
         initialIndex={1}
-        initialIndexAnimated={false}
+        // initialIndexAnimated={false}
         onMount={() => {
           // sheetRef.current?.present(1)
           console.log('Sheet is ready!')