@lodev09/react-native-true-sheet 4.0.0-beta.0 → 4.0.0-beta.10

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 lodev09
+Copyright (c) 2026 lodev09
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights

package/README.md

@@ -1,59 +1,90 @@
-# React Native True Sheet
+# React Native TrueSheet
 
-[![CI](https://github.com/lodev09/react-native-true-sheet/actions/workflows/ci.yml/badge.svg)](https://github.com/lodev09/react-native-true-sheet/actions/workflows/ci.yml)
+[![CI](https://github.com/lodev09/react-native-true-sheet/actions/workflows/checks.yml/badge.svg)](https://github.com/lodev09/react-native-true-sheet/actions/workflows/checks.yml)
 [![NPM Downloads](https://img.shields.io/npm/d18m/%40lodev09%2Freact-native-true-sheet)](https://www.npmjs.com/package/@lodev09/react-native-true-sheet)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/lodev09/react-native-true-sheet)
 
 The true native bottom sheet experience for your React Native Apps. 💩
 
-<img alt="React Native True Sheet - IOS" src="docs/static/img/preview.gif" width="300" height="600" /><img alt="React Native True Sheet - Android" src="docs/static/img/preview-2.gif" width="300" height="600" />
+<img alt="React Native True Sheet - iPad" src="docs/public/img/preview-ipad.gif" width="744" /><br>
+<img alt="React Native True Sheet - IOS" src="docs/public/img/preview-ios.gif" width="248" height="500" /><img alt="React Native True Sheet - Android" src="docs/public/img/preview-android.gif" width="248" height="500" /><img alt="React Native True Sheet - Web" src="docs/public/img/preview-web.gif" width="248" height="500" />
 
 ## Features
 
 * ⚡ **Powered by Fabric** - Built on React Native's new architecture for maximum performance
-* 🎯 **Type-safe** - Full TypeScript support with Codegen-generated native interfaces
-* 🚀 **Blazing fast** - Direct C++ communication, no bridge overhead
-* 🎨 **Native** - Implemented in the native realm
-* 🔄 **Imperative API** - Asynchronus `ref` [methods](https://sheet.lodev09.com/reference/methods#ref-methods)
+* 🚀 **Fully Native** - Implemented in the native realm, zero JS hacks
+* ♿ **Accessible** - Native accessibility and screen reader support out of the box
+* 🔄 **Flexible API** - Use [imperative methods](https://sheet.lodev09.com/reference/methods#ref-methods) or [lifecycle events](https://sheet.lodev09.com/reference/events)
+* ⌨️ **Keyboard Handling** - Built-in [keyboard handling](https://sheet.lodev09.com/guides/keyboard) with automatic adjustment
+* 📐 **Side Sheets** - Native [side sheet](https://sheet.lodev09.com/guides/side-sheets) support for iPad and Android tablets
+* 🪟 **Liquid Glass** - [iOS 26+ Liquid Glass](https://sheet.lodev09.com/guides/liquid-glass) support out of the box, featured in [Expo Blog](https://expo.dev/blog/how-to-create-apple-maps-style-liquid-glass-sheets)
+* 🐎 **Reanimated** - First-class support for [react-native-reanimated](https://sheet.lodev09.com/guides/reanimated)
+* 🧭 **React Navigation** - Built-in [sheet navigator](https://sheet.lodev09.com/guides/navigation) for seamless navigation integration
+* 🌐 **Web Support** - Full [web support](https://sheet.lodev09.com/guides/web) out of the box
+
+## 🎉 What's New in v4
+
+> [!TIP]
+> ✨ **v4 is in beta!** It rewrites the layout engine — the sheet now lays out synchronously per detent, so the container is sized to the sheet's visible height and tracks it in realtime while dragging.
+
+* 📏 **Synchronous layout** - Content resizes in the same frame as the sheet, no more lag
+* 📐 **`auto` detent with scrollables** - The sheet now sizes itself to a `ScrollView`/`FlatList`'s content height
+* 📜 **`scrollableRef`** - Pass a `ScrollView`/`FlatList` ref to wire nested scrolling, keyboard insets, and `auto` detent sizing
+* 🦶 **Relative footers** - Footers take up space below the content by default
+* 🧭 **Expo Router** - First-class support via the `Sheet` layout from `/navigation/expo-router`
+* 🍞 **`TrueSheetOverlay`** - Render toasts, dialogs, and other [overlays above your sheets](https://sheet.lodev09.com/guides/overlays) — no more `FullWindowOverlay`/`Modal` workarounds
+* 🔍 **Element inspector** - React Native's dev menu inspector now works inside a presented sheet
+
+```sh
+npx expo install @lodev09/react-native-true-sheet@beta
+```
+
+See the [Migration Guide](docs/docs/migration.mdx) to upgrade. **v3 is still supported** for React Native 0.81+ and remains the `latest` release on npm.
 
 ## Installation
 
 > [!IMPORTANT]
 > **Version 3.0+ requires React Native's New Architecture (Fabric)**
-> For the old architecture, use version 2.x. See the [Migration Guide (v2 → v3)](https://sheet.lodev09.com/migration) for upgrading.
+> For the old architecture, use version 2.x. See the [Migration Guide](https://sheet.lodev09.com/migration) for upgrading.
 
 ### Prerequisites
 
-- React Native >= 0.81
-- New Architecture enabled (`RCT_NEW_ARCH_ENABLED=1` for iOS, `newArchEnabled=true` for Android)
+- React Native 0.82+ (0.81+ on v3)
+- New Architecture enabled
+- Xcode 26.1+
 
-### Install
+### Compatibility
+
+| TrueSheet  | React Native | Expo SDK |
+|------------|--------------|----------|
+| 4.0+       | 0.82+        | 55+      |
+| 3.7 - 3.11 | 0.81+        | 54+      |
+| 3.6        | 0.80         | 52-53    |
+
+### Expo
 
 ```sh
-yarn add @lodev09/react-native-true-sheet
-```
-```sh
-npm i @lodev09/react-native-true-sheet
+npx expo install @lodev09/react-native-true-sheet
 ```
 
-### iOS Setup
+### Bare React Native
 
 ```sh
+yarn add @lodev09/react-native-true-sheet
 cd ios && pod install
 ```
 
-> **Note:** If you need old architecture support, use version 2.x:
-> ```sh
-> yarn add @lodev09/react-native-true-sheet@^2.0.0
-> ```
+These install v3. For v4, append `@beta` — see [🎉 What's New in v4](#-whats-new-in-v4).
 
 ## Documentation
 
 - [Example](example)
-- [Guides](https://sheet.lodev09.com/category/guides)
-- [Reference](https://sheet.lodev09.com/category/reference)
-- [Migration Guide (v2 → v3)](https://sheet.lodev09.com/migration)
+- [Configuration](https://sheet.lodev09.com/reference/configuration)
+- [Lifecycle Events](https://sheet.lodev09.com/reference/events)
+- [React Navigation](https://sheet.lodev09.com/guides/navigation)
 - [Troubleshooting](https://sheet.lodev09.com/troubleshooting)
 - [Testing with Jest](https://sheet.lodev09.com/guides/jest)
+- [Migrating to v3](https://sheet.lodev09.com/migration-v3)
 
 ## Usage
 
@@ -81,7 +112,6 @@ export const App = () => {
       <TrueSheet
         ref={sheet}
         detents={['auto', 1]}
-        cornerRadius={24}
       >
         <Button onPress={dismiss} title="Dismiss" />
       </TrueSheet>
@@ -90,17 +120,19 @@ export const App = () => {
 }
 ```
 
-## Testing
+## AI Skills
 
-TrueSheet includes built-in Jest mocks for easy testing. Simply mock the package in your tests:
+Skills are reusable AI capabilities that give your AI coding agent knowledge about TrueSheet. With the right skill loaded, your agent can pick the right patterns, avoid common mistakes, and generate correct code without you having to explain the library every time.
 
-```tsx
-jest.mock('@lodev09/react-native-true-sheet');
+```sh
+npx skills add lodev09/react-native-true-sheet
 ```
 
-All methods (`present`, `dismiss`, `resize`) are mocked as Jest functions, allowing you to test your components without native dependencies.
+This will install the **TrueSheet Usage** skill into your project.
+
+## That map is awesome!
 
-**[Full Testing Guide](https://sheet.lodev09.com/guides/jest)**
+Yes it is! Checkout [`@lugg/maps`](https://github.com/lugg/maps), a universal maps library for React Native that I'm developing at [Lugg](https://lugg.com).
 
 ## Contributing
 

package/RNTrueSheet.podspec

@@ -10,11 +10,19 @@ Pod::Spec.new do |s|
   s.license      = package["license"]
   s.authors      = package["author"]
 
-  s.platforms    = { :ios => min_ios_version_supported }
+  s.platforms    = { :ios => min_ios_version_supported, :tvos => min_ios_version_supported }
   s.source       = { :git => "https://github.com/lodev09/react-native-true-sheet.git", :tag => "#{s.version}" }
 
-  s.source_files = "ios/**/*.{h,m,mm,swift,cpp}"
+  # tvOS compiles stubs only — sheets are not supported there, but codegen
+  # still registers the components so the classes must exist (#722)
+  s.ios.source_files = "ios/**/*.{h,m,mm,swift,cpp}", "common/cpp/**/*.{cpp,h}"
+  s.ios.exclude_files = "ios/tvos/**/*"
+  s.tvos.source_files = "ios/tvos/**/*.mm", "common/cpp/**/*.{cpp,h}"
   s.private_header_files = "ios/**/*.h"
 
+  s.pod_target_xcconfig = {
+    "HEADER_SEARCH_PATHS" => "\"$(PODS_TARGET_SRCROOT)/common/cpp\""
+  }
+
   install_modules_dependencies(s)
 end

package/android/build.gradle

@@ -17,7 +17,28 @@ buildscript {
 
 
 apply plugin: "com.android.library"
-apply plugin: "kotlin-android"
+// Android Gradle Plugin 9 ships built-in Kotlin support and applies the Kotlin
+// plugin itself. Applying it a second time fails the configuration phase with
+// "Cannot add extension with name 'kotlin'". Apply it only when AGP is not
+// providing Kotlin: AGP 8 and older, or AGP 9 with android.builtInKotlin=false.
+def shouldApplyKotlinPlugin() {
+  def agpMajor = com.android.Version.ANDROID_GRADLE_PLUGIN_VERSION.tokenize('.')[0].toInteger()
+  if (agpMajor <= 8) {
+    return true
+  }
+  // AGP 10 removes the opt-out: built-in Kotlin is always active there.
+  if (agpMajor >= 10) {
+    return false
+  }
+  def propertyVal = providers.gradleProperty("android.builtInKotlin").orNull
+  def builtInKotlinEnabled = propertyVal != null ? propertyVal.toBoolean() : true
+  return !builtInKotlinEnabled
+}
+
+if (shouldApplyKotlinPlugin()) {
+  apply plugin: "kotlin-android"
+}
+
 apply plugin: "com.facebook.react"
 
 def getExtOrIntegerDefault(name) {
@@ -96,10 +117,11 @@ repositories {
 }
 
 def kotlin_version = getExtOrDefault("kotlinVersion")
+def material_version = getExtOrDefault("materialVersion") ?: "1.12.0"
 
 dependencies {
   implementation "com.facebook.react:react-android"
   implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
-  implementation "com.google.android.material:material:1.12.0"
+  implementation "com.google.android.material:material:$material_version"
 }
 

package/android/src/main/java/com/lodev09/truesheet/TrueSheetContainerView.kt

@@ -2,107 +2,249 @@ package com.lodev09.truesheet
 
 import android.annotation.SuppressLint
 import android.view.View
-import androidx.core.view.isNotEmpty
+import android.view.ViewGroup
 import com.facebook.react.uimanager.ThemedReactContext
+import com.facebook.react.uimanager.events.EventDispatcher
+import com.facebook.react.util.RNLog
 import com.facebook.react.views.view.ReactViewGroup
 
-/**
- * Delegate interface for container view changes
- */
 interface TrueSheetContainerViewDelegate {
+  val eventDispatcher: EventDispatcher?
   fun containerViewContentDidChangeSize(width: Int, height: Int)
+  fun containerViewContentDidScroll()
+  fun containerViewScrollViewDidChange()
+  fun containerViewHeaderDidChangeSize(width: Int, height: Int)
   fun containerViewFooterDidChangeSize(width: Int, height: Int)
+  fun containerViewPeekDidChangeSize(width: Int, height: Int)
 }
 
 /**
- * Container view that manages the bottom sheet content and holds content and footer views.
- * Simplified to be a lightweight content manager - events are now handled via dialog delegate.
+ * Container view that manages the sheet's content, header, and footer views.
+ * Size changes are forwarded to the delegate for sheet reconfiguration.
  */
 @SuppressLint("ViewConstructor")
-class TrueSheetContainerView(private val reactContext: ThemedReactContext) :
+class TrueSheetContainerView(reactContext: ThemedReactContext) :
   ReactViewGroup(reactContext),
   TrueSheetContentViewDelegate,
-  TrueSheetFooterViewDelegate {
+  TrueSheetHeaderViewDelegate,
+  TrueSheetFooterViewDelegate,
+  TrueSheetPeekViewDelegate {
 
   var delegate: TrueSheetContainerViewDelegate? = null
 
+  var contentView: TrueSheetContentView? = null
+  var headerView: TrueSheetHeaderView? = null
+  var footerView: TrueSheetFooterView? = null
+  var peekView: TrueSheetPeekView? = null
+
+  var contentHeight: Int = 0
+  var headerHeight: Int = 0
+  var footerHeight: Int = 0
+
   /**
-   * Reference to content view (first child)
+   * Distance from the top of the content view to the bottom of the peek view.
+   * Includes the peek view's offset within the content (padding, views above it)
+   * so the peek detent reveals everything down to the peek content's bottom edge.
    */
-  val contentView: TrueSheetContentView?
-    get() = if (isNotEmpty() && getChildAt(0) is TrueSheetContentView) {
-      getChildAt(0) as TrueSheetContentView
-    } else {
-      null
+  val peekContentHeight: Int
+    get() {
+      val peek = peekView ?: return 0
+      val content = contentView ?: return peek.height
+
+      var bottom = peek.height
+      var view: View = peek
+      while (view !== content) {
+        bottom += view.top
+        view = view.parent as? View ?: return peek.height
+      }
+
+      return bottom
     }
 
+  var absoluteFooter: Boolean = false
+
   /**
-   * Reference to footer view (second child)
+   * Bottom safe-area inset the footer absorbs as padding — the footer
+   * owns the sheet's bottom edge, so its background fills the inset.
    */
-  val footerView: TrueSheetFooterView?
-    get() = if (childCount > 1 && getChildAt(1) is TrueSheetFooterView) {
-      getChildAt(1) as TrueSheetFooterView
-    } else {
-      null
+  var footerBottomInset: Int = 0
+    set(value) {
+      field = value
+      footerView?.setBottomInset(value)
+    }
+  var scrollableOptions: ScrollableOptions? = null
+    set(value) {
+      field = value
+      contentView?.scrollableOptions = value
     }
 
-  /**
-   * The content view height
-   */
-  val contentHeight: Int
-    get() = contentView?.height ?: 0
+  // React tag of the user-provided scrollable within the content (see the scrollableRef prop)
+  var scrollableHandle: Int = -1
+    set(value) {
+      field = value
+      contentView?.scrollableHandle = value
+    }
 
   /**
-   * The footer view height
+   * Bottom safe-area inset the plugged scrollable applies as content padding
+   * while it can scroll (see ScrollableOptions.contentInsetAdjustment)
    */
-  val footerHeight: Int
-    get() = footerView?.height ?: 0
+  var scrollableBottomInset: Int = 0
+    set(value) {
+      field = value
+      contentView?.bottomInset = value
+    }
+
+  override val eventDispatcher: EventDispatcher?
+    get() = delegate?.eventDispatcher
 
   init {
-    // Container should not clip children to allow footer to position absolutely
+    // Allow footer to position outside container bounds
     clipChildren = false
     clipToPadding = false
   }
 
+  fun setupScrollable() {
+    contentView?.setupScrollable()
+  }
+
+  fun setupKeyboardHandler() {
+    contentView?.setupKeyboardHandler()
+  }
+
+  fun cleanupKeyboardHandler() {
+    contentView?.cleanupKeyboardHandler()
+  }
+
   override fun addView(child: View?, index: Int) {
     super.addView(child, index)
 
-    // Set up delegate when content view is added
-    if (child is TrueSheetContentView) {
-      child.delegate = this
+    when (child) {
+      is TrueSheetContentView -> {
+        child.delegate = this
+        child.scrollableOptions = scrollableOptions
+        child.scrollableHandle = scrollableHandle
+        child.bottomInset = scrollableBottomInset
+        contentView = child
+
+        // State lands before the view is attached, so pull the current value
+        contentHeight = child.naturalHeight
+
+        // Children mount bottom-up, so the content subtree is complete here.
+        // Late-mounted peek views attach themselves instead (see TrueSheetPeekView).
+        findPeekView(child)?.let { attachPeekView(it) }
+      }
+
+      is TrueSheetHeaderView -> {
+        child.delegate = this
+        headerView = child
+      }
+
+      is TrueSheetFooterView -> {
+        child.delegate = this
+        child.setBottomInset(footerBottomInset)
+        footerView = child
+      }
     }
+  }
 
-    // Set up delegate when footer view is added
-    if (child is TrueSheetFooterView) {
-      child.delegate = this
+  override fun removeViewAt(index: Int) {
+    when (val view = getChildAt(index)) {
+      is TrueSheetContentView -> {
+        view.delegate = null
+        contentView = null
+        contentViewDidChangeSize(0, 0)
+      }
+
+      is TrueSheetHeaderView -> {
+        view.delegate = null
+        headerView = null
+        headerViewDidChangeSize(0, 0)
+      }
+
+      is TrueSheetFooterView -> {
+        view.delegate = null
+        footerView = null
+        footerViewDidChangeSize(0, 0)
+      }
     }
+
+    super.removeViewAt(index)
   }
 
-  override fun removeView(view: View?) {
-    // Clean up delegate when content view is removed
-    if (view is TrueSheetContentView) {
-      view.delegate = null
+  // ==================== Peek View ====================
+
+  private fun findPeekView(view: View): TrueSheetPeekView? {
+    if (view is TrueSheetPeekView) return view
+
+    if (view is ViewGroup) {
+      for (i in 0 until view.childCount) {
+        findPeekView(view.getChildAt(i))?.let { return it }
+      }
     }
 
-    // Clean up delegate when footer view is removed
-    if (view is TrueSheetFooterView) {
-      view.delegate = null
+    return null
+  }
+
+  fun attachPeekView(view: TrueSheetPeekView) {
+    if (peekView === view) return
+
+    if (peekView != null) {
+      RNLog.w(context as ThemedReactContext, "TrueSheet: Sheet can only have one peek component.")
+      return
     }
 
-    super.removeView(view)
+    peekView = view
+    view.delegate = this
+    peekViewDidChangeSize(view.width, view.height)
   }
 
-  // ==================== TrueSheetContentViewDelegate Implementation ====================
+  fun detachPeekView(view: TrueSheetPeekView) {
+    if (peekView !== view) return
+
+    view.delegate = null
+    peekView = null
+    peekViewDidChangeSize(0, 0)
+  }
+
+  // ==================== Delegate Implementations ====================
 
   override fun contentViewDidChangeSize(width: Int, height: Int) {
-    // Forward content size changes to controller for sheet resizing
+    contentHeight = height
     delegate?.containerViewContentDidChangeSize(width, height)
   }
 
-  // ==================== TrueSheetFooterViewDelegate Implementation ====================
+  override val footerKeyboardOcclusion: Int
+    get() = if (absoluteFooter) footerView?.keyboardOcclusionHeight ?: 0 else -(footerView?.height ?: 0)
+
+  override val hasRelativeFooter: Boolean
+    get() = footerView != null && !absoluteFooter
+
+  override fun contentViewDidScroll() {
+    delegate?.containerViewContentDidScroll()
+  }
+
+  override fun contentViewScrollViewDidChange() {
+    delegate?.containerViewScrollViewDidChange()
+  }
+
+  override fun headerViewDidChangeSize(width: Int, height: Int) {
+    headerHeight = height
+    delegate?.containerViewHeaderDidChangeSize(width, height)
+  }
 
   override fun footerViewDidChangeSize(width: Int, height: Int) {
-    // Forward footer size changes to host view for repositioning
+    footerHeight = height
     delegate?.containerViewFooterDidChangeSize(width, height)
+    // A relative footer takes over the bottom inset — drop the scrollable's
+    contentView?.updateContentInset()
+  }
+
+  override fun peekViewDidChangeSize(width: Int, height: Int) {
+    delegate?.containerViewPeekDidChangeSize(width, height)
+  }
+
+  companion object {
+    const val TAG_NAME = "TrueSheet"
   }
 }

package/android/src/main/java/com/lodev09/truesheet/TrueSheetContainerViewManager.kt

@@ -1,8 +1,10 @@
 package com.lodev09.truesheet
 
 import com.facebook.react.module.annotations.ReactModule
+import com.facebook.react.uimanager.PointerEvents
 import com.facebook.react.uimanager.ThemedReactContext
 import com.facebook.react.uimanager.ViewGroupManager
+import com.facebook.react.uimanager.annotations.ReactProp
 
 /**
  * ViewManager for TrueSheetContainerView
@@ -15,6 +17,11 @@ class TrueSheetContainerViewManager : ViewGroupManager<TrueSheetContainerView>()
 
   override fun createViewInstance(reactContext: ThemedReactContext): TrueSheetContainerView = TrueSheetContainerView(reactContext)
 
+  @ReactProp(name = "pointerEvents")
+  fun setPointerEvents(view: TrueSheetContainerView, pointerEventsStr: String?) {
+    view.pointerEvents = PointerEvents.parsePointerEvents(pointerEventsStr)
+  }
+
   companion object {
     const val REACT_CLASS = "TrueSheetContainerView"
   }