@lodev09/react-native-true-sheet 4.0.0-beta.2 → 4.0.0-beta.21

package/src/TrueSheet.types.ts

@@ -1,4 +1,4 @@
-import type { ComponentType, ReactElement } from 'react';
+import type { Component, ComponentType, ReactElement, ReactNode, RefObject } from 'react';
 import type {
   ColorValue,
   NativeSyntheticEvent,
@@ -36,6 +36,7 @@ export type WillPresentEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
 export type DidPresentEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
 export type WillDismissEvent = NativeSyntheticEvent<null>;
 export type DidDismissEvent = NativeSyntheticEvent<null>;
+export type DismissAttemptEvent = NativeSyntheticEvent<null>;
 export type DragBeginEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
 export type DragChangeEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
 export type DragEndEvent = NativeSyntheticEvent<DetentInfoEventPayload>;
@@ -161,10 +162,44 @@ export interface AccessibilityOptions {
  */
 export type ScrollEdgeEffect = 'automatic' | 'hard' | 'soft' | 'hidden';
 
+/**
+ * What the sheet insets the bottom of a plugged scrollable's content for.
+ * See `ScrollableOptions.contentInsetAdjustment`.
+ */
+export type ContentInsetAdjustment = 'automatic' | 'safe-area' | 'footer' | 'never';
+
 /**
  * Options for scrollable behavior.
  */
 export interface ScrollableOptions {
+  /**
+   * What the sheet insets the bottom of the scroll content for, so the last
+   * item clears whatever covers the scroll view's bottom edge.
+   *
+   * - `'automatic'`: The bottom safe-area inset while the content can scroll
+   *   (home indicator on iOS, navigation bar on Android), plus the height of
+   *   an `absolute` footer floating over the scroll view. The footer then
+   *   counts toward the `auto` detent so the content ends above it.
+   * - `'safe-area'`: The safe-area inset only — content scrolls under an
+   *   absolute footer.
+   * - `'footer'`: The absolute footer only — you pad for the safe area.
+   * - `'never'`: No inset — you pad the content yourself.
+   *
+   * The safe-area inset only applies while the sheet's `insetAdjustment` is
+   * `'automatic'`; a relative footer absorbs it instead. The footer inset is
+   * independent of `insetAdjustment` — it only covers the part of the footer
+   * overlapping the scroll view, and stacks with the keyboard inset while the
+   * footer rises above the keyboard.
+   *
+   * On iOS, the safe-area inset sets the scroll view's native
+   * [`contentInsetAdjustmentBehavior`](https://developer.apple.com/documentation/uikit/uiscrollview/contentinsetadjustmentbehavior)
+   * to `automatic` while it's plugged into the sheet; Android and Web apply
+   * the inset themselves.
+   *
+   * @default 'automatic'
+   */
+  contentInsetAdjustment?: ContentInsetAdjustment;
+
   /**
    * Extra offset when scrolling to the focused input when keyboard appears.
    *
@@ -172,6 +207,18 @@ export interface ScrollableOptions {
    */
   keyboardScrollOffset?: number;
 
+  /**
+   * Adjusts the bottom inset applied to the scrollable when the keyboard is shown.
+   * Positive values increase the inset; negative values reduce it.
+   * Pass `-insets.bottom` to cancel out safe-area padding already included in
+   * the content's `paddingBottom`.
+   * Does not affect the auto scroll of the focused input — it always targets
+   * the keyboard edge.
+   *
+   * @default 0
+   */
+  keyboardOffset?: number;
+
   /**
    * Whether scrolling the content expands the sheet to the next detent.
    * When `false`, only the grabber can expand the sheet.
@@ -241,28 +288,19 @@ export interface FooterOptions {
    * @default 0
    */
   keyboardOffset?: number;
-}
 
-/**
- * Options for customizing the blur effect.
- * Only applies when `backgroundBlur` is set.
- *
- * @platform ios
- */
-export interface BlurOptions {
-  /**
-   * The intensity of the blur effect (0-100).
-   * Uses system default if not provided.
-   */
-  intensity?: number;
   /**
-   * Enables or disables user interaction on the blur view.
-   * Disabling this can help with visual artifacts (flash) on iOS 18+
-   * when touching the sheet content with blur enabled.
+   * Whether an `absolute` footer rises above the keyboard when it opens.
+   * Set to `false` to keep the footer pinned to the sheet's bottom edge behind the keyboard.
+   * With footer inset adjustment enabled, any uncovered portion still adds scroll padding
+   * and contributes to the expanded `auto` height.
+   * The pinned footer keeps its safe-area padding and ignores `keyboardOffset`.
+   * A `relative` footer never rises, so this has no effect.
    *
+   * @platform ios, android
    * @default true
    */
-  interaction?: boolean;
+  avoidKeyboard?: boolean;
 }
 
 /**
@@ -280,6 +318,20 @@ export type InsetAdjustment =
    */
   | 'never';
 
+/**
+ * How far the sheet must be swiped down from its lowest detent to dismiss.
+ */
+export type DismissThreshold =
+  /**
+   * Past half of the lowest detent, or a quick flick. Matches iOS.
+   */
+  | 'half'
+  /**
+   * A short drag (56 dp) or any downward fling (125 dp/s),
+   * like Compose Material3's `ModalBottomSheet`.
+   */
+  | 'short';
+
 /**
  * Blur style mapped to native values in IOS.
  *
@@ -308,6 +360,11 @@ export type BackgroundBlur =
   | 'system-thick-material-dark'
   | 'system-chrome-material-dark';
 
+export type DetentBackground =
+  | string
+  | { color: ColorValue; blur?: never }
+  | { blur: BackgroundBlur; color?: never };
+
 /**
  * Supported Sheet detent.
  */
@@ -397,6 +454,21 @@ export interface TrueSheetProps extends ViewProps {
    */
   initialDetentAnimated?: boolean;
 
+  /**
+   * Specify whether the sheet content should mount lazily, on first presentation.
+   * Set to `false` to mount the content before presentation without presenting the sheet.
+   * Use this when content is not ready on the first render, then call `present()`
+   * after your readiness signal so auto detents measure the settled content.
+   *
+   * Content that requires window attachment to measure, such as SwiftUI-hosted views,
+   * still only measures during presentation.
+   *
+   * @platform android
+   * @platform ios
+   * @default true
+   */
+  lazy?: boolean;
+
   /**
    * The detent index that the sheet should start to dim the background.
    * This is ignored if `dimmed` is set to `false`.
@@ -407,11 +479,22 @@ export interface TrueSheetProps extends ViewProps {
 
   /**
    * Prevents interactive dismissal of the Sheet.
+   * Blocked attempts fire `onDismissAttempt`, so you can confirm before dismissing programmatically.
    *
    * @default true
    */
   dismissible?: boolean;
 
+  /**
+   * How far the sheet must be swiped down from its lowest detent to dismiss.
+   * Set to `'short'` to dismiss on a short drag or fling, like Compose Material3's sheet.
+   *
+   * @platform android
+   * @platform web
+   * @default 'half'
+   */
+  dismissThreshold?: DismissThreshold;
+
   /**
    * Enables or disables dragging the sheet to resize it.
    * When disabled, the sheet becomes static and can only be resized programmatically.
@@ -423,9 +506,35 @@ export interface TrueSheetProps extends ViewProps {
   /**
    * Main sheet background color.
    * Uses system default when not provided.
+   *
+   * On supported iOS 26.1+ devices, uses a native color effect.
+   * `backgroundBlur` takes precedence on iOS.
+   * Use `backgroundStyle.backgroundColor` for an exact color or to tint glass or blur.
    */
   backgroundColor?: ColorValue;
 
+  /**
+   * Backgrounds matched to `detents` by index. Strings are color values.
+   * Null or missing entries inherit
+   * `backgroundColor`/`backgroundBlur`. iOS 26.1+ transitions natively.
+   * Other platforms cross-fade after passing the midpoint between detents.
+   * Blur entries use the sheet background on Android and Web.
+   */
+  detentBackgrounds?: (DetentBackground | null)[];
+
+  /**
+   * Custom background rendered behind the header, content, and footer.
+   * The wrapper fills the sheet and ignores touches.
+   * Size the element to fill it with `StyleSheet.absoluteFill`.
+   */
+  background?: ReactNode;
+
+  /**
+   * Style for the background wrapper. Only `backgroundColor` is supported.
+   * Use an opaque color for an exact color, or a translucent color to tint glass or blur.
+   */
+  backgroundStyle?: StyleProp<Pick<ViewStyle, 'backgroundColor'>>;
+
   /**
    * The sheet corner radius.
    *
@@ -471,20 +580,13 @@ export interface TrueSheetProps extends ViewProps {
 
   /**
    * The blur effect style on iOS.
-   * Blends with `backgroundColor` when provided.
+   * Takes precedence over `backgroundColor`.
+   * Use `backgroundStyle.backgroundColor` to tint the blur.
    *
    * @platform ios
    */
   backgroundBlur?: BackgroundBlur;
 
-  /**
-   * Options for customizing the blur effect.
-   * Only applies when `backgroundBlur` is set.
-   *
-   * @platform ios
-   */
-  blurOptions?: BlurOptions;
-
   /**
    * Overrides `large` or `100%` height.
    * Also sets the maximum height for 'auto' detents.
@@ -500,27 +602,31 @@ export interface TrueSheetProps extends ViewProps {
   maxContentWidth?: number;
 
   /**
-   * Anchors the sheet to the specified horizontal edge.
+   * Horizontal placement of the sheet within the screen.
+   *
+   * - `'automatic'`: The system decides (default). Centered on Android, Web, and iOS 26 and below.
+   * - `'center'`: Centers the sheet horizontally.
+   * - `'leading'`: Places the sheet on the leading edge (left in LTR, right in RTL).
+   * - `'trailing'`: Places the sheet on the trailing edge (right in LTR, left in RTL).
    *
-   * - `'center'`: Centers the sheet horizontally (default).
-   * - `'left'`: Anchors the sheet to the left edge.
-   * - `'right'`: Anchors the sheet to the right edge.
+   * `'automatic'` and `'center'` only differ on iOS 27+, where they map to
+   * `UISheetPresentationController.preferredPlacement`.
    *
    * Ignored on phones in portrait orientation.
    *
-   * @default 'center'
+   * @default 'automatic'
    */
-  anchor?: 'left' | 'center' | 'right';
+  placement?: 'automatic' | 'leading' | 'center' | 'trailing';
 
   /**
    * The offset from the screen edge.
-   * Only applies when `anchor` is `'left'` or `'right'`.
+   * Only applies when `placement` is `'leading'` or `'trailing'`.
    *
    * @platform android
    * @platform web
    * @default 16
    */
-  anchorOffset?: number;
+  placementOffset?: number;
 
   /**
    * Controls how the sheet adjusts its height for system insets (safe area).
@@ -568,8 +674,26 @@ export interface TrueSheetProps extends ViewProps {
    */
   footerStyle?: StyleProp<ViewStyle>;
 
+  /**
+   * A ref to the scrollable component (e.g. `ScrollView`, `FlatList`)
+   * rendered within the sheet content.
+   * Required for scrollable handling — nested scrolling, keyboard insets,
+   * and `auto` detent sizing are wired to this scrollable.
+   *
+   * Example:
+   * ```tsx
+   * const scrollableRef = useRef<ScrollView>(null)
+   *
+   * <TrueSheet scrollableRef={scrollableRef}>
+   *   <ScrollView ref={scrollableRef} />
+   * </TrueSheet>
+   * ```
+   */
+  scrollableRef?: RefObject<Component<unknown> | null>;
+
   /**
    * Options for scrollable behavior.
+   * Applies to the scrollable provided via `scrollableRef`.
    */
   scrollableOptions?: ScrollableOptions;
 
@@ -621,6 +745,13 @@ export interface TrueSheetProps extends ViewProps {
    */
   onDidDismiss?: (event: DidDismissEvent) => void;
 
+  /**
+   * Called when the user tries to dismiss the sheet while `dismissible` is `false`,
+   * e.g. by dragging down or pressing back/escape. Tapping the dim does not count.
+   * The sheet stays presented. Confirm with the user, then call `dismiss()` to proceed.
+   */
+  onDismissAttempt?: (event: DismissAttemptEvent) => void;
+
   /**
    * Called when the detent of the sheet has changed.
    * Either by dragging or programatically.