react-native-unified-action-sheet 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0]
+
+### Added
+
+- `presentationStyle: 'bottom'`: a native bottom sheet on both platforms, with
+  a drag handle and swipe to dismiss. A long list opens part-way and drags up
+  to expand. On iOS it is a `UISheetPresentationController` sheet with native
+  rows (on iPad, the action sheet's popover instead); on Android, a Material 3
+  bottom sheet. `anchor` is ignored for it.
+- Material is opt-in, so apps that don't use the bottom sheet stay free of the
+  dependency. Set `unifiedActionSheet.material=true` in
+  `android/gradle.properties`. Only then does the library add
+  `com.google.android.material` (1.12.0 by default; override it with
+  `ext.materialVersion` or `unifiedActionSheet.materialVersion`).
+- An Expo config plugin that writes those properties:
+  `plugins: [['react-native-unified-action-sheet', { material: true }]]`, with
+  an optional `materialVersion`. `@expo/config-plugins` is an optional peer
+  dependency.
+
+### Fixed
+
+- On iOS, a sheet, alert or prompt stayed on screen after a JS reload (pressing
+  `r` in Metro). It now closes on reload, as it already did on Android, and its
+  promise is left unresolved, since it belonged to the discarded runtime.
+
+### Notes
+
+- Without the Material opt-in, `'bottom'` on Android falls back to the centered
+  dialog, and warns once in development.
+- Prompts do not support `'bottom'`; they stay centered on both platforms.
+
 ## [0.2.0]
 
 ### Added
@@ -75,7 +106,8 @@ Initial release.
 - No `com.google.android.material` dependency, and no runtime dependencies —
   `react` and `react-native` are peers.
 
-[unreleased]: https://github.com/galikvalkin/react-native-unified-action-sheet/compare/v0.2.0...HEAD
+[unreleased]: https://github.com/galikvalkin/react-native-unified-action-sheet/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/galikvalkin/react-native-unified-action-sheet/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/galikvalkin/react-native-unified-action-sheet/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/galikvalkin/react-native-unified-action-sheet/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/galikvalkin/react-native-unified-action-sheet/releases/tag/v0.1.0

package/README.md

@@ -1,22 +1,16 @@
 # react-native-unified-action-sheet
 
-Unified action sheet API for React Native: a native `UIAlertController` on iOS, a native `AppCompatDialog` on Android.
+Unified native action sheet for React Native, one API on iOS and Android.
 
-| Android | Android (dark mode) | iOS |
+| | Light | Dark |
 | :---: | :---: | :---: |
-| <img src="https://raw.githubusercontent.com/galikvalkin/react-native-unified-action-sheet/HEAD/docs/android-demo.gif" width="280" alt="Android demo" /> | <img src="https://raw.githubusercontent.com/galikvalkin/react-native-unified-action-sheet/HEAD/docs/android-demo-dark-mode.gif" width="280" alt="Android dark-mode demo — following the system dark theme" /> | <img src="https://raw.githubusercontent.com/galikvalkin/react-native-unified-action-sheet/HEAD/docs/ios-demo.gif" width="280" alt="iOS demo" /> |
+| **Android** | <img src="https://raw.githubusercontent.com/galikvalkin/react-native-unified-action-sheet/HEAD/docs/images/android-demo-light-mode.gif" width="280" alt="Android demo in light mode" /> | <img src="https://raw.githubusercontent.com/galikvalkin/react-native-unified-action-sheet/HEAD/docs/images/android-demo-dark-mode.gif" width="280" alt="Android demo in dark mode" /> |
+| **iOS** | <img src="https://raw.githubusercontent.com/galikvalkin/react-native-unified-action-sheet/HEAD/docs/images/ios-demo-light-mode.gif" width="280" alt="iOS demo in light mode" /> | <img src="https://raw.githubusercontent.com/galikvalkin/react-native-unified-action-sheet/HEAD/docs/images/ios-demo-dark-mode.gif" width="280" alt="iOS demo in dark mode" /> |
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/galikvalkin/react-native-unified-action-sheet/HEAD/docs/ipad-demo.gif" width="420" alt="iPad demo — the sheet as a popover anchored to the button that opened it" />
-  <br />
-  <em>iPad: the same sheet presented as a popover, anchored to the view that opened it.</em>
-</p>
-
-- **Fully native, always on top.** The sheet gets its own platform window, so it renders above your whole view tree — including an already-open [`Modal`](https://reactnative.dev/docs/modal). JS-rendered sheets live *inside* the component tree, where `overflow`, `zIndex`, a transform or an open modal can clip or bury them.
-- **One API, native on both platforms**, so the same options behave the same way.
-- **Prompts included.** React Native's `Alert.prompt` is iOS-only and silently does nothing on Android; `showPromptWithOptions()` works on both.
-- Works on React Native **0.81 (old and new architecture)** through the **latest** release.
-- **No extra native dependencies** on either platform, and zero runtime dependencies (`react` / `react-native` peers only).
+- **Fully native, always on top.** The sheet gets its own platform window, so it renders above your whole view tree, including an open [`Modal`](https://reactnative.dev/docs/modal). JS-rendered sheets live inside the component tree, where `overflow`, `zIndex` or a modal can clip or bury them.
+- **One API on both platforms**: action sheets, anchored popovers, bottom sheets and text prompts.
+- **Prompts on Android too.** React Native's `Alert.prompt` is iOS-only; `showPromptWithOptions()` works on both.
+- **No dependencies.** `react` and `react-native` are peers; the Android bottom sheet's Material is opt-in.
 
 ## Installation
 
@@ -26,7 +20,9 @@ npm install react-native-unified-action-sheet
 yarn add react-native-unified-action-sheet
 ```
 
-Autolinking handles the rest on both platforms. In Expo apps, use a development build (`npx expo run:ios` / `npx expo run:android`) — custom native modules do not work in **Expo Go**.
+Autolinking handles the rest. In Expo, use a development build (`npx expo run:ios` / `npx expo run:android`); custom native modules do not work in Expo Go.
+
+**Optional:** for the Android bottom sheet, set `unifiedActionSheet.material=true` in `android/gradle.properties`, or add the Expo plugin. See [Bottom sheets](docs/bottom-sheet.md).
 
 ## Usage
 
@@ -45,41 +41,19 @@ await showActionSheetWithOptions({
 });
 ```
 
-`style` marks the two native roles, which are mutually exclusive; `disabled` is independent of it. `onPress` runs when that button resolves the sheet, and the call also resolves with the tapped index — the two never disagree:
-
-| | promise resolves with | `onPress` runs |
-| --- | --- | --- |
-| Tapping a button | its index | that button's |
-| Backdrop tap, back button, swipe down | the `'cancel'` button's index, or `-1` if there is none | the cancel button's, if there is one |
-| `dismissActionSheet()` | `undefined` | nothing |
-
-The promise never rejects on its own — only if one of your own `onPress` handlers throws.
-
-### Anchored sheets
+The call resolves with the tapped button's index, and that button's `onPress` runs. A backdrop tap or back resolves the `'cancel'` button. The promise never rejects. See [Behavior](docs/behavior.md).
 
-`presentationStyle: 'anchored'` attaches the sheet to a view. Pass the ref itself; the library measures it and sends only the resulting rectangle across:
+### Presentation styles
 
-```tsx
-const anchorRef = useRef<View>(null);
-
-<Pressable
-  ref={anchorRef}
-  onPress={() =>
-    showActionSheetWithOptions({
-      options: [...],
-      presentationStyle: 'anchored',
-      anchor: anchorRef,
-    })
-  }
-/>;
-```
-
-Anything with a `measureInWindow` method works, which is every React Native host component ref. On iOS the anchor only applies on iPad, where the sheet becomes a popover; iPhone always presents from the bottom.
+| `presentationStyle` | iOS | Android |
+| --- | --- | --- |
+| unset | Action sheet from the bottom | Centered dialog |
+| `'centered'` | Centered alert | Centered dialog |
+| `'anchored'` | Popover on iPad, pointing at `anchor` | Popup attached to `anchor` |
+| `'bottom'` | Sheet with a grabber (popover on iPad) | Material bottom sheet ([opt-in](docs/bottom-sheet.md)) |
 
 ### Prompts
 
-`showPromptWithOptions()` is the same dialog with a text field:
-
 ```ts
 import { showPromptWithOptions } from 'react-native-unified-action-sheet';
 
@@ -95,78 +69,16 @@ const result = await showPromptWithOptions({
 // { buttonIndex, text }, or undefined after dismissActionSheet().
 ```
 
-Buttons behave as they do for the sheet, except `onPress` receives the field's
-text. That text is whatever was in the field when the prompt closed, including
-on a dismissal, so a draft is recoverable. Extra options: `placeholder`,
-`defaultValue`, `secureTextEntry` and `keyboardType` (`'default' |
-'email-address' | 'numeric' | 'phone-pad' | 'url'`).
-
-A prompt is always centered — UIKit has no text field in an action sheet, so
-`presentationStyle` and `anchor` do not apply.
-
 ### Dismissing from code
 
-`dismissActionSheet()` closes the most recently opened sheet, `dismissAllActionSheets()` closes every open one. Both are no-ops when nothing is open, and the dismissed sheets resolve with `undefined`.
-
-```ts
-import {
-  dismissActionSheet,
-  dismissAllActionSheets,
-} from 'react-native-unified-action-sheet';
-```
-
-### Options
-
-| Option | Type | iOS | Android | Description |
-| --- | --- | :---: | :---: | --- |
-| `options` | `ActionSheetButtonInterface[]` | ✅ | ✅ | The buttons, in order: `{ label, style?, disabled?, onPress? }`. |
-| `style` (per button) | `'cancel' \| 'destructive'?` | ✅ | ✅ | `'cancel'` renders a separated row and resolves on backdrop tap / back; `'destructive'` uses the destructive color. Only the first `'cancel'` counts. |
-| `disabled` (per button) | `boolean?` | ✅ | ✅ | Renders the row dimmed and unresponsive to taps. |
-| `onPress` (per button) | `() => void?` | ✅ | ✅ | Runs when this button resolves the sheet. |
-| `title` | `string?` | ✅ | ✅ | Sheet title. |
-| `message` | `string?` | ✅ | ✅ | Secondary text under the title. |
-| `presentationStyle` | `'centered' \| 'anchored'` | ✅ | ✅ | `'centered'` is a centered dialog; `'anchored'` attaches to `anchor` (an iPad popover on iOS). **Defaults differ**: Android `'centered'`, iOS the standard action sheet. |
-| `anchor` | `ActionSheetAnchorInterface?` | ✅ | ✅ | A ref, or anything with `measureInWindow`. Without a measurable anchor an `'anchored'` sheet falls back to a centered dialog. |
-| `anchorAlignment` | `'start' \| 'center'` | — | ✅ | Alignment of an `'anchored'` popup relative to its anchor. `'start'` (default) aligns leading edges, flipping in RTL. |
-| `userInterfaceStyle` | `'light' \| 'dark'` | ✅ | ✅ | Forces the appearance; defaults to following the system setting. |
-| `tintColor` | `string?` | ✅ | ✅ | Text color of non-destructive buttons. |
-| `cancelButtonTintColor` | `string?` | ✅ | ✅ | Text color of the cancel button; overrides `tintColor` for that row. |
-| `destructiveColor` | `string?` | ✅ | ✅ | Overrides the destructive row color (Android's palette error color, iOS system red). |
-| `buttonTextAlignment` | `'start' \| 'center'` | — | ✅ | Alignment of button labels. Defaults to `'start'`, which follows layout direction. |
-
-Every options and button type is exported for typing your own wrappers —
-`ActionSheetOptionsInterface`, `PromptOptionsInterface`, `PromptResultInterface`
-and the interfaces they are composed from.
-
-### Platform notes
-
-- **Which gestures dismiss differs.** On iOS a sheet can only be tapped away if it has a `'cancel'` button, and a `'centered'` one never can — UIKit treats it as strictly modal. Android's centered dialog always cancels on a backdrop tap. Give a sheet a cancel button if you want that gesture everywhere.
-- **On iPad, a popover hides the cancel row**, since tapping outside already cancels. The index you receive is unaffected.
-- **Sheets stack.** Opening one over another puts it on top, and each resolves its own promise. Opening a sheet over a `Modal` does not dismiss the modal.
-- **Light or dark follows the system setting** unless `userInterfaceStyle` forces one, chosen when the sheet opens. It uses its own palette, so it looks the same in any host app.
-
-## Testing
-
-The package ships a Jest mock, so a screen that opens a sheet can be tested without the native module:
+`dismissActionSheet()` closes the most recently opened sheet, and `dismissAllActionSheets()` closes every open one. Dismissed sheets resolve with `undefined`.
 
-```ts
-jest.mock('react-native-unified-action-sheet', () =>
-  require('react-native-unified-action-sheet/jest')
-);
-```
-
-Every sheet then resolves with no selection. To simulate a tap, queue the index it should resolve with — the pressed button's `onPress` runs as it would for real:
-
-```ts
-import { setNextButtonIndex } from 'react-native-unified-action-sheet/jest';
-
-setNextButtonIndex(0);
-await openTheSheet();
-```
+## Documentation
 
-`setNextPromptResult({ buttonIndex, text })` does the same for a prompt. Prefer
-these over `mockResolvedValueOnce`, which replaces the implementation and so
-skips `onPress`. `dismissActionSheet` and `dismissAllActionSheets` are spies.
+- [API reference](docs/api.md): every option, per platform
+- [Behavior](docs/behavior.md): what each gesture resolves with, and platform differences
+- [Bottom sheets](docs/bottom-sheet.md): both platforms, and enabling Material on Android
+- [Testing](docs/testing.md): the shipped Jest mock
 
 ## Compatibility
 

package/android/build.gradle

@@ -2,7 +2,8 @@ buildscript {
   ext.UnifiedActionSheet = [
     kotlinVersion: "2.0.21",
     minSdkVersion: 24,
-    compileSdkVersion: 36
+    compileSdkVersion: 36,
+    materialVersion: "1.12.0"
   ]
 
   ext.getExtOrDefault = { prop ->
@@ -31,6 +32,20 @@ apply plugin: "kotlin-android"
 
 apply plugin: "com.facebook.react"
 
+// Material is opt-in, so apps that don't use presentationStyle 'bottom' stay
+// free of the dependency. The app sets unifiedActionSheet.material=true in its
+// gradle.properties (the Expo config plugin writes it); only then is the
+// Material presenter compiled and the dependency added. src/main never
+// references a Material class: it goes through BottomSheetPresenterFactory,
+// which both variant source sets define.
+def materialEnabled = (findProperty("unifiedActionSheet.material") ?: "false").toString().toBoolean()
+
+// ext.materialVersion on the root project wins, then the gradle property, then
+// the version this library is tested against.
+def materialVersion = rootProject.ext.has("materialVersion")
+  ? rootProject.ext.get("materialVersion")
+  : (findProperty("unifiedActionSheet.materialVersion") ?: UnifiedActionSheet.materialVersion)
+
 android {
   namespace "com.unifiedactionsheet"
 
@@ -40,6 +55,15 @@ android {
     minSdkVersion getExtOrDefault("minSdkVersion")
   }
 
+  sourceSets {
+    main {
+      java.srcDirs += materialEnabled ? "src/material/java" : "src/noMaterial/java"
+      if (materialEnabled) {
+        res.srcDirs += "src/material/res"
+      }
+    }
+  }
+
   compileOptions {
     sourceCompatibility JavaVersion.VERSION_17
     targetCompatibility JavaVersion.VERSION_17
@@ -48,4 +72,7 @@ android {
 
 dependencies {
   implementation "com.facebook.react:react-android"
+  if (materialEnabled) {
+    implementation "com.google.android.material:material:${materialVersion}"
+  }
 }

package/android/src/main/java/com/unifiedactionsheet/ActionSheetOptions.kt

@@ -6,11 +6,15 @@ import com.facebook.react.bridge.ReadableMap
 internal enum class PresentationStyle {
   CENTERED,
   ANCHORED,
+  BOTTOM,
   ;
 
   companion object {
-    fun fromWire(value: String?): PresentationStyle =
-      if (value == "anchored") ANCHORED else CENTERED
+    fun fromWire(value: String?): PresentationStyle = when (value) {
+      "anchored" -> ANCHORED
+      "bottom" -> BOTTOM
+      else -> CENTERED
+    }
   }
 }
 

package/android/src/main/java/com/unifiedactionsheet/UnifiedActionSheetModule.kt

@@ -51,6 +51,9 @@ class UnifiedActionSheetModule(reactContext: ReactApplicationContext) :
     }
   }
 
+  override fun getTypedExportedConstants(): MutableMap<String, Any> =
+    mutableMapOf("isMaterialEnabled" to BottomSheetPresenterFactory.isAvailable)
+
   override fun dismissActionSheet() {
     UiThreadUtil.runOnUiThread {
       openDialogs.lastOrNull()?.let { dialog ->
@@ -111,6 +114,9 @@ class UnifiedActionSheetModule(reactContext: ReactApplicationContext) :
           CenteredDialogPresenter
         }
       }
+      // Without Material compiled in there is no bottom sheet; JS has already
+      // warned in development, from the isMaterialEnabled constant.
+      PresentationStyle.BOTTOM -> BottomSheetPresenterFactory.create() ?: CenteredDialogPresenter
     }
 
     val dialog = presenter.build(activity, options) { presented, index ->

package/android/src/material/java/com/unifiedactionsheet/BottomSheetPresenterFactory.kt

@@ -0,0 +1,10 @@
+package com.unifiedactionsheet
+
+/// Compiled only when the app sets unifiedActionSheet.material=true, which also
+/// adds the Material dependency. The noMaterial source set defines the same
+/// object, so src/main compiles against either.
+internal object BottomSheetPresenterFactory {
+  const val isAvailable = true
+
+  fun create(): SheetPresenter? = MaterialBottomSheetPresenter
+}

package/android/src/material/java/com/unifiedactionsheet/MaterialBottomSheetPresenter.kt

@@ -0,0 +1,90 @@
+package com.unifiedactionsheet
+
+import android.app.Activity
+import android.app.Dialog
+import android.content.res.ColorStateList
+import android.view.View
+import android.widget.LinearLayout
+import androidx.core.view.ViewCompat
+import androidx.core.view.WindowCompat
+import androidx.core.view.WindowInsetsCompat
+import com.google.android.material.bottomsheet.BottomSheetDialog
+import com.google.android.material.bottomsheet.BottomSheetDragHandleView
+import com.google.android.material.R as MaterialR
+
+/// presentationStyle 'bottom': a Material 3 modal bottom sheet. Material's own
+/// behavior does the rest: a long list opens at the peek height and drags up to
+/// expand, a short one opens fully, and swiping it away cancels the dialog, so
+/// it resolves through the same cancel path as a backdrop tap.
+internal object MaterialBottomSheetPresenter : SheetPresenter {
+  override fun build(
+    activity: Activity,
+    options: ActionSheetOptions,
+    onSelect: (Dialog, Int) -> Unit,
+  ): Dialog {
+    val isDark = isDarkAppearance(activity, options.userInterfaceStyle)
+    val palette = paletteFor(isDark)
+    // A full Material 3 theme rather than an overlay, so the sheet works inside
+    // an app whose own theme is plain AppCompat.
+    val dialog = BottomSheetDialog(activity, bottomSheetTheme(isDark))
+
+    val context = dialog.context
+    // The cancel row stays the last row, as on the centered dialog. With a long
+    // list it starts below the peek height, which Material users expect:
+    // swipe down, back and a backdrop tap all resolve the cancel index anyway.
+    val content = buildContent(context, options, palette) { index -> onSelect(dialog, index) }
+
+    val root = LinearLayout(context).apply {
+      orientation = LinearLayout.VERTICAL
+      addView(
+        BottomSheetDragHandleView(context),
+        LinearLayout.LayoutParams(
+          LinearLayout.LayoutParams.MATCH_PARENT,
+          LinearLayout.LayoutParams.WRAP_CONTENT,
+        ),
+      )
+      addView(
+        content,
+        LinearLayout.LayoutParams(
+          LinearLayout.LayoutParams.MATCH_PARENT,
+          LinearLayout.LayoutParams.WRAP_CONTENT,
+        ),
+      )
+    }
+    dialog.setContentView(root)
+    dialog.setCanceledOnTouchOutside(true)
+
+    // Tint Material's own sheet background instead of replacing it, so its
+    // rounded top corners and expansion animation stay intact, while the color
+    // matches the palette the centered and anchored styles use.
+    dialog.findViewById<View>(MaterialR.id.design_bottom_sheet)?.let { sheet ->
+      ViewCompat.setBackgroundTintList(sheet, ColorStateList.valueOf(palette.surface))
+    }
+
+    // The sheet now sits behind the navigation bar, so its buttons or gesture
+    // handle need to contrast with the sheet, not with the app underneath.
+    dialog.window?.let { window ->
+      WindowCompat.getInsetsController(window, window.decorView)
+        .isAppearanceLightNavigationBars = !isDark
+    }
+
+    // Edge to edge is for the bottom only. It would also let a long list
+    // expand behind the status bar, so cap the sheet just below it (and any
+    // display cutout); the rows scroll inside it instead.
+    val decor = activity.window.decorView
+    val topInset = ViewCompat.getRootWindowInsets(decor)
+      ?.getInsets(WindowInsetsCompat.Type.systemBars() or WindowInsetsCompat.Type.displayCutout())
+      ?.top ?: 0
+    if (decor.height > topInset) {
+      dialog.behavior.maxHeight = decor.height - topInset
+    }
+
+    return dialog
+  }
+
+  private fun bottomSheetTheme(isDark: Boolean): Int = if (isDark) {
+    R.style.UnifiedActionSheet_BottomSheetDialog_Dark
+  } else {
+    R.style.UnifiedActionSheet_BottomSheetDialog_Light
+  }
+}

package/android/src/material/res/values/unified_action_sheet_bottom_sheet.xml

@@ -0,0 +1,22 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+  <!-- Full Material 3 themes, not overlays: Material components refuse to
+       inflate under a non-Material theme, and the host app's may be plain
+       AppCompat. userInterfaceStyle picks light or dark explicitly, so neither
+       follows DayNight.
+
+       Edge to edge, so the sheet runs down behind the navigation bar instead
+       of stopping above it and leaving a strip of scrim there. Material only
+       does this when enableEdgeToEdge is set and the navigation bar is
+       translucent; the sheet then pads its content by the bar's inset, so the
+       last row stays clear of it. -->
+  <style name="UnifiedActionSheet.BottomSheetDialog.Light" parent="Theme.Material3.Light.BottomSheetDialog">
+    <item name="enableEdgeToEdge">true</item>
+    <item name="android:navigationBarColor">@android:color/transparent</item>
+  </style>
+
+  <style name="UnifiedActionSheet.BottomSheetDialog.Dark" parent="Theme.Material3.Dark.BottomSheetDialog">
+    <item name="enableEdgeToEdge">true</item>
+    <item name="android:navigationBarColor">@android:color/transparent</item>
+  </style>
+</resources>

package/android/src/noMaterial/java/com/unifiedactionsheet/BottomSheetPresenterFactory.kt

@@ -0,0 +1,10 @@
+package com.unifiedactionsheet
+
+/// Compiled when the app has not set unifiedActionSheet.material=true. There is
+/// no bottom sheet without Material, so the module falls back to the centered
+/// dialog, and JS warns in development (see getTypedExportedConstants).
+internal object BottomSheetPresenterFactory {
+  const val isAvailable = false
+
+  fun create(): SheetPresenter? = null
+}

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require('./plugin/withUnifiedActionSheet');